@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/lib/devices/registry.js

@@ -18,7 +18,7 @@ import * as fsSync from 'fs';
 import * as path from 'path';
 import { randomBytes } from 'crypto';
 import lockfile from 'proper-lockfile';
-import { getDevicesRegistryPath, getDevicesIgnoredPath, getDevicesAutoLaunchPath } from '../state.js';
+import { getDevicesRegistryPath, getDevicesIgnoredPath } from '../state.js';
 /** A device's effective role, defaulting to `worker` when unset. */
 export function deviceRole(d) {
     return d.role ?? 'worker';
@@ -56,7 +56,7 @@ export function isDialableDevice(d) {
     // every session on that box unresolvable from any other machine.
     //
     // So: no tailscale block at all is unknown-not-offline (the rule `ssh.ts`
-    // renderDeviceTable and Factory's `isDeviceOnline` already use, so the picker
+    // renderDeviceTable and the ext's `isDeviceOnline` already use, so the picker
     // and the sweep agree on who exists), and a positive probe rescues a device
     // whose snapshot says offline. The cost of dialing a box that is actually
     // asleep is one ConnectTimeout — the pre-existing behaviour, not a regression.
@@ -325,84 +325,3 @@ export async function removeIgnored(name) {
         return true;
     });
 }
-function autoLaunchPath() {
-    return getDevicesAutoLaunchPath();
-}
-/** Load auto-launch preferences. Missing or malformed file => empty map. */
-export async function loadAutoLaunchPreferences() {
-    const p = autoLaunchPath();
-    let raw;
-    try {
-        raw = await fs.readFile(p, 'utf-8');
-    }
-    catch (err) {
-        if (err && err.code === 'ENOENT')
-            return {};
-        throw err;
-    }
-    try {
-        const parsed = JSON.parse(raw);
-        return parsed.devices && typeof parsed.devices === 'object' ? parsed.devices : {};
-    }
-    catch (err) {
-        throw new Error(`Device auto-launch preferences corrupted at ${p}: ${err?.message ?? err}. Inspect and restore from backup.`);
-    }
-}
-/** True if the device is enabled for auto-launch. Missing entry defaults to true. */
-export async function isAutoLaunchEnabled(name) {
-    assertValidDeviceName(name);
-    const prefs = await loadAutoLaunchPreferences();
-    return prefs[name]?.enabled !== false;
-}
-/** Set whether a device is enabled for auto-launch. Setting to the default
- * (enabled) removes the entry to keep the file minimal. */
-export async function setAutoLaunchEnabled(name, enabled) {
-    assertValidDeviceName(name);
-    const p = autoLaunchPath();
-    await withRegistryLock(p, async () => {
-        const prefs = await loadAutoLaunchPreferences();
-        if (enabled) {
-            if (prefs[name]) {
-                const { enabled: _, ...rest } = prefs[name];
-                if (Object.keys(rest).length === 0) {
-                    delete prefs[name];
-                }
-                else {
-                    prefs[name] = rest;
-                }
-            }
-        }
-        else {
-            prefs[name] = { ...prefs[name], enabled: false };
-        }
-        await atomicWriteJson(p, { devices: prefs, updatedAt: new Date().toISOString() });
-    });
-}
-/** True if the device is preferred for auto-launch ranking. */
-export async function isAutoLaunchPreferred(name) {
-    assertValidDeviceName(name);
-    const prefs = await loadAutoLaunchPreferences();
-    return prefs[name]?.preferred === true;
-}
-/** Set whether a device is preferred for auto-launch. Setting to the default
- * (not preferred) removes the flag to keep the file minimal. */
-export async function setAutoLaunchPreferred(name, preferred) {
-    assertValidDeviceName(name);
-    const p = autoLaunchPath();
-    await withRegistryLock(p, async () => {
-        const prefs = await loadAutoLaunchPreferences();
-        if (preferred) {
-            prefs[name] = { ...prefs[name], preferred: true };
-        }
-        else if (prefs[name]) {
-            const { preferred: _, ...rest } = prefs[name];
-            if (Object.keys(rest).length === 0) {
-                delete prefs[name];
-            }
-            else {
-                prefs[name] = rest;
-            }
-        }
-        await atomicWriteJson(p, { devices: prefs, updatedAt: new Date().toISOString() });
-    });
-}

