@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/commands/monitors.js

@@ -12,9 +12,12 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { isDaemonRunning, signalDaemonReload, startDaemon, } from '../lib/daemon.js';
-import { listMonitors, readMonitor, writeMonitor, deleteMonitor, setMonitorEnabled, getMonitorPath, validateMonitor, monitorRunsOnThisDevice, } from '../lib/monitors/config.js';
-import { evaluateMonitorOnce } from '../lib/monitors/engine.js';
-import { listFires, readState } from '../lib/monitors/state.js';
+import { findDuplicateMonitor, monitorFingerprint } from '../lib/monitors/fingerprint.js';
+import { gatherFleetMonitors, NO_MONITOR_FANOUT_ENV } from '../lib/monitors/remote.js';
+import { listMonitors, readMonitor, writeMonitor, deleteMonitor, setMonitorEnabled, getMonitorPath, validateMonitor, monitorRunsOnThisDevice, parseInterval, } from '../lib/monitors/config.js';
+import { formatRelativeTime } from '../lib/session/relative-time.js';
+import { evaluateMonitorOnce, POLL_SOURCE_TYPES } from '../lib/monitors/engine.js';
+import { listFires, readState, readLiveness } from '../lib/monitors/state.js';
 import { listRuns, getLatestRun, getRunDir } from '../lib/routines.js';
 import { getMonitorsDir } from '../lib/state.js';
 import { IS_WINDOWS } from '../lib/platform/index.js';
@@ -72,6 +75,54 @@ function ownerLabel(monitor) {
         return monitor.devices.join(',');
     return 'all';
 }
