Architecture

flowchart TB
    hosts["Hosts<br/>amber TUI · amber-cli · amber-bench"]

    subgraph kernel["libagent_core: microkernel"]
        runtime["PluginRuntime<br/>capability ledger"]
        registries["Contribution registries<br/>tools · providers · commands · status · panels"]
        agent["Agent loop + Context"]
        events["Typed EventBus"]
        transport["LLM transport<br/>openai protocol"]

        runtime -->|install / unwind| registries
        registries --> agent
        agent --> events
        agent --> transport
    end

    bundled["Bundled plugins: compiled in<br/>providers · core tools · status segments · panels"]
    external["External plugins<br/>separate process · JSON-RPC over stdio<br/>tools only"]
    endpoint["OpenAI-compatible endpoint"]

    bundled -->|declare Capability| runtime
    external -->|tool.call| registries
    transport --> endpoint
    hosts -->|AgentHooks| agent

flowchart TD
    run["Agent::run(prompt)"] --> seed["ensure_system_prompt<br/>history always starts with a system message"]
    seed --> loop{"iteration under max_tool_iterations<br/>and not done?"}
    loop -->|no| stop["hard stop<br/>loop detected, or tools kept failing"]
    loop -->|yes| gate{"compression gate<br/>context utilisation over threshold?"}
    gate -->|compress| rebuild["compression pipeline<br/>context rebuilt: clear + push"]
    gate -->|keep| assemble
    rebuild --> assemble["assemble the prompt copy<br/>head + tail blocks, after the gate"]
    assemble --> llm["LLM call, streamed via SSE"]
    llm --> parse["parse tool calls"]
    parse -->|none| confirm["silent confirm turn<br/>are you finished?"]
    confirm -->|done| reply["return the final reply"]
    confirm -->|continue| loop
    parse -->|calls| dispatch["dispatch tool calls<br/>parallel execution, ordered results"]
    dispatch --> push["push tool-role messages"]
    push --> loop

flowchart TD
    each["evaluated every iteration"] --> tool{"3 or more identical<br/>tool call sets in a row?"}
    tool -->|yes| stopTool["hard stop: loop detected"]
    tool -->|no| text{"identical reply text<br/>repeating?"}
    text -->|second time| steerText["inject a steering message"]
    text -->|fifth time| stopText["hard stop"]
    text -->|no| fail{"consecutive tool failures"}
    fail -->|3| steerFail["inject a recovery steer"]
    fail -->|6| stopFail["hard stop: tool calls kept failing"]
    steerText --> hist["steer pushed to history_<br/>the model sees it on the next turn"]
    steerFail --> hist
    hist --> each

flowchart TB
    subgraph ops["the only mutation operations"]
        push["push(msg): seal and append<br/>h = FNV(prev_hash, msg)"]
        pop["pop(): remove the top, LIFO<br/>restores the previous hash in O(1)"]
        clear["clear(): remove all<br/>used only by the compression rebuild"]
        get["get_all(): read-only view<br/>recomputes and asserts the chain"]
    end

    push --> chain["parallel deque of hashes"]
    pop --> chain
    clear --> chain
    chain --> verify["any in-place mutation breaks a link<br/>and asserts in a debug build"]
    get --> verify
    verify --> owner["single ownership, not locking<br/>one writer thread: everyone else reads snapshots"]

stateDiagram-v2
    [*] --> Registered
    Registered --> Active: enable - initialize + install
    Active --> Deactivated: disable - shutdown + unwind ledger
    Deactivated --> Active: enable
    Registered --> Failed: initialize returned false
    Active --> Failed: install failed
    Failed --> Registered: fix and reload
    Deactivated --> [*]

flowchart TB
    provider["provider plugin<br/>flavor + presets + optional dialect factory"] --> select["Config::flavor set at selection"]
    select --> make["make_dialect(flavor)<br/>resolved exactly once per client"]
    make -->|known flavor| dialect
    make -->|unknown flavor| fallback["openai fallback<br/>a typo never breaks a session"]
    fallback --> dialect["Dialect implementation<br/>endpoints · auth · body shape"]
    dialect --> request["build request body and headers"]
    request --> transport["HTTP transport via libcurl<br/>retry · timeout · cancel check"]
    transport --> endpoint["OpenAI-compatible endpoint"]
    endpoint --> decode["stream decoder: SSE framing"]
    decode --> chunks["StreamChunk per event → AgentHooks"]
    decode --> usage["TokenUsage mapping"]
    decode --> errors["is_retryable classification<br/>typed ApiError"]
    request --> normalize["tool calls normalized to the internal shape<br/>at the dialect edge, buffered and streamed alike"]

flowchart TD
    calls["tool calls from the LLM reply"] --> validate{"known tool,<br/>valid JSON arguments?"}
    validate -->|no| denied["denied<br/>tool not found / invalid JSON"]
    validate -->|yes| dup{"duplicate of an identical call<br/>in the last assistant turn?"}
    dup -->|yes| denied
    dup -->|no| policy{"PolicyStore level<br/>read / write / yolo"}
    policy -->|read mode blocks it| denied
    policy -->|needs approval| gate{"approval gate"}
    gate -->|denied| denied
    gate -->|allowed| exec
    policy -->|allowed| exec["execute in parallel via std::async"]
    exec --> collect["collect results"]
    collect --> ordered["append in original order<br/>exactly one tool-role message per call"]
    denied --> ordered
    ordered --> envelope["feedback envelope<br/>status ok / error / denied"]

