small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
7.2 kB · 131 lines
Markdown
at main

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.