@tyvm/knowhow 0.0.158 → 0.0.160

package/src/clients/http.ts

@@ -1,719 +0,0 @@
-import http, {
-  HTTP_UNAUTHORIZED_HANDLER,
-  HttpError,
-  RefreshableHeaders,
-} from "../utils/http";
-import { emitResponseMetadata } from "./responseMetadata";
-
-import {
-  GenericClient,
-  CompletionOptions,
-  CompletionResponse,
-  StreamChunk,
-  EmbeddingOptions,
-  EmbeddingResponse,
-} from "./types";
-import { ModelPricing } from "./pricing/types";
-import fs from "fs";
-import path from "path";
-
-export interface HttpClientOptions {
-  headers?: Record<string, string>;
-  timeout?: number;
-  extra_body?: Record<string, any>;
-}
-
-/**
- * Optional callback that, when set, is called whenever a 401 is received
- * (reactive refresh) or whenever `needsRefresh()` returns true before a
- * request (proactive refresh).  Override this in a subclass or set it
- * directly on an instance:
- *
- *   client.refreshToken = async () => { const newJwt = await ...; client.setJwt(newJwt); };
- */
-export type RefreshTokenFn = () => Promise<void>;
-
-export class HttpClient implements GenericClient {
-  /** Timeout in milliseconds for HTTP requests. Default: 30000 (30s). Use 0 to disable. */
-  private timeout: number;
-  private headers: RefreshableHeaders;
-  private extra_body: Record<string, any>;
-  /** Optional pricing table: model id → per-million-token prices */
-  private pricingMap: Record<string, ModelPricing> = {};
-
-  /**
-   * Override this to provide automatic token refresh.  Called reactively on
-   * 401 responses (via HTTP_UNAUTHORIZED_HANDLER) and proactively before
-   * each request when `needsRefresh()` returns true.
-   *
-   * The implementation should obtain a new token and call `this.setJwt()`
-   * (or `this.setKey()`) before returning.
-   */
-  refreshToken: RefreshTokenFn | undefined = undefined;
-
-  /**
-   * Override this to provide proactive expiry detection.  When it returns
-   * `true`, `refreshToken()` is called before the next outgoing request.
-   * The default implementation decodes the JWT `exp` claim (< 5 min window).
-   */
-  needsRefresh(): boolean {
-    const authHeader = (this.headers as Record<string, string>)[
-      "Authorization"
-    ];
-    if (!authHeader) return false;
-    const token = authHeader.startsWith("Bearer ")
-      ? authHeader.slice(7)
-      : authHeader;
-    try {
-      const parts = token.split(".");
-      if (parts.length !== 3) return false;
-      const payload = JSON.parse(
-        Buffer.from(parts[1], "base64url").toString("utf8")
-      );
-      return (
-        typeof payload.exp === "number" &&
-        payload.exp * 1000 - Date.now() < 5 * 60 * 1000
-      );
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Call before each outgoing request to proactively refresh an expiring
-   * token.  No-ops when no `refreshToken` hook is set.
-   */
-  private async refreshIfNeeded(): Promise<void> {
-    if (this.refreshToken && this.needsRefresh()) {
-      await this.refreshToken();
-    }
-  }
-
-  constructor(private baseUrl: string, options: HttpClientOptions = {}) {
-    this.headers = options.headers ?? {};
-    // Wire the reactive 401 handler so the low-level http util can retry once
-    // after a token refresh without callers needing to do anything extra.
-    Object.defineProperty(this.headers, HTTP_UNAUTHORIZED_HANDLER, {
-      enumerable: false,
-      configurable: true,
-      get: () => (this.refreshToken ? () => this.refreshToken!() : undefined),
-    });
-    this.timeout = options.timeout ?? 30000;
-    this.extra_body = options.extra_body ?? {};
-  }
-
-  private async withRetry<T>(fn: () => Promise<T>, retries = 3): Promise<T> {
-    let lastError: any;
-    for (let attempt = 0; attempt <= retries; attempt++) {
-      try {
-        return await fn();
-      } catch (e: any) {
-        lastError = e;
-        const errorStr = e.toString();
-        const isNonRetriable =
-          errorStr.includes("401") ||
-          errorStr.includes("403") ||
-          errorStr.includes("404") ||
-          errorStr.includes("429");
-        const isRetriable =
-          !isNonRetriable &&
-          (errorStr.match(/5\d\d/) ||
-            errorStr.includes("timeout") ||
-            errorStr.includes("ECONNRESET") ||
-            errorStr.includes("ETIMEDOUT") ||
-            errorStr.includes("Invalid response format from MCP") ||
-            errorStr.includes("Failed to get models"));
-        if (!isRetriable || attempt >= retries) {
-          throw e;
-        }
-        const delay = 1000 * Math.pow(2, attempt);
-        console.warn(
-          `HTTP request failed (attempt ${
-            attempt + 1
-          }/${retries}), retrying in ${delay}ms...`,
-          e.message
-        );
-        await new Promise((resolve) => setTimeout(resolve, delay));
-      }
-    }
-    throw lastError;
-  }
-
-  setJwt(jwt: string) {
-    // Mutate in-place to preserve the HTTP_UNAUTHORIZED_HANDLER symbol property.
-    this.headers.Authorization = `Bearer ${jwt}`;
-  }
-
-  setBaseUrl(baseUrl: string) {
-    this.baseUrl = baseUrl;
-  }
-
-  setKey(key: string) {
-    this.setJwt(key);
-  }
-
-  /**
-   * Supply a pricing map so that createChatCompletion / createEmbedding can
-   * calculate a local usd_cost from usage tokens when the provider does not
-   * return a cost field itself.
-   */
-  setPrices(pricingMap: Record<string, ModelPricing>) {
-    this.pricingMap = pricingMap;
-  }
-
-  /**
-   * A stable provider id used to tag/read the provider-agnostic
-   * `_reasoning_details` slot. Reasoning items are opaque and only meaningful
-   * to the provider that produced them, so we key on the client's baseUrl.
-   */
-  protected reasoningProviderId(): string {
-    return `http:${this.baseUrl}`;
-  }
-
-  /**
-   * Resolve the provider-native reasoning items (Responses API `reasoning`
-   * items with encrypted_content) to re-inject for an assistant message,
-   * reading the provider-agnostic `_reasoning_details` slot only when it was
-   * produced by this same client.
-   */
-  protected getReasoningItems(msg: any): any[] {
-    const details = msg?._reasoning_details;
-    if (
-      details &&
-      details.provider === this.reasoningProviderId() &&
-      Array.isArray(details.items)
-    ) {
-      return details.items;
-    }
-    return [];
-  }
-
-  /**
-   * Returns the pricing entry for a specific model, or all pricing entries if no model is given.
-   * Returns undefined for a specific model if no pricing is known.
-   */
-  getPricing(
-    model?: string
-  ): ModelPricing | Record<string, ModelPricing> | undefined {
-    if (model !== undefined) {
-      return this.pricingMap[model];
-    }
-    return this.pricingMap;
-  }
-
-  /**
-   * Calculate USD cost for a completion/embedding call from token usage.
-   * Returns undefined if no pricing entry exists for the model.
-   */
-  calculateCost(
-    model: string,
-    usage:
-      | {
-          prompt_tokens?: number;
-          completion_tokens?: number;
-          prompt_tokens_details?: { cached_tokens?: number };
-        }
-      | undefined
-  ): number | undefined {
-    if (!usage) return undefined;
-    const pricing = this.pricingMap[model];
-    if (!pricing) return undefined;
-
-    const cachedInputTokens = usage.prompt_tokens_details?.cached_tokens ?? 0;
-    const inputTokens = usage.prompt_tokens ?? 0;
-    const outputTokens = usage.completion_tokens ?? 0;
-
-    const cachedInputCost =
-      (cachedInputTokens * (pricing.cache_hit ?? pricing.cached_input ?? 0)) /
-      1e6;
-    const inputCost =
-      ((inputTokens - cachedInputTokens) * (pricing.input ?? 0)) / 1e6;
-    const outputCost = (outputTokens * (pricing.output ?? 0)) / 1e6;
-
-    return cachedInputCost + inputCost + outputCost;
-  }
-
-  /**
-   * Apply extra options (timeout, headers, extra_body) after construction.
-   * Used by AIClient.resolveClient to honour per-provider config overrides
-   * even when the client is created via a known clientClass (e.g. nvidia, groq).
-   */
-  setOptions(
-    options: Omit<HttpClientOptions, "headers"> & {
-      headers?: Record<string, string>;
-    }
-  ) {
-    if (options.timeout !== undefined) this.timeout = options.timeout;
-    if (options.extra_body !== undefined) this.extra_body = options.extra_body;
-    if (options.headers) {
-      // Mutate in-place to preserve the HTTP_UNAUTHORIZED_HANDLER symbol property.
-      for (const [name, value] of Object.entries(options.headers)) {
-        const existingName = Object.keys(this.headers).find(
-          (candidate) => candidate.toLowerCase() === name.toLowerCase()
-        );
-        this.headers[existingName ?? name] = value;
-      }
-    }
-  }
-
-  loadJwtFile(filePath: string) {
-    try {
-      const jwtFile = path.join(process.cwd(), filePath);
-      if (!fs.existsSync(jwtFile)) {
-        throw new Error(`JWT file not found: ${filePath}`);
-      }
-      const jwt = fs.readFileSync(jwtFile, "utf-8").trim();
-      this.setJwt(jwt);
-    } catch (error) {
-      console.error(`Error loading JWT file: ${error}`);
-    }
-  }
-
-  async createChatCompletion(
-    options: CompletionOptions
-  ): Promise<CompletionResponse> {
-    await this.refreshIfNeeded();
-    return this.withRetry(async () => {
-      const {
-        signal,
-        timeout,
-        maxRetries,
-        backoffMs,
-        onResponseMetadata,
-        ...requestOptions
-      } = options;
-      const body = {
-        ...requestOptions,
-        model: options.model,
-        messages: options.messages,
-        max_tokens: options.max_tokens || 4000,
-        ...this.extra_body,
-
-        ...(options.tools?.length && {
-          tools: options.tools,
-          tool_choice: options.tool_choice ?? "auto",
-        }),
-      };
-
-      let response;
-      try {
-        response = await http.post(
-          `${this.baseUrl}/v1/chat/completions`,
-          body,
-          {
-            headers: this.headers as Record<string, string>,
-            timeout: this.timeout,
-          }
-        );
-      } catch (error) {
-        if (error instanceof HttpError) {
-          emitResponseMetadata(options, {
-            statusCode: error.status,
-            headers: error.response.headers,
-          });
-        }
-        throw error;
-      }
-      emitResponseMetadata(options, {
-        statusCode: response.status,
-        headers: response.headers,
-      });
-
-      const data = response.data;
-
-      // Since this uses a keepalive, we need to detect 200 with error in body
-      if (data.error) {
-        throw new Error(JSON.stringify(data.error, null, 2));
-      }
-
-      return {
-        choices: data.choices.map((choice: any) => ({
-          message: {
-            role: choice.message.role,
-            content: choice.message.content,
-            tool_calls: choice.message.tool_calls,
-          },
-        })),
-        model: data.model,
-        usage: data.usage,
-        usd_cost:
-          data.usd_cost ?? this.calculateCost(options.model, data.usage),
-      };
-    });
-  }
-
-  /**
-   * Streams a chat completion via OpenAI-compatible SSE (`stream: true`).
-   * Parses `data: {...}` lines and yields token deltas, then a final done chunk.
-   */
-  async *createChatCompletionStream(
-    options: CompletionOptions
-  ): AsyncGenerator<StreamChunk> {
-    await this.refreshIfNeeded();
-    const {
-      signal,
-      timeout,
-      maxRetries,
-      backoffMs,
-      onResponseMetadata,
-      ...requestOptions
-    } = options;
-    const body = {
-      ...requestOptions,
-      model: options.model,
-      messages: options.messages,
-      max_tokens: options.max_tokens || 4000,
-      ...this.extra_body,
-      stream: true,
-      stream_options: { include_usage: true },
-      ...(options.tools?.length && {
-        tools: options.tools,
-        tool_choice: options.tool_choice ?? "auto",
-      }),
-    };
-
-    const response = await fetch(`${this.baseUrl}/v1/chat/completions`, {
-      method: "POST",
-      headers: {
-        ...(this.headers as Record<string, string>),
-        "Content-Type": "application/json",
-        Accept: "text/event-stream",
-      },
-      body: JSON.stringify(body),
-      signal: options.signal,
-    });
-    emitResponseMetadata(options, {
-      statusCode: response.status,
-      headers: response.headers,
-    });
-
-    if (!response.ok) {
-      const text = await response.text().catch(() => "");
-      throw new Error(`HTTP ${response.status}: ${text}`);
-    }
-
-    if (!response.body) {
-      throw new Error("No response body for streaming request");
-    }
-
-    const reader = response.body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
-    let usage: StreamChunk["usage"] | undefined;
-
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-
-      buffer += decoder.decode(value, { stream: true });
-      const lines = buffer.split("\n");
-      buffer = lines.pop() ?? "";
-
-      for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed || !trimmed.startsWith("data: ")) continue;
-        const jsonStr = trimmed.slice(6);
-        if (jsonStr === "[DONE]") continue;
-        try {
-          const chunk = JSON.parse(jsonStr);
-          const delta = chunk.choices?.[0]?.delta?.content;
-          if (delta) {
-            yield { delta, done: false };
-          }
-          if (chunk.usage) {
-            usage = {
-              prompt_tokens: chunk.usage.prompt_tokens ?? 0,
-              completion_tokens: chunk.usage.completion_tokens ?? 0,
-              total_tokens: chunk.usage.total_tokens,
-            };
-          }
-        } catch {
-          // Ignore malformed SSE lines
-        }
-      }
-    }
-
-    const usdCost = this.calculateCost(options.model, usage);
-    yield { done: true, usage, usd_cost: usdCost };
-  }
-
-  /**
-   * Creates a completion using the Responses API (/v1/responses).
-   * Compatible with providers that implement the OpenAI Responses API spec
-   * (e.g. xAI at https://api.x.ai/v1/responses).
-   */
-  async createResponse(
-    options: CompletionOptions,
-    store = false
-  ): Promise<CompletionResponse> {
-    await this.refreshIfNeeded();
-    return this.withRetry(async () => {
-      // Extract system messages as instructions
-      const systemMessages = options.messages.filter(
-        (m) => m.role === "system"
-      );
-      const nonSystemMessages = options.messages.filter(
-        (m) => m.role !== "system"
-      );
-      const instructions =
-        systemMessages
-          .map((m) => (typeof m.content === "string" ? m.content : ""))
-          .join("\n")
-          .trim() || undefined;
-
-      // Convert messages to Responses API input format
-      // Responses API hard limit: 10,485,760 chars per function_call_output.output
-      const MAX_TOOL_OUTPUT = 10_485_000;
-      const truncateToolOutput = (s: string) =>
-        s.length > MAX_TOOL_OUTPUT
-          ? s.slice(0, MAX_TOOL_OUTPUT) +
-            "\n\n[TRUNCATED: output exceeded 10MB API limit]"
-          : s;
-      const input: any[] = nonSystemMessages
-        .map((msg) => {
-          if (msg.role === "tool") {
-            return {
-              type: "function_call_output",
-              call_id: msg.tool_call_id,
-              output: truncateToolOutput(
-                typeof msg.content === "string"
-                  ? msg.content
-                  : JSON.stringify(msg.content)
-              ),
-            };
-          }
-          if (msg.role === "assistant" && msg.tool_calls?.length) {
-            // Re-inject any captured reasoning items (encrypted_content) BEFORE
-            // the function_call items so the model preserves its chain-of-thought
-            // across tool-use turns instead of re-deriving it each turn.
-            const reasoningItems = this.getReasoningItems(msg);
-            return [
-              ...reasoningItems,
-              ...(msg.tool_calls as any[]).map((tc: any) => ({
-                type: "function_call",
-                id: tc.id.startsWith("fc") ? tc.id : `fc_${tc.id}`,
-                call_id: tc.id,
-                name: tc.function.name,
-                arguments: tc.function.arguments,
-              })),
-            ];
-          }
-          if (msg.role === "assistant" && this.getReasoningItems(msg).length) {
-            return [
-              ...this.getReasoningItems(msg),
-              {
-                role: msg.role,
-                content:
-                  typeof msg.content === "string"
-                    ? msg.content
-                    : JSON.stringify(msg.content),
-              },
-            ];
-          }
-          return {
-            role: msg.role,
-            content:
-              typeof msg.content === "string"
-                ? msg.content
-                : JSON.stringify(msg.content),
-          };
-        })
-        .flat();
-
-      const tools = options.tools?.map((tool) => ({
-        type: "function" as const,
-        name: tool.function.name,
-        description: tool.function.description,
-        parameters: tool.function.parameters as Record<string, unknown>,
-        strict: false,
-      }));
-
-      const body = {
-        model: options.model,
-        input,
-        ...(instructions && { instructions }),
-        ...(options.max_tokens && { max_output_tokens: options.max_tokens }),
-        ...(tools?.length && {
-          tools,
-          tool_choice: options.tool_choice ?? "auto",
-        }),
-        // Reasoning persistence: store server-side when requested, otherwise
-        // ask the provider to return encrypted reasoning content so we can
-        // thread the reasoning items back into the next request ourselves.
-        store: options.store === true ? true : store,
-        ...(options.previous_response_id && {
-          previous_response_id: options.previous_response_id,
-        }),
-        ...(options.store !== true &&
-          options.reasoning_effort &&
-          options.reasoning_effort !== "none" && {
-            include: ["reasoning.encrypted_content"],
-          }),
-        ...this.extra_body,
-      };
-
-      let response;
-      try {
-        response = await http.post(`${this.baseUrl}/v1/responses`, body, {
-          headers: this.headers as Record<string, string>,
-          timeout: this.timeout,
-        });
-      } catch (error) {
-        if (error instanceof HttpError) {
-          emitResponseMetadata(options, {
-            statusCode: error.status,
-            headers: error.response.headers,
-          });
-        }
-        throw error;
-      }
-      emitResponseMetadata(options, {
-        statusCode: response.status,
-        headers: response.headers,
-      });
-
-      const data = response.data;
-
-      if (data.error) {
-        throw new Error(JSON.stringify(data.error, null, 2));
-      }
-
-      // Map usage from Responses API format to Chat Completions format
-      const usage = data.usage
-        ? {
-            prompt_tokens: data.usage.input_tokens,
-            completion_tokens: data.usage.output_tokens,
-            total_tokens: data.usage.input_tokens + data.usage.output_tokens,
-            prompt_tokens_details: {
-              cached_tokens:
-                data.usage.input_tokens_details?.cached_tokens ?? 0,
-            },
-          }
-        : undefined;
-
-      // Collect text content and tool calls from output items
-      let textContent: string | null = null;
-      const toolCalls: any[] = [];
-      // Reasoning items (encrypted_content) to thread back into the next turn,
-      // plus a human-readable summary of the model's thinking (if present).
-      const reasoningItems: any[] = [];
-      let reasoningSummary: string | null = null;
-
-      for (const item of data.output ?? []) {
-        if (item.type === "message") {
-          for (const part of item.content ?? []) {
-            if (part.type === "output_text") {
-              textContent = (textContent ?? "") + part.text;
-            }
-          }
-        } else if (item.type === "reasoning") {
-          reasoningItems.push(item);
-          const summaryParts = item.summary ?? [];
-          for (const part of summaryParts) {
-            const text = typeof part === "string" ? part : part?.text;
-            if (text) {
-              reasoningSummary = (reasoningSummary ?? "") + text;
-            }
-          }
-        } else if (item.type === "function_call") {
-          toolCalls.push({
-            id: item.call_id,
-            type: "function",
-            function: { name: item.name, arguments: item.arguments },
-          });
-        }
-      }
-
-      return {
-        choices: [
-          {
-            message: {
-              role: "assistant",
-              content: textContent,
-              ...(toolCalls.length > 0 && { tool_calls: toolCalls }),
-              ...(reasoningSummary && { reasoning_summary: reasoningSummary }),
-              ...(reasoningItems.length > 0 && {
-                _reasoning_details: {
-                  provider: this.reasoningProviderId(),
-                  items: reasoningItems,
-                },
-              }),
-            },
-          },
-        ],
-        model: data.model ?? options.model,
-        usage,
-        usd_cost: data.usd_cost ?? this.calculateCost(options.model, usage),
-        response_id: data.id,
-      };
-    });
-  }
-
-  async createEmbedding(options: EmbeddingOptions): Promise<EmbeddingResponse> {
-    await this.refreshIfNeeded();
-    return this.withRetry(async () => {
-      let response;
-      try {
-        response = await http.post(
-          `${this.baseUrl}/v1/embeddings`,
-          {
-            model: options.model,
-            input: options.input,
-          },
-          {
-            headers: this.headers as Record<string, string>,
-            timeout: this.timeout,
-          }
-        );
-      } catch (error) {
-        if (error instanceof HttpError) {
-          emitResponseMetadata(options, {
-            statusCode: error.status,
-            headers: error.response.headers,
-          });
-        }
-        throw error;
-      }
-      emitResponseMetadata(options, {
-        statusCode: response.status,
-        headers: response.headers,
-      });
-
-      const data = response.data;
-
-      // Since this uses a keepalive, we need to detect 200 with error in body
-      if (data.error) {
-        throw new Error(JSON.stringify(data.error, null, 2));
-      }
-
-      return {
-        data: data.data,
-        model: options.model,
-        usage: data.usage,
-        usd_cost:
-          data.usd_cost ?? this.calculateCost(options.model, data.usage),
-      };
-    });
-  }
-
-  async getModels(type = "all") {
-    await this.refreshIfNeeded();
-    return this.withRetry(async () => {
-      const response = await http.get(
-        `${this.baseUrl}/v1/models?type=${type}`,
-        {
-          headers: this.headers as Record<string, string>,
-          timeout: this.timeout,
-        }
-      );
-
-      const data = response.data?.data;
-
-      return data.map((model: any) => ({
-        id: model.id,
-        object: model.object,
-        owned_by: model.owned_by,
-      }));
-    });
-  }
-}