@rynx-ai/runtime 0.1.0

package/dist/runner/manager.js

@@ -0,0 +1,458 @@
+/**
+ * Parent-side runner orchestrator. Replaces {@link LocalAgentHost} at the
+ * composition root as the live co-drive + capability surface, but holds **no
+ * execution backend** of its own: it spawns one runner child per session
+ * (`localThreadId`) that brings up the session's live forwarder + vendor TUI,
+ * forwards per-thread capabilities to a shared capability runner, and answers
+ * status / model-list locally without a backend.
+ *
+ * The process boundary carries no live objects: the parent drives a session over
+ * the runner transport (`live.ensure` / `inject` / `live.interrupt` + terminal
+ * attach), and the child mirrors that session's canonical events back as
+ * {@link SessionEvent}s.
+ *
+ * Today the only transport is local stdio (a spawned child); a remote tunnel
+ * transport drops in here later without touching `ConversationRuntime` or any
+ * channel.
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import readline from "node:readline";
+import { fileURLToPath } from "node:url";
+import { AgentRuntimeError, } from "@rynx-ai/core";
+import { listRuntimeModels } from "../models-catalog.js";
+import { probeRuntimeStatus } from "../runtime-status.js";
+import { fromWireError, } from "./protocol.js";
+import { StdioRunnerTransport } from "./transport.js";
+/** Routing key for the shared capability runner (slash-command RPCs). */
+const CAP_KEY = "__cap__";
+/** Max stderr lines retained per handle for the crash exit-report tail. */
+const STDERR_TAIL_LINES = 40;
+class ManagedTerminal {
+    attachId;
+    sendMsg;
+    ready;
+    dataListener;
+    exitListener;
+    resolveReady;
+    rejectReady;
+    constructor(attachId, sendMsg) {
+        this.attachId = attachId;
+        this.sendMsg = sendMsg;
+        this.ready = new Promise((resolve, reject) => {
+            this.resolveReady = resolve;
+            this.rejectReady = reject;
+        });
+        // Never surface an unhandled rejection if no caller awaits `ready`.
+        void this.ready.catch(() => undefined);
+    }
+    onData(listener) {
+        this.dataListener = listener;
+    }
+    onExit(listener) {
+        this.exitListener = listener;
+    }
+    write(data) {
+        this.sendMsg({ t: "term.input", attachId: this.attachId, dataB64: Buffer.from(data, "utf8").toString("base64") });
+    }
+    resize(cols, rows) {
+        this.sendMsg({ t: "term.resize", attachId: this.attachId, cols, rows });
+    }
+    close() {
+        this.sendMsg({ t: "term.close", attachId: this.attachId });
+    }
+    // ── internal (driven by onChildMessage) ──
+    _opened(role) {
+        this.resolveReady({ role });
+    }
+    _data(dataB64) {
+        this.dataListener?.(Buffer.from(dataB64, "base64").toString("utf8"));
+    }
+    _exit(exitCode) {
+        this.exitListener?.({ exitCode });
+    }
+    _fail(message) {
+        this.rejectReady(new Error(message));
+        this.exitListener?.({ exitCode: 1 });
+    }
+}
+export class RunnerManager {
+    config;
+    sessionStore;
+    runnerEntry;
+    idleTtlMs;
+    spawn;
+    childEnv;
+    now;
+    defaultRuntime;
+    handles = new Map();
+    reapTimer;
+    /** Sink for mirrored {@link SessionEvent}s from every session's forwarder. */
+    mirrorListener = null;
+    /** Sink for session rotations (claude `/clear`·`/fork`) — server records meta. */
+    rotateListener = null;
+    /** Session keys with a live codex forwarder — never reaped while present. */
+    liveSessionKeys = new Set();
+    constructor(opts) {
+        this.config = opts.config;
+        this.sessionStore = opts.sessionStore;
+        this.runnerEntry = opts.runnerEntry ?? defaultRunnerEntry();
+        this.idleTtlMs = opts.idleTtlMs ?? 300_000;
+        this.spawn = opts.spawn ?? nodeSpawn;
+        this.childEnv = opts.childEnv ?? {};
+        this.now = opts.now ?? (() => Date.now());
+        this.defaultRuntime = opts.config.AGENT_RUNTIME ?? "codex";
+        const reapIntervalMs = opts.reapIntervalMs ?? 60_000;
+        if (reapIntervalMs > 0) {
+            this.reapTimer = setInterval(() => this.reapIdle(), reapIntervalMs);
+            this.reapTimer.unref?.();
+        }
+        else {
+            this.reapTimer = null;
+        }
+    }
+    // ── Live terminal ───────────────────────────────────────────────────────────
+    /**
+     * Open a live terminal on the session's runner child (spawning it if needed).
+     * Phase C hosts one terminal ("main") per session; the returned handle is a
+     * single attach client — `owner` (read-write) or a downgraded `read-only`
+     * viewer per the child's ownership rule. Not part of `AgentExecutor`; the WS
+     * bridge calls it directly.
+     */
+    openTerminal(localThreadId, opts) {
+        const handle = this.getOrSpawn(localThreadId);
+        handle.lastUsedAt = this.now();
+        const attachId = randomUUID();
+        const terminal = new ManagedTerminal(attachId, (msg) => handle.transport.send(msg));
+        handle.terminals.set(attachId, terminal);
+        handle.transport.send({
+            t: "term.open",
+            attachId,
+            // Unique per session so two sessions' tmux servers never share a socket.
+            terminalId: `${localThreadId}-main`,
+            localThreadId,
+            role: opts.role,
+            cwd: opts.cwd,
+            cols: opts.cols,
+            rows: opts.rows,
+            ...(opts.command ? { command: opts.command } : {}),
+            ...(opts.args ? { args: opts.args } : {}),
+        });
+        return terminal;
+    }
+    /**
+     * Register the sink for mirrored {@link SessionEvent}s produced by every
+     * session's persistent codex forwarder (web- AND TUI-initiated turns). The
+     * server wires this to `persistSessionEvent` (bus + canonical log).
+     */
+    onMirror(listener) {
+        this.mirrorListener = listener;
+    }
+    /** Register the sink for session rotations (claude `/clear`·`/fork`): the server
+     *  records the new session's meta (carry-over agent/model/title). */
+    onRotate(listener) {
+        this.rotateListener = listener;
+    }
+    /**
+     * Eagerly bring up a session's codex-native live view (persistent forwarder +
+     * detached `codex --remote` TUI) in its runner child, spawning the runner if
+     * needed. Idempotent. Resolves true once the codex thread is bound; false for a
+     * non-codex / non-live session (the caller then uses the normal run path).
+     */
+    ensureLiveSession(localThreadId, opts) {
+        const handle = this.getOrSpawn(localThreadId);
+        handle.lastUsedAt = this.now();
+        this.liveSessionKeys.add(localThreadId);
+        const reqId = randomUUID();
+        return new Promise((resolve) => {
+            handle.live.set(reqId, (res) => resolve(res.ok ?? false));
+            handle.transport.send({
+                t: "live.ensure",
+                reqId,
+                localThreadId,
+                ...(opts?.cwd ? { cwd: opts.cwd } : {}),
+                ...(opts?.cols ? { cols: opts.cols } : {}),
+                ...(opts?.rows ? { rows: opts.rows } : {}),
+                ...(opts?.runtime ? { runtime: opts.runtime } : {}),
+                ...(opts?.agentName ? { agentName: opts.agentName } : {}),
+                ...(opts?.agentSpec ? { agentSpec: opts.agentSpec } : {}),
+            });
+        });
+    }
+    /**
+     * Inject a user turn into a session's live codex thread — omnigent's
+     * single-writer web send (`turn/start` / `turn/steer`); the forwarder mirrors
+     * all output. Resolves true when the app-server accepted the turn, false when
+     * the session has no live forwarder (caller falls back to the run path).
+     */
+    injectMessage(localThreadId, text) {
+        const handle = this.getOrSpawn(localThreadId);
+        handle.lastUsedAt = this.now();
+        const reqId = randomUUID();
+        return new Promise((resolve) => {
+            handle.live.set(reqId, (res) => resolve(res.outcome ?? "failed"));
+            handle.transport.send({ t: "inject", reqId, localThreadId, text });
+        });
+    }
+    /**
+     * Interrupt a session's active live turn — the web Stop button (codex
+     * `turn/interrupt`, claude Escape). Best-effort: resolves false with NO spawn
+     * when the session has no live runner (nothing to interrupt).
+     */
+    interruptLiveSession(localThreadId) {
+        const handle = this.handles.get(localThreadId);
+        if (!handle)
+            return Promise.resolve(false);
+        handle.lastUsedAt = this.now();
+        const reqId = randomUUID();
+        return new Promise((resolve) => {
+            handle.live.set(reqId, (res) => resolve(res.ok ?? false));
+            handle.transport.send({ t: "live.interrupt", reqId, localThreadId });
+        });
+    }
+    /**
+     * Deliver a user's interactive-approval decision to the session's runner
+     * child (Phase D). Best-effort: no-op if the runner isn't live (the pending
+     * approval would have died with it). The child routes it to its codex client.
+     */
+    resolveApproval(localThreadId, approvalId, decision) {
+        const handle = this.handles.get(localThreadId);
+        if (!handle || handle.dead) {
+            return;
+        }
+        handle.transport.send({ t: "approval.resolve", localThreadId, approvalId, decision });
+    }
+    // ── AgentCapabilities ──────────────────────────────────────────────────────
+    async listModels(runtime) {
+        return listRuntimeModels(this.config, runtime ?? this.defaultRuntime);
+    }
+    // Per-thread caps run on the SESSION's own runner child (not the shared cap
+    // child) so they see that session's private CODEX_HOME (its rollout/thread).
+    getGoal(localThreadId) {
+        return this.forwardCap("getGoal", [localThreadId], localThreadId);
+    }
+    setGoal(localThreadId, objective) {
+        return this.forwardCap("setGoal", [localThreadId, objective], localThreadId);
+    }
+    clearGoal(localThreadId) {
+        return this.forwardCap("clearGoal", [localThreadId], localThreadId);
+    }
+    forkSession(currentLocalThreadId, newLocalThreadId) {
+        // Runs on the SOURCE session's child (its home has the source rollout to fork).
+        return this.forwardCap("forkSession", [currentLocalThreadId, newLocalThreadId], currentLocalThreadId);
+    }
+    /**
+     * Backend-free runtime readiness (not part of `AgentCapabilities`; surfaced for
+     * the control console). Never spawns a runner.
+     */
+    getStatus(options = {}) {
+        return probeRuntimeStatus(options.runtime ?? this.defaultRuntime, this.config, this.sessionStore);
+    }
+    /** Stop the runner bound to one session (if any), rejecting its in-flight work. */
+    stopRunner(localThreadId) {
+        const handle = this.handles.get(localThreadId);
+        if (!handle) {
+            return;
+        }
+        handle.transport.send({ t: "shutdown" });
+        handle.child.kill("SIGTERM");
+        this.failHandle(handle, "runner stopped");
+    }
+    /** Kill every runner. Call on server shutdown. */
+    async stop() {
+        if (this.reapTimer) {
+            clearInterval(this.reapTimer);
+        }
+        for (const handle of this.handles.values()) {
+            handle.transport.send({ t: "shutdown" });
+            handle.child.kill("SIGTERM");
+        }
+        this.handles.clear();
+    }
+    // ── internals ──────────────────────────────────────────────────────────────
+    /** Forward a capability to a runner child. Session-less caps (listModels/status)
+     *  use the shared `CAP_KEY` child; per-thread caps pass the session's key so they
+     *  run on that session's child (which owns its private CODEX_HOME). */
+    forwardCap(name, args, key = CAP_KEY) {
+        const handle = this.getOrSpawn(key);
+        const capId = randomUUID();
+        handle.lastUsedAt = this.now();
+        return new Promise((resolve, reject) => {
+            handle.caps.set(capId, { resolve: resolve, reject });
+            handle.transport.send({ t: "cap", capId, name, args });
+        });
+    }
+    getOrSpawn(key) {
+        this.reapIdle();
+        const existing = this.handles.get(key);
+        if (existing && !existing.dead) {
+            existing.lastUsedAt = this.now();
+            return existing;
+        }
+        const handle = this.spawnHandle(key);
+        this.handles.set(key, handle);
+        return handle;
+    }
+    spawnHandle(key) {
+        const args = this.runnerEntry.endsWith(".ts")
+            ? ["--import", "tsx", this.runnerEntry]
+            : [this.runnerEntry];
+        const child = this.spawn(process.execPath, args, {
+            stdio: ["pipe", "pipe", "pipe"],
+            // `RYNX_RUNNER_SESSION` = the child's session key (localThreadId, or `__cap__`
+            // for the shared capability child) so its LocalAgentHost scopes the private
+            // CODEX_HOME to this session.
+            env: { ...process.env, ...this.childEnv, RYNX_RUNNER_SESSION: key },
+        });
+        const transport = new StdioRunnerTransport(child.stdout, child.stdin);
+        const handle = {
+            key,
+            child,
+            transport,
+            stderr: [],
+            lastUsedAt: this.now(),
+            dead: false,
+            caps: new Map(),
+            terminals: new Map(),
+            live: new Map(),
+        };
+        transport.onMessage((msg) => this.onChildMessage(handle, msg));
+        if (child.stderr) {
+            const rl = readline.createInterface({ input: child.stderr, crlfDelay: Infinity });
+            rl.on("line", (line) => {
+                handle.stderr.push(line);
+                if (handle.stderr.length > STDERR_TAIL_LINES) {
+                    handle.stderr.shift();
+                }
+            });
+        }
+        child.on("error", (error) => this.failHandle(handle, error.message));
+        child.on("exit", (code, signal) => this.failHandle(handle, `runner exited (code=${code ?? "null"}${signal ? `, signal=${signal}` : ""})`));
+        return handle;
+    }
+    onChildMessage(handle, msg) {
+        switch (msg.t) {
+            case "ready":
+                return;
+            case "capResult": {
+                const pending = handle.caps.get(msg.capId);
+                handle.caps.delete(msg.capId);
+                if (!pending) {
+                    return;
+                }
+                if (msg.ok) {
+                    pending.resolve(msg.data);
+                }
+                else {
+                    pending.reject(fromWireError(msg.error));
+                }
+                return;
+            }
+            case "term.opened":
+                handle.terminals.get(msg.attachId)?._opened(msg.role);
+                return;
+            case "term.data":
+                handle.terminals.get(msg.attachId)?._data(msg.dataB64);
+                return;
+            case "term.exit": {
+                const terminal = handle.terminals.get(msg.attachId);
+                handle.terminals.delete(msg.attachId);
+                terminal?._exit(msg.exitCode);
+                return;
+            }
+            case "term.error": {
+                const terminal = handle.terminals.get(msg.attachId);
+                handle.terminals.delete(msg.attachId);
+                terminal?._fail(msg.message);
+                return;
+            }
+            case "mirror":
+                this.mirrorListener?.(msg.sessionId, msg.event);
+                return;
+            case "rotate": {
+                // Terminal transfer: alias the new session to THIS runner so its injection
+                // (and live/approval) route to the same child that still owns the pane.
+                this.handles.set(msg.to, handle);
+                this.liveSessionKeys.add(msg.to);
+                this.rotateListener?.({
+                    from: msg.from,
+                    to: msg.to,
+                    kind: msg.kind,
+                    ...(msg.agent ? { agent: msg.agent } : {}),
+                    ...(msg.model ? { model: msg.model } : {}),
+                    ...(msg.cwd ? { cwd: msg.cwd } : {}),
+                    ...(msg.parentSessionId ? { parentSessionId: msg.parentSessionId } : {}),
+                });
+                return;
+            }
+            case "live.ready":
+            case "interrupted":
+            case "injected": {
+                const resolve = handle.live.get(msg.reqId);
+                handle.live.delete(msg.reqId);
+                resolve?.(msg.t === "injected"
+                    ? { outcome: msg.outcome, error: msg.error }
+                    : { ok: msg.ok, error: msg.error });
+                return;
+            }
+        }
+    }
+    /** Mark a handle dead and reject every pending run/cap with the exit reason. */
+    failHandle(handle, reason) {
+        if (handle.dead) {
+            return;
+        }
+        handle.dead = true;
+        // Drop every key mapping to this handle — its launch key AND any rotation
+        // aliases (claude `/clear`·`/fork` terminal transfer).
+        for (const [key, h] of this.handles) {
+            if (h === handle)
+                this.handles.delete(key);
+        }
+        const tail = handle.stderr.join("\n");
+        const message = tail ? `${reason}\n--- runner log tail ---\n${tail}` : reason;
+        const error = new AgentRuntimeError(message, 500, "runner_crashed");
+        for (const pending of handle.caps.values()) {
+            pending.reject(error);
+        }
+        for (const terminal of handle.terminals.values()) {
+            terminal._fail(message);
+        }
+        for (const resolve of handle.live.values()) {
+            resolve({ ok: false, error: message });
+        }
+        handle.caps.clear();
+        handle.terminals.clear();
+        handle.live.clear();
+        this.liveSessionKeys.delete(handle.key);
+        handle.transport.close();
+    }
+    reapIdle() {
+        const now = this.now();
+        for (const [key, handle] of this.handles) {
+            if (handle.caps.size > 0 || handle.terminals.size > 0) {
+                continue;
+            }
+            // A live codex forwarder must outlive terminal detach / idle turns — it is
+            // the session's single event writer, so never reap a session that has one.
+            if (this.liveSessionKeys.has(key)) {
+                continue;
+            }
+            if (now - handle.lastUsedAt < this.idleTtlMs) {
+                continue;
+            }
+            handle.dead = true;
+            this.handles.delete(key);
+            handle.transport.send({ t: "shutdown" });
+            handle.child.kill("SIGTERM");
+            handle.transport.close();
+        }
+    }
+}
+function defaultRunnerEntry() {
+    if (process.env.RYNX_RUNNER_ENTRY?.trim()) {
+        return process.env.RYNX_RUNNER_ENTRY.trim();
+    }
+    // dist/runner/manager.js → dist/runner-main.js
+    return fileURLToPath(new URL("../runner-main.js", import.meta.url));
+}

