@vellumai/assistant 0.3.0

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

@@ -0,0 +1,1135 @@
+import { describe, test, expect } from 'bun:test';
+import { AgentLoop } from '../agent/loop.js';
+import type { AgentEvent, CheckpointInfo, CheckpointDecision } from '../agent/loop.js';
+import type {
+  Provider,
+  Message,
+  ProviderResponse,
+  SendMessageOptions,
+  ToolDefinition,
+  ContentBlock,
+} from '../providers/types.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 }[] } {
+  const calls: { messages: Message[]; tools?: ToolDefinition[]; systemPrompt?: string }[] = [];
+  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 });
+      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', description: 'Read a file', input_schema: { type: 'object', properties: { path: { type: 'string' } } } },
+];
+
+const userMessage: Message = {
+  role: 'user',
+  content: [{ type: 'text', text: 'Hello' }],
+};
+
+function collectEvents(events: AgentEvent[]): (event: AgentEvent) => void {
+  return (event) => events.push(event);
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('AgentLoop', () => {
+  // 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));
+
+    // History should contain original user message + assistant response
+    expect(history).toHaveLength(2);
+    expect(history[0]).toEqual(userMessage);
+    expect(history[1].role).toBe('assistant');
+    expect(history[1].content).toEqual([{ type: 'text', text: 'Hi there!' }]);
+  });
+
+  // 2. Tool execution — provider returns tool_use, verify tool executor is called
+  test('executes tool and passes result back to provider', async () => {
+    const toolCallId = 'tool-1';
+    const { provider, calls } = createMockProvider([
+      toolUseResponse(toolCallId, 'read_file', { path: '/tmp/test.txt' }),
+      textResponse('File contents received.'),
+    ]);
+
+    const toolCalls: { name: string; input: Record<string, unknown> }[] = [];
+    const toolExecutor = async (name: string, input: Record<string, unknown>) => {
+      toolCalls.push({ name, input });
+      return { content: 'file data here', isError: false };
+    };
+
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+    const events: AgentEvent[] = [];
+    const history = await loop.run([userMessage], collectEvents(events));
+
+    // Tool executor was called with correct args
+    expect(toolCalls).toHaveLength(1);
+    expect(toolCalls[0].name).toBe('read_file');
+    expect(toolCalls[0].input).toEqual({ path: '/tmp/test.txt' });
+
+    // Provider was called twice (initial + after tool result)
+    expect(calls).toHaveLength(2);
+
+    // Second call should include the tool result as a user message
+    const secondCallMessages = calls[1].messages;
+    const lastMsg = secondCallMessages[secondCallMessages.length - 1];
+    expect(lastMsg.role).toBe('user');
+
+    const toolResultBlock = lastMsg.content.find(
+      (b): b is Extract<ContentBlock, { type: 'tool_result' }> => b.type === 'tool_result',
+    );
+    expect(toolResultBlock).toBeDefined();
+    expect(toolResultBlock!.tool_use_id).toBe(toolCallId);
+    expect(toolResultBlock!.content).toBe('file data here');
+    expect(toolResultBlock!.is_error).toBe(false);
+
+    // Final history: user, assistant(tool_use), user(tool_result), assistant(text)
+    expect(history).toHaveLength(4);
+    expect(history[3].role).toBe('assistant');
+    expect(history[3].content).toEqual([{ type: 'text', text: 'File contents received.' }]);
+  });
+
+  // 3. Multi-turn tool loop
+  test('supports multi-turn tool execution', async () => {
+    const { provider, calls } = createMockProvider([
+      toolUseResponse('t1', 'read_file', { path: '/a.txt' }),
+      toolUseResponse('t2', 'read_file', { path: '/b.txt' }),
+      textResponse('Done reading both files.'),
+    ]);
+
+    const toolExecutor = async (name: string, input: Record<string, unknown>) => {
+      return { content: `contents of ${(input as { path: string }).path}`, isError: false };
+    };
+
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+    const history = await loop.run([userMessage], () => {});
+
+    // Provider called 3 times (two tool rounds + final text)
+    expect(calls).toHaveLength(3);
+
+    // History: user, assistant(t1), user(result1), assistant(t2), user(result2), assistant(text)
+    expect(history).toHaveLength(6);
+    expect(history[5].content).toEqual([{ type: 'text', text: 'Done reading both files.' }]);
+  });
+
+  // 4. Loop stops when provider returns tool_use but no executor is configured
+  test('stops when tool_use returned but no tool executor configured', async () => {
+    const { provider } = createMockProvider([
+      toolUseResponse('t1', 'read_file', { path: '/a.txt' }),
+    ]);
+
+    // No tool executor provided
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools);
+    const history = await loop.run([userMessage], () => {});
+
+    // Should stop after first response (no executor to handle tool use)
+    expect(history).toHaveLength(2);
+    expect(history[1].role).toBe('assistant');
+  });
+
+  // 5. Error handling — provider throws, verify error event and loop stops
+  test('emits error event and stops when provider throws', async () => {
+    const error = new Error('API rate limit exceeded');
+    const provider: Provider = {
+      name: 'mock',
+      async sendMessage(): Promise<ProviderResponse> {
+        throw error;
+      },
+    };
+
+    const loop = new AgentLoop(provider, 'system');
+    const events: AgentEvent[] = [];
+    const history = await loop.run([userMessage], collectEvents(events));
+
+    // Only the original message remains (no assistant message added on error)
+    expect(history).toHaveLength(1);
+
+    // Error event was emitted
+    const errorEvents = events.filter((e) => e.type === 'error');
+    expect(errorEvents).toHaveLength(1);
+    expect((errorEvents[0] as { type: 'error'; error: Error }).error.message).toBe('API rate limit exceeded');
+  });
+
+  // 6. Abort signal — verify the loop respects AbortSignal
+  test('stops when abort signal is triggered before provider call', async () => {
+    const controller = new AbortController();
+    controller.abort(); // abort immediately
+
+    const { provider } = createMockProvider([textResponse('Should not reach')]);
+    const loop = new AgentLoop(provider, 'system');
+    const history = await loop.run([userMessage], () => {}, controller.signal);
+
+    // Loop should exit immediately, returning only original messages
+    expect(history).toHaveLength(1);
+  });
+
+  test('stops when abort signal is triggered between turns', async () => {
+    const controller = new AbortController();
+    let turnCount = 0;
+
+    const { provider } = createMockProvider([
+      toolUseResponse('t1', 'read_file', { path: '/a.txt' }),
+      toolUseResponse('t2', 'read_file', { path: '/b.txt' }),
+      textResponse('Should not reach'),
+    ]);
+
+    const toolExecutor = async () => {
+      turnCount++;
+      if (turnCount === 1) {
+        // Abort after the first tool turn completes
+        controller.abort();
+      }
+      return { content: 'data', isError: false };
+    };
+
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+    const history = await loop.run([userMessage], () => {}, 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)
+    // The second provider call may or may not happen depending on when the abort
+    // check triggers, but the loop should eventually stop.
+    // At minimum, verify it doesn't run all 3 provider calls.
+    expect(history.length).toBeLessThanOrEqual(4);
+
+    // Verify the loop didn't reach the final text response
+    const lastAssistant = [...history].reverse().find(m => m.role === 'assistant');
+    expect(lastAssistant).toBeDefined();
+    const hasToolUse = lastAssistant!.content.some(b => b.type === 'tool_use');
+    // The last assistant message should be a tool_use, not the final text
+    expect(hasToolUse).toBe(true);
+  });
+
+  // 6b. Abort signal during long-running tool execution — loop exits immediately
+  test('stops immediately when abort fires during a stuck tool execution', async () => {
+    const controller = new AbortController();
+
+    const { provider } = createMockProvider([
+      toolUseResponse('t1', 'read_file', { path: '/stuck.txt' }),
+      textResponse('Should not reach'),
+    ]);
+
+    // Simulate a stuck tool that never resolves — abort fires while it's running
+    const toolExecutor = async () => {
+      // Abort from a timer while this tool is "stuck"
+      setTimeout(() => controller.abort(), 50);
+      // Simulate being stuck for a long time
+      await new Promise(resolve => setTimeout(resolve, 10_000));
+      return { content: 'should never return', isError: false };
+    };
+
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+    const start = Date.now();
+    const history = await loop.run([userMessage], () => {}, controller.signal);
+    const elapsed = Date.now() - start;
+
+    // The loop should exit quickly (~50ms for abort), not wait 10s for the tool
+    expect(elapsed).toBeLessThan(2000);
+
+    // User message + assistant tool_use + synthesized cancellation tool_result
+    expect(history).toHaveLength(3);
+    const lastMsg = history[2];
+    expect(lastMsg.role).toBe('user');
+    expect(lastMsg.content).toHaveLength(1);
+    expect(lastMsg.content[0].type).toBe('tool_result');
+    expect((lastMsg.content[0] as { type: 'tool_result'; tool_use_id: string; content: string; is_error: boolean }).content).toBe('Cancelled by user');
+    expect((lastMsg.content[0] as { type: 'tool_result'; tool_use_id: string; content: string; is_error: boolean }).is_error).toBe(true);
+  });
+
+  // 7. Events — verify text_delta and other events are emitted
+  test('emits text_delta events during streaming', async () => {
+    const { provider } = createMockProvider([textResponse('Hello world')]);
+    const loop = new AgentLoop(provider, 'system');
+
+    const events: AgentEvent[] = [];
+    await loop.run([userMessage], collectEvents(events));
+
+    const textDeltas = events.filter((e) => e.type === 'text_delta');
+    expect(textDeltas).toHaveLength(1);
+    expect((textDeltas[0] as { type: 'text_delta'; text: string }).text).toBe('Hello world');
+  });
+
+  test('emits usage events', async () => {
+    const { provider } = createMockProvider([textResponse('Hi')]);
+    const loop = new AgentLoop(provider, 'system');
+
+    const events: AgentEvent[] = [];
+    await loop.run([userMessage], collectEvents(events));
+
+    const usageEvents = events.filter((e) => e.type === 'usage');
+    expect(usageEvents).toHaveLength(1);
+    const usage = usageEvents[0] as Extract<AgentEvent, { type: 'usage' }>;
+    expect(usage.type).toBe('usage');
+    expect(usage.inputTokens).toBe(10);
+    expect(usage.outputTokens).toBe(5);
+    expect(usage.model).toBe('mock-model');
+    expect(typeof usage.providerDurationMs).toBe('number');
+    expect(usage.providerDurationMs).toBeGreaterThanOrEqual(0);
+  });
+
+  test('emits message_complete events', async () => {
+    const { provider } = createMockProvider([textResponse('Done')]);
+    const loop = new AgentLoop(provider, 'system');
+
+    const events: AgentEvent[] = [];
+    await loop.run([userMessage], collectEvents(events));
+
+    const completeEvents = events.filter((e) => e.type === 'message_complete');
+    expect(completeEvents).toHaveLength(1);
+    expect((completeEvents[0] as { type: 'message_complete'; message: Message }).message.role).toBe('assistant');
+  });
+
+  test('emits tool_use and tool_result events during tool execution', async () => {
+    const { provider } = createMockProvider([
+      toolUseResponse('t1', 'read_file', { path: '/test.txt' }),
+      textResponse('Done'),
+    ]);
+
+    const toolExecutor = async () => ({ content: 'file data', isError: false });
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+
+    const events: AgentEvent[] = [];
+    await loop.run([userMessage], collectEvents(events));
+
+    const toolUseEvents = events.filter((e) => e.type === 'tool_use');
+    expect(toolUseEvents).toHaveLength(1);
+    expect(toolUseEvents[0]).toEqual({
+      type: 'tool_use',
+      id: 't1',
+      name: 'read_file',
+      input: { path: '/test.txt' },
+    });
+
+    const toolResultEvents = events.filter((e) => e.type === 'tool_result');
+    expect(toolResultEvents).toHaveLength(1);
+    expect((toolResultEvents[0] as Extract<AgentEvent, { type: 'tool_result' }>).toolUseId).toBe('t1');
+    expect((toolResultEvents[0] as Extract<AgentEvent, { type: 'tool_result' }>).content).toBe('file data');
+    expect((toolResultEvents[0] as Extract<AgentEvent, { type: 'tool_result' }>).isError).toBe(false);
+  });
+
+  // 8. Progress reminder injection every 5 tool-use turns
+  test('injects progress reminder after every 5 tool-use turns', async () => {
+    // Create 6 tool responses followed by a text response
+    const responses: ProviderResponse[] = [];
+    for (let i = 0; i < 6; i++) {
+      responses.push(toolUseResponse(`t${i}`, 'read_file', { path: `/file${i}.txt` }));
+    }
+    responses.push(textResponse('Finally done'));
+
+    const { provider, calls } = createMockProvider(responses);
+    const toolExecutor = async () => ({ content: 'data', isError: false });
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+
+    await loop.run([userMessage], () => {});
+
+    // After the 5th tool-use turn, the user message should contain a progress reminder
+    // calls[5] is the 6th provider call; its messages[-1] should have the reminder
+    const fifthTurnResultMsg = calls[5].messages[calls[5].messages.length - 1];
+    const reminderBlock = fifthTurnResultMsg.content.find(
+      (b): b is Extract<ContentBlock, { type: 'text' }> =>
+        b.type === 'text' && b.text.includes('making meaningful progress'),
+    );
+    expect(reminderBlock).toBeDefined();
+  });
+
+  test('stops after configured maxToolUseTurns to prevent runaway loops', async () => {
+    const responses: ProviderResponse[] = [
+      toolUseResponse('t1', 'read_file', { path: '/one.txt' }),
+      toolUseResponse('t2', 'read_file', { path: '/two.txt' }),
+      toolUseResponse('t3', 'read_file', { path: '/three.txt' }),
+      textResponse('Should never be requested'),
+    ];
+    const { provider, calls } = createMockProvider(responses);
+    const toolExecutor = async () => ({ content: 'data', isError: false });
+    const loop = new AgentLoop(
+      provider,
+      'system',
+      { maxToolUseTurns: 3 },
+      dummyTools,
+      toolExecutor,
+    );
+
+    const events: AgentEvent[] = [];
+    const history = await loop.run([userMessage], collectEvents(events));
+
+    // The loop should stop immediately after the 3rd tool-use turn, before the next provider call.
+    expect(calls).toHaveLength(3);
+
+    const errorEvents = events.filter(
+      (e): e is Extract<AgentEvent, { type: 'error' }> => e.type === 'error',
+    );
+    expect(errorEvents).toHaveLength(1);
+    expect(errorEvents[0].error.message).toContain('Tool-use turn limit reached (3)');
+
+    const lastMessage = history[history.length - 1];
+    expect(lastMessage.role).toBe('user');
+    const limitText = lastMessage.content.find(
+      (b): b is Extract<ContentBlock, { type: 'text' }> =>
+        b.type === 'text' && b.text.includes('Tool-use turn limit reached (3)'),
+    );
+    expect(limitText).toBeDefined();
+  });
+
+  // 9. Tool executor error results are forwarded correctly
+  test('forwards tool error results to provider', async () => {
+    const { provider, calls } = createMockProvider([
+      toolUseResponse('t1', 'read_file', { path: '/nonexistent.txt' }),
+      textResponse('File not found, sorry.'),
+    ]);
+
+    const toolExecutor = async () => ({ content: 'ENOENT: file not found', isError: true });
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+
+    await loop.run([userMessage], () => {});
+
+    const secondCallMessages = calls[1].messages;
+    const lastMsg = secondCallMessages[secondCallMessages.length - 1];
+    const toolResultBlock = lastMsg.content.find(
+      (b): b is Extract<ContentBlock, { type: 'tool_result' }> => b.type === 'tool_result',
+    );
+    expect(toolResultBlock).toBeDefined();
+    expect(toolResultBlock!.is_error).toBe(true);
+    expect(toolResultBlock!.content).toBe('ENOENT: file not found');
+  });
+
+  // 10. Tool output chunks are forwarded via onEvent
+  test('emits tool_output_chunk events during tool execution', async () => {
+    const { provider } = createMockProvider([
+      toolUseResponse('t1', 'read_file', { path: '/test.txt' }),
+      textResponse('Done'),
+    ]);
+
+    const toolExecutor = async (
+      _name: string,
+      _input: Record<string, unknown>,
+      onOutput?: (chunk: string) => void,
+    ) => {
+      onOutput?.('chunk1');
+      onOutput?.('chunk2');
+      return { content: 'full output', isError: false };
+    };
+
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+    const events: AgentEvent[] = [];
+    await loop.run([userMessage], collectEvents(events));
+
+    const chunkEvents = events.filter((e) => e.type === 'tool_output_chunk');
+    expect(chunkEvents).toHaveLength(2);
+    expect((chunkEvents[0] as Extract<AgentEvent, { type: 'tool_output_chunk' }>).chunk).toBe('chunk1');
+    expect((chunkEvents[1] as Extract<AgentEvent, { type: 'tool_output_chunk' }>).chunk).toBe('chunk2');
+  });
+
+  // 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);
+
+    await loop.run([userMessage], () => {});
+
+    expect(calls[0].systemPrompt).toBe('My system prompt');
+    expect(calls[0].tools).toEqual(dummyTools);
+  });
+
+  // 12. No tools configured — tools are not passed to provider
+  test('does not pass tools to provider when none are configured', async () => {
+    const { provider, calls } = createMockProvider([textResponse('Hi')]);
+    const loop = new AgentLoop(provider, 'system');
+
+    await loop.run([userMessage], () => {});
+
+    expect(calls[0].tools).toBeUndefined();
+  });
+
+  // 13. Parallel tool execution — multiple tool_use blocks in a single response
+  test('executes multiple tools in parallel', async () => {
+    const { provider, calls } = createMockProvider([
+      // Provider returns 3 tool_use blocks in a single response
+      {
+        content: [
+          { type: 'tool_use' as const, id: 't1', name: 'read_file', input: { path: '/a.txt' } },
+          { type: 'tool_use' as const, id: 't2', name: 'read_file', input: { path: '/b.txt' } },
+          { type: 'tool_use' as const, id: 't3', name: 'read_file', input: { path: '/c.txt' } },
+        ],
+        model: 'mock-model',
+        usage: { inputTokens: 10, outputTokens: 5 },
+        stopReason: 'tool_use' as const,
+      },
+      textResponse('Got all three files.'),
+    ]);
+
+    const executionLog: { path: string; start: number; end: number }[] = [];
+    const toolExecutor = async (_name: string, input: Record<string, unknown>) => {
+      const start = Date.now();
+      // Simulate async work — all tools should overlap in time
+      await new Promise(resolve => setTimeout(resolve, 50));
+      const end = Date.now();
+      executionLog.push({ path: (input as { path: string }).path, start, end });
+      return { content: `contents of ${(input as { path: string }).path}`, isError: false };
+    };
+
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+    const events: AgentEvent[] = [];
+    const history = await loop.run([userMessage], collectEvents(events));
+
+    // All 3 tools should have been called
+    expect(executionLog).toHaveLength(3);
+
+    // Verify parallel execution: all tools should start before any finishes
+    // (with 50ms delay each, sequential would take 150ms+, parallel ~50ms)
+    const allStarts = executionLog.map(e => e.start);
+    const allEnds = executionLog.map(e => e.end);
+    const firstEnd = Math.min(...allEnds);
+    const lastStart = Math.max(...allStarts);
+    // In parallel execution, the last tool starts before the first tool ends
+    expect(lastStart).toBeLessThanOrEqual(firstEnd);
+
+    // Provider should have been called twice (tool batch + final text)
+    expect(calls).toHaveLength(2);
+
+    // Second call should contain 3 tool_result blocks in order
+    const secondCallMessages = calls[1].messages;
+    const lastMsg = secondCallMessages[secondCallMessages.length - 1];
+    const toolResultBlocks = lastMsg.content.filter(
+      (b): b is Extract<ContentBlock, { type: 'tool_result' }> => b.type === 'tool_result',
+    );
+    expect(toolResultBlocks).toHaveLength(3);
+    expect(toolResultBlocks[0].tool_use_id).toBe('t1');
+    expect(toolResultBlocks[1].tool_use_id).toBe('t2');
+    expect(toolResultBlocks[2].tool_use_id).toBe('t3');
+
+    // All tool_use events should be emitted before any tool_result events
+    let lastToolUseIdx = -1;
+    let firstToolResultIdx = events.length;
+    events.forEach((e, i) => {
+      if (e.type === 'tool_use') lastToolUseIdx = i;
+      if (e.type === 'tool_result' && i < firstToolResultIdx) firstToolResultIdx = i;
+    });
+    expect(lastToolUseIdx).toBeLessThan(firstToolResultIdx);
+
+    // Final history: user, assistant(3 tool_use), user(3 tool_result), assistant(text)
+    expect(history).toHaveLength(4);
+  });
+
+  // 14. Abort before parallel tool execution synthesizes cancelled results
+  test('synthesizes cancelled results when aborted before tool execution', async () => {
+    const controller = new AbortController();
+
+    const { provider } = createMockProvider([
+      {
+        content: [
+          { type: 'tool_use' as const, id: 't1', name: 'read_file', input: { path: '/a.txt' } },
+          { type: 'tool_use' as const, id: 't2', name: 'read_file', input: { path: '/b.txt' } },
+        ],
+        model: 'mock-model',
+        usage: { inputTokens: 10, outputTokens: 5 },
+        stopReason: 'tool_use' as const,
+      },
+    ]);
+
+    // Abort during the provider call so the signal is already aborted
+    // before tool execution begins
+    const originalSendMessage = provider.sendMessage.bind(provider);
+    provider.sendMessage = async (...args: Parameters<typeof provider.sendMessage>) => {
+      const result = await originalSendMessage(...args);
+      controller.abort();
+      return result;
+    };
+
+    const toolCalls: string[] = [];
+    const toolExecutor = async (_name: string, input: Record<string, unknown>) => {
+      toolCalls.push((input as { path: string }).path);
+      return { content: 'data', isError: false };
+    };
+
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+    const events: AgentEvent[] = [];
+    const history = await loop.run([userMessage], collectEvents(events), controller.signal);
+
+    // No tools should have been executed
+    expect(toolCalls).toHaveLength(0);
+
+    // History should contain cancelled tool_result blocks
+    const lastMsg = history[history.length - 1];
+    expect(lastMsg.role).toBe('user');
+    const toolResultBlocks = lastMsg.content.filter(
+      (b): b is Extract<ContentBlock, { type: 'tool_result' }> => b.type === 'tool_result',
+    );
+    expect(toolResultBlocks).toHaveLength(2);
+    expect(toolResultBlocks[0].tool_use_id).toBe('t1');
+    expect(toolResultBlocks[0].content).toBe('Cancelled by user');
+    expect(toolResultBlocks[0].is_error).toBe(true);
+    expect(toolResultBlocks[1].tool_use_id).toBe('t2');
+    expect(toolResultBlocks[1].content).toBe('Cancelled by user');
+    expect(toolResultBlocks[1].is_error).toBe(true);
+  });
+
+  // 15. Parallel tool_result events are emitted in deterministic tool_use order
+  test('emits tool_result events in tool_use order regardless of completion timing', async () => {
+    const { provider } = createMockProvider([
+      {
+        content: [
+          { type: 'tool_use' as const, id: 't1', name: 'read_file', input: { path: '/slow.txt' } },
+          { type: 'tool_use' as const, id: 't2', name: 'read_file', input: { path: '/fast.txt' } },
+          { type: 'tool_use' as const, id: 't3', name: 'read_file', input: { path: '/medium.txt' } },
+        ],
+        model: 'mock-model',
+        usage: { inputTokens: 10, outputTokens: 5 },
+        stopReason: 'tool_use' as const,
+      },
+      textResponse('Done'),
+    ]);
+
+    // Tools complete in different order than they were called: t2 first, t3 second, t1 last
+    const toolExecutor = async (_name: string, input: Record<string, unknown>) => {
+      const path = (input as { path: string }).path;
+      const delays: Record<string, number> = { '/slow.txt': 80, '/fast.txt': 10, '/medium.txt': 40 };
+      await new Promise(resolve => setTimeout(resolve, delays[path] ?? 10));
+      return { content: `contents of ${path}`, isError: false };
+    };
+
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+    const events: AgentEvent[] = [];
+    await loop.run([userMessage], collectEvents(events));
+
+    // Collect tool_result events in order
+    const toolResultEvents = events.filter(
+      (e): e is Extract<AgentEvent, { type: 'tool_result' }> => e.type === 'tool_result',
+    );
+    expect(toolResultEvents).toHaveLength(3);
+
+    // Results must be in tool_use order (t1, t2, t3), NOT completion order (t2, t3, t1)
+    expect(toolResultEvents[0].toolUseId).toBe('t1');
+    expect(toolResultEvents[1].toolUseId).toBe('t2');
+    expect(toolResultEvents[2].toolUseId).toBe('t3');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Checkpoint callback tests
+  // ---------------------------------------------------------------------------
+
+  // 16. Checkpoint callback is called after tool results with correct info
+  test('checkpoint callback is called after tool results with correct info', async () => {
+    const { provider } = createMockProvider([
+      toolUseResponse('t1', 'read_file', { path: '/test.txt' }),
+      textResponse('Done'),
+    ]);
+
+    const toolExecutor = async () => ({ content: 'file data', isError: false });
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+
+    const checkpoints: CheckpointInfo[] = [];
+    const onCheckpoint = (checkpoint: CheckpointInfo): CheckpointDecision => {
+      checkpoints.push(checkpoint);
+      return 'continue';
+    };
+
+    await loop.run([userMessage], () => {}, undefined, undefined, onCheckpoint);
+
+    expect(checkpoints).toHaveLength(1);
+    expect(checkpoints[0]).toEqual({
+      turnIndex: 0,
+      toolCount: 1,
+      hasToolUse: true,
+    });
+  });
+
+  // 17. Returning 'continue' lets the loop proceed normally
+  test('checkpoint returning continue lets the loop proceed normally', async () => {
+    const { provider, calls } = createMockProvider([
+      toolUseResponse('t1', 'read_file', { path: '/a.txt' }),
+      toolUseResponse('t2', 'read_file', { path: '/b.txt' }),
+      textResponse('All done'),
+    ]);
+
+    const toolExecutor = async () => ({ content: 'data', isError: false });
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+
+    const onCheckpoint = (): CheckpointDecision => 'continue';
+
+    const history = await loop.run([userMessage], () => {}, undefined, undefined, onCheckpoint);
+
+    // All 3 provider calls should happen (2 tool turns + final text)
+    expect(calls).toHaveLength(3);
+    // Full history: user, assistant(t1), user(result1), assistant(t2), user(result2), assistant(text)
+    expect(history).toHaveLength(6);
+    expect(history[5].content).toEqual([{ type: 'text', text: 'All done' }]);
+  });
+
+  // 18. Returning 'yield' causes the loop to stop after that turn
+  test('checkpoint returning yield causes the loop to stop', async () => {
+    const { provider, calls } = createMockProvider([
+      toolUseResponse('t1', 'read_file', { path: '/a.txt' }),
+      toolUseResponse('t2', 'read_file', { path: '/b.txt' }),
+      textResponse('Should not reach'),
+    ]);
+
+    const toolExecutor = async () => ({ content: 'data', isError: false });
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+
+    const onCheckpoint = (): CheckpointDecision => 'yield';
+
+    const history = await loop.run([userMessage], () => {}, undefined, undefined, onCheckpoint);
+
+    // Only 1 provider call should happen — loop yields after first tool turn
+    expect(calls).toHaveLength(1);
+    // History: user, assistant(t1), user(result1)
+    expect(history).toHaveLength(3);
+    expect(history[1].role).toBe('assistant');
+    expect(history[2].role).toBe('user');
+  });
+
+  // 19. Without a checkpoint callback, behavior is unchanged
+  test('without checkpoint callback behavior is unchanged', async () => {
+    const { provider, calls } = createMockProvider([
+      toolUseResponse('t1', 'read_file', { path: '/a.txt' }),
+      textResponse('Done'),
+    ]);
+
+    const toolExecutor = async () => ({ content: 'data', isError: false });
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+
+    const history = await loop.run([userMessage], () => {});
+
+    // Normal behavior: 2 provider calls, full history
+    expect(calls).toHaveLength(2);
+    expect(history).toHaveLength(4);
+    expect(history[3].content).toEqual([{ type: 'text', text: 'Done' }]);
+  });
+
+  // 20. turnIndex increments correctly across turns
+  test('turnIndex increments correctly across multiple turns', async () => {
+    const { provider } = createMockProvider([
+      toolUseResponse('t1', 'read_file', { path: '/a.txt' }),
+      toolUseResponse('t2', 'read_file', { path: '/b.txt' }),
+      toolUseResponse('t3', 'read_file', { path: '/c.txt' }),
+      textResponse('Done'),
+    ]);
+
+    const toolExecutor = async () => ({ content: 'data', isError: false });
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+
+    const checkpoints: CheckpointInfo[] = [];
+    const onCheckpoint = (checkpoint: CheckpointInfo): CheckpointDecision => {
+      checkpoints.push(checkpoint);
+      return 'continue';
+    };
+
+    await loop.run([userMessage], () => {}, undefined, undefined, onCheckpoint);
+
+    expect(checkpoints).toHaveLength(3);
+    expect(checkpoints[0].turnIndex).toBe(0);
+    expect(checkpoints[1].turnIndex).toBe(1);
+    expect(checkpoints[2].turnIndex).toBe(2);
+  });
+
+  // 21. Checkpoint is NOT called when there's no tool use
+  test('checkpoint is not called when assistant responds with text only', async () => {
+    const { provider } = createMockProvider([textResponse('Just a text response')]);
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools);
+
+    const checkpoints: CheckpointInfo[] = [];
+    const onCheckpoint = (checkpoint: CheckpointInfo): CheckpointDecision => {
+      checkpoints.push(checkpoint);
+      return 'continue';
+    };
+
+    const history = await loop.run([userMessage], () => {}, undefined, undefined, onCheckpoint);
+
+    // Checkpoint should never be called for a text-only response
+    expect(checkpoints).toHaveLength(0);
+    // Normal response
+    expect(history).toHaveLength(2);
+    expect(history[1].content).toEqual([{ type: 'text', text: 'Just a text response' }]);
+  });
+
+  // 22. Checkpoint reports correct toolCount for parallel tool execution
+  test('checkpoint reports correct toolCount for parallel tools', async () => {
+    const { provider } = createMockProvider([
+      {
+        content: [
+          { type: 'tool_use' as const, id: 't1', name: 'read_file', input: { path: '/a.txt' } },
+          { type: 'tool_use' as const, id: 't2', name: 'read_file', input: { path: '/b.txt' } },
+          { type: 'tool_use' as const, id: 't3', name: 'read_file', input: { path: '/c.txt' } },
+        ],
+        model: 'mock-model',
+        usage: { inputTokens: 10, outputTokens: 5 },
+        stopReason: 'tool_use' as const,
+      },
+      textResponse('Got all three'),
+    ]);
+
+    const toolExecutor = async () => ({ content: 'data', isError: false });
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+
+    const checkpoints: CheckpointInfo[] = [];
+    const onCheckpoint = (checkpoint: CheckpointInfo): CheckpointDecision => {
+      checkpoints.push(checkpoint);
+      return 'continue';
+    };
+
+    await loop.run([userMessage], () => {}, undefined, undefined, onCheckpoint);
+
+    expect(checkpoints).toHaveLength(1);
+    expect(checkpoints[0].toolCount).toBe(3);
+    expect(checkpoints[0].hasToolUse).toBe(true);
+  });
+
+  // 23. Multiple checkpoints across a multi-turn run with selective yield on turn 3
+  test('multiple checkpoints with selective yield — executes turns 0-2, yields at turn 3, never runs 4+', async () => {
+    // Mock provider to return tool_use for 5 turns, then text
+    const responses: ProviderResponse[] = [];
+    for (let i = 0; i < 5; i++) {
+      responses.push(toolUseResponse(`t${i}`, 'read_file', { path: `/file${i}.txt` }));
+    }
+    responses.push(textResponse('Should never reach this'));
+
+    const { provider, calls } = createMockProvider(responses);
+    const toolExecutor = async () => ({ content: 'data', isError: false });
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+
+    const checkpoints: CheckpointInfo[] = [];
+    const onCheckpoint = (checkpoint: CheckpointInfo): CheckpointDecision => {
+      checkpoints.push(checkpoint);
+      // Yield on turn 3 (0-indexed)
+      return checkpoint.turnIndex === 3 ? 'yield' : 'continue';
+    };
+
+    const events: AgentEvent[] = [];
+    const history = await loop.run([userMessage], collectEvents(events), undefined, undefined, onCheckpoint);
+
+    // Turns 0, 1, 2, 3 execute (4 provider calls). Turn 3 yields, so turns 4+ never execute.
+    expect(calls).toHaveLength(4);
+
+    // Checkpoints should have been called for turns 0 through 3
+    expect(checkpoints).toHaveLength(4);
+    expect(checkpoints[0].turnIndex).toBe(0);
+    expect(checkpoints[1].turnIndex).toBe(1);
+    expect(checkpoints[2].turnIndex).toBe(2);
+    expect(checkpoints[3].turnIndex).toBe(3);
+
+    // History should contain results from turns 0-3:
+    // user, assistant(t0), user(result0), assistant(t1), user(result1),
+    // assistant(t2), user(result2), assistant(t3), user(result3)
+    // = 1 original + 4*(assistant + user) = 9
+    expect(history).toHaveLength(9);
+
+    // Verify the last two messages are from turn 3
+    expect(history[7].role).toBe('assistant');
+    const lastAssistantToolUse = history[7].content.find((b) => b.type === 'tool_use');
+    expect(lastAssistantToolUse).toBeDefined();
+    if (lastAssistantToolUse && lastAssistantToolUse.type === 'tool_use') {
+      expect(lastAssistantToolUse.id).toBe('t3');
+    }
+    expect(history[8].role).toBe('user');
+    const lastToolResult = history[8].content.find(
+      (b): b is Extract<ContentBlock, { type: 'tool_result' }> => b.type === 'tool_result',
+    );
+    expect(lastToolResult).toBeDefined();
+    expect(lastToolResult!.tool_use_id).toBe('t3');
+
+    // Verify turns 4+ never executed — no tool_use event for t4
+    const toolUseEvents = events.filter(
+      (e): e is Extract<AgentEvent, { type: 'tool_use' }> => e.type === 'tool_use',
+    );
+    const toolUseNames = toolUseEvents.map((e) => e.id);
+    expect(toolUseNames).toEqual(['t0', 't1', 't2', 't3']);
+    expect(toolUseNames).not.toContain('t4');
+  });
+
+  // 24. Yield on second turn — first turn proceeds, second stops
+  test('yield on second turn lets first turn proceed and stops on second', async () => {
+    const { provider, calls } = createMockProvider([
+      toolUseResponse('t1', 'read_file', { path: '/a.txt' }),
+      toolUseResponse('t2', 'read_file', { path: '/b.txt' }),
+      textResponse('Should not reach'),
+    ]);
+
+    const toolExecutor = async () => ({ content: 'data', isError: false });
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+
+    const onCheckpoint = (checkpoint: CheckpointInfo): CheckpointDecision => {
+      // Yield on the second turn (turnIndex 1)
+      return checkpoint.turnIndex === 1 ? 'yield' : 'continue';
+    };
+
+    const history = await loop.run([userMessage], () => {}, undefined, undefined, onCheckpoint);
+
+    // 2 provider calls: first tool turn + second tool turn (yield after second)
+    expect(calls).toHaveLength(2);
+    // History: user, assistant(t1), user(result1), assistant(t2), user(result2)
+    expect(history).toHaveLength(5);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Dynamic tool resolver (resolveTools) tests
+  // ---------------------------------------------------------------------------
+
+  // 25. Without resolveTools, static tools are used (backward compatible)
+  test('without resolveTools, static tools are passed to provider', async () => {
+    const { provider, calls } = createMockProvider([textResponse('Hi')]);
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools);
+
+    await loop.run([userMessage], () => {});
+
+    expect(calls[0].tools).toEqual(dummyTools);
+  });
+
+  // 26. resolveTools callback is invoked before each provider call
+  test('resolveTools is invoked before each provider call', async () => {
+    const resolverCalls: Message[][] = [];
+    const resolvedTools: ToolDefinition[] = [
+      { name: 'search', description: 'Search files', input_schema: { type: 'object', properties: { query: { type: 'string' } } } },
+    ];
+
+    const { provider } = createMockProvider([
+      toolUseResponse('t1', 'search', { query: 'foo' }),
+      textResponse('Found it'),
+    ]);
+
+    const toolExecutor = async () => ({ content: 'result', isError: false });
+
+    const resolveTools = (history: Message[]): ToolDefinition[] => {
+      resolverCalls.push([...history]);
+      return resolvedTools;
+    };
+
+    const loop = new AgentLoop(provider, 'system', {}, [], toolExecutor, resolveTools);
+    await loop.run([userMessage], () => {});
+
+    // resolveTools should be called once per provider turn (2 turns total)
+    expect(resolverCalls).toHaveLength(2);
+
+    // First call receives just the initial user message
+    expect(resolverCalls[0]).toHaveLength(1);
+    expect(resolverCalls[0][0]).toEqual(userMessage);
+
+    // Second call receives the accumulated history (user + assistant + tool_result)
+    expect(resolverCalls[1].length).toBeGreaterThan(1);
+  });
+
+  // 27. Resolved tool list is passed to the provider
+  test('resolved tools are passed to the provider instead of static tools', async () => {
+    const dynamicTools: ToolDefinition[] = [
+      { name: 'dynamic_tool', description: 'Dynamic', input_schema: { type: 'object' } },
+    ];
+
+    const { provider, calls } = createMockProvider([textResponse('Hi')]);
+
+    const resolveTools = (): ToolDefinition[] => dynamicTools;
+
+    // Pass different static tools to verify they are overridden
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, undefined, resolveTools);
+    await loop.run([userMessage], () => {});
+
+    // Provider should receive the dynamically resolved tools, not the static ones
+    expect(calls[0].tools).toEqual(dynamicTools);
+    expect(calls[0].tools).not.toEqual(dummyTools);
+  });
+
+  // 28. Tool list can change between turns
+  test('resolveTools can return different tools on each turn', async () => {
+    const toolsPerTurn: ToolDefinition[][] = [
+      [{ name: 'tool_a', description: 'Tool A', input_schema: { type: 'object' } }],
+      [
+        { name: 'tool_a', description: 'Tool A', input_schema: { type: 'object' } },
+        { name: 'tool_b', description: 'Tool B', input_schema: { type: 'object' } },
+      ],
+      [{ name: 'tool_c', description: 'Tool C', input_schema: { type: 'object' } }],
+    ];
+
+    let turnIndex = 0;
+    const resolveTools = (): ToolDefinition[] => {
+      const tools = toolsPerTurn[turnIndex] ?? toolsPerTurn[toolsPerTurn.length - 1];
+      turnIndex++;
+      return tools;
+    };
+
+    const { provider, calls } = createMockProvider([
+      toolUseResponse('t1', 'tool_a', {}),
+      toolUseResponse('t2', 'tool_a', {}),
+      textResponse('Done'),
+    ]);
+
+    const toolExecutor = async () => ({ content: 'ok', isError: false });
+    const loop = new AgentLoop(provider, 'system', {}, [], toolExecutor, resolveTools);
+    await loop.run([userMessage], () => {});
+
+    // Provider should have been called 3 times
+    expect(calls).toHaveLength(3);
+
+    // Each call should have received different tools
+    expect(calls[0].tools).toEqual(toolsPerTurn[0]);
+    expect(calls[1].tools).toEqual(toolsPerTurn[1]);
+    expect(calls[2].tools).toEqual(toolsPerTurn[2]);
+  });
+
+  // 29. resolveTools returning empty array means no tools passed to provider
+  test('resolveTools returning empty array sends no tools to provider', async () => {
+    const resolveTools = (): ToolDefinition[] => [];
+
+    const { provider, calls } = createMockProvider([textResponse('No tools available')]);
+
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, undefined, resolveTools);
+    await loop.run([userMessage], () => {});
+
+    // Empty array should result in undefined tools (same as no-tools behavior)
+    expect(calls[0].tools).toBeUndefined();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Tool result truncation tests
+  // ---------------------------------------------------------------------------
+
+  // 30. Oversized tool results are truncated before entering history
+  test('truncates oversized tool results before adding to history', async () => {
+    const toolCallId = 'tool-large';
+    const largeContent = 'x'.repeat(500_000);
+
+    const { provider, calls } = createMockProvider([
+      toolUseResponse(toolCallId, 'read_file', { path: '/huge.txt' }),
+      textResponse('Got it.'),
+    ]);
+
+    const toolExecutor = async () => {
+      return { content: largeContent, isError: false };
+    };
+
+    const loop = new AgentLoop(
+      provider,
+      'system',
+      { maxInputTokens: 180_000 },
+      dummyTools,
+      toolExecutor,
+    );
+    const events: AgentEvent[] = [];
+    const history = await loop.run([userMessage], collectEvents(events));
+
+    // The tool result user message is at index 2 in history
+    const toolResultMsg = history[2];
+    expect(toolResultMsg.role).toBe('user');
+
+    const toolResultBlock = toolResultMsg.content.find(
+      (b): b is Extract<ContentBlock, { type: 'tool_result' }> => b.type === 'tool_result',
+    );
+    expect(toolResultBlock).toBeDefined();
+
+    // Content should have been truncated (much shorter than the original 500K)
+    expect(toolResultBlock!.content.length).toBeLessThan(500_000);
+
+    // Content should end with the truncation suffix
+    expect(toolResultBlock!.content).toContain(
+      '[Content truncated',
+    );
+
+    // The second provider call should also have the truncated content in messages
+    const secondCallMessages = calls[1].messages;
+    const lastMsg = secondCallMessages[secondCallMessages.length - 1];
+    const sentBlock = lastMsg.content.find(
+      (b): b is Extract<ContentBlock, { type: 'tool_result' }> => b.type === 'tool_result',
+    );
+    expect(sentBlock).toBeDefined();
+    expect(sentBlock!.content.length).toBeLessThan(500_000);
+  });
+
+  // 31. Non-oversized tool results pass through unchanged
+  test('non-oversized tool results pass through unchanged', async () => {
+    const toolCallId = 'tool-small';
+    const smallContent = 'small content';
+
+    const { provider, calls } = createMockProvider([
+      toolUseResponse(toolCallId, 'read_file', { path: '/small.txt' }),
+      textResponse('Got it.'),
+    ]);
+
+    const toolExecutor = async () => {
+      return { content: smallContent, isError: false };
+    };
+
+    const loop = new AgentLoop(
+      provider,
+      'system',
+      { maxInputTokens: 180_000 },
+      dummyTools,
+      toolExecutor,
+    );
+    const events: AgentEvent[] = [];
+    const history = await loop.run([userMessage], collectEvents(events));
+
+    // The tool result user message is at index 2 in history
+    const toolResultMsg = history[2];
+    expect(toolResultMsg.role).toBe('user');
+
+    const toolResultBlock = toolResultMsg.content.find(
+      (b): b is Extract<ContentBlock, { type: 'tool_result' }> => b.type === 'tool_result',
+    );
+    expect(toolResultBlock).toBeDefined();
+
+    // Content should be exactly the original small content — no truncation
+    expect(toolResultBlock!.content).toBe(smallContent);
+
+    // The second provider call should also have the unchanged content
+    const secondCallMessages = calls[1].messages;
+    const lastMsg = secondCallMessages[secondCallMessages.length - 1];
+    const sentBlock = lastMsg.content.find(
+      (b): b is Extract<ContentBlock, { type: 'tool_result' }> => b.type === 'tool_result',
+    );
+    expect(sentBlock).toBeDefined();
+    expect(sentBlock!.content).toBe(smallContent);
+  });
+});