Skip to content
Chapter 3 · Reference 3-10

@ru/agent-sdk

TypeScript client for the Ru agent RPC bridge. It spawns ru agent rpc as a child process, speaks newline-delimited JSON-RPC over stdio (protocol v1), and exposes typed session, run, policy and subagent handles, including streaming run events.

Current package version: 0.1.3, aligned with the product's 0.1.3 release line. It covers every method the v1 bridge advertises; the handshake rejects a bridge that is missing any method the wrapper can call.

Requirements

  • Node.js >= 22
  • A Ru CLI binary reachable either as ru on PATH or through the RU_CLI_PATH environment variable (or pass command explicitly).

Usage

import { RuAgent } from "@ru/agent-sdk";

const ru = await RuAgent.start();

const sessionId = await ru.sessions.create();
const run = await ru.runs.start({ workspace: "C:\\work\\repo", prompt: "fix the failing test", sessionId });

for await (const event of run.events()) {
  console.log(event.sequence, event.event_type, event.status ?? "");
}

await run.cancel();
await ru.close();

Host and policy rules

const status = await ru.host.status();          // { ready, base_url }
const rules = await ru.policies.list("global");
await ru.policies.import("C:\\policies.json", true);
await ru.policies.remove(rules[0]!.rule_id, true);

host.status() reports readiness and the loopback base URL; it never returns the bearer token. policies.list(scope?) returns the host's policy rules. import(file, true) reads a v1 policy JSON file through the bridge, and remove(ruleId, true) deletes one rule. The literal true is part of the TypeScript signatures, so a caller cannot confirm a destructive policy change by accident; the bridge enforces the same requirement.

Run controls

await run.trust(true);                       // approve; the default false denies
await run.command("/status");                // bounded run command
await run.reconcile("applied", hash);        // applied | not_applied | unknown_continue

trust answers a pending workspace-trust challenge. command dispatches a bounded run command. reconcile resolves a durable reconciliation request; both the outcome and the 64-character snapshot hash are required.

RuAgent.start accepts command, args, agentArgs, cwd, and env to control how the bridge process is spawned, and rejects the handshake if the bridge does not advertise every method the wrapper can call. run.events() can also stream transient events ({ includeTransient: true }) and replay from a sequence number ({ afterSequence: n }). It ends on a terminal event; if the bridge detaches the subscription first (run.detached) or shuts down, the iterator throws a bounded BridgeTransportError instead of hanging.

On Windows, .cmd/.bat commands use explicit cmd.exe quoting with delayed expansion disabled. Paths with spaces, Unicode and ordinary literal arguments are supported. Batch command paths containing percent signs, quotes or newlines, and arguments containing %, ^, &, |, <, >, quotes or newlines are rejected before spawning; use an executable command for those literal values.

Each iterator buffers at most 4,096 notifications and 8 MiB of serialized UTF-8, including notifications arriving before attach acknowledgement. A slow consumer that exceeds either limit stops buffering and receives a BridgeTransportError carrying lastDeliveredSequence; use it as afterSequence on a new iterator to replay durable events. Buffered events are discarded on overflow, and transient events are not replayable. This does not cancel the run. Known peer subscriptions do not consume its buffer. Cleanup detaches only this subscription when peers exist; if attach acknowledgement is still pending, cleanup waits for its subscription ID without delaying the overflow error. An invalid attach response also throws BridgeTransportError. If peers exist and the response omits a usable subscription ID, the SDK cannot detach that unknown subscription safely, so it closes the bridge transport. Other iterators on that transport fail too; this does not cancel their Host runs.

Complete and partial RPC frames are bounded to 1 MiB + 64 KiB of UTF-8 before parsing. Invalid envelopes, including null roots and non-object notification params, close the transport and fail pending requests and iterators.

RPC request deadlines include time queued behind stdin backpressure. Requests are correlated before their frames are written, so a response arriving before drain is retained. An unanswered write that remains backpressured through its deadline closes the transport and rejects queued requests; expired queued frames are removed. A completed response cancels that request's write deadline. This does not send run.cancel to the shared Host.

Protocol

This SDK targets RPC protocol v1 and wraps its full method surface: sessions, runs, subagents, host status and policy rules. The wire contract (methods, notifications, and error codes) is documented in docs/operations/rpc.md.

Development

npm install
npm test        # vitest
npm run typecheck
npm run build   # tsup -> dist/

TypeScript is pinned to 6.x: tsup 9 emits dist/index.d.ts through the TypeScript compiler API, which TypeScript 7 no longer ships. The CLI and typecheck run on 6.0.3.

Subagent observation

const snapshot = await run.subagents.list();
for (const child of snapshot.agents) {
  console.log(child.agent_id, child.role, child.attempts.at(-1)?.model);
}

const child = snapshot.agents[0];
if (child) {
  const result = child.results.at(-1);
  if (result) {
    const page = await run.subagents.get(child.agent_id, { resultVersion: result.result_version });
    console.log(page.result?.text, page.result?.next_offset);
  }
}

ru.subagents(rootRunId) also works for a retained root. get supports resultVersion, UTF-8 byte offset and a 4–32,768 byte limit; continue using next_offset until null, keeping the exact version. Users only observe children; the parent model alone sends follow-ups, cancels and applies results. Generic child run mutations and approvals are also refused. Children inherit the exact parent selection. Another model requires an explicit user prompt and a matching signed-in provider catalog. Unknown or incomplete token usage remains nullable. With events({ includeTransient: true }), root transient frames can carry subagent.changed hints. Always fetch list on attach/reconnect; hints are not replayed and detaching the stream never cancels Host work.