The stdio RPC bridge (ru agent rpc)¶
ru agent rpc exposes a Ru run to an external process — an editor extension, a script,
a program in any language — as a JSON-RPC 2.0 conversation over stdin/stdout. It is a
thin client on top of the existing CLI: it resolves the same loopback host through
runtime_descriptor.json and the same bearer token, reuses the same HTTP/SSE clients,
adds no HTTP route, and opens no transport beyond stdio. It runs as the current Windows
user inside the local same-user trust boundary: anyone who can spawn the CLI can drive
the host, exactly as ru agent run can.
Run it with no further arguments — ru agent rpc. The bridge owns stdin/stdout for its
whole life, so it cannot be re-invoked between the phases of a run. The TypeScript SDK
at sdk/ru-agent wraps the spawn and exposes typed
host-status, session, run, subagent and policy handles.
Framing¶
- NDJSON: one complete JSON object per line, UTF-8, LF-terminated. A trailing
\rfrom Windows text mode is stripped. - stdout carries JSON-RPC only; diagnostics are written to stderr. Nothing else may write to stdout while the bridge runs.
- Inbound request lines are capped at 1 MiB of UTF-8 bytes, measured after CR/LF
stripping. An oversized line is answered with a
request_too_largeerror (-32600) and skipped (drained through its newline) instead of guessing at content it cannot read. run.outputenforces the same 1 MiB UTF-8 byte cap on the base64datait returns, so a payload that would not fit fails withoutput_frame_exceeds_limit(-32000) instead of emitting a frame the client would reject; fetch those bytes with the CLIagent outputcommand. Every other outbound frame is bounded by its method-level parameter and result caps.- The TypeScript SDK caps each complete or partial frame at 1 MiB + 64 KiB of UTF-8 bytes, excluding a trailing CR/LF, before parsing. Oversized frames or invalid JSON-RPC envelopes (including null roots or non-object notification params) fail all pending requests and event subscriptions and terminate the child. Later frames in the same read chunk are ignored after failure.
- Each SDK event iterator shares a 4,096-notification / 8 MiB serialized UTF-8
buffer between events arriving before attach acknowledgement and events
waiting for the consumer. Overflow discards that iterator's backlog and throws
BridgeTransportErrorwithlastDeliveredSequence. Cleanup targets its exact subscription when peers exist; a pending attach acknowledgement defers that cleanup until its ID arrives, without delaying the overflow error. A malformed attach result fails the iterator. With peers and no usable subscription ID, cleanup cannot target the unknown subscription safely, so the SDK closes the bridge transport and fails its other iterators too. Host runs continue; this does not sendrun.cancel. Attach again using that value asafterSequenceto replay durable events; transient events cannot be replayed. Detach does not cancel the Host run. - A line that is not valid JSON is answered with
parse_error(-32700) and skipped. - Requests without an
idare notifications and get no response. $/cancelRequestis accepted and ignored: v1 requests are short-lived, so there is no in-flight request to cancel.
Exit codes:
| Exit | Meaning |
|---|---|
0 |
stdin reached EOF; queued messages, including bridge.shutdown, were written. |
3 |
The bounded outbound queue filled up. The bridge fails closed instead of dropping a durable event. |
130 |
The bridge was cancelled. |
EOF on stdin shuts the bridge down cleanly; it does not kill the run on the host. A
run is durable, so a client that reconnects can attach again with afterSequence and
replay the durable events it missed.
Handshake¶
The first request must be initialize:
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientInfo":{"name":"my-editor","version":"1.0"}}}
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"bridge":{"version":"1.0.0.0"},"methods":["initialize","host.status","session.create","session.list","session.rewind","run.start","run.attach","run.detach","run.trust","run.approve","run.cancel","run.status","run.command","run.reconcile","run.output","subagent.list","subagent.get","policy.list","policy.import","policy.remove"],"notifications":["run.event","run.transient","run.detached","bridge.shutdown"]}}
protocolVersionmust be1. Any other value is rejected with-32000anddata.ruCode: "unsupported_protocol".clientInfois accepted and ignored by v1.- Any method other than
initializebefore the handshake is rejected withnot_initialized(-32001), including its own retry path. - Calling
initializea second time in the same process is rejected withalready_initialized(-32002). methodsandnotificationsare the exact v1 surface. Clients use them to detect protocol drift early instead of discovering it on the first failing call.
Methods v1¶
runId is always run_ followed by 32 lowercase hex characters. String parameters are
bounded; the bridge rejects anything over the limit as invalid_params rather than
truncating it.
| Method | Params (main) | Result | Host call |
|---|---|---|---|
initialize |
protocolVersion |
handshake payload above | internal |
host.status |
— | { "ready": true, "base_url": "http://127.0.0.1:..." } |
GET /settings |
session.create |
— | { "session_id": "..." } |
POST /sessions/new |
session.list |
— | session list (passthrough) | GET /sessions |
session.rewind |
sessionId, index |
rewind payload (passthrough) | POST /sessions/{sessionId}/rewind |
run.start |
workspace, prompt, preset?, sessionId?, trustWorkspace?, confirmFullAccess?; prompt is bounded to 200,000 characters (AgentRunLimits.MaxPromptChars) |
{ "run_id", "session_id", "status", "workspace_id" } |
POST /agent/v1/runs |
run.attach |
runId, afterSequence?, includeTransient? |
{ "subscription_id", "run_id", "include_transient" } |
GET /agent/v1/runs/{runId}/events (SSE) |
run.detach |
subscriptionId (or runId for cleanup) |
{ "detached": "<subscriptionId>" } or { "detached": <count>, "run_id": "<runId>" } |
internal |
run.trust |
runId, approve? |
{ "run_id", "status" } |
POST /agent/v1/runs/{runId}/trust |
run.approve |
runId, approvalId, decision |
approval payload (passthrough) | POST /agent/v1/runs/{runId}/approvals/{approvalId} |
run.cancel |
runId |
{ "cancelled": "<runId>" } |
POST /agent/v1/runs/{runId}/cancel |
run.status |
runId |
run record (passthrough) | GET /agent/v1/runs/{runId} |
run.command |
runId, command |
command payload (passthrough) | POST /agent/v1/runs/{runId}/commands |
run.reconcile |
runId, outcome, hash |
reconcile payload (passthrough) | POST /agent/v1/runs/{runId}/reconcile |
run.output |
runId, payloadId |
{ "encoding": "base64", "data", "byte_length" } |
GET /agent/v1/runs/{runId}/payloads/{payloadId} |
subagent.list |
runId (root) |
root-owned snapshot and usage | GET /agent/v1/runs/{runId}/subagents |
subagent.get |
runId, agentId, resultVersion?, offset?, limit? |
child detail and optional UTF-8 result page | GET .../subagents/{agentId} |
policy.list |
scope? |
array of policy rules | GET /agent/v1/policies |
policy.import |
file, confirm |
{ "imported": [ ... ] } |
POST /agent/v1/policies (one request per rule) |
policy.remove |
ruleId, confirm |
{ "removed": "<ruleId>" } |
DELETE /agent/v1/policies/{ruleId} |
Details that are easy to get wrong:
run.start—presetdefaults tostandardand acceptsplan,standardorfull_access.full_accessrequiresconfirmFullAccess: true; without it the call fails withfull_access_confirmation_required.trustWorkspacedefaults tofalse. The returnedstatusis the host's state at creation time —waiting_workspace_truston a workspace that is not trusted yet,waiting_historywhen it already is; granting trust only moves the run forward afterwards, so the example below still reports the creation state.run.attach—afterSequencedefaults to0and must be a non-negative integer;includeTransientdefaults tofalse. Each call returns a freshsubscription_id;run.detachtakes that id, not the run id. A client whose attach response never arrived may callrun.detachwithrunIdinstead: every subscription for that run is cancelled and the answer reports how many (detached: 0is a valid no-op, not an error).run.trust—approvedefaults tofalse, which sendsdeny.run.approve—decisionis one ofallow_once,allow_session_directory,allow_always,deny.run.command—commandtext is bounded to 8192 characters.run.reconcile—hashproves the caller decided on the current durable reconciliation request, not the state of the workspace files. Bothoutcomeandhashare required;hashmust be exactly 64 characters. Accepted outcomes areapplied,not_applied(ornot-applied) andunknown_continue(orunknown).policy.importandpolicy.removerequireconfirm: true; without it the call is rejected asinvalid_params.
run.start:
{"jsonrpc":"2.0","id":3,"method":"run.start","params":{"workspace":"C:\\work\\repo","prompt":"fix the failing test","preset":"standard","sessionId":"7b1e4f5a9c2d4e6f8a0b1c2d3e4f5061","trustWorkspace":true}}
{"jsonrpc":"2.0","id":3,"result":{"run_id":"run_0123456789abcdef0123456789abcdef","session_id":"7b1e4f5a9c2d4e6f8a0b1c2d3e4f5061","status":"waiting_workspace_trust","workspace_id":"a1b2c3d4e5f60718293a4b5c6d7e8f90"}}
run.attach, then the first durable event arrives as an unsolicited notification:
{"jsonrpc":"2.0","id":4,"method":"run.attach","params":{"runId":"run_0123456789abcdef0123456789abcdef","afterSequence":0}}
{"jsonrpc":"2.0","id":4,"result":{"subscription_id":"sub_1","run_id":"run_0123456789abcdef0123456789abcdef","include_transient":false}}
{"jsonrpc":"2.0","method":"run.event","params":{"subscription_id":"sub_1","protocol_version":1,"event_id":"4d5e6f708192a3b4c5d6e7f8091a2b3c","run_id":"run_0123456789abcdef0123456789abcdef","session_id":"7b1e4f5a9c2d4e6f8a0b1c2d3e4f5061","sequence":1,"event_type":"run.state_changed","occurred_at":"2026-09-30T00:00:00Z","status":"running","safe_summary":"Run is running.","payload_ref":null,"input_tokens":null,"output_tokens":null,"total_tokens":null}}
Notifications¶
run.event— one durable event per run, replayed fromafterSequence. Params:subscription_id,protocol_version,event_id,run_id,session_id,sequence,event_type,occurred_at,status,safe_summary,payload_ref,input_tokens,output_tokens,total_tokens. The envelope is safe by construction: it carries a summary and a payload reference, never raw model or tool text. The bridge never followspayload_refon its own — a client that wants the bytes callsrun.output.run.transient— live frames delivered only when the subscription was created withincludeTransient: true. The SSE wire tags every one of themevent: transient, soevent_typeis always"transient"; the actual kind (assistant.delta,tool.output.delta,agent.activity,agent.summary,agent.usage_estimate) rides insidedataas a{"kind":"...","data":"..."}JSON string. Params:subscription_id,transient_sequence,event_type,data. Transient frames are never replayed and never buffered, so a reconnect starts without them.transient.frames_droppedis not one of these — it is a durable event and arrives asrun.event.run.detached— the subscription pump ended before the run reached a terminal state. Params:subscription_id,reason(stream_interruptedwhen transport reads failed past the retry budget or the SSE client failed,subscription_endedwhen the stream ended cleanly and the run was not confirmed terminal or a durable frame could not be read,event_filteredwhen the privacy guard rejected a durable frame — the frame cannot be delivered, and skipping it silently could suppress the terminal event a consumer waits on). A client that calledrun.detach, or a bridge that is shutting down, cancels the pump instead and gets no notification. A full outbound queue skips it too: that path already fails closed withbridge.shutdown. The reason set is bounded so clients can branch on it.bridge.shutdown— written best-effort immediately before the process exits. Params:reason(stdin_closed,backpressure, orcancelled), matching the exit code.
Errors¶
Standard JSON-RPC codes:
| Code | Meaning |
|---|---|
-32700 |
Parse error. |
-32600 |
Invalid request, including request_too_large. |
-32601 |
Unknown method. |
-32602 |
Invalid or missing params. |
-32603 |
Internal bridge failure. |
Bridge-level codes: -32001 not_initialized, -32002 already_initialized.
Application errors use -32000 with data.ruCode carrying the host's error catalog
code and, when the failure came from an HTTP response, data.httpStatus. The
message mirrors the host's bounded error body rather than a reworded summary:
{"jsonrpc":"2.0","id":9,"error":{"code":-32000,"message":"{\"error_code\":\"approval_stale\",\"message\":\"Approval is missing, expired, or already used.\"}","data":{"ruCode":"approval_stale","httpStatus":409}}}
Codes such as approval_stale, workspace_trust_required, trust_failed,
reconcile_failed, full_access_confirmation_required,
invalid_payload_encoding and unsupported_payload_encoding all arrive this way. The
bridge does not retry, rewrite or fall back on host failures; the mapped code is the
original one.
-32602 can also carry data.ruCode when the rejection has a named cause: run.start
rejects an unknown preset with -32602 plus data.ruCode: "invalid_preset", and
policy.import maps file failures the same way (file_error and the policy codec's
own codes).
Security notes¶
- The bearer token never crosses the bridge. No method returns it;
host.statusexposes only the loopbackbase_url. run.outputis an explicit action. Payload bytes are fetched only when the client asks for a specificpayloadIdit already saw inpayload_ref, and are returned as base64. Nothing is fetched in the background.- Transient text is opt-in. Model deltas and tool output stay off the wire unless the
client attaches with
includeTransient: true— the same deliberate default as the--jsontrace renderer, which never carries raw text. - Fail closed. Oversized frames are rejected, the outbound queue is bounded, and a queue overflow exits instead of dropping a durable event silently.
TypeScript SDK¶
import { RuAgent } from "@ru/agent-sdk";
const ru = await RuAgent.start();
const run = await ru.runs.start({ workspace: "C:\\work\\repo", prompt: "fix the failing test" });
for await (const event of run.events()) {
console.log(event.sequence, event.event_type);
}
await ru.close();
The SDK spawns the bridge, manages request ids and cancellation, and surfaces
data.ruCode as a typed error field. It exposes host status, sessions, runs
(including trust, commands, reconciliation and output), subagent observation and
policy rules; policies.import and policies.remove require an explicit
confirmation. RuAgent.start() checks the methods handshake list against what
the wrapper can call and rejects with bridge_method_missing on drift. run.events() ends on a terminal event and
throws a bounded BridgeTransportError if the subscription ends first
(run.detached) or the bridge shuts down/exits, instead of waiting forever. See
sdk/ru-agent/README.md for the full API.
Subagent methods are read-only. Only the parent model's orchestration tools send,
cancel or apply. Generic child run mutations (including approval) are refused.
Pages use returned UTF-8 byte offsets and immutable result versions. Root
run.transient frames may contain subagent.changed hints; fetch snapshots after
attach/reconnect because hints are not durable. See Subagents for bounds and recovery.