Harness architecture

Harness architecture: a mental model

Harness is easiest to understand as a daemon that owns work and durable state, plus clients that act on and observe that work. A client is not the agent runtime: it sends named actions and renders the shared session.

Status: This page describes the current documented/runtime model. The source paths below are implementation-oriented docs in the Harness checkout. Ideas explicitly marked proposal are not current behavior.

The main pieces

• Kernel — machine-level home for connections, credentials, plugin installation/enablement, and defaults. It is not a conversation.
• Session — shared document for a conversation and its work. It holds a root agent, turns, transcript, and session-scoped state.
• Daemon — coordinates session work: it invokes the model through a connection, records emitted work, authorizes tool leaves, and executes permitted work.
• Client — TUI or another shell connected to the session. It submits user actions, displays transcript/work, and can answer approval requests.

The kernel and session are distinct scopes: kernel settings can seed a new session, but session work and state belong to that session. Several clients can operate on the same session document; they do not each own independent agent loops.

Follow the work

client action ──▶ daemon ──▶ session document
                    │             │
                    │             ├─ turn (sequence job)
                    │             │   ├─ completion / model response
                    │             │   └─ tool-call leaf (authorization + execution)
                    │             └─ transcript and session state
                    └─ connection, policy, and tool executors

A user prompt starts a turn. A model response may emit tool calls; the daemon records these as work in the session. A tool call is a leaf with its own authorization state. The daemon executes it only when policy permits; the resulting work and output become observable through the session. A turn is a sequence that can contain jobs, not the same thing as a single tool call.

This explains the division of responsibility: the client asks for an action or supplies a human decision; it does not mint the daemon’s job bodies. Transcript display and work execution are related, but a rendered line is not itself the execution mechanism.

Scope and extension points

Connections provide completion/model access and may expose other registered capabilities. The standard toolkit and built-in host surfaces provide tools; installed plugins contribute supported extension data such as commands and skills. A plugin is not automatically a new model driver or an arbitrary executor. See the tools guide for authorization and the plugin sources listed below for current plugin boundaries.

Concern	Current home
Kernel configuration and plugin reflection	Kernel directory; package installation plus config enablement
Conversation, turns, jobs, transcript	Session document
Model and tool work	Daemon orchestration
User input and presentation	Client shell
Human approval	Client action on the pending work leaf

Current behavior vs proposals

The description above is the current model documented by grain.md, runtime docs, and client docs. docs/canon/proposals.md documents the current PEW/Proposal mechanism (such as cancel and Question); the word “proposal” there is a product noun, not a draft-design status. Treat docs/working-proposals/ as design work unless adopted into current docs and code.

Source paths

Paths are relative to the Harness repository root:

• docs/canon/grain.md — kernel/session/document ownership and work geometry.
• docs/runtime/session-job.md — session, agent, turn, and job roles.
• docs/runtime/README.md — runtime documentation map.
• docs/client/README.md, docs/client/transcript.md — client duties and transcript/watch model.
• docs/plugins/install.md, docs/plugins/README.md — plugin install, enablement, and supported surfaces.
• packages/harness/package.json — TUI package entry point and dependencies.