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

package/dist/runner/manager.d.ts

@@ -16,10 +16,10 @@
  * channel.
  */
 import { spawn as nodeSpawn, type ChildProcess } from "node:child_process";
-import { type AdmissionReservation, type AgentCapabilities, type AgentRuntimeId, type AppConfig, type CapabilityResult, type ModelListResponse, type ResolvedExecutionSnapshot, type RuntimeUserInput, type SessionInteractionResolution, type SessionEvent, type SessionWorkspaceSnapshot, type ThreadGoal } from "@rynx-ai/core";
+import { type AdmissionReservation, type AgentCapabilities, type AgentRuntimeId, type AppConfig, type CapabilityResult, type ModelListResponse, type LiveSessionFailure, type InjectResult, type ResolvedExecutionSnapshot, type RuntimeTurnOptions, type RuntimeUserInput, type SessionCollaborationMode, type SessionInteractionResolution, type SessionEvent, type SessionWorkspaceSnapshot, type ThreadGoal } from "@rynx-ai/core";
 import { type CodexSessionStore } from "../host.js";
 import type { ResolveInteractionResult } from "../interactions.js";
-import { type InjectOutcome, type TerminalOpenErrorCode, type TerminalRole } from "./protocol.js";
+import { type TerminalOpenErrorCode, type TerminalRole } from "./protocol.js";
 /** Runtime-local context attached to one Session runner process. The provider is
  * intentionally generic: package-specific resources stay in the composition
  * root that implements this port. */
