feat: for agent, add structured tool-result runtime and tool-calling …

src/agent/__tests__/tool-result-policy.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "bun:test";
+
+import { getToolResultPolicy } from "../tool-result-policy";
+
+describe("getToolResultPolicy", () => {
+  test("returns summary-first policy for search and filesystem inspection tools", () => {
+    expect(getToolResultPolicy("list_files")).toEqual({
+      preferSummaryOnly: true,
+      includeData: false,
+      maxStringLength: 1000,
+      uiSummaryOnly: true,
+    });
+  });
+
+  test("returns data-carrying policy for read_file", () => {
+    expect(getToolResultPolicy("read_file")).toMatchObject({
+      preferSummaryOnly: false,
+      includeData: true,
+      maxStringLength: 12000,
+    });
+  });
+
+  test("returns default policy for unknown tools", () => {
+    expect(getToolResultPolicy("unknown_tool")).toMatchObject({
+      preferSummaryOnly: false,
+      includeData: true,
+      maxStringLength: 4000,
+    });
+  });
+});

src/agent/__tests__/tool-result-runtime.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, test } from "bun:test";
+
+import { formatToolResultForMessage, inferToolErrorKind, normalizeToolResult } from "../tool-result-runtime";
+
+describe("inferToolErrorKind", () => {
+  test("maps common tool error code families", () => {
+    expect(inferToolErrorKind("INVALID_PATH")).toBe("invalid_input");
+    expect(inferToolErrorKind("DELETE_NOT_SUPPORTED")).toBe("unsupported");
+    expect(inferToolErrorKind("FILE_NOT_FOUND")).toBe("not_found");
+    expect(inferToolErrorKind("RG_NOT_FOUND")).toBe("environment_missing");
+    expect(inferToolErrorKind("PATCH_APPLY_FAILED")).toBe("execution_failed");
+  });
+});
+
+describe("normalizeToolResult", () => {
+  test("preserves structured success results", () => {
+    const result = normalizeToolResult({
+      ok: true,
+      summary: "Read file: /tmp/demo.ts",
+      data: { path: "/tmp/demo.ts", content: "const x = 1;" },
+    });
+
+    expect(result).toMatchObject({
+      ok: true,
+      summary: "Read file: /tmp/demo.ts",
+      data: { path: "/tmp/demo.ts", content: "const x = 1;" },
+    });
+  });
+
+  test("preserves structured errors and infers error kind", () => {
+    const result = normalizeToolResult({
+      ok: false,
+      summary: "File not found",
+      error: "File not found",
+      code: "FILE_NOT_FOUND",
+    });
+
+    expect(result).toMatchObject({
+      ok: false,
+      summary: "File not found",
+      error: "File not found",
+      code: "FILE_NOT_FOUND",
+      errorKind: "not_found",
+    });
+  });
+
+  test("normalizes legacy string errors", () => {
+    const result = normalizeToolResult("Error: something failed");
+    expect(result).toMatchObject({
+      ok: false,
+      summary: "something failed",
+      error: "something failed",
+    });
+  });
+
+  test("normalizes plain success strings", () => {
+    const result = normalizeToolResult("done");
+    expect(result).toMatchObject({
+      ok: true,
+      summary: "done",
+      data: "done",
+    });
+  });
+});
+
+describe("formatToolResultForMessage", () => {
+  test("omits data for summary-first tools", () => {
+    const formatted = formatToolResultForMessage({
+      toolName: "list_files",
+      result: {
+        ok: true,
+        summary: "Listed 5 entries under /tmp/demo",
+        data: { entries: ["a", "b"] },
+      },
+    });
+
+    expect(JSON.parse(formatted)).toEqual({
+      ok: true,
+      summary: "Listed 5 entries under /tmp/demo",
+    });
+  });
+
+  test("preserves data for content-carrying tools", () => {
+    const formatted = formatToolResultForMessage({
+      toolName: "read_file",
+      result: {
+        ok: true,
+        summary: "Read file: /tmp/demo.ts",
+        data: { path: "/tmp/demo.ts", content: "const x = 1;" },
+      },
+    });
+
+    expect(JSON.parse(formatted)).toEqual({
+      ok: true,
+      summary: "Read file: /tmp/demo.ts",
+      data: { path: "/tmp/demo.ts", content: "const x = 1;" },
+    });
+  });
+
+  test("passes through raw read_file text results", () => {
+    const content = ["1: const x = 1;", "2: const y = 2;"].join("\n");
+    const formatted = formatToolResultForMessage({
+      toolName: "read_file",
+      result: content,
+    });
+
+    expect(formatted).toBe(content);
+  });
+
+  test("passes through read_file text that starts with Error: verbatim", () => {
+    const content = "Error: this line is part of the file";
+    const formatted = formatToolResultForMessage({
+      toolName: "read_file",
+      result: content,
+    });
+
+    expect(formatted).toBe(content);
+  });
+
+  test("formats errors with stable structured shape", () => {
+    const formatted = formatToolResultForMessage({
+      toolName: "grep_search",
+      result: {
+        ok: false,
+        summary: "Failed to run rg",
+        error: "Failed to run rg",
+        code: "RG_NOT_FOUND",
+      },
+    });
+
+    expect(JSON.parse(formatted)).toEqual({
+      ok: false,
+      summary: "Failed to run rg",
+      error: "Failed to run rg",
+      code: "RG_NOT_FOUND",
+    });
+  });
+
+  test("always returns valid json when payload exceeds limits", () => {
+    const formatted = formatToolResultForMessage({
+      toolName: "apply_patch",
+      result: {
+        ok: true,
+        summary: "Applied patch",
+        data: { patch: "x".repeat(10000) },
+      },
+    });
+
+    expect(() => JSON.parse(formatted)).not.toThrow();
+    expect(JSON.parse(formatted)).toEqual({
+      ok: true,
+      summary: "Applied patch",
+    });
+  });
+});

