@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/browser-client.js

@@ -1,52 +1,9 @@
-/**
- * browser-client.ts — the ONE process client through which agents-cli talks to
- * the standalone `browser` CLI (@phnx-labs/browser-cli, PHNX-4101).
- *
- * This is the agents-owned half of the browser extraction, and it is
- * deliberately small. agents-cli no longer carries the CDP/BiDi/Arc drivers, a
- * browser IPC service, a chrome-data/profile store, a network-capture pipeline,
- * or the remote SSH driving loop — the standalone engine owns all of it, exactly
- * as `secrets` took the keychain engine (PHNX-3989), `computer` took the
- * accessibility engine (PHNX-4075) and `sessions` took the transcript engine
- * (PHNX-4012). What stays here is what only the fleet CLI can know: which device
- * a `--device` name resolves to, whether this machine consents to being driven,
- * who the acting session is, and where an action must be recorded.
- *
- * THERE IS NO FALLBACK. A missing executable throws `BROWSER_BIN_MISSING` with
- * install guidance (DIST-1) rather than silently driving a bundled engine —
- * agents-cli has none to drive, and a fallback would re-couple the two release
- * trains this extraction exists to separate.
- *
- * Transport — inherited-fd passthrough, not request/response (matches
- * browser-cli's `bin/browser.cjs` launcher, which forwards fds 3-16):
- *
- *   - stdio 0/1/2 are INHERITED. The engine owns the user's terminal: its
- *     stdout is the command's stdout, its `--json` is the command's `--json`,
- *     its prompts reach a real tty. agents-cli never re-formats engine output,
- *     which is what keeps the surface honest as the engine evolves.
- *   - fd 3 (`BROWSER_CONTEXT_FD`) carries ONE JSON object — the consumer context
- *     built by `lib/browser/context.ts` — written and closed immediately, so the
- *     engine reads to EOF and proceeds. The document is read once, before command
- *     parsing; a malformed one is a hard error, an absent one the standalone case.
- *   - fd 4 (`BROWSER_EVENTS_FD`) carries NDJSON action events back: one JSON
- *     object per line, each an action the engine actually performed. agents-cli
- *     turns those into feed events and `sessions --browser` history
- *     (`lib/browser/record.ts`). The engine may emit none; it must never block
- *     on this pipe.
- *
- * Both fds are anonymous pipes on the child's side, the same shape
- * `computer-client.ts` and `secrets-client.ts` settled on after a named FIFO
- * wedged macOS reads. The context is pushed rather than pulled so the engine
- * needs no callback into agents-cli — one direction each way, no reentrancy.
- */
 import { spawn } from 'node:child_process';
 import { realpathSync, existsSync } from 'node:fs';
 import * as path from 'node:path';
 import { findInPath } from './agent-spec/agents.js';
 const INSTALL_HINT = 'npm i -g @phnx-labs/browser-cli';
-/** fd the engine reads its one-shot JSON context from. */
 export const BROWSER_CONTEXT_FD = 3;
