@jskit-ai/assistant-core 0.1.164 → 0.1.166

package/src/server/conversation/codexTurn.js

@@ -0,0 +1,280 @@
+import { normalizeText, isPlainObject } from "./normalize.js";
+import { classifyCodexAppServerEvent, codexAppServerNotificationParams, codexAppServerNotificationThreadId, codexAppServerNotificationTurnId, codexAppServerNotificationTurnStatus, codexAppServerNotificationError, codexAppServerStatusFromValue, codexAppServerProviderThreadAssistantSegments } from "./codexEvents.js";
+const CODEX_APP_SERVER_DETACHED_TURN_TIMEOUT_MS = 180_000;
+const CODEX_APP_SERVER_DETACHED_FAILURE_DETAIL_GRACE_MS = 500;
+
+function codexAppServerTurnStatusIsActive(status = "") {
+  return normalizeText(status) === "inProgress";
+}
+
+function codexAppServerTurnStatusIsComplete(status = "") {
+  return ["completed", "interrupted", "failed"].includes(normalizeText(status));
+}
+
+function codexAppServerTurnStatusIsSuccessfulComplete(status = "") {
+  return normalizeText(status) === "completed";
+}
+
+function codexAppServerTurnStatusIsProviderFailure(status = "") {
+  return ["failed", "interrupted"].includes(normalizeText(status));
+}
+
+function codexAppServerTurnTokenUsage(notification = {}) {
+  if (normalizeText(notification.method) !== "thread/tokenUsage/updated") {
+    return null;
+  }
+  const params = codexAppServerNotificationParams(notification);
+  const tokenUsage = isPlainObject(params.tokenUsage) ? params.tokenUsage : {};
+  const turnUsage = isPlainObject(tokenUsage.last) ? tokenUsage.last : tokenUsage;
+  const snapshot = {};
+  for (const field of [
+    "cachedInputTokens",
+    "cacheWriteInputTokens",
+    "inputTokens",
+    "outputTokens",
+    "reasoningOutputTokens",
+    "totalTokens"
+  ]) {
+    const value = Number(turnUsage[field]);
+    if (Number.isSafeInteger(value) && value >= 0) {
+      snapshot[field] = value;
+    }
+  }
+  return Object.keys(snapshot).length ? Object.freeze(snapshot) : null;
+}
+
+function createCodexAppServerDetachedTurnWatcher(provider = null, threadId = "", {
+  includeThreadHistory = true,
+  onEvent = null,
+  timeoutMs = CODEX_APP_SERVER_DETACHED_TURN_TIMEOUT_MS
+} = {}) {
+  const normalizedThreadId = normalizeText(threadId);
+  let targetTurnId = "";
+  let finalText = "";
+  let usage = null;
+  let failureDetailTimeout = null;
+  let settled = false;
+  let timeout = null;
+  let connectionCheck = null;
+  let unsubscribe = null;
+  let pendingCompletionStatus = "";
+  let pendingFailure = null;
+  let resolveWaiter = null;
+  let rejectWaiter = null;
+
+  function cleanup() {
+    clearTimeout(timeout);
+    timeout = null;
+    clearInterval(connectionCheck);
+    connectionCheck = null;
+    clearTimeout(failureDetailTimeout);
+    failureDetailTimeout = null;
+    unsubscribe?.();
+    unsubscribe = null;
+  }
+
+  function finish(result = {}) {
+    if (settled) {
+      return;
+    }
+    settled = true;
+    cleanup();
+    resolveWaiter?.(result);
+  }
+
+  function fail(error) {
+    if (settled) {
+      return;
+    }
+    settled = true;
+    cleanup();
+    rejectWaiter?.(error);
+  }
+
+  function emitWatcherEvent(classification = {}) {
+    if (typeof onEvent !== "function" || !classification?.kind) {
+      return;
+    }
+    onEvent({
+      ...classification,
+      threadId: classification.threadId || normalizedThreadId,
+      turnId: classification.turnId || targetTurnId
+    });
+  }
+
+  async function resultFromThread() {
+    if (
+      !includeThreadHistory ||
+      !normalizedThreadId ||
+      !targetTurnId ||
+      typeof provider?.readThread !== "function"
+    ) {
+      return {
+        status: "",
+        statusType: "",
+        text: ""
+      };
+    }
+    const thread = await provider.readThread(normalizedThreadId);
+    const rawStatus = thread.raw?.status || thread.response?.thread?.status;
+    return {
+      status: codexAppServerStatusFromValue(rawStatus),
+      statusType: normalizeText(typeof rawStatus === "string" ? rawStatus : rawStatus?.type),
+      text: codexAppServerProviderThreadAssistantSegments(thread, targetTurnId)
+        .map((segment) => segment.text)
+        .join("\n\n")
+    };
+  }
+
+  function failAfterDetailGrace(error) {
+    if (settled || failureDetailTimeout) {
+      return;
+    }
+    failureDetailTimeout = setTimeout(() => {
+      failureDetailTimeout = null;
+      fail(error);
+    }, CODEX_APP_SERVER_DETACHED_FAILURE_DETAIL_GRACE_MS);
+  }
+
+  async function finishFromCompletion(status = "completed") {
+    try {
+      if (!targetTurnId) {
+        pendingCompletionStatus = normalizeText(status) || "completed";
+        return;
+      }
+      const authoritative = await resultFromThread().catch(() => ({
+        status: "",
+        statusType: "",
+        text: ""
+      }));
+      finalText = authoritative.text || finalText;
+      if (!finalText) {
+        pendingCompletionStatus = normalizeText(status) || "completed";
+        const systemError = authoritative.statusType === "systemError" || authoritative.status === "failed";
+        failAfterDetailGrace(new Error(systemError
+          ? "Codex app-server thread entered a system error before producing an assistant response."
+          : "Codex app-server completed without producing an assistant response."));
+        return;
+      }
+      finish({
+        status,
+        text: finalText,
+        threadId: normalizedThreadId,
+        turnId: targetTurnId,
+        usage
+      });
+    } catch (error) {
+      fail(error);
+    }
+  }
+
+  function notificationMatches(notification = {}) {
+    const notificationThreadId = codexAppServerNotificationThreadId(notification);
+    if (notificationThreadId && notificationThreadId !== normalizedThreadId) {
+      return false;
+    }
+    const notificationTurnId = codexAppServerNotificationTurnId(notification);
+    return !targetTurnId || !notificationTurnId || notificationTurnId === targetTurnId;
+  }
+
+  return {
+    async completeNow(status = "completed") {
+      await finishFromCompletion(status);
+    },
+    failNow(error) {
+      fail(error);
+    },
+    failAfterDetailGrace(error) {
+      failAfterDetailGrace(error);
+    },
+    setTurnId(turnId = "") {
+      targetTurnId = normalizeText(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."));
+      }
+      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 = typeof provider?.subscribe === "function"
+          ? provider.subscribe((notification = {}) => {
+              if (!notificationMatches(notification)) {
+                return;
+              }
+              usage = codexAppServerTurnTokenUsage(notification) || usage;
+              const classification = classifyCodexAppServerEvent(notification);
+              emitWatcherEvent(classification);
+              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 = normalizeText(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;
+      });
+    }
+  };
+}
+
+export { createCodexAppServerDetachedTurnWatcher, codexAppServerTurnStatusIsActive, codexAppServerTurnStatusIsComplete, codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure };

package/src/server/conversation/index.js

@@ -0,0 +1,2 @@
+export { createConversationTranscript } from "./transcript.js";
+export { createMemoryConversationStorage } from "./memoryStorage.js";

package/src/server/conversation/memoryStorage.js

@@ -0,0 +1,76 @@
+/** Reference adapter for transient conversations. Scope must be an app-issued string. */
+export function createMemoryConversationStorage() {
+  const conversations = new Map();
+  const pending = new Map();
+
+  function key(scope) {
+    if (typeof scope !== "string" || !scope.trim()) throw new TypeError("Conversation scope must be a nonempty string.");
+    return scope;
+  }
+
+  function transaction(turns) {
+    return {
+      async listTurnIds() { return [...turns.keys()]; },
+      async nextTurnId() { return String(Math.max(0, ...[...turns.keys()].map(Number).filter(Number.isSafeInteger)) + 1).padStart(6, "0"); },
+      async hasMessage(id) {
+        return Boolean(id) && [...turns.values()].some((turn) => turn.messages.some((message) => message.messageId === id));
+      },
+      async readTurn(id) {
+        const turn = turns.get(id);
+        if (!turn) return null;
+        const find = (role) => turn.messages.find((message) => message.role === role) || null;
+        const thinking = turn.messages.filter((message) => message.role === "thinking");
+        const commentary = turn.messages.filter((message) => message.role === "commentary");
+        const activity = [...thinking, ...commentary].sort((a, b) => a.at.localeCompare(b.at));
+        const system = find("system"), user = find("user"), assistant = find("assistant");
+        return structuredClone({
+          turnId: id, user, assistant, thinking, commentary,
+          ...(system ? { system } : {}), ...(turn.metadata ? { metadata: turn.metadata } : {}),
+          messages: [system, user, ...activity, assistant].filter(Boolean)
+        });
+      },
+      async appendMessage(id, { turnMetadata, ...message }) {
+        const turn = turns.get(id) || { messages: [] };
+        if (turnMetadata) turn.metadata = structuredClone(turnMetadata);
+        turn.messages.push(structuredClone(message));
+        turns.set(id, turn);
+      },
+      async replaceAssistant(id, message) {
+        if (!id) throw new TypeError("Assistant replacement requires a turn id.");
+        const turn = turns.get(id) || { messages: [] };
+        const previous = turn.messages.find((entry) => entry.role === "assistant");
+        turn.messages = turn.messages.filter((entry) => entry.role !== "assistant");
+        turn.messages.push({ ...previous, ...structuredClone(message), at: previous?.at || message.at });
+        turns.set(id, turn);
+      }
+    };
+  }
+
+  async function write(scope, callback, remove = false) {
+    const id = key(scope);
+    const previous = pending.get(id) || Promise.resolve();
+    const operation = previous.then(async () => {
+      const draft = structuredClone(conversations.get(id) || new Map());
+      const result = await callback(transaction(draft));
+      if (remove) conversations.delete(id);
+      else conversations.set(id, draft);
+      return result;
+    });
+    const settled = operation.then(() => undefined, () => undefined);
+    pending.set(id, settled);
+    try { return await operation; }
+    finally { if (pending.get(id) === settled) pending.delete(id); }
+  }
+
+  return Object.freeze({
+    write,
+    async read(scope, callback) {
+      const id = key(scope);
+      await pending.get(id);
+      return callback(transaction(structuredClone(conversations.get(id) || new Map())));
+    },
+    async deleteConversation(scope) {
+      await write(scope, async () => {}, true);
+    }
+  });
+}

package/src/server/conversation/normalize.js

@@ -0,0 +1,7 @@
+export function normalizeText(value) {
+  return String(value ?? "").trim();
+}
+
+export function isPlainObject(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}