swarm-mail 0.1.0

package/README.md

@@ -0,0 +1,201 @@
+# swarm-mail
+
+Event sourcing primitives for multi-agent coordination. Local-first, no external servers.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     SWARM MAIL STACK                        │
+├─────────────────────────────────────────────────────────────┤
+│  TIER 3: COORDINATION                                       │
+│  └── ask<Req, Res>() - Request/Response (RPC-style)        │
+│                                                             │
+│  TIER 2: PATTERNS                                           │
+│  ├── DurableMailbox - Actor inbox with typed envelopes     │
+│  └── DurableLock - CAS-based mutual exclusion              │
+│                                                             │
+│  TIER 1: PRIMITIVES                                         │
+│  ├── DurableCursor - Checkpointed stream reader            │
+│  └── DurableDeferred - Distributed promise                 │
+│                                                             │
+│  STORAGE                                                    │
+│  └── PGLite (Embedded Postgres) + Migrations               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Install
+
+```bash
+bun add swarm-mail
+```
+
+## Usage
+
+### Event Store
+
+Append-only event log with automatic projection updates:
+
+```typescript
+import { getSwarmMail } from "swarm-mail";
+
+// Create swarm mail instance (automatically creates PGlite adapter)
+const swarmMail = await getSwarmMail("/my/project");
+
+// Append events
+await swarmMail.appendEvent({
+  type: "agent_registered",
+  agent_name: "WorkerA",
+  task_description: "Implementing auth",
+  timestamp: Date.now(),
+});
+
+// Query projections
+const agents = await swarmMail.getAgents();
+const messages = await swarmMail.getInbox("WorkerA", { limit: 5 });
+```
+
+### Durable Primitives (Effect-TS)
+
+Built on Effect-TS for type-safe, composable coordination:
+
+```typescript
+import { DurableMailbox, DurableLock, ask } from 'swarm-mail'
+import { Effect } from 'effect'
+
+// Actor mailbox
+const mailbox = DurableMailbox.create<MyMessage>('worker-a')
+await Effect.runPromise(
+  mailbox.send({ type: 'task', payload: 'do something' })
+)
+
+// File locking
+const lock = DurableLock.create('src/auth.ts')
+await Effect.runPromise(
+  lock.acquire({ ttl: 60000 }).pipe(
+    Effect.flatMap(() => /* do work */),
+    Effect.ensuring(lock.release())
+  )
+)
+
+// Request/response
+const response = await Effect.runPromise(
+  ask<Request, Response>('other-agent', { type: 'get-types' })
+)
+```
+
+### Database Adapter
+
+Dependency injection for testing and flexibility:
+
+```typescript
+import { DatabaseAdapter, createSwarmMailAdapter } from 'swarm-mail'
+
+// Implement your own adapter
+const customAdapter: DatabaseAdapter = {
+  query: async (sql, params) => /* ... */,
+  exec: async (sql) => /* ... */,
+  transaction: async (fn) => /* ... */,
+  close: async () => /* ... */
+}
+
+// Use custom adapter
+const swarmMail = createSwarmMailAdapter(customAdapter, '/my/project')
+
+// Or use the convenience layer (built-in PGLite)
+import { getSwarmMail, createInMemorySwarmMail } from 'swarm-mail'
+const swarmMail = await getSwarmMail('/my/project') // persistent
+const swarmMail = await createInMemorySwarmMail() // in-memory
+```
+
+## Event Types
+
+```typescript
+type SwarmMailEvent =
+  | { type: "agent_registered"; agent_name: string; task_description?: string }
+  | {
+      type: "message_sent";
+      from: string;
+      to: string[];
+      subject: string;
+      body: string;
+    }
+  | { type: "message_read"; message_id: number; agent_name: string }
+  | {
+      type: "file_reserved";
+      agent_name: string;
+      paths: string[];
+      exclusive: boolean;
+    }
+  | { type: "file_released"; agent_name: string; paths: string[] }
+  | {
+      type: "swarm_checkpointed";
+      epic_id: string;
+      progress: number;
+      state: object;
+    }
+  | { type: "decomposition_generated"; epic_id: string; subtasks: object[] }
+  | {
+      type: "subtask_outcome";
+      bead_id: string;
+      success: boolean;
+      duration_ms: number;
+    };
+```
+
+## Projections
+
+Materialized views derived from events:
+
+| Projection          | Description                        |
+| ------------------- | ---------------------------------- |
+| `agents`            | Active agents per project          |
+| `messages`          | Agent inbox/outbox with recipients |
+| `file_reservations` | Current file locks with TTL        |
+| `swarm_contexts`    | Checkpoint state for recovery      |
+| `eval_records`      | Outcome data for learning          |
+
+## Architecture
+
+- **Append-only log** - Events are immutable, projections are derived
+- **Local-first** - PGLite embedded Postgres, no external servers
+- **Effect-TS** - Type-safe, composable, testable
+- **Exactly-once** - DurableCursor checkpoints position
+
+## API Reference
+
+### SwarmMailAdapter
+
+```typescript
+interface SwarmMailAdapter {
+  // Events
+  appendEvent(event: SwarmMailEvent): Promise<{ id: number; sequence: number }>;
+  getEvents(options?: {
+    limit?: number;
+    after?: number;
+  }): Promise<StoredEvent[]>;
+
+  // Agents
+  getAgents(): Promise<Agent[]>;
+  getAgent(name: string): Promise<Agent | null>;
+
+  // Messages
+  getInbox(agent: string, options?: InboxOptions): Promise<Message[]>;
+  getMessage(id: number): Promise<Message | null>;
+  getThread(threadId: string): Promise<Message[]>;
+
+  // Reservations
+  getReservations(): Promise<Reservation[]>;
+  getReservationsForAgent(agent: string): Promise<Reservation[]>;
+  checkConflicts(paths: string[], excludeAgent?: string): Promise<Conflict[]>;
+
+  // Swarm Context
+  getSwarmContext(epicId: string): Promise<SwarmContext | null>;
+
+  // Debug
+  debugEvents(options?: DebugOptions): Promise<DebugEvent[]>;
+  debugAgent(name: string): Promise<AgentDebugInfo>;
+}
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "swarm-mail",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node && tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "effect": "^3.19.12",
+    "@electric-sql/pglite": "0.3.14",
+    "zod": "4.1.8"
+  },
+  "devDependencies": {
+    "bun-types": "^1.3.4",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,306 @@
+/**
+ * SwarmMail Adapter - Factory for creating SwarmMailAdapter instances
+ *
+ * This file implements the adapter pattern for swarm-mail, enabling
+ * dependency injection of the database instead of singleton access.
+ *
+ * ## Design Pattern
+ * - Accept DatabaseAdapter via factory parameter
+ * - Return SwarmMailAdapter interface
+ * - Delegate to internal implementation functions
+ * - No direct database access (all via adapter)
+ *
+ * ## Usage
+ * ```typescript
+ * import { createPGLiteAdapter } from '@opencode/swarm-mail/adapters/pglite';
+ * import { createSwarmMailAdapter } from '@opencode/swarm-mail';
+ *
+ * const dbAdapter = createPGLiteAdapter({ path: './streams.db' });
+ * const swarmMail = createSwarmMailAdapter(dbAdapter, '/path/to/project');
+ *
+ * // Use the adapter
+ * await swarmMail.appendEvent(event);
+ * const messages = await swarmMail.getInbox('agent-name', { limit: 5 });
+ * ```
+ */
+
+import type { DatabaseAdapter } from "./types/database";
+import type { SwarmMailAdapter } from "./types/adapter";
+import type {
+  AgentRegisteredEvent,
+  MessageSentEvent,
+  FileReservedEvent,
+} from "./streams/events";
+
+// Import all implementation functions (now refactored to accept dbOverride)
+import {
+  appendEvent,
+  appendEvents,
+  readEvents,
+  getLatestSequence,
+  replayEvents,
+  registerAgent,
+  sendMessage,
+  reserveFiles,
+} from "./streams/store";
+
+import {
+  getAgents,
+  getAgent,
+  getInbox,
+  getMessage,
+  getThreadMessages,
+  getActiveReservations,
+  checkConflicts,
+} from "./streams/projections";
+
+import { appendEvent as appendEventUtil } from "./streams/store";
+import { createEvent } from "./streams/events";
+
+/**
+ * Create a SwarmMailAdapter instance
+ *
+ * @param db - DatabaseAdapter instance (PGLite, SQLite, PostgreSQL, etc.)
+ * @param projectKey - Project identifier (typically the project path)
+ * @returns SwarmMailAdapter interface
+ */
+export function createSwarmMailAdapter(
+  db: DatabaseAdapter,
+  projectKey: string,
+): SwarmMailAdapter {
+  return {
+    // ============================================================================
+    // Event Store Operations
+    // ============================================================================
+
+    async appendEvent(event, projectPath?) {
+      return appendEvent(event, projectPath, db);
+    },
+
+    async appendEvents(events, projectPath?) {
+      return appendEvents(events, projectPath, db);
+    },
+
+    async readEvents(options?, projectPath?) {
+      return readEvents(options, projectPath, db);
+    },
+
+    async getLatestSequence(projectKeyParam?, projectPath?) {
+      return getLatestSequence(projectKeyParam, projectPath, db);
+    },
+
+    async replayEvents(options?, projectPath?) {
+      return replayEvents(options, projectPath, db);
+    },
+
+    // ============================================================================
+    // Agent Operations
+    // ============================================================================
+
+    async registerAgent(
+      projectKeyParam,
+      agentName,
+      options?,
+      projectPath?,
+    ): Promise<AgentRegisteredEvent & { id: number; sequence: number }> {
+      return registerAgent(
+        projectKeyParam,
+        agentName,
+        options,
+        projectPath,
+        db,
+      );
+    },
+
+    async getAgents(projectKeyParam, projectPath?) {
+      return getAgents(projectKeyParam, projectPath, db);
+    },
+
+    async getAgent(projectKeyParam, agentName, projectPath?) {
+      return getAgent(projectKeyParam, agentName, projectPath, db);
+    },
+
+    // ============================================================================
+    // Messaging Operations
+    // ============================================================================
+
+    async sendMessage(
+      projectKeyParam,
+      fromAgent,
+      toAgents,
+      subject,
+      body,
+      options?,
+      projectPath?,
+    ): Promise<MessageSentEvent & { id: number; sequence: number }> {
+      return sendMessage(
+        projectKeyParam,
+        fromAgent,
+        toAgents,
+        subject,
+        body,
+        options,
+        projectPath,
+        db,
+      );
+    },
+
+    async getInbox(projectKeyParam, agentName, options?, projectPath?) {
+      return getInbox(projectKeyParam, agentName, options, projectPath, db);
+    },
+
+    async getMessage(projectKeyParam, messageId, projectPath?) {
+      return getMessage(projectKeyParam, messageId, projectPath, db);
+    },
+
+    async getThreadMessages(projectKeyParam, threadId, projectPath?) {
+      return getThreadMessages(projectKeyParam, threadId, projectPath, db);
+    },
+
+    async markMessageAsRead(
+      projectKeyParam,
+      messageId,
+      agentName,
+      projectPath?,
+    ) {
+      // Create message_read event
+      const event = createEvent("message_read", {
+        project_key: projectKeyParam,
+        message_id: messageId,
+        agent_name: agentName,
+      });
+
+      await appendEventUtil(event, projectPath, db);
+    },
+
+    async acknowledgeMessage(
+      projectKeyParam,
+      messageId,
+      agentName,
+      projectPath?,
+    ) {
+      // Create message_acked event
+      const event = createEvent("message_acked", {
+        project_key: projectKeyParam,
+        message_id: messageId,
+        agent_name: agentName,
+      });
+
+      await appendEventUtil(event, projectPath, db);
+    },
+
+    // ============================================================================
+    // Reservation Operations
+    // ============================================================================
+
+    async reserveFiles(
+      projectKeyParam,
+      agentName,
+      paths,
+      options?,
+      projectPath?,
+    ): Promise<FileReservedEvent & { id: number; sequence: number }> {
+      return reserveFiles(
+        projectKeyParam,
+        agentName,
+        paths,
+        options,
+        projectPath,
+        db,
+      );
+    },
+
+    async releaseFiles(projectKeyParam, agentName, options?, projectPath?) {
+      // Create file_released event
+      const event = createEvent("file_released", {
+        project_key: projectKeyParam,
+        agent_name: agentName,
+        paths: options?.paths,
+        reservation_ids: options?.reservationIds,
+      });
+
+      await appendEventUtil(event, projectPath, db);
+    },
+
+    async getActiveReservations(projectKeyParam, projectPath?, agentName?) {
+      return getActiveReservations(projectKeyParam, projectPath, agentName, db);
+    },
+
+    async checkConflicts(projectKeyParam, agentName, paths, projectPath?) {
+      return checkConflicts(projectKeyParam, agentName, paths, projectPath, db);
+    },
+
+    // ============================================================================
+    // Schema and Health Operations
+    // ============================================================================
+
+    async runMigrations(projectPath?) {
+      // Import migrations module and pass db
+      // Note: migrations expects PGlite but DatabaseAdapter is compatible
+      const { runMigrations: runMigrationsImpl } =
+        await import("./streams/migrations");
+      await runMigrationsImpl(db as any);
+    },
+
+    async healthCheck(projectPath?) {
+      // Simple query to check if db is working
+      try {
+        const result = await db.query("SELECT 1 as ok");
+        return result.rows.length > 0;
+      } catch {
+        return false;
+      }
+    },
+
+    async getDatabaseStats(projectPath?) {
+      const [events, agents, messages, reservations] = await Promise.all([
+        db.query<{ count: string }>("SELECT COUNT(*) as count FROM events"),
+        db.query<{ count: string }>("SELECT COUNT(*) as count FROM agents"),
+        db.query<{ count: string }>("SELECT COUNT(*) as count FROM messages"),
+        db.query<{ count: string }>(
+          "SELECT COUNT(*) as count FROM reservations WHERE released_at IS NULL",
+        ),
+      ]);
+
+      return {
+        events: parseInt(events.rows[0]?.count || "0"),
+        agents: parseInt(agents.rows[0]?.count || "0"),
+        messages: parseInt(messages.rows[0]?.count || "0"),
+        reservations: parseInt(reservations.rows[0]?.count || "0"),
+      };
+    },
+
+    async resetDatabase(projectPath?) {
+      await db.exec(`
+				DELETE FROM message_recipients;
+				DELETE FROM messages;
+				DELETE FROM reservations;
+				DELETE FROM agents;
+				DELETE FROM events;
+				DELETE FROM locks;
+				DELETE FROM cursors;
+			`);
+    },
+
+    // ============================================================================
+    // Database Connection Management
+    // ============================================================================
+
+    async getDatabase(projectPath?) {
+      return db;
+    },
+
+    async close(projectPath?) {
+      if (db.close) {
+        await db.close();
+      }
+    },
+
+    async closeAll() {
+      // For single-instance adapter, same as close()
+      if (db.close) {
+        await db.close();
+      }
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+/**
+ * Swarm Mail - Actor-model primitives for multi-agent coordination
+ *
+ * ## Simple API (PGLite convenience layer)
+ * ```typescript
+ * import { getSwarmMail } from '@opencode/swarm-mail';
+ * const swarmMail = await getSwarmMail('/path/to/project');
+ * ```
+ *
+ * ## Advanced API (database-agnostic adapter)
+ * ```typescript
+ * import { createSwarmMailAdapter } from '@opencode/swarm-mail';
+ * const db = createCustomDbAdapter({ path: './custom.db' });
+ * const swarmMail = createSwarmMailAdapter(db, '/path/to/project');
+ * ```
+ */
+
+export const SWARM_MAIL_VERSION = "0.1.0";
+
+// ============================================================================
+// Core (database-agnostic)
+// ============================================================================
+
+export { createSwarmMailAdapter } from "./adapter";
+export type {
+  DatabaseAdapter,
+  SwarmMailAdapter,
+  EventStoreAdapter,
+  AgentAdapter,
+  MessagingAdapter,
+  ReservationAdapter,
+  SchemaAdapter,
+  ReadEventsOptions,
+  InboxOptions,
+  Message,
+  Reservation,
+  Conflict,
+} from "./types";
+
+// ============================================================================
+// PGLite Convenience Layer
+// ============================================================================
+
+export {
+  getSwarmMail,
+  createInMemorySwarmMail,
+  closeSwarmMail,
+  closeAllSwarmMail,
+  getDatabasePath,
+  PGlite,
+} from "./pglite";
+
+// ============================================================================
+// Re-export everything from streams for backward compatibility
+// ============================================================================
+
+export * from "./streams";