@rynx-ai/runtime 0.1.11-beta.2 → 0.1.11-beta.21

package/dist/runner/protocol.d.ts

@@ -6,7 +6,8 @@
  * (`live.ensure` / `inject` / `live.interrupt`) plus per-thread capabilities and
  * terminal attachment; the reply channels mirror each request's `reqId`.
  */
-import { AgentRuntimeError, type ResolvedExecutionSnapshot, type RuntimeUserInput, type SessionInteractionResolution, type SessionEvent, type SessionWorkspaceSnapshot } from "@rynx-ai/core";
+import { AgentRuntimeError, type InjectOutcome, type ResolvedExecutionSnapshot, type RuntimeUserInput, type SessionInteractionResolution, type SessionEvent, type SessionWorkspaceSnapshot } from "@rynx-ai/core";
+export type { InjectOutcome } from "@rynx-ai/core";
 import type { ResolveInteractionResult } from "../interactions.js";
 /** A runtime error flattened for the wire; rebuilt parent-side as `AgentRuntimeError`. */
 export interface WireError {
@@ -22,13 +23,6 @@ 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";
-/** Outcome of an `inject`. `injected` = the app-server / tmux accepted the turn.
- *  `notLive` = no live forwarder for this session (caller may use the run path).
- *  `notReady` = live but not ready within the park window; `failed` = injection
- *  threw. For BOTH notReady and failed the caller reports an error and MUST NOT
- *  re-run the turn (re-running would double-write alongside the forwarder).
- *  Mirrors reference implementation's "inject failure ⇒ response.failed, never re-run locally". */
-export type InjectOutcome = "injected" | "notLive" | "notReady" | "failed";
 /** Parent → child. Terminal PTY bytes ride `term.input` base64-encoded so the
  *  NDJSON line framing stays intact (raw bytes contain newlines). */
 export type ToChild = {
@@ -70,8 +64,9 @@ export type ToChild = {
 }
 /** Eagerly bring up a session's live codex TUI + forwarder (codex-native), so
  *  its turns mirror to the bus regardless of whether the web has attached the
- *  terminal. Idempotent; the child replies `live.ready` (echoing `reqId`) once
- *  the thread is bound. */
+ *  terminal. For Codex-lineage fresh sessions, `live.ready` acknowledges that
+ *  the pane and observer exist; background thread discovery races the
+ *  executor's bridge wait. */
  | {
     t: "live.ensure";
     reqId: string;
@@ -160,8 +155,9 @@ export type FromChild = {
     execution: ResolvedExecutionSnapshot;
     parentSessionId?: string;
 }
-/** Result of a `live.ensure`: `ok` once the requested gate is reached (pane
- *  started for setup, otherwise native thread bound). Echoes `reqId`. */
+/** Result of a `live.ensure`: for Codex-lineage sessions `ok` means the pane
+ *  and observer started; thread discovery continues in parallel with
+ *  injection. Other Providers retain their own readiness gate. */
  | {
     t: "live.ready";
     reqId: string;
@@ -169,9 +165,9 @@ export type FromChild = {
     ok: boolean;
     error?: string;
 }
-/** Result of an `inject`: `outcome` distinguishes injected / notLive / notReady /
- *  failed so the caller never falls back to a second output path on a live
- *  session. Echoes the request `reqId`. */
+/** Result of an `inject`: `outcome` distinguishes a new turn, an active-turn
+ *  steer, and failures so the caller never falls back to a second output path.
+ *  Echoes the request `reqId`. */
  | {
     t: "injected";
     reqId: string;

package/dist/runner/startup-policy.d.ts

@@ -0,0 +1,4 @@
+import type { AgentRuntimeId } from "@rynx-ai/core";
+/** Current live providers are native CLI sessions. Keep this explicit so a
+ * future non-native provider does not silently inherit their startup budget. */
+export declare function isManagedNativeProvider(provider: AgentRuntimeId | undefined): provider is AgentRuntimeId;

package/dist/runner/startup-policy.js

@@ -0,0 +1,5 @@
+/** Current live providers are native CLI sessions. Keep this explicit so a
+ * future non-native provider does not silently inherit their startup budget. */
+export function isManagedNativeProvider(provider) {
+    return provider === "codex" || provider === "traex" || provider === "claude";
+}

package/dist/terminal/claude-tui.d.ts

@@ -18,6 +18,8 @@ export interface ClaudeTuiArgs {
     settingSources?: string;
     /** Launch model (`--model`); omit to use claude's default. */
     model?: string;
+    /** Native Claude Code effort (`--effort`); omit to use its default. */
+    reasoningEffort?: string;
     /** Agent instructions appended to Claude Code's native system prompt. */
     appendSystemPrompt?: string;
     /** Resume a specific prior claude session (`--resume <id>`). */
@@ -36,4 +38,4 @@ export interface ClaudeTuiArgs {
  * Build the `claude` argv for an interactive, co-drivable TUI:
  * `[..extra] [--resume <id>] [--model <m>] [--append-system-prompt <text>] --settings <json>`.
  */
-export declare function buildClaudeTuiArgs({ settingsJson, settingSources, model, appendSystemPrompt, resume, forkSession, sessionId, additionalDirs, extraArgs, }: ClaudeTuiArgs): string[];
+export declare function buildClaudeTuiArgs({ settingsJson, settingSources, model, reasoningEffort, appendSystemPrompt, resume, forkSession, sessionId, additionalDirs, extraArgs, }: ClaudeTuiArgs): string[];

package/dist/terminal/claude-tui.js

@@ -2,7 +2,7 @@
  * Build the `claude` argv for an interactive, co-drivable TUI:
  * `[..extra] [--resume <id>] [--model <m>] [--append-system-prompt <text>] --settings <json>`.
  */
-export function buildClaudeTuiArgs({ settingsJson, settingSources, model, appendSystemPrompt, resume, forkSession = false, sessionId, additionalDirs = [], extraArgs = [], }) {
+export function buildClaudeTuiArgs({ settingsJson, settingSources, model, reasoningEffort, appendSystemPrompt, resume, forkSession = false, sessionId, additionalDirs = [], extraArgs = [], }) {
     const args = [...extraArgs];
     if (additionalDirs.length > 0)
         args.push("--add-dir", ...additionalDirs);
@@ -16,6 +16,8 @@ export function buildClaudeTuiArgs({ settingsJson, settingSources, model, append
         args.push("--session-id", sessionId);
     if (model)
         args.push("--model", model);
+    if (reasoningEffort)
+        args.push("--effort", reasoningEffort);
     if (appendSystemPrompt)
         args.push("--append-system-prompt", appendSystemPrompt);
     args.push("--settings", settingsJson);

package/dist/terminal/tmux.d.ts

@@ -43,6 +43,29 @@ export interface TmuxTerminalOptions {
     /** Injectable for tests; defaults to the real `tmux` binary path. */
     tmuxBin?: string;
 }
+/** 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;
+/** 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): 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>;
+/** 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;
 /** Is a usable `tmux` on PATH? Cheap probe for the capability gate. */
 export declare function isTmuxAvailable(tmuxBin?: string): boolean;
 export declare class TmuxTerminal {
@@ -102,7 +125,9 @@ export declare class TmuxTerminal {
      *  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;
+    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;
@@ -138,7 +163,9 @@ export declare class TmuxTerminal {
     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).
+     * 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?: {
         cols?: number;

package/dist/terminal/tmux.js

@@ -16,7 +16,7 @@
  */
 import { execFile, execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, unlinkSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 const TMUX_TARGET = "main";
@@ -26,8 +26,106 @@ const DEFAULT_ROWS = 24;
  *  wheel-scroll (tmux copy-mode, enabled by `mouse on`) reaches as far back as
  *  the terminal shows. Mirrors reference implementation's `TerminalEnvSpec.scrollback`. */
 const DEFAULT_SCROLLBACK = 20000;
+/** Resolve the exact tmux executable selected by the current Rynx distribution. */
+export function resolveTmuxBin(explicit, env = process.env) {
+    if (explicit !== undefined)
+        return explicit;
+    if (Object.hasOwn(env, "RYNX_TMUX_BIN")) {
+        return env.RYNX_TMUX_BIN?.trim() ?? "";
+    }
+    return "tmux";
+}
+/** 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 function tmuxSocketPath(name) {
+    const key = createHash("sha256").update(name).digest("hex").slice(0, 16);
+    return join(tmpdir(), "rynx-term", `${key}.sock`);
+}
+/** 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 function tmuxWindowActivityAt(name, tmuxBin = resolveTmuxBin()) {
+    const socketPath = tmuxSocketPath(name);
+    return new Promise((resolve) => {
+        execFile(tmuxBin, ["-S", socketPath, "display-message", "-p", "-t", TMUX_TARGET, "#{window_activity}"], { timeout: 2_000 }, (error, stdout) => {
+            if (error) {
+                resolve(null);
+                return;
+            }
+            const raw = stdout.toString().trim();
+            if (!raw) {
+                resolve(null);
+                return;
+            }
+            const value = Number(raw);
+            resolve(Number.isFinite(value) ? value : 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 function tmuxHasAttachedClient(name, tmuxBin = resolveTmuxBin()) {
+    const socketPath = tmuxSocketPath(name);
+    return new Promise((resolve) => {
+        execFile(tmuxBin, ["-S", socketPath, "list-clients", "-t", TMUX_TARGET, "-F", "#{client_name}"], { timeout: 2_000 }, (error, stdout) => {
+            resolve(!error && stdout.toString().split("\n").some((line) => line.trim().length > 0));
+        });
+    });
+}
+/** 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 function terminateTmuxServer(name, tmuxBin = resolveTmuxBin()) {
+    const socketPath = tmuxSocketPath(name);
+    if (!existsSync(socketPath))
+        return true;
+    const base = ["-u", "-S", socketPath];
+    try {
+        execFileSync(tmuxBin, [...base, "kill-server"], { stdio: "ignore" });
+    }
+    catch {
+        // A server may have exited between existsSync and kill-server. Verify below.
+    }
+    try {
+        execFileSync(tmuxBin, [...base, "has-session", "-t", TMUX_TARGET], {
+            stdio: "ignore",
+        });
+        return false;
+    }
+    catch (error) {
+        // Only a real tmux exit status proves the server/session is absent. Spawn
+        // failures (missing/unexecutable tmux) leave liveness unproven and must not
+        // unlink a socket that could still belong to a live server.
+        if (!error ||
+            typeof error !== "object" ||
+            !("status" in error) ||
+            typeof error.status !== "number") {
+            return false;
+        }
+        try {
+            // tmux custom-socket servers can exit while leaving the filesystem entry
+            // behind. Remove that verified-stale socket so process/socket inventories
+            // do not accumulate dead terminals forever.
+            unlinkSync(socketPath);
+            return true;
+        }
+        catch (unlinkError) {
+            return Boolean(unlinkError &&
+                typeof unlinkError === "object" &&
+                "code" in unlinkError &&
+                unlinkError.code === "ENOENT");
+        }
+    }
+}
 /** Is a usable `tmux` on PATH? Cheap probe for the capability gate. */
-export function isTmuxAvailable(tmuxBin = "tmux") {
+export function isTmuxAvailable(tmuxBin = resolveTmuxBin()) {
     try {
         execFileSync(tmuxBin, ["-V"], { stdio: "ignore" });
         return true;
@@ -68,7 +166,7 @@ export class TmuxTerminal {
         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.tmuxBin = resolveTmuxBin(opts.tmuxBin);
         this.injectedSpawn = opts.ptySpawn;
         const dir = join(tmpdir(), "rynx-term");
         mkdirSync(dir, { recursive: true });
@@ -76,8 +174,7 @@ export class TmuxTerminal {
         // 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`);
+        this.socketPath = tmuxSocketPath(opts.name);
     }
     /** tmux argv prefix targeting this terminal's private server. */
     base() {
@@ -221,6 +318,19 @@ export class TmuxTerminal {
             });
         });
     }
+    /** PID of the process currently owning the pane. */
+    panePid() {
+        if (!this.started)
+            return undefined;
+        try {
+            const value = execFileSync(this.tmuxBin, [...this.base(), "list-panes", "-t", TMUX_TARGET, "-F", "#{pane_pid}"], { stdio: ["ignore", "pipe", "ignore"] }).toString().trim().split(/\s+/)[0];
+            const pid = Number(value);
+            return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined;
+        }
+        catch {
+            return 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) {
@@ -286,14 +396,17 @@ export class TmuxTerminal {
     }
     /**
      * 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).
+     * 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).
      */
     async attach(role, dims) {
         this.start();
         const spawn = this.injectedSpawn ?? (await loadPtySpawn());
-        const args = [...this.base(), "attach-session", "-t", TMUX_TARGET];
+        const args = [...this.base(), "attach-session"];
         if (role === "read-only")
-            args.push("-r");
+            args.push("-r", "-f", "ignore-size");
+        args.push("-t", TMUX_TARGET);
         const proc = spawn(this.tmuxBin, args, {
             name: "xterm-256color",
             cols: dims?.cols ?? this.cols,
@@ -353,12 +466,7 @@ export class TmuxTerminal {
     }
     /** 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.
-        }
+        terminateTmuxServer(this.name, this.tmuxBin);
         this.started = false;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rynx-ai/runtime",
-  "version": "0.1.11-beta.2",
+  "version": "0.1.11-beta.21",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rynx-ai/rynx.git",
@@ -24,9 +24,10 @@
     }
   },
   "dependencies": {
-    "node-pty": "^1.0.0",
+    "node-pty": "1.2.0-beta.15",
+    "smol-toml": "1.7.1",
     "ws": "^8.21.0",
-    "@rynx-ai/core": "0.1.11-beta.2"
+    "@rynx-ai/core": "0.1.11-beta.21"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"