@agentuity/core 2.0.7 → 2.0.9-v3.48d5810

package/dist/services/coder/sse.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Server-Sent Events (SSE) client for observing Coder Hub sessions.
+ *
+ * SSE provides a unidirectional stream of events from the server, ideal for
+ * observers who want to watch session activity without sending commands.
+ *
+ * @module coder/sse
+ *
+ * @example Class-based API with callbacks
+ * ```typescript
+ * import { CoderSSEClient } from '@agentuity/core/coder';
+ *
+ * const client = new CoderSSEClient({
+ *   apiKey: 'your-api-key',
+ *   sessionId: 'session-123',
+ *   onSnapshot: (data) => {
+ *     console.log('Session state:', data);
+ *   },
+ *   onBroadcast: (data) => {
+ *     console.log('Broadcast event:', data.event, data.data);
+ *   },
+ *   onPresence: (data) => {
+ *     console.log('Participant:', data.event, data.participant);
+ *   },
+ *   onError: (err) => {
+ *     console.error('SSE error:', err);
+ *   },
+ * });
+ *
+ * client.connect();
+ *
+ * // Later: close the connection
+ * client.close();
+ * ```
+ *
+ * @example Async iterator API
+ * ```typescript
+ * import { streamCoderSessionSSE } from '@agentuity/core/coder';
+ *
+ * const controller = new AbortController();
+ *
+ * for await (const event of streamCoderSessionSSE({
+ *   sessionId: 'session-123',
+ *   signal: controller.signal,
+ * })) {
+ *   console.log('Event:', event.event, event.data);
+ *
+ *   if (event.event === 'broadcast' && event.data.event === 'session_complete') {
+ *     controller.abort(); // Stop the stream
+ *   }
+ * }
+ * ```
+ */
+import { z } from 'zod/v4';
+import type { Logger } from '../../logger.ts';
+import type { BroadcastEventMessage, ObserverSseMessage, PresenceEventMessage, SseHydrationMessage, SseSessionSnapshotMessage } from './protocol.ts';
+/**
+ * Options for the SSE client (both class-based and async iterator APIs).
+ */
+export declare const CoderSSEOptionsSchema: z.ZodObject<{
+    apiKey: z.ZodOptional<z.ZodString>;
+    orgId: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+    subscribe: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    logger: z.ZodOptional<z.ZodCustom<Logger, Logger>>;
+    reconnect: z.ZodOptional<z.ZodBoolean>;
+    maxReconnectAttempts: z.ZodOptional<z.ZodNumber>;
+    reconnectDelayMs: z.ZodOptional<z.ZodNumber>;
+    maxReconnectDelayMs: z.ZodOptional<z.ZodNumber>;
+    signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+}, z.core.$strip>;
+export type CoderSSEOptions = z.infer<typeof CoderSSEOptionsSchema>;
+/**
+ * Options for the class-based SSE client.
+ *
+ * Extends the base options with callbacks for each event type.
+ */
+export declare const CoderSSEClientOptionsSchema: z.ZodObject<{
+    apiKey: z.ZodOptional<z.ZodString>;
+    orgId: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+    subscribe: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    logger: z.ZodOptional<z.ZodCustom<Logger, Logger>>;
+    reconnect: z.ZodOptional<z.ZodBoolean>;
+    maxReconnectAttempts: z.ZodOptional<z.ZodNumber>;
+    reconnectDelayMs: z.ZodOptional<z.ZodNumber>;
+    maxReconnectDelayMs: z.ZodOptional<z.ZodNumber>;
+    signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+    onSnapshot: z.ZodOptional<z.ZodCustom<(data: SseSessionSnapshotMessage) => void, (data: SseSessionSnapshotMessage) => void>>;
+    onHydration: z.ZodOptional<z.ZodCustom<(data: SseHydrationMessage) => void, (data: SseHydrationMessage) => void>>;
+    onPresence: z.ZodOptional<z.ZodCustom<(data: PresenceEventMessage) => void, (data: PresenceEventMessage) => void>>;
+    onBroadcast: z.ZodOptional<z.ZodCustom<(data: BroadcastEventMessage) => void, (data: BroadcastEventMessage) => void>>;
+    onEvent: z.ZodOptional<z.ZodCustom<(event: CoderSSEEvent) => void, (event: CoderSSEEvent) => void>>;
+    onOpen: z.ZodOptional<z.ZodCustom<() => void, () => void>>;
+    onClose: z.ZodOptional<z.ZodCustom<() => void, () => void>>;
+    onError: z.ZodOptional<z.ZodCustom<(error: Error) => void, (error: Error) => void>>;
+}, z.core.$strip>;
+export type CoderSSEClientOptions = z.infer<typeof CoderSSEClientOptionsSchema>;
+/**
+ * Error type for SSE operations.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   for await (const event of streamCoderSessionSSE({ sessionId: 'invalid' })) {
+ *     // ...
+ *   }
+ * } catch (err) {
+ *   if (err instanceof CoderSSEError) {
+ *     console.log('SSE error code:', err.code);
+ *   }
+ * }
+ * ```
+ */
+export declare const CoderSSEError: {
+    new (args?: ({
+        code: "connection_failed" | "auth_failed" | "max_reconnects_exceeded" | "parse_error";
+        sessionId?: string;
+    } & {
+        message?: string;
+        cause?: unknown;
+    }) | undefined): import("../../error.ts").RichError & {
+        readonly _tag: "CoderSSEError";
+    } & Readonly<{
+        code: "connection_failed" | "auth_failed" | "max_reconnects_exceeded" | "parse_error";
+        sessionId?: string;
+    }>;
+    readonly defaultMessage?: string;
+};
+/**
+ * A single SSE event with its event name and parsed data.
+ */
+export interface CoderSSEEvent {
+    /** The SSE event name (e.g., 'snapshot', 'broadcast', 'presence') */
+    event: string;
+    /** The parsed event data */
+    data: ObserverSseMessage;
+}
+/**
+ * Connection state for the SSE client.
+ */
+export type CoderSSEState = 'connecting' | 'connected' | 'reconnecting' | 'closed';
+/**
+ * Class-based SSE client for observing Coder Hub sessions.
+ *
+ * Provides callback-based event handling for session observation via Server-Sent Events.
+ * Automatically reconnects on disconnection with exponential backoff.
+ *
+ * @example
+ * ```typescript
+ * const client = new CoderSSEClient({
+ *   apiKey: 'your-api-key',
+ *   sessionId: 'session-123',
+ *   onSnapshot: (data) => console.log('Snapshot:', data),
+ *   onBroadcast: (data) => console.log('Broadcast:', data),
+ *   onPresence: (data) => console.log('Presence:', data),
+ * });
+ *
+ * client.connect();
+ *
+ * // Check connection state
+ * console.log('State:', client.state);
+ * console.log('Connected:', client.isConnected);
+ *
+ * // Close when done
+ * client.close();
+ * ```
+ */
+export declare class CoderSSEClient {
+    #private;
+    constructor(options: CoderSSEClientOptions);
+    /**
+     * The current connection state.
+     *
+     * - `'connecting'` - Initial connection in progress
+     * - `'connected'` - Connected and receiving events
+     * - `'reconnecting'` - Reconnecting after disconnect
+     * - `'closed'` - Connection closed (manually or after max retries)
+     */
+    get state(): CoderSSEState;
+    /**
+     * Whether the client is currently connected and receiving events.
+     */
+    get isConnected(): boolean;
+    /**
+     * Establish the SSE connection and start receiving events.
+     *
+     * If already connected or connecting, this is a no-op.
+     * Automatically reconnects on disconnection unless `close()` was called.
+     */
+    connect(): void;
+    /**
+     * Close the SSE connection and stop receiving events.
+     *
+     * After calling `close()`, you can call `connect()` again to reconnect.
+     */
+    close(): void;
+}
+/**
+ * Stream Coder Hub session events via Server-Sent Events (SSE).
+ *
+ * Returns an async iterator that yields events as they arrive from the server.
+ * The connection is automatically managed (reconnection, cleanup).
+ *
+ * @param options - Configuration for the SSE subscription
+ * @yields Events from the session as they arrive
+ * @throws {CoderSSEError} If connection fails or max reconnection attempts exceeded
+ *
+ * @example
+ * ```typescript
+ * import { streamCoderSessionSSE } from '@agentuity/core/coder';
+ *
+ * // Basic usage
+ * for await (const event of streamCoderSessionSSE({
+ *   sessionId: 'session-123',
+ * })) {
+ *   if (event.event === 'snapshot') {
+ *     console.log('Session:', event.data.label);
+ *   } else if (event.event === 'broadcast') {
+ *     console.log('Event:', event.data.event);
+ *   }
+ * }
+ * ```
+ *
+ * @example With abort signal
+ * ```typescript
+ * const controller = new AbortController();
+ *
+ * // Stop after 60 seconds
+ * setTimeout(() => controller.abort(), 60000);
+ *
+ * for await (const event of streamCoderSessionSSE({
+ *   sessionId: 'session-123',
+ *   signal: controller.signal,
+ * })) {
+ *   console.log(event);
+ * }
+ * ```
+ *
+ * @example With event filtering
+ * ```typescript
+ * for await (const event of streamCoderSessionSSE({
+ *   sessionId: 'session-123',
+ *   subscribe: ['task_*', 'agent_*'],  // Only task and agent events
+ * })) {
+ *   console.log(event);
+ * }
+ * ```
+ */
+export declare function streamCoderSessionSSE(options: CoderSSEOptions): AsyncGenerator<CoderSSEEvent, void, unknown>;
+//# sourceMappingURL=sse.d.ts.map