package/dist/lib/devices/resolve-profile.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The effective device profile: the registry's discovery record overlaid with
+ * the operator's central config (`fleet.devices.<name>.config` in
+ * `~/.agents/agents.yaml`).
+ *
+ * The registry (`~/.agents/.history/devices/registry.json`) stays the
+ * discovery cache — address, Tailscale snapshot, reachability, createdAt. The
+ * central config owns the operator-set profile fields: `ssh.user`, `ssh.auth`,
+ * `ssh.bundle`, `ssh.bundle-key`, `ssh.identity-file`, and `platform`. A config
+ * value WINS over the registry field so `agents devices config <name>` takes
+ * effect from any box without re-discovery; an unset key falls back to the
+ * registry value.
+ *
+ * Sync and cheap (readMeta is cached), so dial/render call sites apply it at
+ * their entry point rather than threading a resolved profile through every
+ * signature. Resolving an already-resolved profile is idempotent.
+ */
+import { type DeviceProfile } from './registry.js';
+/** Overlay the central config's ssh.* / platform / user keys onto a registry profile. */
+export declare function resolveDeviceProfile(device: DeviceProfile): DeviceProfile;

package/dist/lib/devices/resolve-profile.js

@@ -0,0 +1,44 @@
+/**
+ * The effective device profile: the registry's discovery record overlaid with
+ * the operator's central config (`fleet.devices.<name>.config` in
+ * `~/.agents/agents.yaml`).
+ *
+ * The registry (`~/.agents/.history/devices/registry.json`) stays the
+ * discovery cache — address, Tailscale snapshot, reachability, createdAt. The
+ * central config owns the operator-set profile fields: `ssh.user`, `ssh.auth`,
+ * `ssh.bundle`, `ssh.bundle-key`, `ssh.identity-file`, and `platform`. A config
+ * value WINS over the registry field so `agents devices config <name>` takes
+ * effect from any box without re-discovery; an unset key falls back to the
+ * registry value.
+ *
+ * Sync and cheap (readMeta is cached), so dial/render call sites apply it at
+ * their entry point rather than threading a resolved profile through every
+ * signature. Resolving an already-resolved profile is idempotent.
+ */
+import { shellForPlatform, } from './registry.js';
+import { readDeviceConfigValues } from '../device-config.js';
+/** Overlay the central config's ssh.* / platform / user keys onto a registry profile. */
+export function resolveDeviceProfile(device) {
+    const config = readDeviceConfigValues(device.name);
+    const platform = config.platform ?? device.platform;
+    const method = config.sshAuth ?? device.auth.method;
+    const user = config.sshUser ?? device.user;
+    const identityFile = config.sshIdentityFile ?? device.auth.identityFile;
+    const bundle = config.sshBundle ?? device.auth.bundle;
+    const bundleKey = config.sshBundleKey ?? device.auth.bundleKey;
+    if (platform === device.platform &&
+        method === device.auth.method &&
+        user === device.user &&
+        identityFile === device.auth.identityFile &&
+        bundle === device.auth.bundle &&
+        bundleKey === device.auth.bundleKey) {
+        return device;
+    }
+    return {
+        ...device,
+        platform,
+        shell: shellForPlatform(platform),
+        user,
+        auth: { method, identityFile, bundle, bundleKey },
+    };
+}

