@phnx-labs/agents-cli 1.21.1 → 1.21.2

package/dist/lib/analytics/recipes.d.ts

@@ -0,0 +1,32 @@
+import { type UsageKind } from './usage-db.js';
+export interface TrendsWindow {
+    days: number;
+    sinceIso: string;
+}
+export interface RecipeSection {
+    id: string;
+    title: string;
+    store: 'sessions' | 'usage';
+    rows: Array<Record<string, string | number | null>>;
+    empty?: boolean;
+}
+export declare function trendsWindow(days: number): TrendsWindow;
+export declare function recipeHarnessMix(win: TrendsWindow): RecipeSection;
+export declare function recipeModelMix(win: TrendsWindow): RecipeSection;
+export declare function recipeToolsPerSession(win: TrendsWindow): RecipeSection;
+export declare function recipeTokenRatio(win: TrendsWindow): RecipeSection;
+export declare function recipeSessionVolume(win: TrendsWindow): RecipeSection;
+export declare function recipeSecretsHot(win: TrendsWindow): RecipeSection;
+export declare function recipeBrowserActivity(win: TrendsWindow): RecipeSection;
+export declare function recipeResourceMix(win: TrendsWindow): RecipeSection;
+export type RecipeId = 'harness-mix' | 'model-mix' | 'tools-per-session' | 'token-ratio' | 'session-volume' | 'secrets-hot' | 'browser-activity' | 'resource-mix';
+export declare const RECIPE_IDS: readonly RecipeId[];
+export declare function runRecipe(id: RecipeId, win: TrendsWindow): RecipeSection;
+export declare function listRecipes(): Array<{
+    id: RecipeId;
+    title: string;
+    store: 'sessions' | 'usage';
+}>;
+export declare function hasSessionsInWindow(win: TrendsWindow): boolean;
+export declare function usageKindsPresent(win: TrendsWindow): UsageKind[];
+export declare function usageEventCount(kind: UsageKind, win: TrendsWindow): number;

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;