mcp-coordinator 0.1.0

package/dist/src/mqtt-bridge.d.ts

@@ -0,0 +1,40 @@
+import { type Logger } from "./logger.js";
+interface QueuedMessage {
+    topic: string;
+    payload: Record<string, unknown>;
+    timestamp: number;
+}
+export declare class MqttBridge {
+    private client;
+    private connected;
+    private onOfflineHandler;
+    private listeners;
+    private log;
+    constructor(logger?: Logger);
+    connect(config: {
+        url: string;
+    }): Promise<void>;
+    isConnected(): boolean;
+    onOffline(handler: (agentId: string) => void): void;
+    registerAgent(agentId: string, name: string): void;
+    publishConsultation(threadId: string, agentId: string, subject: string, targetModules: string[]): void;
+    publishMessage(threadId: string, agentId: string, type: string, content: string): void;
+    publishResolution(threadId: string, status: string, summary: string): void;
+    publishBroadcast(agentId: string, message: string): void;
+    publishAgentOffline(agentId: string): void;
+    publishTaskClaimed(threadId: string, claimedBy: string): void;
+    publishTaskCompleted(threadId: string, completedBy: string, summary: string): void;
+    /**
+     * Fanout a refreshed QuotaInfo to live subscribers (dashboard widget,
+     * scheduled-agent runners, anything wanting realtime quota pressure).
+     * Typed via `unknown` to avoid an import cycle with the quota module.
+     */
+    publishQuotaUpdate(info: unknown): void;
+    registerListener(agentId: string): void;
+    removeListener(agentId: string): void;
+    waitForMessage(agentId: string, timeoutMs: number): Promise<QueuedMessage | null>;
+    getQueuedMessages(agentId: string): QueuedMessage[];
+    mqttPublish(topic: string, payload: string): void;
+    disconnect(): Promise<void>;
+}
+export {};

package/dist/src/mqtt-bridge.js

