@agilemonster/mcp-server 1.0.24 → 1.0.25

package/README.md

@@ -100,11 +100,20 @@ in the IDE, with the same ability to search the code, open what it finds, run th
 | Card's agent | Command line agent used | One-time setup |
 | :--- | :--- | :--- |
 | Cursor | `cursor-agent -p --force` | `curl https://cursor.com/install -fsS \| bash`, then `cursor-agent login` |
-| Claude Code | `claude -p --permission-mode acceptEdits` | `npm install -g @anthropic-ai/claude-code`, then `claude` once to sign in |
+| Claude Code | `claude -p --permission-mode acceptEdits` | `npm install -g @anthropic-ai/claude-code`, then `claude auth login` |
 | Codex | `codex exec --sandbox workspace-write` | `npm install -g @openai/codex`, then `codex login` |
 
-If the card's own agent has no CLI here, any other installed one is used and the card says which. The agent
-gets the card, the requester's replies on it, and three rules: decide open details the way the codebase
+The runner also finds an agent that is not on your `PATH` — for example the Codex CLI that the Codex app and
+its IDE plugin install, already signed in with your ChatGPT account — so there is often nothing to set up.
+If the card's own agent cannot run here, any other ready one stands in and the card says which, and why.
+
+To see what this machine will use, and the one step that would fix an agent that is not ready:
+
+```bash
+npx @agilemonster/mcp-server agents
+```
+
+The agent gets the card, the requester's replies on it, and three rules: decide open details the way the codebase
 already does instead of asking, check your own work, and do not commit — the runner commits and deploys
 exactly the files the agent changed, after its own build check.
 

package/bin/mcp.js

