skimpyclaw 0.3.14 → 0.4.0

package/dist/__tests__/token-efficiency.test.js

@@ -1,9 +1,15 @@
-import { describe, it, expect, afterAll } from 'vitest';
-import { truncateToolResult } from '../providers/utils.js';
+import { describe, it, expect, afterAll, vi } from 'vitest';
 import { existsSync, readdirSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
-const scratchDir = join(homedir(), '.skimpyclaw', 'scratch');
+import { fileURLToPath } from 'url';
+const testHome = fileURLToPath(new URL('../..', import.meta.url));
+vi.mock('os', async () => {
+    const actual = await vi.importActual('os');
+    return { ...actual, homedir: () => testHome };
+});
+const { truncateToolResult, splitToolResult } = await import('../providers/utils.js');
+const scratchDir = join(testHome, '.skimpyclaw', 's');
 // Clean up scratch files created during tests
 afterAll(() => {
     try {
@@ -25,25 +31,135 @@ describe('token efficiency', () => {
             expect(truncateToolResult(result)).toBe(result);
         });
         it('returns results under mask threshold unchanged', () => {
-            const result = 'x'.repeat(7_999);
+            const result = 'x'.repeat(799);
             expect(truncateToolResult(result)).toBe(result);
         });
-        it('masks large results to scratch file with summary', () => {
+        it('masks large results to scratch file with path only', () => {
             const result = 'START' + 'x'.repeat(10_000) + 'END';
             const masked = truncateToolResult(result);
             expect(masked.length).toBeLessThan(result.length);
-            expect(masked).toContain('[Full output');
-            expect(masked).toContain('saved to');
-            expect(masked).toContain('.skimpyclaw/scratch/');
-            expect(masked).toContain('use Read tool to access');
-            // Summary includes head and tail
-            expect(masked).toContain('START');
-            expect(masked).toContain('END');
-        });
-        it('includes char count in masked output', () => {
+            expect(masked).toContain('→');
+            expect(masked).toContain('.skimpyclaw/s/');
+        });
+        it('produces minimal output for masked results', () => {
             const result = 'y'.repeat(20_000);
             const masked = truncateToolResult(result);
-            expect(masked).toContain('20000 chars');
+            expect(masked.startsWith('→')).toBe(true);
+            expect(masked).toContain('.skimpyclaw/s/');
+        });
+    });
+    describe('splitToolResult', () => {
+        it('returns small results unchanged', () => {
+            const result = 'short output';
+            expect(splitToolResult('Read', { file_path: '/foo.ts' }, result)).toBe(result);
+        });
+        it('returns results at mask threshold unchanged', () => {
+            const result = 'x'.repeat(800);
+            expect(splitToolResult('Bash', { command: 'echo hi' }, result)).toBe(result);
+        });
+        describe('scratch file reads', () => {
+            it('does not split reads from scratch directory', () => {
+                const largeResult = 'x'.repeat(20_000);
+                const scratchPath = join(testHome, '.skimpyclaw', 'scratch', '12345-abc.txt');
+                const split = splitToolResult('Read', { file_path: scratchPath }, largeResult);
+                expect(split).toBe(largeResult);
+            });
+            it('does not split reads from tilde scratch path', () => {
+                const largeResult = 'y'.repeat(20_000);
+                const split = splitToolResult('Read', { file_path: '~/.skimpyclaw/s/test.txt' }, largeResult);
+                expect(split).toBe(largeResult);
+            });
+            it('does not split read_file from scratch directory', () => {
+                const largeResult = 'z'.repeat(20_000);
+                const scratchPath = join(testHome, '.skimpyclaw', 'scratch', 'foo.txt');
+                const split = splitToolResult('read_file', { path: scratchPath }, largeResult);
+                expect(split).toBe(largeResult);
+            });
+        });
+        describe('Read tool', () => {
+            it('produces preview + scratch path for large read results', () => {
+                const lines = Array.from({ length: 500 }, (_, i) => `line ${i + 1}: content here`);
+                const result = lines.join('\n');
+                const split = splitToolResult('Read', { file_path: '/src/app.ts' }, result);
+                expect(split).toContain('Full output saved to');
+                expect(split).toContain('.skimpyclaw/s/');
+                expect(split).toContain('line 1: content here');
+                // Much shorter than original
+                expect(split.length).toBeLessThan(result.length);
+            });
+            it('handles read_file tool name', () => {
+                const result = 'x\n'.repeat(5000);
+                const split = splitToolResult('read_file', { path: '/foo.txt' }, result);
+                expect(split).toContain('Full output saved to');
+                expect(split).toContain('.skimpyclaw/s/');
+            });
+        });
+        describe('Bash tool', () => {
+            it('produces preview + scratch path for large bash output', () => {
+                const output = Array.from({ length: 400 }, (_, i) => `output line ${i}: ${'x'.repeat(20)}`).join('\n');
+                const split = splitToolResult('Bash', { command: 'find . -name "*.ts"' }, output);
+                expect(split).toContain('Full output saved to');
+                expect(split).toContain('.skimpyclaw/s/');
+                expect(split).toContain('output line 0');
+            });
+            it('extracts exit code when present', () => {
+                const output = 'x\n'.repeat(5000) + 'exit code: 1';
+                const split = splitToolResult('bash', { command: 'make build' }, output);
+                expect(split).toContain('exit=1');
+            });
+            it('includes error lines when present', () => {
+                const lines = ['output1', 'error: something failed', 'output2'];
+                const result = lines.join('\n') + '\n' + 'x'.repeat(9000);
+                const split = splitToolResult('Bash', { command: 'npm install' }, result);
+                expect(split).toContain('error: something failed');
+            });
+        });
+        describe('non-Bash tools', () => {
+            it('produces preview + scratch path for Glob', () => {
+                const entries = Array.from({ length: 300 }, (_, i) => `src/components/deeply/nested/module${i}/file${i}.ts`).join('\n');
+                const split = splitToolResult('Glob', { pattern: '**/*.ts' }, entries);
+                expect(split).toContain('Full output saved to');
+                expect(split).toContain('.skimpyclaw/s/');
+                expect(split).toContain('src/components');
+            });
+            it('produces preview + scratch path for Fetch', () => {
+                const result = 'HTTP/1.1 200 OK\n' + 'x'.repeat(10_000);
+                const split = splitToolResult('Fetch', { url: 'https://example.com/api' }, result);
+                expect(split).toContain('Full output saved to');
+                expect(split).toContain('.skimpyclaw/s/');
+                expect(split).toContain('HTTP/1.1 200 OK');
+            });
+            it('produces preview + scratch path for generic tool output', () => {
+                const result = 'x\n'.repeat(5000);
+                const split = splitToolResult('custom_tool', { action: 'snapshot' }, result);
+                expect(split).toContain('Full output saved to');
+                expect(split).toContain('.skimpyclaw/s/');
+            });
+            it('produces preview + scratch path for MCP', () => {
+                const result = 'x\n'.repeat(5000);
+                const split = splitToolResult('mcp__context_a8c__search', {}, result);
+                expect(split).toContain('Full output saved to');
+                expect(split).toContain('.skimpyclaw/s/');
+                expect(split).toContain('x\n');
+            });
+            it('produces preview + scratch path for unknown tools', () => {
+                const result = 'z'.repeat(10_000);
+                const split = splitToolResult('custom_tool', {}, result);
+                expect(split).toContain('Full output saved to');
+                expect(split).toContain('.skimpyclaw/s/');
+                expect(split).toContain('zzz');
+            });
+        });
+        it('creates scratch file for large results', () => {
+            const result = 'data'.repeat(3000);
+            const split = splitToolResult('Read', { file_path: '/big.txt' }, result);
+            // Extract scratch path from the result
+            const pathMatch = split.match(/saved to (\S*\.skimpyclaw\/s\/\S+)/);
+            expect(pathMatch).not.toBeNull();
+            if (pathMatch) {
+                const p = pathMatch[1].startsWith('~/') ? pathMatch[1].replace('~', homedir()) : pathMatch[1];
+                expect(existsSync(p)).toBe(true);
+            }
         });
     });
     describe('retry prompt compression', () => {

package/dist/__tests__/tool-loop.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for the unified tool loop orchestrator.
+ */
+export {};

package/dist/__tests__/tool-loop.test.js

@@ -0,0 +1,505 @@
+/**
+ * Tests for the unified tool loop orchestrator.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { runToolLoop } from '../providers/tool-loop.js';
+// Mock adapter for testing
+class MockAdapter {
+    name = 'mock';
+    isAvailable() {
+        return true;
+    }
+    async chat(_messages, _options, _config) {
+        return 'mock response';
+    }
+    // Track calls for assertions
+    callCount = 0;
+    buildMessagesCallCount = 0;
+    buildToolDefsCallCount = 0;
+    appendAssistantCallCount = 0;
+    appendToolResultCallCount = 0;
+    compactMessagesCallCount = 0;
+    recordUsageCallCount = 0;
+    // Mock responses to return
+    responses = [];
+    currentResponseIndex = 0;
+    buildMessages(messages, options, config) {
+        this.buildMessagesCallCount++;
+        return {
+            messages: messages.filter(m => m.role !== 'system'),
+            systemParam: messages.find(m => m.role === 'system')?.content,
+        };
+    }
+    buildToolDefs(toolDefs, _config) {
+        this.buildToolDefsCallCount++;
+        return toolDefs;
+    }
+    async call(messages, toolDefs, options, config) {
+        this.callCount++;
+        const response = this.responses[this.currentResponseIndex] || {
+            hasToolCalls: false,
+            toolCalls: [],
+            textContent: 'default response',
+            usage: { inputTokens: 100, outputTokens: 50 },
+            rawResponse: {},
+        };
+        this.currentResponseIndex++;
+        return response;
+    }
+    appendAssistantResponse(messages, rawResponse) {
+        this.appendAssistantCallCount++;
+        messages.messages.push({ role: 'assistant', raw: rawResponse });
+    }
+    appendToolResult(messages, toolCallId, result, isError) {
+        this.appendToolResultCallCount++;
+        messages.messages.push({ role: 'tool', toolCallId, result, isError });
+    }
+    async compactMessages(messages, config, iteration, fullConfig) {
+        this.compactMessagesCallCount++;
+        return {
+            messages: messages.messages,
+            compacted: false,
+        };
+    }
+    recordUsage(model, usage, trigger, agentId) {
+        this.recordUsageCallCount++;
+    }
+}
+// Mock tool execution
+const { mockExecuteTool } = vi.hoisted(() => ({
+    mockExecuteTool: vi.fn().mockResolvedValue('tool result'),
+}));
+vi.mock('../tools.js', () => ({
+    getToolDefinitions: vi.fn().mockResolvedValue([
+        { name: 'testTool', description: 'A test tool' },
+    ]),
+    executeTool: mockExecuteTool,
+}));
+// Mock audit functions
+vi.mock('../audit.js', () => ({
+    startTrace: vi.fn().mockReturnValue('trace-123'),
+    addEvent: vi.fn(),
+    endTrace: vi.fn().mockResolvedValue(undefined),
+}));
+describe('runToolLoop', () => {
+    let adapter;
+    let messages;
+    let options;
+    let config;
+    let toolConfig;
+    beforeEach(() => {
+        mockExecuteTool.mockReset();
+        mockExecuteTool.mockResolvedValue('tool result');
+        adapter = new MockAdapter();
+        messages = [
+            { role: 'system', content: 'You are a helpful assistant' },
+            { role: 'user', content: 'Hello' },
+        ];
+        options = {
+            model: 'test-model',
+            maxTokens: 1000,
+        };
+        config = {
+            gateway: { port: 18790, mode: 'local' },
+            agents: { default: 'main', list: {} },
+            models: { providers: {}, aliases: {} },
+            channels: {
+                telegram: {
+                    enabled: false,
+                    token: 'test-token',
+                    allowFrom: [],
+                }
+            },
+            cron: { jobs: [] },
+            heartbeat: { intervalMs: 300000, prompt: 'HEARTBEAT' },
+        };
+        toolConfig = {
+            enabled: true,
+            allowedPaths: ['/tmp'],
+            maxIterations: 20,
+        };
+    });
+    it('should complete in one iteration when model returns text without tool calls', async () => {
+        adapter.responses = [
+            {
+                hasToolCalls: false,
+                toolCalls: [],
+                textContent: 'Hello! How can I help you?',
+                usage: { inputTokens: 100, outputTokens: 50 },
+                rawResponse: {},
+            },
+        ];
+        const result = await runToolLoop(adapter, messages, options, config, toolConfig);
+        expect(result.response).toBe('Hello! How can I help you?');
+        expect(result.toolCalls).toEqual([]);
+        expect(adapter.callCount).toBe(1);
+        expect(adapter.buildMessagesCallCount).toBe(1);
+        expect(adapter.recordUsageCallCount).toBe(1);
+    });
+    it('should handle tool calls and continue iteration', async () => {
+        adapter.responses = [
+            {
+                hasToolCalls: true,
+                toolCalls: [
+                    {
+                        id: 'call-1',
+                        name: 'testTool',
+                        args: { param: 'value' },
+                        rawArgs: '{"param":"value"}',
+                    },
+                ],
+                textContent: '',
+                usage: { inputTokens: 100, outputTokens: 50 },
+                rawResponse: { content: 'response1' },
+            },
+            {
+                hasToolCalls: false,
+                toolCalls: [],
+                textContent: 'Done!',
+                usage: { inputTokens: 150, outputTokens: 30 },
+                rawResponse: {},
+            },
+        ];
+        const result = await runToolLoop(adapter, messages, options, config, toolConfig);
+        expect(result.response).toBe('Done!');
+        expect(result.toolCalls).toHaveLength(1);
+        expect(adapter.callCount).toBe(2);
+        expect(adapter.appendAssistantCallCount).toBe(1);
+        expect(adapter.appendToolResultCallCount).toBe(1);
+    });
+    it('should stop at max iterations', async () => {
+        // Return tool calls every time
+        adapter.responses = Array(25).fill({
+            hasToolCalls: true,
+            toolCalls: [
+                {
+                    id: 'call-loop',
+                    name: 'testTool',
+                    args: { param: 'value' },
+                    rawArgs: '{"param":"value"}',
+                },
+            ],
+            textContent: '',
+            usage: { inputTokens: 100, outputTokens: 50 },
+            rawResponse: {},
+        });
+        const result = await runToolLoop(adapter, messages, options, config, toolConfig);
+        expect(result.response).toContain('maximum iterations');
+        expect(adapter.callCount).toBe(20); // maxIterations default
+    });
+    it('should handle abort signal', async () => {
+        const abortController = new AbortController();
+        const toolContext = {
+            abortSignal: abortController.signal,
+        };
+        // Set up multiple responses to give abort time to trigger
+        adapter.responses = [
+            {
+                hasToolCalls: true,
+                toolCalls: [{ id: 'call-1', name: 'testTool', args: {}, rawArgs: '{}' }],
+                textContent: '',
+                usage: { inputTokens: 100, outputTokens: 50 },
+                rawResponse: {},
+            },
+            {
+                hasToolCalls: true,
+                toolCalls: [{ id: 'call-2', name: 'testTool', args: {}, rawArgs: '{}' }],
+                textContent: '',
+                usage: { inputTokens: 100, outputTokens: 50 },
+                rawResponse: {},
+            },
+        ];
+        // Abort immediately
+        abortController.abort();
+        const result = await runToolLoop(adapter, messages, options, config, toolConfig, toolContext);
+        expect(result.response).toContain('Cancelled');
+    });
+    it('should call compactMessages on each iteration', async () => {
+        adapter.responses = [
+            {
+                hasToolCalls: true,
+                toolCalls: [{ id: 'call-1', name: 'testTool', args: {}, rawArgs: '{}' }],
+                textContent: '',
+                usage: { inputTokens: 100, outputTokens: 50 },
+                rawResponse: {},
+            },
+            {
+                hasToolCalls: false,
+                toolCalls: [],
+                textContent: 'Done',
+                usage: { inputTokens: 100, outputTokens: 50 },
+                rawResponse: {},
+            },
+        ];
+        await runToolLoop(adapter, messages, options, config, toolConfig);
+        expect(adapter.compactMessagesCallCount).toBe(2);
+    });
+    it('should recover from tool execution errors and feed error back to model', async () => {
+        mockExecuteTool.mockRejectedValueOnce(new Error('file not found'));
+        adapter.responses = [
+            {
+                hasToolCalls: true,
+                toolCalls: [{ id: 'call-err', name: 'testTool', args: { path: '/missing' }, rawArgs: '{"path":"/missing"}' }],
+                textContent: '',
+                usage: { inputTokens: 100, outputTokens: 50 },
+                rawResponse: {},
+            },
+            {
+                hasToolCalls: false,
+                toolCalls: [],
+                textContent: 'Recovered from error',
+                usage: { inputTokens: 100, outputTokens: 50 },
+                rawResponse: {},
+            },
+        ];
+        const result = await runToolLoop(adapter, messages, options, config, toolConfig);
+        expect(result.response).toBe('Recovered from error');
+        expect(adapter.appendToolResultCallCount).toBe(1);
+        expect(adapter.callCount).toBe(2);
+        // Tool log should contain the error
+        expect(result.toolCalls.some(t => t.includes('ERROR'))).toBe(true);
+    });
+    it('should call endTrace when the loop completes and it created the trace', async () => {
+        const { endTrace } = await import('../audit.js');
+        vi.mocked(endTrace).mockClear();
+        adapter.responses = [
+            {
+                hasToolCalls: false,
+                toolCalls: [],
+                textContent: 'Done',
+                usage: { inputTokens: 100, outputTokens: 50 },
+                rawResponse: {},
+            },
+        ];
+        await runToolLoop(adapter, messages, options, config, toolConfig);
+        expect(endTrace).toHaveBeenCalledWith('trace-123', 'ok');
+    });
+    it('should batch multiple tool results via appendToolResults when adapter supports it', async () => {
+        // Add batch support to the mock adapter
+        const batchedResults = [];
+        adapter.appendToolResults = (msgs, results) => {
+            batchedResults.push(...results);
+            msgs.messages.push({ role: 'user', content: results });
+        };
+        adapter.responses = [
+            {
+                hasToolCalls: true,
+                toolCalls: [
+                    { id: 'call-1', name: 'testTool', args: { a: 1 }, rawArgs: '{"a":1}' },
+                    { id: 'call-2', name: 'testTool', args: { b: 2 }, rawArgs: '{"b":2}' },
+                ],
+                textContent: '',
+                usage: { inputTokens: 100, outputTokens: 50 },
+                rawResponse: {},
+            },
+            {
+                hasToolCalls: false,
+                toolCalls: [],
+                textContent: 'Done with both',
+                usage: { inputTokens: 100, outputTokens: 50 },
+                rawResponse: {},
+            },
+        ];
+        const result = await runToolLoop(adapter, messages, options, config, toolConfig);
+        expect(result.response).toBe('Done with both');
+        expect(batchedResults).toHaveLength(2);
+        expect(batchedResults[0].toolCallId).toBe('call-1');
+        expect(batchedResults[1].toolCallId).toBe('call-2');
+        // appendToolResult should NOT have been called (batching was used instead)
+        expect(adapter.appendToolResultCallCount).toBe(0);
+    });
+    it('should provide fallback response when model returns empty text after tool use', async () => {
+        adapter.responses = [
+            {
+                hasToolCalls: true,
+                toolCalls: [{ id: 'call-1', name: 'testTool', args: {}, rawArgs: '{}' }],
+                textContent: '',
+                usage: { inputTokens: 100, outputTokens: 50 },
+                rawResponse: {},
+            },
+            {
+                hasToolCalls: false,
+                toolCalls: [],
+                textContent: '', // Empty response
+                usage: { inputTokens: 100, outputTokens: 50 },
+                rawResponse: {},
+            },
+        ];
+        const result = await runToolLoop(adapter, messages, options, config, toolConfig);
+        expect(result.response).toContain('Completed with 1 tool calls');
+    });
+    describe('onEmptyFinalResponse hook', () => {
+        it('should call onEmptyFinalResponse when final text is empty after tool use', async () => {
+            adapter.onEmptyFinalResponse = vi.fn().mockResolvedValue('Finalized answer');
+            adapter.responses = [
+                {
+                    hasToolCalls: true,
+                    toolCalls: [{ id: 'call-1', name: 'testTool', args: {}, rawArgs: '{}' }],
+                    textContent: '',
+                    usage: { inputTokens: 100, outputTokens: 50 },
+                    rawResponse: {},
+                },
+                {
+                    hasToolCalls: false,
+                    toolCalls: [],
+                    textContent: '', // Empty — triggers finalization hook
+                    usage: { inputTokens: 100, outputTokens: 50 },
+                    rawResponse: {},
+                },
+            ];
+            const result = await runToolLoop(adapter, messages, options, config, toolConfig);
+            expect(result.response).toBe('Finalized answer');
+            expect(adapter.onEmptyFinalResponse).toHaveBeenCalledTimes(1);
+        });
+        it('should NOT call onEmptyFinalResponse when final text is non-empty', async () => {
+            adapter.onEmptyFinalResponse = vi.fn().mockResolvedValue('Should not appear');
+            adapter.responses = [
+                {
+                    hasToolCalls: true,
+                    toolCalls: [{ id: 'call-1', name: 'testTool', args: {}, rawArgs: '{}' }],
+                    textContent: '',
+                    usage: { inputTokens: 100, outputTokens: 50 },
+                    rawResponse: {},
+                },
+                {
+                    hasToolCalls: false,
+                    toolCalls: [],
+                    textContent: 'Got a real answer',
+                    usage: { inputTokens: 100, outputTokens: 50 },
+                    rawResponse: {},
+                },
+            ];
+            const result = await runToolLoop(adapter, messages, options, config, toolConfig);
+            expect(result.response).toBe('Got a real answer');
+            expect(adapter.onEmptyFinalResponse).not.toHaveBeenCalled();
+        });
+        it('should NOT call onEmptyFinalResponse when no tool calls were made', async () => {
+            adapter.onEmptyFinalResponse = vi.fn().mockResolvedValue('Should not appear');
+            adapter.responses = [
+                {
+                    hasToolCalls: false,
+                    toolCalls: [],
+                    textContent: '', // Empty but no tool calls — no finalization
+                    usage: { inputTokens: 100, outputTokens: 50 },
+                    rawResponse: {},
+                },
+            ];
+            const result = await runToolLoop(adapter, messages, options, config, toolConfig);
+            expect(result.response).toBe('[Model returned empty response — please try again]');
+            expect(adapter.onEmptyFinalResponse).not.toHaveBeenCalled();
+        });
+        it('should fall back to default message when onEmptyFinalResponse returns undefined', async () => {
+            adapter.onEmptyFinalResponse = vi.fn().mockResolvedValue(undefined);
+            adapter.responses = [
+                {
+                    hasToolCalls: true,
+                    toolCalls: [{ id: 'call-1', name: 'testTool', args: {}, rawArgs: '{}' }],
+                    textContent: '',
+                    usage: { inputTokens: 100, outputTokens: 50 },
+                    rawResponse: {},
+                },
+                {
+                    hasToolCalls: false,
+                    toolCalls: [],
+                    textContent: '',
+                    usage: { inputTokens: 100, outputTokens: 50 },
+                    rawResponse: {},
+                },
+            ];
+            const result = await runToolLoop(adapter, messages, options, config, toolConfig);
+            expect(result.response).toContain('Completed with 1 tool calls');
+            expect(adapter.onEmptyFinalResponse).toHaveBeenCalledTimes(1);
+        });
+        it('should fall back to default message when onEmptyFinalResponse throws', async () => {
+            adapter.onEmptyFinalResponse = vi.fn().mockRejectedValue(new Error('finalize failed'));
+            adapter.responses = [
+                {
+                    hasToolCalls: true,
+                    toolCalls: [{ id: 'call-1', name: 'testTool', args: {}, rawArgs: '{}' }],
+                    textContent: '',
+                    usage: { inputTokens: 100, outputTokens: 50 },
+                    rawResponse: {},
+                },
+                {
+                    hasToolCalls: false,
+                    toolCalls: [],
+                    textContent: '',
+                    usage: { inputTokens: 100, outputTokens: 50 },
+                    rawResponse: {},
+                },
+            ];
+            const result = await runToolLoop(adapter, messages, options, config, toolConfig);
+            expect(result.response).toContain('Completed with 1 tool calls');
+            expect(adapter.onEmptyFinalResponse).toHaveBeenCalledTimes(1);
+        });
+        it('should call onEmptyFinalResponse when max iterations are reached after tool use', async () => {
+            const customToolConfig = { ...toolConfig, maxIterations: 2 };
+            adapter.onEmptyFinalResponse = vi.fn().mockResolvedValue('Best effort final answer');
+            adapter.responses = Array(2).fill({
+                hasToolCalls: true,
+                toolCalls: [{ id: 'call-loop', name: 'testTool', args: { x: 1 }, rawArgs: '{"x":1}' }],
+                textContent: '',
+                usage: { inputTokens: 10, outputTokens: 5 },
+                rawResponse: {},
+            });
+            const result = await runToolLoop(adapter, messages, options, config, customToolConfig);
+            expect(result.response).toBe('Best effort final answer');
+            expect(adapter.callCount).toBe(2);
+            expect(adapter.onEmptyFinalResponse).toHaveBeenCalledTimes(1);
+        });
+        it('should keep a clear max-iteration fallback when finalization returns empty', async () => {
+            const customToolConfig = { ...toolConfig, maxIterations: 2 };
+            adapter.onEmptyFinalResponse = vi.fn().mockResolvedValue(undefined);
+            adapter.responses = Array(2).fill({
+                hasToolCalls: true,
+                toolCalls: [{ id: 'call-loop', name: 'testTool', args: { x: 1 }, rawArgs: '{"x":1}' }],
+                textContent: '',
+                usage: { inputTokens: 10, outputTokens: 5 },
+                rawResponse: {},
+            });
+            const result = await runToolLoop(adapter, messages, options, config, customToolConfig);
+            expect(result.response).toContain('maximum iterations');
+            expect(adapter.onEmptyFinalResponse).toHaveBeenCalledTimes(1);
+        });
+    });
+    describe('Codex-specific behavior through unified loop', () => {
+        it('should accumulate usage across iterations', async () => {
+            adapter.responses = [
+                {
+                    hasToolCalls: true,
+                    toolCalls: [{ id: 'call-1', name: 'testTool', args: {}, rawArgs: '{}' }],
+                    textContent: '',
+                    usage: { inputTokens: 100, outputTokens: 50 },
+                    cost: { input: 0.001, output: 0.002, total: 0.003 },
+                    rawResponse: {},
+                },
+                {
+                    hasToolCalls: false,
+                    toolCalls: [],
+                    textContent: 'Done',
+                    usage: { inputTokens: 200, outputTokens: 80 },
+                    cost: { input: 0.002, output: 0.004, total: 0.006 },
+                    rawResponse: {},
+                },
+            ];
+            const result = await runToolLoop(adapter, messages, options, config, toolConfig);
+            expect(result.usage?.prompt_tokens).toBe(300);
+            expect(result.usage?.completion_tokens).toBe(130);
+            expect(result.usage?.total_tokens).toBe(430);
+            expect(result.cost?.total).toBeCloseTo(0.009);
+        });
+        it('should respect custom maxIterations from toolConfig', async () => {
+            const customToolConfig = { ...toolConfig, maxIterations: 3 };
+            adapter.responses = Array(5).fill({
+                hasToolCalls: true,
+                toolCalls: [{ id: 'call-x', name: 'testTool', args: { x: 1 }, rawArgs: '{"x":1}' }],
+                textContent: '',
+                usage: { inputTokens: 10, outputTokens: 5 },
+                rawResponse: {},
+            });
+            const result = await runToolLoop(adapter, messages, options, config, customToolConfig);
+            expect(result.response).toContain('maximum iterations');
+            expect(adapter.callCount).toBe(3);
+        });
+    });
+});