macro-agent 0.2.4 → 0.2.6

package/src/roles/builtin/index.ts

@@ -1,51 +0,0 @@
-/**
- * Built-in Role Exports
- *
- * All core roles defined by the framework.
- */
-
-export { WorkerRole, ResolverWorkerRole } from "./worker.js";
-export { IntegratorRole } from "./integrator.js";
-export { CoordinatorRole } from "./coordinator.js";
-export { MonitorRole } from "./monitor.js";
-export { GenericRole } from "./generic.js";
-
-import type { RoleDefinition } from "../types.js";
-import { WorkerRole, ResolverWorkerRole } from "./worker.js";
-import { IntegratorRole } from "./integrator.js";
-import { CoordinatorRole } from "./coordinator.js";
-import { MonitorRole } from "./monitor.js";
-import { GenericRole } from "./generic.js";
-
-/**
- * Map of all built-in roles by name
- */
-export const BUILTIN_ROLES: Map<string, RoleDefinition> = new Map([
-  [WorkerRole.name, WorkerRole],
-  [ResolverWorkerRole.name, ResolverWorkerRole],
-  [IntegratorRole.name, IntegratorRole],
-  [CoordinatorRole.name, CoordinatorRole],
-  [MonitorRole.name, MonitorRole],
-  [GenericRole.name, GenericRole],
-]);
-
-/**
- * Get a built-in role by name
- */
-export function getBuiltinRole(name: string): RoleDefinition | undefined {
-  return BUILTIN_ROLES.get(name);
-}
-
-/**
- * Check if a role name is a built-in role
- */
-export function isBuiltinRole(name: string): boolean {
-  return BUILTIN_ROLES.has(name);
-}
-
-/**
- * List all built-in role names
- */
-export function listBuiltinRoleNames(): string[] {
-  return Array.from(BUILTIN_ROLES.keys());
-}

package/src/roles/builtin/integrator.ts

@@ -1,62 +0,0 @@
-/**
- * Integrator Role Definition
- *
- * Handles merging worker branches into integration branch.
- * Persistent, spawns resolver workers on conflict.
- */
-
-import type { RoleDefinition } from "../types.js";
-import {
-  FILE_CAPABILITIES,
-  GIT_CAPABILITIES,
-  AGENT_CAPABILITIES,
-  LIFECYCLE_CAPABILITIES,
-  MSG_CAPABILITIES,
-  WORKSPACE_CAPABILITIES,
-} from "../capabilities.js";
-
-/**
- * Integrator Role
- *
- * Merge manager agent that:
- * - Processes merge queue from workers
- * - Merges worker branches into integration branch
- * - Spawns resolver workers on conflicts
- * - Notifies coordinator of merge results
- */
-export const IntegratorRole: RoleDefinition = {
-  name: "integrator",
-  displayName: "Integrator",
-  description:
-    "Handles merging worker branches into integration branch, conflict resolution",
-
-  capabilities: [
-    FILE_CAPABILITIES.READ,
-    FILE_CAPABILITIES.WRITE,
-    GIT_CAPABILITIES.COMMIT,
-    GIT_CAPABILITIES.MERGE,
-    GIT_CAPABILITIES.PUSH,
-    AGENT_CAPABILITIES.SPAWN_WORKER, // Spawn resolver workers on conflict
-    LIFECYCLE_CAPABILITIES.DONE,
-    MSG_CAPABILITIES.SEND,
-    MSG_CAPABILITIES.SUBSCRIBE,
-    WORKSPACE_CAPABILITIES.INTEGRATE,
-  ],
-
-  workspace: {
-    type: "own",
-    // Integrator's worktree is on a merge branch, merges INTO integration branch
-    branchPattern: "integrator/{coordinator-id}@{timestamp}",
-    cleanupOnTerminate: true,
-  },
-
-  lifecycle: {
-    type: "persistent",
-    cascadeTerminate: true,
-  },
-
-  protocol: {
-    subscriptions: ["MERGE_REQUEST", "WORKER_DONE"],
-    canEmit: ["MERGE_COMPLETE", "LAND_COMPLETE", "CONFLICT_DETECTED"],
-  },
-};

package/src/roles/builtin/monitor.ts

