swarm-mail 0.1.0 → 0.1.2

package/dist/types/adapter.d.ts

@@ -0,0 +1,267 @@
+/**
+ * SwarmMailAdapter - High-level interface for swarm-mail operations
+ *
+ * This interface abstracts all swarm-mail operations (events, messaging,
+ * reservations, locks) to enable different storage backends.
+ *
+ * ## Design Goals
+ * - Database-agnostic (works with PGLite, SQLite, PostgreSQL, etc.)
+ * - Matches existing swarm-mail API surface
+ * - No implementation details leak through interface
+ *
+ * ## Layering
+ * - DatabaseAdapter: Low-level SQL execution
+ * - SwarmMailAdapter: High-level swarm-mail operations (uses DatabaseAdapter internally)
+ * - Plugin tools: Type-safe Zod-validated wrappers (use SwarmMailAdapter)
+ */
+import type { AgentEvent, AgentRegisteredEvent, FileReservedEvent, MessageSentEvent } from "../streams/events";
+import type { DatabaseAdapter } from "./database";
+export interface ReadEventsOptions {
+    projectKey?: string;
+    types?: AgentEvent["type"][];
+    since?: number;
+    until?: number;
+    afterSequence?: number;
+    limit?: number;
+    offset?: number;
+}
+export interface EventStoreAdapter {
+    /**
+     * Append a single event to the log
+     *
+     * Updates materialized views automatically.
+     */
+    appendEvent(event: AgentEvent, projectPath?: string): Promise<AgentEvent & {
+        id: number;
+        sequence: number;
+    }>;
+    /**
+     * Append multiple events in a transaction
+     *
+     * Atomic - all events succeed or all fail.
+     */
+    appendEvents(events: AgentEvent[], projectPath?: string): Promise<Array<AgentEvent & {
+        id: number;
+        sequence: number;
+    }>>;
+    /**
+     * Read events with filters
+     */
+    readEvents(options?: ReadEventsOptions, projectPath?: string): Promise<Array<AgentEvent & {
+        id: number;
+        sequence: number;
+    }>>;
+    /**
+     * Get the latest sequence number for a project
+     */
+    getLatestSequence(projectKey?: string, projectPath?: string): Promise<number>;
+    /**
+     * Replay events to rebuild materialized views
+     */
+    replayEvents(options?: {
+        projectKey?: string;
+        fromSequence?: number;
+        clearViews?: boolean;
+    }, projectPath?: string): Promise<{
+        eventsReplayed: number;
+        duration: number;
+    }>;
+}
+export interface AgentAdapter {
+    /**
+     * Register an agent for a project
+     */
+    registerAgent(projectKey: string, agentName: string, options?: {
+        program?: string;
+        model?: string;
+        taskDescription?: string;
+    }, projectPath?: string): Promise<AgentRegisteredEvent & {
+        id: number;
+        sequence: number;
+    }>;
+    /**
+     * Get all agents for a project
+     */
+    getAgents(projectKey: string, projectPath?: string): Promise<Array<{
+        id: number;
+        name: string;
+        program: string;
+        model: string;
+        task_description: string | null;
+        registered_at: number;
+        last_active_at: number;
+    }>>;
+    /**
+     * Get a specific agent by name
+     */
+    getAgent(projectKey: string, agentName: string, projectPath?: string): Promise<{
+        id: number;
+        name: string;
+        program: string;
+        model: string;
+        task_description: string | null;
+        registered_at: number;
+        last_active_at: number;
+    } | null>;
+}
+export interface InboxOptions {
+    limit?: number;
+    urgentOnly?: boolean;
+    unreadOnly?: boolean;
+    includeBodies?: boolean;
+    sinceTs?: string;
+}
+export interface Message {
+    id: number;
+    from_agent: string;
+    subject: string;
+    body?: string;
+    thread_id: string | null;
+    importance: string;
+    ack_required: boolean;
+    created_at: number;
+    read_at?: number | null;
+    acked_at?: number | null;
+}
+export interface MessagingAdapter {
+    /**
+     * Send a message to other agents
+     */
+    sendMessage(projectKey: string, fromAgent: string, toAgents: string[], subject: string, body: string, options?: {
+        threadId?: string;
+        importance?: "low" | "normal" | "high" | "urgent";
+        ackRequired?: boolean;
+    }, projectPath?: string): Promise<MessageSentEvent & {
+        id: number;
+        sequence: number;
+    }>;
+    /**
+     * Get inbox messages for an agent
+     */
+    getInbox(projectKey: string, agentName: string, options?: InboxOptions, projectPath?: string): Promise<Message[]>;
+    /**
+     * Get a single message by ID
+     */
+    getMessage(projectKey: string, messageId: number, projectPath?: string): Promise<Message | null>;
+    /**
+     * Get all messages in a thread
+     */
+    getThreadMessages(projectKey: string, threadId: string, projectPath?: string): Promise<Message[]>;
+    /**
+     * Mark a message as read
+     */
+    markMessageAsRead(projectKey: string, messageId: number, agentName: string, projectPath?: string): Promise<void>;
+    /**
+     * Acknowledge a message
+     */
+    acknowledgeMessage(projectKey: string, messageId: number, agentName: string, projectPath?: string): Promise<void>;
+}
+export interface Reservation {
+    id: number;
+    agent_name: string;
+    path_pattern: string;
+    exclusive: boolean;
+    reason: string | null;
+    created_at: number;
+    expires_at: number;
+}
+export interface Conflict {
+    path: string;
+    holder: string;
+    pattern: string;
+    exclusive: boolean;
+}
+export interface ReservationAdapter {
+    /**
+     * Reserve files for exclusive editing
+     */
+    reserveFiles(projectKey: string, agentName: string, paths: string[], options?: {
+        reason?: string;
+        exclusive?: boolean;
+        ttlSeconds?: number;
+    }, projectPath?: string): Promise<FileReservedEvent & {
+        id: number;
+        sequence: number;
+    }>;
+    /**
+     * Release file reservations
+     */
+    releaseFiles(projectKey: string, agentName: string, options?: {
+        paths?: string[];
+        reservationIds?: number[];
+    }, projectPath?: string): Promise<void>;
+    /**
+     * Get active reservations for a project
+     */
+    getActiveReservations(projectKey: string, projectPath?: string, agentName?: string): Promise<Reservation[]>;
+    /**
+     * Check for conflicts with existing reservations
+     */
+    checkConflicts(projectKey: string, agentName: string, paths: string[], projectPath?: string): Promise<Conflict[]>;
+}
+export interface SchemaAdapter {
+    /**
+     * Run database migrations
+     *
+     * Initializes tables, indexes, and constraints.
+     */
+    runMigrations(projectPath?: string): Promise<void>;
+    /**
+     * Check if database is healthy
+     */
+    healthCheck(projectPath?: string): Promise<boolean>;
+    /**
+     * Get database statistics
+     */
+    getDatabaseStats(projectPath?: string): Promise<{
+        events: number;
+        agents: number;
+        messages: number;
+        reservations: number;
+    }>;
+    /**
+     * Reset database for testing
+     *
+     * Clears all data but keeps schema.
+     */
+    resetDatabase(projectPath?: string): Promise<void>;
+}
+/**
+ * SwarmMailAdapter - Complete interface for swarm-mail operations
+ *
+ * Combines all sub-adapters into a single interface.
+ * Implementations provide a DatabaseAdapter and implement all operations.
+ */
+export interface SwarmMailAdapter extends EventStoreAdapter, AgentAdapter, MessagingAdapter, ReservationAdapter, SchemaAdapter {
+    /**
+     * Get the underlying database adapter
+     */
+    getDatabase(projectPath?: string): Promise<DatabaseAdapter>;
+    /**
+     * Close the database connection
+     */
+    close(projectPath?: string): Promise<void>;
+    /**
+     * Close all database connections
+     */
+    closeAll(): Promise<void>;
+}
+/**
+ * SwarmMailAdapterFactory - Function that creates a SwarmMailAdapter instance
+ *
+ * Adapters export a factory function with this signature.
+ *
+ * @example
+ * ```typescript
+ * import { createPGLiteAdapter } from '@opencode/swarm-mail/adapters/pglite';
+ * import { createSQLiteAdapter } from '@opencode/swarm-mail/adapters/sqlite';
+ *
+ * const adapter = createPGLiteAdapter({ path: './streams.db' });
+ * const adapter2 = createSQLiteAdapter({ path: './streams.db' });
+ * ```
+ */
+export type SwarmMailAdapterFactory = (config: {
+    path?: string;
+    timeout?: number;
+}) => SwarmMailAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/types/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/types/adapter.ts"],"names":[],"mappings":"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"}

