@phnx-labs/agents-cli 1.20.92 → 1.20.93

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

@@ -0,0 +1,236 @@
+/**
+ * SQLite-backed usage read-model for `agents secrets`.
+ *
+ * A small local database at ~/.agents/secrets/secrets.db that records one
+ * value-free row for every secret lifecycle/access event a bundle accrues over
+ * its life — created, imported, exported, viewed, accessed (read for injection),
+ * unlocked. It is the queryable, per-bundle counterpart to the append-only
+ * ~/.agents/events.jsonl audit log: the SAME chokepoint (`emitSecretAudit`,
+ * lib/secrets/audit.ts) feeds both, and this store answers "how often / how
+ * recently / by whom was THIS bundle used?" without scanning the whole event
+ * stream. It is a DERIVED index fed off the real access flow — the way
+ * sessions.db indexes session metadata — never a second write path an operation
+ * has to remember to call.
+ *
+ * Contract, mirroring the audit log: NEVER a secret value. Only metadata — the
+ * bundle name, the event kind, key counts, the resolving agent/host, a status.
+ *
+ * Every write is best-effort: a failure here (missing runtime SQLite, a locked
+ * db, a read-only fs) is swallowed so usage telemetry can never break secret
+ * resolution. Set AGENTS_NO_USAGE_TRACK=1 to disable recording entirely (used by
+ * tests and by callers that must stay perfectly silent).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import Database from '../sqlite.js';
+import { getSecretsDbPath } from '../state.js';
+/** All event kinds, in the order `view` prints them. */
+export const SECRET_USAGE_EVENTS = [
+    'access',
+    'unlock',
+    'import',
+    'export',
+    'create',
+    'view',
+];
+/** Events older than this are pruned on open so the history table stays bounded. */
+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,
+  bundle TEXT NOT NULL,
+  event TEXT NOT NULL,
+  agent TEXT,
+  host TEXT,
+  source TEXT,
+  status TEXT,
+  key_count INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_usage_bundle ON usage_events(bundle);
+CREATE INDEX IF NOT EXISTS idx_usage_bundle_event ON usage_events(bundle, event);
+CREATE INDEX IF NOT EXISTS idx_usage_ts ON usage_events(ts DESC);
+`;
+// Cached handle keyed by the resolved path, so a test that redirects
+// AGENTS_SECRETS_DB to a fresh temp file transparently reopens instead of
+// reusing a stale handle pointed at the previous path.
+let cached = null;
+function emptyEvents() {
+    return {
+        access: { count: 0, last: null },
+        unlock: { count: 0, last: null },
+        import: { count: 0, last: null },
+        export: { count: 0, last: null },
+        create: { count: 0, last: null },
+        view: { count: 0, last: null },
+    };
+}
+/**
+ * Open (creating if needed) the usage DB, returning null on any failure so
+ * every caller degrades to a no-op rather than throwing into secret resolution.
+ */
+function open() {
+    const dbPath = getSecretsDbPath();
+    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 });
+        const db = new Database(dbPath);
+        // WAL + a busy timeout so concurrent agent runs writing usage rows don't
+        // fail each other under load; every write is still best-effort besides.
+        db.pragma('journal_mode = WAL');
+        db.pragma('busy_timeout = 2000');
+        db.exec(SCHEMA);
+        // Bounded retention: this is a usage history for operators, not a compliance
+        // log (that is events.jsonl). Prune once per open on a 90-day window.
+        try {
+            db.prepare(`DELETE FROM usage_events WHERE ts < ?`).run(new Date(Date.now() - EVENT_RETENTION_MS).toISOString());
+        }
+        catch { /* prune is best-effort */ }
+        cached = { path: dbPath, db };
+        return db;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Record one usage event. Best-effort and value-free — swallows every error and
+ * honors AGENTS_NO_USAGE_TRACK so telemetry never blocks or slows a read. Rows
+ * with an empty bundle name are ignored (usage is per-bundle by definition).
+ *
+ * This is called from ONE place only — `emitSecretAudit` (lib/secrets/audit.ts)
+ * — so every recorded event has already been written to the events.jsonl audit
+ * log through the same chokepoint. Do not call it from a command handler; emit
+ * the audit event instead.
+ */
+export function recordSecretUsage(p) {
+    if (process.env.AGENTS_NO_USAGE_TRACK)
+        return;
+    if (!p.bundle)
+        return;
+    const db = open();
+    if (!db)
+        return;
+    try {
+        db.prepare(`INSERT INTO usage_events (ts, bundle, event, agent, host, source, status, key_count)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(new Date().toISOString(), p.bundle, p.event, p.agent ?? null, p.host ?? null, p.source ?? null, p.status ?? 'success', p.keyCount ?? null);
+    }
+    catch {
+        // Telemetry must never break secret resolution.
+    }
+}
+function toSummary(bundle, rows, byAgent) {
+    const events = emptyEvents();
+    let total = 0;
+    let lastUsedAt = null;
+    let firstUsedAt = null;
+    for (const r of rows) {
+        if (r.event in events) {
+            const stat = events[r.event];
+            stat.count = r.n;
+            stat.last = r.last;
+        }
+        total += r.n;
+        if (r.last && (!lastUsedAt || r.last > lastUsedAt))
+            lastUsedAt = r.last;
+        if (r.first && (!firstUsedAt || r.first < firstUsedAt))
+            firstUsedAt = r.first;
+    }
+    return { bundle, total, events, lastUsedAt, firstUsedAt, byAgent };
+}
+/**
+ * Usage summary for one bundle, or undefined when nothing has ever been
+ * recorded (or the DB is unavailable). Never throws.
+ */
+export function getBundleUsage(bundle) {
+    const db = open();
+    if (!db)
+        return undefined;
+    try {
+        const rows = db
+            .prepare(`SELECT event, COUNT(*) AS n, MAX(ts) AS last, MIN(ts) AS first
+           FROM usage_events WHERE bundle = ? GROUP BY event`)
+            .all(bundle);
+        if (rows.length === 0)
+            return undefined;
+        const agents = db
+            .prepare(`SELECT agent, COUNT(*) AS n FROM usage_events
+           WHERE bundle = ? AND agent IS NOT NULL GROUP BY agent ORDER BY n DESC`)
+            .all(bundle);
+        return toSummary(bundle, rows, agents.map((a) => ({ agent: a.agent, count: a.n })));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Usage summaries for every bundle that has any recorded event, keyed by bundle
+ * name. Powers `secrets list --sort uses|used`. Empty map when the DB is
+ * unavailable or has no rows. Never throws.
+ */
+export function getAllBundleUsage() {
+    const out = new Map();
+    const db = open();
+    if (!db)
+        return out;
+    try {
+        const rows = db
+            .prepare(`SELECT bundle, event, COUNT(*) AS n, MAX(ts) AS last, MIN(ts) AS first
+           FROM usage_events GROUP BY bundle, event`)
+            .all();
+        const byBundle = new Map();
+        for (const r of rows) {
+            const list = byBundle.get(r.bundle) ?? [];
+            list.push(r);
+            byBundle.set(r.bundle, list);
+        }
+        for (const [bundle, list] of byBundle)
+            out.set(bundle, toSummary(bundle, list, []));
+        return out;
+    }
+    catch {
+        return out;
+    }
+}
+/**
+ * Recent events for the `secrets activity` timeline — one bundle when named,
+ * else across all bundles — newest first. Empty when the DB is unavailable.
+ * Never throws.
+ */
+export function getUsageHistory(bundle, limit = 20) {
+    const db = open();
+    if (!db)
+        return [];
+    try {
+        const sql = bundle
+            ? `SELECT ts, bundle, event, agent, host, source, status, key_count AS keyCount
+           FROM usage_events WHERE bundle = ? ORDER BY ts DESC, id DESC LIMIT ?`
+            : `SELECT ts, bundle, event, agent, host, source, status, key_count AS keyCount
+           FROM usage_events ORDER BY ts DESC, id DESC LIMIT ?`;
+        const rows = bundle
+            ? db.prepare(sql).all(bundle, limit)
+            : db.prepare(sql).all(limit);
+        return rows;
+    }
+    catch {
+        return [];
+    }
+}
+/** Close the cached handle. Used by tests between temp-db swaps. */
+export function closeSecretsUsageDb() {
+    if (cached) {
+        try {
+            cached.db.close();
+        }
+        catch { /* ignore */ }
+        cached = null;
+    }
+}

package/dist/lib/session/remote-active.d.ts

@@ -25,5 +25,9 @@ export interface RemoteActiveResult {
  * (from `--host`), fan out to exactly those. Otherwise sweep the registered,
  * online devices from `ag devices`, excluding this machine and any without an
  * address. Results from all peers run in parallel and are flattened.
+ * `opts.quiet` suppresses the per-device stderr line for callers that report
+ * skipped peers once, compactly, themselves.
  */
-export declare function gatherRemoteActive(hosts?: string[]): Promise<RemoteActiveResult>;
+export declare function gatherRemoteActive(hosts?: string[], opts?: {
+    quiet?: boolean;
+}): Promise<RemoteActiveResult>;

package/dist/lib/session/remote-active.js

@@ -56,13 +56,16 @@ export function parseRemoteActive(stdout, machine) {
  * (from `--host`), fan out to exactly those. Otherwise sweep the registered,
  * online devices from `ag devices`, excluding this machine and any without an
  * address. Results from all peers run in parallel and are flattened.
+ * `opts.quiet` suppresses the per-device stderr line for callers that report
+ * skipped peers once, compactly, themselves.
  */
-export async function gatherRemoteActive(hosts) {
+export async function gatherRemoteActive(hosts, opts) {
     const result = await gatherRemoteAgentsJson({
         args: ['sessions', '--active', '--json'],
         noFanoutEnv: NO_FANOUT_ENV,
         hosts,
         parse: parseRemoteActive,
+        quiet: opts?.quiet,
     });
     return { sessions: result.items, deviceCount: result.deviceCount };
 }

package/dist/lib/sqlite.js

@@ -14,11 +14,38 @@
 import { createRequire } from 'module';
 const isBun = typeof globalThis.Bun !== 'undefined';
 const require = createRequire(import.meta.url);
+// node:sqlite emits a process-level ExperimentalWarning the first time it loads.
+// The packaged CLI launches Node with --no-warnings=ExperimentalWarning, but a
+// direct `node dist/...` run (and vitest's subprocesses) does not, so the warning
+// would leak onto stderr and break any command whose --json output is asserted to
+// be clean. Suppress only that single warning for the duration of the load; every
+// other warning passes through untouched.
+function loadNodeSqlite() {
+    const original = process.emitWarning;
+    const filtered = ((warning, ...rest) => {
+        const name = warning instanceof Error
+            ? warning.name
+            : typeof rest[0] === 'string'
+                ? rest[0]
+                : rest[0]?.type;
+        const message = warning instanceof Error ? warning.message : warning;
+        if (name === 'ExperimentalWarning' && /SQLite/i.test(String(message ?? '')))
+            return;
+        original.call(process, warning, ...rest);
+    });
+    process.emitWarning = filtered;
+    try {
+        return require('node:sqlite');
+    }
+    finally {
+        process.emitWarning = original;
+    }
+}
 // Keep Node on createRequire() so Vitest doesn't try to prebundle the built-in
 // sqlite module as a userland package during test collection.
 const sqliteMod = isBun
     ? await import('bun:sqlite')
-    : require('node:sqlite');
+    : loadNodeSqlite();
 // bun:sqlite exports `Database`; node:sqlite exports `DatabaseSync`.
 const NativeDatabase = sqliteMod.Database
     ?? sqliteMod.DatabaseSync;

package/dist/lib/state.d.ts

@@ -98,6 +98,18 @@ export declare function getUserSubagentsDir(): string;
 export declare function getSystemWorkflowsDir(): string;
 export declare function getUserWorkflowsDir(): string;
 export declare function getUserSecretsDir(): string;
+/**
+ * Path to the secrets usage read-model database (~/.agents/secrets/secrets.db).
+ * Read at CALL time so a test can redirect it to a temp file via
+ * AGENTS_SECRETS_DB without racing the module-load capture of USER_SECRETS_DIR —
+ * mirrors the AGENTS_EVENTS_PATH / AGENTS_DEVICES_DIR escape hatches. Holds only
+ * value-free usage telemetry (which bundle was created/imported/exported/viewed/
+ * accessed/unlocked, when, by whom), never a secret value. It is a derived index
+ * fed FROM the emitSecretAudit chokepoint alongside the append-only
+ * ~/.agents/events.jsonl audit log — the same way sessions.db indexes session
+ * metadata off the real session flow — not a second write path.
+ */
+export declare function getSecretsDbPath(): string;
 export declare function getUserPromptcutsPath(): string;
 /** Canonical home anchor (HOME env override or os.homedir()). */
 export declare function getHomeDir(): string;

package/dist/lib/state.js

@@ -299,6 +299,20 @@ export function getUserSubagentsDir() { return USER_SUBAGENTS_DIR; }
 export function getSystemWorkflowsDir() { return SYSTEM_WORKFLOWS_DIR; }
 export function getUserWorkflowsDir() { return USER_WORKFLOWS_DIR; }
 export function getUserSecretsDir() { return USER_SECRETS_DIR; }
+/**
+ * Path to the secrets usage read-model database (~/.agents/secrets/secrets.db).
+ * Read at CALL time so a test can redirect it to a temp file via
+ * AGENTS_SECRETS_DB without racing the module-load capture of USER_SECRETS_DIR —
+ * mirrors the AGENTS_EVENTS_PATH / AGENTS_DEVICES_DIR escape hatches. Holds only
+ * value-free usage telemetry (which bundle was created/imported/exported/viewed/
+ * accessed/unlocked, when, by whom), never a secret value. It is a derived index
+ * fed FROM the emitSecretAudit chokepoint alongside the append-only
+ * ~/.agents/events.jsonl audit log — the same way sessions.db indexes session
+ * metadata off the real session flow — not a second write path.
+ */
+export function getSecretsDbPath() {
+    return process.env.AGENTS_SECRETS_DB ?? path.join(USER_SECRETS_DIR, 'secrets.db');
+}
 export function getUserPromptcutsPath() { return USER_PROMPTCUTS_FILE; }
 // ─── User operational path getters ────────────────────────────────────────────
 //

package/dist/lib/types.d.ts

@@ -873,10 +873,11 @@ export interface Meta {
     };
     /**
      * Owner/channel notification config for `agents send` / `agents notify`.
-     * `owner` is the default recipient for `agents notify` (channel + target).
-     * `transports` maps a user-facing channel name to the provider that actually
-     * delivers it — explicit, one provider per channel, no fallback. Omitted keys
-     * default to name-identity (channel `slack` -> provider `slack`).
+     * `owner` is the address expanded by `--to owner` and by `agents notify`
+     * (channel + target). `transports` maps a user-facing channel name to the
+     * provider that actually delivers it — explicit, one provider per channel,
+     * no fallback. Omitted keys default to name-identity (channel `slack` ->
+     * provider `slack`).
      */
     notify?: {
         owner?: {

package/dist/lib/versions.d.ts

@@ -464,6 +464,12 @@ export interface SyncResult {
     subagents: string[];
     plugins: string[];
     workflows: string[];
+    /**
+     * Project files the sync left alone because the workspace already has them
+     * (repo-relative). Reported once, grouped, by the command that rendered the
+     * sync — never one line per file from down here.
+     */
+    projectSkipped: string[];
 }
 /**
  * Enumerate the DotAgent repo names that resources can be scoped to:

package/dist/lib/versions.js

@@ -2420,7 +2420,7 @@ export function mergeRepoScopedSelections(repos, cwd = process.cwd()) {
  */
 export function syncResourcesToVersion(agent, version, selection, options = {}) {
     if (isAgentHardDeprecated(agent)) {
-        return { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [] };
+        return { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [], projectSkipped: [] };
     }
     const agentConfig = AGENTS[agent];
     const versionHome = getVersionHomePath(agent, version);
@@ -2431,7 +2431,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     // care about the ORIGINAL intent: a caller passing no selection means
     // "full sync; persist the staleness manifest after."
     const userPassedSelection = selection !== undefined;
-    const result = { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [] };
+    const result = { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [], projectSkipped: [] };
     const cwd = options.cwd || process.cwd();
     const projectAgentsDir = options.projectDir || getProjectAgentsDir(cwd);
     const userAgentsDir = getUserAgentsDir();
@@ -2499,7 +2499,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         }
     }
     if (projectAgentsDir) {
-        syncProjectResourcesToAgent(agent, version, projectAgentsDir);
+        result.projectSkipped = syncProjectResourcesToAgent(agent, version, projectAgentsDir).skipped;
     }
     // Fast guard: skip the entire sync when the caller requested a full sync and
     // nothing has changed since the last full sync. Pattern-derived selections
@@ -2508,7 +2508,9 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     if (!userPassedSelection && !options.force) {
         const manifest = loadManifest(agent, version);
         if (manifest && !isStale(manifest, agent, version, cwd)) {
-            return { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [] };
+            // Nothing synced, but the project sync above already ran — carry its
+            // skipped files out so the caller can still report them.
+            return { ...result };
         }
     }
     // Helper: remove a path (symlink or real) if it exists

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.92",
+  "version": "1.20.93",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",