@sema-agent/core 7.54.1 → 7.56.0

package/dist/brain/open-responses.js

@@ -4,11 +4,12 @@ import { DEGENERATE_MESSAGE, trimDegenerateTail } from "./repetition.js";
 import { STREAM_TORN_WARNING, createRepetitionPoll, modelOutputInvalidOf, noteResponseModel, nameMissingCause, parseStreamedToolArgs, placeTurnNotes } from "./stream-shared.js";
 import { admitToolCallId, providerResultIds, providerToolCallId, responseToolCallIds } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
-import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.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 { admitRouteRequest, applyRouteCredentialHeaders, assertServableRequestRoot, brainConfigSnapshot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential } from "./route-adjudicator.js";
 import { requestRouteOf } from "./request-route.js";
-import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
+import { NAMES_AS_WRITTEN, resolveProviderDialect, endpointToolNames } from "./provider-dialect.js";
+import { applyReasoningToRequest } from "./reasoning-request.js";
 import { runStreamingBrain } from "./stream-engine.js";
 import { refuseRetiredTimeoutKnobs } from "./timeout.js";
 import { resolveFetch } from "./transport.js";
@@ -17,9 +18,6 @@ const DEGENERATE_POLL_CHARS = 64;
 const MALFORMED_SAMPLE_CHARS = 160;
 const MALFORMED_ARGS_CHARS = 200;
 const CAPABILITY_DIAGNOSTIC_TYPE = "responses_capability";
