@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/standalone-tools.js

@@ -0,0 +1,58 @@
+import { installCli, installedCliVersion } from './cli-resources.js';
+import { compareVersions } from './agent-spec/primitives.js';
+import { SECRETS_CLI_PACKAGE, SECRETS_CLI_VERSION } from './secrets-cli.js';
+export const STANDALONE_TOOLS = ['sessions', 'browser', 'secrets', 'computer', 'term'];
+export const STANDALONE_TOOL_PINS = {
+    sessions: { tool: 'sessions', pkg: '@phnx-labs/sessions-cli', floor: '0.5.0' },
+    browser: { tool: 'browser', pkg: '@phnx-labs/browser-cli', floor: '0.1.15' },
+    secrets: { tool: 'secrets', pkg: SECRETS_CLI_PACKAGE, floor: SECRETS_CLI_VERSION },
+    computer: { tool: 'computer', pkg: '@phnx-labs/computer-cli', floor: '0.1.5' },
+    term: { tool: 'term', pkg: '@phnx-labs/term-cli', floor: '0.1.0' },
+};
+export function pinnedSpec(tool) {
+    const pin = STANDALONE_TOOL_PINS[tool];
+    return `${pin.pkg}@${pin.floor}`;
+}
+function pinManifest(tool) {
+    return {
+        name: tool,
+        check: { kind: 'version', cmd: tool, args: ['--version'] },
+        install: [{ npm: pinnedSpec(tool) }],
+        source: 'builtin',
+        path: '',
+    };
+}
+export function meetsFloor(installed, floor) {
+    return installed !== null && compareVersions(installed, floor) >= 0;
+}
+export async function readToolPins(tools = STANDALONE_TOOLS) {
+    return Promise.all(tools.map(async (tool) => {
+        const pin = STANDALONE_TOOL_PINS[tool];
+        const installed = await installedCliVersion(pinManifest(tool));
+        const state = meetsFloor(installed, pin.floor) ? 'ok' : installed === null ? 'missing' : 'outdated';
+        return { tool, pkg: pin.pkg, floor: pin.floor, installed, state };
+    }));
+}
+export async function ensureToolPins(opts = {}) {
+    const before = await readToolPins(opts.tools);
+    const out = [];
+    for (const row of before) {
+        if (row.state === 'ok' || opts.dryRun) {
+            out.push(row);
+            continue;
+        }
+        const result = installCli(pinManifest(row.tool), { logToStderr: opts.logToStderr });
+        const installed = await installedCliVersion(pinManifest(row.tool));
+        if (result.error || !meetsFloor(installed, row.floor)) {
+            out.push({
+                ...row,
+                installed,
+                state: 'failed',
+                error: result.error ?? `\`${row.tool} --version\` reads ${installed ?? 'nothing'} after installing ${pinnedSpec(row.tool)}; another install on PATH shadows it`,
+            });
+            continue;
+        }
+        out.push({ ...row, installed, state: row.state === 'missing' ? 'installed' : 'upgraded' });
+    }
+    return out;
+}

package/dist/lib/star-nudge.d.ts

@@ -1,45 +1,13 @@
-/**
- * One-time "star us on GitHub" nudge.
- *
- * Printed a single time, ever, after a user's first *successful* headline run
- * (`agents run` / `agents teams`). Modelled on the existing warn-once sentinel
- * pattern (see maybeWarnMultiInstall in src/index.ts): a marker under the
- * regenerable runtime-state dir records that the hint was shown so it never
- * repeats. It is a plain inline line — not a toast, not a nag — and stays out
- * of the way of non-interactive, CI, quiet, and JSON output.
- */
-/** Canonical GitHub repo the nudge points at (renamed from agents-cli). */
 export declare const REPO_URL = "https://github.com/phnx-labs/agi-cli";
-/** Has the star nudge already been shown on this machine? */
 export declare function hasShownStarNudge(): boolean;
