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

package/src/modules/code-mode/__tests__/chain-runtime.e2e.test.ts

@@ -0,0 +1,335 @@
+import { describe, expect, it, vi, beforeAll, afterAll } from 'vitest';
+import '@utcp/direct-call';
+import { addFunctionToUtcpDirectCall } from '@utcp/direct-call';
+import { CodeModeUtcpClient } from '@utcp/code-mode';
+import { codeModeMetaTools, dispatchMetaTool } from '@bevel-software/platform-mcp-core';
+import { createCallToolChainTool } from '../code-mode.tool.js';
+
+/**
+ * Every Scenario of the Specification, against a REAL `isolated-vm` isolate.
+ *
+ * mcp-core pins the runtime's pieces one by one, which is where the arithmetic
+ * belongs. What it cannot show is that a chain can actually REACH `atob`, that
+ * `while(true){}` really is answered rather than dropped, and that the
+ * connection survives it — all three are properties of the isolate and of the
+ * runner's own resolved shape, and a mock of `callToolChain` would be asserting
+ * our belief about `@utcp/code-mode` rather than its behaviour. So this file
+ * registers a live manual and runs real chains through the shipping tool.
+ */
+
+const NAMESPACE = 'KNOWLEDGE_BASE';
+let client: CodeModeUtcpClient;
+
+/**
+ * The manual is shaped exactly as `toolDef` shapes a real knowledge-base tool:
+ * flat arguments wrapped under one required `body`, `branch` required inside it
+ * with no `default` and no `enum`, and a handler that REFUSES a call without it
+ * the way the route does. That refusal is the point — it is what turned a
+ * plausible-looking example into `400 … \`branch\` is required`, and a fixture
+ * that accepted anything would have let the example through again.
+ */
+function kbTool(name: string, required: string[], callable: string) {
+  const properties: Record<string, unknown> = {
+    branch: { type: 'string', minLength: 1, description: 'The branch this operates on.' },
+    path: { type: 'string', description: 'The path to read.' },
+  };
+  return {
+    name,
+    description: `A live ${name}, so the namespace is a real object.`,
+    inputs: {
+      type: 'object',
+      properties: {
+        body:
+          required.length === 0
+            ? { type: 'object', properties: {}, additionalProperties: false }
+            : {
+                type: 'object',
+                properties: Object.fromEntries(required.map((k) => [k, properties[k]])),
+                required,
+                additionalProperties: false,
+              },
+      },
+      required: ['body'],
+      additionalProperties: false,
+    },
+    outputs: { type: 'object', properties: {} },
+    tool_call_template: { call_template_type: 'direct-call', callable_name: callable },
+  };
+}
+
+/**
+ * The real `read_file` handler, as a named installer rather than an inline
+ * closure, because a test that swaps it has to put THIS back. Restoring a
+ * permissive stand-in instead silently disarmed the branch check for every
+ * test that ran afterwards — which is how a test for the missing-argument
+ * failure passed while asserting the opposite.
+ *
+ * Note the unwrapping: the direct-call protocol hands the callable the inner
+ * `body` object, so what arrives is `{ branch, path }`, not `{ body: … }`.
+ */
+function installReadFile(): void {
+  addFunctionToUtcpDirectCall('e2e_read_file', async (args: unknown) => {
+    const given = (args ?? {}) as Record<string, unknown>;
+    const body = (given.body as Record<string, unknown> | undefined) ?? given;
+    // The server's own refusal, reproduced: identity never implies a
+    // workspace, so `branch` always comes from the argument.
+    if (!body.branch) throw new Error('HTTP 400: `branch` is required');
+    if (!body.path) throw new Error('HTTP 400: `path` is required');
+    return { content: 'live' };
+  });
+}
+
+beforeAll(async () => {
+  addFunctionToUtcpDirectCall('e2e_manual', async () => ({
+    utcp_version: '1.0.0',
+    manual_version: '1.0.0',
+    tools: [
+      kbTool('read_file', ['branch', 'path'], 'e2e_read_file'),
+      kbTool('start_session', [], 'e2e_start_session'),
+    ],
+  }));
+  installReadFile();
+  addFunctionToUtcpDirectCall('e2e_start_session', async () => ({ sessionId: 's-1' }));
+  client = await CodeModeUtcpClient.create(process.cwd(), null);
+  const registered = await client.registerManual({
+    name: NAMESPACE,
+    call_template_type: 'direct-call',
+    callable_name: 'e2e_manual',
+  } as never);
+  expect(registered.success).toBe(true);
+}, 60_000);
+
+afterAll(async () => {
+  await client?.close();
+});
+
+type ChainResult = {
+  success: boolean;
+  result?: unknown;
+  error?: string;
+  logs?: string[];
+};
+
+/** This client's catalog, in the shape the description builder takes. */
+async function catalog(): Promise<{ utcpName: string; inputSchema: unknown }[]> {
+  return (await client.config.tool_repository.getTools()).map((t) => ({
+    utcpName: t.name,
+    inputSchema: t.inputs,
+  }));
+}
+
+/** The shipping Mastra tool, run for real against the LIVE catalog. */
+async function chain(code: string, timeout?: number): Promise<ChainResult> {
+  const tool = createCallToolChainTool(
+    client,
+    { write: vi.fn() } as never,
+    NAMESPACE,
+    await catalog(),
+  ) as unknown as {
+    execute: (input: { code: string; timeout?: number }) => Promise<ChainResult>;
+  };
+  return tool.execute({ code, ...(timeout === undefined ? {} : { timeout }) });
+}
+
+/** The same chain through the MCP surfaces' dispatcher. */
+async function mcpChain(code: string, timeout?: number): Promise<{ isError?: boolean; text: string }> {
+  const res = await dispatchMetaTool(client, 'call_tool_chain', {
+    code,
+    ...(timeout === undefined ? {} : { timeout }),
+  });
+  return { isError: res.isError as boolean | undefined, text: (res.content[0] as { text: string }).text };
+}
+
+describe('the chain runtime, in a real isolate', () => {
+  it('has atob, and it decodes', async () => {
+    expect(await chain("return atob('SGVsbG8=')")).toMatchObject({ success: true, result: 'Hello' });
+  });
+
+  it('round-trips UTF-8 text through TextEncoder and TextDecoder', async () => {
+    const out = await chain("return new TextDecoder().decode(new TextEncoder().encode('über'))");
+    expect(out).toMatchObject({ success: true, result: 'über' });
+  });
+
+  it('has all four globals as functions', async () => {
+    const out = await chain(
+      'return [typeof atob, typeof btoa, typeof TextEncoder, typeof TextDecoder]',
+    );
+    expect(out.result).toEqual(['function', 'function', 'function', 'function']);
+  });
+
+  it('encodes the bytes a browser encodes, and base64s them', async () => {
+    const out = await chain(
+      "const b = new TextEncoder().encode('über'); return [Array.from(b), btoa(String.fromCharCode.apply(null, Array.from(b)))]",
+    );
+    expect(out.result).toEqual([[195, 188, 98, 101, 114], 'w7xiZXI=']);
+  });
+
+  it('decodes base64 back into UTF-8 text', async () => {
+    const out = await chain(
+      "const s = atob('w7xiZXI='); const b = new Uint8Array(s.length); for (let i = 0; i < s.length; i++) b[i] = s.charCodeAt(i); return new TextDecoder().decode(b)",
+    );
+    expect(out).toMatchObject({ success: true, result: 'über' });
+  });
+
+  it('offers them on the MCP surfaces too', async () => {
+    const out = await mcpChain("return atob('SGVsbG8=')");
+    expect(out.isError).toBeFalsy();
+    expect(JSON.parse(out.text)).toMatchObject({ success: true, result: 'Hello' });
+  });
+});
+
+describe('a chain that outlives its timeout, in a real isolate', () => {
+  it('is answered with a timeout error, and the connection stays usable', async () => {
+    const out = await chain('while(true){}', 1_000);
+    expect(out.success).toBe(false);
+    expect(out.error).toContain('timed out after 1000 ms');
+    expect(out.error).toContain('`timeout`');
+    expect(out.error).toContain('120000');
+    // The Scenario's second half: the NEXT call on the same connection works.
+    expect(await chain("return KNOWLEDGE_BASE.read_file({ body: { branch: 'main', path: 'x' } })")).toMatchObject({
+      success: true,
+      result: { content: 'live' },
+    });
+  }, 30_000);
+
+  it('is answered the same way on the MCP surfaces, which then serve the next call', async () => {
+    const timedOut = await mcpChain('while(true){}', 1_000);
+    expect(timedOut.isError).toBe(true);
+    expect(timedOut.text).toContain('timed out after 1000 ms');
+    expect(timedOut.text).toContain('120000');
+    const next = await mcpChain("return KNOWLEDGE_BASE.read_file({ body: { branch: 'main', path: 'x' } })");
+    expect(next.isError).toBeFalsy();
+    expect(JSON.parse(next.text)).toMatchObject({ success: true });
+    // And a plain tool listing still answers, so nothing about the session died.
+    const listed = await dispatchMetaTool(client, 'list_tools', {});
+    expect((listed.content[0] as { text: string }).text).toContain('KNOWLEDGE_BASE.read_file');
+  }, 30_000);
+});
+
+describe('a chain that fails some other way, in a real isolate', () => {
+  it('is told which namespaces exist when it names one that does not', async () => {
+    const out = await chain("return WRONG.read_file({ path: 'x' })");
+    expect(out.success).toBe(false);
+    expect(out.error).toContain('WRONG is not defined');
+    expect(out.error).toContain('KNOWLEDGE_BASE');
+    expect(out.error).toContain('list_tools');
+  });
+
+  it('is answered with its own reason when the chain throws', async () => {
+    const out = await chain("throw new Error('the chain said no')");
+    expect(out.success).toBe(false);
+    expect(out.error).toContain('the chain said no');
+  });
+
+  it('is answered with the tool\'s reason when a tool inside it throws', async () => {
+    addFunctionToUtcpDirectCall('e2e_read_file', async () => {
+      throw new Error("You don't have read access to \"Secret.md\"");
+    });
+    try {
+      const out = await chain("return KNOWLEDGE_BASE.read_file({ body: { branch: 'main', path: 'Secret.md' } })");
+      expect(out.success).toBe(false);
+      expect(out.error).toContain('read access');
+    } finally {
+      // The REAL handler back, branch check included — see `installReadFile`.
+      installReadFile();
+    }
+  });
+
+  it('is answered with the compiler\'s own complaint rather than an empty success', async () => {
+    const out = await chain('return (((');
+    expect(out.success).toBe(false);
+    expect(out.error).toMatch(/Unexpected token/);
+  });
+
+  it('reports a failure against the chain\'s OWN line numbers, the prelude notwithstanding', async () => {
+    // The single-line prelude earns its keep here: the stack must name the
+    // line of the agent's code, not a line of a runtime it cannot see.
+    const out = await chain('const a = 1;\nconst b = 2;\nreturn WRONG.go();');
+    expect(out.success).toBe(false);
+    const noPrelude = await client.callToolChain('const a = 1;\nconst b = 2;\nreturn WRONG.go();', 10_000);
+    const line = (s: string) => /<isolated-vm>:(\d+):/.exec(s)?.[1];
+    expect(line(noPrelude.logs.join('\n'))).toBeDefined();
+    // Same reported line with and without the prelude in front of the chain.
+    const withPrelude = await client.callToolChain(
+      (await import('@bevel-software/platform-mcp-core')).withChainRuntime(
+        'const a = 1;\nconst b = 2;\nreturn WRONG.go();',
+      ),
+      10_000,
+    );
+    expect(line(withPrelude.logs.join('\n'))).toBe(line(noPrelude.logs.join('\n')));
+  }, 30_000);
+});
+
+describe('a chain that succeeds, in a real isolate', () => {
+  it('still calls its tools and returns its value', async () => {
+    const out = await chain(
+      "const a = KNOWLEDGE_BASE.read_file({ body: { branch: 'main', path: 'x' } }); return { seen: a.content, b64: btoa(a.content) };",
+    );
+    expect(out).toMatchObject({ success: true, result: { seen: 'live', b64: 'bGl2ZQ==' } });
+  });
+
+  it('can still return null without being read as a failure', async () => {
+    expect(await chain('return null')).toMatchObject({ success: true, result: null });
+  });
+});
+
+/**
+ * The acceptance criterion itself: an agent that copies the example call out of
+ * the description gets a WORKING call. Run verbatim, in a real isolate, against
+ * a manual that refuses a call without `branch` exactly as the route does.
+ *
+ * This is the test whose absence shipped the bug. The unit tests checked that
+ * the example's NAME came from the catalog; nothing executed it, so nobody
+ * noticed the arguments beside the name were fixed text omitting a required
+ * one. Here the example is extracted from the generated description and run.
+ */
+describe('the example call in the description, copied verbatim', () => {
+  async function printedExample(): Promise<string> {
+    const tool = createCallToolChainTool(
+      client,
+      { write: vi.fn() } as never,
+      NAMESPACE,
+      await catalog(),
+    ) as unknown as { description: string };
+    const printed = /works exactly as written: `return ([^`]+);`/.exec(tool.description);
+    expect(printed, 'the description printed no example call').not.toBeNull();
+    return printed![1]!;
+  }
+
+  it('runs, and returns a value rather than an error', async () => {
+    const example = await printedExample();
+    const out = await chain(`return ${example};`);
+    expect(out.success).toBe(true);
+    expect(out.error).toBeUndefined();
+    expect(out.result).not.toBeNull();
+  });
+
+  it('runs on the MCP surfaces too, from the description THEY serve', async () => {
+    const chainTool = codeModeMetaTools(NAMESPACE, await catalog()).find(
+      (t) => t.name === 'call_tool_chain',
+    )!;
+    const printed = /works exactly as written: `return ([^`]+);`/.exec(chainTool.description!);
+    expect(printed).not.toBeNull();
+    const out = await mcpChain(`return ${printed![1]!};`);
+    expect(out.isError).toBeFalsy();
+    expect(JSON.parse(out.text)).toMatchObject({ success: true });
+  });
+
+  /**
+   * The fixture has teeth. If a missing `branch` were quietly accepted, the
+   * test above would pass for the wrong reason and the regression would be
+   * invisible again — so prove the refusal is real.
+   */
+  it('fails when a required argument is dropped, which is what the old example did', async () => {
+    const out = await chain("return KNOWLEDGE_BASE.read_file({ body: { path: 'x' } })");
+    expect(out.success).toBe(false);
+    expect(out.error).toContain('`branch` is required');
+  });
+
+  it('names a tool the catalog actually has, in the form the runtime binds', async () => {
+    const example = await printedExample();
+    const name = /^([\w.$]+)\(/.exec(example)![1]!;
+    const bound = await chain(`return typeof ${name};`);
+    expect(bound).toMatchObject({ success: true, result: 'function' });
+  });
+});

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

