macro-agent 0.2.4 → 0.2.6

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

@@ -1,270 +0,0 @@
-/**
- * Tests for TasksAdapter — wraps opentasks client.
- *
- * These tests use mocked opentasks client since the adapter is a thin
- * wrapper. Integration tests with a real opentasks daemon would go
- * in the e2e test suite.
- */
-
-import { describe, it, expect, beforeEach, vi } from "vitest";
-import { DefaultTasksAdapter } from "../tasks-adapter.js";
-
-// Mock the opentasks module
-vi.mock("opentasks", () => ({
-  OpenTasksClient: vi.fn().mockImplementation(() => mockClient),
-}));
-
-// Shared mock client
-let mockClient: MockOpenTasksClient;
-
-interface MockOpenTasksClient {
-  connect: ReturnType<typeof vi.fn>;
-  disconnect: ReturnType<typeof vi.fn>;
-  query: ReturnType<typeof vi.fn>;
-  link: ReturnType<typeof vi.fn>;
-  task: ReturnType<typeof vi.fn>;
-  createNode: ReturnType<typeof vi.fn>;
-  getNode: ReturnType<typeof vi.fn>;
-}
-
-function createMockClient(): MockOpenTasksClient {
-  return {
-    connect: vi.fn().mockResolvedValue(undefined),
-    disconnect: vi.fn(),
-    query: vi.fn().mockResolvedValue({ items: [] }),
-    link: vi.fn().mockResolvedValue({ success: true }),
-    task: vi.fn().mockResolvedValue({ id: "t-new", success: true }),
-    createNode: vi.fn().mockResolvedValue({ id: "t-new", title: "Test", status: "open" }),
-    getNode: vi.fn().mockResolvedValue({ id: "t-1", title: "Test Task", status: "in_progress", assignee: "worker-1", tags: ["urgent"], priority: 1 }),
-  };
-}
-
-describe("TasksAdapter", () => {
-  let adapter: DefaultTasksAdapter;
-
-  beforeEach(async () => {
-    mockClient = createMockClient();
-    adapter = new DefaultTasksAdapter();
-    await adapter.connect();
-  });
-
-  // ── Connection ─────────────────────────────────────────────
-
-  describe("connection lifecycle", () => {
-    it("should connect to opentasks daemon", () => {
-      expect(adapter.connected).toBe(true);
-      expect(mockClient.connect).toHaveBeenCalledOnce();
-    });
-
-    it("should not reconnect if already connected", async () => {
-      await adapter.connect();
-      expect(mockClient.connect).toHaveBeenCalledOnce();
-    });
-
-    it("should disconnect", () => {
-      adapter.disconnect();
-      expect(adapter.connected).toBe(false);
-    });
-
-    it("should throw when not connected", async () => {
-      adapter.disconnect();
-      await expect(adapter.getTask("t-1")).rejects.toThrow("not connected");
-    });
-  });
-
-  // ── createTask ─────────────────────────────────────────────
-
-  describe("createTask", () => {
-    it("should create a task and return ID", async () => {
-      mockClient.createNode.mockResolvedValue({ id: "t-abc123" });
-
-      const id = await adapter.createTask({
-        title: "Implement feature X",
-        assignee: "worker-1",
-        tags: ["backend"],
-      });
-
-      expect(id).toBe("t-abc123");
-      expect(mockClient.createNode).toHaveBeenCalledWith(
-        expect.objectContaining({
-          title: "Implement feature X",
-          assignee: "worker-1",
-          tags: ["backend"],
-        })
-      );
-    });
-  });
-
-  // ── assignTask ─────────────────────────────────────────────
-
-  describe("assignTask", () => {
-    it("should assign a task to an agent", async () => {
-      await adapter.assignTask("t-1", "worker-1");
-
-      expect(mockClient.task).toHaveBeenCalledWith({
-        assign: { id: "t-1", assignee: "worker-1" },
-      });
-    });
-  });
-
-  // ── transitionTask ─────────────────────────────────────────
-
-  describe("transitionTask", () => {
-    it("should transition task state", async () => {
-      await adapter.transitionTask("t-1", "complete");
-
-      expect(mockClient.task).toHaveBeenCalledWith({
-        transition: { id: "t-1", action: "complete" },
-      });
-    });
-
-    it("should support all actions", async () => {
-      for (const action of [
-        "start",
-        "complete",
-        "fail",
-        "block",
-        "reopen",
-      ] as const) {
-        mockClient.task.mockClear();
-        await adapter.transitionTask("t-1", action);
-        expect(mockClient.task).toHaveBeenCalledWith({
-          transition: { id: "t-1", action },
-        });
-      }
-    });
-  });
-
-  // ── getTask ────────────────────────────────────────────────
-
-  describe("getTask", () => {
-    it("should return a task record", async () => {
-      mockClient.getNode.mockResolvedValue({
-        id: "t-1",
-        title: "Test Task",
-        status: "in_progress",
-        assignee: "worker-1",
-        tags: ["urgent"],
-        priority: 1,
-      });
-
-      const task = await adapter.getTask("t-1");
-      expect(task.id).toBe("t-1");
-      expect(task.title).toBe("Test Task");
-      expect(task.status).toBe("in_progress");
-      expect(task.assignee).toBe("worker-1");
-      expect(task.tags).toEqual(["urgent"]);
-    });
-
-    it("should throw for non-existent task", async () => {
-      mockClient.getNode.mockResolvedValue(null);
-      await expect(adapter.getTask("t-missing")).rejects.toThrow(
-        "Task not found"
-      );
-    });
-  });
-
-  // ── queryReady ─────────────────────────────────────────────
-
-  describe("queryReady", () => {
-    it("should return ready tasks", async () => {
-      mockClient.query.mockResolvedValue({
-        items: [
-          { id: "t-1", title: "Ready task", status: "open" },
-          { id: "t-2", title: "Another ready", status: "open" },
-        ],
-      });
-
-      const ready = await adapter.queryReady({ limit: 10 });
-      expect(ready).toHaveLength(2);
-      expect(ready[0].status).toBe("open");
-    });
-
-    it("should pass filter options", async () => {
-      await adapter.queryReady({ tags: ["backend"], limit: 5 });
-
-      expect(mockClient.query).toHaveBeenCalledWith({
-        ready: { tags: ["backend"], limit: 5 },
-        verbose: true,
-      });
-    });
-  });
-
-  // ── Dependencies ───────────────────────────────────────────
-
-  describe("addBlocker / removeBlocker", () => {
-    it("should add a blocking edge", async () => {
-      await adapter.addBlocker("t-impl", "t-spec");
-
-      expect(mockClient.link).toHaveBeenCalledWith({
-        fromId: "t-spec",
-        toId: "t-impl",
-        type: "blocks",
-      });
-    });
-
-    it("should remove a blocking edge", async () => {
-      await adapter.removeBlocker("t-impl", "t-spec");
-
-      expect(mockClient.link).toHaveBeenCalledWith({
-        fromId: "t-spec",
-        toId: "t-impl",
-        type: "blocks",
-        remove: true,
-      });
-    });
-  });
-
-  // ── Pull Mode ──────────────────────────────────────────────
-
-  describe("claimTask", () => {
-    it("should claim the first ready task", async () => {
-      mockClient.query.mockResolvedValue({
-        items: [{ id: "t-1", title: "Claimable", status: "open" }],
-      });
-
-      const claimed = await adapter.claimTask("worker-1");
-      expect(claimed).not.toBeNull();
-      expect(claimed!.id).toBe("t-1");
-      expect(claimed!.status).toBe("in_progress");
-
-      // Should assign then start
-      expect(mockClient.task).toHaveBeenCalledWith({
-        assign: { id: "t-1", assignee: "worker-1" },
-      });
-      expect(mockClient.task).toHaveBeenCalledWith({
-        transition: { id: "t-1", action: "start" },
-      });
-    });
-
-    it("should return null when no tasks available", async () => {
-      mockClient.query.mockResolvedValue({ items: [] });
-      const claimed = await adapter.claimTask("worker-1");
-      expect(claimed).toBeNull();
-    });
-  });
-
-  describe("unclaimTask", () => {
-    it("should block then reopen to unclaim", async () => {
-      await adapter.unclaimTask("t-1");
-
-      expect(mockClient.task).toHaveBeenCalledWith({
-        transition: { id: "t-1", action: "block" },
-      });
-      expect(mockClient.task).toHaveBeenCalledWith({
-        transition: { id: "t-1", action: "reopen" },
-      });
-    });
-  });
-
-  describe("listClaimable", () => {
-    it("should delegate to queryReady", async () => {
-      mockClient.query.mockResolvedValue({
-        items: [{ id: "t-1", title: "Available", status: "open" }],
-      });
-
-      const claimable = await adapter.listClaimable({ limit: 5 });
-      expect(claimable).toHaveLength(1);
-    });
-  });
-});

