@agentuity/core 2.0.9 → 2.0.11

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

@@ -0,0 +1,346 @@
+/**
+ * WebSocket client for the Coder Hub real-time communication.
+ *
+ * Provides bidirectional communication between clients and the Coder Hub server,
+ * supporting multiple connection roles (lead, observer, controller) with
+ * automatic reconnection, heartbeat, and message queuing.
+ *
+ * @module coder/websocket
+ *
+ * @example Class-based API with callbacks
+ * ```typescript
+ * import { CoderHubWebSocketClient } from '@agentuity/core/coder';
+ *
+ * const client = new CoderHubWebSocketClient({
+ *   apiKey: 'your-api-key',
+ *   sessionId: 'session-123',
+ *   role: 'observer',
+ *   onInit: (init) => {
+ *     console.log('Connected to session:', init.sessionId);
+ *     console.log('Available agents:', init.agents);
+ *   },
+ *   onMessage: (msg) => {
+ *     console.log('Received:', msg);
+ *   },
+ *   onStateChange: (state) => {
+ *     console.log('Connection state:', state);
+ *   },
+ * });
+ *
+ * client.connect();
+ *
+ * // Send a message
+ * client.send({
+ *   type: 'ping',
+ *   timestamp: Date.now(),
+ * });
+ *
+ * // Close when done
+ * client.close();
+ * ```
+ *
+ * @example Async iterator API
+ * ```typescript
+ * import { subscribeToCoderHub } from '@agentuity/core/coder';
+ *
+ * for await (const message of subscribeToCoderHub({
+ *   sessionId: 'session-123',
+ *   role: 'observer',
+ * })) {
+ *   if (message.type === 'broadcast') {
+ *     console.log('Event:', message.event, message.data);
+ *   }
+ * }
+ * ```
+ */
+import { z } from 'zod/v4';
+import type { Logger } from '../../logger.ts';
+import type { ClientMessage, CoderHubInitMessage, CoderHubResponse, ServerMessage } from './protocol.ts';
+/**
+ * Connection state for the WebSocket client.
+ *
+ * - `'connecting'` - Initial WebSocket connection in progress
+ * - `'authenticating'` - WebSocket connected, sending auth message
+ * - `'connected'` - Authenticated and ready to send/receive messages
+ * - `'reconnecting'` - Reconnecting after disconnect
+ * - `'closed'` - Connection closed (manually or after max retries)
+ */
+export type CoderHubWebSocketState = 'connecting' | 'authenticating' | 'connected' | 'reconnecting' | 'closed';
+/**
+ * Options for the WebSocket client.
+ */
+export declare const CoderHubWebSocketOptionsSchema: z.ZodObject<{
+    apiKey: z.ZodOptional<z.ZodString>;
+    orgId: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodEnum<{
+        lead: "lead";
+        controller: "controller";
+        observer: "observer";
+    }>>;
+    agent: z.ZodOptional<z.ZodString>;
+    parentSessionId: z.ZodOptional<z.ZodString>;
+    task: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    origin: z.ZodOptional<z.ZodEnum<{
+        tui: "tui";
+        web: "web";
+        desktop: "desktop";
+        sdk: "sdk";
+    }>>;
+    driverMode: z.ZodOptional<z.ZodEnum<{
+        rpc: "rpc";
+    }>>;
+    driverInstanceId: z.ZodOptional<z.ZodString>;
+    driverVersion: z.ZodOptional<z.ZodString>;
+    logger: z.ZodOptional<z.ZodCustom<Logger, Logger>>;
+    autoReconnect: z.ZodOptional<z.ZodBoolean>;
+    maxReconnectAttempts: z.ZodOptional<z.ZodNumber>;
+    reconnectDelayMs: z.ZodOptional<z.ZodNumber>;
+    maxReconnectDelayMs: z.ZodOptional<z.ZodNumber>;
+    heartbeatIntervalMs: z.ZodOptional<z.ZodNumber>;
+    heartbeatTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    maxMessageQueueSize: z.ZodOptional<z.ZodNumber>;
+    onOpen: z.ZodOptional<z.ZodCustom<() => void, () => void>>;
+    onClose: z.ZodOptional<z.ZodCustom<(code: number, reason: string) => void, (code: number, reason: string) => void>>;
+    onError: z.ZodOptional<z.ZodCustom<(error: Error) => void, (error: Error) => void>>;
+    onMessage: z.ZodOptional<z.ZodCustom<(message: ServerMessage) => void, (message: ServerMessage) => void>>;
+    onInit: z.ZodOptional<z.ZodCustom<(message: CoderHubInitMessage) => void, (message: CoderHubInitMessage) => void>>;
+    onStateChange: z.ZodOptional<z.ZodCustom<(state: CoderHubWebSocketState) => void, (state: CoderHubWebSocketState) => void>>;
+}, z.core.$strip>;
+export type CoderHubWebSocketOptions = z.infer<typeof CoderHubWebSocketOptionsSchema>;
+/**
+ * Error type for WebSocket operations.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.sendAndWait({ type: 'tool', name: 'read', ... });
+ * } catch (err) {
+ *   if (err instanceof CoderHubWebSocketError) {
+ *     if (err.code === 'response_timeout') {
+ *       console.log('Server did not respond in time');
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare const CoderHubWebSocketError: {
+    new (args?: ({
+        code: "connection_failed" | "auth_failed" | "connection_error" | "max_reconnects_exceeded" | "send_while_disconnected" | "response_timeout" | "invalid_response";
+        sessionId?: string;
+    } & {
+        message?: string;
+        cause?: unknown;
+    }) | undefined): import("../../error.ts").RichError & {
+        readonly _tag: "CoderHubWebSocketError";
+    } & Readonly<{
+        code: "connection_failed" | "auth_failed" | "connection_error" | "max_reconnects_exceeded" | "send_while_disconnected" | "response_timeout" | "invalid_response";
+        sessionId?: string;
+    }>;
+    readonly defaultMessage?: string;
+};
+/**
+ * WebSocket client for real-time Coder Hub communication.
+ *
+ * Supports multiple connection roles and provides automatic reconnection,
+ * heartbeat management, and message queuing for resilient connections.
+ *
+ * @example Observer connection
+ * ```typescript
+ * const client = new CoderHubWebSocketClient({
+ *   sessionId: 'session-123',
+ *   role: 'observer',
+ *   onMessage: (msg) => {
+ *     if (msg.type === 'broadcast') {
+ *       console.log('Event:', msg.event);
+ *     }
+ *   },
+ * });
+ * client.connect();
+ * ```
+ *
+ * @example Controller connection with sendAndWait
+ * ```typescript
+ * const client = new CoderHubWebSocketClient({
+ *   sessionId: 'session-123',
+ *   role: 'controller',
+ * });
+ * client.connect();
+ *
+ * // Wait for connection
+ * await new Promise(resolve => {
+ *   client.onInit = () => resolve(undefined);
+ * });
+ *
+ * // Send a request and wait for response
+ * const response = await client.sendAndWait({
+ *   type: 'event',
+ *   event: 'steer',
+ *   data: { direction: 'continue' },
+ * });
+ * console.log('Response:', response);
+ * ```
+ *
+ * @example Sub-agent connection
+ * ```typescript
+ * const client = new CoderHubWebSocketClient({
+ *   role: 'observer', // Sub-agents connect as observers to parent
+ *   agent: 'scout',
+ *   parentSessionId: 'parent-session-456',
+ * });
+ * client.connect();
+ * ```
+ */
+export declare class CoderHubWebSocketClient {
+    #private;
+    constructor(options?: CoderHubWebSocketOptions);
+    /**
+     * The current connection state.
+     *
+     * @see CoderHubWebSocketState for state descriptions
+     */
+    get state(): CoderHubWebSocketState;
+    /**
+     * The session ID for this connection.
+     *
+     * Returns the server-assigned session ID (from init message) if available,
+     * otherwise returns the session ID passed in options.
+     */
+    get sessionId(): string | undefined;
+    /**
+     * The init message received from the server after authentication.
+     *
+     * Contains session configuration, available agents, tools, and other metadata.
+     * Only available after successful authentication.
+     */
+    get initMessage(): CoderHubInitMessage | null;
+    /**
+     * Whether the client is currently connected and authenticated.
+     *
+     * Returns `true` only when state is 'connected' AND WebSocket is open.
+     */
+    get isConnected(): boolean;
+    /**
+     * Establish the WebSocket connection and authenticate.
+     *
+     * If already connected or connecting, this is a no-op.
+     * Automatically reconnects on disconnection unless `close()` was called.
+     *
+     * The connection goes through these states:
+     * 1. `'connecting'` - WebSocket opening
+     * 2. `'authenticating'` - Sending auth message
+     * 3. `'connected'` - Received init message
+     */
+    connect(): void;
+    /**
+     * Close the WebSocket connection.
+     *
+     * After calling `close()`, you can call `connect()` again to reconnect.
+     * Any pending requests will be rejected with an error.
+     *
+     * @param code - Optional close code (default: 1000 for normal close)
+     * @param reason - Optional close reason string
+     */
+    close(code?: number, reason?: string): void;
+    /**
+     * Send a message to the server.
+     *
+     * If not connected, the message will be queued and sent when reconnected
+     * (up to `maxMessageQueueSize` messages). If the queue is full, an error
+     * is emitted via `onError`.
+     *
+     * @param message - The message to send
+     *
+     * @example
+     * ```typescript
+     * client.send({
+     *   type: 'ping',
+     *   timestamp: Date.now(),
+     * });
+     *
+     * client.send({
+     *   type: 'session_entry',
+     *   path: 'entries.jsonl',
+     *   line: JSON.stringify({ type: 'message', content: 'Hello' }),
+     * });
+     * ```
+     */
+    send(message: ClientMessage): void;
+    /**
+     * Send a message and wait for a response.
+     *
+     * Automatically adds a unique `id` to the message and waits for a
+     * response with matching `id`. Useful for request/response patterns
+     * like tool calls or RPC commands.
+     *
+     * @param message - The message to send (without `id` field)
+     * @param timeoutMs - Timeout in milliseconds (default: 30000)
+     * @returns Promise that resolves with the response
+     * @throws {CoderHubWebSocketError} If timeout exceeded or connection closed
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const response = await client.sendAndWait({
+     *     type: 'tool',
+     *     name: 'read_file',
+     *     toolCallId: 'call-123',
+     *     params: { path: '/src/index.ts' },
+     *   });
+     *   console.log('Tool result:', response.actions);
+     * } catch (err) {
+     *   if (err instanceof CoderHubWebSocketError && err.code === 'response_timeout') {
+     *     console.log('Tool call timed out');
+     *   }
+     * }
+     * ```
+     */
+    sendAndWait(message: Omit<ClientMessage, 'id'>, timeoutMs?: number): Promise<CoderHubResponse>;
+}
+/**
+ * Subscribe to a Coder Hub session via WebSocket using async iteration.
+ *
+ * Returns an async iterator that yields server messages as they arrive.
+ * The connection is automatically managed (auth, reconnection, cleanup).
+ *
+ * @param options - Configuration for the WebSocket connection
+ * @yields Server messages as they arrive
+ * @throws {CoderHubWebSocketError} If connection fails or max reconnection attempts exceeded
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { subscribeToCoderHub } from '@agentuity/core/coder';
+ *
+ * for await (const message of subscribeToCoderHub({
+ *   sessionId: 'session-123',
+ *   role: 'observer',
+ * })) {
+ *   switch (message.type) {
+ *     case 'broadcast':
+ *       console.log('Event:', message.event);
+ *       break;
+ *     case 'presence':
+ *       console.log('Participant:', message.participant);
+ *       break;
+ *   }
+ * }
+ * ```
+ *
+ * @example With error handling
+ * ```typescript
+ * try {
+ *   for await (const message of subscribeToCoderHub({ sessionId: 'session-123' })) {
+ *     console.log(message);
+ *   }
+ * } catch (err) {
+ *   if (err instanceof CoderHubWebSocketError) {
+ *     console.log('WebSocket error:', err.code);
+ *   }
+ * }
+ * ```
+ */
+export declare function subscribeToCoderHub(options: CoderHubWebSocketOptions): AsyncGenerator<ServerMessage, void, unknown>;
+//# sourceMappingURL=websocket.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../../src/services/coder/websocket.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAO9C,OAAO,KAAK,EACX,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAEhB,aAAa,EACb,MAAM,eAAe,CAAC;AAIvB;;;;;;;;GAQG;AACH,MAAM,MAAM,sBAAsB,GAC/B,YAAY,GACZ,gBAAgB,GAChB,WAAW,GACX,cAAc,GACd,QAAQ,CAAC;AAEZ;;GAEG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4CAsDnB,IAAI,QAAJ,IAAI;8CAGX,MAAM,UAAU,MAAM,KAAK,IAAI,SAA/B,MAAM,UAAU,MAAM,KAAK,IAAI;+CAIrB,KAAK,KAAK,IAAI,UAAd,KAAK,KAAK,IAAI;mDAGrB,aAAa,KAAK,IAAI,YAAtB,aAAa,KAAK,IAAI;gDAKtB,mBAAmB,KAAK,IAAI,YAA5B,mBAAmB,KAAK,IAAI;qDAK9B,sBAAsB,KAAK,IAAI,UAA/B,sBAAsB,KAAK,IAAI;iBAG/C,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB;;cAE/B,mBAAmB,GACnB,aAAa,GACb,kBAAkB,GAClB,yBAAyB,GACzB,yBAAyB,GACzB,kBAAkB,GAClB,kBAAkB;oBACT,MAAM;;;;;;;cAPf,mBAAmB,GACnB,aAAa,GACb,kBAAkB,GAClB,yBAAyB,GACzB,yBAAyB,GACzB,kBAAkB,GAClB,kBAAkB;oBACT,MAAM;;;CACf,CAAC;AAQL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBAAa,uBAAuB;;gBA6CvB,OAAO,GAAE,wBAA6B;IAmClD;;;;OAIG;IACH,IAAI,KAAK,IAAI,sBAAsB,CAElC;IAED;;;;;OAKG;IACH,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAElC;IAED;;;;;OAKG;IACH,IAAI,WAAW,IAAI,mBAAmB,GAAG,IAAI,CAE5C;IAED;;;;OAIG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;;;;;;;;OAUG;IACH,OAAO,IAAI,IAAI;IAYf;;;;;;;;OAQG;IACH,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAgB3C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,IAAI,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAkBlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,WAAW,CAChB,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,EAClC,SAAS,SAAQ,GACf,OAAO,CAAC,gBAAgB,CAAC;CA2U5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAuB,mBAAmB,CACzC,OAAO,EAAE,wBAAwB,GAC/B,cAAc,CAAC,aAAa,EAAE,IAAI,EAAE,OAAO,CAAC,CAkE9C"}