@jskit-ai/assistant-core 0.2.7 → 0.2.9

package/src/server/conversation/codexRunJournal.js

@@ -1,28 +1,46 @@
-import {
-  normalizeCodexRunText,
-  codexAppServerRunStateIsActive,
-  codexAppServerAgentRun,
-  codexAppServerPendingUserMessageClientIds,
-  codexAppServerProcessedResultEvent,
-  codexAppServerTurnCanReceiveProviderActivity,
-  codexAppServerTurnKey,
-  codexAppServerAgentRunPatch,
-  codexAppServerRunIdentityForPatch,
-  codexAppServerRunPatchIsStaleAfterTerminalState,
-  codexAppServerRunPatchSettlesOtherActiveTurn,
-  CODEX_APP_SERVER_AGENT_RUN_ID,
-  CODEX_AGENT_PROVIDER,
-  CODEX_APP_SERVER_RUN_STATE,
-  codexAppServerRunInputSource,
-  codexAppServerTurnStateFromAgentRun
-} from "./codexTurnState.js";
+import { codexAppServerRunStateIsActive, codexAppServerAgentRun, codexAppServerPendingUserMessageClientIds, codexAppServerProcessedResultEvent, codexAppServerTurnCanReceiveProviderActivity, codexAppServerTurnKey, codexAppServerAgentRunPatch, codexAppServerRunIdentityForPatch, codexAppServerRunPatchIsStaleAfterTerminalState, codexAppServerRunPatchSettlesOtherActiveTurn, CODEX_APP_SERVER_AGENT_RUN_ID, CODEX_AGENT_PROVIDER, CODEX_APP_SERVER_RUN_STATE, codexAppServerRunInputSource, codexAppServerTurnStateFromAgentRun } from "./codexTurnState.js";
 import crypto from "node:crypto";
