@bevel-software/platform-core-backend 0.23.0 → 0.24.0

package/src/modules/code-mode/code-mode.tool.ts

@@ -2,20 +2,53 @@ import '@utcp/direct-call';
 import { createTool } from '@mastra/core/tools';
 import { z } from 'zod';
 import { CodeModeUtcpClient } from '@utcp/code-mode';
-import { omitImagePayloads, retiredToolInFailure, retiredToolChainFailure } from '@bevel-software/platform-mcp-core';
+import {
+  omitImagePayloads,
+  retiredToolInFailure,
+  CHAIN_TIMEOUT_DEFAULT_MS,
+  CHAIN_TIMEOUT_MAX_MS,
+  CHAIN_TIMEOUT_MIN_MS,
+  chainExample,
+  type ChainExampleTool,
+  runToolChain,
+} from '@bevel-software/platform-mcp-core';
 import type { SpillStore } from '../workspace/spill-store.js';
 import { utcpNameToTsInterfaceName, findToolByName, AmbiguousToolNameError } from './code-mode-names.js';
 
+/**
+ * The in-process agent's three code-mode tools.
+ *
+ * `namespace` is the UTCP manual the knowledge-base tools are registered under
+ * for THIS client, and every example in the descriptions is written against it.
+ * It is a parameter rather than fixed text because it is not the same name on
+ * every surface — the hosted endpoint registers `KNOWLEDGE_BASE`, the local MCP
+ * server registers the whole deployment as `hexis` — and a description naming
+ * the other one taught the agent a namespace the runtime had no binding for.
+ *
+ * `tools` is this client's catalog — names AND input schemas — and is used only
+ * to write an EXAMPLE call that actually runs. Both halves are needed: the
+ * namespace does not say how deeply a tool's name is nested, and the name does
+ * not say which of its arguments are required (see `chainExample`). Passing
+ * nothing prints no concrete example, which is the honest default for a caller
+ * that has not handed over its catalog.
+ */
 export function createCallToolChainTool(
   client: CodeModeUtcpClient,
   spillStore: SpillStore,
+  namespace: string,
+  tools: readonly ChainExampleTool[] = [],
 ) {
+  const { namespace: ns, call } = chainExample(namespace, tools);
+  // Printed only when the catalog determines every required argument, so a
+  // copied example never 400s on a missing one; see `chainExample`.
+  const worked = call ? ` A call that works exactly as written: \`return ${call};\`.` : '';
   return createTool({
     id: 'call_tool_chain',
     description: [
       CodeModeUtcpClient.AGENT_PROMPT_TEMPLATE,
-      'Execute JavaScript code with direct access to all registered UTCP tools as hierarchical functions (e.g. `manual.tool(args)`, synchronous, no await). The runtime is plain JavaScript — no type annotations or other TypeScript-only syntax. Return the final value with `return`. Use `list_tools` and `tools_info` first to discover available tools and their interfaces.',
+      `Execute JavaScript code with direct access to all registered UTCP tools as hierarchical functions — call them as \`${ns}.<tool>({ body: { ...args } })\`, synchronous, no await.${worked} Every argument a tool declares REQUIRED must be present — for the knowledge-base tools that includes \`branch\`. The runtime is plain JavaScript — no type annotations or other TypeScript-only syntax — plus \`atob\`, \`btoa\`, \`TextEncoder\` and \`TextDecoder\` for base64 and UTF-8 bytes, as in a browser; there is no \`Buffer\`, no \`fetch\` and no \`require\`. Return the final value with \`return\`. Use \`list_tools\` and \`tools_info\` first to discover available tools and their interfaces.`,
       'Error handling inside the chain: a failing tool call THROWS, and the thrown error\'s `.message` holds the server\'s actual reason (e.g. a 403 with the explanation, not just a status code). If you catch it, surface `err.message` (and `err.status` / `err.data` when present) — NEVER `return { error: err }` or otherwise return the raw Error object, because an Error serializes to `{}` (its `message` is non-enumerable) and the reason is lost. If you don\'t need to handle it, just let it throw — the runtime already reports `err.message` back to you.',
+      `Failures are answered, never dropped: a chain that throws comes back with \`success: false\` and the reason, and one that outlives \`timeout\` (default ${CHAIN_TIMEOUT_DEFAULT_MS} ms, maximum ${CHAIN_TIMEOUT_MAX_MS} ms) comes back saying it timed out — raise \`timeout\` or split the work and run it again. Either way your next tool call works as usual.`,
       'Large return values: if the returned value exceeds `max_output_size`, the full JSON is auto-spilled to a shared spill store (outside any workspace, never committed) and the response contains only a `__tool_chain_spill__/…` ref + a truncated marker. You can read the spill back with the regular `read_file` tool — pass that ref as `path` (its `branch` is ignored) plus `offset` / `limit` to slice it, never read a multi-MB file in full. Order of preference: (1) re-run `call_tool_chain` with a follow-up code chain that filters/maps the data inline and returns just what you need; (2) narrow the API call — shorter `fields`, tighter date window, lower `limit`; (3) last resort — `read_file` against the spill ref with `offset` / `limit`. The spill is read-only context only; do NOT use it as a way to persist KB content — for KB writes use the regular `write_file` / `edit_file` tools, which go through the lock/commit pipeline.',
     ].join('\n\n'),
     inputSchema: z.object({
@@ -26,11 +59,11 @@ export function createCallToolChainTool(
       timeout: z
         .number()
         .int()
-        .min(1_000)
-        .max(120_000)
+        .min(CHAIN_TIMEOUT_MIN_MS)
+        .max(CHAIN_TIMEOUT_MAX_MS)
         .optional()
-        .default(30_000)
-        .describe('Timeout in milliseconds (default: 30000).'),
+        .default(CHAIN_TIMEOUT_DEFAULT_MS)
+        .describe(`Timeout in milliseconds (default: ${CHAIN_TIMEOUT_DEFAULT_MS}, max: ${CHAIN_TIMEOUT_MAX_MS}).`),
       max_output_size: z
         .number()
         .int()
@@ -41,15 +74,35 @@ export function createCallToolChainTool(
         .describe('Max size of the stringified result in characters (default: 200000, max: 1000000). If exceeded, the full result is spilled to the shared spill store and only a `__tool_chain_spill__/…` ref is returned.'),
     }),
     execute: async (input) => {
-      const timeout = input.timeout ?? 30_000;
+      const timeout = input.timeout ?? CHAIN_TIMEOUT_DEFAULT_MS;
       const maxOutputSize = input.max_output_size ?? 200_000;
+      // The shared runner always answers: the chain's browser globals are in
+      // place, and a timeout, an exhausted heap and an unknown namespace each
+      // come back as the sentence that says so rather than as a success with a
+      // null result (which is what the runner's own resolved shape looks like).
+      const outcome = await runToolChain(client, input.code, timeout);
+      if (!outcome.ok) {
+        // A chain that failed while calling a REMOVED tool gets the reason it
+        // was removed (who does it now, and where), not "is not a function".
+        // The failure is the signal, not the chain's source: a chain that only
+        // mentions the name and died of something else keeps its own error.
+        const message = retiredToolInFailure(outcome.error) ?? outcome.error;
+        return {
+          success: false,
+          error: message,
+          ...(outcome.logs.length ? { logs: outcome.logs } : {}),
+          ...(outcome.status !== undefined ? { status: outcome.status } : {}),
+          ...(outcome.data !== undefined ? { data: outcome.data } : {}),
+        };
+      }
+      const { result: rawResult, logs } = outcome;
+      // Everything past the outcome is still fallible — `omitImagePayloads`
+      // walks a value the chain built, `JSON.stringify` can meet a cycle or a
+      // BigInt, and the spill store writes to disk. This tool promises a
+      // STRUCTURED failure for every outcome, so a disk or serialization error
+      // must come back as `success: false` with its reason rather than as an
+      // unhandled tool failure the agent sees as a dropped call.
       try {
-        const { result: rawResult, logs } = await client.callToolChain(input.code, timeout);
-        // The runner reports a failed chain in `logs` rather than throwing, so
-        // a chain that died calling a removed tool is recognised here: the agent
-        // gets who does it now, not "is not a function".
-        const retired = retiredToolChainFailure({ result: rawResult, logs });
-        if (retired) return { success: false, error: retired, logs };
         // Same policy as the MCP surfaces' `call_tool_chain` (see
         // `omitImagePayloads`): a chain result is stringified JSON, so an image
         // read inside it comes back as an omitted-image note instead of a
@@ -68,36 +121,30 @@ export function createCallToolChainTool(
           result_bytes: bytes,
           message: `Combined result+logs payload was ${fullJson.length} characters (exceeded max_output_size of ${maxOutputSize}). Full JSON (both \`result\` and \`logs\`) saved to the shared spill store as \`${ref}\` (outside any workspace, uncommitted). Read it back with \`read_file\` — pass that ref as \`path\` (\`branch\` is ignored) plus \`offset\` / \`limit\` for a slice — or, usually better, narrow the next \`call_tool_chain\` call (smaller fields list, tighter date window, lower limit) so the result fits inline.`,
         };
-      } catch (e) {
-        // A failed tool call inside the chain surfaces here. When the UTCP http
-        // transport carries the server's status + body on the thrown error
-        // (so non-2xx tool errors aren't reduced to a bare status code), pass
-        // them through to the agent — `e.message` already holds the server's
-        // reason, and `status` / `data` give it the structured detail.
-        const raw = e instanceof Error ? e.message : String(e);
-        // A chain that failed while calling a removed tool gets the reason it
-        // was removed (who does it now, and where), not "is not a function".
-        // The thrown failure is the signal, not the chain's source: a chain
-        // that only mentions the name and died of something else keeps its own
-        // error, instead of hiding it behind a migration notice.
-        const message = retiredToolInFailure(raw) ?? raw;
-        const status = (e as { status?: unknown })?.status;
-        const data = (e as { data?: unknown })?.data;
+      } catch (err) {
+        // The chain itself SUCCEEDED and only its delivery failed, so the logs
+        // ride along: they are the only trace of the work left, and an agent
+        // deciding whether to re-run a long chain needs them.
         return {
           success: false,
-          error: message,
-          ...(typeof status === 'number' ? { status } : {}),
-          ...(data !== undefined ? { data } : {}),
+          error: `The chain ran, but its result could not be returned: ${err instanceof Error ? err.message : String(err)}. Re-run a narrower chain that returns only what you need.`,
+          ...(logs.length ? { logs } : {}),
         };
       }
     },
   });
 }
 
-export function createListToolsTool(client: CodeModeUtcpClient) {
+export function createListToolsTool(
+  client: CodeModeUtcpClient,
+  namespace: string,
+  tools: readonly ChainExampleTool[] = [],
+) {
+  const { name } = chainExample(namespace, tools);
   return createTool({
     id: 'list_tools',
-    description: 'Returns a list of all UTCP tool names currently registered, in their TypeScript-accessible form (e.g. `manual.tool`).',
+    // A name the catalog really has, or none: see `ChainExample.name`.
+    description: `Returns a list of all UTCP tool names currently registered, in their TypeScript-accessible form${name ? ` (e.g. \`${name}\`)` : ''}.`,
     inputSchema: z.object({}),
     execute: async () => {
       const tools = await client.config.tool_repository.getTools();
@@ -105,7 +152,6 @@ export function createListToolsTool(client: CodeModeUtcpClient) {
     },
   });
 }
-
 export function createToolsInfoTool(client: CodeModeUtcpClient) {
   return createTool({
     id: 'tools_info',

package/src/modules/database/__tests__/connection.test.ts

@@ -1,3 +1,4 @@
+import { randomBytes } from 'node:crypto';
 import { describe, it, expect, afterEach } from 'vitest';
 import {
   DEFAULT_DB_SCHEMA,
@@ -88,6 +89,17 @@ describe('getDb', () => {
     expect(getDb(URL, { schema: DEFAULT_DB_SCHEMA })).toBe(plain);
   });
 
+  it('hands the cached pool to a caller holding the same key spelled otherwise, and refuses another key', () => {
+    const raw = randomBytes(32);
+    const first = getDb(URL, { schema: 'keyed', piiKey: raw.toString('base64') });
+    opened.push(first);
+    // The same 32 bytes as hex: one key, so one pool.
+    expect(getDb(URL, { schema: 'keyed', piiKey: raw.toString('hex') })).toBe(first);
+    expect(() => getDb(URL, { schema: 'keyed', piiKey: randomBytes(32).toString('base64') })).toThrow(
+      /already open with a different personal-data key/,
+    );
+  });
+
   it('opens a fresh pool after the cached one was closed', async () => {
     const first = getDb(URL, { schema: 'closing' });
     await closeDb(first);