ai-hist 0.6.0 → 0.8.2

package/dist/index.js

@@ -1,1249 +1,316 @@
 /**
- * TypeScript SDK for reading the ai-hist SQLite database.
+ * RelayHistory's public TypeScript API.
  *
- * Backed by sql.js (WASM SQLite) so the package has zero native build
- * requirements — works in Electron, Node, and browser contexts without
- * needing electron-rebuild. The SDK reads the same ai-hist SQLite database
- * that `ai-hist sync` writes (default
- * `~/.local/share/ai-hist/ai-history.db`, or `$AI_HIST_DB`).
- *
- * Trade-off vs better-sqlite3: sql.js loads the whole DB file into
- * memory. Fine for the ai-hist scale (tens of thousands of rows, MBs
- * of data); revisit if anyone hits millions.
+ * Every production operation crosses one mandatory Node-API boundary into the
+ * Rust engine. This module owns only input defaults, object normalization,
+ * pagination ergonomics, and stable JavaScript errors.
  */
-import initSqlJs from 'sql.js';
-import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
-import { writeFileSync } from 'node:fs';
-import { execFile } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-import { promisify } from 'node:util';
-import { scanLocalSources, LOCAL_SOURCE_PATHS } from './jsonl-sources.js';
-import { scanLocalTrajectories, trajectoryRootDescription, } from './trajectory-sources.js';
-import { catalogSessionFromJson, } from './session-catalog.js';
-export { SESSION_CATALOG_CONTRACT_VERSION, DiscoveryError, discoverSessions, } from './session-catalog.js';
-const execFileAsync = promisify(execFile);
-/** Resolve the SQLite path that ai-hist writes to. */
-export function defaultDbPath() {
-    const fromEnv = process.env.AI_HIST_DB;
-    if (fromEnv && fromEnv.trim().length > 0)
-        return fromEnv;
-    return join(homedir(), '.local', 'share', 'ai-hist', 'ai-history.db');
-}
-function defaultOpenCodeDbPath() {
-    return process.env.OPENCODE_DB && process.env.OPENCODE_DB.trim().length > 0
-        ? process.env.OPENCODE_DB
-        : join(homedir(), '.local', 'share', 'opencode', 'opencode.db');
-}
-let _sqlPromise = null;
-function getSqlJs() {
-    if (!_sqlPromise) {
-        _sqlPromise = initSqlJs();
+export const NATIVE_CONTRACT_VERSION = 2;
+export const SESSION_CATALOG_CONTRACT_VERSION = 1;
+export class RelayHistoryError extends Error {
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = new.target.name;
     }
-    return _sqlPromise;
 }
-/**
- * Every non-key column of the session catalog, in the order the native schema
- * declares them. Used both to create the table and to backfill it column by
- * column on a database snapshot written before the catalog existed.
- */
-const SESSION_CATALOG_COLUMNS = [
-    ['cwd', 'TEXT'],
-    ['git_branch', 'TEXT'],
-    ['first_activity_ms', 'INTEGER'],
-    ['last_activity_ms', 'INTEGER'],
-    ['last_assistant_text', 'TEXT'],
-    ['raw_path', 'TEXT'],
-    ['parser_version', 'INTEGER NOT NULL DEFAULT 1'],
-    ['first_prompt', 'TEXT'],
-    ['models_json', 'TEXT'],
-    ['originator', 'TEXT'],
-    ['agent_version', 'TEXT'],
-    ['repo_url', 'TEXT'],
-    ['initial_commit', 'TEXT'],
-    ['workspace_roots_json', 'TEXT'],
-    ['source_stamp', 'TEXT'],
-    ['discovery_state', 'TEXT'],
-];
-/** Run a statement whose only expected failure is "already there". */
-function tryRun(db, sql) {
-    try {
-        db.run(sql);
-    }
-    catch {
-        /* column/index already exists, or the table shape rules it out */
-    }
+export class UnsupportedPlatformError extends RelayHistoryError {
 }
-/**
- * Ensure the in-memory copy has the current `sessions` shape.
- *
- * The catalog columns (`first_prompt`, `models_json`, `discovery_state`, …)
- * were added after 0.5.0, so a database file written by an older CLI has the
- * old nine-column table. `CREATE TABLE IF NOT EXISTS` would leave that table
- * untouched and every catalog read would fail with `no such column`, so each
- * column is also added best-effort with `ALTER TABLE` — the same trick used for
- * `history.git_branch` in `openAiHist`. The writes land only in the in-memory
- * copy sql.js holds; the file on disk is untouched and the missing columns
- * simply read as `NULL`.
- */
-function ensureSessionsSchema(db) {
-    db.run(`CREATE TABLE IF NOT EXISTS sessions (
-    session_id TEXT NOT NULL,
-    source TEXT NOT NULL,
-    cwd TEXT,
-    git_branch TEXT,
-    first_activity_ms INTEGER,
-    last_activity_ms INTEGER,
-    last_assistant_text TEXT,
-    raw_path TEXT,
-    parser_version INTEGER NOT NULL DEFAULT 1,
-    first_prompt TEXT,
-    models_json TEXT,
-    originator TEXT,
-    agent_version TEXT,
-    repo_url TEXT,
-    initial_commit TEXT,
-    workspace_roots_json TEXT,
-    source_stamp TEXT,
-    discovery_state TEXT,
-    PRIMARY KEY (session_id, source)
-  )`);
-    for (const [name, decl] of SESSION_CATALOG_COLUMNS) {
-        tryRun(db, `ALTER TABLE sessions ADD COLUMN ${name} ${decl}`);
-    }
-    tryRun(db, 'CREATE INDEX IF NOT EXISTS idx_sessions_cwd ON sessions(cwd)');
-    tryRun(db, 'CREATE INDEX IF NOT EXISTS idx_sessions_branch ON sessions(git_branch)');
-    tryRun(db, 'CREATE INDEX IF NOT EXISTS idx_sessions_last ON sessions(last_activity_ms DESC)');
-    tryRun(db, 'CREATE INDEX IF NOT EXISTS idx_sessions_source_last ON sessions(source, last_activity_ms DESC)');
-    // The catalog's total order is (last_activity_ms DESC, source, session_id) —
-    // recency alone ties constantly, since one discovery pass can stamp many
-    // sessions with the same mtime-derived millisecond. These two carry the whole
-    // ORDER BY, so the listing is answered without a sort here as it is natively.
-    tryRun(db, 'CREATE INDEX IF NOT EXISTS idx_sessions_recency ON sessions(last_activity_ms DESC, source, session_id)');
-    tryRun(db, 'CREATE INDEX IF NOT EXISTS idx_sessions_source_recency ON sessions(source, last_activity_ms DESC, session_id)');
-    tryRun(db, 'CREATE INDEX IF NOT EXISTS idx_sessions_raw_path ON sessions(source, raw_path)');
+export class NativePackageMissingError extends RelayHistoryError {
 }
-/**
- * Mirror the discovery bookkeeping table.
- *
- * Shallow discovery records here that a given source was examined at a given
- * stamp and found not to be a session (a subagent sidecar, say), so a rescan
- * costs a primary-key lookup instead of a re-read. The SDK never reads it; the
- * table is created so an in-memory copy has the same shape as the file the
- * native tool writes.
- */
-function ensureDiscoverySkipsSchema(db) {
-    db.run(`CREATE TABLE IF NOT EXISTS discovery_skips (
-    source TEXT NOT NULL,
-    locator TEXT NOT NULL,
-    stamp TEXT NOT NULL,
-    reason TEXT,
-    updated_ms INTEGER,
-    PRIMARY KEY (source, locator)
-  )`);
+export class NativeLoadError extends RelayHistoryError {
 }
-function ensureTrajectorySchema(db) {
-    db.run(`CREATE TABLE IF NOT EXISTS trajectories (
-    id TEXT PRIMARY KEY,
-    version INTEGER,
-    persona_id TEXT,
-    project_id TEXT,
-    task_title TEXT,
-    task_description TEXT,
-    status TEXT,
-    started_at TEXT,
-    completed_at TEXT,
-    decisions_json TEXT NOT NULL,
-    retrospective_json TEXT NOT NULL,
-    search_text TEXT NOT NULL,
-    path TEXT,
-    updated_ms INTEGER NOT NULL,
-    timestamp_ms INTEGER NOT NULL
-  )`);
-    db.run('CREATE INDEX IF NOT EXISTS idx_trajectories_timestamp ON trajectories(timestamp_ms DESC)');
-    db.run('CREATE INDEX IF NOT EXISTS idx_trajectories_project ON trajectories(project_id)');
+export class NativeContractMismatchError extends RelayHistoryError {
 }
-function ensureTagSchema(db) {
-    db.run(`CREATE TABLE IF NOT EXISTS tags (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    name TEXT NOT NULL UNIQUE,
-    display_name TEXT NOT NULL,
-    color TEXT,
-    created_ms INTEGER NOT NULL,
-    updated_ms INTEGER NOT NULL
-  )`);
-    db.run(`CREATE TABLE IF NOT EXISTS session_tags (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    source TEXT NOT NULL,
-    session_id TEXT NOT NULL,
-    tag_id INTEGER NOT NULL REFERENCES tags(id) ON DELETE CASCADE,
-    created_ms INTEGER NOT NULL,
-    UNIQUE(source, session_id, tag_id)
-  )`);
-    db.run('CREATE INDEX IF NOT EXISTS idx_tags_name ON tags(name)');
-    db.run('CREATE INDEX IF NOT EXISTS idx_session_tags_session ON session_tags(source, session_id)');
-    db.run('CREATE INDEX IF NOT EXISTS idx_session_tags_tag ON session_tags(tag_id)');
+export class DatabaseOpenError extends RelayHistoryError {
 }
-/**
- * Open an `AiHist` reader. Async because sql.js initializes its WASM
- * runtime lazily and the DB file is read asynchronously so the host
- * process's event loop isn't blocked.
- *
- * Each call snapshots the data; to pick up later writes, call `reload()`
- * (or open a fresh instance).
- */
-export async function openAiHist(opts = {}) {
-    const dbPath = opts.dbPath ?? defaultDbPath();
-    const fallback = opts.fallback ?? 'jsonl';
-    const SQL = await getSqlJs();
-    // Fast path: SQLite written by `ai-hist sync`.
-    if (await pathExists(dbPath)) {
-        const fileBuffer = await readFile(dbPath);
-        const db = new SQL.Database(fileBuffer);
-        ensureTrajectorySchema(db);
-        ensureTagSchema(db);
-        ensureSessionsSchema(db);
-        ensureDiscoverySkipsSchema(db);
-        // Add git_branch to history if missing (pre-handoff DBs lack this column).
-        try {
-            db.run('ALTER TABLE history ADD COLUMN git_branch TEXT');
-        }
-        catch { /* already exists */ }
-        // Older database schemas don't contain `idx_history_session` or
-        // `idx_history_timestamp`. Without them, listSessions degrades to
-        // an O(sessions × rows) full table scan and freezes the WASM
-        // single-threaded JS engine for tens of seconds on real-sized DBs.
-        // The DB is opened read-only over a buffer, but sql.js still lets
-        // us run `CREATE INDEX` against the in-memory copy — the index
-        // lives only for this session's lifetime and is rebuilt each
-        // `openAiHist` call. Fast (~30ms on 35K rows).
-        db.run('CREATE INDEX IF NOT EXISTS idx_history_session ON history(session_id)');
-        db.run('CREATE INDEX IF NOT EXISTS idx_history_timestamp ON history(timestamp_ms DESC)');
-        return new AiHist(db, { kind: 'sqlite', path: dbPath }, { projectScope: opts.projectScope });
-    }
-    if (fallback === 'error') {
-        throw new Error(`ai-hist database not found at ${dbPath}. Run \`ai-hist sync\` first ` +
-            `(see https://github.com/AgentWorkforce/ai-hist).`);
-    }
-    // Fallback: scan local source files (Claude/Codex/Cursor/Grok) directly.
-    // Uses TypeScript implementations of the source parsers. Yields control to
-    // the event loop between sources so a
-    // large local history doesn't freeze the host.
-    const db = new SQL.Database();
-    db.run(`CREATE TABLE history (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    source TEXT NOT NULL,
-    session_id TEXT,
-    project TEXT,
-    prompt TEXT NOT NULL,
-    timestamp_ms INTEGER NOT NULL,
-    git_branch TEXT,
-    UNIQUE(source, timestamp_ms, prompt)
-  )`);
-    db.run('CREATE INDEX idx_history_timestamp ON history (timestamp_ms DESC)');
-    db.run('CREATE INDEX idx_history_session ON history (session_id)');
-    ensureTrajectorySchema(db);
-    ensureTagSchema(db);
-    ensureSessionsSchema(db);
-    ensureDiscoverySkipsSchema(db);
-    // scanLocalSources is async with yields between sources so the event
-    // loop stays responsive while we scan many MB of JSONL.
-    const rows = await scanLocalSources();
-    const openCodeRows = await scanOpenCode(SQL);
-    const trajectories = await scanLocalTrajectories();
-    const insert = db.prepare('INSERT OR IGNORE INTO history (source, session_id, project, prompt, timestamp_ms, git_branch) VALUES (?, ?, ?, ?, ?, ?)');
-    const insertTrajectory = db.prepare(`INSERT OR REPLACE INTO trajectories
-     (id, version, persona_id, project_id, task_title, task_description, status,
-      started_at, completed_at, decisions_json, retrospective_json, search_text,
-      path, updated_ms, timestamp_ms)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
-    try {
-        db.exec('BEGIN');
-        for (const row of rows) {
-            insert.run([row.source, row.sessionId, row.project, row.prompt, row.timestampMs, row.gitBranch]);
-        }
-        for (const row of openCodeRows) {
-            insert.run(['opencode', row.sessionId, row.project, row.prompt, row.timestampMs, null]);
-        }
-        for (const trajectory of trajectories) {
-            insertTrajectory.run([
-                trajectory.id,
-                trajectory.version,
-                trajectory.personaId,
-                trajectory.projectId,
-                trajectory.task.title,
-                trajectory.task.description,
-                trajectory.status,
-                trajectory.startedAt,
-                trajectory.completedAt,
-                JSON.stringify(trajectory.decisions),
-                JSON.stringify(trajectory.retrospective),
-                trajectory.searchText,
-                trajectory.path,
-                trajectory.updatedMs,
-                trajectory.timestampMs,
-            ]);
-            insert.run([
-                'trajectory',
-                trajectory.id,
-                trajectory.projectId,
-                trajectory.searchText,
-                trajectory.timestampMs,
-                null,
-            ]);
-        }
-        db.exec('COMMIT');
-    }
-    finally {
-        insert.free();
-        insertTrajectory.free();
-    }
-    const scannedPaths = `${LOCAL_SOURCE_PATHS.claude}, ${LOCAL_SOURCE_PATHS.codex}, ${LOCAL_SOURCE_PATHS.cursorRoot}, ${LOCAL_SOURCE_PATHS.grokSessionsRoot}, ${trajectoryRootDescription()}`;
-    return new AiHist(db, { kind: 'jsonl', path: scannedPaths }, { projectScope: opts.projectScope });
+export class InvalidArgumentError extends RelayHistoryError {
 }
-async function pathExists(p) {
-    try {
-        await stat(p);
-        return true;
-    }
-    catch {
-        return false;
-    }
+const SUPPORTED_PLATFORMS = new Set([
+    'darwin-arm64', 'darwin-x64',
+    'linux-arm64-gnu', 'linux-arm64-musl',
+    'linux-x64-gnu', 'linux-x64-musl',
+    'win32-x64-msvc',
+]);
+function linuxLibc() {
+    const report = process.report?.getReport();
+    return report?.header?.glibcVersionRuntime ? 'gnu' : 'musl';
 }
-async function readSqliteSnapshot(dbPath) {
-    const hasWal = await pathExists(`${dbPath}-wal`);
-    const hasShm = await pathExists(`${dbPath}-shm`);
-    if (!hasWal && !hasShm) {
-        return readFile(dbPath);
-    }
-    const dir = await mkdtemp(join(tmpdir(), 'ai-hist-sqlite-snapshot-'));
-    const snapshot = join(dir, 'snapshot.db');
-    try {
-        await execFileAsync('sqlite3', [dbPath, `.backup '${snapshot.replace(/'/g, "''")}'`], {
-            timeout: 30_000,
-            maxBuffer: 1024 * 1024,
-        });
-        return await readFile(snapshot);
-    }
-    finally {
-        await rm(dir, { recursive: true, force: true });
+export function runtimePlatform() {
+    if (process.platform === 'linux')
+        return `linux-${process.arch}-${linuxLibc()}`;
+    if (process.platform === 'win32')
+        return `win32-${process.arch}-msvc`;
+    return `${process.platform}-${process.arch}`;
+}
+let nativePromise = null;
+export function validateNativeContract(actual) {
+    if (actual !== NATIVE_CONTRACT_VERSION) {
+        throw new NativeContractMismatchError(`ai-hist requires native contract ${NATIVE_CONTRACT_VERSION}, but ai-hist-native provides ${actual}. Reinstall matching versions.`, 'NATIVE_CONTRACT_MISMATCH');
     }
 }
-async function scanOpenCode(SQL) {
-    const dbPath = defaultOpenCodeDbPath();
-    if (!(await pathExists(dbPath)))
-        return [];
-    try {
-        const fileBuffer = await readSqliteSnapshot(dbPath);
-        const db = new SQL.Database(fileBuffer);
+async function loadNative() {
+    if (nativePromise)
+        return nativePromise;
+    nativePromise = (async () => {
+        const platform = runtimePlatform();
+        if (!SUPPORTED_PLATFORMS.has(platform)) {
+            throw new UnsupportedPlatformError(`RelayHistory has no native build for ${platform}. Supported platforms: ${[...SUPPORTED_PLATFORMS].join(', ')}.`, 'UNSUPPORTED_PLATFORM');
+        }
+        let loaded;
         try {
-            const rows = runQuery(db, `SELECT s.id AS session_id, s.directory AS project, p.data,
-                COALESCE(p.time_created, m.time_created, s.time_created) AS timestamp_ms
-         FROM part p
-         JOIN message m ON m.id = p.message_id
-         JOIN session s ON s.id = p.session_id
-         WHERE json_extract(m.data, '$.role') = 'user'
-           AND json_extract(p.data, '$.type') = 'text'
-         ORDER BY p.time_created ASC`, []);
-            const scanned = [];
-            for (const row of rows) {
-                const data = parseJson(row.data, {});
-                const prompt = typeof data.text === 'string' ? data.text.trim() : '';
-                if (!prompt)
-                    continue;
-                scanned.push({
-                    sessionId: row.session_id,
-                    project: row.project,
-                    prompt,
-                    timestampMs: row.timestamp_ms ?? 0,
-                });
+            // Kept as a variable so TypeScript does not require native build-time
+            // declarations; npm installs this mandatory production dependency.
+            const packageName = 'ai-hist-native';
+            loaded = await import(packageName);
+        }
+        catch (cause) {
+            const error = cause;
+            if (error.code === 'ERR_MODULE_NOT_FOUND' || error.code === 'MODULE_NOT_FOUND') {
+                throw new NativePackageMissingError(`RelayHistory supports ${platform}, but its native package is missing. Reinstall ai-hist with optional dependencies enabled.`, 'NATIVE_PACKAGE_MISSING', { cause });
             }
-            return scanned;
+            throw new NativeLoadError(`RelayHistory's native package for ${platform} failed to load: ${error.message}`, 'NATIVE_LOAD_FAILED', { cause });
+        }
+        const binding = (loaded.default ?? loaded);
+        if (typeof binding.nativeContractVersion !== 'function') {
+            throw new NativeContractMismatchError('The installed ai-hist-native package does not expose a contract version. Reinstall matching ai-hist packages.', 'NATIVE_CONTRACT_MISMATCH');
+        }
+        validateNativeContract(binding.nativeContractVersion());
+        return binding;
+    })();
+    return nativePromise.catch((error) => {
+        nativePromise = null;
+        throw error;
+    });
+}
+function nativeMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const match = message.match(/RELAYHISTORY_NATIVE::([A-Z_]+)::([\s\S]*)/);
+    return match ? { code: match[1], message: match[2] } : null;
+}
+async function nativeCall(call) {
+    try {
+        return await call(await loadNative());
+    }
+    catch (error) {
+        if (error instanceof RelayHistoryError)
+            throw error;
+        const native = nativeMessage(error);
+        if (!native)
+            throw new NativeLoadError(String(error), 'NATIVE_CALL_FAILED', { cause: error });
+        if (native.code === 'DATABASE_OPEN_FAILED') {
+            throw new DatabaseOpenError(native.message, native.code, { cause: error });
         }
-        finally {
-            db.close();
+        if (native.code === 'INVALID_ARGUMENT') {
+            throw new InvalidArgumentError(native.message, native.code, { cause: error });
         }
-    }
-    catch {
-        return [];
+        throw new RelayHistoryError(native.message, native.code, { cause: error });
     }
 }
-function rowToEntry(row) {
-    return {
-        id: row.id,
-        source: row.source,
-        sessionId: row.session_id,
-        project: row.project,
-        prompt: row.prompt,
-        timestampMs: row.timestamp_ms,
-        gitBranch: row.git_branch ?? null,
-    };
-}
-function parseJson(raw, fallback) {
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        return fallback;
-    }
+function nullableString(value) {
+    return typeof value === 'string' ? value : null;
 }
-function rowToTrajectory(row) {
+function historyEntry(value) {
     return {
-        id: row.id,
-        version: row.version,
-        personaId: row.persona_id,
-        projectId: row.project_id,
-        task: {
-            title: row.task_title,
-            description: row.task_description,
-        },
-        status: row.status,
-        startedAt: row.started_at,
-        completedAt: row.completed_at,
-        decisions: parseJson(row.decisions_json, []),
-        retrospective: parseJson(row.retrospective_json, {
-            summary: null,
-            approach: null,
-            learnings: [],
-            confidence: null,
-        }),
-        searchText: row.search_text,
-        path: row.path,
-        updatedMs: row.updated_ms,
-        timestampMs: row.timestamp_ms,
+        id: Number(value.id),
+        source: String(value.source),
+        sessionId: nullableString(value.sessionId),
+        project: nullableString(value.project),
+        prompt: String(value.prompt),
+        timestampMs: Number(value.timestampMs),
     };
 }
-function normalizeProjectScope(project) {
-    const trimmed = project?.trim();
-    if (!trimmed)
-        return undefined;
-    return trimmed.replace(/[\\/]+$/, '') || trimmed;
-}
-function escapeLike(value) {
-    return value.replace(/\|/g, '||').replace(/%/g, '|%').replace(/_/g, '|_');
-}
-function scopedPathClause(column, project) {
-    const normalized = normalizeProjectScope(project) ?? project;
-    const escaped = escapeLike(normalized);
-    const slashChildPattern = normalized === '/' ? '/%' : `${escaped}/%`;
-    const backslashChildPattern = normalized === '\\' ? '\\%' : `${escaped}\\%`;
+function catalogCursor(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const row = value;
     return {
-        sql: `(${column} = ? OR ${column} LIKE ? ESCAPE '|' OR ${column} LIKE ? ESCAPE '|')`,
-        params: [normalized, slashChildPattern, backslashChildPattern],
+        lastActivityMs: typeof row.lastActivityMs === 'number' ? row.lastActivityMs : null,
+        source: String(row.source),
+        sessionId: String(row.sessionId),
     };
 }
-function scopedTrajectoryClause(project) {
-    const normalized = normalizeProjectScope(project) ?? project;
-    const pathScope = scopedPathClause('path', normalized);
+function catalogSession(value) {
     return {
-        sql: `(project_id = ? OR ${pathScope.sql})`,
-        params: [normalized, ...pathScope.params],
+        source: String(value.source),
+        sessionId: String(value.sessionId),
+        cwd: nullableString(value.cwd),
+        gitBranch: nullableString(value.gitBranch),
+        firstActivityMs: typeof value.firstActivityMs === 'number' ? value.firstActivityMs : null,
+        lastActivityMs: typeof value.lastActivityMs === 'number' ? value.lastActivityMs : null,
+        firstPrompt: nullableString(value.firstPrompt),
+        lastAssistantText: nullableString(value.lastAssistantText),
+        models: Array.isArray(value.models) ? value.models.map(String) : [],
+        originator: nullableString(value.originator),
+        agentVersion: nullableString(value.agentVersion),
+        repoUrl: nullableString(value.repoUrl),
+        initialCommit: nullableString(value.initialCommit),
+        workspaceRoots: Array.isArray(value.workspaceRoots) ? value.workspaceRoots.map(String) : [],
+        rawPath: nullableString(value.rawPath),
+        sourceStamp: nullableString(value.sourceStamp),
+        discoveryState: value.discoveryState === 'shallow' ? 'shallow' : 'full',
+        fromCache: value.fromCache === true,
     };
 }
-function appendProjectFilter(clauses, params, project, projectScope) {
-    if (projectScope) {
-        const scope = scopedPathClause('project', projectScope);
-        clauses.push(scope.sql);
-        params.push(...scope.params);
-    }
-    if (project) {
-        clauses.push('project = ?');
-        params.push(project);
-    }
-}
-function normalizeTagName(tag) {
-    return tag.trim().toLowerCase().replace(/\s+/g, ' ');
-}
-function appendTagFilter(clauses, params, tag, alias = 'history') {
-    const normalized = tag ? normalizeTagName(tag) : '';
-    if (!normalized)
-        return;
-    clauses.push(`EXISTS (
-      SELECT 1 FROM session_tags st
-      JOIN tags t ON t.id = st.tag_id
-      WHERE st.source = ${alias}.source
-        AND st.session_id = ${alias}.session_id
-        AND t.name = ?
-    )`);
-    params.push(normalized);
-}
-function buildFilters(opts, projectScope) {
-    const clauses = [];
-    const params = [];
-    if (opts.source) {
-        clauses.push('source = ?');
-        params.push(opts.source);
+function assertCatalogContract(value) {
+    if (value !== SESSION_CATALOG_CONTRACT_VERSION) {
+        throw new NativeContractMismatchError(`ai-hist expects catalog contract ${SESSION_CATALOG_CONTRACT_VERSION}, but native returned ${value}.`, 'CATALOG_CONTRACT_MISMATCH');
     }
-    appendProjectFilter(clauses, params, opts.project, projectScope);
-    appendTagFilter(clauses, params, opts.tag, 'history');
-    if (typeof opts.beforeMs === 'number') {
-        clauses.push('timestamp_ms < ?');
-        params.push(opts.beforeMs);
-    }
-    return {
-        sql: clauses.length > 0 ? ` AND ${clauses.join(' AND ')}` : '',
-        params,
-    };
 }
-function tableExists(db, name) {
-    return (runQuery(db, "SELECT COUNT(*) AS c FROM sqlite_master WHERE type = 'table' AND name = ?", [name])[0]?.c > 0);
-}
-function parseTokenJson(raw) {
-    if (!raw)
+function tokenUsage(raw) {
+    if (typeof raw !== 'string')
         return null;
     try {
         const parsed = JSON.parse(raw);
-        return typeof parsed === 'object' && parsed !== null ? parsed : null;
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
     }
     catch {
         return null;
     }
 }
-function runQuery(db, sql, params) {
-    const stmt = db.prepare(sql);
-    try {
-        stmt.bind(params);
-        const rows = [];
-        while (stmt.step()) {
-            rows.push(stmt.getAsObject());
-        }
-        return rows;
-    }
-    finally {
-        stmt.free();
-    }
+function sessionEvent(value) {
+    return {
+        id: Number(value.id), source: String(value.source), sessionId: String(value.sessionId),
+        project: nullableString(value.project), cwd: nullableString(value.cwd), gitBranch: nullableString(value.gitBranch),
+        messageId: nullableString(value.messageId), parentId: nullableString(value.parentId), tsMs: Number(value.tsMs),
+        role: String(value.role), kind: String(value.kind),
+        text: nullableString(value.text), model: nullableString(value.model), tokenUsage: tokenUsage(value.tokenJson),
+        eventUid: String(value.eventUid),
+    };
 }
-export class AiHist {
-    db;
-    _source;
-    _projectScope;
-    closed = false;
-    /** @internal — use `openAiHist(...)` to construct. */
-    constructor(db, source, opts = {}) {
-        this.db = db;
-        this._source = source;
-        this._projectScope = normalizeProjectScope(opts.projectScope);
-    }
-    /**
-     * Path the data came from. SQLite mode: the .db path. JSONL fallback
-     * mode: a comma-separated list of the scanned source paths.
-     */
-    get dbPath() {
-        return this._source.path;
-    }
-    /** Which data path was used: `'sqlite'` (on-disk SQLite database) or `'jsonl'` (fallback). */
-    get sourceKind() {
-        return this._source.kind;
-    }
-    /** Server/client-wide project scope applied to every read, if configured. */
-    get projectScope() {
-        return this._projectScope;
-    }
-    close() {
-        if (this.closed)
-            return;
-        this.db.close();
-        this.closed = true;
-    }
-    persistIfWritable() {
-        if (this._source.kind !== 'sqlite')
-            return;
-        writeFileSync(this._source.path, Buffer.from(this.db.export()));
-    }
-    ensureTag(name, color) {
-        const normalized = normalizeTagName(name);
-        if (!normalized)
-            throw new Error('tag name cannot be empty');
-        const displayName = name.trim();
-        const now = Date.now();
-        this.db.run(`INSERT INTO tags (name, display_name, color, created_ms, updated_ms)
-       VALUES (?, ?, ?, ?, ?)
-       ON CONFLICT(name) DO UPDATE SET
-         display_name = excluded.display_name,
-         color = COALESCE(excluded.color, tags.color),
-         updated_ms = excluded.updated_ms`, [normalized, displayName, color ?? null, now, now]);
-        return runQuery(this.db, 'SELECT id FROM tags WHERE name = ?', [normalized])[0].id;
-    }
-    matchingSessions(sessionId, source) {
-        const clauses = ['session_id = ?'];
-        const params = [sessionId];
-        if (source) {
-            clauses.push('source = ?');
-            params.push(source);
-        }
-        appendProjectFilter(clauses, params, undefined, this._projectScope);
-        return runQuery(this.db, `SELECT source, session_id, MIN(project) AS project, COUNT(*) AS entry_count,
-              MAX(timestamp_ms) AS last_activity_ms
-       FROM history
-       WHERE ${clauses.join(' AND ')}
-       GROUP BY source, session_id
-       ORDER BY source`, params).map((row) => ({
-            source: row.source,
-            sessionId: row.session_id,
-            project: row.project,
-            entryCount: row.entry_count,
-            lastActivityMs: row.last_activity_ms,
-        }));
-    }
-    tagSession(sessionId, tagName, opts = {}) {
-        const sessions = this.matchingSessions(sessionId, opts.source);
-        if (sessions.length === 0)
-            return [];
-        const tagId = this.ensureTag(tagName, opts.color);
-        const now = Date.now();
-        const insert = this.db.prepare('INSERT OR IGNORE INTO session_tags (source, session_id, tag_id, created_ms) VALUES (?, ?, ?, ?)');
-        try {
-            for (const session of sessions) {
-                insert.run([session.source, session.sessionId, tagId, now]);
-            }
-        }
-        finally {
-            insert.free();
-        }
-        this.persistIfWritable();
-        return sessions;
-    }
-    untagSession(sessionId, tagName, opts = {}) {
-        const normalized = normalizeTagName(tagName);
-        const sessions = this.matchingSessions(sessionId, opts.source);
-        let removed = 0;
-        for (const session of sessions) {
-            this.db.run(`DELETE FROM session_tags
-         WHERE source = ? AND session_id = ?
-           AND tag_id IN (SELECT id FROM tags WHERE name = ?)`, [session.source, session.sessionId, normalized]);
-            removed += this.db.getRowsModified();
-        }
-        this.persistIfWritable();
-        return removed;
-    }
-    listTags(opts = {}) {
-        const clauses = [];
-        const params = [];
-        if (opts.tag) {
-            clauses.push('t.name = ?');
-            params.push(normalizeTagName(opts.tag));
-        }
-        const where = clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '';
-        let scopedSessionSql = 'SELECT st.tag_id, st.id, st.created_ms FROM session_tags st';
-        const scopedSessionParams = [];
-        if (this._projectScope) {
-            const scope = scopedPathClause('h.project', this._projectScope);
-            scopedSessionSql = `SELECT st.tag_id, st.id, st.created_ms
-        FROM session_tags st
-        WHERE EXISTS (
-          SELECT 1 FROM history h
-          WHERE h.source = st.source
-            AND h.session_id = st.session_id
-            AND ${scope.sql}
-        )`;
-            scopedSessionParams.push(...scope.params);
-        }
-        return runQuery(this.db, `SELECT t.name, t.display_name, t.color, COUNT(st.id) AS session_count,
-              MIN(st.created_ms) AS first_tagged_ms, MAX(st.created_ms) AS last_tagged_ms
-       FROM tags t
-       LEFT JOIN (${scopedSessionSql}) st ON st.tag_id = t.id
-       ${where}
-       GROUP BY t.id, t.name, t.display_name, t.color
-       ORDER BY t.name`, [...scopedSessionParams, ...params]).map((row) => {
-            const tag = {
-                name: row.name,
-                displayName: row.display_name,
-                color: row.color,
-                sessionCount: row.session_count,
-                firstTaggedMs: row.first_tagged_ms,
-                lastTaggedMs: row.last_tagged_ms,
-            };
-            if (opts.includeSessions) {
-                tag.sessions = this.sessionsByTag(row.name);
-            }
-            return tag;
-        });
-    }
-    sessionsByTag(tagName) {
-        const clauses = ['t.name = ?'];
-        const params = [normalizeTagName(tagName)];
-        if (this._projectScope) {
-            const scope = scopedPathClause('h.project', this._projectScope);
-            clauses.push(scope.sql);
-            params.push(...scope.params);
-        }
-        return runQuery(this.db, `SELECT st.source, st.session_id, MIN(h.project) AS project, COUNT(h.id) AS entry_count,
-              MAX(h.timestamp_ms) AS last_activity_ms
-       FROM session_tags st
-       JOIN tags t ON t.id = st.tag_id
-       JOIN history h ON h.source = st.source AND h.session_id = st.session_id
-       WHERE ${clauses.join(' AND ')}
-       GROUP BY st.source, st.session_id
-       ORDER BY MAX(h.timestamp_ms) DESC`, params).map((row) => ({
-            source: row.source,
-            sessionId: row.session_id,
-            project: row.project,
-            entryCount: row.entry_count,
-            lastActivityMs: row.last_activity_ms,
-        }));
-    }
-    searchByTag(tagName, opts = {}) {
-        return this.recent({ ...opts, tag: tagName });
-    }
-    /** Most recent prompts, newest first. */
-    recent(opts = {}) {
-        const limit = opts.limit ?? 50;
-        const { sql, params } = buildFilters(opts, this._projectScope);
-        return runQuery(this.db, `SELECT id, source, session_id, project, prompt, timestamp_ms, git_branch
-       FROM history
-       WHERE 1=1${sql}
-       ORDER BY timestamp_ms DESC
-       LIMIT ?`, [...params, limit]).map(rowToEntry);
-    }
-    /**
-     * Group history into sessions, ordered by last activity (newest first).
-     * Sessions without a `session_id` are skipped.
-     *
-     * This derives sessions from the `history` table, so it only ever sees
-     * sessions a full `ai-hist sync` has ingested, and it pays a window-function
-     * pass over history to do it. For the fast and complete path — every session
-     * the catalog knows, including ones only shallow discovery has seen, with
-     * cwd, branch, models, originator and repo identity attached — use
-     * {@link AiHist.listSessionCatalog}. This method stays as-is for callers
-     * that want prompt counts and the project-derived grouping.
-     *
-     * Implementation note: this used to use a correlated scalar subquery
-     * to pick `first_prompt`, which ran in O(sessions × rows) — ~19s on a
-     * 35K-row DB. Switched to `ROW_NUMBER() OVER (PARTITION BY session_id
-     * ORDER BY timestamp_ms)` so first-prompt picking is a single pass
-     * over the table (~300ms on the same DB). Plus the index ensure step
-     * in `openAiHist` keeps it fast even when the DB was written by an
-     * older CLI that didn't create `idx_history_session`.
-     */
-    listSessions(opts = {}) {
-        const limit = opts.limit ?? 50;
-        const { sql, params } = buildFilters(opts, this._projectScope);
-        const rows = runQuery(this.db, `WITH filtered AS (
-        SELECT id, source, session_id, project, prompt, timestamp_ms
-        FROM history
-        WHERE session_id IS NOT NULL AND session_id != ''${sql}
-      ),
-      ranked AS (
-        SELECT
-          session_id,
-          source,
-          project,
-          prompt,
-          timestamp_ms,
-          ROW_NUMBER() OVER (
-            PARTITION BY session_id, source, project
-            ORDER BY timestamp_ms ASC, id ASC
-          ) AS rn_first,
-          COUNT(*) OVER (PARTITION BY session_id, source, project) AS prompt_count,
-          MIN(timestamp_ms) OVER (PARTITION BY session_id, source, project) AS first_activity_ms,
-          MAX(timestamp_ms) OVER (PARTITION BY session_id, source, project) AS last_activity_ms
-        FROM filtered
-      )
-      SELECT
-        session_id,
-        source,
-        project,
-        prompt AS first_prompt,
-        first_activity_ms,
-        last_activity_ms,
-        prompt_count
-      FROM ranked
-      WHERE rn_first = 1
-      ORDER BY last_activity_ms DESC
-      LIMIT ?`, [...params, limit]);
-        return rows.map((row) => ({
-            sessionId: row.session_id,
-            source: row.source,
-            project: row.project,
-            firstPrompt: row.first_prompt,
-            lastActivityMs: row.last_activity_ms,
-            firstActivityMs: row.first_activity_ms,
-            promptCount: row.prompt_count,
-        }));
-    }
-    /**
-     * The session catalog, newest first — one indexed query over `sessions` and
-     * nothing else.
-     *
-     * No provider transcript is opened and neither `history` nor
-     * `session_events` is touched, so this stays fast on first paint even with
-     * thousands of historical sessions. It is the read side of the native
-     * `ai-hist sessions list`; populate the catalog with `discoverSessions()`
-     * (or a full `ai-hist sync`).
-     *
-     * Details worth knowing:
-     *   - `trajectory` rows are excluded defensively — trajectories are derived
-     *     records, not sessions, and must never appear in a session list.
-     *   - The catalog's total order is
-     *     `(last_activity_ms DESC, source ASC, session_id ASC)`. SQLite sorts
-     *     NULL lowest, so rows of unknown recency land last under `DESC` without
-     *     a helper expression. Recency alone is not a key: one discovery pass can
-     *     stamp many sessions with the same mtime-derived millisecond, which is
-     *     why the identity columns are part of the order.
-     *   - To page, use {@link AiHist.listSessionCatalogPage} and follow its
-     *     `nextCursor`. `beforeMs` is only a *coarse* cutoff ("anything before
-     *     last Tuesday"): it cannot separate rows sharing a millisecond, so a
-     *     walk built on it drops every row tied with a page boundary. It is
-     *     ignored when `after` is set.
-     *   - A configured `projectScope` constrains rows by `cwd`, like
-     *     `getHandoff`. Sources with no working directory (relay) therefore drop
-     *     out of a scoped listing.
-     *   - In JSONL fallback mode (no SQLite database) the catalog is empty and
-     *     this returns `[]`: the fallback scan builds `history` rows only, and
-     *     only the native discovery engine writes the catalog.
-     */
-    listSessionCatalog(opts = {}) {
-        if (!tableExists(this.db, 'sessions'))
-            return [];
-        // SQLite reads a negative LIMIT as "unlimited", so a negative cap would
-        // quietly dump the whole catalog. The native CLI rejects it; so do we.
-        if (typeof opts.limit === 'number' && opts.limit < 0) {
-            throw new RangeError(`limit must not be negative (got ${opts.limit})`);
-        }
-        const limit = opts.limit ?? 50;
-        const clauses = ["source != 'trajectory'"];
-        const params = [];
-        const sources = [...(opts.sources ?? [])].map((source) => String(source));
-        if (sources.length > 0) {
-            clauses.push(`source IN (${sources.map(() => '?').join(', ')})`);
-            params.push(...sources);
-        }
-        if (opts.after) {
-            // Everything strictly after the cursor in the catalog's total order.
-            // Undated rows sort last, so a dated cursor must still reach them.
-            const { lastActivityMs, source, sessionId } = opts.after;
-            // A timestamp alone is not a cursor: without the identity columns the
-            // predicate cannot separate rows sharing a millisecond, and silently
-            // dropping the cursor would restart the walk at page one. The native CLI
-            // rejects the same half-cursor; so does this, rather than looping.
-            if (typeof source !== 'string' || source.length === 0 || typeof sessionId !== 'string' || sessionId.length === 0) {
-                throw new TypeError('after must carry both source and sessionId — pass the whole nextCursor object from the previous page');
-            }
-            if (typeof lastActivityMs === 'number') {
-                clauses.push(`(last_activity_ms IS NULL OR last_activity_ms < ?
-             OR (last_activity_ms = ?
-                 AND (source > ? OR (source = ? AND session_id > ?))))`);
-                params.push(lastActivityMs, lastActivityMs, source, source, sessionId);
-            }
-            else {
-                clauses.push(`last_activity_ms IS NULL AND (source > ? OR (source = ? AND session_id > ?))`);
-                params.push(source, source, sessionId);
-            }
-        }
-        else if (typeof opts.beforeMs === 'number') {
-            clauses.push('last_activity_ms < ?');
-            params.push(opts.beforeMs);
-        }
-        if (this._projectScope) {
-            const scope = scopedPathClause('cwd', this._projectScope);
-            clauses.push(scope.sql);
-            params.push(...scope.params);
-        }
-        return runQuery(this.db, `SELECT source, session_id, cwd, git_branch, first_activity_ms, last_activity_ms,
-              first_prompt, last_assistant_text, models_json, originator, agent_version,
-              repo_url, initial_commit, workspace_roots_json, raw_path, source_stamp,
-              discovery_state, parser_version
-       FROM sessions
-       WHERE ${clauses.join(' AND ')}
-       ORDER BY last_activity_ms DESC, source ASC, session_id ASC
-       LIMIT ?`, [...params, limit]).map((row) => catalogSessionFromJson({ ...row, from_cache: true }));
-    }
-    /**
-     * {@link AiHist.listSessionCatalog} plus the cursor that continues it.
-     *
-     * Follow `nextCursor` until it comes back `null` to walk the whole catalog:
-     * no skipped and no duplicated rows, even when a whole page shares one
-     * millisecond, and the undated tail stays reachable from a dated cursor.
-     * `nextCursor` is non-null only when the page filled its limit, mirroring
-     * the native `list_session_catalog_page` and the CLI's `next_cursor`.
-     */
-    listSessionCatalogPage(opts = {}) {
-        const sessions = this.listSessionCatalog(opts);
-        const limit = opts.limit ?? 50;
-        const last = sessions[sessions.length - 1];
-        const nextCursor = limit > 0 && sessions.length >= limit && last
-            ? { lastActivityMs: last.lastActivityMs, source: last.source, sessionId: last.sessionId }
-            : null;
-        return { sessions, nextCursor };
-    }
-    /** All prompts in a session, ordered oldest → newest. */
-    getSession(sessionId, opts = {}) {
-        const clauses = ['session_id = ?'];
-        const params = [sessionId];
-        if (opts.source) {
-            clauses.push('source = ?');
-            params.push(opts.source);
-        }
-        appendProjectFilter(clauses, params, undefined, this._projectScope);
-        appendTagFilter(clauses, params, opts.tag, 'history');
-        return runQuery(this.db, `SELECT id, source, session_id, project, prompt, timestamp_ms, git_branch
-       FROM history
-       WHERE ${clauses.join(' AND ')}
-       ORDER BY timestamp_ms ASC`, params).map(rowToEntry);
-    }
-    /**
-     * All normalized events for a session, oldest first — messages, thinking,
-     * tool calls, and tool results with per-event token usage where the
-     * transcript provides it. Returns `[]` when the database predates the
-     * `session_events` table (or in JSONL fallback mode, which has no events).
-     *
-     * Size caveat: this SDK loads the whole database file into memory, so on
-     * large event-bearing databases prefer streaming from the native CLI
-     * (`ai-hist events <session-id> --json`).
-     */
-    getSessionEvents(sessionId, opts = {}) {
-        if (!tableExists(this.db, 'session_events'))
-            return [];
-        const clauses = ['session_id = ?'];
-        const params = [sessionId];
-        if (opts.source) {
-            clauses.push('source = ?');
-            params.push(opts.source);
-        }
-        appendProjectFilter(clauses, params, undefined, this._projectScope);
-        return runQuery(this.db, `SELECT id, source, session_id, project, cwd, git_branch, message_id, parent_id,
-              ts_ms, role, kind, text, model, token_json, event_uid
-       FROM session_events
-       WHERE ${clauses.join(' AND ')}
-       ORDER BY ts_ms IS NULL, ts_ms ASC, id ASC`, params).map((row) => ({
-            id: row.id,
-            source: row.source,
-            sessionId: row.session_id,
-            project: row.project,
-            cwd: row.cwd,
-            gitBranch: row.git_branch,
-            messageId: row.message_id,
-            parentId: row.parent_id,
-            tsMs: row.ts_ms,
-            role: row.role,
-            kind: row.kind,
-            text: row.text,
-            model: row.model,
-            tokenUsage: parseTokenJson(row.token_json),
-            eventUid: row.event_uid,
-        }));
-    }
-    /** All tool calls for a session, oldest first; `[]` on pre-events databases. */
-    getToolCalls(sessionId, opts = {}) {
-        if (!tableExists(this.db, 'tool_calls'))
-            return [];
-        const clauses = ['session_id = ?'];
-        const params = [sessionId];
-        if (opts.source) {
-            clauses.push('source = ?');
-            params.push(opts.source);
-        }
-        // tool_calls has no project column; the configured scope constrains
-        // through the session's events. Without that table the scoped answer is
-        // unknowable — fail closed rather than throw.
-        if (this._projectScope) {
-            if (!tableExists(this.db, 'session_events'))
-                return [];
-            const scope = scopedPathClause('e.project', this._projectScope);
-            clauses.push(`EXISTS (SELECT 1 FROM session_events e
-                 WHERE e.source = tool_calls.source AND e.session_id = tool_calls.session_id
-                   AND ${scope.sql})`);
-            params.push(...scope.params);
-        }
-        return runQuery(this.db, `SELECT id, source, session_id, message_id, tool_use_id, name, target, args_json, is_error, ts_ms
-       FROM tool_calls
-       WHERE ${clauses.join(' AND ')}
-       ORDER BY ts_ms IS NULL, ts_ms ASC, id ASC`, params).map((row) => ({
-            id: row.id,
-            source: row.source,
-            sessionId: row.session_id,
-            messageId: row.message_id,
-            toolUseId: row.tool_use_id,
-            name: row.name,
-            target: row.target,
-            argsJson: row.args_json,
-            isError: row.is_error === null ? null : row.is_error !== 0,
-            tsMs: row.ts_ms,
-        }));
-    }
-    /**
-     * Substring search across prompt + project, case-insensitive, recent
-     * matches first. The native CLI uses FTS5; this SDK uses LIKE because
-     * sql.js's default WASM build doesn't ship the FTS5 module. Plenty fast
-     * for the ai-hist scale (~tens of thousands of rows); revisit if a
-     * future consumer needs phrase/boolean queries.
-     *
-     * The query is matched literally — `%` and `_` are escaped so users can
-     * search for them. Empty queries return recent entries matching the filters.
-     */
-    search(query, opts = {}) {
-        const trimmed = query.trim();
-        const limit = opts.limit ?? 50;
-        const clauses = [];
-        const params = [];
-        if (trimmed) {
-            const escaped = trimmed.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_');
-            const pattern = `%${escaped}%`;
-            clauses.push(`(LOWER(prompt) LIKE LOWER(?) ESCAPE '\\' OR LOWER(COALESCE(project, '')) LIKE LOWER(?) ESCAPE '\\')`);
-            params.push(pattern, pattern);
-        }
-        if (opts.source) {
-            clauses.push('source = ?');
-            params.push(opts.source);
-        }
-        appendProjectFilter(clauses, params, opts.project, this._projectScope);
-        appendTagFilter(clauses, params, opts.tag, 'history');
-        if (typeof opts.beforeMs === 'number') {
-            clauses.push('timestamp_ms < ?');
-            params.push(opts.beforeMs);
-        }
-        return runQuery(this.db, `SELECT id, source, session_id, project, prompt, timestamp_ms, git_branch
-       FROM history
-       WHERE ${clauses.length > 0 ? clauses.join(' AND ') : '1=1'}
-       ORDER BY timestamp_ms DESC
-       LIMIT ?`, [...params, limit]).map(rowToEntry);
-    }
-    /** Search compacted per-run trajectory WHY: decisions and retrospectives. */
-    searchTrajectories(query, opts = {}) {
-        const trimmed = query.trim();
-        if (!trimmed)
-            return [];
-        const limit = opts.limit ?? 20;
-        const escaped = trimmed.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_');
-        const pattern = `%${escaped}%`;
-        const clauses = [
-            `(LOWER(search_text) LIKE LOWER(?) ESCAPE '\\'
-          OR LOWER(COALESCE(task_title, '')) LIKE LOWER(?) ESCAPE '\\'
-          OR LOWER(COALESCE(task_description, '')) LIKE LOWER(?) ESCAPE '\\'
-          OR LOWER(COALESCE(persona_id, '')) LIKE LOWER(?) ESCAPE '\\'
-          OR LOWER(COALESCE(project_id, '')) LIKE LOWER(?) ESCAPE '\\')`,
-        ];
-        const params = [pattern, pattern, pattern, pattern, pattern];
-        for (const project of [this._projectScope, opts.project]) {
-            if (!project)
-                continue;
-            const scope = scopedTrajectoryClause(project);
-            clauses.push(scope.sql);
-            params.push(...scope.params);
-        }
-        return runQuery(this.db, `SELECT id, version, persona_id, project_id, task_title, task_description, status,
-              started_at, completed_at, decisions_json, retrospective_json, search_text,
-              path, updated_ms, timestamp_ms
-       FROM trajectories
-       WHERE ${clauses.join(' AND ')}
-       ORDER BY timestamp_ms DESC
-       LIMIT ?`, [...params, limit]).map(rowToTrajectory);
-    }
-    /** Best-matching per-run trajectory for a task query, or `null` if none match. */
-    whyForTask(query) {
-        return this.searchTrajectories(query, { limit: 1 })[0] ?? null;
-    }
-    /** Single entry by id, or `null` if not found. */
-    getEntry(id) {
-        const clauses = ['id = ?'];
-        const params = [id];
-        appendProjectFilter(clauses, params, undefined, this._projectScope);
-        const rows = runQuery(this.db, `SELECT id, source, session_id, project, prompt, timestamp_ms, git_branch
-       FROM history WHERE ${clauses.join(' AND ')}`, params);
-        return rows.length > 0 ? rowToEntry(rows[0]) : null;
-    }
-    /**
-     * All entries whose timestamp falls within [timestampMs - windowMs,
-     * timestampMs + windowMs], ordered oldest first. Used by get_context.
-     */
-    getInTimeWindow(timestampMs, windowMs) {
-        const clauses = ['timestamp_ms BETWEEN ? AND ?'];
-        const params = [timestampMs - windowMs, timestampMs + windowMs];
-        appendProjectFilter(clauses, params, undefined, this._projectScope);
-        return runQuery(this.db, `SELECT id, source, session_id, project, prompt, timestamp_ms, git_branch
-       FROM history
-       WHERE ${clauses.join(' AND ')}
-       ORDER BY timestamp_ms ASC`, params).map(rowToEntry);
-    }
-    /**
-     * Find sessions matching the given repo/branch/source and return ranked
-     * handoff candidates with a warm-start command for the target CLI.
-     *
-     * Queries the `sessions` table (populated by `ai-hist sync`) for objective
-     * metadata, then joins the last N user prompts from `history` to generate
-     * a brief on demand — no pre-computed summaries.
-     */
-    getHandoff(opts = {}) {
-        const limit = opts.limit ?? 3;
-        const clauses = [];
-        const params = [];
-        if (this._projectScope) {
-            const escaped = this._projectScope.replace(/\|/g, '||').replace(/%/g, '|%').replace(/_/g, '|_');
-            clauses.push("cwd LIKE ? ESCAPE '|'");
-            params.push(`${escaped}%`);
-        }
-        if (opts.source) {
-            clauses.push('source = ?');
-            params.push(opts.source);
-        }
-        if (opts.repo) {
-            const escaped = opts.repo.replace(/\|/g, '||').replace(/%/g, '|%').replace(/_/g, '|_');
-            clauses.push("cwd LIKE ? ESCAPE '|'");
-            params.push(`%${escaped}%`);
-        }
-        if (opts.branch) {
-            const escaped = opts.branch.replace(/\|/g, '||').replace(/%/g, '|%').replace(/_/g, '|_');
-            clauses.push("git_branch LIKE ? ESCAPE '|'");
-            params.push(`%${escaped}%`);
-        }
-        const where = clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '';
-        // Over-fetch sessions because many (old or sub-agent) sessions have no
-        // matching `history` prompts and get skipped below. Fetching exactly
-        // `limit` could starve the result to empty even when good candidates exist
-        // just past the cutoff. We stop scanning once we've collected `limit`.
-        const fetchCount = Math.min(Math.max(limit * 5, limit), 100);
-        const sessionRows = runQuery(this.db, `SELECT session_id, source, cwd, git_branch, first_activity_ms, last_activity_ms,
-              last_assistant_text, raw_path
-       FROM sessions
-       ${where}
-       ORDER BY last_activity_ms DESC
-       LIMIT ?`, [...params, fetchCount]);
-        const candidates = [];
-        for (const session of sessionRows) {
-            if (candidates.length >= limit)
-                break;
-            // Filter by both session_id AND source to prevent cross-source prompt mixing
-            // when two CLIs happen to use the same session ID (rare but possible).
-            const prompts = runQuery(this.db, `SELECT id, source, session_id, project, prompt, timestamp_ms, git_branch
-         FROM history
-         WHERE session_id = ? AND source = ?
-         ORDER BY timestamp_ms ASC`, [session.session_id, session.source]).map(rowToEntry);
-            if (prompts.length === 0)
-                continue;
-            const filesTouched = extractFilePaths(prompts.map((p) => p.prompt).join('\n'));
-            // The first prompt is often injected boilerplate (system-reminder /
-            // command wrappers), especially for relay-driven sessions. Prefer the
-            // first prompt that looks like a real user instruction for the goal.
-            const goalPrompt = prompts.find((p) => !isBoilerplatePrompt(p.prompt)) ?? prompts[0];
-            const goal = goalPrompt.prompt.slice(0, 300).replace(/\n/g, ' ');
-            const lastState = prompts[prompts.length - 1].prompt.slice(0, 300).replace(/\n/g, ' ');
-            const resume = resumeCommand({
-                source: session.source,
-                sessionId: session.session_id,
-                project: session.cwd,
-            });
-            const targetSource = session.source === 'claude' ? 'codex' : 'claude';
-            const warmStart = buildWarmStartCommand(targetSource, goal, filesTouched, lastState, session.last_assistant_text ?? null, session.cwd);
-            let confidence = Math.min(0.6, 0.2 + prompts.length * 0.02);
-            if (opts.branch && session.git_branch?.includes(opts.branch))
-                confidence += 0.25;
-            if (opts.repo && session.cwd?.includes(opts.repo))
-                confidence += 0.15;
-            confidence = Math.min(1.0, confidence);
-            candidates.push({
-                sessionId: session.session_id,
-                source: session.source,
-                cwd: session.cwd,
-                gitBranch: session.git_branch,
-                firstActivityMs: session.first_activity_ms,
-                lastActivityMs: session.last_activity_ms,
-                promptCount: prompts.length,
-                goal,
-                lastState,
-                lastAssistantText: session.last_assistant_text ?? null,
-                filesTouched,
-                resumeCommand: resume,
-                warmStartCommand: warmStart,
-                confidence,
-            });
-        }
-        return candidates.sort((a, b) => b.confidence - a.confidence);
-    }
-    /** Counts + date range, mirroring `ai-hist stats`. */
-    stats() {
-        const scopeClauses = [];
-        const scopeParams = [];
-        appendProjectFilter(scopeClauses, scopeParams, undefined, this._projectScope);
-        const where = scopeClauses.length > 0 ? ` WHERE ${scopeClauses.join(' AND ')}` : '';
-        const andScope = scopeClauses.length > 0 ? ` AND ${scopeClauses.join(' AND ')}` : '';
-        const total = runQuery(this.db, `SELECT COUNT(*) AS c FROM history${where}`, scopeParams)[0]?.c ?? 0;
-        const bySourceRows = runQuery(this.db, `SELECT source, COUNT(*) AS c FROM history${where} GROUP BY source`, scopeParams);
-        const bySource = {};
-        for (const row of bySourceRows) {
-            bySource[row.source] = row.c;
-        }
-        const byProject = runQuery(this.db, `SELECT project, COUNT(*) AS c FROM history
-       WHERE project IS NOT NULL AND project != ''${andScope}
-       GROUP BY project ORDER BY c DESC LIMIT 10`, scopeParams).map((row) => ({ project: row.project, count: row.c }));
-        const range = runQuery(this.db, `SELECT MIN(timestamp_ms) AS mn, MAX(timestamp_ms) AS mx FROM history${where}`, scopeParams)[0];
-        return {
-            total,
-            bySource,
-            byProject,
-            firstTimestampMs: range?.mn ?? null,
-            lastTimestampMs: range?.mx ?? null,
-        };
+export function defaultDbPath() {
+    if (process.env.AI_HIST_DB !== undefined)
+        return process.env.AI_HIST_DB;
+    if (process.env.XDG_DATA_HOME !== undefined) {
+        return join(process.env.XDG_DATA_HOME, 'ai-hist', 'ai-history.db');
     }
+    return join(homedir(), '.local', 'share', 'ai-hist', 'ai-history.db');
 }
 /**
- * Heuristic: does a prompt look like injected boilerplate rather than a real
- * user instruction? Relay/agent sessions often open with a system-reminder or
- * command wrapper that makes a poor "goal" summary.
+ * Optimization profile of the loaded native addon: 'release', 'debug', or
+ * 'unknown' for an addon predating the probe. Performance measurements are
+ * only meaningful against 'release'.
  */
-function isBoilerplatePrompt(prompt) {
-    const t = prompt.trimStart();
-    return (t.startsWith('<system-reminder') ||
-        t.startsWith('<command-') ||
-        t.startsWith('Caveat:') ||
-        t.startsWith('[Request interrupted'));
+export async function nativeBuildProfile() {
+    return nativeCall(async (native) => native.nativeBuildProfile?.() ?? 'unknown');
 }
-/**
- * Extract file paths with recognizable extensions from a block of text.
- * Heuristic — used to populate filesTouched in HandoffCandidate.
- */
-function extractFilePaths(text) {
-    const exts = 'ts|tsx|js|jsx|mjs|cjs|py|go|rs|rb|java|cs|cpp|cc|c|h|json|yaml|yml|toml|md|sh|sql|css|scss|html|svelte|vue';
-    const regex = new RegExp(`(?:^|[\\s,\`'"(])([~./][\\w./-]*\\.(?:${exts})|-?[\\w/-]+\\.(?:${exts}))\\b`, 'gm');
-    const seen = new Set();
-    let m;
-    while ((m = regex.exec(text)) !== null) {
-        const p = m[1].trim();
-        if (p.length > 2 && p.length < 200)
-            seen.add(p);
-    }
-    return Array.from(seen).slice(0, 20);
+export async function search(query, options = {}) {
+    return nativeCall(async (native) => (await native.search(query, options)).map(historyEntry));
 }
-/**
- * Build a warm-start command for the target CLI, injecting context from a
- * prior session so the new agent can pick up mid-task.
- */
-function buildWarmStartCommand(targetSource, goal, files, lastState, lastAssistant, cwd) {
-    const filesLine = files.length > 0 ? ` Files touched: ${files.slice(0, 10).join(', ')}.` : '';
-    const assistantLine = lastAssistant
-        ? ` Last assistant state: ${lastAssistant.replace(/\n/g, ' ').slice(0, 200)}`
-        : '';
-    const context = `Picking up from previous session. Goal: ${goal}.${filesLine} Last user prompt: ${lastState}.${assistantLine}`;
-    const cdPart = cwd ? `cd ${shellQuote(cwd)} && ` : '';
-    return `${cdPart}${targetSource} ${shellQuote(context)}`;
+export async function recent(options = {}) {
+    return nativeCall(async (native) => (await native.recent(options)).map(historyEntry));
+}
+export async function getSession(sessionId, options = {}) {
+    return nativeCall(async (native) => (await native.getSession(sessionId, options)).map(historyEntry));
+}
+export async function listSessionCatalog(options = {}) {
+    return (await listSessionCatalogPage(options)).sessions;
+}
+export async function listSessionCatalogPage(options = {}) {
+    return nativeCall(async (native) => {
+        const page = await native.listSessionCatalogPage({ ...options, after: options.after ? {
+                ...options.after,
+                lastActivityMs: options.after.lastActivityMs ?? undefined,
+            } : undefined });
+        const contractVersion = Number(page.contractVersion);
+        assertCatalogContract(contractVersion);
+        return {
+            contractVersion,
+            sessions: Array.isArray(page.sessions) ? page.sessions.map(catalogSession) : [],
+            nextCursor: catalogCursor(page.nextCursor),
+        };
+    });
+}
+export async function discoverSessions(options = {}) {
+    return nativeCall(async (native) => {
+        const result = await native.discoverSessions(options);
+        const contractVersion = Number(result.contractVersion);
+        assertCatalogContract(contractVersion);
+        return {
+            contractVersion,
+            sessions: Array.isArray(result.sessions) ? result.sessions.map(catalogSession) : [],
+            discovered: Number(result.discovered),
+            skippedUnchanged: Number(result.skippedUnchanged),
+            providers: result.providers ?? [],
+            exemptSources: result.exemptSources ?? [],
+            diagnostics: Array.isArray(result.diagnostics) ? result.diagnostics.map((item) => ({
+                source: String(item.source), locator: nullableString(item.locator), error: String(item.error),
+            })) : [],
+            counters: result.counters,
+        };
+    });
+}
+export async function discoverAndList(options = {}) {
+    await discoverSessions(options);
+    return listSessionCatalogPage(options);
+}
+export async function getSessionEventsPage(sessionId, options = {}) {
+    return nativeCall(async (native) => {
+        const page = await native.getSessionEventsPage(sessionId, options);
+        return {
+            events: Array.isArray(page.events) ? page.events.map(sessionEvent) : [],
+            nextCursor: page.nextCursor && typeof page.nextCursor === 'object'
+                ? { tsMs: Number(page.nextCursor.tsMs), id: Number(page.nextCursor.id) }
+                : null,
+        };
+    });
+}
+export async function* sessionEvents(sessionId, options = {}) {
+    let after;
+    do {
+        const page = await getSessionEventsPage(sessionId, { ...options, after });
+        for (const event of page.events)
+            yield event;
+        after = page.nextCursor ?? undefined;
+    } while (after);
+}
+export async function getSessionEvents(sessionId, options = {}) {
+    const events = [];
+    for await (const event of sessionEvents(sessionId, options))
+        events.push(event);
+    return events;
+}
+export async function stats(options = {}) {
+    return nativeCall(async (native) => {
+        const result = await native.stats(options);
+        const bySource = {};
+        for (const item of result.bySource ?? []) {
+            bySource[String(item.source)] = Number(item.count);
+        }
+        return {
+            total: Number(result.total), bySource,
+            byProject: (result.byProject ?? []).map((item) => ({ project: String(item.project), count: Number(item.count) })),
+            firstTimestampMs: typeof result.firstTimestampMs === 'number' ? result.firstTimestampMs : null,
+            lastTimestampMs: typeof result.lastTimestampMs === 'number' ? result.lastTimestampMs : null,
+        };
+    });
+}
+export async function sync(options = {}) {
+    return nativeCall(async (native) => {
+        const result = await native.sync(options);
+        return { databasePath: String(result.databasePath), completed: result.completed === true };
+    });
 }
-/**
- * Resume command for an entry/session, matching what `ai-hist show` prints.
- * Returns `null` for sources that don't have a resume affordance (relay).
- */
 export function resumeCommand(entry) {
     if (!entry.sessionId)
         return null;
-    switch (entry.source) {
-        case 'claude':
-            return entry.project
-                ? `cd ${shellQuote(entry.project)} && claude --resume ${shellQuote(entry.sessionId)}`
-                : `claude --resume ${shellQuote(entry.sessionId)}`;
-        case 'codex':
+    const resume = (() => {
+        if (entry.source === 'claude')
+            return `claude --resume ${shellQuote(entry.sessionId)}`;
+        if (entry.source === 'codex')
             return `codex resume ${shellQuote(entry.sessionId)}`;
-        case 'cursor':
-            return entry.project
-                ? `cd ${shellQuote(entry.project)} && cursor-agent --resume=${shellQuote(entry.sessionId)}`
-                : `cursor-agent --resume=${shellQuote(entry.sessionId)}`;
-        case 'relay':
-            return null;
-        default:
-            return null;
-    }
+        if (entry.source === 'cursor')
+            return `cursor-agent --resume=${shellQuote(entry.sessionId)}`;
+        if (entry.source === 'grok')
+            return `grok resume ${shellQuote(entry.sessionId)}`;
+        return null;
+    })();
+    return resume && entry.project ? `cd ${shellQuote(entry.project)} && ${resume}` : resume;
 }
 function shellQuote(value) {
-    if (/^[A-Za-z0-9_\-./]+$/.test(value))
-        return value;
-    return `'${value.replace(/'/g, `'\\''`)}'`;
+    return /^[A-Za-z0-9._:/-]+$/.test(value) ? value : `'${value.replace(/'/g, `'"'"'`)}'`;
 }
 //# sourceMappingURL=index.js.map