@jskit-ai/assistant-runtime 0.2.46 → 0.2.47

package/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- `assistantServer.<surface>.maxToolArgumentBytes` (a whole number of bytes, at most 1 MiB) raises a surface's limit on an application tool call's arguments from the default 32 KiB, for an assistant that writes a large document in one call. The surface's own limit is the one its conversations' calls are held to and the one every engine is given (the OpenCode tool connection included); before, the runtime enforced and handed engines the default surface's 32 KiB whatever a surface's catalogue allowed. `assistantServer.<surface>.maxToolResultBytes` (also at most 1 MiB) raises its limit on a tool call's result from the default 48 KiB in the same way, for an assistant that reads a large document back: a larger result reaches the model as `assistant_tool_result_too_large` instead. A malformed value of either stops the server from starting. **Breaking.** The surface-aware tool catalogue no longer has a `limits` property, which always answered the default surface's: each tool set it resolves carries its surface's `limits`. New migration `assistant_transcripts_tool_arguments`: on MySQL and MariaDB, `assistant_messages.content_text` becomes LONGTEXT, so a saved call's arguments and result may pass TEXT's 64 KiB; PostgreSQL and SQLite are unchanged.
 - A Set or Resume goal that the server refuses after its message already appeared in the conversation shows the server's reason (for example that Claude's goal attachment is not available yet) instead of only `jskit.assistant.runtime.goal.changeFailed` ("Could not change the goal."): the transcript turn settled the optimistic message first, so the failure's own text was dropped with it.
 - The saved-conversations list (`GET /api/assistant/:surfaceId/conversations`, and its workspace form) answers 200 again instead of 500 ("metadata is required!") once a person has a conversation: the route still serialized each item with the conversation's read schema, which requires `metadata`, after list items stopped carrying it. It serializes them with assistant-core's `assistantConversationListItemOutputValidator`, the item of `assistantContract`'s `conversationsList`. `conversationsListRoute.test.js` lists a saved conversation over HTTP through the real route, actions and SQL repositories.
 - Each conversation request authenticates once: the route's access check and the action's request context share one sign-in lookup instead of each asking again.

package/fixtures/conversation/vite.config.mjs

