@tyvm/knowhow 0.0.156 → 0.0.157

package/src/clients/openrouter.ts

@@ -1,4 +1,5 @@
-import { HttpClient } from "./http";
+import { HttpClient, HttpClientOptions } from "./http";
+import { withKnowhowAttribution } from "./attribution";
 import { OpenRouterTextPricing } from "./pricing/openrouter";
 
 /**
@@ -9,8 +10,14 @@ import { OpenRouterTextPricing } from "./pricing/openrouter";
  * Set env var OPENROUTER_API_KEY to enable.
  */
 export class GenericOpenRouterClient extends HttpClient {
-  constructor(apiKey = process.env.OPENROUTER_API_KEY) {
-    super("https://openrouter.ai/api");
+  constructor(
+    apiKey = process.env.OPENROUTER_API_KEY,
+    transportOptions: HttpClientOptions = {}
+  ) {
+    super("https://openrouter.ai/api", {
+      ...transportOptions,
+      headers: withKnowhowAttribution(transportOptions.headers),
+    });
     if (apiKey) this.setJwt(apiKey);
     this.setPrices(OpenRouterTextPricing);
   }

package/src/clients/pricing/openai.ts

@@ -231,7 +231,21 @@ export const OpenAiSearchModels: string[] = [
 
 export const OpenAiTextPricing: Record<string, ModelPricing> = {
   // gpt-5.6 series — short context / long context pricing
-  [OpenAiModels.GPT_56_Sol]:   { input: 5.0, cached_input: 0.5,  cache_write: 6.25,  output: 30.0, input_gt_200k: 10.0, output_gt_200k: 45.0 },
+  [OpenAiModels.GPT_56_Sol]: {
+    input: 4.0,
+    cached_input: 0.40,
+    cache_write: 5.00,
+    output: 30.0,
+    input_gt_200k: 10.0,
+    output_gt_200k: 30.0,
+    changelog: [
+      {
+        date: "2026-08-01",
+        note: "Launch pricing — promotional rates available through November 21, 2026",
+        pricing: { input: 5.0, cached_input: 0.5, cache_write: 6.25, output: 30.0, input_gt_200k: 10.0, output_gt_200k: 45.0 },
+      },
+    ],
+  },
   [OpenAiModels.GPT_56_Terra]: { input: 2.0, cached_input: 0.20, cache_write: 2.5,   output: 12.0, input_gt_200k: 4.0,  output_gt_200k: 18.0 },
   [OpenAiModels.GPT_56_Luna]:  { input: 0.2, cached_input: 0.02, cache_write: 0.25,  output: 1.2,  input_gt_200k: 0.4,  output_gt_200k: 1.8  },
   [OpenAiModels.GPT_55]: { input: 5.0, cached_input: 0.5, output: 30.0 },

package/src/clients/pricing/types.ts

@@ -1,3 +1,16 @@
+/**
+ * A historical record of a model's pricing at a point in time.
+ * Use this to track price changes over time.
+ */
+export interface PricingChangelogEntry {
+  /** ISO date string when this pricing became effective (e.g. "2025-04-01") */
+  date: string;
+  /** Optional human-readable note about the change (e.g. "Promotional pricing announcement") */
+  note?: string;
+  /** The pricing values that were in effect from this date */
+  pricing: Omit<ModelPricing, "deprecated" | "deprecationDate" | "limitedAvailability" | "replacedBy" | "reasoningLevels" | "useResponsesApi" | "changelog">;
+}
+
 export type ModelType =
   | "completion"
   | "embedding"
@@ -30,6 +43,8 @@ export interface ModelPricing {
   reasoningLevels?: string[];
   /** If true, this model must be called via the Responses API (/v1/responses) instead of /v1/chat/completions */
   useResponsesApi?: boolean;
+  /** Optional changelog of historical pricing entries, ordered from oldest to newest */
+  changelog?: PricingChangelogEntry[];
 }
 
 export interface ModelCatalogEntry {

package/src/clients/responseMetadata.ts

@@ -0,0 +1,221 @@
+import {
+  ProviderRateLimitMetadata,
+  ProviderResponseMetadata,
+  RetryOptions,
+} from "./types";
+
+const MAX_HEADER_VALUE_LENGTH = 256;
+const MAX_HEADERS = 24;
+const MAX_TOTAL_HEADER_CHARS = 4096;
+const SAFE_HEADER_NAMES = new Set([
+  "retry-after",
+  "ratelimit-limit",
+  "ratelimit-remaining",
+  "ratelimit-reset",
+  "request-id",
+  "x-request-id",
+  "cf-ray",
+  "x-amzn-requestid",
+  "x-amz-request-id",
+]);
+const SAFE_HEADER_PREFIXES = ["x-ratelimit-", "anthropic-ratelimit-"];
+
+type HeaderSource =
+  | Headers
+  | Record<string, unknown>
+  | Iterable<[string, unknown]>
+  | undefined;
+
+function isSafeHeader(name: string) {
+  return (
+    SAFE_HEADER_NAMES.has(name) ||
+    SAFE_HEADER_PREFIXES.some((prefix) => name.startsWith(prefix))
+  );
+}
+
+function entriesFor(headers: HeaderSource): Iterable<[string, unknown]> {
+  if (!headers) return [];
+  if (Symbol.iterator in Object(headers)) {
+    return headers as Iterable<[string, unknown]>;
+  }
+  if (typeof (headers as Headers).forEach === "function") {
+    const entries: Array<[string, unknown]> = [];
+    (headers as Headers).forEach((value, name) => entries.push([name, value]));
+    return entries;
+  }
+  return Object.entries(headers as Record<string, unknown>);
+}
+
+function nonNegativeNumber(value: string | undefined) {
+  if (value === undefined || value.trim() === "") return undefined;
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : undefined;
+}
+
+function resetAt(value: string | undefined, now: Date) {
+  if (!value) return undefined;
+  const seconds = nonNegativeNumber(value);
+  if (seconds !== undefined)
+    return new Date(now.getTime() + seconds * 1000).toISOString();
+
+  // OpenAI-compatible APIs commonly return compact durations such as `6m0s`.
+  const duration = [...value.trim().matchAll(/(\d+(?:\.\d+)?)(ms|s|m|h|d)/gi)];
+  if (
+    duration.length &&
+    duration.map((part) => part[0]).join("") === value.trim()
+  ) {
+    const milliseconds = duration.reduce((total, [, amount, unit]) => {
+      const multiplier = {
+        ms: 1,
+        s: 1_000,
+        m: 60_000,
+        h: 3_600_000,
+        d: 86_400_000,
+      }[unit.toLowerCase()];
+      return total + Number(amount) * multiplier;
+    }, 0);
+    return new Date(now.getTime() + milliseconds).toISOString();
+  }
+
+  const timestamp = Date.parse(value);
+  return Number.isNaN(timestamp)
+    ? undefined
+    : new Date(timestamp).toISOString();
+}
+
+function retryAfterSeconds(value: string | undefined, now: Date) {
+  const seconds = nonNegativeNumber(value);
+  if (seconds !== undefined) return seconds;
+  if (!value) return undefined;
+  const timestamp = Date.parse(value);
+  return Number.isNaN(timestamp)
+    ? undefined
+    : Math.max(0, (timestamp - now.getTime()) / 1000);
+}
+
+/**
+ * Derives one JSON-safe shape from standard, OpenAI-compatible, and Anthropic
+ * rate-limit headers. Callers receive this even when a provider supplied none.
+ */
+export function normalizeRateLimitMetadata(
+  headers: Record<string, string>,
+  now = new Date()
+): ProviderRateLimitMetadata {
+  const header = (...names: string[]) =>
+    names.map((name) => headers[name]).find((value) => value !== undefined);
+  const limit = nonNegativeNumber(
+    header(
+      "anthropic-ratelimit-requests-limit",
+      "ratelimit-limit",
+      "x-ratelimit-limit-requests",
+      "x-ratelimit-limit"
+    )
+  );
+  const remaining = nonNegativeNumber(
+    header(
+      "anthropic-ratelimit-requests-remaining",
+      "ratelimit-remaining",
+      "x-ratelimit-remaining-requests",
+      "x-ratelimit-remaining"
+    )
+  );
+  const requestResetAt = resetAt(
+    header(
+      "anthropic-ratelimit-requests-reset",
+      "ratelimit-reset",
+      "x-ratelimit-reset-requests",
+      "x-ratelimit-reset"
+    ),
+    now
+  );
+  const tokenLimit = nonNegativeNumber(
+    header("anthropic-ratelimit-tokens-limit", "x-ratelimit-limit-tokens")
+  );
+  const tokenRemaining = nonNegativeNumber(
+    header(
+      "anthropic-ratelimit-tokens-remaining",
+      "x-ratelimit-remaining-tokens"
+    )
+  );
+  const tokenResetAt = resetAt(
+    header("anthropic-ratelimit-tokens-reset", "x-ratelimit-reset-tokens"),
+    now
+  );
+  const retryAfter = retryAfterSeconds(header("retry-after"), now);
+  return {
+    ...(limit !== undefined && { limit }),
+    ...(remaining !== undefined && { remaining }),
+    ...(requestResetAt && { resetAt: requestResetAt }),
+    ...(retryAfter !== undefined && { retryAfterSeconds: retryAfter }),
+    ...(tokenLimit !== undefined && { tokenLimit }),
+    ...(tokenRemaining !== undefined && { tokenRemaining }),
+    ...(tokenResetAt && { tokenResetAt }),
+  };
+}
+
+/**
+ * Converts provider headers to the deliberately small telemetry-safe surface.
+ * This function never returns request bodies, credentials, cookies, or arbitrary
+ * provider headers.
+ */
+export function normalizeResponseMetadata(input: {
+  statusCode?: number;
+  headers?: HeaderSource;
+  requestId?: string | null;
+  observedAt?: Date;
+}): ProviderResponseMetadata {
+  const headers: Record<string, string> = {};
+  let totalChars = 0;
+
+  for (const [rawName, rawValue] of entriesFor(input.headers)) {
+    const name = String(rawName).toLowerCase();
+    if (
+      !isSafeHeader(name) ||
+      Object.prototype.hasOwnProperty.call(headers, name)
+    )
+      continue;
+    const value = String(rawValue).slice(0, MAX_HEADER_VALUE_LENGTH);
+    if (
+      Object.keys(headers).length >= MAX_HEADERS ||
+      totalChars + name.length + value.length > MAX_TOTAL_HEADER_CHARS
+    )
+      break;
+    headers[name] = value;
+    totalChars += name.length + value.length;
+  }
+
+  const requestId =
+    input.requestId ??
+    headers["request-id"] ??
+    headers["x-request-id"] ??
+    headers["x-amzn-requestid"] ??
+    headers["x-amz-request-id"];
+  return {
+    ...(typeof input.statusCode === "number" && {
+      statusCode: input.statusCode,
+    }),
+    rateLimit: normalizeRateLimitMetadata(headers, input.observedAt),
+    ...(Object.keys(headers).length > 0 && { headers }),
+    ...(requestId && {
+      requestId: String(requestId).slice(0, MAX_HEADER_VALUE_LENGTH),
+    }),
+  };
+}
+
+/** Emits one visible HTTP response synchronously and isolates observer failures. */
+export function emitResponseMetadata(
+  options: Pick<RetryOptions, "onResponseMetadata"> | undefined,
+  input: {
+    statusCode?: number;
+    headers?: HeaderSource;
+    requestId?: string | null;
+  }
+) {
+  const observer = options?.onResponseMetadata;
+  if (!observer) return;
+  try {
+    observer(normalizeResponseMetadata(input));
+  } catch {
+    // Observability must never affect a provider request or its original error.
+  }
+}

package/src/clients/types.ts

@@ -104,6 +104,36 @@ export interface Tool {
   };
 }
 
+/**
+ * Provider-neutral rate-limit information derived from response headers.
+ * Reset values are ISO-8601 strings so callback payloads remain JSON-safe.
+ */
+export interface ProviderRateLimitMetadata {
+  limit?: number;
+  remaining?: number;
+  resetAt?: string;
+  retryAfterSeconds?: number;
+  tokenLimit?: number;
+  tokenRemaining?: number;
+  tokenResetAt?: string;
+}
+
+/**
+ * Safe telemetry details for one provider response. `rateLimit` is normalized
+ * by the client for every observed response. `headers`, when present, contains
+ * only the bounded allowlisted raw headers used to derive it.
+ */
+export interface ProviderResponseMetadata {
+  statusCode?: number;
+  rateLimit: ProviderRateLimitMetadata;
+  headers?: Record<string, string>;
+  requestId?: string;
+}
+
+export type ProviderResponseMetadataObserver = (
+  metadata: ProviderResponseMetadata
+) => void;
+
 export interface ToolCall {
   id: string;
   type: "function";
@@ -134,6 +164,11 @@ export interface RetryOptions {
    * attempt is cancelled immediately and no further retries are made.
    */
   signal?: AbortSignal;
+  /**
+   * Synchronous observer invoked once for each provider HTTP response visible to
+   * this client, including errors and streaming handshakes.
+   */
+  onResponseMetadata?: ProviderResponseMetadataObserver;
 }
 
 /**
@@ -150,10 +185,13 @@ export const REASONING_EFFORTS = [
   "xhigh",
   "max",
 ] as const;
-export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
+export type ReasoningEffort = typeof REASONING_EFFORTS[number];
 
 export function isReasoningEffort(value: unknown): value is ReasoningEffort {
-  return typeof value === "string" && REASONING_EFFORTS.includes(value as ReasoningEffort);
+  return (
+    typeof value === "string" &&
+    REASONING_EFFORTS.includes(value as ReasoningEffort)
+  );
 }
 
 export interface CompletionOptions extends RetryOptions {
@@ -438,7 +476,9 @@ export interface GenericClient {
   setKey(key: string): void;
   createChatCompletion(options: CompletionOptions): Promise<CompletionResponse>;
   /** Optional streaming variant — yields incremental tokens then a final done chunk. */
-  createChatCompletionStream?(options: CompletionOptions): AsyncGenerator<StreamChunk>;
+  createChatCompletionStream?(
+    options: CompletionOptions
+  ): AsyncGenerator<StreamChunk>;
   createEmbedding(options: EmbeddingOptions): Promise<EmbeddingResponse>;
   createAudioTranscription?(
     options: AudioTranscriptionOptions
@@ -482,5 +522,10 @@ export interface GenericClient {
    * Returns undefined for a specific model if no pricing is known.
    * Only implemented by HttpClient-based providers that have been given a pricing map via setPrices().
    */
-  getPricing?(model?: string): import("./pricing/types").ModelPricing | Record<string, import("./pricing/types").ModelPricing> | undefined;
+  getPricing?(
+    model?: string
+  ):
+    | import("./pricing/types").ModelPricing
+    | Record<string, import("./pricing/types").ModelPricing>
+    | undefined;
 }

package/tests/unit/clients/anthropic.responseMetadata.test.ts

@@ -0,0 +1,81 @@
+import { GenericAnthropicClient } from "../../../src/clients/anthropic";
+
+const options = {
+  model: "claude-sonnet-4-5",
+  messages: [{ role: "user" as const, content: "hello" }],
+};
+
+describe("Anthropic response metadata", () => {
+  it("emits native message response metadata", async () => {
+    const client = new GenericAnthropicClient("test-key");
+    const observer = jest.fn();
+    (client as any).client = {
+      messages: {
+        create: jest.fn(() => ({
+          withResponse: async () => ({
+            data: {
+              content: [{ type: "text", text: "hi" }],
+              usage: { input_tokens: 3, output_tokens: 2 },
+            },
+            response: new Response(null, {
+              status: 200,
+              headers: {
+                "request-id": "anthropic-request",
+                "anthropic-ratelimit-requests-limit": "50",
+                "anthropic-ratelimit-requests-remaining": "49",
+                "anthropic-ratelimit-tokens-remaining": "900",
+              },
+            }),
+            request_id: "anthropic-request",
+          }),
+        })),
+      },
+    };
+
+    const result = await client.createChatCompletion({
+      ...options,
+      onResponseMetadata: observer,
+    });
+    expect(result.choices[0].message.content).toBe("hi");
+    expect(observer).toHaveBeenCalledWith({
+      statusCode: 200,
+      requestId: "anthropic-request",
+      rateLimit: { limit: 50, remaining: 49, tokenRemaining: 900 },
+      headers: {
+        "request-id": "anthropic-request",
+        "anthropic-ratelimit-requests-limit": "50",
+        "anthropic-ratelimit-requests-remaining": "49",
+        "anthropic-ratelimit-tokens-remaining": "900",
+      },
+    });
+  });
+
+  it("emits API error metadata and preserves error identity", async () => {
+    const client = new GenericAnthropicClient("test-key");
+    const observer = jest.fn();
+    const error = Object.assign(new Error("rate limited"), {
+      status: 429,
+      headers: { "retry-after": "1", cookie: "private" },
+      request_id: "anthropic-rate-request",
+    });
+    (client as any).client = {
+      messages: {
+        create: jest.fn(() => ({
+          withResponse: async () => {
+            throw error;
+          },
+        })),
+      },
+    };
+
+    await expect(
+      client.createChatCompletion({ ...options, onResponseMetadata: observer })
+    ).rejects.toBe(error);
+    expect(observer).toHaveBeenCalledWith({
+      statusCode: 429,
+      requestId: "anthropic-rate-request",
+      rateLimit: { retryAfterSeconds: 1 },
+      headers: { "retry-after": "1" },
+    });
+  });
+});

package/tests/unit/clients/attribution.test.ts

@@ -0,0 +1,185 @@
+const post = jest.fn();
+
+jest.mock("../../../src/utils/http", () => ({
+  __esModule: true,
+  default: { post },
+  HTTP_UNAUTHORIZED_HANDLER: Symbol("refresh"),
+  HttpError: class HttpError extends Error {
+    constructor(
+      public status: number,
+      public response: Response,
+      message: string
+    ) {
+      super(message);
+    }
+  },
+}));
+
+import packageJson from "../../../package.json";
+import { HttpClient } from "../../../src/clients/http";
+import { GenericOpenRouterClient } from "../../../src/clients/openrouter";
+import {
+  KNOWHOW_ATTRIBUTION_HEADERS,
+  withKnowhowAttribution,
+} from "../../../src/clients/attribution";
+
+describe("OpenRouter attribution", () => {
+  beforeEach(() => post.mockReset());
+  afterEach(() => jest.restoreAllMocks());
+
+  it("uses the Knowhow application identity and current package version", () => {
+    expect(KNOWHOW_ATTRIBUTION_HEADERS).toEqual({
+      "HTTP-Referer": "https://knowhow.tyvm.ai",
+      "X-Title": "Knowhow",
+      "X-OpenRouter-Title": "Knowhow",
+      "User-Agent": `knowhow/${packageJson.version}`,
+    });
+  });
+
+  it("applies caller overrides case-insensitively without duplicates", () => {
+    const headers = withKnowhowAttribution({
+      "user-agent": "custom-agent",
+      "HTTP-referer": "https://caller.example",
+      "x-title": "Caller",
+      "x-openrouter-title": "Caller",
+      "X-Custom": "preserved",
+    });
+
+    expect(headers).toEqual({
+      "User-Agent": "custom-agent",
+      "HTTP-Referer": "https://caller.example",
+      "X-Title": "Caller",
+      "X-OpenRouter-Title": "Caller",
+      "X-Custom": "preserved",
+    });
+    for (const name of ["user-agent", "http-referer", "x-title", "x-openrouter-title"]) {
+      expect(
+        Object.keys(headers).filter((key) => key.toLowerCase() === name)
+      ).toHaveLength(1);
+    }
+  });
+
+  it("sends attribution only as OpenRouter request headers", async () => {
+    post.mockResolvedValueOnce({
+      status: 200,
+      headers: new Headers(),
+      data: {
+        choices: [{ message: { role: "assistant", content: "ok" } }],
+        model: "test",
+      },
+    });
+    const client = new GenericOpenRouterClient("test-key");
+    client.setOptions({
+      headers: {
+        "user-agent": "caller-agent",
+        "http-referer": "https://caller.example",
+      },
+    });
+
+    await client.createChatCompletion({
+      model: "test",
+      messages: [{ role: "user", content: "hello" }],
+    });
+
+    const body = post.mock.calls[0][1];
+    const headers = post.mock.calls[0][2].headers;
+    expect(headers).toMatchObject({
+      "HTTP-Referer": "https://caller.example",
+      "X-Title": "Knowhow",
+      "X-OpenRouter-Title": "Knowhow",
+      "User-Agent": "caller-agent",
+      Authorization: "Bearer test-key",
+    });
+    expect(
+      Object.keys(headers).filter(
+        (name) => name.toLowerCase() === "http-referer"
+      )
+    ).toHaveLength(1);
+    expect(
+      Object.keys(headers).filter((name) => name.toLowerCase() === "x-title")
+    ).toHaveLength(1);
+    const serializedBody = JSON.stringify(body);
+    expect(serializedBody).not.toContain("HTTP-Referer");
+    expect(serializedBody).not.toContain("X-OpenRouter-Title");
+    expect(serializedBody).not.toContain("caller-agent");
+  });
+
+  it("does not add OpenRouter attribution to generic provider traffic", async () => {
+    post.mockResolvedValueOnce({
+      status: 200,
+      headers: new Headers(),
+      data: {
+        choices: [{ message: { role: "assistant", content: "ok" } }],
+        model: "test",
+      },
+    });
+    const client = new HttpClient("https://provider.example");
+
+    await client.createChatCompletion({
+      model: "test",
+      messages: [{ role: "user", content: "hello" }],
+    });
+
+    expect(post.mock.calls[0][2].headers).toEqual({});
+  });
+
+  it("sends attribution on OpenRouter embedding requests", async () => {
+    post.mockResolvedValueOnce({
+      status: 200,
+      headers: new Headers(),
+      data: { data: [{ embedding: [1] }], usage: {} },
+    });
+    const client = new GenericOpenRouterClient("initial-key", {
+      headers: { "x-openrouter-title": "Embedding caller" },
+    });
+    client.setKey("replacement-key");
+
+    await client.createEmbedding({ model: "embedding-test", input: "hello" });
+
+    expect(post.mock.calls[0][2].headers).toMatchObject({
+      "HTTP-Referer": "https://knowhow.tyvm.ai",
+      "X-OpenRouter-Title": "Embedding caller",
+      // X-Title was not overridden, so it keeps the default "Knowhow"
+      "X-Title": "Knowhow",
+      "User-Agent": `knowhow/${packageJson.version}`,
+      Authorization: "Bearer replacement-key",
+    });
+  });
+
+  it("sends attribution on OpenRouter streaming requests", async () => {
+    const fetchMock = jest.spyOn(global, "fetch").mockResolvedValueOnce(
+      new Response(
+        'data: {"choices":[{"delta":{"content":"ok"}}]}\n\n' +
+          "data: [DONE]\n\n",
+        {
+          status: 200,
+          headers: { "Content-Type": "text/event-stream" },
+        }
+      )
+    );
+    const client = new GenericOpenRouterClient("test-key", {
+      headers: { "HTTP-referer": "https://stream.example" },
+    });
+
+    const chunks = [];
+    for await (const chunk of client.createChatCompletionStream({
+      model: "test",
+      messages: [{ role: "user", content: "hello" }],
+    })) {
+      chunks.push(chunk);
+    }
+
+    const headers = fetchMock.mock.calls[0][1]?.headers as Record<
+      string,
+      string
+    >;
+    expect(headers).toMatchObject({
+      "HTTP-Referer": "https://stream.example",
+      "X-OpenRouter-Title": "Knowhow",
+      "X-Title": "Knowhow",
+      "User-Agent": `knowhow/${packageJson.version}`,
+      Authorization: "Bearer test-key",
+    });
+    expect(chunks.length).toBeGreaterThan(0);
+  });
+});