llm-relay 0.61.0 → 0.63.0

package/dist/backend.js

@@ -12,12 +12,6 @@ import { knownToolUseIds, rewriteToolUseIds, rewriteToolUseIdsInStream } from ".
 import { STREAM_PREFLIGHT_LIMIT } from "./stream-commit.js";
 import { inspectDialectInOpenAiChat, recoverDialectInOpenAiChatStream, } from "./openai-dialect.js";
 import { observeUsage } from "./usage-observer.js";
-/**
- * A tool-call envelope was present in the response text but could not be parsed — truncated, or a
- * dialect variant we do not model. Distinct from a mapper defect: the relay's translation is fine,
- * the SERVING HOST returned an unusable body. Carried as a retriable failure so the pool fails over
- * to a host that parses its models' dialect.
- */
 export class DialectUnparseableError extends Error {
     dialect;
     constructor(dialect) {
@@ -26,15 +20,6 @@ export class DialectUnparseableError extends Error {
         this.name = "DialectUnparseableError";
     }
 }
-/**
- * A tool call recovered from assistant TEXT names a tool on the operator's destructive list.
- *
- * Unlike `DialectUnparseableError` this is NOT a statement about the host: the envelope parsed
- * fine. It is a config decision, so it is carried as a LOCAL failure — the walk must not fail over
- * (re-asking N models to produce the same refused action) and the deployment must not be charged,
- * the same rule under which a hard cap "never registers on the breaker — it is config, not
- * health". See docs/dialect-rescue-destructive-refusal-2026-08-24.md.
- */
 export class DialectDestructiveError extends Error {
     dialect;
     refused;
@@ -45,69 +30,16 @@ export class DialectDestructiveError extends Error {
         this.name = "DialectDestructiveError";
     }
 }
-/**
- * Response header stating who produced an error status: the provider, or this proxy.
- *
- * Every failure out of `fetchBackend` is a synthesized `Response` — a refused document, a
- * translation bug and a genuinely dead provider all arrived as a bare status code, so a
- * caller counting backend failures (the circuit breaker) charged our own local bugs to the
- * provider and failed over to a second provider that would have failed identically. The
- * marker is what makes them separable; `fetchBackend` states it, the caller decides.
- */
 export const ERROR_ORIGIN_HEADER = "x-llm-relay-error-origin";
-/** Read the origin marker off a Response, when it carries one. */
-/**
- * The declared origins, as a runtime set derived from the type rather than hand-listed beside it.
- *
- * `errorOrigin` is the ONE validator for this header, and its two-literal test was the drift seam:
- * a third `ErrorOrigin` member would have been silently rejected here and defaulted to `"upstream"`
- * by every caller — an unknown origin reported as the provider's fault, and `upstream` also means
- * RETRIABLE, so the walk would reroll other pool members for a fault that may be the relay's own.
- * Deriving the set makes a new member a compile error at the table instead.
- */
 const ERROR_ORIGINS = { upstream: true, local: true };
 export function errorOrigin(res) {
     const v = res.headers.get(ERROR_ORIGIN_HEADER);
     return v !== null && Object.hasOwn(ERROR_ORIGINS, v) ? v : null;
 }
-/**
- * Response header naming the deployment that actually answered — the (provider, model) left
- * standing after pool expansion, benchmark ranking, breaker demotion and failover.
- *
- * A pool request's most basic debugging question is "who served this?", and until now the only
- * way to answer it was to correlate timestamps against the proxy's own log. When every candidate
- * fails it carries the list that was tried instead, so an exhausted pool is self-describing.
- */
 export const SERVED_BY_HEADER = "x-llm-relay-served-by";
-/**
- * WHY each of those candidates dropped out — `"13 tried, 0 served: 4x402, 5x429, 3x403, 1x400"`.
- *
- * `SERVED_BY_HEADER` answers "who was tried"; this answers "what happened to them", which is the
- * half that turns a pool exhaustion into a diagnosis. Without it a client holds one member's
- * error — a HuggingFace 402 pointing at a billing page — while the other twelve failed for three
- * unrelated reasons, and the correct action ("use another pool") is invisible.
- *
- * A header rather than a rewritten body, deliberately: the served body stays the last candidate's
- * real upstream error, because a true upstream error beats a synthesized one.
- */
 export const POOL_ATTEMPTS_HEADER = "x-llm-relay-pool-attempts";
-/** Response metadata headers for credential-aware pool diagnostics. */
 export const CREDENTIAL_HEADER = "x-llm-relay-credential";
 export const CREDENTIAL_ATTEMPTS_HEADER = "x-llm-relay-credential-attempts";
-/**
- * How many refusals in this walk said something the relay could not interpret.
- *
- * The learned-eligibility store converges only as fast as somebody explains the messages it does
- * not recognise, and a pull-only queue is a backlog nobody works. This is the push half: the
- * caller — which is usually an agent that is about to report a pool failure to a human anyway —
- * finds out at the moment it matters that a NEW kind of refusal just appeared, and can run
- * `llm-relay eligibility` while the context is still in hand.
- *
- * ⚠ It is a COUNT, never the message. The message is untrusted text from an external service, and
- * putting it in a response header would be the relay handing an agent attacker-controlled prose in
- * a field agents tend to trust. The count says "go look"; `llm-relay eligibility` shows the text
- * with its provenance and the enum-constrained verdicts it may receive.
- */
 export const UNKNOWN_REFUSAL_HEADER = "x-llm-relay-unknown-refusal";
 function oneShotFetch(fetchFn, signal, onEgress) {
     let invoked = false;
@@ -119,112 +51,23 @@ function oneShotFetch(fetchFn, signal, onEgress) {
         return fetchFn(input, init);
     };
 }
-/**
- * This answer came from BELOW the effort band that was asked for.
- *
- * An effort pool falls back to lower-banded live members once its own band is exhausted, because a
- * band with nothing behind it turns "the strongest models are busy" into "no answer at all". That
- * fallback is automatic — but it must never be silent. A capability downgrade that reads as an
- * ordinary 200 is indistinguishable from having got what you asked for, which is the failure mode
- * that lets a caller build on a weaker answer without knowing it did.
- *
- * Names the deployment and the band it fell out of, e.g. `groq/llama-3.3-70b (below xhigh)`.
- */
 export const DEGRADED_HEADER = "x-llm-relay-degraded";
-/**
- * The walk's FIRST choice was demoted for a spent quota and the answer came from further down.
- *
- * Same maxim as `DEGRADED_HEADER` — automatic degradation is acceptable only because it is
- * announced — but a different fact: capability fell below the requested band there, while here a
- * quota figure said the first choice was spent until a known reset. Value is one bounded line,
- * e.g. `groq/llama-3.3-70b (requests/minute remaining 0, provider-stated)` — axis/period/remaining
- * plus the basis, no credential values, nothing secret.
- */
 export const QUOTA_DEMOTED_HEADER = "x-llm-relay-quota-demoted";
-/**
- * This request was refused by an OPERATOR-SET HARD CAP (G2) — not by a provider.
- *
- * Value is one line per capped credential cell, e.g.
- * `a/nim/z-ai/glm-5.2 requests/day 450/450` — label/deployment, axis/period, the inclusive
- * used/cap pair. Present only when EVERY walked candidate was capped: a partial walk serves
- * from whoever remained, and the pool-attempts header carries the `Nxcapped` tally beside the
- * other outcomes instead. Nothing secret: the label is the config slot name, the figures are
- * the operator's own declaration and this relay's own ledger reading.
- *
- * BOUNDED by cell count, not just by cell width: at most `MAX_CAPPED_HEADER_CELLS` (5) cells are
- * named and the rest are counted as `+K more`. A capped attempt costs no walk start budget, so a
- * fully capped 30-member dynamic pool reaches every one of them and an unbounded join would be a
- * ~1.2 KB header. The header says what stopped the request; it is not a roster.
- */
 export const HARD_CAP_HEADER = "x-llm-relay-capped";
-/**
- * This answer came from a deployment that is NOT free.
- *
- * Pools rank free capacity first but no longer exclude paid capacity, so a spent free lane is not
- * a dead end. That is only acceptable if spending is announced: an unflagged paid response is
- * indistinguishable from a free one, and the difference is money. Same reasoning as
- * `DEGRADED_HEADER` — automatic fallback is fine, silent fallback is not.
- *
- * Carries the deployment and how its cost was assessed, e.g.
- * `openrouter/anthropic/claude-sonnet-5 (paid, published-price)`.
- */
 export const PAID_HEADER = "x-llm-relay-paid";
-/** This response contains a tool call reconstructed from a recognized text dialect envelope. */
 export const TOOL_DIALECT_HEADER = "x-llm-relay-tool-dialect";
-/**
- * Per-response proof that a streamed dialect refusal was the RELAY's, not the upstream's.
- *
- * A WeakMap rather than a header or a body field, for the reason the signal exists at all: anything
- * on the wire can be echoed by a counterparty. The server hands this to `probeStreamForCommit`, and
- * a lane the relay never wrapped simply has no entry — so its bytes can never earn `local`
- * provenance. Same shape as `attachUpstreamMetadata`, and deliberately not merged into it: that
- * carries log METADATA about a finished response, this is live state for one in-flight stream.
- */
 const dialectRefusalSignals = new WeakMap();
 export function dialectRefusalSignalOf(response) {
     return dialectRefusalSignals.get(response);
 }
-/**
- * `tool_use` ids in this response were MINTED by the relay because the host reused ones the
- * conversation already carried — value `"<n> rewritten"`.
- *
- * Same maxim as `DEGRADED_HEADER`: an automatic fix is acceptable only because it is announced.
- * A count, never an id: the ids themselves are in the body the caller already has, and a header
- * is not the place to restate content.
- *
- * ⚠ Buffered responses only. On a stream the headers are written before the first
- * `content_block_start` exists, so a count there could only be a guess; the streaming pass
- * reports through `toolUseIdRewrites()` instead, which the server reads for its log record after
- * the stream drains. See `src/tool-use-ids.ts`.
- */
 export const TOOL_USE_IDS_HEADER = "x-llm-relay-tool-use-ids";
-/**
- * OUTBOUND tool-call ids were rewritten to this provider's stated id shape — value
- * `"<n> rewritten"`. Today that is only mistral's `^[a-zA-Z0-9]{9}$` (`compat.toolCallIds:
- * "strict9"`; see `src/openai-request.ts` for the 400 that states the rule).
- *
- * The request-direction sibling of `TOOL_USE_IDS_HEADER`, and the same maxim: an automatic fix is
- * acceptable only because it is announced, a count and never an id. Unlike the response-direction
- * mint the figure is final BEFORE the request is even sent, so it rides a streamed response's
- * headers too.
- */
 export const TOOL_CALL_IDS_HEADER = "x-llm-relay-tool-call-ids";
-/**
- * The provider's `Retry-After` in milliseconds, or null.
- *
- * Accepts both RFC 9110 forms — delta-seconds and an HTTP-date — because providers use both
- * (groq sends seconds, some CDNs in front of a provider send a date). A date in the past, a
- * negative delta or an unparseable value yields null rather than 0: "the provider said nothing
- * usable" and "the provider said retry immediately" call for different cooldowns, and treating
- * garbage as 0 would silently disable the backoff this exists to honour.
- */
 export function parseRetryAfterMs(value, now = Date.now()) {
     if (typeof value !== "string")
         return null;
     const raw = value.trim();
     if (raw.length === 0)
         return null;
-    // delta-seconds — integer per the RFC, but providers do emit fractions ("20.45").
     if (/^\d+(\.\d+)?$/.test(raw)) {
         const ms = Math.round(Number(raw) * 1000);
         return Number.isFinite(ms) && ms >= 0 ? ms : null;
@@ -235,45 +78,26 @@ export function parseRetryAfterMs(value, now = Date.now()) {
     const delta = at - now;
     return delta > 0 ? delta : null;
 }
-// Response provenance is private process state, not a wire header: callers can
-// read it for logging without accidentally forwarding it to the client.
 const upstreamResponseMetadata = new WeakMap();
 const postHeaderBodyFailures = new WeakMap();
 function attachPostHeaderBodyFailure(response, cause) {
     postHeaderBodyFailures.set(response, { kind: "post-header-body-failure", cause });
     return response;
 }
-/** Read adapter-private post-header body failure metadata. */
 export function postHeaderBodyFailure(response) {
     return postHeaderBodyFailures.get(response);
 }
-/** Raw model id stated by the upstream response, before any relay translation. */
 export function upstreamReportedModel(response) {
     return upstreamResponseMetadata.get(response)?.reportedModel;
 }
-/**
- * How many `tool_use` ids this response had minted, or `undefined` when none were.
- *
- * On a streamed response the figure is final only once the body has drained — read it where the
- * server reports end-of-stream facts, not before it writes headers.
- */
 export function toolUseIdRewrites(response) {
     const n = upstreamResponseMetadata.get(response)?.toolUseIdRewrites;
     return n !== undefined && n > 0 ? n : undefined;
 }
-/**
- * How many OUTBOUND tool-call ids this request had rewritten to the provider's stated shape, or
- * `undefined` when none were. Final at request-mapping time, so it is readable as soon as the
- * Response exists.
- */
 export function toolCallIdRewrites(response) {
     const n = upstreamResponseMetadata.get(response)?.toolCallIdRewrites;
     return n !== undefined && n > 0 ? n : undefined;
 }
-/**
- * How many replayed tool calls this request carried gemini's thought-signature sentinel on, or
- * `undefined` when none did. Final at request-mapping time, like `toolCallIdRewrites`.
- */
 export function thoughtSignatureSentinels(response) {
     const n = upstreamResponseMetadata.get(response)?.thoughtSignatureSentinels;
     return n !== undefined && n > 0 ? n : undefined;
@@ -287,22 +111,9 @@ const ANTHROPIC_STREAM_EVENT_FIELDS = new Map([
     ["message_start", "message"], ["content_block_start", "content_block"],
     ["content_block_delta", "delta"], ["message_delta", "delta"], ["error", "error"],
 ]);
-/**
- * Validate only the protocol structure the response mappers rely on. Optional identifiers,
- * model names and usage remain optional because several compatible providers legitimately omit
- * them; the required response discriminator must not be optional, or `{}` becomes a successful
- * empty assistant message.
- */
 function invalidEnvelopeReason(value, protocol, streamed) {
     if (!isRecord(value))
         return "expected a JSON object";
-    // An error envelope seen here under `streamed` is the FIRST event of a 2xx stream — preflight
-    // inspects nothing later, so this cannot fire mid-stream. Pre-commit, an in-band error frame
-    // is a dead turn, not a response: failing it makes the candidate loop walk on to a member
-    // that answers, where forwarding it spent the whole pool on one member's error inside a 200
-    // (adoption review §1.1). An error frame arriving AFTER a valid first event still streams
-    // through untouched — post-commit, honesty beats replay. The reason carries a bounded excerpt
-    // of the upstream's own message, same maxim as serving the last candidate's real error.
     if (streamed && isRecord(value.error)) {
         const message = typeof value.error.message === "string" ? value.error.message.slice(0, 200) : "";
         return message
@@ -373,7 +184,6 @@ function captureReportedModel(metadata, value, protocol, streamed) {
         metadata.reportedModel = envelope.model;
     }
 }
-/** Inspect the first data event before handing a provider stream to llm-bridge. */
 async function preflightResponseStream(body, protocol) {
     const reader = body.getReader();
     const chunks = [];
@@ -395,9 +205,6 @@ async function preflightResponseStream(body, protocol) {
     };
     const replay = () => {
         let prefixIndex = 0;
-        // The first valid event can be a ping. Keep observing the untouched raw
-        // stream while the consumer drains it so a later message_start/chunk can
-        // still supply the upstream's model before terminal logging.
         captureCompleteEvents();
         return { ok: true, metadata, body: new ReadableStream({
                 async pull(controller) {
@@ -465,7 +272,6 @@ async function preflightResponseStream(body, protocol) {
             captureReportedModel(metadata, JSON.parse(data), protocol, true);
         }
         catch {
-            // Preflight owns envelope validity; this observer owns provenance only.
         }
     };
     while (byteLength <= STREAM_PREFLIGHT_LIMIT) {
@@ -475,8 +281,6 @@ async function preflightResponseStream(body, protocol) {
         if (next.done) {
             buffered += decoder.decode();
             let finalReason = buffered.trim() ? inspectEvent(buffered) : undefined;
-            // A few compatible providers ignore `stream: true` and return one valid buffered
-            // completion. Preserve the old adapter behaviour for that genuine envelope.
             if (finalReason === undefined && buffered.trim()) {
                 try {
                     const parsed = JSON.parse(buffered);
@@ -484,7 +288,6 @@ async function preflightResponseStream(body, protocol) {
                     finalReason = invalidEnvelopeReason(parsed, protocol, false);
                 }
                 catch {
-                    // The SSE-specific reason below remains more useful.
                 }
             }
             if (finalReason === null)
@@ -512,14 +315,6 @@ async function preflightResponseStream(body, protocol) {
     }
     return fail("no response event within preflight limit");
 }
-/**
- * Fetch the resolved provider target and return an ANTHROPIC-shaped `Response`,
- * regardless of the backend's native wire format. For kind="anthropic" this is a
- * passthrough. For kind="openai" (NIM/vLLM/OpenRouter/Gemini) the request is
- * translated Anthropic→OpenAI and the response translated back (streaming via
- * llm-bridge's SSE re-encoder, non-streaming via a direct mapper) — so the rest
- * of the proxy (validate/repair) always sees Anthropic Messages.
- */
 export async function fetchBackend(attempt, args, fetchFn = fetch) {
     const invokeFetch = oneShotFetch(fetchFn, args.signal, args.onEgress);
     const target = attempt.target;
@@ -532,8 +327,6 @@ export async function fetchBackend(attempt, args, fetchFn = fetch) {
         const res = args.usage
             ? observeUsage(native, "anthropic-messages", args.usage, { streamed: nativeStreamed })
             : native;
-        // Preserve passthrough bytes, but do not preserve a successful status for a malformed
-        // Messages envelope. Inspecting a clone leaves the original buffered body byte-exact.
         const messagesPath = args.path.split("?", 1)[0] === "/v1/messages";
         if (!res.ok || !messagesPath)
             return res;
@@ -573,35 +366,19 @@ export async function fetchBackend(attempt, args, fetchFn = fetch) {
         captureReportedModel(metadata, body, "anthropic-messages", false);
         return attachUpstreamMetadata(res, metadata);
     }
-    // kind === "openai"
-    // Documents are transcoded to markdown BEFORE the request mapper, or refused: a `document`
-    // block has no OpenAI representation, and the pre-mapper behaviour put its whole base64
-    // payload into the prompt. The pre-pass walks the top level of each turn AND the content of
-    // each `tool_result`, so a document a tool returned is converted rather than refused.
     let reqJson = args.reqJson;
     try {
         reqJson = await transcodeDocuments(reqJson);
     }
     catch (e) {
-        // Local, both of them: the provider was never asked. Charging these to the provider's
-        // failure budget fails over to a second provider that would refuse the same document.
         if (e instanceof DocumentError)
             return anthropicError(400, `llm-relay: ${e.message}`, "local");
         return anthropicError(502, `document conversion failed: ${e.message}`, "local");
     }
     let openaiBody;
-    // Outbound id rewrites, from the RESOLVED compat mode on the target — the mapper is handed a
-    // decision, never a provider name to re-derive one from. `preserve` (everyone but mistral)
-    // leaves this 0 and the outbound bytes untouched.
     let toolCallIdsRewritten = 0;
-    // The sibling pass, resolved the same way: `none` (everyone but Google's Generative Language
-    // API) leaves this 0 and adds nothing to the body.
     let sentinelsStamped = 0;
     try {
-        // The REQUEST direction is relay-owned (`openai-request.ts`); only the RESPONSE direction is
-        // still llm-bridge's. llm-bridge's `universalToOpenAI` has no case for a tool_call/tool_result
-        // block, so it stringified its own IR envelope into the outbound prompt — see
-        // docs/tool-call-dialect-leak.md §"Second mechanism".
         openaiBody = anthropicRequestToOpenAi(reqJson, {
             model: target.model,
             stream: args.wantsStream,
@@ -612,15 +389,10 @@ export async function fetchBackend(attempt, args, fetchFn = fetch) {
         });
     }
     catch (e) {
-        // A block we will not put on the wire is the caller's request being unrepresentable, not a
-        // provider failure — same clean local 400 as an unconvertible document.
         if (e instanceof RequestMappingError)
             return anthropicError(400, `llm-relay: ${e.message}`, "local");
         return anthropicError(502, `request translation failed: ${e.message}`, "local");
     }
-    // OpenAI-compatible backends omit usage from streamed responses unless asked. Without
-    // this the translated `message_delta` reports output_tokens: 0 and anything metering
-    // off the stream undercounts. Not universally supported — see the 400 retry below.
     if (args.wantsStream)
         openaiBody.stream_options = { include_usage: true };
     const post = (body) => invokeFetch(target.base + "/chat/completions", {
@@ -630,8 +402,6 @@ export async function fetchBackend(attempt, args, fetchFn = fetch) {
         signal: args.signal,
     });
     let res = await post(openaiBody);
-    // A backend that doesn't know `stream_options` rejects the whole request (400/422).
-    // Drop the hint and retry once rather than failing a request over telemetry.
     if (!res.ok && openaiBody.stream_options && (res.status === 400 || res.status === 422)) {
         await res.body?.cancel().catch(() => { });
         const { stream_options: _omit, ...withoutUsage } = openaiBody;
@@ -649,16 +419,9 @@ export async function fetchBackend(attempt, args, fetchFn = fetch) {
         catch (cause) {
             return attachPostHeaderBodyFailure(res, cause);
         }
-        // A 404 here is nearly always the model id, not the route — and a provider's
-        // /models catalog is not proof: several ids NIM lists return 404 from
-        // /chat/completions. Say so, or this reads as a proxy bug.
         const hint = res.status === 404
             ? ` — model "${target.model}" is not served by provider "${target.provider}" (a model can be listed in /models and still 404 here)`
             : "";
-        // The provider really answered with this status — the body is reworded, the origin is not.
-        // `Retry-After` is carried onto the synthesized error: this response is a NEW Response, so
-        // without this the one header stating when the provider will serve again was destroyed here,
-        // and neither the breaker's cooldown nor the client's backoff could ever honour it.
         return anthropicError(res.status, `openai backend HTTP ${res.status}${hint}: ${body.slice(0, 300)}`, "upstream", {
             ...retryAfterHeader(res.headers),
         });
@@ -677,28 +440,12 @@ export async function fetchBackend(attempt, args, fetchFn = fetch) {
         }
         try {
             const anthStream = handleUniversalStreamRequest(preflight.body, "openai", "anthropic");
-            // Strip a complete message-opening think block BEFORE dialect scanning. Otherwise the
-            // preamble can hide a tool envelope from recovery. Native Anthropic streams never enter
-            // this branch, and direct OpenAI Chat passthrough is handled on the other front.
             const strippedStream = stripThinkTagsInStream(anthStream);
-            // Recover a tool call this host returned as raw dialect TEXT. Gated on the request actually
-            // declaring tools: with none declared there is no call to recover, and wrapping the stream
-            // would add holdback latency for nothing.
             const schemas = toolSchemaMap(args.reqJson);
             const refusalSignal = dialectRefusalSignal();
             const recovered = schemas.size > 0
                 ? recoverDialectInStream(strippedStream, schemas, args.isDestructive, refusalSignal)
                 : strippedStream;
-            // AFTER recovery, so a call the relay reconstructed is covered too, and BEFORE anything that
-            // watches for the first `tool_use` — validation and repair must see the ids the client will.
-            // The taken-set is a thunk: a response with no tool call never walks the conversation.
-            // ⚠ Deliberately NOT gated on `schemas.size > 0` like the line above, and the asymmetry is
-            // the point: recovery needs a schema to parse a call out of text, uniqueness needs only an
-            // id to exist. A host may emit `tool_calls` a request never declared — Claude Code's compact
-            // turn declares none while the conversation it summarizes is full of tool_use ids — and that
-            // is exactly the turn the normalizer would empty to `[Tool use interrupted]`. The framing
-            // holdback is already paid by `stripThinkTagsInStream` above, and an event with no
-            // `tool_use` substring costs one scan, so the gate would buy little and lose that case.
             const metadata = preflight.metadata;
             if (toolCallIdsRewritten > 0)
                 metadata.toolCallIdRewrites = toolCallIdsRewritten;
@@ -709,8 +456,6 @@ export async function fetchBackend(attempt, args, fetchFn = fetch) {
                 status: res.status,
                 headers: {
                     "content-type": "text/event-stream",
-                    // Unlike the response-direction mint, this count is a REQUEST fact and was final
-                    // before a byte was sent — so a stream can announce it honestly.
                     ...(toolCallIdsRewritten > 0 ? { [TOOL_CALL_IDS_HEADER]: `${toolCallIdsRewritten} rewritten` } : {}),
                 },
             }), metadata);
@@ -745,31 +490,16 @@ export async function fetchBackend(attempt, args, fetchFn = fetch) {
     }
     catch (e) {
         if (e instanceof DialectUnparseableError) {
-            // NOT a mapper defect — the translation is fine and the HOST returned an unusable body. It
-            // counts against this deployment so the breaker sees it and the pool fails over to a host
-            // that parses its models' dialect. 502 is retriable, which is what drives the walk.
             return anthropicError(502, `llm-relay: ${e.message}`, "upstream", {}, "tool_dialect_unparseable");
         }
         if (e instanceof DialectDestructiveError) {
-            // "local" is the load-bearing part: it makes `localFailure` true in the walk, so the request
-            // is NOT rerolled onto another candidate and the deployment is not blamed. A refusal is a
-            // config decision, not a health signal — the same line the hard cap draws.
             return anthropicError(502, `llm-relay: ${e.message}`, "local", { [TOOL_DIALECT_HEADER]: "refused-destructive" }, DIALECT_REFUSED_DESTRUCTIVE_CODE);
         }
-        // The provider returned a valid source envelope, so a failure after this point belongs to
-        // the relay mapper rather than the provider or its failure budget.
         return anthropicError(502, `llm-relay: response translation failed: ${e.message}`, "local", {}, "relay_mapper_defect");
     }
-    // A host that reuses a tool-call id across turns makes Claude Code drop the call while building
-    // its next request; mint a fresh one where it collides. The pass runs on the TRANSLATED message,
-    // so a dialect-recovered call is covered too and keeps its `tu_recovered_*` id unless that id is
-    // itself already in the conversation. See `src/tool-use-ids.ts`.
     const mintedIds = mintUniqueToolUseIds(anthropicJson, args.reqJson);
     if (mintedIds.message)
         anthropicJson = mintedIds.message;
-    // Announce a recovered call for the same reason `x-llm-relay-degraded` is announced: a response
-    // whose tool call the RELAY reconstructed is not the same as one that arrived correct, and an
-    // unflagged reconstruction is indistinguishable from a host that worked.
     const recoveredDialect = recoveredDialectOf(anthropicJson);
     const response = new Response(JSON.stringify(anthropicJson), {
         status: 200,
@@ -790,18 +520,10 @@ export async function fetchBackend(attempt, args, fetchFn = fetch) {
         metadata.toolUseIdRewrites = mintedIds.rewritten;
     if (toolCallIdsRewritten > 0)
         metadata.toolCallIdRewrites = toolCallIdsRewritten;
-    // No header for this one — see `UpstreamResponseMetadata.thoughtSignatureSentinels`.
     if (sentinelsStamped > 0)
         metadata.thoughtSignatureSentinels = sentinelsStamped;
     return attachUpstreamMetadata(response, metadata);
 }
-/**
- * Give a translated message's `tool_use` blocks ids the conversation has not already used.
- *
- * Lazy on purpose: a response with no `tool_use` block never walks the request's messages, so the
- * ordinary text completion — the overwhelming majority of traffic — pays one array scan. `message`
- * is null when nothing changed, so an untouched response is never re-built.
- */
 function mintUniqueToolUseIds(message, reqJson) {
     const content = message.content;
     if (!Array.isArray(content) || !content.some((b) => isRecord(b) && b.type === "tool_use")) {
@@ -812,31 +534,18 @@ function mintUniqueToolUseIds(message, reqJson) {
         return { message: null, rewritten: 0 };
     return { message: { ...message, content: out.content }, rewritten: out.rewritten };
 }
-/** Did this translated message carry a tool call the relay reconstructed from text? */
 function recoveredDialectOf(message) {
     const content = message.content ?? [];
     return content.some((b) => b.type === "tool_use" && typeof b.id === "string" && b.id.startsWith("tu_recovered_"))
         ? "recovered"
         : null;
 }
-/**
- * Map a non-streaming OpenAI chat completion into an Anthropic message.
- *
- * `schemas` enables recovery of a tool call the HOST failed to parse: some free hosts return the
- * model's native tool-call dialect as assistant TEXT instead of populating `tool_calls`, which
- * without this reaches the client as markup it treats as a final answer (see
- * docs/tool-call-dialect-leak.md). Omitting it keeps the pure translation behaviour.
- */
 export function openAiResponseToAnthropic(j, model, schemas, isDestructive) {
     const choice = j.choices?.[0] ?? {};
     const msg = choice.message ?? {};
     const content = [];
     let toolCalls = msg.tool_calls ?? [];
-    // This mapper is the translated OpenAI→Anthropic seam. Strip first so an opening think block
-    // cannot conceal a following dialect envelope from the recovery pass below.
     const messageText = typeof msg.content === "string" ? stripOpeningThinkTag(msg.content) : null;
-    // Recover ONLY when the host parsed nothing. A host that populated `tool_calls` has already
-    // spoken; second-guessing it here would be inference, not translation.
     let recovered = [];
     if (toolCalls.length === 0 && messageText !== null && messageText.length > 0) {
         const out = recoverToolCalls(messageText, schemas ?? new Map(), isDestructive);
@@ -846,15 +555,9 @@ export function openAiResponseToAnthropic(j, model, schemas, isDestructive) {
                 content.push({ type: "text", text: out.text });
         }
         else if (out.status === "refused-destructive") {
-            // The relay reconstructed a destructive call out of prose. Refuse it whole rather than
-            // commit it — "refused, never fabricated". Terminal, not retriable: see the error class.
             throw new DialectDestructiveError(out.dialect, out.refused);
         }
         else if (out.status === "detected") {
-            // Framing present, nothing parseable — a truncated or unmodelled envelope. Fail clean so
-            // failover reaches a host that parses, exactly as repair fails clean on an unrepairable
-            // call. Returning the fragment would hand the client a "final answer" that is really the
-            // tail of a broken tool call, which is the misdiagnosis this whole path exists to prevent.
             throw new DialectUnparseableError(out.dialect);
         }
         else {
@@ -902,7 +605,6 @@ export function openAiResponseToAnthropic(j, model, schemas, isDestructive) {
         ...(usage ? { usage } : {}),
     };
 }
-/** The upstream's `Retry-After`, as a header object to spread, or `{}` when it sent none. */
 function retryAfterHeader(hh) {
     const v = hh.get("retry-after");
     return v ? { "retry-after": v } : {};
@@ -919,11 +621,6 @@ function openaiError(status, message, origin, type = "invalid_request_error", ex
         headers: { "content-type": "application/json", [ERROR_ORIGIN_HEADER]: origin, ...extra },
     });
 }
-/**
- * Remove the usage-only Chat SSE event we requested on the caller's behalf.  This sits after
- * the observer: accounting sees the native bytes immediately, while the client sees its
- * original stream contract.  It deliberately matches only an empty-choices event with usage.
- */
 function suppressRelayAddedOpenAiUsageFrames(body) {
     let pending = new Uint8Array(0);
     const append = (left, right) => {
@@ -944,7 +641,6 @@ function suppressRelayAddedOpenAiUsageFrames(body) {
     const isUsageOnly = (frame) => {
         let event;
         try {
-            // Fatal decoding means opaque/noncanonical bytes pass through untouched.
             event = new TextDecoder("utf-8", { fatal: true }).decode(frame);
         }
         catch {
@@ -976,8 +672,6 @@ function suppressRelayAddedOpenAiUsageFrames(body) {
             if (!isUsageOnly(frame))
                 controller.enqueue(frame);
         }
-        // Do not let a malformed provider frame become unbounded buffering. Retained bytes are
-        // always original slices, never decoder/re-encoder output.
         if ((final || pending.byteLength > 16 * 1024) && pending.byteLength > 0) {
             controller.enqueue(pending);
             pending = new Uint8Array(0);
@@ -1001,13 +695,6 @@ function nativeResponseIsStreamed(response, wantsStream) {
         return false;
     return wantsStream;
 }
-/**
- * Turn an Anthropic Message response into the response envelope expected by an OpenAI client.
- *
- * This is deliberately separate from llm-bridge's request translation. Provider request bodies
- * and provider response bodies are different contracts, and treating a response as a request
- * loses tool calls, stop reasons and usage on the way back to the caller.
- */
 export function anthropicMessageToOpenAi(body, protocol, fallbackModel = "") {
     const content = Array.isArray(body.content) ? body.content : [];
     const textParts = [];
@@ -1090,27 +777,9 @@ export function anthropicMessageToOpenAi(body, protocol, fallbackModel = "") {
         out.usage = withOpenAiTotal(usage);
     return out;
 }
-/**
- * A cache figure this relay is willing to repeat downstream: a finite, non-negative number.
- * Negative or non-finite is malformed host output, not a measurement, so it is treated exactly
- * like an absent field — propagating it would shrink a prompt total or publish a negative
- * `cached_tokens`, i.e. manufacture a figure nobody stated.
- */
 function measuredCacheTokens(v) {
     return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : undefined;
 }
-/**
- * Anthropic→OpenAI prompt-side mapping (used when an anthropic-kind backend answers a
- * Chat/Responses front-door request).
- *
- * The two protocols disagree on what "prompt tokens" means: OpenAI's `prompt_tokens` INCLUDES
- * the cached subset; Anthropic's `input_tokens` EXCLUDES cache reads and cache writes, which
- * ride in their own fields. Mapping input_tokens straight across therefore UNDER-STATES the
- * prompt by exactly the cache traffic, so it is summed back here. `cache_read_input_tokens`
- * additionally becomes `prompt_tokens_details.cached_tokens` — the field an OpenAI client
- * reads to know how much of the prompt was served from cache — and each output field is
- * emitted only when its source was actually reported, never zero-filled.
- */
 function openAiUsage(raw) {
     if (typeof raw !== "object" || raw === null)
         return null;
@@ -1119,39 +788,20 @@ function openAiUsage(raw) {
     const cacheCreation = measuredCacheTokens(usage.cache_creation_input_tokens);
     const cacheSum = (cacheRead ?? 0) + (cacheCreation ?? 0);
     const input = typeof usage.input_tokens === "number" ? usage.input_tokens : undefined;
-    // A usage object with no numeric fields is not a measurement. Keep the relay's unknown-vs-zero
-    // convention instead of manufacturing a cost report for an upstream that omitted usage.
     if (input === undefined && typeof usage.output_tokens !== "number")
         return null;
     const out = {
         ...(input !== undefined ? { prompt_tokens: input + cacheSum } : {}),
         ...(typeof usage.output_tokens === "number" ? { completion_tokens: usage.output_tokens } : {}),
     };
-    // The details object only when a cache read was actually reported — `{cached_tokens: 0}`
-    // would claim the backend stated something about caching that it did not.
     if (cacheRead !== undefined) {
         out.prompt_tokens_details = { cached_tokens: cacheRead };
     }
     return out;
 }
-/**
- * OpenAI→Anthropic prompt-side mapping (the translated seam of `openAiResponseToAnthropic`).
- *
- * Mirror of `openAiUsage`: subtract the cached subset back OUT of `prompt_tokens`, because
- * Anthropic's `input_tokens` must exclude it or every downstream reader of the Anthropic shape
- * (validator, repair envelope re-attachment, SSE re-emission) sees a double-counted figure.
- * Only mapped when the host actually reported `prompt_tokens_details.cached_tokens`, as a
- * finite non-negative number; anything else (`cached_tokens > prompt_tokens`, negative,
- * non-finite) is malformed host output rather than evidence, so the prompt figure passes
- * through unchanged and the cache field is dropped — an unmeasurable split is not evidence
- * either way, and inventing one would be worse than none.
- */
 function openAiPromptUsageToAnthropic(rawUsage) {
     if (typeof rawUsage.prompt_tokens !== "number")
         return {};
-    // Same trust rule as `measuredCacheTokens`, applied to the split direction: a negative or
-    // non-finite `cached_tokens` would make `input_tokens` EXCEED the prompt the host stated, so
-    // it is malformed exactly like `cached > prompt_tokens`.
     const cached = (() => {
         const details = rawUsage.prompt_tokens_details;
         if (typeof details !== "object" || details === null)
@@ -1181,7 +831,6 @@ function openAiFinishReason(stopReason, hasToolCalls) {
         return "content_filter";
     return "stop";
 }
-/** Map an Anthropic error envelope to a client-readable OpenAI error envelope. */
 function anthropicErrorToOpenAi(body, status) {
     try {
         const parsed = JSON.parse(body);
@@ -1198,30 +847,9 @@ function anthropicErrorToOpenAi(body, status) {
         }
     }
     catch {
-        // Fall through to the normalizer, which preserves a useful bounded text message.
     }
     return normalizeOpenAiErrorBody(body, status) ?? body;
 }
-/**
- * Coerce an upstream error body into the OpenAI error envelope — WITHOUT rewriting one that
- * already conforms.
- *
- * The OpenAI front promises "OpenAI in, OpenAI out", but on the error path it returned whatever
- * shape the provider chose. Gemini wraps its error in a JSON ARRAY (`[{"error":{…}}]`); a client
- * reading `response.choices[0]` gets `undefined` from that and reports a malformed completion,
- * so a plain 429 surfaces as "the model returned garbage" — which is exactly how a rate limit
- * cost two days of debugging on the caller's side.
- *
- * Rules, in order:
- *   - already `{error:{…}}`     → returned BYTE-EXACT. A conforming provider's message, code and
- *                                 type are its own to state, and rewriting them would lose detail.
- *   - `[{error:{…}}, …]`        → unwrapped to the element. Same fields, now at the top level.
- *   - anything else (HTML, text,
- *     a bare string, empty)     → wrapped, with the original preserved as the message.
- *
- * Returns null when the body is already conforming, so the caller can stream the original bytes
- * rather than re-serialize them.
- */
 export function normalizeOpenAiErrorBody(body, status) {
     let parsed;
     try {
@@ -1233,7 +861,7 @@ export function normalizeOpenAiErrorBody(body, status) {
     }
     const hasError = (v) => typeof v === "object" && v !== null && typeof v.error === "object" && v.error !== null;
     if (hasError(parsed))
-        return null; // conforms — do not touch it
+        return null;
     if (Array.isArray(parsed)) {
         const wrapped = parsed.find(hasError);
         if (wrapped)
@@ -1254,23 +882,11 @@ function buildTargetHeaders(attempt) {
         ...buildAuthHeaders(credential.value, target.authHeader),
     };
 }
-/**
- * OpenAI-compatible FRONT: an OpenAI Chat Completions or Responses request comes in, its
- * `model` has already been resolved to a provider target by namespace/tier routing.
- *
- * The common case remains a byte-transparent OpenAI→OpenAI Chat Completions proxy. The other
- * combinations use the same Anthropic-shaped internal seam as the Messages front:
- * OpenAI request → Anthropic request → resolved backend → Anthropic response → OpenAI response.
- * That makes an Anthropic passthrough usable from Codex and OpenAI-native IDEs without changing
- * the existing Claude client path.
- */
 export async function fetchOpenAiFront(attempt, args, fetchFn = fetch) {
     const invokeFetch = oneShotFetch(fetchFn, args.signal, args.onEgress);
     const target = attempt.target;
     const protocol = args.protocol ?? "chat";
     const base = (args.reqJson ?? {});
-    // Preserve the existing direct path for the protocol/backend pair that already speaks the
-    // same wire format. It keeps provider-specific OpenAI fields byte-for-byte intact.
     if (target.kind === "openai" && protocol === "chat") {
         const schemas = toolSchemaMap(base);
         const callerRequestedUsage = isRecord(base.stream_options) && base.stream_options.include_usage === true;
@@ -1290,8 +906,6 @@ export async function fetchOpenAiFront(attempt, args, fetchFn = fetch) {
             signal: args.signal,
         });
         let res = await post(body);
-        // Only a relay-added compatibility hint is safe to remove. A caller-provided option is
-        // their request, not relay policy.
         if (!res.ok && relayAddedUsage && (res.status === 400 || res.status === 422)) {
             await res.body?.cancel().catch(() => { });
             res = await post(originalBody);
@@ -1347,9 +961,6 @@ export async function fetchOpenAiFront(attempt, args, fetchFn = fetch) {
             return openaiError(502, `llm-relay: ${error instanceof Error ? error.message : String(error)}`, "upstream", "tool_call_recovery_failed");
         }
         if (recovery.status === "refused-destructive") {
-            // "local" keeps this out of the failover walk and off the deployment's failure budget: the
-            // envelope parsed fine, the relay refused to commit what it reconstructed. Config, not
-            // health — the same line the hard cap draws.
             return openaiError(502, `llm-relay: refused a ${recovery.dialect} tool call recovered from text because it names a destructive tool: ${describeRefused(recovery.refused)}`, "local", DIALECT_REFUSED_DESTRUCTIVE_CODE, { [TOOL_DIALECT_HEADER]: "refused-destructive" });
         }
         if (recovery.status === "detected") {
@@ -1370,12 +981,6 @@ export async function fetchOpenAiFront(attempt, args, fetchFn = fetch) {
     }
     let anthropicBody;
     try {
-        // The RESPONSES request direction is relay-owned (`responses-request.ts`), for the same
-        // reason the Anthropic→OpenAI direction is: llm-bridge's `openaiResponsesToUniversal` models
-        // only `function_call_output`, so an assistant `function_call` was flattened into an empty
-        // user turn and an assistant `output_text` reached the backend as a JSON string. The CHAT
-        // request direction stays llm-bridge's (`openaiToUniversal` does handle `tool_calls` and
-        // `role:"tool"`), as does every response/stream direction.
         anthropicBody = protocol === "responses"
             ? openaiResponsesRequestToAnthropic(base)
             : translateBetweenProviders("openai", "anthropic", base);
@@ -1384,8 +989,6 @@ export async function fetchOpenAiFront(attempt, args, fetchFn = fetch) {
         anthropicBody.stream = args.wantsStream;
     }
     catch (e) {
-        // A shape we will not put on the wire is the caller's request being unrepresentable, not a
-        // provider failure — the same clean local 400 the Messages front raises.
         if (e instanceof RequestMappingError)
             return openaiError(400, `llm-relay: ${e.message}`, "local");
         return openaiError(400, `llm-relay: request translation failed: ${e.message}`, "local");
@@ -1414,14 +1017,7 @@ export async function fetchOpenAiFront(attempt, args, fetchFn = fetch) {
         catch (cause) {
             return attachPostHeaderBodyFailure(backendRes, cause);
         }
-        // Absent or unreadable ⇒ `"upstream"`, deliberately: the provider DID answer, and the relay
-        // marks its own errors. `errorOrigin` is the one place the declared members are enumerated,
-        // and it is now derived from the type — so a third member cannot be silently rejected here.
         const origin = errorOrigin(backendRes) ?? "upstream";
-        // Same rule as the two id-rewrite counters below: rebuilding the response must not swallow the
-        // announcement of a decision the relay made one Response ago. A dialect-rescue destructive
-        // refusal arrives here as a 502 from `fetchBackend` carrying `refused-destructive`, and a
-        // Responses/Messages-front client is entitled to the same marker the Messages front gets.
         const dialect = backendRes.headers.get(TOOL_DIALECT_HEADER);
         const headers = {
             "content-type": "application/json",
@@ -1447,8 +1043,6 @@ export async function fetchOpenAiFront(attempt, args, fetchFn = fetch) {
         const targetProtocol = protocol === "responses" ? "openai-responses" : "openai";
         try {
             const output = handleUniversalStreamRequest(preflight.body, "anthropic", targetProtocol);
-            // Same rule as the buffered rebuild below: rebuilding the response must not swallow the
-            // announcement of a fix the relay applied one Response ago.
             const rewritten = backendRes.headers.get(TOOL_CALL_IDS_HEADER);
             const response = new Response(output, {
                 status: backendRes.status,
@@ -1457,10 +1051,6 @@ export async function fetchOpenAiFront(attempt, args, fetchFn = fetch) {
                     ...(rewritten ? { [TOOL_CALL_IDS_HEADER]: rewritten } : {}),
                 },
             });
-            // Carry the refusal SIGNAL across the rebuild for the same reason as the header above: this
-            // Response is the one the server probes, and the object it must consult was registered
-            // against the inner Response one hop ago. The signal is the same live object, so a refusal
-            // the wrapper marks after this line is still visible.
             const innerRefusal = dialectRefusalSignals.get(backendRes);
             if (innerRefusal)
                 dialectRefusalSignals.set(response, innerRefusal);
@@ -1488,12 +1078,7 @@ export async function fetchOpenAiFront(attempt, args, fetchFn = fetch) {
             : `llm-relay: invalid Anthropic upstream envelope: ${invalidReason}`, generated ? "local" : "upstream", generated ? "relay_mapper_defect" : "invalid_upstream_envelope", retryAfterHeader(backendRes.headers));
     }
     try {
-        // This front's TRANSLATED lane runs through `fetchBackend`, so an `openai`-kind target reached
-        // from `/v1/responses` inherits the id mint. Rebuilding the body must not swallow the
-        // announcement — an automatic fix is acceptable only because it is announced, and the count
-        // is as true here as it was one Response ago.
         const minted = backendRes.headers.get(TOOL_USE_IDS_HEADER);
-        // …and the outbound-id rewrite the same request mapper applied on the way IN.
         const rewritten = backendRes.headers.get(TOOL_CALL_IDS_HEADER);
         const response = new Response(JSON.stringify(anthropicMessageToOpenAi(body, protocol, target.model ?? String(base.model ?? ""))), {
             status: backendRes.status,