0012 - Anthropic Messages-compatible edge as a second gateway dialect

• Status: Accepted
• Date: 2026-06-14
• Deciders: nexus core team
• Tags: gateway, wire-contract, sdk, edge
• Supersedes: none

Context and Problem Statement

0005 - OpenAI-compatible API as the gateway contract chose the OpenAI-compatible shape as the primary gateway edge and deferred an Anthropic Messages edge as an additive expansion. Agentic clients — Claude Code, the official Anthropic Python and TypeScript SDKs, and tools that speak the Anthropic Messages wire — expect the native request body, SSE event sequence, error envelope, and /v1/messages path layout.

Serving those clients through the OpenAI edge would require every caller to accept an OpenAI translation layer and would drop or re-derive Anthropic-only fields (thinking, signed thinking blocks, per-block cache_control, block-array system, anthropic-beta headers) on cross-provider routes.

Decision Drivers

• Claude Code and the Anthropic SDKs must work with a base-URL swap and a nexus API key only.
• Extended-thinking signatures and prompt-cache hints must survive routing when the selected upstream is Anthropic.
• Classification, routing, fallback, policy, audit, analytics, and cost accounting must match the OpenAI edge for the same logical request.
• The OpenAI /v1/* namespace must remain reserved for the OpenAI-compatible contract.

Considered Options

• OpenAI edge only with client-side adaptation — Rejected: loses native SSE, error shapes, and thinking/cache fidelity.
• Parallel Anthropic pipeline — Rejected: duplicates policy, audit, and routing logic.
• Translator edge over the shared attempt pipeline (chosen) — Anthropic-shaped HTTP in and out; internal OpenAI-shaped contract plus a native-field preservation envelope for Anthropic-targeted attempts.

Decision Outcome

Chosen option: a native Anthropic Messages edge mounted under /anthropic.

Contract surface:

• POST /anthropic/v1/messages — Anthropic Messages request and response bodies, buffered or streaming.
• POST /anthropic/v1/messages/count_tokens — returns {"input_tokens": N}; proxies to Anthropic when the resolved route targets Anthropic, otherwise returns a documented byte-length estimate.
• Authentication: nexus API key via x-api-key: nxs_... (Anthropic SDK default) or Authorization: Bearer nxs_.... Upstream Anthropic credentials are never accepted at the edge.
• Errors: {"type": "error", "error": {"type", "message"}} with Anthropic status conventions (invalid_request_error 400, authentication_error 401, permission_error 403, not_found_error 404, rate_limit_error 429, overloaded_error 529, api_error 500).
• Streaming: Anthropic SSE (event: + data: frames); terminal upstream failures after bytes were sent surface as an in-band error event.
• Unknown routes under /anthropic return not_found_error with HTTP 404.
• Native-only fields ride a preservation envelope attached to the internal request; Anthropic-targeted attempts reconstruct upstream bodies from the raw inbound JSON, non-Anthropic attempts receive a stripped OpenAI-shaped body. Extended thinking pins to Anthropic upstreams.

This edge is a second dialect, not a replacement for 0005 - OpenAI-compatible API as the gateway contract’s primary OpenAI edge. Both share AttemptBuilder, AttemptExecutor, registry resolution, and analytics.

Consequences

• Anthropic SDK clients and Claude Code point ANTHROPIC_BASE_URL at https://<gateway>/anthropic and supply a nexus key.
• Certification suites in test-suite/compat/ and test-suite/node/ lock the pinned SDK versions named in test-suite/compat/spec/anthropic-sdk-provenance.json.
• Wire details live in the Wire Contracts reference.
• The edge is mounted under the /anthropic prefix and the SDK appends /v1/messages; clients set ANTHROPIC_BASE_URL to the gateway’s /anthropic URL.

More Information

• Primary edge: 0005 - OpenAI-compatible API as the gateway contract
• Wire contract: Wire Contracts
• Claude Code launch matrix: test-suite/compat/claude-code/environment-matrix.md in the source repository.