src/agent/agent.ts

@@ -12,6 +12,7 @@ import type {
 import type { AgentEvent } from "./agent-event";
 import type { AgentMiddleware } from "./agent-middleware";
 import type { SkillFrontmatter } from "./skills/types";
+import { formatToolResultForMessage } from "./tool-result-runtime";
 
 /**
  * A context that is used to invoke a React agent.
@@ -226,14 +227,14 @@ export class Agent {
         if (!tool) throw new Error(`Tool ${toolUse.name} not found`);
         const beforeResult = await this._beforeToolUse(toolUse);
         if (beforeResult.skip) {
-          return { index, toolUseId: toolUse.id, result: beforeResult.result };
+          return { index, toolUseId: toolUse.id, toolName: toolUse.name, result: beforeResult.result };
         }
         const result = await tool.invoke(toolUse.input, signal);
         await this._afterToolUse(toolUse, result);
-        return { index, toolUseId: toolUse.id, result };
+        return { index, toolUseId: toolUse.id, toolName: toolUse.name, result };
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return { index, toolUseId: toolUse.id, result: `Error: ${message}` };
+        return { index, toolUseId: toolUse.id, toolName: toolUse.name, result: `Error: ${message}` };
       }
     });
 
@@ -261,7 +262,7 @@ export class Agent {
           {
             type: "tool_result",
             tool_use_id: resolved.toolUseId,
-            content: stringifyToolResult(resolved.result),
+            content: formatToolResultForMessage({ toolName: resolved.toolName, result: resolved.result }),
           },
         ],
       };
@@ -359,9 +360,3 @@ export class Agent {
   }
 }
 
-function stringifyToolResult(result: unknown): string {
-  if (result === undefined) return "undefined";
-  if (result === null) return "null";
-  if (typeof result === "object") return JSON.stringify(result);
-  return String(result);
-}

src/agent/tool-result-policy.ts

@@ -0,0 +1,45 @@
+export type ToolResultPolicy = {
+  preferSummaryOnly: boolean;
+  includeData: boolean;
+  maxStringLength?: number;
+  uiSummaryOnly?: boolean;
+};
+
+const DEFAULT_POLICY: ToolResultPolicy = {
+  preferSummaryOnly: false,
+  includeData: true,
+  maxStringLength: 4000,
+};
+
+export function getToolResultPolicy(toolName: string): ToolResultPolicy {
+  switch (toolName) {
+    case "list_files":
+    case "glob_search":
+    case "grep_search":
+    case "file_info":
+    case "mkdir":
+    case "move_path":
+      return {
+        preferSummaryOnly: true,
+        includeData: false,
+        maxStringLength: 1000,
+        uiSummaryOnly: true,
+      };
+    case "read_file":
+      return {
+        preferSummaryOnly: false,
+        includeData: true,
+        maxStringLength: 12000,
+      };
+    case "apply_patch":
+    case "write_file":
+    case "str_replace":
+      return {
+        preferSummaryOnly: false,
+        includeData: true,
+        maxStringLength: 4000,
+      };
+    default:
+      return DEFAULT_POLICY;
+  }
+}