10xgraph-client 0.6.0 → 1.0.0-rc.2

package/src/endpoints/stream.ts

@@ -1,11 +1,23 @@
 import { Message } from '../message.js';
 import { AgentState } from '../agent.js';
 import { ToolExecutor } from '../tools.js';
-import { createErrorFromResponse } from '../errors.js';
-import { buildHeaders, getRequestCredentials, RequestContext } from '../request.js';
+import {
+  createErrorFromResponse,
+  NetworkError,
+  RequestTimeoutError,
+  StreamError,
+} from '../errors.js';
+import {
+  buildHeaders,
+  getRequestCredentials,
+  linkAbortSignal,
+  RequestContext,
+} from '../request.js';
 
 export interface StreamContext extends RequestContext {
   toolExecutor?: ToolExecutor;
+  /** Caller-supplied signal; aborting it cancels the request, including the open stream. */
+  signal?: AbortSignal;
 }
 
 // Stream Request payload (same as Invoke)
@@ -14,6 +26,12 @@ export interface StreamRequest {
   initial_state?: Record<string, any>;
   config?: Record<string, any>;
   recursion_limit?: number;
+  /** What to do when another run is active on the same thread (server default: 'wait'). */
+  on_busy?: 'wait' | 'cancel';
+  /** Value that answers an open interrupt. Send together with `interrupt_id`. */
+  resume?: unknown;
+  /** Id of the interrupt being answered by `resume`. */
+  interrupt_id?: string;
   response_granularity?: 'full' | 'partial' | 'low';
 }
 
@@ -44,27 +62,60 @@ export interface StreamChunk {
   timestamp?: number;
 }
 