-/** fd the engine writes NDJSON action events to. */
 export const BROWSER_EVENTS_FD = 4;
 export class BrowserClientError extends Error {
     code;
@@ -66,29 +23,14 @@ function browserEntrypoint(bin) {
     const launcher = path.join(path.dirname(bin), 'node_modules', '@phnx-labs', 'browser-cli', 'bin', 'browser.cjs');
     return existsSync(launcher) ? launcher : bin;
 }
-/**
- * Accept only the real standalone `browser` executable, never agents-cli's own
- * `browser` command shim (`exec "$AGENTS_BIN" browser`, `installations/shims.ts`)
- * — resolving that would recurse into this process. `findInPath` already skips
- * `~/.agents/.cache/shims`; this guard is the second line, mirroring
- * `isStandaloneComputer` (agents-cli never shipped a `dist/browser.js` bin, but
- * the check stays symmetric and future-proof against one).
- */
 export function isStandaloneBrowser(bin) {
     let real = browserEntrypoint(bin);
     try {
         real = realpathSync(real);
     }
-    catch { /* spawn reports missing explicit paths */ }
+    catch { }
     return !/\.(cmd|ps1)$/i.test(real) && !real.endsWith(path.join('dist', 'browser.js'));
 }
-/**
- * Resolve the standalone executable. `BROWSER_BIN` wins so a dev build can be
- * driven without touching PATH.
- *
- * Resolution uses `findInPath`, which skips `~/.agents/.cache/shims` — see
- * `isStandaloneBrowser` for why that skip is load-bearing.
- */
 export function resolveBrowserBin() {
     if (cachedBin)
         return cachedBin;
@@ -102,8 +44,6 @@ export function resolveBrowserBin() {
     cachedBin = browserEntrypoint(resolved);
     return cachedBin;
 }
-/** True when the standalone `browser` CLI is resolvable — the readiness signal
- * for `agents setup` without a spawn. Never throws. */
 export function browserInstalled() {
     try {
         resolveBrowserBin();
@@ -113,22 +53,11 @@ export function browserInstalled() {
         return false;
     }
 }
-/** A `.js`/`.cjs`/`.mjs` bin is run through this runtime; a real executable is exec'd directly. */
 export function invocation(bin) {
     if (/\.[mc]?js$/.test(bin))
         return { command: process.execPath, prefix: [bin] };
     return { command: bin, prefix: [] };
 }
-/**
- * Split a growing buffer into complete NDJSON lines. Pure so the framing rules —
- * blank lines skipped, a non-JSON line dropped rather than crashing the CLI, a
- * trailing partial line carried forward — are unit-testable without a spawn.
- *
- * A malformed line is dropped, not thrown: these events are telemetry riding
- * alongside a user-visible action that already happened. Failing the command
- * because its receipt was unreadable would be strictly worse than losing the
- * receipt. The action itself already failed loud on its own channel if it failed.
- */
 export function parseEventLines(buffer) {
     const events = [];
     const parts = buffer.split('\n');
@@ -144,19 +73,10 @@ export function parseEventLines(buffer) {
             }
         }
         catch {
-            // Unreadable receipt — see above.
         }
     }
     return { events, rest };
 }
-/**
- * Run the standalone engine with the consumer context on fd 3 and the action
- * event stream on fd 4. Resolves with the engine's exit code; the caller
- * propagates it so `agents browser` exits exactly as the engine did.
- *
- * Throws `BROWSER_BIN_MISSING` when the standalone is not installed. Every other
- * failure is the engine's own, reported on the inherited stderr.
- */
 export async function runBrowser(opts) {
     const bin = resolveBrowserBin();
     const { command, prefix } = invocation(bin);
@@ -171,8 +91,6 @@ export async function runBrowser(opts) {
     const contextPipe = child.stdio[BROWSER_CONTEXT_FD];
     const eventsPipe = child.stdio[BROWSER_EVENTS_FD];
     if (contextPipe) {
-        // An engine that exits before reading the context (bad argv, `--help`)
-        // closes fd 3 and we get EPIPE. That is a normal race, not a failure.
         contextPipe.on('error', () => { });
         contextPipe.end(JSON.stringify(opts.context) + '\n');
     }
@@ -196,7 +114,6 @@ export async function runBrowser(opts) {
         });
         eventsPipe.on('error', () => resolve());
         eventsPipe.on('end', () => {
-            // A final line with no trailing newline still counts.
             const { events } = parseEventLines(pending.endsWith('\n') ? pending : pending + '\n');
             pending = '';
             for (const event of events)
@@ -209,8 +126,6 @@ export async function runBrowser(opts) {
             reject(new BrowserClientError('BROWSER_SPAWN_FAILED', `Could not run \`${bin}\`: ${err.message}`));
         });
         child.on('close', (code, signal) => {
-            // A signalled child has no exit code; report the conventional 128+n so
-            // callers and shells see a non-zero status instead of a false success.
             if (code == null)
                 return resolve(signal ? 128 + (osSignalNumber(signal) ?? 0) : 1);
             resolve(code);
@@ -219,16 +134,12 @@ export async function runBrowser(opts) {
     await drained;
     return { exitCode, stdout };
 }
-/** Signal name → number for the 128+n exit convention. Only the ones a tunnelled
- * or interrupted engine realistically dies on; anything else contributes 0 and
- * still yields a non-zero status. */
 function osSignalNumber(signal) {
     const table = {
         SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGPIPE: 13, SIGTERM: 15,
     };
     return table[signal];
 }
-/** Test seam: drop the memoized bin so PATH fixtures can re-resolve. */
 export function _resetBrowserClientForTest() {
     cachedBin = undefined;
 }

package/dist/lib/budget/config.d.ts

@@ -1,9 +1,3 @@
 import type { BudgetConfig } from '../types.js';
-/**
- * Effective budget for `cwd`: user/global base, then each project-local block
- * from farthest ancestor to nearest, nearest winning. `on_exceed` defaults to
- * `block` when nothing sets it (fail-closed: the safe default is to enforce).
- */
 export declare function resolveBudgetConfig(cwd?: string): BudgetConfig;
-/** True when at least one enforceable cap is set. No caps => budget feature is dormant. */
 export declare function hasAnyCap(cfg: BudgetConfig): boolean;

package/dist/lib/budget/config.js

@@ -1,16 +1,3 @@
-/**
- * Budget config resolution (issue #346).
- *
- * The `budget:` block can live in the user/global agents.yaml (`readMeta().budget`)
- * and in any project-local agents.yaml walked from cwd upward. Precedence is
- * project > user, matching `run:` resolution (lib/run-config.ts). Caps merge
- * field-by-field — a project that sets only `per_run` inherits the user's
- * `per_day`/`per_project`/`per_agent` rather than wiping them.
- *
- * This is the single resolver the pre-flight gate, the live watcher, and the
- * `agents config budget` command all route through, so the effective cap set is
- * computed in exactly one place.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
@@ -18,12 +5,6 @@ import { getUserAgentsDir, readMeta } from '../state.js';
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-/**
- * Coerce a raw parsed `budget:` block into a typed BudgetConfig, dropping any
- * field whose value is the wrong shape. Malformed entries are ignored, not
- * thrown — a typo in one cap must never crash a run (no-fallbacks applies to
- * the data path, not to user-typed config we choose to be lenient about).
- */
 function coerceBudget(raw) {
     if (!isRecord(raw))
         return {};
@@ -52,7 +33,6 @@ function coerceBudget(raw) {
     }
     return out;
 }
-/** Merge a higher-precedence budget over a base. Set fields win; per_agent merges key-by-key. */
 function mergeBudget(base, over) {
     const merged = { ...base, ...stripUndefined(over) };
     if (base.per_agent || over.per_agent) {
@@ -68,7 +48,6 @@ function stripUndefined(cfg) {
     }
     return out;
 }
-/** Read project-local `budget:` blocks from nearest dir upward, nearest LAST (highest precedence). */
 function getProjectBudgets(startPath) {
     const configs = [];
     let dir = path.resolve(startPath);
@@ -83,19 +62,12 @@ function getProjectBudgets(startPath) {
                 }
             }
             catch {
-                // Malformed project config — ignore and keep walking.
             }
         }
         dir = path.dirname(dir);
     }
-    // configs[0] is the nearest dir. Reverse so the nearest applies LAST (wins).
     return configs.reverse();
 }
-/**
- * Effective budget for `cwd`: user/global base, then each project-local block
- * from farthest ancestor to nearest, nearest winning. `on_exceed` defaults to
- * `block` when nothing sets it (fail-closed: the safe default is to enforce).
- */
 export function resolveBudgetConfig(cwd = process.cwd()) {
     const userBudget = coerceBudget(readMeta().budget);
     let merged = userBudget;
@@ -106,7 +78,6 @@ export function resolveBudgetConfig(cwd = process.cwd()) {
         merged.on_exceed = 'block';
     return merged;
 }
-/** True when at least one enforceable cap is set. No caps => budget feature is dormant. */
 export function hasAnyCap(cfg) {
     return (cfg.per_run !== undefined ||
         cfg.per_day !== undefined ||

package/dist/lib/budget/enforce.d.ts

@@ -1,18 +1,4 @@
-/**
- * Live spend watcher + cap math (issue #346).
- *
- * This is the provider-agnostic shared surface the loop driver (#332) will
- * reuse for its budget guard. It knows nothing about child processes, agents,
- * or the ledger — it accepts parsed usage events and a caps object, accumulates
- * cost via the canonical pricing module, and fires `onBreach` exactly once when
- * any active cap is crossed.
- *
- * The accumulation is the cross-vendor primitive: feed Claude usage and Codex
- * usage to the same watcher under one `per_project` / `per_run` cap and the
- * spend aggregates across both — no single-vendor control can do that.
- */
 import type { AgentId, BudgetConfig } from '../types.js';
-/** A parsed usage event from any agent's stream (fields match session/parse). */
 export interface UsageEvent {
     agent?: AgentId | string;
     model?: string;
@@ -21,73 +7,37 @@ export interface UsageEvent {
     cacheReadTokens?: number;
     cacheCreationTokens?: number;
 }
-/**
- * Caps the watcher enforces. `priorDaySpend` / `priorProjectSpend` seed the
- * accumulators with spend already on the ledger BEFORE this run started, so a
- * per_day cap counts today's earlier runs too — not just this process. Per-cap
- * fields are USD; undefined means "not enforced".
- */
 export interface LiveCaps {
     perRun?: number;
     perDay?: number;
     perProject?: number;
-    /** Per-agent daily caps. Each agent's running spend is checked against its own cap. */
     perAgent?: Partial<Record<string, number>>;
-    /** Day spend already on the ledger before this run (cross-vendor). */
     priorDaySpend?: number;
-    /** Project spend already on the ledger before this run (cross-vendor). */
     priorProjectSpend?: number;
-    /** Per-agent day spend already on the ledger before this run, keyed by agent. */
     priorAgentDaySpend?: Partial<Record<string, number>>;
 }
-/** Which cap tripped, and the spend figures at the moment of the breach. */
 export interface BreachInfo {
     cap: 'per_run' | 'per_day' | 'per_project' | 'per_agent';
-    /** The configured limit that was crossed (USD). */
     limit: number;
-    /** The spend that crossed it (USD). */
     spend: number;
-    /** Agent attributed to the breach (only meaningful for per_agent). */
     agent?: string;
-    /** This run's accumulated spend so far (USD). */
     runSpend: number;
 }
-/** Public watcher surface. `feedUsage` is idempotent after a breach (no double-fire). */
 export interface LiveSpendWatcher {
-    /** Feed one parsed usage event; accrues cost and may fire onBreach. */
     feedUsage(event: UsageEvent): void;
-    /** Total USD this run has accumulated across all fed events. */
     runSpend(): number;
-    /** True once a cap has been breached. */
     breached(): boolean;
-    /** Stop accepting events / release references. Idempotent. */
     dispose(): void;
 }
-/** Convert a resolved BudgetConfig + prior ledger spend into the caps the watcher needs. */
 export declare function capsFromConfig(cfg: BudgetConfig, prior?: {
     daySpend?: number;
     projectSpend?: number;
     agentDaySpend?: Partial<Record<string, number>>;
 }): LiveCaps;
-/**
- * Create a live spend watcher. `onBreach` fires at most once, on the first
- * event that pushes any active cap from at-or-under to over. After it fires the
- * watcher keeps accumulating (so `runSpend()` stays accurate for the final
- * ledger record) but never calls `onBreach` again.
- */
 export declare function makeLiveSpendWatcher(args: {
     caps: LiveCaps;
     onBreach: (breach: BreachInfo) => void;
 }): LiveSpendWatcher;
-/**
- * Incrementally extract usage events from a stream-json chunk. Buffers a partial
- * trailing line across calls (returned in `rest`), parses each complete line,
- * and yields one UsageEvent per line that carries token counts. Provider shapes
- * handled: Claude/`--json` assistant turns (`message.usage` with
- * `input_tokens`/`output_tokens`/`cache_*_input_tokens`) and the flatter
- * `usage.record` shape (`usage.input_tokens`/`output`). Lines that aren't JSON
- * or carry no usage are skipped — this never throws on agent output.
- */
 export declare function extractUsageEvents(chunk: string, pending: string, fallbackModel?: string, fallbackAgent?: string): {
     events: UsageEvent[];
     rest: string;

package/dist/lib/budget/enforce.js

@@ -1,5 +1,4 @@
 import { actualCost } from '../pricing/index.js';
-/** Convert a resolved BudgetConfig + prior ledger spend into the caps the watcher needs. */
 export function capsFromConfig(cfg, prior) {
     return {
         perRun: cfg.per_run,
@@ -11,16 +10,9 @@ export function capsFromConfig(cfg, prior) {
         priorAgentDaySpend: prior?.agentDaySpend ?? {},
     };
 }
-/**
- * Create a live spend watcher. `onBreach` fires at most once, on the first
- * event that pushes any active cap from at-or-under to over. After it fires the
- * watcher keeps accumulating (so `runSpend()` stays accurate for the final
- * ledger record) but never calls `onBreach` again.
- */
 export function makeLiveSpendWatcher(args) {
     const { caps, onBreach } = args;
     let run = 0;
-    // Cross-vendor accumulators, seeded with pre-run ledger spend.
     let day = caps.priorDaySpend ?? 0;
     let project = caps.priorProjectSpend ?? 0;
     const agentDay = {};
@@ -81,15 +73,6 @@ export function makeLiveSpendWatcher(args) {
         },
     };
 }
-/**
- * Incrementally extract usage events from a stream-json chunk. Buffers a partial
- * trailing line across calls (returned in `rest`), parses each complete line,
- * and yields one UsageEvent per line that carries token counts. Provider shapes
- * handled: Claude/`--json` assistant turns (`message.usage` with
- * `input_tokens`/`output_tokens`/`cache_*_input_tokens`) and the flatter
- * `usage.record` shape (`usage.input_tokens`/`output`). Lines that aren't JSON
- * or carry no usage are skipped — this never throws on agent output.
- */
 export function extractUsageEvents(chunk, pending, fallbackModel, fallbackAgent) {
     const combined = pending + chunk;
     const lines = combined.split('\n');
@@ -113,15 +96,8 @@ export function extractUsageEvents(chunk, pending, fallbackModel, fallbackAgent)
     return { events, rest };
 }
 function usageFromObject(obj, fallbackModel, fallbackAgent) {
-    // Claude emits a final `type:"result"` event carrying a TOP-LEVEL cumulative
-    // `usage` that already sums every per-turn `message.usage`. Counting both the
-    // per-turn turns AND this cumulative total double-counts a multi-turn run
-    // (~2x). The canonical session parser (src/lib/session/parse.ts) reads usage
-    // ONLY from `message.usage` and extracts nothing from the result line — mirror
-    // that here: skip result lines entirely for usage.
     if (obj?.type === 'result')
         return null;
-    // Claude stream-json assistant turn.
     const mu = obj?.message?.usage;
     if (mu && (typeof mu.input_tokens === 'number' || typeof mu.output_tokens === 'number')) {
         return {
@@ -133,9 +109,6 @@ function usageFromObject(obj, fallbackModel, fallbackAgent) {
             cacheCreationTokens: mu.cache_creation_input_tokens,
         };
     }
-    // Flatter usage.record / usage shape (Codex / `usage.record`). The result-line
-    // guard above already excludes Claude's cumulative result usage, so this only
-    // matches genuine per-event usage records.
     const u = obj?.usage;
     if (u && (typeof u.input_tokens === 'number' || typeof u.output === 'number' || typeof u.output_tokens === 'number')) {
         return {

package/dist/lib/budget/ledger.d.ts

@@ -1,27 +1,16 @@
-/** A single spend observation. Append-only; never mutated in place. */
 export interface SpendEntry {
-    /** Run identifier — groups multiple usage observations from one dispatch. */
     runId: string;
-    /** Agent id (claude, codex, ...). The cross-vendor attribution key. */
     agent: string;
-    /** Project key (absolute path or repo slug). Empty string when unknown. */
     project: string;
-    /** Local calendar day, YYYY-MM-DD. */
     day: string;
-    /** Model id as reported by the stream (may carry vendor prefix / date suffix). */
     model: string;
     inputTok: number;
     outputTok: number;
-    /** Combined cache read + creation tokens (kept as one field for the ledger). */
     cacheTok: number;
-    /** USD cost of THIS observation, via actualCost() at write time. */
     costUsd: number;
-    /** Where the spend came from: local run, teams teammate, or cloud dispatch. */
     source: 'run' | 'teams' | 'cloud';
-    /** ISO timestamp of the observation. */
     ts: string;
 }
-/** Token bundle for a single observation (matches session/parse usage fields). */
 export interface UsageObservation {
     model?: string;
     inputTokens?: number;
@@ -29,13 +18,7 @@ export interface UsageObservation {
     cacheReadTokens?: number;
     cacheCreationTokens?: number;
 }
-/** Local YYYY-MM-DD for a Date (defaults to now). Local, not UTC — caps are a human-day notion. */
 export declare function localDay(d?: Date): string;
-/**
- * Append one spend observation. Computes `costUsd` from the usage via the
- * canonical pricing module (unpriced models contribute $0). Returns the written
- * entry. Creates the spend dir on first write.
- */
 export declare function recordSpend(input: {
     runId: string;
     agent: string;
@@ -45,15 +28,9 @@ export declare function recordSpend(input: {
     source: SpendEntry['source'];
     ts?: Date;
 }, ledgerPath?: string): SpendEntry;
-/** Load every entry. Skips malformed lines (a half-written final line never breaks a rollup). */
 export declare function loadLedger(ledgerPath?: string): SpendEntry[];
-/** Total USD spend on a given local day across ALL agents (cross-vendor). */
 export declare function spendForDay(day: string, ledger?: SpendEntry[]): number;
-/** Total USD spend on a given day for ONE agent (per-agent cap accounting). */
 export declare function spendForAgentDay(agent: string, day: string, ledger?: SpendEntry[]): number;
-/** Total USD spend attributed to an agent across all time. */
 export declare function spendForAgent(agent: string, ledger?: SpendEntry[]): number;
-/** Total USD spend attributed to a project across all time (cross-vendor). */
 export declare function spendForProject(project: string, ledger?: SpendEntry[]): number;
-/** Total USD spend for a single run id (all of its usage observations). */
 export declare function spendForRun(runId: string, ledger?: SpendEntry[]): number;

package/dist/lib/budget/ledger.js

@@ -1,37 +1,16 @@
-/**
- * Append-only spend ledger (issue #346).
- *
- * Every dispatched run that produces token usage records one JSONL line under
- * `<history>/spend/ledger.jsonl`. The ledger is the shared artifact #323's
- * `agents insights cost` can later read for $ rollups, so the entry shape stays clean
- * and stable: one record = one usage observation attributed to a run.
- *
- * `costUsd` is computed at write time via the canonical pricing module
- * (lib/pricing) so the ledger is self-contained — a reader never needs the
- * pricing table to sum spend. Rollups (`spendForDay`/`spendForAgent`/...) are
- * pure folds over the file; for the modest line counts a developer accrues this
- * is plenty fast, and there's no index to corrupt.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getHistoryDir } from '../state.js';
 import { actualCost } from '../pricing/index.js';
-/** Default ledger path: <history>/spend/ledger.jsonl. */
 function defaultLedgerPath() {
     return path.join(getHistoryDir(), 'spend', 'ledger.jsonl');
 }
-/** Local YYYY-MM-DD for a Date (defaults to now). Local, not UTC — caps are a human-day notion. */
 export function localDay(d = new Date()) {
     const y = d.getFullYear();
     const m = String(d.getMonth() + 1).padStart(2, '0');
     const day = String(d.getDate()).padStart(2, '0');
     return `${y}-${m}-${day}`;
 }
-/**
- * Append one spend observation. Computes `costUsd` from the usage via the
- * canonical pricing module (unpriced models contribute $0). Returns the written
- * entry. Creates the spend dir on first write.
- */
 export function recordSpend(input, ledgerPath = defaultLedgerPath()) {
     const ts = input.ts ?? new Date();
     const cacheTok = (input.usage.cacheReadTokens ?? 0) + (input.usage.cacheCreationTokens ?? 0);
@@ -58,7 +37,6 @@ export function recordSpend(input, ledgerPath = defaultLedgerPath()) {
     fs.appendFileSync(ledgerPath, JSON.stringify(entry) + '\n');
     return entry;
 }
-/** Load every entry. Skips malformed lines (a half-written final line never breaks a rollup). */
 export function loadLedger(ledgerPath = defaultLedgerPath()) {
     if (!fs.existsSync(ledgerPath))
         return [];
@@ -73,7 +51,6 @@ export function loadLedger(ledgerPath = defaultLedgerPath()) {
                 out.push(parsed);
         }
         catch {
-            // Tolerate a torn final line; everything before it is intact.
         }
     }
     return out;
@@ -85,23 +62,18 @@ function sum(entries, pred) {
             total += e.costUsd;
     return total;
 }
-/** Total USD spend on a given local day across ALL agents (cross-vendor). */
 export function spendForDay(day, ledger = loadLedger()) {
     return sum(ledger, (e) => e.day === day);
 }
-/** Total USD spend on a given day for ONE agent (per-agent cap accounting). */
 export function spendForAgentDay(agent, day, ledger = loadLedger()) {
     return sum(ledger, (e) => e.agent === agent && e.day === day);
 }
-/** Total USD spend attributed to an agent across all time. */
 export function spendForAgent(agent, ledger = loadLedger()) {
     return sum(ledger, (e) => e.agent === agent);
 }
-/** Total USD spend attributed to a project across all time (cross-vendor). */
 export function spendForProject(project, ledger = loadLedger()) {
     return sum(ledger, (e) => e.project === project);
 }
-/** Total USD spend for a single run id (all of its usage observations). */
 export function spendForRun(runId, ledger = loadLedger()) {
     return sum(ledger, (e) => e.runId === runId);
 }

package/dist/lib/budget/live-cloud.d.ts

@@ -1,40 +1,14 @@
-/**
- * Live budget kill-switch for `agents cloud` dispatch (issue #399).
- *
- * Follow-up to #346, which shipped a pre-flight budget gate for cloud runs but
- * no live mid-run enforcement — a runaway cloud task would keep spending until
- * the user hit Ctrl-C. This wires the same `makeLiveSpendWatcher` the local
- * headless run uses (src/lib/exec.ts) into the cloud SSE stream: each `usage`
- * event from the provider feeds the watcher, and on breach we call
- * `provider.cancel(taskId)` to terminate server-side.
- *
- * Wrapper shape mirrors `renderStream`'s input — it takes an
- * `AsyncIterable<CloudEvent>` and yields the same events downstream. Dormant
- * (returns the source stream unchanged) when no caps are configured.
- */
 import type { CloudProvider, CloudEvent } from '../cloud/types.js';
 import { type BreachInfo } from './enforce.js';
-/** Result surface exposed to the caller so it can act on a mid-stream breach. */
 interface CloudBudgetGate {
-    /** True once a cap crossed and cancel() was invoked. */
     breached(): boolean;
     breach(): BreachInfo | null;
 }
-/**
- * Wrap a cloud event stream with a live budget watcher. On a `usage` event we
- * feed the shared watcher; on the first breach we call `provider.cancel(taskId)`
- * and forward a synthetic `status:'cancelled'` + `error` frame so the renderer
- * shows why the task stopped. Returns null when no caps are configured; callers
- * fall through to the raw stream in that case.
- */
 export declare function wrapStreamWithBudgetGate(args: {
     provider: CloudProvider;
     taskId: string;
-    /** Project attribution key — repo slug for Rush, or cwd. */
     project: string;
-    /** Agent the dispatch runs under (for per_agent cap accounting). */
     agent: string;
-    /** cwd used to resolve the effective budget config. */
     cwd?: string;
 }): {
     wrap: (source: AsyncIterable<CloudEvent>) => AsyncIterable<CloudEvent>;

package/dist/lib/budget/live-cloud.js

@@ -1,13 +1,6 @@
 import { capsFromConfig, makeLiveSpendWatcher, } from './enforce.js';
 import { resolveBudgetConfig, hasAnyCap } from './config.js';
 import { loadLedger, localDay, spendForDay, spendForProject } from './ledger.js';
-/**
- * Wrap a cloud event stream with a live budget watcher. On a `usage` event we
- * feed the shared watcher; on the first breach we call `provider.cancel(taskId)`
- * and forward a synthetic `status:'cancelled'` + `error` frame so the renderer
- * shows why the task stopped. Returns null when no caps are configured; callers
- * fall through to the raw stream in that case.
- */
 export function wrapStreamWithBudgetGate(args) {
     const cfg = resolveBudgetConfig(args.cwd);
     if (!hasAnyCap(cfg))
@@ -36,15 +29,10 @@ export function wrapStreamWithBudgetGate(args) {
                         outputTokens: event.outputTokens ?? 0,
                     });
                     if (watcher.breached() && firstBreach) {
-                        // Cancel server-side FIRST so we stop the meter; then surface the
-                        // breach to the renderer as an error + cancelled status so the CLI
-                        // exits with a visible reason (not a silent stream close).
                         try {
                             await args.provider.cancel(args.taskId);
                         }
                         catch (err) {
-                            // Best-effort — even if cancel fails, break the stream: the
-                            // caller sees the error frame and can retry manually.
                             yield {
                                 type: 'error',
                                 message: `[budget] cap ${firstBreach.cap} exceeded ($${firstBreach.spend.toFixed(2)} > $${firstBreach.limit.toFixed(2)}); cancel FAILED: ${err.message}`,

package/dist/lib/budget/live-team.d.ts

@@ -1,31 +1,14 @@
 import type { AgentManager } from '../teams/agents.js';
 import { type BreachInfo } from './enforce.js';
-/** Public surface of the team-scoped budget watcher. */
 export interface TeamBudgetWatcher {
-    /** Feed any new usage events from every running teammate's stdout.log. */
     poll(): Promise<void>;
-    /** True once any cap has been crossed (mirrors LiveSpendWatcher). */
     breached(): boolean;
-    /** The first breach seen, or null if none yet. */
     breach(): BreachInfo | null;
-    /** Release references and stop tapping streams. Idempotent. */
     dispose(): void;
 }
-/**
- * Build a team-scoped budget watcher for the given team. Returns null when the
- * effective budget config has no caps — matching the local watcher's dormant
- * contract so callers pay nothing when the feature is off.
- *
- * The watcher is seeded with prior-day and prior-project spend from the ledger
- * so a partway-through day counts today's earlier runs against `per_day`.
- * Each `poll()` reads new bytes from every running teammate's stdout.log and
- * feeds parsed usage events into the shared watcher — `onBreach` fires exactly
- * once, mirroring `makeLiveSpendWatcher`.
- */
 export declare function createTeamBudgetWatcher(args: {
     manager: AgentManager;
     team: string;
-    /** Project/cwd used to (a) resolve budget config and (b) seed project spend. */
     cwd: string;
     onBreach: (breach: BreachInfo) => void;
 }): TeamBudgetWatcher | null;