@phnx-labs/agents-cli 1.20.91 → 1.20.93

package/dist/lib/secrets/audit.js

@@ -1,16 +1,23 @@
 /**
- * Canonical audit emitter for `agents secrets` value access and unlock grants.
+ * Canonical audit emitter for every `agents secrets` lifecycle/access event.
  *
- * Every path that reads a secret VALUE or grants an unlock funnels its audit
- * through here, so the operational event stream — `agents events`, backed by the
- * append-only `~/.agents/events.jsonl` audit log — carries a uniform, value-free
- * provenance record: bundle, key NAMES, the resolving agent/harness identity,
- * operation, source, status. The ts / host / session / caller fields are filled
- * in by `emit()` itself. The secret VALUE is never part of the payload; this
- * helper only ever receives metadata, and `emit()`'s `sanitizePayload` is a
- * second redaction layer.
+ * This is the ONE write path for secret events. Every path that creates,
+ * imports, exports, views, reads a VALUE from, or unlocks a bundle funnels its
+ * audit through here, so the operational event stream — `agents events`, backed
+ * by the append-only `~/.agents/events.jsonl` audit log — carries a uniform,
+ * value-free provenance record: bundle, key NAMES, the resolving agent/harness
+ * identity, operation, source, status. The ts / host / session / caller fields
+ * are filled in by `emit()` itself. The secret VALUE is never part of the
+ * payload; this helper only ever receives metadata, and `emit()`'s
+ * `sanitizePayload` is a second redaction layer.
  *
- * Two event types, both audit-level and non-milestone (so they surface in
+ * The same call also mirrors the event into the per-bundle usage read-model DB
+ * (`~/.agents/secrets/secrets.db`, lib/secrets/usage-db.ts) so `secrets view` /
+ * `list` / `activity` can answer "how often / how recently / by whom was this
+ * bundle used?" without scanning the whole event stream — a DERIVED index fed
+ * off this chokepoint, not a second write path a caller has to remember.
+ *
+ * The event vocabulary, all audit-level and non-milestone (so they surface in
  * `agents events` and the persisted audit trail, but are NOT required in the
  * curated `agents activity` / `agents feed` surfaces):
  *  - `secrets.get`      — a value was READ (exec inject, export, `view --reveal`,
@@ -19,8 +26,27 @@
  *  - `secrets.unlocked` — a bundle was GRANTED into the secrets broker / durable
  *                         session by `agents secrets unlock`, then readable
  *                         prompt-free for the grant TTL.
+ *  - `secrets.create`   — a new bundle was created.
+ *  - `secrets.import`   — keys were imported into a bundle (file / ssh / 1password).
+ *  - `secrets.export`   — a bundle's values were exported (file / shell / ssh /
+ *                         1password). Exporting also READS the values, so the
+ *                         underlying resolve emits its own `secrets.get`.
+ *  - `secrets.view`     — a bundle's (masked) metadata was inspected via `view`.
  */
 import { emit } from '../events.js';
+import { recordSecretUsage } from './usage-db.js';
+/**
+ * Map each audit event onto the usage-DB kind it is counted as. `secrets.get` is
+ * the injection/read access; the rest map 1:1 to their lifecycle kind.
+ */
+const USAGE_KIND = {
+    'secrets.get': 'access',
+    'secrets.unlocked': 'unlock',
+    'secrets.create': 'create',
+    'secrets.import': 'import',
+    'secrets.export': 'export',
+    'secrets.view': 'view',
+};
 /**
  * The agent/harness identity to attribute a secret access to. Explicit callers
  * (the bundle reader knows the scope it resolved under) win; otherwise fall back
@@ -53,4 +79,21 @@ export function emitSecretAudit(p) {
         ...(p.ttlMs !== undefined ? { ttlMs: p.ttlMs } : {}),
         ...(p.error !== undefined ? { error: p.error } : {}),
     });
+    // Mirror the event into the per-bundle usage read-model so `secrets view` /
+    // `list` / `activity` can report frequency and recency without scanning the
+    // whole event stream. Fed off THIS chokepoint alongside the events.jsonl
+    // write, never a second write path. Per-bundle only — a raw `secrets get
+    // <item>` has no bundle, so it stays in the events.jsonl audit but is not
+    // counted as bundle usage. Best-effort inside usage-db (swallows errors).
+    if (p.bundle) {
+        recordSecretUsage({
+            bundle: p.bundle,
+            event: USAGE_KIND[p.event],
+            agent,
+            host: p.host,
+            source: p.source,
+            status: p.status,
+            keyCount: p.keyCount,
+        });
+    }
 }

package/dist/lib/secrets/list-filter.d.ts

@@ -79,14 +79,29 @@ export interface FilterContext {
 }
 /** Does this bundle satisfy every set axis? Pure. */
 export declare function bundleMatchesFilter(b: SecretsBundle, f: SecretsListFilter, ctx: FilterContext): boolean;
