fix: make the Anthropic surface conform to the real SDK wire contract (#1274, #1260, #1261, #1259)

[sakibsadmanshajib]

Closes #1274. Closes #1260. Closes #1261. Closes #1259.

Are these one root cause or four?

Two families, not one, and not four independent fixes.

Family A, Go zero-value JSON encoding dropping values the Anthropic contract requires to be present (#1274 and #1260). Both are the gateway emitting a valid Go zero value where Anthropic requires an explicit empty one, and in both cases the Go-side assertion a normal test would write cannot see the defect at all: len(content) == 0 is true for a nil slice and an empty one alike, and a Text field set to "" looks correct right up until encoding/json runs. The mechanism differs (omitempty on a string in one, a nil slice with no tag in the other), so it is one class with two instances rather than a single line to change.

Family B, an auth model that only ever covered POST /v1/messages (#1261 and #1259). Every other route on the Anthropic surface was left to inherit an auth path built for a different dialect. count_tokens is the only route here that does not delegate to the chat chain, so it never gained the API-key authority that chain provides, and GET /v1/models was never given the leaf APIKeyNormalizer that /v1/messages has carried since #954. The two share a cause but not a line of code.

#1259 additionally carries a response-shape defect that belongs to neither family: the route answered an Anthropic client with the OpenAI list envelope and the OpenAI error envelope. Fixed here in the same pass, since fixing only the auth half would have moved the failure one step later.

Ground truth

API shapes were verified against the live specification on 2026-08-28, not from model memory, per the repository rule.

• https://docs.claude.com/en/docs/build-with-claude/streaming shows content_block_start as {"type":"text","text":""} for a text block and {"type":"tool_use","id":...,"name":...,"input":{}} for a tool_use block, in every one of its five worked examples.
• https://docs.claude.com/en/api/models-list shows the list envelope as data (entries of type/id/display_name/created_at) plus has_more, first_id and last_id, the last two typed "string or null".
• The SDK's own accumulator (anthropic/lib/streaming/_messages.py, accumulate_event) was read directly to confirm the failure mechanism: it does content.text += event.delta.text for a text_delta, which is the None += str crash, and for an input_json_delta it assigns content.input from its own jiter buffer rather than reading the block-start value. That is why the missing text was fatal and the missing input was not, and it is why this PR treats the two differently in its claims.

openwolf bug search anthropic and openwolf bug search omitempty both returned no prior entries.

What changed

Issue	Change
#1274	StreamContentBlock.Text is now *string so the empty string serializes, following the precedent StreamEvent.Index already set in this same struct for the identical reason. Input json.RawMessage added and set to {} on a tool_use block start.
#1260	FromOAIResponse seeds Content with an empty non-nil slice at construction and appends into it, which covers the early len(resp.Choices) == 0 return as well as the normal path.
#1261	anthropic.Deps.AuthorizeAPIKey added; count_tokens accepts a JWT session principal or an API-key principal. Nil leaves it session-only and fail-closed. The refusal is the authorizer's own verdict run through the shared WriteAuthFailure status mapping and then reshaped into the Anthropic envelope, so no status logic is duplicated.
#1259	GET /v1/models is registered through a named modelsHandler applying anthropic.APIKeyNormalizer at the leaf and anthropic.ModelsCompat for shape.

Why the leaf normalizer on /v1/models is not redundant

authSelectorMiddleware already wraps every /v1/* route in APIKeyNormalizer (#954), but only when JWT auth is wired: handler = authSelectorMiddleware(jwtMW, handler) sits behind if jwtMW != nil. On a deployment where Supabase JWT config is absent, edge-api logs "JWT auth wiring skipped" and mounts no selector at all, so nothing normalizes x-api-key and handleModels reads an empty Authorization header. /v1/messages kept working there purely because it carries its own leaf wrapper. That asymmetry is exactly the reported symptom in #1259 (same key, same connection, /v1/messages fine and /v1/models 401) and it is why the fix is a leaf wrapper rather than a change to the selector.

Provider-blind invariant

The ModelsCompat translation reads id, created and name and writes type, id, display_name and created_at. owned_by and every other OpenAI field are dropped rather than passed through, so this strictly reduces what reaches an Anthropic client. TestModelsCompat_AnthropicClientGetsTheAnthropicListShape asserts owned_by is absent from the body. Nothing on any path touched here emits a provider name, an upstream id or a system_fingerprint; the existing TestHandleModelsDoesNotLeakProviderNames and TestSSETranslator_MessageID_NeverLeaksUpstreamID guards are unchanged and still pass.

Mutation check

Every added test was proved load-bearing by reverting the fix it guards and observing it fail for the right reason, then restoring and observing it pass. Full transcript, six mutations, all red, then green on restore:

#	Mutation applied	Test	Result
1	StreamContentBlock.Text back to a plain string, call site back to Text: ""	TestSSETranslator_TextBlockStartCarriesExplicitEmptyText	FAIL: text content_block_start omits the "text" key entirely ... map[type:text]
2	Delete Input: json.RawMessage("{}") from the tool_use block start	TestSSETranslator_ToolUseBlockStartCarriesExplicitEmptyInput	FAIL: tool_use content_block_start omits the "input" key: map[id:call_1 name:get_weather type:tool_use]
3	Delete the Content: []ResponseBlock{} seed	TestFromOAIResponse_EmptyCompletionSerializesContentAsArray	FAIL on both subtests: got {... "content":null ...}
4	if h.deps.AuthorizeAPIKey == nil forced to if true, i.e. count_tokens back to session-only	TestHandler_CountTokens_AcceptsAPIKeyPrincipal, ..._RejectedAPIKeyKeepsTheAuthorizersOwnRefusal	FAIL: want 200 got 401 body={"type":"error","error":{"type":"authentication_error","message":"missing user"}}, and error.message: want the authorizer's own refusal got missing user
5	if !IsAnthropicClient(r) forced to if true, i.e. never re-shape	TestModelsCompat_* (3 tests)	FAIL: OpenAI body passed through, first_id/last_id nil, envelope: want top-level type=error got <nil>
6	modelsHandler unwrapped to return handleModels(client, authorizer)	TestModelsHandlerServesAnAnthropicSDKClient	FAIL: x-api-key caller: want 200 got 401: {"error":{"message":"You didn't provide an API key...

After restoring all six, go test ./apps/edge-api/internal/anthropic/... ./apps/edge-api/cmd/server/... is ok for both packages, and the wider go test ./apps/edge-api/... -count=1 -short passes with no failures. gofmt -l reports none of the touched files.

Four of the added tests are deliberately non-regression guards rather than defect guards, and do not go red under any mutation above. The count said two on first posting and was corrected in review; the table is the record anyone reads later, so it should say what is actually true.

• TestModelsCompat_OpenAIClientIsUntouched and TestModelsHandlerKeepsTheOpenAIShapeForOpenAIClients exist to fail if a later change starts re-shaping unconditionally and empties Open WebUI's model picker. Both compare byte-identical bodies, so the inverse mutation of always reshaping does turn them red.
• TestHandler_CountTokens_WithoutAnAPIKeyAuthorityFailsClosed stays green under mutation 4, since a handler wired without an API-key authority writes 401 either way. It pins the fail-closed default and goes red if someone makes a nil authority permissive.
• TestHandler_CountTokens_SessionPrincipalDoesNotConsultTheAPIKeyAuthority also stays green under mutation 4, since the session branch returns before the nil check is reached. It goes red if the two principal checks are ever reordered.

TestIsAnthropicClient is a unit test of a new pure function that none of the six mutations touch, so it is neither a defect guard nor a non-regression guard for anything in the table.

Review round two

Three findings from review, all fixed in 25b2820, all in apps/edge-api/internal/anthropic.

Refusal retry headers were being dropped. apierrors.WriteAuthFailure is the shared source of truth precisely so a retryable 429 is never collapsed into a non-retryable refusal, and it delivers the retryable part through headers rather than the body: retry-after plus the four x-ratelimit-* values on a real 429, and retry-after on both the degraded-limiter branch and the upstream_unavailable branch. Recording the refusal in a headerlessRecorder and reshaping only its body threw all of that away. count_tokens lost it latently, and GET /v1/models lost it live through authorizeAliasRequest, which also left the two client shapes disagreeing about retry metadata for the same refusal on the same route. headerlessRecorder.reshapeInto now carries the headers over and reshapes in one call, so a call site cannot take one half of a refusal without the other. Content-Type and Content-Length are deliberately not carried: the reshaped body is a different envelope of a different length, and a stale Content-Length would truncate it on the wire. Everything that is forwarded is retry metadata and carries no provider identity, so the provider-blind invariant is unchanged.

GET /v1/models served two representations for one URL without declaring it. Nothing on the route sets Cache-Control and the route needs a credential, so no correct cache stores it today and no live exploit exists. The declaration is what keeps a later edge cache in front of Caddy, or an intermediary keying on URL alone, from handing an Anthropic-shaped body to Open WebUI and emptying its model picker, which is the regression TestModelsCompat_OpenAIClientIsUntouched exists to prevent. Vary: anthropic-version, x-api-key is now set on both branches, before either writes.

Finish could emit message_delta before any message_start. Translate calls Finish unconditionally and Finish did not check t.started, so an upstream stream that yielded no parseable chunk at all produced a terminal pair with nothing before it, and the SDK accumulator raises an unexpected-event-order error when a message_delta arrives while its snapshot is still nil. Review suggested a follow-up issue for this rather than widening the PR; the fix turned out to be three lines in a file this PR already changes, which is smaller than the issue describing it, so it is taken here. FeedLine and Finish now share one ensureStarted, which emits message_start exactly once per stream whichever of them reaches it first.

Four more mutations, each applied alone, each restored after:

#	Mutation applied	Test	Result
7	reshapeInto's header loop forced to skip every key	TestHandler_CountTokens_RefusalCarriesTheAuthorizersRetryHeaders, TestHandler_CountTokens_UpstreamUnavailableCarriesRetryAfter, TestModelsCompat_RefusalCarriesTheRetryHeaders	FAIL: retry-after: want 30 got "", retry-after: want 5 got "", and the three x-ratelimit-* assertions on both routes
8	Content-Length removed from the skip list, so the delegated body's length is forwarded	TestModelsCompat_RefusalCarriesTheRetryHeaders	FAIL: content-length: the delegated body length must not describe the reshaped one, got "4096"
9	The Vary line deleted	TestModelsCompat_DeclaresVary	FAIL on both subtests: vary: want both request headers that select the representation, got ""
10	ensureStarted removed from Finish	TestSSETranslator_EmptyStreamStillOpensTheMessage	FAIL: first event: want message_start got message_delta

TestSSETranslator_FinishAfterAStartedStreamDoesNotRepeatMessageStart is a fifth non-regression guard: it stays green under all ten mutations and exists so that opening the message from Finish can never add a second message_start to a stream that already carried one.

Adversarial review of the round-two fixes

The round-two commit went back through the review pipeline before this was called done. Two findings, both fixed in f0e4c56.

The Vary declaration used Set where it should use Add. Nothing in edge-api declares a Vary on this route today (grep finds exactly one writer, the new line itself), so overwriting was harmless in the current tree and wrong the moment an outer middleware declares one of its own, a CORS layer setting Vary: Origin being the obvious case. The wrapper is now additive.

The 2xx branch of ModelsCompat dropped every header the delegated handler set. That path re-encodes the body rather than reshaping it, which is exactly why the carry-over the refusal path had just gained was easy to leave out of it. A header set alongside a success is as much part of that response as the body is, and this route is where a 2xx rate-limit budget would surface. The header copy is now its own method on the recorder, copyHeadersTo, and both branches call it.

#	Mutation applied	Test	Result
11	Vary back to Set	TestModelsCompat_VaryDoesNotClobberAnExistingDeclaration	FAIL: vary: want "Origin" preserved, got "anthropic-version, x-api-key"
12	rec.copyHeadersTo(w) deleted from the success branch	TestModelsCompat_SuccessCarriesTheDelegatedHeaders	FAIL: x-ratelimit-remaining-requests: want 42 got ""

On display_name and the provider-blind edge

Review confirmed independently that the ModelsCompat translation is provider-blind (it reads id, created and name only, so owned_by and description cannot ride along) and flagged the remaining edge: display_name is model_aliases.display_name, free text, and one seeded row already reads Openrouter Auto (Task Aware). That row is visibility='internal' today, so the visibility IN ('public', 'preview') predicate keeps it off both list paths, but the migration that added it describes a later flip to public as a one-line follow-up.

Nothing here closes #1284, and this PR never claimed to: the OpenAI branch is unchanged and still ships the hive-stt and hive-tts descriptions that #1284 reports. The display_name edge is recorded as a comment on #1284 rather than a new issue, since it is the same route and the same family, and the guard it asks for (assert no listed alias's display_name or summary matches a known provider name) belongs where the catalog is listed, not in this translation.

Effect on #1278

This should flip all four xfail markers in packages/sdk-tests/python/tests/test_anthropic_messages.py to real assertions. Not touched here, since that branch is not mine to edit.

• test_streaming_event_sequence_integrity (Streaming content_block_start omits text field, crashing the real Anthropic SDK's stream accumulator on every text response #1274)
• test_tool_choice_none_forbids_tool_use (Anthropic /v1/messages returns content:null instead of content:[] on empty completions, breaking real SDK/typed clients #1260)
• test_count_tokens (POST /v1/messages/count_tokens 401s a valid Hive API key: session-only auth, no API-key path #1261)
• test_models_list (Anthropic /v1/models incompatible with real Anthropic SDK: wrong auth header accepted, wrong error envelope, OpenAI-shaped body #1259)

One caveat on the last one. client.models.list() will now authenticate and return the Anthropic list envelope, but the SDK's typed page model may expect fields this gateway has no source for. If that assertion still fails after this merges, it is a narrower follow-up about specific fields, not the auth and envelope defects #1259 reported.

Scope deliberately not taken

#1260 also observes that a zero-content streaming turn emits message_start, message_delta, message_stop with no content_block_start/stop pair. That is left alone: the streaming path already emits "content":[] in message_start, so an SDK folding the stream back into a message gets an empty array rather than null, and Anthropic's own specification does not require a content block on a turn that produced no content. The reported crash is in the non-streaming builder, which is what this changes.

The neighbouring case where message_start never fires at all is a different defect, was not what #1260 reported, and is now fixed here rather than deferred. See Review round two above.

Test plan

• go test ./apps/edge-api/... -count=1 -short through the toolchain container, green, re-run after the review-round-two fixes
• gofmt -l apps/edge-api clean for every touched file
• Twelve-way mutation check, all three tables above
• CI required checks green
• packages/sdk-tests Anthropic conformance suite re-run against a live stack once test: add Anthropic Messages API conformance suite using the real SDK #1278 merges, to confirm the four xfails flip

Buglog entry

{"id":"bug-2026-08-28-anthropic-sdk-wire-conformance","date":"2026-08-28","title":"Anthropic surface broke the real SDK four ways: content_block_start dropped text, empty completions serialized content null, count_tokens 401d API keys, /v1/models rejected x-api-key and answered OpenAI-shaped","error_message":"TypeError: unsupported operand type(s) for +=: 'NoneType' and 'str' in anthropic/lib/streaming/_messages.py accumulate_event; TypeError: 'NoneType' object is not iterable on msg.content; anthropic.AuthenticationError 401 {\"type\":\"error\",\"error\":{\"type\":\"authentication_error\",\"message\":\"missing user\"}} on count_tokens; anthropic.AuthenticationError 401 invalid_api_key on models.list()","root_cause":"Two families. (1) Go zero-value JSON encoding dropped values the Anthropic wire contract requires to be explicitly present: omitempty on StreamContentBlock.Text dropped the required \"text\":\"\" from every text content_block_start, and a nil []ResponseBlock in FromOAIResponse marshaled to null instead of []. Neither is visible to a Go-side assertion, since len() cannot distinguish nil from empty and a \"\" field looks correct until encoding/json runs. (2) The Anthropic surface's auth model only ever covered POST /v1/messages: count_tokens is the only route that does not delegate to the chat chain so it never gained an API-key authority and recognised session principals only, and GET /v1/models never got the leaf APIKeyNormalizer /v1/messages carries, which matters because the global one in authSelectorMiddleware only exists when jwtMW is non-nil.","fix":"StreamContentBlock.Text became *string and gained Input json.RawMessage set to {} on tool_use starts, matching the live streaming spec. FromOAIResponse seeds Content with an empty non-nil slice at construction so both exits are covered. anthropic.Deps.AuthorizeAPIKey added and count_tokens accepts either principal, fail-closed when nil, refusals reshaped from the shared WriteAuthFailure mapping. GET /v1/models registered through modelsHandler applying APIKeyNormalizer at the leaf plus a ModelsCompat wrapper that answers Anthropic-shaped callers with the Anthropic list and error envelopes while leaving OpenAI callers byte-identical.","tags":["anthropic","sdk-conformance","edge-api","json-encoding","omitempty","auth","streaming","provider-blind"],"issues":[1274,1260,1261,1259],"pr":"fix/anthropic-stream-content-block-start"}

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

Warning

Review limit reached

Next included review available in 40 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: dc79c1af-c639-48a1-b6a4-7e2c5c758244

📥 Commits

Reviewing files that changed from the base of the PR and between db6bace and f0e4c56.

📒 Files selected for processing (12)

• apps/edge-api/cmd/server/main.go
• apps/edge-api/cmd/server/main_test.go
• apps/edge-api/internal/anthropic/handler.go
• apps/edge-api/internal/anthropic/handler_test.go
• apps/edge-api/internal/anthropic/models.go
• apps/edge-api/internal/anthropic/models_test.go
• apps/edge-api/internal/anthropic/stream.go
• apps/edge-api/internal/anthropic/stream_test.go
• apps/edge-api/internal/anthropic/translate_response.go
• apps/edge-api/internal/anthropic/translate_response_test.go
• apps/edge-api/internal/anthropic/translate_writer.go
• apps/edge-api/internal/anthropic/types.go

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sakibsadmanshajib]

Reviewed this as the mandatory security pass, since it changes authentication on two routes. I verified the four fixes against the live specifications and the SDK source myself rather than re-deriving your work, and I traced the auth question end to end. Summary of where I landed, with detail in the inline comments.

Authority is not widened. For count_tokens I followed an hk_ request all the way through: auth.Selector sends it past the JWT middleware with no session user, the leaf APIKeyNormalizer on /v1/messages/ has already rewritten x-api-key into Authorization, and the new closure hands that header to the same authorizer.Authorize the rest of edge-api uses. CheckAccess still enforces key status, expiry and budget on that call; only the model allowlist is skipped, and only because aliasID is empty, which is exactly the precedent handleModels set for /v1/models. The limiter still runs. An invalid or revoked hk_ key gets a 401 carrying the authorizer's own message, which I confirmed is the authorizer's verdict and not a blanket string. What the route grants an API key is a len/4 estimate computed locally from the caller's own request body, with no catalog lookup, no tenant read and no dispatch, so there is no data an API key can reach here that it could not already reach. Nil AuthorizeAPIKey stays session only. For /v1/models the leaf normalizer changes the spelling of the credential, nothing else: same authorizer, same tenant filtered snapshot, and on a deployment with no JWT wiring the route is still fully authenticated because handleModels fails closed on an unresolvable tenant.

The client discriminator cannot be spoofed into revealing anything different. Both branches serve the same authorized snapshot.Models for the same principal, and the Anthropic branch carries a strict subset of the fields. Setting anthropic-version on a session request flips the shape but reveals strictly less. The OpenAI path is genuinely untouched: I grepped every in-repo consumer and nothing outside this PR's own tests sends anthropic-version or x-api-key at /v1/models, so Open WebUI, the console and the OpenAI SDK conformance suite all keep the byte-identical body. One caveat about intermediary caching in an inline comment.

Provider blindness holds, and I confirmed it independently. ModelsCompat reads only id, created and name. owned_by is dropped, and so is description, which is where the live leak in #1284 actually sits (hive-stt and hive-tts name Groq verbatim in model_aliases.summary). So the Anthropic branch is immune to that leak by construction. Please do not let this merge read as closing #1284 though: the OpenAI branch still ships those descriptions to every Open WebUI and OpenAI SDK caller, so that issue stays open. One forward looking risk on display_name inline.

The non-guard labelling is honest but the count is short by two. Both tests you named really are non-defect guards, and both really do go red under the inverse mutation, so they earn their place. Two more added tests are in the same category and are not named. Detail inline.

The declined scope is the right call. I checked it against the live specification rather than plausibility. The streaming page describes "a series of content blocks" with no stated minimum of one, emitMessageStart really does set Content: []string{} so message_start carries "content":[] on the wire, and the SDK accumulator appends blocks into that list and never indexes it eagerly, so a turn with zero blocks folds back into an empty array with no error. I did find one genuinely unhandled sequence next door to it, which is pre-existing rather than something you introduced. Inline, with a suggestion to file it rather than widen this PR.

On the review streams themselves, so the absences are not read as passes:

• CodeRabbit: SKIPPED. Rate limited repo wide. The bot comment on this PR says "Review limit reached" and the check reports zero duration, and the CLI is limited on the same account. Not a clean pass.
• Codex adversarial review: SKIPPED. Over quota. The connector posted "You have reached your Codex usage limits for code reviews" on this PR.
• Everything else ran: the security pass, a Go read, the plain adversarial pass, and a downstream trace through authz, catalog, the alias seed migrations and the Anthropic SDK accumulator source.

Nothing here blocks the fixes. The one I would like addressed before merge is the dropped retry headers, since it is a small change and it quietly undoes a contract another PR added on purpose.