@amalgm/chat 0.1.2 → 0.2.0

package/host/sqlite/index.js

@@ -0,0 +1,704 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import Database from 'better-sqlite3';
+import {
+  applyAcpTranscriptUpdate,
+  createAcpTranscriptState,
+  finalizeAcpTranscript,
+  promptContentPlain,
+} from '../../dist/conversations/index.js';
+
+const SCHEMA_VERSION = 2;
+const TERMINAL = new Set(['completed', 'failed', 'cancelled', 'interrupted']);
+
+export class SqliteConversationStoreError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'SqliteConversationStoreError';
+    this.code = code;
+  }
+}
+
+/** Recommended bounded content batching for the Chat constructor. */
+export function createSqliteJournalBatchPolicy(options = {}) {
+  const maxUpdates = Number.isFinite(options.maxUpdates)
+    ? Math.max(1, Math.floor(options.maxUpdates))
+    : 64;
+  const maxDelayMs = Number.isFinite(options.maxDelayMs)
+    ? Math.max(0, Math.floor(options.maxDelayMs))
+    : 12;
+  return Object.freeze({
+    maxUpdates,
+    maxDelayMs,
+    wait: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+  });
+}
+
+function required(value, label) {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new SqliteConversationStoreError('INVALID_CONVERSATION_INPUT', `${label} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function parseJson(value, fallback) {
+  if (typeof value !== 'string' || !value) return fallback;
+  try { return JSON.parse(value); } catch { return fallback; }
+}
+
+function stringify(value) {
+  return JSON.stringify(value ?? null);
+}
+
+function boolean(value) {
+  return Number(value) === 1;
+}
+
+function conversationFromRow(row) {
+  return Object.freeze({
+    id: row.id,
+    ownerUserId: row.owner_user_id,
+    agentInstallationId: row.agent_installation_id,
+    agentRevisionId: row.agent_revision_id,
+    adapterId: row.adapter_id,
+    title: row.title,
+    activityStatus: row.activity_status,
+    newMessages: boolean(row.new_messages),
+    origin: row.origin,
+    originId: row.origin_id,
+    lastExecutionComputerId: row.last_execution_computer_id,
+    providerSessionId: row.provider_session_id,
+    metadata: Object.freeze(parseJson(row.metadata_json, {})),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    lastMessageAt: row.last_message_at,
+    archivedAt: row.archived_at,
+  });
+}
+
+function turnFromRow(row) {
+  return Object.freeze({
+    id: row.id,
+    conversationId: row.conversation_id,
+    status: row.status,
+    prompt: Object.freeze(parseJson(row.prompt_json, { parts: [] })),
+    execution: Object.freeze(parseJson(row.execution_json, {})),
+    error: row.error_json ? Object.freeze(parseJson(row.error_json, {})) : null,
+    createdAt: row.created_at,
+    startedAt: row.started_at,
+    completedAt: row.completed_at,
+    nextSequence: Number(row.next_sequence),
+  });
+}
+
+function updateFromRow(row) {
+  return Object.freeze({
+    conversationId: row.conversation_id,
+    turnId: row.turn_id,
+    sequence: Number(row.sequence),
+    update: Object.freeze(parseJson(row.update_json, {})),
+    createdAt: row.created_at,
+  });
+}
+
+function messageFromRow(row) {
+  return Object.freeze({
+    id: row.id,
+    conversationId: row.conversation_id,
+    turnId: row.turn_id,
+    role: row.role,
+    parts: Object.freeze(parseJson(row.parts_json, [])),
+    contentPlain: row.content_plain,
+    modelId: row.model_id,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  });
+}
+
+function checkpointFromRow(row) {
+  return Object.freeze({
+    conversationId: row.conversation_id,
+    executionRevision: row.execution_revision,
+    adapterId: row.adapter_id,
+    checkpoint: Object.freeze(parseJson(row.checkpoint_json, {})),
+    updatedAt: row.updated_at,
+  });
+}
+
+function migrate(database) {
+  const version = Number(database.pragma('user_version', { simple: true }));
+  if (version > SCHEMA_VERSION) {
+    throw new SqliteConversationStoreError(
+      'UNSUPPORTED_SCHEMA_VERSION',
+      `Conversation database version ${version} is newer than supported version ${SCHEMA_VERSION}`,
+    );
+  }
+  if (version === SCHEMA_VERSION) return;
+  if (version === 1) {
+    database.exec(`
+      BEGIN IMMEDIATE;
+      CREATE INDEX conversations_origin_activity_idx
+        ON conversations(owner_user_id, origin, origin_id, archived_at, last_message_at DESC);
+      INSERT INTO schema_migrations(version, applied_at)
+        VALUES (2, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'));
+      PRAGMA user_version = 2;
+      COMMIT;
+    `);
+    return;
+  }
+  database.exec(`
+    BEGIN IMMEDIATE;
+
+    CREATE TABLE schema_migrations (
+      version INTEGER PRIMARY KEY,
+      applied_at TEXT NOT NULL
+    );
+
+    CREATE TABLE conversations (
+      id TEXT PRIMARY KEY,
+      owner_user_id TEXT NOT NULL,
+      agent_installation_id TEXT NOT NULL,
+      agent_revision_id TEXT NOT NULL,
+      adapter_id TEXT NOT NULL,
+      title TEXT NOT NULL,
+      activity_status TEXT NOT NULL CHECK(activity_status IN ('in-progress', 'complete', 'error')),
+      new_messages INTEGER NOT NULL CHECK(new_messages IN (0, 1)),
+      origin TEXT,
+      origin_id TEXT,
+      last_execution_computer_id TEXT,
+      provider_session_id TEXT,
+      metadata_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      last_message_at TEXT NOT NULL,
+      archived_at TEXT
+    );
+
+    CREATE TABLE turns (
+      id TEXT PRIMARY KEY,
+      conversation_id TEXT NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+      status TEXT NOT NULL CHECK(status IN ('running', 'completed', 'failed', 'cancelled', 'interrupted')),
+      prompt_json TEXT NOT NULL,
+      execution_json TEXT NOT NULL,
+      error_json TEXT,
+      created_at TEXT NOT NULL,
+      started_at TEXT NOT NULL,
+      completed_at TEXT,
+      next_sequence INTEGER NOT NULL DEFAULT 1 CHECK(next_sequence >= 1)
+    );
+
+    CREATE TABLE turn_updates (
+      conversation_id TEXT NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+      turn_id TEXT NOT NULL REFERENCES turns(id) ON DELETE CASCADE,
+      sequence INTEGER NOT NULL CHECK(sequence >= 1),
+      update_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      PRIMARY KEY(turn_id, sequence)
+    );
+
+    CREATE TABLE messages (
+      id TEXT PRIMARY KEY,
+      conversation_id TEXT NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+      turn_id TEXT NOT NULL REFERENCES turns(id) ON DELETE CASCADE,
+      role TEXT NOT NULL CHECK(role IN ('user', 'assistant')),
+      parts_json TEXT NOT NULL,
+      content_plain TEXT,
+      model_id TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      UNIQUE(turn_id, role)
+    );
+
+    CREATE TABLE provider_checkpoints (
+      conversation_id TEXT NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+      execution_revision TEXT NOT NULL,
+      adapter_id TEXT NOT NULL,
+      checkpoint_json TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      PRIMARY KEY(conversation_id, execution_revision)
+    );
+
+    CREATE INDEX conversations_owner_activity_idx
+      ON conversations(owner_user_id, archived_at, last_message_at DESC);
+    CREATE INDEX conversations_agent_activity_idx
+      ON conversations(owner_user_id, agent_installation_id, last_message_at DESC);
+    CREATE INDEX conversations_origin_activity_idx
+      ON conversations(owner_user_id, origin, origin_id, archived_at, last_message_at DESC);
+    CREATE INDEX turns_conversation_created_idx
+      ON turns(conversation_id, created_at ASC);
+    CREATE UNIQUE INDEX turns_one_running_per_conversation_idx
+      ON turns(conversation_id) WHERE status = 'running';
+    CREATE INDEX turn_updates_conversation_idx
+      ON turn_updates(conversation_id, turn_id, sequence ASC);
+    CREATE INDEX messages_conversation_created_idx
+      ON messages(conversation_id, created_at ASC);
+
+    INSERT INTO schema_migrations(version, applied_at)
+      VALUES (1, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'));
+    INSERT INTO schema_migrations(version, applied_at)
+      VALUES (2, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'));
+    PRAGMA user_version = 2;
+    COMMIT;
+  `);
+}
+
+function openDatabase(options) {
+  if (options.database) return { database: options.database, databasePath: options.databasePath || ':injected:' };
+  if (options.databasePath === ':memory:') {
+    return { database: new Database(':memory:'), databasePath: ':memory:' };
+  }
+  const databasePath = path.resolve(required(options.databasePath, 'databasePath'));
+  fs.mkdirSync(path.dirname(databasePath), { recursive: true, mode: 0o700 });
+  return { database: new Database(databasePath), databasePath };
+}
+
+export class SqliteConversationStore {
+  constructor(options = {}) {
+    const opened = openDatabase(options);
+    this.database = opened.database;
+    this.databasePath = opened.databasePath;
+    this.closed = false;
+    this.database.pragma('journal_mode = WAL');
+    this.database.pragma('foreign_keys = ON');
+    this.database.pragma(`busy_timeout = ${Number.isFinite(options.busyTimeoutMs) ? Math.max(0, Math.floor(options.busyTimeoutMs)) : 5000}`);
+    this.database.pragma(`synchronous = ${options.synchronous === 'normal' ? 'NORMAL' : 'FULL'}`);
+    this.database.pragma('wal_autocheckpoint = 1000');
+    migrate(this.database);
+    this.statements = this.#prepare();
+  }
+
+  #prepare() {
+    return {
+      conversation: this.database.prepare(`
+        SELECT * FROM conversations
+        WHERE id = ? AND owner_user_id = ? AND agent_installation_id = ?
+      `),
+      turn: this.database.prepare(`
+        SELECT t.* FROM turns t
+        JOIN conversations c ON c.id = t.conversation_id
+        WHERE t.id = ? AND c.owner_user_id = ? AND c.agent_installation_id = ?
+      `),
+      activeTurn: this.database.prepare(`
+        SELECT t.* FROM turns t
+        JOIN conversations c ON c.id = t.conversation_id
+        WHERE c.id = ? AND c.owner_user_id = ? AND c.agent_installation_id = ? AND t.status = 'running'
+        LIMIT 1
+      `),
+      latestTurn: this.database.prepare(`
+        SELECT t.* FROM turns t
+        JOIN conversations c ON c.id = t.conversation_id
+        WHERE c.id = ? AND c.owner_user_id = ? AND c.agent_installation_id = ?
+        ORDER BY t.created_at DESC, t.id DESC
+        LIMIT 1
+      `),
+    };
+  }
+
+  #requireConversation(scope, conversationId) {
+    const id = required(conversationId, 'conversationId');
+    const row = this.statements.conversation.get(
+      id,
+      required(scope.ownerUserId, 'ownerUserId'),
+      required(scope.agentInstallationId, 'agentInstallationId'),
+    );
+    if (!row) throw new SqliteConversationStoreError('CONVERSATION_NOT_FOUND', `Conversation not found: ${id}`);
+    return row;
+  }
+
+  #requireTurn(scope, turnId) {
+    const id = required(turnId, 'turnId');
+    const row = this.statements.turn.get(
+      id,
+      required(scope.ownerUserId, 'ownerUserId'),
+      required(scope.agentInstallationId, 'agentInstallationId'),
+    );
+    if (!row) throw new SqliteConversationStoreError('TURN_NOT_FOUND', `Turn not found: ${id}`);
+    return row;
+  }
+
+  async createConversation(input) {
+    const existing = this.database.prepare('SELECT id FROM conversations WHERE id = ?').get(input.id);
+    if (existing) throw new SqliteConversationStoreError('CONVERSATION_EXISTS', `Conversation already exists: ${input.id}`);
+    this.database.prepare(`
+      INSERT INTO conversations (
+        id, owner_user_id, agent_installation_id, agent_revision_id, adapter_id,
+        title, activity_status, new_messages, origin, origin_id,
+        last_execution_computer_id, metadata_json, created_at, updated_at, last_message_at
+      ) VALUES (?, ?, ?, ?, ?, ?, 'complete', 0, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      required(input.id, 'conversation id'),
+      required(input.ownerUserId, 'ownerUserId'),
+      required(input.agentInstallationId, 'agentInstallationId'),
+      required(input.agentRevisionId, 'agentRevisionId'),
+      required(input.adapterId, 'adapterId'),
+      required(input.title, 'title'),
+      input.origin || null,
+      input.originId || null,
+      required(input.lastExecutionComputerId, 'lastExecutionComputerId'),
+      stringify(input.metadata || {}),
+      required(input.createdAt, 'createdAt'),
+      input.createdAt,
+      input.createdAt,
+    );
+    return conversationFromRow(this.#requireConversation(input, input.id));
+  }
+
+  async getConversation(scope, conversationId) {
+    const row = this.statements.conversation.get(
+      required(conversationId, 'conversationId'),
+      required(scope.ownerUserId, 'ownerUserId'),
+      required(scope.agentInstallationId, 'agentInstallationId'),
+    );
+    return row ? conversationFromRow(row) : null;
+  }
+
+  /** Host-only owner lookup used to recover installation scope at an API boundary. */
+  getConversationForOwner(ownerUserId, conversationId, includeArchived = true) {
+    const filters = ['id = ?', 'owner_user_id = ?'];
+    if (!includeArchived) filters.push('archived_at IS NULL');
+    const row = this.database.prepare(`
+      SELECT * FROM conversations WHERE ${filters.join(' AND ')} LIMIT 1
+    `).get(
+      required(conversationId, 'conversationId'),
+      required(ownerUserId, 'ownerUserId'),
+    );
+    if (!row) return null;
+    const record = conversationFromRow(row);
+    return {
+      scope: {
+        ownerUserId: record.ownerUserId,
+        agentInstallationId: record.agentInstallationId,
+      },
+      record,
+    };
+  }
+
+  async listConversations(ownerUserId, options = {}) {
+    const filters = ['owner_user_id = ?'];
+    const values = [required(ownerUserId, 'ownerUserId')];
+    if (options.agentInstallationId) {
+      filters.push('agent_installation_id = ?');
+      values.push(required(options.agentInstallationId, 'agentInstallationId'));
+    }
+    if (options.origin) {
+      filters.push('origin = ?');
+      values.push(required(options.origin, 'origin'));
+    }
+    if (options.originId) {
+      filters.push('origin_id = ?');
+      values.push(required(options.originId, 'originId'));
+    }
+    if (!options.includeArchived) filters.push('archived_at IS NULL');
+    const offset = Number.isFinite(options.offset) ? Math.max(0, Math.floor(options.offset)) : 0;
+    const limit = Number.isFinite(options.limit) ? Math.max(1, Math.min(500, Math.floor(options.limit))) : 100;
+    return this.database.prepare(`
+      SELECT * FROM conversations WHERE ${filters.join(' AND ')}
+      ORDER BY last_message_at DESC, id ASC LIMIT ? OFFSET ?
+    `).all(...values, limit, offset).map(conversationFromRow);
+  }
+
+  async updateTitle(scope, conversationId, title, updatedAt) {
+    const row = this.#requireConversation(scope, conversationId);
+    this.database.prepare('UPDATE conversations SET title = ?, updated_at = ? WHERE id = ?')
+      .run(required(title, 'title'), required(updatedAt, 'updatedAt'), row.id);
+    return conversationFromRow(this.#requireConversation(scope, row.id));
+  }
+
+  async markSeen(scope, conversationId, updatedAt) {
+    const row = this.#requireConversation(scope, conversationId);
+    this.database.prepare('UPDATE conversations SET new_messages = 0, updated_at = ? WHERE id = ?')
+      .run(required(updatedAt, 'updatedAt'), row.id);
+    return conversationFromRow(this.#requireConversation(scope, row.id));
+  }
+
+  /** Mutable presentation projection; identity and agent revision remain immutable. */
+  updateProjection(scope, conversationId, input, updatedAt) {
+    const row = this.#requireConversation(scope, conversationId);
+    const metadata = input.metadata === undefined
+      ? parseJson(row.metadata_json, {})
+      : { ...parseJson(row.metadata_json, {}), ...input.metadata };
+    this.database.prepare(`
+      UPDATE conversations SET
+        provider_session_id = ?,
+        last_execution_computer_id = COALESCE(?, last_execution_computer_id),
+        metadata_json = ?,
+        updated_at = ?
+      WHERE id = ?
+    `).run(
+      input.providerSessionId === undefined ? row.provider_session_id : input.providerSessionId,
+      input.lastExecutionComputerId === undefined ? null : input.lastExecutionComputerId,
+      stringify(metadata),
+      required(updatedAt, 'updatedAt'),
+      row.id,
+    );
+    return conversationFromRow(this.#requireConversation(scope, row.id));
+  }
+
+  async archiveConversation(scope, conversationId, archivedAt) {
+    const row = this.#requireConversation(scope, conversationId);
+    if (this.statements.activeTurn.get(row.id, scope.ownerUserId, scope.agentInstallationId)) {
+      throw new SqliteConversationStoreError('CONVERSATION_BUSY', `Conversation has an active turn: ${row.id}`);
+    }
+    this.database.prepare('UPDATE conversations SET archived_at = ?, updated_at = ? WHERE id = ?')
+      .run(required(archivedAt, 'archivedAt'), archivedAt, row.id);
+    return conversationFromRow(this.#requireConversation(scope, row.id));
+  }
+
+  async beginTurn(input) {
+    const transaction = this.database.transaction(() => {
+      const conversation = this.#requireConversation(input, input.conversationId);
+      if (conversation.archived_at) {
+        throw new SqliteConversationStoreError('CONVERSATION_ARCHIVED', `Conversation is archived: ${conversation.id}`);
+      }
+      if (conversation.agent_installation_id !== input.execution.agent.installationId) {
+        throw new SqliteConversationStoreError('SESSION_AGENT_MISMATCH', `Conversation belongs to a different agent installation: ${conversation.id}`);
+      }
+      if (this.statements.activeTurn.get(conversation.id, input.ownerUserId, input.agentInstallationId)) {
+        throw new SqliteConversationStoreError('CONVERSATION_BUSY', `Conversation has an active turn: ${conversation.id}`);
+      }
+      this.database.prepare(`
+        INSERT INTO turns (
+          id, conversation_id, status, prompt_json, execution_json, created_at, started_at, next_sequence
+        ) VALUES (?, ?, 'running', ?, ?, ?, ?, 1)
+      `).run(
+        required(input.turnId, 'turnId'),
+        conversation.id,
+        stringify(input.prompt),
+        stringify(input.execution),
+        required(input.createdAt, 'createdAt'),
+        input.createdAt,
+      );
+      this.database.prepare(`
+        INSERT INTO messages (
+          id, conversation_id, turn_id, role, parts_json, content_plain, model_id, created_at, updated_at
+        ) VALUES (?, ?, ?, 'user', ?, ?, NULL, ?, ?)
+      `).run(
+        required(input.userMessageId, 'userMessageId'),
+        conversation.id,
+        input.turnId,
+        stringify(input.prompt.parts),
+        promptContentPlain(input.prompt.parts),
+        input.createdAt,
+        input.createdAt,
+      );
+      this.database.prepare(`
+        UPDATE conversations SET
+          agent_revision_id = ?, adapter_id = ?, activity_status = 'in-progress',
+          new_messages = 0, last_execution_computer_id = ?, updated_at = ?, last_message_at = ?
+        WHERE id = ?
+      `).run(
+        input.execution.agent.revisionId,
+        input.execution.agent.adapterId,
+        input.execution.computerId,
+        input.createdAt,
+        input.createdAt,
+        conversation.id,
+      );
+      return this.#requireTurn(input, input.turnId);
+    });
+    try {
+      return turnFromRow(transaction());
+    } catch (error) {
+      if (String(error?.code || '').startsWith('SQLITE_CONSTRAINT')) {
+        throw new SqliteConversationStoreError('CONVERSATION_BUSY', `Conversation has an active turn: ${input.conversationId}`);
+      }
+      throw error;
+    }
+  }
+
+  async appendTurnUpdate(input) {
+    const updates = await this.appendTurnUpdates({
+      ...input,
+      updates: [{ update: input.update, createdAt: input.createdAt }],
+    });
+    return updates[0];
+  }
+
+  async appendTurnUpdates(input) {
+    if (!Array.isArray(input.updates) || input.updates.length === 0) {
+      throw new SqliteConversationStoreError('INVALID_CONVERSATION_INPUT', 'updates must not be empty');
+    }
+    const transaction = this.database.transaction(() => {
+      const turn = this.#requireTurn(input, input.turnId);
+      if (turn.conversation_id !== input.conversationId || turn.status !== 'running') {
+        throw new SqliteConversationStoreError('TURN_NOT_RUNNING', `Turn is not running: ${input.turnId}`);
+      }
+      let sequence = Number(turn.next_sequence);
+      const insert = this.database.prepare(`
+        INSERT INTO turn_updates (conversation_id, turn_id, sequence, update_json, created_at)
+        VALUES (?, ?, ?, ?, ?)
+      `);
+      const stored = [];
+      for (const item of input.updates) {
+        insert.run(
+          turn.conversation_id,
+          turn.id,
+          sequence,
+          stringify(item.update),
+          required(item.createdAt, 'createdAt'),
+        );
+        stored.push(this.database.prepare(
+          'SELECT * FROM turn_updates WHERE turn_id = ? AND sequence = ?',
+        ).get(turn.id, sequence));
+        sequence += 1;
+      }
+      this.database.prepare('UPDATE turns SET next_sequence = ? WHERE id = ?').run(sequence, turn.id);
+      return stored;
+    });
+    return transaction().map(updateFromRow);
+  }
+
+  async sealTurn(input) {
+    const transaction = this.database.transaction(() => {
+      const turn = this.#requireTurn(input, input.turnId);
+      if (turn.conversation_id !== input.conversationId) {
+        throw new SqliteConversationStoreError('TURN_NOT_FOUND', `Turn not found: ${input.turnId}`);
+      }
+      if (TERMINAL.has(turn.status)) return turn;
+      const status = required(input.status, 'status');
+      if (!TERMINAL.has(status)) {
+        throw new SqliteConversationStoreError('INVALID_CONVERSATION_INPUT', `Invalid terminal turn status: ${status}`);
+      }
+      this.database.prepare(`
+        UPDATE turns SET status = ?, error_json = ?, completed_at = ? WHERE id = ? AND status = 'running'
+      `).run(status, input.error ? stringify(input.error) : null, required(input.completedAt, 'completedAt'), turn.id);
+      this.database.prepare(`
+        INSERT INTO messages (
+          id, conversation_id, turn_id, role, parts_json, content_plain, model_id, created_at, updated_at
+        ) VALUES (?, ?, ?, 'assistant', ?, ?, ?, ?, ?)
+      `).run(
+        required(input.assistantMessageId, 'assistantMessageId'),
+        turn.conversation_id,
+        turn.id,
+        stringify(input.assistantParts),
+        promptContentPlain(input.assistantParts),
+        required(input.modelId, 'modelId'),
+        input.completedAt,
+        input.completedAt,
+      );
+      this.database.prepare(`
+        UPDATE conversations SET activity_status = ?, new_messages = 1,
+          updated_at = ?, last_message_at = ?,
+          provider_session_id = COALESCE(?, provider_session_id) WHERE id = ?
+      `).run(
+        status === 'failed' || status === 'interrupted' ? 'error' : 'complete',
+        input.completedAt,
+        input.completedAt,
+        typeof input.providerCheckpoint?.checkpoint?.providerSessionId === 'string'
+          ? input.providerCheckpoint.checkpoint.providerSessionId
+          : null,
+        turn.conversation_id,
+      );
+      if (input.providerCheckpoint) {
+        this.database.prepare(`
+          INSERT INTO provider_checkpoints (
+            conversation_id, execution_revision, adapter_id, checkpoint_json, updated_at
+          ) VALUES (?, ?, ?, ?, ?)
+          ON CONFLICT(conversation_id, execution_revision) DO UPDATE SET
+            adapter_id = excluded.adapter_id,
+            checkpoint_json = excluded.checkpoint_json,
+            updated_at = excluded.updated_at
+        `).run(
+          turn.conversation_id,
+          required(input.providerCheckpoint.executionRevision, 'providerCheckpoint.executionRevision'),
+          required(input.providerCheckpoint.adapterId, 'providerCheckpoint.adapterId'),
+          stringify(input.providerCheckpoint.checkpoint),
+          required(input.providerCheckpoint.updatedAt, 'providerCheckpoint.updatedAt'),
+        );
+      }
+      return this.#requireTurn(input, turn.id);
+    });
+    return turnFromRow(transaction());
+  }
+
+  async getTurn(scope, turnId) {
+    const row = this.statements.turn.get(
+      required(turnId, 'turnId'),
+      required(scope.ownerUserId, 'ownerUserId'),
+      required(scope.agentInstallationId, 'agentInstallationId'),
+    );
+    return row ? turnFromRow(row) : null;
+  }
+
+  async getLatestTurn(scope, conversationId) {
+    const row = this.statements.latestTurn.get(
+      required(conversationId, 'conversationId'),
+      required(scope.ownerUserId, 'ownerUserId'),
+      required(scope.agentInstallationId, 'agentInstallationId'),
+    );
+    return row ? turnFromRow(row) : null;
+  }
+
+  async listTurnUpdates(scope, turnId, afterSequence = 0, limit = 512) {
+    const turn = this.#requireTurn(scope, turnId);
+    const cursor = Number.isFinite(afterSequence) ? Math.max(0, Math.floor(afterSequence)) : 0;
+    const bounded = Number.isFinite(limit) ? Math.max(1, Math.min(2000, Math.floor(limit))) : 512;
+    return this.database.prepare(`
+      SELECT * FROM turn_updates WHERE turn_id = ? AND sequence > ? ORDER BY sequence ASC LIMIT ?
+    `).all(turn.id, cursor, bounded).map(updateFromRow);
+  }
+
+  async listMessages(scope, conversationId) {
+    const conversation = this.#requireConversation(scope, conversationId);
+    return this.database.prepare(`
+      SELECT * FROM messages WHERE conversation_id = ? ORDER BY created_at ASC, role DESC
+    `).all(conversation.id).map(messageFromRow);
+  }
+
+  async getProviderCheckpoint(scope, conversationId, executionRevision) {
+    const conversation = this.#requireConversation(scope, conversationId);
+    const row = this.database.prepare(`
+      SELECT * FROM provider_checkpoints
+      WHERE conversation_id = ? AND execution_revision = ?
+    `).get(conversation.id, required(executionRevision, 'executionRevision'));
+    return row ? checkpointFromRow(row) : null;
+  }
+
+  async recoverInterrupted(ownerUserId, recoveredAt) {
+    const owner = required(ownerUserId, 'ownerUserId');
+    const rows = this.database.prepare(`
+      SELECT t.*, c.agent_installation_id FROM turns t
+      JOIN conversations c ON c.id = t.conversation_id
+      WHERE c.owner_user_id = ? AND t.status = 'running'
+      ORDER BY t.created_at ASC
+    `).all(owner);
+    const recovered = [];
+    for (const row of rows) {
+      const scope = { ownerUserId: owner, agentInstallationId: row.agent_installation_id };
+      const state = createAcpTranscriptState();
+      let cursor = 0;
+      while (true) {
+        const updates = await this.listTurnUpdates(scope, row.id, cursor, 512);
+        for (const event of updates) {
+          applyAcpTranscriptUpdate(state, event.update);
+          cursor = event.sequence;
+        }
+        if (updates.length < 512) break;
+      }
+      const execution = parseJson(row.execution_json, {});
+      const turn = await this.sealTurn({
+        ...scope,
+        conversationId: row.conversation_id,
+        turnId: row.id,
+        assistantMessageId: `interrupted:${row.id}`,
+        status: 'interrupted',
+        assistantParts: finalizeAcpTranscript(state, true),
+        modelId: execution?.model?.modelId || 'unknown',
+        error: {
+          code: 'PROCESS_RESTARTED',
+          message: 'The execution host restarted before the provider operation settled.',
+        },
+        providerCheckpoint: null,
+        completedAt: required(recoveredAt, 'recoveredAt'),
+      });
+      recovered.push(turn);
+    }
+    return recovered;
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.database.close();
+  }
+}