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
{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:
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 fromharness.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.
Choose the action from related records
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 onlydata, 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 separatestream.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. Usepause_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 inunknown 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 Sessionopen, 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.