castle-web-cli 0.4.82 → 0.4.84

package/dist/openrouter-catalog.js

@@ -0,0 +1,299 @@
+// Asks OpenRouter about our own configuration BEFORE a run starts: is this
+// model slug real, can it tool-call, and is this API key usable. Both answers
+// come from cheap metadata endpoints, and both turn an expensive runtime
+// failure into an instant one.
+//
+// - https://openrouter.ai/api/v1/models is public (no auth) and every entry
+//   carries `supported_parameters`, which contains "tools" exactly when the
+//   model can tool-call. That decides two failures a run would otherwise
+//   discover the hard way: a slug that doesn't exist, and a slug that exists
+//   but can never do agent work (image/audio/embedding models share the
+//   catalog).
+// - https://openrouter.ai/api/v1/key validates the key in ~0.2s. Worth the
+//   call: measured against the real binary, a bad key makes the claude CLI
+//   retry internally for OVER TWO MINUTES before it surfaces anything.
+//
+// This module NEVER blocks a run on the network, and never turns "we don't
+// know" into "it's bad". Every failure path resolves to "unavailable", which
+// callers treat as "allow" -- OpenRouter ships models faster than any cache
+// refreshes, and a free-form field that rejects a brand-new model would be
+// worse than one that validates nothing.
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+// Overridable for the QA battery, which runs fake endpoints. Without the cache
+// override the battery would read/write the developer's real ~/.castle and its
+// fall-open assertions would pass spuriously off a warm real catalog.
+function modelsUrl() {
+    return (process.env.CASTLE_OPENROUTER_MODELS_URL ??
+        "https://openrouter.ai/api/v1/models");
+}
+function keyUrl() {
+    return process.env.CASTLE_OPENROUTER_KEY_URL ?? "https://openrouter.ai/api/v1/key";
+}
+function cachePath() {
+    return (process.env.CASTLE_OPENROUTER_CATALOG_CACHE ??
+        path.join(os.homedir(), ".castle", "openrouter-models.json"));
+}
+const FETCH_TIMEOUT_MS = 3_000;
+// Past this the cache is refreshed, but the STALE copy is still served while
+// that happens (see loadCatalog) -- staleness costs a wrong verdict on a model
+// that changed in the last day, which is cheap; a blocking fetch is not.
+const FRESH_MS = 24 * 60 * 60 * 1000;
+const MAX_SUGGESTIONS = 3;
+// Levenshtein ceiling for a "did you mean". Past ~4 edits the suggestion stops
+// being a plausible typo and starts being noise.
+const MAX_SUGGESTION_DISTANCE = 4;
+function hasTools(entry) {
+    return entry.supportedParameters.includes("tools");
+}
+let memo = null;
+// Single-flight: tasks spawn at max concurrency, and N cold pre-flights must
+// not become N fetches of a ~500KB payload.
+let inflight = null;
+function isFresh(file) {
+    const age = Date.now() - file.fetchedAt;
+    // A negative age means the clock moved backwards (or the file was hand-
+    // edited); treat it as stale rather than trusting it forever.
+    return age >= 0 && age < FRESH_MS;
+}
+function parseCatalog(body) {
+    const data = body?.data;
+    if (!Array.isArray(data))
+        return null;
+    const models = [];
+    for (const raw of data) {
+        if (typeof raw?.id !== "string")
+            continue;
+        const params = Array.isArray(raw.supported_parameters)
+            ? raw.supported_parameters.filter((p) => typeof p === "string")
+            : [];
+        models.push({
+            id: raw.id,
+            supportedParameters: params,
+            reasoning: raw.reasoning ?? null,
+        });
+    }
+    // An empty list means the endpoint answered with something we don't
+    // understand -- treat it as a failure rather than caching "no models exist",
+    // which would reject every slug.
+    return models.length > 0 ? models : null;
+}
+async function fetchCatalog() {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const res = await fetch(modelsUrl(), { signal: controller.signal });
+        if (!res.ok)
+            return null;
+        const models = parseCatalog(await res.json());
+        if (!models)
+            return null;
+        return { fetchedAt: Date.now(), models };
+    }
+    catch {
+        // Offline, DNS failure, timeout, malformed JSON -- all the same to us.
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function readCache() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cachePath(), "utf8"));
+        if (!Array.isArray(parsed?.models) || typeof parsed?.fetchedAt !== "number") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(file) {
+    try {
+        fs.mkdirSync(path.dirname(cachePath()), { recursive: true });
+        fs.writeFileSync(cachePath(), JSON.stringify(file));
+    }
+    catch {
+        // A cache we can't persist just means we refetch next boot. Not fatal.
+    }
+}
+async function refresh() {
+    inflight ??= fetchCatalog().finally(() => {
+        inflight = null;
+    });
+    const fetched = await inflight;
+    if (fetched) {
+        memo = fetched;
+        writeCache(fetched);
+    }
+    return fetched;
+}
+// Stale-while-revalidate: a usable copy (however old) is returned immediately
+// and a refresh runs in the background. Only a cold start with no cache at all
+// awaits the network, and priming at serve boot (primeOpenrouterCatalog) means
+// even that lands off the critical path in practice.
+async function loadCatalog() {
+    memo ??= readCache();
+    if (memo) {
+        if (!isFresh(memo))
+            void refresh();
+        return memo;
+    }
+    return refresh();
+}
+// Called at serve boot so the first pre-flight never pays for the fetch. Safe
+// to ignore the result -- it only warms memo/disk.
+export function primeOpenrouterCatalog() {
+    void loadCatalog();
+}
+function levenshtein(a, b) {
+    // Single-row DP -- the id list is ~350 entries and this runs only on a miss.
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const curr = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+        }
+        prev = curr;
+    }
+    return prev[b.length];
+}
+function suggestionsFor(slug, models) {
+    const scored = [];
+    for (const m of models) {
+        // A substring match ranks above any edit distance: someone who typed
+        // "gpt-5.6-terra" without the vendor prefix wants openai/gpt-5.6-terra,
+        // which is 7 edits away and would otherwise never surface.
+        const score = m.id.includes(slug) ? 0 : levenshtein(slug, m.id);
+        if (score <= MAX_SUGGESTION_DISTANCE)
+            scored.push({ id: m.id, score });
+    }
+    scored.sort((x, y) => x.score - y.score || x.id.localeCompare(y.id));
+    if (scored.length === 0)
+        return [];
+    // Keep only what's close to the BEST match, not everything under the ceiling.
+    // Model names in one family sit within a few edits of each other, so a
+    // 1-edit typo on gpt-5.6-terra also "matches" gpt-5.6-luna at 4 -- padding a
+    // confident answer with two wrong ones reads as a guess.
+    const cutoff = scored[0].score + 1;
+    return scored
+        .filter((s) => s.score <= cutoff)
+        .slice(0, MAX_SUGGESTIONS)
+        .map((s) => s.id);
+}
+// OpenRouter accepts routing suffixes that are NOT catalog ids of their own --
+// ":nitro" (throughput) and ":floor" (price) route to a base model. Confirmed
+// against the live catalog: ":free" and ":thinking" ARE listed as distinct ids,
+// ":nitro"/":floor" are not. So an exact miss retries the base slug, or we'd
+// reject "anthropic/claude-opus-4.8:nitro" as unknown when it's perfectly valid.
+function findEntry(slug, models) {
+    const exact = models.find((m) => m.id === slug);
+    if (exact)
+        return exact;
+    const colon = slug.lastIndexOf(":");
+    if (colon <= 0)
+        return undefined;
+    const base = slug.slice(0, colon);
+    return models.find((m) => m.id === base);
+}
+// Verdicts are cached in memory only, never on disk: the cache key is derived
+// from a live credential, and a process-lifetime cache is enough to keep this
+// off the hot path (one check per serve boot per key). Short TTL so revoking a
+// key or topping up credits takes effect without a restart.
+const KEY_CHECK_TTL_MS = 5 * 60 * 1000;
+const keyChecks = new Map();
+const keyInflight = new Map();
+// Cache/log handle for a key that is never itself stored or printed. Not a
+// security boundary (an in-process Map already holds the real key upstream) --
+// it just keeps credentials out of anything that might get dumped.
+function keyHandle(apiKey) {
+    let h = 0;
+    for (let i = 0; i < apiKey.length; i++)
+        h = (Math.imul(h, 31) + apiKey.charCodeAt(i)) | 0;
+    return `k${(h >>> 0).toString(36)}`;
+}
+async function fetchKeyCheck(apiKey) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const res = await fetch(keyUrl(), {
+            headers: { authorization: `Bearer ${apiKey}` },
+            signal: controller.signal,
+        });
+        // Only explicit status codes are trusted. The endpoint also reports
+        // `limit`/`usage`, and inferring exhaustion from that arithmetic is
+        // tempting -- but a wrong inference BLOCKS a working setup, which is the
+        // one outcome this whole module is built to avoid. An out-of-credit key is
+        // still caught at run time by the classifier; a false "no credits" here
+        // would be unrecoverable from the UI.
+        if (res.status === 401 || res.status === 403)
+            return { status: "bad-key" };
+        if (res.status === 402)
+            return { status: "no-credits" };
+        if (!res.ok)
+            return { status: "unavailable" };
+        return { status: "ok" };
+    }
+    catch {
+        return { status: "unavailable" };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function checkOpenrouterKey(apiKey) {
+    if (!apiKey)
+        return { status: "bad-key" };
+    const handle = keyHandle(apiKey);
+    const cached = keyChecks.get(handle);
+    if (cached && Date.now() - cached.at < KEY_CHECK_TTL_MS)
+        return cached.result;
+    // Single-flight per key: tasks spawn concurrently and must not each probe.
+    const existing = keyInflight.get(handle);
+    if (existing)
+        return existing;
+    const p = fetchKeyCheck(apiKey)
+        .then((result) => {
+        // An "unavailable" verdict is deliberately NOT cached -- it means the
+        // network hiccuped, and caching it would suppress validation for the
+        // next 5 minutes over one dropped request.
+        if (result.status !== "unavailable") {
+            keyChecks.set(handle, { at: Date.now(), result });
+        }
+        return result;
+    })
+        .finally(() => keyInflight.delete(handle));
+    keyInflight.set(handle, p);
+    return p;
+}
+export async function checkOpenrouterModel(slug) {
+    const catalog = await loadCatalog();
+    if (!catalog)
+        return { status: "unavailable" };
+    // Catalog ids are all lowercase (verified against the live endpoint), so a
+    // case-only difference is a typo we can match through rather than reject.
+    const normalized = slug.trim().toLowerCase();
+    const entry = findEntry(normalized, catalog.models);
+    if (!entry) {
+        return {
+            status: "unknown-model",
+            suggestions: suggestionsFor(normalized, catalog.models),
+        };
+    }
+    return hasTools(entry) ? { status: "ok" } : { status: "no-tools" };
+}
+// The single catalog lookup for the rest of the CLI -- the settings popover's
+// capabilities endpoint (fetchModelCaps in agent.ts) reads reasoning support
+// from here rather than fetching /models a second time. Resolves null when the
+// slug is unknown OR the catalog is unreachable; callers that need to tell
+// those apart use checkOpenrouterModel.
+export async function openrouterCatalogEntry(slug) {
+    const catalog = await loadCatalog();
+    if (!catalog)
+        return null;
+    return findEntry(slug.trim().toLowerCase(), catalog.models) ?? null;
+}