@jskit-ai/assistant-core 0.2.7 → 0.2.9

package/src/server/conversation/codexThreadReadiness.js

@@ -1,14 +1,21 @@
-import {
-  codexAppServerTurnStatusIsActive,
-  codexAppServerThreadStatus,
-  codexAppServerReadThreadStatus,
-  normalizeCodexRunText
-} from "./codexTurnState.js";
-import { codexAppServerThreadIsMissing, ensureCodexAppServerThread } from "./codexProvider.js";
-import { codexAppServerThreadRawValue, codexAppServerThreadTurnId } from "./codexEvents.js";
+import { codexAppServerTurnStatusIsActive, codexAppServerThreadStatus, codexAppServerReadThreadStatus } from "./codexTurnState.js";
+import { codexAppServerThreadIsMissing, ensureCodexAppServerThread } from "./codexProviderThreads.js";
+import { codexAppServerThreadRawValue, codexAppServerThreadTurnId } from "./codexThreadSnapshot.js";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 
-// Native thread readiness, loaded-thread restoration and reconciliation drain.
-// Its one Map lives as long as the run owner and is shared with shutdown.
+/**
+ * Native thread readiness, loaded-thread restoration and reconciliation drain. Its one Map lives as long as the run
+ * owner and is shared with shutdown.
+ * @param {object} dependencies
+ * @param {import("./codexTurn.js").CodexProviderSessions} [dependencies.providerSessions]
+ * @param {import("./codexProviderSelection.js").CodexProviderSelection} dependencies.selection
+ * @param {import("./codexNotificationObserver.js").CodexNotificationObserver} dependencies.observer
+ * @param {import("./codexThreadStatus.js").CodexThreadStatus} dependencies.threadStatus
+ * @param {import("./codexTurnRecovery.js").CodexTurnRecovery} dependencies.recovery
+ * @param {import("./codexTurn.js").CodexTurnStateReader} dependencies.turnState
+ * @param {import("./codexTurn.js").CodexDebugLog} dependencies.debugLog
+ * @param {import("./codexTurn.js").CodexDebugError} dependencies.debugError
+ */
 export function createCodexThreadReadiness({
   providerSessions,
   selection,
@@ -27,23 +34,11 @@ export function createCodexThreadReadiness({
     ensureSessionProvider,
     rememberManagedSession
   } = selection;
-  const {
-    eventSubscriptionKey: codexAppServerEventSubscriptionKey,
-    eventSubscriptionIsCurrent: codexAppServerEventSubscriptionIsCurrent,
-    subscribeEvents: subscribeCodexAppServerEvents
-  } = observer;
-  const {
-    reconcileThreadStatus: reconcileCodexAppServerThreadStatus,
-    reconcileLoadedThreadStatus: reconcileCodexAppServerLoadedThreadStatus
-  } = threadStatus;
-  const {
-    recoverActiveTurn: recoverCodexAppServerActiveTurn
-  } = recovery;
 
   async function ensureCodexAppServerThreadReady(sessionId, context, preparation) {
     const { runtime, session, workdir } = context;
     // Runtime recovery may await a disconnect callback that writes session
-    // state. This acquisition stays outside the original startup gate.
+    // state. This acquisition stays outside the startup gate.
     const activeProvider = await ensureCodexAppServerProviderForActiveTurn(session, preparation.managedIdentity);
     let providerOptions = activeProvider?.providerOptions;
     if (!providerOptions) {
@@ -54,19 +49,19 @@ export function createCodexThreadReadiness({
     const { currentSession: preparedSession, thread } = await preparation.gate(async currentSession => {
       const thread = await ensureCodexAppServerThread({
         ...preparation.preparation(currentSession),
-        observeThread: threadId => subscribeCodexAppServerEvents(sessionId, provider, threadId,
+        observeThread: threadId => observer.subscribeEvents(sessionId, provider, threadId,
           codexAppServerSessionObserverOptions(sessionId, providerOptions)),
         provider,
         workdir
       });
       return { currentSession, thread };
     });
-    subscribeCodexAppServerEvents(sessionId, provider, thread.threadId,
+    observer.subscribeEvents(sessionId, provider, thread.threadId,
       codexAppServerSessionObserverOptions(sessionId, providerOptions));
     rememberManagedSession(sessionId, providerOptions, {
       executionRoot: context.executionRoot, workdir: context.workdir, threadId: thread.threadId
     });
-    await reconcileCodexAppServerThreadStatus(sessionId, provider, thread.threadId, {
+    await threadStatus.reconcileThreadStatus(sessionId, provider, thread.threadId, {
       failUnconfirmedTrackedTurn: true,
       observeLatestTurn: true,
       requireTrackedTurn: true,
@@ -75,7 +70,7 @@ export function createCodexThreadReadiness({
     const ready = await preparation.ready(preparedSession);
     let currentSession = await runtime.getSession(sessionId);
     if (turnState(currentSession).state === "starting") {
-      currentSession = await recoverCodexAppServerActiveTurn(sessionId, {
+      currentSession = await recovery.recoverActiveTurn(sessionId, {
         provider,
         retryOnError: false,
         runtime
@@ -153,12 +148,12 @@ export function createCodexThreadReadiness({
     }
     debugLog("appServerThread.reconcile.pruneWait.start", {
       pendingCount: pending.length,
-      projectContextRoot: normalizeCodexRunText(projectContextRoot)
+      projectContextRoot: normalizeText(projectContextRoot)
     });
     await Promise.allSettled(pending.map(([, reconciliation]) => reconciliation));
     debugLog("appServerThread.reconcile.pruneWait.done", {
       pendingCount: pending.length,
-      projectContextRoot: normalizeCodexRunText(projectContextRoot)
+      projectContextRoot: normalizeText(projectContextRoot)
     });
   }
 
@@ -166,11 +161,11 @@ export function createCodexThreadReadiness({
     reconnect = true
   } = {}) {
     providerSessions.assertOpen();
-    const normalizedProviderKey = normalizeCodexRunText(providerKey);
+    const normalizedProviderKey = normalizeText(providerKey);
     const managed = providerSessions.managed.get(normalizedProviderKey);
     const provider = providerSessions.owner.providers.get(normalizedProviderKey);
-    const sessionId = normalizeCodexRunText(managed?.sessionId);
-    const threadId = normalizeCodexRunText(managed?.threadId);
+    const sessionId = normalizeText(managed?.sessionId);
+    const threadId = normalizeText(managed?.threadId);
     if (!managed || !provider || !sessionId) {
       throw new Error("Codex app-server managed connection is incomplete.");
     }
@@ -186,7 +181,7 @@ export function createCodexThreadReadiness({
 
     if (reconnect) {
       await providerSessions.owner.acquireRuntime({
-        operation: () => provider.ensureAvailable?.(),
+        operation: () => provider.ensureAvailable(),
         provider,
         providerKey: normalizedProviderKey,
         providerOptions: managed.providerOptions || {}
@@ -220,38 +215,38 @@ export function createCodexThreadReadiness({
     const session = await current.readSession();
     current.assertCurrent(session);
     try {
-      const controls = await provider.ensureThreadControls?.(threadId);
+      const controls = await provider.ensureThreadControls(threadId);
       if (controls?.recovered) providerThread = await codexAppServerReadThreadStatus(provider, threadId);
     } catch (error) {
       current.assertCurrent(session);
-      // Retain the existing stop owner and its visible recovery state. Do not
+      // The stop owner keeps its visible recovery state. This does not
       // spend automatic goal turns or repeatedly probe a known failed binding.
-      void Promise.resolve(provider.failObservation?.(error)).catch(() => null);
+      void Promise.resolve(provider.failObservation(error)).catch(() => null);
       throw error;
     }
     current.assertCurrent(session);
     const nativeStatus = codexAppServerThreadRawValue(providerThread).status;
-    const subscriptionKey = codexAppServerEventSubscriptionKey(
+    const subscriptionKey = observer.eventSubscriptionKey(
       providerKey,
       threadId
     );
-    const subscriptionIsCurrent = codexAppServerEventSubscriptionIsCurrent(subscriptionKey, provider);
+    const subscriptionIsCurrent = observer.eventSubscriptionIsCurrent(subscriptionKey, provider);
     if (!reconnect && (
       nativeStatus === "notLoaded" || nativeStatus?.type === "notLoaded" || !subscriptionIsCurrent
     )) {
       return { ok: true, requiresPreparation: true };
     }
     if (!subscriptionIsCurrent) {
-      subscribeCodexAppServerEvents(
+      observer.subscribeEvents(
         sessionId,
         provider,
         threadId,
         subscriptionOptions
       );
-      await provider.resumeThread?.(threadId, {
-        cwd: normalizeCodexRunText(connection.workdir)
+      await provider.resumeThread(threadId, {
+        cwd: normalizeText(connection.workdir)
       });
-      return reconcileCodexAppServerLoadedThreadStatus(
+      return threadStatus.reconcileLoadedThreadStatus(
         sessionId,
         provider,
         threadId,
@@ -277,7 +272,7 @@ export function createCodexThreadReadiness({
       )) ||
       (!providerIsActive && trackedTurn.active)
     ) {
-      return reconcileCodexAppServerThreadStatus(
+      return threadStatus.reconcileThreadStatus(
         sessionId,
         provider,
         threadId,
@@ -295,7 +290,7 @@ export function createCodexThreadReadiness({
   }
 
   async function codexAppServerLoadedThreadIds(provider = null) {
-    if (typeof provider?.listLoadedThreads !== "function") {
+    if (!provider) {
       return null;
     }
     const threadIds = new Set();
@@ -306,12 +301,12 @@ export function createCodexThreadReadiness({
         limit: 100
       });
       for (const threadId of Array.isArray(response?.data) ? response.data : []) {
-        const normalizedThreadId = normalizeCodexRunText(threadId);
+        const normalizedThreadId = normalizeText(threadId);
         if (normalizedThreadId) {
           threadIds.add(normalizedThreadId);
         }
       }
-      cursor = normalizeCodexRunText(response?.nextCursor);
+      cursor = normalizeText(response?.nextCursor);
     } while (cursor);
     return threadIds;
   }
@@ -320,18 +315,18 @@ export function createCodexThreadReadiness({
     const { runtime, provider, providerKey, threadId } = context;
     const loadedThreadIds = await codexAppServerLoadedThreadIds(provider);
     if (!loadedThreadIds?.has(threadId)) return null;
-    const subscription = subscribeCodexAppServerEvents(
+    const subscription = observer.subscribeEvents(
       sessionId,
       provider,
       threadId,
       context.subscriptionOptions
     );
-    const subscriptionStatus = normalizeCodexRunText(subscription?.status) || "subscribed";
+    const subscriptionStatus = normalizeText(subscription?.status) || "subscribed";
     if (subscriptionStatus !== "alreadySubscribed") {
       await provider.resumeThread(threadId, context.resumeOptions);
     }
     context.remember();
-    await reconcileCodexAppServerLoadedThreadStatus(
+    await threadStatus.reconcileLoadedThreadStatus(
       sessionId,
       provider,
       threadId,
@@ -347,7 +342,7 @@ export function createCodexThreadReadiness({
     });
     let loadedSession = await runtime.getSession(sessionId);
     if (turnState(loadedSession).state === "starting") {
-      loadedSession = await recoverCodexAppServerActiveTurn(sessionId, {
+      loadedSession = await recovery.recoverActiveTurn(sessionId, {
         provider,
         retryOnError: false,
         runtime
@@ -372,12 +367,14 @@ export function createCodexThreadReadiness({
     };
   }
 
-  return {
+  return Object.freeze({
     threadReconciliations: codexAppServerThreadReconciliations,
     ensureThreadReady: ensureCodexAppServerThreadReady,
     reconcileThread: reconcileCodexAppServerThreadForSession,
     waitForThreadReconciliations: waitForOtherCodexAppServerThreadReconciliations,
     checkManagedConnection,
     restoreLoadedThread: restoreCodexAppServerLoadedThread
-  };
+  });
 }
+
+/** @typedef {ReturnType<typeof createCodexThreadReadiness>} CodexThreadReadiness */

package/src/server/conversation/codexThreadSnapshot.js

@@ -0,0 +1,210 @@
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeNullableText } from "./normalize.js";
+import {
+  codexAppServerAssistantItemText,
+  codexAppServerErrorText,
+  codexAppServerSignedOutText,
+  codexAppServerStatusFromValue
+} from "./codexEvents.js";
+
+// Like codexAppServerThreadRawValue, but provider results may also wrap the
+// thread once more under `thread`, checked after raw and response.thread.
+function codexAppServerProviderThread(value) {
+  if (!isRecord(value?.raw) && !isRecord(value?.response?.thread) && isRecord(value?.thread)) {
+    return value.thread;
+  }
+  return codexAppServerThreadRawValue(value || {});
+}
+
+function codexAppServerProviderTurnId(turn = {}) {
+  return normalizeNullableText(turn.id || turn.turnId || turn.turn_id || turn.turn?.id || "");
+}
+
+function codexAppServerProviderTurnItems(turn = {}) {
+  return [
+    ...(Array.isArray(turn.items) ? turn.items : []),
+    ...(Array.isArray(turn.itemsView) ? turn.itemsView : [])
+  ].filter(isRecord);
+}
+
+function codexAppServerProviderThreadTurn(value = {}, turnId = "") {
+  const normalizedTurnId = normalizeNullableText(turnId);
+  if (!normalizedTurnId) {
+    return null;
+  }
+  const thread = codexAppServerProviderThread(value);
+  return (Array.isArray(thread.turns) ? thread.turns : [])
+    .find((turn) => codexAppServerProviderTurnId(turn) === normalizedTurnId) || null;
+}
+
+function codexAppServerProviderTurnAssistantSegments(turn = {}) {
+  const seenItemIds = new Set();
+  const items = codexAppServerProviderTurnItems(turn);
+  // Providers without phases emit progress as ordinary assistant messages.
+  // Only the trailing response can be a final; reasoning/tools separate it
+  // from earlier updates. Explicit finals retain their native attribution.
+  let responseStart = items.length;
+  while (responseStart > 0 && codexAppServerAssistantItemText(items[responseStart - 1])) responseStart -= 1;
+  const active = ["inProgress", "starting"].includes(codexAppServerStatusFromValue(turn.status));
+  return items
+    .filter((item, index) => {
+      const phase = normalizeNullableText(item.phase);
+      return phase === "final_answer" || (!phase && !active && index >= responseStart);
+    })
+    .map((item) => {
+      const itemId = normalizeNullableText(item.id);
+      const text = codexAppServerAssistantItemText(item);
+      if (
+        !itemId ||
+        !text ||
+        seenItemIds.has(itemId)
+      ) {
+        return null;
+      }
+      seenItemIds.add(itemId);
+      return {
+        itemId,
+        text
+      };
+    })
+    .filter(Boolean);
+}
+
+function codexAppServerProviderThreadAssistantSegments(value = {}, turnId = "") {
+  const turn = codexAppServerProviderThreadTurn(value, turnId);
+  return turn ? codexAppServerProviderTurnAssistantSegments(turn) : [];
+}
+
+function codexAppServerThreadRawValue(thread = {}) {
+  if (isRecord(thread.raw)) {
+    return thread.raw;
+  }
+  if (isRecord(thread.response?.thread)) {
+    return thread.response.thread;
+  }
+  return isRecord(thread) ? thread : {};
+}
+
+function codexAppServerThreadTurnId(thread = {}) {
+  const observedTurnId = normalizeNullableText(thread.observedTurn?.id || "");
+  if (observedTurnId) {
+    return observedTurnId;
+  }
+  const rawThread = codexAppServerThreadRawValue(thread);
+  const status = isRecord(rawThread.status) ? rawThread.status : {};
+  return normalizeNullableText(
+    thread.turnId ||
+    thread.turn_id ||
+    thread.turn?.id ||
+    rawThread.turnId ||
+    rawThread.turn_id ||
+    rawThread.turn?.id ||
+    rawThread.currentTurnId ||
+    rawThread.current_turn_id ||
+    rawThread.activeTurnId ||
+    rawThread.active_turn_id ||
+    status.turnId ||
+    status.turn_id ||
+    status.turn?.id ||
+    status.currentTurnId ||
+    status.current_turn_id ||
+    status.activeTurnId ||
+    status.active_turn_id ||
+    ""
+  );
+}
+
+function codexAppServerThreadError(thread = {}) {
+  const rawThread = codexAppServerThreadRawValue(thread);
+  const status = isRecord(rawThread.status) ? rawThread.status : {};
+  return codexAppServerErrorText(rawThread.error || status.error);
+}
+
+function codexAppServerProviderThreadTurns(thread = null) {
+  const rawThread = codexAppServerThreadRawValue(thread || {});
+  return (Array.isArray(rawThread.turns) ? rawThread.turns : [])
+    .filter((turn) => isRecord(turn));
+}
+
+function codexAppServerProviderTurnStatus(turn = {}) {
+  return codexAppServerStatusFromValue(turn.status || turn.state);
+}
+
+function codexAppServerProviderTurnClientIds(turn = {}) {
+  return codexAppServerProviderTurnItems(turn)
+    .map((item) => normalizeNullableText(
+      item.clientId ||
+      item.client_id ||
+      item.clientUserMessageId ||
+      item.client_user_message_id ||
+      ""
+    ))
+    .filter(Boolean);
+}
+
+function codexAppServerProviderTurnForOperation(thread = null, {
+  clientMessageId = "",
+  turnId = ""
+} = {}) {
+  const normalizedTurnId = normalizeNullableText(turnId || "");
+  const normalizedClientMessageId = normalizeNullableText(clientMessageId || "");
+  const turns = codexAppServerProviderThreadTurns(thread);
+  if (normalizedTurnId) {
+    return turns.find((turn) => (
+      codexAppServerProviderTurnId(turn) === normalizedTurnId
+    )) || null;
+  }
+  if (!normalizedClientMessageId) {
+    return null;
+  }
+  return [...turns].reverse().find((turn) => (
+    codexAppServerProviderTurnClientIds(turn).includes(normalizedClientMessageId)
+  )) || null;
+}
+
+// Native snapshot matching for renewal handover and seeding.
+// The application projects these classifications into its approval/error policy.
+function inspectCodexAppServerRenewalThread(thread = null, {
+  clientMessageId = "",
+  turnId: expectedTurnId = "",
+  requireFresh = false
+} = {}) {
+  const snapshotTurns = codexAppServerProviderThreadTurns(thread);
+  const targetTurn = codexAppServerProviderTurnForOperation(thread, {
+    clientMessageId,
+    turnId: expectedTurnId
+  });
+  if (expectedTurnId && !targetTurn) return { targetTurn, failure: "turn_missing" };
+  if (!requireFresh && !targetTurn && snapshotTurns.length === 0) return { targetTurn, failure: "history_missing" };
+  if (requireFresh && snapshotTurns.some((turn) => (
+    !targetTurn || codexAppServerProviderTurnId(turn) !== codexAppServerProviderTurnId(targetTurn)
+  ))) return { targetTurn, failure: "unrelated_history" };
+  return { targetTurn, failure: "" };
+}
+
+function codexAppServerProviderTurnText(thread = null, turnId = "") {
+  return codexAppServerProviderThreadAssistantSegments(thread || {}, turnId)
+    .map((segment) => segment.text)
+    .join("\n\n")
+    .trim();
+}
+
+function codexAppServerProviderTurnError(turn = {}) {
+  return codexAppServerSignedOutText(codexAppServerErrorText(turn.error || turn.status?.error || turn.state?.error));
+}
+
+export {
+  codexAppServerThreadRawValue,
+  codexAppServerThreadTurnId,
+  codexAppServerThreadError,
+  codexAppServerProviderThreadTurns,
+  codexAppServerProviderTurnId,
+  codexAppServerProviderTurnStatus,
+  codexAppServerProviderTurnItems,
+  codexAppServerProviderTurnClientIds,
+  codexAppServerProviderTurnForOperation,
+  inspectCodexAppServerRenewalThread,
+  codexAppServerProviderTurnText,
+  codexAppServerProviderTurnError,
+  codexAppServerProviderThreadAssistantSegments
+};