@phnx-labs/agents-cli 1.20.21 → 1.20.22

package/dist/lib/cloud/factory.js

@@ -1,30 +1,176 @@
 /**
- * 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 { 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;
+}
 /**
- * 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)';
+    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 +178,119 @@ export class FactoryCloudProvider {
             images: false,
         };
     }
-    async dispatch(_options) {
-        throw new Error('Factory cloud provider is not yet available. Coming in a future release.');
+    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 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`.');
+        }
+        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.
  *
@@ -188,14 +199,33 @@ export interface CloudProvider {
     /** Send a follow-up message to a finished/idle/needs_review task. */
     message(taskId: string, content: string): Promise<void>;
 }
+/** 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/menubar/install-menubar.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Install + lifecycle for the macOS menu-bar helper (`MenubarHelper.app`).
+ *
+ * Mirrors `src/lib/secrets/install-helper.ts` (stable Application Support path,
+ * survives npm re-sign) and the secrets-agent launchd pattern in
+ * `src/lib/secrets/agent.ts` (RunAtLoad + KeepAlive user service).
+ *
+ * The helper is a no-Dock `.accessory` status-bar app. It reads live agent
+ * state directly from disk and shells `agents` only for actions, so the plist
+ * bakes in the node interpreter + entry point + bin path so the GUI process can
+ * find the CLI without a login PATH.
+ *
+ * Opt-out is sticky: `agents menubar disable` drops a sentinel that the upgrade
+ * migration (`installMenubarLaunchAgent` in migrate.ts) honors, so a disabled
+ * menu bar never silently comes back on the next release.
+ */
+/** True if the user explicitly disabled the menu bar (don't auto-enable on upgrade). */
+export declare function menubarDisabledByUser(): boolean;
+/** True if the launchd plist for the menu-bar service is installed. */
+export declare function menubarServiceInstalled(): boolean;
+/**
+ * Copy the bundled `.app` to the stable user path (idempotent unless forced).
+ * Returns the installed executable path, or null if no source bundle ships
+ * with this install (e.g. Linux package, or a build without the helper).
+ */
+export declare function ensureMenubarAppInstalled(opts?: {
+    forceReinstall?: boolean;
+}): string | null;
+/**
+ * Install + start the menu-bar helper as a launchd user service (idempotent).
+ * Clears the sticky opt-out, installs the .app, writes the plist, and
+ * bootstraps it into the GUI domain. Returns false on non-darwin or when no
+ * helper bundle ships with this install.
+ */
+export declare function enableMenubarService(opts?: {
+    clearOptOut?: boolean;
+}): boolean;
+/**
+ * Stop + remove the menu-bar service and write the sticky opt-out so the
+ * upgrade migration won't re-enable it.
+ */
+export declare function disableMenubarService(): void;
+/**
+ * Upgrade-time auto-enable. Runs from runMigration() once per sentinel bump.
+ * No-ops if: not darwin, the user opted out, no helper bundle ships, or the
+ * service is already installed. Best-effort — never throws into migration.
+ */
+export declare function installMenubarLaunchAgentOnUpgrade(): void;
+export interface MenubarStatus {
+    platform: string;
+    source: string | null;
+    installedApp: string | null;
+    serviceInstalled: boolean;
+    running: boolean;
+    disabledByUser: boolean;
+}
+export declare function getMenubarStatus(): MenubarStatus;