+/** A monitor's evaluation cadence in ms (falls back to the engine default). */
+function monitorIntervalMs(monitor) {
+    if (monitor.source.interval)
+        return parseInterval(monitor.source.interval) ?? 60_000;
+    return 60_000;
+}
+/**
+ * True when an enabled, locally-owned monitor's last poll is far enough past its
+ * interval that the engine has plainly stopped checking it (dead engine, swallowed
+ * start failure, never picked up). Tolerates a few missed ticks before flagging.
+ */
+function isStalled(monitor, liveness) {
+    if (!monitor.enabled || !monitorRunsOnThisDevice(monitor))
+        return false;
+    if (!liveness)
+        return false; // "never polled" is its own state, handled separately
+    const staleAfter = Math.max(monitorIntervalMs(monitor) * 3, 90_000);
+    return Date.now() - new Date(liveness.lastCheckedAt).getTime() > staleAfter;
+}
+/**
+ * The human liveness line for a monitor. This is the RUSH-2485 fix: it makes
+ * "the engine has never touched this" (`never polled`) visibly distinct from
+ * "polling steadily, condition just isn't matching" (`checked Nx`), from a real
+ * fire, and from a stalled engine.
+ */
+function livenessLabel(monitor, state, liveness) {
+    const here = monitorRunsOnThisDevice(monitor);
+    if (!monitor.enabled)
+        return chalk.gray('paused');
+    if (!here) {
+        // Not owned by this box — this daemon never checks it, so there's no local
+        // liveness to report; fall back to fire history if the owner synced it.
+        return state?.lastFiredAt ? chalk.gray(`fired ${formatRelativeTime(state.lastFiredAt)}`) : chalk.gray('owned elsewhere');
+    }
+    if (!liveness)
+        return chalk.yellow('never polled');
+    if (isStalled(monitor, liveness)) {
+        return chalk.red(`STALLED — last poll ${formatRelativeTime(liveness.lastCheckedAt)}`);
+    }
+    const checkedAgo = formatRelativeTime(liveness.lastCheckedAt);
+    if (liveness.lastError) {
+        return chalk.red(`checked ${liveness.checkCount}x · error: ${liveness.lastError.replace(/\s+/g, ' ').slice(0, 60)}`);
+    }
+    if (state?.lastFiredAt) {
+        return chalk.green(`fired ${formatRelativeTime(state.lastFiredAt)}`) + chalk.gray(` · checked ${liveness.checkCount}x`);
+    }
+    return chalk.gray(`checked ${liveness.checkCount}x · last ${checkedAgo} · no match yet`);
+}
 /** Start or reload the background daemon so a newly-added monitor is watched. */
 function ensureDaemonRunning() {
     if (isDaemonRunning()) {
@@ -88,6 +139,37 @@ function ensureDaemonRunning() {
         stderrLine(chalk.yellow('Could not start the daemon. Start it manually with: agents routines start'));
     }
 }
+/**
+ * Assert the postcondition of `add`: the engine actually picked the monitor up.
+ * Config acceptance is not enough — RUSH-2485 was a monitor that added cleanly,
+ * listed as `on`, and never polled. A poll-model monitor owned by and enabled on
+ * this box should show a liveness heartbeat within a couple of engine ticks; wait
+ * for it and report the real outcome instead of reporting success on write. A
+ * miss is a warning, not a hard failure — a freshly-started daemon may still be
+ * booting — but it is surfaced so a dead engine can never masquerade as healthy.
+ */
+async function assertEnginePickup(monitor) {
+    const pollSource = POLL_SOURCE_TYPES.has(monitor.source.type);
+    if (!monitor.enabled || !monitorRunsOnThisDevice(monitor) || !pollSource)
+        return; // nothing to assert here
+    const before = readLiveness(monitor.name);
+    const baseline = before?.checkCount ?? 0;
+    const deadline = Date.now() + 12_000; // a couple of 5s ticks, plus daemon-boot slack
+    stderrLine(chalk.gray('  waiting for the engine to poll it…'));
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 500));
+        const now = readLiveness(monitor.name);
+        if (now && now.checkCount > baseline) {
+            console.log(chalk.green(`  engine picked it up — first poll ${formatRelativeTime(now.lastCheckedAt)}`));
+            if (now.lastError) {
+                stderrLine(chalk.yellow(`  note: that poll errored — ${now.lastError.replace(/\s+/g, ' ').slice(0, 80)}`));
+            }
+            return;
+        }
+    }
+    stderrLine(chalk.yellow(`  the engine has not polled '${monitor.name}' yet.`));
+    stderrLine(chalk.yellow(`  confirm the daemon is running (agents routines status) and re-check with: agents monitors view ${monitor.name}`));
+}
 /** Validate a single device name against the registered fleet; exit on miss. */
 async function validateDevice(name) {
     const normalized = normalizeHost(name.trim());
@@ -242,6 +324,58 @@ async function pickMonitor(message, alternatives = []) {
     }
 }
 /** Register the `agents monitors` command tree. */
