@phnx-labs/agents-cli 1.20.21 → 1.20.23

package/dist/lib/cloud/factory.js

@@ -1,30 +1,217 @@
 /**
- * Factory/Droid cloud provider -- stub for Phase 2.
+ * Factory (Droid) cloud provider.
  *
- * Will dispatch tasks to a `droid daemon` running on a remote machine.
- * All methods throw until the droid daemon API is documented and stable.
+ * Dispatches to a Factory **Droid Computer** — a persistent cloud VM (managed
+ * by Factory, or bring-your-own via `droid computer register`). There is no
+ * `droid cloud run`; remote execution = reach the computer over the Droid relay
+ * (`droid computer ssh <name>`) and run a headless `droid exec` there.
+ *
+ * `droid exec` is synchronous (it runs to completion and exits, unlike Codex
+ * Cloud which is async server-side). So `dispatch()` runs the remote exec to
+ * completion with `--output-format stream-json`, buffers the NDJSON events, and
+ * `stream()` replays them. The task id is droid's own `session_id` (captured
+ * from the run output), so it lines up with `droid exec -s <id>` for future
+ * resume support.
+ *
+ * Transport note: the exact relay SSH composition (user + ProxyCommand) is
+ * built in `buildSshArgs()` and must be confirmed against a live provisioned
+ * Droid Computer (Factory auth required). `capabilities().available` gates on
+ * the droid binary + a configured computer so the provider fails with a clear
+ * message rather than misfiring when unconfigured.
+ */
+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';
+const VALID_AUTONOMY = new Set(['low', 'medium', 'high']);
+/** Locate the droid binary, checking agents-cli shims first then PATH. */
+export function findDroidBinary() {
+    const shim = path.join(SHIMS_DIR, 'droid');
+    if (fs.existsSync(shim))
+        return shim;
+    try {
+        return execFileSync('which', ['droid'], { stdio: 'pipe' }).toString().trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Normalize an autonomy value, falling back to the safe cloud default (`high`). */
+export function resolveAutonomy(value, fallback = DEFAULT_AUTONOMY) {
+    return typeof value === 'string' && VALID_AUTONOMY.has(value)
+        ? 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;
+}
 /**
- * Factory/Droid cloud provider — stub for Phase 2.
- *
- * Integration path: `droid daemon` running on a remote machine (workstation, cloud VM, k8s pod).
- * Dispatch via HTTP to the daemon, stream output, cancel via HTTP DELETE.
+ * Build the remote `droid exec` argv. Headless, stream-json output, given
+ * autonomy. `sessionId` (when resuming) maps to `-s`.
+ */
+export function buildExecArgs(prompt, opts) {
+    const args = ['exec', '--auto', opts.autonomy, '--output-format', 'stream-json'];
+    if (opts.sessionId)
+        args.push('-s', opts.sessionId);
+    args.push(prompt);
+    return args;
+}
+/**
+ * Build the `ssh` argv that runs a remote command on a Droid Computer through
+ * the Droid relay. The relay is used as an OpenSSH ProxyCommand
+ * (`droid computer ssh <name> --proxy`), so the connection rides Factory's
+ * brokered tunnel rather than a directly reachable host.
  *
- * Not yet implemented because:
- * 1. Droid v0.104 has no cloud dispatch command (droid exec is local only)
- * 2. droid daemon API isn't documented yet
- * 3. droid computer register/ssh is the remote execution primitive but needs exploration
+ * `remoteArgv` is the already-built remote command (e.g. droid exec argv); it is
+ * shell-quoted into a single remote command string.
  */
+export function buildSshArgs(computer, remoteBin, remoteArgv, opts) {
+    const remoteCmd = [remoteBin, ...remoteArgv].map(shellQuote).join(' ');
+    const proxy = `ProxyCommand=${opts.droidBin} computer ssh ${computer} --proxy --port %p`;
+    return [
+        '-o', proxy,
+        '-o', 'StrictHostKeyChecking=accept-new',
+        '-p', opts.port ?? '22',
+        `${opts.user}@${computer}`,
+        remoteCmd,
+    ];
+}
+/** POSIX single-quote a shell argument. */
+function shellQuote(arg) {
+    return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+/** Map a droid stream-json `result.subtype` / `is_error` to a CloudTaskStatus. */
+export function mapResultStatus(line) {
+    if (line.is_error)
+        return 'failed';
+    if (line.subtype && /cancel/i.test(line.subtype))
+        return 'cancelled';
+    return 'completed';
+}
+/**
+ * Map one parsed droid stream-json event to a CloudEvent. The stream-json
+ * schema is only partially documented, so this is defensive: known shapes map
+ * to typed events, everything else surfaces as `unknown` rather than being
+ * dropped (mirrors the rest of the cloud event pipeline).
+ */
+export function mapDroidEvent(obj) {
+    const ts = new Date().toISOString();
+    const type = String(obj.type ?? '');
+    switch (type) {
+        case 'result': {
+            return {
+                type: 'done',
+                status: mapResultStatus(obj),
+                summary: typeof obj.result === 'string' ? obj.result : undefined,
+                timestamp: ts,
+            };
+        }
+        case 'assistant':
+        case 'message':
+        case 'text': {
+            const content = extractText(obj);
+            if (content)
+                return { type: 'text', content, timestamp: ts };
+            break;
+        }
+        case 'thinking':
+        case 'reasoning': {
+            const content = extractText(obj);
+            if (content)
+                return { type: 'thinking', content, timestamp: ts };
+            break;
+        }
+        case 'tool_call':
+        case 'tool_use': {
+            return { type: 'tool_use', tool: String(obj.name ?? obj.tool ?? 'tool'), input: obj.input ?? obj.arguments ?? {}, timestamp: ts };
+        }
+        case 'tool_result': {
+            return { type: 'tool_result', tool: String(obj.name ?? obj.tool ?? 'tool'), output: obj.output ?? obj.result ?? '', timestamp: ts };
+        }
+        case 'error': {
+            return { type: 'error', message: String(obj.message ?? obj.error ?? 'unknown error'), timestamp: ts };
+        }
+    }
+    return { type: 'unknown', name: type || 'unknown', data: JSON.stringify(obj), timestamp: ts };
+}
+/** Pull a text string out of the varied droid message shapes. */
+function extractText(obj) {
+    if (typeof obj.text === 'string')
+        return obj.text;
+    if (typeof obj.content === 'string')
+        return obj.content;
+    if (Array.isArray(obj.content)) {
+        return obj.content
+            .map((c) => (c && typeof c === 'object' && typeof c.text === 'string' ? c.text : ''))
+            .join('');
+    }
+    const msg = obj.message;
+    if (msg && typeof msg === 'object')
+        return extractText(msg);
+    return '';
+}
 export class FactoryCloudProvider {
     id = 'factory';
     name = 'Factory (Droid)';
+    targetKind = 'computer';
+    defaultComputer;
+    defaultAutonomy;
+    /** session_id → buffered run, populated by dispatch, drained by stream. */
+    runs = new Map();
+    constructor(config) {
+        this.defaultComputer = config?.computer;
+        this.defaultAutonomy = resolveAutonomy(config?.autonomy);
+    }
     capabilities() {
+        const droid = findDroidBinary() !== null;
+        const computer = Boolean(this.defaultComputer);
         return {
-            available: false,
-            dispatch: false,
-            status: false,
-            list: false,
-            stream: false,
+            // Reachable only when the droid binary exists AND a computer is set.
+            // (A per-dispatch --computer can still override the missing default.)
+            available: droid && computer,
+            dispatch: droid,
+            status: droid,
+            list: droid,
+            stream: droid,
             cancel: false,
             message: false,
             multiRepo: false,
@@ -32,22 +219,133 @@ export class FactoryCloudProvider {
             images: false,
         };
     }
-    async dispatch(_options) {
-        throw new Error('Factory cloud provider is not yet available. Coming in a future release.');
+    /** 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) {
+            throw new Error('droid CLI not found. Install it: curl -fsSL https://app.factory.ai/cli | sh');
+        }
+        const computer = options.providerOptions?.computer ?? this.defaultComputer;
+        if (!computer) {
+            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';
+        const execArgs = buildExecArgs(options.prompt, { autonomy });
+        const sshArgs = buildSshArgs(computer, 'droid', execArgs, { droidBin, user });
+        const { events, status, summary, sessionId } = await this.runRemote(sshArgs);
+        const now = new Date().toISOString();
+        const id = sessionId ?? `droid-${Date.now()}`;
+        const task = {
+            id,
+            provider: 'factory',
+            status,
+            agent: 'droid',
+            prompt: options.prompt,
+            summary,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.runs.set(id, { events, task });
+        return task;
+    }
+    /** Run the remote droid exec to completion, collecting events + final result. */
+    runRemote(sshArgs) {
+        return new Promise((resolve, reject) => {
+            const proc = spawn('ssh', sshArgs, { stdio: ['ignore', 'pipe', 'pipe'] });
+            const events = [];
+            let status = 'failed';
+            let summary;
+            let sessionId;
+            let stdoutBuf = '';
+            let stderr = '';
+            const handleLine = (line) => {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    return;
+                let obj;
+                try {
+                    obj = JSON.parse(trimmed);
+                }
+                catch {
+                    // Non-JSON line (banner, ssh notice) — surface it, don't drop it.
+                    events.push({ type: 'unknown', name: 'stdout', data: trimmed, timestamp: new Date().toISOString() });
+                    return;
+                }
+                if (typeof obj.session_id === 'string')
+                    sessionId = obj.session_id;
+                const event = mapDroidEvent(obj);
+                if (event.type === 'done') {
+                    status = event.status ?? 'completed';
+                    summary = event.summary ?? summary;
+                }
+                events.push(event);
+            };
+            proc.stdout.on('data', (d) => {
+                stdoutBuf += d.toString();
+                const lines = stdoutBuf.split('\n');
+                stdoutBuf = lines.pop() ?? '';
+                for (const line of lines)
+                    handleLine(line);
+            });
+            proc.stderr.on('data', (d) => { stderr += d.toString(); });
+            proc.on('error', (err) => reject(err));
+            proc.on('close', (code) => {
+                if (stdoutBuf)
+                    handleLine(stdoutBuf);
+                if (code !== 0 && events.every((e) => e.type !== 'done')) {
+                    // Surface the auth error verbatim — it's the common first-run failure.
+                    const detail = stderr.trim() || `ssh exited ${code}`;
+                    reject(new Error(`Factory dispatch failed: ${detail}`));
+                    return;
+                }
+                resolve({ events, status, summary, sessionId });
+            });
+        });
     }
-    async status(_taskId) {
-        throw new Error('Factory cloud provider is not yet available.');
+    async status(taskId) {
+        const run = this.runs.get(taskId);
+        if (run)
+            return run.task;
+        // No remote task registry — the command layer falls back to the local store.
+        throw new Error(`No live status for Factory task ${taskId} (synchronous run; see local cache).`);
     }
-    async list(_filter) {
-        return [];
+    async list() {
+        // Factory has no remote task list; `agents cloud list` reads the local store.
+        return [...this.runs.values()].map((r) => r.task);
     }
-    async *stream(_taskId) {
-        throw new Error('Factory cloud provider is not yet available.');
+    async *stream(taskId) {
+        const run = this.runs.get(taskId);
+        if (!run) {
+            yield {
+                type: 'error',
+                message: `Factory run ${taskId} is not buffered in this process. droid exec is synchronous — its output is not retained after the run completes. See 'agents cloud status ${taskId}' for the summary.`,
+                timestamp: new Date().toISOString(),
+            };
+            return;
+        }
+        for (const event of run.events)
+            yield event;
     }
     async cancel(_taskId) {
-        throw new Error('Factory cloud provider is not yet available.');
+        throw new Error('Cancel is not supported for Factory (Droid) — droid exec runs synchronously to completion.');
     }
     async message(_taskId, _content) {
-        throw new Error('Factory cloud provider is not yet available.');
+        throw new Error('Follow-up messages are not yet supported for Factory (Droid) cloud tasks.');
     }
 }

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

@@ -5,11 +5,27 @@
  * implementations, and exposes lookup helpers used by the `agents cloud` commands.
  */
 import type { CloudProvider, CloudProviderId } from './types.js';
+/**
+ * The cloud provider an agent dispatches to by default. Reads the canonical
+ * `cloudProvider` field on the agent registry entry — one source of truth, no
+ * side map. Returns undefined for agents with no native cloud.
+ */
+export declare function nativeProviderForAgent(agentId: string): CloudProviderId | undefined;
 /** Look up a provider by ID, throwing if the ID is unknown. */
 export declare function getProvider(id: CloudProviderId): CloudProvider;
 /** Return the user's configured default provider, falling back to 'rush'. */
 export declare function getDefaultProviderId(): CloudProviderId;
 /** Return every registered provider (used by `agents cloud providers`). */
 export declare function getAllProviders(): CloudProvider[];
-/** Resolve the active provider from an explicit flag or the configured default. */
-export declare function resolveProvider(explicit?: string): CloudProvider;
+/**
+ * Resolve the active provider for a dispatch.
+ *
+ * Precedence: explicit `--provider` > the agent's native cloud
+ * (`cloudProvider`) > configured `cloud.default_provider` > `rush`. This is
+ * what makes `agents cloud run --agent droid` land on Factory and
+ * `--agent codex` land on Codex Cloud without the user naming a provider.
+ *
+ * Callers that already hold a concrete provider id (e.g. resolving a stored
+ * task's provider) pass it as `explicit` and the agent arg is ignored.
+ */
+export declare function resolveProvider(explicit?: string, agentId?: string): CloudProvider;

package/dist/lib/cloud/registry.js

@@ -10,7 +10,9 @@ import * as yaml from 'yaml';
 import { RushCloudProvider } from './rush.js';
 import { CodexCloudProvider } from './codex.js';
 import { FactoryCloudProvider } from './factory.js';
+import { AntigravityCloudProvider } from './antigravity.js';
 import { getUserAgentsDir } from '../state.js';
+import { AGENTS } from '../agents.js';
 const META_FILE = path.join(getUserAgentsDir(), 'agents.yaml');
 let _config = null;
 /** Parse the `cloud` section from agents.yaml, caching the result for the process lifetime. */
@@ -39,7 +41,17 @@ function initProviders() {
     const config = loadCloudConfig();
     providers.set('rush', new RushCloudProvider());
     providers.set('codex', new CodexCloudProvider(config.providers?.codex));
-    providers.set('factory', new FactoryCloudProvider());
+    providers.set('factory', new FactoryCloudProvider(config.providers?.factory));
+    providers.set('antigravity', new AntigravityCloudProvider(config.providers?.antigravity));
+}
+/**
+ * The cloud provider an agent dispatches to by default. Reads the canonical
+ * `cloudProvider` field on the agent registry entry — one source of truth, no
+ * side map. Returns undefined for agents with no native cloud.
+ */
+export function nativeProviderForAgent(agentId) {
+    const agent = AGENTS[agentId];
+    return agent?.cloudProvider;
 }
 /** Look up a provider by ID, throwing if the ID is unknown. */
 export function getProvider(id) {
@@ -60,8 +72,20 @@ export function getAllProviders() {
     initProviders();
     return [...providers.values()];
 }
-/** Resolve the active provider from an explicit flag or the configured default. */
-export function resolveProvider(explicit) {
-    const id = (explicit ?? getDefaultProviderId());
+/**
+ * Resolve the active provider for a dispatch.
+ *
+ * Precedence: explicit `--provider` > the agent's native cloud
+ * (`cloudProvider`) > configured `cloud.default_provider` > `rush`. This is
+ * what makes `agents cloud run --agent droid` land on Factory and
+ * `--agent codex` land on Codex Cloud without the user naming a provider.
+ *
+ * Callers that already hold a concrete provider id (e.g. resolving a stored
+ * task's provider) pass it as `explicit` and the agent arg is ignored.
+ */
+export function resolveProvider(explicit, agentId) {
+    const id = (explicit
+        ?? (agentId ? nativeProviderForAgent(agentId) : undefined)
+        ?? getDefaultProviderId());
     return getProvider(id);
 }

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

@@ -5,8 +5,19 @@
  * Factory) implement, plus the shared task and event types that flow through
  * the dispatch pipeline.
  */
-/** Identifier for a supported cloud dispatch backend. */
-export type CloudProviderId = 'rush' | 'codex' | 'factory';
+/**
+ * Identifier for a supported cloud dispatch backend.
+ *
+ * Each id is one agent's *own* cloud:
+ *   - `rush`        — Rush Cloud (runs Claude against a GitHub repo → PR)
+ *   - `codex`       — OpenAI Codex Cloud (`codex cloud exec`)
+ *   - `factory`     — Factory Droid Computers (`droid computer ssh` + remote `droid exec`)
+ *   - `antigravity` — Google Gemini Managed Agents (Interactions API)
+ *
+ * Agents route to their native cloud automatically (see `cloudProvider` in the
+ * agent registry); `--provider` overrides.
+ */
+export type CloudProviderId = 'rush' | 'codex' | 'factory' | 'antigravity';
 /**
  * Lifecycle state of a cloud-dispatched task.
  *
@@ -164,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.
  *
@@ -187,15 +225,48 @@ 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';
 /** Per-provider configuration stored in the `cloud.providers` section of agents.yaml. */
 export interface CloudProviderConfig {
     rush?: Record<string, string>;
     codex?: {
         env?: string;
     };
+    /**
+     * Factory (Droid) cloud. `computer` is the pre-provisioned Droid Computer
+     * name (managed in Factory's UI, or BYOM via `droid computer register`) —
+     * the Factory analogue of Codex's pre-built `env`. `autonomy` is the default
+     * `droid exec --auto` level for cloud runs (defaults to `high`).
+     */
     factory?: {
         computer?: string;
+        autonomy?: DroidAutonomy;
+    };
+    /**
+     * Antigravity (Gemini Managed Agents) cloud. The Gemini API key is read from
+     * an `agents secrets` bundle named here (never stored in agents.yaml); if
+     * unset, the provider falls back to GEMINI_API_KEY / GOOGLE_API_KEY in the
+     * environment. `model` overrides the default managed-agent id.
+     */
+    antigravity?: {
+        secretsBundle?: string;
+        model?: string;
     };
 }
 /** Top-level `cloud` section of agents.yaml. */

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>