macro-agent 0.2.4 → 0.2.6

package/src/control/types.ts

@@ -1,95 +0,0 @@
-/**
- * Control Socket Types
- *
- * NDJSON protocol for MCP subprocess → main process lifecycle RPC.
- * Separate from agent-inbox (messaging) — this is the control plane.
- *
- * @module control/types
- */
-
-import type { AgentId } from "../store/types/primitives.js";
-import type { AgentStopReason } from "../agent/types.js";
-
-// =============================================================================
-// Commands (subprocess → main process)
-// =============================================================================
-
-export type ControlCommand =
-  | SpawnCommand
-  | TerminateCommand
-  | GetAgentCommand
-  | ListAgentsCommand
-  | GetChildrenCommand
-  | GetHierarchyCommand
-  | PingCommand
-  | HealthCheckCommand;
-
-export interface SpawnCommand {
-  action: "spawn";
-  task: string;
-  parent?: string | null;
-  role?: string;
-  cwd?: string;
-  team_instance?: string;
-  customPrompt?: string;
-}
-
-export interface TerminateCommand {
-  action: "terminate";
-  agentId: string;
-  reason: AgentStopReason;
-}
-
-export interface GetAgentCommand {
-  action: "get_agent";
-  agentId: string;
-}
-
-export interface ListAgentsCommand {
-  action: "list_agents";
-  filter?: {
-    state?: string;
-    parent?: string | null;
-    headManagersOnly?: boolean;
-  };
-}
-
-export interface GetChildrenCommand {
-  action: "get_children";
-  agentId: string;
-}
-
-export interface GetHierarchyCommand {
-  action: "get_hierarchy";
-  agentId: string;
-  depth?: number;
-}
-
-export interface PingCommand {
-  action: "ping";
-}
-
-export interface HealthCheckCommand {
-  action: "health_check";
-  agentId: string;
-  mcpPid: number;
-}
-
-// =============================================================================
-// Responses (main process → subprocess)
-// =============================================================================
-
-export type ControlResponse =
-  | ControlSuccessResponse
-  | ControlErrorResponse;
-
-export interface ControlSuccessResponse {
-  ok: true;
-  result?: unknown;
-}
-
-export interface ControlErrorResponse {
-  ok: false;
-  error: string;
-  code?: string;
-}

package/src/dispatch/CLAUDE.md

