@phnx-labs/agents-cli 1.12.0 → 1.14.2

package/dist/lib/session/discover.js

@@ -1,16 +1,30 @@
+/**
+ * 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 * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as crypto from 'crypto';
 import * as readline from 'readline';
-import { execSync } from 'child_process';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { getAgentsDir } from '../state.js';
+const execFileAsync = promisify(execFile);
 import { AGENTS, getCliVersion } from '../agents.js';
+import { walkForFiles } from '../fs-walk.js';
 import { getConfigSymlinkVersion } from '../shims.js';
 import { SESSION_AGENTS } from './types.js';
 import { extractSessionTopic } from './prompt.js';
 import { getDB, getScanStampByPath, getScanStampsForPaths, recordScans, syncLabels, upsertSessionsBatch, querySessions, countSessions, ftsSearch, } from './db.js';
 const HOME = os.homedir();
-const AGENTS_DIR = path.join(HOME, '.agents');
+const AGENTS_DIR = getAgentsDir();
+const RUSH_SESSIONS_DIR = path.join(HOME, '.rush', 'sessions');
+const HERMES_SESSIONS_DIR = path.join(HOME, '.hermes', 'sessions');
 /** How long OpenClaw channel/cron snapshots stay valid before we re-shell-out. */
 const OPENCLAW_TTL_MS = 60_000;
 let cachedOpenClawWorkspaces = null;
@@ -32,6 +46,8 @@ export async function discoverSessions(options) {
             case 'gemini': return scanGeminiIncremental(onProgress);
             case 'opencode': return scanOpenCodeIncremental();
             case 'openclaw': return scanOpenClawIncremental();
+            case 'rush': return scanRushIncremental(onProgress);
+            case 'hermes': return scanHermesIncremental(onProgress);
         }
     }));
     const sessions = querySessions(buildQueryOptions(options, agents, { includeLimit: true }));
@@ -46,6 +62,7 @@ export function countSessionsInScope(options) {
     const agents = options.agent ? [options.agent] : SESSION_AGENTS;
     return countSessions(buildQueryOptions(options, agents, { includeLimit: false }));
 }
