@agentuity/core 2.0.9 → 2.0.11

package/dist/services/coder/sse.js

@@ -0,0 +1,676 @@
+/**
+ * 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 { StructuredError } from "../../error.js";
+import { APIClient } from "../api.js";
+import { getServiceUrls } from "../config.js";
+import { createMinimalLogger } from "../logger.js";
+import { getEnv } from "../env.js";
+import { discoverUrl } from "./discover.js";
+import { ObserverSseMessageSchema } from "./protocol.js";
+import { normalizeCoderUrl } from "./util.js";
+/**
+ * Options for the SSE client (both class-based and async iterator APIs).
+ */
+export const CoderSSEOptionsSchema = z.object({
+    /** API key for authentication. Falls back to AGENTUITY_SDK_KEY or AGENTUITY_CLI_KEY env vars. */
+    apiKey: z.string().optional().describe('API key for authentication'),
+    /** Organization ID for multi-tenant operations */
+    orgId: z.string().optional().describe('Organization ID for multi-tenant operations'),
+    /** Session ID to observe (required) */
+    sessionId: z.string().describe('Session ID to observe'),
+    /** Base URL for the Coder Hub. Falls back to AGENTUITY_CODER_URL env var. */
+    url: z.string().optional().describe('Base URL for the Coder Hub'),
+    /** Region used for Catalyst URL resolution when no explicit URL is provided */
+    region: z.string().optional().describe('Region used for Catalyst URL resolution'),
+    /** Event filters to subscribe to. Empty subscribes to default observer events. */
+    subscribe: z.array(z.string()).optional().describe('Event filters to subscribe to'),
+    /** Custom logger implementation */
+    logger: z.custom().optional().describe('Custom logger implementation'),
+    /** Enable automatic reconnection on disconnect (default: true) */
+    reconnect: z.boolean().optional().describe('Enable automatic reconnection'),
+    /** Maximum reconnection attempts before giving up (default: 10) */
+    maxReconnectAttempts: z.number().optional().describe('Maximum reconnection attempts'),
+    /** Initial reconnection delay in milliseconds (default: 1000) */
+    reconnectDelayMs: z.number().optional().describe('Initial reconnection delay'),
+    /** Maximum reconnection delay in milliseconds (default: 30000) */
+    maxReconnectDelayMs: z.number().optional().describe('Maximum reconnection delay'),
+    /** AbortSignal to stop the subscription (async iterator only) */
+    signal: z.custom().optional().describe('AbortSignal to stop the subscription'),
+});
+/**
+ * Options for the class-based SSE client.
+ *
+ * Extends the base options with callbacks for each event type.
+ */
+export const CoderSSEClientOptionsSchema = CoderSSEOptionsSchema.extend({
+    /** Called when the initial session snapshot is received */
+    onSnapshot: z
+        .custom()
+        .optional()
+        .describe('Callback for snapshot events'),
+    /** Called when hydration data (conversation history) is received */
+    onHydration: z
+        .custom()
+        .optional()
+        .describe('Callback for hydration events'),
+    /** Called when presence events (join/leave) occur */
+    onPresence: z
+        .custom()
+        .optional()
+        .describe('Callback for presence events'),
+    /** Called for broadcast events (session activity updates) */
+    onBroadcast: z
+        .custom()
+        .optional()
+        .describe('Callback for broadcast events'),
+    /** Called for any SSE event (catch-all) */
+    onEvent: z
+        .custom()
+        .optional()
+        .describe('Callback for all events'),
+    /** Called when connection is established */
+    onOpen: z.custom().optional().describe('Callback when connection opens'),
+    /** Called when connection closes */
+    onClose: z.custom().optional().describe('Callback when connection closes'),
+    /** Called on errors */
+    onError: z.custom().optional().describe('Callback on error'),
+});
+/**
+ * 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 const CoderSSEError = StructuredError('CoderSSEError')();
+async function buildSSEUrl(sessionId, options) {
+    let baseUrl = options.url;
+    if (!baseUrl) {
+        const envUrl = getEnv('AGENTUITY_CODER_URL');
+        if (envUrl) {
+            baseUrl = normalizeCoderUrl(envUrl);
+        }
+        else {
+            const region = options.region ?? getEnv('AGENTUITY_REGION') ?? 'usc';
+            const catalystUrl = getServiceUrls(region).catalyst;
+            const headers = {};
+            if (options.orgId) {
+                headers['x-agentuity-orgid'] = options.orgId;
+            }
+            const logger = options.logger ?? createMinimalLogger();
+            const catalystClient = new APIClient(catalystUrl, logger, options.apiKey ?? '', {
+                headers,
+            });
+            try {
+                baseUrl = await discoverUrl(catalystClient);
+            }
+            catch (err) {
+                throw new CoderSSEError({
+                    message: `Failed to discover Coder URL: ${err instanceof Error ? err.message : String(err)}`,
+                    code: 'connection_failed',
+                    sessionId,
+                });
+            }
+        }
+    }
+    baseUrl = baseUrl.replace(/\/$/, '');
+    const path = `/api/hub/session/${encodeURIComponent(sessionId)}/events`;
+    const params = new URLSearchParams();
+    if (options.subscribe && options.subscribe.length > 0) {
+        params.set('subscribe', options.subscribe.join(','));
+    }
+    if (options.apiKey) {
+        params.set('api_key', options.apiKey);
+    }
+    if (options.orgId) {
+        params.set('org_id', options.orgId);
+    }
+    const queryString = params.toString();
+    return queryString ? `${baseUrl}${path}?${queryString}` : `${baseUrl}${path}`;
+}
+function getSSEData(event) {
+    const msgEvent = event;
+    if (typeof msgEvent.data === 'string') {
+        return msgEvent.data;
+    }
+    return null;
+}
+/**
+ * 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 class CoderSSEClient {
+    #options;
+    #state = 'closed';
+    #eventSource = null;
+    #reconnectAttempts = 0;
+    #reconnectTimer = null;
+    #intentionallyClosed = false;
+    constructor(options) {
+        this.#options = {
+            sessionId: options.sessionId,
+            url: options.url,
+            region: options.region ?? getEnv('AGENTUITY_REGION') ?? 'usc',
+            apiKey: options.apiKey ?? getEnv('AGENTUITY_SDK_KEY') ?? getEnv('AGENTUITY_CLI_KEY') ?? '',
+            orgId: options.orgId ?? '',
+            subscribe: options.subscribe,
+            logger: options.logger ?? createMinimalLogger(),
+            reconnect: options.reconnect ?? true,
+            maxReconnectAttempts: options.maxReconnectAttempts ?? 10,
+            reconnectDelayMs: options.reconnectDelayMs ?? 1000,
+            maxReconnectDelayMs: options.maxReconnectDelayMs ?? 30000,
+            onSnapshot: options.onSnapshot,
+            onHydration: options.onHydration,
+            onPresence: options.onPresence,
+            onBroadcast: options.onBroadcast,
+            onEvent: options.onEvent,
+            onOpen: options.onOpen,
+            onClose: options.onClose,
+            onError: options.onError,
+        };
+    }
+    /**
+     * 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() {
+        return this.#state;
+    }
+    /**
+     * Whether the client is currently connected and receiving events.
+     */
+    get isConnected() {
+        return this.#state === 'connected' && this.#eventSource?.readyState === 1;
+    }
+    /**
+     * 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() {
+        if (this.#state !== 'closed') {
+            return;
+        }
+        this.#intentionallyClosed = false;
+        this.#reconnectAttempts = 0;
+        if (this.#reconnectTimer !== null) {
+            clearTimeout(this.#reconnectTimer);
+            this.#reconnectTimer = null;
+        }
+        this.#connectInternal();
+    }
+    /**
+     * Close the SSE connection and stop receiving events.
+     *
+     * After calling `close()`, you can call `connect()` again to reconnect.
+     */
+    close() {
+        this.#intentionallyClosed = true;
+        if (this.#reconnectTimer !== null) {
+            clearTimeout(this.#reconnectTimer);
+            this.#reconnectTimer = null;
+        }
+        if (this.#eventSource) {
+            this.#eventSource.close();
+            this.#eventSource = null;
+        }
+        this.#state = 'closed';
+        this.#options.onClose?.();
+    }
+    #setState(state) {
+        this.#state = state;
+    }
+    #handleEvent(eventName, typeOverride) {
+        this.#eventSource.addEventListener(eventName, (event) => {
+            const data = getSSEData(event);
+            if (!data)
+                return;
+            try {
+                const parsed = JSON.parse(data);
+                const payload = typeOverride ? { type: typeOverride, ...parsed } : parsed;
+                const result = ObserverSseMessageSchema.safeParse(payload);
+                if (result.success) {
+                    const semanticEvent = typeOverride || result.data.type;
+                    const sseEvent = { event: semanticEvent, data: result.data };
+                    this.#options.onEvent?.(sseEvent);
+                    if (result.data.type === 'snapshot') {
+                        this.#options.onSnapshot?.(result.data);
+                    }
+                    else if (result.data.type === 'hydration') {
+                        this.#options.onHydration?.(result.data);
+                    }
+                    else if (result.data.type === 'presence') {
+                        this.#options.onPresence?.(result.data);
+                    }
+                    else if (result.data.type === 'broadcast') {
+                        this.#options.onBroadcast?.(result.data);
+                    }
+                }
+                else {
+                    const parseError = new CoderSSEError({
+                        message: `Invalid SSE ${eventName} event format`,
+                        code: 'parse_error',
+                        sessionId: this.#options.sessionId,
+                    });
+                    this.#options.onError?.(parseError);
+                }
+            }
+            catch (err) {
+                const parseError = new CoderSSEError({
+                    message: `Failed to parse SSE ${eventName} event: ${err instanceof Error ? err.message : String(err)}`,
+                    code: 'parse_error',
+                    sessionId: this.#options.sessionId,
+                });
+                this.#options.onError?.(parseError);
+            }
+        });
+    }
+    async #connectInternal() {
+        if (this.#intentionallyClosed) {
+            return;
+        }
+        this.#setState(this.#reconnectAttempts > 0 ? 'reconnecting' : 'connecting');
+        let url;
+        try {
+            url = await buildSSEUrl(this.#options.sessionId, this.#options);
+        }
+        catch (err) {
+            this.#setState('closed');
+            this.#options.onError?.(err);
+            return;
+        }
+        if (this.#intentionallyClosed || this.#state === 'closed') {
+            return;
+        }
+        // Workaround for bun-types EventSource constructor typing issue.
+        // The type definitions don't match the runtime signature, so we use
+        // a double type assertion to construct EventSource with a URL parameter.
+        try {
+            const EventSourceCtor = EventSource;
+            this.#eventSource = new EventSourceCtor(url);
+        }
+        catch (err) {
+            this.#setState('closed');
+            this.#options.onError?.(new CoderSSEError({
+                message: `Failed to create EventSource: ${err instanceof Error ? err.message : String(err)}`,
+                code: 'connection_failed',
+                sessionId: this.#options.sessionId,
+            }));
+            this.#scheduleReconnect();
+            return;
+        }
+        this.#eventSource.onerror = () => {
+            // Notify caller of transient error before reconnecting
+            this.#options.onError?.(new Error('EventSource transient error'));
+            if (this.#eventSource) {
+                this.#eventSource.close();
+                this.#eventSource = null;
+            }
+            if (this.#intentionallyClosed) {
+                return;
+            }
+            this.#scheduleReconnect();
+        };
+        this.#eventSource.onopen = () => {
+            this.#reconnectAttempts = 0;
+            this.#setState('connected');
+            this.#options.logger.debug('SSE connection established for session %s', this.#options.sessionId);
+            this.#options.onOpen?.();
+        };
+        this.#handleEvent('snapshot', 'snapshot');
+        this.#handleEvent('hydration', 'hydration');
+        this.#handleEvent('presence', 'presence');
+        this.#handleEvent('broadcast', 'broadcast');
+        this.#handleEvent('message');
+    }
+    #scheduleReconnect() {
+        if (this.#intentionallyClosed || !this.#options.reconnect) {
+            this.#setState('closed');
+            return;
+        }
+        if (this.#reconnectAttempts >= this.#options.maxReconnectAttempts) {
+            this.#setState('closed');
+            this.#options.onError?.(new CoderSSEError({
+                message: `Exceeded maximum reconnection attempts (${this.#options.maxReconnectAttempts})`,
+                code: 'max_reconnects_exceeded',
+                sessionId: this.#options.sessionId,
+            }));
+            return;
+        }
+        const baseDelay = this.#options.reconnectDelayMs * 2 ** this.#reconnectAttempts;
+        const jitter = 0.5 + Math.random() * 0.5;
+        const delay = Math.min(Math.floor(baseDelay * jitter), this.#options.maxReconnectDelayMs);
+        this.#reconnectAttempts++;
+        this.#setState('reconnecting');
+        this.#options.logger.debug('SSE connection lost, reconnecting in %dms (attempt %d)', delay, this.#reconnectAttempts);
+        this.#reconnectTimer = setTimeout(() => {
+            this.#reconnectTimer = null;
+            this.#connectInternal();
+        }, delay);
+    }
+}
+/**
+ * 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 async function* streamCoderSessionSSE(options) {
+    const logger = options.logger ?? createMinimalLogger();
+    const signal = options.signal;
+    const reconnect = options.reconnect ?? true;
+    const maxReconnectAttempts = options.maxReconnectAttempts ?? 10;
+    const reconnectDelayMs = options.reconnectDelayMs ?? 1000;
+    const maxReconnectDelayMs = options.maxReconnectDelayMs ?? 30000;
+    if (signal?.aborted) {
+        return;
+    }
+    let eventSource = null;
+    let reconnectAttempts = 0;
+    const buffer = [];
+    const MAX_BUFFER = 1000;
+    let resolve = null;
+    let done = false;
+    let terminalError = null;
+    const wake = () => {
+        if (resolve) {
+            resolve();
+            resolve = null;
+        }
+    };
+    const cleanup = () => {
+        if (eventSource) {
+            eventSource.close();
+            eventSource = null;
+        }
+    };
+    const handleSSEEvent = (eventName, typeOverride) => {
+        eventSource.addEventListener(eventName, (event) => {
+            const data = getSSEData(event);
+            if (!data)
+                return;
+            try {
+                const parsed = JSON.parse(data);
+                const payload = typeOverride ? { type: typeOverride, ...parsed } : parsed;
+                const result = ObserverSseMessageSchema.safeParse(payload);
+                if (result.success) {
+                    if (buffer.length >= MAX_BUFFER) {
+                        buffer.shift();
+                        logger.debug('SSE buffer full, dropped oldest event');
+                    }
+                    const semanticEvent = typeOverride || result.data.type;
+                    buffer.push({ event: semanticEvent, data: result.data });
+                    wake();
+                }
+                else {
+                    terminalError = new CoderSSEError({
+                        message: `Invalid SSE ${eventName} event format`,
+                        code: 'parse_error',
+                        sessionId: options.sessionId,
+                    });
+                    done = true;
+                    wake();
+                    return;
+                }
+            }
+            catch (err) {
+                terminalError = new CoderSSEError({
+                    message: `Failed to parse SSE ${eventName} event: ${err instanceof Error ? err.message : String(err)}`,
+                    code: 'parse_error',
+                    sessionId: options.sessionId,
+                });
+                done = true;
+                wake();
+                return;
+            }
+        });
+    };
+    const connect = async () => {
+        if (done || signal?.aborted) {
+            return;
+        }
+        let url;
+        try {
+            url = await buildSSEUrl(options.sessionId, {
+                ...options,
+                logger,
+            });
+        }
+        catch (err) {
+            terminalError = err;
+            done = true;
+            wake();
+            return;
+        }
+        if (signal?.aborted) {
+            done = true;
+            wake();
+            return;
+        }
+        // Workaround for bun-types EventSource constructor typing issue (see above).
+        try {
+            const EventSourceCtor = EventSource;
+            eventSource = new EventSourceCtor(url);
+        }
+        catch (err) {
+            terminalError = new CoderSSEError({
+                message: `Failed to create EventSource: ${err instanceof Error ? err.message : String(err)}`,
+                code: 'connection_failed',
+                sessionId: options.sessionId,
+            });
+            done = true;
+            wake();
+            return;
+        }
+        if (signal?.aborted) {
+            cleanup();
+            done = true;
+            wake();
+            return;
+        }
+        eventSource.onerror = () => {
+            cleanup();
+            if (signal?.aborted) {
+                done = true;
+                wake();
+                return;
+            }
+            if (reconnect && reconnectAttempts < maxReconnectAttempts) {
+                const baseDelay = reconnectDelayMs * 2 ** reconnectAttempts;
+                const jitter = 0.5 + Math.random() * 0.5;
+                const delay = Math.min(Math.floor(baseDelay * jitter), maxReconnectDelayMs);
+                reconnectAttempts++;
+                logger.debug('SSE connection lost, reconnecting in %dms (attempt %d)', delay, reconnectAttempts);
+                setTimeout(() => {
+                    connect();
+                }, delay);
+            }
+            else if (reconnect) {
+                terminalError = new CoderSSEError({
+                    message: `Exceeded maximum reconnection attempts (${maxReconnectAttempts})`,
+                    code: 'max_reconnects_exceeded',
+                    sessionId: options.sessionId,
+                });
+                done = true;
+                wake();
+            }
+            else {
+                done = true;
+                wake();
+            }
+        };
+        eventSource.onopen = () => {
+            reconnectAttempts = 0;
+            logger.debug('SSE connection established for session %s', options.sessionId);
+        };
+        handleSSEEvent('snapshot', 'snapshot');
+        handleSSEEvent('hydration', 'hydration');
+        handleSSEEvent('presence', 'presence');
+        handleSSEEvent('broadcast', 'broadcast');
+        handleSSEEvent('message');
+    };
+    const onAbort = () => {
+        done = true;
+        cleanup();
+        wake();
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    await connect();
+    try {
+        while (!done) {
+            while (buffer.length > 0) {
+                yield buffer.shift();
+            }
+            if (done) {
+                break;
+            }
+            await new Promise((r) => {
+                resolve = r;
+            });
+        }
+        while (buffer.length > 0) {
+            yield buffer.shift();
+        }
+        if (terminalError) {
+            throw terminalError;
+        }
+    }
+    finally {
+        signal?.removeEventListener('abort', onAbort);
+        cleanup();
+    }
+}
+//# sourceMappingURL=sse.js.map