-function responsesCompat(model) {
-    return (model.compat ?? {});
-}
 const NO_CONTENT = "(no content)";
 const DOCUMENT_OMITTED = "[PDF document omitted: PDF direct read requires an Anthropic-family model; re-Read the file (the engine will extract text/render pages when possible) or extract the text via Bash instead (e.g. `pdftotext`).]";
 function textOf(content) {
@@ -37,16 +35,17 @@ function functionCallOutputText(text, hasCarriedImages, original) {
         return "(image attached below)";
     return Array.isArray(original) && original.length > 0 ? "(non-text tool result omitted)" : "";
 }
-function toUserParts(content, supportsVision) {
+function toUserParts(content, withhold) {
     if (typeof content === "string") {
         return content === "" ? [] : [{ type: "input_text", text: content }];
     }
+    const supportsVision = withhold === undefined;
     const nDocs = content.filter((c) => c.type === "document").length;
     if (nDocs > 0)
         emitBrainTelemetry({ kind: "document_placeholder", count: nDocs });
     const images = content.filter((c) => c.type === "image" && c.data !== undefined && c.mimeType !== undefined);
-    if (!supportsVision && images.length > 0)
-        emitBrainTelemetry({ kind: "vision_placeholder", count: images.length });
+    if (withhold !== undefined)
+        reportImagesWithheld(withhold, images.length);
     const parts = [];
     for (const c of content) {
         if (c.type === "text" && typeof c.text === "string" && c.text.length > 0) {
@@ -64,8 +63,9 @@ function toUserParts(content, supportsVision) {
         parts.push({ type: "input_text", text: imagesOmittedNoVisionNote(images.length) });
     return parts;
 }
-function toResponsesInput(ctx, model, replayReasoning) {
-    const supportsVision = modelSupportsVision(model);
+function toResponsesInput(ctx, model, replayReasoning, toolNames) {
+    const imageWithhold = imageWithholdOf(model);
+    const supportsVision = imageWithhold === undefined;
     const out = [];
     let pendingImages = [];
     const flushImages = () => {
@@ -87,7 +87,7 @@ function toResponsesInput(ctx, model, replayReasoning) {
         if (m.role !== "toolResult")
             flushImages();
         if (m.role === "user") {
-            const parts = toUserParts(m.content, supportsVision);
+            const parts = toUserParts(m.content, imageWithhold);
             out.push({
                 type: "message",
                 role: "user",
@@ -116,15 +116,15 @@ function toResponsesInput(ctx, model, replayReasoning) {
             if (text !== "")
                 out.push({ type: "message", role: "assistant", content: [{ type: "output_text", text }] });
             for (const tc of toolCalls) {
-                out.push({ type: "function_call", call_id: providerToolCallId(tc), name: tc.name, arguments: JSON.stringify(tc.arguments ?? {}) });
+                out.push({ type: "function_call", call_id: providerToolCallId(tc), name: toolNames.sent(tc.name), arguments: JSON.stringify(tc.arguments ?? {}) });
             }
         }
         else if (m.role === "toolResult") {
             const mediaImages = sendableImages(Array.isArray(m.content) ? m.content : []);
             const rawImages = m.isError ? [] : mediaImages;
             const images = supportsVision ? rawImages : [];
-            if (!supportsVision && rawImages.length > 0)
-                emitBrainTelemetry({ kind: "vision_placeholder", count: rawImages.length });
+            if (imageWithhold !== undefined)
+                reportImagesWithheld(imageWithhold, rawImages.length);
             const nDocs = Array.isArray(m.content) ? m.content.filter((c) => c.type === "document").length : 0;
             if (nDocs > 0)
                 emitBrainTelemetry({ kind: "document_placeholder", count: nDocs });
@@ -145,27 +145,17 @@ function toResponsesInput(ctx, model, replayReasoning) {
     flushImages();
     return out;
 }
-function toResponsesTools(ctx) {
+function toResponsesTools(ctx, toolNames) {
     if (!ctx.tools || ctx.tools.length === 0)
         return undefined;
     return ctx.tools.map((t) => ({
         type: "function",
-        name: t.name,
+        name: toolNames.sent(t.name),
         description: t.description,
         parameters: t.parameters,
         strict: false,
     }));
 }
-function resolveWireEffort(model, reasoning) {
-    if (model.reasoning && reasoning === "off")
-        return declaredOffSpelling(model);
-    const compat = responsesCompat(model);
-    if (compat.supportsReasoningEffort === false)
-        return undefined;
-    if (!reasoningRequestCarried(model, reasoning))
-        return undefined;
-    return mintEffortWireValue(reasoning, model, compat.reasoningEffortLevels).wireValue;
-}
 function computeUsage(model, raw) {
     const input = raw?.input_tokens ?? 0;
     const output = raw?.output_tokens ?? 0;
@@ -231,6 +221,7 @@ export function createOpenResponsesBrain(given = {}) {
         let sentEffort;
         let builtMaxTokens;
         let builtMaxTokensLane = "unset";
+        let sentToolNames = NAMES_AS_WRITTEN;
         return runStreamingBrain({
             model,
             doFetch,
@@ -245,6 +236,8 @@ export function createOpenResponsesBrain(given = {}) {
                 if (!root) {
                     throw new Error("createOpenResponsesBrain: no baseUrl configured (set config.baseUrl or model.baseUrl)");
                 }
+                const url = joinRequestUrl(root, "/responses");
+                const builtToolNames = endpointToolNames(resolveProviderDialect(url, model.api), model.api, (context.tools ?? []).map((t) => t.name));
                 const modelHeaders = headerBagOnce(model.headers);
                 const optionsHeaders = headerBagOnce(options?.headers);
                 const routeCredential = resolveRouteCredential({
@@ -262,15 +255,14 @@ export function createOpenResponsesBrain(given = {}) {
                         "remove it, or serve this model through the chat-completions lane, which does support it");
                 }
                 const requestedMaxTokens = overrides?.maxOutputTokens ?? options?.maxTokens ?? model.maxTokens;
-                const effort = resolveWireEffort(model, options?.reasoning);
                 const body = {
                     model: model.id,
-                    input: toResponsesInput(context, model, config.replayReasoning !== false),
+                    input: toResponsesInput(context, model, config.replayReasoning !== false, builtToolNames),
                     stream: true,
                 };
                 if (context.systemPrompt)
                     body.instructions = context.systemPrompt;
-                const tools = toResponsesTools(context);
+                const tools = toResponsesTools(context, builtToolNames);
                 if (tools)
                     body.tools = tools;
                 if (options?.temperature !== undefined)
@@ -286,16 +278,15 @@ export function createOpenResponsesBrain(given = {}) {
                     builtMaxTokens = undefined;
                     builtMaxTokensLane = "unset";
                 }
-                if (effort !== undefined)
-                    body.reasoning = { effort };
+                const { body: reasoningBody, effort } = applyReasoningToRequest({ api: "openai-responses", model, level: options?.reasoning, body });
                 const headers = mergeHeaders(modelHeaders, config.headers, optionsHeaders);
                 applyRouteCredentialHeaders(headers, routeCredential);
                 lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
                     lockHeader(headers, OPEN_RESPONSES_KEY_HEADER, `Bearer ${apiKey}`);
-                const { body: wire, dropped: extraBodyDropped } = applyExtraBody(body, model.extraBody, RESPONSES_RESERVED);
+                const { body: wire, dropped: extraBodyDropped } = applyExtraBody(reasoningBody, model, RESPONSES_RESERVED);
                 return {
-                    url: joinRequestUrl(root, "/responses"),
+                    url,
                     headers,
                     body: JSON.stringify(wire),
                     extraBodyDropped,
@@ -307,6 +298,7 @@ export function createOpenResponsesBrain(given = {}) {
                         sentMaxTokens = builtMaxTokens;
                         sentMaxTokensLane = builtMaxTokensLane;
                         sentEffort = effort;
+                        sentToolNames = builtToolNames;
                     },
                 };
             },
@@ -457,7 +449,7 @@ export function createOpenResponsesBrain(given = {}) {
                             else if (itemType === "function_call") {
                                 const acc = openItem(index, "function_call", itemId);
                                 acc.callId = frame.item?.call_id ?? "";
-                                acc.name = frame.item?.name ?? "";
+                                acc.name = sentToolNames.called(frame.item?.name ?? "");
                                 if (frame.item?.arguments)
                                     acc.args += frame.item.arguments;
                             }
@@ -546,7 +538,7 @@ export function createOpenResponsesBrain(given = {}) {
                                 if (!acc.callId && frame.item?.call_id)
                                     acc.callId = frame.item.call_id;
                                 if (!acc.name && frame.item?.name)
-                                    acc.name = frame.item.name;
+                                    acc.name = sentToolNames.called(frame.item.name);
                                 if (acc.args === "" && frame.item?.arguments)
                                     acc.args = frame.item.arguments;
                             }

package/dist/brain/openai.js

@@ -4,13 +4,14 @@ import { DEGENERATE_MESSAGE, trimDegenerateTail } from "./repetition.js";
 import { STREAM_TORN_WARNING, createRepetitionPoll, createStreamEndLedger, echoFoldedWord, modelOutputInvalidOf, noteResponseModel, nameMissingCause, parseStreamedToolArgs, placeTurnNotes, truncationCauseClause } from "./stream-shared.js";
 import { admitToolCallId, providerResultIds, providerToolCallId, responseToolCallIds } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
-import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.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 { BrainError, providerErrorWord } from "./errors.js";
-import { inBandProviderError } from "./provider-dialect.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";
 import { requestRouteOf } from "./request-route.js";
-import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
+import { applyReasoningToRequest } from "./reasoning-request.js";
 import { runStreamingBrain } from "./stream-engine.js";
 import { refuseRetiredTimeoutKnobs } from "./timeout.js";
 import { resolveFetch } from "./transport.js";
@@ -38,7 +39,7 @@ function textOf(content) {
 }
 const NO_CONTENT = "(no content)";
 const DOCUMENT_OMITTED = "[PDF document omitted: PDF direct read requires an Anthropic-family model; re-Read the file (the engine will extract text/render pages when possible) or extract the text via Bash instead (e.g. `pdftotext`).]";
-function toUserContent(content, supportsVision = true) {
+function toUserContent(content, withhold) {
     if (typeof content === "string") {
         return content;
     }
@@ -52,9 +53,9 @@ function toUserContent(content, supportsVision = true) {
             return base;
         return base ? `${base}\n${DOCUMENT_OMITTED}` : DOCUMENT_OMITTED;
     }
-    if (!supportsVision) {
+    if (withhold !== undefined) {
         const n = content.filter((c) => c.type === "image").length;
-        emitBrainTelemetry({ kind: "vision_placeholder", count: n });
+        reportImagesWithheld(withhold, n);
         const base = textOf(content);
         const note = imagesOmittedNoVisionNote(n);
         const withNote = base ? `${base}\n${note}` : note;
@@ -80,85 +81,11 @@ function toUserContent(content, supportsVision = true) {
 function thinkingCompat(model) {
     return (model.compat ?? {});
 }
-function applyThinking(body, model, reasoning) {
-    if (model.reasoning && reasoning === "off") {
-        const offCompat = thinkingCompat(model);
-        const offFormat = offCompat.thinkingFormat ?? "openai";
-        switch (offFormat) {
-            case "qwen":
-            case "zai":
-                body.enable_thinking = false;
-                break;
-            case "qwen-chat-template": {
-                const k = (typeof body.chat_template_kwargs === "object" && body.chat_template_kwargs) || {};
-                body.chat_template_kwargs = { ...k, enable_thinking: false };
-                break;
-            }
-            case "deepseek":
-                body.thinking = { type: "disabled" };
-                break;
-            case "openrouter":
-            case "together":
-                body.reasoning = { enabled: false };
-                break;
-            case "openai": {
-                const offSpelling = declaredOffSpelling(model);
-                if (offSpelling !== undefined)
-                    body.reasoning_effort = offSpelling;
-                break;
-            }
-            default: {
-                const _exhaustive = offFormat;
-                void _exhaustive;
-                break;
-            }
-        }
-        return;
-    }
-    if (!reasoningRequestCarried(model, reasoning))
-        return;
-    const compat = thinkingCompat(model);
-    const supportsEffort = compat.supportsReasoningEffort ?? true;
-    const effortWire = mintEffortWireValue(reasoning, model, compat.reasoningEffortLevels).wireValue;
-    const format = compat.thinkingFormat ?? "openai";
-    switch (format) {
-        case "openai":
-            if (supportsEffort && effortWire !== undefined)
-                body.reasoning_effort = effortWire;
-            break;
-        case "openrouter":
-            body.reasoning = { effort: effortWire };
-            break;
-        case "deepseek":
-            body.thinking = { type: "enabled" };
-            if (supportsEffort && effortWire !== undefined)
-                body.reasoning_effort = effortWire;
-            break;
-        case "together":
-            body.reasoning = { enabled: true };
-            if (supportsEffort && effortWire !== undefined)
-                body.reasoning_effort = effortWire;
-            break;
-        case "qwen":
-        case "zai":
-            body.enable_thinking = true;
-            break;
-        case "qwen-chat-template": {
-            const k = (typeof body.chat_template_kwargs === "object" && body.chat_template_kwargs) || {};
-            body.chat_template_kwargs = { ...k, enable_thinking: true };
-            break;
-        }
-        default: {
-            const _exhaustive = format;
-            void _exhaustive;
-            break;
-        }
-    }
-}
-function toOpenAIMessages(ctx, replayThinking = true, model) {
-    const supportsVision = modelSupportsVision(model);
+function toOpenAIMessages(ctx, replayThinking = true, model, toolNames) {
+    const imageWithhold = imageWithholdOf(model);
+    const supportsVision = imageWithhold === undefined;
     const out = [];
-    const needsEmptyReasoningField = !!model?.reasoning && thinkingCompat(model).requiresReasoningContentOnAssistantMessages === true;
+    const needsEmptyReasoningField = model !== undefined && capabilityHeld(model, "reasoning") && thinkingCompat(model).requiresReasoningContentOnAssistantMessages === true;
     if (ctx.systemPrompt) {
         out.push({ role: "system", content: ctx.systemPrompt });
     }
@@ -181,7 +108,7 @@ function toOpenAIMessages(ctx, replayThinking = true, model) {
         if (m.role !== "toolResult")
             flushImages();
         if (m.role === "user") {
-            const uc = toUserContent(m.content, supportsVision);
+            const uc = toUserContent(m.content, imageWithhold);
             const empty = uc === "" || (Array.isArray(uc) && uc.length === 0);
             out.push({ role: "user", content: empty ? NO_CONTENT : uc });
         }
@@ -206,7 +133,7 @@ function toOpenAIMessages(ctx, replayThinking = true, model) {
                 msg.tool_calls = toolCalls.map((tc) => ({
                     id: providerToolCallId(tc),
                     type: "function",
-                    function: { name: tc.name, arguments: JSON.stringify(tc.arguments ?? {}) },
+                    function: { name: toolNames.sent(tc.name), arguments: JSON.stringify(tc.arguments ?? {}) },
                 }));
             }
             out.push(msg);
@@ -215,8 +142,8 @@ function toOpenAIMessages(ctx, replayThinking = true, model) {
             const mediaImages = sendableImages(Array.isArray(m.content) ? m.content : []);
             const rawImages = m.isError ? [] : mediaImages;
             const images = supportsVision ? rawImages : [];
-            if (!supportsVision && rawImages.length > 0)
-                emitBrainTelemetry({ kind: "vision_placeholder", count: rawImages.length });
+            if (imageWithhold !== undefined)
+                reportImagesWithheld(imageWithhold, rawImages.length);
             const nDocs = Array.isArray(m.content) ? m.content.filter((c) => c.type === "document").length : 0;
             if (nDocs > 0)
                 emitBrainTelemetry({ kind: "document_placeholder", count: nDocs });
@@ -244,13 +171,13 @@ function toolResultText(text, hasCarriedImages, original) {
         return "(image attached below)";
     return Array.isArray(original) && original.length > 0 ? "(non-text tool result omitted)" : "";
 }
-function toOpenAITools(ctx) {
+function toOpenAITools(ctx, toolNames) {
     if (!ctx.tools || ctx.tools.length === 0) {
         return undefined;
     }
     return ctx.tools.map((t) => ({
         type: "function",
-        function: { name: t.name, description: t.description, parameters: t.parameters },
+        function: { name: toolNames.sent(t.name), description: t.description, parameters: t.parameters },
     }));
 }
 const FINISH_REASON_READINGS = Object.freeze({
@@ -334,6 +261,7 @@ export function createOpenAIBrain(given = {}) {
         let sentMaxTokensLane = "unset";
         let builtMaxTokens;
         let builtMaxTokensLane = "unset";
+        let sentToolNames = NAMES_AS_WRITTEN;
         return runStreamingBrain({
             model,
             doFetch,
@@ -348,6 +276,8 @@ export function createOpenAIBrain(given = {}) {
                 if (!root) {
                     throw new Error("createOpenAIBrain: no baseUrl configured (set config.baseUrl or model.baseUrl)");
                 }
+                const url = joinRequestUrl(root, "/chat/completions");
+                const builtToolNames = endpointToolNames(resolveProviderDialect(url, model.api), model.api, (context.tools ?? []).map((t) => t.name));
                 const modelHeaders = headerBagOnce(model.headers);
                 const optionsHeaders = headerBagOnce(options?.headers);
                 const routeCredential = resolveRouteCredential({
@@ -362,11 +292,11 @@ export function createOpenAIBrain(given = {}) {
                 const apiKey = routeCredential.apiKey;
                 const body = {
                     model: model.id,
-                    messages: toOpenAIMessages(context, config.replayThinking, model),
+                    messages: toOpenAIMessages(context, config.replayThinking, model, builtToolNames),
                     stream: true,
                     stream_options: { include_usage: true },
                 };
-                const tools = toOpenAITools(context);
+                const tools = toOpenAITools(context, builtToolNames);
                 if (tools)
                     body.tools = tools;
                 if (options?.temperature !== undefined)
@@ -387,15 +317,15 @@ export function createOpenAIBrain(given = {}) {
                 }
                 if (options?.stop)
                     body.stop = options.stop;
-                applyThinking(body, model, options?.reasoning);
+                const { body: reasoningBody } = applyReasoningToRequest({ api: "openai-completions", model, level: options?.reasoning, body });
                 const headers = mergeHeaders(modelHeaders, config.headers, optionsHeaders);
                 applyRouteCredentialHeaders(headers, routeCredential);
                 lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
                     lockHeader(headers, OPENAI_KEY_HEADER, `Bearer ${apiKey}`);
-                const { body: wire, dropped: extraBodyDropped } = applyExtraBody(body, model.extraBody, OPENAI_RESERVED);
+                const { body: wire, dropped: extraBodyDropped } = applyExtraBody(reasoningBody, model, OPENAI_RESERVED);
                 return {
-                    url: joinRequestUrl(root, "/chat/completions"),
+                    url,
                     headers,
                     body: JSON.stringify(wire),
                     extraBodyDropped,
@@ -406,6 +336,7 @@ export function createOpenAIBrain(given = {}) {
                         routeAdmission();
                         sentMaxTokens = builtMaxTokens;
                         sentMaxTokensLane = builtMaxTokensLane;
+                        sentToolNames = builtToolNames;
                     },
                 };
             },
@@ -577,7 +508,7 @@ export function createOpenAIBrain(given = {}) {
                                 if (tc.id)
                                     acc.id = tc.id;
                                 if (tc.function?.name)
-                                    acc.name = tc.function.name;
+                                    acc.name = sentToolNames.called(tc.function.name);
                                 if (tc.function?.arguments && !acc.closedTc)
                                     acc.args += tc.function.arguments;
                                 toolAccum.set(idx, acc);
@@ -619,7 +550,7 @@ export function createOpenAIBrain(given = {}) {
                             }
                         }
                         if (config.repairTextToolCalls && toolCalls.length === 0 && textFace && context.tools && context.tools.length > 0) {
-                            const names = new Set(context.tools.flatMap((t) => [t.name, ...(t.aliases ?? [])]));
+                            const names = new Set(context.tools.flatMap((t) => [t.name, sentToolNames.sent(t.name), ...(t.aliases ?? [])]));
                             const repaired = repairTextToolCalls(textFace, names);
                             if (repaired.toolCalls.length > 0) {
                                 finalContent.length = 0;
@@ -627,7 +558,8 @@ export function createOpenAIBrain(given = {}) {
                                     finalContent.push({ type: "thinking", thinking: accumReasoning });
                                 if (repaired.cleanedText)
                                     finalContent.push({ type: "text", text: repaired.cleanedText });
-                                for (const tc of repaired.toolCalls) {
+                                for (const repairedCall of repaired.toolCalls) {
+                                    const tc = { ...repairedCall, name: sentToolNames.called(repairedCall.name) };
                                     finalContent.push(tc);
                                     toolCalls.push(tc);
                                 }

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

@@ -1,6 +1,7 @@
 /**
- * The provider dialect table — what each provider endpoint MEANS by the way it fails, declared once per
- * endpoint and read by every seat that reports a provider failure.
+ * The provider dialect table — what each provider endpoint MEANS by the way it fails and by the tool names it is
+ * sent, declared once per endpoint and read by every seat that reports a provider failure or names a tool on the
+ * wire.
  *
  * KEY. An endpoint is named by (wire family, host suffix + path): the same brand can serve two endpoints whose
  * failures read in opposite ways (Moonshot's open platform states an exhausted balance as a 429, its coding
@@ -14,7 +15,9 @@
  * column: rows that turn a status, the envelope's word (`error.code`, else `error.type` — the same word
  * `apiErrorCode` carries) and the envelope's sentence (`error.message`) into one {@link ProviderCondition}. The
  * context-limit refusal is a flag on the same rows (`inputTooLong`), so "this 400 is the input being too long"
- * and "this 400 is something else the provider named" are read off one row and cannot disagree.
+ * and "this 400 is something else the provider named" are read off one row and cannot disagree. `toolNames` is
+ * the tool-name column: names the endpoint gives a meaning of its own on one wire ({@link ToolNameRow}), read by
+ * {@link endpointToolNames} — the one projection every brain sends tool names through and reads call names back by.
  *
  * ONE VERDICT, TWO SEATS. {@link judgeHttpFailure} answers once per failed response; the retry decision, the
  * retry frame (`BrainStatus.providerCondition`) and the terminal (`BrainError` → `AssistantMessage` →
@@ -142,11 +145,24 @@ export interface DialectKey {
     /** A path prefix, matched at a segment boundary. Absent = every path on the host. */
     readonly path?: string;
 }
+/**
+ * One row of the tool-name column. On `wire`, the endpoint treats a tool sent under `name` as a feature of its own
+ * rather than as the tool the request declares, so a tool by that name travels as `sentAs` instead, and a call the
+ * model makes to `sentAs` is a call to `name`. The name inside the engine, the prompts that mention it and the
+ * tool's parameters do not change; only the spelling on this wire does.
+ */
+export interface ToolNameRow {
+    readonly wire: Model["api"];
+    readonly name: string;
+    readonly sentAs: string;
+}
 /** One endpoint's declared dialect: its key and its columns. */
 export interface ProviderDialect {
     readonly name: string;
     readonly key: DialectKey;
     readonly failures: readonly FailureRow[];
+    /** Absent = the endpoint gives no tool name a meaning of its own: every name travels as written. */
+    readonly toolNames?: readonly ToolNameRow[];
 }
 /**
  * The declared dialects. Each row's source is the provider's own error documentation as collected in the
@@ -172,6 +188,26 @@ export declare const GENERIC_FAILURES: readonly FailureRow[];
 export declare function isTransientStatus(status: number): boolean;
 /** The endpoint a request went to, or `undefined` when no dialect declares it. */
 export declare function resolveProviderDialect(url: string, wire: Model["api"]): ProviderDialect | undefined;
+/**
+ * How one request's tool names travel. Both halves read the one set the request declares: `sent` spells a declared
+ * tool's name, in the tool table and in every replayed call to it; `called` reads a call name the model sends back as
+ * the declared tool that travels under it. A name the request does not declare travels and comes back as written —
+ * a replayed call to a tool no longer mounted keeps its name, and a model that calls a tool by the name the prompts
+ * use still reaches it. A brain builds one with each request and keeps the one the engine commits; its parser reads
+ * call names through it.
+ */
+export interface EndpointToolNames {
+    readonly sent: (name: string) => string;
+    readonly called: (sentName: string) => string;
+}
+/** Every name travels as written: the projection of an endpoint whose dialect has no tool-name row on the wire. */
+export declare const NAMES_AS_WRITTEN: EndpointToolNames;
+/**
+ * The tool-name projection of one request: the dialect's rows for this wire, applied to the tools the request
+ * declares. Two declared tools that would travel under one name are refused before anything is sent — the model
+ * could not tell them apart, and neither could the call that comes back.
+ */
+export declare function endpointToolNames(dialect: ProviderDialect | undefined, wire: Model["api"], declared: readonly string[]): EndpointToolNames;
 /** One failure's reading off the table. */
 export interface ProviderVerdict {
     readonly condition: ProviderCondition;

package/dist/brain/provider-dialect.js

@@ -87,6 +87,7 @@ export const PROVIDER_DIALECTS = Object.freeze([
             { status: [429], word: ["1311", "1313"], condition: "stop_other" },
             { status: [400], word: ["1261"], condition: "stop_other", inputTooLong: true },
         ],
+        toolNames: [{ wire: ANTHROPIC, name: "ToolSearch", sentAs: "ToolFinder" }],
     },
     {
         name: "openai",
@@ -120,6 +121,33 @@ export function resolveProviderDialect(url, wire) {
         d.key.hosts.some((h) => host === h || host.endsWith(`.${h}`)) &&
         (d.key.path === undefined || path === d.key.path || path.startsWith(`${d.key.path}/`)));
 }
+export const NAMES_AS_WRITTEN = Object.freeze({ sent: (name) => name, called: (sentName) => sentName });
+export function endpointToolNames(dialect, wire, declared) {
+    const rows = (dialect?.toolNames ?? []).filter((r) => r.wire === wire);
+    if (rows.length === 0)
+        return NAMES_AS_WRITTEN;
+    const sentAs = new Map(rows.map((r) => [r.name, r.sentAs]));
+    const holderOf = new Map();
+    const forward = new Map();
+    const back = new Map();
+    for (const name of new Set(declared)) {
+        const onWire = sentAs.get(name) ?? name;
+        const holder = holderOf.get(onWire);
+        if (holder !== undefined) {
+            const moved = rows.filter((r) => r.sentAs === onWire).map((r) => JSON.stringify(r.name)).join(" / ");
+            const asWritten = [holder, name].find((n) => n === onWire);
+            throw new BrainError("invalid_request", `the request was not sent: the tools ${JSON.stringify(holder)} and ${JSON.stringify(name)} would both travel as ${JSON.stringify(onWire)}. ` +
+                `This endpoint gives the tool name ${moved} a meaning of its own on this wire, so a tool by that name is sent as ${JSON.stringify(onWire)}, ` +
+                `and two tools cannot share one name on the wire — rename ${asWritten === undefined ? "one of them" : `the tool named ${JSON.stringify(asWritten)}`}.`);
+        }
+        holderOf.set(onWire, name);
+        if (onWire !== name) {
+            forward.set(name, onWire);
+            back.set(onWire, name);
+        }
+    }
+    return { sent: (name) => forward.get(name) ?? name, called: (sentName) => back.get(sentName) ?? sentName };
+}
 function statementOf(err) {
     if (err === undefined)
         return undefined;