ruicode 0.0.0-stage → 0.67.1

package/README.md

@@ -1,3 +1,151 @@
-# Temporary Holding Version
+# ruicode (TypeScript client for Rui)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Starts a Rui Host as a child of your process and talks to it over its local socket.
+
+```ts
+import { Rui } from "ruicode";
+
+const rui = await Rui.connect({
+	database: "/var/lib/myapp/rui-store",
+	provider: { baseUrl: "https://api.openai.com/v1", key: process.env.OPENAI_API_KEY },
+	tools: [{ name: "drift", url: "http://127.0.0.1:3000/mcp", bearerToken: process.env.MCP_TOKEN, callTimeoutMs: 30000 }],
+});
+rui.on("exit", ({ code, signal, restarting }) => console.warn("rui exited", { code, signal, restarting }));
+// ...
+await rui.close();
+```
+
+## Install
+
+Run `npm install ruicode`.
+The `ruicode` package carries the client.
+The `rui` executable comes from the platform package beside it
+(`ruicode-linux-x64`, `ruicode-linux-arm64` or `ruicode-darwin-arm64`, installed as optional dependencies), else from `rui` on `PATH`.
+Pass `binary` to `Rui.connect` to name one yourself.
+
+Bundled and custom binaries and their child Host launch are application-owned.
+Standalone client Upgrade does not mutate npm packages or blindly stop an application-owned Host, and reports installation separately from activation.
+There is no HTTP installer endpoint or background update polling; update the application's dependencies and lifecycle explicitly.
+
+`Rui.connect` writes the Store, the provider settings, MCP bearer tokens and a private runtime directory to the child's stdin.
+The optional `provider.caFile` names a PEM file to trust exclusively for that provider instead of system CAs, on macOS as on Linux (for example `provider: { baseUrl: "https://localhost:8443/v1", key: "local-key", caFile: "/path/to/ca.pem" }`).
+It travels in the launch frame, not argv or the environment; do not add `--provider-ca-file` to a launched Host.
+The path must be nonempty, contain no NUL bytes and fit the platform's path limit; relative paths use the Host's working directory, and a file that cannot be loaded or a peer that cannot be verified fails without falling back to system trust.
+`database` accepts a SQLite directory or a `mysql://USER:PASSWORD@HOST[:PORT]/DATABASE` URL.
+For a Unix socket, use its percent-encoded absolute path in place of HOST; TCP verifies TLS.
+For MySQL TCP URLs, the only query option is `ssl-ca=/absolute/path/to/ca.pem` (the path may be percent-encoded), which replaces system trust with that PEM bundle alone; socket URLs and verification-disabling options are refused.
+The MySQL database must already contain the DDL from `rui store schema --engine mysql`.
+The key, tokens and MySQL URL never reach the child's argv, environment or disk.
+Readiness discovers the MySQL Store's stable opaque id, which the client uses on requests instead of the URL.
+MySQL readiness also reports `innodb_doublewrite`, including `OFF`.
+The child gets only `PATH`, `HOME` and `TMPDIR` from your environment.
+Shell commands the agent runs execute as your user; Rui is not a sandbox.
+
+The child lives as long as its stdin stays open, so it stops when your process ends.
+If it exits on its own, the client restarts it, waiting 0.5 s and doubling up to 30 s, and sends calls in flight again once the new Host is ready.
+
+Errors:
+
+- `RuiStartError { code, message }`: Rui refused to open, for example `store_locked` once `lockWaitMs` (default 120 s) has passed.
+- `RuiRequestError { code }`: Rui rejected one request.
+- `RuiUnavailableError`: the child is gone.
+
+For `sessions.create` and `session.update`, `mcp_server_unavailable` means a requested tool is unknown and at least one configured MCP server has no tools, including no saved copies.
+The error's `message` names the unavailable server(s) that may provide the name; it does not assert ownership.
+If every configured server has tools, an unknown name gets `unknown_tool` instead.
+Saved tool copies remain usable in specs even when their server is unreachable; calling such a tool can still fail with `mcp_server_unavailable` as a tool result.
+A creating Message uses the same request rule, and `start_agent` reports it as a tool error naming `spec.tools` rather than starting an agent.
+
+## Session feed
+
+`session.listActivity()` reads to the current end; `{ follow: true }` follows new entries.
+Feed entries are a discriminated union: `switch (entry.kind)` narrows to that wire row's fields.
+Only top-level field names become camelCase (for example `callOrdinal`); nested objects keep their wire spelling (for example `presentation.publication_position`).
+Text-bearing kinds add `text`, or `truncated: true` when the text exceeds 16 KiB; `contentBytes` gives its byte length.
+Use `session.readContent(entry)` or `readContentBytes(entry)` for the whole text.
+
+Following polls with backoff from 250 ms to 2 s only while the Session is busy.
+An empty page in `idle`, `finished`, `failed`, or `stopped` state with nothing queued puts the iterator to sleep **without a timer**.
+It wakes after a successful `send`, `update`, `decide`, `interrupt`, `stop`, `archive`, or `unarchive` through any handle for that Session ID on the same Rui instance, then starts polling again at 250 ms.
+Writes from another process to the same Store are **not noticed while idle** (nor are writes through another Rui instance).
+Pass an AbortSignal as `signal` to end the iterator immediately even while it sleeps.
+
+## Development
+
+`src/wire.ts` is generated from the repository's `openapi.json`, which the Host build emits from its wire types.
+
+```sh
+npm ci
+npm run generate   # after openapi.json changes
+npm run check      # wire.ts is fresh, and the package type-checks
+RUI_BINARY=../../zig-out/bin/rui npm test
+```
+
+`node scripts/pack.mjs <version> <outdir> <platform>=<executable> ...` builds the release tarballs (the compiled client and one package per platform).
+It publishes nothing; the first npm publish waits for the maintainer.
+
+The repository's `zig build ts-client` runs the tests against the Rui it builds.
+The real-Host feed test uses a local HTTPS provider and the `openssl` command to generate its temporary test certificate; no live provider credentials are needed.
+
+## Session settings
+
+`create` needs `model`, `effort`, `compactAt`, `tools` and `permissionMode`, and `workspace` when `tools` includes `bash`, or a `preset` name with optional overrides.
+`provider` may be left out when the Host serves one provider.
+`effort: null` sends no effort, so the provider uses its own; it is accepted only for a model Rui does not list.
+Updates may change the model within the Session's fixed provider; the Workspace also remains fixed.
+An omitted setting stays as it is.
+
+```ts
+const session = await rui.sessions.create({
+	model: "gpt-6.1-sol",
+	effort: "high",
+	compactAt: 244800,
+	tools: ["bash"],
+	permissionMode: "ask",
+	workspace: "/work/project",
+}, { idempotencyKey: "project:1" });
+await session.update({ compactAt: 200000 });
+await session.update({ model: "gpt-5.5" });
+```
+
+`await session.status()` reads the Current report: work `state` and `since`, `turn`, `operation`, `pendingMessages`, `parent`, `label`, `model`, `effort`, `tools`, `permissionMode`, `latestOutcome` and `archiveState`.
+Counts, times and Turn/Operation IDs stay decimal strings; absent targets, parents and outcomes are `null`.
+A separate ending is not in the report, so status does not invent one.
+`interrupt()` uses this status snapshot to select its exact model target.
+
+Presets are complete agent specs passed at connect and kept only in Host memory.
+Creation copies the preset, with every supplied field (including `null`) overriding it.
+
+```ts
+const rui = await Rui.connect({
+	database: "/var/lib/myapp/rui-store",
+	provider: { baseUrl: "https://api.openai.com/v1", key: process.env.OPENAI_API_KEY! },
+	presets: {
+		review: { model: "gpt-6.1-sol", effort: "low", compactAt: 100000, tools: [], permissionMode: "ask" },
+	},
+});
+const review = await rui.sessions.create({ preset: "review", instructions: "Review this patch" }, { idempotencyKey: "review:1" });
+await rui.close();
+```
+
+## Archive and restore
+
+Archive metadata is independent of work state. `archiveState` is `active`, `archiving` or `archived` in Session summaries and status.
+
+```ts
+const result = await session.archive({ idempotencyKey: "archive:1" });
+// result: { archived: true, completion: "pending" | "completed" }
+await session.unarchive({ idempotencyKey: "restore:1" });
+
+await rui.sessions.list();                       // active, including archiving
+await rui.sessions.list({ archive: "archived" }); // archived only
+await rui.sessions.list({ archive: "all" });      // all Sessions
+```
+
+`archive()` submits one durable intent that stops running and queued work, then archives after real settlement.
+An accepted intent can return `completion: "pending"`; acceptance does not mean stopped processes have retired.
+New Messages are rejected with `session_archiving` during settlement, and `unarchive()` is rejected with `archive_pending`.
+A later Message to an archived Session restores it transactionally before admitting new work.
+`unarchive()` restores only organization and never resumes stopped work.
+Replaying an archive request with its original key does not archive again after a later restore.
+Both methods notify local activity followers without submitting a Message or starting work.

