@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/types.js

@@ -1,55 +1,15 @@
-/**
- * Core type definitions for agents-cli.
- *
- * Every data structure that flows between modules lives here: agent identity,
- * configuration schemas, resource tracking, registry types, and permission
- * formats for each supported agent.
- */
-/** Unique identifier for a current or legacy AI coding agent. */
 export const AGENT_IDS = ['claude', 'codex', 'cursor', 'opencode', 'openclaw', 'copilot', 'amp', 'goose', 'antigravity', 'grok', 'kimi', 'droid', 'hermes', 'muse', 'warp'];
 export function isAgentId(value) {
     return AGENT_IDS.includes(value);
 }
-/**
- * Reserved `<agent>` keyword for `agents run auto` — full-auto dispatch:
- * host (14d launch affinity) → harness (best-account headroom, weighted) →
- * account (balanced). Lives in lib (not commands/) because both the run
- * command (exec.ts) and the host dispatch layer (hosts/dispatch.ts, which
- * arms the chain-hop guard for remote `run auto`) must agree on it.
- */
 export const RUN_AUTO_KEYWORD = 'auto';
-/**
- * Env var a host dispatcher exports into the remote SHELL when it dispatches
- * `agents run auto`: tells the remote CLI its host layer is already resolved,
- * so it must not re-run affinity and chain-hop to a third host. It rides the
- * shell-export prelude (hosts/dispatch.ts `remoteRunShellPrelude`) because
- * `--env` flags only reach the spawned AGENT's env — the remote CLI's own
- * process.env (which exec.ts `runAutoDefaultsToAffinity` reads) never sees them.
- */
 export const RUN_AUTO_HOST_RESOLVED_ENV = 'AGENTS_RUN_AUTO_HOST_RESOLVED';
-/**
- * Env var a host dispatcher exports into the remote SHELL when it opens an
- * INTERACTIVE `--device` run: tells the remote CLI that this agent's stdio is a
- * network link, so the run must be detached (tmux-wrapped) to outlive it.
- *
- * Rides the same shell-export prelude as {@link RUN_AUTO_HOST_RESOLVED_ENV},
- * and for the same reason — exec.ts `resolveTmuxWrap` reads the remote CLI's own
- * `process.env`, which `--env` flags (they reach only the spawned AGENT) never
- * touch.
- *
- * Set ONLY on the interactive path. A headless `--device` dispatch is already
- * detached with setsid by `launchDetached`, so it neither needs nor gets this.
- */
 export const REMOTE_INTERACTIVE_ENV = 'AGENTS_REMOTE_INTERACTIVE';
-/** Every canonical mode in declaration order. Useful for iteration / validation. */
 export const ALL_MODES = ['plan', 'edit', 'auto', 'skip'];
-/** Canonical system repo cloned into ~/.agents/.system/. */
 export const DEFAULT_SYSTEM_REPO = 'gh:phnx-labs/.agents-system';
-/** Strip the `gh:` prefix and `.git` suffix to get a GitHub `owner/repo` slug. */
 export function systemRepoSlug(repo = DEFAULT_SYSTEM_REPO) {
     return repo.replace(/^gh:/, '').replace(/\.git$/, '');
 }
