macro-agent 0.0.10 → 0.0.12

package/src/api/server.ts

@@ -42,6 +42,14 @@ import type {
   WSTaskUpdate,
   InjectContextRequest,
   InjectContextResponse,
+  MailConversationSummary,
+  MailConversationDetail,
+  MailConversationListResponse,
+  MailTurnSummary,
+  MailTurnListResponse,
+  MailConversationQueryParams,
+  WSTurnAdded,
+  WSConversationUpdate,
 } from "./types.js";
 import {
   injectContext,
@@ -72,6 +80,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;
 }
 
 // ─────────────────────────────────────────────────────────────────
@@ -197,6 +209,140 @@ export function createAPISharedState(): APISharedState {
   };
 }
 
+// ─────────────────────────────────────────────────────────────────
+// Conversation API Routes (shared between standalone and app mode)
+// ─────────────────────────────────────────────────────────────────
+
+import type { Conversation, ConversationTurn } from "../store/types/conversations.js";
+
+function conversationToSummary(conv: Conversation): MailConversationSummary {
+  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: Conversation): MailConversationDetail {
+  return {
+    ...conversationToSummary(conv),
+    closed_at: conv.closedAt || undefined,
+    closed_by: conv.closedBy || undefined,
+    close_reason: conv.closeReason || undefined,
+  };
+}
+
+function turnToSummary(turn: ConversationTurn): MailTurnSummary {
+  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: Express,
+  services: Pick<APIServices, "mailService">,
+  sendError: (res: Response, status: number, code: string, message: string) => void
+): void {
+  if (!services.mailService) return;
+  const { mailService } = services;
+
+  // GET /api/conversations - List conversations
+  app.get("/api/conversations", (req: Request, res: Response) => {
+    const params = req.query as Record<string, string | undefined>;
+    let conversations = mailService.listConversations({
+      type: params.type as any,
+      status: params.status as any,
+    });
+
+    const total = conversations.length;
+    const offset = parseInt(params.offset as string) || 0;
+    const limit = parseInt(params.limit as string) || 50;
+    conversations = conversations.slice(offset, offset + limit);
+
+    const response: MailConversationListResponse = {
+      conversations: conversations.map(conversationToSummary),
+      total,
+    };
+    res.json(response);
+  });
+
+  // GET /api/conversations/:id - Get conversation detail
+  app.get("/api/conversations/:id", (req: Request, res: Response) => {
+    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: Request, res: Response) => {
+    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 as string) || 50;
+    const offset = parseInt(req.query.offset as string) || 0;
+    const paged = turns.slice(offset, offset + limit);
+
+    const response: MailTurnListResponse = {
+      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: Request, res: Response) => {
+    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 as { reason?: string };
+    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: Request, res: Response) => {
+    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
 // ─────────────────────────────────────────────────────────────────
@@ -366,6 +512,25 @@ export function createAPIServer(
       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: InitResponse = {
         success: true,
         head_manager_id: headManager.id,
@@ -384,6 +549,116 @@ export function createAPIServer(
     res.json(status);
   });
 
+  // GET /api/team - Get active team info
+  app.get("/api/team", (_req: Request, res: Response) => {
+    // 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 as Record<string, unknown>;
+    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: Request, res: Response) => {
+    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 as string | undefined;
+      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: Request, res: Response) => {
+    const allAgents = eventStore.listAgents();
+    const active = allAgents.filter(
+      (a) => a.state === "running" || a.state === "spawning"
+    );
+    const byRole: Record<string, number> = {};
+    const byState: Record<string, number> = {};
+    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: Request, res: Response) => {
+    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: Array<{ timestamp: number; agentId: string; type: string; summary: string }> = [];
+    const byType: Record<string, number> = {};
+
+    for (const e of statusEvents) {
+      if (e.payload?.status_type !== "failed") continue;
+      const agentId = (e.source as { agent_id?: string })?.agent_id ?? "unknown";
+      const summary = (e.payload?.summary as string) ?? "Unknown error";
+      const errorType = ((e.payload?.details as Record<string, unknown>)?.signal as string) ?? "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: Request, res: Response) => {
     // Reject new messages during shutdown
@@ -410,6 +685,23 @@ export function createAPIServer(
         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",
@@ -452,6 +744,23 @@ export function createAPIServer(
         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",
@@ -686,6 +995,9 @@ export function createAPIServer(
     }
   });
 
+  // Register conversation API routes (if mail service available)
+  registerConversationRoutes(app, services, sendError);
+
   // ─────────────────────────────────────────────────────────────────
   // HTTP Server
   // ─────────────────────────────────────────────────────────────────
@@ -756,6 +1068,34 @@ export function createAPIServer(
     broadcastToChannel("tasks", update);
   });
 
+  // Listen for conversation changes (if available)
+  if (eventStore.onConversationChange) {
+    eventStore.onConversationChange((conversationId, conversation) => {
+      if (!conversation) return;
+
+      const update: WSConversationUpdate = {
+        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: WSTurnAdded = {
+        type: "turn_added",
+        conversation_id: conversationId,
+        turn: turnToSummary(turn),
+      };
+
+      broadcastToChannel(`conversation:${conversationId}`, update);
+    });
+  }
+
   // ─────────────────────────────────────────────────────────────────
   // Server Lifecycle
   // ─────────────────────────────────────────────────────────────────
@@ -900,7 +1240,7 @@ export function createAPIServer(
  * @returns Express app
  */
 export function createAPIApp(
-  services: Pick<APIServices, "eventStore" | "agentManager" | "taskManager" | "messageRouter">,
+  services: Pick<APIServices, "eventStore" | "agentManager" | "taskManager" | "messageRouter"> & Pick<Partial<APIServices>, "mailService" | "conversationMap">,
   config: { cors?: boolean } = {}
 ): Express {
   const { cors = true } = config;
@@ -1051,6 +1391,25 @@ export function createAPIApp(
       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: InitResponse = {
         success: true,
         head_manager_id: headManager.id,
@@ -1116,6 +1475,23 @@ export function createAPIApp(
         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",
@@ -1158,6 +1534,23 @@ export function createAPIApp(
         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",
@@ -1393,6 +1786,9 @@ export function createAPIApp(
     }
   });
 
+  // Register conversation API routes (if mail service available)
+  registerConversationRoutes(app, services, sendError);
+
   return app;
 }
 
@@ -1498,6 +1894,34 @@ export function setupAPIWebSocket(
     broadcast("tasks", update);
   });
 
+  // Listen for conversation changes (if available)
+  if (eventStore.onConversationChange) {
+    eventStore.onConversationChange((conversationId, conversation) => {
+      if (!conversation) return;
+
+      const update: WSConversationUpdate = {
+        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: WSTurnAdded = {
+        type: "turn_added",
+        conversation_id: conversationId,
+        turn: turnToSummary(turn),
+      };
+
+      broadcast(`conversation:${conversationId}`, update);
+    });
+  }
+
   return {
     getConnectionCount(): number {
       return wsClients.size;

package/src/api/types.ts

@@ -182,7 +182,9 @@ export type WSMessageType =
   | "task_update"
   | "message"
   | "status"
-  | "error";
+  | "error"
+  | "conversation_update"
+  | "turn_added";
 
 export interface WSMessage {
   type: WSMessageType;
@@ -277,6 +279,67 @@ export interface InjectContextResponse {
   note?: string;
 }
 
+// ─────────────────────────────────────────────────────────────────
+// Mail Conversations
+// ─────────────────────────────────────────────────────────────────
+
+export interface MailConversationSummary {
+  id: string;
+  type: string;
+  status: string;
+  subject: string;
+  created_by: string;
+  created_at: Timestamp;
+  updated_at: Timestamp;
+  participant_count: number;
+  parent_conversation_id?: string;
+}
+
+export interface MailConversationDetail extends MailConversationSummary {
+  closed_at?: Timestamp;
+  closed_by?: string;
+  close_reason?: string;
+}
+
+export interface MailConversationListResponse {
+  conversations: MailConversationSummary[];
+  total: number;
+}
+
+export interface MailTurnSummary {
+  id: string;
+  conversation_id: string;
+  participant: string;
+  content_type: string;
+  content: unknown;
+  timestamp: Timestamp;
+  source_type?: string;
+  source_message_id?: string;
+}
+
+export interface MailTurnListResponse {
+  turns: MailTurnSummary[];
+  total: number;
+}
+
+export interface MailConversationQueryParams {
+  type?: string;
+  status?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface WSTurnAdded {
+  type: "turn_added";
+  conversation_id: string;
+  turn: MailTurnSummary;
+}
+
+export interface WSConversationUpdate {
+  type: "conversation_update";
+  conversation: MailConversationSummary;
+}
+
 // ─────────────────────────────────────────────────────────────────
 // Error Response
 // ─────────────────────────────────────────────────────────────────

package/src/cli/acp.ts

@@ -81,6 +81,8 @@ export interface ACPServerOptions {
   port?: number;
   /** Host for server (default: localhost) */
   host?: string;
+  /** Instance ID to reuse an existing event store (omit for new instance) */
+  instanceId?: string;
 }
 
 /**
@@ -108,6 +110,9 @@ export function parseArgs(argv?: string[]): ACPServerOptions {
     } else if (args[i] === "--host" && args[i + 1]) {
       options.host = args[i + 1];
       i++;
+    } else if (args[i] === "--instance-id" && args[i + 1]) {
+      options.instanceId = args[i + 1];
+      i++;
     }
   }
 
@@ -154,7 +159,10 @@ async function main() {
   const defaultCwd = options.cwd ?? process.cwd();
 
   // Initialize services
-  const eventStore = await createEventStore({ inMemory: false });
+  const eventStore = await createEventStore({
+    inMemory: false,
+    instanceId: options.instanceId,
+  });
 
   // We need to create agentManager first (with a placeholder router),
   // then wire the sessionChecker/wakeHandler into the router,