+/** Hooks that let the caller run an idle timer only while it waits on the network. */
+interface ReadHooks {
+  beforeRead: () => void;
+  afterRead: () => void;
+}
+
+const STREAM_ENDPOINT = '/v1/graph/stream';
+
 /**
  * Parse NDJSON stream and yield individual chunks immediately as they arrive
  * Handles streaming response body as async iterable
  * Supports both newline-separated and concatenated JSON objects
+ *
+ * Leaving the loop early (break, throw, return) cancels the reader so the connection closes.
+ * A body that is cut mid-chunk, or a line that is not JSON, throws StreamError instead of
+ * ending as if the run had succeeded.
  */
 async function* parseStreamChunks(
   reader: ReadableStreamDefaultReader<Uint8Array>,
-  debug: boolean
+  debug: boolean,
+  hooks?: ReadHooks
 ): AsyncGenerator<StreamChunk, void, unknown> {
   const decoder = new TextDecoder();
   let buffer = '';
+  let completed = false;
 
   try {
     while (true) {
-      const { done, value } = await reader.read();
+      let result: ReadableStreamReadResult<Uint8Array>;
+      hooks?.beforeRead();
+      try {
+        result = await reader.read();
+      } catch (error) {
+        if ((error as Error)?.name === 'AbortError') throw error;
+        throw new StreamError(
+          `Stream connection lost: ${(error as Error)?.message ?? String(error)}`,
+          'STREAM_INTERRUPTED',
+          'unknown',
+          STREAM_ENDPOINT,
+          'POST',
+          error
+        );
+      } finally {
+        hooks?.afterRead();
+      }
+      const { done, value } = result;
 
       if (done) {
         // Process any remaining data in buffer
+        buffer += decoder.decode();
         if (buffer.trim()) {
           yield* processBuffer(buffer, debug, true);
         }
+        completed = true;
         break;
       }
 
@@ -72,14 +123,33 @@ async function* parseStreamChunks(
       buffer += decoder.decode(value, { stream: true });
 
       // Immediately process and yield all complete chunks
-      const result = yield* processBuffer(buffer, debug, false);
-      buffer = result.remaining;
+      const processed = yield* processBuffer(buffer, debug, false);
+      buffer = processed.remaining;
     }
   } finally {
+    if (!completed) {
+      // Early exit: tell the server side to stop sending so the connection is released.
+      try {
+        await reader.cancel();
+      } catch {
+        /* already errored or closed */
+      }
+    }
     reader.releaseLock();
   }
 }
 
+function badChunk(text: string, cause: unknown): StreamError {
+  return new StreamError(
+    `Stream data could not be parsed (${text.slice(0, 100)}); the stream was cut or corrupted`,
+    'STREAM_TRUNCATED',
+    'unknown',
+    STREAM_ENDPOINT,
+    'POST',
+    cause
+  );
+}
+
 /**
  * Process buffer and yield all complete JSON chunks
  * Returns the remaining incomplete buffer
@@ -103,9 +173,7 @@ function* processBuffer(
         }
         yield chunk;
       } catch (error) {
-        if (debug) {
-          console.warn('TenxGraphClient: Failed to parse NDJSON line:', line.slice(0, 100), error);
-        }
+        throw badChunk(line, error);
       }
     }
   }
@@ -122,14 +190,7 @@ function* processBuffer(
         yield chunk;
         buffer = extracted.remaining;
       } catch (error) {
-        if (debug) {
-          console.warn(
-            'TenxGraphClient: Failed to parse concatenated JSON:',
-            extracted.json.slice(0, 100),
-            error
-          );
-        }
-        break;
+        throw badChunk(extracted.json, error);
       }
     } else {
       // Incomplete JSON, keep in buffer
@@ -143,13 +204,7 @@ function* processBuffer(
           yield chunk;
           buffer = '';
         } catch (error) {
-          if (debug) {
-            console.warn(
-              'TenxGraphClient: Failed to parse final buffer:',
-              buffer.slice(0, 100),
-              error
-            );
-          }
+          throw badChunk(buffer.trim(), error);
         }
       }
       break;
@@ -246,7 +301,10 @@ export async function* streamInvoke(
   context: StreamContext,
   request: StreamRequest
 ): AsyncGenerator<StreamChunk, void, unknown> {
-  const recursion_limit = request.recursion_limit || 25;
+  const recursion_limit = request.recursion_limit ?? 25;
+  // At least one request is always sent; the limit caps tool round trips after that.
+  const maxRuns = Math.max(1, recursion_limit);
+  const timeoutMs = context.timeout > 0 ? context.timeout : 0;
 
   if (context.debug) {
     console.debug('TenxGraphClient: Starting stream invoke with recursion_limit:', recursion_limit);
@@ -256,15 +314,20 @@ export async function* streamInvoke(
   let currentMessages = request.messages;
   let iterations = 0;
   const initial_state = request.initial_state;
-  const config = request.config;
+  // Copied so a server-assigned thread_id can be added without touching the caller's object
+  let config = request.config;
   const response_granularity = request.response_granularity;
+  const on_busy = request.on_busy;
+  const resume = request.resume;
+  const interrupt_id = request.interrupt_id;
 
   // Main recursion loop (same as invoke, but using streaming)
-  while (iterations < recursion_limit) {
+  while (true) {
+    context.signal?.throwIfAborted();
     iterations++;
 
     if (context.debug) {
-      console.debug(`TenxGraphClient: Stream iteration ${iterations}/${recursion_limit}`);
+      console.debug(`TenxGraphClient: Stream iteration ${iterations}/${maxRuns}`);
     }
 
     // Prepare request for this iteration
@@ -273,6 +336,9 @@ export async function* streamInvoke(
       initial_state: iterations === 1 ? initial_state : undefined,
       config,
       recursion_limit,
+      on_busy,
+      resume: iterations === 1 ? resume : undefined,
+      interrupt_id: iterations === 1 ? interrupt_id : undefined,
       response_granularity,
     };
 
@@ -283,30 +349,52 @@ export async function* streamInvoke(
       );
     }
 
-    // Open the stream and yield all chunks
+    // Open the stream and yield all chunks. The timeout is an idle timeout: it runs while the
+    // client waits on the network (headers, then each body read) and is paused while the
+    // caller processes a chunk, so a stalled proxy is cut but a slow consumer is not.
     const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), context.timeout);
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const disarm = (): void => {
+      if (timer !== undefined) clearTimeout(timer);
+      timer = undefined;
+    };
+    const arm = (): void => {
+      disarm();
+      if (timeoutMs > 0) timer = setTimeout(() => controller.abort(), timeoutMs);
+    };
+    const unlink = linkAbortSignal(controller, context.signal);
+    let finished = false;
+    let sawError = false;
 
     try {
-      const response = await fetch(`${context.baseUrl}/v1/graph/stream`, {
-        method: 'POST',
-        headers: buildHeaders(context as RequestContext, {
-          'Content-Type': 'application/json',
-          Accept: 'application/x-ndjson, application/json',
-        }),
-        ...getRequestCredentials(context as RequestContext),
-        body: JSON.stringify(iterationRequest),
-        signal: controller.signal,
-      });
-
-      clearTimeout(timeoutId);
+      arm();
+      let response: Response;
+      try {
+        response = await fetch(`${context.baseUrl}${STREAM_ENDPOINT}`, {
+          method: 'POST',
+          headers: buildHeaders(context as RequestContext, {
+            'Content-Type': 'application/json',
+            Accept: 'application/x-ndjson, application/json',
+          }),
+          ...getRequestCredentials(context as RequestContext),
+          body: JSON.stringify(iterationRequest),
+          signal: controller.signal,
+        });
+      } catch (error) {
+        if (error instanceof TypeError) {
+          throw new NetworkError(`Network error: ${error.message}`, STREAM_ENDPOINT, 'POST', error);
+        }
+        throw error;
+      }
+      disarm();
 
       if (!response.ok) {
         console.warn(`TenxGraphClient: Stream failed with HTTP ${response.status}`);
+        arm();
         const error = await createErrorFromResponse(
           response,
           'Stream request failed',
-          '/v1/stream',
+          STREAM_ENDPOINT,
           'POST'
         );
         throw error;
@@ -320,15 +408,31 @@ export async function* streamInvoke(
       const responseMessages: Message[] = [];
       const reader = response.body.getReader();
 
-      for await (const chunk of parseStreamChunks(reader, context.debug)) {
+      for await (const chunk of parseStreamChunks(reader, context.debug, {
+        beforeRead: arm,
+        afterRead: disarm,
+      })) {
         // Yield every chunk to the caller
         yield chunk;
 
+        // The server assigns a thread id when the caller omits one; reuse it so the
+        // tool round-trip stays on the same thread. A caller-supplied id is never replaced.
+        const returnedThreadId: string | undefined = chunk.thread_id || chunk.metadata?.thread_id;
+        if (returnedThreadId && !config?.thread_id) {
+          config = { ...(config ?? {}), thread_id: returnedThreadId };
+        }
+
+        // An error chunk (including a shutdown cut with data.interrupted) ends the run.
+        if (chunk.event === StreamEventType.ERROR) {
+          sawError = true;
+        }
+
         // Also collect messages for tool execution check
         if (chunk.message) {
           responseMessages.push(chunk.message);
         }
       }
+      finished = true;
 
       if (context.debug) {
         console.info('TenxGraphClient: Stream iteration completed');
@@ -338,7 +442,24 @@ export async function* streamInvoke(
       // Check if there are remote tool calls to execute
       const hasToolCalls = hasRemoteToolCalls(responseMessages);
 
-      if (hasToolCalls && context.toolExecutor) {
+      if (hasToolCalls && context.toolExecutor && !sawError) {
+        if (iterations >= maxRuns) {
+          // The limit stops the loop with the server thread still waiting for tool results.
+          // Say so in the stream instead of ending as if the run were complete.
+          if (context.debug) {
+            console.warn(`TenxGraphClient: Recursion limit of ${recursion_limit} reached`);
+          }
+          yield {
+            event: StreamEventType.ERROR,
+            data: {
+              recursion_limit_reached: true,
+              message: `Recursion limit of ${recursion_limit} reached with tool calls still pending`,
+            },
+            thread_id: config?.thread_id,
+          };
+          break;
+        }
+
         if (context.debug) {
           console.debug('TenxGraphClient: Found remote tool calls, executing...');
         }
@@ -363,22 +484,23 @@ export async function* streamInvoke(
         break;
       }
     } catch (error) {
-      clearTimeout(timeoutId);
-
       if ((error as Error).name === 'AbortError') {
+        if (context.signal?.aborted) {
+          // Cancelled by the caller, not a timeout: surface the abort as is.
+          throw error;
+        }
         console.warn(`TenxGraphClient: Stream timeout after ${context.timeout}ms`);
-        throw new Error(`Request timeout after ${context.timeout}ms`);
+        throw new RequestTimeoutError(context.timeout, STREAM_ENDPOINT, 'POST', error);
       }
 
       console.error('TenxGraphClient: Stream failed:', error);
       throw error;
-    }
-  }
-
-  // Check if we hit the recursion limit
-  if (iterations >= recursion_limit) {
-    if (context.debug) {
-      console.warn(`TenxGraphClient: Recursion limit of ${recursion_limit} reached`);
+    } finally {
+      disarm();
+      unlink();
+      // Early exit (the caller broke out of the loop, or an error): cancel the request so
+      // the connection closes and the server run releases its thread lock.
+      if (!finished) controller.abort();
     }
   }
 
@@ -388,7 +510,7 @@ export async function* streamInvoke(
 }
 
 /**
- * Clean content blocks by removing empty arrays and undefined values
+ * Clean content blocks by removing undefined values (empty arrays are kept)
  * Server requires array of content blocks, not simplified string
  */
 function cleanContent(content: any[]): any[] {
@@ -397,11 +519,7 @@ function cleanContent(content: any[]): any[] {
     const cleaned: any = {};
 
     for (const [key, value] of Object.entries(block)) {
-      // Skip empty arrays
-      if (Array.isArray(value) && value.length === 0) {
-        continue;
-      }
-      // Skip undefined values
+      // Skip undefined values (empty arrays are real data, e.g. a tool result of [])
       if (value === undefined) {
         continue;
       }

package/src/endpoints/threadDetails.ts

@@ -1,6 +1,12 @@
 import { ResponseMetadata } from './metadata.js';
 import { createErrorFromResponse } from '../errors.js';
-import { buildHeaders, getRequestCredentials, RequestContext } from '../request.js';
+import {
+  buildHeaders,
+  getRequestCredentials,
+  RequestContext,
+  fetchWithTimeout,
+  encodePathSegment,
+} from '../request.js';
 
 export interface ThreadDetailsContext extends RequestContext {}
 
@@ -28,23 +34,17 @@ export async function threadDetails(
       console.debug(`TenxGraphClient: Fetching thread details for thread ${threadId}`);
     }
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), context.timeout);
+    const url = `${context.baseUrl}/v1/threads/${encodePathSegment(threadId)}`;
 
-    const url = `${context.baseUrl}/v1/threads/${threadId}`;
-
-    const response = await fetch(url, {
+    const response = await fetchWithTimeout(context, url, {
       method: 'GET',
       headers: buildHeaders(context as RequestContext, {
         'Content-Type': 'application/json',
         accept: 'application/json',
       }),
       ...getRequestCredentials(context as RequestContext),
-      signal: controller.signal,
     });
 
-    clearTimeout(timeoutId);
-
     if (!response.ok) {
       console.warn(`TenxGraphClient: Thread details fetch failed with HTTP ${response.status}`);
       const error = await createErrorFromResponse(
@@ -64,11 +64,6 @@ export async function threadDetails(
 
     return data;
   } catch (error) {
-    if ((error as Error).name === 'AbortError') {
-      console.warn(`TenxGraphClient: Thread details fetch timeout after ${context.timeout}ms`);
-      throw new Error(`Request timeout after ${context.timeout}ms`);
-    }
-
     if (context.debug) {
       console.debug('TenxGraphClient: Thread details fetch failed:', error);
     }

package/src/endpoints/threadMessage.ts

@@ -1,7 +1,13 @@
 import { ResponseMetadata } from './metadata.js';
 import { Message } from '../message.js';
 import { createErrorFromResponse } from '../errors.js';
-import { buildHeaders, getRequestCredentials, RequestContext } from '../request.js';
+import {
+  buildHeaders,
+  getRequestCredentials,
+  RequestContext,
+  fetchWithTimeout,
+  encodePathSegment,
+} from '../request.js';
 
 export interface ThreadMessageContext extends RequestContext {}
 
@@ -33,22 +39,16 @@ export async function threadMessage(
       );
     }
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), context.timeout);
+    const url = `${context.baseUrl}/v1/threads/${encodePathSegment(request.threadId)}/messages/${encodePathSegment(request.messageId)}`;
 
-    const url = `${context.baseUrl}/v1/threads/${request.threadId}/messages/${request.messageId}`;
-
-    const response = await fetch(url, {
+    const response = await fetchWithTimeout(context, url, {
       method: 'GET',
       headers: buildHeaders(context as RequestContext, {
         'Content-Type': 'application/json',
       }),
       ...getRequestCredentials(context as RequestContext),
-      signal: controller.signal,
     });
 
-    clearTimeout(timeoutId);
-
     if (!response.ok) {
       console.warn(`TenxGraphClient: Thread message fetch failed with HTTP ${response.status}`);
       const error = await createErrorFromResponse(

package/src/endpoints/threadMessages.ts

@@ -1,7 +1,13 @@
 import { ResponseMetadata } from './metadata.js';
 import { Message } from '../message.js';
 import { createErrorFromResponse } from '../errors.js';
-import { buildHeaders, getRequestCredentials, RequestContext } from '../request.js';
+import {
+  buildHeaders,
+  getRequestCredentials,
+  RequestContext,
+  fetchWithTimeout,
+  encodePathSegment,
+} from '../request.js';
 
 export interface ThreadMessagesContext extends RequestContext {}
 
@@ -14,6 +20,12 @@ export interface ThreadMessagesRequest {
 
 export interface ThreadMessagesData {
   messages: Message[];
+  /** True when more messages exist after this page. Absent on servers older than 1.0.0. */
+  has_more?: boolean;
+  /** Offset the server applied. */
+  offset?: number;
+  /** Limit the server applied (after its default and maximum clamp). */
+  limit?: number;
 }
 
 // Backward compatibility alias
@@ -36,9 +48,6 @@ export async function threadMessages(
       console.debug('TenxGraphClient: Fetching thread messages for thread', request.threadId);
     }
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), context.timeout);
-
     // Build query parameters
     const params = new URLSearchParams();
     if (request.search !== undefined) {
@@ -52,19 +61,16 @@ export async function threadMessages(
     }
 
     const queryString = params.toString();
-    const url = `${context.baseUrl}/v1/threads/${request.threadId}/messages${queryString ? '?' + queryString : ''}`;
+    const url = `${context.baseUrl}/v1/threads/${encodePathSegment(request.threadId)}/messages${queryString ? '?' + queryString : ''}`;
 
-    const response = await fetch(url, {
+    const response = await fetchWithTimeout(context, url, {
       method: 'GET',
       headers: buildHeaders(context as RequestContext, {
         'Content-Type': 'application/json',
       }),
       ...getRequestCredentials(context as RequestContext),
-      signal: controller.signal,
     });
 
-    clearTimeout(timeoutId);
-
     if (!response.ok) {
       console.warn(
         `TenxGraphClient: Checkpoint messages fetch failed with HTTP ${response.status}`

package/src/endpoints/threadState.ts

@@ -1,7 +1,13 @@
 import { ResponseMetadata } from './metadata.js';
 import { AgentState } from '../agent.js';
 import { createErrorFromResponse } from '../errors.js';
-import { buildHeaders, getRequestCredentials, RequestContext } from '../request.js';
+import {
+  buildHeaders,
+  getRequestCredentials,
+  RequestContext,
+  fetchWithTimeout,
+  encodePathSegment,
+} from '../request.js';
 
 export interface ThreadStateContext extends RequestContext {}
 
@@ -23,20 +29,18 @@ export async function threadState(
       console.debug(`TenxGraphClient: Fetching thread state for thread ${threadId}`);
     }
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), context.timeout);
-
-    const response = await fetch(`${context.baseUrl}/v1/threads/${threadId}/state`, {
-      method: 'GET',
-      headers: buildHeaders(context as RequestContext, {
-        'Content-Type': 'application/json',
-        accept: 'application/json',
-      }),
-      ...getRequestCredentials(context as RequestContext),
-      signal: controller.signal,
-    });
-
-    clearTimeout(timeoutId);
+    const response = await fetchWithTimeout(
+      context,
+      `${context.baseUrl}/v1/threads/${encodePathSegment(threadId)}/state`,
+      {
+        method: 'GET',
+        headers: buildHeaders(context as RequestContext, {
+          'Content-Type': 'application/json',
+          accept: 'application/json',
+        }),
+        ...getRequestCredentials(context as RequestContext),
+      }
+    );
 
     if (!response.ok) {
       console.warn(`TenxGraphClient: Thread state fetch failed with HTTP ${response.status}`);
@@ -60,11 +64,6 @@ export async function threadState(
 
     return data;
   } catch (error) {
-    if ((error as Error).name === 'AbortError') {
-      console.warn(`TenxGraphClient: Thread state fetch timeout after ${context.timeout}ms`);
-      throw new Error(`Request timeout after ${context.timeout}ms`);
-    }
-
     if (context.debug) {
       console.debug(`TenxGraphClient: Thread state fetch failed:`, error);
     }

package/src/endpoints/threads.ts

@@ -1,6 +1,11 @@
 import { ResponseMetadata } from './metadata.js';
 import { createErrorFromResponse } from '../errors.js';
-import { buildHeaders, getRequestCredentials, RequestContext } from '../request.js';
+import {
+  buildHeaders,
+  getRequestCredentials,
+  RequestContext,
+  fetchWithTimeout,
+} from '../request.js';
 
 export interface ThreadsContext extends RequestContext {}
 
@@ -21,6 +26,12 @@ export interface ThreadItem {
 
 export interface ThreadsData {
   threads: ThreadItem[];
+  /** True when more threads exist after this page. Absent on servers older than 1.0.0. */
+  has_more?: boolean;
+  /** Offset the server applied. */
+  offset?: number;
+  /** Limit the server applied (after its default and maximum clamp). */
+  limit?: number;
 }
 
 export interface ThreadsResponse {
@@ -50,9 +61,6 @@ export async function threads(
       }
     }
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), context.timeout);
-
     // Build query parameters
     const params = new URLSearchParams();
     if (request?.search) {
@@ -68,18 +76,15 @@ export async function threads(
     const queryString = params.toString();
     const url = `${context.baseUrl}/v1/threads${queryString ? `?${queryString}` : ''}`;
 
-    const response = await fetch(url, {
+    const response = await fetchWithTimeout(context, url, {
       method: 'GET',
       headers: buildHeaders(context as RequestContext, {
         'Content-Type': 'application/json',
         accept: 'application/json',
       }),
       ...getRequestCredentials(context as RequestContext),
-      signal: controller.signal,
     });
 
-    clearTimeout(timeoutId);
-
     if (!response.ok) {
       console.warn(`TenxGraphClient: Threads list fetch failed with HTTP ${response.status}`);
       const error = await createErrorFromResponse(
@@ -100,10 +105,6 @@ export async function threads(
 
     return data;
   } catch (error) {
-    if ((error as Error).name === 'AbortError') {
-      console.warn(`TenxGraphClient: Threads list fetch timeout after ${context.timeout}ms`);
-      throw new Error(`Request timeout after ${context.timeout}ms`);
-    }
     if (context.debug) {
       console.debug('TenxGraphClient: Threads list fetch failed:', error);
     }