@rynx-ai/runtime 0.1.11-beta.32 → 0.1.11-beta.34

package/dist/runner/manager.js

@@ -72,11 +72,16 @@ class ManagedTerminal {
     sendMsg;
     onClose;
     ready;
-    dataListener;
-    exitListener;
+    readerDone;
+    resizeListener;
+    dimensions;
+    role = "read-only";
+    seedBytes = 0;
     resolveReady;
     rejectReady;
+    resolveReaderDone;
     state = "opening";
+    pending = new Map();
     constructor(attachId, sendMsg, onClose) {
         this.attachId = attachId;
         this.sendMsg = sendMsg;
@@ -85,20 +90,75 @@ class ManagedTerminal {
             this.resolveReady = resolve;
             this.rejectReady = reject;
         });
+        this.readerDone = new Promise((resolve) => {
+            this.resolveReaderDone = resolve;
+        });
         // Never surface an unhandled rejection if no caller awaits `ready`.
         void this.ready.catch(() => undefined);
     }
-    onData(listener) {
-        this.dataListener = listener;
+    onResize(listener) {
+        this.resizeListener = listener;
+        if (this.dimensions)
+            queueMicrotask(() => listener(this.dimensions));
+    }
+    readSeed(offset, maxBytes) {
+        if (this.state !== "prepared")
+            return Promise.reject(new Error("terminal is not prepared"));
+        return this.requestRead("seed", {
+            t: "term.seed.read",
+            attachId: this.attachId,
+            reqId: randomUUID(),
+            offset,
+            maxBytes,
+        });
+    }
+    start() {
+        if (this.state !== "prepared")
+            return Promise.reject(new Error("terminal is not prepared"));
+        this.state = "starting";
+        const reqId = randomUUID();
+        return this.request("start", { t: "term.start", attachId: this.attachId, reqId })
+            .then(() => {
+            if (this.state === "starting")
+                this.state = "started";
+        });
     }
-    onExit(listener) {
-        this.exitListener = listener;
+    read(offset, maxBytes) {
+        if (this.state !== "started")
+            return Promise.reject(new Error("terminal has not started"));
+        return this.requestRead("read", {
+            t: "term.read",
+            attachId: this.attachId,
+            reqId: randomUUID(),
+            offset,
+            maxBytes,
+        });
     }
     write(data) {
-        this.sendMsg({ t: "term.input", attachId: this.attachId, dataB64: Buffer.from(data, "utf8").toString("base64") });
+        if (this.state !== "started" || this.role !== "owner")
+            return Promise.resolve();
+        const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data);
+        if (bytes.byteLength === 0)
+            return Promise.resolve();
+        const reqId = randomUUID();
+        return this.request("input", {
+            t: "term.input",
+            attachId: this.attachId,
+            reqId,
+            dataB64: bytes.toString("base64"),
+        }).then(() => undefined);
     }
     resize(cols, rows) {
-        this.sendMsg({ t: "term.resize", attachId: this.attachId, cols, rows });
+        if (this.state !== "started")
+            return Promise.resolve();
+        const reqId = randomUUID();
+        return this.request("resize", {
+            t: "term.resize",
+            attachId: this.attachId,
+            reqId,
+            cols,
+            rows,
+        }).then(() => undefined);
     }
     close() {
         if (this.state === "closed")
@@ -107,43 +167,96 @@ class ManagedTerminal {
         this.state = "closed";
         this.sendMsg({ t: "term.close", attachId: this.attachId });
         this.onClose();
+        this.rejectPending(new Error("terminal attachment was closed"));
         if (wasOpening) {
             this.rejectReady(new TerminalOpenError("terminal attachment was closed while opening", "terminal_open_failed"));
         }
+        this.resolveReaderDone({ finalOffset: 0, reason: "client_closed", exitCode: 0 });
     }
     // ── internal (driven by onChildMessage) ──
-    _opened(role) {
+    _prepared(role, seedBytes, cols, rows) {
         if (this.state !== "opening")
             return;
-        this.state = "opened";
-        this.resolveReady({ role });
-    }
-    _data(dataB64) {
-        this.dataListener?.(Buffer.from(dataB64, "base64").toString("utf8"));
+        this.state = "prepared";
+        this.role = role;
+        this.seedBytes = seedBytes;
+        this.dimensions = cols !== undefined && rows !== undefined ? { cols, rows } : undefined;
+        this.resolveReady({
+            role,
+            seedBytes,
+            ...(this.dimensions ? { dimensions: this.dimensions } : {}),
+        });
     }
-    _exit(exitCode) {
+    _dimensions(cols, rows) {
         if (this.state === "closed")
             return;
-        const wasOpening = this.state === "opening";
-        this.state = "closed";
-        if (wasOpening) {
-            this.rejectReady(new TerminalOpenError(`terminal exited before opening (code=${exitCode})`, "terminal_open_failed"));
-        }
-        else {
-            this.exitListener?.({ exitCode });
-        }
+        this.dimensions = { cols, rows };
+        this.resizeListener?.(this.dimensions);
+    }
+    _started(reqId) {
+        this.resolvePending(reqId, "start", undefined);
+    }
+    _chunk(reqId, operation, dataB64, nextOffset, done, finalOffset) {
+        this.resolvePending(reqId, operation, {
+            data: Uint8Array.from(Buffer.from(dataB64, "base64")),
+            nextOffset,
+            done,
+            ...(finalOffset === undefined ? {} : { finalOffset }),
+        });
+    }
+    _ack(reqId, operation) {
+        this.resolvePending(reqId, operation, undefined);
     }
-    _fail(message, code = "terminal_open_failed") {
+    _readerDone(info) {
+        this.resolveReaderDone(info);
+    }
+    _fail(message, code = "terminal_open_failed", reqId) {
         if (this.state === "closed")
             return;
+        if (reqId) {
+            const pending = this.pending.get(reqId);
+            if (pending) {
+                this.pending.delete(reqId);
+                pending.reject(new TerminalOpenError(message, code));
+                return;
+            }
+        }
         const wasOpening = this.state === "opening";
         this.state = "closed";
+        this.rejectPending(new TerminalOpenError(message, code));
         if (wasOpening) {
             this.rejectReady(new TerminalOpenError(message, code));
         }
-        else {
-            this.exitListener?.({ exitCode: 1 });
+        this.resolveReaderDone({ finalOffset: 0, reason: "internal", exitCode: 1 });
+    }
+    requestRead(operation, message) {
+        return this.request(operation, message);
+    }
+    request(operation, message) {
+        return new Promise((resolve, reject) => {
+            this.pending.set(message.reqId, { operation, resolve, reject });
+            try {
+                this.sendMsg(message);
+            }
+            catch (error) {
+                this.pending.delete(message.reqId);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    resolvePending(reqId, operation, value) {
+        const pending = this.pending.get(reqId);
+        if (!pending || pending.operation !== operation) {
+            this._fail(`terminal response ${reqId} is duplicate or out of order`);
+            return;
         }
+        this.pending.delete(reqId);
+        pending.resolve(value);
+    }
+    rejectPending(error) {
+        for (const pending of this.pending.values())
+            pending.reject(error);
+        this.pending.clear();
     }
 }
 export class RunnerManager {
@@ -227,9 +340,12 @@ export class RunnerManager {
         this.shutdownGraceMs = Math.max(0, opts.shutdownGraceMs ?? DEFAULT_SHUTDOWN_GRACE_MS);
         this.shutdownKillGraceMs = Math.max(0, opts.shutdownKillGraceMs ?? DEFAULT_SHUTDOWN_KILL_GRACE_MS);
         this.signalChild = opts.signalChild ?? signalRunnerChild;
-        this.terminateTerminalServer = opts.terminateTerminalServer ?? terminateTmuxServer;
-        this.terminalWindowActivityAt = opts.terminalWindowActivityAt ?? tmuxWindowActivityAt;
-        this.terminalHasAttachedClient = opts.terminalHasAttachedClient ?? tmuxHasAttachedClient;
+        this.terminateTerminalServer = opts.terminateTerminalServer ??
+            ((name, ownerPid) => terminateTmuxServer(name, undefined, ownerPid));
+        this.terminalWindowActivityAt = opts.terminalWindowActivityAt ??
+            ((name, ownerPid) => tmuxWindowActivityAt(name, undefined, ownerPid));
+        this.terminalHasAttachedClient = opts.terminalHasAttachedClient ??
+            ((name, ownerPid) => tmuxHasAttachedClient(name, undefined, ownerPid));
         this.liveStartTimeoutMs = Math.max(1, opts.liveStartTimeoutMs ?? DEFAULT_LIVE_START_TIMEOUT_MS);
         this.liveReadyTimeoutMs = Math.max(1, opts.liveReadyTimeoutMs ?? DEFAULT_LIVE_READY_TIMEOUT_MS);
         this.nativeLiveStartTimeoutMs = Math.max(1, opts.nativeLiveStartTimeoutMs ?? DEFAULT_NATIVE_LIVE_START_TIMEOUT_MS);
@@ -248,9 +364,8 @@ export class RunnerManager {
     /**
      * 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.
+     * single attach client with the requested `owner` (read-write) or `read-only`
+     * role. Not part of `AgentExecutor`; the WS bridge calls it directly.
      */
     openTerminal(localThreadId, opts) {
         const handle = this.getOrSpawn(localThreadId);
@@ -1279,8 +1394,14 @@ export class RunnerManager {
                 }
             });
         }
-        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}` : ""})`));
+        const failAndReap = (reason) => {
+            this.failHandle(handle, reason);
+            void this.terminateHandle(handle, reason).catch((error) => {
+                logTerminationFailure(handle, error);
+            });
+        };
+        child.on("error", (error) => failAndReap(error.message));
+        child.on("exit", (code, signal) => failAndReap(`runner exited (code=${code ?? "null"}${signal ? `, signal=${signal}` : ""})`));
         return handle;
     }
     onChildMessage(handle, msg) {
@@ -1301,22 +1422,36 @@ export class RunnerManager {
                 }
                 return;
             }
-            case "term.opened":
-                handle.terminals.get(msg.attachId)?._opened(msg.role);
+            case "term.prepared":
+                handle.terminals.get(msg.attachId)?._prepared(msg.role, msg.seedBytes, msg.cols, msg.rows);
                 return;
-            case "term.data":
-                handle.terminals.get(msg.attachId)?._data(msg.dataB64);
+            case "term.seed.chunk":
+                handle.terminals.get(msg.attachId)?._chunk(msg.reqId, "seed", msg.dataB64, msg.nextOffset, msg.done, msg.finalOffset);
                 return;
-            case "term.exit": {
-                const terminal = handle.terminals.get(msg.attachId);
-                handle.terminals.delete(msg.attachId);
-                terminal?._exit(msg.exitCode);
+            case "term.started":
+                handle.terminals.get(msg.attachId)?._started(msg.reqId);
+                return;
+            case "term.chunk":
+                handle.terminals.get(msg.attachId)?._chunk(msg.reqId, "read", msg.dataB64, msg.nextOffset, msg.done, msg.finalOffset);
+                return;
+            case "term.dimensions":
+                handle.terminals.get(msg.attachId)?._dimensions(msg.cols, msg.rows);
+                return;
+            case "term.reader.done":
+                handle.terminals.get(msg.attachId)?._readerDone({
+                    finalOffset: msg.finalOffset,
+                    reason: msg.reason,
+                    exitCode: msg.exitCode,
+                });
+                return;
+            case "term.ack":
+                handle.terminals.get(msg.attachId)?._ack(msg.reqId, msg.operation);
                 return;
-            }
             case "term.error": {
                 const terminal = handle.terminals.get(msg.attachId);
-                handle.terminals.delete(msg.attachId);
-                terminal?._fail(msg.message, msg.code);
+                if (!msg.reqId)
+                    handle.terminals.delete(msg.attachId);
+                terminal?._fail(msg.message, msg.code, msg.reqId);
                 return;
             }
             case "mirror":
@@ -1409,6 +1544,18 @@ export class RunnerManager {
                 this.deliverRotateMessage(handle, msg);
                 return;
             }
+            case "terminal.lifecycle.ended": {
+                if (msg.lifecycle === "required") {
+                    void this.terminateHandle(handle, `required Terminal exited with status ${msg.status}`).catch((error) => logTerminationFailure(handle, error));
+                }
+                return;
+            }
+            case "terminal.reaped": {
+                const resolve = handle.live.get(msg.reqId);
+                handle.live.delete(msg.reqId);
+                resolve?.({ ok: msg.ok, error: msg.error });
+                return;
+            }
             case "live.ready":
             case "interrupted":
             case "injected": {
@@ -1499,7 +1646,7 @@ export class RunnerManager {
                 childExited = await waitForChildExit(handle.completion, this.shutdownKillGraceMs);
             }
             if (handle.key !== CAP_KEY) {
-                await Promise.resolve(this.terminateTerminalServer(`${handle.key}-main`)).catch((error) => {
+                await Promise.resolve(this.terminateTerminalServer(`${handle.key}-main`, handle.child.pid)).catch((error) => {
                     console.warn(`[runner-manager] best-effort terminal close failed for ${handle.key}-main: ${error instanceof Error ? error.message : String(error)}`);
                 });
             }
@@ -1584,7 +1731,40 @@ export class RunnerManager {
         // A failed teardown must re-arm on the next scan instead of retrying on
         // every sweep forever.
         delete handle.nativePaneLastBusyAt;
-        await this.terminateHandle(handle, "idle native pane reaped").catch((error) => logTerminationFailure(handle, error));
+        await this.reapNativeTerminal(handle).catch((error) => {
+            logTerminationFailure(handle, error);
+        });
+    }
+    reapNativeTerminal(handle) {
+        const localThreadId = this.currentTerminalSessionId(handle, handle.key);
+        const terminalId = `${localThreadId}-main`;
+        const reqId = randomUUID();
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                if (!handle.live.delete(reqId))
+                    return;
+                reject(new Error(`runner did not acknowledge idle terminal reap within ${this.liveReadyTimeoutMs}ms`));
+            }, this.liveReadyTimeoutMs);
+            timeout.unref?.();
+            handle.live.set(reqId, (reply) => {
+                clearTimeout(timeout);
+                if (reply.ok) {
+                    resolve();
+                    return;
+                }
+                reject(fromWireError(reply.error ?? {
+                    message: "idle terminal reap failed",
+                    code: "terminal_reap_failed",
+                    statusCode: 500,
+                }));
+            });
+            handle.transport.send({
+                t: "terminal.reap",
+                reqId,
+                localThreadId,
+                terminalId,
+            });
+        });
     }
     async isNativePaneBusy(handle) {
         if (handle.activeResponseIds.size > 0 ||
@@ -1595,7 +1775,7 @@ export class RunnerManager {
         }
         const terminalName = `${handle.key}-main`;
         try {
-            if (await this.terminalHasAttachedClient(terminalName))
+            if (await this.terminalHasAttachedClient(terminalName, handle.child.pid))
                 return true;
         }
         catch {
@@ -1603,7 +1783,7 @@ export class RunnerManager {
         }
         let activityAt = null;
         try {
-            activityAt = await this.terminalWindowActivityAt(terminalName);
+            activityAt = await this.terminalWindowActivityAt(terminalName, handle.child.pid);
         }
         catch {
             // A failed probe contributes no busy evidence.

package/dist/runner/protocol.d.ts

@@ -23,7 +23,7 @@ export type TerminalRole = "owner" | "read-only";
 /** Stable reason for a terminal attach failure. `terminal_not_live` is an
  * expected, retryable absence; `terminal_open_failed` is an infrastructure error. */
 export type TerminalOpenErrorCode = "terminal_not_live" | "terminal_open_failed";
-/** Parent → child. Terminal PTY bytes ride `term.input` base64-encoded so the
+/** Parent → child. Raw terminal bytes ride `term.input` base64-encoded so the
  *  NDJSON line framing stays intact (raw bytes contain newlines). */
 export type ToChild = {
     t: "mirror.image.ack";
@@ -51,13 +51,31 @@ export type ToChild = {
     rows: number;
     command?: string;
     args?: string[];
+} | {
+    t: "term.seed.read";
+    attachId: string;
+    reqId: string;
+    offset: number;
+    maxBytes: number;
+} | {
+    t: "term.start";
+    attachId: string;
+    reqId: string;
+} | {
+    t: "term.read";
+    attachId: string;
+    reqId: string;
+    offset: number;
+    maxBytes: number;
 } | {
     t: "term.input";
     attachId: string;
+    reqId: string;
     dataB64: string;
 } | {
     t: "term.resize";
     attachId: string;
+    reqId: string;
     cols: number;
     rows: number;
 } | {
@@ -119,10 +137,18 @@ export type ToChild = {
     t: "live.interrupt";
     reqId: string;
     localThreadId: string;
+}
+/** Pane-scoped idle cleanup. The child removes the terminal resource and
+ * performs the lifecycle adapter's explicit cleanup before acknowledging. */
+ | {
+    t: "terminal.reap";
+    reqId: string;
+    localThreadId: string;
+    terminalId: string;
 } | {
     t: "shutdown";
 };
-/** Child → parent. `term.data` carries base64 PTY output (line-safe NDJSON). */
+/** Child → parent. `term.data` carries raw pane output as base64 (line-safe NDJSON). */
 export type FromChild = {
     t: "ready";
 } | {
@@ -136,20 +162,52 @@ export type FromChild = {
     ok: false;
     error: WireError;
 } | {
-    t: "term.opened";
+    t: "term.prepared";
     attachId: string;
     role: TerminalRole;
+    seedBytes: number;
+    cols?: number;
+    rows?: number;
+} | {
+    t: "term.seed.chunk";
+    attachId: string;
+    reqId: string;
+    dataB64: string;
+    nextOffset: number;
+    done: boolean;
+    finalOffset?: number;
+} | {
+    t: "term.started";
+    attachId: string;
+    reqId: string;
 } | {
-    t: "term.data";
+    t: "term.chunk";
     attachId: string;
+    reqId: string;
     dataB64: string;
+    nextOffset: number;
+    done: boolean;
+    finalOffset?: number;
 } | {
-    t: "term.exit";
+    t: "term.reader.done";
     attachId: string;
+    finalOffset: number;
+    reason: "terminal_exited" | "client_closed" | "backpressure" | "internal";
     exitCode: number;
+} | {
+    t: "term.ack";
+    attachId: string;
+    reqId: string;
+    operation: "input" | "resize";
+} | {
+    t: "term.dimensions";
+    attachId: string;
+    cols: number;
+    rows: number;
 } | {
     t: "term.error";
     attachId: string;
+    reqId?: string;
     code: TerminalOpenErrorCode;
     message: string;
 }
@@ -177,6 +235,19 @@ export type FromChild = {
     t: "mirror.image.commit";
     transferId: string;
     seq: number;
+} | {
+    t: "terminal.lifecycle.ended";
+    localThreadId: string;
+    terminalId: string;
+    lifecycle: "required" | "auxiliary";
+    status: "idle" | "running" | "failed" | "unknown";
+} | {
+    t: "terminal.reaped";
+    reqId: string;
+    localThreadId: string;
+    terminalId: string;
+    ok: boolean;
+    error?: WireError;
 }
 /** 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
@@ -202,8 +273,9 @@ export type FromChild = {
     error?: WireError;
 }
 /** Result of an `inject`: `result.outcome` distinguishes a new turn, an
- * active-turn steer, and failures. Successful results also carry the
- * runtime-owned canonical Response identity. Echoes the request `reqId`. */
+ * active-turn steer, and failures. RPC-backed success carries the canonical
+ * Response identity immediately; transcript-backed success may publish it on
+ * the mirrored user record shortly afterward. Echoes the request `reqId`. */
  | {
     t: "injected";
     reqId: string;

package/dist/runner/transport.d.ts

@@ -3,9 +3,13 @@ import { type FromChild, type ToChild } from "./protocol.js";
 export interface RunnerTransport<TSend, TRecv> {
     /** Send one message. Best-effort: a dead peer is surfaced via {@link onClose}. */
     send(msg: TSend): void;
+    /** Send one bounded message and resolve only after the writable accepts and
+     * drains it. Terminal pull responses use this to keep stdio end-to-end
+     * demand-driven. */
+    sendAndDrain(msg: TSend): Promise<void>;
     /** Register the single message handler. */
     onMessage(cb: (msg: TRecv) => void): void;
-    /** Register a close/error handler (peer stream ended). */
+    /** Register a close/error observer (peer stream ended). */
     onClose(cb: (error?: Error) => void): void;
     /** Stop reading and release the readline interface. */
     close(): void;
@@ -25,12 +29,15 @@ export declare class StdioRunnerTransport<TSend, TRecv> implements RunnerTranspo
     private readonly output;
     private readonly rl;
     private messageHandler;
-    private closeHandler;
+    private readonly closeHandlers;
     private closed;
+    private writeTail;
     constructor(input: Readable, output: Writable);
     send(msg: TSend): void;
+    sendAndDrain(msg: TSend): Promise<void>;
     onMessage(cb: (msg: TRecv) => void): void;
     onClose(cb: (error?: Error) => void): void;
     close(): void;
     private handleClose;
+    private writeMessage;
 }

package/dist/runner/transport.js

@@ -22,8 +22,9 @@ export class StdioRunnerTransport {
     output;
     rl;
     messageHandler = null;
-    closeHandler = null;
+    closeHandlers = new Set();
     closed = false;
+    writeTail = Promise.resolve();
     constructor(input, output) {
         this.input = input;
         this.output = output;
@@ -52,11 +53,16 @@ export class StdioRunnerTransport {
         }
         this.output.write(encodeMessage(msg));
     }
+    sendAndDrain(msg) {
+        const operation = this.writeTail.then(() => this.writeMessage(msg));
+        this.writeTail = operation.catch(() => undefined);
+        return operation;
+    }
     onMessage(cb) {
         this.messageHandler = cb;
     }
     onClose(cb) {
-        this.closeHandler = cb;
+        this.closeHandlers.add(cb);
     }
     close() {
         this.closed = true;
@@ -67,6 +73,52 @@ export class StdioRunnerTransport {
             return;
         }
         this.closed = true;
-        this.closeHandler?.(error);
+        for (const handler of this.closeHandlers)
+            handler(error);
+    }
+    writeMessage(msg) {
+        if (this.closed)
+            return Promise.reject(new Error("runner transport is closed"));
+        const encoded = encodeMessage(msg);
+        return new Promise((resolve, reject) => {
+            let callbackDone = false;
+            let drainDone = false;
+            let settled = false;
+            const cleanup = () => {
+                this.output.off("drain", onDrain);
+                this.output.off("error", onError);
+            };
+            const finish = () => {
+                if (settled || !callbackDone || !drainDone)
+                    return;
+                settled = true;
+                cleanup();
+                resolve();
+            };
+            const onDrain = () => {
+                drainDone = true;
+                finish();
+            };
+            const onError = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                reject(error);
+            };
+            this.output.once("error", onError);
+            const accepted = this.output.write(encoded, (error) => {
+                if (error) {
+                    onError(error);
+                    return;
+                }
+                callbackDone = true;
+                finish();
+            });
+            drainDone = accepted;
+            if (!accepted)
+                this.output.once("drain", onDrain);
+            finish();
+        });
     }
 }