swarm-mail 0.1.0

package/src/streams/events.ts

@@ -0,0 +1,329 @@
+/**
+ * Event Types for Swarm Mail Event Sourcing
+ *
+ * All agent coordination operations are represented as immutable events.
+ * Current state is computed by replaying events (projections).
+ *
+ * Event sourcing benefits:
+ * - Full audit trail for debugging
+ * - Replay from any point
+ * - Events ARE the training data for learning
+ * - No lost messages - append-only, durable
+ */
+import { z } from "zod";
+
+// ============================================================================
+// Base Event Schema
+// ============================================================================
+
+/**
+ * Base fields present on all events
+ */
+export const BaseEventSchema = z.object({
+  /** Auto-generated event ID */
+  id: z.number().optional(),
+  /** Event type discriminator */
+  type: z.string(),
+  /** Project key (usually absolute path) */
+  project_key: z.string(),
+  /** Timestamp when event occurred */
+  timestamp: z.number(), // Unix ms
+  /** Sequence number for ordering */
+  sequence: z.number().optional(),
+});
+
+// ============================================================================
+// Agent Events
+// ============================================================================
+
+export const AgentRegisteredEventSchema = BaseEventSchema.extend({
+  type: z.literal("agent_registered"),
+  agent_name: z.string(),
+  program: z.string().default("opencode"),
+  model: z.string().default("unknown"),
+  task_description: z.string().optional(),
+});
+
+export const AgentActiveEventSchema = BaseEventSchema.extend({
+  type: z.literal("agent_active"),
+  agent_name: z.string(),
+});
+
+// ============================================================================
+// Message Events
+// ============================================================================
+
+export const MessageSentEventSchema = BaseEventSchema.extend({
+  type: z.literal("message_sent"),
+  /** Message ID (auto-generated) */
+  message_id: z.number().optional(),
+  from_agent: z.string(),
+  to_agents: z.array(z.string()),
+  subject: z.string(),
+  body: z.string(),
+  thread_id: z.string().optional(),
+  importance: z.enum(["low", "normal", "high", "urgent"]).default("normal"),
+  ack_required: z.boolean().default(false),
+});
+
+export const MessageReadEventSchema = BaseEventSchema.extend({
+  type: z.literal("message_read"),
+  message_id: z.number(),
+  agent_name: z.string(),
+});
+
+export const MessageAckedEventSchema = BaseEventSchema.extend({
+  type: z.literal("message_acked"),
+  message_id: z.number(),
+  agent_name: z.string(),
+});
+
+// ============================================================================
+// File Reservation Events
+// ============================================================================
+
+export const FileReservedEventSchema = BaseEventSchema.extend({
+  type: z.literal("file_reserved"),
+  /** Reservation ID (auto-generated) */
+  reservation_id: z.number().optional(),
+  agent_name: z.string(),
+  paths: z.array(z.string()),
+  reason: z.string().optional(),
+  exclusive: z.boolean().default(true),
+  /** TTL in seconds */
+  ttl_seconds: z.number().default(3600),
+  /** Absolute expiry timestamp */
+  expires_at: z.number(),
+});
+
+export const FileReleasedEventSchema = BaseEventSchema.extend({
+  type: z.literal("file_released"),
+  agent_name: z.string(),
+  /** Specific paths to release, or empty to release all */
+  paths: z.array(z.string()).optional(),
+  /** Specific reservation IDs to release */
+  reservation_ids: z.array(z.number()).optional(),
+});
+
+// ============================================================================
+// Task Events (for swarm integration)
+// ============================================================================
+
+export const TaskStartedEventSchema = BaseEventSchema.extend({
+  type: z.literal("task_started"),
+  agent_name: z.string(),
+  bead_id: z.string(),
+  epic_id: z.string().optional(),
+});
+
+export const TaskProgressEventSchema = BaseEventSchema.extend({
+  type: z.literal("task_progress"),
+  agent_name: z.string(),
+  bead_id: z.string(),
+  progress_percent: z.number().min(0).max(100).optional(),
+  message: z.string().optional(),
+  files_touched: z.array(z.string()).optional(),
+});
+
+export const TaskCompletedEventSchema = BaseEventSchema.extend({
+  type: z.literal("task_completed"),
+  agent_name: z.string(),
+  bead_id: z.string(),
+  summary: z.string(),
+  files_touched: z.array(z.string()).optional(),
+  success: z.boolean().default(true),
+});
+
+export const TaskBlockedEventSchema = BaseEventSchema.extend({
+  type: z.literal("task_blocked"),
+  agent_name: z.string(),
+  bead_id: z.string(),
+  reason: z.string(),
+});
+
+// ============================================================================
+// Eval Capture Events (for learning system)
+// ============================================================================
+
+export const DecompositionGeneratedEventSchema = BaseEventSchema.extend({
+  type: z.literal("decomposition_generated"),
+  epic_id: z.string(),
+  task: z.string(),
+  context: z.string().optional(),
+  strategy: z.enum(["file-based", "feature-based", "risk-based"]),
+  epic_title: z.string(),
+  subtasks: z.array(
+    z.object({
+      title: z.string(),
+      files: z.array(z.string()),
+      priority: z.number().min(0).max(3).optional(),
+    }),
+  ),
+  recovery_context: z
+    .object({
+      shared_context: z.string().optional(),
+      skills_to_load: z.array(z.string()).optional(),
+      coordinator_notes: z.string().optional(),
+    })
+    .optional(),
+});
+
+export const SubtaskOutcomeEventSchema = BaseEventSchema.extend({
+  type: z.literal("subtask_outcome"),
+  epic_id: z.string(),
+  bead_id: z.string(),
+  planned_files: z.array(z.string()),
+  actual_files: z.array(z.string()),
+  duration_ms: z.number().min(0),
+  error_count: z.number().min(0).default(0),
+  retry_count: z.number().min(0).default(0),
+  success: z.boolean(),
+});
+
+export const HumanFeedbackEventSchema = BaseEventSchema.extend({
+  type: z.literal("human_feedback"),
+  epic_id: z.string(),
+  accepted: z.boolean(),
+  modified: z.boolean().default(false),
+  notes: z.string().optional(),
+});
+
+// ============================================================================
+// Swarm Checkpoint Events (for recovery and coordination)
+// ============================================================================
+
+export const SwarmCheckpointedEventSchema = BaseEventSchema.extend({
+  type: z.literal("swarm_checkpointed"),
+  epic_id: z.string(),
+  bead_id: z.string(),
+  strategy: z.enum(["file-based", "feature-based", "risk-based"]),
+  files: z.array(z.string()),
+  dependencies: z.array(z.string()),
+  directives: z.object({
+    shared_context: z.string().optional(),
+    skills_to_load: z.array(z.string()).optional(),
+    coordinator_notes: z.string().optional(),
+  }),
+  recovery: z.object({
+    last_checkpoint: z.number(),
+    files_modified: z.array(z.string()),
+    progress_percent: z.number().min(0).max(100),
+    last_message: z.string().optional(),
+    error_context: z.string().optional(),
+  }),
+});
+
+export const SwarmRecoveredEventSchema = BaseEventSchema.extend({
+  type: z.literal("swarm_recovered"),
+  epic_id: z.string(),
+  bead_id: z.string(),
+  recovered_from_checkpoint: z.number(), // timestamp
+});
+
+// ============================================================================
+// Union Type
+// ============================================================================
+
+export const AgentEventSchema = z.discriminatedUnion("type", [
+  AgentRegisteredEventSchema,
+  AgentActiveEventSchema,
+  MessageSentEventSchema,
+  MessageReadEventSchema,
+  MessageAckedEventSchema,
+  FileReservedEventSchema,
+  FileReleasedEventSchema,
+  TaskStartedEventSchema,
+  TaskProgressEventSchema,
+  TaskCompletedEventSchema,
+  TaskBlockedEventSchema,
+  DecompositionGeneratedEventSchema,
+  SubtaskOutcomeEventSchema,
+  HumanFeedbackEventSchema,
+  SwarmCheckpointedEventSchema,
+  SwarmRecoveredEventSchema,
+]);
+
+export type AgentEvent = z.infer<typeof AgentEventSchema>;
+
+// Individual event types for convenience
+export type AgentRegisteredEvent = z.infer<typeof AgentRegisteredEventSchema>;
+export type AgentActiveEvent = z.infer<typeof AgentActiveEventSchema>;
+export type MessageSentEvent = z.infer<typeof MessageSentEventSchema>;
+export type MessageReadEvent = z.infer<typeof MessageReadEventSchema>;
+export type MessageAckedEvent = z.infer<typeof MessageAckedEventSchema>;
+export type FileReservedEvent = z.infer<typeof FileReservedEventSchema>;
+export type FileReleasedEvent = z.infer<typeof FileReleasedEventSchema>;
+export type TaskStartedEvent = z.infer<typeof TaskStartedEventSchema>;
+export type TaskProgressEvent = z.infer<typeof TaskProgressEventSchema>;
+export type TaskCompletedEvent = z.infer<typeof TaskCompletedEventSchema>;
+export type TaskBlockedEvent = z.infer<typeof TaskBlockedEventSchema>;
+export type DecompositionGeneratedEvent = z.infer<
+  typeof DecompositionGeneratedEventSchema
+>;
+export type SubtaskOutcomeEvent = z.infer<typeof SubtaskOutcomeEventSchema>;
+export type HumanFeedbackEvent = z.infer<typeof HumanFeedbackEventSchema>;
+export type SwarmCheckpointedEvent = z.infer<
+  typeof SwarmCheckpointedEventSchema
+>;
+export type SwarmRecoveredEvent = z.infer<typeof SwarmRecoveredEventSchema>;
+
+// ============================================================================
+// Session State Types
+// ============================================================================
+
+/**
+ * Shared session state for Agent Mail and Swarm Mail
+ *
+ * Common fields for tracking agent coordination session across both
+ * the MCP-based implementation (agent-mail) and the embedded event-sourced
+ * implementation (swarm-mail).
+ */
+export interface MailSessionState {
+  /** Project key (usually absolute path) */
+  projectKey: string;
+  /** Agent name for this session */
+  agentName: string;
+  /** Active reservation IDs */
+  reservations: number[];
+  /** Session start timestamp (ISO-8601) */
+  startedAt: string;
+}
+
+// ============================================================================
+// Event Helpers
+// ============================================================================
+
+/**
+ * Create an event with timestamp and validate
+ */
+export function createEvent<T extends AgentEvent["type"]>(
+  type: T,
+  data: Omit<
+    Extract<AgentEvent, { type: T }>,
+    "type" | "timestamp" | "id" | "sequence"
+  >,
+): Extract<AgentEvent, { type: T }> {
+  const event = {
+    type,
+    timestamp: Date.now(),
+    ...data,
+  } as Extract<AgentEvent, { type: T }>;
+
+  // Validate
+  const result = AgentEventSchema.safeParse(event);
+  if (!result.success) {
+    throw new Error(`Invalid event: ${result.error.message}`);
+  }
+
+  return result.data as Extract<AgentEvent, { type: T }>;
+}
+
+/**
+ * Type guard for specific event types
+ */
+export function isEventType<T extends AgentEvent["type"]>(
+  event: AgentEvent,
+  type: T,
+): event is Extract<AgentEvent, { type: T }> {
+  return event.type === type;
+}

