swarm-mail 0.1.0 → 0.1.2

package/{src/pglite.ts → dist/pglite.d.ts}

@@ -22,31 +22,8 @@
  * const swarmMail = createSwarmMailAdapter(db, '/path/to/project');
  * ```
  */
-
 import { PGlite } from "@electric-sql/pglite";
-import { createSwarmMailAdapter } from "./adapter";
-import type { DatabaseAdapter, SwarmMailAdapter } from "./types";
-import { existsSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
-
-/**
- * Wrap PGLite to match DatabaseAdapter interface
- *
- * PGLite has query() and exec() methods that match DatabaseAdapter,
- * but TypeScript needs the explicit wrapper for type safety.
- * PGLite's exec() returns Results[] but DatabaseAdapter expects void.
- */
-function wrapPGlite(pglite: PGlite): DatabaseAdapter {
-  return {
-    query: <T>(sql: string, params?: unknown[]) => pglite.query<T>(sql, params),
-    exec: async (sql: string) => {
-      await pglite.exec(sql);
-    },
-    close: () => pglite.close(),
-  };
-}
-
+import type { SwarmMailAdapter } from "./types";
 /**
  * Get database path (project-local or global fallback)
  *
@@ -56,31 +33,7 @@ function wrapPGlite(pglite: PGlite): DatabaseAdapter {
  * @param projectPath - Optional project root path
  * @returns Absolute path to database directory
  */
-export function getDatabasePath(projectPath?: string): string {
-  if (projectPath) {
-    const localDir = join(projectPath, ".opencode");
-    if (!existsSync(localDir)) {
-      mkdirSync(localDir, { recursive: true });
-    }
-    return join(localDir, "streams");
-  }
-  const globalDir = join(homedir(), ".opencode");
-  if (!existsSync(globalDir)) {
-    mkdirSync(globalDir, { recursive: true });
-  }
-  return join(globalDir, "streams");
-}
-
-/**
- * Singleton cache for SwarmMail instances
- *
- * Key is database path, value is the adapter + PGLite instance
- */
-const instances = new Map<
-  string,
-  { adapter: SwarmMailAdapter; pglite: PGlite }
->();
-
+export declare function getDatabasePath(projectPath?: string): string;
 /**
  * Get or create SwarmMail instance for a project
  *
@@ -99,23 +52,7 @@ const instances = new Map<
  * const swarmMail = await getSwarmMail();
  * ```
  */
-export async function getSwarmMail(
-  projectPath?: string,
-): Promise<SwarmMailAdapter> {
-  const dbPath = getDatabasePath(projectPath);
-  const projectKey = projectPath || dbPath;
-
-  if (!instances.has(dbPath)) {
-    const pglite = new PGlite(dbPath);
-    const db = wrapPGlite(pglite);
-    const adapter = createSwarmMailAdapter(db, projectKey);
-    await adapter.runMigrations();
-    instances.set(dbPath, { adapter, pglite });
-  }
-
-  return instances.get(dbPath)!.adapter;
-}
-
+export declare function getSwarmMail(projectPath?: string): Promise<SwarmMailAdapter>;
 /**
  * Create in-memory SwarmMail instance (for testing)
  *
@@ -133,16 +70,7 @@ export async function getSwarmMail(
  * await swarmMail.close();
  * ```
  */
-export async function createInMemorySwarmMail(
-  projectKey = "test",
-): Promise<SwarmMailAdapter> {
-  const pglite = new PGlite(); // in-memory
-  const db = wrapPGlite(pglite);
-  const adapter = createSwarmMailAdapter(db, projectKey);
-  await adapter.runMigrations();
-  return adapter;
-}
-
+export declare function createInMemorySwarmMail(projectKey?: string): Promise<SwarmMailAdapter>;
 /**
  * Close specific SwarmMail instance
  *
@@ -155,15 +83,7 @@ export async function createInMemorySwarmMail(
  * await closeSwarmMail('/path/to/project');
  * ```
  */
-export async function closeSwarmMail(projectPath?: string): Promise<void> {
-  const dbPath = getDatabasePath(projectPath);
-  const instance = instances.get(dbPath);
-  if (instance) {
-    await instance.pglite.close();
-    instances.delete(dbPath);
-  }
-}
-
+export declare function closeSwarmMail(projectPath?: string): Promise<void>;
 /**
  * Close all SwarmMail instances
  *
@@ -178,12 +98,6 @@ export async function closeSwarmMail(projectPath?: string): Promise<void> {
  * });
  * ```
  */
