clauderipple 0.2.0 → 0.3.1

package/dist/router/src/agents.js

@@ -0,0 +1,250 @@
+// Agent definitions, derived from one place: config.json.
+//
+// Claude Code's Agent tool reads `~/.claude/agents/*.md` and takes the worker's model from the
+// frontmatter `model:`. Until now that was a third copy of the truth, beside `providers.*.models`
+// (what the router knows) and `aliases` (what a `[[ripple: xxx@effort]]` marker resolves to), and
+// the copies drifted: an agent file named `deepseek` had no matching alias, so the marker resolved
+// to a model id no provider declared and `PASS` sent thirty 404s to Anthropic (2026-09-20).
+//
+// This module derives both from config: the aliases a marker can name, and the agent files
+// themselves. Files it writes are recorded in a manifest and are the only ones it may touch — a
+// hand-written `muse.md` or `gpt.md` is never overwritten or removed.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { homeDir } from "./config.js";
+import { declaredBy } from "./routing.js";
+/** Where Claude Code's Agent tool reads its worker definitions. */
+export function defaultAgentDir() {
+    return path.join(os.homedir(), ".claude", "agents");
+}
+/**
+ * `cfg` with the agent files' derived aliases merged in. An explicit `cfg.aliases` entry wins, so a
+ * hand-written alias is never overridden by a generated one.
+ */
+export function withAgentAliases(cfg, dir, log) {
+    const derived = agentAliases(dir, log);
+    return { ...cfg, aliases: { ...derived, ...cfg.aliases } };
+}
+/** The body every generated worker carries, verbatim. */
+const BODY = [
+    "너는 이 세션의 실행자다. 위임받은 작업을 직접 끝내고 직접 검증해서 결론만 간결히 보고한다.",
+    "파일 전문·코드 덤프는 보고에 넣지 않는다. 추측은 추측이라 명시하고 근거는 파일:줄번호로 댄다.",
+    "다른 에이전트에게 넘기지 않는다. 프롬프트 첫 줄의 `[[ripple: …]]` 표식은 라우팅용이니 무시한다.",
+    "**작업 디렉터리(cwd)에 어떤 파일도 만들지 않는다.** 조사·감사처럼 \"읽기만\" 하는 일이어도 마찬가지다.",
+    "임시 파일이 필요하면 `/tmp` 아래에만 만들고, 끝나면 지운다. 사본을 작업 폴더에 떨구지 마라.",
+].join("\n");
+/**
+ * Parsed `*.md` frontmatter per directory, keyed by file mtime so a request never re-reads the whole
+ * directory. Only the `---` block's own `key: value` lines are read: no YAML library, because the
+ * two keys we need are two lines.
+ */
+const cache = new Map();
+function parseFrontmatter(text) {
+    const lines = text.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---")
+        return null;
+    const out = {};
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === "---")
+            return out;
+        const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+        if (m)
+            out[m[1].toLowerCase()] = m[2].trim().replace(/^['"]|['"]$/g, "");
+    }
+    return null; // no closing fence: not frontmatter we understand
+}
+/** The `*.md` files of `dir`, parsed and cached on their mtimes. Parse failures are skipped. */
+function scanDir(dir, log) {
+    let files;
+    try {
+        files = fs.readdirSync(dir).filter((f) => f.endsWith(".md"));
+    }
+    catch {
+        cache.delete(dir);
+        return new Map();
+    }
+    const prev = cache.get(dir) ?? new Map();
+    const next = new Map();
+    let changed = false;
+    for (const file of files) {
+        let st;
+        try {
+            st = fs.statSync(path.join(dir, file));
+        }
+        catch {
+            continue;
+        }
+        const hit = prev.get(file);
+        if (hit && hit.mtimeMs === st.mtimeMs) {
+            next.set(file, hit);
+            continue;
+        }
+        changed = true;
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, file), "utf8");
+        }
+        catch (e) {
+            log?.warn(`agent ${file}: unreadable (${e.message}); skipped`);
+            continue;
+        }
+        const fm = parseFrontmatter(text);
+        if (!fm)
+            continue; // no frontmatter: not an agent definition, nothing to warn about
+        const name = fm.name;
+        if (!name) {
+            log?.warn(`agent ${file}: frontmatter has no name; skipped`);
+            continue;
+        }
+        next.set(file, { name, model: fm.model ?? null, mtimeMs: st.mtimeMs });
+    }
+    if (changed || prev.size !== next.size)
+        cache.set(dir, next);
+    return next;
+}
+/**
+ * `{ [name]: model id without its "@effort" }` for every agent file in `dir`. This is the derived
+ * half of the marker aliases; an explicit `cfg.aliases` entry wins over it at the call site.
+ */
+export function agentAliases(dir, log) {
+    const out = {};
+    for (const entry of scanDir(dir, log).values()) {
+        if (!entry.model)
+            continue;
+        out[entry.name] = entry.model.replace(/@[a-z]+$/i, "");
+    }
+    return out;
+}
+/** The agent name (and file basename) a model id maps to: everything outside `[a-z0-9-]` becomes `-`. */
+export function agentNameFor(modelId) {
+    return modelId.replace(/[^a-z0-9-]/g, "-");
+}
+function capsEffortLevels(provider) {
+    return provider.caps?.effortLevels;
+}
+/**
+ * The `@effort` suffix a generated file's `model:` carries: `@medium` when the provider or the model
+ * offers medium reasoning, otherwise none. An empty `model.effortLevels` disables the provider
+ * fallback (config.ts), so it is honoured rather than ignored.
+ */
+function effortSuffix(provider, modelId) {
+    const modelLevels = provider.models?.find((m) => m.id === modelId)?.effortLevels;
+    const levels = modelLevels !== undefined ? modelLevels : capsEffortLevels(provider);
+    return levels?.includes("medium") ? "@medium" : "";
+}
+function fileContent(name, modelId, provider, suffix) {
+    const description = `${modelId} via ${provider}. Generated by ClaudeRipple from config.json — edits are overwritten; ` +
+        `to customise, copy to another name. Set effort with [[ripple: ${name}@<level>]] on the first line.`;
+    return `---\nname: ${name}\ndescription: ${description}\nmodel: ${modelId}${suffix}\n---\n${BODY}\n`;
+}
+function readManifest(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (Array.isArray(parsed.agents))
+            return { agents: parsed.agents.filter((a) => typeof a === "string") };
+    }
+    catch {
+        /* missing or broken: treat as empty, and it is rewritten below */
+    }
+    return { agents: [] };
+}
+function writeManifest(file, manifest, log) {
+    try {
+        fs.writeFileSync(file, JSON.stringify(manifest, null, 2) + "\n");
+    }
+    catch (e) {
+        log?.warn(`generated-agents manifest: cannot write ${file}: ${e.message}`);
+    }
+}
+/**
+ * Bring `dir`'s generated agent files in step with `cfg`: one file per model exactly one non-anthropic
+ * provider declares, and remove the ones this router wrote whose model is no longer ticked. Only
+ * files named in the manifest are ever written or removed — a hand-written agent is left alone, and
+ * a name it already uses is skipped rather than overwritten.
+ *
+ * Never throws: a write failure is a warning, not a dead router.
+ */
+export function syncAgentFiles(cfg, dir, log, opts = {}) {
+    if (cfg.cli.agentFiles === false)
+        return;
+    const manifestFile = opts.manifestPath ?? path.join(homeDir(), "generated-agents.json");
+    const manifest = readManifest(manifestFile);
+    const owned = new Set(manifest.agents);
+    const scanned = scanDir(dir, log);
+    // Names already taken by files this router did not write: hand files win, always.
+    const handNames = new Set();
+    for (const entry of scanned.values())
+        if (!owned.has(entry.name))
+            handNames.add(entry.name);
+    // Targets: each model declared by exactly one provider, that provider not ingress-only.
+    const targets = new Map();
+    for (const [providerName, provider] of Object.entries(cfg.providers)) {
+        if (provider.type === "anthropic" && !provider.accountPool)
+            continue;
+        for (const model of provider.models ?? []) {
+            const owners = declaredBy(model.id, cfg);
+            if (owners.length !== 1) {
+                if (owners.length > 1)
+                    log?.warn(`agent files: "${model.id}" is declared by ${owners.join(", ")}; not generating an agent for it`);
+                continue;
+            }
+            const name = agentNameFor(model.id);
+            const clash = targets.get(name);
+            if (clash) {
+                log?.warn(`agent files: "${model.id}" and "${clash.modelId}" both map to "${name}"; skipping "${model.id}"`);
+                continue;
+            }
+            targets.set(name, { modelId: model.id, provider: providerName, suffix: effortSuffix(provider, model.id) });
+        }
+    }
+    const nextOwned = [];
+    for (const [name, t] of targets) {
+        if (handNames.has(name)) {
+            log?.info?.(`agent files: "${name}" exists and is not ours; leaving it alone`);
+            continue;
+        }
+        const file = path.join(dir, `${name}.md`);
+        const content = fileContent(name, t.modelId, t.provider, t.suffix);
+        const existing = scanned.get(`${name}.md`);
+        if (existing) {
+            let current = null;
+            try {
+                current = fs.readFileSync(file, "utf8");
+            }
+            catch {
+                current = null;
+            }
+            if (current === content) {
+                nextOwned.push(name); // already correct: do not rewrite
+                continue;
+            }
+        }
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(file, content);
+            nextOwned.push(name);
+            log?.info?.(`agent files: wrote ${name}.md (${t.modelId} via ${t.provider})`);
+        }
+        catch (e) {
+            log?.warn(`agent files: cannot write ${file}: ${e.message}`);
+        }
+    }
+    // A model that is no longer ticked: remove the file this router wrote for it, and only that.
+    for (const name of owned) {
+        if (nextOwned.includes(name))
+            continue;
+        try {
+            fs.rmSync(path.join(dir, `${name}.md`), { force: true });
+            log?.info?.(`agent files: removed ${name}.md (model no longer configured)`);
+        }
+        catch (e) {
+            log?.warn(`agent files: cannot remove ${name}.md: ${e.message}`);
+        }
+    }
+    const sorted = [...nextOwned].sort();
+    if (JSON.stringify(sorted) !== JSON.stringify([...manifest.agents].sort())) {
+        writeManifest(manifestFile, { agents: sorted }, log);
+    }
+}

