All docs
System
The Worker contract
Every harness session is the same Worker. Definitions, operations, a turn, identity and unattended running.
A Worker is a harness session that the system starts on a Client over ACP. The engine, the UI and the Router deal with it only through this contract. The Router, the authors and reviewers of workflow steps, called roles and the sessions you open directly are all Workers: they differ in the first message the engine gives them and in where their reports go, not in the contract.
The contract admits only capabilities that all five target harnesses (claude, codex, dsh, pi, antigravity) have and that were measured.
Harness definitions
Each harness has one definition. It is data, kept in harnesses.yaml in the official plugin. Neither the Daemon nor the engine branches on a harness name. Adding a harness means adding a definition, provided it fits this contract.
| Field | Meaning |
|---|---|
id |
Its name |
command |
The command line that starts the adapter process |
env |
Extra environment variables for the adapter process; may be empty |
mode |
Optional. After the session is created, the ACP configuration option of category mode is set to this value |
requires |
A note for people: what must be installed and logged in on the Client |
harnesses:
- id: claude
command: [npx, -y, --package=@agentclientprotocol/claude-agent-acp@0.108.0, --, claude-agent-acp]
mode: bypassPermissions
requires: Node; a logged-in Claude Code
- id: antigravity
command: [agy, acp, --stdio, --dangerously-skip-permissions]
requires: a logged-in agy
Which harnesses a Client can use depends on whether the first item of the command resolves on that machine. A failed start is reported as it is; no other harness is substituted.
Operations
| Operation | What it does |
|---|---|
| Create session | Start the adapter process from the definition, create the ACP session, then set mode, model and thinking in that order. A requested value that is not among the options the harness lists fails; it is never replaced by another |
| Send message | One turn: text and optional images. While the session is busy, messages queue in the Desk and are delivered in order when the turn ends |
| Cancel | The turn ends as "cancelled" and the session can be used again |
| Close | End the whole process tree of the adapter |
| Resume | When the adapter process is gone, the next message reconnects the same session: the context is still there, and so are the mode, model and thinking. If reconnecting fails the turn fails; a new session is never substituted |
Creating a session takes from a few seconds to more than ten, so the caller does not wait: the Desk records the session and answers with its id, messages sent meanwhile are queued, and they are delivered in order once it is ready.
A turn
A turn is caused by exactly one message sent by the Desk and lasts until the harness has answered. While it runs, the Daemon groups ACP updates into four kinds of event for the Desk: text chunks, thought chunks, tool calls and status. Only two things are guaranteed: order is preserved, and the text chunks joined together are the full reply of the turn. Character-by-character streaming and tool details are not guaranteed; the session page shows whatever the harness gives.
A turn ends in a result or a failure. After a failure the session is still usable: the next message resumes it. The engine moves only by the report block in the full reply and by the error text of a failure.
Some harnesses start a turn by themselves between two turns (a background command ends, a timer fires). That is outside the contract: a Worker does not rely on the harness to wake itself; waits are handled by the engine's wake-ups.
Prompts
The role description, the global prompt and the request all go into the first message of the session. ACP's systemPrompt is not used, because not every harness supports it.
Session identity and the tool surface
When the Daemon starts the adapter process it puts three identity variables into its environment, AIL_DESK_URL, AIL_SESSION_ID and AIL_SESSION_AUTH, and puts the directory of ail first on PATH. The agent types ail <subcommand> in its own shell tool, and the Desk recognises the session by its token.
That is the only form of tool the system gives an agent. Cross-device shell, pushing reports, worktrees and calling other roles are all ail subcommands; see the command line. aiL writes nothing into a harness's configuration and injects no MCP server: a native session that it did not start has none of these variables and sees no change at all.
Unattended running
Nobody watches a Worker. As the ACP client, the Daemon:
- approves every permission request;
- refuses every mid-turn question, so what a Worker needs to ask you goes into a report;
- offers no ACP file or terminal capability, so the harness reads and writes files and runs commands with its own tools.
The unattended settings each harness needs are in its definition (mode, start-up arguments).
How differences are handled
| Difference | How it is handled |
|---|---|
| Only some harnesses support a system prompt | It goes into the first message |
| Not every harness accepts session-level MCP | It is outside the contract; system tools are the ail command line |
| Some do not report usage | Usage is optional statistics and takes no part in scheduling |
| There is no common signal for an exhausted quota | A table of text rules recognises it, and a match is retried with back-off |
| Shell tools wait for different lengths of time, the shortest only 10 seconds | Every ail subcommand waits at most 8 seconds; unfinished work becomes a background operation |
| Built-in background and timer tools | Not used; the engine wakes the Worker |
| Model and thinking options differ per harness | Set by ACP category; a role binding uses the options each harness lists |
None of these needs a branch on the harness.