1# zut RPC
2
3`zut rpc` runs the agent runtime as a subprocess that speaks newline-delimited JSON on stdin and stdout. Use it from any language that can spawn a process and read/write its pipes — Go, TypeScript, Python, Rust, shell, anything.
4
5For a Go program embedding the runtime in-process, use the `packages/agent/sdk` SDK instead. The wire format below mirrors the SDK's types one-for-one so consumers can share parsing code.
6
7## Quick start
8
9```bash
10# spawn zut rpc; talk to it from a shell
11( echo '{"id":"1","type":"prompt","message":"hello"}'; sleep 5 ) \
12  | zut rpc --provider anthropic
13```
14
15You'll see one JSON object per line on stdout: a response acknowledging the prompt, a stream of events (`text_delta`, `tool_call`, `tool_result`, `usage`), then `done`.
16
17## Process model
18
19- One `zut rpc` process serves **one cwd, one model, one session**.
20- For multiple projects, spawn multiple processes.
21- Concurrency: at most one prompt or compact in flight at a time. A second one queues until the first finishes; aborting fires immediately.
22- The process exits when stdin closes.
23
24## Flags
25
26`zut rpc` accepts the same flags as the other modes: `--provider`, `--model`, `--cwd`, `--api-key`, `--base-url`, `--system-prompt`, `--append-system-prompt`, `--reasoning`, `--max-steps`, `--no-tools`, `--tools`. Sessions are disabled by default in RPC mode — the embedding application owns persistence.
27
28RPC agents use the same resolved system-prompt policy as other modes. Ponytail coding mode is enabled when `ponytail_enabled` is missing or `true` in `$ZUT_HOME/config.json`, and disabled when it is `false`. A custom `--system-prompt` replaces the built-in identity, while enabled append addenda remain present.
29
30## Auth
31
32If the environment variable `ZUTCORE_RPC_TOKEN` is set on the spawned process, the first line on stdin **must** be a `hello` command containing the matching token:
33
34```json
35{"id":"0","type":"hello","token":"shared-secret"}
36```
37
38If absent or wrong, the response carries `success:false` and the process exits. Without `ZUTCORE_RPC_TOKEN` set, no auth is required (the spawning process is implicitly trusted; if it can spawn `zut` it can also read your `auth.json` directly).
39
40## Wire format
41
42Every line in either direction is one JSON object terminated by `\n`. Object boundaries follow newline boundaries — no multi-line JSON.
43
44### Frame types
45
46| `type` | Direction | Description |
47|---|---|---|
48| any command (`prompt`, `abort`, ...) | client → server | Request |
49| `response` | server → client | Reply to one command, correlated by `id` |
50| any event (`text_delta`, `tool_call`, ...) | server → client | Stream notification (no `id`) |
51
52## Commands
53
54All commands share an optional `id` field; if present, the matching `response` echoes it. Use `id` to correlate replies with requests, especially when several requests are in flight.
55
56### `hello`
57
58```json
59{"id":"0","type":"hello","token":"shared-secret"}
60```
61
62Response:
63
64```json
65{"type":"response","id":"0","command":"hello","success":true,
66 "data":{"protocol_version":1,"version":"0.0.4","provider":"anthropic","model":"claude-opus-4-5"}}
67```
68
69Required as the first message when `ZUTCORE_RPC_TOKEN` is set; optional otherwise.
70
71### `prompt`
72
73```json
74{"id":"1","type":"prompt","message":"fix the failing test","images":[]}
75```
76
77Optional `images` is `[{"mime_type":"image/png","data":"<base64>"}]`.
78
79Response is immediate (the turn is starting):
80
81```json
82{"type":"response","id":"1","command":"prompt","success":true,"data":{"started":true}}
83```
84
85Then a stream of event objects (see below) until the turn ends with `{"type":"done"}`.
86
87### `abort`
88
89Cancel the active prompt or compact.
90
91```json
92{"id":"2","type":"abort"}
93```
94
95Response: `{"type":"response","id":"2","command":"abort","success":true}`.
96
97If the turn was streaming, the next events you see will be a `turn_end` with `stop:"aborted"` then `done`.
98
99### `compact`
100
101Summarise the current transcript into one synthetic user message. Same lifecycle as `prompt` (immediate response, then events).
102
103```json
104{"id":"3","type":"compact"}
105```
106
107Final event: `{"type":"compact_done","summary":"<text>"}`.
108
109### `get_state`
110
111Snapshot of the runtime.
112
113```json
114{"id":"4","type":"get_state"}
115```
116
117Response data:
118
119```json
120{
121  "provider": "anthropic",
122  "model": "claude-opus-4-5",
123  "cwd": "/path/to/zut",
124  "message_count": 12,
125  "busy": false,
126  "usage": {"input": 1234, "output": 567, "reasoning": 123, "cache_read": 890, "cache_write": 0, "cost_usd": 0.0123}
127}
128```
129
130### `get_messages`
131
132Full transcript.
133
134```json
135{"id":"5","type":"get_messages"}
136```
137
138Response data: `{"messages": [<message>, ...]}`. See **message shape** below.
139
140### `clear`
141
142Drop the entire transcript. Equivalent to the `/clear` slash command.
143
144```json
145{"id":"6","type":"clear"}
146```
147
148### `set_model`
149
150Switch model within the same provider.
151
152```json
153{"id":"7","type":"set_model","model":"claude-sonnet-4-5"}
154```
155
156Cross-provider swaps require relaunching `zut rpc` with the new `--provider`.
157
158### `set_reasoning`
159
160Set the reasoning level for subsequent prompts without restarting the process. Accepted values are `off`, `minimum`, `low`, `medium`, `high`, `xhigh`, and `max`.
161
162```json
163{"id":"8","type":"set_reasoning","reasoning":"max"}
164```
165
166The `max` tier is sent natively to supported models and clamped for other backends.
167
168### `get_models`
169
170List models known for the current provider.
171
172```json
173{"id":"8","type":"get_models"}
174```
175
176Response data: `{"models":[{"id":"...","provider":"...","context_window":200000,"max_output":8192,"reasoning":true}, ...]}`.
177
178### `ping`
179
180Health check.
181
182```json
183{"id":"9","type":"ping"}
184```
185
186Response: `{"type":"response","id":"9","command":"ping","success":true,"data":{"pong":true}}`.
187
188## Events
189
190Stream notifications during a `prompt` or `compact`. None carry an `id`.
191
192| `type` | Fields | Meaning |
193|---|---|---|
194| `turn_start` | `step` | Beginning of one model call (max-steps loop iteration) |
195| `request_started` | `provider`, `model`, `scope`, `attempt`, `max_attempts` | A provider (`scope=provider`) or agent (`scope=agent`) request attempt started |
196| `retry_scheduled` | `scope`, `attempt`, `max_attempts`, `delay_ms` | The upcoming attempt is delayed; `delay_ms` is a non-negative integer |
197| `user_message` | `content`, `time` | The submitted prompt as it was added to the transcript |
198| `assistant_start` | (none) | Provider connection opened; waiting for assistant streaming |
199| `text_delta` | `delta` | Partial assistant text. Concatenate to build the full reply |
200| `tool_use_start` | `id`, `name` | Provider started streaming a tool call |
201| `tool_use_args` | `id`, `delta` | Partial tool-call argument JSON |
202| `tool_use_end` | `id` | Provider completed the tool-call argument stream |
203| `tool_call` | `id`, `name`, `args` | The model proposed a tool call |
204| `tool_execution_started` | `id`, `name` | Guard and confirmation checks passed; the tool is about to execute |
205| `tool_progress` | `id`, `text` | Optional progress line from the tool while it runs |
206| `tool_result` | `id`, `is_error`, `content` | Tool finished |
207| `assistant_message` | `content`, `time` | Final assistant message after the model turn ends |
208| `usage` | `input`, `output`, `reasoning`, `cache_read`, `cache_write`, `cost_usd`, `cumulative` | Per-turn + cumulative tokens / cost. `reasoning` is null when unavailable. |
209| `turn_end` | `stop`, optional `error` | One model call finished. `stop` is `end_turn`, `tool_use`, `length`, `error`, or `aborted` |
210| `done` | (none) | The whole prompt/compact completed (success or error) |
211| `error` | `message` | Non-fatal error message |
212| `compact_done` | `summary` | Compaction finished, summary text included |
213| `ext_alert` | `extension`, `kind`, optional `reason` | An extension requested a host alert; RPC clients can map it to their own notification UI. |
214| `ext_widget` | `extension`, `id`, `position`, `title`, `lines` | Persistent extension widget update. `position` may be `above_input` or `right_bar`; clients choose their own layout. |
215| `ext_widget_clear` | `extension`, `id` | Remove one persistent extension widget. |
216| `ext_chrome_clear` | `extension` | The extension exited; discard all persistent status/widget chrome owned by it. |
217
218A `compact` request emits request-lifecycle, `assistant_start`, and summary
219`text_delta` events before `compact_done`. It does not emit model-loop turn or
220tool events.
221
222## Message shape
223
224Used by `get_messages` and inside `user_message` / `assistant_message` events.
225
226```json
227{
228  "role": "user",
229  "content": [<content_block>...],
230  "time": "2026-04-19T11:30:00Z"
231}
232```
233
234### Content block types
235
236```json
237{"type": "text", "text": "..."}
238{"type": "image", "mime_type": "image/png", "bytes": 12345}
239{"type": "tool_call", "id": "toolu_xyz", "name": "read", "args": {"path": "..."}}
240{"type": "tool_result", "call_id": "toolu_xyz", "is_error": false, "content": [<content_block>...]}
241```
242
243Image bytes are reported as a count rather than embedded base64 to keep transcript dumps small. Tool results may nest text and image blocks.
244
245## Reference clients
246
247See `examples/rpc/` for working implementations in:
248
249- `shell` — `bash` + `jq` one-liner
250- `python` — `subprocess.Popen` + `json.loads` per line
251- `node` — `child_process.spawn` + `readline`
252- `go` — direct subprocess wrapper (the `packages/agent/sdk` SDK is the in-process Go API)
253
254## Versioning
255
256The `protocol_version` field in the `hello` response is the major version of this schema. Backwards-incompatible changes bump it. The set of supported events and commands within a major version only grows.