@salesforce/sfdx-agent-harness-claude 0.7.0 → 0.9.0

package/dist/claude-harness.js

@@ -4,7 +4,8 @@
  */
 import { realpath } from 'node:fs/promises';
 import { RealClock, UUIDGenerator, buildSummaryPrompt, getErrorMessage, isAbortError, } from '@salesforce/agentic-common';
-import { AgentSDKError, AgentSDKErrorType, HarnessBusOwner, McpServerStatus, } from '@salesforce/sfdx-agent-sdk';
+import { AgentSDKError, AgentSDKErrorType, HarnessBusOwner, lowerStreamInput, McpServerStatus, resolveToolApprovalMode, } from '@salesforce/sfdx-agent-sdk';
+import { validateMultimodalFiles } from '@salesforce/llm-gateway-sdk';
 import { deleteSession, forkSession, getSessionMessages, listSessions, query, } from '@anthropic-ai/claude-agent-sdk';
 import { ClaudeEventAdapter, mapSessionMessageContent } from './claude-event-adapter.js';
 import { ClaudeStreamBroker } from './claude-stream-broker.js';
@@ -20,6 +21,18 @@ import { DiskBackedSessionStore } from './disk-backed-session-store.js';
 import { ThreadContextStore } from './thread-context-store.js';
 import { teeTextStream } from './text-stream.js';
 import { MAX_TRANSCRIPT_CHARS, partToTranscriptText, splitIntoChunks } from './transcript.js';
+/**
+ * Returns a shallow copy of `m` with `content` normalized: any `MessagePart[]`
+ * is reduced to a compact placeholder string via {@link partToTranscriptText} so
+ * raw base64 blobs never land in the sidecar JSON. All three
+ * `threadContextStore.write` call sites route through this helper.
+ */
+function normalizeMessageForSidecar(m) {
+    return {
+        ...m,
+        content: typeof m.content === 'string' ? m.content : m.content.map((p) => partToTranscriptText(p)).join(' '),
+    };
+}
 export class ClaudeHarness {
     envBuilder;
     optionsBuilder;
@@ -209,8 +222,8 @@ export class ClaudeHarness {
             projectRoot: resolvedProjectRoot,
             config,
             rulesAppend,
+            model: llmGatewayClient.getModel(),
             skillMap,
-            modelId: llmGatewayClient.getModel().name,
             threads,
             mcpServers,
         });
