@jskit-ai/assistant-core 0.2.7 → 0.2.9

package/src/server/conversation/codexTurnRecovery.js

@@ -1,30 +1,37 @@
-import {
-  codexAppServerTurnStatusIsActive,
-  codexAppServerTurnStatusIsComplete,
-  codexAppServerTurnStatusIsSuccessfulComplete,
-  codexAppServerTurnStatusIsProviderFailure,
-  codexAppServerThreadStatus,
-  codexAppServerReadThreadStatus,
-  normalizeCodexRunText,
-  codexAppServerAgentRun,
-  codexAppServerPendingUserMessageClientIds,
-  codexAppServerPendingUserMessageOwnership,
-  codexAppServerTurnOwnsActiveGoal,
-  codexAppServerTurnCanReceiveProviderCompletion,
-  codexAppServerTurnAwaitsProviderIdentity,
-  codexAppServerTurnCanReceiveProviderActivity,
-  codexAppServerTurnCanAdoptSuccessor,
-  codexAppServerTurnKey,
-  CODEX_APP_SERVER_RUN_STATE
-} from "./codexTurnState.js";
-import {
-  codexAppServerProviderTurnForOperation,
-  codexAppServerThreadTurnId,
-  codexAppServerThreadError
-} from "./codexEvents.js";
+import { codexAppServerTurnStatusIsActive, codexAppServerTurnStatusIsComplete, codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, codexAppServerThreadStatus, codexAppServerReadThreadStatus, codexAppServerAgentRun, codexAppServerPendingUserMessageOwnership, codexAppServerTurnCanAdoptSuccessor } from "./codexTurnState.js";
+import { codexAppServerProviderTurnForOperation, codexAppServerThreadTurnId, codexAppServerThreadError } from "./codexThreadSnapshot.js";
+import { createCodexTurnActivity } from "./codexTurnActivity.js";
+import { createCodexTurnEndings } from "./codexTurnEndings.js";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 
-// Original active/finalizing recovery, provider activity and completion decisions.
-// Timers and receipts remain owned by the shared journal/output/settlement instances.
+/**
+ * Active and finalizing turn recovery: the timers that reread the provider, and the reconciliation of the tracked
+ * turn with what the provider reports. Timers and receipts remain owned by the shared journal, output and settlement.
+ * @param {object} dependencies
+ * @param {import("./codexRunJournal.js").CodexRunJournal} dependencies.journal
+ * @param {import("./codexOutput.js").CodexAppServerOutput} dependencies.output
+ * @param {import("./codexResultSettlement.js").CodexResultSettlement} dependencies.settlement
+ * @param {Set<string>} dependencies.promptDeliveries
+ * @param {import("./codexTurn.js").CodexSessionNamespace} dependencies.namespace
+ * @param {import("./codexTurn.js").CodexCreateRuntime} dependencies.createRuntime
+ * @param {import("./codexTurn.js").CodexCreateStore} dependencies.createStore
+ * @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 {import("./codexTurn.js").CodexCaptureContext} dependencies.captureContext
+ * @param {import("./codexTurn.js").CodexRunInContext} dependencies.runInContext
+ * @param {number} dependencies.activeReconcileMs
+ * @param {boolean} dependencies.finalizingGraceAfterHistoryRead
+ * @param {number} dependencies.failureDetailGraceMs
+ * @param {import("./codexNotificationQueue.js").CodexAppServerNotificationQueue} dependencies.notificationQueue
+ * @param {(session: object) => boolean} dependencies.hasRuntime
+ * @param {import("./codexTurn.js").CodexAdmissionRecovery} dependencies.recoverAdmission
+ * @param {import("./codexTurn.js").CodexTurnOutcomes} dependencies.turnOutcomes
+ * @param {(...details: any[]) => Promise<unknown>} dependencies.outcomeNotice
+ * @param {(details: { error?: string }) => string} dependencies.resultDeliveryFailureMessage
+ */
 export function createCodexTurnRecovery({
   journal,
   output,
@@ -50,135 +57,52 @@ export function createCodexTurnRecovery({
   outcomeNotice,
   resultDeliveryFailureMessage
 }) {
-  const {
-    finalizedTurns: codexAppServerFinalizedTurns,
-    resultFinalizationKey: codexAppServerResultFinalizationKey,
-    readAgentRunForSession: readCodexAppServerAgentRunForSession,
-    submitAssistantResult: submitCodexAppServerAssistantResult,
-    cleanupUntrackedTurn: cleanupCodexAppServerUntrackedTurn
-  } = output;
-  const {
-    completedTurns: codexAppServerCompletedTurns,
-    activeTimers: codexAppServerActiveTimers,
-    finalizingTimers: codexAppServerFinalizingTimers,
-    turnResultWasProcessed: codexAppServerTurnResultWasProcessed,
-    clearActiveTimer: clearCodexAppServerActiveTimer,
-    clearFinalizingTimer: clearCodexAppServerFinalizingTimer,
-    publishAgentRun: publishCodexAppServerAgentRun,
-    markTurnFinalizing: markCodexAppServerTurnFinalizing,
-    markTurnIdle: markCodexAppServerTurnIdle,
-    resolveTurnId: resolveCodexAppServerTurnId,
-    finalizingExpired: codexAppServerFinalizingExpired,
-    finalizingRemainingMs: codexAppServerFinalizingRemainingMs,
-    turnWasCompleted: codexAppServerTurnWasCompleted,
-    runInputSource: codexAppServerRunInputSource,
-    writeUserMessageOwnership: writeCodexAppServerUserMessageOwnership,
-    recoverAbandonedPromptClaim: recoverAbandonedCodexAppServerPromptClaim,
-    failOrphanedPromptDelivery: failOrphanedCodexAppServerPromptDelivery
-  } = journal;
-  const {
-    finalizeAssistantResult: finalizeCodexAppServerAssistantResult,
-    recoverFinalResponseBeforeOutcome: recoverCodexAppServerFinalResponseBeforeOutcome,
-    adoptSuccessorTurn: adoptCodexAppServerSuccessorTurn
-  } = settlement;
-  const codexAppServerPromptDeliveries = promptDeliveries;
-  const retainFinalizingTimer = finalizingGraceAfterHistoryRead || failureDetailGraceMs > 0;
+  const activity = createCodexTurnActivity({
+    journal,
+    output,
+    settlement,
+    createRuntime,
+    createStore,
+    debugLog,
+    turnState,
+    turnStateFromAgentRun,
+    scheduleActiveRecovery: scheduleCodexAppServerActiveRecovery
+  });
+  const endings = createCodexTurnEndings({
+    journal,
+    output,
+    settlement,
+    createRuntime,
+    debugLog,
+    debugError,
+    turnState,
+    failureDetailGraceMs,
+    turnOutcomes,
+    outcomeNotice,
+    resultDeliveryFailureMessage,
+    captureContext,
+    runInContext,
+    notificationQueue,
+    finalizingGraceAfterHistoryRead,
+    scheduleActiveRecovery: scheduleCodexAppServerActiveRecovery
+  });
 
   function scheduleCodexAppServerActiveRecovery(sessionId = "", delayMs = activeReconcileMs) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
+    const normalizedSessionId = normalizeText(sessionId);
     const sessionKey = namespace(normalizedSessionId);
     const projectContext = captureContext();
-    if (!normalizedSessionId || codexAppServerActiveTimers.has(sessionKey)) {
+    if (!normalizedSessionId || journal.activeTimers.has(sessionKey)) {
       return;
     }
     const timer = setTimeout(() => {
-      codexAppServerActiveTimers.delete(sessionKey);
+      journal.activeTimers.delete(sessionKey);
       void runInContext(
         projectContext,
         () => recoverCodexAppServerActiveTurn(normalizedSessionId)
       );
     }, delayMs);
-    timer.unref?.();
-    codexAppServerActiveTimers.set(sessionKey, timer);
-  }
-
-  function scheduleCodexAppServerFinalizingRecovery(sessionId = "", threadId = "", turnId = "", {
-    completedAt = "",
-    status = "completed",
-    updatedAt = "",
-    failureDetail = null
-  } = {}) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedThreadId = normalizeCodexRunText(threadId);
-    const normalizedTurnId = normalizeCodexRunText(turnId);
-    if (!normalizedSessionId || !normalizedThreadId || !normalizedTurnId) {
-      return;
-    }
-    clearCodexAppServerFinalizingTimer(normalizedSessionId, normalizedThreadId, normalizedTurnId);
-    const key = codexAppServerResultFinalizationKey(
-      normalizedSessionId,
-      normalizedThreadId,
-      normalizedTurnId
-    );
-    const projectContext = captureContext();
-    const delayMs = failureDetail
-      ? Math.max(0, failureDetail.expiresAt - Date.now())
-      : codexAppServerFinalizingRemainingMs({ completedAt, state: "finalizing", updatedAt });
-    // One record per pending deadline: `recovery` is the in-flight expiry
-    // (retained-timer policy only), `expiresAt` the first deadline that a later
-    // failure-detail grace may not exceed, `failureDetail` a deferred provider
-    // failure, and `startedAt` the post-read clock that rereads must keep.
-    const entry = {
-      timer: null,
-      recovery: null,
-      expiresAt: failureDetailGraceMs > 0 ? Date.now() + delayMs : null,
-      failureDetail,
-      startedAt: !failureDetail && finalizingGraceAfterHistoryRead ? completedAt : ""
-    };
-    entry.timer = setTimeout(() => {
-      if (failureDetail) {
-        notificationQueue.run({ projectContext, provider: failureDetail.provider, sessionId: normalizedSessionId }, async () => {
-          if (codexAppServerFinalizingTimers.get(key) !== entry) return;
-          try {
-            return await stopCodexAppServerTurnWithProviderFailure(normalizedSessionId, normalizedThreadId, normalizedTurnId,
-              { ...failureDetail, failureDetailReady: true });
-          } finally {
-            if (codexAppServerFinalizingTimers.get(key) === entry) {
-              clearCodexAppServerFinalizingTimer(normalizedSessionId, normalizedThreadId, normalizedTurnId);
-            }
-          }
-        });
-        return;
-      }
-      // The post-read policy keeps its first clock while expiry rereads history.
-      if (!retainFinalizingTimer) codexAppServerFinalizingTimers.delete(key);
-      const recovery = runInContext(
-        projectContext,
-        () => recoverCodexAppServerFinalizingTurn(
-          normalizedSessionId,
-          normalizedThreadId,
-          normalizedTurnId,
-          { status, timerRecovery: finalizingGraceAfterHistoryRead }
-        )
-      );
-      if (retainFinalizingTimer) {
-        entry.recovery = recovery;
-        void recovery.then(
-          () => { if (entry.recovery === recovery) entry.recovery = null; },
-          error => {
-            if (entry.recovery === recovery) entry.recovery = null;
-            debugLog("appServerFinalizingRecovery.error", {
-              error: debugError(error), sessionId: normalizedSessionId,
-              threadId: normalizedThreadId, turnId: normalizedTurnId
-            });
-          }
-        );
-      } else {
-        void recovery;
-      }
-    }, delayMs);
-    entry.timer.unref?.();
-    codexAppServerFinalizingTimers.set(key, entry);
+    timer.unref();
+    journal.activeTimers.set(sessionKey, timer);
   }
 
   async function reconcileCodexAppServerActiveTurn(session = {}, {
@@ -186,15 +110,15 @@ export function createCodexTurnRecovery({
     runtime = null,
     providerError = null
   } = {}) {
-    const sessionId = normalizeCodexRunText(session.sessionId);
+    const sessionId = normalizeText(session.sessionId);
     const trackedTurn = turnState(session);
     if (!sessionId || !trackedTurn.active || !trackedTurn.threadId || !hasRuntime(session)) {
       return session;
     }
     const provider = suppliedProvider || await acquireProvider({ sessionId, runtime, session });
-    if (typeof provider?.readThreadStatus !== "function") {
+    if (!provider) {
       if (trackedTurn.state === "finalizing") {
-        await recoverCodexAppServerFinalizingTurn(
+        await endings.recoverFinalizingTurn(
           sessionId,
           trackedTurn.threadId,
           trackedTurn.turnId,
@@ -213,7 +137,7 @@ export function createCodexTurnRecovery({
     let thread = await codexAppServerReadThreadStatus(provider, trackedTurn.threadId);
     let status = codexAppServerThreadStatus(thread);
     let providerTurnId = codexAppServerThreadTurnId(thread);
-    const promptDeliveryIsLocal = codexAppServerPromptDeliveries.has(
+    const promptDeliveryIsLocal = promptDeliveries.has(
       namespace(sessionId)
     );
     if (
@@ -224,8 +148,8 @@ export function createCodexTurnRecovery({
       const ownership = codexAppServerPendingUserMessageOwnership(
         codexAppServerAgentRun(currentSession)
       );
-      if (!ownership || typeof provider?.readThread !== "function") {
-        return failOrphanedCodexAppServerPromptDelivery(
+      if (!ownership) {
+        return journal.failOrphanedPromptDelivery(
           activeRuntime,
           currentSession,
           currentTurn
@@ -236,7 +160,7 @@ export function createCodexTurnRecovery({
         clientMessageId: ownership.clientId
       });
       if (!ownedProviderTurn) {
-        return failOrphanedCodexAppServerPromptDelivery(
+        return journal.failOrphanedPromptDelivery(
           activeRuntime,
           currentSession,
           currentTurn
@@ -249,20 +173,20 @@ export function createCodexTurnRecovery({
       status = codexAppServerThreadStatus(thread);
       providerTurnId = codexAppServerThreadTurnId(thread);
       if (!providerTurnId) {
-        return failOrphanedCodexAppServerPromptDelivery(
+        return journal.failOrphanedPromptDelivery(
           activeRuntime,
           currentSession,
           currentTurn
         );
       }
-      await markCodexAppServerProviderTurnActive(sessionId, {
+      await activity.markProviderTurnActive(sessionId, {
         inputSource: ownership.inputSource,
         source: "owned_prompt_recovery",
         status: codexAppServerTurnStatusIsActive(status) ? status : "inProgress",
         threadId: currentTurn.threadId,
         turnId: providerTurnId
       });
-      await writeCodexAppServerUserMessageOwnership(
+      await journal.writeUserMessageOwnership(
         activeRuntime.store,
         sessionId,
         ownership.clientId,
@@ -285,7 +209,7 @@ export function createCodexTurnRecovery({
       providerTurnId &&
       codexAppServerTurnCanAdoptSuccessor(currentTurn, currentTurn.threadId, providerTurnId)
     ) {
-      const adoption = await adoptCodexAppServerSuccessorTurn(sessionId, {
+      const adoption = await settlement.adoptSuccessorTurn(sessionId, {
         previousTurnId: currentTurn.turnId,
         source: "active_reconciliation",
         status: "inProgress",
@@ -302,14 +226,14 @@ export function createCodexTurnRecovery({
       }
     }
     if (currentTurn.state === "finalizing") {
-      await recoverCodexAppServerFinalizingTurn(sessionId, currentTurn.threadId, currentTurn.turnId, {
+      await endings.recoverFinalizingTurn(sessionId, currentTurn.threadId, currentTurn.turnId, {
         status: currentTurn.status || "completed"
       });
       return activeRuntime.getSession(sessionId);
     }
     if (currentTurn.state === "starting") {
       if (codexAppServerTurnStatusIsActive(status) && providerTurnId) {
-        await markCodexAppServerProviderTurnActive(sessionId, {
+        await activity.markProviderTurnActive(sessionId, {
           source: "active_reconciliation",
           status,
           threadId: currentTurn.threadId,
@@ -326,9 +250,9 @@ export function createCodexTurnRecovery({
         return currentSession;
       }
       if (!providerTurnId || !codexAppServerTurnStatusIsComplete(status)) {
-        return failOrphanedCodexAppServerPromptDelivery(activeRuntime, currentSession, currentTurn);
+        return journal.failOrphanedPromptDelivery(activeRuntime, currentSession, currentTurn);
       }
-      await markCodexAppServerProviderTurnActive(sessionId, {
+      await activity.markProviderTurnActive(sessionId, {
         source: "active_reconciliation",
         status: "inProgress",
         threadId: currentTurn.threadId,
@@ -355,14 +279,14 @@ export function createCodexTurnRecovery({
     });
     if (codexAppServerTurnStatusIsProviderFailure(status)) {
       const exactError = providerError?.threadId === currentTurn.threadId && providerError?.turnId === completedTurnId;
-      await stopCodexAppServerTurnWithProviderFailure(sessionId, currentTurn.threadId, completedTurnId, {
+      await endings.stopTurnWithProviderFailure(sessionId, currentTurn.threadId, completedTurnId, {
         error: exactError ? providerError.error : codexAppServerThreadError(thread),
         failureDetailReady: exactError,
         provider,
         status
       });
     } else if (codexAppServerTurnStatusIsSuccessfulComplete(status)) {
-      await completeCodexAppServerTurn(sessionId, currentTurn.threadId, completedTurnId, {
+      await endings.completeTurn(sessionId, currentTurn.threadId, completedTurnId, {
         status,
         verifyInactive: false
       });
@@ -370,338 +294,24 @@ export function createCodexTurnRecovery({
     return activeRuntime.getSession(sessionId);
   }
 
-  async function codexAppServerProviderBlocksTurnRelease(sessionId = "", provider = null, threadId = "", turnId = "", {
-    source = ""
-  } = {}) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedThreadId = normalizeCodexRunText(threadId);
-    const normalizedTurnId = normalizeCodexRunText(turnId);
-    if (!normalizedSessionId || !normalizedThreadId) {
-      return false;
-    }
-    const runtime = await createRuntime();
-    const session = await runtime.getSession(normalizedSessionId);
-    const turn = turnState(session);
-    if (!turn.active || !codexAppServerTurnCanReceiveProviderActivity(turn, normalizedThreadId, normalizedTurnId)) {
-      return false;
-    }
-    try {
-      const providerThread = await codexAppServerReadThreadStatus(provider, normalizedThreadId, {
-        observeLatestTurn: true
-      });
-      if (!providerThread) {
-        return false;
-      }
-      const status = codexAppServerThreadStatus(providerThread);
-      const providerTurnId = codexAppServerThreadTurnId(providerThread);
-      if (
-        providerTurnId &&
-        providerTurnId !== normalizeCodexRunText(turn.turnId)
-      ) {
-        debugLog("appServerTurn.releaseAllowedSuccessor", {
-          providerTurnId,
-          sessionId: normalizedSessionId,
-          source: normalizeCodexRunText(source),
-          threadId: normalizedThreadId,
-          turnId: turn.turnId
-        });
-        return false;
-      }
-      if (!codexAppServerTurnStatusIsActive(status)) {
-        return false;
-      }
-      debugLog("appServerTurn.releaseBlockedActive", {
-        sessionId: normalizedSessionId,
-        source: normalizeCodexRunText(source),
-        status,
-        threadId: normalizedThreadId,
-        turnId: normalizedTurnId || turn.turnId
-      });
-      scheduleCodexAppServerActiveRecovery(normalizedSessionId);
-      return true;
-    } catch (error) {
-      debugLog("appServerTurn.releaseCheck.error", {
-        error: debugError(error),
-        sessionId: normalizedSessionId,
-        source: normalizeCodexRunText(source),
-        threadId: normalizedThreadId,
-        turnId: normalizedTurnId || turn.turnId
-      });
-      return false;
-    }
-  }
-
-  async function markCodexAppServerTurnActive(sessionId = "", input = {}) {
-    if (input.requireTrackedTurn === true) {
-      const runtime = await createRuntime();
-      const session = await runtime.getSession(sessionId);
-      const turn = turnState(session);
-      if (!codexAppServerTurnCanReceiveProviderActivity(turn, input.threadId, input.turnId)) {
-        debugLog("appServerTurn.active.ignored", {
-          currentState: turn.state,
-          currentStatus: turn.status,
-          currentThreadId: turn.threadId,
-          currentTurnId: turn.turnId,
-          sessionId: normalizeCodexRunText(sessionId),
-          threadId: normalizeCodexRunText(input.threadId),
-          turnId: normalizeCodexRunText(input.turnId)
-        });
-        return {
-          ok: true,
-          processed: false,
-          reason: "untracked_terminal_turn"
-        };
-      }
-    }
-    const status = normalizeCodexRunText(input.status) || "inProgress";
-    const result = await publishCodexAppServerAgentRun(sessionId, {
-      inputSource: normalizeCodexRunText(input.inputSource),
-      phase: input.phase,
-      publishReason: "codex-app-server-turn-active",
-      observedRun: input.observedRun,
-      runState: status === "starting" ? CODEX_APP_SERVER_RUN_STATE.STARTING : CODEX_APP_SERVER_RUN_STATE.ACTIVE,
-      status,
-      threadId: normalizeCodexRunText(input.threadId),
-      turnId: normalizeCodexRunText(input.turnId)
-    });
-    if (status === "starting") {
-      scheduleCodexAppServerActiveRecovery(sessionId);
-    } else {
-      clearCodexAppServerActiveTimer(sessionId);
-    }
-    return result;
-  }
-
-  async function markCodexAppServerProviderTurnActive(sessionId = "", input = {}) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedThreadId = normalizeCodexRunText(input.threadId);
-    const normalizedTurnId = normalizeCodexRunText(input.turnId);
-    const requestedStatus = normalizeCodexRunText(input.status) || "inProgress";
-    const store = await createStore(normalizedSessionId);
-    const persistedRun = await readCodexAppServerAgentRunForSession(
-      store,
-      normalizedSessionId
-    );
-    const persistedTurn = turnStateFromAgentRun(persistedRun || {});
-    const requestedInputSource = normalizeCodexRunText(input.inputSource);
-    if (
-      persistedTurn.active &&
-      persistedTurn.state === "active" &&
-      persistedTurn.threadId === normalizedThreadId &&
-      persistedTurn.turnId === normalizedTurnId &&
-      codexAppServerTurnStatusIsActive(requestedStatus) &&
-      (!requestedInputSource || requestedInputSource === persistedTurn.inputSource)
-    ) {
-      clearCodexAppServerActiveTimer(normalizedSessionId);
-      return {
-        ok: true,
-        processed: false,
-        reason: "already_active"
-      };
-    }
-    const runtime = await createRuntime();
-    let session = await runtime.getSession(normalizedSessionId);
-    let turn = turnState(session);
-    if (
-      input.observedRun &&
-      [CODEX_APP_SERVER_RUN_STATE.FAILED, CODEX_APP_SERVER_RUN_STATE.INTERRUPTED].includes(turn.runState) &&
-      turn.threadId === normalizedThreadId &&
-      turn.turnId === normalizedTurnId &&
-      !codexAppServerTurnResultWasProcessed(session, normalizedThreadId, normalizedTurnId)
-    ) {
-      const recovered = await markCodexAppServerTurnActive(normalizedSessionId, {
-        inputSource: turn.inputSource,
-        observedRun: input.observedRun,
-        status: requestedStatus,
-        threadId: normalizedThreadId,
-        turnId: normalizedTurnId
-      });
-      if (recovered.processed !== false) {
-        codexAppServerCompletedTurns.delete(codexAppServerTurnKey(normalizedThreadId, normalizedTurnId));
-        codexAppServerFinalizedTurns.delete(codexAppServerResultFinalizationKey(
-          normalizedSessionId, normalizedThreadId, normalizedTurnId
-        ));
-      }
-      return recovered;
-    }
-    if (codexAppServerTurnWasCompleted(session, normalizedThreadId, normalizedTurnId)) {
-      debugLog("appServerProviderTurn.completed.ignored", {
-        currentState: turn.state,
-        currentThreadId: turn.threadId,
-        currentTurnId: turn.turnId,
-        sessionId: normalizedSessionId,
-        threadId: normalizedThreadId,
-        turnId: normalizedTurnId
-      });
-      return {
-        ok: true,
-        processed: false,
-        reason: "completed_turn"
-      };
-    }
-    if (
-      turn.state === "finalizing" &&
-      codexAppServerTurnCanAdoptSuccessor(turn, normalizedThreadId, normalizedTurnId) &&
-      codexAppServerTurnResultWasProcessed(session, normalizedThreadId, turn.turnId)
-    ) {
-      await finalizeCodexAppServerAssistantResult(
-        normalizedSessionId,
-        normalizedThreadId,
-        turn.turnId,
-        {
-          status: turn.status || "completed"
-        }
-      );
-      session = await runtime.getSession(normalizedSessionId);
-      turn = turnState(session);
-    }
-    const currentRun = codexAppServerAgentRun(session);
-    const pendingInputSource = codexAppServerPendingUserMessageClientIds(currentRun).length > 0
-      ? codexAppServerRunInputSource(currentRun)
-      : "";
-    const goalInputSource = codexAppServerTurnOwnsActiveGoal(turn, normalizedThreadId)
-      ? codexAppServerRunInputSource(currentRun)
-      : "";
-    const inputSource = normalizeCodexRunText(input.inputSource) || pendingInputSource || goalInputSource;
-    if (codexAppServerTurnCanReceiveProviderActivity(turn, normalizedThreadId, normalizedTurnId)) {
-      return markCodexAppServerTurnActive(normalizedSessionId, {
-        inputSource,
-        status: requestedStatus,
-        threadId: normalizedThreadId,
-        turnId: normalizedTurnId
-      });
-    }
-    if (codexAppServerTurnCanAdoptSuccessor(turn, normalizedThreadId, normalizedTurnId)) {
-      return adoptCodexAppServerSuccessorTurn(normalizedSessionId, {
-        previousTurnId: turn.turnId,
-        source: normalizeCodexRunText(input.source) || "provider_activity",
-        status: requestedStatus,
-        threadId: normalizedThreadId,
-        turnId: normalizedTurnId
-      });
-    }
-    if (turn.active || !normalizedTurnId) {
-      debugLog("appServerProviderTurn.active.ignored", {
-        currentState: turn.state,
-        currentStatus: turn.status,
-        currentThreadId: turn.threadId,
-        currentTurnId: turn.turnId,
-        sessionId: normalizedSessionId,
-        threadId: normalizedThreadId,
-        turnId: normalizedTurnId
-      });
-      return {
-        ok: true,
-        processed: false,
-        reason: turn.active ? "active_turn_mismatch" : "missing_turn"
-      };
-    }
-    return markCodexAppServerTurnActive(normalizedSessionId, {
-      inputSource: inputSource || "terminal",
-      status: requestedStatus,
-      threadId: normalizedThreadId,
-      turnId: normalizedTurnId
-    });
-  }
-
-  async function recoverCodexAppServerFinalizingTurn(sessionId = "", threadId = "", turnId = "", {
-    status = "completed", timerRecovery = false
-  } = {}) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedThreadId = normalizeCodexRunText(threadId);
-    const normalizedTurnId = normalizeCodexRunText(turnId);
-    const key = codexAppServerResultFinalizationKey(normalizedSessionId, normalizedThreadId, normalizedTurnId);
-    const priorTimer = retainFinalizingTimer ? codexAppServerFinalizingTimers.get(key) : null;
-    if (!timerRecovery && priorTimer?.recovery) return priorTimer.recovery;
-    const runtime = await createRuntime();
-    const session = await runtime.getSession(normalizedSessionId);
-    const turn = turnState(session);
-    if (codexAppServerTurnOwnsActiveGoal(turn, normalizedThreadId)) {
-      clearCodexAppServerFinalizingTimer(
-        normalizedSessionId,
-        normalizedThreadId,
-        normalizedTurnId
-      );
-      return {
-        ok: true,
-        processed: false,
-        reason: "goal_continuation_pending"
-      };
-    }
-    const result = await finalizeCodexAppServerAssistantResult(
-      normalizedSessionId,
-      normalizedThreadId,
-      normalizedTurnId,
-      {
-        recoverFromProvider: true,
-        status
-      }
-    );
-    if (result?.processed) {
-      return result;
-    }
-    // A later failure owns the same first deadline, even when this successful
-    // history read was already in flight under the completion-based clock.
-    const currentTimer = codexAppServerFinalizingTimers.get(key);
-    if (currentTimer?.failureDetail) return result;
-    if (retainFinalizingTimer && priorTimer && !currentTimer) return result;
-    let graceTurn = turn;
-    if (finalizingGraceAfterHistoryRead) {
-      const readReturnedAt = new Date().toISOString();
-      const currentTurn = turnState(await runtime.getSession(normalizedSessionId));
-      const timer = codexAppServerFinalizingTimers.get(key);
-      if (timer?.failureDetail || (priorTimer && !timer)) return result;
-      if (currentTurn.state !== "finalizing" || currentTurn.threadId !== normalizedThreadId ||
-          currentTurn.turnId !== normalizedTurnId) {
-        clearCodexAppServerFinalizingTimer(normalizedSessionId, normalizedThreadId, normalizedTurnId);
-        return { ...result, reason: "stale_turn_state" };
-      }
-      if (codexAppServerTurnOwnsActiveGoal(currentTurn, normalizedThreadId)) {
-        clearCodexAppServerFinalizingTimer(normalizedSessionId, normalizedThreadId, normalizedTurnId);
-        return { ok: true, processed: false, reason: "goal_continuation_pending" };
-      }
-      if (!timerRecovery && timer?.recovery) return timer.recovery;
-      // This local clock never changes the native completion timestamp.
-      graceTurn = { ...currentTurn, completedAt: timer?.startedAt || readReturnedAt };
-    }
-    if (!codexAppServerFinalizingExpired(graceTurn)) {
-      scheduleCodexAppServerFinalizingRecovery(normalizedSessionId, normalizedThreadId, normalizedTurnId, {
-        completedAt: graceTurn.completedAt,
-        status,
-        updatedAt: graceTurn.updatedAt
-      });
-      return result;
-    }
-    return stopCodexAppServerTurnWithResultDeliveryFailure(
-      normalizedSessionId,
-      normalizedThreadId,
-      normalizedTurnId,
-      {
-        error: result?.error,
-        reason: result?.reason || "missing_assistant_text",
-        status
-      }
-    );
-  }
-
   async function recoverCodexAppServerActiveTurn(sessionId = "", {
     provider = null,
     retryOnError = true,
     runtime: suppliedRuntime = null,
     providerError = null
   } = {}) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
+    const normalizedSessionId = normalizeText(sessionId);
     if (!normalizedSessionId) {
       return null;
     }
     try {
       const runtime = suppliedRuntime || await createRuntime();
       const storedSession = await runtime.getSession(normalizedSessionId);
-      const abandonedClaim = await (recoverAdmission || recoverAbandonedCodexAppServerPromptClaim)(
+      const abandonedClaim = await recoverAdmission(
         runtime,
         storedSession,
         {
-          promptDeliveryActive: codexAppServerPromptDeliveries.has(
+          promptDeliveryActive: promptDeliveries.has(
             namespace(normalizedSessionId)
           )
         }
@@ -736,7 +346,7 @@ export function createCodexTurnRecovery({
         .then(() => createStore(normalizedSessionId))
         .catch(() => null);
       const run = store
-        ? await readCodexAppServerAgentRunForSession(store, normalizedSessionId).catch(() => null)
+        ? await output.readAgentRunForSession(store, normalizedSessionId).catch(() => null)
         : null;
       if (turnStateFromAgentRun(run || {}).state === "starting") {
         scheduleCodexAppServerActiveRecovery(normalizedSessionId);
@@ -745,376 +355,15 @@ export function createCodexTurnRecovery({
     }
   }
 
-  async function completeCodexAppServerTurn(sessionId = "", threadId = "", turnId = "", {
-    provider = null,
-    status = "completed",
-    verifyInactive = true
-  } = {}) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedThreadId = normalizeCodexRunText(threadId);
-    const normalizedTurnId = normalizeCodexRunText(turnId);
-    const normalizedStatus = normalizeCodexRunText(status) || "completed";
-    const runtime = await createRuntime();
-    const session = await runtime.getSession(normalizedSessionId);
-    const existingTurn = turnState(session);
-    const continuesOwnedGoal = codexAppServerTurnOwnsActiveGoal(
-      existingTurn,
-      normalizedThreadId
-    );
-    if (codexAppServerTurnAwaitsProviderIdentity(existingTurn, normalizedThreadId, normalizedTurnId)) {
-      return {
-        ok: true,
-        processed: false,
-        reason: "turn_identity_pending"
-      };
-    }
-    if (!normalizedTurnId) {
-      if (!codexAppServerTurnCanReceiveProviderCompletion(existingTurn, normalizedThreadId, "")) {
-        cleanupCodexAppServerUntrackedTurn(normalizedThreadId, normalizedTurnId);
-        debugLog("appServerTurn.complete.stale", {
-          currentState: existingTurn.state,
-          currentStatus: existingTurn.status,
-          currentThreadId: existingTurn.threadId,
-          currentTurnId: existingTurn.turnId,
-          sessionId: normalizedSessionId,
-          status: normalizedStatus,
-          threadId: normalizedThreadId,
-          turnId: normalizedTurnId
-        });
-        return {
-          ok: true,
-          processed: false,
-          reason: "stale_turn_state"
-        };
-      }
-      if (verifyInactive && await codexAppServerProviderBlocksTurnRelease(normalizedSessionId, provider, normalizedThreadId, normalizedTurnId, {
-        source: "complete_missing_turn"
-      })) {
-        return {
-          ok: true,
-          processed: false,
-          reason: "provider_still_active",
-          status: "inProgress"
-        };
-      }
-      await markCodexAppServerTurnIdle(normalizedSessionId, {
-        status: normalizedStatus,
-        threadId: normalizedThreadId,
-        turnId: normalizedTurnId
-      });
-      return {
-        ok: true,
-        processed: false,
-        reason: "missing_turn"
-      };
-    }
-    if (!codexAppServerTurnCanReceiveProviderCompletion(existingTurn, normalizedThreadId, normalizedTurnId)) {
-      codexAppServerFinalizedTurns.add(codexAppServerResultFinalizationKey(
-        normalizedSessionId,
-        normalizedThreadId,
-        normalizedTurnId
-      ));
-      cleanupCodexAppServerUntrackedTurn(normalizedThreadId, normalizedTurnId);
-      debugLog("appServerTurn.complete.stale", {
-        currentState: existingTurn.state,
-        currentStatus: existingTurn.status,
-        currentThreadId: existingTurn.threadId,
-        currentTurnId: existingTurn.turnId,
-        sessionId: normalizedSessionId,
-        status: normalizedStatus,
-        threadId: normalizedThreadId,
-        turnId: normalizedTurnId
-      });
-      return {
-        ok: true,
-        processed: false,
-        reason: "stale_turn_state"
-      };
-    }
-    if (verifyInactive && await codexAppServerProviderBlocksTurnRelease(normalizedSessionId, provider, normalizedThreadId, normalizedTurnId, {
-      source: "complete"
-    })) {
-      return {
-        ok: true,
-        processed: false,
-        reason: "provider_still_active",
-        status: "inProgress"
-      };
-    }
-    if (codexAppServerRunInputSource(codexAppServerAgentRun(session)) === "terminal") {
-      codexAppServerCompletedTurns.add(codexAppServerTurnKey(normalizedThreadId, normalizedTurnId));
-      cleanupCodexAppServerUntrackedTurn(normalizedThreadId, normalizedTurnId);
-      await markCodexAppServerTurnIdle(normalizedSessionId, {
-        status: normalizedStatus,
-        threadId: normalizedThreadId,
-        turnId: normalizedTurnId
-      });
-      return {
-        ok: true,
-        processed: true,
-        reason: "terminal_turn_completed"
-      };
-    }
-    const alreadyFinalizing = existingTurn.state === "finalizing" &&
-      existingTurn.threadId === normalizedThreadId &&
-      existingTurn.turnId === normalizedTurnId;
-    codexAppServerCompletedTurns.add(codexAppServerTurnKey(normalizedThreadId, normalizedTurnId));
-    if (!alreadyFinalizing) {
-      await markCodexAppServerTurnFinalizing(normalizedSessionId, {
-        status: normalizedStatus,
-        threadId: normalizedThreadId,
-        turnId: normalizedTurnId
-      });
-    }
-    if (continuesOwnedGoal) {
-      // Keep the outer chat turn active so the next provider turn can adopt
-      // its chat ownership without exposing this internal final as an answer.
-      clearCodexAppServerFinalizingTimer(
-        normalizedSessionId,
-        normalizedThreadId,
-        normalizedTurnId
-      );
-      return {
-        ok: true,
-        processed: true,
-        reason: "goal_continuation_pending"
-      };
-    }
-    return recoverCodexAppServerFinalizingTurn(
-      normalizedSessionId,
-      normalizedThreadId,
-      normalizedTurnId,
-      {
-        status: normalizedStatus
-      }
-    );
-  }
-
-  function codexAppServerStoppedTurnMessage(status = "", error = "", outcome = "") {
-    const normalizedStatus = normalizeCodexRunText(status);
-    let base = "Codex app-server failed before completing this turn.";
-    if (normalizedStatus === "interrupted") {
-      base = outcome === turnOutcomes.CONTROL_RECONFIGURATION
-        ? "Codex app-server was interrupted while its controls were restored."
-        : "Codex app-server was interrupted before completing this turn.";
-    }
-    const normalizedError = normalizeCodexRunText(error);
-    return normalizedError ? `${base} ${normalizedError}` : base;
-  }
-
-  async function stopCodexAppServerTurnWithProviderFailure(sessionId = "", threadId = "", turnId = "", {
-    error = "",
-    ok = false,
-    outcome = "",
-    provider = null,
-    status = "failed",
-    usageLimitExceeded = false,
-    verifyInactive = true,
-    deferFailureDetails = false,
-    failureDetailReady = false
-  } = {}) {
-    const observedAt = Date.now();
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedThreadId = normalizeCodexRunText(threadId);
-    const normalizedTurnId = normalizeCodexRunText(turnId);
-    const normalizedStatus = normalizeCodexRunText(status) || "failed";
-    let resolvedOutcome = normalizeCodexRunText(outcome);
-    if (!resolvedOutcome) {
-      if (normalizedStatus === "interrupted") {
-        const recorded = provider?.interruptionOutcome?.(normalizedThreadId, normalizedTurnId);
-        resolvedOutcome = [turnOutcomes.USER_CANCELLED, turnOutcomes.CONTROL_RECONFIGURATION].includes(recorded)
-          ? recorded : turnOutcomes.INTERRUPTED;
-      } else {
-        resolvedOutcome = turnOutcomes.PROVIDER_FAILURE;
-      }
-    }
-    const runtime = await createRuntime();
-    const staleFailure = async () => {
-      const turn = turnState(await runtime.getSession(normalizedSessionId));
-      if (codexAppServerTurnCanReceiveProviderCompletion(turn, normalizedThreadId, normalizedTurnId)) {
-        return null;
-      }
-      debugLog("appServerTurn.failure.stale", {
-        currentState: turn.state,
-        currentStatus: turn.status,
-        currentThreadId: turn.threadId,
-        currentTurnId: turn.turnId,
-        sessionId: normalizedSessionId,
-        status: normalizedStatus,
-        threadId: normalizedThreadId,
-        turnId: normalizedTurnId
-      });
-      return {
-        ok: true,
-        processed: false,
-        reason: "stale_turn_state"
-      };
-    };
-    const staleBeforeRecovery = await staleFailure();
-    if (staleBeforeRecovery) {
-      return staleBeforeRecovery;
-    }
-    const key = codexAppServerResultFinalizationKey(normalizedSessionId, normalizedThreadId, normalizedTurnId);
-    const pendingTimer = codexAppServerFinalizingTimers.get(key);
-    const pendingDetail = pendingTimer?.failureDetail;
-    if (failureDetailGraceMs > 0 && !failureDetailReady && (deferFailureDetails || pendingDetail) &&
-        ![turnOutcomes.USER_CANCELLED, turnOutcomes.CONTROL_RECONFIGURATION].includes(resolvedOutcome)) {
-      if (!pendingDetail) {
-        scheduleCodexAppServerFinalizingRecovery(normalizedSessionId, normalizedThreadId, normalizedTurnId, {
-          failureDetail: { error, ok, outcome: resolvedOutcome, provider, status: normalizedStatus,
-            usageLimitExceeded, verifyInactive,
-            expiresAt: Math.min(observedAt + failureDetailGraceMs,
-              pendingTimer?.expiresAt ?? Infinity) }
-        });
-      }
-      return { ok: true, processed: false, reason: "failure_detail_pending", status: normalizedStatus };
-    }
-    if (resolvedOutcome === turnOutcomes.PROVIDER_FAILURE) {
-      // Saved output is still useful, but cannot turn a known provider failure
-      // into successful completion. Persist it without settling the turn;
-      // the failure notice and checkpoint below own the terminal outcome.
-      await submitCodexAppServerAssistantResult(normalizedSessionId, normalizedThreadId, normalizedTurnId, {
-        recoverFromProvider: true
-      });
-    } else {
-      const recovered = await recoverCodexAppServerFinalResponseBeforeOutcome(
-        normalizedSessionId,
-        normalizedThreadId,
-        normalizedTurnId,
-        normalizedStatus
-      );
-      if (recovered?.processed) {
-        return recovered;
-      }
-    }
-    // History recovery awaited the provider. Confirm ownership and activity
-    // again before publishing a failure: a successor, Stop or goal
-    // continuation may own the run after that gap.
-    const staleAfterRecovery = await staleFailure();
-    if (staleAfterRecovery) {
-      return staleAfterRecovery;
-    }
-    if (verifyInactive && await codexAppServerProviderBlocksTurnRelease(normalizedSessionId, provider, normalizedThreadId, normalizedTurnId, {
-      source: "provider_failure"
-    })) {
-      return {
-        ok: true,
-        processed: false,
-        reason: "provider_still_active",
-        status: "inProgress"
-      };
-    }
-    const message = codexAppServerStoppedTurnMessage(normalizedStatus, error, resolvedOutcome);
-    await outcomeNotice(
-      runtime,
-      normalizedSessionId,
-      normalizedThreadId,
-      normalizedTurnId,
-      resolvedOutcome,
-      error,
-      { usageLimitExceeded }
-    );
-    await markCodexAppServerTurnIdle(normalizedSessionId, {
-      error: message,
-      status: normalizedStatus,
-      threadId: normalizedThreadId,
-      turnId: normalizedTurnId,
-      turnOutcome: resolvedOutcome
-    });
-    cleanupCodexAppServerUntrackedTurn(normalizedThreadId, normalizedTurnId);
-    return {
-      ok,
-      error: message,
-      status: normalizedStatus
-    };
-  }
-
-  async function stopCodexAppServerTurnWithResultDeliveryFailure(sessionId = "", threadId = "", turnId = "", {
-    error = "",
-    reason = "",
-    status = "completed"
-  } = {}) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedThreadId = normalizeCodexRunText(threadId);
-    const normalizedStatus = normalizeCodexRunText(status) || "completed";
-    const normalizedTurnId = await resolveCodexAppServerTurnId(normalizedSessionId, normalizedThreadId, turnId);
-    const recovered = await recoverCodexAppServerFinalResponseBeforeOutcome(
-      normalizedSessionId,
-      normalizedThreadId,
-      normalizedTurnId,
-      normalizedStatus
-    );
-    if (recovered?.processed) {
-      return recovered;
-    }
-    // The history read can outlive this turn: a successor or Stop may own the
-    // run by now, so the outcome is decided against the run read after it.
-    const runtime = await createRuntime();
-    const currentTurn = turnState(await runtime.getSession(normalizedSessionId));
-    if (!codexAppServerTurnCanReceiveProviderCompletion(currentTurn, normalizedThreadId, normalizedTurnId)) {
-      codexAppServerFinalizedTurns.add(codexAppServerResultFinalizationKey(
-        normalizedSessionId,
-        normalizedThreadId,
-        normalizedTurnId
-      ));
-      cleanupCodexAppServerUntrackedTurn(normalizedThreadId, normalizedTurnId);
-      debugLog("appServerAgentResult.missing.stale", {
-        currentState: currentTurn.state,
-        currentStatus: currentTurn.status,
-        currentThreadId: currentTurn.threadId,
-        currentTurnId: currentTurn.turnId,
-        reason: normalizeCodexRunText(reason),
-        sessionId: normalizedSessionId,
-        status: normalizedStatus,
-        threadId: normalizedThreadId,
-        turnId: normalizedTurnId
-      });
-      return {
-        ok: true,
-        processed: false,
-        reason: "stale_turn_state",
-        status: currentTurn.status
-      };
-    }
-    const message = resultDeliveryFailureMessage({
-      error
-    });
-    await outcomeNotice(
-      runtime,
-      normalizedSessionId,
-      normalizedThreadId,
-      normalizedTurnId,
-      turnOutcomes.RESPONSE_DELIVERY_FAILURE
-    );
-    await markCodexAppServerTurnIdle(normalizedSessionId, {
-      error: message,
-      status: normalizedStatus,
-      threadId: normalizedThreadId,
-      turnId: normalizedTurnId,
-      turnOutcome: turnOutcomes.RESPONSE_DELIVERY_FAILURE
-    });
-    cleanupCodexAppServerUntrackedTurn(normalizedThreadId, normalizedTurnId);
-    debugLog("appServerAgentResult.missing", {
-      error: normalizeCodexRunText(error),
-      reason: normalizeCodexRunText(reason),
-      sessionId: normalizedSessionId,
-      threadId: normalizedThreadId,
-      turnId: normalizedTurnId
-    });
-    return {
-      ok: false,
-      error: message,
-      status: normalizedStatus
-    };
-  }
-
-  return {
+  return Object.freeze({
     scheduleActiveRecovery: scheduleCodexAppServerActiveRecovery,
-    markTurnActive: markCodexAppServerTurnActive,
-    markProviderTurnActive: markCodexAppServerProviderTurnActive,
-    recoverFinalizingTurn: recoverCodexAppServerFinalizingTurn,
+    markTurnActive: activity.markTurnActive,
+    markProviderTurnActive: activity.markProviderTurnActive,
+    recoverFinalizingTurn: endings.recoverFinalizingTurn,
     recoverActiveTurn: recoverCodexAppServerActiveTurn,
-    completeTurn: completeCodexAppServerTurn,
-    stopTurnWithProviderFailure: stopCodexAppServerTurnWithProviderFailure
-  };
+    completeTurn: endings.completeTurn,
+    stopTurnWithProviderFailure: endings.stopTurnWithProviderFailure
+  });
 }
+
+/** @typedef {ReturnType<typeof createCodexTurnRecovery>} CodexTurnRecovery */