macro-agent 0.0.10 → 0.0.12

package/src/mcp/tools/list_claimable_tasks.ts

@@ -0,0 +1,93 @@
+/**
+ * list_claimable_tasks() MCP Tool
+ *
+ * Lists tasks available for claiming. Allows agents to preview
+ * what's in the task pool before claiming.
+ *
+ * @module mcp/tools/list_claimable_tasks
+ */
+
+import { z } from "zod";
+import type { TaskBackend, ClaimFilter, ExtendedTask } from "../../task/backend/types.js";
+import type { ToolContext } from "../types.js";
+
+// =============================================================================
+// Schema
+// =============================================================================
+
+export const ListClaimableTasksSchema = {
+  tags: z
+    .array(z.string())
+    .optional()
+    .describe("Only list tasks with at least one matching tag"),
+  root_tasks_only: z
+    .boolean()
+    .optional()
+    .describe("Only list root tasks (no parent)"),
+  limit: z
+    .number()
+    .optional()
+    .describe("Maximum number of tasks to return (default: 20)"),
+};
+
+// =============================================================================
+// Handler
+// =============================================================================
+
+export interface ListClaimableTasksDeps {
+  taskBackend: TaskBackend;
+}
+
+export function createListClaimableTasksHandler(
+  _context: ToolContext,
+  deps: ListClaimableTasksDeps
+) {
+  return async (args: {
+    tags?: string[];
+    root_tasks_only?: boolean;
+    limit?: number;
+  }): Promise<{
+    tasks: ExtendedTask[];
+    count: number;
+    message: string;
+  }> => {
+    if (!deps.taskBackend.listClaimable) {
+      return {
+        tasks: [],
+        count: 0,
+        message: "Task backend does not support listClaimable operations",
+      };
+    }
+
+    const filter: ClaimFilter = {};
+    if (args.tags) filter.tags = args.tags;
+    if (args.root_tasks_only) filter.rootTasksOnly = args.root_tasks_only;
+
+    let tasks = await deps.taskBackend.listClaimable(filter);
+
+    const limit = args.limit ?? 20;
+    if (tasks.length > limit) {
+      tasks = tasks.slice(0, limit);
+    }
+
+    return {
+      tasks,
+      count: tasks.length,
+      message:
+        tasks.length > 0
+          ? `Found ${tasks.length} claimable task(s)`
+          : "No claimable tasks available",
+    };
+  };
+}
+
+// =============================================================================
+// Tool Info
+// =============================================================================
+
+export const LIST_CLAIMABLE_TASKS_TOOL_INFO = {
+  name: "list_claimable_tasks",
+  description:
+    "List tasks available for claiming. Shows pending, unblocked, unassigned tasks. Requires task.claim capability.",
+  schema: ListClaimableTasksSchema,
+};

package/src/mcp/tools/unclaim_task.ts

