@agilemonster/mcp-server 1.0.22 → 1.0.24

package/dist/agent-engine.js

@@ -0,0 +1,517 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { agileMonsterHome, exec, execShell, readJson, which, writeJsonAtomic } from './runtime.js';
+/** The last complete JSON value an agent CLI printed (they print one result object, sometimes after other lines). */
+function lastJsonValue(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return null;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch { }
+    const lines = trimmed.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].trim();
+        if (!line.startsWith('{') && !line.startsWith('['))
+            continue;
+        try {
+            return JSON.parse(line);
+        }
+        catch { }
+    }
+    return null;
+}
+function resultObject(stdout) {
+    const value = lastJsonValue(stdout);
+    if (Array.isArray(value)) {
+        for (let i = value.length - 1; i >= 0; i--) {
+            if (value[i] && typeof value[i] === 'object' && value[i].type === 'result')
+                return value[i];
+        }
+        return null;
+    }
+    return value && typeof value === 'object' ? value : null;
+}
+const ENGINES = [
+    {
+        id: 'claude',
+        label: 'Claude Code',
+        providers: ['claude_code'],
+        bins: ['claude'],
+        installHint: 'npm install -g @anthropic-ai/claude-code',
+        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'];
+            if (opts.resumeSessionId)
+                args.push('--resume', opts.resumeSessionId);
+            if (opts.model && /^(claude|opus|sonnet|haiku|fable)/i.test(opts.model))
+                args.push('--model', opts.model);
+            // Shell access is what lets it run the build and the tests. The card's status belongs to the runner.
+            args.push('--allowedTools', 'Bash', '--disallowedTools', 'mcp__agilemonster');
+            return args;
+        },
+        parse: (res) => {
+            const obj = resultObject(res.stdout);
+            if (!obj)
+                return { text: res.stdout.trim() };
+            const text = typeof obj.result === 'string' ? obj.result : '';
+            return {
+                text,
+                sessionId: typeof obj.session_id === 'string' ? obj.session_id : undefined,
+                costUsd: typeof obj.total_cost_usd === 'number' ? obj.total_cost_usd : undefined,
+                error: obj.is_error ? text || String(obj.subtype || 'the run reported an error') : undefined,
+            };
+        },
+    },
+    {
+        id: 'cursor',
+        label: 'Cursor Agent',
+        providers: ['cursor'],
+        bins: ['cursor-agent'],
+        installHint: 'curl https://cursor.com/install -fsS | bash',
+        ready: async (bin) => {
+            if ((process.env.CURSOR_API_KEY || '').trim())
+                return null;
+            const status = await exec(bin, ['status'], { timeoutMs: 20000 });
+            return /not logged in/i.test(`${status.stdout}\n${status.stderr}`)
+                ? 'it is installed but not signed in — run `cursor-agent login` once in a terminal'
+                : null;
+        },
+        args: (opts) => {
+            const args = ['-p', '--force', '--trust', '--output-format', 'json', '--workspace', opts.projectPath];
+            if (opts.resumeSessionId)
+                args.push('--resume', opts.resumeSessionId);
+            if (opts.model)
+                args.push('--model', opts.model);
+            args.push(opts.prompt);
+            return args;
+        },
+        parse: (res) => {
+            const obj = resultObject(res.stdout);
+            if (!obj)
+                return { text: res.stdout.trim() };
+            const text = typeof obj.result === 'string' ? obj.result : '';
+            return {
+                text,
+                sessionId: typeof obj.session_id === 'string' ? obj.session_id : undefined,
+                error: obj.is_error ? text || 'the run reported an error' : undefined,
+            };
+        },
+    },
+    {
+        id: 'codex',
+        label: 'Codex',
+        providers: ['codex'],
+        bins: ['codex'],
+        installHint: 'npm install -g @openai/codex',
+        args: (opts, scratch) => ['exec', '--sandbox', 'workspace-write', '--skip-git-repo-check', '-o', scratch.lastMessageFile, opts.prompt],
+        parse: (res, scratch) => {
+            let text = '';
+            try {
+                text = fs.readFileSync(scratch.lastMessageFile, 'utf8').trim();
+            }
+            catch { }
+            return { text: text || res.stdout.trim() };
+        },
+    },
+];
+const CUSTOM_ENGINE = { id: 'custom', label: 'your agent command', bin: '' };
+function customCommand() {
+    return (process.env.AGILEMONSTER_AGENT_COMMAND || '').trim();
+}
+const READY_TTL_MS = 2 * 60 * 1000;
+const readyCache = new Map();
+async function readiness(spec, bin) {
+    if (!spec.ready)
+        return null;
+    const cached = readyCache.get(bin);
+    if (cached && Date.now() - cached.at < READY_TTL_MS)
+        return cached.reason;
+    let reason = null;
+    try {
+        reason = await spec.ready(bin);
+    }
+    catch {
+        reason = null; // an unanswerable check must not hide a working agent: the run itself will tell
+    }
+    readyCache.set(bin, { at: Date.now(), reason });
+    return reason;
+}
+export function engineLabelFor(provider) {
+    const spec = ENGINES.find((e) => e.providers.includes((provider || '').toLowerCase()));
+    return spec ? spec.label : 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 async function resolveEngines(provider) {
+    const pinned = (process.env.AGILEMONSTER_AGENT_ENGINE || '').trim().toLowerCase();
+    if (['builtin', 'built-in', 'off', 'none', '0', 'false'].includes(pinned))
+        return { engines: [], notes: [] };
+    if (customCommand() && (!pinned || pinned === 'auto' || pinned === 'custom'))
+        return { engines: [CUSTOM_ENGINE], notes: [] };
+    const prov = (provider || '').toLowerCase();
+    const native = ENGINES.filter((e) => e.providers.includes(prov));
+    let ordered = [...native, ...ENGINES.filter((e) => !native.includes(e))];
+    if (pinned && pinned !== 'auto')
+        ordered = ENGINES.filter((e) => e.id === pinned);
+    const engines = [];
+    const notes = [];
+    for (const spec of ordered) {
+        const isNative = native.includes(spec);
+        const bin = spec.bins.map((b) => which(b)).find(Boolean) || null;
+        if (!bin) {
+            if (isNative)
+                notes.push(`${spec.label}'s command line agent is not installed on this machine (\`${spec.installHint}\`)`);
+            continue;
+        }
+        const reason = await readiness(spec, bin);
+        if (reason) {
+            notes.push(`${spec.label}: ${reason}`);
+            continue;
+        }
+        engines.push({ id: spec.id, label: spec.label, bin });
+    }
+    return { engines, notes };
+}
+export function agentTimeoutMs() {
+    const minutes = Number(process.env.AGILEMONSTER_AGENT_TIMEOUT_MINUTES || '');
+    return (Number.isFinite(minutes) && minutes >= 1 ? Math.min(minutes, 180) : 30) * 60 * 1000;
+}
+function failureTail(res) {
+    return (res.stderr.trim() || res.stdout.trim() || res.tail).split('\n').filter((l) => l.trim()).slice(-4).join(' | ').slice(0, 500);
+}
+/** Run one agent to completion. Never throws: a CLI that is missing, logged out or crashed comes back as `ok: false`. */
+export async function runEngine(engine, opts) {
+    const started = Date.now();
+    const timeoutMs = opts.timeoutMs || agentTimeoutMs();
+    const scratchDir = fs.mkdtempSync(path.join(os.tmpdir(), 'am-agent-'));
+    const scratch = { lastMessageFile: path.join(scratchDir, 'last-message.txt') };
+    // The agent works on the code. The card belongs to the runner, so its API key stays out of the agent's reach.
+    const env = { ...process.env };
+    delete env.AGILEMONSTER_API_KEY;
+    try {
+        if (engine.id === 'custom') {
+            const promptFile = path.join(scratchDir, 'prompt.md');
+            fs.writeFileSync(promptFile, opts.prompt, 'utf8');
+            const res = await execShell(customCommand(), {
+                cwd: opts.projectPath,
+                timeoutMs,
+                env: { ...env, AGILEMONSTER_PROMPT_FILE: promptFile, AGILEMONSTER_PROJECT_PATH: opts.projectPath },
+            });
+            const text = res.stdout.trim();
+            return {
+                ok: res.ok,
+                text,
+                timedOut: res.timedOut,
+                durationMs: Date.now() - started,
+                failure: res.ok ? undefined : res.timedOut ? `timed out after ${Math.round(timeoutMs / 60000)} minutes` : failureTail(res),
+            };
+        }
+        const spec = ENGINES.find((e) => e.id === engine.id);
+        if (!spec)
+            return { ok: false, text: '', timedOut: false, durationMs: 0, failure: `unknown engine ${engine.id}` };
+        let res = await exec(engine.bin, spec.args(opts, scratch), { cwd: opts.projectPath, timeoutMs, env });
+        // A model name the CLI does not know fails within seconds: the card's preference must not cost the whole run
+        if (!res.ok && !res.timedOut && opts.model && Date.now() - started < 45000 && /model/i.test(`${res.stderr}\n${res.stdout}`)) {
+            res = await exec(engine.bin, spec.args({ ...opts, model: null }, scratch), { cwd: opts.projectPath, timeoutMs, env });
+        }
+        const parsed = spec.parse(res, scratch);
+        const failed = !res.ok || !!parsed.error;
+        return {
+            ok: !failed,
+            text: parsed.text,
+            sessionId: parsed.sessionId,
+            costUsd: parsed.costUsd,
+            timedOut: res.timedOut,
+            durationMs: Date.now() - started,
+            failure: !failed ? undefined : res.timedOut ? `timed out after ${Math.round(timeoutMs / 60000)} minutes` : (parsed.error || failureTail(res)).slice(0, 500),
+        };
+    }
+    finally {
+        try {
+            fs.rmSync(scratchDir, { recursive: true, force: true });
+        }
+        catch { }
+    }
+}
+/**
+ * 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 function buildAgentPrompt(brief) {
+    const lines = [];
+    lines.push(`You are picking up a task card from the "${brief.boardName || 'project'}" board in Agile Monster. The repository is your current directory (${brief.projectPath}).`, 'Nobody is watching this session. Work the way you would for a developer who typed this request into the IDE and walked away: figure it out, build it, check it.', '', '## The card', `Title: ${brief.title.trim() || '(untitled)'}`, '', brief.description.trim() || '(no description — the title and the conversation below are the whole request)');
+    if (brief.conversation.length > 0) {
+        lines.push('', '## Conversation on the card (oldest first)');
+        for (const turn of brief.conversation) {
+            lines.push(`${turn.who === 'requester' ? 'Requester' : 'Agent (an earlier attempt)'}: ${turn.text.trim()}`, '');
+        }
+        lines.push('The requester\'s replies are part of the request. Where an earlier attempt asked a question, their reply is the answer — do not ask it again.');
+    }
+    lines.push('', '## How to work', '- Find the right place yourself. Search the code for the page names, labels and visible text the card mentions; never ask where something lives.', '- Where the card leaves a detail open, decide it the way this codebase already does things and say what you chose in your summary. Do not ask for confirmation of anything the requester already said.', '- Build the whole change, through every layer it needs (data/API, types, UI).', '- Check your work before you finish: run the type check, build or tests that cover what you touched, and fix what you broke.', '- Do not commit, push, deploy, stash or switch branches. When you finish, the Agile Monster runner commits and deploys exactly the files you changed.', '- Do not use Agile Monster MCP tools or its API. This card is already claimed and its status is managed for you, so skip any project instruction about claiming cards or submitting them for review.');
+    if (brief.developerFiles.length > 0) {
+        lines.push(`- These files hold the developer's own uncommitted work. Do not modify them: ${brief.developerFiles.slice(0, 40).map((f) => `\`${f}\``).join(', ')}`);
+    }
+    if (brief.earlierFiles.length > 0) {
+        lines.push(`- An earlier attempt at this card left uncommitted changes in ${brief.earlierFiles.slice(0, 40).map((f) => `\`${f}\``).join(', ')}. They are yours to keep, fix or replace.` +
+            (brief.earlierSummary ? ` It reported: ${brief.earlierSummary.trim().slice(0, 600)}` : ''));
+    }
+    lines.push('', '## When you are done', 'End your reply with one JSON object on its own, and nothing after it:', '{"status":"done","summary":"2-4 plain sentences for the person reviewing the card: what changed and where they will see it","verification_steps":["a step they can do in the running app","..."]}', 'Only if the work is impossible or unsafe without something that is not in the repository:', '{"status":"blocked","question":"the one specific thing you need, and what you already tried"}');
+    return lines.join('\n');
+}
+/** Read the closing JSON object out of the agent's final message. Tolerates code fences and prose around it. */
+export function parseAgentReport(text) {
+    const clean = (text || '').trim();
+    const starts = [];
+    const re = /\{\s*"status"\s*:/g;
+    let m;
+    while ((m = re.exec(clean)))
+        starts.push(m.index);
+    for (let i = starts.length - 1; i >= 0; i--) {
+        let end = clean.lastIndexOf('}');
+        while (end > starts[i]) {
+            try {
+                const obj = JSON.parse(clean.slice(starts[i], end + 1));
+                const status = String(obj.status || '').toLowerCase();
+                const steps = Array.isArray(obj.verification_steps)
+                    ? obj.verification_steps.map((s) => String(s).trim()).filter(Boolean)
+                    : typeof obj.verification_steps === 'string' && obj.verification_steps.trim()
+                        ? [obj.verification_steps.trim()]
+                        : [];
+                return {
+                    status: status === 'done' ? 'done' : status === 'blocked' ? 'blocked' : 'unknown',
+                    summary: String(obj.summary || '').trim(),
+                    verificationSteps: steps,
+                    question: String(obj.question || '').trim(),
+                };
+            }
+            catch { }
+            end = clean.lastIndexOf('}', end - 1);
+        }
+    }
+    return { status: 'unknown', summary: '', verificationSteps: [], question: '' };
+}
+/** The agent's prose without the closing JSON object: what to show a human when the report is missing a field. */
+export function proseOf(text, maxChars = 900) {
+    const clean = (text || '').replace(/```(?:json)?\s*\{\s*"status"[\s\S]*?```/g, '').replace(/\{\s*"status"\s*:[\s\S]*$/, '').trim();
+    return clean.length > maxChars ? `…${clean.slice(-maxChars)}` : clean;
+}
+const ABSENT = 'absent';
+const MAX_FINGERPRINT_BYTES = 8 * 1024 * 1024;
+const MAX_SAVED_BYTES = 2 * 1024 * 1024;
+const git = (cwd, args, timeoutMs = 30000) => exec('git', ['--literal-pathspecs', ...args], { cwd, timeoutMs });
+function fingerprint(abs) {
+    try {
+        const stat = fs.statSync(abs);
+        if (!stat.isFile())
+            return `other:${stat.mtimeMs}`;
+        if (stat.size > MAX_FINGERPRINT_BYTES)
+            return `big:${stat.size}:${stat.mtimeMs}`;
+        return crypto.createHash('sha1').update(fs.readFileSync(abs)).digest('hex');
+    }
+    catch {
+        return ABSENT;
+    }
+}
+/** Paths from `git status --porcelain -z`. A rename reports both its new and its old path. */
+export function parsePorcelainZ(out) {
+    const paths = [];
+    const tokens = out.split('\0');
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.length < 4)
+            continue;
+        paths.push(token.slice(3));
+        if (token[0] === 'R' || token[0] === 'C') {
+            i++;
+            if (tokens[i])
+                paths.push(tokens[i]);
+        }
+    }
+    return paths;
+}
+async function statusPaths(projectPath) {
+    const res = await git(projectPath, ['status', '--porcelain=v1', '-z', '--untracked-files=all']);
+    return res.ok ? parsePorcelainZ(res.stdout) : null;
+}
+/** Record the working tree before the agent starts. Null when the folder is not a Git repository. */
+export async function snapshotWorkingTree(projectPath) {
+    const head = await git(projectPath, ['rev-parse', 'HEAD']);
+    const paths = await statusPaths(projectPath);
+    if (!head.ok || !paths)
+        return null;
+    const entries = new Map();
+    const saved = new Map();
+    for (const rel of paths) {
+        const abs = path.join(projectPath, rel);
+        const print = fingerprint(abs);
+        entries.set(rel, print);
+        if (print === ABSENT) {
+            saved.set(rel, null);
+        }
+        else {
+            try {
+                if (fs.statSync(abs).size <= MAX_SAVED_BYTES)
+                    saved.set(rel, fs.readFileSync(abs));
+            }
+            catch { }
+        }
+    }
+    return { head: head.stdout.trim(), entries, saved };
+}
+/** Files an agent's own tooling drops into a project. New ones are never part of a card's change. */
+function isAgentToolingPath(rel) {
+    return /^(\.claude|\.cursor|\.codex|\.agilemonster|\.specstory)(\/|$)/.test(rel) || rel === '.agilemonster.json';
+}
+/**
+ * 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 async function changesSince(projectPath, snap) {
+    let pushedCommit;
+    const head = await git(projectPath, ['rev-parse', 'HEAD']);
+    const nowHead = head.ok ? head.stdout.trim() : snap.head;
+    if (nowHead !== snap.head) {
+        const descends = await git(projectPath, ['merge-base', '--is-ancestor', snap.head, nowHead]);
+        const onRemote = await git(projectPath, ['branch', '-r', '--contains', nowHead]);
+        if (onRemote.ok && onRemote.stdout.trim() !== '') {
+            pushedCommit = nowHead;
+        }
+        else if (descends.ok) {
+            await git(projectPath, ['reset', '--soft', snap.head]);
+        }
+    }
+    const changed = [];
+    const overlapping = [];
+    const now = new Set((await statusPaths(projectPath)) || []);
+    for (const rel of now) {
+        const before = snap.entries.get(rel);
+        if (before === undefined) {
+            if (!isAgentToolingPath(rel))
+                changed.push(rel);
+        }
+        else if (fingerprint(path.join(projectPath, rel)) !== before) {
+            changed.push(rel);
+            overlapping.push(rel);
+        }
+    }
+    // A file that was dirty and is clean again was put back to HEAD by the agent: the developer's change is gone
+    for (const rel of snap.entries.keys()) {
+        if (!now.has(rel)) {
+            changed.push(rel);
+            overlapping.push(rel);
+        }
+    }
+    return { changed: changed.sort(), overlapping: overlapping.sort(), pushedCommit };
+}
+/**
+ * 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 async function restoreWorkingTree(projectPath, snap, paths) {
+    const failed = [];
+    const root = path.resolve(projectPath);
+    for (const rel of paths) {
+        const abs = path.resolve(root, rel);
+        if (abs !== root && !abs.startsWith(root + path.sep))
+            continue;
+        try {
+            if (snap.entries.has(rel)) {
+                if (!snap.saved.has(rel)) {
+                    failed.push(rel);
+                    continue;
+                }
+                const original = snap.saved.get(rel);
+                if (original === null || original === undefined) {
+                    fs.rmSync(abs, { force: true });
+                }
+                else {
+                    fs.mkdirSync(path.dirname(abs), { recursive: true });
+                    fs.writeFileSync(abs, original);
+                }
+                continue;
+            }
+            // Clean before the run: either a tracked file (take it from HEAD) or one that did not exist (remove it)
+            const tracked = await git(projectPath, ['cat-file', '-e', `${snap.head}:${rel}`]);
+            if (tracked.ok) {
+                const back = await git(projectPath, ['checkout', snap.head, '--', rel]);
+                if (!back.ok)
+                    failed.push(rel);
+            }
+            else {
+                await git(projectPath, ['rm', '--cached', '--quiet', '--ignore-unmatch', '--', rel]);
+                fs.rmSync(abs, { force: true });
+                let dir = path.dirname(abs);
+                while (dir !== root && dir.startsWith(root + path.sep)) {
+                    try {
+                        fs.rmdirSync(dir); // only succeeds on a directory the agent created and we just emptied
+                    }
+                    catch {
+                        break;
+                    }
+                    dir = path.dirname(dir);
+                }
+            }
+        }
+        catch {
+            failed.push(rel);
+        }
+    }
+    return failed;
+}
+/**
+ * `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 async function markNewFilesForDiff(projectPath, files) {
+    if (files.length === 0)
+        return;
+    const untracked = await git(projectPath, ['ls-files', '--others', '--exclude-standard', '-z', '--', ...files]);
+    const fresh = untracked.ok ? untracked.stdout.split('\0').filter(Boolean) : [];
+    if (fresh.length > 0)
+        await git(projectPath, ['add', '--intent-to-add', '--', ...fresh]);
+}
+function runRecordFile(cardId) {
+    return path.join(agileMonsterHome(), 'agent-runs', `${cardId.replace(/[^a-zA-Z0-9-]/g, '')}.json`);
+}
+/**
+ * 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 async function baselineFor(cardId, projectPath) {
+    const snapshot = await snapshotWorkingTree(projectPath);
+    if (!snapshot)
+        return null;
+    const prior = readJson(runRecordFile(cardId));
+    const interrupted = !!prior && prior.project_path === projectPath;
+    try {
+        writeJsonAtomic(runRecordFile(cardId), {
+            card_id: cardId,
+            project_path: projectPath,
+            pid: process.pid,
+            at: new Date().toISOString(),
+        });
+    }
+    catch { }
+    return { snapshot, interrupted };
+}
+/** The card's run reached a conclusion (shipped, reverted, or handed to the human): it is no longer in progress. */
+export function clearBaseline(cardId) {
+    try {
+        fs.rmSync(runRecordFile(cardId), { force: true });
+    }
+    catch { }
+}

package/dist/client.d.ts

@@ -1,5 +1,12 @@
-import { AgileMonsterProjectConfig, AutonomousStepResponse, CardComment, DeployReport, Board, BoardAgentConfig, Card, ContextResponse, DiscoveredProject, PulseResponse } from './types.js';
-export declare const MCP_SERVER_VERSION = "1.0.22";
+import { ActiveClaim, AgileMonsterProjectConfig, AutonomousStepResponse, CardComment, DeployReport, Board, BoardAgentConfig, Card, ContextResponse, DiscoveredProject, PulseResponse } from './types.js';
+export declare const MCP_SERVER_VERSION = "1.0.24";
+/** 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;
+    constructor(message: string, status: number);
+}
+/** The server refused a claim because another agent session holds the card (HTTP 409). */
+export declare function isClaimConflict(err: unknown): boolean;
 export declare class AgileMonsterClient {
     private apiKey;
     private baseUrl;
@@ -41,7 +48,13 @@ export declare class AgileMonsterClient {
             models: Record<string, string> | string[];
         }>;
         installedAgents?: string[];
+        /** Cards this process holds: the server extends their claim (heartbeat). */
+        activeClaims?: ActiveClaim[];
     }): Promise<PulseResponse>;
