@tyvm/knowhow 0.0.156 → 0.0.158

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/fireworks.ts

@@ -11,6 +11,10 @@ import { ModelPricing, ModelCatalogEntry, completions, embeddings } from "./type
 export const FireworksModels = {
   // Moonshot AI
   KimiK3:      "accounts/fireworks/models/kimi-k3",
+
+  // Meta
+  MuseGlimmer30b: "accounts/fireworks/models/muse-glimmer-30b",
+
   KimiK2p7Code: "accounts/fireworks/models/kimi-k2p7-code",
   KimiK2_6:    "accounts/fireworks/models/kimi-k2-6",
   KimiK2_5:    "accounts/fireworks/models/kimi-k2-5",
@@ -22,6 +26,13 @@ export const FireworksModels = {
 
   // Qwen
   Qwen3p7Plus: "accounts/fireworks/models/qwen3p7-plus",
+  Qwen3p8Max:  "accounts/fireworks/models/qwen3p8-2p4t-a95b",
+
+  // NVIDIA
+  NemotronLightning3p530bA3b: "accounts/fireworks/models/nemotron-lightning-3p5-30b-a3b",
+
+  // Thinking Machines Lab
+  Inkling: "accounts/fireworks/models/inkling",
 
   // Deprecated Qwen Models
   Qwen3_6Plus:                "accounts/fireworks/models/qwen3-6-plus",
@@ -56,6 +67,10 @@ export const FireworksTextPricing: Record<string, ModelPricing> = {
   // Moonshot AI
   [FireworksModels.KimiK3]:       { input: 3.0, cache_hit: 0.30, output: 15.0 },
   [FireworksModels.KimiK2p7Code]: { input: 0.95, cache_hit: 0.19, output: 4.0 },
+
+  // Meta
+  [FireworksModels.MuseGlimmer30b]: { input: 0.35, cache_hit: 0.04, output: 1.50 },
+
   [FireworksModels.KimiK2_6]:     { input: 0.95, cache_hit: 0.16, output: 4.0 },
   [FireworksModels.KimiK2_5]:     { input: 0.60, cache_hit: 0.10, output: 3.0 },
 
@@ -67,6 +82,14 @@ export const FireworksTextPricing: Record<string, ModelPricing> = {
   // Qwen
   [FireworksModels.Qwen3p7Plus]:  { input: 0.40, cache_hit: 0.08, output: 1.60 },
 
+  [FireworksModels.Qwen3p8Max]:   { input: 2.00, cache_hit: 0.25, output: 6.00 },
+
+  // NVIDIA
+  [FireworksModels.NemotronLightning3p530bA3b]: { input: 0.05, cache_hit: 0.01, output: 0.20 },
+
+  // Thinking Machines Lab
+  [FireworksModels.Inkling]: { input: 1.00, cache_hit: 0.17, output: 4.05 },
+
   // Deprecated QWEN Models
   [FireworksModels.Qwen3_6Plus]:           { input: 0.50, cache_hit: 0.10, output: 3.0, deprecated: true },
   [FireworksModels.Qwen3p6Plus]:           { input: 0.50, cache_hit: 0.10, output: 3.0, deprecated: true },
@@ -81,8 +104,8 @@ export const FireworksTextPricing: Record<string, ModelPricing> = {
   [FireworksModels.Glm4_7]: { input: 0.60, cache_hit: 0.30, output: 2.20, deprecated: true },
 
   // DeepSeek AI
-  [FireworksModels.DeepseekV4Pro]:   { input: 1.74, cache_hit: 0.15, output: 3.48 },
-  [FireworksModels.DeepseekV4Flash]: { input: 0.14, cache_hit: 0.03, output: 0.28 },
+  [FireworksModels.DeepseekV4Pro]:   { input: 1.32, cache_hit: 0.044, output: 3.96 },
+  [FireworksModels.DeepseekV4Flash]: { input: 0.22, cache_hit: 0.007, output: 0.66 },
   [FireworksModels.DeepseekV3_2]:    { input: 0.56, cache_hit: 0.28, output: 1.68, deprecated: true },
   [FireworksModels.DeepseekV3_1]:    { input: 0.56, cache_hit: 0.28, output: 1.68, deprecated: true },
 
@@ -111,12 +134,19 @@ export const FireworksActiveTextModels: string[] = [
   FireworksModels.KimiK2p7Code,
   FireworksModels.KimiK2_6,
   FireworksModels.KimiK2_5,
+  // Meta
+  FireworksModels.MuseGlimmer30b,
   // MiniMax
   FireworksModels.MinimaxM3,
   FireworksModels.MinimaxM2_7,
   FireworksModels.MinimaxM2_5,
   // Qwen
   FireworksModels.Qwen3p7Plus,
+  FireworksModels.Qwen3p8Max,
+  // NVIDIA
+  FireworksModels.NemotronLightning3p530bA3b,
+  // Thinking Machines Lab
+  FireworksModels.Inkling,
   // Z.ai
   FireworksModels.Glm5p2,
   FireworksModels.Glm5p1,

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/src/commands/mcp.ts

@@ -273,6 +273,7 @@ export function addMcpCommands(program: Command): void {
         await listRemoteSecrets();
       }
     });
+
 }
 
 // ──────────────────────────────────────────────────────────────────────────────

package/src/commands/misc.ts

@@ -63,7 +63,7 @@ export function addLoginCommand(program: Command): void {
         return;
       }
 
-      await login(options.jwt, options.identity);
+      await login(options.jwt, options.identity, options.apiUrl);
     });
 }
 

