swarm-mail 0.1.0

package/src/types/adapter.ts

@@ -0,0 +1,392 @@
+/**
+ * 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";
+
+// ============================================================================
+// Event Store Operations
+// ============================================================================
+
+export interface ReadEventsOptions {
+	projectKey?: string;
+	types?: AgentEvent["type"][];
+	since?: number; // timestamp
+	until?: number; // timestamp
+	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 }>;
+}
+
+// ============================================================================
+// Agent Operations
+// ============================================================================
+
+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>;
+}
+
+// ============================================================================
+// Messaging Operations
+// ============================================================================
+
+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>;
+}
+
+// ============================================================================
+// Reservation Operations
+// ============================================================================
+
+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[]>;
+}
+
+// ============================================================================
+// Schema and Health Operations
+// ============================================================================
+
+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>;
+}
+
+// ============================================================================
+// Combined SwarmMailAdapter Interface
+// ============================================================================
+
+/**
+ * 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>;
+}
+
+// ============================================================================
+// Factory Function Type
+// ============================================================================
+
+/**
+ * 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;

package/src/types/database.ts

@@ -0,0 +1,127 @@
+/**
+ * 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 function supportsTransactions(
+	adapter: DatabaseAdapter,
+): adapter is Required<Pick<DatabaseAdapter, "transaction">> & DatabaseAdapter {
+	return typeof adapter.transaction === "function";
+}

package/src/types/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Swarm Mail Types - Database-agnostic interfaces
+ *
+ * Re-exports all adapter interfaces for easy importing:
+ *
+ * ```typescript
+ * 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 { DatabaseAdapter, DatabaseConfig, QueryResult } from "./database";
+export { supportsTransactions } from "./database";

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ESNext"],
+    "types": ["bun-types"],
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}