10xgraph-client 0.6.0 → 1.0.0-rc.2

package/src/request.ts

@@ -1,4 +1,5 @@
 import type { WebSocketImpl } from './ws.js';
+import { NetworkError, RequestTimeoutError, TenxGraphError } from './errors.js';
 
 export interface TenxGraphBearerAuth {
   type: 'bearer';
@@ -20,6 +21,30 @@ export interface TenxGraphHeaderAuth {
 
 export type TenxGraphAuth = TenxGraphBearerAuth | TenxGraphBasicAuth | TenxGraphHeaderAuth;
 
+/**
+ * Abort `controller` when the caller's `signal` aborts. Returns a cleanup function.
+ * A signal that is already aborted aborts the controller immediately.
+ */
+export function linkAbortSignal(
+  controller: AbortController,
+  signal?: AbortSignal | null
+): () => void {
+  if (!signal) return () => {};
+  if (signal.aborted) {
+    controller.abort();
+    return () => {};
+  }
+  const onAbort = (): void => controller.abort();
+  signal.addEventListener('abort', onAbort, { once: true });
+  return () => signal.removeEventListener('abort', onAbort);
+}
+
+/** Per-call options accepted by every client method that makes a request. */
+export interface RequestOptions {
+  /** Abort to cancel the request. Rejects with the signal's AbortError, never as a timeout. */
+  signal?: AbortSignal;
+}
+
 export interface RequestContext {
   baseUrl: string;
   authToken?: string | null;
@@ -29,6 +54,8 @@ export interface RequestContext {
   timeout: number;
   debug: boolean;
   webSocketImpl?: WebSocketImpl;
+  /** Caller's cancellation signal for this call. Set per call by the client, not stored. */
+  signal?: AbortSignal;
 }
 
 function setHeader(
@@ -166,3 +193,110 @@ export function headerAuth(
 ): TenxGraphHeaderAuth {
   return { type: 'header', name, value, prefix };
 }
+
+/** Percent-encode one URL path segment (thread, message or memory id). */
+export function encodePathSegment(value: string | number): string {
+  return encodeURIComponent(String(value));
+}
+
+/** Strip trailing slashes so `${baseUrl}/path` never produces `//path`. */
+export function normalizeBaseUrl(baseUrl: string): string {
+  // A loop, not /\/+$/: that regex is quadratic on input with many slashes (CodeQL js/polynomial-redos).
+  let end = baseUrl.length;
+  while (end > 0 && baseUrl.charCodeAt(end - 1) === 47 /* '/' */) end--;
+  return baseUrl.slice(0, end);
+}
+
+const MAX_REDIRECTS = 5;
+
+function originOf(url: string): string | null {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+
+function pathOf(url: string): string {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * fetch with the shared client policy:
+ * - the timeout timer is always cleared (also when fetch rejects) and does not keep a Node
+ *   process alive;
+ * - `context.signal` cancels the call (rejects with the AbortError, never as a timeout);
+ * - a timeout throws RequestTimeoutError, any other fetch rejection throws NetworkError
+ *   with the original error as `cause`;
+ * - with header-type credentials other than Authorization (e.g. X-API-Key, which fetch does not
+ *   strip on a redirect)
+ *   redirects are followed only within the same origin; a cross-origin redirect is refused.
+ */
+export async function fetchWithTimeout(
+  context: Pick<RequestContext, 'timeout' | 'signal' | 'auth'>,
+  url: string,
+  init: RequestInit = {}
+): Promise<Response> {
+  const controller = new AbortController();
+  const timer =
+    context.timeout > 0 ? setTimeout(() => controller.abort(), context.timeout) : undefined;
+  (timer as unknown as { unref?: () => void } | undefined)?.unref?.();
+  const unlink = linkAbortSignal(controller, context.signal);
+  const method = (init.method || 'GET').toUpperCase();
+  // fetch strips the standard Authorization header on a cross-origin redirect (checked against
+  // Node's undici), but forwards any other custom header, so only those need the guard.
+  const guardRedirects =
+    context.auth?.type === 'header' && context.auth.name.toLowerCase() !== 'authorization';
+
+  try {
+    let currentUrl = url;
+    let currentInit: RequestInit = { ...init, signal: controller.signal };
+    if (guardRedirects) currentInit.redirect = 'manual';
+
+    for (let hops = 0; ; hops++) {
+      const response = await fetch(currentUrl, currentInit);
+      if (guardRedirects && response.type === 'opaqueredirect') {
+        // Browsers hide the Location of a manual redirect, so it cannot be followed or checked.
+        throw new NetworkError(
+          'The server redirected the request and the browser does not expose the target, so it ' +
+            'was not followed (header credentials must not be sent to another origin). ' +
+            'Point baseUrl at the final URL.',
+          pathOf(url),
+          method
+        );
+      }
+      if (!guardRedirects || !(response.status >= 300 && response.status < 400)) {
+        return response;
+      }
+      const location = response.headers?.get('location');
+      const target = location ? new URL(location, currentUrl).toString() : null;
+      if (!target || originOf(target) !== originOf(url) || hops >= MAX_REDIRECTS) {
+        throw new NetworkError(
+          'Refusing to follow a redirect that leaves the base URL origin (credentials would be forwarded)',
+          pathOf(url),
+          method
+        );
+      }
+      currentUrl = target;
+      if (response.status === 303) {
+        currentInit = { ...currentInit, method: 'GET', body: undefined };
+      }
+    }
+  } catch (error) {
+    if (error instanceof TenxGraphError) throw error;
+    const name = (error as { name?: string } | null)?.name;
+    if (name === 'AbortError') {
+      if (context.signal?.aborted) throw error;
+      throw new RequestTimeoutError(context.timeout, pathOf(url), method, error);
+    }
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new NetworkError(`Network request failed: ${detail}`, pathOf(url), method, error);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    unlink();
+  }
+}

package/src/tools.ts

@@ -52,6 +52,56 @@ export interface ToolRegistration {
   description?: string;
   parameters?: ToolParameter;
   handler: ToolHandler;
+  /**
+   * Runs on the server-sent arguments before the handler (after the declared `parameters`
+   * check). Throw, or return `false`, to reject the call: the model receives a failed tool
+   * result and the handler is not run.
+   */
+  validate?: (args: any) => boolean | void | Promise<boolean | void>;
+  /** Reject calls whose JSON-serialised arguments exceed this many bytes. Default 1 MiB. */
+  maxArgsBytes?: number;
+}
+
+/** Default cap on serialised tool-call arguments. */
+export const DEFAULT_MAX_TOOL_ARGS_BYTES = 1024 * 1024;
+
+/** Check `args` against the top level of a declared JSON Schema; returns an error message or null. */
+export function checkToolArguments(args: unknown, parameters?: ToolParameter): string | null {
+  if (!parameters) return null;
+  if (args === null || typeof args !== 'object' || Array.isArray(args)) {
+    return 'arguments must be an object';
+  }
+  const record = args as Record<string, unknown>;
+  for (const key of parameters.required ?? []) {
+    if (!(key in record)) return `missing required argument '${key}'`;
+  }
+  const properties = parameters.properties ?? {};
+  if (parameters.additionalProperties === false) {
+    for (const key of Object.keys(record)) {
+      if (!(key in properties)) return `unexpected argument '${key}'`;
+    }
+  }
+  for (const [key, schema] of Object.entries(properties)) {
+    const value = record[key];
+    const expected = (schema as { type?: unknown } | null)?.type;
+    if (value === undefined || typeof expected !== 'string') continue;
+    const ok =
+      expected === 'string'
+        ? typeof value === 'string'
+        : expected === 'number'
+          ? typeof value === 'number'
+          : expected === 'integer'
+            ? Number.isInteger(value)
+            : expected === 'boolean'
+              ? typeof value === 'boolean'
+              : expected === 'array'
+                ? Array.isArray(value)
+                : expected === 'object'
+                  ? value !== null && typeof value === 'object' && !Array.isArray(value)
+                  : true;
+    if (!ok) return `argument '${key}' must be of type ${expected}`;
+  }
+  return null;
 }
 
 // Internal tool definition (extends handler)
@@ -60,6 +110,8 @@ export interface ToolDefinition extends ToolHandler {
   description?: string;
   parameters?: ToolParameter;
   node?: string;
+  validate?: ToolRegistration['validate'];
+  maxArgsBytes?: number;
 }
 
 export class ToolExecutor {
@@ -108,6 +160,16 @@ export class ToolExecutor {
       writable: true,
       configurable: true,
     });
+    Object.defineProperty(toolDef, 'validate', {
+      value: registration.validate,
+      writable: true,
+      configurable: true,
+    });
+    Object.defineProperty(toolDef, 'maxArgsBytes', {
+      value: registration.maxArgsBytes,
+      writable: true,
+      configurable: true,
+    });
     Object.defineProperty(toolDef, 'node', {
       value: registration.node,
       writable: true,
@@ -174,14 +236,47 @@ export class ToolExecutor {
 
     const results: Message[] = [];
 
+    const seenCallIds = new Set<string>();
+    const failed = (callId: string, error: string): Message =>
+      Message.tool_message([
+        new ToolResultBlock({
+          call_id: callId,
+          output: { error },
+          status: 'failed',
+          is_error: true,
+        }),
+      ]);
+
     // Execute each tool call
     for (const call of toolCalls) {
       const toolName = call.name;
 
+      if (call.id && seenCallIds.has(call.id)) {
+        results.push(failed(call.id, `Duplicate tool call id '${call.id}' rejected`));
+        continue;
+      }
+      if (call.id) seenCallIds.add(call.id);
+
       if (this.tools.has(toolName)) {
         const tool = this.tools.get(toolName)!;
 
         try {
+          const maxBytes = tool.maxArgsBytes ?? DEFAULT_MAX_TOOL_ARGS_BYTES;
+          const size = JSON.stringify(call.args ?? null)?.length ?? 0;
+          if (size > maxBytes) {
+            results.push(failed(call.id, `Arguments for '${toolName}' exceed ${maxBytes} bytes`));
+            continue;
+          }
+          const invalid = checkToolArguments(call.args ?? {}, tool.parameters);
+          if (invalid) {
+            results.push(failed(call.id, `Invalid arguments for '${toolName}': ${invalid}`));
+            continue;
+          }
+          if (tool.validate && (await tool.validate(call.args)) === false) {
+            results.push(failed(call.id, `Arguments for '${toolName}' were rejected`));
+            continue;
+          }
+
           // Execute the tool
           const result = await tool(call.args);