@illalabs/sdk 0.4.0-canary.56299752 → 0.4.0-canary.842eb5db

package/dist/src/streaming/errors/index.d.ts

@@ -0,0 +1,5 @@
+export { SSEParse } from "./SSEParse.js";
+export { StreamingHttpError } from "./StreamingHttpError.js";
+export { StreamingResponseBodyNull } from "./StreamingResponseBodyNull.js";
+export { StreamingServerError } from "./StreamingServerError.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/streaming/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/streaming/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/src/streaming/errors/index.js

@@ -0,0 +1,5 @@
+export { SSEParse } from "./SSEParse.js";
+export { StreamingHttpError } from "./StreamingHttpError.js";
+export { StreamingResponseBodyNull } from "./StreamingResponseBodyNull.js";
+export { StreamingServerError } from "./StreamingServerError.js";
+//# sourceMappingURL=index.js.map

package/dist/src/streaming/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/streaming/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

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

@@ -0,0 +1,4 @@
+export { SSEParse, StreamingHttpError, StreamingResponseBodyNull, StreamingServerError, } from "./errors/index.js";
+export { parseSSEStream } from "./parseSSE.js";
+export type { ErrorEventData, ErrorStreamEvent, ResultStreamEvent, SSEStreamEndEvent, SSEStreamEndEventData, SSEStreamEvent, StreamEventType, TelemetryStreamEvent, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/streaming/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,QAAQ,EACR,kBAAkB,EAClB,yBAAyB,EACzB,oBAAoB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EACR,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,oBAAoB,GACvB,MAAM,YAAY,CAAC"}

package/dist/src/streaming/index.js

@@ -0,0 +1,3 @@
+export { SSEParse, StreamingHttpError, StreamingResponseBodyNull, StreamingServerError, } from "./errors/index.js";
+export { parseSSEStream } from "./parseSSE.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/streaming/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,QAAQ,EACR,kBAAkB,EAClB,yBAAyB,EACzB,oBAAoB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/src/streaming/parseSSE.d.ts

@@ -0,0 +1,23 @@
+import type { SSEStreamEvent } from "@illalabs/interfaces";
+/**
+ * Async generator that parses SSE events from a ReadableStream.
+ *
+ * @param stream - The ReadableStream from a fetch response body
+ * @param signal - Optional AbortSignal to allow mid-stream cancellation
+ * @yields SSEStreamEvent objects as they are parsed from the stream
+ * @throws SSEParse if event data cannot be parsed
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController();
+ * for await (const event of parseSSEStream(response.body!, controller.signal)) {
+ *   if (event.type === 'telemetry') {
+ *     console.log('Telemetry:', event.data.type);
+ *   } else if (event.type === 'result') {
+ *     console.log('Result:', event.data.text);
+ *   }
+ * }
+ * ```
+ */
+export declare function parseSSEStream(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<SSEStreamEvent>;
+//# sourceMappingURL=parseSSE.d.ts.map

package/dist/src/streaming/parseSSE.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseSSE.d.ts","sourceRoot":"","sources":["../../../src/streaming/parseSSE.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAgH3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAuB,cAAc,CACjC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,MAAM,CAAC,EAAE,WAAW,GACrB,cAAc,CAAC,cAAc,CAAC,CAsChC"}

package/dist/src/streaming/parseSSE.js

@@ -0,0 +1,152 @@
+import { errorEventDataSchema, resultEventDataSchema, streamEndEventDataSchema, telemetryEventSchema, } from "@illalabs/interfaces";
+import { ZodError } from "zod";
+import { SSEParse } from "./errors/index.js";
+/**
+ * Parses a single SSE message into its event type and data.
+ */
+function parseSSEMessage(message) {
+    const lines = message.split("\n");
+    let eventType = "message";
+    const dataLines = [];
+    for (const line of lines) {
+        if (line.startsWith("event:")) {
+            eventType = line.slice(6).trim();
+        }
+        else if (line.startsWith("data:")) {
+            const value = line.slice(5);
+            dataLines.push(value.startsWith(" ") ? value.slice(1) : value);
+        }
+    }
+    const data = dataLines.join("\n");
+    return data ? { event: eventType, data } : null;
+}
+/**
+ * Formats a Zod validation error into a human-readable message.
+ */
+function formatZodError(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+        return `${path}:${issue.message}`;
+    })
+        .join("; ");
+}
+/**
+ * Converts a parsed SSE message into a typed SSEStreamEvent.
+ * Validates the parsed data at runtime using Zod schemas.
+ */
+function toStreamEvent(event, data) {
+    let parsed;
+    try {
+        parsed = JSON.parse(data);
+    }
+    catch (error) {
+        throw new SSEParse(`Failed to parse JSON data: ${data}`, error);
+    }
+    try {
+        switch (event) {
+            case "telemetry": {
+                const validated = telemetryEventSchema.parse(parsed);
+                return { type: "telemetry", data: validated };
+            }
+            case "result": {
+                const validated = resultEventDataSchema.parse(parsed);
+                return { type: "result", data: validated };
+            }
+            case "error": {
+                const validated = errorEventDataSchema.parse(parsed);
+                return { type: "error", data: validated };
+            }
+            case "stream_end": {
+                const validated = streamEndEventDataSchema.parse(parsed);
+                return { type: "stream_end", data: validated };
+            }
+            default: {
+                // Try to infer event type from data.type field if present
+                if (typeof parsed === "object" && parsed !== null && "type" in parsed) {
+                    const typedData = parsed;
+                    switch (typedData.type) {
+                        case "result": {
+                            const validated = resultEventDataSchema.parse(parsed);
+                            return { type: "result", data: validated };
+                        }
+                        case "error": {
+                            const validated = errorEventDataSchema.parse(parsed);
+                            return { type: "error", data: validated };
+                        }
+                        case "stream_end": {
+                            const validated = streamEndEventDataSchema.parse(parsed);
+                            return { type: "stream_end", data: validated };
+                        }
+                    }
+                }
+                // Default to telemetry for unknown event types
+                const validated = telemetryEventSchema.parse(parsed);
+                return { type: "telemetry", data: validated };
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof ZodError) {
+            throw new SSEParse(`Invalid event data for "${event}": ${formatZodError(error)}`, error);
+        }
+        throw error;
+    }
+}
+/**
+ * Async generator that parses SSE events from a ReadableStream.
+ *
+ * @param stream - The ReadableStream from a fetch response body
+ * @param signal - Optional AbortSignal to allow mid-stream cancellation
+ * @yields SSEStreamEvent objects as they are parsed from the stream
+ * @throws SSEParse if event data cannot be parsed
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController();
+ * for await (const event of parseSSEStream(response.body!, controller.signal)) {
+ *   if (event.type === 'telemetry') {
+ *     console.log('Telemetry:', event.data.type);
+ *   } else if (event.type === 'result') {
+ *     console.log('Result:', event.data.text);
+ *   }
+ * }
+ * ```
+ */
+export async function* parseSSEStream(stream, signal) {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+        while (true) {
+            if (signal?.aborted) {
+                break;
+            }
+            const { done, value } = await reader.read();
+            if (done) {
+                if (buffer.trim()) {
+                    const parsed = parseSSEMessage(buffer);
+                    if (parsed) {
+                        yield toStreamEvent(parsed.event, parsed.data);
+                    }
+                }
+                break;
+            }
+            buffer += decoder.decode(value, { stream: true });
+            const messages = buffer.split("\n\n");
+            buffer = messages.pop() ?? "";
+            for (const message of messages) {
+                if (!message.trim())
+                    continue;
+                const parsed = parseSSEMessage(message);
+                if (parsed) {
+                    yield toStreamEvent(parsed.event, parsed.data);
+                }
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+//# sourceMappingURL=parseSSE.js.map

package/dist/src/streaming/parseSSE.js.map

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

package/dist/src/streaming/types.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Streaming types for SSE chat endpoint.
+ * Re-exports types from @illalabs/interfaces for SDK consumers.
+ */
+export type { ErrorEventData, ErrorStreamEvent, ResultStreamEvent, SSEStreamEndEvent, SSEStreamEndEventData, SSEStreamEvent, StreamEventType, TelemetryStreamEvent, } from "@illalabs/interfaces";
+//# sourceMappingURL=types.d.ts.map

package/dist/src/streaming/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/streaming/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EACR,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,oBAAoB,GACvB,MAAM,sBAAsB,CAAC"}

package/dist/src/streaming/types.js

@@ -0,0 +1,6 @@
+/**
+ * Streaming types for SSE chat endpoint.
+ * Re-exports types from @illalabs/interfaces for SDK consumers.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/streaming/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/streaming/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

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

@@ -0,0 +1,140 @@
+import type { OrchestratorPhase, TelemetryEvent, TelemetryEventType } from "@illalabs/interfaces";
+/**
+ * Configuration for the TelemetryClient
+ */
+export type TelemetryClientConfig = {
+    /** Base URL of the API (e.g., "https://api.example.com/v1/chat") */
+    baseUrl: string;
+    /** Called when an event is received from the stream */
+    onEvent?: (event: TelemetryEvent) => void;
+    /** Called when the stream completes successfully */
+    onComplete?: () => void;
+    /** Called when an error occurs */
+    onError?: (error: Error) => void;
+};
+/**
+ * State of the telemetry stream
+ */
+export type TelemetryStreamState = {
+    /** Whether the stream is currently connected */
+    isConnected: boolean;
+    /** Whether the stream has completed */
+    isComplete: boolean;
+    /** All events received from the stream */
+    events: TelemetryEvent[];
+    /** The last event received */
+    lastEvent: TelemetryEvent | null;
+    /** Any error that occurred */
+    error: Error | null;
+    /** Current phase of orchestration */
+    currentPhase: OrchestratorPhase;
+};
+/**
+ * Error thrown when the telemetry stream fails to connect or encounters an error
+ */
+export declare class TelemetryStreamFailed extends Error {
+    /** The request ID that was being streamed */
+    readonly requestId?: string;
+    /**
+     * Creates a new TelemetryStreamFailed error
+     * @param message - Description of what went wrong
+     * @param requestId - The request ID that was being streamed
+     */
+    constructor(message: string, requestId?: string);
+}
+/**
+ * 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 declare class TelemetryClient {
+    private eventSource;
+    private config;
+    private currentRequestId;
+    private _isConnected;
+    private _isComplete;
+    /**
+     * Creates a new TelemetryClient instance
+     * @param config - Configuration including base URL and event callbacks
+     */
+    constructor(config: TelemetryClientConfig);
+    /**
+     * Whether the client is currently connected to a stream
+     */
+    get isConnected(): boolean;
+    /**
+     * Whether the current stream has completed
+     */
+    get isComplete(): boolean;
+    /**
+     * 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: string): void;
+    /**
+     * Disconnect from the current stream
+     */
+    disconnect(): void;
+    /**
+     * Close the EventSource without clearing the requestId
+     * (used when stream ends normally)
+     */
+    private closeEventSource;
+    /**
+     * 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: TelemetryEvent | null): OrchestratorPhase;
+    /**
+     * Get a human-readable label for an orchestrator phase
+     * @param phase - The phase to get label for
+     * @returns Human-readable label
+     */
+    static getPhaseLabel(phase: OrchestratorPhase): string;
+    /**
+     * 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: TelemetryEventType): boolean;
+}
+//# sourceMappingURL=TelemetryClient.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TelemetryClient.d.ts","sourceRoot":"","sources":["../../../src/telemetry/TelemetryClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAElG;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAChC,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IAC1C,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB,kCAAkC;IAClC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACpC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAC/B,gDAAgD;IAChD,WAAW,EAAE,OAAO,CAAC;IACrB,uCAAuC;IACvC,UAAU,EAAE,OAAO,CAAC;IACpB,0CAA0C;IAC1C,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,8BAA8B;IAC9B,SAAS,EAAE,cAAc,GAAG,IAAI,CAAC;IACjC,8BAA8B;IAC9B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,qCAAqC;IACrC,YAAY,EAAE,iBAAiB,CAAC;CACnC,CAAC;AAEF;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC5C,6CAA6C;IAC7C,SAAgB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnC;;;;OAIG;gBACS,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;CAKlD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,eAAe;IACxB,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,WAAW,CAAS;IAE5B;;;OAGG;gBACS,MAAM,EAAE,qBAAqB;IAIzC;;OAEG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;;OAIG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAiEhC;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAQxB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,GAAG,iBAAiB;IA0BzE;;;;OAIG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM;IAuBtD;;;;OAIG;IACH,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO;CAG5D"}

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":"AAkCA;;GAEG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC5C,6CAA6C;IAC7B,SAAS,CAAU;IAEnC;;;;OAIG;IACH,YAAY,OAAe,EAAE,SAAkB;QAC3C,KAAK,CAAC,4BAA4B,OAAO,EAAE,CAAC,CAAC;QAC7C,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC/B,CAAC;CACJ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,OAAO,eAAe;IAChB,WAAW,GAAuB,IAAI,CAAC;IACvC,MAAM,CAAwB;IAC9B,gBAAgB,GAAkB,IAAI,CAAC;IACvC,YAAY,GAAG,KAAK,CAAC;IACrB,WAAW,GAAG,KAAK,CAAC;IAE5B;;;OAGG;IACH,YAAY,MAA6B;QACrC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,IAAI,WAAW;QACX,OAAO,IAAI,CAAC,YAAY,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACV,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,SAAiB;QACrB,yCAAyC;QACzC,IAAI,IAAI,CAAC,gBAAgB,KAAK,SAAS,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YAC3D,OAAO;QACX,CAAC;QAED,6CAA6C;QAC7C,IAAI,OAAO,WAAW,KAAK,WAAW,EAAE,CAAC;YACrC,MAAM,KAAK,GAAG,IAAI,qBAAqB,CACnC,gJAAgJ,EAChJ,SAAS,CACZ,CAAC;YACF,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;YAC7B,OAAO;QACX,CAAC;QAED,IAAI,CAAC,UAAU,EAAE,CAAC;QAElB,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,cAAc,SAAS,EAAE,CAAC;QAC5D,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC;QAClC,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;QAEzB,IAAI,CAAC;YACD,MAAM,WAAW,GAAG,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC;YACzC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;YAE/B,WAAW,CAAC,MAAM,GAAG,GAAS,EAAE;gBAC5B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;YAC7B,CAAC,CAAC;YAEF,WAAW,CAAC,SAAS,GAAG,CAAC,KAA2B,EAAQ,EAAE;gBAC1D,IAAI,CAAC;oBACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAmB,CAAC;oBACtD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;oBAE5B,IAAI,eAAe,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;wBAC7C,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;wBACxB,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE,CAAC;wBAC3B,IAAI,CAAC,gBAAgB,EAAE,CAAC;oBAC5B,CAAC;gBACL,CAAC;gBAAC,MAAM,CAAC;oBACL,8DAA8D;gBAClE,CAAC;YACL,CAAC,CAAC;YAEF,WAAW,CAAC,OAAO,GAAG,GAAS,EAAE;gBAC7B,mDAAmD;gBACnD,IAAI,IAAI,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;oBAC5B,OAAO;gBACX,CAAC;gBAED,MAAM,KAAK,GAAG,IAAI,qBAAqB,CAAC,kBAAkB,EAAE,SAAS,CAAC,CAAC;gBACvE,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;gBAC1B,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;gBAC7B,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC5B,CAAC,CAAC;QACN,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,GAAG,GAAG,IAAI,qBAAqB,CACjC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EACtD,SAAS,CACZ,CAAC;YACF,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC;QAC/B,CAAC;IACL,CAAC;IAED;;OAEG;IACH,UAAU;QACN,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACxB,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;IACjC,CAAC;IAED;;;OAGG;IACK,gBAAgB;QACpB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACnB,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QAC5B,CAAC;QACD,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;IAC9B,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,iBAAiB,CAAC,KAA4B;QACjD,IAAI,CAAC,KAAK;YAAE,OAAO,MAAM,CAAC;QAE1B,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACjB,KAAK,WAAW,CAAC;YACjB,KAAK,iBAAiB,CAAC;YACvB,KAAK,WAAW;gBACZ,OAAO,UAAU,CAAC;YACtB,KAAK,SAAS,CAAC;YACf,KAAK,iBAAiB;gBAClB,OAAO,eAAe,CAAC;YAC3B,KAAK,aAAa;gBACd,OAAO,iBAAiB,CAAC;YAC7B,KAAK,eAAe,CAAC;YACrB,KAAK,kBAAkB;gBACnB,OAAO,oBAAoB,CAAC;YAChC,KAAK,QAAQ,CAAC;YACd,KAAK,YAAY;gBACb,OAAO,UAAU,CAAC;YACtB,KAAK,OAAO;gBACR,OAAO,OAAO,CAAC;YACnB;gBACI,OAAO,UAAU,CAAC;QAC1B,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,aAAa,CAAC,KAAwB;QACzC,QAAQ,KAAK,EAAE,CAAC;YACZ,KAAK,MAAM;gBACP,OAAO,MAAM,CAAC;YAClB,KAAK,UAAU;gBACX,OAAO,aAAa,CAAC;YACzB,KAAK,eAAe;gBAChB,OAAO,kBAAkB,CAAC;YAC9B,KAAK,iBAAiB;gBAClB,OAAO,oBAAoB,CAAC;YAChC,KAAK,oBAAoB;gBACrB,OAAO,uBAAuB,CAAC;YACnC,KAAK,UAAU;gBACX,OAAO,UAAU,CAAC;YACtB,KAAK,OAAO;gBACR,OAAO,OAAO,CAAC;YACnB,KAAK,WAAW;gBACZ,OAAO,cAAc,CAAC;YAC1B;gBACI,OAAO,SAAS,CAAC;QACzB,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,eAAe,CAAC,IAAwB;QAC3C,OAAO,IAAI,KAAK,YAAY,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,OAAO,CAAC;IAC1E,CAAC;CACJ"}

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"}