@jskit-ai/assistant-core 0.1.199 → 0.1.201

package/src/server/conversation/tools.js

@@ -0,0 +1,84 @@
+import { isDeepStrictEqual } from "node:util";
+
+const unknownOutcome = "The application operation did not return a verified result. Inspect its target before requesting another execution.";
+
+/** One turn's application calls. Native/API adapters only transport these calls. */
+export function createConversationTools({ catalog, context, signal: turnSignal, previousCalls = [], authorize, save, emit,
+  maximumCalls = 32, discoveryOnly = false, transient = false, propagateErrors = false }) {
+  if (transient !== true && [authorize, save, emit].some(hook => typeof hook !== "function")) {
+    throw new TypeError("Conversation tools require authorization, durable save and event facilities.");
+  }
+  if (transient === true && previousCalls.length) {
+    throw new TypeError("Transient application tools cannot restore a previous execution.");
+  }
+  const toolSet = catalog.resolveToolSet(context, { discoveryOnly });
+  const calls = new Map(structuredClone(previousCalls).map(call => [call.id, call]));
+  let pending = Promise.resolve();
+  let requested = 0;
+
+  function execute(input, { signal = turnSignal } = {}) {
+    // Some native engines request tools concurrently. Keep application mutations
+    // ordered and recheck admission after each predecessor actually settles.
+    const combined = signal === turnSignal ? signal : AbortSignal.any([turnSignal, signal]);
+    const operation = pending.then(() => run(input, combined));
+    pending = operation.catch(() => {});
+    return operation;
+  }
+
+  async function run({ id, name, arguments: argumentsText }, signal) {
+    await authorize?.();
+    signal.throwIfAborted();
+    if (typeof id !== "string" || !id || id.length > 256 || typeof name !== "string" || !name || name.length > 256 ||
+        typeof argumentsText !== "string") throw new TypeError("An application tool requires its call id, name and JSON arguments.");
+    if (Buffer.byteLength(argumentsText) > catalog.limits.maxToolArgumentBytes) throw new Error("The application tool arguments exceed their size limit.");
+    const input = { id, name, arguments: argumentsText };
+    if (++requested > maximumCalls) throw new Error("The assistant reached the application tool-call limit for this turn.");
+    const recorded = calls.get(id);
+    if (recorded) {
+      if (!isDeepStrictEqual(input, { id: recorded.id, name: recorded.name, arguments: recorded.arguments })) {
+        throw new Error("This application tool call id already belongs to different arguments.");
+      }
+      if (!recorded.result || recorded.status === "unknown") {
+        throw Object.assign(new Error(unknownOutcome), { code: "conversation_tool_outcome_unknown" });
+      }
+      return structuredClone(recorded.result);
+    }
+    const call = { ...input, status: "running", at: new Date().toISOString() };
+    calls.set(id, call);
+    // Canonical calls reserve durably before the effect. Explicit transient
+    // calls retain the same once-only state only for their non-resumable lifetime.
+    try { await save?.([...calls.values()]); }
+    catch (error) { calls.delete(id); throw error; }
+    await emit?.({ type: "tool", call: structuredClone(call) });
+    try {
+      await authorize?.();
+      signal.throwIfAborted();
+    } catch (error) {
+      call.status = "not-executed";
+      call.result = { ok: false, error: { code: "conversation_tool_not_executed", message: "Execution stopped before the action began." } };
+      await save?.([...calls.values()]);
+      throw error;
+    }
+    let failed = false;
+    let failure;
+    call.result = await catalog.executeToolCall({ toolName: name, argumentsText, toolSet, context: { ...context, signal },
+      ...(propagateErrors ? { onFailure(error) { failed = true; failure = error; } } : {}) });
+    call.status = !call.result.ok && call.result.error?.status >= 500 ? "unknown" : "complete";
+    // Keep the result in memory as well: retrySave can persist it after a failed
+    // write without executing the action again or repeating model inference.
+    await save?.([...calls.values()]);
+    await emit?.({ type: "tool", call: structuredClone(call) });
+    if (failed) throw failure;
+    if (!call.result.ok && call.result.error?.status >= 500) {
+      throw Object.assign(new Error(unknownOutcome), { code: "conversation_tool_outcome_unknown" });
+    }
+    return structuredClone(call.result);
+  }
+
+  return {
+    descriptors: toolSet.tools,
+    schemas: toolSet.tools.map(catalog.toOpenAiToolSchema), execute,
+    maximumArgumentBytes: catalog.limits.maxToolArgumentBytes,
+    records: () => structuredClone([...calls.values()])
+  };
+}

