@phnx-labs/agents-cli 1.20.90 → 1.20.92

package/dist/commands/feed.js

@@ -1,8 +1,8 @@
 import chalk from 'chalk';
-import { ensureFeedPublishHook, listAskStats, listBlocks, recordNotified } from '../lib/feed.js';
+import { ensureFeedPublishHook, listAskStats, listBlocks, recordNotified, buildDeclaredBlock, publishBlock, } from '../lib/feed.js';
 import { ensureActivityLogHook, readRecentActivity, formatActivityLine, formatProgressUpdate, mergeActivityEvents, parseActivityPayload, } from '../lib/activity.js';
 import { postFeedStatus } from '../lib/feed-post.js';
-import { parseFeedPostLevel, planFeedBroadcast, runFeedBroadcast, } from '../lib/feed-broadcast.js';
+import { parseFeedPostLevel, planFeedBroadcast, runFeedBroadcast, blockBroadcastContext, blockDeliveryFailure, } from '../lib/feed-broadcast.js';
 import { getSessionById } from '../lib/session/db.js';
 import { readMeta } from '../lib/state.js';
 import { enrichBlocksFromSessions, groupBlocksByOutcome, isUnambiguousOutcomeAnswer, openBlocksForOutcome, stampBlockOutcomes, } from '../lib/feed-outcome.js';