package/dist/services/coder/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../../src/services/coder/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAM9C,OAAO,KAAK,EACX,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,EACzB,MAAM,eAAe,CAAC;AAIvB;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;iBAyBhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;iDAGvB,yBAAyB,KAAK,IAAI,SAAlC,yBAAyB,KAAK,IAAI;kDAKlC,mBAAmB,KAAK,IAAI,SAA5B,mBAAmB,KAAK,IAAI;iDAK5B,oBAAoB,KAAK,IAAI,SAA7B,oBAAoB,KAAK,IAAI;kDAK7B,qBAAqB,KAAK,IAAI,SAA9B,qBAAqB,KAAK,IAAI;+CAK7B,aAAa,KAAK,IAAI,UAAtB,aAAa,KAAK,IAAI;4CAIhB,IAAI,QAAJ,IAAI;6CAEH,IAAI,QAAJ,IAAI;+CAEF,KAAK,KAAK,IAAI,UAAd,KAAK,KAAK,IAAI;iBACvC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa;;cACnB,mBAAmB,GAAG,aAAa,GAAG,yBAAyB,GAAG,aAAa;oBACzE,MAAM;;;;;;;cADZ,mBAAmB,GAAG,aAAa,GAAG,yBAAyB,GAAG,aAAa;oBACzE,MAAM;;;CACf,CAAC;AAEL;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,IAAI,EAAE,kBAAkB,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,WAAW,GAAG,cAAc,GAAG,QAAQ,CAAC;AAmEnF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,cAAc;;gBA4Bd,OAAO,EAAE,qBAAqB;IAwB1C;;;;;;;OAOG;IACH,IAAI,KAAK,IAAI,aAAa,CAEzB;IAED;;OAEG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;;;OAKG;IACH,OAAO,IAAI,IAAI;IAaf;;;;OAIG;IACH,KAAK,IAAI,IAAI;CA0Kb;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAuB,qBAAqB,CAC3C,OAAO,EAAE,eAAe,GACtB,cAAc,CAAC,aAAa,EAAE,IAAI,EAAE,OAAO,CAAC,CA6M9C"}