@@ -1,65 +0,0 @@
-/**
- * Monitor Role Definition
- *
- * Event-driven, activates on specific events rather than running continuously.
- */
-
-import type { RoleDefinition } from "../types.js";
-import {
-  FILE_CAPABILITIES,
-  LIFECYCLE_CAPABILITIES,
-  MSG_CAPABILITIES,
-} from "../capabilities.js";
-
-/**
- * Monitor Role
- *
- * Health monitoring agent that:
- * - Activates on specific events (not continuous polling)
- * - Checks worker health and activity
- * - Detects stale agents (work assigned, no progress > 30 min)
- * - Detects stale sessions
- * - Requests termination of unresponsive agents
- * - Notifies coordinator of issues
- *
- * - Per-coordinator scope (not global)
- * - Event-driven activation
- * - Stateless (queries EventStore on each activation)
- * - No git workspace needed
- * - Bound to coordinator lifecycle
- */
-export const MonitorRole: RoleDefinition = {
-  name: "monitor",
-  displayName: "Monitor",
-  description:
-    "Per-coordinator health monitoring, stale agent detection, cleanup orchestration",
-
-  capabilities: [
-    FILE_CAPABILITIES.READ,
-    LIFECYCLE_CAPABILITIES.DONE, // Can shutdown gracefully
-    MSG_CAPABILITIES.SEND,
-    MSG_CAPABILITIES.BROADCAST,
-    MSG_CAPABILITIES.SUBSCRIBE,
-  ],
-
-  workspace: {
-    type: "none", // Monitor doesn't need a git workspace
-    // Accesses agent state via EventStore and registry, not filesystem
-  },
-
-  lifecycle: {
-    type: "event-driven", // Activates on events, not continuous
-    parentBound: true, // Tied to coordinator lifecycle
-  },
-
-  protocol: {
-    // Subscribes to specific events that require monitoring
-    subscriptions: [
-      "WORKER_SPAWNED", // Track new workers
-      "WORKER_DONE", // Track completions
-      "HEALTH_CHECK_TIMER", // Periodic health check trigger
-      "AGENT_TIMEOUT", // External timeout signal
-    ],
-    canEmit: ["HEALTH_CHECK", "STALE_AGENT", "FORCE_TERMINATE_REQUEST"],
-  },
-};

package/src/roles/builtin/worker.ts