@@ -0,0 +1,173 @@
+import mqtt from "mqtt";
+import { silentLogger } from "./logger.js";
+export class MqttBridge {
+    client = null;
+    connected = false;
+    onOfflineHandler = null;
+    listeners = new Map();
+    log;
+    constructor(logger) {
+        this.log = logger || silentLogger;
+    }
+    async connect(config) {
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                reject(new Error("MQTT connection timeout"));
+            }, 5000);
+            this.client = mqtt.connect(config.url, {
+                clientId: `coordinator-${Date.now()}`,
+                clean: true,
+            });
+            this.client.on("connect", () => {
+                clearTimeout(timeout);
+                this.connected = true;
+                this.log.info({ url: config.url }, "MQTT connected");
+                // Subscribe to agent status for LWT detection
+                this.client.subscribe("coordinator/agents/+/status");
+                resolve();
+            });
+            // Subscribe to consultation topics for agent listeners
+            this.client.subscribe("coordinator/consultations/#");
+            this.client.subscribe("coordinator/broadcast");
+            this.client.on("message", (topic, message) => {
+                const parts = topic.split("/");
+                if (parts[1] === "agents" && parts[3] === "status") {
+                    const agentId = parts[2];
+                    const status = message.toString();
+                    if (status === "offline" && this.onOfflineHandler) {
+                        this.onOfflineHandler(agentId);
+                    }
+                }
+                // Route consultation messages to agent listeners
+                if (parts[1] === "consultations" || parts[1] === "broadcast") {
+                    try {
+                        const payload = JSON.parse(message.toString());
+                        const msg = { topic, payload, timestamp: Date.now() };
+                        for (const listener of this.listeners.values()) {
+                            if (listener.waitResolve) {
+                                const resolve = listener.waitResolve;
+                                listener.waitResolve = null;
+                                resolve(msg);
+                            }
+                            else {
+                                listener.queue.push(msg);
+                            }
+                        }
+                    }
+                    catch { /* ignore malformed */ }
+                }
+            });
+            this.client.on("error", (err) => {
+                clearTimeout(timeout);
+                this.log.error({ err }, "MQTT error");
+                reject(err);
+            });
+        });
+    }
+    isConnected() {
+        return this.connected;
+    }
+    onOffline(handler) {
+        this.onOfflineHandler = handler;
+    }
+    registerAgent(agentId, name) {
+        if (!this.client || !this.connected)
+            return;
+        this.client.publish(`coordinator/agents/${agentId}/status`, JSON.stringify({ status: "online", name }), { retain: true });
+    }
+    publishConsultation(threadId, agentId, subject, targetModules) {
+        if (!this.client || !this.connected)
+            return;
+        this.client.publish("coordinator/consultations/new", JSON.stringify({ thread_id: threadId, agent_id: agentId, subject, target_modules: targetModules }));
+    }
+    publishMessage(threadId, agentId, type, content) {
+        if (!this.client || !this.connected)
+            return;
+        this.client.publish(`coordinator/consultations/${threadId}/messages`, JSON.stringify({ agent_id: agentId, type, content }));
+    }
+    publishResolution(threadId, status, summary) {
+        if (!this.client || !this.connected)
+            return;
+        this.client.publish(`coordinator/consultations/${threadId}/status`, JSON.stringify({ status, summary }), { retain: true });
+    }
+    publishBroadcast(agentId, message) {
+        if (!this.client || !this.connected)
+            return;
+        this.client.publish("coordinator/broadcast", JSON.stringify({ agent_id: agentId, message }));
+    }
+    publishAgentOffline(agentId) {
+        if (!this.client || !this.connected)
+            return;
+        this.client.publish(`coordinator/agents/${agentId}/status`, JSON.stringify({ status: "offline" }), { retain: true });
+    }
+    publishTaskClaimed(threadId, claimedBy) {
+        if (!this.client || !this.connected)
+            return;
+        this.client.publish(`coordinator/consultations/${threadId}/claimed`, JSON.stringify({ agent_id: claimedBy, claimed_by: claimedBy, claimed_at: new Date().toISOString() }));
+    }
+    publishTaskCompleted(threadId, completedBy, summary) {
+        if (!this.client || !this.connected)
+            return;
+        this.client.publish(`coordinator/consultations/${threadId}/completed`, JSON.stringify({ agent_id: completedBy, completed_by: completedBy, summary }));
+    }
+    /**
+     * Fanout a refreshed QuotaInfo to live subscribers (dashboard widget,
+     * scheduled-agent runners, anything wanting realtime quota pressure).
+     * Typed via `unknown` to avoid an import cycle with the quota module.
+     */
+    publishQuotaUpdate(info) {
+        if (!this.client || !this.connected)
+            return;
+        this.client.publish("coordinator/quota/update", JSON.stringify(info));
+    }
+    // ── Agent listener methods (for integrated MCP tools) ──
+    registerListener(agentId) {
+        if (!this.listeners.has(agentId)) {
+            this.listeners.set(agentId, { queue: [], waitResolve: null });
+        }
+    }
+    removeListener(agentId) {
+        const listener = this.listeners.get(agentId);
+        if (listener?.waitResolve) {
+            listener.waitResolve(null); // unblock any waiting call
+        }
+        this.listeners.delete(agentId);
+    }
+    async waitForMessage(agentId, timeoutMs) {
+        this.registerListener(agentId);
+        const listener = this.listeners.get(agentId);
+        // Check queue first
+        if (listener.queue.length > 0) {
+            return listener.queue.shift();
+        }
+        // Block until message or timeout
+        return new Promise((resolve) => {
+            listener.waitResolve = resolve;
+            setTimeout(() => {
+                if (listener.waitResolve === resolve) {
+                    listener.waitResolve = null;
+                    resolve(null);
+                }
+            }, timeoutMs);
+        });
+    }
+    getQueuedMessages(agentId) {
+        this.registerListener(agentId);
+        const listener = this.listeners.get(agentId);
+        const messages = [...listener.queue];
+        listener.queue.length = 0;
+        return messages;
+    }
+    mqttPublish(topic, payload) {
+        if (this.client && this.connected) {
+            this.client.publish(topic, payload);
+        }
+    }
+    async disconnect() {
+        if (this.client) {
+            this.log.info("MQTT disconnected");
+            this.connected = false;
+            await this.client.endAsync();
+        }
+    }
+}