@@ -23,6 +23,14 @@ const firstArg = process.argv[2];
 if (firstArg === '--version' || firstArg === '-v' || firstArg === 'version') {
   console.log(MCP_SERVER_VERSION);
   process.exit(0);
+} else if (firstArg === 'agents' || firstArg === 'doctor') {
+  // Which coding agent on this machine works a card queued from the board, and what would fix the others
+  const { describeAgents, forgetEngineReadiness } = await import('../dist/agent-engine.js');
+  const { ensureUserPath } = await import('../dist/runtime.js');
+  await ensureUserPath();
+  forgetEngineReadiness();
+  console.log(await describeAgents());
+  process.exit(0);
 } else if (firstArg === 'pulse-daemon' || firstArg === '--pulse-daemon') {
   runBackgroundPulseDaemon(20000).catch((err) => {
     console.error('Fatal Pulse Daemon Error:', err);

package/dist/agent-engine.d.ts

@@ -35,6 +35,19 @@ export interface ResolvedEngine {
     label: string;
     bin: string;
 }
+/** Forget cached sign-in checks (a developer who just signed in should not wait out the cache; tests). */
+export declare function forgetEngineReadiness(): void;
+export interface EngineStatus {
+    id: EngineId;
+    label: string;
+    bin: string | null;
+    /** Null when this agent can take a card now, otherwise what stands in the way, in words for the developer. */
+    problem: string | null;
+}
+/** Every agent CLI this runner knows, and whether each can take a card on this machine right now. */
+export declare function engineStatuses(): Promise<EngineStatus[]>;
+/** What `agilemonster agents` prints: which agent works a queued card here, and the one step that would fix the others. */
+export declare function describeAgents(): Promise<string>;
 export declare function engineLabelFor(provider: string): string | null;
 /**
  * The agent CLIs this machine can run for a card, best first: the card's own agent, then any other one that

package/dist/agent-engine.js

@@ -41,7 +41,18 @@ const ENGINES = [
         label: 'Claude Code',
         providers: ['claude_code'],
         bins: ['claude'],
+        locations: () => [path.join(os.homedir(), '.local', 'bin', 'claude'), path.join(os.homedir(), '.claude', 'local', 'claude')],
         installHint: 'npm install -g @anthropic-ai/claude-code',
+        ready: async (bin) => {
+            if ((process.env.ANTHROPIC_API_KEY || process.env.CLAUDE_CODE_OAUTH_TOKEN || '').trim())
+                return null;
+            const status = await exec(bin, ['auth', 'status'], { timeoutMs: 20000 });
+            const info = lastJsonValue(status.stdout);
+            // Only a plain "not signed in to Anthropic" is certain. Bedrock, Vertex and older CLIs answer differently: let the run tell.
+            return info && typeof info === 'object' && info.loggedIn === false && (!info.apiProvider || info.apiProvider === 'firstParty')
+                ? 'it is installed but not signed in — run `claude auth login` once in a terminal'
+                : null;
+        },
         args: (opts) => {
             // The prompt directly follows -p; the list-valued flags come last so they cannot swallow it.
             const args = ['-p', opts.prompt, '--output-format', 'json', '--permission-mode', 'acceptEdits'];
@@ -71,6 +82,7 @@ const ENGINES = [
         label: 'Cursor Agent',
         providers: ['cursor'],
         bins: ['cursor-agent'],
+        locations: () => [path.join(os.homedir(), '.local', 'bin', 'cursor-agent')],
         installHint: 'curl https://cursor.com/install -fsS | bash',
         ready: async (bin) => {
             if ((process.env.CURSOR_API_KEY || '').trim())
@@ -106,8 +118,28 @@ const ENGINES = [
         label: 'Codex',
         providers: ['codex'],
         bins: ['codex'],
+        // The Codex app and its IDE plugin ship the same CLI, already signed in with the developer's ChatGPT account
+        locations: () => [
+            path.join(os.homedir(), '.codex', 'plugins', '.plugin-appserver', 'codex-cli', 'bin', 'codex'),
+            '/Applications/Codex.app/Contents/Resources/codex',
+        ],
         installHint: 'npm install -g @openai/codex',
-        args: (opts, scratch) => ['exec', '--sandbox', 'workspace-write', '--skip-git-repo-check', '-o', scratch.lastMessageFile, opts.prompt],
+        ready: async (bin) => {
+            if ((process.env.CODEX_API_KEY || '').trim())
+                return null;
+            const status = await exec(bin, ['login', 'status'], { timeoutMs: 20000 });
+            return /not logged in/i.test(`${status.stdout}\n${status.stderr}`)
+                ? 'it is installed but not signed in — run `codex login` once in a terminal'
+                : null;
+        },
+        args: (opts, scratch) => {
+            // workspace-write keeps its edits inside the project; network stays on so it can install and build like the IDE does
+            const args = ['exec', '--sandbox', 'workspace-write', '-c', 'sandbox_workspace_write.network_access=true', '--skip-git-repo-check'];
+            if (opts.model && /^gpt-/i.test(opts.model))
+                args.push('-m', opts.model);
+            args.push('-o', scratch.lastMessageFile, opts.prompt);
+            return args;
+        },
         parse: (res, scratch) => {
             let text = '';
             try {
@@ -124,6 +156,77 @@ function customCommand() {
 }
 const READY_TTL_MS = 2 * 60 * 1000;
 const readyCache = new Map();
+/** Forget cached sign-in checks (a developer who just signed in should not wait out the cache; tests). */
+export function forgetEngineReadiness() {
+    readyCache.clear();
+}
+function isExecutableFile(file) {
+    try {
+        fs.accessSync(file, fs.constants.X_OK);
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** The engine's CLI: on PATH, or where its installer, IDE plugin or desktop app keeps it. */
+function findBin(spec) {
+    for (const bin of spec.bins) {
+        const onPath = which(bin);
+        if (onPath)
+            return onPath;
+    }
+    for (const candidate of spec.locations ? spec.locations() : []) {
+        if (isExecutableFile(candidate))
+            return candidate;
+    }
+    return null;
+}
+/** Every agent CLI this runner knows, and whether each can take a card on this machine right now. */
+export async function engineStatuses() {
+    const out = [];
+    for (const spec of ENGINES) {
+        const bin = findBin(spec);
+        out.push({
+            id: spec.id,
+            label: spec.label,
+            bin,
+            problem: bin ? await readiness(spec, bin) : `it is not installed (\`${spec.installHint}\`)`,
+        });
+    }
+    return out;
+}
+/** What `agilemonster agents` prints: which agent works a queued card here, and the one step that would fix the others. */
+export async function describeAgents() {
+    const pinned = (process.env.AGILEMONSTER_AGENT_ENGINE || '').trim().toLowerCase();
+    const lines = ['Coding agents on this machine that can work a card queued from the board:', ''];
+    if (customCommand())
+        lines.push(`  ✓ Your own command   AGILEMONSTER_AGENT_COMMAND=${customCommand()}`, '');
+    const statuses = await engineStatuses();
+    for (const s of statuses) {
+        lines.push(`  ${s.problem ? '✗' : '✓'} ${s.label.padEnd(14)} ${s.problem ? s.problem : s.bin}`);
+    }
+    lines.push('');
+    const usable = statuses.filter((s) => !s.problem);
+    if (['builtin', 'built-in', 'off', 'none', '0', 'false'].includes(pinned)) {
+        lines.push('AGILEMONSTER_AGENT_ENGINE switches agents off: every card runs on the built-in engine (a few files, one pass).');
+    }
+    else if (customCommand()) {
+        lines.push('Every card you created is handed to your own command.');
+    }
+    else if (usable.length === 0) {
+        lines.push('None is ready, so cards run on the built-in engine, which edits a few files in one pass and cannot explore or build.');
+        lines.push('Fix any one line above and the next card is worked by a real agent.');
+    }
+    else {
+        for (const s of statuses) {
+            const worker = s.problem ? usable[0] : s;
+            lines.push(`A card assigned to ${s.label.replace(/ Agent$/, '')} is worked by ${worker.label}${s.problem ? ` (standing in)` : ''}.`);
+        }
+        lines.push('Cards a teammate created always use the built-in engine: an agent with a shell only works cards you wrote.');
+    }
+    return lines.join('\n');
+}
 async function readiness(spec, bin) {
     if (!spec.ready)
         return null;
@@ -167,7 +270,7 @@ export async function resolveEngines(provider) {
     const notes = [];
     for (const spec of ordered) {
         const isNative = native.includes(spec);
-        const bin = spec.bins.map((b) => which(b)).find(Boolean) || null;
+        const bin = findBin(spec);
         if (!bin) {
             if (isNative)
                 notes.push(`${spec.label}'s command line agent is not installed on this machine (\`${spec.installHint}\`)`);

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { ActiveClaim, AgileMonsterProjectConfig, AutonomousStepResponse, CardComment, DeployReport, Board, BoardAgentConfig, Card, ContextResponse, DiscoveredProject, PulseResponse } from './types.js';
-export declare const MCP_SERVER_VERSION = "1.0.24";
+export declare const MCP_SERVER_VERSION = "1.0.25";
 /** An API call the server answered with an error status. `status` lets callers tell "refused" from "broken". */
 export declare class ApiError extends Error {
     readonly status: number;

package/dist/client.js

@@ -4,7 +4,7 @@ import { execSync } from 'node:child_process';
 import { resolveDeployProfile } from './deploy-profile.js';
 import { loadMemory } from './deploy-memory.js';
 import { stripRemoteCredentials } from './redact.js';
-export const MCP_SERVER_VERSION = '1.0.24';
+export const MCP_SERVER_VERSION = '1.0.25';
 /** An API call the server answered with an error status. `status` lets callers tell "refused" from "broken". */
 export class ApiError extends Error {
     status;

package/dist/server.js

@@ -13,7 +13,7 @@ import { knownSecrets, redactResult } from './redact.js';
 import { describeProfile, methodLabel, normalizeMethod, resolveDeployProfile, trustBoundRoute, } from './deploy-profile.js';
 import { addPendingVerification, getCardState, loadMemory, recordAttempt, removePendingVerification, setCardState, setExplicitProfile, } from './deploy-memory.js';
 import { checkCiOnce, describeFailureForHuman, ensureLocalGitExcludes, parseDeployDirective, runDeployment, } from './deploy-runner.js';
-import { baselineFor, buildAgentPrompt, changesSince, clearBaseline, engineLabelFor, markNewFilesForDiff, parseAgentReport, proseOf, resolveEngines, restoreWorkingTree, runEngine, } from './agent-engine.js';
+import { baselineFor, buildAgentPrompt, changesSince, clearBaseline, engineLabelFor, engineStatuses, markNewFilesForDiff, parseAgentReport, proseOf, resolveEngines, restoreWorkingTree, runEngine, } from './agent-engine.js';
 import { addWellKnownToolDirs, agileMonsterHome, configureLogger, ensureUserPath, errorMessage, exec, log, readJson, which, writeJsonAtomic, } from './runtime.js';
 export function createServer(client = new AgileMonsterClient()) {
     const server = new Server({
@@ -1878,8 +1878,10 @@ async function produceChangeWithAgent(run) {
     const { client, card, projectPath, provider, workerLabel, lockFile, carryOverFiles } = run;
     const { engines, notes } = await resolveEngines(provider);
     run.engineNotes.push(...notes);
-    if (engines.length === 0)
+    if (engines.length === 0) {
+        log.info('agent.unavailable', { card: card.id, provider, notes });
         return 'unavailable';
+    }
     // The agent gets a shell. Like a deploy command, what runs on this machine is for its owner to decide:
     // only cards its owner wrote are handed over (and only the owner's replies were kept in the conversation).
     if (!run.ownerId || !card.created_by || card.created_by !== run.ownerId) {
@@ -1931,8 +1933,14 @@ async function produceChangeWithAgent(run) {
     // 1. Run the first agent that actually starts. One that is logged out or crashes on launch touches nothing.
     let engine = engines[0];
     let result = null;
+    const nativeLabel = engineLabelFor(provider);
     for (const candidate of engines) {
-        await client.addProgress(card.id, provider, `Autonomous background runner claimed task in \`${projectPath}\` and moved card to **In Progress**. **${candidate.label}** is working on it in the project folder — reading, searching, editing and building, as it would in the IDE.`);
+        // A card assigned to Cursor that Codex ends up working must say so, with the one step that fixes it
+        const passedOver = nativeLabel && candidate.label !== nativeLabel ? run.engineNotes.filter((n) => n.startsWith(nativeLabel)) : [];
+        await client.addProgress(card.id, provider, `Autonomous background runner claimed task in \`${projectPath}\` and moved card to **In Progress**. **${candidate.label}** is working on it in the project folder — reading, searching, editing and building, as it would in the IDE.` +
+            (passedOver.length > 0
+                ? `\n\n${candidate.label} is standing in for ${nativeLabel}, which cannot run on this machine yet:\n${passedOver.map((n) => `- ${n}`).join('\n')}`
+                : ''));
         log.info('agent.start', { card: card.id, engine: candidate.id, project: projectPath });
         const attempt = await runEngine(candidate, { prompt, projectPath, model });
         log.info('agent.end', { card: card.id, engine: candidate.id, ok: attempt.ok, seconds: Math.round(attempt.durationMs / 1000), failure: attempt.failure });
@@ -3079,6 +3087,10 @@ export async function runBackgroundPulseDaemon(intervalMs = 20000) {
         log.error('daemon.uncaught_exception', { error: errorMessage(err), stack: err instanceof Error ? err.stack : undefined });
         process.exit(1);
     });
+    // Which agent will work a queued card here, on record before the first card arrives
+    engineStatuses()
+        .then((agents) => log.info('daemon.agents', { agents: agents.map((a) => ({ id: a.id, ready: !a.problem, bin: a.bin, problem: a.problem })) }))
+        .catch(() => { });
     startBuiltInPullPulse(null, client, intervalMs, 'daemon');
     // Watch dist/server.js for updates so launchd reloads new code after a rebuild — but only between jobs,
     // never in the middle of an edit or a deployment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agilemonster/mcp-server",
-  "version": "1.0.24",
+  "version": "1.0.25",
   "type": "module",
   "description": "Official Model Context Protocol (MCP) server & Orchestrator for Agile Monster (Cursor, Claude Code, Antigravity, Codex, Hermes, Windsurf)",
   "main": "dist/server.js",