macro-agent 0.1.1 → 0.1.3

package/dist/api/server.js

@@ -1,1554 +1,312 @@
 /**
- * API Server
+ * REST API server for macro-agent.
  *
- * Express server with REST API and WebSocket support for the multi-agent system.
+ * Provides HTTP endpoints for managing agents, tasks, teams, and metrics.
  *
- * Can be used in two modes:
- * 1. Standalone: createAPIServer() creates its own HTTP server
- * 2. Shared: createAPIApp() + setupAPIWebSocket() for external HTTP server
+ * @module api/server
  */
 import express from "express";
-import { WebSocketServer, WebSocket } from "ws";
-import http from "http";
-import { injectContext, } from "../steering/index.js";
-import { secureCompare } from "../auth/token.js";
-/**
- * Create shared state for API app and WebSocket handler
- */
-export function createAPISharedState() {
-    const wsClients = new Set();
-    const broadcast = (channel, message) => {
-        const data = JSON.stringify(message);
-        for (const client of wsClients) {
-            if (client.subscriptions.has(channel) && client.ws.readyState === WebSocket.OPEN) {
-                client.ws.send(data);
-            }
-        }
-    };
-    return {
-        initialized: false,
-        conversationHistory: [],
-        inFlightPrompts: new Map(),
-        isShuttingDown: false,
-        wsClients,
-        broadcast,
-    };
-}
-function conversationToSummary(conv) {
-    return {
-        id: conv.id,
-        type: conv.type,
-        status: conv.status,
-        subject: conv.subject ?? "",
-        created_by: conv.createdBy,
-        created_at: conv.createdAt,
-        updated_at: conv.updatedAt,
-        participant_count: conv.participantCount,
-        parent_conversation_id: conv.parentConversationId || undefined,
-    };
+// =============================================================================
+// Helpers
+// =============================================================================
+/** Extract a single string from Express v5 param/query (string | string[]). */
+function str(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value) && typeof value[0] === "string")
+        return value[0];
+    return undefined;
 }
