10xgraph-client 0.6.0 → 1.0.0-rc.2

package/src/endpoints/updateMemory.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 UpdateMemoryContext extends RequestContext {}
 
@@ -31,10 +37,7 @@ export async function updateMemory(
       console.debug('TenxGraphClient: Updating memory with ID:', request.memoryId);
     }
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), context.timeout);
-
-    const url = `${context.baseUrl}/v1/store/memories/${request.memoryId}`;
+    const url = `${context.baseUrl}/v1/store/memories/${encodePathSegment(request.memoryId)}`;
 
     // Prepare request body
     const body = {
@@ -48,18 +51,15 @@ export async function updateMemory(
       console.debug('TenxGraphClient: Request payload:', JSON.stringify(body, null, 2));
     }
 
-    const response = await fetch(url, {
+    const response = await fetchWithTimeout(context, url, {
       method: 'PUT',
       headers: buildHeaders(context as RequestContext, {
         'Content-Type': 'application/json',
       }),
       ...getRequestCredentials(context as RequestContext),
       body: JSON.stringify(body),
-      signal: controller.signal,
     });
 
-    clearTimeout(timeoutId);
-
     if (!response.ok) {
       console.warn(`TenxGraphClient: Update memory failed with HTTP ${response.status}`);
       const error = await createErrorFromResponse(

package/src/endpoints/updateThreadMessageFeedback.ts

@@ -0,0 +1,80 @@
+import { ResponseMetadata } from './metadata.js';
+import { ThreadMessageData } from './threadMessage.js';
+import { createErrorFromResponse } from '../errors.js';
+import {
+  buildHeaders,
+  getRequestCredentials,
+  RequestContext,
+  fetchWithTimeout,
+  encodePathSegment,
+} from '../request.js';
+
+export interface UpdateThreadMessageFeedbackContext extends RequestContext {}
+
+export interface UpdateThreadMessageFeedbackRequest {
+  threadId: string | number;
+  messageId: string;
+  /**
+   * Any JSON object. Replaces `message.metadata.feedback`. The server rejects
+   * feedback larger than 8192 serialized bytes or nested deeper than 10 levels (HTTP 422).
+   */
+  feedback: Record<string, unknown>;
+}
+
+export interface UpdateThreadMessageFeedbackResponse {
+  data: ThreadMessageData;
+  metadata: ResponseMetadata;
+}
+
+export async function updateThreadMessageFeedback(
+  context: UpdateThreadMessageFeedbackContext,
+  request: UpdateThreadMessageFeedbackRequest
+): Promise<UpdateThreadMessageFeedbackResponse> {
+  try {
+    if (context.debug) {
+      console.debug(
+        'TenxGraphClient: Updating thread message feedback',
+        `thread: ${request.threadId}`,
+        `message: ${request.messageId}`
+      );
+    }
+
+    const url = `${context.baseUrl}/v1/threads/${encodePathSegment(request.threadId)}/messages/${encodePathSegment(request.messageId)}`;
+
+    const response = await fetchWithTimeout(context, url, {
+      method: 'PUT',
+      headers: buildHeaders(context as RequestContext, {
+        'Content-Type': 'application/json',
+        accept: 'application/json',
+      }),
+      ...getRequestCredentials(context as RequestContext),
+      body: JSON.stringify({ feedback: request.feedback }),
+    });
+
+    if (!response.ok) {
+      console.warn(
+        `TenxGraphClient: Update thread message feedback failed with HTTP ${response.status}`
+      );
+      const error = await createErrorFromResponse(
+        response,
+        'Update thread message feedback failed',
+        '/v1/threads/{thread_id}/messages/{message_id}',
+        'PUT'
+      );
+      throw error;
+    }
+
+    const data: UpdateThreadMessageFeedbackResponse = await response.json();
+
+    if (context.debug) {
+      console.info('TenxGraphClient: Thread message feedback updated successfully', data);
+    }
+
+    return data;
+  } catch (error) {
+    if (context.debug) {
+      console.debug('TenxGraphClient: Update thread message feedback failed:', error);
+    }
+    throw error;
+  }
+}

package/src/endpoints/updateThreadState.ts

@@ -1,13 +1,26 @@
 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 UpdateThreadStateContext extends RequestContext {}
 
+/**
+ * State fields the server accepts on update. `context_summary` and `execution_meta` are
+ * rejected by the server, so they are not part of this type.
+ */
+export type UpdatableThreadState = Partial<Omit<AgentState, 'context_summary' | 'execution_meta'>> &
+  Record<string, any>;
+
 export interface UpdateThreadStateRequest {
   config: Record<string, any>;
-  state: AgentState;
+  state: UpdatableThreadState;
 }
 
 export interface UpdateThreadStateData {
@@ -30,21 +43,19 @@ export async function updateThreadState(
       console.debug(`TenxGraphClient: Request payload:`, JSON.stringify(request, null, 2));
     }
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), context.timeout);
-
-    const response = await fetch(`${context.baseUrl}/v1/threads/${threadId}/state`, {
-      method: 'PUT',
-      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);
+    const response = await fetchWithTimeout(
+      context,
+      `${context.baseUrl}/v1/threads/${encodePathSegment(threadId)}/state`,
+      {
+        method: 'PUT',
+        headers: buildHeaders(context as RequestContext, {
+          'Content-Type': 'application/json',
+          accept: 'application/json',
+        }),
+        ...getRequestCredentials(context as RequestContext),
+        body: JSON.stringify(request),
+      }
+    );
 
     if (!response.ok) {
       console.warn(`TenxGraphClient: Thread state update failed with HTTP ${response.status}`);
@@ -68,11 +79,6 @@ export async function updateThreadState(
 
     return data;
   } catch (error) {
-    if ((error as Error).name === 'AbortError') {
-      console.warn(`TenxGraphClient: Thread state update timeout after ${context.timeout}ms`);
-      throw new Error(`Request timeout after ${context.timeout}ms`);
-    }
-
     if (context.debug) {
       console.debug(`TenxGraphClient: Thread state update failed:`, error);
     }

package/src/endpoints/wsStream.ts

@@ -2,6 +2,7 @@ import { Message } from '../message.js';
 import { ToolExecutor } from '../tools.js';
 import { RequestContext } from '../request.js';
 import { buildWsUrl, openWebSocket } from '../ws.js';
+import { RequestTimeoutError, StreamError, WebSocketError } from '../errors.js';
 import { StreamChunk, StreamEventType, StreamRequest, serializeMessage } from './stream.js';
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -10,6 +11,8 @@ import { StreamChunk, StreamEventType, StreamRequest, serializeMessage } from '.
 
 export interface WsStreamContext extends RequestContext {
   toolExecutor?: ToolExecutor;
+  /** Caller-supplied signal; aborting it closes the socket and ends the stream. */
+  signal?: AbortSignal;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -23,9 +26,17 @@ interface WsGraphInput {
   initial_state?: Record<string, any>;
   config?: Record<string, any>;
   recursion_limit?: number;
+  on_busy?: 'wait' | 'cancel';
+  resume?: unknown;
+  interrupt_id?: string;
   response_granularity?: string;
 }
 
+const WS_ENDPOINT = '/v1/graph/ws';
+
+/** What the socket listeners hand to the generator. */
+type QueueItem = StreamChunk | Error | { closed: true; code: number };
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Helpers
 // ─────────────────────────────────────────────────────────────────────────────
@@ -70,21 +81,28 @@ export async function* wsStreamInvoke(
   context: WsStreamContext,
   request: StreamRequest
 ): AsyncGenerator<StreamChunk, void, unknown> {
-  const url = buildWsUrl(context, '/v1/graph/ws');
+  context.signal?.throwIfAborted();
+  const url = buildWsUrl(context, WS_ENDPOINT);
 
   if (context.debug) {
     console.debug('TenxGraphClient [WS]: connecting to', url);
   }
 
   const ws = openWebSocket(url, context);
+  const recursion_limit = request.recursion_limit ?? 25;
+  // At least one run is always sent; the limit caps tool resumes after that.
+  const maxRuns = Math.max(1, recursion_limit);
+  // The timeout is an idle timeout: it applies while waiting for the socket to open and
+  // while waiting for the next frame, never while the caller processes a chunk.
+  const idleMs = context.timeout > 0 ? context.timeout : 0;
 
   // ── Queue bridge ──────────────────────────────────────────────────────────
   // WebSocket is event-based; async generators are pull-based.
   // We buffer incoming items in a queue and wake up the generator each time.
-  const queue: Array<StreamChunk | Error | 'close'> = [];
+  const queue: QueueItem[] = [];
   let wakeUp: (() => void) | null = null;
 
-  const enqueue = (item: StreamChunk | Error | 'close'): void => {
+  const enqueue = (item: QueueItem): void => {
     queue.push(item);
     if (wakeUp) {
       const fn = wakeUp;
@@ -102,60 +120,140 @@ export async function* wsStreamInvoke(
       }
     });
 
+  /** Next queued item, or a timeout error item when nothing arrives within the idle window. */
+  const nextItem = async (): Promise<QueueItem> => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    if (idleMs > 0) {
+      timer = setTimeout(() => enqueue(new RequestTimeoutError(idleMs, WS_ENDPOINT, 'WS')), idleMs);
+    }
+    try {
+      await waitForItem();
+    } finally {
+      if (timer !== undefined) clearTimeout(timer);
+    }
+    return queue.shift()!;
+  };
+
   ws.addEventListener('message', (event: MessageEvent) => {
     try {
       const chunk = JSON.parse(event.data as string) as StreamChunk;
       enqueue(chunk);
     } catch (e) {
-      if (context.debug) {
-        console.warn('TenxGraphClient [WS]: failed to parse chunk:', e);
-      }
+      // A frame that is not JSON means the stream is corrupt; do not skip it silently.
+      enqueue(
+        new StreamError(
+          'WebSocket frame could not be parsed as JSON',
+          'STREAM_TRUNCATED',
+          'unknown',
+          WS_ENDPOINT,
+          'WS',
+          e
+        )
+      );
     }
   });
 
   ws.addEventListener('error', () => {
-    enqueue(new Error('WebSocket error'));
+    enqueue(new WebSocketError('WebSocket error', undefined, WS_ENDPOINT));
   });
 
   ws.addEventListener('close', (event: CloseEvent) => {
     if (context.debug) {
       console.debug('TenxGraphClient [WS]: connection closed, code=', event.code);
     }
-    enqueue('close');
+    enqueue({ closed: true, code: event.code });
   });
 
-  // Wait for the connection to open (or fail)
-  await new Promise<void>((resolve, reject) => {
-    // Numeric readyState literals (OPEN===1) instead of WebSocket.OPEN: the
-    // global WebSocket may be absent on Node < 21 when a custom impl is injected.
-    if (ws.readyState === 1) {
-      resolve();
-      return;
+  const makeAbortError = (): Error => {
+    const err = new Error('The operation was aborted');
+    err.name = 'AbortError';
+    return err;
+  };
+  const onAbort = (): void => {
+    enqueue(makeAbortError());
+    if (ws.readyState === 1 || ws.readyState === 0) {
+      ws.close(1000);
     }
-    ws.addEventListener('open', () => resolve(), { once: true });
-    ws.addEventListener('error', () => reject(new Error('WebSocket connection failed')), {
-      once: true,
-    });
-  });
+  };
+  context.signal?.addEventListener('abort', onAbort, { once: true });
 
-  if (context.debug) {
-    console.debug('TenxGraphClient [WS]: connected');
-  }
+  try {
+    // Wait for the connection to open (or fail). Every listener added here is removed again,
+    // whichever way the wait ends.
+    await new Promise<void>((resolve, reject) => {
+      if (context.signal?.aborted) {
+        reject(makeAbortError());
+        return;
+      }
+      // Numeric readyState literals (OPEN===1) instead of WebSocket.OPEN: the
+      // global WebSocket may be absent on Node < 22 when a custom impl is injected.
+      if (ws.readyState === 1) {
+        resolve();
+        return;
+      }
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const cleanup = (): void => {
+        if (timer !== undefined) clearTimeout(timer);
+        ws.removeEventListener('open', onOpen);
+        ws.removeEventListener('error', onError);
+        ws.removeEventListener('close', onClose);
+        context.signal?.removeEventListener('abort', onConnectAbort);
+      };
+      const onOpen = (): void => {
+        cleanup();
+        resolve();
+      };
+      const onError = (): void => {
+        cleanup();
+        reject(new WebSocketError('WebSocket connection failed', undefined, WS_ENDPOINT));
+      };
+      const onClose = (e: Event): void => {
+        cleanup();
+        const code = (e as CloseEvent)?.code;
+        reject(
+          new WebSocketError(`WebSocket closed before it opened (code ${code})`, code, WS_ENDPOINT)
+        );
+      };
+      const onConnectAbort = (): void => {
+        cleanup();
+        reject(makeAbortError());
+      };
+      ws.addEventListener('open', onOpen);
+      ws.addEventListener('error', onError);
+      ws.addEventListener('close', onClose);
+      context.signal?.addEventListener('abort', onConnectAbort, { once: true });
+      if (idleMs > 0) {
+        timer = setTimeout(() => {
+          cleanup();
+          reject(new RequestTimeoutError(idleMs, WS_ENDPOINT, 'WS'));
+        }, idleMs);
+      }
+    });
+    // Anything queued while connecting (an error event that raced the open) is stale.
+    queue.length = 0;
 
-  // ── Main loop ─────────────────────────────────────────────────────────────
-  let threadId: string | undefined = (request.config as Record<string, any>)?.thread_id;
+    if (context.debug) {
+      console.debug('TenxGraphClient [WS]: connected');
+    }
 
-  let nextPayload: WsGraphInput = {
-    invoke_type: 'fresh',
-    messages: request.messages,
-    initial_state: request.initial_state,
-    config: request.config,
-    recursion_limit: request.recursion_limit ?? 25,
-    response_granularity: request.response_granularity,
-  };
+    // ── Main loop ───────────────────────────────────────────────────────────
+    let threadId: string | undefined = (request.config as Record<string, any>)?.thread_id;
+    let runs = 0;
+
+    let nextPayload: WsGraphInput = {
+      invoke_type: 'fresh',
+      messages: request.messages,
+      initial_state: request.initial_state,
+      config: request.config,
+      recursion_limit,
+      on_busy: request.on_busy,
+      resume: request.resume,
+      interrupt_id: request.interrupt_id,
+      response_granularity: request.response_granularity,
+    };
 
-  try {
     outerLoop: while (true) {
+      runs++;
       if (context.debug) {
         console.debug(
           `TenxGraphClient [WS]: sending ${nextPayload.invoke_type} request, thread_id=${threadId ?? 'new'}`
@@ -168,12 +266,16 @@ export async function* wsStreamInvoke(
       const runMessages: Message[] = [];
 
       innerLoop: while (true) {
-        await waitForItem();
-        const item = queue.shift()!;
-
-        if (item === 'close') {
-          // Server closed the connection unexpectedly
-          break outerLoop;
+        const item = await nextItem();
+
+        if ('closed' in item) {
+          // The server closed the socket before it finished the run (1012 restart,
+          // 1013 busy, 1008 policy, 1011 error ...). Never report that as success.
+          throw new WebSocketError(
+            `WebSocket closed before the run finished (code ${item.code})`,
+            item.code,
+            WS_ENDPOINT
+          );
         }
 
         if (item instanceof Error) {
@@ -202,6 +304,12 @@ export async function* wsStreamInvoke(
 
         // Yield every chunk to the caller (same as HTTP stream)
         yield chunk;
+
+        // The server sends no "done" after an error chunk (busy thread, rate limit, not
+        // authorized, shutdown cut with data.interrupted). The error ends the run.
+        if (chunk.event === StreamEventType.ERROR) {
+          break outerLoop;
+        }
       }
 
       if (context.debug) {
@@ -212,6 +320,21 @@ export async function* wsStreamInvoke(
 
       // ── Tool-call detection & resume ──────────────────────────────────
       if (hasRemoteToolCalls(runMessages) && context.toolExecutor) {
+        if (runs >= maxRuns) {
+          if (context.debug) {
+            console.warn(`TenxGraphClient [WS]: 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: threadId,
+          };
+          break outerLoop;
+        }
+
         if (context.debug) {
           console.debug('TenxGraphClient [WS]: remote tool calls detected, executing…');
         }
@@ -228,7 +351,8 @@ export async function* wsStreamInvoke(
           invoke_type: 'resume',
           tool_result: toolResults.map(serializeMessage),
           config: { ...(request.config ?? {}), thread_id: threadId },
-          recursion_limit: request.recursion_limit ?? 25,
+          recursion_limit,
+          on_busy: request.on_busy,
           response_granularity: request.response_granularity,
         };
         // continue outerLoop → send resume request
@@ -238,8 +362,9 @@ export async function* wsStreamInvoke(
       }
     }
   } finally {
+    context.signal?.removeEventListener('abort', onAbort);
     // CONNECTING===0, OPEN===1 (numeric literals; the global WebSocket may be
-    // absent on Node < 21 when a custom impl is injected).
+    // absent on Node < 22 when a custom impl is injected).
     if (ws.readyState === 1 || ws.readyState === 0) {
       ws.close(1000);
     }