package/dist/router/src/bootstrap.js

@@ -5,6 +5,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { agentAliases } from "./agents.js";
 export const BOOTSTRAP_PATH = "/api/claude_cli/bootstrap";
 /**
  * Model ids named in the user's agent definitions (~/.claude/agents/*.md frontmatter `model:`),
@@ -46,16 +47,25 @@ function routable(id, cfg) {
 }
 export function injectBootstrap(body, cfg, agentDirs) {
     const known = new Set(cfg.cli.extraModels.map((m) => m.model));
+    // The agent files' derived aliases are the same set a marker resolves against, so an id an agent
+    // file names (and its base) is routable here too — otherwise the CLI never lists it and the
+    // subagent silently falls back to the parent session's Claude model.
+    const aliasDir = agentDirs?.[0] ?? path.join(os.homedir(), ".claude", "agents");
+    const aliases = { ...agentAliases(aliasDir), ...cfg.aliases };
     const fromAgents = agentModelIds(agentDirs)
-        .filter((id) => !known.has(id) && routable(id, cfg))
+        .filter((id) => !known.has(id) && routable(id, { ...cfg, aliases }))
         .map((id) => {
         const [base, effort] = id.split("@");
         const named = cfg.cli.extraModels.find((m) => m.model === base);
-        return { model: id, name: `${named?.name ?? base}${effort ? ` · ${effort}` : ""}` };
+        // An "<model>@<effort>" entry is the same model with a different effort, so it has the same window.
+        return { model: id, name: `${named?.name ?? base}${effort ? ` · ${effort}` : ""}`, ...(named?.contextWindow ? { contextWindow: named.contextWindow } : {}) };
     });
     const extra = [...cfg.cli.extraModels, ...fromAgents];
     const win = cfg.cli.autoCompactWindow;
-    if (extra.length === 0 && !win)
+    // Routed models do not share a context window; the global value is only the fallback for entries
+    // that do not name their own, so a per-entry window alone is reason enough to write the map.
+    const anyWindow = win !== undefined || extra.some((m) => m.contextWindow) || Object.values(cfg.routes).some((r) => r.contextWindow);
+    if (extra.length === 0 && !anyWindow)
         return body;
     let j;
     try {
@@ -68,12 +78,18 @@ export function injectBootstrap(body, cfg, agentDirs) {
         const existing = Array.isArray(j.additional_model_options) ? j.additional_model_options : [];
         j.additional_model_options = [...existing, ...extra];
     }
-    if (win) {
+    if (anyWindow) {
         const acw = { ...(j.auto_compact_windows ?? {}) };
-        for (const m of extra)
-            acw[m.model] = win;
-        for (const alias of Object.keys(cfg.routes))
-            acw[alias] = win;
+        for (const m of extra) {
+            const w = m.contextWindow ?? win;
+            if (w)
+                acw[m.model] = w;
+        }
+        for (const [alias, route] of Object.entries(cfg.routes)) {
+            const w = route.contextWindow ?? win;
+            if (w)
+                acw[alias] = w;
+        }
         j.auto_compact_windows = acw;
     }
     return Buffer.from(JSON.stringify(j));

package/dist/router/src/capabilities.js

@@ -0,0 +1,214 @@
+// Measure what a model's capability actually is, by making it answer.
+//
+// A vendor's `/models` tells you ids, not capabilities. OpenCode Go reports only `id`, `object`,
+// `created` and `owned_by` (measured 2026-09-22), yet one subscription serves several wires on one
+// key: `/responses` for Muse Spark, `/chat/completions` for MiMo, `/messages` for MiniMax. The
+// route a model is on is only knowable by asking it — `mimo-v2.6-pro` answered 503 on `/responses`
+// and 200 on `/chat/completions`, while `muse-spark-1.3-contributor` answered the other way round
+// (measured 2026-09-22). A model sent down the wrong wire reads to the user as an unexplained 529.
+//
+// The same is true of reasoning effort: `mimo-v2.6-pro` accepted `none`/`low`/`medium`/`high` and
+// refused `minimal`/`xhigh` with 400 "Invalid request parameters" (measured 2026-09-22). The
+// provider's whole ladder handed to every model therefore offers the GUI steps that fail.
+//
+// This module is pure: every network call goes through `deps.fetch`, so a test can drive it with a
+// stub and nothing here reaches the network on its own.
+import crypto from "node:crypto";
+/** The endpoint a wire appends to a base. Matches what the router itself sends: `endpoint()` in
+ * providers/openai/index.ts, and `messagesUrl()` in admin.ts for the Anthropic wire. */
+function endpointFor(wire, base) {
+    const trimmed = base.replace(/\/+$/, "");
+    if (wire === "chat")
+        return `${trimmed}/chat/completions`;
+    if (wire === "responses")
+        return `${trimmed}/responses`;
+    return `${trimmed}/v1/messages`;
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function snippet(text) {
+    return text.replace(/\s+/g, " ").trim().slice(0, 200);
+}
+/**
+ * The provider's own key, re-sent under the header this wire expects.
+ *
+ * Same rule as `reauthorized` in config.ts: only the auth header is replaced and every other header
+ * is kept, because sending both conventions at once would hand the endpoint a credential it did not
+ * ask for. Nothing recognisable to move means the headers are left exactly as they were rather than
+ * inventing an empty credential, which would read as a missing key instead of a config error.
+ */
+function authHeaders(candidate, headers) {
+    const out = { ...(headers ?? {}) };
+    if (!candidate.authHeader)
+        return out;
+    let key;
+    for (const [name, value] of Object.entries(out)) {
+        const lower = name.toLowerCase();
+        if (lower === "x-api-key") {
+            key ??= value;
+            delete out[name];
+        }
+        else if (lower === "authorization") {
+            key ??= value.replace(/^Bearer\s+/i, "");
+            delete out[name];
+        }
+    }
+    if (key === undefined)
+        return { ...(headers ?? {}) };
+    if (candidate.authHeader === "x-api-key")
+        out["x-api-key"] = key;
+    else
+        out.authorization = `Bearer ${key}`;
+    return out;
+}
+function requestHeaders(candidate, deps) {
+    const headers = { "content-type": "application/json", ...authHeaders(candidate, deps.headers) };
+    // Some vendors gate on the session header: OpenCode Go answers 400 `MissingSessionID` without
+    // `x-opencode-session` (measured 2026-09-18), so a measurement that omitted it would report a
+    // working provider as broken. A fresh value per request, the same random-per-request shape
+    // admin.ts's probeProvider uses.
+    if (deps.sessionHeader)
+        headers[deps.sessionHeader] = `measure-${crypto.randomBytes(8).toString("hex")}`;
+    return headers;
+}
+/**
+ * The smallest request each wire accepts, shaped exactly as the router sends it.
+ *
+ * Effort travels the way that wire carries it: `reasoning_effort` for Chat Completions and
+ * `reasoning: { effort }` for Responses (providers/openai/translate.ts), and Anthropic Messages
+ * carries it as `output_config.effort`, which the anthropic-compatible adapter sanitises
+ * (compat.ts, `sanitizeForCompatible`).
+ */
+function requestBody(wire, id, effort) {
+    if (wire === "chat") {
+        return JSON.stringify({ model: id, max_tokens: 1, stream: false, messages: [{ role: "user", content: "hi" }], ...(effort ? { reasoning_effort: effort } : {}) });
+    }
+    if (wire === "responses") {
+        // Sixteen, not one: Responses refuses anything smaller with a 400 naming `max_output_tokens`
+        // (measured 2026-09-22 against OpenCode Go). Asking for one token there made every model on
+        // this wire look like it did not serve the wire at all, and every effort level look refused.
+        return JSON.stringify({ model: id, max_output_tokens: 16, input: "hi", ...(effort ? { reasoning: { effort } } : {}) });
+    }
+    return JSON.stringify({ model: id, max_tokens: 1, messages: [{ role: "user", content: "hi" }], ...(effort ? { output_config: { effort } } : {}) });
+}
+/**
+ * Every effort level seen named by any endpoint here, weakest first.
+ *
+ * A model can take a level its provider's configured ladder never lists: measured 2026-09-22,
+ * `deepseek-v4.1-flash` answers 200 to `max`, which is absent from the OpenCode Go ladder, so
+ * measuring only what the provider declared could narrow a ladder but never widen one and the level
+ * stayed invisible. The candidate set has to be wider than the configuration it is correcting.
+ */
+const KNOWN_EFFORTS = ["none", "minimal", "low", "medium", "high", "xhigh", "ultra", "max"];
+/** A value no vendor defines, sent to make the endpoint name the ones it does. */
+const NOT_A_LEVEL = "clauderipple-probe";
+/** A refusal of the level itself, as opposed to anything that merely went wrong. OpenCode Go answers
+ * 400 for one model and 422 for another (measured 2026-09-22), so both count. */
+function refusedLevel(status) {
+    return status === 400 || status === 422;
+}
+/**
+ * A refusal aimed at the plan rather than the credential.
+ *
+ * Measured 2026-09-22: OpenCode answers 403 FreeTierError, "OpenCode's free tier can only be used
+ * from within OpenCode", for every model whose id ends in `-free`. The key is accepted and the
+ * model exists; it simply cannot be reached from here, ever. Reading that as an auth failure sends
+ * the operator to re-check a key that is fine and leaves the model looking merely unmeasured.
+ */
+export function refusedByPlan(detail) {
+    return /free.?tier|data.?policy|region|entitle|upgrade|subscription/i.test(detail);
+}
+/**
+ * The levels worth trying: what the endpoint says it takes, else everything known.
+ *
+ * Asked for a level that cannot exist, some endpoints answer with their whole list — "expected one
+ * of `none`, `minimal`, … `ultra`, `max`", or "Supported values: [minimal, low, … max]" (measured
+ * 2026-09-22). That is a candidate list and nothing more: `muse-spark-1.3-contributor` names `max`
+ * among its supported values and then refuses it with a 400, so what a level actually does is still
+ * settled by sending it.
+ */
+async function candidateLevels(id, candidate, ladder, deps) {
+    let listed = [];
+    try {
+        const response = await deps.fetch(endpointFor(candidate.wire, candidate.url), { method: "POST", headers: requestHeaders(candidate, deps), body: requestBody(candidate.wire, id, NOT_A_LEVEL) });
+        if (!response.ok)
+            listed = parseLevels(await response.text());
+    }
+    catch { /* the endpoint said nothing; fall back to everything known */ }
+    const wanted = listed.length > 0 ? listed : [...ladder, ...KNOWN_EFFORTS];
+    const seen = new Set(wanted);
+    // Canonical order first so the GUI reads weakest to strongest, then anything newly named.
+    return [...KNOWN_EFFORTS.filter((level) => seen.has(level)), ...wanted.filter((level) => !KNOWN_EFFORTS.includes(level))]
+        .filter((level, index, all) => all.indexOf(level) === index);
+}
+/** The levels an endpoint listed in its complaint, or nothing when it did not list any. */
+export function parseLevels(message) {
+    const listed = /supported values:\s*\[([^\]]+)\]/i.exec(message)?.[1] ?? /expected one of\s+(.+?)(?:\s+at line\b|$)/i.exec(message)?.[1];
+    if (!listed)
+        return [];
+    return [...listed.matchAll(/[A-Za-z][A-Za-z0-9_-]*/g)].map((match) => match[0].toLowerCase()).filter((level) => level !== NOT_A_LEVEL);
+}
+/**
+ * Which levels this model accepts, one at a time.
+ *
+ * Only an explicit refusal is a capability answer. A 429, a 5xx or a dropped connection says nothing
+ * about the level itself, and dropping a level on one of those would quietly shrink the ladder the
+ * GUI offers over a momentary hiccup. Those levels are kept: an unmeasured level is not an absent one.
+ */
+async function measureLadder(id, candidate, ladder, deps) {
+    const supported = [];
+    const url = endpointFor(candidate.wire, candidate.url);
+    for (const level of await candidateLevels(id, candidate, ladder, deps)) {
+        let response;
+        try {
+            response = await deps.fetch(url, { method: "POST", headers: requestHeaders(candidate, deps), body: requestBody(candidate.wire, id, level) });
+        }
+        catch {
+            supported.push(level); // transient — keep
+            continue;
+        }
+        if (!refusedLevel(response.status))
+            supported.push(level);
+    }
+    return supported;
+}
+/**
+ * Establish one model's wire and effort ladder by calling it.
+ *
+ * Candidates are tried in order and the first 200 wins; the rest are never called, so the common
+ * case (the provider's own wire, first) is one request. An auth failure stops everything: the key
+ * was refused before the path mattered, so reporting anything but "auth" would send the user to
+ * check the wire when the problem is the credential. When no candidate answers, the result carries
+ * the last status and body as `error` and no `wire`.
+ */
+export async function measureModel(id, candidates, ladder, deps) {
+    if (candidates.length === 0)
+        return { id, error: "no candidate wire to try" };
+    let failure = "no candidate wire answered";
+    for (const candidate of candidates) {
+        let response;
+        try {
+            response = await deps.fetch(endpointFor(candidate.wire, candidate.url), { method: "POST", headers: requestHeaders(candidate, deps), body: requestBody(candidate.wire, id) });
+        }
+        catch (e) {
+            failure = `network: ${errorText(e)}`;
+            continue;
+        }
+        if (response.status === 401)
+            return { id, error: "auth" };
+        if (response.status === 403) {
+            // A plan refusing the model is a fact about the model, and worth reporting as one: no other
+            // wire will answer either, so there is nothing left to try.
+            const detail = snippet(await response.text());
+            return { id, error: refusedByPlan(detail) ? `not-entitled: ${detail}` : "auth" };
+        }
+        if (response.ok) {
+            if (ladder.length === 0)
+                return { id, wire: candidate.wire };
+            return { id, wire: candidate.wire, effortLevels: await measureLadder(id, candidate, ladder, deps) };
+        }
+        failure = `${response.status} ${snippet(await response.text())}`.trim();
+    }
+    return { id, error: failure };
+}

