@jskit-ai/assistant-core 0.2.6 → 0.2.8

package/src/server/conversation/codexEvents.js

@@ -11,7 +11,7 @@ function nonNegativeInteger(value) {
   return Number.isSafeInteger(number) && number >= 0 ? number : null;
 }
 
-function codexContextUsageFromNotification(notification = {}) {
+function codexContextUsageFromNotification(notification) {
   if (normalizeNullableText(notification?.method) !== CODEX_TOKEN_USAGE_METHOD) {
     return null;
   }
@@ -104,7 +104,7 @@ function codexAppServerStatusFromValue(status = null) {
   return type;
 }
 
-function codexAppServerNotificationParams(notification = {}) {
+function codexAppServerNotificationParams(notification) {
   return isRecord(notification?.params) ? notification.params : {};
 }
 
@@ -604,74 +604,6 @@ function codexAppServerContextRefreshReason(notification = {}) {
   return "";
 }
 
-// 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 codexAppServerOutputOwnerTurnId({
   notificationThreadId = "",
   notificationTurnId = "",
@@ -693,139 +625,12 @@ function codexAppServerOutputOwnerTurnId({
     : normalizeNullableText(notificationTurnId);
 }
 
-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));
-}
+// The `./server/codex-events` contract forwards this snapshot reader from here.
+export { codexAppServerProviderThreadAssistantSegments } from "./codexThreadSnapshot.js";
 
 export {
   codexContextUsageFromNotification,
   classifyCodexAppServerEvent,
-  codexAppServerThreadRawValue,
-  codexAppServerThreadTurnId,
-  codexAppServerThreadError,
-  codexAppServerProviderThreadTurns,
-  codexAppServerProviderTurnId,
-  codexAppServerProviderTurnStatus,
-  codexAppServerProviderTurnItems,
-  codexAppServerProviderTurnClientIds,
-  codexAppServerProviderTurnForOperation,
-  inspectCodexAppServerRenewalThread,
-  codexAppServerProviderTurnText,
-  codexAppServerProviderTurnError,
   codexAppServerAgentMessageText,
   codexAppServerAssistantItemText,
   codexAppServerContentText,
@@ -842,8 +647,8 @@ export {
   codexAppServerNotificationTurnId,
   codexAppServerNotificationTurnStatus,
   codexAppServerNotificationUsageLimitExceeded,
-  codexAppServerProviderThreadAssistantSegments,
   codexAppServerOutputOwnerTurnId,
+  codexAppServerSignedOutText,
   codexAppServerStatusFromValue,
   codexAppServerUserMessageText
 };

package/src/server/conversation/codexGoalCommands.js

@@ -1,6 +1,17 @@
 import { CODEX_APP_SERVER_AGENT_RUN_ID } from "./codexTurnState.js";
 
-// Private composition of unchanged operations from the original run owner.
+/**
+ * The run owner's native goal commands: preparing a goal's context, validating its input and updating it.
+ * @param {object} dependencies
+ * @param {import("./codexConversations.js").CodexConversationCommands["codexAppServerConversationContext"]} dependencies.conversationContext
+ * @param {import("./codexThreadReadiness.js").CodexThreadReadiness["ensureThreadReady"]} dependencies.ensureThreadReady
+ * @param {import("./codexTurn.js").CodexPublish} dependencies.publish
+ * @param {import("./codexOutput.js").CodexAppServerOutput["readAgentRunForSession"]} dependencies.readCodexAppServerAgentRunForSession
+ * @param {import("./codexNotificationObserver.js").CodexNotificationObserver["reconcileGoalUpdated"]} dependencies.reconcileCodexAppServerGoalUpdated
+ * @param {import("./codexOutput.js").CodexAppServerOutput["submitAssistantResult"]} dependencies.submitCodexAppServerAssistantResult
+ * @param {import("./codexNotificationObserver.js").CodexNotificationObserver["subscribeEvents"]} dependencies.subscribeCodexAppServerEvents
+ * @param {import("./codexTurn.js").CodexTurnStateReader} dependencies.turnState
+ */
 export function createCodexGoalCommands({
   conversationContext,
   ensureThreadReady,
@@ -120,10 +131,9 @@ export function createCodexGoalCommands({
     return { ok: true, status: "available", threadId, goal: result.goal || null };
   }
 
-
-  return {
+  return Object.freeze({
     prepareCodexAppServerGoalContext,
     validateCodexAppServerGoalInput,
     updateCodexAppServerGoal
-  };
+  });
 }

package/src/server/conversation/codexHelperExecution.js

@@ -1,34 +1,31 @@
-import { codexAppServerDeliveredTurn, deleteCodexAppServerThread } from "./codexProvider.js";
-import { CODEX_HELPER_THREAD_LIFECYCLES } from "./codexHelperThreadLedger.js";
-import { codexAppServerErrorMessage as errorMessage, normalizeCodexRunText as normalizeText } from "./codexTurnState.js";
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
+import { codexAppServerDeliveredTurn } from "./codexProviderTurns.js";
+import { deleteCodexAppServerThread } from "./codexProviderThreads.js";
+import { CODEX_HELPER_THREAD_LIFECYCLES } from "./codexHelperThreadRecord.js";
+import { codexAppServerErrorMessage as errorMessage } from "./codexTurnState.js";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 
 export function createCodexHelperOwnershipError({ applicationName = "Application", errorPrefix = "" } = {}) {
   return function codexAppServerHelperOwnershipError(message = "", details = {}) {
-    const error = new Error(
-      normalizeText(message) ||
-      `${applicationName} could not prove ownership of a persisted low-cost assistant thread.`
+    const retryable = details.retryable !== false;
+    const error = new AppError(409,
+      normalizeText(message) || `${applicationName} could not prove ownership of a persisted low-cost assistant thread.`,
+      {
+        code: `${errorPrefix}codex_helper_ownership_blocked`,
+        details: { ...details, retryable },
+        ...(normalizeText(message) ? {} : { messageCode: "assistant.codex.helperOwnershipBlocked", messageParams: { applicationName } })
+      }
     );
-    error.code = `${errorPrefix}codex_helper_ownership_blocked`;
-    error.statusCode = 409;
-    if (!normalizeText(message)) {
-      error.messageCode = "assistant.codex.helperOwnershipBlocked";
-      error.messageParams = { applicationName };
-    }
-    error.retryable = details.retryable !== false;
-    error.details = {
-      ...details,
-      retryable: error.retryable
-    };
+    error.retryable = retryable;
     return error;
   };
 }
 
+/**
+ * @param {import("./codexProvider.js").CodexAppServerAgentProvider} provider
+ * @param {ReturnType<typeof createCodexHelperOwnershipError>} codexAppServerHelperOwnershipError
+ */
 export async function readCodexAppServerAccountIdentity(provider, codexAppServerHelperOwnershipError) {
-  if (typeof provider.currentRuntimeInfo !== "function") {
-    throw codexAppServerHelperOwnershipError(
-      "The Codex provider cannot identify the selected account."
-    );
-  }
   const runtimeInfo = await provider.currentRuntimeInfo();
   const accountIdentitySignature = normalizeText(runtimeInfo?.accountIdentitySignature);
   if (!/^sha256:[a-f0-9]{64}$/u.test(accountIdentitySignature)) {
@@ -39,12 +36,17 @@ export async function readCodexAppServerAccountIdentity(provider, codexAppServer
   return accountIdentitySignature;
 }
 
+/**
+ * @param {import("./codexProvider.js").CodexAppServerAgentProvider | null} provider
+ * @param {string} expectedSignature
+ * @param {ReturnType<typeof createCodexHelperOwnershipError>} codexAppServerHelperOwnershipError
+ */
 export async function assertCodexAppServerHelperAccountIdentity(provider, expectedSignature = "", codexAppServerHelperOwnershipError) {
   const expected = normalizeText(expectedSignature);
   if (!expected) {
     return;
   }
-  if (!/^sha256:[a-f0-9]{64}$/u.test(expected) || typeof provider?.currentRuntimeInfo !== "function") {
+  if (!/^sha256:[a-f0-9]{64}$/u.test(expected) || !provider) {
     throw codexAppServerHelperOwnershipError(
       "The requested low-cost assistant account identity is invalid. Refresh the task and retry."
     );
@@ -65,25 +67,18 @@ export async function sendPreparedCodexAppServerHelperTurn(provider, prepared, h
     prepared.input,
     prepared.turnSettings((await helperIsolation.executionContext(provider)).cwd)
   );
-  return Object.freeze({ executionProfile: prepared.executionProfile, input: prepared.input, turn });
+  return Object.freeze({
+    executionProfile: prepared.executionProfile,
+    input: prepared.input,
+    turn
+  });
 }
 
-// One invocation retains its original mutable record while the shared ownership
-// facet retains all durable state, locks and cross-operation coordination.
+// One invocation holds its own mutable record; the shared owner holds all
+// durable state, locks and cross-operation coordination.
 export async function prepareDetachedCodexHelperThread(owner, scope, preparation, {
   applicationName = "Application"
 } = {}) {
-  const {
-    withProjectOperation: withCodexAppServerHelperProjectOperation,
-    remember: rememberCodexAppServerHelperThread,
-    update: updateCodexAppServerHelperThread,
-    remove: removeCodexAppServerHelperThread,
-    retire: retireCodexAppServerHelperThread,
-    ownershipError: codexAppServerHelperOwnershipError,
-    cleanupError: codexAppServerHelperThreadCleanupError,
-    key: codexAppServerHelperThreadKey,
-    turnStarts: codexAppServerHelperTurnStarts
-  } = owner;
   const {
     executionProfile, onRetired, projectRuntimeRoot, provider, sessionId,
     requestedThreadId, workdir
@@ -100,7 +95,7 @@ export async function prepareDetachedCodexHelperThread(owner, scope, preparation
     sessionId = "",
     workdir = ""
   } = {}) {
-    return withCodexAppServerHelperProjectOperation(projectRuntimeRoot, async () => {
+    return owner.withProjectOperation(projectRuntimeRoot, async () => {
       const projectContextRoot = normalizeText(scope.projectContextRoot);
       let thread = null;
       try {
@@ -116,7 +111,7 @@ export async function prepareDetachedCodexHelperThread(owner, scope, preparation
           error?.codexAppServerHelperThreadCleanupRequired === true &&
           failedThreadId
         ) {
-          await rememberCodexAppServerHelperThread({
+          await owner.remember({
             executionProfile,
             lifecycle: CODEX_HELPER_THREAD_LIFECYCLES.CLEANUP_REQUIRED,
             projectContextRoot,
@@ -134,7 +129,7 @@ export async function prepareDetachedCodexHelperThread(owner, scope, preparation
         throw new Error("Codex app-server did not return a helper thread id.");
       }
       try {
-        const record = await rememberCodexAppServerHelperThread({
+        const record = await owner.remember({
           executionProfile,
           lifecycle: CODEX_HELPER_THREAD_LIFECYCLES.STARTING_TURN,
           onRetired,
@@ -150,7 +145,7 @@ export async function prepareDetachedCodexHelperThread(owner, scope, preparation
         try {
           await deleteCodexAppServerThread({ provider, threadId });
         } catch (cleanupError) {
-          const failure = codexAppServerHelperOwnershipError(
+          const failure = owner.ownershipError(
             `${applicationName} could not persist or retire a newly created low-cost assistant thread.`,
             {
               cleanupError: errorMessage(cleanupError),
@@ -169,7 +164,7 @@ export async function prepareDetachedCodexHelperThread(owner, scope, preparation
 
   if (requestedThreadId) {
     try {
-      helperThreadRecord = await updateCodexAppServerHelperThread(
+      helperThreadRecord = await owner.update(
         helperThreadRecord,
         {
           lifecycle: CODEX_HELPER_THREAD_LIFECYCLES.STARTING_TURN,
@@ -186,30 +181,30 @@ export async function prepareDetachedCodexHelperThread(owner, scope, preparation
     } catch (error) {
       if (error?.codexAppServerHelperThreadRetired === true) {
         try {
-          await removeCodexAppServerHelperThread(helperThreadRecord);
+          await owner.remove(helperThreadRecord);
         } catch (ledgerError) {
-          throw codexAppServerHelperThreadCleanupError(
+          throw owner.cleanupError(
             helperThreadRecord,
             ledgerError
           );
         }
       } else if (error?.codexAppServerHelperThreadCleanupRequired === true) {
         try {
-          helperThreadRecord = await updateCodexAppServerHelperThread(
+          helperThreadRecord = await owner.update(
             helperThreadRecord,
             {
               lifecycle: CODEX_HELPER_THREAD_LIFECYCLES.CLEANUP_REQUIRED
             }
           );
         } catch (ledgerError) {
-          throw codexAppServerHelperThreadCleanupError(
+          throw owner.cleanupError(
             helperThreadRecord,
             ledgerError
           );
         }
       } else {
         try {
-          await retireCodexAppServerHelperThread(helperThreadRecord);
+          await owner.retire(helperThreadRecord);
         } catch (cleanupError) {
           cleanupError.cause = error;
           throw cleanupError;
@@ -236,7 +231,7 @@ export async function prepareDetachedCodexHelperThread(owner, scope, preparation
     if (!helperThreadRecord) {
       return;
     }
-    await retireCodexAppServerHelperThread(helperThreadRecord);
+    await owner.retire(helperThreadRecord);
   };
 
   async function dispatch(threadId, failDispatch) {
@@ -245,13 +240,13 @@ export async function prepareDetachedCodexHelperThread(owner, scope, preparation
     let status = "";
     let helperTurnStart = null;
     try {
-      const helperThreadKey = codexAppServerHelperThreadKey(helperThreadRecord);
+      const helperThreadKey = owner.key(helperThreadRecord);
       helperTurnStart = (async () => {
         const currentDelivery = await sendPreparedCodexAppServerHelperTurn(
           provider, preparation.turn(threadId), preparation.isolation
         );
         const { turnId: currentTurnId, status: currentStatus } = codexAppServerDeliveredTurn(currentDelivery);
-        helperThreadRecord = await updateCodexAppServerHelperThread(
+        helperThreadRecord = await owner.update(
           helperThreadRecord,
           {
             lifecycle: CODEX_HELPER_THREAD_LIFECYCLES.ACTIVE,
@@ -264,15 +259,15 @@ export async function prepareDetachedCodexHelperThread(owner, scope, preparation
           turnId: currentTurnId
         };
       })();
-      codexAppServerHelperTurnStarts.set(helperThreadKey, helperTurnStart);
+      owner.turnStarts.set(helperThreadKey, helperTurnStart);
       ({ delivery, status, turnId } = await helperTurnStart);
     } catch (error) {
       await failDispatch(error);
     } finally {
       if (helperTurnStart) {
-        const helperThreadKey = codexAppServerHelperThreadKey(helperThreadRecord);
-        if (codexAppServerHelperTurnStarts.get(helperThreadKey) === helperTurnStart) {
-          codexAppServerHelperTurnStarts.delete(helperThreadKey);
+        const helperThreadKey = owner.key(helperThreadRecord);
+        if (owner.turnStarts.get(helperThreadKey) === helperTurnStart) {
+          owner.turnStarts.delete(helperThreadKey);
         }
       }
     }
@@ -281,13 +276,13 @@ export async function prepareDetachedCodexHelperThread(owner, scope, preparation
 
   async function complete() {
     try {
-      helperThreadRecord = await updateCodexAppServerHelperThread(helperThreadRecord, {
+      helperThreadRecord = await owner.update(helperThreadRecord, {
         lifecycle: CODEX_HELPER_THREAD_LIFECYCLES.READY,
         turnId: ""
       });
     } catch (error) {
       try {
-        await retireCodexAppServerHelperThread(helperThreadRecord);
+        await owner.retire(helperThreadRecord);
       } catch (cleanupError) {
         cleanupError.cause = error;
         throw cleanupError;
@@ -296,5 +291,10 @@ export async function prepareDetachedCodexHelperThread(owner, scope, preparation
     }
   }
 
-  return Object.freeze({ thread, dispatch, discard: discardHelperThread, complete });
+  return Object.freeze({
+    thread,
+    dispatch,
+    discard: discardHelperThread,
+    complete
+  });
 }