-export async function closeAllSwarmMail(): Promise<void> {
-  for (const [path, instance] of instances) {
-    await instance.pglite.close();
-    instances.delete(path);
-  }
-}
-
-// Re-export PGlite for consumers who need it
+export declare function closeAllSwarmMail(): Promise<void>;
 export { PGlite };
+//# sourceMappingURL=pglite.d.ts.map

package/dist/pglite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pglite.d.ts","sourceRoot":"","sources":["../src/pglite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE9C,OAAO,KAAK,EAAmB,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAsBjE;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAa5D;AAYD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,YAAY,CAChC,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,gBAAgB,CAAC,CAa3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,uBAAuB,CAC3C,UAAU,SAAS,GAClB,OAAO,CAAC,gBAAgB,CAAC,CAM3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOxE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKvD;AAGD,OAAO,EAAE,MAAM,EAAE,CAAC"}

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

@@ -0,0 +1,139 @@
+export interface AgentMailContext {
+    projectKey: string;
+    agentName: string;
+}
+export interface InitAgentOptions {
+    projectPath: string;
+    agentName?: string;
+    program?: string;
+    model?: string;
+    taskDescription?: string;
+}
+export interface SendMessageOptions {
+    projectPath: string;
+    fromAgent: string;
+    toAgents: string[];
+    subject: string;
+    body: string;
+    threadId?: string;
+    importance?: "low" | "normal" | "high" | "urgent";
+    ackRequired?: boolean;
+}
+export interface SendMessageResult {
+    success: boolean;
+    messageId: number;
+    threadId?: string;
+    recipientCount: number;
+}
+export interface GetInboxOptions {
+    projectPath: string;
+    agentName: string;
+    limit?: number;
+    urgentOnly?: boolean;
+    unreadOnly?: boolean;
+    includeBodies?: boolean;
+}
+export interface InboxMessage {
+    id: number;
+    from_agent: string;
+    subject: string;
+    body?: string;
+    thread_id: string | null;
+    importance: string;
+    created_at: number;
+}
+export interface InboxResult {
+    messages: InboxMessage[];
+    total: number;
+}
+export interface ReadMessageOptions {
+    projectPath: string;
+    messageId: number;
+    agentName?: string;
+    markAsRead?: boolean;
+}
+export interface ReserveFilesOptions {
+    projectPath: string;
+    agentName: string;
+    paths: string[];
+    reason?: string;
+    exclusive?: boolean;
+    ttlSeconds?: number;
+    force?: boolean;
+}
+export interface GrantedReservation {
+    id: number;
+    path: string;
+    expiresAt: number;
+}
+export interface ReservationConflict {
+    path: string;
+    holder: string;
+    pattern: string;
+}
+export interface ReserveFilesResult {
+    granted: GrantedReservation[];
+    conflicts: ReservationConflict[];
+}
+export interface ReleaseFilesOptions {
+    projectPath: string;
+    agentName: string;
+    paths?: string[];
+    reservationIds?: number[];
+}
+export interface ReleaseFilesResult {
+    released: number;
+    releasedAt: number;
+}
+export interface AcknowledgeOptions {
+    projectPath: string;
+    messageId: number;
+    agentName: string;
+}
+export interface AcknowledgeResult {
+    acknowledged: boolean;
+    acknowledgedAt: string | null;
+}
+export interface HealthResult {
+    healthy: boolean;
+    database: "connected" | "disconnected";
+    stats?: {
+        events: number;
+        agents: number;
+        messages: number;
+        reservations: number;
+    };
+}
+/**
+ * Initialize an agent for this session
+ */
+export declare function initAgent(options: InitAgentOptions): Promise<AgentMailContext>;
+/**
+ * Send a message to other agents
+ */
+export declare function sendAgentMessage(options: SendMessageOptions): Promise<SendMessageResult>;
+/**
+ * Get inbox messages for an agent
+ */
+export declare function getAgentInbox(options: GetInboxOptions): Promise<InboxResult>;
+/**
+ * Read a single message with full body
+ */
+export declare function readAgentMessage(options: ReadMessageOptions): Promise<InboxMessage | null>;
+/**
+ * Reserve files for exclusive editing
+ */
+export declare function reserveAgentFiles(options: ReserveFilesOptions): Promise<ReserveFilesResult>;
+/**
+ * Release file reservations
+ */
+export declare function releaseAgentFiles(options: ReleaseFilesOptions): Promise<ReleaseFilesResult>;
+/**
+ * Acknowledge a message
+ */
+export declare function acknowledgeMessage(options: AcknowledgeOptions): Promise<AcknowledgeResult>;
+/**
+ * Check if the agent mail store is healthy
+ */
+export declare function checkHealth(projectPath?: string): Promise<HealthResult>;
+//# sourceMappingURL=agent-mail.d.ts.map

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

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

