feat(ai-proxy): add HTTP client for frontend and agent-client usage

Add AiProxyClient class with methods to interact with the ai-proxy API:
- remoteTools(): GET /remote-tools to list available tools
- askAi(): POST /ai-query with Authorization header for chat completions
- invokeTool(): POST /invoke-remote-tool to execute a specific tool

Includes timeout handling, error handling, and comprehensive tests.

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: alban bertolini

packages/ai-proxy/src/client-types.ts

@@ -0,0 +1,49 @@
+import type {
+  ChatCompletionMessage,
+  ChatCompletionResponse,
+  ChatCompletionTool,
+  ChatCompletionToolChoice,
+} from './provider-dispatcher';
+import type { ResponseFormat } from '@langchain/core/tools';
+
+export interface AiProxyClientConfig {
+  baseUrl: string;
+  openAiApiKey?: string;
+  timeout?: number;
+  fetch?: typeof fetch;
+}
+
+export interface AskAiInput {
+  messages: ChatCompletionMessage[];
+  tools?: ChatCompletionTool[];
+  tool_choice?: ChatCompletionToolChoice;
+  aiName?: string;
+}
+
+export interface InvokeToolInput {
+  toolName: string;
+  inputs: ChatCompletionMessage[];
+}
+
+export interface RemoteToolDefinition {
+  name: string;
+  description: string;
+  responseFormat: ResponseFormat;
+  schema: Record<string, unknown>;
+  sourceId: string;
+  sourceType: string;
+}
+
+export type { ChatCompletionResponse as ChatCompletion };
+
+export class AiProxyClientError extends Error {
+  readonly status: number;
+  readonly body?: unknown;
+
+  constructor(message: string, status: number, body?: unknown) {
+    super(message);
+    this.name = 'AiProxyClientError';
+    this.status = status;
+    this.body = body;
+  }
+}

packages/ai-proxy/src/client.ts

@@ -0,0 +1,139 @@
+import type {
+  AiProxyClientConfig,
+  AskAiInput,
+  ChatCompletion,
+  InvokeToolInput,
+  RemoteToolDefinition,
+} from './client-types';
+
+import { AiProxyClientError } from './client-types';
+
+const DEFAULT_TIMEOUT = 30_000;
+
+export class AiProxyClient {
+  private readonly baseUrl: string;
+  private readonly openAiApiKey?: string;
+  private readonly timeout: number;
+  private readonly fetchFn: typeof fetch;
+
+  constructor(config: AiProxyClientConfig) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, '');
+    this.openAiApiKey = config.openAiApiKey;
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.fetchFn = config.fetch ?? fetch;
+  }
+
+  async remoteTools(): Promise<RemoteToolDefinition[]> {
+    return this.request<RemoteToolDefinition[]>({
+      method: 'GET',
+      path: '/remote-tools',
+    });
+  }
+
+  async askAi(input: AskAiInput): Promise<ChatCompletion> {
+    const searchParams = new URLSearchParams();
+
+    if (input.aiName) {
+      searchParams.set('ai-name', input.aiName);
+    }
+
+    return this.request<ChatCompletion>({
+      method: 'POST',
+      path: '/ai-query',
+      searchParams,
+      body: {
+        messages: input.messages,
+        tools: input.tools,
+        tool_choice: input.tool_choice,
+      },
+      auth: true,
+    });
+  }
+
+  async invokeTool<T = unknown>(input: InvokeToolInput): Promise<T> {
+    const searchParams = new URLSearchParams();
+    searchParams.set('tool-name', input.toolName);
+
+    return this.request<T>({
+      method: 'POST',
+      path: '/invoke-remote-tool',
+      searchParams,
+      body: {
+        inputs: input.inputs,
+      },
+    });
+  }
+
+  private async request<T>(params: {
+    method: 'GET' | 'POST';
+    path: string;
+    searchParams?: URLSearchParams;
+    body?: unknown;
+    auth?: boolean;
+  }): Promise<T> {
+    const { method, path, searchParams, body, auth } = params;
+
+    let url = `${this.baseUrl}${path}`;
+
+    if (searchParams && searchParams.toString()) {
+      url += `?${searchParams.toString()}`;
+    }
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    };
+
+    if (auth && this.openAiApiKey) {
+      headers.Authorization = `Bearer ${this.openAiApiKey}`;
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await this.fetchFn(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        let responseBody: unknown;
+
+        try {
+          responseBody = await response.json();
+        } catch {
+          responseBody = await response.text().catch(() => undefined);
+        }
+
+        throw new AiProxyClientError(
+          `Request failed with status ${response.status}`,
+          response.status,
+          responseBody,
+        );
+      }
+
+      return (await response.json()) as T;
+    } catch (error) {
+      if (error instanceof AiProxyClientError) {
+        throw error;
+      }
+
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new AiProxyClientError(`Request timeout after ${this.timeout}ms`, 408);
+      }
+
+      throw new AiProxyClientError(
+        `Network error: ${error instanceof Error ? error.message : String(error)}`,
+        0,
+      );
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+}
+
+export function createAiProxyClient(config: AiProxyClientConfig): AiProxyClient {
+  return new AiProxyClient(config);
+}

packages/ai-proxy/src/index.ts

@@ -9,6 +9,9 @@ export * from './mcp-client';
 
 export * from './types/errors';
 
+export * from './client';
+export * from './client-types';
+
 export function validMcpConfigurationOrThrow(mcpConfig: McpConfiguration) {
   return McpConfigChecker.check(mcpConfig);
 }