-/** Sort fields for `--sort`. `name` is the default and matches `listBundles()`. */
-export declare const SORT_FIELDS: readonly ["name", "used", "created", "updated", "expiry"];
+/** Sort fields for `--sort`. `name` is the default and matches `listBundles()`.
+ * `used` is most-recently-used first and `uses` is most-frequently-accessed
+ * first; both read the value-free usage read-model (lib/secrets/usage-db.ts). */
+export declare const SORT_FIELDS: readonly ["name", "used", "uses", "created", "updated", "expiry"];
 export type SortField = typeof SORT_FIELDS[number];
+/**
+ * The two value-free usage facts `--sort used|uses` needs, keyed by bundle name.
+ * Kept as a minimal shape (not the full BundleUsageSummary) so this module stays
+ * pure and unit-testable without opening the SQLite read-model.
+ */
+export interface BundleUsageHint {
+    /** Most recent recorded event across all kinds, ISO 8601, or null. */
+    lastUsedAt: string | null;
+    /** Recorded `access` (read/inject) count — what `--sort uses` ranks on. */
+    uses: number;
+}
 export declare function parseSortField(raw: string | undefined): SortField;
 /** Sort a copy. Time fields are most-recent-first (the useful direction for
- * "what did I touch lately"); `expiry` is soonest-first; ties fall back to name
- * so the order is stable. */
-export declare function sortBundles(bundles: SecretsBundle[], field: SortField): SecretsBundle[];
+ * "what did I touch lately"); `uses` is most-frequently-accessed first; `expiry`
+ * is soonest-first; ties fall back to name so the order is stable. `usage`
+ * carries the value-free read-model facts `used`/`uses` rank on — when omitted,
+ * `used` falls back to the throttled `last_used` stamp and `uses` sees zero. */
+export declare function sortBundles(bundles: SecretsBundle[], field: SortField, usage?: Map<string, BundleUsageHint>): SecretsBundle[];
 /** Human summary of the active filters, for the empty state. `sessions` only
  * echoes --project/--all on a miss, which leaves you guessing which flag emptied
  * the list; naming every active axis is the difference between "nothing matched"

package/dist/lib/secrets/list-filter.js

@@ -171,8 +171,10 @@ export function bundleMatchesFilter(b, f, ctx) {
     }
     return true;
 }
-/** Sort fields for `--sort`. `name` is the default and matches `listBundles()`. */
-export const SORT_FIELDS = ['name', 'used', 'created', 'updated', 'expiry'];
+/** Sort fields for `--sort`. `name` is the default and matches `listBundles()`.
+ * `used` is most-recently-used first and `uses` is most-frequently-accessed
+ * first; both read the value-free usage read-model (lib/secrets/usage-db.ts). */
+export const SORT_FIELDS = ['name', 'used', 'uses', 'created', 'updated', 'expiry'];
 export function parseSortField(raw) {
     if (!raw)
         return 'name';
@@ -196,11 +198,17 @@ function soonestExpiry(b) {
     return soonest;
 }
 /** Sort a copy. Time fields are most-recent-first (the useful direction for
- * "what did I touch lately"); `expiry` is soonest-first; ties fall back to name
- * so the order is stable. */
-export function sortBundles(bundles, field) {
+ * "what did I touch lately"); `uses` is most-frequently-accessed first; `expiry`
+ * is soonest-first; ties fall back to name so the order is stable. `usage`
+ * carries the value-free read-model facts `used`/`uses` rank on — when omitted,
+ * `used` falls back to the throttled `last_used` stamp and `uses` sees zero. */
+export function sortBundles(bundles, field, usage) {
     const stamp = (iso) => (iso ? new Date(iso).getTime() : 0);
     const byName = (a, z) => a.name.localeCompare(z.name);
+    // `used` combines the throttled keychain stamp with the exact usage-DB recency
+    // so a just-recorded access ranks a bundle even before its stamp catches up.
+    const usedMs = (b) => Math.max(stamp(b.last_used), stamp(usage?.get(b.name)?.lastUsedAt));
+    const usesOf = (b) => usage?.get(b.name)?.uses ?? 0;
     const out = [...bundles];
     if (field === 'name')
         return out.sort(byName);
@@ -209,7 +217,15 @@ export function sortBundles(bundles, field) {
             const d = soonestExpiry(a) - soonestExpiry(z);
             return d !== 0 ? d : byName(a, z);
         }
-        const key = field === 'used' ? 'last_used' : field === 'created' ? 'created_at' : 'updated_at';
+        if (field === 'used') {
+            const d = usedMs(z) - usedMs(a);
+            return d !== 0 ? d : byName(a, z);
+        }
+        if (field === 'uses') {
+            const d = usesOf(z) - usesOf(a);
+            return d !== 0 ? d : byName(a, z);
+        }
+        const key = field === 'created' ? 'created_at' : 'updated_at';
         const d = stamp(z[key]) - stamp(a[key]);
         return d !== 0 ? d : byName(a, z);
     });

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

