macro-agent 0.1.2 → 0.1.4

package/src/mcp/mcp-server-v2.ts

@@ -0,0 +1,485 @@
+/**
+ * MCP Server V2 Factory
+ *
+ * Dramatically simplified — only registers macro-agent-specific tools:
+ * - done: Signal completion and trigger lifecycle cleanup
+ * - inject_context: Steer another agent's session
+ * - spawn_agent: Spawn a child agent
+ * - stop_agent: Stop a child agent
+ * - get_hierarchy: Query agent hierarchy
+ *
+ * Tools that moved to subsystems:
+ * - send_message, check_messages → agent-inbox MCP server (via IPC)
+ * - create_task, get_task, query_index (tasks) → opentasks MCP server (via IPC)
+ * - claim_task, unclaim_task, list_claimable_tasks → opentasks MCP server
+ * - emit_status → replaced by inbox send (event messages)
+ *
+ * @module mcp/mcp-server-v2
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import type { AgentManager } from "../agent/agent-manager.js";
+import type { AgentStore } from "../agent/agent-store.js";
+import type { InboxAdapter } from "../adapters/types.js";
+import type { TasksAdapter } from "../adapters/types.js";
+import type { RoleRegistry, RoleDefinition } from "../roles/types.js";
+import { DefaultRoleRegistry, isToolAllowedForRole } from "../roles/registry.js";
+import type { ToolContext, HierarchyNode } from "./types.js";
+import { MCPToolError } from "./types.js";
+import {
+  DoneSchema,
+  createDoneHandlerV2,
+  DONE_TOOL_INFO,
+  type DoneToolDepsV2,
+} from "./tools/done-v2.js";
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+export interface MCPServerV2Config {
+  name?: string;
+  version?: string;
+}
+
+export interface MCPServicesV2 {
+  agentStore: AgentStore;
+  agentManager: AgentManager;
+  inboxAdapter: InboxAdapter;
+  tasksAdapter: TasksAdapter;
+  roleRegistry?: RoleRegistry;
+  taskMode?: "push" | "pull";
+}
+
+export interface MCPServerV2Instance {
+  server: McpServer;
+  start(): Promise<void>;
+  close(): Promise<void>;
+}
+
+// =============================================================================
+// Schemas
+// =============================================================================
+
+const SpawnAgentSchema = {
+  task: z.string().describe("Task description for the child agent"),
+  role: z.string().optional().describe("Role for the child agent"),
+  cwd: z.string().optional().describe("Working directory (defaults to parent's cwd)"),
+  config: z.object({
+    model: z.string().optional(),
+  }).optional().describe("Custom config"),
+};
+
+const StopAgentSchema = {
+  agent_id: z.string().describe("Agent ID to stop (must be in caller's subtree)"),
+  reason: z.enum(["completed", "failed", "cancelled"]).optional().default("cancelled"),
+};
+
+const GetHierarchySchema = {
+  root: z.string().optional().describe("Root agent ID (defaults to caller)"),
+  depth: z.number().optional().describe("Max depth"),
+};
+
+const InjectContextSchema = {
+  target_agent_id: z.string().describe("Agent ID to inject into"),
+  content: z.string().describe("Context to inject"),
+  urgent: z.boolean().optional().default(false).describe("If true, interrupts immediately"),
+};
+
+const WaitForActivitySchema = {
+  event_type: z.string().optional().describe("Event type to wait for (e.g., 'agent_stopped', 'task_completed')"),
+  timeout_ms: z.number().optional().default(30000).describe("Max time to wait in milliseconds"),
+};
+
+// =============================================================================
+// Factory
+// =============================================================================
+
+export function createMCPServerV2(
+  context: ToolContext,
+  services: MCPServicesV2,
+  config: MCPServerV2Config = {}
+): MCPServerV2Instance {
+  const { name = "macro-agent-mcp", version = "2.0.0" } = config;
+  const {
+    agentStore,
+    agentManager,
+    inboxAdapter,
+    tasksAdapter,
+    roleRegistry = new DefaultRoleRegistry(),
+    taskMode,
+  } = services;
+
+  // Resolve agent's role for tool filtering
+  const agentRecord = agentStore.getAgent(context.agent_id);
+  const agentRole = agentRecord?.role ?? "worker";
+  let resolvedRole: RoleDefinition;
+  try {
+    resolvedRole = roleRegistry.resolveRole(agentRole);
+  } catch {
+    // Fallback to worker role if resolution fails (e.g., unknown custom role)
+    resolvedRole = roleRegistry.resolveRole("worker");
+  }
+
+  function shouldRegister(toolName: string): boolean {
+    return isToolAllowedForRole(toolName, resolvedRole);
+  }
+
+  const server = new McpServer(
+    { name, version },
+    { capabilities: { tools: {} } }
+  );
+
+  // ── Tool: done ───────────────────────────────────────────────
+
+  if (shouldRegister("done")) {
+    const doneDeps: DoneToolDepsV2 = {
+      agentStore,
+      agentManager,
+      inboxAdapter,
+      tasksAdapter,
+      roleRegistry,
+      taskMode,
+    };
+    const doneHandler = createDoneHandlerV2(context, doneDeps);
+
+    server.registerTool(DONE_TOOL_INFO.name, {
+      description: DONE_TOOL_INFO.description,
+      inputSchema: DoneSchema,
+    }, async (args) => {
+      const result = await doneHandler(args as any);
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(result),
+        }],
+      };
+    });
+  }
+
+  // ── Tool: spawn_agent ────────────────────────────────────────
+
+  if (shouldRegister("spawn_agent")) {
+    server.registerTool("spawn_agent", {
+      description: "Spawn a child agent to work on a subtask",
+      inputSchema: SpawnAgentSchema,
+    }, async (args) => {
+      try {
+        const spawned = await agentManager.spawn({
+          task: args.task,
+          parent: context.agent_id,
+          role: args.role,
+          cwd: args.cwd ?? context.cwd,
+          config: args.config,
+        });
+
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({
+              agent_id: spawned.id,
+              name: spawned.agent.name,
+              task_id: spawned.agent.task_id,
+              session_id: spawned.session_id,
+            }),
+          }],
+        };
+      } catch (error) {
+        throw new MCPToolError(
+          `Failed to spawn agent: ${error}`,
+          "SPAWN_FAILED"
+        );
+      }
+    });
+  }
+
+  // ── Tool: stop_agent ─────────────────────────────────────────
+
+  if (shouldRegister("stop_agent")) {
+    server.registerTool("stop_agent", {
+      description: "Stop a child agent in your subtree",
+      inputSchema: StopAgentSchema,
+    }, async (args) => {
+      const targetId = args.agent_id;
+      const target = agentStore.getAgent(targetId);
+      if (!target) {
+        throw new MCPToolError(`Agent ${targetId} not found`, "AGENT_NOT_FOUND");
+      }
+
+      // Verify target is in caller's subtree
+      const descendants = agentStore.getDescendants(context.agent_id);
+      const isInSubtree = descendants.some((d) => d.id === targetId);
+      if (!isInSubtree && targetId !== context.agent_id) {
+        throw new MCPToolError(
+          `Agent ${targetId} is not in your subtree`,
+          "NOT_IN_SUBTREE"
+        );
+      }
+
+      await agentManager.terminate(targetId, args.reason ?? "cancelled");
+
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({
+            success: true,
+            stopped_agents: [{ agent_id: targetId, name: target.name }],
+          }),
+        }],
+      };
+    });
+  }
+
+  // ── Tool: get_hierarchy ──────────────────────────────────────
+
+  if (shouldRegister("get_hierarchy")) {
+    server.registerTool("get_hierarchy", {
+      description: "Get the agent hierarchy tree",
+      inputSchema: GetHierarchySchema,
+    }, async (args) => {
+      const rootId = args.root ?? context.agent_id;
+      const hierarchy = agentManager.getHierarchy(rootId, {
+        depth: args.depth,
+      });
+
+      if (!hierarchy) {
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({ tree: null, depth: 0, total_agents: 0 }),
+          }],
+        };
+      }
+
+      function toNode(h: { agent: any; children: any[] }): HierarchyNode {
+        return {
+          agent_id: h.agent.id,
+          name: h.agent.name,
+          task: h.agent.task,
+          state: h.agent.state,
+          children: h.children.map(toNode),
+        };
+      }
+
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({
+            tree: toNode(hierarchy.root),
+            depth: hierarchy.depth,
+            total_agents: hierarchy.totalAgents,
+          }),
+        }],
+      };
+    });
+  }
+
+  // ── Tool: inject_context ─────────────────────────────────────
+
+  if (shouldRegister("inject_context")) {
+    server.registerTool("inject_context", {
+      description: "Inject context into another agent's session for time-sensitive steering",
+      inputSchema: InjectContextSchema,
+    }, async (args) => {
+      const targetId = args.target_agent_id;
+
+      // Try sending as high-priority inbox message (agent-inbox handles delivery)
+      try {
+        const importance = args.urgent ? "urgent" : "high";
+        const msgId = await inboxAdapter.send(
+          context.agent_id,
+          targetId,
+          { type: "text", text: args.content },
+          {
+            importance,
+            subject: "Context injection",
+            threadTag: `inject:${context.agent_id}`,
+          }
+        );
+
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({
+              success: true,
+              method: "inbox",
+              message_id: msgId,
+              target_agent_id: targetId,
+            }),
+          }],
+        };
+      } catch (error) {
+        throw new MCPToolError(
+          `Failed to inject context: ${error}`,
+          "ROUTING_FAILED"
+        );
+      }
+    });
+  }
+
+  // ── Tool: claim_task (pull mode) ─────────────────────────────
+
+  if (shouldRegister("claim_task")) {
+    server.registerTool("claim_task", {
+      description: "Claim the next available task from the pool (pull mode). Returns the claimed task or null if none available.",
+      inputSchema: {
+        tags: z.array(z.string()).optional().describe("Filter tasks by tags"),
+        root_tasks_only: z.boolean().optional().describe("Only claim root-level tasks (no subtasks)"),
+      },
+    }, async (args) => {
+      try {
+        const filter: { tags?: string[] } = {};
+        if (args.tags) filter.tags = args.tags;
+
+        const task = await tasksAdapter.claimTask(context.agent_id, filter);
+
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify(task ?? { claimed: false, task: null }),
+          }],
+        };
+      } catch (error) {
+        throw new MCPToolError(
+          `Failed to claim task: ${error}`,
+          "TASK_NOT_FOUND"
+        );
+      }
+    });
+  }
+
+  // ── Tool: unclaim_task (pull mode) ─────────────────────────
+
+  if (shouldRegister("unclaim_task")) {
+    server.registerTool("unclaim_task", {
+      description: "Release a previously claimed task back to the pool.",
+      inputSchema: {
+        task_id: z.string().describe("ID of the task to unclaim"),
+      },
+    }, async (args) => {
+      try {
+        await tasksAdapter.unclaimTask(args.task_id);
+
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({ success: true, task_id: args.task_id }),
+          }],
+        };
+      } catch (error) {
+        throw new MCPToolError(
+          `Failed to unclaim task: ${error}`,
+          "TASK_NOT_FOUND"
+        );
+      }
+    });
+  }
+
+  // ── Tool: list_claimable_tasks (pull mode) ─────────────────
+
+  if (shouldRegister("list_claimable_tasks")) {
+    server.registerTool("list_claimable_tasks", {
+      description: "List tasks available for claiming from the pool.",
+      inputSchema: {
+        tags: z.array(z.string()).optional().describe("Filter tasks by tags"),
+        limit: z.number().optional().describe("Maximum number of tasks to return"),
+      },
+    }, async (args) => {
+      try {
+        const filter: { tags?: string[]; limit?: number } = {};
+        if (args.tags) filter.tags = args.tags;
+        if (args.limit) filter.limit = args.limit;
+
+        const tasks = await tasksAdapter.listClaimable(filter);
+
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({ tasks, count: tasks.length }),
+          }],
+        };
+      } catch (error) {
+        throw new MCPToolError(
+          `Failed to list claimable tasks: ${error}`,
+          "TASK_NOT_FOUND"
+        );
+      }
+    });
+  }
+
+  // ── Tool: wait_for_activity ──────────────────────────────────
+
+  server.registerTool("wait_for_activity", {
+    description: "Block until a matching event arrives in your inbox, or timeout. Useful for waiting on agent completion, task updates, or other async events.",
+    inputSchema: WaitForActivitySchema,
+  }, async (args) => {
+    const POLL_INTERVAL_MS = 2000;
+    const timeoutMs = args.timeout_ms ?? 30000;
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < timeoutMs) {
+      try {
+        const messages = await inboxAdapter.checkInbox(context.agent_id);
+
+        if (args.event_type) {
+          // Look for messages matching event_type in content.event field
+          const match = messages.find((msg) => {
+            const content = msg.content as Record<string, unknown> | undefined;
+            return content?.event === args.event_type;
+          });
+          if (match) {
+            return {
+              content: [{
+                type: "text" as const,
+                text: JSON.stringify({ timeout: false, message: match }),
+              }],
+            };
+          }
+        } else if (messages.length > 0) {
+          // No event_type filter — return the first message that arrived after startTime
+          const recent = messages.find((msg) => {
+            const createdAt = msg.created_at;
+            if (typeof createdAt === "number") return createdAt >= startTime;
+            if (typeof createdAt === "string") return new Date(createdAt).getTime() >= startTime;
+            return false;
+          });
+          if (recent) {
+            return {
+              content: [{
+                type: "text" as const,
+                text: JSON.stringify({ timeout: false, message: recent }),
+              }],
+            };
+          }
+        }
+      } catch {
+        // Inbox check failed — continue polling
+      }
+
+      // Wait before next poll
+      await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+
+    return {
+      content: [{
+        type: "text" as const,
+        text: JSON.stringify({ timeout: true }),
+      }],
+    };
+  });
+
+  // ── Start / Close ────────────────────────────────────────────
+
+  return {
+    server,
+    async start(): Promise<void> {
+      const transport = new StdioServerTransport();
+      await server.connect(transport);
+    },
+    async close(): Promise<void> {
+      await server.close();
+    },
+  };
+}

package/src/mcp/tools/done-v2.ts

@@ -0,0 +1,203 @@
+/**
+ * done() MCP Tool V2
+ *
+ * Simplified version that uses InboxAdapter + TasksAdapter instead of
+ * EventStore + MessageRouter + TaskManager.
+ *
+ * @module mcp/tools/done-v2
+ */
+
+import { z } from "zod";
+import type { InboxAdapter, TasksAdapter } from "../../adapters/types.js";
+import type { AgentManager } from "../../agent/agent-manager.js";
+import type { AgentStore } from "../../agent/agent-store.js";
+import type { RoleRegistry } from "../../roles/types.js";
+import type { ToolContext } from "../types.js";
+import type { DoneResult, LifecycleContext } from "../../lifecycle/types.js";
+import { detectCleanupStatus } from "../../lifecycle/cleanup.js";
+import { dispatchDoneV2, type HandlerDepsV2 } from "../../lifecycle/handlers-v2.js";
+
+// =============================================================================
+// Schema (unchanged from V1)
+// =============================================================================
+
+export const DoneSchema = {
+  status: z
+    .enum(["completed", "failed", "blocked", "deferred"])
+    .describe("Completion status of the agent's work"),
+  summary: z
+    .string()
+    .optional()
+    .describe("Summary of work completed or reason for status"),
+  details: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe("Additional structured details"),
+  task_id: z
+    .string()
+    .optional()
+    .describe("Task ID to update (defaults to agent's bound task)"),
+};
+
+// =============================================================================
+// Dependencies
+// =============================================================================
+
+export interface DoneToolDepsV2 {
+  agentStore: AgentStore;
+  agentManager: AgentManager;
+  inboxAdapter: InboxAdapter;
+  tasksAdapter: TasksAdapter;
+  roleRegistry?: RoleRegistry;
+  taskMode?: "push" | "pull";
+  mergeQueue?: import("../../workspace/merge-queue/types.js").MergeQueueInterface;
+}
+
+// =============================================================================
+// Capability Check
+// =============================================================================
+
+function hasLifecycleDoneCapability(
+  agentStore: AgentStore,
+  agentId: string,
+  roleRegistry?: RoleRegistry
+): { hasCapability: boolean; role: string } {
+  const record = agentStore.getAgent(agentId);
+  if (!record) {
+    return { hasCapability: false, role: "unknown" };
+  }
+
+  const role = record.role ?? "worker";
+
+  if (roleRegistry) {
+    return {
+      hasCapability: roleRegistry.hasCapability(role, "lifecycle.done"),
+      role,
+    };
+  }
+
+  // Fallback
+  const rolesWithDone = new Set(["worker", "integrator", "monitor"]);
+  return {
+    hasCapability:
+      rolesWithDone.has(role) || rolesWithDone.has(role.split(".")[0]),
+    role,
+  };
+}
+
+// =============================================================================
+// Build Lifecycle Context
+// =============================================================================
+
+function buildLifecycleContext(
+  toolContext: ToolContext,
+  agentStore: AgentStore,
+  role: string,
+  roleRegistry?: RoleRegistry
+): LifecycleContext {
+  const record = agentStore.getAgent(toolContext.agent_id);
+
+  const ctx: LifecycleContext = {
+    agentId: toolContext.agent_id,
+    role,
+    taskId: toolContext.task_id,
+    parentId: record?.parent_id ?? undefined,
+    workspacePath: record?.workspace_path ?? toolContext.cwd,
+    streamId: record?.workspace_stream_id ?? process.env.MACRO_STREAM_ID,
+  };
+
+  // Resolve capabilities for dispatch
+  if (roleRegistry) {
+    try {
+      const resolvedRole = roleRegistry.resolveRole(role);
+      if (resolvedRole?.capabilities) {
+        ctx.capabilities = [...resolvedRole.capabilities];
+      }
+    } catch {
+      // Role not in registry
+    }
+  }
+
+  return ctx;
+}
+
+// =============================================================================
+// Tool Handler
+// =============================================================================
+
+export function createDoneHandlerV2(
+  context: ToolContext,
+  deps: DoneToolDepsV2
+) {
+  return async (args: {
+    status: "completed" | "failed" | "blocked" | "deferred";
+    summary?: string;
+    details?: Record<string, unknown>;
+    task_id?: string;
+  }): Promise<DoneResult> => {
+    const { agentStore, agentManager, inboxAdapter, tasksAdapter, roleRegistry } = deps;
+
+    // Step 1: Check capability
+    const { hasCapability, role } = hasLifecycleDoneCapability(
+      agentStore,
+      context.agent_id,
+      roleRegistry
+    );
+
+    if (!hasCapability) {
+      return {
+        success: false,
+        shouldTerminate: false,
+        status: args.status,
+        cleanupStatus: { ready: false, reason: "Capability check failed" },
+        error: `Agent ${context.agent_id} does not have lifecycle.done capability (role: ${role})`,
+      };
+    }
+
+    // Step 2: Build context and detect cleanup status
+    const lifecycleContext = buildLifecycleContext(
+      context,
+      agentStore,
+      role,
+      roleRegistry
+    );
+
+    const cleanupStatus = detectCleanupStatus(lifecycleContext);
+
+    // Step 3: Dispatch to V2 handler
+    const handlerDeps: HandlerDepsV2 = {
+      inboxAdapter,
+      tasksAdapter,
+      agentManager,
+      taskMode: deps.taskMode,
+      mergeQueue: deps.mergeQueue,
+    };
+
+    const handlerResult = await dispatchDoneV2(
+      lifecycleContext,
+      {
+        status: args.status,
+        summary: args.summary,
+        details: args.details,
+        taskId: args.task_id ?? context.task_id,
+      },
+      cleanupStatus,
+      handlerDeps
+    );
+
+    return {
+      success: true,
+      shouldTerminate: handlerResult.shouldTerminate,
+      status: args.status,
+      cleanupStatus,
+      warnings: handlerResult.warnings,
+    };
+  };
+}
+
+export const DONE_TOOL_INFO = {
+  name: "done",
+  description:
+    "Signal that the agent has completed its work. Triggers role-appropriate cleanup and termination.",
+  schema: DoneSchema,
+};