castle-web-cli 0.4.83 → 0.4.85

package/dist/ide.js

@@ -72,12 +72,7 @@ export const PTY_WS_PATH = "/__castle/pty";
 export const FILES_API_PREFIX = "/__castle/files/";
 // Directories never surfaced in the file list / never read or written through
 // the builtin editor: VCS, deck-private state, and dependency trees.
-const FILES_IGNORE_DIRS = new Set([
-    ".git",
-    ".castle",
-    "node_modules",
-    "dist",
-]);
+const FILES_IGNORE_DIRS = new Set([".git", ".castle", "node_modules", "dist"]);
 // Fallback set of kit-owned rich-editor extensions: the known castle rich
 // content types across kit variants (.pxart in basic-2d, .drawing in older
 // kits). Only used when a kit is present but its getFileKind couldn't be parsed.
@@ -264,7 +259,9 @@ function handleFilesWrite(deckDir, req, res) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            sendJson(res, 500, { error: `Could not write ${resolved.rel}: ${message}` });
+            sendJson(res, 500, {
+                error: `Could not write ${resolved.rel}: ${message}`,
+            });
         }
     })();
 }
@@ -319,7 +316,9 @@ function handleFilesMkdir(deckDir, req, res) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            return sendJson(res, 500, { error: `Could not create folder ${resolved.rel}: ${message}` });
+            return sendJson(res, 500, {
+                error: `Could not create folder ${resolved.rel}: ${message}`,
+            });
         }
         const visiblePathAdded = ensureVisiblePath(deckDir, resolved.rel);
         sendJson(res, 200, { ok: true, path: resolved.rel, visiblePathAdded });
@@ -359,7 +358,9 @@ function handleFilesRename(deckDir, req, res) {
         // filesystem (default on macOS/Windows) `to` can "exist" only because it is
         // `from` under a different case -- a case-only rename like bounce.jsx ->
         // Bounce.jsx. Allow that by treating same-inode as not-a-collision.
-        if (from.abs !== to.abs && fs.existsSync(to.abs) && !isSameFile(from.abs, to.abs)) {
+        if (from.abs !== to.abs &&
+            fs.existsSync(to.abs) &&
+            !isSameFile(from.abs, to.abs)) {
             return sendJson(res, 409, { error: `Already exists: ${to.rel}` });
         }
         try {
@@ -394,7 +395,9 @@ function handleFilesDelete(deckDir, req, res) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            sendJson(res, 500, { error: `Could not delete ${resolved.rel}: ${message}` });
+            sendJson(res, 500, {
+                error: `Could not delete ${resolved.rel}: ${message}`,
+            });
         }
     })();
 }
