@phnx-labs/agents-cli 1.20.3 → 1.20.5

package/dist/commands/subagents.js

@@ -10,8 +10,9 @@ import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
 import { agentLabel } from '../lib/agents.js';
+import { capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
-import { discoverSubagentsFromRepo, installSubagentCentrally, listInstalledSubagents, getInstalledSubagent, listSubagentsForAgent, SUBAGENT_CAPABLE_AGENTS, iterSubagentsCapableVersions, removeSubagentFromVersion, } from '../lib/subagents.js';
+import { discoverSubagentsFromRepo, installSubagentCentrally, listInstalledSubagents, getInstalledSubagent, listSubagentsForAgent, iterSubagentsCapableVersions, removeSubagentFromVersion, } from '../lib/subagents.js';
 import { listInstalledVersions, syncResourcesToVersion, getGlobalDefault, getVersionHomePath, promptAgentVersionSelection, } from '../lib/versions.js';
 import { getSubagentsDir, recordVersionResources } from '../lib/state.js';
 import { requireDestructiveArg, promptRemovalTargets, parseCommaSeparatedList, resolveAgentTargetsAutoInstalling, } from './utils.js';
@@ -182,7 +183,7 @@ Examples:
         let selectedAgents;
         let versionSelections;
         if (agentsArg) {
-            const result = await resolveAgentTargetsAutoInstalling(agentsArg, SUBAGENT_CAPABLE_AGENTS, { yes: options.yes });
+            const result = await resolveAgentTargetsAutoInstalling(agentsArg, capableAgents('subagents'), { yes: options.yes });
             if (!result) {
                 console.log(chalk.gray('Cancelled.'));
                 return;
@@ -191,7 +192,7 @@ Examples:
             versionSelections = result.versionSelections;
         }
         else {
-            const result = await promptAgentVersionSelection(SUBAGENT_CAPABLE_AGENTS, {
+            const result = await promptAgentVersionSelection(capableAgents('subagents'), {
                 skipPrompts: options.yes,
             });
             selectedAgents = result.selectedAgents;
@@ -307,7 +308,7 @@ Examples:
 /** Every (agent, version) that supports subagents and is installed. */
 function iterSubagentCapableVersions() {
     const out = [];
-    for (const agent of SUBAGENT_CAPABLE_AGENTS) {
+    for (const agent of capableAgents('subagents')) {
         for (const version of listInstalledVersions(agent)) {
             out.push({ agent, version, home: getVersionHomePath(agent, version) });
         }

package/dist/commands/sync.d.ts

@@ -1,10 +1,23 @@
 /**
- * Internal resource sync command.
+ * `agents sync` — synchronize central resources into an installed agent version.
  *
- * Registers the hidden `agents sync` command invoked by shims to
- * synchronize resources (commands, skills, hooks, memory, MCP, etc.)
- * into a specific agent version home before launch.
+ * Forms:
+ *   agents sync claude                                  # uses default/sole installed version
+ *   agents sync claude@2.1.142                          # explicit version
+ *   agents sync claude@latest                           # newest installed
+ *   agents sync --agent claude --agent-version 2.1.142  # legacy form, still supported
+ *
+ * In a TTY the command previews available/new resources and lets the user
+ * select what to sync (same prompts shown after `agents add`). Pass
+ * --yes for non-interactive auto-sync, --force to re-sync when nothing
+ * has changed, --quiet for total silence.
+ *
+ * Hot path:
+ *   --launch is the shim entry point. It skips version-home reconciliation
+ *   and runs only the cheap project-scoped work (rules compile, workspace
+ *   resource mirror, per-scope plugin marketplaces). Filesystem-only,
+ *   sub-50ms steady state. Keep changes here surgical.
  */
 import { Command } from 'commander';
-/** Register the hidden `agents sync` command. */
+/** Register the `agents sync` command. */
 export declare function registerSyncCommand(program: Command): void;

package/dist/commands/sync.js

@@ -1,88 +1,274 @@
 /**
- * Internal resource sync command.
+ * `agents sync` — synchronize central resources into an installed agent version.
  *
- * Registers the hidden `agents sync` command invoked by shims to
- * synchronize resources (commands, skills, hooks, memory, MCP, etc.)
- * into a specific agent version home before launch.
+ * Forms:
+ *   agents sync claude                                  # uses default/sole installed version
+ *   agents sync claude@2.1.142                          # explicit version
+ *   agents sync claude@latest                           # newest installed
+ *   agents sync --agent claude --agent-version 2.1.142  # legacy form, still supported
+ *
+ * In a TTY the command previews available/new resources and lets the user
+ * select what to sync (same prompts shown after `agents add`). Pass
+ * --yes for non-interactive auto-sync, --force to re-sync when nothing
+ * has changed, --quiet for total silence.
+ *
+ * Hot path:
+ *   --launch is the shim entry point. It skips version-home reconciliation
+ *   and runs only the cheap project-scoped work (rules compile, workspace
+ *   resource mirror, per-scope plugin marketplaces). Filesystem-only,
+ *   sub-50ms steady state. Keep changes here surgical.
  */
 import * as path from 'path';
 import chalk from 'chalk';
-import { AGENTS } from '../lib/agents.js';
-import { isVersionInstalled, syncResourcesToVersion } from '../lib/versions.js';
+import { agentLabel, resolveAgentName } from '../lib/agents.js';
+import { isVersionInstalled, syncResourcesToVersion, parseAgentSpec, resolveVersion, listInstalledVersions, getAvailableResources, getActuallySyncedResources, getProjectOnlyResources, getNewResources, hasNewResources, promptResourceSelection, promptNewResourceSelection, } from '../lib/versions.js';
 import { compileRulesForProject } from '../lib/rules/compile.js';
-/** Register the hidden `agents sync` command. */
+import { runLaunchSync } from '../lib/project-launch.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+/** Register the `agents sync` command. */
 export function registerSyncCommand(program) {
     program
-        .command('sync', { hidden: true })
-        .description('Internal: sync resources to a version home. Called by shims, not directly by users.')
-        .requiredOption('--agent <agent>', 'Agent identifier (claude, codex, gemini, cursor, opencode, openclaw)')
-        .requiredOption('--agent-version <version>', 'Installed version to sync resources into')
+        .command('sync [agentSpec]')
+        .summary('Sync resources into an installed agent version')
+        .description('Sync resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into an installed agent version. Previews what will change and lets you pick.\n\n[agentSpec] is the agent name with an optional @version, e.g. "claude" or "claude@2.1.142". Omit the version to sync into the active (or sole installed) one.')
+        .option('--agent <agent>', 'Agent identifier (legacy form; prefer the positional spec)')
+        .option('--agent-version <version>', 'Version to sync into (legacy form; prefer "agent@version")')
         .option('--project-dir <path>', 'Path to project-level .agents/ directory containing project-scoped resources')
         .option('--cwd <path>', 'Working directory for discovering project manifest and resources')
+        .option('--launch', 'Hot-path mode (shim only): skip version-home reconciliation, run project-scoped compile + workspace mirror + plugin marketplaces', false)
+        .option('-y, --yes', 'Skip the interactive preview and auto-sync all detected resources', false)
+        .option('--force', 'Re-sync even if no changes are detected since the last sync', false)
         .option('--quiet', 'Suppress all output (exit code indicates success)', false)
-        .action((opts) => {
-        const agentId = opts.agent;
-        const version = opts.agentVersion;
-        const projectDir = opts.projectDir;
-        const cwd = opts.cwd;
-        const quiet = !!opts.quiet;
-        if (!AGENTS[agentId]) {
-            if (!quiet) {
-                console.error(chalk.red(`Unknown agent '${agentId}'`));
-            }
+        .action(async (agentSpec, opts) => {
+        await runSync(agentSpec, opts);
+    });
+}
+async function runSync(agentSpec, opts) {
+    const quiet = !!opts.quiet;
+    const errLog = (msg) => { if (!quiet)
+        console.error(msg); };
+    const outLog = (msg) => { if (!quiet)
+        console.log(msg); };
+    // ---------- 1. Resolve agent + version ----------
+    let agentId;
+    let version;
+    if (agentSpec) {
+        const parsed = parseAgentSpec(agentSpec);
+        if (!parsed) {
+            errLog(chalk.red(`Invalid agent spec '${agentSpec}'.`));
+            errLog(chalk.gray('Examples: claude, claude@2.1.142, codex@latest'));
             process.exitCode = 1;
             return;
         }
-        if (!isVersionInstalled(agentId, version)) {
-            if (!quiet) {
-                console.error(chalk.red(`${AGENTS[agentId].name}@${version} is not installed`));
-            }
+        agentId = parsed.agent;
+        if (parsed.version !== 'latest')
+            version = parsed.version;
+    }
+    if (opts.agent) {
+        const resolved = resolveAgentName(opts.agent);
+        if (!resolved) {
+            errLog(chalk.red(`Unknown agent '${opts.agent}'.`));
             process.exitCode = 1;
             return;
         }
-        const result = syncResourcesToVersion(agentId, version, undefined, { projectDir, cwd });
-        // Compile project-scope rules into the workspace itself so each agent's
-        // native loader picks up cwd/<INSTRUCTIONS_FILE>. projectDir is the
-        // .agents/ directory; the workspace root is its parent.
-        let projectCompile = null;
-        if (projectDir) {
-            const projectRoot = path.dirname(projectDir);
-            projectCompile = compileRulesForProject(projectRoot);
-        }
-        if (quiet) {
-            return;
+        agentId = resolved;
+    }
+    if (opts.agentVersion) {
+        version = opts.agentVersion;
+    }
+    if (!agentId) {
+        errLog(chalk.red('Usage: agents sync <agent>[@version]'));
+        errLog(chalk.gray('       agents sync claude'));
+        errLog(chalk.gray('       agents sync claude@2.1.142'));
+        process.exitCode = 1;
+        return;
+    }
+    // ---------- 2. Resolve version (project pin → global default → sole installed) ----------
+    if (!version) {
+        version = resolveVersion(agentId, process.cwd()) || undefined;
+        if (!version) {
+            const installed = listInstalledVersions(agentId);
+            if (installed.length === 1) {
+                version = installed[0];
+            }
+            else if (installed.length === 0) {
+                errLog(chalk.red(`No ${agentLabel(agentId)} versions installed.`));
+                errLog(chalk.gray(`Install one: agents add ${agentId}@latest`));
+                process.exitCode = 1;
+                return;
+            }
+            else {
+                errLog(chalk.red(`No default ${agentLabel(agentId)} version pinned. Specify one:`));
+                for (const v of installed) {
+                    errLog(chalk.gray(`  agents sync ${agentId}@${v}`));
+                }
+                process.exitCode = 1;
+                return;
+            }
         }
-        const synced = [];
-        if (result.commands)
-            synced.push('commands');
-        if (result.skills)
-            synced.push('skills');
-        if (result.hooks)
-            synced.push('hooks');
-        if (result.memory.length > 0)
-            synced.push('memory');
-        if (result.permissions)
-            synced.push('permissions');
-        if (result.mcp.length > 0)
-            synced.push('mcp');
-        if (result.subagents.length > 0)
-            synced.push('subagents');
-        if (result.plugins.length > 0)
-            synced.push('plugins');
-        if (synced.length > 0) {
-            console.log(chalk.green(`Synced ${synced.join(', ')} to ${agentId}@${version}`));
+    }
+    if (!isVersionInstalled(agentId, version)) {
+        errLog(chalk.red(`${agentLabel(agentId)}@${version} is not installed.`));
+        const installed = listInstalledVersions(agentId);
+        if (installed.length > 0) {
+            errLog(chalk.gray(`Installed: ${installed.join(', ')}`));
         }
-        else {
-            console.log(chalk.gray('No resources to sync'));
+        errLog(chalk.gray(`Install it: agents add ${agentId}@${version}`));
+        process.exitCode = 1;
+        return;
+    }
+    const projectDir = opts.projectDir;
+    const cwd = opts.cwd || process.cwd();
+    // ---------- 3. --launch mode bypasses everything below ----------
+    if (opts.launch) {
+        runLaunchMode(agentId, version, cwd, quiet);
+        return;
+    }
+    // ---------- 4. Decide selection (interactive preview vs auto) ----------
+    const force = !!opts.force;
+    const yes = !!opts.yes;
+    const interactive = !quiet && !yes && isInteractiveTerminal();
+    let selection;
+    if (interactive) {
+        const available = getAvailableResources(cwd);
+        const actuallySynced = getActuallySyncedResources(agentId, version, { cwd });
+        const projectOnly = getProjectOnlyResources(cwd);
+        const newResources = getNewResources(available, actuallySynced, projectOnly);
+        const hasAnySynced = anyResources(actuallySynced);
+        try {
+            if (!hasAnySynced) {
+                outLog(chalk.cyan(`Syncing to ${agentLabel(agentId)}@${version}.`));
+                const userSelection = await promptResourceSelection(agentId);
+                if (!userSelection || Object.keys(userSelection).length === 0) {
+                    outLog(chalk.gray('Nothing selected. No changes made.'));
+                    return;
+                }
+                selection = userSelection;
+            }
+            else if (hasNewResources(newResources, agentId, version)) {
+                const userSelection = await promptNewResourceSelection(agentId, newResources, version);
+                if (!userSelection || Object.keys(userSelection).length === 0) {
+                    outLog(chalk.gray('Nothing selected. No changes made.'));
+                    return;
+                }
+                selection = userSelection;
+            }
+            else if (!force) {
+                outLog(chalk.gray(`${agentLabel(agentId)}@${version} is already in sync.`));
+                outLog(chalk.gray('Run with --force to re-sync, or --yes to bypass this check.'));
+                return;
+            }
+            // else: --force on a fully-synced version → selection stays undefined,
+            // syncResourcesToVersion falls through to its pattern-based full sync.
         }
-        if (projectCompile?.compiled) {
-            const linkInfo = projectCompile.symlinks.length > 0
-                ? ` (+ ${projectCompile.symlinks.join(', ')})`
-                : '';
-            console.log(chalk.gray(`Compiled project rules → ${projectCompile.agentsPath}${linkInfo}`));
+        catch (e) {
+            if (isPromptCancelled(e)) {
+                outLog(chalk.gray('Cancelled. No changes made.'));
+                return;
+            }
+            throw e;
         }
-        if (projectCompile && projectCompile.skippedClobber.length > 0) {
-            console.log(chalk.yellow(`Skipped (user-authored, not overwritten): ${projectCompile.skippedClobber.join(', ')}`));
+    }
+    // ---------- 5. Run sync ----------
+    const result = syncResourcesToVersion(agentId, version, selection, { projectDir, cwd, force });
+    // Compile project-scope rules into the workspace itself so each agent's
+    // native loader picks up cwd/<INSTRUCTIONS_FILE>. projectDir is the
+    // .agents/ directory; the workspace root is its parent.
+    let projectCompile = null;
+    if (projectDir) {
+        const projectRoot = path.dirname(projectDir);
+        projectCompile = compileRulesForProject(projectRoot);
+    }
+    if (quiet)
+        return;
+    // ---------- 6. Detailed output ----------
+    printSyncDetail(result, agentId, version, cwd);
+    if (projectCompile?.compiled) {
+        const linkInfo = projectCompile.symlinks.length > 0
+            ? ` (+ ${projectCompile.symlinks.join(', ')})`
+            : '';
+        console.log(chalk.gray(`Compiled project rules → ${projectCompile.agentsPath}${linkInfo}`));
+    }
+    if (projectCompile && projectCompile.skippedClobber.length > 0) {
+        console.log(chalk.yellow(`Skipped (user-authored, not overwritten): ${projectCompile.skippedClobber.join(', ')}`));
+    }
+}
+function anyResources(r) {
+    return r.commands.length + r.skills.length + r.hooks.length + r.memory.length +
+        r.mcp.length + r.permissions.length + r.subagents.length +
+        r.plugins.length + r.workflows.length > 0;
+}
+/** Format the post-sync detail output: per-kind count + a name preview. */
+function printSyncDetail(result, agent, version, cwd) {
+    // Booleans in SyncResult (commands, skills, hooks, permissions) carry no
+    // name list. Re-derive ground truth from the version home so the user
+    // sees what's actually present after the sync.
+    const synced = getActuallySyncedResources(agent, version, { cwd });
+    const lines = [];
+    if (result.commands)
+        lines.push({ kind: 'commands', items: synced.commands });
+    if (result.skills)
+        lines.push({ kind: 'skills', items: synced.skills });
+    if (result.hooks)
+        lines.push({ kind: 'hooks', items: synced.hooks });
+    if (result.memory.length > 0)
+        lines.push({ kind: 'memory', items: result.memory });
+    if (result.permissions)
+        lines.push({ kind: 'permissions', items: synced.permissions });
+    if (result.mcp.length > 0)
+        lines.push({ kind: 'mcp', items: result.mcp });
+    if (result.subagents.length > 0)
+        lines.push({ kind: 'subagents', items: result.subagents });
+    if (result.plugins.length > 0)
+        lines.push({ kind: 'plugins', items: result.plugins });
+    if (result.workflows.length > 0)
+        lines.push({ kind: 'workflows', items: result.workflows });
+    if (lines.length === 0) {
+        console.log(chalk.gray(`Already in sync — ${agentLabel(agent)}@${version}`));
+        return;
+    }
+    console.log(chalk.green(`Synced to ${agentLabel(agent)}@${version}:`));
+    const kindWidth = Math.max(...lines.map(l => l.kind.length));
+    const PREVIEW = 5;
+    for (const { kind, items } of lines) {
+        const padded = kind.padEnd(kindWidth);
+        const sorted = [...items].sort((a, b) => a.localeCompare(b));
+        const preview = sorted.slice(0, PREVIEW).join(', ');
+        const more = sorted.length > PREVIEW ? chalk.gray(`, +${sorted.length - PREVIEW} more`) : '';
+        const count = chalk.cyan(`(${sorted.length})`.padStart(5));
+        console.log(`  ${chalk.bold(padded)}  ${count}  ${chalk.gray(preview)}${more}`);
+    }
+}
+function runLaunchMode(agent, version, cwd, quiet) {
+    let result;
+    try {
+        result = runLaunchSync({ agent, version, cwd });
+    }
+    catch (err) {
+        if (!quiet) {
+            console.error(chalk.yellow(`agents: launch sync skipped (${err.message})`));
         }
-    });
+        return;
+    }
+    if (quiet)
+        return;
+    const bits = [];
+    if (result.rulesCompiled)
+        bits.push('rules');
+    if (result.workspaceLinks > 0)
+        bits.push(`${result.workspaceLinks} workspace link(s)`);
+    const mpCount = Object.keys(result.marketplaces).length;
+    if (mpCount > 0) {
+        const pluginCount = Object.values(result.marketplaces).reduce((acc, names) => acc + names.length, 0);
+        bits.push(`${pluginCount} plugin(s) across ${mpCount} marketplace(s)`);
+    }
+    if (bits.length === 0) {
+        console.log(chalk.gray('No project resources to compile'));
+    }
+    else {
+        console.log(chalk.green(`Launch sync: ${bits.join(', ')}`));
+    }
+    if (result.workspaceSkipped.length > 0) {
+        console.log(chalk.yellow(`Skipped (user-owned, not overwritten): ${result.workspaceSkipped.join(', ')}`));
+    }
 }

package/dist/commands/teams.js

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

package/dist/commands/tmux.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `agents tmux` — terminal multiplexer integration.
+ *
+ * Why this exists: the swarmify VS Code extension was hand-rolling tmux
+ * commands with brittle shell escaping (`extension/src/vscode/tmux.ts`).
+ * Lifting the orchestration into the CLI gives one source of truth that the
+ * extension, raw shells, `agents teams`, routines, and the Swarm MCP can all
+ * call into.
+ *
+ * Surface mirrors `agents pty`:
+ *   agents tmux check
+ *   agents tmux new <name>     [--cmd ...] [--cwd DIR] [--replace] [--attach-existing] [--source S]
+ *   agents tmux attach <name>
+ *   agents tmux list [--json]
+ *   agents tmux has <name>
+ *   agents tmux split <name> <h|v> [--cmd ...] [--cwd DIR]
+ *   agents tmux send <name>[:pane] <keys> [--no-enter] [--raw]
+ *   agents tmux capture <name>[:pane] [--lines N] [--ansi]
+ *   agents tmux info <name>    [--json]
+ *   agents tmux kill <name>
+ *   agents tmux kill-all       [--yes]
+ */
+import type { Command } from 'commander';
+/** Register the `agents tmux` command tree. */
+export declare function registerTmuxCommands(program: Command): void;