package/dist/lib/devices/rollout-verify.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Post-rollout verification for `agents fleet update` / `agents devices update`.
+ *
+ * The rollout runs `agents upgrade --yes` per box and calls a box `ok` on
+ * `exit 0` alone ({@link ../devices/fleet.js runFleet}, `fleet.ts:262`), rendered
+ * as `ok  exit 0` (`commands/ssh.ts:416`). That exit code says the npm global was
+ * upgraded — it says nothing about **which copy `agents` resolves to on that
+ * box**. Any install earlier on PATH than the npm global — a stale copy in
+ * another node prefix, a Homebrew shim, a hand-made symlink — keeps winning the
+ * name after the upgrade. The upgrade then succeeds, the rollout prints `ok`,
+ * and every `agents` command on that box still runs the old code (RUSH-2446).
+ *
+ * `scripts/install.sh` used to be the usual culprit, linking its side-by-side
+ * dev build over `~/.local/bin/agents`; it now publishes `agents-dev` instead and
+ * cleans up the links it left. This probe stays as the general backstop — it is
+ * name-based (`command -v agents`), so it catches every other cause too.
+ *
+ * So the rollout asks each box one more question after upgrading: what does
+ * `agents` resolve to here, and what version does it report? A box whose
+ * resolved `agents` is not on the target is reported as **not upgraded**, and a
+ * dev stamp is named as such — never counted as a success.
+ *
+ * Everything below the probe argv is pure: the shell output is parsed and
+ * classified without touching a filesystem or a network, so the verdicts are
+ * unit-tested against real probe output rather than a mocked fleet.
+ */
+import { runLocalCommand, runOnDevice, type FleetRunResult, type FleetTarget } from './fleet.js';
+/**
+ * Argv for the verification probe, run on each box right after its upgrade.
+ *
+ * Space-joined and evaluated by a shell on both fleet paths — `runOnDevice`
+ * hands the tokens to ssh (the remote shell parses them) and `runLocalCommand`
+ * joins them under `shell: true` (`fleet.ts:runLocalCommand` docblock) — so the
+ * quoting here is the same on the self target and every peer.
+ *
+ * POSIX only, deliberately: the two `sh` builtins it needs (`command -v`,
+ * parameter substitution) do not exist in cmd.exe, so a Windows box yields no
+ * parseable output and {@link classifyRolloutVerification} reports it
+ * `unverified` rather than silently passing it.
+ *
+ * `command -v agents` is the resolution the user's own shell performs;
+ * `readlink -f` follows the npm/dev bin symlink to the copy that actually runs,
+ * falling back to the unresolved path where `readlink -f` is unavailable.
+ */
+export declare function rolloutVerifyCommand(): string[];
+export interface RolloutProbe {
+    /** Path the box's own `agents` resolves to, symlinks followed. */
+    resolvedPath?: string;
+    /** Version that resolved copy reports. */
+    reportedVersion?: string;
+}
+/** Parse the probe's stdout. Unlabelled lines (shell banners, motd) are ignored. */
+export declare function parseRolloutVerifyOutput(stdout: string): RolloutProbe;
+export type RolloutVerdict = 
+/** The resolved `agents` reports the target version. */
+'on-target'
+/** The resolved `agents` is a `scripts/install.sh` dev build shadowing the upgraded global. */
+ | 'dev-shadowed'
+/** The resolved `agents` reports some other version — the upgrade did not reach it. */
+ | 'not-upgraded'
+/** The probe produced no usable answer, so upgraded-ness is unknown. */
+ | 'unverified';
+export interface RolloutVerification extends RolloutProbe {
+    verdict: RolloutVerdict;
+    /** One-line human reason, always set for a non-`on-target` verdict. */
+    detail: string;
+}
+/** A verdict other than `on-target` MUST NOT be reported as a successful rollout. */
+export declare function isRolloutSuccess(verdict: RolloutVerdict): boolean;
+/**
+ * Resolve the version the rollout was aiming at.
+ *
+ * An explicit `agents fleet update <version>` names it. A bare
+ * `agents fleet update` resolves the `latest` dist-tag independently on every
+ * box, so the aggregator never sees a number — it is derived here as the highest
+ * **released** version any probed box reports. Dev stamps are excluded from that
+ * derivation: a fleet of dev builds must not elect one of them as the target and
+ * report itself upgraded. Returns undefined when nothing released was observed,
+ * which makes every box `unverified` rather than falsely `on-target`.
+ */
+export declare function resolveRolloutTarget(explicitVersion: string | undefined, probes: RolloutProbe[]): string | undefined;
+/** Classify one box's probe against the rollout target. */
+export declare function classifyRolloutVerification(probe: RolloutProbe, targetVersion: string | undefined): RolloutVerification;
+export interface VerifyFleetRolloutOptions {
+    /** Name of THIS machine; its target is probed locally, mirroring `runFleet`. */
+    self?: string;
+    /** Injectable ssh runner (tests). */
+    runner?: typeof runOnDevice;
+    /** Injectable local runner (tests). */
+    localRunner?: typeof runLocalCommand;
+}
+/**
+ * Probe every box the upgrade reported `ok` and classify what its `agents`
+ * actually resolves to. Keyed by device name.
+ *
+ * Only `ok` boxes are probed: a `skipped` or `failed` row already reports itself
+ * loudly, and re-probing it would add a second confusing line for one fault.
+ * A probe that throws or exits non-zero yields `unverified`, never `on-target` —
+ * "we could not check" and "it is upgraded" are different answers.
+ */
+export declare function verifyFleetRollout(targets: FleetTarget[], results: FleetRunResult[], explicitVersion: string | undefined, opts?: VerifyFleetRolloutOptions): Map<string, RolloutVerification>;

