repoburg 1.3.188 → 1.3.196

package/agent-pane/backend/src/integration/helpers/app-server-mock.ts

@@ -0,0 +1,272 @@
+/**
+ * App-server replay mock for integration tests.
+ *
+ * Replaces the old `@openai/codex-sdk` replay mock. The mock AppServerClient
+ * replays fixture events as JSON-RPC notifications (item/started, item/completed,
+ * turn/completed, turn/failed) instead of SDK async generators.
+ *
+ * The fixture format is unchanged — events use SDK-style names (thread.started,
+ * item.started, etc.) which are translated to app-server notification names
+ * (thread/started, item/started, etc.) by the mock.
+ */
+
+import { EventEmitter } from 'node:events';
+
+/** A single event captured from the real SDK (or app-server). */
+type FixtureEvent = Record<string, unknown>;
+
+/** A captured interaction (events for one turn). */
+interface ReplayCall {
+  prompt: string;
+  events: FixtureEvent[];
+  eventDelay?: number;
+}
+
+/** A captured title generation interaction. */
+interface TitleCall {
+  prompt: string;
+  result: { finalResponse: string };
+}
+
+/** A complete fixture — all interactions for one test scenario. */
+export interface Fixture {
+  name: string;
+  description: string;
+  threadId: string;
+  runStreamedCalls: ReplayCall[];
+  runCalls: TitleCall[];
+}
+
+/** Read a fixture from a JSON string. */
+export function parseFixture(json: string): Fixture {
+  return JSON.parse(json) as Fixture;
+}
+
+/** Map SDK event type to app-server notification method. */
+function sdkEventToNotification(eventType: string): string {
+  switch (eventType) {
+    case 'thread.started':
+      return 'thread/started';
+    case 'item.started':
+      return 'item/started';
+    case 'item.updated':
+      return 'item/updated';
+    case 'item.completed':
+      return 'item/completed';
+    case 'item.agentMessage.delta':
+      return 'item/agentMessage/delta';
+    case 'turn.completed':
+      return 'turn/completed';
+    case 'thread.tokenUsage.updated':
+      return 'thread/tokenUsage/updated';
+    case 'error':
+      return 'turn/failed';
+    default:
+      return eventType;
+  }
+}
+
+/** Map an SDK event to app-server notification params. */
+function sdkEventToParams(event: FixtureEvent, threadId: string, turnId: string): Record<string, unknown> {
+  const type = event.type as string;
+
+  if (type === 'turn.completed') {
+    // Real app-server sends { threadId, turn: { id, status } } — no usage.
+    // Token usage arrives via separate thread/tokenUsage/updated notification.
+    return {
+      threadId,
+      turnId,
+    };
+  }
+
+  if (type === 'error') {
+    return {
+      threadId,
+      turnId,
+      error: { message: event.message as string },
+    };
+  }
+
+  if (type === 'item.agentMessage.delta') {
+    return {
+      threadId,
+      turnId,
+      itemId: event.itemId as string,
+      delta: event.delta as string,
+    };
+  }
+
+  if (type === 'thread.tokenUsage.updated') {
+    const usage = event.tokenUsage as {
+      inputTokens: number;
+      cachedInputTokens: number;
+      cacheWriteInputTokens: number;
+      outputTokens: number;
+      reasoningOutputTokens: number;
+      totalTokens: number;
+    };
+    return {
+      threadId,
+      turnId,
+      tokenUsage: {
+        total: usage,
+        last: usage,
+        modelContextWindow: event.modelContextWindow ?? 258400,
+      },
+    };
+  }
+
+  // item.* events
+  return {
+    threadId,
+    turnId,
+    item: event.item as Record<string, unknown>,
+  };
+}
+
+/**
+ * Create a mock AppServerClient class that replays fixture events.
+ *
+ * @param fixture — The fixture to replay.
+ * @returns A class that can be used to mock the AppServerClient module.
+ */
+export function createAppServerMock(fixture: Fixture) {
+  return class MockAppServerClient {
+    readonly events = new EventEmitter();
+    private notificationHandlers = new Map<string, Array<(params: unknown) => void>>();
+    private closed = false;
+    private interrupted = false;
+    private turnStartIndex = 0;
+    private titleCallIndex = 0;
+
+    async initialize(): Promise<{ userAgent: string }> {
+      return { userAgent: 'mock/0.147.0' };
+    }
+
+    async request<T>(method: string, params?: unknown): Promise<T> {
+      if (this.closed) throw new Error('MockAppServerClient is closed');
+
+      switch (method) {
+        case 'thread/start':
+        case 'thread/resume':
+          return { thread: { id: fixture.threadId } } as T;
+
+        case 'turn/start': {
+          // Detect title generation by checking input prompt prefix
+          const inputText = (params as { input?: Array<{ text?: string }> })?.input?.[0]?.text ?? '';
+          const isTitleGen = inputText.startsWith('Generate a concise 3-5 word title');
+
+          if (isTitleGen) {
+            // Title generation — use runCalls
+            if (this.titleCallIndex < fixture.runCalls.length) {
+              const call = fixture.runCalls[this.titleCallIndex];
+              this.titleCallIndex++;
+
+              const turnId = `title_${this.titleCallIndex}`;
+              this.replayTitleCall(call, fixture.threadId, turnId);
+
+              return { turn: { id: turnId } } as T;
+            }
+            // No more title calls — return empty turn
+            return { turn: { id: 'empty_title' } } as T;
+          }
+
+          // Main turns use runStreamedCalls
+          if (this.turnStartIndex < fixture.runStreamedCalls.length) {
+            const call = fixture.runStreamedCalls[this.turnStartIndex];
+            this.turnStartIndex++;
+
+            const turnId = `turn_${this.turnStartIndex}`;
+            this.replayEvents(call, fixture.threadId, turnId);
+
+            return { turn: { id: turnId } } as T;
+          }
+
+          // No more fixture calls — return empty turn (no events)
+          return { turn: { id: 'empty' } } as T;
+        }
+
+        case 'turn/interrupt':
+          this.interrupted = true;
+          return {} as T;
+
+        default:
+          return {} as T;
+      }
+    }
+
+    notify(): void {
+      // No-op
+    }
+
+    onNotification(method: string, handler: (params: unknown) => void): void {
+      const handlers = this.notificationHandlers.get(method) ?? [];
+      handlers.push(handler);
+      this.notificationHandlers.set(method, handlers);
+    }
+
+    onRequest(): void {
+      // No-op
+    }
+
+    isClosed(): boolean {
+      return this.closed;
+    }
+
+    async close(): Promise<void> {
+      this.closed = true;
+    }
+
+    /** Replay fixture events as notifications with optional delay. */
+    private async replayEvents(call: ReplayCall, threadId: string, turnId: string): Promise<void> {
+      for (const event of call.events) {
+        if (this.interrupted) {
+          // On interrupt, stop replaying — codex-provider handles DB update + broadcast
+          return;
+        }
+
+        if (call.eventDelay) {
+          await new Promise((r) => setTimeout(r, call.eventDelay));
+        }
+
+        const type = event.type as string;
+        const method = sdkEventToNotification(type);
+        const params = sdkEventToParams(event, threadId, turnId);
+
+        this.emitNotification(method, params);
+      }
+    }
+
+    /** Replay a title generation call as notifications (item/completed + turn/completed). */
+    private async replayTitleCall(call: TitleCall, threadId: string, turnId: string): Promise<void> {
+      // Simulate: agent_message item started → completed → turn completed
+      this.emitNotification('item/started', {
+        threadId,
+        turnId,
+        item: { id: 'title_item', type: 'agent_message', text: '' },
+      });
+
+      this.emitNotification('item/completed', {
+        threadId,
+        turnId,
+        item: { id: 'title_item', type: 'agent_message', text: call.result.finalResponse },
+      });
+
+      this.emitNotification('turn/completed', {
+        threadId,
+        turnId,
+      });
+    }
+
+    /** Emit a notification to all registered handlers for the method. */
+    private emitNotification(method: string, params: unknown): void {
+      const handlers = this.notificationHandlers.get(method);
+      if (handlers) {
+        for (const handler of handlers) {
+          handler(params);
+        }
+      }
+      this.events.emit('notification', method, params);
+    }
+  };
+}

