@rynx-ai/runtime 0.1.11-beta.3 → 0.1.11-beta.30

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 InjectResult, type ResolvedExecutionSnapshot, type RuntimeTurnOptions, type RuntimeUserInput, type SessionCollaborationMode, type SessionInteractionResolution, type SessionEvent, type SessionWorkspaceSnapshot } from "@rynx-ai/core";
+export type { InjectOutcome, InjectResult } 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,16 +23,17 @@ 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 = {
+    t: "mirror.image.ack";
+    transferId: string;
+    seq: number;
+} | {
+    t: "mirror.image.hold";
+    transferId: string;
+    seq: number;
+} | {
     t: "cap";
     capId: string;
     name: CapName;
@@ -70,8 +72,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. Fresh sessions connect the discovery listener before TUI launch;
+ *  known-thread resumes launch the TUI after backend preload and attach their
+ *  observer in the background. */
  | {
     t: "live.ensure";
     reqId: string;
@@ -93,6 +96,7 @@ export type ToChild = {
     t: "inject";
     reqId: string;
     localThreadId: string;
+    options?: RuntimeTurnOptions;
 } & ({
     input: RuntimeUserInput;
     text?: never;
@@ -100,6 +104,14 @@ export type ToChild = {
     text: string;
     input?: never;
 }))
+/** Apply a Codex-lineage collaboration mode to an already-loaded native
+ * thread. This control path never starts a runner or waits for a new Turn. */
+ | {
+    t: "collaboration.update";
+    reqId: string;
+    localThreadId: string;
+    mode: SessionCollaborationMode;
+}
 /** Interrupt the session's active turn — the web Stop button. codex: app-server
  *  `turn/interrupt`; claude: an Escape keystroke to the pane. The child replies
  *  `interrupted` (echoing `reqId`). */
@@ -147,6 +159,24 @@ export type FromChild = {
     t: "mirror";
     sessionId: string;
     event: SessionEvent;
+    /** Parent-local completion marker used after a chunked image is rebuilt. */
+    transferId?: string;
+    seq?: number;
+} | {
+    t: "mirror.image.begin";
+    transferId: string;
+    sessionId: string;
+    event: SessionEvent;
+    totalChars: number;
+} | {
+    t: "mirror.image.chunk";
+    transferId: string;
+    seq: number;
+    data: string;
+} | {
+    t: "mirror.image.commit";
+    transferId: string;
+    seq: number;
 }
 /** The session rotated to a fresh machine-session (claude `/clear`·`/fork`): the
  *  child re-pointed its mirror to `to` and asks the daemon to alias the runner
@@ -160,24 +190,26 @@ 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 backend
+ *  preload and pane launch completed. A resume observer and fresh-thread
+ *  discovery may continue in the background. Other Providers retain their
+ *  own readiness gate. */
  | {
     t: "live.ready";
     reqId: string;
     localThreadId: string;
     ok: boolean;
-    error?: string;
+    error?: WireError;
 }
-/** 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`: `result.outcome` distinguishes a new turn, an
+ * active-turn steer, and failures. Successful results also carry the
+ * runtime-owned canonical Response identity. Echoes the request `reqId`. */
  | {
     t: "injected";
     reqId: string;
     localThreadId: string;
-    outcome: InjectOutcome;
-    error?: string;
+    result: InjectResult;
+    error?: WireError;
 }
 /** Result of a `live.interrupt`: `ok` when an active turn was interrupted (false
  *  when there was none). Echoes the request `reqId`. */
@@ -186,13 +218,24 @@ export type FromChild = {
     reqId: string;
     localThreadId: string;
     ok: boolean;
-    error?: string;
+    error?: WireError;
+} | {
+    t: "collaboration.updated";
+    reqId: string;
+    localThreadId: string;
+    ok: boolean;
+    error?: WireError;
 } | {
     t: "interaction.resolved";
     reqId: string;
     localThreadId: string;
     result: ResolveInteractionResult;
 };
+/** Internal runner wire bounds. Generated images are already subject to the
+ * Session image byte limit; chunks keep the NDJSON pipe and parser bounded and
+ * each chunk is acknowledged before the next is sent. */
+export declare const RUNNER_IMAGE_CHUNK_CHARS: number;
+export declare const RUNNER_IMAGE_MAX_RESULT_CHARS: number;
 /** Encode a message as a single NDJSON line (newline included). */
 export declare function encodeMessage(msg: ToChild | FromChild): string;
 /** Parse one NDJSON line; returns `null` for blank lines or malformed JSON. */

package/dist/runner/protocol.js

@@ -7,6 +7,11 @@
  * terminal attachment; the reply channels mirror each request's `reqId`.
  */
 import { AgentRuntimeError, } from "@rynx-ai/core";
+/** Internal runner wire bounds. Generated images are already subject to the
+ * Session image byte limit; chunks keep the NDJSON pipe and parser bounded and
+ * each chunk is acknowledged before the next is sent. */
+export const RUNNER_IMAGE_CHUNK_CHARS = 32 * 1024;
+export const RUNNER_IMAGE_MAX_RESULT_CHARS = 8 * 1024 * 1024;
 /** Encode a message as a single NDJSON line (newline included). */
 export function encodeMessage(msg) {
     return `${JSON.stringify(msg)}\n`;

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

@@ -0,0 +1,7 @@
+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;
+/** Codex-lineage providers own app-server, thread-discovery, and injection
+ * phase errors. Claude instead retains its parent-owned SessionStart gate. */
+export declare function isCodexLineageProvider(provider: AgentRuntimeId | undefined): provider is Exclude<AgentRuntimeId, "claude">;

package/dist/runner/startup-policy.js

@@ -0,0 +1,10 @@
+/** 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";
+}
+/** Codex-lineage providers own app-server, thread-discovery, and injection
+ * phase errors. Claude instead retains its parent-owned SessionStart gate. */
+export function isCodexLineageProvider(provider) {
+    return provider === "codex" || provider === "traex";
+}

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/registry.js

@@ -31,13 +31,13 @@ export class TerminalRegistry {
             return existing;
         if (existing) {
             // Dead pane (its TUI exited) — kill the husk + drop it before relaunching.
+            this.terminals.delete(id);
             try {
                 existing.kill();
             }
             catch {
                 // already gone — fine
             }
-            this.terminals.delete(id);
         }
         const terminal = new TmuxTerminal({ ...opts, name: id });
         terminal.start();
@@ -59,8 +59,9 @@ export class TerminalRegistry {
         const terminal = this.terminals.get(id);
         if (!terminal)
             return;
-        terminal.kill();
+        // reference implementation removes the resource from its registry before best-effort close.
         this.terminals.delete(id);
+        terminal.kill();
     }
     /** Kill every terminal (runner shutdown). */
     closeAll() {

package/dist/terminal/tmux.d.ts

@@ -11,6 +11,11 @@ export interface TerminalAttachment {
     /** Detach this client. The tmux server + pane keep running. */
     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. */
+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;
@@ -43,13 +48,30 @@ 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;
-/** 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. */
+/** 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>;
+/** 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;
 /** Is a usable `tmux` on PATH? Cheap probe for the capability gate. */
 export declare function isTmuxAvailable(tmuxBin?: string): boolean;
@@ -65,6 +87,14 @@ export declare class TmuxTerminal {
     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
+     * reference implementation-style observation per Terminal. */
+    private lifecycleLivenessFlight?;
     constructor(opts: TmuxTerminalOptions);
     /** tmux argv prefix targeting this terminal's private server. */
     private base;
@@ -108,9 +138,20 @@ export declare class TmuxTerminal {
     /** 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"). Exactly like reference implementation's definitive pane probe,
+     *  every command error is `unknown`; only `#{pane_dead}=1` is `dead`. */
+    livenessAsync(): Promise<TerminalLiveness>;
+    /** reference implementation's 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;
@@ -146,7 +187,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;