package/dist/src/mqtt-broker.d.ts

@@ -0,0 +1,23 @@
+import type { Server as HttpServer } from "http";
+import type { Logger } from "./logger.js";
+export interface EmbeddedMqttBroker {
+    tcpPort: number | null;
+    wsPath: string | null;
+    close: () => Promise<void>;
+}
+export interface EmbeddedMqttOptions {
+    tcpPort?: number;
+    httpServer?: HttpServer;
+    wsPath?: string;
+    logger: Logger;
+}
+/**
+ * Start an embedded MQTT broker (aedes) exposed via TCP, WebSocket, or both.
+ * TCP and WS share the same aedes instance, so a client on ws:// can receive
+ * messages from a client on mqtt:// and vice versa.
+ *
+ * Uses Aedes.createBroker() to wait for the broker's async initialization
+ * before accepting connections — new Aedes() returns before the broker is
+ * fully ready, which causes client connect timeouts in compiled binaries.
+ */
+export declare function startEmbeddedMqttBroker(opts: EmbeddedMqttOptions): Promise<EmbeddedMqttBroker>;

package/dist/src/mqtt-broker.js

@@ -0,0 +1,99 @@
+import { Aedes } from "aedes";
+import { createServer as createTcpServer } from "net";
+import { Duplex } from "stream";
+import { WebSocketServer } from "ws";
+/**
+ * Bridge a WebSocket to a Duplex stream for aedes.
+ * Replaces createWebSocketStream which is not supported in Bun.
+ */
+function wsToDuplex(ws) {
+    const duplex = new Duplex({
+        read() { },
+        write(chunk, _encoding, callback) {
+            try {
+                ws.send(chunk);
+                callback();
+            }
+            catch (err) {
+                callback(err);
+            }
+        },
+        final(callback) {
+            ws.close();
+            callback();
+        },
+    });
+    ws.on("message", (data) => duplex.push(data));
+    ws.on("close", () => { duplex.push(null); duplex.destroy(); });
+    ws.on("error", (err) => duplex.destroy(err));
+    return duplex;
+}
+/**
+ * Start an embedded MQTT broker (aedes) exposed via TCP, WebSocket, or both.
+ * TCP and WS share the same aedes instance, so a client on ws:// can receive
+ * messages from a client on mqtt:// and vice versa.
+ *
+ * Uses Aedes.createBroker() to wait for the broker's async initialization
+ * before accepting connections — new Aedes() returns before the broker is
+ * fully ready, which causes client connect timeouts in compiled binaries.
+ */
+export async function startEmbeddedMqttBroker(opts) {
+    const { tcpPort, httpServer, wsPath = "/mqtt", logger } = opts;
+    const broker = await Aedes.createBroker();
+    broker.on("client", (client) => {
+        logger.debug({ client_id: client?.id }, "MQTT client connected");
+    });
+    broker.on("clientDisconnect", (client) => {
+        logger.debug({ client_id: client?.id }, "MQTT client disconnected");
+    });
+    broker.on("clientError", (client, err) => {
+        logger.warn({ client_id: client?.id, err: err.message }, "MQTT client error");
+    });
+    let tcpServerClose = null;
+    let wsServerClose = null;
+    if (tcpPort && tcpPort > 0) {
+        const tcpServer = createTcpServer((socket) => {
+            broker.handle(socket);
+        });
+        // Bind to 127.0.0.1 explicitly — default binding to IPv6 (::) can cause
+        // the mqtt client (which resolves localhost → 127.0.0.1) to hang.
+        await new Promise((resolve, reject) => {
+            tcpServer.once("error", reject);
+            tcpServer.listen(tcpPort, "127.0.0.1", () => {
+                tcpServer.off("error", reject);
+                logger.info({ port: tcpPort, transport: "tcp" }, "Embedded MQTT broker listening");
+                resolve();
+            });
+        });
+        tcpServer.on("error", (err) => {
+            logger.error({ err, port: tcpPort }, "Embedded MQTT TCP server error");
+        });
+        tcpServerClose = () => new Promise((resolve) => tcpServer.close(() => resolve()));
+    }
+    if (httpServer) {
+        const wss = new WebSocketServer({ noServer: true });
+        wss.on("connection", (ws) => {
+            const duplex = wsToDuplex(ws);
+            broker.handle(duplex);
+        });
+        httpServer.on("upgrade", (req, socket, head) => {
+            const url = req.url || "";
+            if (url === wsPath || url.startsWith(`${wsPath}?`)) {
+                wss.handleUpgrade(req, socket, head, (ws) => wss.emit("connection", ws, req));
+            }
+        });
+        logger.info({ path: wsPath, transport: "ws" }, "Embedded MQTT broker listening on HTTP upgrade");
+        wsServerClose = () => new Promise((resolve) => wss.close(() => resolve()));
+    }
+    return {
+        tcpPort: tcpPort && tcpPort > 0 ? tcpPort : null,
+        wsPath: httpServer ? wsPath : null,
+        close: async () => {
+            if (tcpServerClose)
+                await tcpServerClose();
+            if (wsServerClose)
+                await wsServerClose();
+            await new Promise((resolve) => broker.close(() => resolve()));
+        },
+    };
+}

