@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/lib/acp/run.js

@@ -0,0 +1,39 @@
+/**
+ * Headless ACP runner.
+ *
+ * Glue between the `agents run <agent> "prompt" --acp` command and the ACP
+ * client. Emits either a human-readable stream of agent messages or newline-
+ * delimited JSON events, depending on `--json`.
+ */
+import { runAcp } from './client.js';
+/** Runs a prompt turn over ACP, streaming output to stdout per `json` mode. */
+export async function runAcpHeadless(opts) {
+    const onUpdate = opts.json ? emitJsonLine : emitTextChunk;
+    const result = await runAcp({
+        agent: opts.agent,
+        prompt: opts.prompt,
+        cwd: opts.cwd,
+        mode: opts.mode,
+        onUpdate,
+    });
+    if (opts.json) {
+        emitJsonLine({
+            sessionId: result.sessionId,
+            update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: '' } },
+            _meta: { stopReason: result.stopReason },
+        });
+    }
+    else {
+        process.stdout.write('\n');
+    }
+    return result.stopReason === 'end_turn' ? 0 : 1;
+}
+function emitJsonLine(n) {
+    process.stdout.write(JSON.stringify(n) + '\n');
+}
+function emitTextChunk(n) {
+    const upd = n.update;
+    if (upd.sessionUpdate === 'agent_message_chunk' && upd.content.type === 'text') {
+        process.stdout.write(upd.content.text);
+    }
+}

package/dist/lib/agents.d.ts

@@ -1,29 +1,74 @@
 import type { AgentConfig, AgentId } from './types.js';
+/** Represents the installation state of an agent's CLI binary. */
 export interface CliState {
     installed: boolean;
     version: string | null;
     path: string | null;
 }
+/**
+ * Minimum Codex CLI version that supports hooks.
+ * Mirrored on `AGENTS.codex.capabilities.hooks.since` -- kept exported for
+ * legacy import sites that haven't migrated to `supports()` yet.
+ */
 export declare const CODEX_HOOKS_MIN_VERSION = "0.116.0";
+/** Minimum Gemini CLI version that supports the hooks system (v0.26.0, Jan 2026). */
+export declare const GEMINI_HOOKS_MIN_VERSION = "0.26.0";
+/**
+ * Master registry of all supported agents keyed by AgentId.
+ *
+ * Each entry defines the agent's CLI command, npm package, config directory layout,
+ * instructions file name, slash-command format, and capability flags. This is the
+ * single source of truth for agent metadata consumed throughout the codebase.
+ */
 export declare const AGENTS: Record<AgentId, AgentConfig>;
+/** All registered agent IDs derived from the AGENTS registry. */
 export declare const ALL_AGENT_IDS: AgentId[];
+/** Agents that support MCP (Model Context Protocol) server integration. */
 export declare const MCP_CAPABLE_AGENTS: AgentId[];
+/** Agents that support skills (SKILL.md + rules/ bundles). */
 export declare const SKILLS_CAPABLE_AGENTS: AgentId[];
+/** Agents that support file-based slash commands. */
 export declare const COMMANDS_CAPABLE_AGENTS: AgentId[];
-export declare const HOOKS_CAPABLE_AGENTS: readonly ["claude", "codex", "gemini", "openclaw"];
+/** Agents that support event hooks (pre/post lifecycle callbacks). */
+export declare const HOOKS_CAPABLE_AGENTS: readonly AgentId[];
+/** Agents that support the plugin system. */
 export declare const PLUGINS_CAPABLE_AGENTS: AgentId[];
 /** Get the chalk color function for an agent. Works for any AgentId or SessionAgentId. */
 export declare function colorAgent(agentId: string): (s: string) => string;
 /** Return the agent's display name, colored. */
 export declare function agentLabel(agentId: string): string;
+/** Check whether the given agent's CLI binary is present on PATH. */
 export declare function isCliInstalled(agentId: AgentId): Promise<boolean>;
+/** Return the installed CLI version for the given agent, or null if not found. */
 export declare function getCliVersion(agentId: AgentId): Promise<string | null>;
