Expand description
The documented HTTP API an orchestrating agent drives sessions with.
The web viewer’s own /api/... routes exist for the browser: they are
undocumented, cookie-only, and shaped around what a phone renders. These
/api/v1/... routes are the stable surface instead. They authenticate with
a bearer token from a file the same user can read, answer with a version
header so a client can tell which contract it reached, and — the point of
the whole module — let a caller block until one specific prompt finishes and
read a structured outcome for it.
Everything that needs the daemon’s live session actors or its SQLite store
reaches them through SubagentBackend. The daemon implements it in
server_runtime::api; the route tests implement it with a hand-written fake,
so the HTTP contract is tested without a running daemon.
Structs§
- ApiBackground
Work - Observed provider-owned background work; absent when no live snapshot is available.
- ApiFailure
- An API failure with a message written for the caller.
- ApiSession
- One session as the API presents it. This is a narrower, more stable shape than the viewer’s own session projection, which changes whenever the browser needs something new.
- Bundle
Export - A git bundle of the session’s work.
- Export
Request - File
Query - Which file of the session’s workspace to read.
- Prompt
Request - Prompt
Response - Pushed
Branch - A branch the daemon pushed on the caller’s behalf.
- Relay
Health - Session
List Query - Session
List Response - SetConfig
Request - Spawn
Subagent Request - Start
Followup - Configuration and a first prompt to apply once a newly created session’s harness is ready. Served in M2.
- Start
Session Request - Create a session and, optionally, send its first prompt. Served in M2.
- Start
Session Response - Subagent
List Response - Subagent
Source Range - Subagent
View - Transcript
Item View - Transcript
Page - A page of transcript items, read from the durable projection. One page of a session’s transcript, ordered by the sequence a reader pages by rather than by creation order.
- Transcript
Query - Transcript
Response - Turn
State - Where a session stands turn by turn, read from the durable projection when no live actor holds the session.
- Turn
Summary - What one turn produced, without loading the transcript around it.
- Usage
Query - Page through a session’s transcript.
- Wait
Capacity Retry - Wait
Decision - What one pass of the wait loop concluded, before the turn summary is read.
- Wait
Observation - Everything one pass of the wait loop knows about a session.
- Wait
Request - Wait
Response - Wiki
Brief Query - Wiki
Brief Response - Wiki
Restore Body - The fields of a start request a restore needs. The archived session decides the rest: its title, and the project it ran in when the caller names none.
- Wiki
Search Query - Write
File Query - One file from the session’s workspace, as bytes.
- Write
File Response
Enums§
- Export
Error - Why an export could not be produced. Served in M4.
- Export
Kind - What form the caller wants the session’s work in.
- Relay
State - How the daemon’s live view of a session’s relay is doing.
- Start
Status - How far a created session’s follow-up has got. Served in M2.
- Wait
Outcome - How a wait ended.
Constants§
- API_
VERSION - API_
VERSION_ HEADER - Response header naming the contract version this server speaks. A client that understands only version 1 can refuse anything else without parsing a body it may not recognize.
- DEFAULT_
TRANSCRIPT_ LIMIT - How many transcript items a page carries when the caller names no limit, and the most it may ask for. A caller that asks for more gets the ceiling rather than an error: paging is the point, and refusing a large limit would only make the caller retry with a smaller one.
- DEFAULT_
WAIT_ SECS - How long a wait blocks when the caller names no timeout, and the ceiling it may ask for. Both are generous: a turn routinely runs for minutes, and the caller is a program that reconnects rather than a person holding a page.
- MAX_
TRANSCRIPT_ LIMIT - MAX_
WAIT_ SECS - Longest time a sub-agent completion wait may remain pending.
Traits§
- Subagent
Backend - Everything the API needs from the daemon: live session actors, the durable projection, and the target-side git operations.
Functions§
- api_
token_ path - Where the bearer token lives. It is a file rather than an environment variable so it survives daemon restarts and so deleting it is the explicit revoke gesture.
- load_
or_ create_ api_ token - Read the API bearer token, minting one on first use.
- map_
stop_ reason - Classify a harness stop reason.
- resolve_
wait - Decide whether this observation ends the wait.