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

package/dist/index.d.ts

@@ -9,10 +9,10 @@ export type { CodexCapabilities, CapabilityResult, CodexRuntimeStatus, } from ".
 export type { ClaudeForkIntent, CodexSessionStore, CodexSessionRecord, } from "./codex-session-store.js";
 export { RunnerManager, TerminalOpenError } from "./runner/manager.js";
 export type { RunnerManagerOptions, RunnerSessionContext, RunnerSessionContextProvider, OpenTerminalOptions, ParentTerminal, } from "./runner/manager.js";
-export type { InjectOutcome, TerminalOpenErrorCode, TerminalRole } from "./runner/protocol.js";
+export type { InjectOutcome, InjectResult, TerminalOpenErrorCode, TerminalRole } from "./runner/protocol.js";
 export type { ResolveInteractionResult, RuntimeInteractionEvent, RuntimeInteractionListener, } from "./interactions.js";
 export { probeRuntimeStatus } from "./runtime-status.js";
 export { listRuntimeModels } from "./models-catalog.js";
-export { TmuxTerminal, isTmuxAvailable, terminateTmuxServer, tmuxSocketPath, } from "./terminal/tmux.js";
-export type { TerminalAttachment, TmuxTerminalOptions } from "./terminal/tmux.js";
+export { TmuxTerminal, isTmuxAvailable, resolveTmuxBin, terminateTmuxServer, tmuxSocketPath, } from "./terminal/tmux.js";
+export type { PreparedTerminalAttachment, PullTerminalAttachment, TmuxTerminalOptions, } from "./terminal/tmux.js";
 export { TerminalRegistry } from "./terminal/registry.js";

package/dist/index.js

@@ -12,5 +12,5 @@ export { RunnerManager, TerminalOpenError } from "./runner/manager.js";
 export { probeRuntimeStatus } from "./runtime-status.js";
 export { listRuntimeModels } from "./models-catalog.js";
 // Live-terminal subsystem (Phase C): tmux-backed terminals + per-runner registry.
-export { TmuxTerminal, isTmuxAvailable, terminateTmuxServer, tmuxSocketPath, } from "./terminal/tmux.js";
+export { TmuxTerminal, isTmuxAvailable, resolveTmuxBin, terminateTmuxServer, tmuxSocketPath, } from "./terminal/tmux.js";
 export { TerminalRegistry } from "./terminal/registry.js";

package/dist/input-resources.d.ts

@@ -3,6 +3,10 @@ import type { UserInput } from "./codex-app-server/protocol.js";
 /** Convert the provider-native user echo back to resource references. Unknown
  * local paths and remote URLs are deliberately omitted rather than exposed. */
 export declare function codexUserContent(input: readonly UserInput[]): UserContentPart[];
+/** Match the forwarder's public user echo shape exactly. Codex merges adjacent
+ * text inputs (including the internal file marker) into one string before the
+ * Host sees the completed userMessage item. */
+export declare function codexUserEchoContent(input: readonly UserInput[]): string | UserContentPart[] | undefined;
 /** Claude's native TUI has no structured image RPC. The target daemon supplies
  * only managed local paths and the marker makes the transcript echo reversible. */
 export declare function claudeInputText(input: RuntimeUserInput, attachmentToken?: string): string;

package/dist/input-resources.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { basename, extname } from "node:path";
 const CLAUDE_ATTACHMENT_TOKEN = "RYNX_ATTACHMENT_SET";
-const CLAUDE_ATTACHMENT_TOKEN_RE = /^\[RYNX_ATTACHMENT_SET (att_[0-9a-f-]{36}): inspect each RYNX_IMAGE_RESOURCE path with the Read tool before answering\.\]$/m;
+const CLAUDE_ATTACHMENT_TOKEN_RE = /^\[RYNX_ATTACHMENT_SET (att_[0-9a-f-]{36}): inspect each RYNX_IMAGE_RESOURCE or RYNX_FILE_RESOURCE path with the Read tool before answering\.\]$/m;
 /** Convert the provider-native user echo back to resource references. Unknown
  * local paths and remote URLs are deliberately omitted rather than exposed. */
 export function codexUserContent(input) {
@@ -20,21 +20,37 @@ export function codexUserContent(input) {
     }
     return parts;
 }
