@rynx-ai/runtime 0.1.11-beta.5 → 0.1.11-beta.50

package/dist/codex-app-server/forwarder.d.ts

@@ -23,20 +23,39 @@
  */
 import type { AgentEvent, UserContentPart } from "@rynx-ai/core";
 import type { CodexAppServerClient } from "./client.js";
-import type { ResumedTurn } from "./protocol.js";
+import type { McpStartupPlan } from "./mcp-startup.js";
+import type { CollaborationModeKind, ReasoningEffort, ResumedTurn } from "./protocol.js";
 export interface CodexForwarderSink {
     /** A turn began. `turnId` is codex's turn id, used to derive a stable
      *  `responseId`. Start a fresh normalizer/response. */
     onTurnStart(turnId?: string): void;
+    /** The observer received the provider's authoritative `turn/started` edge.
+     * Unlike `onTurnStart`, this is not fired early by turn/start acceptance. */
+    onTurnObserved?(turnId?: string): void;
     /** One mapped event within the current turn. */
     onEvent(event: AgentEvent): void;
+    /** Turn-scoped content arrived while no Provider Turn is active. Attach it
+     * to that response without opening a Turn or changing Session status. */
+    onTurnContentEvent?(turnId: string | undefined, event: AgentEvent): void;
+    /** Provider startup is session status, not a model item. Hosts that already
+     * published the response can forward it without synthesizing another start. */
+    onStatus?(note: string | undefined, statusKind?: "startup"): void;
     /** The current turn finished; `usage` is the runtime's raw snapshot if any. */
-    onTurnEnd(usage?: Record<string, unknown>): void;
+    onTurnEnd(usage?: Record<string, unknown>, reason?: "superseded"): void;
+    /** The provider confirmed that the active turn was explicitly interrupted. */
+    onTurnInterrupted?(usage?: Record<string, unknown>): void;
+    /** Resume proved that the newest turn is terminal even though its live edge
+     * was missed. This updates session state without replaying historical items. */
+    onRecoveredTurnStatus?(status: "idle" | "failed", turnId: string | undefined, error?: Error): void;
     /** A turn failed on the runtime. */
     onTurnError(error: Error): void;
+    /** A steer rejection proves a recorded turn is inactive, without its outcome. */
+    onTurnInactive?(turnId: string): void;
     /** The user's turn text (sourced from codex's `userMessage` item), so a
      *  co-driving TUI's prompt is recorded even though this process never injected it. */
     onUserMessage?(content: string | UserContentPart[]): void;
+    /** Out-of-lifecycle counterpart of `onUserMessage`, scoped when possible. */
+    onTurnContentUserMessage?(turnId: string | undefined, content: string | UserContentPart[]): void;
     /** A managed Core fork also broadcasts `thread/started`, but does not switch
      * the source TUI. Discard that notification before changing the bound thread. */
     shouldIgnoreThreadStarted?(threadId: string, forkedFromId?: string): boolean;
@@ -46,6 +65,22 @@ export interface CodexForwarderSink {
     /** The thread showed activity (a turn/item began, so its rollout now exists).
      *  Fired once; lets a parked `thread/resume` retry (reference implementation's ready signal). */
     onThreadActive?(): void;
+    /** The native TUI or another app-server client changed collaboration mode. */
+    onCollaborationModeChanged?(mode: CollaborationModeKind): void;
+    /** Full mutable settings reported by the native thread. In particular, a
+     * TUI `/model` switch must become the model used by the next mode snapshot. */
+    onThreadSettingsChanged?(settings: {
+        model?: string;
+        reasoningEffort?: ReasoningEffort | null;
+    }): void;
+    /** Codex's terminal-local Plan picker is not emitted by app-server today.
+     * Synthesize it only after a live Plan item and its Turn both complete. */
+    onPlanImplementationPrompt?(prompt: CodexPlanImplementationPrompt): void;
+}
+export interface CodexPlanImplementationPrompt {
+    threadId: string;
+    turnId: string;
+    text: string;
 }
 export interface CodexSessionForwarderOptions {
     /** Some Codex-lineage runtimes publish the final item one frame after
@@ -58,6 +93,9 @@ export interface CodexSessionForwarderOptions {
     assistantMessageGraceMs?: number;
     /** Surface Traex's provider-capacity queue as a canonical running status. */
     surfaceQueueStatus?: boolean;
+    /** Provider-configured MCP servers. Their startup round is synthesized because
+     * Codex currently sends per-server edges only to the thread-owning TUI. */
+    mcpStartup?: McpStartupPlan | null;
 }
 export declare class CodexSessionForwarder {
     private readonly client;
@@ -69,9 +107,16 @@ export declare class CodexSessionForwarder {
     private currentThreadIdValue;
     private activeSignaled;
     private completionTimer;
+    /** Turn id retained only for late-item dedup while a terminal response waits
+     * for its bounded output-ordering grace. It is not an active provider turn. */
+    private pendingCompletionTurnId;
     private assistantMessageTimer;
     private deferredAssistantMessage;
     private pendingCompletion;
+    private readonly pendingMcpServers;
+    private readonly failedMcpServers;
+    private mcpStartupTimer;
+    private lastMcpStatusNote;
     /** Completed-item dedup keys already mirrored (live vs resume backfill). Key =
      *  `threadId:turnId:item.id`; anonymous items use a per-(thread,turn) position
      *  counter. Mirrors reference implementation `_completed_item_key` + `synced_item_keys`. */
@@ -79,16 +124,40 @@ export declare class CodexSessionForwarder {
     /** Per-(thread,turn) position counter for items lacking a stable codex id
      *  (peek-then-advance; advanced only on a successful claim). reference implementation anon path. */
     private readonly anonCounters;
+    private pendingPlanImplementation;
+    /** Latest aggregate diff per Turn. Codex republishes the complete diff after
+     * every edit; only the terminal snapshot belongs in transcript history. */
+    private readonly turnDiffByTurn;
+    private replayingBackfill;
     constructor(client: CodexAppServerClient, sink: CodexForwarderSink, options?: CodexSessionForwarderOptions);
     /** Begin mirroring. Idempotent. */
     start(): void;
     stop(): void;
-    /** True while a turn is open — injection uses `turn/steer` then, else `turn/start`. */
+    /** True while the provider owns an active turn, including the short interval
+     * between injection acceptance and observer confirmation. */
     isTurnOpen(): boolean;
     /** The current turn's codex id (only meaningful while {@link isTurnOpen}). */
     currentTurnId(): string | null;
+    /** Reconcile a proven stale steer without clearing a newer observed turn. */
+    clearActiveTurnIfMatches(turnId: string): void;
+    /**
+     * Record a turn accepted by the injection connection before the independent
+     * observer receives `turn/started`. This closes the read-decide-RPC-write race:
+     * another web message arriving in that window must steer this turn, not start
+     * a second one.
+     */
+    noteTurnAccepted(turnId: string): void;
+    hasPendingMcpStartup(): boolean;
+    /** Mark and return the startup servers cancelled by a web Stop. */
+    cancelMcpStartup(): string[];
+    /** Diagnostic suffix for an injection failure during Provider startup. */
+    mcpStartupDetail(): string | null;
     /** The bound codex thread id captured from `thread/started` (null until then). */
     threadId(): string | null;
+    /** Seed an already-persisted/resumed thread binding. The bridge retains this
+     * state even when app-server does not rebroadcast `thread/started`, so
+     * terminal-boundary recovery must know it too. */
+    noteThreadBound(threadId: string): void;
     /**
      * Replay the backlog turns from a `thread/resume` response as if they were live
      * `item/completed` notifications — the fresh-thread first-turn backfill. Each
@@ -97,11 +166,21 @@ export declare class CodexSessionForwarder {
      * not doubled.
      */
     replayBackfill(turns: ResumedTurn[]): void;
+    /** Suppress our synthesized picker when a future app-server emits the native
+     * `plan_implementation` request itself. */
+    noteNativePlanImplementationPrompt(turnId?: string): void;
+    /** Fail an open response exactly once when its observer or terminal exits. */
+    failOpenTurn(error: Error): boolean;
     private handle;
     private scheduleCompletion;
     private refreshCompletionGrace;
     private flushPendingCompletion;
     private settle;
+    private handleMcpStartupStatus;
+    private settleMcpStartup;
+    private clearMcpStartupTimer;
+    private emitMcpStartupStatus;
+    private emitMcpStatus;
     /** Map + emit one completed codex item, deduped by a TOTAL key and routing the
      *  user echo to {@link CodexForwarderSink.onUserMessage}. Shared by live + backfill. */
     private processCompletedItem;
@@ -118,4 +197,18 @@ export declare class CodexSessionForwarder {
     private completedItemKey;
     private advanceAnonCounter;
     private ensureTurn;
+    private consumeTurnDiff;
+    /** Start (or confirm) the app-server's authoritative active turn. A newer
+     * start supersedes an older response whose terminal edge arrived late; a
+     * pending Traex completion is flushed first so its final item grace remains
+     * intact. */
+    private beginTurn;
+    /** Active-turn clearing contract:
+     *
+     * - an identified active turn is closed only by the same id;
+     * - an id-less boundary cannot close an identified active turn;
+     * - with no observed active turn, an identified boundary may recover a
+     *   missed start only when it carries the currently-bound thread id. */
+    private terminalBoundaryMatchesActiveTurn;
+    private notificationMatchesCurrentThread;
 }