+/** Translate DiscoverOptions into the QueryOptions shape expected by the DB layer. */
 function buildQueryOptions(options, agents, opts) {
     const projectQuery = options?.project?.trim();
     const sinceMs = options?.since ? parseTimeFilter(options.since) : undefined;
@@ -55,7 +72,9 @@ function buildQueryOptions(options, agents, opts) {
     if (options?.cwdPrefix) {
         cwdPrefixFilter = normalizeCwd(options.cwdPrefix);
     }
-    else if (!options?.all && !projectQuery) {
+    else if (!options?.all && !projectQuery && options?.agent !== 'rush' && options?.agent !== 'hermes') {
+        // Rush and Hermes sessions are cloud/gateway-bound and have no cwd — skip
+        // cwd filtering when the user explicitly asked for them.
         cwdFilter = normalizeCwd(options?.cwd || process.cwd());
     }
     return {
@@ -72,6 +91,7 @@ function buildQueryOptions(options, agents, opts) {
         onlyTeamOrigin: options?.onlyTeamOrigin,
     };
 }
+/** Resolve and canonicalize a working directory path (follows symlinks). */
 function normalizeCwd(cwd) {
     if (!cwd)
         return '';
@@ -188,6 +208,7 @@ export function getAgentSessionDirs(agent, subdir) {
 // Claude account info
 // ---------------------------------------------------------------------------
 let cachedClaudeAccount;
+/** Read the Claude OAuth account email from .claude.json across all version homes. */
 function getClaudeAccount() {
     if (cachedClaudeAccount !== undefined)
         return cachedClaudeAccount || undefined;
@@ -234,7 +255,7 @@ function getClaudeAccount() {
  * For sessionId collisions (re-resume of the same session), prefer the most
  * recent startedAt.
  */
-function buildClaudeLabelMap() {
+export function buildClaudeLabelMap() {
     const map = new Map();
     const dir = path.join(HOME, '.claude', 'sessions');
     if (!fs.existsSync(dir))
@@ -265,6 +286,7 @@ function buildClaudeLabelMap() {
         out.set(sid, label);
     return out;
 }
+/** Incrementally re-scan changed Claude session files and upsert into the DB. */
 async function scanClaudeIncremental(onProgress) {
     const account = getClaudeAccount();
     const labelMap = buildClaudeLabelMap();
@@ -331,6 +353,7 @@ async function scanClaudeIncremental(onProgress) {
     if (labelMap.size > 0)
         syncLabels(labelMap);
 }
+/** Stream-parse a single Claude JSONL file to extract session metadata. */
 async function readClaudeMeta(filePath, sessionId, account, label) {
     const scan = await scanClaudeSession(filePath);
     const isTeamOrigin = scan.entrypoint === 'sdk-cli';
@@ -377,6 +400,7 @@ async function readClaudeMeta(filePath, sessionId, account, label) {
 // Codex account info
 // ---------------------------------------------------------------------------
 let cachedCodexAccount;
+/** Extract the Codex account email from the JWT id_token in auth.json. */
 function getCodexAccount() {
     if (cachedCodexAccount !== undefined)
         return cachedCodexAccount || undefined;
@@ -415,6 +439,7 @@ function getCodexAccount() {
 // ---------------------------------------------------------------------------
 // Codex
 // ---------------------------------------------------------------------------
+/** Incrementally re-scan changed Codex session files and upsert into the DB. */
 async function scanCodexIncremental(onProgress) {
     const account = getCodexAccount();
     const currentVersion = await getCurrentAgentVersion('codex');
@@ -453,6 +478,7 @@ async function scanCodexIncremental(onProgress) {
     upsertSessionsBatch(entries);
     recordScans(touched);
 }
+/** Stream-parse a single Codex JSONL file to extract session metadata. */
 async function readCodexMeta(filePath, account, currentVersion) {
     const scan = await scanCodexSession(filePath);
     const sessionId = scan.sessionId || '';
@@ -463,7 +489,9 @@ async function readCodexMeta(filePath, account, currentVersion) {
         id: sessionId,
         shortId: sessionId.slice(0, 8),
         agent: 'codex',
-        timestamp: scan.timestamp || new Date().toISOString(),
+        // Codex `session_meta` only carries the start time; use file mtime when
+        // it's newer so long-running sessions register as recently active.
+        timestamp: pickLatestCodexTimestamp(scan.timestamp, filePath),
         project: cwd ? path.basename(cwd) : undefined,
         cwd,
         filePath,
@@ -476,9 +504,30 @@ async function readCodexMeta(filePath, account, currentVersion) {
     };
     return { meta, content: scan.contentText || '' };
 }
+/**
+ * Codex writes `session_meta` (with the start timestamp) on the first line of a
+ * rollout and never updates it. For long-running sessions that's stale by
+ * hours — `--since 2h` would drop a session still being actively written.
+ * Compare against the file's mtime and use whichever is newer.
+ */
+function pickLatestCodexTimestamp(metaTimestamp, filePath) {
+    const fallback = new Date().toISOString();
+    let mtimeIso = null;
+    try {
+        mtimeIso = fs.statSync(filePath).mtime.toISOString();
+    }
+    catch {
+        /* file vanished between scan and stat */
+    }
+    const candidates = [metaTimestamp, mtimeIso].filter((v) => !!v);
+    if (candidates.length === 0)
+        return fallback;
+    return candidates.reduce((best, cur) => (cur > best ? cur : best));
+}
 // ---------------------------------------------------------------------------
 // Gemini
 // ---------------------------------------------------------------------------
+/** Incrementally re-scan changed Gemini session files and upsert into the DB. */
 async function scanGeminiIncremental(onProgress) {
     const currentVersion = await getCurrentAgentVersion('gemini');
     const projectMap = buildGeminiProjectMap();
@@ -540,6 +589,7 @@ async function scanGeminiIncremental(onProgress) {
     upsertSessionsBatch(entries);
     recordScans(touched);
 }
+/** Parse a single Gemini JSON session file to extract session metadata. */
 function readGeminiMeta(filePath, hashDir, projectMap, currentVersion) {
     let session;
     try {
@@ -604,6 +654,7 @@ function readGeminiMeta(filePath, hashDir, projectMap, currentVersion) {
     };
     return { meta, content: userTexts.join('\n') };
 }
+/** Build a hash-to-project mapping from Gemini's projects.json and history directories. */
 function buildGeminiProjectMap() {
     const map = new Map();
     const projectsJsonPath = path.join(HOME, '.gemini', 'projects.json');
@@ -657,12 +708,17 @@ function buildGeminiProjectMap() {
 // ---------------------------------------------------------------------------
 const OPENCODE_DB = path.join(HOME, '.local', 'share', 'opencode', 'opencode.db');
 let cachedOpenCodeAccount;
-function getOpenCodeAccount() {
+/** Query the active OpenCode account email from its SQLite database. */
+async function getOpenCodeAccount() {
     if (cachedOpenCodeAccount !== undefined)
         return cachedOpenCodeAccount || undefined;
     try {
         if (fs.existsSync(OPENCODE_DB)) {
-            const out = execSync(`sqlite3 "${OPENCODE_DB}" "SELECT email FROM control_account WHERE active=1 LIMIT 1;"`, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+            const { stdout } = await execFileAsync('sqlite3', [
+                OPENCODE_DB,
+                'SELECT email FROM control_account WHERE active=1 LIMIT 1;',
+            ], { encoding: 'utf-8' });
+            const out = stdout.trim();
             if (out) {
                 cachedOpenCodeAccount = out;
                 return out;
@@ -673,6 +729,7 @@ function getOpenCodeAccount() {
     cachedOpenCodeAccount = '';
     return undefined;
 }
+/** Scan OpenCode sessions from its SQLite database when the DB file has changed. */
 async function scanOpenCodeIncremental() {
     if (!fs.existsSync(OPENCODE_DB))
         return;
@@ -689,7 +746,7 @@ async function scanOpenCodeIncremental() {
     if (prev && prev.fileMtimeMs === currentScan.fileMtimeMs && prev.fileSize === currentScan.fileSize) {
         return;
     }
-    const account = getOpenCodeAccount();
+    const account = await getOpenCodeAccount();
     const currentVersion = await getCurrentAgentVersion('opencode');
     try {
         const query = `
@@ -722,7 +779,11 @@ async function scanOpenCodeIncremental() {
       ORDER BY time_created DESC
       LIMIT 1000;
     `.replace(/\n/g, ' ');
-        const out = execSync(`sqlite3 -separator '|||' "${OPENCODE_DB}"`, { encoding: 'utf-8', input: query, stdio: ['pipe', 'pipe', 'ignore'], timeout: 5000 });
+        const { stdout: out } = await execFileAsync('sqlite3', ['-separator', '|||', OPENCODE_DB, query], {
+            encoding: 'utf-8',
+            timeout: 5000,
+            maxBuffer: 32 * 1024 * 1024,
+        });
         const entries = [];
         for (const line of out.split('\n')) {
             if (!line.trim())
@@ -765,10 +826,11 @@ async function scanOpenCodeIncremental() {
 // ---------------------------------------------------------------------------
 // OpenClaw
 // ---------------------------------------------------------------------------
+/** Scan active OpenClaw channels and cron jobs via the openclaw CLI. */
 async function scanOpenClawIncremental() {
     // Check if openclaw is installed — silently skip if not.
     try {
-        execSync('which openclaw', { stdio: 'ignore' });
+        await execFileAsync('which', ['openclaw']);
     }
     catch {
         return;
@@ -786,9 +848,8 @@ async function scanOpenClawIncremental() {
     const scan = { fileMtimeMs: now, fileSize: 0 };
     const entries = [];
     try {
-        const output = execSync('openclaw channels status', {
+        const { stdout: output } = await execFileAsync('openclaw', ['channels', 'status'], {
             encoding: 'utf-8',
-            stdio: ['ignore', 'pipe', 'ignore'],
         });
         for (const line of output.split('\n')) {
             const match = line.match(/^-\s+\w+\s+(\S+)\s+\((\w+)\):\s*(.+)/);
@@ -817,9 +878,8 @@ async function scanOpenClawIncremental() {
         /* channels command failed */
     }
     try {
-        const output = execSync('openclaw cron list', {
+        const { stdout: output } = await execFileAsync('openclaw', ['cron', 'list'], {
             encoding: 'utf-8',
-            stdio: ['ignore', 'pipe', 'ignore'],
         });
         const lines = output.split('\n');
         for (let i = 1; i < lines.length; i++) {
@@ -856,6 +916,255 @@ async function scanOpenClawIncremental() {
     upsertSessionsBatch(entries);
     db.prepare(`INSERT OR REPLACE INTO meta (key, value) VALUES ('openclaw_last_scan_ms', ?)`).run(String(Date.now()));
 }
+/** Incrementally re-scan changed Rush session files and upsert into the DB. */
+async function scanRushIncremental(onProgress) {
+    if (!fs.existsSync(RUSH_SESSIONS_DIR))
+        return;
+    const filePaths = [];
+    let dirNames;
+    try {
+        dirNames = fs.readdirSync(RUSH_SESSIONS_DIR);
+    }
+    catch {
+        return;
+    }
+    for (const dirName of dirNames) {
+        const sessionDir = path.join(RUSH_SESSIONS_DIR, dirName);
+        const stat = safeStatSync(sessionDir);
+        if (!stat?.isDirectory())
+            continue;
+        const messagesPath = path.join(sessionDir, 'messages.jsonl');
+        if (!fs.existsSync(messagesPath))
+            continue;
+        filePaths.push(messagesPath);
+    }
+    const changed = filterChangedFiles(filePaths);
+    if (changed.length === 0)
+        return;
+    onProgress?.({ agent: 'rush', parsed: 0, total: changed.length });
+    const entries = [];
+    const touched = [];
+    let parsed = 0;
+    for (const { filePath, scan } of changed) {
+        try {
+            const sessionId = path.basename(path.dirname(filePath));
+            const result = await readRushMeta(filePath, sessionId);
+            if (result) {
+                entries.push({ meta: result.meta, content: result.content, scan });
+            }
+            else {
+                touched.push({ filePath, scan });
+            }
+        }
+        catch {
+            touched.push({ filePath, scan });
+        }
+        parsed++;
+        onProgress?.({ agent: 'rush', parsed, total: changed.length });
+    }
+    upsertSessionsBatch(entries);
+    recordScans(touched);
+}
+/** Stream-parse a single Rush messages.jsonl file to extract session metadata. */
+async function readRushMeta(filePath, sessionId) {
+    const scan = await scanRushSession(filePath);
+    const stat = safeStatSync(filePath);
+    const timestamp = scan.timestamp
+        || (stat ? stat.mtime.toISOString() : new Date().toISOString());
+    const shortId = sessionId.replace(/^session_/, '').slice(0, 8);
+    const meta = {
+        id: sessionId,
+        shortId,
+        agent: 'rush',
+        timestamp,
+        project: scan.agentId,
+        filePath,
+        topic: scan.topic,
+        messageCount: scan.messageCount,
+    };
+    return { meta, content: scan.contentText || '' };
+}
+/** Stream a Rush messages.jsonl file and extract scan-level metadata. */
+async function scanRushSession(filePath) {
+    const stream = fs.createReadStream(filePath, { encoding: 'utf-8' });
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    let timestamp;
+    let topic;
+    let agentId;
+    let messageCount = 0;
+    const userTexts = [];
+    try {
+        for await (const line of rl) {
+            if (!line.trim())
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (!timestamp && typeof parsed.created_at === 'string') {
+                timestamp = parsed.created_at;
+            }
+            if (!agentId && typeof parsed.agent_id === 'string') {
+                agentId = parsed.agent_id;
+            }
+            if (parsed.type !== 'message')
+                continue;
+            const text = typeof parsed.content?.text === 'string' ? parsed.content.text.trim() : '';
+            if (!text)
+                continue;
+            const cleaned = text
+                .replace(/^<user_input>/, '')
+                .replace(/<\/user_input>$/, '')
+                .trim();
+            if (!cleaned)
+                continue;
+            if (parsed.role === 'system' && cleaned === 'execution_start')
+                continue;
+            messageCount++;
+            if (parsed.role === 'user') {
+                userTexts.push(cleaned);
+                if (!topic)
+                    topic = extractSessionTopic(cleaned);
+            }
+        }
+    }
+    finally {
+        rl.close();
+        stream.destroy();
+    }
+    return {
+        timestamp,
+        topic,
+        agentId,
+        messageCount,
+        contentText: userTexts.length > 0 ? userTexts.join('\n') : undefined,
+    };
+}
+// ---------------------------------------------------------------------------
+// Hermes
+//
+// Hermes sessions live at ~/.hermes/sessions/session_<id>.json (one JSON
+// file per session). Shape:
+//   { session_id, model, platform, session_start, last_updated,
+//     system_prompt, message_count, messages: [{role, content}, ...] }
+// request_dump_*.json files in the same dir are per-turn debug dumps — skip.
+// Hermes is a gateway/API agent, so cwd is left unset.
+// ---------------------------------------------------------------------------
+/** Incrementally re-scan changed Hermes session files and upsert into the DB. */
+async function scanHermesIncremental(onProgress) {
+    if (!fs.existsSync(HERMES_SESSIONS_DIR))
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(HERMES_SESSIONS_DIR);
+    }
+    catch {
+        return;
+    }
+    const filePaths = [];
+    for (const name of entries) {
+        if (!name.startsWith('session_') || !name.endsWith('.json'))
+            continue;
+        filePaths.push(path.join(HERMES_SESSIONS_DIR, name));
+    }
+    const changed = filterChangedFiles(filePaths);
+    if (changed.length === 0)
+        return;
+    onProgress?.({ agent: 'hermes', parsed: 0, total: changed.length });
+    const scanEntries = [];
+    const touched = [];
+    const seen = new Set();
+    let parsed = 0;
+    for (const { filePath, scan } of changed) {
+        try {
+            const result = readHermesMeta(filePath);
+            if (result && !seen.has(result.meta.id)) {
+                seen.add(result.meta.id);
+                scanEntries.push({ meta: result.meta, content: result.content, scan });
+            }
+            else {
+                touched.push({ filePath, scan });
+            }
+        }
+        catch {
+            touched.push({ filePath, scan });
+        }
+        parsed++;
+        onProgress?.({ agent: 'hermes', parsed, total: changed.length });
+    }
+    upsertSessionsBatch(scanEntries);
+    recordScans(touched);
+}
+/** Parse a single Hermes session JSON file to extract session metadata. */
+function readHermesMeta(filePath) {
+    let session;
+    try {
+        session = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    const sessionId = typeof session.session_id === 'string' ? session.session_id : '';
+    if (!sessionId)
+        return null;
+    const messages = Array.isArray(session.messages) ? session.messages : [];
+    const userTexts = [];
+    let topic;
+    let messageCount = 0;
+    for (const msg of messages) {
+        const text = extractHermesMessageText(msg?.content);
+        if (!text)
+            continue;
+        messageCount++;
+        if (msg?.role === 'user') {
+            userTexts.push(text);
+            if (!topic)
+                topic = extractSessionTopic(text);
+        }
+    }
+    const stat = safeStatSync(filePath);
+    const timestamp = typeof session.last_updated === 'string'
+        ? session.last_updated
+        : typeof session.session_start === 'string'
+            ? session.session_start
+            : stat ? stat.mtime.toISOString() : new Date().toISOString();
+    const shortId = sessionId.replace(/^api-/, '').slice(0, 8);
+    const model = typeof session.model === 'string' ? session.model : undefined;
+    const platform = typeof session.platform === 'string' ? session.platform : undefined;
+    const meta = {
+        id: sessionId,
+        shortId,
+        agent: 'hermes',
+        timestamp,
+        project: platform,
+        filePath,
+        version: model,
+        topic,
+        messageCount: messageCount || (typeof session.message_count === 'number' ? session.message_count : undefined),
+    };
+    return { meta, content: userTexts.join('\n') };
+}
+/** Extract plain text from a Hermes message content field (string or list of parts). */
+function extractHermesMessageText(content) {
+    if (typeof content === 'string')
+        return content.trim();
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .map((part) => {
+        if (typeof part === 'string')
+            return part;
+        if (typeof part?.text === 'string')
+            return part.text;
+        return '';
+    })
+        .join('\n')
+        .trim();
+}
+/** Stream a Claude JSONL file and extract scan-level metadata (timestamp, cwd, topic, tokens). */
 async function scanClaudeSession(filePath) {
     const stream = fs.createReadStream(filePath, { encoding: 'utf-8' });
     const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
@@ -937,6 +1246,7 @@ async function scanClaudeSession(filePath) {
         contentText: userTexts.length > 0 ? userTexts.join('\n') : undefined,
     };
 }
+/** Stream a Codex JSONL file and extract scan-level metadata (session ID, cwd, topic, tokens). */
 async function scanCodexSession(filePath) {
     const stream = fs.createReadStream(filePath, { encoding: 'utf-8' });
     const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
@@ -1007,6 +1317,7 @@ async function scanCodexSession(filePath) {
         contentText: userTexts.length > 0 ? userTexts.join('\n') : undefined,
     };
 }
+/** Resolve the working directory for an OpenClaw agent from its workspace config. */
 function getOpenClawSessionCwd(agentId) {
     const workspace = agentId ? getOpenClawWorkspaceMap().get(agentId) : undefined;
     if (workspace)
@@ -1014,6 +1325,7 @@ function getOpenClawSessionCwd(agentId) {
     const configDir = AGENTS.openclaw.configDir;
     return safeRealpathSync(configDir) || configDir;
 }
+/** Build a cached map of OpenClaw agent ID to workspace path from openclaw.json. */
 function getOpenClawWorkspaceMap() {
     if (cachedOpenClawWorkspaces)
         return cachedOpenClawWorkspaces;
@@ -1040,6 +1352,7 @@ function getOpenClawWorkspaceMap() {
 // ---------------------------------------------------------------------------
 // Utilities
 // ---------------------------------------------------------------------------
+/** Read up to maxLines non-empty lines from the beginning of a file. */
 export function readFirstLines(filePath, maxLines) {
     return new Promise((resolve) => {
         const lines = [];
@@ -1058,41 +1371,11 @@ export function readFirstLines(filePath, maxLines) {
         rl.on('error', () => resolve(lines));
     });
 }
-/**
- * Walk a directory recursively for files with a given extension.
- */
-export function walkForFiles(dir, ext, limit) {
-    const results = [];
-    function walk(d, depth) {
-        if (depth > 5)
-            return;
-        let entries;
-        try {
-            entries = fs.readdirSync(d);
-        }
-        catch {
-            return;
-        }
-        for (const entry of entries) {
-            const full = path.join(d, entry);
-            const stat = safeStatSync(full);
-            if (!stat)
-                continue;
-            if (stat.isDirectory()) {
-                walk(full, depth + 1);
-            }
-            else if (entry.endsWith(ext)) {
-                results.push({ path: full, mtime: stat.mtimeMs });
-            }
-        }
-    }
-    walk(dir, 0);
-    results.sort((a, b) => b.mtime - a.mtime);
-    return results.slice(0, limit).map(r => r.path);
-}
+/** Compute the SHA-256 hex digest of a string. */
 function sha256(input) {
     return crypto.createHash('sha256').update(input).digest('hex');
 }
+/** Stat a path, returning null on any error. */
 function safeStatSync(p) {
     try {
         return fs.statSync(p);
@@ -1101,6 +1384,7 @@ function safeStatSync(p) {
         return null;
     }
 }
+/** Resolve a path to its real path, returning null on any error. */
 function safeRealpathSync(p) {
     try {
         return fs.realpathSync(p);
@@ -1109,6 +1393,7 @@ function safeRealpathSync(p) {
         return null;
     }
 }
+/** Extract meaningful user text from a Claude JSONL user event, skipping meta and local-command messages. */
 function extractClaudeUserText(parsed) {
     if (parsed.isMeta === true)
         return undefined;
@@ -1127,9 +1412,11 @@ function extractClaudeUserText(parsed) {
         return undefined;
     return text;
 }
+/** Check whether a message is a local-command wrapper rather than real user input. */
 function isLocalCommandMessage(text) {
     return /<local-command-caveat>|<bash-(input|stdout|stderr)>/i.test(text);
 }
+/** Sum all token usage fields from a Claude assistant message's usage object. */
 function getClaudeUsageTotal(usage) {
     if (!usage || typeof usage !== 'object')
         return null;
@@ -1140,6 +1427,7 @@ function getClaudeUsageTotal(usage) {
         usage.cache_read_input_tokens,
     ]);
 }
+/** Extract text from Codex message content blocks, filtering out system instructions for user messages. */
 function extractCodexMessageText(contentBlocks, role) {
     if (!Array.isArray(contentBlocks))
         return undefined;
@@ -1158,15 +1446,17 @@ function extractCodexMessageText(contentBlocks, role) {
     });
     return text || undefined;
 }
+/** Trim and normalize a version string, returning undefined for empty values. */
 function normalizeVersion(version) {
     const trimmed = version?.trim();
     return trimmed ? trimmed : undefined;
 }
+/** Extract the version number from a managed ~/.agents-system/versions/<agent>/<version>/... path. */
 function extractVersionFromManagedPath(agent, sourcePath) {
     if (!sourcePath)
         return undefined;
     const candidates = [sourcePath, safeRealpathSync(sourcePath) || ''];
-    const marker = `/.agents/versions/${agent}/`;
+    const marker = `/.agents-system/versions/${agent}/`;
     for (const candidate of candidates) {
         if (!candidate)
             continue;
@@ -1180,6 +1470,7 @@ function extractVersionFromManagedPath(agent, sourcePath) {
     }
     return undefined;
 }
+/** Resolve the current version of an agent CLI (symlink version or live CLI output, cached). */
 async function getCurrentAgentVersion(agent) {
     const cached = cachedAgentVersions.get(agent);
     if (cached)
@@ -1193,11 +1484,13 @@ async function getCurrentAgentVersion(agent) {
     cachedAgentVersions.set(agent, promise);
     return promise;
 }
+/** Resolve a session's version: embedded in file > extracted from managed path > current CLI version. */
 function resolveSessionVersion(agent, sourcePath, embeddedVersion, currentVersion) {
     return normalizeVersion(embeddedVersion)
         || extractVersionFromManagedPath(agent, sourcePath)
         || normalizeVersion(currentVersion);
 }
+/** Sum all token usage fields from a Codex total_token_usage object. */
 function getCodexTokenCount(totalTokenUsage) {
     if (!totalTokenUsage || typeof totalTokenUsage !== 'object')
         return null;
@@ -1208,6 +1501,7 @@ function getCodexTokenCount(totalTokenUsage) {
         totalTokenUsage.reasoning_output_tokens,
     ]);
 }
+/** Extract text from a Gemini message content field (string or array of parts). */
 function extractGeminiMessageText(content) {
     if (typeof content === 'string')
         return content.trim();
@@ -1225,6 +1519,7 @@ function extractGeminiMessageText(content) {
     }
     return '';
 }
+/** Extract the total token count from a Gemini message's tokens object. */
 function getGeminiTokenCount(tokens) {
     if (!tokens || typeof tokens !== 'object')
         return null;
@@ -1238,6 +1533,7 @@ function getGeminiTokenCount(tokens) {
         tokens.tool,
     ]);
 }
+/** Sum all numeric values in an array, returning null if none are valid numbers. */
 function sumKnownNumbers(values) {
     let total = 0;
     let found = false;
@@ -1252,6 +1548,7 @@ function sumKnownNumbers(values) {
 // ---------------------------------------------------------------------------
 // Time range parsing
 // ---------------------------------------------------------------------------
+/** Parse a time filter string (relative like '7d' or ISO timestamp) into epoch milliseconds. */
 export function parseTimeFilter(input) {
     const relativeMatch = input.match(/^(\d+)([mhdw])$/i);
     if (relativeMatch) {
@@ -1269,4 +1566,3 @@ export function parseTimeFilter(input) {
     const ts = new Date(input).getTime();
     return Number.isNaN(ts) ? 0 : ts;
 }
-//# sourceMappingURL=discover.js.map