@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/lib/cloud/codex.js

@@ -1,9 +1,17 @@
+/**
+ * Codex Cloud provider -- wraps the `codex` CLI for cloud dispatch.
+ *
+ * Delegates to `codex cloud exec/status/list` subcommands, parsing their
+ * JSON or text output into the unified CloudTask format. Streaming is
+ * emulated via polling since Codex Cloud lacks an SSE endpoint.
+ */
 import { spawn, execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
-import * as os from 'os';
-const SHIMS_DIR = path.join(os.homedir(), '.agents', 'shims');
-/** Map Codex Cloud status strings to our canonical status. */
+import { resolveDispatchRepos } from './types.js';
+import { getShimsDir } from '../state.js';
+const SHIMS_DIR = getShimsDir();
+/** Map a Codex Cloud status string to the canonical CloudTaskStatus enum. */
 function mapStatus(s) {
     const lower = s.toLowerCase();
     if (lower.includes('queued') || lower.includes('pending'))
@@ -18,6 +26,7 @@ function mapStatus(s) {
         return 'cancelled';
     return 'running';
 }
+/** Locate the codex binary, checking agents-cli shims first then PATH. */
 function findCodexBinary() {
     // Check agents-cli shims first
     const shim = path.join(SHIMS_DIR, 'codex');
@@ -31,9 +40,11 @@ function findCodexBinary() {
         return null;
     }
 }
+/** Check whether the codex CLI is installed and reachable. */
 function codexAvailable() {
     return findCodexBinary() !== null;
 }
+/** Spawn the codex CLI with the given arguments and capture its output. */
 function runCodex(args) {
     const bin = findCodexBinary();
     if (!bin)
@@ -49,6 +60,7 @@ function runCodex(args) {
         });
     });
 }
