@phnx-labs/agents-cli 1.20.21 → 1.20.23

package/dist/lib/agents.js

@@ -207,6 +207,9 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
+        // Claude Code has no headless Anthropic-hosted dispatch CLI (only
+        // --remote-control, which bridges a *local* session). Its cloud is Rush.
+        cloudProvider: 'rush',
         capabilities: { hooks: true, mcp: true, allowlist: true, skills: true, commands: true, plugins: true, subagents: true, rules: { file: 'CLAUDE.md' }, workflows: true, modes: ['plan', 'edit', 'auto', 'skip'], rulesImports: true },
     },
     // codex hooks: gated to >= 0.116.0 (introduced [features] codex_hooks flag).
@@ -226,6 +229,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
+        cloudProvider: 'codex',
         capabilities: { hooks: { since: '0.116.0' }, mcp: true, allowlist: false, skills: true, commands: { until: '0.117.0' }, plugins: { since: '0.128.0' }, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit', 'skip'] },
     },
     gemini: {
@@ -412,6 +416,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '{{args}}',
         supportsHooks: true,
+        cloudProvider: 'antigravity',
         capabilities: { hooks: true, mcp: true, allowlist: true, skills: true, commands: true, plugins: true, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['edit', 'skip'], rulesImports: false },
     },
     // xAI Grok Build CLI (`grok`) — early beta, SuperGrok Heavy. Auth via OAuth on
@@ -509,6 +514,9 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
+        // Factory Droid Computers (cloud VMs) reached via `droid computer ssh` +
+        // remote headless `droid exec`.
+        cloudProvider: 'factory',
         capabilities: {
             hooks: false,
             mcp: true,

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

@@ -0,0 +1,70 @@
+/**
+ * Antigravity cloud provider — Google's Antigravity agent via the Gemini
+ * **Managed Agents Interactions API**.
+ *
+ * The `agy` CLI is local-only (`--print` / `--sandbox`); Antigravity's cloud
+ * surface is an HTTP endpoint that runs the Antigravity harness in a remote
+ * ephemeral Linux sandbox:
+ *
+ *   POST https://generativelanguage.googleapis.com/v1beta/interactions
+ *   x-goog-api-key: <GEMINI_API_KEY>
+ *   { "agent": "antigravity-preview-05-2026", "input": "<prompt>", "environment": "remote" }
+ *
+ * The call is synchronous by default (the response carries `status` +
+ * `output_text`), so `dispatch()` awaits it, returns a terminal CloudTask, and
+ * `stream()` replays the buffered text + done events — same shape as the Factory
+ * provider. It is a raw sandbox: no GitHub repo → PR (that's Rush's job).
+ *
+ * Auth: the Gemini API key comes from an `agents secrets` bundle named in
+ * `cloud.providers.antigravity.secretsBundle` (never from agents.yaml), falling
+ * back to GEMINI_API_KEY / GOOGLE_API_KEY in the environment.
+ */
+import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions, ProviderCapabilities } from './types.js';
+/** Shape of the Interactions API response we consume (defensive: all optional). */
+interface InteractionResponse {
+    id?: string;
+    interaction_id?: string;
+    environment_id?: string;
+    status?: string;
+    output_text?: string;
+    error?: {
+        message?: string;
+    } | string;
+}
+/** Map an Interactions API status string to the canonical CloudTaskStatus. */
+export declare function mapStatus(s: string | undefined): CloudTaskStatus;
+/** Build the Interactions API request body for a fresh dispatch. */
+export declare function buildInteractionBody(prompt: string, model: string): Record<string, unknown>;
+/** Parse an Interactions API response into a CloudTask (minus prompt/timestamps). */
+export declare function parseInteraction(resp: InteractionResponse): {
+    id: string;
+    status: CloudTaskStatus;
+    summary?: string;
+    environmentId?: string;
+};
+export declare class AntigravityCloudProvider implements CloudProvider {
+    id: "antigravity";
+    name: string;
+    private secretsBundle?;
+    private model;
+    private runs;
+    constructor(config?: {
+        secretsBundle?: string;
+        model?: string;
+    });
+    /**
+     * True when a key *source* is configured. Cheap: never resolves the bundle
+     * (which could prompt for biometry) — that happens lazily at dispatch.
+     */
+    private hasKeySource;
+    /** Resolve the Gemini API key from the configured bundle or the environment. */
+    private resolveApiKey;
+    capabilities(): ProviderCapabilities;
+    dispatch(options: DispatchOptions): Promise<CloudTask>;
+    status(taskId: string): Promise<CloudTask>;
+    list(): Promise<CloudTask[]>;
+    stream(taskId: string): AsyncIterable<CloudEvent>;
+    cancel(_taskId: string): Promise<void>;
+    message(_taskId: string, _content: string): Promise<void>;
+}
+export {};

