@illalabs/sdk 0.4.0-canary.361ed2fa → 0.4.0-canary.3f75ecce

package/dist/src/telemetry/TelemetryClient.js

@@ -0,0 +1,225 @@
+/**
+ * Error thrown when the telemetry stream fails to connect or encounters an error
+ */
+export class TelemetryStreamFailed extends Error {
+    /** The request ID that was being streamed */
+    requestId;
+    /**
+     * Creates a new TelemetryStreamFailed error
+     * @param message - Description of what went wrong
+     * @param requestId - The request ID that was being streamed
+     */
+    constructor(message, requestId) {
+        super(`Telemetry stream failed: ${message}`);
+        this.name = "TelemetryStreamFailed";
+        this.requestId = requestId;
+    }
+}
+/**
+ * Browser-only client for consuming telemetry SSE streams.
+ * This client connects to the telemetry endpoint and emits events as they arrive.
+ *
+ * **Note**: This client requires the native `EventSource` API, which is only available
+ * in browser environments. For Node.js usage, you must provide a polyfill such as
+ * the `eventsource` package before instantiating this client.
+ *
+ * @example
+ * ```typescript
+ * const client = new TelemetryClient({
+ *   baseUrl: 'https://api.example.com/v1/chat',
+ *   onEvent: (event) => console.log('Event:', event.type),
+ *   onComplete: () => console.log('Stream complete'),
+ *   onError: (error) => console.error('Error:', error),
+ * });
+ *
+ * client.connect('request-uuid');
+ *
+ * // Later, disconnect
+ * client.disconnect();
+ * ```
+ *
+ * @example Node.js usage with polyfill
+ * ```typescript
+ * // Install: pnpm add eventsource
+ * // At the top of your entry file:
+ * import EventSource from 'eventsource';
+ * globalThis.EventSource = EventSource as unknown as typeof globalThis.EventSource;
+ *
+ * // Then use TelemetryClient normally
+ * const client = new TelemetryClient({ ... });
+ * ```
+ */
+export class TelemetryClient {
+    eventSource = null;
+    config;
+    currentRequestId = null;
+    _isConnected = false;
+    _isComplete = false;
+    /**
+     * Creates a new TelemetryClient instance
+     * @param config - Configuration including base URL and event callbacks
+     */
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Whether the client is currently connected to a stream
+     */
+    get isConnected() {
+        return this._isConnected;
+    }
+    /**
+     * Whether the current stream has completed
+     */
+    get isComplete() {
+        return this._isComplete;
+    }
+    /**
+     * Connect to a telemetry stream for a specific request
+     * @param requestId - The request ID to subscribe to
+     * @throws {TelemetryStreamFailed} If EventSource is not available in the environment
+     */
+    connect(requestId) {
+        // Avoid reconnecting to the same request
+        if (this.currentRequestId === requestId && this._isConnected) {
+            return;
+        }
+        // Runtime check for EventSource availability
+        if (typeof EventSource === "undefined") {
+            const error = new TelemetryStreamFailed("EventSource is not available. This client requires a browser environment or an EventSource polyfill (e.g., 'eventsource' package for Node.js).", requestId);
+            this.config.onError?.(error);
+            return;
+        }
+        this.disconnect();
+        const url = `${this.config.baseUrl}/telemetry/${requestId}`;
+        this.currentRequestId = requestId;
+        this._isComplete = false;
+        try {
+            const eventSource = new EventSource(url);
+            this.eventSource = eventSource;
+            eventSource.onopen = () => {
+                this._isConnected = true;
+            };
+            eventSource.onmessage = (event) => {
+                try {
+                    const data = JSON.parse(event.data);
+                    this.config.onEvent?.(data);
+                    if (TelemetryClient.isTerminalEvent(data.type)) {
+                        this._isComplete = true;
+                        this.config.onComplete?.();
+                        this.closeEventSource();
+                    }
+                }
+                catch {
+                    // Ignore malformed JSON - SSE can send comments or other data
+                }
+            };
+            eventSource.onerror = () => {
+                // Check if this is a normal close after stream_end
+                if (this.eventSource === null) {
+                    return;
+                }
+                const error = new TelemetryStreamFailed("Connection error", requestId);
+                this._isConnected = false;
+                this.config.onError?.(error);
+                this.closeEventSource();
+            };
+        }
+        catch (error) {
+            const err = new TelemetryStreamFailed(error instanceof Error ? error.message : String(error), requestId);
+            this.config.onError?.(err);
+        }
+    }
+    /**
+     * Disconnect from the current stream
+     */
+    disconnect() {
+        this.closeEventSource();
+        this.currentRequestId = null;
+    }
+    /**
+     * Close the EventSource without clearing the requestId
+     * (used when stream ends normally)
+     */
+    closeEventSource() {
+        if (this.eventSource) {
+            this.eventSource.close();
+            this.eventSource = null;
+        }
+        this._isConnected = false;
+    }
+    /**
+     * Derive orchestrator phase from a telemetry event.
+     * This static method provides a consistent mapping from events to phases.
+     *
+     * @param event - The telemetry event to derive phase from
+     * @returns The current orchestrator phase
+     *
+     * @example
+     * ```typescript
+     * const phase = TelemetryClient.getPhaseFromEvent(event);
+     * console.log('Current phase:', phase); // e.g., "thinking", "executing_tools"
+     * ```
+     */
+    static getPhaseFromEvent(event) {
+        if (!event)
+            return "idle";
+        switch (event.type) {
+            case "connected":
+            case "iteration_start":
+            case "llm_start":
+                return "thinking";
+            case "llm_end":
+            case "tool_call_batch":
+                return "calling_tools";
+            case "tool_result":
+                return "executing_tools";
+            case "iteration_end":
+            case "scratchpad_reset":
+                return "processing_results";
+            case "finish":
+            case "stream_end":
+                return "complete";
+            case "error":
+                return "error";
+            default:
+                return "thinking";
+        }
+    }
+    /**
+     * Get a human-readable label for an orchestrator phase
+     * @param phase - The phase to get label for
+     * @returns Human-readable label
+     */
+    static getPhaseLabel(phase) {
+        switch (phase) {
+            case "idle":
+                return "Idle";
+            case "thinking":
+                return "Thinking...";
+            case "calling_tools":
+                return "Calling tools...";
+            case "executing_tools":
+                return "Executing tools...";
+            case "processing_results":
+                return "Processing results...";
+            case "complete":
+                return "Complete";
+            case "error":
+                return "Error";
+            case "streaming":
+                return "Streaming...";
+            default:
+                return "Unknown";
+        }
+    }
+    /**
+     * Check if an event type indicates the stream should end
+     * @param type - The event type to check
+     * @returns True if the event indicates stream completion
+     */
+    static isTerminalEvent(type) {
+        return type === "stream_end" || type === "finish" || type === "error";
+    }
+}
+//# sourceMappingURL=TelemetryClient.js.map

