@phnx-labs/agents-cli 1.19.2 → 1.20.0

package/dist/lib/cli-resources.js

@@ -0,0 +1,255 @@
+/**
+ * CLI tool resources — declarative manifests for command-line binaries the user
+ * wants installed on the host (e.g. higgsfield, gh, glab).
+ *
+ * A CLI resource is a YAML file under <repo>/cli/<name>.yaml. Resolution follows
+ * the same project > user > system > extra-repo precedence as other resources,
+ * but unlike skills/commands/hooks, CLI resources are NOT copied into per-agent
+ * version homes — they install binaries onto the host PATH. The relationship is
+ * "Brewfile-style": declare once in ~/.agents/cli/, install on any new machine.
+ */
+import * as fs from 'fs';
+import { execSync, spawnSync } from 'child_process';
+import * as yaml from 'yaml';
+import { listResources, resolveResource } from './resources.js';
+// ─── Parsing ─────────────────────────────────────────────────────────────────
+/**
+ * Parse a single CLI manifest from its YAML contents.
+ * Returns a manifest on success; throws on schema violations so callers can
+ * decide whether to surface or swallow the error per file.
+ */
+export function parseCliManifest(contents, opts) {
+    const raw = yaml.parse(contents);
+    if (!raw || typeof raw !== 'object') {
+        throw new Error('manifest must be a YAML object');
+    }
+    const name = typeof raw.name === 'string' && raw.name.trim() ? raw.name.trim() : opts.name;
+    const description = typeof raw.description === 'string' ? raw.description : undefined;
+    const homepage = typeof raw.homepage === 'string' ? raw.homepage : undefined;
+    const check = typeof raw.check === 'string' && raw.check.trim()
+        ? raw.check.trim()
+        : `${name} --version`;
+    const postInstall = typeof raw.post_install === 'string' ? raw.post_install : undefined;
+    if (!Array.isArray(raw.install) || raw.install.length === 0) {
+        throw new Error('install must be a non-empty list of methods');
+    }
+    const install = raw.install.map((entry, i) => {
+        if (!entry || typeof entry !== 'object') {
+            throw new Error(`install[${i}] must be an object with one of: npm, brew, script, binary`);
+        }
+        const e = entry;
+        const keys = Object.keys(e).filter((k) => e[k] !== undefined && e[k] !== null);
+        if (keys.length !== 1) {
+            throw new Error(`install[${i}] must declare exactly one method (got: ${keys.join(', ') || 'none'})`);
+        }
+        const key = keys[0];
+        const value = e[key];
+        if (key === 'npm' || key === 'brew' || key === 'script') {
+            if (typeof value !== 'string' || !value.trim()) {
+                throw new Error(`install[${i}].${key} must be a non-empty string`);
+            }
+            return { [key]: value.trim() };
+        }
+        if (key === 'binary') {
+            if (!value || typeof value !== 'object') {
+                throw new Error(`install[${i}].binary must be a platform map`);
+            }
+            const binary = {};
+            for (const [platform, spec] of Object.entries(value)) {
+                if (!spec || typeof spec !== 'object') {
+                    throw new Error(`install[${i}].binary.${platform} must be an object with a url`);
+                }
+                const s = spec;
+                if (typeof s.url !== 'string' || !s.url.trim()) {
+                    throw new Error(`install[${i}].binary.${platform}.url must be a non-empty string`);
+                }
+                binary[platform] = {
+                    url: s.url.trim(),
+                    extract: typeof s.extract === 'string' ? s.extract : undefined,
+                };
+            }
+            return { binary };
+        }
+        throw new Error(`install[${i}] has unknown method "${key}" (expected: npm, brew, script, binary)`);
+    });
+    return {
+        name,
+        description,
+        homepage,
+        check,
+        install,
+        postInstall,
+        source: opts.source,
+        path: opts.path,
+    };
+}
+/**
+ * Discover all CLI manifests resolvable from the current cwd. Returns valid
+ * manifests and any parse errors separately so the CLI can show both.
+ */
+export function listCliManifests(cwd) {
+    const resolved = listResources('cli', cwd);
+    const manifests = [];
+    const errors = [];
+    for (const entry of resolved) {
+        if (!entry.path.endsWith('.yaml') && !entry.path.endsWith('.yml'))
+            continue;
+        try {
+            const contents = fs.readFileSync(entry.path, 'utf-8');
+            const manifest = parseCliManifest(contents, {
+                name: entry.name,
+                source: entry.source,
+                path: entry.path,
+            });
+            manifests.push(manifest);
+        }
+        catch (err) {
+            errors.push({ file: entry.path, reason: err.message });
+        }
+    }
+    return { manifests, errors };
+}
+/** Resolve a single CLI manifest by name. Returns null when not declared. */
+export function resolveCliManifest(name, cwd) {
+    const resolved = resolveResource('cli', name, cwd);
+    if (!resolved)
+        return null;
+    if (!resolved.path.endsWith('.yaml') && !resolved.path.endsWith('.yml'))
+        return null;
+    const contents = fs.readFileSync(resolved.path, 'utf-8');
+    return parseCliManifest(contents, {
+        name: resolved.name,
+        source: resolved.source,
+        path: resolved.path,
+    });
+}
+// ─── Host detection ──────────────────────────────────────────────────────────
+/**
+ * Return true if a command resolves on the current PATH. Uses `which` on
+ * POSIX hosts; results are cached for the lifetime of the process.
+ */
+const cmdExistsCache = new Map();
+export function hasCommand(cmd) {
+    if (cmdExistsCache.has(cmd))
+        return cmdExistsCache.get(cmd);
+    const result = spawnSync('command', ['-v', cmd], { shell: true, stdio: 'ignore' });
+    const ok = result.status === 0;
+    cmdExistsCache.set(cmd, ok);
+    return ok;
+}
+/** Run the manifest's `check` command. Returns true when it exits 0. */
+export function isCliInstalled(manifest) {
+    const result = spawnSync(manifest.check, {
+        shell: true,
+        stdio: 'ignore',
+        timeout: 10_000,
+    });
+    return result.status === 0;
+}
+// ─── Method selection ────────────────────────────────────────────────────────
+/**
+ * Pick the first install method whose required host tool is available.
+ * Returns null when none of the declared methods can run on this host.
+ */
+export function selectInstallMethod(manifest) {
+    for (const method of manifest.install) {
+        if ('npm' in method && hasCommand('npm'))
+            return method;
+        if ('brew' in method && hasCommand('brew'))
+            return method;
+        if ('script' in method && (hasCommand('curl') || hasCommand('wget')))
+            return method;
+        if ('binary' in method) {
+            const key = `${process.platform}-${process.arch}`;
+            if (method.binary[key])
+                return method;
+        }
+    }
+    return null;
+}
+/** Short description of a method for display. */
+export function describeMethod(method) {
+    if ('npm' in method)
+        return `npm install -g ${method.npm}`;
+    if ('brew' in method)
+        return `brew install ${method.brew}`;
+    if ('script' in method)
+        return `curl ${method.script} | sh`;
+    const key = `${process.platform}-${process.arch}`;
+    const spec = method.binary[key];
+    return spec ? `download ${spec.url}` : 'binary download';
+}
+/**
+ * Install a single CLI by running its first compatible method. Streams the
+ * underlying command's output to the parent terminal so users see brew/npm
+ * progress live. Verifies success by re-running `check`.
+ */
+export function installCli(manifest, opts = {}) {
+    const method = selectInstallMethod(manifest);
+    if (!method) {
+        return {
+            manifest,
+            method: null,
+            installed: false,
+            error: `No compatible install method for this host (${process.platform}-${process.arch}). Declared methods: ${manifest.install.map(describeMethod).join('; ')}`,
+        };
+    }
+    if (opts.dryRun) {
+        return { manifest, method, installed: false, output: `[dry-run] would run: ${describeMethod(method)}` };
+    }
+    const cmd = buildInstallCommand(method);
+    try {
+        execSync(cmd, { stdio: 'inherit' });
+    }
+    catch (err) {
+        return {
+            manifest,
+            method,
+            installed: false,
+            error: `install command failed: ${err.message}`,
+        };
+    }
+    // Re-check; many installers exit 0 but leave the binary off PATH for the
+    // current shell (e.g. brew on a fresh install). Trust `check`, not the
+    // installer's exit code.
+    cmdExistsCache.delete(manifest.name);
+    const installed = isCliInstalled(manifest);
+    return { manifest, method, installed };
+}
+/**
+ * Map a declarative method to a shell command. Centralized so tests and dry-run
+ * surface the exact string that would execute.
+ */
+export function buildInstallCommand(method) {
+    if ('npm' in method)
+        return `npm install -g ${method.npm}`;
+    if ('brew' in method)
+        return `brew install ${method.brew}`;
+    if ('script' in method) {
+        // Prefer curl when both are present; fall back to wget.
+        return hasCommand('curl')
+            ? `curl -fsSL ${method.script} | sh`
+            : `wget -qO- ${method.script} | sh`;
+    }
+    const key = `${process.platform}-${process.arch}`;
+    const spec = method.binary[key];
+    // The downloader is intentionally minimal — binary install is mostly used
+    // for pre-built tarballs whose extract path varies per project. We expect
+    // the manifest author to document any post-download steps in post_install.
+    return spec.extract
+        ? `curl -fsSL ${spec.url} -o /tmp/agents-cli-bin.tgz && tar -xzf /tmp/agents-cli-bin.tgz -C /usr/local/bin ${spec.extract}`
+        : `curl -fsSL ${spec.url} -o /usr/local/bin/agents-cli-downloaded`;
+}
+/** Convenience: list all manifests + their installed-on-host status. */
+export function listCliStatus(cwd) {
+    const { manifests, errors } = listCliManifests(cwd);
+    const statuses = manifests.map((manifest) => ({
+        manifest,
+        installed: isCliInstalled(manifest),
+    }));
+    return { statuses, errors };
+}
+/** Names of CLIs that are declared but not currently installed on the host. */
+export function getMissingClis(cwd) {
+    return listCliStatus(cwd).statuses.filter((s) => !s.installed).map((s) => s.manifest);
+}