+/** Return the absolute path to the agent's CLI binary on PATH, or null. */
 export declare function getCliPath(agentId: AgentId): Promise<string | null>;
+/**
+ * Resolve the full CLI state for an agent: whether it is installed, its version,
+ * and the path to the binary. Checks version-managed installs first, then falls
+ * back to a plain PATH lookup.
+ */
 export declare function getCliState(agentId: AgentId): Promise<CliState>;
+/** Resolve CLI state for all registered agents in parallel. */
 export declare function getAllCliStates(): Promise<Partial<Record<AgentId, CliState>>>;
+/** Check whether the agent's config directory exists on disk. */
 export declare function isConfigured(agentId: AgentId): boolean;
+/** Info about an existing unmanaged agent installation. */
+export interface UnmanagedInstall {
+    agentId: AgentId;
+    configDir: string;
+    version: string | null;
+}
+/**
+ * Detect existing agent installations that are NOT yet managed by agents-cli.
+ * Returns agents whose config dir exists as a real directory (not a symlink).
+ */
+export declare function getUnmanagedAgentInstalls(): Promise<UnmanagedInstall[]>;
+/** Create the agent's slash-commands directory if it does not exist. */
 export declare function ensureCommandsDir(agentId: AgentId): void;
+/** Create the agent's skills directory if it does not exist. */
 export declare function ensureSkillsDir(agentId: AgentId): void;
+/** Account identity and billing information extracted from an agent's auth config. */
 export interface AccountInfo {
     accountKey: string | null;
     usageKey: string | null;
@@ -39,9 +84,21 @@ export interface AccountInfo {
     } | null;
     lastActive: Date | null;
 }
+/** Return the email address associated with the agent's auth config, or null. */
 export declare function getAccountEmail(agentId: AgentId, home?: string): Promise<string | null>;
+/**
+ * Extract full account information (identity, plan, usage status, credits) from
+ * the agent's local auth/config files. Supports Claude, Codex, and Gemini.
+ */
 export declare function getAccountInfo(agentId: AgentId, home?: string): Promise<AccountInfo>;
+/**
+ * Quick count of session files for an agent (without full DB scan).
+ * Used during init to show approximate session count to user.
+ */
+export declare function countSessionFiles(agentId: AgentId): number;
+/** Check whether a named MCP server is registered with the agent's CLI. */
 export declare function isMcpRegistered(agentId: AgentId, mcpName: string): Promise<boolean>;
