@phnx-labs/agents-cli 1.20.67 → 1.20.69

package/dist/lib/hosts/remote-cmd.d.ts

@@ -117,6 +117,18 @@ export interface WindowsAgentsCommand {
  * `& agents …` invokes the CLI from the machine PATH (Windows has no login
  * shell, so there is no `bash -lc` equivalent — the shim is simply on PATH).
  */
+/**
+ * PowerShell prelude that silences the progress stream. PowerShell 5.1 serializes
+ * progress records ("Preparing modules for first use.") to CLIXML when stderr is a
+ * redirected pipe (an ssh capture, not a console), so a remote `agents …` result
+ * otherwise comes back wrapped in a raw `#< CLIXML <Objs …>` blob — unreadable to
+ * humans and to the JSON parsers that consume doctor / fleet-status output. Prepend
+ * this to EVERY Windows script that invokes `agents` (there is more than one builder
+ * in this file). Verified against a live win-mini (PowerShell 5.1): this clears it.
+ * (`-OutputFormat Text` does NOT — it governs success-stream object serialization,
+ * not the progress stream.)
+ */
+export declare const POWERSHELL_PROGRESS_SILENCE = "$ProgressPreference = 'SilentlyContinue'";
 export declare function windowsAgentsScript(cmd: WindowsAgentsCommand): string;
 /**
  * Build the `ssh <target> <cmd>` string for one `agents …` invocation on a

package/dist/lib/hosts/remote-cmd.js

@@ -110,6 +110,7 @@ export const RUN_OPTION_FORWARDING = {
     lease: 'local-only',
     keepBox: 'local-only',
     copyCreds: 'local-only', // copies creds TO the host before dispatch — local concern only
+    authCheck: 'local-only', // --no-auth-check gates the local interactive login preflight; --host runs skip that preflight entirely
 };
 /** Actionable messages for value-aware rejections, keyed by attribute name. */
 export const RUN_OPTION_REJECT_MESSAGES = {
@@ -190,9 +191,21 @@ export function decodePowershell(encoded) {
  * `& agents …` invokes the CLI from the machine PATH (Windows has no login
  * shell, so there is no `bash -lc` equivalent — the shim is simply on PATH).
  */
+/**
+ * PowerShell prelude that silences the progress stream. PowerShell 5.1 serializes
+ * progress records ("Preparing modules for first use.") to CLIXML when stderr is a
+ * redirected pipe (an ssh capture, not a console), so a remote `agents …` result
+ * otherwise comes back wrapped in a raw `#< CLIXML <Objs …>` blob — unreadable to
+ * humans and to the JSON parsers that consume doctor / fleet-status output. Prepend
+ * this to EVERY Windows script that invokes `agents` (there is more than one builder
+ * in this file). Verified against a live win-mini (PowerShell 5.1): this clears it.
+ * (`-OutputFormat Text` does NOT — it governs success-stream object serialization,
+ * not the progress stream.)
+ */
+export const POWERSHELL_PROGRESS_SILENCE = "$ProgressPreference = 'SilentlyContinue'";
 export function windowsAgentsScript(cmd) {
     const { args, env, cwd, propagateExit = true } = cmd;
-    const parts = [];
+    const parts = [POWERSHELL_PROGRESS_SILENCE];
     if (env)
         for (const [k, v] of Object.entries(env))
             parts.push(`$env:${k} = ${powershellQuote(v)}`);
@@ -232,6 +245,9 @@ export function buildWindowsStdinImportCommand(bundle, opts = {}) {
     // the secret-bearing temp file would otherwise be left behind (RUSH-1764). $tmp
     // starts null so a GetTempFileName that itself throws leaves nothing to remove.
     const script = [
+        // Same CLIXML guard as windowsAgentsScript — this builder also runs `& agents …`
+        // and its raw stderr is printed to the user on failure (secrets export --host <win>).
+        POWERSHELL_PROGRESS_SILENCE,
         '$in = [Console]::In.ReadToEnd()',
         '$tmp = $null',
         `try { $tmp = [System.IO.Path]::GetTempFileName(); [System.IO.File]::WriteAllText($tmp, $in); ` +

package/dist/lib/mcp.d.ts

@@ -108,6 +108,27 @@ export declare function registerMcpCommandToTargets(targets: {
     directAgents: AgentId[];
     versionSelections: Map<AgentId, string[]>;
 }, name: string, commandSpec: McpCommandSpec, scope?: 'user' | 'project', transport?: string): Promise<McpTargetOperationResult[]>;
+/**
+ * MCP server shaped for direct config-file serialization.
+ */
+export interface WritableMcpServer {
+    name: string;
+    transport: 'stdio' | 'http' | 'sse';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Serialize MCP servers into an agent-specific config file.
+ *
+ * `mode: 'overwrite'` replaces the whole MCP section (used for tool-managed
+ * version-home configs). `mode: 'merge'` updates/adds the provided server
+ * entries while preserving existing entries (used for project-level configs
+ * that users may hand-edit or populate via agent CLI commands).
+ */
+export declare function writeMcpConfig(agentId: AgentId, configPath: string, servers: WritableMcpServer[], mode?: 'overwrite' | 'merge'): void;
 /**
  * Install MCP servers to an agent.
  * For Claude/Codex: uses CLI commands (claude mcp add, codex mcp add)

package/dist/lib/mcp.js

@@ -10,12 +10,13 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
+import * as TOML from 'smol-toml';
 import { execFileSync } from 'child_process';
 import * as os from 'os';
 import { getMcpDir, getUserMcpDir, getProjectAgentsDir, getVersionsDir, getUserAgentsDir } from './state.js';
 import { getBinaryPath, getVersionHomePath } from './versions.js';
 import { IS_WINDOWS, execFileShellSpec } from './platform/index.js';
-import { AGENTS } from './agents.js';
+import { AGENTS, getMcpConfigPathForHome, getProjectMcpConfigPath } from './agents.js';
 import { isCapable } from './capabilities.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
 /**
@@ -634,6 +635,225 @@ function installMcpToOpenCodeConfig(server, versionHome) {
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
 }
+/**
+ * Agents whose config file format is implemented by `writeMcpConfig`.
+ * Others are intentionally skipped until their schema is added.
+ */
+function writeMcpConfigSupportsAgent(agentId) {
+    switch (agentId) {
+        case 'claude':
+        case 'cursor':
+        case 'gemini':
+        case 'kimi':
+        case 'droid':
+        case 'forge':
+        case 'openclaw':
+        case 'codex':
+        case 'grok':
+        case 'opencode':
+        case 'hermes':
+            return true;
+        default:
+            return false;
+    }
+}
+/**
+ * Serialize MCP servers into an agent-specific config file.
+ *
+ * `mode: 'overwrite'` replaces the whole MCP section (used for tool-managed
+ * version-home configs). `mode: 'merge'` updates/adds the provided server
+ * entries while preserving existing entries (used for project-level configs
+ * that users may hand-edit or populate via agent CLI commands).
+ */
+export function writeMcpConfig(agentId, configPath, servers, mode = 'overwrite') {
+    if (servers.length === 0) {
+        return;
+    }
+    switch (agentId) {
+        case 'claude':
+        case 'cursor':
+        case 'gemini':
+        case 'kimi':
+        case 'droid':
+        case 'forge': {
+            let config = {};
+            if (fs.existsSync(configPath)) {
+                try {
+                    config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+                }
+                catch {
+                    config = {};
+                }
+            }
+            const mcpServers = mode === 'merge' && config.mcpServers && typeof config.mcpServers === 'object'
+                ? { ...config.mcpServers }
+                : {};
+            for (const server of servers) {
+                if (server.transport === 'stdio') {
+                    mcpServers[server.name] = {
+                        command: server.command,
+                        args: server.args || [],
+                        env: server.env || {},
+                    };
+                }
+                else {
+                    mcpServers[server.name] = {
+                        url: server.url,
+                        ...(server.headers && { headers: server.headers }),
+                    };
+                }
+            }
+            config.mcpServers = mcpServers;
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+            break;
+        }
+        case 'openclaw': {
+            let config = {};
+            if (fs.existsSync(configPath)) {
+                try {
+                    config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+                }
+                catch {
+                    config = {};
+                }
+            }
+            if (!config.mcp || typeof config.mcp !== 'object') {
+                config.mcp = {};
+            }
+            const mcp = config.mcp;
+            const mcpServers = mode === 'merge' && mcp.servers && typeof mcp.servers === 'object'
+                ? { ...mcp.servers }
+                : {};
+            for (const server of servers) {
+                if (server.transport === 'stdio') {
+                    mcpServers[server.name] = {
+                        command: server.command,
+                        args: server.args || [],
+                        env: server.env || {},
+                    };
+                }
+                else {
+                    mcpServers[server.name] = {
+                        url: server.url,
+                        transport: server.transport,
+                        ...(server.headers && { headers: server.headers }),
+                    };
+                }
+            }
+            mcp.servers = mcpServers;
+            config.mcp = mcp;
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+            break;
+        }
+        case 'codex':
+        case 'grok': {
+            let config = {};
+            if (fs.existsSync(configPath)) {
+                try {
+                    config = TOML.parse(fs.readFileSync(configPath, 'utf-8'));
+                }
+                catch {
+                    config = {};
+                }
+            }
+            const mcpServers = mode === 'merge' && config.mcp_servers && typeof config.mcp_servers === 'object'
+                ? { ...config.mcp_servers }
+                : {};
+            for (const server of servers) {
+                if (server.transport === 'stdio') {
+                    mcpServers[server.name] = {
+                        command: server.command,
+                        args: server.args || [],
+                        ...(server.env && { env: server.env }),
+                    };
+                }
+                else {
+                    mcpServers[server.name] = {
+                        url: server.url,
+                        ...(server.headers && { headers: server.headers }),
+                    };
+                }
+            }
+            config.mcp_servers = mcpServers;
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, TOML.stringify(config), 'utf-8');
+            break;
+        }
+        case 'opencode': {
+            let config = {};
+            if (fs.existsSync(configPath)) {
+                try {
+                    const content = fs.readFileSync(configPath, 'utf-8');
+                    const jsonContent = content.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
+                    config = JSON.parse(jsonContent);
+                }
+                catch {
+                    config = {};
+                }
+            }
+            const mcp = mode === 'merge' && config.mcp && typeof config.mcp === 'object'
+                ? { ...config.mcp }
+                : {};
+            for (const server of servers) {
+                if (server.transport === 'stdio') {
+                    const commandArray = [server.command, ...(server.args || [])];
+                    mcp[server.name] = {
+                        type: 'local',
+                        command: commandArray,
+                        ...(server.env && { env: server.env }),
+                    };
+                }
+                else {
+                    mcp[server.name] = {
+                        type: 'remote',
+                        url: server.url,
+                    };
+                }
+            }
+            config.mcp = mcp;
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+            break;
+        }
+        case 'hermes': {
+            let config = {};
+            if (fs.existsSync(configPath)) {
+                try {
+                    const parsed = yaml.parse(fs.readFileSync(configPath, 'utf-8'));
+                    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                        config = parsed;
+                    }
+                }
+                catch {
+                    config = {};
+                }
+            }
+            const mcpServers = mode === 'merge' && config.mcp_servers && typeof config.mcp_servers === 'object' && !Array.isArray(config.mcp_servers)
+                ? { ...config.mcp_servers }
+                : {};
+            for (const server of servers) {
+                if (server.transport === 'stdio') {
+                    mcpServers[server.name] = {
+                        command: server.command,
+                        args: server.args || [],
+                        ...(server.env && { env: server.env }),
+                    };
+                }
+                else {
+                    mcpServers[server.name] = {
+                        url: server.url,
+                    };
+                }
+            }
+            config.mcp_servers = mcpServers;
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, yaml.stringify(config), 'utf-8');
+            break;
+        }
+    }
+}
 /**
  * Install MCP servers to an agent.
  * For Claude/Codex: uses CLI commands (claude mcp add, codex mcp add)
@@ -658,47 +878,92 @@ export function installMcpServers(agentId, version, versionHome, mcpNames, optio
         binaryPath += '.cmd';
     }
     for (const server of servers) {
+        let handled = false;
         try {
             if (agentId === 'claude') {
                 installMcpViaClaude(binaryPath, server, versionHome);
-                applied.push(server.name);
+                handled = true;
             }
             else if (agentId === 'codex') {
                 installMcpViaCodex(binaryPath, server, versionHome);
-                applied.push(server.name);
+                handled = true;
             }
             else if (agentId === 'gemini') {
                 installMcpToGeminiConfig(server, versionHome);
-                applied.push(server.name);
+                handled = true;
             }
             else if (agentId === 'cursor') {
                 installMcpToCursorConfig(server, versionHome);
-                applied.push(server.name);
+                handled = true;
             }
             else if (agentId === 'opencode') {
                 installMcpToOpenCodeConfig(server, versionHome);
-                applied.push(server.name);
+                handled = true;
+            }
+            else if (agentId === 'openclaw') {
+                // OpenClaw has no install CLI; write the JSON config directly.
+                // Use merge because this loop runs once per server.
+                const userConfigPath = getMcpConfigPathForHome(agentId, versionHome);
+                const writableServer = {
+                    name: server.config.name,
+                    transport: server.config.transport,
+                    command: server.config.command,
+                    args: server.config.args,
+                    env: server.config.env,
+                    url: server.config.url,
+                };
+                writeMcpConfig(agentId, userConfigPath, [writableServer], 'merge');
+                handled = true;
             }
             else if (agentId === 'grok') {
-                // Grok primarily uses [mcp_servers] in ~/.grok/config.toml (or project .grok/config.toml).
-                // We have the path helper; full writer can be added (reuse codex toml pattern).
-                // For now the general sync + toml editing via agents mcp works via the path helpers.
-                applied.push(server.name);
+                // Grok has no working `grok mcp add` CLI, so write the TOML config
+                // directly into the version-home directory for all scopes.
+                // Use merge because this loop runs once per server.
+                const userConfigPath = getMcpConfigPathForHome(agentId, versionHome);
+                const writableServer = {
+                    name: server.config.name,
+                    transport: server.config.transport,
+                    command: server.config.command,
+                    args: server.config.args,
+                    env: server.config.env,
+                    url: server.config.url,
+                };
+                writeMcpConfig(agentId, userConfigPath, [writableServer], 'merge');
+                handled = true;
             }
             else if (agentId === 'kimi') {
                 installMcpToKimiConfig(server, versionHome);
-                applied.push(server.name);
+                handled = true;
             }
             else if (agentId === 'droid') {
                 installMcpToFactoryConfig(server, versionHome);
-                applied.push(server.name);
+                handled = true;
             }
             else if (agentId === 'hermes') {
                 installMcpToHermesConfig(server, versionHome);
-                applied.push(server.name);
+                handled = true;
             }
             else if (agentId === 'forge') {
                 installMcpToForgeConfig(server, versionHome);
+                handled = true;
+            }
+            // Project-layer servers also get merged into the agent's project-level
+            // config (e.g., .mcp.json, .codex/config.toml) so the CLI discovers them
+            // when run inside the repo.
+            if (server.scope === 'project' && options.cwd && writeMcpConfigSupportsAgent(agentId)) {
+                const projectConfigPath = getProjectMcpConfigPath(agentId, options.cwd);
+                const writableServer = {
+                    name: server.config.name,
+                    transport: server.config.transport,
+                    command: server.config.command,
+                    args: server.config.args,
+                    env: server.config.env,
+                    url: server.config.url,
+                };
+                writeMcpConfig(agentId, projectConfigPath, [writableServer], 'merge');
+                handled = true;
+            }
+            if (handled) {
                 applied.push(server.name);
             }
         }