feat: show coding agent availability

Author: SaladDay

README.md

@@ -190,7 +190,7 @@ mmx agent setup --agent codex --agent claude-code --api-key "$MINIMAX_API_KEY" -
 mmx agent setup --all --api-key "$MINIMAX_API_KEY" --region cn --output json
 ```
 
-The command verifies the key and selected region before writing. Existing files are backed up when changed; use `--dry-run` to preview or `--skip-verify` to skip the live request.
+The command verifies the key and selected region before writing. Existing files are backed up when changed; use `--dry-run` to preview or `--skip-verify` to skip the live request. Agent setup only writes configuration files; it does not install or launch the selected agents.
 
 ### `mmx update`
 

README_CN.md

@@ -166,7 +166,7 @@ mmx agent setup --agent codex --agent claude-code --api-key "$MINIMAX_API_KEY" -
 mmx agent setup --all --api-key "$MINIMAX_API_KEY" --region cn --output json
 ```
 
-写入前会验证 Key 和所选区域；修改已有文件时会创建备份。可用 `--dry-run` 预览，或用 `--skip-verify` 跳过联网验证。
+写入前会验证 Key 和所选区域；修改已有文件时会创建备份。可用 `--dry-run` 预览，或用 `--skip-verify` 跳过联网验证。该命令只管理配置文件，不会安装或启动所选 Agent。
 
 ### `mmx update`
 

src/agent/availability.ts

@@ -0,0 +1,38 @@
+import { accessSync, constants, statSync } from 'fs';
+import { delimiter, join } from 'path';
+
+import { AGENT_IDS, type AgentId } from './types';
+
+const AGENT_EXECUTABLES: Record<AgentId, readonly string[]> = {
+  'claude-code': ['claude'],
+  codex: ['codex'],
+  grok: ['grok', 'grok-build', 'grok-cli'],
+  opencode: ['opencode'],
+  hermes: ['hermes'],
+  pi: ['pi'],
+};
+
+export function detectAgentsOnPath(env: NodeJS.ProcessEnv = process.env): Set<AgentId> {
+  const pathValue = process.platform === 'win32' ? env.PATH ?? env.Path : env.PATH;
+  if (pathValue === undefined) return new Set();
+  const directories = pathValue
+    .split(delimiter)
+    .map((directory) => directory.replace(/^"|"$/g, ''));
+  const extensions = process.platform === 'win32'
+    ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';')
+    : [''];
+  const accessMode = process.platform === 'win32' ? constants.F_OK : constants.X_OK;
+
+  return new Set(AGENT_IDS.filter((agent) => AGENT_EXECUTABLES[agent].some(
+    (command) => directories.some((directory) => extensions.some((extension) => {
+      const candidate = join(directory, `${command}${extension}`);
+      try {
+        if (!statSync(candidate).isFile()) return false;
+        accessSync(candidate, accessMode);
+        return true;
+      } catch {
+        return false;
+      }
+    })),
+  )));
+}

src/commands/agent/setup.ts

@@ -3,6 +3,7 @@ import {
   applyAgentConfigurations,
   prepareAgentConfigurations,
 } from '../../agent/configurator';
