@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,553 lines • 75.6 kB
text/typescript
import type { IncomingMeta, ProviderAdapter } from "./base";
import { createAdapterTierMetadata, type AdapterTierMetadata } from "../providers/fastwire";
import { ANTHROPIC_FAST_MODE_BETA, mergeAnthropicBetaHeader } from "../providers/anthropic-fast";
import { createToolCallIdAllocator, type ToolCallIdAllocator } from "./tool-call-id";
import { debugDroppedFrame } from "../lib/debug";
import type {
AdapterEvent,
OcxAssistantMessage,
OcxContentPart,
OcxMessage,
OcxParsedRequest,
OcxProviderConfig,
OcxTextContent,
OcxThinkingContent,
OcxToolCall,
OcxToolResultMessage,
OcxUsage,
} from "../types";
import { isAllowedToolChoice, namespacedToolName, resolveToolChoiceWireName, toolChoiceToolPredicate } from "../types";
import { ANTHROPIC_OAUTH_BETA, CLAUDE_CODE_SYSTEM_INSTRUCTION, applyClaudeToolPrefix, stripClaudeToolPrefix } from "../oauth/anthropic";
import { parseDataUrl } from "./image";
import { enforceAnthropicImageLimits } from "./anthropic-image-guard";
import { normalizeAnthropicImages } from "./anthropic-image-normalize";
import { normalizeAnthropicOutputSchema } from "./anthropic-output-schema";
import { stripResponsesOnlyEncryptedMarker } from "./responses-tool-schema";
import { identifyRoutedModel } from "./identity";
import { redactSecretString } from "../lib/redact";
import { CLAUDE_CODE_HEADERS, claudeCodeSessionId } from "./client-fingerprint";
import { buildNonOpenAIToolCatalogNudgeForTools } from "./tool-catalog-nudge";
import { decodeServerSentEvents } from "../lib/sse-decoder";
import { isTranslatorBudgetExceededError, retainTranslatedEventBatch, type TranslatorBudget } from "../lib/translator-budget";
import { isReasoningEffortOmitted, modelRecordValue } from "../reasoning-effort";
import { applyAgentRouterLanguageFraming, isAgentRouterEndpoint } from "./agentrouter";
import { rejectsCombinedSampling, rejectsForcedToolChoice, rejectsSamplingParameters, supportsExplicitThinkingDisable, usesAdaptiveThinking, usesBetweenToolsFloor } from "./anthropic-model-contract";
/** Map a user content part to an Anthropic content block (text or image source). */
function toAnthropicContentPart(p: OcxContentPart): unknown {
if (p.type === "image") {
const data = parseDataUrl(p.imageUrl);
return data
? { type: "image", source: { type: "base64", media_type: data.mediaType, data: data.base64 } }
: { type: "image", source: { type: "url", url: p.imageUrl } };
}
if (p.type === "video") return { type: "text", text: "[video]" };
// The block the caller sent, rebuilt. A Messages-to-Messages route used to reduce it to its
// title before any adapter ran, so the model was told a document existed rather than given
// one, and the answer came back looking the same (#5212).
if (p.type === "document") {
return {
type: "document",
source: { type: "base64", media_type: p.mediaType, data: p.data },
...(p.filename !== undefined ? { title: p.filename } : {}),
};
}
return { type: "text", text: p.text };
}
/** Default `max_tokens` when Codex omits `max_output_tokens`. */
const DEFAULT_MAX_TOKENS = 8192;
/** Safe ceiling for `max_tokens` (thinking + visible output) across current Claude 4.x models. */
const REASONING_MAX_TOKENS_CEILING = 32_000;
/** Adaptive-thinking ceiling: max effort budget (32k) + OUTPUT_HEADROOM (8k).
* Must exceed REASONING_MAX_TOKENS_CEILING so effort=max actually preserves visible-output room. */
const ADAPTIVE_THINKING_CEILING = 40_192;
/** Anthropic's documented minimum `thinking.budget_tokens`. */
const MIN_THINKING_BUDGET = 1024;
/** Visible-output room added above the thinking budget when sizing `max_tokens`. */
const OUTPUT_HEADROOM = 8192;
/** Minimum visible-output room kept below `max_tokens` (so `max_tokens > budget_tokens` always holds). */
const OUTPUT_FLOOR = 4096;
const COMPAT_TOOL_PREFIX = "cx_";
type CacheControl = { type: "ephemeral"; ttl?: "1h" | "5m" };
const MAX_CACHE_BREAKPOINTS = 4;
function resolveCacheControl(retention: "none" | "short" | "long" | undefined): CacheControl | undefined {
const r = retention ?? "short";
if (r === "none") return undefined;
return r === "long" ? { type: "ephemeral", ttl: "1h" } : { type: "ephemeral" };
}
// ---------------------------------------------------------------------------
// Prompt-caching breakpoint placement (ported from jawcode)
//
// Strategy: place cache_control breakpoints on up to 4 locations in order
// of stability (most stable first), so Anthropic's cumulative prefix cuts
// maximise cache hits across turns:
// 1. tools (last block) — changes rarely
// 2. system (last block) — changes rarely
// 3. penultimate user message — stable across the current turn
// 4. last user message — the new turn's content
// ---------------------------------------------------------------------------
function applyCacheControlToLast<T extends Record<string, unknown>>(blocks: T[], cc: CacheControl): void {
if (blocks.length === 0) return;
const i = blocks.length - 1;
blocks[i] = { ...blocks[i], cache_control: cc };
}
function applyCacheControlToLastText(blocks: Array<Record<string, unknown>>, cc: CacheControl): void {
for (let i = blocks.length - 1; i >= 0; i--) {
if (blocks[i].type === "text") {
blocks[i] = { ...blocks[i], cache_control: cc };
return;
}
}
applyCacheControlToLast(blocks, cc);
}
type PromptCachingOptions = {
maxExplicitBreakpoints?: number;
skipLastUser?: boolean;
};
/** Place explicit cache_control breakpoints on the built Anthropic body. */
function applyPromptCaching(
body: Record<string, unknown>,
cc: CacheControl | undefined,
options: PromptCachingOptions = {},
): void {
if (!cc) return;
const explicitLimit = options.maxExplicitBreakpoints ?? MAX_CACHE_BREAKPOINTS;
if (explicitLimit <= 0) return;
const messages = body.messages as Array<Record<string, unknown>> | undefined;
// Skip if external breakpoints are already present on messages.
if (messages) {
for (const msg of messages) {
if (Array.isArray(msg.content)) {
if ((msg.content as Array<Record<string, unknown>>).some(b => b.cache_control != null)) return;
}
}
}
let used = 0;
// 1. tools
const tools = body.tools as Array<Record<string, unknown>> | undefined;
if (tools && tools.length > 0) {
applyCacheControlToLast(tools, cc);
used++;
}
if (used >= explicitLimit) return;
// 2. system
const system = body.system as Array<Record<string, unknown>> | undefined;
if (system && system.length > 0) {
applyCacheControlToLast(system, cc);
used++;
}
if (used >= explicitLimit || !messages) return;
// Locate user-role message indexes.
const userIdxs: number[] = [];
for (let i = 0; i < messages.length; i++) {
if (messages[i].role === "user") userIdxs.push(i);
}
// 3. penultimate user message
if (userIdxs.length >= 2) {
const msg = messages[userIdxs[userIdxs.length - 2]];
if (typeof msg.content === "string") {
msg.content = [{ type: "text", text: msg.content, cache_control: cc }];
} else if (Array.isArray(msg.content) && msg.content.length > 0) {
applyCacheControlToLastText(msg.content as Array<Record<string, unknown>>, cc);
}
used++;
}
if (used >= explicitLimit || options.skipLastUser) return;
// 4. last user message
if (userIdxs.length >= 1) {
const msg = messages[userIdxs[userIdxs.length - 1]];
if (typeof msg.content === "string") {
msg.content = [{ type: "text", text: msg.content, cache_control: cc }];
} else if (Array.isArray(msg.content) && msg.content.length > 0) {
applyCacheControlToLastText(msg.content as Array<Record<string, unknown>>, cc);
}
}
}
/**
* The fast-mode wire this request should carry, if any. Only a settled `set` decision on a
* declared `anthropic-speed` wire emits it, and only with the value that wire maps canonical
* Fast to; everything else (drop, forwarded caller tiers, a declaration for another wire)
* sends no `speed`, which is the API's standard speed.
*/
function anthropicFastSpeed(
parsed: OcxParsedRequest,
provider: OcxProviderConfig,
): { value: string; betas: readonly string[] } | undefined {
const decision = parsed.options.tierDecision;
if (decision?.kind !== "set") return undefined;
const wire = parsed.options.tierObservation?.fastWire ?? provider.fastWire ?? null;
if (wire?.kind !== "anthropic-speed") return undefined;
if (decision.value !== wire.canonicalToWire.priority) return undefined;
return { value: decision.value, betas: wire.betas?.length ? wire.betas : [ANTHROPIC_FAST_MODE_BETA] };
}
/** Feed a `usage.speed` echo ("fast" | "standard") to the attempt's tier observer. */
function observeAnthropicSpeed(usage: unknown, tierMetadata: AdapterTierMetadata | undefined): void {
if (!tierMetadata || !usage || typeof usage !== "object" || Array.isArray(usage)) return;
const speed = (usage as { speed?: unknown }).speed;
if (speed !== undefined) tierMetadata.observeResponseServiceTier(speed);
}
// ---------------------------------------------------------------------------
// Breakpoint cap enforcement — strip excess beyond the 4-breakpoint limit
// ---------------------------------------------------------------------------
function countBreakpoints(body: Record<string, unknown>): number {
let total = 0;
const count = (blocks: Array<Record<string, unknown>> | undefined) => {
if (!blocks) return;
for (const b of blocks) if (b.cache_control) total++;
};
count(body.tools as Array<Record<string, unknown>> | undefined);
count(body.system as Array<Record<string, unknown>> | undefined);
const messages = body.messages as Array<Record<string, unknown>> | undefined;
if (messages) {
for (const msg of messages) {
if (Array.isArray(msg.content)) count(msg.content as Array<Record<string, unknown>>);
}
}
return total;
}
function enforceCacheControlLimit(body: Record<string, unknown>, limit = MAX_CACHE_BREAKPOINTS): void {
const total = countBreakpoints(body);
if (total <= limit) return;
let excess = total - limit;
// Strip from messages first (least stable), then system, then tools.
const messages = body.messages as Array<Record<string, unknown>> | undefined;
if (messages) {
for (const msg of messages) {
if (excess <= 0) break;
if (!Array.isArray(msg.content)) continue;
for (const block of msg.content as Array<Record<string, unknown>>) {
if (excess <= 0) break;
if (block.cache_control) { delete block.cache_control; excess--; }
}
}
}
const stripBlocks = (blocks: Array<Record<string, unknown>> | undefined) => {
if (!blocks) return;
for (const b of blocks) {
if (excess <= 0) break;
if (b.cache_control) { delete b.cache_control; excess--; }
}
};
if (excess > 0) stripBlocks(body.system as Array<Record<string, unknown>> | undefined);
if (excess > 0) stripBlocks(body.tools as Array<Record<string, unknown>> | undefined);
}
// ---------------------------------------------------------------------------
// TTL ordering — Anthropic requires 1-hour breakpoints before 5-minute ones
// ---------------------------------------------------------------------------
function normalizeTtlOrdering(body: Record<string, unknown>): void {
const allBlocks: Array<Record<string, unknown>> = [];
const collect = (blocks: Array<Record<string, unknown>> | undefined) => {
if (!blocks) return;
for (const b of blocks) if (b.cache_control) allBlocks.push(b);
};
collect(body.tools as Array<Record<string, unknown>> | undefined);
collect(body.system as Array<Record<string, unknown>> | undefined);
const messages = body.messages as Array<Record<string, unknown>> | undefined;
if (messages) {
for (const msg of messages) {
if (Array.isArray(msg.content)) collect(msg.content as Array<Record<string, unknown>>);
}
}
// Walk forward: once we see a 5-min (no ttl / ttl:"5m"), any subsequent 1h must be demoted.
let seenShort = false;
for (const b of allBlocks) {
const cc = b.cache_control as CacheControl;
if (cc.ttl !== "1h") {
seenShort = true;
} else if (seenShort) {
// 1h after a short → demote to default (5m)
delete cc.ttl;
}
}
}
function isLikelyRealAnthropicThinkingSignature(signature: string | undefined): signature is string {
if (typeof signature !== "string" || signature.length < 16) return false;
if (/^(fc|call|msg|rs|resp|reasoning|item|ws|tool|func|function)[-_]/i.test(signature)) return false;
return /^[A-Za-z0-9+/_=-]+$/.test(signature);
}
/**
* Bridge error fidelity (web-search/images loops): extract a display-safe summary from an
* Anthropic JSON error envelope so `Provider error <status>` carries the upstream reason.
* JSON-only extraction — HTML/non-JSON bodies yield "" so raw markup is never echoed.
*/
export function formatAnthropicErrorBody(status: number, _headers: Headers, payloadText: string): string {
let parsed: unknown;
try {
parsed = JSON.parse(payloadText);
} catch {
return "";
}
const detail = extractAnthropicErrorDetail(parsed);
if (!detail) return "";
return redactSecretString(detail).slice(0, 400);
}
function isAnthropicContentFilterStopReason(
stopReason: string | undefined,
): stopReason is "refusal" | "content_filter" {
return stopReason === "refusal" || stopReason === "content_filter";
}
/**
* Anthropic `refusal` / `content_filter` is a permanent sampling decision, not a disconnect.
* Emitting `done` with that stopReason used to surface as `response.incomplete` without
* `retryable`, which Codex treats as a dropped stream and retries five times (#4312).
* The explicit incomplete event is what the bridge already forwards into
* `incomplete_details.retryable`. Usage is preserved: a filtered turn still consumed tokens.
* `max_tokens` stays a `done` so the client can continue from a legitimate truncation.
*/
function anthropicContentFilterIncomplete(
stopReason: string,
usage: OcxUsage | undefined,
): Extract<AdapterEvent, { type: "incomplete" }> {
return {
type: "incomplete",
reason: "content_filter",
retryable: false,
message: `upstream ended the turn with stop_reason "${stopReason}"`,
usage,
};
}
function isAnthropicRecord(value: unknown): value is Record<string, unknown> {
return value !== null && typeof value === "object" && !Array.isArray(value);
}
function anthropicStructuralValueType(value: unknown): string {
if (value === null) return "null";
return Array.isArray(value) ? "array" : typeof value;
}
interface InvalidAnthropicShapeDiagnostic {
reason: "content_not_array" | "content_block_not_object";
blockIndex?: number;
valueType: string;
}
/**
* Structured refusal for a malformed buffered response body, shaped like the google adapter's
* `invalidGoogleShapeEvent` so an operator reading a log can tell which rung failed: the content
* container, or one block inside an otherwise well-formed container.
*/
function invalidAnthropicShapeEvent(
diagnostic: InvalidAnthropicShapeDiagnostic,
): Extract<AdapterEvent, { type: "error" }> {
const at = diagnostic.blockIndex !== undefined ? `; blockIndex=${diagnostic.blockIndex}` : "";
const subject = diagnostic.reason === "content_not_array" ? "content" : "content block";
return {
type: "error",
message: `anthropic response contained invalid ${subject} (${diagnostic.reason}${at}; valueType=${diagnostic.valueType})`,
status: 502,
errorType: "upstream_error",
};
}
function extractAnthropicErrorDetail(parsed: unknown): string | undefined {
if (typeof parsed === "string") return parsed.trim() || undefined;
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
const obj = parsed as Record<string, unknown>;
// Anthropic envelope: { type: "error", error: { type, message } }; tolerate a bare
// { error: { message } } and a string error field.
const err = obj.error;
if (typeof err === "string" && err.trim()) return err.trim();
if (err !== null && typeof err === "object" && !Array.isArray(err)) {
const e = err as Record<string, unknown>;
const msg = e.message;
if (typeof msg !== "string" || !msg.trim()) return undefined;
const type = e.type;
return typeof type === "string" && type.trim()
? `${type.trim()}: ${msg.trim()}`
: msg.trim();
}
return undefined;
}
function usesNativeAnthropicEndpoint(provider: OcxProviderConfig): boolean {
try {
return new URL(provider.baseUrl).hostname === "api.anthropic.com";
} catch {
throw new Error(`anthropic provider has malformed baseUrl: ${provider.baseUrl}`);
}
}
/** Normalize provider baseUrl paths ending in `/`, `/v1`, or `/v1/messages` to `{origin}/v1/messages`. */
export function anthropicMessagesUrl(baseUrl: string): string {
try {
new URL(baseUrl);
} catch {
throw new Error(`anthropic provider has malformed baseUrl: ${baseUrl}`);
}
const trimmed = baseUrl.trim().replace(/\/+$/, "");
const root = trimmed.replace(/\/v1\/messages\/?$/i, "").replace(/\/v1\/?$/i, "").replace(/\/+$/, "");
return `${root}/v1/messages`;
}
function synthesizeToolUseId(): string {
return `toolu_${crypto.randomUUID().replace(/-/g, "").slice(0, 24)}`;
}
/**
* A tool_use id that a client can actually echo back. `??` only catches a missing
* field, so an Anthropic-compatible relay that sends `""` or `" "` produced a
* call whose id round-trips as blank — the next turn then cannot pair the result
* with its call. Treat blank as absent and synthesize (#765).
*/
function usableToolUseId(id: unknown): string {
return typeof id === "string" && id.trim() ? id : synthesizeToolUseId();
}
/**
* Bound repair for a malformed tool-arguments string under the compatibility profile (#658):
* a gateway such as AgentRouter can concatenate JSON objects (`{}{"value":42}`). Find the
* last parseable JSON object by scanning suffixes from each object-open brace and prefixes
* ending at each object-close brace. Both scans walk backwards from the end trying at most
* `maxCandidates` positions, so no offset index is ever materialized: a brace-dense hostile
* input costs at most 2 × maxCandidates bounded JSON.parse attempts and no extra storage.
* Inputs above MAX_REPAIRABLE_TOOL_ARGUMENT_BYTES are not repaired at all.
*/
const MAX_REPAIRABLE_TOOL_ARGUMENT_BYTES = 1024 * 1024;
/**
* Whether `input` encodes to more than `max` UTF-8 bytes, with an early exit so the check
* itself never allocates a copy of a hostile string. `string.length` counts UTF-16 code
* units, which undercounts astral text by 2x against a byte budget.
*/
function utf8BytesExceed(input: string, max: number): boolean {
let bytes = 0;
for (let i = 0; i < input.length; i++) {
const code = input.charCodeAt(i);
if (code < 0x80) bytes += 1;
else if (code < 0x800) bytes += 2;
else if (code >= 0xd800 && code <= 0xdbff && i + 1 < input.length
&& input.charCodeAt(i + 1) >= 0xdc00 && input.charCodeAt(i + 1) <= 0xdfff) {
// A complete surrogate pair is one 4-byte scalar. Anything else — a high surrogate
// followed by another high surrogate or a non-surrogate — encodes as two separate
// U+FFFD replacements, so the next unit must NOT be skipped.
bytes += 4;
i++;
} else bytes += 3; // lone surrogates encode as U+FFFD (3 bytes)
if (bytes > max) return true;
}
return false;
}
function lastValidJsonObject(input: string, maxCandidates: number): string | undefined {
const tryParseObject = (candidate: string): string | undefined => {
try {
const parsed = JSON.parse(candidate) as unknown;
if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return candidate;
} catch { /* keep scanning */ }
return undefined;
};
let scanFrom = input.length - 1;
for (let tried = 0; tried < maxCandidates && scanFrom >= 0; tried++) {
const open = input.lastIndexOf("{", scanFrom);
if (open === -1) break;
const repaired = tryParseObject(input.slice(open));
if (repaired !== undefined) return repaired;
scanFrom = open - 1;
}
scanFrom = input.length - 1;
for (let tried = 0; tried < maxCandidates && scanFrom >= 0; tried++) {
const close = input.lastIndexOf("}", scanFrom);
if (close === -1) break;
const repaired = tryParseObject(input.slice(0, close + 1));
if (repaired !== undefined) return repaired;
scanFrom = close - 1;
}
return undefined;
}
function toolUseArguments(input: unknown, lenient = false): string {
if (typeof input === "string") {
const trimmed = input.trim();
if (!trimmed) return "{}";
try {
JSON.parse(trimmed);
return trimmed;
} catch {
if (lenient && !utf8BytesExceed(trimmed, MAX_REPAIRABLE_TOOL_ARGUMENT_BYTES)) {
const repaired = lastValidJsonObject(trimmed, 32);
if (repaired !== undefined) return repaired;
}
// A tool call's arguments must be a JSON object. Re-encoding an unparseable string as a
// JSON *string* is the double-encoding #765 reports: the caller then receives
// `"get weather"` where an object was required and the tool call is unusable either way.
// An empty object at least fails in the tool's own argument validation.
return "{}";
}
}
return JSON.stringify(input ?? {});
}
/**
* Whether arguments assembled from a stream's `input_json_delta` fragments are usable.
* A tool block that sent no fragments at all is fine — that is a no-argument call. Anything
* else has to parse, because unlike the non-stream path the fragments have already been
* forwarded to the client and cannot be repaired after the fact.
*/
function streamedToolArgumentsParse(assembled: string): boolean {
const trimmed = assembled.trim();
if (!trimmed) return true;
try {
JSON.parse(trimmed);
return true;
} catch {
return false;
}
}
function anthropicKeyUsesBearer(provider: OcxProviderConfig): boolean {
return provider.apiKeyTransport === "bearer";
}
/** The `anthropic-version` every Messages request from this proxy pins. */
export const ANTHROPIC_API_VERSION = "2023-06-01";
/**
* The fixed headers of every Messages request this proxy builds, before credentials. Shared by
* the adapter and the managed native lane so both pin the same version and client identity.
*/
export function anthropicBaseRequestHeaders(stream: boolean | undefined): Record<string, string> {
return {
"Content-Type": "application/json",
"anthropic-version": ANTHROPIC_API_VERSION,
"Accept": stream ? "text/event-stream" : "application/json",
"User-Agent": "@anthropic-ai/sdk/0.74.0",
};
}
/** Key-auth credential placement: `x-api-key`, or a bearer when the provider asks for one. */
export function applyAnthropicKeyAuth(headers: Record<string, string>, provider: OcxProviderConfig): void {
if (typeof provider.apiKey !== "string") return;
if (anthropicKeyUsesBearer(provider)) headers["Authorization"] = `Bearer ${provider.apiKey}`;
else headers["x-api-key"] = provider.apiKey;
}
/**
* OAuth (Claude Pro/Max) credential placement: the bearer, the OAuth beta pair and the Claude
* Code client fingerprint. Shared by the adapter and the managed native lane.
*/
export function applyAnthropicOAuthAuth(headers: Record<string, string>, accessToken: string): void {
headers["Authorization"] = `Bearer ${accessToken}`;
headers["anthropic-beta"] = ANTHROPIC_OAUTH_BETA;
// Match the real Claude Code CLI request fingerprint: a valid OAuth token with an empty
// header set is a non-first-party signature. (cch billing-header signing is intentionally
// out of scope — brittle and version-coupled.)
Object.assign(headers, CLAUDE_CODE_HEADERS);
headers["X-Claude-Code-Session-Id"] = claudeCodeSessionId(accessToken);
headers["x-client-request-id"] = crypto.randomUUID();
}
/** The provider's Messages endpoint, refusing a base URL with an unresolved `{placeholder}`. */
export function resolveAnthropicMessagesUrl(provider: Pick<OcxProviderConfig, "baseUrl">): string {
const url = anthropicMessagesUrl(provider.baseUrl);
// indexOf instead of a regex: \{[^}]*\} is quadratic on brace-only input (CodeQL js/polynomial-redos).
const openBrace = url.indexOf("{");
const closeBrace = openBrace === -1 ? -1 : url.indexOf("}", openBrace);
const unresolvedPlaceholder = closeBrace === -1 ? undefined : url.slice(openBrace, closeBrace + 1);
if (unresolvedPlaceholder) {
throw new Error(`anthropic baseUrl contains unresolved ${unresolvedPlaceholder}`);
}
return url;
}
/** Map a Responses reasoning effort to an Anthropic extended-thinking budget (tokens, >= 1024). */
function reasoningBudget(effort: string): number {
switch (effort) {
case "minimal": return 1024;
case "low": return 4096;
case "high": return 16384;
case "xhigh": return 24576;
case "max": return 32000;
case "medium":
default: return 8192;
}
}
/** `output_config.effort` accepts low|medium|high|xhigh|max — "minimal" is rejected with a 400. */
function adaptiveEffort(effort: string): string {
return effort === "minimal" ? "low" : effort;
}
function defaultReasoningEffort(provider: OcxProviderConfig, modelId: string): string | undefined {
const value = modelRecordValue(provider.modelDefaultReasoningEfforts, modelId);
if (typeof value !== "string") return undefined;
const trimmed = value.trim();
// `__omit__` means "send no reasoning field", not "an effort literally named
// __omit__". Without this the sentinel reached the wire as
// `output_config.effort: "__omit__"` on adaptive models, and enabled budget
// thinking on the rest — the opposite of what it asks for (#2432).
if (!trimmed || isReasoningEffortOmitted(trimmed)) return undefined;
return trimmed;
}
function usageFromAnthropic(usage: unknown): OcxUsage | undefined {
if (!isAnthropicRecord(usage)) return undefined;
const tokens = (key: string): number | undefined => {
const value = usage[key];
if (value === undefined) return 0;
return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
};
const input = tokens("input_tokens");
const output = tokens("output_tokens");
const read = tokens("cache_read_input_tokens");
const write = tokens("cache_creation_input_tokens");
// Invalid upstream usage is unreported, not a measured zero or a string that
// can pass through aggregation into a human-readable usage report.
if (input === undefined || output === undefined || read === undefined || write === undefined) return undefined;
const hasCache = usage.cache_read_input_tokens !== undefined || usage.cache_creation_input_tokens !== undefined;
// Anthropic reports input_tokens EXCLUSIVE of cache read/write; normalize to the
// canonical inclusive convention (types.ts OcxUsage / devlog 070).
const inputTokens = input + read + write;
if (!Number.isFinite(inputTokens)) return undefined;
return {
inputTokens,
outputTokens: output,
...(hasCache ? {
cachedInputTokens: read,
cacheReadInputTokens: read,
cacheCreationInputTokens: write,
} : {}),
};
}
type PendingAnthropicUsage = Record<string, unknown> | null | undefined;
function mergeAnthropicUsage(base: PendingAnthropicUsage, next: unknown): PendingAnthropicUsage {
// null remembers an invalid observation. A later partial cumulative frame
// cannot re-establish the missing totals, while an absent update changes nothing.
if (base === null) return null;
if (next === undefined) return base;
if (!isAnthropicRecord(next)) return null;
// Anthropic `message_delta.usage` values are CUMULATIVE; adding them to the
// message_start snapshot double-counted output tokens. Later frames win per key.
const merged = { ...base, ...next };
return usageFromAnthropic(merged) === undefined ? null : merged;
}
function buildToolNameTransforms(provider: OcxProviderConfig): { toWire: (name: string) => string; fromWire: (name: string) => string } {
if (provider.authMode === "oauth") {
return { toWire: applyClaudeToolPrefix, fromWire: stripClaudeToolPrefix };
}
if (provider.escapeBuiltinToolNames === true) {
return {
toWire: (name) => name.startsWith(COMPAT_TOOL_PREFIX) ? name : COMPAT_TOOL_PREFIX + name,
fromWire: (name) => name.startsWith(COMPAT_TOOL_PREFIX) ? name.slice(COMPAT_TOOL_PREFIX.length) : name,
};
}
return { toWire: (name) => name, fromWire: (name) => name };
}
function toAnthropicToolResult(msg: OcxToolResultMessage, wireCallId: string): Record<string, unknown> {
// Anthropic tool_result accepts a string OR content blocks — render images natively
// (e.g. Codex view_image output) instead of dropping them.
let content: string | unknown[];
if (typeof msg.content === "string") {
// Anthropic rejects tool_result with empty text content blocks.
content = msg.content || "(empty tool output)";
} else {
const parts = (msg.content as OcxContentPart[])
.map(toAnthropicContentPart)
.filter(p => !((p as { type?: string }).type === "text" && !(p as { text?: string }).text));
content = parts.length > 0 ? parts : "(empty tool output)";
}
return {
type: "tool_result",
tool_use_id: wireCallId,
content,
...(msg.isError ? { is_error: true } : {}),
};
}
function unrepresentableToolCallText(tc: OcxToolCall, wireName: string): string {
const args = typeof tc.arguments === "string" ? tc.arguments : JSON.stringify(tc.arguments);
return `[tool_use without a usable id: ${wireName}]\n${args}`;
}
function orphanToolResultText(msg: OcxToolResultMessage): string {
const label = msg.toolName ? `${msg.toolName} (${msg.toolCallId})` : msg.toolCallId;
const content = typeof msg.content === "string"
? msg.content
: JSON.stringify(msg.content);
return `[tool_result without adjacent tool_use: ${label}]\n${content}`;
}
function orphanToolResultContent(msg: OcxToolResultMessage): string | unknown[] {
if (typeof msg.content === "string" || !msg.content.some(p => p.type === "image")) {
return orphanToolResultText(msg);
}
const label = msg.toolName ? `${msg.toolName} (${msg.toolCallId})` : msg.toolCallId;
return [
{ type: "text", text: `[tool_result without adjacent tool_use: ${label}]` },
...msg.content
.map(toAnthropicContentPart)
.filter(p => !((p as { type?: string }).type === "text" && !(p as { text?: string }).text)),
];
}
/**
* AgentRouter answers 400 `content-blocked` when the first user message is not in English
* (#2074), while the same request in English returns 200. The gateway is inspecting the opening
* user content, so an Anthropic `system` string cannot reach it — the framing has to sit in the
* first user turn.
*/
function messagesToAnthropicFormat(
parsed: OcxParsedRequest,
toolNames: { toWire: (name: string) => string },
): { system: string | undefined; messages: unknown[] } {
// One allocator for the whole request: a tool_result must resolve to the SAME wire id its
// call got, and two distinct raw ids must never collapse into one. Conforming ids are claimed
// first so a rewritten id can never squat on an id another call legitimately owns.
const callIds = createToolCallIdAllocator();
for (const message of parsed.context.messages) {
if (message.role === "assistant") {
for (const part of (message as OcxAssistantMessage).content) {
if (part.type === "toolCall") callIds.reserve((part as OcxToolCall).id);
}
} else if (message.role === "toolResult") {
callIds.reserve((message as OcxToolResultMessage).toolCallId);
}
}
const toolCatalogNudge = buildNonOpenAIToolCatalogNudgeForTools(
parsed.context.tools,
parsed.options.toolChoice,
tool => toolNames.toWire(namespacedToolName(tool.namespace, tool.name)),
);
const systemParts = [...(parsed.context.systemPrompt ?? []), ...(toolCatalogNudge ? [toolCatalogNudge] : [])];
const system = systemParts.length
? identifyRoutedModel(systemParts.join("\n\n"), parsed.modelId) || undefined
: undefined;
const messages: unknown[] = [];
for (let i = 0; i < parsed.context.messages.length; i++) {
const msg = parsed.context.messages[i];
switch (msg.role) {
case "user":
case "developer": {
let content: string | unknown[];
if (typeof msg.content === "string") {
// Anthropic rejects empty string text content blocks.
content = msg.content || "(empty)";
} else {
const parts = (msg.content as OcxContentPart[])
.map(toAnthropicContentPart)
.filter(p => !((p as { type?: string }).type === "text" && !(p as { text?: string }).text));
content = parts.length > 0 ? parts : "(empty)";
}
messages.push({ role: "user", content });
break;
}
case "assistant": {
const aMsg = msg as OcxAssistantMessage;
const preface: unknown[] = [];
const toolUses: unknown[] = [];
const toolUseIds: string[] = [];
for (const part of aMsg.content) {
if (part.type === "text") {
const text = (part as OcxTextContent).text;
if (text) preface.push({ type: "text", text });
} else if (part.type === "thinking") {
const t = part as OcxThinkingContent;
// History minted under another serving identity (or already rejected as opaque) is not
// this destination's to verify: drop its opaque blocks, as the Responses passthrough does.
if (parsed._stripReasoningEncryptedContent === true) continue;
// Redacted blocks replay verbatim FIRST (they preceded the visible thinking block
// in the original stream order preserved by the bridge envelope).
for (const data of t.redacted ?? []) {
preface.push({ type: "redacted_thinking", data });
}
if (isLikelyRealAnthropicThinkingSignature(t.signature)) {
preface.push({ type: "thinking", thinking: t.thinking, signature: t.signature });
}
} else if (part.type === "toolCall") {
const tc = part as OcxToolCall;
const flatName = namespacedToolName(tc.namespace, tc.name);
// Normalized here, and identically for the matching tool_result above, so a history
// replayed from another provider path keeps its call/result pairing (#1767).
// No raw fallback: restoring an empty/unusable id puts a value on the wire Anthropic
// rejects. An unrepresentable call becomes text instead, and its result follows it there.
const wireCallId = callIds.allocate(tc.id);
if (wireCallId === undefined) {
preface.push({ type: "text", text: unrepresentableToolCallText(tc, toolNames.toWire(flatName)) });
continue;
}
toolUseIds.push(wireCallId);
toolUses.push({ type: "tool_use", id: wireCallId, name: toolNames.toWire(flatName), input: tc.arguments });
}
}
// Anthropic treats text/thinking after tool_use as ending the tool turn, which makes
// earlier tool_use ids look unpaired (#620 / common multi-step history shape).
const content = [...preface, ...toolUses];
if (content.length === 0) break;
messages.push({ role: "assistant", content });
if (toolUseIds.length > 0) {
const requiredIds = new Set(toolUseIds);
const resultBlocks: Record<string, unknown>[] = [];
const orphanBlocks: unknown[] = [];
const seen = new Set<string>();
let j = i + 1;
while (j < parsed.context.messages.length && parsed.context.messages[j].role === "toolResult") {
const tr = parsed.context.messages[j] as OcxToolResultMessage;
// Match on the WIRE id. requiredIds holds normalized ids, so comparing the raw result id
// made every rewritten pair lose its result to orphan text and gain a synthetic
// missing-result block. lookup() never mints an id: a result with no call stays orphan.
const wireResultId = callIds.lookup(tr.toolCallId);
if (wireResultId !== undefined && requiredIds.has(wireResultId) && !seen.has(wireResultId)) {
resultBlocks.push(toAnthropicToolResult(tr, wireResultId));
seen.add(wireResultId);
} else {
const orphan = orphanToolResultContent(tr);
orphanBlocks.push(...(typeof orphan === "string" ? [{ type: "text", text: orphan }] : orphan));
}
j++;
}
for (const id of toolUseIds) {
if (!seen.has(id)) {
resultBlocks.push({
type: "tool_result",
tool_use_id: id,
content: "[missing tool_result for this tool_use in history]",
is_error: true,
});
}
}
messages.push({ role: "user", content: [...resultBlocks, ...orphanBlocks] });
i = j - 1;
}
break;
}
case "toolResult": {
// A standalone Anthropic tool_result is invalid unless it immediately follows an
// assistant tool_use. Preserve text and images as user content without fabricating a pairing.
messages.push({ role: "user", content: orphanToolResultContent(msg as OcxToolResultMessage) });
break;
}
}
}
// Newer Anthropic models reject assistant-tail histories as prefill:
// "This model does not support assistant message prefill. The conversation must end with a user message."
// previous_response_id expansion with empty new input, interrupted-turn replay, and web-search sidecar
// first iterations can all reach this; Kiro uses the same "(continue)" nudge precedent (src/adapters/kiro.ts:283).
if (messages.length === 0) {
messages.push({ role: "user", content: "(continue)" });
} else if ((messages[messages.length - 1] as { role?: string }).role === "assistant") {
messages.push({ role: "user", content: "(continue)" });
}
return { system, messages };
}
function toolsToAnthropicFormat(parsed: OcxParsedRequest, toolNames: { toWire: (name: string) => string }): unknown[] | undefined {
if (!parsed.context.tools || parsed.context.tools.length === 0) return undefined;
const tools = isAllowedToolChoice(parsed.options.toolChoice)
? parsed.context.tools.filter(toolChoiceToolPredicate(parsed.options.toolChoice, parsed.context.tools))
: parsed.context.tools;
if (tools.length === 0) return undefined;
const converted = tools.map(t => ({
name: toolNames.toWire(namespacedToolName(t.namespace, t.name)),
description: t.description,
input_schema: normalizeAnthropicInputSchema(t.parameters),
// Anthropic is the target that DEFINES both of these, and both were dropped while the
// OpenAI Chat adapter already forwarded strict (#5210). Only an explicit `true` is
// emitted: the Messages inbound records an absent strict as `false`, so a false here
// cannot be distinguished from silence and must not become an opt-out on the wire.
...(t.strict === true ? { strict: true } : {}),
...(t.allowedCallers !== undefined ? { allowed_callers: [...t.allowedCallers] } : {}),
}));
return converted;
}
function normalizeAnthropicInputSchema(schema: unknown): Record<string, unknown> {
const stripped = stripResponsesOnlyEncryptedMarker(schema);
const obj = stripped && typeof stripped === "object" && !Array.isArray(stripped)
? stripped as Record<string, unknown>
: {};
// Anthropic rejects root-level missing type and oneOf/anyOf/allOf in input_schema.
// Normalize the root only: ensure type:"object" + properties, flatten root composition
// while preserving nested schemas. Mirrors kiro-tools.ts ensureRootObjectType.
// Known limitation: Object.assign on branch properties means later branches overwrite
// earlier ones when the same property name appears with different schemas.
const compositionKeys = ["oneOf", "anyOf", "allOf"] as const;
const hasRootComposition = compositionKeys.some(key => Array.isArray(obj[key]));
const type = obj.type;
const rootObjectType = type === "object" || (Array.isArray(type) && type.includes("object"));
if (!hasRootComposition) {
const normalized: Record<string, unknown> = rootObjectType && type === "object"
? { ...obj }
: { ...obj, type: "object" };
if (normalized.properties === undefined || normalized.properties === null) {
normalized.properties = {};
}
return normalized;
}
const properties: Record<string, unknown> = {};
const required = new Set<string>();
if (obj.properties && typeof obj.properties === "object" && !Array.isArray(obj.properties)) {
Object.assign(properties, obj.properties as Record<string, unknown>);
}
if (Array.isArray(obj.required)) {
for (const item of obj.required) if (typeof item === "string") required.add(item);
}
for (const key of compositionKeys) {
const variants = obj[key];
if (!Array.isArray(variants)) continue;
const mergeRequired = key === "allOf";
for (const variant of variants) {
if (!variant || typeof variant !== "object" || Array.isArray(variant)) continue;
const v = variant as Record<string, unknown>;
if (v.properties && typeof v.properties === "object" && !Array.isArray(v.properties)) {
Object.assign(properties, v.properties as Record<string, unknown>);
}
if (mergeRequired && Array.isArray(v.required)) {
for (const item of v.required) if (typeof item === "string") required.add(item);
}
}
}
const normalized: Record<string, unknown> = {};
for (const [key, value] of Object.entries(obj)) {
if (key === "oneOf" || key === "anyOf" || key === "allOf") continue;
if (key === "type" || key === "properties" || key === "required") continue;
normalized[key] = value;
}
normalized.type = "object";
normalized.properties = properties;
if (required.size > 0) normalized.required = [...required];
return normalized;
}
export function createAnthropicAdapter(provider: OcxProviderConfig, cacheRetention?: "none" | "short" | "long"): ProviderAdapter {
const isOAuth = provider.authMode === "oauth";
const toolNames = buildToolNameTransforms(provider);
return {
name: "anthropic",
formatErrorBody: formatAnthropicErrorBody,
async buildRequest(parsed: OcxParsedRequest, incoming?: IncomingMeta) {
if (typeof provider.apiKey !== "string" || provider.apiKey.trim() === "") {
if (isOAuth) {
throw new Error("anthropic oauth token missing — run ocx login anthropic");
}
throw new Error("anthropic provider requires a non-empty apiKey (authMode: key)");
}
const { system, messages } = messagesToAnthropicFormat(parsed, toolNames);
// Before image normalization, so the framing block is present for every downstream pass.
if (isAgentRouterEndpoint(provider.baseUrl)) applyAgentRouterLanguageFraming(messages);
// Primary image layer: resize/re-encode to fit Anthropic limits without dropping
// (anthropic-image-normalize.ts); the guard below remains the deterministic backstop.
// imageTierBias > 0 = upstream-413 tightened retry (030): start every image one tier lower.
await normalizeAnthropicImages(messages, {
tierBias: incoming?.imageTierBias ?? 0,
abortSignal: incoming?.abortSignal,
});
// Anthropic rejects many-image requests (>20 images) carrying any image over
// 2000px per side; see anthropic-image-guard.ts for the full limit policy.
enforceAnthropicImageLimits(messages);
const tools = toolsToAnthropicFormat(parsed, toolNames);
// Codex never sends `max_output_tokens`, so the omitted-limit default decides how
// long a Claude answer may run. Honor the provider's configured output budget
// (`modelMaxOutputTokens` / `defaultMaxOutputTokens`) before falling back to the
// conservative 8192, which truncates long answers with stop_reason=max_tokens.
const configuredMaxOut = modelRecordValue(provider.modelMaxOutputTokens, parsed.modelId)
?? provider.defaultMaxOutputTokens;
const omittedMaxTokens = typeof configuredMaxOut === "number" && configuredMaxOut > 0
? configuredMaxOut
: DEFAULT_MAX_TOKENS;
const body: Record<string, unknown> = {
model: parsed.modelId,
messages,
stream: parsed.stream,
max_tokens: parsed.options.maxOutputTokens ?? omittedMaxTokens,
};
if (isOAuth) {
// Claude OAuth (Pro/Max) requires the first system block to be the Claude Code identity.
body.system = [
{ type: "text", text: CLAUDE_CODE_SYSTEM_INSTRUCTION },
...(system ? [{ type: "text", text: system }] : []),
];
} else if (system) {
body.system = [{ type: "text", text: system }];
}
if (tools) body.tools = tools;
if (parsed.options.temperature !== undefined) body.temperature = parsed.options.temperature;
if (parsed.options.topP !== undefined) body.top_p = parsed.options.topP;
if (parsed.options.stopSequences) body.stop_sequences = parsed.options.stopSequences;
// `reasoning` is a Codex effort string; "none" is the disable sentinel (see parser.ts
// REASONING_EFFORTS). A bare truthy check would treat "none" as truthy and wrongly enable
// extended thinking (and strip temperature/top_p), so gate on a real, non-disable effort.
//
// "none" is not the same as absent. Omitting `thinking` lets a default-on model think
// anyway, and thinking shares the caller's `max_tokens` — which truncates a small-budget
// request before it can emit its stop sequence (#545). Say "disabled" out loud where the
// model both defaults to thinking and accepts being told not to.
const effectiveReasoning = parsed.options.reasoning ?? defaultReasoningEffort(provider, parsed.modelId);
if (effectiveReasoning === "none" && supportsExplicitThinkingDisable(parsed.modelId)) {
body.thinking = { type: "disabled" };
} else if (effectiveReasoning === "none" && usesBetweenToolsFloor(parsed.modelId)) {
// Sonnet 5.5 rejects `disabled`; `between_tools` is its lowest setting and turns off up-front
// thinking. No effort is sent: the API default (high) is inside the range it accepts.
body.thinking = { type: "between_tools" };
delete body.temperature;
delete body.top_p;
} else if (typeof effectiveReasoning === "string" && effectiveReasoning !== "none") {
if (usesAdaptiveThinking(parsed.modelId)) {
// Adaptive-thinking models replace the token budget with an effort knob and reject
// `thinking.type: "enabled"` outright. `max_tokens` still caps thinking plus visible
// output, so high effort needs the same total-token headroom as budget thinking or a
// default 8192-token request can spend everything on thought and return empty text.
// Opus 4.7+ defaults `display` to "omitted": the stream then carries signature-only
// thinking blocks, so a Chat client sees minutes of heartbeats and no reasoning delta
// during a long think (#5824). Ask for summarized thinking unless the caller hides it.
body.thinking = parsed.options.hideThinkingSummary
? { type: "adaptive" }
: { type: "adaptive", display: "summarized" };
const effort = adaptiveEffort(effectiveReasoning);
body.output_config = { effort };
const explicitMaxOut = parsed.options.maxOutputTokens;
const wantBudget = reasoningBudget(effort);
const floor = wantBudget + OUTPUT_HEADROOM;
// Preserve explicit caller limits as-is; for omitted limits use the adaptive ceiling
// so effort=max (budget=32k) still leaves OUTPUT_HEADROOM tokens for visible output.
body.max_tokens = explicitMaxOut !== undefined
? explicitMaxOut
: Math.max(omittedMaxTokens, Math.min(ADAPTIVE_THINKING_CEILING, Math.max(DEFAULT_MAX_TOKENS, floor)));
} else {
// Anthropic requires max_tokens > thinking.budget_tokens (max_tokens caps thinking +
// visible output) and budget_tokens >= 1024. Codex sends the SAME value for both, which
// 400s ("max_tokens must be greater than thinking.budget_tokens"). Size them so max_tokens
// always exceeds the budget within a model-safe ceiling, reserving room for visible output.
const maxOut = parsed.options.maxOutputTokens ?? omittedMaxTokens;
const wantBudget = reasoningBudget(effectiveReasoning);
const maxTokens = Math.min(REASONING_MAX_TOKENS_CEILING, Math.max(maxOut, wantBudget + OUTPUT_HEADROOM));
const budget = Math.max(MIN_THINKING_BUDGET, Math.min(wantBudget, maxTokens - OUTPUT_FLOOR));
body.max_tokens = maxTokens;
body.thinking = { type: "enabled", budget_tokens: budget };
}
// Extended thinking disallows temperature != 1 and top_p — drop both or the API 400s.
delete body.temperature;
delete body.top_p;
}
if (rejectsSamplingParameters(parsed.modelId)) {
// Opus 4.7+, Sonnet 5+ and Fable 400 on any non-default sampling parameter, with or without
// thinking (anthropic-model-contract.ts).
delete body.temperature;
delete body.top_p;
} else if (body.temperature !== undefined && body.top_p !== undefined && rejectsCombinedSampling(parsed.modelId)) {
// The 4.5/4.6 families take either field alone but 400 on both; temperature is the one kept.
delete body.top_p;
}
const textFormat = parsed.options.textFormat;
if (textFormat?.type === "json_schema" && textFormat.schema) {
const outputConfig = body.output_config;
body.output_config = {
...(outputConfig && typeof outputConfig === "object" && !Array.isArray(outputConfig)
? outputConfig
: {}),
format: {
type: "json_schema",
schema: normalizeAnthropicOutputSchema(textFormat.schema),
},
};
}
if (parsed.options.toolChoice && (tools || parsed.options.toolChoice === "none")) {
const tc = parsed.options.toolChoice;
if (tc === "auto") body.tool_choice = { type: "auto" };
else if (tc === "none") body.tool_choice = { type: "none" };
else if (tc === "required") body.tool_choice = { type: "any" };
else if (isAllowedToolChoice(tc)) body.tool_choice = { type: tc.mode === "required" ? "any" : "auto" };
else if (typeof tc === "object" && "name" in tc) body.tool_choice = { type: "tool", name: toolNames.toWire(resolveToolChoiceWireName(parsed.context.tools, tc.name)) };
} else if (tools && parsed.options.parallelToolCalls === false) {
// The caller asked for one tool call at a time but sent no explicit choice.
// Anthropic carries that intent INSIDE tool_choice, so the implicit default
// has to be stated before the flag has somewhere to live.
body.tool_choice = { type: "auto" };
}
const selectedToolChoice = body.tool_choice as { type?: string; name?: string } | undefined;
if (rejectsForcedToolChoice(parsed.modelId) && (selectedToolChoice?.type === "any" || selectedToolChoice?.type === "tool")) {
// Claude Opus 5.5 and Sonnet 5.5 reject forced tool use regardless of whether adaptive thinking is
// explicit. Anthropic's migration guidance recommends auto plus a prompt instruction;
// this keeps the request usable but cannot preserve the caller's forced-tool guarantee.
if (selectedToolChoice.type === "tool" && Array.isArray(body.tools)) {
// A named choice still narrows the candidate set even though the upstream cannot
// enforce the forced call. Do not let the compatibility downgrade widen it to every
// declared tool.
body.tools = body.tools.filter(tool => tool && typeof tool === "object" && "name" in tool
&& (tool as { name?: unknown }).name === selectedToolChoice.name);
}
body.tool_choice = { type: "auto" };
}
// disable_parallel_tool_use is nested in tool_choice and caps the model at one
// tool call for auto/any/tool. Under type "none" tool use is already off, so the
// flag is irrelevant there, and with no tools on the wire no tool_choice exists.
// This constrains the model's OUTPUT, not execution order: sequential tool use is
// enforced by the caller returning each tool_result before the next request.
const settledToolChoice = body.tool_choice as { type?: string } | undefined;
if (parsed.options.parallelToolCalls === false
&& settledToolChoice !== undefined
&& settledToolChoice.type !== "none") {
body.tool_choice = { ...settledToolChoice, disable_parallel_tool_use: true };
}
const url = resolveAnthropicMessagesUrl(provider);
// Anthropic fast mode: `speed` is only accepted beside its beta; without it the API
// answers 400 "speed: Extra inputs are not permitted". The beta is merged below, after
// any header override, so a request never carries one without the other.
const fastSpeed = anthropicFastSpeed(parsed, provider);
if (fastSpeed) body.speed = fastSpeed.value;
const headers = anthropicBaseRequestHeaders(parsed.stream);
if (isOAuth) applyAnthropicOAuthAuth(headers, provider.apiKey);
else applyAnthropicKeyAuth(headers, provider);
if (provider.headers) Object.assign(headers, provider.headers);
mergeAnthropicBetaHeader(headers, fastSpeed?.betas ?? []);
// Prompt caching: native Anthropic supports top-level automatic caching, which
// follows the moving final block across turns. Keep one breakpoint slot free for it.
const cc = resolveCacheControl(cacheRetention);
const automaticPromptCaching = cc && usesNativeAnthropicEndpoint(provider);
if (automaticPromptCaching) body.cache_control = cc;
const explicitLimit = automaticPromptCaching ? MAX_CACHE_BREAKPOINTS - 1 : MAX_CACHE_BREAKPOINTS;
applyPromptCaching(body, cc, {
maxExplicitBreakpoints: explicitLimit,
skipLastUser: !!automaticPromptCaching,
});
enforceCacheControlLimit(body, explicitLimit);
normalizeTtlOrdering(body);
return {
url,
method: "POST",
headers,
body: JSON.stringify(body),
// Adapter-owned: the registry wrapper would otherwise report the exact absence of a
// tier field and mislabel every fast turn as downgraded.
tierLog: createAdapterTierMetadata(
parsed.options.tierObservation,
parsed.options.tierDecision,
fastSpeed ? "anthropic-speed" : null,
fastSpeed?.value ?? null,
),
};
},
async *parseStream(
response: Response,
budget: TranslatorBudget,
tierMetadata?: AdapterTierMetadata,
): AsyncGenerator<AdapterEvent> {
if (!response.body) {
yield { type: "error", message: "No response body" };
return;
}
const budgetEncoder = new TextEncoder();
let currentBlockType = "";
let currentToolCallId = "";
let currentToolCallName = "";
let currentToolCallJson = "";
let pendingUsage: PendingAnthropicUsage;
let pendingStopReason: string | undefined;
let emittedDone = false;
let sawVisibleText = false;
const emitDone = function* (): Generator<AdapterEvent> {
if (emittedDone) return;
emittedDone = true;
// An `error` stop reason is a failed generation, not a stop. Forwarding it as `done`
// lets the turn report success and install replacement history on a compaction turn.
if (pendingStopReason === "error") {
yield {
type: "error",
message: "upstream ended the turn with stop_reason \"error\"",
status: 502,
errorType: "upstream_error",
usage: usageFromAnthropic(pendingUsage),
};
return;
}
// Refusal / content_filter must not look like a dropped stream. `done` with that
// stopReason becomes `response.incomplete` without `retryable`, and Codex retries
// the same refusal five times (#4312).
if (isAnthropicContentFilterStopReason(pendingStopReason)) {
yield anthropicContentFilterIncomplete(pendingStopReason, usageFromAnthropic(pendingUsage));
return;
}
yield {
type: "done",
usage: usageFromAnthropic(pendingUsage),
...(pendingStopReason ? { stopReason: pendingStopReason } : {}),
};
};
try {
for await (const record of decodeServerSentEvents(response.body, { includeComments: true, translatorBudget: budget })) {
// Anthropic's streaming API sends `event: ping` / `{"type":"ping"}` records alongside
// SSE comments ("Event streams may also include any number of ping events"). Both mean the
// upstream is still alive, so a long silent thinking block must not look like a dead
// upstream to the bridge stall watchdog (#5707).
if (record.kind === "comment" || record.event === "ping") {
yield { type: "heartbeat" };
continue;
}
const payload = record.data.trim();
if (!payload) continue;
let parsed: unknown;
try {
parsed = JSON.parse(payload);
} catch {
debugDroppedFrame("anthropic", payload);
continue;
}
// `JSON.parse("null")` returns null instead of throwing, so the catch above cannot cover
// it and the `data.type` read below crashed the stream. Drop a non-record frame the same
// way an unparseable one is dropped, so the message_stop check still governs the outcome.
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
debugDroppedFrame("anthropic", payload);
continue;
}
const data = parsed as Record<string, unknown>;
switch (record.event || data.type) {
case "message_start": {
const message = data.message as { usage?: unknown } | undefined;
pendingUsage = mergeAnthropicUsage(pendingUsage, message?.usage);
// Fast mode reports the speed actually served here (`usage.speed`).
observeAnthropicSpeed(message?.usage, tierMetadata);
break;
}
case "content_block_start": {
const block = data.content_block as { type: string; id?: string; name?: unknown; data?: string; thinking?: string } | undefined;
if (!block) break;
currentBlockType = block.type;
if (block.type === "thinking") {
// Preserve even a display:omitted block boundary. The bridge can then
// distinguish consecutive empty signed blocks from signature updates.
yield { type: "thinking_delta", thinking: typeof block.thinking === "string" ? block.thinking : "" };
}
if (block.type === "tool_use") {
currentToolCallId = usableToolUseId(block.id);
currentToolCallName = toolNames.fromWire(typeof block.name === "string" ? block.name : "");
currentToolCallJson = "";
budget.openCall(currentToolCallId);
yield { type: "tool_call_start", id: currentToolCallId, name: currentToolCallName };
}
if (block.type === "redacted_thinking" && typeof block.data === "string") {
// Opaque redacted block: replay verbatim later or tool-use turns 400.
yield { type: "redacted_thinking", data: block.data };
}
break;
}
case "content_block_delta": {
const delta = data.delta as Record<string, unknown> | undefined;
if (!delta) break;
if (delta.type === "text_delta" && typeof delta.text === "string") {
// Only non-empty text proves the upstream produced usable output; an empty
// delta followed by EOF must stay a truncation error even on the tolerant
// profile, or a cut-off turn would surface as a successful empty answer.
if (delta.text.length > 0) sawVisibleText = true;
yield { type: "text_delta", text: delta.text };
} else if (delta.type === "thinking_delta" && typeof delta.thinking === "string") {
yield { type: "thinking_delta", thinking: delta.thinking };
} else if (delta.type === "reasoning_delta" && typeof delta.reasoning === "string") {
// Some Anthropic-compatible reasoning models use `reasoning` names for the
// otherwise equivalent thinking block. Preserve it as raw reasoning and keep
// later text blocks independent.
yield { type: "thinking_delta", thinking: delta.reasoning };
} else if (delta.type === "signature_delta" && typeof delta.signature === "string" && (currentBlockType === "thinking" || currentBlockType === "reasoning")) {
// Anthropic SDKs replace the signature with this value. Forward updates
// within the block; the bridge closes on the next semantic boundary.
yield { type: "thinking_signature", signature: delta.signature };
} else if (delta.type === "input_json_delta" && typeof delta.partial_json === "string" && currentBlockType === "tool_use") {
// Forwarded immediately: the bridge maps each delta to a client-visible
// response.function_call_arguments.delta frame, so withholding fragments until
// block close would leave a started call showing empty arguments. A copy is kept
// to validate the assembled payload at content_block_stop.
const previousBytes = budgetEncoder.encode(currentToolCallJson).byteLength;
const nextBytes = previousBytes + budgetEncoder.encode(delta.partial_json).byteLength;
const reservation = budget.reserveTransient(nextBytes, { kind: "tool_args", callId: currentToolCallId });
try {
currentToolCallJson += delta.partial_json;
reservation.commitRetained();
budget.releaseRetained(previousBytes, { kind: "tool_args", callId: currentToolCallId });
} catch (error) {
reservation.release();
throw error;
}
yield { type: "tool_call_delta", arguments: delta.partial_json };
}
break;
}
case "content_block_stop": {
if (currentBlockType === "tool_use") {
// The non-stream path repairs an unparseable payload in toolUseArguments(); the
// stream cannot, because the fragments are already downstream. Fail the turn
// instead of ending a tool call whose arguments will not parse — the bridge's
// terminal-error path cancels the open call (status incomplete) rather than
// completing it before response.failed (#765).
if (!streamedToolArgumentsParse(currentToolCallJson)) {
yield {
type: "error",
message: "Anthropic stream sent malformed tool_use arguments (invalid JSON)",
};
return;
}
yield { type: "tool_call_end" };
budget.closeCall(currentToolCallId);
currentToolCallId = "";
currentToolCallJson = "";
}
currentBlockType = "";
break;
}
case "message_delta": {
const usage = data.usage;
pendingUsage = mergeAnthropicUsage(pendingUsage, usage);
// Later frames win: a speed here (not seen live, but usage is cumulative) supersedes message_start.
observeAnthropicSpeed(usage, tierMetadata);
const delta = data.delta as { stop_reason?: unknown } | undefined;
if (typeof delta?.stop_reason === "string") pendingStopReason = delta.stop_reason;
break;
}
case "message_stop": {
yield* emitDone();
break;
}
case "ping": {
// A data-only `{"type":"ping"}` record carries no SSE `event:` line, so the
// liveness check above cannot see it (#5707).
yield { type: "heartbeat" };
break;
}
case "error": {
const err = data.error as { message?: string } | undefined;
yield { type: "error", message: err?.message ?? "Anthropic error" };
return;
}
}
}
} catch (error) {
if (!isTranslatorBudgetExceededError(error)) throw error;
yield {
type: "error",
status: 502,
errorType: "upstream_error",
code: "translation_buffer_limit",
message: "upstream translation buffer exceeded the safe limit",
};
// The budget error IS the terminal event for this stream. Falling through to the
// EOF handling below could append tool_call_end/done after it, violating the
// one-terminal-event contract for consumers that keep draining the generator.
return;
} finally {
if (currentToolCallId) budget.closeCall(currentToolCallId);
}
if (!emittedDone) {
// Fail closed on transport EOF. Compatible providers may omit message_stop after message_delta.stop_reason.
if (pendingStopReason !== undefined) {
// Same rule as emitDone: an `error` stop reason is a failed generation, not a stop.
// This branch bypasses emitDone entirely (it exists for providers that close after
// message_delta without message_stop), so the check has to be repeated here or the
// EOF route silently reports success.
if (pendingStopReason === "error") {
emittedDone = true;
yield {
type: "error",
message: "upstream ended the turn with stop_reason \"error\"",
status: 502,
errorType: "upstream_error",
usage: usageFromAnthropic(pendingUsage),
};
return;
}
// Same rule as emitDone: refusal / content_filter is a permanent decision, not a
// disconnect. This branch bypasses emitDone, so the check has to be repeated here
// or the EOF route still emits `done` and Codex retries the refusal (#4312).
if (isAnthropicContentFilterStopReason(pendingStopReason)) {
emittedDone = true;
yield anthropicContentFilterIncomplete(pendingStopReason, usageFromAnthropic(pendingUsage));
return;
}
emittedDone = true;
yield {
type: "done",
usage: usageFromAnthropic(pendingUsage),
...(pendingStopReason ? { stopReason: pendingStopReason } : {}),
};
} else if (provider.anthropicEofTolerance === true) {
// AgentRouter-style compatibility profile (#658): the upstream can close the stream
// after valid content without terminal frames. Complete only when visible text was
// received or an open tool call has complete JSON-object arguments; everything else
// (incomplete tool JSON, no usable content, transport failure) stays a truncation
// error, matching the strict default.
if (currentToolCallId) {
if (streamedToolArgumentsParse(currentToolCallJson)) {
budget.closeCall(currentToolCallId);
currentToolCallId = "";
yield { type: "tool_call_end" };
yield* emitDone();
} else {
yield { type: "error", message: "upstream stream ended before message_stop — possible truncation" };
}
} else if (sawVisibleText) {
yield* emitDone();
} else {
yield { type: "error", message: "upstream stream ended before message_stop — possible truncation" };
}
} else {
yield { type: "error", message: "upstream stream ended before message_stop — possible truncation" };
}
}
},
async parseResponse(
response: Response,
budget: TranslatorBudget,
tierMetadata?: AdapterTierMetadata,
): Promise<AdapterEvent[]> {
const parsed: unknown = await response.json();
// `response.json()` resolves a body of `null` to `null` without throwing, so the cast below
// used to reach `json.content` on it — the #1219 defect at the buffered body root. The
// streaming parser has skipped a non-record frame since #1240, but a buffered body has no
// next frame to recover into, so this fails closed instead.
if (!isAnthropicRecord(parsed)) {
return [{
type: "error",
message: `anthropic response was not a JSON object (${anthropicStructuralValueType(parsed)})`,
status: 502,
errorType: "upstream_error",
}];
}
const json = parsed;
const responseBytes = Buffer.byteLength(JSON.stringify(json), "utf8");
budget.chargeRetained(responseBytes, { kind: "retained_collectors" });
try {
const events: AdapterEvent[] = [];
// Same retain-then-return tail every other terminal branch in this function uses; naming it
// keeps the two shape guards below from drifting out of step with the accounting.
const finishWithEvents = (batch: AdapterEvent[]): AdapterEvent[] => {
retainTranslatedEventBatch(batch, budget);
return batch;
};
const rawContent: unknown = json.content;
// `content` is claimed model output inside a well-formed response, so it is governed by the
// #1332 nested-shape rule (fail closed) rather than #1240's root-frame padding rule (skip).
// Absence stays legal in both encodings. A present non-array was silently accepted and is
// the dangerous case: a string is iterable, so `for (const block of "text")` walked it one
// CHARACTER at a time, read `undefined` from every `block.type`, and completed the turn as a
// successful empty response — the #2231 failure mode on a different adapter.
if (rawContent !== undefined && rawContent !== null && !Array.isArray(rawContent)) {
return finishWithEvents([invalidAnthropicShapeEvent({
reason: "content_not_array",
valueType: anthropicStructuralValueType(rawContent),
})]);
}
if (Array.isArray(rawContent)) {
for (let blockIndex = 0; blockIndex < rawContent.length; blockIndex++) {
if (!isAnthropicRecord(rawContent[blockIndex])) {
return finishWithEvents([invalidAnthropicShapeEvent({
reason: "content_block_not_object",
blockIndex,
valueType: anthropicStructuralValueType(rawContent[blockIndex]),
})]);
}
}
}
const content = rawContent as { type: string; text?: string; id?: string; name?: unknown; input?: unknown; thinking?: string; reasoning?: string; signature?: string; data?: string }[] | undefined;
if (content) {
for (const block of content) {
if (block.type === "text" && block.text) {
events.push({ type: "text_delta", text: block.text });
} else if (block.type === "thinking" && typeof block.thinking === "string") {
events.push({ type: "thinking_delta", thinking: block.thinking });
if (typeof block.signature === "string" && block.signature) {
events.push({ type: "thinking_signature", signature: block.signature });
}
} else if (block.type === "reasoning" && typeof block.reasoning === "string") {
events.push({ type: "thinking_delta", thinking: block.reasoning });
} else if (block.type === "redacted_thinking" && typeof block.data === "string") {
events.push({ type: "redacted_thinking", data: block.data });
} else if (block.type === "tool_use") {
const id = usableToolUseId(block.id);
events.push({ type: "tool_call_start", id, name: toolNames.fromWire(typeof block.name === "string" ? block.name : "") });
events.push({ type: "tool_call_delta", arguments: toolUseArguments(block.input, provider.anthropicEofTolerance === true) });
events.push({ type: "tool_call_end" });
}
}
}
const usage = json.usage as Record<string, number> | undefined;
observeAnthropicSpeed(json.usage, tierMetadata);
const stopReason = typeof json.stop_reason === "string" ? json.stop_reason : undefined;
// An Anthropic-compatible upstream can forward an `error` stop reason verbatim. As a
// `done` it reads as a clean completion, so the turn reports success and — on a compaction
// turn — installs its partial summary as replacement history (#422). Usage is preserved:
// a failed turn still consumed tokens.
if (stopReason === "error") {
events.push({
type: "error",
message: "upstream ended the turn with stop_reason \"error\"",
status: 502,
errorType: "upstream_error",
usage: usageFromAnthropic(usage),
});
retainTranslatedEventBatch(events, budget);
return events;
}
// Same rule as the streaming terminals: a refusal is explicit and non-retryable.
// Leaving it as `done` hides `retryable: false` and Codex retries the filtered
// turn as if the stream dropped (#4312). Partial content above is already in
// `events`; the incomplete event carries usage the same way `done` did.
if (isAnthropicContentFilterStopReason(stopReason)) {
events.push(anthropicContentFilterIncomplete(stopReason, usageFromAnthropic(usage)));
retainTranslatedEventBatch(events, budget);
return events;
}
events.push({
type: "done",
usage: usageFromAnthropic(usage),
...(stopReason ? { stopReason } : {}),
});
retainTranslatedEventBatch(events, budget);
return events;
} finally {
budget.releaseRetained(responseBytes, { kind: "retained_collectors" });
}
},
};
}