fix(agents): trim whitespace from LLM tool call names to prevent lookup failures

SidQin-cyber · SidQin-cyber · commit 5bc6e02698b0 · 2026-02-26T15:45:55.000+08:00
Some models return tool call names with leading/trailing whitespace (e.g. " read " instead of "read"). The agent loop in pi-agent-core uses an exact-match lookup (`tools.find(t => t.name === toolCall.name)`) which fails on these names, producing "Tool not found" errors. Wrap the stream function to intercept response events and trim toolCall content block names in-place before they reach the agent loop's tool dispatch. Closes #27045
diff --git a/src/agents/pi-embedded-runner/run/attempt.ts b/src/agents/pi-embedded-runner/run/attempt.ts
@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import os from "node:os";
-import type { AgentMessage } from "@mariozechner/pi-agent-core";
+import type { AgentMessage, StreamFn } from "@mariozechner/pi-agent-core";
 import type { ImageContent } from "@mariozechner/pi-ai";
 import { streamSimple } from "@mariozechner/pi-ai";
 import {
@@ -128,6 +128,58 @@ type PromptBuildHookRunner = {
   ) => Promise<PluginHookBeforeAgentStartResult | undefined>;
 };
 
+/**
+ * Trim leading/trailing whitespace from tool call names in the LLM response
+ * stream.  Some models return tool names like " read " which causes the
+ * agent loop's exact-match lookup to fail with "Tool not found" (#27045).
+ *
+ * We intercept the async iterator to mutate toolCall content blocks in-place
+ * as they flow through.  Because the partial message objects are the same
+ * references used by the final result, the trimmed names propagate to the
+ * `done` event automatically.
+ */
+function wrapStreamFnTrimToolNames(baseFn: StreamFn): StreamFn {
+  return (model, context, options) => {
+    const stream = baseFn(model, context, options);
+    const origIterator = stream[Symbol.asyncIterator].bind(stream);
+    (stream as unknown as Record<symbol, unknown>)[Symbol.asyncIterator] = function () {
+      const iter = origIterator();
+      return {
+        async next() {
+          const result = await iter.next();
+          if (!result.done && result.value) {
+            const event = result.value as {
+              type?: string;
+              partial?: { content?: unknown[] };
+              message?: { content?: unknown[] };
+            };
+            const contents: unknown[][] = [];
+            if (event.partial?.content) contents.push(event.partial.content);
+            if (event.message?.content) contents.push(event.message.content);
+            for (const content of contents) {
+              for (const block of content) {
+                const b = block as { type?: string; name?: string };
+                if (b.type === "toolCall" && typeof b.name === "string") {
+                  const trimmed = b.name.trim();
+                  if (trimmed !== b.name) b.name = trimmed;
+                }
+              }
+            }
+          }
+          return result;
+        },
+        async return(value?: unknown) {
+          return iter.return?.(value) ?? { done: true as const, value: undefined };
+        },
+        async throw(err?: unknown) {
+          return iter.throw?.(err) ?? { done: true as const, value: undefined };
+        },
+      };
+    };
+    return stream;
+  };
+}
+
 export function injectHistoryImagesIntoMessages(
   messages: AgentMessage[],
   historyImagesByIndex: Map<number, ImageContent[]>,
@@ -823,6 +875,11 @@ export async function runEmbeddedAttempt(
         );
       }
 
+      // Normalize tool call names from LLM responses: some models return
+      // tool names with leading/trailing whitespace, causing "Tool not found"
+      // errors in the agent loop's exact-match lookup (#27045).
+      activeSession.agent.streamFn = wrapStreamFnTrimToolNames(activeSession.agent.streamFn);
+
       try {
         const prior = await sanitizeSessionHistory({
           messages: activeSession.messages,
diff --git a/src/agents/pi-tool-definition-adapter.ts b/src/agents/pi-tool-definition-adapter.ts
@@ -137,7 +137,7 @@ function splitToolExecuteArgs(args: ToolExecuteArgsAny): {
 }
 
 export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] {
-  return tools.map((tool) => {
+  const defs = tools.map((tool) => {
     const name = tool.name || "tool";
     const normalizedName = normalizeToolName(name);
     const beforeHookWrapped = isToolWrappedWithBeforeToolCallHook(tool);
@@ -240,6 +240,7 @@ export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] {
       },
     } satisfies ToolDefinition;
   });
+  return defs;
 }
 
 // Convert client tools (OpenResponses hosted tools) to ToolDefinition format

Original file line number	Diff line number	Diff line change
`@@ -137,7 +137,7 @@ function splitToolExecuteArgs(args: ToolExecuteArgsAny): {`
`137`	`137`	`}`
`138`	`138`
`139`	`139`	`export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] {`
`140`		`- return tools.map((tool) => {`
	`140`	`+ const defs = tools.map((tool) => {`
`141`	`141`	`const name = tool.name \|\| "tool";`
`142`	`142`	`const normalizedName = normalizeToolName(name);`
`143`	`143`	`const beforeHookWrapped = isToolWrappedWithBeforeToolCallHook(tool);`
`@@ -240,6 +240,7 @@ export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] {`
`240`	`240`	`},`
`241`	`241`	`} satisfies ToolDefinition;`
`242`	`242`	`});`
	`243`	`+ return defs;`
`243`	`244`	`}`
`244`	`245`
`245`	`246`	`// Convert client tools (OpenResponses hosted tools) to ToolDefinition format`