@phnx-labs/agents-cli 1.20.22 → 1.20.24

package/dist/lib/cloud/factory.d.ts

@@ -19,11 +19,19 @@
  * the droid binary + a configured computer so the provider fails with a clear
  * message rather than misfiring when unconfigured.
  */
-import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions, ProviderCapabilities, DroidAutonomy } from './types.js';
+import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, CloudTarget, DispatchOptions, ProviderCapabilities, DroidAutonomy } from './types.js';
 /** Locate the droid binary, checking agents-cli shims first then PATH. */
 export declare function findDroidBinary(): string | null;
 /** Normalize an autonomy value, falling back to the safe cloud default (`high`). */
 export declare function resolveAutonomy(value: unknown, fallback?: DroidAutonomy): DroidAutonomy;
+/**
+ * Parse `droid computer list` text into targets. Defensive: the exact column
+ * layout isn't documented, so we take the first whitespace token of each data
+ * row as the computer name and keep the remainder as a label, skipping headers,
+ * separators, and status messages. The interactive picker degrades to free-text
+ * entry if this yields nothing, so an unexpected layout never blocks a dispatch.
+ */
+export declare function parseComputerList(text: string): CloudTarget[];
 /**
  * Build the remote `droid exec` argv. Headless, stream-json output, given
  * autonomy. `sessionId` (when resuming) maps to `-s`.
@@ -61,6 +69,7 @@ export declare function mapDroidEvent(obj: Record<string, unknown>): CloudEvent;
 export declare class FactoryCloudProvider implements CloudProvider {
     id: "factory";
     name: string;
+    targetKind: "computer";
     private defaultComputer?;
     private defaultAutonomy;
     /** session_id → buffered run, populated by dispatch, drained by stream. */
@@ -70,6 +79,8 @@ export declare class FactoryCloudProvider implements CloudProvider {
         autonomy?: DroidAutonomy;
     });
     capabilities(): ProviderCapabilities;
+    /** Enumerate Droid Computers via `droid computer list`. Throws if not signed in. */
+    listTargets(): Promise<CloudTarget[]>;
     dispatch(options: DispatchOptions): Promise<CloudTask>;
     /** Run the remote droid exec to completion, collecting events + final result. */
     private runRemote;

package/dist/lib/cloud/factory.js

@@ -22,6 +22,7 @@
 import { spawn, execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
+import { MissingTargetError } from './types.js';
 import { getShimsDir } from '../state.js';
 const SHIMS_DIR = getShimsDir();
 const DEFAULT_AUTONOMY = 'high';
@@ -44,6 +45,45 @@ export function resolveAutonomy(value, fallback = DEFAULT_AUTONOMY) {
         ? value
         : fallback;
 }
+/** Run the droid CLI and capture output (used for `computer list`). */
+function runDroid(bin, args) {
+    return new Promise((resolve) => {
+        const proc = spawn(bin, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        proc.stdout.on('data', (d) => { stdout += d.toString(); });
+        proc.stderr.on('data', (d) => { stderr += d.toString(); });
+        proc.on('error', (e) => resolve({ stdout, stderr: stderr + String(e), code: 127 }));
+        proc.on('close', (code) => resolve({ stdout, stderr, code: code ?? 1 }));
+    });
+}
+/**
+ * Parse `droid computer list` text into targets. Defensive: the exact column
+ * layout isn't documented, so we take the first whitespace token of each data
+ * row as the computer name and keep the remainder as a label, skipping headers,
+ * separators, and status messages. The interactive picker degrades to free-text
+ * entry if this yields nothing, so an unexpected layout never blocks a dispatch.
+ */
+export function parseComputerList(text) {
+    const out = [];
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        if (/^(name|computer|status|id)\b/i.test(line))
+            continue; // header row
+        if (/^[-=_\s|]+$/.test(line))
+            continue; // separator rule
+        if (/^(no |failed|error|warning)\b/i.test(line))
+            continue; // status message
+        const name = line.split(/\s+/)[0];
+        if (!name)
+            continue;
+        const label = line.slice(name.length).trim() || undefined;
+        out.push({ id: name, label, kind: 'computer' });
+    }
+    return out;
+}
 /**
  * Build the remote `droid exec` argv. Headless, stream-json output, given
  * autonomy. `sessionId` (when resuming) maps to `-s`.
@@ -152,6 +192,7 @@ function extractText(obj) {
 export class FactoryCloudProvider {
     id = 'factory';
     name = 'Factory (Droid)';
+    targetKind = 'computer';
     defaultComputer;
     defaultAutonomy;
     /** session_id → buffered run, populated by dispatch, drained by stream. */
@@ -178,6 +219,20 @@ export class FactoryCloudProvider {
             images: false,
         };
     }
