@robosystems/client 1.12.2 → 1.13.0

package/artifacts/OperationClient.d.ts

@@ -1,3 +1,4 @@
+import type { TokenProvider } from './graphql/client';
 export interface OperationProgress {
     message: string;
     progressPercent?: number;
@@ -25,6 +26,7 @@ export declare class OperationClient {
         credentials?: 'include' | 'same-origin' | 'omit';
         headers?: Record<string, string>;
         token?: string;
+        tokenProvider?: TokenProvider;
         maxRetries?: number;
         retryDelay?: number;
     });

package/artifacts/OperationClient.ts

@@ -6,6 +6,7 @@
  */
 
 import { cancelOperation as cancelOperationSDK, getOperationStatus } from '../sdk.gen'
+import type { TokenProvider } from './graphql/client'
 import { EventType, SSEClient } from './SSEClient'
 
 export interface OperationProgress {
@@ -35,6 +36,7 @@ export class OperationClient {
     credentials?: 'include' | 'same-origin' | 'omit'
     headers?: Record<string, string>
     token?: string // JWT token for authentication
+    tokenProvider?: TokenProvider // consulted on every SSE connect; wins over `token`
     maxRetries?: number
     retryDelay?: number
   }
@@ -46,6 +48,7 @@ export class OperationClient {
     credentials?: 'include' | 'same-origin' | 'omit'
     headers?: Record<string, string>
     token?: string // JWT token for authentication
+    tokenProvider?: TokenProvider // consulted on every SSE connect; wins over `token`
     maxRetries?: number
     retryDelay?: number
   }) {

package/artifacts/OperatorClient.d.ts

@@ -1,3 +1,4 @@
+import type { TokenProvider } from './graphql/client';
 export interface OperatorQueryRequest {
     message: string;
     history?: Array<{
@@ -13,6 +14,12 @@ export interface OperatorOptions {
     mode?: 'auto' | 'sync' | 'async';
     maxWait?: number;
     onProgress?: (message: string, percentage?: number) => void;
+    /**
+     * Interval between `/v1/operations/{id}/status` polls while the client
+     * follows a queued run it could not open an SSE stream for. Defaults to
+     * 2000 ms; only the fallback path uses it.
+     */
+    pollIntervalMs?: number;
 }
 export interface OperatorResult {
     content: string;
@@ -27,6 +34,12 @@ export interface OperatorResult {
     confidence_score?: number;
     execution_time?: number;
     timestamp?: string;
+    /**
+     * Present when the API reports a failed run inside an otherwise successful
+     * response (credit pre-flight, operator timeouts, cancelled runs). `content`
+     * then carries the explanation rather than an answer.
+     */
+    error_details?: Record<string, any>;
 }
 export interface QueuedOperatorResponse {
     status: 'queued';
@@ -34,15 +47,25 @@ export interface QueuedOperatorResponse {
     message: string;
     sse_endpoint?: string;
 }
+export interface OperatorClientConfig {
+    baseUrl: string;
+    credentials?: 'include' | 'same-origin' | 'omit';
+    headers?: Record<string, string>;
+    /**
+     * Static JWT captured at construction. Prefer `tokenProvider` in the
+     * browser — see `SSEConfig` for why a captured token goes stale.
+     */
+    token?: string;
+    /**
+     * Consulted on every SSE connect so a rotated JWT keeps the progress
+     * stream authenticated. Wins over `token` when both are set.
+     */
+    tokenProvider?: TokenProvider;
+}
 export declare class OperatorClient {
     private sseClient?;
     private config;
-    constructor(config: {
-        baseUrl: string;
-        credentials?: 'include' | 'same-origin' | 'omit';
-        headers?: Record<string, string>;
-        token?: string;
-    });
+    constructor(config: OperatorClientConfig);
     /**
      * Execute operator query with automatic operator selection
      */
@@ -51,7 +74,18 @@ export declare class OperatorClient {
      * Execute specific operator type
      */
     executeOperator(graphId: string, operatorType: string, request: OperatorQueryRequest, options?: OperatorOptions): Promise<OperatorResult>;
+    /**
+     * Resolve an operator endpoint response: a sync 200 body is the result, a
+     * 202 with an `operation_id` is followed to completion.
+     */
+    private settle;
     private waitForOperatorCompletion;
+    /**
+     * Follow a queued run over `/v1/operations/{id}/status` until it settles.
+     * Used when the SSE stream could not be opened; `streamError` is folded
+     * into the failure message if polling cannot reach a verdict either.
+     */
+    private pollForCompletion;
     /**
      * Convenience method for simple agent queries with auto-selection
      */

package/artifacts/OperatorClient.js

@@ -8,6 +8,50 @@ exports.QueuedOperatorError = exports.OperatorClient = void 0;
  */
 const sdk_gen_1 = require("../sdk.gen");
 const SSEClient_1 = require("./SSEClient");
+const DEFAULT_POLL_INTERVAL_MS = 2000;
+// Consecutive `/status` failures tolerated before the polling fallback gives
+// up: one transient network error must not lose a run that is still going.
+const MAX_CONSECUTIVE_POLL_FAILURES = 3;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const describeError = (err) => (err instanceof Error ? err.message : String(err));
+/**
+ * Text for the `error` slot of a generated-client envelope: a thrown `Error`
+ * (network failure — the client returns those rather than throwing), an API
+ * body with `detail`, or whatever else came back.
+ */
+const describeEnvelopeError = (err) => {
+    if (err instanceof Error)
+        return err.message;
+    if (err && typeof err === 'object' && 'detail' in err)
+        return String(err.detail);
+    if (err === undefined || err === null)
+        return 'empty response';
+    return typeof err === 'string' ? err : JSON.stringify(err);
+};
+/**
+ * Shape an operator payload — the sync 200 body, the `operation_completed`
+ * event, or the `/status` `result` — into the public result type. All three
+ * carry the same fields, so one mapper keeps them consistent.
+ */
+function toOperatorResult(data) {
+    const result = {
+        content: data.content ?? '',
+        operator_used: data.operator_used || 'unknown',
+        mode_used: data.mode_used || 'standard',
+        metadata: data.metadata,
+        tokens_used: data.tokens_used,
+        confidence_score: data.confidence_score,
+        execution_time: data.execution_time,
+        timestamp: data.timestamp || new Date().toISOString(),
+    };
+    if (data.error_details) {
+        result.error_details = data.error_details;
+    }
+    return result;
+}
+/** Internal: a `/status` verdict that must not be retried. */
+class PollAbort extends Error {
+}
 class OperatorClient {
     constructor(config) {
         this.config = config;
@@ -29,32 +73,7 @@ class OperatorClient {
             },
         };
         const response = await (0, sdk_gen_1.autoSelectOperator)(data);
-        const responseData = response.data;
-        // Check if this is an immediate response (sync execution)
-        if (responseData?.content !== undefined && responseData?.operator_used) {
-            return {
-                content: responseData.content,
-                operator_used: responseData.operator_used,
-                mode_used: responseData.mode_used,
-                metadata: responseData.metadata,
-                tokens_used: responseData.tokens_used,
-                confidence_score: responseData.confidence_score,
-                execution_time: responseData.execution_time,
-                timestamp: new Date().toISOString(),
-            };
-        }
-        // Check if this is a queued response (async background task execution)
-        if (responseData?.operation_id) {
-            const queuedResponse = responseData;
-            // If user doesn't want to wait, throw with queue info
-            if (options.maxWait === 0) {
-                throw new QueuedOperatorError(queuedResponse);
-            }
-            // Use SSE to monitor the operation
-            return this.waitForOperatorCompletion(queuedResponse.operation_id, options);
-        }
-        // Unexpected response format
-        throw new Error('Unexpected response format from operator endpoint');
+        return this.settle(response.data, options);
     }
     /**
      * Execute specific operator type
@@ -73,103 +92,150 @@ class OperatorClient {
             },
         };
         const response = await (0, sdk_gen_1.executeSpecificOperator)(data);
-        const responseData = response.data;
-        // Check if this is an immediate response (sync execution)
+        return this.settle(response.data, options);
+    }
+    /**
+     * Resolve an operator endpoint response: a sync 200 body is the result, a
+     * 202 with an `operation_id` is followed to completion.
+     */
+    async settle(responseData, options) {
+        // Immediate response (sync execution)
         if (responseData?.content !== undefined && responseData?.operator_used) {
-            return {
-                content: responseData.content,
-                operator_used: responseData.operator_used,
-                mode_used: responseData.mode_used,
-                metadata: responseData.metadata,
-                tokens_used: responseData.tokens_used,
-                confidence_score: responseData.confidence_score,
-                execution_time: responseData.execution_time,
-                timestamp: new Date().toISOString(),
-            };
+            return toOperatorResult(responseData);
         }
-        // Check if this is a queued response (async background task execution)
+        // Queued response (async background task execution)
         if (responseData?.operation_id) {
             const queuedResponse = responseData;
             // If user doesn't want to wait, throw with queue info
             if (options.maxWait === 0) {
                 throw new QueuedOperatorError(queuedResponse);
             }
-            // Use SSE to monitor the operation
             return this.waitForOperatorCompletion(queuedResponse.operation_id, options);
         }
         // Unexpected response format
         throw new Error('Unexpected response format from operator endpoint');
     }
     async waitForOperatorCompletion(operationId, options) {
+        const sseClient = new SSEClient_1.SSEClient(this.config);
+        this.sseClient = sseClient;
+        try {
+            await sseClient.connect(operationId);
+        }
+        catch (streamError) {
+            // The run is already queued and finishes whether or not anyone is
+            // watching, so a stream that cannot open — a revoked token, a proxy
+            // that will not hold the connection, the per-user connection cap —
+            // must not lose the result. Follow the operation over `/status`,
+            // which rides the regular REST auth path, instead.
+            this.sseClient = undefined;
+            return this.pollForCompletion(operationId, options, streamError);
+        }
         return new Promise((resolve, reject) => {
-            const sseClient = new SSEClient_1.SSEClient(this.config);
-            sseClient
-                .connect(operationId)
-                .then(() => {
-                let result = null;
-                // Listen for progress events
-                sseClient.on(SSEClient_1.EventType.OPERATION_PROGRESS, (data) => {
-                    options.onProgress?.(data.message, data.progress_percentage);
-                });
-                // Listen for agent-specific events
-                sseClient.on('operator_started', (data) => {
-                    options.onProgress?.(`Operator ${data.operator_type} started`, 0);
-                });
-                sseClient.on('operator_initialized', (data) => {
-                    options.onProgress?.(`${data.agent_name} initialized`, 10);
-                });
-                sseClient.on('progress', (data) => {
-                    options.onProgress?.(data.message, data.percentage);
-                });
-                sseClient.on('operator_completed', (data) => {
-                    result = {
-                        content: data.content,
-                        operator_used: data.operator_used,
-                        mode_used: data.mode_used,
-                        metadata: data.metadata,
-                        tokens_used: data.tokens_used,
-                        confidence_score: data.confidence_score,
-                        execution_time: data.execution_time,
-                        timestamp: data.timestamp || new Date().toISOString(),
-                    };
-                    sseClient.close();
+            let result = null;
+            const finish = () => {
+                sseClient.close();
+                if (this.sseClient === sseClient) {
+                    this.sseClient = undefined;
+                }
+            };
+            // Listen for progress events
+            sseClient.on(SSEClient_1.EventType.OPERATION_PROGRESS, (data) => {
+                options.onProgress?.(data.message, data.progress_percentage);
+            });
+            // Listen for agent-specific events
+            sseClient.on('operator_started', (data) => {
+                options.onProgress?.(`Operator ${data.operator_type} started`, 0);
+            });
+            sseClient.on('operator_initialized', (data) => {
+                options.onProgress?.(`${data.agent_name} initialized`, 10);
+            });
+            sseClient.on('progress', (data) => {
+                options.onProgress?.(data.message, data.percentage);
+            });
+            sseClient.on('operator_completed', (data) => {
+                result = toOperatorResult(data);
+                finish();
+                resolve(result);
+            });
+            // Fallback to generic completion event
+            sseClient.on(SSEClient_1.EventType.OPERATION_COMPLETED, (data) => {
+                if (!result) {
+                    result = toOperatorResult(data.result || data);
+                    finish();
                     resolve(result);
-                });
-                // Fallback to generic completion event
-                sseClient.on(SSEClient_1.EventType.OPERATION_COMPLETED, (data) => {
-                    if (!result) {
-                        const operatorResult = data.result || data;
-                        result = {
-                            content: operatorResult.content || '',
-                            operator_used: operatorResult.operator_used || 'unknown',
-                            mode_used: operatorResult.mode_used || 'standard',
-                            metadata: operatorResult.metadata,
-                            tokens_used: operatorResult.tokens_used,
-                            confidence_score: operatorResult.confidence_score,
-                            execution_time: operatorResult.execution_time,
-                            timestamp: operatorResult.timestamp || new Date().toISOString(),
-                        };
-                        sseClient.close();
-                        resolve(result);
-                    }
-                });
-                sseClient.on(SSEClient_1.EventType.OPERATION_ERROR, (error) => {
-                    sseClient.close();
-                    reject(new Error(error.message || error.error));
-                });
-                sseClient.on(SSEClient_1.EventType.OPERATION_CANCELLED, () => {
-                    sseClient.close();
-                    reject(new Error('Agent execution cancelled'));
-                });
-                // Handle generic error event
-                sseClient.on('error', (error) => {
-                    sseClient.close();
-                    reject(new Error(error.error || error.message || 'Agent execution failed'));
-                });
-            })
-                .catch(reject);
+                }
+            });
+            sseClient.on(SSEClient_1.EventType.OPERATION_ERROR, (error) => {
+                finish();
+                reject(new Error(error.message || error.error));
+            });
+            sseClient.on(SSEClient_1.EventType.OPERATION_CANCELLED, () => {
+                finish();
+                reject(new Error('Agent execution cancelled'));
+            });
+            // Handle generic error event
+            sseClient.on('error', (error) => {
+                finish();
+                reject(new Error(error.error || error.message || 'Agent execution failed'));
+            });
         });
     }
+    /**
+     * Follow a queued run over `/v1/operations/{id}/status` until it settles.
+     * Used when the SSE stream could not be opened; `streamError` is folded
+     * into the failure message if polling cannot reach a verdict either.
+     */
+    async pollForCompletion(operationId, options, streamError) {
+        const interval = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        const streamDetail = describeError(streamError);
+        let consecutiveFailures = 0;
+        options.onProgress?.('Live progress unavailable — waiting for the result');
+        for (;;) {
+            let status;
+            try {
+                const response = await (0, sdk_gen_1.getOperationStatus)({ path: { operation_id: operationId } });
+                if (response.error || !response.data) {
+                    const httpStatus = response.response?.status;
+                    const detail = describeEnvelopeError(response.error);
+                    // A definitive 4xx (expired, not ours, unauthenticated) ends the
+                    // wait; anything else is treated as transient and retried below.
+                    if (httpStatus !== undefined &&
+                        httpStatus >= 400 &&
+                        httpStatus < 500 &&
+                        httpStatus !== 429) {
+                        throw new PollAbort(`Operator stream failed (${streamDetail}); status check failed (${httpStatus}: ${detail})`);
+                    }
+                    throw new Error(detail);
+                }
+                status = response.data;
+                consecutiveFailures = 0;
+            }
+            catch (pollError) {
+                if (pollError instanceof PollAbort) {
+                    throw new Error(pollError.message);
+                }
+                consecutiveFailures += 1;
+                if (consecutiveFailures >= MAX_CONSECUTIVE_POLL_FAILURES) {
+                    throw new Error(`Operator stream failed (${streamDetail}); status polling failed (${describeError(pollError)})`);
+                }
+                await sleep(interval);
+                continue;
+            }
+            switch (status.status) {
+                case 'completed':
+                    return toOperatorResult(status.result || {});
+                case 'failed':
+                    throw new Error(status.error || status.message || 'Operator run failed');
+                case 'cancelled':
+                    throw new Error('Agent execution cancelled');
+                default:
+                    if (status.message) {
+                        options.onProgress?.(status.message);
+                    }
+                    await sleep(interval);
+            }
+        }
+    }
     /**
      * Convenience method for simple agent queries with auto-selection
      */

package/artifacts/OperatorClient.ts

@@ -5,8 +5,9 @@
  * Provides intelligent operator execution with automatic strategy selection
  */
 
-import { autoSelectOperator, executeSpecificOperator } from '../sdk.gen'
+import { autoSelectOperator, executeSpecificOperator, getOperationStatus } from '../sdk.gen'
 import type { AutoSelectOperatorData, ExecuteSpecificOperatorData } from '../types.gen'
+import type { TokenProvider } from './graphql/client'
 import { EventType, SSEClient } from './SSEClient'
 
 export interface OperatorQueryRequest {
@@ -22,6 +23,12 @@ export interface OperatorOptions {
   mode?: 'auto' | 'sync' | 'async'
   maxWait?: number
   onProgress?: (message: string, percentage?: number) => void
+  /**
+   * Interval between `/v1/operations/{id}/status` polls while the client
+   * follows a queued run it could not open an SSE stream for. Defaults to
+   * 2000 ms; only the fallback path uses it.
+   */
+  pollIntervalMs?: number
 }
 
 export interface OperatorResult {
@@ -37,6 +44,12 @@ export interface OperatorResult {
   confidence_score?: number
   execution_time?: number
   timestamp?: string
+  /**
+   * Present when the API reports a failed run inside an otherwise successful
+   * response (credit pre-flight, operator timeouts, cancelled runs). `content`
+   * then carries the explanation rather than an answer.
+   */
+  error_details?: Record<string, any>
 }
 
 export interface QueuedOperatorResponse {
@@ -46,21 +59,74 @@ export interface QueuedOperatorResponse {
   sse_endpoint?: string
 }
 
+export interface OperatorClientConfig {
+  baseUrl: string
+  credentials?: 'include' | 'same-origin' | 'omit'
+  headers?: Record<string, string>
+  /**
+   * Static JWT captured at construction. Prefer `tokenProvider` in the
+   * browser — see `SSEConfig` for why a captured token goes stale.
+   */
+  token?: string
+  /**
+   * Consulted on every SSE connect so a rotated JWT keeps the progress
+   * stream authenticated. Wins over `token` when both are set.
+   */
+  tokenProvider?: TokenProvider
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 2000
+
+// Consecutive `/status` failures tolerated before the polling fallback gives
+// up: one transient network error must not lose a run that is still going.
+const MAX_CONSECUTIVE_POLL_FAILURES = 3
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
+
+const describeError = (err: unknown): string => (err instanceof Error ? err.message : String(err))
+
+/**
+ * Text for the `error` slot of a generated-client envelope: a thrown `Error`
+ * (network failure — the client returns those rather than throwing), an API
+ * body with `detail`, or whatever else came back.
+ */
+const describeEnvelopeError = (err: unknown): string => {
+  if (err instanceof Error) return err.message
+  if (err && typeof err === 'object' && 'detail' in err) return String((err as any).detail)
+  if (err === undefined || err === null) return 'empty response'
+  return typeof err === 'string' ? err : JSON.stringify(err)
+}
+
+/**
+ * Shape an operator payload — the sync 200 body, the `operation_completed`
+ * event, or the `/status` `result` — into the public result type. All three
+ * carry the same fields, so one mapper keeps them consistent.
+ */
+function toOperatorResult(data: Record<string, any>): OperatorResult {
+  const result: OperatorResult = {
+    content: data.content ?? '',
+    operator_used: data.operator_used || 'unknown',
+    mode_used: data.mode_used || 'standard',
+    metadata: data.metadata,
+    tokens_used: data.tokens_used,
+    confidence_score: data.confidence_score,
+    execution_time: data.execution_time,
+    timestamp: data.timestamp || new Date().toISOString(),
+  }
+  if (data.error_details) {
+    result.error_details = data.error_details
+  }
+  return result
+}
+
+/** Internal: a `/status` verdict that must not be retried. */
+class PollAbort extends Error {}
+
 export class OperatorClient {
   private sseClient?: SSEClient
-  private config: {
-    baseUrl: string
-    credentials?: 'include' | 'same-origin' | 'omit'
-    headers?: Record<string, string>
-    token?: string
-  }
+  private config: OperatorClientConfig
 
-  constructor(config: {
-    baseUrl: string
-    credentials?: 'include' | 'same-origin' | 'omit'
-    headers?: Record<string, string>
-    token?: string
-  }) {
+  constructor(config: OperatorClientConfig) {
     this.config = config
   }
 
@@ -86,37 +152,7 @@ export class OperatorClient {
     }
 
     const response = await autoSelectOperator(data)
-    const responseData = response.data as any
-
-    // Check if this is an immediate response (sync execution)
-    if (responseData?.content !== undefined && responseData?.operator_used) {
-      return {
-        content: responseData.content,
-        operator_used: responseData.operator_used,
-        mode_used: responseData.mode_used,
-        metadata: responseData.metadata,
-        tokens_used: responseData.tokens_used,
-        confidence_score: responseData.confidence_score,
-        execution_time: responseData.execution_time,
-        timestamp: new Date().toISOString(),
-      }
-    }
-
-    // Check if this is a queued response (async background task execution)
-    if (responseData?.operation_id) {
-      const queuedResponse = responseData as QueuedOperatorResponse
-
-      // If user doesn't want to wait, throw with queue info
-      if (options.maxWait === 0) {
-        throw new QueuedOperatorError(queuedResponse)
-      }
-
-      // Use SSE to monitor the operation
-      return this.waitForOperatorCompletion(queuedResponse.operation_id, options)
-    }
-
-    // Unexpected response format
-    throw new Error('Unexpected response format from operator endpoint')
+    return this.settle(response.data, options)
   }
 
   /**
@@ -142,23 +178,20 @@ export class OperatorClient {
     }
 
     const response = await executeSpecificOperator(data)
-    const responseData = response.data as any
+    return this.settle(response.data, options)
+  }
 
-    // Check if this is an immediate response (sync execution)
+  /**
+   * Resolve an operator endpoint response: a sync 200 body is the result, a
+   * 202 with an `operation_id` is followed to completion.
+   */
+  private async settle(responseData: any, options: OperatorOptions): Promise<OperatorResult> {
+    // Immediate response (sync execution)
     if (responseData?.content !== undefined && responseData?.operator_used) {
-      return {
-        content: responseData.content,
-        operator_used: responseData.operator_used,
-        mode_used: responseData.mode_used,
-        metadata: responseData.metadata,
-        tokens_used: responseData.tokens_used,
-        confidence_score: responseData.confidence_score,
-        execution_time: responseData.execution_time,
-        timestamp: new Date().toISOString(),
-      }
+      return toOperatorResult(responseData)
     }
 
-    // Check if this is a queued response (async background task execution)
+    // Queued response (async background task execution)
     if (responseData?.operation_id) {
       const queuedResponse = responseData as QueuedOperatorResponse
 
@@ -167,7 +200,6 @@ export class OperatorClient {
         throw new QueuedOperatorError(queuedResponse)
       }
 
-      // Use SSE to monitor the operation
       return this.waitForOperatorCompletion(queuedResponse.operation_id, options)
     }
 
@@ -179,86 +211,151 @@ export class OperatorClient {
     operationId: string,
     options: OperatorOptions
   ): Promise<OperatorResult> {
+    const sseClient = new SSEClient(this.config)
+    this.sseClient = sseClient
+
+    try {
+      await sseClient.connect(operationId)
+    } catch (streamError) {
+      // The run is already queued and finishes whether or not anyone is
+      // watching, so a stream that cannot open — a revoked token, a proxy
+      // that will not hold the connection, the per-user connection cap —
+      // must not lose the result. Follow the operation over `/status`,
+      // which rides the regular REST auth path, instead.
+      this.sseClient = undefined
+      return this.pollForCompletion(operationId, options, streamError)
+    }
+
     return new Promise((resolve, reject) => {
-      const sseClient = new SSEClient(this.config)
-
-      sseClient
-        .connect(operationId)
-        .then(() => {
-          let result: OperatorResult | null = null
-
-          // Listen for progress events
-          sseClient.on(EventType.OPERATION_PROGRESS, (data) => {
-            options.onProgress?.(data.message, data.progress_percentage)
-          })
-
-          // Listen for agent-specific events
-          sseClient.on('operator_started' as EventType, (data) => {
-            options.onProgress?.(`Operator ${data.operator_type} started`, 0)
-          })
-
-          sseClient.on('operator_initialized' as EventType, (data) => {
-            options.onProgress?.(`${data.agent_name} initialized`, 10)
-          })
-
-          sseClient.on('progress' as EventType, (data) => {
-            options.onProgress?.(data.message, data.percentage)
-          })
-
-          sseClient.on('operator_completed' as EventType, (data) => {
-            result = {
-              content: data.content,
-              operator_used: data.operator_used,
-              mode_used: data.mode_used,
-              metadata: data.metadata,
-              tokens_used: data.tokens_used,
-              confidence_score: data.confidence_score,
-              execution_time: data.execution_time,
-              timestamp: data.timestamp || new Date().toISOString(),
-            }
-            sseClient.close()
-            resolve(result)
-          })
-
-          // Fallback to generic completion event
-          sseClient.on(EventType.OPERATION_COMPLETED, (data) => {
-            if (!result) {
-              const operatorResult = data.result || data
-              result = {
-                content: operatorResult.content || '',
-                operator_used: operatorResult.operator_used || 'unknown',
-                mode_used: operatorResult.mode_used || 'standard',
-                metadata: operatorResult.metadata,
-                tokens_used: operatorResult.tokens_used,
-                confidence_score: operatorResult.confidence_score,
-                execution_time: operatorResult.execution_time,
-                timestamp: operatorResult.timestamp || new Date().toISOString(),
-              }
-              sseClient.close()
-              resolve(result)
-            }
-          })
-
-          sseClient.on(EventType.OPERATION_ERROR, (error) => {
-            sseClient.close()
-            reject(new Error(error.message || error.error))
-          })
-
-          sseClient.on(EventType.OPERATION_CANCELLED, () => {
-            sseClient.close()
-            reject(new Error('Agent execution cancelled'))
-          })
-
-          // Handle generic error event
-          sseClient.on('error' as EventType, (error) => {
-            sseClient.close()
-            reject(new Error(error.error || error.message || 'Agent execution failed'))
-          })
-        })
-        .catch(reject)
+      let result: OperatorResult | null = null
+
+      const finish = () => {
+        sseClient.close()
+        if (this.sseClient === sseClient) {
+          this.sseClient = undefined
+        }
+      }
+
+      // Listen for progress events
+      sseClient.on(EventType.OPERATION_PROGRESS, (data) => {
+        options.onProgress?.(data.message, data.progress_percentage)
+      })
+
+      // Listen for agent-specific events
+      sseClient.on('operator_started' as EventType, (data) => {
+        options.onProgress?.(`Operator ${data.operator_type} started`, 0)
+      })
+
+      sseClient.on('operator_initialized' as EventType, (data) => {
+        options.onProgress?.(`${data.agent_name} initialized`, 10)
+      })
+
+      sseClient.on('progress' as EventType, (data) => {
+        options.onProgress?.(data.message, data.percentage)
+      })
+
+      sseClient.on('operator_completed' as EventType, (data) => {
+        result = toOperatorResult(data)
+        finish()
+        resolve(result)
+      })
+
+      // Fallback to generic completion event
+      sseClient.on(EventType.OPERATION_COMPLETED, (data) => {
+        if (!result) {
+          result = toOperatorResult(data.result || data)
+          finish()
+          resolve(result)
+        }
+      })
+
+      sseClient.on(EventType.OPERATION_ERROR, (error) => {
+        finish()
+        reject(new Error(error.message || error.error))
+      })
+
+      sseClient.on(EventType.OPERATION_CANCELLED, () => {
+        finish()
+        reject(new Error('Agent execution cancelled'))
+      })
+
+      // Handle generic error event
+      sseClient.on('error' as EventType, (error) => {
+        finish()
+        reject(new Error(error.error || error.message || 'Agent execution failed'))
+      })
     })
   }
 
+  /**
+   * Follow a queued run over `/v1/operations/{id}/status` until it settles.
+   * Used when the SSE stream could not be opened; `streamError` is folded
+   * into the failure message if polling cannot reach a verdict either.
+   */
+  private async pollForCompletion(
+    operationId: string,
+    options: OperatorOptions,
+    streamError: unknown
+  ): Promise<OperatorResult> {
+    const interval = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS
+    const streamDetail = describeError(streamError)
+    let consecutiveFailures = 0
+
+    options.onProgress?.('Live progress unavailable — waiting for the result')
+
+    for (;;) {
+      let status: any
+      try {
+        const response = await getOperationStatus({ path: { operation_id: operationId } })
+        if (response.error || !response.data) {
+          const httpStatus = response.response?.status
+          const detail = describeEnvelopeError(response.error)
+          // A definitive 4xx (expired, not ours, unauthenticated) ends the
+          // wait; anything else is treated as transient and retried below.
+          if (
+            httpStatus !== undefined &&
+            httpStatus >= 400 &&
+            httpStatus < 500 &&
+            httpStatus !== 429
+          ) {
+            throw new PollAbort(
+              `Operator stream failed (${streamDetail}); status check failed (${httpStatus}: ${detail})`
+            )
+          }
+          throw new Error(detail)
+        }
+        status = response.data
+        consecutiveFailures = 0
+      } catch (pollError) {
+        if (pollError instanceof PollAbort) {
+          throw new Error(pollError.message)
+        }
+        consecutiveFailures += 1
+        if (consecutiveFailures >= MAX_CONSECUTIVE_POLL_FAILURES) {
+          throw new Error(
+            `Operator stream failed (${streamDetail}); status polling failed (${describeError(pollError)})`
+          )
+        }
+        await sleep(interval)
+        continue
+      }
+
+      switch (status.status) {
+        case 'completed':
+          return toOperatorResult(status.result || {})
+        case 'failed':
+          throw new Error(status.error || status.message || 'Operator run failed')
+        case 'cancelled':
+          throw new Error('Agent execution cancelled')
+        default:
+          if (status.message) {
+            options.onProgress?.(status.message)
+          }
+          await sleep(interval)
+      }
+    }
+  }
+
   /**
    * Convenience method for simple agent queries with auto-selection
    */

package/artifacts/QueryClient.d.ts

@@ -1,3 +1,4 @@
+import type { TokenProvider } from './graphql/client';
 export interface QueryRequest {
     query: string;
     parameters?: Record<string, any>;
@@ -34,6 +35,7 @@ export declare class QueryClient {
         credentials?: 'include' | 'same-origin' | 'omit';
         headers?: Record<string, string>;
         token?: string;
+        tokenProvider?: TokenProvider;
     });
     executeQuery(graphId: string, request: QueryRequest, options?: QueryOptions): Promise<QueryResult | AsyncIterableIterator<any>>;
     private parseNDJSONResponse;

package/artifacts/QueryClient.ts

@@ -7,6 +7,7 @@
 
 import { executeCypher } from '../sdk.gen'
 import type { ExecuteCypherData } from '../types.gen'
+import type { TokenProvider } from './graphql/client'
 import { EventType, SSEClient } from './SSEClient'
 
 export interface QueryRequest {
@@ -48,6 +49,7 @@ export class QueryClient {
     credentials?: 'include' | 'same-origin' | 'omit'
     headers?: Record<string, string>
     token?: string // JWT token for authentication
+    tokenProvider?: TokenProvider // consulted on every SSE connect; wins over `token`
   }
 
   constructor(config: {
@@ -55,6 +57,7 @@ export class QueryClient {
     credentials?: 'include' | 'same-origin' | 'omit'
     headers?: Record<string, string>
     token?: string // JWT token for authentication
+    tokenProvider?: TokenProvider // consulted on every SSE connect; wins over `token`
   }) {
     this.config = config
   }

package/artifacts/SSEClient.d.ts

@@ -14,12 +14,30 @@
  * - Implementing a WebSocket-based alternative
  * - Using short-lived tokens that expire quickly
  * - Ensuring all connections use HTTPS
+ *
+ * CREDENTIAL ROTATION: the stream endpoint authenticates the JWT it finds in
+ * the URL, and the backend revokes the previous JWT on every session refresh.
+ * A `token` captured once therefore goes dead the moment the session rotates
+ * (about every 25 minutes in the browser apps); pass a `tokenProvider` and it
+ * is consulted on every connect — including automatic reconnects — instead.
  */
+import type { TokenProvider } from './graphql/client';
 export interface SSEConfig {
     baseUrl: string;
     credentials?: 'include' | 'same-origin' | 'omit';
     headers?: Record<string, string>;
+    /**
+     * Static JWT captured at construction. Fine for long-lived API keys and
+     * server-side flows; browser sessions should use `tokenProvider`.
+     */
     token?: string;
+    /**
+     * Dynamic credential callback, consulted on every `connect()` and
+     * preferred over `token` when both are set. Return `null` to connect
+     * without a token. See the class documentation for why a static token
+     * is not enough in the browser.
+     */
+    tokenProvider?: TokenProvider;
     maxRetries?: number;
     retryDelay?: number;
     heartbeatInterval?: number;
@@ -51,6 +69,14 @@ export declare class SSEClient {
     private listeners;
     constructor(config: SSEConfig);
     connect(operationId: string, fromSequence?: number): Promise<void>;
+    /**
+     * Credential for one connect attempt: the `tokenProvider` result when one
+     * is configured (`null`/`undefined` connects unauthenticated), otherwise
+     * the static `token`. A throwing provider fails the connect — matching the
+     * GraphQL client — because the caller intended to authenticate, and a
+     * silent unauthenticated attempt would surface as an unrelated-looking 401.
+     */
+    private resolveToken;
     private handleMessage;
     private handleTypedEvent;
     private handleError;

package/artifacts/SSEClient.js

@@ -27,13 +27,16 @@ class SSEClient {
         };
     }
     async connect(operationId, fromSequence = 0) {
+        // Resolved per attempt so a rotated JWT is picked up by every connect,
+        // not just the first one after construction.
+        const token = await this.resolveToken();
         return new Promise((resolve, reject) => {
             let url = `${this.config.baseUrl}/v1/operations/${operationId}/stream?from_sequence=${fromSequence}`;
             // Add JWT token as query parameter if provided
             // WARNING: EventSource API doesn't support custom headers, so tokens are passed via query param
             // This has security implications - see class documentation
-            if (this.config.token) {
-                url += `&token=${encodeURIComponent(this.config.token)}`;
+            if (token) {
+                url += `&token=${encodeURIComponent(token)}`;
             }
             this.eventSource = new EventSource(url, {
                 withCredentials: this.config.credentials === 'include',
@@ -83,6 +86,29 @@ class SSEClient {
             });
         });
     }
+    /**
+     * Credential for one connect attempt: the `tokenProvider` result when one
+     * is configured (`null`/`undefined` connects unauthenticated), otherwise
+     * the static `token`. A throwing provider fails the connect — matching the
+     * GraphQL client — because the caller intended to authenticate, and a
+     * silent unauthenticated attempt would surface as an unrelated-looking 401.
+     */
+    async resolveToken() {
+        if (!this.config.tokenProvider) {
+            return this.config.token;
+        }
+        let token;
+        try {
+            token = await this.config.tokenProvider();
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new Error(`RoboSystems SDK: tokenProvider threw while resolving the SSE credential (${detail}). ` +
+                'Fix the tokenProvider passed in the client config (or via setSDKClientConfig) so it ' +
+                'returns the current token, or null to connect without one.');
+        }
+        return token || undefined;
+    }
     handleMessage(event) {
         try {
             const data = JSON.parse(event.data);

package/artifacts/SSEClient.ts

@@ -16,13 +16,32 @@
  * - Implementing a WebSocket-based alternative
  * - Using short-lived tokens that expire quickly
  * - Ensuring all connections use HTTPS
+ *
+ * CREDENTIAL ROTATION: the stream endpoint authenticates the JWT it finds in
+ * the URL, and the backend revokes the previous JWT on every session refresh.
+ * A `token` captured once therefore goes dead the moment the session rotates
+ * (about every 25 minutes in the browser apps); pass a `tokenProvider` and it
+ * is consulted on every connect — including automatic reconnects — instead.
  */
 
+import type { TokenProvider } from './graphql/client'
+
 export interface SSEConfig {
   baseUrl: string
   credentials?: 'include' | 'same-origin' | 'omit'
   headers?: Record<string, string>
-  token?: string // JWT token for authentication
+  /**
+   * Static JWT captured at construction. Fine for long-lived API keys and
+   * server-side flows; browser sessions should use `tokenProvider`.
+   */
+  token?: string
+  /**
+   * Dynamic credential callback, consulted on every `connect()` and
+   * preferred over `token` when both are set. Return `null` to connect
+   * without a token. See the class documentation for why a static token
+   * is not enough in the browser.
+   */
+  tokenProvider?: TokenProvider
   maxRetries?: number
   retryDelay?: number
   heartbeatInterval?: number
@@ -66,14 +85,18 @@ export class SSEClient {
   }
 
   async connect(operationId: string, fromSequence: number = 0): Promise<void> {
+    // Resolved per attempt so a rotated JWT is picked up by every connect,
+    // not just the first one after construction.
+    const token = await this.resolveToken()
+
     return new Promise((resolve, reject) => {
       let url = `${this.config.baseUrl}/v1/operations/${operationId}/stream?from_sequence=${fromSequence}`
 
       // Add JWT token as query parameter if provided
       // WARNING: EventSource API doesn't support custom headers, so tokens are passed via query param
       // This has security implications - see class documentation
-      if (this.config.token) {
-        url += `&token=${encodeURIComponent(this.config.token)}`
+      if (token) {
+        url += `&token=${encodeURIComponent(token)}`
       }
 
       this.eventSource = new EventSource(url, {
@@ -135,6 +158,31 @@ export class SSEClient {
     })
   }
 
+  /**
+   * Credential for one connect attempt: the `tokenProvider` result when one
+   * is configured (`null`/`undefined` connects unauthenticated), otherwise
+   * the static `token`. A throwing provider fails the connect — matching the
+   * GraphQL client — because the caller intended to authenticate, and a
+   * silent unauthenticated attempt would surface as an unrelated-looking 401.
+   */
+  private async resolveToken(): Promise<string | undefined> {
+    if (!this.config.tokenProvider) {
+      return this.config.token
+    }
+    let token: string | null | undefined
+    try {
+      token = await this.config.tokenProvider()
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err)
+      throw new Error(
+        `RoboSystems SDK: tokenProvider threw while resolving the SSE credential (${detail}). ` +
+          'Fix the tokenProvider passed in the client config (or via setSDKClientConfig) so it ' +
+          'returns the current token, or null to connect without one.'
+      )
+    }
+    return token || undefined
+  }
+
   private handleMessage(event: MessageEvent): void {
     try {
       const data = JSON.parse(event.data)

package/artifacts/hooks.js

@@ -45,6 +45,7 @@ function useQuery(graphId) {
             credentials: sdkConfig.credentials,
             headers: sdkConfig.headers,
             token,
+            tokenProvider: sdkConfig.tokenProvider,
         });
         return () => {
             clientRef.current?.close();
@@ -122,6 +123,7 @@ function useStreamingQuery(graphId) {
             credentials: sdkConfig.credentials,
             headers: sdkConfig.headers,
             token: sdkConfig.token,
+            tokenProvider: sdkConfig.tokenProvider,
         });
         return () => {
             clientRef.current?.close();
@@ -201,6 +203,7 @@ function useOperation(operationId) {
             baseUrl: sdkConfig.baseUrl || clientConfig.baseUrl || 'http://localhost:8000',
             credentials: sdkConfig.credentials,
             token,
+            tokenProvider: sdkConfig.tokenProvider,
             maxRetries: sdkConfig.maxRetries,
             retryDelay: sdkConfig.retryDelay,
         });
@@ -300,6 +303,7 @@ function useMultipleOperations() {
             baseUrl: sdkConfig.baseUrl || clientConfig.baseUrl || 'http://localhost:8000',
             credentials: sdkConfig.credentials,
             token,
+            tokenProvider: sdkConfig.tokenProvider,
             maxRetries: sdkConfig.maxRetries,
             retryDelay: sdkConfig.retryDelay,
         });
@@ -368,6 +372,7 @@ function useSDKClients() {
             credentials: sdkConfig.credentials,
             headers: sdkConfig.headers,
             token,
+            tokenProvider: sdkConfig.tokenProvider,
         };
         const queryClient = new QueryClient_1.QueryClient(baseConfig);
         const operationsClient = new OperationClient_1.OperationClient(baseConfig);

package/artifacts/hooks.ts

@@ -46,6 +46,7 @@ export function useQuery(graphId: string) {
       credentials: sdkConfig.credentials,
       headers: sdkConfig.headers,
       token,
+      tokenProvider: sdkConfig.tokenProvider,
     })
 
     return () => {
@@ -143,6 +144,7 @@ export function useStreamingQuery(graphId: string) {
       credentials: sdkConfig.credentials,
       headers: sdkConfig.headers,
       token: sdkConfig.token,
+      tokenProvider: sdkConfig.tokenProvider,
     })
 
     return () => {
@@ -240,6 +242,7 @@ export function useOperation<T = any>(operationId?: string) {
       baseUrl: sdkConfig.baseUrl || clientConfig.baseUrl || 'http://localhost:8000',
       credentials: sdkConfig.credentials,
       token,
+      tokenProvider: sdkConfig.tokenProvider,
       maxRetries: sdkConfig.maxRetries,
       retryDelay: sdkConfig.retryDelay,
     })
@@ -353,6 +356,7 @@ export function useMultipleOperations<T = any>() {
       baseUrl: sdkConfig.baseUrl || clientConfig.baseUrl || 'http://localhost:8000',
       credentials: sdkConfig.credentials,
       token,
+      tokenProvider: sdkConfig.tokenProvider,
       maxRetries: sdkConfig.maxRetries,
       retryDelay: sdkConfig.retryDelay,
     })
@@ -439,6 +443,7 @@ export function useSDKClients() {
       credentials: sdkConfig.credentials,
       headers: sdkConfig.headers,
       token,
+      tokenProvider: sdkConfig.tokenProvider,
     }
 
     const queryClient = new QueryClient(baseConfig)

package/artifacts/index.d.ts

@@ -22,9 +22,12 @@ export interface RoboSystemsClientConfig {
      */
     token?: string;
     /**
-     * Dynamic credential callback invoked on every GraphQL request.
-     * When set, JWT refreshes are picked up automatically — no need
-     * to rebuild or clear cached clients after a refresh.
+     * Dynamic credential callback invoked on every GraphQL request and
+     * every SSE connect. When set, JWT refreshes are picked up
+     * automatically — no need to rebuild or clear cached clients after a
+     * refresh. Browser sessions need this: the backend revokes the previous
+     * JWT on each refresh, so a static `token` captured at construction
+     * stops opening progress streams the moment the session rotates.
      */
     tokenProvider?: TokenProvider;
     headers?: Record<string, string>;

package/artifacts/index.js

@@ -60,27 +60,33 @@ class RoboSystemsClients {
             retryDelay: config.retryDelay || 1000,
             timeout: config.timeout,
         };
+        // Every client that opens an SSE stream gets the tokenProvider too:
+        // the stream endpoint authenticates the JWT from the URL, and a
+        // captured static token is dead after the first session refresh.
         this.query = new QueryClient_1.QueryClient({
             baseUrl: this.config.baseUrl,
             credentials: this.config.credentials,
             token: this.config.token,
+            tokenProvider: this.config.tokenProvider,
             headers: this.config.headers,
         });
         this.operator = new OperatorClient_1.OperatorClient({
             baseUrl: this.config.baseUrl,
             credentials: this.config.credentials,
             token: this.config.token,
+            tokenProvider: this.config.tokenProvider,
             headers: this.config.headers,
         });
         this.operations = new OperationClient_1.OperationClient({
             baseUrl: this.config.baseUrl,
             credentials: this.config.credentials,
             token: this.config.token,
+            tokenProvider: this.config.tokenProvider,
             maxRetries: this.config.maxRetries,
             retryDelay: this.config.retryDelay,
         });
-        // LedgerClient / InvestorClient use GraphQL internally, so they
-        // get the tokenProvider — REST-only clients do not.
+        // LedgerClient / InvestorClient / LibraryClient use GraphQL internally
+        // and consult the tokenProvider on every request.
         this.ledger = new LedgerClient_1.LedgerClient({
             baseUrl: this.config.baseUrl,
             credentials: this.config.credentials,
@@ -125,6 +131,7 @@ class RoboSystemsClients {
             baseUrl: this.config.baseUrl,
             credentials: this.config.credentials,
             token: this.config.token,
+            tokenProvider: this.config.tokenProvider,
             headers: this.config.headers,
             maxRetries: this.config.maxRetries,
             retryDelay: this.config.retryDelay,

package/artifacts/index.ts

@@ -34,9 +34,12 @@ export interface RoboSystemsClientConfig {
    */
   token?: string
   /**
-   * Dynamic credential callback invoked on every GraphQL request.
-   * When set, JWT refreshes are picked up automatically — no need
-   * to rebuild or clear cached clients after a refresh.
+   * Dynamic credential callback invoked on every GraphQL request and
+   * every SSE connect. When set, JWT refreshes are picked up
+   * automatically — no need to rebuild or clear cached clients after a
+   * refresh. Browser sessions need this: the backend revokes the previous
+   * JWT on each refresh, so a static `token` captured at construction
+   * stops opening progress streams the moment the session rotates.
    */
   tokenProvider?: TokenProvider
   headers?: Record<string, string>
@@ -98,10 +101,14 @@ export class RoboSystemsClients {
       timeout: config.timeout,
     }
 
+    // Every client that opens an SSE stream gets the tokenProvider too:
+    // the stream endpoint authenticates the JWT from the URL, and a
+    // captured static token is dead after the first session refresh.
     this.query = new QueryClient({
       baseUrl: this.config.baseUrl,
       credentials: this.config.credentials,
       token: this.config.token,
+      tokenProvider: this.config.tokenProvider,
       headers: this.config.headers,
     })
 
@@ -109,6 +116,7 @@ export class RoboSystemsClients {
       baseUrl: this.config.baseUrl,
       credentials: this.config.credentials,
       token: this.config.token,
+      tokenProvider: this.config.tokenProvider,
       headers: this.config.headers,
     })
 
@@ -116,12 +124,13 @@ export class RoboSystemsClients {
       baseUrl: this.config.baseUrl,
       credentials: this.config.credentials,
       token: this.config.token,
+      tokenProvider: this.config.tokenProvider,
       maxRetries: this.config.maxRetries,
       retryDelay: this.config.retryDelay,
     })
 
-    // LedgerClient / InvestorClient use GraphQL internally, so they
-    // get the tokenProvider — REST-only clients do not.
+    // LedgerClient / InvestorClient / LibraryClient use GraphQL internally
+    // and consult the tokenProvider on every request.
     this.ledger = new LedgerClient({
       baseUrl: this.config.baseUrl,
       credentials: this.config.credentials,
@@ -171,6 +180,7 @@ export class RoboSystemsClients {
       baseUrl: this.config.baseUrl,
       credentials: this.config.credentials,
       token: this.config.token,
+      tokenProvider: this.config.tokenProvider,
       headers: this.config.headers,
       maxRetries: this.config.maxRetries,
       retryDelay: this.config.retryDelay,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robosystems/client",
-  "version": "1.12.2",
+  "version": "1.13.0",
   "description": "TypeScript client library for the RoboSystems financial intelligence platform",
   "main": "index.js",
   "types": "index.d.ts",