@@ -0,0 +1,71 @@
+/**
+ * unclaim_task() MCP Tool
+ *
+ * Allows agents with `task.claim` capability to release a claimed task
+ * back to the pending pool.
+ *
+ * @module mcp/tools/unclaim_task
+ */
+
+import { z } from "zod";
+import type { TaskBackend } from "../../task/backend/types.js";
+import type { ToolContext } from "../types.js";
+
+// =============================================================================
+// Schema
+// =============================================================================
+
+export const UnclaimTaskSchema = {
+  task_id: z.string().describe("ID of the task to unclaim"),
+};
+
+// =============================================================================
+// Handler
+// =============================================================================
+
+export interface UnclaimTaskDeps {
+  taskBackend: TaskBackend;
+}
+
+export function createUnclaimTaskHandler(
+  _context: ToolContext,
+  deps: UnclaimTaskDeps
+) {
+  return async (args: {
+    task_id: string;
+  }): Promise<{
+    success: boolean;
+    message: string;
+  }> => {
+    if (!deps.taskBackend.unclaim) {
+      return {
+        success: false,
+        message: "Task backend does not support unclaim operations",
+      };
+    }
+
+    try {
+      await deps.taskBackend.unclaim(args.task_id);
+      return {
+        success: true,
+        message: `Task ${args.task_id} unclaimed and returned to pending pool`,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        message: `Failed to unclaim task: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  };
+}
+
+// =============================================================================
+// Tool Info
+// =============================================================================
+
+export const UNCLAIM_TASK_TOOL_INFO = {
+  name: "unclaim_task",
+  description:
+    "Release a claimed task back to the pending pool so another agent can pick it up. Requires task.claim capability.",
+  schema: UnclaimTaskSchema,
+};

package/src/metrics/index.ts

@@ -0,0 +1,9 @@
+export {
+  getThroughputMetrics,
+  getUtilizationMetrics,
+  getErrorMetrics,
+  type ThroughputMetrics,
+  type UtilizationMetrics,
+  type ErrorMetrics,
+  type ErrorEntry,
+} from "./metrics.js";

package/src/metrics/metrics.ts

@@ -0,0 +1,280 @@
+/**
+ * Metrics Module
+ *
+ * Computes throughput, utilization, and error metrics from EventStore data.
+ * No new events needed — aggregates existing spawn, terminate, task, and
+ * status events.
+ *
+ * @module metrics/metrics
+ */
+
+import type { EventStore } from "../store/event-store.js";
+import type { Agent } from "../store/types/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ThroughputMetrics {
+  /** Tasks completed in the time window */
+  tasksCompleted: number;
+
+  /** 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
+// =============================================================================
+
+/**
+ * Compute throughput metrics for a time window.
+ *
+ * @param eventStore - EventStore to query
+ * @param windowMs - Time window in milliseconds (default: 5 minutes)
+ */
+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;
+
+  return {
+    tasksCompleted,
+    tasksFailed,
+    tasksCreated,
+    avgCompletionTimeMs:
+      completedWithTime > 0
+        ? Math.round(totalCompletionTimeMs / completedWithTime)
+        : null,
+    completedPerMinute: Math.round(completedPerMinute * 100) / 100,
+    windowStart,
+    windowEnd: now,
+  };
+}
+
+/**
+ * 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;
+
+  // Current agents
+  const allAgents = eventStore.listAgents();
+  const activeAgents = allAgents.filter(
+    (a: Agent) => a.state === "running" || a.state === "spawning"
+  );
+
+  // Agents by role
+  const agentsByRole: Record<string, number> = {};
+  for (const agent of activeAgents) {
+    const role = agent.role ?? "unknown";
+    agentsByRole[role] = (agentsByRole[role] ?? 0) + 1;
+  }
+
+  // Agents by state
+  const agentsByState: Record<string, number> = {};
+  for (const agent of allAgents) {
+    agentsByState[agent.state] = (agentsByState[agent.state] ?? 0) + 1;
+  }
+
+  // Count spawn and terminate events in window
+  const spawnEvents = eventStore.query({
+    type: "spawn",
+    after: windowStart,
+  });
+  const terminateEvents = eventStore.query({
+    type: "terminate",
+    after: windowStart,
+  });
+
+  return {
+    activeAgents: activeAgents.length,
+    totalSpawned: spawnEvents.length,
+    totalStopped: terminateEvents.length,
+    agentsByRole,
+    agentsByState,
+  };
+}
+
+/**
+ * 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;
+
+  // Query status events that indicate errors
+  const statusEvents = eventStore.query({
+    type: "status",
+    after: windowStart,
+  });
+
+  const errors: ErrorEntry[] = [];
+  const errorsByType: Record<string, number> = {};
+
+  for (const event of statusEvents) {
+    const statusType = event.payload?.status_type as string | undefined;
+    if (statusType !== "failed") continue;
+
+    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";
+
+    errors.push({
+      timestamp: event.timestamp,
+      agentId,
+      type: errorType,
+      summary,
+    });
+
+    errorsByType[errorType] = (errorsByType[errorType] ?? 0) + 1;
+  }
+
+  // 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`,
+    });
+
+    errorsByType["task_failed"] = (errorsByType["task_failed"] ?? 0) + 1;
+  }
+
+  // Sort by timestamp descending and limit
+  errors.sort((a, b) => b.timestamp - a.timestamp);
+  const recentErrors = errors.slice(0, maxRecent);
+
+  return {
+    totalErrors: errors.length,
+    errorsByType,
+    recentErrors,
+  };
+}

package/src/roles/capabilities.ts

@@ -48,6 +48,7 @@ export const TASK_CAPABILITIES = {
   ASSIGN: "task.assign" as const,
   UPDATE: "task.update" as const,
   CLOSE: "task.close" as const,
+  CLAIM: "task.claim" as const,
 };
 
 /** Execution capabilities */
