@phnx-labs/agents-cli 1.20.64 → 1.20.66

package/dist/commands/apply.js

@@ -0,0 +1,274 @@
+/**
+ * `agents apply` (alias `ag apply`) — reconcile the whole fleet to a declared
+ * profile in one command: install agents-cli + agents, sync config, and
+ * propagate login so a machine that's signed in once seeds every device. Kills
+ * the "6 hosts x ~8 harnesses = ~48 OAuth flows" slog.
+ *
+ * The manifest is the `fleet:` block of any `-f` file (default `agents.yaml`).
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { Option } from 'commander';
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { machineId } from '../lib/session/sync/config.js';
+import { loadDevices, isControlDevice } from '../lib/devices/registry.js';
+import { readFleetFile, resolveDesired } from '../lib/fleet/manifest.js';
+import { snapshotAuth, materializeAuth, parseAuthBundle, KEYCHAIN_BOUND_ON_MAC } from '../lib/fleet/auth-sync.js';
+import { agentIdOf, diffFleet, probeDevice, runFleetApply, pool, sourceHome, } from '../lib/fleet/apply.js';
+/** Version of the running agents-cli — the fleet target version. */
+function localCliVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(fs.readFileSync(path.join(here, '..', '..', 'package.json'), 'utf-8'));
+        return String(pkg.version ?? '');
+    }
+    catch {
+        return '';
+    }
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const c of process.stdin)
+        chunks.push(c);
+    return Buffer.concat(chunks).toString('utf-8');
+}
+/** Hidden path: receive an auth bundle on stdin and materialize it locally. */
+async function runRecvAuth() {
+    const raw = await readStdin();
+    const bundle = parseAuthBundle(raw);
+    const res = materializeAuth(bundle, { home: os.homedir() });
+    if (res.errors.length > 0) {
+        console.error(`recv-auth: ${res.errors.length} error(s): ${res.errors.join('; ')}`);
+        process.exit(1);
+    }
+    console.log(`recv-auth: wrote login for ${res.written.join(', ') || '(nothing)'}`);
+}
+function confirm(question) {
+    return new Promise((resolve) => {
+        process.stdout.write(question);
+        const onData = (d) => {
+            process.stdin.pause();
+            process.stdin.off('data', onData);
+            resolve(/^y(es)?$/i.test(d.toString().trim()));
+        };
+        process.stdin.resume();
+        process.stdin.once('data', onData);
+    });
+}
+const ONLY_KINDS = {
+    agents: new Set(['install-cli', 'upgrade-cli', 'add-agent']),
+    config: new Set(['sync-config']),
+    login: new Set(['push-login', 'needs-login']),
+};
+/** Render the device x dimension matrix (cribbed from `doctor --devices`). */
+function renderPlan(plan) {
+    const rows = plan.devices;
+    const nameWidth = Math.max('device'.length, ...rows.map((r) => r.device.length));
+    const cell = (row, kinds, okLabel) => {
+        if (!row.probe.reachable)
+            return chalk.gray('- offline');
+        const acts = row.actions.filter((a) => kinds.includes(a.kind));
+        if (acts.length === 0)
+            return chalk.green(`ok ${okLabel}`);
+        if (acts.some((a) => a.kind === 'needs-login')) {
+            const push = acts.filter((a) => a.kind === 'push-login').length;
+            const need = acts.filter((a) => a.kind === 'needs-login').length;
+            return chalk.yellow(`${push} push · ${need} manual`);
+        }
+        return chalk.cyan('↑ ' + acts.map((a) => a.agent ?? a.kind.replace('-cli', '')).join(','));
+    };
+    const header = `  ${'device'.padEnd(nameWidth)}   ${'agents-cli'.padEnd(12)}${'agents'.padEnd(20)}${'config'.padEnd(10)}login`;
+    console.log(chalk.gray(header));
+    for (const row of rows) {
+        const cli = row.probe.reachable
+            ? (row.actions.find((a) => a.kind === 'install-cli') ? chalk.cyan('install')
+                : row.actions.find((a) => a.kind === 'upgrade-cli') ? chalk.cyan('upgrade')
+                    : chalk.green(`ok ${row.probe.cliVersion ?? ''}`))
+            : chalk.gray('- offline');
+        const agentsCell = row.probe.reachable
+            ? (() => {
+                const add = row.actions.filter((a) => a.kind === 'add-agent');
+                return add.length === 0 ? chalk.green(`ok ${row.desired.agents.length}/${row.desired.agents.length}`) : chalk.cyan('+ ' + add.map((a) => a.agent).join(','));
+            })()
+            : chalk.gray('-');
+        const configCell = row.probe.reachable
+            ? (row.actions.some((a) => a.kind === 'sync-config') ? chalk.cyan('↑ sync') : chalk.green('ok'))
+            : chalk.gray('-');
+        const loginCell = cell(row, ['push-login', 'needs-login'], `${row.desired.agents.length}/${row.desired.agents.length}`);
+        console.log(`  ${row.device.padEnd(nameWidth)}   ${stripPad(cli, 12)}${stripPad(agentsCell, 20)}${stripPad(configCell, 10)}${loginCell}`);
+    }
+    console.log();
+    console.log(chalk.gray(`  ${plan.actions.length} action(s) across ${rows.filter((r) => r.probe.reachable).length} reachable device(s)`));
+    // Distinguish *why* a login can't be propagated: a macOS keychain-bound token
+    // vs. the source simply not being signed in to that agent (no portable file).
+    const bound = [];
+    const noToken = [];
+    for (const r of rows) {
+        for (const a of r.loginBlocked) {
+            const tag = `${a}@${r.device}`;
+            if (r.probe.platform === 'macos' && KEYCHAIN_BOUND_ON_MAC.has(a))
+                bound.push(tag);
+            else
+                noToken.push(tag);
+        }
+    }
+    if (bound.length > 0) {
+        console.log(chalk.yellow(`  manual login needed (macOS keychain-bound): ${bound.join(', ')}`));
+    }
+    if (noToken.length > 0) {
+        console.log(chalk.yellow(`  manual login needed (no portable token on source): ${noToken.join(', ')}`));
+    }
+}
+/** padEnd on the visible width, ignoring chalk color codes. Exported for tests. */
+export function stripPad(s, width) {
+    // Strip the whole SGR sequence (ESC `[` ... `m`). Matching only the `[...m`
+    // tail leaves each leading ESC byte counted as visible, so every colored
+    // cell over-pads and the plan table misaligns in a real TTY.
+    // eslint-disable-next-line no-control-regex
+    const visible = s.replace(/\x1b\[[0-9;]*m/g, '').length;
+    return s + ' '.repeat(Math.max(1, width - visible));
+}
+async function runApply(opts) {
+    const file = opts.file ?? 'agents.yaml';
+    const manifest = readFleetFile(path.resolve(file));
+    const source = machineId();
+    const registry = await loadDevices();
+    // Control devices (a cockpit) never run agents — exclude them from the
+    // reconcile set entirely so `agents apply` doesn't try to install/sync/login
+    // onto a paired phone.
+    const all = Object.values(registry).filter((d) => !isControlDevice(d));
+    const online = all.filter((d) => d.tailscale?.online === true).map((d) => d.name);
+    const registered = all.map((d) => d.name);
+    let desired = resolveDesired(manifest, { onlineDevices: online, registeredDevices: registered, source });
+    if (opts.device) {
+        desired = desired.filter((d) => d.device === opts.device);
+        if (desired.length === 0)
+            throw new Error(`Device '${opts.device}' is not a target in this manifest.`);
+    }
+    if (opts.login === false)
+        desired = desired.map((d) => ({ ...d, login: 'skip' }));
+    if (desired.length === 0) {
+        console.log(chalk.gray('No target devices — nothing to apply.'));
+        return;
+    }
+    // Snapshot source auth once for every agent named anywhere in the profile.
+    const allAgents = [...new Set(desired.flatMap((d) => d.agents.map(agentIdOf)))];
+    const snap = snapshotAuth(allAgents, { home: sourceHome(), platform: process.platform });
+    const filesByAgent = new Map();
+    for (const f of snap.files) {
+        const arr = filesByAgent.get(f.agent) ?? [];
+        arr.push(f);
+        filesByAgent.set(f.agent, arr);
+    }
+    const sourceAuth = {
+        available: new Set(snap.files.map((f) => f.agent)),
+        bound: new Set(snap.bound),
+        filesByAgent,
+    };
+    // Probe every target device in parallel.
+    const nameToProfile = new Map(desired.map((d) => [d.device, registry[d.device]]));
+    console.log(chalk.gray(`Probing ${desired.length} device(s)…`));
+    const probeList = await pool(desired, 6, async (d) => probeDevice(nameToProfile.get(d.device)));
+    const probes = new Map(probeList.map((p) => [p.device, p]));
+    const targetCliVersion = localCliVersion();
+    let plan = diffFleet(desired, probes, { targetCliVersion, sourceAuth });
+    // --only filter.
+    if (opts.only) {
+        const keep = new Set();
+        for (const k of opts.only.split(',').map((s) => s.trim()))
+            for (const x of ONLY_KINDS[k] ?? [])
+                keep.add(x);
+        plan = {
+            devices: plan.devices.map((r) => ({ ...r, actions: r.actions.filter((a) => keep.has(a.kind)) })),
+            actions: plan.actions.filter((a) => keep.has(a.kind)),
+        };
+    }
+    console.log();
+    console.log(chalk.bold(`Fleet profile · ${desired.length} device(s) · ${allAgents.length} agent(s) (${allAgents.join(', ')})`));
+    renderPlan(plan);
+    const isDry = opts.plan || opts.dryRun;
+    if (isDry)
+        return;
+    if (plan.actions.filter((a) => a.kind !== 'needs-login').length === 0) {
+        console.log(chalk.green('\nNothing to do — fleet already matches the profile.'));
+        return;
+    }
+    if (!opts.yes) {
+        const ok = await confirm(chalk.bold(`\nApply this plan? (${plan.actions.length} action(s)) [y/N] `));
+        if (!ok) {
+            console.log(chalk.gray('Aborted.'));
+            return;
+        }
+    }
+    console.log();
+    const results = await runFleetApply(plan.devices, nameToProfile, {
+        targetCliVersion,
+        source,
+        sourceAuth,
+    });
+    reportResults(results);
+}
+function reportResults(results) {
+    let failures = 0;
+    for (const r of results) {
+        if (r.note && r.steps.length === 0) {
+            console.log(`  ${chalk.gray(r.device.padEnd(16))} ${chalk.yellow('skipped')} ${chalk.gray(r.note)}`);
+            continue;
+        }
+        const badge = r.ok ? chalk.green('ok  ') : chalk.red('fail');
+        if (!r.ok)
+            failures++;
+        const summary = r.steps.map((s) => `${s.ok ? '✓' : '✗'} ${s.kind}`).join('  ');
+        console.log(`  ${chalk.bold(r.device.padEnd(16))} ${badge}  ${chalk.gray(summary)}`);
+        for (const s of r.steps.filter((x) => x.kind === 'needs-login')) {
+            console.log(`      ${chalk.yellow('→')} ${chalk.gray(s.detail)}`);
+        }
+    }
+    console.log();
+    if (failures > 0) {
+        console.error(chalk.red(`${failures} device(s) had failures.`));
+        process.exit(1);
+    }
+    console.log(chalk.green('Fleet reconciled.'));
+}
+export function registerApplyCommand(program) {
+    const applyCmd = program
+        .command('apply')
+        .description('Reconcile the fleet to a declared profile: install agents, sync config, propagate login.')
+        .option('-f, --file <path>', 'Manifest file carrying a fleet: block (default: agents.yaml)')
+        .option('--plan', 'Show the reconcile plan and exit (no changes)')
+        .option('--dry-run', 'Alias for --plan')
+        .option('-y, --yes', 'Skip the confirmation prompt')
+        .option('--device <name>', 'Scope the apply to a single device')
+        .option('--only <dims>', 'Limit to dimensions: comma list of agents,config,login')
+        .option('--no-login', 'Do not propagate logins')
+        .addOption(new Option('--recv-auth', 'internal: receive an auth bundle on stdin').hideHelp())
+        .action(async (opts) => {
+        try {
+            if (opts.recvAuth) {
+                await runRecvAuth();
+                return;
+            }
+            await runApply(opts);
+        }
+        catch (e) {
+            console.error(chalk.red(e.message));
+            process.exit(1);
+        }
+    });
+    setHelpSections(applyCmd, {
+        examples: `
+      # Preview what would change across the fleet
+      agents apply --plan -f agents.yaml
+
+      # Bring every device to the profile (installs, syncs, propagates login)
+      ag apply -f agents.yaml
+
+      # One device only
+      agents apply --device yosemite-s1 -y
+    `,
+    });
+}

package/dist/commands/browser.js

@@ -4,7 +4,7 @@ import { listProfiles, getProfile, createProfile, deleteProfile, ensureDefaultBr
 import { updateMeta } from '../lib/state.js';
 import { loginsForProfile, profilesLoggedInto, serviceForUrl, loginsWithAccountsForProfile, accountsForProfile, credKeysForService, AUTH_SIGNATURES, } from '../lib/browser/login-detection.js';
 import { parseSecretRef } from '../lib/browser/secret-ref.js';
-import { readAndResolveBundleEnv, bundleExists, readBundle, describeBundle } from '../lib/secrets/bundles.js';
+import { readAndResolveBundleEnv, isHeadlessSecretsContext, bundleExists, readBundle, describeBundle } from '../lib/secrets/bundles.js';
 import { findBrowserPath, getPortOccupant, isLauncherScript } from '../lib/browser/chrome.js';
 import { listProfileCacheDirs, removeProfileCache, listAllProfileSnapshots, } from '../lib/browser/runtime-state.js';
 import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
@@ -1420,7 +1420,7 @@ function registerTaskCommands(browser) {
                 process.exit(1);
             }
             try {
-                const { env } = readAndResolveBundleEnv(parsed.bundle, { caller: 'browser type', keys: [parsed.key] });
+                const { env } = readAndResolveBundleEnv(parsed.bundle, { caller: 'browser type', keys: [parsed.key], agentOnly: isHeadlessSecretsContext() });
                 if (!(parsed.key in env)) {
                     console.error(`Key "${parsed.key}" not in bundle "${parsed.bundle}".`);
                     process.exit(1);

package/dist/commands/cloud.js

@@ -8,6 +8,7 @@ import { insertTask, updateTaskStatus, getTaskById, listTasks as listStoredTasks
 import { renderStream } from '../lib/cloud/stream.js';
 import { MissingTargetError, MAX_IMAGES_PER_DISPATCH } from '../lib/cloud/types.js';
 import { normalizeTriggerEvent, validateTrigger, writeJob, jobExists, GITHUB_TRIGGER_EVENTS } from '../lib/routines.js';
+import { machineId } from '../lib/machine-id.js';
 import { emit } from '../lib/events.js';
 /** Map a supported image file extension to its wire mimeType. Rejects anything else. */
 function imageMimeFromPath(file) {
@@ -145,7 +146,7 @@ Examples:
     cloud
         .command('run [prompt]')
         .description('Dispatch a task to a cloud agent.')
-        .option('--provider <id>', 'Cloud backend: rush, codex, factory, antigravity (overrides agent auto-routing)')
+        .option('--provider <id>', 'Cloud backend: rush, codex, factory, antigravity, host (overrides agent auto-routing)')
         .option('--agent <name>', 'Agent to run: claude, codex, droid, antigravity (auto-routes to its native cloud)')
         .option('--repo <owner/repo>', 'GitHub repository. Repeatable for multi-repo dispatch (Rush Cloud only).', (value, previous) => {
         const acc = Array.isArray(previous) ? previous : [];
@@ -160,6 +161,9 @@ Examples:
         .option('--model <model>', 'Model override')
         .option('--env <id>', 'Codex Cloud environment ID')
         .option('--computer <name>', 'Factory/Droid computer target')
+        .option('--host <name>', 'One of your machines as the target (a registered host, device, capability tag, or user@host). Implies --provider host.')
+        .option('--remote-cwd <dir>', 'Working directory on the host (--provider host only)')
+        .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match')
         .option('--autonomy <level>', 'Factory/Droid autonomy: low, medium, high (default high)')
         .option('--mode <mode>', 'Execution mode (e.g., plan, edit, full)')
         .option('--image <path>', `Attach an image (.png/.jpg/.webp) for vision dispatch. Repeatable, up to ${MAX_IMAGES_PER_DISPATCH} (Rush Cloud only).`, (value, previous) => {
@@ -189,6 +193,10 @@ Examples:
   # Codex Cloud
   agents cloud run "add auth tests" --provider codex --env env_abc123
 
+  # One of your own machines (agents hosts / agents devices), over SSH
+  agents cloud run "run the nightly benchmark" --host gpu-box --agent claude
+  agents cloud run "rebuild the index" --host gpu --any --remote-cwd ~/proj
+
   # Default provider (set in ~/.agents/agents.yaml)
   agents cloud run "refactor auth module" --repo user/repo
 `)
@@ -208,9 +216,16 @@ Examples:
                 process.stderr.write(chalk.dim(`Reading prompt from ${filePath} (${sizeKB} KB)\n`));
             }
         }
+        // --host names one of YOUR machines as the target — that only means
+        // something to the host provider, so it implies --provider host rather
+        // than silently riding along to a cloud backend that would ignore it.
+        if (options.host && options.provider && options.provider !== 'host') {
+            die(`--host targets your own machines (--provider host), not ${options.provider}. Drop --host, or use --provider host.`);
+        }
+        const explicitProvider = options.provider ?? (options.host ? 'host' : undefined);
         // Agent-aware: with no --provider, the agent routes to its native cloud
         // (claude→rush, codex→codex, droid→factory, antigravity→antigravity).
-        const provider = resolveProvider(options.provider, options.agent);
+        const provider = resolveProvider(explicitProvider, options.agent);
         // --repo is repeatable: commander gives us an array via our collector.
         // A single --repo value arrives as a one-element array; keep the legacy
         // singular `repo` field in sync so providers that only know that field
@@ -234,6 +249,12 @@ Examples:
             dispatchOptions.providerOptions.env = options.env;
         if (options.computer)
             dispatchOptions.providerOptions.computer = options.computer;
+        if (options.host)
+            dispatchOptions.providerOptions.host = options.host;
+        if (options.remoteCwd)
+            dispatchOptions.providerOptions.remoteCwd = options.remoteCwd;
+        if (options.any)
+            dispatchOptions.providerOptions.any = true;
         if (options.autonomy)
             dispatchOptions.providerOptions.autonomy = options.autonomy;
         if (options.mode)
@@ -279,6 +300,15 @@ Examples:
             };
             if (repoValues[0])
                 routine.repo = repoValues[0];
+            // --host with --on: the webhook-fired run places on that machine (the
+            // routine carries the placement, and firing pins to THIS device so a
+            // fleet of receivers can't each dispatch a duplicate).
+            if (options.host) {
+                routine.host = options.host;
+                if (options.remoteCwd)
+                    routine.remoteCwd = options.remoteCwd;
+                routine.devices = [machineId()];
+            }
             writeJob(routine);
             if (json) {
                 console.log(JSON.stringify({ ok: true, registered: routineName, trigger }, null, 2));

package/dist/commands/doctor.js

@@ -1,6 +1,6 @@
 import { addHostOption } from '../lib/hosts/option.js';
 import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
-import { loadDevices } from '../lib/devices/registry.js';
+import { loadDevices, isControlDevice } from '../lib/devices/registry.js';
 import { resolveHost } from '../lib/hosts/registry.js';
 import { sshExec } from '../lib/ssh-exec.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
@@ -249,6 +249,9 @@ async function resolveFleetTargets(opts) {
     const localName = machineId();
     return Object.values(registry)
         .filter((d) => d.name.toLowerCase() !== localName)
+        // Control devices (a cockpit) never run agents — skip them in the fleet
+        // fan-out (an explicit --device <name> still resolves above).
+        .filter((d) => !isControlDevice(d))
         .map((d) => ({
         name: d.name,
         sshTarget: d.name,

package/dist/commands/exec.d.ts

@@ -7,6 +7,54 @@
  */
 import { type Command } from 'commander';
 import type { ExecEffort } from '../lib/exec.js';
+import { type SshGResult } from '../lib/hosts/ssh-config.js';
+/** The host descriptor fields the `--copy-creds` security gate reads. */
+export interface CopyCredsGateHost {
+    name: string;
+    /** Concrete SSH target for inline/provider hosts; unset for ssh-config aliases. */
+    address?: string;
+    /** `devices` = registered Tailscale fleet host; `local` = ssh-config/inline. */
+    provider?: string;
+}
+/** Outcome of the `--copy-creds` security gate (RUSH-1767). */
+export interface CopyCredsGateDecision {
+    /** Ship credentials? True only when the host key is pinned in the managed store. */
+    allowed: boolean;
+    /** The address whose key is checked/pinned — an ssh-config alias resolved to its real HostName. */
+    pinTarget: string;
+    /** True when the non-device self-pin path pinned the target during this call. */
+    selfPinned: boolean;
+}
+/** Injectable network seams so the gate decision is testable without ssh/keyscan. */
+export interface CopyCredsGateDeps {
+    /** Managed known_hosts store file (defaults to the real cache path). */
+    file?: string;
+    /** Resolve an ssh-config alias to its effective HostName/Port (defaults to real `ssh -G`). */
+    resolve?: (name: string) => SshGResult | undefined;
+    /** Self-pin `target` via ssh-keyscan; returns whether it's pinned afterward (defaults to real `pinHostKey`). */
+    selfPin?: (target: string, port: number | undefined, file: string) => boolean;
+}
+/**
+ * Decide whether `--copy-creds` may ship credentials (and the Claude OAuth
+ * token) to `host` (RUSH-1767). Credentials ship only to a host whose SSH host
+ * key is pinned in the managed known_hosts store, so the offload never rides an
+ * accept-new (TOFU) connection a machine-in-the-middle could intercept.
+ *
+ * Resolution:
+ *  - The checked target is the host's concrete `address`, else its ssh-config
+ *    HostName (`ssh -G`), else its name — so an alias is pinned/verified against
+ *    the SAME real host the strict dispatch later connects to.
+ *  - An unpinned NON-device (a bare `~/.ssh/config` `Host` alias or literal,
+ *    which `agents ssh <name>` can't reach — "Unknown device") is self-pinned in
+ *    place via ssh-keyscan. A registered device is left unpinned here — it earns
+ *    its pin through the normal `agents ssh <name>` accept-new connect, so the
+ *    caller steers there instead.
+ *
+ * The network seams (`resolve`, `selfPin`) default to the real ssh -G /
+ * ssh-keyscan implementations and are injectable so the ship/refuse decision is
+ * unit-testable against real known_hosts fixtures with no network.
+ */
+export declare function decideCopyCredsGate(host: CopyCredsGateHost, deps?: CopyCredsGateDeps): CopyCredsGateDecision;
 /**
  * Build the LoopConfig the driver consumes from CLI flags and/or a workflow's
  * `loop:` frontmatter block (issue #332). Returns undefined when neither source