+/**
+ * Refuse a monitor that duplicates one already in play — same NAME (which
+ * `writeMonitor` would silently overwrite) or same BEHAVIOR under any name, on
+ * this box or any other. Exits the process on a refusal.
+ *
+ * Shared by BOTH `add` paths. The file path (`add ./watcher.yml`) returns early
+ * and used to skip the guard entirely, so a duplicate could be walked straight
+ * in through a YAML file — the one input an agent is most likely to generate.
+ */
+async function guardAgainstDuplicateMonitor(config, force) {
+    if (force)
+        return;
+    const existing = listMonitors();
+    const sameName = existing.find((m) => m.name === config.name);
+    if (sameName) {
+        stderrLine(chalk.red(`Monitor '${config.name}' already exists — adding would overwrite it.`));
+        stderrLine(chalk.gray(`  Inspect it:   agents monitors view ${config.name}`));
+        stderrLine(chalk.gray(`  Replace it:   agents monitors add ${config.name} ... --force`));
+        process.exit(1);
+    }
+    const duplicate = findDuplicateMonitor(config, existing);
+    if (duplicate) {
+        stderrLine(chalk.red(`Monitor '${duplicate}' already watches this exact source and fires the same action.`));
+        stderrLine(chalk.gray('  Adding it again would fire the same trigger twice.'));
+        stderrLine(chalk.gray(`  Inspect it:   agents monitors view ${duplicate}`));
+        stderrLine(chalk.gray(`  Add anyway:   agents monitors add ${config.name} ... --force`));
+        process.exit(1);
+    }
+    // The case a local check cannot see: another agent, on another box, already
+    // watching this same work item with these same arguments. One work item, two
+    // triggers. Identity is the arguments, so the claim has to be fleet-wide —
+    // different arguments (another PR) are not a clash and still pass.
+    if (process.env[NO_MONITOR_FANOUT_ENV])
+        return;
+    const fleet = await gatherFleetMonitors();
+    const mine = monitorFingerprint(config);
+    const clash = fleet.monitors.find((r) => monitorFingerprint(r.monitor) === mine);
+    if (clash) {
+        stderrLine(chalk.red(`Monitor '${clash.monitor.name}' on ${chalk.bold(clash.machine)} already watches this exact source and fires the same action.`));
+        stderrLine(chalk.gray('  Two boxes watching one work item is a double trigger.'));
+        stderrLine(chalk.gray(`  Inspect it:   agents ssh ${clash.machine} 'agents monitors view ${clash.monitor.name}'`));
+        stderrLine(chalk.gray(`  Add anyway:   agents monitors add ${config.name} ... --force`));
+        process.exit(1);
+    }
+    // Never treat "could not ask" as "no duplicate".
+    if (fleet.discoveryFailed) {
+        stderrLine(chalk.yellow('  Note: could not reach the device registry — the fleet was not checked for duplicates.'));
+    }
+    else if (fleet.skipped.length > 0) {
+        stderrLine(chalk.yellow(`  Note: could not check ${fleet.skipped.join(', ')} — a duplicate there would not have been caught.`));
+    }
+}
 export function registerMonitorsCommands(program) {
     const monitorsCmd = program
         .command('monitors')
@@ -315,11 +449,12 @@ export function registerMonitorsCommands(program) {
         .option('--notify [channel]', 'Notify the owner (notify.owner); [channel] overrides the owner channel')
         .option('--webhook-out <url>', 'POST the event to this URL')
         // PLACEMENT / hygiene
-        .option('--device <name>', 'OWNER (not body placement) — the single machine that evaluates + fires (exactly-once). See docs/00-concepts.md#placement.')
+        .option('--device <name>', 'OWNER (not body placement) — the single machine that evaluates + fires (exactly-once). See docs/concepts.md#placement.')
         .option('--devices <list>', 'Allowlist (comma-separated): each device fires independently')
         .option('--run-on <host>', 'BODY placement — execute the ACTION on this machine over SSH (same idea as run --where device:<host>)')
         .option('--rate-limit <spec>', 'Auto-pause if it fires more than N/<interval> (e.g. 5/1m)')
         .option('--disabled', 'Create the monitor paused (enable later with resume)')
+        .option('--force', 'Overwrite a same-named monitor, or add one that duplicates an existing watcher')
         .action(async (nameOrPath, options) => {
         // File mode: a single arg pointing at an existing .yml with no source flags.
         const hasSourceFlag = Boolean(options.watch || options.poll || options.pollHttp || options.on || options.ws || options.watchFile || options.watchDevice);
@@ -342,9 +477,11 @@ export function registerMonitorsCommands(program) {
                     stderrLine(chalk.red(`  - ${err}`));
                 process.exit(1);
             }
+            await guardAgainstDuplicateMonitor(config, options.force === true);
             writeMonitor(config);
             console.log(chalk.green(`Monitor '${name}' added`));
             ensureDaemonRunning();
+            await assertEnginePickup(config);
             return;
         }
         if (!nameOrPath) {
@@ -413,10 +550,12 @@ export function registerMonitorsCommands(program) {
         if (condition.mode === 'match' && condition.match && /^(issued|success|ok|pass(ed)?|done|ready)$/i.test(condition.match)) {
             stderrLine(chalk.yellow(`  Note: --match '${condition.match}' only fires on success — it stays silent if the source breaks or never matches.`));
         }
+        await guardAgainstDuplicateMonitor(config, options.force === true);
         writeMonitor(config);
         console.log(chalk.green(`Monitor '${nameOrPath}' added`));
         console.log(chalk.gray(`  ${sourceLabel(source)} → [${condition.mode}] → ${actionLabel(action)} · owner: ${ownerLabel(config)}`));
         ensureDaemonRunning();
+        await assertEnginePickup(config);
     });
     // ─── list ────────────────────────────────────────────────────────────────────
     monitorsCmd
@@ -428,16 +567,28 @@ export function registerMonitorsCommands(program) {
         if (options.json) {
             const payload = monitors.map((m) => {
                 const state = readState(m.name);
+                const liveness = readLiveness(m.name);
                 return {
                     name: m.name,
                     enabled: m.enabled,
                     source: m.source,
                     condition: m.condition,
-                    action: { type: m.action.type },
+                    // Full action, not just `type`: the cross-machine duplicate guard
+                    // fingerprints source+condition+action, so a type-only action made
+                    // every `--run` monitor unmatchable and the fleet check inert for
+                    // exactly the case it exists for. `source` already ships whole.
+                    action: m.action,
                     owner: ownerLabel(m),
                     runsHere: monitorRunsOnThisDevice(m),
                     lastSeenAt: state?.lastSeenAt ?? null,
                     lastFiredAt: state?.lastFiredAt ?? null,
+                    // Liveness heartbeat (RUSH-2485): distinguishes never-polled from
+                    // polling-not-matching from a stalled engine.
+                    lastCheckedAt: liveness?.lastCheckedAt ?? null,
+                    checkCount: liveness?.checkCount ?? 0,
+                    lastError: liveness?.lastError ?? null,
+                    consecutiveErrors: liveness?.consecutiveErrors ?? 0,
+                    stalled: isStalled(m, liveness),
                 };
             });
             stdoutJson(payload);
@@ -451,12 +602,12 @@ export function registerMonitorsCommands(program) {
         console.log(chalk.bold('Monitors\n'));
         for (const m of monitors) {
             const state = readState(m.name);
+            const liveness = readLiveness(m.name);
             const enabled = m.enabled ? chalk.green('on') : chalk.gray('off');
             const here = monitorRunsOnThisDevice(m);
             const owner = here ? ownerLabel(m) : chalk.gray(ownerLabel(m));
-            const lastFired = state?.lastFiredAt ? `fired ${state.lastFiredAt}` : chalk.gray('never fired');
             console.log(`  ${chalk.cyan(m.name.padEnd(22))} ${enabled.padEnd(3)} ${sourceLabel(m.source)}`);
-            console.log(`  ${' '.repeat(22)}     ${chalk.gray(`[${m.condition.mode}]`)} → ${actionLabel(m.action)}  ${chalk.gray(`owner: ${owner}`)}  ${chalk.gray(lastFired)}`);
+            console.log(`  ${' '.repeat(22)}     ${chalk.gray(`[${m.condition.mode}]`)} → ${actionLabel(m.action)}  ${chalk.gray(`owner: ${owner}`)}  ${livenessLabel(m, state, liveness)}`);
         }
         console.log();
     });
@@ -477,6 +628,7 @@ export function registerMonitorsCommands(program) {
             process.exit(1);
         }
         const state = readState(name);
+        const liveness = readLiveness(name);
         const recentFires = listFires(name).slice(-5);
         if (options.json) {
             stdoutJson({
@@ -485,14 +637,30 @@ export function registerMonitorsCommands(program) {
                 owner: ownerLabel(monitor),
                 runsHere: monitorRunsOnThisDevice(monitor),
                 state,
+                liveness,
+                stalled: isStalled(monitor, liveness),
                 recentFires,
             });
             return;
         }
         console.log(chalk.bold(`Monitor: ${name}\n`));
         console.log(yaml.stringify(monitor));
+        // Liveness first (RUSH-2485): the heartbeat is the answer to "is this thing
+        // actually running?" — it renders even when the monitor has never fired.
+        console.log(chalk.bold('Liveness'));
+        console.log(`  ${livenessLabel(monitor, state, liveness)}`);
+        if (liveness) {
+            console.log(chalk.gray(`  last checked: ${liveness.lastCheckedAt} (${formatRelativeTime(liveness.lastCheckedAt)})`));
+            console.log(chalk.gray(`  checks:       ${liveness.checkCount}`));
+            if (liveness.lastError) {
+                console.log(chalk.red(`  last error:   ${liveness.lastError.replace(/\s+/g, ' ').slice(0, 200)} (${liveness.consecutiveErrors} in a row)`));
+            }
+        }
+        else if (monitor.enabled && monitorRunsOnThisDevice(monitor)) {
+            console.log(chalk.yellow('  The engine has not polled this monitor yet. If this persists, the daemon may not have picked it up — check: agents routines status'));
+        }
         if (state) {
-            console.log(chalk.bold('Watched state'));
+            console.log(chalk.bold('\nWatched state'));
             console.log(chalk.gray(`  last seen:  ${state.lastSeenAt}`));
             if (state.lastFiredAt)
                 console.log(chalk.gray(`  last fired: ${state.lastFiredAt}`));
@@ -566,19 +734,29 @@ export function registerMonitorsCommands(program) {
             if (!name)
                 return;
         }
+        // getMonitorPath is user-layer only: edits always land in the user dir,
+        // never the pull-only system mirror. Editing a system built-in (no user
+        // copy yet) materializes one, prefilled with the built-in's own config.
         let monitorPath = getMonitorPath(name);
         if (!monitorPath) {
             const dir = getMonitorsDir();
             fs.mkdirSync(dir, { recursive: true });
             monitorPath = safeJoin(dir, `${name}.yml`);
-            const template = yaml.stringify({
-                name,
-                source: { type: 'poll', command: 'echo hello', interval: '1m' },
-                condition: { mode: 'on-change' },
-                action: { type: 'notify' },
-            });
-            fs.writeFileSync(monitorPath, template, 'utf-8');
-            console.log(chalk.gray(`Created new monitor file: ${monitorPath}`));
+            const builtIn = readMonitor(name);
+            if (builtIn) {
+                fs.writeFileSync(monitorPath, yaml.stringify(builtIn), 'utf-8');
+                console.log(chalk.gray(`Editing a copy of built-in monitor '${name}' in your user dir: ${monitorPath}`));
+            }
+            else {
+                const template = yaml.stringify({
+                    name,
+                    source: { type: 'poll', command: 'echo hello', interval: '1m' },
+                    condition: { mode: 'on-change' },
+                    action: { type: 'notify' },
+                });
+                fs.writeFileSync(monitorPath, template, 'utf-8');
+                console.log(chalk.gray(`Created new monitor file: ${monitorPath}`));
+            }
         }
         const editor = process.env.EDITOR || process.env.VISUAL || (IS_WINDOWS ? 'notepad' : 'vi');
         const parts = editor.split(/\s+/).filter(Boolean);
@@ -772,6 +950,11 @@ export function registerMonitorsCommands(program) {
                 stderrLine(chalk.gray('Daemon reloaded'));
             }
         }
+        else if (readMonitor(name)) {
+            // Resolvable but not in the user dir: a pull-only system built-in.
+            stderrLine(chalk.red(`Monitor '${name}' is a built-in and can't be removed; pause it with: agents monitors pause ${name}`));
+            process.exit(1);
+        }
         else {
             stderrLine(chalk.red(`Monitor '${name}' not found`));
             process.exit(1);

package/dist/commands/open.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `agents open` — resolve an `agents://` deep link, and manage the OS handler
+ * that routes such links here.
+ *
+ *   agents open agents://session/<id>     resume that session in a terminal
+ *   agents open register                  register the agents:// scheme with the OS
+ *   agents open unregister                remove the handler
+ *   agents open status                    report whether the handler is registered
+ *
+ * A rendered artifact (plan/report) embeds `agents://session/<id>` in its
+ * provenance line; clicking it hands the URL to the OS, which invokes
+ * `agents open <url>`. This command parses it (lib/deeplink/url.ts) and hands the
+ * session id to the existing resume dispatcher, which resolves the owning host
+ * and opens the terminal with the cursor in the input bar. The id is passed as
+ * argv, never interpolated into a shell.
+ */
+import type { Command } from 'commander';
+export declare function registerOpenCommand(program: Command): void;

package/dist/commands/open.js

@@ -0,0 +1,57 @@
+import chalk from 'chalk';
+import { parseAgentsUrl } from '../lib/deeplink/url.js';
+import { registerAgentsUrlScheme, unregisterAgentsUrlScheme, agentsUrlSchemeStatus, } from '../lib/deeplink/register.js';
+export function registerOpenCommand(program) {
+    const open = program
+        .command('open [url]')
+        .description('Resume a session from an agents:// deep link, or register/unregister/status the OS URL-scheme handler.')
+        .action(async (url) => {
+        if (!url) {
+            open.help();
+            return;
+        }
+        await handleUrl(url);
+    });
+    open
+        .command('register')
+        .description('Register the agents:// URL scheme with the OS so artifact links resume sessions (idempotent).')
+        .action(() => {
+        const status = registerAgentsUrlScheme();
+        if (status.registered) {
+            console.log(chalk.green('agents:// scheme registered.') + chalk.gray(` ${status.detail}`));
+        }
+        else {
+            console.log(chalk.yellow('Could not register the agents:// scheme.') + chalk.gray(` ${status.detail}`));
+            process.exitCode = 1;
+        }
+    });
+    open
+        .command('unregister')
+        .description('Remove the agents:// URL scheme handler.')
+        .action(() => {
+        const status = unregisterAgentsUrlScheme();
+        console.log(chalk.gray(status.detail));
+    });
+    open
+        .command('status')
+        .description('Report whether the agents:// URL scheme handler is registered.')
+        .action(() => {
+        const status = agentsUrlSchemeStatus();
+        const label = status.registered ? chalk.green('registered') : chalk.yellow('not registered');
+        console.log(`agents:// handler: ${label} ${chalk.gray(`(${status.platform})`)}`);
+        console.log(chalk.gray(`  ${status.detail}`));
+        if (!status.registered)
+            process.exitCode = 1;
+    });
+}
+async function handleUrl(url) {
+    const parsed = parseAgentsUrl(url);
+    if ('error' in parsed) {
+        console.error(chalk.red(`Not a valid agents:// link: ${parsed.error}`));
+        process.exitCode = 2;
+        return;
+    }
+    // Lazy-import the resume dispatcher so `register`/`status` stay cold-start cheap.
+    const { dispatchSessionLifecycleInPlace } = await import('./sessions-resume.js');
+    await dispatchSessionLifecycleInPlace(parsed.id, parsed.host ? [parsed.host] : []);
+}

package/dist/commands/packages.js

@@ -6,15 +6,13 @@
  * hooks from configured registries or GitHub sources.
  */
 import * as fs from 'fs';
-import * as path from 'path';
 import chalk from 'chalk';
 import ora from 'ora';
-import { getAgentsDir, getEnabledExtraRepos } from '../lib/state.js';
 import { AGENTS, getAllCliStates, agentLabel, } from '../lib/agents.js';
 import { capableAgents } from '../lib/capabilities.js';
 import { DEFAULT_REGISTRIES } from '../lib/types.js';
-import { getRegistries, setRegistry, removeRegistry, search as searchRegistries, resolvePackage, validatedNpmSpec, validatedPyPISpec, buildSkillIndex, verifySkillIntegrity, parseOwnerRepoFromRemote, } from '../lib/registry.js';
-import { cloneRepo, commitAndPush, getCurrentBranch, getRemoteUrl, isGitRepo } from '../lib/git.js';
+import { getRegistries, setRegistry, removeRegistry, search as searchRegistries, resolvePackage, validatedNpmSpec, validatedPyPISpec, verifySkillIntegrity, } from '../lib/registry.js';
+import { cloneRepo } from '../lib/git.js';
 import { discoverCommands, resolveCommandSource, installCommand, installCommandCentrally, } from '../lib/commands.js';
 import { discoverSkillsFromRepo, installSkill, installSkillCentrally, } from '../lib/skills.js';
 import { discoverHooksFromRepo, installHooks, installHooksCentrally, } from '../lib/hooks.js';
@@ -328,109 +326,6 @@ When to use:
         }
     });
     // ==========================================================================
-    // PUBLISH COMMAND (self-hosted, git-index skill registry)
-    // ==========================================================================
-    program
-        .command('publish')
-        .description('Generate a skills-index.json for a git repo and push it, making its skills discoverable via agents search/install')
-        .option('--repo <alias>', 'Publish an extra repo added via `agents repo add` (default: your ~/.agents repo)')
-        .option('--name <name>', 'Registry name to suggest in the output (default: the repo name)')
-        .option('--branch <branch>', 'Branch to push the index to and reference in the raw URL (default: the repo\'s current branch)')
-        .option('--dry-run', 'Write the index and print the URL without committing or pushing')
-        .addHelpText('after', `
-Publish walks a repo's skills/ directory, records a sha256 of every SKILL.md,
-and writes skills-index.json at the repo root — a flat index that 'agents search'
-and 'agents install' can consume directly from raw.githubusercontent.com. No
-hosted infrastructure: the index is just a file committed to your GitHub repo.
-
-Examples:
-  # Publish your ~/.agents repo's skills
-  agents publish
-
-  # Publish an extra repo added via 'agents repo add'
-  agents publish --repo team-skills
-
-  # Preview the index without pushing
-  agents publish --dry-run
-
-After publishing, share the printed 'agents registry add skill ...' command so
-others can search and install your skills. Installs verify each SKILL.md against
-the sha256 in the index and abort on mismatch.
-`)
-        .action(async (options) => {
-        // Resolve the target repo: an extra repo by alias, else the primary ~/.agents repo.
-        let repoDir;
-        if (options.repo) {
-            const extra = getEnabledExtraRepos().find((r) => r.alias === options.repo);
-            if (!extra) {
-                console.log(chalk.red(`No enabled extra repo aliased '${options.repo}'.`));
-                console.log(chalk.gray('Add one with: agents repo add <source> --as <alias>'));
-                process.exit(1);
-            }
-            repoDir = extra.dir;
-        }
-        else {
-            repoDir = getAgentsDir();
-        }
-        if (!isGitRepo(repoDir)) {
-            console.log(chalk.red(`${repoDir} is not a git repository.`));
-            console.log(chalk.gray('publish commits + pushes the index, so the repo needs a GitHub remote.'));
-            process.exit(1);
-        }
-        const remoteUrl = await getRemoteUrl(repoDir);
-        const repoSlug = remoteUrl ? parseOwnerRepoFromRemote(remoteUrl) : null;
-        if (!repoSlug) {
-            console.log(chalk.red(`Could not resolve an 'owner/repo' from the git remote of ${repoDir}.`));
-            console.log(chalk.gray(`  Remote: ${remoteUrl || '(none)'} — publish needs a GitHub origin.`));
-            process.exit(1);
-        }
-        const spinner = ora('Building skills index...').start();
-        const index = buildSkillIndex(repoDir, repoSlug, { generatedAt: new Date().toISOString() });
-        spinner.stop();
-        if (index.skills.length === 0) {
-            console.log(chalk.yellow(`No skills found under ${repoDir}/skills.`));
-            console.log(chalk.gray('Add a skill (a directory with a SKILL.md) and re-run publish.'));
-            process.exit(1);
-        }
-        const indexPath = path.join(repoDir, 'skills-index.json');
-        fs.writeFileSync(indexPath, JSON.stringify(index, null, 2) + '\n', 'utf-8');
-        console.log(chalk.bold(`\nIndexed ${index.skills.length} skill(s) into skills-index.json:`));
-        for (const s of index.skills) {
-            console.log(`  ${chalk.cyan(s.name)} ${chalk.gray(`sha256:${s.sha256?.slice(0, 12)}…`)}`);
-        }
-        // The branch the URL references must be the branch the index actually
-        // lands on. In a real push that's whatever commitAndPush reports back
-        // (the requested --branch, else the checked-out branch); in a dry run we
-        // resolve it the same way without pushing.
-        let urlBranch;
-        if (options.dryRun) {
-            urlBranch = options.branch || (await getCurrentBranch(repoDir));
-            console.log(chalk.gray(`\nDry run — wrote ${indexPath} but did not commit or push.`));
-        }
-        else {
-            const pushSpinner = ora('Committing and pushing skills-index.json...').start();
-            const result = await commitAndPush(repoDir, 'chore: update skills-index.json (agents publish)', options.branch);
-            if (!result.success) {
-                pushSpinner.fail(`Push failed: ${result.error}`);
-                console.log(chalk.gray('The index was written locally — commit and push it manually to publish.'));
-                process.exit(1);
-            }
-            // commitAndPush always reports the pushed branch on success; the `??`
-            // only satisfies the optional return type, it is not a behavior path.
-            urlBranch = result.branch ?? (await getCurrentBranch(repoDir));
-            pushSpinner.succeed(`Pushed skills-index.json to ${urlBranch}`);
-        }
-        const rawUrl = `https://raw.githubusercontent.com/${repoSlug}/${urlBranch}/skills-index.json`;
-        const registryName = options.name || repoSlug.split('/')[1] || 'my-skills';
-        console.log(chalk.bold('\nPublished. Share these with anyone who wants your skills:\n'));
-        console.log(chalk.gray('  Index URL:'));
-        console.log(`    ${rawUrl}`);
-        console.log(chalk.gray('\n  Register + search + install:'));
-        console.log(`    ${chalk.green(`agents registry add skill ${registryName} ${rawUrl}`)}`);
-        console.log(`    ${chalk.green(`agents search ${index.skills[0].name} --type skill`)}`);
-        console.log(`    ${chalk.green(`agents install skill:${index.skills[0].name} --agents claude,codex,cursor`)}`);
-    });
-    // ==========================================================================
     // INSTALL COMMAND (unified package installation)
     // ==========================================================================
     program

package/dist/commands/plugins.js

@@ -282,10 +282,11 @@ Examples:
         }
         console.log();
     });
