swarm-mail 0.1.0 → 0.1.3

package/src/streams/effect/ask.integration.test.ts

@@ -1,314 +0,0 @@
-/**
- * Ask Pattern Integration Tests
- *
- * Tests request/response communication between agents using
- * DurableMailbox + DurableDeferred pattern.
- */
-
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { Effect } from "effect";
-import { ask, respond, askWithMailbox } from "./ask";
-import { DurableMailbox } from "./mailbox";
-import { DurableDeferred } from "./deferred";
-import { DurableAskLive } from "./layers";
-import { resetDatabase, closeDatabase } from "../index";
-import { randomUUID } from "node:crypto";
-
-// ============================================================================
-// Test Fixtures
-// ============================================================================
-
-interface TestRequest {
-  action: string;
-  userId: number;
-}
-
-interface TestResponse {
-  status: "success" | "error";
-  data?: unknown;
-  message?: string;
-}
-
-// ============================================================================
-// Setup/Teardown
-// ============================================================================
-
-let testDbPath: string;
-
-beforeEach(async () => {
-  testDbPath = `/tmp/ask-test-${randomUUID()}`;
-  await resetDatabase(testDbPath);
-});
-
-afterEach(async () => {
-  await closeDatabase(testDbPath);
-});
-
-// ============================================================================
-// Tests
-// ============================================================================
-
-describe("Ask Pattern", () => {
-  it("should send request and receive response via ask()", async () => {
-    const program = Effect.gen(function* () {
-      const mailboxService = yield* DurableMailbox;
-
-      // Create mailboxes for both agents
-      const agentA = yield* mailboxService.create({
-        agent: "agent-a",
-        projectKey: "test-proj",
-        projectPath: testDbPath,
-      });
-
-      const agentB = yield* mailboxService.create({
-        agent: "agent-b",
-        projectKey: "test-proj",
-        projectPath: testDbPath,
-      });
-
-      // Agent B: Listen for request and respond
-      const responder = Effect.promise(async () => {
-        for await (const envelope of agentB.receive<TestRequest>()) {
-          expect(envelope.payload.action).toBe("getUserData");
-          expect(envelope.payload.userId).toBe(123);
-          expect(envelope.replyTo).toBeDefined();
-
-          // Send response
-          await Effect.runPromise(
-            respond<TestResponse>(
-              envelope,
-              {
-                status: "success",
-                data: { username: "testuser", id: 123 },
-              },
-              testDbPath,
-            ).pipe(Effect.provide(DurableAskLive)),
-          );
-
-          await Effect.runPromise(envelope.commit());
-          break; // Exit after first message
-        }
-      });
-
-      // Start responder in background
-      Effect.runFork(responder.pipe(Effect.provide(DurableAskLive)));
-
-      // Agent A: Send request via ask()
-      const response = yield* ask<TestRequest, TestResponse>({
-        mailbox: agentA,
-        to: "agent-b",
-        payload: { action: "getUserData", userId: 123 },
-        ttlSeconds: 5,
-      });
-
-      expect(response.status).toBe("success");
-      expect(response.data).toEqual({ username: "testuser", id: 123 });
-
-      return response;
-    }).pipe(Effect.provide(DurableAskLive));
-
-    const result = await Effect.runPromise(program);
-    expect(result.status).toBe("success");
-  });
-
-  it("should timeout when no response received", async () => {
-    const program = Effect.gen(function* () {
-      const mailboxService = yield* DurableMailbox;
-
-      const agentA = yield* mailboxService.create({
-        agent: "agent-a",
-        projectKey: "test-proj",
-        projectPath: testDbPath,
-      });
-
-      // No one listening, should timeout after 1 second
-      const response = yield* ask<TestRequest, TestResponse>({
-        mailbox: agentA,
-        to: "agent-b-nonexistent",
-        payload: { action: "getUserData", userId: 123 },
-        ttlSeconds: 1,
-      });
-
-      return response;
-    }).pipe(Effect.provide(DurableAskLive));
-
-    // Expect timeout error
-    const result = await Effect.runPromise(Effect.either(program));
-    expect(result._tag).toBe("Left");
-    if (result._tag === "Left") {
-      expect(result.left).toHaveProperty("_tag", "TimeoutError");
-    }
-  });
-
-  it("should support askWithMailbox for one-off requests", async () => {
-    const program = Effect.gen(function* () {
-      const mailboxService = yield* DurableMailbox;
-
-      // Agent B: Listen for request
-      const agentB = yield* mailboxService.create({
-        agent: "agent-b",
-        projectKey: "test-proj",
-        projectPath: testDbPath,
-      });
-
-      const responder = Effect.promise(async () => {
-        for await (const envelope of agentB.receive<TestRequest>()) {
-          await Effect.runPromise(
-            respond<TestResponse>(
-              envelope,
-              { status: "success", message: "One-off response" },
-              testDbPath,
-            ).pipe(Effect.provide(DurableAskLive)),
-          );
-          await Effect.runPromise(envelope.commit());
-          break;
-        }
-      });
-
-      Effect.runFork(responder.pipe(Effect.provide(DurableAskLive)));
-
-      // Use askWithMailbox (creates mailbox automatically)
-      const response = yield* askWithMailbox<TestRequest, TestResponse>({
-        agent: "agent-a",
-        projectKey: "test-proj",
-        to: "agent-b",
-        payload: { action: "ping", userId: 0 },
-        ttlSeconds: 5,
-        projectPath: testDbPath,
-      });
-
-      expect(response.status).toBe("success");
-      expect(response.message).toBe("One-off response");
-
-      return response;
-    }).pipe(Effect.provide(DurableAskLive));
-
-    const result = await Effect.runPromise(program);
-    expect(result.status).toBe("success");
-  });
-
-  it("should handle multiple concurrent asks", async () => {
-    const program = Effect.gen(function* () {
-      const mailboxService = yield* DurableMailbox;
-
-      const agentA = yield* mailboxService.create({
-        agent: "agent-a",
-        projectKey: "test-proj",
-        projectPath: testDbPath,
-      });
-
-      const agentB = yield* mailboxService.create({
-        agent: "agent-b",
-        projectKey: "test-proj",
-        projectPath: testDbPath,
-      });
-
-      // Agent B: Respond to all requests (limit to 3)
-      const responder = Effect.promise(async () => {
-        let count = 0;
-        for await (const envelope of agentB.receive<TestRequest>()) {
-          await Effect.runPromise(
-            respond<TestResponse>(
-              envelope,
-              {
-                status: "success",
-                data: { userId: envelope.payload.userId },
-              },
-              testDbPath,
-            ).pipe(Effect.provide(DurableAskLive)),
-          );
-          await Effect.runPromise(envelope.commit());
-          count++;
-          if (count >= 3) break; // Exit after 3 responses
-        }
-      });
-
-      Effect.runFork(responder.pipe(Effect.provide(DurableAskLive)));
-
-      // Send 3 concurrent requests
-      const requests = [
-        ask<TestRequest, TestResponse>({
-          mailbox: agentA,
-          to: "agent-b",
-          payload: { action: "getData", userId: 1 },
-          ttlSeconds: 5,
-        }),
-        ask<TestRequest, TestResponse>({
-          mailbox: agentA,
-          to: "agent-b",
-          payload: { action: "getData", userId: 2 },
-          ttlSeconds: 5,
-        }),
-        ask<TestRequest, TestResponse>({
-          mailbox: agentA,
-          to: "agent-b",
-          payload: { action: "getData", userId: 3 },
-          ttlSeconds: 5,
-        }),
-      ];
-
-      const responses = yield* Effect.all(requests, { concurrency: 3 });
-
-      expect(responses).toHaveLength(3);
-      // Sort by userId to avoid flaky ordering - concurrent responses may arrive in any order
-      const sortedData = responses
-        .map((r) => r.data)
-        .sort((a: any, b: any) => a.userId - b.userId);
-      expect(sortedData).toEqual([{ userId: 1 }, { userId: 2 }, { userId: 3 }]);
-
-      return responses;
-    }).pipe(Effect.provide(DurableAskLive));
-
-    const results = await Effect.runPromise(program);
-    expect(results).toHaveLength(3);
-  });
-
-  it("should support thread IDs for conversation tracking", async () => {
-    const program = Effect.gen(function* () {
-      const mailboxService = yield* DurableMailbox;
-
-      const agentA = yield* mailboxService.create({
-        agent: "agent-a",
-        projectKey: "test-proj",
-        projectPath: testDbPath,
-      });
-
-      const agentB = yield* mailboxService.create({
-        agent: "agent-b",
-        projectKey: "test-proj",
-        projectPath: testDbPath,
-      });
-
-      const responder = Effect.promise(async () => {
-        for await (const envelope of agentB.receive<TestRequest>()) {
-          expect(envelope.threadId).toBe("conversation-123");
-          await Effect.runPromise(
-            respond<TestResponse>(
-              envelope,
-              { status: "success" },
-              testDbPath,
-            ).pipe(Effect.provide(DurableAskLive)),
-          );
-          await Effect.runPromise(envelope.commit());
-          break;
-        }
-      });
-
-      Effect.runFork(responder.pipe(Effect.provide(DurableAskLive)));
-
-      const response = yield* ask<TestRequest, TestResponse>({
-        mailbox: agentA,
-        to: "agent-b",
-        payload: { action: "test", userId: 0 },
-        threadId: "conversation-123",
-        ttlSeconds: 5,
-      });
-
-      expect(response.status).toBe("success");
-
-      return response;
-    }).pipe(Effect.provide(DurableAskLive));
-
-    await Effect.runPromise(program);
-  });
-});