@@ -1,129 +0,0 @@
-# macro-agent/src/dispatch — hub-driven work intake
-
-This directory contains the consumer-side handlers that receive
-hub-orchestrated `x-dispatch/work` envelopes from a connected OpenHive
-hub (or any hub speaking the same wire shape). Two consumers, one
-mail-bridge:
-
-- **`mail-inbound-consumer.ts`** — addressed to the sidecar (`recipient =
-  dispatcher:<claimantId>`). Spawns a **fresh, parentless** worker per
-  envelope. Used when the hub picks the sidecar as the mail target —
-  typically because no specialized worker is registered yet, or because
-  the hub's `mail_lifecycle: 'fresh'` hint forced sidecar routing.
-- **`mail-inbound-reuse-consumer.ts`** — addressed to a **non-sidecar**
-  agent that already exists on the swarm. Forwards the envelope into
-  the long-lived agent's prompt iterator instead of spawning. Used for
-  `mail_lifecycle: 'reuse'` dispatches against multi-role swarms.
-- **`mail-bridge.ts`** — receives `mail/turn.received` MAP notifications
-  from the hub and forwards each turn into the sidecar's local
-  agent-inbox so the consumers above can dispatch on `inbox.message`.
-
-## Wire envelope shape (hub contract)
-
-Every envelope follows:
-
-```json
-{
-  "type": "x-dispatch/work",
-  "body": {
-    "taskId": "disp_xxx",
-    "prompt": "<rendered prompt>",
-    "role": "worker | executor | reviewer | ...",
-    "loadout": { "permissions": {...}, "mcpProviders": [...], ... },
-    "metadata": { "permissions": ..., "mcpProviders": ... },  // legacy
-    "_conversationId": "conv_xxx"  // mail-reuse path only
-  }
-}
-```
-
-- `body.role` may be **any** string the hub side surfaces (e.g., from a
-  team template's `team_role_ref.role`). It is NOT guaranteed to match
-  any built-in or locally-configured macro-agent role. The consumer
-  must defend against unknown role strings — see "Role validation" below.
-- `body.loadout` is the canonical structured slot. `body.metadata` carries
-  the legacy permissions/MCP fields for one deprecation cycle so older
-  consumers continue to work.
-
-## Role validation (regression hardening)
-
-When the hub surfaces a team-defined role like `'executor'`, the wire
-envelope arrives at `mail-inbound-consumer.ts` with `body.role:
-'executor'`. macro-agent's role registry has no `'executor'` entry, so
-`roleRegistry.resolveRole('executor')` falls back to `GenericRole` —
-which has:
-
-- `lifecycle.type: 'persistent'` (no auto-cleanup, no task-bound timeout)
-- `WILDCARD_CAPABILITY` (so it has the `done` capability technically),
-  but no system-prompt instruction telling the agent to call `done()`
-
-When such an agent finishes a single prompt cycle (`promptUntilDone(...,
-{maxFollowUps: 0})`), it stops without invoking `done({summary: ...})`.
-The lifecycle handler's `_lastSummary` write is gated on `args.summary`,
-so nothing gets persisted. The consumer reads back `_lastSummary` to
-post the reply turn — empty → "no reply turn posted" → the hub never
-sees an answer and the dispatch silently dies.
-
-The fix: validate the requested role against the registry **before**
-passing it to `agentManager.spawn`. Unknown roles fall back to
-`'worker'` (ephemeral lifecycle + `LIFECYCLE_CAPABILITIES.DONE` +
-explicit "you MUST call done()" system prompt):
-
-```typescript
-const requestedRole = data.role;
-const roleRegistry = agentManager.getRoleRegistry?.();
-const knownRole =
-  requestedRole && roleRegistry?.getRole(requestedRole) !== undefined;
-const role = knownRole ? requestedRole! : "worker";
-if (requestedRole && !knownRole) {
-  log(`[mail-inbound] Unknown role '${requestedRole}' for taskId=${taskId} — falling back to 'worker'`);
-}
-```
-
-`roleRegistry.getRole(name)` is exact-match across custom / project /
-user / built-in maps and returns `undefined` for unknown names —
-distinct from `resolveRole(name)` which always returns *something* via
-`GenericRole`. We use the former here intentionally so the fallback
-path is observable (we log a warning) rather than silent.
-
-**Apply the same pattern to any future consumer that spawns workers
-from a wire envelope.** The receiving side owns the role taxonomy;
-hubs cannot be expected to use names that match the receiver's
-registry.
-
-## Reply path (worker → hub)
-
-After the consumer spawns a worker:
-
-1. `agentManager.promptUntilDone(spawnedId, prompt, {maxFollowUps: 0})`
-   drives the worker through one prompt cycle.
-2. Worker calls `done({status, summary})` — the lifecycle handler
-   writes `_lastSummary` to agent metadata (`handlers-v2.ts:233`,
-   gated on `inDispatch || !parentId`).
-3. AgentManager fires the lifecycle `stopped` event.
-4. The consumer's `stopped` listener reads `_lastSummary` from
-   `agentStore.getAgent(agentId)` and posts a reply turn into the
-   dispatch conversation via `mail/turn`.
-5. The hub's `mail.turn.added` event fires; the orchestrator's
-   reply-demuxer routes it back to swarm-dispatch as the dispatch
-   completion.
-
-If `_lastSummary` is empty when the worker stops, the consumer logs
-"Worker stopped but _lastSummary is empty — no reply turn posted" and
-bails. This is the canary for role-validation failures, lifecycle
-misconfigurations, or agents that exit without calling `done()`.
-
-## Idempotency + dedup
-
-Both consumers track `seenTaskIds` with a 1-hour TTL to drop duplicate
-deliveries (the hub's mail-push bridge can re-fire `mail.turn.added`
-on reconnect; the local inbox can re-emit `inbox.message` for the same
-logical turn). Within the TTL window, a re-delivered taskId is
-silently ignored. After the TTL expires, a stale retry could
-legitimately re-spawn — preferable to permanent memory growth.
-
-## Tests
-
-- `__tests__/mail-inbound-consumer.test.ts` — unit-level spawn/reply flow with mocked AgentManager
-- `__tests__/mail-inbound-consumer.integration.test.ts` — full lifecycle through real `AgentManagerV2`
-- `__tests__/mail-inbound-reuse-consumer.test.ts` — reuse-path classification + filtering
-- Live e2e (in OpenHive): `src/__tests__/swarm/live-{loadout,mail-reuse}-dispatch*.test.ts` — gated by `LIVE_AGENT_E2E=true`

package/src/dispatch/__tests__/loadout-translation.test.ts

@@ -1,141 +0,0 @@
-/**
- * Unit tests for `loadoutToSpawnOptions` — the pure-function translator
- * from wire-shape `MaterializedLoadout` to macro-agent `SpawnAgentOptions`.
- *
- * These tests pin the shared contract used by both the mail-inbound
- * consumer and the new `dispatch/spawn-agent` MAP handler. Both paths
- * should produce identical spawn options for the same loadout input.
- */
-
-import { describe, it, expect } from "vitest";
-import {
-  loadoutToSpawnOptions,
-  type WireLoadout,
-} from "../loadout-translation.js";
-
-describe("loadoutToSpawnOptions", () => {
-  it("returns {} for undefined loadout", () => {
-    expect(loadoutToSpawnOptions(undefined)).toEqual({});
-  });
-
-  it("returns {} when ctx is provided but loadout is undefined", () => {
-    expect(loadoutToSpawnOptions(undefined, { fullAutonomous: true })).toEqual({});
-  });
-
-  it("returns {} for loadout with no permissions/capabilities (empty fields)", () => {
-    const loadout: WireLoadout = {};
-    expect(loadoutToSpawnOptions(loadout)).toEqual({});
-  });
-
-  it("returns {} when permissions is present but all rule arrays are empty", () => {
-    const loadout: WireLoadout = {
-      permissions: { allow: [], deny: [], ask: [] },
-    };
-    // hasAnyRule returns false → no permissions or fullAutonomous propagated.
-    expect(loadoutToSpawnOptions(loadout, { fullAutonomous: true })).toEqual({});
-  });
-
-  it("propagates deny rules + sets fullAutonomous from ctx (true)", () => {
-    const loadout: WireLoadout = {
-      permissions: { deny: ["Bash(rm -rf:*)"] },
-    };
-    const result = loadoutToSpawnOptions(loadout, { fullAutonomous: true });
-    expect(result.permissions).toEqual({
-      allow: [],
-      deny: ["Bash(rm -rf:*)"],
-      ask: [],
-    });
-    expect(result.fullAutonomous).toBe(true);
-  });
-
-  it("propagates deny rules + sets fullAutonomous from ctx (false)", () => {
-    const loadout: WireLoadout = {
-      permissions: { deny: ["Bash(rm -rf:*)"] },
-    };
-    const result = loadoutToSpawnOptions(loadout, { fullAutonomous: false });
-    expect(result.permissions).toEqual({
-      allow: [],
-      deny: ["Bash(rm -rf:*)"],
-      ask: [],
-    });
-    expect(result.fullAutonomous).toBe(false);
-  });
-
-  it("defaults fullAutonomous to false when ctx omits it but permissions are present", () => {
-    const loadout: WireLoadout = {
-      permissions: { ask: ["Write(*.env)"] },
-    };
-    const result = loadoutToSpawnOptions(loadout);
-    expect(result.permissions).toEqual({
-      allow: [],
-      deny: [],
-      ask: ["Write(*.env)"],
-    });
-    expect(result.fullAutonomous).toBe(false);
-  });
-
-  it("does NOT propagate fullAutonomous when no permissions are present", () => {
-    // ctx.fullAutonomous is meaningless without permissions to apply it to.
-    const loadout: WireLoadout = { capabilities: ["editor"] };
-    const result = loadoutToSpawnOptions(loadout, { fullAutonomous: true });
-    expect(result.fullAutonomous).toBeUndefined();
-    expect(result.permissions).toBeUndefined();
-  });
-
-  it("forwards capabilities (cloned, not aliased)", () => {
-    const sourceCaps = ["editor", "git"];
-    const loadout: WireLoadout = { capabilities: sourceCaps };
-    const result = loadoutToSpawnOptions(loadout);
-    expect(result.capabilities).toEqual(["editor", "git"]);
-    // Ensure we cloned — mutating the result's array must not affect the source.
-    result.capabilities!.push("newcap");
-    expect(sourceCaps).toEqual(["editor", "git"]);
-  });
-
-  it("does not include capabilities when the array is empty", () => {
-    const loadout: WireLoadout = { capabilities: [] };
-    const result = loadoutToSpawnOptions(loadout);
-    expect(result.capabilities).toBeUndefined();
-  });
-
-  it("ignores mcpProviders (Phase 2 — reserved/no-op)", () => {
-    const loadout: WireLoadout = {
-      mcpProviders: [
-        { name: "github", command: "github-mcp", args: ["--read-only"] },
-      ],
-    };
-    const result = loadoutToSpawnOptions(loadout);
-    // The provider should NOT appear on the returned spawn options.
-    expect(result).toEqual({});
-    expect((result as Record<string, unknown>).mcpProviders).toBeUndefined();
-  });
-
-  it("ignores mcpScope (Phase 1 — reserved/no-op)", () => {
-    const loadout: WireLoadout = {
-      mcpScope: [{ server: "github", tools: ["search"] }],
-    };
-    const result = loadoutToSpawnOptions(loadout);
-    expect(result).toEqual({});
-    expect((result as Record<string, unknown>).mcpScope).toBeUndefined();
-  });
-
-  it("combines permissions + capabilities + ignores mcp fields together", () => {
-    const loadout: WireLoadout = {
-      permissions: { allow: ["Read(**)"], deny: ["Bash(rm:*)"] },
-      capabilities: ["editor"],
-      mcpProviders: [{ name: "github" }],
-      mcpScope: [{ server: "github" }],
-    };
-    const result = loadoutToSpawnOptions(loadout, { fullAutonomous: true });
-
-    expect(result.permissions).toEqual({
-      allow: ["Read(**)"],
-      deny: ["Bash(rm:*)"],
-      ask: [],
-    });
-    expect(result.fullAutonomous).toBe(true);
-    expect(result.capabilities).toEqual(["editor"]);
-    expect((result as Record<string, unknown>).mcpProviders).toBeUndefined();
-    expect((result as Record<string, unknown>).mcpScope).toBeUndefined();
-  });
-});