repoburg 1.3.199 → 1.3.202

package/agent-pane/backend/src/integration/threads-claude-fork.test.ts

@@ -0,0 +1,241 @@
+/**
+ * Integration test: discussion threads — Claude fork isolation (BUG 1 + BUG 2).
+ *
+ * Exercises the REAL claudeProvider + REAL thread routes with a mocked Claude
+ * SDK (`query` + `forkSession`). Verifies that creating a Discuss thread forks
+ * the main session, stores the fork id on the thread row, and never corrupts
+ * the main session's `external_thread_id`; and that a failed fork starts a
+ * fresh isolated session instead of resuming (and contaminating) the main
+ * session.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import type Database from 'better-sqlite3';
+import { clearBroadcasts, capturedBroadcasts } from './helpers/ws-capture.ts';
+import type { TestApp } from './helpers/test-app.ts';
+
+// Mock the Claude SDK — both the query factory and forkSession.
+vi.mock('@anthropic-ai/claude-agent-sdk', () => ({
+  query: vi.fn(),
+  forkSession: vi.fn(),
+}));
+
+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 });
+    }),
+  };
+});
+
+// Import after mocks are set up.
+import { query, forkSession } from '@anthropic-ai/claude-agent-sdk';
+import { clearAllThreads } from '../claude/claude-provider.ts';
+const { getDb } = await import('../db/index.ts');
+const { createTestApp, insertTestSession, waitForTurn } = await import('./helpers/test-app.ts');
+
+// ---------------------------------------------------------------------------
+// Mock helpers
+// ---------------------------------------------------------------------------
+
+/** Build a mock `Query` whose async iterator yields the given SDK messages in
+ *  order, then ends. getContextUsage resolves an empty snapshot (0/0) so the
+ *  result/success handler completes the turn without emitting contextUsage. */
+function createClaudeQueryMock(messages: unknown[]): unknown {
+  return {
+    getContextUsage: vi.fn().mockResolvedValue({
+      totalTokens: 0, maxTokens: 0, rawMaxTokens: 0, percentage: 0,
+      categories: [], gridRows: [], model: '', memoryFiles: [], mcpTools: [],
+    }),
+    interrupt: vi.fn(),
+    setModel: vi.fn(),
+    close: vi.fn(),
+    stopTask: vi.fn(),
+    initializationResult: vi.fn(),
+    [Symbol.asyncIterator]: async function* () {
+      for (const m of messages) yield m;
+    },
+  };
+}
+
+/** A `system/init` SDK message carrying the given Claude session id. */
+function initMsg(claudeSessionId: string): unknown {
+  return { type: 'system', subtype: 'init', session_id: claudeSessionId };
+}
+
+/** A `result/success` SDK message that completes a turn. */
+function resultSuccessMsg(claudeSessionId: string): unknown {
+  return {
+    type: 'result', subtype: 'success',
+    usage: { input_tokens: 10, cache_read_input_tokens: 0, cache_creation_input_tokens: 0, output_tokens: 5 },
+    modelUsage: {}, result: 'done', is_error: false, num_turns: 1,
+    stop_reason: 'end_turn', duration_ms: 1, duration_api_ms: 1, total_cost_usd: 0,
+    permission_denials: [], uuid: 'u1', session_id: claudeSessionId,
+  };
+}
+
+describe('Integration: discussion threads — Claude fork isolation', () => {
+  let testApp: TestApp;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    clearAllThreads();
+    clearBroadcasts();
+    testApp = await createTestApp();
+  });
+
+  afterEach(async () => {
+    clearAllThreads();
+    await testApp.cleanup();
+  });
+
+  /** Seed a Claude session + anchor turn/item, ready for a thread creation. */
+  function seedSession(db: Database.Database): void {
+    insertTestSession(db, 's1', { runtime_type: 'claude', external_thread_id: 'main-1', title: 'Test' });
+    const now = '2025-01-01T00:00:00Z';
+    db.prepare(
+      `INSERT INTO turns (id, session_id, user_prompt, agent_response, status, external_turn_id, created_at, updated_at)
+       VALUES ('t1', 's1', 'prompt', 'response', 'completed', 'msg-uuid-1', ?, ?)`,
+    ).run(now, now);
+    db.prepare(
+      `INSERT INTO items (id, turn_id, external_item_id, type, data, status, created_at, updated_at)
+       VALUES ('i1', 't1', 'ext1', 'agent_message', ?, 'completed', ?, ?)`,
+    ).run(JSON.stringify({ text: 'Some text to discuss' }), now, now);
+  }
+
+  /** The shared thread-creation POST payload. */
+  const threadPayload = {
+    itemId: 'i1',
+    turnId: 't1',
+    startOffset: 0,
+    endOffset: 10,
+    selectedText: 'Some text ',
+    message: 'What does this mean?',
+  };
+
+  it('successful fork: stores fork id, resumes the fork, does NOT corrupt the main session (BUG 1 + BUG 2)', async () => {
+    const db: Database.Database = getDb();
+    seedSession(db);
+
+    // forkSession returns a new forked session id.
+    vi.mocked(forkSession).mockResolvedValue({ sessionId: 'fork-9' } as never);
+    // The forked query emits init with the FORK's id, then completes the turn.
+    vi.mocked(query).mockReturnValue(createClaudeQueryMock([initMsg('fork-9'), resultSuccessMsg('fork-9')]) as never);
+
+    const res = await testApp.app.inject({
+      method: 'POST',
+      url: '/api/sessions/s1/threads',
+      payload: threadPayload,
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    const threadId = body.thread.id as string;
+    const turnId = body.turn.id as string;
+
+    // forkSession was called with the MAIN session id + the anchor turn's message UUID.
+    expect(vi.mocked(forkSession).mock.calls[0][0]).toBe('main-1');
+    expect((vi.mocked(forkSession).mock.calls[0][1] as { upToMessageId?: string }).upToMessageId).toBe('msg-uuid-1');
+
+    // The fork id is stored on the THREAD row, not the main session.
+    const threadRow = db.prepare('SELECT external_thread_id FROM discussion_threads WHERE id = ?').get(threadId) as
+      | { external_thread_id: string | null }
+      | undefined;
+    expect(threadRow?.external_thread_id).toBe('fork-9');
+
+    // Wait for the thread turn to complete, then assert the main session is intact.
+    await waitForTurn(db, turnId);
+
+    // BUG 2: the thread turn resumed its OWN fork ('fork-9'), not the main session.
+    const opts = (vi.mocked(query).mock.calls[0][0] as { options: { resume?: string } }).options;
+    expect(opts.resume).toBe('fork-9');
+
+    // BUG 1: the main session's external_thread_id was NOT overwritten with the fork's id.
+    const sessionRow = db.prepare('SELECT external_thread_id FROM sessions WHERE id = ?').get('s1') as
+      | { external_thread_id: string | null }
+      | undefined;
+    expect(sessionRow?.external_thread_id).toBe('main-1');
+
+    // thread:created was broadcast.
+    expect(capturedBroadcasts.find((b) => b.event === 'thread:created')).toBeDefined();
+  });
+
+  it('failed fork (null): thread still created, starts a FRESH session (resume undefined), main session untouched (BUG 2)', async () => {
+    const db: Database.Database = getDb();
+    seedSession(db);
+
+    // forkSession returns null (e.g. no main session to fork from, or SDK refused).
+    vi.mocked(forkSession).mockResolvedValue(null as never);
+    // The fresh isolated session emits its own init id, then completes.
+    vi.mocked(query).mockReturnValue(createClaudeQueryMock([initMsg('fresh-1'), resultSuccessMsg('fresh-1')]) as never);
+
+    const res = await testApp.app.inject({
+      method: 'POST',
+      url: '/api/sessions/s1/threads',
+      payload: threadPayload,
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    const threadId = body.thread.id as string;
+    const turnId = body.turn.id as string;
+
+    // The thread row has NO fork id.
+    const threadRow = db.prepare('SELECT external_thread_id FROM discussion_threads WHERE id = ?').get(threadId) as
+      | { external_thread_id: string | null }
+      | undefined;
+    expect(threadRow?.external_thread_id).toBeNull();
+
+    await waitForTurn(db, turnId);
+
+    // BUG 2: the thread started a FRESH session — no `resume` option — and did
+    // NOT fall back to the main session's 'main-1'.
+    const opts = (vi.mocked(query).mock.calls[0][0] as { options: { resume?: string } }).options;
+    expect(opts.resume).toBeUndefined();
+
+    // The main session is untouched.
+    const sessionRow = db.prepare('SELECT external_thread_id FROM sessions WHERE id = ?').get('s1') as
+      | { external_thread_id: string | null }
+      | undefined;
+    expect(sessionRow?.external_thread_id).toBe('main-1');
+  });
+
+  it('failed fork (throws): caught, thread still created, main session untouched (BUG 2)', async () => {
+    const db: Database.Database = getDb();
+    seedSession(db);
+
+    // forkSession throws — the route must catch it and still create the thread.
+    vi.mocked(forkSession).mockRejectedValue(new Error('boom') as never);
+    vi.mocked(query).mockReturnValue(createClaudeQueryMock([initMsg('fresh-2'), resultSuccessMsg('fresh-2')]) as never);
+
+    const res = await testApp.app.inject({
+      method: 'POST',
+      url: '/api/sessions/s1/threads',
+      payload: threadPayload,
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    const threadId = body.thread.id as string;
+    const turnId = body.turn.id as string;
+
+    // The thread row has NO fork id (fork threw before storing anything).
+    const threadRow = db.prepare('SELECT external_thread_id FROM discussion_threads WHERE id = ?').get(threadId) as
+      | { external_thread_id: string | null }
+      | undefined;
+    expect(threadRow?.external_thread_id).toBeNull();
+
+    await waitForTurn(db, turnId);
+
+    // The thread started a fresh isolated session (no resume), not the main session.
+    const opts = (vi.mocked(query).mock.calls[0][0] as { options: { resume?: string } }).options;
+    expect(opts.resume).toBeUndefined();
+
+    const sessionRow = db.prepare('SELECT external_thread_id FROM sessions WHERE id = ?').get('s1') as
+      | { external_thread_id: string | null }
+      | undefined;
+    expect(sessionRow?.external_thread_id).toBe('main-1');
+  });
+});

package/agent-pane/backend/src/providers/index.ts

@@ -7,8 +7,10 @@
 
 import { codexProvider } from '../codex/codex-provider.ts';
 import { claudeProvider } from '../claude/claude-provider.ts';
+import { repoburgProvider } from '../repoburg/repoburg-provider.ts';
 import { registerProvider } from './registry.ts';
 
 // Register built-in providers
 registerProvider('codex', codexProvider);
-registerProvider('claude', claudeProvider);
+registerProvider('claude', claudeProvider);
+registerProvider('repoburg', repoburgProvider);

package/agent-pane/backend/src/providers/runtime-provider.ts

@@ -29,6 +29,12 @@ export interface RuntimeProvider {
    *  Returns the new provider-native session ID, or null if there is no thread to fork.
    *  Optional — providers without fork support omit it. */
   forkSession?(session: Session, targetTurn: Turn): Promise<string | null>;
+  /** Truncate the runtime session's history IN PLACE after the target turn
+   *  (platform-parity rewind: hard delete). Throws on failure — the caller
+   *  must NOT apply any local rewind when this fails.
+   *  Optional — providers without in-place truncation omit it (e.g. Claude
+   *  uses forkSession instead). */
+  rewindRuntime?(session: Session, targetTurn: Turn): Promise<void>;
   /** Change the model for a running session without restarting the CLI process.
    *  Only supported in streaming-input mode (Claude). If the session hasn't
    *  started yet, the new model is read from the DB on next startTurn.

package/agent-pane/backend/src/repoburg/action-mapping.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect } from 'vitest';
+import { mapActionToItem, parseSelectionGroups } from './action-mapping.ts';
+import type { RepoburgAction } from './repoburg-client.ts';
+
+function askUserAction(selections: string | null): RepoburgAction {
+  return {
+    id: 'a1',
+    action_type: 'ask_user',
+    status: 'CONFIRMED_KEPT',
+    selections,
+    order_of_execution: 0,
+  };
+}
+
+function subagentAction(status: string, output = ''): RepoburgAction {
+  return {
+    id: 'act-1',
+    action_type: 'invoke_subagent',
+    status,
+    arguments: JSON.stringify({ agent_name: 'explore-codebase', prompt: 'Find auth files' }),
+    order_of_execution: 0,
+    executionLogs: [{ output }],
+  };
+}
+
+describe('mapActionToItem — invoke_subagent', () => {
+  it('maps to a completed background_task card (snapshot/reload shape)', () => {
+    const mapped = mapActionToItem(subagentAction('CONFIRMED_KEPT', 'auth files found'));
+    expect(mapped).not.toBeNull();
+    expect(mapped!.type).toBe('background_task');
+    expect(mapped!.status).toBe('completed');
+    expect(mapped!.data).toMatchObject({
+      task_type: 'subagent',
+      subagent_type: 'explore-codebase',
+      description: 'Find auth files',
+      status: 'completed',
+      summary: 'auth files found',
+      last_tool_name: null,
+      token_count: null,
+    });
+  });
+
+  it('maps a failed invoke_subagent to a failed background_task with the error as summary', () => {
+    const action = {
+      ...subagentAction('EXECUTION_FAILED'),
+      executionLogs: [{ error_message: 'boom' }],
+    };
+    const mapped = mapActionToItem(action);
+    expect(mapped!.status).toBe('failed');
+    expect(mapped!.data).toMatchObject({ status: 'failed', summary: 'boom' });
+  });
+});
+describe('parseSelectionGroups', () => {
+  it('parses canonical [{question, selections[]}] groups', () => {
+    const raw = JSON.stringify([
+      { question: 'Which database?', selections: ['Postgres', 'SQLite'] },
+      { question: 'Proceed?', selections: ['yes', 'no'] },
+    ]);
+    expect(parseSelectionGroups(raw)).toEqual([
+      { question: 'Which database?', selections: ['Postgres', 'SQLite'] },
+      { question: 'Proceed?', selections: ['yes', 'no'] },
+    ]);
+  });
+
+  it('coerces flat string arrays into single-option groups', () => {
+    expect(parseSelectionGroups(JSON.stringify(['Yes', 'No']))).toEqual([
+      { question: '', selections: ['Yes'] },
+      { question: '', selections: ['No'] },
+    ]);
+  });
+
+  it('drops invalid entries and non-string options', () => {
+    const raw = JSON.stringify([
+      { question: 'Q', selections: ['ok', 42] },
+      null,
+      { question: 'No options', selections: [] },
+    ]);
+    expect(parseSelectionGroups(raw)).toEqual([{ question: 'Q', selections: ['ok'] }]);
+  });
+
+  it('returns [] for malformed JSON, null, and non-array payloads', () => {
+    expect(parseSelectionGroups('not json')).toEqual([]);
+    expect(parseSelectionGroups(null)).toEqual([]);
+    expect(parseSelectionGroups('{"question":"q"}')).toEqual([]);
+  });
+});
+
+describe('mapActionToItem — ask_user', () => {
+  it('maps to an ask_user item with parsed groups', () => {
+    const raw = JSON.stringify([
+      { question: 'Which database?', selections: ['Postgres', 'SQLite'] },
+    ]);
+    const mapped = mapActionToItem(askUserAction(raw));
+    expect(mapped).not.toBeNull();
+    expect(mapped!.type).toBe('ask_user');
+    expect(mapped!.status).toBe('completed');
+    expect(mapped!.data).toEqual({
+      question: '',
+      groups: [{ question: 'Which database?', selections: ['Postgres', 'SQLite'] }],
+    });
+  });
+
+  it('falls back to a plain-text question card on malformed selections', () => {
+    const mapped = mapActionToItem(askUserAction('Plain question?'));
+    expect(mapped).not.toBeNull();
+    expect(mapped!.type).toBe('ask_user');
+    expect(mapped!.data).toEqual({ question: 'Plain question?', groups: [] });
+  });
+
+  it('maps without selections to a question card with the raw payload as text', () => {
+    const mapped = mapActionToItem(askUserAction('Which one?\n["A","B"]'));
+    expect(mapped).not.toBeNull();
+    expect(mapped!.data).toEqual({ question: 'Which one?\n["A","B"]', groups: [] });
+  });
+
+  it('maps a failed ask_user action to a failed item', () => {
+    const raw = JSON.stringify([{ question: 'Q?', selections: ['a', 'b'] }]);
+    const action = { ...askUserAction(raw), status: 'EXECUTION_FAILED' };
+    const mapped = mapActionToItem(action);
+    expect(mapped!.status).toBe('failed');
+  });
+});

package/agent-pane/backend/src/repoburg/action-mapping.ts

@@ -0,0 +1,294 @@
+/**
+ * Shared mapping helpers for the repoburg provider: repoburg AIAction →
+ * agent-pane item shapes, DB item helpers, and usage mapping.
+ * Used by both the provider (turn orchestration) and the turn projector
+ * (message-stream projection).
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import type Database from 'better-sqlite3';
+import { broadcast } from '../ws/index.ts';
+import type { Item, ItemStatus } from '../db/schema.ts';
+import type { AskUserSelectionGroup, AskUserItemData } from '@agentpane/shared';
+import type { RepoburgAction } from './repoburg-client.ts';
+
+/** Safely parse a JSON string field from an action row. */
+export function parseJsonArgs(raw: string | null | undefined): Record<string, unknown> | null {
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed === 'object' && parsed !== null ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Parse a raw selections JSON string into validated groups (platform parity:
+ *  ActionItemContent.parseSelectionGroups). Never throws; flat-string arrays
+ *  coerce into single-option groups; invalid entries are dropped. */
+export function parseSelectionGroups(raw: string | null | undefined): AskUserSelectionGroup[] {
+  if (!raw) return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  return parsed
+    .map((item): AskUserSelectionGroup | null => {
+      if (item && typeof item === 'object' && !Array.isArray(item)) {
+        const obj = item as Record<string, unknown>;
+        if (Array.isArray(obj.selections)) {
+          const opts = obj.selections.filter((s): s is string => typeof s === 'string');
+          if (opts.length > 0) {
+            return {
+              question: typeof obj.question === 'string' ? obj.question : '',
+              selections: opts,
+            };
+          }
+        }
+        return null;
+      }
+      // Graceful coercion: flat string → single-option group.
+      if (typeof item === 'string') {
+        return { question: '', selections: [item] };
+      }
+      return null;
+    })
+    .filter((g): g is AskUserSelectionGroup => g !== null);
+}
+
+/** Map a repoburg AIAction (+ its first execution log) to an agent-pane item
+ *  shape. Returns null for actions that carry no displayable content
+ *  (final/html_final — their text is part of the LLM response). */
+export function mapActionToItem(
+  action: RepoburgAction,
+): { type: Item['type']; data: Record<string, unknown>; status: ItemStatus } | null {
+  const failed = action.status === 'EXECUTION_FAILED';
+  const status: ItemStatus = failed ? 'failed' : 'completed';
+  const log = action.executionLogs?.[0];
+  const output = log?.output ?? '';
+  const errorMsg = log?.error_message ?? '';
+
+  switch (action.action_type) {
+    case 'create_file':
+    case 'overwrite_file':
+    case 'patch':
+    case 'quick_edit':
+    case 'apply_diff':
+    case 'write_todo':
+    case 'delete_file': {
+      const kind =
+        action.action_type === 'create_file'
+          ? 'add'
+          : action.action_type === 'delete_file'
+            ? 'delete'
+            : 'modify';
+      return {
+        type: 'file_change',
+        data: { changes: [{ path: action.file_path ?? '', kind }], status },
+        status,
+      };
+    }
+
+    case 'run_command':
+    case 'execute_code':
+      return {
+        type: 'command_execution',
+        data: {
+          command: action.command_string ?? action.action_type,
+          aggregated_output: output,
+          exit_code: failed ? 1 : 0,
+          status,
+        },
+        status,
+      };
+
+    case 'invoke_subagent': {
+      // background_task completed form — Claude-provider data shape. Serves
+      // snapshot reconcile + reload; the live projector finalizes the same
+      // card through the identical external id `<inputId>-action-<actionId>`.
+      const args = parseJsonArgs(action.arguments);
+      const agentName = (args?.agent_name as string) ?? (args?.agentName as string) ?? 'Sub-agent';
+      const prompt = (args?.prompt as string) ?? '';
+      return {
+        type: 'background_task',
+        data: {
+          task_id: (args?.childSessionId as string) ?? '',
+          description: prompt || agentName,
+          task_type: 'subagent',
+          subagent_type: agentName,
+          prompt: prompt || null,
+          status: failed ? 'failed' : 'completed',
+          summary: output || (failed ? errorMsg || 'Sub-agent failed' : ''),
+          output_file: null,
+          output: '',
+          token_count: null,
+          last_tool_name: null,
+        },
+        status,
+      };
+    }
+
+    case 'web_search': {
+      const args = parseJsonArgs(action.arguments);
+      return { type: 'web_search', data: { query: (args?.query as string) ?? '' }, status };
+    }
+
+    case 'ask_user': {
+      // Rendered as clickable selection buttons in the frontend.
+      // Malformed payload → fallback plain-text question card.
+      const groups = parseSelectionGroups(action.selections);
+      const data: AskUserItemData = {
+        question: groups.length ? '' : (action.selections ?? ''),
+        groups,
+      };
+      return {
+        type: 'ask_user',
+        data: { question: data.question, groups: data.groups },
+        status,
+      };
+    }
+
+    case 'final':
+    case 'html_final':
+      // Their text is part of the LLM response — no separate item.
+      return null;
+
+    default: {
+      // MCP tools (serverName__toolName) and remaining built-ins → generic tool call.
+      const isMcp = !!(action.server_name && action.tool_name);
+      return {
+        type: 'mcp_tool_call',
+        data: {
+          server: isMcp ? action.server_name : null,
+          tool: isMcp ? action.tool_name : action.action_type,
+          arguments: parseJsonArgs(action.arguments),
+          result: output ? [{ type: 'text', text: output }] : null,
+          error: failed ? errorMsg || 'Action failed' : null,
+          status,
+        },
+        status,
+      };
+    }
+  }
+}
+
+/** Map repoburg token counts to the agent-pane TokenUsage shape. */
+export function mapUsage(u: {
+  input: number;
+  cached: number;
+  output: number;
+}): {
+  input_tokens: number;
+  cached_input_tokens: number;
+  cache_write_input_tokens: number;
+  output_tokens: number;
+  reasoning_output_tokens: number;
+} {
+  return {
+    input_tokens: u.input,
+    cached_input_tokens: u.cached,
+    cache_write_input_tokens: 0,
+    output_tokens: u.output,
+    reasoning_output_tokens: 0,
+  };
+}
+
+/** Update an item's data + status and broadcast the updated item. */
+export function updateItem(
+  db: Database.Database,
+  sessionId: string,
+  turnId: string,
+  item: Item,
+  data: Record<string, unknown>,
+  status: ItemStatus,
+): void {
+  const now = new Date().toISOString();
+  db.prepare('UPDATE items SET data = ?, status = ?, updated_at = ? WHERE id = ?').run(
+    JSON.stringify(data),
+    status,
+    now,
+    item.id,
+  );
+  const updated: Item = { ...item, data, status, updated_at: now };
+  broadcast('item:updated', { sessionId, turnId, item: updated });
+}
+
+/** Update the running state and status of a session. */
+export function setSessionStatus(
+  db: Database.Database,
+  sessionId: string,
+  isRunning: 0 | 1,
+  status: string,
+  now: string,
+  hasUnreviewed = false,
+): void {
+  if (hasUnreviewed) {
+    db.prepare('UPDATE sessions SET is_running = ?, status = ?, has_unreviewed = 1, updated_at = ? WHERE id = ?').run(
+      isRunning,
+      status,
+      now,
+      sessionId,
+    );
+  } else {
+    db.prepare('UPDATE sessions SET is_running = ?, status = ?, updated_at = ? WHERE id = ?').run(
+      isRunning,
+      status,
+      now,
+      sessionId,
+    );
+  }
+}
+
+/** Insert an item row and broadcast it. Returns the created item. */
+export function insertItem(
+  db: Database.Database,
+  sessionId: string,
+  turnId: string,
+  externalId: string,
+  type: Item['type'],
+  data: Record<string, unknown>,
+  status: ItemStatus,
+  broadcastEvent: 'item:started' | 'item:completed',
+): Item {
+  const now = new Date().toISOString();
+  const itemId = uuidv4();
+  db.prepare(
+    'INSERT INTO items (id, turn_id, external_item_id, type, data, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+  ).run(itemId, turnId, externalId, type, JSON.stringify(data), status, now, now);
+
+  const item: Item = {
+    id: itemId,
+    turn_id: turnId,
+    external_item_id: externalId,
+    type,
+    data,
+    status,
+    created_at: now,
+    updated_at: now,
+  };
+  broadcast(broadcastEvent, { sessionId, turnId, item });
+  return item;
+}
+
+/** Update an item's data + status and broadcast the completed item. */
+export function completeItem(
+  db: Database.Database,
+  sessionId: string,
+  turnId: string,
+  item: Item,
+  data: Record<string, unknown>,
+  status: ItemStatus,
+): void {
+  const now = new Date().toISOString();
+  db.prepare('UPDATE items SET data = ?, status = ?, updated_at = ? WHERE id = ?').run(
+    JSON.stringify(data),
+    status,
+    now,
+    item.id,
+  );
+  const updated: Item = { ...item, data, status, updated_at: now };
+  broadcast('item:completed', { sessionId, turnId, item: updated });
+}