package/dist/streams/debug.d.ts

@@ -0,0 +1,173 @@
+import type { AgentEvent } from "./events";
+export interface DebugEventsOptions {
+    projectPath: string;
+    types?: AgentEvent["type"][];
+    agentName?: string;
+    limit?: number;
+    since?: number;
+    until?: number;
+}
+export interface DebugEventResult {
+    id: number;
+    sequence: number;
+    type: AgentEvent["type"];
+    timestamp: number;
+    timestamp_human: string;
+    agent_name?: string;
+    from_agent?: string;
+    to_agents?: string[];
+    [key: string]: unknown;
+}
+export interface DebugEventsResult {
+    events: DebugEventResult[];
+    total: number;
+}
+export interface DebugAgentOptions {
+    projectPath: string;
+    agentName: string;
+    includeEvents?: boolean;
+}
+export interface DebugAgentResult {
+    agent: {
+        name: string;
+        program: string;
+        model: string;
+        task_description: string | null;
+        registered_at: number;
+        last_active_at: number;
+    } | null;
+    stats: {
+        messagesSent: number;
+        messagesReceived: number;
+    };
+    reservations: Array<{
+        id: number;
+        path: string;
+        reason: string | null;
+        expires_at: number;
+    }>;
+    recentEvents?: DebugEventResult[];
+}
+export interface DebugMessageOptions {
+    projectPath: string;
+    messageId: number;
+    includeEvents?: boolean;
+}
+export interface DebugMessageResult {
+    message: {
+        id: number;
+        from_agent: string;
+        subject: string;
+        body: string;
+        thread_id: string | null;
+        importance: string;
+        created_at: number;
+    } | null;
+    recipients: Array<{
+        agent_name: string;
+        read_at: number | null;
+        acked_at: number | null;
+    }>;
+    events?: DebugEventResult[];
+}
+export interface DebugReservationsOptions {
+    projectPath: string;
+    checkConflicts?: boolean;
+}
+export interface DebugReservationsResult {
+    reservations: Array<{
+        id: number;
+        agent_name: string;
+        path_pattern: string;
+        reason: string | null;
+        expires_at: number;
+        expires_in_human: string;
+    }>;
+    byAgent: Record<string, Array<{
+        path: string;
+        expires_at: number;
+    }>>;
+    conflicts?: Array<{
+        path1: string;
+        agent1: string;
+        path2: string;
+        agent2: string;
+    }>;
+}
+export interface TimelineEntry {
+    time: string;
+    type: AgentEvent["type"];
+    summary: string;
+    agent: string;
+    sequence: number;
+}
+export interface TimelineResult {
+    timeline: TimelineEntry[];
+}
+export interface InspectStateOptions {
+    projectPath: string;
+    format?: "object" | "json";
+}
+export interface InspectStateResult {
+    agents: Array<{
+        name: string;
+        program: string;
+        model: string;
+        task_description: string | null;
+    }>;
+    messages: Array<{
+        id: number;
+        from_agent: string;
+        subject: string;
+        thread_id: string | null;
+    }>;
+    reservations: Array<{
+        id: number;
+        agent_name: string;
+        path_pattern: string;
+    }>;
+    eventCount: number;
+    latestSequence: number;
+    stats: {
+        events: number;
+        agents: number;
+        messages: number;
+        reservations: number;
+    };
+    json?: string;
+}
+/**
+ * Get recent events with filtering
+ *
+ * For large event logs (>100k events), consider using batchSize option
+ * to paginate through results instead of loading all events.
+ */
+export declare function debugEvents(options: DebugEventsOptions & {
+    batchSize?: number;
+}): Promise<DebugEventsResult>;
+/**
+ * Get detailed agent information
+ */
+export declare function debugAgent(options: DebugAgentOptions): Promise<DebugAgentResult>;
+/**
+ * Get detailed message information with audit trail
+ */
+export declare function debugMessage(options: DebugMessageOptions): Promise<DebugMessageResult>;
+/**
+ * Get current reservation state
+ */
+export declare function debugReservations(options: DebugReservationsOptions): Promise<DebugReservationsResult>;
+/**
+ * Get event timeline for visualization
+ */
+export declare function getEventTimeline(options: {
+    projectPath: string;
+    since?: number;
+    until?: number;
+    limit?: number;
+}): Promise<TimelineResult>;
+/**
+ * Get complete state snapshot for debugging
+ */
+export declare function inspectState(options: InspectStateOptions): Promise<InspectStateResult>;
+//# sourceMappingURL=debug.d.ts.map

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

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

