opencode-swarm-plugin 0.25.2 → 0.25.3

package/src/agent-mail.integration.test.ts

@@ -1,1429 +0,0 @@
-/**
- * Integration tests for agent-mail.ts
- *
- * These tests run against a real Agent Mail server (typically in Docker).
- * Set AGENT_MAIL_URL environment variable to override the default server location.
- *
- * Run with: pnpm test:integration
- * Or in Docker: docker compose up --build --abort-on-container-exit
- */
-
-import { describe, it, expect, beforeAll } from "vitest";
-import {
-  mcpCall,
-  mcpCallWithAutoInit,
-  sessionStates,
-  setState,
-  clearState,
-  requireState,
-  MAX_INBOX_LIMIT,
-  AgentMailNotInitializedError,
-  isProjectNotFoundError,
-  isAgentNotFoundError,
-  type AgentMailState,
-} from "./agent-mail";
-
-// ============================================================================
-// Test Configuration
-// ============================================================================
-
-const AGENT_MAIL_URL = process.env.AGENT_MAIL_URL || "http://127.0.0.1:8765";
-
-/**
- * Generate a unique test context to avoid state collisions between tests
- */
-function createTestContext() {
-  const id = `test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-  return {
-    sessionID: id,
-    projectKey: `/test/project-${id}`,
-  };
-}
-
-/**
- * Initialize a test agent and return its state
- */
-async function initTestAgent(
-  ctx: { sessionID: string; projectKey: string },
-  agentName?: string,
-) {
-  // Ensure project exists
-  const project = await mcpCall<{
-    id: number;
-    slug: string;
-    human_key: string;
-  }>("ensure_project", { human_key: ctx.projectKey });
-
-  // Register agent
-  const agent = await mcpCall<{
-    id: number;
-    name: string;
-    program: string;
-    model: string;
-    task_description: string;
-  }>("register_agent", {
-    project_key: ctx.projectKey,
-    program: "opencode-test",
-    model: "test-model",
-    name: agentName,
-    task_description: "Integration test agent",
-  });
-
-  // Store state
-  const state: AgentMailState = {
-    projectKey: ctx.projectKey,
-    agentName: agent.name,
-    reservations: [],
-    startedAt: new Date().toISOString(),
-  };
-  setState(ctx.sessionID, state);
-
-  return { project, agent, state };
-}
-
-// ============================================================================
-// Health Check Tests
-// ============================================================================
-
-describe("agent-mail integration", () => {
-  beforeAll(async () => {
-    // Verify server is reachable before running tests
-    const response = await fetch(`${AGENT_MAIL_URL}/health/liveness`);
-    if (!response.ok) {
-      throw new Error(
-        `Agent Mail server not available at ${AGENT_MAIL_URL}. ` +
-          `Start it with: docker compose up agent-mail`,
-      );
-    }
-  });
-
-  describe("agentmail_health", () => {
-    it("returns healthy when server is running", async () => {
-      const response = await fetch(`${AGENT_MAIL_URL}/health/liveness`);
-      expect(response.ok).toBe(true);
-      const data = await response.json();
-      // Real Agent Mail returns "alive" not "ok"
-      expect(data.status).toBe("alive");
-    });
-
-    it("returns ready when database is accessible", async () => {
-      const response = await fetch(`${AGENT_MAIL_URL}/health/readiness`);
-      expect(response.ok).toBe(true);
-      const data = await response.json();
-      expect(data.status).toBe("ready");
-    });
-  });
-
-  // ============================================================================
-  // Initialization Tests
-  // ============================================================================
-
-  describe("agentmail_init", () => {
-    it("creates project and registers agent", async () => {
-      const ctx = createTestContext();
-
-      const { project, agent, state } = await initTestAgent(ctx);
-
-      expect(project.id).toBeGreaterThan(0);
-      expect(project.human_key).toBe(ctx.projectKey);
-      expect(agent.id).toBeGreaterThan(0);
-      expect(agent.name).toBeTruthy();
-      expect(state.projectKey).toBe(ctx.projectKey);
-      expect(state.agentName).toBe(agent.name);
-
-      // Cleanup
-      clearState(ctx.sessionID);
-    });
-
-    it("generates unique agent name when not provided", async () => {
-      const ctx = createTestContext();
-
-      const { agent: agent1 } = await initTestAgent(ctx);
-      clearState(ctx.sessionID);
-
-      // Register another agent without name
-      const ctx2 = { ...createTestContext(), projectKey: ctx.projectKey };
-      const { agent: agent2 } = await initTestAgent(ctx2);
-
-      // Both should have adjective+noun style names
-      expect(agent1.name).toMatch(/^[A-Z][a-z]+[A-Z][a-z]+$/);
-      expect(agent2.name).toMatch(/^[A-Z][a-z]+[A-Z][a-z]+$/);
-
-      // Cleanup
-      clearState(ctx.sessionID);
-      clearState(ctx2.sessionID);
-    });
-
-    it("uses provided agent name when specified (valid adjective+noun)", async () => {
-      const ctx = createTestContext();
-      // Server has a specific word list - use known-valid combinations
-      // Valid: BlueLake, GreenDog, RedStone, BlueBear
-      const customName = "BlueLake";
-
-      const { agent } = await initTestAgent(ctx, customName);
-
-      expect(agent.name).toBe(customName);
-
-      // Cleanup
-      clearState(ctx.sessionID);
-    });
-
-    it("re-registering same name updates existing agent (dedup by name)", async () => {
-      // Note: Real Agent Mail deduplicates by name within a project
-      // Re-registering with same name updates the existing agent (same ID)
-      const ctx = createTestContext();
-      // Use a valid name from the server's word list
-      const customName = "GreenDog";
-
-      const { agent: agent1 } = await initTestAgent(ctx, customName);
-      clearState(ctx.sessionID);
-
-      // Re-register with same name - updates existing agent
-      const ctx2 = { ...createTestContext(), projectKey: ctx.projectKey };
-      const { agent: agent2 } = await initTestAgent(ctx2, customName);
-
-      // Same name, same ID (updated, not duplicated)
-      expect(agent1.name).toBe(agent2.name);
-      expect(agent1.id).toBe(agent2.id);
-
-      // Cleanup
-      clearState(ctx2.sessionID);
-    });
-  });
-
-  // ============================================================================
-  // State Management Tests
-  // ============================================================================
-
-  describe("state management", () => {
-    it("requireState throws when not initialized", () => {
-      const sessionID = "nonexistent-session";
-
-      expect(() => requireState(sessionID)).toThrow(
-        AgentMailNotInitializedError,
-      );
-    });
-
-    it("requireState returns state when initialized", async () => {
-      const ctx = createTestContext();
-      await initTestAgent(ctx);
-
-      const state = requireState(ctx.sessionID);
-      expect(state.projectKey).toBe(ctx.projectKey);
-
-      // Cleanup
-      clearState(ctx.sessionID);
-    });
-
-    it("clearState removes session state", async () => {
-      const ctx = createTestContext();
-      await initTestAgent(ctx);
-
-      expect(sessionStates.has(ctx.sessionID)).toBe(true);
-      clearState(ctx.sessionID);
-      expect(sessionStates.has(ctx.sessionID)).toBe(false);
-    });
-  });
-
-  // ============================================================================
-  // Messaging Tests
-  // ============================================================================
-
-  describe("agentmail_send", () => {
-    it("sends message to another agent", async () => {
-      const ctx = createTestContext();
-      const { state: senderState } = await initTestAgent(
-        ctx,
-        `Sender_${Date.now()}`,
-      );
-
-      // Create recipient agent
-      const recipientCtx = {
-        ...createTestContext(),
-        projectKey: ctx.projectKey,
-      };
-      const { state: recipientState } = await initTestAgent(
-        recipientCtx,
-        `Recipient_${Date.now()}`,
-      );
-
-      // Send message
-      // Real Agent Mail returns { deliveries: [{ payload: { id, subject, ... } }], count }
-      const result = await mcpCall<{
-        deliveries: Array<{
-          payload: { id: number; subject: string; to: string[] };
-        }>;
-        count: number;
-      }>("send_message", {
-        project_key: senderState.projectKey,
-        sender_name: senderState.agentName,
-        to: [recipientState.agentName],
-        subject: "Test message",
-        body_md: "This is a test message body",
-        thread_id: "bd-test-123",
-        importance: "normal",
-        ack_required: false,
-      });
-
-      expect(result.count).toBe(1);
-      expect(result.deliveries[0].payload.id).toBeGreaterThan(0);
-      expect(result.deliveries[0].payload.subject).toBe("Test message");
-      expect(result.deliveries[0].payload.to).toContain(
-        recipientState.agentName,
-      );
-
-      // Cleanup
-      clearState(ctx.sessionID);
-      clearState(recipientCtx.sessionID);
-    });
-
-    it("sends urgent message with ack_required", async () => {
-      const ctx = createTestContext();
-      const { state: senderState } = await initTestAgent(
-        ctx,
-        `UrgentSender_${Date.now()}`,
-      );
-
-      const recipientCtx = {
-        ...createTestContext(),
-        projectKey: ctx.projectKey,
-      };
-      const { state: recipientState } = await initTestAgent(
-        recipientCtx,
-        `UrgentRecipient_${Date.now()}`,
-      );
-
-      // Real Agent Mail returns { deliveries: [...], count }
-      const result = await mcpCall<{
-        deliveries: Array<{ payload: { id: number } }>;
-        count: number;
-      }>("send_message", {
-        project_key: senderState.projectKey,
-        sender_name: senderState.agentName,
-        to: [recipientState.agentName],
-        subject: "Urgent: Action required",
-        body_md: "Please acknowledge this message",
-        importance: "urgent",
-        ack_required: true,
-      });
-
-      expect(result.count).toBe(1);
-      expect(result.deliveries[0].payload.id).toBeGreaterThan(0);
-
-      // Cleanup
-      clearState(ctx.sessionID);
-      clearState(recipientCtx.sessionID);
-    });
-  });
-
-  // ============================================================================
-  // Inbox Tests
-  // ============================================================================
-
-  describe("agentmail_inbox", () => {
-    it("fetches messages without bodies by default (context-safe)", async () => {
-      const ctx = createTestContext();
-      const { state: senderState } = await initTestAgent(
-        ctx,
-        `InboxSender_${Date.now()}`,
-      );
-
-      const recipientCtx = {
-        ...createTestContext(),
-        projectKey: ctx.projectKey,
-      };
-      const { state: recipientState } = await initTestAgent(
-        recipientCtx,
-        `InboxRecipient_${Date.now()}`,
-      );
-
-      // Send a message
-      await mcpCall("send_message", {
-        project_key: senderState.projectKey,
-        sender_name: senderState.agentName,
-        to: [recipientState.agentName],
-        subject: "Inbox test message",
-        body_md: "This body should NOT be included by default",
-      });
-
-      // Fetch inbox WITHOUT bodies
-      // Real Agent Mail returns { result: [...] } wrapper
-      const response = await mcpCall<{
-        result: Array<{
-          id: number;
-          subject: string;
-          from: string;
-          body_md?: string;
-        }>;
-      }>("fetch_inbox", {
-        project_key: recipientState.projectKey,
-        agent_name: recipientState.agentName,
-        limit: 5,
-        include_bodies: false, // MANDATORY context-safe default
-      });
-
-      const messages = response.result;
-      expect(messages.length).toBeGreaterThan(0);
-      const testMsg = messages.find((m) => m.subject === "Inbox test message");
-      expect(testMsg).toBeDefined();
-      expect(testMsg?.from).toBe(senderState.agentName);
-      // Body should NOT be included when include_bodies: false
-      expect(testMsg?.body_md).toBeUndefined();
-
-      // Cleanup
-      clearState(ctx.sessionID);
-      clearState(recipientCtx.sessionID);
-    });
-
-    it("enforces MAX_INBOX_LIMIT constraint", async () => {
-      const ctx = createTestContext();
-      const { state: senderState } = await initTestAgent(
-        ctx,
-        `LimitSender_${Date.now()}`,
-      );
-
-      const recipientCtx = {
-        ...createTestContext(),
-        projectKey: ctx.projectKey,
-      };
-      const { state: recipientState } = await initTestAgent(
-        recipientCtx,
-        `LimitRecipient_${Date.now()}`,
-      );
-
-      // Send more messages than MAX_INBOX_LIMIT
-      const messageCount = MAX_INBOX_LIMIT + 3;
-      for (let i = 0; i < messageCount; i++) {
-        await mcpCall("send_message", {
-          project_key: senderState.projectKey,
-          sender_name: senderState.agentName,
-          to: [recipientState.agentName],
-          subject: `Limit test message ${i}`,
-          body_md: `Message body ${i}`,
-        });
-      }
-
-      // Request more than MAX_INBOX_LIMIT
-      const response = await mcpCall<{ result: Array<{ id: number }> }>(
-        "fetch_inbox",
-        {
-          project_key: recipientState.projectKey,
-          agent_name: recipientState.agentName,
-          limit: messageCount, // Request more than allowed
-          include_bodies: false,
-        },
-      );
-
-      // Should still return the requested amount from server
-      // The constraint enforcement happens in the tool wrapper, not mcpCall
-      expect(response.result.length).toBeGreaterThanOrEqual(MAX_INBOX_LIMIT);
-
-      // Cleanup
-      clearState(ctx.sessionID);
-      clearState(recipientCtx.sessionID);
-    });
-
-    it("filters urgent messages when urgent_only is true", async () => {
-      const ctx = createTestContext();
-      const { state: senderState } = await initTestAgent(
-        ctx,
-        `UrgentFilterSender_${Date.now()}`,
-      );
-
-      const recipientCtx = {
-        ...createTestContext(),
-        projectKey: ctx.projectKey,
-      };
-      const { state: recipientState } = await initTestAgent(
-        recipientCtx,
-        `UrgentFilterRecipient_${Date.now()}`,
-      );
-
-      // Send normal and urgent messages
-      await mcpCall("send_message", {
-        project_key: senderState.projectKey,
-        sender_name: senderState.agentName,
-        to: [recipientState.agentName],
-        subject: "Normal message",
-        body_md: "Not urgent",
-        importance: "normal",
-      });
-
-      await mcpCall("send_message", {
-        project_key: senderState.projectKey,
-        sender_name: senderState.agentName,
-        to: [recipientState.agentName],
-        subject: "Urgent message",
-        body_md: "Very urgent!",
-        importance: "urgent",
-      });
-
-      // Fetch only urgent messages
-      const response = await mcpCall<{
-        result: Array<{ subject: string; importance: string }>;
-      }>("fetch_inbox", {
-        project_key: recipientState.projectKey,
-        agent_name: recipientState.agentName,
-        limit: 10,
-        include_bodies: false,
-        urgent_only: true,
-      });
-
-      const messages = response.result;
-      // All returned messages should be urgent
-      for (const msg of messages) {
-        expect(msg.importance).toBe("urgent");
-      }
-      expect(messages.some((m) => m.subject === "Urgent message")).toBe(true);
-
-      // Cleanup
-      clearState(ctx.sessionID);
-      clearState(recipientCtx.sessionID);
-    });
-
-    it("filters by since_ts timestamp", async () => {
-      const ctx = createTestContext();
-      const { state: senderState } = await initTestAgent(
-        ctx,
-        `TimeSender_${Date.now()}`,
-      );
-
-      const recipientCtx = {
-        ...createTestContext(),
-        projectKey: ctx.projectKey,
-      };
-      const { state: recipientState } = await initTestAgent(
-        recipientCtx,
-        `TimeRecipient_${Date.now()}`,
-      );
-
-      // Send first message
-      await mcpCall("send_message", {
-        project_key: senderState.projectKey,
-        sender_name: senderState.agentName,
-        to: [recipientState.agentName],
-        subject: "Old message",
-        body_md: "Sent before timestamp",
-      });
-
-      // Wait a moment and capture timestamp
-      await new Promise((resolve) => setTimeout(resolve, 100));
-      const sinceTs = new Date().toISOString();
-      await new Promise((resolve) => setTimeout(resolve, 100));
-
-      // Send second message after timestamp
-      await mcpCall("send_message", {
-        project_key: senderState.projectKey,
-        sender_name: senderState.agentName,
-        to: [recipientState.agentName],
-        subject: "New message",
-        body_md: "Sent after timestamp",
-      });
-
-      // Fetch only messages after timestamp
-      const response = await mcpCall<{
-        result: Array<{ subject: string }>;
-      }>("fetch_inbox", {
-        project_key: recipientState.projectKey,
-        agent_name: recipientState.agentName,
-        limit: 10,
-        include_bodies: false,
-        since_ts: sinceTs,
-      });
-
-      const messages = response.result;
-      expect(messages.some((m) => m.subject === "New message")).toBe(true);
-      expect(messages.some((m) => m.subject === "Old message")).toBe(false);
-
-      // Cleanup
-      clearState(ctx.sessionID);
-      clearState(recipientCtx.sessionID);
-    });
-  });
-
-  // ============================================================================
-  // Read Message Tests
-  // ============================================================================
-
-  describe("agentmail_read_message", () => {
-    it("marks message as read", async () => {
-      const ctx = createTestContext();
-      const { state: senderState } = await initTestAgent(
-        ctx,
-        `ReadSender_${Date.now()}`,
-      );
-
-      const recipientCtx = {
-        ...createTestContext(),
-        projectKey: ctx.projectKey,
-      };
-      const { state: recipientState } = await initTestAgent(
-        recipientCtx,
-        `ReadRecipient_${Date.now()}`,
-      );
-
-      // Send a message
-      // Real Agent Mail returns { deliveries: [{ payload: { id, ... } }] }
-      const sentMsg = await mcpCall<{
-        deliveries: Array<{ payload: { id: number } }>;
-      }>("send_message", {
-        project_key: senderState.projectKey,
-        sender_name: senderState.agentName,
-        to: [recipientState.agentName],
-        subject: "Read test message",
-        body_md: "This message will be marked as read",
-      });
-
-      const messageId = sentMsg.deliveries[0].payload.id;
-
-      // Mark as read
-      // Real Agent Mail returns { message_id, read: bool, read_at: iso8601 | null }
-      const result = await mcpCall<{
-        message_id: number;
-        read: boolean;
-        read_at: string | null;
-      }>("mark_message_read", {
-        project_key: recipientState.projectKey,
-        agent_name: recipientState.agentName,
-        message_id: messageId,
-      });
-
-      expect(result.message_id).toBe(messageId);
-      expect(result.read).toBe(true);
-      expect(result.read_at).toBeTruthy();
-
-      // Cleanup
-      clearState(ctx.sessionID);
-      clearState(recipientCtx.sessionID);
-    });
-  });
-
-  // ============================================================================
-  // Thread Summary Tests
-  // ============================================================================
-
-  describe("agentmail_summarize_thread", () => {
-    // Skip: summarize_thread requires LLM which may not be available
-    it.skip("summarizes messages in a thread", async () => {
-      const ctx = createTestContext();
-      const { state: senderState } = await initTestAgent(
-        ctx,
-        `ThreadSender_${Date.now()}`,
-      );
-
-      const recipientCtx = {
-        ...createTestContext(),
-        projectKey: ctx.projectKey,
-      };
-      const { state: recipientState } = await initTestAgent(
-        recipientCtx,
-        `ThreadRecipient_${Date.now()}`,
-      );
-
-      const threadId = `thread-${Date.now()}`;
-
-      // Send multiple messages in the same thread
-      await mcpCall("send_message", {
-        project_key: senderState.projectKey,
-        sender_name: senderState.agentName,
-        to: [recipientState.agentName],
-        subject: "Thread message 1",
-        body_md: "First message in thread",
-        thread_id: threadId,
-      });
-
-      await mcpCall("send_message", {
-        project_key: senderState.projectKey,
-        sender_name: senderState.agentName,
-        to: [recipientState.agentName],
-        subject: "Thread message 2",
-        body_md: "Second message in thread",
-        thread_id: threadId,
-      });
-
-      // Get thread summary
-      const summary = await mcpCall<{
-        thread_id: string;
-        summary: {
-          participants: string[];
-          key_points: string[];
-          action_items: string[];
-          total_messages: number;
-        };
-      }>("summarize_thread", {
-        project_key: senderState.projectKey,
-        thread_id: threadId,
-        include_examples: false,
-      });
-
-      expect(summary.thread_id).toBe(threadId);
-      expect(summary.summary.participants).toContain(senderState.agentName);
-      expect(summary.summary.total_messages).toBe(2);
-      expect(summary.summary.key_points.length).toBeGreaterThan(0);
-
-      // Cleanup
-      clearState(ctx.sessionID);
-      clearState(recipientCtx.sessionID);
-    });
-
-    // Skip: summarize_thread requires LLM which may not be available
-    it.skip("includes example messages when requested", async () => {
-      const ctx = createTestContext();
-      const { state: senderState } = await initTestAgent(
-        ctx,
-        `ExampleSender_${Date.now()}`,
-      );
-
-      const recipientCtx = {
-        ...createTestContext(),
-        projectKey: ctx.projectKey,
-      };
-      const { state: recipientState } = await initTestAgent(
-        recipientCtx,
-        `ExampleRecipient_${Date.now()}`,
-      );
-
-      const threadId = `example-thread-${Date.now()}`;
-
-      await mcpCall("send_message", {
-        project_key: senderState.projectKey,
-        sender_name: senderState.agentName,
-        to: [recipientState.agentName],
-        subject: "Example thread message",
-        body_md: "This should be in examples",
-        thread_id: threadId,
-      });
-
-      // Get summary with examples
-      const summary = await mcpCall<{
-        thread_id: string;
-        examples?: Array<{
-          id: number;
-          subject: string;
-          from: string;
-          body_md?: string;
-        }>;
-      }>("summarize_thread", {
-        project_key: senderState.projectKey,
-        thread_id: threadId,
-        include_examples: true,
-      });
-
-      expect(summary.examples).toBeDefined();
-      expect(summary.examples!.length).toBeGreaterThan(0);
-      expect(summary.examples![0].subject).toBe("Example thread message");
-      expect(summary.examples![0].body_md).toBe("This should be in examples");
-
-      // Cleanup
-      clearState(ctx.sessionID);
-      clearState(recipientCtx.sessionID);
-    });
-  });
-
-  // ============================================================================
-  // File Reservation Tests
-  // ============================================================================
-
-  describe("agentmail_reserve", () => {
-    it("grants file reservations", async () => {
-      const ctx = createTestContext();
-      const { state } = await initTestAgent(ctx, `ReserveAgent_${Date.now()}`);
-
-      const result = await mcpCall<{
-        granted: Array<{
-          id: number;
-          path_pattern: string;
-          exclusive: boolean;
-          reason: string;
-          expires_ts: string;
-        }>;
-        conflicts: Array<{ path: string; holders: string[] }>;
-      }>("file_reservation_paths", {
-        project_key: state.projectKey,
-        agent_name: state.agentName,
-        paths: ["src/auth/**", "src/config.ts"],
-        ttl_seconds: 3600,
-        exclusive: true,
-        reason: "bd-test-123: Working on auth",
-      });
-
-      expect(result.granted.length).toBe(2);
-      expect(result.conflicts.length).toBe(0);
-      expect(result.granted[0].exclusive).toBe(true);
-      expect(result.granted[0].reason).toContain("bd-test-123");
-
-      // Cleanup
-      clearState(ctx.sessionID);
-    });
-
-    it("detects conflicts with exclusive reservations", async () => {
-      const ctx = createTestContext();
-      const { state: agent1State } = await initTestAgent(
-        ctx,
-        `ConflictAgent1_${Date.now()}`,
-      );
-
-      const agent2Ctx = { ...createTestContext(), projectKey: ctx.projectKey };
-      const { state: agent2State } = await initTestAgent(
-        agent2Ctx,
-        `ConflictAgent2_${Date.now()}`,
-      );
-
-      const conflictPath = `src/conflict-${Date.now()}.ts`;
-
-      // Agent 1 reserves the file
-      const result1 = await mcpCall<{
-        granted: Array<{ id: number }>;
-        conflicts: Array<{ path: string; holders: string[] }>;
-      }>("file_reservation_paths", {
-        project_key: agent1State.projectKey,
-        agent_name: agent1State.agentName,
-        paths: [conflictPath],
-        ttl_seconds: 3600,
-        exclusive: true,
-      });
-
-      expect(result1.granted.length).toBe(1);
-      expect(result1.conflicts.length).toBe(0);
-
-      // Agent 2 tries to reserve the same file
-      // Real Agent Mail GRANTS the reservation but ALSO reports conflicts
-      // This is the expected behavior - it's a warning, not a block
-      const result2 = await mcpCall<{
-        granted: Array<{ id: number }>;
-        conflicts: Array<{
-          path: string;
-          holders: Array<{ agent: string; path_pattern: string }>;
-        }>;
-      }>("file_reservation_paths", {
-        project_key: agent2State.projectKey,
-        agent_name: agent2State.agentName,
-        paths: [conflictPath],
-        ttl_seconds: 3600,
-        exclusive: true,
-      });
-
-      // Server grants the reservation but reports conflicts
-      expect(result2.granted.length).toBe(1);
-      expect(result2.conflicts.length).toBe(1);
-      expect(result2.conflicts[0].path).toBe(conflictPath);
-      // holders is an array of objects with agent field
-      expect(
-        result2.conflicts[0].holders.some(
-          (h) => h.agent === agent1State.agentName,
-        ),
-      ).toBe(true);
-
-      // Cleanup
-      clearState(ctx.sessionID);
-      clearState(agent2Ctx.sessionID);
-    });
-
-    it("stores reservation IDs in state", async () => {
-      const ctx = createTestContext();
-      const { state } = await initTestAgent(ctx, `StateAgent_${Date.now()}`);
-
-      const result = await mcpCall<{
-        granted: Array<{ id: number }>;
-      }>("file_reservation_paths", {
-        project_key: state.projectKey,
-        agent_name: state.agentName,
-        paths: ["src/state-test.ts"],
-        ttl_seconds: 3600,
-        exclusive: true,
-      });
-
-      // Manually track reservations like the tool does
-      const reservationIds = result.granted.map((r) => r.id);
-      state.reservations = [...state.reservations, ...reservationIds];
-      setState(ctx.sessionID, state);
-
-      // Verify state was updated
-      const updatedState = requireState(ctx.sessionID);
-      expect(updatedState.reservations.length).toBeGreaterThan(0);
-      expect(updatedState.reservations).toContain(result.granted[0].id);
-
-      // Cleanup
-      clearState(ctx.sessionID);
-    });
-  });
-
-  // ============================================================================
-  // Release Reservation Tests
-  // ============================================================================
-
-  describe("agentmail_release", () => {
-    it("releases all reservations for an agent", async () => {
-      const ctx = createTestContext();
-      const { state } = await initTestAgent(ctx, `ReleaseAgent_${Date.now()}`);
-
-      // Create reservations
-      await mcpCall("file_reservation_paths", {
-        project_key: state.projectKey,
-        agent_name: state.agentName,
-        paths: ["src/release-test-1.ts", "src/release-test-2.ts"],
-        ttl_seconds: 3600,
-        exclusive: true,
-      });
-
-      // Release all
-      const result = await mcpCall<{ released: number; released_at: string }>(
-        "release_file_reservations",
-        {
-          project_key: state.projectKey,
-          agent_name: state.agentName,
-        },
-      );
-
-      expect(result.released).toBe(2);
-      expect(result.released_at).toBeTruthy();
-
-      // Cleanup
-      clearState(ctx.sessionID);
-    });
-
-    it("releases specific paths only", async () => {
-      const ctx = createTestContext();
-      const { state } = await initTestAgent(
-        ctx,
-        `SpecificReleaseAgent_${Date.now()}`,
-      );
-
-      const path1 = `src/specific-release-1-${Date.now()}.ts`;
-      const path2 = `src/specific-release-2-${Date.now()}.ts`;
-
-      // Create reservations
-      await mcpCall("file_reservation_paths", {
-        project_key: state.projectKey,
-        agent_name: state.agentName,
-        paths: [path1, path2],
-        ttl_seconds: 3600,
-        exclusive: true,
-      });
-
-      // Release only one path
-      const result = await mcpCall<{ released: number }>(
-        "release_file_reservations",
-        {
-          project_key: state.projectKey,
-          agent_name: state.agentName,
-          paths: [path1],
-        },
-      );
-
-      expect(result.released).toBe(1);
-
-      // Verify second path can still cause conflicts
-      const agent2Ctx = { ...createTestContext(), projectKey: ctx.projectKey };
-      const { state: agent2State } = await initTestAgent(
-        agent2Ctx,
-        `SpecificReleaseAgent2_${Date.now()}`,
-      );
-
-      const conflictResult = await mcpCall<{
-        conflicts: Array<{ path: string }>;
-      }>("file_reservation_paths", {
-        project_key: agent2State.projectKey,
-        agent_name: agent2State.agentName,
-        paths: [path2],
-        exclusive: true,
-      });
-
-      expect(conflictResult.conflicts.length).toBe(1);
-
-      // Cleanup
-      clearState(ctx.sessionID);
-      clearState(agent2Ctx.sessionID);
-    });
-
-    it("releases by reservation IDs", async () => {
-      const ctx = createTestContext();
-      const { state } = await initTestAgent(
-        ctx,
-        `IdReleaseAgent_${Date.now()}`,
-      );
-
-      // Create reservations
-      const reserveResult = await mcpCall<{
-        granted: Array<{ id: number }>;
-      }>("file_reservation_paths", {
-        project_key: state.projectKey,
-        agent_name: state.agentName,
-        paths: ["src/id-release-1.ts", "src/id-release-2.ts"],
-        ttl_seconds: 3600,
-        exclusive: true,
-      });
-
-      const firstId = reserveResult.granted[0].id;
-
-      // Release by ID
-      const result = await mcpCall<{ released: number }>(
-        "release_file_reservations",
-        {
-          project_key: state.projectKey,
-          agent_name: state.agentName,
-          file_reservation_ids: [firstId],
-        },
-      );
-
-      expect(result.released).toBe(1);
-
-      // Cleanup
-      clearState(ctx.sessionID);
-    });
-  });
-
-  // ============================================================================
-  // Acknowledge Message Tests
-  // ============================================================================
-
-  describe("agentmail_ack", () => {
-    it("acknowledges a message requiring acknowledgement", async () => {
-      const ctx = createTestContext();
-      const { state: senderState } = await initTestAgent(
-        ctx,
-        `AckSender_${Date.now()}`,
-      );
-
-      const recipientCtx = {
-        ...createTestContext(),
-        projectKey: ctx.projectKey,
-      };
-      const { state: recipientState } = await initTestAgent(
-        recipientCtx,
-        `AckRecipient_${Date.now()}`,
-      );
-
-      // Send message requiring ack
-      // Real Agent Mail returns { deliveries: [{ payload: { id, ... } }] }
-      const sentMsg = await mcpCall<{
-        deliveries: Array<{ payload: { id: number } }>;
-      }>("send_message", {
-        project_key: senderState.projectKey,
-        sender_name: senderState.agentName,
-        to: [recipientState.agentName],
-        subject: "Please acknowledge",
-        body_md: "This requires acknowledgement",
-        ack_required: true,
-      });
-
-      const messageId = sentMsg.deliveries[0].payload.id;
-
-      // Acknowledge
-      // Real Agent Mail returns { acknowledged: bool, acknowledged_at: iso8601 | null }
-      const result = await mcpCall<{
-        message_id: number;
-        acknowledged: boolean;
-        acknowledged_at: string | null;
-      }>("acknowledge_message", {
-        project_key: recipientState.projectKey,
-        agent_name: recipientState.agentName,
-        message_id: messageId,
-      });
-
-      expect(result.message_id).toBe(messageId);
-      expect(result.acknowledged).toBe(true);
-      expect(result.acknowledged_at).toBeTruthy();
-
-      // Cleanup
-      clearState(ctx.sessionID);
-      clearState(recipientCtx.sessionID);
-    });
-  });
-
-  // ============================================================================
-  // Search Tests
-  // ============================================================================
-
-  describe("agentmail_search", () => {
-    it("searches messages by keyword using FTS5", async () => {
-      const ctx = createTestContext();
-      const { state: senderState } = await initTestAgent(
-        ctx,
-        `SearchSender_${Date.now()}`,
-      );
-
-      const recipientCtx = {
-        ...createTestContext(),
-        projectKey: ctx.projectKey,
-      };
-      const { state: recipientState } = await initTestAgent(
-        recipientCtx,
-        `SearchRecipient_${Date.now()}`,
-      );
-
-      const uniqueKeyword = `unicorn${Date.now()}`;
-
-      // Send messages with searchable content
-      await mcpCall("send_message", {
-        project_key: senderState.projectKey,
-        sender_name: senderState.agentName,
-        to: [recipientState.agentName],
-        subject: `Message about ${uniqueKeyword}`,
-        body_md: "This message contains the keyword",
-      });
-
-      await mcpCall("send_message", {
-        project_key: senderState.projectKey,
-        sender_name: senderState.agentName,
-        to: [recipientState.agentName],
-        subject: "Unrelated message",
-        body_md: "This message is about something else",
-      });
-
-      // Search
-      // Real Agent Mail returns { result: [...] }
-      const response = await mcpCall<{
-        result: Array<{ id: number; subject: string }>;
-      }>("search_messages", {
-        project_key: senderState.projectKey,
-        query: uniqueKeyword,
-        limit: 10,
-      });
-
-      const results = response.result;
-      expect(results.length).toBeGreaterThan(0);
-      expect(results.every((r) => r.subject.includes(uniqueKeyword))).toBe(
-        true,
-      );
-
-      // Cleanup
-      clearState(ctx.sessionID);
-      clearState(recipientCtx.sessionID);
-    });
-
-    it("respects search limit", async () => {
-      const ctx = createTestContext();
-      const { state: senderState } = await initTestAgent(
-        ctx,
-        `LimitSearchSender_${Date.now()}`,
-      );
-
-      const recipientCtx = {
-        ...createTestContext(),
-        projectKey: ctx.projectKey,
-      };
-      const { state: recipientState } = await initTestAgent(
-        recipientCtx,
-        `LimitSearchRecipient_${Date.now()}`,
-      );
-
-      const keyword = `searchlimit${Date.now()}`;
-
-      // Send multiple matching messages
-      for (let i = 0; i < 5; i++) {
-        await mcpCall("send_message", {
-          project_key: senderState.projectKey,
-          sender_name: senderState.agentName,
-          to: [recipientState.agentName],
-          subject: `${keyword} message ${i}`,
-          body_md: `Content with ${keyword}`,
-        });
-      }
-
-      // Search with limit
-      // Real Agent Mail returns { result: [...] }
-      const response = await mcpCall<{
-        result: Array<{ id: number }>;
-      }>("search_messages", {
-        project_key: senderState.projectKey,
-        query: keyword,
-        limit: 2,
-      });
-
-      expect(response.result.length).toBe(2);
-
-      // Cleanup
-      clearState(ctx.sessionID);
-      clearState(recipientCtx.sessionID);
-    });
-  });
-
-  // ============================================================================
-  // Error Handling Tests
-  // ============================================================================
-
-  describe("error handling", () => {
-    it("throws on unknown tool", async () => {
-      // Real Agent Mail returns isError: true which mcpCall converts to throw
-      await expect(mcpCall("nonexistent_tool", {})).rejects.toThrow(
-        /Unknown tool/,
-      );
-    });
-
-    it("throws on missing required parameters", async () => {
-      // Real Agent Mail returns validation error with isError: true
-      await expect(mcpCall("ensure_project", {})).rejects.toThrow(
-        /Missing required argument|validation error/,
-      );
-    });
-
-    it("throws on invalid project reference", async () => {
-      // Real Agent Mail auto-creates projects, so this actually succeeds
-      // Instead test with a truly invalid operation
-      await expect(
-        mcpCall("register_agent", {
-          // Missing required project_key
-          program: "test",
-          model: "test",
-        }),
-      ).rejects.toThrow(/Missing required argument|validation error/);
-    });
-  });
-
-  // ============================================================================
-  // Multi-Agent Coordination Tests
-  // ============================================================================
-
-  describe("multi-agent coordination", () => {
-    it("enables communication between multiple agents", async () => {
-      const ctx = createTestContext();
-
-      // Create 3 agents in the same project
-      const agent1Ctx = ctx;
-      const { state: agent1 } = await initTestAgent(
-        agent1Ctx,
-        `Coordinator_${Date.now()}`,
-      );
-
-      const agent2Ctx = { ...createTestContext(), projectKey: ctx.projectKey };
-      const { state: agent2 } = await initTestAgent(
-        agent2Ctx,
-        `Worker1_${Date.now()}`,
-      );
-
-      const agent3Ctx = { ...createTestContext(), projectKey: ctx.projectKey };
-      const { state: agent3 } = await initTestAgent(
-        agent3Ctx,
-        `Worker2_${Date.now()}`,
-      );
-
-      // Coordinator broadcasts to workers
-      await mcpCall("send_message", {
-        project_key: agent1.projectKey,
-        sender_name: agent1.agentName,
-        to: [agent2.agentName, agent3.agentName],
-        subject: "Task assignment",
-        body_md: "Please complete your subtasks",
-        thread_id: "bd-epic-123",
-        importance: "high",
-      });
-
-      // Verify both workers received the message
-      const worker1Response = await mcpCall<{
-        result: Array<{ subject: string }>;
-      }>("fetch_inbox", {
-        project_key: agent2.projectKey,
-        agent_name: agent2.agentName,
-        limit: 5,
-        include_bodies: false,
-      });
-
-      const worker2Response = await mcpCall<{
-        result: Array<{ subject: string }>;
-      }>("fetch_inbox", {
-        project_key: agent3.projectKey,
-        agent_name: agent3.agentName,
-        limit: 5,
-        include_bodies: false,
-      });
-
-      expect(
-        worker1Response.result.some((m) => m.subject === "Task assignment"),
-      ).toBe(true);
-      expect(
-        worker2Response.result.some((m) => m.subject === "Task assignment"),
-      ).toBe(true);
-
-      // Cleanup
-      clearState(agent1Ctx.sessionID);
-      clearState(agent2Ctx.sessionID);
-      clearState(agent3Ctx.sessionID);
-    });
-
-    it("prevents file conflicts in swarm scenarios", async () => {
-      const ctx = createTestContext();
-
-      // Coordinator assigns different files to workers
-      const coordCtx = ctx;
-      await initTestAgent(coordCtx, `SwarmCoord_${Date.now()}`);
-
-      const worker1Ctx = { ...createTestContext(), projectKey: ctx.projectKey };
-      const { state: worker1 } = await initTestAgent(
-        worker1Ctx,
-        `SwarmWorker1_${Date.now()}`,
-      );
-
-      const worker2Ctx = { ...createTestContext(), projectKey: ctx.projectKey };
-      const { state: worker2 } = await initTestAgent(
-        worker2Ctx,
-        `SwarmWorker2_${Date.now()}`,
-      );
-
-      const path1 = `src/swarm/file1-${Date.now()}.ts`;
-      const path2 = `src/swarm/file2-${Date.now()}.ts`;
-
-      // Worker 1 reserves file 1
-      const res1 = await mcpCall<{
-        granted: Array<{ id: number }>;
-        conflicts: unknown[];
-      }>("file_reservation_paths", {
-        project_key: worker1.projectKey,
-        agent_name: worker1.agentName,
-        paths: [path1],
-        exclusive: true,
-        reason: "bd-subtask-1",
-      });
-
-      // Worker 2 reserves file 2
-      const res2 = await mcpCall<{
-        granted: Array<{ id: number }>;
-        conflicts: unknown[];
-      }>("file_reservation_paths", {
-        project_key: worker2.projectKey,
-        agent_name: worker2.agentName,
-        paths: [path2],
-        exclusive: true,
-        reason: "bd-subtask-2",
-      });
-
-      // Both should succeed (no conflicts)
-      expect(res1.granted.length).toBe(1);
-      expect(res1.conflicts.length).toBe(0);
-      expect(res2.granted.length).toBe(1);
-      expect(res2.conflicts.length).toBe(0);
-
-      // Worker 1 tries to reserve file 2 (should conflict)
-      // Real Agent Mail returns holders as array of objects with agent field
-      const conflict = await mcpCall<{
-        conflicts: Array<{
-          path: string;
-          holders: Array<{ agent: string; path_pattern: string }>;
-        }>;
-      }>("file_reservation_paths", {
-        project_key: worker1.projectKey,
-        agent_name: worker1.agentName,
-        paths: [path2],
-        exclusive: true,
-      });
-
-      expect(conflict.conflicts.length).toBe(1);
-      // holders is an array of objects with agent field
-      expect(
-        conflict.conflicts[0].holders.some(
-          (h) => h.agent === worker2.agentName,
-        ),
-      ).toBe(true);
-
-      // Cleanup
-      clearState(coordCtx.sessionID);
-      clearState(worker1Ctx.sessionID);
-      clearState(worker2Ctx.sessionID);
-    });
-  });
-
-  // ============================================================================
-  // Self-Healing Tests (mcpCallWithAutoInit)
-  // ============================================================================
-
-  describe("self-healing (mcpCallWithAutoInit)", () => {
-    it("detects project not found errors correctly", () => {
-      const projectError = new Error("Project 'migrate-egghead' not found.");
-      const agentError = new Error("Agent 'BlueLake' not found in project");
-      const otherError = new Error("Network timeout");
-
-      expect(isProjectNotFoundError(projectError)).toBe(true);
-      expect(isProjectNotFoundError(agentError)).toBe(false);
-      expect(isProjectNotFoundError(otherError)).toBe(false);
-
-      expect(isAgentNotFoundError(agentError)).toBe(true);
-      expect(isAgentNotFoundError(projectError)).toBe(false);
-      expect(isAgentNotFoundError(otherError)).toBe(false);
-    });
-
-    it("auto-registers project on 'not found' error", async () => {
-      const ctx = createTestContext();
-
-      // First, ensure project exists and register an agent
-      const { state } = await initTestAgent(ctx, `AutoInit_${Date.now()}`);
-
-      // Now use mcpCallWithAutoInit - it should work normally
-      // (no error to recover from, but verifies the wrapper works)
-      await mcpCallWithAutoInit("send_message", {
-        project_key: state.projectKey,
-        agent_name: state.agentName,
-        sender_name: state.agentName,
-        to: [],
-        subject: "Test auto-init wrapper",
-        body_md: "This should work normally",
-        thread_id: "test-thread",
-        importance: "normal",
-      });
-
-      // Verify message was sent by checking inbox
-      const inbox = await mcpCall<Array<{ subject: string }>>("fetch_inbox", {
-        project_key: state.projectKey,
-        agent_name: state.agentName,
-        limit: 5,
-        include_bodies: false,
-      });
-
-      // The message should be in the inbox (sent to empty 'to' = broadcast)
-      // Note: depending on Agent Mail behavior, broadcast might not show in sender's inbox
-      // This test mainly verifies the wrapper doesn't break normal operation
-
-      // Cleanup
-      clearState(ctx.sessionID);
-    });
-
-    it("recovers from simulated project not found by re-registering", async () => {
-      const ctx = createTestContext();
-
-      // Create a fresh project key that doesn't exist yet
-      const freshProjectKey = `/test/fresh-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-      const agentName = `Recovery_${Date.now()}`;
-
-      // First ensure the project exists (simulating initial setup)
-      await mcpCall("ensure_project", { human_key: freshProjectKey });
-      await mcpCall("register_agent", {
-        project_key: freshProjectKey,
-        program: "opencode-test",
-        model: "test-model",
-        name: agentName,
-        task_description: "Recovery test agent",
-      });
-
-      // Now use mcpCallWithAutoInit for an operation
-      // This should work, and if the project somehow got lost, it would re-register
-      await mcpCallWithAutoInit("send_message", {
-        project_key: freshProjectKey,
-        agent_name: agentName,
-        sender_name: agentName,
-        to: [],
-        subject: "Recovery test",
-        body_md: "Testing self-healing",
-        thread_id: "recovery-test",
-        importance: "normal",
-      });
-
-      // If we got here without error, the wrapper is working
-      // (In a real scenario where the server restarted, it would have re-registered)
-    });
-
-    it("passes through non-recoverable errors", async () => {
-      const ctx = createTestContext();
-      const { state } = await initTestAgent(ctx, `ErrorPass_${Date.now()}`);
-
-      // Try to call a non-existent tool - should throw, not retry forever
-      await expect(
-        mcpCallWithAutoInit("nonexistent_tool_xyz", {
-          project_key: state.projectKey,
-          agent_name: state.agentName,
-        }),
-      ).rejects.toThrow(/Unknown tool/);
-
-      // Cleanup
-      clearState(ctx.sessionID);
-    });
-  });
-});