package/dist/lib/cloud/antigravity.js

@@ -0,0 +1,196 @@
+/**
+ * Antigravity cloud provider — Google's Antigravity agent via the Gemini
+ * **Managed Agents Interactions API**.
+ *
+ * The `agy` CLI is local-only (`--print` / `--sandbox`); Antigravity's cloud
+ * surface is an HTTP endpoint that runs the Antigravity harness in a remote
+ * ephemeral Linux sandbox:
+ *
+ *   POST https://generativelanguage.googleapis.com/v1beta/interactions
+ *   x-goog-api-key: <GEMINI_API_KEY>
+ *   { "agent": "antigravity-preview-05-2026", "input": "<prompt>", "environment": "remote" }
+ *
+ * The call is synchronous by default (the response carries `status` +
+ * `output_text`), so `dispatch()` awaits it, returns a terminal CloudTask, and
+ * `stream()` replays the buffered text + done events — same shape as the Factory
+ * provider. It is a raw sandbox: no GitHub repo → PR (that's Rush's job).
+ *
+ * Auth: the Gemini API key comes from an `agents secrets` bundle named in
+ * `cloud.providers.antigravity.secretsBundle` (never from agents.yaml), falling
+ * back to GEMINI_API_KEY / GOOGLE_API_KEY in the environment.
+ */
+import { resolveDispatchRepos } from './types.js';
+import { readAndResolveBundleEnv } from '../secrets/bundles.js';
+const INTERACTIONS_URL = 'https://generativelanguage.googleapis.com/v1beta/interactions';
+const DEFAULT_MODEL = 'antigravity-preview-05-2026';
+const KEY_NAMES = ['GEMINI_API_KEY', 'GOOGLE_API_KEY'];
+/** Map an Interactions API status string to the canonical CloudTaskStatus. */
+export function mapStatus(s) {
+    const lower = (s ?? '').toLowerCase();
+    if (lower.includes('queue') || lower.includes('pending'))
+        return 'queued';
+    if (lower.includes('run') || lower.includes('progress'))
+        return 'running';
+    if (lower.includes('complete') || lower.includes('success'))
+        return 'completed';
+    if (lower.includes('fail') || lower.includes('error'))
+        return 'failed';
+    if (lower.includes('cancel'))
+        return 'cancelled';
+    return 'completed';
+}
+/** Build the Interactions API request body for a fresh dispatch. */
+export function buildInteractionBody(prompt, model) {
+    return {
+        agent: model,
+        input: prompt,
+        environment: 'remote',
+    };
+}
+/** Parse an Interactions API response into a CloudTask (minus prompt/timestamps). */
+export function parseInteraction(resp) {
+    const id = resp.id ?? resp.interaction_id ?? `antigravity-${Date.now()}`;
+    return {
+        id,
+        status: mapStatus(resp.status),
+        summary: resp.output_text,
+        environmentId: resp.environment_id,
+    };
+}
+export class AntigravityCloudProvider {
+    id = 'antigravity';
+    name = 'Antigravity (Gemini)';
+    secretsBundle;
+    model;
+    runs = new Map();
+    constructor(config) {
+        this.secretsBundle = config?.secretsBundle;
+        this.model = config?.model ?? DEFAULT_MODEL;
+    }
+    /**
+     * True when a key *source* is configured. Cheap: never resolves the bundle
+     * (which could prompt for biometry) — that happens lazily at dispatch.
+     */
+    hasKeySource() {
+        if (this.secretsBundle)
+            return true;
+        return KEY_NAMES.some((k) => Boolean(process.env[k]));
+    }
+    /** Resolve the Gemini API key from the configured bundle or the environment. */
+    resolveApiKey() {
+        if (this.secretsBundle) {
+            try {
+                const { env } = readAndResolveBundleEnv(this.secretsBundle, { caller: 'cloud:antigravity' });
+                for (const k of KEY_NAMES) {
+                    if (env[k])
+                        return env[k];
+                }
+                throw new Error(`Secrets bundle '${this.secretsBundle}' has no ${KEY_NAMES.join(' or ')}. Add one: agents secrets add ${this.secretsBundle} GEMINI_API_KEY`);
+            }
+            catch (err) {
+                throw new Error(`Could not read Gemini API key from bundle '${this.secretsBundle}': ${err.message}`);
+            }
+        }
+        for (const k of KEY_NAMES) {
+            const v = process.env[k];
+            if (v)
+                return v;
+        }
+        throw new Error(`Antigravity cloud needs a Gemini API key. Set cloud.providers.antigravity.secretsBundle in ~/.agents/agents.yaml, or export ${KEY_NAMES.join(' / ')}.`);
+    }
+    capabilities() {
+        const available = this.hasKeySource();
+        return {
+            available,
+            dispatch: available,
+            status: available,
+            list: available,
+            stream: available,
+            cancel: false,
+            message: false,
+            multiRepo: false,
+            skills: false,
+            images: false,
+        };
+    }
+    async dispatch(options) {
+        // The Interactions sandbox has no GitHub repo → PR flow. Reject repos
+        // loudly rather than silently ignoring them (point the user at Rush).
+        const repos = resolveDispatchRepos(options);
+        if (repos.length > 0) {
+            throw new Error(`Antigravity cloud is a raw sandbox with no GitHub repo → PR flow. Got repo(s): ${repos.join(', ')}. ` +
+                `Use --provider rush for repo-backed dispatch.`);
+        }
+        const apiKey = this.resolveApiKey();
+        const model = options.model ?? this.model;
+        const body = buildInteractionBody(options.prompt, model);
+        let resp;
+        try {
+            resp = await fetch(INTERACTIONS_URL, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', 'x-goog-api-key': apiKey },
+                body: JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            throw new Error(`Antigravity dispatch failed (network): ${err.message}`);
+        }
+        const text = await resp.text();
+        if (!resp.ok) {
+            throw new Error(`Antigravity dispatch failed (${resp.status}): ${text.slice(0, 500)}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`Antigravity returned non-JSON response: ${text.slice(0, 300)}`);
+        }
+        const { id, status, summary } = parseInteraction(parsed);
+        const now = new Date().toISOString();
+        const task = {
+            id,
+            provider: 'antigravity',
+            status,
+            agent: 'antigravity',
+            prompt: options.prompt,
+            summary,
+            createdAt: now,
+            updatedAt: now,
+        };
+        const events = [];
+        if (summary)
+            events.push({ type: 'text', content: summary, timestamp: now });
+        events.push({ type: 'done', status, summary, timestamp: now });
+        this.runs.set(id, { events, task });
+        return task;
+    }
+    async status(taskId) {
+        const run = this.runs.get(taskId);
+        if (run)
+            return run.task;
+        throw new Error(`No live status for Antigravity task ${taskId} (synchronous interaction; see local cache).`);
+    }
+    async list() {
+        return [...this.runs.values()].map((r) => r.task);
+    }
+    async *stream(taskId) {
+        const run = this.runs.get(taskId);
+        if (!run) {
+            yield {
+                type: 'error',
+                message: `Antigravity interaction ${taskId} is not buffered in this process. The interaction is synchronous — see 'agents cloud status ${taskId}' for the result.`,
+                timestamp: new Date().toISOString(),
+            };
+            return;
+        }
+        for (const event of run.events)
+            yield event;
+    }
+    async cancel(_taskId) {
+        throw new Error('Cancel is not supported for Antigravity — interactions run synchronously to completion.');
+    }
+    async message(_taskId, _content) {
+        throw new Error('Follow-up messages are not yet supported for Antigravity cloud tasks.');
+    }
+}

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

@@ -9,6 +9,7 @@ import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOpt
 export declare class CodexCloudProvider implements CloudProvider {
     id: "codex";
     name: string;
+    targetKind: "env";
     private defaultEnv?;
     constructor(config?: {
         env?: string;

package/dist/lib/cloud/codex.js

@@ -8,7 +8,7 @@
 import { spawn, execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
-import { resolveDispatchRepos } from './types.js';
+import { resolveDispatchRepos, MissingTargetError } from './types.js';
 import { getShimsDir } from '../state.js';
 const SHIMS_DIR = getShimsDir();
 /** Map a Codex Cloud status string to the canonical CloudTaskStatus enum. */
@@ -85,6 +85,10 @@ function parseTaskFromText(text) {
 export class CodexCloudProvider {
     id = 'codex';
     name = 'Codex Cloud';
+    targetKind = 'env';
+    // No listTargets: OpenAI ships no non-interactive "list environments"
+    // command. `codex cloud exec` requires --env and the help points at the
+    // interactive `codex cloud` TUI to browse. So discovery is guidance-only.
     defaultEnv;
     constructor(config) {
         this.defaultEnv = config?.env;
@@ -107,7 +111,9 @@ export class CodexCloudProvider {
     async dispatch(options) {
         const env = options.providerOptions?.env ?? this.defaultEnv;
         if (!env) {
-            throw new Error('Codex Cloud requires --env <id>. Set a default in ~/.agents/agents.yaml under cloud.providers.codex.env.');
+            throw new MissingTargetError('env', 'Codex Cloud requires --env <id>.', 'Codex environments are created in the Codex web UI and bundle a repo + setup. ' +
+                'Browse yours with `codex cloud` (interactive), then re-run with --env <id> ' +
+                'or set a default in ~/.agents/agents.yaml under cloud.providers.codex.env.');
         }
         // Codex envs bundle their own repo list — the repos a task can touch are
         // fixed at env-creation time, not per-dispatch. Passing 2+ repos here is

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

@@ -1,31 +1,92 @@
 /**
- * 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 type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions, ProviderCapabilities } 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;
 /**
- * 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.
+ * 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`.
+ */
+export declare function buildExecArgs(prompt: string, opts: {
+    autonomy: DroidAutonomy;
+    sessionId?: string;
+}): string[];
+/**
+ * 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 declare function buildSshArgs(computer: string, remoteBin: string, remoteArgv: string[], opts: {
+    droidBin: string;
+    user: string;
+    port?: string;
+}): string[];
+/** Map a droid stream-json `result.subtype` / `is_error` to a CloudTaskStatus. */
+export declare function mapResultStatus(line: {
+    is_error?: boolean;
+    subtype?: string;
+}): CloudTaskStatus;
+/**
+ * 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 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. */
+    private runs;
+    constructor(config?: {
+        computer?: string;
+        autonomy?: DroidAutonomy;
+    });
     capabilities(): ProviderCapabilities;
-    dispatch(_options: DispatchOptions): Promise<CloudTask>;
-    status(_taskId: string): Promise<CloudTask>;
-    list(_filter?: {
-        status?: CloudTaskStatus;
-    }): Promise<CloudTask[]>;
-    stream(_taskId: string): AsyncIterable<CloudEvent>;
+    /** 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;
+    status(taskId: string): Promise<CloudTask>;
+    list(): Promise<CloudTask[]>;
+    stream(taskId: string): AsyncIterable<CloudEvent>;
     cancel(_taskId: string): Promise<void>;
     message(_taskId: string, _content: string): Promise<void>;
 }