-    // agents plugins sync <name> [agent]
+    // Deprecated: superseded by `agents sync --plugin <name>`. Kept as a warned,
+    // functional alias so old muscle-memory and scripts don't break.
     pluginsCmd
-        .command('sync <name> [agent]')
-        .description('Apply a plugin to an agent. Syncs every installed version (pass agent@version to target one).')
+        .command('sync <name> [agent]', { hidden: true })
+        .description('Deprecated — use `agents sync --plugin <name>` instead.')
         .option('--allow-exec-surfaces', 'Enable the plugin even when it ships hooks/, .mcp.json, bin/, scripts/, settings.json, or permissions/')
         .addHelpText('after', `
 Examples:
@@ -302,6 +303,8 @@ Examples:
   agents plugins sync hivemind claude --allow-exec-surfaces
 `)
         .action(async (name, agentArg, options) => {
+        console.warn(chalk.yellow('`agents plugins sync` is deprecated — use `agents sync --plugin` instead:'));
+        console.warn(chalk.gray(`  agents sync --plugin ${name}`));
         const plugin = getPlugin(name);
         if (!plugin) {
             console.log(chalk.red(`Plugin '${name}' not found`));

package/dist/commands/profiles.d.ts

@@ -25,6 +25,7 @@ export interface AddProfileOptions {
     model?: string;
     baseUrl?: string;
     authProvider?: string;
+    account?: string;
     version?: string;
     keyStdin?: boolean;
     force?: boolean;