@jskit-ai/assistant-core 0.2.7 → 0.2.8

package/src/server/conversation/codexDetachedConversation.js

@@ -0,0 +1,203 @@
+import { codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure } from "./codexTurnState.js";
+import { CODEX_APP_SERVER_DETACHED_TURN_TIMEOUT_MS, createCodexAppServerDetachedTurnWatcher } from "./codexDetachedTurn.js";
+import { assertCodexAppServerHelperAccountIdentity } from "./codexHelperExecution.js";
+import { prepareCodexAppServerConversationThread } from "./codexConversationTurns.js";
+import { codexAppServerDeliveredTurn, sendCodexAppServerPrompt } from "./codexProviderTurns.js";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+function ignoreDetachedConversationEvent() {}
+
+export async function acquireCodexAppServerDetachedThread(provider, requestedThreadId, threadSettings, input = {}) {
+  let thread = null;
+  if (requestedThreadId) {
+    thread = await provider.resumeThread(requestedThreadId, threadSettings);
+  }
+  if (!thread) {
+    thread = await provider.startThread({
+      ...threadSettings,
+      ...(input.ephemeral === true ? { ephemeral: true } : {})
+    });
+  }
+  return thread;
+}
+
+export function codexAppServerDetachedThreadId(thread, requestedThreadId) {
+  const threadId = normalizeText(thread.id || thread.response?.thread?.id || requestedThreadId);
+  if (!threadId) {
+    throw new Error("Codex app-server did not return a detached chat thread id.");
+  }
+  return threadId;
+}
+
+export async function dispatchCodexAppServerDetachedTurn({ provider, prompt, threadId }, authorized) {
+  const delivery = await sendCodexAppServerPrompt({ provider, prompt, threadId }, authorized);
+  return { delivery, ...codexAppServerDeliveredTurn(delivery) };
+}
+
+export async function runDetachedCodexAppServerTurn({
+  provider,
+  threadId,
+  timeoutMs,
+  onEvent: emitDetachedEvent,
+  onFailure
+} = {}, operation) {
+  const watcher = createCodexAppServerDetachedTurnWatcher(provider, threadId, {
+    onEvent: (classification) => {
+      emitDetachedEvent({
+        classification,
+        threadId,
+        turnId: classification.turnId,
+        type: "notification"
+      });
+    },
+    timeoutMs
+  });
+  const waitForResult = watcher.wait();
+  void waitForResult.catch(() => null);
+  const throwWatcherFailure = async (fallbackError, status = "", {
+    waitForDetail = false
+  } = {}) => {
+    if (waitForDetail) {
+      watcher.failAfterDetailGrace(fallbackError);
+    } else {
+      watcher.failNow(fallbackError);
+    }
+    const error = await waitForResult.then(
+      () => fallbackError,
+      (watcherError) => watcherError
+    );
+    throw await onFailure(error, status);
+  };
+  const { delivery, status, turnId } = await operation(throwWatcherFailure);
+  watcher.setTurnId(turnId);
+  emitDetachedEvent({
+    status,
+    threadId,
+    turnId,
+    type: "turn"
+  });
+  if (codexAppServerTurnStatusIsProviderFailure(status)) {
+    const error = new Error(codexAppServerDeliveredTurn(delivery).error || `Codex app-server turn ${status}.`);
+    await throwWatcherFailure(error, status, {
+      waitForDetail: true
+    });
+  }
+  if (codexAppServerTurnStatusIsSuccessfulComplete(status)) {
+    await watcher.completeNow(status);
+  }
+  let result = null;
+  try {
+    result = await waitForResult;
+  } catch (error) {
+    throw await onFailure(error, status);
+  }
+  return result;
+}
+
+/**
+ * A detached conversation: one prompt on a resumed or fresh native thread, watched until its turn completes.
+ * A Helper's turn runs on its retained Helper thread instead.
+ * @param {object} dependencies
+ * @param {object} dependencies.conversationPreparation The application's conversation preparation.
+ * @param {import("./codexConversations.js").CodexConversationResult} dependencies.codexAppServerConversationResult
+ * @param {import("./codexConversations.js").CodexConversationContextReader} dependencies.codexAppServerConversationContext
+ * @param {import("./codexHelperThreads.js").CodexHelperThreadLifecycle} dependencies.helperLifecycle
+ * @param {string} dependencies.helperOwnershipError
+ */
+export function createCodexDetachedConversation({
+  conversationPreparation,
+  codexAppServerConversationResult,
+  codexAppServerConversationContext,
+  helperLifecycle,
+  helperOwnershipError
+}) {
+  async function runDetachedCodexAppServerConversation(sessionId, input = {}, options = {}) {
+    const preparation = conversationPreparation.detached(sessionId, input);
+    const { admission } = preparation;
+    if (admission.ok === false) return admission;
+    try {
+      return await codexAppServerConversationResult(async () => {
+        const unavailable = preparation.result;
+        if (unavailable) return unavailable;
+        const prompt = preparation.prompt;
+        const context = await codexAppServerConversationContext(sessionId, input, options);
+        if (context.ok === false) return context;
+        const { provider, runtime, workdir } = context;
+        const executionProfile = input.executionProfile && typeof input.executionProfile === "object" &&
+          !Array.isArray(input.executionProfile) ? input.executionProfile : null;
+        const helperTurn = Boolean(executionProfile);
+        const emitDetachedEvent = options.onEvent || ignoreDetachedConversationEvent;
+        const onRetired = ({ threadId }) => emitDetachedEvent({ threadId, type: "thread-retired" });
+        if (helperTurn) {
+          await assertCodexAppServerHelperAccountIdentity(provider, input.expectedAccountIdentitySignature, helperOwnershipError);
+        }
+        const execution = preparation.execution(context);
+        const threadSettings = helperTurn ? null : await prepareCodexAppServerConversationThread(
+          provider, execution.threadPreparation, conversationPreparation.isolation
+        );
+        const requestedThreadId = normalizeText(input.threadId || input.codexSessionId);
+        let helper = null;
+        let thread;
+        if (helperTurn) {
+          const scope = { executionProfile, onRetired, projectRuntimeRoot: normalizeText(runtime?.stateRoot),
+            projectContextRoot: normalizeText(runtime?.projectContextRoot), provider, sessionId, requestedThreadId, workdir,
+            ...(requestedThreadId ? { record: helperLifecycle.threadForOperation({ executionProfile,
+              projectRuntimeRoot: normalizeText(runtime?.stateRoot), provider, sessionId,
+              threadId: requestedThreadId, workdir }) } : {}) };
+          helper = await helperLifecycle.prepareDetached(scope, execution.helperPreparation);
+          thread = helper.thread;
+        } else {
+          thread = await acquireCodexAppServerDetachedThread(provider, requestedThreadId, threadSettings, input);
+        }
+        const threadId = codexAppServerDetachedThreadId(thread, requestedThreadId);
+        emitDetachedEvent({ threadId, type: "thread" });
+        const requestedTimeoutMs = Number(input.timeoutMs || 0);
+        const profileTimeoutMs = Number(executionProfile?.limits?.timeoutMs || 0);
+        let turnId = "";
+        const result = await runDetachedCodexAppServerTurn({
+          provider, threadId, onEvent: emitDetachedEvent,
+          timeoutMs: helperTurn
+            ? Math.min(requestedTimeoutMs > 0 ? requestedTimeoutMs : profileTimeoutMs, profileTimeoutMs)
+            : requestedTimeoutMs > 0 ? requestedTimeoutMs : CODEX_APP_SERVER_DETACHED_TURN_TIMEOUT_MS,
+          async onFailure(error, status) {
+            await helper?.discard();
+            return execution.failure(error, status);
+          }
+        }, async failDispatch => {
+          let dispatched;
+          if (helperTurn) {
+            dispatched = await helper.dispatch(threadId, failDispatch);
+          } else {
+            try {
+              dispatched = await dispatchCodexAppServerDetachedTurn({ provider, prompt, threadId }, execution.authorized);
+            } catch (error) {
+              await failDispatch(error);
+            }
+          }
+          turnId = dispatched.turnId;
+          return dispatched;
+        });
+        if (helperTurn) {
+          try {
+            await assertCodexAppServerHelperAccountIdentity(provider, input.expectedAccountIdentitySignature, helperOwnershipError);
+            execution.validateOutput(result.text);
+          } catch (error) {
+            await helper.discard();
+            throw error;
+          }
+          await helper.complete();
+        }
+        emitDetachedEvent({ status: result.status || "completed", text: result.text,
+          threadId, turnId: result.turnId || turnId, type: "completed" });
+        return { ok: true, text: result.text, threadId, turnId: result.turnId || turnId,
+          ...(helperTurn ? { inputCharacters: prompt.length, outputCharacters: result.text.length, usage: result.usage || null } : {}) };
+      });
+    } finally {
+      admission.release();
+    }
+  }
+
+  return Object.freeze({ runDetachedCodexAppServerConversation });
+}
+
+/** @typedef {ReturnType<typeof createCodexDetachedConversation>} CodexDetachedConversation */

