macro-agent 0.2.4 → 0.2.5

package/src/agent/types.ts

@@ -202,15 +202,36 @@ export interface AgentConfig {
 }
 
 /**
- * MCP server configuration
+ * MCP server configuration.
+ *
+ * A discriminated union over transport. The legacy stdio shape (no `type`,
+ * or `type: "stdio"`) is preserved byte-for-byte; new `http`/`sse` variants
+ * carry a `url` + optional `headers` instead of a `command`. These map
+ * directly onto the ACP wire's `McpServerStdio` / `McpServerHttp` /
+ * `McpServerSse` shapes (see acp-factory `createSession({ mcpServers })`).
  */
-export interface MCPServerConfig {
+export type MCPServerConfig = MCPServerStdioConfig | MCPServerHttpConfig;
+
+/** Stdio transport (legacy default — preserved for M0 compatibility). */
+export interface MCPServerStdioConfig {
   name: string;
+  /** Optional transport discriminant; absent means stdio. */
+  type?: "stdio";
   command: string;
   args?: string[];
   env?: Record<string, string>;
 }
 
+/** HTTP (streamable-http) or SSE transport for a remote MCP server. */
+export interface MCPServerHttpConfig {
+  name: string;
+  type: "http" | "sse";
+  /** URL to the remote MCP server. */
+  url: string;
+  /** HTTP headers to set on requests to the server. */
+  headers?: Record<string, string>;
+}
+
 // ─────────────────────────────────────────────────────────────────
 // Spawned Agent Result
 // ─────────────────────────────────────────────────────────────────

package/src/cognitive/__tests__/macro-agent-backend.test.ts

@@ -6,16 +6,23 @@ import type { RoleRegistry, RoleDefinition } from "../../roles/types.js";
 
 // ── Mock Helpers ─────────────────────────────────────────────────
 
+// Stand-in for the built-in "generic" role the REAL DefaultRoleRegistry falls
+// back to. Used by resolveRole() below so the mock matches production
+// semantics (resolveRole NEVER throws on a miss).
+const GENERIC_FALLBACK = { name: "generic" } as unknown as RoleDefinition;
+
 function createMockRoleRegistry(): RoleRegistry {
   const roles = new Map<string, RoleDefinition>();
   return {
     registerRole: vi.fn((role: RoleDefinition) => {
       roles.set(role.name, role);
     }),
+    // MUST mirror the real DefaultRoleRegistry.resolveRole(): on an unknown
+    // role it does NOT throw — it logs and returns the GenericRole fallback.
+    // A throwing mock (the old behavior) masked the constructor bug where
+    // analyst registration was gated on resolveRole() throwing.
     resolveRole: vi.fn((name: string) => {
-      const role = roles.get(name);
-      if (!role) throw new Error(`Role not found: ${name}`);
-      return role;
+      return roles.get(name) ?? GENERIC_FALLBACK;
     }),
     getRole: vi.fn((name: string) => roles.get(name)),
     hasCapability: vi.fn(() => true),
@@ -92,10 +99,33 @@ describe("MacroAgentBackend", () => {
       );
     });
 
+    it("registers analyst against a real-semantics registry (resolveRole does NOT throw on miss)", () => {
+      // Regression guard for the live Arm-B bug: the constructor must NOT rely
+      // on resolveRole() throwing to detect a missing analyst role. With a
+      // non-throwing registry (production behavior), analyst must still be
+      // registered, and resolveRole("analyst") must then return analyst —
+      // NOT fall back to "generic" (which would give the spawned agent
+      // all built-in tools + own-workspace + persistent lifecycle, exactly
+      // the conditions that produced 0 env-tool calls and a 600s timeout).
+      const registry = createMockRoleRegistry();
+      const am = createMockAgentManager({
+        getRoleRegistry: vi.fn().mockReturnValue(registry),
+      });
+
+      new MacroAgentBackend(am);
+
+      expect(registry.registerRole).toHaveBeenCalledWith(
+        expect.objectContaining({ name: "analyst" }),
+      );
+      // After construction, the role must resolve to analyst, not generic.
+      expect(registry.resolveRole("analyst").name).toBe("analyst");
+    });
+
     it("skips registration if analyst role already exists", () => {
       const registry = createMockRoleRegistry();
-      // Pre-register analyst
-      (registry.resolveRole as ReturnType<typeof vi.fn>).mockReturnValue({
+      // Pre-register analyst via getRole (the exact-match existence check the
+      // constructor now uses), mirroring the real registry's API.
+      (registry.getRole as ReturnType<typeof vi.fn>).mockReturnValue({
         name: "analyst",
       });
 
@@ -203,6 +233,129 @@ describe("MacroAgentBackend", () => {
       );
     });
 
+    it("forwards mcpServers into the raw macro spawn config (Arm B chain)", async () => {
+      const mcpServers = [
+        {
+          name: "tauenv",
+          command: "/venv/bin/python",
+          args: ["-m", "autonomation_tau_bench.mcp_env", "--split", "airline"],
+          env: { TAU_REWARD_FILE: "/tmp/reward.json" },
+        },
+      ];
+
+      await backend.spawn({
+        agentType: "claude-code",
+        task: { description: "handle the customer" },
+        mcpServers,
+      });
+
+      expect(agentManager.spawn).toHaveBeenCalledWith(
+        expect.objectContaining({
+          config: expect.objectContaining({ mcpServers }),
+        }),
+      );
+    });
+
+    it("forwards both env and mcpServers together into the raw spawn config", async () => {
+      const mcpServers = [
+        { name: "tauenv", command: "/venv/bin/python", args: ["-m", "x"] },
+      ];
+
+      await backend.spawn({
+        agentType: "claude-code",
+        task: { description: "test" },
+        env: { TAU_REWARD_FILE: "/tmp/r.json" },
+        mcpServers,
+      });
+
+      expect(agentManager.spawn).toHaveBeenCalledWith(
+        expect.objectContaining({
+          config: {
+            env: { TAU_REWARD_FILE: "/tmp/r.json" },
+            mcpServers,
+          },
+        }),
+      );
+    });
+
+    it("invokes beforeSpawn BEFORE driving the agent (per-attempt reset hook)", async () => {
+      // beforeSpawn must run before agentManager.spawn so the env subprocess /
+      // reward sink is reset for THIS attempt. We assert ordering by recording
+      // the call sequence.
+      const order: string[] = [];
+      const beforeSpawn = vi.fn(() => {
+        order.push("beforeSpawn");
+      });
+      const am = createMockAgentManager({
+        spawn: vi.fn().mockImplementation(async () => {
+          order.push("spawn");
+          return { id: "agent_test123", session_id: "session_test123" };
+        }),
+      });
+      const b = new MacroAgentBackend(am);
+
+      await b.spawn({
+        agentType: "claude-code",
+        task: { description: "tau episode" },
+        beforeSpawn,
+      });
+
+      expect(beforeSpawn).toHaveBeenCalledTimes(1);
+      expect(order).toEqual(["beforeSpawn", "spawn"]);
+    });
+
+    it("passes completionSignal into promptUntilDone (S1 threading)", async () => {
+      const completionSignal = vi.fn(() => false);
+
+      await backend.spawn({
+        agentType: "claude-code",
+        task: { description: "tau episode" },
+        completionSignal,
+      });
+
+      await vi.waitFor(() => {
+        expect(agentManager.promptUntilDone).toHaveBeenCalledWith(
+          expect.any(String),
+          expect.any(String),
+          expect.objectContaining({ isComplete: completionSignal }),
+        );
+      });
+    });
+
+    it("treats completedExternally as a success (session → completed) even without done()", async () => {
+      const am = createMockAgentManager({
+        promptUntilDone: vi.fn().mockResolvedValue({
+          doneCalled: false,
+          completedExternally: true,
+          updates: [],
+        }),
+      });
+      const b = new MacroAgentBackend(am);
+
+      const session = await b.spawn({
+        agentType: "claude-code",
+        task: { description: "tau episode" },
+        completionSignal: () => true,
+      });
+
+      await vi.waitFor(async () => {
+        const s = await b.getSession(session.id);
+        expect(s!.state).toBe("completed");
+        expect(s!.error).toBeUndefined();
+      });
+    });
+
+    it("passes config: undefined when neither env nor mcpServers set (M0 back-compat)", async () => {
+      await backend.spawn({
+        agentType: "claude-code",
+        task: { description: "test" },
+      });
+
+      expect(agentManager.spawn).toHaveBeenCalledWith(
+        expect.objectContaining({ config: undefined }),
+      );
+    });
+
     it("stores macro agent ID in session metadata", async () => {
       const session = await backend.spawn({
         agentType: "claude-code",

package/src/cognitive/macro-agent-backend.ts

@@ -57,11 +57,14 @@ export class MacroAgentBackend {
     this.onSessionComplete = config?.onSessionComplete;
     this.inboxAdapter = config?.inboxAdapter;
 
-    // Register analyst role if not already present
+    // Register analyst role if not already present. Use getRole() (exact match,
+    // returns undefined on a miss) rather than resolveRole(): the real
+    // DefaultRoleRegistry.resolveRole() never throws on an unknown role — it
+    // logs "Role 'analyst' not found, falling back to 'generic'" and returns
+    // GenericRole — so a resolveRole()/try-catch guard would silently skip
+    // registration and every spawn would fall back to GenericRole.
     const registry = this.agentManager.getRoleRegistry();
-    try {
-      registry.resolveRole("analyst");
-    } catch {
+    if (!registry.getRole("analyst")) {
       registry.registerRole(AnalystRole);
     }
   }
@@ -189,6 +192,29 @@ export class MacroAgentBackend {
     config: CognitiveAgentSpawnConfig,
     taskId?: string,
   ): Promise<CognitiveAgentSession> {
+    // Per-attempt reset hook — runs BEFORE the agent is driven so each attempt
+    // (initial spawn AND each refinement re-spawn) starts from a clean external
+    // state (e.g. a deleted benchmark reward sink). Best-effort: a failing hook
+    // must not abort the spawn.
+    if (config.beforeSpawn) {
+      try {
+        await config.beforeSpawn();
+      } catch {
+        // Best effort — reset failure should not block the spawn.
+      }
+    }
+
+    // Forward env and MCP servers into the raw macro spawn's `config`. Build
+    // the AgentConfig only when at least one field is present so non-MCP,
+    // non-env spawns keep passing `config: undefined` (byte-identical to M0).
+    const rawConfig =
+      config.env || config.mcpServers
+        ? {
+            ...(config.env ? { env: config.env } : {}),
+            ...(config.mcpServers ? { mcpServers: config.mcpServers } : {}),
+          }
+        : undefined;
+
     const spawned = await this.agentManager.spawn({
       task: config.task.description,
       task_id: taskId,
@@ -197,7 +223,7 @@ export class MacroAgentBackend {
         ? this.config.coordinatorAgentId
         : null,
       cwd: config.cwd,
-      config: config.env ? { env: config.env } : undefined,
+      config: rawConfig,
       customPrompt: config.systemPromptAdditions,
     });
 
@@ -319,12 +345,18 @@ export class MacroAgentBackend {
             updateSessionFromEvent(session, update);
             config.onMessage?.(session.messages[session.messages.length - 1]!);
           },
+          // Forward the caller's completion predicate (e.g. a benchmark reward
+          // sink wrote done:true). When it fires, promptUntilDone returns
+          // completedExternally:true instead of exhausting maxFollowUps.
+          isComplete: config.completionSignal,
         },
       );
 
       if (session.state === "running") {
-        session.state = result.doneCalled ? "completed" : "failed";
-        if (!result.doneCalled) session.error = "Agent did not call done()";
+        // External completion (predicate) is a success path, same as done().
+        const completed = result.doneCalled || result.completedExternally;
+        session.state = completed ? "completed" : "failed";
+        if (!completed) session.error = "Agent did not call done()";
         session.endTime = new Date();
         session.result = result.doneStatus;
       }

package/src/cognitive/types.ts

@@ -11,6 +11,7 @@
 
 import type { AgentId } from "../store/types/index.js";
 import type { TasksAdapter, InboxAdapter } from "../adapters/types.js";
+import type { MCPServerConfig } from "../agent/types.js";
 
 // ─────────────────────────────────────────────────────────────────
 // Agent Session Types (matches cognitive-core/src/runtime/types.ts)
@@ -78,6 +79,29 @@ export interface CognitiveAgentSpawnConfig {
   cwd?: string;
   timeout?: number;
   onMessage?: (message: CognitiveAgentMessage) => void;
+  /**
+   * MCP servers to mount on the spawned agent (e.g. a per-task tau-env
+   * server). Forwarded verbatim into the macro `AgentManager.spawn`'s
+   * `config.mcpServers`. Optional / back-compat: non-MCP spawns are
+   * unaffected. Matches macro `AgentConfig.mcpServers` (the stdio/http union).
+   */
+  mcpServers?: MCPServerConfig[];
+  /**
+   * Optional completion predicate forwarded into `promptUntilDone`. When it
+   * returns true the agent loop completes externally (without the macro done()
+   * tool) — e.g. a benchmark env wrote its reward sink with done:true. Generic:
+   * the backend has no knowledge of what it reads. Back-compat: absent →
+   * unchanged.
+   */
+  completionSignal?: () => boolean | Promise<boolean>;
+  /**
+   * Optional per-attempt hook invoked BEFORE the agent is driven (and again
+   * before each refinement re-spawn, since refine() spreads this config). Used
+   * to reset per-attempt external state — e.g. delete a benchmark reward sink so
+   * each attempt only sees its OWN completion signal. Back-compat: absent →
+   * unchanged.
+   */
+  beforeSpawn?: () => void | Promise<void>;
 }
 
 // ─────────────────────────────────────────────────────────────────

package/src/index.ts

@@ -55,6 +55,8 @@ export {
   AgentManagerError,
   type AgentManagerErrorCode,
   type MCPServerConfig as AgentMCPServerConfig,
+  type MCPServerStdioConfig as AgentMCPServerStdioConfig,
+  type MCPServerHttpConfig as AgentMCPServerHttpConfig,
   type AgentConfig as SpawnAgentConfig,
 } from './agent/types.js';
 

package/src/map/__tests__/mail-bridge.test.ts

@@ -67,11 +67,12 @@ describe("setupMailBridge", () => {
     );
   });
 
-  it("drops non-JSON turns silently", async () => {
+  it("delivers plain-text turns into the inbox as a text message", async () => {
     const logs: string[] = [];
     await setupMailBridge({
       connection: conn,
       inboxAdapter: inbox as any,
+      dispatcherAgentId: "dispatcher:host:1234:abc",
       log: (m) => logs.push(m),
     });
 
@@ -81,10 +82,46 @@ describe("setupMailBridge", () => {
       participant_id: "some-agent",
       content_type: "text/plain",
       content: "hello world",
+      thread_id: "thread-xyz",
+      importance: "high",
+    });
+
+    expect(inbox.send).toHaveBeenCalledOnce();
+    const [from, to, content, opts] = inbox.send.mock.calls[0];
+    expect(from).toBe("some-agent");
+    expect(to).toBe("dispatcher:host:1234:abc");
+    // Delivered as a text message that normalizeContent passes through,
+    // carrying the conversation id for reply threading.
+    expect(content).toMatchObject({
+      type: "text",
+      text: "hello world",
+      _conversationId: "conv-1",
+    });
+    // Not shaped as a work envelope — the classifier must not match it.
+    expect(content).not.toHaveProperty("schema");
+    expect(opts?.threadTag).toBe("thread-xyz");
+    expect(opts?.importance).toBe("high");
+    expect(logs.some((l) => l.includes("Forwarded text turn"))).toBe(true);
+  });
+
+  it("skips empty / whitespace-only text turns", async () => {
+    const logs: string[] = [];
+    await setupMailBridge({
+      connection: conn,
+      inboxAdapter: inbox as any,
+      log: (m) => logs.push(m),
+    });
+
+    await conn._fire({
+      conversation_id: "conv-empty",
+      turn_id: "turn-empty",
+      participant_id: "some-agent",
+      content_type: "text/plain",
+      content: "   ",
     });
 
     expect(inbox.send).not.toHaveBeenCalled();
-    expect(logs.some((l) => l.includes("Dropping"))).toBe(true);
+    expect(logs.some((l) => l.includes("Skipping empty"))).toBe(true);
   });
 
   describe("with dispatcherAgentId", () => {

package/src/map/mail-bridge.ts

@@ -13,6 +13,13 @@
  *   2. The classifier recognizes `x-dispatch/work` schema and routes the
  *      prompt to a worker agent (existing or freshly spawned).
  *
+ * Turns that aren't structured `x-dispatch/work` envelopes (e.g.
+ * natural-language spec-discussion replies) are delivered into the inbox as
+ * plain-text messages instead of being dropped. The classifier won't match
+ * them (so no worker spawns), but the delivery still wakes the agent via
+ * TriggerSystemV2 (importance → wake action) so it reads the reply on its
+ * next turn.
+ *
  * Without this bridge, hub-side mail turns never reach macro-agent's
  * dispatcher. The MessagePort is wired to local inbox events only.
  */
@@ -135,14 +142,64 @@ export async function setupMailBridge(
     metadata: { source: "openhive-mail-forward" },
   });
 
+  // Importance derivation shared by the structured-work and plain-text
+  // delivery paths. Defaults to "normal" when the hub doesn't tag the turn.
+  const VALID_IMPORTANCE = ["low", "normal", "high", "urgent"];
+  const deriveImportance = (
+    value: string | undefined,
+  ): "low" | "normal" | "high" | "urgent" =>
+    typeof value === "string" && VALID_IMPORTANCE.includes(value)
+      ? (value as "low" | "normal" | "high" | "urgent")
+      : "normal";
+
   const handler = async (params: unknown): Promise<void> => {
     const turn = (params ?? {}) as MailTurnReceivedParams;
+    const wireImportance = deriveImportance(turn.importance);
     const raw = parseTurnContent(turn.content, turn.content_type);
+
+    // Plain-text (non-JSON) turn — e.g. a natural-language spec-discussion
+    // reply. Previously dropped; now delivered into the local inbox as a
+    // text message so the agent wakes (TriggerSystemV2 maps importance to a
+    // wake action) and reads it on its next turn. The dispatcher's
+    // MessagePort classifier won't match a text payload, so no worker is
+    // spawned — correct for a conversational message. The conversation id
+    // rides along (mirrors the structured path) so the agent's reply can be
+    // threaded back to the right hub conversation.
     if (!raw) {
-      log(
-        `[mail-bridge] Dropping non-JSON turn (conv=${turn.conversation_id ?? "?"} ` +
-          `participant=${turn.participant_id ?? "?"})`,
-      );
+      const text = typeof turn.content === "string" ? turn.content : "";
+      if (!text.trim()) {
+        log(
+          `[mail-bridge] Skipping empty/non-text turn (conv=${turn.conversation_id ?? "?"} ` +
+            `participant=${turn.participant_id ?? "?"})`,
+        );
+        return;
+      }
+      const textContent: Record<string, unknown> = {
+        type: "text",
+        text,
+        ...(turn.conversation_id
+          ? { _conversationId: turn.conversation_id }
+          : {}),
+      };
+      try {
+        await inboxAdapter.send(
+          turn.participant_id ?? "openhive-hub",
+          recipientId,
+          textContent as never,
+          {
+            threadTag: turn.thread_id,
+            importance: wireImportance,
+          },
+        );
+        log(
+          `[mail-bridge] Forwarded text turn ${turn.turn_id ?? "?"} into local inbox`,
+        );
+      } catch (err) {
+        log(
+          `[mail-bridge] Forward failed for text turn ${turn.turn_id ?? "?"}: ` +
+            `${(err as Error).message}`,
+        );
+      }
       return;
     }
 
@@ -172,15 +229,6 @@ export async function setupMailBridge(
       ...(turn.conversation_id ? { _conversationId: turn.conversation_id } : {}),
     };
 
-    // Derive importance from the hub's wire params. Default to "normal"
-    // when the hub doesn't tag the turn (backward compat).
-    const VALID_IMPORTANCE = ["low", "normal", "high", "urgent"];
-    const wireImportance =
-      typeof turn.importance === "string" &&
-      VALID_IMPORTANCE.includes(turn.importance)
-        ? (turn.importance as "low" | "normal" | "high" | "urgent")
-        : "normal";
-
     try {
       await inboxAdapter.send(
         turn.participant_id ?? "openhive-hub",

package/src/teams/team-runtime-v2.ts

@@ -532,12 +532,35 @@ export class TeamRuntimeV2 {
           ...options.config,
           mcpServers: [
             ...(options.config?.mcpServers ?? []),
-            ...teamMcpServers.map((s) => ({
-              name: s.name,
-              command: s.command,
-              args: s.args,
-              env: s.env,
-            })),
+            ...teamMcpServers.map((s) => {
+              // openteams' static McpServerEntry is stdio-only, but a
+              // resolved loadout entry may carry a remote transport
+              // (type/url/headers — see openteams McpProviderSpec). Pass
+              // those through unchanged so http/sse loadout servers reach
+              // the spawn conversion; otherwise emit the stdio shape.
+              const remote = s as unknown as {
+                type?: "stdio" | "http" | "sse";
+                url?: string;
+                headers?: Record<string, string>;
+              };
+              if (
+                (remote.type === "http" || remote.type === "sse") &&
+                remote.url
+              ) {
+                return {
+                  name: s.name,
+                  type: remote.type,
+                  url: remote.url,
+                  headers: remote.headers,
+                };
+              }
+              return {
+                name: s.name,
+                command: s.command,
+                args: s.args,
+                env: s.env,
+              };
+            }),
           ],
           env: {
             ...options.config?.env,