+    /** Enumerate Droid Computers via `droid computer list`. Throws if not signed in. */
+    async listTargets() {
+        const droidBin = findDroidBinary();
+        if (!droidBin) {
+            throw new Error('droid CLI not found. Install it: curl -fsSL https://app.factory.ai/cli | sh');
+        }
+        const { stdout, stderr, code } = await runDroid(droidBin, ['computer', 'list']);
+        if (code !== 0) {
+            // Surface droid's own message verbatim — e.g. "No authenticated user with
+            // organization available" when the user hasn't logged in.
+            throw new Error((stderr.trim() || stdout.trim() || `droid computer list exited ${code}`));
+        }
+        return parseComputerList(stdout);
+    }
     async dispatch(options) {
         const droidBin = findDroidBinary();
         if (!droidBin) {
@@ -185,9 +240,9 @@ export class FactoryCloudProvider {
         }
         const computer = options.providerOptions?.computer ?? this.defaultComputer;
         if (!computer) {
-            throw new Error('Factory cloud requires a Droid Computer. Pass --computer <name>, or set ' +
-                'cloud.providers.factory.computer in ~/.agents/agents.yaml. Create one in ' +
-                'Factory (Settings → Droid Computers), or register a machine with `droid computer register`.');
+            throw new MissingTargetError('computer', 'Factory cloud requires a Droid Computer.', 'Pass --computer <name>, or set cloud.providers.factory.computer in ~/.agents/agents.yaml. ' +
+                'Create one in Factory (Settings → Droid Computers), or register a machine with `droid computer register`. ' +
+                'List yours with `agents cloud envs --provider factory`.');
         }
         const autonomy = resolveAutonomy(options.providerOptions?.autonomy ?? options.providerOptions?.mode, this.defaultAutonomy);
         const user = options.providerOptions?.user ?? 'droid';

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

@@ -175,6 +175,33 @@ export interface ProviderCapabilities {
     skills: boolean;
     images: boolean;
 }
+/**
+ * A pre-provisioned dispatch target a provider runs *inside* — a Codex
+ * environment (`env_…`) or a Factory Droid Computer (a name). Surfaced by
+ * `agents cloud envs` and the missing-target picker so users don't have to
+ * copy opaque IDs out of a web UI.
+ */
+export interface CloudTarget {
+    /** The value passed to dispatch (env id / computer name). */
+    id: string;
+    /** Human label — repo, description, or status. */
+    label?: string;
+    kind: TargetKind;
+}
+/** Which dispatch option a provider's pre-provisioned target maps to. */
+export type TargetKind = 'env' | 'computer';
+/**
+ * Thrown by a provider's `dispatch()` when it needs a pre-provisioned target
+ * (Codex env / Factory computer) and none was supplied. The CLI catches this
+ * to offer a picker (`listTargets`) or actionable guidance, instead of a raw
+ * error. `kind` names the missing flag; `guidance` is shown when the target
+ * can't be enumerated.
+ */
+export declare class MissingTargetError extends Error {
+    kind: TargetKind;
+    guidance?: string | undefined;
+    constructor(kind: TargetKind, message: string, guidance?: string | undefined);
+}
 /**
  * Contract that every cloud backend must implement.
  *
@@ -198,6 +225,20 @@ export interface CloudProvider {
     cancel(taskId: string): Promise<void>;
     /** Send a follow-up message to a finished/idle/needs_review task. */
     message(taskId: string, content: string): Promise<void>;
+    /**
+     * The pre-provisioned target this provider runs inside, if any. Set for
+     * Codex (`env`) and Factory (`computer`); undefined for Rush (per-repo) and
+     * Antigravity (on-demand sandbox).
+     */
+    targetKind?: TargetKind;
+    /**
+     * Enumerate selectable targets for `agents cloud envs` and the picker.
+     * Present only when the backend can list non-interactively (Factory via
+     * `droid computer list`). Codex has no such CLI — it omits this, and callers
+     * fall back to `MissingTargetError.guidance`. May throw (e.g. not signed in);
+     * callers surface that verbatim.
+     */
+    listTargets?(): Promise<CloudTarget[]>;
 }
 /** Autonomy level passed to `droid exec --auto` for Factory cloud dispatches. */
 export type DroidAutonomy = 'low' | 'medium' | 'high';

package/dist/lib/cloud/types.js

@@ -32,3 +32,20 @@ export function resolveDispatchRepos(options) {
     }
     return out;
 }
