@phnx-labs/agents-cli 1.20.17 → 1.20.19

package/dist/lib/secrets/linux.js

@@ -7,24 +7,21 @@
  * (common on server-class Linux — no graphical login means the keyring
  * passphrase never enters the daemon, so `secret-tool store` fails with
  * "Cannot create an item in a locked collection"), we transparently switch
- * to a file-based AES-256-GCM encrypted store under
- * `~/.agents/.cache/secrets/`. The encryption key is scrypt-derived from a
- * passphrase read from `AGENTS_SECRETS_PASSPHRASE` (preferred) or a TTY
- * prompt. The decision is cached per process; one stderr line is emitted
- * the first time the fallback activates.
+ * to the AES-256-GCM encrypted-file store in ./filestore.ts. The decision is
+ * cached per process; one stderr line is emitted the first time the fallback
+ * activates.
  *
  * Secrets stored via secret-tool use:
  *   service = "agents-cli"
  *   account = username
  *   item    = the secret identifier
- *
- * File-fallback layout: one `<item>.enc` JSON file per item, mode 0600.
  */
-import { spawnSync, execSync } from 'child_process';
-import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'crypto';
-import * as fs from 'fs';
+import { spawnSync } from 'child_process';
 import * as os from 'os';
-import * as path from 'path';
+import { fileStore, fileDir, fileStoreHasItems, machinePassphraseExists, _resetFileStoreForTest, } from './filestore.js';
+// Re-exported so existing importers (and tests) can keep reaching these via
+// './linux.js'. The implementations live in ./filestore.ts.
+export { encryptForFallback, decryptForFallback, fileBackend, } from './filestore.js';
 const SERVICE = 'agents-cli';
 // ---------- secret-tool availability ----------
 function secretToolAvailable() {
@@ -38,12 +35,6 @@ let isAvailable = false;
 // ---------- file fallback state ----------
 let useFileFallback = false;
 let warnedFallback = false;
-let warnedAutoPassphrase = false;
-let fileDirOverride = null;
-let cachedPassphrase = null;
-function fileDir() {
-    return fileDirOverride ?? path.join(os.homedir(), '.agents', '.cache', 'secrets');
-}
 function activateFileFallback() {
     if (useFileFallback)
         return;
@@ -57,18 +48,6 @@ function isLockedCollectionError(stderr) {
     return /locked collection/i.test(stderr) ||
         /Prompt was dismissed/i.test(stderr);
 }
-/** True if the fallback dir has any committed encrypted items. Means an
- *  earlier process (this one or another) already routed writes to the file
- *  store, so this process must keep reading/writing from the same store —
- *  otherwise `list` / `get` / `has` would silently miss them. */
-function fileFallbackPreviouslyActivated() {
-    try {
-        return fs.readdirSync(fileDir()).some((e) => e.endsWith('.enc'));
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * Decide which backend a given op should use. Activates file fallback if
  * `secret-tool` is missing and `AGENTS_SECRETS_PASSPHRASE` is set, OR if a
@@ -79,7 +58,7 @@ function fileFallbackPreviouslyActivated() {
 function preflight() {
     if (useFileFallback)
         return 'file';
-    if (fileFallbackPreviouslyActivated()) {
+    if (fileStoreHasItems()) {
         activateFileFallback();
         return 'file';
     }
@@ -107,233 +86,12 @@ function preflight() {
     }
     return 'secret-tool';
 }
-// ---------- passphrase ----------
-function readPassphraseFromTty() {
-    const fd = fs.openSync('/dev/tty', 'r+');
-    let echoDisabled = false;
-    try {
-        fs.writeSync(fd, 'Enter AGENTS_SECRETS_PASSPHRASE: ');
-        try {
-            execSync('stty -echo < /dev/tty', { stdio: 'ignore' });
-            echoDisabled = true;
-        }
-        catch {
-            // stty not available — fall through; passphrase will echo. Better
-            // than refusing to function.
-        }
-        let pass = '';
-        const buf = Buffer.alloc(1);
-        while (true) {
-            const n = fs.readSync(fd, buf, 0, 1, null);
-            if (n === 0)
-                break;
-            const ch = buf.toString('utf8', 0, n);
-            if (ch === '\n' || ch === '\r')
-                break;
-            pass += ch;
-        }
-        return pass;
-    }
-    finally {
-        if (echoDisabled) {
-            try {
-                execSync('stty echo < /dev/tty', { stdio: 'ignore' });
-            }
-            catch { /* best effort */ }
-        }
-        try {
-            fs.writeSync(fd, '\n');
-        }
-        catch { /* best effort */ }
-        fs.closeSync(fd);
-    }
-}
-/** Path of the auto-provisioned machine-local passphrase. Lives alongside the
- *  encrypted items but is never itself an item (no `.enc` suffix, so it's
- *  excluded from list/has/get and from fileFallbackPreviouslyActivated). */
-function passphraseFilePath() {
-    return path.join(fileDir(), '.passphrase');
-}
-/** True if a machine-local passphrase has already been provisioned. */
-function machinePassphraseExists() {
-    try {
-        return fs.readFileSync(passphraseFilePath(), 'utf8').trim().length > 0;
-    }
-    catch {
-        return false;
-    }
-}
-function readMachinePassphrase() {
-    try {
-        const p = fs.readFileSync(passphraseFilePath(), 'utf8').trim();
-        return p.length > 0 ? p : null;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Provision (or read back) a stable machine-local passphrase for the encrypted
- * file store, so `agents secrets` works out of the box on a headless box where
- * the keyring is locked and no AGENTS_SECRETS_PASSPHRASE is set.
- *
- * Security model: this is encryption-at-rest with the key held in a 0600 file —
- * the same posture as an SSH private key, and identical to the common
- * "export AGENTS_SECRETS_PASSPHRASE=… in ~/.zshenv (chmod 600)" workaround. The
- * keyring (key in a daemon's locked memory) is stronger but is unavailable
- * without a graphical/unlocked session. For an off-disk key, set
- * AGENTS_SECRETS_PASSPHRASE (it always takes precedence) or unlock the keyring.
- */
-function provisionMachinePassphrase() {
-    const existing = readMachinePassphrase();
-    if (existing)
-        return existing;
-    ensureFileDir();
-    const generated = randomBytes(32).toString('base64');
-    const fp = passphraseFilePath();
-    try {
-        // wx: fail if a concurrent process created it first (then we read theirs).
-        fs.writeFileSync(fp, generated, { mode: 0o600, flag: 'wx' });
-    }
-    catch {
-        const raced = readMachinePassphrase();
-        if (raced)
-            return raced;
-        throw new Error(`Failed to provision machine-local passphrase at ${fp}.`);
-    }
-    if (!warnedAutoPassphrase) {
-        warnedAutoPassphrase = true;
-        process.stderr.write(`[agents] keyring locked and no AGENTS_SECRETS_PASSPHRASE set; provisioned a ` +
-            `machine-local passphrase at ${fp} (mode 0600). Set AGENTS_SECRETS_PASSPHRASE ` +
-            `for a key held off disk.\n`);
-    }
-    return generated;
-}
-function getPassphrase() {
-    if (cachedPassphrase !== null)
-        return cachedPassphrase;
-    const env = process.env.AGENTS_SECRETS_PASSPHRASE;
-    if (env && env.length > 0) {
-        cachedPassphrase = env;
-        return env;
-    }
-    // A previously-provisioned machine-local passphrase is this machine's stable
-    // file-store key — prefer it for both interactive and headless runs so they
-    // always agree (a TTY run won't re-prompt once the file exists).
-    const onDisk = readMachinePassphrase();
-    if (onDisk) {
-        cachedPassphrase = onDisk;
-        return onDisk;
-    }
-    // First run, no env, no provisioned key: prompt when interactive, otherwise
-    // (headless — the reported bug) auto-provision instead of hard-failing.
-    if (process.stdin.isTTY) {
-        const p = readPassphraseFromTty();
-        if (!p)
-            throw new Error('No passphrase entered.');
-        cachedPassphrase = p;
-        return p;
-    }
-    cachedPassphrase = provisionMachinePassphrase();
-    return cachedPassphrase;
-}
-function deriveKey(passphrase, salt) {
-    return scryptSync(passphrase, salt, 32);
-}
-/** Encrypt plaintext under a passphrase using AES-256-GCM with a random
- *  scrypt salt and a random 96-bit IV. Exported for tests. */
-export function encryptForFallback(plaintext, passphrase) {
-    const salt = randomBytes(16);
-    const iv = randomBytes(12);
-    const key = deriveKey(passphrase, salt);
-    const cipher = createCipheriv('aes-256-gcm', key, iv);
-    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
-    return {
-        salt: salt.toString('hex'),
-        iv: iv.toString('hex'),
-        authTag: cipher.getAuthTag().toString('hex'),
-        ciphertext: ciphertext.toString('hex'),
-    };
-}
-/** Decrypt an EncFile under a passphrase. Throws on wrong key or tampered
- *  ciphertext (auth-tag mismatch). Exported for tests. */
-export function decryptForFallback(enc, passphrase) {
-    const salt = Buffer.from(enc.salt, 'hex');
-    const iv = Buffer.from(enc.iv, 'hex');
-    const authTag = Buffer.from(enc.authTag, 'hex');
-    const ciphertext = Buffer.from(enc.ciphertext, 'hex');
-    const key = deriveKey(passphrase, salt);
-    const decipher = createDecipheriv('aes-256-gcm', key, iv);
-    decipher.setAuthTag(authTag);
-    const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
-    return plaintext.toString('utf8');
-}
-// ---------- file backend ----------
-function fileFor(item) {
-    return path.join(fileDir(), `${item}.enc`);
-}
-function ensureFileDir() {
-    fs.mkdirSync(fileDir(), { recursive: true, mode: 0o700 });
-}
-function fileHas(item) {
-    return fs.existsSync(fileFor(item));
-}
-function fileGet(item) {
-    const fp = fileFor(item);
-    if (!fs.existsSync(fp)) {
-        throw new Error(`Secret '${item}' not found in encrypted store.`);
-    }
-    const raw = fs.readFileSync(fp, 'utf8');
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        throw new Error(`Encrypted secret file ${fp} is corrupt (not valid JSON).`);
-    }
-    try {
-        return decryptForFallback(parsed, getPassphrase());
-    }
-    catch {
-        throw new Error(`Failed to decrypt '${item}'. Wrong AGENTS_SECRETS_PASSPHRASE or tampered file.`);
-    }
-}
-function fileSet(item, value) {
-    ensureFileDir();
-    const enc = encryptForFallback(value, getPassphrase());
-    fs.writeFileSync(fileFor(item), JSON.stringify(enc), { mode: 0o600 });
-}
-function fileDelete(item) {
-    const fp = fileFor(item);
-    if (!fs.existsSync(fp))
-        return true; // idempotent, matches secret-tool clear
-    fs.unlinkSync(fp);
-    return true;
-}
-function fileList(prefix) {
-    const dir = fileDir();
-    if (!fs.existsSync(dir))
-        return [];
-    return fs.readdirSync(dir)
-        .filter((f) => f.endsWith('.enc'))
-        .map((f) => f.slice(0, -'.enc'.length))
-        .filter((name) => name.startsWith(prefix));
-}
-/** File-only KeychainBackend (exported for tests; the public surface uses
- *  the secret-tool-with-fallback `linuxBackend` below). */
-export const fileBackend = {
-    has: fileHas,
-    get: fileGet,
-    set: fileSet,
-    delete: fileDelete,
-    list: fileList,
-};
 // ---------- secret-tool ops with fallback ----------
 /** secret-tool lookup attributes:
  *   service=agents-cli account=<user> item=<itemName> */
 export function hasSecretToolToken(item) {
     if (preflight() === 'file')
-        return fileHas(item);
+        return fileStore.has(item);
     const user = os.userInfo().username;
     const result = spawnSync('secret-tool', [
         'lookup',
@@ -347,13 +105,13 @@ export function hasSecretToolToken(item) {
     const stderr = result.stderr?.toString() ?? '';
     if (isLockedCollectionError(stderr)) {
         activateFileFallback();
-        return fileHas(item);
+        return fileStore.has(item);
     }
     return false;
 }
 export function getSecretToolToken(item) {
     if (preflight() === 'file')
-        return fileGet(item);
+        return fileStore.get(item);
     const user = os.userInfo().username;
     const result = spawnSync('secret-tool', [
         'lookup',
@@ -370,7 +128,7 @@ export function getSecretToolToken(item) {
     const stderr = result.stderr?.toString() ?? '';
     if (isLockedCollectionError(stderr)) {
         activateFileFallback();
-        return fileGet(item);
+        return fileStore.get(item);
     }
     throw new Error(`Secret '${item}' not found in keyring.`);
 }
@@ -378,7 +136,7 @@ export function setSecretToolToken(item, value) {
     if (!value || !value.trim())
         throw new Error('Secret value is empty.');
     if (preflight() === 'file')
-        return fileSet(item, value);
+        return fileStore.set(item, value);
     const user = os.userInfo().username;
     const label = `agents-cli: ${item}`;
     const result = spawnSync('secret-tool', [
@@ -393,7 +151,7 @@ export function setSecretToolToken(item, value) {
     const stderr = result.stderr?.toString().trim() ?? '';
     if (isLockedCollectionError(stderr)) {
         activateFileFallback();
-        fileSet(item, value);
+        fileStore.set(item, value);
         return;
     }
     throw new Error(`Failed to store secret '${item}': ${stderr || 'unknown error'}\n` +
@@ -402,7 +160,7 @@ export function setSecretToolToken(item, value) {
 }
 export function deleteSecretToolToken(item) {
     if (preflight() === 'file')
-        return fileDelete(item);
+        return fileStore.delete(item);
     const user = os.userInfo().username;
     const result = spawnSync('secret-tool', [
         'clear',
@@ -415,7 +173,7 @@ export function deleteSecretToolToken(item) {
     const stderr = result.stderr?.toString() ?? '';
     if (isLockedCollectionError(stderr)) {
         activateFileFallback();
-        return fileDelete(item);
+        return fileStore.delete(item);
     }
     // secret-tool clear returns 0 whether the item existed or not.
     // A non-zero exit that isn't a locked-collection error is a real failure;
@@ -456,7 +214,7 @@ export function parseSecretToolItems(output, prefix) {
  */
 export function listSecretToolItems(prefix) {
     if (preflight() === 'file')
-        return fileList(prefix);
+        return fileStore.list(prefix);
     const result = spawnSync('secret-tool', [
         'search',
         '--all',
@@ -466,7 +224,7 @@ export function listSecretToolItems(prefix) {
         const stderr = result.stderr?.toString() ?? '';
         if (isLockedCollectionError(stderr)) {
             activateFileFallback();
-            return fileList(prefix);
+            return fileStore.list(prefix);
         }
         return [];
     }
@@ -495,13 +253,12 @@ export const linuxBackend = {
     },
 };
 /** Test-only: reset module state so independent test cases don't bleed
- *  passphrase / fallback decisions across each other. */
+ *  passphrase / fallback decisions across each other. File-store state (file
+ *  dir + cached passphrase) lives in ./filestore.ts and is reset there. */
 export function _resetForTest(opts = {}) {
-    fileDirOverride = opts.fileDir ?? null;
+    _resetFileStoreForTest({ fileDir: opts.fileDir ?? null, passphrase: opts.passphrase ?? null });
     useFileFallback = opts.forceFileFallback ?? false;
     warnedFallback = false;
-    warnedAutoPassphrase = false;
-    cachedPassphrase = opts.passphrase ?? null;
     checkedAvailability = false;
     isAvailable = false;
 }

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

@@ -23,6 +23,8 @@ export interface SessionRow {
     label: string | null;
     message_count: number | null;
     token_count: number | null;
+    cost_usd: number | null;
+    duration_ms: number | null;
     file_path: string;
     file_mtime_ms: number | null;
     file_size: number | null;
@@ -50,6 +52,12 @@ export interface QueryOptions {
     excludeTeamOrigin?: boolean;
     /** Keep only team-origin rows (for hidden-count queries). */
     onlyTeamOrigin?: boolean;
+    /**
+     * Column to order by, all descending. 'timestamp' (default) sorts newest
+     * first; 'cost' and 'duration' put the priciest / longest sessions on top,
+     * with NULLs sorted last so unpriced rows never crowd out real data.
+     */
+    sortBy?: 'timestamp' | 'cost' | 'duration';
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
 export declare function getDB(): Database.Database;
@@ -114,6 +122,38 @@ export declare function syncLabels(labelMap: Map<string, string | null>): number
 export declare function querySessions(options?: QueryOptions): SessionMeta[];
 /** Count sessions matching the given filter options. */
 export declare function countSessions(options?: QueryOptions): number;
+/** One grouped row in a cost/duration rollup. */
+export interface UsageRollupRow {
+    /** Grouping key value: the agent id, project name, or ISO date (YYYY-MM-DD). */
+    key: string;
+    costUsd: number;
+    durationMs: number;
+    sessionCount: number;
+    tokenCount: number;
+}
+/** What to group a usage rollup by. */
+export type UsageRollupGroup = 'agent' | 'project' | 'day';
+/**
+ * Aggregate cost / duration / tokens across sessions, grouped by agent,
+ * project, or calendar day. Honors the same filter shape as querySessions
+ * (agent, since/until, team-origin) so `agents cost --since 7d --by day`
+ * lines up with what `agents sessions` would list. Ordered by cost desc.
+ */
+export declare function queryUsageRollup(options: QueryOptions & {
+    groupBy: UsageRollupGroup;
+}): UsageRollupRow[];
+/** A session with its cost, for the top-N-by-cost listing. */
+export interface TopCostSession {
+    meta: SessionMeta;
+    costUsd: number;
+    durationMs: number;
+}
+/**
+ * Return the N most expensive sessions (cost_usd DESC, NULLs excluded),
+ * honoring the same filter shape as querySessions. Drops rows whose JSONL
+ * vanished, mirroring querySessions' liveness filter.
+ */
+export declare function topSessionsByCost(n: number, options?: QueryOptions): TopCostSession[];
 /** 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. */

package/dist/lib/session/db.js

@@ -13,7 +13,7 @@ import { getSessionsDir, getSessionsDbPath } from '../state.js';
 const SESSIONS_DIR = getSessionsDir();
 const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. */
-const SCHEMA_VERSION = 5;
+const SCHEMA_VERSION = 6;
 /**
  * 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`
@@ -53,6 +53,8 @@ CREATE TABLE IF NOT EXISTS sessions (
   label TEXT,
   message_count INTEGER,
   token_count INTEGER,
+  cost_usd REAL,
+  duration_ms INTEGER,
   file_path TEXT NOT NULL,
   file_mtime_ms INTEGER,
   file_size INTEGER,
@@ -141,6 +143,19 @@ function migrateSchema(db, fromVersion) {
         // repopulate under canonical keys.
         db.exec(`DELETE FROM scan_ledger;`);
     }
+    if (fromVersion < 6) {
+        // v5 → v6: cost ($) and wall-clock duration are now computed at scan time
+        // from raw per-model token usage. Add the columns and force a full rescan
+        // so every existing session gets its cost_usd / duration_ms populated.
+        const cols = db.prepare(`PRAGMA table_info(sessions)`).all();
+        if (!cols.some(c => c.name === 'cost_usd')) {
+            db.exec(`ALTER TABLE sessions ADD COLUMN cost_usd REAL`);
+        }
+        if (!cols.some(c => c.name === 'duration_ms')) {
+            db.exec(`ALTER TABLE sessions ADD COLUMN duration_ms INTEGER`);
+        }
+        db.exec(`DELETE FROM scan_ledger;`);
+    }
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
 export function getDB() {
@@ -350,10 +365,12 @@ const upsertSessionStmt = (db) => db.prepare(`
   INSERT INTO sessions (
     id, short_id, agent, version, account, timestamp,
     project, cwd, git_branch, topic, label, message_count, token_count,
+    cost_usd, duration_ms,
     file_path, file_mtime_ms, file_size, scanned_at, is_team_origin
   ) VALUES (
     @id, @short_id, @agent, @version, @account, @timestamp,
     @project, @cwd, @git_branch, @topic, @label, @message_count, @token_count,
+    @cost_usd, @duration_ms,
     @file_path, @file_mtime_ms, @file_size, @scanned_at, @is_team_origin
   )
   ON CONFLICT(id) DO UPDATE SET
@@ -369,6 +386,8 @@ const upsertSessionStmt = (db) => db.prepare(`
     label = excluded.label,
     message_count = excluded.message_count,
     token_count = excluded.token_count,
+    cost_usd = excluded.cost_usd,
+    duration_ms = excluded.duration_ms,
     file_path = excluded.file_path,
     file_mtime_ms = excluded.file_mtime_ms,
     file_size = excluded.file_size,
@@ -409,6 +428,8 @@ export function upsertSession(meta, content, scan) {
         label: meta.label ?? null,
         message_count: meta.messageCount ?? null,
         token_count: meta.tokenCount ?? null,
+        cost_usd: meta.costUsd ?? null,
+        duration_ms: meta.durationMs ?? null,
         file_path: meta.filePath,
         file_mtime_ms: scan?.fileMtimeMs ?? null,
         file_size: scan?.fileSize ?? null,
@@ -482,6 +503,8 @@ export function upsertSessionsBatch(entries) {
                 label: meta.label ?? null,
                 message_count: meta.messageCount ?? null,
                 token_count: meta.tokenCount ?? null,
+                cost_usd: meta.costUsd ?? null,
+                duration_ms: meta.durationMs ?? null,
                 file_path: meta.filePath,
                 file_mtime_ms: scan?.fileMtimeMs ?? null,
                 file_size: scan?.fileSize ?? null,
@@ -548,6 +571,8 @@ function rowToMeta(row) {
         gitBranch: row.git_branch ?? undefined,
         messageCount: row.message_count ?? undefined,
         tokenCount: row.token_count ?? undefined,
+        costUsd: row.cost_usd ?? undefined,
+        durationMs: row.duration_ms ?? undefined,
         version: row.version ?? undefined,
         account: row.account ?? undefined,
         topic: row.topic ?? undefined,
@@ -611,7 +636,14 @@ export function querySessions(options = {}) {
     const limitClause = options.limit
         ? `LIMIT ${Math.max(1, Math.floor(options.limit)) + 16}`
         : '';
-    const sql = `SELECT * FROM sessions ${clause} ORDER BY timestamp DESC ${limitClause}`;
+    // NULLs last so unpriced / duration-less rows never crowd out real data when
+    // sorting by cost or duration. timestamp is never null (NOT NULL column).
+    const orderClause = options.sortBy === 'cost'
+        ? 'ORDER BY cost_usd IS NULL, cost_usd DESC, timestamp DESC'
+        : options.sortBy === 'duration'
+            ? 'ORDER BY duration_ms IS NULL, duration_ms DESC, timestamp DESC'
+            : 'ORDER BY timestamp DESC';
+    const sql = `SELECT * FROM sessions ${clause} ${orderClause} ${limitClause}`;
     const rows = db.prepare(sql).all(...params);
     // Belt-and-suspenders: drop rows whose JSONL no longer exists on disk. The
     // authoritative fix is to keep file_path in sync (see updateSessionFilePaths
@@ -631,6 +663,56 @@ export function countSessions(options = {}) {
     const row = db.prepare(sql).get(...params);
     return row ? row.n : 0;
 }
+/**
+ * Aggregate cost / duration / tokens across sessions, grouped by agent,
+ * project, or calendar day. Honors the same filter shape as querySessions
+ * (agent, since/until, team-origin) so `agents cost --since 7d --by day`
+ * lines up with what `agents sessions` would list. Ordered by cost desc.
+ */
+export function queryUsageRollup(options) {
+    const db = getDB();
+    const { clause, params } = buildSessionWhere(options);
+    const keyExpr = options.groupBy === 'agent'
+        ? 'agent'
+        : options.groupBy === 'project'
+            ? `IFNULL(NULLIF(project, ''), '(no project)')`
+            // ISO timestamps are lexicographically date-sortable; the date is the
+            // first 10 chars (YYYY-MM-DD).
+            : `substr(timestamp, 1, 10)`;
+    const sql = `
+    SELECT
+      ${keyExpr} AS key,
+      IFNULL(SUM(cost_usd), 0) AS costUsd,
+      IFNULL(SUM(duration_ms), 0) AS durationMs,
+      COUNT(*) AS sessionCount,
+      IFNULL(SUM(token_count), 0) AS tokenCount
+    FROM sessions
+    ${clause}
+    GROUP BY key
+    ORDER BY costUsd DESC, key ASC
+  `;
+    return db.prepare(sql).all(...params);
+}
+/**
+ * Return the N most expensive sessions (cost_usd DESC, NULLs excluded),
+ * honoring the same filter shape as querySessions. Drops rows whose JSONL
+ * vanished, mirroring querySessions' liveness filter.
+ */
+export function topSessionsByCost(n, options = {}) {
+    const db = getDB();
+    const { clause, params } = buildSessionWhere(options);
+    const whereCost = clause ? `${clause} AND cost_usd IS NOT NULL` : 'WHERE cost_usd IS NOT NULL';
+    const limit = Math.max(1, Math.floor(n));
+    // Over-fetch a small buffer to survive the on-disk liveness filter below.
+    const sql = `SELECT * FROM sessions ${whereCost} ORDER BY cost_usd DESC, timestamp DESC LIMIT ${limit + 16}`;
+    const rows = db.prepare(sql).all(...params);
+    const live = rows.filter(r => !r.file_path || fs.existsSync(r.file_path));
+    return live.slice(0, limit).map(r => ({
+        meta: rowToMeta(r),
+        costUsd: r.cost_usd ?? 0,
+        durationMs: r.duration_ms ?? 0,
+    }));
+}
 /** Return the set of all file paths currently tracked in the sessions table. */
 export function getAllFilePaths() {
     const db = getDB();

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

@@ -25,6 +25,8 @@ export interface DiscoverOptions {
     excludeTeamOrigin?: boolean;
     /** Keep only team-spawned sessions (used for hidden-count queries). */
     onlyTeamOrigin?: boolean;
+    /** Column to order results by (all descending): 'timestamp' (default), 'cost', or 'duration'. */
+    sortBy?: 'timestamp' | 'cost' | 'duration';
     /** Called as each agent makes parsing progress. Totals count only files that need re-parsing (cache misses). */
     onProgress?: (progress: ScanProgress) => void;
 }