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, because this crate cannot depend
on the daemon runtime that owns them.
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 - 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.