package/dist/router/src/compat.js

@@ -7,6 +7,7 @@ export const STRICT_COMPAT_CAPS = {
     thinking: "none",
     betas: false,
     cacheControl: true,
+    serverTools: false,
 };
 export function resolveCompatibleCaps(preset, override) {
     return {
@@ -14,6 +15,7 @@ export function resolveCompatibleCaps(preset, override) {
         thinking: override?.thinking ?? preset?.thinking ?? STRICT_COMPAT_CAPS.thinking,
         betas: override?.betas ?? preset?.betas ?? STRICT_COMPAT_CAPS.betas,
         cacheControl: override?.cacheControl ?? preset?.cacheControl ?? STRICT_COMPAT_CAPS.cacheControl,
+        serverTools: override?.serverTools ?? preset?.serverTools ?? STRICT_COMPAT_CAPS.serverTools,
     };
 }
 function record(value) {
@@ -131,7 +133,9 @@ export function sanitizeForCompatible(json, caps) {
                 kept.push(tool);
                 continue;
             }
-            if (source.type !== undefined && source.type !== "custom") {
+            // A provider that runs server tools keeps them: dropping one it can execute throws away a
+            // capability the user is paying for, and the loss is invisible (see `serverTools`).
+            if (source.type !== undefined && source.type !== "custom" && !caps.serverTools) {
                 dropped++;
                 if (typeof source.name === "string")
                     droppedNames.add(source.name);