+import { detectAgentsOnPath } from '../../agent/availability';
 import {
   AGENT_IDS,
   type AgentId,
@@ -44,6 +45,7 @@ const AGENT_LABELS: Record<AgentId, string> = {
   hermes: 'Hermes Agent',
   pi: 'Pi',
 };
+const DEFAULT_INTERACTIVE_AGENTS: AgentId[] = ['claude-code', 'codex'];
 
 function uniqueAgents(values: string[]): AgentId[] {
   const result: AgentId[] = [];
@@ -69,11 +71,17 @@ function isInteractiveInvocation(flags: GlobalFlags): boolean {
 
 async function interactiveOptions(
   config: Config,
+  detectedAgents: Set<AgentId>,
 ): Promise<AgentSetupOptions> {
   const selectedAgents = await promptMultiSelect({
     message: 'Select agents to configure',
-    choices: AGENT_IDS.map((agent) => ({ value: agent, label: AGENT_LABELS[agent] })),
-    initialValues: ['claude-code', 'codex'],
+    choices: AGENT_IDS.map((agent) => ({
+      value: agent,
+      label: detectedAgents.has(agent)
+        ? AGENT_LABELS[agent]
+        : `${AGENT_LABELS[agent]} (not detected on PATH)`,
+    })),
+    initialValues: DEFAULT_INTERACTIVE_AGENTS.filter((agent) => detectedAgents.has(agent)),
     required: true,
   });
   if (!selectedAgents?.length) {
@@ -105,9 +113,13 @@ async function interactiveOptions(
   }
   if (!apiKey) throw new CLIError('An API key is required.', ExitCode.USAGE);
 
-  const confirmed = await promptConfirm({
-    message: `Configure ${agents.map((agent) => AGENT_LABELS[agent]).join(', ')}?`,
-  });
+  const notDetected = agents.filter((agent) => !detectedAgents.has(agent));
+  let message = `Configure ${agents.map((agent) => AGENT_LABELS[agent]).join(', ')}? `
+    + 'mmx will only write configuration files; it will not install or launch agents.';
+  if (notDetected.length > 0) {
+    message += ` Not detected on PATH: ${notDetected.map((agent) => AGENT_LABELS[agent]).join(', ')}.`;
+  }
+  const confirmed = await promptConfirm({ message });
   if (!confirmed) throw new CLIError('Agent setup cancelled.', ExitCode.GENERAL);
 
   return { agents, apiKey, region: selectedRegion, model: 'MiniMax-M3' };
@@ -166,7 +178,7 @@ function nonInteractiveOptions(
 
 export default defineCommand({
   name: 'agent setup',
-  description: 'Configure MiniMax for external coding agents',
+  description: 'Configure external coding agents (does not install or launch them)',
   usage: 'mmx agent setup [--agent <name> ... | --all] [--api-key <key>] [--region <region>]',
   options: [
     {
@@ -185,8 +197,9 @@ export default defineCommand({
     'mmx agent setup --agent opencode --api-key <key> --region cn --dry-run',
   ],
   async run(config: Config, flags: GlobalFlags) {
+    const detectedAgents = detectAgentsOnPath();
     const options = isInteractiveInvocation(flags)
-      ? await interactiveOptions(config)
+      ? await interactiveOptions(config, detectedAgents)
       : nonInteractiveOptions(config, flags);
 
     let verification: AgentVerification = {
@@ -212,5 +225,12 @@ export default defineCommand({
       agents: options.agents,
       files,
     }, format));
+    const notDetected = options.agents.filter((agent) => !detectedAgents.has(agent));
+    if (notDetected.length > 0 && !config.quiet) {
+      process.stderr.write(
+        `Warning: Not detected on PATH: ${notDetected.map((agent) => AGENT_LABELS[agent]).join(', ')}. `
+        + 'mmx only manages configuration; it does not install or launch agents.\n',
+      );
+    }
   },
 });

test/agent/availability.test.ts

@@ -0,0 +1,72 @@
+import { afterEach, describe, expect, it } from 'bun:test';
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+import { detectAgentsOnPath } from '../../src/agent/availability';
+
+describe('agent availability', () => {
+  const roots: string[] = [];
+
+  afterEach(() => {
+    for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+  });
+
+  it('detects supported executable names without treating directories as commands', () => {
+    const root = mkdtempSync(join(tmpdir(), 'mmx-agent-path-'));
+    roots.push(root);
+    const suffix = process.platform === 'win32' ? '.CMD' : '';
+    const executable = join(root, `pi${suffix}`);
+    writeFileSync(executable, '');
+    chmodSync(executable, 0o700);
+    mkdirSync(join(root, `codex${suffix}`));
+
+    const detected = detectAgentsOnPath({
+      PATH: root,
+      PATHEXT: '.COM;.EXE;.BAT;.CMD',
+    });
+
+    expect(detected).toEqual(new Set(['pi']));
+  });
+
+  it('recognizes every supported Grok executable name', () => {
+    const suffix = process.platform === 'win32' ? '.CMD' : '';
+    for (const command of ['grok', 'grok-build', 'grok-cli']) {
+      const root = mkdtempSync(join(tmpdir(), 'mmx-agent-path-'));
+      roots.push(root);
+      const executable = join(root, `${command}${suffix}`);
+      writeFileSync(executable, '');
+      chmodSync(executable, 0o700);
+
+      expect(detectAgentsOnPath({ PATH: root, PATHEXT: '.COM;.EXE;.BAT;.CMD' }).has('grok'))
+        .toBe(true);
+    }
+  });
+
+  it('does not scan the working directory when PATH is missing', () => {
+    const root = mkdtempSync(join(tmpdir(), 'mmx-agent-path-'));
+    roots.push(root);
+    const originalCwd = process.cwd();
+    const suffix = process.platform === 'win32' ? '.CMD' : '';
+    const executable = join(root, `codex${suffix}`);
+    writeFileSync(executable, '');
+    chmodSync(executable, 0o700);
+    process.chdir(root);
+    try {
+      expect(detectAgentsOnPath({})).toEqual(new Set());
+    } finally {
+      process.chdir(originalCwd);
+    }
+  });
+
+  it('does not treat Path as PATH on case-sensitive platforms', () => {
+    if (process.platform === 'win32') return;
+    const root = mkdtempSync(join(tmpdir(), 'mmx-agent-path-'));
+    roots.push(root);
+    const executable = join(root, 'pi');
+    writeFileSync(executable, '');
+    chmodSync(executable, 0o700);
+
+    expect(detectAgentsOnPath({ Path: root })).toEqual(new Set());
+  });
+});

test/commands/agent/setup.test.ts

@@ -15,7 +15,7 @@ function testConfig(overrides: Partial<Config> = {}): Config {
     output: 'json',
     timeout: 30,
     verbose: false,
-    quiet: false,
+    quiet: true,
     noColor: true,
     yes: false,
     dryRun: true,
@@ -165,4 +165,38 @@ describe('agent setup command', () => {
     )).rejects.toThrow('Unsupported agent "typo"');
   });
 
+  it('warns on stderr when a selected agent is not detected on PATH', async () => {
+    const originalPath = process.env.PATH;
+    const originalLog = console.log;
+    const originalWrite = process.stderr.write.bind(process.stderr);
+    let stderr = '';
+    process.env.PATH = home;
+    console.log = () => {};
+    (process.stderr as NodeJS.WriteStream).write = (chunk: unknown) => {
+      stderr += String(chunk);
+      return true;
+    };
+
+    try {
+      await setupCommand.execute(
+        testConfig({ quiet: false }),
+        testFlags({
+          agent: ['pi'],
+          apiKey: 'sk-test-secret',
+          region: 'cn',
+        }),
+      );
+    } finally {
+      if (originalPath === undefined) delete process.env.PATH;
+      else process.env.PATH = originalPath;
+      console.log = originalLog;
+      (process.stderr as NodeJS.WriteStream).write = originalWrite;
+    }
+
+    expect(stderr).toBe(
+      'Warning: Not detected on PATH: Pi. '
+      + 'mmx only manages configuration; it does not install or launch agents.\n',
+    );
+  });
+
 });