package/src/commands/remote.ts

@@ -0,0 +1,77 @@
+import { Command } from "commander";
+import { getConfig, updateConfig } from "../config";
+import {
+  createRemote,
+  DEFAULT_API_URL,
+  DEFAULT_REMOTE_NAME,
+  getConfiguredRemotes,
+  registerRemote,
+} from "../remotes";
+
+export function addRemoteCommand(program: Command): void {
+  const command = program
+    .command("remote")
+    .description("Manage Knowhow API remotes");
+
+  command
+    .command("add")
+    .description("Register a Knowhow-compatible backend")
+    .argument("<name>", "Remote name")
+    .argument("<api-url>", "API base URL")
+    .action(async (name: string, apiUrl: string) => {
+      const config = await getConfig();
+      if (config.remotes?.[name]) {
+        throw new Error(`Remote '${name}' already exists.`);
+      }
+      const remote = createRemote(name, apiUrl);
+      registerRemote(config, remote);
+      await updateConfig(config);
+      console.log(`Added remote '${name}' (${remote.apiUrl}).`);
+    });
+
+  command
+    .command("use")
+    .description("Select the remote used by Knowhow commands in this configuration")
+    .argument("<name>", "Remote name")
+    .action(async (name: string) => {
+      const config = await getConfig();
+      const remote = getConfiguredRemotes(config)[name] ??
+        (name === DEFAULT_REMOTE_NAME ? createRemote(DEFAULT_REMOTE_NAME, DEFAULT_API_URL) : undefined);
+      if (!remote) {
+        throw new Error(`Unknown remote '${name}'. Add it with: knowhow remote add ${name} <api-url>`);
+      }
+      registerRemote(config, remote);
+      config.activeRemote = name;
+      await updateConfig(config);
+      console.log(`Using remote '${name}' (${remote.apiUrl}).`);
+    });
+
+  command
+    .command("list")
+    .alias("ls")
+    .description("List configured remotes")
+    .action(async () => {
+      const config = await getConfig();
+      const remotes = { ...getConfiguredRemotes(config) };
+      if (!remotes[DEFAULT_REMOTE_NAME]) {
+        remotes[DEFAULT_REMOTE_NAME] = createRemote(DEFAULT_REMOTE_NAME, DEFAULT_API_URL);
+      }
+      for (const [name, remote] of Object.entries(remotes)) {
+        const marker = (config.activeRemote ?? DEFAULT_REMOTE_NAME) === name ? "*" : " ";
+        console.log(`${marker} ${name}\t${remote.apiUrl}\t${remote.jwtPath}${remote.orgId ? `\t${remote.orgId}` : ""}`);
+      }
+    });
+
+  command
+    .command("get-url")
+    .description("Print a remote API URL")
+    .argument("[name]", "Remote name")
+    .action(async (name?: string) => {
+      const config = await getConfig();
+      const selectedName = name ?? config.activeRemote ?? DEFAULT_REMOTE_NAME;
+      const remote = getConfiguredRemotes(config)[selectedName] ??
+        (selectedName === DEFAULT_REMOTE_NAME ? createRemote(DEFAULT_REMOTE_NAME, DEFAULT_API_URL) : undefined);
+      if (!remote) throw new Error(`Unknown remote '${selectedName}'.`);
+      console.log(remote.apiUrl);
+    });
+}

package/src/config.ts

@@ -4,7 +4,6 @@ import * as os from "os";
 import gitignoreToGlob from "gitignore-to-glob";
 import { Prompts } from "./prompts";
 import { promisify } from "util";
-import { KNOWHOW_API_URL } from "./services/KnowhowClient";
 import {
   Config,
   SourceRef,
@@ -113,6 +112,15 @@ const defaultConfig = {
     },
   },
 
+  activeRemote: "origin",
+  remotes: {
+    origin: {
+      name: "origin",
+      apiUrl: "https://api.knowhow.tyvm.ai",
+      jwtPath: ".knowhow/.jwt",
+    },
+  },
+
   syncRemote: false,
 } as Config;