@sriinnu/kosha-discovery 1.2.0 → 1.5.1

package/dist/proxy.js

@@ -15,31 +15,162 @@
  *   <N>k           minimum context window in tokens
  *   provider:<id>  pin to a specific serving-layer provider
  *
- * Supported transports: openai, openai-compatible-http, ollama.
- * Anthropic, Google, Cohere, Bedrock, Vertex speak different wire formats
- * and are not yet proxied.
+ * Supported transports: openai, openai-compatible-http, ollama, anthropic.
+ * Anthropic is proxied through the OpenAI ↔ Anthropic wire translator
+ * (`wire-anthropic.ts`): streaming, tools / tool calls, image_url parts,
+ * response_format, and reasoning_effort are carried; audio input and
+ * non-function tools fail over to a native OpenAI-compatible route. Google,
+ * Bedrock, and Vertex speak cloud-SDK wire formats and are not yet proxied.
+ *
+ * Spend accounting: every successful forward writes a ledger row with the
+ * pre-flight estimate AND, when the upstream returned a `usage` block (JSON
+ * or SSE), the reconciled actual cost. Budget enforcement prefers the actual.
  *
  * Response headers added by the proxy:
- *   x-kosha-model      — resolved model ID
- *   x-kosha-provider   — resolved provider
- *   x-kosha-requested  — original model string from the caller
+ *   x-kosha-model               — resolved model ID
+ *   x-kosha-provider            — resolved provider
+ *   x-kosha-requested           — original model string from the caller
+ *   x-kosha-attempt-chain       — provider:status for each attempt
+ *   x-kosha-estimated-cost-usd  — pre-flight estimate
+ *   x-kosha-actual-cost-usd     — reconciled from upstream usage (non-streaming)
+ *   x-kosha-usage-source        — upstream | estimate (non-streaming)
+ *   x-kosha-wire-notes          — Anthropic translator notes (dropped / degraded fields)
  * @module
  */
-import { getProviderDescriptor, providerExecutionCredentialRequired } from "./provider-catalog.js";
+import { randomUUID } from "node:crypto";
+import { getProviderDescriptor, listProviderDescriptors, providerExecutionCredentialRequired } from "./provider-catalog.js";
 import { fallbackRegistryCredential, getRegistryCredentialResolver } from "./registry-runtime.js";
+import { parseRouteStrategy } from "./registry-routing.js";
+import { actualCostFromUsage, appendLedgerEntry, estimateRequestCost, readMonthlyBudgetUsd, readSpendForMonth, readTenantBudgetUsd, } from "./cost.js";
+import { UnsupportedWireContentError, coerceOpenAIChatRequest, translateAnthropicStreamToOpenAI, translateAnthropicToOpenAI, translateOpenAIToAnthropicWithNotes, } from "./wire-anthropic.js";
+const proxyCounters = {
+    requestsTotal: 0,
+    errorsTotal: 0,
+    byProvider: {},
+};
+/** Record one forwarded outcome: total + per-provider requests/errors/latency. */
+function bumpProxyMetric(provider, ok, latencyMs) {
+    proxyCounters.requestsTotal += 1;
+    if (!ok)
+        proxyCounters.errorsTotal += 1;
+    let c = proxyCounters.byProvider[provider];
+    if (!c) {
+        c = { requests: 0, errors: 0, latencySumMs: 0 };
+        proxyCounters.byProvider[provider] = c;
+    }
+    c.requests += 1;
+    if (!ok)
+        c.errors += 1;
+    c.latencySumMs += latencyMs;
+}
+/**
+ * Snapshot the proxy hot-path counters. In-memory only (resets on restart);
+ * complements the breaker / provider-observation data the registry exposes.
+ */
+export function snapshotProxyMetrics() {
+    const byProvider = {};
+    for (const [provider, c] of Object.entries(proxyCounters.byProvider)) {
+        byProvider[provider] = {
+            requests: c.requests,
+            errors: c.errors,
+            avgLatencyMs: c.requests > 0 ? Math.round(c.latencySumMs / c.requests) : 0,
+        };
+    }
+    return { requestsTotal: proxyCounters.requestsTotal, errorsTotal: proxyCounters.errorsTotal, byProvider };
+}
+// ---------------------------------------------------------------------------
+// Upstream host allowlist (SSRF guard)
+// ---------------------------------------------------------------------------
+/**
+ * Hostnames the proxy is allowed to forward to. Built once at module load
+ * from the in-process provider catalog (NOT from any file/cache value).
+ * Even though buildUpstreamUrl already only takes the host from the in-process
+ * catalog for non-local providers, validating the parsed URL's hostname
+ * against this list here lets static analyzers (CodeQL `js/request-forgery`)
+ * recognize this code as a sanitizer for the outbound fetch.
+ */
+const ALLOWED_UPSTREAM_HOSTS = (() => {
+    const hosts = new Set();
+    for (const descriptor of listProviderDescriptors()) {
+        try {
+            hosts.add(new URL(descriptor.defaultBaseUrl).hostname);
+        }
+        catch {
+            // A malformed catalog entry should not block loading the module.
+        }
+    }
+    return Object.freeze(Array.from(hosts));
+})();
+/**
+ * Return the upstream URL if-and-only-if its hostname is one we trust.
+ * Returns null for an unparseable URL, an exotic protocol, or a hostname
+ * outside the catalog allowlist / loopback families. The caller refuses the
+ * request in that case rather than dialing a tainted host. Written with
+ * explicit `===` checks against literal strings so static taint analysis
+ * recognizes this function as a sanitizer.
+ */
+function safeUpstreamUrl(rawUrl, isLocalProvider) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        return null;
+    }
+    // Block exotic schemes that fetch would otherwise accept (data:, file:, …).
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+        return null;
+    const host = parsed.hostname;
+    if (isLocalProvider) {
+        // Loopback-only for user-configurable local runtimes. Explicit literal
+        // comparisons let CodeQL recognize this as a sanitizer.
+        if (host === "localhost")
+            return parsed;
+        if (host === "127.0.0.1")
+            return parsed;
+        if (host === "::1")
+            return parsed;
+        if (host === "0.0.0.0")
+            return parsed;
+        return null;
+    }
+    // Non-local: hostname must match one drawn from the in-process catalog.
+    for (const allowed of ALLOWED_UPSTREAM_HOSTS) {
+        if (host === allowed)
+            return parsed;
+    }
+    return null;
+}
 // native-http providers that speak the OpenAI wire format natively.
 // All openai-compatible-http providers are implicitly forwardable.
 const NATIVE_OPENAI_WIRE = new Set(["openai", "ollama"]);
