swarm-mail 0.1.0 → 0.1.2

package/dist/streams/migrations.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Schema Migration System
+ *
+ * Handles database schema evolution for the PGLite event store.
+ *
+ * ## How It Works
+ *
+ * 1. Each migration has a unique version number (incrementing integer)
+ * 2. On startup, `runMigrations()` checks current schema version
+ * 3. Migrations are applied in order until schema is current
+ * 4. Version is stored in `schema_version` table
+ *
+ * ## Adding a New Migration
+ *
+ * ```typescript
+ * // In migrations.ts
+ * export const migrations: Migration[] = [
+ *   // ... existing migrations
+ *   {
+ *     version: 3,
+ *     description: "add_new_column",
+ *     up: `ALTER TABLE events ADD COLUMN new_col TEXT`,
+ *     down: `ALTER TABLE events DROP COLUMN new_col`,
+ *   },
+ * ];
+ * ```
+ *
+ * ## Rollback
+ *
+ * Rollback is supported via `rollbackTo(db, targetVersion)`.
+ * Note: Some migrations may not be fully reversible (data loss).
+ *
+ * ## Best Practices
+ *
+ * - Always test migrations on a copy of production data
+ * - Keep migrations small and focused
+ * - Include both `up` and `down` SQL
+ * - Use transactions for multi-statement migrations
+ * - Document any data transformations
+ *
+ * @module migrations
+ */
+import type { PGlite } from "@electric-sql/pglite";
+/**
+ * A database migration definition.
+ */
+export interface Migration {
+    /** Unique version number (must be sequential) */
+    version: number;
+    /** Human-readable migration description */
+    description: string;
+    /** SQL to apply the migration */
+    up: string;
+    /** SQL to rollback the migration (best effort) */
+    down: string;
+}
+interface SchemaVersion {
+    version: number;
+    applied_at: number;
+    description: string | null;
+}
+export declare const migrations: Migration[];
+/**
+ * Get the current schema version
+ *
+ * Returns 0 if no migrations have been applied
+ */
+export declare function getCurrentVersion(db: PGlite): Promise<number>;
+/**
+ * Get all applied migrations
+ */
+export declare function getAppliedMigrations(db: PGlite): Promise<SchemaVersion[]>;
+/**
+ * Run all pending migrations
+ *
+ * Idempotent - safe to run multiple times.
+ * Only runs migrations that haven't been applied yet.
+ */
+export declare function runMigrations(db: PGlite): Promise<{
+    applied: number[];
+    current: number;
+}>;
+/**
+ * Rollback to a specific version
+ *
+ * WARNING: This will DROP tables and LOSE DATA.
+ * Only use for testing or emergency recovery.
+ */
+export declare function rollbackTo(db: PGlite, targetVersion: number): Promise<{
+    rolledBack: number[];
+    current: number;
+}>;
+/**
+ * Check if a specific migration has been applied
+ */
+export declare function isMigrationApplied(db: PGlite, version: number): Promise<boolean>;
+/**
+ * Get pending migrations (not yet applied)
+ */
+export declare function getPendingMigrations(db: PGlite): Promise<Migration[]>;
+export {};
+//# sourceMappingURL=migrations.d.ts.map

package/dist/streams/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/streams/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAMnD;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAMD,eAAO,MAAM,UAAU,EAAE,SAAS,EAwFjC,CAAC;AAmBF;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQnE;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,aAAa,EAAE,CAAC,CAgB1B;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACvD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC,CAkDD;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,MAAM,EACV,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC;IACT,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC,CA4CD;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC,CASlB;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAK3E"}

package/dist/streams/projections.d.ts