+/**
+ * Thrown by a provider's `dispatch()` when it needs a pre-provisioned target
+ * (Codex env / Factory computer) and none was supplied. The CLI catches this
+ * to offer a picker (`listTargets`) or actionable guidance, instead of a raw
+ * error. `kind` names the missing flag; `guidance` is shown when the target
+ * can't be enumerated.
+ */
+export class MissingTargetError extends Error {
+    kind;
+    guidance;
+    constructor(kind, message, guidance) {
+        super(message);
+        this.kind = kind;
+        this.guidance = guidance;
+        this.name = 'MissingTargetError';
+    }
+}

package/dist/lib/exec.d.ts

@@ -99,6 +99,8 @@ export interface ExecOptions {
      * flag alone merely ADDS to the existing server set).
      */
     mcpConfigPath?: string;
+    /** Raw args captured after `--` on the command line, forwarded verbatim to the underlying agent CLI. */
+    passthroughArgs?: string[];
 }
 /**
  * Resolve interactive vs headless. Explicit flags are definitive and win over

package/dist/lib/exec.js

@@ -596,6 +596,11 @@ export function buildExecCommand(options) {
             cmd.push('--strict-mcp-config');
         }
     }
+    // Forward arbitrary native flags supplied after `--` verbatim. Appended last
+    // so they cannot be misinterpreted as values for earlier flags or as the prompt.
+    if (options.passthroughArgs && options.passthroughArgs.length > 0) {
+        cmd.push(...options.passthroughArgs);
+    }
     return cmd;
 }
 /** Spawn an agent and return its exit code. Convenience wrapper over spawnAgent. */

package/dist/lib/menubar/MenubarHelper.app/Contents/Info.plist

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>CFBundleExecutable</key>
+    <string>MenubarHelper</string>
+    <key>CFBundleIdentifier</key>
+    <string>com.phnx-labs.agents-menubar</string>
+    <key>CFBundleName</key>
+    <string>Agents Menu Bar</string>
+    <key>CFBundlePackageType</key>
+    <string>APPL</string>
+    <key>CFBundleShortVersionString</key>
+    <string>0.1.0</string>
+    <key>CFBundleVersion</key>
+    <string>1</string>
+    <key>LSUIElement</key>
+    <true/>
+</dict>
+</plist>

package/dist/lib/menubar/MenubarHelper.app/Contents/_CodeSignature/CodeResources

@@ -0,0 +1,115 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>files</key>
+	<dict/>
+	<key>files2</key>
+	<dict/>
+	<key>rules</key>
+	<dict>
+		<key>^Resources/</key>
+		<true/>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^version.plist$</key>
+		<true/>
+	</dict>
+	<key>rules2</key>
+	<dict>
+		<key>.*\.dSYM($|/)</key>
+		<dict>
+			<key>weight</key>
+			<real>11</real>
+		</dict>
+		<key>^(.*/)?\.DS_Store$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>2000</real>
+		</dict>
+		<key>^(Frameworks|SharedFrameworks|PlugIns|Plug-ins|XPCServices|Helpers|MacOS|Library/(Automator|Spotlight|LoginItems))/</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^.*</key>
+		<true/>
+		<key>^Info\.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^PkgInfo$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^[^/]+$</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^embedded\.provisionprofile$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^version\.plist$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+	</dict>
+</dict>
+</plist>

package/dist/lib/secrets/agent.d.ts

@@ -25,6 +25,17 @@
 import type { SecretsBundle } from './bundles.js';
 /** Default lifetime of an unlocked bundle when `--ttl` is not given. */
 export declare const DEFAULT_TTL_MS: number;
