@bevel-software/platform-mcp-core 0.23.0 → 0.25.0

package/src/meta-tools.ts

@@ -1,8 +1,15 @@
 import type { Tool as McpTool, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { CodeModeUtcpClient } from '@utcp/code-mode';
-import { utcpNameToTsInterfaceName, findToolsByNames } from './code-mode-names.js';
-import { toCallToolResult, toolError, describeToolFailure, omitImagePayloads } from './results.js';
-import { retiredToolInFailure, retiredToolChainFailure } from './retired-tools.js';
+import { utcpNameToTsInterfaceName, findToolsByNames, sanitizeIdentifier } from './code-mode-names.js';
+import { chainExample, type ChainExample, type ChainExampleTool } from './chain-example.js';
+import { toCallToolResult, toolError, describeToolFailure, withTransportDetail, omitImagePayloads } from './results.js';
+import { retiredToolInFailure } from './retired-tools.js';
+import {
+  CHAIN_TIMEOUT_DEFAULT_MS,
+  CHAIN_TIMEOUT_MAX_MS,
+  CHAIN_TIMEOUT_MIN_MS,
+  runToolChain,
+} from './chain-runtime.js';
 
 /**
  * Code-mode meta-tools exposed ALONGSIDE the direct tools. They let an external
@@ -13,9 +20,22 @@ import { retiredToolInFailure, retiredToolChainFailure } from './retired-tools.j
  * are how it discovers what to call. There IS a system prompt over MCP now: the
  * platform header and the admin's preamble arrive as `instructions` on the
  * initialize handshake (see core-backend's modules/agent-instructions/compose.ts).
- * The protocol stays in the description regardless, because several clients
+ * The PROTOCOL stays in the description regardless, because several clients
  * (claude.ai on the web, the Agent SDK, Cline) drop that field.
  *
+ * What a chain DOES, though — to a failure, to a large result, to an image —
+ * is true of every call, and those rules are stated once, in the handshake
+ * instructions and in the platform-managed agent guide, rather than on each
+ * tool they cover. So on a surface that has those rules the chain description
+ * ends with the same pointer sentence every file tool ends with, composed
+ * where the tool is served and the guide's configured name is known
+ * (core-backend's mcp.service.ts; nothing here may spell `AGENTS.md`, since
+ * the name is a deployment setting). A client that drops `instructions` is
+ * then still told WHERE the rules are, which is what the guide is for.
+ * The standalone bridge in `hexis-mcp` passes no pointer and so serves the
+ * description WHOLE, rules included: it proxies a remote knowledge base and
+ * does not know that deployment's layout.
+ *
  * Security is identical to the direct surface: the chain runs in an isolated-vm
  * but calls tools with the CALLER's credentials against the external catalog —
  * internal-only tools aren't in that catalog, so a chain can't reach them either.
@@ -26,51 +46,166 @@ import { retiredToolInFailure, retiredToolChainFailure } from './retired-tools.j
  * the remote trio describes the remote registry, and locally they must describe
  * the merged one.
  */
-const CALL_TOOL_CHAIN_DESCRIPTION = [
-  'Execute a short JavaScript program with direct access to every registered UTCP tool as a synchronous function. Call tools as `KNOWLEDGE_BASE.<tool>({ body: { ...args } })` with NO `await` (results are already resolved), and `return` the final value. The runtime is plain JavaScript (no type annotations / no TypeScript-only syntax).',
-  'Discover first: `list_tools` lists every tool in callable form (e.g. `KNOWLEDGE_BASE.read_file`); `tools_info` returns their exact argument + return shapes — do not guess. Batch multiple tool calls into one chain to avoid a round-trip per call. The chain runs with your own connection key, so it can only reach the tools you can already call directly.',
-  'Large results: if the combined result+logs exceed `max_output_size` (default 200000 chars) the full JSON is spilled to a shared store and you get back a `__tool_chain_spill__/…` ref instead. Read it with `read_file` (pass that ref as `path` — `branch` is ignored — plus `offset`/`limit` to slice it), or better, re-run a narrower chain that returns only what you need.',
-  'Images: image files are returned as native MCP image content on a DIRECT `read_file` call only — a chained `read_file` of an image yields `{ image_omitted: true, note }` instead of the picture, so call it outside the chain to actually see the image.',
-].join('\n\n');
 
-export const CODE_MODE_META_TOOLS: McpTool[] = [
-  {
-    name: 'list_tools',
-    description:
-      'List every UTCP tool currently registered, in TypeScript-accessible form (e.g. `KNOWLEDGE_BASE.read_file`) for use inside `call_tool_chain`.',
-    inputSchema: { type: 'object', properties: {}, additionalProperties: false } as McpTool['inputSchema'],
-  },
-  {
-    name: 'tools_info',
-    description:
-      'Get full TypeScript interface definitions for named tools (names from `list_tools`). The schemas are the source of truth — do not guess shapes.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        tool_names: { type: 'array', items: { type: 'string' }, minItems: 1, description: 'Tool names to describe.' },
-      },
-      required: ['tool_names'],
-      additionalProperties: false,
-    } as McpTool['inputSchema'],
-  },
-  {
-    name: 'call_tool_chain',
-    description: CALL_TOOL_CHAIN_DESCRIPTION,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        code: { type: 'string', minLength: 1, description: 'JavaScript to execute against the registered tools.' },
-        timeout: { type: 'integer', minimum: 1000, maximum: 120000, description: 'Timeout in ms (default 30000).' },
-        max_output_size: { type: 'integer', minimum: 1000, maximum: 1000000, description: 'Max result+logs size in chars before spilling (default 200000, max 1000000).' },
-      },
-      required: ['code'],
-      additionalProperties: false,
-    } as McpTool['inputSchema'],
-  },
-];
+/** The chain tool's name, for the callers that single it out by name. */
+export const CALL_TOOL_CHAIN_NAME = 'call_tool_chain';
+
+/**
+ * The namespace every example in the three descriptions is written against.
+ *
+ * It is NOT fixed text, because it is not the same name on every connection:
+ * the hosted endpoint registers the knowledge-base tools as `KNOWLEDGE_BASE`,
+ * while the local server registers the whole deployment as one `hexis` manual.
+ * A description that named the other one taught the agent a namespace the
+ * runtime had no binding for, and the example call it copied died of
+ * `ReferenceError` — which is how this was reported. So each surface passes
+ * the name it actually registers, and the examples are built from it.
+ *
+ * Sanitized the way the runtime sanitizes it, so the example is callable even
+ * when the registered manual's name is not a bare identifier: `@utcp/code-mode`
+ * exposes `global.<sanitized manual name>`, and an example spelled any other
+ * way would not run.
+ */
+export function chainNamespaceExample(namespace: string): string {
+  return sanitizeIdentifier(namespace);
+}
+
+/**
+ * What a chain does when it FAILS — one of the rules about a chain that are
+ * true of every call, not of how to write one.
+ *
+ * Exported as text because it is stated in ONE of two places, never both: in
+ * the rules every tool shares (the handshake instructions and the managed
+ * agent guide, see core-backend's `agent-instructions/shared-file-rules.ts`)
+ * on a surface that has them, and in the chain's own description on one that
+ * does not. The same sentences either way, so the rule cannot read differently
+ * depending on where an agent found it.
+ */
+export const CHAIN_FAILURES_RULE = `Failures are answered, never dropped: a chain that throws comes back as an error carrying the reason, and one that outlives \`timeout\` (default ${CHAIN_TIMEOUT_DEFAULT_MS} ms, maximum ${CHAIN_TIMEOUT_MAX_MS} ms) comes back saying so — raise \`timeout\` or split the work and run it again. Either way the connection stays open and your next call works as usual.`;
+
+/** What a chain does with a result too large to return. Placed as {@link CHAIN_FAILURES_RULE} is. */
+export const CHAIN_LARGE_RESULTS_RULE =
+  'Large results: if the combined result+logs exceed `max_output_size` (default 200000 chars) the full JSON is spilled to a shared store and you get back a `__tool_chain_spill__/…` ref instead. Read it with `read_file` (pass that ref as `path` — `branch` is ignored — plus `offset`/`limit` to slice it), or better, re-run a narrower chain that returns only what you need.';
+
+/**
+ * What a chained read of an IMAGE gives back. On a surface with the shared
+ * rules this is part of their content rule, which states it among everything
+ * else a read returns; it is spelled here only for a description that has to
+ * carry it itself.
+ */
+const CHAIN_IMAGES_RULE =
+  'Images: image files are returned as native MCP image content on a DIRECT `read_file` call only — a chained `read_file` of an image yields `{ image_omitted: true, note }` instead of the picture, so call it outside the chain to actually see the image.';
+
+/**
+ * The chain's description, in one of two forms.
+ *
+ * WITH a `sharedRulesPointer`, it is how to write a chain and how to discover
+ * what to call, ending in that sentence: the rules about what a chain does —
+ * failures, large results, images — are stated once for every tool, in the
+ * place the pointer names, and repeating them here is what made this
+ * description long enough for a client to cut.
+ *
+ * WITHOUT one, it carries those rules itself. A surface that has no shared
+ * rules to point at (the standalone bridge, which proxies a deployment whose
+ * guide it cannot name) would otherwise tell an agent nothing about a chain
+ * that timed out.
+ */
+function callToolChainDescription(example: ChainExample, sharedRulesPointer?: string): string {
+  const { namespace: ns, name, call } = example;
+  // Printed only when the catalog determines every required argument. A call
+  // the agent cannot trust is worse than the shape on its own, and `tools_info`
+  // is one hop away either way.
+  const worked = call ? ` A call that works exactly as written: \`return ${call};\`.` : '';
+  // A name the catalog really has, or no name: see `ChainExample.name`.
+  const forInstance = name ? ` (e.g. \`${name}\`)` : '';
+  const howToWriteOne = [
+    `Execute a short JavaScript program with direct access to every registered UTCP tool as a synchronous function. Call tools as \`${ns}.<tool>({ body: { ...args } })\` with NO \`await\` (results are already resolved), and \`return\` the final value.${worked} Every argument a tool declares REQUIRED must be present — \`tools_info\` gives the exact shapes, and for the knowledge-base tools that includes \`branch\`. The runtime is plain JavaScript (no type annotations / no 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\`.`,
+    `Discover first: \`list_tools\` lists every tool in callable form${forInstance}; \`tools_info\` returns their exact argument + return shapes — do not guess. Batch multiple tool calls into one chain to avoid a round-trip per call. The chain runs with your own connection key, so it can only reach the tools you can already call directly.`,
+  ];
+  if (sharedRulesPointer !== undefined) return `${howToWriteOne.join('\n\n')}${sharedRulesPointer}`;
+  return [...howToWriteOne, CHAIN_FAILURES_RULE, CHAIN_LARGE_RESULTS_RULE, CHAIN_IMAGES_RULE].join('\n\n');
+}
+
+/** What a surface says about itself when it asks for the meta-tools. */
+export interface CodeModeMetaToolsOptions {
+  /**
+   * The sentence that ends the chain's description on a surface whose
+   * knowledge base states the shared rules (see {@link callToolChainDescription}).
+   * Opaque text: the caller composes it, because it names the agent guide and
+   * that name is a deployment setting — nothing here may spell `AGENTS.md`.
+   * Absent, the description carries the chain's rules itself.
+   */
+  sharedRulesPointer?: string;
+}
 
