macro-agent 0.1.11 → 0.2.0

package/src/dispatch/__tests__/spawn-agent-handler.test.ts

@@ -0,0 +1,282 @@
+/**
+ * Unit tests for `handleDispatchSpawnAgent` — the MAP `dispatch/spawn-agent`
+ * request handler. All dependencies are mocked.
+ */
+
+import { describe, it, expect, beforeEach, vi, type MockedFunction } from "vitest";
+import {
+  handleDispatchSpawnAgent,
+  type SpawnAgentRequest,
+  type SpawnAgentHandlerDeps,
+} from "../spawn-agent-handler.js";
+import type { AgentManager } from "../../agent/agent-manager.js";
+
+// ─────────────────────────────────────────────────────────────────
+// Mock helpers
+// ─────────────────────────────────────────────────────────────────
+
+function makeAgentManager(spawnedId = "agent-spawn-1"): {
+  manager: Partial<AgentManager>;
+  spawnFn: MockedFunction<AgentManager["spawn"]>;
+} {
+  const spawnFn = vi.fn().mockResolvedValue({ id: spawnedId }) as unknown as MockedFunction<
+    AgentManager["spawn"]
+  >;
+  return {
+    manager: { spawn: spawnFn },
+    spawnFn,
+  };
+}
+
+function makeDeps(
+  am: ReturnType<typeof makeAgentManager>,
+  overrides: Partial<SpawnAgentHandlerDeps> = {},
+): SpawnAgentHandlerDeps & { logs: string[] } {
+  const logs: string[] = [];
+  return {
+    agentManager: am.manager as AgentManager,
+    log: (msg: string) => logs.push(msg),
+    ...overrides,
+    logs,
+  } as SpawnAgentHandlerDeps & { logs: string[] };
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Tests
+// ─────────────────────────────────────────────────────────────────
+
+describe("handleDispatchSpawnAgent", () => {
+  let am: ReturnType<typeof makeAgentManager>;
+
+  beforeEach(() => {
+    am = makeAgentManager("agent-spawn-1");
+  });
+
+  // ── Validation ───────────────────────────────────────────────
+
+  it("throws on missing role", async () => {
+    const deps = makeDeps(am);
+    const params = { cwd: "/tmp/work" } as SpawnAgentRequest;
+    await expect(handleDispatchSpawnAgent(params, deps)).rejects.toThrow(
+      /missing 'role'/,
+    );
+    expect(am.spawnFn).not.toHaveBeenCalled();
+  });
+
+  it("throws on lifecycle: 'reuse' (handler is fresh-only)", async () => {
+    const deps = makeDeps(am);
+    const params: SpawnAgentRequest = {
+      role: "coordinator",
+      cwd: "/tmp/work",
+      lifecycle: "reuse",
+    };
+    await expect(handleDispatchSpawnAgent(params, deps)).rejects.toThrow(
+      /lifecycle='reuse'/,
+    );
+    expect(am.spawnFn).not.toHaveBeenCalled();
+  });
+
+  it("proceeds with lifecycle: 'fresh'", async () => {
+    const deps = makeDeps(am);
+    const params: SpawnAgentRequest = {
+      role: "coordinator",
+      cwd: "/tmp/work",
+      lifecycle: "fresh",
+    };
+    const result = await handleDispatchSpawnAgent(params, deps);
+    expect(result).toEqual({ agentId: "agent-spawn-1" });
+    expect(am.spawnFn).toHaveBeenCalledOnce();
+  });
+
+  it("proceeds when lifecycle is omitted (defaults to fresh)", async () => {
+    const deps = makeDeps(am);
+    const params: SpawnAgentRequest = {
+      role: "coordinator",
+      cwd: "/tmp/work",
+    };
+    const result = await handleDispatchSpawnAgent(params, deps);
+    expect(result).toEqual({ agentId: "agent-spawn-1" });
+    expect(am.spawnFn).toHaveBeenCalledOnce();
+  });
+
+  // ── Spawn-options derivation ──────────────────────────────────
+
+  it("calls agentManager.spawn with options derived via loadoutToSpawnOptions", async () => {
+    const deps = makeDeps(am);
+    const params: SpawnAgentRequest = {
+      role: "coordinator",
+      cwd: "/tmp/work",
+      lifecycle: "fresh",
+      loadout: {
+        permissions: { deny: ["Bash(rm -rf:*)"] },
+        capabilities: ["editor"],
+      },
+      fullAutonomous: true,
+    };
+    await handleDispatchSpawnAgent(params, deps);
+
+    expect(am.spawnFn).toHaveBeenCalledOnce();
+    const spawnArgs = am.spawnFn.mock.calls[0][0];
+    expect(spawnArgs.role).toBe("coordinator");
+    expect(spawnArgs.cwd).toBe("/tmp/work");
+    expect(spawnArgs.parent).toBeNull();
+    expect(spawnArgs.isolatedSettings).toBe(true);
+    expect(spawnArgs.permissions).toEqual({
+      allow: [],
+      deny: ["Bash(rm -rf:*)"],
+      ask: [],
+    });
+    expect(spawnArgs.fullAutonomous).toBe(true);
+    expect(spawnArgs.capabilities).toEqual(["editor"]);
+  });
+
+  it("forwards params.cwd when present", async () => {
+    const deps = makeDeps(am);
+    const params: SpawnAgentRequest = {
+      role: "coordinator",
+      cwd: "/tmp/abc",
+    };
+    await handleDispatchSpawnAgent(params, deps);
+    const args = am.spawnFn.mock.calls[0][0];
+    expect(args.cwd).toBe("/tmp/abc");
+  });
+
+  it("omits cwd from spawn options when absent", async () => {
+    const deps = makeDeps(am);
+    const params = { role: "coordinator" } as SpawnAgentRequest;
+    await handleDispatchSpawnAgent(params, deps);
+    const args = am.spawnFn.mock.calls[0][0];
+    expect(Object.prototype.hasOwnProperty.call(args, "cwd")).toBe(false);
+  });
+
+  it("returns { agentId } from the spawned result", async () => {
+    am = makeAgentManager("custom-agent-id-42");
+    const deps = makeDeps(am);
+    const result = await handleDispatchSpawnAgent(
+      { role: "worker", cwd: "/tmp/x" },
+      deps,
+    );
+    expect(result).toEqual({ agentId: "custom-agent-id-42" });
+  });
+
+  // ── ACP-registration barrier ─────────────────────────────────
+
+  it("calls waitForAcpRegistration(agentId, 5000) when provided", async () => {
+    const waitForAcpRegistration = vi.fn().mockResolvedValue(true);
+    const deps = makeDeps(am, { waitForAcpRegistration });
+    await handleDispatchSpawnAgent(
+      { role: "coordinator", cwd: "/tmp/x" },
+      deps,
+    );
+    expect(waitForAcpRegistration).toHaveBeenCalledOnce();
+    expect(waitForAcpRegistration).toHaveBeenCalledWith("agent-spawn-1", 5_000);
+  });
+
+  it("tolerates waitForAcpRegistration timeout (logs warning, still returns agentId)", async () => {
+    const waitForAcpRegistration = vi.fn().mockResolvedValue(false);
+    const deps = makeDeps(am, { waitForAcpRegistration });
+    const result = await handleDispatchSpawnAgent(
+      { role: "coordinator", cwd: "/tmp/x" },
+      deps,
+    );
+    expect(result).toEqual({ agentId: "agent-spawn-1" });
+    expect(deps.logs.some((l) => l.includes("Warning: ACP registration not confirmed"))).toBe(
+      true,
+    );
+  });
+
+  it("calls waitForAcpRegistration even if it rejects (caught, no propagation)", async () => {
+    const waitForAcpRegistration = vi
+      .fn()
+      .mockRejectedValue(new Error("registration timeout"));
+    const deps = makeDeps(am, { waitForAcpRegistration });
+    const result = await handleDispatchSpawnAgent(
+      { role: "coordinator", cwd: "/tmp/x" },
+      deps,
+    );
+    expect(result).toEqual({ agentId: "agent-spawn-1" });
+    expect(waitForAcpRegistration).toHaveBeenCalledOnce();
+    // The rejection is treated as a non-confirmation → warning logged.
+    expect(deps.logs.some((l) => l.includes("Warning: ACP registration not confirmed"))).toBe(
+      true,
+    );
+  });
+
+  it("does not call waitForAcpRegistration when not provided", async () => {
+    const deps = makeDeps(am); // no waitForAcpRegistration
+    const result = await handleDispatchSpawnAgent(
+      { role: "coordinator", cwd: "/tmp/x" },
+      deps,
+    );
+    expect(result).toEqual({ agentId: "agent-spawn-1" });
+    // Just ensure we don't crash; nothing else to assert.
+  });
+
+  // ── fullAutonomous default ───────────────────────────────────
+
+  it("defaults fullAutonomous to true when params.fullAutonomous is omitted", async () => {
+    const deps = makeDeps(am);
+    const params: SpawnAgentRequest = {
+      role: "coordinator",
+      cwd: "/tmp/x",
+      loadout: { permissions: { ask: ["Write(*.env)"] } },
+    };
+    await handleDispatchSpawnAgent(params, deps);
+
+    const args = am.spawnFn.mock.calls[0][0];
+    expect(args.fullAutonomous).toBe(true);
+    expect(args.permissions).toEqual({
+      allow: [],
+      deny: [],
+      ask: ["Write(*.env)"],
+    });
+  });
+
+  it("respects explicit fullAutonomous: false from params", async () => {
+    const deps = makeDeps(am);
+    const params: SpawnAgentRequest = {
+      role: "coordinator",
+      cwd: "/tmp/x",
+      loadout: { permissions: { ask: ["Write(*.env)"] } },
+      fullAutonomous: false,
+    };
+    await handleDispatchSpawnAgent(params, deps);
+
+    const args = am.spawnFn.mock.calls[0][0];
+    expect(args.fullAutonomous).toBe(false);
+  });
+
+  // ── Task placeholder ─────────────────────────────────────────
+
+  it("uses params.task when provided", async () => {
+    const deps = makeDeps(am);
+    const params: SpawnAgentRequest = {
+      role: "coordinator",
+      cwd: "/tmp/x",
+      task: "Implement the widget",
+    };
+    await handleDispatchSpawnAgent(params, deps);
+    const args = am.spawnFn.mock.calls[0][0];
+    expect(args.task).toBe("Implement the widget");
+  });
+
+  it("applies the default task placeholder when params.task is omitted", async () => {
+    const deps = makeDeps(am);
+    const params: SpawnAgentRequest = { role: "coordinator", cwd: "/tmp/x" };
+    await handleDispatchSpawnAgent(params, deps);
+    const args = am.spawnFn.mock.calls[0][0];
+    expect(args.task).toBe("Awaiting dispatch (created by dispatch/spawn-agent)");
+  });
+
+  // ── isolatedSettings ─────────────────────────────────────────
+
+  it("always passes isolatedSettings: true to spawn", async () => {
+    const deps = makeDeps(am);
+    await handleDispatchSpawnAgent(
+      { role: "coordinator", cwd: "/tmp/x" },
+      deps,
+    );
+    const args = am.spawnFn.mock.calls[0][0];
+    expect(args.isolatedSettings).toBe(true);
+  });
+});

package/src/dispatch/loadout-translation.ts

@@ -0,0 +1,138 @@
+/**
+ * Loadout → SpawnAgentOptions translator (macro-agent)
+ *
+ * Single named function that converts the runtime-agnostic
+ * `MaterializedLoadout` wire payload into macro-agent-specific
+ * `SpawnAgentOptions`. Two callers:
+ *
+ *   - `mail-inbound-consumer` — for mail-routed dispatches (ACP+fresh
+ *     workers spawned per envelope)
+ *   - `dispatch/spawn-agent` MAP handler — for ACP-routed dispatches when
+ *     `lifecycle: 'fresh'`
+ *
+ * Both call sites pass the same shape; this function is the only place
+ * macro-agent-specific spawn vocabulary (`permissions`, `fullAutonomous`,
+ * `capabilities`) is derived from loadout fields. A future ACP runtime
+ * (codex, etc.) would implement its own translator with the same input
+ * shape and a different output shape.
+ *
+ * The wire shape (`MaterializedLoadout` subset) is documented in
+ * openhive-2 `docs/LOADOUTS_DESIGN.md` → "Channel 2 — `loadout` as a
+ * first-class wire concept".
+ */
+
+import type { SpawnAgentOptions } from "../agent/types.js";
+
+/**
+ * Wire shape — a strict subset of openhive's `MaterializedLoadout` that
+ * is meaningful to a runtime's spawn config. Skill content (`rendered`,
+ * `items`) and `promptAddendum` ride in the prompt body for both routes,
+ * so they aren't included here.
+ *
+ * Defined locally rather than imported from openhive to avoid a runtime
+ * dependency on the hub's source tree. Structural compatibility with
+ * `MaterializedLoadout` is what matters at the wire boundary.
+ */
+export interface WireLoadout {
+  permissions?: {
+    allow?: string[];
+    deny?: string[];
+    ask?: string[];
+  };
+  mcpProviders?: Array<{
+    name: string;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+  }>;
+  mcpScope?: Array<{ server: string; tools?: string[]; exclude?: string[] }>;
+  capabilities?: string[];
+}
+
+export interface TranslationContext {
+  /**
+   * Mail-inbound and other autonomous consumers set this true so `ask`
+   * rules collapse to `allow` (proceed without human round-trip).
+   * Non-autonomous spawns leave it false, collapsing `ask` → `deny`.
+   */
+  fullAutonomous?: boolean;
+}
+
+/**
+ * Translate a wire-shaped loadout into the subset of `SpawnAgentOptions`
+ * that macro-agent's `agentManager.spawn` consumes from loadout content.
+ *
+ * Returns a partial — the caller merges with required spawn fields
+ * (`task`, `task_id`, `role`, `parent`, `cwd`, `isolatedSettings`, etc.).
+ *
+ * Mappings:
+ *   loadout.permissions → SpawnAgentOptions.permissions (carried verbatim;
+ *     `ask` collapse is performed inside agentManager.spawn based on
+ *     fullAutonomous)
+ *   loadout.capabilities → SpawnAgentOptions.capabilities (forwarded)
+ *   loadout.mcpProviders → reserved (Phase 2 — not yet wired)
+ *   loadout.mcpScope → reserved (Phase 1 — not yet wired)
+ */
+export function loadoutToSpawnOptions(
+  loadout: WireLoadout | undefined,
+  ctx: TranslationContext = {},
+): Partial<SpawnAgentOptions> {
+  if (!loadout) return {};
+
+  const opts: Partial<SpawnAgentOptions> = {};
+
+  if (loadout.permissions && hasAnyRule(loadout.permissions)) {
+    opts.permissions = {
+      allow: loadout.permissions.allow ?? [],
+      deny: loadout.permissions.deny ?? [],
+      ask: loadout.permissions.ask ?? [],
+    };
+    opts.fullAutonomous = ctx.fullAutonomous ?? false;
+  }
+
+  if (loadout.capabilities?.length) {
+    opts.capabilities = [...loadout.capabilities];
+  }
+
+  return opts;
+}
+
+function hasAnyRule(p: WireLoadout["permissions"]): boolean {
+  if (!p) return false;
+  return (
+    (p.allow?.length ?? 0) +
+      (p.deny?.length ?? 0) +
+      (p.ask?.length ?? 0) >
+    0
+  );
+}
+
+/**
+ * Collapse a permissions block's `ask` rules based on the autonomous
+ * setting, returning a fully-resolved {allow, deny} pair suitable for
+ * a permission-overlay registry entry (no `ask` left).
+ *
+ *   fullAutonomous: true  → ask collapses to allow (autonomous worker
+ *                            proceeds without human round-trip)
+ *   fullAutonomous: false → ask collapses to deny  (safe default;
+ *                            autonomous workers shouldn't make
+ *                            judgment calls)
+ *
+ * Mirrors the inline logic in `agent-manager-v2.ts`'s
+ * `claudeCodeOptions.settings.permissions` build path so the runtime
+ * overlay applies the same `ask`-resolution semantics as the
+ * spawn-time settings.
+ *
+ * Returns `undefined` when the input has no rules at all (caller can
+ * skip overlay registration entirely).
+ */
+export function collapsePermissionsForAutonomous(
+  perms: WireLoadout["permissions"] | undefined,
+  fullAutonomous: boolean,
+): { allow: string[]; deny: string[] } | undefined {
+  if (!perms || !hasAnyRule(perms)) return undefined;
+  const { allow = [], deny = [], ask = [] } = perms;
+  return fullAutonomous
+    ? { allow: [...allow, ...ask], deny: [...deny] }
+    : { allow: [...allow], deny: [...deny, ...ask] };
+}