Skip to main content
State belongs to a specific object. A Run can be completed while its Session remains open; a Sandbox can be running while a Run waits for approval. Runtime unreachable does not prove compute absence. Track client connectivity separately.

Session

Source: modules/sandboxes/lifecycle.ts.

Run

Source: modules/execution/runs.ts.

Runtime binding

Source: modules/execution/worker.ts.

Sandbox resource

Source: modules/sandboxes/connector.ts.

Resource operation

Source: modules/sandboxes/operations.ts.

Transitions and observation

The normal Run path is queued → provisioning → running → completed. Failure, authorization, approval, cancellation and worker recovery add branches; this is not a strictly increasing UI progress bar. run.claimed describes worker ownership/generation, not a Run state named claimed. run.recovery_needed can record recovery error information without changing the current state; it is not a new terminal state. Runtime invocations have their own starting, running, cancelling, exited, cancelled, failed and interrupted states; see Runtime. Exited only means process termination. The worker still parses results and exports artifacts before Run completion. The persisted Runtime binding and invocation state are also separate fields.

Transition conditions and separate state examples

These examples show selected fields from separate objects, not a combined API response or a real execution receipt. Read current records to decide the next action. An ordinary Run follows queued → provisioning → running → completed. The worker transition method also allows failure from queued, provisioning, running, either waiting state, and cancelling. Authorization, approval and Tool handlers add their own waiting/resume transitions; the worker transition map alone is not the entire state machine. Cancelling a terminal or already-cancelling Run leaves that state unchanged. For pause/resume, an existing matching target state is returned without starting another transition; a different pause scope is a conflict. A pending transition with the same scope follows reconciliation. The control plane inspects the original resource after uncertain native pause/resume outcomes rather than blindly repeating the remote operation. Provider-managed automatic standby is distinct from explicit compute suspension. Expiry cleanup is different from explicit close: it can fence active Runs, expire pending approvals and record run.cancelling with reason: sandbox_expired before completing resource cleanup. Therefore a close button and an expiry worker do not have identical preconditions. session.pausing, session.paused, session.resuming and session.resumed are persisted in the separate internal session_lifecycle_events table. They are not promised events in the Run event API documented below. Refresh the Session record when observing lifecycle actions. Sources: Session lifecycle, Run transitions and cancellation, Runtime worker, image preparation and cleanup, Tool broker.

Event envelope and cursor

This is an illustrative sanitized shape, not an observed log. JSON event queries return {events:[...]} with id/type/data/created_at. SSE uses id/event/data fields; SDK-parsed stream events do not add the database created_at field. Example SSE:
The cursor is the database sequence as a numeric string: increasing within a Run query, not necessarily contiguous, and distinct from Runtime cursor. Events are persisted before streaming. JSON queries return up to 500 rows. SSE after takes precedence over Last-Event-ID, defaulting to 0. Deduplicate by Run/id and save event plus cursor atomically in your application. A keepalive comment may arrive about every 15 seconds. Once terminal and drained, stream.end carries {state: ...} without an id; it is not durable. Disconnecting only stops observation. Empty pages do not prove terminal state; query the Run after stream completion. Sources: HTTP SSE, Runs.

Main events and payloads

Fields depend on the emitting path; the summary is not a strict JSON schema. Tool sources: broker, reconciliation; artifacts: capture. tool.outcome_unknown requires investigation, not a new approval. Inspect the original call’s hash, policy and state.

Model and protected-API transport events

model.response and protected_api.response record authenticated transport facts for grants associated with a Run. Their data contains connection_id, nullable HTTP status, transport (received when status is known, otherwise failed), and connection_version when supplied. The emitter excludes headers, prompts and response bodies. A public grant without a Run ID does not produce this Run event. status: 200 means an HTTP response was received, not that the model completed the task or a Tool write succeeded. Conversely, status: null leaves the remote outcome uncertain. These events are separate from ToolBroker’s tool.completed and from final run.completed. Source: ConnectionAccess.recordModelOutcome.

Runtime and derived activity events