@@ -1,134 +0,0 @@
-/**
- * Worker Role Definition
- *
- * Executes discrete tasks, writes code, runs tests.
- * Ephemeral, task-bound with 30-minute stale timeout.
- */
-
-import type { RoleDefinition } from "../types.js";
-import {
-  FILE_CAPABILITIES,
-  GIT_CAPABILITIES,
-  EXEC_CAPABILITIES,
-  LIFECYCLE_CAPABILITIES,
-  AGENT_CAPABILITIES,
-  MSG_CAPABILITIES,
-  WORKSPACE_CAPABILITIES,
-} from "../capabilities.js";
-
-/** 30 minutes in milliseconds (stale timeout) */
-const STALE_TIMEOUT_MS = 30 * 60 * 1000;
-
-/**
- * Worker Role
- *
- * Core execution agent that:
- * - Executes discrete tasks
- * - Writes code and makes file changes
- * - Runs tests, builds, and lints
- * - Can spawn child workers
- * - Self-terminates on task completion
- */
-export const WorkerRole: RoleDefinition = {
-  name: "worker",
-  displayName: "Worker",
-  description: "Executes discrete tasks, writes code, runs tests",
-
-  capabilities: [
-    FILE_CAPABILITIES.READ,
-    FILE_CAPABILITIES.WRITE,
-    FILE_CAPABILITIES.DELETE,
-    GIT_CAPABILITIES.COMMIT,
-    EXEC_CAPABILITIES.COMMAND,
-    EXEC_CAPABILITIES.BUILD,
-    EXEC_CAPABILITIES.TEST,
-    EXEC_CAPABILITIES.LINT,
-    LIFECYCLE_CAPABILITIES.DONE,
-    AGENT_CAPABILITIES.SPAWN_WORKER,
-    MSG_CAPABILITIES.SEND,
-    WORKSPACE_CAPABILITIES.WORKTREE,
-  ],
-
-  workspace: {
-    type: "own",
-    branchPattern: "worker/{prefix?}/{agent-id}/{task-id}@{timestamp}",
-    cleanupOnTerminate: true,
-  },
-
-  lifecycle: {
-    type: "ephemeral",
-    taskBound: true,
-    maxDurationMs: STALE_TIMEOUT_MS,
-    cascadeTerminate: true,
-    selfCleanup: true,
-  },
-
-  protocol: {
-    subscriptions: ["WORK_ASSIGNED", "HEALTH_CHECK"],
-    canEmit: ["WORKER_DONE", "MERGE_REQUEST"],
-  },
-
-  systemPrompt: `You are a worker agent. After completing your assigned task:
-1. Verify all requirements are met
-2. Commit any changes (if working with files)
-3. Call done() with status "completed" and a summary of what you did
-
-IMPORTANT: You MUST call done() when finished. Example:
-done({ status: "completed", summary: "Created src/greeting.ts with hello function and committed changes" })`,
-};
-
-/**
- * Resolver Worker Role
- *
- * Specialized worker spawned by Integrator to resolve merge conflicts.
- * Inherits from Worker with conflict resolution guidance.
- */
-export const ResolverWorkerRole: RoleDefinition = {
-  name: "worker.resolver",
-  displayName: "Resolver Worker",
-  description: "Resolves merge conflicts with fresh baseline",
-  extends: "worker",
-
-  // Inherits capabilities from worker
-  capabilities: [
-    FILE_CAPABILITIES.READ,
-    FILE_CAPABILITIES.WRITE,
-    FILE_CAPABILITIES.DELETE,
-    GIT_CAPABILITIES.COMMIT,
-    EXEC_CAPABILITIES.COMMAND,
-    EXEC_CAPABILITIES.BUILD,
-    EXEC_CAPABILITIES.TEST,
-    EXEC_CAPABILITIES.LINT,
-    LIFECYCLE_CAPABILITIES.DONE,
-    AGENT_CAPABILITIES.SPAWN_WORKER,
-    MSG_CAPABILITIES.SEND,
-    WORKSPACE_CAPABILITIES.WORKTREE,
-  ],
-
-  // Inherits workspace from worker
-  workspace: {
-    type: "own",
-    branchPattern: "worker/resolver/{agent-id}/{task-id}@{timestamp}",
-    cleanupOnTerminate: true,
-  },
-
-  // Inherits lifecycle from worker
-  lifecycle: {
-    type: "ephemeral",
-    taskBound: true,
-    maxDurationMs: STALE_TIMEOUT_MS,
-    cascadeTerminate: true,
-    selfCleanup: true,
-  },
-
-  protocol: {
-    subscriptions: ["WORK_ASSIGNED", "HEALTH_CHECK"],
-    canEmit: ["WORKER_DONE", "RESOLVER_DONE"],
-  },
-
-  systemPrompt: `You are a resolver worker. Your job is to:
-1. Apply the changes from the original work to the updated baseline
-2. Resolve any conflicts that arise
-3. Ensure tests pass after resolution
-4. Call done() when complete`,
-};

package/src/roles/capabilities.ts

