@soleri/core 9.0.4 → 9.2.0

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

@@ -0,0 +1,394 @@
+/**
+ * Agent Loop — colocated tests.
+ *
+ * Covers: basic end_turn flow, tool dispatch, cancellation via AbortSignal,
+ * max iterations, callbacks, error handling.
+ *
+ * All HTTP calls to Anthropic API are mocked via vi.stubGlobal('fetch').
+ */
+
+import { describe, test, expect, beforeEach, afterEach, vi } from 'vitest';
+import { runAgentLoop } from './agent-loop.js';
+import type { AgentLoopConfig, ToolResult } from './agent-loop-types.js';
+import type { ChatMessage } from './types.js';
+
+// ─── Helpers ──────────────────────────────────────────────────────────
+
+function makeMessages(text: string): ChatMessage[] {
+  return [{ role: 'user', content: text, timestamp: Date.now() }];
+}
+
+function makeConfig(overrides?: Partial<AgentLoopConfig>): AgentLoopConfig {
+  return {
+    apiKey: 'test-key',
+    systemPrompt: 'You are a test assistant.',
+    tools: [],
+    executor: async () => ({ output: '', isError: false }),
+    model: 'test-model',
+    baseUrl: 'https://mock.api',
+    ...overrides,
+  };
+}
+
+/** Create a mock fetch response mimicking the Anthropic messages API. */
+function anthropicResponse(
+  content: Array<{ type: string; text?: string; id?: string; name?: string; input?: unknown }>,
+  stopReason: string = 'end_turn',
+  usage = { input_tokens: 10, output_tokens: 20 },
+) {
+  return {
+    ok: true,
+    status: 200,
+    json: async () => ({
+      content,
+      stop_reason: stopReason,
+      usage,
+    }),
+    text: async () => '',
+    headers: new Headers(),
+  };
+}
+
+function anthropicError(status: number, body: string = 'error') {
+  return {
+    ok: false,
+    status,
+    json: async () => ({}),
+    text: async () => body,
+    headers: new Headers(),
+  };
+}
+
+describe('runAgentLoop', () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('basic flow', () => {
+    test('returns text on end_turn', async () => {
+      fetchMock.mockResolvedValueOnce(
+        anthropicResponse([{ type: 'text', text: 'Hello!' }]),
+      );
+
+      const result = await runAgentLoop(makeMessages('hi'), makeConfig());
+      expect(result.text).toBe('Hello!');
+      expect(result.stopReason).toBe('end_turn');
+      expect(result.iterations).toBe(1);
+      expect(result.toolCalls).toBe(0);
+      expect(result.usage.inputTokens).toBe(10);
+      expect(result.usage.outputTokens).toBe(20);
+    });
+
+    test('accumulates newMessages', async () => {
+      fetchMock.mockResolvedValueOnce(
+        anthropicResponse([{ type: 'text', text: 'reply' }]),
+      );
+
+      const result = await runAgentLoop(makeMessages('q'), makeConfig());
+      expect(result.newMessages.length).toBeGreaterThanOrEqual(1);
+      expect(result.newMessages[0].role).toBe('assistant');
+      expect(result.newMessages[0].content).toBe('reply');
+    });
+  });
+
+  describe('tool dispatch', () => {
+    test('executes tool calls and continues', async () => {
+      // First call: LLM returns a tool_use block
+      fetchMock.mockResolvedValueOnce(
+        anthropicResponse(
+          [
+            { type: 'text', text: 'Let me search...' },
+            { type: 'tool_use', id: 'tu_1', name: 'search', input: { q: 'test' } },
+          ],
+          'tool_use',
+        ),
+      );
+      // Second call: LLM returns final text
+      fetchMock.mockResolvedValueOnce(
+        anthropicResponse([{ type: 'text', text: 'Found it!' }]),
+      );
+
+      const executorResults: string[] = [];
+      const executor = async (name: string, _input: Record<string, unknown>): Promise<ToolResult> => {
+        executorResults.push(name);
+        return { output: `result for ${name}`, isError: false };
+      };
+
+      const result = await runAgentLoop(makeMessages('search'), makeConfig({
+        tools: [{ name: 'search', description: 'Search', inputSchema: { type: 'object' } }],
+        executor,
+      }));
+
+      expect(result.iterations).toBe(2);
+      expect(result.toolCalls).toBe(1);
+      expect(executorResults).toEqual(['search']);
+      expect(result.text).toContain('Found it!');
+    });
+
+    test('handles tool execution errors gracefully', async () => {
+      fetchMock.mockResolvedValueOnce(
+        anthropicResponse(
+          [{ type: 'tool_use', id: 'tu_1', name: 'broken', input: {} }],
+          'tool_use',
+        ),
+      );
+      fetchMock.mockResolvedValueOnce(
+        anthropicResponse([{ type: 'text', text: 'Done' }]),
+      );
+
+      const errors: string[] = [];
+      const result = await runAgentLoop(
+        makeMessages('go'),
+        makeConfig({
+          tools: [{ name: 'broken', description: 'Broken', inputSchema: { type: 'object' } }],
+          executor: async () => { throw new Error('tool failed'); },
+        }),
+        {
+          onError: (err, ctx) => errors.push(`${ctx}: ${err.message}`),
+        },
+      );
+
+      expect(result.iterations).toBe(2);
+      expect(result.toolCalls).toBe(1);
+      expect(errors).toHaveLength(1);
+      expect(errors[0]).toContain('tool:broken');
+    });
+  });
+
+  describe('cancellation', () => {
+    test('returns cancelled when signal is already aborted', async () => {
+      const controller = new AbortController();
+      controller.abort();
+
+      const result = await runAgentLoop(
+        makeMessages('hi'),
+        makeConfig({ signal: controller.signal }),
+      );
+
+      expect(result.stopReason).toBe('cancelled');
+      expect(result.iterations).toBe(0);
+      expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    test('returns cancelled when aborted during tool execution', async () => {
+      const controller = new AbortController();
+
+      fetchMock.mockResolvedValueOnce(
+        anthropicResponse(
+          [
+            { type: 'tool_use', id: 'tu_1', name: 'slow', input: {} },
+            { type: 'tool_use', id: 'tu_2', name: 'slow2', input: {} },
+          ],
+          'tool_use',
+        ),
+      );
+
+      let callCount = 0;
+      const result = await runAgentLoop(
+        makeMessages('go'),
+        makeConfig({
+          tools: [
+            { name: 'slow', description: 'Slow', inputSchema: { type: 'object' } },
+            { name: 'slow2', description: 'Slow2', inputSchema: { type: 'object' } },
+          ],
+          executor: async () => {
+            callCount++;
+            controller.abort(); // Abort after first tool
+            return { output: 'ok', isError: false };
+          },
+          signal: controller.signal,
+        }),
+      );
+
+      expect(result.stopReason).toBe('cancelled');
+      expect(callCount).toBe(1); // Only first tool ran
+    });
+
+    test('returns cancelled when fetch aborts', async () => {
+      const controller = new AbortController();
+
+      fetchMock.mockImplementation(async () => {
+        controller.abort();
+        throw new DOMException('aborted', 'AbortError');
+      });
+
+      const result = await runAgentLoop(
+        makeMessages('hi'),
+        makeConfig({ signal: controller.signal }),
+      );
+
+      expect(result.stopReason).toBe('cancelled');
+    });
+  });
+
+  describe('max iterations', () => {
+    test('stops at maxIterations', async () => {
+      // Always return tool_use to keep the loop going
+      fetchMock.mockImplementation(async () =>
+        anthropicResponse(
+          [{ type: 'tool_use', id: `tu_${Date.now()}`, name: 'loop', input: {} }],
+          'tool_use',
+        ),
+      );
+
+      const result = await runAgentLoop(
+        makeMessages('go'),
+        makeConfig({
+          maxIterations: 3,
+          tools: [{ name: 'loop', description: 'Loop', inputSchema: { type: 'object' } }],
+          executor: async () => ({ output: 'again', isError: false }),
+        }),
+      );
+
+      expect(result.stopReason).toBe('max_iterations');
+      expect(result.iterations).toBe(3);
+    });
+  });
+
+  describe('callbacks', () => {
+    test('fires onIteration for each loop', async () => {
+      fetchMock.mockResolvedValueOnce(
+        anthropicResponse([{ type: 'text', text: 'ok' }]),
+      );
+
+      const iterations: number[] = [];
+      await runAgentLoop(makeMessages('hi'), makeConfig(), {
+        onIteration: (n) => iterations.push(n),
+      });
+
+      expect(iterations).toEqual([1]);
+    });
+
+    test('fires onToolUse and onToolResult', async () => {
+      fetchMock.mockResolvedValueOnce(
+        anthropicResponse(
+          [{ type: 'tool_use', id: 'tu_1', name: 'ping', input: { val: 1 } }],
+          'tool_use',
+        ),
+      );
+      fetchMock.mockResolvedValueOnce(
+        anthropicResponse([{ type: 'text', text: 'done' }]),
+      );
+
+      const toolUses: string[] = [];
+      const toolResults: string[] = [];
+
+      await runAgentLoop(
+        makeMessages('go'),
+        makeConfig({
+          tools: [{ name: 'ping', description: 'Ping', inputSchema: { type: 'object' } }],
+          executor: async () => ({ output: 'pong', isError: false }),
+        }),
+        {
+          onToolUse: (name) => toolUses.push(name),
+          onToolResult: (name, result, ms) => {
+            toolResults.push(`${name}:${result.output}`);
+            expect(ms).toBeGreaterThanOrEqual(0);
+          },
+        },
+      );
+
+      expect(toolUses).toEqual(['ping']);
+      expect(toolResults).toEqual(['ping:pong']);
+    });
+  });
+
+  describe('API errors', () => {
+    test('throws on non-retryable API error', async () => {
+      fetchMock.mockResolvedValueOnce(anthropicError(400, 'bad request'));
+
+      await expect(
+        runAgentLoop(makeMessages('hi'), makeConfig()),
+      ).rejects.toThrow('Anthropic API error 400');
+    });
+
+    test('fires onError callback before throwing', async () => {
+      fetchMock.mockResolvedValueOnce(anthropicError(500, 'server error'));
+
+      const errors: string[] = [];
+      await expect(
+        runAgentLoop(makeMessages('hi'), makeConfig(), {
+          onError: (err) => errors.push(err.message),
+        }),
+      ).rejects.toThrow();
+
+      expect(errors).toHaveLength(1);
+      expect(errors[0]).toContain('500');
+    });
+  });
+
+  describe('message sanitization', () => {
+    test('strips leading assistant messages', async () => {
+      fetchMock.mockResolvedValueOnce(
+        anthropicResponse([{ type: 'text', text: 'ok' }]),
+      );
+
+      const messages: ChatMessage[] = [
+        { role: 'assistant', content: 'orphan', timestamp: Date.now() },
+        { role: 'user', content: 'hello', timestamp: Date.now() },
+      ];
+
+      const result = await runAgentLoop(messages, makeConfig());
+      expect(result.text).toBe('ok');
+
+      // Verify the API was called with user message first
+      const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+      expect(body.messages[0].role).toBe('user');
+    });
+
+    test('skips standalone tool messages', async () => {
+      fetchMock.mockResolvedValueOnce(
+        anthropicResponse([{ type: 'text', text: 'ok' }]),
+      );
+
+      const messages: ChatMessage[] = [
+        { role: 'user', content: 'hello', timestamp: Date.now() },
+        { role: 'tool', content: 'orphan tool result', timestamp: Date.now() },
+      ];
+
+      const result = await runAgentLoop(messages, makeConfig());
+      expect(result.text).toBe('ok');
+
+      const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+      // Tool messages are stripped — only user message remains
+      expect(body.messages).toHaveLength(1);
+    });
+  });
+
+  describe('usage accumulation', () => {
+    test('sums usage across iterations', async () => {
+      fetchMock.mockResolvedValueOnce(
+        anthropicResponse(
+          [{ type: 'tool_use', id: 'tu_1', name: 'x', input: {} }],
+          'tool_use',
+          { input_tokens: 100, output_tokens: 50 },
+        ),
+      );
+      fetchMock.mockResolvedValueOnce(
+        anthropicResponse(
+          [{ type: 'text', text: 'done' }],
+          'end_turn',
+          { input_tokens: 150, output_tokens: 30 },
+        ),
+      );
+
+      const result = await runAgentLoop(
+        makeMessages('go'),
+        makeConfig({
+          tools: [{ name: 'x', description: 'X', inputSchema: { type: 'object' } }],
+          executor: async () => ({ output: 'ok', isError: false }),
+        }),
+      );
+
+      expect(result.usage.inputTokens).toBe(250);
+      expect(result.usage.outputTokens).toBe(80);
+    });
+  });
+});

package/src/chat/agent-loop.ts

@@ -64,6 +64,7 @@ export async function runAgentLoop(
     // Call the Anthropic API
     let response: AnthropicResponse;
     try {
+      // oxlint-disable-next-line eslint(no-await-in-loop)
       response = await callAnthropic({
         baseUrl,
         apiKey: config.apiKey,
@@ -158,6 +159,7 @@ export async function runAgentLoop(
       const startTime = Date.now();
       let result;
       try {
+        // oxlint-disable-next-line eslint(no-await-in-loop)
         result = await config.executor(toolUse.name, toolUse.input as Record<string, unknown>);
       } catch (error) {
         result = {

package/src/{__tests__ → chat}/chat-differentiators.test.ts

@@ -6,9 +6,9 @@ import { describe, test, expect, beforeEach, afterEach } from 'vitest';
 import { mkdtempSync, rmSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { transcribeAudio, synthesizeSpeech } from '../chat/voice.js';
-import { MessageQueue } from '../chat/queue.js';
-import { BrowserSessionManager } from '../chat/browser-session.js';
+import { transcribeAudio, synthesizeSpeech } from './voice.js';
+import { MessageQueue } from './queue.js';
+import { BrowserSessionManager } from './browser-session.js';
 
 function makeTempDir(): string {
   return mkdtempSync(join(tmpdir(), 'chat-diff-'));

package/src/{__tests__ → chat}/chat-enhanced.test.ts

@@ -6,7 +6,7 @@ import { describe, test, expect, beforeEach, afterEach } from 'vitest';
 import { mkdtempSync, rmSync, readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { SelfUpdateManager, RESTART_EXIT_CODE } from '../chat/self-update.js';
+import { SelfUpdateManager, RESTART_EXIT_CODE } from './self-update.js';
 import {
   detectFileIntent,
   buildMultimodalContent,
@@ -15,9 +15,9 @@ import {
   sanitizeForPersistence,
   MAX_FILE_SIZE,
   TEXT_EXTENSIONS,
-} from '../chat/file-handler.js';
-import { NotificationEngine } from '../chat/notifications.js';
-import type { FileInfo, MultimodalContent } from '../chat/file-handler.js';
+} from './file-handler.js';
+import { NotificationEngine } from './notifications.js';
+import type { FileInfo, MultimodalContent } from './file-handler.js';
 
 function makeTempDir(): string {
   return mkdtempSync(join(tmpdir(), 'chat-enhanced-'));

package/src/{__tests__ → chat}/chat-transport.test.ts

@@ -7,12 +7,12 @@ import { describe, test, expect, beforeEach, afterEach } from 'vitest';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { ChatSessionManager } from '../chat/chat-session.js';
-import { FragmentBuffer } from '../chat/fragment-buffer.js';
-import { ChatAuthManager } from '../chat/auth-manager.js';
-import { TaskCancellationManager } from '../chat/cancellation.js';
-import { chunkResponse, markdownToHtml, convertMarkup } from '../chat/response-chunker.js';
-import type { Fragment } from '../chat/types.js';
+import { ChatSessionManager } from './chat-session.js';
+import { FragmentBuffer } from './fragment-buffer.js';
+import { ChatAuthManager } from './auth-manager.js';
+import { TaskCancellationManager } from './cancellation.js';
+import { chunkResponse, markdownToHtml, convertMarkup } from './response-chunker.js';
+import type { Fragment } from './types.js';
 
 // ─── Helpers ────────────────────────────────────────────────────────
 

package/src/chat/mcp-bridge.test.ts

@@ -0,0 +1,173 @@
+/**
+ * McpToolBridge — colocated tests.
+ *
+ * Covers: registration, allowlist filtering, execution, compression,
+ * truncation, error handling, executor factory.
+ */
+
+import { describe, test, expect, beforeEach } from 'vitest';
+import { McpToolBridge } from './mcp-bridge.js';
+import type { McpToolRegistration } from './agent-loop-types.js';
+
+function makeTool(name: string, result: unknown = 'ok'): McpToolRegistration {
+  return {
+    name,
+    description: `Tool ${name}`,
+    inputSchema: { type: 'object' },
+    handler: async () => result,
+  };
+}
+
+describe('McpToolBridge', () => {
+  let bridge: McpToolBridge;
+
+  beforeEach(() => {
+    bridge = new McpToolBridge();
+  });
+
+  describe('registration', () => {
+    test('register adds a tool', () => {
+      bridge.register(makeTool('vault_search'));
+      expect(bridge.has('vault_search')).toBe(true);
+      expect(bridge.size).toBe(1);
+    });
+
+    test('registerAll adds multiple tools', () => {
+      bridge.registerAll([makeTool('a'), makeTool('b'), makeTool('c')]);
+      expect(bridge.size).toBe(3);
+      expect(bridge.listTools().sort()).toEqual(['a', 'b', 'c']);
+    });
+
+    test('register overwrites existing tool', () => {
+      bridge.register(makeTool('x', 'v1'));
+      bridge.register(makeTool('x', 'v2'));
+      expect(bridge.size).toBe(1);
+    });
+
+    test('clear removes all tools', () => {
+      bridge.registerAll([makeTool('a'), makeTool('b')]);
+      bridge.clear();
+      expect(bridge.size).toBe(0);
+      expect(bridge.has('a')).toBe(false);
+    });
+  });
+
+  describe('allowlist', () => {
+    test('only registers allowed tools', () => {
+      const filtered = new McpToolBridge({ allowlist: ['allowed'] });
+      filtered.register(makeTool('allowed'));
+      filtered.register(makeTool('blocked'));
+      expect(filtered.has('allowed')).toBe(true);
+      expect(filtered.has('blocked')).toBe(false);
+      expect(filtered.size).toBe(1);
+    });
+
+    test('registerAll respects allowlist', () => {
+      const filtered = new McpToolBridge({ allowlist: ['a', 'c'] });
+      filtered.registerAll([makeTool('a'), makeTool('b'), makeTool('c')]);
+      expect(filtered.listTools().sort()).toEqual(['a', 'c']);
+    });
+  });
+
+  describe('getTools', () => {
+    test('returns AgentTool array', () => {
+      bridge.register(makeTool('vault_search'));
+      const tools = bridge.getTools();
+      expect(tools).toHaveLength(1);
+      expect(tools[0].name).toBe('vault_search');
+      expect(tools[0].description).toBe('Tool vault_search');
+      expect(tools[0].inputSchema).toEqual({ type: 'object' });
+    });
+
+    test('returns empty array when no tools', () => {
+      expect(bridge.getTools()).toEqual([]);
+    });
+  });
+
+  describe('execute', () => {
+    test('returns string output', async () => {
+      bridge.register(makeTool('echo', 'hello world'));
+      const result = await bridge.execute('echo', {});
+      expect(result.output).toBe('hello world');
+      expect(result.isError).toBe(false);
+    });
+
+    test('stringifies non-string results', async () => {
+      bridge.register(makeTool('data', { key: 'value' }));
+      const result = await bridge.execute('data', {});
+      expect(result.output).toBe('{"key":"value"}');
+      expect(result.isError).toBe(false);
+    });
+
+    test('returns error for unknown tool', async () => {
+      const result = await bridge.execute('nonexistent', {});
+      expect(result.isError).toBe(true);
+      expect(result.output).toContain('Unknown tool');
+    });
+
+    test('catches handler errors', async () => {
+      bridge.register({
+        ...makeTool('broken'),
+        handler: async () => { throw new Error('kaboom'); },
+      });
+      const result = await bridge.execute('broken', {});
+      expect(result.isError).toBe(true);
+      expect(result.output).toContain('kaboom');
+    });
+
+    test('passes input to handler', async () => {
+      let received: Record<string, unknown> = {};
+      bridge.register({
+        ...makeTool('capture'),
+        handler: async (input) => { received = input; return 'ok'; },
+      });
+      await bridge.execute('capture', { foo: 'bar' });
+      expect(received).toEqual({ foo: 'bar' });
+    });
+
+    test('truncates output exceeding maxOutput', async () => {
+      const small = new McpToolBridge({ maxOutput: 50 });
+      small.register(makeTool('verbose', 'x'.repeat(200)));
+      const result = await small.execute('verbose', {});
+      expect(result.output.length).toBeLessThanOrEqual(100); // 50 + truncation notice
+      expect(result.output).toContain('truncated');
+    });
+  });
+
+  describe('compressor', () => {
+    test('applies compressor to output', async () => {
+      const compressing = new McpToolBridge({
+        compressor: (_name, output, _max) => output.toUpperCase(),
+      });
+      compressing.register(makeTool('echo', 'hello'));
+      const result = await compressing.execute('echo', {});
+      expect(result.output).toBe('HELLO');
+    });
+
+    test('truncates after compression if still too long', async () => {
+      const compressing = new McpToolBridge({
+        compressor: (_name, output) => output, // no-op compressor
+        maxOutput: 20,
+      });
+      compressing.register(makeTool('big', 'x'.repeat(100)));
+      const result = await compressing.execute('big', {});
+      expect(result.output).toContain('truncated');
+    });
+  });
+
+  describe('createExecutor', () => {
+    test('returns a function that delegates to execute', async () => {
+      bridge.register(makeTool('ping', 'pong'));
+      const executor = bridge.createExecutor();
+      const result = await executor('ping', {});
+      expect(result.output).toBe('pong');
+      expect(result.isError).toBe(false);
+    });
+
+    test('executor handles unknown tool', async () => {
+      const executor = bridge.createExecutor();
+      const result = await executor('missing', {});
+      expect(result.isError).toBe(true);
+    });
+  });
+});

package/src/chat/notifications.ts

@@ -126,8 +126,10 @@ export class NotificationEngine {
           continue;
         }
 
+        // oxlint-disable-next-line eslint(no-await-in-loop)
         const message = await check.check();
         if (message) {
+          // oxlint-disable-next-line eslint(no-await-in-loop)
           await this.onNotify(id, message);
           this.lastNotified.set(id, Date.now());
           this.sent++;