macro-agent 0.1.10 → 0.1.12

package/src/__tests__/e2e/dispatch.e2e.test.ts

@@ -0,0 +1,376 @@
+/**
+ * Task Dispatch E2E Tests (mocked agents)
+ *
+ * Tests dispatch boot wiring, configuration, and basic dispatch flow
+ * using mocked acp-factory and opentasks (no real agents or daemon).
+ *
+ * REQUIRES: RUN_E2E_TESTS=true
+ *
+ * Run with:
+ *   RUN_E2E_TESTS=true npx vitest run --config vitest.e2e.config.ts src/__tests__/e2e/dispatch.e2e.test.ts
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+  vi,
+} from "vitest";
+import * as path from "path";
+import * as os from "os";
+import * as fs from "fs";
+import { bootV2, type MacroAgentSystemV2 } from "../../boot-v2.js";
+
+// ─────────────────────────────────────────────────────────────────
+// Configuration
+// ─────────────────────────────────────────────────────────────────
+
+const RUN_E2E = !!process.env.RUN_E2E_TESTS;
+const describeFn = RUN_E2E ? describe : describe.skip;
+
+// ─────────────────────────────────────────────────────────────────
+// Mocks
+// ─────────────────────────────────────────────────────────────────
+
+vi.mock("acp-factory", () => ({
+  AgentFactory: {
+    spawn: vi.fn().mockResolvedValue({
+      createSession: vi.fn().mockResolvedValue({
+        id: `session-${Date.now()}`,
+        prompt: vi.fn().mockReturnValue({
+          [Symbol.asyncIterator]: () => ({
+            next: () => Promise.resolve({ done: true, value: undefined }),
+          }),
+        }),
+        forkWithFlush: vi.fn().mockResolvedValue({ id: `forked-${Date.now()}` }),
+      }),
+      loadSession: vi.fn().mockResolvedValue({ id: `loaded-${Date.now()}` }),
+      close: vi.fn().mockResolvedValue(undefined),
+      isRunning: vi.fn().mockReturnValue(true),
+    }),
+  },
+}));
+
+vi.mock("opentasks", () => ({
+  OpenTasksClient: vi.fn().mockImplementation(() => ({
+    connect: vi.fn().mockRejectedValue(new Error("No daemon")),
+    disconnect: vi.fn(),
+    query: vi.fn().mockResolvedValue({ items: [] }),
+    link: vi.fn().mockResolvedValue({ success: true }),
+    task: vi.fn().mockResolvedValue({ id: "t-1" }),
+  })),
+}));
+
+// ─────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────
+
+function createTestDir(): string {
+  const dir = path.join(
+    os.tmpdir(),
+    `dispatch-e2e-${Date.now()}-${Math.random().toString(36).slice(2)}`
+  );
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Tests
+// ─────────────────────────────────────────────────────────────────
+
+describeFn("Task Dispatch E2E", () => {
+  let system: MacroAgentSystemV2;
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = createTestDir();
+  });
+
+  afterEach(async () => {
+    if (system) {
+      try {
+        const running = system.agentManager.list({ state: "running" } as any);
+        for (const agent of running) {
+          await system.agentManager.terminate(agent.id, "cancelled");
+        }
+      } catch { /* best effort */ }
+      await system.shutdown();
+    }
+    if (fs.existsSync(testDir)) {
+      fs.rmSync(testDir, { recursive: true, force: true });
+    }
+  });
+
+  // ── Boot with dispatch enabled ─────────────────────────────
+
+  describe("Boot", () => {
+    it("boots successfully with dispatch enabled", async () => {
+      system = await bootV2({
+        cwd: testDir,
+        baseDir: testDir,
+        inbox: { socketPath: path.join(testDir, "inbox.sock") },
+        dispatch: {
+          enabled: true,
+          pollIntervalMs: 60_000,
+          maxConcurrent: 3,
+          defaultRole: "worker",
+        },
+      });
+
+      expect(system).toBeDefined();
+      expect(system.taskDispatcher).toBeDefined();
+      expect(system.taskDispatcher!.running).toBe(true);
+    });
+
+    it("boots successfully with dispatch and reconcile enabled", async () => {
+      system = await bootV2({
+        cwd: testDir,
+        baseDir: testDir,
+        inbox: { socketPath: path.join(testDir, "inbox.sock") },
+        dispatch: {
+          enabled: true,
+          pollIntervalMs: 60_000,
+          maxConcurrent: 3,
+          reconcile: { enabled: true, intervalMs: 120_000 },
+        },
+      });
+
+      expect(system.taskDispatcher).toBeDefined();
+      expect(system.taskDispatcher!.running).toBe(true);
+    });
+
+    it("boots without dispatch when not enabled", async () => {
+      system = await bootV2({
+        cwd: testDir,
+        baseDir: testDir,
+        inbox: { socketPath: path.join(testDir, "inbox.sock") },
+      });
+
+      expect(system.taskDispatcher).toBeUndefined();
+    });
+
+    it("exposes tracker for observability", async () => {
+      system = await bootV2({
+        cwd: testDir,
+        baseDir: testDir,
+        inbox: { socketPath: path.join(testDir, "inbox.sock") },
+        dispatch: {
+          enabled: true,
+          pollIntervalMs: 60_000,
+          maxConcurrent: 3,
+        },
+      });
+
+      expect(system.taskDispatcher!.tracker).toBeDefined();
+      expect(system.taskDispatcher!.tracker.activeCount()).toBe(0);
+      expect(system.taskDispatcher!.tracker.listRetries()).toHaveLength(0);
+    });
+  });
+
+  // ── Dispatch via dispatchNow ───────────────────────────────
+
+  describe("Dispatch", () => {
+    it("dispatchNow triggers a dispatch cycle", async () => {
+      system = await bootV2({
+        cwd: testDir,
+        baseDir: testDir,
+        inbox: { socketPath: path.join(testDir, "inbox.sock") },
+        dispatch: {
+          enabled: true,
+          pollIntervalMs: 600_000,
+          maxConcurrent: 5,
+        },
+      });
+
+      // dispatchNow should not throw even with no ready tasks
+      await system.taskDispatcher!.dispatchNow();
+      expect(system.taskDispatcher!.tracker.activeCount()).toBe(0);
+    });
+
+    it("reconcileNow triggers a reconciliation cycle", async () => {
+      system = await bootV2({
+        cwd: testDir,
+        baseDir: testDir,
+        inbox: { socketPath: path.join(testDir, "inbox.sock") },
+        dispatch: {
+          enabled: true,
+          pollIntervalMs: 600_000,
+          maxConcurrent: 3,
+          reconcile: { enabled: true, intervalMs: 600_000 },
+        },
+      });
+
+      // reconcileNow should not throw with no active dispatches
+      await system.taskDispatcher!.reconcileNow();
+    });
+  });
+
+  // ── Event subscription ─────────────────────────────────────
+
+  describe("Events", () => {
+    it("emits poll events via onEvent", async () => {
+      system = await bootV2({
+        cwd: testDir,
+        baseDir: testDir,
+        inbox: { socketPath: path.join(testDir, "inbox.sock") },
+        dispatch: {
+          enabled: true,
+          pollIntervalMs: 600_000,
+        },
+      });
+
+      const events: any[] = [];
+      system.taskDispatcher!.onEvent((e) => events.push(e));
+
+      await system.taskDispatcher!.dispatchNow();
+
+      const poll = events.find((e) => e.type === "poll");
+      expect(poll).toBeDefined();
+      expect(poll.dispatched).toBe(0);
+      expect(poll.active).toBe(0);
+    });
+  });
+
+  // ── Shutdown ───────────────────────────────────────────────
+
+  describe("Shutdown", () => {
+    it("shuts down cleanly with dispatch enabled", async () => {
+      system = await bootV2({
+        cwd: testDir,
+        baseDir: testDir,
+        inbox: { socketPath: path.join(testDir, "inbox.sock") },
+        dispatch: {
+          enabled: true,
+          pollIntervalMs: 60_000,
+          maxConcurrent: 3,
+          reconcile: { enabled: true, intervalMs: 120_000 },
+        },
+      });
+
+      await system.shutdown();
+      system = undefined as any;
+    });
+  });
+
+  // ── Config Variations ──────────────────────────────────────
+
+  describe("Configuration", () => {
+    it("applies custom config values", async () => {
+      system = await bootV2({
+        cwd: testDir,
+        baseDir: testDir,
+        inbox: { socketPath: path.join(testDir, "inbox.sock") },
+        dispatch: {
+          enabled: true,
+          pollIntervalMs: 5_000,
+          maxConcurrent: 10,
+          defaultRole: "security-auditor",
+          tags: ["security", "audit"],
+          maxRetries: 5,
+          retryBaseDelayMs: 5_000,
+          retryMaxDelayMs: 120_000,
+          reconcile: { enabled: true, intervalMs: 30_000 },
+          eligibility: {
+            minPriority: 3,
+            excludeTags: ["wip"],
+            minScore: 0.5,
+          },
+        },
+      });
+
+      expect(system.taskDispatcher).toBeDefined();
+      expect(system.taskDispatcher!.running).toBe(true);
+    });
+
+    it("boots without reconcile when reconcile.enabled is false", async () => {
+      system = await bootV2({
+        cwd: testDir,
+        baseDir: testDir,
+        inbox: { socketPath: path.join(testDir, "inbox.sock") },
+        dispatch: {
+          enabled: true,
+          pollIntervalMs: 60_000,
+          reconcile: { enabled: false },
+        },
+      });
+
+      // Dispatcher should still work — just no reconcile timer
+      expect(system.taskDispatcher).toBeDefined();
+      expect(system.taskDispatcher!.running).toBe(true);
+    });
+  });
+
+  // ── MAP Event Bridge ───────────────────────────────────────
+
+  describe("MAP Event Bridge", () => {
+    it("dispatcher works without MAP sidecar", async () => {
+      // No MAP config → no sidecar → dispatch should still work
+      system = await bootV2({
+        cwd: testDir,
+        baseDir: testDir,
+        inbox: { socketPath: path.join(testDir, "inbox.sock") },
+        dispatch: {
+          enabled: true,
+          pollIntervalMs: 60_000,
+        },
+        // No map config
+      });
+
+      expect(system.taskDispatcher).toBeDefined();
+      expect(system.taskDispatcher!.running).toBe(true);
+
+      // dispatchNow should work without MAP bridge
+      await system.taskDispatcher!.dispatchNow();
+    });
+
+    it("onEvent subscription works independently of MAP", async () => {
+      system = await bootV2({
+        cwd: testDir,
+        baseDir: testDir,
+        inbox: { socketPath: path.join(testDir, "inbox.sock") },
+        dispatch: {
+          enabled: true,
+          pollIntervalMs: 60_000,
+        },
+      });
+
+      const events: any[] = [];
+      const unsub = system.taskDispatcher!.onEvent((e) => events.push(e));
+
+      await system.taskDispatcher!.dispatchNow();
+
+      expect(events.some((e) => e.type === "poll")).toBe(true);
+
+      // Unsubscribe stops events
+      const countBefore = events.length;
+      unsub();
+      await system.taskDispatcher!.dispatchNow();
+      expect(events.length).toBe(countBefore);
+    });
+
+    it("MAP sidecar with unreachable server does not break dispatch", async () => {
+      system = await bootV2({
+        cwd: testDir,
+        baseDir: testDir,
+        inbox: { socketPath: path.join(testDir, "inbox.sock") },
+        dispatch: {
+          enabled: true,
+          pollIntervalMs: 60_000,
+        },
+        map: {
+          enabled: true,
+          server: "ws://127.0.0.1:1", // Unreachable
+          scope: "swarm:test",
+        },
+      });
+
+      // Dispatch should work even though MAP sidecar failed to connect
+      expect(system.taskDispatcher).toBeDefined();
+      expect(system.taskDispatcher!.running).toBe(true);
+
+      await system.taskDispatcher!.dispatchNow();
+    });
+  });
+});

