@jskit-ai/assistant-core 0.1.142 → 0.1.144

package/test/assistantScroll.browser.test.js

@@ -0,0 +1,139 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import process from "node:process";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { chromium, expect } from "@playwright/test";
+import {
+  createChromiumLaunchOptions,
+  startViteFixture,
+  stopProcess
+} from "../../../tooling/testUtils/browserFixture.mjs";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURE_ROOT = path.resolve(TEST_DIRECTORY, "../fixtures/responsive-assistant");
+const RUN_BROWSER_TEST = process.env.JSKIT_ASSISTANT_CORE_BROWSER_INTEGRATION === "1";
+const VIEWPORTS = Object.freeze([
+  Object.freeze({ name: "phone", width: 390, height: 844, sidePanelsVisible: false }),
+  Object.freeze({ name: "compact", width: 800, height: 900, sidePanelsVisible: false }),
+  Object.freeze({ name: "medium", width: 1224, height: 900, sidePanelsVisible: true }),
+  Object.freeze({ name: "expanded", width: 1365, height: 900, sidePanelsVisible: true })
+]);
+
+async function readLayoutMetrics(page) {
+  return page.evaluate(() => {
+    const root = document.querySelector(".assistant-client-element");
+    const layout = document.querySelector(".assistant-layout");
+    const mainColumn = document.querySelector(".assistant-main-col");
+    const sideColumn = document.querySelector(".assistant-side-col");
+    const messages = document.querySelector(".messages-panel");
+    const composer = document.querySelector(".assistant-composer-shell");
+    const history = document.querySelector(".assistant-history-card");
+    const tools = document.querySelector(".assistant-tools-card");
+    const rect = (element) => element?.getBoundingClientRect() || null;
+
+    return {
+      viewportHeight: window.innerHeight,
+      documentOverflow: document.documentElement.scrollWidth - document.documentElement.clientWidth,
+      root: rect(root),
+      layout: rect(layout),
+      mainColumn: rect(mainColumn),
+      sideColumn: rect(sideColumn),
+      messages: {
+        ...rect(messages),
+        clientHeight: messages?.clientHeight || 0,
+        scrollHeight: messages?.scrollHeight || 0,
+        scrollTop: messages?.scrollTop || 0
+      },
+      composer: rect(composer),
+      sideColumnDisplay: sideColumn ? window.getComputedStyle(sideColumn).display : "missing",
+      historyDisplay: history ? window.getComputedStyle(history).display : "missing",
+      toolsDisplay: tools ? window.getComputedStyle(tools).display : "missing"
+    };
+  });
+}
+
+async function assertResponsiveAssistant(page, viewport) {
+  await page.setViewportSize({ width: viewport.width, height: viewport.height });
+  await page.goto("/", { waitUntil: "networkidle" });
+
+  const root = page.getByTestId("assistant-client-element");
+  const messages = page.getByTestId("assistant-messages-panel");
+  const compactConversationControl = page.getByRole("button", { name: "Conversations", exact: true });
+  await root.waitFor({ state: "visible" });
+
+  const metrics = await readLayoutMetrics(page);
+  assert.ok(
+    metrics.messages.scrollHeight > metrics.messages.clientHeight,
+    `${viewport.name}: messages did not become an internal scroll container.`
+  );
+  assert.ok(metrics.composer, `${viewport.name}: composer was not rendered.`);
+  assert.ok(
+    metrics.composer.bottom <= metrics.viewportHeight + 1,
+    `${viewport.name}: composer bottom ${metrics.composer.bottom}px exceeded the ${metrics.viewportHeight}px viewport.`
+  );
+  assert.ok(
+    metrics.root.bottom <= metrics.viewportHeight + 1,
+    `${viewport.name}: assistant root escaped the viewport.`
+  );
+  assert.ok(
+    metrics.mainColumn.bottom <= metrics.root.bottom + 1,
+    `${viewport.name}: main column escaped its bounded root.`
+  );
+  assert.ok(metrics.documentOverflow <= 1, `${viewport.name}: page overflowed horizontally.`);
+
+  if (viewport.sidePanelsVisible) {
+    assert.equal(metrics.sideColumnDisplay, "flex", `${viewport.name}: sidebar column was hidden.`);
+    assert.equal(metrics.historyDisplay, "flex", `${viewport.name}: conversation history was hidden.`);
+    assert.equal(metrics.toolsDisplay, "flex", `${viewport.name}: tool timeline was hidden.`);
+    await expect(compactConversationControl).toBeHidden();
+  } else {
+    assert.equal(metrics.sideColumnDisplay, "none", `${viewport.name}: sidebar column still occupied the layout.`);
+    await expect(compactConversationControl).toBeVisible();
+  }
+
+  await messages.evaluate((element) => {
+    element.scrollTop = 0;
+    element.dispatchEvent(new Event("scroll"));
+  });
+  await messages.hover();
+  await page.mouse.wheel(0, 420);
+  await expect.poll(() => messages.evaluate((element) => element.scrollTop)).toBeGreaterThan(0);
+}
+
+test("AssistantClientElement keeps long conversations scrollable across responsive layouts", {
+  skip: RUN_BROWSER_TEST
+    ? false
+    : "set JSKIT_ASSISTANT_CORE_BROWSER_INTEGRATION=1 to run assistant-core browser integration",
+  timeout: 180_000
+}, async () => {
+  const vite = await startViteFixture({ fixtureRoot: FIXTURE_ROOT });
+  let browser = null;
+
+  try {
+    browser = await chromium.launch(createChromiumLaunchOptions());
+    const context = await browser.newContext({
+      baseURL: vite.baseURL,
+      locale: "en-US"
+    });
+    const page = await context.newPage();
+
+    for (const viewport of VIEWPORTS) {
+      await assertResponsiveAssistant(page, viewport);
+    }
+
+    await context.close();
+  } catch (error) {
+    const fixtureOutput = vite.readOutput().trim();
+    if (!fixtureOutput) {
+      throw error;
+    }
+    throw new Error(
+      `${error.message}\n\nAssistant fixture output:\n${fixtureOutput}`,
+      { cause: error }
+    );
+  } finally {
+    await browser?.close();
+    await stopProcess(vite);
+  }
+});

