macro-agent 0.0.17 → 0.1.1

package/src/mcp/map-client.ts

@@ -0,0 +1,177 @@
+/**
+ * Thin MAP Client
+ *
+ * Ephemeral WebSocket client for MCP subprocesses to call MAP extension
+ * methods on the main server. Each call opens a connection, performs the
+ * MAP handshake, sends a single RPC, and disconnects.
+ *
+ * Uses raw WebSocket + JSON-RPC — not the full MAP ClientConnection SDK,
+ * since the SDK's capability negotiation and subscription management
+ * overhead is unnecessary for single-RPC ephemeral calls.
+ */
+
+import WebSocket from "ws";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id: number;
+  method: string;
+  params?: unknown;
+}
+
+interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: number;
+  result?: unknown;
+  error?: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+}
+
+export interface MapCallOptions {
+  /** Timeout in milliseconds (default: 30000) */
+  timeoutMs?: number;
+  /** Server token for authentication (appended as query param on WebSocket URL) */
+  serverToken?: string;
+}
+
+export class MapCallError extends Error {
+  readonly code: number;
+  readonly data?: unknown;
+
+  constructor(code: number, message: string, data?: unknown) {
+    super(message);
+    this.name = "MapCallError";
+    this.code = code;
+    this.data = data;
+  }
+}
+
+// =============================================================================
+// Implementation
+// =============================================================================
+
+/**
+ * Make a single MAP extension RPC call via ephemeral WebSocket.
+ *
+ * 1. Opens WebSocket to the MAP endpoint
+ * 2. Sends `map/connect` handshake
+ * 3. Sends the RPC request
+ * 4. Awaits the response
+ * 5. Closes the WebSocket
+ *
+ * @param serverUrl - HTTP URL of the macro-agent server (e.g., "http://localhost:3001")
+ * @param method - MAP extension method (e.g., "_macro/mcp/spawn_agent")
+ * @param params - Method parameters (includes context)
+ * @param options - Timeout and other options
+ * @returns The RPC result
+ */
+export async function mapCall<T = unknown>(
+  serverUrl: string,
+  method: string,
+  params?: unknown,
+  options?: MapCallOptions
+): Promise<T> {
+  const timeoutMs = options?.timeoutMs ?? 30000;
+  let wsUrl = serverUrl.replace(/^http/, "ws") + "/map";
+  if (options?.serverToken) {
+    wsUrl += `?token=${encodeURIComponent(options.serverToken)}`;
+  }
+
+  return new Promise<T>((resolve, reject) => {
+    let settled = false;
+    let nextId = 1;
+    let handshakeCompleted = false;
+
+    const timeout = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        ws.close();
+        reject(new MapCallError(-32000, `MAP call timed out after ${timeoutMs}ms: ${method}`));
+      }
+    }, timeoutMs);
+
+    const ws = new WebSocket(wsUrl);
+
+    ws.on("open", () => {
+      // Step 1: Send MAP handshake
+      const connectRequest: JsonRpcRequest = {
+        jsonrpc: "2.0",
+        id: nextId++,
+        method: "map/connect",
+        params: {
+          participantType: "client",
+          identity: `mcp-bridge-${Date.now()}`,
+        },
+      };
+      ws.send(JSON.stringify(connectRequest));
+    });
+
+    ws.on("message", (data) => {
+      if (settled) return;
+
+      let msg: JsonRpcResponse;
+      try {
+        msg = JSON.parse(data.toString());
+      } catch {
+        return; // Ignore non-JSON messages
+      }
+
+      if (!handshakeCompleted) {
+        // This should be the map/connect response
+        if (msg.error) {
+          settled = true;
+          clearTimeout(timeout);
+          ws.close();
+          reject(new MapCallError(msg.error.code, `MAP handshake failed: ${msg.error.message}`, msg.error.data));
+          return;
+        }
+
+        handshakeCompleted = true;
+
+        // Step 2: Send the actual RPC request
+        const rpcRequest: JsonRpcRequest = {
+          jsonrpc: "2.0",
+          id: nextId++,
+          method,
+          params,
+        };
+        ws.send(JSON.stringify(rpcRequest));
+        return;
+      }
+
+      // This is the RPC response
+      settled = true;
+      clearTimeout(timeout);
+      ws.close();
+
+      if (msg.error) {
+        reject(new MapCallError(msg.error.code, msg.error.message, msg.error.data));
+      } else {
+        resolve(msg.result as T);
+      }
+    });
+
+    ws.on("error", (err) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timeout);
+        reject(new MapCallError(-32000, `MAP WebSocket error: ${err.message}`));
+      }
+    });
+
+    ws.on("close", () => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timeout);
+        reject(new MapCallError(-32000, "MAP WebSocket closed unexpectedly"));
+      }
+    });
+  });
+}