+/** Register an MCP server with an agent's CLI via `mcp add`. */
 export declare function registerMcp(agentId: AgentId, name: string, command: string, scope?: 'user' | 'project', transport?: string, options?: {
     home?: string;
     binary?: string;
@@ -49,6 +106,7 @@ export declare function registerMcp(agentId: AgentId, name: string, command: str
     success: boolean;
     error?: string;
 }>;
+/** Unregister (remove) a named MCP server from an agent's CLI config. */
 export declare function unregisterMcp(agentId: AgentId, name: string, options?: {
     home?: string;
     binary?: string;
@@ -56,21 +114,32 @@ export declare function unregisterMcp(agentId: AgentId, name: string, options?:
     success: boolean;
     error?: string;
 }>;
+/** Result of an MCP registration or removal operation targeting a specific agent and optional version. */
 export interface McpTargetOperationResult {
     agentId: AgentId;
     version?: string;
     success: boolean;
     error?: string;
 }
+/**
+ * Register an MCP server across multiple agent targets, including both direct
+ * (non-version-managed) agents and specific version-managed installs.
+ */
 export declare function registerMcpToTargets(targets: {
     directAgents: AgentId[];
     versionSelections: Map<AgentId, string[]>;
 }, name: string, command: string, scope?: 'user' | 'project', transport?: string): Promise<McpTargetOperationResult[]>;
+/**
+ * Unregister an MCP server from multiple agent targets, including both direct
+ * agents and specific version-managed installs.
+ */
 export declare function unregisterMcpFromTargets(targets: {
     directAgents: AgentId[];
     versionSelections: Map<AgentId, string[]>;
 }, name: string): Promise<McpTargetOperationResult[]>;
+/** Scope at which an MCP server is registered: user-global or per-project. */
 export type McpScope = 'user' | 'project';
+/** Describes an MCP server discovered in an agent's config, with its scope and command. */
 export interface InstalledMcp {
     name: string;
     scope: McpScope;
@@ -99,9 +168,12 @@ export declare function parseMcpConfig(agentId: AgentId, configPath: string): Re
 export declare function listInstalledMcpsWithScope(agentId: AgentId, cwd?: string, options?: {
     home?: string;
 }): InstalledMcp[];
+/** Map of agent name aliases and shorthand identifiers to canonical AgentId values. */
 export declare const AGENT_NAME_ALIASES: Record<string, AgentId>;
+/** Resolve a user-provided agent name (alias, shorthand, or canonical) to its AgentId. */
 export declare function resolveAgentName(input: string): AgentId | null;
+/** Check whether the input string matches any known agent name or alias. */
 export declare function isAgentName(input: string): boolean;
+/** Format an error message for an unrecognized agent name, listing valid options. */
 export declare function formatAgentError(agentName: string, validAgents?: AgentId[]): string;
 export {};
-//# sourceMappingURL=agents.d.ts.map

package/dist/lib/agents.js

@@ -1,18 +1,35 @@
-import { exec } from 'child_process';
+/**
+ * Core agent configuration and detection module.
+ *
+ * Defines the canonical registry of all supported AI coding agents (Claude, Codex,
+ * Gemini, Cursor, OpenCode, OpenClaw, Copilot, Amp, Kiro, Goose, Roo) with their
+ * CLI commands, config paths, capability flags, and MCP integration points.
+ *
+ * Provides functions for detecting installed CLIs, resolving version-managed binaries,
+ * reading account/auth info, and managing MCP server registrations across agents.
+ */
+import { execFile } from 'child_process';
 import { promisify } from 'util';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as TOML from 'smol-toml';
 import chalk from 'chalk';
-import { walkForFiles } from './session/discover.js';
-import { getVersionsDir, getShimsDir } from './state.js';
+import { walkForFiles } from './fs-walk.js';
+import { getVersionsDir, getShimsDir, getAgentsDir } from './state.js';
 import { resolveVersion, getVersionHomePath, getBinaryPath } from './versions.js';
 import { loadClaudeOauth } from './usage.js';
-const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
 const HOME = os.homedir();
+/**
+ * Minimum Codex CLI version that supports hooks.
+ * Mirrored on `AGENTS.codex.capabilities.hooks.since` -- kept exported for
+ * legacy import sites that haven't migrated to `supports()` yet.
+ */
 export const CODEX_HOOKS_MIN_VERSION = '0.116.0';
-const CLI_VERSION_CACHE_PATH = path.join(HOME, '.agents', '.cli-version-cache.json');
+/** Minimum Gemini CLI version that supports the hooks system (v0.26.0, Jan 2026). */
+export const GEMINI_HOOKS_MIN_VERSION = '0.26.0';
+const CLI_VERSION_CACHE_PATH = path.join(getAgentsDir(), '.cli-version-cache.json');
 let cliVersionCache = null;
 function loadCliVersionCache() {
     if (cliVersionCache)
@@ -39,7 +56,7 @@ function saveCliVersionCache() {
         /* best-effort cache persist */
     }
 }
-/** Synchronous PATH search — no subprocess. Returns first matching binary path. */
+/** Synchronous PATH search -- no subprocess. Returns first matching binary path. */
 function findInPath(command) {
     const pathEnv = process.env.PATH || '';
     const pathExt = process.platform === 'win32' ? (process.env.PATHEXT || '').split(';') : [''];
@@ -60,6 +77,67 @@ function findInPath(command) {
     }
     return null;
 }
+function splitCommandLine(command) {
+    const args = [];
+    let current = '';
+    let quote = null;
+    let tokenStarted = false;
+    for (let i = 0; i < command.length; i++) {
+        const char = command[i];
+        if (quote) {
+            if (char === quote) {
+                quote = null;
+                tokenStarted = true;
+            }
+            else if (char === '\\' && quote === '"' && i + 1 < command.length) {
+                current += command[++i];
+                tokenStarted = true;
+            }
+            else {
+                current += char;
+                tokenStarted = true;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            tokenStarted = true;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (tokenStarted) {
+                args.push(current);
+                current = '';
+                tokenStarted = false;
+            }
+            continue;
+        }
+        if (char === '\\' && i + 1 < command.length) {
+            current += command[++i];
+            tokenStarted = true;
+            continue;
+        }
+        current += char;
+        tokenStarted = true;
+    }
+    if (quote) {
+        throw new Error('Unterminated quote in MCP command');
+    }
+    if (tokenStarted) {
+        args.push(current);
+    }
+    if (args.length === 0) {
+        throw new Error('MCP command is required');
+    }
+    return args;
+}
+/**
+ * Master registry of all supported agents keyed by AgentId.
+ *
+ * Each entry defines the agent's CLI command, npm package, config directory layout,
+ * instructions file name, slash-command format, and capability flags. This is the
+ * single source of truth for agent metadata consumed throughout the codebase.
+ */
 export const AGENTS = {
     claude: {
         id: 'claude',
@@ -79,6 +157,7 @@ export const AGENTS = {
         supportsHooks: true,
         capabilities: { hooks: true, mcp: true, allowlist: true, skills: true, commands: true, plugins: true, memoryImports: true },
     },
+    // codex hooks: gated to >= 0.116.0 (introduced [features] codex_hooks flag).
     codex: {
         id: 'codex',
         name: 'Codex',
@@ -94,7 +173,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        capabilities: { hooks: true, mcp: true, allowlist: false, skills: true, commands: true, plugins: false },
+        capabilities: { hooks: { since: '0.116.0' }, mcp: true, allowlist: false, skills: true, commands: { until: '0.117.0' }, plugins: false },
     },
     gemini: {
         id: 'gemini',
@@ -112,7 +191,8 @@ export const AGENTS = {
         variableSyntax: '{{args}}',
         supportsHooks: true,
         nativeAgentsSkillsDir: true,
-        capabilities: { hooks: true, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, memoryImports: true },
+        // gemini hooks: shipped in v0.26.0 (Jan 2026); older binaries silently ignore the `hooks` key.
+        capabilities: { hooks: { since: '0.26.0' }, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, memoryImports: true },
     },
     cursor: {
         id: 'cursor',
@@ -255,12 +335,18 @@ export const AGENTS = {
         capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false },
     },
 };
+/** All registered agent IDs derived from the AGENTS registry. */
 export const ALL_AGENT_IDS = Object.keys(AGENTS);
+/** Agents that support MCP (Model Context Protocol) server integration. */
 export const MCP_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.mcp);
+/** Agents that support skills (SKILL.md + rules/ bundles). */
 export const SKILLS_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.skills);
+/** Agents that support file-based slash commands. */
 export const COMMANDS_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.commands);
-export const HOOKS_CAPABLE_AGENTS = ['claude', 'codex', 'gemini', 'openclaw'];
-export const PLUGINS_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.plugins);
+/** Agents that support event hooks (pre/post lifecycle callbacks). */
+export const HOOKS_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.hooks !== false);
+/** Agents that support the plugin system. */
+export const PLUGINS_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.plugins !== false);
 /** Get the chalk color function for an agent. Works for any AgentId or SessionAgentId. */
 export function colorAgent(agentId) {
     const agent = AGENTS[agentId];
@@ -275,10 +361,12 @@ export function agentLabel(agentId) {
         return agentId;
     return chalk[agent.color](agent.name);
 }
+/** Check whether the given agent's CLI binary is present on PATH. */
 export async function isCliInstalled(agentId) {
     const agent = AGENTS[agentId];
     return findInPath(agent.cliCommand) !== null;
 }
+/** Return the installed CLI version for the given agent, or null if not found. */
 export async function getCliVersion(agentId) {
     const agent = AGENTS[agentId];
     const binaryPath = findInPath(agent.cliCommand);
@@ -286,6 +374,7 @@ export async function getCliVersion(agentId) {
         return null;
     return getCachedVersionForBinary(agentId, binaryPath);
 }
+/** Return the absolute path to the agent's CLI binary on PATH, or null. */
 export async function getCliPath(agentId) {
     return findInPath(AGENTS[agentId].cliCommand);
 }
@@ -307,7 +396,7 @@ async function getCachedVersionForBinary(agentId, binaryPath) {
     const agent = AGENTS[agentId];
     let version = null;
     try {
-        const { stdout } = await execAsync(`${agent.cliCommand} --version`, { timeout: 3000 });
+        const { stdout } = await execFileAsync(agent.cliCommand, ['--version'], { timeout: 3000 });
         if (agentId === 'openclaw') {
             const match = stdout.match(/openclaw\/(\d+\.\d+\.\d+)/);
             version = match ? match[1] : stdout.trim();
@@ -325,6 +414,11 @@ async function getCachedVersionForBinary(agentId, binaryPath) {
     saveCliVersionCache();
     return version;
 }
+/**
+ * Resolve the full CLI state for an agent: whether it is installed, its version,
+ * and the path to the binary. Checks version-managed installs first, then falls
+ * back to a plain PATH lookup.
+ */
 export async function getCliState(agentId) {
     // Fast path: if version-managed, derive state from filesystem (no subprocesses)
     const agent = AGENTS[agentId];
@@ -370,6 +464,7 @@ export async function getCliState(agentId) {
         path: binaryPath,
     };
 }
+/** Resolve CLI state for all registered agents in parallel. */
 export async function getAllCliStates() {
     const states = {};
     const results = await Promise.all(ALL_AGENT_IDS.map(async (agentId) => ({
@@ -381,26 +476,56 @@ export async function getAllCliStates() {
     }
     return states;
 }
+/** Check whether the agent's config directory exists on disk. */
 export function isConfigured(agentId) {
     const agent = AGENTS[agentId];
     return fs.existsSync(agent.configDir);
 }
+/**
+ * Detect existing agent installations that are NOT yet managed by agents-cli.
+ * Returns agents whose config dir exists as a real directory (not a symlink).
+ */
+export async function getUnmanagedAgentInstalls() {
+    const unmanaged = [];
+    const candidates = ['claude', 'codex', 'gemini'];
+    for (const agentId of candidates) {
+        const agent = AGENTS[agentId];
+        try {
+            const stat = fs.lstatSync(agent.configDir);
+            if (stat.isDirectory() && !stat.isSymbolicLink()) {
+                const version = await getCliVersion(agentId);
+                unmanaged.push({ agentId, configDir: agent.configDir, version });
+            }
+        }
+        catch {
+            // Config dir doesn't exist
+        }
+    }
+    return unmanaged;
+}
+/** Create the agent's slash-commands directory if it does not exist. */
 export function ensureCommandsDir(agentId) {
     const agent = AGENTS[agentId];
     if (!fs.existsSync(agent.commandsDir)) {
         fs.mkdirSync(agent.commandsDir, { recursive: true });
     }
 }
+/** Create the agent's skills directory if it does not exist. */
 export function ensureSkillsDir(agentId) {
     const agent = AGENTS[agentId];
     if (!fs.existsSync(agent.skillsDir)) {
         fs.mkdirSync(agent.skillsDir, { recursive: true });
     }
 }
+/** Return the email address associated with the agent's auth config, or null. */
 export async function getAccountEmail(agentId, home) {
     const info = await getAccountInfo(agentId, home);
     return info.email;
 }
+/**
+ * Extract full account information (identity, plan, usage status, credits) from
+ * the agent's local auth/config files. Supports Claude, Codex, and Gemini.
+ */
 export async function getAccountInfo(agentId, home) {
     const base = home || os.homedir();
     const empty = {
@@ -537,6 +662,7 @@ export async function getAccountInfo(agentId, home) {
         return { ...empty, lastActive };
     }
 }
+/** Determine when the agent was last used by checking session file mtimes, falling back to config mtime. */
 function resolveLastActive(agentId, base, configPath) {
     const sessionDir = getSessionDir(agentId, base);
     const sessionExt = getSessionExtension(agentId);
@@ -555,6 +681,7 @@ function resolveLastActive(agentId, base, configPath) {
         return null;
     }
 }
+/** Return the root directory where the agent stores session files, or null if unknown. */
 function getSessionDir(agentId, base) {
     switch (agentId) {
         case 'claude':
@@ -567,6 +694,7 @@ function getSessionDir(agentId, base) {
             return null;
     }
 }
+/** Return the file extension used for session files by the given agent. */
 function getSessionExtension(agentId) {
     switch (agentId) {
         case 'claude':
@@ -578,6 +706,36 @@ function getSessionExtension(agentId) {
             return null;
     }
 }
+/**
+ * Quick count of session files for an agent (without full DB scan).
+ * Used during init to show approximate session count to user.
+ */
+export function countSessionFiles(agentId) {
+    const sessionDir = getSessionDir(agentId, HOME);
+    const ext = getSessionExtension(agentId);
+    if (!sessionDir || !ext || !fs.existsSync(sessionDir))
+        return 0;
+    let count = 0;
+    const walk = (dir) => {
+        try {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    walk(path.join(dir, entry.name));
+                }
+                else if (entry.isFile() && entry.name.endsWith(ext)) {
+                    count++;
+                }
+            }
+        }
+        catch {
+            // Permission denied or other error
+        }
+    };
+    walk(sessionDir);
+    return count;
+}
+/** Walk a directory for files matching the extension and return the mtime of the most recent one. */
 function getLatestFileMtime(dir, ext) {
     if (!fs.existsSync(dir))
         return null;
@@ -591,6 +749,7 @@ function getLatestFileMtime(dir, ext) {
         return null;
     }
 }
+/** Decode the payload section of a JWT token without verifying its signature. */
 function decodeJwtPayload(token) {
     const payload = token.split('.')[1];
     if (!payload)
@@ -602,6 +761,7 @@ function decodeJwtPayload(token) {
         return null;
     }
 }
+/** Extract the default organization ID from a Codex/OpenAI auth claim. */
 function getCodexDefaultOrgId(authClaim) {
     const organizations = authClaim?.organizations;
     if (!Array.isArray(organizations))
@@ -609,12 +769,14 @@ function getCodexDefaultOrgId(authClaim) {
     const first = organizations[0];
     return typeof first?.id === 'string' ? first.id : null;
 }
+/** Trim and normalize an identity string, returning null for empty or non-string values. */
 function normalizeIdentityPart(value) {
     if (typeof value !== 'string')
         return null;
     const trimmed = value.trim();
     return trimmed || null;
 }
+/** Build a composite identity key like "claude:account=abc:org=xyz" from labeled parts. */
 function buildIdentityKey(agentId, parts) {
     const encoded = parts
         .filter(([, value]) => value)
@@ -623,13 +785,14 @@ function buildIdentityKey(agentId, parts) {
         return null;
     return `${agentId}:${encoded.join(':')}`;
 }
+/** Check whether a named MCP server is registered with the agent's CLI. */
 export async function isMcpRegistered(agentId, mcpName) {
     const agent = AGENTS[agentId];
     if (!agent.capabilities.mcp || !(await isCliInstalled(agentId))) {
         return false;
     }
     try {
-        const { stdout } = await execAsync(`${agent.cliCommand} mcp list`);
+        const { stdout } = await execFileAsync(agent.cliCommand, ['mcp', 'list']);
         return stdout.toLowerCase().includes(mcpName.toLowerCase());
     }
     catch {
@@ -637,6 +800,7 @@ export async function isMcpRegistered(agentId, mcpName) {
         return false;
     }
 }
+/** Register an MCP server with an agent's CLI via `mcp add`. */
 export async function registerMcp(agentId, name, command, scope = 'user', transport = 'stdio', options) {
     const agent = AGENTS[agentId];
     if (!agent.capabilities.mcp) {
@@ -648,22 +812,24 @@ export async function registerMcp(agentId, name, command, scope = 'user', transp
     try {
         // Use explicit binary path when provided (bypasses shim for version-managed agents)
         const bin = options?.binary || agent.cliCommand;
-        let cmd;
+        let args;
+        const commandArgs = splitCommandLine(command);
         if (agentId === 'claude') {
-            cmd = `${bin} mcp add --transport ${transport} --scope ${scope} "${name}" -- ${command}`;
+            args = ['mcp', 'add', '--transport', transport, '--scope', scope, name, '--', ...commandArgs];
         }
         else {
-            cmd = `${bin} mcp add "${name}" -- ${command}`;
+            args = ['mcp', 'add', name, '--', ...commandArgs];
         }
         // When home is specified, override HOME so MCP config writes to the version's config dir
         const env = options?.home ? { ...process.env, HOME: options.home } : undefined;
-        await execAsync(cmd, env ? { env } : undefined);
+        await execFileAsync(bin, args, env ? { env } : undefined);
         return { success: true };
     }
     catch (err) {
         return { success: false, error: err.message };
     }
 }
+/** Unregister (remove) a named MCP server from an agent's CLI config. */
 export async function unregisterMcp(agentId, name, options) {
     const agent = AGENTS[agentId];
     if (!agent.capabilities.mcp) {
@@ -675,13 +841,17 @@ export async function unregisterMcp(agentId, name, options) {
     try {
         const bin = options?.binary || agent.cliCommand;
         const env = options?.home ? { ...process.env, HOME: options.home } : undefined;
-        await execAsync(`${bin} mcp remove "${name}"`, env ? { env } : undefined);
+        await execFileAsync(bin, ['mcp', 'remove', name], env ? { env } : undefined);
         return { success: true };
     }
     catch (err) {
         return { success: false, error: err.message };
     }
 }
+/**
+ * Register an MCP server across multiple agent targets, including both direct
+ * (non-version-managed) agents and specific version-managed installs.
+ */
 export async function registerMcpToTargets(targets, name, command, scope = 'user', transport = 'stdio') {
     const results = [];
     for (const agentId of targets.directAgents) {
@@ -699,6 +869,10 @@ export async function registerMcpToTargets(targets, name, command, scope = 'user
     }
     return results;
 }
+/**
+ * Unregister an MCP server from multiple agent targets, including both direct
+ * agents and specific version-managed installs.
+ */
 export async function unregisterMcpFromTargets(targets, name) {
     const results = [];
     for (const agentId of targets.directAgents) {
@@ -718,8 +892,8 @@ export async function unregisterMcpFromTargets(targets, name) {
 }
 /**
  * Extract version from npm package specification.
- * Examples: @swarmify/agents-mcp@latest -> latest
- *           @swarmify/agents-mcp@1.2.3 -> 1.2.3
+ * Examples: @scope/package@latest -> latest
+ *           @scope/package@1.2.3 -> 1.2.3
  *           some-package -> undefined
  */
 function extractNpmVersion(args) {
@@ -1051,7 +1225,7 @@ export function listInstalledMcpsWithScope(agentId, cwd = process.cwd(), options
     }
     return results;
 }
-// Agent name aliases for flexible input
+/** Map of agent name aliases and shorthand identifiers to canonical AgentId values. */
 export const AGENT_NAME_ALIASES = {
     claude: 'claude',
     'claude-code': 'claude',
@@ -1084,13 +1258,15 @@ export const AGENT_NAME_ALIASES = {
     'roo-code': 'roo',
     roocode: 'roo',
 };
+/** Resolve a user-provided agent name (alias, shorthand, or canonical) to its AgentId. */
 export function resolveAgentName(input) {
     return AGENT_NAME_ALIASES[input.toLowerCase()] || null;
 }
+/** Check whether the input string matches any known agent name or alias. */
 export function isAgentName(input) {
     return resolveAgentName(input) !== null;
 }
+/** Format an error message for an unrecognized agent name, listing valid options. */
 export function formatAgentError(agentName, validAgents = ALL_AGENT_IDS) {
     return `Unknown agent '${agentName}'. Valid agents: ${validAgents.join(', ')}`;
 }
-//# sourceMappingURL=agents.js.map