10xgraph-client 0.6.0 → 1.0.0-rc.2

package/src/endpoints/graphTools.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 GraphToolsContext extends RequestContext {}
 
@@ -41,21 +46,15 @@ export async function graphTools(context: GraphToolsContext): Promise<GraphTools
       console.debug('TenxGraphClient: Fetching graph tools from', context.baseUrl);
     }
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), context.timeout);
-
-    const response = await fetch(`${context.baseUrl}/v1/graph/tools`, {
+    const response = await fetchWithTimeout(context, `${context.baseUrl}/v1/graph/tools`, {
       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: Graph tools fetch failed with HTTP ${response.status}`);
       const error = await createErrorFromResponse(
@@ -79,11 +78,6 @@ export async function graphTools(context: GraphToolsContext): Promise<GraphTools
       console.debug('TenxGraphClient: Graph tools fetch failed:', error);
     }
 
-    if ((error as Error).name === 'AbortError') {
-      console.warn(`TenxGraphClient: Graph tools fetch timeout after ${context.timeout}ms`);
-      throw new Error(`Request timeout after ${context.timeout}ms`);
-    }
-
     console.error('TenxGraphClient: Graph tools fetch failed:', error);
     throw error;
   }

package/src/endpoints/invoke.ts

@@ -1,11 +1,24 @@
 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 { serializeMessage } from './stream.js';
+import {
+  buildHeaders,
+  getRequestCredentials,
+  linkAbortSignal,
+  RequestContext,
+} from '../request.js';
 
 export interface InvokeContext extends RequestContext {
   toolExecutor?: ToolExecutor;
+  /** Caller-supplied signal; aborting it cancels the in-flight request. */
+  signal?: AbortSignal;
 }
 
 // Invoke Request payload
@@ -14,6 +27,12 @@ export interface InvokeRequest {
   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';
 }
 
@@ -74,45 +93,78 @@ async function makeSingleInvokeCall(
   request: InvokeRequest
 ): Promise<InvokeResponse> {
   const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), context.timeout);
+  // The timeout and the caller's signal stay armed until the body is read, so a server that
+  // sends headers and then stalls is cut off too. A timeout of 0 means no timeout.
+  const timeoutId =
+    context.timeout > 0 ? setTimeout(() => controller.abort(), context.timeout) : undefined;
+  const unlink = linkAbortSignal(controller, context.signal);
 
   try {
-    const response = await fetch(`${context.baseUrl}/v1/graph/invoke`, {
-      method: 'POST',
-      headers: buildHeaders(context as RequestContext, {
-        'Content-Type': 'application/json',
-        accept: 'application/json',
-      }),
-      ...getRequestCredentials(context as RequestContext),
-      body: JSON.stringify(request),
-      signal: controller.signal,
-    });
-
-    clearTimeout(timeoutId);
+    let response: Response;
+    try {
+      response = await fetch(`${context.baseUrl}/v1/graph/invoke`, {
+        method: 'POST',
+        headers: buildHeaders(context as RequestContext, {
+          'Content-Type': 'application/json',
+          accept: 'application/json',
+        }),
+        ...getRequestCredentials(context as RequestContext),
+        body: JSON.stringify(request),
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if (error instanceof TypeError) {
+        throw new NetworkError(
+          `Network error: ${error.message}`,
+          '/v1/graph/invoke',
+          'POST',
+          error
+        );
+      }
+      throw error;
+    }
 
     if (!response.ok) {
       console.warn(`TenxGraphClient: Invoke failed with HTTP ${response.status}`);
       const error = await createErrorFromResponse(
         response,
         'Invoke request failed',
-        '/v1/invoke',
+        '/v1/graph/invoke',
         'POST'
       );
       throw error;
     }
 
     const data: InvokeResponse = await response.json();
+    // A body without `data` (or without `messages`) must not crash the tool loop later.
+    if (!data || typeof data !== 'object' || !data.data || typeof data.data !== 'object') {
+      throw new StreamError(
+        'Invoke response had no data object',
+        'INVALID_RESPONSE',
+        'unknown',
+        '/v1/graph/invoke',
+        'POST'
+      );
+    }
+    if (!Array.isArray(data.data.messages)) {
+      data.data.messages = [];
+    }
     return data;
   } 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: Invoke timeout after ${context.timeout}ms`);
-      throw new Error(`Request timeout after ${context.timeout}ms`);
+      throw new RequestTimeoutError(context.timeout, '/v1/graph/invoke', 'POST', error);
     }
 
     console.error('TenxGraphClient: Invoke failed:', error);
     throw error;
+  } finally {
+    if (timeoutId !== undefined) clearTimeout(timeoutId);
+    unlink();
   }
 }
 
