@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/perf/spool.d.ts

@@ -1,18 +1,6 @@
-/**
- * Hot-path perf writers — append-only NDJSON spool, no SQLite.
- *
- * Loaded from the CLI root `postAction` and from `events.ts` timing helpers.
- * Must stay free of `../sqlite.js` so ordinary commands never load node:sqlite
- * (which emits ExperimentalWarning on stderr).
- */
 import type { PerfSample } from './types.js';
 export type { PerfSample } from './types.js';
-/** Test seam — pair with db._resetPerfDbForTest. */
 export declare function _resetPerfSpoolForTest(spoolPath?: string | null): void;
 export declare function resolveSpoolPath(): string;
-/** Short session id: first 8 chars (sessions.short_id shape). */
 export declare function shortSessionId(sessionId: string | undefined | null): string | undefined;
-/**
- * Append one sample to the spool. Never throws. Never opens SQLite.
- */
 export declare function recordSample(sample: PerfSample): void;

package/dist/lib/perf/spool.js

@@ -1,10 +1,3 @@
-/**
- * Hot-path perf writers — append-only NDJSON spool, no SQLite.
- *
- * Loaded from the CLI root `postAction` and from `events.ts` timing helpers.
- * Must stay free of `../sqlite.js` so ordinary commands never load node:sqlite
- * (which emits ExperimentalWarning on stderr).
- */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -12,7 +5,6 @@ import { getPerfSpoolPath } from '../state.js';
 import { localMachineId } from '../origin-machine.js';
 let _spoolOverride = null;
 let _disabled = false;