package/src/server/conversation/codexDetachedTurn.js

@@ -1,6 +1,14 @@
 import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
 import { normalizeNullableText } from "./normalize.js";
-import { classifyCodexAppServerEvent, codexAppServerNotificationParams, codexAppServerNotificationThreadId, codexAppServerNotificationTurnId, codexAppServerNotificationTurnStatus, codexAppServerNotificationError, codexAppServerStatusFromValue, codexAppServerProviderThreadAssistantSegments, codexAppServerProviderTurnId, codexAppServerProviderTurnStatus, codexAppServerProviderTurnForOperation, codexAppServerProviderTurnText, codexAppServerProviderTurnError } from "./codexEvents.js";
+import { classifyCodexAppServerEvent, codexAppServerNotificationParams, codexAppServerNotificationThreadId, codexAppServerNotificationTurnId, codexAppServerNotificationTurnStatus, codexAppServerNotificationError, codexAppServerStatusFromValue } from "./codexEvents.js";
+import {
+  codexAppServerProviderThreadAssistantSegments,
+  codexAppServerProviderTurnId,
+  codexAppServerProviderTurnStatus,
+  codexAppServerProviderTurnForOperation,
+  codexAppServerProviderTurnText,
+  codexAppServerProviderTurnError
+} from "./codexThreadSnapshot.js";
 import { codexAppServerTurnStatusIsProviderFailure, codexAppServerTurnStatusIsSuccessfulComplete } from "./codexTurnState.js";
 
 const CODEX_APP_SERVER_DETACHED_TURN_TIMEOUT_MS = 180_000;
