@andreprado/agentkit 0.1.0-alpha.10

package/src/storage/sqlite.ts

@@ -0,0 +1,1118 @@
+import { Buffer } from "node:buffer";
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+
+import type { DatabaseArgs, DatabaseResult, DatabaseRow, DatabaseStatement } from "../index";
+import type { AgentMessageRole, ProviderRunResult } from "../providers";
+import type { LoadedAgentCapsule } from "../runtime/config";
+import { AgentKitError } from "../runtime/errors";
+import { KNOWLEDGE_MIGRATION_ID, KNOWLEDGE_SCHEMA_SQL } from "../runtime/knowledge/schema";
+
+export type ConversationSummary = {
+  id: string;
+  agentName: string;
+  title: string | null;
+  createdAt: string;
+  updatedAt: string;
+  messageCount: number;
+};
+
+export type StoredMessage = {
+  id: string;
+  conversationId: string;
+  role: AgentMessageRole;
+  content: string;
+  createdAt: string;
+  sequence: number;
+};
+
+export type ConversationRecord = ConversationSummary & {
+  messages: StoredMessage[];
+};
+
+export type RunStatus = "running" | "completed" | "failed";
+export type ToolCallStatus = "running" | "completed" | "failed";
+export type ToolCallVisibility = "user" | "internal";
+
+export type StoredToolCall = {
+  id: string;
+  runId: string;
+  conversationId: string | null;
+  toolName: string;
+  visibility: ToolCallVisibility;
+  input: unknown;
+  output: unknown;
+  rendered: unknown;
+  status: ToolCallStatus;
+  startedAt: string;
+  completedAt: string | null;
+  errorMessage: string | null;
+};
+
+export type StoredRun = {
+  id: string;
+  conversationId: string | null;
+  provider: string;
+  model: string;
+  status: RunStatus;
+  usage: {
+    inputTokens: number | null;
+    outputTokens: number | null;
+    totalTokens: number | null;
+  };
+  startedAt: string;
+  completedAt: string | null;
+  errorCode: string | null;
+  errorMessage: string | null;
+};
+
+export type PersistedChatRun = {
+  conversationId: string;
+  runId: string;
+  userMessageId: string;
+  assistantMessageId?: string;
+};
+
+type SqliteRow = Record<string, unknown>;
+type SqliteColumn = {
+  name: string;
+};
+type SqliteStatement = {
+  run(...bindings: unknown[]): { changes?: number; lastInsertRowid?: number | bigint };
+  all(...bindings: unknown[]): SqliteRow[];
+  get(...bindings: unknown[]): SqliteRow | null | undefined;
+  columnNames?: string[];
+  columns?: () => SqliteColumn[];
+};
+type SqliteDatabase = {
+  close(): void;
+  exec(sql: string): unknown;
+  prepare(sql: string): SqliteStatement;
+};
+
+const MIGRATIONS = [
+  {
+    id: "0001_create_conversations",
+    sql: `
+      CREATE TABLE IF NOT EXISTS conversations (
+        id TEXT PRIMARY KEY,
+        agent_name TEXT NOT NULL,
+        title TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        metadata_json TEXT NOT NULL DEFAULT '{}'
+      );
+    `,
+  },
+  {
+    id: "0002_create_messages",
+    sql: `
+      CREATE TABLE IF NOT EXISTS messages (
+        id TEXT PRIMARY KEY,
+        conversation_id TEXT NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+        role TEXT NOT NULL,
+        content TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        sequence INTEGER NOT NULL,
+        metadata_json TEXT NOT NULL DEFAULT '{}'
+      );
+
+      CREATE INDEX IF NOT EXISTS messages_conversation_sequence_idx
+        ON messages(conversation_id, sequence);
+    `,
+  },
+  {
+    id: "0003_create_runs",
+    sql: `
+      CREATE TABLE IF NOT EXISTS runs (
+        id TEXT PRIMARY KEY,
+        conversation_id TEXT REFERENCES conversations(id) ON DELETE SET NULL,
+        provider TEXT NOT NULL,
+        model TEXT NOT NULL,
+        status TEXT NOT NULL,
+        input_tokens INTEGER,
+        output_tokens INTEGER,
+        total_tokens INTEGER,
+        started_at TEXT NOT NULL,
+        completed_at TEXT,
+        error_code TEXT,
+        error_message TEXT,
+        metadata_json TEXT NOT NULL DEFAULT '{}'
+      );
+
+      CREATE INDEX IF NOT EXISTS runs_conversation_started_idx
+        ON runs(conversation_id, started_at);
+    `,
+  },
+  {
+    id: "0004_create_tool_calls",
+    sql: `
+      CREATE TABLE IF NOT EXISTS tool_calls (
+        id TEXT PRIMARY KEY,
+        run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
+        conversation_id TEXT REFERENCES conversations(id) ON DELETE SET NULL,
+        tool_name TEXT NOT NULL,
+        permission_json TEXT NOT NULL DEFAULT '[]',
+        input_json TEXT NOT NULL,
+        output_json TEXT,
+        status TEXT NOT NULL,
+        started_at TEXT NOT NULL,
+        completed_at TEXT,
+        error_message TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS tool_calls_run_started_idx
+        ON tool_calls(run_id, started_at);
+    `,
+  },
+  {
+    id: "0005_add_tool_call_visibility",
+    sql: `
+      ALTER TABLE tool_calls
+        ADD COLUMN visibility TEXT NOT NULL DEFAULT 'user';
+    `,
+  },
+  {
+    id: KNOWLEDGE_MIGRATION_ID,
+    sql: KNOWLEDGE_SCHEMA_SQL,
+  },
+  {
+    id: "0007_add_tool_call_rendered",
+    sql: `
+      ALTER TABLE tool_calls
+        ADD COLUMN rendered_json TEXT;
+    `,
+  },
+] as const;
+
+export async function openCapsuleStore(capsule: LoadedAgentCapsule): Promise<SqliteAgentKitStore> {
+  if (capsule.config.storage.driver !== "sqlite" && capsule.config.storage.driver !== "agentkit") {
+    throw new AgentKitError(
+      "storage_not_supported",
+      `Storage driver "${capsule.config.storage.driver}" is not supported by the local runtime.`,
+    );
+  }
+
+  if (!capsule.storagePath) {
+    throw new AgentKitError("invalid_config", 'SQLite storage requires storage.path, usually ".agentkit/agentkit.db".');
+  }
+
+  return SqliteAgentKitStore.open(capsule.storagePath);
+}
+
+async function openSqliteDatabase(dbPath: string): Promise<SqliteDatabase> {
+  if (typeof (globalThis as { Bun?: unknown }).Bun !== "undefined") {
+    const bunSqliteSpecifier: string = "bun:sqlite";
+    const sqlite = (await import(bunSqliteSpecifier)) as {
+      Database: new (path: string, options?: { create?: boolean; readwrite?: boolean }) => SqliteDatabase;
+    };
+    return new sqlite.Database(dbPath, { create: true, readwrite: true });
+  }
+
+  const sqlite = (await import("node:sqlite")) as {
+    DatabaseSync: new (path: string) => SqliteDatabase;
+  };
+  return new sqlite.DatabaseSync(dbPath);
+}
+
+function sqliteColumnNames(statement: SqliteStatement): string[] {
+  if (statement.columns) {
+    return statement.columns().map((column) => column.name);
+  }
+
+  return statement.columnNames ?? [];
+}
+
+export class SqliteAgentKitStore {
+  static async open(dbPath: string): Promise<SqliteAgentKitStore> {
+    await mkdir(dirname(dbPath), { recursive: true });
+    const database = await openSqliteDatabase(dbPath);
+    const store = new SqliteAgentKitStore(dbPath, database);
+    try {
+      store.migrate();
+    } catch (error) {
+      database.close();
+      throw translateSqliteError(error);
+    }
+    return store;
+  }
+
+  private constructor(
+    readonly dbPath: string,
+    private readonly db: SqliteDatabase,
+  ) {}
+
+  private applicationTransactionActive = false;
+
+  close(): void {
+    this.db.close();
+  }
+
+  createConversation(input: { id?: string; agentName: string; title: string | null; now?: string }): ConversationSummary {
+    return this.sqlite(() => {
+      const now = input.now ?? new Date().toISOString();
+      const id = input.id ?? randomId();
+
+      this.db
+        .prepare(
+          `
+        INSERT INTO conversations (id, agent_name, title, created_at, updated_at, metadata_json)
+        VALUES ($id, $agentName, $title, $createdAt, $updatedAt, '{}')
+      `,
+        )
+        .run({
+          $id: id,
+          $agentName: input.agentName,
+          $title: input.title,
+          $createdAt: now,
+          $updatedAt: now,
+        });
+
+      return {
+        id,
+        agentName: input.agentName,
+        title: input.title,
+        createdAt: now,
+        updatedAt: now,
+        messageCount: 0,
+      };
+    });
+  }
+
+  appendMessage(input: {
+    conversationId: string;
+    role: AgentMessageRole;
+    content: string;
+    now?: string;
+  }): StoredMessage {
+    return this.sqlite(() => {
+      const now = input.now ?? new Date().toISOString();
+      const sequence = this.nextMessageSequence(input.conversationId);
+      const id = randomId();
+
+      const insertMessage = () => this.transaction(() => {
+        this.db
+          .prepare(
+            `
+          INSERT INTO messages (id, conversation_id, role, content, created_at, sequence, metadata_json)
+          VALUES ($id, $conversationId, $role, $content, $createdAt, $sequence, '{}')
+        `,
+          )
+          .run({
+            $id: id,
+            $conversationId: input.conversationId,
+            $role: input.role,
+            $content: input.content,
+            $createdAt: now,
+            $sequence: sequence,
+          });
+
+        this.touchConversation(input.conversationId, now);
+      });
+
+      insertMessage();
+
+      return {
+        id,
+        conversationId: input.conversationId,
+        role: input.role,
+        content: input.content,
+        createdAt: now,
+        sequence,
+      };
+    });
+  }
+
+  createRun(input: {
+    conversationId: string;
+    provider: string;
+    model: string;
+    status?: RunStatus;
+    startedAt?: string;
+  }): { id: string; conversationId: string; startedAt: string; status: RunStatus } {
+    return this.sqlite(() => {
+      const id = randomId();
+      const startedAt = input.startedAt ?? new Date().toISOString();
+      const status = input.status ?? "running";
+
+      this.db
+        .prepare(
+          `
+        INSERT INTO runs (
+          id,
+          conversation_id,
+          provider,
+          model,
+          status,
+          started_at,
+          metadata_json
+        )
+        VALUES (
+          $id,
+          $conversationId,
+          $provider,
+          $model,
+          $status,
+          $startedAt,
+          '{}'
+        )
+      `,
+        )
+        .run({
+          $id: id,
+          $conversationId: input.conversationId,
+          $provider: input.provider,
+          $model: input.model,
+          $status: status,
+          $startedAt: startedAt,
+        });
+
+      return { id, conversationId: input.conversationId, startedAt, status };
+    });
+  }
+
+  completeRun(input: {
+    runId: string;
+    status: RunStatus;
+    completedAt?: string;
+    usage?: ProviderRunResult["usage"];
+    errorCode?: string;
+    errorMessage?: string;
+  }): void {
+    this.sqlite(() => {
+      this.db
+        .prepare(
+          `
+        UPDATE runs
+        SET
+          status = $status,
+          completed_at = $completedAt,
+          input_tokens = $inputTokens,
+          output_tokens = $outputTokens,
+          total_tokens = $totalTokens,
+          error_code = $errorCode,
+          error_message = $errorMessage
+        WHERE id = $runId
+      `,
+        )
+        .run({
+          $runId: input.runId,
+          $status: input.status,
+          $completedAt: input.completedAt ?? new Date().toISOString(),
+          $inputTokens: input.usage?.inputTokens ?? null,
+          $outputTokens: input.usage?.outputTokens ?? null,
+          $totalTokens: input.usage?.totalTokens ?? null,
+          $errorCode: input.errorCode ?? null,
+          $errorMessage: redactSecrets(input.errorMessage ?? null),
+        });
+    });
+  }
+
+  createToolCall(input: {
+    runId: string;
+    conversationId: string;
+    toolName: string;
+    visibility?: ToolCallVisibility;
+    permissions?: string[];
+    input: unknown;
+    startedAt?: string;
+    secretValues?: string[];
+  }): {
+    id: string;
+    runId: string;
+    conversationId: string;
+    toolName: string;
+    visibility: ToolCallVisibility;
+    startedAt: string;
+    status: ToolCallStatus;
+  } {
+    return this.sqlite(() => {
+      const id = randomId();
+      const startedAt = input.startedAt ?? new Date().toISOString();
+      const status: ToolCallStatus = "running";
+      const visibility = input.visibility ?? "user";
+
+      this.db
+        .prepare(
+          `
+        INSERT INTO tool_calls (
+          id,
+          run_id,
+          conversation_id,
+          tool_name,
+          visibility,
+          permission_json,
+          input_json,
+          status,
+          started_at
+        )
+        VALUES (
+          $id,
+          $runId,
+          $conversationId,
+          $toolName,
+          $visibility,
+          $permissionJson,
+          $inputJson,
+          $status,
+          $startedAt
+        )
+      `,
+        )
+        .run({
+          $id: id,
+          $runId: input.runId,
+          $conversationId: input.conversationId,
+          $toolName: input.toolName,
+          $visibility: visibility,
+          $permissionJson: serializeJson(input.permissions ?? [], input.secretValues),
+          $inputJson: serializeJson(input.input, input.secretValues),
+          $status: status,
+          $startedAt: startedAt,
+        });
+
+      return {
+        id,
+        runId: input.runId,
+        conversationId: input.conversationId,
+        toolName: input.toolName,
+        visibility,
+        startedAt,
+        status,
+      };
+    });
+  }
+
+  completeToolCall(input: {
+    toolCallId: string;
+    status: ToolCallStatus;
+    output?: unknown;
+    rendered?: unknown;
+    completedAt?: string;
+    errorMessage?: string;
+    secretValues?: string[];
+  }): void {
+    this.sqlite(() => {
+      this.db
+        .prepare(
+          `
+        UPDATE tool_calls
+        SET
+          status = $status,
+          output_json = $outputJson,
+          rendered_json = $renderedJson,
+          completed_at = $completedAt,
+          error_message = $errorMessage
+        WHERE id = $toolCallId
+      `,
+        )
+        .run({
+          $toolCallId: input.toolCallId,
+          $status: input.status,
+          $outputJson: input.output === undefined ? null : serializeJson(input.output, input.secretValues),
+          $renderedJson: input.rendered === undefined ? null : serializeJson(input.rendered, input.secretValues),
+          $completedAt: input.completedAt ?? new Date().toISOString(),
+          $errorMessage: redactSecrets(input.errorMessage ?? null, input.secretValues),
+        });
+    });
+  }
+
+  listConversations(): ConversationSummary[] {
+    return this.sqlite(() => {
+      const rows = this.db
+        .prepare(
+          `
+        SELECT
+          conversations.id,
+          conversations.agent_name,
+          conversations.title,
+          conversations.created_at,
+          conversations.updated_at,
+          COUNT(messages.id) AS message_count
+        FROM conversations
+        LEFT JOIN messages ON messages.conversation_id = conversations.id
+        GROUP BY conversations.id
+        ORDER BY conversations.updated_at DESC
+      `,
+        )
+        .all() as SqliteRow[];
+
+      return rows.map(conversationSummaryFromRow);
+    });
+  }
+
+  getConversation(id: string): ConversationRecord | null {
+    return this.sqlite(() => {
+      const conversationRow = this.db
+        .prepare(
+          `
+        SELECT
+          conversations.id,
+          conversations.agent_name,
+          conversations.title,
+          conversations.created_at,
+          conversations.updated_at,
+          COUNT(messages.id) AS message_count
+        FROM conversations
+        LEFT JOIN messages ON messages.conversation_id = conversations.id
+        WHERE conversations.id = $id
+        GROUP BY conversations.id
+      `,
+        )
+        .get({ $id: id }) as SqliteRow | null;
+
+      if (!conversationRow) {
+        return null;
+      }
+
+      const messageRows = this.db
+        .prepare(
+          `
+        SELECT id, conversation_id, role, content, created_at, sequence
+        FROM messages
+        WHERE conversation_id = $id
+        ORDER BY sequence ASC
+      `,
+        )
+        .all({ $id: id }) as SqliteRow[];
+
+      return {
+        ...conversationSummaryFromRow(conversationRow),
+        messages: messageRows.map(storedMessageFromRow),
+      };
+    });
+  }
+
+  listRunsForConversation(conversationId: string): StoredRun[] {
+    return this.sqlite(() => {
+      const rows = this.db
+        .prepare(
+          `
+          SELECT
+            id,
+            conversation_id,
+            provider,
+            model,
+            status,
+            input_tokens,
+            output_tokens,
+            total_tokens,
+            started_at,
+            completed_at,
+            error_code,
+            error_message
+          FROM runs
+          WHERE conversation_id = $conversationId
+          ORDER BY started_at ASC
+        `,
+        )
+        .all({ $conversationId: conversationId }) as SqliteRow[];
+
+      return rows.map(storedRunFromRow);
+    });
+  }
+
+  listToolCallsForRun(runId: string): StoredToolCall[] {
+    return this.sqlite(() => {
+      const rows = this.db
+        .prepare(
+          `
+          SELECT
+            id,
+            run_id,
+            conversation_id,
+            tool_name,
+            visibility,
+            input_json,
+            output_json,
+            rendered_json,
+            status,
+            started_at,
+            completed_at,
+            error_message
+          FROM tool_calls
+          WHERE run_id = $runId
+          ORDER BY started_at ASC
+        `,
+        )
+        .all({ $runId: runId }) as SqliteRow[];
+
+      return rows.map(storedToolCallFromRow);
+    });
+  }
+
+  applyApplicationMigrations(migrations: Array<{ id: string; sql: string }>): { applied: string[]; skipped: string[] } {
+    return this.sqlite(() => {
+      if (migrations.length === 0) {
+        return { applied: [], skipped: [] };
+      }
+
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS agentkit_app_migrations (
+          id TEXT PRIMARY KEY,
+          applied_at TEXT NOT NULL
+        )
+      `);
+
+      const applied = new Set(
+        (
+          this.db.prepare("SELECT id FROM agentkit_app_migrations").all() as Array<{
+            id: string;
+          }>
+        ).map((row) => row.id),
+      );
+      const result = {
+        applied: [] as string[],
+        skipped: [] as string[],
+      };
+
+      for (const migration of migrations) {
+        if (applied.has(migration.id)) {
+          result.skipped.push(migration.id);
+          continue;
+        }
+
+        const statements = splitSqlStatements(migration.sql);
+        this.transaction(() => {
+          for (const statement of statements) {
+            this.db.exec(statement);
+          }
+
+          this.db
+            .prepare("INSERT INTO agentkit_app_migrations (id, applied_at) VALUES ($id, $appliedAt)")
+            .run({ $id: migration.id, $appliedAt: new Date().toISOString() });
+        });
+        result.applied.push(migration.id);
+      }
+
+      return result;
+    });
+  }
+
+  applyApplicationSchema(source: string): void {
+    this.sqlite(() => {
+      const statements = splitSqlStatements(source);
+
+      if (statements.length === 0) {
+        return;
+      }
+
+      const transaction = () => this.transaction(() => {
+        for (const statement of statements) {
+          this.db.exec(statement);
+        }
+      });
+
+      transaction();
+    });
+  }
+
+  executeApplicationSql(sql: string, args: DatabaseArgs = []): DatabaseResult {
+    return this.sqlite(() => {
+      const statement = this.db.prepare(sql);
+      const columns = sqliteColumnNames(statement);
+      const bindings = [...args] as unknown[];
+
+      if (columns.length > 0) {
+        return {
+          rows: normalizeRows((statement.all as (...bindings: unknown[]) => SqliteRow[])(...bindings)),
+          rowsAffected: 0,
+          lastInsertRowid: null,
+          columns,
+        };
+      }
+
+      const result = (statement.run as (...bindings: unknown[]) => { changes: number; lastInsertRowid: number | bigint })(
+        ...bindings,
+      );
+      return {
+        rows: [],
+        rowsAffected: result.changes,
+        lastInsertRowid: normalizeLastInsertRowid(result.lastInsertRowid),
+        columns: [],
+      };
+    });
+  }
+
+  executeApplicationBatch(statements: DatabaseStatement[]): DatabaseResult[] {
+    return this.runApplicationTransaction(() =>
+      statements.map((statement) => this.executeApplicationSql(statement.sql, statement.args ?? [])),
+    ) as unknown as DatabaseResult[];
+  }
+
+  runApplicationTransaction<T>(callback: () => Promise<T> | T): Promise<T>;
+  runApplicationTransaction<T>(callback: () => T): T;
+  runApplicationTransaction<T>(callback: () => Promise<T> | T): Promise<T> | T {
+    if (this.applicationTransactionActive) {
+      throw new AgentKitError(
+        "database_transaction_unsupported",
+        "Nested database transactions are not supported. Use one ctx.db.transaction callback or ctx.db.batch call.",
+      );
+    }
+
+    return this.sqlite(() => {
+      this.applicationTransactionActive = true;
+      this.db.exec("BEGIN IMMEDIATE");
+
+      let callbackResult: Promise<T> | T;
+
+      try {
+        callbackResult = callback();
+      } catch (error) {
+        this.rollbackApplicationTransaction();
+        throw error;
+      }
+
+      if (callbackResult && typeof (callbackResult as Promise<T>).then === "function") {
+        return (callbackResult as Promise<T>).then(
+          (value) => {
+            this.commitApplicationTransaction();
+            return value;
+          },
+          (error) => {
+            this.rollbackApplicationTransaction();
+            throw error;
+          },
+        );
+      }
+
+      this.commitApplicationTransaction();
+      return callbackResult;
+    });
+  }
+
+  private migrate(): void {
+    this.db.exec(`PRAGMA busy_timeout = ${sqliteBusyTimeoutMs()}`);
+    this.db.exec("PRAGMA foreign_keys = ON");
+    this.db.exec("PRAGMA journal_mode = WAL");
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS agentkit_migrations (
+        id TEXT PRIMARY KEY,
+        applied_at TEXT NOT NULL
+      )
+    `);
+
+    const applied = new Set(
+      (
+        this.db.prepare("SELECT id FROM agentkit_migrations").all() as Array<{
+          id: string;
+        }>
+      ).map((row) => row.id),
+    );
+
+    const transaction = () => this.transaction(() => {
+      for (const migration of MIGRATIONS) {
+        if (applied.has(migration.id)) {
+          continue;
+        }
+
+        this.db.exec(migration.sql);
+        this.db
+          .prepare("INSERT INTO agentkit_migrations (id, applied_at) VALUES ($id, $appliedAt)")
+          .run({ $id: migration.id, $appliedAt: new Date().toISOString() });
+      }
+    });
+
+    transaction();
+  }
+
+  private nextMessageSequence(conversationId: string): number {
+    const row = this.db
+      .prepare("SELECT COALESCE(MAX(sequence), 0) + 1 AS next_sequence FROM messages WHERE conversation_id = $id")
+      .get({ $id: conversationId }) as { next_sequence: number };
+
+    return row.next_sequence;
+  }
+
+  private touchConversation(conversationId: string, updatedAt: string): void {
+    this.db
+      .prepare("UPDATE conversations SET updated_at = $updatedAt WHERE id = $id")
+      .run({ $id: conversationId, $updatedAt: updatedAt });
+  }
+
+  private sqlite<T>(operation: () => T): T {
+    try {
+      return operation();
+    } catch (error) {
+      throw translateSqliteError(error);
+    }
+  }
+
+  private commitApplicationTransaction(): void {
+    try {
+      this.db.exec("COMMIT");
+    } finally {
+      this.applicationTransactionActive = false;
+    }
+  }
+
+  private rollbackApplicationTransaction(): void {
+    try {
+      this.db.exec("ROLLBACK");
+    } finally {
+      this.applicationTransactionActive = false;
+    }
+  }
+
+  private transaction<T>(callback: () => T): T {
+    this.db.exec("BEGIN IMMEDIATE");
+
+    try {
+      const result = callback();
+      this.db.exec("COMMIT");
+      return result;
+    } catch (error) {
+      this.db.exec("ROLLBACK");
+      throw error;
+    }
+  }
+}
+
+function conversationSummaryFromRow(row: SqliteRow): ConversationSummary {
+  return {
+    id: String(row.id),
+    agentName: String(row.agent_name),
+    title: row.title === null ? null : String(row.title),
+    createdAt: String(row.created_at),
+    updatedAt: String(row.updated_at),
+    messageCount: Number(row.message_count),
+  };
+}
+
+function storedMessageFromRow(row: SqliteRow): StoredMessage {
+  const role = String(row.role);
+
+  if (role !== "system" && role !== "user" && role !== "assistant") {
+    throw new AgentKitError("storage_error", `Invalid stored message role "${role}".`);
+  }
+
+  return {
+    id: String(row.id),
+    conversationId: String(row.conversation_id),
+    role,
+    content: String(row.content),
+    createdAt: String(row.created_at),
+    sequence: Number(row.sequence),
+  };
+}
+
+function storedRunFromRow(row: SqliteRow): StoredRun {
+  const status = String(row.status);
+
+  if (status !== "running" && status !== "completed" && status !== "failed") {
+    throw new AgentKitError("storage_error", `Invalid stored run status "${status}".`);
+  }
+
+  return {
+    id: String(row.id),
+    conversationId: row.conversation_id === null ? null : String(row.conversation_id),
+    provider: String(row.provider),
+    model: String(row.model),
+    status,
+    usage: {
+      inputTokens: nullableNumber(row.input_tokens),
+      outputTokens: nullableNumber(row.output_tokens),
+      totalTokens: nullableNumber(row.total_tokens),
+    },
+    startedAt: String(row.started_at),
+    completedAt: row.completed_at === null ? null : String(row.completed_at),
+    errorCode: row.error_code === null ? null : String(row.error_code),
+    errorMessage: row.error_message === null ? null : String(row.error_message),
+  };
+}
+
+function storedToolCallFromRow(row: SqliteRow): StoredToolCall {
+  const status = String(row.status);
+  const visibility = String(row.visibility);
+
+  if (status !== "running" && status !== "completed" && status !== "failed") {
+    throw new AgentKitError("storage_error", `Invalid stored tool call status "${status}".`);
+  }
+
+  if (visibility !== "user" && visibility !== "internal") {
+    throw new AgentKitError("storage_error", `Invalid stored tool call visibility "${visibility}".`);
+  }
+
+  return {
+    id: String(row.id),
+    runId: String(row.run_id),
+    conversationId: row.conversation_id === null ? null : String(row.conversation_id),
+    toolName: String(row.tool_name),
+    visibility,
+    input: parseStoredJson(row.input_json),
+    output: row.output_json === null ? undefined : parseStoredJson(row.output_json),
+    rendered: row.rendered_json === null ? undefined : parseStoredJson(row.rendered_json),
+    status,
+    startedAt: String(row.started_at),
+    completedAt: row.completed_at === null ? null : String(row.completed_at),
+    errorMessage: row.error_message === null ? null : String(row.error_message),
+  };
+}
+
+function nullableNumber(value: unknown): number | null {
+  return value === null || value === undefined ? null : Number(value);
+}
+
+function parseStoredJson(value: unknown): unknown {
+  if (typeof value !== "string") {
+    return value;
+  }
+
+  return JSON.parse(value);
+}
+
+function normalizeRows(rows: SqliteRow[]): DatabaseRow[] {
+  return rows.map((row) =>
+    Object.fromEntries(
+      Object.entries(row).map(([key, value]) => {
+        if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+          return [key, value];
+        }
+
+        if (typeof value === "bigint") {
+          const numberValue = Number(value);
+          return [key, Number.isSafeInteger(numberValue) ? numberValue : value.toString()];
+        }
+
+        if (value instanceof Uint8Array) {
+          return [key, Buffer.from(value).toString("base64")];
+        }
+
+        return [key, String(value)];
+      }),
+    ),
+  );
+}
+
+function normalizeLastInsertRowid(value: number | bigint): number | string {
+  if (typeof value === "number") {
+    return value;
+  }
+
+  const numberValue = Number(value);
+  return Number.isSafeInteger(numberValue) ? numberValue : value.toString();
+}
+
+function splitSqlStatements(source: string): string[] {
+  return source
+    .split(";")
+    .map((statement) => statement.trim())
+    .filter(Boolean);
+}
+
+function serializeJson(value: unknown, secretValues: string[] = []): string {
+  return redactSecrets(JSON.stringify(value), secretValues);
+}
+
+function redactSecrets(value: string, secretValues?: string[]): string;
+function redactSecrets(value: null, secretValues?: string[]): null;
+function redactSecrets(value: string | null, secretValues?: string[]): string | null;
+function redactSecrets(value: string | null, secretValues: string[] = []): string | null {
+  if (value === null) {
+    return null;
+  }
+
+  let redacted = value;
+
+  for (const secret of secretValues) {
+    if (!secret) {
+      continue;
+    }
+
+    redacted = redacted.split(secret).join("[REDACTED]");
+  }
+
+  return redactSecretPatterns(redacted);
+}
+
+function redactSecretPatterns(value: string): string {
+  return value
+    .replace(/bot[0-9]{5,}:[A-Za-z0-9_-]{20,}/g, "bot[REDACTED]")
+    .replace(/\b(?:sk|rk|pk|zap|meta|telegram|bearer)[-_A-Za-z0-9]{16,}\b/gi, "[REDACTED]")
+    .replace(/\b[A-Za-z0-9_-]{24,}\.[A-Za-z0-9_-]{24,}\.[A-Za-z0-9_-]{24,}\b/g, "[REDACTED]");
+}
+
+function randomId(): string {
+  return crypto.randomUUID();
+}
+
+function translateSqliteError(error: unknown): never {
+  if (isAgentKitError(error)) {
+    throw error;
+  }
+
+  if (isSqliteBusyError(error)) {
+    throw new AgentKitError(
+      "database_unavailable",
+      "The local SQLite database is busy or locked. Wait for the active AgentKit run to finish, then retry.",
+      { cause: error },
+    );
+  }
+
+  if (isSqliteConstraintError(error)) {
+    throw new AgentKitError("constraint_conflict", "Database constraint conflict.", { cause: error });
+  }
+
+  if (isSqliteSchemaError(error)) {
+    throw new AgentKitError("database_schema_error", sqliteSchemaErrorMessage(error), { cause: error });
+  }
+
+  if (isSqliteQueryError(error)) {
+    throw new AgentKitError("database_query_invalid", "Database query is invalid.", { cause: error });
+  }
+
+  throw error;
+}
+
+function isAgentKitError(error: unknown): error is AgentKitError {
+  return error instanceof AgentKitError;
+}
+
+function isSqliteBusyError(error: unknown): boolean {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+
+  const record = error as Record<string, unknown>;
+  const code = typeof record.code === "string" ? record.code : "";
+  const message = error instanceof Error ? error.message : String(error);
+
+  return code === "SQLITE_BUSY" || code === "SQLITE_LOCKED" || /database is locked|database table is locked/i.test(message);
+}
+
+function isSqliteConstraintError(error: unknown): boolean {
+  const code = sqliteErrorCode(error);
+  const message = error instanceof Error ? error.message : String(error);
+
+  return code.startsWith("SQLITE_CONSTRAINT") || /constraint failed|UNIQUE constraint|FOREIGN KEY constraint|CHECK constraint/i.test(message);
+}
+
+function isSqliteSchemaError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /no such table|no such column|has no column named|database schema has changed|malformed database schema/i.test(message);
+}
+
+function isSqliteQueryError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /syntax error|incomplete input|near ".+": syntax error|SQL logic error/i.test(message);
+}
+
+function sqliteSchemaErrorMessage(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return `Database schema error: ${message}`;
+}
+
+function sqliteErrorCode(error: unknown): string {
+  if (!error || typeof error !== "object") {
+    return "";
+  }
+
+  const code = (error as Record<string, unknown>).code;
+  return typeof code === "string" ? code : "";
+}
+
+function sqliteBusyTimeoutMs(): number {
+  const value = Number(process.env.AGENTKIT_SQLITE_BUSY_TIMEOUT_MS ?? 5000);
+
+  return Number.isInteger(value) && value >= 0 ? value : 5000;
+}