@bevel-software/platform-mcp-core 0.15.1 → 0.19.0

package/dist/session-recovery.js

@@ -0,0 +1,309 @@
+import { registerManual } from './dispatch.js';
+/**
+ * Client-side recovery from MCP session loss: when a remote MCP server has
+ * forgotten the session our manual holds — almost always because it restarted —
+ * re-register that manual once and retry the call once.
+ *
+ * WHY IT LIVES ON THE CLIENT OBJECT. Two paths reach a tool call in our stack:
+ * `dispatchToolCall` (the MCP surface of the hosted proxy and of the local
+ * server) goes through `callToolStreaming`, and a code-mode chain
+ * (`call_tool_chain`, gate probes) goes through `callTool` — `callToolChain`
+ * bridges every in-isolate tool function to `this.callTool`. Wrapping those two
+ * methods ON THE CLIENT INSTANCE is the one seam both paths cross, so the
+ * policy exists exactly once instead of being copied into each caller.
+ *
+ * WHY ONLY SESSION LOSS. A retry is only safe when the first attempt provably
+ * did nothing. Session loss is decided in the server's ROUTING layer, before
+ * the request is dispatched to a tool, so a mutating tool cannot have run.
+ * Every other failure — a tool error, an auth refusal, a timeout, a reset
+ * connection — could have executed the tool, and is surfaced unchanged. That is
+ * the whole safety argument: it rests on the trigger class, so
+ * {@link isSessionLoss} is deliberately narrow and separately testable.
+ */
+/** The JSON-RPC code the Streamable HTTP transport reserves for a missing session. */
+const SESSION_NOT_FOUND_CODE = -32001;
+/** How far up a `cause` chain to look before giving up. */
+const MAX_CAUSE_DEPTH = 8;
+/** Each error in `err`'s `cause` chain, nearest first, bounded and cycle-safe. */
+function* errorChain(err) {
+    const seen = new Set();
+    let current = err;
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH; depth += 1) {
+        if (current === null || typeof current !== 'object' || seen.has(current))
+            return;
+        seen.add(current);
+        yield current;
+        current = current.cause;
+    }
+}
+/**
+ * The HTTP status an error carries, or undefined when it carries none.
+ *
+ * The MCP SDK's `StreamableHTTPError` puts the HTTP status in `code`, which is
+ * also where `McpError` puts its JSON-RPC code — and those two namespaces
+ * OVERLAP on the very number this module cares about: `-32001` is "Session not
+ * found" on the wire but `ErrorCode.RequestTimeout` in the SDK's own enum. The
+ * range test is what keeps them apart: a JSON-RPC code is negative and can
+ * never be read as a status, so a local request timeout never looks like a
+ * session miss (and is never retried).
+ */
+function httpStatusOf(err) {
+    for (const key of ['code', 'status', 'statusCode']) {
+        const value = err[key];
+        if (typeof value === 'number' && value >= 100 && value <= 599)
+            return value;
+    }
+    return undefined;
+}
+/**
+ * Does this error's text carry the session-not-found signal?
+ *
+ * The transport surfaces a failed POST as `Error POSTing to endpoint: <body>`,
+ * so the server's JSON-RPC body rides along in the message and is the only
+ * place the `-32001` is visible. Both halves of the spec's signal are accepted
+ * — the code (structural) and the reserved message — because a server may send
+ * either; requiring the 404 alongside is what keeps this from over-matching.
+ */
+function saysSessionNotFound(message) {
+    return (new RegExp(`"code"\\s*:\\s*${SESSION_NOT_FOUND_CODE}\\b`).test(message) ||
+        /\bsession not found\b/i.test(message));
+}
+/**
+ * Is `err` unambiguously "the server has forgotten this session"?
+ *
+ * The signal is HTTP 404 carrying JSON-RPC `-32001` / "Session not found", which
+ * the MCP spec reserves for exactly one meaning: the request presented an
+ * `Mcp-Session-Id` the server no longer holds, and the client should
+ * re-initialize. The presented-a-session-id half is not observable from here,
+ * and does not need to be: a request with NO session id is answered 400 /
+ * `-32000` (a client mistake with nothing to recover), so a 404 in this shape
+ * implies a session id was sent.
+ *
+ * Everything else is false — including a 404 whose body is an ordinary
+ * not-found, an auth refusal, a timeout (see {@link httpStatusOf}), and a
+ * refused connection. Pure and exported so this boundary can be pinned by test
+ * rather than inferred from the recovery path around it.
+ */
+export function isSessionLoss(err) {
+    for (const candidate of errorChain(err)) {
+        if (httpStatusOf(candidate) !== 404)
+            continue;
+        const message = candidate.message;
+        if (typeof message === 'string' && saysSessionNotFound(message))
+            return true;
+    }
+    return false;
+}
+const messageOf = (err) => (err instanceof Error ? err.message : String(err));
+/**
+ * Per-client re-registration counters, keyed by manual — the same maps the
+ * installed recovery reads, reachable from {@link noteManualReregistered} so a
+ * surface can report a re-registration of its own.
+ */
+const GENERATIONS = new WeakMap();
+/**
+ * Tell recovery that `manualName`'s session was replaced by something OTHER
+ * than recovery. `hexis-mcp` re-registers the remote manual whenever a renewed
+ * connection key arrives; a call that lost its session around such a swap must
+ * then retry against THAT session instead of deregistering it and dialing a
+ * third one. Without this the two paths each replace a session the other just
+ * made — correct, but a round trip and a discovery pass wasted on every
+ * overlap. No-op when recovery is not installed on `client`.
+ */
+export function noteManualReregistered(client, manualName) {
+    const generations = GENERATIONS.get(client);
+    if (!generations)
+        return;
+    generations.set(manualName, (generations.get(manualName) ?? 0) + 1);
+}
+/**
+ * Wrap `client`'s tool-call entry points with session recovery, in place.
+ *
+ * Returns the same client so it can be used as an expression at the
+ * construction site. Installing twice is a no-op: the second call would stack a
+ * second retry on the first, which is precisely the "exactly once" guarantee
+ * this module exists to make.
+ */
+const INSTALLED = Symbol.for('@bevel-software/platform-mcp-core.sessionRecovery');
+export function installSessionRecovery(client, options) {
+    const marked = client;
+    if (marked[INSTALLED])
+        return client;
+    marked[INSTALLED] = true;
+    const log = options.log ?? ((message) => console.error(message));
+    const callTool = client.callTool.bind(client);
+    const callToolStreaming = client.callToolStreaming.bind(client);
+    /**
+     * How many times each manual has been re-registered. A call reads this
+     * BEFORE its attempt; if the number moved while the attempt was in flight,
+     * some other call already replaced the session this one was using and the
+     * retry can go straight through — no second re-registration, and no window
+     * in which a burst of failures that arrive slightly apart each starts its
+     * own. Together with `inflight` below, this is what makes the coalescing
+     * hold for concurrent calls whether they fail together or in sequence.
+     */
+    const generations = new Map();
+    GENERATIONS.set(client, generations);
+    const inflight = new Map();
+    const generationOf = (manualName) => generations.get(manualName) ?? 0;
+    /**
+     * Deregister + register once. Reports what happened; the caller does the
+     * logging. `generation` is what the failing call saw before its attempt: if
+     * the counter has moved, the session has ALREADY been replaced — by the
+     * surface's own credential swap, or by another call — and replacing it again
+     * would throw away a live session to dial an identical one.
+     *
+     * Tested TWICE, because this function has two places it can wait and either
+     * is long enough for a swap to land: the surface's gate (before the call
+     * arrives here) and `manualTemplate`, which a surface may deliberately park
+     * in. The check that matters is the one immediately before the deregister —
+     * the first is only there to skip work nobody needs.
+     */
+    async function reregisterNow(manualName, generation) {
+        const notes = [];
+        const reused = { ok: true, reused: true, notes };
+        if (generationOf(manualName) !== generation)
+            return reused;
+        const template = await options.manualTemplate(manualName);
+        // Not ours to re-register — or not an MCP manual at all, in which case it
+        // holds no session and the 404 came from somewhere we must not second-guess.
+        // Silent on purpose: nothing happened, so there is nothing to report.
+        if (!template || template.call_template_type !== 'mcp')
+            return { ok: false, notes };
+        // Resolving the template is itself a place a surface waits.
+        if (generationOf(manualName) !== generation)
+            return reused;
+        try {
+            // Deregistering is what closes the manual's (now dead) session, so the
+            // registration below dials a fresh one instead of reusing the cached
+            // transport. Best effort: a manual already gone is not a failure here.
+            await client.deregisterManual(manualName);
+        }
+        catch (err) {
+            notes.push(`deregistering first failed: ${messageOf(err)}`);
+        }
+        const result = await registerManual(client, template);
+        if (!result.ok) {
+            // The server is very likely still coming back up. The call fails as it
+            // would have anyway; the NEXT one recovers once the server answers.
+            notes.push(`re-registration failed: ${result.error}`);
+            return { ok: false, notes };
+        }
+        generations.set(manualName, generationOf(manualName) + 1);
+        if (options.afterReregister) {
+            try {
+                await options.afterReregister(manualName);
+            }
+            catch (err) {
+                notes.push(`post-re-registration cleanup failed: ${messageOf(err)}`);
+            }
+        }
+        return { ok: true, notes };
+    }
+    /**
+     * {@link reregisterNow} under the surface's own gate, if it has one, and with
+     * every escape route closed. NEVER throws — and that is load-bearing: a
+     * throwing template resolver (or gate) must not replace the caller's real
+     * session-loss error with a recovery-internal one. The answer here is only
+     * ever "may we retry?".
+     */
+    async function reregister(manualName, generation) {
+        try {
+            return options.withReregister
+                ? await options.withReregister(manualName, () => reregisterNow(manualName, generation))
+                : await reregisterNow(manualName, generation);
+        }
+        catch (err) {
+            return { ok: false, notes: [`re-registration threw: ${messageOf(err)}`] };
+        }
+    }
+    /**
+     * Single-flight {@link reregister}: concurrent losers share one attempt.
+     *
+     * The generation belongs to whoever started the attempt, and that is right
+     * for the joiners too — {@link recover} sends nobody here whose generation
+     * differs from the current one, so every sharer of this promise failed
+     * against the same session.
+     */
+    function reregisterOnce(manualName, generation) {
+        const existing = inflight.get(manualName);
+        if (existing)
+            return existing;
+        const tracked = reregister(manualName, generation).finally(() => {
+            if (inflight.get(manualName) === tracked)
+                inflight.delete(manualName);
+        });
+        inflight.set(manualName, tracked);
+        return tracked;
+    }
+    /**
+     * May this failed call be retried? True only for session loss on a manual we
+     * hold a template for, and only after the session has actually been replaced.
+     */
+    async function recover(toolName, generation, err) {
+        if (!isSessionLoss(err))
+            return false;
+        const manualName = toolName.split('.')[0];
+        if (!manualName)
+            return false;
+        /** The session was replaced by someone else — a concurrent call, or the surface. */
+        const alreadyReplaced = () => {
+            log(`[mcp] session lost on '${manualName}' — re-registered by a concurrent call; retrying.`);
+            return true;
+        };
+        // Someone else re-registered while this call was in flight: the session it
+        // failed against is already gone, so retry against the new one directly.
+        if (generationOf(manualName) !== generation)
+            return alreadyReplaced();
+        const outcome = await reregisterOnce(manualName, generation);
+        // The same finding, made too late to skip the queue: the re-registration
+        // landed while this call waited for the surface's gate.
+        if (outcome.reused)
+            return alreadyReplaced();
+        // One recovered call, one line — whatever went sideways on the way rides
+        // along in it rather than arriving as a line of its own.
+        const notes = outcome.notes.length > 0 ? ` (${outcome.notes.join('; ')})` : '';
+        if (!outcome.ok) {
+            if (notes) {
+                log(`[mcp] session lost on '${manualName}' — not recovered${notes}; the original failure stands.`);
+            }
+            return false;
+        }
+        log(`[mcp] session lost on '${manualName}' — re-registered and retried.${notes}`);
+        return true;
+    }
+    client.callTool = async function recoveringCallTool(toolName, toolArgs) {
+        const generation = generationOf(toolName.split('.')[0] ?? '');
+        try {
+            return await callTool(toolName, toolArgs);
+        }
+        catch (err) {
+            if (!(await recover(toolName, generation, err)))
+                throw err;
+            // Exactly one retry: whatever this produces is what the caller sees,
+            // including a second session loss.
+            return await callTool(toolName, toolArgs);
+        }
+    };
+    client.callToolStreaming = async function* recoveringCallToolStreaming(toolName, toolArgs) {
+        const generation = generationOf(toolName.split('.')[0] ?? '');
+        let yielded = false;
+        try {
+            for await (const chunk of callToolStreaming(toolName, toolArgs)) {
+                yielded = true;
+                yield chunk;
+            }
+            return;
+        }
+        catch (err) {
+            // A stream that already produced output is past the point where session
+            // loss can happen (the session is validated before the first byte), and
+            // replaying it would duplicate the chunks the caller already saw.
+            if (yielded || !(await recover(toolName, generation, err)))
+                throw err;
+        }
+        yield* callToolStreaming(toolName, toolArgs);
+    };
+    return client;
+}
+//# sourceMappingURL=session-recovery.js.map

