/** * SQLite DbAdapter -- durable persistence for `db("sqlite:./data.db")`. * * This is the full {@link DbAdapter} contract (sessions, messages, runs, tool * calls, traces, spans) on top of a real SQLite file, so a session written by * one process is readable by the next one. `MemoryDbAdapter` dies with the * process; this does not. * * NOT the same thing as `./sqlite.ts`. That module ships `SQLiteAdapter`, a * low-level transport with its own narrower table shapes and its own method * names (`addMessage`, `addTrace`, ...). It is kept for callers that already * use it; it is not what the `Agent` talks to, and it silently degrades to an * in-process Map when the native binding will not load. This adapter never * does that -- see "Driver loading" below. * * ## Driver loading * * Two drivers can back this adapter, tried in order: * * 1. `better-sqlite3` -- the declared dependency. It is a native module, so * its prebuilt binding is compiled against one specific Node ABI * (`NODE_MODULE_VERSION`). Installed under one Node major and run under * another, `new Database(...)` throws `ERR_DLOPEN_FAILED`. * 2. `node:sqlite` -- Node's own SQLite, built into Node >= 22.5. No native * build step, so no ABI to mismatch. It is flagged experimental by Node * and prints one `ExperimentalWarning` when first loaded. Same on-disk * format, so a file written by either driver reads in the other. * * If neither loads, every operation REJECTS with a message naming what each * driver did and how to fix it. It never falls back to memory: a persistence * layer that quietly stops persisting is the bug this module exists to fix. * * `PRAISONAI_SQLITE_DRIVER=better-sqlite3|node` pins the choice (useful to * reproduce a driver-specific failure); `driver` on the constructor does the * same per-instance. * * ## Schema (version 1.0) * * Table and column names mirror what the Python side persists * (`praisonaiagents/db/protocol.py`, `runs/sqlite_ledger.py`) so the two are * conceptually aligned: snake_case columns, JSON-encoded `metadata`, * epoch-millisecond timestamps. Only the fields TypeScript's `DbAdapter` * actually has are stored -- Python's `input_content`/`output_content`/ * `events` have no TypeScript counterpart and are not invented here. * * sessions(id PK, created_at, updated_at, metadata) * messages(id PK, session_id, run_id, role, content, name, tool_call_id, * tool_calls, created_at, metadata) * runs(id PK, session_id, agent_name, status, started_at, completed_at, * error, metadata, prompt_tokens, completion_tokens, total_tokens) * tool_calls(id PK, run_id, name, arguments, result, status, started_at, * completed_at, error) * traces(id PK, session_id, run_id, agent_name, started_at, completed_at, * status, metadata) * spans(id PK, trace_id, parent_id, name, started_at, completed_at, status, * attributes) * praisonai_meta(key PK, value) -- holds schema_version * * Timestamps are epoch milliseconds (`Date.now()`), matching the `DbMessage`/ * `DbRun` types, NOT Python's float seconds. */ import type { DbAdapter, DbSession, DbMessage, DbRun, DbToolCall, DbTrace, DbSpan } from './types'; /** Schema version stored in `praisonai_meta`. Mirrors Python's SCHEMA_VERSION. */ export declare const SQLITE_SCHEMA_VERSION = "1.0"; /** The only value types bound to a statement. `undefined` is never bound: */ /** `node:sqlite` rejects it outright and better-sqlite3 rejects it too. */ export type SqliteParam = string | number | null; /** A prepared statement, as both drivers expose one. */ export interface SqliteStatement { run(...params: SqliteParam[]): unknown; get(...params: SqliteParam[]): any; all(...params: SqliteParam[]): any[]; } /** An open database handle, normalised across drivers. */ export interface SqliteConnection { exec(sql: string): void; prepare(sql: string): SqliteStatement; close(): void; } /** A driver is a name plus a way to open a file. */ export interface SqliteDriver { name: string; open(filename: string): SqliteConnection; } export type SqliteDriverName = 'better-sqlite3' | 'node'; export interface SqliteDbAdapterOptions { /** File path, or `':memory:'` for a real but process-local SQLite database. */ filename: string; /** Pin the driver instead of trying each in turn. */ driver?: SqliteDriverName; /** * Override driver loading. Exists so tests can prove the failure path (an * unusable native binding must throw, not degrade); not part of the public * contract. */ driverLoader?: () => Promise; } export declare class SqliteDbAdapter implements DbAdapter { private readonly filename; private readonly driverPreference?; private readonly driverLoader?; private connection; private driver; private connecting; constructor(options: SqliteDbAdapterOptions | string); /** The file this adapter persists to (`':memory:'` for the in-process form). */ getFilename(): string; /** Which driver opened the database, once connected. */ getDriverName(): string | null; connect(): Promise; private openAndMigrate; private verifySchema; disconnect(): Promise; isConnected(): boolean; /** * The Agent never calls `connect()` -- it goes straight to `saveMessage` / * `getMessages` -- so every operation opens on demand. When the database * cannot be opened this rejects with {@link unavailableError}, which is the * point: no operation ever quietly succeeds against memory. */ private db; createSession(session: DbSession): Promise; getSession(id: string): Promise; updateSession(id: string, updates: Partial): Promise; deleteSession(id: string): Promise; listSessions(limit?: number, offset?: number): Promise; private rowToSession; saveMessage(message: DbMessage): Promise; getMessages(sessionId: string, limit?: number): Promise; deleteMessages(sessionId: string): Promise; private rowToMessage; createRun(run: DbRun): Promise; getRun(id: string): Promise; updateRun(id: string, updates: Partial): Promise; listRuns(sessionId: string, limit?: number): Promise; private rowToRun; saveToolCall(toolCall: DbToolCall): Promise; getToolCalls(runId: string): Promise; createTrace(trace: DbTrace): Promise; getTrace(id: string): Promise; updateTrace(id: string, updates: Partial): Promise; createSpan(span: DbSpan): Promise; getSpans(traceId: string): Promise; updateSpan(id: string, updates: Partial): Promise; /** Schema version recorded in the file. */ getSchemaVersion(): Promise; /** Drop every row, keeping the schema. Mirrors MemoryDbAdapter.clear(). */ clear(): Promise; } /** Factory mirroring `createSQLiteAdapter` in `./sqlite.ts`. */ export declare function createSqliteDbAdapter(options: SqliteDbAdapterOptions | string): SqliteDbAdapter;