@phnx-labs/agents-cli 1.12.0 → 1.14.2

package/dist/lib/session/db.d.ts

@@ -1,5 +1,14 @@
-import Database from 'better-sqlite3';
+/**
+ * SQLite-backed session index and full-text search.
+ *
+ * Stores session metadata and user-prompt text in a WAL-mode SQLite database
+ * at ~/.agents/sessions/sessions.db. Provides incremental upsert, scan-stamp
+ * ledger (mtime/size tracking to skip unchanged files), FTS5 search with
+ * BM25 ranking, and label-first search for /rename'd sessions.
+ */
+import Database from '../sqlite.js';
 import type { SessionAgentId, SessionMeta } from './types.js';
+/** Raw row shape returned from the sessions table. */
 export interface SessionRow {
     id: string;
     short_id: string;
@@ -20,10 +29,12 @@ export interface SessionRow {
     scanned_at: number | null;
     is_team_origin: number;
 }
+/** File stat snapshot used to detect changes between scan runs. */
 export interface ScanStamp {
     fileMtimeMs: number;
     fileSize: number;
 }
+/** Filter and pagination options for querying the sessions table. */
 export interface QueryOptions {
     agent?: SessionAgentId;
     agents?: SessionAgentId[];
@@ -40,8 +51,11 @@ export interface QueryOptions {
     /** Keep only team-origin rows (for hidden-count queries). */
     onlyTeamOrigin?: boolean;
 }
+/** Open (or return the cached) sessions database, applying migrations as needed. */
 export declare function getDB(): Database.Database;
+/** Close the cached database connection. */
 export declare function closeDB(): void;
+/** Return the absolute path to the sessions database file. */
 export declare function getDBPath(): string;
 /**
  * Look up the file stat stamp we stored the last time we scanned a given file path.
@@ -66,6 +80,7 @@ export declare function recordScans(entries: Array<{
  * `content` is the tokenizable user-prompt text; pass '' to leave the row unsearchable.
  */
 export declare function upsertSession(meta: SessionMeta, content: string, scan?: ScanStamp): void;
+/** Batch-upsert sessions with their FTS5 content and scan stamps in a single transaction. */
 export declare function upsertSessionsBatch(entries: Array<{
     meta: SessionMeta;
     content: string;
@@ -77,11 +92,17 @@ export declare function upsertSessionsBatch(entries: Array<{
  * Leaves FTS5 content/topic/project untouched — cheap to call every run.
  */
 export declare function syncLabels(labelMap: Map<string, string | null>): number;
+/** Query sessions from the database, applying filters and ordering by timestamp descending. */
 export declare function querySessions(options?: QueryOptions): SessionMeta[];
+/** Count sessions matching the given filter options. */
 export declare function countSessions(options?: QueryOptions): number;
+/** Return the set of all file paths currently tracked in the sessions table. */
 export declare function getAllFilePaths(): Set<string>;
+/** Look up sessions by their source file paths. */
 export declare function getSessionsByFilePaths(paths: string[]): Map<string, SessionMeta>;
+/** Look up a single session by its unique ID. */
 export declare function getSessionById(id: string): SessionMeta | null;
+/** A single full-text search result with ranking score. */
 export interface FtsHit {
     sessionId: string;
     score: number;
@@ -111,8 +132,8 @@ export declare function buildFtsQuery(input: string): {
  * so "higher = better" is consistent across all tiers.
  */
 export declare function ftsSearch(input: string, limit?: number): FtsHit[];
+/** Return the total row counts for the sessions and FTS5 tables (diagnostic). */
 export declare function getRowCount(): {
     sessions: number;
     textRows: number;
 };
-//# sourceMappingURL=db.d.ts.map

package/dist/lib/session/db.js

@@ -1,14 +1,43 @@
+/**
+ * SQLite-backed session index and full-text search.
+ *
+ * Stores session metadata and user-prompt text in a WAL-mode SQLite database
+ * at ~/.agents/sessions/sessions.db. Provides incremental upsert, scan-stamp
+ * ledger (mtime/size tracking to skip unchanged files), FTS5 search with
+ * BM25 ranking, and label-first search for /rename'd sessions.
+ */
 import * as fs from 'fs';
-import * as os from 'os';
 import * as path from 'path';
-import Database from 'better-sqlite3';
-const HOME = os.homedir();
-const SESSIONS_DIR = path.join(HOME, '.agents', 'sessions');
+import Database from '../sqlite.js';
+import { getAgentsDir } from '../state.js';
+const SESSIONS_DIR = path.join(getAgentsDir(), 'sessions');
 const DB_PATH = path.join(SESSIONS_DIR, 'sessions.db');
-const SCHEMA_VERSION = 4;
+/** Current schema version; bumped when migrations are added. */
+const SCHEMA_VERSION = 5;
+/**
+ * Canonicalize a file path for use as a scan_ledger key. The same physical
+ * session file is reachable via multiple aliases — `~/.claude/projects/x.jsonl`
+ * (when `~/.claude` is a symlink to a versioned home) and
+ * `~/.agents-system/versions/claude/<v>/home/.claude/projects/x.jsonl`. Keying the
+ * ledger by the raw path means switching between these aliases (e.g. via
+ * `agents use`) misses the cache and forces a full re-parse. Realpath collapses
+ * all aliases to one stable key.
+ */
+function canonicalLedgerKey(filePath) {
+    if (!filePath)
+        return filePath;
+    try {
+        return fs.realpathSync(filePath);
+    }
+    catch {
+        return filePath;
+    }
+}
 // BM25 column weights for session_text: label > topic > project > content.
 // Higher weights make matches in that column rank higher.
+/** BM25 column weights for FTS5: label > topic > project > content. */
 const BM25_WEIGHTS = [5.0, 2.0, 1.5, 1.0];
+/** DDL for the sessions database (tables, indexes, FTS5 virtual table). */
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS sessions (
   id TEXT PRIMARY KEY,
@@ -105,7 +134,15 @@ function migrateSchema(db, fromVersion) {
         }
         db.exec(`DELETE FROM scan_ledger;`);
     }
+    if (fromVersion < 5) {
+        // v4 → v5: ledger is now keyed by realpath instead of the as-discovered
+        // path, so symlink/version-relative aliases for the same physical file
+        // collapse to one row. Old aliased rows are dropped — next scan will
+        // repopulate under canonical keys.
+        db.exec(`DELETE FROM scan_ledger;`);
+    }
 }
+/** Open (or return the cached) sessions database, applying migrations as needed. */
 export function getDB() {
     if (dbInstance)
         return dbInstance;
@@ -144,12 +181,14 @@ export function getDB() {
     dbInstance = db;
     return db;
 }
+/** Close the cached database connection. */
 export function closeDB() {
     if (dbInstance) {
         dbInstance.close();
         dbInstance = null;
     }
 }
+/** Return the absolute path to the sessions database file. */
 export function getDBPath() {
     return DB_PATH;
 }
@@ -161,7 +200,7 @@ export function getScanStampByPath(filePath) {
     const db = getDB();
     const row = db
         .prepare(`SELECT file_mtime_ms, file_size FROM scan_ledger WHERE file_path = ? LIMIT 1`)
-        .get(filePath);
+        .get(canonicalLedgerKey(filePath));
     return row ? { fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size } : null;
 }
 /**
@@ -173,10 +212,24 @@ export function getScanStampsForPaths(filePaths) {
     if (filePaths.length === 0)
         return result;
     const db = getDB();
+    // Multiple input paths can resolve to the same canonical key (e.g. the same
+    // session JSONL reachable via `~/.claude/...` and `~/.agents-system/versions/...`).
+    // We query DB by canonical key, then fan results back out to every original
+    // alias so callers can `.get(filePath)` with the path they passed in.
+    const canonicalToOriginals = new Map();
+    for (const fp of filePaths) {
+        const canonical = canonicalLedgerKey(fp);
+        const aliases = canonicalToOriginals.get(canonical);
+        if (aliases)
+            aliases.push(fp);
+        else
+            canonicalToOriginals.set(canonical, [fp]);
+    }
+    const canonicalKeys = [...canonicalToOriginals.keys()];
     // SQLite parameter limit is typically 999 / 32766 — chunk defensively.
     const CHUNK = 500;
-    for (let i = 0; i < filePaths.length; i += CHUNK) {
-        const chunk = filePaths.slice(i, i + CHUNK);
+    for (let i = 0; i < canonicalKeys.length; i += CHUNK) {
+        const chunk = canonicalKeys.slice(i, i + CHUNK);
         const placeholders = chunk.map(() => '?').join(',');
         const rows = db
             .prepare(`
@@ -186,7 +239,10 @@ export function getScanStampsForPaths(filePaths) {
       `)
             .all(...chunk);
         for (const row of rows) {
-            result.set(row.file_path, { fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size });
+            const stamp = { fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size };
+            for (const original of canonicalToOriginals.get(row.file_path) || []) {
+                result.set(original, stamp);
+            }
         }
     }
     return result;
@@ -210,7 +266,7 @@ export function recordScans(entries) {
     const now = Date.now();
     const txn = db.transaction((items) => {
         for (const { filePath, scan } of items) {
-            stmt.run(filePath, scan.fileMtimeMs, scan.fileSize, now);
+            stmt.run(canonicalLedgerKey(filePath), scan.fileMtimeMs, scan.fileSize, now);
         }
     });
     txn(entries);
@@ -291,6 +347,7 @@ export function upsertSession(meta, content, scan) {
     });
     txn();
 }
+/** Batch-upsert sessions with their FTS5 content and scan stamps in a single transaction. */
 export function upsertSessionsBatch(entries) {
     if (entries.length === 0)
         return;
@@ -330,7 +387,7 @@ export function upsertSessionsBatch(entries) {
             delText.run(meta.id);
             insText.run(meta.id, meta.label ?? '', meta.topic ?? '', meta.project ?? '', content ?? '');
             if (scan && meta.filePath) {
-                ledger.run(meta.filePath, scan.fileMtimeMs, scan.fileSize, now);
+                ledger.run(canonicalLedgerKey(meta.filePath), scan.fileMtimeMs, scan.fileSize, now);
             }
         }
     });
@@ -374,6 +431,7 @@ export function syncLabels(labelMap) {
     txn(updates);
     return updates.length;
 }
+/** Convert a raw database row into a SessionMeta object. */
 function rowToMeta(row) {
     return {
         id: row.id,
@@ -393,6 +451,7 @@ function rowToMeta(row) {
         isTeamOrigin: row.is_team_origin === 1,
     };
 }
+/** Build a parameterized WHERE clause from query options. */
 function buildSessionWhere(options) {
     const where = [];
     const params = [];
@@ -438,6 +497,7 @@ function buildSessionWhere(options) {
     const clause = where.length > 0 ? `WHERE ${where.join(' AND ')}` : '';
     return { clause, params };
 }
+/** Query sessions from the database, applying filters and ordering by timestamp descending. */
 export function querySessions(options = {}) {
     const db = getDB();
     const { clause, params } = buildSessionWhere(options);
@@ -446,6 +506,7 @@ export function querySessions(options = {}) {
     const rows = db.prepare(sql).all(...params);
     return rows.map(rowToMeta);
 }
+/** Count sessions matching the given filter options. */
 export function countSessions(options = {}) {
     const db = getDB();
     const { clause, params } = buildSessionWhere(options);
@@ -453,11 +514,13 @@ export function countSessions(options = {}) {
     const row = db.prepare(sql).get(...params);
     return row ? row.n : 0;
 }
+/** Return the set of all file paths currently tracked in the sessions table. */
 export function getAllFilePaths() {
     const db = getDB();
     const rows = db.prepare(`SELECT file_path FROM sessions`).all();
     return new Set(rows.map(r => r.file_path));
 }
+/** Look up sessions by their source file paths. */
 export function getSessionsByFilePaths(paths) {
     if (paths.length === 0)
         return new Map();
@@ -471,6 +534,7 @@ export function getSessionsByFilePaths(paths) {
         result.set(row.file_path, rowToMeta(row));
     return result;
 }
+/** Look up a single session by its unique ID. */
 export function getSessionById(id) {
     const db = getDB();
     const row = db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(id);
@@ -567,10 +631,10 @@ export function ftsSearch(input, limit = 200) {
     hits.sort((a, b) => b.score - a.score);
     return hits.slice(0, limit);
 }
+/** Return the total row counts for the sessions and FTS5 tables (diagnostic). */
 export function getRowCount() {
     const db = getDB();
     const sessions = db.prepare(`SELECT COUNT(*) AS c FROM sessions`).get().c;
     const textRows = db.prepare(`SELECT COUNT(*) AS c FROM session_text`).get().c;
     return { sessions, textRows };
 }
-//# sourceMappingURL=db.js.map

package/dist/lib/session/discover.d.ts

@@ -1,4 +1,13 @@
+/**
+ * Session discovery across Claude, Codex, Gemini, OpenCode, and OpenClaw.
+ *
+ * Performs incremental scans: each agent's session files are stat'd and compared
+ * to a scan-stamp ledger in SQLite. Only files whose mtime or size changed since
+ * the last run are re-parsed. All metadata is upserted into the sessions DB so
+ * subsequent queries are served entirely from the cache.
+ */
 import type { SessionAgentId, SessionMeta } from './types.js';
+/** Options controlling which sessions to discover and how to report progress. */
 export interface DiscoverOptions {
     agent?: SessionAgentId;
     version?: string;
@@ -19,6 +28,7 @@ export interface DiscoverOptions {
     /** Called as each agent makes parsing progress. Totals count only files that need re-parsing (cache misses). */
     onProgress?: (progress: ScanProgress) => void;
 }
+/** Progress report emitted during incremental scanning. */
 export interface ScanProgress {
     agent: SessionAgentId;
     parsed: number;
@@ -51,10 +61,15 @@ export declare function searchContentIndex(sessions: SessionMeta[], query: strin
  * realpath to avoid double-counting symlinked version homes.
  */
 export declare function getAgentSessionDirs(agent: string, subdir: string): string[];
-export declare function readFirstLines(filePath: string, maxLines: number): Promise<string[]>;
 /**
- * Walk a directory recursively for files with a given extension.
+ * Build a map of Claude sessionId -> user-given label from ~/.claude/sessions/*.json.
+ * Each JSON has shape { pid, sessionId, cwd, startedAt, name?, ... }. The
+ * `name` field only exists if the user ran /rename in that session.
+ * For sessionId collisions (re-resume of the same session), prefer the most
+ * recent startedAt.
  */
-export declare function walkForFiles(dir: string, ext: string, limit: number): string[];
+export declare function buildClaudeLabelMap(): Map<string, string | null>;
+/** Read up to maxLines non-empty lines from the beginning of a file. */
+export declare function readFirstLines(filePath: string, maxLines: number): Promise<string[]>;
+/** Parse a time filter string (relative like '7d' or ISO timestamp) into epoch milliseconds. */
 export declare function parseTimeFilter(input: string): number;
-//# sourceMappingURL=discover.d.ts.map