package/dist/streams/effect/ask.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Ask Pattern - Request/Response over Durable Streams
+ *
+ * Combines DurableMailbox (message passing) + DurableDeferred (distributed promise)
+ * for synchronous-style request/response communication between agents.
+ *
+ * Based on Kyle Matthews' pattern from Agent Mail.
+ *
+ * @example
+ * ```typescript
+ * // Agent A asks Agent B for data
+ * const result = yield* ask<Request, Response>({
+ *   mailbox: myMailbox,
+ *   to: "agent-b",
+ *   payload: { query: "getUserData", userId: 123 },
+ *   ttlSeconds: 30,
+ * });
+ *
+ * // Agent B receives request and responds
+ * for await (const envelope of mailbox.receive()) {
+ *   const response = processRequest(envelope.payload);
+ *   if (envelope.replyTo) {
+ *     yield* DurableDeferred.resolve(envelope.replyTo, response);
+ *   }
+ *   yield* envelope.commit();
+ * }
+ * ```
+ */
+import { Effect } from "effect";
+import { DurableCursor } from "./cursor";
+import { DurableMailbox, type Mailbox } from "./mailbox";
+import { DurableDeferred } from "./deferred";
+import type { TimeoutError, NotFoundError } from "./deferred";
+/**
+ * Configuration for ask() request
+ */
+export interface AskConfig<Req> {
+    /** Mailbox to send message from */
+    readonly mailbox: Mailbox;
+    /** Recipient agent(s) */
+    readonly to: string | string[];
+    /** Request payload */
+    readonly payload: Req;
+    /** Time-to-live in seconds before timeout (default: 60) */
+    readonly ttlSeconds?: number;
+    /** Optional thread ID for conversation tracking */
+    readonly threadId?: string;
+    /** Optional importance level */
+    readonly importance?: "low" | "normal" | "high" | "urgent";
+    /** Optional project path for database isolation */
+    readonly projectPath?: string;
+}
+/**
+ * Request/response pattern combining mailbox send + deferred await
+ *
+ * Creates a deferred promise, sends message with replyTo URL, then blocks
+ * until the recipient resolves the deferred (or timeout).
+ *
+ * @template Req - Request payload type
+ * @template Res - Response type
+ * @param config - Ask configuration
+ * @returns Effect that resolves with response or fails with timeout/not-found
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const mailbox = yield* DurableMailbox;
+ *   const myMailbox = yield* mailbox.create({ agent: "worker-1", projectKey: "proj" });
+ *
+ *   const response = yield* ask<Request, Response>({
+ *     mailbox: myMailbox,
+ *     to: "worker-2",
+ *     payload: { task: "getData" },
+ *     ttlSeconds: 30,
+ *   });
+ *
+ *   console.log("Got response:", response);
+ * });
+ * ```
+ */
+export declare function ask<Req, Res>(config: AskConfig<Req>): Effect.Effect<Res, TimeoutError | NotFoundError, DurableDeferred>;
+/**
+ * Ask pattern with automatic mailbox creation
+ *
+ * Simpler variant when you don't need to reuse the mailbox.
+ *
+ * @example
+ * ```typescript
+ * const response = yield* askWithMailbox({
+ *   agent: "worker-1",
+ *   projectKey: "proj",
+ *   to: "worker-2",
+ *   payload: { task: "getData" },
+ * });
+ * ```
+ */
+export declare function askWithMailbox<Req, Res>(config: {
+    readonly agent: string;
+    readonly projectKey: string;
+    readonly to: string | string[];
+    readonly payload: Req;
+    readonly ttlSeconds?: number;
+    readonly threadId?: string;
+    readonly importance?: "low" | "normal" | "high" | "urgent";
+    readonly projectPath?: string;
+}): Effect.Effect<Res, TimeoutError | NotFoundError, DurableDeferred | DurableMailbox | DurableCursor>;
+/**
+ * Respond to a message envelope by resolving its replyTo deferred
+ *
+ * Helper for the receiver side of ask() pattern.
+ *
+ * @example
+ * ```typescript
+ * for await (const envelope of mailbox.receive()) {
+ *   const response = processRequest(envelope.payload);
+ *   yield* respond(envelope, response);
+ *   yield* envelope.commit();
+ * }
+ * ```
+ */
+export declare function respond<T>(envelope: {
+    readonly replyTo?: string;
+}, value: T, projectPath?: string): Effect.Effect<void, NotFoundError, DurableDeferred>;
+//# sourceMappingURL=ask.d.ts.map