package/dist/lib/devices/rollout-verify.js

@@ -0,0 +1,193 @@
+/**
+ * Post-rollout verification for `agents fleet update` / `agents devices update`.
+ *
+ * The rollout runs `agents upgrade --yes` per box and calls a box `ok` on
+ * `exit 0` alone ({@link ../devices/fleet.js runFleet}, `fleet.ts:262`), rendered
+ * as `ok  exit 0` (`commands/ssh.ts:416`). That exit code says the npm global was
+ * upgraded — it says nothing about **which copy `agents` resolves to on that
+ * box**. Any install earlier on PATH than the npm global — a stale copy in
+ * another node prefix, a Homebrew shim, a hand-made symlink — keeps winning the
+ * name after the upgrade. The upgrade then succeeds, the rollout prints `ok`,
+ * and every `agents` command on that box still runs the old code (RUSH-2446).
+ *
+ * `scripts/install.sh` used to be the usual culprit, linking its side-by-side
+ * dev build over `~/.local/bin/agents`; it now publishes `agents-dev` instead and
+ * cleans up the links it left. This probe stays as the general backstop — it is
+ * name-based (`command -v agents`), so it catches every other cause too.
+ *
+ * So the rollout asks each box one more question after upgrading: what does
+ * `agents` resolve to here, and what version does it report? A box whose
+ * resolved `agents` is not on the target is reported as **not upgraded**, and a
+ * dev stamp is named as such — never counted as a success.
+ *
+ * Everything below the probe argv is pure: the shell output is parsed and
+ * classified without touching a filesystem or a network, so the verdicts are
+ * unit-tested against real probe output rather than a mocked fleet.
+ */
+import { compareVersions } from '../agent-spec/primitives.js';
+import { isDevVersionStamp } from '../startup/dev-build.js';
+import { runLocalCommand, runOnDevice, } from './fleet.js';
+import { isSelfHost } from './self-host.js';
+/**
+ * Line prefixes the probe emits. Prefixed rather than positional because a
+ * login shell can print its own banner lines into the same stdout, and a
+ * rollout that mis-reads a motd line as a version would report a false verdict.
+ */
+const PATH_PREFIX = 'agents-rollout-path=';
+const VERSION_PREFIX = 'agents-rollout-version=';
+/**
+ * Argv for the verification probe, run on each box right after its upgrade.
+ *
+ * Space-joined and evaluated by a shell on both fleet paths — `runOnDevice`
+ * hands the tokens to ssh (the remote shell parses them) and `runLocalCommand`
+ * joins them under `shell: true` (`fleet.ts:runLocalCommand` docblock) — so the
+ * quoting here is the same on the self target and every peer.
+ *
+ * POSIX only, deliberately: the two `sh` builtins it needs (`command -v`,
+ * parameter substitution) do not exist in cmd.exe, so a Windows box yields no
+ * parseable output and {@link classifyRolloutVerification} reports it
+ * `unverified` rather than silently passing it.
+ *
+ * `command -v agents` is the resolution the user's own shell performs;
+ * `readlink -f` follows the npm/dev bin symlink to the copy that actually runs,
+ * falling back to the unresolved path where `readlink -f` is unavailable.
+ */
+export function rolloutVerifyCommand() {
+    const script = [
+        'p=$(command -v agents || true)',
+        'r=$(readlink -f "$p" 2>/dev/null || echo "$p")',
+        `echo ${PATH_PREFIX}$r`,
+        `echo ${VERSION_PREFIX}$(agents --version 2>/dev/null || true)`,
+    ].join('; ');
+    return ['sh', '-c', `'${script}'`];
+}
+/** Parse the probe's stdout. Unlabelled lines (shell banners, motd) are ignored. */
+export function parseRolloutVerifyOutput(stdout) {
+    const probe = {};
+    for (const raw of stdout.split('\n')) {
+        const line = raw.trim();
+        if (line.startsWith(PATH_PREFIX)) {
+            const value = line.slice(PATH_PREFIX.length).trim();
+            if (value)
+                probe.resolvedPath = value;
+        }
+        else if (line.startsWith(VERSION_PREFIX)) {
+            const value = line.slice(VERSION_PREFIX.length).trim();
+            if (value)
+                probe.reportedVersion = value;
+        }
+    }
+    return probe;
+}
+/** A verdict other than `on-target` MUST NOT be reported as a successful rollout. */
+export function isRolloutSuccess(verdict) {
+    return verdict === 'on-target';
+}
+/**
+ * Resolve the version the rollout was aiming at.
+ *
+ * An explicit `agents fleet update <version>` names it. A bare
+ * `agents fleet update` resolves the `latest` dist-tag independently on every
+ * box, so the aggregator never sees a number — it is derived here as the highest
+ * **released** version any probed box reports. Dev stamps are excluded from that
+ * derivation: a fleet of dev builds must not elect one of them as the target and
+ * report itself upgraded. Returns undefined when nothing released was observed,
+ * which makes every box `unverified` rather than falsely `on-target`.
+ */
+export function resolveRolloutTarget(explicitVersion, probes) {
+    if (explicitVersion && !isDistTag(explicitVersion))
+        return explicitVersion;
+    let best;
+    for (const probe of probes) {
+        const version = probe.reportedVersion;
+        if (!version || isDevVersionStamp(version))
+            continue;
+        if (best === undefined || compareVersions(version, best) > 0)
+            best = version;
+    }
+    return best;
+}
+/**
+ * A dist-tag (`latest`, `next`) is not a comparable version. `agents fleet update`
+ * accepts either (`fleet.ts:upgradeCommand`), so a tag argument is treated the
+ * same as no argument: derive the number from what the fleet reports.
+ */
+function isDistTag(version) {
+    return !/^\d/.test(version);
+}
+/** Classify one box's probe against the rollout target. */
+export function classifyRolloutVerification(probe, targetVersion) {
+    const { resolvedPath, reportedVersion } = probe;
+    if (!reportedVersion) {
+        return {
+            ...probe,
+            verdict: 'unverified',
+            detail: resolvedPath
+                ? `resolved ${resolvedPath} but it reported no version`
+                : 'could not resolve `agents` on this box',
+        };
+    }
+    if (!targetVersion) {
+        return {
+            ...probe,
+            verdict: 'unverified',
+            detail: `runs ${reportedVersion}; no target version to compare against`,
+        };
+    }
+    if (reportedVersion === targetVersion) {
+        return { ...probe, verdict: 'on-target', detail: `runs ${reportedVersion}` };
+    }
+    if (isDevVersionStamp(reportedVersion)) {
+        return {
+            ...probe,
+            verdict: 'dev-shadowed',
+            detail: `NOT upgraded — \`agents\` resolves to a dev build (${reportedVersion})` +
+                `${resolvedPath ? ` at ${resolvedPath}` : ''}, shadowing the upgraded ${targetVersion} global`,
+        };
+    }
+    return {
+        ...probe,
+        verdict: 'not-upgraded',
+        detail: `NOT upgraded — \`agents\` runs ${reportedVersion}, target ${targetVersion}` +
+            `${resolvedPath ? ` (resolves to ${resolvedPath})` : ''}`,
+    };
+}
+/** Probe deadline. The probe is two shell builtins plus `agents --version`. */
+const VERIFY_TIMEOUT_MS = 60_000;
+/**
+ * Probe every box the upgrade reported `ok` and classify what its `agents`
+ * actually resolves to. Keyed by device name.
+ *
+ * Only `ok` boxes are probed: a `skipped` or `failed` row already reports itself
+ * loudly, and re-probing it would add a second confusing line for one fault.
+ * A probe that throws or exits non-zero yields `unverified`, never `on-target` —
+ * "we could not check" and "it is upgraded" are different answers.
+ */
+export function verifyFleetRollout(targets, results, explicitVersion, opts = {}) {
+    const runner = opts.runner ?? runOnDevice;
+    const localRunner = opts.localRunner ?? runLocalCommand;
+    const upgraded = new Set(results.filter((r) => r.status === 'ok').map((r) => r.name));
+    const cmd = rolloutVerifyCommand();
+    const probes = new Map();
+    for (const t of targets) {
+        const name = t.device.name;
+        if (t.skip || !upgraded.has(name))
+            continue;
+        try {
+            const isSelf = (opts.self !== undefined && name === opts.self) || isSelfHost(name);
+            const res = isSelf
+                ? localRunner(cmd, { timeoutMs: VERIFY_TIMEOUT_MS })
+                : runner(t.device, cmd, { timeoutMs: VERIFY_TIMEOUT_MS });
+            probes.set(name, parseRolloutVerifyOutput(res.stdout));
+        }
+        catch {
+            probes.set(name, {});
+        }
+    }
+    const target = resolveRolloutTarget(explicitVersion, [...probes.values()]);
+    const out = new Map();
+    for (const [name, probe] of probes) {
+        out.set(name, classifyRolloutVerification(probe, target));
+    }
+    return out;
+}