package/dist/src/plan-quality.d.ts

@@ -0,0 +1,11 @@
+export interface PlanQualityResult {
+    mode: "with_plan" | "discovery";
+    score: number;
+    checks: {
+        mentions_files: boolean;
+        concrete_approach: boolean;
+        sufficient_detail: boolean;
+    };
+    original_plan: string | null;
+}
+export declare function assessPlanQuality(plan: string | null | undefined): PlanQualityResult;

package/dist/src/plan-quality.js

@@ -0,0 +1,30 @@
+export function assessPlanQuality(plan) {
+    if (!plan || plan.trim().length === 0) {
+        return {
+            mode: "discovery",
+            score: 0,
+            checks: { mentions_files: false, concrete_approach: false, sufficient_detail: false },
+            original_plan: null,
+        };
+    }
+    const trimmed = plan.trim();
+    // Check 1: Mentions specific files (paths with extensions or slashes)
+    const mentions_files = /\w+\/\w+|\.\w{2,4}\b/.test(trimmed);
+    // Check 2: Concrete approach — the plan contains concrete action verbs
+    // anywhere. Match word stems (no trailing \b) so inflected forms like
+    // "adding", "creating", "replaces", "implementing" are recognized.
+    // A leading vague word ("Fix", "Update") does NOT disqualify a plan that
+    // otherwise describes concrete actions.
+    const concretePatterns = /\b(ajout|cré|creat|add|split|extract|replac|remplac|implémen|implement|supprim|delet|remov|migr|wrap)/i;
+    const concrete_approach = concretePatterns.test(trimmed);
+    // Check 3: Sufficient detail (more than 20 words)
+    const wordCount = trimmed.split(/\s+/).length;
+    const sufficient_detail = wordCount > 20;
+    const score = [mentions_files, concrete_approach, sufficient_detail].filter(Boolean).length;
+    return {
+        mode: score >= 2 ? "with_plan" : "discovery",
+        score,
+        checks: { mentions_files, concrete_approach, sufficient_detail },
+        original_plan: trimmed,
+    };
+}

package/dist/src/quota/credential-reader.d.ts