package/dist/runner/protocol.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Wire protocol between the parent {@link import("./manager.js").RunnerManager}
+ * and a per-session runner child process. Transport-agnostic: the messages here
+ * carry no live objects, so the same protocol runs over local stdio today
+ * (NDJSON) and an outbound tunnel later. The seam is the live co-drive surface
+ * (`live.ensure` / `inject` / `live.interrupt`) plus per-thread capabilities and
+ * terminal attachment; the reply channels mirror each request's `reqId`.
+ */
+import { AgentRuntimeError, type AgentRuntimeId, type AgentSpec, type SessionEvent } from "@rynx-ai/core";
+/** A runtime error flattened for the wire; rebuilt parent-side as `AgentRuntimeError`. */
+export interface WireError {
+    message: string;
+    /** Stable error code (e.g. `codex_timeout`); preserved so `toNormalizerError` maps it. */
+    code: string;
+    statusCode: number;
+}
+/** Capabilities forwarded to a runner (parent serves status/listModels itself). */
+export type CapName = "getGoal" | "setGoal" | "clearGoal" | "forkSession";
+/** A live terminal role: `owner` is read-write, `read-only` a viewer. */
+export type TerminalRole = "owner" | "read-only";
+/** A codex approval decision the user returns for an interactive approval. */
+export type ApprovalDecisionWire = "acceptForSession" | "accept" | "decline" | "cancel";
+/** Outcome of an `inject`. `injected` = the app-server / tmux accepted the turn.
+ *  `notLive` = no live forwarder for this session (caller may use the run path).
+ *  `notReady` = live but not ready within the park window; `failed` = injection
+ *  threw. For BOTH notReady and failed the caller reports an error and MUST NOT
+ *  re-run the turn (re-running would double-write alongside the forwarder).
+ *  Mirrors omnigent's "inject failure ⇒ response.failed, never re-run locally". */
+export type InjectOutcome = "injected" | "notLive" | "notReady" | "failed";
+/** Parent → child. Terminal PTY bytes ride `term.input` base64-encoded so the
+ *  NDJSON line framing stays intact (raw bytes contain newlines). */
+export type ToChild = {
+    t: "cap";
+    capId: string;
+    name: CapName;
+    args: unknown[];
+} | {
+    t: "term.open";
+    attachId: string;
+    terminalId: string;
+    /** Session id — lets the child derive a codex-native TUI command from its
+     *  executor when no explicit `command` is given. */
+    localThreadId?: string;
+    role: TerminalRole;
+    cwd: string;
+    cols: number;
+    rows: number;
+    command?: string;
+    args?: string[];
+} | {
+    t: "term.input";
+    attachId: string;
+    dataB64: string;
+} | {
+    t: "term.resize";
+    attachId: string;
+    cols: number;
+    rows: number;
+} | {
+    t: "term.close";
+    attachId: string;
+} | {
+    t: "approval.resolve";
+    localThreadId: string;
+    approvalId: string;
+    decision: ApprovalDecisionWire;
+}
+/** Eagerly bring up a session's live codex TUI + forwarder (codex-native), so
+ *  its turns mirror to the bus regardless of whether the web has attached the
+ *  terminal. Idempotent; the child replies `live.ready` (echoing `reqId`) once
+ *  the thread is bound. */
+ | {
+    t: "live.ensure";
+    reqId: string;
+    localThreadId: string;
+    cwd?: string;
+    cols?: number;
+    rows?: number;
+    /** Runtime this session co-drives (resolved from the agent spec by the
+     *  control plane), so live picks the right backend per agent — not the
+     *  global default. Absent ⇒ host falls back to the store record / default. */
+    runtime?: AgentRuntimeId;
+    /** The session's preset agent id, so the host can load its spec and apply
+     *  the agent's model / skills / instructions to the live launch (not just
+     *  the runtime). Absent for inline-config or agent-less sessions. */
+    agentName?: string;
+    /** An inline agent spec (console session created from an inline config
+     *  rather than a preset id) — same purpose as `agentName`. */
+    agentSpec?: AgentSpec;
+}
+/** Inject a user turn into the session's live codex thread (`turn/start` or
+ *  `turn/steer`). The forwarder mirrors the output — this is the single-writer
+ *  web send path. The child replies `injected` (echoing `reqId`). */
+ | {
+    t: "inject";
+    reqId: string;
+    localThreadId: string;
+    text: string;
+}
+/** Interrupt the session's active turn — the web Stop button. codex: app-server
+ *  `turn/interrupt`; claude: an Escape keystroke to the pane. The child replies
+ *  `interrupted` (echoing `reqId`). */
+ | {
+    t: "live.interrupt";
+    reqId: string;
+    localThreadId: string;
+} | {
+    t: "shutdown";
+};
+/** Child → parent. `term.data` carries base64 PTY output (line-safe NDJSON). */
+export type FromChild = {
+    t: "ready";
+} | {
+    t: "capResult";
+    capId: string;
+    ok: true;
+    data: unknown;
+} | {
+    t: "capResult";
+    capId: string;
+    ok: false;
+    error: WireError;
+} | {
+    t: "term.opened";
+    attachId: string;
+    role: TerminalRole;
+} | {
+    t: "term.data";
+    attachId: string;
+    dataB64: string;
+} | {
+    t: "term.exit";
+    attachId: string;
+    exitCode: number;
+} | {
+    t: "term.error";
+    attachId: string;
+    message: string;
+}
+/** A canonical {@link SessionEvent} mirrored by the session's persistent codex
+ *  forwarder (web- AND TUI-initiated turns). Not bound to any single `run`. */
+ | {
+    t: "mirror";
+    sessionId: string;
+    event: SessionEvent;
+}
+/** The session rotated to a fresh machine-session (claude `/clear`·`/fork`): the
+ *  child re-pointed its mirror to `to` and asks the daemon to alias the runner
+ *  (terminal transfer, so `to` stays injectable) and record its meta. */
+ | {
+    t: "rotate";
+    from: string;
+    to: string;
+    kind: "clear" | "fork";
+    agent?: string;
+    model?: string;
+    cwd?: string;
+    parentSessionId?: string;
+}
+/** Result of a `live.ensure`: `ok` once the codex thread is bound (or a no-op
+ *  for a non-codex / non-live session). Echoes the request `reqId`. */
+ | {
+    t: "live.ready";
+    reqId: string;
+    localThreadId: string;
+    ok: boolean;
+    error?: string;
+}
+/** Result of an `inject`: `outcome` distinguishes injected / notLive / notReady /
+ *  failed so the caller never falls back to a second output path on a live
+ *  session. Echoes the request `reqId`. */
+ | {
+    t: "injected";
+    reqId: string;
+    localThreadId: string;
+    outcome: InjectOutcome;
+    error?: string;
+}
+/** Result of a `live.interrupt`: `ok` when an active turn was interrupted (false
+ *  when there was none). Echoes the request `reqId`. */
+ | {
+    t: "interrupted";
+    reqId: string;
+    localThreadId: string;
+    ok: boolean;
+    error?: string;
+};
+/** Encode a message as a single NDJSON line (newline included). */
+export declare function encodeMessage(msg: ToChild | FromChild): string;
+/** Parse one NDJSON line; returns `null` for blank lines or malformed JSON. */
+export declare function decodeMessage<T extends ToChild | FromChild>(line: string): T | null;
+/** Flatten an error for the wire, preserving `AgentRuntimeError`'s code/status. */
+export declare function toWireError(error: unknown): WireError;
+/** Rebuild an `AgentRuntimeError` parent-side so `code` survives the boundary. */
+export declare function fromWireError(error: WireError): AgentRuntimeError;

