@robosystems/client 1.12.1 → 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,23 +74,22 @@ export declare class OperatorClient {
      * Execute specific operator type
      */
     executeOperator(graphId: string, operatorType: string, request: OperatorQueryRequest, options?: OperatorOptions): Promise<OperatorResult>;
-    private waitForOperatorCompletion;
-    /**
-     * Convenience method for simple agent queries with auto-selection
-     */
-    query(graphId: string, message: string, context?: Record<string, any>): Promise<OperatorResult>;
     /**
-     * Execute financial agent for financial analysis
+     * Resolve an operator endpoint response: a sync 200 body is the result, a
+     * 202 with an `operation_id` is followed to completion.
      */
-    analyzeFinancials(graphId: string, message: string, options?: OperatorOptions): Promise<OperatorResult>;
+    private settle;
+    private waitForOperatorCompletion;
     /**
-     * Execute research agent for deep research
+     * 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.
      */
-    research(graphId: string, message: string, options?: OperatorOptions): Promise<OperatorResult>;
+    private pollForCompletion;
     /**
-     * Execute RAG agent for fast retrieval
+     * Convenience method for simple agent queries with auto-selection
      */
-    rag(graphId: string, message: string, options?: OperatorOptions): Promise<OperatorResult>;
+    query(graphId: string, message: string, context?: Record<string, any>): Promise<OperatorResult>;
     /**
      * Cancel any active SSE connections
      */

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,126 +92,155 @@ 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'));
+            });
         });
     }
     /**
-     * Convenience method for simple agent queries with auto-selection
-     */
-    async query(graphId, message, context) {
-        return this.executeQuery(graphId, { message, context }, { mode: 'auto' });
-    }
-    /**
-     * Execute financial agent for financial analysis
+     * 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 analyzeFinancials(graphId, message, options = {}) {
-        return this.executeOperator(graphId, 'financial', { message }, options);
-    }
-    /**
-     * Execute research agent for deep research
-     */
-    async research(graphId, message, options = {}) {
-        return this.executeOperator(graphId, 'research', { message }, options);
+    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);
+            }
+        }
     }
     /**
-     * Execute RAG agent for fast retrieval
+     * Convenience method for simple agent queries with auto-selection
      */
-    async rag(graphId, message, options = {}) {
-        return this.executeOperator(graphId, 'rag', { message }, options);
+    async query(graphId, message, context) {
+        return this.executeQuery(graphId, { message, context }, { mode: 'auto' });
     }
     /**
      * Cancel any active SSE connections