zero/docs/STREAM_JSON_PROTOCOL.md

Zero Stream-JSON Protocol

Zero stream-json is a line-delimited protocol for headless clients such as editor extensions and automation wrappers.

Every line is one JSON object. Empty input lines are ignored. Output events are redacted before they are written to stdout.

Version

Current schema version: 1

Every input and output event must include:

{ "schemaVersion": 1, "type": "..." }

Output events also include runId.

Input Events

zero exec --input-format stream-json accepts these JSONL events from stdin or --file.

{ "schemaVersion": 1, "type": "message", "role": "user", "content": "Inspect this repo." }
{ "schemaVersion": 1, "type": "prompt", "content": "Return only blockers." }

Zero combines accepted input event content in order, separated by blank lines. Unknown fields are rejected so protocol clients catch drift early.

Output Events

zero exec --output-format stream-json emits schema-versioned JSONL events.

{ "schemaVersion": 1, "type": "run_start", "runId": "run_20260603_abc123", "sessionId": "zero_20260603100000_abc123", "cwd": "/repo", "provider": "openai", "model": "gpt-4.1", "apiModel": "gpt-4.1" }
{ "schemaVersion": 1, "type": "text", "runId": "run_20260603_abc123", "delta": "..." }
{ "schemaVersion": 1, "type": "tool_call", "runId": "run_20260603_abc123", "id": "call_1", "name": "read_file", "args": { "path": "README.md" }, "sideEffect": "read" }
{ "schemaVersion": 1, "type": "tool_result", "runId": "run_20260603_abc123", "id": "call_1", "status": "ok", "output": "...", "truncated": false }
{ "schemaVersion": 1, "type": "usage", "runId": "run_20260603_abc123", "promptTokens": 12, "completionTokens": 8, "totalTokens": 20 }
{ "schemaVersion": 1, "type": "final", "runId": "run_20260603_abc123", "text": "..." }
{ "schemaVersion": 1, "type": "run_end", "runId": "run_20260603_abc123", "status": "success", "exitCode": 0 }

Errors are part of the protocol and are followed by run_end.

{ "schemaVersion": 1, "type": "error", "runId": "run_20260603_abc123", "code": "provider_error", "message": "...", "recoverable": false }
{ "schemaVersion": 1, "type": "run_end", "runId": "run_20260603_abc123", "status": "error", "exitCode": 3 }