package/src/streams/index.test.ts

@@ -0,0 +1,229 @@
+/**
+ * Tests for database singleton management
+ *
+ * Each test uses isolated database paths to prevent cross-test pollution.
+ */
+import { randomUUID } from "node:crypto";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import {
+  closeAllDatabases,
+  closeDatabase,
+  getDatabase,
+  getDatabasePath,
+  getDatabaseStats,
+  isDatabaseHealthy,
+  resetDatabase,
+} from "./index";
+
+// ============================================================================
+// Test Isolation Helpers
+// ============================================================================
+
+/** Generate unique test database path */
+function testDbPath(prefix = "test"): string {
+  return `/tmp/streams-${prefix}-${randomUUID()}`;
+}
+
+/** Track paths created during test for cleanup */
+let testPaths: string[] = [];
+
+function trackPath(path: string): string {
+  testPaths.push(path);
+  return path;
+}
+
+// ============================================================================
+// Global Cleanup
+// ============================================================================
+
+beforeEach(async () => {
+  testPaths = [];
+  // Nuclear cleanup - close everything before each test
+  await closeAllDatabases();
+});
+
+afterEach(async () => {
+  // Clean up all test databases
+  for (const path of testPaths) {
+    try {
+      // Wipe all data before closing
+      const db = await getDatabase(path);
+      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;
+        DELETE FROM deferred;
+      `);
+    } catch {
+      // Ignore errors during cleanup
+    }
+    await closeDatabase(path);
+  }
+  testPaths = [];
+  // Nuclear cleanup after each test too
+  await closeAllDatabases();
+});
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe("getDatabasePath", () => {
+  it("returns project-local path when .opencode exists", () => {
+    const path = getDatabasePath(process.cwd());
+    expect(path).toMatch(/\.opencode\/streams$/);
+  });
+
+  it("falls back to global path when projectPath is undefined", () => {
+    const path = getDatabasePath();
+    expect(path).toMatch(/\.opencode\/streams$/);
+    expect(path).toContain(require("node:os").homedir());
+  });
+});
+
+describe("getDatabase singleton", () => {
+  it("returns same instance for same path", async () => {
+    const path = trackPath(testDbPath("same-instance"));
+    const db1 = await getDatabase(path);
+    const db2 = await getDatabase(path);
+    expect(db1).toBe(db2);
+  });
+
+  it("caches instances by path", async () => {
+    // This test verifies the caching behavior - same path returns same instance
+    // Different paths may or may not return different instances depending on
+    // whether file-based storage works or falls back to in-memory
+    const path1 = trackPath(testDbPath("cache-1"));
+    const path2 = trackPath(testDbPath("cache-2"));
+
+    const db1a = await getDatabase(path1);
+    const db1b = await getDatabase(path1);
+    const db2 = await getDatabase(path2);
+
+    // Same path MUST return same instance (this is the cache contract)
+    expect(db1a).toBe(db1b);
+
+    // Both should be functional
+    const r1 = await db1a.query("SELECT 1 as ok");
+    const r2 = await db2.query("SELECT 1 as ok");
+    expect(r1.rows[0]).toEqual({ ok: 1 });
+    expect(r2.rows[0]).toEqual({ ok: 1 });
+  });
+
+  it("initializes schema on first access", async () => {
+    const path = trackPath(testDbPath("schema-init"));
+    const db = await getDatabase(path);
+    const result = await db.query("SELECT COUNT(*) FROM events");
+    expect(result.rows).toBeDefined();
+  });
+
+  it("does not reinitialize schema on subsequent access", async () => {
+    const path = trackPath(testDbPath("no-reinit"));
+    const db1 = await getDatabase(path);
+
+    await db1.exec(
+      "INSERT INTO events (type, project_key, timestamp, data) VALUES ('test', 'test', 123, '{}')",
+    );
+
+    const db2 = await getDatabase(path);
+    const result = await db2.query<{ count: string }>(
+      "SELECT COUNT(*) as count FROM events",
+    );
+    expect(parseInt(result.rows[0].count)).toBe(1);
+  });
+
+  it("concurrent calls return the same instance (no race condition)", async () => {
+    const path = trackPath(testDbPath("race"));
+    const promises = Array.from({ length: 10 }, () => getDatabase(path));
+    const results = await Promise.all(promises);
+
+    const firstInstance = results[0];
+    const allSame = results.every((db) => db === firstInstance);
+    expect(allSame).toBe(true);
+  });
+});
+
+describe("closeDatabase", () => {
+  it("removes instance from cache", async () => {
+    const path = trackPath(testDbPath("close"));
+    const db1 = await getDatabase(path);
+    await closeDatabase(path);
+    const db2 = await getDatabase(path);
+    expect(db1).not.toBe(db2);
+  });
+
+  it("handles closing non-existent database gracefully", async () => {
+    const path = testDbPath("non-existent");
+    // Should not throw
+    await closeDatabase(path);
+    expect(true).toBe(true);
+  });
+});
+
+describe("closeAllDatabases", () => {
+  it("closes all cached instances", async () => {
+    const path1 = trackPath(testDbPath("all-1"));
+    const path2 = trackPath(testDbPath("all-2"));
+    const db1 = await getDatabase(path1);
+    const db2 = await getDatabase(path2);
+
+    await closeAllDatabases();
+
+    const db3 = await getDatabase(path1);
+    const db4 = await getDatabase(path2);
+
+    expect(db3).not.toBe(db1);
+    expect(db4).not.toBe(db2);
+  });
+});
+
+describe("isDatabaseHealthy", () => {
+  it("returns true for healthy database", async () => {
+    const path = trackPath(testDbPath("healthy"));
+    await getDatabase(path);
+    const healthy = await isDatabaseHealthy(path);
+    expect(healthy).toBe(true);
+  });
+});
+
+describe("resetDatabase", () => {
+  it("clears all data but keeps schema", async () => {
+    const path = trackPath(testDbPath("reset"));
+    const db = await getDatabase(path);
+    await db.exec(
+      "INSERT INTO events (type, project_key, timestamp, data) VALUES ('test', 'test', 123, '{}')",
+    );
+
+    await resetDatabase(path);
+
+    const result = await db.query<{ count: string }>(
+      "SELECT COUNT(*) as count FROM events",
+    );
+    expect(parseInt(result.rows[0].count)).toBe(0);
+
+    // Schema should still exist
+    await expect(
+      db.query("SELECT 1 FROM events LIMIT 0"),
+    ).resolves.toBeDefined();
+  });
+});
+
+describe("getDatabaseStats", () => {
+  it("returns counts for all tables", async () => {
+    const path = trackPath(testDbPath("stats"));
+    await resetDatabase(path);
+    const stats = await getDatabaseStats(path);
+
+    expect(stats).toEqual({
+      events: 0,
+      agents: 0,
+      messages: 0,
+      reservations: 0,
+    });
+  });
+});