EggPool transparently translates between OpenAI Chat Completions, OpenAI
Responses, Anthropic Messages, and selected native provider wire surfaces,
letting clients keep their public grammar while upstream contracts vary. The
request path captures a small canonical semantic intent before
provider-specific encoding. The mature field-level transcoders remain the
compatibility implementation for Chat/Messages semantics; concrete wire
codecs cover Responses and native Gemini Interactions/generateContent.
Protocol transcoding exists because providers expose several incompatible wire formats: OpenAI Chat Completions/Responses, Anthropic Messages, and native Gemini APIs. Most providers serve only one. Without the canonical boundary, a client would be limited to providers exposing its exact request grammar.
Transcoding is on by default. Every EggPool data plane normalises the client request to the appropriate upstream wire format automatically: an OpenAI Chat Completions client posting to /v1/chat/completions reaches Anthropic upstreams (and vice versa) without any operator configuration. This is the primary behaviour of the router: clients should always see their expected protocol, regardless of the upstream provider's protocol.
The transcoder sits in the request path and:
- Rewrites the request body before dispatch using the selected surface codec.
- Decodes the response body back to the client's expected format.
- Re-renders non-retryable errors in the client protocol so error handling stays uniform.
- Adapts streaming SSE events from one shared bounded frame stream in real time, preserving native terminal semantics. Same-surface Responses streams are observed and forwarded without payload reconstruction; cross-surface Responses streams use bounded lifecycle state to synthesize complete output items.
rust/src/wire/ir.rs contains the portable subset used for cross-surface
replay: ordered messages/content blocks, function/freeform/deferred-search
tools and choices, response format intent, normalized usage, response blocks,
and bounded stream events.
ReasoningIntent records unspecified, explicit disable, named effort,
fixed budget, adaptive, or toggle semantics. Named effort is not converted to
a guessed token budget; the selected provider/model capability owns the final
wire encoding.
The original canonical request is retained in TranscodeContext and
ProxyRequestContext. A retry or future alternate-surface attempt must start
from that source, not from the body emitted for an earlier provider. Native
same-surface requests retain the existing byte-preserving fast path. For
Responses specifically, admission also retains a bounded source-native
envelope outside the canonical IR. Responses-to-Responses forwarding keeps
ordered native history, encrypted reasoning, native tools, and extensions;
when an alias changes the upstream model, only the top-level model is
rewritten. Cross-surface adaptation rejects native-only items/tools before
dispatch and reports safely omittable extensions through bounded adaptation
notices.
Responses custom tools are the portable freeform exception: a function-only
target receives a strict single-string input wrapper, and the per-request
tool declaration maps the provider call back to a Responses
custom_tool_call/custom_tool_call_output pair. Client-executed
tool_search is the portable deferred-search exception: the wrapper reuses
the exact bounded query/limit schema and maps back to an authoritative
tool_search_call with distinct item/call IDs. Both mappings are
declaration-scoped, never inferred from a name alone, and never persisted.
Hosted/server search, namespaces, and other native/server tools without a
reusable semantic equivalent remain preserved only on native Responses routes
or fail before provider dispatch. Eggpool never executes the search.
Request encoders receive the provider-bound payload as a read-only Mapping and
construct a fresh target graph. The coordinator adopts that graph as the new
request-local provider generation; it does not recursively copy the source
request first or rematerialize the translated graph afterward. Prepared
transcodes remain request-local and reuse their encoded bytes when valid.
Image and PDF data-URI validation first uses encoded-length arithmetic to reject obvious provider-limit overflow. Inputs that remain possible candidates still use strict base64 decoding; the temporary decoded validation buffer is released before the translated output container is built. Media limits, invalid-base64 behavior, and URL-source behavior are unchanged.
RequestCoordinator creates one SSEDecoder for each upstream stream. It owns
UTF-8 decoding, line-ending normalization, multiline data: assembly, and
bounds incomplete input to 64 KiB. Each DecodedSSEFrame is then delivered to
the completion/usage observer and, when needed, the selected transcoder.
DecodedSSEFrame.json_object() lazily caches a parsed object so two consumers
never parse the same frame twice. Concrete transcoders do not parse raw bytes;
their translate_frame() and finish() methods are synchronous. Native
Responses responses remain byte-for-byte pass-through apart from observation
when the client and upstream Responses surfaces match. Other translated
streams retain only bounded active text, reasoning, and tool argument state.
Responses output indexes and sequence numbers are downstream serialization
state; function-call call_id is kept distinct from the generated output-item
ID, and response.output_item.done is emitted before response.completed.
Encrypted reasoning is preserved only on the native Responses path and is
never synthesized from plaintext.
Usage and cost fields are preserved exactly as the upstream reported them: no translation, no rounding, no loss.
The [transcoder] block is optional and rarely needs to be touched:
[transcoder]
# Optional loss policy: "warn" (default) or "reject"
loss_policy = "warn"
# Optional routing preference: native-protocol accounts outrank transcodable ones
prefer_native = true
[transcoder.features]
# Deprecated compatibility field; tool calling is baseline protocol
# compatibility and is translated regardless of this value.
tools = true
# Image / document content parts (default: false)
vision = false
# Extended thinking blocks ↔ reasoning_content (default: true)
thinking = true
# OpenAI response_format / json_schema coercion (default: false)
structured_outputs = false
# Anthropic-only primitives explicit handling (default: false)
anthropic_primitives = falseAt boot you'll see:
INFO Protocol transcoding ENABLED (default): clients may reach upstream accounts whose provider.protocols does not match the client protocol. loss_policy=warn prefer_native=true
The enabled flag is deprecated but still honoured as an escape hatch for operators who need to disable translation (for example, while diagnosing routing issues or pinning legacy behaviour):
[transcoder]
enabled = false # DEPRECATED: forces legacy protocol-exact routingWhen set, EggPool boots with a WARNING and reverts to the pre-default behaviour: every request must match its upstream protocol exactly. Cross-protocol requests will fail with HTTP 400 ProtocolMismatchError. This option will be removed in a future release.
| OpenAI field | Anthropic field | Notes |
|---|---|---|
model |
model |
Passed through verbatim |
messages[system] |
system |
Extracted from messages, concatenated |
messages[user] |
messages[user] |
Text content passed through |
messages[assistant] |
messages[assistant] |
Text content passed through |
temperature |
temperature |
Clamped to ≤ 1.0 (Anthropic max) |
max_tokens |
max_tokens |
Defaults to 4096 if missing |
stop |
stop_sequences |
String → single-element list |
top_p |
N/A | Dropped, warning emitted |
frequency_penalty |
N/A | Dropped, warning emitted |
presence_penalty |
N/A | Dropped, warning emitted |
n |
N/A | Dropped when > 1, warning emitted |
logprobs |
N/A | Dropped, warning emitted |
top_logprobs |
N/A | Dropped, warning emitted |
response_format |
output_config.format or system |
A verified Anthropic target receives native json_schema; otherwise the configured loss policy governs the explicitly lossy prompt fallback. json_object remains prompt-based because it has no schema to send. |
reasoning_effort |
thinking |
Feature-gated: the canonical effort intent is resolved only after target capability selection; verified low/medium/high mappings remain supported and unknown labels are never assigned a guessed budget |
seed |
N/A | Dropped, warning emitted |
user |
N/A | Dropped, warning emitted |
logit_bias |
N/A | Dropped, warning emitted |
messages[user].content[image_url] |
messages[user].content[image] |
Feature-gated: base64 data URI → {type: "base64", media_type, data} where data is the raw base64 payload; URL → {type: "url", url}; detail dropped; images over 5 MB are dropped with image_too_large |
messages[user].content[input_audio] |
N/A | Dropped, warning emitted |
messages[user].content[file] |
N/A | Dropped, warning emitted (file storage not bridged) |
tools (function-shape) |
tools (Anthropic-shape) |
Translated field-by-field (see Tool-Use Transcoding below) |
tool_choice |
tool_choice |
Translated between string and object shapes |
parallel_tool_calls: true |
omitted | Anthropic defaults to allowing parallel calls |
parallel_tool_calls: false |
tool_choice.disable_parallel_tool_use |
Emitted only for a target with explicit parallel_tool_control = ["anthropic"]; otherwise loss is reported. |
tools[].function.strict |
tools[].strict |
Emitted only for a target with explicit strict_tools = ["anthropic"]; otherwise loss is reported. |
stream_options |
N/A | Wrapper dropped with warning; include_usage lifted onto TranscodeContext.request_include_usage |
messages[assistant].tool_calls[] |
messages[assistant].content[].tool_use |
Translated; id map mints new upstream ids |
messages[tool] |
messages[user].content[].tool_result |
Translated; tool_call_id ↔ tool_use_id via id map |
messages[].content[non-text] |
N/A | Non-text blocks dropped, warning emitted |
| Anthropic field | OpenAI field | Notes |
|---|---|---|
model |
model |
Passed through verbatim |
system |
messages[system] |
Converted to system message |
messages[user] |
messages[user] |
Text content passed through |
messages[assistant] |
messages[assistant] |
Text content passed through |
temperature |
temperature |
Passed through |
max_tokens |
max_tokens |
Passed through |
stop_sequences |
stop |
Single → string, multi → list |
metadata.user_id |
user |
Mapped to OpenAI user field |
top_k |
N/A | Dropped, warning top_k_dropped emitted |
cache_control |
N/A | Dropped, warning cache_control_feature_disabled emitted |
thinking |
N/A | Dropped, warning emitted (see Extended Thinking below) |
context_management |
N/A | Dropped, warning emitted (experimental) |
container |
N/A | Dropped, warning emitted (experimental) |
mcp_servers |
N/A | Dropped, warning emitted (experimental) |
tools (Anthropic-shape) |
tools (function-shape) |
Translated field-by-field (see Tool-Use Transcoding below) |
tool_choice |
tool_choice |
Translated between object and string shapes |
tools[].cache_control |
N/A | Dropped with cache_control_unsupported_by_target_protocol warning; boundary tracked on TranscodeContext.cache_boundary_tracker |
messages[].content[].cache_control |
N/A | Dropped with cache_control_unsupported_by_target_protocol warning |
messages[assistant].content[thinking] |
messages[assistant].reasoning_content |
Feature-gated: thinking text mapped; signature dropped with thinking_signature_dropped warning |
messages[assistant].content[image] |
messages[user].content[image_url] |
Feature-gated: base64 → data URI; URL → image_url.url |
messages[user].content[document] |
messages[user].content[file] |
Feature-gated: PDF base64 → file with data URI; URL dropped; non-PDF, invalid base64, and PDFs over 32 MB are dropped. All requests must also fit [server].max_request_body_bytes (10 MiB by default). |
messages[assistant].content[].tool_use |
messages[assistant].tool_calls[] |
Translated; id map mints new client ids |
messages[user].content[].tool_result |
messages[tool] |
Translated; tool_use_id ↔ tool_call_id via id map |
messages[].content[non-text] |
N/A | Non-text blocks dropped, warning emitted |
| Anthropic field | OpenAI field | Notes |
|---|---|---|
id |
id |
Prefixed chatcmpl- if needed |
model |
model |
Passed through |
content[].text |
message.content |
Text blocks concatenated |
content[].tool_use |
message.tool_calls[] |
Translated; id map mints new client ids |
content[].thinking |
message.reasoning_content |
Feature-gated: thinking text mapped; signature dropped with thinking_signature_dropped warning |
content[].redacted_thinking |
N/A | Dropped, warning emitted |
content[].image |
message.content[image_url] |
Feature-gated: base64 → data URI; URL → image_url.url |
stop_reason |
choices[].finish_reason |
Mapped (see table below) |
usage.input_tokens |
usage.prompt_tokens |
Direct mapping |
usage.output_tokens |
usage.completion_tokens |
Direct mapping |
| N/A | usage.total_tokens |
Computed (prompt + completion) |
| OpenAI field | Anthropic field | Notes |
|---|---|---|
id |
id |
Prefixed msg_ if needed |
model |
model |
Passed through |
message.content |
content[].text |
Wrapped in text block |
message.tool_calls[] |
content[].tool_use |
Translated; id map mints new upstream ids |
message.reasoning_content |
content[].thinking |
Feature-gated: reasoning text mapped to thinking block |
choices[].finish_reason |
stop_reason |
Mapped (see table below) |
usage.prompt_tokens |
usage.input_tokens |
Direct mapping |
usage.completion_tokens |
usage.output_tokens |
Direct mapping |
message.refusal |
content[].text + stop_reason=refusal |
Content replaced |
Anthropic stop_reason |
OpenAI finish_reason |
|
|---|---|---|
end_turn |
stop |
Lossless |
stop_sequence |
stop |
Lossy (sequence identity lost) |
max_tokens |
length |
Lossless |
tool_use |
tool_calls |
Lossless |
refusal |
content_filter |
Lossless |
pause_turn |
tool_calls + sentinel |
Lossy; see Tool-Use Transcoding |
model_context_window_exceeded |
length |
Lossy (cause obscured) |
Tool calling is translated between OpenAI Chat Completions and Anthropic Messages in both directions, for streaming and non-streaming requests. The OpenAI Chat Completions client's tools and tool_choice reach Anthropic-only upstreams (e.g. MiniMax International) intact, and tool calls emitted by an Anthropic upstream are reconstructed as OpenAI tool_calls on the response. Anthropic clients driving OpenAI Chat Completions-only upstreams see the same round trip in reverse.
OpenAI tools → Anthropic tools:
| OpenAI input | Anthropic output | Notes |
|---|---|---|
tools[i].type == "function" |
tools[i] (Anthropic-shape) |
Lifted; function.name → name, function.description → description, function.parameters → input_schema |
tools[i].type other than "function" |
dropped | Warning unsupported_tool_type |
tools[i].function.strict |
tools[i].strict |
Capability-gated native mapping; generic compatible providers remain conservative. |
Anthropic tools → OpenAI tools:
| Anthropic input | OpenAI output | Notes |
|---|---|---|
tools[i].name, description, input_schema |
tools[i].type == "function" with function.{name, description, parameters} |
parameters is the lifted input_schema |
tools[i].cache_control |
N/A | Dropped with warning; OpenAI Chat Completions has no tool-definition boundary placement |
tool_choice translation:
| OpenAI input | Anthropic output | Notes |
|---|---|---|
"none" |
{"type": "none"} |
|
"auto" |
omitted | Anthropic default |
"required" |
{"type": "any"} |
|
{"type": "function", "function": {"name": "X"}} |
{"type": "tool", "name": "X"} |
|
| anything else | omitted | Warning invalid_tool_choice |
| Anthropic input | OpenAI output | Notes |
|---|---|---|
{"type": "auto"} |
"auto" |
|
{"type": "any"} |
"required" |
|
{"type": "tool", "name": "X"} |
{"type": "function", "function": {"name": "X"}} |
|
{"type": "none"} |
"none" |
|
| anything else | "auto" |
Warning invalid_tool_choice |
parallel_tool_calls:
parallel_tool_calls: trueis omitted on the Anthropic side (Anthropic defaults to allowing parallel calls).parallel_tool_calls: falsemaps totool_choice.disable_parallel_tool_use = trueonly when the target model capability explicitly verifies that control; otherwise it produces a loss warning (or a local 400 underloss_policy = "reject").
Provider/model capability overrides use [model_capabilities.<model>.transcoding]
or the provider-scoped equivalent. Supported fields are
native_structured_outputs, strict_tools, parallel_tool_control,
prompt_cache_breakpoints, and reasoning_efforts. Cache entries are keyed by
target protocol and must declare dialect = "first_party" or
dialect = "compatible_extension", plus any verified TTLs and breakpoint
limit. Empty or missing fields mean unknown/unverified support; EggPool never
enables native fields solely because an account advertises an OpenAI or
Anthropic protocol.
Prompt-cache translation is best-effort across the representable subset. An
explicit OpenAI content breakpoint can become an Anthropic block
cache_control, and an Anthropic message/system block boundary can become an
OpenAI prompt_cache_breakpoint, only when the target capability explicitly
lists that protocol. Source-only breakpoint fields are consumed at the
translation boundary and never remain on the target wire. TTLs are not treated
as equivalent: Anthropic's 5-minute and 1-hour controls do not silently become
OpenAI's 30-minute setting (or vice versa); mismatch metadata uses the selected
target contract rather than a generic TTL literal. Anthropic tool-definition
boundaries remain lossy for OpenAI Chat Completions when no native tool
breakpoint is available. OpenAI's automatic caching and prompt_cache_key
grouping do not opt translated Anthropic requests into explicit caching, and
explicit source intent can request a mapped target boundary; EggPool does not
synthesize cache controls. An absent OpenAI breakpoint is ordinary content, not
a cache loss. In the reverse
direction, only a breakpoint actually emitted on the OpenAI target counts as a
mapping; malformed, unsupported, and overflow cases remain loss-visible
without causing prompt_cache_options to appear by themselves.
Tool-call ids are protocol-shaped and never reused across the wire. OpenAI clients expect call_<…> ids; Anthropic upstreams expect toolu_<…> ids. The transcoder maintains a per-request ToolCallIdMap keyed on the originating TranscodeContext.id_map so the two namespaces stay independent.
| Direction | Source id | Generated id |
|---|---|---|
OpenAI → Anthropic (assistant tool_calls) |
call_… (client) |
toolu_<24 hex> (via generate_anthropic_id) |
Anthropic → OpenAI (assistant content[].tool_use) |
toolu_… (upstream) |
call_<24 hex> (via generate_openai_id) |
OpenAI → Anthropic (role: "tool" history) |
call_… (client tool_call_id) |
toolu_… carried over as the tool_use_id on the Anthropic tool_result block |
Anthropic → OpenAI (tool_result history) |
toolu_… (upstream tool_use_id) |
call_… carried over as the tool_call_id on the OpenAI tool message |
Both generate_openai_id and generate_anthropic_id produce 24 hex characters after the prefix (call_ / toolu_), matching what real OpenAI and Anthropic responses emit. The id_map is per-TranscodeContext (i.e. per-request), so concurrent requests cannot collide.
Whenever the map mints a new id, the transcoder appends a tool_call_id_translated loss warning so operators can audit id translation traffic.
| OpenAI input | Anthropic output | Notes |
|---|---|---|
messages[i].role == "assistant", tool_calls[j].id (call_…) |
messages[i].content[k].type == "tool_use", id (toolu_…) |
id via id_map.register(call_…, toolu_…) |
messages[i].role == "assistant", tool_calls[j].function.name, function.arguments |
tool_use.name, tool_use.input |
arguments JSON-parsed into an object; on parse failure the raw string is preserved as {"__raw_arguments__": "<string>"} and a malformed_tool_arguments warning is emitted |
messages[i].role == "assistant", mixed text + tool_calls |
content: [{type: "text", ...}, {type: "tool_use", ...}, ...] |
Anthropic permits mixed text + tool_use in one assistant turn |
messages[i].role == "tool", content: str, tool_call_id |
messages[i].role == "user", content: [{type: "tool_result", tool_use_id, content: <str>, is_error: <bool>}] |
tool_use_id resolved via id_map.to_upstream(call_id) |
messages[i].role == "tool", content: list (mixed text/image) |
tool_result with joined text; image parts dropped |
Warning media_tool_result_flattened |
messages[i].role == "tool", is_error: true |
tool_result.is_error: true |
Forwarded verbatim |
| Anthropic input | OpenAI output | Notes |
|---|---|---|
messages[i].content[k].type == "tool_use", id (toolu_…), name, input |
messages[i].role == "assistant", tool_calls[k'] with id (call_…), type: "function", function.name, function.arguments |
input JSON-stringified into arguments; on encode failure the raw value is preserved as {"__raw_arguments__": "<string>"} with malformed_tool_arguments warning |
messages[i].content[k].type == "tool_result", tool_use_id, content: str |
messages[i].role == "tool", tool_call_id (call_…), content: <str> |
|
messages[i].content[k].type == "tool_result", content: list |
messages[i].role == "tool", content: <joined text> |
Text parts joined with \n; non-text dropped with non_text_content_dropped |
messages[i].content[k].type == "tool_result", is_error: true |
messages[i].role == "tool", content: <error text> |
Warning tool_result_error_passthrough: OpenAI has no is_error field |
Anthropic → OpenAI (upstream SSE → client SSE):
Each Anthropic content_block_start with content_block.type == "tool_use" opens an indexed slot in the streaming transcoder's per-request state, keyed by the Anthropic index. The transcoder mints a fresh call_<…> id via id_map.generate_openai_id() and emits a tool_calls delta carrying {index, id, type: "function", function: {name, arguments: ""}}. Each subsequent content_block_delta with delta.type == "input_json_delta" appends partial_json to the slot's argument buffer and emits a tool_calls delta with {index, function: {arguments: <chunk>}}. The content_block_stop finalises the slot but emits nothing extra: the terminal finish_reason: "tool_calls" chunk plus [DONE] arrive on message_delta.
| Upstream event | Emitted client delta |
|---|---|
content_block_start (type: tool_use, id: toolu_X, name: fn, input: {}) |
delta.tool_calls[i] = {index, id: call_Y, type: "function", function: {name: fn, arguments: ""}} |
content_block_delta (type: input_json_delta, partial_json: <chunk>) |
delta.tool_calls[i] = {index, function: {arguments: <chunk>}} |
content_block_stop (index: i) |
(nothing) |
message_delta (stop_reason: tool_use) |
delta: {}, finish_reason: "tool_calls", then [DONE] |
If flush() is called before a slot received its content_block_stop, the streaming transcoder still emits a final tool_calls delta with the accumulated arguments. If the accumulated JSON fails to parse, a malformed_tool_arguments warning is appended and the raw string is delivered anyway so the client can attempt to use the partial value.
OpenAI → Anthropic (upstream SSE → client SSE):
OpenAI tool_calls[*] deltas may arrive split across many chunks (often with the id and name on the first chunk and incremental arguments on subsequent chunks). The transcoder buffers each call keyed on the OpenAI tool_calls[*].index until finish_reason: "tool_calls" arrives on the terminal delta, then assembles the Anthropic tool_use blocks in insertion order:
event: content_block_start
data: {"index": K, "content_block": {"type": "tool_use", "id": "toolu_<…>", "name": <name>, "input": <parsed JSON>}}
event: content_block_stop
data: {"index": K}
The message_delta then carries stop_reason: "tool_use" and message_stop closes the stream. Each block is emitted at a fresh index (the position in the assembled list), so multi-tool-call OpenAI traffic round-trips to multiple Anthropic tool_use blocks at distinct indices.
Edge cases:
- If an OpenAI delta arrives with a new
index, a new slot is allocated. - If an existing slot receives a non-empty
idmid-stream, atool_call_id_changedwarning is appended and the new id is re-registered; callers should not update the id mid-stream. tool_calls[*].function.argumentsis accumulated verbatim and parsed atfinish_reason: "tool_calls". On parse failure, the raw string is wrapped in{"__raw_arguments__": "<string>"}and amalformed_tool_argumentswarning is emitted.
Anthropic's pause_turn stop_reason signals that the model paused mid-turn (typically to wait for a long-running tool). EggPool surfaces this to OpenAI clients by mapping stop_reason: pause_turn to finish_reason: "tool_calls" and appending a synthetic sentinel entry to message.tool_calls:
{
"id": "call_pause_turn_<request_id>",
"type": "function",
"function": {
"name": "__eggpool_pause_turn__",
"arguments": "{}"
}
}OpenAI clients detect the sentinel by name (__eggpool_pause_turn__) and resume the turn with the same tool_use_id they received from the original Anthropic content_block_start. The sentinel is emitted on both streaming and non-streaming paths, with a pause_turn loss warning appended in each case.
A pause_turn loss warning is also appended to TranscodeContext.loss_warnings whenever the sentinel is synthesized, so operators can audit how often pause-and-resume flows happen against their upstreams.
OpenAI's stream_options.include_usage flag has no Anthropic analogue, so the wrapper object is dropped with a dropped_field warning when transcoding to an Anthropic upstream. The single field inside (include_usage: bool) is significant for usage accounting, so the transcoder lifts it onto TranscodeContext.request_include_usage before the streaming transcoder runs. The streaming transcoder reads request_include_usage from the context to decide whether to forward upstream usage chunks to the OpenAI client. The reverse direction (Anthropic → OpenAI) does not need this: OpenAI clients receive usage only when stream_options.include_usage was set on the request, which it wasn't.
Anthropic thinking_delta events translate to OpenAI reasoning delta fields. The field names are configurable via [transcoder.openai_reasoning_fields]: stream_delta (default ["reasoning"]) controls streaming field names. Order is preserved: thinking comes before tool_use comes before text in Anthropic, and reasoning content comes before content in OpenAI.
| Upstream event | Emitted client delta |
|---|---|
content_block_start (type: thinking) |
(none; block is started lazily) |
content_block_delta (type: thinking_delta, thinking: <text>) |
delta.<reasoning_field>: <text> |
content_block_stop (thinking index) |
(nothing) |
When [transcoder.features].thinking = false, streaming thinking deltas are dropped (consistent with non-streaming behavior). When emit_compat_aliases = true, multiple field names are emitted per delta.
Thinking deltas and text deltas are emitted independently: a stream may contain both reasoning and content chunks on the same request.
EggPool makes the JSON field names used for reasoning content configurable via [transcoder.openai_reasoning_fields]. This controls both non-streaming and streaming output.
[transcoder.openai_reasoning_fields]
non_stream = ["reasoning_content"] # message field(s) for reasoning
stream_delta = ["reasoning"] # delta field(s) for reasoning
emit_compat_aliases = false # emit extra aliases?The first entry in each list is always emitted. Additional entries are only included when emit_compat_aliases = true. This is useful for clients that recognize different field names.
Non-streaming: OpenAIToAnthropic.decode_response emits reasoning content in the configured non_stream field(s) on choices[].message.
Streaming: AnthropicToOpenAIStreaming emits reasoning deltas in the configured stream_delta field(s) on choices[].delta. Streaming is feature-gated consistently with non-streaming: when [transcoder.features].thinking = false, streaming thinking deltas are dropped with no output.
The following kind values may appear on TranscodeContext.loss_warnings:
kind |
Emitted when | Example fields |
|---|---|---|
tool_call_id_translated |
The id map mints a fresh id on either side of the translation | field, from, to |
tool_call_id_changed |
A streaming delta re-supplies a non-empty id for an existing tool_call slot |
field, from, to |
parallel_tool_calls_collapsed |
parallel_tool_calls: false cannot be sent because target capability is unverified |
field, reason |
malformed_tool_arguments |
tool_calls[*].function.arguments or content[].tool_use.input fails to JSON-parse |
field, value_type, length, reason |
invalid_tool_choice |
A tool_choice value cannot be mapped to the target shape |
field, optional from |
unsupported_tool_type |
A tools[i].type other than "function" is dropped |
field, from |
empty_tool_use_block |
Anthropic stop_reason: tool_use produced zero tool_use blocks |
field |
media_tool_result_flattened |
Non-text media inside a tool_result block was flattened to text because the target does not support media-bearing tool results |
field |
tool_result_error_passthrough |
Anthropic tool_result.is_error was forwarded as OpenAI tool content + warning (no is_error field in OpenAI shape) |
field |
cache_control_feature_disabled |
Top-level Anthropic cache_control was dropped because OpenAI has no equivalent field |
field |
cache_control_unsupported_by_target_protocol |
A nested cache_control annotation (system block, message block, tool definition) was dropped because the target protocol cannot carry it |
field |
cache_control_invalid_shape |
A cache_control annotation was malformed (missing or non-string type) and could not be carried across |
field |
provider_extension_not_preserved |
A non-portable vendor extension on an Anthropic tool (e.g. defer_loading) was dropped during translation |
field |
stable_prefix_preserved |
The provider-visible stable prefix round-trips without reordering; upstream cache hints should remain valid | field |
stable_prefix_reordered_canonically |
The stable prefix was reordered to canonical key order before wire serialisation; the upstream will treat this as a new cache key but content is identical | field |
pause_turn |
stop_reason: pause_turn was mapped to finish_reason: tool_calls plus a sentinel tool_call |
field, to |
non_text_content_dropped |
A non-text content part inside a translated message was dropped | field |
image_unsupported_format |
An image URL had an unrecognised scheme (not data: or https:) |
field |
image_too_large |
An image exceeded the 5 MB size limit | field, size |
pdf_too_large |
A PDF document exceeded the 32 MB size limit | field, size |
document_url_dropped |
An Anthropic document with a URL source was dropped (OpenAI has no PDF URL intake) | field |
document_unsupported_media |
An Anthropic document had a non-PDF media type and was dropped | field, media_type |
thinking_signature_dropped |
An Anthropic thinking block's cryptographic signature was dropped during translation | field |
reasoning_content_dropped |
A thinking/reasoning content block was dropped because the feature was disabled | field |
anthropic_top_level_thinking_dropped |
The Anthropic top-level thinking block was dropped when transcoding to OpenAI (no verified mapping) |
reason |
response_format_to_system_prompt |
An OpenAI response_format was coerced to a system-prompt instruction |
field |
top_k_dropped |
Anthropic top_k was dropped (OpenAI has no top-k sampling knob) |
field |
budget_clamped |
A thinking budget was clamped to the provider's maximum | requested, resolved |
unknown_effort |
A reasoning_effort value could not be mapped to a budget |
effort |
budget_rejected |
Strict policy rejected an unresolvable thinking budget | requested, policy |
budget_resolution_no_input |
Budget resolution was requested but no input was provided | policy |
The complete catalogue lives in the Rust wire-adaptation registry.
Loss warnings are safe to emit to ordinary logs: malformed tool arguments and inputs are represented by structural metadata only. Raw request content is never included in warning objects or transcode observability logs.
| Protocol | Status code field | Error type field | Message field | Request ID field |
|---|---|---|---|---|
| OpenAI | HTTP status | error.type |
error.message |
request_id |
| Anthropic | HTTP status | type |
error.message |
request_id |
Error types are mapped bidirectionally:
| Anthropic error type | OpenAI error type |
|---|---|
invalid_request_error |
invalid_request_error |
authentication_error |
invalid_api_key |
permission_error |
insufficient_quota |
not_found_error |
invalid_request_error |
request_too_large |
invalid_request_error |
rate_limit_error |
rate_limit_exceeded |
api_error |
api_error |
overloaded_error |
api_error |
billing_error |
insufficient_quota |
timeout_error |
timeout |
conflict_error |
invalid_request_error |
internal_error |
api_error |
Both protocols are normalised to a common internal representation before reaching the cost calculator:
| Canonical field | OpenAI source | Anthropic source |
|---|---|---|
prompt_tokens |
prompt_tokens |
input_tokens |
completion_tokens |
completion_tokens |
output_tokens |
total_tokens |
total_tokens |
Computed (input + output) |
cache_creation_tokens |
N/A | cache_creation_input_tokens |
cache_read_tokens |
N/A | cache_read_input_tokens |
Cache token fields are only populated for Anthropic upstreams.
For request finalization and dashboard accounting, streaming and non-streaming responses use the same protocol-specific usage extractors. Malformed, negative, or non-finite token counts are passed through the shared token-count coercion path and treated as zero for internal cost/quota calculation. The downstream response body is not rewritten solely for accounting normalization.
Transcoding is triggered when the client protocol differs from the selected account's upstream protocol. Providers that need transcoding:
| Provider | Upstream protocol | When transcoding fires |
|---|---|---|
| Anthropic | Anthropic | Client sends OpenAI requests to a model routed to an Anthropic account |
| OpenAI | OpenAI | Client sends Anthropic requests to a model routed to an OpenAI account |
| OpenRouter | OpenAI | Same as OpenAI: Anthropic clients hitting OpenRouter models |
| DeepSeek | OpenAI | Anthropic clients hitting DeepSeek models |
| Together AI | OpenAI | Anthropic clients hitting Together models |
| Google Gemini | OpenAI | Anthropic clients hitting Gemini models |
Providers that support both protocols natively (like OpenCode Go) may never trigger transcoding if accounts are configured with the right protocol flags.
When prefer_native = true (the default), the router uses native protocol as a tie-breaker inside the selected routing_priority tier. Transcoding still fires when no native account is available, when a transcodable account has a better quota score, or when a higher-priority provider tier is transcodable.
For production deployments using transcoding:
-
Review your client mix. If every client and every selected upstream account already speak the same protocol, transcoding will stay idle even though it is enabled.
-
Set
loss_policy = "warn"first. Run in warn mode for at least a week to see what fields are being dropped. Check logs fortranscode.loss_warningsentries. -
Audit loss warnings. If a dropped field is critical for your use case (e.g.,
top_kfor Anthropic-specific tuning), either:- Switch to a native-protocol provider for that model, or
- Accept the loss and document it for your users.
-
Test streaming. Streaming transcoding is the most complex path. Verify with a real streaming client that:
- Text content arrives correctly.
finish_reason/stop_reasonis correct.- Usage values appear in the final chunk.
- Tool-call deltas arrive in insertion order and terminate with
finish_reason: "tool_calls"plus[DONE]. For tool-using requests against Anthropic-only upstreams, ensure the synthetic__eggpool_pause_turn__sentinel (if any) is detected and surfaced to the application logic.
-
Check your dashboard. The Runtime page shows a Transcoding card with total transcoded requests, direction breakdown, and top loss warnings. Monitor this after adding cross-protocol providers or clients.
-
Verify
prefer_native. Withprefer_native = true, native-protocol accounts win score ties inside the selected priority tier.routing_prioritystill selects the provider tier before this tie-breaker runs. Setprefer_native = falseonly if quota score alone should decide same-tier native-versus-transcoded ordering. -
Set
loss_policy = "reject"only if you've confirmed no critical request fields are dropped. In reject mode, lossy request-body translation returns a 400 before dispatch. Loss warnings discovered while decoding upstream responses are still logged and shown in diagnostics.
Every loss warning is a structured dict with at minimum kind and field. The possible kind values:
kind |
Meaning | Example |
|---|---|---|
dropped_field |
A field was removed because the target protocol has no equivalent | {"kind": "dropped_field", "field": "top_p", "reason": "anthropic_unsupported"} |
missing_field |
A required field was absent and a default was inserted | {"kind": "missing_field", "field": "max_tokens", "default": 4096} |
value_clamped |
A value was adjusted to fit the target protocol's range | {"kind": "value_clamped", "field": "temperature", "from": 2.0, "to": 1.0} |
lossy_mapping |
A value was mapped but semantics changed | {"kind": "lossy_mapping", "field": "stop_reason", "from": "stop_sequence", "to": "stop"} |
inserted_field |
An empty or missing structure was synthesised | {"kind": "inserted_field", "field": "messages", "reason": "empty_messages"} |
tool_call_id_translated |
The id map minted a new id on either side of the translation | {"kind": "tool_call_id_translated", "field": "messages[assistant].tool_calls[].id", "from": "call_…", "to": "toolu_…"} |
tool_call_id_changed |
A streaming delta re-supplied a non-empty id for an existing tool_call slot |
{"kind": "tool_call_id_changed", "field": "tool_calls[]", "from": "call_X", "to": "call_Y"} |
parallel_tool_calls_collapsed |
parallel_tool_calls: false was dropped (no Anthropic equivalent) |
{"kind": "parallel_tool_calls_collapsed", "field": "parallel_tool_calls"} |
malformed_tool_arguments |
Tool argument JSON failed to parse; raw string delivered as __raw_arguments__ |
{"kind": "malformed_tool_arguments", "id": "call_…"} |
invalid_tool_choice |
A tool_choice value could not be mapped to the target shape |
{"kind": "invalid_tool_choice", "field": "tool_choice"} |
unsupported_tool_type |
A tools[i].type other than "function" was dropped |
{"kind": "unsupported_tool_type", "field": "tools[].type"} |
empty_tool_use_block |
Anthropic stop_reason: tool_use produced zero tool_use blocks |
{"kind": "empty_tool_use_block", "field": "content[].tool_use"} |
media_tool_result_flattened |
Non-text media inside a tool_result block was flattened to text |
{"kind": "media_tool_result_flattened", "field": "messages[tool].content"} |
tool_result_error_passthrough |
Anthropic tool_result.is_error was forwarded as OpenAI tool content + warning |
{"kind": "tool_result_error_passthrough", "field": "tool_result.is_error"} |
cache_control_feature_disabled |
Top-level Anthropic cache_control was dropped during Anthropic → OpenAI translation |
{"kind": "cache_control_feature_disabled", "field": "cache_control"} |
cache_control_unsupported_by_target_protocol |
A nested cache_control annotation (system block, message block, tool definition) was dropped because OpenAI cannot carry it |
{"kind": "cache_control_unsupported_by_target_protocol", "field": "tools[0].cache_control"} |
cache_control_invalid_shape |
A cache_control annotation was malformed and could not be carried across |
{"kind": "cache_control_invalid_shape", "field": "tools[0].cache_control"} |
cache_breakpoint_invalid_shape |
An OpenAI explicit breakpoint marker was malformed and was removed from the Anthropic target body | {"kind": "cache_breakpoint_invalid_shape", "field": "messages[0].content[0].prompt_cache_breakpoint"} |
provider_extension_not_preserved |
A non-portable vendor extension on an Anthropic tool was dropped during translation | {"kind": "provider_extension_not_preserved", "field": "tools[0].defer_loading"} |
stable_prefix_preserved |
The provider-visible stable prefix round-trips without reordering | {"kind": "stable_prefix_preserved", "field": "cache_control"} |
stable_prefix_reordered_canonically |
The stable prefix was reordered to canonical key order before wire serialisation | {"kind": "stable_prefix_reordered_canonically", "field": "cache_control"} |
pause_turn |
stop_reason: pause_turn was mapped to finish_reason: tool_calls plus a sentinel tool_call |
{"kind": "pause_turn", "field": "stop_reason", "to": "tool_calls"} |
non_text_content_dropped |
A non-text content part inside a translated message was dropped | {"kind": "non_text_content_dropped", "field": "messages[assistant].content"} |
image_unsupported_format |
An image URL had an unrecognised scheme (not data: or https:) |
{"kind": "image_unsupported_format", "field": "messages[user].content[image_url]"} |
image_too_large |
An image exceeded the 5 MB size limit | {"kind": "image_too_large", "field": "...", "size": 6291456} |
pdf_too_large |
A PDF document exceeded the 32 MB size limit | {"kind": "pdf_too_large", "field": "...", "size": 33554432} |
document_url_dropped |
An Anthropic document with a URL source was dropped (OpenAI has no PDF URL intake) | {"kind": "document_url_dropped", "field": "messages[user].content[document]"} |
document_media_type_unsupported |
An Anthropic document had a non-PDF media type and was dropped | {"kind": "document_media_type_unsupported", "field": "...", "media_type": "text/html"} |
unsupported_modality |
An entire modality (e.g. audio) is not representable by the target protocol | {"kind": "unsupported_modality", "field": "content[audio]", "modality": "audio"} |
unsupported_source_form |
A specific source form (base64 or URL) is not supported for the given media type | {"kind": "unsupported_source_form", "field": "content[image_url]", "source_form": "url"} |
thinking_signature_dropped |
An Anthropic thinking block's cryptographic signature was dropped during translation | {"kind": "thinking_signature_dropped", "field": "content[].thinking"} |
reasoning_content_dropped |
A thinking/reasoning content block was dropped because the feature was disabled | {"kind": "reasoning_content_dropped", "field": "content[].thinking"} |
response_format_to_system_prompt |
An OpenAI response_format was coerced to a system-prompt instruction |
{"kind": "response_format_to_system_prompt", "field": "response_format"} |
top_k_dropped |
Anthropic top_k was dropped (OpenAI has no top-k sampling knob) |
{"kind": "top_k_dropped", "field": "top_k"} |
budget_clamped |
A thinking budget was clamped to the provider's maximum | {"kind": "budget_clamped", "requested": 16384, "resolved": 8192} |
unknown_effort |
A reasoning_effort value could not be mapped to a budget |
{"kind": "unknown_effort", "effort": "xlow"} |
budget_rejected |
Strict policy rejected an unresolvable thinking budget | {"kind": "budget_rejected", "requested": 32768, "policy": "strict"} |
budget_resolution_no_input |
Budget resolution was requested but no input was provided | {"kind": "budget_resolution_no_input", "policy": "strict"} |
Additional context fields that may appear:
| Field | Present when |
|---|---|
reason |
Explains why (e.g., anthropic_unsupported, openai_unsupported, empty_messages) |
from / to |
Shows original and mapped value for value_clamped, lossy_mapping, tool_call_id_translated, tool_call_id_changed, pause_turn |
default |
Shows the synthetic default for missing_field |
id |
Tool-call id associated with the warning (e.g., malformed_tool_arguments) |
The complete catalogue lives in the Rust wire-adaptation registry.
| Scenario | Kind | Detail |
|---|---|---|
temperature > 1.0 → Anthropic |
value_clamped |
Clamped to 1.0 |
max_tokens missing from OpenAI request → Anthropic |
missing_field |
Defaulted to 4096 |
stop_sequence → OpenAI stop |
lossy_mapping |
Sequence identity lost |
pause_turn → OpenAI tool_calls + __eggpool_pause_turn__ sentinel |
lossy_mapping + pause_turn |
Semantic change; see Tool-Use Transcoding |
model_context_window_exceeded → OpenAI length |
lossy_mapping |
Cause obscured |
parallel_tool_calls: false → Anthropic |
parallel_tool_calls_collapsed |
Target lacks verified parallel-tool control |
tools[].function.strict → Anthropic |
strict_tool_capability_missing |
Target lacks verified strict-tool support |
tools[].cache_control → OpenAI |
cache_control_unsupported_by_target_protocol |
Chat Completions has no tool-definition breakpoint placement; selected-provider contracts cannot relocate it |
Top-level cache_control → OpenAI |
cache_control_feature_disabled |
OpenAI has no equivalent field; loss is policy-driven |
messages[].content[].cache_control → OpenAI |
(preserved when capability is verified) | Otherwise the boundary is reported as cache_control_unsupported_by_target_protocol; tool-definition boundaries remain unrepresentable |
tools[].cache_control (OpenAI-side extension) → Anthropic |
(preserved) | Boundary annotated preserved on TranscodeContext.cache_boundary_tracker |
Non-portable Anthropic tool fields (defer_loading, etc.) → OpenAI |
provider_extension_not_preserved |
Vendor extensions have no OpenAI equivalent |
function_call / functions (deprecated OpenAI API) |
dropped_field |
Deprecated; clients should migrate to tools |
Tool-call id rewritten (call_… ↔ toolu_…) |
tool_call_id_translated |
Map is per-request, never collides across requests |
reasoning_effort → Anthropic thinking budget_tokens |
lossy_mapping |
Heuristic mapping (low→1024, medium→4096, high→16384) |
| Thinking block signature → OpenAI | thinking_signature_dropped |
Cryptographic receipt cannot be re-fed to OpenAI |
response_format: json_object → Anthropic system prompt |
response_format_to_system_prompt |
Best-effort coercion; no schema is available for native output |
Image input_audio / file → Anthropic |
dropped_field |
No Anthropic equivalent for OpenAI audio/file parts |
Anthropic document (non-PDF) → OpenAI |
document_unsupported_media |
OpenAI file intake limited to PDF |
Anthropic document (URL) → OpenAI |
document_url_dropped |
OpenAI has no PDF URL intake |
- Body translation: a bounded in-process Rust transformation: no I/O or network calls.
- Streaming translation: One state machine per request. The state machine processes SSE frames incrementally: no buffering of the full stream.
- Memory: The shared decoder bounds each incomplete line/event to 64KB; the transcoder retains only protocol state and bounded tool/reasoning buffers.
- No additional network hops: Transcoding happens inside the existing request path. There is no sidecar or proxy.
The overhead is negligible compared to upstream latency (typically 200ms–30s). You will not measure a difference in p99 latency from transcoding alone.
The streaming transcoder path is optimised to minimise per-chunk event-loop pressure when many transcoded streams are in flight concurrently:
- Shared frame fan-out: The coordinator's bounded
SSEDecoderowns the only UTF-8/SSE framing pass. It sends eachDecodedSSEFrametoIncrementalSSEObserverand the transcoder; the transcoder no longer parses raw bytes. Shared frames lazily cache JSON objects, so usage extraction and translation do not repeat a parse. The transcoder'susageproperty returns a defaultStreamUsageResult(); callers should always read usage from the coordinator's observer. - Synchronous frame translation: The streaming transcoder's
per-frame work (cached JSON parsing, nested map construction,
serde_jsonserialization) performs no async I/O, so spawning an async task per chunk is unnecessary scheduler overhead. Any future implementation that requires async I/O must not be placed in this per-chunk path without a separate design review. - Coalesced per-chunk output: The coordinator joins the bytes the
transcoder produces for one upstream chunk into a single
body write rather than yielding each translated
frame separately. This preserves wire ordering and granularity while
reducing Hyper body writes.
[DONE]and the terminalmessage_delta/message_stopframes are still emitted in the correct order. - Single-pass
include_usage:upstream_include_usageis computed once during streaming dispatch setup (after any injection of OpenAIstream_options.include_usage) and threaded into the stream generator via an explicit parameter. The generator no longer re-parses the request body to determine the include-usage behaviour. - Compact JSON frames: Frame helpers use
compact
serde_jsonserialization (no extra whitespace). SSE clients parse the JSON payload and never rely on preserved whitespace, so this reduces both output bytes and serialization work.
Streaming codec contracts are covered by the Rust integration targets under
rust/tests/, including wire_stream.rs and wire_codecs.rs. Use the native
Cargo test flow for replay and terminal-evidence checks.
Provider-visible prompt caching (Anthropic's cache_control breakpoints) is observational in v1: the transcoder preserves or annotates every cache_control event but never reorders key material, mutates prompt content, or synthesises cache hints that the caller did not provide. Two helpers make the cache surface explicit:
rust/src/wire/owns the per-request cache-boundary tracker, structural boundary extraction, provider-visible prefix handling, and deterministic hashing.
Cache-boundary annotation kinds emitted by the tracker:
| Kind | Meaning |
|---|---|
preserved |
Cache annotation carried across at the same path with the same cache_control_type. |
preserved_relocated |
Reserved for future phases that rewrite the annotation onto a different target path. |
dropped_unsupported_target |
The target protocol cannot carry this annotation (e.g. OpenAI has no cache_control). |
dropped_feature_disabled |
Operator-disabled preservation path; the annotation was discarded by policy. |
dropped_invalid_shape |
The annotation failed shape validation (missing or non-string type). |
synthesized |
Reserved for future phases that synthesise cache hints on behalf of the caller. |
Operators can read the boundary tracker through structured loss warnings
(stable_prefix_preserved, stable_prefix_reordered_canonically,
cache_control_*). Routing does not consume these annotations; cache
observability is reporting-only.
When the operator has set loss_policy = "reject" on [transcoder], the body transcoder raises the Rust wire-adaptation error (rendered as HTTP 400 with invalid_request_error) before upstream dispatch whenever any of the protected loss kinds is recorded:
| Kind | When fired |
|---|---|
cache_control_unsupported_by_target_protocol |
The target protocol has no cache_control primitive and the annotation could not be carried across. |
cache_control_feature_disabled |
The operator disabled cache_control preservation (the top-level cache_control feature gate). |
cache_control_invalid_shape |
The annotation lacked a string type field and was rejected by shape validation. |
provider_extension_not_preserved |
A non-portable vendor field (e.g. defer_loading) on an Anthropic tool could not be carried into the OpenAI wire. |
stable_prefix_reordered_canonically |
Source and target cache boundary lists diverge: the prefix was canonically reordered. |
unsupported_modality |
An entire modality (e.g. audio) is not representable by the target protocol. |
unsupported_source_form |
A specific source form (base64 or URL) is not supported for the given media type by the target provider. |
media_tool_result_flattened |
Non-text media inside a tool result was flattened to text because the target does not support media-bearing tool results. |
document_media_type_unsupported |
A document media type (e.g. non-PDF) is not supported by the target provider. |
The warn default preserves the v1 behaviour: the request proceeds and the
loss is recorded for audit. The transcoder never injects warning text into the
translated body.
The transcoder depends on the upstream pricing catalogs (OpenRouter, OpenCode Zen, ...) that the resolver pipeline caches per catalog. Each TTLCache is bounded by a configurable max_entries knob (default 4096, LRU eviction on store). Unparsed raw payloads are stripped after the catalog is parsed so the cache footprint stays small even with hundreds of models in the upstream catalog.
[pricing.catalogs.openrouter]
enabled = true
priority = 100
ttl_seconds = 86400
max_entries = 4096 # bound the in-memory catalog cache; oldest entries evict firstLower max_entries to trade catalog completeness for steady-state RSS on memory-constrained hosts (Raspberry Pi, SBC). The OpenRouter catalog ships ~250+ entries today, so the default has plenty of headroom.
-
Headers preserved verbatim. Upstream response headers are passed through to the client without translation. Some Anthropic-specific headers (e.g.,
anthropic-ratelimit-*) may leak to OpenAI clients. This is cosmetic and harmless. -
All-or-nothing per deployment. When
enabled = true, transcoding applies to every account. Per-account opt-out is not supported in v1. -
No partial translation. If a request contains both translatable and non-translatable features (e.g., text + vision content), the entire request is translated. Non-translatable request parts are dropped with warnings: the transcoder refuses the request only when
loss_policy = "reject". -
loss_policy = "reject"is opt-in and strict for requests. Any single request translation loss warning causes a 400 response before upstream dispatch. This can be surprising: use warn mode first to audit. -
Anthropic error types are best-effort. The error type mapping covers the common cases but not every edge case. Unrecognised error types map to
api_error(Anthropic) orinvalid_request_error(OpenAI). -
Usage values are upstream-authoritative. If the upstream reports unusual usage (e.g., negative cache tokens), the transcoder passes them through. There is no sanitisation.
-
Tool-call id remapping is opaque to clients. Every cross-protocol tool call has its id rewritten (
call_…↔toolu_…) by theid_map. Clients that compare ids across turns see the rewritten id, not the original. The mapping is per-request so concurrent requests never collide. -
pause_turnis surfaced as a sentinel tool call. Anthropic'spause_turnstop_reason becomesfinish_reason: "tool_calls"plus a synthetic__eggpool_pause_turn__tool_call entry. OpenAI clients detect the pause by name and resume with the sametool_use_id. -
Structured outputs are capability-gated. Verified Anthropic targets receive native
output_config.formatJSON-schema output. Unverified targets use the explicitly lossy prompt fallback (or reject underloss_policy = "reject"), andjson_objectremains prompt-based because it carries no schema.
Check the boot log:
INFO Protocol transcoding ENABLED (default): clients may reach upstream accounts whose provider.protocols does not match the client protocol. loss_policy=warn prefer_native=true
If you see WARNING Protocol transcoding DISABLED, the [transcoder] enabled = false escape hatch is in effect and cross-protocol requests will fail.
Every transcoded request emits a structured INFO log:
INFO request_id=req_abc123 client_protocol=openai upstream_protocol=anthropic
account=anthropic-primary provider=anthropic native_match=false
loss_warnings=2
Key fields:
client_protocol/upstream_protocol: confirms translation is happeningnative_match=false: means the request was transcoded (true = no translation needed)loss_warnings: count of dropped fields / lossy mappings for this request
Search for dropped_field, value_clamped, or lossy_mapping in structured logs. Each entry includes the request ID and field name.
The Runtime page (/runtime) includes a Transcoding card showing:
- Total transcoded requests
- Direction breakdown (OpenAI→Anthropic vs Anthropic→OpenAI)
- Top loss warnings by kind and field
eggpool stats transcoding --period 7d
eggpool stats transcoding --period 30d --jsonGET /api/stats/transcoding?period=24h returns the same counters as the
Runtime card. JSON responses encode direction keys as strings such as
"openai→anthropic" under per_direction; internal tuple keys are never
exposed on the API surface.
Set enabled = false in [transcoder] and restart. All requests will now require protocol match: a client speaking OpenAI to an Anthropic-only account will get a protocol mismatch error. This option is deprecated; transcoding will become unconditionally on in a future release.
- Find the
request_idfrom the per-request log or dashboard. - Search logs for that request ID.
- Look for
loss_warnings: each entry tells you which field was dropped and why. - If the issue is a missing field, check the translation tables above to understand what the transcoder does and does not support.