package/src/mcp/mcp-server.ts

@@ -224,16 +224,6 @@ const StopAgentSchema = {
     .describe("Reason for stopping"),
 };
 
-const CreateTaskSchema = {
-  description: z.string().describe("Task description"),
-  parent_task: z.string().optional().describe("Parent task ID for subtasks"),
-  inputs: z.record(z.string(), z.unknown()).optional().describe("Initial inputs for the task"),
-};
-
-const GetTaskSchema = {
-  task_id: z.string().describe("Task ID to look up"),
-};
-
 // ─────────────────────────────────────────────────────────────────
 // Peer Communication Schemas
 // ─────────────────────────────────────────────────────────────────
@@ -351,6 +341,12 @@ export function createMCPServer(
         debugLog(`[MCP spawn_agent] Agent IDs: ${allAgents.map(a => a.id).join(', ')}`);
       }
 
+      // Inherit the parent's permission mode so sub-agents respect
+      // the same mode (e.g., "interactive") set during initialization.
+      // Read from env var since the MCP server is a separate process
+      // without access to the macro-agent server's in-memory state.
+      const parentPermissionMode = process.env.MACRO_PERMISSION_MODE;
+
       const spawned = await agentManager.spawn({
         task: args.task,
         parent: context.agent_id,
@@ -358,6 +354,7 @@ export function createMCPServer(
         topics: args.topics ?? [],
         config: args.config,
         cwd: args.cwd ?? context.cwd,
+        permissionMode: (parentPermissionMode || undefined) as import("acp-factory").PermissionMode | undefined,
       });
 
       return {
@@ -366,6 +363,7 @@ export function createMCPServer(
             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,
             }),
@@ -511,14 +509,18 @@ export function createMCPServer(
       includeAcknowledged: args.include_acknowledged ?? false,
     });
 