@@ -101,6 +102,7 @@ export const ALL_CAPABILITIES: Set<Capability> = new Set([
   TASK_CAPABILITIES.ASSIGN,
   TASK_CAPABILITIES.UPDATE,
   TASK_CAPABILITIES.CLOSE,
+  TASK_CAPABILITIES.CLAIM,
   // Exec
   EXEC_CAPABILITIES.COMMAND,
   EXEC_CAPABILITIES.BUILD,
@@ -159,6 +161,7 @@ export const CAPABILITY_TOOL_MAP: CapabilityToolMap = {
   [TASK_CAPABILITIES.ASSIGN]: ["sudocode_upsert_issue", "assign_task"],
   [TASK_CAPABILITIES.UPDATE]: ["sudocode_upsert_issue", "update_task"],
   [TASK_CAPABILITIES.CLOSE]: ["sudocode_upsert_issue", "close_task"],
+  [TASK_CAPABILITIES.CLAIM]: ["claim_task", "unclaim_task", "list_claimable_tasks"],
 
   // Execution operations
   [EXEC_CAPABILITIES.COMMAND]: ["bash"],

package/src/roles/types.ts

@@ -41,7 +41,8 @@ export type TaskCapability =
   | "task.create"
   | "task.assign"
   | "task.update"
-  | "task.close";
+  | "task.close"
+  | "task.claim";
 
 /** Execution capabilities */
 export type ExecCapability =

package/src/router/README.md

@@ -0,0 +1,120 @@
+# Router Module
+
+Core internal message routing for macro-agent. Handles all agent-to-agent communication.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     MessageRouter                            │
+│                                                              │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
+│  │ Legacy API  │  │ Address API │  │   Status/Events     │  │
+│  │ send()      │  │ sendTo      │  │   emitStatus()      │  │
+│  │ sendMessage │  │ Address()   │  │   subscribe()       │  │
+│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
+│         │                │                   │               │
+│         └────────────────┼───────────────────┘               │
+│                          ▼                                   │
+│                   ┌─────────────┐                            │
+│                   │ EventStore  │                            │
+│                   └─────────────┘                            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Components
+
+### MessageRouter (`message-router.ts`)
+
+The central routing authority. Two APIs:
+
+**Legacy Channel-based** (`send`, `sendMessage`):
+```typescript
+router.send(from, { agent_id: targetId }, content);
+router.send(from, { task_id: taskId }, content);
+router.send(from, { topic: "updates" }, content);
+```
+
+**MAP Address-based** (`sendToAddress`):
+```typescript
+router.sendToAddress({
+  from: agentId,
+  to: { agent: targetId },
+  content: "Hello",
+  priority: "high",
+});
+```
+
+### Channels (`channels.ts`, `types.ts`)
+
+Channel types for legacy routing:
+- `agent_id` - Direct to agent
+- `task_id` - To task's assigned agent
+- `topic` - Pub/sub topic
+- `lineage` - To ancestors
+- `subtree` - To descendants
+- `broadcast` - System-wide
+
+### Role Resolution (`role-resolver.ts`)
+
+Resolves role-based addresses to agent IDs:
+
+```typescript
+const workers = resolveRoleTarget(agentSource, {
+  role: "worker",
+  scope: "project-1",  // Filter by scope membership
+  coordinatorId: "coord-1",  // Filter by subtree
+});
+```
+
+### Wake Logic (`wake.ts`)
+
+Priority-based wake decisions:
+- `urgent` → Interrupt current activity
+- `high` → Inject into session (fallback: interrupt)
+- `normal` → Wake if idle
+- `low` → Queue only
+
+### Broadcast (`broadcast.ts`)
+
+Fan-out message delivery:
+- `all` - All running agents
+- `coordinators` - Agents with coordinator role
+- `workers` - Agents with worker role
+- `monitors` - Agents with monitor role
+
+## Usage
+
+```typescript
+import { createMessageRouter } from "./router/message-router.js";
+
+const router = createMessageRouter({
+  eventStore,
+  agentManager,
+  federationHandler,  // Optional: for cross-system routing
+});
+
+// Send to agent
+await router.sendToAddress({
+  from: senderId,
+  to: { agent: recipientId },
+  content: "Hello",
+});
+
+// Send to role
+await router.sendToAddress({
+  from: senderId,
+  to: { role: "worker" },
+  content: "Task update",
+});
+```
+
+## Relationship to Other Routers
+
+| Router | Purpose | Entry Point |
+|--------|---------|-------------|
+| **MessageRouter** | Internal agent↔agent | AgentManager, MCP tools |
+| **MAPAdapter** | External MAP clients | WebSocket connections |
+| **TriggerRouter** | External events | Webhooks, cron |
+
+MessageRouter is the **core authority** - other routers delegate to it.