-function conversationToDetail(conv) {
-    return {
-        ...conversationToSummary(conv),
-        closed_at: conv.closedAt || undefined,
-        closed_by: conv.closedBy || undefined,
-        close_reason: conv.closeReason || undefined,
-    };
-}
-function turnToSummary(turn) {
+async function collectMetricsPlaceholder(system, startTime) {
+    const agents = system.agentStore.listAgents();
+    const running = agents.filter((a) => a.state === "running").length;
+    const stopped = agents.filter((a) => a.state === "stopped").length;
+    const failed = agents.filter((a) => a.state === "failed").length;
+    let taskMetrics = { total: 0, open: 0, in_progress: 0, closed: 0 };
+    try {
+        const tasks = await system.tasksAdapter.listTasks();
+        taskMetrics = {
+            total: tasks.length,
+            open: tasks.filter((t) => t.status === "open").length,
+            in_progress: tasks.filter((t) => t.status === "in_progress").length,
+            closed: tasks.filter((t) => t.status === "closed").length,
+        };
+    }
+    catch {
+        // opentasks may be down
+    }
     return {
-        id: turn.id,
-        conversation_id: turn.conversationId,
-        participant: turn.participant,
-        content_type: turn.contentType,
-        content: turn.content,
-        timestamp: turn.timestamp,
-        source_type: turn.sourceType || undefined,
-        source_message_id: turn.sourceMessageId || undefined,
+        agents: {
+            total: agents.length,
+            running,
+            stopped,
+            failed,
+        },
+        tasks: taskMetrics,
+        uptime: (Date.now() - startTime) / 1000,
+        collectedAt: new Date().toISOString(),
     };
 }
-/**
- * Register conversation API routes on an Express app.
- * Used by both standalone and shared server modes.
- */
-function registerConversationRoutes(app, services, sendError) {
-    if (!services.mailService)
-        return;
-    const { mailService } = services;
-    // GET /api/conversations - List conversations
-    app.get("/api/conversations", (req, res) => {
-        const params = req.query;
-        let conversations = mailService.listConversations({
-            type: params.type,
-            status: params.status,
+// =============================================================================
+// Factory
+// =============================================================================
+export function createApiServer(system, config) {
+    const port = config?.port ?? 3000;
+    const host = config?.host ?? "127.0.0.1";
+    const startTime = Date.now();
+    const app = express();
+    app.use(express.json());
+    // ── Health ──────────────────────────────────────────────────────
+    app.get("/api/health", (_req, res) => {
+        res.json({
+            ok: true,
+            uptime: (Date.now() - startTime) / 1000,
+            version: "0.1.1",
         });
-        const total = conversations.length;
-        const offset = parseInt(params.offset) || 0;
-        const limit = parseInt(params.limit) || 50;
-        conversations = conversations.slice(offset, offset + limit);
-        const response = {
-            conversations: conversations.map(conversationToSummary),
-            total,
-        };
-        res.json(response);
-    });
-    // GET /api/conversations/:id - Get conversation detail
-    app.get("/api/conversations/:id", (req, res) => {
-        const conv = mailService.getConversation(req.params.id);
-        if (!conv) {
-            return sendError(res, 404, "CONVERSATION_NOT_FOUND", `Conversation not found: ${req.params.id}`);
-        }
-        res.json(conversationToDetail(conv));
     });
-    // GET /api/conversations/:id/turns - List turns for a conversation
-    app.get("/api/conversations/:id/turns", (req, res) => {
-        const conv = mailService.getConversation(req.params.id);
-        if (!conv) {
-            return sendError(res, 404, "CONVERSATION_NOT_FOUND", `Conversation not found: ${req.params.id}`);
+    // ── Agents ─────────────────────────────────────────────────────
+    app.get("/api/agents", (req, res) => {
+        try {
+            const state = str(req.query.state);
+            const role = str(req.query.role);
+            const team = str(req.query.team);
+            const limit = parseInt(str(req.query.limit) ?? "50", 10) || 50;
+            const offset = parseInt(str(req.query.offset) ?? "0", 10) || 0;
+            const filter = {};
+            if (state)
+                filter.state = state;
+            if (role)
+                filter.role = role;
+            if (team)
+                filter.team = team;
+            const agents = system.agentManager.list(Object.keys(filter).length > 0 ? filter : undefined);
+            const total = agents.length;
+            const paged = agents.slice(offset, offset + limit);
+            res.json({ agents: paged, total });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message ?? "Internal server error" });
         }
-        const turns = mailService.listTurns({ conversationId: req.params.id });
-        const limit = parseInt(req.query.limit) || 50;
-        const offset = parseInt(req.query.offset) || 0;
-        const paged = turns.slice(offset, offset + limit);
-        const response = {
-            turns: paged.map(turnToSummary),
-            total: turns.length,
-        };
-        res.json(response);
     });
-    // POST /api/conversations/:id/close - Close a conversation
-    app.post("/api/conversations/:id/close", (req, res) => {
-        const conv = mailService.getConversation(req.params.id);
-        if (!conv) {
-            return sendError(res, 404, "CONVERSATION_NOT_FOUND", `Conversation not found: ${req.params.id}`);
-        }
-        if (conv.status !== "active") {
-            return sendError(res, 400, "ALREADY_CLOSED", `Conversation already ${conv.status}`);
+    app.get("/api/agents/:id", (req, res) => {
+        try {
+            const id = str(req.params.id);
+            const agent = system.agentManager.get(id);
+            if (!agent) {
+                res.status(404).json({ error: "Agent not found" });
+                return;
+            }
+            res.json(agent);
         }
-        const body = req.body;
-        mailService.closeConversation({
-            conversationId: req.params.id,
-            closedBy: "api",
-            reason: body.reason ?? "completed",
-        });
-        res.json({ success: true });
-    });
-    // GET /api/conversations/:id/participants - List participants
-    app.get("/api/conversations/:id/participants", (req, res) => {
-        const conv = mailService.getConversation(req.params.id);
-        if (!conv) {
-            return sendError(res, 404, "CONVERSATION_NOT_FOUND", `Conversation not found: ${req.params.id}`);
+        catch (err) {
+            res.status(500).json({ error: err.message ?? "Internal server error" });
         }
-        const participants = mailService.listParticipants(req.params.id);
-        res.json({ participants, total: participants.length });
     });
-}
-// ─────────────────────────────────────────────────────────────────
-// Create API Server
-// ─────────────────────────────────────────────────────────────────
-export function createAPIServer(services, config = {}) {
-    const { port = 3000, host = "localhost", cors = true, shutdownGracePeriodMs = 5000, serverToken } = config;
-    const { eventStore, agentManager, taskManager } = services;
-    // Server state
-    const state = {
-        initialized: false,
-        conversationHistory: [],
-        inFlightPrompts: new Map(),
-        isShuttingDown: false,
-    };
-    // WebSocket clients
-    const wsClients = new Set();
-    // Create Express app
-    const app = express();
-    // Middleware
-    app.use(express.json());
-    if (cors) {
-        app.use((_req, res, next) => {
-            res.header("Access-Control-Allow-Origin", "*");
-            res.header("Access-Control-Allow-Headers", "Content-Type, Authorization");
-            res.header("Access-Control-Allow-Methods", "GET, POST, DELETE");
-            next();
-        });
-    }
-    // Bearer token auth middleware (skip /health)
-    if (serverToken) {
-        app.use((req, res, next) => {
-            if (req.path === "/health")
-                return next();
-            const authHeader = req.headers.authorization;
-            const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : undefined;
-            if (!token || !secureCompare(token, serverToken)) {
-                const error = { error: "Unauthorized", code: "AUTH_REQUIRED" };
-                res.status(401).json(error);
+    app.get("/api/agents/:id/hierarchy", (req, res) => {
+        try {
+            const id = str(req.params.id);
+            const depthStr = str(req.query.depth);
+            const options = depthStr ? { depth: parseInt(depthStr, 10) } : undefined;
+            const hierarchy = system.agentManager.getHierarchy(id, options);
+            if (!hierarchy) {
+                res.status(404).json({ error: "Agent not found" });
                 return;
             }
-            next();
-        });
-    }
-    // ─────────────────────────────────────────────────────────────────
-    // Helper Functions
-    // ─────────────────────────────────────────────────────────────────
-    function agentToSummary(agent) {
-        return {
-            id: agent.id,
-            session_id: agent.session_id,
-            task: agent.task ?? "No task",
-            state: agent.state,
-            parent: agent.parent,
-            children_count: agentManager.getChildren(agent.id).length,
-            created_at: agent.created_at,
-        };
-    }
-    function agentToDetail(agent) {
-        return {
-            ...agentToSummary(agent),
-            lineage: agent.lineage,
-            task_id: agent.task_id,
-            config: agent.config,
-            started_at: agent.started_at,
-            stopped_at: agent.stopped_at,
-            stop_reason: agent.stop_reason,
-        };
-    }
-    function taskToSummary(task) {
-        return {
-            id: task.id,
-            description: task.description,
-            status: task.status,
-            assigned_agent: task.assigned_agent,
-            created_at: task.created_at,
-        };
-    }
-    function taskToDetail(task) {
-        return {
-            ...taskToSummary(task),
-            parent_task: task.parent_task,
-            subtasks: task.subtasks ?? [],
-            created_by: task.created_by,
-            inputs: task.inputs,
-            outputs: task.outputs,
-            artifacts: task.artifacts,
-            started_at: task.started_at,
-            completed_at: task.completed_at,
-        };
-    }
-    function eventToSummary(event) {
-        let summary = "";
-        switch (event.type) {
-            case "spawn":
-                summary = `Agent ${event.payload.agent_id} spawned`;
-                break;
-            case "stop":
-                summary = `Agent terminated: ${event.payload.reason}`;
-                break;
-            case "status":
-                summary = `${event.payload.status_type}: ${event.payload.summary}`;
-                break;
-            case "message":
-                summary = `Message: ${String(event.payload.content).substring(0, 50)}...`;
-                break;
-            case "task":
-                summary = `Task ${event.payload.action}: ${event.payload.task_id}`;
-                break;
-            default:
-                summary = `${event.type} event`;
+            res.json(hierarchy);
         }
-        return {
-            id: event.id,
-            type: event.type,
-            timestamp: event.timestamp,
-            source_agent_id: event.source.agent_id,
-            target_agent_id: event.target?.agent_id,
-            summary,
-        };
-    }
-    function buildHierarchyNode(agent) {
-        const children = agentManager.getChildren(agent.id);
-        return {
-            agent_id: agent.id,
-            task: agent.task ?? "No task",
-            state: agent.state,
-            children: children.map(buildHierarchyNode),
-        };
-    }
-    function sendError(res, status, code, message) {
-        const error = { error: message, code };
-        res.status(status).json(error);
-    }
-    function broadcastToChannel(channel, message) {
-        const data = JSON.stringify(message);
-        for (const client of wsClients) {
-            if (client.subscriptions.has(channel) && client.ws.readyState === WebSocket.OPEN) {
-                client.ws.send(data);
-            }
+        catch (err) {
+            res.status(500).json({ error: err.message ?? "Internal server error" });
         }
-    }
-    // ─────────────────────────────────────────────────────────────────
-    // API Routes
-    // ─────────────────────────────────────────────────────────────────
-    // POST /api/init - Initialize the system
-    app.post("/api/init", async (req, res) => {
+    });
+    app.get("/api/agents/:id/inbox", async (req, res) => {
         try {
-            if (state.initialized) {
-                return sendError(res, 400, "ALREADY_INITIALIZED", "System already initialized");
+            const id = str(req.params.id);
+            const agent = system.agentManager.get(id);
+            if (!agent) {
+                res.status(404).json({ error: "Agent not found" });
+                return;
             }
-            const body = req.body;
-            const cwd = body.cwd ?? process.cwd();
-            const headManager = await agentManager.getOrCreateHeadManager({
-                cwd,
-                systemPrompt: body.system_prompt,
-                permissionMode: body.permission_mode,
+            const limit = parseInt(str(req.query.limit) ?? "20", 10) || 20;
+            const unreadOnly = str(req.query.unreadOnly) === "true";
+            const messages = await system.inboxAdapter.checkInbox(id, {
+                limit,
+                unreadOnly,
             });
-            state.initialized = true;
-            state.headManagerId = headManager.id;
-            state.startedAt = Date.now();
-            // Create session conversation for mail tracking
-            if (services.mailService && services.conversationMap) {
-                try {
-                    const { conversationId } = services.mailService.createConversation({
-                        type: "session",
-                        subject: "User session",
-                        createdBy: "user",
-                    });
-                    services.mailService.joinConversation({
-                        conversationId,
-                        participantId: headManager.id,
-                        role: "worker",
-                    });
-                    services.conversationMap.setSessionConversation(headManager.id, conversationId);
-                }
-                catch {
-                    // Never fail init due to mail errors
-                }
-            }
-            const response = {
-                success: true,
-                head_manager_id: headManager.id,
-                session_id: headManager.session_id,
-            };
-            res.json(response);
+            res.json({ messages });
         }
-        catch (error) {
-            sendError(res, 500, "INIT_FAILED", `Failed to initialize: ${error}`);
+        catch (err) {
+            res.status(500).json({ error: err.message ?? "Internal server error" });
         }
     });
-    // GET /api/status - Get system status
-    app.get("/api/status", (_req, res) => {
-        const status = getStatus();
-        res.json(status);
-    });
-    // GET /api/team - Get active team info
-    app.get("/api/team", (_req, res) => {
-        // Check for team config in EventStore
-        const statusEvents = eventStore.query({ type: "status", limit: 50 });
-        const teamConfigEvent = statusEvents.find((e) => e.payload?.team_config != null);
-        if (!teamConfigEvent?.payload?.team_config) {
-            res.json({ active: false });
-            return;
-        }
-        const tc = teamConfigEvent.payload.team_config;
-        res.json({
-            active: true,
-            name: tc.teamName,
-            strategy: tc.strategy,
-            taskMode: tc.taskMode,
-            enforcement: tc.enforcement,
-        });
-    });
-    // ─────────────────────────────────────────────────────────────────
-    // Metrics Endpoints (Phase 5)
-    // ─────────────────────────────────────────────────────────────────
-    // GET /api/metrics/throughput - Task throughput metrics
-    app.get("/api/metrics/throughput", (req, res) => {
-        const windowMs = req.query.window_ms
-            ? Number(req.query.window_ms)
-            : 5 * 60 * 1000;
-        const after = Date.now() - windowMs;
-        const taskEvents = eventStore.query({ type: "task", after });
-        let completed = 0, failed = 0, created = 0;
-        for (const e of taskEvents) {
-            const action = e.payload?.action;
-            if (action === "created")
-                created++;
-            else if (action === "completed")
-                completed++;
-            else if (action === "failed")
-                failed++;
-        }
-        const windowMin = windowMs / 60000;
-        res.json({
-            tasksCompleted: completed,
-            tasksFailed: failed,
-            tasksCreated: created,
-            completedPerMinute: windowMin > 0 ? Math.round((completed / windowMin) * 100) / 100 : 0,
-            windowMs,
-        });
-    });
-    // GET /api/metrics/utilization - Agent utilization metrics
-    app.get("/api/metrics/utilization", (_req, res) => {
-        const allAgents = eventStore.listAgents();
-        const active = allAgents.filter((a) => a.state === "running" || a.state === "spawning");
-        const byRole = {};
-        const byState = {};
-        for (const a of active) {
-            const role = a.role ?? "unknown";
-            byRole[role] = (byRole[role] ?? 0) + 1;
-        }
-        for (const a of allAgents) {
-            byState[a.state] = (byState[a.state] ?? 0) + 1;
-        }
-        res.json({
-            activeAgents: active.length,
-            totalAgents: allAgents.length,
-            agentsByRole: byRole,
-            agentsByState: byState,
-        });
-    });
-    // GET /api/metrics/errors - Error metrics
-    app.get("/api/metrics/errors", (req, res) => {
-        const windowMs = req.query.window_ms
-            ? Number(req.query.window_ms)
-            : 30 * 60 * 1000;
-        const limit = req.query.limit ? Number(req.query.limit) : 20;
-        const statusEvents = eventStore.query({
-            type: "status",
-            after: Date.now() - windowMs,
-        });
-        const errors = [];
-        const byType = {};
-        for (const e of statusEvents) {
-            if (e.payload?.status_type !== "failed")
-                continue;
-            const agentId = e.source?.agent_id ?? "unknown";
-            const summary = e.payload?.summary ?? "Unknown error";
-            const errorType = e.payload?.details?.signal ?? "agent_failed";
-            errors.push({ timestamp: e.timestamp, agentId, type: errorType, summary });
-            byType[errorType] = (byType[errorType] ?? 0) + 1;
-        }
-        errors.sort((a, b) => b.timestamp - a.timestamp);
-        res.json({
-            totalErrors: errors.length,
-            errorsByType: byType,
-            recentErrors: errors.slice(0, limit),
-        });
-    });
-    // POST /api/conversation/message - Send message to head manager
-    app.post("/api/conversation/message", async (req, res) => {
-        // Reject new messages during shutdown
-        if (state.isShuttingDown) {
-            return sendError(res, 503, "SHUTTING_DOWN", "Server is shutting down");
-        }
-        const promptId = `prompt_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    app.post("/api/agents", async (req, res) => {
         try {
-            if (!state.initialized || !state.headManagerId) {
-                return sendError(res, 400, "NOT_INITIALIZED", "System not initialized");
-            }
-            const body = req.body;
-            if (!body.message) {
-                return sendError(res, 400, "MISSING_MESSAGE", "Message is required");
-            }
-            // Add user message to history
-            state.conversationHistory.push({
-                role: "user",
-                content: body.message,
-                timestamp: Date.now(),
-            });
-            // Record user turn in session conversation
-            if (services.mailService && services.conversationMap && state.headManagerId) {
-                try {
-                    const sessionConvId = services.conversationMap.getSessionConversation(state.headManagerId);
-                    if (sessionConvId) {
-                        services.mailService.recordTurn({
-                            conversationId: sessionConvId,
-                            participant: "user",
-                            contentType: "text",
-                            content: body.message,
-                        });
-                    }
-                }
-                catch {
-                    // Never fail message handling due to mail errors
-                }
-            }
-            // Broadcast to conversation channel
-            broadcastToChannel("conversation", {
-                type: "message",
-                data: {
-                    role: "user",
-                    content: body.message,
-                    timestamp: Date.now(),
-                },
-            });
-            // Track this prompt as in-flight
-            let resolvePrompt;
-            const promptPromise = new Promise((resolve) => {
-                resolvePrompt = resolve;
-            });
-            state.inFlightPrompts.set(promptId, promptPromise);
-            // Send to head manager and collect response
-            let responseContent = "";
-            try {
-                for await (const update of agentManager.prompt(state.headManagerId, body.message)) {
-                    if ("sessionUpdate" in update && update.sessionUpdate === "agent_message_chunk") {
-                        const chunk = update;
-                        if (chunk.content.type === "text" && chunk.content.text) {
-                            responseContent += chunk.content.text;
-                        }
-                    }
-                }
-            }
-            finally {
-                // Mark prompt as complete
-                resolvePrompt();
-                state.inFlightPrompts.delete(promptId);
-            }
-            // Add assistant response to history
-            state.conversationHistory.push({
-                role: "assistant",
-                content: responseContent,
-                agent_id: state.headManagerId,
-                timestamp: Date.now(),
-            });
-            // Record assistant turn in session conversation
-            if (services.mailService && services.conversationMap && state.headManagerId) {
-                try {
-                    const sessionConvId = services.conversationMap.getSessionConversation(state.headManagerId);
-                    if (sessionConvId) {
-                        services.mailService.recordTurn({
-                            conversationId: sessionConvId,
-                            participant: state.headManagerId,
-                            contentType: "text",
-                            content: responseContent,
-                        });
-                    }
-                }
-                catch {
-                    // Never fail message handling due to mail errors
-                }
+            const { task, role, parent, cwd } = req.body;
+            if (!task) {
+                res.status(400).json({ error: "Missing required field: task" });
+                return;
             }
-            // Broadcast response
-            broadcastToChannel("conversation", {
-                type: "message",
-                data: {
-                    role: "assistant",
-                    content: responseContent,
-                    agent_id: state.headManagerId,
-                    timestamp: Date.now(),
-                },
-            });
-            res.json({
-                content: responseContent,
-                agent_id: state.headManagerId,
-                message_id: `msg_${Date.now()}`,
+            const spawned = await system.agentManager.spawn({
+                task,
+                role,
+                parent,
+                cwd,
             });
+            res.status(201).json(spawned);
         }
-        catch (error) {
-            // Ensure we clean up the in-flight prompt on error
-            state.inFlightPrompts.delete(promptId);
-            sendError(res, 500, "MESSAGE_FAILED", `Failed to process message: ${error}`);
-        }
-    });
-    // GET /api/conversation/history - Get conversation history
-    app.get("/api/conversation/history", (req, res) => {
-        const limit = parseInt(req.query.limit) || 50;
-        const offset = parseInt(req.query.offset) || 0;
-        const history = state.conversationHistory.slice(offset, offset + limit);
-        const response = {
-            history,
-            total: state.conversationHistory.length,
-        };
-        res.json(response);
-    });
-    // GET /api/agents - List agents
-    app.get("/api/agents", (req, res) => {
-        const params = req.query;
-        let agents = agentManager.list();
-        // Apply filters
-        if (params.state) {
-            agents = agents.filter((a) => a.state === params.state);
-        }
-        if (params.parent !== undefined) {
-            const parentValue = params.parent === "null" ? null : params.parent;
-            agents = agents.filter((a) => a.parent === parentValue);
-        }
-        const total = agents.length;
-        // Apply pagination
-        const offset = params.offset ?? 0;
-        const limit = params.limit ?? 50;
-        agents = agents.slice(offset, offset + limit);
-        const response = {
-            agents: agents.map(agentToSummary),
-            total,
-        };
-        res.json(response);
-    });
-    // GET /api/agents/:id - Get agent details
-    app.get("/api/agents/:id", (req, res) => {
-        const id = req.params.id;
-        const agent = agentManager.get(id);
-        if (!agent) {
-            return sendError(res, 404, "AGENT_NOT_FOUND", `Agent not found: ${id}`);
-        }
-        res.json(agentToDetail(agent));
-    });
-    // GET /api/agents/:id/hierarchy - Get agent hierarchy
-    app.get("/api/agents/:id/hierarchy", (req, res) => {
-        const id = req.params.id;
-        const agent = agentManager.get(id);
-        if (!agent) {
-            return sendError(res, 404, "AGENT_NOT_FOUND", `Agent not found: ${id}`);
-        }
-        const hierarchy = agentManager.getHierarchy(id);
-        if (!hierarchy) {
-            return sendError(res, 500, "HIERARCHY_ERROR", "Failed to build hierarchy");
+        catch (err) {
+            res.status(500).json({ error: err.message ?? "Internal server error" });
         }
-        const response = {
-            tree: buildHierarchyNode(agent),
-            depth: hierarchy.depth,
-            total_agents: hierarchy.totalAgents,
-        };
-        res.json(response);
     });
-    // GET /api/tasks - List tasks
-    app.get("/api/tasks", (req, res) => {
-        const params = req.query;
-        let tasks = taskManager.list();
-        // Apply filters
-        if (params.status) {
-            tasks = tasks.filter((t) => t.status === params.status);
-        }
-        if (params.assigned_agent) {
-            tasks = tasks.filter((t) => t.assigned_agent === params.assigned_agent);
-        }
-        const total = tasks.length;
-        // Apply pagination
-        const offset = params.offset ?? 0;
-        const limit = params.limit ?? 50;
-        tasks = tasks.slice(offset, offset + limit);
-        const response = {
-            tasks: tasks.map(taskToSummary),
-            total,
-        };
-        res.json(response);
-    });
-    // GET /api/tasks/:id - Get task details
-    app.get("/api/tasks/:id", (req, res) => {
-        const id = req.params.id;
-        const task = taskManager.get(id);
-        if (!task) {
-            return sendError(res, 404, "TASK_NOT_FOUND", `Task not found: ${id}`);
-        }
-        res.json(taskToDetail(task));
-    });
-    // GET /api/events - List events with filters
-    app.get("/api/events", (req, res) => {
-        const params = req.query;
-        const events = eventStore.query({
-            type: params.type,
-            source_agent_id: params.source_agent_id,
-            target_agent_id: params.target_agent_id,
-            after: params.after,
-            before: params.before,
-            limit: (params.limit ?? 50) + 1, // Get one extra to check has_more
-        });
-        const limit = params.limit ?? 50;
-        const hasMore = events.length > limit;
-        const resultEvents = hasMore ? events.slice(0, limit) : events;
-        const response = {
-            events: resultEvents.map(eventToSummary),
-            total: resultEvents.length,
-            has_more: hasMore,
-        };
-        res.json(response);
-    });
-    // POST /api/agents/:id/inject - Inject context into agent session
-    app.post("/api/agents/:id/inject", async (req, res) => {
-        const id = req.params.id;
-        const body = req.body;
-        // Validate content
-        if (!body.content) {
-            return sendError(res, 400, "MISSING_CONTENT", "Content is required");
-        }
-        // Check agent exists
-        const agent = agentManager.get(id);
-        if (!agent) {
-            return sendError(res, 404, "AGENT_NOT_FOUND", `Agent not found: ${id}`);
-        }
-        // Create injection deps
-        const injectionDeps = {
-            getSession(agentId) {
-                const session = agentManager.getSession(agentId);
-                if (!session)
-                    return null;
-                return {
-                    inject: async (content) => session.inject(content),
-                    supportsInject: () => session.supportsInject(),
-                    checkInjectSupport: async () => session.supportsInject(),
-                    interruptWith: (content) => session.interruptWith(content),
-                };
-            },
-            isPrompting(agentId) {
-                return agentManager.isPrompting(agentId);
-            },
-            async sendMessage(_fromAgentId, toAgentId, content, priority) {
-                await services.messageRouter.sendToAddress({
-                    from: "__human__",
-                    to: { agent: toAgentId },
-                    content,
-                    options: { priority },
-                });
-            },
-        };
+    app.delete("/api/agents/:id", async (req, res) => {
         try {
-            const result = await injectContext(injectionDeps, id, body.content, {
-                urgent: body.urgent,
-                allowInterrupt: true,
-                source: { type: "human" },
-                reason: body.reason,
-            });
-            const response = {
-                success: result.success,
-                method: result.method,
-                error: result.error,
-                note: result.note,
-            };
-            if (result.success) {
-                res.json(response);
-            }
-            else {
-                res.status(500).json(response);
+            const id = str(req.params.id);
+            const agent = system.agentManager.get(id);
+            if (!agent) {
+                res.status(404).json({ error: "Agent not found" });
+                return;
             }
+            const reason = str(req.query.reason) ?? "cancelled";
+            await system.agentManager.terminate(id, reason);
+            res.json({ ok: true });
         }
-        catch (error) {
-            sendError(res, 500, "INJECTION_FAILED", `Failed to inject context: ${error}`);
+        catch (err) {
+            res.status(500).json({ error: err.message ?? "Internal server error" });
         }
     });
-    // Register conversation API routes (if mail service available)
-    registerConversationRoutes(app, services, sendError);
-    // ─────────────────────────────────────────────────────────────────
-    // HTTP Server
-    // ─────────────────────────────────────────────────────────────────
-    const server = http.createServer(app);
-    // ─────────────────────────────────────────────────────────────────
-    // WebSocket Server
-    // ─────────────────────────────────────────────────────────────────
-    const wss = new WebSocketServer({ server });
-    wss.on("connection", (ws) => {
-        const client = {
-            ws,
-            subscriptions: new Set(),
-        };
-        wsClients.add(client);
-        ws.on("message", (data) => {
+    // ── Tasks ──────────────────────────────────────────────────────
+    app.get("/api/tasks", async (req, res) => {
+        try {
+            const status = str(req.query.status);
+            const assignee = str(req.query.assignee);
+            const limitStr = str(req.query.limit);
+            const filter = {};
+            if (status)
+                filter.status = status;
+            if (assignee)
+                filter.assignee = assignee;
+            if (limitStr)
+                filter.limit = parseInt(limitStr, 10);
+            const tasks = await system.tasksAdapter.listTasks(Object.keys(filter).length > 0 ? filter : undefined);
+            res.json({ tasks });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message ?? "Internal server error" });
+        }
+    });
+    app.get("/api/tasks/ready", async (req, res) => {
+        try {
+            const limitStr = str(req.query.limit);
+            const tagsStr = str(req.query.tags);
+            const opts = {};
+            if (limitStr)
+                opts.limit = parseInt(limitStr, 10);
+            if (tagsStr)
+                opts.tags = tagsStr.split(",");
+            const tasks = await system.tasksAdapter.queryReady(opts);
+            res.json({ tasks });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message ?? "Internal server error" });
+        }
+    });
+    // ── Metrics ────────────────────────────────────────────────────
+    app.get("/api/metrics", async (_req, res) => {
+        try {
+            // Try real metrics module first, fall back to placeholder
+            let snapshot;
             try {
-                const message = JSON.parse(data.toString());
-                if (message.type === "subscribe" && message.channel) {
-                    client.subscriptions.add(message.channel);
-                    ws.send(JSON.stringify({ type: "subscribed", channel: message.channel }));
-                }
-                else if (message.type === "unsubscribe" && message.channel) {
-                    client.subscriptions.delete(message.channel);
-                    ws.send(JSON.stringify({ type: "unsubscribed", channel: message.channel }));
-                }
+                // Dynamic import — module may not exist yet (built in parallel)
+                const metricsPath = "../metrics/metrics.js";
+                const metricsModule = await import(metricsPath);
+                snapshot = await metricsModule.collectMetrics(system, startTime);
             }
             catch {
-                ws.send(JSON.stringify({ type: "error", error: "Invalid message format" }));
-            }
-        });
-        ws.on("close", () => {
-            wsClients.delete(client);
-        });
-    });
-    // ─────────────────────────────────────────────────────────────────
-    // Event Store Listeners for Real-time Updates
-    // ─────────────────────────────────────────────────────────────────
-    // Listen for agent changes
-    eventStore.onAgentChange((agentId, agent) => {
-        if (!agent)
-            return;
-        const update = {
-            type: "agent_update",
-            action: agent.state === "stopped" ? "stopped" : "started",
-            agent: agentToSummary(agent),
-        };
-        broadcastToChannel("agents", update);
-    });
-    // Listen for task changes
-    eventStore.onTaskChange((taskId, task) => {
-        if (!task)
-            return;
-        const update = {
-            type: "task_update",
-            action: task.status === "completed" ? "completed" : "status_change",
-            task: taskToSummary(task),
-        };
-        broadcastToChannel("tasks", update);
-    });
-    // Listen for conversation changes (if available)
-    if (eventStore.onConversationChange) {
-        eventStore.onConversationChange((conversationId, conversation) => {
-            if (!conversation)
-                return;
-            const update = {
-                type: "conversation_update",
-                conversation: conversationToSummary(conversation),
-            };
-            broadcastToChannel("conversations", update);
-            broadcastToChannel(`conversation:${conversationId}`, update);
-        });
-    }
-    // Listen for turn changes (if available)
-    if (eventStore.onTurnChange) {
-        eventStore.onTurnChange((conversationId, turn) => {
-            const update = {
-                type: "turn_added",
-                conversation_id: conversationId,
-                turn: turnToSummary(turn),
-            };
-            broadcastToChannel(`conversation:${conversationId}`, update);
-        });
-    }
-    // ─────────────────────────────────────────────────────────────────
-    // Server Lifecycle
-    // ─────────────────────────────────────────────────────────────────
-    function getStatus() {
-        const agents = agentManager.list();
-        const tasks = taskManager.list();
-        return {
-            initialized: state.initialized,
-            head_manager_id: state.headManagerId,
-            agents: {
-                total: agents.length,
-                running: agents.filter((a) => a.state === "running").length,
-                stopped: agents.filter((a) => a.state === "stopped").length,
-            },
-            tasks: {
-                total: tasks.length,
-                pending: tasks.filter((t) => t.status === "pending").length,
-                in_progress: tasks.filter((t) => t.status === "in_progress").length,
-                completed: tasks.filter((t) => t.status === "completed").length,
-                failed: tasks.filter((t) => t.status === "failed").length,
-            },
-            uptime: state.startedAt ? Date.now() - state.startedAt : 0,
-            started_at: state.startedAt,
-        };
-    }
-    async function start() {
-        return new Promise((resolve) => {
-            server.listen(port, host, () => {
-                resolve();
-            });
-        });
-    }
-    /**
-     * Helper function to create a delay promise
-     */
-    function sleep(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
-    }
-    /**
-     * Get all in-flight prompt promises
-     */
-    function getInFlightPrompts() {
-        return Array.from(state.inFlightPrompts.values());
-    }
-    async function stop(options) {
-        // Prevent concurrent shutdown calls
-        if (state.isShuttingDown) {
-            return;
-        }
-        state.isShuttingDown = true;
-        const gracePeriod = options?.force ? 0 : shutdownGracePeriodMs;
-        // 1. Stop accepting new connections
-        server.close();
-        // 2. Wait grace period for in-flight work
-        if (gracePeriod > 0) {
-            const inFlight = getInFlightPrompts();
-            if (inFlight.length > 0) {
-                await Promise.race([
-                    Promise.all(inFlight),
-                    sleep(gracePeriod),
-                ]);
+                snapshot = await collectMetricsPlaceholder(system, startTime);
             }
+            res.json(snapshot);
         }
-        // 3. Close WebSocket connections with 1001 "going away"
-        for (const client of wsClients) {
-            if (client.ws.readyState === WebSocket.OPEN) {
-                client.ws.close(1001, "Server shutting down");
-            }
+        catch (err) {
+            res.status(500).json({ error: err.message ?? "Internal server error" });
         }
-        wsClients.clear();
-        // 4. Terminate running agents
-        await agentManager.close();
-        // 5-6. Persist and close event store
-        await eventStore.persist();
-        await eventStore.close();
-    }
-    /**
-     * Register signal handlers for graceful shutdown.
-     * Should be called after server.start() in production.
-     */
-    function registerSignalHandlers() {
-        let shutdownInProgress = false;
-        const handleSignal = async (signal) => {
-            if (shutdownInProgress) {
-                // Force exit on second signal
-                process.exit(1);
-            }
-            shutdownInProgress = true;
-            console.log(`\nReceived ${signal}, shutting down gracefully...`);
-            try {
-                await stop();
-                console.log("Server shutdown complete.");
-                process.exit(0);
-            }
-            catch (error) {
-                console.error("Error during shutdown:", error);
-                process.exit(1);
-            }
-        };
-        process.on("SIGINT", () => handleSignal("SIGINT"));
-        process.on("SIGTERM", () => handleSignal("SIGTERM"));
-    }
-    return {
-        app,
-        server,
-        wss,
-        start,
-        stop,
-        getStatus,
-        registerSignalHandlers,
-    };
-}
-// ─────────────────────────────────────────────────────────────────
-// Shared Server Mode (createAPIApp + setupAPIWebSocket)
-// ─────────────────────────────────────────────────────────────────
-/**
- * Create Express app with API routes for use with an external HTTP server.
- *
- * Use this when you want to share an HTTP server with other services.
- *
- * @param services - Shared services (EventStore, AgentManager, etc.)
- * @param config - Configuration options
- * @returns Express app
- */
-export function createAPIApp(services, config = {}) {
-    const { cors = true, serverToken } = config;
-    const { agentManager, taskManager, messageRouter } = services;
-    // Create shared state
-    const state = createAPISharedState();
-    // Create Express app
-    const app = express();
-    // Store state on app for access by setupAPIWebSocket
-    app.__apiState = state;
-    app.__apiServices = services;
-    // Middleware
-    app.use(express.json());
-    if (cors) {
-        app.use((_req, res, next) => {
-            res.header("Access-Control-Allow-Origin", "*");
-            res.header("Access-Control-Allow-Headers", "Content-Type, Authorization");
-            res.header("Access-Control-Allow-Methods", "GET, POST, DELETE");
-            next();
-        });
-    }
-    // Bearer token auth middleware (skip /health)
-    if (serverToken) {
-        app.use((req, res, next) => {
-            if (req.path === "/health")
-                return next();
-            const authHeader = req.headers.authorization;
-            const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : undefined;
-            if (!token || !secureCompare(token, serverToken)) {
-                const error = { error: "Unauthorized", code: "AUTH_REQUIRED" };
-                res.status(401).json(error);
-                return;
-            }
-            next();
-        });
-    }
-    // ─────────────────────────────────────────────────────────────────
-    // Helper Functions
-    // ─────────────────────────────────────────────────────────────────
-    function agentToSummary(agent) {
-        return {
-            id: agent.id,
-            session_id: agent.session_id,
-            task: agent.task ?? "No task",
-            state: agent.state,
-            parent: agent.parent,
-            children_count: agentManager.getChildren(agent.id).length,
-            created_at: agent.created_at,
-        };
-    }
-    function agentToDetail(agent) {
-        return {
-            ...agentToSummary(agent),
-            lineage: agent.lineage,
-            task_id: agent.task_id,
-            config: agent.config,
-            started_at: agent.started_at,
-            stopped_at: agent.stopped_at,
-            stop_reason: agent.stop_reason,
-        };
-    }
-    function taskToSummary(task) {
-        return {
-            id: task.id,
-            description: task.description,
-            status: task.status,
-            assigned_agent: task.assigned_agent,
-            created_at: task.created_at,
-        };
-    }
-    function taskToDetail(task) {
-        return {
-            ...taskToSummary(task),
-            parent_task: task.parent_task,
-            subtasks: task.subtasks ?? [],
-            created_by: task.created_by,
-            inputs: task.inputs,
-            outputs: task.outputs,
-            artifacts: task.artifacts,
-            started_at: task.started_at,
-            completed_at: task.completed_at,
-        };
-    }
-    function eventToSummary(event) {
-        let summary = "";
-        switch (event.type) {
-            case "spawn":
-                summary = `Agent ${event.payload.agent_id} spawned`;
-                break;
-            case "stop":
-                summary = `Agent terminated: ${event.payload.reason}`;
-                break;
-            case "status":
-                summary = `${event.payload.status_type}: ${event.payload.summary}`;
-                break;
-            case "message":
-                summary = `Message: ${String(event.payload.content).substring(0, 50)}...`;
-                break;
-            case "task":
-                summary = `Task ${event.payload.action}: ${event.payload.task_id}`;
-                break;
-            default:
-                summary = `${event.type} event`;
-        }
-        return {
-            id: event.id,
-            type: event.type,
-            timestamp: event.timestamp,
-            source_agent_id: event.source.agent_id,
-            target_agent_id: event.target?.agent_id,
-            summary,
-        };
-    }
-    function buildHierarchyNode(agent) {
-        const children = agentManager.getChildren(agent.id);
-        return {
-            agent_id: agent.id,
-            task: agent.task ?? "No task",
-            state: agent.state,
-            children: children.map(buildHierarchyNode),
-        };
-    }
-    function sendError(res, status, code, message) {
-        const error = { error: message, code };
-        res.status(status).json(error);
-    }
-    // ─────────────────────────────────────────────────────────────────
-    // API Routes
-    // ─────────────────────────────────────────────────────────────────
-    // POST /api/init - Initialize the system
-    app.post("/api/init", async (req, res) => {
+    });
+    app.get("/api/metrics/agents", (_req, res) => {
         try {
-            if (state.initialized) {
-                return sendError(res, 400, "ALREADY_INITIALIZED", "System already initialized");
-            }
-            const body = req.body;
-            const cwd = body.cwd ?? process.cwd();
-            const headManager = await agentManager.getOrCreateHeadManager({
-                cwd,
-                systemPrompt: body.system_prompt,
-                permissionMode: body.permission_mode,
+            const agents = system.agentStore.listAgents();
+            const running = agents.filter((a) => a.state === "running").length;
+            const stopped = agents.filter((a) => a.state === "stopped").length;
+            const failed = agents.filter((a) => a.state === "failed").length;
+            res.json({
+                total: agents.length,
+                running,
+                stopped,
+                failed,
             });
-            state.initialized = true;
-            state.headManagerId = headManager.id;
-            state.startedAt = Date.now();
-            // Create session conversation for mail tracking
-            if (services.mailService && services.conversationMap) {
-                try {
-                    const { conversationId } = services.mailService.createConversation({
-                        type: "session",
-                        subject: "User session",
-                        createdBy: "user",
-                    });
-                    services.mailService.joinConversation({
-                        conversationId,
-                        participantId: headManager.id,
-                        role: "worker",
-                    });
-                    services.conversationMap.setSessionConversation(headManager.id, conversationId);
-                }
-                catch {
-                    // Never fail init due to mail errors
-                }
-            }
-            const response = {
-                success: true,
-                head_manager_id: headManager.id,
-                session_id: headManager.session_id,
-            };
-            res.json(response);
         }
-        catch (error) {
-            sendError(res, 500, "INIT_FAILED", `Failed to initialize: ${error}`);
+        catch (err) {
+            res.status(500).json({ error: err.message ?? "Internal server error" });
         }
     });
-    // GET /api/status - Get system status
-    app.get("/api/status", (_req, res) => {
-        const agents = agentManager.list();
-        const tasks = taskManager.list();
-        const status = {
-            initialized: state.initialized,
-            head_manager_id: state.headManagerId,
-            agents: {
-                total: agents.length,
-                running: agents.filter((a) => a.state === "running").length,
-                stopped: agents.filter((a) => a.state === "stopped").length,
-            },
-            tasks: {
-                total: tasks.length,
-                pending: tasks.filter((t) => t.status === "pending").length,
-                in_progress: tasks.filter((t) => t.status === "in_progress").length,
-                completed: tasks.filter((t) => t.status === "completed").length,
-                failed: tasks.filter((t) => t.status === "failed").length,
-            },
-            uptime: state.startedAt ? Date.now() - state.startedAt : 0,
-            started_at: state.startedAt,
-        };
-        res.json(status);
-    });
-    // POST /api/conversation/message - Send message to head manager
-    app.post("/api/conversation/message", async (req, res) => {
-        // Reject new messages during shutdown
-        if (state.isShuttingDown) {
-            return sendError(res, 503, "SHUTTING_DOWN", "Server is shutting down");
-        }
-        const promptId = `prompt_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    app.get("/api/metrics/tasks", async (_req, res) => {
         try {
-            if (!state.initialized || !state.headManagerId) {
-                return sendError(res, 400, "NOT_INITIALIZED", "System not initialized");
-            }
-            const body = req.body;
-            if (!body.message) {
-                return sendError(res, 400, "MISSING_MESSAGE", "Message is required");
-            }
-            // Add user message to history
-            state.conversationHistory.push({
-                role: "user",
-                content: body.message,
-                timestamp: Date.now(),
-            });
-            // Record user turn in session conversation
-            if (services.mailService && services.conversationMap && state.headManagerId) {
-                try {
-                    const sessionConvId = services.conversationMap.getSessionConversation(state.headManagerId);
-                    if (sessionConvId) {
-                        services.mailService.recordTurn({
-                            conversationId: sessionConvId,
-                            participant: "user",
-                            contentType: "text",
-                            content: body.message,
-                        });
-                    }
-                }
-                catch {
-                    // Never fail message handling due to mail errors
-                }
-            }
-            // Broadcast to conversation channel
-            state.broadcast("conversation", {
-                type: "message",
-                data: {
-                    role: "user",
-                    content: body.message,
-                    timestamp: Date.now(),
-                },
-            });
-            // Track this prompt as in-flight
-            let resolvePrompt;
-            const promptPromise = new Promise((resolve) => {
-                resolvePrompt = resolve;
-            });
-            state.inFlightPrompts.set(promptId, promptPromise);
-            // Send to head manager and collect response
-            let responseContent = "";
-            try {
-                for await (const update of agentManager.prompt(state.headManagerId, body.message)) {
-                    if ("sessionUpdate" in update && update.sessionUpdate === "agent_message_chunk") {
-                        const chunk = update;
-                        if (chunk.content.type === "text" && chunk.content.text) {
-                            responseContent += chunk.content.text;
-                        }
-                    }
-                }
-            }
-            finally {
-                // Mark prompt as complete
-                resolvePrompt();
-                state.inFlightPrompts.delete(promptId);
-            }
-            // Add assistant response to history
-            state.conversationHistory.push({
-                role: "assistant",
-                content: responseContent,
-                agent_id: state.headManagerId,
-                timestamp: Date.now(),
-            });
-            // Record assistant turn in session conversation
-            if (services.mailService && services.conversationMap && state.headManagerId) {
-                try {
-                    const sessionConvId = services.conversationMap.getSessionConversation(state.headManagerId);
-                    if (sessionConvId) {
-                        services.mailService.recordTurn({
-                            conversationId: sessionConvId,
-                            participant: state.headManagerId,
-                            contentType: "text",
-                            content: responseContent,
-                        });
-                    }
-                }
-                catch {
-                    // Never fail message handling due to mail errors
-                }
-            }
-            // Broadcast response
-            state.broadcast("conversation", {
-                type: "message",
-                data: {
-                    role: "assistant",
-                    content: responseContent,
-                    agent_id: state.headManagerId,
-                    timestamp: Date.now(),
-                },
-            });
+            const tasks = await system.tasksAdapter.listTasks();
             res.json({
-                content: responseContent,
-                agent_id: state.headManagerId,
-                message_id: `msg_${Date.now()}`,
+                total: tasks.length,
+                open: tasks.filter((t) => t.status === "open").length,
+                in_progress: tasks.filter((t) => t.status === "in_progress").length,
+                closed: tasks.filter((t) => t.status === "closed").length,
             });
         }
-        catch (error) {
-            // Ensure we clean up the in-flight prompt on error
-            state.inFlightPrompts.delete(promptId);
-            sendError(res, 500, "MESSAGE_FAILED", `Failed to process message: ${error}`);
-        }
-    });
-    // GET /api/conversation/history - Get conversation history
-    app.get("/api/conversation/history", (req, res) => {
-        const limit = parseInt(req.query.limit) || 50;
-        const offset = parseInt(req.query.offset) || 0;
-        const history = state.conversationHistory.slice(offset, offset + limit);
-        const response = {
-            history,
-            total: state.conversationHistory.length,
-        };
-        res.json(response);
-    });
-    // GET /api/agents - List agents
-    app.get("/api/agents", (req, res) => {
-        const params = req.query;
-        let agents = agentManager.list();
-        // Apply filters
-        if (params.state) {
-            agents = agents.filter((a) => a.state === params.state);
-        }
-        if (params.parent !== undefined) {
-            const parentValue = params.parent === "null" ? null : params.parent;
-            agents = agents.filter((a) => a.parent === parentValue);
-        }
-        const total = agents.length;
-        // Apply pagination
-        const offset = params.offset ?? 0;
-        const limit = params.limit ?? 50;
-        agents = agents.slice(offset, offset + limit);
-        const response = {
-            agents: agents.map(agentToSummary),
-            total,
-        };
-        res.json(response);
-    });
-    // GET /api/agents/:id - Get agent details
-    app.get("/api/agents/:id", (req, res) => {
-        const id = req.params.id;
-        const agent = agentManager.get(id);
-        if (!agent) {
-            return sendError(res, 404, "AGENT_NOT_FOUND", `Agent not found: ${id}`);
-        }
-        res.json(agentToDetail(agent));
-    });
-    // GET /api/agents/:id/hierarchy - Get agent hierarchy
-    app.get("/api/agents/:id/hierarchy", (req, res) => {
-        const id = req.params.id;
-        const agent = agentManager.get(id);
-        if (!agent) {
-            return sendError(res, 404, "AGENT_NOT_FOUND", `Agent not found: ${id}`);
-        }
-        const hierarchy = agentManager.getHierarchy(id);
-        if (!hierarchy) {
-            return sendError(res, 500, "HIERARCHY_ERROR", "Failed to build hierarchy");
+        catch (err) {
+            res.status(500).json({ error: err.message ?? "Internal server error" });
         }
-        const response = {
-            tree: buildHierarchyNode(agent),
-            depth: hierarchy.depth,
-            total_agents: hierarchy.totalAgents,
-        };
-        res.json(response);
     });
-    // GET /api/tasks - List tasks
-    app.get("/api/tasks", (req, res) => {
-        const params = req.query;
-        let tasks = taskManager.list();
-        // Apply filters
-        if (params.status) {
-            tasks = tasks.filter((t) => t.status === params.status);
-        }
-        if (params.assigned_agent) {
-            tasks = tasks.filter((t) => t.assigned_agent === params.assigned_agent);
-        }
-        const total = tasks.length;
-        // Apply pagination
-        const offset = params.offset ?? 0;
-        const limit = params.limit ?? 50;
-        tasks = tasks.slice(offset, offset + limit);
-        const response = {
-            tasks: tasks.map(taskToSummary),
-            total,
-        };
-        res.json(response);
-    });
-    // GET /api/tasks/:id - Get task details
-    app.get("/api/tasks/:id", (req, res) => {
-        const id = req.params.id;
-        const task = taskManager.get(id);
-        if (!task) {
-            return sendError(res, 404, "TASK_NOT_FOUND", `Task not found: ${id}`);
-        }
-        res.json(taskToDetail(task));
-    });
-    // GET /api/events - List events with filters
-    app.get("/api/events", (req, res) => {
-        const params = req.query;
-        const { eventStore } = services;
-        const events = eventStore.query({
-            type: params.type,
-            source_agent_id: params.source_agent_id,
-            target_agent_id: params.target_agent_id,
-            after: params.after,
-            before: params.before,
-            limit: (params.limit ?? 50) + 1, // Get one extra to check has_more
-        });
-        const limit = params.limit ?? 50;
-        const hasMore = events.length > limit;
-        const resultEvents = hasMore ? events.slice(0, limit) : events;
-        const response = {
-            events: resultEvents.map(eventToSummary),
-            total: resultEvents.length,
-            has_more: hasMore,
-        };
-        res.json(response);
-    });
-    // POST /api/agents/:id/inject - Inject context into agent session
-    app.post("/api/agents/:id/inject", async (req, res) => {
-        const id = req.params.id;
-        const body = req.body;
-        // Validate content
-        if (!body.content) {
-            return sendError(res, 400, "MISSING_CONTENT", "Content is required");
-        }
-        // Check agent exists
-        const agent = agentManager.get(id);
-        if (!agent) {
-            return sendError(res, 404, "AGENT_NOT_FOUND", `Agent not found: ${id}`);
-        }
-        // Create injection deps
-        const injectionDeps = {
-            getSession(agentId) {
-                const session = agentManager.getSession(agentId);
-                if (!session)
-                    return null;
-                return {
-                    inject: async (content) => session.inject(content),
-                    supportsInject: () => session.supportsInject(),
-                    checkInjectSupport: async () => session.supportsInject(),
-                    interruptWith: (content) => session.interruptWith(content),
-                };
-            },
-            isPrompting(agentId) {
-                return agentManager.isPrompting(agentId);
-            },
-            async sendMessage(_fromAgentId, toAgentId, content, priority) {
-                await messageRouter.sendToAddress({
-                    from: "__human__",
-                    to: { agent: toAgentId },
-                    content,
-                    options: { priority },
-                });
-            },
-        };
+    // ── Teams ──────────────────────────────────────────────────────
+    app.get("/api/teams", (_req, res) => {
         try {
-            const result = await injectContext(injectionDeps, id, body.content, {
-                urgent: body.urgent,
-                allowInterrupt: true,
-                source: { type: "human" },
-                reason: body.reason,
-            });
-            const response = {
-                success: result.success,
-                method: result.method,
-                error: result.error,
-                note: result.note,
-            };
-            if (result.success) {
-                res.json(response);
-            }
-            else {
-                res.status(500).json(response);
+            const agents = system.agentStore.listAgents();
+            const teamMap = new Map();
+            for (const agent of agents) {
+                const teamName = agent.team ?? "default";
+                let entry = teamMap.get(teamName);
+                if (!entry) {
+                    entry = { name: teamName, agentCount: 0, roles: new Set() };
+                    teamMap.set(teamName, entry);
+                }
+                entry.agentCount++;
+                entry.roles.add(agent.role);
             }
+            const teams = Array.from(teamMap.values()).map((t) => ({
+                name: t.name,
+                agentCount: t.agentCount,
+                roles: Array.from(t.roles),
+            }));
+            res.json({ teams });
         }
-        catch (error) {
-            sendError(res, 500, "INJECTION_FAILED", `Failed to inject context: ${error}`);
+        catch (err) {
+            res.status(500).json({ error: err.message ?? "Internal server error" });
         }
     });
-    // Register conversation API routes (if mail service available)
-    registerConversationRoutes(app, services, sendError);
-    return app;
-}
-/**
- * Set up API WebSocket handling on an existing WebSocketServer.
- *
- * Use this when you want to share an HTTP server with other services.
- * The WebSocketServer should be created with `noServer: true`.
- *
- * @param wss - WebSocketServer instance (noServer mode)
- * @param services - Shared services (EventStore, AgentManager, etc.)
- * @returns Handler for managing connections
- */
-export function setupAPIWebSocket(wss, services, app) {
-    const { eventStore, agentManager } = services;
-    // Get shared state from app if provided, otherwise create new
-    const state = app && app.__apiState
-        ? app.__apiState
-        : createAPISharedState();
-    const { wsClients, broadcast } = state;
-    // Helper functions for event listeners
-    function agentToSummary(agent) {
-        return {
-            id: agent.id,
-            session_id: agent.session_id,
-            task: agent.task ?? "No task",
-            state: agent.state,
-            parent: agent.parent,
-            children_count: agentManager.getChildren(agent.id).length,
-            created_at: agent.created_at,
-        };
-    }
-    function taskToSummary(task) {
-        return {
-            id: task.id,
-            description: task.description,
-            status: task.status,
-            assigned_agent: task.assigned_agent,
-            created_at: task.created_at,
-        };
-    }
-    // Handle WebSocket connections
-    wss.on("connection", (ws) => {
-        const client = {
-            ws,
-            subscriptions: new Set(),
-        };
-        wsClients.add(client);
-        ws.on("message", (data) => {
-            try {
-                const message = JSON.parse(data.toString());
-                if (message.type === "subscribe" && message.channel) {
-                    client.subscriptions.add(message.channel);
-                    ws.send(JSON.stringify({ type: "subscribed", channel: message.channel }));
-                }
-                else if (message.type === "unsubscribe" && message.channel) {
-                    client.subscriptions.delete(message.channel);
-                    ws.send(JSON.stringify({ type: "unsubscribed", channel: message.channel }));
-                }
-            }
-            catch {
-                ws.send(JSON.stringify({ type: "error", error: "Invalid message format" }));
-            }
-        });
-        ws.on("close", () => {
-            wsClients.delete(client);
-        });
-    });
-    // Listen for agent changes
-    eventStore.onAgentChange((agentId, agent) => {
-        if (!agent)
-            return;
-        const update = {
-            type: "agent_update",
-            action: agent.state === "stopped" ? "stopped" : "started",
-            agent: agentToSummary(agent),
-        };
-        broadcast("agents", update);
-    });
-    // Listen for task changes
-    eventStore.onTaskChange((taskId, task) => {
-        if (!task)
-            return;
-        const update = {
-            type: "task_update",
-            action: task.status === "completed" ? "completed" : "status_change",
-            task: taskToSummary(task),
-        };
-        broadcast("tasks", update);
-    });
-    // Listen for conversation changes (if available)
-    if (eventStore.onConversationChange) {
-        eventStore.onConversationChange((conversationId, conversation) => {
-            if (!conversation)
-                return;
-            const update = {
-                type: "conversation_update",
-                conversation: conversationToSummary(conversation),
-            };
-            broadcast("conversations", update);
-            broadcast(`conversation:${conversationId}`, update);
-        });
-    }
-    // Listen for turn changes (if available)
-    if (eventStore.onTurnChange) {
-        eventStore.onTurnChange((conversationId, turn) => {
-            const update = {
-                type: "turn_added",
-                conversation_id: conversationId,
-                turn: turnToSummary(turn),
-            };
-            broadcast(`conversation:${conversationId}`, update);
-        });
-    }
+    // ── Server Lifecycle ───────────────────────────────────────────
+    let server = null;
     return {
-        getConnectionCount() {
-            return wsClients.size;
+        app,
+        async start() {
+            return new Promise((resolve) => {
+                server = app.listen(port, host, () => {
+                    console.log(`[api] Listening on ${host}:${port}`);
+                    resolve();
+                });
+            });
         },
-        closeAll() {
-            console.error(`[api-ws] Closing ${wsClients.size} connections...`);
-            for (const client of wsClients) {
-                if (client.ws.readyState === WebSocket.OPEN) {
-                    client.ws.close(1001, "Server shutting down");
-                }
+        async stop() {
+            if (server) {
+                return new Promise((resolve) => {
+                    server.close(() => {
+                        server = null;
+                        resolve();
+                    });
+                });
             }
-            wsClients.clear();
         },
     };
 }