@jskit-ai/assistant-core 0.2.7 → 0.2.8

package/src/server/conversation/codexNotificationObserver.js

@@ -1,12 +1,4 @@
-import {
-  codexAppServerTurnStatusIsActive,
-  codexAppServerTurnStatusIsSuccessfulComplete,
-  codexAppServerTurnStatusIsProviderFailure,
-  normalizeCodexRunText,
-  CODEX_APP_SERVER_AGENT_RUN_ID,
-  CODEX_AGENT_PROVIDER,
-  CODEX_APP_SERVER_RUN_STATE
-} from "./codexTurnState.js";
+import { codexAppServerTurnStatusIsActive, codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, CODEX_APP_SERVER_AGENT_RUN_ID, CODEX_AGENT_PROVIDER, CODEX_APP_SERVER_RUN_STATE } from "./codexTurnState.js";
 import { codexAppServerProviderConnectionGeneration } from "./codexModelCatalog.js";
 import {
   codexAppServerAssistantItemText,
@@ -23,9 +15,27 @@ import {
   codexAppServerContextRefreshReason,
   codexAppServerNotificationUsageLimitExceeded
 } from "./codexEvents.js";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 
-// Native notification routing, goal updates and provider-generation subscriptions.
-// Ordering belongs to the notification queue; state belongs to the operation owners.
+/**
+ * Native notification routing, goal updates and provider-generation subscriptions. Ordering belongs to the
+ * notification queue; state belongs to the operation owners.
+ * @param {object} dependencies
+ * @param {import("./codexRunJournal.js").CodexRunJournal} dependencies.journal
+ * @param {import("./codexTurnRecovery.js").CodexTurnRecovery} dependencies.recovery
+ * @param {import("./codexThreadStatus.js").CodexThreadStatus} dependencies.threadStatus
+ * @param {import("./codexOutput.js").CodexAppServerOutput} dependencies.output
+ * @param {import("./codexMessageDelivery.js").CodexAppServerMessageDelivery} dependencies.delivery
+ * @param {import("./codexNotificationQueue.js").CodexAppServerNotificationQueue} dependencies.notificationQueue
+ * @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 {import("./codexTurn.js").CodexCaptureContext} dependencies.captureContext
+ * @param {import("./codexTurn.js").CodexDebugLog} dependencies.debugLog
+ * @param {(kind: string, details: object) => Promise<unknown>} dependencies.onNotificationSignal
+ * @param {import("./codexTurn.js").CodexAgentRunTurnStateReader} dependencies.turnStateFromAgentRun
+ */
 export function createCodexNotificationObserver({
   journal,
   recovery,
@@ -42,25 +52,6 @@ export function createCodexNotificationObserver({
   onNotificationSignal,
   turnStateFromAgentRun
 }) {
-  const { resolveTurnId: resolveCodexAppServerTurnId } = journal;
-  const {
-    recoverFinalizingTurn: recoverCodexAppServerFinalizingTurn,
-    markTurnActive: markCodexAppServerTurnActive,
-    markProviderTurnActive: markCodexAppServerProviderTurnActive,
-    stopTurnWithProviderFailure: stopCodexAppServerTurnWithProviderFailure,
-    completeTurn: completeCodexAppServerTurn
-  } = recovery;
-  const { reconcileThreadStatus: reconcileCodexAppServerThreadStatus } = threadStatus;
-  const {
-    readAgentRunForSession: readCodexAppServerAgentRunForSession,
-    recordReasoningForSession: recordCodexAppServerReasoningForSession,
-    writeStream: writeCodexAppServerStream,
-    recordFinalAssistantResult: recordCodexAppServerFinalAssistantResult,
-    writeLiveProgress: writeCodexAppServerLiveProgress,
-    mirrorTerminalAssistantMessage: mirrorCodexAppServerTerminalAssistantMessage
-  } = output;
-  const { mirrorTerminalUserMessage: mirrorCodexAppServerTerminalUserMessage } = delivery;
-  const { run: runCodexAppServerNotificationTask } = notificationQueue;
   const CODEX_APP_SERVER_GOAL_STATUSES = new Set([
     "active", "blocked", "budgetLimited", "complete", "paused", "usageLimited"
   ]);
@@ -68,7 +59,7 @@ export function createCodexNotificationObserver({
   const codexAppServerAutomaticHookThreads = new Set();
 
   function codexAppServerEventSubscriptionKey(providerKey = "", threadId = "") {
-    return `${normalizeCodexRunText(providerKey)}:${normalizeCodexRunText(threadId)}`;
+    return `${normalizeText(providerKey)}:${normalizeText(threadId)}`;
   }
 
   function codexAppServerEventSubscriptionIsCurrent(key = "", provider = null) {
@@ -82,16 +73,16 @@ export function createCodexNotificationObserver({
 
   function unsubscribeCodexAppServerEventSubscription(key = "") {
     const record = codexAppServerEventSubscriptions.get(key);
-    record?.unsubscribe?.();
+    record?.unsubscribe();
     codexAppServerEventSubscriptions.delete(key);
   }
 
   function queueCodexAppServerReasoning(context, notification) {
-    return notificationQueue.reasoning(context, notification, recordCodexAppServerReasoningForSession);
+    return notificationQueue.reasoning(context, notification, output.recordReasoningForSession);
   }
 
   function queueCodexAppServerStream(context, classification) {
-    return notificationQueue.stream(context, classification, writeCodexAppServerStream);
+    return notificationQueue.stream(context, classification, output.writeStream);
   }
 
   async function reconcileCodexAppServerGoalUpdated(
@@ -100,26 +91,26 @@ export function createCodexNotificationObserver({
     threadId = "",
     notification = {}
   ) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedThreadId = normalizeCodexRunText(threadId);
+    const normalizedSessionId = normalizeText(sessionId);
+    const normalizedThreadId = normalizeText(threadId);
     const notificationTurnId = codexAppServerNotificationTurnId(notification);
-    const goalStatus = normalizeCodexRunText(notification.params?.goal?.status);
+    const goalStatus = normalizeText(notification.params?.goal?.status);
     const goalCleared = notification.method === "thread/goal/cleared";
     const runtime = await createRuntime();
-    let run = await readCodexAppServerAgentRunForSession(
+    let run = await output.readAgentRunForSession(
       runtime.store,
       normalizedSessionId
     );
     if (run?.providerStatus === "observation_lost") return { ok: true, processed: false, reason: "observation_lost" };
-    const currentThreadId = normalizeCodexRunText(run?.providerThreadId);
+    const currentThreadId = normalizeText(run?.providerThreadId);
     if (currentThreadId && currentThreadId !== normalizedThreadId) {
       return { ok: true, processed: false, reason: "goal_thread_changed" };
     }
     if (
       (goalCleared || CODEX_APP_SERVER_GOAL_STATUSES.has(goalStatus)) &&
       (
-        normalizeCodexRunText(run?.providerGoalStatus) !== goalStatus ||
-        normalizeCodexRunText(run?.providerGoalThreadId) !== normalizedThreadId
+        normalizeText(run?.providerGoalStatus) !== goalStatus ||
+        normalizeText(run?.providerGoalThreadId) !== normalizedThreadId
       )
     ) {
       const updatedAt = new Date().toISOString();
@@ -142,7 +133,7 @@ export function createCodexNotificationObserver({
           providerGoalUpdatedAt: updatedAt
         }
       });
-      run = await readCodexAppServerAgentRunForSession(
+      run = await output.readAgentRunForSession(
         runtime.store,
         normalizedSessionId
       );
@@ -169,7 +160,7 @@ export function createCodexNotificationObserver({
       turn.threadId === normalizedThreadId &&
       (!notificationTurnId || turn.turnId === notificationTurnId)
     ) {
-      return recoverCodexAppServerFinalizingTurn(
+      return recovery.recoverFinalizingTurn(
         normalizedSessionId,
         normalizedThreadId,
         turn.turnId,
@@ -178,7 +169,7 @@ export function createCodexNotificationObserver({
         }
       );
     }
-    return reconcileCodexAppServerThreadStatus(
+    return threadStatus.reconcileThreadStatus(
       normalizedSessionId,
       provider,
       normalizedThreadId,
@@ -190,14 +181,14 @@ export function createCodexNotificationObserver({
   }
 
   function subscribeCodexAppServerEvents(sessionId = "", provider = null, threadId = "", options = {}) {
-    const normalizedSessionId = normalizeCodexRunText(sessionId);
-    const normalizedThreadId = normalizeCodexRunText(threadId);
-    if (!normalizedSessionId || !normalizedThreadId || typeof provider?.subscribe !== "function") {
+    const normalizedSessionId = normalizeText(sessionId);
+    const normalizedThreadId = normalizeText(threadId);
+    if (!normalizedSessionId || !normalizedThreadId || !provider) {
       throw new Error("Codex thread observation requires a session, thread and provider subscription.");
     }
     const projectContext = captureContext();
     const sessionKey = namespace(normalizedSessionId);
-    const providerKey = normalizeCodexRunText(options.providerKey);
+    const providerKey = normalizeText(options.providerKey);
     const key = codexAppServerEventSubscriptionKey(providerKey, normalizedThreadId);
     const existing = codexAppServerEventSubscriptions.get(key);
     if (existing && codexAppServerEventSubscriptionIsCurrent(key, provider)) {
@@ -211,27 +202,27 @@ export function createCodexNotificationObserver({
     }
     // A new observer cannot confirm a previously active phase. Fresh native
     // events restore it; a stored phase alone must not animate activity.
-    runCodexAppServerNotificationTask({ projectContext, provider, sessionId: normalizedSessionId, sessionKey }, async () => {
+    notificationQueue.run({ projectContext, provider, sessionId: normalizedSessionId, sessionKey }, async () => {
       const store = await createStore(normalizedSessionId);
-      const run = await readCodexAppServerAgentRunForSession(store, normalizedSessionId);
+      const run = await output.readAgentRunForSession(store, normalizedSessionId);
       if (!run?.providerPhase || run.providerThreadId !== normalizedThreadId) return;
-      await markCodexAppServerTurnActive(normalizedSessionId, {
+      await recovery.markTurnActive(normalizedSessionId, {
         phase: "", requireTrackedTurn: true,
         threadId: normalizedThreadId, turnId: run.providerTurnId
       });
     });
     const onNotification = (notification = {}) => {
-      const runProviderFailure = (context, turnId, status) => runCodexAppServerNotificationTask(context, () =>
-        stopCodexAppServerTurnWithProviderFailure(normalizedSessionId, normalizedThreadId, turnId, {
+      const runProviderFailure = (context, turnId, status) => notificationQueue.run(context, () =>
+        recovery.stopTurnWithProviderFailure(normalizedSessionId, normalizedThreadId, turnId, {
           error: codexAppServerNotificationError(notification),
           provider,
           status,
           usageLimitExceeded: codexAppServerNotificationUsageLimitExceeded(notification),
           deferFailureDetails: true
         }));
-      const method = normalizeCodexRunText(notification.method);
+      const method = normalizeText(notification.method);
       if (method === "account/rateLimits/updated" || method === "account/updated") {
-        runCodexAppServerNotificationTask({ method, projectContext, provider, sessionId: normalizedSessionId, sessionKey }, () =>
+        notificationQueue.run({ method, projectContext, provider, sessionId: normalizedSessionId, sessionKey }, () =>
           publish(normalizedSessionId, { reason: "codex-plan-usage" }));
         return;
       }
@@ -249,7 +240,7 @@ export function createCodexNotificationObserver({
         turnId: codexAppServerNotificationTurnId(notification)
       };
       if (method === "thread/tokenUsage/updated") {
-        runCodexAppServerNotificationTask(notificationContext, async () => {
+        notificationQueue.run(notificationContext, async () => {
           const store = await createStore(normalizedSessionId);
           return onNotificationSignal("usage", {
             store, sessionId: normalizedSessionId, threadId: normalizedThreadId, notification
@@ -259,10 +250,10 @@ export function createCodexNotificationObserver({
       const classification = classifyCodexAppServerEvent(notification);
       if (classification.kind === "provider_error" && classification.text &&
           codexAppServerNotificationParams(notification).willRetry !== true) {
-        runCodexAppServerNotificationTask(notificationContext, async () => {
+        notificationQueue.run(notificationContext, async () => {
           return onNotificationSignal("provider_error", {
             sessionId: normalizedSessionId, threadId: normalizedThreadId, provider,
-            turnId: await resolveCodexAppServerTurnId(normalizedSessionId, normalizedThreadId,
+            turnId: await journal.resolveTurnId(normalizedSessionId, normalizedThreadId,
               codexAppServerNotificationTurnId(notification)),
             error: classification.text
           });
@@ -279,14 +270,14 @@ export function createCodexNotificationObserver({
       const retrying = classification.phase === "retrying";
       if (!hookOwned &&
           (retrying || method === "item/started" || method === "item/completed" && ["contextCompaction", "reasoning"].includes(itemType))) {
-        runCodexAppServerNotificationTask(notificationContext, async () => {
+        notificationQueue.run(notificationContext, async () => {
           const phase = retrying ? "retrying" : method === "item/started"
             ? ({ contextCompaction: "compacting", reasoning: "reasoning" })[itemType] || ""
             : "";
           const store = await createStore(normalizedSessionId);
-          const run = await readCodexAppServerAgentRunForSession(store, normalizedSessionId);
-          if (normalizeCodexRunText(run?.providerPhase) === phase) return;
-          return markCodexAppServerTurnActive(normalizedSessionId, {
+          const run = await output.readAgentRunForSession(store, normalizedSessionId);
+          if (normalizeText(run?.providerPhase) === phase) return;
+          return recovery.markTurnActive(normalizedSessionId, {
             phase, requireTrackedTurn: true,
             threadId: normalizedThreadId,
             turnId: codexAppServerNotificationTurnId(notification)
@@ -294,7 +285,7 @@ export function createCodexNotificationObserver({
         });
       }
       if (contextRefreshReason) {
-        runCodexAppServerNotificationTask(notificationContext, () => {
+        notificationQueue.run(notificationContext, () => {
           return onNotificationSignal("context_refresh", {
             sessionId: normalizedSessionId, threadId: normalizedThreadId,
             notification, reason: contextRefreshReason
@@ -302,14 +293,14 @@ export function createCodexNotificationObserver({
         });
       }
       if (method === "thread/goal/cleared") {
-        runCodexAppServerNotificationTask(notificationContext, async () => {
+        notificationQueue.run(notificationContext, async () => {
           await reconcileCodexAppServerGoalUpdated(normalizedSessionId, provider, normalizedThreadId, notification);
           await publish(normalizedSessionId, { reason: "codex-goal", nativeGoal: { threadId: normalizedThreadId, goal: null } });
         });
         return;
       }
       if (method === "thread/goal/updated") {
-        runCodexAppServerNotificationTask(notificationContext, async () => {
+        notificationQueue.run(notificationContext, async () => {
           await publish(normalizedSessionId, { reason: "codex-goal", nativeGoal: { threadId: normalizedThreadId, goal: notification.params.goal } });
           return reconcileCodexAppServerGoalUpdated(
             normalizedSessionId,
@@ -333,8 +324,8 @@ export function createCodexNotificationObserver({
       if (classification.kind === "final_assistant_result") {
         const event = codexAppServerNotificationEvent(notification);
         const payload = codexAppServerNotificationEventPayload(notification, event);
-        runCodexAppServerNotificationTask(notificationContext, () => {
-          return recordCodexAppServerFinalAssistantResult({
+        notificationQueue.run(notificationContext, () => {
+          return output.recordFinalAssistantResult({
             itemId: classification.itemId,
             notification,
             sessionId: normalizedSessionId,
@@ -345,11 +336,11 @@ export function createCodexNotificationObserver({
           });
         });
         debugLog("appServerFinalAssistantResult.received", {
-          eventId: normalizeCodexRunText(event?.id),
+          eventId: normalizeText(event?.id),
           eventType: codexAppServerNotificationEventType(notification, event),
-          itemId: normalizeCodexRunText(codexAppServerNotificationItem(notification)?.id),
+          itemId: normalizeText(codexAppServerNotificationItem(notification)?.id),
           method,
-          payloadId: normalizeCodexRunText(payload?.id),
+          payloadId: normalizeText(payload?.id),
           stableItemId: classification.itemId,
           source: classification.source,
           sessionId: normalizedSessionId,
@@ -361,28 +352,28 @@ export function createCodexNotificationObserver({
         if (hookOwned) {
           return;
         }
-        runCodexAppServerNotificationTask(notificationContext, () => {
-          return writeCodexAppServerLiveProgress(normalizedSessionId, normalizedThreadId, notification);
+        notificationQueue.run(notificationContext, () => {
+          return output.writeLiveProgress(normalizedSessionId, normalizedThreadId, notification);
         });
       }
       if (method === "item/completed") {
         const item = codexAppServerNotificationItem(notification);
-        if (normalizeCodexRunText(item?.type) === "userMessage") {
-          runCodexAppServerNotificationTask(notificationContext, () => {
-            return mirrorCodexAppServerTerminalUserMessage(normalizedSessionId, normalizedThreadId, notification);
+        if (normalizeText(item?.type) === "userMessage") {
+          notificationQueue.run(notificationContext, () => {
+            return delivery.mirrorTerminalUserMessage(normalizedSessionId, normalizedThreadId, notification);
           });
           return;
         }
         if (codexAppServerAssistantItemText(item)) {
-          runCodexAppServerNotificationTask(notificationContext, () => {
-            return mirrorCodexAppServerTerminalAssistantMessage(normalizedSessionId, normalizedThreadId, notification);
+          notificationQueue.run(notificationContext, () => {
+            return output.mirrorTerminalAssistantMessage(normalizedSessionId, normalizedThreadId, notification);
           });
           return;
         }
       }
       if (method === "turn/started") {
         codexAppServerAutomaticHookThreads.delete(normalizedThreadId);
-        runCodexAppServerNotificationTask(notificationContext, () => markCodexAppServerProviderTurnActive(normalizedSessionId, {
+        notificationQueue.run(notificationContext, () => recovery.markProviderTurnActive(normalizedSessionId, {
           source: "turn_started",
           status: codexAppServerNotificationTurnStatus(notification) || "inProgress",
           threadId: normalizedThreadId,
@@ -399,8 +390,8 @@ export function createCodexNotificationObserver({
           return;
         }
         if (codexAppServerTurnStatusIsSuccessfulComplete(status)) {
-          runCodexAppServerNotificationTask(notificationContext, () => {
-            return completeCodexAppServerTurn(normalizedSessionId, normalizedThreadId, turnId, {
+          notificationQueue.run(notificationContext, () => {
+            return recovery.completeTurn(normalizedSessionId, normalizedThreadId, turnId, {
               provider,
               status
             });
@@ -411,13 +402,13 @@ export function createCodexNotificationObserver({
       if (method === "thread/status/changed") {
         const status = codexAppServerNotificationTurnStatus(notification);
         if (codexAppServerTurnStatusIsActive(status)) {
-          runCodexAppServerNotificationTask(notificationContext, async () => {
-            const turnId = await resolveCodexAppServerTurnId(
+          notificationQueue.run(notificationContext, async () => {
+            const turnId = await journal.resolveTurnId(
               normalizedSessionId,
               normalizedThreadId,
               codexAppServerNotificationTurnId(notification)
             );
-            await markCodexAppServerProviderTurnActive(normalizedSessionId, {
+            await recovery.markProviderTurnActive(normalizedSessionId, {
               source: "thread_status_changed",
               status,
               threadId: normalizedThreadId,
@@ -433,13 +424,13 @@ export function createCodexNotificationObserver({
           return;
         }
         if (codexAppServerTurnStatusIsSuccessfulComplete(status)) {
-          runCodexAppServerNotificationTask(notificationContext, async () => {
-            const resolvedTurnId = await resolveCodexAppServerTurnId(
+          notificationQueue.run(notificationContext, async () => {
+            const resolvedTurnId = await journal.resolveTurnId(
               normalizedSessionId,
               normalizedThreadId,
               turnId
             );
-            return completeCodexAppServerTurn(normalizedSessionId, normalizedThreadId, resolvedTurnId, {
+            return recovery.completeTurn(normalizedSessionId, normalizedThreadId, resolvedTurnId, {
               provider,
               status
             });
@@ -467,7 +458,7 @@ export function createCodexNotificationObserver({
     };
   }
 
-  return {
+  return Object.freeze({
     eventSubscriptions: codexAppServerEventSubscriptions,
     automaticHookThreads: codexAppServerAutomaticHookThreads,
     eventSubscriptionKey: codexAppServerEventSubscriptionKey,
@@ -475,5 +466,7 @@ export function createCodexNotificationObserver({
     unsubscribeEventSubscription: unsubscribeCodexAppServerEventSubscription,
     reconcileGoalUpdated: reconcileCodexAppServerGoalUpdated,
     subscribeEvents: subscribeCodexAppServerEvents
-  };
+  });
 }
+
+/** @typedef {ReturnType<typeof createCodexNotificationObserver>} CodexNotificationObserver */

package/src/server/conversation/codexNotificationQueue.js

@@ -1,12 +1,21 @@
-import { normalizeCodexRunText } from "./codexTurnState.js";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 
-// Per-session ordered notification tasks. Coalesces only fragments still
-// waiting behind a running write; running batches are never merged or delayed.
+function ignoreNotificationTaskError() {}
+
+/**
+ * Per-session ordered notification tasks. Coalesces only fragments still
+ * waiting behind a running write; running batches are never merged or delayed.
+ * @param {object} [options]
+ * @param {import("./codexTurn.js").CodexSessionNamespace} [options.namespace]
+ * @param {() => boolean} [options.isClosing]
+ * @param {import("./codexTurn.js").CodexRunInContext} [options.runInContext]
+ * @param {(error: unknown, context: object) => void} [options.reportError]
+ */
 export function createCodexAppServerNotificationQueue({
-  namespace = normalizeCodexRunText,
+  namespace = normalizeText,
   isClosing = () => false,
   runInContext = (_context, operation) => operation(),
-  reportError = () => {}
+  reportError = ignoreNotificationTaskError
 } = {}) {
   const codexAppServerNotificationTasks = new Map();
   const codexAppServerPendingStreams = new Map();
@@ -16,8 +25,8 @@ export function createCodexAppServerNotificationQueue({
     if (isClosing()) {
       return;
     }
-    const taskSessionId = normalizeCodexRunText(context.sessionId);
-    const taskSessionKey = normalizeCodexRunText(context.sessionKey) ||
+    const taskSessionId = normalizeText(context.sessionId);
+    const taskSessionKey = normalizeText(context.sessionKey) ||
       namespace(taskSessionId);
     // Other notifications end the pending stream batch so completion, reasoning
     // and turn changes retain their position in the provider's event order.
@@ -28,7 +37,7 @@ export function createCodexAppServerNotificationQueue({
       .catch(() => null)
       .then(() => runInContext(context.projectContext, operation))
       .catch((error) => {
-        context.provider?.failObservation?.(error);
+        context.provider?.failObservation(error);
         reportError(error, context);
       });
     codexAppServerNotificationTasks.set(taskSessionKey, task);
@@ -98,7 +107,7 @@ export function createCodexAppServerNotificationQueue({
     codexAppServerPendingReasoning.set(context.sessionKey, batch);
   }
 
-  return {
+  return Object.freeze({
     tasks: codexAppServerNotificationTasks,
     pendingStreams: codexAppServerPendingStreams,
     pendingReasoning: codexAppServerPendingReasoning,
@@ -107,5 +116,7 @@ export function createCodexAppServerNotificationQueue({
     captureDrain: captureCodexAppServerNotificationDrain,
     stream: queueCodexAppServerStream,
     reasoning: queueCodexAppServerReasoning
-  };
+  });
 }
+
+/** @typedef {ReturnType<typeof createCodexAppServerNotificationQueue>} CodexAppServerNotificationQueue */