Module api 

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.

The artifact routes are contract

A caller that runs work somewhere other than this machine cannot read the working tree to decide whether a change is safe to publish, so four routes are part of the stable contract rather than conveniences. Changing any of their media types, response bodies, or status meanings is a change to this API:

• GET /sessions/{session_id}/diff answers a unified diff as text/x-diff; charset=utf-8, comparing from the revision the caller names in base when it names one. With json=true it answers application/json carrying mj_checkpoint::archive::SessionDiff instead, a type that lives in the checkpoint crate, so changing its fields is also a change here.
• POST /sessions/{session_id}/export answers the work in the form the caller asks for: kind: "patch" as text/x-diff, kind: "branch" as {"branch", "remote"}, and kind: "bundle" as application/octet-stream with the bundle named in an attachment filename.
• GET and PUT /sessions/{session_id}/files read one file as application/octet-stream and inject one, answering {"path", "bytes"}. Injection requires a live, idle session, because a write into a running turn has no meaning.
• GET /sessions/{session_id}/transcript answers a page of the transcript, with next_after_seq as the cursor to continue from and latest_seq to tell whether the page reached the end.

Where a route can refuse because of the session’s own state — an export with nothing to export, an injection into a session that is neither live nor idle — it answers 409 with a sentence the caller can act on. A failure that is not the caller’s to fix is a 5xx. Keeping those apart is part of the contract, because one is a decision for a person and the other is not.

Structs

ApiBackgroundWork

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.

BundleExport

A git bundle of the session’s work.

CreateWorkspaceRequest

Name the workspace to work in. The name is the identity: it is trimmed, at most 64 characters, and unique case-insensitively, so naming one that already exists returns it rather than making a second.

CreateWorkspaceResponse

DiffOptions

Comparison and representation requested for a session’s working-tree diff.

ExportRequest

FileQuery

Which file of the session’s workspace to read.

LaunchBundle

One repository set a managed target can provision.

LaunchDefault

The pair a caller may leave unnamed when it starts a session.

LaunchHost

One host or fleet, as much as a caller needs to explain an unavailable target. The probe’s own error text is deliberately absent.

LaunchOptions

What a caller may choose when it starts a session, and which pair to use when it chooses nothing.

LaunchProfile

One account this daemon can run work under.

LaunchRepository

LaunchTarget

One runtime template a session can run on.

PromptRequest

PromptResponse

PushedBranch

A branch the daemon pushed on the caller’s behalf.

RelayHealth

ResumeSessionRequest

Resume a stopped, lost, or failed session. Every field is optional: the session’s own record supplies what the caller does not name, which is what makes POST .../resume with no body the scriptable “continue this session” call.

ResumeSessionResponse

What a resume was accepted as: the settings it will actually use, resolved from the request and the session’s record.

SessionListQuery

SessionListResponse

SetConfigRequest

SpawnSubagentRequest

StartFollowup

Configuration and a first prompt to apply once a newly created session’s harness is ready. Served in M2.

StartSessionRequest

Create a session and, optionally, send its first prompt. Served in M2.

StartSessionResponse

SubagentListResponse

SubagentSourceRange

SubagentView

TranscriptItemView

TranscriptPage

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.

TranscriptQuery

TranscriptResponse

TurnSpan

The transcript positions one finished turn covers.

TurnState

Where a session stands turn by turn, read from the durable projection when no live actor holds the session.

TurnSummary

What one turn produced, without loading the transcript around it.

UsageQuery

Page through a session’s transcript.

WaitCapacityRetry

WaitDecision

What one pass of the wait loop concluded, before the turn summary is read.

WaitObservation

Everything one pass of the wait loop knows about a session.

WaitRequest

WaitResponse

WikiBriefQuery

WikiBriefResponse

WikiHitsQuery

The query for the matching passages of one indexed session.

WikiRestoreBody

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.

WikiSearchQuery

WorkspaceListResponse

The workspaces the daemon holds, newest opening first, exactly as the terminal’s workspace tabs and the viewer’s list see them.

WriteFileQuery

One file from the session’s workspace, as bytes.

WriteFileResponse

Enums

ExportError

Why an export could not be produced. Served in M4.

ExportKind

What form the caller wants the session’s work in.

LaunchAvailability

How much this daemon knows about a target’s host.

RelayState

How the daemon’s live view of a session’s relay is doing.

StartStatus

How far a created session’s follow-up has got. Served in M2.

WaitOutcome

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

SubagentBackend

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.