-/** Inputs to the pure show/skip decision (kept side-effect free for testing). */
 export interface StarNudgeContext {
-    /** Caller asked for quiet / JSON output. */
     quiet?: boolean;
-    /** stdout is attached to an interactive terminal. */
     isTTY: boolean;
-    /** CI is set in the environment. */
     ci: boolean;
-    /** User opted out via AGENTS_NO_NUDGE=1. */
     optedOut: boolean;
-    /** The one-time sentinel already exists. */
     alreadyShown: boolean;
 }
-/**
- * Pure decision: should the one-time star nudge be shown? Skipped for
- * quiet/JSON output, non-interactive terminals (pipes, redirects), CI, an
- * explicit opt-out, or once it has already been shown.
- */
 export declare function shouldShowStarNudge(ctx: StarNudgeContext): boolean;
-/**
- * Show the one-time star nudge if it hasn't been shown yet and the context is
- * appropriate. Best-effort by contract: never throws, never blocks the run it
- * follows.
- *
- * Skipped when: the caller asked for quiet/JSON output, stdout is not an
- * interactive terminal (pipes, redirects), CI is set, or the user opted out
- * with AGENTS_NO_NUDGE=1.
- */
 export declare function maybeShowStarNudge(opts?: {
     quiet?: boolean;
 }): void;

package/dist/lib/star-nudge.js

@@ -1,24 +1,11 @@
-/**
- * One-time "star us on GitHub" nudge.
- *
- * Printed a single time, ever, after a user's first *successful* headline run
- * (`agents run` / `agents teams`). Modelled on the existing warn-once sentinel
- * pattern (see maybeWarnMultiInstall in src/index.ts): a marker under the
- * regenerable runtime-state dir records that the hint was shown so it never
- * repeats. It is a plain inline line — not a toast, not a nag — and stays out
- * of the way of non-interactive, CI, quiet, and JSON output.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
 import { getRuntimeStateDir } from './state.js';
-/** Canonical GitHub repo the nudge points at (renamed from agents-cli). */
 export const REPO_URL = 'https://github.com/phnx-labs/agi-cli';
-/** Sentinel written the first (and only) time the nudge is shown. */
 function nudgeSentinelPath() {
     return path.join(getRuntimeStateDir(), 'star-nudge-shown');
 }
