@cohortapp/agent-sdk 2.3.0

package/lib/model-router/pricing-refresh.mjs

@@ -0,0 +1,463 @@
+/**
+ * lib/model-router/pricing-refresh.mjs — the OpenClaw external pricing oracle.
+ *
+ * A nightly cadence (NEVER the decision path) refreshes the COST-only layer the
+ * catalog already reads via its authority merge. `refreshPricing({fetchImpl,now})`
+ * fetches two community-maintained pricing sources in parallel —
+ *
+ *   - LiteLLM   model_prices_and_context_window.json  (flat + tiered $/token)
+ *   - OpenRouter /api/v1/models                       (flat $/token, prompt/completion)
+ *
+ * — merges them into `state/model-router/pricing-cache.json` (the flat
+ * `{ "<provider>/<id>": { input, output, cache_read, cache_write, tiered?,
+ * provenance:{source,fetched,volatile} } }` shape `catalog.applyPricingCache`
+ * consumes), and atomically writes it back. Capabilities / compat / grade /
+ * context windows are NEVER touched — this layer updates COST FIELDS ONLY, exactly
+ * as the catalog's authority-merge contract requires.
+ *
+ * Hardening mined from OpenClaw's model-pricing-cache.ts:
+ *   - Injected fetch (no ambient network); 60s per-source timeout; 5MB payload cap.
+ *   - Partial-failure backfill: if one source fails, the other still merges, and
+ *     entries already in the cache survive (we never blow away a good price because
+ *     a refresh round was offline).
+ *   - Provenance stamp per entry: { source: "litellm"|"openrouter"|"litellm+openrouter",
+ *     fetched: ISO, volatile: true } so the catalog's staleness ladder / doctor can
+ *     reason about freshness. `volatile:true` marks "this came from the external
+ *     oracle" (vs human-curated bundled rows).
+ *   - NEVER throws, NEVER on the decision path: a fully-offline refresh returns
+ *     { ok:false, ... } and leaves the existing cache untouched (fail open — stale
+ *     prices beat no prices, and the catalog read path degrades gracefully anyway).
+ *   - $/MTok normalization: both upstreams quote $/token; the cache + catalog speak
+ *     $/MTok, so every rate is multiplied by 1e6.
+ *
+ * Only models the org actually configures matter, but this module does NOT need a
+ * config to be useful: by default it merges the full LiteLLM/OpenRouter universe
+ * keyed by the provider/model ref the catalog uses, and the catalog's
+ * applyPricingCache silently ignores any ref not present in the catalog (it warns,
+ * never errors). An optional `opts.refs` allowlist narrows the write to configured
+ * models when the caller wants a small cache.
+ *
+ * House style (CLAUDE.md): ESM .mjs, Node 20, near-zero-dep, everything injectable
+ * (fetchImpl, now, stateDir/agentRoot, an explicit cache for tests).
+ *
+ * @module lib/model-router/pricing-refresh
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  unlinkSync,
+} from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+
+const SECOND = 1000;
+
+/** Per-source fetch timeout. */
+export const FETCH_TIMEOUT_MS = 60 * SECOND;
+/** Max payload size we will read from a source (DoS guard). */
+export const MAX_PAYLOAD_BYTES = 5 * 1024 * 1024;
+
+const LITELLM_URL =
+  "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
+const OPENROUTER_URL = "https://openrouter.ai/api/v1/models";
+
+/** $/token → $/MTok. */
+const PER_MTOK = 1e6;
+
+// Map an upstream provider namespace → the catalog's provider key. The catalog
+// uses bare provider names (anthropic, deepseek, moonshot, qwen). LiteLLM and
+// OpenRouter both prefix slugs; normalise so refs line up with catalog refs.
+const PROVIDER_ALIASES = Object.freeze({
+  moonshotai: "moonshot",
+  "moonshot-ai": "moonshot",
+  "z-ai": "zai",
+  "deepseek-ai": "deepseek",
+  anthropic: "anthropic",
+  deepseek: "deepseek",
+  moonshot: "moonshot",
+  qwen: "qwen",
+});
+
+// ---------------------------------------------------------------------------
+// Paths / injected primitives
+// ---------------------------------------------------------------------------
+
+function clock(opts) {
+  return opts && typeof opts.now === "function" ? opts.now : Date.now;
+}
+
+function agentRootOf(opts) {
+  return resolve(
+    (opts && opts.agentRoot) ||
+      process.env.AGENT_ROOT ||
+      process.env.AGENT_DIR ||
+      process.cwd()
+  );
+}
+
+function cachePath(opts) {
+  if (opts && opts.cachePath) return resolve(opts.cachePath);
+  if (opts && opts.stateDir) return join(resolve(opts.stateDir), "pricing-cache.json");
+  return join(agentRootOf(opts), "state", "model-router", "pricing-cache.json");
+}
+
+// ---------------------------------------------------------------------------
+// Existing-cache read (for backfill)
+// ---------------------------------------------------------------------------
+
+function readExistingCache(opts) {
+  if (opts && opts.existingCache !== undefined) {
+    const c = opts.existingCache;
+    return c && typeof c === "object" ? unwrapEntries(c) : {};
+  }
+  const p = cachePath(opts);
+  if (!existsSync(p)) return {};
+  try {
+    const raw = JSON.parse(readFileSync(p, "utf-8"));
+    return raw && typeof raw === "object" ? unwrapEntries(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Accept both `{models:{...}}` and flat `{ "<ref>": {...} }`. */
+function unwrapEntries(obj) {
+  if (obj.models && typeof obj.models === "object") return { ...obj.models };
+  return { ...obj };
+}
+
+// ---------------------------------------------------------------------------
+// Fetch (injected; bounded; never throws)
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch + JSON-parse one source with a timeout and a payload cap. Returns
+ * `{ ok:true, json }` or `{ ok:false, error }`. NEVER throws.
+ */
+async function fetchJson(fetchImpl, url, opts) {
+  if (typeof fetchImpl !== "function") {
+    return { ok: false, error: "no_fetch_impl" };
+  }
+  // AbortController is a Node 20 global; guard for exotic runtimes.
+  let signal;
+  let timer = null;
+  try {
+    if (typeof AbortController === "function") {
+      const ac = new AbortController();
+      signal = ac.signal;
+      timer = setTimeout(() => {
+        try { ac.abort(); } catch { /* */ }
+      }, FETCH_TIMEOUT_MS);
+      if (timer && typeof timer.unref === "function") timer.unref();
+    }
+  } catch { /* */ }
+
+  try {
+    const res = await fetchImpl(url, signal ? { signal } : {});
+    if (!res || (typeof res.ok === "boolean" && !res.ok)) {
+      return { ok: false, error: `http_${(res && res.status) || "error"}` };
+    }
+    // Read the body as text first so we can enforce the byte cap before parsing.
+    let text;
+    if (typeof res.text === "function") {
+      text = await res.text();
+    } else if (typeof res.json === "function") {
+      // No text() — fall back to json() (the byte cap is best-effort here).
+      const j = await res.json();
+      return { ok: true, json: j };
+    } else {
+      return { ok: false, error: "no_body_reader" };
+    }
+    if (typeof text === "string" && Buffer.byteLength(text, "utf8") > MAX_PAYLOAD_BYTES) {
+      return { ok: false, error: "payload_too_large" };
+    }
+    try {
+      return { ok: true, json: JSON.parse(text) };
+    } catch (err) {
+      return { ok: false, error: `parse_failed:${err && err.message}` };
+    }
+  } catch (err) {
+    return { ok: false, error: `fetch_failed:${(err && err.message) || err}` };
+  } finally {
+    if (timer) { try { clearTimeout(timer); } catch { /* */ } }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Source parsers → Map<ref, {input,output,cache_read,cache_write,tiered?}>
+// ---------------------------------------------------------------------------
+
+function num(v) {
+  const n = Number(v);
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+/** Normalise an upstream provider segment to the catalog's provider key. */
+function canonProvider(p) {
+  const k = String(p || "").trim().toLowerCase();
+  return PROVIDER_ALIASES[k] || k;
+}
+
+/**
+ * Parse the LiteLLM model_prices_and_context_window.json. Keys look like
+ * "deepseek/deepseek-chat", "claude-sonnet-4-6" (no provider) or
+ * "anthropic/claude-...". Each value has input/output_cost_per_token plus
+ * cache_read/creation variants and `litellm_provider`.
+ *
+ * @returns {Map<string,object>} ref → cost block ($/MTok)
+ */
+export function parseLiteLLM(json) {
+  const out = new Map();
+  if (!json || typeof json !== "object") return out;
+  for (const [rawKey, v] of Object.entries(json)) {
+    if (rawKey === "sample_spec") continue;
+    if (!v || typeof v !== "object") continue;
+    const ref = litellmRef(rawKey, v);
+    if (!ref) continue;
+    const input = num(v.input_cost_per_token);
+    const output = num(v.output_cost_per_token);
+    if (input == null && output == null) continue; // no usable price
+    const cacheRead = num(
+      v.cache_read_input_token_cost ?? v.input_cost_per_token_cache_hit
+    );
+    const cacheWrite = num(v.cache_creation_input_token_cost);
+    out.set(ref, scaleCost({ input, output, cache_read: cacheRead, cache_write: cacheWrite }));
+  }
+  return out;
+}
+
+/** Derive the catalog ref "provider/model" from a LiteLLM key + value. */
+function litellmRef(rawKey, v) {
+  const key = String(rawKey).trim();
+  if (!key) return null;
+  if (key.includes("/")) {
+    const [prov, ...rest] = key.split("/");
+    return `${canonProvider(prov)}/${rest.join("/")}`;
+  }
+  // No provider in the key — fall back to litellm_provider.
+  const prov = v.litellm_provider ? canonProvider(v.litellm_provider) : null;
+  if (!prov) return null;
+  return `${prov}/${key}`;
+}
+
+/**
+ * Parse OpenRouter /api/v1/models. Shape: { data: [ { id:"deepseek/deepseek-chat",
+ * pricing:{ prompt:"0.00000014", completion:"0.00000028", input_cache_read?, ... } } ] }.
+ *
+ * @returns {Map<string,object>} ref → cost block ($/MTok)
+ */
+export function parseOpenRouter(json) {
+  const out = new Map();
+  const data = json && Array.isArray(json.data) ? json.data : Array.isArray(json) ? json : [];
+  for (const m of data) {
+    if (!m || typeof m !== "object" || typeof m.id !== "string") continue;
+    const id = m.id.trim();
+    if (!id.includes("/")) continue;
+    const [prov, ...rest] = id.split("/");
+    const ref = `${canonProvider(prov)}/${rest.join("/")}`;
+    const p = m.pricing && typeof m.pricing === "object" ? m.pricing : {};
+    const input = num(p.prompt);
+    const output = num(p.completion);
+    if (input == null && output == null) continue;
+    const cacheRead = num(p.input_cache_read);
+    const cacheWrite = num(p.input_cache_write);
+    out.set(ref, scaleCost({ input, output, cache_read: cacheRead, cache_write: cacheWrite }));
+  }
+  return out;
+}
+
+/** Multiply $/token rates to $/MTok; drop null fields. */
+function scaleCost(block) {
+  const out = {};
+  for (const f of ["input", "output", "cache_read", "cache_write"]) {
+    if (block[f] != null) out[f] = round6(block[f] * PER_MTOK);
+  }
+  return out;
+}
+
+function round6(n) {
+  return Math.round(n * 1e6) / 1e6;
+}
+
+// ---------------------------------------------------------------------------
+// Merge: OpenRouter base + LiteLLM (LiteLLM wins on conflict — it has cache tiers
+// and is the more authoritative pricing JSON, mirroring OpenClaw's strategy of
+// "OpenRouter base + LiteLLM tiers").
+// ---------------------------------------------------------------------------
+
+function mergeSources(openrouter, litellm, fetchedISO, sources) {
+  const refs = new Set([...openrouter.keys(), ...litellm.keys()]);
+  const merged = {};
+  for (const ref of refs) {
+    const orBlock = openrouter.get(ref) || {};
+    const llBlock = litellm.get(ref) || {};
+    const cost = { ...orBlock, ...llBlock }; // LiteLLM wins field-wise
+    if (!Object.keys(cost).length) continue;
+    const inBoth = openrouter.has(ref) && litellm.has(ref);
+    const source = inBoth
+      ? "litellm+openrouter"
+      : litellm.has(ref)
+        ? "litellm"
+        : "openrouter";
+    merged[ref] = {
+      ...cost,
+      provenance: { source, fetched: fetchedISO, volatile: true },
+    };
+  }
+  return merged;
+}
+
+// ---------------------------------------------------------------------------
+// Atomic write (never throws)
+// ---------------------------------------------------------------------------
+
+function writeCache(path, entries, opts) {
+  if (opts && opts.noWrite) return true; // test hook: skip the FS write
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}.${Date.now()}.${randomBytes(2).toString("hex")}`;
+    writeFileSync(tmp, JSON.stringify({ models: entries }, null, 2) + "\n");
+    try {
+      renameSync(tmp, path);
+    } catch (err) {
+      try { unlinkSync(tmp); } catch { /* */ }
+      throw err;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// refreshPricing — public entry point (nightly cadence)
+// ---------------------------------------------------------------------------
+
+/**
+ * Refresh the cost-only pricing cache from LiteLLM + OpenRouter. NEVER throws,
+ * NEVER on the decision path. Fail-open: if BOTH sources fail (offline), the
+ * existing cache is left untouched and `{ ok:false }` is returned.
+ *
+ * @param {object} [opts]
+ *   @param {function} opts.fetchImpl         injected fetch (REQUIRED for a network refresh)
+ *   @param {()=>number} [opts.now]
+ *   @param {string}   [opts.agentRoot]
+ *   @param {string}   [opts.stateDir]        override state dir (writes <dir>/pricing-cache.json)
+ *   @param {string}   [opts.cachePath]       override the exact cache file path
+ *   @param {object}   [opts.existingCache]   bypass-FS existing cache (tests)
+ *   @param {boolean}  [opts.noWrite]         compute the merge but skip the FS write (tests)
+ *   @param {string[]} [opts.refs]            optional allowlist: only write these refs
+ *   @param {string}   [opts.litellmUrl]
+ *   @param {string}   [opts.openrouterUrl]
+ * @returns {Promise<{
+ *   ok:boolean, written:number, sources:string[], errors:Array<{source:string,error:string}>,
+ *   cache:object, fetchedAt:string, path:string|null
+ * }>}
+ */
+export async function refreshPricing(opts = {}) {
+  const fetchImpl = opts.fetchImpl;
+  const now = clock(opts)();
+  const fetchedISO = new Date(now).toISOString();
+  const errors = [];
+  const okSources = [];
+
+  // Fetch both in parallel; each failure is recorded, not thrown.
+  const [llRes, orRes] = await Promise.all([
+    fetchJson(fetchImpl, opts.litellmUrl || LITELLM_URL, opts),
+    fetchJson(fetchImpl, opts.openrouterUrl || OPENROUTER_URL, opts),
+  ]);
+
+  let litellm = new Map();
+  let openrouter = new Map();
+
+  if (llRes.ok) {
+    try {
+      litellm = parseLiteLLM(llRes.json);
+      okSources.push("litellm");
+    } catch (err) {
+      errors.push({ source: "litellm", error: `parse_threw:${err && err.message}` });
+    }
+  } else {
+    errors.push({ source: "litellm", error: llRes.error });
+  }
+
+  if (orRes.ok) {
+    try {
+      openrouter = parseOpenRouter(orRes.json);
+      okSources.push("openrouter");
+    } catch (err) {
+      errors.push({ source: "openrouter", error: `parse_threw:${err && err.message}` });
+    }
+  } else {
+    errors.push({ source: "openrouter", error: orRes.error });
+  }
+
+  const existing = readExistingCache(opts);
+  const path = cachePath(opts);
+
+  // BOTH sources failed → fail open: leave the cache untouched.
+  if (okSources.length === 0) {
+    return {
+      ok: false,
+      written: 0,
+      sources: [],
+      errors,
+      cache: existing,
+      fetchedAt: fetchedISO,
+      path: null,
+    };
+  }
+
+  // Merge fresh sources, then backfill from the existing cache so a partial
+  // failure (one source offline) never deletes a previously-good price.
+  const fresh = mergeSources(openrouter, litellm, fetchedISO, okSources);
+
+  // Backfill: keep existing entries that the fresh merge did not refresh.
+  const merged = { ...existing };
+  for (const [ref, block] of Object.entries(fresh)) {
+    merged[ref] = block;
+  }
+
+  // Optional allowlist: only write the configured refs.
+  let outEntries = merged;
+  if (Array.isArray(opts.refs) && opts.refs.length) {
+    const allow = new Set(opts.refs);
+    outEntries = {};
+    for (const [ref, block] of Object.entries(merged)) {
+      if (allow.has(ref)) outEntries[ref] = block;
+    }
+  }
+
+  const wroteOk = writeCache(path, outEntries, opts);
+
+  return {
+    ok: true,
+    written: Object.keys(fresh).length,
+    sources: okSources,
+    errors,
+    cache: outEntries,
+    fetchedAt: fetchedISO,
+    path: wroteOk && !opts.noWrite ? path : null,
+  };
+}
+
+export const _internals = {
+  parseLiteLLM,
+  parseOpenRouter,
+  mergeSources,
+  scaleCost,
+  canonProvider,
+  litellmRef,
+  fetchJson,
+  readExistingCache,
+  LITELLM_URL,
+  OPENROUTER_URL,
+  PER_MTOK,
+  PROVIDER_ALIASES,
+};
+
+export default { refreshPricing, parseLiteLLM, parseOpenRouter };