package/test/componentContracts.test.js

@@ -13,3 +13,14 @@ test("AssistantClientElement unwraps viewer refs before reading avatar fields",
   const source = await readPackageFile("src/client/components/AssistantClientElement.vue");
   assert.match(source, /normalizeObject\(unref\(props\.viewer\)\)/);
 });
+
+test("AssistantClientElement keeps its responsive scroll ancestors height-bounded", async () => {
+  const source = await readPackageFile("src/client/components/AssistantClientElement.vue");
+
+  assert.match(source, /<v-row class="assistant-layout h-100 flex-grow-1 flex-nowrap my-0">/u);
+  assert.match(source, /<v-col cols="12" md="8" class="assistant-main-col/u);
+  assert.match(source, /<v-col cols="12" md="4" class="assistant-side-col d-none d-md-flex/u);
+  assert.match(source, /class="d-md-none"/u);
+  assert.match(source, /\.assistant-main-col,\s*\.assistant-side-col,[\s\S]*height: 100%;[\s\S]*max-height: 100%;/u);
+  assert.match(source, /\.messages-panel \{[\s\S]*flex: 1 1 auto;[\s\S]*min-height: 0;[\s\S]*overflow: auto;/u);
+});

package/test/serviceToolCatalog.test.js

@@ -5,8 +5,8 @@ import { createSchema } from "json-rest-schema";
 import { createActionCatalogue } from "@jskit-ai/kernel/server/actions";
 import { createServiceToolCatalog } from "../src/server/lib/serviceToolCatalog.js";
 
-function schema(fields = {}) {
-  return { schema: createSchema(fields), mode: "patch" };
+function schema(fields = {}, mode = "patch") {
+  return { schema: createSchema(fields), mode };
 }
 
 function createActions(definitions = []) {
@@ -21,6 +21,8 @@ function createActions(definitions = []) {
 
 function action({
   id = "demo.books.list",
+  version = 1,
+  kind = "query",
   channels = ["automation"],
   surfaces = ["admin"],
   permission = { require: "authenticated" },
@@ -31,8 +33,8 @@ function action({
 } = {}) {
   return {
     id,
-    version: 1,
-    kind: "query",
+    version,
+    kind,
     channels,
     surfaces,
     permission,
@@ -94,19 +96,94 @@ test("assistant tools honor barred ids, prefixes, schemas, and explicit descript
   assert.equal(catalog.toOpenAiToolSchema(tool).function.name, tool.name);
 });
 
-test("assistant tools require both input and output contracts", () => {
+test("assistant tools require complete action or explicit assistant contracts", () => {
   const actions = createActions([
     action({ id: "demo.complete" }),
-    action({ id: "demo.no-output", output: null })
+    action({ id: "demo.no-output", output: null }),
+    action({
+      id: "demo.assistant-output",
+      output: null,
+      extensions: {
+        assistant: {
+          output: schema({ ok: { type: "boolean", required: true } }, "replace")
+        }
+      }
+    })
   ]);
   const tools = createServiceToolCatalog(actions)
     .resolveToolSet({ actor: { id: "7" }, surface: "admin" })
     .tools;
 
-  assert.deepEqual(tools.map((entry) => entry.actionId), ["demo.complete"]);
+  assert.deepEqual(tools.map((entry) => entry.actionId), ["demo.assistant-output", "demo.complete"]);
+});
+
+test("assistant-specific result transforms are validated against their explicit contract", async () => {
+  const actions = createActions([action({
+    id: "demo.books.transformed",
+    output: null,
+    extensions: {
+      assistant: {
+        output: schema({
+          id: { type: "string", required: true },
+          title: { type: "string", required: true }
+        }, "replace"),
+        transformResult(result) {
+          return {
+            id: result.data.id,
+            title: result.data.attributes.title
+          };
+        }
+      }
+    },
+    execute: async () => ({
+      data: {
+        id: "42",
+        attributes: { title: "Kindred" }
+      }
+    })
+  })]);
+  const catalog = createServiceToolCatalog(actions);
+  const context = { actor: { id: "7" }, surface: "admin" };
+  const toolSet = catalog.resolveToolSet(context);
+
+  assert.equal(toolSet.tools[0].outputSchema.properties.title.type, "string");
+  assert.deepEqual(await catalog.executeToolCall({
+    toolName: toolSet.tools[0].name,
+    context,
+    toolSet
+  }), {
+    ok: true,
+    result: { id: "42", title: "Kindred" }
+  });
+
+  const invalidCatalog = createServiceToolCatalog(createActions([action({
+    id: "demo.books.invalid-transform",
+    output: null,
+    extensions: {
+      assistant: {
+        output: schema({ title: { type: "string", required: true } }, "replace"),
+        transformResult() {
+          return {};
+        }
+      }
+    }
+  })]));
+  const invalidToolSet = invalidCatalog.resolveToolSet(context);
+  assert.deepEqual(await invalidCatalog.executeToolCall({
+    toolName: invalidToolSet.tools[0].name,
+    context,
+    toolSet: invalidToolSet
+  }), {
+    ok: false,
+    error: {
+      code: "assistant_tool_output_invalid",
+      message: "Tool call failed.",
+      status: 500
+    }
+  });
 });
 
-test("assistant tools hide workspaceSlug after workspace context is resolved and inject it on execution", async () => {
+test("assistant tools hide workspaceSlug and overwrite model values with trusted workspace context", async () => {
   let executed = null;
   const actions = createActions([action({
     input: schema({
@@ -129,7 +206,7 @@ test("assistant tools hide workspaceSlug after workspace context is resolved and
   assert.equal(Object.hasOwn(toolSet.tools[0].parameters.properties, "workspaceSlug"), false);
   const response = await catalog.executeToolCall({
     toolName: toolSet.tools[0].name,
-    argumentsText: JSON.stringify({ title: "Kindred" }),
+    argumentsText: JSON.stringify({ workspaceSlug: "other", title: "Kindred" }),
     context,
     toolSet
   });
@@ -139,6 +216,238 @@ test("assistant tools hide workspaceSlug after workspace context is resolved and
   assert.equal(executed.context.channel, "automation");
 });
 
+test("assistant tools expose safe field-level input guidance to the model", async () => {
+  const actions = createActions([action({
+    input: schema({
+      include: {
+        type: "string",
+        required: false,
+        messages: {
+          default: "include expects a comma-separated string such as \"pet,service\"."
+        }
+      }
+    })
+  })]);
+  const catalog = createServiceToolCatalog(actions);
+  const context = { actor: { id: "7" }, surface: "admin" };
+  const toolSet = catalog.resolveToolSet(context);
+
+  assert.deepEqual(await catalog.executeToolCall({
+    toolName: toolSet.tools[0].name,
+    argumentsText: JSON.stringify({ include: ["pet"] }),
+    context,
+    toolSet
+  }), {
+    ok: false,
+    error: {
+      code: "ACTION_VALIDATION_FAILED",
+      message: "Validation failed. include: include expects a comma-separated string such as \"pet,service\".",
+      status: 400
+    }
+  });
+});
+
+test("large authorized catalogs use compact paged discovery, exact contracts, and gated execution", async () => {
+  const executions = [];
+  const workspaceInput = schema({
+    workspaceSlug: { type: "string", required: true },
+    q: { type: "string", required: false }
+  });
+  const definitions = [
+    action({
+      id: "demo.books.list",
+      input: workspaceInput,
+      execute: async (input, context) => {
+        executions.push({ input, context });
+        return { ok: true };
+      }
+    }),
+    action({ id: "demo.books.view", input: workspaceInput }),
+    action({
+      id: "demo.books.delete",
+      permission: { require: "all", permissions: ["books.delete"] }
+    }),
+    action({ id: "demo.books.other-surface", surfaces: ["app"] }),
+    action({ id: "demo.books.internal", channels: ["internal"] })
+  ];
+  const catalog = createServiceToolCatalog(createActions(definitions), {
+    maxDirectTools: 1,
+    discoveryPageSize: 1
+  });
+  const context = {
+    actor: { id: "7" },
+    surface: "admin",
+    workspace: { slug: "library" }
+  };
+  const toolSet = catalog.resolveToolSet(context);
+
+  assert.deepEqual(toolSet.tools.map((entry) => entry.name), [
+    "assistant_action_search",
+    "assistant_action_contract",
+    "assistant_action_execute"
+  ]);
+
+  const firstPage = await catalog.executeToolCall({
+    toolName: "assistant_action_search",
+    argumentsText: JSON.stringify({ query: "books", limit: 1 }),
+    context,
+    toolSet
+  });
+  assert.equal(firstPage.ok, true);
+  assert.equal(firstPage.result.total, 2);
+  assert.equal(firstPage.result.items.length, 1);
+  assert.equal(Object.hasOwn(firstPage.result.items[0], "inputSchema"), false);
+  assert.equal(typeof firstPage.result.nextCursor, "string");
+
+  const secondPage = await catalog.executeToolCall({
+    toolName: "assistant_action_search",
+    argumentsText: JSON.stringify({
+      query: "books",
+      cursor: firstPage.result.nextCursor,
+      limit: 1
+    }),
+    context,
+    toolSet
+  });
+  assert.equal(secondPage.result.items.length, 1);
+  assert.equal(secondPage.result.nextCursor, null);
+
+  assert.deepEqual(await catalog.executeToolCall({
+    toolName: "assistant_action_contract",
+    argumentsText: JSON.stringify({ actionId: "demo.books.delete" }),
+    context,
+    toolSet
+  }), {
+    ok: false,
+    error: {
+      code: "assistant_action_unknown",
+      message: "Action is not available.",
+      status: 404
+    }
+  });
+
+  assert.deepEqual(await catalog.executeToolCall({
+    toolName: "assistant_action_execute",
+    argumentsText: JSON.stringify({
+      actionId: "demo.books.list",
+      version: 1,
+      input: { workspaceSlug: "other", q: "octavia" }
+    }),
+    context,
+    toolSet
+  }), {
+    ok: false,
+    error: {
+      code: "assistant_action_contract_required",
+      message: "Load this action's exact contract before executing it.",
+      status: 409
+    }
+  });
+
+  const contract = await catalog.executeToolCall({
+    toolName: "assistant_action_contract",
+    argumentsText: JSON.stringify({ actionId: "demo.books.list", version: 1 }),
+    context,
+    toolSet
+  });
+  assert.equal(contract.ok, true);
+  assert.equal(contract.result.actionId, "demo.books.list");
+  assert.equal(Object.hasOwn(contract.result.inputSchema.properties, "workspaceSlug"), false);
+  assert.equal(contract.result.outputSchema.properties.ok["x-json-rest-schema"].castType, "boolean");
+
+  assert.deepEqual(await catalog.executeToolCall({
+    toolName: "assistant_action_execute",
+    argumentsText: JSON.stringify({
+      actionId: "demo.books.list",
+      version: 1,
+      input: { workspaceSlug: "other", q: "octavia" }
+    }),
+    context,
+    toolSet
+  }), {
+    ok: true,
+    result: {
+      actionId: "demo.books.list",
+      version: 1,
+      result: { ok: true }
+    }
+  });
+  assert.deepEqual(executions[0].input, {
+    workspaceSlug: "library",
+    q: "octavia"
+  });
+  assert.equal(executions[0].context.channel, "automation");
+});
+
+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")}`
+  }));
+  const discoveryCatalog = createServiceToolCatalog(createActions(definitions), {
+    maxDirectTools: 1
+  });
+  const context = { actor: { id: "7" }, surface: "admin" };
+  const discoveryToolSet = discoveryCatalog.resolveToolSet(context);
+  const page = await discoveryCatalog.executeToolCall({
+    toolName: "assistant_action_search",
+    argumentsText: JSON.stringify({ limit: 100 }),
+    context,
+    toolSet: discoveryToolSet
+  });
+  assert.equal(page.ok, true);
+  assert.equal(page.result.items.length, 20);
+  assert.equal(typeof page.result.nextCursor, "string");
+
+  const largeContractFields = Object.fromEntries(
+    Array.from({ length: 30 }, (_, index) => [
+      `field${index}`,
+      { type: "string", required: false, description: "x".repeat(40) }
+    ])
+  );
+  const contractCatalog = createServiceToolCatalog(createActions([action({
+    id: "demo.large.contract",
+    input: schema(largeContractFields)
+  })]), {
+    maxDirectTools: 0,
+    maxToolResultBytes: 500
+  });
+  const contractToolSet = contractCatalog.resolveToolSet(context);
+  assert.deepEqual(await contractCatalog.executeToolCall({
+    toolName: "assistant_action_contract",
+    argumentsText: JSON.stringify({ actionId: "demo.large.contract" }),
+    context,
+    toolSet: contractToolSet
+  }), {
+    ok: false,
+    error: {
+      code: "assistant_tool_contract_too_large",
+      message: "Action contract exceeds the assistant size limit. Narrow the request and try again.",
+      status: 413
+    }
+  });
+
+  const resultCatalog = createServiceToolCatalog(createActions([action({
+    id: "demo.large.read",
+    output: schema({ value: { type: "string", required: true } }, "replace"),
+    execute: async () => ({ value: "x".repeat(1000) })
+  })]), {
+    maxToolResultBytes: 200
+  });
+  const resultToolSet = resultCatalog.resolveToolSet(context);
+  assert.deepEqual(await resultCatalog.executeToolCall({
+    toolName: resultToolSet.tools[0].name,
+    context,
+    toolSet: resultToolSet
+  }), {
+    ok: false,
+    error: {
+      code: "assistant_tool_result_too_large",
+      message: "Tool result exceeds the assistant size limit. Narrow the request and try again.",
+      status: 413
+    }
+  });
+});
+
 test("assistant tools reject unknown tools and return safe action failures", async () => {
   const actions = createActions([action({
     execute: async () => {