-export const META_TOOL_NAMES: ReadonlySet<string> = new Set(CODE_MODE_META_TOOLS.map((t) => t.name));
+/**
+ * The three meta-tools, with every example written against the namespace this
+ * connection really exposes and a tool name its catalog really has.
+ *
+ * Built per listing rather than held as a module constant: both belong to the
+ * surface, and a description computed once and shared across surfaces is the
+ * fixed text this replaces. `tools` is the surface's catalog — pass every tool
+ * it serves, names AND input schemas, since the arguments in the example come
+ * from the schema (see `chainExample`).
+ *
+ * `list_tools` and `tools_info` describe the registry, not what a call does,
+ * so neither ever carried a shared rule and neither gains the pointer.
+ */
+export function codeModeMetaTools(
+  namespace: string,
+  tools: readonly ChainExampleTool[] = [],
+  options: CodeModeMetaToolsOptions = {},
+): McpTool[] {
+  const example = chainExample(namespace, tools);
+  const { name } = example;
+  return [
+    {
+      name: 'list_tools',
+      description: `List every UTCP tool currently registered, in TypeScript-accessible form${name ? ` (e.g. \`${name}\`)` : ''} for use inside \`call_tool_chain\`.`,
+      inputSchema: { type: 'object', properties: {}, additionalProperties: false } as McpTool['inputSchema'],
+    },
+    {
+      name: 'tools_info',
+      description:
+        'Get full TypeScript interface definitions for named tools (names from `list_tools`). The schemas are the source of truth — do not guess shapes.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          tool_names: { type: 'array', items: { type: 'string' }, minItems: 1, description: 'Tool names to describe.' },
+        },
+        required: ['tool_names'],
+        additionalProperties: false,
+      } as McpTool['inputSchema'],
+    },
+    {
+      name: CALL_TOOL_CHAIN_NAME,
+      description: callToolChainDescription(example, options.sharedRulesPointer),
+      inputSchema: {
+        type: 'object',
+        properties: {
+          code: { type: 'string', minLength: 1, description: 'JavaScript to execute against the registered tools.' },
+          timeout: {
+            type: 'integer',
+            minimum: CHAIN_TIMEOUT_MIN_MS,
+            maximum: CHAIN_TIMEOUT_MAX_MS,
+            description: `Timeout in ms (default ${CHAIN_TIMEOUT_DEFAULT_MS}, max ${CHAIN_TIMEOUT_MAX_MS}).`,
+          },
+          max_output_size: { type: 'integer', minimum: 1000, maximum: 1000000, description: 'Max result+logs size in chars before spilling (default 200000, max 1000000).' },
+        },
+        required: ['code'],
+        additionalProperties: false,
+      } as McpTool['inputSchema'],
+    },
+  ];
+}
 