package/src/adapters/federation.ts

@@ -1,185 +0,0 @@
-/**
- * Federation — Cross-instance communication via agent-inbox federation.
- *
- * Enables multiple macro-agent instances to communicate by federating
- * their embedded agent-inbox instances. Messaging uses federated
- * addressing ("agentId@systemId"). Lifecycle operations (spawn, terminate)
- * are handled via convention-based inbox messages.
- *
- * ## Architecture
- *
- * Each macro-agent instance embeds its own agent-inbox with a unique systemId.
- * Federation connects the inboxes:
- *
- *   Instance A (systemId: "dev-laptop")
- *     └── agent-inbox ←──federation──→ agent-inbox
- *                                        └── Instance B (systemId: "ci-server")
- *
- * ## Messaging
- *
- * Direct: `inboxAdapter.send("agentA", "agentB@ci-server", "hello")`
- * The inbox federation layer handles routing to the remote instance.
- *
- * ## Lifecycle Requests (convention-based)
- *
- * Cross-instance spawn: send a `remote_spawn_request` event to the remote
- * instance's system agent. The receiving instance handles it via trigger system.
- *
- * ```typescript
- * await inboxAdapter.send("coordinator@dev-laptop", "system@ci-server", {
- *   type: "event",
- *   event: "remote_spawn_request",
- *   data: { task: "Run tests", role: "worker", requestedBy: "coordinator@dev-laptop" }
- * }, { importance: "high" });
- * ```
- *
- * @module adapters/federation
- */
-
-import type { InboxAdapter, InboxDeliveryEvent } from "./types.js";
-import type { AgentManager } from "../agent/agent-manager.js";
-
-// =============================================================================
-// Federation Config
-// =============================================================================
-
-/**
- * Federation configuration for connecting macro-agent instances.
- */
-export interface FederationConfig {
-  /** Unique system ID for this instance (e.g., "dev-laptop", "ci-server") */
-  systemId: string;
-
-  /** Peer instances to connect to */
-  peers?: FederationPeer[];
-
-  /** Trust policy */
-  trust?: {
-    /** Only accept connections from these system IDs */
-    allowedSystems?: string[];
-  };
-}
-
-export interface FederationPeer {
-  /** System ID of the peer */
-  systemId: string;
-  /** WebSocket URL for the peer's agent-inbox MAP server */
-  url?: string;
-  /** Mesh peer ID for agentic-mesh P2P transport */
-  meshPeerId?: string;
-}
-
-// =============================================================================
-// Remote Spawn Handler
-// =============================================================================
-
-/**
- * Handle incoming remote_spawn_request events from federated instances.
- *
- * When a remote instance sends a spawn request via inbox, this handler
- * spawns the agent locally and sends a confirmation back.
- */
-export function createRemoteSpawnHandler(
-  agentManager: AgentManager,
-  inboxAdapter: InboxAdapter,
-  systemId: string
-) {
-  return async (event: InboxDeliveryEvent) => {
-    const { message } = event;
-    const content = message.content as any;
-
-    // Only handle remote_spawn_request events addressed to "system"
-    if (
-      content?.type !== "event" ||
-      content?.event !== "remote_spawn_request" ||
-      event.agentId !== `system@${systemId}`
-    ) {
-      return;
-    }
-
-    const data = content.data;
-    if (!data?.task) return;
-
-    try {
-      const spawned = await agentManager.spawn({
-        task: data.task,
-        role: data.role,
-        cwd: data.cwd,
-      });
-
-      // Send confirmation back to requester
-      if (data.requestedBy) {
-        await inboxAdapter.send(
-          `system@${systemId}`,
-          data.requestedBy,
-          {
-            type: "event",
-            event: "remote_spawn_response",
-            data: {
-              success: true,
-              agentId: spawned.id,
-              name: spawned.agent.name,
-              role: spawned.agent.role,
-              systemId,
-            },
-          },
-          { importance: "high" }
-        );
-      }
-    } catch (err) {
-      // Send error back to requester
-      if (data.requestedBy) {
-        await inboxAdapter.send(
-          `system@${systemId}`,
-          data.requestedBy,
-          {
-            type: "event",
-            event: "remote_spawn_response",
-            data: {
-              success: false,
-              error: err instanceof Error ? err.message : String(err),
-              systemId,
-            },
-          },
-          { importance: "high" }
-        );
-      }
-    }
-  };
-}
-
-// =============================================================================
-// Federation Helper
-// =============================================================================
-
-/**
- * Set up federation for a macro-agent instance.
- *
- * Registers the remote spawn handler on the inbox adapter's delivery events.
- * Returns a cleanup function.
- */
-export function setupFederation(
-  agentManager: AgentManager,
-  inboxAdapter: InboxAdapter,
-  config: FederationConfig
-): () => void {
-  const handler = createRemoteSpawnHandler(
-    agentManager,
-    inboxAdapter,
-    config.systemId
-  );
-
-  inboxAdapter.onDelivery(handler);
-
-  // Register "system" as a virtual agent for receiving federation requests
-  inboxAdapter.registerAgent(`system@${config.systemId}`, {
-    name: "System",
-    role: "system",
-    scope: "default",
-    metadata: { systemId: config.systemId, federation: true },
-  });
-
-  return () => {
-    inboxAdapter.offDelivery(handler);
-  };
-}