@phnx-labs/agents-cli 1.20.27 → 1.20.29

package/dist/lib/devices/registry.js

@@ -0,0 +1,168 @@
+/**
+ * Device registry.
+ *
+ * Manages the persistent registry of SSH device profiles stored at
+ * ~/.agents/.history/devices/registry.json. Each profile records what we had
+ * to re-derive by hand the first time we reached a host: its platform (so we
+ * know PowerShell vs POSIX), the login user, how to address it (Tailscale
+ * DNS name / IP), and how to authenticate (pubkey, or a password pulled from
+ * a secrets bundle).
+ *
+ * Like the team registry this is per-machine runtime state (it embeds a host
+ * list + addresses) and lives under .history/ so it is NOT pulled in by
+ * `agents repo push`. The load/save/lock plumbing is a deliberate clone of
+ * src/lib/teams/registry.ts so the data-loss guarantees match exactly.
+ */
+import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
+import * as path from 'path';
+import { randomBytes } from 'crypto';
+import lockfile from 'proper-lockfile';
+import { getDevicesRegistryPath } from '../state.js';
+function registryPath() {
+    return getDevicesRegistryPath();
+}
+/** Valid logical device name: the ssh-alias charset, so it renders into an
+ * unambiguous `Host` stanza and is safe as an ssh target. */
+const DEVICE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+/** Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.). */
+export function assertValidDeviceName(name) {
+    if (!DEVICE_NAME_RE.test(name)) {
+        throw new Error(`Invalid device name ${JSON.stringify(name)}. Use letters, digits, '.', '_', '-' (no spaces) — e.g. 'win-mini'.`);
+    }
+}
+/** Map a Tailscale `OS` field to our platform enum. */
+export function platformFromOs(os) {
+    switch ((os ?? '').toLowerCase()) {
+        case 'windows':
+            return 'windows';
+        case 'linux':
+            return 'linux';
+        case 'macos':
+        case 'darwin':
+            return 'macos';
+        default:
+            return 'unknown';
+    }
+}
+/** The remote shell a platform speaks. */
+export function shellForPlatform(platform) {
+    return platform === 'windows' ? 'powershell' : 'posix';
+}
+/**
+ * Atomic JSON write: write to a unique sibling tmp file then rename over the
+ * target. rename(2) is atomic on POSIX, so a crashed write leaves the old file
+ * untouched instead of producing a half-written registry that loadDevices()
+ * would reject.
+ */
+async function atomicWriteJson(p, data) {
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    const tmp = `${p}.tmp.${process.pid}.${randomBytes(4).toString('hex')}`;
+    await fs.writeFile(tmp, JSON.stringify(data, null, 2));
+    try {
+        await fs.rename(tmp, p);
+    }
+    catch (err) {
+        await fs.unlink(tmp).catch(() => { });
+        throw err;
+    }
+}
+/**
+ * Run `fn` while holding an exclusive cross-process lock on the registry file.
+ * proper-lockfile requires the target to exist, so we touch it first. Stale
+ * locks (from crashed callers) auto-expire after `stale` ms.
+ */
+async function withRegistryLock(p, fn) {
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    if (!fsSync.existsSync(p)) {
+        try {
+            await fs.writeFile(p, '{}', { flag: 'wx' });
+        }
+        catch (err) {
+            if (err && err.code !== 'EEXIST')
+                throw err;
+        }
+    }
+    const release = await lockfile.lock(p, {
+        retries: { retries: 60, minTimeout: 25, maxTimeout: 250, factor: 1.5 },
+        stale: 10_000,
+    });
+    try {
+        return await fn();
+    }
+    finally {
+        await release();
+    }
+}
+/**
+ * Load all devices from the registry file. Returns an empty object only when
+ * the file does not exist. A malformed file is a hard error — silently
+ * returning {} would let the next write wipe the user's device list.
+ */
+export async function loadDevices() {
+    const p = registryPath();
+    let raw;
+    try {
+        raw = await fs.readFile(p, 'utf-8');
+    }
+    catch (err) {
+        if (err && err.code === 'ENOENT')
+            return {};
+        throw err;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Device registry corrupted at ${p}: ${err?.message ?? err}. Inspect and restore from backup.`);
+    }
+}
+async function saveDevices(reg) {
+    await atomicWriteJson(registryPath(), reg);
+}
+/** Get a single device profile, or null if it is not registered. */
+export async function getDevice(name) {
+    const reg = await loadDevices();
+    return reg[name] ?? null;
+}
+/**
+ * Create the device if absent, otherwise merge the supplied fields into the
+ * existing profile. `shell` is always re-derived from the (possibly new)
+ * platform so the two can never drift. Returns the resulting profile.
+ */
+export async function upsertDevice(name, input) {
+    assertValidDeviceName(name);
+    const p = registryPath();
+    return withRegistryLock(p, async () => {
+        const reg = await loadDevices();
+        const now = new Date().toISOString();
+        const prev = reg[name];
+        const platform = input.platform ?? prev?.platform ?? 'unknown';
+        const merged = {
+            name,
+            platform,
+            shell: shellForPlatform(platform),
+            user: input.user ?? prev?.user,
+            address: input.address ?? prev?.address ?? { via: 'manual' },
+            auth: input.auth ?? prev?.auth ?? { method: 'key' },
+            tailscale: input.tailscale ?? prev?.tailscale,
+            createdAt: prev?.createdAt ?? now,
+            updatedAt: now,
+        };
+        reg[name] = merged;
+        await saveDevices(reg);
+        return merged;
+    });
+}
+/** Remove a device. Returns false if it was not registered. */
+export async function removeDevice(name) {
+    const p = registryPath();
+    return withRegistryLock(p, async () => {
+        const reg = await loadDevices();
+        if (!reg[name])
+            return false;
+        delete reg[name];
+        await saveDevices(reg);
+        return true;
+    });
+}

package/dist/lib/devices/ssh-config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Render the device registry into an OpenSSH `ssh_config` include block.
+ *
+ * Writing a managed include (e.g. `~/.ssh/config.d/agents`) makes every tool
+ * that speaks ssh — plain `ssh`/`scp`/`rsync`/`git`, and `agents sessions
+ * --host` — resolve the registry's logical device names transparently, without
+ * each of them learning about the registry. `agents ssh` stays the value-add
+ * layer (preflight, password-from-bundle auth, platform-aware exec) on top.
+ *
+ * `renderSshConfig` is a pure function (registry in, config text out) so the
+ * exact rendering is unit-testable.
+ */
+import { type DeviceProfile, type DeviceRegistry } from './registry.js';
+/** The HostName an ssh client should dial for a device: DNS name first, then IP. */
+export declare function hostNameFor(device: DeviceProfile): string | undefined;
+/**
+ * Render the whole registry into ssh_config text. Devices are emitted in
+ * stable alphabetical order (so the file does not churn between runs) and
+ * addressless devices are skipped.
+ */
+export declare function renderSshConfig(reg: DeviceRegistry): string;

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

@@ -0,0 +1,33 @@
+const HEADER = [
+    '# Managed by `agents devices` — do not edit by hand.',
+    '# Regenerate with: agents devices render',
+    '# Include from ~/.ssh/config with:  Include config.d/agents',
+].join('\n');
+/** The HostName an ssh client should dial for a device: DNS name first, then IP. */
+export function hostNameFor(device) {
+    return device.address.dnsName ?? device.address.ip;
+}
+/** Render a single device into an ssh_config `Host` stanza, or null if it has no address. */
+function renderHost(device) {
+    const hostName = hostNameFor(device);
+    if (!hostName)
+        return null;
+    const lines = [`Host ${device.name}`, `    HostName ${hostName}`];
+    if (device.user)
+        lines.push(`    User ${device.user}`);
+    return lines.join('\n');
+}
+/**
+ * Render the whole registry into ssh_config text. Devices are emitted in
+ * stable alphabetical order (so the file does not churn between runs) and
+ * addressless devices are skipped.
+ */
+export function renderSshConfig(reg) {
+    const stanzas = [];
+    for (const name of Object.keys(reg).sort()) {
+        const stanza = renderHost(reg[name]);
+        if (stanza)
+            stanzas.push(stanza);
+    }
+    return [HEADER, '', ...stanzas, ''].join('\n');
+}

package/dist/lib/devices/tailscale.d.ts

@@ -0,0 +1,31 @@
+import { type DeviceInput, type DevicePlatform } from './registry.js';
+/** A single node distilled from `tailscale status --json`. */
+export interface TailscaleNode {
+    name: string;
+    platform: DevicePlatform;
+    dnsName?: string;
+    ip?: string;
+    online: boolean;
+    direct: boolean;
+    relay?: string;
+    lastSeen?: string;
+}
+/**
+ * Slugify a raw Tailscale HostName into a valid logical device name (ssh alias
+ * charset). Used only as a fallback — when a node has a DNSName we prefer its
+ * first label, which is the canonical slug Tailscale itself derived.
+ */
+export declare function slugifyHostName(hostName: string): string;
+/**
+ * Parse `tailscale status --json` output into one node per tailnet device,
+ * including Self. Throws on malformed JSON. Nodes without a HostName are
+ * skipped (they cannot be addressed by a logical name).
+ */
+export declare function parseTailscaleStatus(json: string): TailscaleNode[];
+/** Turn a parsed Tailscale node into the registry fields it can populate. */
+export declare function nodeToDeviceInput(node: TailscaleNode): DeviceInput;
+/**
+ * Run `tailscale status --json` and return its raw stdout. Throws a clear
+ * error when the binary is missing or the daemon is not reachable.
+ */
+export declare function tailscaleStatusJson(): string;

package/dist/lib/devices/tailscale.js

@@ -0,0 +1,126 @@
+/**
+ * Tailscale ingestion for the device registry.
+ *
+ * `tailscale status --json` already hands us most of a device registry for
+ * free — per node: `OS` (→ platform), `Online`/`LastSeen` (→ reachability),
+ * `Relay` vs `CurAddr` (→ direct-vs-relayed latency hint), `DNSName`, and
+ * `TailscaleIPs`. `parseTailscaleStatus` turns that JSON into draft device
+ * profiles so `agents devices sync` can self-populate instead of you
+ * hand-entering hosts. Kept a pure function (JSON in, profiles out) so it is
+ * unit-testable without a live tailnet.
+ */
+import { spawnSync } from 'child_process';
+import { platformFromOs, } from './registry.js';
+/** Strip MagicDNS's trailing dot so the name is usable as an ssh HostName. */
+function trimDnsDot(dns) {
+    if (!dns)
+        return undefined;
+    return dns.endsWith('.') ? dns.slice(0, -1) : dns;
+}
+/** First IPv4 in the node's address list (preferred over IPv6 for ssh). */
+function firstIpv4(ips) {
+    if (!ips)
+        return undefined;
+    return ips.find((ip) => /^\d{1,3}(\.\d{1,3}){3}$/.test(ip)) ?? ips[0];
+}
+/**
+ * Slugify a raw Tailscale HostName into a valid logical device name (ssh alias
+ * charset). Used only as a fallback — when a node has a DNSName we prefer its
+ * first label, which is the canonical slug Tailscale itself derived.
+ */
+export function slugifyHostName(hostName) {
+    return hostName
+        .toLowerCase()
+        .replace(/['’"]/g, '') // drop quotes/apostrophes (so "Bisma's" → "bismas", matching MagicDNS)
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * The logical name for a node. macOS computer names contain spaces and
+ * apostrophes ("Bisma's MacBook Pro") and iOS devices all report HostName
+ * "localhost" — both break as ssh aliases and the latter collides in the
+ * registry. The MagicDNS label (first segment of DNSName) is already a unique,
+ * valid slug per device, so prefer it; fall back to a slugified HostName.
+ */
+function deviceNameFor(raw, dnsName) {
+    const label = dnsName?.split('.')[0];
+    if (label && label.length > 0)
+        return label;
+    const host = raw.HostName?.trim();
+    if (!host)
+        return null;
+    const slug = slugifyHostName(host);
+    return slug.length > 0 ? slug : null;
+}
+function toNode(raw) {
+    const dnsName = trimDnsDot(raw.DNSName);
+    const name = deviceNameFor(raw, dnsName);
+    if (!name)
+        return null;
+    // A non-empty CurAddr means the last handshake was a direct connection;
+    // an empty CurAddr with a Relay means traffic is going through DERP.
+    const direct = Boolean(raw.CurAddr && raw.CurAddr.length > 0);
+    return {
+        name,
+        platform: platformFromOs(raw.OS),
+        dnsName,
+        ip: firstIpv4(raw.TailscaleIPs),
+        online: Boolean(raw.Online),
+        direct,
+        relay: raw.Relay || undefined,
+        lastSeen: raw.LastSeen,
+    };
+}
+/**
+ * Parse `tailscale status --json` output into one node per tailnet device,
+ * including Self. Throws on malformed JSON. Nodes without a HostName are
+ * skipped (they cannot be addressed by a logical name).
+ */
+export function parseTailscaleStatus(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (err) {
+        throw new Error(`Could not parse tailscale status JSON: ${err?.message ?? err}`);
+    }
+    const out = [];
+    if (parsed.Self) {
+        const self = toNode(parsed.Self);
+        if (self)
+            out.push(self);
+    }
+    for (const raw of Object.values(parsed.Peer ?? {})) {
+        const node = toNode(raw);
+        if (node)
+            out.push(node);
+    }
+    return out;
+}
+/** Turn a parsed Tailscale node into the registry fields it can populate. */
+export function nodeToDeviceInput(node) {
+    return {
+        platform: node.platform,
+        address: { via: 'tailscale', dnsName: node.dnsName, ip: node.ip },
+        tailscale: {
+            online: node.online,
+            direct: node.direct,
+            relay: node.relay,
+            lastSeen: node.lastSeen,
+        },
+    };
+}
+/**
+ * Run `tailscale status --json` and return its raw stdout. Throws a clear
+ * error when the binary is missing or the daemon is not reachable.
+ */
+export function tailscaleStatusJson() {
+    const res = spawnSync('tailscale', ['status', '--json'], { encoding: 'utf-8' });
+    if (res.error && res.error.code === 'ENOENT') {
+        throw new Error('tailscale not found on PATH. Install Tailscale, or add devices manually with `agents devices add`.');
+    }
+    if (res.status !== 0) {
+        throw new Error(`tailscale status failed: ${(res.stderr || res.stdout || '').trim() || `exit ${res.status}`}`);
+    }
+    return res.stdout ?? '';
+}

package/dist/lib/doctor-diff.d.ts

@@ -20,6 +20,7 @@
  *     against the compiled artifact, not the raw source file.
  */
 import type { AgentId } from './types.js';
+import type { DiscoveredPlugin } from './types.js';
 export type DoctorKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'permissions' | 'subagents' | 'plugins' | 'promptcuts';
 export type DiffStatus = 'ok' | 'diff' | 'missing' | 'extra';
 export type SourceLayer = 'project' | 'user' | 'system' | 'extra';
@@ -32,6 +33,9 @@ export interface ResourceDiff {
     sourcePath?: string;
     /** Absolute path to the file/dir inside the version home (when present). */
     homePath?: string;
+    /** Human-readable specifics for a divergent row — e.g. for a stale plugin:
+     *  "0.6.1→0.7.0, missing skills: ship, learn". Currently set for plugins. */
+    detail?: string;
 }
 export interface VersionResourceReport {
     agent: AgentId;
@@ -55,6 +59,14 @@ export interface VersionResourceReport {
         extra: number;
     };
 }
+/**
+ * Describe how a version's marketplace MIRROR of a plugin diverges from its
+ * central source — the detail presence-only checks miss. Surfaces a stale mirror
+ * version, a Claude-invalid manifest, and (the part users care about) the
+ * plugin's own skills/commands that never made it into the mirror. Returns null
+ * when the mirror faithfully matches source.
+ */
+export declare function describePluginDrift(central: DiscoveredPlugin, mirrorDir: string): string | null;
 export interface DiffOptions {
     cwd?: string;
     /** Restrict to specific kinds; undefined = all. */

package/dist/lib/doctor-diff.js

@@ -23,7 +23,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, agentConfigDirName } from './agents.js';
 import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getEffectivePromptcutsPath, } from './state.js';
-import { getAvailableResources, getActuallySyncedResources, getVersionHomePath, } from './versions.js';
+import { getAvailableResources, getActuallySyncedResources, getVersionHomePath, compareVersions, } from './versions.js';
+import { discoverPlugins, marketplaceSpecForName } from './plugins.js';
+import { pluginInstallDir, repairableManifestFields } from './plugin-marketplace.js';
 import { markdownToToml } from './convert.js';
 import { resolveImports, supportsRulesImports } from './rules/compile.js';
 import { listCommandsInVersionHome, getVersionCommandsDir } from './commands.js';
@@ -425,6 +427,91 @@ function diffPresenceOnly(kind, available, synced) {
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
+// ─── plugins (content-aware) ───────────────────────────────────────────────
+function listPluginSkillDirs(pluginDir) {
+    const d = path.join(pluginDir, 'skills');
+    try {
+        return fs.readdirSync(d, { withFileTypes: true })
+            .filter((e) => (e.isDirectory() || e.isSymbolicLink()) && fs.existsSync(path.join(d, e.name, 'SKILL.md')))
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+function listPluginCommandFiles(pluginDir) {
+    const d = path.join(pluginDir, 'commands');
+    try {
+        return fs.readdirSync(d).filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, ''));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Describe how a version's marketplace MIRROR of a plugin diverges from its
+ * central source — the detail presence-only checks miss. Surfaces a stale mirror
+ * version, a Claude-invalid manifest, and (the part users care about) the
+ * plugin's own skills/commands that never made it into the mirror. Returns null
+ * when the mirror faithfully matches source.
+ */
+export function describePluginDrift(central, mirrorDir) {
+    if (!fs.existsSync(mirrorDir))
+        return 'mirror missing';
+    const parts = [];
+    let mManifest = null;
+    try {
+        mManifest = JSON.parse(fs.readFileSync(path.join(mirrorDir, '.claude-plugin', 'plugin.json'), 'utf-8'));
+    }
+    catch {
+        mManifest = null;
+    }
+    const mVer = mManifest && typeof mManifest.version === 'string' ? mManifest.version : undefined;
+    const cVer = central.manifest.version;
+    if (mVer && cVer && compareVersions(cVer, mVer) > 0)
+        parts.push(`${mVer}→${cVer}`);
+    if (mManifest && repairableManifestFields(mManifest).length > 0)
+        parts.push('invalid manifest');
+    const mirrorSkills = new Set(listPluginSkillDirs(mirrorDir));
+    const missSkills = listPluginSkillDirs(central.root).filter((s) => !mirrorSkills.has(s)).sort();
+    const mirrorCmds = new Set(listPluginCommandFiles(mirrorDir));
+    const missCmds = listPluginCommandFiles(central.root).filter((c) => !mirrorCmds.has(c)).sort();
+    if (missSkills.length)
+        parts.push(`missing skill${missSkills.length > 1 ? 's' : ''}: ${missSkills.join(', ')}`);
+    if (missCmds.length)
+        parts.push(`missing command${missCmds.length > 1 ? 's' : ''}: ${missCmds.join(', ')}`);
+    return parts.length ? parts.join(', ') : null;
+}
+function diffPlugins(agent, version, cwd) {
+    const versionHome = getVersionHomePath(agent, version);
+    const synced = new Set(getActuallySyncedResources(agent, version, { cwd }).plugins);
+    const rows = [];
+    const seen = new Set();
+    for (const p of discoverPlugins({ cwd })) {
+        if (seen.has(p.name))
+            continue; // dedupe across marketplaces for the readout
+        seen.add(p.name);
+        if (!synced.has(p.name)) {
+            rows.push({ kind: 'plugins', name: p.name, status: 'missing', sourcePath: p.root });
+            continue;
+        }
+        const mirror = pluginInstallDir(p, marketplaceSpecForName(p.marketplace), agent, versionHome);
+        const detail = describePluginDrift(p, mirror);
+        rows.push({
+            kind: 'plugins',
+            name: p.name,
+            status: detail ? 'diff' : 'ok',
+            sourcePath: p.root,
+            homePath: mirror,
+            ...(detail ? { detail } : {}),
+        });
+    }
+    for (const name of synced) {
+        if (!seen.has(name))
+            rows.push({ kind: 'plugins', name, status: 'extra' });
+    }
+    return rows.sort((a, b) => a.name.localeCompare(b.name));
+}
 function diffPromptcuts() {
     const sourcePath = getEffectivePromptcutsPath();
     if (!fs.existsSync(sourcePath))
@@ -468,7 +555,7 @@ export function diffVersionResources(agent, version, options = {}) {
     if (requested.has('subagents'))
         empty.subagents = diffPresenceOnly('subagents', available.subagents, synced.subagents);
     if (requested.has('plugins'))
-        empty.plugins = diffPresenceOnly('plugins', available.plugins, synced.plugins);
+        empty.plugins = diffPlugins(agent, version, cwd);
     if (requested.has('promptcuts'))
         empty.promptcuts = diffPromptcuts();
     let ok = 0, diff = 0, missing = 0, extra = 0;

package/dist/lib/exec.d.ts

@@ -80,6 +80,14 @@ export interface ExecOptions {
     addDirs?: string[];
     timeout?: string;
     sessionId?: string;
+    /**
+     * Resume the conversation named by `sessionId` using the agent's NATIVE resume
+     * form (claude `--resume`, codex `resume`) instead of the default `--session-id`
+     * create. Only set for agents where `nativeResume` returns true; other agents
+     * resume via a `/continue <id>` first message (Tier 2), which needs no flag and
+     * leaves this unset.
+     */
+    resume?: boolean;
     verbose?: boolean;
     env?: Record<string, string>;
     /**
@@ -150,6 +158,19 @@ export interface AgentCommandTemplate {
     modelFlag?: string;
     printFlags?: string[];
     verboseFlag?: string;
+    /**
+     * How this agent natively resumes a prior conversation. Presence here is the
+     * single source of truth for `nativeResume(agent)` — agents without it fall
+     * back to the universal `/continue <id>` replay (Tier 2). Two shapes:
+     *   { flag }       — append `<flag> <id>` (e.g. claude `--resume <id>`)
+     *   { subcommand } — replace the headless base subcommand with `<subcommand> <id>`
+     *                    (codex: `codex exec` -> `codex exec resume <id>`)
+     */
+    resume?: {
+        flag: string;
+    } | {
+        subcommand: string;
+    };
 }
 /**
  * CLI command templates for every supported agent.
@@ -158,6 +179,12 @@ export interface AgentCommandTemplate {
  * AGENTS[agent].capabilities.modes. A test in exec.test.ts asserts this.
  */
 export declare const AGENT_COMMANDS: Record<AgentId, AgentCommandTemplate>;
+/**
+ * Whether `agent` has a native resume form (Tier 1). Derived solely from the
+ * command template's `resume` field — the single source of truth. Agents that
+ * return false resume via the universal Tier-2 `/continue` replay instead.
+ */
+export declare function nativeResume(agent: AgentId): boolean;
 /** Assemble the full CLI argument array for an agent invocation. */
 export declare function buildExecCommand(options: ExecOptions): string[];
 /** Spawn an agent and return its exit code. Convenience wrapper over spawnAgent. */