@phnx-labs/agents-cli 1.20.12 → 1.20.13

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+**Windows: `agents` is discoverable right after `npm i -g`**
+
+- On a global Windows install, postinstall now prepends npm's global-bin dir (where `agents.cmd`/`agents.ps1` live) to the **User PATH** via the .NET environment API. Node's installer normally adds it, but winget / portable / nvm-windows setups often don't — and then `npm i -g @phnx-labs/agents-cli` succeeds yet `agents` is "not recognized". The shims dir (claude/codex/…) is still left to `agents setup`, which the user can now run because `agents` resolves.
+- Postinstall also detects a `Restricted`/`AllSigned` PowerShell execution policy (which blocks the generated `.ps1` launchers, so even an on-PATH `agents` fails in PowerShell) and prints the one-line fix (`Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`). The policy is a security setting, so it is never changed silently — only surfaced.
+- Refactor: the Windows User-PATH prepend logic moved from `shims.ts` into a new `src/lib/platform/winpath.ts` leaf module (`prependToWindowsUserPath`, `getEffectiveExecutionPolicy`, `blocksLocalScripts`, `npmGlobalBinFromEntry`); `addShimsToWindowsUserPath` now delegates to it. Pure helpers are unit-tested.
+
+**Factory AI Droid (first-class support)**
+
+- Add `droid` as a first-class supported agent (AgentId + full registry entry for Factory AI's `droid` CLI, config in `~/.factory/`). Installs via the official script (`curl -fsSL https://app.factory.ai/cli | sh`); the binary is resolved through the standard install-script path and isolated per version via the `~/.factory` config symlink (Droid has no `*_HOME` override).
+- Resource sync wired for the four resource types Droid supports natively: **MCP** (`~/.factory/mcp.json`), **rules** (native `AGENTS.md`), **subagents** (custom droids flattened to `~/.factory/droids/*.md`, with the unsupported `color` frontmatter key stripped), and **commands** (`~/.factory/commands/`). Skills/plugins/workflows have no Droid equivalent and are disabled; hooks/permissions are deferred.
+- `agents run droid` and `agents teams add … droid` work end-to-end: headless `droid exec` with mode mapping (plan → read-only, edit → `--auto low`, auto → `--auto high`, skip → `--skip-permissions-unsafe`), `-o stream-json` output, `-m` model selection, and `-r` reasoning effort. Routine/daemon jobs (`buildJobCommand`) support Droid too.
+- Known limitation: `agents teams` renders Droid events through the generic normalizer pending a verified `droid exec -o stream-json` event schema; structured tool/file categorization will follow. Session reading and Factory cloud dispatch remain follow-ups.
+
 **`agents upgrade` now refreshes the macOS Keychain helper**
 
 - Upgrading runs `npm install -g … --ignore-scripts`, so the postinstall that installs the signed Keychain helper never fired — a user upgrading away from a broken build (e.g. the entitlement-less 1.20.4 helper that failed `SecItemAdd` with `errSecMissingEntitlement -34018`) kept the broken helper until the lazy staleness check in `getKeychainHelperPath()` happened to repair it on their next secret operation. `installResolvedPackage` now force-refreshes the helper (`ensureKeychainHelperInstalled({ forceReinstall: true })`) on darwin after the install, so both the explicit `agents upgrade` and the auto-update prompt land the fixed helper immediately. Best-effort and non-fatal: an upgrade never fails because the helper could not be reinstalled, and `agents helper install --force` remains the manual path.

package/README.md

@@ -29,6 +29,8 @@
   <a href="https://github.com/NousResearch/hermes-agent" title="Hermes Agent"><img src="assets/harnesses/hermes.png" height="32" alt="Hermes Agent" /></a>
   &nbsp;&nbsp;&nbsp;&nbsp;
   <a href="https://x.ai" title="Grok Build (xAI)"><strong>Grok</strong></a>
+  &nbsp;&nbsp;&nbsp;&nbsp;
+  <a href="https://factory.ai" title="Factory AI Droid"><strong>Droid</strong></a>
 </p>
 
 https://agents-cli.sh/demo.mp4
@@ -86,6 +88,7 @@ Think `requirements.txt` for CLI coding agents, on steroids. A shim reads `agent
 ```bash
 agents add claude@2.0.65     # Install a specific version
 agents add codex@latest       # Install latest
+agents add codex@oldest       # Install the oldest published version
 agents view                   # See everything installed
 ```
 

package/dist/commands/computer-actions.d.ts

@@ -35,6 +35,9 @@ export declare function buildRaiseParams(opts: {
     windowId?: number;
     title?: string;
 }): Record<string, unknown>;
+export declare const CHAR_DELAY_MIN_MS = 1;
+export declare const CHAR_DELAY_MAX_MS = 250;
+export declare function clampCharDelay(ms: number | undefined): number | undefined;
 export declare function buildWaitParams(opts: {
     duration?: number;
     id?: string;

package/dist/commands/computer-actions.js

@@ -70,6 +70,18 @@ export function buildRaiseParams(opts) {
         params.title = opts.title;
     return params;
 }
+// Inter-character typing delay for type-text. Default 4ms matches the daemon's
+// historical fixed rate; lossy keyboard relays (Parallels/VM guests) drop chars
+// at that rate, so callers can raise it. Clamp to [1, 250]ms CLI-side (the
+// daemon clamps too — defense in depth). Returns undefined when unset so the
+// daemon applies its own default. Pure + tested.
+export const CHAR_DELAY_MIN_MS = 1;
+export const CHAR_DELAY_MAX_MS = 250;
+export function clampCharDelay(ms) {
+    if (ms === undefined || !Number.isFinite(ms))
+        return undefined;
+    return Math.min(CHAR_DELAY_MAX_MS, Math.max(CHAR_DELAY_MIN_MS, Math.trunc(ms)));
+}
 // Build the wait RPC params. Pure + tested. Three modes, mirroring the
 // daemon's Wait.run: --duration (unconditional sleep), --id + --until
 // (cached-element poll), or --role/--label/--identifier (live locator poll).
@@ -276,6 +288,7 @@ export function registerActionCommands(program) {
         .option('--commit', 'Press Return after typing')
         .option('--raise', 'Bring the target app to the front first')
         .option('--require-frontmost', 'Fail (not warn) if the target is not the frontmost app')
+        .option('--char-delay <ms>', 'Inter-character delay in ms (default 4; raise for lossy keyboard relays like VM guests, e.g. 25). Clamped to [1, 250].', (v) => parseInt(v, 10))
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts);
@@ -285,6 +298,9 @@ export function registerActionCommands(program) {
                 params.commit = true;
             if (opts.requireFrontmost)
                 params.require_frontmost = true;
+            const charDelay = clampCharDelay(opts.charDelay);
+            if (charDelay !== undefined)
+                params.char_delay_ms = charDelay;
             const res = unwrap(await client.call('type_text', params));
             warnIfNotFrontmost(res);
             emit(res, Boolean(opts.json), () => `typed ${res.chars ?? opts.text.length} char(s)`);

package/dist/commands/exec.js

@@ -36,8 +36,8 @@ export function registerRunCommand(program) {
         .option('--add-dir <dir>', 'Grant access to an additional directory outside the project (Claude only, repeatable)', (val, prev) => [...prev, val], [])
         .option('--json', 'Stream events as JSON lines (for parsing by other tools)')
         .option('--quiet', 'Suppress preamble (rotation banner, "Running:" line). Useful when piping JSON events to a parser.', false)
-        .option('--headless', 'Non-interactive mode (auto-enabled when prompt provided)', false)
-        .option('-i, --interactive', 'Force interactive mode even when a prompt is provided')
+        .option('--headless', 'Force headless mode. Auto-enabled when a prompt is provided; pass explicitly to stay headless with no prompt (reads the prompt from stdin).', false)
+        .option('-i, --interactive', 'Force interactive mode even when a prompt is provided. Mutually exclusive with --headless.')
         .option('--session-id <id>', 'Resume a previous conversation (Claude only)')
         .option('--verbose', 'Show detailed execution logs')
         .option('--timeout <duration>', 'Kill the agent after this duration (e.g., 30m, 1h, 2h30m)')
@@ -85,7 +85,7 @@ export function registerRunCommand(program) {
     `,
     });
     runCmd.action(async (agentSpec, prompt, options) => {
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef }, { resolveRunDefaults },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor, headlessPlanStallCommand }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef }, { resolveRunDefaults },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -306,6 +306,23 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
         }