@@ -1,257 +0,0 @@
-/**
- * Capability Constants and Tool Mappings
- *
- * Defines all available capabilities and their mapping to MCP tools.
- */
-
-import type { Capability, CapabilityToolMap } from "./types.js";
-
-// =============================================================================
-// Capability Constants
-// =============================================================================
-
-/** File operation capabilities */
-export const FILE_CAPABILITIES = {
-  READ: "file.read" as const,
-  WRITE: "file.write" as const,
-  DELETE: "file.delete" as const,
-};
-
-/** Git operation capabilities */
-export const GIT_CAPABILITIES = {
-  COMMIT: "git.commit" as const,
-  MERGE: "git.merge" as const,
-  PUSH: "git.push" as const,
-  BRANCH_CREATE: "git.branch.create" as const,
-  BRANCH_DELETE: "git.branch.delete" as const,
-};
-
-/** Agent management capabilities */
-export const AGENT_CAPABILITIES = {
-  SPAWN_WORKER: "agent.spawn.worker" as const,
-  SPAWN_INTEGRATOR: "agent.spawn.integrator" as const,
-  SPAWN_MONITOR: "agent.spawn.monitor" as const,
-  SPAWN_CUSTOM: "agent.spawn.custom" as const,
-  TERMINATE: "agent.terminate" as const,
-};
-
-/** Lifecycle capabilities */
-export const LIFECYCLE_CAPABILITIES = {
-  DONE: "lifecycle.done" as const,
-  PERSISTENT: "lifecycle.persistent" as const,
-  DAEMON: "lifecycle.daemon" as const,
-};
-
-/** Task management capabilities */
-export const TASK_CAPABILITIES = {
-  CREATE: "task.create" as const,
-  ASSIGN: "task.assign" as const,
-  UPDATE: "task.update" as const,
-  CLOSE: "task.close" as const,
-  CLAIM: "task.claim" as const,
-};
-
-/** Execution capabilities */
-export const EXEC_CAPABILITIES = {
-  COMMAND: "exec.command" as const,
-  BUILD: "exec.build" as const,
-  TEST: "exec.test" as const,
-  LINT: "exec.lint" as const,
-};
-
-/** Communication capabilities */
-export const MSG_CAPABILITIES = {
-  SEND: "msg.send" as const,
-  BROADCAST: "msg.broadcast" as const,
-  SUBSCRIBE: "msg.subscribe" as const,
-};
-
-/** Workspace capabilities */
-export const WORKSPACE_CAPABILITIES = {
-  WORKTREE: "workspace.worktree" as const,    // Gets own git worktree; done() submits to merge queue
-  STREAM: "workspace.stream" as const,         // Creates integration stream at spawn
-  INTEGRATE: "workspace.integrate" as const,   // Joins stream; processes merge queue entries
-};
-
-/** Wildcard capability */
-export const WILDCARD_CAPABILITY = "*" as const;
-
-// =============================================================================
-// All Known Capabilities
-// =============================================================================
-
-/**
- * Set of all known capability strings for validation
- */
-export const ALL_CAPABILITIES: Set<Capability> = new Set([
-  // File
-  FILE_CAPABILITIES.READ,
-  FILE_CAPABILITIES.WRITE,
-  FILE_CAPABILITIES.DELETE,
-  // Git
-  GIT_CAPABILITIES.COMMIT,
-  GIT_CAPABILITIES.MERGE,
-  GIT_CAPABILITIES.PUSH,
-  GIT_CAPABILITIES.BRANCH_CREATE,
-  GIT_CAPABILITIES.BRANCH_DELETE,
-  // Agent
-  AGENT_CAPABILITIES.SPAWN_WORKER,
-  AGENT_CAPABILITIES.SPAWN_INTEGRATOR,
-  AGENT_CAPABILITIES.SPAWN_MONITOR,
-  AGENT_CAPABILITIES.SPAWN_CUSTOM,
-  AGENT_CAPABILITIES.TERMINATE,
-  // Lifecycle
-  LIFECYCLE_CAPABILITIES.DONE,
-  LIFECYCLE_CAPABILITIES.PERSISTENT,
-  LIFECYCLE_CAPABILITIES.DAEMON,
-  // Task
-  TASK_CAPABILITIES.CREATE,
-  TASK_CAPABILITIES.ASSIGN,
-  TASK_CAPABILITIES.UPDATE,
-  TASK_CAPABILITIES.CLOSE,
-  TASK_CAPABILITIES.CLAIM,
-  // Exec
-  EXEC_CAPABILITIES.COMMAND,
-  EXEC_CAPABILITIES.BUILD,
-  EXEC_CAPABILITIES.TEST,
-  EXEC_CAPABILITIES.LINT,
-  // Msg
-  MSG_CAPABILITIES.SEND,
-  MSG_CAPABILITIES.BROADCAST,
-  MSG_CAPABILITIES.SUBSCRIBE,
-  // Workspace
-  WORKSPACE_CAPABILITIES.WORKTREE,
-  WORKSPACE_CAPABILITIES.STREAM,
-  WORKSPACE_CAPABILITIES.INTEGRATE,
-  // Wildcard
-  WILDCARD_CAPABILITY,
-]);
-
-/**
- * Check if a capability string is known.
- * Accepts exact matches from ALL_CAPABILITIES, plus dynamic `agent.spawn.*`
- * patterns generated by team-defined spawn rules (e.g., "agent.spawn.grinder").
- */
-export function isKnownCapability(capability: string): capability is Capability {
-  if (ALL_CAPABILITIES.has(capability as Capability)) {
-    return true;
-  }
-  // Team-defined roles generate dynamic agent.spawn.<role> capabilities
-  // via TeamLoader spawn_rules translation (RD3). These are valid at runtime.
-  if (capability.startsWith("agent.spawn.")) {
-    return true;
-  }
-  return false;
-}
-
-// =============================================================================
-// Capability to Tool Mapping
-// =============================================================================
-
-/**
- * Maps capabilities to their corresponding MCP tools.
- * Used for capability-based tool filtering.
- *
- * NOTE: Tool names must match actual MCP tool registration names in mcp-server.ts
- */
-export const CAPABILITY_TOOL_MAP: CapabilityToolMap = {
-  // File operations (Claude Code tools, if available)
-  [FILE_CAPABILITIES.READ]: ["read", "glob", "grep"],
-  [FILE_CAPABILITIES.WRITE]: ["write", "edit"],
-  [FILE_CAPABILITIES.DELETE]: ["bash"], // rm via bash
-
-  // Git operations (via bash)
-  [GIT_CAPABILITIES.COMMIT]: ["bash"],
-  [GIT_CAPABILITIES.MERGE]: ["bash"],
-  [GIT_CAPABILITIES.PUSH]: ["bash"],
-  [GIT_CAPABILITIES.BRANCH_CREATE]: ["bash"],
-  [GIT_CAPABILITIES.BRANCH_DELETE]: ["bash"],
-
-  // Agent operations - MCP tool names
-  [AGENT_CAPABILITIES.SPAWN_WORKER]: ["spawn_agent"],
-  [AGENT_CAPABILITIES.SPAWN_INTEGRATOR]: ["spawn_agent"],
-  [AGENT_CAPABILITIES.SPAWN_MONITOR]: ["spawn_agent"],
-  [AGENT_CAPABILITIES.SPAWN_CUSTOM]: ["spawn_agent"],
-  [AGENT_CAPABILITIES.TERMINATE]: ["stop_agent"],
-
-  // Lifecycle operations
-  [LIFECYCLE_CAPABILITIES.DONE]: ["done"],
-
-  // Task operations (via TaskBackend + OpenTasks tools)
-  [TASK_CAPABILITIES.CREATE]: ["create_task"],
-  [TASK_CAPABILITIES.ASSIGN]: ["assign_task", "task"],
-  [TASK_CAPABILITIES.UPDATE]: ["update_task", "task", "link", "annotate"],
-  [TASK_CAPABILITIES.CLOSE]: ["close_task", "task"],
-  [TASK_CAPABILITIES.CLAIM]: ["claim_task", "unclaim_task", "list_claimable_tasks"],
-
-  // Execution operations
-  [EXEC_CAPABILITIES.COMMAND]: ["bash"],
-  [EXEC_CAPABILITIES.BUILD]: ["bash"],
-  [EXEC_CAPABILITIES.TEST]: ["bash"],
-  [EXEC_CAPABILITIES.LINT]: ["bash"],
-
-  // Communication operations - MCP tool names
-  [MSG_CAPABILITIES.SEND]: ["send_message", "check_messages", "send_peer_message"],
-  [MSG_CAPABILITIES.BROADCAST]: ["send_message"],
-  [MSG_CAPABILITIES.SUBSCRIBE]: ["check_messages"],
-};
-
-// =============================================================================
-// Workspace/Query Tools (always available)
-// =============================================================================
-
-/**
- * Tools that are always available regardless of capabilities.
- * These are read-only observability tools that don't require special permissions.
- */
-export const ALWAYS_ALLOWED_TOOLS: string[] = [
-  "emit_status",
-  "query_index",
-  "get_hierarchy",
-  "get_agent_summary",
-  "get_task",
-  "inject_context",
-  "wait_for_activity",
-  "send_peer_request",
-  "respond_to_peer_request",
-];
-
-/**
- * Get the tools allowed for a set of capabilities
- */
-export function getToolsForCapabilities(
-  capabilities: Capability[],
-  allToolNames: string[]
-): string[] {
-  // Wildcard means all tools
-  if (capabilities.includes(WILDCARD_CAPABILITY)) {
-    return allToolNames;
-  }
-
-  const allowedTools = new Set<string>();
-
-  for (const cap of capabilities) {
-    const tools = CAPABILITY_TOOL_MAP[cap];
-    if (tools) {
-      for (const tool of tools) {
-        allowedTools.add(tool);
-      }
-    }
-  }
-
-  return Array.from(allowedTools);
-}
-
-/**
- * Check if a capability grants access to a specific tool
- */
-export function capabilityGrantsTool(
-  capability: Capability,
-  toolName: string
-): boolean {
-  if (capability === WILDCARD_CAPABILITY) {
-    return true;
-  }
-  const tools = CAPABILITY_TOOL_MAP[capability];
-  return tools ? tools.includes(toolName) : false;
-}