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

package/dist/host.d.ts

@@ -1,8 +1,8 @@
-import { type ResolvedExecutionSnapshot, type ResolvedExecutionBudget, type RuntimeUserInput, type SessionWorkspaceSnapshot, type SessionInteractionResolution, type SessionEvent } from "@rynx-ai/core";
+import { type ResolvedExecutionSnapshot, type ResolvedExecutionBudget, type RuntimeTurnOptions, type RuntimeUserInput, type SessionCollaborationMode, type LiveSessionFailure, type SessionWorkspaceSnapshot, type SessionInteractionResolution, type SessionEvent } from "@rynx-ai/core";
 import { type AgentRuntimeId } from "@rynx-ai/core";
 import { type AppConfig } from "@rynx-ai/core";
 import { createCodexChildEnv } from "./codex-child-env.js";
-import type { InjectOutcome } from "./runner/protocol.js";
+import type { InjectResult } from "./runner/protocol.js";
 import type { ResolveInteractionResult } from "./interactions.js";
 import { CodexAppServerClient } from "./codex-app-server/client.js";
 import type { ModelListResponse, ThreadGoal } from "./codex-app-server/protocol.js";
@@ -125,6 +125,9 @@ export declare class LocalAgentHost implements CodexCapabilities {
     private readonly clock;
     private readonly backendIdleTtlMs;
     private readonly forwarderClientFactory;
+    private readonly preloadClientFactory;
+    /** Builds one short-lived message/interrupt client. */
+    private readonly injectionClientFactory;
     private readonly backends;
     private readonly sessionId;
     private readonly runtimeHomeSessionId;
@@ -133,6 +136,10 @@ export declare class LocalAgentHost implements CodexCapabilities {
     private readonly runtimeHomes;
     private readonly liveSessions;
     private readonly liveClaudeSessions;
+    /** Exact pre-live startup failure, retained after the partial handle has been
+     * cleaned up so Core/plugin callers receive the failed phase, not a generic
+     * `live session unavailable` wrapper. */
+    private readonly liveStartupErrors;
     /** Claude forwarders stopped before their terminal is killed. Runner shutdown
      * finalizes these synchronously afterwards to scrub raw interaction answers. */
     private readonly pendingClaudeFinalizers;
@@ -141,7 +148,7 @@ export declare class LocalAgentHost implements CodexCapabilities {
     /** Short-lived dedupe for managed fork notifications delivered after the
      * `thread/fork` response. Values are expected source Provider thread ids. */
     private readonly managedForkThreadStarts;
-    constructor({ config, commandRunner, sessionStore, allowedRoots, appServerClient, now, backendIdleTtlMs, forwarderClientFactory, sessionId, runtimeHomeSessionId, }: {
+    constructor({ config, commandRunner, sessionStore, allowedRoots, appServerClient, now, backendIdleTtlMs, forwarderClientFactory, preloadClientFactory, injectionClientFactory, sessionId, runtimeHomeSessionId, }: {
         config: AppConfig;
         commandRunner?: CodexCommandRunner;
         sessionStore?: CodexSessionStore;
@@ -153,6 +160,10 @@ export declare class LocalAgentHost implements CodexCapabilities {
         backendIdleTtlMs?: number;
         /** Override the live-session forwarder connection factory (tests inject a fake). */
         forwarderClientFactory?: (appServerUrl: string) => CodexAppServerClient;
+        /** Override the short-lived known-thread preload connection factory. */
+        preloadClientFactory?: (appServerUrl: string) => CodexAppServerClient;
+        /** Override the short-lived message/interrupt connection factory. */
+        injectionClientFactory?: (appServerUrl: string) => CodexAppServerClient;
         /** The rynx session (localThreadId) this host serves — a per-session runner
          *  child sets it from `RYNX_RUNNER_SESSION` so the private CODEX_HOME is
          *  session-scoped. The shared `__cap__` child / tests fall back to a sentinel
@@ -178,6 +189,16 @@ export declare class LocalAgentHost implements CodexCapabilities {
     private createAppServerClient;
     /** Resolve a pending native question/approval without opening a new Turn. */
     resolveInteraction(localThreadId: string, interactionId: string, resolution: SessionInteractionResolution): Promise<ResolveInteractionResult>;
+    /** Apply collaboration mode to an already-loaded Codex-lineage thread. The
+     * caller persists only after this native RPC succeeds. */
+    updateCollaborationMode(localThreadId: string, mode: SessionCollaborationMode): Promise<void>;
+    /** Apply one explicit collaboration mode to the current native thread and
+     * remember only a successful RPC. A supplied client is already initialized
+     * and remains owned by its caller (used by cold-resume preload). */
+    private applyLiveCollaborationMode;
+    /** Apply pending explicit model/effort settings and, when requested, one
+     * collaboration mode in a single native update. */
+    private applyLiveThreadSettings;
     /**
      * The command to run in a session's live terminal so it co-drives the codex
      * app-server thread (Phase D). Returns `null` when live-terminal is off, the
@@ -191,6 +212,7 @@ export declare class LocalAgentHost implements CodexCapabilities {
         args: string[];
         cwd: string;
         env?: Record<string, string>;
+        skipTraexStartupPrompts?: boolean;
     } | null>;
     /**
      * Bring up (idempotently) a session's persistent codex forwarder and emit its
@@ -211,26 +233,43 @@ export declare class LocalAgentHost implements CodexCapabilities {
     /** Bind a session's codex thread id once known (TUI broadcast or store): persist
      *  it, unblock injection, and kick off the resume-subscribe loop (once). */
     private onLiveThreadStarted;
+    /** Start the known-thread observer after the replacement TUI has launched.
+     * Fresh sessions already connected their discovery listener before launch;
+     * this is therefore an idempotent no-op for them and for a healthy observer. */
+    startLiveCodexObserver(localThreadId: string): void;
+    /** reference implementation treats the forwarder as a required component of one native
+     * lifecycle: if its transport dies, it closes the app-server instead of
+     * accepting turns that can no longer reach the canonical mirror. */
+    private failObserverLifecycle;
     private shouldIgnoreManagedForkThreadStarted;
     private rememberManagedForkThreadStart;
     /**
      * Subscribe the forwarder connection to a thread (reference implementation's
      * `_subscribe_until_ready`). A fresh TUI thread has no rollout until its first
      * turn, so `thread/resume` is retried: park until the forwarder observes the
-     * thread active, then retry WITHOUT `excludeTurns` so the response backfills the
-     * first turn's items (replayed, deduped against the live stream). Once resume
-     * succeeds, subsequent turns arrive as live notifications on this connection.
+     * thread active, then retry. Like reference implementation, the first attempt always uses
+     * `excludeTurns`: a known-session cold resume therefore never reconstructs
+     * historical running/completed state. Only a fresh thread whose first attempt
+     * failed as not-ready retries without `excludeTurns`, backfilling the newly
+     * materialized first turn and de-duplicating it against live notifications.
      */
     private subscribeUntilReady;
-    /** Await a live session's thread binding (bounded). Returns false on timeout /
+    /** Await a live session's thread binding. `null` leaves the deadline to the
+     *  caller; a number keeps the Provider-local bound. Returns false on timeout /
      *  no live session. Injection and the runner's `live.ready` gate on this. */
-    waitLiveReady(localThreadId: string, timeoutMs?: number): Promise<boolean>;
-    /** Await the stronger Terminal gate: another app-server connection has
-     * successfully resumed the thread, so the detached TUI cannot race rollout
-     * discovery or indexing. */
-    waitTerminalReady(localThreadId: string, timeoutMs?: number): Promise<boolean>;
+    waitLiveReady(localThreadId: string, timeoutMs?: number | null): Promise<boolean>;
+    /** Await the observer subscription diagnostic. Codex/Traex Terminal startup
+     * deliberately does not gate on this promise: the dedicated preload owns resume,
+     * while the independent observer attaches in the background. */
+    waitTerminalReady(localThreadId: string, timeoutMs?: number | null): Promise<boolean>;
     /** Diagnostic from the provider adapter when native discovery/resume failed. */
     liveSessionError(localThreadId: string): string | undefined;
+    /** Structured phase + concrete cause used by the runner wire protocol. */
+    liveSessionFailure(localThreadId: string): LiveSessionFailure | undefined;
+    /** Publish the background TUI/thread discovery failure so an executor
+     * already waiting in the 60s bridge window exits immediately with the exact
+     * 30s discovery cause. */
+    failLiveStartup(localThreadId: string, error: Error): boolean;
     /**
      * Inject a user turn into a session's live codex thread — reference implementation's
      * single-writer web send. `turn/steer` when a turn is open (mid-turn
@@ -238,13 +277,13 @@ export declare class LocalAgentHost implements CodexCapabilities {
      * resumed from the persisted native id. Serialized per session so two
      * injects can't double-open a turn.
      *
-     * Returns an {@link InjectOutcome}: `notLive` when this session has no live
+     * Returns an {@link InjectResult}: `notLive` when this session has no live
      * forwarder (caller may use the run path); `notReady`/`failed` are hard errors
      * the caller reports WITHOUT re-running (re-running double-writes alongside the
      * forwarder). Park-until-ready (~60s), aligning reference implementation's executor waiting for
      * the bridge instead of a short race that falls back to a second output path.
      */
-    injectMessage(localThreadId: string, input: RuntimeUserInput | string): Promise<InjectOutcome>;
+    injectMessage(localThreadId: string, input: RuntimeUserInput | string, options?: RuntimeTurnOptions): Promise<InjectResult>;
     /**
      * Interrupt the session's active turn — the web Stop button. codex: the
      * app-server `turn/interrupt` on the active `{threadId, turnId}` (exactly what
@@ -258,6 +297,11 @@ export declare class LocalAgentHost implements CodexCapabilities {
     stopLiveCodexSession(localThreadId: string, opts?: {
         deferClaudeInteractionCleanup?: boolean;
     }): void;
+    /** Tear down one codex-lineage native runtime without deleting its durable
+     * session-store binding. reference implementation couples its auxiliary Terminal, observer,
+     * forwarder and per-session app-server as one disposable runtime envelope;
+     * the next message recreates that envelope and cold-resumes the native id. */
+    teardownLiveCodexSession(localThreadId: string, error?: Error): boolean;
     /** Complete the second shutdown phase after the runner has killed all native
      * terminals and hook subprocesses. Must run before the runner process exits. */
     finalizeStoppedLiveSessions(): void;
@@ -279,7 +323,7 @@ export declare class LocalAgentHost implements CodexCapabilities {
      *  serialized per session. Parks until the thread is ready AND the tmux injector
      *  is (re)attached, then pastes; `injectViaTerminal` RAISES if the prompt never
      *  appears (reference implementation RAISE), so a not-ready pane is a hard error — NOT a
-     *  fall-through-to-run signal. Returns {@link InjectOutcome}. */
+     *  fall-through-to-run signal. Returns {@link InjectResult}. */
     private injectClaude;
     /** Park until the claude session's tmux injector is (re)attached by the
      *  runner-child, or the deadline passes. Pane relaunch re-attaches it via
@@ -287,9 +331,12 @@ export declare class LocalAgentHost implements CodexCapabilities {
      *  would fail and (pre-reference implementation) fall through to a second output path. */
     private waitInjector;
     /** Attach a session's tmux pane injector (from the runner-child, which owns the
-     *  terminal registry — the host does not hold tmux). Ignored for codex sessions
-     *  (they inject via the app-server). Idempotent. */
+     *  terminal registry — the host does not hold tmux). Claude uses it for normal
+     *  message injection; Codex uses it only to dismiss the exact TUI-local Plan
+     *  picker after its synthetic Web form is submitted. Idempotent. */
     attachTerminalInjector(localThreadId: string, injector: TerminalInjector): void;
+    /** Close an active native response when its terminal or runner disappears. */
+    failLiveSession(localThreadId: string, error: Error): boolean;
     /** List the models a runtime exposes (App Server for codex/traex; static for claude). */
     listModels(runtime?: AgentRuntimeId): Promise<ModelListResponse | null>;
     /**
@@ -318,7 +365,3 @@ export declare function isUnsupportedMethodError(error: unknown): boolean;
  *  — a fresh TUI thread before its first turn. Retryable (park until active).
  *  Mirrors reference implementation's `_is_thread_not_ready_error`. */
 export declare function isThreadNotReadyError(error: unknown): boolean;
-/** A persisted thread id that a freshly started app-server cannot load yet.
- * During startup, both errors can be transient while the rollout index catches
- * up. Retry the same id; never use either error as permission to replace it. */
-export declare function isRetryableThreadResumeError(error: unknown): boolean;