+/**
+ * The meta-tool NAMES, which no namespace can change. Kept separate from
+ * {@link codeModeMetaTools} because every surface needs them to route a call
+ * and to keep a discovered copy out of its listing, and neither of those knows
+ * — or should need — the namespace.
+ */
+export const META_TOOL_NAMES: ReadonlySet<string> = new Set(['list_tools', 'tools_info', CALL_TOOL_CHAIN_NAME]);
 /** Default cap on a `call_tool_chain` result's stringified size before it spills. */
 export const CALL_TOOL_CHAIN_MAX_OUTPUT = 200_000;
 
@@ -149,19 +284,38 @@ export async function dispatchMetaTool(
     // the isolate far past the documented 120s cap.
     const timeout =
       typeof args.timeout === 'number' && Number.isFinite(args.timeout)
-        ? Math.min(120_000, Math.max(1_000, Math.trunc(args.timeout)))
-        : 30_000;
+        ? Math.min(CHAIN_TIMEOUT_MAX_MS, Math.max(CHAIN_TIMEOUT_MIN_MS, Math.trunc(args.timeout)))
+        : CHAIN_TIMEOUT_DEFAULT_MS;
     // Clamp to [1000, 1_000_000] so a caller can't force oversized inline
     // output past the spill.
     const maxOutputSize =
       typeof args.max_output_size === 'number' && Number.isFinite(args.max_output_size)
         ? Math.min(1_000_000, Math.max(1_000, Math.trunc(args.max_output_size)))
         : CALL_TOOL_CHAIN_MAX_OUTPUT;
-    const { result: rawResult, logs } = await client.callToolChain(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, not in the catch.
-    const retired = retiredToolChainFailure({ result: rawResult, logs });
-    if (retired) return toolError(retired);
+    // The shared runner, which answers every failure instead of leaving one to
+    // pass for a success with a null result: the chain's own browser globals
+    // are in place, and a timeout, an exhausted heap and an unknown namespace
+    // each come back as the sentence that says so.
+    const outcome = await runToolChain(client, code, timeout);
+    if (!outcome.ok) {
+      // A chain that died calling a REMOVED tool gets the reason it was
+      // removed, not the runtime's "is not a function". Read from the failure
+      // itself, never from the chain's source: a chain that merely mentions
+      // the name and died of something else keeps its own reason. A migration
+      // notice answers alone — the transport detail below would be noise
+      // beside an answer that is not about the transport.
+      const retired = retiredToolInFailure(outcome.error);
+      if (retired) return toolError(retired);
+      // An MCP caller is answered with TEXT and nothing else, so the
+      // transport's own status and body are folded into it. `runToolChain`
+      // composes the message with `describeToolFailure` (which lifts an
+      // axios-shaped `response.data.error` out) and carries `status`/`data`
+      // beside it for the shapes that put the reason there instead; returning
+      // `outcome.error` alone dropped that half on this surface, leaving the
+      // caller with generic transport text.
+      return toolError(withTransportDetail(outcome.error, outcome.status, outcome.data));
+    }
+    const { result: rawResult, logs } = outcome;
     // Images never ride a chain result: the chain's value is stringified JSON,
     // where base64 is context flood, not a picture. A chained `read_file` of an
     // image comes back as an omitted-image note instead (see omitImagePayloads);
@@ -196,12 +350,12 @@ export async function dispatchMetaTool(
       message: `Result+logs payload was ${fullJson.length} characters (exceeded max_output_size of ${maxOutputSize}). Full JSON saved to the shared spill store as \`${ref}\`. Read it back with \`read_file\` (pass that ref as \`path\`, \`branch\` ignored, plus \`offset\`/\`limit\` to slice), or re-run a narrower chain that returns only what you need.`,
     });
   } catch (err) {
-    // A chain that failed while calling a removed tool gets the reason it was
-    // removed, not the runtime's "is not a function". Read from the failure
-    // itself, never from the chain's source: a chain that merely mentions the
-    // name and died of something else must report what really happened.
+    // `runToolChain` answers rather than throws, so a chain no longer reaches
+    // here — what does is a catalog read, a name lookup or the spill write.
+    // The retired-tool mapping is kept all the same: it costs nothing, and it
+    // is the one answer that must survive however the failure arrived.
     const failure = describeToolFailure(err);
-    const retired = name === 'call_tool_chain' ? retiredToolInFailure(failure) : undefined;
+    const retired = name === CALL_TOOL_CHAIN_NAME ? retiredToolInFailure(failure) : undefined;
     if (retired) return toolError(retired);
     return toolError(`The "${name}" tool failed: ${failure}`);
   }