package/src/server/conversation/transcript.js

@@ -1,7 +1,7 @@
 import { normalizeText } from "./normalize.js";
 
 /** Conversation policy, independent of database, filesystem, identity and HTTP. */
-export function createConversationTranscript({ storage, clock = () => new Date() } = {}) {
+export function createConversationTranscript({ storage, clock = () => new Date(), applicationTurns = false } = {}) {
   if (typeof storage?.read !== "function" || typeof storage?.write !== "function") {
     throw new TypeError("Conversation storage requires read(scope, callback) and write(scope, callback).");
   }
@@ -44,15 +44,15 @@ export function createConversationTranscript({ storage, clock = () => new Date()
     return ids.length ? transaction.readTurn(ids.at(-1)) : null;
   }
 
-  async function append(scope, role, { text = "", messageId = "", at = "", attachments = [], turnMetadata = null, requireOpenTurn = false } = {}) {
+  async function append(scope, role, { text = "", messageId = "", at = "", attachments = [], turnMetadata = null, requireOpenTurn = false, outputId = "" } = {}) {
     const messageText = normalizeText(text);
     const id = normalizeText(messageId);
-    if (!messageText) return null;
+    if (!messageText && !(role === "user" && Array.isArray(attachments) && attachments.length)) return null;
     return storage.write(scope, async (transaction) => {
       if (id && await transaction.hasMessage(id)) return null;
       const createdAt = new Date(at || clock());
       const tail = ["assistant", "commentary", "thinking"].includes(role) ? await tailTurn(transaction) : null;
-      const open = tail?.user && !tail.assistant ? tail : null;
+      const open = (tail?.user || applicationTurns && tail?.system?.origin === "application") && !tail.assistant ? tail : null;
       if (requireOpenTurn && !open) return null;
       const thinkingOnly = role === "thinking" && !open && at && tail &&
         !tail.system && !tail.user && !tail.assistant && !tail.commentary?.length &&
@@ -60,6 +60,7 @@ export function createConversationTranscript({ storage, clock = () => new Date()
       const turnId = open?.turnId || (thinkingOnly ? tail.turnId : await transaction.nextTurnId());
       await transaction.appendMessage(turnId, {
         role, text: messageText, messageId: id, at: createdAt.toISOString(),
+        ...(["assistant", "commentary", "thinking"].includes(role) && normalizeText(outputId) ? { outputId: normalizeText(outputId) } : {}),
         ...(role === "user" ? { attachments, turnMetadata } : {})
       });
       return transaction.readTurn(turnId);

package/src/server/hosts/claudeHistory.js

@@ -0,0 +1,5 @@
+export {
+  listClaudeConversationStorage,
+  readClaudeHistory,
+  retireClaudeConversationHistory
+} from "../conversation/claudeHistory.js";

package/src/server/hosts/claudeProcess.js

@@ -0,0 +1,11 @@
+export {
+  bindClaudeConversationAccount,
+  claudeCodeArguments,
+  claudeCatalogueModels,
+  claudeFlagSettings,
+  claudeModelConfiguration,
+  createClaudeAccountQueries,
+  createClaudeCodeProcess,
+  readClaudeCodeAuthStatus,
+  verifyClaudeProviderKey
+} from "../conversation/claudeProcess.js";

package/src/server/hosts/claudeTurn.js

@@ -0,0 +1,4 @@
+export {
+  createClaudeConversationOwner,
+  claudeNativeMessageId
+} from "../conversation/claudeTurn.js";

package/src/server/hosts/codexConfiguration.js

@@ -0,0 +1,20 @@
+export {
+  codexAppServerThreadSettings,
+  codexAppServerReadOnlyThreadSettings,
+  codexAppServerTurnSettings,
+  codexInteractiveArguments,
+  normalizeCodexThreadId,
+  codexAppServerProjectHookTrustConfig,
+  codexAuthOutputRequiresReconnect,
+  codexProviderConfiguration,
+  codexProviderFileConfiguration,
+  verifyCodexProviderKey,
+  codexProviderModelCatalog,
+  codexCatalogRows,
+  codexCatalogReasoningEfforts,
+  codexCatalogModels,
+  codexConfiguredModelCatalog,
+  createCodexAccountReader,
+  createCodexAppServerIsolation,
+  readCodexToolFreeConfiguration
+} from "../conversation/codexConfiguration.js";

package/src/server/hosts/codexEvents.js

@@ -0,0 +1,13 @@
+export {
+  codexContextUsageFromNotification,
+  codexAppServerContextRefreshReason,
+  codexAppServerNotificationEvent,
+  codexAppServerNotificationItemId,
+  codexAppServerNotificationTurnId,
+  codexAppServerProviderThreadAssistantSegments,
+  codexAppServerProviderThreadTurns,
+  codexAppServerProviderTurnForOperation,
+  codexAppServerProviderTurnId,
+  codexAppServerThreadError,
+  codexAppServerThreadTurnId
+} from "../conversation/codexEvents.js";

package/src/server/hosts/codexProcess.js

@@ -0,0 +1,12 @@
+export {
+  CODEX_APP_SERVER_METADATA_SCHEMA_VERSION,
+  CODEX_APP_SERVER_RUNTIME_DIR_NAME,
+  CODEX_APP_SERVER_TRANSPORT,
+  codexAppServerExecutionMode,
+  codexAppServerHelperHomeDir,
+  codexAppServerHelperWorkspaceDir,
+  codexAppServerIsHelper,
+  createCodexAppServerRuntime,
+  normalizeCodexAppServerTerminalEnv,
+  runCodexAppServerProcess
+} from "../conversation/codexProcess.js";

package/src/server/hosts/codexProvider.js

@@ -0,0 +1,23 @@
+export {
+  CODEX_APP_SERVER_INVALID_REQUEST_CODE,
+  CodexAppServerAgentProvider,
+  assertCodexAuthPreflightReady,
+  codexAppServerEndpointForTarget,
+  codexAppServerRequestIsInvalid,
+  codexAppServerRuntimeStopWasVerified,
+  codexCliResumeCommand,
+  codexRenewalThreadError,
+  codexTextInput,
+  codexTurnInput,
+  createCodexAppServerProviderOwner,
+  defineCodexRenewalThreadIds,
+  deleteCodexAppServerHelperThread,
+  deleteCodexAppServerThread,
+  ensureCodexAppServerThread,
+  inspectCodexAppServerMessageAdmission,
+  retireCodexConversationHistory,
+  resumeExactCodexAppServerThread,
+  sendCodexAppServerPrompt,
+  shellQuote,
+  startFreshCodexAppServerThread
+} from "../conversation/codexProvider.js";

package/src/server/hosts/codexTurn.js

@@ -0,0 +1,20 @@
+export {
+  codexAppServerAgentRun,
+  codexAppServerConversationTurnIsActive,
+  codexAppServerFrozenTurnInterruptResponse,
+  codexAppServerInterruptUnavailableResponse,
+  codexAppServerMessageDisplayText,
+  codexAppServerMessageText,
+  codexAppServerThreadStatus,
+  codexAppServerTurnState,
+  codexAppServerTurnStateFromAgentRun,
+  createCodexAppServerNotificationQueue,
+  createCodexAppServerRunOwner,
+  sendPreparedCodexAppServerHelperTurn
+} from "../conversation/codexTurn.js";
+
+export {
+  CODEX_HELPER_THREAD_LEDGER_SCHEMA_VERSION,
+  CODEX_HELPER_THREAD_LIFECYCLES,
+  createCodexHelperThreadLedgerOwner
+} from "../conversation/codexHelperThreadLedger.js";

package/src/server/hosts/nativeHistory.js

@@ -0,0 +1,3 @@
+export {
+  retireNativeConversation
+} from "../conversation/nativeHistoryExport.js";

package/src/server/hosts/openCodeClient.js

@@ -0,0 +1,3 @@
+export {
+  retireOpenCodeConversationHistory
+} from "../conversation/openCodeClient.js";

package/src/server/hosts/openCodeProcess.js

@@ -0,0 +1,23 @@
+export {
+  OPENCODE_EXPECTED_VERSION,
+  OPENCODE_HOST,
+  OPENCODE_READY_TIMEOUT_MS,
+  assertOpenCodeModelProvider,
+  createOpenCodeConversationPlugin,
+  createOpenCodeServerProcess,
+  createOpenCodeSharedRuntime,
+  ensureOpenCodeSession,
+  limitOpenCodeModelOutput,
+  openCodeApplicationToolSchemas,
+  openCodeConversationAgents,
+  openCodeEnvironmentForDirectory,
+  openCodeEnvironmentForSession,
+  openCodeModel,
+  openCodeProcessEnvironment,
+  openCodeServerForDirectory,
+  readOpenCodeEnvironments,
+  readOpenCodeCatalog,
+  readOpenCodeZenModelIds,
+  verifyOpenCodeApiKey,
+  sameOpenCodeSelection
+} from "../conversation/openCodeProcess.js";

package/src/server/hosts/openCodeTurn.js

@@ -0,0 +1,7 @@
+export {
+  openCodeDetachedPrompt,
+  openCodeMessageError,
+  openCodeRowsForInput,
+  openCodeStructuredOutput,
+  runOpenCodeConversationTurn
+} from "../conversation/openCodeTurn.js";

package/src/server/index.js

@@ -14,3 +14,5 @@ export {
 } from "./lib/ndjson.js";
 export { resolveWorkspaceSlug } from "./lib/resolveWorkspaceSlug.js";
 export { createServiceToolCatalog } from "./lib/serviceToolCatalog.js";
+export { consumeCompletionStream, sanitizeAssistantMessageText } from "./lib/assistantCompletion.js";
+export { runAssistantToolLoop, runBoundedAssistantToolLoop } from "./lib/assistantToolLoop.js";

package/src/server/lib/aiConnectionClient.js

@@ -47,7 +47,7 @@ function sdkMessages(messages) {
 }
 
 /** Accept only the server-side result of an authorized AI connection resolver. */
-export function createAiConnectionClient(connection, { fetch, timeoutMs = 120_000, maxOutputTokens } = {}) {
+export function createAiConnectionClient(connection, { fetch, timeoutMs = 120_000, maxOutputTokens, effort } = {}) {
   if (!connection?.apiKey || !connection.model || !Object.hasOwn(providers, connection.sdkPackage)) {
     throw new TypeError("An authorized AI connection with a supported SDK and model is required.");
   }
@@ -61,7 +61,7 @@ export function createAiConnectionClient(connection, { fetch, timeoutMs = 120_00
       tools: Object.fromEntries(tools.map(({ function: tool }) => [tool.name, {
         description: tool.description, inputSchema: jsonSchema(tool.parameters)
       }])),
-      abortSignal: signal, timeout: timeoutMs, maxRetries: 0, temperature, maxOutputTokens
+      abortSignal: signal, timeout: timeoutMs, maxRetries: 0, temperature, maxOutputTokens, reasoning: effort
     };
   }
   return Object.freeze({
@@ -70,21 +70,28 @@ export function createAiConnectionClient(connection, { fetch, timeoutMs = 120_00
       const result = await generateText(options(input));
       return { choices: [{ message: { role: "assistant", content: result.text,
         tool_calls: result.toolCalls.map(call => ({ id: call.toolCallId, type: "function",
-          function: { name: call.toolName, arguments: JSON.stringify(call.input) } })) } }] };
+          function: { name: call.toolName, arguments: JSON.stringify(call.input) } })) }, finish_reason: result.finishReason }] };
     },
     async *createChatCompletionStream(input) {
       const result = streamText({ ...options(input), onError() {} });
       let toolIndex = 0;
+      let failure;
       for await (const part of result.fullStream) {
-        if (part.type === "error") throw part.error;
-        if (part.type === "abort") throw input?.signal?.reason || new Error("Assistant request was aborted.");
+        // Let the SDK settle its stream before reporting a rejected tool call.
+        // Cancelling this iterator mid-step leaves its completion unresolved.
+        if (part.type === "error" || (part.type === "tool-call" && part.invalid)) {
+          failure ||= part.error || new Error("The model returned an invalid tool call.");
+        }
+        if (part.type === "abort") failure ||= input?.signal?.reason || new Error("Assistant request was aborted.");
+        if (failure) continue;
         if (part.type === "text-delta") yield { choices: [{ delta: { content: part.text } }] };
+        if (part.type === "finish") yield { choices: [{ delta: {}, finish_reason: part.finishReason }], usage: part.totalUsage };
         if (part.type === "tool-call") {
-          if (part.invalid) throw part.error;
           yield { choices: [{ delta: { tool_calls: [{ index: toolIndex++, id: part.toolCallId,
             function: { name: part.toolName, arguments: JSON.stringify(part.input) } }] } }] };
         }
       }
+      if (failure) throw failure;
     }
   });
 }

package/src/server/lib/assistantCompletion.js

@@ -0,0 +1,190 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+function extractTextDelta(deltaContent) {
+  if (typeof deltaContent === "string") {
+    return deltaContent;
+  }
+
+  if (!Array.isArray(deltaContent)) {
+    return "";
+  }
+
+  return deltaContent
+    .map((entry) => {
+      if (typeof entry === "string") {
+        return entry;
+      }
+      if (!entry || typeof entry !== "object") {
+        return "";
+      }
+      return String(entry.text || "");
+    })
+    .join("");
+}
+
+function sanitizeAssistantMessageText(value, { preserveWhitespace = false } = {}) {
+  let source = String(value || "");
+  if (!source) {
+    return "";
+  }
+
+  const blockPatterns = [
+    /<[^>\n]*function_calls[^>\n]*>[\s\S]*?(?:<\/[^>\n]*function_calls>|$)/gi,
+    /<[^>\n]*tool_calls?[^>\n]*>[\s\S]*?(?:<\/[^>\n]*tool_calls?[^>\n]*>|$)/gi,
+    /<[^>\n]*invoke\b[^>\n]*>[\s\S]*?(?:<\/[^>\n]*invoke>|$)/gi,
+    /<(?:analysis|reasoning|think)>[\s\S]*?(?:<\/(?:analysis|reasoning|think)>|$)/gi
+  ];
+  for (const pattern of blockPatterns) {
+    source = source.replace(pattern, " ");
+  }
+
+  const inlineTagPatterns = [
+    /<[^>\n]*invoke\b[^>]*\/>/gi,
+    /<\/?[^>\n]*invoke[^>\n]*>/gi,
+    /<\/?[^>\n]*function_calls[^>\n]*>/gi,
+    /<\/?[^>\n]*tool_calls?[^>\n]*>/gi,
+    /<\/?[^>\n]*DSML[^>\n]*>/gi
+  ];
+  for (const pattern of inlineTagPatterns) {
+    source = source.replace(pattern, " ");
+  }
+
+  if (preserveWhitespace) return source;
+
+  return source
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join("\n");
+}
+
+function parseDsmlToolCallsFromText(value = "") {
+  const source = String(value || "");
+  if (!source) {
+    return [];
+  }
+
+  const functionCallsMatch = source.match(
+    /<[^>\n]*function_calls[^>\n]*>([\s\S]*?)<\/[^>\n]*function_calls>/i
+  );
+  if (!functionCallsMatch) {
+    return [];
+  }
+
+  const blockText = String(functionCallsMatch[1] || "");
+  if (!blockText) {
+    return [];
+  }
+
+  const calls = [];
+  const invokePattern = /<[^>\n]*invoke\b([^>]*)>([\s\S]*?)<\/[^>\n]*invoke>/gi;
+  let match = invokePattern.exec(blockText);
+  while (match) {
+    const attributes = String(match[1] || "");
+    const body = normalizeText(String(match[2] || ""));
+    const quotedNameMatch =
+      attributes.match(/\bname\s*=\s*"([^"]+)"/i) || attributes.match(/\bname\s*=\s*'([^']+)'/i);
+    const bareNameMatch = attributes.match(/\bname\s*=\s*([^\s"'/>]+)/i);
+    const name = normalizeText(quotedNameMatch?.[1] || bareNameMatch?.[1]);
+    if (name) {
+      calls.push({
+        id: `dsml_tool_call_${calls.length + 1}`,
+        name,
+        arguments: body && /^[\[{]/.test(body) ? body : "{}"
+      });
+    }
+
+    match = invokePattern.exec(blockText);
+  }
+
+  return calls;
+}
+
+async function consumeCompletionStream(stream, onText = () => {}, {
+  signal, limits, preserveWhitespace = false, requireCallIds = false, callIdPrefix = ""
+} = {}) {
+  let assistantText = "";
+  let finishReason;
+  const toolCallsByIndex = new Map();
+
+  function checkToolLimits(call, count) {
+    if (!limits) return;
+    if (limits.maxToolCalls === 0) throw new Error("This conversation has no configured application tools.");
+    if (count > limits.maxToolCalls || call.name.length > 256 || call.id.length > 256 ||
+        Buffer.byteLength(call.arguments) > limits.maxToolArgumentBytes) {
+      throw new Error("The model exceeded the configured application tool-call limits.");
+    }
+  }
+
+  for await (const chunk of stream) {
+    signal?.throwIfAborted();
+    const choice = chunk?.choices?.[0] || {};
+    const delta = choice?.delta || {};
+    finishReason = choice.finish_reason || finishReason;
+
+    const textDelta = extractTextDelta(delta.content);
+    if (textDelta) {
+      assistantText += textDelta;
+      if (limits && assistantText.length > limits.maxOutputCharacters) {
+        throw new Error("The assistant exceeded the configured response limit.");
+      }
+      // An opening provider tag can be split between chunks. Keep it private
+      // until its boundary is known; complete internal blocks are stripped below.
+      const tagStart = assistantText.lastIndexOf("<");
+      const safeText = tagStart > assistantText.lastIndexOf(">") ? assistantText.slice(0, tagStart) : assistantText;
+      await onText(sanitizeAssistantMessageText(safeText, { preserveWhitespace }));
+    }
+
+    const toolCalls = Array.isArray(delta.tool_calls) ? delta.tool_calls : [];
+    for (const partialToolCall of toolCalls) {
+      const index = Number(partialToolCall?.index || 0);
+      const existing =
+        toolCallsByIndex.get(index) ||
+        {
+          id: normalizeText(partialToolCall?.id) || (requireCallIds ? "" : `tool_call_${index + 1}`),
+          name: "",
+          arguments: ""
+        };
+
+      if (partialToolCall?.id) {
+        existing.id = normalizeText(partialToolCall.id) || existing.id;
+      }
+      if (partialToolCall?.function?.name) {
+        existing.name += String(partialToolCall.function.name || "");
+      }
+      if (partialToolCall?.function?.arguments) {
+        existing.arguments += String(partialToolCall.function.arguments || "");
+      }
+
+      toolCallsByIndex.set(index, existing);
+      checkToolLimits(existing, toolCallsByIndex.size);
+    }
+  }
+
+  let toolCalls = [...toolCallsByIndex.values()].map((toolCall, index) => ({
+    id: normalizeText(toolCall.id) || (requireCallIds ? "" : `tool_call_${index + 1}`),
+    name: normalizeText(toolCall.name),
+    arguments: String(toolCall.arguments || "")
+  }));
+
+  let toolCallSource = toolCalls.length ? "structured" : "";
+  if (toolCalls.length < 1) {
+    const parsedDsmlCalls = parseDsmlToolCallsFromText(assistantText);
+    if (parsedDsmlCalls.length > 0) {
+      toolCallSource = "text";
+      toolCalls = parsedDsmlCalls.map(call => ({ ...call, id: `${callIdPrefix}${call.id}` }));
+      for (const call of toolCalls) checkToolLimits(call, toolCalls.length);
+      const visible = sanitizeAssistantMessageText(assistantText, { preserveWhitespace });
+      assistantText = preserveWhitespace ? visible : normalizeText(visible);
+    }
+  }
+
+  return {
+    assistantText,
+    toolCalls,
+    toolCallSource,
+    finishReason
+  };
+}
+
+export { consumeCompletionStream, sanitizeAssistantMessageText };