ACP adapter #
The CLI presents ACP over stdio as newline JSON-RPC and translates each request
into a daemon operation. server.go owns the
connection; accepted work belongs to the daemon, so an adapter that exits leaves
its turns running. See sessions for the actor and stream it
observes.
Requests #
requestRoutes in 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 and
advertises loadSession plus the resume, list, close, and delete
session capabilities, and no prompt or MCP capabilities.
Session lifecycle #
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 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 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 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 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 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 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.
MCP overlays #
The editor can supply MCP servers as a session overlay.
acp.validate 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
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, 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 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 and
plugins.