@phnx-labs/agents-cli 1.21.1 → 1.21.3

package/dist/lib/analytics/recipes.js

@@ -0,0 +1,316 @@
+import Database from '../sqlite.js';
+import { getSessionsDbPath } from '../state.js';
+import { topNamesByKind, kindMix, countUsage, listUsageKindsWithData, } from './usage-db.js';
+export function trendsWindow(days) {
+    const d = Number.isFinite(days) && days > 0 ? days : 7;
+    const since = new Date(Date.now() - d * 24 * 60 * 60 * 1000);
+    return { days: d, sinceIso: since.toISOString() };
+}
+function openSessions() {
+    try {
+        const db = new Database(getSessionsDbPath());
+        db.pragma('busy_timeout = 2000');
+        return db;
+    }
+    catch {
+        return null;
+    }
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    if (sorted.length === 1)
+        return sorted[0];
+    const rank = (p / 100) * (sorted.length - 1);
+    const lo = Math.floor(rank);
+    const hi = Math.ceil(rank);
+    if (lo === hi)
+        return sorted[lo];
+    const frac = rank - lo;
+    return sorted[lo] * (1 - frac) + sorted[hi] * frac;
+}
+export function recipeHarnessMix(win) {
+    const db = openSessions();
+    const id = 'harness-mix';
+    const title = 'Harness mix';
+    if (!db)
+        return { id, title, store: 'sessions', rows: [], empty: true };
+    try {
+        const rows = db.prepare(`SELECT agent AS name, COUNT(*) AS n
+         FROM sessions WHERE timestamp >= ?
+         GROUP BY agent ORDER BY n DESC`).all(win.sinceIso);
+        return {
+            id,
+            title,
+            store: 'sessions',
+            rows: rows.map((r) => ({ harness: r.name, sessions: r.n })),
+            empty: rows.length === 0,
+        };
+    }
+    catch {
+        return { id, title, store: 'sessions', rows: [], empty: true };
+    }
+    finally {
+        try {
+            db.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+export function recipeModelMix(win) {
+    const db = openSessions();
+    const id = 'model-mix';
+    const title = 'Model mix';
+    if (!db)
+        return { id, title, store: 'sessions', rows: [], empty: true };
+    try {
+        const rows = db.prepare(`SELECT COALESCE(NULLIF(TRIM(model), ''), '(unrecorded)') AS name, COUNT(*) AS n
+         FROM sessions WHERE timestamp >= ?
+         GROUP BY 1 ORDER BY n DESC LIMIT 25`).all(win.sinceIso);
+        return {
+            id,
+            title,
+            store: 'sessions',
+            rows: rows.map((r) => ({ model: r.name, sessions: r.n })),
+            empty: rows.length === 0,
+        };
+    }
+    catch {
+        return { id, title, store: 'sessions', rows: [], empty: true };
+    }
+    finally {
+        try {
+            db.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+export function recipeToolsPerSession(win) {
+    const db = openSessions();
+    const id = 'tools-per-session';
+    const title = 'Tools per session';
+    if (!db)
+        return { id, title, store: 'sessions', rows: [], empty: true };
+    try {
+        const cols = db.prepare(`PRAGMA table_info(sessions)`).all();
+        if (!cols.some((c) => c.name === 'tool_call_count')) {
+            return { id, title, store: 'sessions', rows: [], empty: true };
+        }
+        const byAgent = db.prepare(`SELECT agent, tool_call_count AS n
+         FROM sessions
+        WHERE timestamp >= ? AND tool_call_count IS NOT NULL`).all(win.sinceIso);
+        if (byAgent.length === 0)
+            return { id, title, store: 'sessions', rows: [], empty: true };
+        const groups = new Map();
+        const all = [];
+        for (const r of byAgent) {
+            all.push(r.n);
+            const list = groups.get(r.agent) ?? [];
+            list.push(r.n);
+            groups.set(r.agent, list);
+        }
+        const roll = (label, vals) => {
+            const sorted = [...vals].sort((a, b) => a - b);
+            const sum = sorted.reduce((a, b) => a + b, 0);
+            return {
+                scope: label,
+                n: sorted.length,
+                avg: Math.round(sum / sorted.length),
+                p50: Math.round(percentile(sorted, 50)),
+                p99: Math.round(percentile(sorted, 99)),
+            };
+        };
+        const rows = [roll('(all)', all)];
+        for (const [agent, vals] of [...groups.entries()].sort((a, b) => b[1].length - a[1].length)) {
+            rows.push(roll(agent, vals));
+        }
+        return { id, title, store: 'sessions', rows, empty: false };
+    }
+    catch {
+        return { id, title, store: 'sessions', rows: [], empty: true };
+    }
+    finally {
+        try {
+            db.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+export function recipeTokenRatio(win) {
+    const db = openSessions();
+    const id = 'token-ratio';
+    const title = 'Token read→write ratio';
+    if (!db)
+        return { id, title, store: 'sessions', rows: [], empty: true };
+    try {
+        const rows = db.prepare(`SELECT agent,
+              COUNT(*) AS sessions,
+              IFNULL(SUM(token_count), 0) AS tokenIn,
+              IFNULL(SUM(output_tokens), 0) AS tokenOut
+         FROM sessions
+        WHERE timestamp >= ?
+          AND (token_count IS NOT NULL OR output_tokens IS NOT NULL)
+        GROUP BY agent
+        ORDER BY sessions DESC`).all(win.sinceIso);
+        if (rows.length === 0)
+            return { id, title, store: 'sessions', rows: [], empty: true };
+        const totalIn = rows.reduce((a, r) => a + r.tokenIn, 0);
+        const totalOut = rows.reduce((a, r) => a + r.tokenOut, 0);
+        const totalSessions = rows.reduce((a, r) => a + r.sessions, 0);
+        const fmt = (inn, out) => (out > 0 ? (inn / out).toFixed(2) : out === 0 && inn > 0 ? '∞' : '—');
+        const outRows = [{
+                scope: '(all)',
+                sessions: totalSessions,
+                token_in: totalIn,
+                token_out: totalOut,
+                ratio: fmt(totalIn, totalOut),
+                avg_in: totalSessions ? Math.round(totalIn / totalSessions) : 0,
+                avg_out: totalSessions ? Math.round(totalOut / totalSessions) : 0,
+            }];
+        for (const r of rows) {
+            outRows.push({
+                scope: r.agent,
+                sessions: r.sessions,
+                token_in: r.tokenIn,
+                token_out: r.tokenOut,
+                ratio: fmt(r.tokenIn, r.tokenOut),
+                avg_in: Math.round(r.tokenIn / r.sessions),
+                avg_out: Math.round(r.tokenOut / r.sessions),
+            });
+        }
+        return { id, title, store: 'sessions', rows: outRows, empty: false };
+    }
+    catch {
+        return { id, title, store: 'sessions', rows: [], empty: true };
+    }
+    finally {
+        try {
+            db.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+export function recipeSessionVolume(win) {
+    const db = openSessions();
+    const id = 'session-volume';
+    const title = 'Session volume';
+    if (!db)
+        return { id, title, store: 'sessions', rows: [], empty: true };
+    try {
+        const rows = db.prepare(`SELECT COALESCE(NULLIF(TRIM(machine), ''), '(unknown)') AS machine,
+              COUNT(*) AS sessions,
+              IFNULL(SUM(duration_ms), 0) AS durationMs
+         FROM sessions WHERE timestamp >= ?
+         GROUP BY 1 ORDER BY sessions DESC`).all(win.sinceIso);
+        return {
+            id,
+            title,
+            store: 'sessions',
+            rows: rows.map((r) => ({
+                machine: r.machine,
+                sessions: r.sessions,
+                duration_min: Math.round(r.durationMs / 60000),
+            })),
+            empty: rows.length === 0,
+        };
+    }
+    catch {
+        return { id, title, store: 'sessions', rows: [], empty: true };
+    }
+    finally {
+        try {
+            db.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+export function recipeSecretsHot(win) {
+    const id = 'secrets-hot';
+    const title = 'Hottest secrets';
+    const rows = topNamesByKind('secret', win.sinceIso, 15);
+    return {
+        id,
+        title,
+        store: 'usage',
+        rows: rows.map((r) => ({ bundle: r.name, accesses: r.n, last: r.last })),
+        empty: rows.length === 0,
+    };
+}
+export function recipeBrowserActivity(win) {
+    const id = 'browser-activity';
+    const title = 'Browser activity';
+    const rows = topNamesByKind('browser', win.sinceIso, 15);
+    return {
+        id,
+        title,
+        store: 'usage',
+        rows: rows.map((r) => ({ profile: r.name, events: r.n, last: r.last })),
+        empty: rows.length === 0,
+    };
+}
+export function recipeResourceMix(win) {
+    const id = 'resource-mix';
+    const title = 'Resource usage mix';
+    const rows = kindMix(win.sinceIso);
+    return {
+        id,
+        title,
+        store: 'usage',
+        rows: rows.map((r) => ({ kind: r.kind, events: r.n })),
+        empty: rows.length < 2,
+    };
+}
+export const RECIPE_IDS = [
+    'harness-mix',
+    'model-mix',
+    'tools-per-session',
+    'token-ratio',
+    'session-volume',
+    'secrets-hot',
+    'browser-activity',
+    'resource-mix',
+];
+const RUNNERS = {
+    'harness-mix': recipeHarnessMix,
+    'model-mix': recipeModelMix,
+    'tools-per-session': recipeToolsPerSession,
+    'token-ratio': recipeTokenRatio,
+    'session-volume': recipeSessionVolume,
+    'secrets-hot': recipeSecretsHot,
+    'browser-activity': recipeBrowserActivity,
+    'resource-mix': recipeResourceMix,
+};
+export function runRecipe(id, win) {
+    return RUNNERS[id](win);
+}
+export function listRecipes() {
+    const win = trendsWindow(7);
+    return RECIPE_IDS.map((id) => {
+        const s = RUNNERS[id](win);
+        return { id, title: s.title, store: s.store };
+    });
+}
+export function hasSessionsInWindow(win) {
+    const db = openSessions();
+    if (!db)
+        return false;
+    try {
+        const row = db.prepare(`SELECT 1 AS ok FROM sessions WHERE timestamp >= ? LIMIT 1`).get(win.sinceIso);
+        return Boolean(row);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        try {
+            db.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+export function usageKindsPresent(win) {
+    return listUsageKindsWithData(win.sinceIso);
+}
+export function usageEventCount(kind, win) {
+    return countUsage({ kind, sinceIso: win.sinceIso });
+}

package/dist/lib/analytics/usage-db.d.ts

@@ -0,0 +1,84 @@
+export type UsageKind = 'secret' | 'agent' | 'skill' | 'plugin' | 'browser' | 'computer';
+export declare const USAGE_KINDS: readonly UsageKind[];
+export interface RecordUsageParams {
+    kind: UsageKind;
+    name: string;
+    event: string;
+    agent?: string;
+    sessionId?: string;
+    machine?: string;
+    actor?: string;
+    source?: string;
+    status?: 'success' | 'error' | string;
+    meta?: Record<string, unknown>;
+    ts?: string;
+}
+export interface UsageEventRow {
+    ts: string;
+    kind: UsageKind;
+    name: string;
+    event: string;
+    agent: string | null;
+    sessionId: string | null;
+    machine: string | null;
+    actor: string | null;
+    source: string | null;
+    status: string | null;
+    metaJson: string | null;
+}
+export declare function recordUsage(p: RecordUsageParams): void;
+export declare function usageDbPath(): string;
+export declare function analyticsDir(): string;
+export declare function listUsageKindsWithData(sinceIso: string): UsageKind[];
+export declare function countUsage(opts: {
+    kind?: UsageKind;
+    sinceIso: string;
+    name?: string;
+    event?: string;
+}): number;
+export declare function queryUsage(opts: {
+    kind?: UsageKind;
+    name?: string;
+    event?: string;
+    sinceIso: string;
+    limit?: number;
+}): UsageEventRow[];
+export interface NameCountRow {
+    name: string;
+    n: number;
+    last: string | null;
+}
+export declare function topNamesByKind(kind: UsageKind, sinceIso: string, limit?: number): NameCountRow[];
+export interface KindCountRow {
+    kind: string;
+    n: number;
+}
+export declare function kindMix(sinceIso: string): KindCountRow[];
+export declare function getSecretBundleRollup(bundle: string): Array<{
+    event: string;
+    n: number;
+    last: string | null;
+    first: string | null;
+}>;
+export declare function getSecretBundleAgents(bundle: string): Array<{
+    agent: string;
+    n: number;
+}>;
+export declare function getAllSecretBundleRollups(): Array<{
+    name: string;
+    event: string;
+    n: number;
+    last: string | null;
+    first: string | null;
+}>;
+export declare function getSecretHistory(bundle: string | undefined, limit?: number): Array<{
+    ts: string;
+    bundle: string;
+    event: string;
+    agent: string | null;
+    host: string | null;
+    source: string | null;
+    status: string | null;
+    keyCount: number | null;
+}>;
+export declare function closeUsageDb(): void;

package/dist/lib/analytics/usage-db.js

@@ -0,0 +1,301 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import Database from '../sqlite.js';
+import { getUsageDbPath, getSecretsDbPath, getAnalyticsDir } from '../state.js';
+import { localMachineId } from '../session/origin-machine.js';
+export const USAGE_KINDS = [
+    'secret',
+    'agent',
+    'skill',
+    'plugin',
+    'browser',
+    'computer',
+];
+const EVENT_RETENTION_MS = 90 * 24 * 60 * 60 * 1000;
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS usage_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  name TEXT NOT NULL,
+  event TEXT NOT NULL,
+  agent TEXT,
+  session_id TEXT,
+  machine TEXT,
+  actor TEXT,
+  source TEXT,
+  status TEXT,
+  meta_json TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_analytics_usage_ts ON usage_events(ts DESC);
+CREATE INDEX IF NOT EXISTS idx_analytics_usage_kind_ts ON usage_events(kind, ts DESC);
+CREATE INDEX IF NOT EXISTS idx_analytics_usage_kind_name ON usage_events(kind, name);
+CREATE INDEX IF NOT EXISTS idx_analytics_usage_kind_event ON usage_events(kind, event);
+CREATE INDEX IF NOT EXISTS idx_analytics_usage_machine_ts ON usage_events(machine, ts DESC);
+CREATE INDEX IF NOT EXISTS idx_analytics_usage_session ON usage_events(session_id);
+CREATE TABLE IF NOT EXISTS meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`;
+let cached = null;
+function isDisabled() {
+    const v = process.env.AGENTS_NO_USAGE_TRACK;
+    return v === '1' || v === 'true';
+}
+function open() {
+    if (isDisabled())
+        return null;
+    const dbPath = getUsageDbPath();
+    if (cached && cached.path === dbPath)
+        return cached.db;
+    if (cached) {
+        try {
+            cached.db.close();
+        }
+        catch { /* ignore */ }
+        cached = null;
+    }
+    try {
+        fs.mkdirSync(path.dirname(dbPath), { recursive: true, mode: 0o700 });
+        const db = new Database(dbPath);
+        db.pragma('journal_mode = WAL');
+        db.pragma('busy_timeout = 2000');
+        db.exec(SCHEMA);
+        try {
+            db.prepare(`DELETE FROM usage_events WHERE ts < ?`).run(new Date(Date.now() - EVENT_RETENTION_MS).toISOString());
+        }
+        catch { /* prune best-effort */ }
+        migrateSecretsUsageOnce(db);
+        cached = { path: dbPath, db };
+        return db;
+    }
+    catch {
+        return null;
+    }
+}
+function migrateSecretsUsageOnce(db) {
+    try {
+        const done = db.prepare(`SELECT value FROM meta WHERE key = 'migrate_secrets_v1'`).get();
+        if (done?.value === '1')
+            return;
+        const secretsPath = getSecretsDbPath();
+        if (fs.existsSync(secretsPath)) {
+            const legacy = new Database(secretsPath);
+            try {
+                const rows = legacy.prepare(`SELECT ts, bundle, event, agent, host, source, status, key_count FROM usage_events`).all();
+                const insert = db.prepare(`INSERT INTO usage_events (ts, kind, name, event, agent, session_id, machine, actor, source, status, meta_json)
+           VALUES (?, 'secret', ?, ?, ?, NULL, ?, NULL, ?, ?, ?)`);
+                const machine = localMachineId();
+                const txn = db.transaction((items) => {
+                    for (const r of items) {
+                        if (!r.bundle)
+                            continue;
+                        const meta = r.key_count != null ? JSON.stringify({ keyCount: r.key_count, host: r.host }) : (r.host ? JSON.stringify({ host: r.host }) : null);
+                        insert.run(r.ts, r.bundle, r.event, r.agent, machine, r.source, r.status, meta);
+                    }
+                });
+                txn(rows);
+            }
+            finally {
+                try {
+                    legacy.close();
+                }
+                catch { /* ignore */ }
+            }
+        }
+        db.prepare(`INSERT OR REPLACE INTO meta(key, value) VALUES ('migrate_secrets_v1', '1')`).run();
+    }
+    catch {
+        /* migrate is best-effort */
+    }
+}
+export function recordUsage(p) {
+    if (isDisabled())
+        return;
+    if (!p.kind || !p.name || !p.event)
+        return;
+    const db = open();
+    if (!db)
+        return;
+    try {
+        db.prepare(`INSERT INTO usage_events (ts, kind, name, event, agent, session_id, machine, actor, source, status, meta_json)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(p.ts ?? new Date().toISOString(), p.kind, p.name, p.event, p.agent ?? null, p.sessionId ?? null, p.machine ?? localMachineId(), p.actor ?? null, p.source ?? null, p.status ?? 'success', p.meta != null ? JSON.stringify(p.meta) : null);
+    }
+    catch {
+        /* telemetry must never break callers */
+    }
+}
+export function usageDbPath() {
+    return getUsageDbPath();
+}
+export function analyticsDir() {
+    return getAnalyticsDir();
+}
+export function listUsageKindsWithData(sinceIso) {
+    const db = open();
+    if (!db)
+        return [];
+    try {
+        const rows = db.prepare(`SELECT DISTINCT kind FROM usage_events WHERE ts >= ?`).all(sinceIso);
+        return rows.map((r) => r.kind).filter((k) => USAGE_KINDS.includes(k));
+    }
+    catch {
+        return [];
+    }
+}
+export function countUsage(opts) {
+    const db = open();
+    if (!db)
+        return 0;
+    try {
+        const clauses = ['ts >= ?'];
+        const args = [opts.sinceIso];
+        if (opts.kind) {
+            clauses.push('kind = ?');
+            args.push(opts.kind);
+        }
+        if (opts.name) {
+            clauses.push('name = ?');
+            args.push(opts.name);
+        }
+        if (opts.event) {
+            clauses.push('event = ?');
+            args.push(opts.event);
+        }
+        const row = db.prepare(`SELECT COUNT(*) AS n FROM usage_events WHERE ${clauses.join(' AND ')}`).get(...args);
+        return row?.n ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+export function queryUsage(opts) {
+    const db = open();
+    if (!db)
+        return [];
+    try {
+        const clauses = ['ts >= ?'];
+        const args = [opts.sinceIso];
+        if (opts.kind) {
+            clauses.push('kind = ?');
+            args.push(opts.kind);
+        }
+        if (opts.name) {
+            clauses.push('name = ?');
+            args.push(opts.name);
+        }
+        if (opts.event) {
+            clauses.push('event = ?');
+            args.push(opts.event);
+        }
+        const limit = opts.limit && opts.limit > 0 ? opts.limit : 100;
+        args.push(limit);
+        const rows = db.prepare(`SELECT ts, kind, name, event, agent, session_id AS sessionId, machine, actor, source, status, meta_json AS metaJson
+         FROM usage_events WHERE ${clauses.join(' AND ')}
+         ORDER BY ts DESC, id DESC LIMIT ?`).all(...args);
+        return rows;
+    }
+    catch {
+        return [];
+    }
+}
+export function topNamesByKind(kind, sinceIso, limit = 20) {
+    const db = open();
+    if (!db)
+        return [];
+    try {
+        return db.prepare(`SELECT name, COUNT(*) AS n, MAX(ts) AS last
+         FROM usage_events WHERE kind = ? AND ts >= ?
+         GROUP BY name ORDER BY n DESC LIMIT ?`).all(kind, sinceIso, limit);
+    }
+    catch {
+        return [];
+    }
+}
+export function kindMix(sinceIso) {
+    const db = open();
+    if (!db)
+        return [];
+    try {
+        return db.prepare(`SELECT kind, COUNT(*) AS n FROM usage_events WHERE ts >= ? GROUP BY kind ORDER BY n DESC`).all(sinceIso);
+    }
+    catch {
+        return [];
+    }
+}
+export function getSecretBundleRollup(bundle) {
+    const db = open();
+    if (!db)
+        return [];
+    try {
+        return db.prepare(`SELECT event, COUNT(*) AS n, MAX(ts) AS last, MIN(ts) AS first
+         FROM usage_events WHERE kind = 'secret' AND name = ? GROUP BY event`).all(bundle);
+    }
+    catch {
+        return [];
+    }
+}
+export function getSecretBundleAgents(bundle) {
+    const db = open();
+    if (!db)
+        return [];
+    try {
+        return db.prepare(`SELECT agent, COUNT(*) AS n FROM usage_events
+         WHERE kind = 'secret' AND name = ? AND agent IS NOT NULL
+         GROUP BY agent ORDER BY n DESC`).all(bundle);
+    }
+    catch {
+        return [];
+    }
+}
+export function getAllSecretBundleRollups() {
+    const db = open();
+    if (!db)
+        return [];
+    try {
+        return db.prepare(`SELECT name, event, COUNT(*) AS n, MAX(ts) AS last, MIN(ts) AS first
+         FROM usage_events WHERE kind = 'secret' GROUP BY name, event`).all();
+    }
+    catch {
+        return [];
+    }
+}
+export function getSecretHistory(bundle, limit = 20) {
+    const db = open();
+    if (!db)
+        return [];
+    try {
+        const sql = bundle
+            ? `SELECT ts, name AS bundle, event, agent, source, status, meta_json
+           FROM usage_events WHERE kind = 'secret' AND name = ? ORDER BY ts DESC, id DESC LIMIT ?`
+            : `SELECT ts, name AS bundle, event, agent, source, status, meta_json
+           FROM usage_events WHERE kind = 'secret' ORDER BY ts DESC, id DESC LIMIT ?`;
+        const rows = (bundle ? db.prepare(sql).all(bundle, limit) : db.prepare(sql).all(limit));
+        return rows.map((r) => {
+            let host = null;
+            let keyCount = null;
+            if (r.meta_json) {
+                try {
+                    const m = JSON.parse(r.meta_json);
+                    host = m.host ?? null;
+                    keyCount = typeof m.keyCount === 'number' ? m.keyCount : null;
+                }
+                catch { /* ignore */ }
+            }
+            return { ts: r.ts, bundle: r.bundle, event: r.event, agent: r.agent, host, source: r.source, status: r.status, keyCount };
+        });
+    }
+    catch {
+        return [];
+    }
+}
+export function closeUsageDb() {
+    if (cached) {
+        try {
+            cached.db.close();
+        }
+        catch { /* ignore */ }
+        cached = null;
+    }
+}