@@ -473,8 +486,8 @@ export class ClaudeHarness {
         if (source.contextHistory.length === 0 && source.pendingContext.length === 0)
             return;
         await this.threadContextStore.write(projectRoot, threadId, {
-            contextHistory: [...source.contextHistory],
-            pendingContext: [...source.pendingContext],
+            contextHistory: source.contextHistory.map(normalizeMessageForSidecar),
+            pendingContext: source.pendingContext.map(normalizeMessageForSidecar),
         });
     }
     /**
@@ -568,6 +581,21 @@ export class ClaudeHarness {
                 ?.warn(`Best-effort destroyThread failed during compactThread for thread "${threadId}" on agent "${agentId}": ${getErrorMessage(err)}`, { agentId, threadId }, err instanceof Error ? err : new Error(String(err)));
         }
     }
+    /**
+     * Pattern of upstream-Bedrock SSE-truncation strings the gateway
+     * occasionally surfaces as the assistant's `result.result` text instead
+     * of throwing. Observed empirically against the Salesforce LLM Gateway's
+     * Bedrock-Claude path: the same string also surfaces as a late-throw on
+     * the chat-stream path (see PR #424). When `summarize()` sees this
+     * pattern in the result body it retries instead of returning the error
+     * string verbatim as the "summary."
+     *
+     * Temporary workaround for an upstream LLM Gateway regression (#396 /
+     * #453 / #479). Remove together with the `stream()` post-finish
+     * swallow once the gateway team confirms the trailing-JSON shape is
+     * fixed end-to-end — cleanup tracked by #474.
+     */
+    static UPSTREAM_TRUNCATION_PATTERN = /API Error: Truncated event message received\.?/i;
     /**
      * Issue a single non-agentic model call (`maxTurns: 1`) for one-shot
      * summarization. Used internally by `compactThread()`; not part of the
@@ -578,12 +606,20 @@ export class ClaudeHarness {
      *     don't want the summary call leaking into the harness store.
      *   - no MCP servers, no consumer tools, no rules append, no
      *     `canUseTool` broker — the task is text-in / text-out.
+     *
+     * Retries up to 2 times on the upstream Bedrock SSE-truncation pattern
+     * (see {@link UPSTREAM_TRUNCATION_PATTERN}). The Salesforce LLM Gateway's
+     * Bedrock-Claude path occasionally returns a successful `result` whose
+     * body is the upstream truncation error string rather than a real
+     * summary; without retry the harness would happily seed the new thread
+     * with that error string. Each retry uses a fresh ephemeral session id
+     * and fresh `query()` invocation.
      */
     async summarize(agent, prompt) {
         if (!agent.config.orgJwt) {
             throw new Error('Agent has no orgJwt configured');
         }
-        const { env, nativeModelId } = await this.envBuilder.build(agent.config.orgJwt, agent.modelId);
+        const { env, nativeModelId } = await this.envBuilder.build(agent.config.orgJwt, agent.model.name);
         const summaryConfig = {
             orgJwt: agent.config.orgJwt,
             // The role declaration + summarization imperative + the
@@ -598,34 +634,58 @@ export class ClaudeHarness {
                 'Preserve numeric values, dates, and proper names verbatim. ' +
                 'Do not invent details that are not present in the transcript.',
         };
-        const options = this.optionsBuilder.build(agent.projectRoot, summaryConfig, { maxSteps: 1 }, env, undefined, nativeModelId, undefined, undefined, undefined);
-        // Override post-build: ephemeral session, no persistence, no
-        // sessionStore (rejected together with persistSession:false).
-        options.persistSession = false;
-        delete options.sessionStore;
-        delete options.resume;
-        delete options.sessionId;
-        const summaryQuery = query({ prompt, options: options });
-        let resultText;
-        try {
-            for await (const msg of summaryQuery) {
-                if (msg.type === 'result' && msg.subtype === 'success') {
-                    resultText = msg.result;
+        const buildOptions = () => {
+            const options = this.optionsBuilder.build(agent.projectRoot, summaryConfig, { maxSteps: 1 }, env, undefined, nativeModelId, undefined, undefined, undefined);
+            // Override post-build: ephemeral session, no persistence, no
+            // sessionStore (rejected together with persistSession:false).
+            options.persistSession = false;
+            delete options.sessionStore;
+            delete options.resume;
+            delete options.sessionId;
+            return options;
+        };
+        const MAX_ATTEMPTS = 3;
+        let lastFailureReason;
+        for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+            const summaryQuery = query({ prompt, options: buildOptions() });
+            let resultText;
+            let upstreamThrow;
+            try {
+                for await (const msg of summaryQuery) {
+                    if (msg.type === 'result' && msg.subtype === 'success') {
+                        resultText = msg.result;
+                    }
                 }
             }
-        }
-        finally {
-            try {
-                summaryQuery.close?.();
+            catch (err) {
+                upstreamThrow = err;
             }
-            catch {
-                /* iterator already closed */
+            finally {
+                try {
+                    summaryQuery.close?.();
+                }
+                catch {
+                    /* iterator already closed */
+                }
             }
+            const truncatedThrow = upstreamThrow !== undefined &&
+                ClaudeHarness.UPSTREAM_TRUNCATION_PATTERN.test(getErrorMessage(upstreamThrow));
+            const truncatedBody = resultText !== undefined && ClaudeHarness.UPSTREAM_TRUNCATION_PATTERN.test(resultText);
+            if (truncatedThrow || truncatedBody) {
+                lastFailureReason = truncatedThrow
+                    ? getErrorMessage(upstreamThrow)
+                    : `result body was upstream truncation: ${resultText}`;
+                continue;
+            }
+            if (upstreamThrow !== undefined) {
+                throw upstreamThrow;
+            }
+            if (!resultText || resultText.length === 0) {
+                throw new Error('Summary call produced no result text');
+            }
+            return resultText;
         }
-        if (!resultText || resultText.length === 0) {
-            throw new Error('Summary call produced no result text');
-        }
-        return resultText;
+        throw new Error(`Summary call hit upstream Bedrock SSE truncation on all ${MAX_ATTEMPTS} attempts. Last failure: ${lastFailureReason}`);
     }
     /**
      * Two-pass summarization for transcripts above the char budget. The
@@ -644,32 +704,94 @@ export class ClaudeHarness {
             ? this.summarize(agent, buildSummaryPrompt(merged))
             : this.summarizeInChunks(agent, merged);
     }
+    /**
+     * Validates a `MessagePart[]` and lowers it to a single-message `AsyncIterable<SDKUserMessage>`
+     * carrying Anthropic content blocks (`text`, `image`, `document`).
+     *
+     * Pre-stream validation and the input-part guard live in the SDK's {@link lowerStreamInput}:
+     * `image` / `file` parts are validated against the agent's gateway `Model.supportedFormats` and
+     * the global gateway caps via the shared `validateMultimodalFiles`, so a file is accepted or
+     * rejected identically on the Claude and Mastra paths (we deliberately mirror the SDK's
+     * conservative caps even though the underlying Bedrock models may accept more), and a
+     * `reasoning` / `tool-call` / `tool-result` part rejects with `INVALID_MESSAGE_CONTENT`. This
+     * method only supplies the Anthropic-specific lowering of each part.
+     *
+     * Validation and block construction run synchronously (the returned generator only yields the
+     * pre-built message) so failures reject the caller's `stream()` promise before any query starts.
+     */
+    buildMultimodalPrompt(agentState, parts) {
+        const content = lowerStreamInput(parts, (files) => validateMultimodalFiles(files, agentState.model), (part) => {
+            switch (part.type) {
+                case 'text':
+                    return { type: 'text', text: part.text };
+                case 'image':
+                    return {
+                        type: 'image',
+                        source: { type: 'base64', media_type: part.mimeType, data: part.data },
+                    };
+                case 'file':
+                    return {
+                        type: 'document',
+                        source: { type: 'base64', media_type: part.mimeType, data: part.data },
+                        ...(part.fileName !== undefined ? { title: part.fileName } : {}),
+                    };
+            }
+        });
+        const userMessage = {
+            type: 'user',
+            parent_tool_use_id: null,
+            message: { role: 'user', content },
+        };
+        return (async function* () {
+            yield userMessage;
+        })();
+    }
     async stream(agentId, threadId, message, streamOptions) {
         const agentState = this.agents.get(agentId);
         if (!agentState) {
             throw new Error(`Agent "${agentId}" not found`);
         }
-        const { projectRoot, config, rulesAppend, modelId } = agentState;
+        const { projectRoot, config, rulesAppend, model } = agentState;
         const threadState = agentState.threads.get(threadId);
         if (!config.orgJwt) {
             throw new Error(`Agent "${agentId}" has no orgJwt configured`);
         }
-        const { env, nativeModelId } = await this.envBuilder.build(config.orgJwt, modelId);
+        // Build (and pre-stream-validate) the query prompt. A plain string passes through; a
+        // MessagePart[] is validated against the model's capabilities and lowered to a single
+        // Anthropic user message carrying text / image / document content blocks. Validation runs
+        // synchronously here so failures reject the `stream()` promise (pre-stream contract) rather
+        // than surfacing mid-iteration.
+        const prompt = typeof message === 'string' ? message : this.buildMultimodalPrompt(agentState, message);
+        const { env, nativeModelId } = await this.envBuilder.build(config.orgJwt, model.name);
         const sessionOptions = threadState?.hasStreamed ? { resume: threadId } : { sessionId: threadId };
         const pendingContext = threadState?.pendingContext ?? [];
         const contextConfig = pendingContext.length > 0
             ? { ...config, instructions: this.buildContextPrompt(config.instructions, pendingContext) }
             : config;
-        const adapter = new ClaudeEventAdapter(this.buses.getLogBus());
+        // Closure over `agentState.mcpServers` so the adapter and broker can
+        // enrich `tool-call` / `tool-result` / `tool-approval-request` events
+        // with `serverName` + `annotations` for MCP-bridged tools (#466).
+        // Non-MCP tools (built-ins like `Bash`, the in-process
+        // `consumer_tools` / `skill_bridge` servers) return undefined and the
+        // events stay un-enriched, matching Mastra's shape on the same paths.
+        const lookup = (toolName) => lookupMcpToolMetadata(agentState.mcpServers, toolName);
+        const adapter = new ClaudeEventAdapter(this.buses.getLogBus(), lookup);
         const controller = new AbortController();
+        // Resolve `requireToolApproval` to its canonical mode (#447):
+        // `undefined` (no gating), `'serial'`, or `'batch'`. The broker
+        // is allocated for both gating modes; only the emission shape
+        // differs.
+        const approvalMode = resolveToolApprovalMode(streamOptions?.requireToolApproval);
         let broker;
-        if (streamOptions?.requireToolApproval) {
+        if (approvalMode !== undefined) {
             const key = this.brokerKey(agentId, threadId);
             this.brokers.get(key)?.dispose();
             broker = new ClaudeStreamBroker({
                 adapter,
                 toolApprovalTimeoutMs: this.toolApprovalTimeoutMs,
                 abortController: controller,
+                lookupMcpToolMetadata: lookup,
+                mode: approvalMode,
             });
             this.brokers.set(key, broker);
         }
@@ -682,7 +804,7 @@ export class ClaudeHarness {
         const consumerTools = config.tools ?? [];
         let consumerToolBroker;
         let consumerToolsBridge;
-        if (!streamOptions?.requireToolApproval && consumerTools.length > 0) {
+        if (approvalMode === undefined && consumerTools.length > 0) {
             const key = this.brokerKey(agentId, threadId);
             this.consumerToolBrokers.get(key)?.dispose();
             consumerToolBroker = new ConsumerToolBroker(CONSUMER_TOOLS_BRIDGE_SERVER_NAME);
@@ -694,7 +816,7 @@ export class ClaudeHarness {
         // set; the bridge is plumbing the Claude subprocess uses to reach
         // those clients via in-process JSON-RPC.
         const bridgeConfigs = this.buildBridgeConfigsForStream(agentState, consumerToolsBridge);
-        const options = this.optionsBuilder.build(projectRoot, contextConfig, streamOptions, env, sessionOptions, nativeModelId, broker?.canUseTool, bridgeConfigs, rulesAppend.length > 0 ? rulesAppend : undefined);
+        const options = this.optionsBuilder.build(projectRoot, contextConfig, streamOptions, env, sessionOptions, nativeModelId, broker?.preToolUseHook, bridgeConfigs, rulesAppend.length > 0 ? rulesAppend : undefined);
         options.abortController = controller;
         // Mirror subprocess writes into the harness-owned store. With this
         // set, the host-side `getSessionMessages` / `deleteSession` calls
@@ -704,11 +826,28 @@ export class ClaudeHarness {
         options.sessionStore = this.sessionStore;
         if (streamOptions?.abortSignal) {
             streamOptions.abortSignal.throwIfAborted();
-            streamOptions.abortSignal.addEventListener('abort', () => {
+            const onAbort = () => {
                 controller.abort();
                 broker?.abort();
                 consumerToolBroker?.abort();
-            }, { once: true });
+            };
+            const abortSignal = streamOptions.abortSignal;
+            abortSignal.addEventListener('abort', onAbort);
+            // Detach the listener at the per-stream controller's abort
+            // event. The harness aborts `controller` from end-of-stream
+            // paths (the eventStream generator's `finally`, broker
+            // dispose's `abortController.abort()`, consumer-tool broker's
+            // abort, the inbound abort listener above), so this fires
+            // exactly once per stream — natural completion, error, or
+            // forwarded abort. Without this, a long-lived consumer
+            // AbortController (session-scoped, app-scoped) would
+            // accumulate one listener per turn even when the turn never
+            // aborts. Tying cleanup to `controller.signal` instead of
+            // `broker?.onTeardown()` covers the no-broker path (most
+            // turns) too.
+            controller.signal.addEventListener('abort', () => abortSignal.removeEventListener('abort', onAbort), {
+                once: true,
+            });
         }
         if (threadState && pendingContext.length > 0) {
             threadState.pendingContext = [];
@@ -716,12 +855,13 @@ export class ClaudeHarness {
             // stream and the next addContext doesn't re-inject the
             // already-consumed pendingContext into the model's
             // systemPrompt. contextHistory persists unchanged.
+            // Normalize to placeholders so raw base64 never lands on disk.
             await this.threadContextStore.write(projectRoot, threadId, {
-                pendingContext: threadState.pendingContext,
-                contextHistory: threadState.contextHistory,
+                pendingContext: [],
+                contextHistory: threadState.contextHistory.map(normalizeMessageForSidecar),
             });
         }
-        const queryResult = query({ prompt: message, options });
+        const queryResult = query({ prompt, options });
         if (threadState) {
             threadState.hasStreamed = true;
         }
@@ -760,17 +900,38 @@ export class ClaudeHarness {
             return teeTextStream(consumerToolBroker.initialSink().generator());
         }
         const logBus = this.buses.getLogBus();
+        // Snapshot here so the catch block can distinguish a
+        // consumer-forwarded abort (signal aborted before the iterator
+        // threw) from "iterator threw normally and the finally aborted
+        // `controller` for listener cleanup." Without this, the natural
+        // error path would mis-classify as abort once the finally runs.
+        const consumerAbortSignal = streamOptions?.abortSignal;
         async function* eventStream() {
             let terminalEmitted = false;
             try {
-                for await (const msg of queryResult) {
-                    for (const event of adapter.mapMessage(msg)) {
-                        if (event.type === 'finish') {
-                            terminalEmitted = true;
+                try {
+                    for await (const msg of queryResult) {
+                        for (const event of adapter.mapMessage(msg)) {
+                            if (event.type === 'finish') {
+                                terminalEmitted = true;
+                            }
+                            yield event;
                         }
-                        yield event;
                     }
                 }
+                finally {
+                    // Abort the per-stream controller on every exit path
+                    // (natural completion, iterator throw, consumer
+                    // `return()` from a `break`). The abort fires the
+                    // `controller.signal` listeners we register above
+                    // (consumer-AbortSignal listener detach, broker
+                    // teardown), so a turn that never explicitly aborts
+                    // still releases its inbound listener. Idempotent —
+                    // the inbound abort listener already aborted
+                    // `controller` when applicable.
+                    if (!controller.signal.aborted)
+                        controller.abort();
+                }
             }
             catch (err) {
                 // The Salesforce LLM Gateway's Bedrock-Claude path
@@ -798,13 +959,20 @@ export class ClaudeHarness {
                     });
                     return;
                 }
-                if (controller.signal.aborted) {
+                if (consumerAbortSignal?.aborted) {
                     // When the consumer-supplied AbortSignal fires, the
                     // harness forwards it onto its local controller and the
                     // Claude SDK iterator throws whatever it throws (varies
                     // by upstream version). Normalize to the SDK's
                     // documented abort contract: AbortError-named Error +
                     // `code: 'abort'`. Matches the Mastra harness convention.
+                    //
+                    // We check the CONSUMER's signal here, not
+                    // `controller.signal` — the per-stream controller is
+                    // also aborted from the generator's `finally` for
+                    // listener cleanup on natural error paths, so checking
+                    // it would mis-classify regular iterator failures as
+                    // aborts.
                     yield {
                         type: 'error',
                         error: new DOMException('The stream was aborted.', 'AbortError'),
@@ -848,8 +1016,8 @@ export class ClaudeHarness {
         for (const [name, state] of agent.mcpServers) {
             if (state.currentStatus !== McpServerStatus.Connected)
                 continue;
-            const timeout = agent.config.mcpServers?.[name]?.timeout;
-            out[name] = buildBridgeForServer(name, state.client, state.tools, timeout);
+            const serverConfig = agent.config.mcpServers?.[name];
+            out[name] = buildBridgeForServer(name, state.client, state.tools, serverConfig?.timeout, serverConfig?.alwaysLoad);
         }
         if (consumerToolsBridge) {
             out[CONSUMER_TOOLS_BRIDGE_SERVER_NAME] = consumerToolsBridge;
@@ -870,7 +1038,16 @@ export class ClaudeHarness {
      * fresh continuation sink returned here.
      */
     async submitToolResult(agentId, threadId, toolResult) {
-        const broker = this.consumerToolBrokers.get(this.brokerKey(agentId, threadId));
+        const key = this.brokerKey(agentId, threadId);
+        // A `ClaudeStreamBroker` only exists when the originating turn was
+        // approval-gated. The broker has no path to settle a
+        // consumer-executed tool result (its decision shape is
+        // approve/decline only), so refuse with cross-harness-parity
+        // guidance — Mastra's submitToolResult emits the same shape.
+        if (this.brokers.has(key)) {
+            throw new Error(`ClaudeHarness.submitToolResult(): thread "${threadId}" on agent "${agentId}" is in approval-gated mode; settle pending approvals via approveToolCall / declineToolCall first`);
+        }
+        const broker = this.consumerToolBrokers.get(key);
         if (!broker) {
             throw new Error(`ClaudeHarness.submitToolResult(): no active consumer-tool stream for thread "${threadId}" on agent "${agentId}"`);
         }
@@ -916,6 +1093,9 @@ export class ClaudeHarness {
         // `pendingContext` → systemPrompt path on the next stream. Order is
         // injection-order followed by persisted-transcript-order, matching
         // the Mastra harness shape.
+        // Consumer-visible content round-trips unchanged: contextHistory entries
+        // are returned exactly as passed to addContext(), including any raw base64
+        // in image/file parts. Only the sidecar-persisted copy is normalized (see addContext()).
         const contextHistory = threadState?.contextHistory ?? [];
         return contextHistory.length === 0 ? persisted : [...contextHistory, ...persisted];
     }
@@ -940,7 +1120,7 @@ export class ClaudeHarness {
     }
     buildContextPrompt(baseInstructions, messages) {
         const contextBlock = messages
-            .map((m) => `[${m.role}]: ${typeof m.content === 'string' ? m.content : JSON.stringify(m.content)}`)
+            .map((m) => `[${m.role}]: ${typeof m.content === 'string' ? m.content : m.content.map((p) => partToTranscriptText(p)).join(' ')}`)
             .join('\n');
         const prefix = baseInstructions ? `${baseInstructions}\n\n` : '';
         return `${prefix}<prior-context>\n${contextBlock}\n</prior-context>`;
@@ -967,9 +1147,12 @@ export class ClaudeHarness {
         // path (`memory.saveMessages`) propagates libsql failures, and
         // silently masking a write failure here would recreate the very
         // cross-restart drop the sidecar exists to prevent.
+        // Normalize MessagePart[] content to placeholder text before writing so
+        // raw base64 blobs never land in the sidecar JSON (same pattern as
+        // compactThread's transcript builder).
         await this.threadContextStore.write(agent.projectRoot, threadId, {
-            pendingContext: threadState.pendingContext,
-            contextHistory: threadState.contextHistory,
+            pendingContext: threadState.pendingContext.map(normalizeMessageForSidecar),
+            contextHistory: threadState.contextHistory.map(normalizeMessageForSidecar),
         });
     }
     /**
@@ -1107,6 +1290,51 @@ export class ClaudeHarness {
 function isDisposedError(err) {
     return err instanceof AgentSDKError && err.type === AgentSDKErrorType.DISPOSED;
 }
+/**
+ * Resolve the originating MCP server name and (optional) annotations for a
+ * Claude-namespaced tool name (`mcp__<server>__<tool>`). Returns `undefined`
+ * for tools that aren't in any MCP server's catalog (built-ins like `Bash`,
+ * the in-process `consumer_tools` / `skill_bridge` SDK MCP servers, or any
+ * tool name that doesn't carry the `mcp__` prefix).
+ *
+ * Selects the **longest matching prefix whose catalog actually contains the
+ * tool**. The `__` separator makes single-underscore prefix collisions
+ * impossible (`mcp__foo__` is not a prefix of `mcp__foo_extra__`), but a
+ * server name that itself contains `__` does collide with a shorter sibling:
+ * `mcp__foo__bar__baz` could come from server `foo` + tool `bar__baz` or
+ * from server `foo__bar` + tool `baz`. The existence check on the
+ * candidate's `tools` array picks the server that actually catalogs the
+ * tool; the longest-prefix tiebreak handles the rarer case where both
+ * legitimately catalog a tool that resolves to the same fully-namespaced
+ * name.
+ *
+ * Mirrors `lookupMcpToolMetadata` in the Mastra harness so the cross-harness
+ * `serverName` / `annotations` enrichment contract has identical observable
+ * behavior on both harnesses.
+ */
+function lookupMcpToolMetadata(mcpServers, namespacedToolName) {
+    if (!namespacedToolName.startsWith('mcp__'))
+        return undefined;
+    let best;
+    for (const [serverName, state] of mcpServers) {
+        const prefix = `mcp__${serverName}__`;
+        if (!namespacedToolName.startsWith(prefix))
+            continue;
+        const bareName = namespacedToolName.slice(prefix.length);
+        const tool = state.tools.find((t) => t.name === bareName);
+        if (!tool)
+            continue;
+        if (!best || serverName.length > best.serverName.length) {
+            best = { serverName, tool };
+        }
+    }
+    if (!best)
+        return undefined;
+    return {
+        serverName: best.serverName,
+        ...(best.tool.annotations ? { annotations: best.tool.annotations } : {}),
+    };
+}
 /**
  * Race a promise against an `AbortSignal` so a wedged operation (e.g. a
  * stuck stdio MCP child during `connect()` or `listTools()`) cannot block
@@ -1195,7 +1423,11 @@ function projectMcpServerStateToInfo(name, state) {
     }
 }
 function mapToolToInfo(serverName, tool) {
-    const info = { name: `mcp__${serverName}__${tool.name}` };
+    const info = {
+        name: `mcp__${serverName}__${tool.name}`,
+        serverName,
+        toolName: tool.name,
+    };
     if (tool.description !== undefined && tool.description !== '') {
         info.description = tool.description;
     }