+/**
+ * Decide whether a persistent broker should self-heal onto freshly-installed
+ * code (exit so launchd relaunches it). Only when the store is EMPTY: exiting
+ * with bundles still unlocked wipes them from memory, so the next reader falls
+ * back to a direct keychain read and re-prompts for Touch ID. Deferring the
+ * restart until the cache is idle (TTL-expired / screen-locked) means an
+ * in-place `npm i -g` never wipes a hot cache — the new code is adopted at the
+ * next quiet moment instead. See #435: rapid repeated upgrades wiped a hot
+ * cache on every bump and produced a recurring Touch ID storm.
+ */
+export declare function shouldSelfHealForUpgrade(persistent: boolean, storeSize: number, runningVersion: string, onDiskVersion: string): boolean;
 export interface StoredBundle {
     bundle: SecretsBundle;
     env: Record<string, string>;

package/dist/lib/secrets/agent.js

@@ -41,6 +41,25 @@ export const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24h
 const IDLE_EXIT_MS = 5 * 60 * 1000; // 5m
 /** How often the broker sweeps expired entries. */
 const SWEEP_INTERVAL_MS = 30 * 1000;
+/**
+ * Decide whether a persistent broker should self-heal onto freshly-installed
+ * code (exit so launchd relaunches it). Only when the store is EMPTY: exiting
+ * with bundles still unlocked wipes them from memory, so the next reader falls
+ * back to a direct keychain read and re-prompts for Touch ID. Deferring the
+ * restart until the cache is idle (TTL-expired / screen-locked) means an
+ * in-place `npm i -g` never wipes a hot cache — the new code is adopted at the
+ * next quiet moment instead. See #435: rapid repeated upgrades wiped a hot
+ * cache on every bump and produced a recurring Touch ID storm.
+ */
+export function shouldSelfHealForUpgrade(persistent, storeSize, runningVersion, onDiskVersion) {
+    if (!persistent)
+        return false;
+    if (storeSize > 0)
+        return false; // hot cache — defer rather than wipe unlocks
+    if (runningVersion === 'unknown' || onDiskVersion === 'unknown')
+        return false;
+    return onDiskVersion !== runningVersion;
+}
 function onDarwin() {
     return process.platform === 'darwin';
 }
@@ -307,15 +326,15 @@ export async function runSecretsAgent(opts = {}) {
         for (const [name, e] of store)
             if (now >= e.expiresAt)
                 store.delete(name);
-        // Self-heal: a newer version was installed in place — exit so launchd
-        // relaunches us on the new code. Only meaningful when launchd will restart
-        // us (persistent); a one-off broker just keeps serving until idle.
-        if (persistent) {
-            const onDisk = getCliVersionFresh();
-            if (onDisk !== 'unknown' && runningVersion !== 'unknown' && onDisk !== runningVersion) {
-                shutdown(0); // KeepAlive relaunches on the new code
-                return;
-            }
+        // Self-heal onto a newer in-place install — but ONLY while the store is
+        // empty, so we never wipe live unlocks and force a re-prompt (#435). The
+        // `store.size === 0` short-circuit also keeps getCliVersionFresh (a disk
+        // read) off the hot path. A pending upgrade is adopted at the next idle
+        // sweep instead of immediately.
+        if (store.size === 0 &&
+            shouldSelfHealForUpgrade(persistent, store.size, runningVersion, getCliVersionFresh())) {
+            shutdown(0); // KeepAlive relaunches on the new code
+            return;
         }
         if (store.size === 0) {
             if (!persistent && now - emptySince >= IDLE_EXIT_MS)

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

@@ -0,0 +1,99 @@
+/**
+ * Lazy command registry.
+ *
+ * The CLI entry point (src/index.ts) used to statically import every command
+ * module and call its `registerXCommand(program)` on every invocation. That
+ * loaded the entire command tree (~50 modules) before the first line of output,
+ * dominating cold-start latency.
+ *
+ * This module maps each user-typed top-level command name to a thunk that
+ * dynamically imports ONLY the module(s) that command needs. Fast commands
+ * (`--version`, `view`, ...) now pay for just the one module they use; the full
+ * tree is loaded only on the rare slow paths (unknown-command spellcheck, bare
+ * help) via `registerAllEagerCommands` in src/index.ts.
+ *
+ * Parity is non-negotiable: the name -> loader map below mirrors exactly which
+ * module registers which top-level command on `main`. Multi-command modules
+ * (versions, packages) map several names to the same loader; `prune` needs BOTH
+ * versions (which creates `prune <specs...>`) and prune.js (which attaches the
+ * `cleanup` subcommand to it), in that order — see commands/prune.ts.
+ */
+import type { Command } from 'commander';
+/** A function that registers one or more commands onto the root program. */
+export type Registrar = (program: Command) => void;
+/** A thunk that dynamically imports a command module and returns its registrar. */
+export type ModuleLoader = () => Promise<Registrar>;
+export declare const loadView: ModuleLoader;
+export declare const loadInspect: ModuleLoader;
+export declare const loadFeedback: ModuleLoader;
+export declare const loadCommands: ModuleLoader;
+export declare const loadHooks: ModuleLoader;
+export declare const loadSkills: ModuleLoader;
+export declare const loadRules: ModuleLoader;
+export declare const loadPermissions: ModuleLoader;
+export declare const loadMcp: ModuleLoader;
+export declare const loadCli: ModuleLoader;
+export declare const loadSubagents: ModuleLoader;
+export declare const loadPlugins: ModuleLoader;
+export declare const loadWorkflows: ModuleLoader;
+export declare const loadWorktree: ModuleLoader;
+export declare const loadVersions: ModuleLoader;
+export declare const loadImport: ModuleLoader;
+export declare const loadPackages: ModuleLoader;
+export declare const loadDaemon: ModuleLoader;
+export declare const loadRoutines: ModuleLoader;
+export declare const loadRun: ModuleLoader;
+export declare const loadDefaults: ModuleLoader;
+export declare const loadModels: ModuleLoader;
+export declare const loadPrune: ModuleLoader;
+export declare const loadTrash: ModuleLoader;
+export declare const loadRestore: ModuleLoader;
+export declare const loadDoctor: ModuleLoader;
+export declare const loadProfiles: ModuleLoader;
+export declare const loadSecrets: ModuleLoader;
+export declare const loadWallet: ModuleLoader;
+export declare const loadHelper: ModuleLoader;
+export declare const loadMenubar: ModuleLoader;
+export declare const loadBeta: ModuleLoader;
+export declare const loadSync: ModuleLoader;
+export declare const loadRefreshRules: ModuleLoader;
+export declare const loadDrive: ModuleLoader;
+export declare const loadFactory: ModuleLoader;
+export declare const loadUsage: ModuleLoader;
+export declare const loadCost: ModuleLoader;
+export declare const loadBudget: ModuleLoader;
+export declare const loadAlias: ModuleLoader;
+export declare const loadPty: ModuleLoader;
+export declare const loadTmux: ModuleLoader;
+export declare const loadBrowser: ModuleLoader;
+export declare const loadComputer: ModuleLoader;
+export declare const loadPull: ModuleLoader;
+export declare const loadPush: ModuleLoader;
+export declare const loadRepo: ModuleLoader;
+export declare const loadSetup: ModuleLoader;
+export declare const loadSessions: ModuleLoader;
+export declare const loadTeams: ModuleLoader;
+export declare const loadCloud: ModuleLoader;
+/**
+ * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
+ * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help
+ * conventions at module top-level, lazy registration just before parse), so they
+ * inherit the root's custom help formatter rather than getting the per-command
+ * recursive pass. Keeping that ordering preserves their `--help` output exactly.
+ */
+export declare const LAZY_COMMAND_NAMES: ReadonlySet<string>;
+/**
+ * User-typed top-level command name -> ordered list of module loaders to run.
+ *
+ * Most names map to a single loader. The exceptions encode real coupling on main:
+ *  - `add`/`use`/`list`/`remove`/`rm`/`purge` all come from the versions module.
+ *  - `registry`/`search`/`install` all come from the packages module.
+ *  - `trash` and `restore` are separate registrars in the trash module.
+ *  - `prune` needs versions FIRST (it creates `prune <specs...>`) then prune.js
+ *    (which finds that command and attaches the `cleanup` subcommand).
+ *
+ * Inline deprecated aliases (memory/perms/exec/jobs/cron) and the inline
+ * `upgrade` command are NOT here — they are closures over entry-point state and
+ * are handled directly in src/index.ts.
+ */
+export declare const COMMAND_LOADERS: Record<string, ModuleLoader[]>;