@rynx-ai/runtime 0.1.11-beta.4 → 0.1.11-beta.41

package/dist/terminal/control-parser.d.ts

@@ -0,0 +1,39 @@
+export declare class TmuxControlProtocolError extends Error {
+    readonly name = "TmuxControlProtocolError";
+}
+export interface TmuxControlParserOptions {
+    onOutput(chunk: Uint8Array): void;
+    onControlLine(line: Uint8Array): void;
+    outputChunkBytes?: number;
+    maxControlLineBytes?: number;
+}
+/** Incremental parser for tmux control mode.
+ *
+ * `%output` payloads are decoded directly into fixed-size output chunks. Only
+ * the possible tail of one `\ooo` escape survives between writes. Other
+ * control notifications stay line-oriented and are capped independently.
+ */
+export declare class TmuxControlParser {
+    private readonly onOutput;
+    private readonly onControlLine;
+    private readonly outputChunkBytes;
+    private readonly maxControlLineBytes;
+    private mode;
+    private line;
+    private pane;
+    private escape;
+    private output;
+    private outputLength;
+    private ended;
+    constructor(options: TmuxControlParserOptions);
+    get retainedBytes(): number;
+    write(input: Uint8Array): void;
+    end(): void;
+    private consume;
+    private consumeGeneric;
+    private finishControlLine;
+    private consumePayload;
+    private flushEscapeLiteral;
+    private pushOutput;
+    private flushOutput;
+}

package/dist/terminal/control-parser.js