+/** Match the forwarder's public user echo shape exactly. Codex merges adjacent
+ * text inputs (including the internal file marker) into one string before the
+ * Host sees the completed userMessage item. */
+export function codexUserEchoContent(input) {
+    const parts = codexUserContent(input);
+    if (parts.length === 0)
+        return undefined;
+    if (parts.every((part) => part.type === "input_text")) {
+        const text = parts.map((part) => part.text).join("").trim();
+        return text || undefined;
+    }
+    return parts;
+}
 /** Claude's native TUI has no structured image RPC. The target daemon supplies
  * only managed local paths and the marker makes the transcript echo reversible. */
 export function claudeInputText(input, attachmentToken = `att_${randomUUID()}`) {
-    const images = input.content.filter((part) => part.type === "local_image");
+    const attachments = input.content.filter((part) => part.type !== "text");
     const text = input.content
         .filter((part) => part.type === "text")
         .map((part) => part.text)
         .join("");
-    if (images.length === 0)
+    if (attachments.length === 0)
         return text;
     if (!/^att_[0-9a-f-]{36}$/.test(attachmentToken)) {
         throw new Error("Claude attachment token is invalid");
     }
-    const preamble = `[${CLAUDE_ATTACHMENT_TOKEN} ${attachmentToken}: inspect each RYNX_IMAGE_RESOURCE path with the Read tool before answering.]`;
-    const markers = images.map((part) => `[[RYNX_IMAGE_RESOURCE ${JSON.stringify({ path: part.path })}]]`);
+    const preamble = `[${CLAUDE_ATTACHMENT_TOKEN} ${attachmentToken}: inspect each RYNX_IMAGE_RESOURCE or RYNX_FILE_RESOURCE path with the Read tool before answering.]`;
+    const markers = attachments.map((part) => `[[RYNX_${part.type === "local_image" ? "IMAGE" : "FILE"}_RESOURCE ${JSON.stringify({
+        path: part.path,
+        ...(part.resource.filename ? { filename: part.resource.filename } : {}),
+    })}]]`);
     return [preamble, ...markers, text]
         .filter((part, index) => index <= markers.length || part.length > 0)
         .join("\n");

package/dist/models-catalog.d.ts

@@ -1,11 +1,12 @@
 import { type AgentRuntimeId, type AppConfig } from "@rynx-ai/core";
 import type { ModelListResponse } from "./codex-app-server/protocol.js";
 export interface RuntimeModelCatalogDeps {
+    readCodexModels?: () => Promise<unknown>;
     readTraexModels?: () => Promise<unknown>;
     readTraexDebugModels?: () => Promise<unknown>;
 }
 /**
  * The model list for a runtime, without an execution backend.
- * Falls back to the configured model if live Traex discovery is unavailable.
+ * Falls back to the configured model if local/native discovery is unavailable.
  */
 export declare function listRuntimeModels(config: AppConfig, runtime: AgentRuntimeId, deps?: RuntimeModelCatalogDeps): Promise<ModelListResponse | null>;

package/dist/models-catalog.js

@@ -3,24 +3,37 @@
  *
  * The parent control plane no longer holds an app-server, so `/models` can't be
  * a live `model/list` RPC anymore. Following reference implementation's static-catalog model, we
- * serve a config-derived Codex list and Traex's native `models --json` catalog.
+ * serve Codex's local model cache and Traex's native `models --json` catalog.
  * claude already has its own static list ({@link listClaudeModels}).
  */
 import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
 import { promisify } from "node:util";
-import { resolveRuntimeBinary, resolveRuntimeModel, } from "@rynx-ai/core";
+import { getRuntimeProfile, resolveRuntimeBinary, resolveRuntimeHome, resolveRuntimeModel, } from "@rynx-ai/core";
 import { listClaudeModels } from "./claude/models.js";
 const execFileAsync = promisify(execFile);
 const TRAEX_MODELS_TIMEOUT_MS = 8_000;
 const TRAEX_MODELS_MAX_BYTES = 2 * 1024 * 1024;
 /**
  * The model list for a runtime, without an execution backend.
- * Falls back to the configured model if live Traex discovery is unavailable.
+ * Falls back to the configured model if local/native discovery is unavailable.
  */
 export async function listRuntimeModels(config, runtime, deps = {}) {
     if (runtime === "claude") {
         return listClaudeModels();
     }
+    if (runtime === "codex") {
+        try {
+            const configuredDefault = resolveRuntimeModel(config, runtime).trim();
+            const models = normalizeCodexModels(await (deps.readCodexModels ?? readCodexModels)(), configuredDefault);
+            if (models.length > 0)
+                return { data: models };
+        }
+        catch {
+            // Keep the configured fallback usable before Codex has populated its cache.
+        }
+    }
     if (runtime === "traex") {
         try {
             const value = await (deps.readTraexModels ?? readTraexModels)();
@@ -48,6 +61,72 @@ export async function listRuntimeModels(config, runtime, deps = {}) {
     }
     return { data: [{ id: model, model, isDefault: true }] };
 }
+async function readCodexModels() {
+    const cachePath = join(resolveRuntimeHome(getRuntimeProfile("codex")), "models_cache.json");
+    return JSON.parse(await readFile(cachePath, "utf8"));
+}
+function normalizeCodexModels(value, configuredDefault) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return [];
+    const entries = value.models;
+    if (!Array.isArray(entries))
+        return [];
+    const models = [];
+    const seen = new Set();
+    for (const item of entries) {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const record = item;
+        const id = typeof record.slug === "string" ? record.slug.trim() : "";
+        if (!id || seen.has(id) || record.visibility === "hide")
+            continue;
+        seen.add(id);
+        const supportedReasoningEfforts = Array.isArray(record.supported_reasoning_levels)
+            ? record.supported_reasoning_levels.flatMap((raw) => {
+                if (!raw || typeof raw !== "object" || Array.isArray(raw))
+                    return [];
+                const effort = typeof raw.effort === "string"
+                    ? raw.effort.trim()
+                    : "";
+                if (!effort)
+                    return [];
+                const description = raw.description;
+                return [{
+                        reasoningEffort: effort,
+                        ...(typeof description === "string" && description.trim()
+                            ? { description: description.trim() }
+                            : {}),
+                    }];
+            })
+            : [];
+        const displayName = typeof record.display_name === "string"
+            ? record.display_name.trim()
+            : "";
+        const description = typeof record.description === "string"
+            ? record.description.trim()
+            : "";
+        const defaultReasoningEffort = typeof record.default_reasoning_level === "string"
+            ? record.default_reasoning_level.trim()
+            : "";
+        models.push({
+            id,
+            model: id,
+            ...(displayName ? { displayName } : {}),
+            ...(description ? { description } : {}),
+            isDefault: id === configuredDefault,
+            ...(supportedReasoningEfforts.length > 0 ? { supportedReasoningEfforts } : {}),
+            ...(defaultReasoningEffort ? { defaultReasoningEffort } : {}),
+        });
+    }
+    if (configuredDefault && !seen.has(configuredDefault)) {
+        models.unshift({
+            id: configuredDefault,
+            model: configuredDefault,
+            isDefault: true,
+        });
+    }
+    return models;
+}
 async function readTraexModels() {
     const { stdout } = await execFileAsync(resolveRuntimeBinary("traex"), ["models", "--json"], {
         encoding: "utf8",
@@ -93,19 +172,28 @@ function normalizeTraexModels(value, configuredDefault) {
         return [];
     const models = [];
     const seen = new Set();
+    let foundConfiguredDefault = false;
     for (const item of value) {
         if (!item || typeof item !== "object" || Array.isArray(item))
             continue;
         const record = item;
-        const id = typeof record.name === "string" ? record.name.trim() : "";
+        const name = typeof record.name === "string" ? record.name.trim() : "";
+        // Traex 0.201.1 exposes the launchable model slug as real_name; name is its label/config alias.
+        const realName = typeof record.real_name === "string" ? record.real_name.trim() : "";
+        const id = realName || name;
         if (!id || seen.has(id))
             continue;
         seen.add(id);
+        const isDefault = configuredDefault
+            ? configuredDefault === id || configuredDefault === name
+            : models.length === 0;
+        foundConfiguredDefault ||= isDefault;
         models.push({
             id,
             model: id,
+            ...(name && name !== id ? { displayName: name } : {}),
             ...(typeof record.description === "string" ? { description: record.description } : {}),
-            isDefault: configuredDefault ? id === configuredDefault : models.length === 0,
+            isDefault,
             ...(typeof record.context_window === "number" ? { contextWindow: record.context_window } : {}),
             ...(Array.isArray(record.supported_mime_types)
                 ? { supportedMimeTypes: record.supported_mime_types }
@@ -113,7 +201,7 @@ function normalizeTraexModels(value, configuredDefault) {
             ...(record._meta && typeof record._meta === "object" ? { _meta: record._meta } : {}),
         });
     }
-    if (configuredDefault && !seen.has(configuredDefault)) {
+    if (configuredDefault && !foundConfiguredDefault) {
         models.unshift({ id: configuredDefault, model: configuredDefault, isDefault: true });
     }
     return models;

package/dist/runner/child.d.ts

@@ -1,18 +1,10 @@
-/**
- * Child-side runner session. One per runner process (i.e. per session); owns the
- * single execution backend via the injected executor (a {@link LocalAgentHost}
- * in production, which in a per-session process holds exactly one backend). It
- * translates inbound {@link ToChild} control messages into the live co-drive
- * surface (bring up the session's forwarder + TUI, inject / interrupt turns) and
- * per-thread capabilities, answered against the same backend so the parent never
- * needs an app-server of its own.
- */
-import { type AgentCapabilities, type ResolvedExecutionSnapshot, type RuntimeUserInput, type SessionInteractionResolution, type SessionWorkspaceSnapshot } from "@rynx-ai/core";
-import type { SessionEvent } from "@rynx-ai/core";
+import { type AgentCapabilities, type LiveSessionFailure, type ResolvedExecutionSnapshot, type RuntimeTurnOptions, type RuntimeUserInput, type SessionCollaborationMode, type SessionInteractionResolution, type SessionWorkspaceSnapshot } from "@rynx-ai/core";
+import { type TerminalLifecycle } from "../terminal/registry.js";
 import type { TerminalInjector } from "../claude/native-integration.js";
+import type { MirrorEmitter } from "../host.js";
 import type { ResolveInteractionResult } from "../interactions.js";
-import { type InjectOutcome } from "./protocol.js";
-import type { ChildTransport } from "./transport.js";
+import { type InjectResult } from "./protocol.js";
+import { type ChildTransport } from "./transport.js";
 /** Re-target the mirror to a freshly minted rynx session (claude `/clear`·`/fork`)
  *  + record the terminal transfer with the daemon. The child owns the transport,
  *  so it supplies this to the host. */
@@ -21,7 +13,8 @@ type RetargetMirror = (newSessionId: string, meta: {
     workspace: SessionWorkspaceSnapshot;
     execution: ResolvedExecutionSnapshot;
     parentSessionId?: string;
-}) => void;
+    beforeApplied?: () => void | Promise<void>;
+}) => void | Promise<void>;
 /** Codex-native live-session methods the executor (a `LocalAgentHost`) exposes
  *  beyond the `AgentExecutor`/`AgentCapabilities` contract. Duck-typed so the
  *  runner works with any executor (a claude-only host simply lacks them). */
@@ -32,24 +25,47 @@ interface LiveCodexProvider {
         cwd: string;
         env?: Record<string, string>;
         skipTraexStartupPrompts?: boolean;
+        scrollback?: number;
+        tmuxAllowPassthrough?: boolean;
+        tmuxStartOnAttach?: boolean;
+        keepAliveAfterExit?: boolean;
+        lifecycle: TerminalLifecycle;
     } | null>;
-    ensureLiveCodexSession?(localThreadId: string, emit: (event: SessionEvent) => void, opts: {
+    ensureLiveCodexSession?(localThreadId: string, emit: MirrorEmitter, opts: {
         workspace: SessionWorkspaceSnapshot;
         execution: ResolvedExecutionSnapshot;
         retargetMirror?: RetargetMirror;
     }): Promise<boolean>;
-    waitLiveReady?(localThreadId: string, timeoutMs?: number): Promise<boolean>;
-    waitTerminalReady?(localThreadId: string, timeoutMs?: number): Promise<boolean>;
+    /** Known-thread Codex/Traex resume only: start the independent transcript
+     * observer after the replacement TUI has launched. Fresh discovery connects
+     * its listener before launch and this method is an idempotent no-op. */
+    startLiveCodexObserver?(localThreadId: string): void;
+    /** `null` delegates the deadline to RunnerManager. */
+    waitLiveReady?(localThreadId: string, timeoutMs?: number | null): Promise<boolean>;
+    /** `null` delegates the deadline to RunnerManager. */
+    waitTerminalReady?(localThreadId: string, timeoutMs?: number | null): Promise<boolean>;
     liveSessionError?(localThreadId: string): string | undefined;
-    injectMessage?(localThreadId: string, input: RuntimeUserInput | string): Promise<InjectOutcome>;
+    liveSessionFailure?(localThreadId: string): LiveSessionFailure | undefined;
+    failLiveStartup?(localThreadId: string, error: Error): boolean;
+    failLiveSession?(localThreadId: string, error: Error): boolean;
+    /** Codex/Traex auxiliary Terminal lifecycle: settle the current Turn, stop
+     * observer/forwarder, and evict the owned app-server while preserving the
+     * durable native-session binding for a later cold resume. */
+    teardownLiveCodexSession?(localThreadId: string, error?: Error): boolean;
+    /** Cleanup coupled runtime resources after an auxiliary terminal is
+     * intentionally idle-reaped. Unexpected auxiliary exit does not call this. */
+    teardownAuxiliaryTerminalRuntime?(localThreadId: string): Promise<void>;
+    injectMessage?(localThreadId: string, input: RuntimeUserInput | string, options?: RuntimeTurnOptions): Promise<InjectResult>;
+    updateCollaborationMode?(localThreadId: string, mode: SessionCollaborationMode): Promise<void>;
     interruptLive?(localThreadId: string): Promise<boolean>;
     stopLiveCodexSession?(localThreadId: string, opts?: {
         deferClaudeInteractionCleanup?: boolean;
     }): void;
-    finalizeStoppedLiveSessions?(): void;
+    finalizeStoppedLiveSessions?(): void | Promise<void>;
     resolveInteraction?(localThreadId: string, interactionId: string, resolution: SessionInteractionResolution): Promise<ResolveInteractionResult>;
-    /** claude-native: hand the session's tmux pane injector to the host (which
-     *  doesn't own tmux). No-op for codex sessions (they inject via app-server). */
+    /** Hand the session's tmux pane injector to the host (which doesn't own
+     * tmux). Claude uses it for messages; Codex uses it only for TUI-local
+     * controls that the app-server cannot resolve, such as the final Plan picker. */
     attachTerminalInjector?(localThreadId: string, injector: TerminalInjector): void;
     /** Internal Provider operation used only by MachineSessionService through
      * RunnerManager. It is deliberately absent from public AgentCapabilities. */
@@ -65,21 +81,42 @@ export interface RunnerSessionDeps {
     /** Invoked on a `shutdown` message (default: close transport). */
     onShutdown?: () => void;
 }
+/** Delivery retry schedule: 1, 2, 4, 8, 16, 30, 30… seconds.
+ * Clamp before exponentiation so an indefinitely transient outage cannot
+ * overflow after thousands of attempts. */
+export declare function mirrorRetryDelayMs(failedAttempt: number): number;
 export declare class RunnerSession {
     private readonly transport;
     private readonly executor;
     private readonly onShutdown;
     /** Live terminals hosted by this session, and per-attach client handles. */
     private readonly terminals;
+    private readonly preparations;
     private readonly attachments;
     private readonly attachmentThreadIds;
+    private readonly attachmentRoles;
     private readonly traexStartupWatchers;
+    private readonly traexStartupGates;
+    private readonly codexStartupMonitors;
+    private readonly terminalWatchers;
     /** Opens are async; a close received before attach resolves tombstones the id. */
     private readonly pendingTerminalOpens;
     private readonly cancelledTerminalOpens;
     /** Session ids with a live codex forwarder started here (stopped on shutdown). */
     private readonly liveIds;
+    private readonly mirrorQueues;
+    private readonly mirrorAcks;
+    private readonly mirrorImageAcks;
+    private readonly mirrorRetryWaiters;
+    private readonly rotationPublishAcks;
+    private readonly rotationAppliedAcks;
+    /** Provider name retained for asynchronous Terminal-exit diagnostics. */
+    private readonly liveRuntimes;
+    private readonly terminalStatuses;
+    private consecutiveMirrorFailures;
+    private mirrorDegraded;
     private shuttingDown;
+    private shutdownPromise;
     constructor({ transport, executor, onShutdown }: RunnerSessionDeps);
     private handle;
     private get liveProvider();
@@ -90,29 +127,61 @@ export declare class RunnerSession {
      *  new session AND tells the daemon to alias the runner (terminal transfer) so
      *  the new session stays injectable. */
     private mirrorChannel;
+    private transferNativeSessionResources;
+    private enqueueMirror;
+    private sendMirroredEvent;
+    private deliverMirrorImageEvent;
+    private deliverMirrorImageTransportFrame;
+    private deliverMirrorEvent;
+    private noteMirrorDeliveryFailed;
+    private noteMirrorDeliveryRecovered;
+    private sendMirrorEventFrame;
+    private abandonMirrorDelivery;
+    private waitForMirrorRetry;
+    private cancelMirrorGeneration;
+    private rejectMirrorAcks;
+    private sendMirrorImageFrame;
+    private rejectMirrorImageAcks;
+    private sendRotationFrame;
+    private sendRotationAppliedFrame;
+    private rejectRotationAcks;
     /**
-     * Eagerly bring up a session's codex-native live view: start the persistent
-     * forwarder connection (which resume-subscribes to mirror every turn) and
-     * launch the detached `codex --remote resume` TUI against the thread the
-     * structured runtime created. The forwarder subscribes to that same thread,
-     * so the TUI is usable immediately and its turns mirror to chat.
+     * Eagerly bring up a session's codex-native live view. Fresh sessions connect
+     * the discovery listener before launching the detached TUI; known-thread
+     * resumes preload first, launch the replacement TUI, then start their
+     * persistent observer in the background.
      */
     private ensureLive;
+    private monitorCodexThreadStartup;
+    /** Discovery failure is terminal for this partial native launch. Publish the
+     * exact cause first so an in-flight injection wakes, then drop the observer
+     * and TUI so a later task retry creates a clean launch instead of reusing an
+     * already-rejected readiness promise. */
+    private failCodexThreadStartup;
     private inject;
+    private updateCollaborationMode;
     private interruptLive;
+    private reapTerminal;
     /** Launch (idempotently) the session's codex TUI pane from the executor's
      *  `codexTerminalSpec`. Shares the `${id}-main` terminal id with `term.open`,
      *  so the web attach reuses the same detached pane. */
     private launchCodexPane;
+    private watchNativeTerminal;
     private cancelTraexStartupWatcher;
     private skipTraexStartupPrompts;
     private stopLive;
     /** Stop event forwarding, kill native terminals/hooks, then synchronously
      * scrub provider handoff files before the child process is allowed to exit. */
-    shutdown(): void;
+    shutdown(): Promise<void>;
     private openTerminal;
-    /** Attach an already-created terminal and forward its data/exit to the parent. */
+    /** Prepare captured history without starting the live control client. */
     private attachExisting;
+    private readTerminalSeed;
+    private startTerminal;
+    private readTerminalOutput;
+    private writeTerminalInput;
+    private resizeTerminal;
+    private sendTerminalOperationError;
     private runCap;
     private dispatchCap;
 }