flowchart TD
    query["search tool call<br/>mode argument"] --> pick{"mode"}
    pick -->|semantic| sem["SemanticBackend<br/>dependency-free lexical index<br/>cached per root and glob"]
    pick -->|anything else| grep["GrepBackend<br/>wraps grep -rnI, stateless"]
    sem --> fresh["a backend is created fresh per execute()"]
    grep --> fresh
    fresh --> format["results formatted into the tool envelope"]

sequenceDiagram
    autonumber
    participant U as User
    participant H as amber, the MCP host
    participant T as Transport
    participant S as MCP server

    U->>H: /mcp connect
    H->>T: open transport, stdio or streamable HTTP
    T->>S: spawn the process, or POST
    H->>S: initialize - protocol negotiation
    S-->>H: server capabilities
    H->>S: tools/list
    S-->>H: tools, paginated
    H->>S: resources/list, prompts/list
    S-->>H: resources, prompts
    Note over H,S: adapters map all three onto the Tool port
    S-->>H: notifications/listChanged
    U->>H: invoke a server tool
    H->>S: tools/call
    S-->>H: result
    U->>H: disconnect
    H->>S: shutdown

flowchart TB
    task["task tool call"] --> mode{"execution mode"}
    mode -->|serial| serial["one at a time<br/>sequential requests share the system-prompt prefix<br/>so provider prompt caches stay warm"]
    mode -->|parallel| parallel["concurrent, capped by max()"]
    serial --> build
    parallel --> build["each sub-agent gets its own Context<br/>and a custom system prompt"]
    build --> iters["max_iterations cap, default 20"]
    iters --> result["result returned to the parent agent"]

sequenceDiagram
    autonumber
    participant A as Agent
    participant C as Context (live)
    participant L as LLM

    A->>C: read the snapshot
    C-->>A: messages (Context stays untouched)
    A->>A: collapse consecutive tool-call loops

    Note over A,L: both requests share a content-identical prefix,<br/>so the second extends the first's KV cache

    A->>L: classify request
    L-->>A: classification json - core / context / prune
    A->>L: extract request, replaying the classify prefix
    L-->>A: extraction json - memories + skills

    A->>A: apply classification, enforce headroom
    A->>C: clear() then push() the compressed set
    Note over A,C: the rebuild is the only live-context change,<br/>and only on success; a failure leaves it untouched

flowchart TD
    call["tool call"] --> mode{"agent mode"}
    mode -->|read| block["read mode blocks<br/>every non-read-only tool"]
    mode -->|write or yolo| classify{"shell_classify<br/>bash only"}
    classify -->|read-only, or benign in-workspace write| run["runs free"]
    classify -->|destructive, or outside the workspace| policy
    classify -->|not a bash call| policy{"stored or session rule?"}
    policy -->|granted| run
    policy -->|no rule| handler{"approval handler installed?"}
    handler -->|no handler| deny["denied: fail-safe"]
    handler -->|non-TTY with no --yes| deny
    handler -->|TTY| dialog["approval dialog<br/>prompted once per scope: kind or folder"]
    dialog -->|approve| grant["session grant recorded"]
    grant --> run["tool executes<br/>own process group, stdin to /dev/null"]
    dialog -->|deny| deny
    block --> deny

flowchart TD
    input["path from the tool call"] --> empty{"empty?"}
    empty -->|yes| reject
    empty -->|no| root["resolve the root<br/>cached, then $AMBER_WORKSPACE, then cwd"]
    root --> normalize["lexical normalisation<br/>no filesystem access during resolution"]
    normalize --> escape{"escapes the root?<br/>dot-dot traversal or an absolute path outside"}
    escape -->|yes| reject["rejected"]
    escape -->|no| prefix{"slash-terminated prefix match<br/>/ws2 is not inside /ws"}
    prefix -->|no| reject
    prefix -->|yes| ok["confined absolute path returned"]
    ok --> io["only now does any file I/O happen"]

flowchart TB
    subgraph core["libagent_core.a: UI-free core"]
        engine["agent loop · context · dispatch<br/>plugin runtime · event bus · ledger"]
        dialects["LLM dialects + HTTP transport"]
        bundled["bundled plugins, compiled in<br/>providers · core tools · hello"]
    end

    subgraph toolslib["libagent_tools.a"]
        tools["read · write · search · bash<br/>process · task · todowrite · skills"]
    end

    toolslib -->|depends on core| core

    core --> cli["amber-cli<br/>headless"]
    core --> tui["amber<br/>ncurses TUI"]
    core --> bench["amber-bench<br/>KPI harness"]
    toolslib --> cli
    toolslib --> tui
    toolslib --> bench

    tui --> nclib["ncurses + md4c"]
    cli --> curl["libcurl"]
    tui --> curl
    bench --> curl

    ext["external plugins<br/>separate processes, JSON-RPC<br/>never linked into any client"] -.->|process boundary| core
    note["core and tools appear twice on every link line<br/>to resolve the circular reference between them"]