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

package/dist/terminal/spool.js

@@ -0,0 +1,231 @@
+import { closeSync, mkdirSync, mkdtempSync, openSync, readSync, rmSync, unlinkSync, writeSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const DEFAULT_SEGMENT_BYTES = 1024 * 1024;
+const MAX_READ_BYTES = 1024 * 1024;
+export class TerminalSpoolCapacityError extends Error {
+    name = "TerminalSpoolCapacityError";
+}
+export class TerminalSpoolProtocolError extends Error {
+    name = "TerminalSpoolProtocolError";
+}
+/**
+ * A single-reader byte log backed by disposable fixed-size files. Producers
+ * append while the consumer pulls with an exact monotonic offset. Fully
+ * consumed segments are unlinked immediately, so retained disk is bounded by
+ * viewer lag rather than the lifetime output volume.
+ */
+export class SegmentedTerminalSpool {
+    directory;
+    segmentBytes;
+    quotaBytes;
+    segments = [];
+    writeOffset = 0;
+    readOffset = 0;
+    ended = false;
+    closed = false;
+    failure;
+    pending;
+    constructor(options = {}) {
+        this.segmentBytes = positiveInteger(options.segmentBytes ?? DEFAULT_SEGMENT_BYTES, "segmentBytes");
+        this.quotaBytes = options.quotaBytes === undefined
+            ? undefined
+            : positiveInteger(options.quotaBytes, "quotaBytes");
+        const parent = options.directory ?? tmpdir();
+        mkdirSync(parent, { recursive: true });
+        this.directory = mkdtempSync(join(parent, "rynx-terminal-spool-"));
+    }
+    get retainedBytes() {
+        return this.writeOffset - this.readOffset;
+    }
+    get finalOffset() {
+        return this.ended ? this.writeOffset : undefined;
+    }
+    append(input) {
+        this.assertWritable();
+        if (input.byteLength === 0)
+            return;
+        if (this.quotaBytes !== undefined &&
+            this.retainedBytes + input.byteLength > this.quotaBytes) {
+            const error = new TerminalSpoolCapacityError(`Terminal viewer lag exceeded ${this.quotaBytes} bytes`);
+            this.fail(error);
+            throw error;
+        }
+        const source = Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+        let sourceOffset = 0;
+        while (sourceOffset < source.byteLength) {
+            let segment = this.segments.at(-1);
+            if (!segment || segment.sealed)
+                segment = this.createSegment();
+            const writable = Math.min(this.segmentBytes - segment.length, source.byteLength - sourceOffset);
+            writeSync(segment.fd, source, sourceOffset, writable, segment.length);
+            segment.length += writable;
+            sourceOffset += writable;
+            this.writeOffset += writable;
+            if (segment.length === this.segmentBytes) {
+                segment.sealed = true;
+                closeSync(segment.fd);
+                segment.fd = -1;
+            }
+        }
+        this.settlePending();
+    }
+    end() {
+        if (this.closed || this.ended)
+            return;
+        this.ended = true;
+        const segment = this.segments.at(-1);
+        if (segment && !segment.sealed) {
+            segment.sealed = true;
+            closeSync(segment.fd);
+            segment.fd = -1;
+        }
+        this.settlePending();
+    }
+    fail(error) {
+        if (this.closed || this.failure)
+            return;
+        this.failure = error;
+        this.ended = true;
+        const pending = this.pending;
+        this.pending = undefined;
+        pending?.reject(error);
+    }
+    read(offset, maxBytes) {
+        if (this.closed)
+            return Promise.reject(new TerminalSpoolProtocolError("Terminal spool is closed"));
+        if (this.failure)
+            return Promise.reject(this.failure);
+        if (!Number.isSafeInteger(offset) || offset < 0 || offset !== this.readOffset) {
+            return Promise.reject(new TerminalSpoolProtocolError(`Terminal spool expected offset ${this.readOffset}, received ${String(offset)}`));
+        }
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > MAX_READ_BYTES) {
+            return Promise.reject(new TerminalSpoolProtocolError(`Terminal spool maxBytes must be within 1..${MAX_READ_BYTES}`));
+        }
+        if (this.pending) {
+            return Promise.reject(new TerminalSpoolProtocolError("Concurrent reads from one terminal spool are not allowed"));
+        }
+        const available = this.writeOffset - this.readOffset;
+        if (available > 0 || this.ended)
+            return Promise.resolve(this.readNow(maxBytes));
+        return new Promise((resolve, reject) => {
+            this.pending = { offset, maxBytes, resolve, reject };
+        });
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const error = new TerminalSpoolProtocolError("Terminal spool is closed");
+        const pending = this.pending;
+        this.pending = undefined;
+        pending?.reject(error);
+        for (const segment of this.segments) {
+            if (segment.fd !== -1) {
+                try {
+                    closeSync(segment.fd);
+                }
+                catch {
+                    // Best-effort cleanup continues through every segment.
+                }
+            }
+        }
+        this.segments.length = 0;
+        rmSync(this.directory, { recursive: true, force: true });
+    }
+    assertWritable() {
+        if (this.closed)
+            throw new TerminalSpoolProtocolError("Terminal spool is closed");
+        if (this.failure)
+            throw this.failure;
+        if (this.ended)
+            throw new TerminalSpoolProtocolError("Terminal spool has ended");
+    }
+    createSegment() {
+        const start = this.writeOffset;
+        const path = join(this.directory, `${String(start).padStart(20, "0")}.bin`);
+        const segment = {
+            path,
+            start,
+            fd: openSync(path, "wx+", 0o600),
+            length: 0,
+            sealed: false,
+        };
+        this.segments.push(segment);
+        return segment;
+    }
+    settlePending() {
+        const pending = this.pending;
+        if (!pending || (this.writeOffset === pending.offset && !this.ended))
+            return;
+        this.pending = undefined;
+        if (this.failure)
+            pending.reject(this.failure);
+        else
+            pending.resolve(this.readNow(pending.maxBytes));
+    }
+    readNow(maxBytes) {
+        if (this.failure)
+            throw this.failure;
+        const available = this.writeOffset - this.readOffset;
+        const length = Math.min(maxBytes, available);
+        const data = Buffer.allocUnsafe(length);
+        let copied = 0;
+        let cursor = this.readOffset;
+        for (const segment of this.segments) {
+            const segmentEnd = segment.start + segment.length;
+            if (cursor >= segmentEnd)
+                continue;
+            if (cursor < segment.start) {
+                throw new TerminalSpoolProtocolError("Terminal spool contains a byte gap");
+            }
+            const within = cursor - segment.start;
+            const count = Math.min(segment.length - within, length - copied);
+            if (count <= 0)
+                break;
+            const fd = segment.fd === -1 ? openSync(segment.path, "r") : segment.fd;
+            try {
+                const actual = readSync(fd, data, copied, count, within);
+                if (actual !== count)
+                    throw new TerminalSpoolProtocolError("Terminal spool segment was truncated");
+            }
+            finally {
+                if (segment.fd === -1)
+                    closeSync(fd);
+            }
+            copied += count;
+            cursor += count;
+            if (copied === length)
+                break;
+        }
+        this.readOffset += copied;
+        this.discardConsumedSegments();
+        const done = this.ended && this.readOffset === this.writeOffset;
+        return {
+            data: Uint8Array.from(data.subarray(0, copied)),
+            nextOffset: this.readOffset,
+            done,
+            ...(done ? { finalOffset: this.writeOffset } : {}),
+        };
+    }
+    discardConsumedSegments() {
+        while (this.segments.length > 0) {
+            const segment = this.segments[0];
+            if (!segment.sealed || segment.start + segment.length > this.readOffset)
+                return;
+            this.segments.shift();
+            try {
+                unlinkSync(segment.path);
+            }
+            catch {
+                // The directory-level close remains the final cleanup fence.
+            }
+        }
+    }
+}
+function positiveInteger(value, field) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new TypeError(`${field} must be a positive integer`);
+    }
+    return value;
+}

