ai-hist 0.3.2 → 0.3.4

package/dist/index.js

@@ -3,27 +3,37 @@
  *
  * 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 file the Python CLI
- * maintains (default `~/.local/share/ai-hist/ai-history.db`, or
- * `$AI_HIST_DB`); the Python tool stays the canonical sync engine.
+ * 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.
  */
 import initSqlJs from 'sql.js';
-import { readFile, stat } from 'node:fs/promises';
+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';
-/** Resolve the SQLite path the Python CLI writes to. */
+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) {
@@ -31,6 +41,23 @@ function getSqlJs() {
     }
     return _sqlPromise;
 }
+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,
+    PRIMARY KEY (session_id, source)
+  )`);
+    db.run('CREATE INDEX IF NOT EXISTS idx_sessions_cwd ON sessions(cwd)');
+    db.run('CREATE INDEX IF NOT EXISTS idx_sessions_branch ON sessions(git_branch)');
+    db.run('CREATE INDEX IF NOT EXISTS idx_sessions_last ON sessions(last_activity_ms DESC)');
+}
 function ensureTrajectorySchema(db) {
     db.run(`CREATE TABLE IF NOT EXISTS trajectories (
     id TEXT PRIMARY KEY,
@@ -52,6 +79,27 @@ function ensureTrajectorySchema(db) {
     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)');
 }
+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)');
+}
 /**
  * Open an `AiHist` reader. Async because sql.js initializes its WASM
  * runtime lazily and the DB file is read asynchronously so the host
@@ -69,6 +117,13 @@ export async function openAiHist(opts = {}) {
         const fileBuffer = await readFile(dbPath);
         const db = new SQL.Database(fileBuffer);
         ensureTrajectorySchema(db);
+        ensureTagSchema(db);
+        ensureSessionsSchema(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 */ }
         // The Python CLI's schema doesn't create `idx_history_session` or
         // `idx_history_timestamp`. Without them, listSessions degrades to
         // an O(sessions × rows) full table scan and freezes the WASM
@@ -97,16 +152,20 @@ export async function openAiHist(opts = {}) {
     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);
     // 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) VALUES (?, ?, ?, ?, ?)');
+    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,
@@ -115,7 +174,10 @@ export async function openAiHist(opts = {}) {
     try {
         db.exec('BEGIN');
         for (const row of rows) {
-            insert.run([row.source, row.sessionId, row.project, row.prompt, row.timestampMs]);
+            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([
@@ -141,6 +203,7 @@ export async function openAiHist(opts = {}) {
                 trajectory.projectId,
                 trajectory.searchText,
                 trajectory.timestampMs,
+                null,
             ]);
         }
         db.exec('COMMIT');
@@ -161,6 +224,64 @@ async function pathExists(p) {
         return false;
     }
 }
+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 });
+    }
+}
+async function scanOpenCode(SQL) {
+    const dbPath = defaultOpenCodeDbPath();
+    if (!(await pathExists(dbPath)))
+        return [];
+    try {
+        const fileBuffer = await readSqliteSnapshot(dbPath);
+        const db = new SQL.Database(fileBuffer);
+        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,
+                });
+            }
+            return scanned;
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        return [];
+    }
+}
 function rowToEntry(row) {
     return {
         id: row.id,
@@ -169,6 +290,7 @@ function rowToEntry(row) {
         project: row.project,
         prompt: row.prompt,
         timestampMs: row.timestamp_ms,
+        gitBranch: row.git_branch ?? null,
     };
 }
 function parseJson(raw, fallback) {
@@ -243,6 +365,22 @@ function appendProjectFilter(clauses, params, project, projectScope) {
         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 = [];
@@ -251,6 +389,7 @@ function buildFilters(opts, projectScope) {
         params.push(opts.source);
     }
     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);
@@ -306,11 +445,151 @@ export class AiHist {
         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
+        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
@@ -375,11 +654,16 @@ export class AiHist {
         }));
     }
     /** All prompts in a session, ordered oldest → newest. */
-    getSession(sessionId) {
+    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);
-        return runQuery(this.db, `SELECT id, source, session_id, project, prompt, timestamp_ms
+        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);
@@ -410,11 +694,12 @@ export class AiHist {
             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
+        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 DESC
@@ -460,7 +745,7 @@ export class AiHist {
         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
+        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;
     }
@@ -472,11 +757,105 @@ export class AiHist {
         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
+        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 = [];
@@ -503,6 +882,47 @@ export class AiHist {
         };
     }
 }
+/**
+ * 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.
+ */
+function isBoilerplatePrompt(prompt) {
+    const t = prompt.trimStart();
+    return (t.startsWith('<system-reminder') ||
+        t.startsWith('<command-') ||
+        t.startsWith('Caveat:') ||
+        t.startsWith('[Request interrupted'));
+}
+/**
+ * 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);
+}
+/**
+ * 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)}`;
+}
 /**
  * Resume command for an entry/session, matching what `ai-hist show` prints.
  * Returns `null` for sources that don't have a resume affordance (relay).