@@ -30,10 +38,33 @@ function codexAppServerTurnTokenUsage(notification = {}) {
   return Object.keys(snapshot).length ? Object.freeze(snapshot) : null;
 }
 
-function createCodexAppServerDetachedTurnWatcher(provider = null, threadId = "", {
+/**
+ * The provider methods a detached turn watcher reads.
+ * @typedef {Pick<import("./codexProvider.js").CodexAppServerAgentProvider,
+ *   "subscribe" | "readThread" | "isAvailable" | "currentConnectionGeneration">} CodexDetachedTurnProvider
+ */
+
+/**
+ * The observer told about each classified notification of the watched turn.
+ * @typedef {(classification: object, notification: object) => void} CodexDetachedTurnEventObserver
+ */
+
+function ignoreCodexDetachedTurnEvent() {}
+
+/**
+ * Watches one native turn of a thread until it completes, fails or times out.
+ * @param {CodexDetachedTurnProvider} provider
+ * @param {string} threadId
+ * @param {object} [options]
+ * @param {boolean} [options.includeThreadHistory]
+ * @param {boolean} [options.allowEmptyResponse]
+ * @param {CodexDetachedTurnEventObserver} [options.onEvent]
+ * @param {number} [options.timeoutMs]
+ */
+function createCodexAppServerDetachedTurnWatcher(provider, threadId = "", {
   includeThreadHistory = true,
   allowEmptyResponse = false,
-  onEvent = null,
+  onEvent = ignoreCodexDetachedTurnEvent,
   timeoutMs = CODEX_APP_SERVER_DETACHED_TURN_TIMEOUT_MS
 } = {}) {
   const normalizedThreadId = normalizeNullableText(threadId);
@@ -79,8 +110,8 @@ function createCodexAppServerDetachedTurnWatcher(provider = null, threadId = "",
     rejectWaiter?.(error);
   }
 
-  function emitWatcherEvent(classification = {}, notification) {
-    if (typeof onEvent !== "function" || !classification?.kind) {
+  function emitWatcherEvent(classification, notification) {
+    if (!classification.kind) {
       return;
     }
     onEvent({
@@ -94,8 +125,7 @@ function createCodexAppServerDetachedTurnWatcher(provider = null, threadId = "",
     if (
       !includeThreadHistory ||
       !normalizedThreadId ||
-      !targetTurnId ||
-      typeof provider?.readThread !== "function"
+      !targetTurnId
     ) {
       return {
         status: "",
@@ -165,104 +195,101 @@ function createCodexAppServerDetachedTurnWatcher(provider = null, threadId = "",
     return !targetTurnId || !notificationTurnId || notificationTurnId === targetTurnId;
   }
 
-  return {
-    async completeNow(status = "completed") {
-      await finishFromCompletion(status);
-    },
-    failNow(error) {
-      fail(error);
-    },
-    failAfterDetailGrace(error) {
-      failAfterDetailGrace(error);
-    },
-    setTurnId(turnId = "") {
-      targetTurnId = normalizeNullableText(turnId);
-      if (pendingFailure) {
-        failAfterDetailGrace(pendingFailure);
-        return;
-      }
-      if (pendingCompletionStatus) {
-        const status = pendingCompletionStatus;
-        pendingCompletionStatus = "";
-        void finishFromCompletion(status);
-      }
-    },
-    wait() {
-      if (settled) {
-        return Promise.reject(new Error("Codex app-server detached turn watcher was already settled."));
+  function setTurnId(turnId = "") {
+    targetTurnId = normalizeNullableText(turnId);
+    if (pendingFailure) {
+      failAfterDetailGrace(pendingFailure);
+      return;
+    }
+    if (pendingCompletionStatus) {
+      const status = pendingCompletionStatus;
+      pendingCompletionStatus = "";
+      void finishFromCompletion(status);
+    }
+  }
+
+  function wait() {
+    if (settled) {
+      return Promise.reject(new Error("Codex app-server detached turn watcher was already settled."));
+    }
+    return new Promise((resolve, reject) => {
+      resolveWaiter = resolve;
+      rejectWaiter = reject;
+      if (timeoutMs > 0) {
+        timeout = setTimeout(() => {
+          fail(new Error("Timed out waiting for Codex app-server response."));
+        }, timeoutMs);
+      } else {
+        // Interactive repair turns may take longer than bounded helper jobs.
+        // Retain their watcher until completion, interruption, or connection loss.
+        const generation = provider.currentConnectionGeneration();
+        connectionCheck = setInterval(() => {
+          if (provider.isAvailable() === false ||
+            provider.currentConnectionGeneration() !== generation) {
+            fail(new Error("Connection to Codex was lost while the temporary AI was working."));
+          }
+        }, 1000);
+        connectionCheck.unref();
       }
-      return new Promise((resolve, reject) => {
-        resolveWaiter = resolve;
-        rejectWaiter = reject;
-        if (timeoutMs > 0) {
-          timeout = setTimeout(() => {
-            fail(new Error("Timed out waiting for Codex app-server response."));
-          }, timeoutMs);
-        } else {
-          // Interactive repair turns may take longer than bounded helper jobs.
-          // Retain their watcher until completion, interruption, or connection loss.
-          const generation = provider?.currentConnectionGeneration?.();
-          connectionCheck = setInterval(() => {
-            if (provider?.isAvailable?.() === false ||
-              provider?.currentConnectionGeneration?.() !== generation) {
-              fail(new Error("Connection to Codex was lost while the temporary AI was working."));
-            }
-          }, 1000);
-          connectionCheck.unref?.();
+      unsubscribe = provider.subscribe((notification = {}) => {
+        if (!notificationMatches(notification)) {
+          return;
+        }
+        usage = codexAppServerTurnTokenUsage(notification) || usage;
+        const classification = classifyCodexAppServerEvent(notification);
+        emitWatcherEvent(classification, notification);
+        if (
+          classification.kind === "provider_error" &&
+          classification.text &&
+          codexAppServerNotificationParams(notification).willRetry !== true
+        ) {
+          const error = new Error(classification.text);
+          if (!targetTurnId) {
+            pendingFailure = error;
+            return;
+          }
+          fail(error);
+          return;
+        }
+        if (classification.kind === "final_assistant_result" && classification.text) {
+          finalText = classification.text;
+          if (pendingCompletionStatus && targetTurnId) {
+            const status = pendingCompletionStatus;
+            pendingCompletionStatus = "";
+            clearTimeout(failureDetailTimeout);
+            failureDetailTimeout = null;
+            void finishFromCompletion(status);
+          }
+        }
+        const method = normalizeNullableText(notification.method);
+        if (method !== "turn/completed" && method !== "thread/status/changed") {
+          return;
+        }
+        const status = codexAppServerNotificationTurnStatus(notification) || "completed";
+        if (codexAppServerTurnStatusIsProviderFailure(status)) {
+          const error = new Error(codexAppServerNotificationError(notification) || `Codex app-server turn ${status}.`);
+          if (!targetTurnId) {
+            pendingFailure = error;
+            return;
+          }
+          failAfterDetailGrace(error);
+          return;
+        }
+        if (codexAppServerTurnStatusIsSuccessfulComplete(status)) {
+          void finishFromCompletion(status);
         }
-        unsubscribe = typeof provider?.subscribe === "function"
-          ? provider.subscribe((notification = {}) => {
-              if (!notificationMatches(notification)) {
-                return;
-              }
-              usage = codexAppServerTurnTokenUsage(notification) || usage;
-              const classification = classifyCodexAppServerEvent(notification);
-              emitWatcherEvent(classification, notification);
-              if (
-                classification.kind === "provider_error" &&
-                classification.text &&
-                codexAppServerNotificationParams(notification).willRetry !== true
-              ) {
-                const error = new Error(classification.text);
-                if (!targetTurnId) {
-                  pendingFailure = error;
-                  return;
-                }
-                fail(error);
-                return;
-              }
-              if (classification.kind === "final_assistant_result" && classification.text) {
-                finalText = classification.text;
-                if (pendingCompletionStatus && targetTurnId) {
-                  const status = pendingCompletionStatus;
-                  pendingCompletionStatus = "";
-                  clearTimeout(failureDetailTimeout);
-                  failureDetailTimeout = null;
-                  void finishFromCompletion(status);
-                }
-              }
-              const method = normalizeNullableText(notification.method);
-              if (method !== "turn/completed" && method !== "thread/status/changed") {
-                return;
-              }
-              const status = codexAppServerNotificationTurnStatus(notification) || "completed";
-              if (codexAppServerTurnStatusIsProviderFailure(status)) {
-                const error = new Error(codexAppServerNotificationError(notification) || `Codex app-server turn ${status}.`);
-                if (!targetTurnId) {
-                  pendingFailure = error;
-                  return;
-                }
-                failAfterDetailGrace(error);
-                return;
-              }
-              if (codexAppServerTurnStatusIsSuccessfulComplete(status)) {
-                void finishFromCompletion(status);
-              }
-            })
-          : null;
       });
-    }
-  };
+    });
+  }
+
+  return Object.freeze({
+    completeNow: finishFromCompletion,
+    failNow: fail,
+    failAfterDetailGrace,
+    // readable-check: allow setter-seam - not a slot: setTurnId records the turn identity that startup acknowledges after wait() has subscribed
+    setTurnId,
+    wait
+  });
 }
 
 function codexAppServerTurnError(reason, details = {}, providerMessage = "") {
@@ -276,6 +303,15 @@ function codexAppServerTurnError(reason, details = {}, providerMessage = "") {
   return error;
 }
 
+/**
+ * Waits for an already started native turn and returns its final answer.
+ * @param {CodexDetachedTurnProvider} provider
+ * @param {string} threadId
+ * @param {object | null} turn
+ * @param {object} [options]
+ * @param {number} [options.timeoutMs]
+ * @param {typeof codexAppServerTurnError} [options.createError]
+ */
 async function waitForCodexAppServerTurn(provider, threadId = "", turn = null, {
   timeoutMs = CODEX_APP_SERVER_DETACHED_TURN_TIMEOUT_MS,
   createError = codexAppServerTurnError
@@ -313,7 +349,7 @@ async function waitForCodexAppServerTurn(provider, threadId = "", turn = null, {
   void pending.catch(() => null);
   if (codexAppServerTurnStatusIsSuccessfulComplete(status)) {
     await watcher.completeNow(status);
-  } else if (typeof provider?.readThread === "function") {
+  } else {
     const latestThread = await provider.readThread(normalizedThreadId);
     const latestTurn = codexAppServerProviderTurnForOperation(latestThread, { turnId });
     const latestStatus = codexAppServerProviderTurnStatus(latestTurn || {});
@@ -330,4 +366,9 @@ async function waitForCodexAppServerTurn(provider, threadId = "", turn = null, {
   return pending;
 }
 
-export { CODEX_APP_SERVER_DETACHED_TURN_TIMEOUT_MS, createCodexAppServerDetachedTurnWatcher, waitForCodexAppServerTurn };
+export {
+  CODEX_APP_SERVER_DETACHED_TURN_TIMEOUT_MS,
+  createCodexAppServerDetachedTurnWatcher,
+  ignoreCodexDetachedTurnEvent,
+  waitForCodexAppServerTurn
+};