Does: the network API — /v1 routes, bearer token → session, SSE, lease-request resources, console files.
Surface: remote-agents.mdx, console.mdx.
Dispatch:
- Never a second dispatcher and never the unix socket:
deps.dispatchis the daemon's own dispatcher, called in process. Role check,authorizeand readiness parking run there. - No role or
authorizecheck here. The exceptions: the cross-site check on a proxy-signed identity (requireAuth), the lease lookup of a module's lease route and of the lease file routes, and request ownership (requireOwnRequest): a stored request is read or cancelled by its owner or an operator, else 403. app.tsis a pure request → response function; the console lives inserver.ts.- Never imports drivers or gateway. No lint rule holds this.
- The listener starts right after the socket claim, before startup convergence. Early requests park in the dispatcher.
Auth and answers:
requireAuthruns on every route butGET /v1/healthz, mounts and module lease routes included. Who the caller is, issrc/auth's answer; aworkerjoin token gets 403 on every route.- A proxy-signed (
ambient) identity on any method but GET, HEAD or OPTIONS needsSec-Fetch-Site: same-originexactly, else 403FORBIDDEN. So does a WebSocket upgrade. Tokens are exempt. - A subscription stream (a request's events, a lease's events, the event stream) opened by an identity with
expiresAt(a proxy JWT) ends then, and so does a screen stream (stream/service.ts). The exec and component-install streams take no deadline: they end with their command. - No secret or hash in a body:
token.list's output schema has neither. The secret is shown once, bytoken.create. - An error nothing recognizes answers
INTERNAL, "Internal error", and is logged; its own message never leaves. - The ETag step buffers a body to hash it, so it runs only on a JSON answer under
/v1that is not a mount's. A stream's or a mount's body is never read. emptyBodyAsNoneruns before the validator on a route whose body is optional: an empty body is read as none, whatever the content type.
Route declarations:
- A route's error code lists are documentation: nothing enforces them.
- A handler's JSON reply is type-checked against its declaration, never at run time. A stream or a bodiless 204 returns any
Response. buildOpenApiDocumentwrites the document from the same declarations, plus the routes of every module definition that carrieshttp.core-routes.test.tschecks that every route the app serves is declared, and that its first path segment is in the contract'sCORE_ROUTE_SEGMENTS, which a module's name may not start with.- A module's lease route (
HttpLeaseRoute) gets the lease already resolved withlease.get: the owner or an operator; anyone else, and an unknown id, get 404UNKNOWN_LEASE. The module never checks an owner, and http knows a module only by its name. - A WebSocket upgrade of a lease route goes through
app.leaseSocket, which runs the same auth and lease resolution, then the route'ssocket.open. A route with nosocketanswers 404 to an upgrade.
Lease requests:
- The record is the daemon's (
LeaseRequestReader: a worker's request book or a gateway's coordinator), read throughleaseRequestRecordSchema.LeaseRequestTrackerstores none. POST /v1/lease-requestsanswers 201 once the daemon has stored the request and then reported progress or granted. It answers at once on admission forallowDownload(not on a gateway:answerDownloadsEarly) and for a replayed request. A rejection before that fails thePOST.- A request's event stream ends at a terminal stage, or at once when nothing in this process drives it.
Streams:
- The exec and component-install streams open on
onStarted; a failure before that is a plain error response. OutputRelay: the write promise is the backpressure. Once the client is gone the command runs on and nothing is kept (OutputRelay.bufferedCountis asserted).LeaseNoticeBuffertakes the lease's health facts from the daemon'sOwnerRoutedFacts, pushes them live to SSE listeners and keeps them until the lease's renew drains them intonotices.lease_lostclears the lease.
- The notice buffer is the last frontend-held state. It is in memory and resets on a daemon restart, so a polling client loses the health facts it had not drained. It needs a durable record of why a lease ended first.
- Single-lease reads answer 404, not 403, for an unowned lease.
GET /v1/leases/{id}and its/eventsdispatchlease.get, which answersUNKNOWN_LEASEfor a lease that is not there and for one the caller does not own alike. Renew and release dispatch directly and answer 403. - Error codes outside the contract union.
UNAUTHENTICATED,UNKNOWN_LEASE_REQUEST,REQUEST_NOT_CANCELLABLE,REQUEST_CANCELLED(errors.ts) have noERROR_TABLErow, so a typed client seesUNKNOWN_DAEMON_ERROR.