@phnx-labs/agents-cli 1.20.22 → 1.20.23

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,6 +44,47 @@ 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
@@ -182,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);
@@ -422,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).'));