Developer docs for main, checked against 9849aeb on 2026-11-16.

HTTP and browser

Long-lived admission

src/serve.rs implements Serve: it accepts programs, compiles them, supervises runs on worker threads, and keeps run records. It outlives individual runs. Each run also has a diagram server, implemented in src/diagram.rs.

The HTTP implementation uses TCP streams and blocking connection handlers. Request/response structs and route dispatch in serve.rs are the source of truth for payloads.

Route families

RoutePurpose
GET /healthRuntime health and protocol information
POST /v1/runsAdmit source and inputs as a run
GET /v1/runs, GET /v1/runs/{id}List runs or read a run record
POST /v1/runs/{id}/pause, /resume, /stopControl execution
GET /v1/runs/{id}/program, /snapshot, /timelineInspect source and execution
GET /v1/runs/{id}/checkpointsInspect recovery points
POST /v1/runs/{id}/rollback, /mutateRestore or change a run
/v1/chat, /v1/chatsMessages and conversation lifecycle
/v1/workspacesSaved workflow drafts and properties
POST /v1/programs/check, /v1/properties/checkCompile or check properties without starting a run

Run diagram traffic is relayed through /v1/runs/{id}/diagram. Chat updates use the event stream at GET /v1/chat/events. Agent terminals use WebSocket routes under /v1/agents/{name}/terminal.

The full listener binds loopback. An optional view listener serves unauthenticated read-only access; its route restrictions are enforced by view_refusal. EA callback routes such as /v1/agent/reply resolve their conversation through a token in the request body.

Browser contract

runtime-client.ts implements browser requests and terminal URLs. protocol.ts contains protocol handling; protocol-generated.ts contains generated Rust wire types and runtime vocabularies.

src/protocol.rs generates the TypeScript contract under Rust tests and checks that the committed output matches. Change the Rust wire definitions when changing shared types.

The standalone browser entry is web/spa/main.tsx. The optional Cargo ui feature embeds the prebuilt web/dist/spa bundle through src/web_assets.rs; a plain Rust build does not require Node. Build commands live in web/package.json.