macro-agent 0.0.11 → 0.0.13

package/src/mcp/tools/done.ts

@@ -65,10 +65,16 @@ export interface DoneToolDeps {
     /** Get merge queue for coordinating worker merges */
     getMergeQueue?(): AllHandlerDeps["mergeQueue"];
   };
+  /** Optional RoleRegistry for capability-based done() checks */
+  roleRegistry?: import("../../roles/types.js").RoleRegistry;
   /** Optional MailService for recording completion turns */
   mailService?: import("../../mail/mail-service.js").MailService;
   /** Optional ConversationMap for agent-to-conversation lookup */
   conversationMap?: import("../../mail/conversation-map.js").ConversationMap;
+  /** Optional integration strategy (from team config) */
+  integrationStrategy?: import("../../workspace/strategies/types.js").IntegrationStrategy;
+  /** Optional task mode from team config */
+  taskMode?: "push" | "pull";
 }
 
 // =============================================================================
@@ -76,11 +82,15 @@ export interface DoneToolDeps {
 // =============================================================================
 
 /**
- * Check if an agent has the lifecycle.done capability
+ * Check if an agent has the lifecycle.done capability.
+ *
+ * Uses RoleRegistry for capability resolution, supporting both built-in
+ * roles and team-defined roles that extend them.
  */
 export function hasLifecycleDoneCapability(
   eventStore: EventStore,
-  agentId: string
+  agentId: string,
+  roleRegistry?: import("../../roles/types.js").RoleRegistry
 ): { hasCapability: boolean; role: string } {
   // Get the agent to find their role
   const agent = eventStore.getAgent(agentId);
@@ -88,13 +98,15 @@ export function hasLifecycleDoneCapability(
     return { hasCapability: false, role: "unknown" };
   }
 
-  // Get the agent's role (set at spawn time) or default to "worker"
-  // In the future, this should query the RoleRegistry for full capability lookup
   const role = agent.role ?? "worker";
 
-  // Check if the role has lifecycle.done capability
-  // For now, we check based on known roles that have this capability
-  // In the future, this should query the RoleRegistry
+  // Use RoleRegistry for capability lookup when available
+  if (roleRegistry) {
+    const hasCapability = roleRegistry.hasCapability(role, "lifecycle.done");
+    return { hasCapability, role };
+  }
+
+  // Fallback: check base role via prefix match against known built-in roles
   const rolesWithDoneCapability = new Set([
     "worker",
     "worker.resolver",
@@ -102,7 +114,6 @@ export function hasLifecycleDoneCapability(
     "monitor",
   ]);
 
-  // Check exact match or prefix match
   const hasCapability =
     rolesWithDoneCapability.has(role) ||
     rolesWithDoneCapability.has(role.split(".")[0]);
@@ -162,7 +173,7 @@ export function createDoneHandler(context: ToolContext, deps: DoneToolDeps) {
     details?: Record<string, unknown>;
     task_id?: string;
   }): Promise<DoneResult> => {
-    const { eventStore, agentManager, messageRouter, taskManager, workspaceManager, mailService, conversationMap } = deps;
+    const { eventStore, agentManager, messageRouter, taskManager, workspaceManager, roleRegistry, mailService, conversationMap } = deps;
 
     // ─────────────────────────────────────────────────────────────────────────
     // Step 1: Check capability
@@ -170,7 +181,8 @@ export function createDoneHandler(context: ToolContext, deps: DoneToolDeps) {
 
     const { hasCapability, role } = hasLifecycleDoneCapability(
       eventStore,
-      context.agent_id
+      context.agent_id,
+      roleRegistry
     );
 
     if (!hasCapability) {
@@ -286,6 +298,8 @@ export function createDoneHandler(context: ToolContext, deps: DoneToolDeps) {
       getWorkspacePath: workspaceManager
         ? (agentId: string) => workspaceManager.getWorkspace(agentId)?.path
         : undefined,
+      integrationStrategy: deps.integrationStrategy,
+      taskMode: deps.taskMode,
     };
 
     const handlerResult = await dispatchDone(

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 =