@@ -0,0 +1,173 @@
+import type { DatabaseAdapter } from "../types/database";
+export interface Agent {
+    id: number;
+    name: string;
+    program: string;
+    model: string;
+    task_description: string | null;
+    registered_at: number;
+    last_active_at: number;
+}
+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 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;
+}
+/**
+ * Get all agents for a project
+ *
+ * @param projectKey - Project identifier
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ */
+export declare function getAgents(projectKey: string, projectPath?: string, dbOverride?: DatabaseAdapter): Promise<Agent[]>;
+/**
+ * Get a specific agent by name
+ *
+ * @param projectKey - Project identifier
+ * @param agentName - Agent name to lookup
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ */
+export declare function getAgent(projectKey: string, agentName: string, projectPath?: string, dbOverride?: DatabaseAdapter): Promise<Agent | null>;
+export interface InboxOptions {
+    limit?: number;
+    urgentOnly?: boolean;
+    unreadOnly?: boolean;
+    includeBodies?: boolean;
+    sinceTs?: string;
+}
+/**
+ * Get inbox messages for an agent
+ *
+ * @param projectKey - Project identifier
+ * @param agentName - Agent name to get inbox for
+ * @param options - Inbox query options
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ */
+export declare function getInbox(projectKey: string, agentName: string, options?: InboxOptions, projectPath?: string, dbOverride?: DatabaseAdapter): Promise<Message[]>;
+/**
+ * Get a single message by ID with full body
+ *
+ * @param projectKey - Project identifier
+ * @param messageId - Message ID to lookup
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ */
+export declare function getMessage(projectKey: string, messageId: number, projectPath?: string, dbOverride?: DatabaseAdapter): Promise<Message | null>;
+/**
+ * Get all messages in a thread
+ *
+ * @param projectKey - Project identifier
+ * @param threadId - Thread ID to lookup
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ */
+export declare function getThreadMessages(projectKey: string, threadId: string, projectPath?: string, dbOverride?: DatabaseAdapter): Promise<Message[]>;
+/**
+ * Get active (non-expired, non-released) reservations
+ *
+ * @param projectKey - Project identifier
+ * @param projectPath - Optional project path for database location
+ * @param agentName - Optional agent name to filter by
+ * @param dbOverride - Optional database adapter for dependency injection
+ */
+export declare function getActiveReservations(projectKey: string, projectPath?: string, agentName?: string, dbOverride?: DatabaseAdapter): Promise<Reservation[]>;
+/**
+ * Check for conflicts with existing reservations
+ *
+ * Returns conflicts where:
+ * - Another agent holds an exclusive reservation
+ * - The path matches (exact or glob pattern)
+ * - The reservation is still active
+ *
+ * @param projectKey - Project identifier
+ * @param agentName - Agent attempting reservation
+ * @param paths - Paths to check for conflicts
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ */
+export declare function checkConflicts(projectKey: string, agentName: string, paths: string[], projectPath?: string, dbOverride?: DatabaseAdapter): Promise<Conflict[]>;
+export interface EvalRecord {
+    id: string;
+    project_key: string;
+    task: string;
+    context: string | null;
+    strategy: string;
+    epic_title: string;
+    subtasks: Array<{
+        title: string;
+        files: string[];
+        priority?: number;
+    }>;
+    outcomes?: Array<{
+        bead_id: string;
+        planned_files: string[];
+        actual_files: string[];
+        duration_ms: number;
+        error_count: number;
+        retry_count: number;
+        success: boolean;
+    }>;
+    overall_success: boolean | null;
+    total_duration_ms: number | null;
+    total_errors: number | null;
+    human_accepted: boolean | null;
+    human_modified: boolean | null;
+    human_notes: string | null;
+    file_overlap_count: number | null;
+    scope_accuracy: number | null;
+    time_balance_ratio: number | null;
+    created_at: number;
+    updated_at: number;
+}
+export interface EvalStats {
+    totalRecords: number;
+    successRate: number;
+    avgDurationMs: number;
+    byStrategy: Record<string, number>;
+}
+/**
+ * Get eval records with optional filters
+ *
+ * @param projectKey - Project identifier
+ * @param options - Query options
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ */
+export declare function getEvalRecords(projectKey: string, options?: {
+    limit?: number;
+    strategy?: string;
+}, projectPath?: string, dbOverride?: DatabaseAdapter): Promise<EvalRecord[]>;
+/**
+ * Get eval statistics for a project
+ *
+ * @param projectKey - Project identifier
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ */
+export declare function getEvalStats(projectKey: string, projectPath?: string, dbOverride?: DatabaseAdapter): Promise<EvalStats>;
+//# sourceMappingURL=projections.d.ts.map

package/dist/streams/projections.d.ts.map

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

package/dist/streams/store.d.ts