package/dist/lib/devices/ssh-config.js

@@ -1,3 +1,4 @@
+import { resolveDeviceProfile } from './resolve-profile.js';
 const HEADER = [
     '# Managed by `agents devices` — do not edit by hand.',
     '# Regenerate with: agents devices render',
@@ -9,14 +10,17 @@ export function hostNameFor(device) {
 }
 /** Render a single device into an ssh_config `Host` stanza, or null if it has no address. */
 function renderHost(device) {
-    const hostName = hostNameFor(device);
+    // Effective profile: operator config (ssh.user / ssh.identity-file) overlaid
+    // on the discovery record, so the rendered stanza matches what `agents ssh` dials.
+    const resolved = resolveDeviceProfile(device);
+    const hostName = hostNameFor(resolved);
     if (!hostName)
         return null;
-    const lines = [`Host ${device.name}`, `    HostName ${hostName}`];
-    if (device.user)
-        lines.push(`    User ${device.user}`);
-    if (device.auth.method === 'key' && device.auth.identityFile) {
-        lines.push(`    IdentityFile ${device.auth.identityFile}`, '    IdentitiesOnly yes');
+    const lines = [`Host ${resolved.name}`, `    HostName ${hostName}`];
+    if (resolved.user)
+        lines.push(`    User ${resolved.user}`);
+    if (resolved.auth.method === 'key' && resolved.auth.identityFile) {
+        lines.push(`    IdentityFile ${resolved.auth.identityFile}`, '    IdentitiesOnly yes');
     }
     return lines.join('\n');
 }

package/dist/lib/event-families.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Event stream families — sessions-style --include / --exclude for the unified
+ * event reader. One vocabulary maps onto existing filters (includeActivity,
+ * eventTypes, level) so the engine stays single-path.
+ */
+import type { EventType } from './events.js';
+import type { UnifiedQuery } from './event-stream.js';
+export declare const EVENT_FAMILIES: readonly ["ops", "activity", "commands", "runs", "security"];
+export type EventFamily = (typeof EVENT_FAMILIES)[number];
+export declare function isEventFamily(value: string): value is EventFamily;
+/**
+ * Parse a comma-separated family list. Throws on unknown names or empty list
+ * after split (same discipline as sessions role lists).
+ */
+export declare function parseFamilyList(raw: string, flagName: string): EventFamily[];
+/** Command-churn event kinds. */
+export declare const COMMAND_EVENT_TYPES: readonly EventType[];
+/** Run-dispatch outcome kinds (replaces the separate audit/log.jsonl product). */
+export declare const RUN_EVENT_TYPES: readonly EventType[];
+/**
+ * Fold family include/exclude into a UnifiedQuery.
+ * Precedence: family narrows sources/types; field filters (module, event, …)
+ * still apply on top.
+ *
+ * --include and --exclude are mutually exclusive at the CLI layer; this
+ * function accepts only one of includeFamilies / excludeFamilies.
+ */
+export declare function applyFamilies(q: UnifiedQuery): UnifiedQuery;