@amodalai/runtime 0.1.26 → 0.2.1

package/dist/src/agent/loop.test.js

@@ -0,0 +1,1594 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Agent Loop Tests
+ *
+ * Tests the state machine core:
+ * 1. Unit: each state handler produces expected transitions
+ * 2. Integration: runAgent() full conversation flow
+ * 3. Abort handling: clean shutdown on signal abort
+ * 4. Turn budget: max_turns enforcement
+ * 5. SSE event ordering (init first, done last, done always has usage)
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { z } from 'zod';
+import { SSEEventType } from '../types.js';
+import { runAgent, transition } from './loop.js';
+import { DEFAULT_LOOP_CONFIG } from './loop-types.js';
+// ---------------------------------------------------------------------------
+// Mock helpers
+// ---------------------------------------------------------------------------
+function makeMockLogger() {
+    return {
+        trace: vi.fn(),
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+        fatal: vi.fn(),
+        child: vi.fn().mockReturnThis(),
+    };
+}
+function makeUsage(overrides) {
+    return {
+        inputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0,
+        ...overrides,
+    };
+}
+function makeMockToolDef(overrides) {
+    return {
+        description: 'Test tool',
+        parameters: {},
+        execute: vi.fn().mockResolvedValue({ output: 'tool result' }),
+        readOnly: false,
+        metadata: { category: 'custom' },
+        ...overrides,
+    };
+}
+function makeMockRegistry(tools = {}) {
+    return {
+        register: vi.fn(),
+        get: vi.fn((name) => tools[name]),
+        getTools: vi.fn(() => tools),
+        names: vi.fn(() => Object.keys(tools)),
+        subset: vi.fn().mockReturnValue({}),
+        size: Object.keys(tools).length,
+    };
+}
+/**
+ * Create a mock StreamTextResult that yields the given stream events.
+ */
+function makeMockStream(events, text = 'Hello from the model') {
+    return {
+        textStream: (async function* () {
+            yield text;
+        })(),
+        fullStream: (async function* () {
+            for (const event of events) {
+                yield event;
+            }
+        })(),
+        usage: Promise.resolve(makeUsage({ inputTokens: 100, outputTokens: 50, totalTokens: 150 })),
+        text: Promise.resolve(text),
+    };
+}
+function makeMockContext(overrides) {
+    const logger = makeMockLogger();
+    return {
+        provider: {
+            model: 'test-model',
+            provider: 'test',
+            languageModel: {},
+            streamText: vi.fn(() => makeMockStream([
+                { type: 'text-delta', textDelta: 'Hello' },
+                { type: 'finish', usage: makeUsage({ inputTokens: 100, outputTokens: 50, totalTokens: 150 }) },
+            ])),
+            generateText: vi.fn(),
+        },
+        toolRegistry: makeMockRegistry(),
+        permissionChecker: {
+            check: vi.fn().mockReturnValue({ allowed: true }),
+        },
+        logger,
+        signal: new AbortController().signal,
+        sessionId: 'test-session',
+        user: { roles: ['user'] },
+        systemPrompt: 'You are a helpful assistant.',
+        messages: [],
+        usage: makeUsage(),
+        turnCount: 0,
+        maxTurns: 10,
+        maxContextTokens: 200_000,
+        config: { ...DEFAULT_LOOP_CONFIG },
+        compactionFailures: 0,
+        preExecutionCache: new Map(),
+        confirmedCallIds: new Set(),
+        disabledToolsUntilTurn: new Map(),
+        waitForConfirmation: vi.fn().mockResolvedValue(true),
+        buildToolContext: vi.fn().mockReturnValue({
+            request: vi.fn(),
+            store: vi.fn(),
+            env: vi.fn(),
+            log: vi.fn(),
+            user: { roles: [] },
+            signal: new AbortController().signal,
+            sessionId: 'test-session',
+        }),
+        ...overrides,
+    };
+}
+// ---------------------------------------------------------------------------
+// 1. Unit: transition dispatcher + exhaustive switch
+// ---------------------------------------------------------------------------
+describe('transition', () => {
+    it('dispatches thinking state to handleThinking', async () => {
+        const ctx = makeMockContext();
+        const state = { type: 'thinking', messages: [] };
+        const result = await transition(state, ctx);
+        // Should transition to streaming
+        expect(result.next.type).toBe('streaming');
+        expect(ctx.turnCount).toBe(1);
+    });
+    it('dispatches done state as pass-through', async () => {
+        const ctx = makeMockContext();
+        const state = { type: 'done', usage: makeUsage(), reason: 'model_stop' };
+        const result = await transition(state, ctx);
+        expect(result.next).toBe(state);
+        expect(result.effects).toEqual([]);
+    });
+});
+// ---------------------------------------------------------------------------
+// 2. State handler unit tests
+// ---------------------------------------------------------------------------
+describe('handleThinking (via transition)', () => {
+    it('increments turn count and starts streaming', async () => {
+        const ctx = makeMockContext();
+        const state = { type: 'thinking', messages: [] };
+        const result = await transition(state, ctx);
+        expect(result.next.type).toBe('streaming');
+        expect(ctx.turnCount).toBe(1);
+        expect(ctx.provider.streamText).toHaveBeenCalledWith(expect.objectContaining({
+            system: 'You are a helpful assistant.',
+            abortSignal: ctx.signal,
+        }));
+    });
+    it('passes tool schemas without execute functions to provider', async () => {
+        const testTool = makeMockToolDef({ description: 'Search repos' });
+        const registry = makeMockRegistry({ search: testTool });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        await transition({ type: 'thinking', messages: [] }, ctx);
+        const streamTextCall = vi.mocked(ctx.provider.streamText).mock.calls[0][0];
+        const tools = streamTextCall.tools;
+        expect(tools['search']).toBeDefined();
+        // Should have inputSchema (not parameters) and no execute
+        expect(tools['search']).toHaveProperty('inputSchema');
+        expect(tools['search']).not.toHaveProperty('execute');
+    });
+    it('detects tool call loops and forces done(loop_detected)', async () => {
+        // Build messages with 8 repeated tool calls for the same tool
+        const messages = [];
+        for (let i = 0; i < 8; i++) {
+            messages.push({
+                role: 'assistant',
+                content: [{ type: 'tool-call', toolCallId: `c${i}`, toolName: 'stuck_tool', input: { q: 'same' } }],
+            });
+            messages.push({
+                role: 'tool',
+                content: [{ type: 'tool-result', toolCallId: `c${i}`, toolName: 'stuck_tool', output: { type: 'text', value: 'error' } }],
+            });
+        }
+        const ctx = makeMockContext();
+        const result = await transition({ type: 'thinking', messages }, ctx);
+        expect(result.next.type).toBe('done');
+        if (result.next.type === 'done') {
+            expect(result.next.reason).toBe('loop_detected');
+        }
+        const errorEvents = result.effects.filter((e) => e.type === SSEEventType.Error);
+        expect(errorEvents.length).toBe(1);
+    });
+    it('detects loops with similar (not identical) parameters', async () => {
+        // Build messages where the same tool is called with slightly different
+        // params. Use a non-pagination key (retry_count) — pagination keys
+        // (offset/limit/page/cursor) are treated as iteration, not loops.
+        const messages = [];
+        for (let i = 0; i < 8; i++) {
+            messages.push({
+                role: 'assistant',
+                content: [{ type: 'tool-call', toolCallId: `c${i}`, toolName: 'search_api', input: { query: 'test', retry_count: i } }],
+            });
+            messages.push({
+                role: 'tool',
+                content: [{ type: 'tool-result', toolCallId: `c${i}`, toolName: 'search_api', output: { type: 'text', value: 'no results' } }],
+            });
+        }
+        const ctx = makeMockContext();
+        const result = await transition({ type: 'thinking', messages }, ctx);
+        // Same tool, same keys, >50% identical values → detected as loop
+        expect(result.next.type).toBe('done');
+        if (result.next.type === 'done') {
+            expect(result.next.reason).toBe('loop_detected');
+        }
+    });
+    it('does NOT detect pagination as a loop (offset/limit/page variants)', async () => {
+        // Agent walking a long file in chunks is legitimate iteration — same
+        // tool, same path, different offset. Must not trip the loop detector.
+        const messages = [];
+        for (let i = 0; i < 8; i++) {
+            messages.push({
+                role: 'assistant',
+                content: [{
+                        type: 'tool-call',
+                        toolCallId: `c${i}`,
+                        toolName: 'read_repo_file',
+                        input: { path: 'knowledge/big.md', offset: 1 + i * 2000, limit: 2000 },
+                    }],
+            });
+            messages.push({
+                role: 'tool',
+                content: [{ type: 'tool-result', toolCallId: `c${i}`, toolName: 'read_repo_file', output: { type: 'text', value: 'chunk' } }],
+            });
+        }
+        const ctx = makeMockContext();
+        const result = await transition({ type: 'thinking', messages }, ctx);
+        // Should NOT be done — the loop detector should have skipped these.
+        expect(result.next.type).not.toBe('done');
+    });
+    it('replaces old tool results with summarizer output when hook is set', async () => {
+        // Build 20 tool-result messages so clearing triggers (threshold=15 by default)
+        const messages = [];
+        for (let i = 0; i < 20; i++) {
+            messages.push({
+                role: 'tool',
+                content: [{
+                        type: 'tool-result',
+                        toolCallId: `c${i}`,
+                        toolName: 'search_api',
+                        output: { type: 'text', value: `result body ${i} with lots of content` },
+                    }],
+            });
+        }
+        const summarizer = vi.fn().mockResolvedValue('found 3 matching records');
+        const ctx = makeMockContext({ summarizeToolResult: summarizer });
+        await transition({ type: 'thinking', messages }, ctx);
+        // Summarizer should have been called for the cleared (non-kept) messages.
+        // threshold=15, keepRecent=5 → 15 cleared (all but the last 5).
+        expect(summarizer).toHaveBeenCalled();
+        expect(summarizer.mock.calls.length).toBe(15);
+        // Verify the summary is wired through — the messages passed to streamText
+        // should include the summary text in a cleared marker.
+        const streamTextCall = vi.mocked(ctx.provider.streamText).mock.calls[0][0];
+        const passedMessages = streamTextCall.messages;
+        const clearedMsg = passedMessages[0];
+        if (clearedMsg.role === 'tool' && Array.isArray(clearedMsg.content)) {
+            const part = clearedMsg.content[0];
+            if ('output' in part && part.output && typeof part.output === 'object' && 'value' in part.output) {
+                expect(String(part.output.value)).toContain('found 3 matching records');
+                expect(String(part.output.value)).toContain('search_api');
+            }
+        }
+    });
+    it('falls back to static marker when summarizer throws', async () => {
+        const messages = [];
+        for (let i = 0; i < 20; i++) {
+            messages.push({
+                role: 'tool',
+                content: [{
+                        type: 'tool-result',
+                        toolCallId: `c${i}`,
+                        toolName: 'flaky_tool',
+                        output: { type: 'text', value: `body ${i}` },
+                    }],
+            });
+        }
+        const summarizer = vi.fn().mockRejectedValue(new Error('haiku unavailable'));
+        const ctx = makeMockContext({ summarizeToolResult: summarizer });
+        await transition({ type: 'thinking', messages }, ctx);
+        // Summarizer was called but threw; we should still proceed with static marker
+        expect(summarizer).toHaveBeenCalled();
+        const streamTextCall = vi.mocked(ctx.provider.streamText).mock.calls[0][0];
+        const clearedMsg = streamTextCall.messages[0];
+        if (clearedMsg.role === 'tool' && Array.isArray(clearedMsg.content)) {
+            const part = clearedMsg.content[0];
+            if ('output' in part && part.output && typeof part.output === 'object' && 'value' in part.output) {
+                expect(String(part.output.value)).toContain('Tool result cleared');
+            }
+        }
+        // The failure should have been logged
+        expect(ctx.logger.warn).toHaveBeenCalledWith('tool_result_summarization_failed', expect.objectContaining({ tool: 'flaky_tool' }));
+    });
+    it('skips already-cleared messages (idempotent)', async () => {
+        // Already-cleared messages keep their original toolCallId (otherwise
+        // providers reject "orphaned" assistant tool-calls). Detection is by
+        // output-value prefix: "[Tool result cleared..." or "[Summary of ...".
+        const messages = [];
+        for (let i = 0; i < 20; i++) {
+            messages.push({
+                role: 'tool',
+                content: [{
+                        type: 'tool-result',
+                        toolCallId: `c${i}`,
+                        toolName: 'search_api',
+                        // First 15 are already-cleared (marker prefix); last 5 are fresh
+                        output: {
+                            type: 'text',
+                            value: i < 15 ? '[Tool result cleared to save context space]' : `body ${i}`,
+                        },
+                    }],
+            });
+        }
+        const summarizer = vi.fn().mockResolvedValue('summary');
+        const ctx = makeMockContext({ summarizeToolResult: summarizer });
+        await transition({ type: 'thinking', messages }, ctx);
+        // Clearing kicks in (20 > 15), but all 15 candidates are already cleared.
+        // Summarizer should NOT be called for already-cleared messages.
+        expect(summarizer).not.toHaveBeenCalled();
+    });
+    it('escalates at loopEscalationThreshold: stronger warn + removes looping tool', async () => {
+        // Build messages with 5 tool calls so count hits escalation (default=5)
+        // but not hard-stop (default=8).
+        const messages = [];
+        for (let i = 0; i < 5; i++) {
+            messages.push({
+                role: 'assistant',
+                content: [{ type: 'tool-call', toolCallId: `c${i}`, toolName: 'stuck_api', input: { q: 'same' } }],
+            });
+            messages.push({
+                role: 'tool',
+                content: [{ type: 'tool-result', toolCallId: `c${i}`, toolName: 'stuck_api', output: { type: 'text', value: 'no progress' } }],
+            });
+        }
+        // Registry has both the looping tool and another tool
+        const stuckTool = makeMockToolDef({ description: 'Stuck tool' });
+        const otherTool = makeMockToolDef({ description: 'Other tool' });
+        const registry = makeMockRegistry({ stuck_api: stuckTool, other_tool: otherTool });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        const result = await transition({ type: 'thinking', messages }, ctx);
+        // Should still stream (not hard-stop)
+        expect(result.next.type).toBe('streaming');
+        // The escalation-level warn should have been logged
+        expect(ctx.logger.warn).toHaveBeenCalledWith('agent_loop_escalation', expect.objectContaining({ tool: 'stuck_api', count: 5 }));
+        // The looping tool should be EXCLUDED from this turn's tool set
+        const streamTextCall = vi.mocked(ctx.provider.streamText).mock.calls[0][0];
+        const passedTools = streamTextCall.tools;
+        expect(passedTools['stuck_api']).toBeUndefined();
+        expect(passedTools['other_tool']).toBeDefined();
+        // Escalation message should be appended
+        const lastMsg = streamTextCall.messages[streamTextCall.messages.length - 1];
+        expect(lastMsg.role).toBe('user');
+        if (typeof lastMsg.content === 'string') {
+            expect(lastMsg.content).toContain('temporarily disabled');
+            expect(lastMsg.content).toContain('stuck_api');
+        }
+        // The looping tool should be registered in the cooldown map, not just
+        // filtered once-off — so subsequent turns also skip it.
+        expect(ctx.disabledToolsUntilTurn.has('stuck_api')).toBe(true);
+    });
+    it('escalation cooldown keeps tool disabled across subsequent turns', async () => {
+        // Simulate a session where escalation fires at turn 5 with default
+        // cooldown of 3, then the agent moves on. The looping tool should be
+        // excluded from turns 5-7 and return at turn 8.
+        const stuckTool = makeMockToolDef({ description: 'Stuck tool' });
+        const otherTool = makeMockToolDef({ description: 'Other tool' });
+        const registry = makeMockRegistry({ stuck_api: stuckTool, other_tool: otherTool });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        // Pre-populate the cooldown as if escalation fired at turn 5
+        ctx.turnCount = 4; // next turn will be 5
+        ctx.disabledToolsUntilTurn.set('stuck_api', 8); // disable until turn 8
+        // Turn 5: tool still disabled
+        await transition({ type: 'thinking', messages: [] }, ctx);
+        let streamTextCall = vi.mocked(ctx.provider.streamText).mock.calls[0][0];
+        let passedTools = streamTextCall.tools;
+        expect(passedTools['stuck_api']).toBeUndefined();
+        expect(passedTools['other_tool']).toBeDefined();
+        // Turn 6: still disabled
+        await transition({ type: 'thinking', messages: [] }, ctx);
+        streamTextCall = vi.mocked(ctx.provider.streamText).mock.calls[1][0];
+        passedTools = streamTextCall.tools;
+        expect(passedTools['stuck_api']).toBeUndefined();
+        // Turn 7: still disabled (turnCount=7, untilTurn=8)
+        await transition({ type: 'thinking', messages: [] }, ctx);
+        streamTextCall = vi.mocked(ctx.provider.streamText).mock.calls[2][0];
+        passedTools = streamTextCall.tools;
+        expect(passedTools['stuck_api']).toBeUndefined();
+        // Turn 8: cooldown expired — tool back in the set
+        await transition({ type: 'thinking', messages: [] }, ctx);
+        streamTextCall = vi.mocked(ctx.provider.streamText).mock.calls[3][0];
+        passedTools = streamTextCall.tools;
+        expect(passedTools['stuck_api']).toBeDefined();
+        // Map should be cleaned up after expiry
+        expect(ctx.disabledToolsUntilTurn.has('stuck_api')).toBe(false);
+    });
+    it('injects warning when tool called 3+ times', async () => {
+        const messages = [];
+        for (let i = 0; i < 3; i++) {
+            messages.push({
+                role: 'assistant',
+                content: [{ type: 'tool-call', toolCallId: `c${i}`, toolName: 'flaky_api', input: {} }],
+            });
+            messages.push({
+                role: 'tool',
+                content: [{ type: 'tool-result', toolCallId: `c${i}`, toolName: 'flaky_api', output: { type: 'text', value: 'fail' } }],
+            });
+        }
+        const ctx = makeMockContext();
+        const result = await transition({ type: 'thinking', messages }, ctx);
+        // Should still stream (not stop), but the messages passed to streamText
+        // should include a warning
+        expect(result.next.type).toBe('streaming');
+        const streamTextCall = vi.mocked(ctx.provider.streamText).mock.calls[0][0];
+        const lastMsg = streamTextCall.messages[streamTextCall.messages.length - 1];
+        expect(lastMsg.role).toBe('user');
+        if (typeof lastMsg.content === 'string') {
+            expect(lastMsg.content).toContain('flaky_api');
+            expect(lastMsg.content).toContain('3 times');
+        }
+    });
+});
+describe('handleStreaming (via transition)', () => {
+    it('text-only response transitions to done(model_stop)', async () => {
+        const stream = makeMockStream([
+            { type: 'text-delta', textDelta: 'Hello!' },
+            { type: 'finish', usage: makeUsage({ inputTokens: 50, outputTokens: 20, totalTokens: 70 }) },
+        ]);
+        const ctx = makeMockContext();
+        const state = { type: 'streaming', stream, pendingToolCalls: [] };
+        const result = await transition(state, ctx);
+        expect(result.next.type).toBe('done');
+        if (result.next.type === 'done') {
+            expect(result.next.reason).toBe('model_stop');
+        }
+        // Should have emitted text_delta events
+        const textEvents = result.effects.filter((e) => e.type === SSEEventType.TextDelta);
+        expect(textEvents.length).toBeGreaterThan(0);
+    });
+    it('tool call response transitions to executing', async () => {
+        const stream = makeMockStream([
+            { type: 'text-delta', textDelta: 'Let me search.' },
+            {
+                type: 'tool-call',
+                toolCallId: 'call-1',
+                toolName: 'search',
+                args: { query: 'test' },
+            },
+            { type: 'finish', usage: makeUsage({ inputTokens: 50, outputTokens: 20, totalTokens: 70 }) },
+        ], 'Let me search.');
+        const ctx = makeMockContext();
+        const state = { type: 'streaming', stream, pendingToolCalls: [] };
+        const result = await transition(state, ctx);
+        expect(result.next.type).toBe('executing');
+        if (result.next.type === 'executing') {
+            expect(result.next.current.toolCallId).toBe('call-1');
+            expect(result.next.current.toolName).toBe('search');
+            expect(result.next.current.args).toEqual({ query: 'test' });
+        }
+    });
+    it('tracks token usage from finish events', async () => {
+        const stream = makeMockStream([
+            { type: 'finish', usage: makeUsage({ inputTokens: 100, outputTokens: 50, totalTokens: 150 }) },
+        ]);
+        const ctx = makeMockContext();
+        const state = { type: 'streaming', stream, pendingToolCalls: [] };
+        await transition(state, ctx);
+        expect(ctx.usage.inputTokens).toBe(100);
+        expect(ctx.usage.outputTokens).toBe(50);
+    });
+    it('stream error transitions to done(error)', async () => {
+        const stream = makeMockStream([
+            { type: 'error', error: new Error('Provider failed') },
+        ]);
+        const ctx = makeMockContext();
+        const state = { type: 'streaming', stream, pendingToolCalls: [] };
+        const result = await transition(state, ctx);
+        expect(result.next.type).toBe('done');
+        if (result.next.type === 'done') {
+            expect(result.next.reason).toBe('error');
+        }
+        // Should have emitted an error SSE event
+        const errorEvents = result.effects.filter((e) => e.type === SSEEventType.Error);
+        expect(errorEvents.length).toBe(1);
+    });
+    it('pre-executes read-only tools during streaming', async () => {
+        const readOnlyTool = makeMockToolDef({
+            readOnly: true,
+            execute: vi.fn().mockResolvedValue('cached result'),
+        });
+        const registry = makeMockRegistry({ lookup: readOnlyTool });
+        const stream = makeMockStream([
+            { type: 'tool-call', toolCallId: 'call-ro', toolName: 'lookup', args: { id: '1' } },
+            { type: 'finish', usage: makeUsage() },
+        ], '');
+        const ctx = makeMockContext({ toolRegistry: registry });
+        const state = { type: 'streaming', stream, pendingToolCalls: [] };
+        await transition(state, ctx);
+        // Pre-execution cache should have an entry
+        expect(ctx.preExecutionCache.has('call-ro')).toBe(true);
+    });
+    it('logs pre-execution errors on abort instead of swallowing silently', async () => {
+        const failingTool = makeMockToolDef({
+            readOnly: true,
+            execute: vi.fn().mockRejectedValue(new Error('tool crashed')),
+        });
+        const registry = makeMockRegistry({ broken_lookup: failingTool });
+        const stream = makeMockStream([
+            { type: 'tool-call', toolCallId: 'call-fail', toolName: 'broken_lookup', args: {} },
+            { type: 'finish', usage: makeUsage() },
+        ], '');
+        const ctx = makeMockContext({ toolRegistry: registry });
+        const state = { type: 'streaming', stream, pendingToolCalls: [] };
+        await transition(state, ctx);
+        // Wait for the pre-execution promise to settle (it rejects)
+        const cached = ctx.preExecutionCache.get('call-fail');
+        expect(cached).toBeDefined();
+        // The .catch() handler should have logged, not thrown
+        await expect(cached).rejects.toThrow('tool crashed');
+        // The suppression handler should have logged the error
+        expect(ctx.logger.debug).toHaveBeenCalledWith('preexec_suppressed', expect.objectContaining({
+            tool: 'broken_lookup',
+            error: 'tool crashed',
+        }));
+    });
+});
+describe('handleExecuting (via transition)', () => {
+    it('executes a tool and transitions to thinking when queue empty', async () => {
+        const searchTool = makeMockToolDef({
+            execute: vi.fn().mockResolvedValue({ repos: ['amodal'] }),
+        });
+        const registry = makeMockRegistry({ search: searchTool });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        const state = {
+            type: 'executing',
+            queue: [],
+            current: { toolCallId: 'call-1', toolName: 'search', args: { q: 'test' } },
+            results: [],
+        };
+        const result = await transition(state, ctx);
+        expect(result.next.type).toBe('thinking');
+        expect(searchTool.execute).toHaveBeenCalledWith({ q: 'test' }, expect.objectContaining({ sessionId: 'test-session' }));
+        // Should emit tool_call_start and tool_call_result SSE events
+        const startEvents = result.effects.filter((e) => e.type === SSEEventType.ToolCallStart);
+        const resultEvents = result.effects.filter((e) => e.type === SSEEventType.ToolCallResult);
+        expect(startEvents.length).toBe(1);
+        expect(resultEvents.length).toBe(1);
+    });
+    it('routes requiresConfirmation tools through CONFIRMING on first pass', async () => {
+        const destructiveTool = makeMockToolDef({
+            execute: vi.fn().mockResolvedValue({ deleted: true }),
+            requiresConfirmation: true,
+        });
+        const registry = makeMockRegistry({ delete_repo: destructiveTool });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        const state = {
+            type: 'executing',
+            queue: [],
+            current: { toolCallId: 'call-danger', toolName: 'delete_repo', args: { name: 'foo' } },
+            results: [],
+        };
+        const result = await transition(state, ctx);
+        expect(result.next.type).toBe('confirming');
+        expect(destructiveTool.execute).not.toHaveBeenCalled();
+        // ConfirmationRequired SSE event should be emitted
+        const confirmEvents = result.effects.filter((e) => e.type === SSEEventType.ConfirmationRequired);
+        expect(confirmEvents.length).toBe(1);
+    });
+    it('executes requiresConfirmation tools after approval (no re-confirm loop)', async () => {
+        const destructiveTool = makeMockToolDef({
+            execute: vi.fn().mockResolvedValue({ deleted: true }),
+            requiresConfirmation: true,
+        });
+        const registry = makeMockRegistry({ delete_repo: destructiveTool });
+        // Pre-populate confirmedCallIds as if CONFIRMING already approved this call
+        const ctx = makeMockContext({ toolRegistry: registry });
+        ctx.confirmedCallIds.add('call-approved');
+        const state = {
+            type: 'executing',
+            queue: [],
+            current: { toolCallId: 'call-approved', toolName: 'delete_repo', args: { name: 'foo' } },
+            results: [],
+        };
+        const result = await transition(state, ctx);
+        // Should execute this time, not route back to CONFIRMING
+        expect(result.next.type).toBe('thinking');
+        expect(destructiveTool.execute).toHaveBeenCalledTimes(1);
+    });
+    it('connection tool does NOT re-prompt after confirmedCallIds marks the call', async () => {
+        // Regression test for the latent infinite-loop bug: a connection tool
+        // whose ACL gate returns requiresConfirmation=true used to re-route back
+        // to CONFIRMING on every pass, since the permission checker has no
+        // notion of "already approved." confirmedCallIds fixes this.
+        const connectionTool = makeMockToolDef({
+            execute: vi.fn().mockResolvedValue({ ok: true }),
+            metadata: { category: 'connection', connection: 'github' },
+        });
+        const registry = makeMockRegistry({ request: connectionTool });
+        const ctx = makeMockContext({
+            toolRegistry: registry,
+            permissionChecker: {
+                check: vi.fn().mockReturnValue({
+                    allowed: true,
+                    requiresConfirmation: true,
+                    reason: 'Write to github requires confirmation',
+                }),
+            },
+        });
+        // Simulate: CONFIRMING has already approved this call
+        ctx.confirmedCallIds.add('call-gh-write');
+        const state = {
+            type: 'executing',
+            queue: [],
+            current: {
+                toolCallId: 'call-gh-write',
+                toolName: 'request',
+                args: { method: 'POST', endpoint: '/repos/foo', intent: 'confirmed_write' },
+            },
+            results: [],
+        };
+        const result = await transition(state, ctx);
+        // Should execute the connection tool instead of re-routing to CONFIRMING
+        expect(result.next.type).toBe('thinking');
+        expect(connectionTool.execute).toHaveBeenCalledTimes(1);
+        // No ConfirmationRequired SSE event should have been emitted
+        const confirmEvents = result.effects.filter((e) => e.type === SSEEventType.ConfirmationRequired);
+        expect(confirmEvents.length).toBe(0);
+    });
+    it('transitions to compacting when context exceeds threshold', async () => {
+        const tool = makeMockToolDef({
+            // Return a large result to inflate context
+            execute: vi.fn().mockResolvedValue('x'.repeat(10_000)),
+        });
+        const registry = makeMockRegistry({ big_tool: tool });
+        const ctx = makeMockContext({
+            toolRegistry: registry,
+            maxContextTokens: 1000, // Very small budget
+            config: { ...DEFAULT_LOOP_CONFIG, compactThreshold: 0.7 },
+        });
+        // Pre-populate messages to be near the threshold
+        ctx.messages = Array.from({ length: 20 }, () => ({
+            role: 'user',
+            content: 'x'.repeat(200),
+        }));
+        const state = {
+            type: 'executing',
+            queue: [],
+            current: { toolCallId: 'call-1', toolName: 'big_tool', args: {} },
+            results: [],
+        };
+        const result = await transition(state, ctx);
+        expect(result.next.type).toBe('compacting');
+        if (result.next.type === 'compacting') {
+            expect(result.next.estimatedTokens).toBeGreaterThan(0);
+        }
+        expect(ctx.logger.info).toHaveBeenCalledWith('context_compaction_triggered', expect.objectContaining({
+            session: 'test-session',
+        }));
+    });
+    it('continues to next tool when queue has more items', async () => {
+        const tool = makeMockToolDef();
+        const registry = makeMockRegistry({ tool_a: tool, tool_b: tool });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        const state = {
+            type: 'executing',
+            queue: [{ toolCallId: 'call-2', toolName: 'tool_b', args: {} }],
+            current: { toolCallId: 'call-1', toolName: 'tool_a', args: {} },
+            results: [],
+        };
+        const result = await transition(state, ctx);
+        expect(result.next.type).toBe('executing');
+        if (result.next.type === 'executing') {
+            expect(result.next.current.toolCallId).toBe('call-2');
+            expect(result.next.queue).toEqual([]);
+        }
+    });
+    it('returns error result for unknown tool', async () => {
+        const ctx = makeMockContext();
+        const state = {
+            type: 'executing',
+            queue: [],
+            current: { toolCallId: 'call-1', toolName: 'nonexistent', args: {} },
+            results: [],
+        };
+        const result = await transition(state, ctx);
+        // Should transition to thinking (agent can recover)
+        expect(result.next.type).toBe('thinking');
+        // Messages should contain the error tool result
+        expect(ctx.messages.length).toBeGreaterThan(0);
+    });
+    it('handles tool execution error as continue site', async () => {
+        const failingTool = makeMockToolDef({
+            execute: vi.fn().mockRejectedValue(new Error('API rate limit')),
+        });
+        const registry = makeMockRegistry({ api_call: failingTool });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        const state = {
+            type: 'executing',
+            queue: [],
+            current: { toolCallId: 'call-1', toolName: 'api_call', args: {} },
+            results: [],
+        };
+        const result = await transition(state, ctx);
+        // Should NOT crash — transitions to thinking so model can recover
+        expect(result.next.type).toBe('thinking');
+        // Should emit tool_call_result with error status
+        const resultEvents = result.effects.filter((e) => e.type === SSEEventType.ToolCallResult);
+        expect(resultEvents.length).toBe(1);
+        // Logger should have recorded the error
+        expect(ctx.logger.error).toHaveBeenCalledWith('tool_execution_error', expect.objectContaining({
+            tool: 'api_call',
+        }));
+    });
+    it('rejects hallucinated args that fail schema validation', async () => {
+        const { z } = await import('zod');
+        const strictTool = makeMockToolDef({
+            parameters: z.object({ query: z.string(), limit: z.number().int().positive() }),
+        });
+        const registry = makeMockRegistry({ search: strictTool });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        const state = {
+            type: 'executing',
+            queue: [],
+            current: { toolCallId: 'call-1', toolName: 'search', args: { query: 123, limit: -5 } },
+            results: [],
+        };
+        const result = await transition(state, ctx);
+        // Should recover — transition to thinking with error message for the model
+        expect(result.next.type).toBe('thinking');
+        expect(ctx.logger.warn).toHaveBeenCalledWith('tool_args_invalid', expect.objectContaining({
+            tool: 'search',
+        }));
+        // Should NOT have called execute
+        expect(strictTool.execute).not.toHaveBeenCalled();
+    });
+    it('sanitizes sensitive parameters in SSE events', async () => {
+        const tool = makeMockToolDef();
+        const registry = makeMockRegistry({ auth_tool: tool });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        const state = {
+            type: 'executing',
+            queue: [],
+            current: {
+                toolCallId: 'call-1',
+                toolName: 'auth_tool',
+                args: { api_key: 'sk-secret123', query: 'hello' },
+            },
+            results: [],
+        };
+        const result = await transition(state, ctx);
+        const startEvent = result.effects.find((e) => e.type === SSEEventType.ToolCallStart);
+        expect(startEvent).toBeDefined();
+        if (startEvent && 'parameters' in startEvent) {
+            const params = startEvent.parameters;
+            expect(params['api_key']).toBe('[REDACTED]');
+            expect(params['query']).toBe('hello');
+        }
+    });
+    it('snips oversized tool results keeping head and tail', async () => {
+        const largeOutput = 'A'.repeat(25_000); // Exceeds 20K default maxResultSize
+        const tool = makeMockToolDef({
+            execute: vi.fn().mockResolvedValue(largeOutput),
+        });
+        const registry = makeMockRegistry({ big_api: tool });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        const state = {
+            type: 'executing',
+            queue: [],
+            current: { toolCallId: 'call-1', toolName: 'big_api', args: {} },
+            results: [],
+        };
+        await transition(state, ctx);
+        // The message appended should contain the snipped content
+        const lastMsg = ctx.messages[ctx.messages.length - 1];
+        expect(lastMsg.role).toBe('tool');
+        if (Array.isArray(lastMsg.content) && 'output' in lastMsg.content[0]) {
+            const output = lastMsg.content[0].output;
+            const value = typeof output === 'object' && output !== null && 'value' in output
+                ? String(output.value)
+                : '';
+            expect(value).toContain('snipped');
+            expect(value.length).toBeLessThan(largeOutput.length);
+        }
+        expect(ctx.logger.info).toHaveBeenCalledWith('tool_result_snipped', expect.objectContaining({
+            tool: 'big_api',
+            originalSize: 25_000,
+        }));
+    });
+    it('uses pre-execution cache for read-only tools', async () => {
+        const readTool = makeMockToolDef({ readOnly: true });
+        const registry = makeMockRegistry({ read_data: readTool });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        // Simulate pre-execution cache from streaming phase
+        ctx.preExecutionCache.set('call-cached', Promise.resolve({ data: 'cached' }));
+        const state = {
+            type: 'executing',
+            queue: [],
+            current: { toolCallId: 'call-cached', toolName: 'read_data', args: {} },
+            results: [],
+        };
+        await transition(state, ctx);
+        // The cached result should be used — tool.execute should NOT be called again
+        expect(readTool.execute).not.toHaveBeenCalled();
+    });
+    // -------------------------------------------------------------------------
+    // Parallel tool calls: batch contiguous read-only calls
+    // -------------------------------------------------------------------------
+    it('batches contiguous read-only calls and runs them concurrently', async () => {
+        // Two read-only tools. Each sleeps before resolving. If batched in
+        // parallel, total wall time ≈ max(sleep). If sequential, ≈ sum(sleep).
+        const sleep = (ms) => new Promise((r) => setTimeout(() => r('ok'), ms));
+        const readA = makeMockToolDef({
+            readOnly: true,
+            execute: vi.fn(() => sleep(50)),
+        });
+        const readB = makeMockToolDef({
+            readOnly: true,
+            execute: vi.fn(() => sleep(50)),
+        });
+        const registry = makeMockRegistry({ read_a: readA, read_b: readB });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        const state = {
+            type: 'executing',
+            queue: [{ toolCallId: 'call-b', toolName: 'read_b', args: {} }],
+            current: { toolCallId: 'call-a', toolName: 'read_a', args: {} },
+            results: [],
+        };
+        const startedAt = Date.now();
+        const result = await transition(state, ctx);
+        const elapsed = Date.now() - startedAt;
+        // Both executed
+        expect(readA.execute).toHaveBeenCalledTimes(1);
+        expect(readB.execute).toHaveBeenCalledTimes(1);
+        // Parallel: should finish in roughly one sleep, well under the sum
+        expect(elapsed).toBeLessThan(90);
+        // Batch drained the queue and transitioned to thinking in one step
+        expect(result.next.type).toBe('thinking');
+        // Both results appended to messages
+        const toolMessages = ctx.messages.filter((m) => m.role === 'tool');
+        expect(toolMessages).toHaveLength(2);
+        // Per-call SSE events emitted (2 start + 2 result)
+        const starts = result.effects.filter((e) => e.type === SSEEventType.ToolCallStart);
+        const results = result.effects.filter((e) => e.type === SSEEventType.ToolCallResult);
+        expect(starts).toHaveLength(2);
+        expect(results).toHaveLength(2);
+    });
+    it('stops batching at the first write (non-readOnly) tool', async () => {
+        const readTool = makeMockToolDef({ readOnly: true, execute: vi.fn().mockResolvedValue('r') });
+        const writeTool = makeMockToolDef({ readOnly: false, execute: vi.fn().mockResolvedValue('w') });
+        const registry = makeMockRegistry({ read: readTool, write: writeTool });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        const state = {
+            type: 'executing',
+            queue: [
+                { toolCallId: 'call-read-2', toolName: 'read', args: {} },
+                { toolCallId: 'call-write', toolName: 'write', args: {} },
+                { toolCallId: 'call-read-3', toolName: 'read', args: {} },
+            ],
+            current: { toolCallId: 'call-read-1', toolName: 'read', args: {} },
+            results: [],
+        };
+        const result = await transition(state, ctx);
+        // Batched the two leading reads; the write stopped the batch
+        expect(readTool.execute).toHaveBeenCalledTimes(2);
+        expect(writeTool.execute).not.toHaveBeenCalled();
+        // Next state should process the write sequentially
+        expect(result.next.type).toBe('executing');
+        if (result.next.type === 'executing') {
+            expect(result.next.current.toolCallId).toBe('call-write');
+            expect(result.next.queue).toHaveLength(1);
+            expect(result.next.queue[0].toolCallId).toBe('call-read-3');
+        }
+    });
+    it('does not batch when the current call is a write', async () => {
+        const writeTool = makeMockToolDef({ readOnly: false, execute: vi.fn().mockResolvedValue('w') });
+        const readTool = makeMockToolDef({ readOnly: true, execute: vi.fn().mockResolvedValue('r') });
+        const registry = makeMockRegistry({ write: writeTool, read: readTool });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        const state = {
+            type: 'executing',
+            queue: [{ toolCallId: 'call-read', toolName: 'read', args: {} }],
+            current: { toolCallId: 'call-write', toolName: 'write', args: {} },
+            results: [],
+        };
+        const result = await transition(state, ctx);
+        // Only write executes; read stays in queue for the next transition
+        expect(writeTool.execute).toHaveBeenCalledTimes(1);
+        expect(readTool.execute).not.toHaveBeenCalled();
+        expect(result.next.type).toBe('executing');
+        if (result.next.type === 'executing') {
+            expect(result.next.current.toolCallId).toBe('call-read');
+        }
+    });
+    it('does not batch connection tools (any call could transition to CONFIRMING)', async () => {
+        const connRead = makeMockToolDef({
+            readOnly: true,
+            execute: vi.fn().mockResolvedValue('x'),
+            metadata: { category: 'connection', connection: 'github' },
+        });
+        const registry = makeMockRegistry({ request: connRead });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        const state = {
+            type: 'executing',
+            queue: [{ toolCallId: 'call-2', toolName: 'request', args: { method: 'GET', endpoint: '/x' } }],
+            current: { toolCallId: 'call-1', toolName: 'request', args: { method: 'GET', endpoint: '/y' } },
+            results: [],
+        };
+        const result = await transition(state, ctx);
+        // Only the first ran; the second stays queued for its own ACL check
+        expect(connRead.execute).toHaveBeenCalledTimes(1);
+        expect(result.next.type).toBe('executing');
+    });
+    it('does not batch read-only tools that require confirmation', async () => {
+        const gated = makeMockToolDef({
+            readOnly: true,
+            requiresConfirmation: true,
+            execute: vi.fn().mockResolvedValue('x'),
+        });
+        const registry = makeMockRegistry({ gated });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        const state = {
+            type: 'executing',
+            queue: [{ toolCallId: 'call-2', toolName: 'gated', args: {} }],
+            current: { toolCallId: 'call-1', toolName: 'gated', args: {} },
+            results: [],
+        };
+        const result = await transition(state, ctx);
+        // Routes to CONFIRMING, no execution yet
+        expect(result.next.type).toBe('confirming');
+        expect(gated.execute).not.toHaveBeenCalled();
+    });
+    it('a failure in one batched call does not block the others', async () => {
+        const good = makeMockToolDef({ readOnly: true, execute: vi.fn().mockResolvedValue('ok') });
+        const bad = makeMockToolDef({
+            readOnly: true,
+            execute: vi.fn().mockRejectedValue(new Error('boom')),
+        });
+        const registry = makeMockRegistry({ good, bad });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        const state = {
+            type: 'executing',
+            queue: [
+                { toolCallId: 'call-bad', toolName: 'bad', args: {} },
+                { toolCallId: 'call-good-2', toolName: 'good', args: {} },
+            ],
+            current: { toolCallId: 'call-good-1', toolName: 'good', args: {} },
+            results: [],
+        };
+        const result = await transition(state, ctx);
+        // All three tried, failure surfaced as an error tool-result for the bad one
+        expect(good.execute).toHaveBeenCalledTimes(2);
+        expect(bad.execute).toHaveBeenCalledTimes(1);
+        expect(result.next.type).toBe('thinking');
+        const toolMessages = ctx.messages.filter((m) => m.role === 'tool');
+        expect(toolMessages).toHaveLength(3);
+        // Error result is present in the SSE stream
+        const errorEvents = result.effects.filter((e) => e.type === SSEEventType.ToolCallResult && e.status === 'error');
+        expect(errorEvents).toHaveLength(1);
+    });
+});
+describe('handleConfirming (via transition)', () => {
+    it('approved confirmation resumes executing', async () => {
+        const ctx = makeMockContext({
+            waitForConfirmation: vi.fn().mockResolvedValue(true),
+        });
+        const state = {
+            type: 'confirming',
+            call: { toolCallId: 'call-1', toolName: 'delete_item', args: { id: '123' } },
+            remainingQueue: [],
+        };
+        const result = await transition(state, ctx);
+        expect(result.next.type).toBe('executing');
+        if (result.next.type === 'executing') {
+            expect(result.next.current.toolCallId).toBe('call-1');
+        }
+    });
+    it('denied confirmation transitions to thinking with denial message', async () => {
+        const ctx = makeMockContext({
+            waitForConfirmation: vi.fn().mockResolvedValue(false),
+        });
+        const state = {
+            type: 'confirming',
+            call: { toolCallId: 'call-1', toolName: 'delete_item', args: { id: '123' } },
+            remainingQueue: [],
+        };
+        const result = await transition(state, ctx);
+        expect(result.next.type).toBe('thinking');
+        // A denial message should have been appended
+        expect(ctx.messages.length).toBeGreaterThan(0);
+    });
+    it('approved confirmation marks the callId in ctx.confirmedCallIds', async () => {
+        const ctx = makeMockContext({
+            waitForConfirmation: vi.fn().mockResolvedValue(true),
+        });
+        const state = {
+            type: 'confirming',
+            call: { toolCallId: 'call-XYZ', toolName: 'delete_item', args: { id: '123' } },
+            remainingQueue: [],
+        };
+        await transition(state, ctx);
+        expect(ctx.confirmedCallIds.has('call-XYZ')).toBe(true);
+    });
+    it('denied confirmation does NOT mark callId as confirmed', async () => {
+        const ctx = makeMockContext({
+            waitForConfirmation: vi.fn().mockResolvedValue(false),
+        });
+        const state = {
+            type: 'confirming',
+            call: { toolCallId: 'call-DENIED', toolName: 'delete_item', args: { id: '123' } },
+            remainingQueue: [],
+        };
+        await transition(state, ctx);
+        expect(ctx.confirmedCallIds.has('call-DENIED')).toBe(false);
+    });
+    it('intercepts dispatch_task and transitions to DISPATCHING', async () => {
+        const dispatchTool = {
+            description: 'Dispatch sub-task',
+            parameters: z.object({ agent_name: z.string(), tools: z.array(z.string()), prompt: z.string() }),
+            execute: vi.fn(),
+            readOnly: false,
+            metadata: { category: 'system' },
+        };
+        const registry = makeMockRegistry({ dispatch_task: dispatchTool });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        const state = {
+            type: 'executing',
+            queue: [],
+            current: {
+                toolCallId: 'tc-dispatch',
+                toolName: 'dispatch_task',
+                args: { agent_name: 'fetcher', tools: ['request'], prompt: 'Fetch data' },
+            },
+            results: [],
+        };
+        const result = await transition(state, ctx);
+        // Should transition to DISPATCHING, not execute the tool
+        expect(result.next.type).toBe('dispatching');
+        if (result.next.type === 'dispatching') {
+            expect(result.next.task.agentName).toBe('fetcher');
+            expect(result.next.task.toolSubset).toEqual(['request']);
+            expect(result.next.task.prompt).toBe('Fetch data');
+            expect(result.next.toolCallId).toBe('tc-dispatch');
+        }
+        // Should emit ToolCallStart but NOT call execute
+        const startEvents = result.effects.filter((e) => e.type === SSEEventType.ToolCallStart);
+        expect(startEvents.length).toBe(1);
+        expect(dispatchTool.execute).not.toHaveBeenCalled();
+    });
+    it('strips dispatch_task from child tool subset', async () => {
+        const dispatchTool = {
+            description: 'Dispatch',
+            parameters: z.object({ agent_name: z.string(), tools: z.array(z.string()), prompt: z.string() }),
+            execute: vi.fn(),
+            readOnly: false,
+            metadata: { category: 'system' },
+        };
+        const registry = makeMockRegistry({ dispatch_task: dispatchTool });
+        const ctx = makeMockContext({ toolRegistry: registry });
+        const state = {
+            type: 'executing',
+            queue: [],
+            current: {
+                toolCallId: 'tc-d',
+                toolName: 'dispatch_task',
+                args: { agent_name: 'child', tools: ['request', 'dispatch_task', 'query_store'], prompt: 'Go' },
+            },
+            results: [],
+        };
+        const result = await transition(state, ctx);
+        if (result.next.type === 'dispatching') {
+            expect(result.next.task.toolSubset).toEqual(['request', 'query_store']);
+            expect(result.next.task.toolSubset).not.toContain('dispatch_task');
+        }
+    });
+});
+describe('handleCompacting (via transition)', () => {
+    it('summarizes old messages and keeps recent turns', async () => {
+        // Build a conversation with enough turns to compact
+        const messages = [];
+        for (let i = 0; i < 10; i++) {
+            messages.push({ role: 'user', content: `Question ${i}` });
+            messages.push({ role: 'assistant', content: `Answer ${i}` });
+        }
+        const ctx = makeMockContext({
+            provider: {
+                model: 'test-model',
+                provider: 'test',
+                languageModel: {},
+                streamText: vi.fn(),
+                generateText: vi.fn().mockResolvedValue({
+                    text: '## Summary\nThis is a compacted summary.',
+                    toolCalls: [],
+                    usage: makeUsage({ inputTokens: 200, outputTokens: 100, totalTokens: 300 }),
+                    finishReason: 'stop',
+                }),
+            },
+        });
+        const result = await transition({ type: 'compacting', messages, estimatedTokens: 5000 }, ctx);
+        expect(result.next.type).toBe('thinking');
+        if (result.next.type === 'thinking') {
+            // Should have fewer messages (summary + recent turns)
+            expect(result.next.messages.length).toBeLessThan(messages.length);
+            // First message should be the compaction summary (user role, not system,
+            // because Anthropic rejects system messages after user/assistant turns)
+            const firstMsg = result.next.messages[0];
+            expect(firstMsg.role).toBe('user');
+            const firstContent = firstMsg.content;
+            expect(typeof firstContent === 'string' && firstContent.includes('Conversation Summary')).toBe(true);
+        }
+        // Should emit compaction_start and compaction_end SSE events
+        const startEvents = result.effects.filter((e) => e.type === SSEEventType.CompactionStart);
+        const endEvents = result.effects.filter((e) => e.type === SSEEventType.CompactionEnd);
+        expect(startEvents.length).toBe(1);
+        expect(endEvents.length).toBe(1);
+        // Token usage should be tracked
+        expect(ctx.usage.inputTokens).toBe(200);
+        expect(ctx.usage.outputTokens).toBe(100);
+    });
+    it('skips compaction when too few messages to split', async () => {
+        const messages = [
+            { role: 'user', content: 'Hello' },
+            { role: 'assistant', content: 'Hi!' },
+        ];
+        const ctx = makeMockContext();
+        const result = await transition({ type: 'compacting', messages, estimatedTokens: 1000 }, ctx);
+        expect(result.next.type).toBe('thinking');
+        if (result.next.type === 'thinking') {
+            // Messages unchanged — not enough to compact
+            expect(result.next.messages).toBe(messages);
+        }
+    });
+    it('circuit breaker skips compaction after repeated failures', async () => {
+        const messages = [];
+        for (let i = 0; i < 10; i++) {
+            messages.push({ role: 'user', content: `Q${i}` });
+            messages.push({ role: 'assistant', content: `A${i}` });
+        }
+        const ctx = makeMockContext({ compactionFailures: 3 }); // Already at threshold
+        const result = await transition({ type: 'compacting', messages, estimatedTokens: 5000 }, ctx);
+        expect(result.next.type).toBe('thinking');
+        if (result.next.type === 'thinking') {
+            expect(result.next.messages).toBe(messages); // Unchanged
+        }
+        expect(ctx.logger.warn).toHaveBeenCalledWith('compaction_circuit_breaker', expect.objectContaining({
+            failures: 3,
+        }));
+    });
+    it('increments failure counter on generateText error and continues', async () => {
+        const messages = [];
+        for (let i = 0; i < 10; i++) {
+            messages.push({ role: 'user', content: `Q${i}` });
+            messages.push({ role: 'assistant', content: `A${i}` });
+        }
+        const ctx = makeMockContext({
+            provider: {
+                model: 'test-model',
+                provider: 'test',
+                languageModel: {},
+                streamText: vi.fn(),
+                generateText: vi.fn().mockRejectedValue(new Error('Provider rate limited')),
+            },
+        });
+        const result = await transition({ type: 'compacting', messages, estimatedTokens: 5000 }, ctx);
+        // Should continue without compaction
+        expect(result.next.type).toBe('thinking');
+        if (result.next.type === 'thinking') {
+            expect(result.next.messages).toBe(messages); // Unchanged
+        }
+        expect(ctx.compactionFailures).toBe(1);
+        expect(ctx.logger.error).toHaveBeenCalledWith('compaction_failed', expect.objectContaining({
+            error: 'Summarization failed: Provider rate limited',
+        }));
+    });
+    it('resets failure counter on successful compaction', async () => {
+        const messages = [];
+        for (let i = 0; i < 10; i++) {
+            messages.push({ role: 'user', content: `Q${i}` });
+            messages.push({ role: 'assistant', content: `A${i}` });
+        }
+        const ctx = makeMockContext({
+            compactionFailures: 2,
+            provider: {
+                model: 'test-model',
+                provider: 'test',
+                languageModel: {},
+                streamText: vi.fn(),
+                generateText: vi.fn().mockResolvedValue({
+                    text: 'Summary of conversation.',
+                    toolCalls: [],
+                    usage: makeUsage({ inputTokens: 100, outputTokens: 50, totalTokens: 150 }),
+                    finishReason: 'stop',
+                }),
+            },
+        });
+        await transition({ type: 'compacting', messages, estimatedTokens: 5000 }, ctx);
+        expect(ctx.compactionFailures).toBe(0);
+    });
+});
+describe('handleDispatching (via transition)', () => {
+    it('runs child agent and returns text result to parent', async () => {
+        const ctx = makeMockContext();
+        const result = await transition({
+            type: 'dispatching',
+            task: { agentName: 'research-agent', toolSubset: [], prompt: 'Find info' },
+            toolCallId: 'tc-dispatch-1',
+            queue: [],
+            results: [],
+        }, ctx);
+        // Child completes → parent goes to THINKING (no more queue items)
+        expect(result.next.type).toBe('thinking');
+        // Should have SubagentEvent effects (thought + complete)
+        const subagentEvents = result.effects.filter((e) => e.type === SSEEventType.SubagentEvent);
+        expect(subagentEvents.length).toBeGreaterThanOrEqual(1);
+        // Should have a ToolCallResult for the dispatch_task call
+        const toolResult = result.effects.find((e) => e.type === SSEEventType.ToolCallResult);
+        expect(toolResult).toBeDefined();
+        // Child usage merged into parent
+        expect(ctx.usage.inputTokens).toBeGreaterThan(0);
+    });
+    it('emits SubagentEvent with correct parent_tool_id', async () => {
+        const ctx = makeMockContext();
+        const result = await transition({
+            type: 'dispatching',
+            task: { agentName: 'profiler', toolSubset: [], prompt: 'Profile entity' },
+            toolCallId: 'tc-abc',
+            queue: [],
+            results: [],
+        }, ctx);
+        const subagentEvents = result.effects.filter((e) => e.type === SSEEventType.SubagentEvent);
+        for (const event of subagentEvents) {
+            if (event.type === SSEEventType.SubagentEvent) {
+                expect(event.parent_tool_id).toBe('tc-abc');
+                expect(event.agent_name).toBe('profiler');
+            }
+        }
+    });
+    it('continues execution queue after dispatch completes', async () => {
+        const ctx = makeMockContext();
+        const result = await transition({
+            type: 'dispatching',
+            task: { agentName: 'fetcher', toolSubset: [], prompt: 'Fetch data' },
+            toolCallId: 'tc-dispatch',
+            queue: [{ toolCallId: 'tc-next', toolName: 'request', args: {} }],
+            results: [],
+        }, ctx);
+        // Should transition to executing the next tool in queue
+        expect(result.next.type).toBe('executing');
+    });
+    it('handles child agent error gracefully', async () => {
+        // Provider that throws on streamText
+        const failingProvider = {
+            model: 'test-model',
+            provider: 'test',
+            languageModel: {},
+            streamText: vi.fn(() => { throw new Error('Provider crashed'); }),
+            generateText: vi.fn(),
+        };
+        const ctx = makeMockContext({ provider: failingProvider });
+        const result = await transition({
+            type: 'dispatching',
+            task: { agentName: 'broken-agent', toolSubset: [], prompt: 'Do something' },
+            toolCallId: 'tc-fail',
+            queue: [],
+            results: [],
+        }, ctx);
+        // Should NOT crash — transitions to thinking so parent can recover
+        expect(result.next.type).toBe('thinking');
+        // Should emit SubagentEvent with error
+        const errorEvents = result.effects.filter((e) => e.type === SSEEventType.SubagentEvent && 'event_type' in e && e.event_type === 'error');
+        expect(errorEvents.length).toBeGreaterThanOrEqual(1);
+        // Should emit ToolCallResult with error status
+        const toolResult = result.effects.find((e) => e.type === SSEEventType.ToolCallResult);
+        expect(toolResult).toBeDefined();
+        if (toolResult && toolResult.type === SSEEventType.ToolCallResult) {
+            expect(toolResult.status).toBe('error');
+        }
+        // Should log the error
+        expect(ctx.logger.error).toHaveBeenCalledWith('dispatch_child_error', expect.objectContaining({
+            agent: 'broken-agent',
+        }));
+    });
+    it('propagates parent remaining token budget to child', async () => {
+        // Parent has 100 budget, 90 already used → child should get 10.
+        // Child's first mock turn yields 150 tokens, which exceeds the child's
+        // 10-token budget; the child's outer loop catches it on the next check
+        // and stops with budget_exceeded. Parent usage reflects the child's
+        // consumed tokens once the child merges back.
+        const parentCtx = makeMockContext({
+            maxSessionTokens: 100,
+            usage: { inputTokens: 60, outputTokens: 30, totalTokens: 90 },
+        });
+        const result = await transition({
+            type: 'dispatching',
+            task: { agentName: 'starved-child', toolSubset: [], prompt: 'Do lots of work' },
+            toolCallId: 'tc-starved',
+            queue: [],
+            results: [],
+        }, parentCtx);
+        // Parent should resume (doesn't crash on child budget exhaustion)
+        expect(result.next.type).toBe('thinking');
+        // Child should have stopped early — its merged-back token usage should
+        // not massively exceed the original budget, because the check fires on
+        // the next outer loop iteration after the first 150-token turn.
+        // (It won't be zero — the first turn runs fully and merges — but it
+        // won't compound across many turns.)
+        expect(parentCtx.usage.totalTokens).toBeLessThanOrEqual(90 + 150 + 150);
+    });
+    it('child inherits unlimited budget when parent has no cap', async () => {
+        // No maxSessionTokens on parent → child should also have no cap (undefined).
+        // The child runs through normal termination (model_stop), not budget.
+        const parentCtx = makeMockContext({
+            // maxSessionTokens intentionally omitted
+            usage: { inputTokens: 500, outputTokens: 500, totalTokens: 1000 },
+        });
+        const result = await transition({
+            type: 'dispatching',
+            task: { agentName: 'unbounded-child', toolSubset: [], prompt: 'Go' },
+            toolCallId: 'tc-unbounded',
+            queue: [],
+            results: [],
+        }, parentCtx);
+        expect(result.next.type).toBe('thinking');
+        // No agent_loop_budget_exceeded log should have fired for the child
+        expect(parentCtx.logger.warn).not.toHaveBeenCalledWith('agent_loop_budget_exceeded', expect.anything());
+    });
+});
+// ---------------------------------------------------------------------------
+// 3. Integration: runAgent() full flow
+// ---------------------------------------------------------------------------
+describe('runAgent', () => {
+    it('text-only conversation: init → text_delta → done with usage', async () => {
+        const ctx = makeMockContext();
+        const events = [];
+        for await (const event of runAgent({
+            messages: [{ role: 'user', content: 'Hello' }],
+            context: ctx,
+        })) {
+            events.push(event);
+        }
+        // Init is first
+        expect(events[0].type).toBe(SSEEventType.Init);
+        // Done is last
+        const lastEvent = events[events.length - 1];
+        expect(lastEvent.type).toBe(SSEEventType.Done);
+        // Done always has usage (G2)
+        const doneEvent = lastEvent;
+        expect(doneEvent.usage).toBeDefined();
+        expect(doneEvent.usage?.input_tokens).toBeGreaterThanOrEqual(0);
+        expect(doneEvent.usage?.output_tokens).toBeGreaterThanOrEqual(0);
+    });
+    it('tool call conversation: init → text → tool_start → tool_result → done', async () => {
+        const searchTool = makeMockToolDef({
+            execute: vi.fn().mockResolvedValue({ results: ['found'] }),
+        });
+        const registry = makeMockRegistry({ search: searchTool });
+        let callCount = 0;
+        const provider = {
+            model: 'test-model',
+            provider: 'test',
+            languageModel: {},
+            streamText: vi.fn(() => {
+                callCount++;
+                if (callCount === 1) {
+                    // First call: model requests a tool
+                    return makeMockStream([
+                        { type: 'text-delta', textDelta: 'Searching...' },
+                        { type: 'tool-call', toolCallId: 'c1', toolName: 'search', args: { q: 'test' } },
+                        { type: 'finish', usage: makeUsage({ inputTokens: 50, outputTokens: 20, totalTokens: 70 }) },
+                    ], 'Searching...');
+                }
+                // Second call: model responds with text
+                return makeMockStream([
+                    { type: 'text-delta', textDelta: 'Found results.' },
+                    { type: 'finish', usage: makeUsage({ inputTokens: 80, outputTokens: 30, totalTokens: 110 }) },
+                ], 'Found results.');
+            }),
+            generateText: vi.fn(),
+        };
+        const ctx = makeMockContext({ provider, toolRegistry: registry });
+        const events = [];
+        for await (const event of runAgent({
+            messages: [{ role: 'user', content: 'Search for test' }],
+            context: ctx,
+        })) {
+            events.push(event);
+        }
+        // Should have init, text deltas, tool events, more text deltas, done
+        const types = events.map((e) => e.type);
+        expect(types[0]).toBe(SSEEventType.Init);
+        expect(types[types.length - 1]).toBe(SSEEventType.Done);
+        expect(types).toContain(SSEEventType.ToolCallStart);
+        expect(types).toContain(SSEEventType.ToolCallResult);
+        // tool_call_start must come before tool_call_result
+        const startIdx = types.indexOf(SSEEventType.ToolCallStart);
+        const resultIdx = types.indexOf(SSEEventType.ToolCallResult);
+        expect(startIdx).toBeLessThan(resultIdx);
+        // Provider should have been called twice (thinking → tool → thinking → done)
+        expect(provider.streamText).toHaveBeenCalledTimes(2);
+    });
+    it('abort signal terminates the loop with user_abort', async () => {
+        const abortController = new AbortController();
+        // Provider that aborts after first call
+        const provider = {
+            model: 'test-model',
+            provider: 'test',
+            languageModel: {},
+            streamText: vi.fn(() => {
+                // Abort after stream starts
+                abortController.abort();
+                return makeMockStream([
+                    { type: 'text-delta', textDelta: 'Starting...' },
+                    { type: 'finish', usage: makeUsage() },
+                ]);
+            }),
+            generateText: vi.fn(),
+        };
+        const ctx = makeMockContext({ provider, signal: abortController.signal });
+        const events = [];
+        for await (const event of runAgent({
+            messages: [{ role: 'user', content: 'Hello' }],
+            context: ctx,
+        })) {
+            events.push(event);
+        }
+        // Should end with done event
+        const doneEvent = events[events.length - 1];
+        expect(doneEvent.type).toBe(SSEEventType.Done);
+        // Usage should be present even on abort
+        expect(doneEvent.usage).toBeDefined();
+    });
+    it('max turns terminates the loop', async () => {
+        const tool = makeMockToolDef();
+        const registry = makeMockRegistry({ loop_tool: tool });
+        // Provider always requests a tool call (infinite loop)
+        const provider = {
+            model: 'test-model',
+            provider: 'test',
+            languageModel: {},
+            streamText: vi.fn(() => makeMockStream([
+                { type: 'tool-call', toolCallId: `c-${Date.now()}`, toolName: 'loop_tool', args: {} },
+                { type: 'finish', usage: makeUsage({ inputTokens: 10, outputTokens: 5, totalTokens: 15 }) },
+            ], '')),
+            generateText: vi.fn(),
+        };
+        const ctx = makeMockContext({
+            provider,
+            toolRegistry: registry,
+            maxTurns: 3,
+        });
+        const events = [];
+        for await (const event of runAgent({
+            messages: [{ role: 'user', content: 'Loop forever' }],
+            context: ctx,
+        })) {
+            events.push(event);
+        }
+        // Should have terminated
+        const doneEvent = events[events.length - 1];
+        expect(doneEvent.type).toBe(SSEEventType.Done);
+        // Turn count should not exceed maxTurns
+        expect(ctx.turnCount).toBeLessThanOrEqual(3);
+    });
+    it('token budget terminates the loop with reason=budget_exceeded', async () => {
+        const tool = makeMockToolDef();
+        const registry = makeMockRegistry({ loop_tool: tool });
+        // Each turn yields 15 tokens (10 in + 5 out). With maxSessionTokens=30, the loop
+        // should stop after the 2nd turn pushes cumulative usage past the cap.
+        const provider = {
+            model: 'test-model',
+            provider: 'test',
+            languageModel: {},
+            streamText: vi.fn(() => makeMockStream([
+                { type: 'tool-call', toolCallId: `c-${Date.now()}`, toolName: 'loop_tool', args: {} },
+                { type: 'finish', usage: makeUsage({ inputTokens: 10, outputTokens: 5, totalTokens: 15 }) },
+            ], '')),
+            generateText: vi.fn(),
+        };
+        const ctx = makeMockContext({
+            provider,
+            toolRegistry: registry,
+            maxTurns: 100,
+            maxSessionTokens: 30,
+        });
+        const events = [];
+        for await (const event of runAgent({
+            messages: [{ role: 'user', content: 'Burn tokens' }],
+            context: ctx,
+        })) {
+            events.push(event);
+        }
+        // Should have terminated on budget, not max_turns
+        const doneEvent = events[events.length - 1];
+        expect(doneEvent.type).toBe(SSEEventType.Done);
+        expect(ctx.turnCount).toBeLessThan(100);
+        expect(ctx.usage.totalTokens).toBeGreaterThanOrEqual(30);
+    });
+    it('undefined maxSessionTokens means no budget cap', async () => {
+        // Same infinite-tool-call provider as max_turns test, but with no
+        // maxSessionTokens set and a small maxTurns to bound the test. Verifies that
+        // undefined budget doesn't accidentally trip the check.
+        const tool = makeMockToolDef();
+        const registry = makeMockRegistry({ loop_tool: tool });
+        const provider = {
+            model: 'test-model',
+            provider: 'test',
+            languageModel: {},
+            streamText: vi.fn(() => makeMockStream([
+                { type: 'tool-call', toolCallId: `c-${Date.now()}`, toolName: 'loop_tool', args: {} },
+                { type: 'finish', usage: makeUsage({ inputTokens: 100, outputTokens: 100, totalTokens: 200 }) },
+            ], '')),
+            generateText: vi.fn(),
+        };
+        const ctx = makeMockContext({
+            provider,
+            toolRegistry: registry,
+            maxTurns: 2,
+            // maxSessionTokens intentionally omitted
+        });
+        const events = [];
+        for await (const event of runAgent({
+            messages: [{ role: 'user', content: 'Run' }],
+            context: ctx,
+        })) {
+            events.push(event);
+        }
+        // Should stop on max_turns, budget check should not interfere
+        const doneEvent = events[events.length - 1];
+        expect(doneEvent.type).toBe(SSEEventType.Done);
+        expect(ctx.usage.totalTokens).toBeGreaterThan(0);
+        // No budget-exceeded log should have been emitted
+        // (positive assertion: we reached max_turns, accumulating tokens beyond any tiny cap)
+    });
+    it('done event always includes usage regardless of reason (G2)', async () => {
+        // Abort immediately
+        const abortController = new AbortController();
+        abortController.abort();
+        const ctx = makeMockContext({
+            signal: abortController.signal,
+            usage: makeUsage({ inputTokens: 42, outputTokens: 13, totalTokens: 55 }),
+        });
+        const events = [];
+        for await (const event of runAgent({
+            messages: [{ role: 'user', content: 'Test' }],
+            context: ctx,
+        })) {
+            events.push(event);
+        }
+        const doneEvent = events[events.length - 1];
+        expect(doneEvent.type).toBe(SSEEventType.Done);
+        expect(doneEvent.usage).toBeDefined();
+        expect(doneEvent.usage?.input_tokens).toBe(42);
+        expect(doneEvent.usage?.output_tokens).toBe(13);
+    });
+    it('init event has session_id', async () => {
+        const ctx = makeMockContext({ sessionId: 'sess-abc' });
+        const events = [];
+        for await (const event of runAgent({
+            messages: [{ role: 'user', content: 'Hi' }],
+            context: ctx,
+        })) {
+            events.push(event);
+        }
+        const initEvent = events[0];
+        expect(initEvent.type).toBe(SSEEventType.Init);
+        expect(initEvent.session_id).toBe('sess-abc');
+    });
+    it('logs agent_loop_start and agent_loop_done', async () => {
+        const ctx = makeMockContext();
+        const events = [];
+        for await (const event of runAgent({
+            messages: [{ role: 'user', content: 'Hello' }],
+            context: ctx,
+        })) {
+            events.push(event);
+        }
+        expect(ctx.logger.info).toHaveBeenCalledWith('agent_loop_start', expect.objectContaining({
+            session: 'test-session',
+        }));
+        expect(ctx.logger.info).toHaveBeenCalledWith('agent_loop_done', expect.objectContaining({
+            session: 'test-session',
+            reason: expect.any(String),
+        }));
+    });
+});
+//# sourceMappingURL=loop.test.js.map