@phnx-labs/agents-cli 1.22.46 → 1.22.47

package/dist/lib/agent-spec/agents.js

@@ -298,7 +298,7 @@ export const AGENTS = {
         cloudProvider: 'codex',
         // Subagents: multi-agent plumbing since 0.117.0; custom agents as
         // ~/.codex/agents/*.toml (name, description, developer_instructions).
-        capabilities: { hooks: { since: '0.116.0' }, mcp: true, mcpHttp: true, mcpHeaders: false, allowlist: { since: '0.138.0' }, skills: true, commands: { until: '0.117.0' }, plugins: { since: '0.128.0' }, subagents: { since: '0.117.0' }, rules: { file: 'AGENTS.md' }, workflows: false, memory: true, modes: ['plan', 'edit', 'skip'], interactiveRepl: true },
+        capabilities: { hooks: { since: '0.116.0' }, mcp: true, mcpHttp: true, mcpHeaders: false, allowlist: { since: '0.138.0' }, skills: true, commands: { until: '0.117.0' }, plugins: { since: '0.128.0' }, subagents: { since: '0.117.0' }, rules: { file: 'AGENTS.md' }, workflows: false, memory: true, modes: ['plan', 'edit', 'auto', 'skip'], interactiveRepl: true },
     },
     gemini: {
         id: 'gemini',
@@ -3050,15 +3050,23 @@ export function isAgentName(input) {
     return resolveAgentName(input) !== null;
 }
 /**
- * Split a CLI-provided `<agent>[@<version>]` spec into its bare agent id and
- * optional exact version token, the same way `agents run` does
- * (commands/exec.ts parses its positional with a plain `split('@')`) — NOT the
+ * Split a CLI-provided `<agent>[@<version>][#<label>]` spec into its bare agent
+ * id, optional exact version token, and optional account label, the same way
+ * `agents run` does — NOT the
  * agent-spec qualifier engine (`@latest`/`@all`), which enumerates installed
  * versions for read/diagnostic commands, not a single launch target. Returns an
  * error message rather than throwing so callers decide exit-vs-continue.
  */
 export function parseAgentVersionSpec(raw) {
-    const parts = raw.split('@');
+    const labelParts = raw.split('#');
+    if (labelParts.length > 2) {
+        return { error: `Invalid agent spec '${raw}': at most one '#label' is allowed` };
+    }
+    const [versionSpec, rawLabel] = labelParts;
+    if (rawLabel !== undefined && (rawLabel === '' || !/^[a-zA-Z0-9][a-zA-Z0-9@._+-]*$/.test(rawLabel))) {
+        return { error: `Invalid account label '${rawLabel}' in '${raw}'` };
+    }
+    const parts = versionSpec.split('@');
     if (parts.length > 2) {
         return { error: `Invalid agent spec '${raw}': at most one '@version' is allowed` };
     }
@@ -3070,7 +3078,7 @@ export function parseAgentVersionSpec(raw) {
     if (rawVersion !== undefined && (rawVersion === '' || !VERSION_RE.test(rawVersion))) {
         return { error: `Invalid version '${rawVersion}' in '${raw}'` };
     }
-    return { agent, ...(rawVersion ? { version: rawVersion } : {}) };
+    return { agent, ...(rawVersion ? { version: rawVersion } : {}), ...(rawLabel ? { label: rawLabel } : {}) };
 }
 /**
  * Build the deprecation notice lines for an agent, or null if it isn't

package/dist/lib/analytics/mix-commands.d.ts

@@ -5,7 +5,7 @@
  * peer of `agents insights` with overlapping "analytics" meaning, so agents and
  * humans kept picking the wrong verb. The cheap counter path (sessions index +
  * usage.db) still exists — it is now `agents insights mix` and the recipe
- * subcommands below. Latency stays on `agents perf`; quota on `agents usage`.
+ * subcommands below. Latency stays on `agents perf`; quota on `agents view`.
  *
  * Former top-level `agents trends` is gone. The nested spelling
  * `agents insights trends` is an alias of `agents insights mix`.

package/dist/lib/analytics/mix-commands.js

@@ -5,7 +5,7 @@
  * peer of `agents insights` with overlapping "analytics" meaning, so agents and
  * humans kept picking the wrong verb. The cheap counter path (sessions index +
  * usage.db) still exists — it is now `agents insights mix` and the recipe
- * subcommands below. Latency stays on `agents perf`; quota on `agents usage`.
+ * subcommands below. Latency stays on `agents perf`; quota on `agents view`.
  *
  * Former top-level `agents trends` is gone. The nested spelling
  * `agents insights trends` is an alias of `agents insights mix`.
@@ -97,7 +97,7 @@ export function registerMixCommands(parent) {
       Session recipes read sessions.db; resource recipes read ~/.agents/.history/analytics/usage.db.
       Empty recipes are skipped on the default mix board.
       This is the cheap counter path. Behavioural report (transcript content, account split)
-      is bare \`agents insights\`. Latency is \`agents perf\`; quota is \`agents usage\`.
+      is bare \`agents insights\`. Latency is \`agents perf\`; quota is \`agents view\`.
       Skill/slash-command popularity is \`agents sessions stats\`.
     `,
     });

package/dist/lib/auth-health.d.ts

@@ -148,13 +148,21 @@ export declare function mergeAuthHealthEntries(current: Record<string, AuthHealt
 export declare function writeAuthHealthEntries(entries: Record<string, AuthHealth>): void;
 /**
  * Complete a live auth probe for one (agent, home). For claude/kimi/droid this
- * hits the provider; for everyone else it reports a best-effort local verdict
- * (`unverified` when a credential is present, `unconfigured` otherwise) — never
- * masquerading as `live`.
+ * hits the provider — unless the account's usage cache already holds a fresh
+ * successful fetch, which is the same authenticated request and proves the
+ * token live without spending a second one (RUSH-3036). For everyone else it
+ * reports a best-effort local verdict (`unverified` when a credential is
+ * present, `unconfigured` otherwise) — never masquerading as `live`.
  */
 export declare function probeAuthHealth(agent: AgentId, home: string | undefined, opts?: {
     cliVersion?: string | null;
     info?: AccountInfo | null;
+    /**
+     * Skip the derived-from-usage shortcut and fire a real network probe
+     * (RUSH-3036). Set by `agents devices ping [--strict]`, whose contract is
+     * a genuinely live request that surfaces `revoked` immediately.
+     */
+    forceLive?: boolean;
 }): Promise<AuthHealth>;
 /** One probed install on a host. */
 export interface AuthProbeRow {
@@ -215,6 +223,8 @@ export declare function groupFleetAuthInstalls<T extends FleetAuthInstall>(insta
 export declare function probeLocalFleetAuth(opts?: {
     cliVersion?: string | null;
     agents?: readonly AgentId[];
+    /** Fire real network probes even when fresh usage evidence exists (RUSH-3036) — the `devices ping [--strict]` contract. */
+    forceLive?: boolean;
 }): Promise<AuthProbeRow[]>;
 /** Persist a host's probed rows into the cache (keyed by host+agent+version). */
 export declare function writeFleetAuthRows(host: string, rows: AuthProbeRow[]): void;

package/dist/lib/auth-health.js

@@ -20,7 +20,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { ALL_AGENT_IDS, getAccountInfo } from './agents.js';
 import { getCacheDir } from './state.js';
-import { probeClaudeStatus, probeDroidStatus, probeKimiStatus, USAGE_HEADLESS_SCOPE_MARKER, } from './accounting/usage.js';
+import { probeClaudeStatus, probeDroidStatus, probeKimiStatus, USAGE_HEADLESS_SCOPE_MARKER, readClaudeUsageCache, } from './accounting/usage.js';
 import { getVersionHomePath, listInstalledVersions } from './installations/versions.js';
 import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
 /** Agents with a live network probe wired up today. The rest are best-effort. */
@@ -294,22 +294,64 @@ export function writeAuthHealthEntries(entries) {
 // ---------------------------------------------------------------------------
 // The probe (writer side)
 // ---------------------------------------------------------------------------
+/**
+ * A usage snapshot this recent is live proof the account's shared setup-token
+ * works: the snapshot only exists because an authenticated `/oauth/usage`
+ * request succeeded. Matches the periodic tick's own probe window
+ * (AUTH_PROBE_MAX_AGE_MS in daemon-ticks.ts — not imported to avoid a cycle;
+ * a drift here only widens/narrows evidence freshness, never correctness).
+ */
+const FRESH_USAGE_VERDICT_MAX_AGE_MS = 20 * 60_000;
+/**
+ * A `live` verdict derived from the account's usage cache instead of a second
+ * network request (RUSH-3036). The auth probe and the usage fetch hit the SAME
+ * rate-limited endpoint with the SAME fleet-shared setup-token, so a fresh
+ * successful usage snapshot already proves everything the probe would: paying a
+ * second request per account per box was half the fleet's endpoint load.
+ *
+ * Two guards keep the evidence honest (both review findings on the first cut):
+ * the caller must assert this box holds a LOCAL credential for the account
+ * (`signedIn`) — a fleet-imported snapshot proves the shared token works, not
+ * that THIS box can authenticate, so an unsigned home never derives `live`;
+ * and a `forceLive` caller (`agents devices ping --strict`) skips derivation
+ * entirely, because its contract is a real request that can surface `revoked`
+ * within seconds, not minutes. Returns null when there is no admissible fresh
+ * evidence — the caller then live-probes as before.
+ */
+function verdictFromFreshUsage(usageKey, signedIn, now) {
+    if (!usageKey || !signedIn)
+        return null;
+    const snapshot = readClaudeUsageCache(usageKey);
+    const capturedAt = snapshot?.capturedAt?.getTime();
+    if (!capturedAt || now - capturedAt >= FRESH_USAGE_VERDICT_MAX_AGE_MS)
+        return null;
+    const ageMin = Math.max(1, Math.round((now - capturedAt) / 60_000));
+    return { verdict: 'live', checkedAt: now, detail: `token proven live by a usage fetch ${ageMin}m ago` };
+}
 /**
  * Complete a live auth probe for one (agent, home). For claude/kimi/droid this
- * hits the provider; for everyone else it reports a best-effort local verdict
- * (`unverified` when a credential is present, `unconfigured` otherwise) — never
- * masquerading as `live`.
+ * hits the provider — unless the account's usage cache already holds a fresh
+ * successful fetch, which is the same authenticated request and proves the
+ * token live without spending a second one (RUSH-3036). For everyone else it
+ * reports a best-effort local verdict (`unverified` when a credential is
+ * present, `unconfigured` otherwise) — never masquerading as `live`.
  */
 export async function probeAuthHealth(agent, home, opts) {
     const checkedAt = Date.now();
     if (LIVE_PROBE_AGENTS.has(agent)) {
+        const usageScope = opts?.info?.usageKey ?? null;
+        if (opts?.forceLive !== true) {
+            const derived = verdictFromFreshUsage(usageScope, opts?.info?.signedIn === true, checkedAt);
+            if (derived)
+                return derived;
+        }
         let probe;
         if (agent === 'claude')
-            probe = await probeClaudeStatus(home, opts?.cliVersion);
+            probe = await probeClaudeStatus(home, opts?.cliVersion, usageScope);
         else if (agent === 'kimi')
-            probe = await probeKimiStatus(home);
+            probe = await probeKimiStatus(home, usageScope);
         else
-            probe = await probeDroidStatus(home);
+            probe = await probeDroidStatus(home, usageScope);
         return { verdict: verdictFromProbe(probe), checkedAt, detail: probeDetail(probe) };
     }
     const info = opts?.info !== undefined ? opts.info : await getAccountInfo(agent, home).catch(() => null);
@@ -384,7 +426,7 @@ export async function probeLocalFleetAuth(opts) {
     // accounts, so no same-account concurrency is left to trip the throttle.
     const perGroup = await Promise.all(groupFleetAuthInstalls(installs, (inst) => LIVE_PROBE_AGENTS.has(inst.agent)).map(async (group) => {
         const rep = group.probe;
-        const health = await probeAuthHealth(rep.agent, rep.home, { cliVersion: opts?.cliVersion, info: rep.info });
+        const health = await probeAuthHealth(rep.agent, rep.home, { cliVersion: opts?.cliVersion, info: rep.info, forceLive: opts?.forceLive });
         health.account = authAccountLabel(rep.info);
         if (health.verdict === 'unconfigured')
             return [];

package/dist/lib/browser/devices.d.ts

@@ -13,3 +13,22 @@ export declare const DEFAULT_VIEWPORT: {
 export declare const DEVICES: Record<string, DeviceDescriptor>;
 export declare function getDevice(name: string): DeviceDescriptor | undefined;
 export declare function listDevices(): string[];
+/**
+ * Parse a `--window WxH` value. Returns null when the value is malformed, so
+ * callers emit their own actionable error.
+ *
+ * Shared by `profiles create` and `profiles edit` — one regex, one test, no
+ * drift between the two surfaces.
+ */
+export declare function parseWindowSize(raw: string): {
+    width: number;
+    height: number;
+} | null;
+/**
+ * Parse a `--position X,Y` value. Negative coordinates are valid — a window may
+ * sit on a display left of or above the primary one.
+ */
+export declare function parseWindowPosition(raw: string): {
+    x: number;
+    y: number;
+} | null;

package/dist/lib/browser/devices.js

@@ -36,3 +36,26 @@ export function getDevice(name) {
 export function listDevices() {
     return Object.keys(DEVICES);
 }
+/**
+ * Parse a `--window WxH` value. Returns null when the value is malformed, so
+ * callers emit their own actionable error.
+ *
+ * Shared by `profiles create` and `profiles edit` — one regex, one test, no
+ * drift between the two surfaces.
+ */
+export function parseWindowSize(raw) {
+    const m = String(raw).match(/^(\d+)x(\d+)$/);
+    if (!m)
+        return null;
+    return { width: parseInt(m[1], 10), height: parseInt(m[2], 10) };
+}
+/**
+ * Parse a `--position X,Y` value. Negative coordinates are valid — a window may
+ * sit on a display left of or above the primary one.
+ */
+export function parseWindowPosition(raw) {
+    const m = String(raw).match(/^(-?\d+),(-?\d+)$/);
+    if (!m)
+        return null;
+    return { x: parseInt(m[1], 10), y: parseInt(m[2], 10) };
+}

package/dist/lib/browser/ipc.d.ts

@@ -96,7 +96,7 @@ export declare function sendIPCRequest(request: IPCRequest, opts?: IPCRequestOpt
  * Fill actor / launchId / sessionId from the calling process when the request
  * left them blank. Explicit values on the request always win.
  */
-export declare function stampCallerIdentity(request: IPCRequest): IPCRequest;
+export declare function stampCallerIdentity(request: IPCRequest, env?: NodeJS.ProcessEnv): IPCRequest;
 /**
  * Open one connection that can serve many browser operations. This uses the
  * same daemon readiness and version-reconciliation path as sendIPCRequest;

package/dist/lib/browser/ipc.js

@@ -8,6 +8,7 @@ import { startDaemon, stopDaemon } from '../daemon/daemon.js';
 import { getCliVersion } from '../version.js';
 import { compareVersions } from '../agent-spec/primitives.js';
 import { getDaemonLogPath } from '../daemon/daemon.js';
+import { isFleetRemoteInvocation } from './remote-control.js';
 import { resolveCallerIdentity } from './caller-identity.js';
 import { actionable } from './service.js';
 /**
@@ -382,6 +383,7 @@ export class BrowserIPCServer {
                 actor: request.actor,
                 launchId: request.launchId,
                 sessionId: request.sessionId,
+                fleetRemote: request.fleetRemote,
                 createIfMissing,
                 title: request.title,
                 url: request.url,
@@ -421,6 +423,22 @@ export class BrowserIPCServer {
             case 'version': {
                 return { ok: true, version: getCliVersion() };
             }
+            case 'show': {
+                // Task-less by design — see BrowserService.showUrl. Absent from both
+                // PAGE_CREATE_VERBS and PAGE_RESOLVE_VERBS, so bindTask never ran above
+                // and this request carries no task.
+                if (!request.url) {
+                    return { ok: false, error: actionable('URL required.', 'Next: agents browser navigate <url>') };
+                }
+                if (!request.profile) {
+                    return { ok: false, error: actionable('Profile required.', 'Next: agents browser profiles list') };
+                }
+                const shown = await this.service.showUrl(request.profile, request.url, {
+                    fleetRemote: request.fleetRemote,
+                    actor: request.actor,
+                });
+                return { ok: true, tabId: shown.tabId };
+            }
             case 'start': {
                 if (!request.profile) {
                     return { ok: false, error: actionable('Profile required.', 'Next: agents browser profiles list') };
@@ -434,6 +452,7 @@ export class BrowserIPCServer {
                     actor: request.actor,
                     launchId: request.launchId,
                     sessionId: request.sessionId,
+                    fleetRemote: request.fleetRemote,
                     title: request.title,
                 });
                 return {
@@ -855,15 +874,22 @@ export async function sendIPCRequest(request, opts = {}) {
  * Fill actor / launchId / sessionId from the calling process when the request
  * left them blank. Explicit values on the request always win.
  */
-export function stampCallerIdentity(request) {
-    if (request.actor && request.launchId && request.sessionId)
-        return request;
+export function stampCallerIdentity(request, env = process.env) {
+    // The consent marker is stamped FIRST, above the identity early-return: a
+    // request that already carries a full identity (every streamed request does)
+    // would otherwise skip stamping entirely and reach the daemon unmarked.
+    // OR-ed, never overwritten — a client may assert the marker but must not be
+    // able to clear one this environment sets.
+    const fleetRemote = isFleetRemoteInvocation(env) || request.fleetRemote === true;
+    const marked = request.fleetRemote === fleetRemote ? request : { ...request, fleetRemote };
+    if (marked.actor && marked.launchId && marked.sessionId)
+        return marked;
     const id = resolveCallerIdentity();
     return {
-        ...request,
-        actor: request.actor ?? id.actor,
-        launchId: request.launchId ?? id.launchId,
-        sessionId: request.sessionId ?? id.sessionId,
+        ...marked,
+        actor: marked.actor ?? id.actor,
+        launchId: marked.launchId ?? id.launchId,
+        sessionId: marked.sessionId ?? id.sessionId,
     };
 }
 /**

package/dist/lib/browser/profiles.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserProfile } from './types.js';
+import type { BrowserProfile, ProfileName } from './types.js';
 export type { BrowserProfile } from './types.js';
 /**
  * Name of the profile `ensureDefaultBrowserProfile` auto-detects and pins.
@@ -167,6 +167,20 @@ export declare function effectiveLocalPort(profile: BrowserProfile): number | un
  * skip remote profiles in this scan.
  */
 export declare function findFreeProfilePort(): Promise<number>;
+/**
+ * Refuse a profile whose LOCAL port another profile already owns.
+ *
+ * Every CDP/SSH profile ends up listening on (or tunneling to) the same LOCAL
+ * port number as the one configured in the endpoint URL — SSH profiles reuse
+ * `?port=N` locally, so we no longer scope by host. Two profiles that would
+ * need the same local port can't both run at the same time.
+ *
+ * `opts.ignore` is the profile's own name on an edit. Without it every edit
+ * collides with itself, since the stored copy still owns the port being kept.
+ */
+export declare function assertLocalPortFree(profile: BrowserProfile, opts?: {
+    ignore?: string;
+}): void;
 /**
  * Create a profile. **It lands in this machine's own store by default** — pass
  * `{ fleet: true }` (the CLI's `--fleet`) to put it in the synced `agents.yaml`
@@ -188,6 +202,97 @@ export declare function createProfile(profile: BrowserProfile, opts?: {
     fleet?: boolean;
 }): Promise<void>;
 export declare function updateProfile(profile: BrowserProfile): Promise<void>;
+/**
+ * Flag a fleet-synced profile whose contents only make sense on ONE machine.
+ *
+ * A `cdp://` endpoint on loopback always connects on the machine EVALUATING the
+ * profile, so a fleet-scope copy does not mean "that browser" — it means "port N
+ * on whichever box ran the command". The name then silently resolves to a
+ * different, usually logged-out browser on every other machine, which is the
+ * worst possible failure for a profile that carries live logins.
+ *
+ * Reported by `profiles doctor` (a failing `scope` check) and noted in the
+ * `kept` reason `profiles prune` prints for a fleet profile. The repair is
+ * {@link moveProfileScope}, never an automatic rewrite of the synced doc.
+ */
+export declare function misfiledFleetProfile(profile: BrowserProfile, scope: ProfileScope): {
+    misfiled: false;
+} | {
+    misfiled: true;
+    why: string;
+};
+/** Fields an existing profile may be edited in place.
+ *
+ * Deliberately a SUBSET of {@link BrowserProfile}. `name` and `browser` are
+ * identity, not settings: both key the on-disk runtime dir
+ * ({@link getProfileRuntimeDir}) and any live `<name>@<endpoint>` connection, so
+ * changing either orphans the cached browser data. Delete and recreate instead.
+ */
+export type EditableProfileFields = Partial<Pick<BrowserProfile, 'description' | 'binary' | 'electron' | 'targetFilter' | 'endpoints' | 'chrome' | 'secrets' | 'viewport'>>;
+export interface EditProfileResult {
+    profile: BrowserProfile;
+    scope: ProfileScope;
+    /** Field names that actually changed. Empty means the edit was a no-op. */
+    changed: string[];
+    /**
+     * Set when the write landed machine-locally while a stale fleet copy remains.
+     * Only reachable for {@link isMachineLocalProfile} names that an older version
+     * wrote into the fleet store: {@link updateProfile} pins those local, so this
+     * box sees the edit and every other box keeps the old value. Callers must say
+     * so rather than reporting a clean success.
+     */
+    fleetCopyLeftStale?: boolean;
+}
+/**
+ * Merge `patch` onto the stored profile and persist it in the store it already
+ * lives in (see {@link updateProfile} for the scope rules).
+ *
+ * Runs {@link createProfile}'s validations against the MERGED record, not just
+ * the patched fields — a binary edit re-resolves the browser path, a
+ * targetFilter edit re-checks the electron gate, and the local-port scan runs
+ * with this profile excluded so an unchanged port is not a self-collision.
+ */
+export declare function editProfile(name: string, patch: EditableProfileFields): Promise<EditProfileResult>;
+/**
+ * Throw if `name` cannot be used for a NEW profile.
+ *
+ * Shared by `profiles create` and {@link renameProfile} so the two cannot drift
+ * — the shape rule used to live inline in the command, which is how `rename`
+ * would have accepted a name `create` rejects.
+ *
+ * `default` is refused because it is the reserved ALIAS meaning "whatever
+ * profile this machine is configured to use" (RUSH-2709). A literal profile by
+ * that name makes `--profile default` mean two different things.
+ */
+export declare function assertRegistrableProfileName(name: string): void;
+/**
+ * Rename a profile, taking its on-disk state with it.
+ *
+ * `editProfile` deliberately refuses a name change, and this is why: the name
+ * keys the runtime dir ({@link getProfileRuntimeDir}), every fork/endpoint dir
+ * derived from it, and the `browser.profile` pointer. Delete-and-recreate — the
+ * only route before this — silently abandons the browser's `--user-data-dir`,
+ * which is where a profile's logins live. On a real agent browser that is
+ * gigabytes of session state and every account it has ever signed into.
+ *
+ * Refuses when the profile is in use: moving a `--user-data-dir` out from under
+ * a running browser corrupts it.
+ */
+export declare function renameProfile(from: ProfileName, to: ProfileName): Promise<{
+    scope: ProfileScope;
+    movedDirs: string[];
+    repointedDefault: boolean;
+    repointedViewer: boolean;
+    /** Peers still pinning the OLD name, and which key each used. */
+    stalePins: Array<{
+        device: string;
+        key: 'browser.profile' | 'browser.viewer';
+    }>;
+}>;
+export declare function moveProfileScope(name: string, to: ProfileScope): Promise<{
+    from: ProfileScope;
+    to: ProfileScope;
+}>;
 export declare function deleteProfile(name: string): Promise<void>;
 /**
  * Pad `text` to exactly `width` visible characters, truncating with an ellipsis