@phnx-labs/agents-cli 1.20.63 → 1.20.65

package/dist/lib/exec.js

@@ -147,12 +147,13 @@ export function resolveInteractive(options) {
  * @param piped        true when the parent's stdout is NOT a TTY (output piped)
  * @param capsActive   true when a budget watcher is attached (caps configured)
  */
-export function shouldTapStdout(interactive, piped, capsActive) {
+export function shouldTapStdout(interactive, piped, capsActive, captureTail = false) {
     if (interactive)
         return false;
     // Always pipe when the caller pipes us downstream (preserve composability),
-    // OR when caps are active so the watcher can read the stream at a TTY.
-    return piped || capsActive;
+    // when caps are active so the watcher can read the stream at a TTY, or when
+    // a fallback chain needs a stdout tail for rate-limit detection.
+    return piped || capsActive || captureTail;
 }
 /** Pattern for valid environment variable names (C identifier rules). */
 const EXEC_ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -866,11 +867,17 @@ export function shouldWrapInTmux(ctx) {
  *     `#{pane_pid}`, clean signal delivery on detach/kill).
  * Keys are filtered to valid identifiers so exported shell functions
  * (`BASH_FUNC_*%%`) can't make `env` choke.
+ *
+ * `redactEnvValues` replaces every value with a `<redacted>` marker while keeping
+ * the KEY names. The env map here carries resolved secrets bundles (options.env),
+ * so the real string would embed secret VALUES — which get persisted verbatim
+ * into SessionMeta.cmd on disk (tmux/session.ts). The launched command uses the
+ * real values; the stored/informational copy uses the redacted form (RUSH-1758).
  */
-export function buildTmuxAgentCommand(executable, args, env) {
+export function buildTmuxAgentCommand(executable, args, env, opts = {}) {
     const envPrefix = Object.entries(env)
         .filter(([k, v]) => v !== undefined && EXEC_ENV_KEY_PATTERN.test(k))
-        .map(([k, v]) => `${k}=${shellQuote(String(v))}`)
+        .map(([k, v]) => `${k}=${opts.redactEnvValues ? '<redacted>' : shellQuote(String(v))}`)
         .join(' ');
     const agentCmd = [executable, ...args].map(shellQuote).join(' ');
     return `exec env ${envPrefix} ${agentCmd}`;
@@ -917,11 +924,16 @@ async function runInTmux(options, executable, args) {
     const cwd = options.cwd || process.cwd();
     const idSeed = (options.sessionId ?? randomUUID()).slice(0, 8);
     const name = slugifyName(`ag-${options.agent}-${idSeed}`);
-    const cmd = buildTmuxAgentCommand(executable, args, buildExecEnv(options));
+    const execEnv = buildExecEnv(options);
+    // Launch with the real env (secret VALUES materialized into the pane); persist
+    // only a value-redacted copy in SessionMeta.cmd so resolved secrets never hit
+    // disk via the informational cmd field (RUSH-1758).
+    const cmd = buildTmuxAgentCommand(executable, args, execEnv);
+    const metaCmd = buildTmuxAgentCommand(executable, args, execEnv, { redactEnvValues: true });
     const labels = { agent: options.agent };
     if (options.sessionId)
         labels.sessionId = options.sessionId;
-    const meta = await createSession({ name, cmd, cwd, socket, source: 'cli', labels });
+    const meta = await createSession({ name, cmd, metaCmd, cwd, socket, source: 'cli', labels });
     const pane = meta.pane;
     if (pane) {
         // When the AGENT pane dies, detach the client (don't kill) so the session
@@ -990,7 +1002,7 @@ async function runInTmux(options, executable, args) {
             await surfacePaneFailure(before.status, `${options.agent} exited before it could start`);
         }
         await killSession(name, socket).catch(() => { });
-        return { exitCode: before.status ?? 0, stderr: '' };
+        return { exitCode: before.status ?? 0, stderr: '', stdout: '' };
     }
     await attachTmux({ socket, args: ['attach-session', '-t', name] });
     const after = pane ? await paneExitStatus(pane, socket) : { dead: false };
@@ -1003,10 +1015,10 @@ async function runInTmux(options, executable, args) {
             await surfacePaneFailure(after.status, `${options.agent} exited`);
         }
         await killSession(name, socket).catch(() => { });
-        return { exitCode: after.status ?? 0, stderr: '' };
+        return { exitCode: after.status ?? 0, stderr: '', stdout: '' };
     }
     // Pane still alive → the user detached; keep the session for `agents focus`.
-    return { exitCode: 0, stderr: '' };
+    return { exitCode: 0, stderr: '', stdout: '' };
 }
 /**
  * Spawn an agent process and return its exit code plus a tee'd copy of stderr.
@@ -1092,7 +1104,7 @@ async function spawnAgent(options) {
         // PIPE (and later tee) stdout whenever the live budget watcher must read it
         // — for ALL non-interactive runs when caps are active, regardless of TTY.
         // See shouldTapStdout() for the rationale (FIX 3, issue #346).
-        const tapStdout = shouldTapStdout(interactive, piped, watcherState !== null);
+        const tapStdout = shouldTapStdout(interactive, piped, watcherState !== null, options.captureStdoutTail);
         const stdio = interactive
             ? ['inherit', 'inherit', 'inherit']
             : ['inherit', tapStdout ? 'pipe' : 'inherit', 'pipe'];
@@ -1127,10 +1139,17 @@ async function spawnAgent(options) {
         timer.mark('startup');
         let budgetKilled = false;
         let budgetKillTimer;
+        let stdoutTail = '';
+        const STDOUT_TAIL_CAP = 16 * 1024;
         if (!interactive && tapStdout && child.stdout) {
             // TEE the child's stdout back to the parent's so the user still sees
             // output (mirrors stdio:'inherit') while we tap the same stream for usage.
             child.stdout.pipe(process.stdout);
+            // Keep a rolling TAIL (billing refusals arrive at the very end of a run)
+            // for the fallback chain's rate-limit scan.
+            child.stdout.on('data', (chunk) => {
+                stdoutTail = (stdoutTail + chunk.toString('utf-8')).slice(-STDOUT_TAIL_CAP);
+            });
             // Tap the same stream for budget usage events without consuming the pipe
             // (a 'data' listener and .pipe() both receive every chunk). Kill on breach.
             if (watcherState) {
@@ -1200,7 +1219,7 @@ async function spawnAgent(options) {
             // teams/cloud can tell a budget termination apart from a normal failure.
             const exitCode = budgetKilled ? BUDGET_KILL_EXIT_CODE : (code ?? 0);
             timer.end({ exitCode, status: budgetKilled ? 'budget_killed' : code === 0 ? 'success' : 'failed' });
-            resolve({ exitCode, stderr: stderrBuffer });
+            resolve({ exitCode, stderr: stderrBuffer, stdout: stdoutTail });
         });
     });
 }
@@ -1282,6 +1301,12 @@ export const RATE_LIMIT_PATTERNS = [
     /too many requests/i,
     /api[\s_-]?overloaded/i,
     /\boverloaded\b/i,
+    // Claude billing refusals — "You've hit your org's monthly spend limit" and
+    // "You're out of usage credits". Both end the run with exit 1 and are exactly
+    // the condition a fallback chain exists to recover from. Printed to STDOUT,
+    // hence the stdout tail in SpawnResult.
+    /spend[\s-]?limit/i,
+    /out of (?:usage )?credits/i,
 ];
 /** Return true if the text contains any known rate-limit or overload indicator. */
 export function detectRateLimit(text) {
@@ -1370,6 +1395,9 @@ export async function runWithFallback(options) {
             prompt,
             env: envOverride ? { ...(options.env ?? {}), ...envOverride } : options.env,
             sessionId: pinnedSessionId ?? (i === 0 ? options.sessionId : undefined),
+            // Claude prints billing refusals (spend limit / out of credits) to
+            // stdout; tail it so the cascade check below can see them.
+            captureStdoutTail: true,
         };
         const label = version ? `${agent}@${version}` : agent;
         const modelSwapNote = sameHostRetry && envOverride
@@ -1397,7 +1425,7 @@ export async function runWithFallback(options) {
         const isLast = i === chain.length - 1;
         if (isLast)
             return result.exitCode;
-        if (!detectRateLimit(result.stderr)) {
+        if (!detectRateLimit(result.stderr) && !detectRateLimit(result.stdout)) {
             return result.exitCode;
         }
         const next = chain[i + 1];

package/dist/lib/fleet/apply.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Reconcile engine for `agents apply`. The diff (`diffFleet`) is pure and unit-
+ * tested; execution (`probeDevice`, `reconcileDevice`, `runFleetApply`) drives
+ * the real fleet over SSH and is verified end-to-end against live devices.
+ *
+ * Flow per device: probe → install/upgrade agents-cli → add missing agents →
+ * sync config → propagate login. Every step reuses an existing primitive
+ * (`readyProbe`, `bootstrapAgentsCli`, `buildRemoteAgentsInvocation`, `sshExec`).
+ */
+import type { DeviceProfile } from '../devices/registry.js';
+import type { DeviceDesired, DeviceProbe, DeviceDiff, FleetAction, FleetPlan, AuthFilePayload } from './types.js';
+/** Strip a version suffix from an agent spec: `claude@latest` -> `claude`. */
+export declare function agentIdOf(spec: string): string;
+/** Source-side auth availability, computed once from `snapshotAuth`. */
+export interface SourceAuth {
+    /** Agent ids the source has a readable, propagatable credential file for. */
+    available: Set<string>;
+    /** Agent ids whose source auth is device-bound (macOS keychain). */
+    bound: Set<string>;
+    /** The captured file payloads, keyed by agent. */
+    filesByAgent: Map<string, AuthFilePayload[]>;
+}
+/**
+ * Can we propagate `agent`'s login to a target on `targetPlatform`? False when
+ * the agent has no portable file, the source can't provide it (bound / not
+ * signed in), or the target consumes credentials from its own keychain.
+ */
+export declare function canPushLogin(agent: string, targetPlatform: string | undefined, src: SourceAuth): boolean;
+export interface DiffContext {
+    /** agents-cli version the source is on — the fleet target version. */
+    targetCliVersion: string;
+    sourceAuth: SourceAuth;
+}
+/** Pure: desired vs probed -> per-device diff + flat action list. */
+export declare function diffFleet(desired: DeviceDesired[], probes: Map<string, DeviceProbe>, ctx: DiffContext): FleetPlan;
+/** Probe one device: reachability + agents-cli version + installed agent ids. */
+export declare function probeDevice(device: DeviceProfile): DeviceProbe;
+export interface ApplyStep {
+    kind: FleetAction['kind'];
+    ok: boolean;
+    detail: string;
+}
+export interface DeviceApplyResult {
+    device: string;
+    ok: boolean;
+    steps: ApplyStep[];
+    note?: string;
+}
+export interface ExecContext {
+    targetCliVersion: string;
+    source: string;
+    sourceAuth: SourceAuth;
+    /** Set for a dry run — probe + plan only, execute nothing. */
+    dryRun?: boolean;
+}
+/** Execute one device's planned actions in order. Real SSH — no mocks. */
+export declare function reconcileDevice(row: DeviceDiff, device: DeviceProfile, ctx: ExecContext): DeviceApplyResult;
+/** Run a pool of async tasks with a concurrency cap, preserving input order. */
+export declare function pool<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+/** Reconcile every device row in parallel (capped). */
+export declare function runFleetApply(rows: DeviceDiff[], nameToProfile: Map<string, DeviceProfile>, ctx: ExecContext, concurrency?: number): Promise<DeviceApplyResult[]>;
+/** Default home for source snapshots (overridable in tests). */
+export declare function sourceHome(): string;

package/dist/lib/fleet/apply.js

@@ -0,0 +1,214 @@
+/**
+ * Reconcile engine for `agents apply`. The diff (`diffFleet`) is pure and unit-
+ * tested; execution (`probeDevice`, `reconcileDevice`, `runFleetApply`) drives
+ * the real fleet over SSH and is verified end-to-end against live devices.
+ *
+ * Flow per device: probe → install/upgrade agents-cli → add missing agents →
+ * sync config → propagate login. Every step reuses an existing primitive
+ * (`readyProbe`, `bootstrapAgentsCli`, `buildRemoteAgentsInvocation`, `sshExec`).
+ */
+import * as os from 'os';
+import { sshTargetFor } from '../devices/connect.js';
+import { readyProbe, bootstrapAgentsCli } from '../hosts/ready.js';
+import { buildRemoteAgentsInvocation } from '../hosts/remote-cmd.js';
+import { sshExec } from '../ssh-exec.js';
+import { isPropagatableAgent, KEYCHAIN_BOUND_ON_MAC, buildAuthBundle, } from './auth-sync.js';
+/** Strip a version suffix from an agent spec: `claude@latest` -> `claude`. */
+export function agentIdOf(spec) {
+    return spec.split('@')[0].trim();
+}
+/**
+ * Can we propagate `agent`'s login to a target on `targetPlatform`? False when
+ * the agent has no portable file, the source can't provide it (bound / not
+ * signed in), or the target consumes credentials from its own keychain.
+ */
+export function canPushLogin(agent, targetPlatform, src) {
+    if (!isPropagatableAgent(agent))
+        return false;
+    if (src.bound.has(agent))
+        return false;
+    if (targetPlatform === 'macos' && KEYCHAIN_BOUND_ON_MAC.has(agent))
+        return false;
+    return src.available.has(agent);
+}
+/** Pure: desired vs probed -> per-device diff + flat action list. */
+export function diffFleet(desired, probes, ctx) {
+    const devices = [];
+    const actions = [];
+    for (const d of desired) {
+        const probe = probes.get(d.device) ?? {
+            device: d.device,
+            reachable: false,
+            installedAgents: [],
+            note: 'not probed',
+        };
+        const rowActions = [];
+        const loginBlocked = [];
+        if (probe.reachable) {
+            // agents-cli presence.
+            if (!probe.cliVersion) {
+                rowActions.push({ device: d.device, kind: 'install-cli', detail: `install agents-cli ${ctx.targetCliVersion}` });
+            }
+            else if (probe.cliVersion !== ctx.targetCliVersion) {
+                rowActions.push({ device: d.device, kind: 'upgrade-cli', detail: `agents-cli ${probe.cliVersion} -> ${ctx.targetCliVersion}` });
+            }
+            // agents.
+            for (const spec of d.agents) {
+                const id = agentIdOf(spec);
+                if (!probe.installedAgents.includes(id)) {
+                    rowActions.push({ device: d.device, kind: 'add-agent', agent: id, detail: `install ${spec}` });
+                }
+            }
+            // config.
+            if (d.sync.length > 0) {
+                rowActions.push({ device: d.device, kind: 'sync-config', detail: `sync config (${d.sync.join(', ')})` });
+            }
+            // login.
+            if (d.login === 'sync') {
+                for (const spec of d.agents) {
+                    const id = agentIdOf(spec);
+                    if (canPushLogin(id, probe.platform, ctx.sourceAuth)) {
+                        rowActions.push({ device: d.device, kind: 'push-login', agent: id, detail: `propagate ${id} login` });
+                    }
+                    else if (isPropagatableAgent(id) &&
+                        (ctx.sourceAuth.bound.has(id) || (probe.platform === 'macos' && KEYCHAIN_BOUND_ON_MAC.has(id)))) {
+                        // A login-propagation candidate we still can't push: the source token
+                        // is keychain-bound (unextractable), or the macOS target consumes its
+                        // own keychain. Surface those as manual — don't fake. Agents that were
+                        // never propagation candidates (no portable file), or a source that
+                        // simply isn't signed in, are silently skipped the same on every OS.
+                        loginBlocked.push(id);
+                        rowActions.push({ device: d.device, kind: 'needs-login', agent: id, detail: `${id} needs a manual login` });
+                    }
+                }
+            }
+        }
+        devices.push({ device: d.device, desired: d, probe, actions: rowActions, loginBlocked });
+        actions.push(...rowActions);
+    }
+    return { devices, actions };
+}
+// ---- execution (real SSH; verified end-to-end, not unit-mocked) ----
+function osHint(platform) {
+    return platform === 'windows' ? 'windows' : undefined;
+}
+/** POSIX login shells often miss the shims dir; inject it (mirrors doctor). */
+function remoteEnv(platform) {
+    return platform === 'windows' ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' };
+}
+/** Probe one device: reachability + agents-cli version + installed agent ids. */
+export function probeDevice(device) {
+    let target;
+    try {
+        target = sshTargetFor(device);
+    }
+    catch (e) {
+        return { device: device.name, reachable: false, platform: device.platform, installedAgents: [], note: e.message };
+    }
+    const hint = osHint(device.platform);
+    const ready = readyProbe(target, hint);
+    if (!ready.reachable) {
+        return { device: device.name, reachable: false, platform: device.platform, installedAgents: [], note: 'unreachable' };
+    }
+    let installed = [];
+    const remoteCmd = buildRemoteAgentsInvocation(['teams', 'doctor', '--json'], undefined, hint, remoteEnv(device.platform));
+    const res = sshExec(target, remoteCmd, { timeoutMs: 30000, multiplex: true });
+    if (res.code === 0) {
+        try {
+            const map = JSON.parse(res.stdout);
+            installed = Object.entries(map).filter(([, e]) => e?.installed).map(([k]) => k);
+        }
+        catch {
+            /* agents-cli present but doctor output unparsable — treat as no agents */
+        }
+    }
+    return {
+        device: device.name,
+        reachable: true,
+        platform: device.platform,
+        cliVersion: ready.version ?? undefined,
+        installedAgents: installed,
+    };
+}
+/** Execute one device's planned actions in order. Real SSH — no mocks. */
+export function reconcileDevice(row, device, ctx) {
+    if (!row.probe.reachable) {
+        return { device: row.device, ok: false, steps: [], note: row.probe.note ?? 'unreachable' };
+    }
+    const steps = [];
+    let target;
+    try {
+        target = sshTargetFor(device);
+    }
+    catch (e) {
+        return { device: row.device, ok: false, steps: [], note: e.message };
+    }
+    const hint = osHint(device.platform);
+    const env = remoteEnv(device.platform);
+    let ok = true;
+    const sshAgents = (args, input) => sshExec(target, buildRemoteAgentsInvocation(args, undefined, hint, env), { timeoutMs: 300000, multiplex: true, input });
+    // 1. agents-cli install/upgrade.
+    const cliAction = row.actions.find((a) => a.kind === 'install-cli' || a.kind === 'upgrade-cli');
+    if (cliAction) {
+        const r = bootstrapAgentsCli(target, ctx.targetCliVersion, hint);
+        steps.push({ kind: cliAction.kind, ok: r.ok, detail: cliAction.detail });
+        ok = ok && r.ok;
+    }
+    // 2. agents.
+    for (const a of row.actions.filter((x) => x.kind === 'add-agent')) {
+        const spec = a.detail.replace(/^install\s+/, '');
+        const r = sshAgents(['add', spec, '--yes']);
+        steps.push({ kind: 'add-agent', ok: r.code === 0, detail: a.detail });
+        ok = ok && r.code === 0;
+    }
+    // 3. config sync.
+    if (row.actions.some((a) => a.kind === 'sync-config')) {
+        const r = sshAgents(['sync']);
+        steps.push({ kind: 'sync-config', ok: r.code === 0, detail: `sync config` });
+        ok = ok && r.code === 0;
+    }
+    // 4. login propagation — one bundle for all pushable agents on this device.
+    const pushAgents = [...new Set(row.actions.filter((a) => a.kind === 'push-login').map((a) => a.agent))];
+    if (pushAgents.length > 0) {
+        const files = [];
+        for (const agent of pushAgents)
+            files.push(...(ctx.sourceAuth.filesByAgent.get(agent) ?? []));
+        const bundle = buildAuthBundle(ctx.source, files);
+        const r = sshAgents(['apply', '--recv-auth'], JSON.stringify(bundle));
+        steps.push({ kind: 'push-login', ok: r.code === 0, detail: `propagate login: ${pushAgents.join(', ')}` });
+        ok = ok && r.code === 0;
+    }
+    // Surface blocked logins as (non-fatal) informational steps.
+    for (const blocked of row.loginBlocked) {
+        steps.push({ kind: 'needs-login', ok: false, detail: `${blocked} needs a manual login (\`agents ssh ${row.device} -- ${blocked}\`)` });
+    }
+    return { device: row.device, ok, steps };
+}
+/** Run a pool of async tasks with a concurrency cap, preserving input order. */
+export async function pool(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i], i);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+/** Reconcile every device row in parallel (capped). */
+export async function runFleetApply(rows, nameToProfile, ctx, concurrency = 6) {
+    return pool(rows, concurrency, async (row) => {
+        const profile = nameToProfile.get(row.device);
+        if (!profile)
+            return { device: row.device, ok: false, steps: [], note: 'no device profile' };
+        return reconcileDevice(row, profile, ctx);
+    });
+}
+/** Default home for source snapshots (overridable in tests). */
+export function sourceHome() {
+    return os.homedir();
+}

package/dist/lib/fleet/auth-sync.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Login/token propagation — the "one login instead of ~48 OAuth flows" core of
+ * `agents apply`.
+ *
+ * A source machine that is already signed in to a set of harnesses has portable
+ * credential files on disk (verified per-agent locations below). `snapshotAuth`
+ * captures those; `materializeAuth` writes them into the corresponding paths on
+ * a target device. Transport is the caller's job — `apply` streams the bundle
+ * over the existing (encrypted, authenticated) SSH channel via `sshExec`'s
+ * stdin `input`, so no app-layer crypto is layered on top of SSH here.
+ *
+ * Honest boundary: on macOS, claude and antigravity keep their tokens in the
+ * login keychain, ACL-bound to the harness process — unreadable by us. Those are
+ * classified `bound` and surfaced for a one-time manual login, never faked.
+ */
+import type { AuthFilePayload, AuthBundle, AuthSnapshotResult } from './types.js';
+/** A portable credential file location, relative to $HOME. */
+interface AuthFileSpec {
+    rel: string;
+    mode: number;
+}
+/**
+ * Verified portable auth-file locations per agent (home-relative). Sourced from
+ * live inspection of a Linux fleet box + the agent registry. Agents absent here
+ * have no portable credential file we can propagate.
+ */
+export declare const FLEET_AUTH_FILES: Record<string, AuthFileSpec[]>;
+/** Agents whose macOS credentials live in the ACL-bound login keychain. */
+export declare const KEYCHAIN_BOUND_ON_MAC: ReadonlySet<string>;
+/** Which agents `apply` can propagate auth for at all. */
+export declare function isPropagatableAgent(agent: string): boolean;
+export interface SnapshotOptions {
+    /** Home directory to read credential files from. */
+    home: string;
+    /** Platform of the source machine (`process.platform`). */
+    platform: NodeJS.Platform;
+}
+/**
+ * Capture portable credential files for the given agents from a source home.
+ * Returns the readable file payloads plus the list of agents whose auth is
+ * device-bound (macOS keychain) and therefore cannot be captured. Agents that
+ * are simply not signed in (no file on disk) are silently omitted — nothing to
+ * propagate, not an error.
+ */
+export declare function snapshotAuth(agents: string[], opts: SnapshotOptions): AuthSnapshotResult;
+/** Assemble the plaintext bundle shipped to a target. */
+export declare function buildAuthBundle(source: string, files: AuthFilePayload[]): AuthBundle;
+export interface MaterializeOptions {
+    /** Home directory to write credential files into. */
+    home: string;
+}
+export interface MaterializeResult {
+    /** Agent ids that received at least one file. */
+    written: string[];
+    /** `rel: reason` for any file that failed. */
+    errors: string[];
+}
+/**
+ * Write a captured auth bundle into a target home. Parent dirs are created; the
+ * captured POSIX mode is restored (0600 for credentials). Writing through an
+ * existing symlink lands in the agent's active version home, which is exactly
+ * what per-version credential carry-forward expects.
+ */
+export declare function materializeAuth(bundle: AuthBundle, opts: MaterializeOptions): MaterializeResult;
+/** Parse + validate a bundle received on stdin (the remote `--_recv-auth` path). */
+export declare function parseAuthBundle(raw: string): AuthBundle;
+export {};

package/dist/lib/fleet/auth-sync.js

@@ -0,0 +1,142 @@
+/**
+ * Login/token propagation — the "one login instead of ~48 OAuth flows" core of
+ * `agents apply`.
+ *
+ * A source machine that is already signed in to a set of harnesses has portable
+ * credential files on disk (verified per-agent locations below). `snapshotAuth`
+ * captures those; `materializeAuth` writes them into the corresponding paths on
+ * a target device. Transport is the caller's job — `apply` streams the bundle
+ * over the existing (encrypted, authenticated) SSH channel via `sshExec`'s
+ * stdin `input`, so no app-layer crypto is layered on top of SSH here.
+ *
+ * Honest boundary: on macOS, claude and antigravity keep their tokens in the
+ * login keychain, ACL-bound to the harness process — unreadable by us. Those are
+ * classified `bound` and surfaced for a one-time manual login, never faked.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Verified portable auth-file locations per agent (home-relative). Sourced from
+ * live inspection of a Linux fleet box + the agent registry. Agents absent here
+ * have no portable credential file we can propagate.
+ */
+export const FLEET_AUTH_FILES = {
+    claude: [{ rel: '.claude/.credentials.json', mode: 0o600 }],
+    codex: [{ rel: '.codex/auth.json', mode: 0o600 }],
+    gemini: [{ rel: '.gemini/oauth_creds.json', mode: 0o600 }],
+    grok: [{ rel: '.grok/auth.json', mode: 0o600 }],
+    kimi: [{ rel: '.kimi-code/credentials/kimi-code.json', mode: 0o600 }],
+    opencode: [{ rel: '.local/share/opencode/auth.json', mode: 0o600 }],
+    droid: [
+        { rel: '.factory/auth.v2.file', mode: 0o600 },
+        { rel: '.factory/auth.v2.key', mode: 0o600 },
+    ],
+    antigravity: [{ rel: '.gemini/antigravity-cli/antigravity-oauth-token', mode: 0o600 }],
+};
+/** Agents whose macOS credentials live in the ACL-bound login keychain. */
+export const KEYCHAIN_BOUND_ON_MAC = new Set(['claude', 'antigravity']);
+/** Which agents `apply` can propagate auth for at all. */
+export function isPropagatableAgent(agent) {
+    return agent in FLEET_AUTH_FILES;
+}
+/**
+ * Capture portable credential files for the given agents from a source home.
+ * Returns the readable file payloads plus the list of agents whose auth is
+ * device-bound (macOS keychain) and therefore cannot be captured. Agents that
+ * are simply not signed in (no file on disk) are silently omitted — nothing to
+ * propagate, not an error.
+ */
+export function snapshotAuth(agents, opts) {
+    const files = [];
+    const bound = [];
+    for (const agent of agents) {
+        const specs = FLEET_AUTH_FILES[agent];
+        if (!specs)
+            continue; // not propagatable — caller surfaces separately if desired
+        if (opts.platform === 'darwin' && KEYCHAIN_BOUND_ON_MAC.has(agent)) {
+            bound.push(agent);
+            continue;
+        }
+        for (const spec of specs) {
+            const abs = path.join(opts.home, spec.rel);
+            let stat;
+            try {
+                stat = fs.statSync(abs);
+            }
+            catch {
+                continue; // not signed in for this agent — nothing to carry
+            }
+            if (!stat.isFile())
+                continue;
+            const content = fs.readFileSync(abs); // follows symlinks into version homes
+            files.push({
+                agent,
+                rel: spec.rel,
+                contentB64: content.toString('base64'),
+                mode: (stat.mode & 0o777) || spec.mode,
+            });
+        }
+    }
+    return { files, bound };
+}
+/** Assemble the plaintext bundle shipped to a target. */
+export function buildAuthBundle(source, files) {
+    return { v: 1, source, files };
+}
+/**
+ * Write a captured auth bundle into a target home. Parent dirs are created; the
+ * captured POSIX mode is restored (0600 for credentials). Writing through an
+ * existing symlink lands in the agent's active version home, which is exactly
+ * what per-version credential carry-forward expects.
+ */
+export function materializeAuth(bundle, opts) {
+    const written = new Set();
+    const errors = [];
+    for (const f of bundle.files) {
+        const abs = path.join(opts.home, f.rel);
+        try {
+            fs.mkdirSync(path.dirname(abs), { recursive: true });
+            fs.writeFileSync(abs, Buffer.from(f.contentB64, 'base64'));
+            fs.chmodSync(abs, f.mode || 0o600);
+            written.add(f.agent);
+        }
+        catch (e) {
+            errors.push(`${f.rel}: ${e.message}`);
+        }
+    }
+    return { written: [...written], errors };
+}
+/** Parse + validate a bundle received on stdin (the remote `--_recv-auth` path). */
+export function parseAuthBundle(raw) {
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`auth bundle is not valid JSON: ${e.message}`);
+    }
+    if (typeof doc !== 'object' || doc === null)
+        throw new Error('auth bundle must be an object.');
+    const o = doc;
+    if (o.v !== 1)
+        throw new Error(`unsupported auth bundle version ${JSON.stringify(o.v)}.`);
+    if (typeof o.source !== 'string')
+        throw new Error('auth bundle missing source.');
+    if (!Array.isArray(o.files))
+        throw new Error('auth bundle missing files[].');
+    for (const f of o.files) {
+        if (typeof f !== 'object' || f === null ||
+            typeof f.agent !== 'string' ||
+            typeof f.rel !== 'string' ||
+            typeof f.contentB64 !== 'string' ||
+            typeof f.mode !== 'number') {
+            throw new Error('auth bundle has a malformed file entry.');
+        }
+        // Reject path traversal — rel must stay under $HOME.
+        const rel = f.rel;
+        if (rel.startsWith('/') || rel.split('/').includes('..')) {
+            throw new Error(`auth bundle rejected unsafe path: ${rel}`);
+        }
+    }
+    return doc;
+}

package/dist/lib/fleet/manifest.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Parse + validate the `fleet:` block of a profile manifest and resolve it into
+ * per-device desired state.
+ *
+ * `fleet:` is additive to the `Meta` schema (`types.ts`). Any `-f <file>` that
+ * carries a `fleet:` block is a valid manifest, so `ag apply -f agents.yaml`
+ * works against the project file. The functions here are pure (no SSH, no
+ * registry I/O) so they're fully unit-testable; device enumeration is injected.
+ */
+import type { FleetManifest, DeviceDesired } from './types.js';
+/** Validate a raw `fleet:` object (already YAML-parsed) into a typed manifest. */
+export declare function parseFleetManifest(raw: unknown): FleetManifest;
+/** Read a YAML file and extract + validate its `fleet:` block. */
+export declare function readFleetFile(filePath: string): FleetManifest;
+export interface ResolveContext {
+    /** Device names currently online (used to expand `devices: all`). */
+    onlineDevices: string[];
+    /** All registered device names (used to validate explicit entries). */
+    registeredDevices: string[];
+    /** The source machine, always excluded from the target set. */
+    source: string;
+}
+/**
+ * Expand a manifest into concrete per-device desired states. `devices: all`
+ * expands to every online registered device minus the source; an explicit map
+ * validates each name against the registry. Devices with no desired agents,
+ * sync scopes, and `login: skip` are still returned (probe/report only).
+ */
+export declare function resolveDesired(manifest: FleetManifest, ctx: ResolveContext): DeviceDesired[];