@jskit-ai/assistant-core 0.1.149 → 0.1.151

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-core",
-  "version": "0.1.149",
+  "version": "0.1.151",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -11,16 +11,16 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/resource-core": "0.1.115",
-    "@jskit-ai/resource-crud-core": "0.1.115",
+    "@jskit-ai/resource-core": "0.1.117",
+    "@jskit-ai/resource-crud-core": "0.1.117",
     "dompurify": "^3.4.13",
     "json-rest-schema": "^1.0.17",
     "marked": "^17.0.4",
     "openai": "^6.22.0"
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.1.171",
-    "@jskit-ai/kernel": "0.1.173",
+    "@jskit-ai/http-runtime": "0.1.173",
+    "@jskit-ai/kernel": "0.1.175",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0"
   },

package/src/client/lib/assistantApi.js

@@ -1,4 +1,5 @@
 import { appendQueryString } from "@jskit-ai/kernel/shared/support";
+import { encodeJsonApiResourceQueryObject } from "@jskit-ai/http-runtime/shared";
 import {
   ASSISTANT_CONVERSATIONS_TRANSPORT,
   ASSISTANT_CONVERSATION_MESSAGES_TRANSPORT,
@@ -30,6 +31,19 @@ function appendQueryParam(params, key, value) {
   params.set(key, normalized);
 }
 
+function createAssistantQueryParams(query = {}, transport = null) {
+  const params = new URLSearchParams();
+  const encodedQuery = encodeJsonApiResourceQueryObject(query, {
+    responseType: transport?.responseType
+  });
+
+  for (const [key, value] of Object.entries(encodedQuery)) {
+    appendQueryParam(params, key, value);
+  }
+
+  return params;
+}
+
 function normalizeSurfaceHeaderValue(value) {
   return String(value || "").trim().toLowerCase();
 }
@@ -110,10 +124,7 @@ function createAssistantApi({ request, requestStream, resolveBasePath, resolveSu
 
     listConversations(query = {}) {
       const basePath = resolveRequiredBasePath(resolveBasePath);
-      const params = new URLSearchParams();
-      appendQueryParam(params, "cursor", query.cursor);
-      appendQueryParam(params, "limit", query.limit);
-      appendQueryParam(params, "status", query.status);
+      const params = createAssistantQueryParams(query, ASSISTANT_CONVERSATIONS_TRANSPORT);
       const requestHeaders = resolveAssistantRequestHeaders(resolveSurfaceId);
 
       return request(
@@ -128,9 +139,7 @@ function createAssistantApi({ request, requestStream, resolveBasePath, resolveSu
     getConversationMessages(conversationId, query = {}) {
       const basePath = resolveRequiredBasePath(resolveBasePath);
       const encodedConversationId = encodeURIComponent(String(conversationId || "").trim());
-      const params = new URLSearchParams();
-      appendQueryParam(params, "page", query.page);
-      appendQueryParam(params, "pageSize", query.pageSize);
+      const params = createAssistantQueryParams(query, ASSISTANT_CONVERSATION_MESSAGES_TRANSPORT);
       const requestHeaders = resolveAssistantRequestHeaders(resolveSurfaceId);
 
       return request(

package/src/server/lib/serviceToolCatalog.js

@@ -9,6 +9,8 @@ import { resolveWorkspaceSlug } from "./resolveWorkspaceSlug.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;
@@ -141,6 +143,14 @@ 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") {
@@ -149,6 +159,8 @@ function normalizeAssistantExtension(value) {
 
   return Object.freeze({
     description: normalizeText(source.description),
+    alwaysAvailable: source.alwaysAvailable === true,
+    preflight: normalizePreflightIntents(source.preflight),
     output: Object.hasOwn(source, "output") ? source.output : null,
     transformResult: typeof source.transformResult === "function" ? source.transformResult : null
   });
@@ -545,6 +557,8 @@ function resolveActionBackedToolEntries(actions) {
       kind: normalizeText(action.kind).toLowerCase() || "command",
       toolBaseName: actionId,
       description: assistantExtension.description || `Run ${actionId}.`,
+      alwaysAvailable: assistantExtension.alwaysAvailable,
+      preflight: assistantExtension.preflight,
       inputSchema,
       outputDefinition,
       outputSchema,
@@ -594,6 +608,8 @@ function resolveActionToolEntries(
           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
         }),
@@ -677,8 +693,18 @@ function createServiceToolCatalog(
   function resolveToolSet(context = {}) {
     const actionEntries = resolveAuthorizedEntries(context);
     const useDiscovery = actionEntries.length > maxDirectTools;
+    const alwaysAvailableEntries = useDiscovery
+      ? actionEntries
+          .filter((entry) => entry.descriptor.alwaysAvailable === true)
+          .filter((entry) => !Object.values(DISCOVERY_TOOL_NAMES).includes(entry.descriptor.name))
+          .slice(0, MAX_ALWAYS_AVAILABLE_TOOLS)
+      : [];
+    const alwaysAvailableEntrySet = new Set(alwaysAvailableEntries);
     const tools = useDiscovery
-      ? DISCOVERY_TOOL_DESCRIPTORS.slice()
+      ? [
+          ...DISCOVERY_TOOL_DESCRIPTORS,
+          ...alwaysAvailableEntries.map((entry) => entry.descriptor)
+        ]
       : actionEntries.map((entry) => entry.descriptor);
     const byName = new Map();
     for (const descriptor of tools) {
@@ -693,7 +719,7 @@ function createServiceToolCatalog(
     const directEntriesByToolName = new Map();
     for (const entry of actionEntries) {
       actionEntriesById.set(entry.descriptor.actionId.toLowerCase(), entry);
-      if (!useDiscovery) {
+      if (!useDiscovery || alwaysAvailableEntrySet.has(entry)) {
         directEntriesByToolName.set(entry.descriptor.name, entry);
       }
     }

package/src/shared/assistantResource.js

@@ -305,6 +305,7 @@ const assistantResource = defineResource({
 export {
   MAX_INPUT_CHARS,
   MAX_HISTORY_MESSAGES,
+  MAX_MESSAGE_PAGE_SIZE,
   assistantResource,
   assistantConversationOutputValidator
 };

package/src/shared/index.js

@@ -28,6 +28,7 @@ export {
 export {
   MAX_INPUT_CHARS,
   MAX_HISTORY_MESSAGES,
+  MAX_MESSAGE_PAGE_SIZE,
   assistantResource,
   assistantConversationOutputValidator
 } from "./assistantResource.js";

package/test/assistantApiSurfaceHeader.test.js

@@ -43,10 +43,12 @@ test("assistant api forwards normalized surface header on requests", async () =>
     input: "Hello"
   });
   await api.listConversations({
-    limit: 5
+    cursor: "next-page",
+    limit: 5,
+    status: "completed"
   });
   await api.getConversationMessages(99, {
-    page: 1,
+    page: 2,
     pageSize: 5
   });
   await api.getSettings();
@@ -59,6 +61,18 @@ test("assistant api forwards normalized surface header on requests", async () =>
   assert.equal(observed.messages?.options?.headers?.["x-jskit-surface"], "admin");
   assert.equal(observed.settingsRead?.options?.headers?.["x-jskit-surface"], "admin");
   assert.equal(observed.settingsUpdate?.options?.headers?.["x-jskit-surface"], "admin");
+  const conversationsUrl = new URL(observed.list?.url, "https://assistant.test");
+  assert.equal(conversationsUrl.searchParams.get("page[cursor]"), "next-page");
+  assert.equal(conversationsUrl.searchParams.get("page[limit]"), "5");
+  assert.equal(conversationsUrl.searchParams.get("filter[status]"), "completed");
+  assert.equal(conversationsUrl.searchParams.has("cursor"), false);
+  assert.equal(conversationsUrl.searchParams.has("limit"), false);
+  assert.equal(conversationsUrl.searchParams.has("status"), false);
+  const messagesUrl = new URL(observed.messages?.url, "https://assistant.test");
+  assert.equal(messagesUrl.searchParams.get("filter[page]"), "2");
+  assert.equal(messagesUrl.searchParams.get("filter[pageSize]"), "5");
+  assert.equal(messagesUrl.searchParams.has("page"), false);
+  assert.equal(messagesUrl.searchParams.has("pageSize"), false);
   assert.deepEqual(observed.list?.options?.transport, ASSISTANT_CONVERSATIONS_TRANSPORT);
   assert.deepEqual(observed.messages?.options?.transport, ASSISTANT_CONVERSATION_MESSAGES_TRANSPORT);
   assert.deepEqual(observed.settingsRead?.options?.transport, ASSISTANT_SETTINGS_TRANSPORT);

package/test/serviceToolCatalog.test.js

@@ -249,11 +249,26 @@ test("assistant tools expose safe field-level input guidance to the model", asyn
 
 test("large authorized catalogs use compact paged discovery, exact contracts, and gated execution", async () => {
   const executions = [];
+  let clockExecution = null;
   const workspaceInput = schema({
     workspaceSlug: { type: "string", required: true },
     q: { type: "string", required: false }
   });
   const definitions = [
+    action({
+      id: "demo.clock.read",
+      input: workspaceInput,
+      extensions: {
+        assistant: {
+          alwaysAvailable: true,
+          preflight: ["CURRENT-TIME", "current-time"]
+        }
+      },
+      execute: async (input, context) => {
+        clockExecution = { input, context };
+        return { ok: true };
+      }
+    }),
     action({
       id: "demo.books.list",
       input: workspaceInput,
@@ -284,8 +299,24 @@ test("large authorized catalogs use compact paged discovery, exact contracts, an
   assert.deepEqual(toolSet.tools.map((entry) => entry.name), [
     "assistant_action_search",
     "assistant_action_contract",
-    "assistant_action_execute"
+    "assistant_action_execute",
+    "demo_clock_read"
   ]);
+  const clockTool = toolSet.tools.find((entry) => entry.actionId === "demo.clock.read");
+  assert.deepEqual(clockTool.preflight, ["current-time"]);
+  assert.equal(clockTool.alwaysAvailable, true);
+  assert.equal(clockTool.parameters.required?.includes("workspaceSlug") || false, false);
+  assert.deepEqual(await catalog.executeToolCall({
+    toolName: clockTool.name,
+    argumentsText: "{}",
+    context,
+    toolSet
+  }), {
+    ok: true,
+    result: { ok: true }
+  });
+  assert.deepEqual(clockExecution.input, { workspaceSlug: "library" });
+  assert.equal(clockExecution.context.channel, "automation");
 
   const firstPage = await catalog.executeToolCall({
     toolName: "assistant_action_search",
@@ -379,6 +410,44 @@ test("large authorized catalogs use compact paged discovery, exact contracts, an
   assert.equal(executions[0].context.channel, "automation");
 });
 
+test("discovery mode bounds authorized always-available tools", () => {
+  const definitions = Array.from({ length: 10 }, (_, index) => action({
+    id: `demo.clock-${String(index + 1).padStart(2, "0")}.read`,
+    extensions: {
+      assistant: {
+        alwaysAvailable: true,
+        preflight: ["current-time"]
+      }
+    }
+  }));
+  definitions.push(action({
+    id: "demo.clock-denied.read",
+    permission: { require: "all", permissions: ["clock.read"] },
+    extensions: {
+      assistant: {
+        alwaysAvailable: true,
+        preflight: ["current-time"]
+      }
+    }
+  }));
+
+  const toolSet = createServiceToolCatalog(createActions(definitions), {
+    maxDirectTools: 0
+  }).resolveToolSet({ actor: { id: "7" }, surface: "admin" });
+
+  assert.deepEqual(toolSet.tools.slice(0, 3).map((entry) => entry.name), [
+    "assistant_action_search",
+    "assistant_action_contract",
+    "assistant_action_execute"
+  ]);
+  assert.equal(toolSet.tools.length, 11);
+  assert.deepEqual(
+    toolSet.tools.slice(3).map((entry) => entry.actionId),
+    definitions.slice(0, 8).map((entry) => entry.id)
+  );
+  assert.equal(toolSet.tools.some((entry) => entry.actionId === "demo.clock-denied.read"), false);
+});
+
 test("discovery pages and persisted tool results stay within configured bounds", async () => {
   const definitions = Array.from({ length: 25 }, (_, index) => action({
     id: `demo.items.action-${String(index + 1).padStart(2, "0")}`