package/dist/lib/cloud/rush.js

@@ -16,7 +16,7 @@ import { listInstalledVersions, getVersionHomePath } from '../versions.js';
 import { getAccountInfo } from '../agents.js';
 import { loadClaudeOauth } from '../usage.js';
 import { selectBalancedVersion } from '../rotate.js';
-const PROXY_BASE = 'https://api.prix.dev';
+const PROXY_BASE = process.env.RUSH_PROXY_BASE ?? 'https://api.prix.dev';
 const PROXY_HOST = new URL(PROXY_BASE).host;
 const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
 // Persistent consent record for uploading Claude OAuth blobs to Rush Cloud.
@@ -441,7 +441,7 @@ export class RushCloudProvider {
     }
     async status(taskId) {
         const token = readToken();
-        const res = await api('GET', `/api/v1/cloud-runs/${taskId}`, token);
+        const res = await api('GET', `/api/v1/cloud-runs/${encodeURIComponent(taskId)}`, token);
         if (!res.ok) {
             throw new Error(`Failed to get task status (${res.status}).`);
         }
@@ -487,7 +487,7 @@ export class RushCloudProvider {
     }
     async *stream(taskId) {
         const token = readToken();
-        const res = await fetch(`${PROXY_BASE}/api/v1/cloud-runs/${taskId}/stream`, {
+        const res = await fetch(`${PROXY_BASE}/api/v1/cloud-runs/${encodeURIComponent(taskId)}/stream`, {
             headers: { 'Authorization': `Bearer ${token}` },
         });
         if (!res.ok) {
@@ -497,14 +497,14 @@ export class RushCloudProvider {
     }
     async cancel(taskId) {
         const token = readToken();
-        const res = await api('DELETE', `/api/v1/cloud-runs/${taskId}`, token);
+        const res = await api('DELETE', `/api/v1/cloud-runs/${encodeURIComponent(taskId)}`, token);
         if (!res.ok) {
             throw new Error(`Failed to cancel task (${res.status}).`);
         }
     }
     async message(taskId, content) {
         const token = readToken();
-        const res = await api('POST', `/api/v1/cloud-runs/${taskId}/message`, token, { content });
+        const res = await api('POST', `/api/v1/cloud-runs/${encodeURIComponent(taskId)}/message`, token, { content });
         if (!res.ok) {
             throw new Error(`Failed to send message (${res.status}).`);
         }

package/dist/lib/command-skills.js

@@ -50,8 +50,6 @@ function readSkillCommandMarker(skillMdPath) {
     }
 }
 export function shouldInstallCommandAsSkill(agent, version) {
-    if (agent !== 'codex')
-        return false;
     return !supports(agent, 'commands', version).ok && supports(agent, 'skills', version).ok;
 }
 export function commandSkillName(commandName) {

package/dist/lib/computer-rpc.d.ts

@@ -15,6 +15,9 @@ export declare function resolveLogPath(): string;
 export declare function resolvePolicyPath(): string;
 export declare function loadComputerAllowList(): string[];
 export declare function writeComputerPolicy(allowedBundleIds: string[]): void;
+export declare function resolvePeersPath(): string;
+export declare function loadDefaultPeers(): string[];
+export declare function writeComputerPeers(allowedExecPaths: string[]): void;
 export declare function resolveHelperExec(): string | null;
 export declare function resolveHelperApp(): string | null;
 export declare function openComputerClient(): ComputerClient;

package/dist/lib/computer-rpc.js

@@ -110,6 +110,59 @@ export function writeComputerPolicy(allowedBundleIds) {
     const policy = { allow: allowedBundleIds };
     fs.writeFileSync(resolvePolicyPath(), JSON.stringify(policy, null, 2), { mode: 0o600 });
 }
+// Peer-auth (F5): the helper reads a list of executable paths it will
+// accept connections from. Anything else — `nc`, `/usr/bin/python3`, a
+// random electron app — gets the socket closed before its first RPC.
+// File mirrors computer-policy.json: JSON, mode 0600, missing/unparseable
+// means deny-everything.
+export function resolvePeersPath() {
+    return path.join(getHelpersDir(), 'computer-peers.json');
+}
+// Default peer set: this exact `agents` CLI binary plus Rush.app if it's
+// installed. realpath() the symlink chain so we record the on-disk path
+// the helper will see via proc_pidpath, not the shim path.
+//
+// Why path-based instead of codesign-team-id? The agents CLI is unsigned
+// today (npm distribution), and even if we sign Rush.app the team-id
+// check would need a separate roundtrip. Path is concrete and fast; the
+// daemon already runs as the user so anyone who can swap a binary at
+// these paths can do worse via other means.
+export function loadDefaultPeers() {
+    const out = new Set();
+    const add = (p) => {
+        try {
+            out.add(fs.realpathSync(p));
+        }
+        catch {
+            out.add(p);
+        }
+    };
+    // The Node executable currently running the CLI. This is what
+    // proc_pidpath() will report when the CLI calls into the daemon.
+    if (process.execPath)
+        add(process.execPath);
+    // Rush.app — the consumer Electron client. Both the helper-binary and
+    // the main app binary are possible callers depending on how Rush wires
+    // the RPC client.
+    const rushCandidates = [
+        '/Applications/Rush.app/Contents/MacOS/Rush',
+        '/Applications/Rush.app/Contents/MacOS/Electron',
+    ];
+    for (const p of rushCandidates) {
+        if (fs.existsSync(p))
+            add(p);
+    }
+    return [...out].sort();
+}
+// Write the peer-auth allow list. Same mode 0600 + atomic-ish semantics
+// as the policy file. The daemon picks it up at startup and on SIGHUP.
+export function writeComputerPeers(allowedExecPaths) {
+    const dir = getHelpersDir();
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(resolvePeersPath(), JSON.stringify({ allow: allowedExecPaths }, null, 2), { mode: 0o600 });
+}
 // Resolve the helper executable inside the dist .app bundle. Used by the
 // stdio fallback and by install-helper to find the source bundle.
 export function resolveHelperExec() {

package/dist/lib/daemon.js

@@ -14,6 +14,7 @@ import { getDaemonDir as getDaemonDirRoot } from './state.js';
 import { listJobs as listAllJobs } from './routines.js';
 import { JobScheduler } from './scheduler.js';
 import { executeJobDetached, monitorRunningJobs } from './runner.js';
+import { detectOverdueJobs, notifyOverdue } from './overdue.js';
 import { BrowserService } from './browser/service.js';
 import { BrowserIPCServer } from './browser/ipc.js';
 const PID_FILE = 'daemon.pid';
@@ -178,6 +179,25 @@ export async function runDaemon() {
     for (const job of scheduled) {
         log('INFO', `  ${job.name} -> next: ${job.nextRun?.toISOString() || 'unknown'}`);
     }
+    // Backlog detection: any enabled recurring job whose most-recent expected
+    // fire is older than its most-recent recorded run is overdue. Happens when
+    // the laptop was off or the daemon crashed through a scheduled fire.
+    // We log it and pop a native notification — the user can review with
+    // `agents routines list` and run them with `agents routines catchup`.
+    try {
+        const overdue = detectOverdueJobs();
+        if (overdue.length > 0) {
+            log('WARN', `${overdue.length} routine(s) overdue:`);
+            for (const job of overdue) {
+                const last = job.lastRanAt ? job.lastRanAt.toISOString() : 'never';
+                log('WARN', `  ${job.name} -- expected ${job.expectedAt.toISOString()}, last ran ${last}`);
+            }
+            notifyOverdue(overdue);
+        }
+    }
+    catch (err) {
+        log('ERROR', `Overdue detection failed: ${err.message}`);
+    }
     // Before the BrowserService comes up, reap browser + tunnel processes
     // spawned by previous daemons that are no longer alive. Without this,
     // a daemon hard-crash (SIGKILL, OOM) would leak every browser and SSH

package/dist/lib/exec.d.ts

@@ -27,8 +27,9 @@ export interface ExecOptions {
 export declare function parseExecEnv(entries: string[]): Record<string, string> | undefined;
 /**
  * Build the process environment for an agent invocation.
- * Pins CLAUDE_CONFIG_DIR for Claude and CODEX_HOME for Codex; strips the
- * other agent's env var so it doesn't leak into unrelated invocations.
+ * Pins CLAUDE_CONFIG_DIR for Claude, CODEX_HOME for Codex, and COPILOT_HOME
+ * for GitHub Copilot; strips the other agents' env vars so they don't leak
+ * into unrelated invocations.
  */
 export declare function buildExecEnv(options: ExecOptions): NodeJS.ProcessEnv;
 /** Describes how to translate ExecOptions into CLI arguments for a specific agent. */

package/dist/lib/exec.js

@@ -35,8 +35,9 @@ export function parseExecEnv(entries) {
 }
 /**
  * Build the process environment for an agent invocation.
- * Pins CLAUDE_CONFIG_DIR for Claude and CODEX_HOME for Codex; strips the
- * other agent's env var so it doesn't leak into unrelated invocations.
+ * Pins CLAUDE_CONFIG_DIR for Claude, CODEX_HOME for Codex, and COPILOT_HOME
+ * for GitHub Copilot; strips the other agents' env vars so they don't leak
+ * into unrelated invocations.
  */
 export function buildExecEnv(options) {
     const result = { ...process.env };
@@ -56,6 +57,7 @@ export function buildExecEnv(options) {
             result.CLAUDE_CONFIG_DIR = path.join(getVersionHomePath('claude', version), '.claude');
         }
         delete result.CODEX_HOME;
+        delete result.COPILOT_HOME;
     }
     else if (options.agent === 'codex') {
         const cwd = options.cwd || process.cwd();
@@ -67,10 +69,27 @@ export function buildExecEnv(options) {
             result.CODEX_HOME = path.join(getVersionHomePath('codex', version), '.codex');
         }
         delete result.CLAUDE_CONFIG_DIR;
+        delete result.COPILOT_HOME;
+    }
+    else if (options.agent === 'copilot') {
+        // Copilot honors COPILOT_HOME (relocates ~/.copilot, including settings,
+        // mcp-config.json, sessions, logs). Pin it at the per-version home so
+        // version switches isolate MCP servers, auth, and session history.
+        const cwd = options.cwd || process.cwd();
+        const resolvedVersion = options.version ?? resolveVersion('copilot', cwd);
+        const version = options.version
+            ? resolvedVersion
+            : (resolvedVersion && isVersionInstalled('copilot', resolvedVersion) ? resolvedVersion : null);
+        if (version) {
+            result.COPILOT_HOME = path.join(getVersionHomePath('copilot', version), '.copilot');
+        }
+        delete result.CLAUDE_CONFIG_DIR;
+        delete result.CODEX_HOME;
     }
     else {
         delete result.CLAUDE_CONFIG_DIR;
         delete result.CODEX_HOME;
+        delete result.COPILOT_HOME;
     }
     return {
         ...result,
@@ -148,14 +167,25 @@ export const AGENT_COMMANDS = {
         jsonFlags: ['--output-format', 'stream-json'],
         modelFlag: '--model',
     },
+    // GitHub Copilot CLI (`@github/copilot`, GA 2026-02-25). Flags verified
+    // against `copilot --help` from v0.0.413+:
+    //   -p, --prompt <text>          non-interactive one-shot
+    //   --mode <interactive|plan|autopilot>
+    //   --allow-all-tools            required for non-interactive tool exec
+    //   --allow-all (alias --yolo)   tools + paths + URLs
+    //   --output-format <text|json>  json => JSONL, one object per line
+    //   --model <model>
+    // Plan mode is read-only so it does not need an allow-tools grant; edit/full
+    // need at minimum --allow-all-tools so headless runs don't stall on prompts.
     copilot: {
         base: ['copilot'],
-        promptFlag: 'positional',
+        promptFlag: '-p',
         modeFlags: {
-            plan: [],
-            edit: [],
-            full: [],
+            plan: ['--mode', 'plan'],
+            edit: ['--allow-all-tools'],
+            full: ['--allow-all'],
         },
+        jsonFlags: ['--output-format', 'json'],
         modelFlag: '--model',
     },
     amp: {
@@ -197,13 +227,18 @@ export const AGENT_COMMANDS = {
         },
         modelFlag: '--model',
     },
+    // Antigravity full mode uses --dangerously-skip-permissions (YOLO).
+    // TODO: --output-format json is documented but currently broken upstream
+    // ("flags provided but not defined: -output-format"). Track resolution at
+    // https://github.com/google-antigravity/antigravity-cli/issues/7 before
+    // adding `jsonFlags` here.
     antigravity: {
         base: ['agy'],
         promptFlag: 'positional',
         modeFlags: {
             plan: [],
             edit: [],
-            full: [],
+            full: ['--dangerously-skip-permissions'],
         },
         modelFlag: '--model',
     },
@@ -211,9 +246,9 @@ export const AGENT_COMMANDS = {
         base: ['grok'],
         promptFlag: '-p',
         modeFlags: {
-            plan: [],
+            plan: ['--mode', 'plan'],
             edit: [],
-            full: [],
+            full: ['--always-approve'],
         },
         jsonFlags: ['--output-format', 'streaming-json'],
         modelFlag: '--model',