repoburg 1.3.183 → 1.3.186

package/agent-pane/backend/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "agent-pane-backend",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "esbuild src/index.ts --bundle --platform=node --outfile=dist/index.js --format=esm",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@fastify/cors": "^10.0.0",
+    "@openai/codex-sdk": "^0.147.0",
+    "better-sqlite3": "^11.8.0",
+    "fastify": "^5.2.0",
+    "uuid": "^11.1.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22.10.0",
+    "@types/uuid": "^10.0.0",
+    "@types/ws": "^8.5.13",
+    "esbuild": "^0.24.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}

package/agent-pane/backend/src/codex/codex-provider.ts

@@ -0,0 +1,260 @@
+import { Codex, type Thread, type ThreadEvent, type ThreadItem, type ThreadOptions } from '@openai/codex-sdk';
+import { v4 as uuidv4 } from 'uuid';
+import { getDb } from '../db/index.ts';
+import { broadcast } from '../ws/index.ts';
+import { mapItemData, getItemStatus } from './item-mapper.ts';
+import type { Session, Turn, Item, ItemStatus } from '../db/schema.ts';
+
+interface ThreadEntry {
+  codex: Codex;
+  thread: Thread;
+  abortController: AbortController | null;
+}
+
+const threadMap = new Map<string, ThreadEntry>();
+
+function getThreadOptions(session: Session): ThreadOptions {
+  return {
+    model: session.model ?? undefined,
+    workingDirectory: session.cwd ?? undefined,
+    sandboxMode: 'workspace-write',
+    approvalPolicy: 'never',
+    skipGitRepoCheck: true,
+  };
+}
+
+function getOrCreateThread(session: Session): { codex: Codex; thread: Thread } {
+  const existing = threadMap.get(session.id);
+  if (existing) {
+    return { codex: existing.codex, thread: existing.thread };
+  }
+
+  const codex = new Codex();
+  let thread: Thread;
+
+  if (session.external_thread_id) {
+    thread = codex.resumeThread(session.external_thread_id, getThreadOptions(session));
+  } else {
+    thread = codex.startThread(getThreadOptions(session));
+  }
+
+  return { codex, thread };
+}
+
+/** Start a Codex turn. Fire-and-forget — streams events via WS. */
+export async function startTurn(session: Session, turn: Turn): Promise<void> {
+  const db = getDb();
+
+  // Phase 1: create or resume thread
+  let codex: Codex;
+  let thread: Thread;
+
+  try {
+    const result = getOrCreateThread(session);
+    codex = result.codex;
+    thread = result.thread;
+  } catch (err) {
+    const errMsg = `Failed to create Codex thread: ${(err as Error).message}`;
+    const now = new Date().toISOString();
+    db.prepare('UPDATE turns SET status = ?, error = ?, updated_at = ? WHERE id = ?')
+      .run('failed', errMsg, now, turn.id);
+    db.prepare('UPDATE sessions SET is_running = 0, status = ?, updated_at = ? WHERE id = ?')
+      .run('failed', now, session.id);
+    broadcast('turn:failed', { sessionId: session.id, turnId: turn.id, error: errMsg });
+    return;
+  }
+
+  // Phase 2: set up abort controller and update status
+  const abortController = new AbortController();
+  threadMap.set(session.id, { codex, thread, abortController });
+
+  const now = new Date().toISOString();
+  db.prepare('UPDATE turns SET status = ?, updated_at = ? WHERE id = ?')
+    .run('running', now, turn.id);
+  db.prepare('UPDATE sessions SET is_running = 1, status = ?, updated_at = ? WHERE id = ?')
+    .run('running', now, session.id);
+
+  broadcast('turn:started', { sessionId: session.id, turnId: turn.id });
+
+  // Phase 3: run the turn and handle events
+  try {
+    const { events } = await thread.runStreamed(turn.user_prompt, { signal: abortController.signal });
+
+    for await (const event of events) {
+      handleEvent(event, session.id, turn.id);
+    }
+  } catch (err) {
+    const isAbort = abortController.signal.aborted || (err as Error).name === 'AbortError';
+    const errMsg = (err as Error).message;
+    const now2 = new Date().toISOString();
+
+    if (isAbort) {
+      db.prepare('UPDATE turns SET status = ?, updated_at = ? WHERE id = ?')
+        .run('aborted', now2, turn.id);
+      db.prepare('UPDATE sessions SET is_running = 0, status = ?, updated_at = ? WHERE id = ?')
+        .run('active', now2, session.id);
+      broadcast('turn:failed', { sessionId: session.id, turnId: turn.id, error: 'Turn cancelled by user' });
+    } else {
+      db.prepare('UPDATE turns SET status = ?, error = ?, updated_at = ? WHERE id = ?')
+        .run('failed', errMsg, now2, turn.id);
+      db.prepare('UPDATE sessions SET is_running = 0, status = ?, updated_at = ? WHERE id = ?')
+        .run('failed', now2, session.id);
+      broadcast('turn:failed', { sessionId: session.id, turnId: turn.id, error: errMsg });
+    }
+  } finally {
+    const entry = threadMap.get(session.id);
+    if (entry) {
+      threadMap.set(session.id, { ...entry, abortController: null });
+    }
+  }
+}
+
+/** Cancel a running turn by session ID. Returns true if a turn was cancelled. */
+export function interruptTurn(sessionId: string): boolean {
+  const entry = threadMap.get(sessionId);
+  if (entry?.abortController) {
+    entry.abortController.abort();
+    return true;
+  }
+  return false;
+}
+
+function handleEvent(event: ThreadEvent, sessionId: string, turnId: string): void {
+  const db = getDb();
+  const now = new Date().toISOString();
+
+  switch (event.type) {
+    case 'thread.started': {
+      db.prepare('UPDATE sessions SET external_thread_id = ?, updated_at = ? WHERE id = ?')
+        .run(event.thread_id, now, sessionId);
+      break;
+    }
+
+    case 'turn.started': {
+      // Already broadcasted turn:started before the stream started.
+      break;
+    }
+
+    case 'item.started': {
+      const item = event.item;
+      const itemId = uuidv4();
+      const data = mapItemData(item);
+      db.prepare(
+        'INSERT INTO items (id, turn_id, external_item_id, type, data, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+      ).run(itemId, turnId, item.id, item.type, JSON.stringify(data), 'in_progress', now, now);
+
+      broadcast('item:started', { sessionId, turnId, item: makeItem(itemId, turnId, item, 'in_progress', now, now) });
+      break;
+    }
+
+    case 'item.updated': {
+      const item = event.item;
+      const data = mapItemData(item);
+      const result = db.prepare('UPDATE items SET data = ?, updated_at = ? WHERE external_item_id = ? AND turn_id = ?')
+        .run(JSON.stringify(data), now, item.id, turnId);
+
+      // SDK may skip item.started — insert if missing
+      if (result.changes === 0) {
+        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, item.id, item.type, JSON.stringify(data), 'in_progress', now, now);
+        broadcast('item:updated', { sessionId, turnId, item: makeItem(itemId, turnId, item, 'in_progress', now, now) });
+      } else {
+        const row = db.prepare('SELECT id, status, created_at FROM items WHERE external_item_id = ? AND turn_id = ?')
+          .get(item.id, turnId) as { id: string; status: ItemStatus; created_at: string } | undefined;
+        if (row) {
+          broadcast('item:updated', { sessionId, turnId, item: makeItem(row.id, turnId, item, row.status, row.created_at, now) });
+        }
+      }
+      break;
+    }
+
+    case 'item.completed': {
+      const item = event.item;
+      const status = getItemStatus(item);
+      const data = mapItemData(item);
+      const result = db.prepare('UPDATE items SET data = ?, status = ?, updated_at = ? WHERE external_item_id = ? AND turn_id = ?')
+        .run(JSON.stringify(data), status, now, item.id, turnId);
+
+      // SDK may skip item.started — insert if missing
+      let itemId: string;
+      let createdAt: string;
+      if (result.changes === 0) {
+        itemId = uuidv4();
+        createdAt = now;
+        db.prepare(
+          'INSERT INTO items (id, turn_id, external_item_id, type, data, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+        ).run(itemId, turnId, item.id, item.type, JSON.stringify(data), status, now, now);
+      } else {
+        const row = db.prepare('SELECT id, created_at FROM items WHERE external_item_id = ? AND turn_id = ?')
+          .get(item.id, turnId) as { id: string; created_at: string };
+        itemId = row.id;
+        createdAt = row.created_at;
+      }
+
+      // Update turn-level fields
+      if (item.type === 'agent_message') {
+        db.prepare('UPDATE turns SET agent_response = ?, updated_at = ? WHERE id = ?')
+          .run(item.text, now, turnId);
+      }
+      if (item.type === 'reasoning') {
+        const existing = db.prepare('SELECT thoughts FROM turns WHERE id = ?').get(turnId) as { thoughts: string | null };
+        const thoughts = existing.thoughts ? existing.thoughts + '\n' + item.text : item.text;
+        db.prepare('UPDATE turns SET thoughts = ?, updated_at = ? WHERE id = ?')
+          .run(thoughts, now, turnId);
+      }
+
+      broadcast('item:completed', { sessionId, turnId, item: makeItem(itemId, turnId, item, status, createdAt, now) });
+      break;
+    }
+
+    case 'turn.completed': {
+      const usage = event.usage;
+      db.prepare('UPDATE turns SET status = ?, token_usage = ?, updated_at = ? WHERE id = ?')
+        .run('completed', JSON.stringify(usage), now, turnId);
+      db.prepare('UPDATE sessions SET is_running = 0, status = ?, updated_at = ? WHERE id = ?')
+        .run('active', now, sessionId);
+      broadcast('turn:completed', { sessionId, turnId, usage });
+      break;
+    }
+
+    case 'turn.failed': {
+      db.prepare('UPDATE turns SET status = ?, error = ?, updated_at = ? WHERE id = ?')
+        .run('failed', event.error.message, now, turnId);
+      db.prepare('UPDATE sessions SET is_running = 0, status = ?, updated_at = ? WHERE id = ?')
+        .run('failed', now, sessionId);
+      broadcast('turn:failed', { sessionId, turnId, error: event.error.message });
+      break;
+    }
+
+    case 'error': {
+      db.prepare('UPDATE turns SET status = ?, error = ?, updated_at = ? WHERE id = ?')
+        .run('failed', event.message, now, turnId);
+      db.prepare('UPDATE sessions SET is_running = 0, status = ?, updated_at = ? WHERE id = ?')
+        .run('failed', now, sessionId);
+      broadcast('turn:failed', { sessionId, turnId, error: event.message });
+      break;
+    }
+  }
+}
+
+function makeItem(
+  id: string,
+  turnId: string,
+  sdkItem: ThreadItem,
+  status: ItemStatus,
+  createdAt: string,
+  updatedAt: string,
+): Item {
+  return {
+    id,
+    turn_id: turnId,
+    external_item_id: sdkItem.id,
+    type: sdkItem.type,
+    data: mapItemData(sdkItem),
+    status,
+    created_at: createdAt,
+    updated_at: updatedAt,
+  };
+}

package/agent-pane/backend/src/codex/item-mapper.ts

@@ -0,0 +1,59 @@
+import type { ThreadItem } from '@openai/codex-sdk';
+
+/** Map a Codex ThreadItem to the JSON `data` field for the items table. */
+export function mapItemData(item: ThreadItem): Record<string, unknown> {
+  switch (item.type) {
+    case 'agent_message':
+      return { text: item.text };
+
+    case 'reasoning':
+      return { text: item.text };
+
+    case 'command_execution':
+      return {
+        command: item.command,
+        aggregated_output: item.aggregated_output,
+        exit_code: item.exit_code ?? null,
+        status: item.status,
+      };
+
+    case 'file_change':
+      return {
+        changes: item.changes,
+        status: item.status,
+      };
+
+    case 'mcp_tool_call':
+      return {
+        server: item.server,
+        tool: item.tool,
+        arguments: item.arguments,
+        result: item.result ?? null,
+        error: item.error ?? null,
+        status: item.status,
+      };
+
+    case 'web_search':
+      return { query: item.query };
+
+    case 'todo_list':
+      return { items: item.items };
+
+    case 'error':
+      return { message: item.message };
+
+    default:
+      return {};
+  }
+}
+
+/** Determine the DB status from a completed ThreadItem. */
+export function getItemStatus(item: ThreadItem): 'in_progress' | 'completed' | 'failed' {
+  if (item.type === 'command_execution' || item.type === 'file_change' || item.type === 'mcp_tool_call') {
+    return item.status;
+  }
+  if (item.type === 'error') {
+    return 'failed';
+  }
+  return 'completed';
+}

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

@@ -0,0 +1,67 @@
+import Database from 'better-sqlite3';
+import type { Database as DB } from 'better-sqlite3';
+
+let db: DB;
+
+export function initDb(path: string = 'data.db'): DB {
+  db = new Database(path);
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+
+  createTables(db);
+  return db;
+}
+
+export function getDb(): DB {
+  if (!db) {
+    throw new Error('Database not initialized. Call initDb() first.');
+  }
+  return db;
+}
+
+function createTables(database: DB): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS sessions (
+      id                  TEXT PRIMARY KEY,
+      title               TEXT,
+      runtime_type        TEXT NOT NULL DEFAULT 'codex',
+      model               TEXT,
+      cwd                 TEXT,
+      external_thread_id  TEXT,
+      status              TEXT NOT NULL DEFAULT 'active',
+      is_running          INTEGER NOT NULL DEFAULT 0,
+      created_at          TEXT NOT NULL,
+      updated_at          TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS turns (
+      id                  TEXT PRIMARY KEY,
+      session_id          TEXT NOT NULL,
+      user_prompt         TEXT NOT NULL,
+      agent_response      TEXT,
+      thoughts            TEXT,
+      token_usage         TEXT,
+      external_turn_id    TEXT,
+      status              TEXT NOT NULL DEFAULT 'pending',
+      error               TEXT,
+      created_at          TEXT NOT NULL,
+      updated_at          TEXT NOT NULL,
+      FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
+    );
+
+    CREATE TABLE IF NOT EXISTS items (
+      id                  TEXT PRIMARY KEY,
+      turn_id             TEXT NOT NULL,
+      external_item_id    TEXT,
+      type                TEXT NOT NULL,
+      data                TEXT,
+      status              TEXT NOT NULL DEFAULT 'in_progress',
+      created_at          TEXT NOT NULL,
+      updated_at          TEXT NOT NULL,
+      FOREIGN KEY (turn_id) REFERENCES turns(id) ON DELETE CASCADE
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_turns_session_id ON turns(session_id);
+    CREATE INDEX IF NOT EXISTS idx_items_turn_id ON items(turn_id);
+  `);
+}

package/agent-pane/backend/src/db/schema.ts

@@ -0,0 +1,65 @@
+// Database schema — TypeScript interfaces (no ORM, raw SQL).
+
+export type SessionStatus = 'active' | 'running' | 'completed' | 'failed' | 'aborted';
+export type TurnStatus = 'pending' | 'running' | 'completed' | 'failed' | 'aborted';
+export type ItemType =
+  | 'agent_message'
+  | 'reasoning'
+  | 'command_execution'
+  | 'file_change'
+  | 'mcp_tool_call'
+  | 'web_search'
+  | 'todo_list'
+  | 'error';
+export type ItemStatus = 'in_progress' | 'completed' | 'failed';
+
+export interface Session {
+  id: string;
+  title: string | null;
+  runtime_type: string; // 'codex' (future: 'claude', 'cursor')
+  model: string | null;
+  cwd: string | null;
+  external_thread_id: string | null; // Codex thread ID for resume
+  status: SessionStatus;
+  is_running: number; // 0 | 1
+  created_at: string; // ISO
+  updated_at: string; // ISO
+}
+
+export interface TokenUsage {
+  input_tokens: number;
+  cached_input_tokens: number;
+  cache_write_input_tokens: number;
+  output_tokens: number;
+  reasoning_output_tokens: number;
+}
+
+export interface Turn {
+  id: string;
+  session_id: string;
+  user_prompt: string;
+  agent_response: string | null;
+  thoughts: string | null;
+  token_usage: TokenUsage | null;
+  external_turn_id: string | null;
+  status: TurnStatus;
+  error: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface Item {
+  id: string;
+  turn_id: string;
+  external_item_id: string | null;
+  type: ItemType;
+  data: Record<string, unknown> | null;
+  status: ItemStatus;
+  created_at: string;
+  updated_at: string;
+}
+
+// Nested session detail for GET /api/sessions/:id
+export interface SessionDetail extends Session {
+  turns: (Turn & { items: Item[] })[];
+}

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

@@ -0,0 +1,55 @@
+import Fastify from 'fastify';
+import cors from '@fastify/cors';
+import { initDb } from './db/index.ts';
+import { initWs, handleUpgrade, getWss } from './ws/index.ts';
+import { registerSessionRoutes } from './routes/sessions.ts';
+import { registerTurnRoutes } from './routes/turns.ts';
+
+const PORT = 3001;
+
+async function main(): Promise<void> {
+  // Initialize database
+  initDb('data.db');
+
+  // Create Fastify server
+  const fastify = Fastify({ logger: true });
+
+  // Register CORS (allow Vite dev server)
+  await fastify.register(cors, { origin: true });
+
+  // Register routes
+  await registerSessionRoutes(fastify);
+  await registerTurnRoutes(fastify);
+
+  // Initialize WebSocket server (noServer mode)
+  const wss = initWs();
+
+  // Handle HTTP upgrade for /ws path
+  fastify.server.on('upgrade', (request, socket, head) => {
+    const wsServer = getWss();
+    if (wsServer) {
+      handleUpgrade(wsServer, request, socket, head);
+    } else {
+      socket.destroy();
+    }
+  });
+
+  wss.on('connection', (ws) => {
+    fastify.log.info('WebSocket client connected');
+    ws.on('close', () => {
+      fastify.log.info('WebSocket client disconnected');
+    });
+  });
+
+  // Start server
+  try {
+    await fastify.listen({ port: PORT, host: '0.0.0.0' });
+    fastify.log.info(`AgentPane backend running on http://localhost:${PORT}`);
+    fastify.log.info(`WebSocket endpoint: ws://localhost:${PORT}/ws`);
+  } catch (err) {
+    fastify.log.error(err);
+    process.exit(1);
+  }
+}
+
+main();

package/agent-pane/backend/src/routes/sessions.ts

@@ -0,0 +1,97 @@
+import type { FastifyInstance } from 'fastify';
+import { v4 as uuidv4 } from 'uuid';
+import { getDb } from '../db/index.ts';
+import type { Session, SessionDetail, Turn, Item } from '../db/schema.ts';
+
+/** Raw DB row for turns — token_usage is a JSON string, not parsed. */
+interface TurnRow extends Omit<Turn, 'token_usage'> {
+  token_usage: string | null;
+}
+
+/** Raw DB row for items — data is a JSON string, not parsed. */
+interface ItemRow extends Omit<Item, 'data'> {
+  data: string | null;
+}
+
+export async function registerSessionRoutes(fastify: FastifyInstance): Promise<void> {
+  // GET /api/sessions — list all sessions
+  fastify.get('/api/sessions', async () => {
+    const rows = getDb().prepare('SELECT * FROM sessions ORDER BY created_at DESC').all() as Session[];
+    return rows;
+  });
+
+  // GET /api/sessions/:id — session with turns + items
+  fastify.get<{ Params: { id: string } }>('/api/sessions/:id', async (request, reply) => {
+    const { id } = request.params;
+    const db = getDb();
+
+    const session = db.prepare('SELECT * FROM sessions WHERE id = ?').get(id) as Session | undefined;
+    if (!session) {
+      return reply.code(404).send({ error: 'Session not found' });
+    }
+
+    const turnRows = db.prepare('SELECT * FROM turns WHERE session_id = ? ORDER BY created_at ASC').all(id) as TurnRow[];
+    const itemRows = db.prepare(
+      'SELECT * FROM items WHERE turn_id IN (SELECT id FROM turns WHERE session_id = ?) ORDER BY created_at ASC',
+    ).all(id) as ItemRow[];
+
+    // Parse item data from JSON string and group by turn_id
+    const itemsByTurn = new Map<string, Item[]>();
+    for (const row of itemRows) {
+      const item: Item = {
+        ...row,
+        data: row.data ? JSON.parse(row.data) : null,
+      };
+      const list = itemsByTurn.get(item.turn_id) ?? [];
+      list.push(item);
+      itemsByTurn.set(item.turn_id, list);
+    }
+
+    const detail: SessionDetail = {
+      ...session,
+      turns: turnRows.map((row) => ({
+        ...row,
+        token_usage: row.token_usage ? JSON.parse(row.token_usage) : null,
+        items: itemsByTurn.get(row.id) ?? [],
+      })),
+    };
+
+    return detail;
+  });
+
+  // POST /api/sessions — create session
+  fastify.post<{ Body: { title?: string; runtime_type?: string; model?: string; cwd?: string } }>(
+    '/api/sessions',
+    async (request) => {
+      const { title = null, runtime_type = 'codex', model = null, cwd = null } = request.body || {};
+      const id = uuidv4();
+      const now = new Date().toISOString();
+
+      getDb().prepare(
+        `INSERT INTO sessions (id, title, runtime_type, model, cwd, external_thread_id, status, is_running, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, NULL, 'active', 0, ?, ?)`,
+      ).run(id, title, runtime_type, model, cwd, now, now);
+
+      const session = getDb().prepare('SELECT * FROM sessions WHERE id = ?').get(id) as Session;
+      return session;
+    },
+  );
+
+  // DELETE /api/sessions/:id — delete session (cascade)
+  fastify.delete<{ Params: { id: string } }>('/api/sessions/:id', async (request, reply) => {
+    const { id } = request.params;
+    const db = getDb();
+
+    const existing = db.prepare('SELECT id FROM sessions WHERE id = ?').get(id);
+    if (!existing) {
+      return reply.code(404).send({ error: 'Session not found' });
+    }
+
+    // Delete items first (turns cascade via FK, but better-sqlite3 needs explicit cascade if pragma is set)
+    db.prepare('DELETE FROM items WHERE turn_id IN (SELECT id FROM turns WHERE session_id = ?)').run(id);
+    db.prepare('DELETE FROM turns WHERE session_id = ?').run(id);
+    db.prepare('DELETE FROM sessions WHERE id = ?').run(id);
+
+    return { success: true };
+  });
+}

package/agent-pane/backend/src/routes/turns.ts

@@ -0,0 +1,60 @@
+import type { FastifyInstance } from 'fastify';
+import { v4 as uuidv4 } from 'uuid';
+import { getDb } from '../db/index.ts';
+import { startTurn, interruptTurn } from '../codex/codex-provider.ts';
+import type { Session, Turn } from '../db/schema.ts';
+
+export async function registerTurnRoutes(fastify: FastifyInstance): Promise<void> {
+  // POST /api/sessions/:id/turns — submit prompt, starts Codex turn
+  fastify.post<{ Params: { id: string }; Body: { user_prompt: string } }>(
+    '/api/sessions/:id/turns',
+    async (request, reply) => {
+      const { id } = request.params;
+      const { user_prompt } = request.body || {};
+
+      if (!user_prompt || !user_prompt.trim()) {
+        return reply.code(400).send({ error: 'user_prompt is required' });
+      }
+
+      const db = getDb();
+      const session = db.prepare('SELECT * FROM sessions WHERE id = ?').get(id) as Session | undefined;
+      if (!session) {
+        return reply.code(404).send({ error: 'Session not found' });
+      }
+
+      if (session.is_running) {
+        return reply.code(409).send({ error: 'A turn is already running for this session' });
+      }
+
+      // Create turn in DB
+      const turnId = uuidv4();
+      const now = new Date().toISOString();
+      db.prepare(
+        `INSERT INTO turns (id, session_id, user_prompt, agent_response, thoughts, token_usage, external_turn_id, status, error, created_at, updated_at)
+         VALUES (?, ?, ?, NULL, NULL, NULL, NULL, 'pending', NULL, ?, ?)`,
+      ).run(turnId, id, user_prompt, now, now);
+
+      const turn = db.prepare('SELECT * FROM turns WHERE id = ?').get(turnId) as Turn;
+
+      // Fire and forget — events stream via WebSocket
+      startTurn(session, turn).catch((err) => {
+        console.error(`[codex-provider] Unhandled error for session ${id}:`, err);
+      });
+
+      return turn;
+    },
+  );
+
+  // POST /api/sessions/:id/cancel — cancel running turn
+  fastify.post<{ Params: { id: string } }>(
+    '/api/sessions/:id/cancel',
+    async (request, reply) => {
+      const { id } = request.params;
+      const cancelled = interruptTurn(id);
+      if (!cancelled) {
+        return reply.code(409).send({ error: 'No running turn to cancel' });
+      }
+      return { success: true };
+    },
+  );
+}