@@ -0,0 +1,172 @@
+const OUTPUT_PREFIX = Buffer.from("%output ", "ascii");
+const DEFAULT_OUTPUT_CHUNK_BYTES = 64 * 1024;
+const DEFAULT_MAX_CONTROL_LINE_BYTES = 16 * 1024;
+const MAX_PANE_TOKEN_BYTES = 256;
+export class TmuxControlProtocolError extends Error {
+    name = "TmuxControlProtocolError";
+}
+/** Incremental parser for tmux control mode.
+ *
+ * `%output` payloads are decoded directly into fixed-size output chunks. Only
+ * the possible tail of one `\ooo` escape survives between writes. Other
+ * control notifications stay line-oriented and are capped independently.
+ */
+export class TmuxControlParser {
+    onOutput;
+    onControlLine;
+    outputChunkBytes;
+    maxControlLineBytes;
+    mode = "prefix";
+    line = [];
+    pane = [];
+    escape = [];
+    output;
+    outputLength = 0;
+    ended = false;
+    constructor(options) {
+        this.onOutput = options.onOutput;
+        this.onControlLine = options.onControlLine;
+        this.outputChunkBytes = positiveInteger(options.outputChunkBytes ?? DEFAULT_OUTPUT_CHUNK_BYTES, "outputChunkBytes");
+        this.maxControlLineBytes = positiveInteger(options.maxControlLineBytes ?? DEFAULT_MAX_CONTROL_LINE_BYTES, "maxControlLineBytes");
+        this.output = Buffer.allocUnsafe(this.outputChunkBytes);
+    }
+    get retainedBytes() {
+        return this.line.length + this.pane.length + this.escape.length + this.outputLength;
+    }
+    write(input) {
+        if (this.ended)
+            throw new TmuxControlProtocolError("tmux control parser has ended");
+        const bytes = Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+        for (const byte of bytes)
+            this.consume(byte);
+    }
+    end() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        if (this.mode === "payload") {
+            this.flushEscapeLiteral();
+            this.flushOutput();
+        }
+        this.line = [];
+        this.pane = [];
+        this.escape = [];
+    }
+    consume(byte) {
+        if (this.mode === "payload") {
+            this.consumePayload(byte);
+            return;
+        }
+        if (this.mode === "pane") {
+            if (byte === 0x20) {
+                if (this.pane.length === 0) {
+                    this.line = [...OUTPUT_PREFIX];
+                    this.consumeGeneric(byte);
+                }
+                else {
+                    this.mode = "payload";
+                    this.pane = [];
+                }
+                return;
+            }
+            if (byte === 0x0a) {
+                this.line = [...OUTPUT_PREFIX, ...this.pane];
+                this.pane = [];
+                this.finishControlLine();
+                return;
+            }
+            this.pane.push(byte);
+            if (this.pane.length > MAX_PANE_TOKEN_BYTES) {
+                throw new TmuxControlProtocolError("tmux output pane token exceeded its limit");
+            }
+            return;
+        }
+        this.consumeGeneric(byte);
+    }
+    consumeGeneric(byte) {
+        if (byte === 0x0a) {
+            this.finishControlLine();
+            return;
+        }
+        this.line.push(byte);
+        if (this.line.length > this.maxControlLineBytes) {
+            throw new TmuxControlProtocolError(`tmux control line exceeded ${this.maxControlLineBytes} bytes`);
+        }
+        if (this.line.length === OUTPUT_PREFIX.length) {
+            let outputPrefix = true;
+            for (let index = 0; index < OUTPUT_PREFIX.length; index += 1) {
+                if (this.line[index] !== OUTPUT_PREFIX[index]) {
+                    outputPrefix = false;
+                    break;
+                }
+            }
+            if (outputPrefix) {
+                this.line = [];
+                this.mode = "pane";
+            }
+        }
+    }
+    finishControlLine() {
+        if (this.line.at(-1) === 0x0d)
+            this.line.pop();
+        this.onControlLine(Uint8Array.from(this.line));
+        this.line = [];
+        this.pane = [];
+        this.mode = "prefix";
+    }
+    consumePayload(byte) {
+        if (byte === 0x0a) {
+            this.flushEscapeLiteral();
+            this.flushOutput();
+            this.mode = "prefix";
+            return;
+        }
+        if (this.escape.length > 0) {
+            this.escape.push(byte);
+            if (this.escape.length === 4) {
+                if (this.escape.slice(1).every(isOctalDigit)) {
+                    this.pushOutput((this.escape[1] - 0x30) * 64 +
+                        (this.escape[2] - 0x30) * 8 +
+                        (this.escape[3] - 0x30));
+                }
+                else {
+                    for (const escapedByte of this.escape)
+                        this.pushOutput(escapedByte);
+                }
+                this.escape = [];
+            }
+            return;
+        }
+        if (byte === 0x5c) {
+            this.escape = [byte];
+            return;
+        }
+        this.pushOutput(byte);
+    }
+    flushEscapeLiteral() {
+        for (const byte of this.escape)
+            this.pushOutput(byte);
+        this.escape = [];
+    }
+    pushOutput(byte) {
+        this.output[this.outputLength] = byte;
+        this.outputLength += 1;
+        if (this.outputLength === this.output.byteLength)
+            this.flushOutput();
+    }
+    flushOutput() {
+        if (this.outputLength === 0)
+            return;
+        this.onOutput(Uint8Array.from(this.output.subarray(0, this.outputLength)));
+        this.outputLength = 0;
+    }
+}
+function isOctalDigit(value) {
+    return value >= 0x30 && value <= 0x37;
+}
+function positiveInteger(value, field) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new TypeError(`${field} must be a positive integer`);
+    }
+    return value;
+}

package/dist/terminal/registry.d.ts

@@ -2,41 +2,44 @@
  * Per-runner registry of live {@link TmuxTerminal}s, keyed by terminal id.
  *
  * Owns terminal lifecycle. Read-only vs read-write is decided PURELY by the
