@phnx-labs/agents-cli 1.20.21 → 1.20.23

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+**Secrets prompt policy: human-readable `always` / `daily`, and `secrets list` now shows it**
+
+- Renamed the secrets-agent `tier` to a **prompt policy** with plain-language names: `biometry` → **`always`** (ask every time), `session` → **`daily`** (ask once, then held ~24h until screen-lock / sleep / logout). The old name `session` was misleading — it never meant "once per login session" — and collided with the half-dozen other "session" concepts in the CLI (`agents sessions`, sessions-sync, pty/browser sessions). Set it with `agents secrets policy <bundle> [always|daily]`.
+- **Disclosure fixed.** `agents secrets list` now has a `POLICY` column — previously there was no way to tell which bundles would Touch-ID-prompt you. `daily` bundles currently held by the agent show `daily · Nh left`. `agents secrets view` and `create` now always state the policy (before, only the quiet tier was shown; the noisy default printed nothing).
+- **Back-compat:** the policy still persists under the legacy `tier`/`session` token, so bundles stay readable across mixed CLI versions on synced machines. `agents secrets tier`, `--tier`, and the `biometry`/`session` values keep working as aliases.
+- A third **`never`** policy (silent, no biometry ACL) is tracked for later in #421.
+
+**Self-healing: long-running processes reload onto new code after an upgrade**
+
+- Root cause behind a class of "stale behavior" bugs: a routines daemon or secrets-agent broker keeps running **pre-upgrade code** for days. An in-place `npm i -g` swaps the files but not the running processes, so fixes (keychain read-memoization, the broker fast-path, etc.) silently never take effect — the daemon kept popping Touch ID from the keychain because it predated the fix.
+- **Heal-on-upgrade:** `postinstall` now bounces the routines daemon and kickstarts the persistent secrets-agent broker onto the just-installed code — the one moment we know the code changed. Best-effort, non-fatal, skipped in CI / with `AGENTS_NO_HEAL=1`.
+- **Broker version-skew self-heal:** the broker's `ping` reports the version of the code it's running; `ensureAgentRunning` (the unlock / auto-cache path, never per-read) restarts a broker found running stale code, and a persistent broker self-exits on detecting an in-place upgrade so launchd relaunches it fresh. New `getCliVersionFresh()` re-reads `package.json` to detect the swap.
+- No hot-path cost: all checks live on existing control-plane paths (postinstall, the broker sweep, `ensureAgentRunning`), never on a per-secret-read. macOS only. Complements #412 (daemon session-sync memoization) by ensuring the daemon actually *runs* that code.
+
 **`agents secrets start`: persistent secrets-agent service (fixes the broker under heavy load)**
 
 - On a heavily-loaded machine (many concurrent agents, high load average) the on-demand broker — a full CLI cold-start — couldn't get scheduled enough CPU to finish booting and bind its socket, so `unlock`/auto-cache silently failed and reads kept prompting. New `agents secrets start` installs the broker as a **launchd user service** (`RunAtLoad` + `KeepAlive`, `ProcessType: Interactive` for foreground scheduling priority): it starts once and stays up for the whole login session, so every read just connects — the cold start happens once (and launchd retries until it wins), never per read. `agents secrets stop` removes it; `agents secrets status` shows whether it's installed.

package/dist/commands/cloud.js

@@ -4,6 +4,7 @@ import ora from 'ora';
 import { resolveProvider, getAllProviders, getDefaultProviderId } from '../lib/cloud/registry.js';
 import { insertTask, updateTaskStatus, getTaskById, listTasks as listStoredTasks, listActiveTasks } from '../lib/cloud/store.js';
 import { renderStream } from '../lib/cloud/stream.js';
