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

package/dist/claude/transcript.js

@@ -15,6 +15,7 @@
 import { readFileSync } from "node:fs";
 import { open, stat } from "node:fs/promises";
 import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
 /** A sub-agent (Task) writes its own transcript to
  *  `<project>/<sessionId>/subagents/agent-<agentId>.jsonl`, alongside the parent
  *  `<sessionId>.jsonl`. Derive that path from the parent transcript path. */
@@ -22,11 +23,32 @@ export function subagentTranscriptPath(parentTranscriptPath, agentId) {
     const dir = parentTranscriptPath.replace(/\.jsonl$/, "");
     return join(dir, "subagents", `agent-${agentId}.jsonl`);
 }
+function strippedImagePlaceholder(source) {
+    const mediaType = source.media_type;
+    const label = typeof mediaType === "string" && mediaType ? `${mediaType} image` : "image";
+    return `[${label} omitted from history to save context — re-run the tool call above (e.g. Read the same path) to view it again]`;
+}
+/** Remove Claude's inline image bytes before tool output reaches canonical
+ *  history. A Read image result can contain a full-resolution base64 payload;
+ *  replaying it as text only bloats the transcript, while the model cannot use
+ *  those encoded bytes as text. Keep a small, human-readable marker instead. */
+function stripInlineImageData(value) {
+    if (Array.isArray(value))
+        return value.map(stripInlineImageData);
+    if (!isObject(value))
+        return value;
+    const source = isObject(value.source) ? value.source : undefined;
+    if (value.type === "image" && source) {
+        return { type: "text", text: strippedImagePlaceholder(source) };
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, stripInlineImageData(nested)]));
+}
 function stringifyToolContent(content) {
-    if (typeof content === "string")
-        return content;
-    if (Array.isArray(content)) {
-        return content
+    const stripped = stripInlineImageData(content);
+    if (typeof stripped === "string")
+        return stripped;
+    if (Array.isArray(stripped)) {
+        return stripped
             .map((part) => part && typeof part === "object" && "text" in part
             ? String(part.text ?? "")
             : typeof part === "string"
@@ -34,22 +56,26 @@ function stringifyToolContent(content) {
                 : JSON.stringify(part))
             .join("");
     }
-    return content == null ? "" : JSON.stringify(content);
-}
-function toolLabel(name, input) {
-    if (input && typeof input === "object") {
-        const rec = input;
-        for (const key of ["command", "cmd", "path", "file_path", "pattern", "query"]) {
-            const v = rec[key];
-            if (typeof v === "string" && v)
-                return v;
-        }
-    }
-    return name ?? "tool";
+    return stripped == null ? "" : JSON.stringify(stripped);
 }
 const BASH_INPUT_RE = /<bash-input>([\s\S]*?)<\/bash-input>/;
 const BASH_STDOUT_RE = /<bash-stdout>([\s\S]*?)<\/bash-stdout>/;
 const BASH_STDERR_RE = /<bash-stderr>([\s\S]*?)<\/bash-stderr>/;
+/** Parse either half of Claude's shell-mode record. Newer and older Claude
+ * builds may split `<bash-input>` from the later stdout/stderr record. */
+export function parseTerminalCommandFragments(content) {
+    const input = BASH_INPUT_RE.exec(content);
+    const stdout = BASH_STDOUT_RE.exec(content);
+    const stderr = BASH_STDERR_RE.exec(content);
+    if (!input && !stdout && !stderr)
+        return undefined;
+    return {
+        ...(input ? { command: input[1].trim() } : {}),
+        ...(stdout ? { stdout: stdout[1] } : {}),
+        ...(stderr ? { stderr: stderr[1] } : {}),
+        hasOutput: Boolean(stdout || stderr),
+    };
+}
 /**
  * Parse a claude local-command (`!` bash mode) user record's string content into
  * a {@link TerminalCommandData}. Claude records the command and its captured
@@ -59,16 +85,14 @@ const BASH_STDERR_RE = /<bash-stderr>([\s\S]*?)<\/bash-stderr>/;
  * `<system-reminder>`) are bookkeeping, not terminal commands.
  */
 export function parseTerminalCommand(content) {
-    const input = BASH_INPUT_RE.exec(content);
-    if (!input)
+    const fragments = parseTerminalCommandFragments(content);
+    if (!fragments || fragments.command === undefined)
         return undefined;
-    const data = { command: input[1].trim() };
-    const stdout = BASH_STDOUT_RE.exec(content)?.[1];
-    const stderr = BASH_STDERR_RE.exec(content)?.[1];
-    if (stdout)
-        data.stdout = stdout;
-    if (stderr)
-        data.stderr = stderr;
+    const data = { command: fragments.command };
+    if (fragments.stdout)
+        data.stdout = fragments.stdout;
+    if (fragments.stderr)
+        data.stderr = fragments.stderr;
     return data;
 }
 /**
@@ -103,26 +127,42 @@ export function parseTranscriptRecord(record, opts) {
     if (rec.isSidechain && !parent)
         return []; // sub-agent turns are replayed separately
     const message = rec.message;
-    if (!message || !Array.isArray(message.content))
+    if (!message)
         return [];
     const out = [];
     if (rec.type === "assistant" && message.role === "assistant") {
+        const content = typeof message.content === "string"
+            ? [{ type: "text", text: message.content }]
+            : message.content;
+        if (!Array.isArray(content))
+            return [];
         // Claude writes this zero-token synthetic filler after an accidental empty
         // submit. It is transcript bookkeeping, not an assistant response. Filter
         // by provider provenance and exact shape here, before normalization loses
         // `model: "<synthetic>"`; a UI string filter could hide legitimate output.
         if (!rec.isApiErrorMessage &&
             message.model === "<synthetic>" &&
-            message.content.length === 1 &&
-            message.content[0]?.type === "text" &&
-            message.content[0].text === "No response requested.") {
+            content.length === 1 &&
+            content[0]?.type === "text" &&
+            content[0].text === "No response requested.") {
             return [];
         }
         const itemId = message.id;
-        const texts = [];
-        for (const block of message.content) {
+        const textBlockCount = content.filter((block) => block.type === "text" && block.text).length;
+        for (const [blockIndex, block] of content.entries()) {
             if (block.type === "text" && block.text) {
-                texts.push(block.text);
+                // Preserve Claude's block order. Keep a single text block's
+                // native message id for MessageDisplay correlation; only derive an id
+                // when one record contains multiple independently ordered text blocks.
+                const textItemId = itemId && textBlockCount > 1
+                    ? `${itemId}:text:${blockIndex}`
+                    : itemId;
+                out.push({
+                    type: "message_completed",
+                    text: block.text,
+                    ...(textItemId ? { itemId: textItemId } : {}),
+                    ...parentTag,
+                });
             }
             else if (block.type === "thinking" && block.thinking) {
                 out.push({ type: "reasoning_completed", summary: [block.thinking], ...(itemId ? { itemId } : {}), ...parentTag });
@@ -132,18 +172,20 @@ export function parseTranscriptRecord(record, opts) {
                     type: "tool",
                     event: "on_tool_start",
                     name: block.name,
-                    input: { ...(isObject(block.input) ? block.input : {}), id: block.id, command: toolLabel(block.name, block.input) },
-                    data: { id: block.id },
+                    input: { ...(isObject(block.input) ? block.input : {}), id: block.id },
+                    // A transcript tool_use is already a completed Provider record. Live
+                    // runtimes still omit this marker and remain in_progress until their
+                    // completion event arrives.
+                    data: { id: block.id, itemStatus: "completed" },
                     ...parentTag,
                 });
             }
         }
-        if (texts.length) {
-            out.push({ type: "message_completed", text: texts.join(""), ...(itemId ? { itemId } : {}), ...parentTag });
-        }
         return out;
     }
     if (rec.type === "user" && message.role === "user") {
+        if (!Array.isArray(message.content))
+            return [];
         for (const block of message.content) {
             if (block.type === "tool_result") {
                 out.push({
@@ -156,7 +198,7 @@ export function parseTranscriptRecord(record, opts) {
                         exitCode: null,
                     },
                     ...(block.is_error ? { error: "tool_error" } : {}),
-                    data: { tool_use_id: block.tool_use_id },
+                    data: { tool_use_id: block.tool_use_id, itemStatus: "completed" },
                     ...parentTag,
                 });
             }
@@ -169,13 +211,14 @@ function isObject(value) {
 }
 /**
  * Whether a transcript is a `/fork` (branch) of another session: claude stamps a
- * `forkedFrom: { sessionId }` marker in an early record pointing at the source
+ * `forkedFrom: { sessionId }` marker on copied records pointing at the source
  * session (reference implementation's `transcript_has_forked_from_marker`). Used to distinguish a
  * fork from an ordinary `resume` (both arrive as `SessionStart source="resume"`).
- * Scans only the head of the file (the marker lands up front). NOTE: unverified on
- * this host — no local transcript carries the marker — so it follows reference implementation's shape.
+ * The marker must belong to the announced target and expected source; sample
+ * the first and last 200 records because long copied histories can place it at
+ * either edge.
  */
-export function transcriptHasForkedFrom(path, currentSessionId) {
+export function transcriptHasForkedFrom(path, claudeSessionId, sourceClaudeSessionId) {
     let text;
     try {
         text = readFileSync(path, "utf8");
@@ -183,17 +226,60 @@ export function transcriptHasForkedFrom(path, currentSessionId) {
     catch {
         return false;
     }
-    let scanned = 0;
-    for (const line of text.split("\n")) {
-        if (++scanned > 200)
-            break;
+    const lines = text.split("\n");
+    const sampled = lines.length <= 400
+        ? lines
+        : [...lines.slice(0, 200), ...lines.slice(-200)];
+    for (const line of sampled) {
         const trimmed = line.trim();
         if (!trimmed || !trimmed.includes("forkedFrom"))
             continue;
         try {
             const rec = JSON.parse(trimmed);
+            if (rec.sessionId !== claudeSessionId)
+                continue;
             const from = rec.forkedFrom?.sessionId;
-            if (typeof from === "string" && from && from !== currentSessionId)
+            if (typeof from === "string" &&
+                from &&
+                from !== claudeSessionId &&
+                (sourceClaudeSessionId === undefined || from === sourceClaudeSessionId))
+                return true;
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    return false;
+}
+const RECENT_LOCAL_COMMAND_LINE_LIMIT = 200;
+const RECENT_LOCAL_COMMAND_WINDOW_MS = 10_000;
+/** Claude versions without a copied-record marker still persist `/fork` and
+ * `/branch` as a recent top-level local command. Match only the new native
+ * Session and the hook's narrow time window. */
+export function transcriptHasRecentLocalCommand(path, claudeSessionId, recordedAtMs, commandNames = new Set(["/fork", "/branch"])) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        return false;
+    }
+    for (const line of text.split("\n").slice(-RECENT_LOCAL_COMMAND_LINE_LIMIT)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const rec = JSON.parse(trimmed);
+            if (rec.sessionId !== claudeSessionId || rec.subtype !== "local_command")
+                continue;
+            const timestamp = transcriptTimestampMs(rec.timestamp);
+            if (timestamp === undefined ||
+                Math.abs(timestamp - recordedAtMs) > RECENT_LOCAL_COMMAND_WINDOW_MS ||
+                typeof rec.content !== "string")
+                continue;
+            const command = /<command-name>([\s\S]*?)<\/command-name>/
+                .exec(rec.content)?.[1]?.trim();
+            if (command && commandNames.has(command))
                 return true;
         }
         catch {
@@ -202,6 +288,31 @@ export function transcriptHasForkedFrom(path, currentSessionId) {
     }
     return false;
 }
+/** Wait briefly for Claude to flush either fork signal after SessionStart.
+ * The observer hook calls this before recording the edge, allowing a
+ * one-second late-marker window without delaying ordinary transcript polling. */
+export async function waitForTranscriptForkSignal(path, claudeSessionId, sourceClaudeSessionId, recordedAtMs, options = {}) {
+    const timeoutMs = Math.max(0, options.timeoutMs ?? 1_000);
+    const pollMs = Math.max(1, options.pollMs ?? 50);
+    const deadline = Date.now() + timeoutMs;
+    do {
+        if (transcriptHasForkedFrom(path, claudeSessionId, sourceClaudeSessionId) ||
+            transcriptHasRecentLocalCommand(path, claudeSessionId, recordedAtMs))
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await sleep(Math.min(pollMs, Math.max(1, deadline - Date.now())));
+    } while (true);
+}
+function transcriptTimestampMs(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value < 10_000_000_000 ? value * 1_000 : value;
+    }
+    if (typeof value !== "string" || !value)
+        return undefined;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
 /**
  * Read a sub-agent (Task) transcript in full and map it to {@link AgentEvent}s
  * tagged with `parentToolUseId`. Called once the parent Task tool_result arrives

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

@@ -1,5 +1,5 @@
 import type { RuntimeUserInput, SessionInteractionResolution } from "@rynx-ai/core";
-import type { AskForApproval, ClientInfo, CollaborationModeListResponse, GetAuthStatusParams, GetAuthStatusResponse, InitializeResponse, ModelListParams, ModelListResponse, ReviewStartParams, ReviewStartResponse, SandboxMode, ThreadForkParams, ThreadGoalClearParams, ThreadGoalGetParams, ThreadGoalGetResponse, ThreadGoalSetParams, ThreadListParams, ThreadListResponse, ResumedThread, ThreadResumeParams, ThreadSettingsUpdateParams, ThreadStartParams, TurnInterruptParams, TurnStartParams, TurnSteerParams, UserInput } from "./protocol.js";
+import type { AskForApproval, ClientInfo, CollaborationModeListResponse, ConfigReadParams, ConfigReadResponse, GetAuthStatusParams, GetAuthStatusResponse, InitializeResponse, ModelListParams, ModelListResponse, ReviewStartParams, ReviewStartResponse, SandboxMode, ThreadForkParams, ThreadGoalClearParams, ThreadGoalGetParams, ThreadGoalGetResponse, ThreadGoalSetParams, ThreadListParams, ThreadListResponse, ResumedThread, ThreadResumeParams, ThreadRuntimeSettings, ThreadSettingsUpdateParams, ThreadStartParams, TurnInterruptParams, TurnStartParams, TurnSteerParams, UserInput } from "./protocol.js";
 import { CodexAppServerTransport, type CodexAppServerProcessSpawner, type RpcChannel, type TransportLogger } from "./transport.js";
 import type { ResolveInteractionResult, RuntimeInteractionListener } from "../interactions.js";
 export type ApprovalDecisionPolicy = "auto-approve-session" | "auto-decline" | "auto-cancel";
@@ -29,9 +29,11 @@ export declare class CodexAppServerClient {
     private interactionListener;
     private connectionListener;
     private connectionState;
+    private connectionEstablished;
     private readonly pendingInteractions;
     private readonly settledInteractions;
     private initializeResponse;
+    private initializePromise;
     constructor({ spawner, channel, logger, clientInfo, approvalDecisionPolicy, }: CodexAppServerClientOptions);
     /**
      * The multi-client endpoint a `codex --remote` TUI can attach to, when this
@@ -42,13 +44,16 @@ export declare class CodexAppServerClient {
     terminalRemoteUrl(): string | undefined;
     ensureInitialized(): Promise<InitializeResponse>;
     getAuthStatus(params?: GetAuthStatusParams): Promise<GetAuthStatusResponse>;
+    /** Read the runtime's merged effective config. This is the stable seam for
+     * discovering a fresh thread's model across Traex YAML/TOML generations. */
+    configRead(params: ConfigReadParams): Promise<ConfigReadResponse>;
     threadStart(params: ThreadStartParams): Promise<{
         threadId: string;
-    }>;
+    } & ThreadRuntimeSettings>;
     threadResume(params: ThreadResumeParams): Promise<{
         threadId: string;
         thread: ResumedThread;
-    }>;
+    } & ThreadRuntimeSettings>;
     turnStart(params: TurnStartParams): Promise<{
         turnId: string;
     }>;
@@ -94,9 +99,8 @@ export declare class CodexAppServerClient {
      * resolver still wins correctly.
      */
     setInteractionListener(listener: RuntimeInteractionListener | null): void;
-    /** Observe the underlying app-server connection independently from any one
-     * interaction. A disconnected client that never received the duplicate
-     * native request still has to count as unavailable during host failover. */
+    /** Observe the initialized connection lifecycle. Registration never reports
+     * disconnected for a client that has not connected yet. */
     setConnectionListener(listener: ((state: "connected" | "disconnected") => void) | null): void;
     private setConnectionState;
     resolveInteraction(interactionId: string, resolution: SessionInteractionResolution): ResolveInteractionResult;

package/dist/codex-app-server/client.js

@@ -953,9 +953,11 @@ export class CodexAppServerClient {
     interactionListener = null;
     connectionListener = null;
     connectionState = "disconnected";
+    connectionEstablished = false;
     pendingInteractions = new Map();
     settledInteractions = new Set();
     initializeResponse = null;
+    initializePromise = null;
     constructor({ spawner, channel, logger = defaultLogger, clientInfo = DEFAULT_CLIENT_INFO, approvalDecisionPolicy = "auto-approve-session", }) {
         this.logger = logger;
         this.clientInfo = clientInfo;
@@ -988,30 +990,66 @@ export class CodexAppServerClient {
         if (this.initializeResponse) {
             return this.initializeResponse;
         }
-        await this.transport.ensureStarted();
-        const response = await this.transport.sendRequest("initialize", {
-            clientInfo: this.clientInfo,
-            capabilities: { experimentalApi: true },
-        });
-        this.initializeResponse = response;
-        this.setConnectionState("connected");
-        return response;
+        if (this.initializePromise)
+            return this.initializePromise;
+        const initializing = (async () => {
+            await this.transport.ensureStarted();
+            const response = await this.transport.sendRequest("initialize", {
+                clientInfo: this.clientInfo,
+                capabilities: { experimentalApi: true },
+            });
+            // Codex app-server uses the full initialize handshake: it does not accept
+            // capability requests after merely replying to `initialize`. The client
+            // must acknowledge that response with the `initialized` notification
+            // before `thread/resume`, `turn/start`, and the other APIs are legal.
+            await this.transport.sendNotification("initialized");
+            this.initializeResponse = response;
+            this.setConnectionState("connected");
+            return response;
+        })();
+        this.initializePromise = initializing;
+        try {
+            return await initializing;
+        }
+        finally {
+            if (this.initializePromise === initializing)
+                this.initializePromise = null;
+        }
     }
     async getAuthStatus(params = {}) {
         await this.ensureInitialized();
         return this.transport.sendRequest("getAuthStatus", params);
     }
+    /** Read the runtime's merged effective config. This is the stable seam for
+     * discovering a fresh thread's model across Traex YAML/TOML generations. */
+    async configRead(params) {
+        await this.ensureInitialized();
+        return this.transport.sendRequest("config/read", params);
+    }
     async threadStart(params) {
         await this.ensureInitialized();
         const response = await this.transport.sendRequest("thread/start", params);
-        return { threadId: response.thread.id };
+        return {
+            threadId: response.thread.id,
+            ...(response.model ? { model: response.model } : {}),
+            ...(response.reasoningEffort === undefined
+                ? {}
+                : { reasoningEffort: response.reasoningEffort }),
+        };
     }
     async threadResume(params) {
         await this.ensureInitialized();
         const response = await this.transport.sendRequest("thread/resume", params);
         // Expose the whole `thread` (not just its id): its `turns[].items[]` are the
         // backfill the forwarder replays for a fresh thread's first turn.
-        return { threadId: response.thread.id, thread: response.thread };
+        return {
+            threadId: response.thread.id,
+            thread: response.thread,
+            ...(response.model ? { model: response.model } : {}),
+            ...(response.reasoningEffort === undefined
+                ? {}
+                : { reasoningEffort: response.reasoningEffort }),
+        };
     }
     async turnStart(params) {
         await this.ensureInitialized();
@@ -1146,14 +1184,18 @@ export class CodexAppServerClient {
     setInteractionListener(listener) {
         this.interactionListener = listener;
     }
-    /** Observe the underlying app-server connection independently from any one
-     * interaction. A disconnected client that never received the duplicate
-     * native request still has to count as unavailable during host failover. */
+    /** Observe the initialized connection lifecycle. Registration never reports
+     * disconnected for a client that has not connected yet. */
     setConnectionListener(listener) {
         this.connectionListener = listener;
-        listener?.(this.connectionState);
+        if (listener && this.connectionEstablished)
+            listener(this.connectionState);
     }
     setConnectionState(state) {
+        if (state === "connected")
+            this.connectionEstablished = true;
+        if (state === "disconnected" && !this.connectionEstablished)
+            return;
         if (this.connectionState === state)
             return;
         this.connectionState = state;
@@ -1363,7 +1405,17 @@ export function buildTextUserInput(message) {
 export function buildRuntimeUserInput(input) {
     return input.content.map((part) => part.type === "text"
         ? { type: "text", text: part.text, text_elements: [] }
-        : { type: "localImage", path: part.path });
+        : part.type === "local_image"
+            ? { type: "localImage", path: part.path }
+            : {
+                type: "text",
+                text: `[[RYNX_FILE_RESOURCE ${JSON.stringify({
+                    path: part.path,
+                    ...(part.resource.filename ? { filename: part.resource.filename } : {}),
+                    mediaType: part.resource.mediaType,
+                })}]]\nInspect this absolute file path with the available file-reading tools before answering.`,
+                text_elements: [],
+            });
 }
 const defaultLogger = {
     log(entry) {

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

@@ -23,20 +23,37 @@
  */
 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;
     /** 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 +63,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 +91,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 +105,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 +122,38 @@ 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;
+    /**
+     * 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 +162,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 +193,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;
 }