mcp-coordinator 0.2.1 → 0.4.0

package/dist/src/server-setup.d.ts

@@ -11,6 +11,7 @@ import { SseEmitter } from "./sse-emitter.js";
 import { MqttBridge } from "./mqtt-bridge.js";
 import { AgentActivityTracker } from "./agent-activity.js";
 import { QuotaCache } from "./quota/quota-cache.js";
+import { Metrics } from "./metrics.js";
 import type { CoordinatorConfig } from "./types.js";
 import { type Logger } from "./logger.js";
 export interface CoordinatorServices {
@@ -27,6 +28,7 @@ export interface CoordinatorServices {
     sseEmitter: SseEmitter;
     mqttBridge: MqttBridge;
     quotaCache: QuotaCache;
+    metrics: Metrics;
 }
 /** Create shared services (once at startup). */
 export declare function createServices(config: CoordinatorConfig): CoordinatorServices;

package/dist/src/server-setup.js

@@ -1,6 +1,11 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
 import { initDatabase } from "./database.js";
+import { registerConsultationTools } from "./tools/consultation-tools.js";
+import { registerAgentTools } from "./tools/agents-tools.js";
+import { registerFilesTools } from "./tools/files-tools.js";
+import { registerDependenciesTools } from "./tools/dependencies-tools.js";
+import { registerStatusTools } from "./tools/status-tools.js";
+import { registerMqttTools } from "./tools/mqtt-tools.js";
 import { AgentRegistry } from "./agent-registry.js";
 import { Consultation } from "./consultation.js";
 import { ConflictDetector } from "./conflict-detector.js";
@@ -11,9 +16,9 @@ import { SummaryContextProvider } from "./context-provider.js";
 import { IntrospectionManager } from "./introspection.js";
 import { SseEmitter } from "./sse-emitter.js";
 import { MqttBridge } from "./mqtt-bridge.js";
-import { assessPlanQuality } from "./plan-quality.js";
 import { AgentActivityTracker } from "./agent-activity.js";
 import { QuotaCache } from "./quota/quota-cache.js";
+import { Metrics } from "./metrics.js";
 import { createLogger } from "./logger.js";
 import { getVersion } from "../cli/version.js";
 const VERSION = getVersion();
@@ -32,6 +37,7 @@ export function createServices(config) {
     const contextProvider = new SummaryContextProvider(registry, consultation, fileTracker);
     const sseEmitter = new SseEmitter();
     const mqttBridge = new MqttBridge(logger.child({ component: "mqtt" }));
+    const metrics = new Metrics();
     // Quota cache — macOS-only for now, Linux/Windows stubs return 503 via the
     // /api/quota handler so raids keep running without a quota guardrail there.
     // onRefresh fans the new data out to dashboard (SSE) + any live listener (MQTT)
@@ -58,8 +64,9 @@ export function createServices(config) {
         else if (event.type === "agent_offline")
             quotaCache.onAgentInactive();
     });
-    // Centralized resolution → SSE + MQTT
+    // Centralized resolution → SSE + MQTT + metrics
     consultation.onResolve((event) => {
+        metrics.recordThreadResolved(event.resolution_type);
         sseEmitter.emit("thread_resolved", {
             thread_id: event.thread_id,
             resolution_type: event.resolution_type,
@@ -73,10 +80,15 @@ export function createServices(config) {
         if (event.resolution_type !== "auto_resolved") {
             mqttBridge.publishResolution(event.thread_id, "resolved", event.resolution_summary || "");
         }
+        // P1 fix: clear the retained `coordinator/consultations/new` event so a
+        // coordinator restart doesn't re-broadcast a consultation that's already
+        // been resolved. No-op when the retained slot holds a different (newer)
+        // thread.
+        mqttBridge.clearRetainedConsultation(event.thread_id);
     });
     return {
         logger, registry, activityTracker, consultation, conflictDetector,
-        depMap, fileTracker, impactScorer, introspection, contextProvider, sseEmitter, mqttBridge, quotaCache,
+        depMap, fileTracker, impactScorer, introspection, contextProvider, sseEmitter, mqttBridge, quotaCache, metrics,
     };
 }
 /** Create a new McpServer bound to the shared services (one per MCP session). */
@@ -87,367 +99,14 @@ export function createMcpServer(services) {
         name: "mcp-coordinator-v3",
         version: VERSION,
     });
-    // ── AGENT REGISTRY TOOLS ──
-    server.tool("register_agent", "Register agent as online with module list", {
-        agent_id: z.string(),
-        name: z.string(),
-        modules: z.array(z.string()),
-    }, async ({ agent_id, name, modules }) => {
-        mcpLog.info({ tool: "register_agent", agent_id, name, module_count: modules.length }, "Tool called");
-        const agent = registry.register(agent_id, name, modules);
-        sseEmitter.emit("agent_online", { agent_id, name, modules });
-        mqttBridge.registerAgent(agent_id, name);
-        return { content: [{ type: "text", text: JSON.stringify(agent) }] };
-    });
-    server.tool("list_agents", "List registered agents", {
-        online_only: z.boolean().optional(),
-    }, async ({ online_only }) => {
-        const agents = online_only ? registry.listOnline() : registry.listAll();
-        return { content: [{ type: "text", text: JSON.stringify(agents) }] };
-    });
-    server.tool("heartbeat", "Update agent activity status and last seen timestamp", {
-        agent_id: z.string(),
-        current_file: z.string().optional(),
-        current_thread: z.string().optional(),
-    }, async ({ agent_id, current_file, current_thread }) => {
-        registry.heartbeat(agent_id);
-        activityTracker.heartbeat(agent_id, {
-            currentFile: current_file || null,
-            currentThread: current_thread || null,
-        });
-        const activity = activityTracker.getActivity(agent_id);
-        sseEmitter.emit("agent_activity", {
-            agent_id, activity_status: activity.activity_status,
-            current_file: activity.current_file, current_thread: activity.current_thread,
-        });
-        return { content: [{ type: "text", text: JSON.stringify(activity) }] };
-    });
-    server.tool("agent_activity", "Get activity status for all online agents", {}, async () => {
-        const activities = activityTracker.listAll({ idleAfterMinutes: 5 });
-        return { content: [{ type: "text", text: JSON.stringify(activities) }] };
-    });
-    // ── CONSULTATION TOOLS ──
-    server.tool("announce_work", "Open a consultation thread before starting work", {
-        agent_id: z.string(),
-        subject: z.string(),
-        plan: z.string().optional(),
-        target_modules: z.array(z.string()),
-        target_files: z.array(z.string()),
-        depends_on_files: z.array(z.string()).optional(),
-        exports_affected: z.array(z.string()).optional(),
-        keep_open: z.boolean().optional().describe("Keep thread open even if no agents are concerned (for manual coordination like games or debates)"),
-        assigned_to: z.string().optional().describe("Directed-dispatch: only this agent_id will be allowed to claim the thread. Use for lead→worker handoffs in maitre/chaine/relais presets. Implies keep_open=true."),
-    }, async ({ agent_id, subject, plan, target_modules, target_files, depends_on_files, exports_affected, keep_open, assigned_to }) => {
-        mcpLog.info({ tool: "announce_work", agent_id, subject, target_modules, target_files, assigned_to }, "Tool called");
-        // Quality gate on plan
-        const planQuality = assessPlanQuality(plan);
-        const effectiveMode = planQuality.mode;
-        const conflicts = conflictDetector.detect({ agent_id, target_modules, target_files });
-        const thread = consultation.announceWork({
-            agent_id, subject, plan, target_modules, target_files, depends_on_files, exports_affected, keep_open, assigned_to,
-        });
-        // Store conflicts on thread
-        if (conflicts.length > 0) {
-            const db = (await import("./database.js")).getDb();
-            db.prepare("UPDATE threads SET conflicts = ? WHERE id = ?")
-                .run(JSON.stringify(conflicts), thread.id);
-        }
-        // Impact scoring: categorize all online agents
-        const categorized = impactScorer.categorize({
-            agent_id, target_modules, target_files, depends_on_files, exports_affected,
-        });
-        // Override expected_respondents with concerned agents from scorer
-        {
-            const db = (await import("./database.js")).getDb();
-            const concernedIds = categorized.concerned.map(s => s.agent_id);
-            db.prepare("UPDATE threads SET expected_respondents = ? WHERE id = ?")
-                .run(JSON.stringify(concernedIds), thread.id);
-            // Only auto-resolve when truly alone — no other online agents.
-            // If peers are online but not yet concerned, keep the thread open so
-            // a subsequent announce can still match via Layer 0. Thread timeouts
-            // naturally if no one joins.
-            const otherOnlineCount = registry.listOnline().filter((a) => a.id !== agent_id).length;
-            const shouldAutoResolve = concernedIds.length === 0 && otherOnlineCount === 0;
-            if (shouldAutoResolve && thread.status === "open" && !keep_open) {
-                db.prepare("UPDATE threads SET status = 'resolved', resolved_at = ? WHERE id = ?")
-                    .run(new Date().toISOString(), thread.id);
-                consultation.emitResolution(thread.id, "auto_resolved");
-            }
-        }
-        // Emit impact_scored SSE events for all agents
-        for (const s of [...categorized.concerned, ...categorized.gray_zone, ...categorized.pass]) {
-            sseEmitter.emit("impact_scored", {
-                thread_id: thread.id, agent_id: s.agent_id, agent_name: s.agent_name,
-                score: s.score, reasons: s.reasons, category: s.score >= 90 ? "concerned" : s.score >= 30 ? "gray_zone" : "pass",
-            });
-        }
-        // Create introspection records and emit introspection_requested for gray_zone agents
-        for (const s of categorized.gray_zone) {
-            introspection.create({ thread_id: thread.id, agent_id: s.agent_id, score: s.score, reasons: s.reasons });
-            sseEmitter.emit("introspection_requested", {
-                thread_id: thread.id, agent_id: s.agent_id, agent_name: s.agent_name, score: s.score, reasons: s.reasons,
-            });
-        }
-        // Emit downgrade event when plan is provided but quality is insufficient
-        if (plan && effectiveMode === "discovery") {
-            sseEmitter.emit("impact_scored", {
-                thread_id: thread.id,
-                agent_id: agent_id,
-                agent_name: registry.get(agent_id)?.name || agent_id,
-                score: planQuality.score,
-                reasons: [`plan downgraded: score ${planQuality.score}/3 — ${!planQuality.checks.mentions_files ? 'no files' : ''} ${!planQuality.checks.concrete_approach ? 'vague approach' : ''} ${!planQuality.checks.sufficient_detail ? 'too short' : ''}`.trim()],
-                category: "plan_quality",
-            });
-        }
-        const updated = consultation.getThread(thread.id);
-        const respondents = JSON.parse(updated.expected_respondents || "[]");
-        sseEmitter.emit("thread_opened", {
-            thread_id: thread.id, initiator: agent_id, subject, target_modules, conflicts,
-            expected_respondents: respondents,
-            mode: effectiveMode,
-            plan: plan || null,
-            plan_quality: planQuality,
-        });
-        mqttBridge.publishConsultation(thread.id, agent_id, subject, target_modules);
-        // Gather context from concerned agents for the initiator
-        const contextForInitiator = respondents.map((rid) => contextProvider.getRelevantContext(rid, { thread_id: updated.id, subject, target_modules, target_files })).filter((ctx) => ctx.modules.length > 0);
-        return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify({ thread: updated, conflicts, context: contextForInitiator, impact: categorized }),
-                }],
-        };
-    });
-    server.tool("post_to_thread", "Post a message to a consultation thread", {
-        thread_id: z.string(),
-        agent_id: z.string(),
-        agent_name: z.string().optional(),
-        type: z.enum(["context", "suggestion", "warning"]),
-        content: z.string(),
-        context_snapshot: z.string().optional(),
-        in_reply_to: z.string().optional(),
-    }, async ({ thread_id, agent_id, agent_name, type, content, context_snapshot, in_reply_to }) => {
-        mcpLog.info({ tool: "post_to_thread", thread_id, agent_id, type }, "Tool called");
-        const msg = consultation.postToThread({
-            thread_id, agent_id, agent_name, type, content, context_snapshot, in_reply_to,
-        });
-        const thread = consultation.getThread(thread_id);
-        sseEmitter.emit("message_posted", {
-            thread_id, agent_id, agent_name: agent_name || agent_id,
-            type, content, round: thread?.round || 1,
-            token_estimate: msg.token_estimate || 0,
-        });
-        mqttBridge.publishMessage(thread_id, agent_id, type, content);
-        return { content: [{ type: "text", text: JSON.stringify(msg) }] };
-    });
-    server.tool("propose_resolution", "Propose a resolution for the consultation", {
-        thread_id: z.string(),
-        agent_id: z.string(),
-        summary: z.string(),
-        plan: z.string().optional(),
-    }, async ({ thread_id, agent_id, summary, plan }) => {
-        mcpLog.info({ tool: "propose_resolution", thread_id, agent_id }, "Tool called");
-        consultation.proposeResolution(thread_id, agent_id, summary);
-        sseEmitter.emit("resolution_proposed", { thread_id, agent_id, summary });
-        mqttBridge.publishResolution(thread_id, "resolving", summary);
-        const thread = consultation.getThread(thread_id);
-        return { content: [{ type: "text", text: JSON.stringify(thread) }] };
-    });
-    server.tool("approve_resolution", "Approve the proposed resolution", {
-        thread_id: z.string(),
-        agent_id: z.string(),
-    }, async ({ thread_id, agent_id }) => {
-        mcpLog.info({ tool: "approve_resolution", thread_id, agent_id }, "Tool called");
-        const agentInfo = registry.get(agent_id);
-        consultation.approveResolution(thread_id, agent_id, agentInfo?.name);
-        const thread = consultation.getThread(thread_id);
-        return { content: [{ type: "text", text: JSON.stringify(thread) }] };
-    });
-    server.tool("contest_resolution", "Contest the proposed resolution", {
-        thread_id: z.string(),
-        agent_id: z.string(),
-        reason: z.string(),
-    }, async ({ thread_id, agent_id, reason }) => {
-        mcpLog.info({ tool: "contest_resolution", thread_id, agent_id }, "Tool called");
-        consultation.contestResolution(thread_id, agent_id, reason);
-        const thread = consultation.getThread(thread_id);
-        return { content: [{ type: "text", text: JSON.stringify(thread) }] };
-    });
-    server.tool("close_thread", "Close a consultation thread", {
-        thread_id: z.string(),
-        agent_id: z.string(),
-        summary: z.string(),
-    }, async ({ thread_id, agent_id, summary }) => {
-        mcpLog.info({ tool: "close_thread", thread_id, agent_id }, "Tool called");
-        consultation.closeThread(thread_id, agent_id, summary);
-        return { content: [{ type: "text", text: "closed" }] };
-    });
-    server.tool("cancel_thread", "Cancel a consultation thread", {
-        thread_id: z.string(),
-        agent_id: z.string(),
-        reason: z.string().optional(),
-    }, async ({ thread_id, agent_id, reason }) => {
-        mcpLog.info({ tool: "cancel_thread", thread_id, agent_id }, "Tool called");
-        consultation.cancelThread(thread_id, agent_id, reason);
-        sseEmitter.emit("thread_cancelled", { thread_id, reason });
-        return { content: [{ type: "text", text: "cancelled" }] };
-    });
-    server.tool("get_thread", "Get a thread with all messages", {
-        thread_id: z.string(),
-    }, async ({ thread_id }) => {
-        const result = consultation.getThreadWithMessages(thread_id);
-        mcpLog.debug({ tool: "get_thread", thread_id, message_count: result?.messages.length }, "Tool called");
-        return { content: [{ type: "text", text: JSON.stringify(result) }] };
-    });
-    server.tool("get_thread_updates", "Get new messages since timestamp", {
-        agent_id: z.string(),
-        since: z.string().optional(),
-    }, async ({ agent_id, since }) => {
-        const updates = consultation.getThreadUpdates(agent_id, since);
-        return { content: [{ type: "text", text: JSON.stringify(updates) }] };
-    });
-    server.tool("list_threads", "List consultation threads", {
-        status: z.string().optional(),
-        agent_id: z.string().optional(),
-        module: z.string().optional(),
-        assigned_to_me: z.string().optional().describe("Filter to threads claimable by this agent_id: open pool (assigned_to NULL) OR directed to me. Use for worker agents receiving directed dispatches."),
-    }, async ({ status, agent_id, module, assigned_to_me }) => {
-        const threads = consultation.listThreads({ status, agent_id, module, assigned_to_me });
-        mcpLog.debug({ tool: "list_threads", status, agent_id, module, assigned_to_me, result_count: threads.length }, "Tool called");
-        return { content: [{ type: "text", text: JSON.stringify(threads) }] };
-    });
-    server.tool("log_action_summary", "Log a one-liner summary of an action", {
-        session_id: z.string(),
-        agent_id: z.string(),
-        file_path: z.string().optional(),
-        summary: z.string(),
-    }, async ({ session_id, agent_id, file_path, summary }) => {
-        const result = consultation.logActionSummary({ session_id, agent_id, file_path, summary });
-        sseEmitter.emit("action_summary", { agent_id, file_path, summary });
-        return { content: [{ type: "text", text: JSON.stringify(result) }] };
-    });
-    // ── FILE TRACKING TOOLS ──
-    server.tool("hot_files", "List files modified by multiple agents", {
-        since_minutes: z.number().optional(),
-    }, async ({ since_minutes }) => {
-        const files = fileTracker.getHotFiles(since_minutes || 30);
-        return { content: [{ type: "text", text: JSON.stringify(files) }] };
-    });
-    server.tool("get_session_files", "Get files modified in a session", {
-        session_id: z.string(),
-    }, async ({ session_id }) => {
-        const files = fileTracker.getBySession(session_id);
-        return { content: [{ type: "text", text: JSON.stringify(files) }] };
-    });
-    server.tool("check_file_conflict", "Check if another agent is editing a file", {
-        file_path: z.string(),
-        agent_id: z.string(),
-        within_minutes: z.number().optional(),
-    }, async ({ file_path, agent_id, within_minutes }) => {
-        const result = fileTracker.checkFileConflict(file_path, agent_id, within_minutes || 30);
-        return { content: [{ type: "text", text: JSON.stringify(result) }] };
-    });
-    // ── DEPENDENCY MAP TOOLS ──
-    server.tool("set_dependency_map", "Load module dependency graph", {
-        modules: z.string(), // JSON DependencyMap
-    }, async ({ modules }) => {
-        const map = JSON.parse(modules);
-        depMap.setMap(map);
-        return { content: [{ type: "text", text: "ok" }] };
-    });
-    server.tool("get_blast_radius", "Calculate impact of changes to a module", {
-        module_id: z.string(),
-    }, async ({ module_id }) => {
-        const radius = depMap.getBlastRadius(module_id);
-        return { content: [{ type: "text", text: JSON.stringify(radius) }] };
-    });
-    server.tool("get_module_info", "Get module dependency info", {
-        module_id: z.string(),
-    }, async ({ module_id }) => {
-        const info = depMap.getModuleInfo(module_id);
-        return { content: [{ type: "text", text: JSON.stringify(info) }] };
-    });
-    // ── STATUS TOOL ──
-    server.tool("coordinator_status", "Full system status", {}, async () => {
-        const online = registry.listOnline();
-        const openThreads = consultation.listThreads({ status: "open" });
-        const resolvingThreads = consultation.listThreads({ status: "resolving" });
-        const hotFiles = fileTracker.getHotFiles(30);
-        const status = {
-            agents_online: online.length,
-            agents: online.map((a) => ({ id: a.id, name: a.name, modules: JSON.parse(a.modules) })),
-            open_threads: openThreads.length,
-            resolving_threads: resolvingThreads.length,
-            hot_files: hotFiles.length,
-            mqtt_connected: mqttBridge.isConnected(),
-        };
-        mcpLog.debug({ tool: "coordinator_status", agents_online: online.length, open_threads: openThreads.length }, "Tool called");
-        return { content: [{ type: "text", text: JSON.stringify(status) }] };
-    });
-    // ── COORDINATION HELPERS ──
-    server.tool("wait_for_peers", "Block until at least N other online agents are registered, or timeout. Use before the first announce_work to avoid the race where one agent announces before peers have booted.", {
-        agent_id: z.string(),
-        min_peers: z.number().optional(),
-        timeout_seconds: z.number().optional(),
-    }, async ({ agent_id, min_peers, timeout_seconds }) => {
-        const targetPeers = min_peers ?? 1;
-        const timeoutMs = (timeout_seconds ?? 30) * 1000;
-        const pollIntervalMs = 1000;
-        const startedAt = Date.now();
-        mcpLog.info({ tool: "wait_for_peers", agent_id, min_peers: targetPeers, timeout_seconds: timeoutMs / 1000 }, "Tool called");
-        while (Date.now() - startedAt < timeoutMs) {
-            const peers = registry.listOnline().filter((a) => a.id !== agent_id);
-            if (peers.length >= targetPeers) {
-                return {
-                    content: [{
-                            type: "text",
-                            text: JSON.stringify({
-                                ready: true,
-                                online_peers: peers.map((p) => ({ id: p.id, name: p.name })),
-                                waited_ms: Date.now() - startedAt,
-                            }),
-                        }],
-                };
-            }
-            await new Promise((r) => setTimeout(r, pollIntervalMs));
-        }
-        const finalPeers = registry.listOnline().filter((a) => a.id !== agent_id);
-        return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify({
-                        ready: false,
-                        timeout: true,
-                        online_peers: finalPeers.map((p) => ({ id: p.id, name: p.name })),
-                        waited_ms: Date.now() - startedAt,
-                    }),
-                }],
-        };
-    });
-    // ── MQTT LISTENER TOOLS (replaces standalone mqtt-mcp-bridge) ──
-    server.tool("wait_for_message", "Block until an MQTT consultation message arrives or timeout", {
-        agent_id: z.string(),
-        timeout_seconds: z.number().optional(),
-    }, async ({ agent_id, timeout_seconds }) => {
-        const timeoutMs = (timeout_seconds || 15) * 1000;
-        const msg = await mqttBridge.waitForMessage(agent_id, timeoutMs);
-        if (msg) {
-            return { content: [{ type: "text", text: JSON.stringify(msg) }] };
-        }
-        return { content: [{ type: "text", text: JSON.stringify({ timeout: true }) }] };
-    });
-    server.tool("get_queued_messages", "Get all queued MQTT messages without blocking", {
-        agent_id: z.string(),
-    }, async ({ agent_id }) => {
-        const messages = mqttBridge.getQueuedMessages(agent_id);
-        return { content: [{ type: "text", text: JSON.stringify(messages) }] };
-    });
-    server.tool("mqtt_publish", "Publish a message to an MQTT topic", {
-        topic: z.string(),
-        payload: z.string(),
-    }, async ({ topic, payload }) => {
-        mqttBridge.mqttPublish(topic, payload);
-        return { content: [{ type: "text", text: "published" }] };
-    });
+    // S1: all 23 MCP tools registered via per-domain modules under src/tools/.
+    // Each register*Tools function takes (server, services, mcpLog) and wires
+    // its tool group; nothing else lives here. See src/tools/*.ts for behavior.
+    registerAgentTools(server, services, mcpLog);
+    registerConsultationTools(server, services, mcpLog);
+    registerFilesTools(server, services, mcpLog);
+    registerDependenciesTools(server, services, mcpLog);
+    registerStatusTools(server, services, mcpLog);
+    registerMqttTools(server, services, mcpLog);
     return server;
 }

