@rynx-ai/runtime 0.1.0

package/dist/terminal/tmux.js

@@ -0,0 +1,364 @@
+/**
+ * A tmux-backed live terminal — the durable half of rynx's terminal subsystem
+ * (Phase C of the native-integration refactor).
+ *
+ * The tmux SERVER (private socket, one per terminal) holds the real pane PTY and
+ * survives client detach / browser reload / a brief runner reconnect. A client
+ * ATTACH is a short-lived node-pty process bridging the pane's bytes to a caller
+ * (the WS bridge). Multiple attaches can coexist: one owner (read-write) plus
+ * any number of read-only viewers (`tmux attach -r`) — the co-drive model.
+ *
+ * Control commands (new-session / send-keys / has-session / kill) run through
+ * plain `execFile`; only the interactive attach needs a PTY. node-pty is loaded
+ * lazily so importing this module never hard-fails when the native binding is
+ * absent — {@link isTmuxAvailable} + a caller-side capability gate keep the
+ * terminal overlay optional (the structured layer works without it).
+ */
+import { execFile, execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const TMUX_TARGET = "main";
+const DEFAULT_COLS = 80;
+const DEFAULT_ROWS = 24;
+/** tmux pane scrollback depth. Matches the browser xterm `scrollback` so a
+ *  wheel-scroll (tmux copy-mode, enabled by `mouse on`) reaches as far back as
+ *  the terminal shows. Mirrors omnigent's `TerminalEnvSpec.scrollback`. */
+const DEFAULT_SCROLLBACK = 20000;
+/** Is a usable `tmux` on PATH? Cheap probe for the capability gate. */
+export function isTmuxAvailable(tmuxBin = "tmux") {
+    try {
+        execFileSync(tmuxBin, ["-V"], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function loadPtySpawn() {
+    const mod = (await import("node-pty"));
+    return mod.spawn;
+}
+/** Ensure a UTF-8 locale so tmux renders multibyte (CJK) output correctly. A
+ *  pm2/systemd-spawned daemon often has no LANG/LC_*, so tmux treats CJK bytes as
+ *  single-byte and mangles Chinese. omnigent inherits a UTF-8 locale from its launch
+ *  env; a pm2 daemon may not — so inject one when none is present. */
+function withUtf8Locale(env) {
+    const hasUtf8 = [env.LC_ALL, env.LC_CTYPE, env.LANG].some((v) => v != null && /utf-?8/i.test(v));
+    return hasUtf8 ? env : { ...env, LANG: "en_US.UTF-8", LC_CTYPE: "en_US.UTF-8" };
+}
+export class TmuxTerminal {
+    name;
+    socketPath;
+    cwd;
+    command;
+    args;
+    env;
+    cols;
+    rows;
+    tmuxBin;
+    injectedSpawn;
+    started = false;
+    constructor(opts) {
+        this.name = opts.name;
+        this.cwd = opts.cwd;
+        this.command = opts.command ?? process.env.SHELL ?? "/bin/bash";
+        this.args = opts.args ?? [];
+        this.env = withUtf8Locale(opts.env ?? process.env);
+        this.cols = opts.cols ?? DEFAULT_COLS;
+        this.rows = opts.rows ?? DEFAULT_ROWS;
+        this.tmuxBin = opts.tmuxBin ?? "tmux";
+        this.injectedSpawn = opts.ptySpawn;
+        const dir = join(tmpdir(), "rynx-term");
+        mkdirSync(dir, { recursive: true });
+        // A short hash of the (per-session-unique) name keeps the socket path well
+        // under the unix-domain path limit (~104 chars on macOS) — a full session id
+        // like `sess_<uuid>-main` under $TMPDIR would overflow it and fail with
+        // "File name too long". The hash stays unique per terminal.
+        const key = createHash("sha256").update(opts.name).digest("hex").slice(0, 16);
+        this.socketPath = join(dir, `${key}.sock`);
+    }
+    /** tmux argv prefix targeting this terminal's private server. */
+    base() {
+        // `-u` forces tmux to emit UTF-8 even when the launch env has no UTF-8 locale (a
+        // pm2/systemd-spawned daemon often has no LANG) — without it multibyte CJK output
+        // is mangled. Belt-and-suspenders with the UTF-8 locale injected into `this.env`.
+        return ["-u", "-S", this.socketPath];
+    }
+    /** Create the private tmux server + detached session running the inner
+     *  command. Idempotent: a second call is a no-op once the session exists. */
+    start() {
+        if (this.started)
+            return;
+        // Clear any stale server on this socket (a crashed prior run / a test rerun
+        // reusing the name); the socket is unique per session, so this only ever
+        // reaps our own leftover, never a live sibling.
+        try {
+            execFileSync(this.tmuxBin, [...this.base(), "kill-server"], { stdio: "ignore" });
+        }
+        catch {
+            // No stale server — expected on a fresh start.
+        }
+        // `new-session -d` starts detached; `-x/-y` seed the pane size so output
+        // wraps sanely before the first client attaches and resizes it.
+        execFileSync(this.tmuxBin, [
+            ...this.base(),
+            "new-session",
+            "-d",
+            "-s",
+            TMUX_TARGET,
+            "-x",
+            String(this.cols),
+            "-y",
+            String(this.rows),
+            "-c",
+            this.cwd,
+            this.command,
+            ...this.args,
+        ], { env: this.env, stdio: "ignore" });
+        this.configureSession();
+        this.started = true;
+    }
+    /**
+     * Apply omnigent'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. omnigent 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).
+     */
+    configureSession() {
+        const commands = [
+            // input + scrollback
+            ["set-option", "-g", "history-limit", String(DEFAULT_SCROLLBACK)],
+            ["set-option", "-sq", "extended-keys", "on"],
+            ["set-option", "-sq", "extended-keys-format", "csi-u"],
+            ["set-option", "-g", "mouse", "on"],
+            ["set-option", "-g", "focus-events", "on"],
+            ["set-option", "-g", "escape-time", "0"],
+            // persistence: outlive the inner CLI's exit (see `#{pane_dead}` liveness)
+            ["set-option", "-gq", "remain-on-exit", "on"],
+            ["set-option", "-sq", "exit-empty", "off"],
+            // passthrough escape sequences
+            ["set-option", "-g", "allow-passthrough", "on"],
+            // lockdown: no prefix, no right-click pane/window creation
+            ["set-option", "-g", "prefix", "None"],
+            ["set-option", "-g", "prefix2", "None"],
+            ["unbind-key", "-a", "-T", "prefix"],
+            ["unbind-key", "-q", "-T", "root", "MouseDown3Pane"],
+            ["unbind-key", "-q", "-T", "root", "M-MouseDown3Pane"],
+            ["unbind-key", "-q", "-T", "root", "MouseDown3Status"],
+            ["unbind-key", "-q", "-T", "root", "M-MouseDown3Status"],
+            ["unbind-key", "-q", "-T", "root", "MouseDown3StatusLeft"],
+            ["unbind-key", "-q", "-T", "root", "M-MouseDown3StatusLeft"],
+            // hide tmux chrome (no conversation link to show, unlike omnigent)
+            ["set-option", "-g", "status", "off"],
+        ];
+        const argv = [...this.base()];
+        commands.forEach((cmd, i) => {
+            if (i > 0)
+                argv.push(";");
+            argv.push(...cmd);
+        });
+        execFileSync(this.tmuxBin, argv, { env: this.env, stdio: "ignore" });
+    }
+    /** 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 omnigent's `_terminal.is_alive`. */
+    isAlive() {
+        if (!this.started)
+            return false;
+        try {
+            const out = execFileSync(this.tmuxBin, [...this.base(), "list-panes", "-t", TMUX_TARGET, "-F", "#{pane_dead}"], { stdio: ["ignore", "pipe", "ignore"] })
+                .toString()
+                .split(/\s+/)
+                .filter(Boolean);
+            // No panes, or any pane reporting dead (its process exited), → not alive.
+            return out.length > 0 && !out.includes("1");
+        }
+        catch {
+            return false; // session / server gone
+        }
+    }
+    /** 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"). omnigent's `_tmux_session_alive` uses an async
+     *  subprocess + timeout for exactly this reason. */
+    isAliveAsync() {
+        if (!this.started)
+            return Promise.resolve(false);
+        return new Promise((resolve) => {
+            execFile(this.tmuxBin, [...this.base(), "list-panes", "-t", TMUX_TARGET, "-F", "#{pane_dead}"], { timeout: 2000 }, (err, stdout) => {
+                if (err) {
+                    resolve(false);
+                    return;
+                }
+                const panes = stdout.toString().split(/\s+/).filter(Boolean);
+                resolve(panes.length > 0 && !panes.includes("1"));
+            });
+        });
+    }
+    /** Type literal text into the pane (agent injection / co-drive from a
+     *  non-PTY caller). `-l` sends the text literally rather than as key names. */
+    sendKeys(text) {
+        execFile(this.tmuxBin, [...this.base(), "send-keys", "-t", TMUX_TARGET, "-l", "--", text], { env: this.env }, () => undefined);
+    }
+    /**
+     * The visible pane text (synchronous). Used by the claude-native injection
+     * path as a ready-gate (poll for the `❯` prompt glyph before typing) and to
+     * verify a pasted draft landed / left the input box. Returns "" on failure so
+     * a dead pane just reads as empty rather than throwing mid-poll.
+     */
+    capturePane() {
+        try {
+            return execFileSync(this.tmuxBin, [...this.base(), "capture-pane", "-t", TMUX_TARGET, "-p"], {
+                env: this.env,
+                encoding: "utf8",
+            });
+        }
+        catch {
+            return "";
+        }
+    }
+    /** Send a submit Enter as a KEY NAME (no `-l`), committing the input line.
+     *  Kept separate from the paste so a multi-line paste isn't folded into a
+     *  single submit (claude coalesces a rapid stdin burst into a paste). */
+    sendEnter() {
+        this.sendKeyNames("Enter");
+    }
+    /** 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 omnigent's `inject_interrupt`. */
+    interrupt() {
+        this.sendKeyNames("Escape");
+    }
+    /** 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 (omnigent). */
+    clearInputLine() {
+        this.sendKeyNames("C-a", "C-k");
+    }
+    /** Send one or more tmux key NAMES (e.g. `Enter`, `C-a`) to the pane. */
+    sendKeyNames(...keys) {
+        execFileSync(this.tmuxBin, [...this.base(), "send-keys", "-t", TMUX_TARGET, ...keys], {
+            env: this.env,
+            stdio: "ignore",
+        });
+    }
+    /**
+     * Deliver `text` into the pane as a bracketed paste — `load-buffer` (from
+     * stdin, no temp file) then `paste-buffer -p` (bracketed markers keep newlines
+     * as data, so claude treats it as one pasted draft, not N submits) and `-d`
+     * (drop the buffer after). This is the injection body; the caller sends a
+     * separate {@link sendEnter} to submit. Handles multi-line + large messages
+     * that would overflow a `send-keys` argv.
+     */
+    paste(text, bufferName = "rynx-paste") {
+        execFileSync(this.tmuxBin, [...this.base(), "load-buffer", "-b", bufferName, "-"], {
+            env: this.env,
+            input: text,
+            stdio: ["pipe", "ignore", "ignore"],
+        });
+        execFileSync(this.tmuxBin, [...this.base(), "paste-buffer", "-p", "-d", "-b", bufferName, "-t", TMUX_TARGET], { env: this.env, stdio: "ignore" });
+    }
+    /**
+     * Attach a client. `role: "read-only"` passes tmux `-r` so the viewer cannot
+     * type (defense-in-depth on top of the WS bridge dropping input frames).
+     */
+    async attach(role, dims) {
+        this.start();
+        const spawn = this.injectedSpawn ?? (await loadPtySpawn());
+        const args = [...this.base(), "attach-session", "-t", TMUX_TARGET];
+        if (role === "read-only")
+            args.push("-r");
+        const proc = spawn(this.tmuxBin, args, {
+            name: "xterm-256color",
+            cols: dims?.cols ?? this.cols,
+            rows: dims?.rows ?? this.rows,
+            cwd: this.cwd,
+            env: this.env,
+        });
+        // Pane-death watcher: with `remain-on-exit on` a dead pane keeps the attach
+        // process alive (so `proc.onExit` never fires) while tmux paints "Pane is dead".
+        // Poll `#{pane_dead}` and synthesize an exit so the web bridge closes the WS and
+        // shows the dead-pane overlay instead of leaking tmux's "Pane is dead" text
+        // (omnigent: the server closes the socket on pane death → StatusOverlay).
+        // Multi-listener, not a single slot: the runner child (and any future
+        // subscriber) register `onExit`; a single-slot setter would let a later
+        // `onExit` silently CLOBBER an earlier one (that clobber is exactly how the
+        // old owner-slot release was lost — a tab switch then re-attached read-only).
+        const exitListeners = [];
+        let exited = false;
+        const fireExit = (exitCode) => {
+            if (exited)
+                return;
+            exited = true;
+            if (deadTimer)
+                clearInterval(deadTimer);
+            for (const listener of exitListeners)
+                listener({ exitCode });
+        };
+        // Skip the poll under injectedSpawn (tests use a fake pane; `isAlive` shells out
+        // to real tmux). `unref` so a lingering attach never keeps the process alive.
+        const deadTimer = this.injectedSpawn
+            ? undefined
+            : setInterval(() => {
+                if (exited)
+                    return;
+                // ASYNC probe (never execFileSync here — that would block the event loop
+                // and freeze the PTY stream, making the terminal unresponsive).
+                void this.isAliveAsync().then((alive) => {
+                    if (!alive && !exited)
+                        fireExit(0);
+                });
+            }, 1000);
+        deadTimer?.unref?.();
+        proc.onExit((info) => fireExit(info.exitCode));
+        return {
+            onData: (listener) => proc.onData(listener),
+            onExit: (listener) => {
+                exitListeners.push(listener);
+            },
+            write: (data) => proc.write(data),
+            resize: (cols, rows) => proc.resize(cols, rows),
+            kill: () => {
+                if (deadTimer)
+                    clearInterval(deadTimer);
+                proc.kill();
+            },
+        };
+    }
+    /** Kill the tmux server (ends the session and all attaches). */
+    kill() {
+        try {
+            execFileSync(this.tmuxBin, [...this.base(), "kill-server"], { stdio: "ignore" });
+        }
+        catch {
+            // Already gone — nothing to clean up.
+        }
+        this.started = false;
+    }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@rynx-ai/runtime",
+  "version": "0.1.0",
+  "description": "Runtime host that drives local coding-agent CLIs (codex / traex / claude) behind one AgentExecutor + AgentCapabilities contract.",
+  "type": "module",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "node-pty": "^1.0.0",
+    "ws": "^8.21.0",
+    "@rynx-ai/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/runner-main.js dist/claude/native-hook-main.js dist/claude/native-message-display-main.js dist/claude/native-status-main.js"
+  }
+}