# ACP adapter The CLI presents ACP over stdio as newline JSON-RPC and translates each request into a daemon operation. [`server.go`](../cli/internal/acp/server.go) owns the connection; accepted work belongs to the daemon, so an adapter that exits leaves its turns running. See [sessions](sessions.md) for the actor and stream it observes. ## Requests `requestRoutes` in [`server.go`](../cli/internal/acp/server.go) is the whole surface: `initialize`, `authenticate`, `session/list`, `session/new`, `session/resume`, `session/load`, `session/close`, `session/delete`, `session/set_config_option`, `session/prompt`, and the `session/cancel` notification. A route says whether the request runs on a worker and whether requests naming one session keep arrival order; other sessions stay free. An ordered request reserves its session's place on the reader before its worker starts, so two of them cannot overtake each other, and `session/close` and `session/delete` join that order so an in-flight resume cannot outlive them. The adapter pins ACP schema v1.32.0 in [`testdata`](../cli/internal/acp/testdata/acp-schema-v1.32.0.json) and advertises `loadSession` plus the `resume`, `list`, `close`, and `delete` session capabilities, and no prompt or MCP capabilities. ## Session lifecycle [`state.go`](../cli/internal/acp/state.go) holds one session's lifecycle as a value: an observation phase, one activity slot, one queued activity, and the daemon turn that work belongs to. Its transitions are pure and return effects, which [`session.go`](../cli/internal/acp/session.go) performs. Add a state to that value rather than a flag to `session`. `lost` is terminal: the adapter cannot prove which output the editor already saw, so it refuses further prompts and configuration until the editor resumes. A configuration write marks `preparing` for its duration. `session/load` replays history only after the event stream is accepted. A stream that fails before subscribing, or that never starts within 30 seconds, answers the request instead of leaving it open, and a session that ended up `lost` fails the load rather than replaying into an observation nobody can reconcile. `session/delete` detaches only once the daemon deleted the session, so a refusal leaves the editor's session usable. ## Configuration [`option.go`](../cli/internal/acp/option.go) models each selector once: its ACP id, name, category, choices, the value it writes, and what that value means locally, so the offered choices are also the validation rule. The selectors are `model`, `effort`, `contextWindow`, and `compactionStrategy`. `effort` offers `default` and the model's own levels, and a session with no saved level reads as `default`, so picking it changes nothing; `contextWindow` offers `0` ("Automatic") and a fixed ladder of 50k, 100k, 250k, 500k, 750k and 1M, clipped to the model's usable window. The catalogue's default and maximum are not separate choices, and a window saved outside ACP stays selectable. `compactionStrategy` offers `auto`, which clears the session's choice. Model levels come from the provider catalogue, a session's own values from its account, and an unreadable catalogue is reported on diagnostics instead of silently shortening a selector. [`app/acp.go`](../cli/internal/app/acp.go) owns the backend side. `ACPSettings` is one session's whole configuration, catalogue and selection together; `Catalog` lists what the connection offers before a session exists, `Refresh` adds one session's selection to a catalogue, and `Settings` is both; each write replaces the value wholesale, so no caller merges partial results. ## Output and reconciliation [`update.go`](../cli/internal/acp/update.go) defines every session update the adapter sends, keyed by one `updateKind`. The writer coalesces consecutive agent and thought chunks of one message up to 32 KiB and bounds its queue at 4 MiB. [`reconcile.go`](../cli/internal/acp/reconcile.go) keeps the bounded identity metadata that orders live output against durable replay; reaching its limit marks the session lost instead of dropping the excess. `usage_update` is sent only once the window is known, because ACP requires a non-null size. That window is the session's configured window or its compaction strategy's limit, not necessarily the model catalogue's. `used` is the latest call's prompt tokens, its total tokens, or the daemon's estimated request size, clamped to the window; cost is `USD`, or `credits` for a counted statement. A compaction becomes one `compaction_update`, `completed` with the summary or `failed` with the error, and only when the client advertised `clientCapabilities.session.compaction`. Its id combines the daemon generation and stream sequence, so a restarted actor does not reuse a boundary, while a replayed row uses its durable entry. Each attach advertises a `compact` command; a `/compact` prompt is not sent to the model, a command that arrives during a turn waits for it like a queued prompt, and the command's 195 s deadline outlasts the daemon's action so the daemon's verdict reaches the editor. ## Ownership and recovery [`acp_attachments.gleam`](../src/albedo/daemon/acp_attachments.gleam) owns writer attachments and overlays in a daemon-lifetime actor: a 20 second lease with a 5 second heartbeat, before test time scaling, neither surviving a daemon or actor restart. An ACP session takes input only from the connection holding its attachment, and only that holder may compact it; a client without a token gets `acp_owned`, a wrong token `attachment_lost`. The adapter sees `attachment_lost`, `overlay_reattach_required`, or `overlay_installed_reload_failed`. See [`acp_session.gleam`](../src/albedo/daemon/acp_session.gleam). ## MCP overlays The editor can supply MCP servers as a session overlay. [`acp.validate`](../src/albedo/daemon/acp.gleam) requires absolute command paths, unique server names, and unique environment variable names per server, and overlay names cannot shadow globally configured servers. [`http_acp.validate_and_probe_overlay`](../src/albedo/daemon/http_acp.gleam) reads the reserved names from the installed `McpServersPlugin` and starts candidates with the installed `EditorMcpPlugin`, both answering while disabled; without an `EditorMcpPlugin`, a non-empty overlay fails with `409 mcp_overlay_failed`. The daemon stores keyed fingerprints of server configuration while the live overlay belongs to the attachment actor, published at an idle boundary by [`acp_session.publish`](../src/albedo/daemon/acp_session.gleam), which restores the previous durable requirement when publication fails. A session requiring an absent overlay must reattach. Overlay contents and credentials are runtime configuration. [`acp_overlay.resolve`](../src/albedo/daemon/acp_overlay.gleam) is bound to `extension.Preparation.editor_overlay`; it reads the ACP marker first and returns `None` for a session without one, so ordinary turns do not load `acp_session`. See [MCP](mcp.md#editor-servers-over-acp) and [plugins](plugins.md#mcp-settings-and-editor-probes). ## Related pages - [All topics](README.md) - [Change guidance](contributing.md) - [Session attachment](sessions.md) - [MCP extension](mcp.md)