-/** Built-in registry endpoints shipped with agents-cli. */
 export const DEFAULT_REGISTRIES = {
     mcp: {
         official: {
@@ -59,19 +19,9 @@ export const DEFAULT_REGISTRIES = {
     },
     skill: {},
 };
-/**
- * Third-party registries pre-seeded on first install for discoverability.
- *
- * These ship into new users' agents.yaml once, but are not "defaults" — after
- * seeding they behave like any user-added registry (listable, disable-able,
- * removable). Removed users can `agents registry remove <name>` to opt out;
- * once removed they don't come back.
- */
 export const SEEDED_REGISTRIES = {
     mcp: {},
     skill: {
-        // Hermes Agent (Nous Research) — flat JSON index of 1800+ skills aggregated
-        // from official, github, lobehub, skills.sh, and claude-marketplace. No auth.
         hermes: {
             url: 'https://hermes-agent.nousresearch.com/docs/api/skills-index.json',
             enabled: true,

package/dist/lib/uninstall.d.ts

@@ -1,5 +1,4 @@
 import type { AgentId } from './types.js';
-/** What the uninstall intends to do with one agent's config directory. */
 export type ConfigAction = {
     agent: AgentId;
     realPath: string;
@@ -27,13 +26,10 @@ export type ConfigAction = {
     realPath: string;
     kind: 'absent';
 };
-/** A home-level file symlink (e.g. `~/.claude.json`) agents-cli owns. */
 export interface HomeFileAction {
     realPath: string;
-    /** Resolved symlink target whose contents are copied back to `realPath`. */
     source: string;
 }
-/** The full, read-only plan describing what an uninstall would change. */
 export interface UninstallPlan {
     isInstalled: boolean;
     agentsDir: string;
@@ -43,7 +39,6 @@ export interface UninstallPlan {
     launchers: string[];
     rcFiles: string[];
 }
-/** Structured result of an executed uninstall (for reporting). */
 export interface UninstallResult {
     restoredConfigs: Array<{
         agent: AgentId;
@@ -62,22 +57,10 @@ export interface UninstallResult {
         movedTo?: string;
     };
     legacySymlinkRemoved: boolean;
-    /** True when `--purge` was requested but downgraded to move-aside after errors. */
     purgeDowngraded: boolean;
     errors: string[];
 }
-/**
- * Build a read-only plan of everything a complete uninstall would change.
- * Performs no mutations; safe to run for `--dry-run` and to print for confirm.
- */
 export declare function planUninstall(): UninstallPlan;
-/**
- * Execute a plan built by {@link planUninstall}. Restores adopted config dirs
- * and home files, releases adopted launchers, strips shim PATH lines, then
- * disposes of `~/.agents` — moved aside to `~/.agents.removed-<ts>` (recoverable)
- * by default, or hard-deleted when `purge` is set. Config restore always runs
- * before disposal because the backups live inside `~/.agents`.
- */
 export declare function executeUninstall(plan: UninstallPlan, opts: {
     purge?: boolean;
     timestamp: number;

package/dist/lib/uninstall.js

@@ -1,20 +1,3 @@
-/**
- * Complete teardown of agents-cli — the reverse of `agents setup`.
- *
- * The hard part is undoing "adoption": normal installs move the user's real
- * `~/.<agent>` aside and replace it with a symlink into agents-cli's version
- * homes (see `switchConfigSymlink` / `importAgent`). A clean uninstall must put
- * those real directories back, release any adopted launchers, strip the shim
- * directory from the user's PATH, and only then dispose of `~/.agents`.
- *
- * Safety invariant: a `~/.<agent>` that agents-cli never adopted is a REAL user
- * directory and is never touched. Ownership is decided structurally by
- * `getConfigSymlinkVersion` (non-null only for a symlink into our versions dir),
- * exactly as `removeVersion` does it — no marker files, no guessing.
- *
- * This module is split into a read-only {@link planUninstall} and a mutating
- * {@link executeUninstall} so `--dry-run` and the real run share one code path.
- */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -22,11 +5,9 @@ import { AGENTS, ALL_AGENT_IDS } from './agents.js';
 import { getAgentConfigPath, getConfigSymlinkVersion, stripShimPathLines, releaseAdoptedLauncher, removeGhOverloadShim, } from './installations/shims.js';
 import { moveDirCrossDevice, copyDirStrippingAgentsSymlinks } from './config-transfer.js';
 import { getUserAgentsDir, getBackupsDir, getHistoryDir, getShimsDir, getLegacySystemAgentsDir, } from './state.js';
-/** Home dir honoring the AGENTS_REAL_HOME test/override, mirroring shims.ts. */
 function realHome() {
     return process.env.AGENTS_REAL_HOME || os.homedir();
 }
-/** Newest timestamped backup dir under `<backups>/<agent>/`, or null. */
 function newestBackupDir(agent) {
     const dir = path.join(getBackupsDir(), agent);
     let entries;
@@ -41,7 +22,6 @@ function newestBackupDir(agent) {
     entries.sort((a, b) => Number(a) - Number(b));
     return path.join(dir, entries[entries.length - 1]);
 }
-/** Absolute target of a symlink, or null if `p` is not a readable symlink. */
 function symlinkTarget(p) {
     try {
         const raw = fs.readlinkSync(p);
@@ -51,17 +31,9 @@ function symlinkTarget(p) {
         return null;
     }
 }
-/**
- * Remove a symlink/junction at `p` without following into its target. On POSIX
- * this is a plain `unlinkSync`; on Windows the same call correctly deletes a
- * junction or directory-symlink reparse point while leaving the target intact —
- * verified on a real Windows host, where `fs.rmSync(p, { force: true })` instead
- * throws `EFAULT` on a reparse point. `rmSync` is deliberately NOT used here.
- */
 function removeLink(p) {
     fs.unlinkSync(p);
 }
-/** Classify one agent's config dir without mutating anything. */
 function planConfig(agent) {
     const realPath = getAgentConfigPath(agent);
     let stat;
@@ -71,15 +43,10 @@ function planConfig(agent) {
     catch {
         return { agent, realPath, kind: 'absent' };
     }
-    // A real directory means agents-cli never adopted it — leave it alone.
     if (!stat.isSymbolicLink())
         return { agent, realPath, kind: 'leave-real' };
-    // A symlink we don't own (target not under our versions dir) — leave it alone.
     if (getConfigSymlinkVersion(agent) === null)
         return { agent, realPath, kind: 'leave-foreign' };
-    // Owned symlink: prefer the timestamped backup (switchConfigSymlink moved the
-    // real dir there); otherwise the symlink target itself holds the user's data
-    // (importAgent renamed the real dir INTO the version home).
     const backup = newestBackupDir(agent);
     if (backup)
         return { agent, realPath, kind: 'restore-backup', source: backup };
@@ -89,7 +56,6 @@ function planConfig(agent) {
     }
     return { agent, realPath, kind: 'remove-dangling' };
 }
-/** Owned home-file symlinks (e.g. `~/.claude.json`) to copy back as real files. */
 function planHomeFiles() {
     const home = realHome();
     const userDir = getUserAgentsDir();
@@ -110,7 +76,6 @@ function planHomeFiles() {
             if (!stat.isSymbolicLink())
                 continue;
             const target = symlinkTarget(realPath);
-            // Only ours (points into ~/.agents) and only if the target still exists.
             if (target && target.startsWith(userDir + path.sep) && fs.existsSync(target)) {
                 out.push({ realPath, source: target });
             }
@@ -118,7 +83,6 @@ function planHomeFiles() {
     }
     return out;
 }
-/** cliCommand basenames that have an adopted-launcher record to release. */
 function planLaunchers() {
     const dir = path.join(getHistoryDir(), 'adopted-launchers');
     try {
@@ -128,7 +92,6 @@ function planLaunchers() {
         return [];
     }
 }
-/** Candidate shell rc files that currently contain a shim PATH entry. */
 function planRcFiles() {
     const home = realHome();
     const shimsDir = getShimsDir();
@@ -148,18 +111,11 @@ function planRcFiles() {
     }
     return out;
 }
-/**
- * Build a read-only plan of everything a complete uninstall would change.
- * Performs no mutations; safe to run for `--dry-run` and to print for confirm.
- */
 export function planUninstall() {
     const agentsDir = getUserAgentsDir();
     const legacy = getLegacySystemAgentsDir();
     let legacySymlink = null;
     try {
-        // Only claim it if it's actually a link (symlink on POSIX, junction on Windows —
-        // both report isSymbolicLink()); a real directory here is left alone so removeLink
-        // (unlinkSync) is always the correct primitive for what we captured.
         if (fs.lstatSync(legacy).isSymbolicLink())
             legacySymlink = legacy;
     }
@@ -176,13 +132,6 @@ export function planUninstall() {
         rcFiles: planRcFiles(),
     };
 }
-/**
- * Execute a plan built by {@link planUninstall}. Restores adopted config dirs
- * and home files, releases adopted launchers, strips shim PATH lines, then
- * disposes of `~/.agents` — moved aside to `~/.agents.removed-<ts>` (recoverable)
- * by default, or hard-deleted when `purge` is set. Config restore always runs
- * before disposal because the backups live inside `~/.agents`.
- */
 export function executeUninstall(plan, opts) {
     const result = {
         restoredConfigs: [],
@@ -195,24 +144,14 @@ export function executeUninstall(plan, opts) {
         purgeDowngraded: false,
         errors: [],
     };
-    // 1. Restore adopted config directories (reads backups inside ~/.agents).
     for (const c of plan.configs) {
         try {
             if (c.kind === 'restore-backup') {
-                // The adopted link carries no data (the real dir is the backup); drop it,
-                // then move the backup out of ~/.agents onto the real path — EXDEV-safe so a
-                // cross-volume ~/.agents can't strand the backup mid-restore. unlinkSync (not
-                // rmSync) is deliberate: it removes a POSIX symlink AND a Windows junction/
-                // dir-symlink without following into the target, whereas rmSync throws EFAULT
-                // on a Windows reparse point.
                 removeLink(c.realPath);
                 moveDirCrossDevice(c.source, c.realPath);
                 result.restoredConfigs.push({ agent: c.agent, realPath: c.realPath });
             }
             else if (c.kind === 'restore-version-home') {
-                // importAgent renamed the real dir INTO the version home; copy it back
-                // (step 6 disposes the original) while stripping resource symlinks that
-                // would dangle once ~/.agents is gone.
                 removeLink(c.realPath);
                 copyDirStrippingAgentsSymlinks(c.source, c.realPath, plan.agentsDir);
                 result.restoredConfigs.push({ agent: c.agent, realPath: c.realPath });
@@ -221,13 +160,11 @@ export function executeUninstall(plan, opts) {
                 removeLink(c.realPath);
                 result.removedDanglingConfigs.push({ agent: c.agent, realPath: c.realPath });
             }
-            // leave-real / leave-foreign / absent: intentionally untouched.
         }
         catch (err) {
             result.errors.push(`config ${c.agent} (${c.realPath}): ${err.message}`);
         }
     }
-    // 2. Restore owned home-file symlinks as real files (e.g. ~/.claude.json).
     for (const hf of plan.homeFiles) {
         try {
             removeLink(hf.realPath);
@@ -238,7 +175,6 @@ export function executeUninstall(plan, opts) {
             result.errors.push(`home file ${hf.realPath}: ${err.message}`);
         }
     }
-    // 3. Release adopted launchers (reads records inside ~/.agents).
     const byCli = new Map(ALL_AGENT_IDS.map((a) => [AGENTS[a].cliCommand, a]));
     for (const cli of plan.launchers) {
         const agent = byCli.get(cli);
@@ -252,16 +188,12 @@ export function executeUninstall(plan, opts) {
             result.errors.push(`launcher ${cli}: ${err.message}`);
         }
     }
-    // 3b. Remove the gh overload shim explicitly, so a real gh returns even if the
-    // shims dir itself is left in place. (The shim self-heals to real gh regardless,
-    // but leaving no orphan is cleaner — PHNX-3501.)
     try {
         removeGhOverloadShim();
     }
     catch (err) {
         result.errors.push(`gh overload shim: ${err.message}`);
     }
-    // 4. Strip the shim directory from the user's PATH across all rc files.
     const shimsDir = getShimsDir();
     for (const rc of plan.rcFiles) {
         try {
@@ -273,10 +205,6 @@ export function executeUninstall(plan, opts) {
             result.errors.push(`rc file ${rc}: ${err.message}`);
         }
     }
-    // 5. Remove the legacy back-compat symlink, if present. `~/.agents-system` is a
-    // link (junction on Windows — createLink uses 'junction' for a dir source), so it
-    // goes through removeLink for the same reason as the config links: rmSync throws
-    // EFAULT on a Windows reparse point.
     if (plan.legacySymlink) {
         try {
             removeLink(plan.legacySymlink);
@@ -286,9 +214,6 @@ export function executeUninstall(plan, opts) {
             result.errors.push(`legacy ${plan.legacySymlink}: ${err.message}`);
         }
     }
-    // 6. Dispose of ~/.agents LAST (its backups fed step 1). If any restore above
-    // failed, downgrade a --purge to a recoverable move-aside: a swallowed restore
-    // error must never let the hard-delete take the user's only copy with it.
     if (fs.existsSync(plan.agentsDir)) {
         const purge = !!opts.purge && result.errors.length === 0;
         if (opts.purge && !purge)

package/dist/lib/usage-backoff.d.ts

@@ -1,30 +1,10 @@
 import type { AgentId } from './types.js';
 export declare function setUsageBackoffDirForTest(dir: string | null): string | null;
-/**
- * Parse a `Retry-After` header. HTTP allows either delta-seconds or an HTTP
- * date; both appear in the wild, so handle both and ignore anything else.
- * Returns milliseconds from `now`, or null when there is nothing usable.
- */
 export declare function parseRetryAfterMs(header: string | null | undefined, now?: number): number | null;
-/**
- * Record that `agent`'s usage endpoint threw a 429. `retryAfter` is the raw
- * header; when it is absent or unparseable we still back off for `fallbackMs`,
- * because continuing to poll an endpoint that just said no is what created the
- * loop in the first place.
- */
 export declare function noteUsageRateLimited(agent: AgentId, retryAfter: string | null | undefined, opts?: {
     now?: number;
     fallbackMs?: number;
     account?: string | null;
 }): void;
-/**
- * Epoch ms until which `agent`'s usage endpoint should not be called, or null
- * when it is free — the furthest recorded deadline still in the future, so a
- * concurrently-written shorter one can never pull it in.
- *
- * Sweeps elapsed files while it is here: they can only accumulate at the rate
- * penalties are issued, and this is the one place that already lists them.
- */
 export declare function usageRateLimitedUntil(agent: AgentId, now?: number, account?: string | null): number | null;
-/** Human-readable remaining backoff, for the error a skipped read returns. */
 export declare function formatBackoffRemaining(untilMs: number, now?: number): string;

package/dist/lib/usage-backoff.js

@@ -52,18 +52,10 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir } from './state.js';
-/** Cap a server-supplied delay so a bad header cannot park a provider forever. */
 const MAX_BACKOFF_MS = 60 * 60 * 1000;
-/**
- * Test seam, mirroring `setKeychainBackendForTest`. The cache dir is resolved
- * from a module-level constant at import time, so overriding `HOME` in a test
- * does NOT redirect this state — it silently writes into the developer's real
- * `~/.agents/.cache/` and parks their own usage reads behind a 45-minute
- * penalty. (It did exactly that once while this was being written.) Returns the
- * previous value so a test can restore it.
- */
 let backoffDirOverride = null;
 export function setUsageBackoffDirForTest(dir) {
+    // Tests redirect this seam so rate-limit probes cannot write the operator cache.
     const prev = backoffDirOverride;
     backoffDirOverride = dir;
     return prev;
@@ -71,12 +63,8 @@ export function setUsageBackoffDirForTest(dir) {
 function backoffDir() {
     return backoffDirOverride ?? path.join(getCacheDir(), 'usage-backoff');
 }
-/**
- * Parse a `Retry-After` header. HTTP allows either delta-seconds or an HTTP
- * date; both appear in the wild, so handle both and ignore anything else.
- * Returns milliseconds from `now`, or null when there is nothing usable.
- */
 export function parseRetryAfterMs(header, now = Date.now()) {
+    // Server delays cap at one hour; an unusable header falls through to the caller's fallback.
     const raw = (header ?? '').trim();
     if (!raw)
         return null;
@@ -90,32 +78,17 @@ export function parseRetryAfterMs(header, now = Date.now()) {
     const ms = at - now;
     return ms > 0 ? Math.min(ms, MAX_BACKOFF_MS) : null;
 }
-/**
- * File-name scope for a penalty. Provider-wide penalties are `<agent>`;
- * account-scoped ones are `<agent>@<slug>` (RUSH-3036), where the slug is the
- * account's usage key with path separators neutralized (usage keys carry `:`,
- * `=`, `.` and `@` freely — all filename-safe on the platforms we run on).
- * `@` cannot collide with the provider scope because provider files are always
- * `<agent>.<digits>` and agent ids never contain `@`.
- */
 function backoffScope(agent, account) {
     if (!account)
         return agent;
     return `${agent}@${account.replace(/[/\\]/g, '_')}`;
 }
-/**
- * Every recorded deadline for `scope`. A file belongs to the scope only when
- * everything after `<scope>.` is pure digits — account slugs contain dots
- * (emails inside usage keys), so a bare prefix match would let scope
- * `claude@a` swallow `claude@a.b`'s files.
- */
 function deadlinesFor(scope) {
     let names;
     try {
         names = fs.readdirSync(backoffDir());
     }
     catch {
-        // No directory yet: nothing is throttled.
         return [];
     }
     const prefix = `${scope}.`;
@@ -132,48 +105,20 @@ function deadlinesFor(scope) {
     }
     return out;
 }
-/**
- * Record that `agent`'s usage endpoint threw a 429. `retryAfter` is the raw
- * header; when it is absent or unparseable we still back off for `fallbackMs`,
- * because continuing to poll an endpoint that just said no is what created the
- * loop in the first place.
- */
 export function noteUsageRateLimited(agent, retryAfter, opts) {
+    // Each deadline gets its own file so concurrent processes can only increase the effective backoff.
     const now = opts?.now ?? Date.now();
     const fallbackMs = opts?.fallbackMs ?? 15 * 60 * 1000;
     const ms = parseRetryAfterMs(retryAfter, now) ?? fallbackMs;
     const deadline = now + Math.min(ms, MAX_BACKOFF_MS);
     try {
         fs.mkdirSync(backoffDir(), { recursive: true });
-        // Empty file: the name carries the whole value, so there is no content a
-        // concurrent reader could catch half-written, and no document to merge.
-        //
-        // With an account, the penalty is scoped to THAT account (RUSH-3036): the
-        // observed 429s are per-account quotas, and a provider-wide park let the
-        // first throttled account starve every account after it in the refresh
-        // loop's fixed order — the same 4 accounts stayed 'usage unavailable'
-        // across passes while their siblings refreshed. Callers with no account
-        // identity still record provider-wide, which continues to park everything.
         fs.writeFileSync(path.join(backoffDir(), `${backoffScope(agent, opts?.account)}.${deadline}`), '');
     }
     catch {
-        // Best-effort. An unwritable cache dir costs the cross-process backoff, not
-        // the correctness of this read.
     }
 }
-/**
- * Epoch ms until which `agent`'s usage endpoint should not be called, or null
- * when it is free — the furthest recorded deadline still in the future, so a
- * concurrently-written shorter one can never pull it in.
- *
- * Sweeps elapsed files while it is here: they can only accumulate at the rate
- * penalties are issued, and this is the one place that already lists them.
- */
 export function usageRateLimitedUntil(agent, now = Date.now(), account) {
-    // A provider-wide penalty parks every account; an account-scoped read also
-    // honors that account's own penalties. A bare (no-account) read deliberately
-    // ignores account-scoped penalties — one pinned account must not park its
-    // siblings (RUSH-3036).
     const scopes = account ? [backoffScope(agent, null), backoffScope(agent, account)] : [backoffScope(agent, null)];
     let latest = null;
     for (const scope of scopes) {
@@ -187,14 +132,12 @@ export function usageRateLimitedUntil(agent, now = Date.now(), account) {
                     fs.rmSync(path.join(backoffDir(), `${scope}.${at}`), { force: true });
                 }
                 catch {
-                    /* another process may have swept it already */
                 }
             }
         }
     }
     return latest;
 }
-/** Human-readable remaining backoff, for the error a skipped read returns. */
 export function formatBackoffRemaining(untilMs, now = Date.now()) {
     const mins = Math.ceil((untilMs - now) / 60_000);
     if (mins <= 1)