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

package/dist/terminal/tmux.d.ts

@@ -1,33 +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;
 }
-/** 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;
+/** 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;
 }
-type PtySpawn = (file: string, args: string[], opts: {
-    name: string;
-    cols: number;
-    rows: number;
-    cwd: string;
-    env: Record<string, string>;
-}) => PtyProcess;
+/** 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 uses
+ * capture failure to identify a vanished server/session. */
+export type TerminalLiveness = "alive" | "dead" | "unknown";
 export interface TmuxTerminalOptions {
     /** Unique name for the tmux session + socket, e.g. `rynx-<sessionId>-<termId>`. */
     name: string;
@@ -38,19 +48,67 @@ 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;
-/** Kill one private tmux server and verify it no longer answers. Missing
- * sockets are already stopped; an existing socket with an unusable tmux
- * command is unproven and returns false. */
-export declare function terminateTmuxServer(name: string, tmuxBin?: string): boolean;
+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
+ * emits bytes. It is deliberately queried out-of-process rather than inferred
+ * from Rynx's forwarded PTY stream: the forwarder/status path is exactly what
+ * 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, 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, 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 {
@@ -62,55 +120,50 @@ 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
+     * pane-dead stage. One Terminal must never fan the same tmux control probe
+     * out once per attached client. */
+    private paneLivenessFlight?;
+    /** Shared by lifecycle callers so capture + pane-dead remains one ordered
+     * observation per Terminal. */
+    private lifecycleLivenessFlight?;
     constructor(opts: TmuxTerminalOptions);
     /** tmux argv prefix targeting this terminal's private server. */
     private base;
     /** 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"). reference implementation's `_tmux_session_alive` uses an async
-     *  subprocess + timeout for exactly this reason. */
-    private isAliveAsync;
+     *  terminal appears "stuck"). Every command error is `unknown`; only
+     *  `#{pane_dead}=1` is definitive evidence of `dead`. */
+    livenessAsync(): Promise<TerminalLiveness>;
+    /** 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. */
+    lifecycleLivenessAsync(): Promise<TerminalLiveness>;
+    /** Compatibility boolean for callers that cannot represent an inconclusive
+     * probe. Unknown must remain live so a transient tmux failure cannot tear down
+     * a healthy native Session. */
+    isAliveAsync(): Promise<boolean>;
+    /** PID of the process currently owning the pane. */
+    panePid(): number | undefined;
     /** 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: string): void;
@@ -127,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;
@@ -144,15 +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 (defense-in-depth on top of the WS bridge dropping input 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 {};