Event protocol

Every Workbench run has an ordered stream of normalized events, the same for every runner. This is the integration boundary for hosts: wb run --json, wb resume --json, and wb attach --json write it as NDJSON, one complete event per line, and the workbenches.dev API stores and serves the same events for cloud runs.

The protocol is protocol: 0. It is versioned separately from the manifest spec number. Its normative schema is /schemas/events/v0/workbench-event.schema.json.

Envelope#

Every event has these fields, and only these:

{
    "protocol": 0,
    "run_id": "wb_d8m99qyw2e4qqhitfff63f1n",
    "sequence": 7,
    "timestamp": "2026-10-28T14:05:41.204Z",
    "type": "output.text",
    "runner": "opencode",
    "data": { "text": "Reading the migration." }
}

Sequences belong to one run. A cursor such as wb wait --after is only meaningful with the run it came from.

Event types#

run.started       run.ready
repository.preparing  repository.ready  repository.checks
delivery.started  delivery.completed  delivery.failed
authentication.requested  authentication.completed
turn.started      turn.completed
output.text
tool.started      tool.completed
file.changed
plan.updated
input.requested   input.accepted
input.queued      input.delivered      input.rejected
question.requested    question.answered    question.rejected
usage.updated
outcome.available     outcome.failed
preview.available
run.completed     run.failed     run.cancelled
runner.event

Exactly one of run.completed, run.failed, or run.cancelled ends the stream.

Data by type#

The schema constrains data for these types. Fields marked optional may be absent.

Turns#

A run may contain several turns. turn.completed means the runner finished one response and may accept another input; it does not end the run.

A turn that ends with reason: "length" hit the model's output limit, so its last tool call did not run. A run with no person attached gets one recovery turn, whose turn.started carries recovery: "length". A run whose latest turn still ends on length when it closes reports run.failed with code: "output_truncated" and a partial outcome.

Tools#

Tool events carry a stable call ID and the native tool name, and may carry a safe display title, target, short description, duration, and normalized failure. They never carry file contents or tool output.

A shell tool's target is its command, scrubbed before it leaves the adapter: values of environment assignments, secret-named flags, authorization headers, URL user information, and secret-named fields in headers, query strings, and bodies become [REDACTED], as do recognizable key formats and long opaque tokens. Heredoc bodies become a line count, control characters are removed, and the command is bounded to 500 characters on one line. Pattern scrubbing cannot recognize every credential, so a host that injects credentials should also redact their exact values before storing events.

exit_code is reported when the runner's tool metadata includes it. The OpenCode adapter passes it through; the Claude Code and Pi adapters report only a failed status.

Plans#

plan.updated carries the agent's whole plan, never a diff, whenever the adapter translates one, such as after a native todo tool call. items holds up to 50 entries. total excludes cancelled items. The plan can grow as the agent finds work, so expect total to change. Runners whose adapter does not translate a plan emit no plan events.

Inputs#

input.accepted means the host accepted the control request. input.queued means the input is waiting in the host or runner. input.delivered means it left that queue for the runner's active execution. Receipts and input events carry request IDs and dispositions, never prompt, image, or answer contents.

A runner can withdraw a permission or question it no longer needs. A withdrawn permission is recorded as input.rejected and a withdrawn question as question.rejected, each with code: "request_withdrawn".

Usage#

Usage is reported at native step completion, not token by token. Costs are provider-reported model costs. Descendant sessions a runner reports contribute their usage and tool activity to the owning run, with native_session_id on child activity.

Infrastructure#

Remote runtimes may attach infrastructure to the terminal event: provider, duration_ms, optional maximum_duration_ms, optional resources (cpu_count, memory_mb), and cost, an estimated or unavailable USD amount. Model tokens and model cost stay exclusive to usage.updated; clients must not combine the two silently.

Previews#

preview.available reports a server the agent started and announced with wbx preview <port> --name <name>. name matches ^[a-z0-9][a-z0-9-]{0,39}$, port is 1024 to 65535 and not one the engine uses, and a run has at most 8 previews. On the local runtime url is the loopback address http://127.0.0.1:<port>/. On Daytona the event has no url, because the port is reached through a signed URL, which is a credential.

Unknown native events#

Adapters translate events whose meaning is known and emit a minimal runner.event with only the native type for anything else. Portable events never copy arbitrary native payloads, which can contain reasoning, credentials, provider metadata, or complete tool results.

Large events#

The reference engine stores an event larger than 4 MiB serialized with its data replaced by { "truncated": true, "original_bytes": <n>, "limit_bytes": 4194304 }, keeping its envelope and sequence.

Compatibility#

Within protocol: 0, minor versions may add event types and optional data fields; existing types and fields keep their meaning. Clients must ignore event types and fields they do not recognize. The event stream is part of the 1.0 stability promise.