+import { MissingTargetError } from '../lib/cloud/types.js';
 /** Print an error message to stderr and exit. */
 function die(msg, code = 1) {
     console.error(chalk.red(msg));
@@ -43,16 +44,61 @@ function statusColor(status) {
 function isJsonMode(opts) {
     return Boolean(opts.json) || !process.stdout.isTTY;
 }
+/**
+ * After a `MissingTargetError`, try to resolve the target interactively.
+ * Returns the chosen id, or undefined when no interactive resolution is
+ * possible (non-TTY/JSON, provider can't enumerate, or user cancels) — the
+ * caller then prints the error's guidance.
+ *
+ * Codex has no `listTargets` (no list-environments CLI), so it always returns
+ * undefined here and the user sees the `codex cloud` guidance. Factory lists
+ * Droid Computers; if listing fails (not signed in) or parses to nothing, we
+ * fall back to a free-text prompt so a dispatch is never hard-blocked.
+ */
+async function pickMissingTarget(provider, err, json) {
+    if (json || !process.stdout.isTTY)
+        return undefined;
+    if (!provider.listTargets)
+        return undefined;
+    const { select, input } = await import('@inquirer/prompts');
+    const promptName = err.kind === 'env' ? 'environment' : 'computer';
+    let targets;
+    try {
+        targets = await provider.listTargets();
+    }
+    catch (listErr) {
+        process.stderr.write(chalk.dim(`Could not list ${promptName}s: ${listErr.message}\n`));
+        targets = [];
+    }
+    try {
+        if (targets.length > 0) {
+            return await select({
+                message: `Select a ${promptName}`,
+                choices: targets.map((t) => ({ value: t.id, name: t.label ? `${t.id}  ${chalk.dim(t.label)}` : t.id })),
+            });
+        }
+        const typed = (await input({ message: `No ${promptName}s found. Enter a ${promptName} name (blank to cancel):` })).trim();
+        return typed || undefined;
+    }
+    catch {
+        // User hit Ctrl-C / Esc on the prompt.
+        return undefined;
+    }
+}
 /** Register the `agents cloud` command tree (run, list, status, logs, cancel, message, providers). */
 export function registerCloudCommands(program) {
     const cloud = program
         .command('cloud', { hidden: true })
-        .description('Dispatch and manage cloud agent tasks across providers (Rush Cloud, Codex Cloud, Factory).')
+        .description('Dispatch and manage cloud agent tasks across providers (Rush, Codex, Factory, Antigravity).')
         .addHelpText('after', `
+Each agent runs in its own cloud. Pass --agent and the provider is auto-selected
+(claude→rush, codex→codex, droid→factory, antigravity→antigravity); --provider overrides.
+
 Providers:
-  rush      Rush Cloud — dispatches against a GitHub repo + branch
-  codex     Codex Cloud — runs in a pre-built Codex environment
-  factory   Factory pods — Droid + computer-use targets
+  rush         Rush Cloud — Claude against a GitHub repo + branch → PR
+  codex        Codex Cloud — runs in a pre-built Codex environment (--env)
+  factory      Factory Droid Computer — droid exec on a cloud VM (--computer)
+  antigravity  Gemini Managed Agents — Antigravity harness in a remote sandbox
 
 Examples:
   # Dispatch a quick fix to Rush Cloud and stream the output
@@ -92,8 +138,8 @@ Examples:
     cloud
         .command('run [prompt]')
         .description('Dispatch a task to a cloud agent.')
-        .option('--provider <id>', 'Cloud backend: rush, codex, factory')
-        .option('--agent <name>', 'Agent to run: claude, codex, droid')
+        .option('--provider <id>', 'Cloud backend: rush, codex, factory, antigravity (overrides agent auto-routing)')
+        .option('--agent <name>', 'Agent to run: claude, codex, droid, antigravity (auto-routes to its native cloud)')
         .option('--repo <owner/repo>', 'GitHub repository. Repeatable for multi-repo dispatch (Rush Cloud only).', (value, previous) => {
         const acc = Array.isArray(previous) ? previous : [];
         acc.push(value);
@@ -105,6 +151,7 @@ Examples:
         .option('--model <model>', 'Model override')
         .option('--env <id>', 'Codex Cloud environment ID')
         .option('--computer <name>', 'Factory/Droid computer target')
+        .option('--autonomy <level>', 'Factory/Droid autonomy: low, medium, high (default high)')
         .option('--mode <mode>', 'Execution mode (e.g., plan, edit, full)')
         .option('-b, --balanced', 'Shortcut for --strategy balanced. Route the factory run across all healthy accounts.')
         .option('--strategy <strategy>', 'Account selection strategy for the factory: balanced. Sends all healthy accounts so the factory pod rotates between them on rate-limit.')
@@ -142,7 +189,9 @@ Examples:
                 process.stderr.write(chalk.dim(`Reading prompt from ${filePath} (${sizeKB} KB)\n`));
             }
         }
-        const provider = resolveProvider(options.provider);
+        // Agent-aware: with no --provider, the agent routes to its native cloud
+        // (claude→rush, codex→codex, droid→factory, antigravity→antigravity).
+        const provider = resolveProvider(options.provider, options.agent);
         // --repo is repeatable: commander gives us an array via our collector.
         // A single --repo value arrives as a one-element array; keep the legacy
         // singular `repo` field in sync so providers that only know that field
@@ -166,6 +215,8 @@ Examples:
             dispatchOptions.providerOptions.env = options.env;
         if (options.computer)
             dispatchOptions.providerOptions.computer = options.computer;
+        if (options.autonomy)
+            dispatchOptions.providerOptions.autonomy = options.autonomy;
         if (options.mode)
             dispatchOptions.providerOptions.mode = options.mode;
         if (options.balanced || options.strategy === 'balanced') {
@@ -173,16 +224,41 @@ Examples:
         }
         if (options.uploadAccountTokens)
             dispatchOptions.providerOptions.uploadAccountTokens = true;
-        // Dispatch
-        const spinner = ora({ text: `Dispatching to ${provider.name}...`, stream: process.stderr }).start();
+        // Dispatch. On a missing pre-provisioned target (Codex env / Factory
+        // computer), offer an interactive picker instead of a raw error.
+        const dispatchOnce = async () => {
+            const spinner = ora({ text: `Dispatching to ${provider.name}...`, stream: process.stderr }).start();
+            try {
+                const t = await provider.dispatch(dispatchOptions);
+                spinner.succeed(`Task ${t.id} dispatched to ${provider.name}`);
+                return t;
+            }
+            catch (err) {
+                spinner.fail('Dispatch failed');
+                throw err;
+            }
+        };
         let task;
         try {
-            task = await provider.dispatch(dispatchOptions);
-            spinner.succeed(`Task ${task.id} dispatched to ${provider.name}`);
+            task = await dispatchOnce();
         }
         catch (err) {
-            spinner.fail('Dispatch failed');
-            die(err.message);
+            if (err instanceof MissingTargetError) {
+                const picked = await pickMissingTarget(provider, err, json);
+                if (!picked) {
+                    die(err.guidance ? `${err.message}\n\n${err.guidance}` : err.message);
+                }
+                dispatchOptions.providerOptions[err.kind] = picked;
+                try {
+                    task = await dispatchOnce();
+                }
+                catch (err2) {
+                    die(err2.message);
+                }
+            }
+            else {
+                die(err.message);
+            }
         }
         // Persist locally
         insertTask(task);
@@ -413,4 +489,57 @@ Examples:
             console.log(`  ${p.id.padEnd(12)} ${p.name.padEnd(20)} ${status}${defaultTag}`);
         }
     });
+    // ── agents cloud envs ─────────────────────────────────────────────────
+    // Discover the pre-provisioned targets a provider runs inside — Codex
+    // environments, Factory Droid Computers — so users don't copy opaque IDs
+    // out of a web UI.
+    cloud
+        .command('envs')
+        .alias('targets')
+        .description('List the pre-provisioned targets (Codex environments / Droid Computers) you can dispatch into.')
+        .option('--provider <id>', 'Only this provider (codex, factory, ...)')
+        .option('--json', 'JSON output')
+        .action(async (options) => {
+        const json = isJsonMode(options);
+        const only = options.provider;
+        // Providers that run inside a pre-provisioned target declare targetKind.
+        const providers = getAllProviders().filter((p) => p.targetKind && (!only || p.id === only));
+        if (only && providers.length === 0) {
+            die(`Provider '${only}' has no pre-provisioned targets (or is unknown). Targets apply to: codex, factory.`);
+        }
+        const results = [];
+        for (const p of providers) {
+            const kind = p.targetKind;
+            if (!p.listTargets) {
+                // Not enumerable (Codex). Surface guidance instead of a list.
+                const guidance = kind === 'env'
+                    ? 'Codex environments are not listable from the CLI. Browse/create them with `codex cloud` (interactive), then use --env <id>.'
+                    : 'Not enumerable from the CLI.';
+                results.push({ provider: p.id, kind, targets: [], note: guidance });
+                continue;
+            }
+            try {
+                const targets = await p.listTargets();
+                results.push({ provider: p.id, kind, targets: targets.map((t) => ({ id: t.id, label: t.label })) });
+            }
+            catch (err) {
+                results.push({ provider: p.id, kind, targets: [], note: err.message });
+            }
+        }
+        if (json) {
+            process.stdout.write(JSON.stringify(results, null, 2) + '\n');
+            return;
+        }
+        for (const r of results) {
+            console.log(chalk.bold(`\n${r.provider}`) + chalk.dim(` (${r.kind})`));
+            if (r.targets.length > 0) {
+                for (const t of r.targets) {
+                    console.log(`  ${t.id}${t.label ? '  ' + chalk.dim(t.label) : ''}`);
+                }
+            }
+            else {
+                console.log(chalk.dim(`  ${r.note ?? 'none'}`));
+            }
+        }
+    });
 }

package/dist/commands/exec.js

@@ -150,6 +150,10 @@ export function registerRunCommand(program) {
 
       # Inject a keychain-backed secrets bundle
       agents run claude "deploy the worker" --secrets prod --mode edit
+
+      # Pass arbitrary native flags to the underlying CLI via -- separator
+      agents run kimi -- --plan --some-kimi-option value
+      agents run claude "fix the bug" -- --custom-flag
     `,
         notes: `
       Modes (not every agent supports every mode — check agents.yaml capabilities):
@@ -168,9 +172,16 @@ export function registerRunCommand(program) {
       Fallback: --fallback codex,gemini retries on rate-limit failure via /continue handoff. Each entry accepts @version.
 
       Resume: --session-id <id> continues a prior Claude conversation.
+
+      Passthrough: everything after -- is forwarded verbatim to the underlying agent CLI.
+        agents run kimi -- --plan --some-native-flag value
     `,
     });
-    runCmd.action(async (agentSpec, prompt, options) => {
+    runCmd.action(async (agentSpec, prompt, options, command) => {
+        // Capture everything after -- as passthrough args forwarded verbatim to the underlying CLI.
+        // Use command.args (all positional strings) and strip the declared positional args from the front.
+        const declaredArgCount = prompt !== undefined ? 2 : 1;
+        const passthroughArgs = command.args.slice(declaredArgCount);
         // --resume-checkpoint short-circuits normal dispatch entirely: the
         // checkpoint already carries the agent, version, prompt, session id,
         // iteration, and loop config of the killed run. Reconstruct ExecOptions
@@ -642,6 +653,7 @@ export function registerRunCommand(program) {
             env,
             toolsRestrict: workflowToolsRestrict,
             mcpConfigPath: workflowMcpConfigPath,
+            passthroughArgs,
         };
         if (options.interactive && options.headless) {
             console.error(chalk.red('--interactive and --headless are mutually exclusive. Pass one, or neither (mode is inferred from prompt presence).'));

package/dist/commands/menubar.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `agents menubar` — manage the macOS menu-bar helper.
+ *
+ * The helper is a no-Dock status-bar app that surfaces running sessions, agents
+ * needing input, and routines, and launches new sessions. It auto-installs on
+ * upgrade (runMigration -> installMenubarLaunchAgentOnUpgrade) for every macOS
+ * user; these commands are the manual override.
+ */
+import type { Command } from 'commander';
+export declare function registerMenubarCommands(program: Command): void;

package/dist/commands/menubar.js

@@ -0,0 +1,83 @@
+/**
+ * `agents menubar` — manage the macOS menu-bar helper.
+ *
+ * The helper is a no-Dock status-bar app that surfaces running sessions, agents
+ * needing input, and routines, and launches new sessions. It auto-installs on
+ * upgrade (runMigration -> installMenubarLaunchAgentOnUpgrade) for every macOS
+ * user; these commands are the manual override.
+ */
+import chalk from 'chalk';
+import { enableMenubarService, disableMenubarService, getMenubarStatus, } from '../lib/menubar/install-menubar.js';
+function notMac() {
+    if (process.platform !== 'darwin') {
+        console.log(chalk.yellow('The menu bar helper is macOS only.'));
+        return true;
+    }
+    return false;
+}
+export function registerMenubarCommands(program) {
+    const menubar = program
+        .command('menubar')
+        .description('Manage the macOS menu-bar helper (running sessions, agents awaiting input, routines)');
+    menubar
+        .command('enable')
+        .description('Install and start the menu-bar helper (launches at login)')
+        .action(() => {
+        if (notMac())
+            return;
+        const ok = enableMenubarService({ clearOptOut: true });
+        if (!ok) {
+            console.log(chalk.red('Could not enable: no menu-bar helper bundle ships with this install.'));
+            console.log(chalk.gray('  This build may predate the helper, or be a non-macOS package.'));
+            return;
+        }
+        console.log(chalk.green('Menu bar helper enabled.') + chalk.gray('  Look for the agents mark in your menu bar.'));
+    });
+    menubar
+        .command('disable')
+        .description('Stop and remove the menu-bar helper (stays off across upgrades)')
+        .action(() => {
+        if (notMac())
+            return;
+        disableMenubarService();
+        console.log(chalk.green('Menu bar helper disabled.') + chalk.gray('  Re-enable any time with `agents menubar enable`.'));
+    });
+    menubar
+        .command('status')
+        .description('Show whether the menu-bar helper is installed and running')
+        .option('--json', 'Emit machine-readable JSON')
+        .action((options) => {
+        const s = getMenubarStatus();
+        if (options.json) {
+            process.stdout.write(JSON.stringify(s) + '\n');
+            return;
+        }
+        if (s.platform !== 'darwin') {
+            console.log(chalk.yellow('The menu bar helper is macOS only.'));
+            return;
+        }
+        const yn = (b) => (b ? chalk.green('yes') : chalk.gray('no'));
+        console.log(chalk.bold('Menu bar helper\n'));
+        console.log(`  running            ${yn(s.running)}`);
+        console.log(`  service installed  ${yn(s.serviceInstalled)}`);
+        console.log(`  app installed      ${s.installedApp ? chalk.gray(s.installedApp) : chalk.gray('no')}`);
+        console.log(`  bundle source      ${s.source ? chalk.gray(s.source) : chalk.red('missing (cannot enable)')}`);
+        console.log(`  disabled by user   ${yn(s.disabledByUser)}`);
+        if (!s.serviceInstalled && !s.disabledByUser) {
+            console.log(chalk.gray('\n  Enable it with `agents menubar enable`.'));
+        }
+    });
+    // Bare `agents menubar` -> status.
+    menubar.action(() => {
+        const s = getMenubarStatus();
+        if (s.platform !== 'darwin') {
+            console.log(chalk.yellow('The menu bar helper is macOS only.'));
+            return;
+        }
+        const yn = (b) => (b ? chalk.green('yes') : chalk.gray('no'));
+        console.log(chalk.bold('Menu bar helper\n'));
+        console.log(`  running            ${yn(s.running)}`);
+        console.log(`  service installed  ${yn(s.serviceInstalled)}`);
+        console.log(chalk.gray('\n  enable | disable | status'));
+    });
+}

package/dist/commands/routines.js

@@ -124,9 +124,14 @@ export function registerRoutinesCommands(program) {
     routinesCmd
         .command('list')
         .description('See all scheduled jobs, when they run next, and their last execution status')
-        .action(() => {
+        .option('--json', 'Emit machine-readable JSON instead of the table (used by the menu bar helper)')
+        .action((options) => {
         const jobs = listAllJobs(process.cwd());
         if (jobs.length === 0) {
+            if (options.json) {
+                process.stdout.write('[]\n');
+                return;
+            }
             console.log(chalk.gray('No jobs configured'));
             console.log(chalk.gray('  Add a job: agents routines add <path-to-job.yml>'));
             return;
@@ -142,6 +147,34 @@ export function registerRoutinesCommands(program) {
         catch {
             // Best-effort indicator; never block the list on detection errors.
         }
+        // Machine-readable path: same data the table renders, but structured.
+        // The menu bar helper relies on this so it never reimplements cron math.
+        if (options.json) {
+            const nowJson = new Date();
+            const payload = jobs.map((job) => {
+                const nextRun = scheduler.getNextRun(job.name);
+                const latestRun = getLatestRun(job.name);
+                return {
+                    name: job.name,
+                    agent: job.agent ?? null,
+                    workflow: job.workflow ?? null,
+                    repo: job.repo ?? null,
+                    schedule: job.schedule,
+                    scheduleHuman: humanizeCron(job.schedule, job.timezone),
+                    timezone: job.timezone ?? null,
+                    enabled: job.enabled,
+                    overdue: overdueSet.has(job.name),
+                    nextRun: nextRun ? nextRun.toISOString() : null,
+                    nextRunHuman: humanizeNextRun(nextRun ?? null, nowJson, job.timezone),
+                    lastStatus: latestRun?.status ?? null,
+                    lastRunStartedAt: latestRun?.startedAt ?? null,
+                    lastRunCompletedAt: latestRun?.completedAt ?? null,
+                };
+            });
+            scheduler.stopAll();
+            process.stdout.write(JSON.stringify(payload) + '\n');
+            return;
+        }
         console.log(chalk.bold('Scheduled Jobs\n'));
         // OSC 8 hyperlink helper — renders as a clickable link in supporting terminals.
         // Guarded on process.stdout.isTTY so that piped/redirected output never

package/dist/commands/secrets.d.ts

@@ -5,7 +5,7 @@
  * and managing named bundles of environment variables backed by macOS
  * Keychain. Bundles are injected at run time via `agents run --secrets`.
  */
-import type { Command } from 'commander';
+import { type Command } from 'commander';
 /**
  * SSH target for `export --to-ssh`: a bare ssh-config host alias (e.g. `yosemite-s0`)
  * or `user@host`. The strict allowlist blocks shell metacharacters and a leading `-`