@phnx-labs/agents-cli 1.22.21 → 1.22.23

package/dist/lib/session/db.js

@@ -26,7 +26,7 @@ const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/05-sessions.md calls the constant the source of truth). */
-export const SCHEMA_VERSION = 33;
+export const SCHEMA_VERSION = 34;
 /**
  * Bump to force `agents sessions backfill resources` to re-derive every
  * session's skill/slash-command tallies on its next run (resource_scan_ledger
@@ -268,7 +268,33 @@ CREATE TABLE IF NOT EXISTS resource_scan_ledger (
   indexed_at INTEGER NOT NULL,
   resource_count INTEGER NOT NULL
 );
+
+-- Behavioural facets per session, for "agents insights". Deliberately its own table
+-- and deliberately NOT tied to SCHEMA_VERSION: it is created by CREATE TABLE IF NOT
+-- EXISTS and keyed on (file_mtime_ms, file_size), so it self-heals after any future
+-- migration that flushes a ledger, and adding it costs the hot "sessions" table
+-- nothing. Populated lazily by the insights command, never by a normal scan --
+-- parsing every transcript is far too expensive for the common listing path.
+-- file_mtime_ms / file_size are NULLABLE because they are nullable on the sessions
+-- table too (a source with no statable file indexes them as NULL). NOT NULL here made
+-- a legitimate null-stat session throw a constraint error that took the whole batch
+-- transaction down with it.
+CREATE TABLE IF NOT EXISTS session_insights (
+  session_id TEXT PRIMARY KEY,
+  file_mtime_ms INTEGER,
+  file_size INTEGER,
+  extractor_version INTEGER NOT NULL,
+  computed_at INTEGER NOT NULL,
+  facets TEXT NOT NULL
+);
 `;
+/**
+ * Bumping this invalidates every cached facet row without touching the schema
+ * version, so a change to the extraction logic (a new metric, a corrected bucket)
+ * re-derives on the next `agents insights` instead of silently reporting stale
+ * numbers alongside fresh ones. Same role as RESOURCE_INDEX_VERSION.
+ */
+export const INSIGHTS_EXTRACTOR_VERSION = 3;
 let dbInstance = null;
 /**
  * Apply schema migrations from `fromVersion` → SCHEMA_VERSION. The new
@@ -753,6 +779,37 @@ function migrateSchema(db, fromVersion) {
         db.exec(`CREATE INDEX IF NOT EXISTS idx_sessions_account_key ON sessions(account_key)`);
         backfillClaudeAccounts(db);
     }
+    if (fromVersion < 34) {
+        // v33 -> v34: claude-opus-5 and claude-sonnet-5 were missing from the pricing
+        // table. `getModelPricing` matches on a dash-bounded prefix, so neither could fall
+        // back to its Claude 4 entry: both resolved to null and every session using them
+        // priced to $0 -- silently, because an unpriced model contributes nothing rather
+        // than raising. On one real index that was 526 sessions, 478 of them the current
+        // default model.
+        //
+        // Adding the prices alone fixes nothing already indexed: cost_usd is computed at
+        // scan time, and the scanner skips any transcript whose (file_mtime_ms, file_size)
+        // is unchanged. Nor can those rows be repaired in place -- the row stores
+        // token_count and output_tokens, not the uncached-input / cache-read / cache-write
+        // split the price table needs -- so the figure has to come from re-reading the
+        // transcript.
+        //
+        // Flush ONLY the affected transcripts, not the whole ledger. A blanket
+        // `DELETE FROM scan_ledger` (what v5 -> v6 did when cost was introduced) would
+        // re-parse every session on the next scan and break the contract the other
+        // migrations here are tested against: adding a column must not invalidate warm
+        // session ledgers. Scoping it to the rows that actually mispriced keeps every
+        // other ledger entry warm and still guarantees the numbers correct themselves.
+        db.exec(`
+      DELETE FROM scan_ledger
+      WHERE file_path IN (
+        SELECT file_path FROM sessions
+        WHERE cost_usd IS NULL
+          AND file_path IS NOT NULL AND file_path <> ''
+          AND (model LIKE 'claude-opus-5%' OR model LIKE 'claude-sonnet-5%')
+      );
+    `);
+    }
 }
 /**
  * Stamp `account_key` / `account_org` / `account` on every Claude row from its
@@ -2105,6 +2162,80 @@ export function countSessions(options = {}) {
     const row = db.prepare(sql).get(...params);
     return row ? row.n : 0;
 }
+/** What to group a usage rollup by. */
+/**
+ * Read cached facets for the given sessions, dropping any row that is stale.
+ *
+ * Staleness is decided in SQL against the session's own `file_mtime_ms` / `file_size`,
+ * the same pair the scanner maintains — so the cache cannot disagree with the index,
+ * `IS` rather than `=` so a source with no statable file — NULL on both sides — is a
+ * cache HIT rather than a permanent miss that re-parses it on every run.
+ */
+export function readSessionInsights(ids) {
+    const db = getDB();
+    const out = new Map();
+    if (ids.length === 0)
+        return out;
+    const CHUNK = 400; // chunk.length + 1 binds, well under SQLite's 999-variable limit
+    for (let i = 0; i < ids.length; i += CHUNK) {
+        const chunk = ids.slice(i, i + CHUNK);
+        const phs = chunk.map(() => '?').join(',');
+        const rows = db.prepare(`
+      SELECT si.session_id AS id, si.facets AS facets
+      FROM session_insights si
+      JOIN sessions s ON s.id = si.session_id
+      WHERE si.session_id IN (${phs})
+        AND si.extractor_version = ?
+        AND si.file_mtime_ms IS s.file_mtime_ms
+        AND si.file_size IS s.file_size
+    `).all(...chunk, INSIGHTS_EXTRACTOR_VERSION);
+        for (const row of rows) {
+            try {
+                out.set(row.id, JSON.parse(row.facets));
+            }
+            catch {
+                // A corrupt cache row is not a reason to fail the report; recompute it.
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Persist freshly computed facets against the stamp of the bytes actually parsed.
+ *
+ * The caller passes the stat it observed when it read the file. Re-reading the stamp
+ * from the sessions table inside this INSERT would race: a concurrent rescan between
+ * the parse and the write (the cold path flushes in batches, so the window is minutes
+ * wide, and this module treats concurrent access as a design assumption) stamps NEW
+ * bytes onto OLD facets — a permanent false cache hit until the file changes again.
+ * tool-index.ts sets the precedent: stat at parse time, carry the stamp into the write.
+ */
+export function writeSessionInsights(entries) {
+    if (entries.length === 0)
+        return;
+    const db = getDB();
+    const stmt = db.prepare(`
+    INSERT INTO session_insights
+      (session_id, file_mtime_ms, file_size, extractor_version, computed_at, facets)
+    VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT(session_id) DO UPDATE SET
+      file_mtime_ms = excluded.file_mtime_ms,
+      file_size = excluded.file_size,
+      extractor_version = excluded.extractor_version,
+      computed_at = excluded.computed_at,
+      facets = excluded.facets
+  `);
+    const now = Date.now();
+    db.transaction(() => {
+        for (const e of entries) {
+            stmt.run(e.id, e.fileMtimeMs, e.fileSize, INSIGHTS_EXTRACTOR_VERSION, now, JSON.stringify(e.facets));
+        }
+    })();
+}
+/** Drop every cached facet row. Backs `agents insights --refresh`. */
+export function clearSessionInsights() {
+    getDB().exec(`DELETE FROM session_insights`);
+}
 export function queryAffinityRollup(options) {
     const db = getDB();
     const where = [];

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

@@ -13,6 +13,9 @@ export interface FileChange {
     path: string;
     op: FileOp;
 }
+export declare const READ_TOOLS: Set<string>;
+export declare const WRITE_TOOLS: Set<string>;
+export declare const EDIT_TOOLS: Set<string>;
 /**
  * Path-shaped noise that must never surface as a session "change": shell
  * redirect tokens (`2>&1`), unexpanded env-var prefixes (`$WT/...`), dependency

package/dist/lib/session/digest.js

@@ -10,9 +10,9 @@
 import { bucketKey, classifyBashCommand } from './bash-command.js';
 // Tool vocab mirrors parse.ts / render.ts so classification matches what those
 // modules already recognize across Claude/Codex/others.
-const READ_TOOLS = new Set(['Read', 'read_file', 'view_file', 'cat_file', 'get_file']);
-const WRITE_TOOLS = new Set(['Write', 'write_file', 'create_file']);
-const EDIT_TOOLS = new Set(['Edit', 'edit_file', 'replace', 'patch', 'MultiEdit', 'apply_patch']);
+export const READ_TOOLS = new Set(['Read', 'read_file', 'view_file', 'cat_file', 'get_file']);
+export const WRITE_TOOLS = new Set(['Write', 'write_file', 'create_file', 'Create']);
+export const EDIT_TOOLS = new Set(['Edit', 'edit_file', 'replace', 'patch', 'MultiEdit', 'apply_patch']);
 /**
  * Path-shaped noise that must never surface as a session "change": shell
  * redirect tokens (`2>&1`), unexpanded env-var prefixes (`$WT/...`), dependency

package/dist/lib/session/discover.js

@@ -47,6 +47,8 @@ const HOME = os.homedir();
 const VERSIONS_ROOTS = [getHistoryDir(), getAgentsDir()];
 const RUSH_SESSIONS_DIR = path.join(HOME, '.rush', 'sessions');
 const HERMES_SESSIONS_DIR = path.join(HOME, '.hermes', 'sessions');
+/** Muse Code sessions: ~/.local/share/muse/sessions/YYYY/MM/DD/<uuid>/session.jsonl */
+const MUSE_SESSIONS_DIR = path.join(HOME, '.local', 'share', 'muse', 'sessions');
 /** How long OpenClaw channel/cron snapshots stay valid before we re-shell-out. */
 const OPENCLAW_TTL_MS = 60_000;
 const ACTIVE_APPEND_RESCAN_DEBOUNCE_MS = 5_000;
@@ -303,6 +305,7 @@ function dispatchAgentScan(agent, onProgress) {
         case 'droid': return scanDroidIncremental(onProgress);
         case 'grok': return scanGrokIncremental(onProgress);
         case 'cursor': return scanCursorIncremental(onProgress);
+        case 'muse': return scanMuseIncremental(onProgress);
         default: return Promise.resolve();
     }
 }
@@ -2274,6 +2277,171 @@ function readHermesMeta(filePath) {
     };
     return { meta, content: userTexts.join('\n') };
 }
+/**
+ * Muse Code stores one session per directory under
+ * ~/.local/share/muse/sessions/YYYY/MM/DD/<uuid>/session.jsonl (event-sourced
+ * JSONL). Walk the tree for session.jsonl files and index each one.
+ *
+ * Also scan version homes (`versions/muse/<v>/home/.local/share/muse/sessions`)
+ * so managed/isolated runs that rewrite HOME still show up in `agents sessions`.
+ */
+function scanMuseIncremental(onProgress) {
+    const roots = [];
+    if (fs.existsSync(MUSE_SESSIONS_DIR))
+        roots.push(MUSE_SESSIONS_DIR);
+    for (const root of VERSIONS_ROOTS) {
+        const versionsBase = path.join(root, 'versions', 'muse');
+        if (!fs.existsSync(versionsBase))
+            continue;
+        try {
+            for (const version of fs.readdirSync(versionsBase)) {
+                const dir = path.join(versionsBase, version, 'home', '.local', 'share', 'muse', 'sessions');
+                if (fs.existsSync(dir))
+                    roots.push(dir);
+            }
+        }
+        catch {
+            /* unreadable */
+        }
+    }
+    if (roots.length === 0)
+        return Promise.resolve();
+    const filePaths = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const ent of entries) {
+            const full = path.join(dir, ent.name);
+            if (ent.isDirectory()) {
+                // Skip subagent child sessions — nested under subagent/<id>/
+                if (ent.name === 'subagent')
+                    continue;
+                walk(full);
+            }
+            else if (ent.name === 'session.jsonl') {
+                filePaths.push(full);
+            }
+        }
+    };
+    for (const root of roots)
+        walk(root);
+    const changed = filterChangedFiles(filePaths);
+    if (changed.length === 0)
+        return Promise.resolve();
+    onProgress?.({ agent: 'muse', 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 = readMuseMeta(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: 'muse', parsed, total: changed.length });
+    }
+    upsertSessionsBatch(scanEntries);
+    recordScans(touched);
+    return Promise.resolve();
+}
+/** Parse a Muse session.jsonl for session metadata + first user prompt text. */
+function readMuseMeta(filePath) {
+    // Path shape: .../sessions/YYYY/MM/DD/<uuid>/session.jsonl
+    const sessionId = path.basename(path.dirname(filePath));
+    if (!/^[0-9a-f-]{36}$/i.test(sessionId))
+        return null;
+    let content;
+    try {
+        content = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    const userTexts = [];
+    let topic;
+    let messageCount = 0;
+    let model;
+    let project;
+    let firstTs;
+    let lastTs;
+    for (const line of content.split('\n')) {
+        if (!line.trim())
+            continue;
+        let raw;
+        try {
+            raw = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (typeof raw.recorded_at === 'number') {
+            const v = raw.recorded_at;
+            // Muse logs use microseconds; values < 1e14 are treated as milliseconds.
+            const ms = v > 1e14 ? Math.floor(v / 1000) : v;
+            const ts = new Date(ms).toISOString();
+            if (!firstTs)
+                firstTs = ts;
+            lastTs = ts;
+        }
+        const payloadType = raw.payload_type;
+        const payload = raw.payload;
+        if (payloadType === 'runtime.session.metadata') {
+            const record = payload?.record;
+            if (typeof record?.workspace_root === 'string')
+                project = record.workspace_root;
+        }
+        if (payloadType === 'runtime.command_intake.received') {
+            const cmd = payload?.record?.command;
+            if (cmd?.kind === 'turn_submit' && typeof cmd.prompt === 'string' && cmd.prompt.trim()) {
+                messageCount++;
+                userTexts.push(cmd.prompt.trim());
+                if (!topic)
+                    topic = extractSessionTopic(cmd.prompt.trim());
+            }
+        }
+        const event = payload?.event ?? payload;
+        if (event?.kind === 'assistant_message_committed' && typeof event.text === 'string') {
+            messageCount++;
+        }
+        if (event?.kind === 'model_request_configured' && typeof event.model === 'string') {
+            model = event.model;
+        }
+        if (typeof event?.model === 'string' && !model)
+            model = event.model;
+    }
+    const stat = safeStatSync(filePath);
+    const timestamp = lastTs
+        || firstTs
+        || (stat ? stat.mtime.toISOString() : new Date().toISOString());
+    const shortId = deriveShortId(sessionId);
+    const meta = {
+        id: sessionId,
+        shortId,
+        agent: 'muse',
+        timestamp,
+        project,
+        filePath,
+        model,
+        topic,
+        messageCount: messageCount || 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')

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

@@ -0,0 +1,126 @@
+/**
+ * Behavioural facets of a coding session, and the cross-session rollup built from them.
+ *
+ * This is the engine behind `agents insights`. It answers "how do you work" rather than
+ * "what did you spend" (`agents cost`) or "what shipped" (`agents output`), and it is
+ * the only surface that splits any of it by the account that produced the work.
+ *
+ * Everything here is a pure function of a parsed `SessionEvent[]`, so it is testable
+ * without a database and cheap to re-run. The expensive part is parsing the transcript,
+ * which is why results are cached per session in `session_insights` and recomputed only
+ * when the file's (mtime, size) changes — the same staleness contract as `scan_ledger`.
+ *
+ * Prior art: Claude Code's own `/insights`, which computes a comparable set from
+ * `~/.claude/projects` alone. Two deliberate differences:
+ *
+ *   - It sees ONE account's directory. This reads every indexed session, across every
+ *     Claude account and every other harness, and reports them apart.
+ *   - It collapses conversation branches before counting. agents-cli is file-per-session
+ *     throughout (`discover.ts` keys on the transcript's basename), so session counts
+ *     here will read slightly higher than `/insights` on the same machine. Reported as
+ *     the raw file count rather than quietly differing.
+ */
+import type { SessionEvent } from './types.js';
+/** Behavioural facets of one session. Serialized as JSON into `session_insights`. */
+export interface InsightFacets {
+    toolCounts: Record<string, number>;
+    /** Per-model assistant turn counts. `/insights` has no model dimension at all. */
+    models: Record<string, number>;
+    languages: Record<string, number>;
+    /** Slash commands the user invoked, by name. */
+    slashCommands: Record<string, number>;
+    errorCategories: Record<string, number>;
+    /** Times the user cut a turn short — the `interrupt` event from parse.ts. */
+    interruptions: number;
+    /** Seconds between an assistant's last event and the user's next message. */
+    responseGaps: number[];
+    /** Gaps excluded for exceeding the ceiling — reported, never silently dropped. */
+    gapsOverCeiling: number;
+    /**
+     * Lines in the BEFORE and AFTER text of every edit and write — "lines touched", not
+     * a diff. An Edit whose old_string is three unchanged context lines counts them in
+     * both; git counts them zero times. Measured against a real commit the added figure
+     * ran 19% high and the removed figure 475% high, so this must never be rendered as
+     * a diffstat. Computing a true delta needs a line-level diff per edit, which is a
+     * different feature.
+     */
+    linesTouchedBefore: number;
+    linesTouchedAfter: number;
+    /**
+     * Edit/write calls in a vocabulary we recognise. NOT a proxy for measurability:
+     * codex renames `apply_patch` to `Edit` but carries no line-bearing arguments, so it
+     * reports edit calls with zero lines. Callers decide "measurable" from the line
+     * totals themselves.
+     */
+    editingToolCalls: number;
+    filesCreated: number;
+    filesModified: number;
+    filesDeleted: number;
+    gitCommits: number;
+    gitPushes: number;
+    /**
+     * Tool calls that carried an actual command string to search. Not every harness
+     * populates one: the codex parser sets `command` for `exec_command` but not for
+     * plain `exec`, its dominant tool, so git activity is structurally invisible there.
+     * 0 means the commit counts are unmeasurable, not observed-zero.
+     */
+    shellCommandsSeen: number;
+    /** 24 slots, local time, indexed by hour of the user's messages. */
+    messageHours: number[];
+    userTurns: number;
+    assistantTurns: number;
+    toolCount: number;
+    errorCount: number;
+}
+/**
+ * Compute every behavioural facet of one session from its parsed events.
+ *
+ * Pure: no I/O, no clock, no filesystem. `timezoneOffsetMinutes` is injected rather
+ * than read from the environment so the hour histogram is deterministic in tests and
+ * can be re-bucketed for a different display timezone without re-parsing.
+ */
+export declare function computeInsightFacets(events: SessionEvent[], timezoneOffsetMinutes?: number): InsightFacets;
+/** Percentile of a numeric sample, nearest-rank. Returns 0 for an empty sample. */
+export declare function percentile(values: number[], p: number): number;
+/** Bucket response gaps for display. Returns every bucket, including empty ones. */
+export declare function bucketGaps(gaps: number[]): Array<{
+    bucket: string;
+    count: number;
+}>;
+/** A session's time span, for overlap detection. */
+export interface SessionSpan {
+    id: string;
+    accountKey: string;
+    startMs: number;
+    endMs: number;
+}
+/** How much work ran concurrently, and how much of it straddled two accounts. */
+export interface OverlapReport {
+    /** Pairs of sessions whose spans intersect. */
+    overlappingPairs: number;
+    /** Of those, pairs belonging to DIFFERENT accounts. */
+    crossAccountPairs: number;
+    /** Distinct sessions involved in any overlap. */
+    sessionsInvolved: number;
+}
+/**
+ * Detect concurrent sessions by interval intersection.
+ *
+ * This is the metric that makes the account split legible rather than academic: a
+ * cross-account overlap is `balanced` rotation actively running two orgs' quota at the
+ * same moment. `/insights` has a comparable "multi-clauding" count, but with one
+ * account it can only ever report the same-account case.
+ *
+ * Sweep in start order, keeping only spans that could still intersect, so this is
+ * O(n log n + pairs) rather than O(n^2) over ~3k sessions.
+ */
+export declare function detectOverlap(spans: SessionSpan[]): OverlapReport;
+/** Merge a session's facets into a running total. */
+export declare function mergeFacets(into: InsightFacets, add: InsightFacets): void;
+/** A fresh zeroed accumulator, for callers folding many sessions together. */
+export declare function newFacetAccumulator(): InsightFacets;
+/** Top-N entries of a count map, highest first, ties broken by name for determinism. */
+export declare function topEntries(counts: Record<string, number>, limit: number): Array<{
+    name: string;
+    count: number;
+}>;