package/dist/session-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-recovery.js","sourceRoot":"","sources":["../src/session-recovery.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-mcp-core",
-  "version": "0.15.1",
+  "version": "0.19.0",
   "description": "The transport-agnostic half of Bevel's MCP surface: UTCP manual registration, tool discovery, MCP listing/dispatch and the code-mode meta-tools. Shared by the hosted proxy and the local stdio server.",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,14 +20,14 @@
     "THIRD-PARTY-NOTICES.md"
   ],
   "engines": {
-    "node": ">=22.13 <23"
+    "node": ">=22.13 <23 || >=24 <25"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@utcp/code-mode": "^1.2.13",
     "@utcp/http": "^1.1.12",
-    "@utcp/mcp": "^1.1.7",
-    "@utcp/sdk": "^1.1.1"
+    "@utcp/mcp": "^1.2.0",
+    "@utcp/sdk": "^1.2.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0",

package/src/index.ts

@@ -16,12 +16,14 @@
  * Everything between "a UTCP client with manuals registered" and "an MCP result"
  * is identical, and lives here: name flattening, the tool-name/schema guards
  * that stop one bad tool blanking a client's whole toolset, streaming dispatch,
- * and the code-mode meta-tools.
+ * the code-mode meta-tools, and recovery from a remote server that restarted
+ * and forgot our session (see `session-recovery.ts`).
  *
  * What is NOT here, on purpose: manual DISCOVERY (who may see which manual is
  * an access-control question the hosted REST surface answers), credential
- * resolution (a vault loader server-side, `process.env` locally), and retry
- * policy (see `registerManual`).
+ * resolution (a vault loader server-side, `process.env` locally), and
+ * REGISTRATION retry policy (see `registerManual`) — which is not the same
+ * thing as session recovery, and stays each surface's own.
  */
 
 export {
@@ -55,6 +57,21 @@ export {
 
 export { registerManual, dispatchToolCall } from './dispatch.js';
 
+export {
+  RETIRED_TOOL_MESSAGES,
+  RETIRED_TOOL_NAMES,
+  retiredToolMessage,
+  retiredToolInFailure,
+  retiredToolChainFailure,
+} from './retired-tools.js';
+
+export {
+  isSessionLoss,
+  installSessionRecovery,
+  noteManualReregistered,
+  type SessionRecoveryOptions,
+} from './session-recovery.js';
+
 export {
   type SkillSummary,
   type LoadedSkill,
@@ -74,3 +91,5 @@ export {
   findToolsByNames,
   AmbiguousToolNameError,
 } from './code-mode-names.js';
+
+export { printable } from './printable.js';

package/src/meta-tools.ts

@@ -2,14 +2,19 @@ import type { Tool as McpTool, CallToolResult } from '@modelcontextprotocol/sdk/
 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';
 
 /**
  * Code-mode meta-tools exposed ALONGSIDE the direct tools. They let an external
  * agent batch many Bevel calls into one isolated-vm run (`call_tool_chain`)
  * instead of one MCP round-trip per call — the same efficiency our own agent
- * gets. `call_tool_chain`'s description carries the code-mode protocol (there is
- * no system prompt over MCP), so the client learns the convention from the tool
- * itself; `list_tools`/`tools_info` are how it discovers what to call.
+ * gets. `call_tool_chain`'s description carries the code-mode protocol, so the
+ * client learns the convention from the tool itself; `list_tools`/`tools_info`
+ * 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
+ * (claude.ai on the web, the Agent SDK, Cline) drop that field.
  *
  * 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 —
@@ -153,6 +158,10 @@ export async function dispatchMetaTool(
         ? 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);
     // 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);
@@ -187,6 +196,13 @@ 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) {
-    return toolError(`The "${name}" tool failed: ${describeToolFailure(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.
+    const failure = describeToolFailure(err);
+    const retired = name === 'call_tool_chain' ? retiredToolInFailure(failure) : undefined;
+    if (retired) return toolError(retired);
+    return toolError(`The "${name}" tool failed: ${failure}`);
   }
 }

package/src/printable.ts

@@ -0,0 +1,23 @@
+/**
+ * Untrusted text, rendered so it cannot forge or colour a log line.
+ *
+ * Anything a caller controls — a request header, a URL, a name from an
+ * identity provider — may carry newlines or ANSI escapes, and interpolated
+ * verbatim it would start a line of its own in the operator log, or paint
+ * the terminal. `JSON.stringify` escapes the C0 controls (U+0000–U+001F)
+ * plus quote and backslash; the C1 controls (U+007F–U+009F — including
+ * U+009B, the one-byte CSI that starts an ANSI sequence on its own) and the
+ * JS line separators U+2028/U+2029 pass through raw, so those are escaped
+ * here. The result is one quoted token: `"python-httpx/0.28.1"`,
+ * `"evil\n[forged]"`.
+ *
+ * Every log line that carries caller-supplied text goes through this, and
+ * only this: the rule "the log is one line per event" is enforced at the
+ * one place text enters a line, not by each call site remembering.
+ */
+export function printable(text: string): string {
+  return JSON.stringify(text).replace(
+    /[\x7F-\x9F\u{2028}\u{2029}]/gu,
+    (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`,
+  );
+}

package/src/results.ts

@@ -86,8 +86,28 @@ function isMcpImageBlockObject(value: unknown): value is { type: 'image'; data:
 export function describeToolFailure(err: unknown): string {
   const data = (err as { response?: { data?: unknown } })?.response?.data;
   if (data && typeof data === 'object') {
-    const inner = (data as { error?: unknown }).error;
-    if (typeof inner === 'string' && inner.length > 0) return inner;
+    let inner: unknown;
+    try {
+      inner = (data as { error?: unknown }).error;
+    } catch {
+      inner = undefined;
+    }
+    if (typeof inner === 'string' && inner.length > 0) {
+      // A typed refusal (`{ error, kind, … }`) keeps its machine-readable
+      // fields: an MCP caller sees only this string, and `kind` is what it
+      // branches on. Every read of `data` past `.error` runs under the guard,
+      // so a throwing getter or Proxy cannot escape this catch path; details
+      // that do not serialise (a cycle, a BigInt) degrade via `safeJsonText`
+      // rather than dropping `kind`.
+      try {
+        const details: Record<string, unknown> = { ...(data as Record<string, unknown>) };
+        delete details.error;
+        if (typeof (details as { kind?: unknown }).kind === 'string') return `${inner} ${safeJsonText(details)}`;
+      } catch {
+        // fall through to the plain message
+      }
+      return inner;
+    }
   }
   if (typeof data === 'string' && data.length > 0) return data;
   // Total, like `safeJsonText`: a thrown value whose own `toString` throws

package/src/retired-tools.ts

@@ -0,0 +1,97 @@
+/**
+ * Agent tools that were removed on purpose, and what a caller still using the
+ * old name is told instead of a bare "Unknown tool".
+ *
+ * An agent proposes and syncs; a person merges. `merge_change_request` let an
+ * agent land a change request itself, so it is gone from every agent-facing
+ * tool set — but models (and saved scripts) keep calling a name they learned,
+ * and "Unknown tool" invites them to go looking for another way in. The answer
+ * says who does it and where.
+ *
+ * One table, read by every surface that resolves a tool name: the hosted MCP
+ * endpoint, the local `hexis-mcp` server, the code-mode `call_tool_chain`
+ * runners, and the backend's own route for the old name.
+ */
+export const RETIRED_TOOL_MESSAGES: Readonly<Record<string, string>> = Object.freeze({
+  merge_change_request:
+    '`merge_change_request` is no longer available to agents: a change request is merged by a person in the app. ' +
+    'Ask the user to review and merge it there. To bring a draft up to date with its target, use `merge_branch` ' +
+    'with the target as `source` and the draft as `target`.',
+});
+
+/**
+ * The retired tool names themselves. A surface that PROXIES another
+ * deployment needs these: an older deployment still advertises the tool, and a
+ * discovered copy left in the registry is callable — directly and from a
+ * code-mode chain — which would perform the very merge the removal forbids.
+ * Purge by name, then answer the name from {@link retiredToolMessage}.
+ */
+export const RETIRED_TOOL_NAMES: ReadonlySet<string> = new Set(Object.keys(RETIRED_TOOL_MESSAGES));
+
+/**
+ * The retired-tool message for `name`, or undefined when it is not retired.
+ * Matches the bare name and any namespaced spelling of it (`manual.tool`,
+ * `manual_tool` flattening aside — `manual__tool`, `a.b.tool`), since each
+ * surface advertises tool names in its own shape.
+ */
+export function retiredToolMessage(name: string): string | undefined {
+  for (const [retired, message] of Object.entries(RETIRED_TOOL_MESSAGES)) {
+    if (name === retired || name.endsWith(`.${retired}`) || name.endsWith(`__${retired}`)) return message;
+  }
+  return undefined;
+}
+
+/**
+ * The retired-tool message when `failure` — the text of a FAILED chain's
+ * error, not its source — names a retired tool, or undefined.
+ *
+ * The failure text is the signal, deliberately. Scanning the chain's source
+ * instead would rewrite any failure from a chain that merely MENTIONS the name
+ * in a comment, a string or an unrelated call, hiding the real reason it died
+ * behind a migration notice. The runtime names the callee it could not find
+ * ("KNOWLEDGE_BASE.merge_change_request is not a function"), so the tool that
+ * actually failed is right there in the message.
+ *
+ * Matched in the shape the runtime reports a missing callee — `<expr>.<name>
+ * is not a function`, `<name> is not defined` — and not anywhere in the text:
+ * a failure that merely QUOTES the name (a missing file whose path carries
+ * it, a server's error echoing the request) died of something else, and the
+ * migration notice would hide that.
+ *
+ * A chain that reaches the retired name through a computed property
+ * (`KNOWLEDGE_BASE['merge_' + 'change_request']()`) is not recognised: the
+ * runtime prints the expression, not the resolved name. It still fails — the
+ * tool is gone from every registry — it just fails with the runtime's own
+ * words instead of ours.
+ */
+export function retiredToolInFailure(failure: string): string | undefined {
+  for (const [retired, message] of Object.entries(RETIRED_TOOL_MESSAGES)) {
+    // The name as an identifier or a member (`X.name`), not as quoted text:
+    // a server that echoes the sentence back inside quotes is a different
+    // failure, and the quote mark before the name is what tells them apart.
+    if (new RegExp(`(?:^|[\\s.])${retired} is not (?:a function|defined)\\b`).test(failure)) return message;
+  }
+  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;
+}