swarm-mail 0.1.0 → 0.1.3

package/src/streams/events.ts

@@ -1,329 +0,0 @@
-/**
- * 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

@@ -1,229 +0,0 @@
-/**
- * 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,
-    });
-  });
-});