@@ -43,33 +43,45 @@ export interface RunnerManagerOptions {
     runnerEntry?: string;
     /** Idle TTL (ms) after which an unused runner is reaped. */
     idleTtlMs?: number;
+    /** Native pane idle window. `<= 0` disables native-pane idle reaping. */
+    nativePaneIdleTtlMs?: number;
+    /** Recent tmux-output window used as independent native-pane busy evidence. */
+    nativePaneOutputBusyWindowMs?: number;
     /** Background reap sweep interval (ms); `0` disables the timer (tests). */
     reapIntervalMs?: number;
     /** Grace period between SIGTERM and SIGKILL during runner shutdown. */
     shutdownGraceMs?: number;
     /** Final bounded wait for child exit after SIGKILL. */
     shutdownKillGraceMs?: number;
-    /** Max wait for a setup-pane launch acknowledgement. */
+    /** Max wait for a legacy setup-pane launch acknowledgement. Codex/Traex use
+     * their internal phase deadlines and are not wrapped by this timer. */
     liveStartTimeoutMs?: number;
     /** Max wait for a Provider-native thread to become ready. */
     liveReadyTimeoutMs?: number;
+    /** Claude SessionStart deadline. Codex/Traex have no parent-owned startup
+     * deadline; their app-server/discovery/injection phases report directly. */
+    nativeLiveStartTimeoutMs?: number;
     /** Max wait for a native interrupt acknowledgement before reporting it
      * unproven. Callers may then use the explicit force-stop path. */
     liveInterruptTimeoutMs?: number;
     /** Max wait for an accepted owner TUI submission to become observable as a
      * mirrored response or a published native rotation. */
     terminalInputHandoffTimeoutMs?: number;
-    /** Initial exponential backoff for retrying unproven terminal cleanup. */
-    terminalInputCleanupRetryMs?: number;
     /** Injected for tests. */
     spawn?: typeof nodeSpawn;
     /** Injected for tests. Defaults to signaling the whole POSIX process group
      * created for the runner child, with direct-child fallback. */
     signalChild?: (child: ChildProcess, signal: NodeJS.Signals, processGroup: boolean) => void;
-    /** Injected for tests. Kills and verifies the deterministic private tmux
-     * server owned by a Session runner. */
-    terminateTerminalServer?: (terminalName: string) => boolean | Promise<boolean>;
+    /** Injected for tests. Best-effort close of the deterministic private tmux
+     * server owned by a Session runner; reference implementation does not verify/retry close. */
+    terminateTerminalServer?: (terminalName: string, ownerPid?: number) => boolean | Promise<boolean>;
+    /** Injected tmux `#{window_activity}` reader. Returns epoch seconds. */
+    terminalWindowActivityAt?: (terminalName: string, ownerPid?: number) => number | null | Promise<number | null>;
+    /** Injected tmux attached-client probe. */
+    terminalHasAttachedClient?: (terminalName: string, ownerPid?: number) => boolean | Promise<boolean>;
     now?: () => number;
+    /** Wall clock used to compare tmux's epoch timestamp. */
+    wallNow?: () => number;
     /** Extra env merged into every spawned runner child — e.g. the control-plane
      *  URL + token so a claude-native PermissionRequest hook can POST back. */
     childEnv?: Record<string, string>;
@@ -104,24 +116,39 @@ export interface OpenTerminalOptions {
     command?: string;
     args?: string[];
 }
-/**
- * Parent-side handle to a live terminal on a runner child. Bytes flow through
- * {@link onData} / {@link write} (decoded from the base64 wire frames); resize
- * and close are forwarded as control messages. {@link ready} resolves with the
- * granted role once the child attaches (an `owner` request is downgraded to
- * read-only when the owner slot is taken).
- */
+export interface ParentTerminalRead {
+    data: Uint8Array;
+    nextOffset: number;
+    done: boolean;
+    finalOffset?: number;
+}
+export interface ParentTerminalReaderDone {
+    finalOffset: number;
+    reason: "terminal_exited" | "client_closed" | "backpressure" | "internal";
+    exitCode: number;
+}
+/** Parent-side demand-driven terminal handle. `ready` publishes only captured
+ * history metadata; the caller must pull every seed byte before `start`. */
 export interface ParentTerminal {
     readonly attachId: string;
     readonly ready: Promise<{
         role: TerminalRole;
+        seedBytes: number;
+        dimensions?: {
+            cols: number;
+            rows: number;
+        };
     }>;
-    onData(listener: (chunk: string) => void): void;
-    onExit(listener: (info: {
-        exitCode: number;
+    readonly readerDone: Promise<ParentTerminalReaderDone>;
+    readSeed(offset: number, maxBytes: number): Promise<ParentTerminalRead>;
+    start(): Promise<void>;
+    read(offset: number, maxBytes: number): Promise<ParentTerminalRead>;
+    onResize?(listener: (dimensions: {
+        cols: number;
+        rows: number;
     }) => void): void;
-    write(data: string): void;
-    resize(cols: number, rows: number): void;
+    write(data: string | Uint8Array): Promise<void>;
+    resize(cols: number, rows: number): Promise<void>;
     close(): void;
 }
 /** A typed attach failure so transport adapters can distinguish an expected
@@ -136,6 +163,8 @@ export declare class RunnerManager implements AgentCapabilities {
     private readonly sessionStore;
     private readonly runnerEntry;
     private readonly idleTtlMs;
+    private readonly nativePaneIdleTtlMs;
+    private readonly nativePaneOutputBusyWindowMs;
     private readonly spawn;
     private readonly childEnv;
     private readonly sessionContextProvider;
@@ -152,15 +181,28 @@ export declare class RunnerManager implements AgentCapabilities {
     private readonly shutdownKillGraceMs;
     private readonly signalChild;
     private readonly terminateTerminalServer;
+    private readonly terminalWindowActivityAt;
+    private readonly terminalHasAttachedClient;
+    private readonly wallNow;
     private readonly liveStartTimeoutMs;
     private readonly liveReadyTimeoutMs;
+    private readonly nativeLiveStartTimeoutMs;
     private readonly liveInterruptTimeoutMs;
     private readonly terminalInputHandoffTimeoutMs;
-    private readonly terminalInputCleanupRetryMs;
+    private reapPromise;
     private stopping;
     private stopPromise;
     /** Sink for mirrored {@link SessionEvent}s from every session's forwarder. */
     private mirrorListener;
+    /** Settles process-local projections only when an ordinary durable item has
+     * exhausted its permanent retry budget. */
+    private mirrorAbandonListener;
+    /** Clears process-live optimistic state when /clear permanently moves the
+     * native pane away from the old Session. */
+    private mirrorSupersedeListener;
+    /** Synchronous persistence hook for native collaboration-mode reflection.
+     * It runs before the event reaches the Session bus. */
+    private collaborationModeListener;
     /** Sink for session rotations (claude `/clear`·`/fork`) — server records meta. */
     private rotateListener;
     /** Session keys with a live codex forwarder — never reaped while present. */
@@ -189,9 +231,8 @@ export declare class RunnerManager implements AgentCapabilities {
     /**
      * Open a live terminal on the session's runner child (spawning it if needed).
      * Phase C hosts one terminal ("main") per session; the returned handle is a
-     * single attach client — `owner` (read-write) or a downgraded `read-only`
-     * viewer per the child's ownership rule. Not part of `AgentExecutor`; the WS
-     * bridge calls it directly.
+     * single attach client with the requested `owner` (read-write) or `read-only`
+     * role. Not part of `AgentExecutor`; the WS bridge calls it directly.
      */
     openTerminal(localThreadId: string, opts: OpenTerminalOptions): ParentTerminal;
     /**
@@ -208,7 +249,10 @@ export declare class RunnerManager implements AgentCapabilities {
      * session's persistent codex forwarder (web- AND TUI-initiated turns). The
      * server wires this to `persistSessionEvent` (bus + canonical log).
      */
-    onMirror(listener: (sessionId: string, event: SessionEvent) => void): void;
+    onMirror(listener: (sessionId: string, event: SessionEvent) => void | Promise<void>): void;
+    onMirrorAbandon(listener: (sessionId: string, token: string) => void): void;
+    onMirrorSupersede(listener: (sessionId: string) => void): void;
+    onCollaborationMode(listener: (sessionId: string, mode: SessionCollaborationMode) => void): void;
     /** Register the sink for session rotations (claude `/clear`·`/fork`): the server
      *  records the new session's meta (carry-over agent/model/title). */
     onRotate(listener: (rotation: RotateInfo) => void | Promise<void>): void;
@@ -222,13 +266,14 @@ export declare class RunnerManager implements AgentCapabilities {
     private finishTerminalInputHandoff;
     private finishAllTerminalInputHandoffs;
     private preserveTerminalInputHandoffsAsActivity;
-    private scheduleTerminalInputCleanupRetry;
     private expireTerminalInputHandoffs;
     /**
      * Eagerly bring up a session's codex-native live view (persistent forwarder +
      * detached `codex --remote` TUI) in its runner child, spawning the runner if
-     * needed. Idempotent. Resolves true once the codex thread is bound; false for a
-     * non-codex / non-live session (the caller then uses the normal run path).
+     * needed. Idempotent. For Codex-lineage sessions, resolves after backend
+     * preload and pane launch; known-thread observer attach and fresh-thread
+     * discovery continue in the background. Other providers retain their
+     * readiness gate.
      */
     ensureLiveSession(localThreadId: string, opts: {
         workspace: SessionWorkspaceSnapshot;
@@ -247,13 +292,14 @@ export declare class RunnerManager implements AgentCapabilities {
     }): Promise<boolean>;
     private requestLiveSession;
     lastLiveSessionError(localThreadId: string): string | undefined;
+    lastLiveSessionFailure(localThreadId: string): LiveSessionFailure | undefined;
     /**
      * Inject a user turn into a session's live codex thread — reference implementation's
      * single-writer web send (`turn/start` / `turn/steer`); the forwarder mirrors
      * all output. Resolves true when the app-server accepted the turn, false when
      * the session has no live forwarder (caller falls back to the run path).
      */
-    injectMessage(localThreadId: string, input: RuntimeUserInput | string): Promise<InjectOutcome>;
+    injectMessage(localThreadId: string, input: RuntimeUserInput | string, options?: RuntimeTurnOptions): Promise<InjectResult>;
     private injectMessageAdmitted;
     /**
      * Interrupt a session's active live turn — the web Stop button (codex
@@ -263,6 +309,8 @@ export declare class RunnerManager implements AgentCapabilities {
     interruptLiveSession(localThreadId: string): Promise<boolean>;
     /** Resolve a native question/approval without ever spawning a new runner. */
     resolveInteraction(localThreadId: string, interactionId: string, resolution: SessionInteractionResolution): Promise<ResolveInteractionResult>;
+    /** Update a loaded Codex-lineage native thread without spawning a runner. */
+    updateCollaborationMode(localThreadId: string, mode: SessionCollaborationMode): Promise<void>;
     listModels(runtime?: AgentRuntimeId): Promise<ModelListResponse | null>;
     getGoal(localThreadId: string): Promise<CapabilityResult<ThreadGoal | null>>;
     setGoal(localThreadId: string, objective: string): Promise<CapabilityResult>;
@@ -305,12 +353,45 @@ export declare class RunnerManager implements AgentCapabilities {
     private bufferForkTargetMessage;
     private reservedForkTarget;
     private deliverForkBufferedMessage;
+    private deliverMirrorMessage;
+    private releaseMirrorDelivery;
+    private failMirrorImageTransfer;
     private deliverRotateMessage;
+    /** Bridge ownership is a child-local binding, but the parent is the only
+     * process that knows logical target publication committed. Mark that fact
+     * durably before allowing the child to apply and expose the alias. */
+    private publishNativeRotationBinding;
+    private publishNativeRotationRecords;
+    private deliverRotateAppliedMessage;
+    private finalizeNativeRotation;
+    private acknowledgeRotateApplied;
+    private releasePendingNativeRotation;
+    private publishNativeRotationNotice;
     private spawnHandle;
     private onChildMessage;
     /** Mark a handle dead and reject every pending run/cap with the exit reason. */
     private failHandle;
     private terminateHandle;
     private reapIdle;
+    private reapIdleOnce;
+    /** Provider-authoritative turn state is the lifecycle truth; attached clients
+     * and tmux's own activity clock are independent busy evidence. There is no
+     * "user was inactive for an hour" override for an active turn. */
+    private reapNativePane;
+    private reapNativeTerminal;
+    private isNativePaneBusy;
+    private isManagedNativeHandle;
+    private failActiveResponses;
+    private interruptActiveResponses;
+    /** Crash/termination compensation is intentionally best-effort because it is
+     * a terminal/status edge rather than an ordinary transcript delivery.
+     * Still consume an asynchronous persistence rejection so a dying child
+     * cannot take the parent daemon down with an unhandled rejection. */
+    private emitCompensatingMirror;
+    /** Track the provider-authoritative response lifecycle. Native-pane busy
+     * classification consumes this level directly; output volume is separately
+     * grounded in tmux's own activity clock. */
+    private observeHandleRuntimeEvent;
+    private isStaleMirrorGeneration;
     private openSessionContext;
 }