@sema-agent/core 7.56.0 → 7.57.0

package/dist/agents/peer-session-drain.js

@@ -1,4 +1,4 @@
-import { mailboxCrossProcessMountVerdict } from "../core/mailbox-store.js";
+import { isMailboxDecisionFinal, mailboxCrossProcessMountVerdict, moveMailboxDecision } from "../core/mailbox-store.js";
 import { decodeEngineFrame, ENGINE_FRAME_CODEC_VERSION, renderTaskNotificationXml, taskNotificationDedupKey } from "../core/task-notification.js";
 import { createFrameSettlement, toolResultReceiptKey } from "../core/frame-settlement.js";
 import { PRINCIPAL_INBOX_HANDLE } from "./cross-session-ref.js";
@@ -161,7 +161,7 @@ export function createPeerSessionDrain(opts) {
         ...(live
             ? {
                 inject: (entry) => {
-                    if (currentRound === undefined)
+                    if (currentRound === undefined || !currentRound.holds(lane))
                         return "deferred";
                     const payload = buildPeerMessagePayload(lane, entry);
                     if (currentRound.deliver(payload, "next") === "deferred")
@@ -169,9 +169,13 @@ export function createPeerSessionDrain(opts) {
                     noteDelivered(lane, entry.seq, 1, payload, currentRound.carrier);
                     return undefined;
                 },
+                canInject: () => currentRound !== undefined && currentRound.holds(lane) && !currentRound.spent,
             }
             : {}),
         receipt: receipt(lane),
+        tellsSender: (entry) => receiptAddress(lane, entry) !== undefined,
+        decide: (entry, expect, next) => moveMailboxDecision(mailbox, scope, lane.boxHandle, entry.seq, expect, next),
+        onFault: (entry, e) => opts.onError?.(e, { phase: "degraded", sessionId, classification: `peer-decision-move:${entry.box}#${entry.seq}` }),
         onHeld: (entry, count, cause, reannounce) => {
             if (!reannounce && lane.disclosedHeld.has(entry.seq))
                 return;
@@ -179,12 +183,13 @@ export function createPeerSessionDrain(opts) {
             disclose(lane, "held", cause, entry, reannounce ? `still held; its cause moved to ${cause} (${count} held)` : undefined);
         },
         onSettled: (entry, settlement, reason, count) => {
-            if (entry.box === lane.boxHandle && settlement !== "delivered")
+            if (entry.box === lane.boxHandle && settlement !== "delivered" && settlement !== "retired")
                 lane.ledger.set(entry.seq, { kind: "terminal", why: `held_${settlement}` });
             const replyTo = receiptAddress(lane, entry);
+            const told = reason !== "decided_elsewhere" && settlement !== "retired" && replyTo !== undefined;
             deliverEngineNotice(opts.onNotice, {
                 code: "peer.held_settled",
-                message: `held cross-session message seq ${entry.seq} left this session's held queue: ${settlement} (${reason}); ${count} still held${settlement === "expired" && reason === "evicted" ? " — the held queue was full, so the oldest entry was expired to make room" : ""}. The sender ${replyTo !== undefined ? "was sent a receipt" : "has no reply address and was not told"}.`,
+                message: `held cross-session message seq ${entry.seq} left this session's held queue: ${settlement} (${reason}); ${count} still held${settlement === "expired" && reason === "evicted" ? " — the held queue was full, so the oldest entry was expired to make room" : ""}${settlement === "retired" ? (reason === "superseded" ? " — its record is no longer in the box (another consumer settled it); nothing was decided here" : " — no decision was taken: it stays held in the box, and the next drain presents it again") : ""}${reason === "decided_elsewhere" ? " — another consumer of the box decided it first" : ""}. The sender ${told ? "was sent a receipt" : replyTo !== undefined ? "was not sent a receipt from here" : "has no reply address and was not told"}.`,
                 detail: { settlement, reason, seq: entry.seq, box: lane.boxHandle, ...(entry.peerMeta?.fromSession !== undefined ? { fromSession: entry.peerMeta.fromSession } : {}), heldCount: count, sessionId, runId },
             });
         },
@@ -216,28 +221,29 @@ export function createPeerSessionDrain(opts) {
     idleMachine.requester.configure({
         expired: (o) => void routePeerIdleNotice(route(), sessionId, { kind: "expired", label: o.label }),
     });
-    const adoptHeldDecisions = (lane) => {
-        const decided = lane.held.decisions();
-        if (decided.size === 0)
-            return;
-        for (const [seq, settlement] of decided) {
-            if (lane.ackedUpTo !== undefined && seq <= lane.ackedUpTo)
-                continue;
-            const mine = lane.ledger.get(seq);
-            if (mine !== undefined && mine.kind !== "held")
-                continue;
-            lane.ledger.set(seq, { kind: "terminal", why: `held_${settlement}` });
+    const reconcileHeld = (lane, lease) => {
+        const live = lease.messages.filter((m) => lane.ackedUpTo === undefined || m.seq > lane.ackedUpTo);
+        lane.held.reconcile(new Map(live.map((m) => [m.seq, m.decision])));
+        adoptFinalDecisions(lane, lease);
+        for (const m of live) {
+            const d = lane.ledger.get(m.seq);
+            if (lane.held.has(m.seq)) {
+                if (d === undefined)
+                    lane.ledger.set(m.seq, { kind: "held" });
+            }
+            else if (d?.kind === "held")
+                lane.ledger.delete(m.seq);
         }
     };
-    const reconcileHeld = (lane, lease) => {
-        lane.held.reconcile(new Set(lease.messages.map((m) => m.seq)));
-        let queued;
-        for (const [seq, d] of lane.ledger) {
-            if (d.kind !== "held")
+    const adoptFinalDecisions = (lane, lease) => {
+        for (const m of lease.messages) {
+            if (lane.ackedUpTo !== undefined && m.seq <= lane.ackedUpTo)
                 continue;
-            queued ??= new Set(lane.held.list().filter((e) => e.box === lane.boxHandle).map((e) => e.seq));
-            if (!queued.has(seq))
-                lane.ledger.delete(seq);
+            if (!isMailboxDecisionFinal(m.decision))
+                continue;
+            const d = lane.ledger.get(m.seq);
+            if (d === undefined || d.kind === "held" || d.kind === "invalidated")
+                lane.ledger.set(m.seq, { kind: "terminal", why: `held_${m.decision}` });
         }
     };
     const wantsCompactionEffects = () => {
@@ -280,7 +286,6 @@ export function createPeerSessionDrain(opts) {
     };
     const settleLaneLocally = (lane, landed) => {
         const { ledger, boxHandle } = lane;
-        adoptHeldDecisions(lane);
         const hostWithheldSeqs = [];
         if (seam.receipts.size > 0 || seam.withheld.size > 0 || seam.hostWithheld.size > 0) {
             for (const [seq, d] of ledger) {
@@ -326,26 +331,17 @@ export function createPeerSessionDrain(opts) {
         }
     };
     const ackSettledPrefix = async (lane, lease) => {
-        const { held, ledger, boxHandle } = lane;
-        const decided = held.decisions();
-        if (decided.size > 0) {
-            const live = new Set(lease.messages.map((m) => m.seq));
-            held.forgetDecisions([...decided.keys()].filter((seq) => !live.has(seq)));
-        }
+        const { ledger, boxHandle } = lane;
+        adoptFinalDecisions(lane, lease);
         const prefix = deriveAckPrefix(lane, lease.messages);
         if (prefix !== undefined && (lane.ackedUpTo === undefined || prefix > lane.ackedUpTo)) {
             try {
                 const result = await mailbox.ack(scope, boxHandle, drainOwner, prefix);
                 if (result.acked) {
                     lane.ackedUpTo = prefix;
-                    const gone = [];
-                    for (const seq of [...ledger.keys()]) {
-                        if (seq > prefix)
-                            continue;
-                        gone.push(seq);
-                        ledger.delete(seq);
-                    }
-                    held.forgetDecisions(gone);
+                    for (const seq of [...ledger.keys()])
+                        if (seq <= prefix)
+                            ledger.delete(seq);
                 }
                 else {
                     opts.onError?.(new Error(`the ${lane.kind === "session" ? "session box" : "principal inbox"} ${boxHandle} refused this leg's ack up to seq ${prefix}: the drain lease is no longer held by ${drainOwner} (it expired and another cycle claimed it). The records stay parked and the lease holder re-serves them.`), { phase: "degraded", sessionId, classification: "peer-box-ack" });
@@ -451,6 +447,13 @@ export function createPeerSessionDrain(opts) {
             lane.ledger.set(seq, { kind: "terminal", why });
         }
         batch = [];
+        leasedLanes = new Set();
+        lease(lanes) {
+            this.leasedLanes = new Set(lanes);
+        }
+        holds(lane) {
+            return this.leasedLanes.has(lane);
+        }
         chars = 0;
         constructor(limit, out, carrier, charBudget) {
             this.limit = limit;
@@ -527,15 +530,17 @@ export function createPeerSessionDrain(opts) {
             const leased = claims.filter((c) => c.lease !== null);
             if (leased.length === 0)
                 return { pending: 0, urgent: 0 };
+            round.lease(leased.map((c) => c.lane));
             for (const { lane, lease } of leased) {
                 bindHeld(lane, true);
                 reconcileHeld(lane, lease);
-                lane.held.rejudge();
+                await lane.held.rejudge();
             }
             try {
                 for (const { lane, lease } of leased) {
                     const { ledger, disclosedHeld, held, boxHandle } = lane;
                     const ackedUpTo = lane.ackedUpTo;
+                    let adoptedThisPass = false;
                     for (const m of lease.messages) {
                         const prior = ledger.get(m.seq);
                         if (prior === undefined || prior.kind !== "invalidated")
@@ -545,7 +550,6 @@ export function createPeerSessionDrain(opts) {
                         const attempt = prior.attempt + 1;
                         round.batch.push({ lane, payload: { ...prior.payload, attempt, resupplied: true }, priority: "next", urgent: false, seq: m.seq, attempt });
                     }
-                    adoptHeldDecisions(lane);
                     for (const m of lease.messages) {
                         if (ackedUpTo !== undefined && m.seq <= ackedUpTo)
                             continue;
@@ -597,15 +601,29 @@ export function createPeerSessionDrain(opts) {
                             continue;
                         }
                         const sameTree = meta?.fromRoot !== undefined && meta.fromRoot.toLowerCase() === sessionId.toLowerCase();
+                        const known = m.decision;
                         if (!sameTree) {
                             const judged = judgeMeta(facts, meta);
-                            if (judged.verdict === "refuse") {
+                            const shown = known === "held" || known === "approved";
+                            if (!shown && judged.verdict === "refuse") {
                                 disclose(lane, "refused", judged.cause, m);
                                 round.dispose(lane, m.seq, `refused:${judged.cause}`);
                                 continue;
                             }
-                            if (judged.verdict === "hold") {
-                                held.hold({ seq: m.seq, box: boxHandle, content: m.content, ...(m.from !== undefined ? { from: m.from } : {}), sentAt: m.sentAt, ...(m.hopChain !== undefined ? { hopChain: [...m.hopChain] } : {}), ...(meta !== undefined ? { peerMeta: { ...meta } } : {}), cause: judged.cause });
+                            if (shown || (judged.verdict === "hold" && known !== "delivered")) {
+                                const outcome = await held.hold({ seq: m.seq, box: boxHandle, content: m.content, ...(m.from !== undefined ? { from: m.from } : {}), sentAt: m.sentAt, ...(m.hopChain !== undefined ? { hopChain: [...m.hopChain] } : {}), ...(meta !== undefined ? { peerMeta: { ...meta } } : {}), cause: judged.verdict === "hold" ? judged.cause : "explicit-setting" }, shown ? known : undefined);
+                                if (outcome === "gone" || outcome === "fault")
+                                    continue;
+                                if (outcome !== "held" && outcome !== "adopted" && outcome !== "uncarded") {
+                                    round.dispose(lane, m.seq, `held_${outcome}`);
+                                    continue;
+                                }
+                                if (shown && outcome === "adopted")
+                                    adoptedThisPass = true;
+                                if (outcome === "uncarded" && !disclosedHeld.has(m.seq)) {
+                                    disclosedHeld.add(m.seq);
+                                    disclose(lane, "held", judged.verdict === "hold" ? judged.cause : "explicit-setting", m, "it is held in the box, but this session's held queue is full; it is shown when a card frees");
+                                }
                                 if (!ledger.has(m.seq))
                                     ledger.set(m.seq, { kind: "held" });
                                 continue;
@@ -622,6 +640,8 @@ export function createPeerSessionDrain(opts) {
                         }
                         round.batch.push({ lane, payload, priority: "next", urgent: meta?.urgent === true, seq: m.seq, attempt: 1 });
                     }
+                    if (adoptedThisPass)
+                        await held.rejudge();
                 }
             }
             finally {

package/dist/agents/send-message-tool.js

@@ -1,7 +1,7 @@
 import { Type } from "typebox";
 import { isNotificationInjectionOutcome } from "../core/task-notification.js";
 import { defineTool } from "../core/tools.js";
-import { normalizeAgentName, DURABLE_AGENT_HANDLE_RE, DURABLE_AGENT_HEARTBEAT_MS } from "../core/task-registry.js";
+import { normalizeAgentName, chosenAgentName, DURABLE_AGENT_HANDLE_RE, DURABLE_AGENT_HEARTBEAT_MS } from "../core/task-registry.js";
 import { announceTranscriptIntegrityGapOnce, canAccessAgentRecord, clearRevivedRowTerminalPayload } from "../core/background-agent-store.js";
 import { uuidv7 } from "../internal/harness.js";
 import { MAILBOX_TOMBSTONED_RECIPIENT_CODE, mailboxCrossProcessMountVerdict } from "../core/mailbox-store.js";
@@ -1041,6 +1041,7 @@ export function createSendMessageTool(opts) {
                 if (!l3Verdict.ok)
                     return admissionRefusal(l3Verdict.reason, who);
                 assertParentSpecSeatCurrent(ctx.parentSpecSeat);
+                const chosenRowName = chosenAgentName(targetId, row.name);
                 const resume = createSubagentResume({
                     ledger,
                     parentToolCallId: resumeToolUseId,
@@ -1055,7 +1056,7 @@ export function createSendMessageTool(opts) {
                     ...((ctx.onBackgroundChildEvent ?? opts.onBackgroundChildEvent) ? { bgSink: ctx.onBackgroundChildEvent ?? opts.onBackgroundChildEvent } : {}),
                     sessionScoped: row.sessionScoped === true,
                     ...(row.description !== undefined ? { rowDescription: row.description } : {}),
-                    ...(row.name !== undefined ? { rowName: row.name } : {}),
+                    ...(chosenRowName !== undefined ? { rowName: chosenRowName } : {}),
                     ...(row.agentType !== undefined ? { rowAgentType: row.agentType } : {}),
                     ...(row.owner !== undefined ? { rowOwner: row.owner } : {}),
                     ...(row.scope !== undefined ? { rowScope: row.scope } : {}),

package/dist/agents/subagent.js

@@ -41,7 +41,7 @@ import { boundedRedactedSummary } from "../core/untrusted-egress.js";
 import { uuidv7 } from "../internal/harness.js";
 import { addWorktree } from "../core/git-worktree-env.js";
 import { shellQuote } from "../tools/fs/search.js";
-import { BG_AGENT_REAP_STOP_ERROR } from "../core/task-registry.js";
+import { BG_AGENT_REAP_STOP_ERROR, chosenAgentName } from "../core/task-registry.js";
 import { readDurableOrgAdmission } from "../core/memory-admission.js";
 import { governanceRetryClass } from "../core/governance-codes.js";
 import { readSkillGrantCapture } from "../core/skill-grant.js";
@@ -1534,7 +1534,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             if (a.name !== undefined && typeof a.name !== "string") {
                 return notStartedResult({ isError: true, content: "Sub-agent not started: name must be a string.", details: { error: "name.invalid" } });
             }
-            const agentName = a.name;
+            const agentName = reviveClaim !== undefined ? chosenAgentName(reviveClaim.row.handle, a.name) : a.name;
             if (agentName !== undefined) {
                 if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(agentName)) {
                     return notStartedResult({
@@ -1732,7 +1732,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         content: errorCodeOf(e) === WORKTREE_NOT_A_REPOSITORY
                             ? "Sub-agent not started: worktree isolation failed — the working directory is not a git repository. Retry without the isolation parameter."
                             : "Sub-agent not started: worktree isolation failed. Retry without the isolation parameter, or fix the repository state.",
-                        details: { error: "isolation.failed", cause: thrownText(e) },
+                        details: { error: "isolation.failed", cause: childThrownText(e) },
                     });
                 }
             }
@@ -1756,13 +1756,13 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 }
                 catch (e) {
                     worktreeKeptPath = worktreeDir;
-                    worktreeFault = thrownText(e);
+                    worktreeFault = childThrownText(e);
                     return `worktree: ${worktreeDir} (cleanup check failed — the directory is kept on disk)`;
                 }
             };
             const reportedWorktreeLine = (line) => (line !== undefined && worktreeFault !== undefined ? `${line}: ${worktreeFault}` : line);
             const faultDetails = (cause) => ({
-                ...(cause !== undefined ? { cause: thrownText(cause) } : {}),
+                ...(cause !== undefined ? { cause: childThrownText(cause) } : {}),
                 ...(worktreeFault !== undefined ? { worktreeCause: worktreeFault } : {}),
             });
             let injectedTools = [];
@@ -2499,7 +2499,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             }
                         }
                         if (!settled) {
-                            const detail = thrownText(lastErr);
+                            const detail = childThrownText(lastErr);
                             try {
                                 enqueueMemoryAnnouncement(forkSettlementSeat.controlDir, {
                                     kind: "gate",
@@ -3007,7 +3007,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         }
                     }
                     if (!settled) {
-                        const detail = thrownText(lastErr);
+                        const detail = childThrownText(lastErr);
                         try {
                             enqueueMemoryAnnouncement(settlementSeat.controlDir, {
                                 kind: "gate",
@@ -3030,7 +3030,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             ...(reviveRow.sessionScoped ? { sessionScoped: true } : {}),
                             ...(reviveRow.description !== undefined ? { description: reviveRow.description } : {}),
                             agentType: spawnAgentType,
-                            ...(reviveRow.name !== undefined ? { name: reviveRow.name } : {}),
+                            name: reviveRow.name,
                             ...(reviveRow.parentTaskId !== undefined ? { parentTaskId: reviveRow.parentTaskId } : {}),
                             ...(reviveRow.parentSessionId !== undefined ? { parentSessionId: reviveRow.parentSessionId } : {}),
                             ...((reviveRow.rootSessionId ?? reviveRow.parentSessionId) !== undefined

package/dist/brain/anthropic.js

@@ -6,7 +6,7 @@ import { STREAM_TORN_WARNING, createRepetitionPoll, createStreamEndLedger, model
 import { admitToolCallId, providerResultIds, providerToolCallId, responseToolCallIds } from "./tool-call-id.js";
 import { emitBrainTelemetry, reportReasoningWireFacts } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imageWithholdOf, reportImagesWithheld, sendableImages } from "./media-degrade.js";
-import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, headerBagOnce, lockHeader, mergeHeaders, takeHeaderSpellings } from "./request-params.js";
+import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, declaredRequestValues, effectiveOutputCap, headerBagOnce, headerListEntries, lockHeader, mergeHeaders, takeHeaderSpellings } from "./request-params.js";
 import { admitRouteRequest, applyRouteCredentialHeaders, assertServableRequestRoot, brainConfigSnapshot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential } from "./route-adjudicator.js";
 import { requestRouteOf } from "./request-route.js";
 import { NAMES_AS_WRITTEN, resolveProviderDialect, endpointToolNames } from "./provider-dialect.js";
@@ -296,6 +296,8 @@ export function createAnthropicBrain(given = {}) {
                 const headerLayers = [modelHeaders, config.headers, optionsHeaders];
                 const headers = mergeHeaders(...headerLayers);
                 applyRouteCredentialHeaders(headers, routeCredential);
+                const declaredBetas = headerLayers.flatMap((layer) => Object.entries(layer ?? {}).flatMap(([name, value]) => (name.toLowerCase() === "anthropic-beta" ? headerListEntries(value) : [])));
+                const declared = declaredRequestValues([...headerLayers, headers], [config.version, ...declaredBetas], apiKey);
                 takeHeaderSpellings(headers, "anthropic-beta");
                 for (const layer of headerLayers) {
                     for (const [name, value] of Object.entries(layer ?? {}))
@@ -320,6 +322,7 @@ export function createAnthropicBrain(given = {}) {
                 return {
                     url,
                     headers,
+                    declared,
                     body: JSON.stringify(wire),
                     extraBodyDropped,
                     route: requestRouteOf(routeCredential, rootOrigin),
@@ -353,7 +356,7 @@ export function createAnthropicBrain(given = {}) {
                 let lastDegenCheckThinking = 0;
                 const detectRep = config.detectRepetition !== false;
                 let messageStopped = false;
-                const afterEnd = createStreamEndLedger();
+                const afterEnd = createStreamEndLedger(ctrl.providerWords);
                 const streamEnded = () => stopReason != null || messageStopped;
                 const mergeDeltaUsage = (u) => {
                     if (!u)
@@ -430,7 +433,7 @@ export function createAnthropicBrain(given = {}) {
                         else if (acc.type === "tool_use") {
                             const closed = acc.stopped === true || !endedCut;
                             if (!acc.toolName) {
-                                (nameMissingCause(closed) === "truncated" ? malformed : unnamed).push(`id="${acc.toolId || "?"}"(${acc.toolJson.slice(0, 200)})`);
+                                (nameMissingCause(closed) === "truncated" ? malformed : unnamed).push(`id="${ctrl.providerWords(acc.toolId || "?")}"(${ctrl.providerWords(acc.toolJson).slice(0, 200)})`);
                             }
                             else {
                                 const tc = closeToolUseBlock(acc, responseIds, closed);
@@ -439,7 +442,7 @@ export function createAnthropicBrain(given = {}) {
                                     finalContent.push(tc);
                                 }
                                 else {
-                                    malformed.push(`${acc.toolName}(${acc.toolJson.slice(0, 200)})`);
+                                    malformed.push(`${ctrl.providerWords(acc.toolName)}(${ctrl.providerWords(acc.toolJson).slice(0, 200)})`);
                                 }
                             }
                         }
@@ -580,8 +583,13 @@ export function createAnthropicBrain(given = {}) {
                             const d = evt.delta;
                             if (d?.stop_reason)
                                 stopReason = d.stop_reason;
-                            if (d?.stop_details)
-                                stopDetails = d.stop_details;
+                            if (d?.stop_details) {
+                                const raw = d.stop_details;
+                                stopDetails = {
+                                    ...(typeof raw.category === "string" ? { category: ctrl.providerWords(raw.category) } : {}),
+                                    ...(typeof raw.explanation === "string" ? { explanation: ctrl.providerWords(raw.explanation) } : {}),
+                                };
+                            }
                             mergeDeltaUsage(evt.usage);
                             break;
                         }
@@ -596,7 +604,7 @@ export function createAnthropicBrain(given = {}) {
                             const inputTooLong = e?.type === "request_too_large" ||
                                 (e?.type === "invalid_request_error" && typeof e.message === "string" && startsWithInputTooLongAnchor(e.message));
                             ctrl.keepOutput({ content: assembleTurn({}).content, ...reportedUsage() });
-                            throw new BrainError(anthropicStreamErrorCode(e?.type), `anthropic stream error (${e?.type ?? "unknown"}): ${e?.message ?? ""}`, undefined, { apiError: true, ...(e === undefined ? {} : inputTooLong ? { inputTooLong: true } : { inputTooLongRuledOut: true }) });
+                            throw new BrainError(anthropicStreamErrorCode(e?.type), `anthropic stream error ${ctrl.providerWords(`(${e?.type ?? "unknown"}): ${e?.message ?? ""}`)}`, undefined, { apiError: true, ...(e === undefined ? {} : inputTooLong ? { inputTooLong: true } : { inputTooLongRuledOut: true }) });
                         }
                         default:
                             break;
@@ -636,7 +644,7 @@ export function createAnthropicBrain(given = {}) {
                         }
                         catch {
                             malformedFrames++;
-                            malformedSample ??= data.slice(0, 160);
+                            malformedSample ??= ctrl.providerWords(data).slice(0, 160);
                             return;
                         }
                         handleEvent(evt);

package/dist/brain/open-responses.js

@@ -5,7 +5,7 @@ import { STREAM_TORN_WARNING, createRepetitionPoll, modelOutputInvalidOf, noteRe
 import { admitToolCallId, providerResultIds, providerToolCallId, responseToolCallIds } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imageWithholdOf, imagesOmittedNoVisionNote, reportImagesWithheld, sendableImages } from "./media-degrade.js";
-import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap, headerBagOnce, lockHeader, mergeHeaders } from "./request-params.js";
+import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, declaredRequestValues, effectiveOutputCap, headerBagOnce, lockHeader, mergeHeaders } from "./request-params.js";
 import { admitRouteRequest, applyRouteCredentialHeaders, assertServableRequestRoot, brainConfigSnapshot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential } from "./route-adjudicator.js";
 import { requestRouteOf } from "./request-route.js";
 import { NAMES_AS_WRITTEN, resolveProviderDialect, endpointToolNames } from "./provider-dialect.js";
@@ -281,6 +281,7 @@ export function createOpenResponsesBrain(given = {}) {
                 const { body: reasoningBody, effort } = applyReasoningToRequest({ api: "openai-responses", model, level: options?.reasoning, body });
                 const headers = mergeHeaders(modelHeaders, config.headers, optionsHeaders);
                 applyRouteCredentialHeaders(headers, routeCredential);
+                const declared = declaredRequestValues([modelHeaders, config.headers, optionsHeaders, headers], [], apiKey);
                 lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
                     lockHeader(headers, OPEN_RESPONSES_KEY_HEADER, `Bearer ${apiKey}`);
@@ -288,6 +289,7 @@ export function createOpenResponsesBrain(given = {}) {
                 return {
                     url,
                     headers,
+                    declared,
                     body: JSON.stringify(wire),
                     extraBodyDropped,
                     route: requestRouteOf(routeCredential, rootOrigin),
@@ -563,10 +565,10 @@ export function createOpenResponsesBrain(given = {}) {
                         case "response.failed": {
                             noteResponseModel(partial, frame.response?.model, model.id);
                             const err = frame.response?.error;
-                            throw new BrainError(responsesErrorCode(err?.code), `responses stream failed (${err?.code ?? "unknown"}): ${err?.message ?? ""}`, undefined, { apiError: true });
+                            throw new BrainError(responsesErrorCode(err?.code), `responses stream failed ${ctrl.providerWords(`(${err?.code ?? "unknown"}): ${err?.message ?? ""}`)}`, undefined, { apiError: true });
                         }
                         case "error": {
-                            throw new BrainError(responsesErrorCode(frame.code), `responses stream error (${frame.code ?? "unknown"}): ${frame.message ?? ""}`, undefined, { apiError: true });
+                            throw new BrainError(responsesErrorCode(frame.code), `responses stream error ${ctrl.providerWords(`(${frame.code ?? "unknown"}): ${frame.message ?? ""}`)}`, undefined, { apiError: true });
                         }
                         default:
                             return;
@@ -607,7 +609,7 @@ export function createOpenResponsesBrain(given = {}) {
                         }
                         catch {
                             malformedFrames++;
-                            malformedSample ??= data.slice(0, MALFORMED_SAMPLE_CHARS);
+                            malformedSample ??= ctrl.providerWords(data).slice(0, MALFORMED_SAMPLE_CHARS);
                             return;
                         }
                         handleFrame(frame);
@@ -660,10 +662,10 @@ export function createOpenResponsesBrain(given = {}) {
                                     finalContent.push(tc);
                                 }
                                 else if (acc.name) {
-                                    malformed.push(`${acc.name}(${acc.args.slice(0, MALFORMED_ARGS_CHARS)})`);
+                                    malformed.push(`${ctrl.providerWords(acc.name)}(${ctrl.providerWords(acc.args).slice(0, MALFORMED_ARGS_CHARS)})`);
                                 }
                                 else {
-                                    (nameMissingCause(closed) === "truncated" ? malformed : unnamed).push(`call_id="${acc.callId || "?"}"(${acc.args.slice(0, MALFORMED_ARGS_CHARS)})`);
+                                    (nameMissingCause(closed) === "truncated" ? malformed : unnamed).push(`call_id="${ctrl.providerWords(acc.callId || "?")}"(${ctrl.providerWords(acc.args).slice(0, MALFORMED_ARGS_CHARS)})`);
                                 }
                             }
                         }
@@ -708,14 +710,14 @@ export function createOpenResponsesBrain(given = {}) {
                             : safetyCut
                                 ? `[refusal] response cut by the provider content filter (incomplete_details.reason="${INCOMPLETE_CONTENT_FILTER}") — the output was censored/truncated for policy and is unreliable`
                                 : refused
-                                    ? `[refusal] response refused by the model for policy reasons: ${accumRefusal.trim()}`
+                                    ? `[refusal] response refused by the model for policy reasons: ${ctrl.providerWords(accumRefusal.trim())}`
                                     : (toolError ??
                                         (truncatedEmpty && !dynamicCut && !staticReasoningCut
                                             ? reasoningSeen
                                                 ? `[length_empty] response truncated at max_output_tokens (${maxTokensNote}) with no answer text — the model spent the whole budget on reasoning; raise the cap, or lower the reasoning effort for this task.`
                                                 : `[length_empty] response truncated at max_output_tokens (${maxTokensNote}) with no answer text — raise the cap`
                                             : emptyNoFinish
-                                                ? `[stream_torn] model stream ended with no content and ${terminalStatus === undefined ? "no terminal response event" : `a terminal status "${terminalStatus}" with no reason this client recognises (incomplete_details.reason=${incompleteReason ?? "absent"})`} — the response was lost (a torn stream or an in-band provider error frame)${malformedFrames > 0 ? ` — ${malformedFrames} unparseable data frame(s) were dropped on this stream (first sample: ${JSON.stringify(malformedSample)})` : ""}`
+                                                ? `[stream_torn] model stream ended with no content and ${terminalStatus === undefined ? "no terminal response event" : `a terminal status "${ctrl.providerWords(terminalStatus)}" with no reason this client recognises (incomplete_details.reason=${incompleteReason === undefined ? "absent" : ctrl.providerWords(String(incompleteReason))})`} — the response was lost (a torn stream or an in-band provider error frame)${malformedFrames > 0 ? ` — ${malformedFrames} unparseable data frame(s) were dropped on this stream (first sample: ${JSON.stringify(malformedSample)})` : ""}`
                                                 : undefined));
                         const errored = degenerate ||
                             safetyCut ||

package/dist/brain/openai.js

@@ -6,7 +6,7 @@ import { admitToolCallId, providerResultIds, providerToolCallId, responseToolCal
 import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imageWithholdOf, imagesOmittedNoVisionNote, reportImagesWithheld, sendableImages } from "./media-degrade.js";
 import { capabilityHeld } from "./model-capability.js";
-import { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, headerBagOnce, lockHeader, mergeHeaders } from "./request-params.js";
+import { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, declaredRequestValues, effectiveOutputCap, headerBagOnce, lockHeader, mergeHeaders } from "./request-params.js";
 import { BrainError, providerErrorWord } from "./errors.js";
 import { NAMES_AS_WRITTEN, inBandProviderError, resolveProviderDialect, endpointToolNames } from "./provider-dialect.js";
 import { admitRouteRequest, applyRouteCredentialHeaders, assertServableRequestRoot, brainConfigSnapshot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential } from "./route-adjudicator.js";
@@ -320,6 +320,7 @@ export function createOpenAIBrain(given = {}) {
                 const { body: reasoningBody } = applyReasoningToRequest({ api: "openai-completions", model, level: options?.reasoning, body });
                 const headers = mergeHeaders(modelHeaders, config.headers, optionsHeaders);
                 applyRouteCredentialHeaders(headers, routeCredential);
+                const declaredValues = declaredRequestValues([modelHeaders, config.headers, optionsHeaders, headers], [], apiKey);
                 lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
                     lockHeader(headers, OPENAI_KEY_HEADER, `Bearer ${apiKey}`);
@@ -327,6 +328,7 @@ export function createOpenAIBrain(given = {}) {
                 return {
                     url,
                     headers,
+                    declared: declaredValues,
                     body: JSON.stringify(wire),
                     extraBodyDropped,
                     route: requestRouteOf(routeCredential, rootOrigin),
@@ -359,7 +361,7 @@ export function createOpenAIBrain(given = {}) {
                 const responseIds = responseToolCallIds();
                 let finishReason = null;
                 let inBandError;
-                const afterEnd = createStreamEndLedger();
+                const afterEnd = createStreamEndLedger(ctrl.providerWords);
                 const terminalFrameSeen = () => finishReason != null || inBandError !== undefined;
                 let usageRaw;
                 let malformedFrames = 0;
@@ -447,7 +449,7 @@ export function createOpenAIBrain(given = {}) {
                         }
                         catch {
                             malformedFrames++;
-                            malformedSample ??= data.slice(0, 160);
+                            malformedSample ??= ctrl.providerWords(data).slice(0, 160);
                             return;
                         }
                         const stated = chunk.error;
@@ -456,7 +458,7 @@ export function createOpenAIBrain(given = {}) {
                                 afterEnd.note("error", providerErrorWord(stated) ?? "?");
                                 return;
                             }
-                            inBandError = inBandProviderError(ctrl.dialect, stated, "gateway");
+                            inBandError = inBandProviderError(ctrl.dialect, stated, "gateway", ctrl.providerWords);
                             ctrl.cancel();
                             return;
                         }
@@ -537,7 +539,7 @@ export function createOpenAIBrain(given = {}) {
                                     emptyPlaceholders++;
                                     continue;
                                 }
-                                (nameMissingCause(!endedCut) === "truncated" ? malformed : unnamed).push(`id="${acc.id || "?"}"(${acc.args.slice(0, 200)})`);
+                                (nameMissingCause(!endedCut) === "truncated" ? malformed : unnamed).push(`id="${ctrl.providerWords(acc.id || "?")}"(${ctrl.providerWords(acc.args).slice(0, 200)})`);
                                 continue;
                             }
                             const tc = closeToolCallAccum(acc, responseIds, !endedCut);
@@ -546,7 +548,7 @@ export function createOpenAIBrain(given = {}) {
                                 finalContent.push(tc);
                             }
                             else {
-                                malformed.push(`${acc.name}(${acc.args.slice(0, 200)})`);
+                                malformed.push(`${ctrl.providerWords(acc.name)}(${ctrl.providerWords(acc.args).slice(0, 200)})`);
                             }
                         }
                         if (config.repairTextToolCalls && toolCalls.length === 0 && textFace && context.tools && context.tools.length > 0) {
@@ -604,8 +606,8 @@ export function createOpenAIBrain(given = {}) {
                         const safetyCut = finishReading?.kind === "refusal";
                         const contextWindowExceeded = finishReading?.kind === "input_too_long";
                         const providerCut = finishReading?.kind === "provider_cut" ? finishReading : undefined;
-                        const finishReasonUnknown = finishReading?.kind === "unrecognized" ? echoFoldedWord(finishReason ?? "") : undefined;
-                        const finishQuoted = JSON.stringify((finishReason ?? "").slice(0, 64));
+                        const finishReasonUnknown = finishReading?.kind === "unrecognized" ? echoFoldedWord(finishReason ?? "", ctrl.providerWords) : undefined;
+                        const finishQuoted = JSON.stringify(ctrl.providerWords(finishReason ?? "").slice(0, 64));
                         const refused = accumRefusal.trim().length > 0;
                         const emptyNoFinish = noUsableContent && finishReason == null && !degenerate;
                         const maxTokensNote = sentMaxTokens !== undefined
@@ -620,7 +622,7 @@ export function createOpenAIBrain(given = {}) {
                             : safetyCut
                                 ? `[refusal] response cut by the provider content filter (finish_reason=${finishQuoted}) — the output was censored/truncated for policy and is unreliable`
                                 : refused
-                                    ? `[refusal] response refused by the model for policy reasons: ${accumRefusal.trim()}`
+                                    ? `[refusal] response refused by the model for policy reasons: ${ctrl.providerWords(accumRefusal.trim())}`
                                     : contextWindowExceeded
                                         ? `[invalid_request] model context window exceeded (finish_reason=${finishQuoted}) — the conversation no longer fits the model's context window`
                                         : providerCut !== undefined

package/dist/brain/provider-dialect.d.ts

@@ -240,11 +240,12 @@ export declare function judgeInBandError(dialect: ProviderDialect | undefined, e
  * The failure an in-band error frame states, as the brain error the stream's terminal carries: the code its
  * condition reads as ({@link PROVIDER_CONDITION_TRAITS}), the provider's word and sentence in the message, the word
  * on the echo seat, the verdict, and the context-limit reading of the same row. A frame the provider sent on its
- * own stream is a provider failure by construction (`apiError`); it states no status.
+ * own stream is a provider failure by construction (`apiError`); it states no status. The message carries the
+ * provider's words as the stream's mint (`providerWords`) renders them; the verdict reads the frame as it came.
  */
 export declare function inBandProviderError(dialect: ProviderDialect | undefined, envelope: {
     message?: unknown;
     code?: unknown;
     type?: unknown;
-}, label: string): BrainError;
+}, label: string, providerWords: (words: string) => string): BrainError;
 export {};

package/dist/brain/provider-dialect.js

@@ -201,11 +201,11 @@ export function judgeHttpFailure(args) {
 export function judgeInBandError(dialect, envelope) {
     return verdictOf(dialect, undefined, statementOf(envelope), true);
 }
-export function inBandProviderError(dialect, envelope, label) {
+export function inBandProviderError(dialect, envelope, label, providerWords) {
     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, {
+    return new BrainError(PROVIDER_CONDITION_TRAITS[v.condition].inBandCode, `${label} stream error ${providerWords(`(${word ?? "unknown"}): ${sentence}`)}`, undefined, {
         apiError: true,
         ...(v.inputTooLong === "yes" ? { inputTooLong: true } : v.inputTooLong === "no" ? { inputTooLongRuledOut: true } : {}),
         ...(word !== undefined ? { providerCode: word } : {}),

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

@@ -136,6 +136,12 @@ export declare function headerListEntries(value: unknown): string[];
  *  or keys answer differently on a second read cannot be judged as one bag and sent as another. */
 export declare function headerBagOnce(bag: Readonly<Record<string, string>> | undefined): Record<string, string> | undefined;
 export declare function mergeHeaders(...bags: Array<Record<string, string> | undefined>): Record<string, string>;
+/** The values a request is DECLARED with ({@link import("./stream-engine.js").SSERequest.declared}): every value of the header bags it was
+ *  built from — the route's credential headers included, as the merge after `applyRouteCredentialHeaders` holds them — the values the
+ *  deployment or the call stated outside a bag (a configured protocol version, each entry of a list header the brain re-folds), and the
+ *  key when it names a secret ({@link namesASecret}: a placeholder key is left in the words as it is left to every child). The values the
+ *  brain writes itself (a structural lock, the default version, the beta entries it chose) are not among them. */
+export declare function declaredRequestValues(bags: ReadonlyArray<Readonly<Record<string, string>> | undefined>, stated: ReadonlyArray<string | undefined>, key: string | undefined): string[];
 /**
  * The output-cap key(s) each lane's wire form uses. A lane's set is exactly the keys THAT lane's
  * endpoint reads — a stray cap key belonging to another wire form is inert there and must not be