@@ -86,7 +86,7 @@ describe('call_tool_chain image scrub', () => {
       callToolChain: vi.fn(async () => ({ result: { pic: sentinel, ok: true }, logs: [] as string[] })),
     } as unknown as CodeModeUtcpClient;
     const spill = { write: vi.fn(async () => ({ ref: '__tool_chain_spill__/x.json', bytes: 1 })) };
-    const tool = createCallToolChainTool(chainClient, spill as never) as unknown as {
+    const tool = createCallToolChainTool(chainClient, spill as never, 'KNOWLEDGE_BASE') as unknown as {
       execute: (input: { code: string }) => Promise<unknown>;
     };
     const out = JSON.stringify(await tool.execute({ code: 'return 1' }));
@@ -98,6 +98,50 @@ describe('call_tool_chain image scrub', () => {
   });
 });
 
+/**
+ * `call_tool_chain` promises a STRUCTURED answer for every outcome. The work
+ * past the runner is still fallible — the spill store writes to disk, and
+ * `JSON.stringify` can meet a value it cannot serialize — and an exception
+ * escaping `execute` reaches the agent as an unhandled tool failure, which is
+ * the dropped call this ticket is about.
+ */
+describe('call_tool_chain when the result cannot be delivered', () => {
+  async function runWith(spill: { write: (json: string) => Promise<{ ref: string; bytes: number }> }, result: unknown) {
+    const { createCallToolChainTool } = await import('../code-mode.tool.js');
+    const chainClient = {
+      callToolChain: vi.fn(async () => ({ result, logs: ['[LOG] halfway'] as string[] })),
+    } as unknown as CodeModeUtcpClient;
+    const tool = createCallToolChainTool(chainClient, spill as never, 'KNOWLEDGE_BASE') as unknown as {
+      execute: (input: { code: string; max_output_size?: number }) => Promise<{
+        success: boolean;
+        error?: string;
+        logs?: string[];
+      }>;
+    };
+    return tool.execute({ code: 'return 1', max_output_size: 1_000 });
+  }
+
+  it('answers with the reason when the spill store cannot write', async () => {
+    const out = await runWith(
+      { write: vi.fn(async () => Promise.reject(new Error('ENOSPC: no space left on device'))) },
+      'x'.repeat(2_000),
+    );
+    expect(out.success).toBe(false);
+    expect(out.error).toContain('ENOSPC');
+    // The chain itself ran, so its logs are the only trace of the work left.
+    expect(out.logs).toEqual(['[LOG] halfway']);
+  });
+
+  it('answers with the reason when the chain\'s value cannot be serialized', async () => {
+    // A BigInt, not a cycle: `omitImagePayloads` already replaces a cycle with
+    // `"[Circular]"`, so a cyclic result serializes fine and is not this case.
+    const out = await runWith({ write: vi.fn(async () => ({ ref: 'r', bytes: 1 })) }, { n: 1n });
+    expect(out.success).toBe(false);
+    expect(out.error).toMatch(/could not be returned/);
+    expect(out.error).toMatch(/BigInt/);
+  });
+});
+
 /**
  * `merge_change_request` is retired from every agent tool set, the in-app
  * chat's included. A chain still calling it gets who merges now, not the
@@ -108,7 +152,7 @@ describe('call_tool_chain and a retired tool', () => {
 
   async function runWith(chainClient: CodeModeUtcpClient, code: string) {
     const { createCallToolChainTool } = await import('../code-mode.tool.js');
-    const tool = createCallToolChainTool(chainClient, { write: vi.fn() } as never) as unknown as {
+    const tool = createCallToolChainTool(chainClient, { write: vi.fn() } as never, 'KNOWLEDGE_BASE') as unknown as {
       execute: (input: { code: string }) => Promise<{ success: boolean; error?: string; result?: unknown }>;
     };
     return tool.execute({ code });

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);