+    /** Extend the claims this process holds. Used while a long job keeps the pulse loop busy. */
+    heartbeat(activeClaims: ActiveClaim[]): Promise<{
+        renewed: number;
+    }>;
     /**
      * Cross-platform detection of AI coding agents installed on this computer.
      * Checks for Cursor, Claude Code, Antigravity, Codex, Hermes, Windsurf, Aider.

package/dist/client.js

@@ -4,7 +4,20 @@ 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.22';
+export const MCP_SERVER_VERSION = '1.0.24';
+/** An API call the server answered with an error status. `status` lets callers tell "refused" from "broken". */
+export class ApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+    }
+}
+/** The server refused a claim because another agent session holds the card (HTTP 409). */
+export function isClaimConflict(err) {
+    return err instanceof ApiError && err.status === 409;
+}
 export class AgileMonsterClient {
     apiKey = '';
     baseUrl;
@@ -144,7 +157,7 @@ export class AgileMonsterClient {
         }
         if (!res.ok) {
             const msg = json?.message || json?.error || `HTTP ${res.status}: ${text.slice(0, 150)}`;
-            throw new Error(`Agile Monster API Error: ${msg}`);
+            throw new ApiError(`Agile Monster API Error: ${msg}`, res.status);
         }
         return json;
     }
