@jskit-ai/assistant-core 0.2.7 → 0.2.9

package/src/server/conversation/codexOutput.js

@@ -1,31 +1,32 @@
 import { createCodexAppServerReasoning } from "./codexReasoning.js";
+import { createCodexAppServerLiveItems, codexAppServerLiveProgressCandidate } from "./codexLiveItems.js";
+import { codexAppServerProcessedResultEvent, codexAppServerTurnCanReceiveProviderCompletion, codexAppServerTurnAwaitsProviderIdentity, codexAppServerTurnCanReceiveProviderActivity, codexAppServerTurnKey, CODEX_APP_SERVER_AGENT_RUN_ID, codexAppServerRunInputSource, codexAppServerConversationMessageId } from "./codexTurnState.js";
+import { isRecord, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import {
-  normalizeCodexRunText,
-  codexAppServerProcessedResultEvent,
-  codexAppServerTurnCanReceiveProviderCompletion,
-  codexAppServerTurnAwaitsProviderIdentity,
-  codexAppServerTurnCanReceiveProviderActivity,
-  codexAppServerTurnKey,
-  CODEX_APP_SERVER_AGENT_RUN_ID,
-  codexAppServerRunInputSource
-} from "./codexTurnState.js";
-import crypto from "node:crypto";
-import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
-import {
-  codexAppServerAgentMessageText,
   codexAppServerAssistantItemText,
-  classifyCodexAppServerEvent,
-  codexAppServerNotificationEvent,
-  codexAppServerNotificationEventType,
-  codexAppServerNotificationEventPayload,
-  codexAppServerNotificationItem,
   codexAppServerNotificationItemId,
-  codexAppServerNotificationTurnId,
-  codexAppServerProviderThreadAssistantSegments
+  codexAppServerNotificationTurnId
 } from "./codexEvents.js";
+import { codexAppServerProviderThreadAssistantSegments } from "./codexThreadSnapshot.js";
 
-// Native output, reasoning persistence and exact-result identity.
-// One instance belongs to each retained run owner; its state is shared by reference.
+/**
+ * Native output, reasoning persistence and exact-result identity. One instance belongs to each retained run owner;
+ * its state is shared by reference.
+ * @param {object} dependencies
+ * @param {import("./codexTurn.js").CodexSessionNamespace} dependencies.namespace
+ * @param {import("./codexTurn.js").CodexCreateRuntime} dependencies.createRuntime
+ * @param {import("./codexTurn.js").CodexCreateStore} dependencies.createStore
+ * @param {import("./codexTurn.js").CodexPublish} dependencies.publish
+ * @param {(input: { sessionId: string, runtime: any, session: object }) => Promise<any>} dependencies.acquireProvider
+ * @param {import("./codexTurn.js").CodexTurnStateReader} dependencies.turnState
+ * @param {import("./codexTurn.js").CodexAgentRunTurnStateReader} dependencies.turnStateFromAgentRun
+ * @param {import("./codexTurn.js").CodexDebugLog} dependencies.debugLog
+ * @param {import("./codexTurn.js").CodexDebugError} dependencies.debugError
+ * @param {number} dependencies.liveProgressMaxLength
+ * @param {boolean} [dependencies.persistCommentary]
+ * @param {import("./codexTurn.js").CodexMessageMetadataHooks} dependencies.messageMetadata
+ * @param {number} dependencies.snapshotRecoveryItemLimit
+ */
 export function createCodexAppServerOutput({
   namespace,
   createRuntime,
@@ -38,7 +39,6 @@ export function createCodexAppServerOutput({
   debugError,
   liveProgressMaxLength,
   persistCommentary = true,
-  storeReadError,
   messageMetadata,
   snapshotRecoveryItemLimit
 }) {
@@ -59,9 +59,24 @@ export function createCodexAppServerOutput({
     debugLog,
     readCodexAppServerAgentRunForSession
   });
-  const codexAppServerLiveProgressItems = new Set();
-  const codexAppServerLiveProgressFingerprints = new Set();
-  const codexAppServerMirroredTerminalItems = new Set();
+  const {
+    liveProgressItems: codexAppServerLiveProgressItems,
+    liveProgressFingerprints: codexAppServerLiveProgressFingerprints,
+    mirroredTerminalItems: codexAppServerMirroredTerminalItems,
+    writeLiveProgress: writeCodexAppServerLiveProgress,
+    writeMirroredTerminalMessage: writeMirroredCodexAppServerTerminalMessage,
+    mirrorTerminalAssistantMessage: mirrorCodexAppServerTerminalAssistantMessage,
+    forgetTurnItems: forgetCodexAppServerLiveTurnItems
+  } = createCodexAppServerLiveItems({
+    createStore,
+    publish,
+    turnStateFromAgentRun,
+    debugLog,
+    readCodexAppServerAgentRunForSession,
+    messageMetadata,
+    persistCommentary,
+    liveProgressMaxLength
+  });
 
   function codexAppServerResultFinalizationKey(sessionId = "", threadId = "", turnId = "") {
     return [
@@ -70,262 +85,21 @@ export function createCodexAppServerOutput({
     ].filter(Boolean).join(":");
   }
 
-  function codexAppServerLiveProgressCandidate(notification = {}) {
-    const method = normalizeCodexRunText(notification.method);
-    const event = codexAppServerNotificationEvent(notification);
-    if (isRecord(event)) {
-      const eventType = codexAppServerNotificationEventType(notification, event);
-      const payload = codexAppServerNotificationEventPayload(notification, event);
-      const payloadType = normalizeCodexRunText(payload.type);
-      const phase = normalizeCodexRunText(payload.phase || event.phase);
-      if (eventType === "event_msg" && payloadType === "agent_message" && phase && phase !== "final_answer") {
-        return {
-          explicit: Boolean(phase),
-          phase,
-          source: "event",
-          text: codexAppServerAgentMessageText(payload)
-        };
-      }
-    }
-
-    if (method !== "item/completed") {
-      return null;
-    }
-    const item = codexAppServerNotificationItem(notification);
-    const text = codexAppServerAssistantItemText(item);
-    if (!text) {
-      return null;
-    }
-    const phase = normalizeCodexRunText(item?.phase || item?.purpose || item?.category);
-    if (phase === "final_answer") {
-      return null;
-    }
-    return {
-      explicit: ["commentary", "progress", "status", "thinking"].includes(phase),
-      phase,
-      source: "item",
-      text
-    };
-  }
-
-  function codexAppServerLiveProgressText(notification = {}) {
-    const candidate = codexAppServerLiveProgressCandidate(notification);
-    const text = normalizeCodexRunText(candidate?.text);
-    if (!text) {
-      return "";
-    }
-    if (candidate?.phase === "commentary") {
-      return text;
-    }
-    if (text.length > liveProgressMaxLength) {
-      return "";
-    }
-    if (text.includes("\n") || text.includes("\r") || text.includes("```")) {
-      return "";
-    }
-    return text;
-  }
-
-  function codexAppServerLiveProgressKey(sessionId = "", threadId = "", notification = {}) {
-    const itemId = codexAppServerNotificationItemId(notification);
-    if (!itemId) {
-      return "";
-    }
-    return [
-      normalizeCodexRunText(sessionId),
-      normalizeCodexRunText(threadId),
-      codexAppServerNotificationTurnId(notification) || "*",
-      "live-progress",
-      itemId
-    ].join(":");
-  }
-
-  function codexAppServerLiveProgressFingerprintKey(
-    sessionId = "",
-    threadId = "",
-    turnId = "",
-    text = ""
-  ) {
-    const normalizedText = normalizeCodexRunText(text);
-    if (!normalizedText) {
-      return "";
-    }
-    return [
-      normalizeCodexRunText(sessionId),
-      normalizeCodexRunText(threadId),
-      normalizeCodexRunText(turnId) || "*",
-      "live-progress-text",
-      crypto.createHash("sha256").update(normalizedText).digest("hex")
-    ].join(":");
-  }
-
-  function codexAppServerConversationMessageId(
-    threadId = "",
-    turnId = "",
-    role = "",
-    text = ""
-  ) {
-    const normalizedText = normalizeCodexRunText(text);
-    const normalizedThreadId = normalizeCodexRunText(threadId);
-    if (!normalizedText || !normalizedThreadId) {
-      return "";
-    }
-    const digest = crypto.createHash("sha256")
-      .update([
-        normalizedThreadId,
-        normalizeCodexRunText(turnId) || "*",
-        normalizeCodexRunText(role),
-        normalizedText
-      ].join("\u0000"))
-      .digest("hex");
-    return `codex-${digest}`;
-  }
-
   async function readCodexAppServerAgentRunForSession(store, sessionId = "") {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
+    const normalizedSessionId = normalizeText(sessionId);
     if (!normalizedSessionId) {
       return null;
     }
-    if (typeof store?.readAgentRun !== "function") {
-      throw new Error(storeReadError);
-    }
     return store.readAgentRun(
       normalizedSessionId,
       CODEX_APP_SERVER_AGENT_RUN_ID
     );
   }
 
-  function codexAppServerTerminalItemMirrorKey(sessionId = "", threadId = "", notification = {}, role = "") {
-    const itemId = codexAppServerNotificationItemId(notification);
-    if (!itemId) {
-      return "";
-    }
-    return [
-      normalizeCodexRunText(sessionId),
-      normalizeCodexRunText(threadId),
-      codexAppServerNotificationTurnId(notification) || "*",
-      normalizeCodexRunText(role),
-      itemId
-    ].join(":");
-  }
-
-  async function writeMirroredCodexAppServerTerminalMessage({
-    notification = {},
-    role = "",
-    sessionId = "",
-    text = "",
-    threadId = ""
-  } = {}) {
-    const normalizedRole = normalizeCodexRunText(role);
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedText = normalizeCodexRunText(text);
-    if (!normalizedSessionId || !normalizedText || !["assistant", "user"].includes(normalizedRole)) {
-      return null;
-    }
-    const key = codexAppServerTerminalItemMirrorKey(
-      normalizedSessionId,
-      threadId,
-      notification,
-      normalizedRole
-    );
-    if (!key) {
-      return null;
-    }
-    if (codexAppServerMirroredTerminalItems.has(key)) {
-      return null;
-    }
-    codexAppServerMirroredTerminalItems.add(key);
-    let written = null;
-    try {
-      const store = await createStore(sessionId);
-      const writer = normalizedRole === "user"
-        ? store?.writeConversationUserMessage
-        : store?.writeConversationAssistantMessage;
-      if (typeof writer !== "function") {
-        codexAppServerMirroredTerminalItems.delete(key);
-        return null;
-      }
-      let turnMetadata = null;
-      if (normalizedRole === "user" && typeof store.readConversationLog === "function") {
-        turnMetadata = await messageMetadata.terminal?.(store, normalizedSessionId) ?? null;
-      }
-      written = await writer.call(store, normalizedSessionId, {
-        messageId: codexAppServerConversationMessageId(
-          threadId,
-          codexAppServerNotificationTurnId(notification),
-          normalizedRole,
-          normalizedText
-        ),
-        text: normalizedText,
-        nativeIdentity: { threadId, turnId: codexAppServerNotificationTurnId(notification) },
-        ...(turnMetadata ? { turnMetadata } : {})
-      });
-      if (!written) {
-        codexAppServerMirroredTerminalItems.delete(key);
-        return null;
-      }
-      const reason = normalizedRole === "user"
-        ? "codex-app-server-terminal-user-message"
-        : "codex-app-server-terminal-assistant-message";
-      await publish(normalizedSessionId, {
-        payload: {
-          conversationLogPatch: {
-            turn: written,
-            type: "upsert-turn"
-          }
-        },
-        reason
-      });
-      debugLog(`appServerTerminal${normalizedRole === "user" ? "User" : "Assistant"}Message.mirrored`, {
-        itemId: normalizeCodexRunText(codexAppServerNotificationItem(notification)?.id),
-        sessionId: normalizedSessionId,
-        threadId: normalizeCodexRunText(threadId),
-        turnId: codexAppServerNotificationTurnId(notification)
-      });
-      return written;
-    } catch (error) {
-      if (!written) {
-        codexAppServerMirroredTerminalItems.delete(key);
-      }
-      throw error;
-    }
-  }
-
-  async function mirrorCodexAppServerTerminalAssistantMessage(sessionId = "", threadId = "", notification = {}) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedThreadId = normalizeCodexRunText(threadId);
-    if (codexAppServerLiveProgressCandidate(notification)?.explicit === true) {
-      return;
-    }
-    const classification = classifyCodexAppServerEvent(notification);
-    // Completed finals use the same native-item publication owner as UI chat.
-    if (classification.kind === "final_assistant_result") {
-      return;
-    }
-    const text = normalizeCodexRunText(
-      codexAppServerAssistantItemText(codexAppServerNotificationItem(notification))
-    );
-    if (!normalizedSessionId || !text) {
-      return;
-    }
-    const store = await createStore(normalizedSessionId);
-    const run = await readCodexAppServerAgentRunForSession(store, normalizedSessionId);
-    if (normalizeCodexRunText(run?.inputSource) !== "terminal") {
-      return;
-    }
-    await writeMirroredCodexAppServerTerminalMessage({
-      notification,
-      role: "assistant",
-      sessionId: normalizedSessionId,
-      text,
-      threadId: normalizedThreadId
-    });
-  }
-
   function readCodexAppServerFinalAssistantResult(sessionId = "", threadId = "", turnId = "") {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedThreadId = normalizeCodexRunText(threadId);
-    const normalizedTurnId = normalizeCodexRunText(turnId);
+    const normalizedSessionId = normalizeText(sessionId);
+    const normalizedThreadId = normalizeText(threadId);
+    const normalizedTurnId = normalizeText(turnId);
     if (!normalizedSessionId || !normalizedThreadId || !normalizedTurnId) {
       return null;
     }
@@ -338,7 +112,7 @@ export function createCodexAppServerOutput({
     if (record.conversationTurn && !streamItemId) {
       return record.conversationTurn;
     }
-    const conversationText = normalizeCodexRunText(record.text);
+    const conversationText = normalizeText(record.text);
     if (!conversationText) {
       return null;
     }
@@ -385,11 +159,11 @@ export function createCodexAppServerOutput({
     });
     record.conversationTurn = written;
     debugLog("appServerAssistantResponseBundle.persisted", {
-      conversationTurnId: normalizeCodexRunText(written.turnId),
-      sessionId: normalizeCodexRunText(sessionId),
+      conversationTurnId: normalizeText(written.turnId),
+      sessionId: normalizeText(sessionId),
       textLength: conversationText.length,
-      threadId: normalizeCodexRunText(record.threadId),
-      turnId: normalizeCodexRunText(record.turnId)
+      threadId: normalizeText(record.threadId),
+      turnId: normalizeText(record.turnId)
     });
     return written;
   }
@@ -405,10 +179,10 @@ export function createCodexAppServerOutput({
     threadId = "",
     turnId = ""
   } = {}) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedThreadId = normalizeCodexRunText(threadId);
-    const assistantText = normalizeCodexRunText(text);
-    const normalizedItemId = normalizeCodexRunText(itemId) || codexAppServerNotificationItemId(notification);
+    const normalizedSessionId = normalizeText(sessionId);
+    const normalizedThreadId = normalizeText(threadId);
+    const assistantText = normalizeText(text);
+    const normalizedItemId = normalizeText(itemId) || codexAppServerNotificationItemId(notification);
     if (!normalizedSessionId || !normalizedThreadId || !assistantText || !normalizedItemId) {
       return {
         recorded: false,
@@ -419,8 +193,8 @@ export function createCodexAppServerOutput({
     const runtime = await createRuntime();
     const session = await runtime.getSession(normalizedSessionId);
     const currentTurn = turnState(session);
-    const currentTurnId = normalizeCodexRunText(currentTurn.turnId);
-    const normalizedTurnId = normalizeCodexRunText(turnId) || codexAppServerNotificationTurnId(notification);
+    const currentTurnId = normalizeText(currentTurn.turnId);
+    const normalizedTurnId = normalizeText(turnId) || codexAppServerNotificationTurnId(notification);
     if (!normalizedTurnId) {
       return { recorded: false, reason: "missing_turn_id" };
     }
@@ -454,7 +228,7 @@ export function createCodexAppServerOutput({
           currentThreadId: currentTurn.threadId,
           currentTurnId: currentTurn.turnId,
           sessionId: normalizedSessionId,
-          source: normalizeCodexRunText(source),
+          source: normalizeText(source),
           threadId: normalizedThreadId,
           turnId: normalizedTurnId
         });
@@ -497,7 +271,7 @@ export function createCodexAppServerOutput({
     }
     const record = {
       itemId: normalizedItemId,
-      source: normalizeCodexRunText(source),
+      source: normalizeText(source),
       text: assistantText,
       threadId: normalizedThreadId,
       turnId: normalizedTurnId
@@ -530,26 +304,7 @@ export function createCodexAppServerOutput({
 
   function cleanupCodexAppServerUntrackedTurn(threadId = "", turnId = "") {
     cleanupCodexAppServerReasoningTurn(threadId, turnId);
-    const normalizedThreadId = normalizeCodexRunText(threadId);
-    const normalizedTurnId = normalizeCodexRunText(turnId);
-    if (!normalizedThreadId) {
-      return;
-    }
-    const markers = [
-      `:${normalizedThreadId}:*:`,
-      ...(normalizedTurnId ? [`:${normalizedThreadId}:${normalizedTurnId}:`] : [])
-    ];
-    for (const set of [
-      codexAppServerLiveProgressItems,
-      codexAppServerLiveProgressFingerprints,
-      codexAppServerMirroredTerminalItems
-    ]) {
-      for (const key of set) {
-        if (markers.some((marker) => key.includes(marker))) {
-          set.delete(key);
-        }
-      }
-    }
+    forgetCodexAppServerLiveTurnItems(threadId, turnId);
   }
 
   function codexAppServerStreamMessage(classification) {
@@ -583,102 +338,10 @@ export function createCodexAppServerOutput({
     }
   }
 
-  async function writeCodexAppServerLiveProgress(sessionId = "", threadId = "", notification = {}) {
-    // Phase-less providers also send short updates as agent messages.
-    // Reasoning items are recorded separately from these user-facing updates.
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedThreadId = normalizeCodexRunText(threadId);
-    const candidate = codexAppServerLiveProgressCandidate(notification);
-    const text = codexAppServerLiveProgressText(notification);
-    if (!normalizedSessionId || !normalizedThreadId || !text) {
-      return null;
-    }
-    const store = await createStore(normalizedSessionId);
-    const run = await readCodexAppServerAgentRunForSession(store, normalizedSessionId);
-    const turn = turnStateFromAgentRun(run || {});
-    const notificationTurnId = codexAppServerNotificationTurnId(notification);
-    const ownerTurnId = notificationTurnId || turn.turnId;
-    if (!codexAppServerTurnCanReceiveProviderActivity(turn, normalizedThreadId, notificationTurnId)) {
-      return null;
-    }
-    const key = codexAppServerLiveProgressKey(normalizedSessionId, normalizedThreadId, notification);
-    if (!key) {
-      return null;
-    }
-    const fingerprintKey = codexAppServerLiveProgressFingerprintKey(
-      normalizedSessionId,
-      normalizedThreadId,
-      ownerTurnId,
-      text
-    );
-    const streamMessageId = codexAppServerConversationMessageId(
-      normalizedThreadId, notificationTurnId,
-      "assistant-item", codexAppServerNotificationItemId(notification)
-    );
-    if (
-      codexAppServerLiveProgressItems.has(key) ||
-      codexAppServerLiveProgressFingerprints.has(fingerprintKey)
-    ) {
-      await publish(normalizedSessionId, {
-        payload: { conversationStream: store.completeConversationStreamMessage(normalizedSessionId, streamMessageId) },
-        reason: "assistant-stream"
-      });
-      return null;
-    }
-    codexAppServerLiveProgressItems.add(key);
-    codexAppServerLiveProgressFingerprints.add(fingerprintKey);
-    let written = null;
-    try {
-      const role = !candidate.phase || candidate.phase === "commentary" ? "commentary" : "thinking";
-      const writer = role === "commentary"
-        ? store.writeConversationCommentaryMessage
-        : store.writeConversationThinkingMessage;
-      if (role !== "commentary" || persistCommentary) {
-        written = await writer.call(store, normalizedSessionId, {
-          ...(streamMessageId ? { outputId: streamMessageId } : {}),
-          messageId: codexAppServerConversationMessageId(
-            normalizedThreadId,
-            ownerTurnId,
-            role,
-            text
-          ),
-          requireOpenTurn: false,
-          nativeIdentity: { threadId: normalizedThreadId, turnId: ownerTurnId },
-          text
-        });
-        if (!written) {
-          codexAppServerLiveProgressItems.delete(key);
-          codexAppServerLiveProgressFingerprints.delete(fingerprintKey);
-        }
-      }
-      const payload = {
-        conversationStream: await store.completeConversationStreamMessage(normalizedSessionId, streamMessageId, {
-          text, role, nativeIdentity: { threadId: normalizedThreadId, turnId: ownerTurnId }
-        })
-      };
-      if (written) {
-        payload.conversationLogPatch = { turn: written, type: "upsert-turn" };
-      }
-      await publish(normalizedSessionId, {
-        payload,
-        reason: role === "commentary"
-          ? "codex-app-server-commentary"
-          : "codex-app-server-live-progress"
-      });
-      return written;
-    } catch (error) {
-      if (!written) {
-        codexAppServerLiveProgressItems.delete(key);
-        codexAppServerLiveProgressFingerprints.delete(fingerprintKey);
-      }
-      throw error;
-    }
-  }
-
   async function recoverCodexAppServerAssistantSegmentsFromProvider(sessionId = "", threadId = "", turnId = "") {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedThreadId = normalizeCodexRunText(threadId);
-    const normalizedTurnId = normalizeCodexRunText(turnId);
+    const normalizedSessionId = normalizeText(sessionId);
+    const normalizedThreadId = normalizeText(threadId);
+    const normalizedTurnId = normalizeText(turnId);
     if (!normalizedSessionId || !normalizedThreadId || !normalizedTurnId) {
       return [];
     }
@@ -717,9 +380,9 @@ export function createCodexAppServerOutput({
   async function submitCodexAppServerAssistantResult(sessionId = "", threadId = "", turnId = "", {
     recoverFromProvider = false
   } = {}) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
+    const normalizedSessionId = normalizeText(sessionId);
     let finalResult = readCodexAppServerFinalAssistantResult(normalizedSessionId, threadId, turnId);
-    let assistantText = normalizeCodexRunText(finalResult?.text);
+    let assistantText = normalizeText(finalResult?.text);
     const reasoningText = readCodexAppServerReasoningText(threadId, turnId);
     try {
       if (normalizedSessionId && recoverFromProvider) {
@@ -740,7 +403,7 @@ export function createCodexAppServerOutput({
         }
         if (recoveredSegments.length) {
           finalResult = readCodexAppServerFinalAssistantResult(normalizedSessionId, threadId, turnId);
-          assistantText = normalizeCodexRunText(finalResult?.text);
+          assistantText = normalizeText(finalResult?.text);
         }
       }
       if (!normalizedSessionId || !assistantText && !reasoningText) {
@@ -771,11 +434,11 @@ export function createCodexAppServerOutput({
       debugLog("appServerAgentResult.error", {
         error: debugError(error),
         sessionId: normalizedSessionId,
-        threadId: normalizeCodexRunText(threadId),
-        turnId: normalizeCodexRunText(turnId)
+        threadId: normalizeText(threadId),
+        turnId: normalizeText(turnId)
       });
       return {
-        error: normalizeCodexRunText(error?.error || error?.message || error) || "Codex app-server response could not be processed.",
+        error: normalizeText(error?.error || error?.message || error) || "Codex app-server response could not be processed.",
         ok: false,
         processed: false,
         reason: "error"
@@ -785,7 +448,7 @@ export function createCodexAppServerOutput({
     }
   }
 
-  function codexAppServerSnapshotCursor(run = {}) {
+  function codexAppServerSnapshotCursor(run) {
     const cursor = run?.providerSnapshotCursor;
     if (!isRecord(cursor)) {
       return {
@@ -794,8 +457,8 @@ export function createCodexAppServerOutput({
       };
     }
     return {
-      itemId: normalizeCodexRunText(cursor.itemId),
-      turnId: normalizeCodexRunText(cursor.turnId)
+      itemId: normalizeText(cursor.itemId),
+      turnId: normalizeText(cursor.turnId)
     };
   }
 
@@ -803,9 +466,9 @@ export function createCodexAppServerOutput({
     itemId = "",
     turnId = ""
   } = {}) {
-    const normalizedItemId = normalizeCodexRunText(itemId);
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedTurnId = normalizeCodexRunText(turnId);
+    const normalizedItemId = normalizeText(itemId);
+    const normalizedSessionId = normalizeText(sessionId);
+    const normalizedTurnId = normalizeText(turnId);
     if (!normalizedItemId || !normalizedSessionId || !normalizedTurnId) {
       return;
     }
@@ -836,11 +499,11 @@ export function createCodexAppServerOutput({
     observedTurn = null,
     provider = null
   ) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedThreadId = normalizeCodexRunText(threadId);
-    const normalizedTurnId = normalizeCodexRunText(observedTurn?.id);
+    const normalizedSessionId = normalizeText(sessionId);
+    const normalizedThreadId = normalizeText(threadId);
+    const normalizedTurnId = normalizeText(observedTurn?.id);
     const items = (Array.isArray(observedTurn?.items) ? observedTurn.items : [])
-      .filter((item) => isRecord(item) && normalizeCodexRunText(item.id));
+      .filter((item) => isRecord(item) && normalizeText(item.id));
     if (!normalizedSessionId || !normalizedThreadId || !normalizedTurnId || !items.length) {
       return;
     }
@@ -861,7 +524,7 @@ export function createCodexAppServerOutput({
       }
       const cursor = codexAppServerSnapshotCursor(run);
       const cursorIndex = cursor.turnId === normalizedTurnId
-        ? items.findIndex((item) => normalizeCodexRunText(item.id) === cursor.itemId)
+        ? items.findIndex((item) => normalizeText(item.id) === cursor.itemId)
         : -1;
       const unseenItems = cursorIndex >= 0
         ? items.slice(cursorIndex + 1)
@@ -890,7 +553,7 @@ export function createCodexAppServerOutput({
         );
       }
       await recordCodexAppServerSnapshotCursor(store, normalizedSessionId, {
-        itemId: normalizeCodexRunText(items.at(-1)?.id),
+        itemId: normalizeText(items.at(-1)?.id),
         turnId: normalizedTurnId
       });
     } catch (error) {
@@ -899,7 +562,7 @@ export function createCodexAppServerOutput({
     }
   }
 
-  return {
+  return Object.freeze({
     finalizedTurns: codexAppServerFinalizedTurns,
     finalAssistantResults: codexAppServerFinalAssistantResults,
     reasoningTurns: codexAppServerReasoningTurns,
@@ -925,5 +588,7 @@ export function createCodexAppServerOutput({
     writeMirroredTerminalMessage: writeMirroredCodexAppServerTerminalMessage,
     mirrorTerminalAssistantMessage: mirrorCodexAppServerTerminalAssistantMessage,
     reconcileObservedTurnItems: reconcileCodexAppServerObservedTurnItems
-  };
+  });
 }
+
+/** @typedef {ReturnType<typeof createCodexAppServerOutput>} CodexAppServerOutput */