package/dist/terminal/tmux.d.ts

@@ -1,38 +1,43 @@
-/** A live attach handle: the pane's bytes flow through `onData`; caller input
- *  goes through `write`; `resize` reflows the pane; `kill` ends this client
- *  (not the server). Shape mirrors the node-pty surface the WS bridge needs. */
-export interface TerminalAttachment {
-    onData(listener: (chunk: string) => void): void;
-    onExit(listener: (info: {
-        exitCode: number;
+import { type TerminalSpoolRead } from "./spool.js";
+export type TerminalReaderDoneReason = "terminal_exited" | "client_closed" | "backpressure" | "internal";
+export interface TerminalReaderDone {
+    reason: TerminalReaderDoneReason;
+    finalOffset: number;
+    exitCode: number;
+}
+/** Live half of a prepared control attachment. Output is pulled by exact
+ * offset; reader completion is published independently of pull activity. */
+export interface PullTerminalAttachment {
+    readonly dimensions?: {
+        cols: number;
+        rows: number;
+    };
+    readonly readerDone: Promise<TerminalReaderDone>;
+    read(offset: number, maxBytes: number): Promise<TerminalSpoolRead>;
+    onResize(listener: (dimensions: {
+        cols: number;
+        rows: number;
     }) => void): void;
-    write(data: string): void;
-    resize(cols: number, rows: number): void;
-    /** Detach this client. The tmux server + pane keep running. */
+    write(data: Uint8Array): Promise<void>;
+    resize(cols: number, rows: number): Promise<void>;
+    kill(): void;
+}
+/** Capture phase. No tmux control client exists until `start` succeeds. */
+export interface PreparedTerminalAttachment {
+    readonly seedBytes: number;
+    readonly dimensions?: {
+        cols: number;
+        rows: number;
+    };
+    readSeed(offset: number, maxBytes: number): Promise<TerminalSpoolRead>;
+    start(): Promise<PullTerminalAttachment>;
     kill(): void;
 }
 /** Result of probing the inner tmux pane. `unknown` is deliberately distinct
  * from `dead`: a timed-out/unexecutable control command is inconclusive;
- * `dead` requires an explicit dead pane. The lifecycle watcher separately
- * mirrors reference implementation's capture failure path for a vanished server/session. */
+ * `dead` requires an explicit dead pane. The lifecycle watcher separately uses
+ * capture failure to identify a vanished server/session. */
 export type TerminalLiveness = "alive" | "dead" | "unknown";
-/** Minimal node-pty surface (kept local so this module has no type dep on it). */
-interface PtyProcess {
-    onData(cb: (data: string) => void): void;
-    onExit(cb: (e: {
-        exitCode: number;
-    }) => void): void;
-    write(data: string): void;
-    resize(cols: number, rows: number): void;
-    kill(signal?: string): void;
-}
-type PtySpawn = (file: string, args: string[], opts: {
-    name: string;
-    cols: number;
-    rows: number;
-    cwd: string;
-    env: Record<string, string>;
-}) => PtyProcess;
 export interface TmuxTerminalOptions {
     /** Unique name for the tmux session + socket, e.g. `rynx-<sessionId>-<termId>`. */
     name: string;
@@ -43,17 +48,42 @@ export interface TmuxTerminalOptions {
     env?: Record<string, string>;
     cols?: number;
     rows?: number;
-    /** Injectable for tests; defaults to the real node-pty spawn. */
-    ptySpawn?: PtySpawn;
+    /** Rows retained by tmux for reconnect-time history. */
+    scrollback?: number;
+    /** Allow pane escape sequences to pass through tmux. */
+    tmuxAllowPassthrough?: boolean;
+    /** Delay the inner command until the first client attaches. */
+    tmuxStartOnAttach?: boolean;
+    /** Preserve a dead pane for diagnostics until lifecycle cleanup runs. */
+    keepAliveAfterExit?: boolean;
     /** Injectable for tests; defaults to the real `tmux` binary path. */
     tmuxBin?: string;
 }
+/** Decode tmux's three-digit octal escapes in a `%output` payload. */
+export declare function unescapeControlOutput(value: Uint8Array): Uint8Array;
+/** Byte-exact control commands for one browser input frame. */
+export declare function hexSendKeysCommands(target: string, data: Uint8Array): Buffer[];
+/** Global tmux argv for a control-mode attach. Exported to pin role semantics. */
+export declare function controlAttachArgs(socketPath: string, role: "owner" | "read-only"): string[];
+export interface TmuxManagedOptionSpec {
+    scrollback: number;
+    allowPassthrough: boolean;
+    keepAliveAfterExit: boolean;
+}
+/** Options applied before pane creation so per-pane values take effect. */
+export declare function tmuxManagedOptionCommands(spec: TmuxManagedOptionSpec): string[][];
+/** Extract the pane size from tmux's `%layout-change` notification. */
+export declare function controlLayoutDimensions(line: Uint8Array): {
+    cols: number;
+    rows: number;
+} | undefined;
 /** Resolve the exact tmux executable selected by the current Rynx distribution. */
 export declare function resolveTmuxBin(explicit?: string, env?: NodeJS.ProcessEnv): string;
 /** Deterministic private socket owned by one terminal name. Parent-side
  * shutdown uses the same mapping when the runner child is too wedged to clean
  * up its own tmux server. */
-export declare function tmuxSocketPath(name: string): string;
+export declare function tmuxSocketPath(name: string, ownerPid?: number): string;
+export declare function tmuxInstanceDir(name: string, ownerPid?: number): string;
 /** Read tmux's own output-activity clock for a private terminal window.
  *
  * `#{window_activity}` is an epoch timestamp updated by tmux whenever the pane
@@ -62,17 +92,23 @@ export declare function tmuxSocketPath(name: string): string;
  * may have stalled when the idle reaper needs an independent liveness signal.
  * Missing servers, command failures, timeouts, and unparseable output are all
  * treated as unknown (`null`). */
-export declare function tmuxWindowActivityAt(name: string, tmuxBin?: string): Promise<number | null>;
+export declare function tmuxWindowActivityAt(name: string, tmuxBin?: string, ownerPid?: number): Promise<number | null>;
 /** Whether tmux itself reports an attached client for this private terminal.
  * This remains authoritative if a parent-side attachment bookkeeping edge was
  * missed during a transport failure. */
-export declare function tmuxHasAttachedClient(name: string, tmuxBin?: string): Promise<boolean>;
-/** Best-effort close of one private tmux server. Mirrors reference implementation's bounded
- * `TerminalInstance.close`: attempt `kill-server`, then retire the private
- * socket regardless of command outcome. The registry has already forgotten
- * the resource, so cleanup failure is diagnostic rather than a second
- * lifecycle state. */
-export declare function terminateTmuxServer(name: string, tmuxBin?: string): boolean;
+export declare function tmuxHasAttachedClient(name: string, tmuxBin?: string, ownerPid?: number): Promise<boolean>;
+/** Best-effort close of one private tmux server. Attempt `kill-server`, then
+ * retire the private socket regardless of command outcome. The registry has
+ * already forgotten the resource, so cleanup failure is diagnostic rather than
+ * a second lifecycle state. */
+export declare function terminateTmuxServer(name: string, tmuxBin?: string, ownerPid?: number): boolean;
+/** Reap private terminal servers whose owning runner process is gone. Dirs
+ * without an owner marker are deliberately ignored. */
+export declare function reapOrphanedTerminals(opts?: {
+    root?: string;
+    tmuxBin?: string;
+    isProcessAlive?: (pid: number) => boolean;
+}): number;
 /** Is a usable `tmux` on PATH? Cheap probe for the capability gate. */
 export declare function isTmuxAvailable(tmuxBin?: string): boolean;
 export declare class TmuxTerminal {
@@ -84,8 +120,11 @@ export declare class TmuxTerminal {
     private readonly env;
     private readonly cols;
     private readonly rows;
+    private readonly scrollback;
+    private readonly tmuxAllowPassthrough;
+    private readonly tmuxStartOnAttach;
+    private readonly keepAliveAfterExit;
     private readonly tmuxBin;
-    private readonly injectedSpawn?;
     private started;
     private lastPaneSnapshot;
     /** Shared by every attachment watcher and by the lifecycle watcher's
@@ -93,7 +132,7 @@ export declare class TmuxTerminal {
      * out once per attached client. */
     private paneLivenessFlight?;
     /** Shared by lifecycle callers so capture + pane-dead remains one ordered
-     * reference implementation-style observation per Terminal. */
+     * observation per Terminal. */
     private lifecycleLivenessFlight?;
     constructor(opts: TmuxTerminalOptions);
     /** tmux argv prefix targeting this terminal's private server. */
@@ -101,47 +140,20 @@ export declare class TmuxTerminal {
     /** Create the private tmux server + detached session running the inner
      *  command. Idempotent: a second call is a no-op once the session exists. */
     start(): void;
-    /**
-     * Apply reference implementation's tmux option suite to the private server (inner/terminal.py).
-     * These are NOT cosmetic — several fix real co-drive behavior that the tmux
-     * defaults break:
-     *  - `mouse on`: the web terminal's wheel scrolls the pane's scrollback (and
-     *    mouse events reach a TUI that requests them). Without it, no scrolling.
-     *  - `extended-keys on` + `csi-u`: tmux forwards Kitty Keyboard Protocol / CSI-u
-     *    keys (Ctrl+C, Shift+Enter, modified keys) that codex/claude TUIs request —
-     *    without it tmux downgrades them and the vendor TUI mis-reads modifiers.
-     *  - `escape-time 0`: kills tmux's default 500 ms wait after ESC, which otherwise
-     *    makes arrow keys / Alt-combos / pasted CSI feel laggy or mis-parse.
-     *  - `prefix None` + `prefix2 None` + unbind the prefix table: the user's
-     *    keystrokes (notably C-b) go to the pane, never tmux — a co-drive terminal
-     *    must not intercept a prefix.
-     *  - `focus-events on`, `allow-passthrough on`, `history-limit`: focus reporting,
-     *    passthrough sequences, scrollback depth.
-     *  - `remain-on-exit on` + `exit-empty off`: keep the dead pane + server after the
-     *    inner CLI exits so its last output stays capturable and `#{pane_dead}` reads
-     *    the exit (liveness probe), instead of the server vanishing.
-     *  - `MouseDown3*` unbinds: no right-click menu to spawn extra panes/windows.
-     *  - `status off`: hide tmux chrome. reference implementation keeps the status line only to show
-     *    a conversation link; rynx has none, so the whole line (and its
-     *    `[main] 0:node*` window list) is hidden.
-     * `-q`/`-gq`/`-sq` keep an older tmux that lacks an option from failing launch.
-     * Batched into one invocation with `;` command separators (one spawn).
-     */
-    private configureSession;
     /** Whether the terminal's INNER PROCESS is still running. Probes the pane's
      *  `#{pane_dead}` flag rather than mere session existence: with
      *  `remain-on-exit on` the session/server deliberately outlive the inner CLI's
      *  exit (a dead pane shows tmux's "Pane is dead"), so `has-session` succeeding
      *  no longer implies a live process. Alive only when the session exists AND its
-     *  pane process has not exited. Mirrors reference implementation's `_terminal.is_alive`. */
+     *  pane process has not exited. */
     isAlive(): boolean;
     /** Async pane-liveness probe — MUST NOT block the event loop. The attach
      *  pane-death watcher polls this on an interval; a synchronous `execFileSync`
      *  there stalls the runner child's event loop (freezing the PTY stream → the
-     *  terminal appears "stuck"). Exactly like reference implementation's definitive pane probe,
-     *  every command error is `unknown`; only `#{pane_dead}=1` is `dead`. */
+     *  terminal appears "stuck"). Every command error is `unknown`; only
+     *  `#{pane_dead}=1` is definitive evidence of `dead`. */
     livenessAsync(): Promise<TerminalLiveness>;
-    /** reference implementation's always-on terminal lifecycle watcher first captures the pane:
+    /** The always-on terminal lifecycle watcher first captures the pane:
      * a control command that ran and reports the target missing is terminal exit;
      * a probe that cannot spawn is inconclusive. If capture succeeds, the normal
      * definitive `pane_dead` probe distinguishes live from exited. */
@@ -168,11 +180,11 @@ export declare class TmuxTerminal {
     sendEnter(): void;
     /** Interrupt the pane's running TUI turn with an Escape key — codex/claude both
      *  cancel an in-flight response on a single Esc ("esc to interrupt"). A key NAME
-     *  (no `-l`) so tmux interprets it. Mirrors reference implementation's `inject_interrupt`. */
+     *  (no `-l`) so tmux interprets it. */
     interrupt(): void;
     /** Clear the current input line before an injection so leftover keystrokes
      *  can't prepend to the pasted draft. `C-a` (Home) + `C-k` (kill-to-end) is
-     *  the safe pair — `C-u` only clears backwards from the cursor (reference implementation). */
+     *  the safe pair because `C-u` only clears backwards from the cursor. */
     clearInputLine(): void;
     /** Send one or more tmux key NAMES (e.g. `Enter`, `C-a`) to the pane. */
     private sendKeyNames;
@@ -185,17 +197,14 @@ export declare class TmuxTerminal {
      * that would overflow a `send-keys` argv.
      */
     paste(text: string, bufferName?: string): void;
-    /**
-     * Attach a client. `role: "read-only"` passes tmux `-r` so the viewer cannot
-     * type and `ignore-size` so even its initial PTY dimensions cannot resize the
-     * owner's pane (defense-in-depth on top of the WS bridge dropping input and
-     * resize frames).
-     */
-    attach(role: "owner" | "read-only", dims?: {
+    private execTmuxBuffer;
+    /** Prepare connect-time history without creating a live tmux client. */
+    prepare(role: "owner" | "read-only", dims?: {
         cols?: number;
         rows?: number;
-    }): Promise<TerminalAttachment>;
+    }): Promise<PreparedTerminalAttachment>;
+    private controlModeSeedSpool;
+    private startPullAttachment;
     /** Kill the tmux server (ends the session and all attaches). */
     kill(): void;
 }
-export {};