macro-agent 0.0.10 → 0.0.12

package/dist/agent-detection/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * CLI Agent Auto-Detection Types
+ *
+ * Type definitions for detecting installed CLI coding agents
+ * and constructing headless invocation commands.
+ */
+/**
+ * Headless invocation configuration for a CLI agent.
+ */
+export interface HeadlessConfig {
+    /** Subcommand before prompt (e.g., "exec" for codex, "run" for goose) */
+    subcommand?: string;
+    /** Flag to pass the prompt. Empty string means prompt is positional. */
+    promptFlag: string;
+    /** Default flags always included in headless mode */
+    defaultFlags?: string[];
+}
+/**
+ * Definition of a known CLI coding agent.
+ * Describes how to detect and invoke the agent in headless mode.
+ */
+export interface CLIAgentDefinition {
+    /** Unique identifier (e.g., "claude-code", "codex") */
+    id: string;
+    /** Human-readable display name */
+    name: string;
+    /** Short description */
+    description: string;
+    /** The binary/command name to invoke */
+    binary: string;
+    /** Arguments to check version (typically ["--version"]) */
+    versionArgs: string[];
+    /** Headless invocation configuration */
+    headless: HeadlessConfig;
+    /** Flag for model selection (e.g., "--model") */
+    modelFlag?: string;
+    /** Flag for working directory (e.g., "--cwd", "--path") */
+    cwdFlag?: string;
+    /** Provider/vendor name */
+    vendor: string;
+}
+/**
+ * Result of detecting a single CLI agent on the system.
+ */
+export interface DetectedAgent {
+    /** Agent definition ID */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Whether the binary was found on PATH */
+    installed: boolean;
+    /** Parsed version string (e.g., "1.2.3") */
+    version?: string;
+    /** Absolute path to binary */
+    path?: string;
+    /** The full agent definition (for client display) */
+    definition: CLIAgentDefinition;
+    /** When detection was performed (epoch ms) */
+    detectedAt: number;
+}
+/**
+ * Result of a full detection scan across all known agents.
+ */
+export interface DetectionResult {
+    /** All agents (installed and not installed) */
+    agents: DetectedAgent[];
+    /** Number of agents scanned */
+    scanned: number;
+    /** Detection duration in milliseconds */
+    durationMs: number;
+    /** Whether detection is still in progress */
+    pending?: boolean;
+}
+/**
+ * Options for building a spawn command.
+ */
+export interface SpawnCommandOptions {
+    /** Model to use (passed via modelFlag) */
+    model?: string;
+    /** Working directory (passed via cwdFlag) */
+    cwd?: string;
+}
+/**
+ * Result of building a spawn command.
+ */
+export interface SpawnCommand {
+    /** The binary/command to execute */
+    command: string;
+    /** Arguments to pass to the command */
+    args: string[];
+}
+/**
+ * Configuration for the agent detection system.
+ */
+export interface AgentDetectionConfig {
+    /** Whether agent detection is enabled (default: true) */
+    enabled?: boolean;
+    /** Cache TTL in milliseconds (default: 60000) */
+    cacheTtlMs?: number;
+    /** Timeout for `which` calls in milliseconds (default: 5000) */
+    whichTimeoutMs?: number;
+    /** Timeout for version checks in milliseconds (default: 10000) */
+    versionTimeoutMs?: number;
+    /** Additional custom agent definitions to include */
+    additionalAgents?: CLIAgentDefinition[];
+    /** Agent IDs to exclude from detection */
+    disabledAgents?: string[];
+}
+/**
+ * Error codes for agent detection operations.
+ */
+export type AgentDetectionErrorCode = "UNKNOWN_AGENT" | "AGENT_NOT_INSTALLED" | "DETECTION_FAILED" | "DETECTION_TIMEOUT";
+/**
+ * Error thrown by agent detection operations.
+ */
+export declare class AgentDetectionError extends Error {
+    readonly code: AgentDetectionErrorCode;
+    readonly agentId?: string | undefined;
+    constructor(message: string, code: AgentDetectionErrorCode, agentId?: string | undefined);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agent-detection/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agent-detection/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;IAEnB,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IAEX,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IAEb,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IAEpB,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IAEf,2DAA2D;IAC3D,WAAW,EAAE,MAAM,EAAE,CAAC;IAEtB,wCAAwC;IACxC,QAAQ,EAAE,cAAc,CAAC;IAEzB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,0BAA0B;IAC1B,EAAE,EAAE,MAAM,CAAC;IAEX,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IAEb,2CAA2C;IAC3C,SAAS,EAAE,OAAO,CAAC;IAEnB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,qDAAqD;IACrD,UAAU,EAAE,kBAAkB,CAAC;IAE/B,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,MAAM,EAAE,aAAa,EAAE,CAAC;IAExB,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAEhB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IAEnB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAEhB,uCAAuC;IACvC,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAMD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAExC,0CAA0C;IAC1C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAMD;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAC/B,eAAe,GACf,qBAAqB,GACrB,kBAAkB,GAClB,mBAAmB,CAAC;AAExB;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAG1B,IAAI,EAAE,uBAAuB;aAC7B,OAAO,CAAC,EAAE,MAAM;gBAFhC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,uBAAuB,EAC7B,OAAO,CAAC,EAAE,MAAM,YAAA;CAKnC"}

package/dist/agent-detection/types.js

@@ -0,0 +1,20 @@
+/**
+ * CLI Agent Auto-Detection Types
+ *
+ * Type definitions for detecting installed CLI coding agents
+ * and constructing headless invocation commands.
+ */
+/**
+ * Error thrown by agent detection operations.
+ */
+export class AgentDetectionError extends Error {
+    code;
+    agentId;
+    constructor(message, code, agentId) {
+        super(message);
+        this.code = code;
+        this.agentId = agentId;
+        this.name = "AgentDetectionError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/agent-detection/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agent-detection/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsKH;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAG1B;IACA;IAHlB,YACE,OAAe,EACC,IAA6B,EAC7B,OAAgB;QAEhC,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAyB;QAC7B,YAAO,GAAP,OAAO,CAAS;QAGhC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF"}

package/dist/api/server.d.ts

@@ -30,6 +30,10 @@ export interface APIServices {
     agentManager: AgentManager;
     taskManager: TaskManager;
     messageRouter: MessageRouter;
+    /** Optional mail service for conversation tracking */
+    mailService?: import("../mail/mail-service.js").MailService;
+    /** Optional conversation map for agent-to-conversation tracking */
+    conversationMap?: import("../mail/conversation-map.js").ConversationMap;
 }
 export interface StopOptions {
     /** Force immediate shutdown, skipping grace period */
@@ -103,7 +107,7 @@ export declare function createAPIServer(services: APIServices, config?: APIServe
  * @param config - Configuration options
  * @returns Express app
  */
-export declare function createAPIApp(services: Pick<APIServices, "eventStore" | "agentManager" | "taskManager" | "messageRouter">, config?: {
+export declare function createAPIApp(services: Pick<APIServices, "eventStore" | "agentManager" | "taskManager" | "messageRouter"> & Pick<Partial<APIServices>, "mailService" | "conversationMap">, config?: {
     cors?: boolean;
 }): Express;
 /**

package/dist/api/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/api/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAgB,EAAE,OAAO,EAAmC,MAAM,SAAS,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAChD,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,OAAO,KAAK,EACV,YAAY,EAmBZ,SAAS,EAMV,MAAM,YAAY,CAAC;AAWpB,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,sBAAsB;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,kBAAkB;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf,sFAAsF;IACtF,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,UAAU,CAAC;IACvB,YAAY,EAAE,YAAY,CAAC;IAC3B,WAAW,EAAE,WAAW,CAAC;IACzB,aAAa,EAAE,aAAa,CAAC;CAC9B;AAMD,MAAM,WAAW,WAAW;IAC1B,sDAAsD;IACtD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,8BAA8B;IAC9B,GAAG,EAAE,OAAO,CAAC;IAEb,kBAAkB;IAClB,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;IAEpB,uBAAuB;IACvB,GAAG,EAAE,eAAe,CAAC;IAErB,uBAAuB;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;;;;OAOG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3C,yBAAyB;IACzB,SAAS,IAAI,YAAY,CAAC;IAE1B,qDAAqD;IACrD,sBAAsB,IAAI,IAAI,CAAC;CAChC;AA0BD,UAAU,QAAQ;IAChB,EAAE,EAAE,SAAS,CAAC;IACd,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,kBAAkB,IAAI,MAAM,CAAC;IAE7B,uCAAuC;IACvC,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB,EAAE,KAAK,CAAC;QACzB,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QAC3B,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC,CAAC;IACH,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5C,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;IACzB,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,KAAK,IAAI,CAAC;CAC1D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CAoBrD;AAMD,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,WAAW,EACrB,MAAM,GAAE,eAAoB,GAC3B,SAAS,CAwqBX;AAMD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,YAAY,GAAG,cAAc,GAAG,aAAa,GAAG,eAAe,CAAC,EAC5F,MAAM,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAC9B,OAAO,CA4eT;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,YAAY,GAAG,cAAc,GAAG,aAAa,CAAC,EAC1E,GAAG,CAAC,EAAE,OAAO,GACZ,mBAAmB,CAuGrB"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/api/server.ts"],"names":[],"mappings":"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"}

package/dist/api/server.js

@@ -33,6 +33,115 @@ export function createAPISharedState() {
         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,
+    };
+}
+function conversationToDetail(conv) {
+    return {
+        ...conversationToSummary(conv),
+        closed_at: conv.closedAt || undefined,
+        closed_by: conv.closedBy || undefined,
+        close_reason: conv.closeReason || undefined,
+    };
+}
+function turnToSummary(turn) {
+    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,
+    };
+}
+/**
+ * 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,
+        });
+        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}`);
+        }
+        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}`);
+        }
+        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}`);
+        }
+        const participants = mailService.listParticipants(req.params.id);
+        res.json({ participants, total: participants.length });
+    });
+}
 // ─────────────────────────────────────────────────────────────────
 // Create API Server
 // ─────────────────────────────────────────────────────────────────
@@ -177,6 +286,25 @@ export function createAPIServer(services, config = {}) {
             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,
@@ -193,6 +321,101 @@ export function createAPIServer(services, config = {}) {
         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
@@ -214,6 +437,23 @@ export function createAPIServer(services, config = {}) {
                 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",
@@ -253,6 +493,23 @@ export function createAPIServer(services, config = {}) {
                 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
             broadcastToChannel("conversation", {
                 type: "message",
@@ -450,6 +707,8 @@ export function createAPIServer(services, config = {}) {
             sendError(res, 500, "INJECTION_FAILED", `Failed to inject context: ${error}`);
         }
     });
+    // Register conversation API routes (if mail service available)
+    registerConversationRoutes(app, services, sendError);
     // ─────────────────────────────────────────────────────────────────
     // HTTP Server
     // ─────────────────────────────────────────────────────────────────
@@ -509,6 +768,30 @@ export function createAPIServer(services, config = {}) {
         };
         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
     // ─────────────────────────────────────────────────────────────────
@@ -762,6 +1045,25 @@ export function createAPIApp(services, config = {}) {
             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,
@@ -818,6 +1120,23 @@ export function createAPIApp(services, config = {}) {
                 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",
@@ -857,6 +1176,23 @@ export function createAPIApp(services, config = {}) {
                 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",
@@ -1055,6 +1391,8 @@ export function createAPIApp(services, config = {}) {
             sendError(res, 500, "INJECTION_FAILED", `Failed to inject context: ${error}`);
         }
     });
+    // Register conversation API routes (if mail service available)
+    registerConversationRoutes(app, services, sendError);
     return app;
 }
 /**
@@ -1144,6 +1482,30 @@ export function setupAPIWebSocket(wss, services, app) {
         };
         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);
+        });
+    }
     return {
         getConnectionCount() {
             return wsClients.size;