package/src/results.ts

@@ -84,7 +84,17 @@ function isMcpImageBlockObject(value: unknown): value is { type: 'image'; data:
  * MCP caller sees the tool's real message instead of a bare "status code 500".
  */
 export function describeToolFailure(err: unknown): string {
-  const data = (err as { response?: { data?: unknown } })?.response?.data;
+  // Read through to the body UNDER the guard. `err` is whatever a transport
+  // threw, and a getter or Proxy on `response` — or on `response.data` — that
+  // throws while being read must not escape: this function runs inside catch
+  // paths, and `runToolChain` promises an answer for every outcome, so a throw
+  // here would surface as the dropped connection that contract rules out.
+  let data: unknown;
+  try {
+    data = (err as { response?: { data?: unknown } })?.response?.data;
+  } catch {
+    data = undefined;
+  }
   if (data && typeof data === 'object') {
     let inner: unknown;
     try {
@@ -121,6 +131,101 @@ export function describeToolFailure(err: unknown): string {
   }
 }
 
+/**
+ * Does `message` already state `status` AS a status code?
+ *
+ * The bare digits are not enough to go on: a message like `Processed 404 files`
+ * contains them without saying anything about a response code, and treating
+ * that as "already said" would drop the status from the one string the caller
+ * gets. So only the two phrasings a transport actually uses count — axios's
+ * `status code 404` and this file's own `HTTP 404` — and neither matches a
+ * longer number that merely starts with the same digits (`HTTP 4042`).
+ */
+function statesStatus(message: string, status: number): boolean {
+  return new RegExp(`(?:HTTP\\s+|status code\\s+)${status}(?!\\d)`, 'i').test(message);
+}
+
+/**
+ * `message` with the transport's own `status` and body folded INTO it, for a
+ * surface that can only answer with text.
+ *
+ * An MCP caller sees one string: the structured fields a `ToolChainOutcome`
+ * carries beside its message (`status`, `data`) reach it only if they are in
+ * that string. {@link describeToolFailure} already lifts an axios-shaped
+ * `response.data.error` out, but the UTCP http transport also throws failures
+ * carrying `status`/`data` directly, and THAT body is the actionable half —
+ * without this it was simply dropped on the way to the caller.
+ *
+ * Nothing is said twice: a message that already carries the body's own
+ * `error` reason — which is what `describeToolFailure` lifts out of an
+ * axios-shaped failure — does not get that reason again, and a status the
+ * message already STATES as a status code (see {@link statesStatus}) is not
+ * repeated either. And nothing is LOST to that: whatever else the body holds
+ * that the message does not already say (the `kind` a caller switches on, the
+ * `proposal` steps of a refused write) still follows it.
+ */
+export function withTransportDetail(message: string, status?: unknown, data?: unknown): string {
+  let out = message;
+  // An integer: a status is a response code, and `(HTTP 404.5)` would be
+  // nonsense to print and a sloppy pattern to match with.
+  if (Number.isInteger(status) && !statesStatus(out, status as number)) out += ` (HTTP ${status as number})`;
+  if (data !== undefined) {
+    // Already said? The actionable part of a body is its `error` field, and
+    // `describeToolFailure` lifts exactly that (plus `kind`) out of an
+    // axios-shaped failure — so a message already carrying it has the body in
+    // it, and appending the raw JSON beside it would read as two failures.
+    let reason: unknown;
+    try {
+      reason = (data as { error?: unknown })?.error;
+    } catch {
+      reason = undefined;
+    }
+    if (typeof reason === 'string' && reason.length > 0 && out.includes(reason)) {
+      // The reason is said. The REST of the body is said only as far as the
+      // message happens to contain it: a refusal's `kind`, its `proposal`
+      // steps or the paths it names are the half a caller acts on, and
+      // treating the whole body as covered because one of its fields was
+      // dropped them. What the message does not already carry follows it.
+      const unsaid = fieldsNotIn(out, data, 'error');
+      return unsaid === null ? out : `${out} Error data: ${unsaid}`;
+    }
+    // Total, like the rest of this file: a body that does not serialise
+    // degrades through `safeJsonText` rather than throwing in a catch path.
+    const text = typeof data === 'string' ? data : safeJsonText(data);
+    if (text.length > 0 && text !== '{}' && text !== '""' && !out.includes(text)) out += ` Error data: ${text}`;
+  }
+  return out;
+}
+
+/**
+ * The fields of `data` — all but `skip` — that `message` does not already
+ * state, as JSON; null when there is none. A field is stated when its value
+ * appears in the message: as it is for a string, a number or a boolean, as
+ * its JSON for anything else. Total: a body that cannot be walked or
+ * serialised says nothing more rather than throwing in a catch path.
+ */
+function fieldsNotIn(message: string, data: unknown, skip: string): string | null {
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) return null;
+  let unsaid: [string, unknown][];
+  try {
+    unsaid = Object.entries(data as Record<string, unknown>).filter(([key, value]) => {
+      if (key === skip || value === undefined) return false;
+      const scalar = typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+      const said = scalar ? String(value) : safeJsonText(value);
+      return !(said.length > 0 && message.includes(said));
+    });
+  } catch {
+    return null;
+  }
+  if (unsaid.length === 0) return null;
+  // `Object.fromEntries` DEFINES each entry, where an assignment would run a
+  // setter: a body is JSON from a server, any name is a legal key in it, and
+  // one called `__proto__` assigned into a plain object sets its prototype
+  // and vanishes from what is serialised. Defined, every key is just a key.
+  const text = safeJsonText(Object.fromEntries(unsaid));
+  return text.length > 0 && text !== '{}' ? text : null;
+}
+
 /**
  * Turn a tool's final value into an MCP result:
  *  - a tool that already returns the MCP agentic shape (`{ content: [...] }`,

package/src/retired-tools.ts

@@ -73,25 +73,3 @@ export function retiredToolInFailure(failure: string): string | undefined {
   }
   return undefined;
 }
-
-/** The log line `@utcp/code-mode` records when a chain's code fails. */
-const CHAIN_FAILURE_LOG = '[ERROR] Code execution failed';
-
-/**
- * The retired-tool message for a chain that FAILED on a retired tool, read
- * from what `callToolChain` returned. The runner does not throw when the code
- * fails — it resolves `{ result: null, logs }` with a `[ERROR] Code execution
- * failed: …` line (e.g. `KNOWLEDGE_BASE.merge_change_request is not a
- * function`) — so a caller's catch never sees it. Undefined for a chain that
- * succeeded, or one whose failure does not name a retired tool.
- */
-export function retiredToolChainFailure(outcome: { result: unknown; logs?: unknown }): string | undefined {
-  if (outcome.result !== null && outcome.result !== undefined) return undefined;
-  const logs = Array.isArray(outcome.logs) ? outcome.logs : [];
-  const failures = logs.filter((l): l is string => typeof l === 'string' && l.startsWith(CHAIN_FAILURE_LOG));
-  for (const failure of failures) {
-    const message = retiredToolInFailure(failure);
-    if (message) return message;
-  }
-  return undefined;
-}