package/dist/src/sse-emitter.d.ts

@@ -1,10 +1,16 @@
 import type { CoordinatorEvent, EventType } from "./types.js";
 type EventListener = (event: CoordinatorEvent) => void;
+export declare const MAX_SSE_CLIENTS: number;
 export declare class SseEmitter {
     private listeners;
+    private rejectedCount;
     emit(type: EventType, payload: Record<string, unknown>): void;
     getEventsSince(lastId: number): CoordinatorEvent[];
     addListener(listener: EventListener): () => void;
     removeAllListeners(): void;
+    /** P3: introspection for tests + ops dashboards. */
+    listenerCount(): number;
+    /** P3: count of addListener calls refused due to MAX_SSE_CLIENTS. */
+    getRejectedCount(): number;
 }
 export {};

package/dist/src/sse-emitter.js

@@ -1,6 +1,25 @@
 import { getDb } from "./database.js";
+/**
+ * P3: bound the listener array so a runaway client (or DoS attempt) can't
+ * grow it without limit. Default 100 covers a small-to-mid swarm — enough
+ * headroom for a dashboard + every agent + a handful of CLI tailers, but
+ * not so large that a leak would silently exhaust memory. Override via
+ * COORDINATOR_MAX_SSE_CLIENTS for larger deployments.
+ */
+const DEFAULT_MAX_SSE_CLIENTS = 100;
+export const MAX_SSE_CLIENTS = (() => {
+    const raw = process.env.COORDINATOR_MAX_SSE_CLIENTS;
+    if (!raw)
+        return DEFAULT_MAX_SSE_CLIENTS;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_MAX_SSE_CLIENTS;
+})();
+const NOOP = () => { };
 export class SseEmitter {
     listeners = [];
+    // P3: track refusals so operators can see when the cap is being hit.
+    // Also lets tests assert "we refused without throwing" without scraping logs.
+    rejectedCount = 0;
     emit(type, payload) {
         const db = getDb();
         const payloadStr = JSON.stringify(payload);
@@ -13,8 +32,22 @@ export class SseEmitter {
             payload: payloadStr,
             created_at: new Date().toISOString(),
         };
-        for (const listener of this.listeners) {
-            listener(event);
+        // P3: async fan-out via setImmediate so a slow listener (e.g. a stalled
+        // SSE client whose socket buffer is full) cannot block siblings or the
+        // emit() caller. Snapshot the array first so a listener that unsubscribes
+        // mid-loop doesn't shift indices under us.
+        const snapshot = this.listeners.slice();
+        for (const listener of snapshot) {
+            setImmediate(() => {
+                try {
+                    listener(event);
+                }
+                catch {
+                    // Listener errors must not crash the emitter or affect siblings.
+                    // Drop silently — the SSE response writers swallow their own
+                    // socket errors via the unsubscribe path on req.on("close").
+                }
+            });
         }
     }
     getEventsSince(lastId) {
@@ -24,6 +57,13 @@ export class SseEmitter {
             .all(lastId);
     }
     addListener(listener) {
+        // P3: refuse-with-no-op when the cap is reached. Returning a no-op
+        // keeps the caller's unsubscribe contract intact (no special-casing
+        // upstream) while preventing the array from growing past MAX_SSE_CLIENTS.
+        if (this.listeners.length >= MAX_SSE_CLIENTS) {
+            this.rejectedCount++;
+            return NOOP;
+        }
         this.listeners.push(listener);
         return () => {
             this.listeners = this.listeners.filter((l) => l !== listener);
@@ -32,4 +72,12 @@ export class SseEmitter {
     removeAllListeners() {
         this.listeners = [];
     }
+    /** P3: introspection for tests + ops dashboards. */
+    listenerCount() {
+        return this.listeners.length;
+    }
+    /** P3: count of addListener calls refused due to MAX_SSE_CLIENTS. */
+    getRejectedCount() {
+        return this.rejectedCount;
+    }
 }

package/dist/src/tools/agents-tools.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CoordinatorServices } from "../server-setup.js";
+import type { Logger } from "../logger.js";
+/**
+ * S1: agent registry MCP tools (4 tools).
+ * register_agent, list_agents, heartbeat, agent_activity.
+ */
+export declare function registerAgentTools(server: McpServer, services: CoordinatorServices, mcpLog: Logger): void;

package/dist/src/tools/agents-tools.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+/**
+ * S1: agent registry MCP tools (4 tools).
+ * register_agent, list_agents, heartbeat, agent_activity.
+ */
+export function registerAgentTools(server, services, mcpLog) {
+    const { registry, activityTracker, sseEmitter, mqttBridge } = services;
+    server.tool("register_agent", "Register agent as online with module list", {
+        agent_id: z.string(),
+        name: z.string(),
+        modules: z.array(z.string()),
+    }, async ({ agent_id, name, modules }) => {
+        mcpLog.info({ tool: "register_agent", agent_id, name, module_count: modules.length }, "Tool called");
+        const agent = registry.register(agent_id, name, modules);
+        sseEmitter.emit("agent_online", { agent_id, name, modules });
+        mqttBridge.registerAgent(agent_id, name);
+        return { content: [{ type: "text", text: JSON.stringify(agent) }] };
+    });
+    server.tool("list_agents", "List registered agents", {
+        online_only: z.boolean().optional(),
+    }, async ({ online_only }) => {
+        const agents = online_only ? registry.listOnline() : registry.listAll();
+        return { content: [{ type: "text", text: JSON.stringify(agents) }] };
+    });
+    server.tool("heartbeat", "Update agent activity status and last seen timestamp", {
+        agent_id: z.string(),
+        current_file: z.string().optional(),
+        current_thread: z.string().optional(),
+    }, async ({ agent_id, current_file, current_thread }) => {
+        registry.heartbeat(agent_id);
+        activityTracker.heartbeat(agent_id, {
+            currentFile: current_file || null,
+            currentThread: current_thread || null,
+        });
+        const activity = activityTracker.getActivity(agent_id);
+        sseEmitter.emit("agent_activity", {
+            agent_id, activity_status: activity.activity_status,
+            current_file: activity.current_file, current_thread: activity.current_thread,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(activity) }] };
+    });
+    server.tool("agent_activity", "Get activity status for all online agents", {}, async () => {
+        const activities = activityTracker.listAll({ idleAfterMinutes: 5 });
+        return { content: [{ type: "text", text: JSON.stringify(activities) }] };
+    });
+}

package/dist/src/tools/consultation-tools.d.ts

@@ -0,0 +1,21 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CoordinatorServices } from "../server-setup.js";
+import type { Logger } from "../logger.js";
+/**
+ * S1 fix (partial): consultation domain tools extracted from server-setup.ts.
+ *
+ * Originally these 11 tools (announce_work, post_to_thread, propose/approve/
+ * contest_resolution, close/cancel_thread, get_thread, get_thread_updates,
+ * list_threads, log_action_summary) lived inline in createMcpServer's
+ * 420-line body. Extraction here:
+ *   - reduces server-setup.ts by ~200 lines
+ *   - groups related tools by domain (= one file per concern)
+ *   - keeps behavior identical (no signature changes, no SSE/MQTT shape
+ *     changes — verified by all existing tests)
+ *
+ * Other tool groups (agents, files, dependencies, mqtt, status) remain in
+ * server-setup.ts under their existing section comments. Splitting them is
+ * straightforward following this pattern but kept out of this PR to minimize
+ * the diff for reviewers.
+ */
+export declare function registerConsultationTools(server: McpServer, services: CoordinatorServices, mcpLog: Logger): void;