@@ -88,7 +88,7 @@ export default defineConfig({
                 async createConversationForTurn() { return { conversation: { id: "100" } }; },
                 async completeConversation() {}
               },
-              serviceToolCatalog: { limits: { maxToolArgumentBytes: 64 * 1024 }, resolveToolSet: () => ({ tools: [] }),
+              serviceToolCatalog: { resolveToolSet: () => ({ tools: [], limits: { maxToolArgumentBytes: 64 * 1024 } }),
                 toOpenAiToolSchema: tool => ({ type: "function", function: tool }) },
               assistantConfigService: { resolveSystemPrompt: async () => "Answer the user." },
               personContextPrompt: createPersonContextPrompt({ personContext: NO_PERSON_CONTEXT, logger: silentLogger }),

package/migrations/assistant_transcripts_tool_arguments.cjs

@@ -0,0 +1,14 @@
+// An application tool call's arguments are saved in its tool_call row's content_text and its result in
+// its tool_result row's, and a surface may allow up to 1 MiB of each
+// (assistantServer.<surface>.maxToolArgumentBytes and maxToolResultBytes). MySQL's TEXT holds 64 KiB,
+// so on MySQL and MariaDB content_text becomes LONGTEXT; PostgreSQL's and SQLite's text has no such
+// limit and stays as it is.
+exports.up = async function up(knex) {
+  if (!/mysql|maria/iu.test(String(knex.client.config.client))) return;
+  await knex.schema.alterTable("assistant_messages", table => {
+    table.text("content_text", "longtext").nullable().alter();
+  });
+};
+
+// Narrowing content_text back to TEXT would cut longer saved calls and results, so it stays LONGTEXT.
+exports.down = async function down() {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-runtime",
-  "version": "0.2.46",
+  "version": "0.2.47",
   "type": "module",
   "scripts": {
     "test": "jskit test"
@@ -15,7 +15,7 @@
     "./locales/en.json": "./locales/en.json"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.2.44",
+    "@jskit-ai/assistant-core": "0.2.45",
     "@jskit-ai/resource-core": "0.1.211",
     "json-rest-schema": "^1.0.20"
   },

package/src/server/services/assistantConfigService.js

@@ -29,7 +29,7 @@ function createService({
   appConfig,
   workspaceScopeSupport
 }) {
-  // Read once here, so a malformed settingsUpdatePermission stops the server from starting.
+  // Read once here, so a malformed settingsUpdatePermission, maxToolArgumentBytes or maxToolResultBytes stops the server from starting.
   resolveAssistantServerConfigMap(appConfig);
 
   /**

package/src/server/support/assistantServerConfig.js

@@ -7,6 +7,8 @@ import {
 } from "@jskit-ai/assistant-core/server";
 
 const SETTINGS_UPDATE_REQUIRE_MODES = Object.freeze(["authenticated", "all", "any"]);
+// The most a surface may raise its application tool argument and result limits to: 1 MiB.
+const MAX_TOOL_BYTES_CEILING = 1024 * 1024;
 
 /**
  * Who may change a surface's assistant settings, as configured: a permission, an auth policy
@@ -36,6 +38,27 @@ function normalizeSettingsUpdatePermission(value, targetSurfaceId) {
   );
 }
 
+/**
+ * A surface's limit in bytes on its application tool calls' arguments (`maxToolArgumentBytes`) or
+ * results (`maxToolResultBytes`), as configured, or null for the tool catalogue's default (32 KiB of
+ * arguments, 48 KiB of result).
+ * @param {Record<string, unknown>} entry
+ * @param {"maxToolArgumentBytes" | "maxToolResultBytes"} key
+ * @param {string} targetSurfaceId
+ */
+function normalizeMaxToolBytes(entry, key, targetSurfaceId) {
+  const value = entry[key];
+  if (value === undefined) {
+    return null;
+  }
+  if (Number.isSafeInteger(value) && value >= 1 && value <= MAX_TOOL_BYTES_CEILING) {
+    return value;
+  }
+  throw new TypeError(
+    `assistantServer.${targetSurfaceId}.${key} must be a whole number of bytes from 1 to ${MAX_TOOL_BYTES_CEILING} (1 MiB).`
+  );
+}
+
 function resolveAssistantServerConfigMap(appConfig) {
   const source = normalizeObject(appConfig?.assistantServer);
   const resolved = {};
@@ -58,6 +81,8 @@ function resolveAssistantServerConfigMap(appConfig) {
       timeoutMs: entry.timeoutMs,
       barredActionIds: Object.freeze(normalizeUniqueTextList(entry.barredActionIds, { acceptSingle: true })),
       toolSkipActionPrefixes: Object.freeze(normalizeUniqueTextList(entry.toolSkipActionPrefixes, { acceptSingle: true })),
+      maxToolArgumentBytes: normalizeMaxToolBytes(entry, "maxToolArgumentBytes", targetSurfaceId),
+      maxToolResultBytes: normalizeMaxToolBytes(entry, "maxToolResultBytes", targetSurfaceId),
       settingsUpdatePermission: normalizeSettingsUpdatePermission(entry.settingsUpdatePermission, targetSurfaceId)
     });
   }

package/src/server/support/createSurfaceAwareToolCatalog.js

@@ -8,7 +8,9 @@ function buildCatalogOptions(appConfig = {}, surfaceId = "") {
 
   return Object.freeze({
     barredActionIds: surfaceConfig.barredActionIds || [],
-    skipActionPrefixes: Object.freeze(["assistant.", ...(surfaceConfig.toolSkipActionPrefixes || [])])
+    skipActionPrefixes: Object.freeze(["assistant.", ...(surfaceConfig.toolSkipActionPrefixes || [])]),
+    ...(surfaceConfig.maxToolArgumentBytes ? { maxToolArgumentBytes: surfaceConfig.maxToolArgumentBytes } : {}),
+    ...(surfaceConfig.maxToolResultBytes ? { maxToolResultBytes: surfaceConfig.maxToolResultBytes } : {})
   });
 }
 
@@ -24,9 +26,10 @@ function requireContextSurfaceId(context) {
 /**
  * The assistant's tool catalogue over an application's actions, resolved per surface. Each surface
  * offers the actions its `assistantServer` configuration leaves in (its barred action ids and
- * skipped prefixes taken out), and every call names its surface in `context.surface`. The assistant
- * runtime builds its catalogue this way; an application test builds one the same way to see the
- * tools a surface offers and to call them.
+ * skipped prefixes taken out), and its tool sets carry its limits, `maxToolArgumentBytes` and
+ * `maxToolResultBytes` included, which its calls are held to. Every call names its surface in
+ * `context.surface`. The assistant runtime builds its catalogue this way; an application test builds
+ * one the same way to see the tools a surface offers and to call them.
  * @param {import("@jskit-ai/kernel/server/types").ActionCatalogue} actions The application's actions (`runtime.actions`).
  * @param {object} [options]
  * @param {Record<string, any>} [options.appConfig] The server configuration that holds `assistantServer`.
@@ -72,10 +75,6 @@ function createSurfaceAwareToolCatalog(actions, { appConfig = {}, createCatalog
   }
 
   return Object.freeze({
-    get limits() {
-      if (!schemaCatalog) schemaCatalog = createCatalog(actions, buildCatalogOptions(normalizedAppConfig, ""));
-      return schemaCatalog.limits;
-    },
     resolveToolSet,
     toOpenAiToolSchema,
     executeToolCall

package/test/assistantServerConfig.test.js

@@ -42,6 +42,8 @@ test("assistant server config resolves per-surface AI config without app-level g
     timeoutMs: 45_000,
     barredActionIds: ["demo.admin.secret"],
     toolSkipActionPrefixes: ["demo.hidden."],
+    maxToolArgumentBytes: null,
+    maxToolResultBytes: null,
     settingsUpdatePermission: null
   });
   assert.deepEqual(resolveAssistantAiConfig({ appConfig, env }, "admin"), {
@@ -73,3 +75,18 @@ test("assistant server config requires explicit aiConfigPrefix for each surface"
     /requires assistantServer\.admin\.aiConfigPrefix/
   );
 });
+
+for (const [key, fallback] of [["maxToolArgumentBytes", "32 KiB"], ["maxToolResultBytes", "48 KiB"]]) {
+  test(`assistantServer.<surface>.${key} raises a surface's tool ${key === "maxToolArgumentBytes" ? "argument" : "result"} limit up to 1 MiB`, () => {
+    const resolve = value => resolveAssistantServerConfig({ assistantServer: { writer: { [key]: value } } }, "writer");
+    assert.equal(resolve(undefined)[key], null, `Absent, the surface keeps the catalogue's ${fallback}`);
+    assert.equal(resolve(128 * 1024)[key], 128 * 1024);
+    assert.equal(resolve(1024 * 1024)[key], 1024 * 1024);
+    for (const invalid of [0, -1, 1.5, "65536", 1024 * 1024 + 1, Number.POSITIVE_INFINITY, null, true]) {
+      assert.throws(() => resolve(invalid), {
+        name: "TypeError",
+        message: new RegExp(`^assistantServer\\.writer\\.${key} must be`, "u")
+      }, String(invalid));
+    }
+  });
+}

package/test/chatServiceLifecycle.test.js

@@ -148,9 +148,8 @@ function createHarness(completions, { executeToolCall = null, tools: configuredT
       }
     },
     serviceToolCatalog: {
-      limits: { maxToolArgumentBytes: 64 * 1024 },
       resolveToolSet() {
-        return { tools };
+        return { tools, limits: { maxToolArgumentBytes: 64 * 1024 } };
       },
       toOpenAiToolSchema(tool) {
         return {

package/test/createSurfaceAwareToolCatalog.test.js

@@ -1,5 +1,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { createSchema } from "json-rest-schema";
+import { createActionCatalogue } from "@jskit-ai/kernel/server/actions";
 import { createSurfaceAwareToolCatalog } from "../src/server/support/createSurfaceAwareToolCatalog.js";
 
 test("surface-aware tool catalog applies per-surface skip and barred configuration", async () => {
@@ -12,7 +14,9 @@ test("surface-aware tool catalog applies per-surface skip and barred configurati
         assistantServer: {
           admin: {
             barredActionIds: ["demo.admin.secret"],
-            toolSkipActionPrefixes: ["demo.admin."]
+            toolSkipActionPrefixes: ["demo.admin."],
+            maxToolArgumentBytes: 65536,
+            maxToolResultBytes: 131072
           },
           console: {
             barredActionIds: ["demo.console.secret"]
@@ -65,7 +69,9 @@ test("surface-aware tool catalog applies per-surface skip and barred configurati
   assert.deepEqual(observed, [
     {
       barredActionIds: ["demo.admin.secret"],
-      skipActionPrefixes: ["assistant.", "demo.admin."]
+      skipActionPrefixes: ["assistant.", "demo.admin."],
+      maxToolArgumentBytes: 65536,
+      maxToolResultBytes: 131072
     },
     {
       barredActionIds: ["demo.console.secret"],
@@ -74,10 +80,66 @@ test("surface-aware tool catalog applies per-surface skip and barred configurati
   ]);
   assert.deepEqual(execution.options, {
     barredActionIds: ["demo.admin.secret"],
-    skipActionPrefixes: ["assistant.", "demo.admin."]
+    skipActionPrefixes: ["assistant.", "demo.admin."],
+    maxToolArgumentBytes: 65536,
+    maxToolResultBytes: 131072
   });
 });
 
+test("each surface's tool sets carry and enforce its maxToolArgumentBytes", async () => {
+  const lengths = [];
+  const actions = createActionCatalogue();
+  actions.register({ contributorId: "test.documents", domain: "test", actions: [{
+    id: "documents.propose", version: 1, kind: "command", channels: ["automation"], surfaces: ["writer", "home"],
+    permission: { require: "authenticated" },
+    input: { schema: createSchema({ text: { type: "string", required: true } }), mode: "replace" },
+    output: { schema: createSchema({ length: { type: "number", required: true } }), mode: "replace" },
+    execute: async ({ text }) => { lengths.push(text.length); return { length: text.length }; }
+  }] });
+  const catalog = createSurfaceAwareToolCatalog(actions, { appConfig: { assistantServer: { writer: { maxToolArgumentBytes: 64 * 1024 } } } });
+  const argumentsText = JSON.stringify({ text: "x".repeat(40 * 1024) });
+  const call = surface => {
+    const context = { actor: { id: "owner" }, surface };
+    const toolSet = catalog.resolveToolSet(context);
+    return { limit: toolSet.limits.maxToolArgumentBytes,
+      result: catalog.executeToolCall({ toolName: toolSet.tools[0].name, argumentsText, context, toolSet }) };
+  };
+
+  const writer = call("writer");
+  assert.equal(writer.limit, 64 * 1024);
+  assert.deepEqual(await writer.result, { ok: true, result: { length: 40 * 1024 } });
+  const home = call("home");
+  assert.equal(home.limit, 32 * 1024, "A surface without the key keeps the default");
+  assert.equal((await home.result).error.code, "assistant_tool_arguments_too_large");
+  assert.deepEqual(lengths, [40 * 1024]);
+});
+
+test("each surface's tool sets carry and enforce its maxToolResultBytes", async () => {
+  const actions = createActionCatalogue();
+  actions.register({ contributorId: "test.documents", domain: "test", actions: [{
+    id: "documents.read", version: 1, kind: "query", channels: ["automation"], surfaces: ["reader", "home"],
+    permission: { require: "authenticated" },
+    input: { schema: createSchema({}), mode: "replace" },
+    output: { schema: createSchema({ text: { type: "string", required: true } }), mode: "replace" },
+    execute: async () => ({ text: "x".repeat(67 * 1024) })
+  }] });
+  const catalog = createSurfaceAwareToolCatalog(actions, { appConfig: { assistantServer: { reader: { maxToolResultBytes: 96 * 1024 } } } });
+  const call = surface => {
+    const context = { actor: { id: "owner" }, surface };
+    const toolSet = catalog.resolveToolSet(context);
+    return { limit: toolSet.limits.maxToolResultBytes,
+      result: catalog.executeToolCall({ toolName: toolSet.tools[0].name, argumentsText: "{}", context, toolSet }) };
+  };
+
+  const reader = call("reader");
+  assert.equal(reader.limit, 96 * 1024);
+  assert.equal((await reader.result).result.text.length, 67 * 1024);
+  const home = call("home");
+  assert.equal(home.limit, 48 * 1024, "A surface without the key keeps the default");
+  assert.deepEqual((await home.result).error, { code: "assistant_tool_result_too_large",
+    message: "Tool result exceeds the assistant size limit. Narrow the request and try again.", status: 413 });
+});
+
 test("an application reaches the surface-aware tool catalog through the package's server entry", async () => {
   const server = await import("@jskit-ai/assistant-runtime/server");
   assert.equal(server.createSurfaceAwareToolCatalog, createSurfaceAwareToolCatalog);

package/test/packageMetadata.test.js

@@ -24,6 +24,7 @@ test("assistant-runtime registers providers without install-time authoring machi
     "assistant_config_initial.cjs",
     "assistant_transcripts_initial.cjs",
     "assistant_transcripts_summary.cjs",
+    "assistant_transcripts_tool_arguments.cjs",
     "assistant_turn_requests.cjs",
     "constraints"
   ]);

package/test/sqlConversationStorage.mysql.test.js

@@ -4,6 +4,7 @@ import knex from "knex";
 import { verifyConversationStorageContract } from "@jskit-ai/assistant-core/testing/conversation-storage";
 import transcriptsMigration from "../migrations/assistant_transcripts_initial.cjs";
 import summaryMigration from "../migrations/assistant_transcripts_summary.cjs";
+import toolArgumentsMigration from "../migrations/assistant_transcripts_tool_arguments.cjs";
 import { createSqlConversationStorage } from "../src/server/sqlConversationStorage.js";
 import { createTestAssistantStore } from "./support/assistantStore.js";
 
@@ -77,6 +78,28 @@ test("the SQL conversation storage keeps its contract, cache and summary on MySQ
     }));
     assert.deepEqual(summarised, { summary: { text, throughTurnId: "000100" }, after: ["000101", "000102"] });
 
+    // A tool call's arguments are its tool_call row's text and its result its tool_result row's: an
+    // application may allow up to 1 MiB of each, past the 64 KiB a MySQL TEXT column holds.
+    const contentTextType = async () => (await f.db.raw("SELECT DATA_TYPE AS type FROM information_schema.COLUMNS " +
+      "WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'assistant_messages' AND COLUMN_NAME = 'content_text'"))[0][0].type.toLowerCase();
+    assert.equal(await contentTextType(), "text");
+    await toolArgumentsMigration.up(f.db);
+    await toolArgumentsMigration.up(f.db);
+    assert.equal(await contentTextType(), "longtext");
+    const proposal = await conversation("1");
+    const argumentsText = JSON.stringify({ text: "x".repeat(1024 * 1024 - 11) });
+    const call = { id: "propose", name: "documents_propose", arguments: argumentsText, status: "complete",
+      at: "2026-03-01T00:00:00.000Z", result: { ok: true, result: { text: "y".repeat(1024 * 1024 - 32) } } };
+    const proposed = await f.storage.write(proposal.id, async transaction => {
+      const turnId = await transaction.nextTurnId();
+      await transaction.appendMessage(turnId, { role: "user", messageId: "propose", text: "Propose a document.", at: call.at });
+      await transaction.updateTurnMetadata(turnId, { applicationTools: [call] });
+      return turnId;
+    });
+    const reread = await (await connect()).storage.read(proposal.id, transaction => transaction.readTurn(proposed));
+    assert.equal(reread.metadata.applicationTools[0].arguments, argumentsText, "A 1 MiB call's arguments are saved whole");
+    assert.deepEqual(reread.metadata.applicationTools[0].result, call.result, "And its 1 MiB result");
+
     await summaryMigration.down(f.db);
     for (const column of ["summary_text", "summary_through_turn_id", "transcript_revision"]) {
       assert.equal(await f.db.schema.hasColumn("assistant_conversations", column), false);

package/test/sqlConversationStorage.test.js

@@ -10,6 +10,7 @@ import { createConversationTranscript } from "@jskit-ai/assistant-core/server/co
 import { verifyConversationStorageContract } from "@jskit-ai/assistant-core/testing/conversation-storage";
 import transcriptsMigration from "../migrations/assistant_transcripts_initial.cjs";
 import summaryMigration from "../migrations/assistant_transcripts_summary.cjs";
+import toolArgumentsMigration from "../migrations/assistant_transcripts_tool_arguments.cjs";
 import claimsMigration from "../migrations/assistant_turn_requests.cjs";
 import { createSqlConversationStorage } from "../src/server/sqlConversationStorage.js";
 import { createAssistantConversationRuntime } from "../src/server/createAssistantRuntime.js";
@@ -48,6 +49,8 @@ async function fixture(t) {
   await first.db("users").insert([{ id: 1 }, { id: 2 }]);
   await transcriptsMigration.up(first.db);
   await summaryMigration.up(first.db);
+  // MySQL only: SQLite's text holds a tool call's arguments as they are.
+  await toolArgumentsMigration.up(first.db);
   await claimsMigration.up(first.db);
   await first.db.raw("PRAGMA journal_mode = WAL");
   const conversation = actor => first.conversationsRepository.create({ createdByUserId: actor || "1", surfaceId: "assistant", metadata: {} });
@@ -171,8 +174,8 @@ test("the SQL facade uses common inference and durable tool rows, and the model'
       })();
     }, { model: "fixture-model" }) };
   } };
-  const catalog = { limits: { maxToolArgumentBytes: 4096 },
-    resolveToolSet: () => ({ tools: [{ name: "inventory_lookup", parameters: { type: "object" } }] }),
+  const catalog = {
+    resolveToolSet: () => ({ tools: [{ name: "inventory_lookup", parameters: { type: "object" } }], limits: { maxToolArgumentBytes: 4096 } }),
     toOpenAiToolSchema: tool => ({ type: "function", function: tool }),
     async executeToolCall() {
       executions += 1;
@@ -347,7 +350,7 @@ for (const shape of ["orphan-output", "orphan-tool-result", "unconfirmed-tool"])
           yield { choices: [{ delta: { content: "Fresh answer." }, finish_reason: "stop" }] };
         })();
       }, { model: "fixture-model" }) }) };
-    const catalog = { limits: { maxToolArgumentBytes: 4096 }, resolveToolSet: () => ({ tools: [] }),
+    const catalog = { resolveToolSet: () => ({ tools: [], limits: { maxToolArgumentBytes: 4096 } }),
       toOpenAiToolSchema: tool => ({ type: "function", function: tool }),
       executeToolCall() { effects++; assert.fail("Retained history cannot repeat an application effect"); } };
     const runtime = createAssistantConversationRuntime({ ...f, aiClientFactory, toolCatalog: catalog });

package/test/surfaceToolLimits.test.js

@@ -0,0 +1,102 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createSchema } from "json-rest-schema";
+import { createActionCatalogue } from "@jskit-ai/kernel/server/actions";
+import { createConversationRuntime, createMemoryConversationStorage } from "@jskit-ai/assistant-core/server/conversation";
+import { createSurfaceAwareToolCatalog } from "../src/server/support/createSurfaceAwareToolCatalog.js";
+
+// An assistant on an API model that proposes a whole document in one application tool call, and reads one back.
+const KIB = 1024;
+const SURFACES = ["writer", "planner", "reader", "home"];
+const appConfig = { assistantServer: { writer: { maxToolArgumentBytes: 64 * KIB }, planner: { maxToolArgumentBytes: 256 * KIB },
+  reader: { maxToolResultBytes: 96 * KIB }, home: {} } };
+const frame = (delta, finish_reason = null) => `data: ${JSON.stringify({ choices: [{ index: 0, delta, finish_reason }] })}\n\n`;
+const stream = body => new Response(body, { headers: { "content-type": "text/event-stream" } });
+/** A document whose JSON is `bytes` bytes: {"text":"…"} is 11 bytes around the text. */
+function documentOf(bytes) {
+  const document = { text: "x".repeat(bytes - 11) };
+  assert.equal(Buffer.byteLength(JSON.stringify(document)), bytes);
+  return document;
+}
+
+/**
+ * On `surface`, the model calls `actionId` once with `input`, then answers. documents.read answers
+ * a document of `resultBytes` bytes. Returns the turn, what the actions received and the model's requests.
+ */
+async function converse(t, surface, actionId, input, { resultBytes = 0 } = {}) {
+  const received = [];
+  const text = createSchema({ text: { type: "string", required: true } });
+  const action = { version: 1, channels: ["automation"], surfaces: SURFACES, permission: { require: "authenticated" } };
+  const actions = createActionCatalogue();
+  actions.register({ contributorId: "test.documents", domain: "test", actions: [{
+    ...action, id: "documents.propose", kind: "command", input: { schema: text, mode: "replace" },
+    output: { schema: createSchema({ length: { type: "number", required: true } }), mode: "replace" },
+    execute: async ({ text: proposed }) => { received.push(proposed.length); return { length: proposed.length }; }
+  }, {
+    ...action, id: "documents.read", kind: "query", input: { schema: createSchema({}), mode: "replace" }, output: { schema: text, mode: "replace" },
+    execute: async () => { received.push("read"); return documentOf(resultBytes); }
+  }] });
+  const toolCatalog = createSurfaceAwareToolCatalog(actions, { appConfig });
+  const context = { actor: { id: "owner" }, surface, applicationId: "test", subjectId: "owner" };
+  const name = toolCatalog.resolveToolSet(context).tools.find(tool => tool.actionId === actionId).name;
+  const requests = [];
+  const runtime = createConversationRuntime({ storage: createMemoryConversationStorage(), toolCatalog, authorize: () => true,
+    connections: { resolve: async () => ({ providerId: "test", model: "test-model", sdkPackage: "@ai-sdk/openai-compatible",
+      apiKey: "test", baseURL: "http://test.invalid/v1" }) },
+    async fetch(_url, request) {
+      const body = JSON.parse(request.body);
+      // A check of the reply's claims, when the engine makes one, finds none unsupported.
+      if (!body.stream) return Response.json({ id: "check", object: "chat.completion", created: 0, model: "test-model",
+        choices: [{ index: 0, message: { role: "assistant", content: '{"unsupported": []}' }, finish_reason: "stop" }] });
+      requests.push(body);
+      return stream(requests.length === 1
+        ? frame({ tool_calls: [{ index: 0, id: "call", type: "function", function: { name, arguments: JSON.stringify(input) } }] }) + frame({}, "tool_calls")
+        : frame({ content: "Here it is." }) + frame({}, "stop"));
+    } });
+  t.after(() => runtime.close());
+  const conversation = await runtime.open({ id: "document", context, configuration: { systemPrompt: "Work on documents.", integrationId: "assistant" } });
+  await conversation.send({ messageId: "ask", text: "Work on the document." });
+  const result = await conversation.wait();
+  const toolMessage = requests[1]?.messages.find(message => message.role === "tool");
+  return { result, received, modelSaw: toolMessage && JSON.parse(toolMessage.content) };
+}
+
+test("an API conversation's tool call is held to its surface's maxToolArgumentBytes", async t => {
+  const writer = await converse(t, "writer", "documents.propose", documentOf(40 * KIB));
+  assert.equal(writer.result.error, "");
+  assert.equal(writer.result.conversationLog[0].metadata.runtime.status, "complete");
+  assert.deepEqual(writer.received, [40 * KIB - 11]);
+  assert.equal(writer.result.conversationLog[0].metadata.applicationTools[0].arguments.length, 40 * KIB);
+
+  const home = await converse(t, "home", "documents.propose", documentOf(40 * KIB));
+  assert.equal(home.result.error, "The application tool arguments exceed their size limit.");
+  assert.deepEqual(home.received, [], "Over the default 32 KiB the action never runs");
+});
+
+test("a 128 KiB tool call passes end to end on a surface that allows it, and one over its limit fails the same way", async t => {
+  const fits = await converse(t, "planner", "documents.propose", documentOf(128 * KIB));
+  assert.equal(fits.result.error, "");
+  assert.deepEqual(fits.received, [128 * KIB - 11]);
+
+  const over = await converse(t, "planner", "documents.propose", documentOf(256 * KIB + 1));
+  assert.equal(over.result.error, "The application tool arguments exceed their size limit.");
+  assert.deepEqual(over.received, []);
+});
+
+test("a 67 KiB document read back reaches the model on a surface whose maxToolResultBytes allows it, and only the error does elsewhere", async t => {
+  const reader = await converse(t, "reader", "documents.read", {}, { resultBytes: 67 * KIB });
+  assert.equal(reader.result.error, "");
+  assert.equal(reader.result.conversationLog[0].metadata.applicationTools[0].result.ok, true);
+  assert.equal(reader.modelSaw.text.length, 67 * KIB - 11, "The model reads the whole document");
+
+  const home = await converse(t, "home", "documents.read", {}, { resultBytes: 67 * KIB });
+  assert.equal(home.result.error, "", "The turn carries on with the error in the document's place");
+  assert.deepEqual(home.received, ["read"]);
+  assert.equal(home.result.conversationLog[0].metadata.applicationTools[0].result.error.code, "assistant_tool_result_too_large");
+  assert.equal(home.modelSaw.error.code, "assistant_tool_result_too_large", "Over the default 48 KiB the model gets the error, not the document");
+
+  const atLimit = await converse(t, "reader", "documents.read", {}, { resultBytes: 96 * KIB });
+  assert.equal(atLimit.modelSaw.text.length, 96 * KIB - 11);
+  const over = await converse(t, "reader", "documents.read", {}, { resultBytes: 96 * KIB + 1 });
+  assert.equal(over.modelSaw.error.code, "assistant_tool_result_too_large");
+});

package/test/turnRequests.test.js

@@ -81,7 +81,7 @@ function service(repository, { provider, transcript = [] } = {}) {
       async createConversationForTurn() { return { conversation: { id: "100" } }; },
       async completeConversation() {}
     },
-    serviceToolCatalog: { limits: { maxToolArgumentBytes: 64 * 1024 }, resolveToolSet: () => ({ tools: [] }),
+    serviceToolCatalog: { resolveToolSet: () => ({ tools: [], limits: { maxToolArgumentBytes: 64 * 1024 } }),
       toOpenAiToolSchema: tool => ({ type: "function", function: tool }) },
     assistantConfigService: { resolveSystemPrompt: async () => "Answer." },
     personContextPrompt: createPersonContextPrompt({ personContext: NO_PERSON_CONTEXT, logger: silentLogger }),