-    const formattedInternalMessages = internalMessages.map((msg) => ({
-      id: msg.id,
-      from: `agent:${msg.from.agent_id}`,
-      content: msg.content.length > 500 ? msg.content.substring(0, 500) : msg.content,
-      timestamp: msg.timestamp,
-      truncated: msg.truncated || msg.content.length > 500,
-      correlation_id: msg.correlation_id,
-    }));
+    const formattedInternalMessages = internalMessages.map((msg) => {
+      const fromAgent = msg.from.agent_id ? agentManager.get(msg.from.agent_id) : undefined;
+      return {
+        id: msg.id,
+        from: `agent:${msg.from.agent_id}`,
+        from_name: fromAgent?.name,
+        content: msg.content.length > 500 ? msg.content.substring(0, 500) : msg.content,
+        timestamp: msg.timestamp,
+        truncated: msg.truncated || msg.content.length > 500,
+        correlation_id: msg.correlation_id,
+      };
+    });
 
     // Get peer messages if peerManager is available
     let formattedPeerMessages: Array<{
@@ -586,6 +588,7 @@ export function createMCPServer(
     const entries: Array<{
       type: "agent" | "task";
       id: string;
+      name?: string;
       summary: string;
       state?: string;
       status?: string;
@@ -612,6 +615,7 @@ export function createMCPServer(
         agents = agents.filter(
           (a) =>
             a.id.toLowerCase().includes(search) ||
+            a.name?.toLowerCase().includes(search) ||
             a.task?.toLowerCase().includes(search)
         );
       }
@@ -620,6 +624,7 @@ export function createMCPServer(
         entries.push({
           type: "agent",
           id: agent.id,
+          name: agent.name,
           summary: agent.task ?? "No task description",
           state: agent.state,
         });
@@ -703,6 +708,7 @@ export function createMCPServer(
 
         return {
           agent_id: node.agent.id,
+          name: node.agent.name,
           task: node.agent.task ?? "No task",
           state: node.agent.state,
           children: shouldIncludeChildren
@@ -772,6 +778,7 @@ export function createMCPServer(
             type: "text" as const,
             text: JSON.stringify({
               id: agent.id,
+              name: agent.name,
               session_id: agent.session_id,
               task: agent.task ?? "No task",
               state: agent.state,
@@ -817,7 +824,7 @@ export function createMCPServer(
     }
 
     // Collect all agents that will be stopped (target + descendants)
-    const stoppedAgents: AgentId[] = [];
+    const stoppedAgents: Array<{ agent_id: AgentId; name?: string }> = [];
 
     async function stopRecursive(agentId: AgentId): Promise<void> {
       const agent = agentManager.get(agentId);
@@ -829,9 +836,10 @@ export function createMCPServer(
         await stopRecursive(child.id);
       }
 
-      // Stop this agent
+      // Capture name before stopping
+      const agentName = agent.name;
       await agentManager.terminate(agentId, args.reason ?? "cancelled");
-      stoppedAgents.push(agentId);
+      stoppedAgents.push({ agent_id: agentId, name: agentName });
     }
 
     await stopRecursive(args.agent_id);
@@ -850,85 +858,6 @@ export function createMCPServer(
     });
   }
 
-  // ─────────────────────────────────────────────────────────────────
-  // Tool: create_task (requires task.create capability)
-  // ─────────────────────────────────────────────────────────────────
-
-  if (shouldRegisterTool("create_task")) {
-    server.registerTool("create_task", {
-      description: "Create a new task",
-      inputSchema: CreateTaskSchema,
-    }, async (args) => {
-      try {
-        const task = taskManager.create({
-          description: args.description,
-          created_by: context.agent_id,
-          parent_task: args.parent_task,
-          inputs: args.inputs,
-        });
-
-        return {
-          content: [
-            {
-              type: "text" as const,
-              text: JSON.stringify({
-                task_id: task.id,
-              }),
-            },
-          ],
-        };
-      } catch (error) {
-        throw new MCPToolError(
-          `Failed to create task: ${error}`,
-          "INVALID_INPUT"
-        );
-      }
-    });
-  }
-
-  // ─────────────────────────────────────────────────────────────────
-  // Tool: get_task (always allowed - observability)
-  // ─────────────────────────────────────────────────────────────────
-
-  if (shouldRegisterTool("get_task")) {
-    server.registerTool("get_task", {
-      description: "Get details of a specific task",
-      inputSchema: GetTaskSchema,
-    }, async (args) => {
-      const task = taskManager.get(args.task_id);
-      if (!task) {
-        throw new MCPToolError(
-          `Task not found: ${args.task_id}`,
-          "TASK_NOT_FOUND"
-        );
-      }
-
-      // Use completed_at, started_at, or created_at as last update
-      const updatedAt = task.completed_at ?? task.started_at ?? task.created_at;
-
-      return {
-        content: [
-          {
-            type: "text" as const,
-            text: JSON.stringify({
-              id: task.id,
-              description: task.description,
-              status: task.status,
-              assigned_agent: task.assigned_agent,
-              parent_task: task.parent_task,
-              subtasks: task.subtasks ?? [],
-              inputs: task.inputs,
-              outputs: task.outputs,
-              artifacts: task.artifacts,
-              created_at: task.created_at,
-              updated_at: updatedAt,
-            }),
-          },
-        ],
-      };
-    });
-  }
-
   // ─────────────────────────────────────────────────────────────────
   // Tool: send_peer_message (requires msg.send capability)
   // ─────────────────────────────────────────────────────────────────
@@ -1302,3 +1231,165 @@ export function createMCPServer(
     close,
   };
 }
+
+// ─────────────────────────────────────────────────────────────────
+// Thin-Client Factory (MAP WebSocket mode)
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Type for the mapCall function used in thin-client mode.
+ */
+export type MapCallFn = <T = unknown>(
+  method: string,
+  params?: unknown,
+  options?: { timeoutMs?: number }
+) => Promise<T>;
+
+/**
+ * Creates a thin-client MCP server where every tool handler calls
+ * the main server via MAP WebSocket RPC instead of using local services.
+ *
+ * Tool schemas, descriptions, and role filtering remain the same.
+ * Only the handler bodies change — they forward to `_macro/mcp/*` extensions.
+ */
+export function createMCPServerThinClient(
+  context: ToolContext,
+  mapCallFn: MapCallFn,
+  config: MCPServerConfig = {}
+): MCPServerInstance {
+  const { name = "macro-agent-mcp", version = "1.0.0" } = config;
+
+  const server = new McpServer(
+    { name, version },
+    { capabilities: { tools: {} } }
+  );
+
+  /**
+   * Helper: wrap args with agent context for the bridge handler.
+   */
+  function withContext(args: Record<string, unknown>): Record<string, unknown> {
+    return { ...args, context };
+  }
+
+  /**
+   * Helper: create a tool handler that forwards to a MAP bridge extension.
+   */
+  function bridgeTool(
+    toolName: string,
+    schema: Record<string, z.ZodTypeAny>,
+    description: string,
+    mapMethod: string,
+    options?: { timeoutMs?: number }
+  ) {
+    server.registerTool(toolName, { description, inputSchema: schema }, async (args) => {
+      try {
+        const result = await mapCallFn(mapMethod, withContext(args as Record<string, unknown>), options);
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(result) }],
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new MCPToolError(`${toolName} failed: ${message}`, "ROUTING_FAILED");
+      }
+    });
+  }
+
+  // Register all tools pointing to their _macro/mcp/* bridge counterparts
+
+  bridgeTool("spawn_agent", SpawnAgentSchema, "Spawn a child agent to work on a subtask",
+    "_macro/mcp/spawn_agent");
+
+  bridgeTool("emit_status", EmitStatusSchema, "Report a status milestone (started, checkpoint, completed, failed, blocked)",
+    "_macro/mcp/emit_status");
+
+  bridgeTool("send_message", SendMessageSchema, "Send a message to another agent, task, or topic",
+    "_macro/mcp/send_message");
+
+  bridgeTool("check_messages", CheckMessagesSchema, "Check pending messages in your inbox",
+    "_macro/mcp/check_messages");
+
+  bridgeTool("query_index", QueryIndexSchema, "Search for agents and tasks",
+    "_macro/mcp/query_index");
+
+  bridgeTool("get_hierarchy", GetHierarchySchema, "View the agent hierarchy tree",
+    "_macro/mcp/get_hierarchy");
+
+  bridgeTool("get_agent_summary", GetAgentSummarySchema, "Get detailed summary of a specific agent",
+    "_macro/mcp/get_agent_summary");
+
+  bridgeTool("stop_agent", StopAgentSchema, "Stop a child agent in your subtree",
+    "_macro/mcp/stop_agent");
+
+  bridgeTool("done", DoneSchema, DONE_TOOL_INFO.description,
+    "_macro/mcp/done");
+
+  bridgeTool("inject_context", InjectContextSchema, INJECT_CONTEXT_TOOL_INFO.description,
+    "_macro/mcp/inject_context");
+
+  bridgeTool("wait_for_activity", WaitForActivitySchema, WAIT_FOR_ACTIVITY_TOOL_INFO.description,
+    "_macro/mcp/wait_for_activity", { timeoutMs: 65000 }); // Extra buffer for long-poll
+
+  bridgeTool("claim_task", ClaimTaskSchema, CLAIM_TASK_TOOL_INFO.description,
+    "_macro/mcp/claim_task");
+
+  bridgeTool("unclaim_task", UnclaimTaskSchema, UNCLAIM_TASK_TOOL_INFO.description,
+    "_macro/mcp/unclaim_task");
+
+  bridgeTool("list_claimable_tasks", ListClaimableTasksSchema, LIST_CLAIMABLE_TASKS_TOOL_INFO.description,
+    "_macro/mcp/list_claimable_tasks");
+
+  bridgeTool("send_peer_message", SendPeerMessageSchema, "Send a fire-and-forget message to another macro-agent (peer)",
+    "_macro/mcp/send_peer_message");
+
+  bridgeTool("send_peer_request", SendPeerRequestSchema, "Send a request to another macro-agent (peer) and wait for response",
+    "_macro/mcp/send_peer_request");
+
+  bridgeTool("respond_to_peer_request", RespondToPeerRequestSchema, "Respond to an incoming peer request",
+    "_macro/mcp/respond_to_peer_request");
+
+  // ─────────────────────────────────────────────────────────────────
+  // Server Lifecycle
+  // ─────────────────────────────────────────────────────────────────
+
+  let transport: StdioServerTransport | null = null;
+
+  async function start(): Promise<void> {
+    // Discover dynamic task tools from the server before connecting.
+    // This ensures we only register tools the server actually supports
+    // (e.g. memory backend = 4 tools, OpenTasks = 7 tools, none = 0).
+    try {
+      const result = await mapCallFn<{ tools: Array<{ name: string; description: string }> }>(
+        "_macro/mcp/task_tools_list",
+        withContext({})
+      );
+
+      if (result?.tools?.length > 0) {
+        const DynamicTaskParamsSchema = {
+          params: z.record(z.string(), z.unknown()).optional()
+            .describe("Tool parameters (validated by the server-side handler)"),
+        };
+
+        for (const tool of result.tools) {
+          bridgeTool(tool.name, DynamicTaskParamsSchema, tool.description,
+            `_macro/mcp/task_tool/${tool.name}`);
+        }
+        debugLog(`[MCP] Registered ${result.tools.length} dynamic task tools from server`);
+      }
+    } catch (error) {
+      // Server may not support task tools — continue without them
+      debugLog(`[MCP] Failed to discover task tools: ${error instanceof Error ? error.message : error}`);
+    }
+
+    transport = new StdioServerTransport();
+    await server.connect(transport);
+  }
+
+  async function close(): Promise<void> {
+    if (transport) {
+      await server.close();
+      transport = null;
+    }
+  }
+
+  return { server, start, close };
+}

package/src/mcp/types.ts

@@ -196,6 +196,7 @@ export interface GetTaskInput {
  */
 export interface SpawnAgentOutput {
   agent_id: AgentId;
+  name?: string;
   task_id: TaskId;
   session_id: string;
 }
@@ -223,6 +224,7 @@ export interface CheckMessagesOutput {
   messages: Array<{
     id: string;
     from: AgentId;
+    from_name?: string;
     content: string;
     timestamp: number;
     truncated: boolean;
@@ -239,6 +241,7 @@ export interface QueryIndexOutput {
   entries: Array<{
     type: "agent" | "task";
     id: string;
+    name?: string;
     summary: string;
     state?: string;
     status?: string;
@@ -258,6 +261,7 @@ export interface GetHierarchyOutput {
 
 export interface HierarchyNode {
   agent_id: AgentId;
+  name?: string;
   task: string;
   state: string;
   children: HierarchyNode[];
@@ -268,6 +272,7 @@ export interface HierarchyNode {
  */
 export interface GetAgentSummaryOutput {
   id: AgentId;
+  name?: string;
   session_id: string;
   task: string;
   state: string;
@@ -286,7 +291,7 @@ export interface GetAgentSummaryOutput {
  */
 export interface StopAgentOutput {
   success: boolean;
-  stopped_agents: AgentId[];
+  stopped_agents: Array<{ agent_id: AgentId; name?: string }>;
 }
 
 /**

package/src/metrics/metrics.ts

@@ -186,7 +186,7 @@ export function getUtilizationMetrics(
     after: windowStart,
   });
   const terminateEvents = eventStore.query({
-    type: "terminate",
+    type: "stop",
     after: windowStart,
   });
 

package/src/monitor/__tests__/stale-agent-flow.integration.test.ts

@@ -262,7 +262,7 @@ describe("STALE_AGENT Flow Integration", () => {
 
       // Terminate the worker
       eventStore.emit({
-        type: "terminate",
+        type: "stop",
         source: { agent_id: workerId },
         payload: {
           agent_id: workerId,

package/src/roles/__tests__/config-loader.test.ts

@@ -65,20 +65,20 @@ describe("Role Config Loader", () => {
     it("CONFIG-PATH-01: getProjectConfigPath returns correct path", () => {
       const projectPath = "/my/project";
       const configPath = getProjectConfigPath(projectPath);
-      expect(configPath).toBe("/my/project/.macro-agent/roles.json");
+      expect(configPath).toBe("/my/project/.multiagent/roles.json");
     });
 
     it("CONFIG-PATH-02: getProjectConfigPath uses cwd when no path provided", () => {
       const configPath = getProjectConfigPath();
       expect(configPath).toBe(
-        path.join(process.cwd(), ".macro-agent", "roles.json")
+        path.join(process.cwd(), ".multiagent", "roles.json")
       );
     });
 
     it("CONFIG-PATH-03: getUserConfigPath returns path in home directory", () => {
       const configPath = getUserConfigPath();
       expect(configPath).toBe(
-        path.join(os.homedir(), ".macro-agent", "roles.json")
+        path.join(os.homedir(), ".multiagent", "roles.json")
       );
     });
   });
@@ -260,7 +260,7 @@ describe("Role Config Loader", () => {
   describe("Project/User Config Loading", () => {
     it("CONFIG-PROJECT-01: loadProjectConfig uses correct path", () => {
       const projectPath = tempDir;
-      const configDir = path.join(projectPath, ".macro-agent");
+      const configDir = path.join(projectPath, ".multiagent");
       fs.mkdirSync(configDir, { recursive: true });
 
       const configPath = path.join(configDir, "roles.json");
@@ -280,7 +280,7 @@ describe("Role Config Loader", () => {
 
     it("CONFIG-ALL-01: loadAllConfigs combines user and project configs", () => {
       // Create project config
-      const projectConfigDir = path.join(tempDir, "project", ".macro-agent");
+      const projectConfigDir = path.join(tempDir, "project", ".multiagent");
       fs.mkdirSync(projectConfigDir, { recursive: true });
       writeConfigFile(path.join(projectConfigDir, "roles.json"), {
         roles: {
@@ -289,7 +289,7 @@ describe("Role Config Loader", () => {
       });
 
       // Create user config
-      const userConfigDir = path.join(tempDir, "user", ".macro-agent");
+      const userConfigDir = path.join(tempDir, "user", ".multiagent");
       fs.mkdirSync(userConfigDir, { recursive: true });
       writeConfigFile(path.join(userConfigDir, "roles.json"), {
         roles: {
@@ -363,7 +363,7 @@ describe("Role Config Loader", () => {
 
     it("CONFIG-REG-03: Registry with autoLoad loads configs on construction", () => {
       // Create project config
-      const projectConfigDir = path.join(tempDir, ".macro-agent");
+      const projectConfigDir = path.join(tempDir, ".multiagent");
       fs.mkdirSync(projectConfigDir, { recursive: true });
       writeConfigFile(path.join(projectConfigDir, "roles.json"), {
         roles: {