macro-agent 0.1.1 → 0.1.3

package/src/metrics/__tests__/metrics.test.ts

@@ -0,0 +1,205 @@
+import { describe, it, expect, vi } from "vitest";
+import { collectMetrics } from "../metrics.js";
+import type { MacroAgentSystemV2 } from "../../boot-v2.js";
+import type { AgentRecord } from "../../agent/agent-store.js";
+
+// ─────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────
+
+function makeAgent(
+  overrides: Partial<AgentRecord> & { id: string; role: string; state: string }
+): AgentRecord {
+  return {
+    parent_id: null,
+    lineage: [],
+    scope: "default",
+    task: "test",
+    cwd: "/tmp",
+    capabilities: [],
+    created_at: Date.now(),
+    ...overrides,
+  } as AgentRecord;
+}
+
+function createMockSystem(
+  overrides: {
+    agents?: AgentRecord[];
+    unhealthy?: Array<{ agentId: string; lastSeen: number; pid: number }>;
+    tasksConnected?: boolean;
+    tasks?: Array<{ id: string; status: string }>;
+    readyTasks?: Array<{ id: string; status: string }>;
+    agentsWithEvents?: string[];
+    cronJobs?: unknown[];
+  } = {}
+): MacroAgentSystemV2 {
+  const {
+    agents = [],
+    unhealthy = [],
+    tasksConnected = false,
+    tasks = [],
+    readyTasks = [],
+    agentsWithEvents = [],
+    cronJobs = [],
+  } = overrides;
+
+  return {
+    agentManager: {} as any,
+    agentStore: {
+      listAgents: vi.fn().mockReturnValue(agents),
+    } as any,
+    inboxAdapter: {} as any,
+    tasksAdapter: {
+      connected: tasksConnected,
+      listTasks: vi.fn().mockResolvedValue(tasks),
+      queryReady: vi.fn().mockResolvedValue(readyTasks),
+    } as any,
+    triggerSystem: {
+      queue: {
+        getAgentsWithEvents: vi.fn().mockReturnValue(agentsWithEvents),
+      },
+      cronService: {
+        list: vi.fn().mockResolvedValue(cronJobs),
+      },
+    } as any,
+    controlServer: {
+      getUnhealthyAgents: vi.fn().mockReturnValue(unhealthy),
+    } as any,
+    roleRegistry: {} as any,
+    controlSocketPath: "/tmp/control.sock",
+    shutdown: vi.fn(),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Tests
+// ─────────────────────────────────────────────────────────────────
+
+describe("collectMetrics", () => {
+  const START_TIME = Date.now() - 10_000; // 10s ago
+
+  it("returns correct agent counts by state", async () => {
+    const system = createMockSystem({
+      agents: [
+        makeAgent({ id: "a1", role: "worker", state: "running" }),
+        makeAgent({ id: "a2", role: "worker", state: "running" }),
+        makeAgent({ id: "a3", role: "worker", state: "running" }),
+        makeAgent({ id: "a4", role: "coordinator", state: "stopped" }),
+        makeAgent({ id: "a5", role: "coordinator", state: "stopped" }),
+      ],
+    });
+
+    const snapshot = await collectMetrics(system, START_TIME);
+
+    expect(snapshot.agents.total).toBe(5);
+    expect(snapshot.agents.byState).toEqual({
+      running: 3,
+      stopped: 2,
+    });
+  });
+
+  it("returns correct agent counts by role", async () => {
+    const system = createMockSystem({
+      agents: [
+        makeAgent({ id: "a1", role: "worker", state: "running" }),
+        makeAgent({ id: "a2", role: "worker", state: "running" }),
+        makeAgent({ id: "a3", role: "coordinator", state: "running" }),
+      ],
+    });
+
+    const snapshot = await collectMetrics(system, START_TIME);
+
+    expect(snapshot.agents.byRole).toEqual({
+      worker: 2,
+      coordinator: 1,
+    });
+  });
+
+  it("returns correct agent counts by team", async () => {
+    const system = createMockSystem({
+      agents: [
+        makeAgent({ id: "a1", role: "worker", state: "running", team: "alpha" }),
+        makeAgent({ id: "a2", role: "worker", state: "running", team: "alpha" }),
+        makeAgent({ id: "a3", role: "worker", state: "running", team: "beta" }),
+        makeAgent({ id: "a4", role: "coordinator", state: "running" }), // no team
+      ],
+    });
+
+    const snapshot = await collectMetrics(system, START_TIME);
+
+    expect(snapshot.agents.byTeam).toEqual({
+      alpha: 2,
+      beta: 1,
+    });
+  });
+
+  it("returns unhealthy count from control server", async () => {
+    const system = createMockSystem({
+      agents: [
+        makeAgent({ id: "a1", role: "worker", state: "running" }),
+      ],
+      unhealthy: [
+        { agentId: "a1", lastSeen: Date.now() - 120_000, pid: 1234 },
+        { agentId: "a2", lastSeen: Date.now() - 90_000, pid: 5678 },
+      ],
+    });
+
+    const snapshot = await collectMetrics(system, START_TIME);
+
+    expect(snapshot.agents.unhealthy).toBe(2);
+  });
+
+  it("returns task metrics when opentasks is available", async () => {
+    const system = createMockSystem({
+      tasksConnected: true,
+      tasks: [
+        { id: "t1", status: "open" },
+        { id: "t2", status: "open" },
+        { id: "t3", status: "in_progress" },
+        { id: "t4", status: "blocked" },
+        { id: "t5", status: "closed" },
+      ],
+      readyTasks: [
+        { id: "t1", status: "open" },
+        { id: "t2", status: "open" },
+      ],
+    });
+
+    const snapshot = await collectMetrics(system, START_TIME);
+
+    expect(snapshot.tasks).not.toBeNull();
+    expect(snapshot.tasks!.byStatus).toEqual({
+      open: 2,
+      in_progress: 1,
+      blocked: 1,
+      closed: 1,
+    });
+    expect(snapshot.tasks!.ready).toBe(2);
+    expect(snapshot.tasks!.blocked).toBe(1);
+  });
+
+  it("returns tasks: null when opentasks is unavailable", async () => {
+    const system = createMockSystem({
+      tasksConnected: false,
+    });
+
+    const snapshot = await collectMetrics(system, START_TIME);
+
+    expect(snapshot.tasks).toBeNull();
+  });
+
+  it("returns system uptime and queue depth", async () => {
+    const system = createMockSystem({
+      agentsWithEvents: ["a1", "a2", "a3"],
+      cronJobs: [{}, {}, {}], // 3 cron jobs
+    });
+
+    const snapshot = await collectMetrics(system, START_TIME);
+
+    // Uptime should be approximately 10_000ms (with some tolerance)
+    expect(snapshot.system.uptime).toBeGreaterThanOrEqual(9_900);
+    expect(snapshot.system.uptime).toBeLessThan(15_000);
+    expect(snapshot.system.triggerQueueDepth).toBe(3);
+    expect(snapshot.system.cronJobCount).toBe(3);
+  });
+});

package/src/metrics/index.ts

@@ -1,9 +1,13 @@
-export {
-  getThroughputMetrics,
-  getUtilizationMetrics,
-  getErrorMetrics,
-  type ThroughputMetrics,
-  type UtilizationMetrics,
-  type ErrorMetrics,
-  type ErrorEntry,
-} from "./metrics.js";
+/**
+ * Metrics module — observability for macro-agent.
+ *
+ * @module metrics
+ */
+
+export { collectMetrics } from "./metrics.js";
+export type {
+  AgentMetrics,
+  TaskMetrics,
+  SystemMetrics,
+  MetricsSnapshot,
+} from "./types.js";

package/src/metrics/metrics.ts

@@ -1,280 +1,151 @@
 /**
- * Metrics Module
+ * Metrics collection for macro-agent.
  *
- * Computes throughput, utilization, and error metrics from EventStore data.
- * No new events needed — aggregates existing spawn, terminate, task, and
- * status events.
+ * Single entry point: `collectMetrics()` gathers agent, task, and
+ * system metrics into a point-in-time snapshot.
  *
  * @module metrics/metrics
  */
 
-import type { EventStore } from "../store/event-store.js";
-import type { Agent } from "../store/types/index.js";
+import type { MacroAgentSystemV2 } from "../boot-v2.js";
+import type {
+  AgentMetrics,
+  TaskMetrics,
+  SystemMetrics,
+  MetricsSnapshot,
+} from "./types.js";
 
-// =============================================================================
-// Types
-// =============================================================================
+// ─────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────
 
-export interface ThroughputMetrics {
-  /** Tasks completed in the time window */
-  tasksCompleted: number;
+/** Threshold for considering an agent unhealthy (ms). */
+const UNHEALTHY_THRESHOLD_MS = 60_000;
 
-  /** Tasks failed in the time window */
-  tasksFailed: number;
-
-  /** Total tasks created in the time window */
-  tasksCreated: number;
-
-  /** Average completion time in ms (completed tasks only) */
-  avgCompletionTimeMs: number | null;
-
-  /** Tasks per minute (completed) */
-  completedPerMinute: number;
-
-  /** Time window start */
-  windowStart: number;
-
-  /** Time window end */
-  windowEnd: number;
-}
-
-export interface UtilizationMetrics {
-  /** Currently running agents */
-  activeAgents: number;
-
-  /** Total agents spawned in the time window */
-  totalSpawned: number;
-
-  /** Total agents stopped in the time window */
-  totalStopped: number;
-
-  /** Agents by role */
-  agentsByRole: Record<string, number>;
-
-  /** Agents by state */
-  agentsByState: Record<string, number>;
-}
-
-export interface ErrorMetrics {
-  /** Total errors in the time window */
-  totalErrors: number;
-
-  /** Errors by type */
-  errorsByType: Record<string, number>;
-
-  /** Recent errors (last N) */
-  recentErrors: ErrorEntry[];
-}
-
-export interface ErrorEntry {
-  /** Timestamp */
-  timestamp: number;
-
-  /** Agent ID */
-  agentId: string;
-
-  /** Error type/category */
-  type: string;
-
-  /** Error summary */
-  summary: string;
-}
-
-// =============================================================================
-// Implementation
-// =============================================================================
+// ─────────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────────
 
 /**
- * Compute throughput metrics for a time window.
+ * Collect a point-in-time metrics snapshot from the running system.
  *
- * @param eventStore - EventStore to query
- * @param windowMs - Time window in milliseconds (default: 5 minutes)
+ * @param system - The booted MacroAgentSystemV2 instance.
+ * @param startTime - `Date.now()` value captured at boot, used for uptime.
  */
-export function getThroughputMetrics(
-  eventStore: EventStore,
-  windowMs: number = 5 * 60 * 1000
-): ThroughputMetrics {
-  const now = Date.now();
-  const windowStart = now - windowMs;
-
-  const taskEvents = eventStore.query({
-    type: "task",
-    after: windowStart,
-  });
-
-  let tasksCompleted = 0;
-  let tasksFailed = 0;
-  let tasksCreated = 0;
-  let totalCompletionTimeMs = 0;
-  let completedWithTime = 0;
-
-  for (const event of taskEvents) {
-    const action = event.payload?.action as string | undefined;
-
-    if (action === "created") {
-      tasksCreated++;
-    } else if (action === "completed") {
-      tasksCompleted++;
-
-      // Try to compute completion time
-      const taskId = event.payload?.task_id as string | undefined;
-      if (taskId) {
-        const task = eventStore.getTask(taskId);
-        if (task?.created_at && task?.completed_at) {
-          totalCompletionTimeMs += task.completed_at - task.created_at;
-          completedWithTime++;
-        }
-      }
-    } else if (action === "failed") {
-      tasksFailed++;
-    }
-  }
-
-  const windowMinutes = windowMs / 60000;
-  const completedPerMinute =
-    windowMinutes > 0 ? tasksCompleted / windowMinutes : 0;
+export async function collectMetrics(
+  system: MacroAgentSystemV2,
+  startTime: number
+): Promise<MetricsSnapshot> {
+  const [agents, tasks, systemMetrics] = await Promise.all([
+    collectAgentMetrics(system),
+    collectTaskMetrics(system),
+    collectSystemMetrics(system, startTime),
+  ]);
 
   return {
-    tasksCompleted,
-    tasksFailed,
-    tasksCreated,
-    avgCompletionTimeMs:
-      completedWithTime > 0
-        ? Math.round(totalCompletionTimeMs / completedWithTime)
-        : null,
-    completedPerMinute: Math.round(completedPerMinute * 100) / 100,
-    windowStart,
-    windowEnd: now,
+    timestamp: new Date().toISOString(),
+    agents,
+    tasks,
+    system: systemMetrics,
   };
 }
 
-/**
- * Compute utilization metrics (current snapshot + window).
- *
- * @param eventStore - EventStore to query
- * @param windowMs - Time window for spawn/stop counts (default: 5 minutes)
- */
-export function getUtilizationMetrics(
-  eventStore: EventStore,
-  windowMs: number = 5 * 60 * 1000
-): UtilizationMetrics {
-  const now = Date.now();
-  const windowStart = now - windowMs;
+// ─────────────────────────────────────────────────────────────────
+// Agent Metrics
+// ─────────────────────────────────────────────────────────────────
 
-  // Current agents
-  const allAgents = eventStore.listAgents();
-  const activeAgents = allAgents.filter(
-    (a: Agent) => a.state === "running" || a.state === "spawning"
-  );
+async function collectAgentMetrics(
+  system: MacroAgentSystemV2
+): Promise<AgentMetrics> {
+  const agents = system.agentStore.listAgents();
 
-  // Agents by role
-  const agentsByRole: Record<string, number> = {};
-  for (const agent of activeAgents) {
-    const role = agent.role ?? "unknown";
-    agentsByRole[role] = (agentsByRole[role] ?? 0) + 1;
-  }
+  const byState: Record<string, number> = {};
+  const byRole: Record<string, number> = {};
+  const byTeam: Record<string, number> = {};
 
-  // Agents by state
-  const agentsByState: Record<string, number> = {};
-  for (const agent of allAgents) {
-    agentsByState[agent.state] = (agentsByState[agent.state] ?? 0) + 1;
+  for (const agent of agents) {
+    // Count by state
+    byState[agent.state] = (byState[agent.state] ?? 0) + 1;
+
+    // Count by role
+    byRole[agent.role] = (byRole[agent.role] ?? 0) + 1;
+
+    // Count by team (skip agents without a team)
+    if (agent.team) {
+      byTeam[agent.team] = (byTeam[agent.team] ?? 0) + 1;
+    }
   }
 
-  // Count spawn and terminate events in window
-  const spawnEvents = eventStore.query({
-    type: "spawn",
-    after: windowStart,
-  });
-  const terminateEvents = eventStore.query({
-    type: "stop",
-    after: windowStart,
-  });
+  const unhealthy =
+    system.controlServer.getUnhealthyAgents(UNHEALTHY_THRESHOLD_MS).length;
 
   return {
-    activeAgents: activeAgents.length,
-    totalSpawned: spawnEvents.length,
-    totalStopped: terminateEvents.length,
-    agentsByRole,
-    agentsByState,
+    total: agents.length,
+    byState,
+    byRole,
+    byTeam,
+    unhealthy,
   };
 }
 
-/**
- * Compute error metrics for a time window.
- *
- * @param eventStore - EventStore to query
- * @param windowMs - Time window in milliseconds (default: 30 minutes)
- * @param maxRecent - Maximum recent errors to return (default: 20)
- */
-export function getErrorMetrics(
-  eventStore: EventStore,
-  windowMs: number = 30 * 60 * 1000,
-  maxRecent: number = 20
-): ErrorMetrics {
-  const now = Date.now();
-  const windowStart = now - windowMs;
+// ─────────────────────────────────────────────────────────────────
+// Task Metrics
+// ─────────────────────────────────────────────────────────────────
 
-  // Query status events that indicate errors
-  const statusEvents = eventStore.query({
-    type: "status",
-    after: windowStart,
-  });
-
-  const errors: ErrorEntry[] = [];
-  const errorsByType: Record<string, number> = {};
+async function collectTaskMetrics(
+  system: MacroAgentSystemV2
+): Promise<TaskMetrics | null> {
+  // If the tasks adapter is not connected, return null
+  if (!system.tasksAdapter.connected) {
+    return null;
+  }
 
-  for (const event of statusEvents) {
-    const statusType = event.payload?.status_type as string | undefined;
-    if (statusType !== "failed") continue;
+  try {
+    const [allTasks, readyTasks] = await Promise.all([
+      system.tasksAdapter.listTasks(),
+      system.tasksAdapter.queryReady(),
+    ]);
 
-    const agentId =
-      (event.source as { agent_id?: string })?.agent_id ?? "unknown";
-    const summary =
-      (event.payload?.summary as string) ?? "Unknown error";
-    const errorType =
-      (event.payload?.details as Record<string, unknown>)?.signal as string ??
-      "agent_failed";
+    const byStatus: Record<string, number> = {};
+    let blocked = 0;
 
-    errors.push({
-      timestamp: event.timestamp,
-      agentId,
-      type: errorType,
-      summary,
-    });
+    for (const task of allTasks) {
+      byStatus[task.status] = (byStatus[task.status] ?? 0) + 1;
+      if (task.status === "blocked") {
+        blocked++;
+      }
+    }
 
-    errorsByType[errorType] = (errorsByType[errorType] ?? 0) + 1;
+    return {
+      byStatus,
+      ready: readyTasks.length,
+      blocked,
+    };
+  } catch {
+    // opentasks daemon may have disconnected — non-fatal
+    return null;
   }
+}
 
-  // Also count task failures
-  const taskEvents = eventStore.query({
-    type: "task",
-    after: windowStart,
-  });
-
-  for (const event of taskEvents) {
-    if (event.payload?.action !== "failed") continue;
-
-    const agentId =
-      (event.source as { agent_id?: string })?.agent_id ?? "unknown";
-    const taskId = (event.payload?.task_id as string) ?? "unknown";
-
-    errors.push({
-      timestamp: event.timestamp,
-      agentId,
-      type: "task_failed",
-      summary: `Task ${taskId} failed`,
-    });
+// ─────────────────────────────────────────────────────────────────
+// System Metrics
+// ─────────────────────────────────────────────────────────────────
 
-    errorsByType["task_failed"] = (errorsByType["task_failed"] ?? 0) + 1;
-  }
+async function collectSystemMetrics(
+  system: MacroAgentSystemV2,
+  startTime: number
+): Promise<SystemMetrics> {
+  const uptime = Date.now() - startTime;
+  const triggerQueueDepth =
+    system.triggerSystem.queue.getAgentsWithEvents().length;
 
-  // Sort by timestamp descending and limit
-  errors.sort((a, b) => b.timestamp - a.timestamp);
-  const recentErrors = errors.slice(0, maxRecent);
+  // CronService.list() returns all enabled jobs
+  const cronJobs = await system.triggerSystem.cronService.list();
+  const cronJobCount = cronJobs.length;
 
   return {
-    totalErrors: errors.length,
-    errorsByType,
-    recentErrors,
+    uptime,
+    triggerQueueDepth,
+    cronJobCount,
   };
 }

package/src/metrics/types.ts

@@ -0,0 +1,63 @@
+/**
+ * Metrics type definitions.
+ *
+ * @module metrics/types
+ */
+
+// ─────────────────────────────────────────────────────────────────
+// Agent Metrics
+// ─────────────────────────────────────────────────────────────────
+
+export interface AgentMetrics {
+  /** Total number of agents. */
+  total: number;
+  /** Count of agents by state (e.g., running, stopped). */
+  byState: Record<string, number>;
+  /** Count of agents by role (e.g., worker, coordinator). */
+  byRole: Record<string, number>;
+  /** Count of agents by team. */
+  byTeam: Record<string, number>;
+  /** Number of agents with stale MCP heartbeats. */
+  unhealthy: number;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Task Metrics
+// ─────────────────────────────────────────────────────────────────
+
+export interface TaskMetrics {
+  /** Count of tasks by status (open, in_progress, blocked, closed). */
+  byStatus: Record<string, number>;
+  /** Number of tasks ready to be worked on (no active blockers). */
+  ready: number;
+  /** Number of blocked tasks. */
+  blocked: number;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// System Metrics
+// ─────────────────────────────────────────────────────────────────
+
+export interface SystemMetrics {
+  /** Uptime in milliseconds since boot. */
+  uptime: number;
+  /** Number of agents with queued trigger events. */
+  triggerQueueDepth: number;
+  /** Number of registered cron jobs. */
+  cronJobCount: number;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Snapshot
+// ─────────────────────────────────────────────────────────────────
+
+export interface MetricsSnapshot {
+  /** ISO timestamp of when this snapshot was collected. */
+  timestamp: string;
+  /** Agent metrics. */
+  agents: AgentMetrics;
+  /** Task metrics, or null if opentasks is unavailable. */
+  tasks: TaskMetrics | null;
+  /** System-level metrics. */
+  system: SystemMetrics;
+}