@@ -431,7 +434,7 @@ function handleFilesApi(deckDir, req, res, reqPath) {
         const url = new URL(req.url ?? "/", "http://localhost");
         const resolved = resolveDeckPath(deckDir, url.searchParams.get("path"));
         if (!resolved.ok)
-            return sendJson(res, 400, { error: resolved.error }), true;
+            return (sendJson(res, 400, { error: resolved.error }), true);
         try {
             const contents = fs.readFileSync(resolved.abs, "utf8");
             sendJson(res, 200, { path: resolved.rel, contents });
@@ -457,13 +460,32 @@ function handleFilesApi(deckDir, req, res, reqPath) {
         handleFilesMkdir(deckDir, req, res);
         return true;
     }
-    return sendJson(res, 404, { error: `Unknown files action: ${action}` }), true;
+    return (sendJson(res, 404, { error: `Unknown files action: ${action}` }),
+        true);
 }
 function defaultShell() {
     if (process.platform === "win32") {
         return { command: process.env.COMSPEC ?? "cmd.exe", args: [] };
     }
-    return { command: process.env.SHELL ?? "/bin/zsh", args: ["-l"] };
+    // Pick the first shell that actually exists: $SHELL (dev), then zsh (macOS),
+    // then bash / sh. The cloud sandbox image is Debian-based (node:22) with no
+    // zsh and no $SHELL set, so a bare `/bin/zsh` fallback fails with execvp
+    // ENOENT and the terminal never gets a shell.
+    const candidates = [
+        process.env.SHELL,
+        "/bin/zsh",
+        "/bin/bash",
+        "/bin/sh",
+    ].filter((c) => Boolean(c));
+    const command = candidates.find((c) => {
+        try {
+            return fs.existsSync(c);
+        }
+        catch {
+            return false;
+        }
+    }) ?? "/bin/sh";
+    return { command, args: ["-l"] };
 }
 function ptyEnv() {
     const env = {

package/dist/native/loop.js

@@ -565,6 +565,10 @@ async function runLoop(opts, toolSchemas, log) {
     const imageLabels = new Map();
     let finalText = "";
     let totalUsage;
+    // Whether this run has called ANY tool, across every iteration -- not just
+    // the current one. Scoped to the run because the question is "did this task
+    // do anything at all", which one iteration can't answer.
+    let usedAnyTool = false;
     // Once our own timeout/external-abort fires, whatever streamChatCompletion
     // reports is moot -- the abort IS the reason for stopping, so we always
     // attribute the final error to it (rather than a network error that might
@@ -635,6 +639,9 @@ async function runLoop(opts, toolSchemas, log) {
                 return {
                     text: finalText,
                     error: streamResult.error ?? "openrouter stream ended without a final response",
+                    // Present only for an HTTP status streamChat could label; absent for
+                    // a dropped connection, which stays unclassified on purpose.
+                    failure: streamResult.failure,
                     usage: totalUsage,
                     playtestFrames: playtestFrameList(playtestFrames),
                     crashed: streamResult.crashed,
@@ -657,12 +664,40 @@ async function runLoop(opts, toolSchemas, log) {
                     : {}),
             });
             if (toolCalls.length === 0) {
+                // No tool calls is the normal way a run ends -- the model is done and
+                // signing off. But a TASK that reaches this on iteration 1, having
+                // never called a single tool, did no work: it chatted. That used to
+                // return a bare success, so the card finalized "done" at 100% with
+                // nothing changed -- the loudest silent failure this backend had.
+                //
+                // Only tasks: the router legitimately answers in plain text, and a
+                // task that used tools and THEN signs off with prose is fine.
+                //
+                // This narrows the failure class rather than closing it: a task whose
+                // only tool calls were reads still counts as "used a tool" here and
+                // can still finish having changed nothing. Detecting that needs a
+                // notion of which tools mutate, which is a bigger change than this.
+                if (opts.role === "task" && !usedAnyTool) {
+                    return {
+                        text: finalText,
+                        error: "the model replied without calling any tools, so nothing was done",
+                        failure: {
+                            kind: "no-work",
+                            detail: "model returned prose with no tool calls",
+                            model: opts.model,
+                            verbose: finalText,
+                        },
+                        usage: totalUsage,
+                        playtestFrames: playtestFrameList(playtestFrames),
+                    };
+                }
                 return {
                     text: finalText,
                     usage: totalUsage,
                     playtestFrames: playtestFrameList(playtestFrames),
                 };
             }
+            usedAnyTool = true;
             messages.push({
                 role: "assistant",
                 content: streamResult.message.content || null,

package/dist/native/openrouter.d.ts

@@ -1,3 +1,4 @@
+import { type AgentFailure } from "../agent-failures.js";
 import type { NativeUsage } from "./types.js";
 export interface ORToolCall {
     id: string;
@@ -55,5 +56,11 @@ export interface StreamChatResult {
     reasoningTokens?: number;
     crashed: boolean;
     error?: string;
+    failure?: AgentFailure;
+}
+export declare class OpenrouterHttpError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
 }
 export declare function streamChatCompletion(opts: StreamChatOpts): Promise<StreamChatResult>;

package/dist/native/openrouter.js

@@ -13,6 +13,7 @@
 // the model already said, which the caller (native/loop.ts) is better placed
 // to decide (or simply not do, matching today's crash-then-relaunch policy at
 // the task-attempt level).
+import { failureForStatus } from "../agent-failures.js";
 // Overridable via CASTLE_OPENROUTER_URL so the QA harness (see
 // scripts/tests/agent-qa/native/fake-openrouter.mjs) can point this client at
 // a local fake server instead of the real API -- read per-call (not hoisted
@@ -48,6 +49,22 @@ function backoffMs(attempt) {
 function isRetryableStatus(status) {
     return status === 429 || status >= 500;
 }
+// A non-retryable HTTP error from OpenRouter, carrying the status as a NUMBER
+// rather than only baked into a message. This path knows the status
+// first-hand, so classification upstream is a lookup instead of a regex over
+// our own error prose (the claude-CLI path has no such luxury -- see
+// classifyProviderError). `message` keeps the old "HTTP <status>: <body>"
+// wording so logs and any string-matching callers read the same as before.
+export class OpenrouterHttpError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`HTTP ${status}${body ? `: ${body.slice(0, 300)}` : ""}`);
+        this.status = status;
+        this.body = body;
+        this.name = "OpenrouterHttpError";
+    }
+}
 async function safeReadText(res) {
     try {
         return (await res.text()).trim();
@@ -93,7 +110,7 @@ async function connectWithRetry(init, opts) {
             continue;
         }
         const bodyText = await safeReadText(res);
-        throw new Error(`HTTP ${res.status}${bodyText ? `: ${bodyText.slice(0, 300)}` : ""}`);
+        throw new OpenrouterHttpError(res.status, bodyText);
     }
     // Unreachable (the loop above always returns or throws), but keeps the
     // return type honest for TS.
@@ -242,6 +259,13 @@ export async function streamChatCompletion(opts) {
             message: null,
             crashed: false,
             error: `could not run openrouter: ${err instanceof Error ? err.message : String(err)}`,
+            // Only an HTTP error carries a status worth classifying. A network-level
+            // failure (DNS, refused, reset) stays unlabelled so it keeps landing in
+            // the pre-existing "spawn" bucket via the "could not run" prefix --
+            // that's already the right read: the request never got going.
+            failure: err instanceof OpenrouterHttpError
+                ? failureForStatus(err.status, err.body)
+                : undefined,
         };
     }
     if (!res.body) {

package/dist/native/types.d.ts

@@ -1,3 +1,4 @@
+import type { AgentFailure } from "../agent-failures.js";
 import type { PlaytestExecutor } from "./playtest.js";
 import type { ORReasoningEffort, ORRoutingMode } from "./openrouter.js";
 export type NativeRole = "router" | "task";
@@ -37,6 +38,7 @@ export interface NativeRunOpts {
 export interface NativeRunResult {
     text: string;
     error?: string;
+    failure?: AgentFailure;
     usage?: NativeUsage;
     playtestFrames?: string[];
     crashed?: boolean;

package/dist/native/types.js

@@ -1,41 +1,3 @@
 // Shapes for the native (in-process, OpenRouter-backed) agent backend --
 // see the plan at native_openrouter_agent_loop_fd7d9b3e.plan.md, "Path B".
-//
-// These MIRROR the non-exported CliRunOpts / CliRunResult / CliUsage
-// interfaces in cli/src/agent.ts (see runAgentCli there), which normalize
-// the headless `claude` / `cursor-agent` CLI backends into onDelta/onActivity/
-// onThinking hooks plus a { finalText, error, usage, crashed } result. This
-// file is a SEPARATE set of types for now (new-files-only
-// constraint -- agent.ts is being edited concurrently by a sibling change),
-// not a re-export, so field names differ in a few places. When the native
-// backend is wired into agent.ts, expect one of these two outcomes:
-//
-//   1. CliRunOpts/CliRunResult are widened to a shape both backends share
-//      (command/args/parser and children become backend-specific extras), or
-//   2. the call site maps between the two shapes directly:
-//        - NativeRunResult.text            -> CliRunResult.finalText
-//        - NativeRunResult.error/usage/crashed -> same names
-//        - CliRunResult.ok                 <- derived as
-//              `!result.error && !result.crashed` (no native equivalent of
-//              a process exit code -- "ok" always follows from the other
-//              two fields)
-//        - CliRunOpts.children (Set<ChildProcess>) has no native
-//          equivalent -- runAgentNative takes `signal` (AbortSignal)
-//          instead, so a caller cancels a run the same way it would abort
-//          any other fetch-based operation. The wiring step would create one
-//          AbortController per run and adapt it to whatever cancellation
-//          registry agent.ts uses for CLI children.
-//        - CliRunOpts.command/args/parser have no native equivalent --
-//          replaced by `model` (the free-form OpenRouter model id) and
-//          `apiKey`.
-//        - CliRunOpts.logPath maps to NativeRunOpts.logPath: same file
-//          locations (tasks/<id>/log.jsonl, .castle/agent/router-log.jsonl),
-//          same append-JSONL discipline, but the native lines are STRUCTURED
-//          run events (init/assistant/tool_result/eviction/retry/result --
-//          see createRunLogger in loop.ts) rather than raw CLI stream-json.
-//
-// Turns stay stateless exactly as they are today: the caller rebuilds one big
-// prompt string per turn (buildRouterPrompt/buildTaskPrompt) and passes it as
-// `prompt`; runAgentNative holds the resulting message array only for the
-// lifetime of that one call.
 export {};

package/dist/openrouter-catalog.d.ts

@@ -0,0 +1,28 @@
+export interface CatalogEntry {
+    id: string;
+    supportedParameters: string[];
+    reasoning: unknown;
+}
+export type ModelCheck = {
+    status: "ok";
+} | {
+    status: "unknown-model";
+    suggestions: string[];
+} | {
+    status: "no-tools";
+} | {
+    status: "unavailable";
+};
+export declare function primeOpenrouterCatalog(): void;
+export type KeyCheck = {
+    status: "ok";
+} | {
+    status: "bad-key";
+} | {
+    status: "no-credits";
+} | {
+    status: "unavailable";
+};
+export declare function checkOpenrouterKey(apiKey: string): Promise<KeyCheck>;
+export declare function checkOpenrouterModel(slug: string): Promise<ModelCheck>;
+export declare function openrouterCatalogEntry(slug: string): Promise<CatalogEntry | null>;

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;
+}