Skip to main content

firstpass_proxy/
provider.rs

1//! Normalized model access: a provider-agnostic request/response shape, and the wire adapters
2//! (Anthropic Messages, OpenAI Chat Completions, Google Gemini) that speak it. The router
3//! ([`crate::router`]) only ever talks to [`Provider`]; it never knows which wire format is
4//! behind a given rung.
5
6use std::collections::HashMap;
7use std::sync::Arc;
8use std::time::SystemTime;
9
10use async_trait::async_trait;
11use axum::http::HeaderMap;
12use firstpass_core::config::BUILTIN_OPENAI_COMPATIBLE;
13use serde::{Deserialize, Serialize};
14use serde_json::Value;
15
16/// One message in a normalized chat conversation. `content` is either a plain string (the common
17/// case — serializes byte-identically to a text message) OR the original array of content blocks
18/// (`text` / `tool_use` / `tool_result` / `image`), forwarded verbatim so tool and multimodal turns
19/// survive the enforce path (ADR 0005). Use [`ChatMessage::text_view`] to read a text projection for
20/// gating.
21#[derive(Debug, Clone, Serialize, Deserialize)]
22pub struct ChatMessage {
23    /// `"user"`, `"assistant"`, or `"system"`.
24    pub role: String,
25    /// Message content — a string, or an array of content blocks, forwarded as-is to the provider.
26    pub content: Value,
27}
28
29impl ChatMessage {
30    /// A text-only message (the common path).
31    #[must_use]
32    pub fn text(role: impl Into<String>, content: impl Into<String>) -> Self {
33        Self {
34            role: role.into(),
35            content: Value::String(content.into()),
36        }
37    }
38
39    /// Concatenate the text this message carries, for gating. A string is itself; an array yields the
40    /// joined `text` blocks (tool_use/tool_result/image blocks contribute no gating text).
41    #[must_use]
42    pub fn text_view(&self) -> String {
43        match &self.content {
44            Value::String(s) => s.clone(),
45            Value::Array(blocks) => blocks
46                .iter()
47                .filter_map(|b| b.get("text").and_then(Value::as_str))
48                .collect::<Vec<_>>()
49                .join("\n"),
50            _ => String::new(),
51        }
52    }
53}
54
55/// A provider-agnostic model request, built once per incoming call and re-used (with
56/// `model` swapped) across every rung of the ladder.
57///
58// Message content is carried verbatim (string or content-block array, ADR 0005); gates read a text
59// projection via `ChatMessage::text_view`. `tools` is opaque passthrough.
60#[derive(Debug, Clone, Serialize, Deserialize)]
61pub struct ModelRequest {
62    /// `provider/model`, e.g. `"anthropic/claude-haiku-4-5"`.
63    pub model: String,
64    /// System prompt, if any.
65    #[serde(default, skip_serializing_if = "Option::is_none")]
66    pub system: Option<String>,
67    /// Conversation turns.
68    pub messages: Vec<ChatMessage>,
69    /// Max tokens to generate.
70    pub max_tokens: u32,
71    /// Opaque tool/function-calling passthrough, forwarded as-is to the wire provider.
72    #[serde(default)]
73    pub tools: Value,
74    /// The **full original inbound request JSON**, when this request came off the proxy's wire
75    /// (ADR 0005). Anthropic-dialect providers send it verbatim with only `model` swapped (and
76    /// `stream` stripped), so every field — `tools`, `tool_choice`, `temperature`, `thinking`,
77    /// `stop_sequences`, … — survives the rung exactly as the caller wrote it. `Null` for
78    /// synthesized requests (judge / consistency samples), which use the normalized fields.
79    #[serde(default, skip_serializing_if = "Value::is_null")]
80    pub raw: Value,
81    /// Whether to insert prompt-cache breakpoints on the stable prefix — see
82    /// [`add_cache_breakpoints`]. Set from `[escalation] prompt_cache`; `false` everywhere else,
83    /// including synthesized judge/consistency requests, so nothing changes unless asked.
84    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
85    pub cache_prefix: bool,
86}
87
88/// A provider-agnostic model response.
89#[derive(Debug, Clone, Serialize, Deserialize)]
90pub struct ModelResponse {
91    /// `provider/model` that produced this response.
92    pub model: String,
93    /// Concatenated text output.
94    pub text: String,
95    /// Input tokens billed, **uncached only** — see `cache_write_tokens` for the rest.
96    pub in_tokens: u64,
97    /// Prompt tokens written to the provider's cache (billed at a premium). 0 when the caller did
98    /// not use prompt caching, or the provider does not report it.
99    pub cache_write_tokens: u64,
100    /// Prompt tokens served from the provider's cache (billed at a discount).
101    pub cache_read_tokens: u64,
102    /// Output tokens billed.
103    pub out_tokens: u64,
104    /// The raw wire response, kept for debugging/audit — never logged wholesale.
105    pub raw: Value,
106}
107
108impl ModelResponse {
109    /// Whether the model stopped at the request's output-token limit. See [`hit_output_limit`].
110    #[must_use]
111    pub fn truncated(&self) -> bool {
112        hit_output_limit(&self.raw)
113    }
114
115    /// Whether the response contains at least one tool call.
116    /// Handles Anthropic (`content[*].type == "tool_use"`) and
117    /// OpenAI (`choices[0].message.tool_calls` non-empty) formats.
118    #[must_use]
119    pub fn has_tool_calls(&self) -> bool {
120        // Anthropic: a content array that contains at least one tool_use block.
121        if let Some(blocks) = self.raw.get("content").and_then(Value::as_array) {
122            return blocks
123                .iter()
124                .any(|b| b.get("type").and_then(Value::as_str) == Some("tool_use"));
125        }
126        // OpenAI: choices[0].message.tool_calls is a non-empty array.
127        self.raw
128            .pointer("/choices/0/message/tool_calls")
129            .and_then(Value::as_array)
130            .is_some_and(|tc| !tc.is_empty())
131    }
132}
133
134/// Whether a raw provider response says generation stopped at the output-token limit:
135/// Anthropic `stop_reason: "max_tokens"`, OpenAI Chat `finish_reason: "length"`, OpenAI Responses
136/// `incomplete_details.reason: "max_output_tokens"`, Gemini `finishReason: "MAX_TOKENS"`.
137#[must_use]
138pub fn hit_output_limit(raw: &Value) -> bool {
139    let is = |ptr: &str, want: &str| raw.pointer(ptr).and_then(Value::as_str) == Some(want);
140    is("/stop_reason", "max_tokens")
141        || is("/choices/0/finish_reason", "length")
142        || is("/incomplete_details/reason", "max_output_tokens")
143        || is("/candidates/0/finishReason", "MAX_TOKENS")
144}
145
146/// Failure modes of a provider call.
147#[derive(Debug, Clone, thiserror::Error)]
148pub enum ProviderError {
149    /// The request never got a response (connection failure, timeout).
150    #[error("transport error: {0}")]
151    Transport(String),
152    /// The provider responded with a non-2xx status.
153    #[error("http {status}: {body}")]
154    Http {
155        /// HTTP status code.
156        status: u16,
157        /// Response body (truncated upstream, not by us).
158        body: String,
159    },
160    /// The response body didn't parse into the shape we expected.
161    #[error("decode error: {0}")]
162    Decode(String),
163}
164
165impl ProviderError {
166    /// Whether this failure should trigger cross-rung/cross-provider failover (transport
167    /// errors and 5xx) rather than being treated as a hard, non-retryable error (4xx, decode).
168    #[must_use]
169    pub fn is_failover_eligible(&self) -> bool {
170        match self {
171            ProviderError::Transport(_) => true,
172            ProviderError::Http { status, .. } => *status >= 500,
173            ProviderError::Decode(_) => false,
174        }
175    }
176}
177
178/// BYOK credentials for one request, extracted from headers with env-var fallback.
179///
180/// Never logged or persisted — [`std::fmt::Debug`] redacts all credential fields.
181#[derive(Clone, Default)]
182pub struct Auth {
183    /// Anthropic API key from the request's `x-api-key` header **only**.
184    /// Never populated from env or from a Bearer token — the env fallback is handled by
185    /// [`AnthropicProvider::complete`] at lowest priority after `anthropic_bearer`.
186    pub anthropic_key: Option<String>,
187    /// OpenAI (or OpenAI-compatible) API key from `Authorization: Bearer …` on OpenAI-dialect
188    /// requests, or `OPENAI_API_KEY` env. **Never populated on Anthropic-dialect requests** so
189    /// the server's `OPENAI_API_KEY` cannot accidentally be forwarded to api.anthropic.com, and
190    /// a Claude Code OAuth token arriving on `/v1/messages` cannot be sent to an OpenAI rung.
191    pub openai_key: Option<String>,
192    /// Bearer token from `Authorization: Bearer …` on **Anthropic-dialect requests only** (`/v1/messages`,
193    /// count-tokens). Used by [`AnthropicProvider`] as the OAuth/subscription fallback when
194    /// `anthropic_key` is absent (Claude Code with a Claude account). Never populated from env
195    /// vars — only from the inbound request header on the Anthropic path.
196    pub anthropic_bearer: Option<String>,
197    /// `anthropic-beta` header value, forwarded verbatim to the Anthropic endpoint.
198    pub anthropic_beta: Option<String>,
199    /// `anthropic-version` header value. When set, overrides the default `2023-06-01`.
200    pub anthropic_version: Option<String>,
201    /// Google Gemini API key from the inbound request's `x-goog-api-key` header, **only on
202    /// Gemini-dialect requests** (`/v1beta/models/{model}:generateContent`).
203    /// Never populated from env. A Gemini rung that must work for non-Gemini callers (a mixed
204    /// ladder) needs `api_key_env` on its `[[provider]]` block; there is no ambient fallback.
205    /// Never set on Anthropic/OpenAI paths — scoping prevents the Google key from reaching
206    /// other providers.
207    pub gemini_key: Option<String>,
208}
209
210impl std::fmt::Debug for Auth {
211    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
212        f.debug_struct("Auth")
213            .field("anthropic_key", &self.anthropic_key.as_ref().map(|_| "***"))
214            .field("openai_key", &self.openai_key.as_ref().map(|_| "***"))
215            .field(
216                "anthropic_bearer",
217                &self.anthropic_bearer.as_ref().map(|_| "***"),
218            )
219            .field("anthropic_beta", &self.anthropic_beta)
220            .field("anthropic_version", &self.anthropic_version)
221            .field("gemini_key", &self.gemini_key.as_ref().map(|_| "***"))
222            .finish()
223    }
224}
225
226impl Auth {
227    /// Extract BYOK credentials from request headers, scoped to `dialect` so credentials
228    /// cannot leak across provider boundaries.
229    ///
230    /// - On **Anthropic-dialect** requests (`/v1/messages`, count-tokens): an inbound
231    ///   `Authorization: Bearer` token goes into `anthropic_bearer` only — it is the
232    ///   OAuth/subscription credential for Claude accounts and must NOT be forwarded to
233    ///   OpenAI rungs. `openai_key` is populated only from the `OPENAI_API_KEY` env var
234    ///   (no inbound Bearer on this path).
235    ///
236    /// - On **OpenAI-dialect** requests (`/v1/chat/completions`, `/v1/responses`): an inbound
237    ///   `Authorization: Bearer` token goes into `openai_key` only — it is the caller's
238    ///   OpenAI key and must NOT be forwarded to Anthropic rungs. `anthropic_bearer` is
239    ///   always `None` on this path.
240    ///
241    /// This scoping ensures `OPENAI_API_KEY` is never sent to api.anthropic.com and a Claude
242    /// OAuth token is never sent to an OpenAI-compatible endpoint.
243    #[must_use]
244    pub fn from_headers(headers: &HeaderMap, dialect: firstpass_core::Dialect) -> Self {
245        // Only the request header; env fallback is the provider's responsibility so that
246        // a request-supplied Bearer is not shadowed by the server's ANTHROPIC_API_KEY.
247        // Not on the Gemini path: a Gemini client's headers are for Google, and a mixed ladder's
248        // Anthropic rung must not forward a stray inbound `x-api-key` from one.
249        let anthropic_key = headers
250            .get("x-api-key")
251            .filter(|_| !matches!(dialect, firstpass_core::Dialect::Gemini))
252            .and_then(|v| v.to_str().ok())
253            .map(str::to_owned);
254
255        let bearer = headers
256            .get(axum::http::header::AUTHORIZATION)
257            .and_then(|v| v.to_str().ok())
258            .and_then(|v| v.strip_prefix("Bearer "))
259            .map(str::to_owned);
260
261        let (openai_key, anthropic_bearer) = match dialect {
262            firstpass_core::Dialect::Anthropic => {
263                // Bearer on this path is an Anthropic OAuth token — not an OpenAI key.
264                let openai_env = std::env::var("OPENAI_API_KEY").ok();
265                (openai_env, bearer)
266            }
267            firstpass_core::Dialect::Openai => {
268                // Bearer on this path is an OpenAI key — not an Anthropic credential.
269                let openai_key = bearer.or_else(|| std::env::var("OPENAI_API_KEY").ok());
270                (openai_key, None)
271            }
272            firstpass_core::Dialect::Gemini => {
273                // Bearer on this path is a Google token — neither OpenAI nor Anthropic.
274                // `openai_key` is still populated from env for mixed-ladder rungs; it is NOT
275                // sourced from the inbound `x-goog-api-key` (that goes into `gemini_key`).
276                let openai_env = std::env::var("OPENAI_API_KEY").ok();
277                (openai_env, None)
278            }
279        };
280
281        // Gemini API key from the inbound `x-goog-api-key` header.
282        // Only trusted on the Gemini path; on other paths the header is ignored.
283        let gemini_key = if matches!(dialect, firstpass_core::Dialect::Gemini) {
284            headers
285                .get("x-goog-api-key")
286                .and_then(|v| v.to_str().ok())
287                .map(str::to_owned)
288        } else {
289            None
290        };
291
292        // Multiple `anthropic-beta` values (e.g. "extended-thinking-2025-02-19" + another flag)
293        // are joined into a comma-separated string so the upstream receives all of them.
294        let anthropic_beta = {
295            let vals: Vec<&str> = headers
296                .get_all("anthropic-beta")
297                .iter()
298                .filter_map(|v| v.to_str().ok())
299                .collect();
300            if vals.is_empty() {
301                None
302            } else {
303                Some(vals.join(", "))
304            }
305        };
306        let anthropic_version = headers
307            .get("anthropic-version")
308            .and_then(|v| v.to_str().ok())
309            .map(str::trim)
310            .filter(|v| !v.is_empty())
311            .map(str::to_owned);
312        Self {
313            anthropic_key,
314            openai_key,
315            anthropic_bearer,
316            anthropic_beta,
317            anthropic_version,
318            gemini_key,
319        }
320    }
321}
322
323/// A normalized model backend. Implementations translate [`ModelRequest`]/[`ModelResponse`]
324/// to/from one wire API.
325#[async_trait]
326pub trait Provider: Send + Sync + std::fmt::Debug {
327    /// Call the model and normalize the result.
328    ///
329    /// # Errors
330    /// Returns [`ProviderError`] on transport failure, a non-2xx response, or a response
331    /// that doesn't decode into the expected shape.
332    async fn complete(
333        &self,
334        req: &ModelRequest,
335        auth: &Auth,
336    ) -> Result<ModelResponse, ProviderError>;
337
338    /// Provider identity, e.g. `"anthropic"`.
339    fn id(&self) -> &str;
340
341    /// Whether this provider carries structured content (tool_use / tool_result / image blocks
342    /// and top-level `tools`) **verbatim** on the wire for the given *inbound* dialect.
343    ///
344    /// - Anthropic-dialect providers (Anthropic / Bedrock / Vertex) return `true` iff
345    ///   `inbound == Dialect::Anthropic`: the raw inbound body is forwarded with only the model
346    ///   swapped, so every caller field — `tools`, `tool_choice`, `thinking`, … — survives
347    ///   intact (ADR 0005 P4).
348    /// - `OpenAiProvider` returns `true` iff `inbound == Dialect::Openai`: same verbatim-carry
349    ///   rule for all-OpenAI-dialect ladders.
350    /// - All other providers (Gemini, unknown) return `false` — no verbatim-carry built yet.
351    ///
352    /// The enforce path's fidelity guard uses this to decide: verbatim-carry path (all rungs
353    /// return `true` for the inbound dialect), translation path (OpenAI → Anthropic when
354    /// content is translatable), or transparent observe passthrough (safe fallback).
355    fn carries_structured_verbatim(&self, _inbound: firstpass_core::Dialect) -> bool {
356        false
357    }
358}
359
360/// Strip the `provider/` prefix from a ladder model id for the provider's wire API — Anthropic and
361/// OpenAI expect the bare model (`claude-haiku-4-5`), not `anthropic/claude-haiku-4-5`. The full
362/// prefixed id is still what the ladder/trace use; only the wire call is stripped.
363fn wire_model(model: &str) -> &str {
364    model.split_once('/').map_or(model, |(_, m)| m)
365}
366
367/// Resolve the API key for a provider call.
368///
369/// - If `api_key_env` is `Some(env_name)`, the resolved value is **only** the content of that
370///   env var. If the env var is unset or empty the function returns `""` — it never falls through
371///   to the BYOK override. An operator who wires `api_key_env = "GROQ_API_KEY"` for a custom host
372///   must never inadvertently receive the client's own OpenAI key when the Groq var is missing.
373/// - If `api_key_env` is `None`, the BYOK override is used (may itself be empty/`""`).
374fn resolve_api_key(api_key_env: Option<&str>, byok_override: Option<&str>) -> String {
375    match api_key_env {
376        Some(env_name) => std::env::var(env_name)
377            .ok()
378            .filter(|s| !s.is_empty())
379            .unwrap_or_default(),
380        None => byok_override.unwrap_or("").to_owned(),
381    }
382}
383
384/// The credential an Anthropic-dialect call sends upstream.
385#[derive(Debug, PartialEq, Eq)]
386enum AnthropicCredential {
387    ApiKey(String),
388    Bearer(String),
389}
390
391/// Pick the Anthropic credential, highest priority first:
392///   1. The rung's configured `api_key_env` value (outer `Some`). An operator who declared this
393///      provider's key must never have a client credential forwarded to that host instead.
394///      If the env var is configured but **unset/empty** (`Some(None)` or `Some(Some(""))`), the
395///      function returns `None` — no credential is sent rather than falling through to the client.
396///   2. (only when `configured = None`) The request's `x-api-key`.
397///   3. (only when `configured = None`) The request's `Authorization: Bearer` OAuth token.
398///   4. (only when `configured = None`) The ambient `ANTHROPIC_API_KEY` env fallback.
399///
400/// `configured: Option<Option<String>>`
401///   - `None`           → api_key_env not configured; proceed with client creds + ambient.
402///   - `Some(None)`     → api_key_env configured but the env var is unset.
403///   - `Some(Some(k))`  → api_key_env configured and resolved to `k`.
404///
405/// Never the OpenAI key. Pure so the ordering is unit-testable without touching process env.
406fn anthropic_credential(
407    configured: Option<Option<String>>,
408    auth: &Auth,
409    ambient: Option<String>,
410) -> Option<AnthropicCredential> {
411    match configured {
412        Some(key) => {
413            // api_key_env IS configured. Use its value if non-empty; otherwise no credential
414            // (never fall through to client creds — the operator intended this provider's key).
415            key.filter(|s| !s.is_empty())
416                .map(AnthropicCredential::ApiKey)
417        }
418        None => {
419            // api_key_env NOT configured — use client creds + ambient.
420            let non_empty = |v: &Option<String>| v.clone().filter(|s| !s.is_empty());
421            non_empty(&auth.anthropic_key)
422                .map(AnthropicCredential::ApiKey)
423                .or_else(|| non_empty(&auth.anthropic_bearer).map(AnthropicCredential::Bearer))
424                .or_else(|| non_empty(&ambient).map(AnthropicCredential::ApiKey))
425        }
426    }
427}
428
429/// Build the Anthropic Messages wire body for `req`: the original inbound JSON **verbatim** with
430/// only `model` swapped to the rung's wire id and `stream` stripped (`complete` is the buffered
431/// call — the gate needs the whole candidate). Falls back to the normalized fields when there is
432/// no raw body (synthesized judge/consistency requests). Pure, so fidelity is unit-testable.
433#[must_use]
434pub fn anthropic_wire_body(req: &ModelRequest) -> Value {
435    if let Value::Object(raw) = &req.raw {
436        let mut body = raw.clone();
437        body.insert(
438            "model".to_owned(),
439            Value::String(wire_model(&req.model).to_owned()),
440        );
441        body.remove("stream");
442        normalize_reasoning(&mut body, Wire::Anthropic);
443        if req.cache_prefix {
444            add_cache_breakpoints(&mut body);
445        }
446        return Value::Object(body);
447    }
448    let messages: Vec<Value> = req
449        .messages
450        .iter()
451        .map(|m| serde_json::json!({ "role": m.role, "content": m.content }))
452        .collect();
453    let mut body = serde_json::json!({
454        "model": wire_model(&req.model),
455        "max_tokens": req.max_tokens,
456        "messages": messages,
457    });
458    if let Some(system) = req.system.as_deref() {
459        body["system"] = serde_json::json!(system);
460    }
461    if !req.tools.is_null() {
462        body["tools"] = req.tools.clone();
463    }
464    // This branch is not a rare fallback: it is the path every translated request takes, and
465    // every CONDENSED one — condensing clears `raw` precisely so the smaller message list is what
466    // gets sent. Applying breakpoints only in the raw branch above would mean `prompt_cache`
467    // silently did nothing for exactly the long conversations it exists to pay for.
468    if req.cache_prefix
469        && let Some(map) = body.as_object_mut()
470    {
471        add_cache_breakpoints(map);
472    }
473    body
474}
475
476/// Speaks `POST {base}/v1/messages` (Anthropic Messages API).
477///
478// LIVE-VERIFIED (2026-07-10): exercised against real Anthropic through the running proxy's enforce
479// path — a haiku completion served end-to-end. The `anthropic/` prefix must be stripped for the
480// wire call (see `wire_model`); sending it verbatim 404s.
481#[derive(Debug, Clone)]
482pub struct AnthropicProvider {
483    /// Ladder prefix / trace label for this provider (usually `"anthropic"`).
484    pub id: String,
485    /// Base URL, e.g. `https://api.anthropic.com`.
486    pub base_url: String,
487    /// Env var the API key is read from when no per-request BYOK header is present. `None` for the
488    /// built-in provider, which resolves the key via [`Auth`] (`x-api-key` header or env).
489    pub api_key_env: Option<String>,
490    /// Shared, connection-pooled HTTP client.
491    pub http: reqwest::Client,
492}
493
494#[async_trait]
495impl Provider for AnthropicProvider {
496    fn id(&self) -> &str {
497        &self.id
498    }
499
500    fn carries_structured_verbatim(&self, inbound: firstpass_core::Dialect) -> bool {
501        inbound == firstpass_core::Dialect::Anthropic
502    }
503
504    async fn complete(
505        &self,
506        req: &ModelRequest,
507        auth: &Auth,
508    ) -> Result<ModelResponse, ProviderError> {
509        let body = anthropic_wire_body(req);
510
511        let url = format!("{}/v1/messages", self.base_url.trim_end_matches('/'));
512        let mut builder = self.http.post(url);
513
514        match anthropic_credential(
515            self.api_key_env.as_deref().map(|e| std::env::var(e).ok()),
516            auth,
517            std::env::var("ANTHROPIC_API_KEY").ok(),
518        ) {
519            Some(AnthropicCredential::ApiKey(key)) => builder = builder.header("x-api-key", key),
520            Some(AnthropicCredential::Bearer(token)) => {
521                builder =
522                    builder.header(axum::http::header::AUTHORIZATION, format!("Bearer {token}"));
523            }
524            None => {}
525        }
526
527        // Forward anthropic-version (inbound header wins; default to the published stable version).
528        let version = auth.anthropic_version.as_deref().unwrap_or("2023-06-01");
529        builder = builder.header("anthropic-version", version);
530
531        // Forward anthropic-beta verbatim (extended thinking, interleaved-thinking, …).
532        if let Some(beta) = &auth.anthropic_beta {
533            builder = builder.header("anthropic-beta", beta);
534        }
535
536        let resp = builder
537            .json(&body)
538            .send()
539            .await
540            .map_err(|e| ProviderError::Transport(e.to_string()))?;
541
542        let status = resp.status();
543        let bytes = resp
544            .bytes()
545            .await
546            .map_err(|e| ProviderError::Transport(e.to_string()))?;
547
548        if !status.is_success() {
549            return Err(ProviderError::Http {
550                status: status.as_u16(),
551                body: String::from_utf8_lossy(&bytes).into_owned(),
552            });
553        }
554
555        let json: Value =
556            serde_json::from_slice(&bytes).map_err(|e| ProviderError::Decode(e.to_string()))?;
557        let u = anthropic_parse_response(&json)?;
558        let (text, in_tokens, out_tokens) = (u.text, u.in_tokens, u.out_tokens);
559        let (cache_write_tokens, cache_read_tokens) = (u.cache_write_tokens, u.cache_read_tokens);
560
561        Ok(ModelResponse {
562            cache_write_tokens,
563            cache_read_tokens,
564            model: req.model.clone(),
565            text,
566            in_tokens,
567            out_tokens,
568            raw: json,
569        })
570    }
571}
572
573/// Extract `(text, in_tokens, out_tokens)` from an Anthropic Messages API response. Shared by
574/// [`AnthropicProvider`] and every auth scheme that wraps the Anthropic body shape (Bedrock,
575/// Vertex — ADR 0006): they all get the same response back, only the request's auth/URL differ.
576fn anthropic_parse_response(json: &Value) -> Result<AnthropicUsage, ProviderError> {
577    let text = json
578        .get("content")
579        .and_then(Value::as_array)
580        .map(|blocks| {
581            blocks
582                .iter()
583                .filter_map(|b| b.get("text").and_then(Value::as_str))
584                .collect::<Vec<_>>()
585                .join("")
586        })
587        .ok_or_else(|| ProviderError::Decode("missing content[].text".to_owned()))?;
588
589    let in_tokens = json
590        .pointer("/usage/input_tokens")
591        .and_then(Value::as_u64)
592        .unwrap_or(0);
593    let out_tokens = json
594        .pointer("/usage/output_tokens")
595        .and_then(Value::as_u64)
596        .unwrap_or(0);
597    // Prompt caching splits the prompt across three counters. Reading only `input_tokens` — which
598    // this did until now — reports about 20 tokens for a 190k-token cached prefix, so the receipt
599    // records a fraction of a cent for a call that cost most of a dollar, and `[budget]` caps fed
600    // by that total never trip.
601    let cache_write_tokens = json
602        .pointer("/usage/cache_creation_input_tokens")
603        .and_then(Value::as_u64)
604        .unwrap_or(0);
605    let cache_read_tokens = json
606        .pointer("/usage/cache_read_input_tokens")
607        .and_then(Value::as_u64)
608        .unwrap_or(0);
609
610    Ok(AnthropicUsage {
611        text,
612        in_tokens,
613        cache_write_tokens,
614        cache_read_tokens,
615        out_tokens,
616    })
617}
618
619/// Text plus the full token split from an Anthropic response.
620struct AnthropicUsage {
621    text: String,
622    in_tokens: u64,
623    cache_write_tokens: u64,
624    cache_read_tokens: u64,
625    out_tokens: u64,
626}
627
628/// Build an Anthropic Messages-shaped request body with the model **omitted** — Bedrock and Vertex
629/// both put the model in the URL, not the body (ADR 0006 P2/P3), unlike direct Anthropic API calls
630/// which need `model` in the body ([`AnthropicWireRequest`]). `anthropic_version` is the dialect
631/// version string each host expects (`bedrock-2023-05-31` / `vertex-2023-10-16`).
632fn anthropic_messages_body(req: &ModelRequest, anthropic_version: &str) -> Value {
633    // Same verbatim-carry rule as `anthropic_wire_body`, adapted to hosts that put the model in
634    // the URL: original inbound JSON minus `model`/`stream`, plus the host's version string.
635    if let Value::Object(raw) = &req.raw {
636        let mut body = raw.clone();
637        body.remove("model");
638        body.remove("stream");
639        body.insert(
640            "anthropic_version".to_owned(),
641            Value::String(anthropic_version.to_owned()),
642        );
643        return Value::Object(body);
644    }
645    let messages: Vec<Value> = req
646        .messages
647        .iter()
648        .map(|m| serde_json::json!({ "role": m.role, "content": m.content }))
649        .collect();
650    let mut body = serde_json::json!({
651        "anthropic_version": anthropic_version,
652        "max_tokens": req.max_tokens,
653        "messages": messages,
654    });
655    if let Some(system) = req.system.as_deref() {
656        body["system"] = serde_json::json!(system);
657    }
658    if !req.tools.is_null() {
659        body["tools"] = req.tools.clone();
660    }
661    body
662}
663
664/// Build the OpenAI Chat Completions wire body for `req`: the original inbound JSON **verbatim**
665/// with only `model` swapped to the rung's wire id and `stream` stripped (analogous to
666/// [`anthropic_wire_body`] for all-OpenAI-dialect ladders). Falls back to the normalized fields
667/// when there is no raw body (synthesized judge/consistency requests, or translation path).
668/// Pure, so fidelity is unit-testable.
669#[must_use]
670pub fn openai_wire_body(req: &ModelRequest) -> Value {
671    if let Value::Object(raw) = &req.raw {
672        let mut body = raw.clone();
673        body.insert(
674            "model".to_owned(),
675            Value::String(wire_model(&req.model).to_owned()),
676        );
677        body.remove("stream");
678        normalize_reasoning(&mut body, Wire::OpenAi);
679        return Value::Object(body);
680    }
681    // Fallback: reconstruct from normalized fields (translation path or synthesized requests).
682    let mut messages: Vec<Value> = Vec::with_capacity(req.messages.len() + 1);
683    if let Some(system) = req.system.as_deref() {
684        messages.push(serde_json::json!({ "role": "system", "content": system }));
685    }
686    messages.extend(
687        req.messages
688            .iter()
689            .map(|m| serde_json::json!({ "role": m.role, "content": m.content })),
690    );
691    let mut body = serde_json::json!({
692        "model": wire_model(&req.model),
693        "max_tokens": req.max_tokens,
694        "messages": messages,
695    });
696    if !req.tools.is_null() {
697        body["tools"] = req.tools.clone();
698    }
699    body
700}
701
702/// How hard the caller asked the model to think, independent of how any one provider spells it.
703///
704/// A cascade crosses vendors by design — a ladder is routinely `openai/…` under `anthropic/…` —
705/// so the caller's reasoning request has to survive the crossing. Without this, an OpenAI client
706/// that sets `reasoning_effort` gets a **400** the moment the router escalates it onto an
707/// Anthropic rung, because raw bodies pass through verbatim and Anthropic rejects the unknown
708/// field. The caller did nothing wrong; the ladder moved under it.
709#[derive(Debug, Clone, Copy, PartialEq, Eq)]
710pub enum Effort {
711    Low,
712    Medium,
713    High,
714}
715
716impl Effort {
717    /// Anthropic/Gemini want a token budget rather than a word. These are deliberately modest:
718    /// the budget is billed as output tokens, so a generous default would silently raise the cost
719    /// of every request that merely mentioned reasoning.
720    const fn budget_tokens(self) -> u32 {
721        match self {
722            Self::Low => 1024, // Anthropic's documented floor; below it the field is invalid.
723            Self::Medium => 4096,
724            Self::High => 16384,
725        }
726    }
727
728    /// Read back a budget as a level, so a caller that spelled it in tokens keeps its intent when
729    /// the request lands on a provider that spells it in words.
730    const fn from_budget(tokens: u64) -> Self {
731        if tokens < 2048 {
732            Self::Low
733        } else if tokens < 8192 {
734            Self::Medium
735        } else {
736            Self::High
737        }
738    }
739
740    fn as_str(self) -> &'static str {
741        match self {
742            Self::Low => "low",
743            Self::Medium => "medium",
744            Self::High => "high",
745        }
746    }
747}
748
749/// Read the caller's reasoning request out of a raw inbound body, in any dialect. Returns `None`
750/// for a body that is not an object or asked for no reasoning.
751#[must_use]
752pub fn effort_of(raw: &Value) -> Option<Effort> {
753    read_effort(raw.as_object()?)
754}
755
756/// Read whichever spelling the caller used, in any dialect.
757fn read_effort(body: &serde_json::Map<String, Value>) -> Option<Effort> {
758    // OpenAI: a word.
759    if let Some(s) = body.get("reasoning_effort").and_then(Value::as_str) {
760        return match s {
761            "low" | "minimal" => Some(Effort::Low),
762            "medium" => Some(Effort::Medium),
763            "high" => Some(Effort::High),
764            _ => None,
765        };
766    }
767    // Anthropic: a budget, but only when thinking is actually enabled.
768    if let Some(t) = body.get("thinking").and_then(Value::as_object)
769        && t.get("type").and_then(Value::as_str) != Some("disabled")
770        && let Some(b) = t.get("budget_tokens").and_then(Value::as_u64)
771    {
772        return Some(Effort::from_budget(b));
773    }
774    // Gemini: a budget under a camelCase key.
775    if let Some(b) = body
776        .get("thinkingConfig")
777        .and_then(Value::as_object)
778        .and_then(|c| c.get("thinkingBudget"))
779        .and_then(Value::as_u64)
780    {
781        return Some(Effort::from_budget(b));
782    }
783    None
784}
785
786/// Which wire dialect a body is being prepared for.
787#[derive(Debug, Clone, Copy, PartialEq, Eq)]
788pub enum Wire {
789    Anthropic,
790    OpenAi,
791    Gemini,
792}
793
794/// Rewrite `body` so the caller's reasoning request is spelled the way `target` expects, and no
795/// other dialect's spelling is left behind to be rejected.
796///
797/// Pure and total: a body with no reasoning request loses nothing, and a request that *cannot* be
798/// expressed within the target's constraints is dropped rather than sent invalid.
799pub fn normalize_reasoning(body: &mut serde_json::Map<String, Value>, target: Wire) {
800    // If the caller already spelled it the target's way, this is a same-dialect request: leave it
801    // completely alone. ADR 0005 promises a raw body reaches its own provider verbatim, and that
802    // promise covers the caller's mistakes too — a budget the caller's `max_tokens` cannot fit is
803    // theirs to see as a provider error, not ours to silently rewrite into a different request.
804    // Only a request whose spelling is *foreign* to where it landed needs translating, which is
805    // the cross-vendor escalation this exists for.
806    let native = match target {
807        Wire::OpenAi => "reasoning_effort",
808        Wire::Anthropic => "thinking",
809        Wire::Gemini => "thinkingConfig",
810    };
811    if body.contains_key(native) {
812        return;
813    }
814    let effort = read_effort(body);
815    // Strip every dialect first, so nothing foreign survives the crossing.
816    body.remove("reasoning_effort");
817    body.remove("thinking");
818    body.remove("thinkingConfig");
819    let Some(effort) = effort else { return };
820
821    match target {
822        Wire::OpenAi => {
823            body.insert(
824                "reasoning_effort".to_owned(),
825                Value::String(effort.as_str().to_owned()),
826            );
827        }
828        Wire::Anthropic => {
829            // Anthropic requires `max_tokens > budget_tokens`, and a budget of at least 1024.
830            // A caller with a small `max_tokens` cannot satisfy both, and sending it anyway is a
831            // 400 — so serve the request without extended thinking instead of failing it.
832            let max = body.get("max_tokens").and_then(Value::as_u64).unwrap_or(0);
833            let budget = u64::from(effort.budget_tokens()).min(max.saturating_sub(1));
834            if budget >= 1024 {
835                body.insert(
836                    "thinking".to_owned(),
837                    serde_json::json!({ "type": "enabled", "budget_tokens": budget }),
838                );
839                // Extended thinking rejects any temperature but the default; the caller's value
840                // was chosen without knowing the router would enable thinking.
841                body.remove("temperature");
842                body.remove("top_p");
843            }
844        }
845        Wire::Gemini => {
846            // Gemini nests this under `generationConfig`, not at the top level.
847            body.entry("generationConfig")
848                .or_insert_with(|| Value::Object(serde_json::Map::new()))
849                .as_object_mut()
850                .map(|c| {
851                    c.insert(
852                        "thinkingConfig".to_owned(),
853                        serde_json::json!({ "thinkingBudget": effort.budget_tokens() }),
854                    )
855                });
856        }
857    }
858}
859
860/// Insert Anthropic prompt-cache breakpoints on the stable prefix of a request.
861///
862/// Marks the end of the system prompt and the end of the tool definitions — the part of an agent's
863/// request that is byte-identical turn after turn. Everything after the last breakpoint (the
864/// conversation itself) is not cached.
865///
866/// **This is opt-in, and it is not free money.** A cache *write* costs
867/// [`CACHE_WRITE_MULTIPLIER`](firstpass_core::cost::CACHE_WRITE_MULTIPLIER) (1.25×) of base input,
868/// and only pays back once the same prefix is read again — [`CACHE_READ_MULTIPLIER`] is 0.1×, so
869/// roughly one reuse covers the premium and everything after is a large saving. On a long agent
870/// session with a fixed system prompt and tool set that is a clear win; on single-shot traffic it
871/// is a 25% surcharge on the prefix for nothing. Which one an operator has is a question about
872/// their traffic, not about this code, so it is configured rather than assumed.
873///
874/// Idempotent: a caller already using `cache_control` keeps their own breakpoints and gets none
875/// added, since they have placed them with knowledge this code does not have.
876/// Smallest serialized prefix worth marking, in characters.
877///
878/// Anthropic's minimum cacheable prefix is 1024 tokens (2048 on Haiku). At roughly 4 characters per
879/// token that is ~4096 characters; this floor sits deliberately below it, so the guard only skips
880/// prefixes that could not possibly qualify rather than second-guessing the tokenizer.
881const MIN_CACHEABLE_PREFIX_CHARS: usize = 3000;
882
883pub fn add_cache_breakpoints(body: &mut serde_json::Map<String, Value>) {
884    if body_has_cache_control(body) {
885        return;
886    }
887    // Anthropic refuses to cache a prefix below a per-model minimum (1024 tokens for Sonnet/Opus,
888    // 2048 for Haiku). Marking a shorter one is not merely wasted — it is a request the API can
889    // reject outright. Estimated from serialized bytes at the usual ~4 chars/token, floored well
890    // under the real minimum so this only skips prefixes that are clearly too small to qualify.
891    let prefix_chars = body.get("system").map_or(0, |v| v.to_string().len())
892        + body.get("tools").map_or(0, |v| v.to_string().len());
893    if prefix_chars < MIN_CACHEABLE_PREFIX_CHARS {
894        return;
895    }
896    let marker = serde_json::json!({ "type": "ephemeral" });
897
898    // `system` may be a bare string; caching requires the block form.
899    match body.get("system") {
900        Some(Value::String(text)) if !text.is_empty() => {
901            body.insert(
902                "system".to_owned(),
903                serde_json::json!([{
904                    "type": "text", "text": text, "cache_control": marker,
905                }]),
906            );
907        }
908        Some(Value::Array(blocks)) if !blocks.is_empty() => {
909            let mut blocks = blocks.clone();
910            if let Some(last) = blocks.last_mut().and_then(Value::as_object_mut) {
911                last.insert("cache_control".to_owned(), marker.clone());
912            }
913            body.insert("system".to_owned(), Value::Array(blocks));
914        }
915        _ => {}
916    }
917
918    // Tool definitions are the other half of the stable prefix, and on an agent request usually
919    // the larger half.
920    if let Some(Value::Array(tools)) = body.get("tools")
921        && !tools.is_empty()
922    {
923        let mut tools = tools.clone();
924        if let Some(last) = tools.last_mut().and_then(Value::as_object_mut) {
925            last.insert("cache_control".to_owned(), marker);
926        }
927        body.insert("tools".to_owned(), Value::Array(tools));
928    }
929}
930
931/// Whether the caller already placed cache breakpoints of their own.
932fn body_has_cache_control(body: &serde_json::Map<String, Value>) -> bool {
933    fn any_in(v: &Value) -> bool {
934        match v {
935            Value::Array(items) => items.iter().any(any_in),
936            Value::Object(o) => o.contains_key("cache_control") || o.values().any(any_in),
937            _ => false,
938        }
939    }
940    body.values().any(any_in)
941}
942
943/// Speaks `POST {base}/v1/chat/completions` (OpenAI Chat Completions API).
944///
945// LIVE-UNVERIFIED: the `wire_model` prefix-strip fix is applied here too, but the OpenAI path has
946// not yet been exercised against a real endpoint (only Anthropic has). Verify against a real key
947// before relying on it in production.
948#[derive(Debug, Clone)]
949pub struct OpenAiProvider {
950    /// Ladder prefix / trace label for this provider (`"openai"`, `"groq"`, `"together"`, …).
951    pub id: String,
952    /// Base URL, e.g. `https://api.openai.com` or `https://api.groq.com/openai`.
953    pub base_url: String,
954    /// Env var the API key is read from, e.g. `"GROQ_API_KEY"`. `None` for the built-in `openai`
955    /// provider (resolves via [`Auth`]: `authorization` header or `OPENAI_API_KEY`) and for keyless
956    /// local endpoints (Ollama / vLLM).
957    pub api_key_env: Option<String>,
958    /// Shared, connection-pooled HTTP client.
959    pub http: reqwest::Client,
960}
961
962#[async_trait]
963impl Provider for OpenAiProvider {
964    fn id(&self) -> &str {
965        &self.id
966    }
967
968    fn carries_structured_verbatim(&self, inbound: firstpass_core::Dialect) -> bool {
969        inbound == firstpass_core::Dialect::Openai
970    }
971
972    async fn complete(
973        &self,
974        req: &ModelRequest,
975        auth: &Auth,
976    ) -> Result<ModelResponse, ProviderError> {
977        let key = resolve_api_key(self.api_key_env.as_deref(), auth.openai_key.as_deref());
978        let body = openai_wire_body(req);
979
980        let url = format!(
981            "{}/v1/chat/completions",
982            self.base_url.trim_end_matches('/')
983        );
984        let resp = self
985            .http
986            .post(url)
987            .header(axum::http::header::AUTHORIZATION, format!("Bearer {key}"))
988            .json(&body)
989            .send()
990            .await
991            .map_err(|e| ProviderError::Transport(e.to_string()))?;
992
993        let status = resp.status();
994        let bytes = resp
995            .bytes()
996            .await
997            .map_err(|e| ProviderError::Transport(e.to_string()))?;
998
999        if !status.is_success() {
1000            return Err(ProviderError::Http {
1001                status: status.as_u16(),
1002                body: String::from_utf8_lossy(&bytes).into_owned(),
1003            });
1004        }
1005
1006        let json: Value =
1007            serde_json::from_slice(&bytes).map_err(|e| ProviderError::Decode(e.to_string()))?;
1008
1009        // `content` is null for tool-call-only responses; treat as empty text rather than an error.
1010        let text = json
1011            .pointer("/choices/0/message/content")
1012            .and_then(Value::as_str)
1013            .unwrap_or("")
1014            .to_owned();
1015
1016        let in_tokens = json
1017            .pointer("/usage/prompt_tokens")
1018            .and_then(Value::as_u64)
1019            .unwrap_or(0);
1020        let out_tokens = json
1021            .pointer("/usage/completion_tokens")
1022            .and_then(Value::as_u64)
1023            .unwrap_or(0);
1024
1025        Ok(ModelResponse {
1026            // This provider reports no prompt-cache split.
1027            cache_write_tokens: 0,
1028            cache_read_tokens: 0,
1029            model: req.model.clone(),
1030            text,
1031            in_tokens,
1032            out_tokens,
1033            raw: json,
1034        })
1035    }
1036}
1037
1038/// Build the Gemini `generateContent` request body from a normalized [`ModelRequest`]. Split out
1039/// (pure, no I/O) so the translation is unit-tested offline. Gemini uses `contents` with roles
1040/// `user` / `model` (not `assistant`) and a separate `systemInstruction`; the system prompt and the
1041/// per-message text projection ([`ChatMessage::text_view`]) are what we send. Tool/multimodal blocks
1042/// for Gemini (its `functionCall` / `functionResponse` / `inlineData` shapes) are a follow-on — this
1043/// adapter routes text, matching the OpenAI adapter's current scope.
1044fn gemini_request_body(req: &ModelRequest) -> Value {
1045    let contents: Vec<Value> = req
1046        .messages
1047        .iter()
1048        .map(|m| {
1049            let role = if m.role == "assistant" {
1050                "model"
1051            } else {
1052                "user"
1053            };
1054            serde_json::json!({ "role": role, "parts": [{ "text": m.text_view() }] })
1055        })
1056        .collect();
1057    let mut body = serde_json::json!({
1058        "contents": contents,
1059        "generationConfig": { "maxOutputTokens": req.max_tokens },
1060    });
1061    if let Some(system) = req.system.as_deref() {
1062        body["systemInstruction"] = serde_json::json!({ "parts": [{ "text": system }] });
1063    }
1064    // This builder reconstructs from normalized fields, so the caller's reasoning request is only
1065    // in `raw` — carry it across rather than dropping it on the Gemini rung.
1066    if let (Some(effort), Some(map)) = (effort_of(&req.raw), body.as_object_mut()) {
1067        let mut carry = serde_json::Map::new();
1068        carry.insert(
1069            "reasoning_effort".to_owned(),
1070            Value::String(effort.as_str().to_owned()),
1071        );
1072        carry.insert(
1073            "generationConfig".to_owned(),
1074            map["generationConfig"].clone(),
1075        );
1076        normalize_reasoning(&mut carry, Wire::Gemini);
1077        map.insert(
1078            "generationConfig".to_owned(),
1079            carry["generationConfig"].clone(),
1080        );
1081    }
1082    body
1083}
1084
1085/// Extract `(text, in_tokens, out_tokens)` from a Gemini `generateContent` response. `text` is the
1086/// concatenation of the first candidate's text parts; token counts come from `usageMetadata`.
1087fn gemini_parse_response(json: &Value) -> Result<(String, u64, u64), ProviderError> {
1088    let parts = json
1089        .pointer("/candidates/0/content/parts")
1090        .and_then(Value::as_array)
1091        .ok_or_else(|| ProviderError::Decode("missing candidates[0].content.parts".to_owned()))?;
1092    let text = parts
1093        .iter()
1094        .filter_map(|p| p.get("text").and_then(Value::as_str))
1095        .collect::<Vec<_>>()
1096        .join("");
1097    let in_tokens = json
1098        .pointer("/usageMetadata/promptTokenCount")
1099        .and_then(Value::as_u64)
1100        .unwrap_or(0);
1101    // Thinking tokens (Gemini 2.5+/3) are billed as output; leaving them out under-bills.
1102    // ponytail: cachedContentTokenCount is not split out here, so implicit cache hits are
1103    // priced at the full input rate (over-, never under-billing); split it if that matters.
1104    let u = |ptr: &str| json.pointer(ptr).and_then(Value::as_u64).unwrap_or(0);
1105    let out_tokens =
1106        u("/usageMetadata/candidatesTokenCount") + u("/usageMetadata/thoughtsTokenCount");
1107    Ok((text, in_tokens, out_tokens))
1108}
1109
1110/// Speaks `POST {base}/v1beta/models/{model}:generateContent` (Google Gemini Generative Language
1111/// API). The API key goes in the `x-goog-api-key` header — never the URL query string, so it stays
1112/// out of logs and proxies.
1113///
1114// LIVE-VERIFIED (2026-08-03): served `google/gemini-3.5-flash-lite` end to end through the real
1115// proxy against the real endpoint, with a receipt, in the `provider-smoke` matrix. Note the
1116// timestamp — that is a claim about a commit, not a standing property.
1117#[derive(Debug, Clone)]
1118pub struct GeminiProvider {
1119    /// Ladder prefix / trace label (usually `"gemini"` or `"google"`).
1120    pub id: String,
1121    /// Base URL, e.g. `https://generativelanguage.googleapis.com`.
1122    pub base_url: String,
1123    /// Env var the API key is read from, e.g. `"GEMINI_API_KEY"`.
1124    pub api_key_env: Option<String>,
1125    /// Shared, connection-pooled HTTP client.
1126    pub http: reqwest::Client,
1127}
1128
1129#[async_trait]
1130impl Provider for GeminiProvider {
1131    fn id(&self) -> &str {
1132        &self.id
1133    }
1134
1135    async fn complete(
1136        &self,
1137        req: &ModelRequest,
1138        auth: &Auth,
1139    ) -> Result<ModelResponse, ProviderError> {
1140        // A configured api_key_env wins and never falls through (it is *this* provider's key);
1141        // otherwise the inbound x-goog-api-key, Gemini dialect only. Never auth.openai_key.
1142        let key = resolve_api_key(self.api_key_env.as_deref(), auth.gemini_key.as_deref());
1143        let body = gemini_request_body(req);
1144        let url = format!(
1145            "{}/v1beta/models/{}:generateContent",
1146            self.base_url.trim_end_matches('/'),
1147            wire_model(&req.model),
1148        );
1149        let resp = self
1150            .http
1151            .post(url)
1152            .header("x-goog-api-key", key)
1153            .json(&body)
1154            .send()
1155            .await
1156            .map_err(|e| ProviderError::Transport(e.to_string()))?;
1157
1158        let status = resp.status();
1159        let bytes = resp
1160            .bytes()
1161            .await
1162            .map_err(|e| ProviderError::Transport(e.to_string()))?;
1163        if !status.is_success() {
1164            return Err(ProviderError::Http {
1165                status: status.as_u16(),
1166                body: String::from_utf8_lossy(&bytes).into_owned(),
1167            });
1168        }
1169
1170        let json: Value =
1171            serde_json::from_slice(&bytes).map_err(|e| ProviderError::Decode(e.to_string()))?;
1172        let (text, in_tokens, out_tokens) = gemini_parse_response(&json)?;
1173        Ok(ModelResponse {
1174            // This provider reports no prompt-cache split.
1175            cache_write_tokens: 0,
1176            cache_read_tokens: 0,
1177            model: req.model.clone(),
1178            text,
1179            in_tokens,
1180            out_tokens,
1181            raw: json,
1182        })
1183    }
1184}
1185
1186/// AWS credentials read fresh from the standard env vars at call time — never cached, never
1187/// logged (ADR 0006 P2). `AWS_SESSION_TOKEN` is optional (long-lived IAM user keys have none;
1188/// STS-issued temporary credentials do).
1189struct AwsEnvCredentials {
1190    access_key_id: String,
1191    secret_access_key: String,
1192    session_token: Option<String>,
1193}
1194
1195impl AwsEnvCredentials {
1196    fn from_env() -> Result<Self, ProviderError> {
1197        let access_key_id = std::env::var("AWS_ACCESS_KEY_ID")
1198            .map_err(|_| ProviderError::Transport("AWS_ACCESS_KEY_ID is not set".to_owned()))?;
1199        let secret_access_key = std::env::var("AWS_SECRET_ACCESS_KEY")
1200            .map_err(|_| ProviderError::Transport("AWS_SECRET_ACCESS_KEY is not set".to_owned()))?;
1201        let session_token = std::env::var("AWS_SESSION_TOKEN").ok();
1202        Ok(Self {
1203            access_key_id,
1204            secret_access_key,
1205            session_token,
1206        })
1207    }
1208}
1209
1210/// Build the Bedrock `invoke` URL for a region + wire model id.
1211fn bedrock_url(region: &str, model: &str) -> String {
1212    format!("https://bedrock-runtime.{region}.amazonaws.com/model/{model}/invoke")
1213}
1214
1215/// SigV4-sign a Bedrock `InvokeModel` request, returning the fully-built (headers + body) HTTP
1216/// request ready to hand to reqwest. Delegates all canonical-request construction and HMAC signing
1217/// to `aws-sigv4` (ADR 0006 I3) — this function only wires host/service/region into that crate's
1218/// API and applies the resulting signature. Split out from [`BedrockProvider::complete`] so the
1219/// signing shape (not its cryptographic validity, which only a real AWS call can prove) is
1220/// unit-testable offline with dummy credentials.
1221///
1222// LIVE-UNVERIFIED: tests assert the produced request carries an `AWS4-HMAC-SHA256` authorization
1223// header and the expected host, against dummy credentials. Signature validity is only provable
1224// against a real Bedrock endpoint.
1225fn sign_bedrock(
1226    url: &str,
1227    region: &str,
1228    body: &[u8],
1229    creds: &AwsEnvCredentials,
1230) -> Result<http::Request<Vec<u8>>, ProviderError> {
1231    let host = url
1232        .parse::<http::Uri>()
1233        .ok()
1234        .and_then(|u| u.host().map(str::to_owned))
1235        .ok_or_else(|| ProviderError::Transport(format!("invalid bedrock URL: {url}")))?;
1236
1237    let identity: aws_smithy_runtime_api::client::identity::Identity =
1238        aws_credential_types::Credentials::new(
1239            creds.access_key_id.clone(),
1240            creds.secret_access_key.clone(),
1241            creds.session_token.clone(),
1242            None,
1243            "firstpass",
1244        )
1245        .into();
1246
1247    let signing_params: aws_sigv4::http_request::SigningParams<'_> =
1248        aws_sigv4::sign::v4::SigningParams::builder()
1249            .identity(&identity)
1250            .region(region)
1251            .name("bedrock")
1252            .time(SystemTime::now())
1253            .settings(aws_sigv4::http_request::SigningSettings::default())
1254            .build()
1255            .map_err(|e| ProviderError::Transport(format!("sigv4 signing params: {e}")))?
1256            .into();
1257
1258    let headers = [
1259        ("host", host.as_str()),
1260        ("content-type", "application/json"),
1261    ];
1262    let signable = aws_sigv4::http_request::SignableRequest::new(
1263        "POST",
1264        url,
1265        headers.into_iter(),
1266        aws_sigv4::http_request::SignableBody::Bytes(body),
1267    )
1268    .map_err(|e| ProviderError::Transport(format!("sigv4 signable request: {e}")))?;
1269
1270    let (instructions, _signature) = aws_sigv4::http_request::sign(signable, &signing_params)
1271        .map_err(|e| ProviderError::Transport(format!("sigv4 sign: {e}")))?
1272        .into_parts();
1273
1274    let mut req = http::Request::builder()
1275        .method("POST")
1276        .uri(url)
1277        .header("host", host)
1278        .header("content-type", "application/json")
1279        .body(body.to_vec())
1280        .map_err(|e| ProviderError::Transport(format!("build bedrock request: {e}")))?;
1281    instructions.apply_to_request_http1x(&mut req);
1282    Ok(req)
1283}
1284
1285/// Speaks `POST https://bedrock-runtime.{region}.amazonaws.com/model/{model}/invoke` (Claude on AWS
1286/// Bedrock) — an Anthropic-shaped body ([`anthropic_messages_body`]) authenticated with AWS SigV4
1287/// request signing rather than an API key (ADR 0006 P2). Credentials come from the standard
1288/// `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN` env vars, read fresh per
1289/// call — never logged, never put in the URL (I2).
1290///
1291// LIVE-UNVERIFIED: the request/response translation and signing call shape are unit-tested
1292// offline; this has not been exercised against a real Bedrock endpoint. Verify against real AWS
1293// credentials before relying on it in production.
1294#[derive(Debug, Clone)]
1295pub struct BedrockProvider {
1296    /// Ladder prefix / trace label (usually `"bedrock"`).
1297    pub id: String,
1298    /// AWS region Bedrock is called in, e.g. `"us-east-1"`.
1299    pub region: Option<String>,
1300    /// Shared, connection-pooled HTTP client.
1301    pub http: reqwest::Client,
1302}
1303
1304#[async_trait]
1305impl Provider for BedrockProvider {
1306    fn id(&self) -> &str {
1307        &self.id
1308    }
1309
1310    fn carries_structured_verbatim(&self, inbound: firstpass_core::Dialect) -> bool {
1311        inbound == firstpass_core::Dialect::Anthropic
1312    }
1313
1314    async fn complete(
1315        &self,
1316        req: &ModelRequest,
1317        _auth: &Auth,
1318    ) -> Result<ModelResponse, ProviderError> {
1319        let region = self.region.as_deref().ok_or_else(|| {
1320            ProviderError::Transport("bedrock provider requires a region".to_owned())
1321        })?;
1322        let model = wire_model(&req.model);
1323        let url = bedrock_url(region, model);
1324        let body = anthropic_messages_body(req, "bedrock-2023-05-31");
1325        let body_bytes =
1326            serde_json::to_vec(&body).map_err(|e| ProviderError::Decode(e.to_string()))?;
1327
1328        let creds = AwsEnvCredentials::from_env()?;
1329        let signed = sign_bedrock(&url, region, &body_bytes, &creds)?;
1330        let http_req = reqwest::Request::try_from(signed)
1331            .map_err(|e| ProviderError::Transport(format!("build reqwest request: {e}")))?;
1332
1333        let resp = self
1334            .http
1335            .execute(http_req)
1336            .await
1337            .map_err(|e| ProviderError::Transport(e.to_string()))?;
1338
1339        let status = resp.status();
1340        let bytes = resp
1341            .bytes()
1342            .await
1343            .map_err(|e| ProviderError::Transport(e.to_string()))?;
1344        if !status.is_success() {
1345            return Err(ProviderError::Http {
1346                status: status.as_u16(),
1347                body: String::from_utf8_lossy(&bytes).into_owned(),
1348            });
1349        }
1350
1351        let json: Value =
1352            serde_json::from_slice(&bytes).map_err(|e| ProviderError::Decode(e.to_string()))?;
1353        let u = anthropic_parse_response(&json)?;
1354        let (text, in_tokens, out_tokens) = (u.text, u.in_tokens, u.out_tokens);
1355        let (cache_write_tokens, cache_read_tokens) = (u.cache_write_tokens, u.cache_read_tokens);
1356        Ok(ModelResponse {
1357            cache_write_tokens,
1358            cache_read_tokens,
1359            model: req.model.clone(),
1360            text,
1361            in_tokens,
1362            out_tokens,
1363            raw: json,
1364        })
1365    }
1366}
1367
1368/// Build the Vertex AI `rawPredict` URL for a region + project + wire model id (Claude on Vertex).
1369fn vertex_url(region: &str, project: &str, model: &str) -> String {
1370    format!(
1371        "https://{region}-aiplatform.googleapis.com/v1/projects/{project}/locations/{region}/publishers/anthropic/models/{model}:rawPredict"
1372    )
1373}
1374
1375/// Speaks `POST https://{region}-aiplatform.googleapis.com/.../publishers/anthropic/models/{model}:rawPredict`
1376/// (Claude on Google Vertex AI) — an Anthropic-shaped body ([`anthropic_messages_body`])
1377/// authenticated with a GCP OAuth2 bearer token rather than an API key (ADR 0006 P3). The token is
1378/// minted and cached by `gcp_auth` from `GOOGLE_APPLICATION_CREDENTIALS` or the ambient GCP
1379/// environment — this adapter never caches or logs it, and it never goes in the URL (I2).
1380///
1381// LIVE-UNVERIFIED: the request/response translation is unit-tested offline; this has not been
1382// exercised against a real Vertex endpoint. Verify against a real service account before relying
1383// on it in production.
1384#[derive(Debug, Clone)]
1385pub struct VertexProvider {
1386    /// Ladder prefix / trace label (usually `"vertex"`).
1387    pub id: String,
1388    /// GCP region Vertex is called in, e.g. `"us-central1"`.
1389    pub region: Option<String>,
1390    /// GCP project id.
1391    pub project: Option<String>,
1392    /// Shared, connection-pooled HTTP client.
1393    pub http: reqwest::Client,
1394}
1395
1396#[async_trait]
1397impl Provider for VertexProvider {
1398    fn id(&self) -> &str {
1399        &self.id
1400    }
1401
1402    fn carries_structured_verbatim(&self, inbound: firstpass_core::Dialect) -> bool {
1403        inbound == firstpass_core::Dialect::Anthropic
1404    }
1405
1406    async fn complete(
1407        &self,
1408        req: &ModelRequest,
1409        _auth: &Auth,
1410    ) -> Result<ModelResponse, ProviderError> {
1411        let region = self.region.as_deref().ok_or_else(|| {
1412            ProviderError::Transport("vertex provider requires a region".to_owned())
1413        })?;
1414        let project = self.project.as_deref().ok_or_else(|| {
1415            ProviderError::Transport("vertex provider requires a project".to_owned())
1416        })?;
1417        let model = wire_model(&req.model);
1418        let url = vertex_url(region, project, model);
1419        let body = anthropic_messages_body(req, "vertex-2023-10-16");
1420
1421        // ponytail: gcp_auth re-detects the auth method per call (the token itself is cached inside
1422        // the provider). Cache the provider in a OnceCell if Vertex ever becomes a hot path.
1423        let provider = gcp_auth::provider()
1424            .await
1425            .map_err(|e| ProviderError::Transport(format!("gcp_auth provider: {e}")))?;
1426        let token = provider
1427            .token(&["https://www.googleapis.com/auth/cloud-platform"])
1428            .await
1429            .map_err(|e| ProviderError::Transport(format!("gcp_auth token: {e}")))?;
1430
1431        let resp = self
1432            .http
1433            .post(url)
1434            .header(
1435                axum::http::header::AUTHORIZATION,
1436                format!("Bearer {}", token.as_str()),
1437            )
1438            .json(&body)
1439            .send()
1440            .await
1441            .map_err(|e| ProviderError::Transport(e.to_string()))?;
1442
1443        let status = resp.status();
1444        let bytes = resp
1445            .bytes()
1446            .await
1447            .map_err(|e| ProviderError::Transport(e.to_string()))?;
1448        if !status.is_success() {
1449            return Err(ProviderError::Http {
1450                status: status.as_u16(),
1451                body: String::from_utf8_lossy(&bytes).into_owned(),
1452            });
1453        }
1454
1455        let json: Value =
1456            serde_json::from_slice(&bytes).map_err(|e| ProviderError::Decode(e.to_string()))?;
1457        let u = anthropic_parse_response(&json)?;
1458        let (text, in_tokens, out_tokens) = (u.text, u.in_tokens, u.out_tokens);
1459        let (cache_write_tokens, cache_read_tokens) = (u.cache_write_tokens, u.cache_read_tokens);
1460        Ok(ModelResponse {
1461            cache_write_tokens,
1462            cache_read_tokens,
1463            model: req.model.clone(),
1464            text,
1465            in_tokens,
1466            out_tokens,
1467            raw: json,
1468        })
1469    }
1470}
1471
1472/// Lookup from provider id (`"anthropic"`, `"openai"`, ...) to the [`Provider`] that serves it.
1473#[derive(Clone)]
1474pub struct ProviderRegistry {
1475    providers: HashMap<String, Arc<dyn Provider>>,
1476}
1477
1478impl std::fmt::Debug for ProviderRegistry {
1479    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1480        f.debug_struct("ProviderRegistry")
1481            .field("providers", &self.providers.keys().collect::<Vec<_>>())
1482            .finish()
1483    }
1484}
1485
1486/// The env var a built-in OpenAI-compatible provider reads its key from, if `id` is one.
1487///
1488/// Exposed so `doctor` can report a missing key at setup time rather than letting the first real
1489/// request discover it.
1490#[must_use]
1491pub fn builtin_key_env(id: &str) -> Option<&'static str> {
1492    BUILTIN_OPENAI_COMPATIBLE
1493        .iter()
1494        .find(|(p, _, _)| *p == id)
1495        .map(|(_, _, k)| *k)
1496}
1497
1498impl ProviderRegistry {
1499    /// One HTTP client shared by every provider. The enforce path is request/response (never
1500    /// streamed through the adapter), so it carries a total request timeout as well as a connect
1501    /// timeout — a hung or slow upstream can't pin a routing decision indefinitely. The total is
1502    /// 600 s, the Anthropic SDK's own default: a long generation (12k output tokens) legitimately
1503    /// runs past two minutes, and a shorter cap turns it into a provider error on every rung.
1504    /// Falls back to a default client if the builder fails (only on TLS backend init, which is
1505    /// fatal anyway).
1506    fn build_http_client() -> reqwest::Client {
1507        reqwest::Client::builder()
1508            .connect_timeout(std::time::Duration::from_secs(10))
1509            .timeout(std::time::Duration::from_secs(600))
1510            .build()
1511            .unwrap_or_else(|_| reqwest::Client::new())
1512    }
1513
1514    /// Build the standard registry: the built-in `anthropic` + `openai` providers.
1515    #[must_use]
1516    pub fn new(anthropic_base: impl Into<String>, openai_base: impl Into<String>) -> Self {
1517        Self::from_config(&[], anthropic_base, openai_base)
1518    }
1519
1520    /// Build the registry with the built-in `anthropic` / `openai` providers plus every configured
1521    /// `[[provider]]` entry — so a ladder can route to any OpenAI-compatible or Anthropic-compatible
1522    /// endpoint (Groq, Together, Fireworks, DeepSeek, Mistral, xAI, OpenRouter, Ollama, vLLM, Azure,
1523    /// …) by id. A `[[provider]]` whose id is `anthropic` or `openai` overrides the built-in default
1524    /// (e.g. to point `openai` at Azure). Shares one HTTP client across all of them.
1525    #[must_use]
1526    pub fn from_config(
1527        defs: &[firstpass_core::ProviderDef],
1528        anthropic_base: impl Into<String>,
1529        openai_base: impl Into<String>,
1530    ) -> Self {
1531        let http = Self::build_http_client();
1532        let mut providers: HashMap<String, Arc<dyn Provider>> = HashMap::new();
1533        providers.insert(
1534            "anthropic".to_owned(),
1535            Arc::new(AnthropicProvider {
1536                id: "anthropic".to_owned(),
1537                base_url: anthropic_base.into(),
1538                api_key_env: None,
1539                http: http.clone(),
1540            }),
1541        );
1542        providers.insert(
1543            "openai".to_owned(),
1544            Arc::new(OpenAiProvider {
1545                id: "openai".to_owned(),
1546                base_url: openai_base.into(),
1547                api_key_env: None,
1548                http: http.clone(),
1549            }),
1550        );
1551        // Registered BEFORE user `[[provider]]` blocks so an explicit definition overrides the
1552        // built-in — an operator pointing `groq` at a proxy of their own must win over our default.
1553        for (id, base, key_env) in BUILTIN_OPENAI_COMPATIBLE {
1554            providers.insert(
1555                (*id).to_owned(),
1556                Arc::new(OpenAiProvider {
1557                    id: (*id).to_owned(),
1558                    base_url: (*base).to_owned(),
1559                    api_key_env: Some((*key_env).to_owned()),
1560                    http: http.clone(),
1561                }),
1562            );
1563        }
1564        for def in defs {
1565            // Auth scheme comes first (ADR 0006): `aws_sigv4`/`gcp_oauth` are bespoke-auth
1566            // backends that wrap the Anthropic body shape regardless of `dialect`; `api_key`
1567            // (the default) is today's dialect-driven dispatch, unchanged.
1568            let provider: Arc<dyn Provider> = match def.auth {
1569                firstpass_core::AuthScheme::AwsSigv4 => Arc::new(BedrockProvider {
1570                    id: def.id.clone(),
1571                    region: def.region.clone(),
1572                    http: http.clone(),
1573                }),
1574                firstpass_core::AuthScheme::GcpOauth => Arc::new(VertexProvider {
1575                    id: def.id.clone(),
1576                    region: def.region.clone(),
1577                    project: def.project.clone(),
1578                    http: http.clone(),
1579                }),
1580                firstpass_core::AuthScheme::ApiKey => match def.dialect {
1581                    firstpass_core::Dialect::Anthropic => Arc::new(AnthropicProvider {
1582                        id: def.id.clone(),
1583                        base_url: def.base_url.clone(),
1584                        api_key_env: def.api_key_env.clone(),
1585                        http: http.clone(),
1586                    }),
1587                    firstpass_core::Dialect::Openai => Arc::new(OpenAiProvider {
1588                        id: def.id.clone(),
1589                        base_url: def.base_url.clone(),
1590                        api_key_env: def.api_key_env.clone(),
1591                        http: http.clone(),
1592                    }),
1593                    firstpass_core::Dialect::Gemini => Arc::new(GeminiProvider {
1594                        id: def.id.clone(),
1595                        base_url: def.base_url.clone(),
1596                        api_key_env: def.api_key_env.clone(),
1597                        http: http.clone(),
1598                    }),
1599                },
1600            };
1601            providers.insert(def.id.clone(), provider);
1602        }
1603        Self { providers }
1604    }
1605
1606    /// Build a registry from arbitrary providers — used to wire up [`MockProvider`]s in tests.
1607    #[must_use]
1608    pub fn from_map(providers: HashMap<String, Arc<dyn Provider>>) -> Self {
1609        Self { providers }
1610    }
1611
1612    /// Look up a provider by id.
1613    #[must_use]
1614    pub fn get(&self, provider_id: &str) -> Option<Arc<dyn Provider>> {
1615        self.providers.get(provider_id).cloned()
1616    }
1617}
1618
1619/// Test-only provider: returns a pre-programmed outcome per model, deterministically.
1620#[cfg(test)]
1621#[derive(Debug, Clone, Default)]
1622pub struct MockProvider {
1623    id: String,
1624    outcomes: HashMap<String, Result<ModelResponse, ProviderError>>,
1625    /// Every model string `complete()` was called with — lets speculation tests assert which rungs
1626    /// were actually fired. Shared (`Arc`) so a clone taken before boxing still observes the calls.
1627    calls: Arc<std::sync::Mutex<Vec<String>>>,
1628    /// Simulated per-call latency (0 = respond instantly). Lets a test measure the wall-clock win
1629    /// speculation buys by overlapping rung calls that would otherwise run serially.
1630    delay_ms: u64,
1631}
1632
1633#[cfg(test)]
1634impl MockProvider {
1635    /// Build a mock provider that answers `outcomes[model]` for `complete()`.
1636    #[must_use]
1637    pub fn new(
1638        id: impl Into<String>,
1639        outcomes: HashMap<String, Result<ModelResponse, ProviderError>>,
1640    ) -> Self {
1641        Self {
1642            id: id.into(),
1643            outcomes,
1644            calls: Arc::default(),
1645            delay_ms: 0,
1646        }
1647    }
1648
1649    /// Make `complete()` sleep `ms` before responding, to simulate real per-call latency.
1650    #[must_use]
1651    pub fn with_delay(mut self, ms: u64) -> Self {
1652        self.delay_ms = ms;
1653        self
1654    }
1655
1656    /// A handle to the shared call log; clone it before boxing the provider into a registry, then
1657    /// inspect the models `complete()` saw after the engine runs.
1658    #[must_use]
1659    pub fn call_log(&self) -> Arc<std::sync::Mutex<Vec<String>>> {
1660        Arc::clone(&self.calls)
1661    }
1662}
1663
1664#[cfg(test)]
1665#[async_trait]
1666impl Provider for MockProvider {
1667    fn id(&self) -> &str {
1668        &self.id
1669    }
1670
1671    // ponytail: returns true for all dialects — test-only mock needs to pass the fidelity guard
1672    // for both Anthropic and OpenAI inbound tests without a real dialect-split implementation.
1673    fn carries_structured_verbatim(&self, _inbound: firstpass_core::Dialect) -> bool {
1674        true
1675    }
1676
1677    async fn complete(
1678        &self,
1679        req: &ModelRequest,
1680        _auth: &Auth,
1681    ) -> Result<ModelResponse, ProviderError> {
1682        self.calls.lock().unwrap().push(req.model.clone());
1683        if self.delay_ms > 0 {
1684            tokio::time::sleep(std::time::Duration::from_millis(self.delay_ms)).await;
1685        }
1686        self.outcomes.get(&req.model).cloned().unwrap_or_else(|| {
1687            Err(ProviderError::Decode(format!(
1688                "no mock outcome configured for {}",
1689                req.model
1690            )))
1691        })
1692    }
1693}
1694
1695#[cfg(test)]
1696mod tests {
1697    /// Every provider's way of saying "stopped at the output-token limit" is recognised, and a
1698    /// normal stop or an unknown shape is not.
1699    #[test]
1700    fn output_limit_is_detected_across_providers() {
1701        use serde_json::json;
1702        for raw in [
1703            json!({"stop_reason": "max_tokens"}),
1704            json!({"choices": [{"finish_reason": "length"}]}),
1705            json!({"status": "incomplete", "incomplete_details": {"reason": "max_output_tokens"}}),
1706            json!({"candidates": [{"finishReason": "MAX_TOKENS"}]}),
1707        ] {
1708            assert!(hit_output_limit(&raw), "{raw}");
1709        }
1710        for raw in [
1711            json!({"stop_reason": "end_turn"}),
1712            json!({"choices": [{"finish_reason": "stop"}]}),
1713            json!({"incomplete_details": {"reason": "content_filter"}}),
1714            json!({"candidates": [{"finishReason": "STOP"}]}),
1715            serde_json::Value::Null,
1716        ] {
1717            assert!(!hit_output_limit(&raw), "{raw}");
1718        }
1719    }
1720
1721    use super::*;
1722
1723    fn obj(v: Value) -> serde_json::Map<String, Value> {
1724        v.as_object().expect("test literal is an object").clone()
1725    }
1726
1727    #[test]
1728    fn openai_reasoning_effort_crosses_onto_an_anthropic_rung() {
1729        // The bug this exists for: a ladder is routinely cross-vendor, so an OpenAI client that
1730        // set `reasoning_effort` gets escalated onto an Anthropic rung. Forwarded verbatim that
1731        // is a 400 on a request the caller wrote correctly.
1732        let mut body = obj(serde_json::json!({
1733            "model": "claude-sonnet-5", "max_tokens": 8192, "reasoning_effort": "high",
1734        }));
1735
1736        normalize_reasoning(&mut body, Wire::Anthropic);
1737
1738        assert!(
1739            !body.contains_key("reasoning_effort"),
1740            "the foreign spelling must not survive: {body:?}"
1741        );
1742        assert_eq!(body["thinking"]["type"], "enabled");
1743        // Clamped to max_tokens - 1: "high" wants 16384, but Anthropic requires the budget to
1744        // leave room for the answer itself.
1745        assert_eq!(body["thinking"]["budget_tokens"], 8191);
1746    }
1747
1748    #[test]
1749    fn anthropic_thinking_budget_crosses_onto_an_openai_rung_as_a_word() {
1750        let mut body = obj(serde_json::json!({
1751            "model": "gpt-5.5",
1752            "thinking": { "type": "enabled", "budget_tokens": 16384 },
1753        }));
1754
1755        normalize_reasoning(&mut body, Wire::OpenAi);
1756
1757        assert!(!body.contains_key("thinking"));
1758        assert_eq!(body["reasoning_effort"], "high");
1759    }
1760
1761    #[test]
1762    fn thinking_is_dropped_rather_than_sent_invalid_when_max_tokens_cannot_fit_it() {
1763        // Anthropic requires budget >= 1024 AND max_tokens > budget. A caller asking for high
1764        // effort with max_tokens=500 cannot have both; sending it anyway is a 400. Serving
1765        // without extended thinking is the answer the caller can actually use.
1766        let mut body = obj(serde_json::json!({
1767            "model": "claude-sonnet-5", "max_tokens": 500, "reasoning_effort": "high",
1768        }));
1769
1770        normalize_reasoning(&mut body, Wire::Anthropic);
1771
1772        assert!(
1773            !body.contains_key("thinking"),
1774            "must not emit a budget max_tokens cannot satisfy: {body:?}"
1775        );
1776        assert!(!body.contains_key("reasoning_effort"));
1777    }
1778
1779    #[test]
1780    fn enabling_thinking_clears_a_temperature_the_caller_chose_without_knowing() {
1781        // Extended thinking rejects any temperature but the default. The caller set it before the
1782        // router decided to enable thinking, so keeping it would 400.
1783        let mut body = obj(serde_json::json!({
1784            "model": "claude-sonnet-5", "max_tokens": 8192,
1785            "reasoning_effort": "medium", "temperature": 0.2, "top_p": 0.9,
1786        }));
1787
1788        normalize_reasoning(&mut body, Wire::Anthropic);
1789
1790        assert_eq!(body["thinking"]["budget_tokens"], 4096);
1791        assert!(!body.contains_key("temperature"), "{body:?}");
1792        assert!(!body.contains_key("top_p"), "{body:?}");
1793    }
1794
1795    #[test]
1796    fn a_body_that_asked_for_no_reasoning_is_left_alone() {
1797        let before = serde_json::json!({
1798            "model": "claude-sonnet-5", "max_tokens": 1024, "temperature": 0.7,
1799        });
1800        let mut body = obj(before.clone());
1801
1802        normalize_reasoning(&mut body, Wire::Anthropic);
1803
1804        assert_eq!(
1805            Value::Object(body),
1806            before,
1807            "no reasoning request, no rewrite"
1808        );
1809    }
1810
1811    #[test]
1812    fn gemini_gets_a_nested_budget_not_a_top_level_one() {
1813        let mut body = obj(serde_json::json!({
1814            "contents": [], "generationConfig": { "maxOutputTokens": 4096 },
1815            "reasoning_effort": "low",
1816        }));
1817
1818        normalize_reasoning(&mut body, Wire::Gemini);
1819
1820        assert_eq!(
1821            body["generationConfig"]["thinkingConfig"]["thinkingBudget"],
1822            1024
1823        );
1824        assert_eq!(
1825            body["generationConfig"]["maxOutputTokens"], 4096,
1826            "must not clobber the rest of generationConfig"
1827        );
1828        assert!(
1829            !body.contains_key("thinkingConfig"),
1830            "top level is wrong for Gemini"
1831        );
1832    }
1833
1834    #[test]
1835    fn a_same_dialect_body_is_never_rewritten_even_when_the_caller_got_it_wrong() {
1836        // budget_tokens(1024) > max_tokens(512) is invalid at Anthropic — and this request is
1837        // already Anthropic-spelled, so it is not ours to "fix". Rewriting it would serve a
1838        // different request than the caller wrote and hide the error that explains why.
1839        let before = serde_json::json!({
1840            "max_tokens": 512,
1841            "thinking": { "type": "enabled", "budget_tokens": 1024 },
1842        });
1843        let mut body = obj(before.clone());
1844
1845        normalize_reasoning(&mut body, Wire::Anthropic);
1846
1847        assert_eq!(Value::Object(body), before);
1848    }
1849
1850    #[test]
1851    fn disabled_thinking_is_not_read_as_a_request_to_think() {
1852        let body = obj(serde_json::json!({
1853            "thinking": { "type": "disabled", "budget_tokens": 16384 },
1854        }));
1855        assert_eq!(read_effort(&body), None);
1856    }
1857
1858    #[test]
1859    fn a_cached_response_reports_its_cache_tokens_not_just_the_remainder() {
1860        // A real cached Claude Code turn: the prompt is in the cache counters, and `input_tokens`
1861        // is the small uncached remainder. Reading only `input_tokens` — which this did — is how a
1862        // ~$0.70 call banked a receipt reading a fraction of a cent.
1863        let json = serde_json::json!({
1864            "content": [{ "type": "text", "text": "ok" }],
1865            "usage": {
1866                "input_tokens": 20,
1867                "cache_creation_input_tokens": 190_000,
1868                "cache_read_input_tokens": 1_234,
1869                "output_tokens": 400,
1870            },
1871        });
1872
1873        let u = anthropic_parse_response(&json).expect("parses");
1874
1875        assert_eq!(u.in_tokens, 20);
1876        assert_eq!(u.cache_write_tokens, 190_000);
1877        assert_eq!(u.cache_read_tokens, 1_234);
1878        assert_eq!(u.out_tokens, 400);
1879    }
1880
1881    #[test]
1882    fn an_uncached_response_reports_zero_cache_traffic() {
1883        // The overwhelmingly common case must be untouched.
1884        let json = serde_json::json!({
1885            "content": [{ "type": "text", "text": "ok" }],
1886            "usage": { "input_tokens": 1000, "output_tokens": 200 },
1887        });
1888
1889        let u = anthropic_parse_response(&json).expect("parses");
1890
1891        assert_eq!(u.in_tokens, 1000);
1892        assert_eq!(u.cache_write_tokens, 0);
1893        assert_eq!(u.cache_read_tokens, 0);
1894    }
1895
1896    #[test]
1897    fn cache_breakpoints_land_on_the_stable_prefix_only() {
1898        // System prompt and tool definitions are what repeat byte-for-byte across an agent's
1899        // turns. The conversation after them is not cached, and must not be marked.
1900        let mut body = obj(serde_json::json!({
1901            "model": "claude-sonnet-5",
1902            "system": "you are a careful assistant. ".repeat(200),
1903            "tools": [{ "name": "a" }, { "name": "b" }],
1904            "messages": [{ "role": "user", "content": "hi" }],
1905        }));
1906
1907        add_cache_breakpoints(&mut body);
1908
1909        // A bare string system cannot carry cache_control — it must become the block form.
1910        assert_eq!(body["system"][0]["type"], "text");
1911        assert_eq!(body["system"][0]["cache_control"]["type"], "ephemeral");
1912        assert!(
1913            body["system"][0]["text"]
1914                .as_str()
1915                .unwrap()
1916                .starts_with("you are a careful")
1917        );
1918        // Only the LAST tool: a breakpoint marks the end of a prefix, and one per tool would
1919        // spend the write premium several times over for the same prefix.
1920        assert!(body["tools"][0].get("cache_control").is_none());
1921        assert_eq!(body["tools"][1]["cache_control"]["type"], "ephemeral");
1922        assert!(
1923            body["messages"][0].get("cache_control").is_none(),
1924            "the conversation is not the stable prefix"
1925        );
1926    }
1927
1928    #[test]
1929    fn a_prefix_too_small_to_qualify_is_not_marked() {
1930        // Anthropic refuses to cache below a per-model minimum (1024 tokens, 2048 on Haiku), and
1931        // marking a shorter prefix is not merely wasted — it is a request the API can reject.
1932        let mut body = obj(serde_json::json!({
1933            "model": "claude-sonnet-5",
1934            "system": "be terse",
1935            "messages": [{ "role": "user", "content": "hi" }],
1936        }));
1937        let before = body.clone();
1938
1939        add_cache_breakpoints(&mut body);
1940
1941        assert_eq!(body, before, "a two-word system prompt cannot be cached");
1942    }
1943
1944    #[test]
1945    fn a_caller_that_placed_its_own_breakpoints_is_left_alone() {
1946        // They have knowledge of their own prefix that this code does not; adding more would
1947        // exceed Anthropic's breakpoint limit and re-bill the write premium.
1948        let before = serde_json::json!({
1949            "system": [{ "type": "text", "text": "s", "cache_control": { "type": "ephemeral" } }],
1950            "tools": [{ "name": "a" }],
1951        });
1952        let mut body = obj(before.clone());
1953
1954        add_cache_breakpoints(&mut body);
1955
1956        assert_eq!(Value::Object(body), before);
1957    }
1958
1959    #[test]
1960    fn nothing_is_marked_when_there_is_no_stable_prefix() {
1961        let mut body = obj(serde_json::json!({
1962            "model": "claude-sonnet-5",
1963            "messages": [{ "role": "user", "content": "one shot" }],
1964        }));
1965        let before = body.clone();
1966
1967        add_cache_breakpoints(&mut body);
1968
1969        assert_eq!(body, before, "no system, no tools — nothing to cache");
1970    }
1971
1972    #[test]
1973    fn breakpoints_are_off_unless_the_request_asks_for_them() {
1974        // The default path must be byte-identical to before this existed.
1975        let raw = serde_json::json!({
1976            "model": "claude-sonnet-5", "max_tokens": 64,
1977            "system": "a long stable system prefix. ".repeat(200),
1978            "messages": [{ "role": "user", "content": "hi" }],
1979        });
1980        let req = ModelRequest {
1981            model: "anthropic/claude-sonnet-5".to_owned(),
1982            system: Some("a long stable system prefix. ".repeat(200)),
1983            messages: vec![ChatMessage::text("user", "hi")],
1984            max_tokens: 64,
1985            tools: Value::Null,
1986            raw: raw.clone(),
1987            cache_prefix: false,
1988        };
1989
1990        let body = anthropic_wire_body(&req);
1991        assert!(body["system"].is_string(), "unchanged when opted out");
1992
1993        let opted = ModelRequest {
1994            cache_prefix: true,
1995            ..req
1996        };
1997        let body = anthropic_wire_body(&opted);
1998        assert_eq!(body["system"][0]["cache_control"]["type"], "ephemeral");
1999    }
2000
2001    #[test]
2002    fn breakpoints_apply_on_the_normalized_path_too() {
2003        // Found in review. The normalized branch is not a rare fallback — it is what every
2004        // translated request uses, and every CONDENSED one, since condensing clears `raw` on
2005        // purpose. Marking only the raw branch meant `prompt_cache` did nothing for exactly the
2006        // long conversations it exists to pay for.
2007        let req = ModelRequest {
2008            model: "anthropic/claude-sonnet-5".to_owned(),
2009            system: Some("stable prefix. ".repeat(300)),
2010            messages: vec![ChatMessage::text("user", "hi")],
2011            max_tokens: 64,
2012            tools: serde_json::json!([{ "name": "a" }]),
2013            raw: Value::Null, // no raw body → normalized build path
2014            cache_prefix: true,
2015        };
2016
2017        let body = anthropic_wire_body(&req);
2018
2019        assert_eq!(body["system"][0]["cache_control"]["type"], "ephemeral");
2020        assert_eq!(body["tools"][0]["cache_control"]["type"], "ephemeral");
2021    }
2022
2023    #[test]
2024    fn common_openai_compatible_providers_work_without_a_config_block() {
2025        // The breadth gap: a ladder naming `groq/…` previously needed a `[[provider]]` block, so
2026        // "bring your own provider" meant boilerplate before the first request.
2027        let reg = ProviderRegistry::from_config(
2028            &[],
2029            "https://api.anthropic.com",
2030            "https://api.openai.com",
2031        );
2032        for id in [
2033            "groq",
2034            "deepseek",
2035            "together",
2036            "fireworks",
2037            "mistral",
2038            "openrouter",
2039            "xai",
2040            "cerebras",
2041        ] {
2042            assert!(reg.get(id).is_some(), "{id} should be built in");
2043        }
2044        // The originals are untouched.
2045        assert!(reg.get("anthropic").is_some());
2046        assert!(reg.get("openai").is_some());
2047        assert!(reg.get("not-a-provider").is_none());
2048    }
2049
2050    #[test]
2051    fn an_explicit_provider_block_overrides_the_builtin() {
2052        // An operator pointing `groq` at a gateway of their own must win over our default —
2053        // otherwise the built-in silently routes their traffic to the public endpoint instead.
2054        let defs = vec![firstpass_core::ProviderDef {
2055            id: "groq".to_owned(),
2056            base_url: "https://internal.example.com/groq".to_owned(),
2057            api_key_env: Some("MY_KEY".to_owned()),
2058            dialect: firstpass_core::Dialect::Openai,
2059            auth: firstpass_core::AuthScheme::ApiKey,
2060            region: None,
2061            project: None,
2062        }];
2063
2064        let reg = ProviderRegistry::from_config(
2065            &defs,
2066            "https://api.anthropic.com",
2067            "https://api.openai.com",
2068        );
2069
2070        let p = reg.get("groq").expect("groq present");
2071        assert!(
2072            format!("{p:?}").contains("internal.example.com"),
2073            "the explicit block must win: {p:?}"
2074        );
2075    }
2076
2077    #[test]
2078    fn wire_model_strips_the_provider_prefix() {
2079        // Regression: sending "anthropic/claude-haiku-4-5" verbatim 404s at the provider.
2080        assert_eq!(wire_model("anthropic/claude-haiku-4-5"), "claude-haiku-4-5");
2081        assert_eq!(wire_model("openai/gpt-5.5"), "gpt-5.5");
2082        assert_eq!(wire_model("claude-opus-4-8"), "claude-opus-4-8"); // no prefix → unchanged
2083    }
2084
2085    #[test]
2086    fn gemini_request_maps_roles_and_system_instruction() {
2087        let req = ModelRequest {
2088            model: "gemini/gemini-2.0-flash".to_owned(),
2089            system: Some("be terse".to_owned()),
2090            messages: vec![
2091                ChatMessage::text("user", "hi"),
2092                ChatMessage::text("assistant", "hello"),
2093            ],
2094            max_tokens: 256,
2095            tools: Value::Null,
2096            raw: Value::Null,
2097            cache_prefix: false,
2098        };
2099        let body = gemini_request_body(&req);
2100        // System prompt goes in systemInstruction (canonical REST field name), not contents.
2101        assert_eq!(body["systemInstruction"]["parts"][0]["text"], "be terse");
2102        assert_eq!(body["generationConfig"]["maxOutputTokens"], 256);
2103        // Anthropic's "assistant" role becomes Gemini's "model"; "user" stays "user".
2104        assert_eq!(body["contents"][0]["role"], "user");
2105        assert_eq!(body["contents"][0]["parts"][0]["text"], "hi");
2106        assert_eq!(body["contents"][1]["role"], "model");
2107        assert_eq!(body["contents"][1]["parts"][0]["text"], "hello");
2108    }
2109
2110    #[test]
2111    fn gemini_response_parses_text_and_usage() {
2112        let json = serde_json::json!({
2113            "candidates": [{ "content": { "role": "model", "parts": [
2114                { "text": "the answer " }, { "text": "is 42" }
2115            ] } }],
2116            "usageMetadata": { "promptTokenCount": 11, "candidatesTokenCount": 4 }
2117        });
2118        let (text, in_tok, out_tok) = gemini_parse_response(&json).unwrap();
2119        assert_eq!(text, "the answer is 42");
2120        assert_eq!(in_tok, 11);
2121        assert_eq!(out_tok, 4);
2122        // A response with no candidates is a decode error, not a fabricated empty answer.
2123        assert!(gemini_parse_response(&serde_json::json!({ "candidates": [] })).is_err());
2124        let thinking = serde_json::json!({
2125            "candidates": [{ "content": { "parts": [{ "text": "ok" }] } }],
2126            "usageMetadata": { "promptTokenCount": 7, "candidatesTokenCount": 3, "thoughtsTokenCount": 40 }
2127        });
2128        let (_, _, out) = gemini_parse_response(&thinking).unwrap();
2129        assert_eq!(out, 43, "thinking tokens are billed output");
2130    }
2131
2132    #[test]
2133    fn from_config_wires_the_gemini_dialect() {
2134        let defs = vec![firstpass_core::ProviderDef {
2135            id: "gemini".to_owned(),
2136            dialect: firstpass_core::Dialect::Gemini,
2137            base_url: "https://generativelanguage.googleapis.com".to_owned(),
2138            api_key_env: Some("GEMINI_API_KEY".to_owned()),
2139            auth: firstpass_core::AuthScheme::ApiKey,
2140            region: None,
2141            project: None,
2142        }];
2143        let reg = ProviderRegistry::from_config(
2144            &defs,
2145            "https://api.anthropic.com",
2146            "https://api.openai.com",
2147        );
2148        assert_eq!(reg.get("gemini").unwrap().id(), "gemini");
2149    }
2150
2151    #[test]
2152    fn from_config_registers_custom_providers_alongside_builtins() {
2153        let defs = vec![
2154            firstpass_core::ProviderDef {
2155                id: "groq".to_owned(),
2156                dialect: firstpass_core::Dialect::Openai,
2157                base_url: "https://api.groq.com/openai".to_owned(),
2158                api_key_env: Some("GROQ_API_KEY".to_owned()),
2159                auth: firstpass_core::AuthScheme::ApiKey,
2160                region: None,
2161                project: None,
2162            },
2163            // A custom provider may override a built-in id (e.g. point `openai` at Azure).
2164            firstpass_core::ProviderDef {
2165                id: "openai".to_owned(),
2166                dialect: firstpass_core::Dialect::Openai,
2167                base_url: "https://my-azure.openai.azure.com".to_owned(),
2168                api_key_env: Some("AZURE_OPENAI_KEY".to_owned()),
2169                auth: firstpass_core::AuthScheme::ApiKey,
2170                region: None,
2171                project: None,
2172            },
2173        ];
2174        let reg = ProviderRegistry::from_config(
2175            &defs,
2176            "https://api.anthropic.com",
2177            "https://api.openai.com",
2178        );
2179        // Built-in anthropic is still present; the custom groq resolves and labels itself "groq".
2180        assert_eq!(reg.get("anthropic").unwrap().id(), "anthropic");
2181        assert_eq!(reg.get("groq").unwrap().id(), "groq");
2182        // Unknown provider → None (router fails over rather than guessing).
2183        assert!(reg.get("does-not-exist").is_none());
2184    }
2185
2186    #[test]
2187    fn anthropic_messages_body_omits_model_and_includes_system_only_when_set() {
2188        let req = ModelRequest {
2189            model: "bedrock/anthropic.claude-3-5-haiku".to_owned(),
2190            system: Some("be terse".to_owned()),
2191            messages: vec![
2192                ChatMessage::text("user", "hi"),
2193                ChatMessage {
2194                    role: "assistant".to_owned(),
2195                    content: serde_json::json!([{ "type": "text", "text": "hello" }]),
2196                },
2197            ],
2198            max_tokens: 128,
2199            tools: Value::Null,
2200            raw: Value::Null,
2201            cache_prefix: false,
2202        };
2203        let body = anthropic_messages_body(&req, "bedrock-2023-05-31");
2204        // Model goes in the URL for Bedrock/Vertex, never the body.
2205        assert!(body.get("model").is_none());
2206        assert_eq!(body["anthropic_version"], "bedrock-2023-05-31");
2207        assert_eq!(body["max_tokens"], 128);
2208        assert_eq!(body["system"], "be terse");
2209        assert_eq!(body["messages"][0]["content"], serde_json::json!("hi"));
2210        // Content-block arrays forward verbatim, same as the direct Anthropic adapter (ADR 0005).
2211        assert_eq!(
2212            body["messages"][1]["content"],
2213            serde_json::json!([{ "type": "text", "text": "hello" }])
2214        );
2215
2216        // No system prompt => no `system` key at all (not `null`).
2217        let req_no_system = ModelRequest {
2218            system: None,
2219            ..req
2220        };
2221        let body2 = anthropic_messages_body(&req_no_system, "vertex-2023-10-16");
2222        assert!(body2.get("system").is_none());
2223    }
2224
2225    #[test]
2226    fn bedrock_url_construction_and_missing_region() {
2227        assert_eq!(
2228            bedrock_url("us-east-1", "anthropic.claude-3-5-haiku-20241022-v1:0"),
2229            "https://bedrock-runtime.us-east-1.amazonaws.com/model/anthropic.claude-3-5-haiku-20241022-v1:0/invoke"
2230        );
2231    }
2232
2233    #[tokio::test]
2234    async fn bedrock_complete_errors_without_a_region() {
2235        let provider = BedrockProvider {
2236            id: "bedrock".to_owned(),
2237            region: None,
2238            http: reqwest::Client::new(),
2239        };
2240        let req = ModelRequest {
2241            model: "bedrock/anthropic.claude-3-5-haiku".to_owned(),
2242            system: None,
2243            messages: vec![],
2244            max_tokens: 16,
2245            tools: Value::Null,
2246            raw: Value::Null,
2247            cache_prefix: false,
2248        };
2249        let err = provider.complete(&req, &Auth::default()).await.unwrap_err();
2250        assert!(matches!(err, ProviderError::Transport(_)));
2251    }
2252
2253    #[test]
2254    fn bedrock_signing_produces_a_sigv4_authorization_header() {
2255        // Dummy, non-production credentials — this only proves the *shape* of the signed request
2256        // (algorithm header + host), not cryptographic validity against real AWS (LIVE-UNVERIFIED).
2257        let creds = AwsEnvCredentials {
2258            access_key_id: "AKIDEXAMPLE".to_owned(),
2259            secret_access_key: "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY".to_owned(),
2260            session_token: None,
2261        };
2262        let url = bedrock_url("us-east-1", "anthropic.claude-3-5-haiku");
2263        let body = br#"{"anthropic_version":"bedrock-2023-05-31"}"#;
2264        let signed = sign_bedrock(&url, "us-east-1", body, &creds).unwrap();
2265
2266        let auth_header = signed
2267            .headers()
2268            .get("authorization")
2269            .and_then(|v| v.to_str().ok())
2270            .expect("authorization header present");
2271        assert!(auth_header.starts_with("AWS4-HMAC-SHA256"));
2272
2273        let host_header = signed
2274            .headers()
2275            .get("host")
2276            .and_then(|v| v.to_str().ok())
2277            .expect("host header present");
2278        assert_eq!(host_header, "bedrock-runtime.us-east-1.amazonaws.com");
2279    }
2280
2281    #[test]
2282    fn vertex_url_construction_and_missing_project() {
2283        assert_eq!(
2284            vertex_url("us-central1", "my-project", "claude-3-5-sonnet"),
2285            "https://us-central1-aiplatform.googleapis.com/v1/projects/my-project/locations/us-central1/publishers/anthropic/models/claude-3-5-sonnet:rawPredict"
2286        );
2287    }
2288
2289    #[tokio::test]
2290    async fn vertex_complete_errors_without_a_project() {
2291        let provider = VertexProvider {
2292            id: "vertex".to_owned(),
2293            region: Some("us-central1".to_owned()),
2294            project: None,
2295            http: reqwest::Client::new(),
2296        };
2297        let req = ModelRequest {
2298            model: "vertex/claude-3-5-sonnet".to_owned(),
2299            system: None,
2300            messages: vec![],
2301            max_tokens: 16,
2302            tools: Value::Null,
2303            raw: Value::Null,
2304            cache_prefix: false,
2305        };
2306        let err = provider.complete(&req, &Auth::default()).await.unwrap_err();
2307        assert!(matches!(err, ProviderError::Transport(_)));
2308    }
2309
2310    #[test]
2311    fn from_config_wires_bedrock_and_vertex_auth_schemes() {
2312        let defs = vec![
2313            firstpass_core::ProviderDef {
2314                id: "bedrock".to_owned(),
2315                dialect: firstpass_core::Dialect::Anthropic,
2316                base_url: String::new(),
2317                api_key_env: None,
2318                auth: firstpass_core::AuthScheme::AwsSigv4,
2319                region: Some("us-east-1".to_owned()),
2320                project: None,
2321            },
2322            firstpass_core::ProviderDef {
2323                id: "vertex".to_owned(),
2324                dialect: firstpass_core::Dialect::Anthropic,
2325                base_url: String::new(),
2326                api_key_env: None,
2327                auth: firstpass_core::AuthScheme::GcpOauth,
2328                region: Some("us-central1".to_owned()),
2329                project: Some("my-project".to_owned()),
2330            },
2331        ];
2332        let reg = ProviderRegistry::from_config(
2333            &defs,
2334            "https://api.anthropic.com",
2335            "https://api.openai.com",
2336        );
2337        assert_eq!(reg.get("bedrock").unwrap().id(), "bedrock");
2338        assert_eq!(reg.get("vertex").unwrap().id(), "vertex");
2339    }
2340
2341    #[test]
2342    fn resolve_api_key_prefers_configured_env_then_byok() {
2343        // Use PATH (always present) to exercise the env branch without mutating process env.
2344        let path = std::env::var("PATH").expect("PATH is set");
2345        // Configured env wins over any BYOK override (the env var is *this* provider's key).
2346        assert_eq!(resolve_api_key(Some("PATH"), Some("byok")), path);
2347        // Configured env unset → return "" (never fall through to the client's BYOK override).
2348        // Sending no credential is safer than leaking a key to the wrong host.
2349        assert_eq!(
2350            resolve_api_key(Some("FIRSTPASS_DEFINITELY_UNSET_KEY"), Some("byok")),
2351            ""
2352        );
2353        // No configured env → fall back to BYOK.
2354        assert_eq!(resolve_api_key(None, Some("byok")), "byok");
2355        // Neither → empty (keyless local endpoint).
2356        assert_eq!(resolve_api_key(None, None), "");
2357    }
2358
2359    #[test]
2360    fn anthropic_wire_forwards_tool_and_image_content_verbatim() {
2361        // ADR 0005 I3 (request side): the Anthropic adapter serializes tool_use / tool_result /
2362        // image content blocks byte-for-byte into the wire body — enforce forwards them, it does not
2363        // flatten them. A plain-string message still serializes as a bare string (I1).
2364        let messages = vec![
2365            ChatMessage::text("user", "hi"),
2366            ChatMessage {
2367                role: "assistant".to_owned(),
2368                content: serde_json::json!([
2369                    { "type": "tool_use", "id": "t1", "name": "calc", "input": { "x": 1 } }
2370                ]),
2371            },
2372            ChatMessage {
2373                role: "user".to_owned(),
2374                content: serde_json::json!([
2375                    { "type": "tool_result", "tool_use_id": "t1", "content": "2" },
2376                    { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "AA==" } }
2377                ]),
2378            },
2379        ];
2380        let wire = anthropic_wire_body(&ModelRequest {
2381            model: "anthropic/claude-haiku-4-5".to_owned(),
2382            system: None,
2383            messages,
2384            max_tokens: 64,
2385            tools: Value::Null,
2386            raw: Value::Null,
2387            cache_prefix: false,
2388        });
2389        assert_eq!(wire["messages"][0]["content"], serde_json::json!("hi"));
2390        assert_eq!(
2391            wire["messages"][1]["content"],
2392            serde_json::json!([{ "type": "tool_use", "id": "t1", "name": "calc", "input": { "x": 1 } }])
2393        );
2394        assert_eq!(
2395            wire["messages"][2]["content"],
2396            serde_json::json!([
2397                { "type": "tool_result", "tool_use_id": "t1", "content": "2" },
2398                { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "AA==" } }
2399            ])
2400        );
2401    }
2402
2403    fn resp(model: &str, text: &str) -> ModelResponse {
2404        ModelResponse {
2405            model: model.to_owned(),
2406            text: text.to_owned(),
2407            in_tokens: 10,
2408            cache_write_tokens: 0,
2409            cache_read_tokens: 0,
2410            out_tokens: 5,
2411            raw: Value::Null,
2412        }
2413    }
2414
2415    #[test]
2416    fn transport_and_5xx_are_failover_eligible() {
2417        assert!(ProviderError::Transport("boom".into()).is_failover_eligible());
2418        assert!(
2419            ProviderError::Http {
2420                status: 503,
2421                body: String::new()
2422            }
2423            .is_failover_eligible()
2424        );
2425    }
2426
2427    #[test]
2428    fn client_errors_and_decode_failures_are_hard() {
2429        assert!(
2430            !ProviderError::Http {
2431                status: 400,
2432                body: String::new()
2433            }
2434            .is_failover_eligible()
2435        );
2436        assert!(!ProviderError::Decode("bad json".into()).is_failover_eligible());
2437    }
2438
2439    #[test]
2440    fn auth_debug_never_prints_key_material() {
2441        let auth = Auth {
2442            anthropic_key: Some("sk-ant-super-secret".to_owned()),
2443            openai_key: Some("sk-oai-super-secret".to_owned()),
2444            anthropic_bearer: Some("oauth-super-secret".to_owned()),
2445            anthropic_beta: None,
2446            anthropic_version: None,
2447            gemini_key: None,
2448        };
2449        let debug = format!("{auth:?}");
2450        assert!(!debug.contains("super-secret"));
2451    }
2452
2453    #[tokio::test]
2454    async fn mock_provider_returns_configured_outcome() {
2455        let mut outcomes = HashMap::new();
2456        outcomes.insert(
2457            "anthropic/claude-haiku-4-5".to_owned(),
2458            Ok(resp("anthropic/claude-haiku-4-5", "hello")),
2459        );
2460        let provider = MockProvider::new("anthropic", outcomes);
2461        let req = ModelRequest {
2462            model: "anthropic/claude-haiku-4-5".to_owned(),
2463            system: None,
2464            messages: vec![],
2465            max_tokens: 100,
2466            tools: Value::Null,
2467            raw: Value::Null,
2468            cache_prefix: false,
2469        };
2470        let out = provider.complete(&req, &Auth::default()).await.unwrap();
2471        assert_eq!(out.text, "hello");
2472    }
2473
2474    #[test]
2475    fn anthropic_wire_body_carries_raw_request_verbatim() {
2476        // ADR 0005: with a raw inbound body present, the wire request IS that body — every field
2477        // the caller set (tools, tool_choice, temperature, thinking, ...) survives; only `model`
2478        // is swapped to the rung's wire id and `stream` is stripped (complete() buffers to gate).
2479        let raw = serde_json::json!({
2480            "model": "claude-opus-4-8",
2481            "stream": true,
2482            "max_tokens": 512,
2483            "temperature": 0.2,
2484            "tool_choice": { "type": "auto" },
2485            "tools": [{ "name": "get_weather", "input_schema": { "type": "object" } }],
2486            "thinking": { "type": "enabled", "budget_tokens": 1024 },
2487            "messages": [{ "role": "user", "content": "hi" }]
2488        });
2489        let req = ModelRequest {
2490            model: "anthropic/claude-haiku-4-5".to_owned(),
2491            system: None,
2492            messages: vec![ChatMessage::text("user", "hi")],
2493            max_tokens: 512,
2494            tools: raw["tools"].clone(),
2495            raw: raw.clone(),
2496            cache_prefix: false,
2497        };
2498        let wire = anthropic_wire_body(&req);
2499        assert_eq!(wire["model"], "claude-haiku-4-5", "rung model swapped in");
2500        assert!(wire.get("stream").is_none(), "stream stripped");
2501        for field in [
2502            "temperature",
2503            "tool_choice",
2504            "tools",
2505            "thinking",
2506            "max_tokens",
2507            "messages",
2508        ] {
2509            assert_eq!(
2510                wire[field], raw[field],
2511                "field {field} must survive verbatim"
2512            );
2513        }
2514    }
2515
2516    #[test]
2517    fn bedrock_vertex_body_carries_raw_minus_model_plus_version() {
2518        let raw = serde_json::json!({
2519            "model": "claude-haiku-4-5",
2520            "stream": true,
2521            "max_tokens": 64,
2522            "tools": [{ "name": "t" }],
2523            "messages": [{ "role": "user", "content": "hi" }]
2524        });
2525        let req = ModelRequest {
2526            model: "bedrock/anthropic.claude-haiku".to_owned(),
2527            system: None,
2528            messages: vec![ChatMessage::text("user", "hi")],
2529            max_tokens: 64,
2530            tools: raw["tools"].clone(),
2531            raw: raw.clone(),
2532            cache_prefix: false,
2533        };
2534        let body = anthropic_messages_body(&req, "bedrock-2023-05-31");
2535        assert!(body.get("model").is_none(), "model lives in the URL");
2536        assert!(body.get("stream").is_none());
2537        assert_eq!(body["anthropic_version"], "bedrock-2023-05-31");
2538        assert_eq!(body["tools"], raw["tools"]);
2539        assert_eq!(body["messages"], raw["messages"]);
2540    }
2541
2542    #[test]
2543    fn verbatim_carriers_are_dialect_aware() {
2544        use firstpass_core::Dialect;
2545        let reg = ProviderRegistry::new("http://localhost", "http://localhost");
2546        // Anthropic provider: verbatim for Anthropic inbound, not for OpenAI
2547        assert!(
2548            reg.get("anthropic")
2549                .unwrap()
2550                .carries_structured_verbatim(Dialect::Anthropic)
2551        );
2552        assert!(
2553            !reg.get("anthropic")
2554                .unwrap()
2555                .carries_structured_verbatim(Dialect::Openai)
2556        );
2557        // OpenAI provider: verbatim for OpenAI inbound, not for Anthropic
2558        assert!(
2559            reg.get("openai")
2560                .unwrap()
2561                .carries_structured_verbatim(Dialect::Openai)
2562        );
2563        assert!(
2564            !reg.get("openai")
2565                .unwrap()
2566                .carries_structured_verbatim(Dialect::Anthropic)
2567        );
2568    }
2569
2570    #[test]
2571    fn openai_wire_body_carries_raw_request_verbatim() {
2572        // All-OpenAI-ladder raw carry: same semantics as anthropic_wire_body_carries_raw_request_verbatim.
2573        let raw = serde_json::json!({
2574            "model": "gpt-4o",
2575            "stream": true,
2576            "max_tokens": 256,
2577            "temperature": 0.7,
2578            "response_format": { "type": "json_object" },
2579            "tool_choice": "auto",
2580            "tools": [{ "type": "function", "function": { "name": "get_weather", "parameters": {} } }],
2581            "messages": [{ "role": "user", "content": "hi" }]
2582        });
2583        let req = ModelRequest {
2584            model: "openai/gpt-4.1-mini".to_owned(),
2585            system: None,
2586            messages: vec![ChatMessage::text("user", "hi")],
2587            max_tokens: 256,
2588            tools: Value::Null,
2589            raw: raw.clone(),
2590            cache_prefix: false,
2591        };
2592        let wire = openai_wire_body(&req);
2593        assert_eq!(wire["model"], "gpt-4.1-mini", "rung model swapped in");
2594        assert!(wire.get("stream").is_none(), "stream stripped");
2595        for field in [
2596            "temperature",
2597            "tool_choice",
2598            "tools",
2599            "response_format",
2600            "messages",
2601            "max_tokens",
2602        ] {
2603            assert_eq!(
2604                wire[field], raw[field],
2605                "field {field} must survive verbatim"
2606            );
2607        }
2608    }
2609
2610    #[test]
2611    fn openai_wire_body_falls_back_to_normalized_fields() {
2612        // Translation path (raw = Null): reconstruct from normalized fields.
2613        let req = ModelRequest {
2614            model: "openai/gpt-4.1-mini".to_owned(),
2615            system: Some("be terse".to_owned()),
2616            messages: vec![
2617                ChatMessage::text("user", "hello"),
2618                ChatMessage::text("assistant", "hi"),
2619            ],
2620            max_tokens: 128,
2621            tools: Value::Null,
2622            raw: Value::Null,
2623            cache_prefix: false,
2624        };
2625        let wire = openai_wire_body(&req);
2626        assert_eq!(wire["model"], "gpt-4.1-mini");
2627        // System → injected as first message with role="system"
2628        assert_eq!(wire["messages"][0]["role"], "system");
2629        assert_eq!(wire["messages"][0]["content"], "be terse");
2630        assert_eq!(wire["messages"][1]["role"], "user");
2631        assert_eq!(wire["messages"][2]["role"], "assistant");
2632    }
2633
2634    #[test]
2635    fn gemini_dialect_never_populates_anthropic_or_inbound_openai_credentials() {
2636        use firstpass_core::Dialect;
2637        let mut h = HeaderMap::new();
2638        h.insert("x-goog-api-key", "goog-key".parse().unwrap());
2639        h.insert("x-api-key", "stray-anthropic-key".parse().unwrap());
2640        h.insert(
2641            axum::http::header::AUTHORIZATION,
2642            "Bearer stray-bearer".parse().unwrap(),
2643        );
2644        let auth = Auth::from_headers(&h, Dialect::Gemini);
2645        assert_eq!(auth.gemini_key.as_deref(), Some("goog-key"));
2646        assert!(
2647            auth.anthropic_key.is_none(),
2648            "x-api-key must not cross to Anthropic"
2649        );
2650        assert!(auth.anthropic_bearer.is_none());
2651        assert_ne!(auth.openai_key.as_deref(), Some("stray-bearer"));
2652    }
2653
2654    #[test]
2655    fn auth_from_headers_captures_beta_and_version() {
2656        use firstpass_core::Dialect;
2657        let mut h = HeaderMap::new();
2658        h.insert("x-api-key", "sk-ant-key".parse().unwrap());
2659        h.insert(
2660            "anthropic-beta",
2661            "interleaved-thinking-2025-05-14".parse().unwrap(),
2662        );
2663        h.insert("anthropic-version", "2024-01-01".parse().unwrap());
2664        let auth = Auth::from_headers(&h, Dialect::Anthropic);
2665        assert_eq!(auth.anthropic_key.as_deref(), Some("sk-ant-key"));
2666        assert_eq!(
2667            auth.anthropic_beta.as_deref(),
2668            Some("interleaved-thinking-2025-05-14")
2669        );
2670        assert_eq!(auth.anthropic_version.as_deref(), Some("2024-01-01"));
2671        assert!(auth.openai_key.is_none());
2672        assert!(auth.anthropic_bearer.is_none());
2673    }
2674
2675    #[test]
2676    fn auth_from_headers_anthropic_dialect_bearer_goes_to_anthropic_bearer_not_openai_key() {
2677        // A Claude account subscription client: Bearer arrives on /v1/messages (Anthropic dialect).
2678        // It must populate `anthropic_bearer` only — never `openai_key`.
2679        use firstpass_core::Dialect;
2680        let mut h = HeaderMap::new();
2681        h.insert(
2682            axum::http::header::AUTHORIZATION,
2683            "Bearer claude-oauth-token".parse().unwrap(),
2684        );
2685        let auth = Auth::from_headers(&h, Dialect::Anthropic);
2686        assert!(auth.anthropic_key.is_none(), "no x-api-key header");
2687        assert!(
2688            auth.openai_key.is_none(),
2689            "Bearer on Anthropic path must NOT populate openai_key"
2690        );
2691        assert_eq!(
2692            auth.anthropic_bearer.as_deref(),
2693            Some("claude-oauth-token"),
2694            "Bearer on Anthropic path goes to anthropic_bearer"
2695        );
2696    }
2697
2698    #[test]
2699    fn auth_from_headers_openai_dialect_bearer_goes_to_openai_key_not_anthropic_bearer() {
2700        // An OpenAI client: Bearer arrives on /v1/chat/completions (OpenAI dialect).
2701        // It must populate `openai_key` only — never `anthropic_bearer`.
2702        use firstpass_core::Dialect;
2703        let mut h = HeaderMap::new();
2704        h.insert(
2705            axum::http::header::AUTHORIZATION,
2706            "Bearer sk-openai-key".parse().unwrap(),
2707        );
2708        let auth = Auth::from_headers(&h, Dialect::Openai);
2709        assert!(auth.anthropic_key.is_none());
2710        assert!(
2711            auth.anthropic_bearer.is_none(),
2712            "Bearer on OpenAI path must NOT populate anthropic_bearer"
2713        );
2714        assert_eq!(
2715            auth.openai_key.as_deref(),
2716            Some("sk-openai-key"),
2717            "Bearer on OpenAI path goes to openai_key"
2718        );
2719    }
2720
2721    /// Verifies that `AnthropicProvider` sends `anthropic-beta`, uses the inbound
2722    /// `anthropic-version`, and falls back to `Authorization: Bearer` when no `x-api-key` is
2723    /// present — all three changes required for OAuth/subscription clients (e.g. Claude Code).
2724    #[tokio::test]
2725    async fn anthropic_provider_forwards_beta_version_and_bearer_fallback() {
2726        use std::sync::{Arc, Mutex};
2727        // Spin up a local axum server that records the incoming request headers.
2728        let captured: Arc<Mutex<Option<HeaderMap>>> = Arc::new(Mutex::new(None));
2729        let captured_clone = Arc::clone(&captured);
2730        let app = axum::Router::new().route(
2731            "/v1/messages",
2732            axum::routing::post(move |headers: HeaderMap| {
2733                *captured_clone.lock().unwrap() = Some(headers);
2734                async {
2735                    axum::Json(serde_json::json!({
2736                        "id": "msg_test", "type": "message", "role": "assistant",
2737                        "content": [{"type": "text", "text": "ok"}],
2738                        "stop_reason": "end_turn",
2739                        "usage": {"input_tokens": 1, "output_tokens": 1}
2740                    }))
2741                }
2742            }),
2743        );
2744        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
2745        let addr = listener.local_addr().unwrap();
2746        tokio::spawn(async move {
2747            let _ = axum::serve(listener, app).await;
2748        });
2749
2750        let provider = AnthropicProvider {
2751            id: "anthropic".to_owned(),
2752            base_url: format!("http://{addr}"),
2753            api_key_env: None,
2754            http: reqwest::Client::new(),
2755        };
2756        let req = ModelRequest {
2757            model: "anthropic/claude-haiku-4-5".to_owned(),
2758            system: None,
2759            messages: vec![ChatMessage::text("user", "hi")],
2760            max_tokens: 16,
2761            tools: Value::Null,
2762            raw: serde_json::json!({"messages": [{"role":"user","content":"hi"}], "max_tokens": 16}),
2763            cache_prefix: false,
2764        };
2765        let auth = Auth {
2766            anthropic_key: None, // no API key — use Bearer fallback
2767            openai_key: None,    // OpenAI key must NOT be forwarded to Anthropic
2768            anthropic_bearer: Some("oauth-bearer-token".to_owned()),
2769            anthropic_beta: Some("interleaved-thinking-2025-05-14".to_owned()),
2770            anthropic_version: Some("2024-01-01".to_owned()),
2771            gemini_key: None,
2772        };
2773        provider.complete(&req, &auth).await.expect("must succeed");
2774
2775        let hdrs = captured.lock().unwrap().take().expect("headers captured");
2776        assert!(
2777            hdrs.get("x-api-key").is_none(),
2778            "x-api-key must be absent when no API key is configured"
2779        );
2780        assert_eq!(
2781            hdrs.get(axum::http::header::AUTHORIZATION)
2782                .and_then(|v| v.to_str().ok()),
2783            Some("Bearer oauth-bearer-token"),
2784            "OAuth Bearer from anthropic_bearer must be forwarded when x-api-key is absent"
2785        );
2786        assert_eq!(
2787            hdrs.get("anthropic-version").and_then(|v| v.to_str().ok()),
2788            Some("2024-01-01"),
2789            "inbound anthropic-version must override the default"
2790        );
2791        assert_eq!(
2792            hdrs.get("anthropic-beta").and_then(|v| v.to_str().ok()),
2793            Some("interleaved-thinking-2025-05-14"),
2794            "anthropic-beta must be forwarded verbatim"
2795        );
2796    }
2797
2798    #[test]
2799    fn response_has_tool_calls_anthropic_format() {
2800        let with_tool = ModelResponse {
2801            model: "m".to_owned(),
2802            text: String::new(),
2803            in_tokens: 0,
2804            cache_write_tokens: 0,
2805            cache_read_tokens: 0,
2806            out_tokens: 0,
2807            raw: serde_json::json!({
2808                "content": [{"type": "tool_use", "id": "t1", "name": "f", "input": {}}]
2809            }),
2810        };
2811        assert!(with_tool.has_tool_calls());
2812
2813        let text_only = ModelResponse {
2814            raw: serde_json::json!({"content": [{"type": "text", "text": "hi"}]}),
2815            ..with_tool.clone()
2816        };
2817        assert!(!text_only.has_tool_calls());
2818
2819        let no_content = ModelResponse {
2820            raw: serde_json::Value::Null,
2821            ..with_tool.clone()
2822        };
2823        assert!(!no_content.has_tool_calls());
2824    }
2825
2826    #[test]
2827    fn response_has_tool_calls_openai_format() {
2828        let with_tc = ModelResponse {
2829            model: "m".to_owned(),
2830            text: String::new(),
2831            in_tokens: 0,
2832            cache_write_tokens: 0,
2833            cache_read_tokens: 0,
2834            out_tokens: 0,
2835            raw: serde_json::json!({
2836                "choices": [{"message": {"role": "assistant",
2837                    "tool_calls": [{"id": "c1", "type": "function",
2838                        "function": {"name": "f", "arguments": "{}"}}]
2839                }}]
2840            }),
2841        };
2842        assert!(with_tc.has_tool_calls());
2843
2844        let no_tc = ModelResponse {
2845            raw: serde_json::json!({"choices": [{"message": {"content": "hi"}}]}),
2846            ..with_tc.clone()
2847        };
2848        assert!(!no_tc.has_tool_calls());
2849    }
2850
2851    /// SECURITY: OPENAI_API_KEY must never be forwarded to the Anthropic endpoint.
2852    /// When `anthropic_key` is absent but `openai_key` is set (e.g. from the env fallback on
2853    /// a server that has OPENAI_API_KEY set), the Anthropic provider must send NO auth header
2854    /// rather than leaking the OpenAI key.
2855    #[tokio::test]
2856    async fn anthropic_provider_does_not_forward_openai_key_to_anthropic_endpoint() {
2857        use std::sync::{Arc, Mutex};
2858        let captured: Arc<Mutex<Option<HeaderMap>>> = Arc::new(Mutex::new(None));
2859        let captured_clone = Arc::clone(&captured);
2860        let app = axum::Router::new().route(
2861            "/v1/messages",
2862            axum::routing::post(move |headers: HeaderMap| {
2863                *captured_clone.lock().unwrap() = Some(headers);
2864                async {
2865                    axum::Json(serde_json::json!({
2866                        "id": "msg_test", "type": "message", "role": "assistant",
2867                        "content": [{"type": "text", "text": "ok"}],
2868                        "stop_reason": "end_turn",
2869                        "usage": {"input_tokens": 1, "output_tokens": 1}
2870                    }))
2871                }
2872            }),
2873        );
2874        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
2875        let addr = listener.local_addr().unwrap();
2876        tokio::spawn(async move {
2877            let _ = axum::serve(listener, app).await;
2878        });
2879
2880        let provider = AnthropicProvider {
2881            id: "anthropic".to_owned(),
2882            base_url: format!("http://{addr}"),
2883            api_key_env: None,
2884            http: reqwest::Client::new(),
2885        };
2886        let req = ModelRequest {
2887            model: "anthropic/claude-haiku-4-5".to_owned(),
2888            system: None,
2889            messages: vec![ChatMessage::text("user", "hi")],
2890            max_tokens: 16,
2891            tools: Value::Null,
2892            raw: serde_json::json!({"messages": [{"role":"user","content":"hi"}], "max_tokens": 16}),
2893            cache_prefix: false,
2894        };
2895
2896        // Auth with an openai_key set (e.g., from OPENAI_API_KEY env) but no anthropic creds.
2897        let auth = Auth {
2898            anthropic_key: None,
2899            openai_key: Some("sk-openai-from-env".to_owned()),
2900            anthropic_bearer: None,
2901            anthropic_beta: None,
2902            anthropic_version: None,
2903            gemini_key: None,
2904        };
2905        provider.complete(&req, &auth).await.expect("must succeed");
2906
2907        let hdrs = captured.lock().unwrap().take().expect("headers captured");
2908        assert!(hdrs.get("x-api-key").is_none(), "x-api-key must be absent");
2909        assert!(
2910            hdrs.get(axum::http::header::AUTHORIZATION).is_none(),
2911            "SECURITY: openai_key must NOT be forwarded to the Anthropic endpoint"
2912        );
2913    }
2914
2915    /// A rung with its own configured key (e.g. a custom Anthropic-compatible host) sends that
2916    /// key, and neither the client's `x-api-key` nor its OAuth Bearer reaches that host.
2917    /// `api_key_env = "PATH"` stands in for a configured key without `unsafe env::set_var`.
2918    #[tokio::test]
2919    async fn anthropic_provider_sends_the_configured_key_not_the_clients_credentials() {
2920        use std::sync::{Arc, Mutex};
2921        let captured: Arc<Mutex<Option<HeaderMap>>> = Arc::new(Mutex::new(None));
2922        let captured_clone = Arc::clone(&captured);
2923        let app = axum::Router::new().route(
2924            "/v1/messages",
2925            axum::routing::post(move |headers: HeaderMap| {
2926                *captured_clone.lock().unwrap() = Some(headers);
2927                async {
2928                    axum::Json(serde_json::json!({
2929                        "id": "msg_test", "type": "message", "role": "assistant",
2930                        "content": [{"type": "text", "text": "ok"}],
2931                        "stop_reason": "end_turn",
2932                        "usage": {"input_tokens": 1, "output_tokens": 1}
2933                    }))
2934                }
2935            }),
2936        );
2937        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
2938        let addr = listener.local_addr().unwrap();
2939        tokio::spawn(async move {
2940            let _ = axum::serve(listener, app).await;
2941        });
2942
2943        let provider = AnthropicProvider {
2944            id: "anthropic".to_owned(),
2945            base_url: format!("http://{addr}"),
2946            // "PATH" is always set; its value is used as the api key — doesn't matter
2947            // for this test, we only care that x-api-key does NOT appear in the request.
2948            api_key_env: Some("PATH".to_owned()),
2949            http: reqwest::Client::new(),
2950        };
2951        let req = ModelRequest {
2952            model: "anthropic/claude-haiku-4-5".to_owned(),
2953            system: None,
2954            messages: vec![ChatMessage::text("user", "hi")],
2955            max_tokens: 16,
2956            tools: Value::Null,
2957            raw: serde_json::json!({"messages":[{"role":"user","content":"hi"}],"max_tokens":16}),
2958            cache_prefix: false,
2959        };
2960        // Client sends Bearer only — no x-api-key.  Bearer must win over the server env key.
2961        let auth = Auth {
2962            anthropic_key: Some("client-anthropic-key".to_owned()),
2963            openai_key: None,
2964            anthropic_bearer: Some("client-oauth-token".to_owned()),
2965            anthropic_beta: None,
2966            anthropic_version: None,
2967            gemini_key: None,
2968        };
2969        provider.complete(&req, &auth).await.expect("must succeed");
2970
2971        let hdrs = captured.lock().unwrap().take().expect("headers captured");
2972        let path = std::env::var("PATH").unwrap_or_default();
2973        assert_eq!(
2974            hdrs.get("x-api-key").and_then(|v| v.to_str().ok()),
2975            Some(path.as_str()),
2976            "the rung's configured key must be sent"
2977        );
2978        assert!(
2979            hdrs.get(axum::http::header::AUTHORIZATION).is_none(),
2980            "a client's OAuth token must not reach a host with its own configured key"
2981        );
2982    }
2983
2984    /// The credential order: configured > request key > request Bearer > ambient.
2985    ///
2986    /// Key security invariant: when `api_key_env` is configured (outer `Some`) but the env var is
2987    /// unset (`Some(None)`), the function returns `None` — it never falls through to client creds.
2988    #[test]
2989    fn anthropic_credential_order() {
2990        let auth = |key: Option<&str>, bearer: Option<&str>| Auth {
2991            anthropic_key: key.map(str::to_owned),
2992            openai_key: Some("openai".to_owned()),
2993            anthropic_bearer: bearer.map(str::to_owned),
2994            anthropic_beta: None,
2995            anthropic_version: None,
2996            gemini_key: None,
2997        };
2998        // configured = Option<Option<String>>
2999        //   None           → api_key_env not set → use client creds + ambient
3000        //   Some(None)     → api_key_env set but env var unset → send nothing
3001        //   Some(Some(k))  → api_key_env set and resolved → use k
3002        let cfg = |v: &str| Some(Some(v.to_owned())); // Some(Some(k))
3003        let no_env: Option<Option<String>> = Some(None); // configured, env var unset
3004        let s = |v: &str| Some(v.to_owned()); // ambient / auth helper
3005        use AnthropicCredential::{ApiKey, Bearer};
3006
3007        // Not configured, bearer present — bearer wins over ambient.
3008        assert_eq!(
3009            anthropic_credential(None, &auth(None, Some("oauth")), s("ambient")),
3010            Some(Bearer("oauth".to_owned()))
3011        );
3012        // Not configured, api-key + bearer — api-key wins.
3013        assert_eq!(
3014            anthropic_credential(None, &auth(Some("k"), Some("oauth")), s("ambient")),
3015            Some(ApiKey("k".to_owned()))
3016        );
3017        // Configured key wins over every client credential and ambient.
3018        assert_eq!(
3019            anthropic_credential(cfg("cfgkey"), &auth(Some("k"), Some("oauth")), s("ambient")),
3020            Some(ApiKey("cfgkey".to_owned()))
3021        );
3022        // Not configured, no client creds — ambient fallback.
3023        assert_eq!(
3024            anthropic_credential(None, &auth(None, None), s("ambient")),
3025            Some(ApiKey("ambient".to_owned()))
3026        );
3027        // Configured but env var unset → None (never leak client creds to the wrong host).
3028        assert_eq!(
3029            anthropic_credential(no_env, &auth(Some("k"), Some("oauth")), s("ambient")),
3030            None,
3031            "configured-but-unset must not fall through to client credentials"
3032        );
3033        // Configured but resolved to empty string → also None.
3034        assert_eq!(
3035            anthropic_credential(cfg(""), &auth(Some("k"), None), None),
3036            None,
3037            "empty configured value must not fall through to client key"
3038        );
3039        // OpenAI key is never used (different provider).
3040        assert_eq!(
3041            anthropic_credential(None, &auth(None, None), None),
3042            None,
3043            "the OpenAI key is never used for Anthropic requests"
3044        );
3045    }
3046
3047    /// When a request x-api-key is present it must be used even when a Bearer is also present.
3048    #[tokio::test]
3049    async fn anthropic_provider_prefers_x_api_key_over_bearer() {
3050        use std::sync::{Arc, Mutex};
3051        let captured: Arc<Mutex<Option<HeaderMap>>> = Arc::new(Mutex::new(None));
3052        let captured_clone = Arc::clone(&captured);
3053        let app = axum::Router::new().route(
3054            "/v1/messages",
3055            axum::routing::post(move |headers: HeaderMap| {
3056                *captured_clone.lock().unwrap() = Some(headers);
3057                async {
3058                    axum::Json(serde_json::json!({
3059                        "id": "msg_t", "type": "message", "role": "assistant",
3060                        "content": [{"type": "text", "text": "ok"}],
3061                        "stop_reason": "end_turn",
3062                        "usage": {"input_tokens": 1, "output_tokens": 1}
3063                    }))
3064                }
3065            }),
3066        );
3067        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
3068        let addr = listener.local_addr().unwrap();
3069        tokio::spawn(async move {
3070            let _ = axum::serve(listener, app).await;
3071        });
3072
3073        let provider = AnthropicProvider {
3074            id: "anthropic".to_owned(),
3075            base_url: format!("http://{addr}"),
3076            api_key_env: None,
3077            http: reqwest::Client::new(),
3078        };
3079        let req = ModelRequest {
3080            model: "anthropic/claude-haiku-4-5".to_owned(),
3081            system: None,
3082            messages: vec![ChatMessage::text("user", "hi")],
3083            max_tokens: 16,
3084            tools: Value::Null,
3085            raw: serde_json::json!({"messages":[{"role":"user","content":"hi"}],"max_tokens":16}),
3086            cache_prefix: false,
3087        };
3088        // Both x-api-key and Bearer present: x-api-key must win.
3089        let auth = Auth {
3090            anthropic_key: Some("sk-real-api-key".to_owned()),
3091            openai_key: None,
3092            anthropic_bearer: Some("oauth-bearer-ignored".to_owned()),
3093            anthropic_beta: None,
3094            anthropic_version: None,
3095            gemini_key: None,
3096        };
3097        provider.complete(&req, &auth).await.expect("must succeed");
3098
3099        let hdrs = captured.lock().unwrap().take().expect("headers captured");
3100        assert_eq!(
3101            hdrs.get("x-api-key").and_then(|v| v.to_str().ok()),
3102            Some("sk-real-api-key"),
3103            "x-api-key must be sent when present"
3104        );
3105        assert!(
3106            hdrs.get(axum::http::header::AUTHORIZATION).is_none(),
3107            "Bearer must not be sent when x-api-key is present"
3108        );
3109    }
3110
3111    #[test]
3112    fn blank_anthropic_version_header_is_absent() {
3113        let mut h = HeaderMap::new();
3114        h.insert(
3115            "anthropic-version",
3116            "  ".parse().unwrap_or_else(|_| unreachable!()),
3117        );
3118        assert_eq!(
3119            Auth::from_headers(&h, firstpass_core::Dialect::Anthropic).anthropic_version,
3120            None
3121        );
3122    }
3123
3124    #[test]
3125    fn auth_from_headers_multiple_anthropic_beta_values_are_joined() {
3126        use firstpass_core::Dialect;
3127        let mut h = HeaderMap::new();
3128        h.append(
3129            "anthropic-beta",
3130            "extended-thinking-2025-02-19".parse().unwrap(),
3131        );
3132        h.append(
3133            "anthropic-beta",
3134            "interleaved-thinking-2025-05-14".parse().unwrap(),
3135        );
3136        let auth = Auth::from_headers(&h, Dialect::Anthropic);
3137        // Both values must appear joined — order preserved, separated by ", ".
3138        let beta = auth.anthropic_beta.expect("anthropic_beta must be Some");
3139        assert!(
3140            beta.contains("extended-thinking-2025-02-19"),
3141            "first beta value missing: {beta}"
3142        );
3143        assert!(
3144            beta.contains("interleaved-thinking-2025-05-14"),
3145            "second beta value missing: {beta}"
3146        );
3147        assert!(
3148            beta.contains(", "),
3149            "values must be comma-separated: {beta}"
3150        );
3151    }
3152}