- * requested role (the caller derives it from the viewer's permission level),
- * exactly like reference implementation's terminal attach (`terminal_attach.py`: `read_only`
- * from the URL → `-r`). There is deliberately NO stateful "first owner wins,
+ * requested role (the caller derives it from the viewer's permission level).
+ * There is deliberately NO stateful "first owner wins,
  * later owners downgraded" slot: that rynx-only mechanism leaked its owner slot
  * across a detach (the release ran on the attachment's `onExit`, which the
  * runner child's own `onExit` clobbered), so a tab switch away then back
  * re-attached read-only and silently dropped every keystroke. Multiple
  * read-write owners coexisting is fine — tmux merges their input.
  */
-import { TmuxTerminal, type TerminalAttachment, type TmuxTerminalOptions } from "./tmux.js";
+import { TmuxTerminal, type PreparedTerminalAttachment, type TmuxTerminalOptions } from "./tmux.js";
 export type TerminalRole = "owner" | "read-only";
-export interface AttachResult {
-    attachment: TerminalAttachment;
-    /** The granted role — always the requested role (no downgrade). */
+export type TerminalLifecycle = "required" | "auxiliary";
+export type TerminalLaunchOptions = Omit<TmuxTerminalOptions, "name"> & {
+    lifecycle: TerminalLifecycle;
+};
+export interface PrepareResult {
+    preparation: PreparedTerminalAttachment;
     role: TerminalRole;
 }
 export declare class TerminalRegistry {
     private readonly terminals;
     get(id: string): TmuxTerminal | undefined;
+    lifecycle(id: string): TerminalLifecycle | undefined;
     has(id: string): boolean;
     /** Create + start a terminal under `id`, reusing a LIVE existing one. If the
      *  existing terminal's tmux session died (its TUI process exited), drop it and
      *  relaunch — so a reconnect after the pane died restarts the terminal instead
      *  of attaching to a dead session. `name` is derived from the id so the tmux
      *  socket is unique per terminal. */
-    getOrCreate(id: string, opts: Omit<TmuxTerminalOptions, "name">): TmuxTerminal;
-    /** Attach a client at the requested role (`owner` → read-write, `read-only`
-     *  → `tmux attach -r`). Throws if the terminal id is unknown (create it
-     *  first). */
-    attach(id: string, requestedRole: TerminalRole, dims?: {
+    getOrCreate(id: string, opts: TerminalLaunchOptions): TmuxTerminal;
+    /** Move a live resource to a new logical id. Target collision is atomic. */
+    transfer(sourceId: string, targetId: string): void;
+    prepare(id: string, requestedRole: TerminalRole, dims?: {
         cols?: number;
         rows?: number;
-    }): Promise<AttachResult>;
-    /** Kill a terminal's tmux server and drop it. */
-    close(id: string): void;
+    }): Promise<PrepareResult>;
+    /** Kill a terminal's tmux server and drop it. When `expected` is supplied,
+     *  close only if that exact instance still owns the id. */
+    close(id: string, expected?: TmuxTerminal): boolean;
     /** Kill every terminal (runner shutdown). */
     closeAll(): void;
 }

package/dist/terminal/registry.js

@@ -2,20 +2,22 @@
  * Per-runner registry of live {@link TmuxTerminal}s, keyed by terminal id.
  *
  * Owns terminal lifecycle. Read-only vs read-write is decided PURELY by the
- * requested role (the caller derives it from the viewer's permission level),
- * exactly like reference implementation's terminal attach (`terminal_attach.py`: `read_only`
- * from the URL → `-r`). There is deliberately NO stateful "first owner wins,
+ * requested role (the caller derives it from the viewer's permission level).
+ * There is deliberately NO stateful "first owner wins,
  * later owners downgraded" slot: that rynx-only mechanism leaked its owner slot
  * across a detach (the release ran on the attachment's `onExit`, which the
  * runner child's own `onExit` clobbered), so a tab switch away then back
  * re-attached read-only and silently dropped every keystroke. Multiple
  * read-write owners coexisting is fine — tmux merges their input.
  */
-import { TmuxTerminal } from "./tmux.js";
+import { TmuxTerminal, } from "./tmux.js";
 export class TerminalRegistry {
     terminals = new Map();
     get(id) {
-        return this.terminals.get(id);
+        return this.terminals.get(id)?.terminal;
+    }
+    lifecycle(id) {
+        return this.terminals.get(id)?.lifecycle;
     }
     has(id) {
         return this.terminals.has(id);
@@ -27,40 +29,59 @@ export class TerminalRegistry {
      *  socket is unique per terminal. */
     getOrCreate(id, opts) {
         const existing = this.terminals.get(id);
-        if (existing && existing.isAlive())
-            return existing;
+        if (existing && existing.terminal.isAlive()) {
+            if (existing.lifecycle !== opts.lifecycle) {
+                throw new Error(`terminal ${id} lifecycle does not match its live resource`);
+            }
+            return existing.terminal;
+        }
         if (existing) {
             // Dead pane (its TUI exited) — kill the husk + drop it before relaunching.
+            this.terminals.delete(id);
             try {
-                existing.kill();
+                existing.terminal.kill();
             }
             catch {
                 // already gone — fine
             }
-            this.terminals.delete(id);
         }
-        const terminal = new TmuxTerminal({ ...opts, name: id });
+        const { lifecycle, ...terminalOptions } = opts;
+        const terminal = new TmuxTerminal({ ...terminalOptions, name: id });
         terminal.start();
-        this.terminals.set(id, terminal);
+        this.terminals.set(id, { terminal, lifecycle });
         return terminal;
     }
-    /** Attach a client at the requested role (`owner` → read-write, `read-only`
-     *  → `tmux attach -r`). Throws if the terminal id is unknown (create it
-     *  first). */
-    async attach(id, requestedRole, dims) {
+    /** Move a live resource to a new logical id. Target collision is atomic. */
+    transfer(sourceId, targetId) {
+        if (sourceId === targetId)
+            return;
+        if (this.terminals.has(targetId)) {
+            throw new Error(`terminal ${targetId} already exists`);
+        }
+        const source = this.terminals.get(sourceId);
+        if (!source)
+            throw new Error(`terminal ${sourceId} does not exist`);
+        this.terminals.delete(sourceId);
+        this.terminals.set(targetId, source);
+    }
+    async prepare(id, requestedRole, dims) {
         const terminal = this.terminals.get(id);
         if (!terminal)
             throw new Error(`terminal ${id} does not exist`);
-        const attachment = await terminal.attach(requestedRole, dims);
-        return { attachment, role: requestedRole };
+        const preparation = await terminal.terminal.prepare(requestedRole, dims);
+        return { preparation, role: requestedRole };
     }
-    /** Kill a terminal's tmux server and drop it. */
-    close(id) {
-        const terminal = this.terminals.get(id);
-        if (!terminal)
-            return;
-        terminal.kill();
+    /** Kill a terminal's tmux server and drop it. When `expected` is supplied,
+     *  close only if that exact instance still owns the id. */
+    close(id, expected) {
+        const entry = this.terminals.get(id);
+        if (!entry || (expected && entry.terminal !== expected))
+            return false;
+        // Remove the resource before best-effort close so a failed kill cannot
+        // leave a dead registry entry that later attaches will reuse.
         this.terminals.delete(id);
+        entry.terminal.kill();
+        return true;
     }
     /** Kill every terminal (runner shutdown). */
     closeAll() {

package/dist/terminal/spool.d.ts

@@ -0,0 +1,47 @@
+export interface TerminalSpoolRead {
+    data: Uint8Array;
+    nextOffset: number;
+    done: boolean;
+    finalOffset?: number;
+}
+export declare class TerminalSpoolCapacityError extends Error {
+    readonly name = "TerminalSpoolCapacityError";
+}
+export declare class TerminalSpoolProtocolError extends Error {
+    readonly 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 declare class SegmentedTerminalSpool {
+    readonly directory: string;
+    readonly segmentBytes: number;
+    readonly quotaBytes: number | undefined;
+    private readonly segments;
+    private writeOffset;
+    private readOffset;
+    private ended;
+    private closed;
+    private failure;
+    private pending;
+    constructor(options?: {
+        segmentBytes?: number;
+        quotaBytes?: number;
+        directory?: string;
+    });
+    get retainedBytes(): number;
+    get finalOffset(): number | undefined;
+    append(input: Uint8Array): void;
+    end(): void;
+    fail(error: Error): void;
+    read(offset: number, maxBytes: number): Promise<TerminalSpoolRead>;
+    close(): void;
+    private assertWritable;
+    private createSegment;
+    private settlePending;
+    private readNow;
+    private discardConsumedSegments;
+}

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;
+}