package/dist/types/database.d.ts

@@ -0,0 +1,117 @@
+/**
+ * DatabaseAdapter - Database-agnostic interface for swarm-mail
+ *
+ * Abstracts PGLite-specific operations to support multiple database backends.
+ * Based on coursebuilder's adapter-drizzle pattern.
+ *
+ * ## Design Goals
+ * - Zero PGLite types in this interface
+ * - Support for PGLite, better-sqlite3, libsql, PostgreSQL
+ * - Transaction support optional (some adapters may not support it)
+ *
+ * ## Implementation Strategy
+ * - Accept database instance via dependency injection
+ * - Adapters implement this interface for their specific database
+ * - Query results use plain objects (no driver-specific types)
+ */
+/**
+ * Query result with rows array
+ *
+ * All database adapters return results in this shape.
+ */
+export interface QueryResult<T = unknown> {
+    /** Array of result rows */
+    rows: T[];
+}
+/**
+ * DatabaseAdapter interface
+ *
+ * Minimal interface for executing SQL queries and managing transactions.
+ * Adapters implement this for PGLite, SQLite, PostgreSQL, etc.
+ */
+export interface DatabaseAdapter {
+    /**
+     * Execute a query and return results
+     *
+     * @param sql - SQL query string (parameterized)
+     * @param params - Query parameters ($1, $2, etc.)
+     * @returns Query result with rows array
+     *
+     * @example
+     * ```typescript
+     * const result = await db.query<{ id: number }>(
+     *   "SELECT id FROM agents WHERE name = $1",
+     *   ["BlueLake"]
+     * );
+     * const id = result.rows[0]?.id;
+     * ```
+     */
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<QueryResult<T>>;
+    /**
+     * Execute a SQL statement without returning results
+     *
+     * Used for DDL (CREATE TABLE, etc.), DML (INSERT/UPDATE/DELETE), and transactions.
+     *
+     * @param sql - SQL statement(s) to execute
+     *
+     * @example
+     * ```typescript
+     * await db.exec("BEGIN");
+     * await db.exec("COMMIT");
+     * await db.exec("CREATE TABLE users (id SERIAL PRIMARY KEY)");
+     * ```
+     */
+    exec(sql: string): Promise<void>;
+    /**
+     * Execute a function within a transaction (optional)
+     *
+     * If the adapter doesn't support transactions, it can omit this method
+     * or throw an error. The swarm-mail layer will handle transaction
+     * fallback (using manual BEGIN/COMMIT/ROLLBACK).
+     *
+     * @param fn - Function to execute within transaction context
+     * @returns Result of the function
+     *
+     * @example
+     * ```typescript
+     * const result = await db.transaction?.(async (tx) => {
+     *   await tx.query("INSERT INTO events ...", [...]);
+     *   await tx.query("UPDATE agents ...", [...]);
+     *   return { success: true };
+     * });
+     * ```
+     */
+    transaction?<T>(fn: (tx: DatabaseAdapter) => Promise<T>): Promise<T>;
+    /**
+     * Close the database connection (optional)
+     *
+     * Some adapters (like PGLite) need explicit cleanup.
+     * If not provided, swarm-mail assumes connection is managed externally.
+     */
+    close?(): Promise<void>;
+}
+/**
+ * Database configuration options
+ *
+ * Passed to adapter factory functions to create DatabaseAdapter instances.
+ */
+export interface DatabaseConfig {
+    /** Path to database file or connection string */
+    path: string;
+    /** Optional timeout in milliseconds for queries */
+    timeout?: number;
+    /** Optional flags for database initialization */
+    flags?: {
+        /** Create database if it doesn't exist */
+        create?: boolean;
+        /** Enable foreign key constraints */
+        foreignKeys?: boolean;
+        /** Enable WAL mode (SQLite) */
+        wal?: boolean;
+    };
+}
+/**
+ * Type guard to check if adapter supports transactions
+ */
+export declare function supportsTransactions(adapter: DatabaseAdapter): adapter is Required<Pick<DatabaseAdapter, "transaction">> & DatabaseAdapter;
+//# sourceMappingURL=database.d.ts.map