+        // Fail fast on the headless-plan stall footgun: a slash command run
+        // headless under the implicit default 'plan' mode hangs forever at
+        // ExitPlanMode (no TTY to approve the plan). Tell the user how to fix it
+        // instead of leaving them staring at a frozen process. Explicit
+        // `--mode plan` is respected for genuine read-only command runs.
+        const stallCmd = headlessPlanStallCommand({
+            prompt,
+            interactive: options.interactive,
+            mode,
+            modeIsDefault,
+        });
+        if (stallCmd) {
+            console.error(chalk.red(`Refusing to run ${stallCmd} headless in read-only 'plan' mode — it would hang at ExitPlanMode (no TTY to approve the plan).`));
+            console.error(chalk.yellow(`Re-run with an explicit mode: --mode auto (recommended — auto-approves safe ops, blocks risky ones), --mode edit, or --mode full.`));
+            console.error(chalk.gray(`Pass --mode plan explicitly if you really want a read-only run.`));
+            process.exit(1);
+        }
         const effort = options.effort;
         if (!['low', 'medium', 'high', 'xhigh', 'max', 'auto'].includes(effort)) {
             console.error(chalk.red(`Invalid effort: ${effort}. Use 'low', 'medium', 'high', 'xhigh', 'max', or 'auto'`));
@@ -363,12 +380,16 @@ export function registerRunCommand(program) {
             model,
             addDirs: options.addDir,
             json: options.json,
-            headless: options.headless ?? true,
+            headless: options.headless,
             sessionId: options.sessionId,
             verbose: options.verbose,
             timeout: options.timeout,
             env,
         };
+        if (options.interactive && options.headless) {
+            console.error(chalk.red('--interactive and --headless are mutually exclusive. Pass one, or neither (mode is inferred from prompt presence).'));
+            process.exit(1);
+        }
         if (options.interactive) {
             if (options.fallback) {
                 console.error(chalk.red('--interactive is not compatible with --fallback. Fallback only works for headless prompt runs.'));

package/dist/commands/import.js

@@ -44,6 +44,11 @@ async function runImport(agentArg, opts) {
     // installer dropped it. We adopt by symlinking that PATH binary directly
     // into the version's `node_modules/.bin/`. No package.json walk.
     const isInstallScriptAgent = !agent.npmPackage;
+    // Whether to adopt the binary by a direct symlink (installScript style) vs.
+    // the npm package.json walk. Starts equal to isInstallScriptAgent, but an
+    // npm-capable agent that turns out to be installed as a standalone binary
+    // (see the resolvePackageDirFromBinary fallback below) flips this to true.
+    let useDirectBinaryImport = isInstallScriptAgent;
     let globalPath = null;
     let installScriptBinary = null;
     if (opts.fromPath) {
@@ -84,9 +89,15 @@ async function runImport(agentArg, opts) {
         else {
             globalPath = resolvePackageDirFromBinary(binary);
             if (!globalPath) {
-                console.error(chalk.red(`Could not resolve npm package for binary: ${binary}`));
-                console.error(chalk.gray('Pass --from-path <dir> with the package directory explicitly.'));
-                process.exit(1);
+                // npmPackage is declared, but the binary on PATH doesn't live inside an
+                // npm package layout — e.g. Kimi installed via its curl install.sh,
+                // which drops a standalone bundled binary at ~/.kimi-code/bin/kimi
+                // rather than into node_modules/<pkg>/. The binary is valid and
+                // self-contained, so adopt it the same way as an installScript agent:
+                // a direct symlink. Key the decision on the on-disk layout, not on
+                // whether an npmPackage label happens to exist.
+                installScriptBinary = binary;
+                useDirectBinaryImport = true;
             }
         }
     }
@@ -112,7 +123,7 @@ async function runImport(agentArg, opts) {
     }
     let version = opts.version;
     if (!version) {
-        if (!isInstallScriptAgent && globalPath) {
+        if (!useDirectBinaryImport && globalPath) {
             try {
                 const pkg = JSON.parse(fs.readFileSync(path.join(globalPath, 'package.json'), 'utf8'));
                 version = typeof pkg.version === 'string' ? pkg.version : undefined;
@@ -142,7 +153,7 @@ async function runImport(agentArg, opts) {
         process.exit(1);
     }
     const versionDir = getVersionDir(agentId, version);
-    const fromLabel = isInstallScriptAgent ? installScriptBinary : globalPath;
+    const fromLabel = useDirectBinaryImport ? installScriptBinary : globalPath;
     console.log(chalk.bold(`\nImport ${agentLabel(agentId)} v${version}`));
     console.log(`  from: ${chalk.gray(fromLabel)}`);
     console.log(`  into: ${chalk.gray(versionDir)}`);
@@ -197,7 +208,7 @@ async function runImport(agentArg, opts) {
         }
     }
     const binSpinner = ora(`Registering ${agentLabel(agentId)} v${version} binary...`).start();
-    const binResult = isInstallScriptAgent
+    const binResult = useDirectBinaryImport
         ? importInstallScriptBinary({ agentId, npmPackage: agent.npmPackage, cliCommand: agent.cliCommand }, version, installScriptBinary, versionDir)
         : importAgentBinary({ agentId, npmPackage: agent.npmPackage, cliCommand: agent.cliCommand }, version, globalPath, versionDir);
     if (binResult.success) {

package/dist/commands/inspect.d.ts

@@ -12,6 +12,7 @@
  * AGENT.md / the file itself) so users can click straight to the source.
  */
 import { Command } from 'commander';
+import { type PluginResourceGroup } from '../lib/plugins.js';
 /** Resource kinds the inspect command can drill into. */
 declare const DRILLABLE_KINDS: readonly ["commands", "skills", "hooks", "mcp", "rules", "plugins", "workflows", "subagents"];
 type DrillableKind = typeof DRILLABLE_KINDS[number];
@@ -24,8 +25,10 @@ interface ResourceItem {
     linkTarget: string;
     /** One-line description (frontmatter `description:` or first non-frontmatter line). */
     description: string;
-    /** Extra detail rows surfaced in detail mode (e.g. a plugin's bundled skills/commands). */
+    /** Scalar detail rows surfaced in detail mode (e.g. a plugin's version). */
     extra?: Array<[string, string]>;
+    /** For plugins: the resource categories (skills, commands, …) the bundle packages. */
+    groups?: PluginResourceGroup[];
 }
 interface InspectOptions {
     brief?: boolean;
@@ -38,6 +41,13 @@ interface InspectOptions {
     plugins?: boolean | string;
     workflows?: boolean | string;
     subagents?: boolean | string;
+    command?: string;
+    skill?: string;
+    hook?: string;
+    rule?: string;
+    plugin?: string;
+    workflow?: string;
+    subagent?: string;
 }
 export declare function registerInspectCommand(program: Command): void;
 export declare function inspectAction(target: string, options: InspectOptions): Promise<void>;

package/dist/commands/inspect.js

@@ -23,7 +23,8 @@ import { readMeta, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, ge
 import { getVersionHomePath } from '../lib/versions.js';
 import { getShimsDir, getVersionedAliasPath } from '../lib/shims.js';
 import { getAgentResources, listResources, } from '../lib/resources.js';
-import { discoverPlugins, discoverPluginsInDir } from '../lib/plugins.js';
+import { discoverPlugins, discoverPluginsInDir, pluginResourceGroups } from '../lib/plugins.js';
+import { PLUGIN_GROUP_COLORS } from './plugins.js';
 import { countSessionsInScope } from '../lib/session/discover.js';
 import { damerauLevenshtein } from '../lib/fuzzy.js';
 /** Resource kinds the inspect command can drill into. */
@@ -37,6 +38,21 @@ const DRILLABLE_KINDS = [
     'workflows',
     'subagents',
 ];
+/**
+ * Singular aliases for the plural drill-down flags. `--plugin code` reads as
+ * "show the one plugin named code" — a required-value flag that always lands in
+ * detail mode, the natural counterpart to `--plugins` (list). `mcp` has no
+ * distinct singular, so it is intentionally absent.
+ */
+const SINGULAR_DRILL_ALIASES = {
+    command: 'commands',
+    skill: 'skills',
+    hook: 'hooks',
+    rule: 'rules',
+    plugin: 'plugins',
+    workflow: 'workflows',
+    subagent: 'subagents',
+};
 const CAPABILITY_NAMES = [
     'hooks', 'mcp', 'skills', 'commands', 'subagents', 'plugins', 'workflows', 'rules', 'allowlist',
 ];
@@ -50,6 +66,9 @@ export function registerInspectCommand(program) {
     for (const kind of DRILLABLE_KINDS) {
         cmd.option(`--${kind} [query]`, `list ${kind}; pass a name (fuzzy) to show detail`);
     }
+    for (const singular of Object.keys(SINGULAR_DRILL_ALIASES)) {
+        cmd.option(`--${singular} <query>`, `show detail for one ${singular} by name (fuzzy)`);
+    }
     cmd.action(async (target, options) => {
         await inspectAction(target, options);
     });
@@ -121,15 +140,21 @@ function pickDrillKind(options) {
     for (const kind of DRILLABLE_KINDS) {
         const value = options[kind];
         if (value !== undefined)
-            active.push({ kind, query: value });
+            active.push({ flag: `--${kind}`, kind, query: value });
+    }
+    // Singular aliases (`--plugin code`) always carry a name → detail mode.
+    for (const [singular, plural] of Object.entries(SINGULAR_DRILL_ALIASES)) {
+        const value = options[singular];
+        if (typeof value === 'string')
+            active.push({ flag: `--${singular}`, kind: plural, query: value });
     }
     if (active.length === 0)
         return null;
     if (active.length > 1) {
-        console.error(chalk.red(`Pick at most one drill-down flag. Got: ${active.map(a => '--' + a.kind).join(', ')}`));
+        console.error(chalk.red(`Pick at most one drill-down flag. Got: ${active.map(a => a.flag).join(', ')}`));
         process.exit(1);
     }
-    return active[0];
+    return { kind: active[0].kind, query: active[0].query };
 }
 /** Files at a DotAgents root that mark it as one, beyond the per-kind dirs. */
 const REPO_MARKER_FILES = ['agents.yaml', 'hooks.yaml'];
@@ -526,7 +551,7 @@ function renderItemList(header, jsonHead, kind, items, options) {
             ...jsonHead,
             kind,
             count: items.length,
-            items: items.map(i => ({ name: i.name, source: i.source, path: i.path, description: i.description })),
+            items: items.map(i => ({ name: i.name, source: i.source, path: i.path, description: i.description, ...(i.groups ? { groups: i.groups } : {}) })),
         }, null, 2));
         return;
     }
@@ -542,9 +567,23 @@ function renderItemList(header, jsonHead, kind, items, options) {
         if (item.description) {
             console.log(`             ${chalk.gray(truncate(item.description, 90))}`);
         }
+        if (item.groups)
+            printGroupRows(item.groups);
     }
     console.log('');
 }
+/** Print a plugin's resource breakdown as aligned `label  items` rows under a list entry. */
+function printGroupRows(groups) {
+    if (groups.length === 0)
+        return;
+    const width = Math.max(...groups.map(g => g.label.length));
+    for (const g of groups) {
+        const colorFn = PLUGIN_GROUP_COLORS[g.label] ?? chalk.white;
+        const label = chalk.gray(g.label.padEnd(width));
+        const value = g.items.map((s) => colorFn(s)).join(chalk.gray(', '));
+        console.log(`             ${label}  ${value}`);
+    }
+}
 // ─── Detail mode (fuzzy) ─────────────────────────────────────────────────────
 async function renderDetail(agent, version, versionHome, kind, query, options) {
     const items = collectKind(agent, versionHome, kind);
@@ -653,17 +692,6 @@ function pluginItems() {
  */
 function pluginToItem(plugin, source) {
     const extra = [];
-    const list = (names) => names.length <= 8 ? names.join(', ') : `${names.slice(0, 8).join(', ')}, +${names.length - 8} more`;
-    if (plugin.skills.length)
-        extra.push(['skills', `${plugin.skills.length}  (${list(plugin.skills)})`]);
-    if (plugin.commands.length)
-        extra.push(['commands', `${plugin.commands.length}  (${list(plugin.commands)})`]);
-    if (plugin.agentDefs.length)
-        extra.push(['subagents', `${plugin.agentDefs.length}  (${list(plugin.agentDefs)})`]);
-    if (plugin.hooks.length)
-        extra.push(['hooks', String(plugin.hooks.length)]);
-    if (plugin.mcpServers.length)
-        extra.push(['mcp', list(plugin.mcpServers)]);
     if (plugin.manifest.version)
         extra.push(['version', plugin.manifest.version]);
     return {
@@ -673,6 +701,7 @@ function pluginToItem(plugin, source) {
         linkTarget: linkTarget(plugin.root),
         description: plugin.manifest.description ?? '',
         extra,
+        groups: pluginResourceGroups(plugin),
     };
 }
 function entriesFromAgentResources(agent, versionHome, kind) {
@@ -742,9 +771,14 @@ function buildDetailRows(item, kind) {
                 rows.push(['tools', fm.tools.join(', ')]);
         }
     }
-    // Plugin bundles carry their nested resources as pre-built rows.
-    if (kind === 'plugins' && item.extra) {
-        rows.push(...item.extra);
+    // Plugin bundles surface their nested resources (skills, commands, …) plus
+    // scalar rows (version).
+    if (kind === 'plugins') {
+        if (item.groups)
+            for (const g of item.groups)
+                rows.push([g.label, g.items.join(', ')]);
+        if (item.extra)
+            rows.push(...item.extra);
     }
     return rows;
 }

package/dist/commands/mcp.js

@@ -92,9 +92,9 @@ function parseMcpAgentTargets(value) {
             }
             continue;
         }
-        const resolvedVersion = versionToken === 'latest'
-            ? installedVersions[installedVersions.length - 1]
-            : versionToken;
+        const resolvedVersion = versionToken === 'latest' ? installedVersions[installedVersions.length - 1]
+            : versionToken === 'oldest' ? installedVersions[0]
+                : versionToken;
         if (!installedVersions.includes(resolvedVersion)) {
             throw new VersionNotInstalledError(agentId, resolvedVersion, installedVersions);
         }

package/dist/commands/plugins.d.ts

@@ -22,4 +22,6 @@ interface MarketplaceRow {
  * default Claude version's settings.json#enabledPlugins keyed on @<marketplace>.
  */
 export declare function collectMarketplaceRows(): MarketplaceRow[];
+/** Per-category color for a plugin resource breakdown (shared with `agents inspect`). */
+export declare const PLUGIN_GROUP_COLORS: Record<string, (s: string) => string>;
 export {};

package/dist/commands/plugins.js

@@ -12,7 +12,7 @@ import { homeDir } from '../lib/platform/index.js';
 import { input } from '@inquirer/prompts';
 import { agentLabel } from '../lib/agents.js';
 import { capableAgents, isCapable } from '../lib/capabilities.js';
-import { discoverPlugins, getPlugin, pluginSupportsAgent, removePluginFromVersion, isPluginSynced, installPlugin, updatePlugin, loadUserConfig, saveUserConfig, checkPluginDependencies, hasPluginExecSurfaces, inspectPluginCapabilities, pluginCapabilityLabels, parseInstallSpec, syncPluginToVersion, } from '../lib/plugins.js';
+import { discoverPlugins, getPlugin, pluginSupportsAgent, removePluginFromVersion, isPluginSynced, installPlugin, updatePlugin, loadUserConfig, saveUserConfig, checkPluginDependencies, hasPluginExecSurfaces, inspectPluginCapabilities, pluginCapabilityLabels, parseInstallSpec, syncPluginToVersion, pluginResourceGroups, } from '../lib/plugins.js';
 import { listInstalledVersions, syncResourcesToVersion, getGlobalDefault, getVersionHomePath, } from '../lib/versions.js';
 import { isPromptCancelled, isInteractiveTerminal, requireDestructiveArg, requireInteractiveSelection, promptRemovalTargets, } from './utils.js';
 import { itemPicker } from '../lib/picker.js';
@@ -276,14 +276,17 @@ Examples:
     // agents plugins sync <name> [agent]
     pluginsCmd
         .command('sync <name> [agent]')
-        .description('Apply a plugin to the default version of an agent (or all supported agents if none specified)')
+        .description('Apply a plugin to an agent. Syncs every installed version (pass agent@version to target one).')
         .option('--allow-exec-surfaces', 'Enable the plugin even when it ships hooks/, .mcp.json, bin/, scripts/, settings.json, or permissions/')
         .addHelpText('after', `
 Examples:
-  # Sync a plugin to a specific agent (default version)
+  # Sync a plugin to every installed version of an agent
   agents plugins sync rush-toolkit claude
 
-  # Sync to all supported agents
+  # Sync to one specific version (parity with 'agents sync')
+  agents plugins sync rush-toolkit claude@2.1.142
+
+  # Sync to all supported agents (every installed version of each)
   agents plugins sync rush-toolkit
 
   # Re-affirm consent for a hooks-bearing plugin
@@ -295,12 +298,22 @@ Examples:
             console.log(chalk.red(`Plugin '${name}' not found`));
             process.exit(1);
         }
+        // Accept the same "agent@version" form as `agents sync`. Splitting here
+        // also means an unknown spec is reported cleanly rather than crashing
+        // isCapable() with a bare "claude@2.1.168".
+        let versionArg;
+        let agentName = agentArg;
+        if (agentArg && agentArg.includes('@')) {
+            const at = agentArg.lastIndexOf('@');
+            agentName = agentArg.slice(0, at);
+            versionArg = agentArg.slice(at + 1);
+        }
         // Determine target agents
         let targetAgents;
-        if (agentArg) {
-            const agentId = agentArg;
+        if (agentName) {
+            const agentId = agentName;
             if (!isCapable(agentId, 'plugins')) {
-                console.log(chalk.red(`Agent '${agentArg}' does not support plugins`));
+                console.log(chalk.red(`Agent '${agentName}' does not support plugins`));
                 process.exit(1);
             }
             if (!pluginSupportsAgent(plugin, agentId)) {
@@ -310,6 +323,10 @@ Examples:
             targetAgents = [agentId];
         }
         else {
+            if (versionArg) {
+                console.log(chalk.red(`A version (@${versionArg}) requires naming the agent, e.g. claude@${versionArg}`));
+                process.exit(1);
+            }
             targetAgents = capableAgents('plugins').filter(a => pluginSupportsAgent(plugin, a));
         }
         const allowExec = options.allowExecSurfaces === true;
@@ -317,8 +334,21 @@ Examples:
             const versions = listInstalledVersions(agentId);
             if (versions.length === 0)
                 continue;
-            const defaultVer = getGlobalDefault(agentId);
-            const targetVersions = defaultVer ? [defaultVer] : [versions[versions.length - 1]];
+            // Default to EVERY installed version. The previous behaviour synced only
+            // the global default, which silently skipped non-default versions used
+            // by balanced rotation -- so a rotated version would lack the plugin's
+            // slash commands. An explicit agent@version narrows back to one.
+            let targetVersions;
+            if (versionArg) {
+                if (!versions.includes(versionArg)) {
+                    console.log(chalk.red(`${agentLabel(agentId)} has no installed version ${versionArg} (installed: ${versions.join(', ')})`));
+                    process.exit(1);
+                }
+                targetVersions = [versionArg];
+            }
+            else {
+                targetVersions = versions;
+            }
             for (const version of targetVersions) {
                 const didSync = allowExec
                     ? syncPluginToVersion(plugin, agentId, getVersionHomePath(agentId, version), { allowExecSurfaces: true, version }).success
@@ -711,6 +741,32 @@ function buildPluginRows(plugins) {
     });
     return rows;
 }
+/** Per-category color for a plugin resource breakdown (shared with `agents inspect`). */
+export const PLUGIN_GROUP_COLORS = {
+    skills: chalk.cyan,
+    commands: chalk.cyan,
+    subagents: chalk.magenta,
+    hooks: chalk.yellow,
+    mcp: chalk.green,
+    lsp: chalk.green,
+    monitors: chalk.blue,
+    bin: chalk.white,
+    scripts: chalk.white,
+    settings: chalk.gray,
+};
+/** Human-readable section header per category, used by the picker detail pane. */
+const PLUGIN_GROUP_TITLES = {
+    skills: 'Skills',
+    commands: 'Commands',
+    subagents: 'Subagents',
+    hooks: 'Hooks',
+    mcp: 'MCP Servers',
+    lsp: 'LSP Servers',
+    monitors: 'Monitors',
+    bin: 'Bin',
+    scripts: 'Scripts',
+    settings: 'Settings',
+};
 /** Build the multi-line detail pane shown when a plugin is selected in the picker. */
 function formatPluginDetail(plugin, targets) {
     const lines = [];
@@ -728,24 +784,11 @@ function formatPluginDetail(plugin, targets) {
         lines.push('  ' + chalk.gray('Supports: ') + supported.join(chalk.gray(' · ')));
     }
     lines.push('  ' + chalk.gray(formatPath(plugin.root)));
-    const section = (label, items, colorFn) => {
-        if (items.length === 0)
-            return;
+    for (const group of pluginResourceGroups(plugin)) {
+        const colorFn = PLUGIN_GROUP_COLORS[group.label] ?? chalk.white;
         lines.push('');
-        lines.push(chalk.bold(`  ${label}`));
-        lines.push('  ' + items.map(colorFn).join(chalk.gray(', ')));
-    };
-    section('Skills', plugin.skills.map((s) => `/${plugin.name}:${s}`), chalk.cyan);
-    section('Commands', plugin.commands.map((c) => `/${plugin.name}:${c}`), chalk.cyan);
-    section('Subagents', plugin.agentDefs, chalk.magenta);
-    section('Hooks', plugin.hooks, chalk.yellow);
-    section('MCP Servers', plugin.mcpServers, chalk.green);
-    section('LSP Servers', plugin.lspServers, chalk.green);
-    section('Monitors', plugin.monitors, chalk.blue);
-    section('Bin', plugin.bin, chalk.white);
-    section('Scripts', plugin.scripts, chalk.white);
-    if (plugin.hasSettings) {
-        section('Settings', ['settings.json'], chalk.gray);
+        lines.push(chalk.bold(`  ${PLUGIN_GROUP_TITLES[group.label] ?? group.label}`));
+        lines.push('  ' + group.items.map((s) => colorFn(s)).join(chalk.gray(', ')));
     }
     if (targets.length > 0) {
         lines.push('');

package/dist/commands/sync.js

@@ -61,7 +61,7 @@ async function runSync(agentSpec, opts) {
             return;
         }
         agentId = parsed.agent;
-        if (parsed.version !== 'latest')
+        if (parsed.version !== 'latest' && parsed.version !== 'oldest')
             version = parsed.version;
     }
     if (opts.agent) {

package/dist/commands/teams.js

@@ -25,6 +25,7 @@ const AGENT_NAMES = {
     grok: 'Grok',
     antigravity: 'Antigravity',
     kimi: 'Kimi',
+    droid: 'Droid',
 };
 const VALID_AGENTS = Object.keys(AGENT_NAMES);
 // 'full' kept as historical alias for 'skip'; normalized to 'skip' downstream.

package/dist/commands/trash.d.ts

@@ -7,4 +7,15 @@
  * `rm -rf ~/.agents/.history/trash/` removes bytes from disk.
  */
 import type { Command } from 'commander';
+/**
+ * Restore a soft-deleted version back into ~/.agents/.history/versions/.
+ * Shared by `agents trash restore` and the top-level `agents restore` alias.
+ * Exits the process with a non-zero code on any failure.
+ */
+export declare function restoreVersion(target: string): void;
+/**
+ * Register the top-level `agents restore` command — a shorthand for
+ * `agents trash restore` so users can undo a `remove`/`prune` directly.
+ */
+export declare function registerRestoreCommand(program: Command): void;
 export declare function registerTrashCommands(program: Command): void;