@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/output.js

@@ -7,14 +7,13 @@ import { addHostOption } from '../lib/hosts/option.js';
 import { discoverSessions, parseTimeFilter } from '../lib/session/discover.js';
 import { queryUsageRollup } from '../lib/session/db.js';
 import { formatUsd, PRICING_VERSION } from '../lib/pricing/index.js';
-import { formatDuration } from '../lib/session/render.js';
+import { formatDuration } from '@phnx-labs/sessions-cli/reader';
 import { terminalWidth, truncateToWidth, padToWidth } from '../lib/session/width.js';
 import { collectGitOutput } from '../lib/output/git-output.js';
 import { loadDevices } from '../lib/devices/registry.js';
 import { machineId } from '../lib/session/sync/config.js';
 import { stripClixml } from '../lib/hosts/remote-cmd.js';
 const execFileAsync = promisify(execFile);
-/** Register `agents insights output` under the insights parent. */
 export function registerOutputCommand(insightsCmd) {
     addHostOption(insightsCmd.command('output'))
         .description('Productivity rollup — token burn vs shipped output (PRs, commits) across agents')
@@ -42,12 +41,6 @@ The burn is split into input / cache-read / cache-write where the harness record
 (Claude/Codex/Gemini/Droid). --pricing no-cache reprices cached tokens at the input rate,
 so you can see what caching is saving. --json always carries both actual and no-cache costs.
 `)
-        // Read opts via optsWithGlobals(): `--json`/`--since`/`--by` collide by name
-        // with the `insights` parent's own options, so commander binds them to the
-        // parent at parse time and the leaf's plain opts() never sees them. Merging
-        // ancestor opts is what the sibling `insights mix` recipes already do
-        // (mix-commands.ts) — without it every flag on this command is silently
-        // dropped (e.g. `agents insights output --json` printed the human table).
         .action(async (_options, command) => {
         await outputAction(command.optsWithGlobals());
     });
@@ -68,7 +61,6 @@ function resolvePricing(pricing) {
     console.error(chalk.red('error: --pricing must be one of: actual, no-cache'));
     process.exit(1);
 }
-/** Compact token formatter: 38.6M, 4.1K, 10.6B. */
 function formatCompact(n) {
     const abs = Math.abs(n);
     if (abs >= 1e9)
@@ -106,11 +98,9 @@ function sumBurn(rows) {
         return acc;
     }, emptyBurn());
 }
-/** Compute this machine's payload from the local session DB + git. */
 async function computeLocalPayload(options, includePrs) {
     const since = options.since ?? '7d';
     const sinceMs = parseTimeFilter(since);
-    // Ensure the index is fresh (and migrated to v12 so output_tokens is populated).
     await discoverSessions({ all: true, since, limit: 1 });
     const filter = { sinceMs };
     const groupBy = resolveGroup(options.by);
@@ -143,7 +133,6 @@ async function computeLocalPayload(options, includePrs) {
         uncostedAgents: groupBy === 'agent' ? breakdown.filter(r => r.costUsd === 0).map(r => r.key) : [],
     };
 }
-/** Fetch one remote device's payload by re-invoking `agents insights output --json --device <name>`. */
 async function fetchRemotePayload(device, options) {
     const args = ['insights', 'output', '--json', '--no-prs', '--device', device, '--since', options.since ?? '7d'];
     if (options.by)
@@ -157,8 +146,6 @@ async function fetchRemotePayload(device, options) {
             timeout: 120_000,
             maxBuffer: 64 * 1024 * 1024,
         });
-        // A Windows device relays its payload through PowerShell, which can prefix a
-        // CLIXML banner ahead of the JSON — strip it before parsing (RUSH-2286).
         const parsed = JSON.parse(stripClixml(stdout));
         parsed.machine = parsed.machine || device;
         return parsed;
@@ -178,9 +165,6 @@ async function fetchRemotePayload(device, options) {
 }
 async function outputAction(options) {
     const includePrs = options.prs !== false;
-    // Validate --pricing up front so a bad value errors even under --json. The JSON
-    // payload always carries BOTH costs regardless of the scenario — the flag only
-    // chooses which one the text renderer leads with.
     const scenario = resolvePricing(options.pricing);
     if (!options.allHosts) {
         const payload = await computeLocalPayload(options, includePrs);
@@ -191,7 +175,6 @@ async function outputAction(options) {
         renderSingle(payload, scenario);
         return;
     }
-    // Fleet: local payload + every online device, folded in over SSH.
     const self = machineId();
     const registry = await loadDevices();
     const remotes = Object.values(registry)
@@ -199,7 +182,6 @@ async function outputAction(options) {
         .map(d => d.name);
     if (!options.json)
         console.error(chalk.gray(`Folding in ${remotes.length} online device${remotes.length !== 1 ? 's' : ''}…`));
-    // PRs are global (gh search by author, not machine-bound) — compute once, locally.
     const local = await computeLocalPayload(options, includePrs);
     const remotePayloads = await Promise.all(remotes.map(d => fetchRemotePayload(d, options)));
     const machines = [local, ...remotePayloads];
@@ -209,13 +191,9 @@ async function outputAction(options) {
     }
     renderFleet(machines, options, scenario);
 }
-/** Merge per-machine payloads into a combined one (burn + commits summed; PRs local-only). */
 function mergeMachines(machines, options) {
     const burn = emptyBurn();
     const byKey = new Map();
-    // Union commit SHAs across machines: shared repos (cloned on several boxes)
-    // expose the same commits to `git log` on each, so summing counts would
-    // multi-count. A commit's SHA is its global identity — union, don't add.
     const allShas = new Set();
     const uncosted = new Set();
     for (const m of machines) {
@@ -238,8 +216,6 @@ function mergeMachines(machines, options) {
                 sessionCount: 0, tokenCount: 0, outputTokens: 0,
                 inputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0,
             };
-            // Peers resolve their own labels; keep the first non-empty one so a machine that
-            // has not indexed an account yet does not blank a label another machine supplied.
             cur.label ??= r.label;
             cur.costUsd += r.costUsd;
             cur.costUsdNoCache += r.costUsdNoCache;
@@ -254,7 +230,6 @@ function mergeMachines(machines, options) {
         }
     }
     const rows = [...byKey.values()].sort((a, b) => b.costUsd - a.costUsd);
-    // PRs from the local machine only (machines[0]) — gh search is not machine-scoped.
     const localGit = machines[0].output;
     return {
         machine: 'fleet',
@@ -266,7 +241,6 @@ function mergeMachines(machines, options) {
         uncostedAgents: [...uncosted],
     };
 }
-/** Attach burn-vs-output ratios to a payload for JSON output. */
 function withRatios(payload, machines) {
     const prsTotal = payload.output.prsOpened + payload.output.prsMerged;
     return {
@@ -279,11 +253,9 @@ function withRatios(payload, machines) {
         machines: machines.length > 1 ? machines.map(m => ({ machine: m.machine, burn: m.burn, commits: m.output.commits, error: m.error })) : undefined,
     };
 }
-/** The cost the text renderer leads with for the chosen scenario. */
 function scenarioCost(x, scenario) {
     return scenario === 'no-cache' ? x.costUsdNoCache : x.costUsd;
 }
-/** Shared header line: burned · output tokens · PRs · commits, plus ratios + burn split. */
 function headerLines(payload, scenario) {
     const prsTotal = payload.output.prsOpened + payload.output.prsMerged;
     const burn = payload.burn;
@@ -306,7 +278,6 @@ function headerLines(payload, scenario) {
         ratios.push(`${formatCompact(Math.round(burn.outputTokens / cost))} out-tok/$`);
     if (ratios.length > 0)
         out.push(chalk.gray('  ' + ratios.join('  ·  ')));
-    // Burn split — only for harnesses that recorded one (input/cache totals > 0).
     const splitTotal = burn.inputTokens + burn.cacheReadTokens + burn.cacheWriteTokens;
     if (splitTotal > 0) {
         out.push(chalk.gray('  burn split: ') +
@@ -316,8 +287,6 @@ function headerLines(payload, scenario) {
             chalk.gray('  ·  ') +
             `${chalk.cyan(formatCompact(burn.cacheWriteTokens))} cache-write`);
     }
-    // No-cache comparison — shown whenever caching actually moved the number, so an
-    // operator sees the saving in `actual` mode too (RUSH-2287: "both if useful").
     if (burn.costUsdNoCache > burn.costUsd && burn.costUsd > 0) {
         const saved = burn.costUsdNoCache - burn.costUsd;
         const pct = Math.round((saved / burn.costUsdNoCache) * 100);
@@ -329,7 +298,6 @@ function headerLines(payload, scenario) {
     }
     return out;
 }
-/** Render the per-group burn/output table. */
 function renderBreakdown(rows, groupBy, scenario) {
     const out = [chalk.bold(`By ${groupBy}`)];
     if (rows.length === 0)
@@ -388,7 +356,6 @@ function renderFleet(machines, options, scenario) {
     out.push(chalk.bold('Output') + chalk.gray(`  ·  fleet (${machines.length} machines)  ·  pricing ${merged.pricingVersion}  ·  since ${merged.since}`));
     out.push(...headerLines(merged, scenario));
     out.push('');
-    // By machine.
     out.push(chalk.bold('By machine'));
     const nameW = Math.max(...machines.map(m => m.machine.length), 7);
     const burnW = Math.max(...machines.map(m => formatUsd(scenarioCost(m.burn, scenario)).length), 4);

package/dist/commands/packages-materialize.d.ts

@@ -1,17 +1,6 @@
-/**
- * `agents packages materialize` — user-facing front door for portable-agent
- * materialization (PHNX-3838). ONE execution path: this command resolves the
- * schema-v3 package once with {@link resolveAgentPackage} and projects it into
- * an ephemeral native home with the canonical {@link materializeAgentPackage}
- * (agent-spec/materialize.ts). The front door owns only what a materializer must
- * not: the portable-harness allowlist, an exact harness version, and the
- * output-home refusal that keeps a run off the live `~/.claude` / `~/.codex` /
- * `~/.opencode` homes.
- */
 import type { Command } from 'commander';
 import { type MaterializationReceipt } from '../lib/agent-spec/index.js';
 import { PORTABLE_HARNESSES } from '../lib/packages/output-home.js';
 export { PORTABLE_HARNESSES };
 export type { MaterializationReceipt };
-/** Register `agents packages materialize`. */
 export declare function registerPortablePackageCommands(program: Command): void;

package/dist/commands/packages-materialize.js

@@ -23,7 +23,6 @@ function fail(err, json) {
     }
     die(err instanceof Error ? err.message : String(err), 1, { json });
 }
-/** Register `agents packages materialize`. */
 export function registerPortablePackageCommands(program) {
     const packagesCmd = program
         .command('packages')
@@ -64,8 +63,6 @@ export function registerPortablePackageCommands(program) {
             const resolved = resolveAgentPackage(pkg);
             const receipt = materializeAgentPackage(resolved, { harness, harnessVersion, outputHome });
             if (json) {
-                // Verbatim canonical receipt — byte-identical to the
-                // materialization-receipt.json the materializer wrote into the home.
                 console.log(JSON.stringify(receipt, null, 2));
                 return;
             }

package/dist/commands/packages.d.ts

@@ -1,15 +1,5 @@
-/**
- * Package registry and installation commands.
- *
- * Registers `agents registry`, `agents search`, `agents install`, and
- * `agents packages materialize` for discovering and installing MCP servers,
- * skills, commands, and hooks from configured registries or GitHub sources,
- * and for materializing a schema-v3 agent.yaml package into an ephemeral
- * harness home (PHNX-3838).
- */
 import type { Command } from 'commander';
 import type { McpPackage } from '../lib/types.js';
 import { type McpCommandSpec } from '../lib/mcp.js';
 export declare function buildMcpPackageCommand(pkg: McpPackage): McpCommandSpec;
-/** Register the `agents registry`, `agents search`, `agents install`, and `agents packages` commands. */
 export declare function registerPackagesCommands(program: Command): void;

package/dist/commands/packages.js

@@ -1,12 +1,3 @@
-/**
- * Package registry and installation commands.
- *
- * Registers `agents registry`, `agents search`, `agents install`, and
- * `agents packages materialize` for discovering and installing MCP servers,
- * skills, commands, and hooks from configured registries or GitHub sources,
- * and for materializing a schema-v3 agent.yaml package into an ephemeral
- * harness home (PHNX-3838).
- */
 import * as fs from 'fs';
 import chalk from 'chalk';
 import ora from 'ora';
@@ -36,11 +27,6 @@ export function buildMcpPackageCommand(pkg) {
     }
     throw new Error(`Unsupported MCP runtime: ${pkg.runtime}. Supported: node, python.`);
 }
-/**
- * Picker fallback for `registry enable/config [name]`.
- * Returns the picked name, or null if the user cancels. In non-TTY shells,
- * hard-fails with a clear reminder of the positional form.
- */
 async function pickRegistryName(type, verb, pred) {
     const registries = getRegistries(type);
     const entries = Object.entries(registries).filter(([, cfg]) => (pred ? pred(cfg) : true));
@@ -83,12 +69,8 @@ async function pickRegistryName(type, verb, pred) {
         throw err;
     }
 }
-/** Register the `agents registry`, `agents search`, `agents install`, and `agents packages` commands. */
 export function registerPackagesCommands(program) {
     registerPortablePackageCommands(program);
-    // ==========================================================================
-    // REGISTRY COMMANDS
-    // ==========================================================================
     const registryCmd = program
         .command('registry')
         .description('Manage package registries');
@@ -143,7 +125,6 @@ export function registerPackagesCommands(program) {
             process.exit(1);
         }
         if (!nameArg) {
-            // Show only user-added registries — default registries can't be removed.
             const registries = getRegistries(type);
             const removable = Object.keys(registries).filter((n) => !DEFAULT_REGISTRIES[type]?.[n]);
             requireDestructiveArg({
@@ -155,7 +136,6 @@ export function registerPackagesCommands(program) {
             });
         }
         const name = nameArg;
-        // Check if it's a default registry
         if (DEFAULT_REGISTRIES[type]?.[name]) {
             console.log(chalk.yellow(`Cannot remove default registry '${name}'. Use 'agents registry disable' instead.`));
             process.exit(1);
@@ -199,7 +179,6 @@ export function registerPackagesCommands(program) {
             process.exit(1);
         }
         if (!nameArg) {
-            // Disabling is reversible but still mutates state; force typing.
             const registries = getRegistries(type);
             const candidates = Object.entries(registries)
                 .filter(([, cfg]) => cfg.enabled)
@@ -255,9 +234,6 @@ export function registerPackagesCommands(program) {
         setRegistry(type, name, updates);
         console.log(chalk.green(`Updated ${type} registry '${name}'`));
     });
-    // ==========================================================================
-    // SEARCH COMMAND
-    // ==========================================================================
     program
         .command('search <query>')
         .description('Find packages (MCP servers, skills) across configured registries')
@@ -299,7 +275,6 @@ When to use:
                 return;
             }
             console.log(chalk.bold(`Found ${results.length} packages`));
-            // Group by type
             const mcpResults = results.filter((r) => r.type === 'mcp');
             const skillResults = results.filter((r) => r.type === 'skill');
             if (mcpResults.length > 0) {
@@ -329,9 +304,6 @@ When to use:
             process.exit(1);
         }
     });
-    // ==========================================================================
-    // INSTALL COMMAND (unified package installation)
-    // ==========================================================================
     program
         .command('install <identifier>')
         .description('Install a package: mcp:, skill:, plugin:, or GitHub (gh:user/repo) — one install path (Phase 5)')
@@ -409,7 +381,6 @@ delegate to the same underlying installers.
                     console.log(chalk.yellow(`Warning: missing dependencies: ${missingDeps.join(', ')}`));
                     console.log(chalk.gray('Install them with: agents install plugin:<name>@<source>'));
                 }
-                // Same sync loop as `agents plugins install` (default version per harness).
                 console.log();
                 let synced = 0;
                 for (const agentId of capableAgents('plugins')) {
@@ -445,7 +416,6 @@ delegate to the same underlying installers.
                 return;
             }
             if (resolved.type === 'mcp') {
-                // Install MCP server
                 const entry = resolved.mcpEntry;
                 if (!entry) {
                     console.log(chalk.red('Failed to get MCP server details'));
@@ -458,7 +428,6 @@ delegate to the same underlying installers.
                 if (entry.repository?.url) {
                     console.log(chalk.gray(`  ${entry.repository.url}`));
                 }
-                // Get package info
                 const pkg = entry.packages?.[0];
                 if (!pkg) {
                     console.log(chalk.yellow('\nNo installable package found for this server.'));
@@ -516,15 +485,8 @@ delegate to the same underlying installers.
                 console.log(chalk.green('\nMCP server installed.'));
             }
             else if (resolved.type === 'git' || resolved.type === 'skill') {
-                // Install from git source: sniff every resource type the repo
-                // contains. Optional --types narrows which kinds get installed;
-                // --names narrows which specific resources within those kinds.
                 console.log(chalk.bold(`\nInstalling from ${resolved.source}`));
                 const { localPath } = await cloneRepo(resolved.source);
-                // Integrity: a published skill entry carries the sha256 of its
-                // SKILL.md. Verify the freshly cloned file against it BEFORE
-                // installing anything — a mismatch aborts rather than trusting a
-                // tampered artifact.
                 if (resolved.type === 'skill' && resolved.skillEntry) {
                     const check = verifySkillIntegrity(localPath, resolved.skillEntry);
                     if (!check.ok) {
@@ -543,8 +505,6 @@ delegate to the same underlying installers.
                         return items;
                     return items.filter((item) => requestedNames.has(item.name));
                 };
-                // Discover everything; filter to requested types up front so the
-                // summary table reflects what will actually be installed.
                 let commands = includeType('commands') ? discoverCommands(localPath) : [];
                 let skills = includeType('skills') ? discoverSkillsFromRepo(localPath) : [];
                 let hooks = includeType('hooks') ? discoverHooksFromRepo(localPath) : [];
@@ -552,9 +512,6 @@ delegate to the same underlying installers.
                 let subagents = includeType('subagents') ? discoverSubagentsFromRepo(localPath) : [];
                 let permissions = includeType('permissions') ? discoverPermissionsFromRepo(localPath) : [];
                 let mcpServers = includeType('mcp') ? discoverMcpConfigsFromRepo(localPath) : [];
-                // --names filter applies across every discovered type. If the user
-                // typed a name that matched nothing, fail loud so they can fix the
-                // typo rather than silently install zero items.
                 if (requestedNames.size > 0) {
                     const allNames = new Set([
                         ...commands.map((c) => c.name),
@@ -617,7 +574,6 @@ delegate to the same underlying installers.
                     console.log(chalk.yellow('\nNo agents selected.'));
                     return;
                 }
-                // Install commands
                 if (commands.length > 0) {
                     console.log(chalk.bold('\nInstalling commands...'));
                     let directInstalled = 0;
@@ -661,7 +617,6 @@ delegate to the same underlying installers.
                         console.log(`  ${failed} command installation(s) failed`);
                     }
                 }
-                // Install skills
                 if (skills.length > 0) {
                     console.log(chalk.bold('\nInstalling skills...'));
                     const directAgents = targets.directAgents.filter((agentId) => AGENTS[agentId].capabilities.skills && gitCliStates[agentId]?.installed);
@@ -688,7 +643,6 @@ delegate to the same underlying installers.
                     }
                     console.log(`  Synced skills to ${syncedVersions} managed version(s)`);
                 }
-                // Install hooks
                 if (hooks.length > 0) {
                     console.log(chalk.bold('\nInstalling hooks...'));
                     let syncedVersions = 0;
@@ -710,7 +664,6 @@ delegate to the same underlying installers.
                     }
                     console.log(`  Synced hooks to ${syncedVersions} managed version(s)`);
                 }
-                // Install workflows
                 if (workflows.length > 0) {
                     console.log(chalk.bold('\nInstalling workflows...'));
                     let installed = 0;
@@ -735,7 +688,6 @@ delegate to the same underlying installers.
                     console.log(`  Installed ${installed} workflow(s) to ~/.agents/workflows/`);
                     console.log(`  Synced workflows to ${syncedVersions} managed version(s)`);
                 }
-                // Install subagents
                 if (subagents.length > 0) {
                     console.log(chalk.bold('\nInstalling subagents...'));
                     let installed = 0;
@@ -760,7 +712,6 @@ delegate to the same underlying installers.
                     console.log(`  Installed ${installed} subagent(s) to ~/.agents/subagents/`);
                     console.log(`  Synced subagents to ${syncedVersions} managed version(s)`);
                 }
-                // Install permissions
                 if (permissions.length > 0) {
                     console.log(chalk.bold('\nInstalling permission sets...'));
                     let installed = 0;
@@ -776,7 +727,6 @@ delegate to the same underlying installers.
                     console.log(`  Installed ${installed} permission set(s) to ~/.agents/permissions/`);
                     console.log(chalk.gray('  Apply with: agents permissions apply <name> --agents <selector>'));
                 }
-                // Install MCP server configs
                 if (mcpServers.length > 0) {
                     console.log(chalk.bold('\nInstalling MCP server configs...'));
                     let installed = 0;

package/dist/commands/perf.d.ts

@@ -1,17 +1,3 @@
-/**
- * `agents insights perf` — latency rollups over the disposable perf SQLite
- * warehouse (former top-level `agents perf`, moved under insights in PHNX-3391).
- *
- * Subcommands:
- *   agents insights perf              multi-section summary (commands + hooks + runs)
- *   agents insights perf hooks        per-hook p50/p99 + cache hit rates
- *   agents insights perf commands     slowest CLI command paths (from command.end)
- *   agents insights perf run          agent.run / perf.timing labels
- *   agents insights perf friction     sessions stuck repeatedly hitting the same guard
- *
- * 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';
 import { type PerfAggregateRow } from '../lib/perf/db.js';
 import { type HookProfileRow } from '../lib/hooks/profile.js';
@@ -22,41 +8,14 @@ interface PerfGlobalOpts {
     limit?: string;
     project?: string;
 }
-/** Map warehouse rows shaped like hook.fire into the existing HookProfileRow UI. */
 export declare function asHookRows(rows: PerfAggregateRow[]): HookProfileRow[];
-/**
- * `err:12% block:40% to:4%` when any rate is present, else ''.
- * Exit 2 (intentional deny) is `block:`, not `err:` — so a deny-by-design
- * guard no longer reads as a crashing hook in the table.
- */
 export declare function formatRateColumn(r: {
     errorRate?: number;
     blockRate?: number;
     timeoutRate?: number;
 }): string;
 export declare function renderHookTable(rows: HookProfileRow[], warnMs: number): void;
-/**
- * Prefer SQLite samples; fall back to the legacy daily JSONL so existing
- * instrumentation still surfaces until shims are resynced. `project` only
- * narrows the SQLite path — the legacy JSONL log has no cwd, so a fallback
- * hit ignores it (a caller filtering by project has no legacy rows to miss).
- */
 export declare function loadHookProfile(days: number, project?: string): HookProfileRow[];
-/**
- * Sessions stuck repeatedly hitting the SAME guard block (git-guard,
- * rm-guard, git-require-clean-tree, …) instead of adapting after the first
- * denial. Reads the `friction` event sink (emitFriction in events.ts) that
- * guard hooks self-report into via `agents _internal friction` before they
- * exit 2 — see lib/friction-heuristics.ts for the grouping.
- */
 export declare function frictionAction(opts: PerfGlobalOpts): void;
-/**
- * Attach the `perf` latency-rollup command under a parent (the top-level
- * `insights` group). Performance is an insight, not a top-level noun — `agents
- * perf` was retired in favour of `agents insights perf` (PHNX-3391). It is a
- * sibling of `agents insights cost` / `output`, registered in
- * `registerInsightsCommand` beside them (top-level insights only, not
- * `sessions insights`).
- */
 export declare function registerPerfSubcommand(parent: Command): void;
 export {};

package/dist/commands/perf.js

@@ -1,17 +1,3 @@
-/**
- * `agents insights perf` — latency rollups over the disposable perf SQLite
- * warehouse (former top-level `agents perf`, moved under insights in PHNX-3391).
- *
- * Subcommands:
- *   agents insights perf              multi-section summary (commands + hooks + runs)
- *   agents insights perf hooks        per-hook p50/p99 + cache hit rates
- *   agents insights perf commands     slowest CLI command paths (from command.end)
- *   agents insights perf run          agent.run / perf.timing labels
- *   agents insights perf friction     sessions stuck repeatedly hitting the same guard
- *
- * 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';
@@ -29,7 +15,6 @@ 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. */
 export function asHookRows(rows) {
     return rows.map((r) => ({
         hook: r.label,
@@ -60,11 +45,6 @@ function printTable(headers, widths, lines, slowFlags) {
         console.log(slowFlags[i] ? chalk.yellow(line) : line);
     }
 }
-/**
- * `err:12% block:40% to:4%` when any rate is present, else ''.
- * Exit 2 (intentional deny) is `block:`, not `err:` — so a deny-by-design
- * guard no longer reads as a crashing hook in the table.
- */
 export function formatRateColumn(r) {
     const parts = [];
     if (r.errorRate)
@@ -132,9 +112,6 @@ function renderLabelTable(title, rows, warnMs, limit) {
         formatMs(r.maxMs),
         formatRateColumn(r),
     ]), sliced.map((r) => r.p99Ms > warnMs));
-    // Sub-phase break-out (agent.run's `startup` = spawn overhead before the child
-    // runs, PHNX-3468). Indented under the row so a slow boot is visible next to
-    // the total without adding columns that are empty for phaseless labels.
     for (const r of sliced) {
         if (!r.phases)
             continue;
@@ -143,12 +120,6 @@ function renderLabelTable(title, rows, warnMs, limit) {
         }
     }
 }
-/**
- * Prefer SQLite samples; fall back to the legacy daily JSONL so existing
- * instrumentation still surfaces until shims are resynced. `project` only
- * narrows the SQLite path — the legacy JSONL log has no cwd, so a fallback
- * hit ignores it (a caller filtering by project has no legacy rows to miss).
- */
 export function loadHookProfile(days, project) {
     const fromDb = asHookRows(aggregateSamples({ days, kinds: ['hook.fire'], project }));
     if (fromDb.length > 0 || project)
@@ -187,19 +158,7 @@ function runAction(opts) {
     }
     renderLabelTable('run/timing', rows, warnMs, limit);
 }
-/**
- * Sessions stuck repeatedly hitting the SAME guard block (git-guard,
- * rm-guard, git-require-clean-tree, …) instead of adapting after the first
- * denial. Reads the `friction` event sink (emitFriction in events.ts) that
- * guard hooks self-report into via `agents _internal friction` before they
- * exit 2 — see lib/friction-heuristics.ts for the grouping.
- */
 export function frictionAction(opts) {
-    // --project is declared on the shared `perf` parent for hooks/commands/run,
-    // where every sample carries a cwd. friction events (emitFriction in
-    // events.ts) don't carry one today — agents _internal friction has no
-    // --cwd flag — so silently accepting the flag here would look like it
-    // filtered when it did nothing. Fail loud instead of no-op.
     if (opts.project) {
         console.error(chalk.red("agents insights perf friction does not support --project yet — friction events carry no cwd to filter on."));
         process.exitCode = 1;
@@ -255,24 +214,12 @@ function attachSharedOptions(cmd) {
         .option('--project <key>', 'Scope to one project (the repo directory name a sample\'s cwd resolves to — see project-key.ts)')
         .option('--json', 'Emit JSON instead of a table');
 }
-/**
- * Commander binds a flag declared on both parent and child to the *parent*.
- * Merge so `agents insights 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() };
 }