@@ -202,9 +215,17 @@ export class AgileMonsterClient {
                 discovered_projects: options.discoveredProjects,
                 discovered_models: options.discoveredModels,
                 installed_agents: installed,
+                active_claims: options.activeClaims && options.activeClaims.length > 0 ? options.activeClaims : undefined,
             }),
         });
     }
+    /** Extend the claims this process holds. Used while a long job keeps the pulse loop busy. */
+    async heartbeat(activeClaims) {
+        return this.request('/api/agent/heartbeat', {
+            method: 'POST',
+            body: JSON.stringify({ active_claims: activeClaims }),
+        });
+    }
     /**
      * Cross-platform detection of AI coding agents installed on this computer.
      * Checks for Cursor, Claude Code, Antigravity, Codex, Hermes, Windsurf, Aider.

package/dist/deploy-profile.d.ts

@@ -11,7 +11,11 @@ import type { ProjectMemory } from './deploy-memory.js';
  * Precedence: explicit project file > user-set binding > last verified success > ranked evidence.
  */
 export type DeployMethod = 'github_actions' | 'docker_compose' | 'deploy_script' | 'cloud_cli' | 'git_push' | 'manual' | 'none';
-export type ProfileSource = 'explicit' | 'user' | 'learned' | 'verified' | 'detected';
+/**
+ * 'proposed' = a route someone ELSE set for this project on the board (a teammate, or a deployment verified
+ * on another machine). It is never "confirmed" for this computer by that alone.
+ */
+export type ProfileSource = 'explicit' | 'user' | 'learned' | 'verified' | 'detected' | 'proposed';
 export type Confidence = 'high' | 'medium' | 'low';
 export interface PushTrigger {
     branches: string[] | null;
@@ -61,6 +65,16 @@ export interface DeployCandidate {
     /** The deploy workflow only starts when dispatched (pushing alone does not deploy). */
     dispatchOnly?: boolean;
 }
+/** A deploy route another account set on the board binding. The server sends it apart from the confirmed fields. */
+export interface RouteProposal {
+    method?: string | null;
+    command?: string | null;
+    live_url?: string | null;
+    /** How it is stored on the board: 'user' (stated by that person), 'verified' (worked on their machine), 'auto'. */
+    source?: string | null;
+    set_by?: string | null;
+    set_by_name?: string | null;
+}
 export interface BoundProfile {
     deploy_method?: string | null;
     deploy_command?: string | null;
@@ -68,7 +82,18 @@ export interface BoundProfile {
     build_command?: string | null;
     /** 'user' = set by a human, 'verified' = confirmed by a successful deploy, 'auto' = a guess. */
     deploy_source?: string | null;
+    /** The account that set deploy_method / deploy_command on the board. */
+    deploy_set_by?: string | null;
+    /** A route someone else set: used only as described at `resolveDeployProfile`. */
+    proposal?: RouteProposal | null;
 }
+/**
+ * Second check on this side of the wire: the server only sends a binding's route as confirmed to the account
+ * that set it, but what runs in a shell on this computer is decided HERE. If the confirmed fields name a
+ * setter and it is not this machine's account, the route is demoted to a proposal.
+ * `ownerId` null = this machine's account could not be determined; the fields are left as the server sent them.
+ */
+export declare function trustBoundRoute(bound: BoundProfile | null | undefined, ownerId: string | null | undefined): BoundProfile | null;
 export interface GitInfo {
     isRepo: boolean;
     branch: string | null;