HTTP API behavior #
This guide describes ordering, retries, recovery, and caller obligations for daemon protocol 3. OpenAPI owns exact routes, methods, request fields, response fields, variants, and limits. Its document-format version is separate from the daemon protocol version.
API architecture owns implementation and persistence boundaries. Client API ownership describes the Go adapter. Follow Change the HTTP API when editing a contract or adding an operation.
Contract boundaries #
Resources group domain operations, rather than matching individual screens. JSON
reads and SSE watches use the same resource URL with different Accept headers.
Ordinary HTTP requests perform changes. SSE delivers updates.
An input ID identifies submitted intent across retries. A stream cursor identifies an actor lifetime and position. A transcript checkpoint identifies durable history. Those identities are not interchangeable.
The daemon owns execution, argument parsing, storage inspection, and bounded progress. Clients own navigation, drafts, rendering, and confirmations. Local discovery and process replacement remain application policy outside the API connection.
Bounds apply before subscriber mailboxes. Model execution does not wait for a client socket to drain. Session streams describe replay and overflow behavior.
Reading and changing the wire contract #
OpenAPI defines required, optional, and nullable fields. DynamicJSON marks
provider-private or extension-specific data inside typed envelopes. A client may
ignore unknown response fields, but it must validate required fields and known
variants.
An SSE event's data is a string containing JSON. Decode it before validating
the declared contentSchema. Validating the outer string does not validate its
contents. OpenAPI's byte-limit annotations also require runtime checks. JSON
Schema maxLength counts Unicode code points, not encoded bytes.
The contribution guide separates required validation work from the existing verification evidence.
Resource map #
This table is a navigation guide, not an exhaustive route or method inventory.
The paths section of OpenAPI defines supported operations,
including routes not shown here.
server.gleam dispatches core requests.
Extensions dispatch their own services.
| Resource family | Behavior in this guide |
|---|---|
/server, /server/shutdown |
Readiness and instance-targeted shutdown. |
/settings, /storage, /usage |
Shared settings and accounting. |
/sessions and /sessions/{session_id} |
Browsing, creation, configuration, deletion, and input. |
/sessions/{session_id}/shell-commands/{command_id} |
Human shell commands, stop, and output reads. |
/sessions/{session_id}/side-questions/{question_id} |
Side questions and cancellation. |
| Session history and active-output resources | Durable content and unfinished-output recovery. |
| Session context, catalog, reload, kernel, and compaction resources | Observation and runtime changes. |
/models, /workspaces, /hosts, and session file and checkout-change resources |
Models and workspace observations. |
/auth and its login and account resources |
Provider login. |
/extensions/{extension_name} |
Extension-owned operations. |
Session creation uses the SessionCreationRequest union in OpenAPI. History
kinds come from HistoryEntry, and published event variants come from
SessionEvent. This guide explains their semantics without maintaining parallel
enum lists.
Opening a chat #
- Use the supplied base URL and bearer token to read
/server. Check protocol and required capabilities before opening a screen. - Read
/sessionsfor the picker or family graph. Each row includes its metadata and bounded live state. - Read the selected session. Install its history, pending inputs, status, progress, and cursor together. Count a deliberate opening with one identified visit. Background reads do not count.
- Watch that same session URL as SSE, passing the installed cursor pair. Apply subsequent events, or replace the daemon-derived view on reset.
- Send a message with an identified input PUT. Keep its local handle until the returned decision or matching stream event resolves it. Cancellation targets that input identity.
- Fetch older history by durable position. Open context, catalog, or extension resources when the user needs them. Use the validator already displayed with a resource when editing it.
HTTP rules #
Addressing and authentication #
A client receives a base URL and daemon bearer token. Native local clients may read the protected discovery record. Other clients receive both values through explicit connection setup. No API method reads client installation files, launches a daemon, or replaces one.
Every platform request, including SSE, uses
Authorization: Bearer <daemon-token>. The token grants operator access to this
daemon. This protocol has no user accounts, tenant isolation, or session ACLs.
Provider OAuth accounts are model-provider credentials, not daemon identities.
Browser OPTIONS preflights are the exception to bearer presentation. They return
only allowed request metadata and cannot read or mutate resources.
The default listener remains loopback. Connections across an untrusted network require HTTPS or an encrypted tunnel. Tokens never appear in URLs, response bodies, diagnostic logs, or stream events.
Browser clients use fetch for JSON and SSE so they can send the authorization
header. Native EventSource does not expose arbitrary request headers.
The SSE specification
defines its constructor and stream format.
Browser access uses an operator-configured list of exact allowed origins. The
daemon validates Origin before routing or reading a body. Allowed preflights
advertise the supported method and headers, including Authorization,
Content-Type, If-Match, and If-None-Match. Responses vary by Origin and
expose ETag, Location, and Retry-After. There are no authentication
cookies or wildcard origins. Origin approval does not replace the bearer check.
This follows the
Fetch CORS protocol.
The daemon validates the requested host against its listener and configured public addresses. A supplied origin or host never grants additional permission. Optional extension intake routes declare their own authentication policy.
Encoding, limits, and pagination #
The SDK http_api.gleam owns the
response limit, strict JSON decoding, and paging tokens. The daemon
http_api.gleam owns request body
limits. http_coding.gleam owns
content-coding negotiation.
JSON uses UTF-8, snake_case field names, and tagged objects for variants. IDs
are opaque strings. Paths and query values use ordinary percent encoding. Core
timestamps are UTC RFC 3339 strings. Unknown historical timestamps are null.
Durations use explicitly named units. Counters and sequence numbers are integers
from zero through 2^53 - 1.
Unknown request fields, duplicate JSON keys, invalid enum values, malformed
query values, and unknown query parameters return 400 invalid_request.
Requests do not silently substitute defaults for invalid values. Unknown
response fields may be ignored. Missing required fields and invalid known
variants fail decoding.
PATCH uses application/merge-patch+json. Omission keeps a value, null
removes an override or optional value, and false remains a real value. Arrays
replace the complete array. Writable fields are listed for each resource.
JSON Merge Patch defines these
rules.
Ordinary JSON request bodies have a 64 KiB limit. Input admission has a 100,200,000-byte limit, room for ten encoded images and 20 MiB of decoded generic files. JSON responses and SSE data frames have a 1 MiB limit. The limits on each OpenAPI operation apply as well. HTTP body framing accepts valid fixed-length and chunked requests, enforcing the same byte limit while reading. Ambiguous framing, unsupported content encoding, and incomplete bodies fail without executing the operation.
zstd is the one content coding. A JSON or text response of at least 1 KiB is
compressed when Accept-Encoding admits zstd, and so is a session or
collection event stream, flushed after every frame. Limits and ETag values
describe the decoded representation, and these responses add
Vary: Accept-Encoding. Image resources are never coded. The daemon needs OTP
29, whose zstd can flush a stream between frames. Frames use a 64 KiB window
(windowLog 16 in albedo_http_api), not level 1's 512 KiB default: the window
is the memory a client's decoder must hold, and an event stream keeps one
decoder for the client's whole life. When GET /server lists the
zstd_requests capability, a request body may use Content-Encoding: zstd. It
must be one frame that declares its decoded size, which must fit the route's
limit. Anything else is 400. The CLI compresses bodies of 16 KiB or more.
Lists return { "items": [], "next": null }. next is an opaque continuation
token tied to the query and representation, including limit. Follow-up
requests retain the original query and add next. Default limit is 50.
Maximum is 200. Each page also respects its encoded byte limit, including JSON
escaping. Catalog entries, glances, input outcomes, and reset snapshots obey
that bound even when their item counts fit. Large content uses its documented
paging path. Summary text is shortened explicitly. A single catalog entry is at
most 64 KiB. Session glances include at most 16 entries of 8 KiB each. Tokens
never contain credentials and cannot authorize access. A token for another query
returns 400. Missing singleton resources return 404. An empty collection
returns 200.
Collection traversal uses a stable sort key and ID as its tie breaker. Sessions use most recent activity first. A traversal is not a frozen global snapshot: concurrent edits can move rows. Clients key rows by ID and refresh on invalidation. History traversals use immutable transcript positions and do not have this limitation.
Revisions and errors #
The SDK HTTP contract encodes problems and validators for the daemon and extension services. The domain owner checks the validator at its commit boundary.
An ETag validates the complete selected JSON representation. Configuration has
a separate representation from volatile session state. Session reads expose the
URL and validator for view=configuration. Settings reads expose the URL and
validator for each group. Editing those representations uses If-Match
without conflicting with unrelated progress or another settings group. Extension
item reads likewise expose the item's observed URL and validator.
PATCH and conditional DELETE require the observed If-Match. Missing
preconditions return 428. Stale ones return 412. Checks and the
corresponding commit occur under the owning resource's serialization or
transaction boundary. Validators are opaque. Clients never derive them from an
integer revision. Mutation envelopes carry new resource validators explicitly
and are not cached as canonical read representations.
Errors use application/problem+json, with type: "about:blank", title,
status, detail, and a stable Albedo code. An optional fields array
contains JSON pointers and safe explanations. Identified operation decisions can
add a typed decision field. Clients branch on status and code, never wording.
Raw request bodies, secrets, and provider responses do not appear in errors.
Problem Details defines the
common envelope.
| Status | Meaning |
|---|---|
| 200 | A read or synchronous operation returned its documented result |
| 201 | A resource was created. Location identifies it |
| 202 | Input is durably accepted, or an explicitly identified action is underway |
| 204 | A deletion or cancellation needs no response body |
| 400 | Invalid syntax, fields, query, or identity timestamp |
| 401 | Missing or invalid daemon token. Includes WWW-Authenticate: Bearer |
| 403 | Disallowed browser origin or caller permission |
| 404 | Unknown current resource or disabled extension route |
| 405 | Known path, unsupported method. Includes Allow |
| 406 | Unsupported response media type |
| 409 | Busy state, identity conflict, stale catalog, or incompatible operation |
| 410 | Retained deletion, expired identity, or obsolete prepared context |
| 412 | The observed representation or creation precondition no longer holds |
| 413 | Body exceeds its limit |
| 415 | Unsupported request media type |
| 428 | Required precondition is missing |
| 429 | Admission or rate limit. Includes Retry-After where a later new intent can succeed |
| 503 | Owner, storage, or upstream preparation is unavailable |
All authenticated data responses use Cache-Control: no-store. Clients may keep
in-memory resource state and validators. Errors after SSE headers use the stream
failure contract rather than pretending to change the HTTP status.
Retries and cancellation #
Reads can retry transient connection failures with capped backoff and jitter. They remain subject to the caller's deadline. Authentication and protocol errors are actionable failures, not evidence that a daemon is absent.
Session creation, input admission, visits, and login creation retain the original ID and encoded intent during recovery. Other changes have no automatic replay after a lost response. A precondition or a resource-specific identity can make an explicit retry safe. The session contract defines identified-operation recovery.
Canceling a client context stops its requests and subscriptions. It does not undo an accepted input, interrupt a shared turn, stop a detached daemon, or authorize replacing one. Those are separate operations. Transport cancellation after a mutation was sent can leave its outcome uncertain.
Server, settings, and storage #
Server identity and shutdown #
GET /server reports readiness, daemon instance identity, protocol,
capabilities, build information, and observations. instance_id changes at each
startup. Build labels and digests are update information, not proof of API
compatibility.
Capabilities map feature names to contract versions. Attachment checks the
required versions in daemon/server.go.
Optional operations check their advertised capability before invocation.
Daemon attachment explains the
connection boundary.
Quota readings retain their account, observation time, source, and safe failure details. An unknown percentage remains unknown. The optional history view is paged. See quota observations and the parameters on the OpenAPI operation.
Reading a notice does not dismiss it. Dismissal is a shared UI setting.
POST /server/shutdown accepts instance_id and timeout_ms, default 5,000
and maximum 30,000. A different instance returns 409 instance_changed. The
daemon marks itself draining, refuses new admissions, stops active turns,
flushes durable state, and closes. Accepted waiting inputs remain durable for
the replacement daemon. Kernels keep running for it unless stop_kernels is
true. Then sessions save their variables and their kernels end. 202 reports
instance_id and state: "draining". The client observes closure with a
bounded wait. It cannot use this endpoint to start the replacement.
The interactive CLI still offers to keep or restart a discovered daemon. Keeping it is the default. Its approved instance identifies the shutdown target. Daemon attachment and local startup owns this user flow and deliberate operator overrides.
Shared settings #
The settings operations in OpenAPI define group names, fields, secret-presence metadata, and patch schemas. Persisted settings links the implementation owners.
A group read supplies its canonical URL and validator. A patch changes one group
under its observed If-Match. It cannot partially apply a multi-group request.
Validation covers the complete candidate before publication. The
settings recovery boundary
coordinates participating readers and writers.
Provider keys and MCP secrets are write-only. Omission retains a secret, a replacement string changes it, and null removes it. Reads expose presence and names, not values. Response-only presence fields are invalid on writes. Deleting a profile or MCP definition also removes its associated secrets.
MCP candidate validation runs before persistence. A failed probe keeps the
previous definition and secrets. The write-only validate_connection control
can deliberately skip that probe. It is not a saved definition field.
Public and secret environment or header maps cannot declare the same name. Header names compare without case. A definition cannot combine multiple bearer sources. Switching sources requires removing the old one in the same patch. Environment references resolve on the daemon host, and the probe uses the candidate's resolved values.
Changing a provider profile does not select it. Changing the default profile explicitly affects new sessions. Removing the selected default requires a replacement or an explicit removal in the same patch.
Per-model raised-cap and compact-at choices affect subsequent prepared requests.
Clients use the returned cap_key rather than constructing one. A compact-at
choice can lower a model window, not raise it. Existing requests retain their
captured settings.
Capability selection uses candidate IDs and the observed catalog revision. The daemon resolves IDs to persisted preference keys. This prevents stale discovery from changing a different file. Configured MCP enablement is separate from capability selection: a disabled definition remains unavailable even if selected.
A successful patch distinguishes the saved resource from application state.
composition_changed describes a change to desired composition, not proof that
open sessions reloaded. The caller can list sessions with needs_reload=true
and explicitly reload them. Global services use new desired settings on
subsequent requests.
The exact group and mutation envelopes remain in OpenAPI. The settings tests exercise conditional edits, secret retention and removal, candidate validation failure, and persistence failure.
Usage totals #
GET /usage (capability usage_summary: 1) answers what the provider calls
used over the last 1-90 days (seven by default), ending with the client's today.
utc_offset_minutes (-720 to 840, default zero) sets the client's midnight.
That one offset applies to every day, so days before a daylight-saving change
are an hour out, and an hour that straddles a fractional-offset midnight counts
in the earlier day. Optional provider and account (which needs provider.
Empty selects rows without an account) narrow the days and model lines, never
scopes. The read is one snapshot of hourly totals kept beside the request
ledger. provider requests
owns how they are kept.
Storage accounting #
GET /storage reports database, session, shared-image, and daemon-file
accounting. OpenAPI defines the report fields and section continuations.
Storage reads in the Go adapter page those
sections without filesystem access.
Session estimates count pinned context, transcript content, cell sources,
payloads, and traces. Shared images count once outside session estimates.
Estimates do not claim allocated disk space per session. Database measurements
share one read boundary. Filesystem measurements describe the inspection period.
Session and file lists use separate next tokens within this response, with
each token identifying its section. A session token resumes after the last
session ID shown, so sessions written, added or removed between pages never void
it. Totals always cover the complete store.
An online client needs no filesystem or Python access. Returned paths describe the daemon's files and never authorize local deletion. Offline diagnosis and approved cleanup remain explicit local operations under the ownership lock.
History, context, catalogs, and runtime #
Durable history #
http_history.gleam and
http_transcript.gleam own
history projections and content paging.
GET /sessions/{session_id}/history accepts view=entries|checkpoints, default
entries, and one of before, after, or next. Positions are durable
transcript positions, unrelated to the actor cursor. Pages retain ascending
display order and include older, newer, and high_water. Default entry
count is 100, maximum 200, with a 256 KiB content budget.
Each entry has stable id, position, kind, turn_id, input_id,
created_at, content, nullable checkpoint_id, and content_complete. User
entries, assistant answers, and tool calls expose checkpoints for their
inclusive durable transcript row. Calls packed into one row share a checkpoint.
A fork cannot split that row. Checkpoint view lists user turns for the TUI fork
picker. Recorded thinking duration is exposed as thinking_duration_ms. Live
thinking completion can report elapsed_ms. These measure thinking, not the
whole turn.
HistoryEntry in OpenAPI defines the complete kind and content
unions, including human shell_command outcomes. Content can contain text,
JSON, image metadata, and execution traces.
Tagged daemon notes retain their native origin as a JSON part with
field: "origin". Tool names, native call IDs, normalized progress-call IDs,
activity summaries, and file diffs remain available. Provider-private fields are
explicit opaque data. Clients do not reinterpret them as execution instructions.
The daemon pages on complete display groups when they fit. A large group uses content references rather than growing a response past its bound. Preview truncation is explicit and never changes the stored content. Checkpoint view contains position, valid checkpoint ID, title, turn type, and bounded preview. It provides the TUI tree and fork picker without a separate tree route.
GET /sessions/{session_id}/history/{entry_id} returns the full entry content
as pages of parts, each with field, offset_bytes, text, and complete.
Text and JSON fields use their exact stored UTF-8 encoding. Offsets are bytes,
and pieces end on UTF-8 boundaries. Opaque next identifies the next piece. The
decoded content budget is 256 KiB per page. The daemon shortens a page further
when JSON escaping would reach the common encoded response bound. Image fields
are not paged. An image's metadata gives its MIME type, dimensions, byte count,
and a reference to GET /sessions/{session_id}/history/{entry_id}/{field},
which returns the stored bytes with the image's own Content-Type. Clients can
reconstruct full arguments, results, and images without filesystem access.
GET /sessions/{session_id}/history/content?entries=a,b,c reads those parts for
up to 200 entries in one walk, in the order entries names them, so a page
whose entries are mostly references costs one request per byte budget instead of
one per entry. Each part carries the entry_id it belongs to, because a page
can stop in the middle of an entry. Offsets, the per-piece and per-page budgets,
and the exclusion of image fields are the single-entry route's. A next
continuation is bound to that request's path and its exact set of entries, so it
cannot be replayed against another set. Entry IDs are at most 128 characters.
Clients that need one entry's content keep using the single-entry route.
Prepared context and request records #
GET /sessions/{session_id}/context defaults to view=summary. It describes
the latest actual prepared request, never prepares a new one. The summary has
state: "pending"|"ready", nullable snapshot_id, capture time, provider,
model, protocol, context-window tokens, compaction observations, and sections.
Each section contains ID, label, kind, source, item count, UTF-8 byte count,
page count, and bounded preview. Pending state contains a reason.
view=section requires snapshot_id, section_id, and a zero-based page. A
page has text, omitted-content explanation, page index, and page count. Text
has a 32 KiB UTF-8 limit and ends on a character boundary. Only the latest
snapshot is retained. If it changes during navigation, the old identity returns
410 context_changed. The client refreshes the summary. A page never silently
comes from another prepared request.
view=requests pages provider request records by durable sequence. It exposes
attempt identity, attribution, outcome, usage observations, and links to
transcript positions. Full provider request bodies and credentials are absent.
Unknown historical identities remain null. Estimated and observed token counts
have separate fields and sources. See
provider request recording.
GET /models?view=cache-policy reads the cache-policy table and its layer
diagnostics. Entries retain matching patterns, clock, tiers, prices, survival,
evidence, sources, and notes. limit and next page entries. Optional
extension, host, and model selectors return the first matching entry in
matched, independent of the displayed page. This view does not require a
provider profile and never connects to a provider. Catalogue view remains the
default.
Discovery and loaded composition #
GET /sessions/{session_id}/catalog returns discovery and loaded as
separate fields. Optional kind=extensions|skills|instructions|mcp|commands
filters entries without changing these identities. Discovery contains
revision, workspace, candidates, and diagnostics. It reflects current local
files and preferences. Remote files come from the last observed mirror.
Preparation refreshes stale mirrors. Loaded contains its composition revision
and prepared command definitions. Reading discovery does not reload the prompt
or start a kernel. Before a composition exists, native_commands supplies
static HTTP declarations from selected extensions. Clients use these
declarations only while the loaded revision is null. Observing them does not
prepare an extension or start a kernel. If desired discovery fails, discovery
is null and discovery_failure contains a safe reason. Retained loaded commands
remain readable. Successful discovery sets discovery_failure to null. Clients
need a discovery revision to edit selection.
Candidates retain source, resolved-source identity, enablement, shadowing, dependencies, and diagnostics. OpenAPI defines their exact fields and the plugin metadata available for extension inspection.
Selections use candidate IDs and the observed discovery revision. Paths are daemon metadata, not client filesystem instructions. Diagnostics survive missing, invalid, shadowed, and quarantined entries.
Command definitions contain ID, slash name, description, typed argument
declarations, caller permissions, and delivery: "read"|"mutation"|"input".
They identify either a canonical HTTP operation or a durable input variant.
There is no public endpoint that accepts an arbitrary slash command string. The
CLI parses slash syntax into the named operation. Python bindings call the same
domain owner with trusted model caller context.
Page descriptors declare display and form data together with typed HTTP actions. The command contract and OpenAPI own their field definitions.
An action resolves bindings from literals, the displayed row, submitted form
values, or the installed session snapshot. An edit binds If-Match to the row's
observed validator. The adapter does not fetch a newer validator just to
overwrite a stale screen.
Descriptors cannot change retry policy or authorization. The adapter rejects foreign origins and undeclared extension routes. Result schemas are local JSON Schema fragments without remote schema retrieval. Extension response bodies remain explicit dynamic JSON values.
Reload, kernel upgrade, and compaction #
POST /sessions/{session_id}/reload accepts
target: "session"|"models"|"both", default both. Session reload requires idle,
builds the candidate composition before swapping it, and retains the previous
composition on failure. Success preserves the Python namespace and pinned prompt
prefix, except where an extension's declared lifecycle requires restart. The
result includes loaded revision, restart requirements, and warnings. Model
reload reports success or failure per provider and keeps old catalog data where
refresh failed. It also reloads cache policy, reported separately as
cache_policy with state and failure. Session-only reload returns null there.
both returns these outcomes explicitly. One confirmed refresh is not hidden by
failure of the other.
POST /sessions/{session_id}/kernel/upgrade accepts an empty object and
requires idle. It stages the new kernel, reports the fate of live jobs, copies
supported namespace state, and swaps only after validation. Failure keeps the
previous kernel usable where the existing upgrade boundary permits it. Stopped
external jobs are reported as stopped and cannot be claimed restored. The
response contains old and new identities, upgrade state, stopped jobs, and
warnings.
POST /sessions/{session_id}/kernel/restart accepts an empty object and does
not require idle: it cancels queued inputs and the running turn as an interrupt
does, discards the saved variables, and stops the kernel and its jobs without
asking the kernel anything. The response waits for the stop and reports the old
kernel id (null when none ran), the stopped jobs, and the cells that ended. A
stop that fails answers 503 kernel_restart_failed.
POST /sessions/{session_id}/compaction accepts an optional strategy. It
requires idle and compacts the model-facing projection without deleting
transcript history. A supplied strategy first becomes the session override. The
response reports selection_applied, the effective strategy, compaction state,
before and after counts, and safe failure details. A failed compaction can
retain a successfully selected strategy. The response preserves that fact. The
holder of an ACP attachment may compact its own session; a client without a
token gets acp_owned, and a wrong token gets attachment_lost. Neither
runtime action automatically retries an uncertain external effect.
Models, workspaces, hosts, and provider login #
GET /models reads metadata for a saved provider profile or an explicitly
supplied provider and endpoint. It returns model objects even when the provider
cannot enumerate every ID. A manual model ID can still be selected. Unknown
limits remain null, and metadata retains its source and freshness.
Model selection links the owning provider and catalog
code.
GET /workspaces without location lists recent canonical workspaces with use
counts and last activity. With location, it browses that directory. Optional
preview data includes VCS facts, language shares, and a bounded file tree. The
exact representation and limits are in OpenAPI.
include=files (alone or as preview,files) lists the directory's files after
its directories, each by name under the same pagination, and gives every item
kind, size (null for a directory) and ignored (whether git, or a colocated
jj, ignores it. Null outside a repository or in jj without git). Git and jj
facts retain their distinct typed variants. A missing optional VCS fact is null
with a diagnostic, rather than loss of the entire directory. The tree has at
most 12 top-level entries and four children per directory. more counts
omissions. Local and SSH locations share this representation. Paths are
interpreted and canonicalized on the daemon's host.
GET /sessions/{session_id}/files?path= reads one file for a client to show, on
the machine the session's workspace is on, local or over the same SSH gather as
browsing. path is absolute there, relative to the workspace, ~/... in a
local workspace, or the host-prefixed spelling the answer uses. The answer
carries the canonical path (host-prefixed when remote), size in bytes,
modified_at, and text. Only regular UTF-8 files without NUL are read: over 1
MiB, or too large to answer within the response limit, is 413 file_too_large.
Binary or invalid UTF-8 is 415 file_not_text. Missing, a directory, or not a
regular file is 404 file_not_found. A host that is not ready is 503
workspace_unavailable, as for browsing.
GET /sessions/{session_id}/changes?base=uncommitted|upstream reads every
change of the checkout enclosing the session's workspace, on the machine the
workspace is on. It answers the checkout (kind, root, head, branch), the base it
compared with (spec, label such as HEAD, @-, origin/main or trunk(), and
short commit), and the files sorted by path, each with status, the path a rename
came from, line counts, a binary flag, and a unified diff or the reason it was
omitted (binary, too_large past 256 KiB, budget once 768 KiB of encoded
diffs is spent, in order). At most 1000 files are listed, then truncated. It
never writes: no index refresh, no jj snapshot or operation. Each answer has an
ETag over its body, and If-None-Match with it answers 304, so a client polls
it while a session works. A workspace outside any checkout is 409
not_a_repository, an upstream base with nothing to compare with 409
no_upstream, a host that is not ready 503 workspace_unavailable, a failing
git or jj 502 vcs_failed, and commands past their 15 s deadline 504
vcs_timeout. Capability checkout_changes: 1 covers it and include=files.
GET /hosts reads known SSH targets and cached probe state.
POST /hosts/{host}/probe starts or joins a bounded probe. Repeated probes
coalesce. A read does not start SSH sign-in.
Workspace and host ownership links the daemon
implementation.
SSH sign-in remains an explicit operator action. A local CLI can perform the existing terminal handoff using daemon-supplied target and control-path metadata after confirmation. A client on another machine displays instructions for signing in on the daemon host. This API does not promise a browser terminal. Filesystem failure codes distinguish missing workspace, needs-auth, unreachable host, unsupported host, and permission denied.
GET /auth returns login providers, their form fields and supported flows,
redacted accounts, and account selection metadata. It does not duplicate
credential values from settings. PUT /auth/logins/{login_id} uses UUIDv7, with
provider and declared typed form values. The server records immutable login
intent and returns URL, expiry, state, and manual-input instructions. First
creation returns 201. An identical PUT returns the existing flow with 200.
Changed intent returns 409 login_conflict. Same-ID comparison stays inside the
daemon and includes the private form values. A duplicate never starts a second
flow. Login secrets never appear in the read representation or its fingerprint
provenance fields. Fingerprints are server-created and are not exposed for
low-entropy login secrets.
GET inspects that flow. PATCH supplies response, such as a pasted callback
URL or provider code, under If-Match. DELETE cancels it idempotently. States
are waiting, exchanging, complete, failed, cancelled, and expired.
Flow reads include bounded safe progress and globally unique opaque account IDs
that also identify their provider. Completed flows return account metadata.
Terminal flow metadata remains for 15 minutes, uncompleted flows expire after
their advertised provider deadline, and at most eight flows are active.
Duplicate creation never opens a second flow. An expired or evicted ID cannot
restart a flow. Unknown IDs older than the 15-minute flow recovery window return
410.
Login admission intent and terminal decisions survive daemon restart within
their retention window. A restart marks an unfinished flow failed with
code: "daemon_restarted". It does not reuse a lost listener or exchange.
Repeating its PUT returns that retained failure. Starting again requires a new
login ID. The daemon retains only the protected secret material needed for
immutable-intent comparison and removes it when the record expires.
OAuth callbacks stay on provider-required daemon-owned loopback listeners. They
validate provider state and PKCE where the provider supports it. Manual callback
input preserves remote-client usability. Secrets and callback codes stay out of
logs and SSE. Selecting an account updates a provider profile through
/settings. DELETE /auth/accounts/{account_id} refuses removal while a saved
profile still references it. It does not interrupt a running request using
captured credentials.
Client responsibilities #
API operations are independent of UI shortcuts. Client-owned drafts, editors, clipboard operations, animation, navigation, confirmations, and quit behavior do not need daemon routes.
Human graph messages use ordinary user inputs addressed to the selected session. Agent-originated mail uses trusted family permissions. A client cannot forge an agent sender by adding a role or caller field.
The daemon exposes bounded live state and full durable content separately. A screen can show a preview without reconstructing tool arguments, but must use content reads when the user requests the complete result. A reset replaces daemon-derived state while preserving local drafts and unresolved operation handles.
Client API ownership describes adaptation. API architecture names persistence and lifecycle owners. Change the HTTP API states contribution requirements.
Verification #
These are examples of checked behavior, not an exhaustive coverage claim:
| Behavior | Evidence |
|---|---|
| An ordinary HTTP consumer creates a session, admits input, reconnects, and reads history. | http_consumer_test.py. |
| Identified input keeps its intent, queue decision, and delivery state across retries and restart. | operations_test.py and operations_lifecycle_test.py. |
| Old actor cursors reset, replay retains order, and stalled readers cannot retain unbounded queues. | stream_replay_test.py and stream_pressure_test.py. |
| Unicode preview offsets and interleaved tool identities stay consistent with durable arguments. | tool_progress_test.py. |
| Conditional settings edits preserve secrets, and a blocked committed recovery reports failure until recovery can finish. | settings_test.py. This does not establish coverage of every storage crash point. |
| Shell command retries and side-question continuation preserve identity without replaying external effects. | shell_commands_test.py and side_questions_test.py. |
Controlled session stream tests cover malformed batches and callback failure before cursor commit. The real-daemon contract transport validates responses encountered by Go end-to-end scenarios. Neither establishes coverage of operations a scenario never invokes.
Change the HTTP API states the checks required for a new change. A requirement to test a failure boundary is not a claim that every such test already exists.