package/dist/streams/effect/ask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../../src/streams/effect/ask.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,eAAe,EAAuB,MAAM,YAAY,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAM9D;;GAEG;AACH,MAAM,WAAW,SAAS,CAAC,GAAG;IAC5B,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,yBAAyB;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC/B,sBAAsB;IACtB,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,gCAAgC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;IAC3D,mDAAmD;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,GAAG,EAC1B,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,GACrB,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,YAAY,GAAG,aAAa,EAAE,eAAe,CAAC,CAwBnE;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B,GAAG,MAAM,CAAC,MAAM,CACf,GAAG,EACH,YAAY,GAAG,aAAa,EAC5B,eAAe,GAAG,cAAc,GAAG,aAAa,CACjD,CAoBA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,QAAQ,EAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,EACvC,KAAK,EAAE,CAAC,EACR,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,aAAa,EAAE,eAAe,CAAC,CAUrD"}

package/dist/streams/effect/cursor.d.ts

@@ -0,0 +1,87 @@
+/**
+ * DurableCursor - Positioned event stream consumption with checkpointing
+ *
+ * Effect-TS service that wraps event stream reading with cursor state management.
+ * Enables reliable event processing with resumable position tracking.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const cursor = yield* DurableCursor;
+ *   const consumer = yield* cursor.create({
+ *     stream: "projects/foo/events",
+ *     checkpoint: "agents/bar/position"
+ *   });
+ *
+ *   for await (const msg of consumer.consume()) {
+ *     yield* handleMessage(msg.value);
+ *     yield* msg.commit();
+ *   }
+ * });
+ * ```
+ */
+import { Context, Effect } from "effect";
+import type { AgentEvent } from "../events";
+/**
+ * Configuration for creating a cursor
+ */
+export interface CursorConfig {
+    /** Stream identifier (e.g. "projects/foo/events") */
+    readonly stream: string;
+    /** Checkpoint identifier (e.g. "agents/bar/position") */
+    readonly checkpoint: string;
+    /** Project path for database location */
+    readonly projectPath?: string;
+    /** Batch size for reading events (default: 100) */
+    readonly batchSize?: number;
+    /** Optional filters for event types */
+    readonly types?: AgentEvent["type"][];
+}
+/**
+ * A message from the cursor with commit capability
+ */
+export interface CursorMessage<T = unknown> {
+    /** The event value */
+    readonly value: T;
+    /** Event sequence number */
+    readonly sequence: number;
+    /** Commit this position to the checkpoint */
+    readonly commit: () => Effect.Effect<void>;
+}
+/**
+ * A cursor instance for consuming events
+ */
+export interface Cursor {
+    /** Get current position */
+    readonly getPosition: () => Effect.Effect<number>;
+    /** Consume events as an async iterable */
+    readonly consume: <T = AgentEvent & {
+        id: number;
+        sequence: number;
+    }>() => AsyncIterable<CursorMessage<T>>;
+    /** Update checkpoint position */
+    readonly commit: (sequence: number) => Effect.Effect<void>;
+}
+/**
+ * DurableCursor service interface
+ */
+export interface DurableCursorService {
+    /** Create a new cursor instance */
+    readonly create: (config: CursorConfig) => Effect.Effect<Cursor>;
+}
+declare const DurableCursor_base: Context.TagClass<DurableCursor, "DurableCursor", DurableCursorService>;
+/**
+ * DurableCursor Context.Tag
+ */
+export declare class DurableCursor extends DurableCursor_base {
+}
+/**
+ * Live implementation of DurableCursor service
+ */
+export declare const DurableCursorLive: DurableCursorService;
+/**
+ * Default layer for DurableCursor service
+ */
+export declare const DurableCursorLayer: Context.Context<DurableCursor>;
+export {};
+//# sourceMappingURL=cursor.d.ts.map

package/dist/streams/effect/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../../src/streams/effect/cursor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAe,MAAM,QAAQ,CAAC;AAGtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAM5C;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,sBAAsB;IACtB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,4BAA4B;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,2BAA2B;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAClD,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,CAChB,CAAC,GAAG,UAAU,GAAG;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,OAC5C,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACvC,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;CAClE;;AAMD;;GAEG;AACH,qBAAa,aAAc,SAAQ,kBAGhC;CAAG;AAuLN;;GAEG;AACH,eAAO,MAAM,iBAAiB,sBAE5B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,kBAAkB,gCAG9B,CAAC"}