harness-multitool

Architecture

How the harness is built: its layers, one turn of the loop, its modes and plugins, its builds, and the repository layout. The same architecture is kept as a mind map in the project's journal.

Layers

flowchart TB
    subgraph Frontends["Frontends (IF-11)"]
        TUI["Terminal (ratatui)"]
        WEB["Browser (WebAssembly)"]
    end
    subgraph Core["Core — not pluggable"]
        LOOP["Agent loop (IF-0.1)"]
        BUS["Event bus (IF-0.2)"]
        REG["Registry (IF-0.3)"]
    end
    subgraph Plugins["Interfaces, each with default implementations"]
        PROV["Provider (IF-1)"]
        AUTH["Auth (IF-2)"]
        ROUT["Router (IF-3)"]
        TOOL["Tool (IF-4)"]
        POL["Policy (IF-5)"]
        HOOK["Hook (IF-6)"]
        MEM["Memory (IF-7)"]
        CTX["ContextStrategy (IF-8)"]
        SES["SessionStore (IF-9)"]
        VER["Verifier (IF-10)"]
        TRANS["Transport (IF-12)"]
        TRIG["Trigger (IF-13)"]
        SKILL["Skill (IF-14)"]
        COND["Condition (IF-15)"]
        HAND["CallbackHandler (IF-16)"]
    end
    DAEMON["Daemon: memory + the single callback entry, a URL per agent window"]
    subgraph Platform["Platform (IF-20..25)"]
        FS["Fs"] --- PROC["Process"] --- NET["Net"] --- CLK["Clock"] --- STO["Storage"] --- TERM["Terminal"]
    end
    Frontends <--> BUS
    LOOP <--> BUS
    REG --> LOOP
    LOOP --> ROUT --> PROV
    PROV --> AUTH
    LOOP --> POL --> TOOL
    LOOP --> CTX --> MEM
    LOOP --> VER --> MEM
    LOOP --> SES
    DAEMON --> TRIG
    TRANS --> TRIG
    TRIG -->|by type| HAND
    HAND -->|condition true, one message per batch| COND
    HAND -->|notification| LOOP
    HAND -->|skill| SKILL --> LOOP
    HAND -->|journal| MEM
    HAND -->|flowstate_update| MEM
    MEM --- DAEMON
    BUS --> HOOK
    BUS --> TRANS
    Plugins --> Platform

One turn of the loop

flowchart TD
    A([task]) --> B[ContextStrategy builds context<br/>from task, session log, memory]
    B --> C[Router picks provider and model]
    C --> D[Provider streams the turn]
    D --> E{tool calls?}
    E -- yes --> F{Policy}
    F -- allow --> G[Tool runs within its declared capabilities]
    F -- ask --> H[/user approves or denies/]
    H --> F
    F -- deny --> I[denial goes back to the model]
    G --> J[result appended to the session log]
    I --> J
    J --> B
    E -- no --> K[Verifier runs the task's protocol]
    K -- pass, evidence recorded --> L([done])
    K -- fail --> B

Every box is an event on the bus (IF-0.2) and an append to the session log (INV-5), which is what makes rewind and branching (IF-9) a fold over events rather than a feature bolted on.

Session modes

A session runs in a mode (IF-0.5); entering a mode fires a hook that adds the mode's instructions (IF-6). Each mode is a framework, not a prompt (P-10):

ModeWhat it addsStatus
normalthe loop abovespecified
step-debugone reference flowchart per pipeline, callbacks in the client code, a debug router in the client app by one contract (approve, step back where possible), env gate MULTITOOL_DEBUG_MODE=1 with auth, runs kept in .harness/debug (ADR 0013)accepted
reliability monitoringsignals accumulate in the daemon; a Condition wakes the agent with one message per batch; per-project response policies in .harness/policies; sessions open 24/7 (ADR 0014)concept
planonly harness tools, read operations and web search; the plan is journal entries, mind maps and flowcharts (ADR 0016)idea

Plugins and hot reload

Plugins are crates linked into the binary (CON-2). A reload rebuilds the local build and swaps the binary in the same terminal at a safe point; the new process replays each session's log, so sessions are not restarted (ADR 0015, CON-50).

Documentation mirror

A project's journal, mind maps and flowcharts are mirrored into its docs/ tree (CON-43): project-init creates the tree and .harness/ (CON-44); a PostToolUse hook on every memory write tells the agent which file to update; a built-in check linked by doc id reminds it once at Stop and runs as multitool docs check in CI (CON-45) (ADR 0017).

A local build

crates/cli/src/plugins.rs is where a local build lists its own callback handlers (IF-16); the daemon runs them.

Builds

A conversation and a task

A conversation lives in the daemon and can go on with any provider (conversations.md).

A message runs turns until the model stops. With a verification protocol that is a task: it reaches done only through the verifier (INV-4), and a stop or a failure ends it. Without one it is a conversation: the model's stop waits for the next message, the task stays running, and a stop or a provider failure can be followed by another message.

Debugging a feature

Each feature has its own way to be looked at without the rest of the system:

Repository layout

Built today:

The rest is the proposed layout:

crates/
  core/            agent loop, event bus, registry, task states
  doubles/  scenarios/  session/
  api/             one module per interface: traits, types, errors (semver, INV-8)
  platform-native/ platform-wasm/
  provider-anthropic/ provider-openai/
  auth-apikey/
  tools-builtin/   read, edit, shell, search, fetch
  policy-default/  context-default/  session-files/  verifier-protocol/  router-default/
  memory-daemon/   memory-browser/
  frontend-tui/    frontend-web/    tui-snapshot/
  transport-daemon/
  cli/             the binary: config, registry wiring, frontends
docs/

The architecture map

The high-level architecture is also kept as a mind map in the project's journal, shared with every session that works on the project, its nodes pointing at the decision and specification entries. This document and that map must agree; when they differ, that is a finding to settle.

This page's source