package/src/acp/macro-agent.ts

@@ -587,12 +587,47 @@ export function createMacroAgent(
         return {};
       }
 
-      // No mapping — but if the client supplied provider_session_id via _meta,
-      // we can still replay history from the JSONL on disk. This is the
-      // cross-restart recovery path. We don't create a session mapping because
-      // there's no live agent to bind to — the client should create a fresh
-      // session if it wants to continue the conversation.
+      // No in-memory mapping and the ACP sessionId isn't an agent ID. If the
+      // client supplied provider_session_id via _meta, reverse-lookup the
+      // owning agent in the agent-store and resume it. This is the durable
+      // cross-restart recovery path: macro-agent's sessionMapper is
+      // in-memory, so after a process restart it's empty, but the agent +
+      // session records survive on disk keyed by provider_session_id.
+      //
+      // The critical piece is creating the sessionMapper entry here — without
+      // it, subsequent `prompt` calls throw `session not found` and the ACP
+      // layer catches that and returns stopReason:"cancelled", making the
+      // session appear unresponsive.
       if (metaProviderSessionId) {
+        const store = (system as any).agentStore;
+        const sessionRec = typeof store?.findSessionByProviderSessionId === "function"
+          ? store.findSessionByProviderSessionId(metaProviderSessionId)
+          : undefined;
+        if (sessionRec?.agent_id) {
+          const agentId = sessionRec.agent_id;
+          try {
+            // Idempotent: resume() throws ALREADY_RUNNING if the agent is
+            // already active (e.g. _macro/resumeAgent just brought it back).
+            // We still need to bind the ACP session to this agent.
+            if (!agentManager.hasActiveSession(agentId as any)) {
+              await agentManager.resume(agentId as any);
+            }
+            // Bind under BOTH the macro-agent ACP sessionId AND the provider
+            // session UUID. The MAP SDK's ACPStreamConnection often ends up
+            // storing _meta.provider_session_id as its stream.sessionId —
+            // which is what swarmcraft echoes back in session/prompt. Without
+            // the UUID mapping, prompt hits sessionMapper with the UUID key
+            // and fails (→ stopReason: cancelled).
+            sessionMapper.createMapping(sessionId, agentId);
+            if (metaProviderSessionId !== sessionId) {
+              sessionMapper.createMapping(metaProviderSessionId as any, agentId);
+            }
+            await replayHistory(agentId, metaProviderSessionId);
+            return {};
+          } catch {
+            // Fall through to history-only replay below
+          }
+        }
         await replayHistory(undefined, metaProviderSessionId);
         return {};
       }