-import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+import { isRecord, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 
 const CODEX_APP_SERVER_PROMPT_CLAIM_GRACE_MS = 15000;
 
-// Original native run claims, guarded journal writes and status retirement.
-// The containing run owner shares these exact Sets and Maps by reference.
+function terminalCodexAppServerAgentRunState(status = "") {
+  const normalizedStatus = normalizeText(status);
+  if (normalizedStatus === "interrupted") {
+    return CODEX_APP_SERVER_RUN_STATE.INTERRUPTED;
+  }
+  if (normalizedStatus === "failed") {
+    return CODEX_APP_SERVER_RUN_STATE.FAILED;
+  }
+  return CODEX_APP_SERVER_RUN_STATE.COMPLETED;
+}
+
+function codexAppServerDateValueMs(value = "") {
+  const parsed = Date.parse(normalizeText(value));
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+/**
+ * Native run claims, guarded journal writes and status retirement. The containing run owner shares these exact Sets
+ * and Maps by reference.
+ * @param {object} dependencies
+ * @param {import("./codexTurn.js").CodexSessionNamespace} dependencies.namespace
+ * @param {(state: unknown) => string} dependencies.normalizeRunState
+ * @param {import("./codexTurn.js").CodexTurnStateReader} dependencies.turnState
+ * @param {import("./codexTurn.js").CodexCreateRuntime} dependencies.createRuntime
+ * @param {import("./codexTurn.js").CodexPublish} dependencies.publish
+ * @param {(sessionId: string, input: object) => Promise<unknown>} dependencies.checkpoint
+ * @param {import("./codexTurn.js").CodexDebugLog} dependencies.debugLog
+ * @param {import("./codexOutput.js").CodexAppServerOutput} dependencies.output
+ * @param {string} dependencies.messageIdPrefix
+ * @param {string} dependencies.sessionIdRequiredError
+ * @param {string} dependencies.turnAlreadyRunningError
+ * @param {string} dependencies.errorPrefix
+ * @param {object} [dependencies.idlePublishPayload]
+ * @param {number} dependencies.finalizingGraceMs
+ * @param {(session: object, run: object) => boolean} dependencies.admissionTaskFinished
+ * @param {string} dependencies.orphanedPromptMessage
+ */
 export function createCodexRunJournal({
   namespace,
   normalizeRunState,
@@ -34,7 +52,6 @@ export function createCodexRunJournal({
   output,
   messageIdPrefix,
   sessionIdRequiredError,
-  turnClaimsUnsupportedError,
   turnAlreadyRunningError,
   errorPrefix,
   idlePublishPayload,
@@ -49,18 +66,14 @@ export function createCodexRunJournal({
   const agentRunPatch = input => codexAppServerAgentRunPatch(input, normalizeRunState);
   const runIdentityForPatch = (session, input) => codexAppServerRunIdentityForPatch(session, input, normalizeRunState);
   const runPatchIsStaleAfterTerminalState = (turn, patch) => codexAppServerRunPatchIsStaleAfterTerminalState(turn, patch, normalizeRunState);
-  const {
-    resultFinalizationKey: codexAppServerResultFinalizationKey,
-    readAgentRunForSession: readCodexAppServerAgentRunForSession
-  } = output;
 
   function codexAppServerTurnResultWasProcessed(session = {}, threadId = "", turnId = "") {
-    const normalizedThreadId = normalizeCodexRunText(threadId);
-    const normalizedTurnId = normalizeCodexRunText(turnId);
+    const normalizedThreadId = normalizeText(threadId);
+    const normalizedTurnId = normalizeText(turnId);
     if (!normalizedThreadId || !normalizedTurnId) {
       return false;
     }
-    return codexAppServerProcessedTurns.has(codexAppServerResultFinalizationKey(
+    return codexAppServerProcessedTurns.has(output.resultFinalizationKey(
       session.sessionId,
       normalizedThreadId,
       normalizedTurnId
@@ -70,8 +83,8 @@ export function createCodexRunJournal({
   async function claimCodexAppServerTurnStart(runtime, sessionId = "", outerTurnId = "", {
     inputSource = "chat"
   } = {}) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedOuterTurnId = normalizeCodexRunText(outerTurnId);
+    const normalizedSessionId = normalizeText(sessionId);
+    const normalizedOuterTurnId = normalizeText(outerTurnId);
     let claimResult = null;
     const mutationResult = await runtime.store.mutateSession(normalizedSessionId, async () => {
       const currentSession = await runtime.getSession(normalizedSessionId);
@@ -85,7 +98,7 @@ export function createCodexRunJournal({
       }
       const updatedAt = new Date().toISOString();
       const runPatch = agentRunPatch({
-        inputSource: normalizeCodexRunText(inputSource) || "chat",
+        inputSource: normalizeText(inputSource) || "chat",
         outerTurnId: normalizedOuterTurnId,
         runState: CODEX_APP_SERVER_RUN_STATE.STARTING,
         session: currentSession,
@@ -115,8 +128,8 @@ export function createCodexRunJournal({
   async function claimCodexAppServerMessageStart(runtime, sessionId = "", outerTurnId = "", {
     inputSource = "chat"
   } = {}) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedOuterTurnId = normalizeCodexRunText(outerTurnId) ||
+    const normalizedSessionId = normalizeText(sessionId);
+    const normalizedOuterTurnId = normalizeText(outerTurnId) ||
       `${messageIdPrefix}${crypto.randomUUID()}`;
     if (!normalizedSessionId) {
       return {
@@ -127,9 +140,6 @@ export function createCodexRunJournal({
         } }
       };
     }
-    if (typeof runtime?.store?.mutateSession !== "function" || typeof runtime?.getSession !== "function") {
-      throw new Error(turnClaimsUnsupportedError);
-    }
     const result = await claimCodexAppServerTurnStart(runtime, normalizedSessionId, normalizedOuterTurnId, { inputSource });
     if (result?.claimed === false && result.session) {
       const turn = turnState(result.session);
@@ -139,8 +149,8 @@ export function createCodexRunJournal({
         error: turnAlreadyRunningError,
         operationOutcome: "agent_already_running",
         refreshRecommended: true,
-        threadId: normalizeCodexRunText(turn.threadId),
-        turnId: normalizeCodexRunText(turn.turnId)
+        threadId: normalizeText(turn.threadId),
+        turnId: normalizeText(turn.turnId)
       }, session: result.session } };
     }
     if (result?.claimed) {
@@ -165,15 +175,13 @@ export function createCodexRunJournal({
     turnId = "",
     updatedAt = ""
   } = {}) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
+    const normalizedSessionId = normalizeText(sessionId);
     let runPatch = null;
     let conversationStream = null;
     let wrote = false;
     let stale = null;
     const updatedSession = await runtime.store.mutateSession(normalizedSessionId, async () => {
-      const currentSession = typeof runtime?.getSession === "function"
-        ? await runtime.getSession(normalizedSessionId).catch(() => null)
-        : null;
+      const currentSession = await runtime.getSession(normalizedSessionId).catch(() => null);
       const identity = runIdentityForPatch(currentSession || {}, {
         threadId,
         turnId
@@ -187,13 +195,13 @@ export function createCodexRunJournal({
         status,
         threadId: identity.threadId,
         turnId: identity.turnId,
-        updatedAt: normalizeCodexRunText(updatedAt) || new Date().toISOString()
+        updatedAt: normalizeText(updatedAt) || new Date().toISOString()
       });
       const currentTurn = turnState(currentSession || {});
       if (
         codexAppServerRunStateIsActive(runPatch.state) &&
-        currentTurn.threadId === normalizeCodexRunText(runPatch.providerThreadId) &&
-        currentTurn.turnId === normalizeCodexRunText(runPatch.providerTurnId) &&
+        currentTurn.threadId === normalizeText(runPatch.providerThreadId) &&
+        currentTurn.turnId === normalizeText(runPatch.providerTurnId) &&
         currentTurn.startedAt
       ) {
         runPatch.startedAt = currentTurn.startedAt;
@@ -209,7 +217,7 @@ export function createCodexRunJournal({
         currentTurn.turnId === runPatch.providerTurnId &&
         runPatch.state === CODEX_APP_SERVER_RUN_STATE.ACTIVE;
       const observationLostBlocks = currentTurn.status === "observation_lost" && status !== "observation_lost";
-      const phaseTargetsOtherTurn = phase !== undefined && (!normalizeCodexRunText(turnId) ||
+      const phaseTargetsOtherTurn = phase !== undefined && (!normalizeText(turnId) ||
         !codexAppServerTurnCanReceiveProviderActivity(currentTurn, threadId, turnId));
       const observationExpired = Boolean(observedRun) && !canRecoverStoppedTurn;
       const terminalAlreadyRecorded = !canRecoverStoppedTurn && runPatchIsStaleAfterTerminalState(currentTurn, runPatch);
@@ -241,7 +249,7 @@ export function createCodexRunJournal({
       await runtime.store.writeAgentRunEvent(normalizedSessionId, CODEX_APP_SERVER_AGENT_RUN_ID, {
         event: {
           kind: publishReason || "codex-app-server-turn-state",
-          message: normalizeCodexRunText(error),
+          message: normalizeText(error),
           state: runPatch.state
         },
         patch: runPatch
@@ -256,7 +264,7 @@ export function createCodexRunJournal({
   }
 
   function clearCodexAppServerActiveTimer(sessionId = "") {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
+    const normalizedSessionId = normalizeText(sessionId);
     const sessionKey = namespace(normalizedSessionId);
     const timer = codexAppServerActiveTimers.get(sessionKey);
     if (timer) {
@@ -266,7 +274,7 @@ export function createCodexRunJournal({
   }
 
   function clearCodexAppServerFinalizingTimer(sessionId = "", threadId = "", turnId = "") {
-    const key = codexAppServerResultFinalizationKey(sessionId, threadId, turnId);
+    const key = output.resultFinalizationKey(sessionId, threadId, turnId);
     const entry = codexAppServerFinalizingTimers.get(key);
     if (entry) {
       clearTimeout(entry.timer);
@@ -275,7 +283,7 @@ export function createCodexRunJournal({
   }
 
   function clearCodexAppServerSessionRecoveryTimers(sessionId = "") {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
+    const normalizedSessionId = normalizeText(sessionId);
     clearCodexAppServerActiveTimer(normalizedSessionId);
     const finalizingKeyPrefix = `${namespace(normalizedSessionId)}:`;
     for (const [key, entry] of codexAppServerFinalizingTimers.entries()) {
@@ -286,17 +294,6 @@ export function createCodexRunJournal({
     }
   }
 
-  function terminalCodexAppServerAgentRunState(status = "") {
-    const normalizedStatus = normalizeCodexRunText(status);
-    if (normalizedStatus === "interrupted") {
-      return CODEX_APP_SERVER_RUN_STATE.INTERRUPTED;
-    }
-    if (normalizedStatus === "failed") {
-      return CODEX_APP_SERVER_RUN_STATE.FAILED;
-    }
-    return CODEX_APP_SERVER_RUN_STATE.COMPLETED;
-  }
-
   function codexAppServerAgentRunRealtimePayload(runPatch = {}) {
     const turn = codexAppServerTurnStateFromAgentRun({ ...runPatch, id: CODEX_APP_SERVER_AGENT_RUN_ID }, normalizeRunState);
     return {
@@ -350,7 +347,7 @@ export function createCodexRunJournal({
     turnId = "",
     updatedAt = ""
   } = {}) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
+    const normalizedSessionId = normalizeText(sessionId);
     if (!normalizedSessionId) {
       return {
         ok: false,
@@ -385,27 +382,27 @@ export function createCodexRunJournal({
 
   async function markCodexAppServerTurnFinalizing(sessionId = "", input = {}) {
     const result = await publishCodexAppServerAgentRun(sessionId, {
-      error: normalizeCodexRunText(input.error),
+      error: normalizeText(input.error),
       publishReason: "codex-app-server-turn-finalizing",
       runState: CODEX_APP_SERVER_RUN_STATE.FINALIZING,
-      status: normalizeCodexRunText(input.status) || "completed",
-      threadId: normalizeCodexRunText(input.threadId),
-      turnId: normalizeCodexRunText(input.turnId)
+      status: normalizeText(input.status) || "completed",
+      threadId: normalizeText(input.threadId),
+      turnId: normalizeText(input.turnId)
     });
     clearCodexAppServerActiveTimer(sessionId);
     return result;
   }
 
   async function markCodexAppServerTurnIdle(sessionId = "", input = {}) {
-    const status = normalizeCodexRunText(input.status) || "completed";
+    const status = normalizeText(input.status) || "completed";
     const result = await publishCodexAppServerAgentRun(sessionId, {
-      error: normalizeCodexRunText(input.error),
+      error: normalizeText(input.error),
       publishPayload: idlePublishPayload,
       publishReason: "codex-app-server-turn-idle",
       runState: terminalCodexAppServerAgentRunState(status),
       status,
-      threadId: normalizeCodexRunText(input.threadId),
-      turnId: normalizeCodexRunText(input.turnId)
+      threadId: normalizeText(input.threadId),
+      turnId: normalizeText(input.turnId)
     });
     clearCodexAppServerActiveTimer(sessionId);
     clearCodexAppServerFinalizingTimer(sessionId, input.threadId, input.turnId);
@@ -416,16 +413,16 @@ export function createCodexRunJournal({
       ...result,
       checkpoint: await checkpoint(sessionId, {
         status,
-        turnOutcome: normalizeCodexRunText(input.turnOutcome),
-        threadId: normalizeCodexRunText(input.threadId),
-        turnId: normalizeCodexRunText(input.turnId)
+        turnOutcome: normalizeText(input.turnOutcome),
+        threadId: normalizeText(input.threadId),
+        turnId: normalizeText(input.turnId)
       })
     };
   }
 
   async function currentCodexAppServerTurnId(sessionId = "", threadId = "") {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedThreadId = normalizeCodexRunText(threadId);
+    const normalizedSessionId = normalizeText(sessionId);
+    const normalizedThreadId = normalizeText(threadId);
     if (!normalizedSessionId) {
       return "";
     }
@@ -442,16 +439,11 @@ export function createCodexRunJournal({
   }
 
   async function resolveCodexAppServerTurnId(sessionId = "", threadId = "", turnId = "") {
-    return normalizeCodexRunText(turnId) || await currentCodexAppServerTurnId(sessionId, threadId);
-  }
-
-  function codexAppServerDateValueMs(value = "") {
-    const parsed = Date.parse(normalizeCodexRunText(value));
-    return Number.isFinite(parsed) ? parsed : 0;
+    return normalizeText(turnId) || await currentCodexAppServerTurnId(sessionId, threadId);
   }
 
   function codexAppServerFinalizingExpired(turn = {}, nowMs = Date.now()) {
-    if (normalizeCodexRunText(turn.state) !== "finalizing") {
+    if (normalizeText(turn.state) !== "finalizing") {
       return false;
     }
     const referenceMs = codexAppServerDateValueMs(turn.completedAt) || codexAppServerDateValueMs(turn.updatedAt);
@@ -467,8 +459,8 @@ export function createCodexRunJournal({
   }
 
   function codexAppServerTurnWasCompleted(session = {}, threadId = "", turnId = "") {
-    const normalizedThreadId = normalizeCodexRunText(threadId);
-    const normalizedTurnId = normalizeCodexRunText(turnId);
+    const normalizedThreadId = normalizeText(threadId);
+    const normalizedTurnId = normalizeText(turnId);
     if (!normalizedThreadId || !normalizedTurnId) {
       return false;
     }
@@ -479,7 +471,7 @@ export function createCodexRunJournal({
   }
 
   async function failOrphanedCodexAppServerPromptDelivery(runtime, session = {}, turn = {}) {
-    const sessionId = normalizeCodexRunText(session.sessionId);
+    const sessionId = normalizeText(session.sessionId);
     if (!sessionId) {
       return session;
     }
@@ -523,14 +515,14 @@ export function createCodexRunJournal({
     eventKind = "codex-app-server-user-message-ownership-updated",
     owned = false
   } = {}) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedClientId = normalizeCodexRunText(clientId);
+    const normalizedSessionId = normalizeText(sessionId);
+    const normalizedClientId = normalizeText(clientId);
     if (!normalizedSessionId || !normalizedClientId) {
       return false;
     }
     let wasOwned = false;
     await store.mutateSession(normalizedSessionId, async () => {
-      const run = await readCodexAppServerAgentRunForSession(store, normalizedSessionId);
+      const run = await output.readAgentRunForSession(store, normalizedSessionId);
       const currentIds = codexAppServerPendingUserMessageClientIds(run);
       wasOwned = currentIds.indexOf(normalizedClientId) >= 0;
       if (wasOwned === owned) {
@@ -567,9 +559,9 @@ export function createCodexRunJournal({
       nowMs - runUpdatedMs >= CODEX_APP_SERVER_PROMPT_CLAIM_GRACE_MS
     );
     return (
-      normalizeCodexRunText(run.state) === CODEX_APP_SERVER_RUN_STATE.STARTING &&
-      !normalizeCodexRunText(run.providerThreadId) &&
-      !normalizeCodexRunText(run.providerTurnId) &&
+      normalizeText(run.state) === CODEX_APP_SERVER_RUN_STATE.STARTING &&
+      !normalizeText(run.providerThreadId) &&
+      !normalizeText(run.providerTurnId) &&
       promptDeliveryActive !== true &&
       (admissionTaskFinished(session, run) || claimExpired)
     ) ? run : null;
@@ -577,7 +569,7 @@ export function createCodexRunJournal({
 
   async function recoverAbandonedCodexAppServerPromptClaim(runtime, session = {}, options = {}) {
     const run = abandonedCodexAppServerPromptClaim(session, options);
-    if (!run || !session?.sessionId || typeof runtime?.store?.writeAgentRunEvent !== "function") {
+    if (!run || !session.sessionId) {
       return {
         recovered: false,
         session
@@ -602,7 +594,7 @@ export function createCodexRunJournal({
       }
     });
     debugLog("appServerPrompt.abandoned", {
-      runUpdatedAt: normalizeCodexRunText(run.updatedAt),
+      runUpdatedAt: normalizeText(run.updatedAt),
       sessionId: session.sessionId
     });
     return {
@@ -611,7 +603,7 @@ export function createCodexRunJournal({
     };
   }
 
-  return {
+  return Object.freeze({
     completedTurns: codexAppServerCompletedTurns,
     processedTurns: codexAppServerProcessedTurns,
     activeTimers: codexAppServerActiveTimers,
@@ -619,7 +611,7 @@ export function createCodexRunJournal({
     agentRunPatch,
     turnResultWasProcessed: codexAppServerTurnResultWasProcessed,
     claimTurnStart: claimCodexAppServerTurnStart,
-    claimMessageStart: claimCodexAppServerMessageStart,
+    claimCodexAppServerMessageStart,
     writeAgentRun: writeCodexAppServerAgentRun,
     clearActiveTimer: clearCodexAppServerActiveTimer,
     clearFinalizingTimer: clearCodexAppServerFinalizingTimer,
@@ -636,5 +628,7 @@ export function createCodexRunJournal({
     writeUserMessageOwnership: writeCodexAppServerUserMessageOwnership,
     recoverAbandonedPromptClaim: recoverAbandonedCodexAppServerPromptClaim,
     failOrphanedPromptDelivery: failOrphanedCodexAppServerPromptDelivery
-  };
+  });
 }
+
+/** @typedef {ReturnType<typeof createCodexRunJournal>} CodexRunJournal */