@@ -0,0 +1,21 @@
+export declare class NotImplementedError extends Error {
+    constructor(platform: NodeJS.Platform);
+}
+export interface CredentialReader {
+    readClaudeOAuthToken(): Promise<string>;
+}
+/**
+ * macOS implementation: shells out to `security find-generic-password` against
+ * the Claude Code-credentials entry in the user's Keychain, then parses the
+ * JSON blob the CLI stored.
+ */
+export declare class MacOSCredentialReader implements CredentialReader {
+    readClaudeOAuthToken(): Promise<string>;
+}
+export declare class LinuxCredentialReader implements CredentialReader {
+    readClaudeOAuthToken(): Promise<string>;
+}
+export declare class WindowsCredentialReader implements CredentialReader {
+    readClaudeOAuthToken(): Promise<string>;
+}
+export declare function createCredentialReader(platform?: NodeJS.Platform): CredentialReader;

package/dist/src/quota/credential-reader.js

@@ -0,0 +1,86 @@
+// OAuth credential access for Claude Code — reads the "Claude Code-credentials"
+// secret stored by the Claude Code CLI and extracts the accessToken.
+//
+// macOS is the only platform with a real implementation; Linux and Windows
+// stubs throw NotImplementedError so the coordinator can start on those
+// platforms (the quota endpoint simply returns 503 — see quota-cache.ts /
+// serve-http.ts for the fallback path that keeps raids running without a
+// quota guardrail).
+import { execFile } from "child_process";
+import { promisify } from "util";
+const execFileP = promisify(execFile);
+export class NotImplementedError extends Error {
+    constructor(platform) {
+        super(`Claude OAuth credential reader not implemented for platform "${platform}" yet`);
+        this.name = "NotImplementedError";
+    }
+}
+/**
+ * macOS implementation: shells out to `security find-generic-password` against
+ * the Claude Code-credentials entry in the user's Keychain, then parses the
+ * JSON blob the CLI stored.
+ */
+export class MacOSCredentialReader {
+    async readClaudeOAuthToken() {
+        let stdout;
+        try {
+            // -s = service, -w = print password only (the stored JSON blob).
+            const result = await execFileP("security", [
+                "find-generic-password",
+                "-s", "Claude Code-credentials",
+                "-w",
+            ]);
+            stdout = result.stdout;
+        }
+        catch (err) {
+            throw new Error(`security CLI failed — Keychain entry likely missing (${err.message})`);
+        }
+        const raw = stdout.trim();
+        if (!raw)
+            throw new Error("Keychain returned empty credential blob");
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new Error(`Keychain credential is not valid JSON: ${err.message}`);
+        }
+        const token = extractAccessToken(parsed);
+        if (!token)
+            throw new Error("claudeAiOauth.accessToken missing or empty");
+        return token;
+    }
+}
+export class LinuxCredentialReader {
+    // TODO: probably `secret-tool lookup` via libsecret, or read from
+    //       ~/.config/claude-code/credentials.json — verify Claude Code's
+    //       actual storage layout on Linux before implementing.
+    async readClaudeOAuthToken() {
+        throw new NotImplementedError("linux");
+    }
+}
+export class WindowsCredentialReader {
+    // TODO: likely the Windows Credential Manager via `cmdkey` or a native
+    //       binding — verify where Claude Code stores its OAuth token on Win
+    //       before implementing.
+    async readClaudeOAuthToken() {
+        throw new NotImplementedError("win32");
+    }
+}
+export function createCredentialReader(platform = process.platform) {
+    switch (platform) {
+        case "darwin": return new MacOSCredentialReader();
+        case "linux": return new LinuxCredentialReader();
+        case "win32": return new WindowsCredentialReader();
+        default: throw new NotImplementedError(platform);
+    }
+}
+function extractAccessToken(parsed) {
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const oauth = parsed.claudeAiOauth;
+    if (!oauth || typeof oauth !== "object")
+        return null;
+    const token = oauth.accessToken;
+    return typeof token === "string" && token.length > 0 ? token : null;
+}

