ACP adapter #

albedo acp serves Agent Client Protocol v1 over stdio. The Go adapter translates requests into daemon HTTP and SSE calls. The daemon owns execution, history, authorization, and MCP connections. OpenAPI defines the HTTP contract.

Connection and capabilities #

The adapter supports local daemons and workspaces. It connects lazily, never prompts or restarts an incompatible daemon, and requires capabilities.acp_attachment >= 3. Provider credentials come from normal albedo configuration. Missing setup returns provider_missing with instructions to run albedo login in a terminal.

initialize answers without contacting the daemon. Supported methods are session/new, session/list, session/load, session/resume, session/prompt, and session/cancel. Output uses session/update. Prompts accept text and resource links. Images, embedded resources, editor filesystem and terminal callbacks, and HTTP MCP servers are unsupported. File tools use saved disk contents.

Stdout contains newline-delimited JSON-RPC only; diagnostics use stderr. Reading, observation, and writing run independently. The writer bounds pending output to 4 MiB. Overflow or write failure disconnects the adapter without cancelling daemon work.

Ownership and recovery #

session/new requires an absolute cwd and an mcpServers list. Creation establishes the durable ACP marker, attachment, and MCP configuration before runtime preparation. Retries retain their operation identity and compare configuration fingerprints without persisting credentials.

Each session has one writer attachment, authorized by Albedo-Attachment-Token, separate from daemon authentication. The daemon retains only its digest. Leases renew every five seconds and expire after twenty. Competing attachments are refused. Other clients may inspect, stop, rename, change preferences, and delete ACP sessions, but cannot submit input or change execution.

Disconnect or lease expiry releases ownership without cancelling accepted work or removing MCP state. Sessions remain visible as attached or detached. Daemon restart clears attachments and MCP credentials. Interrupted ACP prompts are not re-executed.

A stream gap or incompatible durable replacement fails observation and requires resume. Observation failure never cancels execution. After updating albedo, reconnect the editor's agent process as well as restarting the daemon; an existing process continues running its old binary.

Models and history #

session/list discovers ACP sessions without acquiring ownership. It supports an exact cwd filter and opaque pagination. Load and resume require full session IDs, matching workspaces, and the intended MCP configuration. Competing writers cannot attach.

Load replays durable user messages, replies, thoughts, and tools in order, then delivers buffered live activity. It excludes internal provider records and system input. Replay failure returns an error and releases the attachment. Resume delivers future activity without replay. Resuming running work permits cancellation but blocks new prompts until it ends.

Prompts and output #

Whole-prompt validation precedes admission and preserves block order. Local file links retain their URI and decoded path; other schemes remain references without fetching. Descriptions reach model context, and negative resource sizes are rejected. Opaque metadata affects retry identity but is not stored or shown to the model.

Each ACP prompt runs as its own turn; mail and scheduled input cannot merge into it. One successor may wait once cancellation begins or the prior response is queued. Cancellation before admission is retained until admission is known. Queued cancellation uses its receipt; running cancellation waits for confirmed completion. If completion wins the race, its actual outcome is returned. All updates precede the final response.

Live and durable output reconcile by identity and streamed-prefix hashes, never text equality. Provider-only records cannot claim visible text. Reconciliation state is bounded and cleared at turn completion. An unprovable replacement requires resume because ACP cannot retract delivered chunks.

Tool identities and outcomes survive live delivery and replay. Displayed results include recorded arguments, failures, locations, and genuine before/after diffs. Missing snapshots produce explanatory text; unified diffs never reconstruct full files. Snapshots are bounded to 128 KiB per file and 256 KiB per trace. Tool display is limited to 256 KiB of encoded JSON, with explicit truncation; durable history is unchanged.

MCP overlays #

The default-enabled editor-mcp extension exposes editor-supplied stdio servers separately from configured MCP servers. See editor MCP tools for selection and Python-binding behavior.

Commands run directly, without a shell, in the session workspace. Literal environment values pass through the secrets path. Duplicate names and collisions with configured servers are rejected. Configuration, credentials, and catalogues stay in daemon memory across disconnects and disappear on restart.

Servers must initialize and finish discovery before publication. Preparation failure returns 409 mcp_overlay_failed without changing the previous overlay. After confirmed publication, reload failure returns 503 overlay_installed_reload_failed and keeps the replacement installed. An unanswered publication returns 503 overlay_update_uncertain; installation may still complete. An identical reattach reconciles or retries reload. Active turns accept only identical overlays.

With editor MCP enabled, publication awaiting reload blocks execution; new prompts are refused before admission. Daemon or attachment-owner restart requires reattachment even for an empty overlay. Disabling editor MCP removes that execution dependency. Empty configuration removes only the editor overlay.

Implementation #

cli/internal/acp owns framing, session state, replay, and output. cli/internal/app owns workflows; cli/internal/daemon owns HTTP calls. The pinned ACP schema is under cli/internal/acp/testdata.

On the daemon, acp_attachments.gleam owns leases and memory-only overlays, acp_session.gleam owns publication and readiness, and http_acp.gleam owns routes. Session actors serialize admission, model selection, publication, and capture of durable and live boundaries.