@agilemonster/mcp-server 1.0.23 → 1.0.25

package/README.md

@@ -91,6 +91,48 @@ Agents have access to these purpose-built lifecycle tools:
 
 ---
 
+## 🧠 Who works a card that is queued from the board
+
+A card you assign to an agent in the web app is picked up by the background runner on your machine. The
+runner hands it to a **real coding agent running headless in the project folder** — the same agent you use
+in the IDE, with the same ability to search the code, open what it finds, run the build and fix what it broke:
+
+| 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 auth login` |
+| Codex | `codex exec --sandbox workspace-write` | `npm install -g @openai/codex`, then `codex login` |
+
+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.
+
+- **No CLI installed or signed in?** The card falls back to the built-in engine (the server-side model picks
+  a few files and writes one patch). It cannot explore or debug, so it is noticeably weaker; the card tells
+  you what to install or sign in to.
+- **Only your own cards reach the agent.** It can run commands on your machine, so a card or comment written
+  by another board member is never passed to it. Those cards use the built-in engine.
+- **Your uncommitted work is safe.** If the agent touches a file you had open changes in, everything it did
+  is put back and the card asks you to commit or stash first.
+
+| Variable | Effect |
+| :--- | :--- |
+| `AGILEMONSTER_AGENT_ENGINE` | `claude`, `cursor` or `codex` to pin one; `builtin` to never start an agent CLI. |
+| `AGILEMONSTER_AGENT_COMMAND` | Your own command instead. It runs in the project folder with the brief in `$AGILEMONSTER_PROMPT_FILE`; whatever it prints last is the report. |
+| `AGILEMONSTER_AGENT_TIMEOUT_MINUTES` | How long one agent run may take (default 30). |
+
+---
+
 ## 🚀 How deployment is decided (and remembered)
 
 Cards started from the Agile Monster web app run in the background without your IDE's context, so the

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

@@ -0,0 +1,145 @@
+/**
+ * Hands a card to a real coding agent running headless in the project folder — the same Cursor, Claude Code
+ * or Codex agent the developer uses interactively — instead of the built-in "pick six files, generate one
+ * search/replace patch" pipeline.
+ *
+ * The difference is the whole point: an agent with tools can search the repository for "Recently active
+ * projects", open the files it finds, run the type checker and fix what it broke. The built-in pipeline can
+ * do none of that, which is why it asked the requester where things live and gave up on a compile error.
+ *
+ * This module knows how to start each CLI, what the working tree looked like before, and what the agent
+ * changed. It never commits: the runner ships exactly the files reported here through its normal gates.
+ */
+export type EngineId = 'claude' | 'cursor' | 'codex' | 'custom';
+export interface EngineRunOptions {
+    prompt: string;
+    projectPath: string;
+    model?: string | null;
+    /** Continue the agent's own session (it remembers what it did) instead of starting cold. */
+    resumeSessionId?: string | null;
+    timeoutMs?: number;
+}
+export interface EngineRun {
+    ok: boolean;
+    /** The agent's final message. */
+    text: string;
+    sessionId?: string;
+    costUsd?: number;
+    timedOut: boolean;
+    durationMs: number;
+    /** Why the run produced nothing usable (for the log and the card). */
+    failure?: string;
+}
+export interface ResolvedEngine {
+    id: EngineId;
+    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
+ * is installed. `AGILEMONSTER_AGENT_ENGINE` pins the choice (`claude`, `cursor`, `codex`) or switches the
+ * whole thing off (`builtin`); `AGILEMONSTER_AGENT_COMMAND` replaces it with a command of the developer's own.
+ *
+ * `notes` say, in words for the card, why a better engine was passed over — an installed CLI that is not
+ * signed in is one command away from working, and the developer should hear that.
+ */
+export declare function resolveEngines(provider: string): Promise<{
+    engines: ResolvedEngine[];
+    notes: string[];
+}>;
+export declare function agentTimeoutMs(): number;
+/** Run one agent to completion. Never throws: a CLI that is missing, logged out or crashed comes back as `ok: false`. */
+export declare function runEngine(engine: ResolvedEngine, opts: EngineRunOptions): Promise<EngineRun>;
+export interface ConversationTurn {
+    who: 'requester' | 'agent';
+    text: string;
+}
+export interface AgentBrief {
+    title: string;
+    description: string;
+    projectPath: string;
+    boardName?: string | null;
+    conversation: ConversationTurn[];
+    /** Files with the developer's own uncommitted work: off limits. */
+    developerFiles: string[];
+    /** Uncommitted files an earlier attempt at this card left behind: the agent's to continue. */
+    earlierFiles: string[];
+    earlierSummary?: string | null;
+}
+/**
+ * What the agent is told. It reads like a request typed into the IDE — the card, the thread, and the few
+ * rules that differ from an interactive session (nobody is there to answer, and the runner does the shipping).
+ */
+export declare function buildAgentPrompt(brief: AgentBrief): string;
+export interface AgentReport {
+    status: 'done' | 'blocked' | 'unknown';
+    summary: string;
+    verificationSteps: string[];
+    question: string;
+}
+/** Read the closing JSON object out of the agent's final message. Tolerates code fences and prose around it. */
+export declare function parseAgentReport(text: string): AgentReport;
+/** The agent's prose without the closing JSON object: what to show a human when the report is missing a field. */
+export declare function proseOf(text: string, maxChars?: number): string;
+export interface TreeSnapshot {
+    head: string;
+    /** Every path Git reported as changed or untracked, with a fingerprint of its content at that moment. */
+    entries: Map<string, string>;
+    /** Contents of those files, so a file the developer had open can be put back exactly (null = did not exist). */
+    saved: Map<string, Buffer | null>;
+}
+/** Paths from `git status --porcelain -z`. A rename reports both its new and its old path. */
+export declare function parsePorcelainZ(out: string): string[];
+/** Record the working tree before the agent starts. Null when the folder is not a Git repository. */
+export declare function snapshotWorkingTree(projectPath: string): Promise<TreeSnapshot | null>;
+export interface TreeChange {
+    /** Every file that differs from the snapshot. */
+    changed: string[];
+    /** Of those, the ones that already had uncommitted changes before the agent started. */
+    overlapping: string[];
+    /** Set when the agent committed and the commit is already on a remote: it can no longer be folded back. */
+    pushedCommit?: string;
+}
+/**
+ * Compare the working tree with the snapshot. If the agent committed despite its instructions, the commits
+ * are undone first (soft, so nothing is lost) — unless they were pushed, which only a human can sort out.
+ */
+export declare function changesSince(projectPath: string, snap: TreeSnapshot): Promise<TreeChange>;
+/**
+ * Put the given files back the way the snapshot found them. Returns the files that could not be restored
+ * (only possible for a file the developer had changed that was too large to keep a copy of).
+ */
+export declare function restoreWorkingTree(projectPath: string, snap: TreeSnapshot, paths: string[]): Promise<string[]>;
+/**
+ * `git diff` does not show files Git has never seen. Mark the agent's new files as "to be added" (no content
+ * is staged) so the reviewer's diff includes them.
+ */
+export declare function markNewFilesForDiff(projectPath: string, files: string[]): Promise<void>;
+/**
+ * Snapshot the tree before this card's agent starts, and note that a run is in progress.
+ *
+ * `interrupted` is true when an earlier run of the same card never reached a conclusion (the machine slept,
+ * the daemon was killed). Whatever that run left in the tree cannot be told apart from the developer's own
+ * edits, so it is treated as theirs — never reverted, never committed — and the card can say where the
+ * leftovers probably came from.
+ */
+export declare function baselineFor(cardId: string, projectPath: string): Promise<{
+    snapshot: TreeSnapshot;
+    interrupted: boolean;
+} | null>;
+/** The card's run reached a conclusion (shipped, reverted, or handed to the human): it is no longer in progress. */
+export declare function clearBaseline(cardId: string): void;