package/src/streams/effect/ask.ts

@@ -1,202 +0,0 @@
-/**
- * Ask Pattern - Request/Response over Durable Streams
- *
- * Combines DurableMailbox (message passing) + DurableDeferred (distributed promise)
- * for synchronous-style request/response communication between agents.
- *
- * Based on Kyle Matthews' pattern from Agent Mail.
- *
- * @example
- * ```typescript
- * // Agent A asks Agent B for data
- * const result = yield* ask<Request, Response>({
- *   mailbox: myMailbox,
- *   to: "agent-b",
- *   payload: { query: "getUserData", userId: 123 },
- *   ttlSeconds: 30,
- * });
- *
- * // Agent B receives request and responds
- * for await (const envelope of mailbox.receive()) {
- *   const response = processRequest(envelope.payload);
- *   if (envelope.replyTo) {
- *     yield* DurableDeferred.resolve(envelope.replyTo, response);
- *   }
- *   yield* envelope.commit();
- * }
- * ```
- */
-
-import { Effect } from "effect";
-import { DurableCursor } from "./cursor";
-import { DurableMailbox, type Mailbox } from "./mailbox";
-import { DurableDeferred, type DeferredConfig } from "./deferred";
-import type { TimeoutError, NotFoundError } from "./deferred";
-
-// ============================================================================
-// Types
-// ============================================================================
-
-/**
- * Configuration for ask() request
- */
-export interface AskConfig<Req> {
-  /** Mailbox to send message from */
-  readonly mailbox: Mailbox;
-  /** Recipient agent(s) */
-  readonly to: string | string[];
-  /** Request payload */
-  readonly payload: Req;
-  /** Time-to-live in seconds before timeout (default: 60) */
-  readonly ttlSeconds?: number;
-  /** Optional thread ID for conversation tracking */
-  readonly threadId?: string;
-  /** Optional importance level */
-  readonly importance?: "low" | "normal" | "high" | "urgent";
-  /** Optional project path for database isolation */
-  readonly projectPath?: string;
-}
-
-// ============================================================================
-// Ask Implementation
-// ============================================================================
-
-/**
- * Request/response pattern combining mailbox send + deferred await
- *
- * Creates a deferred promise, sends message with replyTo URL, then blocks
- * until the recipient resolves the deferred (or timeout).
- *
- * @template Req - Request payload type
- * @template Res - Response type
- * @param config - Ask configuration
- * @returns Effect that resolves with response or fails with timeout/not-found
- *
- * @example
- * ```typescript
- * const program = Effect.gen(function* () {
- *   const mailbox = yield* DurableMailbox;
- *   const myMailbox = yield* mailbox.create({ agent: "worker-1", projectKey: "proj" });
- *
- *   const response = yield* ask<Request, Response>({
- *     mailbox: myMailbox,
- *     to: "worker-2",
- *     payload: { task: "getData" },
- *     ttlSeconds: 30,
- *   });
- *
- *   console.log("Got response:", response);
- * });
- * ```
- */
-export function ask<Req, Res>(
-  config: AskConfig<Req>,
-): Effect.Effect<Res, TimeoutError | NotFoundError, DurableDeferred> {
-  return Effect.gen(function* () {
-    const deferred = yield* DurableDeferred;
-
-    // Create deferred for response
-    const deferredConfig: DeferredConfig = {
-      ttlSeconds: config.ttlSeconds ?? 60,
-      projectPath: config.projectPath,
-    };
-    const responseHandle = yield* deferred.create<Res>(deferredConfig);
-
-    // Send message with replyTo URL
-    yield* config.mailbox.send(config.to, {
-      payload: config.payload,
-      replyTo: responseHandle.url,
-      threadId: config.threadId,
-      importance: config.importance,
-    });
-
-    // Block until response or timeout
-    const response = yield* responseHandle.value;
-
-    return response;
-  });
-}
-
-// ============================================================================
-// Convenience Variants
-// ============================================================================
-
-/**
- * Ask pattern with automatic mailbox creation
- *
- * Simpler variant when you don't need to reuse the mailbox.
- *
- * @example
- * ```typescript
- * const response = yield* askWithMailbox({
- *   agent: "worker-1",
- *   projectKey: "proj",
- *   to: "worker-2",
- *   payload: { task: "getData" },
- * });
- * ```
- */
-export function askWithMailbox<Req, Res>(config: {
-  readonly agent: string;
-  readonly projectKey: string;
-  readonly to: string | string[];
-  readonly payload: Req;
-  readonly ttlSeconds?: number;
-  readonly threadId?: string;
-  readonly importance?: "low" | "normal" | "high" | "urgent";
-  readonly projectPath?: string;
-}): Effect.Effect<
-  Res,
-  TimeoutError | NotFoundError,
-  DurableDeferred | DurableMailbox | DurableCursor
-> {
-  return Effect.gen(function* () {
-    const mailboxService = yield* DurableMailbox;
-
-    const mailbox = yield* mailboxService.create({
-      agent: config.agent,
-      projectKey: config.projectKey,
-      projectPath: config.projectPath,
-    });
-
-    return yield* ask<Req, Res>({
-      mailbox,
-      to: config.to,
-      payload: config.payload,
-      ttlSeconds: config.ttlSeconds,
-      threadId: config.threadId,
-      importance: config.importance,
-      projectPath: config.projectPath,
-    });
-  });
-}
-
-/**
- * Respond to a message envelope by resolving its replyTo deferred
- *
- * Helper for the receiver side of ask() pattern.
- *
- * @example
- * ```typescript
- * for await (const envelope of mailbox.receive()) {
- *   const response = processRequest(envelope.payload);
- *   yield* respond(envelope, response);
- *   yield* envelope.commit();
- * }
- * ```
- */
-export function respond<T>(
-  envelope: { readonly replyTo?: string },
-  value: T,
-  projectPath?: string,
-): Effect.Effect<void, NotFoundError, DurableDeferred> {
-  return Effect.gen(function* () {
-    if (!envelope.replyTo) {
-      // No replyTo - this wasn't an ask() request, just return
-      return;
-    }
-
-    const deferred = yield* DurableDeferred;
-    yield* deferred.resolve(envelope.replyTo, value, projectPath);
-  });
-}