@tyvm/knowhow 0.0.156 → 0.0.157

package/src/clients/http.ts

@@ -1,4 +1,10 @@
-import http, { HTTP_UNAUTHORIZED_HANDLER, RefreshableHeaders } from "../utils/http";
+import http, {
+  HTTP_UNAUTHORIZED_HANDLER,
+  HttpError,
+  RefreshableHeaders,
+} from "../utils/http";
+import { emitResponseMetadata } from "./responseMetadata";
+
 import {
   GenericClient,
   CompletionOptions,
@@ -51,14 +57,23 @@ export class HttpClient implements GenericClient {
    * The default implementation decodes the JWT `exp` claim (< 5 min window).
    */
   needsRefresh(): boolean {
-    const authHeader = (this.headers as Record<string, string>)["Authorization"];
+    const authHeader = (this.headers as Record<string, string>)[
+      "Authorization"
+    ];
     if (!authHeader) return false;
-    const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : authHeader;
+    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;
+      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;
     }
@@ -81,7 +96,7 @@ export class HttpClient implements GenericClient {
     Object.defineProperty(this.headers, HTTP_UNAUTHORIZED_HANDLER, {
       enumerable: false,
       configurable: true,
-      get: () => this.refreshToken ? () => this.refreshToken!() : undefined,
+      get: () => (this.refreshToken ? () => this.refreshToken!() : undefined),
     });
     this.timeout = options.timeout ?? 30000;
     this.extra_body = options.extra_body ?? {};
@@ -177,7 +192,9 @@ export class HttpClient implements GenericClient {
    * 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 {
+  getPricing(
+    model?: string
+  ): ModelPricing | Record<string, ModelPricing> | undefined {
     if (model !== undefined) {
       return this.pricingMap[model];
     }
@@ -190,19 +207,27 @@ export class HttpClient implements GenericClient {
    */
   calculateCost(
     model: string,
-    usage: { prompt_tokens?: number; completion_tokens?: number; prompt_tokens_details?: { cached_tokens?: number } } | undefined
+    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 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 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;
@@ -213,12 +238,21 @@ export class HttpClient implements GenericClient {
    * 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> }) {
+  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.
-      Object.assign(this.headers, options.headers);
+      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;
+      }
     }
   }
 
@@ -240,8 +274,16 @@ export class HttpClient implements GenericClient {
   ): Promise<CompletionResponse> {
     await this.refreshIfNeeded();
     return this.withRetry(async () => {
+      const {
+        signal,
+        timeout,
+        maxRetries,
+        backoffMs,
+        onResponseMetadata,
+        ...requestOptions
+      } = options;
       const body = {
-        ...options,
+        ...requestOptions,
         model: options.model,
         messages: options.messages,
         max_tokens: options.max_tokens || 4000,
@@ -253,11 +295,29 @@ export class HttpClient implements GenericClient {
         }),
       };
 
-      const response = await http.post(
-        `${this.baseUrl}/v1/chat/completions`,
-        body,
-        { headers: this.headers as Record<string, string>, timeout: this.timeout }
-      );
+      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;
 
@@ -276,7 +336,8 @@ export class HttpClient implements GenericClient {
         })),
         model: data.model,
         usage: data.usage,
-        usd_cost: data.usd_cost ?? this.calculateCost(options.model, data.usage),
+        usd_cost:
+          data.usd_cost ?? this.calculateCost(options.model, data.usage),
       };
     });
   }
@@ -289,8 +350,16 @@ export class HttpClient implements GenericClient {
     options: CompletionOptions
   ): AsyncGenerator<StreamChunk> {
     await this.refreshIfNeeded();
+    const {
+      signal,
+      timeout,
+      maxRetries,
+      backoffMs,
+      onResponseMetadata,
+      ...requestOptions
+    } = options;
     const body = {
-      ...options,
+      ...requestOptions,
       model: options.model,
       messages: options.messages,
       max_tokens: options.max_tokens || 4000,
@@ -308,11 +377,15 @@ export class HttpClient implements GenericClient {
       headers: {
         ...(this.headers as Record<string, string>),
         "Content-Type": "application/json",
-        "Accept": "text/event-stream",
+        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(() => "");
@@ -376,58 +449,76 @@ export class HttpClient implements GenericClient {
     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;
+      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.slice(0, MAX_TOOL_OUTPUT) +
+            "\n\n[TRUNCATED: output exceeded 10MB API limit]"
           : s;
-      const input: any[] = nonSystemMessages.map((msg) => {
-        if (msg.role === "tool") {
+      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 {
-            type: "function_call_output",
-            call_id: msg.tool_call_id,
-            output: truncateToolOutput(typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content)),
+            role: msg.role,
+            content:
+              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();
+        })
+        .flat();
 
       const tools = options.tools?.map((tool) => ({
         type: "function" as const,
@@ -461,11 +552,25 @@ export class HttpClient implements GenericClient {
         ...this.extra_body,
       };
 
-      const response = await http.post(
-        `${this.baseUrl}/v1/responses`,
-        body,
-        { headers: this.headers as Record<string, string>, timeout: this.timeout }
-      );
+      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;
 
@@ -547,14 +652,32 @@ export class HttpClient implements GenericClient {
   async createEmbedding(options: EmbeddingOptions): Promise<EmbeddingResponse> {
     await this.refreshIfNeeded();
     return this.withRetry(async () => {
-      const response = await http.post(
-        `${this.baseUrl}/v1/embeddings`,
-        {
-          model: options.model,
-          input: options.input,
-        },
-        { headers: this.headers as Record<string, string>, timeout: this.timeout }
-      );
+      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;
 
@@ -567,7 +690,8 @@ export class HttpClient implements GenericClient {
         data: data.data,
         model: options.model,
         usage: data.usage,
-        usd_cost: data.usd_cost ?? this.calculateCost(options.model, data.usage),
+        usd_cost:
+          data.usd_cost ?? this.calculateCost(options.model, data.usage),
       };
     });
   }
@@ -575,10 +699,13 @@ export class HttpClient implements GenericClient {
   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 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;
 

package/src/clients/index.ts

@@ -69,6 +69,7 @@ export {
   XaiImagePricing,
   XaiVideoPricing,
 };
+export * from "./responseMetadata";
 export type {
   ModelPricing,
   ModelType,
@@ -82,8 +83,8 @@ export type {
 // ---------------------------------------------------------------------------
 
 type ProviderRegistryEntry = {
-  /** Constructor that accepts up to two optional string args (e.g. apiKey or url, jwt) */
-  clientClass?: new (arg1?: string, arg2?: string) => GenericClient;
+  /** Constructor that accepts the optional API key passed by the registry. */
+  clientClass?: new (arg1?: string) => GenericClient;
   /** Custom factory — takes precedence over clientClass */
   createClient?: (entry: ModelProvider) => GenericClient | null;
 };
@@ -111,7 +112,11 @@ const BUILT_IN_PROVIDER_REGISTRY: Record<string, ProviderRegistryEntry> = {
     createClient: (entry: ModelProvider) => {
       if (!loadKnowhowJwt()) {
         const config = getConfigSync();
-        if (!config.orgId || (!keyPairExists(config.cliIdentityPath) && !keyPairExists())) return null;
+        if (
+          !config.orgId ||
+          (!keyPairExists(config.cliIdentityPath) && !keyPairExists())
+        )
+          return null;
       }
       return new KnowhowGenericClient(KNOWHOW_API_URL);
     },
@@ -320,9 +325,10 @@ export class AIClient {
         if (entry.provider === "knowhow") {
           if (process.env.KNOWHOW_CLI) {
             const warnNeeds = (process.env.KNOWHOW_WARN_NEEDS ?? "").split(",");
-            if (warnNeeds.includes("models")) console.warn(
-              `⚠️  Knowhow provider is not logged in. Run 'knowhow login' to enable Knowhow models.`
-            );
+            if (warnNeeds.includes("models"))
+              console.warn(
+                `⚠️  Knowhow provider is not logged in. Run 'knowhow login' to enable Knowhow models.`
+              );
           }
         }
         continue;
@@ -417,7 +423,9 @@ export class AIClient {
       // Model not in local registry — pass it through anyway so the provider
       // API can accept or reject it directly (e.g. newly-released models that
       // haven't been fetched into our local model list yet).
-      console.warn(`⚠️  Model '${model}' not in local registry for provider '${provider}', attempting anyway.`);
+      console.warn(
+        `⚠️  Model '${model}' not in local registry for provider '${provider}', attempting anyway.`
+      );
     }
 
     return { client: this.clients[provider], provider, model };
@@ -914,7 +922,9 @@ export class AIClient {
    * For HttpClient-based providers with getPricing(), only priced models are kept.
    * For other providers (no getPricing()), all models pass through unchanged.
    */
-  private _filterByPricing(models: Record<string, string[]>): Record<string, string[]> {
+  private _filterByPricing(
+    models: Record<string, string[]>
+  ): Record<string, string[]> {
     const result: Record<string, string[]> = {};
     for (const [provider, ids] of Object.entries(models)) {
       const client = this.clients[provider];
@@ -1009,7 +1019,9 @@ export class AIClient {
   }
 
   listAllModelsWithProvider(options?: { pricing?: boolean }) {
-    const models = options?.pricing ? this._filterByPricing(this.clientModels) : this.clientModels;
+    const models = options?.pricing
+      ? this._filterByPricing(this.clientModels)
+      : this.clientModels;
     return Object.entries(models)
       .map(([provider, ids]) => ids.map((m) => ({ id: `${provider}/${m}` })))
       .flat();