-/** Test seam — pair with db._resetPerfDbForTest. */
 export function _resetPerfSpoolForTest(spoolPath) {
     _spoolOverride = spoolPath === undefined ? null : spoolPath;
     _disabled = false;
@@ -30,16 +22,12 @@ function isDisabled() {
     const v = process.env.AGENTS_DISABLE_PERF;
     return v === '1' || v === 'true';
 }
-/** Short session id: first 8 chars (sessions.short_id shape). */
 export function shortSessionId(sessionId) {
     if (!sessionId)
         return undefined;
     const cleaned = sessionId.replace(/^session_/, '');
     return cleaned.length >= 8 ? cleaned.slice(0, 8) : cleaned || undefined;
 }
-/**
- * Append one sample to the spool. Never throws. Never opens SQLite.
- */
 export function recordSample(sample) {
     if (isDisabled())
         return;
@@ -74,6 +62,5 @@ export function recordSample(sample) {
         fs.appendFileSync(spool, line + '\n', { mode: 0o600 });
     }
     catch {
-        // Fail soft.
     }
 }

package/dist/lib/perf/types.d.ts

@@ -1,17 +1,13 @@
-/** Shared perf sample shape (spool NDJSON + SQLite rows). */
 export type PerfKind = 'hook.fire' | 'perf.timing' | 'command.end' | string;
 export interface PerfSample {
     tsMs?: number;
     kind: PerfKind;
     label: string;
     durationMs: number;
-    /** Full session id — same string as sessions.id when known. */
     sessionId?: string;
-    /** First 8 chars of sessionId (sessions.short_id shape). */
     sessionShort?: string;
     agent?: string;
     agentVersion?: string;
-    /** Fleet registry name (sessions.machine), preferred over raw hostname. */
     machine?: string;
     hostname?: string;
     actor?: string;
@@ -21,9 +17,7 @@ export interface PerfSample {
     status?: string;
     metaJson?: string;
 }
-/** Percentiles for one sub-phase (e.g. agent.run's `startup`) across a bucket. */
 export interface PerfPhaseStat {
-    /** Samples that carried this phase (may be < the row's `n`). */
     n: number;
     p50Ms: number;
     p90Ms: number;
@@ -38,34 +32,15 @@ export interface PerfAggregateRow {
     meanMs: number;
     maxMs: number;
     minMs: number;
-    /**
-     * Per-sub-phase percentiles parsed from each sample's meta_json `phases`.
-     * Present only when at least one sample in the bucket recorded a phase
-     * (agent.run records `startup` — time from spawnAgent entry to child spawn —
-     * so boot cost is trackable independently of the total run, PHNX-3468).
-     */
     phases?: Record<string, PerfPhaseStat>;
     cacheHitPct?: number;
     cacheStalePct?: number;
     cacheMissPct?: number;
     errorCount?: number;
-    /**
-     * Fraction (0-1) of samples with a real crash exit (exit 1 / other nonzero
-     * except the intentional PreToolUse deny code 2). Exit 2 is blockRate.
-     */
     errorRate?: number;
-    /**
-     * Count of intentional deny/block exits (Claude/Codex PreToolUse exit 2).
-     * Not an error — deny-by-design guards (ask-user-question-guard, git-guard,
-     * plan-html-reminder) exit 2 when they block.
-     */
     blockCount?: number;
-    /** Fraction (0-1) of samples with exit code 2 (intentional deny/block). */
     blockRate?: number;
-    /** Fraction (0-1) of samples with status:'timeout'. */
     timeoutRate?: number;
-    /** Project key (see project-key.ts) the row is scoped to — set only when
-     *  the `project` filter narrowed the query to one project. */
     project?: string;
 }
 export interface AggregateOptions {
@@ -75,6 +50,5 @@ export interface AggregateOptions {
     machine?: string;
     agent?: string;
     minN?: number;
-    /** Scope results to samples whose cwd resolves to this project key. */
     project?: string;
 }

package/dist/lib/perf/types.js

@@ -1,2 +1 @@
-/** Shared perf sample shape (spool NDJSON + SQLite rows). */
 export {};

package/dist/lib/permissions-registry.d.ts

@@ -1,64 +1,16 @@
 import type { AgentId, PermissionSet } from './types.js';
-/** Canonical tool (lowercased) -> Grok's lowercase tool vocabulary. */
 export declare const GROK_TOOL_BY_CANONICAL: Record<string, string | undefined>;
-/** Canonical tool -> OpenClaw tool id (tool-level granularity only). */
 export declare const CANONICAL_TO_OPENCLAW_TOOL: Record<string, string>;
-/** Canonical tool -> Antigravity's action namespace. */
 export declare const ANTIGRAVITY_ACTION_BY_TOOL: Record<string, string | undefined>;
-/** Filename Codex stores generated deny rules under `.codex/rules/`. */
 export declare const CODEX_RULES_FILENAME = "agents-deny.rules";
-/**
- * Strip JSON comments for JSONC parsing, only OUTSIDE string literals.
- *
- * A naive `//`-to-end-of-line regex destroys
- * `"$schema": "https://opencode.ai/config.json"` — which every
- * opencode-generated config carries — so the file then fails to parse and its
- * permissions read back as absent, the very defect this registry exists to fix.
- * Exported so `permissions.ts` shares this one implementation instead of
- * keeping its own copy.
- */
 export declare function stripJsonComments(content: string): string;
-/** The complete permissions contract for one agent. */
 interface PermissionTarget {
-    /** Permissions file under a HOME root (a version home, or the real HOME). */
     home(home: string): string;
-    /** Permissions file for a project checkout, when the harness reads one. */
     project?: (cwd: string) => string;
-    /**
-     * Read `configPath` and project it to canonical form. Returns null when the
-     * file is absent, unreadable, or records no permissions — never throws.
-     */
     toCanonical(configPath: string): PermissionSet | null;
-    /** One line naming what this harness's shape loses on the way back. */
     lossyBecause: string;
-    /**
-     * Extra path suffixes this harness's config may use, for DETECTION only.
-     *
-     * `home()`/`project()` may probe the filesystem to pick between accepted
-     * spellings, which is correct when resolving a real root but meaningless for
-     * detection — `detectPermissionAgentFromPath` passes `''`, so the probe would
-     * resolve against `process.cwd()` and make the same input detect differently
-     * depending on where the CLI was run.
-     *
-     * Detection still calls `home('')`/`project('')`, since most targets are pure
-     * `path.join` and need no entry. A target whose resolver probes MUST list
-     * EVERY spelling it can return — that is what makes the probe's answer
-     * irrelevant rather than unreachable. `existingOr` (opencode) is the only
-     * probing resolver today; `permissions-registry.test.ts` pins the invariant
-     * for the whole table rather than leaving it as prose.
-     */
     altSuffixes?: string[];
 }
-/**
- * Single source of truth for where each allowlist-capable agent stores
- * permissions and how to read them back. Keys MUST equal
- * `capableAgents('allowlist')` — pinned by `permissions-registry.test.ts`.
- */
 export declare const PERMISSION_TARGETS: Partial<Record<AgentId, PermissionTarget>>;
-/**
- * Read `agent`'s permissions from `home` (a version home or the real HOME) and
- * project them to canonical form. `scope: 'project'` reads the repo-local file
- * for the harnesses that have one, and returns null for those that do not.
- */
 export declare function readCanonicalPermissions(agent: AgentId, scope?: 'user' | 'project', cwd?: string, home?: string): PermissionSet | null;
 export {};

package/dist/lib/permissions-registry.js

@@ -1,43 +1,8 @@
-/**
- * Declarative permission-target registry.
- *
- * Every allowlist-capable agent gets ONE entry (`PERMISSION_TARGETS`) describing
- * where its permissions live and how to read that file back into the canonical
- * `PermissionSet`. `agents permissions list <agent>` and the config-file import
- * behind `agents permissions add <path>` used to dispatch through hand-written
- * 3-arm switches while
- * `applyPermissionsToVersion` wrote 13 harnesses, so permissions were written
- * for cursor, antigravity, grok, kimi, droid, copilot, openclaw and
- * hermes and then reported as absent for all ten (RUSH-2676).
- *
- * The key set is pinned to `capableAgents('allowlist')` by
- * `permissions-registry.test.ts`, mirroring `SUBAGENT_TARGETS` — the pattern the
- * repo's own AGENTS.md names for cross-harness capabilities. A newly added
- * allowlist harness cannot be written-but-unreadable: it must land an entry here
- * in the same change.
- *
- * This module also OWNS the canonical<->native tool vocabularies. `permissions.ts`
- * imports them for the forward (canonical -> native) serializers, and the reverse
- * projections below are derived from the same tables, so the two directions
- * cannot drift into disagreeing about what `developer__shell` or `fs_read` means.
- *
- * ## Every reverse projection is lossy, and says how
- *
- * The forward direction discards information — several canonical tools collapse
- * onto one native id (`Read`/`Grep`/`Glob` all become a coarse capability), and
- * pattern grammars differ (`git:*` becomes `git *`). Reading back therefore
- * recovers a permission set that GRANTS THE SAME ACCESS, not the byte-identical
- * strings that were written. Each target documents its own collapse. Callers that
- * need a faithful record of what agents-cli installed should read the central
- * `~/.agents/permissions/` set, not a harness's config.
- */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import * as TOML from 'smol-toml';
-// ── canonical <-> native tool vocabularies (single source of truth) ──────────
-/** Canonical tool (lowercased) -> Grok's lowercase tool vocabulary. */
 export const GROK_TOOL_BY_CANONICAL = {
     bash: 'bash',
     read: 'read',
@@ -45,7 +10,6 @@ export const GROK_TOOL_BY_CANONICAL = {
     grep: 'grep',
     webfetch: 'webfetch',
 };
-/** Canonical tool -> OpenClaw tool id (tool-level granularity only). */
 export const CANONICAL_TO_OPENCLAW_TOOL = {
     bash: 'exec',
     read: 'read',
@@ -54,20 +18,12 @@ export const CANONICAL_TO_OPENCLAW_TOOL = {
     webfetch: 'web_fetch',
     websearch: 'web_search',
 };
-/** Canonical tool -> Antigravity's action namespace. */
 export const ANTIGRAVITY_ACTION_BY_TOOL = {
     bash: 'command',
     read: 'read_file',
     write: 'write_file',
     webfetch: 'read_url',
 };
-/**
- * Invert a forward map, keeping the FIRST canonical tool that maps to each
- * native id. Several canonical tools collapse onto one native id, so the
- * inverse must pick a representative; declaration order in the forward table is
- * that choice, which is why `read` (declared before `grep`/`glob`) represents
- * a coarser native capability.
- */
 function invertFirstWins(forward) {
     const out = {};
     for (const [canonical, native] of Object.entries(forward)) {
@@ -81,9 +37,7 @@ function invertFirstWins(forward) {
 const CANONICAL_BY_GROK_TOOL = invertFirstWins(GROK_TOOL_BY_CANONICAL);
 const CANONICAL_BY_OPENCLAW_TOOL = invertFirstWins(CANONICAL_TO_OPENCLAW_TOOL);
 const CANONICAL_BY_ANTIGRAVITY_ACTION = invertFirstWins(ANTIGRAVITY_ACTION_BY_TOOL);
-/** Filename Codex stores generated deny rules under `.codex/rules/`. */
 export const CODEX_RULES_FILENAME = 'agents-deny.rules';
-/** Canonical TitleCase spelling for a lowercased canonical tool name. */
 const CANONICAL_TOOL_CASE = {
     bash: 'Bash',
     read: 'Read',
@@ -101,10 +55,6 @@ const CANONICAL_TOOL_CASE = {
 function titleCaseTool(lower) {
     return CANONICAL_TOOL_CASE[lower] ?? lower;
 }
-/**
- * Inverse of the serializers' `normalizeBashPattern`: native grammars spell a
- * command's arg-glob `git *`, canonical spells it `git:*`. `*` stays `*`.
- */
 function denormalizeBashPattern(pattern) {
     if (pattern === '*' || pattern === '**')
         return '*';
@@ -112,14 +62,12 @@ function denormalizeBashPattern(pattern) {
         return `${pattern.slice(0, -2)}:*`;
     return pattern;
 }
-/** Build a canonical rule string, collapsing a blanket pattern to the tool's wildcard. */
 function canonicalRule(lowerTool, pattern) {
     const tool = titleCaseTool(lowerTool);
     if (pattern === null)
         return lowerTool === 'bash' ? 'Bash(*)' : `${tool}(**)`;
     return `${tool}(${pattern})`;
 }
-/** Assemble a PermissionSet, dropping empty arrays so callers can test truthiness. */
 function permissionSet(allow, deny) {
     const uniqueAllow = [...new Set(allow)];
     const uniqueDeny = [...new Set(deny)];
@@ -131,17 +79,6 @@ function permissionSet(allow, deny) {
         ...(uniqueDeny.length ? { deny: uniqueDeny } : {}),
     };
 }
-// ── file readers ─────────────────────────────────────────────────────────────
-/**
- * Strip JSON comments for JSONC parsing, only OUTSIDE string literals.
- *
- * A naive `//`-to-end-of-line regex destroys
- * `"$schema": "https://opencode.ai/config.json"` — which every
- * opencode-generated config carries — so the file then fails to parse and its
- * permissions read back as absent, the very defect this registry exists to fix.
- * Exported so `permissions.ts` shares this one implementation instead of
- * keeping its own copy.
- */
 export function stripJsonComments(content) {
     let result = '';
     let inString = false;
@@ -226,23 +163,12 @@ function readToml(configPath) {
         return null;
     }
 }
-/** `preferred` unless it is absent and `alternate` exists. */
 function existingOr(preferred, alternate) {
     return !fs.existsSync(preferred) && fs.existsSync(alternate) ? alternate : preferred;
 }
-/** Every string in `value` when it is a string array, else []. */
 function stringList(value) {
     return Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
 }
-/**
- * Invert `convertDenyToCodexRules` (permissions.ts). The writer emits
- * `prefix_rule(pattern=["git", "reset"], decision="forbidden")` from a
- * canonical `Bash(git reset:*)`. Prefix-match is the native form of `:*`,
- * so the reverse always reconstructs `Bash(<parts>:*)`.
- *
- * Only `decision = "forbidden"` is a deny; anything else is skipped rather
- * than guessed into an allow (Codex grants come from sandbox_mode).
- */
 function convertCodexRulesToDeny(content) {
     const deny = [];
     const marker = 'prefix_rule';
@@ -289,7 +215,6 @@ function convertCodexRulesToDeny(content) {
     }
     return deny;
 }
-/** Index of the closer matching `source[openIdx]`, skipping quoted strings. */
 function findMatchingCloser(source, openIdx, open, close) {
     let depth = 0;
     let inString = false;
@@ -334,11 +259,6 @@ function readCodexDenyRules(configPath) {
         return [];
     }
 }
-/**
- * Single source of truth for where each allowlist-capable agent stores
- * permissions and how to read them back. Keys MUST equal
- * `capableAgents('allowlist')` — pinned by `permissions-registry.test.ts`.
- */
 export const PERMISSION_TARGETS = {
     claude: {
         home: (h) => path.join(h, '.claude', 'settings.json'),
@@ -358,14 +278,8 @@ export const PERMISSION_TARGETS = {
         },
     },
     opencode: {
-        // OpenCode accepts either extension and `openCodeConfigPath` probes both, so
-        // an existing `opencode.json` must be found rather than shadowed by the
-        // `.jsonc` default.
         home: (h) => existingOr(path.join(h, '.config', 'opencode', 'opencode.jsonc'), path.join(h, '.config', 'opencode', 'opencode.json')),
         project: (cwd) => existingOr(path.join(cwd, 'opencode.jsonc'), path.join(cwd, 'opencode.json')),
-        // BOTH spellings, for home and project. The preferred one needs an entry
-        // too: `home('')`/`project('')` resolve it through `existingOr`, which
-        // probes, so leaving it out left `opencode.jsonc` detection cwd-dependent.
         altSuffixes: [
             path.join('.config', 'opencode', 'opencode.jsonc'),
             path.join('.config', 'opencode', 'opencode.json'),
@@ -424,7 +338,6 @@ export const PERMISSION_TARGETS = {
             if (!perms || typeof perms !== 'object' || Array.isArray(perms))
                 return null;
             const p = perms;
-            // Cursor spells Bash as Shell(...) and canonical WebSearch as WebFetch(...).
             const back = (rule) => rule.startsWith('Shell') ? rule.replace(/^Shell/, 'Bash') : rule;
             return permissionSet(stringList(p.allow).map(back), stringList(p.deny).map(back));
         },
@@ -538,8 +451,6 @@ export const PERMISSION_TARGETS = {
             if (!locations || typeof locations !== 'object' || Array.isArray(locations))
                 return null;
             const allow = [];
-            // Copilot records approvals per location; the canonical set has no location
-            // axis, so every location's approvals union into one allow list.
             for (const location of Object.values(locations)) {
                 if (!location || typeof location !== 'object' || Array.isArray(location))
                     continue;
@@ -565,7 +476,6 @@ export const PERMISSION_TARGETS = {
                     }
                 }
             }
-            // Copilot's config records approvals (grants) only — it has no deny list.
             return permissionSet(allow, []);
         },
     },
@@ -582,8 +492,6 @@ export const PERMISSION_TARGETS = {
                 const lowerTool = CANONICAL_BY_OPENCLAW_TOOL[id];
                 return lowerTool ? [canonicalRule(lowerTool, null)] : [];
             });
-            // `tools.allow` is OpenClaw's absolute allowlist and is never written by
-            // agents-cli (see convertToOpenClawFormat), so it is not read back either.
             return permissionSet(back(stringList(t.alsoAllow)), back(stringList(t.deny)));
         },
     },
@@ -603,18 +511,9 @@ export const PERMISSION_TARGETS = {
         },
     },
 };
-/**
- * Invert `kimiBashPatterns` + `canonicalToKimiRules`.
- *
- * Kimi writes a bare tool name for a blanket grant (`Bash`, `Read`), and expands
- * one canonical `cmd:*` into TWO picomatch patterns (`Bash(cmd*)` and
- * `Bash(cmd*​/**)`) so slash-bearing arguments match. Both collapse back to the
- * single canonical rule, and the caller dedupes.
- */
 function kimiPatternToCanonical(pattern) {
     const m = pattern.match(/^([\w-]+)\((.*)\)$/);
     if (!m) {
-        // Bare tool name — a blanket grant, or an MCP tool id Kimi matches by name.
         const lower = pattern.toLowerCase();
         return lower in CANONICAL_TOOL_CASE ? canonicalRule(lower, null) : pattern;
     }
@@ -630,11 +529,6 @@ function kimiPatternToCanonical(pattern) {
     }
     return canonicalRule(lowerTool, arg);
 }
-/**
- * Read `agent`'s permissions from `home` (a version home or the real HOME) and
- * project them to canonical form. `scope: 'project'` reads the repo-local file
- * for the harnesses that have one, and returns null for those that do not.
- */
 export function readCanonicalPermissions(agent, scope = 'user', cwd, home) {
     const target = PERMISSION_TARGETS[agent];
     if (!target)
@@ -644,7 +538,5 @@ export function readCanonicalPermissions(agent, scope = 'user', cwd, home) {
             return null;
         return target.toCanonical(target.project(cwd ?? process.cwd()));
     }
-    // os.homedir() -- not `process.env.HOME ?? ''`, which resolved a RELATIVE
-    // path (`.grok/config.toml`) when HOME is unset, as it is on Windows.
     return target.toCanonical(target.home(home ?? os.homedir()));
 }