10xgraph-client 0.0.0-stage → 0.6.0

package/src/tools.ts

@@ -0,0 +1,225 @@
+import { Message, RemoteToolCallBlock, ToolResultBlock } from './message.js';
+
+// TOOL HANDLER
+export interface ToolHandler {
+  (args: any): Promise<any>;
+}
+
+/**
+ * JSON Schema describing a tool's arguments.
+ *
+ * `properties` and `required` are optional, matching JSON Schema itself: a tool
+ * whose arguments are all optional needs neither, and a tool that takes no
+ * arguments can be declared as `{ type: 'object' }`. Additional JSON Schema
+ * keywords (`additionalProperties`, `$defs`, ...) are passed through untouched.
+ */
+export interface ToolParameter {
+  type: string;
+  properties?: Record<string, any>;
+  required?: string[];
+  [key: string]: unknown;
+}
+
+/**
+ * Fill in the JSON Schema defaults a tool declaration may leave out, so the
+ * wire format sent to the server is always a complete object schema.
+ */
+export function normalizeToolParameters(parameters?: ToolParameter): ToolParameter {
+  const source: Partial<ToolParameter> = parameters ?? {};
+  const { type, properties, required, ...rest } = source;
+
+  return {
+    ...rest,
+    type: type ?? 'object',
+    properties: properties ?? {},
+    required: required ?? [],
+  };
+}
+
+export interface Tool {
+  type: string;
+  function: {
+    name: string;
+    description: string;
+    parameters: ToolParameter;
+  };
+}
+
+// Tool Registration - what users provide when registering tools
+export interface ToolRegistration {
+  node?: string;
+  name: string;
+  description?: string;
+  parameters?: ToolParameter;
+  handler: ToolHandler;
+}
+
+// Internal tool definition (extends handler)
+export interface ToolDefinition extends ToolHandler {
+  name: string;
+  description?: string;
+  parameters?: ToolParameter;
+  node?: string;
+}
+
+export class ToolExecutor {
+  private tools: Map<string, ToolDefinition>;
+  private toolsByNode: Map<string, Map<string, ToolDefinition>>;
+
+  constructor(tools: ToolDefinition[] = []) {
+    this.tools = new Map<string, ToolDefinition>();
+    this.toolsByNode = new Map<string, Map<string, ToolDefinition>>();
+
+    for (const func of tools) {
+      this.tools.set(func.name, func);
+
+      // Also organize by node if specified
+      if (func.node) {
+        if (!this.toolsByNode.has(func.node)) {
+          this.toolsByNode.set(func.node, new Map());
+        }
+        this.toolsByNode.get(func.node)!.set(func.name, func);
+      }
+    }
+  }
+
+  /**
+   * Register a new tool
+   */
+  registerTool(registration: ToolRegistration): void {
+    // Create a proper ToolDefinition by wrapping the handler
+    const toolDef: ToolDefinition = async (args: any) => {
+      return registration.handler(args);
+    };
+
+    // Use Object.defineProperty to add properties to the function
+    Object.defineProperty(toolDef, 'name', {
+      value: registration.name,
+      writable: true,
+      configurable: true,
+    });
+    Object.defineProperty(toolDef, 'description', {
+      value: registration.description,
+      writable: true,
+      configurable: true,
+    });
+    Object.defineProperty(toolDef, 'parameters', {
+      value: registration.parameters,
+      writable: true,
+      configurable: true,
+    });
+    Object.defineProperty(toolDef, 'node', {
+      value: registration.node,
+      writable: true,
+      configurable: true,
+    });
+
+    this.tools.set(registration.name, toolDef);
+
+    // Organize by node
+    if (registration.node) {
+      if (!this.toolsByNode.has(registration.node)) {
+        this.toolsByNode.set(registration.node, new Map());
+      }
+      this.toolsByNode.get(registration.node)!.set(registration.name, toolDef);
+    }
+  }
+
+  /**
+   * Get tools for a specific node
+   */
+  getToolsForNode(node: string): ToolDefinition[] {
+    const nodeTools = this.toolsByNode.get(node);
+    return nodeTools ? Array.from(nodeTools.values()) : [];
+  }
+
+  /**
+   * Get all tools in OpenAI-compatible format
+   */
+  all_tools(): Tool[] {
+    const openaiTools: Tool[] = [];
+
+    for (const [name, func] of this.tools) {
+      const tool: Tool = {
+        type: 'function',
+        function: {
+          name: name,
+          description: func.description || `Execute ${name}`,
+          parameters: normalizeToolParameters(func.parameters),
+        },
+      };
+      openaiTools.push(tool);
+    }
+
+    return openaiTools;
+  }
+
+  /**
+   * Extract and execute all tool calls from the response
+   * Returns an array of tool result messages
+   */
+  async executeToolCalls(messages: Message[]): Promise<Message[]> {
+    const toolCalls: RemoteToolCallBlock[] = [];
+
+    // Extract all remote_tool_call blocks from messages
+    for (const msg of messages) {
+      if (msg.content) {
+        for (const block of msg.content) {
+          if (block.type === 'remote_tool_call') {
+            toolCalls.push(block as RemoteToolCallBlock);
+          }
+        }
+      }
+    }
+
+    const results: Message[] = [];
+
+    // Execute each tool call
+    for (const call of toolCalls) {
+      const toolName = call.name;
+
+      if (this.tools.has(toolName)) {
+        const tool = this.tools.get(toolName)!;
+
+        try {
+          // Execute the tool
+          const result = await tool(call.args);
+
+          // Create a tool result message
+          const toolResultBlock = new ToolResultBlock({
+            call_id: call.id,
+            output: result,
+            status: 'completed',
+            is_error: false,
+          });
+
+          results.push(Message.tool_message([toolResultBlock]));
+        } catch (error) {
+          // Handle errors
+          const errorMessage = error instanceof Error ? error.message : String(error);
+
+          const toolResultBlock = new ToolResultBlock({
+            call_id: call.id,
+            output: { error: errorMessage },
+            status: 'failed',
+            is_error: true,
+          });
+
+          results.push(Message.tool_message([toolResultBlock]));
+        }
+      } else {
+        // Tool not found error
+        const toolResultBlock = new ToolResultBlock({
+          call_id: call.id,
+          output: { error: `Tool '${toolName}' not found` },
+          status: 'failed',
+          is_error: true,
+        });
+
+        results.push(Message.tool_message([toolResultBlock]));
+      }
+    }
+
+    return results;
+  }
+}