@@ -238,6 +238,9 @@ export function registerFeedCommand(program) {
         .option('--session <id>', 'Session id escape hatch (default: auto from env / pid registry)')
         .option('--attach <path-or-url...>', 'Attach an artifact (local file or URL); repeatable')
         .option('--level <level>', 'How loudly to broadcast: milestone (default) or important. Configured sinks with minLevel: important only fire on the latter.', 'milestone')
+        .option('--blocked', 'You are STUCK and need the user. Opens an answerable block and always broadcasts at important — do not also pass --level.')
+        .option('--option <label...>', 'With --blocked: an answer the user can pick; repeatable')
+        .option('--default <answer>', 'With --blocked: a safe default policy may apply if nobody answers in time')
         .option('--json', 'Emit the written event as JSON')
         .addHelpText('after', `
 Examples:
@@ -249,6 +252,17 @@ Examples:
   # Worth interrupting someone over — reaches sinks gated on minLevel: important:
   agents feed post "release blocked: npm token expired" --level important
 
+  # You are STUCK and cannot proceed. Opens an answerable block that stays in
+  # 'agents feed' until someone resolves it, and always reaches the owner —
+  # do NOT also pass --level:
+  agents feed post "force-push denied by git-guard on PR #1749" --blocked
+  agents feed post "publish to npm or wait for review?" --blocked --option publish --option wait
+  agents feed post "delete the stale preview env?" --blocked --default "leave it"
+
+  # Exhaust self-serve FIRST. A block is for what you genuinely cannot do:
+  # a credential only the user holds, a decision only they can make, an
+  # approval only they can give. Not "should I do the obvious next step?".
+
   # Outside a run, pass the session explicitly:
   agents feed post "manual note" --session 00998b0e-2d15-4d2f-a58b-974a886c9b47
 
@@ -268,22 +282,66 @@ docs/06-observability.md.
             session: opts?.session ?? cmd?.opts?.()?.session,
             attach: opts?.attach ?? cmd?.opts?.()?.attach,
             level: opts?.level ?? cmd?.opts?.()?.level,
+            blocked: Boolean(opts?.blocked ?? cmd?.opts?.()?.blocked),
+            option: opts?.option ?? cmd?.opts?.()?.option,
+            default: opts?.default ?? cmd?.opts?.()?.default,
             json: Boolean(opts?.json ?? cmd?.opts?.()?.json ?? cmd?.parent?.opts?.()?.json),
         };
         try {
-            const level = parseFeedPostLevel(flags.level);
+            // Blocked is a state, not a volume: it always broadcasts at `important`,
+            // so an agent has exactly one thing to say. Passing both is a usage
+            // error rather than a silent override -- an agent that thinks it chose
+            // the level should not be quietly ignored.
+            if (flags.blocked && flags.level && flags.level !== 'milestone') {
+                throw new Error('--blocked already broadcasts at important; drop --level.');
+            }
+            if (!flags.blocked && (flags.option?.length || flags.default)) {
+                throw new Error('--option/--default only apply with --blocked.');
+            }
+            const level = flags.blocked ? 'important' : parseFeedPostLevel(flags.level);
             const { event } = postFeedStatus({
                 text: Array.isArray(textParts) ? textParts.join(' ') : String(textParts ?? ''),
                 sessionId: flags.session,
                 attach: flags.attach,
+                blocked: flags.blocked,
             });
-            const outcomes = broadcastPostedEvent(event, level);
+            // A blocked post lands in BOTH stores: the event in the shared activity
+            // stream (what happened) and an OpenBlock in the ledger (what is still
+            // open). The ledger is what makes it answerable and clearable -- without
+            // it the ask would scroll away like any other update.
+            let outcomes;
+            if (flags.blocked) {
+                const block = buildDeclaredBlock(event, {
+                    text: event.detail ?? '',
+                    options: flags.option,
+                    safeDefault: flags.default,
+                });
+                publishBlock(block);
+                outcomes = broadcastBlock(block, { project: event.project, agent: event.agent });
+            }
+            else {
+                outcomes = broadcastPostedEvent(event, level);
+            }
+            // Fail loud when a block reached nobody. This is computed BEFORE the
+            // --json early return: a machine caller is exactly the one that reads the
+            // exit code, so returning 0 there while a human gets 1 would make the
+            // undelivered block invisible to the caller most likely to act on it —
+            // reintroducing, behind a flag, the silent failure this exists to remove.
+            // One sink failing among several stays a warning: the channels are
+            // redundant by design.
+            const undelivered = blockDeliveryFailure(flags.blocked, outcomes);
+            if (undelivered)
+                process.exitCode = 1;
             if (flags.json) {
                 console.log(JSON.stringify(outcomes.length ? { ...event, broadcast: outcomes } : event, null, 2));
+                if (undelivered)
+                    console.error(chalk.red(undelivered));
                 return;
             }
             console.log(formatProgressUpdate(event));
             reportBroadcast(outcomes);
+            if (undelivered)
+                console.error(chalk.red(undelivered));
         }
         catch (err) {
             console.error(chalk.red(err.message));
@@ -516,6 +574,21 @@ function broadcastPostedEvent(event, level) {
     });
     return runFeedBroadcast(planned);
 }
+/**
+ * Mirror a declared block to the same sinks a post reaches.
+ *
+ * Blocks previously never broadcast at all: `broadcastPostedEvent` ran only for
+ * `feed post`, while every `publishBlock` call wrote to the ledger and stopped
+ * there — so a "needs you" record was durable and invisible at the same time.
+ */
+function broadcastBlock(block, extras) {
+    const config = readMeta().feed?.broadcast;
+    if (!config || Object.keys(config).length === 0)
+        return [];
+    const ticket = getSessionById(block.sessionId)?.ticketId;
+    const ctx = blockBroadcastContext({ ...block, ticket: block.ticket ?? ticket }, extras);
+    return runFeedBroadcast(planFeedBroadcast(config, ctx));
+}
 /** One line per sink that ran. Silent when nothing is configured. */
 function reportBroadcast(outcomes) {
     for (const o of outcomes) {

package/dist/commands/hooks.js

@@ -603,30 +603,46 @@ Examples:
         .option('--warn-ms <n>', 'p99 threshold above which a hook is flagged as slow', '2000')
         .option('--json', 'Emit raw JSON rows instead of the table')
         .addHelpText('after', `
-Shows aggregated stats for every hook that emitted a hook.fire event into
-~/.agents/.cache/logs/events-YYYY-MM-DD.jsonl. Only hooks with \`cache:\` in
-their manifest are instrumented today — the generated shim writes the events.
+Shows aggregated stats for every hook that fired through a generated shim.
+Primary source: disposable SQLite warehouse ~/.agents/.cache/perf/perf.db
+(same data as \`agents perf hooks\`). Falls back to the legacy daily JSONL under
+~/.agents/.cache/logs/ when the warehouse is empty.
 
 Examples:
   agents hooks profile                # last 7 days, table form
   agents hooks profile --days 30      # roll up the full month
   agents hooks profile --json | jq    # pipe somewhere
+  agents perf hooks                   # same rollup under the perf surface
 
 A hook whose p99 exceeds --warn-ms gets flagged in the cache column. Add
 'cache: 5m' or 'cache: 5m-bg' to its hooks.yaml entry to fix it.
 `)
         .action(async (options) => {
         const { aggregateHookProfile, loadHookFireEvents, formatMs, formatCacheColumn, DEFAULT_SLOW_HOOK_WARN_MS } = await import('../lib/hooks/profile.js');
+        const { aggregateSamples } = await import('../lib/perf/db.js');
         const days = Math.max(1, parseInt(options.days, 10) || 7);
         const warnMs = Math.max(0, parseInt(options.warnMs, 10) || DEFAULT_SLOW_HOOK_WARN_MS);
-        const rows = aggregateHookProfile(loadHookFireEvents(days));
+        // Prefer the indexed warehouse; fall back to legacy JSONL for pre-warehouse shims.
+        const fromDb = aggregateSamples({ days, kinds: ['hook.fire'] }).map((r) => ({
+            hook: r.label,
+            n: r.n,
+            p50Ms: r.p50Ms,
+            p99Ms: r.p99Ms,
+            meanMs: r.meanMs,
+            maxMs: r.maxMs,
+            cacheHitPct: r.cacheHitPct ?? 0,
+            cacheStalePct: r.cacheStalePct ?? 0,
+            cacheMissPct: r.cacheMissPct ?? 0,
+            errorCount: r.errorCount ?? 0,
+        }));
+        const rows = fromDb.length > 0 ? fromDb : aggregateHookProfile(loadHookFireEvents(days));
         if (options.json) {
             console.log(JSON.stringify(rows, null, 2));
             return;
         }
         if (rows.length === 0) {
-            console.log(chalk.gray(`No hook.fire events in the last ${days} day${days === 1 ? '' : 's'}.`));
-            console.log(chalk.gray('Add \'cache: 5m\' to a hook in hooks.yaml to start collecting stats.'));
+            console.log(chalk.gray(`No hook.fire samples in the last ${days} day${days === 1 ? '' : 's'}.`));
+            console.log(chalk.gray('Add \'cache: 5m\' to a hook (or matches:) so a shim instruments it, then resync.'));
             return;
         }
         const widths = { hook: 36, n: 5, p50: 7, p99: 7, mean: 7, max: 7, cache: 30 };

package/dist/commands/perf.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `agents perf` — latency rollups over the disposable perf SQLite warehouse.
+ *
+ * Subcommands:
+ *   agents perf              multi-section summary (commands + hooks + runs)
+ *   agents perf hooks        per-hook p50/p99 + cache hit rates
+ *   agents perf commands     slowest CLI command paths (from command.end)
+ *   agents perf run          agent.run / perf.timing labels
+ *
+ * Soft-joins sessions.db via shared string keys (session_id, agent, machine) —
+ * no foreign keys. Warehouse lives at ~/.agents/.cache/perf/perf.db (safe to wipe).
+ */
+import type { Command } from 'commander';
+export declare function registerPerfCommand(program: Command): void;

package/dist/commands/perf.js

@@ -0,0 +1,221 @@
+/**
+ * `agents perf` — latency rollups over the disposable perf SQLite warehouse.
+ *
+ * Subcommands:
+ *   agents perf              multi-section summary (commands + hooks + runs)
+ *   agents perf hooks        per-hook p50/p99 + cache hit rates
+ *   agents perf commands     slowest CLI command paths (from command.end)
+ *   agents perf run          agent.run / perf.timing labels
+ *
+ * Soft-joins sessions.db via shared string keys (session_id, agent, machine) —
+ * no foreign keys. Warehouse lives at ~/.agents/.cache/perf/perf.db (safe to wipe).
+ */
+import chalk from 'chalk';
+import { aggregateSamples, perfDbPath, } from '../lib/perf/db.js';
+import { formatMs, formatCacheColumn, DEFAULT_SLOW_HOOK_WARN_MS, loadHookFireEvents, aggregateHookProfile, } from '../lib/hooks/profile.js';
+function parseDays(raw) {
+    const n = parseInt(raw ?? '7', 10);
+    return Number.isFinite(n) && n > 0 ? n : 7;
+}
+function parseWarnMs(raw, fallback) {
+    const n = parseInt(raw ?? String(fallback), 10);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+function parseLimit(raw, fallback) {
+    const n = parseInt(raw ?? String(fallback), 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+/** Map warehouse rows shaped like hook.fire into the existing HookProfileRow UI. */
+function asHookRows(rows) {
+    return rows.map((r) => ({
+        hook: r.label,
+        n: r.n,
+        p50Ms: r.p50Ms,
+        p99Ms: r.p99Ms,
+        meanMs: r.meanMs,
+        maxMs: r.maxMs,
+        cacheHitPct: r.cacheHitPct ?? 0,
+        cacheStalePct: r.cacheStalePct ?? 0,
+        cacheMissPct: r.cacheMissPct ?? 0,
+        errorCount: r.errorCount ?? 0,
+    }));
+}
+function printTable(headers, widths, lines, slowFlags) {
+    const pad = (s, w) => (s.length >= w ? s.slice(0, w) : s + ' '.repeat(w - s.length));
+    const header = headers.map((h, i) => pad(h, widths[i])).join(' ');
+    console.log(chalk.bold(header));
+    console.log(chalk.gray('─'.repeat(header.length)));
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].map((c, j) => pad(c, widths[j])).join(' ');
+        console.log(slowFlags[i] ? chalk.yellow(line) : line);
+    }
+}
+function renderHookTable(rows, warnMs) {
+    if (rows.length === 0) {
+        console.log(chalk.gray('No hook timing samples yet.'));
+        console.log(chalk.gray(`Warehouse: ${perfDbPath()}`));
+        console.log(chalk.gray('Hooks write via cache/matches shims into the spool; run a session or resync hooks.'));
+        return;
+    }
+    const widths = { hook: 36, n: 5, p50: 7, p99: 7, mean: 7, max: 7, cache: 28 };
+    const pad = (s, w) => (s.length >= w ? s.slice(0, w) : s + ' '.repeat(w - s.length));
+    const header = [
+        pad('HOOK', widths.hook),
+        pad('N', widths.n),
+        pad('P50', widths.p50),
+        pad('P99', widths.p99),
+        pad('MEAN', widths.mean),
+        pad('MAX', widths.max),
+        pad('CACHE', widths.cache),
+    ].join(' ');
+    console.log(chalk.bold(header));
+    console.log(chalk.gray('─'.repeat(header.length)));
+    for (const r of rows) {
+        const slow = r.p99Ms > warnMs;
+        const cacheCol = formatCacheColumn(r);
+        const warning = slow && r.cacheHitPct + r.cacheStalePct === 0 ? '  ← add cache: 5m' : '';
+        const line = [
+            pad(r.hook, widths.hook),
+            pad(String(r.n), widths.n),
+            pad(formatMs(r.p50Ms), widths.p50),
+            pad(formatMs(r.p99Ms), widths.p99),
+            pad(formatMs(r.meanMs), widths.mean),
+            pad(formatMs(r.maxMs), widths.max),
+            pad(cacheCol, widths.cache),
+        ].join(' ') + warning;
+        console.log(slow ? chalk.yellow(line) : line);
+    }
+}
+function renderLabelTable(title, rows, warnMs, limit) {
+    const sliced = rows.slice(0, limit);
+    if (sliced.length === 0) {
+        console.log(chalk.gray(`No ${title} samples yet.`));
+        return;
+    }
+    const widths = [40, 5, 7, 7, 7, 7];
+    printTable(['LABEL', 'N', 'P50', 'P99', 'MEAN', 'MAX'], widths, sliced.map((r) => [
+        r.label,
+        String(r.n),
+        formatMs(r.p50Ms),
+        formatMs(r.p99Ms),
+        formatMs(r.meanMs),
+        formatMs(r.maxMs),
+    ]), sliced.map((r) => r.p99Ms > warnMs));
+}
+/**
+ * Prefer SQLite samples; fall back to the legacy daily JSONL so existing
+ * instrumentation still surfaces until shims are resynced.
+ */
+function loadHookProfile(days) {
+    const fromDb = asHookRows(aggregateSamples({ days, kinds: ['hook.fire'] }));
+    if (fromDb.length > 0)
+        return fromDb;
+    return aggregateHookProfile(loadHookFireEvents(days));
+}
+function hooksAction(opts) {
+    const days = parseDays(opts.days);
+    const warnMs = parseWarnMs(opts.warnMs, DEFAULT_SLOW_HOOK_WARN_MS);
+    const rows = loadHookProfile(days);
+    if (opts.json) {
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
+    renderHookTable(rows, warnMs);
+}
+function commandsAction(opts) {
+    const days = parseDays(opts.days);
+    const warnMs = parseWarnMs(opts.warnMs, 500);
+    const limit = parseLimit(opts.limit, 40);
+    const rows = aggregateSamples({ days, kinds: ['command.end'] });
+    if (opts.json) {
+        console.log(JSON.stringify(rows.slice(0, limit), null, 2));
+        return;
+    }
+    renderLabelTable('command', rows, warnMs, limit);
+}
+function runAction(opts) {
+    const days = parseDays(opts.days);
+    const warnMs = parseWarnMs(opts.warnMs, 60_000);
+    const limit = parseLimit(opts.limit, 40);
+    const rows = aggregateSamples({ days, kinds: ['perf.timing'] });
+    if (opts.json) {
+        console.log(JSON.stringify(rows.slice(0, limit), null, 2));
+        return;
+    }
+    renderLabelTable('run/timing', rows, warnMs, limit);
+}
+function summaryAction(opts) {
+    const days = parseDays(opts.days);
+    if (opts.json) {
+        console.log(JSON.stringify({
+            days,
+            warehouse: perfDbPath(),
+            hooks: loadHookProfile(days),
+            commands: aggregateSamples({ days, kinds: ['command.end'] }).slice(0, 20),
+            run: aggregateSamples({ days, kinds: ['perf.timing'] }).slice(0, 20),
+        }, null, 2));
+        return;
+    }
+    console.log(chalk.bold(`agents perf — last ${days} day${days === 1 ? '' : 's'}`));
+    console.log(chalk.gray(`warehouse: ${perfDbPath()}  (disposable; soft-join sessions via session_id/agent/machine)`));
+    console.log('');
+    console.log(chalk.bold('Commands (slowest by p99)'));
+    renderLabelTable('command', aggregateSamples({ days, kinds: ['command.end'] }), parseWarnMs(opts.warnMs, 500), 12);
+    console.log('');
+    console.log(chalk.bold('Hooks'));
+    renderHookTable(loadHookProfile(days), parseWarnMs(opts.warnMs, DEFAULT_SLOW_HOOK_WARN_MS));
+    console.log('');
+    console.log(chalk.bold('Runs (perf.timing)'));
+    renderLabelTable('run/timing', aggregateSamples({ days, kinds: ['perf.timing'] }), parseWarnMs(opts.warnMs, 60_000), 12);
+}
+function attachSharedOptions(cmd) {
+    return cmd
+        .option('--days <n>', 'Days of samples to include', '7')
+        .option('--warn-ms <n>', 'p99 above this is highlighted')
+        .option('--limit <n>', 'Max rows in the table', '40')
+        .option('--json', 'Emit JSON instead of a table');
+}
+/**
+ * Commander binds a flag declared on both parent and child to the *parent*.
+ * Merge so `agents perf commands --json` still sees json:true on the leaf.
+ */
+function leafOpts(cmd) {
+    const parent = cmd.parent && typeof cmd.parent.opts === 'function'
+        ? cmd.parent.opts()
+        : {};
+    return { ...parent, ...cmd.opts() };
+}
+export function registerPerfCommand(program) {
+    const perf = program
+        .command('perf')
+        .description('Latency rollups from the disposable perf warehouse (hooks, commands, runs)')
+        .addHelpText('after', `
+The warehouse is SQLite at ~/.agents/.cache/perf/perf.db — safe to delete.
+Identity columns reuse sessions/events string shapes (session_id, agent, machine)
+for soft cross-reference; there are no foreign keys.
+
+Examples:
+  agents perf                     # summary: commands + hooks + runs
+  agents perf hooks               # per-hook p50/p99 + cache hit rate
+  agents perf commands --days 30  # slowest CLI entrypoints
+  agents perf run --json          # agent.run timings as JSON
+  agents perf hooks --warn-ms 500
+`);
+    // Options live on the parent so `agents perf --json` and
+    // `agents perf commands --json` both work (see leafOpts).
+    attachSharedOptions(perf).action(function summary() {
+        summaryAction(this.opts());
+    });
+    perf.command('hooks').description('Per-hook timing + cache stats')
+        .action(function hooks() {
+        hooksAction(leafOpts(this));
+    });
+    perf.command('commands').description('Slowest CLI command paths (command.end samples)')
+        .action(function commands() {
+        commandsAction(leafOpts(this));
+    });
+    perf.command('run').description('agent.run / perf.timing label rollups')
+        .action(function run() {
+        runAction(leafOpts(this));
+    });
+}

package/dist/commands/projects.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `agents projects` — named, multi-repo projects and the progress
+ * rollup. Definitions live in `~/.agents/projects/<name>.yaml` (see
+ * `lib/projects.ts`); this registers the command tree over them. Beta-gated on
+ * `isBetaEnabled('projects')`, mirroring `agents factory`.
+ *
+ * The headline is `status`: instead of the vague per-agent activity line, it
+ * rolls every session up by project (matched on cwd) into one card — agents by
+ * lifecycle state, plan completion, open PRs, and tickets in flight.
+ */
+import type { Command } from 'commander';
+export declare function registerProjectsCommands(program: Command): void;