@@ -931,7 +966,7 @@ export function createMacroAgent(
         }
 
         return { stopReason: "end_turn" };
-      } catch (err) {
+      } catch {
         // If prompt fails, still return a valid response
         return { stopReason: "cancelled" };
       } finally {

package/src/adapters/__tests__/tasks-adapter.test.ts

@@ -185,6 +185,7 @@ describe("TasksAdapter", () => {
 
       expect(mockClient.query).toHaveBeenCalledWith({
         ready: { tags: ["backend"], limit: 5 },
+        verbose: true,
       });
     });
   });

package/src/adapters/tasks-adapter.ts

@@ -88,6 +88,7 @@ export class DefaultTasksAdapter implements ITasksAdapter {
       parent_id: opts.parent,
       tags: opts.tags,
       priority: opts.priority,
+      metadata: opts.metadata,
     });
 
     return node?.id ?? "";
@@ -129,6 +130,7 @@ export class DefaultTasksAdapter implements ITasksAdapter {
         limit: opts?.limit,
         tags: opts?.tags,
       },
+      verbose: true,
     });
 
     return (result.items ?? []).map((n: NodeSummaryLike) =>
@@ -146,6 +148,7 @@ export class DefaultTasksAdapter implements ITasksAdapter {
         tags: filter?.tags,
         limit: filter?.limit,
       },
+      verbose: true,
     });
 
     return (result.items ?? []).map((n: NodeSummaryLike) =>

package/src/adapters/types.ts

@@ -188,6 +188,7 @@ export interface CreateTaskOptions {
   parent?: string;
   tags?: string[];
   priority?: number;
+  metadata?: Record<string, unknown>;
 }
 
 /**

package/src/agent/__tests__/agent-store.test.ts

@@ -409,5 +409,57 @@ describe("AgentStore", () => {
       const session = store.getSession("agent-1")!;
       expect(session.provider_session_id).toBeUndefined();
     });
+
+    it("findSessionByProviderSessionId returns the matching session", () => {
+      store.putAgent(makeAgent({ id: "agent-2" }));
+      store.putSession({
+        agent_id: "agent-1",
+        session_id: "session-abc",
+        provider_session_id: "psid-xyz",
+        created_at: Date.now(),
+      });
+      store.putSession({
+        agent_id: "agent-2",
+        session_id: "session-def",
+        provider_session_id: "psid-other",
+        created_at: Date.now(),
+      });
+
+      const found = store.findSessionByProviderSessionId("psid-xyz");
+      expect(found).not.toBeNull();
+      expect(found!.agent_id).toBe("agent-1");
+      expect(found!.session_id).toBe("session-abc");
+    });
+
+    it("findSessionByProviderSessionId returns null when no match", () => {
+      store.putSession({
+        agent_id: "agent-1",
+        session_id: "session-1",
+        provider_session_id: "psid-1",
+        created_at: Date.now(),
+      });
+      expect(store.findSessionByProviderSessionId("psid-missing")).toBeNull();
+    });
+
+    it("findSessionByProviderSessionId returns most recent on duplicate psid", () => {
+      // Shouldn't normally happen but verify the ORDER BY created_at DESC path.
+      store.putAgent(makeAgent({ id: "agent-old" }));
+      store.putAgent(makeAgent({ id: "agent-new" }));
+      store.putSession({
+        agent_id: "agent-old",
+        session_id: "session-old",
+        provider_session_id: "psid-dup",
+        created_at: 1000,
+      });
+      store.putSession({
+        agent_id: "agent-new",
+        session_id: "session-new",
+        provider_session_id: "psid-dup",
+        created_at: 2000,
+      });
+
+      const found = store.findSessionByProviderSessionId("psid-dup");
+      expect(found!.agent_id).toBe("agent-new");
+    });
   });
 });

package/src/agent/agent-manager-v2.ts

@@ -879,7 +879,16 @@ export function createAgentManagerV2(
       healthCheckService.stopForCoordinator(agentId);
     }
 
-    // Submit merge request if worker completed with workspace
+    // Land the worker's work if completed with a workspace.
+    //
+    // V3 path (preferred): look up the role's YAML landing strategy via
+    // TopologyPolicy.getRoleConfig and dispatch through
+    // WorkspaceManager.land(). This fires cascade events (stream.merged or
+    // queue.added) so the hub sees the work. Landing = 'none' short-circuits.
+    //
+    // Legacy fallback: if no TopologyPolicy is wired or it can't resolve a
+    // landing for this role, submit to the legacy MergeQueue as before.
+    // Keeps pre-V3 programmatic callers + tests that bypass YAML working.
     if (
       workspaceManager &&
       agentWorkspaces.has(agentId) &&
@@ -887,18 +896,45 @@ export function createAgentManagerV2(
     ) {
       const ws = agentWorkspaces.get(agentId)!;
       if (ws.role === "worker" && ws.streamId) {
-        try {
-          const mergeQueue = workspaceManager.getMergeQueue();
-          if (mergeQueue) {
-            mergeQueue.submit({
+        const roleConfig = topologyPolicy?.getRoleConfig?.(record.role);
+        const yamlLandingName = roleConfig?.landing;
+        const usingV3Landing =
+          typeof yamlLandingName === "string" && yamlLandingName.length > 0;
+
+        if (usingV3Landing) {
+          try {
+            const taskRef = (record.metadata as Record<string, unknown> | undefined)
+              ?.task_ref as { resource_id: string; node_id: string } | undefined;
+            await workspaceManager.land({
+              agentId,
               streamId: ws.streamId,
-              workerBranch: ws.branch,
-              taskId: record.task_id ?? agentId,
-              workerAgentId: agentId,
+              sourceWorktree: ws.path,
+              strategyName: yamlLandingName,
+              strategyConfig: roleConfig?.landing_config,
+              taskRef,
+              // Dispatcher overwrites this with `this`; placeholder keeps the
+              // type satisfied without a cast.
+              workspaceManager,
             });
+          } catch {
+            // Non-fatal landing failure — agent still terminates; conflicts
+            // and strategy errors surface via WorkspaceEvent emission and
+            // the strategy's own logs.
+          }
+        } else {
+          try {
+            const mergeQueue = workspaceManager.getMergeQueue();
+            if (mergeQueue) {
+              mergeQueue.submit({
+                streamId: ws.streamId,
+                workerBranch: ws.branch,
+                taskId: record.task_id ?? agentId,
+                workerAgentId: agentId,
+              });
+            }
+          } catch {
+            // Non-fatal merge queue submission failure
           }
-        } catch {
-          // Non-fatal merge queue submission failure
         }
       }
     }
@@ -987,11 +1023,16 @@ export function createAgentManagerV2(
               .map((r) => agentRecordToAgent(r)),
           terminate: (id: AgentId, r: AgentStopReason) => terminate(id, r),
         };
+        const parentTaskRef = (record.metadata as Record<string, unknown> | undefined)
+          ?.task_ref as { resource_id: string; node_id: string } | undefined;
         await terminateWithChangeConsolidation(
           child.id as AgentId,
           agentId,
           cascadeAdapter,
-          wsProvider
+          wsProvider,
+          undefined,
+          workspaceManager ?? undefined,
+          parentTaskRef
         );
       }
     }
@@ -1097,6 +1138,21 @@ export function createAgentManagerV2(
     });
 
     const agent = agentRecordToAgent(agentStore.getAgent(agentId)!);
+
+    // Re-publish the agent to subscribers (local MAP server, hub lifecycle
+    // bridge, team auto-join listeners) so a resumed agent is a first-class
+    // registered agent — not just an in-memory handle. Without this, the hub
+    // never re-registers the agent after cold-start; ACP routing works but
+    // the hub's "Registered Agents" view stays empty and capabilities never
+    // propagate back through `map/agents/register`.
+    //
+    // Spawn semantics are correct here: the process is new, the session is
+    // (re)loaded, and subscribers treat it as a fresh registration. Paired
+    // with the `stopped` event that fired on the prior termination, this
+    // keeps the bridge's `registered` map consistent.
+    notifyLifecycle({ type: "spawned", agent });
+    notifyLifecycle({ type: "started", agent });
+
     return {
       id: agentId,
       session_id: sessionRecord?.session_id ?? "",
@@ -1500,6 +1556,18 @@ export function createAgentManagerV2(
       }
     }
 
+    // Auto-terminate when done() was called and the handler signaled shouldTerminate.
+    // This closes the lifecycle gap: without this, agents stay in "running" state
+    // after calling done() because nothing triggers terminate().
+    if (doneCalled) {
+      const reason = doneStatus === "completed" ? "completed" : (doneStatus ?? "failed");
+      try {
+        await terminate(agentId, reason as any);
+      } catch {
+        // Best effort — agent may already be stopping
+      }
+    }
+
     return { doneCalled, doneStatus, updates: allUpdates };
   }