@robosystems/client 1.12.1 → 1.13.0

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,128 +211,160 @@ 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
 
-  /**
-   * Convenience method for simple agent queries with auto-selection
-   */
-  async query(
-    graphId: string,
-    message: string,
-    context?: Record<string, any>
-  ): Promise<OperatorResult> {
-    return this.executeQuery(graphId, { message, context }, { mode: 'auto' })
-  }
+      const finish = () => {
+        sseClient.close()
+        if (this.sseClient === sseClient) {
+          this.sseClient = undefined
+        }
+      }
 
-  /**
-   * Execute financial agent for financial analysis
-   */
-  async analyzeFinancials(
-    graphId: string,
-    message: string,
-    options: OperatorOptions = {}
-  ): Promise<OperatorResult> {
-    return this.executeOperator(graphId, 'financial', { message }, options)
+      // 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'))
+      })
+    })
   }
 
   /**
-   * 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.
    */
-  async research(
-    graphId: string,
-    message: string,
-    options: OperatorOptions = {}
+  private async pollForCompletion(
+    operationId: string,
+    options: OperatorOptions,
+    streamError: unknown
   ): Promise<OperatorResult> {
-    return this.executeOperator(graphId, 'research', { message }, options)
+    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)
+      }
+    }
   }
 
   /**
-   * Execute RAG agent for fast retrieval
+   * Convenience method for simple agent queries with auto-selection
    */
-  async rag(
+  async query(
     graphId: string,
     message: string,
-    options: OperatorOptions = {}
+    context?: Record<string, any>
   ): Promise<OperatorResult> {
-    return this.executeOperator(graphId, 'rag', { message }, options)
+    return this.executeQuery(graphId, { message, context }, { mode: 'auto' })
   }
 
   /**

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)