@@ -0,0 +1,171 @@
+import type { DatabaseAdapter } from "../types/database";
+import { type AgentEvent, type AgentRegisteredEvent, type MessageSentEvent, type FileReservedEvent } from "./events";
+/**
+ * Append an event to the log
+ *
+ * Also updates materialized views (agents, messages, reservations)
+ *
+ * @param event - Event to append
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ */
+export declare function appendEvent(event: AgentEvent, projectPath?: string, dbOverride?: DatabaseAdapter): Promise<AgentEvent & {
+    id: number;
+    sequence: number;
+}>;
+/**
+ * Append multiple events in a transaction
+ *
+ * @param events - Events to append
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ */
+export declare function appendEvents(events: AgentEvent[], projectPath?: string, dbOverride?: DatabaseAdapter): Promise<Array<AgentEvent & {
+    id: number;
+    sequence: number;
+}>>;
+/**
+ * Read events with optional filters
+ *
+ * @param options - Filter options
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ */
+export declare function readEvents(options?: {
+    projectKey?: string;
+    types?: AgentEvent["type"][];
+    since?: number;
+    until?: number;
+    afterSequence?: number;
+    limit?: number;
+    offset?: number;
+}, projectPath?: string, dbOverride?: DatabaseAdapter): Promise<Array<AgentEvent & {
+    id: number;
+    sequence: number;
+}>>;
+/**
+ * Get the latest sequence number
+ *
+ * @param projectKey - Optional project key to filter by
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ */
+export declare function getLatestSequence(projectKey?: string, projectPath?: string, dbOverride?: DatabaseAdapter): Promise<number>;
+/**
+ * Replay events to rebuild materialized views
+ *
+ * Useful for:
+ * - Recovering from corruption
+ * - Migrating to new schema
+ * - Debugging state issues
+ *
+ * @param options - Replay options
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ */
+export declare function replayEvents(options?: {
+    projectKey?: string;
+    fromSequence?: number;
+    clearViews?: boolean;
+}, projectPath?: string, dbOverride?: DatabaseAdapter): Promise<{
+    eventsReplayed: number;
+    duration: number;
+}>;
+/**
+ * Replay events in batches to avoid OOM
+ *
+ * For large event logs (>100k events), use this instead of replayEvents()
+ * to keep memory usage constant.
+ *
+ * Example:
+ * ```typescript
+ * const result = await replayEventsBatched(
+ *   "my-project",
+ *   async (events, progress) => {
+ *     console.log(`Replayed ${progress.processed}/${progress.total} (${progress.percent}%)`);
+ *   },
+ *   { batchSize: 1000, clearViews: true },
+ *   "/path/to/project"
+ * );
+ * console.log(`Replayed ${result.eventsReplayed} events in ${result.duration}ms`);
+ * ```
+ *
+ * @param projectKey Project key to filter events
+ * @param onBatch Callback invoked for each batch with progress
+ * @param options Configuration options
+ * @param options.batchSize Number of events per batch (default 1000)
+ * @param options.fromSequence Start from this sequence number (default 0)
+ * @param options.clearViews Clear materialized views before replay (default false)
+ * @param projectPath Path to project database
+ */
+export declare function replayEventsBatched(projectKey: string, onBatch: (events: Array<AgentEvent & {
+    id: number;
+    sequence: number;
+}>, progress: {
+    processed: number;
+    total: number;
+    percent: number;
+}) => Promise<void>, options?: {
+    batchSize?: number;
+    fromSequence?: number;
+    clearViews?: boolean;
+}, projectPath?: string, dbOverride?: DatabaseAdapter): Promise<{
+    eventsReplayed: number;
+    duration: number;
+}>;
+/**
+ * Register an agent (creates event + updates view)
+ *
+ * @param projectKey - Project identifier
+ * @param agentName - Agent name
+ * @param options - Registration options
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ */
+export declare function registerAgent(projectKey: string, agentName: string, options?: {
+    program?: string;
+    model?: string;
+    taskDescription?: string;
+}, projectPath?: string, dbOverride?: DatabaseAdapter): Promise<AgentRegisteredEvent & {
+    id: number;
+    sequence: number;
+}>;
+/**
+ * Send a message (creates event + updates view)
+ *
+ * @param projectKey - Project identifier
+ * @param fromAgent - Sender agent name
+ * @param toAgents - Recipient agent names
+ * @param subject - Message subject
+ * @param body - Message body
+ * @param options - Message options
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ */
+export declare function sendMessage(projectKey: string, fromAgent: string, toAgents: string[], subject: string, body: string, options?: {
+    threadId?: string;
+    importance?: "low" | "normal" | "high" | "urgent";
+    ackRequired?: boolean;
+}, projectPath?: string, dbOverride?: DatabaseAdapter): Promise<MessageSentEvent & {
+    id: number;
+    sequence: number;
+}>;
+/**
+ * Reserve files (creates event + updates view)
+ *
+ * @param projectKey - Project identifier
+ * @param agentName - Agent reserving the files
+ * @param paths - File paths to reserve
+ * @param options - Reservation options
+ * @param projectPath - Optional project path for database location
+ * @param dbOverride - Optional database adapter for dependency injection
+ */
+export declare function reserveFiles(projectKey: string, agentName: string, paths: string[], options?: {
+    reason?: string;
+    exclusive?: boolean;
+    ttlSeconds?: number;
+}, projectPath?: string, dbOverride?: DatabaseAdapter): Promise<FileReservedEvent & {
+    id: number;
+    sequence: number;
+}>;
+//# sourceMappingURL=store.d.ts.map

package/dist/streams/store.d.ts.map

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

package/dist/streams/swarm-mail.d.ts

