@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/storage.ts

@@ -0,0 +1,807 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
+
+type Log = { error?: (message: string) => void };
+
+export type ClawChatStoreOptions = {
+  dbPath?: string;
+  log?: Log;
+};
+
+export type ActivationInput = {
+  platform: string;
+  accountId: string;
+  userId?: string | null;
+  ownerUserId?: string | null;
+  accessToken?: string | null;
+  refreshToken?: string | null;
+  conversationId?: string | null;
+  activatedAt?: number;
+  loginMethod?: string | null;
+};
+
+export type ActivationBootstrapInput = {
+  platform: string;
+  accountId: string;
+  staleClaimMs?: number;
+};
+
+export type ActivationBootstrapConversation = { conversationId: string };
+
+export type MarkActivationBootstrapSentInput = ActivationBootstrapInput & {
+  conversationId: string;
+};
+
+export type ReleaseActivationBootstrapClaimInput = ActivationBootstrapInput & {
+  conversationId: string;
+};
+
+export type MessageInput = {
+  platform: string;
+  accountId: string;
+  kind: string;
+  direction: string;
+  eventType: string;
+  traceId?: string | null;
+  chatId?: string | null;
+  messageId?: string | null;
+  text?: string | null;
+  raw?: unknown;
+  createdAt?: number;
+};
+
+export type MessageAcknowledgedInput = {
+  accountId: string;
+  kind: string;
+  direction: string;
+  messageId: string;
+  protocolMessageId?: string | null;
+  ackedAt?: number | null;
+};
+
+export type StartConnectionInput = {
+  platform: string;
+  accountId: string;
+  attempt?: number | null;
+  reconnectCount?: number | null;
+  connectStartedAt?: number;
+};
+
+export type ConnectionUpdateOptions = { at?: number };
+
+export type ConnectionReadyOptions = ConnectionUpdateOptions & {
+  resolvedDeviceId?: string | null;
+  deliveryMode?: string | null;
+};
+
+export type FinishConnectionInput = {
+  state: string;
+  disconnectedAt?: number;
+  closeCode?: number | null;
+  closeReason?: string | null;
+  error?: string | null;
+};
+
+export type ToolCallInput = {
+  platform: string;
+  accountId?: string | null;
+  toolName: string;
+  args?: unknown;
+  result?: unknown;
+  error?: string | null;
+  startedAt?: number;
+  endedAt?: number | null;
+};
+
+export type ConversationAccountInput = {
+  platform: string;
+  accountId: string;
+};
+
+export type ActivationConversation = {
+  conversationId: string;
+  conversationType: string | null;
+  metadataVersion: number | null;
+  lastSeenAt: number | null;
+  lastRefreshedAt: number | null;
+};
+
+type Migration = { version: number; name: string; sql: string };
+
+const DB_FILENAME = "clawchat.sqlite";
+const DEFAULT_BOOTSTRAP_CLAIM_STALE_MS = 5 * 60 * 1000;
+
+const MIGRATIONS: Migration[] = [
+  {
+    version: 1,
+    name: "initial_schema",
+    sql: `
+CREATE TABLE IF NOT EXISTS schema_migrations (
+  version INTEGER PRIMARY KEY,
+  name TEXT NOT NULL,
+  applied_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS clawchat_messages (
+  id INTEGER PRIMARY KEY,
+  platform TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  direction TEXT NOT NULL,
+  event_type TEXT NOT NULL,
+  trace_id TEXT,
+  chat_id TEXT,
+  message_id TEXT,
+  text TEXT,
+  raw_json TEXT,
+  created_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS activations (
+  platform TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  user_id TEXT,
+  access_token TEXT,
+  refresh_token TEXT,
+  activated_at INTEGER NOT NULL,
+  login_method TEXT,
+  updated_at INTEGER NOT NULL,
+  PRIMARY KEY (platform, account_id)
+);
+
+CREATE TABLE IF NOT EXISTS connections (
+  id INTEGER PRIMARY KEY,
+  platform TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  attempt INTEGER,
+  reconnect_count INTEGER,
+  state TEXT NOT NULL,
+  connect_started_at INTEGER,
+  connect_sent_at INTEGER,
+  ready_at INTEGER,
+  disconnected_at INTEGER,
+  close_code INTEGER,
+  close_reason TEXT,
+  error TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS tool_calls (
+  id INTEGER PRIMARY KEY,
+  platform TEXT NOT NULL,
+  account_id TEXT,
+  tool_name TEXT NOT NULL,
+  args_json TEXT,
+  result_json TEXT,
+  error TEXT,
+  started_at INTEGER NOT NULL,
+  ended_at INTEGER,
+  duration_ms INTEGER,
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_clawchat_messages_chat_created
+  ON clawchat_messages(chat_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_clawchat_messages_message_id
+  ON clawchat_messages(message_id);
+CREATE INDEX IF NOT EXISTS idx_connections_account_created
+  ON connections(platform, account_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_tool_calls_name_created
+  ON tool_calls(tool_name, created_at);
+`,
+  },
+  {
+    version: 2,
+    name: "message_idempotency",
+    sql: `
+CREATE UNIQUE INDEX IF NOT EXISTS idx_clawchat_messages_message_unique
+  ON clawchat_messages(account_id, direction, kind, message_id)
+  WHERE kind = 'message' AND message_id IS NOT NULL;
+`,
+  },
+  {
+    version: 3,
+    name: "activation_bootstrap",
+    sql: `
+ALTER TABLE activations ADD COLUMN conversation_id TEXT;
+ALTER TABLE activations ADD COLUMN bootstrap_sent INTEGER NOT NULL DEFAULT 1;
+ALTER TABLE activations ADD COLUMN bootstrap_claimed_at INTEGER;
+`,
+  },
+  {
+    version: 4,
+    name: "activation_owner_user_id",
+    sql: `
+ALTER TABLE activations ADD COLUMN owner_user_id TEXT;
+`,
+  },
+  {
+    version: 5,
+    name: "connection_metadata",
+    sql: `
+ALTER TABLE connections ADD COLUMN resolved_device_id TEXT;
+ALTER TABLE connections ADD COLUMN delivery_mode TEXT;
+`,
+  },
+  {
+    version: 6,
+    name: "message_ack_status",
+    sql: `
+ALTER TABLE clawchat_messages ADD COLUMN send_status TEXT;
+ALTER TABLE clawchat_messages ADD COLUMN protocol_message_id TEXT;
+ALTER TABLE clawchat_messages ADD COLUMN acked_at INTEGER;
+ALTER TABLE clawchat_messages ADD COLUMN send_error TEXT;
+`,
+  },
+];
+
+function fallbackDbPath(): string {
+  const home = process.env.OPENCLAW_HOME || path.join(os.homedir(), ".openclaw");
+  return path.join(home, DB_FILENAME);
+}
+
+export function clawChatDbPathForStateDir(stateDir: string): string {
+  return path.join(stateDir, DB_FILENAME);
+}
+
+export function defaultDbPath(): string {
+  try {
+    return clawChatDbPathForStateDir(resolveStateDir());
+  } catch {
+    return fallbackDbPath();
+  }
+}
+
+function toNullableString(value: unknown): string | null {
+  return typeof value === "string" ? value : value == null ? null : String(value);
+}
+
+function toJson(value: unknown): string | null {
+  if (value === undefined) return null;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return null;
+  }
+}
+
+function hasOwn(value: object, key: PropertyKey): 0 | 1 {
+  return Object.prototype.hasOwnProperty.call(value, key) ? 1 : 0;
+}
+
+function safeErrorMessage(err: unknown): string {
+  const message = err instanceof Error ? err.message : String(err);
+  return message
+    .replace(/(access[_-]?token["'\s:=]+)[^"'\s,}]+/gi, "$1[REDACTED]")
+    .replace(/(refresh[_-]?token["'\s:=]+)[^"'\s,}]+/gi, "$1[REDACTED]")
+    .replace(/(authorization["'\s:=]+bearer\s+)[^"'\s,}]+/gi, "$1[REDACTED]");
+}
+
+export class ClawChatStore {
+  readonly dbPath: string;
+  private readonly log?: Log;
+  private db: DatabaseSync | null = null;
+  private initialized = false;
+  private disabled = false;
+
+  constructor(options: ClawChatStoreOptions = {}) {
+    this.dbPath = options.dbPath ?? defaultDbPath();
+    this.log = options.log;
+  }
+
+  initialize(): void {
+    this.ensureInitialized();
+  }
+
+  listAppliedMigrations(): Array<{ version: number; name: string }> {
+    return this.read(() =>
+      this.requireDb()
+        .prepare("SELECT version, name FROM schema_migrations ORDER BY version")
+        .all() as Array<{ version: number; name: string }>,
+    ) ?? [];
+  }
+
+  upsertActivation(input: ActivationInput): void {
+    this.write(() => {
+      const now = input.activatedAt ?? Date.now();
+      const conversationId = input.conversationId?.trim() || null;
+      const userId = input.userId?.trim() || null;
+      const ownerUserId = input.ownerUserId?.trim() || null;
+      const accessToken = input.accessToken?.trim() || null;
+      const refreshToken = input.refreshToken?.trim() || null;
+      this.requireDb()
+        .prepare(
+          `INSERT INTO activations(
+            platform, account_id, user_id, owner_user_id, access_token, refresh_token,
+            activated_at, login_method, conversation_id, bootstrap_sent,
+            bootstrap_claimed_at, updated_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          ON CONFLICT(platform, account_id) DO UPDATE SET
+            user_id = excluded.user_id,
+            owner_user_id = excluded.owner_user_id,
+            access_token = excluded.access_token,
+            refresh_token = excluded.refresh_token,
+            activated_at = excluded.activated_at,
+            login_method = excluded.login_method,
+            conversation_id = excluded.conversation_id,
+            bootstrap_sent = excluded.bootstrap_sent,
+            bootstrap_claimed_at = NULL,
+            updated_at = excluded.updated_at`,
+        )
+        .run(
+          input.platform,
+          input.accountId,
+          userId,
+          ownerUserId,
+          accessToken,
+          refreshToken,
+          now,
+          input.loginMethod ?? null,
+          conversationId,
+          conversationId ? 0 : 1,
+          null,
+          now,
+        );
+      void conversationId;
+    });
+  }
+
+  getActivationConversation(input: ConversationAccountInput): ActivationConversation | null {
+    return this.read(() => {
+      const row = this.requireDb()
+        .prepare(
+          `SELECT conversation_id
+          FROM activations
+          WHERE platform = ?
+            AND account_id = ?
+            AND conversation_id IS NOT NULL
+            AND conversation_id <> ''`,
+        )
+        .get(input.platform, input.accountId) as
+        | {
+            conversation_id?: unknown;
+          }
+        | undefined;
+      if (typeof row?.conversation_id !== "string") return null;
+      return {
+        conversationId: row.conversation_id,
+        conversationType: null,
+        metadataVersion: null,
+        lastSeenAt: null,
+        lastRefreshedAt: null,
+      };
+    }) ?? null;
+  }
+
+  claimPendingActivationBootstrap(
+    input: ActivationBootstrapInput,
+  ): ActivationBootstrapConversation | null {
+    return this.write(() => {
+      const now = Date.now();
+      const staleMs = Math.max(0, input.staleClaimMs ?? DEFAULT_BOOTSTRAP_CLAIM_STALE_MS);
+      const staleBefore = now - staleMs;
+      const row = this.requireDb()
+        .prepare(
+          `UPDATE activations SET
+            bootstrap_claimed_at = ?, updated_at = ?
+          WHERE platform = ?
+            AND account_id = ?
+            AND conversation_id IS NOT NULL
+            AND conversation_id <> ''
+            AND bootstrap_sent = 0
+            AND (bootstrap_claimed_at IS NULL OR bootstrap_claimed_at <= ?)
+          RETURNING conversation_id`,
+        )
+        .get(now, now, input.platform, input.accountId, staleBefore) as
+        | { conversation_id?: unknown }
+        | undefined;
+      const conversationId = row?.conversation_id;
+      return typeof conversationId === "string" && conversationId.length > 0
+        ? { conversationId }
+        : null;
+    }) ?? null;
+  }
+
+  releaseActivationBootstrapClaim(input: ReleaseActivationBootstrapClaimInput): boolean | null {
+    return this.write(() => {
+      const now = Date.now();
+      const result = this.requireDb()
+        .prepare(
+          `UPDATE activations SET
+            bootstrap_claimed_at = NULL,
+            updated_at = ?
+          WHERE platform = ?
+            AND account_id = ?
+            AND conversation_id = ?
+            AND bootstrap_sent = 0
+            AND bootstrap_claimed_at IS NOT NULL`,
+        )
+        .run(now, input.platform, input.accountId, input.conversationId);
+      return result.changes > 0;
+    });
+  }
+
+  markActivationBootstrapSent(input: MarkActivationBootstrapSentInput): boolean | null {
+    return this.write(() => {
+      const now = Date.now();
+      const result = this.requireDb()
+        .prepare(
+          `UPDATE activations SET
+            bootstrap_sent = 1,
+            bootstrap_claimed_at = NULL,
+            updated_at = ?
+          WHERE platform = ?
+            AND account_id = ?
+            AND conversation_id = ?
+            AND bootstrap_sent = 0
+            AND bootstrap_claimed_at IS NOT NULL`,
+        )
+        .run(now, input.platform, input.accountId, input.conversationId);
+      return result.changes > 0;
+    });
+  }
+
+  insertMessage(input: MessageInput): boolean | null {
+    return this.write(() => {
+      this.requireDb()
+        .prepare(
+          `INSERT INTO clawchat_messages(
+            platform, account_id, kind, direction, event_type, trace_id, chat_id,
+            message_id, text, raw_json, created_at, send_status
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        )
+        .run(
+          input.platform,
+          input.accountId,
+          input.kind,
+          input.direction,
+          input.eventType,
+          input.traceId ?? null,
+          input.chatId ?? null,
+          input.messageId ?? null,
+          input.text ?? null,
+          toJson(input.raw),
+          input.createdAt ?? Date.now(),
+          input.direction === "outbound" ? "pending" : null,
+        );
+      return true;
+    });
+  }
+
+  claimMessageOnce(input: MessageInput): true | false | null {
+    return this.write(() => {
+      const result = this.requireDb()
+        .prepare(
+          `INSERT OR IGNORE INTO clawchat_messages(
+            platform, account_id, kind, direction, event_type, trace_id, chat_id,
+            message_id, text, raw_json, created_at, send_status
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        )
+        .run(
+          input.platform,
+          input.accountId,
+          input.kind,
+          input.direction,
+          input.eventType,
+          input.traceId ?? null,
+          input.chatId ?? null,
+          input.messageId ?? null,
+          input.text ?? null,
+          toJson(input.raw),
+          input.createdAt ?? Date.now(),
+          input.direction === "outbound" ? "pending" : null,
+        );
+      return result.changes > 0;
+    });
+  }
+
+  markMessageAcknowledged(input: MessageAcknowledgedInput): boolean | null {
+    return this.write(() => {
+      const result = this.requireDb()
+        .prepare(
+          `UPDATE clawchat_messages SET
+            send_status = 'acknowledged',
+            protocol_message_id = ?,
+            acked_at = ?,
+            send_error = NULL
+          WHERE account_id = ? AND kind = ? AND direction = ? AND message_id = ?`,
+        )
+        .run(
+          input.protocolMessageId ?? input.messageId,
+          input.ackedAt ?? Date.now(),
+          input.accountId,
+          input.kind,
+          input.direction,
+          input.messageId,
+        );
+      return result.changes > 0;
+    });
+  }
+
+  updateMessageByIdentity(input: {
+    accountId: string;
+    kind: string;
+    direction: MessageInput["direction"];
+    messageId: string;
+    eventType: string;
+    traceId?: string | null;
+    chatId?: string | null;
+    text?: string | null;
+    raw?: unknown;
+  }): void {
+    this.write(() => {
+      this.requireDb()
+        .prepare(
+          `UPDATE clawchat_messages SET
+            event_type = ?, trace_id = ?, chat_id = ?, text = ?, raw_json = ?
+          WHERE account_id = ? AND kind = ? AND direction = ? AND message_id = ?`,
+        )
+        .run(
+          input.eventType,
+          input.traceId ?? null,
+          input.chatId ?? null,
+          input.text ?? null,
+          toJson(input.raw),
+          input.accountId,
+          input.kind,
+          input.direction,
+          input.messageId,
+        );
+    });
+  }
+
+  startConnection(input: StartConnectionInput): number | null {
+    return this.write(() => {
+      const now = input.connectStartedAt ?? Date.now();
+      const result = this.requireDb()
+        .prepare(
+          `INSERT INTO connections(
+            platform, account_id, attempt, reconnect_count, state,
+            connect_started_at, created_at, updated_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+        )
+        .run(
+          input.platform,
+          input.accountId,
+          input.attempt ?? null,
+          input.reconnectCount ?? null,
+          "connecting",
+          now,
+          now,
+          now,
+        );
+      return Number(result.lastInsertRowid);
+    }) ?? null;
+  }
+
+  markConnectSent(connectionId: number | null | undefined, options: ConnectionUpdateOptions = {}): void {
+    if (typeof connectionId !== "number") return;
+    this.updateConnectionTime(connectionId, "connect_sent_at", options.at ?? Date.now());
+  }
+
+  markConnectionReady(connectionId: number | null | undefined, options: ConnectionReadyOptions = {}): void {
+    if (typeof connectionId !== "number") return;
+    this.write(() => {
+      const now = options.at ?? Date.now();
+      this.requireDb()
+        .prepare(
+          `UPDATE connections SET
+            state = ?,
+            ready_at = ?,
+            resolved_device_id = CASE WHEN ? THEN ? ELSE resolved_device_id END,
+            delivery_mode = CASE WHEN ? THEN ? ELSE delivery_mode END,
+            updated_at = ?
+          WHERE id = ?`,
+        )
+        .run(
+          "ready",
+          now,
+          hasOwn(options, "resolvedDeviceId"),
+          options.resolvedDeviceId ?? null,
+          hasOwn(options, "deliveryMode"),
+          options.deliveryMode ?? null,
+          now,
+          connectionId,
+        );
+    });
+  }
+
+  finishConnection(connectionId: number | null | undefined, input: FinishConnectionInput): void {
+    if (typeof connectionId !== "number") return;
+    this.write(() => {
+      const now = input.disconnectedAt ?? Date.now();
+      this.requireDb()
+        .prepare(
+          `UPDATE connections SET
+            state = ?, disconnected_at = ?, close_code = ?, close_reason = ?, error = ?, updated_at = ?
+          WHERE id = ?`,
+        )
+        .run(
+          input.state,
+          now,
+          input.closeCode ?? null,
+          input.closeReason ?? null,
+          input.error ?? null,
+          now,
+          connectionId,
+        );
+    });
+  }
+
+  recordToolCall(input: ToolCallInput): void {
+    this.write(() => {
+      const startedAt = input.startedAt ?? Date.now();
+      const endedAt = input.endedAt ?? null;
+      const durationMs = endedAt == null ? null : Math.max(0, endedAt - startedAt);
+      this.requireDb()
+        .prepare(
+          `INSERT INTO tool_calls(
+            platform, account_id, tool_name, args_json, result_json, error,
+            started_at, ended_at, duration_ms, created_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        )
+        .run(
+          input.platform,
+          input.accountId ?? null,
+          input.toolName,
+          toJson(input.args),
+          toJson(input.result),
+          toNullableString(input.error),
+          startedAt,
+          endedAt,
+          durationMs,
+          startedAt,
+        );
+    });
+  }
+
+  getActivationForTest(platform: string, accountId: string): Record<string, unknown> | null {
+    return this.read(() =>
+      this.requireDb()
+        .prepare("SELECT * FROM activations WHERE platform = ? AND account_id = ?")
+        .get(platform, accountId) as Record<string, unknown> | undefined,
+    ) ?? null;
+  }
+
+  listMessagesForTest(): Record<string, unknown>[] {
+    return this.read(() =>
+      this.requireDb()
+        .prepare("SELECT * FROM clawchat_messages ORDER BY id")
+        .all() as Record<string, unknown>[],
+    ) ?? [];
+  }
+
+  listConnectionsForTest(): Record<string, unknown>[] {
+    return this.read(() =>
+      this.requireDb().prepare("SELECT * FROM connections ORDER BY id").all() as Record<string, unknown>[],
+    ) ?? [];
+  }
+
+  listToolCallsForTest(): Record<string, unknown>[] {
+    return this.read(() =>
+      this.requireDb().prepare("SELECT * FROM tool_calls ORDER BY id").all() as Record<string, unknown>[],
+    ) ?? [];
+  }
+
+  close(): void {
+    this.db?.close();
+    this.db = null;
+    this.initialized = false;
+  }
+
+  private updateConnectionTime(connectionId: number, field: "connect_sent_at", at: number): void {
+    this.write(() => {
+      this.requireDb()
+        .prepare(`UPDATE connections SET ${field} = ?, updated_at = ? WHERE id = ?`)
+        .run(at, at, connectionId);
+    });
+  }
+
+  private read<T>(fn: () => T): T | null {
+    if (!this.ensureInitialized()) return null;
+    try {
+      return fn();
+    } catch (err) {
+      this.logFailure("clawchat-plugin-openclaw sqlite read failed", err);
+      return null;
+    }
+  }
+
+  private write<T>(fn: () => T): T | null {
+    if (!this.ensureInitialized()) return null;
+    try {
+      return fn();
+    } catch (err) {
+      this.logFailure("clawchat-plugin-openclaw sqlite write failed", err);
+      return null;
+    }
+  }
+
+  private ensureInitialized(): boolean {
+    if (this.disabled) return false;
+    if (this.initialized) return true;
+    try {
+      fs.mkdirSync(path.dirname(this.dbPath), { recursive: true });
+      this.db = new DatabaseSync(this.dbPath);
+      this.db.exec("PRAGMA journal_mode=WAL");
+      try {
+        fs.chmodSync(this.dbPath, 0o600);
+      } catch {
+        // Best effort only; permissions vary by platform/filesystem.
+      }
+      this.applyMigrations();
+      this.initialized = true;
+      return true;
+    } catch (err) {
+      this.disabled = true;
+      this.logFailure("clawchat-plugin-openclaw sqlite disabled after initialization failure", err);
+      try {
+        this.db?.close();
+      } catch {
+        // best effort
+      }
+      this.db = null;
+      return false;
+    }
+  }
+
+  private applyMigrations(): void {
+    const db = this.requireDb();
+    db.exec(
+      `CREATE TABLE IF NOT EXISTS schema_migrations (
+        version INTEGER PRIMARY KEY,
+        name TEXT NOT NULL,
+        applied_at INTEGER NOT NULL
+      )`,
+    );
+    const hasMigration = db.prepare("SELECT 1 FROM schema_migrations WHERE version = ?");
+    const insertMigration = db.prepare(
+      "INSERT INTO schema_migrations(version, name, applied_at) VALUES (?, ?, ?)",
+    );
+    for (const migration of MIGRATIONS) {
+      if (hasMigration.get(migration.version)) continue;
+      db.exec("BEGIN");
+      try {
+        db.exec(migration.sql);
+        insertMigration.run(migration.version, migration.name, Date.now());
+        db.exec("COMMIT");
+      } catch (err) {
+        db.exec("ROLLBACK");
+        throw err;
+      }
+    }
+  }
+
+  private requireDb(): DatabaseSync {
+    if (!this.db) throw new Error("clawchat sqlite database is not open");
+    return this.db;
+  }
+
+  private logFailure(prefix: string, err: unknown): void {
+    this.log?.error?.(`${prefix}: ${safeErrorMessage(err)}`);
+  }
+}
+
+let singleton: ClawChatStore | null = null;
+
+export function createClawChatStore(options: ClawChatStoreOptions = {}): ClawChatStore {
+  return new ClawChatStore(options);
+}
+
+export function getClawChatStore(options: ClawChatStoreOptions = {}): ClawChatStore {
+  const dbPath = options.dbPath ?? defaultDbPath();
+  if (!singleton || singleton.dbPath !== dbPath) {
+    singleton?.close();
+    singleton = createClawChatStore({ ...options, dbPath });
+  }
+  return singleton;
+}
+
+export function resetClawChatStoreForTest(): void {
+  singleton?.close();
+  singleton = null;
+}