macro-agent 0.2.5 → 0.2.6

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

@@ -1,282 +0,0 @@
-/**
- * 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

@@ -1,138 +0,0 @@
-/**
- * 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] };
-}