@jskit-ai/assistant-core 0.2.7 → 0.2.8

package/src/server/lib/aiConnectionClient.js

@@ -64,32 +64,42 @@ export function createAiConnectionClient(connection, { fetch, timeoutMs = 120_00
       abortSignal: signal, timeout: timeoutMs, maxRetries: 0, temperature, maxOutputTokens, reasoning: effort
     };
   }
-  return Object.freeze({
-    enabled: true, supportsAttachments: true, provider: connection.providerId, defaultModel: connection.model,
-    async createChatCompletion(input) {
-      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) } })) }, finish_reason: result.finishReason }] };
-    },
-    async *createChatCompletionStream(input) {
-      const result = streamText({ ...options(input), onError() {} });
-      let toolIndex = 0;
-      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.");
-        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") {
-          // Only the application catalogue can reject an unavailable action
-          // and persist its no-effect receipt. Other invalid calls stay errors.
-          const unavailable = reportUnavailableToolCalls === true && NoSuchToolError.isInstance(part.error) &&
-            !part.providerExecuted && part.input !== null && typeof part.input === "object" && !Array.isArray(part.input);
-          if (part.invalid && !unavailable) throw part.error;
-          yield { choices: [{ delta: { tool_calls: [{ index: toolIndex++, id: part.toolCallId,
-            function: { name: part.toolName, arguments: JSON.stringify(part.input) } }] } }] };
-        }
+
+  async function createChatCompletion(input) {
+    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) } })) }, finish_reason: result.finishReason }] };
+  }
+
+  async function* createChatCompletionStream(input) {
+    const result = streamText({ ...options(input), onError() {} });
+    let toolIndex = 0;
+    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.");
+      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") {
+        // Only the application catalogue can reject an unavailable action
+        // and persist its no-effect receipt. Other invalid calls stay errors.
+        const unavailable = reportUnavailableToolCalls === true && NoSuchToolError.isInstance(part.error) &&
+          !part.providerExecuted && part.input !== null && typeof part.input === "object" && !Array.isArray(part.input);
+        if (part.invalid && !unavailable) throw part.error;
+        yield { choices: [{ delta: { tool_calls: [{ index: toolIndex++, id: part.toolCallId,
+          function: { name: part.toolName, arguments: JSON.stringify(part.input) } }] } }] };
       }
     }
+  }
+
+  return Object.freeze({
+    enabled: true,
+    supportsAttachments: true,
+    provider: connection.providerId,
+    defaultModel: connection.model,
+    // The AI SDK model itself, for the agent engine's loop.
+    model,
+    createChatCompletion,
+    createChatCompletionStream
   });
 }

package/src/server/lib/ndjson.js