@@ -0,0 +1,153 @@
+export interface SwarmMailContext {
+    projectKey: string;
+    agentName: string;
+}
+export interface InitSwarmAgentOptions {
+    projectPath: string;
+    agentName?: string;
+    program?: string;
+    model?: string;
+    taskDescription?: string;
+}
+export interface SendSwarmMessageOptions {
+    projectPath: string;
+    fromAgent: string;
+    toAgents: string[];
+    subject: string;
+    body: string;
+    threadId?: string;
+    importance?: "low" | "normal" | "high" | "urgent";
+    ackRequired?: boolean;
+}
+export interface SendSwarmMessageResult {
+    success: boolean;
+    messageId: number;
+    threadId?: string;
+    recipientCount: number;
+}
+export interface GetSwarmInboxOptions {
+    projectPath: string;
+    agentName: string;
+    limit?: number;
+    urgentOnly?: boolean;
+    unreadOnly?: boolean;
+    includeBodies?: boolean;
+}
+export interface SwarmInboxMessage {
+    id: number;
+    from_agent: string;
+    subject: string;
+    body?: string;
+    thread_id: string | null;
+    importance: string;
+    created_at: number;
+}
+export interface SwarmInboxResult {
+    messages: SwarmInboxMessage[];
+    total: number;
+}
+export interface ReadSwarmMessageOptions {
+    projectPath: string;
+    messageId: number;
+    agentName?: string;
+    markAsRead?: boolean;
+}
+export interface ReserveSwarmFilesOptions {
+    projectPath: string;
+    agentName: string;
+    paths: string[];
+    reason?: string;
+    exclusive?: boolean;
+    ttlSeconds?: number;
+    force?: boolean;
+}
+export interface GrantedSwarmReservation {
+    id: number;
+    path_pattern: string;
+    exclusive: boolean;
+    expiresAt: number;
+}
+export interface SwarmReservationConflict {
+    path: string;
+    holder: string;
+    pattern: string;
+}
+export interface ReserveSwarmFilesResult {
+    granted: GrantedSwarmReservation[];
+    conflicts: SwarmReservationConflict[];
+}
+export interface ReleaseSwarmFilesOptions {
+    projectPath: string;
+    agentName: string;
+    paths?: string[];
+    reservationIds?: number[];
+}
+export interface ReleaseSwarmFilesResult {
+    released: number;
+    releasedAt: number;
+}
+export interface AcknowledgeSwarmOptions {
+    projectPath: string;
+    messageId: number;
+    agentName: string;
+}
+export interface AcknowledgeSwarmResult {
+    acknowledged: boolean;
+    acknowledgedAt: string | null;
+}
+export interface SwarmHealthResult {
+    healthy: boolean;
+    database: "connected" | "disconnected";
+    stats?: {
+        events: number;
+        agents: number;
+        messages: number;
+        reservations: number;
+    };
+}
+/**
+ * Initialize a swarm agent for this session
+ *
+ * Future: Can use DurableMailbox.create() for actor-style message consumption
+ */
+export declare function initSwarmAgent(options: InitSwarmAgentOptions): Promise<SwarmMailContext>;
+/**
+ * Send a message to other swarm agents
+ *
+ * Future: Use DurableMailbox.send() for envelope pattern with replyTo support
+ */
+export declare function sendSwarmMessage(options: SendSwarmMessageOptions): Promise<SendSwarmMessageResult>;
+/**
+ * Get inbox messages for a swarm agent
+ *
+ * Future: Use DurableCursor.consume() for positioned consumption with checkpointing
+ */
+export declare function getSwarmInbox(options: GetSwarmInboxOptions): Promise<SwarmInboxResult>;
+/**
+ * Read a single message with full body
+ */
+export declare function readSwarmMessage(options: ReadSwarmMessageOptions): Promise<SwarmInboxMessage | null>;
+/**
+ * Reserve files for exclusive editing
+ *
+ * Always grants reservations (even with conflicts) - conflicts are warnings, not blockers.
+ * This matches the test expectations and allows agents to proceed with awareness.
+ *
+ * Future: Use DurableLock.acquire() for distributed mutex with automatic expiry
+ */
+export declare function reserveSwarmFiles(options: ReserveSwarmFilesOptions): Promise<ReserveSwarmFilesResult>;
+/**
+ * Release file reservations
+ *
+ * Future: Use DurableLock.release() for automatic cleanup
+ */
+export declare function releaseSwarmFiles(options: ReleaseSwarmFilesOptions): Promise<ReleaseSwarmFilesResult>;
+/**
+ * Acknowledge a swarm message
+ */
+export declare function acknowledgeSwarmMessage(options: AcknowledgeSwarmOptions): Promise<AcknowledgeSwarmResult>;
+/**
+ * Check if the swarm mail store is healthy
+ */
+export declare function checkSwarmHealth(projectPath?: string): Promise<SwarmHealthResult>;
+//# sourceMappingURL=swarm-mail.d.ts.map

package/dist/streams/swarm-mail.d.ts.map

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