package/agent-pane/backend/src/integration/helpers/test-app.ts

@@ -0,0 +1,108 @@
+/**
+ * Test app factory for integration tests.
+ *
+ * Sets up a Fastify instance with all route handlers registered, using
+ * an in-memory SQLite database. The `app-server-client.ts` module is mocked
+ * by the test file (not here) using `createAppServerMock(fixture)`.
+ *
+ * Usage in a test file:
+ * ```ts
+ * vi.mock('../codex/app-server-client.ts', () => ({ AppServerClient: createAppServerMock(fixture) }));
+ * vi.mock('../../ws/index.ts', () => ({ ...realWs, broadcast: mockBroadcast }));
+ * const { app, db } = await createTestApp();
+ * ```
+ */
+
+import Fastify, { type FastifyInstance } from 'fastify';
+import type Database from 'better-sqlite3';
+import { initDb } from '../../db/index.ts';
+import { initWs } from '../../ws/index.ts';
+import { registerSessionRoutes } from '../../routes/sessions.ts';
+import { registerTurnRoutes } from '../../routes/turns.ts';
+import { registerWorkspaceRoutes } from '../../routes/workspaces.ts';
+import { clearAllProviders } from '../../providers/registry.ts';
+import '../../providers/index.ts'; // register providers for integration tests
+
+export interface TestApp {
+  app: FastifyInstance;
+  db: Database.Database;
+  /** Close the Fastify instance and close the DB. */
+  cleanup: () => Promise<void>;
+}
+
+/**
+ * Create a test Fastify app with all routes and an in-memory DB.
+ *
+ * @returns `{ app, db, cleanup }`. Call `cleanup()` in `afterEach`.
+ */
+export async function createTestApp(): Promise<TestApp> {
+  const db = initDb(':memory:');
+
+  const app = Fastify();
+
+  await registerSessionRoutes(app);
+  await registerTurnRoutes(app);
+  await registerWorkspaceRoutes(app);
+
+  initWs();
+
+  return {
+    app,
+    db,
+    cleanup: async () => {
+      clearAllProviders();
+      await app.close();
+      db.close();
+    },
+  };
+}
+
+/**
+ * Wait for a turn to reach a terminal status by polling the DB.
+ *
+ * `startTurn()` is fire-and-forget — the HTTP POST returns immediately.
+ * Integration tests must wait for the async turn to finish before
+ * asserting on DB state or WS broadcasts.
+ *
+ * @param db — The in-memory DB instance.
+ * @param turnId — The turn ID to poll.
+ * @param timeoutMs — Max wait time (default 5000ms).
+ * @throws If the turn does not reach a terminal status within the timeout.
+ */
+export async function waitForTurn(db: Database.Database, turnId: string, timeoutMs = 5000): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const row = db.prepare('SELECT status FROM turns WHERE id = ?').get(turnId) as { status: string } | undefined;
+    if (!row) {
+      throw new Error(`Turn ${turnId} not found in DB`);
+    }
+    if (row.status === 'completed' || row.status === 'failed' || row.status === 'aborted') {
+      return;
+    }
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  throw new Error(`Turn ${turnId} did not complete within ${timeoutMs}ms`);
+}
+
+/** Insert a session row with sensible defaults for integration tests. */
+export function insertTestSession(db: Database.Database, id: string, overrides: Record<string, unknown> = {}): void {
+  const now = new Date().toISOString();
+  db.prepare(
+    `INSERT INTO sessions (id, title, runtime_type, model, model_reasoning_effort, cwd, external_thread_id, status, is_running, lifecycle, has_unreviewed, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  ).run(
+    id,
+    (overrides['title'] as string | null) ?? null,
+    (overrides['runtime_type'] as string) ?? 'codex',
+    (overrides['model'] as string | null) ?? null,
+    (overrides['model_reasoning_effort'] as string | null) ?? null,
+    (overrides['cwd'] as string | null) ?? null,
+    (overrides['external_thread_id'] as string | null) ?? null,
+    (overrides['status'] as string) ?? 'active',
+    (overrides['is_running'] as number) ?? 0,
+    (overrides['lifecycle'] as string) ?? 'working',
+    (overrides['has_unreviewed'] as number) ?? 0,
+    (overrides['created_at'] as string) ?? now,
+    (overrides['updated_at'] as string) ?? now,
+  );
+}

package/agent-pane/backend/src/integration/helpers/ws-capture.ts

@@ -0,0 +1,64 @@
+/**
+ * Broadcast capture helper for integration tests.
+ *
+ * Replaces the real `broadcast()` function in `ws/index.ts` with a spy
+ * that records every call. This lets integration tests assert on the
+ * exact sequence of WS events without connecting a real WebSocket client.
+ */
+
+export interface CapturedBroadcast {
+  event: string;
+  data: unknown;
+}
+
+/** A list of captured broadcast calls, populated by the mock. */
+export const capturedBroadcasts: CapturedBroadcast[] = [];
+
+/** Clear all captured broadcasts. Call in `beforeEach`. */
+export function clearBroadcasts(): void {
+  capturedBroadcasts.length = 0;
+}
+
+/**
+ * Mock broadcast function — records the call into `capturedBroadcasts`.
+ * Drop-in replacement for the real `broadcast()` in `ws/index.ts`.
+ */
+export function mockBroadcast(event: string, data: unknown): void {
+  capturedBroadcasts.push({ event, data });
+}
+
+/**
+ * Assert that broadcasts contain a specific event type.
+ * @param event — The event name to find (e.g. 'turn:started').
+ * @returns The first matching broadcast's data.
+ * @throws If no matching broadcast is found.
+ */
+export function findBroadcast(event: string): unknown {
+  const found = capturedBroadcasts.find((b) => b.event === event);
+  if (!found) {
+    const events = capturedBroadcasts.map((b) => b.event).join(', ');
+    throw new Error(`Expected broadcast "${event}" not found. Actual broadcasts: [${events}]`);
+  }
+  return found.data;
+}
+
+/**
+ * Assert the ordered sequence of broadcast event names.
+ * @param expected — Array of event names in expected order.
+ */
+export function expectBroadcastSequence(expected: string[]): void {
+  const actual = capturedBroadcasts.map((b) => b.event);
+  if (actual.length < expected.length) {
+    throw new Error(
+      `Expected ${expected.length} broadcasts but got ${actual.length}. ` +
+        `Expected: [${expected.join(', ')}]. Actual: [${actual.join(', ')}]`,
+    );
+  }
+  for (let i = 0; i < expected.length; i++) {
+    if (actual[i] !== expected[i]) {
+      throw new Error(
+        `Broadcast ${i}: expected "${expected[i]}" but got "${actual[i]}". ` + `Full actual: [${actual.join(', ')}]`,
+      );
+    }
+  }
+}

package/agent-pane/backend/src/integration/item-lifecycle.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Integration test: item lifecycle across multiple item types.
+ *
+ * Verifies that handleEvent correctly processes all item types through
+ * item-mapper, including status transitions, thoughts accumulation,
+ * and WS broadcasts for each item event.
+ *
+ * Uses HTTP POST to trigger the turn (fire-and-forget startTurn).
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type Database from 'better-sqlite3';
+import { createAppServerMock, type Fixture } from './helpers/app-server-mock.ts';
+import { clearBroadcasts, capturedBroadcasts } from './helpers/ws-capture.ts';
+import type { TestApp } from './helpers/test-app.ts';
+
+const fixture = JSON.parse(readFileSync(resolve(__dirname, '__fixtures__/multi-item-turn.json'), 'utf-8')) as Fixture;
+
+vi.mock('../codex/app-server-client.ts', () => ({
+  AppServerClient: createAppServerMock(fixture),
+}));
+
+vi.mock('../ws/index.ts', async (importOriginal) => {
+  const actual = (await importOriginal()) as Record<string, unknown>;
+  return {
+    ...actual,
+    broadcast: vi.fn((event: string, data: unknown) => {
+      capturedBroadcasts.push({ event, data });
+    }),
+  };
+});
+
+const { getDb } = await import('../db/index.ts');
+const { createTestApp, waitForTurn } = await import('./helpers/test-app.ts');
+
+describe('Integration: item lifecycle', () => {
+  let testApp: TestApp;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    clearBroadcasts();
+    testApp = await createTestApp();
+  });
+
+  afterEach(async () => {
+    await testApp.cleanup();
+  });
+
+  it('processes reasoning, command, file_change, agent_message items correctly', async () => {
+    const db: Database.Database = getDb();
+
+    // Create session
+    const createRes = await testApp.app.inject({
+      method: 'POST',
+      url: '/api/sessions',
+      payload: {},
+    });
+    const session = createRes.json();
+
+    // Submit turn via HTTP
+    const turnRes = await testApp.app.inject({
+      method: 'POST',
+      url: `/api/sessions/${session.id}/turns`,
+      payload: { user_prompt: 'List files and create a test file' },
+    });
+    const turn = turnRes.json();
+
+    await waitForTurn(db, turn.id);
+
+    // Assert items in DB — all 4 types mapped correctly
+    const items = db.prepare('SELECT * FROM items WHERE turn_id = ? ORDER BY created_at ASC').all(turn.id) as {
+      type: string;
+      data: string;
+      status: string;
+    }[];
+
+    expect(items).toHaveLength(4);
+
+    // Reasoning
+    expect(items[0].type).toBe('reasoning');
+    expect(items[0].status).toBe('completed');
+    expect(JSON.parse(items[0].data)).toEqual({
+      text: 'I need to list files first, then create a test file.',
+    });
+
+    // Command execution
+    expect(items[1].type).toBe('command_execution');
+    expect(items[1].status).toBe('completed');
+    expect(JSON.parse(items[1].data)).toEqual({
+      command: 'ls -la',
+      aggregated_output: 'total 0\ndrwxr-xr-x 2 user staff 64 Jan 1 00:00 .',
+      exit_code: 0,
+      status: 'completed',
+    });
+
+    // File change
+    expect(items[2].type).toBe('file_change');
+    expect(items[2].status).toBe('completed');
+    expect(JSON.parse(items[2].data)).toEqual({
+      changes: [{ path: 'test.txt', change_type: 'added' }],
+      status: 'completed',
+    });
+
+    // Agent message
+    expect(items[3].type).toBe('agent_message');
+    expect(items[3].status).toBe('completed');
+    expect(JSON.parse(items[3].data)).toEqual({
+      text: 'I listed the files and created test.txt for you.',
+    });
+
+    // Assert turn-level fields updated from items
+    const dbTurn = db.prepare('SELECT thoughts, agent_response FROM turns WHERE id = ?').get(turn.id) as {
+      thoughts: string | null;
+      agent_response: string | null;
+    };
+    expect(dbTurn.thoughts).toBe('I need to list files first, then create a test file.');
+    expect(dbTurn.agent_response).toBe('I listed the files and created test.txt for you.');
+
+    // Assert WS broadcasts — 4 item:started + 4 item:completed
+    const startedCount = capturedBroadcasts.filter((b) => b.event === 'item:started').length;
+    const completedCount = capturedBroadcasts.filter((b) => b.event === 'item:completed').length;
+    expect(startedCount).toBe(4);
+    expect(completedCount).toBe(4);
+
+    // Verify item:completed broadcasts contain correct item types
+    const completedTypes = capturedBroadcasts
+      .filter((b) => b.event === 'item:completed')
+      .map((b) => (b.data as { item: { type: string } }).item.type);
+    expect(completedTypes).toEqual(['reasoning', 'command_execution', 'file_change', 'agent_message']);
+  });
+});

package/agent-pane/backend/src/integration/mcp-tool-call.test.ts

@@ -0,0 +1,102 @@
+/**
+ * Integration test: MCP tool call item type.
+ *
+ * Verifies that mcp_tool_call items are correctly mapped via item-mapper
+ * and stored in DB with the right data shape.
+ *
+ * Uses HTTP POST to trigger the turn (fire-and-forget startTurn).
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type Database from 'better-sqlite3';
+import { createAppServerMock, type Fixture } from './helpers/app-server-mock.ts';
+import { clearBroadcasts, capturedBroadcasts } from './helpers/ws-capture.ts';
+import type { TestApp } from './helpers/test-app.ts';
+
+const fixture = JSON.parse(readFileSync(resolve(__dirname, '__fixtures__/mcp-tool-call.json'), 'utf-8')) as Fixture;
+
+vi.mock('../codex/app-server-client.ts', () => ({
+  AppServerClient: createAppServerMock(fixture),
+}));
+
+vi.mock('../ws/index.ts', async (importOriginal) => {
+  const actual = (await importOriginal()) as Record<string, unknown>;
+  return {
+    ...actual,
+    broadcast: vi.fn((event: string, data: unknown) => {
+      capturedBroadcasts.push({ event, data });
+    }),
+  };
+});
+
+const { getDb } = await import('../db/index.ts');
+const { createTestApp, waitForTurn } = await import('./helpers/test-app.ts');
+
+describe('Integration: MCP tool call', () => {
+  let testApp: TestApp;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    clearBroadcasts();
+    testApp = await createTestApp();
+  });
+
+  afterEach(async () => {
+    await testApp.cleanup();
+  });
+
+  it('maps mcp_tool_call item with server, tool, arguments, result', async () => {
+    const db: Database.Database = getDb();
+
+    // Create session
+    const createRes = await testApp.app.inject({
+      method: 'POST',
+      url: '/api/sessions',
+      payload: {},
+    });
+    const session = createRes.json();
+
+    // Submit turn via HTTP
+    const turnRes = await testApp.app.inject({
+      method: 'POST',
+      url: `/api/sessions/${session.id}/turns`,
+      payload: { user_prompt: 'Search the web for cats' },
+    });
+    const turn = turnRes.json();
+
+    await waitForTurn(db, turn.id);
+
+    const items = db.prepare('SELECT * FROM items WHERE turn_id = ? ORDER BY created_at ASC').all(turn.id) as {
+      type: string;
+      data: string;
+      status: string;
+    }[];
+    expect(items).toHaveLength(2);
+
+    // MCP tool call
+    expect(items[0].type).toBe('mcp_tool_call');
+    expect(items[0].status).toBe('completed');
+    expect(JSON.parse(items[0].data)).toEqual({
+      server: 'web-search',
+      tool: 'search',
+      arguments: { query: 'cats' },
+      result: { urls: ['https://example.com/cats'] },
+      error: null,
+      status: 'completed',
+    });
+
+    // Agent message
+    expect(items[1].type).toBe('agent_message');
+    expect(items[1].status).toBe('completed');
+
+    // Verify WS: mcp item:started has in_progress status
+    const mcpStarted = capturedBroadcasts.find(
+      (b) => b.event === 'item:started' && (b.data as { item: { type: string } }).item.type === 'mcp_tool_call',
+    );
+    expect(mcpStarted).toBeDefined();
+    const mcpStartedData = mcpStarted!.data as { item: { status: string } };
+    expect(mcpStartedData.item.status).toBe('in_progress');
+  });
+});