fix(agents): normalize malformed tool results in adapter (#27007)

src/agents/pi-tool-definition-adapter.test.ts

@@ -25,6 +25,15 @@ async function executeThrowingTool(name: string, callId: string) {
   return await def.execute(callId, {}, undefined, undefined, extensionContext);
 }
 
+async function executeTool(tool: AgentTool, callId: string) {
+  const defs = toToolDefinitions([tool]);
+  const def = defs[0];
+  if (!def) {
+    throw new Error("missing tool definition");
+  }
+  return await def.execute(callId, {}, undefined, undefined, extensionContext);
+}
+
 describe("pi tool definition adapter", () => {
   it("wraps tool errors into a tool result", async () => {
     const result = await executeThrowingTool("boom", "call1");
@@ -46,4 +55,46 @@ describe("pi tool definition adapter", () => {
       error: "nope",
     });
   });
+
+  it("coerces details-only tool results to include content", async () => {
+    const tool = {
+      name: "memory_query",
+      label: "Memory Query",
+      description: "returns details only",
+      parameters: Type.Object({}),
+      execute: (async () => ({
+        details: {
+          hits: [{ id: "a1", score: 0.9 }],
+        },
+      })) as unknown as AgentTool["execute"],
+    } satisfies AgentTool;
+
+    const result = await executeTool(tool, "call3");
+    expect(result.details).toEqual({
+      hits: [{ id: "a1", score: 0.9 }],
+    });
+    expect(result.content[0]).toMatchObject({ type: "text" });
+    expect((result.content[0] as { text?: string }).text).toContain('"hits"');
+  });
+
+  it("coerces non-standard object results to include content", async () => {
+    const tool = {
+      name: "memory_query_raw",
+      label: "Memory Query Raw",
+      description: "returns plain object",
+      parameters: Type.Object({}),
+      execute: (async () => ({
+        count: 2,
+        ids: ["m1", "m2"],
+      })) as unknown as AgentTool["execute"],
+    } satisfies AgentTool;
+
+    const result = await executeTool(tool, "call4");
+    expect(result.details).toEqual({
+      count: 2,
+      ids: ["m1", "m2"],
+    });
+    expect(result.content[0]).toMatchObject({ type: "text" });
+    expect((result.content[0] as { text?: string }).text).toContain('"count"');
+  });
 });

src/agents/pi-tool-definition-adapter.ts

@@ -62,6 +62,56 @@ function describeToolExecutionError(err: unknown): {
   return { message: String(err) };
 }
 
+function stringifyToolPayload(payload: unknown): string {
+  if (typeof payload === "string") {
+    return payload;
+  }
+  try {
+    const encoded = JSON.stringify(payload, null, 2);
+    if (typeof encoded === "string") {
+      return encoded;
+    }
+  } catch {
+    // Fall through to String(payload) for non-serializable values.
+  }
+  return String(payload);
+}
+
+function normalizeToolExecutionResult(params: {
+  toolName: string;
+  result: unknown;
+}): AgentToolResult<unknown> {
+  const { toolName, result } = params;
+  if (result && typeof result === "object") {
+    const record = result as Record<string, unknown>;
+    if (Array.isArray(record.content)) {
+      return result as AgentToolResult<unknown>;
+    }
+    logDebug(`tools: ${toolName} returned non-standard result (missing content[]); coercing`);
+    const details = "details" in record ? record.details : record;
+    const safeDetails = details ?? { status: "ok", tool: toolName };
+    return {
+      content: [
+        {
+          type: "text",
+          text: stringifyToolPayload(safeDetails),
+        },
+      ],
+      details: safeDetails,
+    };
+  }
+  const safeDetails = result ?? { status: "ok", tool: toolName };
+  return {
+    content: [
+      {
+        type: "text",
+        text: stringifyToolPayload(safeDetails),
+      },
+    ],
+    details: safeDetails,
+  };
+}
+
 function splitToolExecuteArgs(args: ToolExecuteArgsAny): {
   toolCallId: string;
   params: unknown;
@@ -111,7 +161,11 @@ export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] {
             }
             executeParams = hookOutcome.params;
           }
-          const result = await tool.execute(toolCallId, executeParams, signal, onUpdate);
+          const rawResult = await tool.execute(toolCallId, executeParams, signal, onUpdate);
+          const result = normalizeToolExecutionResult({
+            toolName: normalizedName,
+            result: rawResult,
+          });
           const afterParams = beforeHookWrapped
             ? (consumeAdjustedParamsForToolCall(toolCallId) ?? executeParams)
             : executeParams;