package/dist/src/telemetry/TelemetryClient.js.map

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

package/dist/src/telemetry/index.d.ts

@@ -0,0 +1,2 @@
+export { TelemetryClient, TelemetryStreamFailed, type TelemetryClientConfig, type TelemetryStreamState, } from "./TelemetryClient.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/telemetry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,eAAe,EACf,qBAAqB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC5B,MAAM,sBAAsB,CAAC"}

package/dist/src/telemetry/index.js

@@ -0,0 +1,2 @@
+export { TelemetryClient, TelemetryStreamFailed, } from "./TelemetryClient.js";
+//# sourceMappingURL=index.js.map

package/dist/src/telemetry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,eAAe,EACf,qBAAqB,GAGxB,MAAM,sBAAsB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illalabs/sdk",
-  "version": "0.4.0-canary.361ed2fa",
+  "version": "0.4.0-canary.3f75ecce",
   "private": false,
   "description": "TypeScript SDK for interacting with Illa's Core API",
   "license": "MIT",
@@ -23,10 +23,8 @@
     "axios": "1.12.2",
     "uuid": "13.0.0",
     "viem": "2.37.13",
-    "@illalabs/interfaces": "0.3.0-canary.361ed2fa"
-  },
-  "devDependencies": {
-    "zod": "4.1.12"
+    "zod": "3.25.76",
+    "@illalabs/interfaces": "0.3.0-canary.3f75ecce"
   },
   "publishConfig": {
     "access": "public"