katman-mcp 0.1.0

package/dist/tools/visibility/openrouter.js

@@ -0,0 +1,449 @@
+// OpenRouter access for visibility runs: public model catalog (cached 24 h in .katman/cache),
+// key check, a retrying chat client, and the request/response shapes. Docs verified 2026-09-30:
+// - web search: `tools: [{type: "openrouter:web_search", parameters: {engine, max_uses, ...}}]`
+//   (the `web` plugin still works but is deprecated; used only as a fallback surface)
+// - every response carries `usage.cost` (USD); `usage: {include: true}` is a deprecated no-op
+// - searches: `usage.server_tool_use.web_search_requests` (OpenAPI: `server_tool_use_details`)
+// - citations: `message.annotations[{type: "url_citation", url_citation: {url, title}}]`
+// - 402 with `error.metadata.limit_source = "openrouter_in_flight_budget"` is transient (Retry-After);
+//   any other 402 means the balance or key limit is exhausted
+// - `GET /api/v1/key` works with a normal key; `/credits` needs a management key
+import { mapLimit, sleep } from "../../net.js";
+import { readJson, writeJson, writeText, readText } from "../../state.js";
+import { EXA_PRICE_PER_SEARCH, FALLBACK_PRICES, MAX_SEARCHES_PER_ANSWER, countryForLang, engineOf, vendorOf, } from "./models.js";
+export const OPENROUTER_API = "https://openrouter.ai/api/v1";
+export const ATTRIBUTION_HEADERS = {
+    "HTTP-Referer": "https://katman.pro",
+    "X-OpenRouter-Title": "Katman MCP",
+    "X-Title": "Katman MCP",
+};
+export const CATALOG_CACHE = "cache/models.json";
+export const CATALOG_MAX_AGE_MS = 24 * 3600 * 1000;
+export const ANSWER_TIMEOUT_MS = 90_000;
+const KEY_VARS = ["OPENROUTER_API_KEY", "KATMAN_OPENROUTER_API_KEY"];
+/** The user's key from the environment. Never logged, printed or written to disk. */
+export function getApiKey(env = process.env) {
+    for (const name of KEY_VARS) {
+        const v = (env[name] ?? "").trim();
+        if (v)
+            return { key: v, source: name };
+    }
+    return {};
+}
+/** Strip anything that looks like a key or bearer token from text we show or store. */
+export function redact(s) {
+    return s
+        .replace(/sk-or-[A-Za-z0-9_-]{4,}/g, "sk-or-…")
+        .replace(/Bearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, "Bearer …");
+}
+async function getJson(fetchImpl, url, timeoutMs, headers = {}) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, { headers: { accept: "application/json", ...ATTRIBUTION_HEADERS, ...headers }, signal: ctrl.signal });
+        const text = await res.text();
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            json = undefined;
+        }
+        return { status: res.status, json };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function trimModel(m) {
+    if (typeof m.id !== "string")
+        return undefined;
+    const p = (m.pricing ?? {});
+    const str = (v) => (typeof v === "string" || typeof v === "number" ? String(v) : undefined);
+    const r = m.reasoning;
+    return {
+        id: m.id,
+        name: typeof m.name === "string" ? m.name : undefined,
+        created: typeof m.created === "number" ? m.created : undefined,
+        pricing: { prompt: str(p.prompt), completion: str(p.completion), web_search: str(p.web_search), request: str(p.request) },
+        supported_parameters: Array.isArray(m.supported_parameters) ? m.supported_parameters.filter((x) => typeof x === "string") : [],
+        reasoning: r && typeof r === "object"
+            ? { mandatory: r.mandatory, default_enabled: r.default_enabled, supported_efforts: r.supported_efforts, default_effort: r.default_effort }
+            : null,
+    };
+}
+export async function fetchModelList(fetchImpl = fetch) {
+    const { status, json } = await getJson(fetchImpl, `${OPENROUTER_API}/models`, 30_000);
+    const data = json?.data;
+    if (status !== 200 || !Array.isArray(data))
+        throw new Error(`GET /models returned ${status}`);
+    return data.map((m) => trimModel(m)).filter((m) => !!m);
+}
+const SERVICE_TIER = /\/(fast|flex|priority)$/i;
+export async function fetchEndpoints(id, fetchImpl = fetch, now = new Date()) {
+    const base = id.split(":")[0];
+    const { status, json } = await getJson(fetchImpl, `${OPENROUTER_API}/models/${base}/endpoints`, 15_000);
+    const eps = (json?.data?.endpoints ?? []);
+    if (status !== 200)
+        throw new Error(`GET /models/${base}/endpoints returned ${status}`);
+    const tags = [];
+    const nativeSearchTags = [];
+    for (const e of eps) {
+        const tag = typeof e.tag === "string" ? e.tag : undefined;
+        // Service-tier endpoints (openai/fast, xai/priority, …/flex) are opt-in and priced differently: naming them in
+        // provider.only would opt into that tier, so they are never pinned.
+        if (!tag || SERVICE_TIER.test(tag))
+            continue;
+        tags.push(tag);
+        const nt = e.native_tools;
+        if (nt && nt["openrouter:web_search"])
+            nativeSearchTags.push(tag);
+    }
+    return { fetchedAt: now.toISOString(), tags, nativeSearchTags };
+}
+/**
+ * Public model catalog (no key needed): cached in .katman/cache/models.json for 24 h.
+ * `root` undefined = in-memory only (CLI `models` outside a project).
+ */
+export async function loadCatalog(root, o = {}) {
+    const fetchImpl = o.fetchImpl ?? fetch;
+    const now = o.now ?? new Date();
+    const maxAge = o.maxAgeMs ?? CATALOG_MAX_AGE_MS;
+    const cached = root ? await readJson(root, CATALOG_CACHE) : undefined;
+    let file = cached && Array.isArray(cached.models) && cached.fetchedAt ? { ...cached, endpoints: cached.endpoints ?? {} } : undefined;
+    let source;
+    let warning;
+    let dirty = false;
+    const age = file ? now.getTime() - Date.parse(file.fetchedAt) : Infinity;
+    if (file && age >= 0 && age < maxAge)
+        source = "cache";
+    else if (o.offline)
+        source = file ? "stale-cache" : "none";
+    else {
+        try {
+            const models = await fetchModelList(fetchImpl);
+            file = { version: 1, fetchedAt: now.toISOString(), models, endpoints: file?.endpoints ?? {} };
+            source = "live";
+            dirty = true;
+        }
+        catch (e) {
+            source = file ? "stale-cache" : "none";
+            warning = `Could not fetch the OpenRouter model list (${redact(e instanceof Error ? e.message : String(e))}); ${file ? `using the cached list from ${file.fetchedAt.slice(0, 16).replace("T", " ")} UTC` : "using built-in prices verified 2026-09-30"}.`;
+        }
+    }
+    // Endpoint info needs the network: skip it when the model list could not be fetched either.
+    if (!o.offline && o.endpointIds?.length && (source === "live" || source === "cache")) {
+        const f = file ?? { version: 1, fetchedAt: now.toISOString(), models: [], endpoints: {} };
+        const need = [...new Set(o.endpointIds.map((id) => id.split(":")[0]))].filter((id) => {
+            const e = f.endpoints[id];
+            return !e || now.getTime() - Date.parse(e.fetchedAt) >= maxAge;
+        });
+        await mapLimit(need, 5, async (id) => {
+            try {
+                f.endpoints[id] = await fetchEndpoints(id, fetchImpl, now);
+                dirty = true;
+            }
+            catch {
+                // endpoint info is an optimisation (provider pinning); static pins apply without it
+            }
+        });
+        file = f;
+    }
+    if (root && file && dirty) {
+        await writeJson(root, CATALOG_CACHE, file);
+        // The cache is regenerated data: keep it out of git (the monitoring workflow commits .katman/).
+        if ((await readText(root, "cache/.gitignore")) === undefined)
+            await writeText(root, "cache/.gitignore", "*\n");
+    }
+    return {
+        source,
+        fetchedAt: file?.fetchedAt,
+        models: new Map((file?.models ?? []).map((m) => [m.id, m])),
+        endpoints: file?.endpoints ?? {},
+        warning,
+    };
+}
+/** true/false when the catalog is known, undefined when it could not be loaded. */
+export function isInCatalog(c, slug) {
+    if (!c || c.source === "none" || c.models.size === 0)
+        return undefined;
+    return c.models.has(slug.split(":")[0]);
+}
+function num(v) {
+    if (v === undefined)
+        return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+export function priceOf(c, slug) {
+    const id = slug.split(":")[0];
+    const m = c?.models.get(id);
+    if (m) {
+        const prompt = num(m.pricing.prompt);
+        const completion = num(m.pricing.completion);
+        if (prompt !== undefined && completion !== undefined) {
+            return { prompt, completion, webSearch: num(m.pricing.web_search) ?? 0.01, request: num(m.pricing.request) ?? 0, source: "catalog" };
+        }
+    }
+    const f = FALLBACK_PRICES[id];
+    if (f)
+        return { ...f, request: 0, source: "builtin" };
+    return { prompt: 3e-6, completion: 15e-6, webSearch: 0.01, request: 0, source: "unknown" };
+}
+/** Price of one search for this spec: the provider's own fee for native search, Exa's for OpenRouter-run search. */
+export function searchUnitPrice(spec, p) {
+    const engine = engineOf(spec);
+    if (engine === "none")
+        return 0;
+    if (engine === "exa")
+        return EXA_PRICE_PER_SEARCH;
+    return p.webSearch + p.request;
+}
+export async function fetchKeyInfo(key, fetchImpl = fetch) {
+    try {
+        const { status, json } = await getJson(fetchImpl, `${OPENROUTER_API}/key`, 15_000, { Authorization: `Bearer ${key}` });
+        const d = json?.data;
+        if (status !== 200 || !d) {
+            const msg = json?.error?.message;
+            return { ok: false, status, error: redact(msg ?? `HTTP ${status}`) };
+        }
+        const n = (v) => (typeof v === "number" ? v : v === null ? null : undefined);
+        return {
+            ok: true,
+            status,
+            limit: n(d.limit),
+            limitRemaining: n(d.limit_remaining),
+            usage: typeof d.usage === "number" ? d.usage : undefined,
+            isFreeTier: typeof d.is_free_tier === "boolean" ? d.is_free_tier : undefined,
+        };
+    }
+    catch (e) {
+        return { ok: false, status: 0, error: redact(e instanceof Error ? e.message : String(e)) };
+    }
+}
+export class OpenRouterError extends Error {
+    kind;
+    status;
+    extra;
+    constructor(kind, message, status = 0, extra = {}) {
+        super(redact(message));
+        this.kind = kind;
+        this.status = status;
+        this.extra = extra;
+        this.name = "OpenRouterError";
+    }
+}
+export function isRetriable(e) {
+    if (e.kind === "credits")
+        return e.extra.limitSource === "openrouter_in_flight_budget" && e.extra.retryAfterMs !== undefined;
+    return e.kind === "rate" || e.kind === "server" || e.kind === "timeout" || e.kind === "network";
+}
+function retryAfterMs(h) {
+    const v = h.get("retry-after");
+    if (!v)
+        return undefined;
+    const s = Number(v);
+    if (Number.isFinite(s))
+        return Math.max(0, s * 1000);
+    const t = Date.parse(v);
+    return Number.isFinite(t) ? Math.max(0, t - Date.now()) : undefined;
+}
+function kindForCode(code) {
+    if (code === 401)
+        return "auth";
+    if (code === 402)
+        return "credits";
+    if (code === 403)
+        return "forbidden";
+    if (code === 404)
+        return "not_found";
+    if (code === 408)
+        return "timeout";
+    if (code === 429)
+        return "rate";
+    if (code >= 500)
+        return "server";
+    if (code >= 400)
+        return "bad_request";
+    return "provider";
+}
+async function postOnce(key, body, o) {
+    const fetchImpl = o.fetchImpl ?? fetch;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), o.timeoutMs ?? ANSWER_TIMEOUT_MS);
+    let res;
+    let text;
+    try {
+        res = await fetchImpl(`${OPENROUTER_API}/chat/completions`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json", ...ATTRIBUTION_HEADERS },
+            body: JSON.stringify(body),
+            signal: ctrl.signal,
+        });
+        text = await res.text();
+    }
+    catch (e) {
+        if (ctrl.signal.aborted)
+            throw new OpenRouterError("timeout", `no answer within ${Math.round((o.timeoutMs ?? ANSWER_TIMEOUT_MS) / 1000)} s`);
+        throw new OpenRouterError("network", e instanceof Error ? e.message : String(e));
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        json = undefined;
+    }
+    const err = json?.error;
+    if (!res.ok) {
+        const message = typeof err?.message === "string" ? err.message : `HTTP ${res.status}`;
+        throw new OpenRouterError(kindForCode(res.status), message, res.status, {
+            limitSource: typeof err?.metadata?.limit_source === "string" ? err.metadata.limit_source : undefined,
+            retryAfterMs: retryAfterMs(res.headers),
+        });
+    }
+    if (!json)
+        throw new OpenRouterError("server", "OpenRouter returned a response that is not JSON", res.status);
+    if (err) {
+        // A provider failure after the request was accepted arrives as HTTP 200 with an error body.
+        const code = typeof err.code === "number" ? err.code : Number(err.code) || 502;
+        const message = typeof err.message === "string" ? err.message : "provider error";
+        throw new OpenRouterError(kindForCode(code), message, code);
+    }
+    return json;
+}
+/** POST /chat/completions with retries: 429/5xx/timeouts back off exponentially (3 attempts by default). */
+export async function postChat(key, body, o = {}) {
+    const attempts = Math.max(1, o.attempts ?? 3);
+    const wait = o.sleepFn ?? sleep;
+    let last;
+    for (let i = 1; i <= attempts; i++) {
+        try {
+            return await postOnce(key, body, o);
+        }
+        catch (e) {
+            last = e instanceof OpenRouterError ? e : new OpenRouterError("network", e instanceof Error ? e.message : String(e));
+            if (!isRetriable(last) || i === attempts)
+                throw last;
+            const backoff = 1000 * 2 ** (i - 1) + Math.floor(Math.random() * 300);
+            await wait(Math.min(30_000, last.extra.retryAfterMs ?? backoff));
+        }
+    }
+    throw last ?? new OpenRouterError("network", "request failed");
+}
+export function tuningFor(spec, m, ep) {
+    const v = vendorOf(spec.id);
+    const efforts = m?.reasoning?.supported_efforts ?? [];
+    let reasoningEffort;
+    if (v !== "perplexity") {
+        if (efforts.length)
+            reasoningEffort = ["low", "minimal", "medium"].find((e) => efforts.includes(e)) ?? efforts[efforts.length - 1];
+        else if (!m && v)
+            reasoningEffort = "low";
+    }
+    const reasoningOn = !!reasoningEffort || !!m?.reasoning?.mandatory || !!m?.reasoning?.default_enabled;
+    const temperature = m ? m.supported_parameters.includes("temperature") : v !== "openai";
+    let providerOnly;
+    let providerIgnore;
+    if (engineOf(spec) === "native" && v && v !== "perplexity") {
+        if (ep && ep.tags.length) {
+            if (ep.nativeSearchTags.length && ep.nativeSearchTags.length < ep.tags.length) {
+                providerOnly = [...new Set(ep.nativeSearchTags)];
+                providerIgnore = [...new Set(ep.tags.filter((t) => !ep.nativeSearchTags.includes(t)))];
+            }
+        }
+        else if (v === "anthropic")
+            providerOnly = ["anthropic", "claude-on-aws"];
+    }
+    // ~1200 answer tokens; reasoning models get room to think first so the answer is not cut off.
+    return { maxTokens: reasoningOn ? 2200 : 1200, reasoningEffort, temperature, providerOnly, providerIgnore, maxSearches: MAX_SEARCHES_PER_ANSWER };
+}
+/** Request body for an assistant answer: the question is the only user message (no system prompt), like a real user. */
+export function buildAnswerBody(spec, messages, tuning, o) {
+    const body = {
+        model: spec.id,
+        messages,
+        max_tokens: o.maxTokens ?? tuning.maxTokens,
+        usage: { include: true }, // deprecated no-op (usage is always returned); kept for older gateways
+    };
+    if (tuning.temperature && typeof o.temperature === "number")
+        body.temperature = o.temperature;
+    if (tuning.reasoningEffort)
+        body.reasoning = { effort: tuning.reasoningEffort, exclude: true };
+    const provider = { data_collection: "deny" };
+    if (tuning.providerOnly?.length)
+        provider.only = tuning.providerOnly;
+    if (tuning.providerIgnore?.length)
+        provider.ignore = tuning.providerIgnore;
+    body.provider = provider;
+    const engine = engineOf(spec);
+    // Perplexity models search their own index on every call and take no tools.
+    if (engine === "none" || vendorOf(spec.id) === "perplexity")
+        return body;
+    if (o.surface === "tool") {
+        const parameters = { engine: engine === "native" ? "native" : "exa", max_uses: tuning.maxSearches };
+        if (engine === "exa")
+            parameters.max_results = 5;
+        const country = engine === "native" ? countryForLang(o.lang) : undefined;
+        if (country)
+            parameters.user_location = { type: "approximate", country };
+        body.tools = [{ type: "openrouter:web_search", parameters }];
+    }
+    else {
+        body.plugins = [engine === "native" ? { id: "web", engine: "native" } : { id: "web", engine: "exa", max_results: 5 }];
+    }
+    return body;
+}
+export function parseCompletion(json) {
+    const choice = json.choices?.[0] ?? {};
+    const msg = (choice.message ?? {});
+    let text = "";
+    if (typeof msg.content === "string")
+        text = msg.content;
+    else if (Array.isArray(msg.content)) {
+        text = msg.content.map((p) => (typeof p === "string" ? p : typeof p?.text === "string" ? p.text : "")).join("");
+    }
+    const sources = [];
+    const pushSource = (url, title) => {
+        if (typeof url === "string" && /^https?:\/\//i.test(url))
+            sources.push({ url, title: typeof title === "string" && title.trim() ? title.trim() : undefined });
+    };
+    for (const a of msg.annotations ?? []) {
+        if (a?.type !== "url_citation")
+            continue;
+        const u = (a.url_citation ?? a);
+        pushSource(u.url, u.title);
+    }
+    for (const c of (json.citations ?? msg.citations) ?? []) {
+        if (typeof c === "string")
+            pushSource(c);
+        else if (c && typeof c === "object")
+            pushSource(c.url, c.title);
+    }
+    for (const r of (json.search_results ?? msg.search_results) ?? []) {
+        pushSource(r?.url, r?.title);
+    }
+    const u = (json.usage ?? {});
+    const stu = (u.server_tool_use ?? u.server_tool_use_details ?? {});
+    const details = (u.completion_tokens_details ?? {});
+    const n = (v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+    return {
+        text,
+        finishReason: typeof choice.finish_reason === "string" ? choice.finish_reason : undefined,
+        model: typeof json.model === "string" ? json.model : undefined,
+        provider: typeof json.provider === "string" ? json.provider : undefined,
+        id: typeof json.id === "string" ? json.id : undefined,
+        sources,
+        webSearches: n(stu.web_search_requests) ?? n(stu.webSearchRequests) ?? 0,
+        usage: { promptTokens: n(u.prompt_tokens), completionTokens: n(u.completion_tokens), reasoningTokens: n(details.reasoning_tokens), cost: n(u.cost) },
+    };
+}
+/** Charged cost: `usage.cost` when OpenRouter reports it, else computed from tokens and searches. */
+export function costOf(c, price, searchUnit) {
+    if (typeof c.usage.cost === "number")
+        return c.usage.cost;
+    return (c.usage.promptTokens ?? 0) * price.prompt + (c.usage.completionTokens ?? 0) * price.completion + c.webSearches * searchUnit + price.request;
+}