Runtime ingest stores source events with deduplication keys, then may emit one additional normalized activity event from harness.stdout. The extra event has its own durable event ID; it is not a second Runtime cursor. These are observable process/output records, not private model reasoning. The activity projector accepts only a complete newline-terminated JSON string of at most 65536 JavaScript code units. It recognizes selected OpenClaw, item-based and tool/text event shapes; it does not normalize arbitrary output or every Harness. Names are truncated to 256 units, IDs to 512, and message text to 32768. Missing normalized activity does not mean no work happened. Do not concatenate agent.message and agent.message.delta indiscriminately or overwrite the authoritative Run output with either. Source envelopes come from Runtime; native JSON inside text remains version-specific. Preserve unknown records safely and consult the exact Harness contract when interpreting them. The examples here illustrate source-defined payloads, not logs from an executed task. For example, {"type":"tool.outcome_unknown","data":{"call_id":"example-call"}} directs the UI to investigation. It contains no approval ID. Conversely, {"type":"approval.required","data":{"id":"example-approval","action":{"summary":"illustrative operation"}}} identifies a decision record; action depends on its emitter. These are illustrative payloads, not UUID-valid requests to replay. Events describe what happened; fetch current object state to resolve present actions. The broker and decision handlers update Run state directly in some paths, so deriving state solely by stripping run. from event names is incomplete.

Consumer requirements

Preserve or safely ignore unknown event types without crashing or manufacturing state transitions. Narrow payloads before reading fields. Tool completed can deliver an error or an authorization-denial result; it is not proof a side effect succeeded. caller_verified identifies a caller’s checked conclusion, not a fresh provider request by the server. Reconnect to the original Run rather than resubmitting. Reconcile unknown outcomes. Display Run result, Session state, connectivity and cleanup separately so a success badge cannot conceal unresolved resources. For the underlying recovery model, see durable events; for operational inspection, see observability. SDK event parsing is implemented in Python and TypeScript.

Payload examples by emitted event

These source-shaped examples cover the current fixed event families described above, including the unnumbered transport marker. Each row shows only data, not the full envelope. IDs, digests, timestamps and content are illustrative; zero hashes are placeholders, not byte-integrity receipts. They are not one chronological execution trace. Empty transition data is valid; recovery diagnostics, approval actions and native output may contain additional path-specific fields. Future or provider-specific records must still be handled as unknown types safely.

Emitter boundaries and open event types

The fixed payload examples above cover 35 durable event names and the separate stream.end transport marker. This is a current-source inventory, not a closed event-type enum: Runs.ingest persists a Runtime item’s type as supplied, and the shared Runtime contract can evolve. Unknown event types must remain safe to store or ignore. A future value does not authorize inferring a new Run state. There are also Session lifecycle events in a different table. Their existence does not add them to the Run stream. The event emitter list must be reviewed together with direct state updates: approving, denying authorization or completing a Tool can change Run state without emitting a matching run.running event.

Minimal examples for each state value

Each cell contains independent illustrative projections, not a response containing alternative states simultaneously. Required identifiers and other fields are omitted. Read these with the transition conditions above; they are not commands to force a state. Sandbox state remains an open Provider-derived string. One additional control-plane projection matters: successful Session closure stores {"state":"destroyed"} inside the saved Sandbox object when one existed. That is a retained lifecycle projection, not a fresh Provider inspect response or a universal provider enum. A connector’s inspect(id) === null is a separate absence result, not a resource whose state equals null. See closure.

Lifecycle actions are conditional transitions

The same Session state can represent different compute strategies. Use pause_scope, declared capabilities and persisted operation receipts together with the state. These are action preconditions and observation rules, not a client-side state machine that can replace server checks. Sources: changePause, checkpointTransition, worker preparation.

Review state does not resolve operation outcome

Only an operation currently in unknown accepts the review actions below. Review history and scheduling changes are persisted before optional reconciliation. A successful HTTP response can still contain reconciliation_error; inspect the returned operation outcome rather than using the status code as a cleanup receipt. A completed, rejected or deleted operation does not become reviewable merely because its Session is still closing. Use the actual unresolved operation and preserve its private identifiers. Source: ResourceOperations.review; operational procedure: reconciliation.

Defaults and parameterized writes

New rows start as Session open, Run queued, Runtime binding reserved and resource operation pending; operation review starts as automatic. These defaults come from the initial schema, Runtime binding schema and review schema. Most lifecycle state columns are text rather than database-enforced enums. The values listed here describe current implementation writes; callers must tolerate future values without inventing transitions. Close reconciliation differs from adoption for continued execution. Provision/restore requires a unique matching resource. Close can retain multiple exact operation matches in reconciled_ids and attempt to clean all of those owned resources; zero matches still leaves creation unconfirmed. Marking the original create operation completed during this cleanup reconciliation does not prove a successful Agent invocation, nor does it complete the separate delete operations. Source: closeSession. The source-write inventory records 45 insert/state-write query sites for these four tables across the current non-test TypeScript application/modules/integrations. Dynamic query expressions are listed separately for review. This inventory is source coverage, not evidence that all transitions were executed against a database or Provider. Next: streaming guide, recovery, reconciliation.