@vellumai/assistant 0.8.6 → 0.8.7-dev.202606052118.34cd356

package/src/__tests__/agent-loop.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "bun:test";
+import { beforeEach, describe, expect, test } from "bun:test";
 
 import type {
   AgentEvent,
@@ -6,87 +6,24 @@ import type {
   CheckpointInfo,
 } from "../agent/loop.js";
 import { AgentLoop } from "../agent/loop.js";
+import { resetPluginRegistryAndRegisterDefaults } from "../plugins/defaults/index.js";
 import type {
   ContentBlock,
   Message,
   Provider,
   ProviderResponse,
-  SendMessageOptions,
   ToolDefinition,
 } from "../providers/types.js";
+import {
+  createMockProvider,
+  textResponse,
+  toolUseResponse,
+} from "./helpers/mock-provider.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-/** A mock provider that returns pre-configured responses in sequence. */
-function createMockProvider(responses: ProviderResponse[]): {
-  provider: Provider;
-  calls: {
-    messages: Message[];
-    tools?: ToolDefinition[];
-    systemPrompt?: string;
-    options?: SendMessageOptions;
-  }[];
-} {
-  const calls: {
-    messages: Message[];
-    tools?: ToolDefinition[];
-    systemPrompt?: string;
-    options?: SendMessageOptions;
-  }[] = [];
-  let callIndex = 0;
-
-  const provider: Provider = {
-    name: "mock",
-    async sendMessage(
-      messages: Message[],
-      tools?: ToolDefinition[],
-      systemPrompt?: string,
-      options?: SendMessageOptions,
-    ): Promise<ProviderResponse> {
-      calls.push({ messages: [...messages], tools, systemPrompt, options });
-      const response = responses[callIndex] ?? responses[responses.length - 1];
-      callIndex++;
-
-      // Emit streaming events if the response has text blocks
-      if (options?.onEvent) {
-        for (const block of response.content) {
-          if (block.type === "text") {
-            options.onEvent({ type: "text_delta", text: block.text });
-          }
-        }
-      }
-
-      return response;
-    },
-  };
-
-  return { provider, calls };
-}
-
-function textResponse(text: string): ProviderResponse {
-  return {
-    content: [{ type: "text", text }],
-    model: "mock-model",
-    usage: { inputTokens: 10, outputTokens: 5 },
-    stopReason: "end_turn",
-  };
-}
-
-function toolUseResponse(
-  id: string,
-  name: string,
-  input: Record<string, unknown>,
-): ProviderResponse {
-  return {
-    content: [{ type: "tool_use", id, name, input }],
-    model: "mock-model",
-    usage: { inputTokens: 10, outputTokens: 5 },
-    stopReason: "tool_use",
-  };
-}
-
 const dummyTools: ToolDefinition[] = [
   {
     name: "read_file",
@@ -109,13 +46,20 @@ function collectEvents(events: AgentEvent[]): (event: AgentEvent) => void {
 // ---------------------------------------------------------------------------
 
 describe("AgentLoop", () => {
+  // The agent loop fires the `post-tool-use` hook for tool-result
+  // truncation, which only runs when the default plugin is registered.
+  // Register the defaults so the loop behaves as it does in production.
+  beforeEach(() => {
+    resetPluginRegistryAndRegisterDefaults();
+  });
+
   // 1. Basic text response
   test("returns history with assistant message for simple text response", async () => {
     const { provider } = createMockProvider([textResponse("Hi there!")]);
     const loop = new AgentLoop(provider, "system prompt");
 
     const events: AgentEvent[] = [];
-    const history = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run([userMessage], collectEvents(events));
 
     // History should contain original user message + assistant response
     expect(history).toHaveLength(2);
@@ -141,15 +85,12 @@ describe("AgentLoop", () => {
       return { content: "file data here", isError: false };
     };
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
     const events: AgentEvent[] = [];
-    const history = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run([userMessage], collectEvents(events));
 
     // Tool executor was called with correct args
     expect(toolCalls).toHaveLength(1);
@@ -193,26 +134,16 @@ describe("AgentLoop", () => {
       overrideProfile = "quality-optimized";
       return { content: "ok", isError: false };
     };
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
 
-    await loop.run(
-      [userMessage],
-      collectEvents([]),
-      undefined,
-      "req-1",
-      undefined,
-      "mainAgent",
-      undefined,
-      undefined,
-      undefined,
-      () => overrideProfile,
-    );
+    await loop.run([userMessage], collectEvents([]), {
+      requestId: "req-1",
+      callSite: "mainAgent",
+      resolveOverrideProfile: () => overrideProfile,
+    });
 
     expect(calls).toHaveLength(2);
     expect(calls[0].options?.config?.overrideProfile).toBeUndefined();
@@ -232,27 +163,19 @@ describe("AgentLoop", () => {
       maxInputTokens = 10_000;
       return { content: toolOutput, isError: false };
     };
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
 
-    await loop.run(
-      [userMessage],
-      collectEvents([]),
-      undefined,
-      "req-1",
-      undefined,
-      "mainAgent",
-      undefined,
-      undefined,
-      1_000,
-      undefined,
-      () => maxInputTokens,
-    );
+    await loop.run([userMessage], collectEvents([]), {
+      requestId: "req-1",
+      callSite: "mainAgent",
+      resolveContextWindow: () => ({
+        maxInputTokens,
+        overflowRecovery: { enabled: false, safetyMarginRatio: 0 },
+      }),
+    });
 
     const secondCallMessages = calls[1].messages;
     const lastMsg = secondCallMessages[secondCallMessages.length - 1];
@@ -281,14 +204,11 @@ describe("AgentLoop", () => {
       };
     };
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
-    const history = await loop.run([userMessage], () => {});
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
+    const { history } = await loop.run([userMessage], () => {});
 
     // Provider called 3 times (two tool rounds + final text)
     expect(calls).toHaveLength(3);
@@ -307,8 +227,8 @@ describe("AgentLoop", () => {
     ]);
 
     // No tool executor provided
-    const loop = new AgentLoop(provider, "system", {}, dummyTools);
-    const history = await loop.run([userMessage], () => {});
+    const loop = new AgentLoop(provider, "system", { tools: dummyTools });
+    const { history } = await loop.run([userMessage], () => {});
 
     // Should stop after first response (no executor to handle tool use)
     expect(history).toHaveLength(2);
@@ -327,7 +247,7 @@ describe("AgentLoop", () => {
 
     const loop = new AgentLoop(provider, "system");
     const events: AgentEvent[] = [];
-    const history = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run([userMessage], collectEvents(events));
 
     // Only the original message remains (no assistant message added on error)
     expect(history).toHaveLength(1);
@@ -347,7 +267,9 @@ describe("AgentLoop", () => {
 
     const { provider } = createMockProvider([textResponse("Should not reach")]);
     const loop = new AgentLoop(provider, "system");
-    const history = await loop.run([userMessage], () => {}, controller.signal);
+    const { history } = await loop.run([userMessage], () => {}, {
+      signal: controller.signal,
+    });
 
     // Loop should exit immediately, returning only original messages
     expect(history).toHaveLength(1);
@@ -372,14 +294,13 @@ describe("AgentLoop", () => {
       return { content: "data", isError: false };
     };
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
-    const history = await loop.run([userMessage], () => {}, controller.signal);
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
+    const { history } = await loop.run([userMessage], () => {}, {
+      signal: controller.signal,
+    });
 
     // After the first tool turn, abort fires. The while loop checks signal at the
     // top and breaks. History: user, assistant(t1), user(result1)
@@ -419,15 +340,14 @@ describe("AgentLoop", () => {
       return { content: "should never return", isError: false };
     };
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
     const start = Date.now();
-    const history = await loop.run([userMessage], () => {}, controller.signal);
+    const { history } = await loop.run([userMessage], () => {}, {
+      signal: controller.signal,
+    });
     const elapsed = Date.now() - start;
 
     // The loop should exit quickly (~50ms for abort), not wait 10s for the tool
@@ -516,13 +436,10 @@ describe("AgentLoop", () => {
     ]);
 
     const toolExecutor = async () => ({ content: "file data", isError: false });
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
 
     const events: AgentEvent[] = [];
     await loop.run([userMessage], collectEvents(events));
@@ -563,13 +480,10 @@ describe("AgentLoop", () => {
       content: "ENOENT: file not found",
       isError: true,
     });
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
 
     await loop.run([userMessage], () => {});
 
@@ -601,13 +515,10 @@ describe("AgentLoop", () => {
       return { content: "full output", isError: false };
     };
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
     const events: AgentEvent[] = [];
     await loop.run([userMessage], collectEvents(events));
 
@@ -626,7 +537,9 @@ describe("AgentLoop", () => {
   // 11. System prompt and tools are passed to provider
   test("passes system prompt and tools to provider", async () => {
     const { provider, calls } = createMockProvider([textResponse("Hi")]);
-    const loop = new AgentLoop(provider, "My system prompt", {}, dummyTools);
+    const loop = new AgentLoop(provider, "My system prompt", {
+      tools: dummyTools,
+    });
 
     await loop.run([userMessage], () => {});
 
@@ -692,15 +605,12 @@ describe("AgentLoop", () => {
       };
     };
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
     const events: AgentEvent[] = [];
-    const history = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run([userMessage], collectEvents(events));
 
     // All 3 tools should have been called
     expect(executionLog).toHaveLength(3);
@@ -789,19 +699,14 @@ describe("AgentLoop", () => {
       return { content: "data", isError: false };
     };
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
     const events: AgentEvent[] = [];
-    const history = await loop.run(
-      [userMessage],
-      collectEvents(events),
-      controller.signal,
-    );
+    const { history } = await loop.run([userMessage], collectEvents(events), {
+      signal: controller.signal,
+    });
 
     // No tools should have been executed
     expect(toolCalls).toHaveLength(0);
@@ -868,13 +773,10 @@ describe("AgentLoop", () => {
       return { content: `contents of ${path}`, isError: false };
     };
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
     const events: AgentEvent[] = [];
     await loop.run([userMessage], collectEvents(events));
 
@@ -903,13 +805,10 @@ describe("AgentLoop", () => {
     ]);
 
     const toolExecutor = async () => ({ content: "file data", isError: false });
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
 
     const checkpoints: CheckpointInfo[] = [];
     const onCheckpoint = (checkpoint: CheckpointInfo): CheckpointDecision => {
@@ -917,7 +816,7 @@ describe("AgentLoop", () => {
       return "continue";
     };
 
-    await loop.run([userMessage], () => {}, undefined, undefined, onCheckpoint);
+    await loop.run([userMessage], () => {}, { onCheckpoint });
 
     expect(checkpoints).toHaveLength(1);
     expect(checkpoints[0]).toMatchObject({
@@ -938,23 +837,16 @@ describe("AgentLoop", () => {
     ]);
 
     const toolExecutor = async () => ({ content: "data", isError: false });
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
 
     const onCheckpoint = (): CheckpointDecision => "continue";
 
-    const history = await loop.run(
-      [userMessage],
-      () => {},
-      undefined,
-      undefined,
+    const { history } = await loop.run([userMessage], () => {}, {
       onCheckpoint,
-    );
+    });
 
     // All 3 provider calls should happen (2 tool turns + final text)
     expect(calls).toHaveLength(3);
@@ -972,23 +864,16 @@ describe("AgentLoop", () => {
     ]);
 
     const toolExecutor = async () => ({ content: "data", isError: false });
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
 
-    const onCheckpoint = (): CheckpointDecision => "yield";
+    const onCheckpoint = (): CheckpointDecision => "budget";
 
-    const history = await loop.run(
-      [userMessage],
-      () => {},
-      undefined,
-      undefined,
+    const { history } = await loop.run([userMessage], () => {}, {
       onCheckpoint,
-    );
+    });
 
     // Only 1 provider call should happen — loop yields after first tool turn
     expect(calls).toHaveLength(1);
@@ -1006,15 +891,12 @@ describe("AgentLoop", () => {
     ]);
 
     const toolExecutor = async () => ({ content: "data", isError: false });
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
 
-    const history = await loop.run([userMessage], () => {});
+    const { history } = await loop.run([userMessage], () => {});
 
     // Normal behavior: 2 provider calls, full history
     expect(calls).toHaveLength(2);
@@ -1032,13 +914,10 @@ describe("AgentLoop", () => {
     ]);
 
     const toolExecutor = async () => ({ content: "data", isError: false });
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
 
     const checkpoints: CheckpointInfo[] = [];
     const onCheckpoint = (checkpoint: CheckpointInfo): CheckpointDecision => {
@@ -1046,7 +925,7 @@ describe("AgentLoop", () => {
       return "continue";
     };
 
-    await loop.run([userMessage], () => {}, undefined, undefined, onCheckpoint);
+    await loop.run([userMessage], () => {}, { onCheckpoint });
 
     expect(checkpoints).toHaveLength(3);
     expect(checkpoints[0].turnIndex).toBe(0);
@@ -1059,7 +938,7 @@ describe("AgentLoop", () => {
     const { provider } = createMockProvider([
       textResponse("Just a text response"),
     ]);
-    const loop = new AgentLoop(provider, "system", {}, dummyTools);
+    const loop = new AgentLoop(provider, "system", { tools: dummyTools });
 
     const checkpoints: CheckpointInfo[] = [];
     const onCheckpoint = (checkpoint: CheckpointInfo): CheckpointDecision => {
@@ -1067,13 +946,9 @@ describe("AgentLoop", () => {
       return "continue";
     };
 
-    const history = await loop.run(
-      [userMessage],
-      () => {},
-      undefined,
-      undefined,
+    const { history } = await loop.run([userMessage], () => {}, {
       onCheckpoint,
-    );
+    });
 
     // Checkpoint should never be called for a text-only response
     expect(checkpoints).toHaveLength(0);
@@ -1116,13 +991,10 @@ describe("AgentLoop", () => {
     ]);
 
     const toolExecutor = async () => ({ content: "data", isError: false });
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
 
     const checkpoints: CheckpointInfo[] = [];
     const onCheckpoint = (checkpoint: CheckpointInfo): CheckpointDecision => {
@@ -1130,7 +1002,7 @@ describe("AgentLoop", () => {
       return "continue";
     };
 
-    await loop.run([userMessage], () => {}, undefined, undefined, onCheckpoint);
+    await loop.run([userMessage], () => {}, { onCheckpoint });
 
     expect(checkpoints).toHaveLength(1);
     expect(checkpoints[0].toolCount).toBe(3);
@@ -1150,29 +1022,22 @@ describe("AgentLoop", () => {
 
     const { provider, calls } = createMockProvider(responses);
     const toolExecutor = async () => ({ content: "data", isError: false });
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
 
     const checkpoints: CheckpointInfo[] = [];
     const onCheckpoint = (checkpoint: CheckpointInfo): CheckpointDecision => {
       checkpoints.push(checkpoint);
       // Yield on turn 3 (0-indexed)
-      return checkpoint.turnIndex === 3 ? "yield" : "continue";
+      return checkpoint.turnIndex === 3 ? "budget" : "continue";
     };
 
     const events: AgentEvent[] = [];
-    const history = await loop.run(
-      [userMessage],
-      collectEvents(events),
-      undefined,
-      undefined,
+    const { history } = await loop.run([userMessage], collectEvents(events), {
       onCheckpoint,
-    );
+    });
 
     // Turns 0, 1, 2, 3 execute (4 provider calls). Turn 3 yields, so turns 4+ never execute.
     expect(calls).toHaveLength(4);
@@ -1226,26 +1091,19 @@ describe("AgentLoop", () => {
     ]);
 
     const toolExecutor = async () => ({ content: "data", isError: false });
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
 
     const onCheckpoint = (checkpoint: CheckpointInfo): CheckpointDecision => {
       // Yield on the second turn (turnIndex 1)
-      return checkpoint.turnIndex === 1 ? "yield" : "continue";
+      return checkpoint.turnIndex === 1 ? "budget" : "continue";
     };
 
-    const history = await loop.run(
-      [userMessage],
-      () => {},
-      undefined,
-      undefined,
+    const { history } = await loop.run([userMessage], () => {}, {
       onCheckpoint,
-    );
+    });
 
     // 2 provider calls: first tool turn + second tool turn (yield after second)
     expect(calls).toHaveLength(2);
@@ -1260,7 +1118,7 @@ describe("AgentLoop", () => {
   // 25. Without resolveTools, static tools are used
   test("without resolveTools, static tools are passed to provider", async () => {
     const { provider, calls } = createMockProvider([textResponse("Hi")]);
-    const loop = new AgentLoop(provider, "system", {}, dummyTools);
+    const loop = new AgentLoop(provider, "system", { tools: dummyTools });
 
     await loop.run([userMessage], () => {});
 
@@ -1293,14 +1151,10 @@ describe("AgentLoop", () => {
       return resolvedTools;
     };
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      [],
-      toolExecutor,
-      resolveTools,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      toolExecutor: toolExecutor,
+      resolveTools: resolveTools,
+    });
     await loop.run([userMessage], () => {});
 
     // resolveTools should be called once per provider turn (2 turns total)
@@ -1329,14 +1183,10 @@ describe("AgentLoop", () => {
     const resolveTools = (): ToolDefinition[] => dynamicTools;
 
     // Pass different static tools to verify they are overridden
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      undefined,
-      resolveTools,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      resolveTools: resolveTools,
+    });
     await loop.run([userMessage], () => {});
 
     // Provider should receive the dynamically resolved tools, not the static ones
@@ -1390,14 +1240,10 @@ describe("AgentLoop", () => {
     ]);
 
     const toolExecutor = async () => ({ content: "ok", isError: false });
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      [],
-      toolExecutor,
-      resolveTools,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      toolExecutor: toolExecutor,
+      resolveTools: resolveTools,
+    });
     await loop.run([userMessage], () => {});
 
     // Provider should have been called 3 times
@@ -1417,14 +1263,10 @@ describe("AgentLoop", () => {
       textResponse("No tools available"),
     ]);
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      undefined,
-      resolveTools,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      resolveTools: resolveTools,
+    });
     await loop.run([userMessage], () => {});
 
     // Empty array should result in undefined tools (same as no-tools behavior)
@@ -1449,15 +1291,13 @@ describe("AgentLoop", () => {
       return { content: largeContent, isError: false };
     };
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      { maxInputTokens: 180_000 },
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      config: { maxInputTokens: 180_000 },
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
     const events: AgentEvent[] = [];
-    const history = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run([userMessage], collectEvents(events));
 
     // The tool result user message is at index 2 in history
     const toolResultMsg = history[2];
@@ -1500,15 +1340,13 @@ describe("AgentLoop", () => {
       return { content: smallContent, isError: false };
     };
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      { maxInputTokens: 180_000 },
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      config: { maxInputTokens: 180_000 },
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
     const events: AgentEvent[] = [];
-    const history = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run([userMessage], collectEvents(events));
 
     // The tool result user message is at index 2 in history
     const toolResultMsg = history[2];
@@ -1560,15 +1398,12 @@ describe("AgentLoop", () => {
       ],
     });
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
     const events: AgentEvent[] = [];
-    const history = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run([userMessage], collectEvents(events));
 
     // The final assistant message in HISTORY should retain placeholders
     // (so the model never sees real values on subsequent turns)
@@ -1629,13 +1464,10 @@ describe("AgentLoop", () => {
       ],
     });
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
     const events: AgentEvent[] = [];
     await loop.run([userMessage], collectEvents(events));
 
@@ -1664,15 +1496,12 @@ describe("AgentLoop", () => {
       // No sensitiveBindings
     });
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
     const events: AgentEvent[] = [];
-    const history = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run([userMessage], collectEvents(events));
 
     const lastAssistant = history[history.length - 1];
     const textBlock = lastAssistant.content.find(
@@ -1681,9 +1510,11 @@ describe("AgentLoop", () => {
     expect(textBlock!.text).toBe("Normal response with no placeholders.");
   });
 
-  // Tool error retry nudge — when a tool returns isError: true, the loop
-  // should inject a system_notice nudging the LLM to retry instead of ending.
-  test("injects retry nudge system_notice when tool returns an error", async () => {
+  // Tool error retry coaching — when a tool returns isError: true, the coaching
+  // notice is appended as a separate text block in the tool-result user message
+  // (not into the tool_result content), nudging the LLM to retry instead of
+  // ending the turn while keeping the tool's actual output clean.
+  test("appends retry coaching as a separate block when a tool returns an error", async () => {
     const { provider, calls } = createMockProvider([
       // First turn: LLM calls a tool that errors
       toolUseResponse("t1", "read_file", { path: "/missing.txt" }),
@@ -1709,19 +1540,17 @@ describe("AgentLoop", () => {
       return { content: "file contents", isError: false };
     };
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
     await loop.run([userMessage], () => {});
 
     // Provider should have been called 3 times (error -> retry -> final text)
     expect(calls).toHaveLength(3);
 
-    // The second call's messages should contain the retry nudge system_notice
+    // The second call's messages should carry the retry coaching as a separate
+    // text block, with the tool_result's own content left untouched.
     const secondCallMessages = calls[1].messages;
     const toolResultMessage = secondCallMessages[secondCallMessages.length - 1];
     expect(toolResultMessage.role).toBe("user");
@@ -1732,7 +1561,14 @@ describe("AgentLoop", () => {
     );
     expect(retryNudge).toBeDefined();
 
-    // The third call should NOT have the retry nudge (successful tool result)
+    // The errored tool_result itself stays the tool's actual output.
+    const erroredToolResult = toolResultMessage.content.find(
+      (b): b is Extract<ContentBlock, { type: "tool_result" }> =>
+        b.type === "tool_result",
+    );
+    expect(erroredToolResult?.content).not.toContain("looks recoverable");
+
+    // The third call should NOT have the retry coaching (successful tool result)
     const thirdCallMessages = calls[2].messages;
     const thirdToolResultMessage =
       thirdCallMessages[thirdCallMessages.length - 1];
@@ -1743,8 +1579,9 @@ describe("AgentLoop", () => {
     expect(noRetryNudge).toBeUndefined();
   });
 
-  // Retry nudge stops after MAX_CONSECUTIVE_ERROR_NUDGES (3) consecutive errors
-  test("stops injecting retry nudge after 3 consecutive error turns", async () => {
+  // Retry coaching stops after a tool fails 3 times in a row — past that the
+  // error is likely unrecoverable and further coaching only burns tokens.
+  test("stops appending retry coaching after 3 consecutive failures of a tool", async () => {
     const { provider, calls } = createMockProvider([
       // 4 consecutive error turns, then final text
       toolUseResponse("t1", "read_file", { path: "/a" }),
@@ -1761,34 +1598,29 @@ describe("AgentLoop", () => {
       return { content: "service unavailable", isError: true };
     };
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
     await loop.run([userMessage], () => {});
 
     expect(calls).toHaveLength(5);
 
-    // Helper to check if a call's last user message has the retry nudge
+    // Helper to check if a call's last user message has the retry coaching
+    // (a separate text block, not part of the tool_result content).
     const hasRetryNudge = (callIndex: number): boolean => {
       const msgs = calls[callIndex].messages;
       const lastMsg = msgs[msgs.length - 1];
       return lastMsg.content.some(
-        (b) =>
-          b.type === "text" &&
-          "text" in b &&
-          (b as { text: string }).text.includes("looks recoverable"),
+        (b) => b.type === "text" && b.text.includes("looks recoverable"),
       );
     };
 
-    // Turns 1-3 should have the nudge
+    // Turns 1-3 should have the coaching
     expect(hasRetryNudge(1)).toBe(true);
     expect(hasRetryNudge(2)).toBe(true);
     expect(hasRetryNudge(3)).toBe(true);
-    // Turn 4 should NOT have the nudge (exceeded limit)
+    // Turn 4 should NOT have the coaching (exceeded limit)
     expect(hasRetryNudge(4)).toBe(false);
   });
 
@@ -1812,15 +1644,12 @@ describe("AgentLoop", () => {
       isError: false,
     });
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
     const events: AgentEvent[] = [];
-    const history = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run([userMessage], collectEvents(events));
 
     // Provider should be called 3 times: initial, empty response, retry
     expect(calls).toHaveLength(3);
@@ -1890,15 +1719,12 @@ describe("AgentLoop", () => {
       isError: false,
     });
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
     const events: AgentEvent[] = [];
-    const history = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run([userMessage], collectEvents(events));
 
     // Provider called exactly 2 times: initial [text+tool_use], then empty.
     // No third (retry) call because the prior turn had visible text.
@@ -1952,15 +1778,12 @@ describe("AgentLoop", () => {
       isError: false,
     });
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
     const events: AgentEvent[] = [];
-    const history = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run([userMessage], collectEvents(events));
 
     // Provider called 3 times: initial, empty, retry (also empty)
     expect(calls).toHaveLength(3);
@@ -1991,7 +1814,7 @@ describe("AgentLoop", () => {
 
     const loop = new AgentLoop(provider, "system");
     const events: AgentEvent[] = [];
-    const history = await loop.run([userMessage], collectEvents(events));
+    const { history } = await loop.run([userMessage], collectEvents(events));
 
     // Should NOT retry — this is the first turn with no tool use history
     expect(calls).toHaveLength(1);
@@ -2005,14 +1828,7 @@ describe("AgentLoop", () => {
     const { provider, calls } = createMockProvider([textResponse("ok")]);
 
     const loop = new AgentLoop(provider, "system");
-    await loop.run(
-      [userMessage],
-      () => {},
-      undefined, // signal
-      undefined, // requestId
-      undefined, // onCheckpoint
-      "heartbeatAgent",
-    );
+    await loop.run([userMessage], () => {}, { callSite: "heartbeatAgent" });
 
     expect(calls).toHaveLength(1);
     expect(calls[0].options?.config?.callSite).toBe("heartbeatAgent");