Client API ownership
The Go daemon package adapts daemon protocol 4.
Application commands and TUI screens call named operations and receive typed
results. Generated code constructs routes and queries. The adapter checks
responses, bounds decoding, and chooses recovery policy. OpenAPI
defines the wire format. HTTP API behavior defines its
behavior.
On this page: Request flow, Code organization, Changes and recovery, Storage reports, Related guides, and Conditional configuration edits.
Request flow
Opening a context page follows this flow:
- The screen calls
GetContextSnapshotto obtain the latest prepared snapshot. - It calls
GetContextPagewith that snapshot ID, section, and page. - The adapter validates the response and returns a typed page or an error.
- A typed UI message carries the result to the screen, which owns selection, rendering, and rejection of outdated replies.
Reading context does not prepare a model request. If the snapshot changes, the client obtains the new summary before requesting its pages.
Code organization
Each domain keeps its operations and application-facing types together.
protocol/api.gen.go contains
wire types and HTTP request builders generated from OpenAPI with pinned
oapi-codegen. Conversion stays inside the adapter. The
API contribution guide
gives the generation command and required checks.
The generator runs in cli/tools/apigen, outside
the CLI dependency graph. It projects OpenAPI 3.2 to 3.1 in memory for the
generator, selects raw JSON for unions, and preserves nullable field tags for
adapter validation. The canonical spec remains authoritative. The adapter owns
bounded response reads, semantic validation, authentication recovery, and SSE
framing and replay. Session stream parsing is separate from chat operations.
Transport, decoding, and receipt recovery are private machinery.
Extension-specific result bodies remain explicit json.RawMessage values.
Local discovery and launching have separate responsibilities. API recovery cannot launch or replace a daemon. The interactive CLI still offers to keep or restart a running daemon. Replacement requires the user's choice. Daemon lifecycle describes startup and operator overrides.
Changes and recovery
connection.go owns connection
operations. session_stream.go and
session_events.go own session
delivery and decoding.
Typed patches preserve omitted fields, explicit removals, and false values. Configuration writes use the observed resource validator. A stale screen cannot silently overwrite a newer edit.
Reads can recover through rediscovery within the caller's deadline. Identified creation and input recovery retain the original ID and encoded intent. Other mutations do not automatically replay after a lost acknowledgement. Canceling a request does not cancel accepted input, interrupt a turn, or stop a shared daemon.
Session SSE uses an actor generation and sequence. The client saves both only after delivery succeeds. A reset replaces visible history and live progress. Older durable history remains available through paging. Collection SSE carries invalidations. Initial reset and overflow require authoritative refresh.
History entries retain their durable id and position. Clients merge repeated
entries by ID, including overlap between live delivery and older pages.
Identical text from different entries remains distinct. Empty assistant provider
records do not settle a streamed reply or consume its duplicate match.
turn_type distinguishes agent mail from user input. Optional mail metadata
supplies the mail ID, sender session ID, sender label, and kind. Clients use the
structured label, falling back to "Agent", rather than parsing display text.
The daemon owns bounded tool progress and argument parsing. Clients validate and render the normalized updates. Preview offsets count decoded Unicode scalar values. Full arguments, results, and recorded traces remain in durable history.
Storage reports
albedo storage reads the authenticated /storage resource through
GetStorageReport. The adapter traverses
report pages. The daemon inspects its own files and database. Online clients
need neither Python nor filesystem access.
Proven absence or a stale discovery record selects read-only local diagnosis.
Authentication, protocol, health, and transport failures remain errors.
--offline deliberately selects local diagnosis, which inspects a temporary
database and WAL copy without changing the installation. Unsupported required
schema columns fail rather than producing incomplete totals. Cleanup requires
the local ownership lock and rechecks approved candidates before deleting files.
Related guides
- Change the HTTP API: contribution rules and validation.
- API behavior: server ordering and recovery contracts.
- Terminal client: UI state and asynchronous replies.
- Web client: browser adaptation and local web server.
- Daemon lifecycle: discovery and process ownership.
Conditional configuration edits
Configuration reads and patches use /sessions/{id}/configuration. A patch
returns SessionConfigurationChange: the canonical resource and the desired and
loaded composition revisions. It does not encode history or reload the session.
Callers retain the validator they observed. A stale edit returns 412 and is not
silently retried against a newer validator. Callers with no prior observation
read configuration once before writing and consume the returned resource.
Generated Go patch fields distinguish omission, a value, and nullable removal.
Use SetPatch for nonnullable fields, SetNullablePatch for nullable values,
and ClearPatch only for nullable fields. A zero optional field is omitted.
Required fields are always serialized. The operation schema determines which
values are in bounds. Containing serializers preserve false, zero, empty
strings, and empty collections. Response types retain their ordinary
representation. TypeScript keeps its native undefined, null, and value
semantics.
NewCompaction, SubmitCompaction, and ReadCompaction retain immutable
action identity across uncertain delivery. The convenience compaction call polls
the receipt and returns an uncertain error carrying that handle if its wait
ends. See recovery workflows.
Previous extension api Next http workflows