swarm-mail 0.1.0 → 0.1.3

package/dist/streams/events.d.ts

@@ -0,0 +1,487 @@
+/**
+ * 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 fields present on all events
+ */
+export declare const BaseEventSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodString;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const AgentRegisteredEventSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"agent_registered">;
+    agent_name: z.ZodString;
+    program: z.ZodDefault<z.ZodString>;
+    model: z.ZodDefault<z.ZodString>;
+    task_description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const AgentActiveEventSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"agent_active">;
+    agent_name: z.ZodString;
+}, z.core.$strip>;
+export declare const MessageSentEventSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"message_sent">;
+    message_id: z.ZodOptional<z.ZodNumber>;
+    from_agent: z.ZodString;
+    to_agents: z.ZodArray<z.ZodString>;
+    subject: z.ZodString;
+    body: z.ZodString;
+    thread_id: z.ZodOptional<z.ZodString>;
+    importance: z.ZodDefault<z.ZodEnum<{
+        low: "low";
+        normal: "normal";
+        high: "high";
+        urgent: "urgent";
+    }>>;
+    ack_required: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const MessageReadEventSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"message_read">;
+    message_id: z.ZodNumber;
+    agent_name: z.ZodString;
+}, z.core.$strip>;
+export declare const MessageAckedEventSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"message_acked">;
+    message_id: z.ZodNumber;
+    agent_name: z.ZodString;
+}, z.core.$strip>;
+export declare const FileReservedEventSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"file_reserved">;
+    reservation_id: z.ZodOptional<z.ZodNumber>;
+    agent_name: z.ZodString;
+    paths: z.ZodArray<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+    exclusive: z.ZodDefault<z.ZodBoolean>;
+    ttl_seconds: z.ZodDefault<z.ZodNumber>;
+    expires_at: z.ZodNumber;
+}, z.core.$strip>;
+export declare const FileReleasedEventSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"file_released">;
+    agent_name: z.ZodString;
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    reservation_ids: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+}, z.core.$strip>;
+export declare const TaskStartedEventSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"task_started">;
+    agent_name: z.ZodString;
+    bead_id: z.ZodString;
+    epic_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const TaskProgressEventSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"task_progress">;
+    agent_name: z.ZodString;
+    bead_id: z.ZodString;
+    progress_percent: z.ZodOptional<z.ZodNumber>;
+    message: z.ZodOptional<z.ZodString>;
+    files_touched: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const TaskCompletedEventSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"task_completed">;
+    agent_name: z.ZodString;
+    bead_id: z.ZodString;
+    summary: z.ZodString;
+    files_touched: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    success: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const TaskBlockedEventSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"task_blocked">;
+    agent_name: z.ZodString;
+    bead_id: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export declare const DecompositionGeneratedEventSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"decomposition_generated">;
+    epic_id: z.ZodString;
+    task: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+    strategy: z.ZodEnum<{
+        "file-based": "file-based";
+        "feature-based": "feature-based";
+        "risk-based": "risk-based";
+    }>;
+    epic_title: z.ZodString;
+    subtasks: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        files: z.ZodArray<z.ZodString>;
+        priority: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    recovery_context: z.ZodOptional<z.ZodObject<{
+        shared_context: z.ZodOptional<z.ZodString>;
+        skills_to_load: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        coordinator_notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const SubtaskOutcomeEventSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"subtask_outcome">;
+    epic_id: z.ZodString;
+    bead_id: z.ZodString;
+    planned_files: z.ZodArray<z.ZodString>;
+    actual_files: z.ZodArray<z.ZodString>;
+    duration_ms: z.ZodNumber;
+    error_count: z.ZodDefault<z.ZodNumber>;
+    retry_count: z.ZodDefault<z.ZodNumber>;
+    success: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const HumanFeedbackEventSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"human_feedback">;
+    epic_id: z.ZodString;
+    accepted: z.ZodBoolean;
+    modified: z.ZodDefault<z.ZodBoolean>;
+    notes: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const SwarmCheckpointedEventSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"swarm_checkpointed">;
+    epic_id: z.ZodString;
+    bead_id: z.ZodString;
+    strategy: z.ZodEnum<{
+        "file-based": "file-based";
+        "feature-based": "feature-based";
+        "risk-based": "risk-based";
+    }>;
+    files: z.ZodArray<z.ZodString>;
+    dependencies: z.ZodArray<z.ZodString>;
+    directives: z.ZodObject<{
+        shared_context: z.ZodOptional<z.ZodString>;
+        skills_to_load: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        coordinator_notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    recovery: z.ZodObject<{
+        last_checkpoint: z.ZodNumber;
+        files_modified: z.ZodArray<z.ZodString>;
+        progress_percent: z.ZodNumber;
+        last_message: z.ZodOptional<z.ZodString>;
+        error_context: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const SwarmRecoveredEventSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"swarm_recovered">;
+    epic_id: z.ZodString;
+    bead_id: z.ZodString;
+    recovered_from_checkpoint: z.ZodNumber;
+}, z.core.$strip>;
+export declare const AgentEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"agent_registered">;
+    agent_name: z.ZodString;
+    program: z.ZodDefault<z.ZodString>;
+    model: z.ZodDefault<z.ZodString>;
+    task_description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"agent_active">;
+    agent_name: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"message_sent">;
+    message_id: z.ZodOptional<z.ZodNumber>;
+    from_agent: z.ZodString;
+    to_agents: z.ZodArray<z.ZodString>;
+    subject: z.ZodString;
+    body: z.ZodString;
+    thread_id: z.ZodOptional<z.ZodString>;
+    importance: z.ZodDefault<z.ZodEnum<{
+        low: "low";
+        normal: "normal";
+        high: "high";
+        urgent: "urgent";
+    }>>;
+    ack_required: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"message_read">;
+    message_id: z.ZodNumber;
+    agent_name: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"message_acked">;
+    message_id: z.ZodNumber;
+    agent_name: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"file_reserved">;
+    reservation_id: z.ZodOptional<z.ZodNumber>;
+    agent_name: z.ZodString;
+    paths: z.ZodArray<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+    exclusive: z.ZodDefault<z.ZodBoolean>;
+    ttl_seconds: z.ZodDefault<z.ZodNumber>;
+    expires_at: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"file_released">;
+    agent_name: z.ZodString;
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    reservation_ids: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"task_started">;
+    agent_name: z.ZodString;
+    bead_id: z.ZodString;
+    epic_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"task_progress">;
+    agent_name: z.ZodString;
+    bead_id: z.ZodString;
+    progress_percent: z.ZodOptional<z.ZodNumber>;
+    message: z.ZodOptional<z.ZodString>;
+    files_touched: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"task_completed">;
+    agent_name: z.ZodString;
+    bead_id: z.ZodString;
+    summary: z.ZodString;
+    files_touched: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    success: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"task_blocked">;
+    agent_name: z.ZodString;
+    bead_id: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"decomposition_generated">;
+    epic_id: z.ZodString;
+    task: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+    strategy: z.ZodEnum<{
+        "file-based": "file-based";
+        "feature-based": "feature-based";
+        "risk-based": "risk-based";
+    }>;
+    epic_title: z.ZodString;
+    subtasks: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        files: z.ZodArray<z.ZodString>;
+        priority: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    recovery_context: z.ZodOptional<z.ZodObject<{
+        shared_context: z.ZodOptional<z.ZodString>;
+        skills_to_load: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        coordinator_notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"subtask_outcome">;
+    epic_id: z.ZodString;
+    bead_id: z.ZodString;
+    planned_files: z.ZodArray<z.ZodString>;
+    actual_files: z.ZodArray<z.ZodString>;
+    duration_ms: z.ZodNumber;
+    error_count: z.ZodDefault<z.ZodNumber>;
+    retry_count: z.ZodDefault<z.ZodNumber>;
+    success: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"human_feedback">;
+    epic_id: z.ZodString;
+    accepted: z.ZodBoolean;
+    modified: z.ZodDefault<z.ZodBoolean>;
+    notes: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"swarm_checkpointed">;
+    epic_id: z.ZodString;
+    bead_id: z.ZodString;
+    strategy: z.ZodEnum<{
+        "file-based": "file-based";
+        "feature-based": "feature-based";
+        "risk-based": "risk-based";
+    }>;
+    files: z.ZodArray<z.ZodString>;
+    dependencies: z.ZodArray<z.ZodString>;
+    directives: z.ZodObject<{
+        shared_context: z.ZodOptional<z.ZodString>;
+        skills_to_load: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        coordinator_notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    recovery: z.ZodObject<{
+        last_checkpoint: z.ZodNumber;
+        files_modified: z.ZodArray<z.ZodString>;
+        progress_percent: z.ZodNumber;
+        last_message: z.ZodOptional<z.ZodString>;
+        error_context: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    project_key: z.ZodString;
+    timestamp: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"swarm_recovered">;
+    epic_id: z.ZodString;
+    bead_id: z.ZodString;
+    recovered_from_checkpoint: z.ZodNumber;
+}, z.core.$strip>], "type">;
+export type AgentEvent = z.infer<typeof AgentEventSchema>;
+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>;
+/**
+ * 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;
+}
+/**
+ * Create an event with timestamp and validate
+ */
+export declare function createEvent<T extends AgentEvent["type"]>(type: T, data: Omit<Extract<AgentEvent, {
+    type: T;
+}>, "type" | "timestamp" | "id" | "sequence">): Extract<AgentEvent, {
+    type: T;
+}>;
+/**
+ * Type guard for specific event types
+ */
+export declare function isEventType<T extends AgentEvent["type"]>(event: AgentEvent, type: T): event is Extract<AgentEvent, {
+    type: T;
+}>;
+//# sourceMappingURL=events.d.ts.map

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

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

package/dist/streams/index.d.ts

@@ -0,0 +1,106 @@
+/**
+ * SwarmMail Event Store - PGLite-based event sourcing
+ *
+ * ## Thread Safety
+ *
+ * PGLite runs in-process as a single-threaded SQLite-compatible database.
+ * While Node.js is single-threaded, async operations can interleave.
+ *
+ * **Concurrency Model:**
+ * - Single PGLite instance per project (singleton pattern via LRU cache)
+ * - Transactions provide isolation for multi-statement operations
+ * - appendEvents uses BEGIN/COMMIT for atomic event batches
+ * - Concurrent reads are safe (no locks needed)
+ * - Concurrent writes are serialized by PGLite internally
+ *
+ * **Race Condition Mitigations:**
+ * - File reservations use INSERT with conflict detection
+ * - Sequence numbers are auto-incremented by database
+ * - Materialized views updated within same transaction as events
+ * - Pending instance promises prevent duplicate initialization
+ *
+ * **Known Limitations:**
+ * - No distributed locking (single-process only)
+ * - Large transactions may block other operations
+ * - No connection pooling (embedded database)
+ *
+ * ## Database Setup
+ *
+ * Embedded PostgreSQL database for event sourcing.
+ * No external server required - runs in-process.
+ *
+ * Database location: .opencode/streams.db (project-local)
+ * or ~/.opencode/streams.db (global fallback)
+ */
+import { PGlite } from "@electric-sql/pglite";
+/**
+ * Wrap a promise with a timeout
+ *
+ * @param promise - The promise to wrap
+ * @param ms - Timeout in milliseconds
+ * @param operation - Operation name for error message
+ * @returns The result of the promise
+ * @throws Error if timeout is reached
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, operation: string): Promise<T>;
+/**
+ * Execute a database operation with timing instrumentation.
+ * Logs a warning if the operation exceeds SLOW_QUERY_THRESHOLD_MS.
+ *
+ * @param operation - Name of the operation for logging
+ * @param fn - Async function to execute
+ * @returns Result of the function
+ */
+export declare function withTiming<T>(operation: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Get the database path for a project
+ *
+ * Prefers project-local .opencode/streams.db
+ * Falls back to global ~/.opencode/streams.db
+ */
+export declare function getDatabasePath(projectPath?: string): string;
+/**
+ * Get or create a PGLite instance for the given path
+ *
+ * If initialization fails, falls back to in-memory database and marks instance as degraded.
+ *
+ * Uses Promise-based caching to prevent race conditions when multiple concurrent
+ * calls occur before the first one completes.
+ */
+export declare function getDatabase(projectPath?: string): Promise<PGlite>;
+/**
+ * Close a database instance
+ */
+export declare function closeDatabase(projectPath?: string): Promise<void>;
+/**
+ * Close all database instances
+ */
+export declare function closeAllDatabases(): Promise<void>;
+/**
+ * Reset database for testing - clears all data but keeps schema
+ */
+export declare function resetDatabase(projectPath?: string): Promise<void>;
+/**
+ * Check if the database is healthy
+ *
+ * Returns false if database is in degraded mode (using in-memory fallback)
+ */
+export declare function isDatabaseHealthy(projectPath?: string): Promise<boolean>;
+/**
+ * Get database statistics
+ */
+export declare function getDatabaseStats(projectPath?: string): Promise<{
+    events: number;
+    agents: number;
+    messages: number;
+    reservations: number;
+}>;
+export { PGlite };
+export * from "./agent-mail";
+export * from "./debug";
+export * from "./events";
+export * from "./migrations";
+export * from "./projections";
+export * from "./store";
+export * from "./swarm-mail";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/streams/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAW9C;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,CAAC,CAAC,CAQZ;AASD;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAYZ;AAwBD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAkB5D;AA2DD;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA6BvE;AAqED;;GAEG;AACH,wBAAsB,aAAa,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWvE;AAED;;GAEG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CASvD;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWvE;AAwHD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,OAAO,CAAC,CAqBlB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC,CAkBD;AAuCD,OAAO,EAAE,MAAM,EAAE,CAAC;AAClB,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC"}