@@ -0,0 +1,106 @@
+/**
+ * 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).
+ */
+/** The lifecycle/access events a bundle accrues over its life. */
+export type SecretUsageEvent = 'access' | 'unlock' | 'import' | 'export' | 'create' | 'view';
+/** All event kinds, in the order `view` prints them. */
+export declare const SECRET_USAGE_EVENTS: readonly SecretUsageEvent[];
+export interface RecordUsageParams {
+    /** Bundle the event applies to (required — usage is always per-bundle). */
+    bundle: string;
+    /** What happened. */
+    event: SecretUsageEvent;
+    /** Resolving agent/harness identity, when known (`*` = a global grant). */
+    agent?: string;
+    /** Remote host the value was pulled from / pushed to, when applicable. */
+    host?: string;
+    /** Free-form origin label, e.g. 'agent', 'reveal', 'ssh', '1password'. */
+    source?: string;
+    /** Outcome; defaults to 'success'. */
+    status?: 'success' | 'error';
+    /** How many keys the event touched (names only are ever known here). */
+    keyCount?: number;
+}
+/** One event kind's rollup for a bundle. */
+export interface UsageStat {
+    count: number;
+    /** ISO 8601 timestamp of the most recent occurrence, or null if never. */
+    last: string | null;
+}
+/** Per-bundle usage summary for the `view` / `list` surfaces. */
+export interface BundleUsageSummary {
+    bundle: string;
+    /** Every recorded event, all kinds. */
+    total: number;
+    /** Rollup per event kind (every kind present, zeroed when unused). */
+    events: Record<SecretUsageEvent, UsageStat>;
+    /** Most recent event across all kinds, or null. */
+    lastUsedAt: string | null;
+    /** Earliest event across all kinds, or null. */
+    firstUsedAt: string | null;
+    /** Event count grouped by resolving agent, most-first. `*` = a global grant. */
+    byAgent: Array<{
+        agent: string;
+        count: number;
+    }>;
+}
+/** One recorded event, for the `secrets activity` timeline. */
+export interface SecretUsageHistoryEntry {
+    ts: string;
+    bundle: string;
+    event: SecretUsageEvent;
+    agent: string | null;
+    host: string | null;
+    source: string | null;
+    status: string | null;
+    keyCount: number | 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 declare function recordSecretUsage(p: RecordUsageParams): void;
+/**
+ * Usage summary for one bundle, or undefined when nothing has ever been
+ * recorded (or the DB is unavailable). Never throws.
+ */
+export declare function getBundleUsage(bundle: string): BundleUsageSummary | 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 declare function getAllBundleUsage(): Map<string, BundleUsageSummary>;
+/**
+ * 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 declare function getUsageHistory(bundle: string | undefined, limit?: number): SecretUsageHistoryEntry[];
+/** Close the cached handle. Used by tests between temp-db swaps. */
+export declare function closeSecretsUsageDb(): void;

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/bash-command.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Parses the raw command strings agents pass to Bash tool calls into structured
+ * metadata: the executable, category, subcommand, and a display summary. Used by
+ * session rendering and the activity-log hook so `agents sessions` and
+ * `agents activity` can summarize what actually happened instead of printing a
+ * wall of shell.
+ */
+export type BashCategory = 'vcs' | 'build-test' | 'install' | 'remote' | 'http' | 'media' | 'upscaling' | 'metadata' | 'probe' | 'search' | 'shell' | 'wait' | 'other';
+export interface BashToolInfo {
+    category: BashCategory;
+    signal: 'high' | 'mid' | 'low';
+    action: string;
+    aliases?: string[];
+}
+export interface BashCommandInfo {
+    tool: string;
+    category: BashCategory;
+    subcommand: string;
+    action: string;
+    summary: string;
+    signal: 'high' | 'mid' | 'low';
+}
+export declare function unwrapCommand(cmd: string): string;
+/**
+ * Split a possibly-compound Bash command into simple commands, then tokenize each
+ * with shlex. Returns an empty array for empty input.
+ */
+export declare function tokenizeBash(cmd: string): string[][];
+/**
+ * Classify the first simple command in a Bash string. Returns coarse metadata
+ * (tool name, category, subcommand, human action) used for summaries and
+ * activity logging. Unknown executables fall back to `other`.
+ */
+export declare function classifyBashCommand(command: string): BashCommandInfo;
+/**
+ * Stable bucket key for grouping similar Bash commands in summaries. Commands run
+ * through a remote wrapper (ssh/scp/rsync) get an `ssh→` prefix on the inner key,
+ * so `ssh host "git push"` buckets as `ssh→git push`, distinct from a local push.
+ */
+export declare function bucketKey(command: string): string;
+/**
+ * Detect high-signal Bash-driven milestones (video renders, upscales, metadata
+ * edits, git commits/pushes/worktrees, PR opens). Returns null for routine
+ * commands.
+ */
+export declare function detectBashMilestone(command: string): {
+    event: string;
+    detail: string;
+} | null;
+/**
+ * Human-readable category label for renderers.
+ */
+export declare function categoryLabel(category: BashCategory): string;