+/** Best-effort parse of codex CLI output into task fields (tries JSON, then key:value lines). */
 function parseTaskFromText(text) {
     // Codex cloud list/status output varies. Try JSON first, then parse text.
     try {
@@ -77,13 +89,37 @@ export class CodexCloudProvider {
     constructor(config) {
         this.defaultEnv = config?.env;
     }
-    supports(_options) {
-        return codexAvailable();
+    capabilities() {
+        const available = codexAvailable();
+        return {
+            available,
+            dispatch: available,
+            status: available,
+            list: available,
+            stream: available,
+            cancel: false,
+            message: false,
+            multiRepo: false,
+            skills: false,
+            images: false,
+        };
     }
     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 Error('Codex Cloud requires --env <id>. Set a default in ~/.agents-system/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
+        // almost always a misconfiguration: either the user meant to dispatch to
+        // Rush (which does support multi-repo), or they need to create/pick a
+        // Codex env that already contains those repos. Fail loudly rather than
+        // silently ignore the extras.
+        const repos = resolveDispatchRepos(options);
+        if (repos.length > 1) {
+            throw new Error(`Codex Cloud does not support multi-repo dispatch. Got ${repos.length} repos (${repos.join(', ')}). ` +
+                `Codex envs bundle repos at the env layer — either configure a Codex env that includes all of these repos, ` +
+                `or switch to --provider rush (which clones each repo into /workspace/<owner>/<name>/).`);
         }
         const args = ['cloud', 'exec', '--env', env];
         if (options.branch)
@@ -102,6 +138,8 @@ export class CodexCloudProvider {
             status: 'queued',
             agent: 'codex',
             prompt: options.prompt,
+            repo: repos[0],
+            repos: repos.length > 0 ? repos : undefined,
             branch: options.branch,
             createdAt: now,
             updatedAt: now,
@@ -164,11 +202,13 @@ export class CodexCloudProvider {
                 const task = await this.status(taskId);
                 if (task.status !== lastStatus) {
                     lastStatus = task.status;
-                    yield {
-                        type: terminalStatuses.has(task.status) ? 'done' : 'status',
-                        data: JSON.stringify({ status: task.status, summary: task.summary }),
-                        timestamp: new Date().toISOString(),
-                    };
+                    const ts = new Date().toISOString();
+                    if (terminalStatuses.has(task.status)) {
+                        yield { type: 'done', status: task.status, summary: task.summary, timestamp: ts };
+                    }
+                    else {
+                        yield { type: 'status', status: task.status, timestamp: ts };
+                    }
                 }
                 if (terminalStatuses.has(task.status))
                     break;
@@ -176,7 +216,7 @@ export class CodexCloudProvider {
             catch (err) {
                 yield {
                     type: 'error',
-                    data: err instanceof Error ? err.message : String(err),
+                    message: err instanceof Error ? err.message : String(err),
                     timestamp: new Date().toISOString(),
                 };
                 break;
@@ -193,6 +233,7 @@ export class CodexCloudProvider {
         throw new Error('Follow-up messages are not supported for Codex Cloud tasks.');
     }
 }
+/** Extract a task ID from codex CLI output (JSON field, key:value line, or UUID pattern). */
 function extractTaskId(output) {
     // Try JSON first
     try {
@@ -207,4 +248,3 @@ function extractTaskId(output) {
         return match?.[1];
     }
 }
-//# sourceMappingURL=codex.js.map

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

@@ -1,4 +1,10 @@
-import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions } from './types.js';
+/**
+ * Factory/Droid cloud provider -- stub for Phase 2.
+ *
+ * Will dispatch tasks to a `droid daemon` running on a remote machine.
+ * All methods throw until the droid daemon API is documented and stable.
+ */
+import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions, ProviderCapabilities } from './types.js';
 /**
  * Factory/Droid cloud provider — stub for Phase 2.
  *
@@ -13,7 +19,7 @@ import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOpt
 export declare class FactoryCloudProvider implements CloudProvider {
     id: "factory";
     name: string;
-    supports(_options: DispatchOptions): boolean;
+    capabilities(): ProviderCapabilities;
     dispatch(_options: DispatchOptions): Promise<CloudTask>;
     status(_taskId: string): Promise<CloudTask>;
     list(_filter?: {
@@ -23,4 +29,3 @@ export declare class FactoryCloudProvider implements CloudProvider {
     cancel(_taskId: string): Promise<void>;
     message(_taskId: string, _content: string): Promise<void>;
 }
-//# sourceMappingURL=factory.d.ts.map

package/dist/lib/cloud/factory.js

@@ -1,3 +1,9 @@
+/**
+ * Factory/Droid cloud provider -- stub for Phase 2.
+ *
+ * Will dispatch tasks to a `droid daemon` running on a remote machine.
+ * All methods throw until the droid daemon API is documented and stable.
+ */
 /**
  * Factory/Droid cloud provider — stub for Phase 2.
  *
@@ -12,8 +18,19 @@
 export class FactoryCloudProvider {
     id = 'factory';
     name = 'Factory (Droid)';
-    supports(_options) {
-        return false;
+    capabilities() {
+        return {
+            available: false,
+            dispatch: false,
+            status: false,
+            list: false,
+            stream: false,
+            cancel: false,
+            message: false,
+            multiRepo: false,
+            skills: false,
+            images: false,
+        };
     }
     async dispatch(_options) {
         throw new Error('Factory cloud provider is not yet available. Coming in a future release.');
@@ -34,4 +51,3 @@ export class FactoryCloudProvider {
         throw new Error('Factory cloud provider is not yet available.');
     }
 }
-//# sourceMappingURL=factory.js.map

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

@@ -1,6 +1,15 @@
+/**
+ * Cloud provider registry.
+ *
+ * Reads the `cloud` section of agents.yaml, lazily instantiates provider
+ * implementations, and exposes lookup helpers used by the `agents cloud` commands.
+ */
 import type { CloudProvider, CloudProviderId } from './types.js';
+/** 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;
-//# sourceMappingURL=registry.d.ts.map

package/dist/lib/cloud/registry.js

@@ -1,12 +1,19 @@
+/**
+ * Cloud provider registry.
+ *
+ * Reads the `cloud` section of agents.yaml, lazily instantiates provider
+ * implementations, and exposes lookup helpers used by the `agents cloud` commands.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
-import * as os from 'os';
 import * as yaml from 'yaml';
 import { RushCloudProvider } from './rush.js';
 import { CodexCloudProvider } from './codex.js';
 import { FactoryCloudProvider } from './factory.js';
-const META_FILE = path.join(os.homedir(), '.agents', 'agents.yaml');
+import { getAgentsDir } from '../state.js';
+const META_FILE = path.join(getAgentsDir(), 'agents.yaml');
 let _config = null;
+/** Parse the `cloud` section from agents.yaml, caching the result for the process lifetime. */
 function loadCloudConfig() {
     if (_config)
         return _config;
@@ -25,6 +32,7 @@ function loadCloudConfig() {
     return _config;
 }
 const providers = new Map();
+/** Instantiate all provider implementations once, keyed by their ID. */
 function initProviders() {
     if (providers.size > 0)
         return;
@@ -33,6 +41,7 @@ function initProviders() {
     providers.set('codex', new CodexCloudProvider(config.providers?.codex));
     providers.set('factory', new FactoryCloudProvider());
 }
+/** Look up a provider by ID, throwing if the ID is unknown. */
 export function getProvider(id) {
     initProviders();
     const provider = providers.get(id);
@@ -41,16 +50,18 @@ export function getProvider(id) {
     }
     return provider;
 }
+/** Return the user's configured default provider, falling back to 'rush'. */
 export function getDefaultProviderId() {
     const config = loadCloudConfig();
     return config.default_provider ?? 'rush';
 }
+/** Return every registered provider (used by `agents cloud providers`). */
 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());
     return getProvider(id);
 }
-//# sourceMappingURL=registry.js.map

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

@@ -1,8 +1,69 @@
-import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions } from './types.js';
+/**
+ * Rush Cloud provider -- dispatches tasks to the Factory Floor via api.prix.dev.
+ *
+ * Auth: reads the session token from ~/.rush/user.yaml (written by `rush login`).
+ * Requires the Rush GitHub App installed on the target repo.
+ */
+import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions, ProviderCapabilities } from './types.js';
+/** One version's entry in the account manifest sent on every dispatch. */
+export interface AccountManifestEntry {
+    version: string;
+    email: string;
+    cred_fp: string;
+}
+/**
+ * Manifest of the user's local Claude accounts. Sent on every dispatch so the
+ * server can detect "new account" or "token rotated" drift and ask the client
+ * to upload the underlying credentials. The manifest itself contains no
+ * secrets — only public-ish identifiers + a hash of each token.
+ */
+export interface AccountManifest {
+    fp: string;
+    versions: AccountManifestEntry[];
+}
+/** Token blob uploaded on retry when the server detects drift. */
+export interface AccountTokenEntry {
+    version: string;
+    /** Stringified OAuth credentials JSON (Mac: keychain blob; Linux: .credentials.json). */
+    credentials_json: string;
+}
+/**
+ * Build a manifest of the user's local Claude installations to send on every
+ * cloud dispatch. The manifest is the contract the server uses to detect when
+ * the user has added a new account or rotated a token.
+ *
+ * Returns null when no Claude versions are signed in (the dispatch falls back
+ * to the platform-wide key, current behavior).
+ */
+export declare function buildAccountManifest(): Promise<AccountManifest | null>;
+/**
+ * Re-load OAuth blobs for the given versions so they can be uploaded to the
+ * server on a retry. Only the versions named in the manifest are loaded — we
+ * never upload tokens for versions the server hasn't asked about.
+ */
+export declare function buildAccountTokensPayload(versions: string[]): Promise<AccountTokenEntry[]>;
+/**
+ * Build the POST body for /api/v1/cloud-runs. Exported so tests can verify
+ * the back-compat shape (singular fields + repos[]) without needing real
+ * GitHub installations or a live Rush session. `findInstallation` is the
+ * only other I/O and it's tested by the halo/proxy integration suite.
+ */
+export declare function buildDispatchBody(input: {
+    agent?: string;
+    prompt: string;
+    mode?: string;
+    resolvedRepos: Array<{
+        installation_id: number;
+        repo_owner: string;
+        repo_name: string;
+    }>;
+    accountManifest?: AccountManifest | null;
+    accountTokens?: AccountTokenEntry[] | null;
+}): Record<string, unknown>;
 export declare class RushCloudProvider implements CloudProvider {
     id: "rush";
     name: string;
-    supports(_options: DispatchOptions): boolean;
+    capabilities(): ProviderCapabilities;
     dispatch(options: DispatchOptions): Promise<CloudTask>;
     status(taskId: string): Promise<CloudTask>;
     list(filter?: {
@@ -12,4 +73,3 @@ export declare class RushCloudProvider implements CloudProvider {
     cancel(taskId: string): Promise<void>;
     message(taskId: string, content: string): Promise<void>;
 }
-//# sourceMappingURL=rush.d.ts.map