@sema-agent/core 7.48.0 → 7.49.1

package/dist/brain/provider-dialect.js

@@ -0,0 +1,186 @@
+import { BrainError, carriedProviderWord, providerErrorWord, statedEnvelope } from "./errors.js";
+import { readUnifiedResetEpochMs } from "./retry.js";
+export const PROVIDER_CONDITIONS = Object.freeze(["quota_exhausted", "throttled", "overloaded", "stop_other", "unknown"]);
+export const PROVIDER_CONDITION_SOURCES = Object.freeze(["unified_header", "provider_code", "status"]);
+export const PROVIDER_CONDITION_TRAITS = {
+    quota_exhausted: { retryable: false, inBandCode: "rate_limit" },
+    throttled: { retryable: true, inBandCode: "rate_limit" },
+    overloaded: { retryable: true, inBandCode: "server" },
+    stop_other: { retryable: false, inBandCode: "invalid_request" },
+    unknown: { retryable: true, inBandCode: "server" },
+};
+Object.freeze(PROVIDER_CONDITION_TRAITS);
+export function isProviderCondition(v) {
+    return typeof v === "string" && PROVIDER_CONDITIONS.includes(v);
+}
+export function isProviderConditionSource(v) {
+    return typeof v === "string" && PROVIDER_CONDITION_SOURCES.includes(v);
+}
+export const INPUT_TOO_LONG_ANCHORED_RE = /^(?:prompt is too long|prompt too long|input is too long|this model's maximum context length is |context.{0,3}length|context window (?:limit|exceeded)|reached its context window|too many tokens|maximum context|input length and `max_tokens` exceed context limit|(?:the )?request(?: \([^)]{0,40}\))? exceeds|(?:the )?input token count(?: \([^)]{0,40}\))? exceeds|requested tokens(?: \([^)]{0,40}\))? exceed|your input exceeds|(?:the )?number of tokens in the request exceeds|range of input length should be|input token length too long|invalid request: your request exceeded model token limit|total message size)/i;
+export function startsWithInputTooLongAnchor(diagnostic) {
+    return INPUT_TOO_LONG_ANCHORED_RE.test(diagnostic.trimStart());
+}
+const INPUT_TOO_LONG_STATUSES = new Set([400, 413, 422]);
+const OPENAI_CHAT = "openai-completions";
+const OPENAI_RESPONSES = "openai-responses";
+const ANTHROPIC = "anthropic-messages";
+const OPENAI_SPEND_CODES = ["credit_balance_exhausted", "organization_spend_limit_exceeded", "project_spend_limit_exceeded", "organization_usage_limit_exceeded"];
+export const PROVIDER_DIALECTS = Object.freeze([
+    {
+        name: "deepseek",
+        key: { wires: [OPENAI_CHAT, ANTHROPIC], hosts: ["api.deepseek.com"] },
+        failures: [
+            { status: [429], condition: "throttled" },
+            { status: [503], condition: "overloaded" },
+        ],
+    },
+    {
+        name: "dashscope",
+        key: { wires: [OPENAI_CHAT], hosts: ["dashscope.aliyuncs.com", "dashscope-intl.aliyuncs.com"] },
+        failures: [
+            { status: [429], word: ["limit_requests", "limit_burst_rate", "Throttling.Concurrency", "Throttling"], condition: "throttled" },
+            { status: [429], word: ["insufficient_quota", "Throttling.AllocationQuota"], sentence: /^free allocated quota exceeded/i, condition: "quota_exhausted" },
+            { status: [429], word: ["insufficient_quota", "Throttling.AllocationQuota"], condition: "throttled" },
+            { status: [429], word: ["Throttling.ServiceOverloaded", "ResourceExhausted"], condition: "overloaded" },
+            { status: [429], word: ["PrepaidBillOverdue", "PostpaidBillOverdue", "BudgetLimitExceeded", "CommodityNotPurchased"], condition: "quota_exhausted" },
+            { status: [429], condition: "throttled" },
+            { status: [400], word: ["Arrearage"], condition: "quota_exhausted" },
+            { status: [403], word: ["AllocationQuota.FreeTierOnly"], condition: "quota_exhausted" },
+            { status: [400], word: ["DataInspectionFailed"], condition: "stop_other" },
+            { status: [500, 503], word: ["InternalError", "RequestTimeOut", "ModelUnavailable"], condition: "overloaded" },
+        ],
+    },
+    {
+        name: "moonshot",
+        key: { wires: [OPENAI_CHAT], hosts: ["api.moonshot.cn", "api.moonshot.ai"] },
+        failures: [
+            { status: [429], word: ["exceeded_current_quota_error"], condition: "quota_exhausted" },
+            { status: [429], word: ["rate_limit_reached_error"], sentence: /\bTPD\b|每日/i, condition: "quota_exhausted" },
+            { status: [429], word: ["rate_limit_reached_error"], condition: "throttled" },
+            { status: [429], word: ["engine_overloaded_error"], condition: "overloaded" },
+            { status: [429], condition: "throttled" },
+            { status: [503], word: ["server_unavailable"], condition: "overloaded" },
+            { status: [403], word: ["permission_denied_error"], condition: "stop_other" },
+            { status: [400], word: ["content_filter"], condition: "stop_other" },
+        ],
+    },
+    {
+        name: "kimi-code",
+        key: { wires: [ANTHROPIC, OPENAI_CHAT], hosts: ["api.kimi.com"], path: "/coding" },
+        failures: [
+            { status: [429], sentence: /^the engine is currently overloaded/i, condition: "overloaded" },
+            { status: [429], condition: "throttled" },
+            { status: [403], sentence: /^you(?:'|’)ve reached your\b.*\busage limit/i, condition: "quota_exhausted" },
+        ],
+    },
+    {
+        name: "glm",
+        key: { wires: [OPENAI_CHAT, ANTHROPIC], hosts: ["open.bigmodel.cn", "api.z.ai"] },
+        failures: [
+            { status: [429], word: ["1302"], condition: "throttled" },
+            { status: [429], word: ["1305"], condition: "overloaded" },
+            {
+                status: [429],
+                word: ["1113", "1308", "1309", "1310", "1314", "1315", "1316", "1317", "1318", "1319", "1320", "1321"],
+                condition: "quota_exhausted",
+            },
+            { status: [429], word: ["1311", "1313"], condition: "stop_other" },
+            { status: [400], word: ["1261"], condition: "stop_other", inputTooLong: true },
+        ],
+    },
+    {
+        name: "openai",
+        key: { wires: [OPENAI_CHAT, OPENAI_RESPONSES], hosts: ["api.openai.com"] },
+        failures: [
+            { status: [429], word: [...OPENAI_SPEND_CODES, "insufficient_quota"], condition: "quota_exhausted" },
+            { status: [429], word: ["slow_down", "rate_limit_exceeded", "rate_limit_error"], condition: "throttled" },
+            { status: [429], condition: "throttled" },
+            { status: [503], word: ["server_is_overloaded"], condition: "overloaded" },
+        ],
+    },
+]);
+export const GENERIC_FAILURES = Object.freeze([
+    { status: [402], condition: "quota_exhausted" },
+    { status: [429], word: [...OPENAI_SPEND_CODES], condition: "quota_exhausted" },
+    { status: [429], word: ["insufficient_quota"], condition: "unknown" },
+    { status: [400, 422], word: ["context_length_exceeded"], condition: "stop_other", inputTooLong: true },
+    { status: [400, 422], sentence: INPUT_TOO_LONG_ANCHORED_RE, condition: "stop_other", inputTooLong: true },
+    { status: [413], condition: "stop_other", inputTooLong: true },
+]);
+export function isTransientStatus(status) {
+    return status >= 500 || status === 408 || status === 409;
+}
+export function resolveProviderDialect(url, wire) {
+    if (!URL.canParse(url))
+        return undefined;
+    const u = new URL(url);
+    const host = u.hostname.toLowerCase().replace(/\.$/, "");
+    const path = u.pathname;
+    return PROVIDER_DIALECTS.find((d) => d.key.wires.includes(wire) &&
+        d.key.hosts.some((h) => host === h || host.endsWith(`.${h}`)) &&
+        (d.key.path === undefined || path === d.key.path || path.startsWith(`${d.key.path}/`)));
+}
+function statementOf(err) {
+    if (err === undefined)
+        return undefined;
+    const word = providerErrorWord(err);
+    const sentence = typeof err.message === "string" ? err.message.trimStart() : undefined;
+    return { ...(word !== undefined ? { word } : {}), ...(sentence !== undefined ? { sentence } : {}) };
+}
+function bestRow(rows, status, stated) {
+    let best;
+    let bestRank = -1;
+    for (const row of rows) {
+        if (status === undefined ? row.word === undefined && row.sentence === undefined : row.status !== undefined && !row.status.includes(status))
+            continue;
+        if (row.word !== undefined && (stated?.word === undefined || !row.word.includes(stated.word)))
+            continue;
+        if (row.sentence !== undefined && (stated?.sentence === undefined || !row.sentence.test(stated.sentence)))
+            continue;
+        const rank = (row.word !== undefined ? 2 : 0) + (row.sentence !== undefined ? 1 : 0);
+        if (rank > bestRank) {
+            best = row;
+            bestRank = rank;
+        }
+    }
+    return best;
+}
+function verdictOf(dialect, status, stated, enveloped) {
+    const row = bestRow(dialect?.failures ?? [], status, stated) ?? bestRow(GENERIC_FAILURES, status, stated);
+    const condition = row?.condition ?? (status === undefined || status === 429 || isTransientStatus(status) ? "unknown" : "stop_other");
+    const source = row !== undefined && (row.word !== undefined || row.sentence !== undefined) ? "provider_code" : "status";
+    const inputTooLong = status !== undefined && !INPUT_TOO_LONG_STATUSES.has(status) ? "no" : row?.inputTooLong === true ? "yes" : enveloped ? "no" : "unknown";
+    return { condition, source, inputTooLong };
+}
+const UNIFIED_QUOTA_HEADERS = [
+    "anthropic-ratelimit-unified-representative-claim",
+    "anthropic-ratelimit-unified-overage-status",
+    "anthropic-ratelimit-unified-overage-disabled-reason",
+];
+function headerPresent(headers, name) {
+    const v = headers?.get?.(name);
+    return typeof v === "string" && v.length > 0;
+}
+export function judgeHttpFailure(args) {
+    const { dialect, status, headers, body } = args;
+    if (status === 429 && UNIFIED_QUOTA_HEADERS.some((h) => headerPresent(headers, h))) {
+        const resetAtMs = readUnifiedResetEpochMs(headers);
+        return { condition: "quota_exhausted", source: "unified_header", ...(resetAtMs !== undefined ? { resetAtMs } : {}), inputTooLong: "no" };
+    }
+    const envelope = statedEnvelope(body);
+    return verdictOf(dialect, status, statementOf(envelope), envelope !== undefined);
+}
+export function judgeInBandError(dialect, envelope) {
+    return verdictOf(dialect, undefined, statementOf(envelope), true);
+}
+export function inBandProviderError(dialect, envelope, label) {
+    const v = judgeInBandError(dialect, envelope);
+    const word = carriedProviderWord(envelope);
+    const sentence = typeof envelope.message === "string" ? envelope.message : "";
+    return new BrainError(PROVIDER_CONDITION_TRAITS[v.condition].inBandCode, `${label} stream error (${word ?? "unknown"}): ${sentence}`, undefined, {
+        apiError: true,
+        ...(v.inputTooLong === "yes" ? { inputTooLong: true } : v.inputTooLong === "no" ? { inputTooLongRuledOut: true } : {}),
+        ...(word !== undefined ? { providerCode: word } : {}),
+        verdict: { condition: v.condition, source: v.source },
+    });
+}

package/dist/brain/request-params.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Request-parameter passthrough (design/40). A deployment can set official provider params it wants but
+ * core doesn't model as first-class fields (OpenAI `frequency_penalty`/`presence_penalty`/`top_p`/`seed`/
+ * `logit_bias`; Anthropic `top_k`/`top_p`/`stop_sequences`; …) via `Model.extraBody`, and core merges them
+ * into the brain's request body. Anchored at the **Model** level (not per-turn) so the serialized body
+ * stays byte-stable across turns → the prefix cache holds (design/9/31).
+ *
+ * Symmetric: each brain owns its structural + tuning keys (`reserved`) and ALWAYS wins — `extraBody` can
+ * only supply the long tail, never clobber `messages`/`tools`/`temperature`/etc. Stripping is the safety
+ * enforcement (the brains are standalone-usable), and a strip is never silent: {@link applyExtraBody}
+ * RETURNS the keys it stripped, the brain reports them on the request it built
+ * (`SSERequest.extraBodyDropped`), the stream engine reports them to the run's sink when it commits that
+ * request (`reportExtraBodyDropped`), and the Runner announces them (`route.extra_body_reserved_dropped`).
+ * One reading, at the one place the strip happens — so an `extraBody` a host brain swapped in for a single
+ * request, or one on the compaction model, is said the same way the task's own model spec is.
+ */
 /** OpenAI request-body keys core owns; `extraBody` cannot override these. */
 export declare const OPENAI_RESERVED: ReadonlySet<string>;
 /** Anthropic request-body keys core owns; `extraBody` cannot override these. (Note the asymmetry vs
@@ -9,19 +25,24 @@ export declare const ANTHROPIC_RESERVED: ReadonlySet<string>;
  * The last three are NOT keys the adapter sets — they are keys it must be IMPOSSIBLE to set. The
  * Open Responses lane is stateless by contract (this engine is the transcript authority), and
  * `extraBody` is the only other path to the request body, so `store` / `previous_response_id` /
- * `conversation` are reserved purely to close it. A deployment that sets one gets the design/40
- * collision warning at load and a stripped key on the wire, never a silently server-linked turn.
+ * `conversation` are reserved purely to close it. A deployment that sets one gets a stripped key on the
+ * wire and the drop announced, never a silently server-linked turn.
  */
 export declare const RESPONSES_RESERVED: ReadonlySet<string>;
-/** Reserved set for a model's API. */
-export declare function reservedFor(api: string): ReadonlySet<string>;
 /**
  * Merge `extraBody` into a brain's already-built request `body`, dropping any key the brain owns so core
- * always wins. Returns a NEW object (passthrough keys first, then core keys) when `extraBody` is set; the
+ * always wins. `body` is a NEW object (passthrough keys first, then core keys) when `extraBody` is set; the
  * exact `body` reference (no allocation, byte-identical serialization) when it isn't — so an existing
  * deployment with no `extraBody` is unaffected.
+ *
+ * `dropped` is the keys of `extraBody` that were stripped, in `extraBody`'s insertion order, names only (a
+ * value never leaves this function except inside `body`). It is a property of the same walk that strips, so
+ * what is said and what is dropped cannot disagree; empty when nothing was stripped.
  */
-export declare function applyExtraBody(body: Record<string, unknown>, extraBody: Record<string, unknown> | undefined, reserved: ReadonlySet<string>): Record<string, unknown>;
+export declare function applyExtraBody(body: Record<string, unknown>, extraBody: Record<string, unknown> | undefined, reserved: ReadonlySet<string>): {
+    body: Record<string, unknown>;
+    dropped: readonly string[];
+};
 /** The auth-bearing header names (case-fold), single-sourced for the credential enforcement
  *  (`applyRouteCredentialHeaders`, route-adjudicator.ts — the ONE authority over auth spelling: a
  *  per-model winner strips every carrier, any case, and re-asserts the winning bag's own),
@@ -99,5 +120,3 @@ export declare const OUTPUT_CAP_KEYS: Readonly<Record<"openai" | "anthropic" | "
  * request that carries two. Smallest wins so a consumer reasoning about the bound stays conservative.
  */
 export declare function effectiveOutputCap(body: Record<string, unknown>, keys: readonly string[]): number | undefined;
-/** Names in `extraBody` that collide with a reserved (core-owned) key — for a load-time warning. */
-export declare function reservedCollisions(extraBody: Record<string, unknown> | undefined, reserved: ReadonlySet<string>): string[];

package/dist/brain/request-params.js

@@ -1,4 +1,3 @@
-import { RESPONSES_APIS } from "./reasoning.js";
 export const OPENAI_RESERVED = new Set([
     "model",
     "messages",
@@ -39,20 +38,19 @@ export const RESPONSES_RESERVED = new Set([
     "previous_response_id",
     "conversation",
 ]);
-export function reservedFor(api) {
-    if (RESPONSES_APIS.has(api))
-        return RESPONSES_RESERVED;
-    return api === "anthropic-messages" ? ANTHROPIC_RESERVED : OPENAI_RESERVED;
-}
+const NO_KEYS = Object.freeze([]);
 export function applyExtraBody(body, extraBody, reserved) {
     if (!extraBody)
-        return body;
+        return { body, dropped: NO_KEYS };
     const passthrough = {};
+    const dropped = [];
     for (const [k, v] of Object.entries(extraBody)) {
-        if (!reserved.has(k))
+        if (reserved.has(k))
+            dropped.push(k);
+        else
             passthrough[k] = v;
     }
-    return { ...passthrough, ...body };
+    return { body: { ...passthrough, ...body }, dropped: dropped.length === 0 ? NO_KEYS : dropped };
 }
 export const AUTH_CARRIER_NAMES = new Set(["authorization", "x-api-key"]);
 export function lockHeader(headers, lowerName, value) {
@@ -109,6 +107,3 @@ export function effectiveOutputCap(body, keys) {
     }
     return smallest;
 }
-export function reservedCollisions(extraBody, reserved) {
-    return extraBody ? Object.keys(extraBody).filter((k) => reserved.has(k)) : [];
-}

package/dist/brain/request-route.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The route a provider request took, as the brain that built it states it: where the credential it carried came
+ * from, how that credential rode, and which knob named the request's root. One projection of the two resolutions a
+ * request build already runs ({@link import("./route-adjudicator.js").resolveRouteCredential} and
+ * {@link import("./route-adjudicator.js").resolveRequestRootOf}) — never a key value, never a URL.
+ *
+ * Who reads it: the engine's terminal-shell mint lifts the committed request's route onto
+ * `AssistantMessage.apiErrorRoute` (only beside `isApiErrorMessage`), and a run whose terminal is a provider refusal
+ * carries it on `terminal.detail.route`. {@link ROUTE_CREDENTIAL_PAIRING} is the same vocabulary as a table: one row
+ * per declaration shape a request can carry, naming the knob(s) the credential is read from and the root knob it is
+ * paired with — the machine-readable half of the pairing law whose verdicts the conformance corpus pins.
+ */
+import type { RouteCredential } from "../internal/llm.js";
+/** Where the credential a request would carry came from.
+ *  - `"per-model"` — resolved FOR this model: a per-call key/headers from the per-model auth hook
+ *    (`getApiKeyAndHeaders`), or an auth-bearing header declared on `Model.headers`. Paired by
+ *    construction (the resolver was asked about THIS entry), so the adjudicator never refuses it.
+ *  - `"deployment-config"` — the brain construction-time fallback (`config.apiKey` / an auth header
+ *    in `config.headers`). Paired only with the deployment's own declared root (`config.baseUrl`).
+ *  - `"absent"` — no credential anywhere. Legal for keyless gateways; refused only where an entry
+ *    declares its OWN URL away from a declared deployment root (a distinct endpoint with no
+ *    credential route is a configuration hole, not a keyless deployment). */
+export declare const ROUTE_CREDENTIAL_SOURCES: readonly ["per-model", "deployment-config", "absent"];
+export type RouteCredentialSource = (typeof ROUTE_CREDENTIAL_SOURCES)[number];
+/** How a credential rode: the brain's apiKey knob (written as the lane's own auth header), or an auth-bearing header
+ *  from one of the header bags. */
+export declare const ROUTE_CARRIERS: readonly ["apiKey", "header"];
+export type RouteCarrier = (typeof ROUTE_CARRIERS)[number];
+/** The header bag an auth-bearing header came from: the per-call options (the per-model auth hook's headers), the
+ *  model entry (`Model.headers`), or the brain's construction config (`config.headers`). */
+export declare const ROUTE_CARRIER_BAGS: readonly ["options", "model", "config"];
+export type RouteCarrierBag = (typeof ROUTE_CARRIER_BAGS)[number];
+/** Which knob named the request's root: the model entry (`Model.baseUrl`), the brain's construction config
+ *  (`config.baseUrl`), or the lane's own default endpoint (neither was declared). */
+export declare const REQUEST_ROOT_ORIGINS: readonly ["model", "deployment", "lane-default"];
+export type RequestRootOrigin = (typeof REQUEST_ROOT_ORIGINS)[number];
+/**
+ * The route a request took ({@link requestRouteOf}). Never a key value and never a URL — the words name knobs, so the
+ * value may travel wherever the failure it describes travels.
+ *  - `credentialSource` — {@link RouteCredentialSource}.
+ *  - `carrier` — how the credential rode ({@link RouteCarrier}); absent exactly when `credentialSource` is `"absent"`.
+ *  - `carrierBag` — the header bag whose auth header rode ({@link RouteCarrierBag}); present exactly when one did:
+ *    with carrier `"header"`, and beside carrier `"apiKey"` in the deployment shape that sets both `config.apiKey`
+ *    and an auth header in `config.headers` (both ride).
+ *  - `root` — which knob named the request's root ({@link RequestRootOrigin}).
+ * The legal shapes are exactly the rows of {@link ROUTE_CREDENTIAL_PAIRING}.
+ */
+export interface RequestRoute {
+    credentialSource: RouteCredentialSource;
+    carrier?: RouteCarrier;
+    carrierBag?: RouteCarrierBag;
+    root: RequestRootOrigin;
+}
+/** The route of a request carrying `credential`, rooted at the knob `root` names — the one mint of a
+ *  {@link RequestRoute}. Reads the credential's SHAPE only; its key value never leaves this function. */
+export declare function requestRouteOf(credential: RouteCredential, root: RequestRootOrigin): RequestRoute;
+/** One row of {@link ROUTE_CREDENTIAL_PAIRING}. */
+export interface RouteCredentialPairingRow {
+    readonly credentialSource: RouteCredentialSource;
+    readonly carrier?: RouteCarrier;
+    readonly carrierBag?: RouteCarrierBag;
+    /** The knob(s) the credential is read from, in this engine's own spelling (`getApiKeyAndHeaders` is the per-model
+     *  auth hook, whose answer reaches the brain as the per-call options). Empty for `"absent"`. */
+    readonly credentialKnobs: readonly string[];
+    /** The root knob the credential is paired with: `"Model.baseUrl"` for a per-model credential (paired by
+     *  construction — it was resolved for this entry), `"config.baseUrl"` for the deployment credential (paired only
+     *  when that root is declared and the request targets it; undeclared = the unpinned posture). Absent for
+     *  `"absent"`. */
+    readonly pairsWith?: "Model.baseUrl" | "config.baseUrl";
+}
+/**
+ * The pairing law as a table — one row per route shape a request can carry, in resolution precedence (an earlier
+ * row's source wins when several are configured; the three deployment rows are one rank, the deployment credential
+ * judged as one). A consumer naming "which key was that" reads the row a {@link RequestRoute} lands on (same
+ * `credentialSource` / `carrier` / `carrierBag`), never a sentence. The verdicts the law gives these shapes are the
+ * conformance corpus's (`ROUTE_ADJUDICATION_CONFORMANCE_CORPUS`).
+ */
+export declare const ROUTE_CREDENTIAL_PAIRING: readonly RouteCredentialPairingRow[];
+/** The pairing row a route lands on, `undefined` for a shape no request carries. */
+export declare function routePairingRowOf(route: Pick<RequestRoute, "credentialSource" | "carrier" | "carrierBag">): RouteCredentialPairingRow | undefined;
+/** A route as a value this engine did not build carries it (a host Brain's message, an adapter's request): each member
+ *  read once, and the whole value admitted only as a shape some request carries — a {@link ROUTE_CREDENTIAL_PAIRING}
+ *  row plus a closed-set root. Anything else is no route (absent), never a partial one. */
+export declare function admittedRequestRoute(value: unknown): RequestRoute | undefined;

package/dist/brain/request-route.js

@@ -0,0 +1,41 @@
+import { readMember } from "../core/thrown-value.js";
+export const ROUTE_CREDENTIAL_SOURCES = Object.freeze(["per-model", "deployment-config", "absent"]);
+export const ROUTE_CARRIERS = Object.freeze(["apiKey", "header"]);
+export const ROUTE_CARRIER_BAGS = Object.freeze(["options", "model", "config"]);
+export const REQUEST_ROOT_ORIGINS = Object.freeze(["model", "deployment", "lane-default"]);
+export function requestRouteOf(credential, root) {
+    const carrier = credential.apiKey !== undefined ? "apiKey" : credential.headersBorne === true ? "header" : undefined;
+    return {
+        credentialSource: credential.source,
+        ...(carrier !== undefined ? { carrier } : {}),
+        ...(credential.headersBorne === true && credential.carrierBag !== undefined ? { carrierBag: credential.carrierBag } : {}),
+        root,
+    };
+}
+export const ROUTE_CREDENTIAL_PAIRING = Object.freeze([
+    { credentialSource: "per-model", carrier: "apiKey", credentialKnobs: ["getApiKeyAndHeaders().apiKey"], pairsWith: "Model.baseUrl" },
+    { credentialSource: "per-model", carrier: "header", carrierBag: "options", credentialKnobs: ["getApiKeyAndHeaders().headers"], pairsWith: "Model.baseUrl" },
+    { credentialSource: "per-model", carrier: "header", carrierBag: "model", credentialKnobs: ["Model.headers"], pairsWith: "Model.baseUrl" },
+    { credentialSource: "deployment-config", carrier: "apiKey", credentialKnobs: ["config.apiKey"], pairsWith: "config.baseUrl" },
+    { credentialSource: "deployment-config", carrier: "apiKey", carrierBag: "config", credentialKnobs: ["config.apiKey", "config.headers"], pairsWith: "config.baseUrl" },
+    { credentialSource: "deployment-config", carrier: "header", carrierBag: "config", credentialKnobs: ["config.headers"], pairsWith: "config.baseUrl" },
+    { credentialSource: "absent", credentialKnobs: [] },
+].map((row) => Object.freeze({ ...row, credentialKnobs: Object.freeze([...row.credentialKnobs]) })));
+export function routePairingRowOf(route) {
+    return ROUTE_CREDENTIAL_PAIRING.find((row) => row.credentialSource === route.credentialSource && row.carrier === route.carrier && row.carrierBag === route.carrierBag);
+}
+const ROOT_ORIGIN_SET = new Set(REQUEST_ROOT_ORIGINS);
+export function admittedRequestRoute(value) {
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const credentialSource = readMember(value, "credentialSource");
+    const carrier = readMember(value, "carrier");
+    const carrierBag = readMember(value, "carrierBag");
+    const root = readMember(value, "root");
+    if (!ROOT_ORIGIN_SET.has(root))
+        return undefined;
+    const row = ROUTE_CREDENTIAL_PAIRING.find((r) => r.credentialSource === credentialSource && r.carrier === carrier && r.carrierBag === carrierBag);
+    if (row === undefined)
+        return undefined;
+    return { credentialSource: row.credentialSource, ...(row.carrier !== undefined ? { carrier: row.carrier } : {}), ...(row.carrierBag !== undefined ? { carrierBag: row.carrierBag } : {}), root: root };
+}

package/dist/brain/retry.d.ts

@@ -24,6 +24,14 @@ export declare function parseRetryAfter(res: Response | undefined): number | und
  * (a stale stamp carries no wait, so the caller falls back to its computed backoff).
  */
 export declare function parseRateLimitReset(res: Response | undefined): number | undefined;
+/**
+ * The one read of `anthropic-ratelimit-unified-reset`: the absolute instant (epoch ms, wall clock) the window
+ * reopens, or undefined when absent, unparseable or not a positive stamp. The backoff floor above reads it
+ * relative to now; a quota verdict carries it as the instant itself (`provider-dialect.ts`).
+ */
+export declare function readUnifiedResetEpochMs(headers: {
+    get?: (name: string) => string | null;
+} | undefined | null): number | undefined;
 /**
  * A single provider wait hint after clamping, carrying enough of its own history to disclose a
  * truncation: `rawMs` is only set when the response actually asked for more than {@link

package/dist/brain/retry.js

@@ -15,14 +15,20 @@ export function parseRetryAfter(res) {
     return undefined;
 }
 export function parseRateLimitReset(res) {
-    const h = res?.headers?.get?.("anthropic-ratelimit-unified-reset");
+    const at = readUnifiedResetEpochMs(res?.headers);
+    if (at === undefined)
+        return undefined;
+    const ms = at - Date.now();
+    return ms > 0 ? ms : undefined;
+}
+export function readUnifiedResetEpochMs(headers) {
+    const h = headers?.get?.("anthropic-ratelimit-unified-reset");
     if (!h)
         return undefined;
     const epochSecs = Number(h);
-    if (!Number.isFinite(epochSecs))
+    if (!Number.isFinite(epochSecs) || epochSecs <= 0)
         return undefined;
-    const ms = Math.round(epochSecs * 1000 - Date.now());
-    return ms > 0 ? ms : undefined;
+    return Math.round(epochSecs * 1000);
 }
 function clampHint(rawMs) {
     return rawMs > MAX_HEADER_WAIT_MS ? { ms: MAX_HEADER_WAIT_MS, rawMs } : { ms: rawMs };

package/dist/brain/route-adjudicator.d.ts

@@ -40,6 +40,7 @@
 import type { Model } from "../internal/llm.js";
 import type { RouteAdjudication, RouteCredential, RoutePairingConfig, RoutePairingPosture } from "../internal/llm.js";
 import type { Brain, EngineNotice } from "../core/types.js";
+import type { RequestRootOrigin } from "./request-route.js";
 /** A base URL's ROUTE KEY — the value the pairing law COMPARES, folded to WIRE equivalence: the
  *  halves the wire itself treats as case-insensitive (scheme and host, RFC 9110) fold, the scheme's
  *  default port elides, and PATH and QUERY ride byte-preserved apart from the trailing slashes the
@@ -113,6 +114,12 @@ export declare function stripUrlCredentials(text: string): string;
  *  three homes; now it has one. Answers `""` when nothing is declared and the lane has no default —
  *  whether that is a refusal is the caller's. */
 export declare function resolveRequestRoot(modelBaseUrl: string | undefined, configBaseUrl: string | undefined, laneDefault?: string): string;
+/** {@link resolveRequestRoot} with the knob that named the root beside it (`RequestRootOrigin`) — the one
+ *  resolution; the root a request build sends to and the root its route states cannot come from two readings. */
+export declare function resolveRequestRootOf(modelBaseUrl: string | undefined, configBaseUrl: string | undefined, laneDefault?: string): {
+    root: string;
+    origin: RequestRootOrigin;
+};
 /** Whether a header bag carries an auth-bearing header (any case). */
 export declare function hasAuthCarrier(headers: Record<string, string> | undefined): boolean;
 /**

package/dist/brain/route-adjudicator.js

@@ -178,10 +178,14 @@ export function stripUrlCredentials(text) {
     return text.replace(/([A-Za-z][A-Za-z0-9+.\-]*:\/\/)[^/\s"'@]*@/g, `$1${REDACTED_CREDENTIALS}@`);
 }
 export function resolveRequestRoot(modelBaseUrl, configBaseUrl, laneDefault = "") {
+    return resolveRequestRootOf(modelBaseUrl, configBaseUrl, laneDefault).root;
+}
+export function resolveRequestRootOf(modelBaseUrl, configBaseUrl, laneDefault = "") {
     const entry = judgeRequestRoot(modelBaseUrl, "Model.baseUrl");
     const declared = judgeRequestRoot(configBaseUrl, "config.baseUrl");
+    const origin = entry !== undefined ? "model" : declared !== undefined ? "deployment" : "lane-default";
     const chosen = (entry ?? declared)?.parsed ?? servableParse(laneDefault.trim());
-    return chosen === undefined ? laneDefault : canonicalRootSpelling(chosen);
+    return { root: chosen === undefined ? laneDefault : canonicalRootSpelling(chosen), origin };
 }
 export function hasAuthCarrier(headers) {
     if (!headers)

package/dist/brain/status-sink.d.ts

@@ -130,3 +130,23 @@ export declare function runWithReasoningWireFacts<T>(observe: (f: ReasoningWireF
  * {@link runWithReasoningWireFacts}).
  */
 export declare function reportReasoningWireFacts(facts: ReasoningWireFacts): void;
+/** What a request that is about to be sent had stripped from its model's `extraBody`: the wire adapter's `api`, the catalog id
+ *  the request was sent as, and the stripped key NAMES (never a value), in `extraBody`'s order. */
+export interface ExtraBodyDroppedReport {
+    api: string;
+    modelId: string;
+    keys: readonly string[];
+}
+/**
+ * Run `fn` with a per-run extraBody-strip sink in scope — the FOURTH brain→runner ALS channel, same decoupling contract as
+ * its siblings (no brain-interface field, no per-call option, no-op outside the scope, a report never changes a call's
+ * outcome). Unlike them it spans the WHOLE leg (the Runner scopes it around everything the leg does, the end-of-task
+ * compaction included), is NOT shielded around the leg's internal calls (the compaction summary, a side query fired from a
+ * tool, the classifier: their model specs strip keys too), and is NOT revoked on settlement: it writes to no returned value
+ * (the report is an out-of-band notice, attributed to its run by id), and the lanes that run after the result — the
+ * next-prompt suggestions, a call the guardrail abandoned — strip keys the operator should hear about all the same.
+ */
+export declare function runWithExtraBodyDropped<T>(observe: (r: ExtraBodyDroppedReport) => void, fn: () => Promise<T>): Promise<T>;
+/** Report the strip of the request the engine has SELECTED to send, to the active per-run sink, if any (called at the
+ *  engine's commit points, never from `buildRequest`, which is also built speculatively). */
+export declare function reportExtraBodyDropped(report: ExtraBodyDroppedReport): void;

package/dist/brain/status-sink.js

@@ -57,3 +57,14 @@ export function reportReasoningWireFacts(facts) {
     catch {
     }
 }
+const extraBodyDroppedSinkStore = new AsyncLocalStorage();
+export function runWithExtraBodyDropped(observe, fn) {
+    return extraBodyDroppedSinkStore.run({ observe }, fn);
+}
+export function reportExtraBodyDropped(report) {
+    try {
+        extraBodyDroppedSinkStore.getStore()?.observe(report);
+    }
+    catch {
+    }
+}

package/dist/brain/stream-engine.d.ts

@@ -1,4 +1,8 @@
-import { type AssistantMessage, type Model, createAssistantMessageEventStream } from "../internal/llm.js";
+import { type AssistantMessage, type Model, type Usage, createAssistantMessageEventStream } from "../internal/llm.js";
+import type { BrainRetryErrClass } from "../core/types.js";
+import type { AssertAllKeysHandled } from "../core/ask-origin.js";
+import { type RequestRoute } from "./request-route.js";
+import { type ProviderDialect } from "./provider-dialect.js";
 import { type BrainTimeoutConfig } from "./timeout.js";
 /**
  * Shared streaming engine for the OpenAI- and Anthropic-shaped brains (design/32, consolidation).
@@ -130,6 +134,21 @@ export interface SSERequest {
      * come back identical; an adapter that declares nothing therefore permits no body change at all.
      */
     capDerivedPaths?: readonly string[];
+    /**
+     * The keys `Model.extraBody` carried that this adapter owns and therefore stripped from the body
+     * ({@link import("./request-params.js").applyExtraBody}'s `dropped`), names only; empty or absent when
+     * nothing was stripped. The engine reports them to the run's sink ({@link reportExtraBodyDropped}) when this
+     * request is committed to be sent, which is where the Runner announces them.
+     */
+    extraBodyDropped?: readonly string[];
+    /**
+     * The route this request takes, as the adapter that built it states it ({@link RequestRoute}, minted by
+     * `requestRouteOf` from the same credential and root resolutions the build used). The engine lifts the committed
+     * request's route onto the terminal shell of a provider failure (`AssistantMessage.apiErrorRoute`, beside
+     * `isApiErrorMessage`) — every failure of the request states the same route, so it is declared once here rather
+     * than on each failure. Absent = the adapter states none.
+     */
+    route?: RequestRoute;
     /**
      * Called by the engine once, if and only if THIS request becomes the one that is sent.
      *
@@ -168,6 +187,20 @@ export interface StreamControls {
     sawContentToken(): void;
     /** Cancel the underlying stream (e.g. degenerate-repetition cutoff). The read loop then ends. */
     cancel(): void;
+    /** The endpoint this call goes to, as the provider dialect table names it (`undefined` = none declares it):
+     *  what an in-band error frame is judged by. */
+    dialect: ProviderDialect | undefined;
+    /** Hand the engine what this attempt produced — its final content and the provider-reported usage — before
+     *  raising the provider's own in-band failure from `finalize`: the terminal message the engine mints for that
+     *  failure keeps it (the text the provider streamed, the usage it reported), rather than an empty shell. */
+    keepOutput(output: KeptOutput): void;
+}
+/** The output a parser hands over with {@link StreamControls.keepOutput}. */
+export interface KeptOutput {
+    content: AssistantMessage["content"];
+    usage: Usage;
+    /** The provider reported no usage frame (the zeros are not a measurement). */
+    usageMissing?: true;
 }
 export interface StreamParser {
     /** Handle one raw SSE line (`data: {...}`); parse, emit events, call `ctrl.sawContentToken()` on content. */
@@ -215,6 +248,23 @@ export interface StreamParser {
      */
     sealForRetry(): void;
 }
+/**
+ * The phase a retry-wait frame of each {@link BrainRetryErrClass} carries — ONE table, so a frame's two
+ * classifications are never mapped separately: the phase is what the brain is doing about the wait (waiting
+ * out a rate limit, re-connecting, re-sending), read off why it waits. Every retry-wait frame this engine
+ * emits — the connect ladder, the first-byte lane, the output-cap re-send, the mid-stream tiers — reads it.
+ */
+declare const RETRY_PHASE_OF_ERR_CLASS: {
+    readonly connect_refused: "reconnecting";
+    readonly transport: "reconnecting";
+    readonly stall: "reconnecting";
+    readonly rate_limit: "rate_limited";
+    readonly server: "retrying";
+    readonly http: "retrying";
+    readonly output_cap: "retrying";
+};
+/** Compile-time fence: every retry class has a phase row. */
+export type RetryPhaseTableCoversEveryErrClass = AssertAllKeysHandled<Exclude<BrainRetryErrClass, keyof typeof RETRY_PHASE_OF_ERR_CLASS>>;
 /**
  * Run one streaming request end-to-end and drive the provider `parser`. Returns a fresh event stream;
  * never throws (errors are pushed as `error` events, mirroring the Brain contract).
@@ -249,3 +299,4 @@ export declare function runStreamingBrain(args: {
      *  and never more than the brain's own budget ({@link resolveMaxRetries}); a non-finite or negative value caps nothing. */
     maxRetries?: number;
 }): ReturnType<typeof createAssistantMessageEventStream>;
+export {};