Developer guide / runner

Run delivery and recovery

An agent runs once. The runner can send the same event again until the gateway acknowledges it.

Draft · The release review is in progress.

Before HTTP success

The runtime validates the request and resolves the trusted user. It finds or creates the thread and acquires the run lock.

The runtime uses canonical thread and run IDs from the platform. It joins the gateway before it returns a successful run response.

A failed join must release the lock. A conflicting run must not start another agent.

Each event has a stable ID and sequence number. A retry preserves those values and the event content.

The gateway can advertise runner_event_batch_v1 during a join. Each negotiated batch contains at most 32 events.

Without that capability, the runner sends individual events. The final event also requires an acknowledgment before successful completion.

A retryable gateway_draining response does not end the run. The runner retries the join within its recovery deadline.

A planned WebSocket close with code 1012 triggers reconnect and replay. The runner must not start the agent again.

A gateway stop must cancel an idle agent. An HTTP stop must pass the user-ownership check.

An optional runId protects a current run from an old stop request. Repeated stops must not abandon an unacknowledged batch.

Shutdown must also include requests that await a lock or gateway join. Application agents must cooperate with cancellation.

A clean network close does not prove that the agent finished. A stream without a terminal event must produce INCOMPLETE_STREAM.

The runtime closes unfinished text and tool streams. An intentional stop uses the stopped result. An unexpected stream end is not success.