+// native-http providers whose wire format we translate into OpenAI-compatible
+// at the proxy boundary, so the SDK contract stays OpenAI throughout.
+const TRANSLATABLE_WIRE = new Set(["anthropic"]);
+const KOSHA_PREFIX = "kosha:";
+/**
+ * Parse a `kosha:<strategy>[filters]` selector. Returns null when the model
+ * string is not a kosha selector or names an unknown strategy (the caller
+ * then falls through to direct model/alias resolution).
+ *
+ * Examples: `kosha:cheapest`, `kosha:fastest[tool_use,128k]`,
+ * `kosha:reliable[provider:groq]`, `kosha:balanced[vision]`.
+ */
 function parseKoshaHint(model) {
-    if (!model.startsWith("kosha:cheapest"))
+    if (!model.startsWith(KOSHA_PREFIX))
         return null;
-    const m = /\[([^\]]*)\]/.exec(model);
-    if (!m)
-        return {};
-    const hint = {};
-    for (const part of m[1].split(",").map((s) => s.trim()).filter(Boolean)) {
+    const rest = model.slice(KOSHA_PREFIX.length);
+    const bracket = /\[([^\]]*)\]/.exec(rest);
+    const head = (bracket ? rest.slice(0, bracket.index) : rest).trim();
+    const strategy = parseRouteStrategy(head);
+    if (!strategy)
+        return null;
+    const hint = { strategy };
+    if (!bracket)
+        return hint;
+    for (const part of bracket[1].split(",").map((s) => s.trim()).filter(Boolean)) {
         if (part.startsWith("provider:")) {
-            hint.provider = part.slice(9);
+            hint.provider = part.slice("provider:".length);
         }
         else if (/^\d+k$/i.test(part)) {
             hint.minContext = Number.parseInt(part, 10) * 1_000;
@@ -54,13 +185,18 @@ function parseKoshaHint(model) {
 // Model resolution
 // ---------------------------------------------------------------------------
 function isForwardable(model) {
+    // Retired models are no longer served upstream — never offer them as a
+    // proxy route, even when their transport would otherwise be forwardable.
+    if (model.status === "retired")
+        return false;
     const descriptor = getProviderDescriptor(model.provider);
     if (!descriptor)
         return false;
     if (descriptor.transport === "openai-compatible-http")
         return true;
-    if (descriptor.transport === "native-http")
-        return NATIVE_OPENAI_WIRE.has(model.provider);
+    if (descriptor.transport === "native-http") {
+        return NATIVE_OPENAI_WIRE.has(model.provider) || TRANSLATABLE_WIRE.has(model.provider);
+    }
     return false; // cloud-sdk (bedrock, vertex) needs per-SDK translation
 }
 function isExecutableRoute(registry, model) {
@@ -71,56 +207,205 @@ function isExecutableRoute(registry, model) {
         return true;
     return registry.provider(model.provider)?.authenticated === true;
 }
-function resolveProxyModel(registry, requested) {
+/**
+ * Resolve an ordered list of forwardable candidate routes for `requested`.
+ *
+ * The order is the failover sequence: routes we hold credentials for come
+ * first (ranked by the selector's strategy for kosha: hints), then any other
+ * forwardable route. Duplicates (same provider + model id) are removed. An
+ * empty list means nothing forwardable matched.
+ */
+function resolveProxyCandidates(registry, requested) {
     const hint = parseKoshaHint(requested);
     if (hint !== null) {
-        const result = registry.cheapestModels({
+        const ranked = registry.rankedRoutes({
             mode: "chat",
             capability: hint.capability,
             provider: hint.provider,
             limit: 20,
-        });
-        const candidates = hint.minContext
-            ? result.matches.filter((m) => m.model.contextWindow >= hint.minContext)
-            : result.matches;
-        // Only pick a provider we can actually forward to.
-        return candidates.find((m) => isExecutableRoute(registry, m.model))?.model ??
-            candidates.find((m) => isForwardable(m.model))?.model ??
-            null;
+        }, hint.strategy);
+        const filtered = hint.minContext
+            ? ranked.filter((r) => r.model.contextWindow >= hint.minContext)
+            : ranked;
+        const exec = filtered.filter((r) => isExecutableRoute(registry, r.model)).map((r) => r.model);
+        const fwd = filtered
+            .filter((r) => isForwardable(r.model) && !isExecutableRoute(registry, r.model))
+            .map((r) => r.model);
+        return dedupeModels([...exec, ...fwd]);
     }
     // For a specific model ID or alias, prefer the canonical card but fall back
     // to any forwardable route if the primary provider isn't proxiable (e.g.
-    // "claude-sonnet-4-6" resolves to Anthropic by default, but if the caller
+    // "claude-sonnet-5" resolves to Anthropic by default, but if the caller
     // only has an OpenRouter key, we should route through OpenRouter instead).
     const primary = registry.model(requested);
-    if (primary && isExecutableRoute(registry, primary))
-        return primary;
     const routes = registry.modelRoutes(requested);
-    return routes.find((route) => isExecutableRoute(registry, route)) ??
-        (primary && isForwardable(primary) ? primary : undefined) ??
-        routes.find(isForwardable) ??
-        primary ??
-        null;
+    const ordered = [];
+    if (primary && isExecutableRoute(registry, primary))
+        ordered.push(primary);
+    for (const route of routes)
+        if (isExecutableRoute(registry, route))
+            ordered.push(route);
+    if (primary && isForwardable(primary))
+        ordered.push(primary);
+    for (const route of routes)
+        if (isForwardable(route))
+            ordered.push(route);
+    return dedupeModels(ordered);
+}
+/** Allowed shape of a tenant tag: short, filesystem/log-safe identifier. */
+const TENANT_TAG_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
+/**
+ * Extract a tenant tag from the request. Two carriers are accepted:
+ *
+ *   - `x-kosha-tenant: <name>` — preferred, and the only option when
+ *     `KOSHA_PROXY_TOKEN` is set (the Authorization header then carries the
+ *     operator token instead).
+ *   - `Authorization: Bearer kosha-tenant-<name>` — legacy carrier, kept for
+ *     callers that can only set a bearer token.
+ *
+ * The tag is a bucketing label only (per-tenant ledger rows + budget), never
+ * authentication — the bearer is consumed and replaced with the resolved
+ * upstream credential before forwarding. Returns null for any non-conforming
+ * value so downstream code doesn't have to guard for empties.
+ */
+export function parseTenantTag(authHeader, tenantHeader) {
+    const explicit = tenantHeader?.trim();
+    if (explicit && TENANT_TAG_PATTERN.test(explicit))
+        return explicit;
+    if (!authHeader)
+        return null;
+    const match = /^\s*Bearer\s+kosha-tenant-([A-Za-z0-9_.-]{1,64})\s*$/i.exec(authHeader);
+    return match ? match[1] : null;
+}
+/**
+ * Pull a `{ message, type }` error shape out of an Anthropic upstream error
+ * body. Anthropic errors are `{ type, error: { type, message } }`; a flat
+ * `{ message, type }` is also tolerated. Defaults keep the OpenAI error
+ * envelope well-formed when the body doesn't match either shape.
+ */
+function extractAnthropicError(raw) {
+    if (raw && typeof raw === "object") {
+        const obj = raw;
+        const err = obj.error && typeof obj.error === "object" ? obj.error : obj;
+        return {
+            message: typeof err.message === "string" ? err.message : "anthropic upstream error",
+            type: typeof err.type === "string" ? err.type : "upstream_error",
+        };
+    }
+    return { message: "anthropic upstream error", type: "upstream_error" };
+}
+/** Stable de-dup of model cards by provider + id, preserving first occurrence. */
+function dedupeModels(models) {
+    const seen = new Set();
+    const out = [];
+    for (const model of models) {
+        const key = `${model.provider}:${model.id}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(model);
+    }
+    return out;
+}
+function resolveProxyModel(registry, requested) {
+    return resolveProxyCandidates(registry, requested)[0] ?? null;
 }
 // ---------------------------------------------------------------------------
 // URL builder
 // ---------------------------------------------------------------------------
 function buildUpstreamUrl(model, registry) {
-    const info = registry.provider(model.provider);
     const descriptor = getProviderDescriptor(model.provider);
-    const base = (descriptor?.isLocal
-        ? info?.baseUrl ?? descriptor.defaultBaseUrl
-        : descriptor?.defaultBaseUrl ?? info?.baseUrl ?? "").replace(/\/$/, "");
+    // For non-local providers we ONLY use the in-process catalog's
+    // defaultBaseUrl. The registry's `baseUrl` is loaded from disk and is
+    // untrusted for routing decisions; using it in the URL would let a
+    // poisoned cache redirect outbound traffic (SSRF / request forgery).
+    // Local providers are user-configurable, so we still let the registry
+    // override the default host — but the safeUpstreamUrl() loopback check
+    // in the request handler refuses anything outside the loopback families.
+    let base;
+    if (descriptor?.isLocal) {
+        const info = registry.provider(model.provider);
+        base = (info?.baseUrl ?? descriptor.defaultBaseUrl).replace(/\/$/, "");
+    }
+    else {
+        base = (descriptor?.defaultBaseUrl ?? "").replace(/\/$/, "");
+    }
     // Some native/local roots expose the OpenAI-compatible layer under /v1.
     if ((model.provider === "openai" || model.provider === "ollama" || model.provider === "llama.cpp") && !base.endsWith("/v1")) {
         return `${base}/v1/chat/completions`;
     }
     return `${base}/chat/completions`;
 }
+/**
+ * Make caller- or upstream-derived text safe to reflect into a response
+ * header: printable ASCII only, bounded length. HTTP header values must be
+ * ISO-8859-1 and undici's `Headers.set` throws on anything above U+00FF —
+ * which, if it happened after the upstream call, would turn a paid request
+ * into an unrecorded 500.
+ */
+function headerSafe(value, max = 400) {
+    return value.replace(/[^\x20-\x7e]/g, "?").slice(0, max);
+}
+/**
+ * Pass an OpenAI-compatible SSE stream through byte-for-byte while watching
+ * for a `usage` object in the events (providers emit it on the final chunk
+ * when the caller set `stream_options.include_usage`). Resolves with the last
+ * usage seen, or null when the stream never carried one — on every terminal
+ * path, including the client cancelling or the upstream erroring.
+ */
+function observeOpenAIStreamUsage(upstream) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let lastUsage = null;
+    let resolve;
+    const usage = new Promise((r) => {
+        resolve = r;
+    });
+    const scan = (flushAll) => {
+        const parts = buffer.split(/\r?\n\r?\n/);
+        buffer = flushAll ? "" : (parts.pop() ?? "");
+        // Never let a stream without blank-line separators grow the buffer unbounded.
+        if (buffer.length > 65_536)
+            buffer = buffer.slice(-65_536);
+        for (const part of parts) {
+            for (const line of part.split(/\r?\n/)) {
+                if (!line.startsWith("data:"))
+                    continue;
+                const data = line.slice(5).trim();
+                if (!data || data === "[DONE]")
+                    continue;
+                try {
+                    const evt = JSON.parse(data);
+                    if (evt && typeof evt === "object" && evt.usage && typeof evt.usage === "object")
+                        lastUsage = evt.usage;
+                }
+                catch {
+                    // partial / non-JSON line — ignore
+                }
+            }
+        }
+    };
+    const stream = upstream.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            controller.enqueue(chunk);
+            buffer += decoder.decode(chunk, { stream: true });
+            scan(false);
+        },
+        flush() {
+            buffer += decoder.decode();
+            scan(true);
+            resolve(lastUsage);
+        },
+        cancel() {
+            resolve(lastUsage);
+        },
+    }));
+    return { stream, usage };
+}
 // ---------------------------------------------------------------------------
 // Route registration
 // ---------------------------------------------------------------------------
-export function registerProxyRoutes(app, registry) {
+export function registerProxyRoutes(app, registry, shutdownSignal) {
     // OpenAI-compatible model list — returns all models the proxy can forward.
     // Required for SDK compatibility: OpenAI clients call this before chat requests.
     app.get("/proxy/v1/models", (ctx) => {
@@ -148,66 +433,446 @@ export function registerProxyRoutes(app, registry) {
         if (!requested) {
             return ctx.json({ error: "missing required field: model" }, 400);
         }
-        // ── Resolve model ──────────────────────────────────────────────
-        const model = resolveProxyModel(registry, requested);
-        if (!model) {
+        // ── Resolve candidate routes (failover order) ──────────────────
+        const candidates = resolveProxyCandidates(registry, requested);
+        if (candidates.length === 0) {
+            // Distinguish "found but not proxiable" (422) from "not found" (404).
+            const primary = registry.model(requested);
+            if (primary && !isForwardable(primary)) {
+                const descriptor = getProviderDescriptor(primary.provider);
+                return ctx.json({
+                    error: `provider '${primary.provider}' uses '${descriptor?.transport ?? "unknown"}' transport — proxy not yet supported`,
+                    resolvedModel: primary.id,
+                    resolvedProvider: primary.provider,
+                }, 422);
+            }
             return ctx.json({ error: `no model found for '${requested}'` }, 404);
         }
-        if (!isForwardable(model)) {
-            const descriptor = getProviderDescriptor(model.provider);
-            return ctx.json({
-                error: `provider '${model.provider}' uses '${descriptor?.transport ?? "unknown"}' transport — proxy not yet supported`,
-                resolvedModel: model.id,
-                resolvedProvider: model.provider,
-            }, 422);
+        // `requested` is caller-controlled. Reduce it to printable ASCII and
+        // bound the length before reflecting it into a response header: the
+        // Headers API throws on CR/LF and on any non-Latin-1 character, which
+        // would turn a malformed model string into an unhandled 500.
+        const safeRequested = headerSafe(requested, 200);
+        // Optional per-tenant tag, drawn from a kosha-tenant-<name> bearer token.
+        // We don't trust the value as authentication — it just buckets ledger
+        // rows and per-tenant budgets. The proxy still resolves real upstream
+        // credentials from env / CLI files as usual.
+        const tenant = parseTenantTag(ctx.req.header("authorization"), ctx.req.header("x-kosha-tenant"));
+        // ── Budget gate ────────────────────────────────────────────────
+        // When a budget is configured we MUST fail closed: if the ledger is
+        // unreadable (permissions, FS error, partial mount) we cannot prove the
+        // caller is under budget, so we refuse. Treating the read failure as
+        // $0 spent would let an attacker bypass the cap by corrupting the
+        // ledger file.
+        // The global cap is always checked against TOTAL spend — never a
+        // tenant's slice — so a caller cannot escape it by inventing a fresh
+        // tenant tag per request. A per-tenant cap is an additional gate.
+        const budget = readMonthlyBudgetUsd();
+        const tenantBudget = tenant ? readTenantBudgetUsd() : null;
+        if (budget !== null || tenantBudget !== null) {
+            let spent = 0;
+            let tenantSpent = 0;
+            try {
+                if (budget !== null)
+                    spent = await readSpendForMonth(Date.now());
+                if (tenantBudget !== null)
+                    tenantSpent = await readSpendForMonth(Date.now(), tenant);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return ctx.json({
+                    error: "budget enforcement unavailable — ledger could not be read",
+                    detail: message,
+                    budgetUsd: budget ?? tenantBudget,
+                }, 503);
+            }
+            if (budget !== null && spent >= budget) {
+                return ctx.json({ error: "monthly budget exceeded", spentUsd: spent, budgetUsd: budget }, 429, {
+                    "x-kosha-budget-remaining-usd": Math.max(0, budget - spent).toFixed(4),
+                    "x-kosha-budget-usd": budget.toFixed(2),
+                });
+            }
+            if (tenantBudget !== null && tenantSpent >= tenantBudget) {
+                return ctx.json({ error: "tenant monthly budget exceeded", tenant, spentUsd: tenantSpent, budgetUsd: tenantBudget }, 429, {
+                    "x-kosha-budget-remaining-usd": Math.max(0, tenantBudget - tenantSpent).toFixed(4),
+                    "x-kosha-budget-usd": tenantBudget.toFixed(2),
+                });
+            }
         }
-        // ── Resolve credential ─────────────────────────────────────────
         // Use the full 5-tier CredentialResolver (CLI files, ADC, OAuth, env vars)
         // so the proxy honours the same credential sources as discovery.
         const resolver = await getRegistryCredentialResolver();
-        const credential = resolver
-            ? await resolver.resolve(model.provider)
-            : fallbackRegistryCredential(model.provider);
-        const bearerToken = credential.apiKey ?? credential.accessToken;
-        const credentialDescriptor = getProviderDescriptor(model.provider);
-        if (credentialDescriptor && providerExecutionCredentialRequired(credentialDescriptor) && !bearerToken) {
-            const envHint = credentialDescriptor.credentialEnvVars.length
-                ? credentialDescriptor.credentialEnvVars.join(" or ")
-                : credentialDescriptor.primaryCredentialEnvVar;
+        // ── Forward, failing over on transport / 5xx errors ────────────
+        // We try ranked candidates in order, bounding the number of actual
+        // upstream fetches so a wave of dead providers can't stall the caller.
+        // A 4xx is the caller's own fault (bad request, bad key) and is returned
+        // as-is; a 5xx or network error rolls over to the next candidate.
+        const MAX_FETCHES = 3;
+        // Hard ceiling on a single upstream call so a hung provider can't stall
+        // the caller or hold a connection open past shutdown.
+        const UPSTREAM_TIMEOUT_MS = 30_000;
+        const attemptChain = [];
+        let fetchAttempts = 0;
+        let lastNoCred = null;
+        let sawCredentialedRoute = false;
+        let lastUnsupportedWire = null;
+        const wantsStream = body.stream === true;
+        const includeUsage = wantsStream && body.stream_options?.include_usage === true;
+        for (const model of candidates) {
+            const credential = resolver
+                ? await resolver.resolve(model.provider)
+                : fallbackRegistryCredential(model.provider);
+            const bearerToken = credential.apiKey ?? credential.accessToken;
+            const descriptor = getProviderDescriptor(model.provider);
+            if (descriptor && providerExecutionCredentialRequired(descriptor) && !bearerToken) {
+                const envHint = descriptor.credentialEnvVars.length
+                    ? descriptor.credentialEnvVars.join(" or ")
+                    : descriptor.primaryCredentialEnvVar;
+                lastNoCred = { provider: model.provider, envHint };
+                attemptChain.push(`${model.provider}:no-credential`);
+                continue; // can't call this provider — try the next route
+            }
+            sawCredentialedRoute = true;
+            if (fetchAttempts >= MAX_FETCHES)
+                break;
+            const upstreamUrl = buildUpstreamUrl(model, registry);
+            // The proxy never forwards to a host outside the in-process catalog
+            // allowlist. The registry's `provider.baseUrl` is loaded from disk
+            // cache (or could come from a user config file), so a poisoned
+            // value must NOT redirect a request to an attacker-chosen host —
+            // this is the SSRF / `js/request-forgery` guard.
+            const safeUrl = safeUpstreamUrl(upstreamUrl, descriptor?.isLocal === true);
+            if (!safeUrl) {
+                attemptChain.push(`${model.provider}:untrusted-host`);
+                continue;
+            }
+            const usesAnthropicWire = model.provider === "anthropic";
+            const upstreamHeaders = { "content-type": "application/json" };
+            let upstreamBody;
+            let upstreamUrlString;
+            let wireNotes = [];
+            if (usesAnthropicWire) {
+                // Anthropic /v1/messages: auth via x-api-key + anthropic-version,
+                // body translated from OpenAI chat-completions on the way in,
+                // response (JSON or SSE) translated back on the way out. The
+                // translator is fail-safe: content it cannot carry throws
+                // UnsupportedWireContentError rather than being silently mangled;
+                // we then fail over to a native-OpenAI route for the same model
+                // (OpenRouter, etc.) and only 422 if none exists.
+                upstreamHeaders["x-api-key"] = bearerToken ?? "";
+                upstreamHeaders["anthropic-version"] = "2023-06-01";
+                let translation;
+                try {
+                    translation = translateOpenAIToAnthropicWithNotes({ ...coerceOpenAIChatRequest(body), model: model.id });
+                }
+                catch (err) {
+                    if (err instanceof UnsupportedWireContentError) {
+                        attemptChain.push(`${model.provider}:unsupported-wire-content`);
+                        lastUnsupportedWire = err.message;
+                        continue;
+                    }
+                    throw err;
+                }
+                wireNotes = translation.notes;
+                if (model.maxOutputTokens > 0 && translation.request.max_tokens > model.maxOutputTokens) {
+                    wireNotes.push(`clamped max_tokens ${translation.request.max_tokens} to ${model.maxOutputTokens}: model output cap`);
+                    translation.request.max_tokens = model.maxOutputTokens;
+                }
+                upstreamBody = JSON.stringify(translation.request);
+                // Rebuild the URL via the WHATWG URL API rather than a string
+                // `replace`, so the pathname swap can't be tripped by a fragment
+                // or query-string that happens to contain `/chat/completions`.
+                // `safeUrl` is already allowlist-validated, so reusing its
+                // origin keeps the SSRF guarantee intact.
+                const anthropicUrl = new URL(safeUrl.toString());
+                anthropicUrl.pathname = "/v1/messages";
+                upstreamUrlString = anthropicUrl.toString();
+            }
+            else {
+                if (bearerToken)
+                    upstreamHeaders.authorization = `Bearer ${bearerToken}`;
+                upstreamBody = JSON.stringify({ ...body, model: model.id });
+                upstreamUrlString = safeUrl.toString();
+            }
+            fetchAttempts += 1;
+            const attemptStart = Date.now();
+            // Bound the upstream call so a hung provider can't stall the caller,
+            // and abort in-flight requests when kosha is shutting down so we
+            // drain instead of dropping streams mid-flight. The timer covers
+            // headers and non-streaming bodies only: a streamed body legitimately
+            // runs for minutes on 128K-output models, so once we start relaying
+            // a stream the timer is released and only the shutdown signal (and
+            // the client hanging up) can end it.
+            const upstreamAbort = new AbortController();
+            const upstreamTimer = setTimeout(() => upstreamAbort.abort(new DOMException(`upstream did not respond within ${UPSTREAM_TIMEOUT_MS}ms`, "TimeoutError")), UPSTREAM_TIMEOUT_MS);
+            const releaseTimer = () => clearTimeout(upstreamTimer);
+            let upstream;
+            try {
+                const signal = shutdownSignal ? AbortSignal.any([upstreamAbort.signal, shutdownSignal]) : upstreamAbort.signal;
+                upstream = await fetch(upstreamUrlString, {
+                    method: "POST",
+                    headers: upstreamHeaders,
+                    body: upstreamBody,
+                    signal,
+                });
+            }
+            catch (err) {
+                releaseTimer();
+                attemptChain.push(`${model.provider}:error`);
+                const errLatency = Date.now() - attemptStart;
+                const errorType = err instanceof Error && err.name === "TimeoutError" ? "timeout" : "transport";
+                registry.recordProxyOutcome(model.provider, { ok: false, latencyMs: errLatency, errorType });
+                bumpProxyMetric(model.provider, false, errLatency);
+                if (fetchAttempts < MAX_FETCHES)
+                    continue; // fail over
+                const message = err instanceof Error ? err.message : String(err);
+                return ctx.json({ error: `upstream unreachable: ${message}`, resolvedProvider: model.provider, attemptChain }, 502);
+            }
+            // A retryable upstream failure (5xx) rolls over to the next route,
+            // unless we've spent our fetch budget — then we surface it.
+            if (upstream.status >= 500 && fetchAttempts < MAX_FETCHES) {
+                releaseTimer();
+                attemptChain.push(`${model.provider}:${upstream.status}`);
+                await upstream.body?.cancel().catch(() => { });
+                registry.recordProxyOutcome(model.provider, {
+                    ok: false,
+                    status: upstream.status,
+                    latencyMs: Date.now() - attemptStart,
+                    errorType: "transport",
+                });
+                bumpProxyMetric(model.provider, false, Date.now() - attemptStart);
+                continue;
+            }
+            attemptChain.push(`${model.provider}:${upstream.status}`);
+            // Feed the real inference outcome into the health tracker so
+            // kosha:reliable/fastest/balanced rank on actual proxy traffic, not
+            // just discovery-ping latency. A 4xx is the caller's fault and not a
+            // provider-health signal, so we neither credit nor penalize it.
+            const attemptLatencyMs = Date.now() - attemptStart;
+            if (upstream.ok) {
+                registry.recordProxyOutcome(model.provider, { ok: true, status: upstream.status, latencyMs: attemptLatencyMs });
+                bumpProxyMetric(model.provider, true, attemptLatencyMs);
+            }
+            else if (upstream.status >= 500) {
+                registry.recordProxyOutcome(model.provider, {
+                    ok: false,
+                    status: upstream.status,
+                    latencyMs: attemptLatencyMs,
+                    errorType: "transport",
+                });
+                bumpProxyMetric(model.provider, false, attemptLatencyMs);
+            }
+            // Pre-flight cost estimate: (input tokens × inputRate + expected
+            // output × outputRate), reflected on the response so the caller can
+            // audit before paying. When the upstream returns a usage block we
+            // also reconcile the actual cost and record both on the ledger.
+            const estimate = estimateRequestCost(model, body);
+            const responseHeaders = new Headers({
+                "x-kosha-model": model.id,
+                "x-kosha-provider": model.provider,
+                "x-kosha-requested": safeRequested,
+                "x-kosha-attempt-chain": headerSafe(attemptChain.join(",")),
+            });
+            if (wireNotes.length > 0)
+                responseHeaders.set("x-kosha-wire-notes", headerSafe(wireNotes.join("; ")));
+            if (estimate)
+                responseHeaders.set("x-kosha-estimated-cost-usd", estimate.estimatedUsd.toFixed(6));
+            const upstreamStatus = upstream.status;
+            const upstreamOk = upstream.ok;
+            const requestId = randomUUID();
+            // Only charge the ledger on a successful upstream response. A 4xx
+            // is the caller's fault (malformed request, bad key) and costs
+            // nothing upstream — charging it would let malformed traffic
+            // exhaust a tenant's monthly budget. Append failures are
+            // observability losses, never a reason to fail the request.
+            //
+            // The request row is written the moment we know the upstream said
+            // yes — before any body is read or relayed — so a client that
+            // disconnects mid-stream, a stream that errors, or a later header
+            // failure can never leave a paid request unrecorded. Streaming
+            // responses learn their real usage only at the end; that lands as a
+            // separate `adjustment` row carrying the delta.
+            const recordSpend = (actual) => {
+                if (!estimate || !upstreamOk)
+                    return;
+                appendLedgerEntry({
+                    ts: Date.now(),
+                    provider: model.provider,
+                    modelId: model.id,
+                    requested: safeRequested,
+                    tenant,
+                    estimatedUsd: estimate.estimatedUsd,
+                    estimatedInputTokens: estimate.inputTokens,
+                    estimatedOutputTokens: estimate.expectedOutputTokens,
+                    upstreamStatus,
+                    kind: "request",
+                    requestId,
+                    ...(actual
+                        ? {
+                            actualUsd: actual.usd,
+                            actualInputTokens: actual.inputTokens,
+                            actualOutputTokens: actual.outputTokens,
+                            cacheReadTokens: actual.cacheReadTokens,
+                            cacheWriteTokens: actual.cacheWriteTokens,
+                            usageSource: "upstream",
+                        }
+                        : { usageSource: "estimate" }),
+                }).catch(() => { });
+            };
+            const recordAdjustment = (actual) => {
+                if (!estimate || !upstreamOk || !actual)
+                    return;
+                appendLedgerEntry({
+                    ts: Date.now(),
+                    provider: model.provider,
+                    modelId: model.id,
+                    requested: safeRequested,
+                    tenant,
+                    estimatedUsd: 0,
+                    estimatedInputTokens: 0,
+                    estimatedOutputTokens: 0,
+                    upstreamStatus,
+                    kind: "adjustment",
+                    requestId,
+                    adjustmentUsd: actual.usd - estimate.estimatedUsd,
+                    adjustmentInputTokens: actual.inputTokens - estimate.inputTokens,
+                    adjustmentOutputTokens: actual.outputTokens - estimate.expectedOutputTokens,
+                    actualUsd: actual.usd,
+                    actualInputTokens: actual.inputTokens,
+                    actualOutputTokens: actual.outputTokens,
+                    cacheReadTokens: actual.cacheReadTokens,
+                    cacheWriteTokens: actual.cacheWriteTokens,
+                    usageSource: "upstream",
+                }).catch(() => { });
+            };
+            const reflectActual = (actual) => {
+                if (actual) {
+                    responseHeaders.set("x-kosha-actual-cost-usd", actual.usd.toFixed(6));
+                    responseHeaders.set("x-kosha-usage-source", "upstream");
+                }
+                else {
+                    responseHeaders.set("x-kosha-usage-source", "estimate");
+                }
+            };
+            if (usesAnthropicWire) {
+                // Error bodies are re-shaped into the OpenAI error envelope
+                // ({ error: { message, type, code } }) so a client using the
+                // OpenAI SDK reads a structured error instead of an Anthropic
+                // blob it can't parse. Anthropic returns JSON errors even for
+                // stream requests, so this branch runs before the SSE one.
+                responseHeaders.set("content-type", "application/json");
+                if (!upstream.ok) {
+                    let raw;
+                    try {
+                        raw = await upstream.json();
+                    }
+                    catch {
+                        raw = null;
+                    }
+                    releaseTimer();
+                    const aErr = extractAnthropicError(raw);
+                    return new Response(JSON.stringify({ error: { ...aErr, code: String(upstream.status) } }), { status: upstream.status, headers: responseHeaders });
+                }
+                if (wantsStream) {
+                    if (!upstream.body) {
+                        releaseTimer();
+                        recordSpend(null);
+                        return new Response(JSON.stringify({ error: { message: "anthropic upstream returned no stream body", type: "upstream_error" } }), { status: 502, headers: responseHeaders });
+                    }
+                    // Estimate now; reconcile when (if) the stream reports usage.
+                    recordSpend(null);
+                    const { stream, usage } = translateAnthropicStreamToOpenAI(upstream.body, model.id, { includeUsage });
+                    usage.then((u) => recordAdjustment(actualCostFromUsage(model, u, "anthropic"))).catch(() => { });
+                    releaseTimer();
+                    responseHeaders.set("content-type", "text/event-stream; charset=utf-8");
+                    responseHeaders.set("cache-control", "no-cache");
+                    return new Response(stream, { status: 200, headers: responseHeaders });
+                }
+                let raw;
+                try {
+                    raw = await upstream.json();
+                }
+                catch {
+                    releaseTimer();
+                    recordSpend(null);
+                    return new Response(JSON.stringify({ error: { message: "anthropic upstream returned unparseable JSON", type: "upstream_error" } }), { status: 502, headers: responseHeaders });
+                }
+                releaseTimer();
+                const anthropicResponse = raw;
+                const actual = actualCostFromUsage(model, anthropicResponse.usage, "anthropic");
+                reflectActual(actual);
+                recordSpend(actual);
+                const translated = translateAnthropicToOpenAI(anthropicResponse, model.id);
+                return new Response(JSON.stringify(translated), { status: upstream.status, headers: responseHeaders });
+            }
+            // ── Native OpenAI-compatible passthrough ───────────────────────
+            const contentType = upstream.headers.get("content-type") ?? "";
+            if (contentType)
+                responseHeaders.set("content-type", headerSafe(contentType, 200));
+            if (!upstream.ok || !upstream.body) {
+                releaseTimer();
+                if (upstream.ok)
+                    recordSpend(null);
+                return new Response(upstream.body, { status: upstream.status, headers: responseHeaders });
+            }
+            if (contentType.includes("text/event-stream")) {
+                // Bytes pass through untouched; we only watch for a trailing
+                // usage chunk (present when the caller asked for include_usage).
+                // Estimate now; reconcile when the stream ends with usage.
+                recordSpend(null);
+                const { stream, usage } = observeOpenAIStreamUsage(upstream.body);
+                usage.then((u) => recordAdjustment(actualCostFromUsage(model, u, "openai"))).catch(() => { });
+                releaseTimer();
+                return new Response(stream, { status: upstream.status, headers: responseHeaders });
+            }
+            if (contentType.includes("application/json")) {
+                let text;
+                try {
+                    text = await upstream.text();
+                }
+                catch (err) {
+                    releaseTimer();
+                    recordSpend(null);
+                    const message = err instanceof Error ? err.message : String(err);
+                    return ctx.json({ error: `upstream body could not be read: ${message}`, resolvedProvider: model.provider, attemptChain }, 502);
+                }
+                releaseTimer();
+                let usageRaw = null;
+                try {
+                    usageRaw = JSON.parse(text).usage ?? null;
+                }
+                catch {
+                    // Not JSON after all — forward as-is with the estimate only.
+                }
+                const actual = actualCostFromUsage(model, usageRaw, "openai");
+                reflectActual(actual);
+                recordSpend(actual);
+                return new Response(text, { status: upstream.status, headers: responseHeaders });
+            }
+            releaseTimer();
+            reflectActual(null);
+            recordSpend(null);
+            return new Response(upstream.body, { status: upstream.status, headers: responseHeaders });
+        }
+        // Exhausted candidates without a returnable response.
+        if (!sawCredentialedRoute && lastNoCred) {
             return ctx.json({
-                error: `no credential found for '${model.provider}'`,
-                hint: envHint ? `set ${envHint}` : "configure credentials for this provider",
-                resolvedModel: model.id,
-                resolvedProvider: model.provider,
+                error: `no credential found for '${lastNoCred.provider}'`,
+                hint: lastNoCred.envHint ? `set ${lastNoCred.envHint}` : "configure credentials for this provider",
+                resolvedProvider: lastNoCred.provider,
+                attemptChain,
             }, 401);
         }
-        // ── Forward ────────────────────────────────────────────────────
-        const upstreamUrl = buildUpstreamUrl(model, registry);
-        const upstreamHeaders = { "content-type": "application/json" };
-        if (bearerToken)
-            upstreamHeaders.authorization = `Bearer ${bearerToken}`;
-        let upstream;
-        try {
-            upstream = await fetch(upstreamUrl, {
-                method: "POST",
-                headers: upstreamHeaders,
-                body: JSON.stringify({ ...body, model: model.id }),
-            });
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            return ctx.json({ error: `upstream unreachable: ${message}`, resolvedProvider: model.provider }, 502);
+        // 422 only when NO upstream was ever contacted: the translator skipped
+        // every candidate. If a native route was actually tried and failed,
+        // that failure (502) is the honest answer.
+        if (lastUnsupportedWire && fetchAttempts === 0) {
+            return ctx.json({
+                error: `request uses content the Anthropic wire translator cannot carry and no native OpenAI-compatible route was available: ${lastUnsupportedWire}`,
+                attemptChain,
+            }, 422);
         }
-        // ── Stream response back ───────────────────────────────────────
-        const responseHeaders = new Headers({
-            "x-kosha-model": model.id,
-            "x-kosha-provider": model.provider,
-            "x-kosha-requested": requested,
-        });
-        const ct = upstream.headers.get("content-type");
-        if (ct)
-            responseHeaders.set("content-type", ct);
-        return new Response(upstream.body, { status: upstream.status, headers: responseHeaders });
+        return ctx.json({ error: "all upstream providers failed", attemptChain }, 502);
     });
 }
 //# sourceMappingURL=proxy.js.map