package/dist/binary.d.ts

@@ -0,0 +1,10 @@
+/** The platform packages, by `process.platform` and `process.arch` (D127, D186). */
+export declare const PLATFORM_PACKAGES: Record<string, Record<string, string>>;
+export interface BinaryLookup {
+    platform?: string;
+    arch?: string;
+    /** A file URL or path that module resolution starts from. Default: this module. */
+    from?: string;
+}
+/** The executable to start: `binary` if given, else the installed platform package's, else `rui` on PATH. */
+export declare function resolveBinary(binary: string | undefined, lookup?: BinaryLookup): string;

package/dist/binary.js

@@ -0,0 +1,23 @@
+// Where the `rui` executable comes from when the caller names none: the
+// platform package installed beside this one (D125, D127), else PATH.
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+/** The platform packages, by `process.platform` and `process.arch` (D127, D186). */
+export const PLATFORM_PACKAGES = {
+    linux: { x64: "ruicode-linux-x64", arm64: "ruicode-linux-arm64" },
+    darwin: { arm64: "ruicode-darwin-arm64" },
+};
+/** The executable to start: `binary` if given, else the installed platform package's, else `rui` on PATH. */
+export function resolveBinary(binary, lookup = {}) {
+    if (binary !== undefined)
+        return binary;
+    const name = PLATFORM_PACKAGES[lookup.platform ?? process.platform]?.[lookup.arch ?? process.arch];
+    if (name === undefined)
+        return "rui";
+    try {
+        return join(dirname(createRequire(lookup.from ?? import.meta.url).resolve(`${name}/package.json`)), "bin", "rui");
+    }
+    catch {
+        return "rui";
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,97 @@
+import { EventEmitter } from "node:events";
+import { SessionNotifications } from "./notifications.ts";
+import { RuiStartError } from "./errors.ts";
+import { Session, Sessions, type AgentSpec, type ModelSummary } from "./sessions.ts";
+import { type ReplyLimits } from "./transport.ts";
+import type { components } from "./wire.ts";
+type Schemas = components["schemas"];
+export interface McpServer {
+    name: string;
+    url: string;
+    bearerToken: string;
+    callTimeoutMs: number;
+}
+export interface ConnectOptions {
+    /** The MCP servers whose tools Sessions may name. */
+    tools?: McpServer[];
+    /** The Store: a SQLite directory or a mysql:// URL, sent only in the stdin launch frame.
+     * MySQL TCP accepts only ssl-ca=<absolute PEM path> (percent encoding allowed) for exclusive CA trust; sockets refuse it and verification cannot be disabled. */
+    database: string;
+    /** The OpenAI-compatible provider. Only the key Adapter is offered to a launched Host (D149). */
+    provider: {
+        baseUrl: string;
+        key: string;
+        /** Trust only this PEM file for this provider, instead of system CAs. Sent in the launch frame. */
+        caFile?: string;
+    };
+    /** How many Turns may run at once. Left out, the Host picks its default. */
+    activeCapacity?: number;
+    /** Named creation specs, held only by this Host. No default preset is selected. */
+    presets?: Record<string, AgentSpec>;
+    /** How long connect keeps retrying while another Host holds the Store (D183, D198). Default 120 000. */
+    lockWaitMs?: number;
+    /** Opens the Host with Turns held, as if `rui.pause()` had just run (D196); `rui.resume()` lifts it. A restarted Host opens paused again. */
+    paused?: boolean;
+    /** The `rui` executable. Default: the one from the installed platform package, else `rui` on PATH. */
+    binary?: string;
+}
+/** Fires on every child exit, including one the client restarts from (D129). */
+export interface ExitEvent {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    restarting: boolean;
+}
+type HostInfo = components["schemas"]["HostInfoReply"];
+interface Launch {
+    binary: string;
+    frame: Schemas["LaunchFrame"];
+    socketPath: string;
+    store: string;
+    env: NodeJS.ProcessEnv;
+}
+export declare class Rui extends EventEmitter<{
+    exit: [ExitEvent];
+}> {
+    #private;
+    /** Local Session write notifications, shared by every handle. Internal. */
+    readonly activity: SessionNotifications;
+    /** Create and list Sessions. */
+    readonly sessions: Sessions;
+    private constructor();
+    /** Starts Rui as a child of this process and resolves once it is ready. */
+    static connect(options: ConnectOptions): Promise<Rui>;
+    /** A handle on an existing Session. Does no I/O: an unknown id fails on the first call (D16). */
+    getSession(id: string): Session;
+    /** The models each provider offers. */
+    models(): Promise<ModelSummary[]>;
+    /** Holds every new Turn until `resume`. Running work continues. */
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    /**
+     * Closes the child's stdin and resolves once it has exited, bounded by the
+     * Host's 10 s shutdown (D129). Later calls fail with RuiUnavailableError.
+     */
+    close(): Promise<void>;
+    /**
+     * Sends one request to the ready Host. A call that finds the child gone
+     * waits for the restarted Host and is sent once more. Internal: the
+     * package's calls are built on it.
+     */
+    call(path: string, body: string, environment?: Buffer, limits?: ReplyLimits): Promise<Buffer>;
+    /**
+     * Sends one request built for the Host's Store. `build` receives the
+     * canonical Store name the Host reported at readiness. Internal: the
+     * package's calls are built on it.
+     */
+    exchange(path: string, build: (store: string) => string, environment?: Buffer, limits?: ReplyLimits): Promise<Buffer>;
+    /** The running child's process id. Internal. */
+    get pid(): number | undefined;
+    /** The latest host-info reply. Internal. */
+    get hostInfo(): HostInfo | undefined;
+}
+export declare function launchFor(options: ConnectOptions, runtimeDir: string): Launch;
+/** One length-prefixed JSON frame: a 4-byte big-endian length, then UTF-8 JSON (D130). */
+export declare function encodeFrame(frame: Schemas["LaunchFrame"]): Buffer;
+/** The refusal a child wrote as its one stdout line, `{"rui_start_error":{code,message}}` (D211). */
+export declare function startError(output: string): RuiStartError | undefined;
+export {};

package/dist/client.js

@@ -0,0 +1,370 @@
+// Rui.connect starts the Host as a child of this process, hands it the launch
+// frame on stdin and waits until it answers host-info on the socket in its
+// private runtimeDir (D107, D112, D130, D131). The child lives as long as its
+// stdin stays open (D5, D118). A child that exits on its own is restarted with
+// capped backoff, and calls in flight are retried once the new Host is ready;
+// every write carries a request key, so a retry is safe (D118, D129).
+import { spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { mkdtemp, realpath, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { SessionNotifications } from "./notifications.js";
+import { resolveBinary } from "./binary.js";
+import { RuiStartError, RuiUnavailableError } from "./errors.js";
+import { agentSpec, models, Session, Sessions, setPaused } from "./sessions.js";
+import { ConnectionError, post, WIRE_VERSION } from "./transport.js";
+const FRAME_VERSION = 1;
+const SOCKET_NAME = "rui.sock";
+const DEFAULT_LOCK_WAIT_MS = 120_000;
+const LOCK_RETRY_MS = 500;
+const FIRST_RESTART_MS = 500;
+const MAX_RESTART_MS = 30_000;
+/** The Host bounds its own shutdown at 10 s (D118); this leaves room for the exit to arrive. */
+const CLOSE_GRACE_MS = 15_000;
+const READY_POLL_MS = 25;
+/** How long a refused connection waits for the child's exit before it counts as unanswered. */
+const EXIT_NOTICE_MS = 2_000;
+/** Refusals a restart cannot fix: the same frame would be refused again. */
+const RETRYABLE_START_CODES = new Set(["store_locked"]);
+/** A failed start, with the child's exit when there was a child. */
+class AttemptFailed extends Error {
+    error;
+    exit;
+    constructor(error, exit) {
+        super(error.message);
+        this.error = error;
+        this.exit = exit;
+    }
+}
+export class Rui extends EventEmitter {
+    #launch;
+    #runtimeDir;
+    #host;
+    /** The child of the latest start, ready or not. */
+    #child;
+    #waiters = [];
+    #backoff = FIRST_RESTART_MS;
+    #restart;
+    #closing;
+    #dead;
+    /** Local Session write notifications, shared by every handle. Internal. */
+    activity = new SessionNotifications();
+    /** Create and list Sessions. */
+    sessions = new Sessions(this);
+    constructor(launch, runtimeDir, host) {
+        super();
+        this.#launch = launch;
+        this.#runtimeDir = runtimeDir;
+        this.#adopt(host);
+    }
+    /** Starts Rui as a child of this process and resolves once it is ready. */
+    static async connect(options) {
+        const runtimeDir = await mkdtemp(join(tmpdir(), "rui-"));
+        try {
+            const launch = launchFor(options, runtimeDir);
+            const deadline = Date.now() + (options.lockWaitMs ?? DEFAULT_LOCK_WAIT_MS);
+            for (;;) {
+                try {
+                    return new Rui(launch, runtimeDir, await start(launch, () => { }));
+                }
+                catch (failure) {
+                    const error = failure instanceof AttemptFailed ? failure.error : failure;
+                    const remaining = deadline - Date.now();
+                    if (!(error instanceof RuiStartError && error.code === "store_locked") || remaining <= 0)
+                        throw error;
+                    await sleep(Math.min(LOCK_RETRY_MS, remaining));
+                }
+            }
+        }
+        catch (error) {
+            await rm(runtimeDir, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    /** A handle on an existing Session. Does no I/O: an unknown id fails on the first call (D16). */
+    getSession(id) {
+        return new Session(this, id);
+    }
+    /** The models each provider offers. */
+    models() {
+        return models(this);
+    }
+    /** Holds every new Turn until `resume`. Running work continues. */
+    pause() {
+        return setPaused(this, true);
+    }
+    resume() {
+        return setPaused(this, false);
+    }
+    /**
+     * Closes the child's stdin and resolves once it has exited, bounded by the
+     * Host's 10 s shutdown (D129). Later calls fail with RuiUnavailableError.
+     */
+    close() {
+        this.#closing ??= this.#close();
+        return this.#closing;
+    }
+    async #close() {
+        clearTimeout(this.#restart);
+        this.#fail(new RuiUnavailableError("the Rui client is closed"));
+        const child = this.#child;
+        this.#host = undefined;
+        if (child && child.exitCode === null && child.signalCode === null) {
+            const exited = exitOf(child);
+            child.stdin?.end();
+            const timer = setTimeout(() => child.kill("SIGKILL"), CLOSE_GRACE_MS);
+            const exit = await exited;
+            clearTimeout(timer);
+            this.emit("exit", { ...exit, restarting: false });
+        }
+        await rm(this.#runtimeDir, { recursive: true, force: true });
+    }
+    /**
+     * Sends one request to the ready Host. A call that finds the child gone
+     * waits for the restarted Host and is sent once more. Internal: the
+     * package's calls are built on it.
+     */
+    async call(path, body, environment, limits) {
+        let retried = false;
+        for (;;) {
+            const host = await this.#ready();
+            try {
+                return await post({
+                    socketPath: this.#launch.socketPath,
+                    path,
+                    body,
+                    instance: host.instance,
+                    ...(environment ? { environment } : {}),
+                    ...(limits ? { limits } : {}),
+                });
+            }
+            catch (error) {
+                if (!(error instanceof ConnectionError))
+                    throw error;
+                const gone = await Promise.race([host.exited.then(() => true), sleep(EXIT_NOTICE_MS, false)]);
+                if (!gone || retried)
+                    throw new RuiUnavailableError("the Rui Host did not answer", { cause: error });
+                retried = true;
+            }
+        }
+    }
+    /**
+     * Sends one request built for the Host's Store. `build` receives the
+     * canonical Store name the Host reported at readiness. Internal: the
+     * package's calls are built on it.
+     */
+    async exchange(path, build, environment, limits) {
+        const host = await this.#ready();
+        return this.call(path, build(host.info.store), environment, limits);
+    }
+    /** The running child's process id. Internal. */
+    get pid() {
+        return this.#host?.child.pid;
+    }
+    /** The latest host-info reply. Internal. */
+    get hostInfo() {
+        return this.#host?.info;
+    }
+    #ready() {
+        if (this.#host)
+            return Promise.resolve(this.#host);
+        const failed = this.#dead ?? (this.#closing ? new RuiUnavailableError("the Rui client is closed") : undefined);
+        if (failed)
+            return Promise.reject(failed);
+        this.#restart?.ref();
+        return new Promise((resolve, reject) => this.#waiters.push({ resolve, reject }));
+    }
+    #adopt(host) {
+        this.#host = host;
+        this.#child = host.child;
+        this.#backoff = FIRST_RESTART_MS;
+        for (const waiter of this.#waiters.splice(0))
+            waiter.resolve(host);
+        void host.exited.then((exit) => {
+            if (this.#closing || this.#host !== host)
+                return;
+            this.#host = undefined;
+            this.emit("exit", { ...exit, restarting: true });
+            this.#scheduleRestart();
+        });
+    }
+    #fail(error) {
+        this.activity.fail(error);
+        for (const waiter of this.#waiters.splice(0))
+            waiter.reject(error);
+    }
+    #scheduleRestart() {
+        // Once close has begun nothing may start again, whoever asked (an exit listener may close).
+        if (this.#closing)
+            return;
+        const delay = this.#backoff;
+        this.#backoff = Math.min(this.#backoff * 2, MAX_RESTART_MS);
+        this.#restart = setTimeout(() => void this.#restartNow(), delay);
+        // An idle client does not keep the process alive; a call waiting for the restart does (see #ready).
+        if (this.#waiters.length === 0)
+            this.#restart.unref();
+    }
+    async #restartNow() {
+        try {
+            const host = await start(this.#launch, (child) => {
+                this.#child = child;
+            });
+            if (this.#closing) {
+                host.child.stdin?.end();
+                return;
+            }
+            this.#adopt(host);
+        }
+        catch (failure) {
+            if (this.#closing)
+                return;
+            const error = failure instanceof AttemptFailed ? failure.error : failure;
+            const exit = failure instanceof AttemptFailed ? failure.exit : undefined;
+            const retryable = error instanceof RuiUnavailableError || (error instanceof RuiStartError && RETRYABLE_START_CODES.has(error.code));
+            if (exit)
+                this.emit("exit", { ...exit, restarting: retryable });
+            this.#fail(new RuiUnavailableError(`the Rui Host could not restart: ${error.message}`, { cause: error }));
+            if (retryable)
+                return this.#scheduleRestart();
+            this.#dead = new RuiUnavailableError(`the Rui Host cannot restart: ${error.message}`, { cause: error });
+        }
+    }
+}
+export function launchFor(options, runtimeDir) {
+    // A URL is passed through; anything else is a SQLite Store directory.
+    const store = /^[a-z][a-z0-9+.-]*:\/\//i.test(options.database) ? options.database : resolve(options.database);
+    const frame = {
+        v: FRAME_VERSION,
+        store,
+        runtimeDir,
+        ...(options.activeCapacity === undefined ? {} : { activeCapacity: options.activeCapacity }),
+        ...(options.paused ? { paused: true } : {}),
+        ...(options.presets === undefined ? {} : {
+            presets: Object.fromEntries(Object.entries(options.presets).map(([name, spec]) => [name, presetFor(spec)])),
+        }),
+        provider: {
+            kind: "openai_key", baseUrl: options.provider.baseUrl, key: options.provider.key,
+            ...(options.provider.caFile === undefined ? {} : { caFile: options.provider.caFile }),
+        },
+        // Only the Host's fields are copied: it refuses unknown ones.
+        mcpServers: (options.tools ?? []).map(({ name, url, bearerToken, callTimeoutMs }) => ({ name, url, bearerToken, callTimeoutMs })),
+    };
+    // The child gets only what it needs to find programs and its home (D185).
+    const env = {};
+    for (const name of ["PATH", "HOME", "TMPDIR"]) {
+        const value = process.env[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    return { binary: resolveBinary(options.binary), frame, socketPath: join(runtimeDir, SOCKET_NAME), store, env };
+}
+/** Presets and Session mutation requests use the same wire writer. */
+function presetFor(spec) {
+    return agentSpec(spec);
+}
+/** Starts one child and resolves once it answers host-info, or throws AttemptFailed. */
+async function start(launch, spawned) {
+    let child;
+    try {
+        child = spawn(launch.binary, ["host", "serve", "--launch-frame"], {
+            env: launch.env,
+            stdio: ["pipe", "pipe", "inherit"],
+        });
+    }
+    catch (error) {
+        throw new AttemptFailed(new RuiUnavailableError(`could not start ${launch.binary}`, { cause: error }), undefined);
+    }
+    spawned(child);
+    const stdout = [];
+    child.stdout?.on("data", (chunk) => stdout.push(chunk));
+    const outputEnded = new Promise((done) => child.stdout?.once("close", done));
+    const launchError = new Promise((done) => child.once("error", done));
+    const exited = exitOf(child);
+    // The child must not keep this process alive; its stdin closing is how it learns this process ended.
+    child.unref();
+    child.stdout?.unref();
+    child.stdin?.unref();
+    child.stdin?.on("error", () => { });
+    child.stdin?.write(encodeFrame(launch.frame));
+    let ended;
+    void exited.then((exit) => (ended ??= exit));
+    void launchError.then((error) => (ended ??= error));
+    while (ended === undefined) {
+        const info = await probe(launch).catch((error) => {
+            if (error instanceof ConnectionError)
+                return undefined;
+            child.kill("SIGKILL");
+            throw new AttemptFailed(error, undefined);
+        });
+        if (info)
+            return { child, instance: info.instance, info, exited };
+        await sleep(READY_POLL_MS);
+    }
+    if (ended instanceof Error) {
+        throw new AttemptFailed(new RuiUnavailableError(`could not start ${launch.binary}: ${ended.message}`, { cause: ended }), undefined);
+    }
+    // The refusal line is written before the exit; give the pipe a moment to deliver it.
+    await Promise.race([outputEnded, sleep(1_000)]);
+    const refusal = startError(Buffer.concat(stdout).toString("utf8"));
+    throw new AttemptFailed(refusal ?? new RuiUnavailableError(`rui exited before it was ready (code ${ended.code}, signal ${ended.signal})`), ended);
+}
+async function probe(launch) {
+    try {
+        await stat(launch.socketPath);
+    }
+    catch {
+        return undefined;
+    }
+    // The Host names a SQLite Store by its canonical path, which exists once the socket does.
+    let store = launch.store.startsWith("mysql://") ? "" : launch.store;
+    if (store !== "" && !store.includes("://")) {
+        try {
+            store = await realpath(store);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const body = JSON.stringify({
+        version: WIRE_VERSION,
+        kind: "host_info",
+        store,
+    });
+    const reply = await post({ socketPath: launch.socketPath, path: "/v1/host-info", body });
+    return JSON.parse(reply.toString("utf8"));
+}
+/** One length-prefixed JSON frame: a 4-byte big-endian length, then UTF-8 JSON (D130). */
+export function encodeFrame(frame) {
+    const json = Buffer.from(JSON.stringify(frame));
+    const out = Buffer.alloc(4 + json.length);
+    out.writeUInt32BE(json.length, 0);
+    json.copy(out, 4);
+    json.fill(0);
+    return out;
+}
+/** The refusal a child wrote as its one stdout line, `{"rui_start_error":{code,message}}` (D211). */
+export function startError(output) {
+    for (const line of output.split("\n").reverse()) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            const refusal = parsed?.rui_start_error;
+            if (refusal && typeof refusal.code === "string") {
+                return new RuiStartError(refusal.code, typeof refusal.message === "string" ? refusal.message : refusal.code);
+            }
+        }
+        catch {
+            // Not the refusal line.
+        }
+    }
+    return undefined;
+}
+function exitOf(child) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        return Promise.resolve({ code: child.exitCode, signal: child.signalCode });
+    }
+    return new Promise((done) => child.once("exit", (code, signal) => done({ code, signal })));
+}