@phnx-labs/agents-cli 1.20.17 → 1.20.18

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+**`agents secrets unlock`: a secrets-agent that ends Touch ID prompt spam (macOS)**
+
+- macOS pops a Touch ID prompt **per bundle, per process** — the biometry assertion is process-local and macOS refuses to cache `kSecAccessControl`+biometry items, so running several agents at once (`agents teams`, parallel `agents run --secrets`) re-prompts once per process. New `agents secrets unlock <bundle>` reads the bundle once (one prompt) and holds the resolved env in a local broker; every later resolution — `agents run`, teammates, browser profiles, the routines daemon — is served from memory over a user-only Unix socket (`~/.agents/.cache/helpers/secrets-agent/`, `0700`) with no prompt. `agents secrets lock` wipes it; `agents secrets status` shows what's held and when it locks. The hold also ends on TTL expiry (default 24h, `--ttl`) and on screen-lock / sleep.
+- **Opt-in by construction:** if you never `unlock`, resolution is byte-for-byte the existing keychain path — guarded behind a single `agentSocketExists()` stat. The single integration point is `readAndResolveBundleEnv`, so every consumer benefits without per-call-site changes. Broker-served reads are tagged `"source":"agent"` in the audit log.
+- **Security trade-off (documented in `docs/secrets.md`):** while unlocked, a same-user process that can reach the socket reads the bundle silently — the same trust boundary the keychain already concedes (the ACL is user-presence, not code-identity), minus the visible prompt. Bounded by explicit per-bundle opt-in, TTL, screen-lock/sleep auto-lock, and `lock`.
+- Snapshot semantics: `unlock` freezes a bundle's dynamic `exec:`/`env:`/`file:` refs at unlock time; keychain and literal values are unaffected.
+- **Release note:** auto-lock on screen-lock/sleep adds a `watch-lock` subcommand to `keychain-helper.swift`. The signed helper must be rebuilt + re-notarized and its sha re-pinned (`scripts/build-keychain-helper.sh`, `scripts/Agents CLI.app.sha256`) for that path to ship; until then the agent degrades gracefully to TTL-only locking. Source: `src/lib/secrets/agent.ts`.
+
+**Per-bundle tiers + opt-in auto-cache for the secrets-agent**
+
+- Bundles now carry a tier (`agents secrets tier <bundle> [biometry|session]`, or `--tier` on `create`). `biometry` (default) is today's behavior — only an explicit `unlock` puts it in the agent. `session` makes a bundle agent-eligible.
+- New `secrets.agent.auto: true` in `agents.yaml` (default off): the first real keychain read of a **`session`**-tier bundle auto-loads it into the broker in the background (no added latency, secret passed over stdin not argv), so the next concurrent run reads it silently — no manual `unlock`. A `biometry`-tier bundle is never auto-held.
+- A `none` tier (items without the biometry ACL, fully silent, no agent) is intentionally **not** offered yet — it needs a separate signed-helper change and is the global downgrade the agent exists to avoid.
+- Default secrets-agent TTL is 24h.
+
 **Headless Linux: `agents secrets` works out of the box when the keyring is locked**
 
 - On a headless server the libsecret/GNOME-keyring collection is locked, so the encrypted-file fallback is the only option — but it previously hard-failed unless `AGENTS_SECRETS_PASSPHRASE` was set, leaving `agents secrets` silently unusable. Now, on a headless run with no passphrase set, a random machine-local passphrase is auto-provisioned once at `~/.agents/.cache/secrets/.passphrase` (mode 0600) so the encrypted-file store just works. `AGENTS_SECRETS_PASSPHRASE` still takes precedence (off-disk key), an existing `.passphrase` is reused for stable interactive/headless behavior, and interactive TTY sessions are still prompted. Security model + resolution order documented in `docs/secrets.md`. (#371)

package/README.md

@@ -553,7 +553,7 @@ Two repos with the same shape, different roles:
 
 See [docs/00-concepts.md](docs/00-concepts.md) for the full mental model: DotAgents repos, resource kinds, and how resolution works end-to-end.
 
-Other useful commands: `agents doctor` checks CLI availability and resource sync drift, `agents usage` shows available quota/rate-limit data for installed agents, `agents import` adopts an existing unmanaged install, `agents trash` lists and restores soft-deleted version directories, and `agents subagents` installs reusable subagent definitions for parent-agent workflows.
+Other useful commands: `agents doctor` checks CLI availability and resource sync drift, `agents usage` shows available quota/rate-limit data for installed agents, `agents budget` shows cross-vendor spend caps and current spend-to-cap (and enforces pre-flight estimates + a hard-cap kill-switch on every run — see [docs/06-observability.md](docs/06-observability.md#budget-guardrails-agents-budget)), `agents import` adopts an existing unmanaged install, `agents trash` lists and restores soft-deleted version directories, and `agents subagents` installs reusable subagent definitions for parent-agent workflows.
 
 ---
 

package/dist/commands/budget.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `agents budget` — view and set spend caps (issue #346).
+ *
+ *   agents budget                show effective caps + spend-to-cap (today + project)
+ *   agents budget --json         machine-readable snapshot
+ *   agents budget set <cap> <n>  write a cap to the user agents.yaml budget: block
+ *
+ * Caps resolve project > user (see lib/budget/config.ts); `agents budget`
+ * reports the EFFECTIVE merged config for the current directory, and `set`
+ * writes the user-global layer (the project layer is hand-edited in the repo's
+ * agents.yaml, like every other project override).
+ */
+import type { Command } from 'commander';
+export declare function registerBudgetCommand(program: Command): void;

package/dist/commands/budget.js

@@ -0,0 +1,137 @@
+import chalk from 'chalk';
+import { ALL_AGENT_IDS } from '../lib/agents.js';
+import { readMeta, updateMeta } from '../lib/state.js';
+import { resolveBudgetConfig, hasAnyCap } from '../lib/budget/config.js';
+import { loadLedger, spendForDay, spendForProject, spendForAgentDay, localDay } from '../lib/budget/ledger.js';
+import { formatUsd } from '../lib/pricing/index.js';
+const TOP_CAPS = ['per_run', 'per_day', 'per_project'];
+export function registerBudgetCommand(program) {
+    const budgetCmd = program
+        .command('budget')
+        .description('Show spend caps and current spend-to-cap (issue #346)')
+        .option('--json', 'Emit the budget + spend snapshot as JSON')
+        .action((options) => {
+        const cwd = process.cwd();
+        const cfg = resolveBudgetConfig(cwd);
+        const ledger = loadLedger();
+        const today = localDay();
+        const daySpend = spendForDay(today, ledger);
+        const projectSpend = spendForProject(cwd, ledger);
+        const perAgentSpend = {};
+        if (cfg.per_agent) {
+            for (const agent of Object.keys(cfg.per_agent)) {
+                perAgentSpend[agent] = spendForAgentDay(agent, today, ledger);
+            }
+        }
+        if (options.json) {
+            console.log(JSON.stringify({
+                currency: cfg.currency ?? 'USD',
+                on_exceed: cfg.on_exceed ?? 'block',
+                require_confirm_over: cfg.require_confirm_over ?? null,
+                caps: {
+                    per_run: cfg.per_run ?? null,
+                    per_day: cfg.per_day ?? null,
+                    per_project: cfg.per_project ?? null,
+                    per_agent: cfg.per_agent ?? {},
+                },
+                spend: {
+                    day: daySpend,
+                    project: projectSpend,
+                    per_agent_day: perAgentSpend,
+                },
+                configured: hasAnyCap(cfg),
+                project: cwd,
+                day: today,
+            }, null, 2));
+            return;
+        }
+        console.log(renderBudget(cfg, { daySpend, projectSpend, perAgentSpend, project: cwd, day: today }));
+    });
+    budgetCmd
+        .command('set <cap> <amount>')
+        .description(`Set a user-global cap. <cap> = ${TOP_CAPS.join(' | ')} | per_agent.<agent> | on_exceed | require_confirm_over`)
+        .addHelpText('after', `
+Examples:
+  agents budget set per_run 5            Cap any single run at $5
+  agents budget set per_day 50           Cap total spend per day at $50
+  agents budget set per_agent.claude 30  Cap Claude's daily spend at $30
+  agents budget set on_exceed warn       Switch to warn-only (do not block)
+`)
+        .action((cap, amount) => {
+        const meta = readMeta();
+        const current = { ...(meta.budget ?? {}) };
+        if (cap === 'on_exceed') {
+            if (amount !== 'block' && amount !== 'warn') {
+                console.error(chalk.red(`on_exceed must be 'block' or 'warn'.`));
+                process.exit(1);
+            }
+            current.on_exceed = amount;
+        }
+        else if (cap.startsWith('per_agent.')) {
+            const agent = cap.slice('per_agent.'.length);
+            if (!ALL_AGENT_IDS.includes(agent)) {
+                console.error(chalk.red(`Unknown agent '${agent}'. Known: ${ALL_AGENT_IDS.join(', ')}`));
+                process.exit(1);
+            }
+            const value = parseAmount(amount);
+            current.per_agent = { ...(current.per_agent ?? {}), [agent]: value };
+        }
+        else if (TOP_CAPS.includes(cap) || cap === 'require_confirm_over') {
+            const value = parseAmount(amount);
+            current[cap] = value;
+        }
+        else {
+            console.error(chalk.red(`Unknown cap '${cap}'. Use: ${TOP_CAPS.join(', ')}, per_agent.<agent>, on_exceed, require_confirm_over.`));
+            process.exit(1);
+        }
+        updateMeta((m) => ({ ...m, budget: current }));
+        console.log(chalk.green(`Set budget.${cap} = ${amount}`));
+    });
+}
+function parseAmount(amount) {
+    const value = Number(amount.replace(/^\$/, ''));
+    if (!Number.isFinite(value) || value < 0) {
+        console.error(chalk.red(`Invalid amount '${amount}'. Use a non-negative number (e.g. 5 or 5.00).`));
+        process.exit(1);
+    }
+    return value;
+}
+/** Render one cap line: "  per_run     $0.42 / $5.00  ▮▮▯▯▯▯▯▯▯▯". Unset caps render as "(unset)". */
+function capLine(label, spend, cap) {
+    if (cap === undefined) {
+        return `  ${label.padEnd(14)} ${chalk.dim('(unset)')}`;
+    }
+    const spent = spend ?? 0;
+    const ratio = cap > 0 ? Math.min(spent / cap, 1) : 0;
+    const bars = Math.round(ratio * 10);
+    const bar = '▮'.repeat(bars) + '▯'.repeat(10 - bars);
+    const color = ratio >= 1 ? chalk.red : ratio >= 0.8 ? chalk.yellow : chalk.green;
+    const figure = spend === null ? formatUsd(cap) : `${formatUsd(spent)} / ${formatUsd(cap)}`;
+    return `  ${label.padEnd(14)} ${color(figure.padEnd(18))} ${color(bar)}`;
+}
+function renderBudget(cfg, snap) {
+    const lines = [];
+    lines.push(chalk.bold('Budget') + chalk.dim(`  (on_exceed: ${cfg.on_exceed ?? 'block'}, currency: ${cfg.currency ?? 'USD'})`));
+    lines.push(chalk.dim(`  project: ${snap.project}`));
+    lines.push(chalk.dim(`  day:     ${snap.day}`));
+    lines.push('');
+    if (!hasAnyCap(cfg)) {
+        lines.push(chalk.dim('  No caps configured. Set one with: agents budget set per_run 5'));
+        return lines.join('\n');
+    }
+    lines.push(capLine('per_run', null, cfg.per_run));
+    lines.push(capLine('per_day', snap.daySpend, cfg.per_day));
+    lines.push(capLine('per_project', snap.projectSpend, cfg.per_project));
+    if (cfg.per_agent && Object.keys(cfg.per_agent).length > 0) {
+        lines.push('');
+        lines.push(chalk.bold('Per-agent (today)'));
+        for (const [agent, cap] of Object.entries(cfg.per_agent)) {
+            lines.push(capLine(agent, snap.perAgentSpend[agent] ?? 0, cap));
+        }
+    }
+    if (cfg.require_confirm_over !== undefined) {
+        lines.push('');
+        lines.push(chalk.dim(`  confirm prompt over: ${formatUsd(cfg.require_confirm_over)}`));
+    }
+    return lines.join('\n');
+}

package/dist/commands/cost.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Cost command — roll up $ spend and wall-clock duration across the local,
+ * cross-agent session index.
+ *
+ * This is the read side of issue #323. Cost and duration are computed and
+ * persisted at scan time (see src/lib/session/discover.ts + db.ts); this
+ * command only queries and renders them — a pure SQLite/CLI win, no server,
+ * no telemetry. Distinct from `agents usage`, which reports live rate-limit /
+ * quota status per agent and is left untouched.
+ */
+import type { Command } from 'commander';
+export declare function registerCostCommand(program: Command): void;

package/dist/commands/cost.js

@@ -0,0 +1,139 @@
+import chalk from 'chalk';
+import { discoverSessions, parseTimeFilter } from '../lib/session/discover.js';
+import { queryUsageRollup, topSessionsByCost, } from '../lib/session/db.js';
+import { formatUsd, PRICING_VERSION } from '../lib/pricing/index.js';
+import { formatDuration } from '../lib/session/render.js';
+export function registerCostCommand(program) {
+    program
+        .command('cost')
+        .description('Roll up $ cost and duration across local agent sessions')
+        .option('--json', 'Output the rollup as JSON')
+        .option('--since <time>', 'Only sessions newer than this (e.g., 7d, 4w, or ISO date)')
+        .option('--by <dimension>', 'Group the breakdown by: agent (default), project, or day')
+        .addHelpText('after', `
+Examples:
+  agents cost                   Daily histogram + top sessions + per-agent breakdown
+  agents cost --since 30d       Last 30 days only
+  agents cost --by project      Break down by project instead of agent
+  agents cost --by day --json   Machine-readable daily rollup
+
+Cost is computed offline from a versioned per-model price table (${PRICING_VERSION}).
+`)
+        .action(async (options) => {
+        await costAction(options);
+    });
+}
+/** Map the --by flag to a rollup group, rejecting unknown values. */
+function resolveGroup(by) {
+    if (by === undefined)
+        return 'agent';
+    if (by === 'agent' || by === 'project' || by === 'day')
+        return by;
+    console.error(chalk.red('error: --by must be one of: agent, project, day'));
+    process.exit(1);
+}
+async function costAction(options) {
+    const sinceMs = options.since ? parseTimeFilter(options.since) : undefined;
+    // Ensure the index is fresh (and migrated to v6) before we read costs.
+    await discoverSessions({ all: true, since: options.since, limit: 1 });
+    const filter = {};
+    if (typeof sinceMs === 'number')
+        filter.sinceMs = sinceMs;
+    const groupBy = resolveGroup(options.by);
+    const daily = queryUsageRollup({ ...filter, groupBy: 'day' });
+    const breakdown = queryUsageRollup({ ...filter, groupBy });
+    const top = topSessionsByCost(10, filter);
+    const totalCost = breakdown.reduce((s, r) => s + r.costUsd, 0);
+    const totalSessions = breakdown.reduce((s, r) => s + r.sessionCount, 0);
+    const totalDuration = breakdown.reduce((s, r) => s + r.durationMs, 0);
+    if (options.json) {
+        process.stdout.write(JSON.stringify({
+            pricingVersion: PRICING_VERSION,
+            since: options.since ?? null,
+            totals: { costUsd: totalCost, sessionCount: totalSessions, durationMs: totalDuration },
+            daily,
+            breakdown: { by: groupBy, rows: breakdown },
+            topSessions: top.map(t => ({
+                id: t.meta.id,
+                shortId: t.meta.shortId,
+                agent: t.meta.agent,
+                project: t.meta.project ?? null,
+                topic: t.meta.topic ?? t.meta.label ?? null,
+                costUsd: t.costUsd,
+                durationMs: t.durationMs,
+                timestamp: t.meta.timestamp,
+            })),
+        }, null, 2) + '\n');
+        return;
+    }
+    if (totalSessions === 0) {
+        console.log(chalk.gray('No sessions with cost data found. Run `agents sessions --all` to index, then retry.'));
+        return;
+    }
+    const out = [];
+    out.push(chalk.bold('Cost') + chalk.gray(`  ·  pricing ${PRICING_VERSION}${options.since ? `  ·  since ${options.since}` : ''}`));
+    out.push(`  ${chalk.green(formatUsd(totalCost))} across ${totalSessions} session${totalSessions !== 1 ? 's' : ''}` +
+        (totalDuration > 0 ? chalk.gray(`  ·  ${formatDuration(totalDuration)} total`) : ''));
+    out.push('');
+    // Daily histogram (unicode block sparkline, zero deps).
+    if (daily.length > 0) {
+        out.push(chalk.bold('Daily'));
+        out.push(renderDailyHistogram(daily));
+        out.push('');
+    }
+    // Top sessions by cost.
+    if (top.length > 0) {
+        out.push(chalk.bold('Top sessions by cost'));
+        const costW = Math.max(...top.map(t => formatUsd(t.costUsd).length), 4);
+        for (const t of top) {
+            const cost = formatUsd(t.costUsd).padStart(costW);
+            const dur = t.durationMs > 0 ? formatDuration(t.durationMs) : '—';
+            const label = t.meta.label || t.meta.topic || '(untitled)';
+            const proj = t.meta.project ? chalk.gray(` ${t.meta.project}`) : '';
+            out.push(`  ${chalk.green(cost)}  ${chalk.gray(t.meta.shortId)}  ${chalk.cyan(t.meta.agent.padEnd(7))} ${truncate(label, 48)}` +
+                proj +
+                chalk.gray(`  ${dur}`));
+        }
+        out.push('');
+    }
+    // Per-agent / per-project / per-day breakdown.
+    const groupLabel = groupBy === 'agent' ? 'agent' : groupBy === 'project' ? 'project' : 'day';
+    out.push(chalk.bold(`By ${groupLabel}`));
+    const keyW = Math.max(...breakdown.map(r => r.key.length), groupLabel.length);
+    const costW2 = Math.max(...breakdown.map(r => formatUsd(r.costUsd).length), 4);
+    for (const r of breakdown) {
+        const cost = formatUsd(r.costUsd).padStart(costW2);
+        const dur = r.durationMs > 0 ? formatDuration(r.durationMs) : '—';
+        out.push(`  ${r.key.padEnd(keyW)}  ${chalk.green(cost)}  ${chalk.gray(`${r.sessionCount} session${r.sessionCount !== 1 ? 's' : ''}`)}  ${chalk.gray(dur)}`);
+    }
+    console.log(out.join('\n'));
+}
+/** Eight levels of vertical block characters for sparkline rendering. */
+const BLOCKS = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
+/** Render a per-day cost histogram as a unicode sparkline plus a labeled list. */
+function renderDailyHistogram(daily) {
+    // Daily comes back cost-desc; show it chronologically for the sparkline.
+    const sorted = [...daily].sort((a, b) => a.key.localeCompare(b.key));
+    const max = Math.max(...sorted.map(d => d.costUsd), 0);
+    const spark = sorted
+        .map(d => {
+        if (max <= 0 || d.costUsd <= 0)
+            return BLOCKS[0];
+        const idx = Math.min(BLOCKS.length - 1, Math.round((d.costUsd / max) * (BLOCKS.length - 1)));
+        return BLOCKS[idx];
+    })
+        .join('');
+    const lines = [`  ${chalk.green(spark)}`];
+    // Show the most expensive days as a short list under the sparkline.
+    const topDays = [...daily].slice(0, 7);
+    const costW = Math.max(...topDays.map(d => formatUsd(d.costUsd).length), 4);
+    for (const d of topDays) {
+        lines.push(`  ${chalk.gray(d.key)}  ${chalk.green(formatUsd(d.costUsd).padStart(costW))}`);
+    }
+    return lines.join('\n');
+}
+/** Truncate a string to n chars with an ellipsis. */
+function truncate(s, n) {
+    const oneLine = s.replace(/\s+/g, ' ').trim();
+    return oneLine.length > n ? oneLine.slice(0, n - 1) + '…' : oneLine;
+}

package/dist/commands/exec.d.ts

@@ -6,5 +6,25 @@
  * injection, and multi-agent fallback chains for rate-limit resilience.
  */
 import type { Command } from 'commander';
+/**
+ * Build the LoopConfig the driver consumes from CLI flags and/or a workflow's
+ * `loop:` frontmatter block (issue #332). Returns undefined when neither source
+ * activates a loop (the common single-shot run). CLI flags take precedence over
+ * the workflow's declared values field-by-field, so `--max-iterations 5`
+ * overrides a workflow's `max_iterations: 3`.
+ *
+ * `--loop` with no sub-options is a valid bare loop (driver applies its own
+ * maxIterations safety cap). A workflow `loop:` block activates a loop even
+ * without `--loop` so `agents run <workflow>` honors a declared loop.
+ */
+export declare function buildLoopConfig(flags: {
+    loop?: boolean;
+    maxIterations?: string;
+    budget?: string;
+    until?: string;
+    interval?: string;
+}, workflowLoop?: import('../lib/workflows.js').LoopConfigRaw): import('../lib/loop.js').LoopConfig | undefined;
+/** Map a loop stop reason to a process exit code. condition-met/max are clean exits. */
+export declare function loopExitCode(stoppedBy: import('../lib/loop.js').LoopStoppedBy): number;
 /** Register the `agents run <agent> [prompt]` command. */
 export declare function registerRunCommand(program: Command): void;