@rynx-ai/runtime 0.1.11-beta.24 → 0.1.11-beta.26

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

@@ -1,4 +1,4 @@
-import { codexUserContent } from "../input-resources.js";
+import { codexUserEchoContent } from "../input-resources.js";
 import { codexResumeTerminalStatus, mapCodexItem, mapCodexNotification, } from "./mapping.js";
 const MCP_STARTUP_STATUS_METHOD = "mcpServer/startupStatus/updated";
 const MCP_TERMINAL_STATES = new Set(["ready", "failed", "cancelled"]);
@@ -13,14 +13,7 @@ function turnIdFrom(params) {
 function userMessageContent(item) {
     if (item.type !== "userMessage")
         return undefined;
-    const parts = codexUserContent(item.content);
-    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;
+    return codexUserEchoContent(item.content);
 }
 /** Whether a notification implies the thread is now active (its first turn has
  *  begun, so the rollout exists). Mirrors reference implementation's `_event_indicates_thread_active`. */
@@ -59,6 +52,20 @@ function isTurnScopedMethod(method) {
 function canRecoverMissedTurnFrom(method) {
     return method === "item/agentMessage/delta" || method === "item/plan/delta";
 }
+/** Omnigent forwards these live deltas only for the bridge's exact active
+ * Codex turn. Assistant/plan deltas may recover a missed `turn/started` when
+ * fully scoped; command output never opens or recovers a Turn. */
+function requiresMatchingActiveTurn(method) {
+    return canRecoverMissedTurnFrom(method) || method === "item/commandExecution/outputDelta";
+}
+/** Content Omnigent forwards independently from the active-turn status edge. */
+function isIndependentTurnContent(method) {
+    return method === "item/started" ||
+        method === "item/reasoning/textDelta" ||
+        method === "item/reasoning/summaryTextDelta" ||
+        method === "item/fileChange/patchUpdated" ||
+        method === "turn/plan/updated";
+}
 export class CodexSessionForwarder {
     client;
     sink;
@@ -86,6 +93,11 @@ export 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. */
     anonCounters = new Map();
+    pendingPlanImplementation = null;
+    /** Latest aggregate diff per Turn. Codex republishes the complete diff after
+     * every edit; only the terminal snapshot belongs in transcript history. */
+    turnDiffByTurn = new Map();
+    replayingBackfill = false;
     constructor(client, sink, options = {}) {
         this.client = client;
         this.sink = sink;
@@ -120,6 +132,7 @@ export class CodexSessionForwarder {
         else {
             this.currentTurnIdValue = null;
         }
+        this.turnDiffByTurn.clear();
     }
     /** True while the provider owns an active turn, including the short interval
      * between injection acceptance and observer confirmation. */
@@ -191,22 +204,37 @@ export class CodexSessionForwarder {
      * not doubled.
      */
     replayBackfill(turns) {
-        for (const turn of turns) {
-            const turnId = turn.id ?? turn.turnId;
-            if (turnId)
-                this.currentTurnIdValue = turnId;
-            this.ensureTurn();
-            for (const item of turn.items ?? [])
-                this.processCompletedItem(item);
-            if (codexResumeTerminalStatus(turn) === undefined)
-                continue;
-            const mapped = mapCodexNotification("turn/completed", { turn });
-            this.turnOpen = false;
-            this.currentTurnIdValue = null;
-            if (mapped.fatalError)
-                this.sink.onTurnError(mapped.fatalError);
-            else
-                this.sink.onTurnEnd(mapped.usage);
+        this.replayingBackfill = true;
+        try {
+            for (const turn of turns) {
+                const turnId = turn.id ?? turn.turnId;
+                if (turnId)
+                    this.currentTurnIdValue = turnId;
+                this.ensureTurn();
+                for (const item of turn.items ?? [])
+                    this.processCompletedItem(item);
+                if (codexResumeTerminalStatus(turn) === undefined)
+                    continue;
+                const mapped = mapCodexNotification("turn/completed", { turn });
+                this.turnOpen = false;
+                this.currentTurnIdValue = null;
+                if (mapped.fatalError)
+                    this.sink.onTurnError(mapped.fatalError);
+                else
+                    this.sink.onTurnEnd(mapped.usage);
+            }
+        }
+        finally {
+            this.replayingBackfill = false;
+        }
+    }
+    /** Suppress our synthesized picker when a future app-server emits the native
+     * `plan_implementation` request itself. */
+    noteNativePlanImplementationPrompt(turnId) {
+        if (!this.pendingPlanImplementation)
+            return;
+        if (!turnId || this.pendingPlanImplementation.turnId === turnId) {
+            this.pendingPlanImplementation = null;
         }
     }
     /** Fail an open response exactly once when its observer or terminal exits. */
@@ -234,6 +262,7 @@ export class CodexSessionForwarder {
                 }
                 this.currentTurnIdValue = null;
                 this.activeSignaled = false;
+                this.turnDiffByTurn.clear();
                 this.currentThreadIdValue = tid;
                 this.sink.onThreadStarted?.(tid, normalizedForkedFromId);
             }
@@ -248,6 +277,14 @@ export class CodexSessionForwarder {
             this.handleMcpStartupStatus(params);
             return;
         }
+        if (method === "thread/settings/updated") {
+            const threadSettings = params?.threadSettings;
+            const mode = (threadSettings?.collaborationMode ?? threadSettings?.collaboration_mode)?.mode;
+            if (mode === "plan" || mode === "default") {
+                this.sink.onCollaborationModeChanged?.(mode);
+            }
+            return;
+        }
         if (isThreadIdle(method, params) || isModelOutput(method, params)) {
             this.settleMcpStartup();
         }
@@ -264,6 +301,21 @@ export class CodexSessionForwarder {
         if (method === "queue/status" && this.currentTurnIdValue === null)
             return;
         const carriedTurnId = turnIdFrom(params);
+        if (method === "turn/diff/updated") {
+            if (!carriedTurnId)
+                return;
+            const update = params;
+            const diff = typeof update?.diff === "string"
+                ? update.diff
+                : typeof update?.unifiedDiff === "string"
+                    ? update.unifiedDiff
+                    : "";
+            if (diff)
+                this.turnDiffByTurn.set(carriedTurnId, diff);
+            else
+                this.turnDiffByTurn.delete(carriedTurnId);
+            return;
+        }
         if (method === "turn/started") {
             this.beginTurn(carriedTurnId);
             this.sink.onTurnObserved?.(carriedTurnId);
@@ -271,12 +323,21 @@ export class CodexSessionForwarder {
         }
         if (isTerminalTurnMethod(method)) {
             if (!this.terminalBoundaryMatchesActiveTurn(carriedTurnId, notificationThreadId)) {
+                const staleDiff = this.consumeTurnDiff(carriedTurnId);
+                if (staleDiff && carriedTurnId) {
+                    this.sink.onTurnContentEvent?.(carriedTurnId, staleDiff);
+                }
                 return;
             }
             const hadActiveTurn = this.currentTurnIdValue !== null;
             const hadOpenResponse = this.turnOpen;
             const mapped = mapCodexNotification(method, params);
+            const terminalTurnId = carriedTurnId ?? this.currentTurnIdValue;
+            const turnDiff = this.consumeTurnDiff(terminalTurnId);
             if (!hadActiveTurn && !hadOpenResponse) {
+                if (turnDiff && terminalTurnId) {
+                    this.sink.onTurnContentEvent?.(terminalTurnId, turnDiff);
+                }
                 const turn = params?.turn;
                 const recoveredStatus = mapped.fatalError ||
                     method === "turn/failed" ||
@@ -298,10 +359,18 @@ export class CodexSessionForwarder {
                 this.sink.onEvent(event);
             }
             this.scheduleCompletion(mapped.fatalError
-                ? { kind: "error", error: mapped.fatalError }
+                ? { kind: "error", error: mapped.fatalError, ...(turnDiff ? { turnDiff } : {}) }
                 : mapped.turnInterrupted
-                    ? { kind: "interrupted", ...(mapped.usage ? { usage: mapped.usage } : {}) }
-                    : { kind: "end", ...(mapped.usage ? { usage: mapped.usage } : {}) });
+                    ? {
+                        kind: "interrupted",
+                        ...(mapped.usage ? { usage: mapped.usage } : {}),
+                        ...(turnDiff ? { turnDiff } : {}),
+                    }
+                    : {
+                        kind: "end",
+                        ...(mapped.usage ? { usage: mapped.usage } : {}),
+                        ...(turnDiff ? { turnDiff } : {}),
+                    });
             return;
         }
         // A late event from an older turn must not replace the app-server's active
@@ -310,32 +379,66 @@ export class CodexSessionForwarder {
             this.currentTurnIdValue &&
             carriedTurnId !== this.currentTurnIdValue &&
             isTurnScopedMethod(method)) {
-            return;
+            // Durable completed items and passive content belong to their carried
+            // response even if a newer Turn is active. Only active-turn deltas and
+            // lifecycle edges are stale with respect to the newer Turn.
+            if (method === "item/completed") {
+                // Continue into the completed-item dedup/order path below.
+            }
+            else if (isIndependentTurnContent(method) && this.sink.onTurnContentEvent) {
+                const mapped = mapCodexNotification(method, params);
+                for (const event of mapped.events) {
+                    if (event.type !== "runtime_debug") {
+                        this.sink.onTurnContentEvent(carriedTurnId, event);
+                    }
+                }
+                return;
+            }
+            else {
+                return;
+            }
         }
-        if (carriedTurnId && this.currentTurnIdValue === null) {
-            if (canRecoverMissedTurnFrom(method)) {
-                if (!this.notificationMatchesCurrentThread(notificationThreadId))
+        if (requiresMatchingActiveTurn(method)) {
+            if (this.currentTurnIdValue !== null) {
+                // An id-less delta is not attributable to the active Turn. Omnigent's
+                // `_is_active_turn_delta` applies the same exact-id requirement.
+                if (carriedTurnId !== this.currentTurnIdValue)
                     return;
+            }
+            else if (carriedTurnId &&
+                canRecoverMissedTurnFrom(method) &&
+                this.notificationMatchesCurrentThread(notificationThreadId)) {
                 this.currentTurnIdValue = carriedTurnId;
                 this.ensureTurn();
             }
+            else {
+                return;
+            }
         }
         // Completed items (user echo, assistant, tool, reasoning) go through the
         // deduped path so a resume backfill and the live stream never double them.
         if (method === "item/completed") {
             const item = params?.item;
             if (item) {
+                if (carriedTurnId &&
+                    this.currentTurnIdValue &&
+                    carriedTurnId !== this.currentTurnIdValue) {
+                    // This is durable content for an older response, not an ordering
+                    // signal for the newer Turn's deferred assistant message.
+                    this.processCompletedItem(item, carriedTurnId);
+                    return;
+                }
                 if (this.shouldDeferAssistantMessage(item)) {
-                    this.deferAssistantMessage(item);
+                    this.deferAssistantMessage(item, carriedTurnId);
                     this.refreshCompletionGrace();
                     return;
                 }
-                // A late reasoning item belongs before the held final answer. Any other
-                // completed item establishes that the held message was not final and
-                // must retain its original position.
+                // Within one Turn, a late reasoning item belongs before the held final
+                // answer. Any other completed item establishes that the held message
+                // was not final and must retain its original position.
                 if (item.type !== "reasoning")
                     this.flushDeferredAssistantMessage();
-                this.processCompletedItem(item);
+                this.processCompletedItem(item, carriedTurnId);
                 this.refreshCompletionGrace();
                 return;
             }
@@ -350,6 +453,19 @@ export class CodexSessionForwarder {
         if (canonicalEvents.some((event) => event.type !== "reasoning_delta" && event.type !== "reasoning_completed")) {
             this.flushDeferredAssistantMessage();
         }
+        // Omnigent's item/content channel is independent from its turn-status
+        // channel. A scoped item or reasoning delta that arrives after the terminal
+        // edge remains visible, but must not synthesize another running response.
+        if (!this.turnOpen &&
+            this.currentTurnIdValue === null &&
+            !mapped.fatalError &&
+            canonicalEvents.length > 0 &&
+            this.sink.onTurnContentEvent) {
+            for (const event of canonicalEvents) {
+                this.sink.onTurnContentEvent(carriedTurnId, event);
+            }
+            return;
+        }
         if (canonicalEvents.length || mapped.turnCompleted || mapped.fatalError) {
             this.ensureTurn();
         }
@@ -400,6 +516,18 @@ export class CodexSessionForwarder {
     }
     settle(completion) {
         this.flushDeferredAssistantMessage();
+        const completedTurnId = this.pendingCompletionTurnId ?? this.currentTurnIdValue;
+        const planPrompt = completion.kind === "end" &&
+            this.pendingPlanImplementation?.turnId === completedTurnId
+            ? this.pendingPlanImplementation
+            : null;
+        if (this.pendingPlanImplementation?.turnId === completedTurnId) {
+            this.pendingPlanImplementation = null;
+        }
+        if (completion.turnDiff)
+            this.sink.onEvent(completion.turnDiff);
+        if (completedTurnId)
+            this.turnDiffByTurn.delete(completedTurnId);
         this.turnOpen = false;
         this.currentTurnIdValue = null;
         this.pendingCompletionTurnId = null;
@@ -411,8 +539,11 @@ export class CodexSessionForwarder {
             else
                 this.sink.onTurnEnd(completion.usage);
         }
-        else
+        else {
             this.sink.onTurnEnd(completion.usage);
+            if (planPrompt)
+                this.sink.onPlanImplementationPrompt?.(planPrompt);
+        }
     }
     handleMcpStartupStatus(params) {
         const update = params;
@@ -483,31 +614,52 @@ export class CodexSessionForwarder {
     }
     /** Map + emit one completed codex item, deduped by a TOTAL key and routing the
      *  user echo to {@link CodexForwarderSink.onUserMessage}. Shared by live + backfill. */
-    processCompletedItem(item) {
-        if (!this.claimCompletedItem(item))
+    processCompletedItem(item, completedTurnId) {
+        if (!this.claimCompletedItem(item, completedTurnId))
             return;
-        this.emitCompletedItem(item);
+        this.emitCompletedItem(item, completedTurnId);
     }
-    claimCompletedItem(item) {
-        const { key, isAnon } = this.completedItemKey(item);
+    claimCompletedItem(item, completedTurnId) {
+        const { key, isAnon } = this.completedItemKey(item, completedTurnId);
         if (this.seenCompletedItems.has(key))
             return false;
         this.seenCompletedItems.add(key);
         if (isAnon)
-            this.advanceAnonCounter();
+            this.advanceAnonCounter(completedTurnId);
         return true;
     }
-    emitCompletedItem(item) {
+    emitCompletedItem(item, completedTurnId) {
+        const outsideTurnLifecycle = !this.turnOpen || Boolean(completedTurnId &&
+            this.currentTurnIdValue &&
+            completedTurnId !== this.currentTurnIdValue);
         const userContent = userMessageContent(item);
         if (userContent !== undefined) {
+            if (outsideTurnLifecycle && this.sink.onTurnContentUserMessage) {
+                this.sink.onTurnContentUserMessage(completedTurnId, userContent);
+                return;
+            }
             this.ensureTurn();
             this.sink.onUserMessage?.(userContent);
             return;
         }
+        if (item.type === "plan" && !this.replayingBackfill) {
+            const text = item.text?.trim();
+            const turnId = this.currentTurnIdValue ?? this.pendingCompletionTurnId;
+            const threadId = this.currentThreadIdValue;
+            if (text && turnId && threadId) {
+                this.pendingPlanImplementation = { threadId, turnId, text };
+            }
+        }
         const mapped = mapCodexItem("item/completed", item);
         const canonicalEvents = mapped.events.filter((event) => event.type !== "runtime_debug");
         if (canonicalEvents.length === 0)
             return;
+        if (outsideTurnLifecycle && this.sink.onTurnContentEvent) {
+            for (const event of canonicalEvents) {
+                this.sink.onTurnContentEvent(completedTurnId, event);
+            }
+            return;
+        }
         this.ensureTurn();
         for (const event of canonicalEvents)
             this.sink.onEvent(event);
@@ -518,11 +670,11 @@ export class CodexSessionForwarder {
         }
         return Boolean(item.text?.trim());
     }
-    deferAssistantMessage(item) {
-        if (!this.claimCompletedItem(item))
+    deferAssistantMessage(item, turnId) {
+        if (!this.claimCompletedItem(item, turnId))
             return;
         this.flushDeferredAssistantMessage();
-        this.deferredAssistantMessage = item;
+        this.deferredAssistantMessage = { item, ...(turnId ? { turnId } : {}) };
         const graceMs = this.options.assistantMessageGraceMs ?? 0;
         this.assistantMessageTimer = setTimeout(() => this.flushDeferredAssistantMessage(), graceMs);
         this.assistantMessageTimer.unref?.();
@@ -531,26 +683,26 @@ export class CodexSessionForwarder {
         if (this.assistantMessageTimer)
             clearTimeout(this.assistantMessageTimer);
         this.assistantMessageTimer = null;
-        const item = this.deferredAssistantMessage;
+        const deferred = this.deferredAssistantMessage;
         this.deferredAssistantMessage = null;
-        if (item)
-            this.emitCompletedItem(item);
+        if (deferred)
+            this.emitCompletedItem(deferred.item, deferred.turnId);
     }
     /** Build a total dedup key for one completed item. Stable-id items use
      *  `threadId:turnId:item.id` — identical across replay + live, so the second
      *  delivery is dropped. Items without a codex id fall back to a per-(thread,turn)
      *  position counter (peeked here; advanced only on a successful claim, via
      *  {@link advanceAnonCounter}). Mirrors reference implementation `_completed_item_key`. */
-    completedItemKey(item) {
+    completedItemKey(item, completedTurnId) {
         const threadId = this.currentThreadIdValue ?? "thread";
-        const turnId = this.currentTurnIdValue ?? this.pendingCompletionTurnId ?? "turn";
+        const turnId = completedTurnId ?? this.currentTurnIdValue ?? this.pendingCompletionTurnId ?? "turn";
         if (item.id)
             return { key: `${threadId}:${turnId}:${item.id}`, isAnon: false };
         const n = this.anonCounters.get(`${threadId}:${turnId}`) ?? 0;
         return { key: `${threadId}:${turnId}:anon:${n}`, isAnon: true };
     }
-    advanceAnonCounter() {
-        const turnId = this.currentTurnIdValue ?? this.pendingCompletionTurnId ?? "turn";
+    advanceAnonCounter(completedTurnId) {
+        const turnId = completedTurnId ?? this.currentTurnIdValue ?? this.pendingCompletionTurnId ?? "turn";
         const k = `${this.currentThreadIdValue ?? "thread"}:${turnId}`;
         this.anonCounters.set(k, (this.anonCounters.get(k) ?? 0) + 1);
     }
@@ -560,6 +712,15 @@ export class CodexSessionForwarder {
             this.sink.onTurnStart(this.currentTurnIdValue ?? undefined);
         }
     }
+    consumeTurnDiff(turnId) {
+        if (!turnId)
+            return undefined;
+        const diff = this.turnDiffByTurn.get(turnId);
+        this.turnDiffByTurn.delete(turnId);
+        return diff
+            ? { type: "turn_diff", callId: `codex_turn_diff_${turnId}`, diff }
+            : undefined;
+    }
     /** 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

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

@@ -1,9 +1,3 @@
-/**
- * Pure codex app-server notification → {@link AgentEvent} mapping. Extracted from
- * the executor so BOTH the per-turn executor and the persistent session
- * forwarder (which mirrors every thread turn — web- AND TUI-initiated — into the
- * canonical log, reference implementation's codex-native model) share one mapping.
- */
 import type { AgentEvent } from "@rynx-ai/core";
 import type { ThreadItem } from "./protocol.js";
 export interface CodexMapResult {

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

@@ -1,3 +1,10 @@
+/**
+ * Pure codex app-server notification → {@link AgentEvent} mapping. Extracted from
+ * the executor so BOTH the per-turn executor and the persistent session
+ * forwarder (which mirrors every thread turn — web- AND TUI-initiated — into the
+ * canonical log, reference implementation's codex-native model) share one mapping.
+ */
+import { extname, isAbsolute } from "node:path";
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -115,6 +122,23 @@ function webSearchInput(item) {
     }
     return { id: item.id, query: item.query };
 }
+function fileChangeSummary(changes) {
+    const lines = [];
+    for (const change of changes) {
+        if (!isRecord(change))
+            continue;
+        const kind = isRecord(change.kind) && typeof change.kind.type === "string" && change.kind.type
+            ? change.kind.type
+            : "change";
+        lines.push(`${kind} ${String(change.path)}`);
+    }
+    return lines.join("\n");
+}
+function isSupportedAbsoluteImagePath(path) {
+    if (!isAbsolute(path))
+        return false;
+    return [".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg"].includes(extname(path).toLowerCase());
+}
 /** Map one thread item (`item/started` | `item/completed`) to events. */
 export function mapCodexItem(method, item) {
     const events = [];
@@ -144,16 +168,18 @@ export function mapCodexItem(method, item) {
             return { events };
         }
         case "fileChange": {
+            const fileChange = item;
+            const changes = Array.isArray(fileChange.changes) ? fileChange.changes : [];
             events.push({
                 type: "tool",
                 event: isStart ? "on_tool_start" : "on_tool_end",
-                name: "file_change",
-                input: isStart ? { id: item.id } : undefined,
+                name: "apply_patch",
+                input: isStart || isEnd ? { id: item.id, ...(changes.length ? { changes } : {}) } : undefined,
                 output: isEnd
                     ? {
                         id: item.id,
-                        changes: item.changes,
-                        status: item.status,
+                        status: fileChange.status,
+                        aggregatedOutput: fileChangeSummary(changes),
                     }
                     : undefined,
                 data: { method, item },
@@ -199,6 +225,30 @@ export function mapCodexItem(method, item) {
             });
             return { events };
         }
+        case "imageGeneration": {
+            const image = item;
+            events.push({
+                type: "tool",
+                event: isStart ? "on_tool_start" : "on_tool_end",
+                name: "image_generation",
+                input: isStart ? { id: image.id } : undefined,
+                output: isEnd
+                    ? {
+                        id: image.id,
+                        status: image.status,
+                        generatedImage: {
+                            ...(!image.savedPath || !isSupportedAbsoluteImagePath(image.savedPath)
+                                ? { result: image.result }
+                                : {}),
+                            revisedPrompt: image.revisedPrompt,
+                            ...(image.savedPath ? { savedPath: image.savedPath } : {}),
+                        },
+                    }
+                    : undefined,
+                data: { method, item: { ...image, result: image.result ? "[image data omitted]" : "" } },
+            });
+            return { events };
+        }
         case "agentMessage": {
             const text = item.text?.trim() ?? "";
             if (isEnd && text) {
@@ -208,7 +258,11 @@ export function mapCodexItem(method, item) {
             return { events };
         }
         case "plan": {
-            events.push({ type: "runtime_debug", channel: "codexEvent", data: { method, item } });
+            const text = item.text?.trim() ?? "";
+            if (isEnd && text) {
+                events.push({ type: "message_completed", itemId: item.id, text });
+                return { events, finalText: text };
+            }
             return { events };
         }
         case "reasoning": {
@@ -276,6 +330,17 @@ export function mapCodexNotification(method, params) {
             }
             return { events };
         }
+        case "item/plan/delta": {
+            const delta = typed.params.delta ?? "";
+            if (delta) {
+                events.push({
+                    type: "token",
+                    text: delta,
+                    metadata: { source: "app_server", itemId: typed.params.itemId },
+                });
+            }
+            return { events };
+        }
         case "item/reasoning/summaryTextDelta":
         case "item/reasoning/textDelta": {
             const p = typed.params;

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

@@ -87,6 +87,16 @@ export interface PermissionProfileModificationParams {
 export type PermissionSelection = string | PermissionProfileSelectionParams;
 /** Open since Codex App Server 0.144; values are advertised by `model/list`. */
 export type ReasoningEffort = string;
+export type CollaborationModeKind = "plan" | "default";
+/** Full Codex-lineage mode snapshot required by the App Server wire protocol. */
+export interface CollaborationMode {
+    mode: CollaborationModeKind;
+    settings: {
+        model: string;
+        reasoning_effort: ReasoningEffort | null;
+        developer_instructions: string | null;
+    };
+}
 export interface ThreadStartParams {
     model?: string | null;
     modelProvider?: string | null;
@@ -102,6 +112,8 @@ export interface ThreadStartParams {
     baseInstructions?: string | null;
     developerInstructions?: string | null;
     ephemeral?: boolean | null;
+    /** Native UI intent for a context-clearing fresh thread. */
+    sessionStartSource?: "clear" | string;
 }
 export interface ThreadResumeParams extends ThreadStartParams {
     threadId: string;
@@ -157,6 +169,7 @@ export interface TurnStartParams {
     permissions?: PermissionSelection | null;
     model?: string | null;
     effort?: ReasoningEffort | null;
+    collaborationMode?: CollaborationMode | null;
 }
 export interface TurnInterruptParams {
     threadId: string;
@@ -254,7 +267,16 @@ export interface WebSearchItem extends ThreadItemBase {
         type: "other";
     } | null;
 }
-export type ThreadItem = UserMessageItem | AgentMessageItem | ReasoningItem | PlanItem | CommandExecutionItem | FileChangeItem | McpToolCallItem | DynamicToolCallItem | WebSearchItem | (ThreadItemBase & Record<string, unknown>);
+export interface ImageGenerationItem extends ThreadItemBase {
+    type: "imageGeneration";
+    status: string;
+    revisedPrompt: string | null;
+    /** Base64 image bytes supplied when no durable saved path is available. */
+    result: string;
+    /** Codex App Server guarantees this is absolute when present. */
+    savedPath?: string;
+}
+export type ThreadItem = UserMessageItem | AgentMessageItem | ReasoningItem | PlanItem | CommandExecutionItem | FileChangeItem | McpToolCallItem | DynamicToolCallItem | WebSearchItem | ImageGenerationItem | (ThreadItemBase & Record<string, unknown>);
 export interface ThreadSummary {
     id?: string;
     threadId?: string;
@@ -304,7 +326,7 @@ export interface ThreadSettingsUpdateParams {
     serviceTier?: string | null;
     effort?: ReasoningEffort | null;
     summary?: string | null;
-    collaborationMode?: Record<string, unknown> | null;
+    collaborationMode?: CollaborationMode | null;
     personality?: string | null;
 }
 export interface ModelListParams {
@@ -478,6 +500,14 @@ export interface QueueStatusNotificationParams {
 export type ServerNotification = {
     method: "thread/started";
     params: ThreadStartedNotificationParams;
+} | {
+    method: "thread/settings/updated";
+    params: {
+        threadId: string;
+        threadSettings: {
+            collaborationMode?: CollaborationMode | null;
+        } & Record<string, unknown>;
+    };
 } | {
     method: "turn/started";
     params: TurnStartedNotificationParams;
@@ -499,6 +529,9 @@ export type ServerNotification = {
 } | {
     method: "item/agentMessage/delta";
     params: AgentMessageDeltaNotificationParams;
+} | {
+    method: "item/plan/delta";
+    params: AgentMessageDeltaNotificationParams;
 } | {
     method: "item/reasoning/summaryTextDelta";
     params: ReasoningSummaryTextDeltaNotificationParams;