package/dist/src/quota/quota-cache.d.ts

@@ -0,0 +1,93 @@
+import type { CredentialReader } from "./credential-reader.js";
+import { type QuotaInfo } from "./quota.js";
+import type { Logger } from "../logger.js";
+export declare const DEFAULT_TTL_MS = 120000;
+export interface QuotaCacheOptions {
+    ttlMs?: number;
+    reader?: CredentialReader;
+    logger?: Logger;
+    /**
+     * Injected for tests so we don't hit network. Defaults to the real
+     * Anthropic fetcher.
+     */
+    fetcher?: (reader: CredentialReader) => Promise<QuotaInfo>;
+    /**
+     * Notified every time a refresh produces a new QuotaInfo. The server wires
+     * this to MQTT + SSE so dashboards see live updates.
+     */
+    onRefresh?: (info: QuotaInfo) => void;
+}
+export interface QuotaCacheStatus {
+    /** Last fetched info, or null if never successfully fetched. */
+    info: QuotaInfo | null;
+    /** True when the last fetch attempt threw (Keychain / network / parse). */
+    unavailable: boolean;
+    /** Most recent failure reason, for debug. */
+    lastError: string | null;
+    /** Number of agents currently registered as active (drives background refresh). */
+    activeAgents: number;
+    ttlMs: number;
+    /**
+     * When > now, the cache is in a 429 cool-down — it refuses to hit the
+     * Anthropic usage API until this time passes. Surfaced so the HTTP layer
+     * can explain the delay to the user instead of showing a generic 503.
+     */
+    cooldownUntil: number | null;
+}
+/**
+ * Returns true if the cached info is still within TTL. Pure function so
+ * callers can decide cache freshness without touching the cache instance.
+ */
+export declare function isFresh(info: QuotaInfo | null, ttlMs: number, now?: number): boolean;
+export declare class QuotaCache {
+    private info;
+    private lastError;
+    private refreshInFlight;
+    private activeAgents;
+    private backgroundTimer;
+    private cooldownUntil;
+    private readonly ttlMs;
+    private readonly reader;
+    private readonly logger;
+    private readonly fetcher;
+    private readonly onRefresh;
+    constructor(opts?: QuotaCacheOptions);
+    /**
+     * Returns the cached QuotaInfo if fresh, otherwise triggers a refresh and
+     * returns the new value. Returns null when fetching fails (fail-open path).
+     * Concurrent calls share a single in-flight fetch.
+     */
+    get(): Promise<QuotaInfo | null>;
+    /**
+     * Returns the cached value synchronously, even if stale or missing. Used
+     * by the HTTP handler to decide 200 vs 503 without awaiting a refresh.
+     */
+    snapshot(): QuotaCacheStatus;
+    /**
+     * Force a refresh now. Returns the new value or null on failure. Subsequent
+     * concurrent callers share the same in-flight promise so we never issue
+     * parallel Anthropic calls for the same refresh window. During a 429
+     * cool-down we short-circuit to the cached value (possibly null) without
+     * hitting the API — keeps us from hammering an endpoint that's already
+     * pushing back.
+     */
+    refresh(): Promise<QuotaInfo | null>;
+    private doRefresh;
+    /**
+     * Call when an agent connects so the background tick keeps the cache warm
+     * during an active run. Multiple calls without a matching decrement are
+     * idempotent above 0 — the tick runs whenever activeAgents > 0.
+     */
+    onAgentActive(): void;
+    /**
+     * Call when an agent disconnects so the background tick stops when the
+     * coordinator goes idle — no point re-fetching if nobody will read it.
+     */
+    onAgentInactive(): void;
+    /**
+     * Stop the timer so process teardown doesn't leak. Safe to call multiple
+     * times. The next onAgentActive() will restart it.
+     */
+    stopBackgroundTick(): void;
+    private startBackgroundTick;
+}