package/src/ws.ts

@@ -0,0 +1,100 @@
+import { TenxGraphAuth, buildHeaders } from './request.js';
+
+/**
+ * Sec-WebSocket-Protocol token the server recognizes for browser-safe bearer auth.
+ * The client opens the socket with `[WS_BEARER_SUBPROTOCOL, "<jwt>"]`; the server
+ * extracts the second protocol entry as the token. This works in browsers (which
+ * cannot set request headers on a WebSocket) and avoids leaking the token in the URL.
+ */
+export const WS_BEARER_SUBPROTOCOL = '10xgraph-bearer';
+
+/** Minimal constructor shape shared by the browser `WebSocket` and the Node `ws` package. */
+export type WebSocketImpl = new (
+  url: string,
+  protocols?: string | string[],
+  options?: unknown
+) => WebSocket;
+
+/** The auth/transport fields the WS helpers read from a request context. */
+export interface WsAuthContext {
+  baseUrl: string;
+  authToken?: string | null;
+  auth?: TenxGraphAuth | null;
+  headers?: HeadersInit;
+  credentials?: RequestCredentials;
+  debug?: boolean;
+  /** Optional WebSocket implementation for runtimes without a global (Node < 21). */
+  webSocketImpl?: WebSocketImpl;
+}
+
+/**
+ * Resolve the bearer token with the same priority as `buildHeaders`.
+ *
+ * `auth` takes precedence over `authToken`, matching the HTTP path. When `auth`
+ * is set to a non-bearer scheme (basic/header) there is no bearer token to send,
+ * so this returns `null` rather than silently falling back to `authToken` — the
+ * HTTP path would not send a bearer in that case either.
+ */
+export function resolveBearerToken(
+  context: Pick<WsAuthContext, 'authToken' | 'auth'>
+): string | null {
+  if (context.auth) {
+    return context.auth.type === 'bearer' ? context.auth.token : null;
+  }
+  if (context.authToken) {
+    return context.authToken;
+  }
+  return null;
+}
+
+/**
+ * Convert the HTTP base URL to a WebSocket URL and append `path`.
+ * The token is never placed in the URL — it travels via the `10xgraph-bearer`
+ * subprotocol (browser-safe) and, in Node, the Authorization header.
+ */
+export function buildWsUrl(context: Pick<WsAuthContext, 'baseUrl'>, path: string): string {
+  return (
+    context.baseUrl
+      .replace(/^https:/, 'wss:')
+      .replace(/^http:/, 'ws:')
+      .replace(/\/$/, '') + path
+  );
+}
+
+/**
+ * Open a WebSocket with bearer auth.
+ *
+ * - If a token is present it is sent as the `10xgraph-bearer` subprotocol (works
+ *   in browsers and Node `ws`).
+ * - In Node-style implementations that accept a third `options` argument, the
+ *   Authorization header is also passed (ignored by browsers).
+ * - The implementation is taken from `context.webSocketImpl`, falling back to the
+ *   global `WebSocket`. If neither exists a descriptive error is thrown.
+ */
+export function openWebSocket(url: string, context: WsAuthContext): WebSocket {
+  const Impl: WebSocketImpl | undefined =
+    context.webSocketImpl ?? (globalThis as { WebSocket?: WebSocketImpl }).WebSocket;
+
+  if (!Impl) {
+    throw new Error(
+      'No WebSocket implementation available. In Node < 21 pass `webSocketImpl` ' +
+        'in the client config (e.g. the `ws` package: `new TenxGraphClient({ ..., webSocketImpl: WebSocket })`).'
+    );
+  }
+
+  const token = resolveBearerToken(context);
+  const protocols = token ? [WS_BEARER_SUBPROTOCOL, token] : undefined;
+
+  const headers = buildHeaders(context);
+  const authHeader = headers['Authorization'] ?? headers['authorization'];
+
+  if (authHeader) {
+    try {
+      return new Impl(url, protocols, { headers: { Authorization: authHeader } });
+    } catch {
+      // Fall through: browser constructors reject the 3rd arg shape — retry plain.
+    }
+  }
+
+  return new Impl(url, protocols);
+}