-/** Has the star nudge already been shown on this machine? */
 export function hasShownStarNudge() {
     try {
         return fs.existsSync(nudgeSentinelPath());
@@ -27,11 +14,6 @@ export function hasShownStarNudge() {
         return false;
     }
 }
-/**
- * Pure decision: should the one-time star nudge be shown? Skipped for
- * quiet/JSON output, non-interactive terminals (pipes, redirects), CI, an
- * explicit opt-out, or once it has already been shown.
- */
 export function shouldShowStarNudge(ctx) {
     if (ctx.quiet)
         return false;
@@ -45,15 +27,6 @@ export function shouldShowStarNudge(ctx) {
         return false;
     return true;
 }
-/**
- * Show the one-time star nudge if it hasn't been shown yet and the context is
- * appropriate. Best-effort by contract: never throws, never blocks the run it
- * follows.
- *
- * Skipped when: the caller asked for quiet/JSON output, stdout is not an
- * interactive terminal (pipes, redirects), CI is set, or the user opted out
- * with AGENTS_NO_NUDGE=1.
- */
 export function maybeShowStarNudge(opts = {}) {
     try {
         const show = shouldShowStarNudge({
@@ -65,12 +38,6 @@ export function maybeShowStarNudge(opts = {}) {
         });
         if (!show)
             return;
-        // Claim the one-time slot with an ATOMIC exclusive create (O_EXCL). The
-        // hasShownStarNudge() check above is only a cheap fast-path; the existsSync
-        // + write pair is a TOCTOU race across processes, and `agents teams` spawns
-        // many at once. The `wx` flag makes the create itself the arbiter: exactly
-        // one process succeeds, every other gets EEXIST and stays silent — so the
-        // hint prints at most once even under concurrent completions.
         const sentinel = nudgeSentinelPath();
         fs.mkdirSync(path.dirname(sentinel), { recursive: true });
         try {
@@ -78,14 +45,13 @@ export function maybeShowStarNudge(opts = {}) {
         }
         catch (e) {
             if (e.code === 'EEXIST')
-                return; // another process won the race
-            throw e; // real write failure -> caught by the outer best-effort guard
+                return;
+            throw e;
         }
         console.log('\n' +
             chalk.gray('Enjoying agents-cli? Give it a star to help others find it: ') +
             chalk.cyan(REPO_URL));
     }
     catch {
-        /* best-effort: a nudge must never break a successful run */
     }
 }

package/dist/lib/startup/command-registry.d.ts

@@ -1,48 +1,3 @@
-/**
- * Every top-level command name the CLI answers to — the loader table plus the
- * inline aliases/tombstones above. This is the "does this command exist?"
- * predicate for code that runs BEFORE commander parses, most importantly the
- * `--device` router (lib/hosts/passthrough.ts): without it a typo'd
- * command carrying `--device` reported a flag-support error instead of
- * `unknown command` (RUSH-2022).
- *
- * Commander sub-aliases (`sessions ls`, `teams rm`, …) are deliberately absent —
- * this set is top-level only. `command-registry.test.ts` pins it against the real
- * registered command tree so a new command can never drift out of it.
- */
 export declare const KNOWN_TOP_LEVEL_COMMANDS: ReadonlySet<string>;
-/**
- * Former top-level names that must NOT auto-correct (edit-distance 1) into a
- * live command. Without this a pruned surface silently misroutes: the typed
- * name is gone, the spellchecker finds a neighbour, and the CLI runs something
- * the user never asked for instead of saying the command is gone.
- *
- * `set` moved under `agents models`/`agents config` (RUSH-2579); `share`,
- * `unshare`, and the whole `artifacts` group moved OUT to the standalone
- * `artifacts` CLI (`@phnx-labs/artifacts-cli`, PHNX-3992) — artifact sharing is
- * no longer an agents-cli surface at all. login/logout/budget/bench/mine/
- * cost/output/profiles/snapshot/cp/resume/roster moved under nested homes
- * (cli-surface-consolidate). `timeline` was removed as a duplicated surface —
- * use `agents feed --filter updates` (RUSH-2692). `status` moved under
- * `agents sync status` (RUSH-2864). `tickets` was removed — use `linear`
- * (linear-cli) (RUSH-2932). `alias` moved under `agents setup alias` (RUSH-2965).
- * `inbox` was a pure alias of `agents feed` (RUSH-2984). `audit` nested under
- * `agents events audit`.
- * `trends` was removed with the insights recipe collapse — the one counter
- * surface is `agents insights mix` (PHNX-3391). `serve` (the
- * read-only local web companion + `--control` anchor) was removed with the
- * unshipped iOS Fleet Cockpit it existed for (RUSH-3001). `apply` nested under
- * `agents fleet apply` / `agents devices apply`. `beta` nested under
- * `agents setup beta` (RUSH-2981). `org` (the Prix-coupled account layer) was
- * removed; `agents auth` returned against Phoenix ID with `auth space` as the
- * team surface (RUSH-2581). `usage` was removed as a duplicate surface of
- * `agents view`, which renders per-account usage with account, version, and
- * auth state beside it (RUSH-3079). `perf` nested under `agents insights perf`
- * — performance metrics are an insight, not a top-level noun (PHNX-3391).
- * `list` was removed — it was a long-deprecated full duplicate of `agents view`
- * (it already printed "agents list is now agents view"); `agents view` is the
- * one version-listing surface (PHNX-3391). The `agents trash restore` subcommand
- * was likewise removed as an exact duplicate of top-level `agents restore`.
- */
 export declare const RETIRED_TOP_LEVEL_COMMANDS: ReadonlySet<string>;
 export declare function isKnownTopLevelCommand(name: string): boolean;

package/dist/lib/startup/command-registry.js

@@ -8,62 +8,17 @@ const LOADED_COMMAND_NAMES = [
     'refresh-rules', 'factory', 'insights', 'trace', 'reminders',
     'tmux', 'watchdog', 'browser', 'computer', 'logs', 'events',
     'ssh', 'devices', 'fleet', 'repos', 'repo', 'setup', 'uninstall', 'upgrade', 'sessions',
-    'teams', 'cloud', 'message', 'send', 'feed',
+    'teams', 'cloud', 'message', 'ps', 'send', 'feed',
     'mailboxes', 'mailbox', 'webhooks',
     'humans', 'daemon', 'traces',
 ];
 const INLINE_COMMAND_NAMES = [
     'perms', 'exec', 'jobs', 'cron', 'check', 'resources', 'hq', '_internal',
 ];
-/**
- * Every top-level command name the CLI answers to — the loader table plus the
- * inline aliases/tombstones above. This is the "does this command exist?"
- * predicate for code that runs BEFORE commander parses, most importantly the
- * `--device` router (lib/hosts/passthrough.ts): without it a typo'd
- * command carrying `--device` reported a flag-support error instead of
- * `unknown command` (RUSH-2022).
- *
- * Commander sub-aliases (`sessions ls`, `teams rm`, …) are deliberately absent —
- * this set is top-level only. `command-registry.test.ts` pins it against the real
- * registered command tree so a new command can never drift out of it.
- */
 export const KNOWN_TOP_LEVEL_COMMANDS = new Set([
     ...LOADED_COMMAND_NAMES,
     ...INLINE_COMMAND_NAMES,
 ]);
-/**
- * Former top-level names that must NOT auto-correct (edit-distance 1) into a
- * live command. Without this a pruned surface silently misroutes: the typed
- * name is gone, the spellchecker finds a neighbour, and the CLI runs something
- * the user never asked for instead of saying the command is gone.
- *
- * `set` moved under `agents models`/`agents config` (RUSH-2579); `share`,
- * `unshare`, and the whole `artifacts` group moved OUT to the standalone
- * `artifacts` CLI (`@phnx-labs/artifacts-cli`, PHNX-3992) — artifact sharing is
- * no longer an agents-cli surface at all. login/logout/budget/bench/mine/
- * cost/output/profiles/snapshot/cp/resume/roster moved under nested homes
- * (cli-surface-consolidate). `timeline` was removed as a duplicated surface —
- * use `agents feed --filter updates` (RUSH-2692). `status` moved under
- * `agents sync status` (RUSH-2864). `tickets` was removed — use `linear`
- * (linear-cli) (RUSH-2932). `alias` moved under `agents setup alias` (RUSH-2965).
- * `inbox` was a pure alias of `agents feed` (RUSH-2984). `audit` nested under
- * `agents events audit`.
- * `trends` was removed with the insights recipe collapse — the one counter
- * surface is `agents insights mix` (PHNX-3391). `serve` (the
- * read-only local web companion + `--control` anchor) was removed with the
- * unshipped iOS Fleet Cockpit it existed for (RUSH-3001). `apply` nested under
- * `agents fleet apply` / `agents devices apply`. `beta` nested under
- * `agents setup beta` (RUSH-2981). `org` (the Prix-coupled account layer) was
- * removed; `agents auth` returned against Phoenix ID with `auth space` as the
- * team surface (RUSH-2581). `usage` was removed as a duplicate surface of
- * `agents view`, which renders per-account usage with account, version, and
- * auth state beside it (RUSH-3079). `perf` nested under `agents insights perf`
- * — performance metrics are an insight, not a top-level noun (PHNX-3391).
- * `list` was removed — it was a long-deprecated full duplicate of `agents view`
- * (it already printed "agents list is now agents view"); `agents view` is the
- * one version-listing surface (PHNX-3391). The `agents trash restore` subcommand
- * was likewise removed as an exact duplicate of top-level `agents restore`.
- */
 export const RETIRED_TOP_LEVEL_COMMANDS = new Set([
     'webhook',
     'org',

package/dist/lib/startup/dev-build.d.ts

@@ -1,11 +1,2 @@
-/**
- * Whether a version string is the `0.0.0-dev.<sha>[-dirty]` stamp
- * `scripts/install.sh` writes for a side-by-side dev install (`install.sh:61`).
- *
- * Split out from {@link detectDevBuild} because a caller holding only a version
- * string — a fleet rollout reading `agents --version` off a remote box — cannot
- * run signal 2 (it needs that machine's filesystem), and must not re-spell the
- * stamp prefix.
- */
 export declare function isDevVersionStamp(version: string): boolean;
 export declare function detectDevBuild(argv1: string, version: string): boolean;

package/dist/lib/startup/dev-build.js

@@ -1,47 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
-/**
- * Decide whether the CLI is running from a source checkout (a "dev build") vs an
- * installed package. Dev builds suppress autopull / migrations / auto-update so
- * iterating on the repo never mutates the user's real setup.
- *
- * Two signals:
- *   1. A `0.0.0-dev*` version stamp (scripts/install.sh dev installs).
- *   2. Running out of an actual agents-cli git checkout.
- *
- * Signal 2 must be precise. The naive check —
- * `existsSync(dirname(dirname(argv[1])) + '/.git')` — false-positives badly:
- *   - npm-global bins are symlinks. `/opt/homebrew/bin/agents` →
- *     `…/node_modules/@phnx-labs/agents-cli/dist/index.js`. Without resolving the
- *     symlink, `dirname(dirname())` walks to `/opt/homebrew`, which is **itself a
- *     git repo** (Homebrew). So every Homebrew-node user looked like a dev build
- *     and had migrations + the menu-bar self-heal silently disabled.
- *
- * Fix: resolve the symlink with realpath and require the resolved package root's
- * own package.json `name` to actually be the agents-cli package, before ever
- * looking for `.git`.
- *
- * That package root does not always hold `.git` itself, though — this repo is a
- * monorepo where the package lives at `cli` and `.git` sits one level
- * higher, at the true repo root. `.git` is therefore searched for in a SMALL,
- * bounded set of ancestors above the package root (see
- * `DEV_BUILD_GIT_ANCESTOR_DEPTH`), not just the package root itself — a source
- * checkout run via tsx/ts-node from `cli/src/` or built to
- * `cli/dist/` must still be recognized. The bound keeps this well short of
- * an unrelated ancestor repo: a real Homebrew npm-global install's package root
- * sits 3 directories below `/opt/homebrew` (`lib/node_modules/@phnx-labs/…`),
- * so a depth of 2 finds this repo's `.git` while staying short of Homebrew's.
- */
 const DEV_BUILD_GIT_ANCESTOR_DEPTH = 2;
-/**
- * Whether a version string is the `0.0.0-dev.<sha>[-dirty]` stamp
- * `scripts/install.sh` writes for a side-by-side dev install (`install.sh:61`).
- *
- * Split out from {@link detectDevBuild} because a caller holding only a version
- * string — a fleet rollout reading `agents --version` off a remote box — cannot
- * run signal 2 (it needs that machine's filesystem), and must not re-spell the
- * stamp prefix.
- */
 export function isDevVersionStamp(version) {
     return version.startsWith('0.0.0-dev');
 }
@@ -63,7 +22,7 @@ export function detectDevBuild(argv1, version) {
                 return true;
             const parent = path.dirname(dir);
             if (parent === dir)
-                return false; // reached the filesystem root
+                return false;
             dir = parent;
         }
         return false;

package/dist/lib/startup/root-command.d.ts

@@ -1,22 +1,3 @@
 import type { Command } from 'commander';
-/**
- * Configure the public root surface shared by the live CLI and reference generator.
- *
- * Does NOT call `enablePositionalOptions()` — tried for RUSH-2687 (a subcommand
- * option whose long name collides with an ancestor's is silently dropped at
- * parse time) and reverted. Commander's `copyInheritedSettings()` copies
- * `_enablePositionalOptions` onto every command created via `.command()` from
- * that point on, so setting it here cascades to all ~552 registered commands,
- * not just the root's own scan. That broke a real, load-bearing pattern used
- * elsewhere in the tree: a parent command (e.g. `sessions`, which owns
- * `--since`/`--json`/`--local`) whose LEAF subcommands declare none of their
- * own options and read them back via `command.optsWithGlobals()` (e.g.
- * `sessions backfill tools --since 7d --json --local`) — positional options
- * makes the parent stop scanning at the first subcommand-shaped token, so it
- * never sees the flags typed after it, and the leaf sees `unknown option`
- * instead of a silent drop. RUSH-2687 was fixed per-surface in share.ts
- * instead (renaming the colliding options), not with this global flag.
- */
 export declare function configureRootCommand(program: Command, name: string, version: string): Command;
-/** Resume takes one device; its parent listing command takes a variadic list. */
 export declare function normalizeResumeDeviceArgs(args: string[]): string[];

package/dist/lib/startup/root-command.js

@@ -1,21 +1,3 @@
-/**
- * Configure the public root surface shared by the live CLI and reference generator.
- *
- * Does NOT call `enablePositionalOptions()` — tried for RUSH-2687 (a subcommand
- * option whose long name collides with an ancestor's is silently dropped at
- * parse time) and reverted. Commander's `copyInheritedSettings()` copies
- * `_enablePositionalOptions` onto every command created via `.command()` from
- * that point on, so setting it here cascades to all ~552 registered commands,
- * not just the root's own scan. That broke a real, load-bearing pattern used
- * elsewhere in the tree: a parent command (e.g. `sessions`, which owns
- * `--since`/`--json`/`--local`) whose LEAF subcommands declare none of their
- * own options and read them back via `command.optsWithGlobals()` (e.g.
- * `sessions backfill tools --since 7d --json --local`) — positional options
- * makes the parent stop scanning at the first subcommand-shaped token, so it
- * never sees the flags typed after it, and the leaf sees `unknown option`
- * instead of a silent drop. RUSH-2687 was fixed per-surface in share.ts
- * instead (renaming the colliding options), not with this global flag.
- */
 export function configureRootCommand(program, name, version) {
     return program
         .name(name)
@@ -26,7 +8,6 @@ export function configureRootCommand(program, name, version) {
         .helpOption('-h, --help', 'Show help')
         .addHelpCommand(false);
 }
-/** Resume takes one device; its parent listing command takes a variadic list. */
 export function normalizeResumeDeviceArgs(args) {
     if (args[0] !== 'sessions' || args[1] !== 'resume')
         return args;

package/dist/lib/startup/spellcheck.d.ts

@@ -1,17 +1,4 @@
-/**
- * Top-level command spellcheck (RUSH-2329).
- *
- * Candidates are plain strings from KNOWN_TOP_LEVEL_COMMANDS — never the live
- * commander registry — so an unknown / typo'd invocation does not pay for
- * registerAllEagerCommands (~250-330ms of dynamic import + module eval).
- */
-/** Calculate the Levenshtein edit distance between two strings. */
 export declare function levenshtein(a: string, b: string): number;
-/**
- * Closest top-level command name by Levenshtein distance.
- * Iterates candidates in first-seen order so ties break the same way as the
- * historical registerAllEagerCommands registration order (RUSH-2329).
- */
 export declare function closestTopLevelCommand(unknown: string, candidates: Iterable<string>): {
     closest: string | null;
     minDist: number;

package/dist/lib/startup/spellcheck.js

@@ -1,11 +1,3 @@
-/**
- * Top-level command spellcheck (RUSH-2329).
- *
- * Candidates are plain strings from KNOWN_TOP_LEVEL_COMMANDS — never the live
- * commander registry — so an unknown / typo'd invocation does not pay for
- * registerAllEagerCommands (~250-330ms of dynamic import + module eval).
- */
-/** Calculate the Levenshtein edit distance between two strings. */
 export function levenshtein(a, b) {
     const m = a.length;
     const n = b.length;
@@ -26,11 +18,6 @@ export function levenshtein(a, b) {
     }
     return dp[m][n];
 }
-/**
- * Closest top-level command name by Levenshtein distance.
- * Iterates candidates in first-seen order so ties break the same way as the
- * historical registerAllEagerCommands registration order (RUSH-2329).
- */
 export function closestTopLevelCommand(unknown, candidates) {
     let closest = null;
     let minDist = Infinity;