-/**
- * Attach the `perf` latency-rollup command under a parent (the top-level
- * `insights` group). Performance is an insight, not a top-level noun — `agents
- * perf` was retired in favour of `agents insights perf` (PHNX-3391). It is a
- * sibling of `agents insights cost` / `output`, registered in
- * `registerInsightsCommand` beside them (top-level insights only, not
- * `sessions insights`).
- */
 export function registerPerfSubcommand(parent) {
     const perf = parent
         .command('perf')
@@ -291,8 +238,6 @@ Examples:
   agents insights perf hooks --project agents-cli  # scope to one repo's samples
   agents insights perf friction               # sessions stuck retrying the same guard block
 `);
-    // Options live on the parent so `agents insights perf --json` and
-    // `agents insights perf commands --json` both work (see leafOpts).
     attachSharedOptions(perf).action(function summary() {
         summaryAction(this.opts());
     });

package/dist/commands/permissions.d.ts

@@ -1,13 +1,4 @@
-/**
- * Permission management commands for controlling agent access boundaries.
- *
- * Implements `agents permissions` -- list, add, remove, and view permission
- * sets (allow/deny rules for bash, tools, and filesystem). Supports importing
- * from agent config files, GitHub repos, and YAML, with merge/replace
- * semantics and multi-version targeting.
- */
 import type { Command } from 'commander';
 import { discoverPermissionsFromRepo } from '../lib/permissions.js';
 export declare function shouldRefuseBroadPermissions(permissions: ReturnType<typeof discoverPermissionsFromRepo>, allowBroadPermissions: boolean): boolean;
-/** Register the `agents permissions` command tree (list, add, remove, view). */
 export declare function registerPermissionsCommands(program: Command): void;