@@ -7,6 +7,7 @@ function setNdjsonHeaders(reply) {
   reply.header("Cache-Control", "no-cache");
   reply.header("X-Accel-Buffering", "no");
 
+  // readable-check: allow method-probe - platform object: a Fastify reply's raw Node response, when it has one
   if (reply?.raw && typeof reply.raw.setHeader === "function") {
     reply.raw.setHeader("Content-Type", NDJSON_CONTENT_TYPE);
     reply.raw.setHeader("Cache-Control", "no-cache");

package/src/server/lib/providers/anthropicClient.js

@@ -297,6 +297,10 @@ async function fetchAnthropicMessage({
   }
 }
 
+/**
+ * An assistant client for Anthropic's Messages API, or a disabled client without a key.
+ * @param {{ enabled?: boolean, apiKey?: string, baseUrl?: string, model?: string, timeoutMs?: number }} [options]
+ */
 function createAnthropicClient({
   enabled = true,
   apiKey = "",
@@ -339,17 +343,22 @@ function createAnthropicClient({
     };
   }
 
+  const streaming = createAiConnectionClient({
+    providerId: "anthropic", sdkPackage: "@ai-sdk/anthropic", apiKey: normalizedApiKey,
+    model: normalizedModel, baseURL: `${normalizedBaseUrl}/v1`
+  }, { timeoutMs, maxOutputTokens: DEFAULT_ANTHROPIC_MAX_OUTPUT_LIMIT });
+
+  function createChatCompletionStream(input) {
+    return streaming.createChatCompletionStream({ temperature: 0.2, ...input });
+  }
+
   return Object.freeze({
     enabled: true,
     provider: "anthropic",
     defaultModel: normalizedModel,
+    model: streaming.model,
     createChatCompletion: createCompletion,
-    createChatCompletionStream(input) {
-      return createAiConnectionClient({
-        providerId: "anthropic", sdkPackage: "@ai-sdk/anthropic", apiKey: normalizedApiKey,
-        model: normalizedModel, baseURL: `${normalizedBaseUrl}/v1`
-      }, { timeoutMs, maxOutputTokens: DEFAULT_ANTHROPIC_MAX_OUTPUT_LIMIT }).createChatCompletionStream({ temperature: 0.2, ...input });
-    }
+    createChatCompletionStream
   });
 }
 

package/src/server/lib/providers/common.js

@@ -61,16 +61,20 @@ function createDisabledClient({ provider = DEFAULT_AI_PROVIDER, model = "" } = {
     throw new AppError(503, "Assistant provider is not configured.", { code: "assistant.provider.notConfigured" });
   };
 
+  async function createChatCompletion() {
+    disabledError();
+  }
+
+  async function createChatCompletionStream() {
+    disabledError();
+  }
+
   return Object.freeze({
     enabled: false,
     provider,
     defaultModel: model,
-    async createChatCompletion() {
-      disabledError();
-    },
-    async createChatCompletionStream() {
-      disabledError();
-    }
+    createChatCompletion,
+    createChatCompletionStream
   });
 }
 

package/src/server/lib/providers/openAiCompatibleClient.js

@@ -1,4 +1,6 @@
 import OpenAI from "openai";
+import { createOpenAI } from "@ai-sdk/openai";
+import { chatModel } from "@jskit-ai/agent/server";
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import {
   createDisabledClient,
@@ -7,6 +9,11 @@ import {
   normalizeTimeoutMs
 } from "./common.js";
 
+/**
+ * An assistant client for an OpenAI-compatible chat completions API, or a disabled client without a key.
+ * @param {{ enabled?: boolean, apiKey?: string, baseUrl?: string, model?: string, defaultModel?: string, provider?: string,
+ *   timeoutMs?: number }} [options]
+ */
 function createOpenAiCompatibleClient({
   enabled = true,
   apiKey = "",
@@ -36,33 +43,43 @@ function createOpenAiCompatibleClient({
     timeout: normalizeTimeoutMs(timeoutMs)
   });
 
-  return Object.freeze({
-    enabled: true,
-    provider: normalizedProvider,
-    defaultModel: normalizedModel,
-    async createChatCompletion({ messages = [], tools = [], temperature = 0, signal } = {}) {
-      const requestPayload = {
+  const baseURL = normalizedBaseUrl || undefined;
+
+  async function createChatCompletion({ messages = [], tools = [], temperature = 0, signal } = {}) {
+    const requestPayload = {
+      model: normalizedModel,
+      messages,
+      ...(Array.isArray(tools) && tools.length > 0 ? { tools } : {}),
+      temperature,
+      stream: false
+    };
+
+    return client.chat.completions.create(requestPayload, signal ? { signal } : undefined);
+  }
+
+  async function createChatCompletionStream({ messages = [], tools = [], signal, temperature = 0.2 } = {}) {
+    return client.chat.completions.create(
+      {
         model: normalizedModel,
         messages,
-        ...(Array.isArray(tools) && tools.length > 0 ? { tools } : {}),
+        tools,
         temperature,
-        stream: false
-      };
+        stream: true
+      },
+      signal ? { signal } : undefined
+    );
+  }
 
-      return client.chat.completions.create(requestPayload, signal ? { signal } : undefined);
-    },
-    async createChatCompletionStream({ messages = [], tools = [], signal, temperature = 0.2 } = {}) {
-      return client.chat.completions.create(
-        {
-          model: normalizedModel,
-          messages,
-          tools,
-          temperature,
-          stream: true
-        },
-        signal ? { signal } : undefined
-      );
-    }
+  return Object.freeze({
+    enabled: true,
+    provider: normalizedProvider,
+    defaultModel: normalizedModel,
+    // The same endpoint as an AI SDK model, for the agent engine's loop.
+    model: normalizedProvider === "deepseek"
+      ? chatModel({ apiKey: normalizedApiKey, model: normalizedModel, baseURL })
+      : createOpenAI({ apiKey: normalizedApiKey, baseURL }).chat(normalizedModel),
+    createChatCompletion,
+    createChatCompletionStream
   });
 }
 

package/src/server/lib/serviceToolCatalog.js

@@ -1,16 +1,13 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
 import { requireAuth } from "@jskit-ai/kernel/server/runtime";
 import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
 import { normalizePositiveInteger, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
-import {
-  resolveSchemaTransportSchemaDefinition,
-  validateSchemaPayload
-} from "@jskit-ai/kernel/shared/validators";
+import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
 import { resolveWorkspaceSlug } from "./resolveWorkspaceSlug.js";
+import { AUTOMATION_CHANNEL, normalizePermissionSpec, resolveActionToolEntries } from "./serviceToolEntries.js";
 
-const AUTOMATION_CHANNEL = "automation";
 const DEFAULT_MAX_DIRECT_TOOLS = 32;
 const MAX_ALWAYS_AVAILABLE_TOOLS = 8;
-const MAX_PREFLIGHT_INTENTS_PER_TOOL = 8;
 const DEFAULT_DISCOVERY_PAGE_SIZE = 10;
 const MAX_DISCOVERY_PAGE_SIZE = 20;
 const DEFAULT_MAX_TOOL_ARGUMENT_BYTES = 32 * 1024;
@@ -143,122 +140,6 @@ const DISCOVERY_TOOL_DESCRIPTORS = Object.freeze([
   })
 ]);
 
-function normalizePreflightIntents(value) {
-  const source = Array.isArray(value) ? value : [value];
-  const normalized = source
-    .map((entry) => normalizeText(entry).toLowerCase())
-    .filter(Boolean);
-  return Object.freeze([...new Set(normalized)].slice(0, MAX_PREFLIGHT_INTENTS_PER_TOOL));
-}
-
-function normalizeAssistantExtension(value) {
-  const source = value && typeof value === "object" && !Array.isArray(value) ? value : {};
-  if (source.transformResult != null && typeof source.transformResult !== "function") {
-    throw new TypeError("extensions.assistant.transformResult must be a function when provided.");
-  }
-
-  return Object.freeze({
-    description: normalizeText(source.description),
-    exclude: normalizeText(source.exclude),
-    alwaysAvailable: source.alwaysAvailable === true,
-    preflight: normalizePreflightIntents(source.preflight),
-    output: Object.hasOwn(source, "output") ? source.output : null,
-    transformResult: typeof source.transformResult === "function" ? source.transformResult : null
-  });
-}
-
-function normalizeAssistantActionExtension(action = {}) {
-  const source = action && typeof action === "object" && !Array.isArray(action) ? action : {};
-  const actionId = normalizeText(source.id);
-
-  if (Object.prototype.hasOwnProperty.call(source, "assistantTool")) {
-    throw new Error(
-      `Action definition \"${actionId || "<unknown>"}\" assistantTool is not supported. Use extensions.assistant instead.`
-    );
-  }
-
-  const extensions = source.extensions && typeof source.extensions === "object" && !Array.isArray(source.extensions)
-    ? source.extensions
-    : {};
-  return normalizeAssistantExtension(extensions.assistant);
-}
-
-function normalizeBarredEntry(value) {
-  return normalizeText(value).toLowerCase();
-}
-
-function normalizeBarredActionSet(value) {
-  const source = Array.isArray(value) ? value : [value];
-  const exact = new Set();
-  const prefixes = [];
-
-  for (const entry of source) {
-    const normalized = normalizeBarredEntry(entry);
-    if (!normalized) {
-      continue;
-    }
-
-    if (normalized.endsWith(".*")) {
-      const prefix = normalized.slice(0, -1);
-      if (prefix) {
-        prefixes.push(prefix);
-      }
-      continue;
-    }
-
-    exact.add(normalized);
-  }
-
-  return Object.freeze({
-    exact,
-    prefixes: Object.freeze(prefixes)
-  });
-}
-
-function isActionBarred(barredRules, actionId) {
-  const normalizedActionId = normalizeText(actionId).toLowerCase();
-  if (!normalizedActionId) {
-    return true;
-  }
-
-  if (barredRules.exact.has(normalizedActionId)) {
-    return true;
-  }
-
-  return barredRules.prefixes.some((prefix) => normalizedActionId.startsWith(prefix));
-}
-
-function sanitizeToolName(value) {
-  const normalized = String(value || "")
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9_]+/g, "_")
-    .replace(/_+/g, "_")
-    .replace(/^_+|_+$/g, "");
-
-  if (!normalized) {
-    return "tool";
-  }
-
-  return normalized;
-}
-
-function resolveUniqueToolName(baseName, used) {
-  const normalizedBase = sanitizeToolName(baseName) || "tool";
-  let candidate = normalizedBase.slice(0, 64);
-  let suffix = 1;
-
-  while (used.has(candidate)) {
-    const suffixText = `_${suffix}`;
-    const baseBudget = Math.max(1, 64 - suffixText.length);
-    candidate = `${normalizedBase.slice(0, baseBudget)}${suffixText}`;
-    suffix += 1;
-  }
-
-  used.add(candidate);
-  return candidate;
-}
-
 // Empty arguments mean "no input"; anything else must be one JSON object, so a
 // truncated or malformed call fails instead of running the action with {}.
 function parseToolPayload(argumentsText) {
@@ -293,11 +174,7 @@ function serializedByteLength(value) {
 }
 
 function createToolError(status, code, message) {
-  const error = new Error(message);
-  error.status = status;
-  error.statusCode = status;
-  error.code = code;
-  return error;
+  return new AppError(status, message, { code });
 }
 
 function ensureSerializedSize(value, maxBytes, { code = "assistant_tool_result_too_large", label = "Tool result" } = {}) {
@@ -411,21 +288,6 @@ function canInvokeMethod(permission, context) {
   }
 }
 
-function normalizePermissionSpec(permission) {
-  const source = permission && typeof permission === "object" && !Array.isArray(permission)
-    ? permission
-    : {};
-  const requireMode = normalizeText(source.require || "none").toLowerCase();
-  const permissions = Array.isArray(source.permissions) ? source.permissions : [];
-
-  return Object.freeze({
-    require: requireMode || "none",
-    permissions,
-    message: normalizeText(source.message),
-    code: normalizeText(source.code)
-  });
-}
-
 function stripWorkspaceSlugFromSchema(schema, context = {}) {
   if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
     return schema;
@@ -457,31 +319,13 @@ function stripWorkspaceSlugFromSchema(schema, context = {}) {
   };
 }
 
-function hasAutomationChannel(action = {}) {
-  const channels = Array.isArray(action.channels) ? action.channels : [];
-  return channels.some((channel) => normalizeText(channel).toLowerCase() === AUTOMATION_CHANNEL);
-}
-
-function normalizeSurfaceList(value) {
-  const source = Array.isArray(value) ? value : [value];
-  const resolved = [];
-
-  for (const entry of source) {
-    const normalized = normalizeSurfaceId(entry);
-    if (normalized) {
-      resolved.push(normalized);
-    }
-  }
-
-  return Object.freeze(resolved);
-}
-
 function canUseToolOnSurface(entry = {}, context = {}) {
   const toolSurfaces = Array.isArray(entry.surfaces) ? entry.surfaces : [];
   if (toolSurfaces.length < 1) {
     return true;
   }
 
+  // readable-check: allow no-optional-after-default - input validation: a caller may pass a null context
   const contextSurfaceId = normalizeSurfaceId(context?.surface);
   if (!contextSurfaceId) {
     return true;
@@ -490,125 +334,22 @@ function canUseToolOnSurface(entry = {}, context = {}) {
   return toolSurfaces.includes("*") || toolSurfaces.includes(contextSurfaceId);
 }
 
-function resolveActionBackedToolEntries(actions) {
-  if (!actions || typeof actions.listDefinitions !== "function") {
-    throw new TypeError("Assistant tool catalog requires runtime.actions.");
-  }
-  const entriesByActionId = new Map();
-  for (const action of actions.listDefinitions()) {
-    if (!action || typeof action !== "object") {
-      continue;
-    }
-    if (!hasAutomationChannel(action)) {
-      continue;
-    }
-
-    const actionId = normalizeText(action.id);
-    if (!actionId) {
-      continue;
-    }
-
-    let assistantExtension = null;
-    try {
-      assistantExtension = normalizeAssistantActionExtension(action);
-    } catch {
-      continue;
-    }
-
-    if (assistantExtension.exclude) {
-      continue;
-    }
-
-    const outputDefinition = assistantExtension.output || action.output;
-    const inputSchema = resolveSchemaTransportSchemaDefinition(action.input, {
-      context: `Action definition "${actionId}" input`,
-      defaultMode: "patch"
-    }) || null;
-    const outputSchema = resolveSchemaTransportSchemaDefinition(outputDefinition, {
-      context: `Action definition "${actionId}" assistant output`,
-      defaultMode: "replace"
-    }) || null;
-    if (!inputSchema || !outputSchema) {
-      continue;
-    }
-
-    const actionVersion = Number(action.version) || 1;
-    const actionKey = actionId.toLowerCase();
-    const nextEntry = Object.freeze({
-      actionId,
-      actionVersion,
-      kind: normalizeText(action.kind).toLowerCase() || "command",
-      toolBaseName: actionId,
-      description: assistantExtension.description || `Run ${actionId}.`,
-      alwaysAvailable: assistantExtension.alwaysAvailable,
-      preflight: assistantExtension.preflight,
-      inputSchema,
-      outputDefinition,
-      outputSchema,
-      transformResult: assistantExtension.transformResult,
-      permission: normalizePermissionSpec(action.permission),
-      surfaces: normalizeSurfaceList(action.surfaces)
-    });
-    const existing = entriesByActionId.get(actionKey);
-    if (!existing || actionVersion >= Number(existing.actionVersion || 0)) {
-      entriesByActionId.set(actionKey, nextEntry);
-    }
-  }
-
-  return entriesByActionId;
-}
-
-function resolveActionToolEntries(
-  actions,
-  { barredActionIds = [], skipActionPrefixes = [] } = {}
-) {
-  const actionBackedEntries = resolveActionBackedToolEntries(actions);
-  const barredRules = normalizeBarredActionSet(barredActionIds);
-  const usedToolNames = new Set();
-  const entries = [];
-
-  for (const actionEntry of actionBackedEntries.values()) {
-    const actionId = normalizeText(actionEntry?.actionId);
-    if (!actionId) {
-      continue;
-    }
-
-    const normalizedActionId = actionId.toLowerCase();
-    const skipByPrefix = skipActionPrefixes.some((prefix) => normalizedActionId.startsWith(prefix));
-    if (skipByPrefix) {
-      continue;
-    }
-
-    if (isActionBarred(barredRules, actionId)) {
-      continue;
-    }
-
-    const toolName = resolveUniqueToolName(actionEntry.toolBaseName, usedToolNames);
-    entries.push(
-      Object.freeze({
-        descriptor: Object.freeze({
-          name: toolName,
-          actionId,
-          actionVersion: Number(actionEntry.actionVersion) || null,
-          description: normalizeText(actionEntry.description) || `Run ${actionId}.`,
-          alwaysAvailable: actionEntry.alwaysAvailable === true,
-          preflight: actionEntry.preflight,
-          parameters: actionEntry.inputSchema,
-          outputSchema: actionEntry.outputSchema
-        }),
-        kind: actionEntry.kind,
-        acceptsWorkspaceSlug: Object.hasOwn(actionEntry.inputSchema.properties || {}, "workspaceSlug"),
-        outputDefinition: actionEntry.outputDefinition,
-        transformResult: actionEntry.transformResult,
-        permission: actionEntry.permission,
-        surfaces: actionEntry.surfaces
-      })
-    );
-  }
-
-  return Object.freeze(entries.sort((left, right) => left.descriptor.name.localeCompare(right.descriptor.name)));
-}
-
+// A tool call whose caller does not watch its failures.
+function reportNoToolFailure() {}
+
+/**
+ * The assistant tools an application's actions offer one caller: direct tools, or discovery
+ * tools when there are too many, each checked against permission, surface and policy.
+ * @param {{ listDefinitions(): object[], execute(request: object): Promise<unknown> }} actions The application's action runtime.
+ * @param {object} [options]
+ * @param {(request: { actionId: string, kind: string, context: object }) => boolean} [options.isActionAvailable]
+ * @param {string[] | string} [options.barredActionIds]
+ * @param {string[] | string} [options.skipActionPrefixes]
+ * @param {number} [options.maxDirectTools]
+ * @param {number} [options.discoveryPageSize]
+ * @param {number} [options.maxToolArgumentBytes]
+ * @param {number} [options.maxToolResultBytes]
+ */
 function createServiceToolCatalog(
   actions,
   {
@@ -621,9 +362,11 @@ function createServiceToolCatalog(
     maxToolResultBytes: rawMaxToolResultBytes = DEFAULT_MAX_TOOL_RESULT_BYTES
   } = {}
 ) {
+  // readable-check: allow method-probe - input validation: the application passes its action runtime
   if (!actions || typeof actions.listDefinitions !== "function" || typeof actions.execute !== "function") {
     throw new TypeError("createServiceToolCatalog requires runtime.actions.");
   }
+  // readable-check: allow method-probe - input validation: an optional action policy must be a function
   if (isActionAvailable !== undefined && typeof isActionAvailable !== "function") {
     throw new TypeError("isActionAvailable must be a synchronous action policy.");
   }
@@ -875,7 +618,7 @@ function createServiceToolCatalog(
     };
   }
 
-  async function executeToolCall({ toolName = "", argumentsText = "", context = {}, toolSet = null, onFailure } = {}) {
+  async function executeToolCall({ toolName = "", argumentsText = "", context = {}, toolSet = null, onFailure = reportNoToolFailure } = {}) {
     const normalizedToolName = normalizeText(toolName);
     const suppliedState = toolSet && typeof toolSet === "object" ? toolSetStates.get(toolSet) : null;
     const resolvedToolSet = suppliedState ? toolSet : resolveToolSet(context);
@@ -920,13 +663,16 @@ function createServiceToolCatalog(
         result
       };
     } catch (error) {
-      onFailure?.(error);
+      onFailure(error);
       return resolveToolFailure(error);
     }
   }
 
   return Object.freeze({
-    limits: Object.freeze({ maxToolArgumentBytes, maxToolResultBytes }),
+    limits: Object.freeze({
+      maxToolArgumentBytes,
+      maxToolResultBytes
+    }),
     resolveToolSet,
     toOpenAiToolSchema,
     executeToolCall