@amodalai/runtime 0.1.26 → 0.2.0

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

@@ -0,0 +1,1030 @@
+/**
+ * @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',
+        tenantId: 'test-tenant',
+        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(),
+        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',
+            tenantId: 'test-tenant',
+        }),
+        ...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
+        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', page: 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('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('system');
+        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('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();
+    });
+});
+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('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 system summary
+            const firstMsg = result.next.messages[0];
+            expect(firstMsg.role).toBe('system');
+            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',
+        }));
+    });
+});
+// ---------------------------------------------------------------------------
+// 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('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',
+            tenant: 'test-tenant',
+        }));
+        expect(ctx.logger.info).toHaveBeenCalledWith('agent_loop_done', expect.objectContaining({
+            session: 'test-session',
+            reason: expect.any(String),
+        }));
+    });
+});
+//# sourceMappingURL=loop.test.js.map