package/dist/types/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/types/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACvC,2BAA2B;IAC3B,IAAI,EAAE,CAAC,EAAE,CAAC;CACV;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC/B;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7E;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjC;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAAW,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,eAAe,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAErE;;;;;OAKG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,KAAK,CAAC,EAAE;QACP,0CAA0C;QAC1C,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,qCAAqC;QACrC,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,+BAA+B;QAC/B,GAAG,CAAC,EAAE,OAAO,CAAC;KACd,CAAC;CACF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,eAAe,GACtB,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC,GAAG,eAAe,CAE7E"}

package/{src/types/index.ts → dist/types/index.d.ts}

@@ -7,20 +7,7 @@
  * import type { DatabaseAdapter, SwarmMailAdapter } from '@opencode/swarm-mail/types';
  * ```
  */
-
-export type {
-	AgentAdapter,
-	Conflict,
-	EventStoreAdapter,
-	InboxOptions,
-	Message,
-	MessagingAdapter,
-	ReadEventsOptions,
-	Reservation,
-	ReservationAdapter,
-	SchemaAdapter,
-	SwarmMailAdapter,
-	SwarmMailAdapterFactory,
-} from "./adapter";
+export type { AgentAdapter, Conflict, EventStoreAdapter, InboxOptions, Message, MessagingAdapter, ReadEventsOptions, Reservation, ReservationAdapter, SchemaAdapter, SwarmMailAdapter, SwarmMailAdapterFactory, } from "./adapter";
 export type { DatabaseAdapter, DatabaseConfig, QueryResult } from "./database";
 export { supportsTransactions } from "./database";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY,EACX,YAAY,EACZ,QAAQ,EACR,iBAAiB,EACjB,YAAY,EACZ,OAAO,EACP,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EAChB,uBAAuB,GACvB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC"}

package/package.json

@@ -1,23 +1,39 @@
 {
   "name": "swarm-mail",
-  "version": "0.1.0",
+  "version": "0.1.2",
+  "description": "Event sourcing primitives for multi-agent coordination. Local-first, no external servers.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "exports": {
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     }
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joelhooks/opencode-swarm-plugin"
+  },
+  "author": "Joel Hooks",
+  "license": "MIT",
   "scripts": {
     "build": "bun build ./src/index.ts --outdir ./dist --target node && tsc",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "test": "vitest run --exclude '**/*.integration.test.ts'",
+    "test:integration": "vitest run --include '**/*.integration.test.ts' --testTimeout 60000",
+    "test:all": "vitest run --testTimeout 60000",
+    "typecheck": "tsc --noEmit",
+    "publish:pkg": "npm publish --access public --provenance"
   },
   "dependencies": {
-    "effect": "^3.19.12",
     "@electric-sql/pglite": "0.3.14",
+    "effect": "^3.19.12",
+    "minimatch": "^10.1.1",
+    "nanoid": "^5.1.6",
     "zod": "4.1.8"
   },
   "devDependencies": {