@@ -137,7 +189,9 @@ export async function invoke(
   request: InvokeRequest,
   onPartialResult?: InvokeCallback
 ): Promise<InvokeResult> {
-  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);
 
   if (context.debug) {
     console.debug('TenxGraphClient: Starting invoke with recursion_limit:', recursion_limit);
@@ -151,15 +205,20 @@ export async function invoke(
   let recursionLimitReached = false;
   let lastResponse: InvokeResponse | undefined;
   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
-  while (iterations < recursion_limit) {
+  while (true) {
+    context.signal?.throwIfAborted();
     iterations++;
 
     if (context.debug) {
-      console.debug(`TenxGraphClient: Iteration ${iterations}/${recursion_limit}`);
+      console.debug(`TenxGraphClient: Iteration ${iterations}/${maxRuns}`);
     }
 
     // Prepare request for this iteration
@@ -168,6 +227,9 @@ export async function invoke(
       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,
     };
 
@@ -179,6 +241,13 @@ export async function invoke(
     const response = await makeSingleInvokeCall(context, iterationRequest);
     lastResponse = response;
 
+    // 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 = response.data.meta?.thread_id;
+    if (returnedThreadId && !config?.thread_id) {
+      config = { ...(config ?? {}), thread_id: returnedThreadId };
+    }
+
     if (context.debug) {
       console.info('TenxGraphClient: Invoke successful');
       console.debug('TenxGraphClient: Response:', JSON.stringify(response, null, 2));
@@ -192,6 +261,9 @@ export async function invoke(
     // Check if there are remote tool calls to execute
     const hasToolCalls = hasRemoteToolCalls(response);
 
+    // A tool round trip follows only while there is an executor and room under the limit
+    const willContinue = hasToolCalls && !!context.toolExecutor && iterations < maxRuns;
+
     // Send partial result immediately if callback provided
     if (onPartialResult) {
       const partialResult: InvokePartialResult = {
@@ -202,12 +274,21 @@ export async function invoke(
         summary: response.data.summary,
         meta: response.data.meta,
         has_tool_calls: hasToolCalls,
-        is_final: !hasToolCalls,
+        is_final: !willContinue,
       };
 
       await onPartialResult(partialResult);
     }
 
+    if (hasToolCalls && context.toolExecutor && iterations >= maxRuns) {
+      // The limit stopped a loop that still wanted tools: the server thread is left waiting
+      recursionLimitReached = true;
+      if (context.debug) {
+        console.warn(`TenxGraphClient: Recursion limit of ${recursion_limit} reached`);
+      }
+      break;
+    }
+
     if (hasToolCalls && context.toolExecutor) {
       if (context.debug) {
         console.debug('TenxGraphClient: Found remote tool calls, executing...');
@@ -237,14 +318,6 @@ export async function invoke(
     }
   }
 
-  // Check if we hit the recursion limit
-  if (iterations >= recursion_limit) {
-    recursionLimitReached = true;
-    if (context.debug) {
-      console.warn(`TenxGraphClient: Recursion limit of ${recursion_limit} reached`);
-    }
-  }
-
   // Construct the result
   const result: InvokeResult = {
     messages: lastResponse?.data.messages || [],
@@ -264,55 +337,3 @@ export async function invoke(
 
   return result;
 }
-
-/**
- * Clean content blocks by removing empty arrays and undefined values
- * Server requires array of content blocks
- */
-function cleanContent(content: any[]): any[] {
-  // Always return as array of blocks (server requires this format)
-  return content.map((block) => {
-    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
-      if (value === undefined) {
-        continue;
-      }
-      cleaned[key] = value;
-    }
-
-    return cleaned;
-  });
-}
-
-/**
- * Serialize a Message object for API transmission
- */
-function serializeMessage(message: Message): any {
-  const serialized: any = {
-    role: message.role,
-    content: cleanContent(message.content),
-  };
-
-  // message_id: use "0" if not set (server will generate one)
-  if (message.message_id !== null && message.message_id !== undefined) {
-    serialized.message_id = String(message.message_id);
-  } else {
-    serialized.message_id = '0';
-  }
-
-  // Only include optional fields if they are explicitly set
-  if (message.tools_calls) {
-    serialized.tools_calls = message.tools_calls;
-  }
-  if (message.metadata && Object.keys(message.metadata).length > 0) {
-    serialized.metadata = message.metadata;
-  }
-
-  return serialized;
-}

package/src/endpoints/listMemories.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';
 import { MemoryResult } from './searchMemory.js';
 
 export interface ListMemoriesContext extends RequestContext {}
@@ -9,10 +14,16 @@ export interface ListMemoriesRequest {
   config?: Record<string, any>;
   options?: Record<string, any>;
   limit?: number;
+  /** Memories to skip, for paging. Use `next_offset` from the previous page. Needs 10xgraph-api with paging support. */
+  offset?: number;
 }
 
 export interface ListMemoriesData {
   memories: MemoryResult[];
+  /** True when more memories follow this page. Absent on servers without paging. */
+  has_more?: boolean;
+  /** Offset to request next, or null on the last page. */
+  next_offset?: number | null;
 }
 
 export interface ListMemoriesResponse {
@@ -31,17 +42,18 @@ export async function listMemories(
       });
     }
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), context.timeout);
-
     const url = `${context.baseUrl}/v1/store/memories/list`;
 
     // Prepare request body
-    const body = {
+    // `offset` is sent only when given, so a call without it matches older servers.
+    const body: Record<string, unknown> = {
       config: request.config || {},
       options: request.options || {},
       limit: request.limit || 100,
     };
+    if (request.offset !== undefined) {
+      body.offset = request.offset;
+    }
 
     if (context.debug) {
       console.debug(
@@ -50,7 +62,7 @@ export async function listMemories(
       );
     }
 
-    const response = await fetch(url, {
+    const response = await fetchWithTimeout(context, url, {
       method: 'POST',
       headers: buildHeaders(context as RequestContext, {
         'Content-Type': 'application/json',
@@ -58,11 +70,8 @@ export async function listMemories(
       }),
       ...getRequestCredentials(context as RequestContext),
       body: JSON.stringify(body),
-      signal: controller.signal,
     });
 
-    clearTimeout(timeoutId);
-
     if (!response.ok) {
       console.warn(`TenxGraphClient: List memories failed with HTTP ${response.status}`);
       const error = await createErrorFromResponse(
@@ -85,10 +94,6 @@ export async function listMemories(
 
     return data;
   } catch (error) {
-    if ((error as Error).name === 'AbortError') {
-      console.warn(`TenxGraphClient: List memories timeout after ${context.timeout}ms`);
-      throw new Error(`Request timeout after ${context.timeout}ms`);
-    }
     if (context.debug) {
       console.debug('TenxGraphClient: List memories failed:', error);
     }

package/src/endpoints/observability.ts

@@ -1,9 +1,34 @@
 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 ObservabilityContext extends RequestContext {}
 
+/** Compact view of a complete message seen during a node visit. */
+export interface ObsMessageSummary {
+  role: 'user' | 'assistant' | 'tool' | 'system' | string;
+  text?: string;
+  tool_calls?: Array<{ id: string; name: string }>;
+  tool_results?: Array<{ call_id: string; is_error: boolean }>;
+}
+
+/**
+ * One span in the run tree: `root` > `node` (one per visit) > `llm` and `tool`.
+ * The tree is built from `parent`. Fields marked 1.0.0 are absent on older servers.
+ * Values in `inputs` / `outputs` are clipped at 4000 characters
+ * (a clipped value is a string ending in `...[truncated N chars]`).
+ *
+ * `inputs` / `outputs` by kind:
+ * - root: `{ user_message }` / `{ assistant_message }`
+ * - node: `{ incoming_message }` (approximate) / `{ messages: ObsMessageSummary[] }`
+ * - llm: `null` (the prompt is not recorded) / `{ text?, tool_calls? }`
+ * - tool: `{ args }` / `{ result }`
+ */
 export interface ObsSpan {
   id: string;
   name: string;
@@ -14,6 +39,21 @@ export interface ObsSpan {
   model?: string | null;
   input_tokens?: number | null;
   output_tokens?: number | null;
+  /** ok | error | running. */
+  status?: 'ok' | 'error' | 'running';
+  /** Error text when `status` is `error`. */
+  error?: string | null;
+  inputs?: Record<string, unknown> | null;
+  outputs?: Record<string, unknown> | null;
+  /** Graph step (node spans), else null. */
+  step?: number | null;
+  /** 1-based visit count of this node name (node spans), else null. */
+  visit?: number | null;
+  total_tokens?: number | null;
+  reasoning_tokens?: number | null;
+  /** Tool spans only. */
+  tool_name?: string | null;
+  tool_call_id?: string | null;
 }
 
 export interface ObsEvent {
@@ -43,14 +83,29 @@ export interface ObsRun {
   usage: ObsTokenUsage;
   llm_calls: number;
   tool_calls: number;
+  /** Number of node visits (distinct node names on servers older than 1.0.0). */
   iterations: number;
+  /** First error text seen in the run, else null. */
+  error?: string | null;
+  /** First model seen in the run, else null. */
+  model?: string | null;
+  models?: string[];
+  /** Human-readable limits of this run's trace (may be empty). */
+  notes?: string[];
 }
 
+/** Why `run` is null. */
+export type ObsEmptyReason = 'disabled_in_production' | 'store_unavailable' | 'no_runs';
+
 export interface ObservabilityData {
   thread_id: string;
   run_count: number;
   run_ids: string[];
   run: ObsRun | null;
+  /** False when the local trace store is off (for example MODE=production). */
+  enabled?: boolean;
+  /** Why `run` is null: tracing off, store missing, or no runs captured yet. */
+  reason?: ObsEmptyReason | null;
 }
 
 export interface ObservabilityResponse {
@@ -67,41 +122,29 @@ export async function observability(
   threadId: string,
   runId?: string
 ): Promise<ObservabilityResponse> {
-  try {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), context.timeout);
-
-    const query = runId ? `?run_id=${encodeURIComponent(runId)}` : '';
-    const response = await fetch(
-      `${context.baseUrl}/v1/observability/${encodeURIComponent(threadId)}${query}`,
-      {
-        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) {
-      const error = await createErrorFromResponse(
-        response,
-        'Observability fetch failed',
-        `/v1/observability/${threadId}`,
-        'GET'
-      );
-      throw error;
+  const query = runId ? `?run_id=${encodeURIComponent(runId)}` : '';
+  const response = await fetchWithTimeout(
+    context,
+    `${context.baseUrl}/v1/observability/${encodeURIComponent(threadId)}${query}`,
+    {
+      method: 'GET',
+      headers: buildHeaders(context as RequestContext, {
+        'Content-Type': 'application/json',
+        accept: 'application/json',
+      }),
+      ...getRequestCredentials(context as RequestContext),
     }
+  );
 
-    return (await response.json()) as ObservabilityResponse;
-  } catch (error) {
-    if ((error as Error).name === 'AbortError') {
-      throw new Error(`Request timeout after ${context.timeout}ms`);
-    }
+  if (!response.ok) {
+    const error = await createErrorFromResponse(
+      response,
+      'Observability fetch failed',
+      `/v1/observability/${threadId}`,
+      'GET'
+    );
     throw error;
   }
+
+  return (await response.json()) as ObservabilityResponse;
 }

package/src/endpoints/ping.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 PingContext extends RequestContext {}
 
@@ -15,20 +20,14 @@ export async function ping(context: PingContext): Promise<PingResponse> {
       console.debug('TenxGraphClient: Pinging server at', context.baseUrl);
     }
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), context.timeout);
-
-    const response = await fetch(`${context.baseUrl}/ping`, {
+    const response = await fetchWithTimeout(context, `${context.baseUrl}/ping`, {
       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: Ping failed with HTTP ${response.status}`);
       const error = await createErrorFromResponse(response, 'Ping request failed', '/ping', 'GET');
@@ -47,11 +46,6 @@ export async function ping(context: PingContext): Promise<PingResponse> {
       console.debug('TenxGraphClient: Ping failed:', error);
     }
 
-    if ((error as Error).name === 'AbortError') {
-      console.warn(`TenxGraphClient: Ping timeout after ${context.timeout}ms`);
-      throw new Error(`Request timeout after ${context.timeout}ms`);
-    }
-
     console.error('TenxGraphClient: Ping failed:', error);
     throw error;
   }