package/dist/runner/protocol.js

@@ -0,0 +1,41 @@
+/**
+ * Wire protocol between the parent {@link import("./manager.js").RunnerManager}
+ * and a per-session runner child process. Transport-agnostic: the messages here
+ * carry no live objects, so the same protocol runs over local stdio today
+ * (NDJSON) and an outbound tunnel later. The seam is the live co-drive surface
+ * (`live.ensure` / `inject` / `live.interrupt`) plus per-thread capabilities and
+ * terminal attachment; the reply channels mirror each request's `reqId`.
+ */
+import { AgentRuntimeError, } from "@rynx-ai/core";
+/** Encode a message as a single NDJSON line (newline included). */
+export function encodeMessage(msg) {
+    return `${JSON.stringify(msg)}\n`;
+}
+/** Parse one NDJSON line; returns `null` for blank lines or malformed JSON. */
+export function decodeMessage(line) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+        return null;
+    }
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+}
+/** Flatten an error for the wire, preserving `AgentRuntimeError`'s code/status. */
+export function toWireError(error) {
+    if (error instanceof AgentRuntimeError) {
+        return { message: error.message, code: error.code, statusCode: error.statusCode };
+    }
+    return {
+        message: error instanceof Error ? error.message : String(error),
+        code: "runtime_error",
+        statusCode: 500,
+    };
+}
+/** Rebuild an `AgentRuntimeError` parent-side so `code` survives the boundary. */
+export function fromWireError(error) {
+    return new AgentRuntimeError(error.message, error.statusCode, error.code);
+}