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 serde::{Deserialize, Serialize};
13use serde_json::Value;
14
15/// One message in a normalized chat conversation. `content` is either a plain string (the common
16/// case — serializes byte-identically to a text message) OR the original array of content blocks
17/// (`text` / `tool_use` / `tool_result` / `image`), forwarded verbatim so tool and multimodal turns
18/// survive the enforce path (ADR 0005). Use [`ChatMessage::text_view`] to read a text projection for
19/// gating.
20#[derive(Debug, Clone, Serialize, Deserialize)]
21pub struct ChatMessage {
22    /// `"user"`, `"assistant"`, or `"system"`.
23    pub role: String,
24    /// Message content — a string, or an array of content blocks, forwarded as-is to the provider.
25    pub content: Value,
26}
27
28impl ChatMessage {
29    /// A text-only message (the common path).
30    #[must_use]
31    pub fn text(role: impl Into<String>, content: impl Into<String>) -> Self {
32        Self {
33            role: role.into(),
34            content: Value::String(content.into()),
35        }
36    }
37
38    /// Concatenate the text this message carries, for gating. A string is itself; an array yields the
39    /// joined `text` blocks (tool_use/tool_result/image blocks contribute no gating text).
40    #[must_use]
41    pub fn text_view(&self) -> String {
42        match &self.content {
43            Value::String(s) => s.clone(),
44            Value::Array(blocks) => blocks
45                .iter()
46                .filter_map(|b| b.get("text").and_then(Value::as_str))
47                .collect::<Vec<_>>()
48                .join("\n"),
49            _ => String::new(),
50        }
51    }
52}
53
54/// A provider-agnostic model request, built once per incoming call and re-used (with
55/// `model` swapped) across every rung of the ladder.
56///
57// Message content is carried verbatim (string or content-block array, ADR 0005); gates read a text
58// projection via `ChatMessage::text_view`. `tools` is opaque passthrough.
59#[derive(Debug, Clone, Serialize, Deserialize)]
60pub struct ModelRequest {
61    /// `provider/model`, e.g. `"anthropic/claude-haiku-4-5"`.
62    pub model: String,
63    /// System prompt, if any.
64    #[serde(default, skip_serializing_if = "Option::is_none")]
65    pub system: Option<String>,
66    /// Conversation turns.
67    pub messages: Vec<ChatMessage>,
68    /// Max tokens to generate.
69    pub max_tokens: u32,
70    /// Opaque tool/function-calling passthrough, forwarded as-is to the wire provider.
71    #[serde(default)]
72    pub tools: Value,
73    /// The **full original inbound request JSON**, when this request came off the proxy's wire
74    /// (ADR 0005). Anthropic-dialect providers send it verbatim with only `model` swapped (and
75    /// `stream` stripped), so every field — `tools`, `tool_choice`, `temperature`, `thinking`,
76    /// `stop_sequences`, … — survives the rung exactly as the caller wrote it. `Null` for
77    /// synthesized requests (judge / consistency samples), which use the normalized fields.
78    #[serde(default, skip_serializing_if = "Value::is_null")]
79    pub raw: Value,
80    /// Whether to insert prompt-cache breakpoints on the stable prefix — see
81    /// [`add_cache_breakpoints`]. Set from `[escalation] prompt_cache`; `false` everywhere else,
82    /// including synthesized judge/consistency requests, so nothing changes unless asked.
83    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
84    pub cache_prefix: bool,
85}
86
87/// A provider-agnostic model response.
88#[derive(Debug, Clone, Serialize, Deserialize)]
89pub struct ModelResponse {
90    /// `provider/model` that produced this response.
91    pub model: String,
92    /// Concatenated text output.
93    pub text: String,
94    /// Input tokens billed, **uncached only** — see `cache_write_tokens` for the rest.
95    pub in_tokens: u64,
96    /// Prompt tokens written to the provider's cache (billed at a premium). 0 when the caller did
97    /// not use prompt caching, or the provider does not report it.
98    pub cache_write_tokens: u64,
99    /// Prompt tokens served from the provider's cache (billed at a discount).
100    pub cache_read_tokens: u64,
101    /// Output tokens billed.
102    pub out_tokens: u64,
103    /// The raw wire response, kept for debugging/audit — never logged wholesale.
104    pub raw: Value,
105}
106
107/// Failure modes of a provider call.
108#[derive(Debug, Clone, thiserror::Error)]
109pub enum ProviderError {
110    /// The request never got a response (connection failure, timeout).
111    #[error("transport error: {0}")]
112    Transport(String),
113    /// The provider responded with a non-2xx status.
114    #[error("http {status}: {body}")]
115    Http {
116        /// HTTP status code.
117        status: u16,
118        /// Response body (truncated upstream, not by us).
119        body: String,
120    },
121    /// The response body didn't parse into the shape we expected.
122    #[error("decode error: {0}")]
123    Decode(String),
124}
125
126impl ProviderError {
127    /// Whether this failure should trigger cross-rung/cross-provider failover (transport
128    /// errors and 5xx) rather than being treated as a hard, non-retryable error (4xx, decode).
129    #[must_use]
130    pub fn is_failover_eligible(&self) -> bool {
131        match self {
132            ProviderError::Transport(_) => true,
133            ProviderError::Http { status, .. } => *status >= 500,
134            ProviderError::Decode(_) => false,
135        }
136    }
137}
138
139/// BYOK credentials for one request, extracted from headers with env-var fallback.
140///
141/// Never logged or persisted — [`std::fmt::Debug`] redacts both fields.
142#[derive(Clone, Default)]
143pub struct Auth {
144    /// Anthropic API key (`x-api-key` header, or `ANTHROPIC_API_KEY`).
145    pub anthropic_key: Option<String>,
146    /// OpenAI API key (`authorization: Bearer ...` header, or `OPENAI_API_KEY`).
147    pub openai_key: Option<String>,
148}
149
150impl std::fmt::Debug for Auth {
151    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
152        f.debug_struct("Auth")
153            .field("anthropic_key", &self.anthropic_key.as_ref().map(|_| "***"))
154            .field("openai_key", &self.openai_key.as_ref().map(|_| "***"))
155            .finish()
156    }
157}
158
159impl Auth {
160    /// Extract BYOK credentials from request headers, falling back to `ANTHROPIC_API_KEY` /
161    /// `OPENAI_API_KEY` environment variables.
162    #[must_use]
163    pub fn from_headers(headers: &HeaderMap) -> Self {
164        let anthropic_key = headers
165            .get("x-api-key")
166            .and_then(|v| v.to_str().ok())
167            .map(str::to_owned)
168            .or_else(|| std::env::var("ANTHROPIC_API_KEY").ok());
169        let openai_key = headers
170            .get(axum::http::header::AUTHORIZATION)
171            .and_then(|v| v.to_str().ok())
172            .and_then(|v| v.strip_prefix("Bearer "))
173            .map(str::to_owned)
174            .or_else(|| std::env::var("OPENAI_API_KEY").ok());
175        Self {
176            anthropic_key,
177            openai_key,
178        }
179    }
180}
181
182/// A normalized model backend. Implementations translate [`ModelRequest`]/[`ModelResponse`]
183/// to/from one wire API.
184#[async_trait]
185pub trait Provider: Send + Sync + std::fmt::Debug {
186    /// Call the model and normalize the result.
187    ///
188    /// # Errors
189    /// Returns [`ProviderError`] on transport failure, a non-2xx response, or a response
190    /// that doesn't decode into the expected shape.
191    async fn complete(
192        &self,
193        req: &ModelRequest,
194        auth: &Auth,
195    ) -> Result<ModelResponse, ProviderError>;
196
197    /// Provider identity, e.g. `"anthropic"`.
198    fn id(&self) -> &str;
199
200    /// Whether this provider carries structured content (tool_use / tool_result / image blocks
201    /// and top-level `tools`) **verbatim** on the wire for the given *inbound* dialect.
202    ///
203    /// - Anthropic-dialect providers (Anthropic / Bedrock / Vertex) return `true` iff
204    ///   `inbound == Dialect::Anthropic`: the raw inbound body is forwarded with only the model
205    ///   swapped, so every caller field — `tools`, `tool_choice`, `thinking`, … — survives
206    ///   intact (ADR 0005 P4).
207    /// - `OpenAiProvider` returns `true` iff `inbound == Dialect::Openai`: same verbatim-carry
208    ///   rule for all-OpenAI-dialect ladders.
209    /// - All other providers (Gemini, unknown) return `false` — no verbatim-carry built yet.
210    ///
211    /// The enforce path's fidelity guard uses this to decide: verbatim-carry path (all rungs
212    /// return `true` for the inbound dialect), translation path (OpenAI → Anthropic when
213    /// content is translatable), or transparent observe passthrough (safe fallback).
214    fn carries_structured_verbatim(&self, _inbound: firstpass_core::Dialect) -> bool {
215        false
216    }
217}
218
219/// Strip the `provider/` prefix from a ladder model id for the provider's wire API — Anthropic and
220/// OpenAI expect the bare model (`claude-haiku-4-5`), not `anthropic/claude-haiku-4-5`. The full
221/// prefixed id is still what the ladder/trace use; only the wire call is stripped.
222fn wire_model(model: &str) -> &str {
223    model.split_once('/').map_or(model, |(_, m)| m)
224}
225
226/// Resolve the API key for a provider call. A configured `api_key_env` wins (that env var is *this*
227/// provider's key — e.g. `GROQ_API_KEY` for a Groq rung); otherwise fall back to the per-request
228/// BYOK override from headers/env (the built-in `anthropic`/`openai` path). Empty string when
229/// neither is set (a keyless local endpoint).
230fn resolve_api_key(api_key_env: Option<&str>, byok_override: Option<&str>) -> String {
231    api_key_env
232        .and_then(|e| std::env::var(e).ok())
233        .or_else(|| byok_override.map(str::to_owned))
234        .unwrap_or_default()
235}
236
237/// Build the Anthropic Messages wire body for `req`: the original inbound JSON **verbatim** with
238/// only `model` swapped to the rung's wire id and `stream` stripped (`complete` is the buffered
239/// call — the gate needs the whole candidate). Falls back to the normalized fields when there is
240/// no raw body (synthesized judge/consistency requests). Pure, so fidelity is unit-testable.
241#[must_use]
242pub fn anthropic_wire_body(req: &ModelRequest) -> Value {
243    if let Value::Object(raw) = &req.raw {
244        let mut body = raw.clone();
245        body.insert(
246            "model".to_owned(),
247            Value::String(wire_model(&req.model).to_owned()),
248        );
249        body.remove("stream");
250        normalize_reasoning(&mut body, Wire::Anthropic);
251        if req.cache_prefix {
252            add_cache_breakpoints(&mut body);
253        }
254        return Value::Object(body);
255    }
256    let messages: Vec<Value> = req
257        .messages
258        .iter()
259        .map(|m| serde_json::json!({ "role": m.role, "content": m.content }))
260        .collect();
261    let mut body = serde_json::json!({
262        "model": wire_model(&req.model),
263        "max_tokens": req.max_tokens,
264        "messages": messages,
265    });
266    if let Some(system) = req.system.as_deref() {
267        body["system"] = serde_json::json!(system);
268    }
269    if !req.tools.is_null() {
270        body["tools"] = req.tools.clone();
271    }
272    // This branch is not a rare fallback: it is the path every translated request takes, and
273    // every CONDENSED one — condensing clears `raw` precisely so the smaller message list is what
274    // gets sent. Applying breakpoints only in the raw branch above would mean `prompt_cache`
275    // silently did nothing for exactly the long conversations it exists to pay for.
276    if req.cache_prefix
277        && let Some(map) = body.as_object_mut()
278    {
279        add_cache_breakpoints(map);
280    }
281    body
282}
283
284/// Speaks `POST {base}/v1/messages` (Anthropic Messages API).
285///
286// LIVE-VERIFIED (2026-07-10): exercised against real Anthropic through the running proxy's enforce
287// path — a haiku completion served end-to-end. The `anthropic/` prefix must be stripped for the
288// wire call (see `wire_model`); sending it verbatim 404s.
289#[derive(Debug, Clone)]
290pub struct AnthropicProvider {
291    /// Ladder prefix / trace label for this provider (usually `"anthropic"`).
292    pub id: String,
293    /// Base URL, e.g. `https://api.anthropic.com`.
294    pub base_url: String,
295    /// Env var the API key is read from when no per-request BYOK header is present. `None` for the
296    /// built-in provider, which resolves the key via [`Auth`] (`x-api-key` header or env).
297    pub api_key_env: Option<String>,
298    /// Shared, connection-pooled HTTP client.
299    pub http: reqwest::Client,
300}
301
302#[async_trait]
303impl Provider for AnthropicProvider {
304    fn id(&self) -> &str {
305        &self.id
306    }
307
308    fn carries_structured_verbatim(&self, inbound: firstpass_core::Dialect) -> bool {
309        inbound == firstpass_core::Dialect::Anthropic
310    }
311
312    async fn complete(
313        &self,
314        req: &ModelRequest,
315        auth: &Auth,
316    ) -> Result<ModelResponse, ProviderError> {
317        let key = resolve_api_key(self.api_key_env.as_deref(), auth.anthropic_key.as_deref());
318        let body = anthropic_wire_body(req);
319
320        let url = format!("{}/v1/messages", self.base_url.trim_end_matches('/'));
321        let resp = self
322            .http
323            .post(url)
324            .header("x-api-key", key)
325            .header("anthropic-version", "2023-06-01")
326            .json(&body)
327            .send()
328            .await
329            .map_err(|e| ProviderError::Transport(e.to_string()))?;
330
331        let status = resp.status();
332        let bytes = resp
333            .bytes()
334            .await
335            .map_err(|e| ProviderError::Transport(e.to_string()))?;
336
337        if !status.is_success() {
338            return Err(ProviderError::Http {
339                status: status.as_u16(),
340                body: String::from_utf8_lossy(&bytes).into_owned(),
341            });
342        }
343
344        let json: Value =
345            serde_json::from_slice(&bytes).map_err(|e| ProviderError::Decode(e.to_string()))?;
346        let u = anthropic_parse_response(&json)?;
347        let (text, in_tokens, out_tokens) = (u.text, u.in_tokens, u.out_tokens);
348        let (cache_write_tokens, cache_read_tokens) = (u.cache_write_tokens, u.cache_read_tokens);
349
350        Ok(ModelResponse {
351            cache_write_tokens,
352            cache_read_tokens,
353            model: req.model.clone(),
354            text,
355            in_tokens,
356            out_tokens,
357            raw: json,
358        })
359    }
360}
361
362/// Extract `(text, in_tokens, out_tokens)` from an Anthropic Messages API response. Shared by
363/// [`AnthropicProvider`] and every auth scheme that wraps the Anthropic body shape (Bedrock,
364/// Vertex — ADR 0006): they all get the same response back, only the request's auth/URL differ.
365fn anthropic_parse_response(json: &Value) -> Result<AnthropicUsage, ProviderError> {
366    let text = json
367        .get("content")
368        .and_then(Value::as_array)
369        .map(|blocks| {
370            blocks
371                .iter()
372                .filter_map(|b| b.get("text").and_then(Value::as_str))
373                .collect::<Vec<_>>()
374                .join("")
375        })
376        .ok_or_else(|| ProviderError::Decode("missing content[].text".to_owned()))?;
377
378    let in_tokens = json
379        .pointer("/usage/input_tokens")
380        .and_then(Value::as_u64)
381        .unwrap_or(0);
382    let out_tokens = json
383        .pointer("/usage/output_tokens")
384        .and_then(Value::as_u64)
385        .unwrap_or(0);
386    // Prompt caching splits the prompt across three counters. Reading only `input_tokens` — which
387    // this did until now — reports about 20 tokens for a 190k-token cached prefix, so the receipt
388    // records a fraction of a cent for a call that cost most of a dollar, and `[budget]` caps fed
389    // by that total never trip.
390    let cache_write_tokens = json
391        .pointer("/usage/cache_creation_input_tokens")
392        .and_then(Value::as_u64)
393        .unwrap_or(0);
394    let cache_read_tokens = json
395        .pointer("/usage/cache_read_input_tokens")
396        .and_then(Value::as_u64)
397        .unwrap_or(0);
398
399    Ok(AnthropicUsage {
400        text,
401        in_tokens,
402        cache_write_tokens,
403        cache_read_tokens,
404        out_tokens,
405    })
406}
407
408/// Text plus the full token split from an Anthropic response.
409struct AnthropicUsage {
410    text: String,
411    in_tokens: u64,
412    cache_write_tokens: u64,
413    cache_read_tokens: u64,
414    out_tokens: u64,
415}
416
417/// Build an Anthropic Messages-shaped request body with the model **omitted** — Bedrock and Vertex
418/// both put the model in the URL, not the body (ADR 0006 P2/P3), unlike direct Anthropic API calls
419/// which need `model` in the body ([`AnthropicWireRequest`]). `anthropic_version` is the dialect
420/// version string each host expects (`bedrock-2023-05-31` / `vertex-2023-10-16`).
421fn anthropic_messages_body(req: &ModelRequest, anthropic_version: &str) -> Value {
422    // Same verbatim-carry rule as `anthropic_wire_body`, adapted to hosts that put the model in
423    // the URL: original inbound JSON minus `model`/`stream`, plus the host's version string.
424    if let Value::Object(raw) = &req.raw {
425        let mut body = raw.clone();
426        body.remove("model");
427        body.remove("stream");
428        body.insert(
429            "anthropic_version".to_owned(),
430            Value::String(anthropic_version.to_owned()),
431        );
432        return Value::Object(body);
433    }
434    let messages: Vec<Value> = req
435        .messages
436        .iter()
437        .map(|m| serde_json::json!({ "role": m.role, "content": m.content }))
438        .collect();
439    let mut body = serde_json::json!({
440        "anthropic_version": anthropic_version,
441        "max_tokens": req.max_tokens,
442        "messages": messages,
443    });
444    if let Some(system) = req.system.as_deref() {
445        body["system"] = serde_json::json!(system);
446    }
447    if !req.tools.is_null() {
448        body["tools"] = req.tools.clone();
449    }
450    body
451}
452
453/// Build the OpenAI Chat Completions wire body for `req`: the original inbound JSON **verbatim**
454/// with only `model` swapped to the rung's wire id and `stream` stripped (analogous to
455/// [`anthropic_wire_body`] for all-OpenAI-dialect ladders). Falls back to the normalized fields
456/// when there is no raw body (synthesized judge/consistency requests, or translation path).
457/// Pure, so fidelity is unit-testable.
458#[must_use]
459pub fn openai_wire_body(req: &ModelRequest) -> Value {
460    if let Value::Object(raw) = &req.raw {
461        let mut body = raw.clone();
462        body.insert(
463            "model".to_owned(),
464            Value::String(wire_model(&req.model).to_owned()),
465        );
466        body.remove("stream");
467        normalize_reasoning(&mut body, Wire::OpenAi);
468        return Value::Object(body);
469    }
470    // Fallback: reconstruct from normalized fields (translation path or synthesized requests).
471    let mut messages: Vec<Value> = Vec::with_capacity(req.messages.len() + 1);
472    if let Some(system) = req.system.as_deref() {
473        messages.push(serde_json::json!({ "role": "system", "content": system }));
474    }
475    messages.extend(
476        req.messages
477            .iter()
478            .map(|m| serde_json::json!({ "role": m.role, "content": m.content })),
479    );
480    let mut body = serde_json::json!({
481        "model": wire_model(&req.model),
482        "max_tokens": req.max_tokens,
483        "messages": messages,
484    });
485    if !req.tools.is_null() {
486        body["tools"] = req.tools.clone();
487    }
488    body
489}
490
491/// How hard the caller asked the model to think, independent of how any one provider spells it.
492///
493/// A cascade crosses vendors by design — a ladder is routinely `openai/…` under `anthropic/…` —
494/// so the caller's reasoning request has to survive the crossing. Without this, an OpenAI client
495/// that sets `reasoning_effort` gets a **400** the moment the router escalates it onto an
496/// Anthropic rung, because raw bodies pass through verbatim and Anthropic rejects the unknown
497/// field. The caller did nothing wrong; the ladder moved under it.
498#[derive(Debug, Clone, Copy, PartialEq, Eq)]
499pub enum Effort {
500    Low,
501    Medium,
502    High,
503}
504
505impl Effort {
506    /// Anthropic/Gemini want a token budget rather than a word. These are deliberately modest:
507    /// the budget is billed as output tokens, so a generous default would silently raise the cost
508    /// of every request that merely mentioned reasoning.
509    const fn budget_tokens(self) -> u32 {
510        match self {
511            Self::Low => 1024, // Anthropic's documented floor; below it the field is invalid.
512            Self::Medium => 4096,
513            Self::High => 16384,
514        }
515    }
516
517    /// Read back a budget as a level, so a caller that spelled it in tokens keeps its intent when
518    /// the request lands on a provider that spells it in words.
519    const fn from_budget(tokens: u64) -> Self {
520        if tokens < 2048 {
521            Self::Low
522        } else if tokens < 8192 {
523            Self::Medium
524        } else {
525            Self::High
526        }
527    }
528
529    fn as_str(self) -> &'static str {
530        match self {
531            Self::Low => "low",
532            Self::Medium => "medium",
533            Self::High => "high",
534        }
535    }
536}
537
538/// Read the caller's reasoning request out of a raw inbound body, in any dialect. Returns `None`
539/// for a body that is not an object or asked for no reasoning.
540#[must_use]
541pub fn effort_of(raw: &Value) -> Option<Effort> {
542    read_effort(raw.as_object()?)
543}
544
545/// Read whichever spelling the caller used, in any dialect.
546fn read_effort(body: &serde_json::Map<String, Value>) -> Option<Effort> {
547    // OpenAI: a word.
548    if let Some(s) = body.get("reasoning_effort").and_then(Value::as_str) {
549        return match s {
550            "low" | "minimal" => Some(Effort::Low),
551            "medium" => Some(Effort::Medium),
552            "high" => Some(Effort::High),
553            _ => None,
554        };
555    }
556    // Anthropic: a budget, but only when thinking is actually enabled.
557    if let Some(t) = body.get("thinking").and_then(Value::as_object)
558        && t.get("type").and_then(Value::as_str) != Some("disabled")
559        && let Some(b) = t.get("budget_tokens").and_then(Value::as_u64)
560    {
561        return Some(Effort::from_budget(b));
562    }
563    // Gemini: a budget under a camelCase key.
564    if let Some(b) = body
565        .get("thinkingConfig")
566        .and_then(Value::as_object)
567        .and_then(|c| c.get("thinkingBudget"))
568        .and_then(Value::as_u64)
569    {
570        return Some(Effort::from_budget(b));
571    }
572    None
573}
574
575/// Which wire dialect a body is being prepared for.
576#[derive(Debug, Clone, Copy, PartialEq, Eq)]
577pub enum Wire {
578    Anthropic,
579    OpenAi,
580    Gemini,
581}
582
583/// Rewrite `body` so the caller's reasoning request is spelled the way `target` expects, and no
584/// other dialect's spelling is left behind to be rejected.
585///
586/// Pure and total: a body with no reasoning request loses nothing, and a request that *cannot* be
587/// expressed within the target's constraints is dropped rather than sent invalid.
588pub fn normalize_reasoning(body: &mut serde_json::Map<String, Value>, target: Wire) {
589    // If the caller already spelled it the target's way, this is a same-dialect request: leave it
590    // completely alone. ADR 0005 promises a raw body reaches its own provider verbatim, and that
591    // promise covers the caller's mistakes too — a budget the caller's `max_tokens` cannot fit is
592    // theirs to see as a provider error, not ours to silently rewrite into a different request.
593    // Only a request whose spelling is *foreign* to where it landed needs translating, which is
594    // the cross-vendor escalation this exists for.
595    let native = match target {
596        Wire::OpenAi => "reasoning_effort",
597        Wire::Anthropic => "thinking",
598        Wire::Gemini => "thinkingConfig",
599    };
600    if body.contains_key(native) {
601        return;
602    }
603    let effort = read_effort(body);
604    // Strip every dialect first, so nothing foreign survives the crossing.
605    body.remove("reasoning_effort");
606    body.remove("thinking");
607    body.remove("thinkingConfig");
608    let Some(effort) = effort else { return };
609
610    match target {
611        Wire::OpenAi => {
612            body.insert(
613                "reasoning_effort".to_owned(),
614                Value::String(effort.as_str().to_owned()),
615            );
616        }
617        Wire::Anthropic => {
618            // Anthropic requires `max_tokens > budget_tokens`, and a budget of at least 1024.
619            // A caller with a small `max_tokens` cannot satisfy both, and sending it anyway is a
620            // 400 — so serve the request without extended thinking instead of failing it.
621            let max = body.get("max_tokens").and_then(Value::as_u64).unwrap_or(0);
622            let budget = u64::from(effort.budget_tokens()).min(max.saturating_sub(1));
623            if budget >= 1024 {
624                body.insert(
625                    "thinking".to_owned(),
626                    serde_json::json!({ "type": "enabled", "budget_tokens": budget }),
627                );
628                // Extended thinking rejects any temperature but the default; the caller's value
629                // was chosen without knowing the router would enable thinking.
630                body.remove("temperature");
631                body.remove("top_p");
632            }
633        }
634        Wire::Gemini => {
635            // Gemini nests this under `generationConfig`, not at the top level.
636            body.entry("generationConfig")
637                .or_insert_with(|| Value::Object(serde_json::Map::new()))
638                .as_object_mut()
639                .map(|c| {
640                    c.insert(
641                        "thinkingConfig".to_owned(),
642                        serde_json::json!({ "thinkingBudget": effort.budget_tokens() }),
643                    )
644                });
645        }
646    }
647}
648
649/// Insert Anthropic prompt-cache breakpoints on the stable prefix of a request.
650///
651/// Marks the end of the system prompt and the end of the tool definitions — the part of an agent's
652/// request that is byte-identical turn after turn. Everything after the last breakpoint (the
653/// conversation itself) is not cached.
654///
655/// **This is opt-in, and it is not free money.** A cache *write* costs
656/// [`CACHE_WRITE_MULTIPLIER`](firstpass_core::cost::CACHE_WRITE_MULTIPLIER) (1.25×) of base input,
657/// and only pays back once the same prefix is read again — [`CACHE_READ_MULTIPLIER`] is 0.1×, so
658/// roughly one reuse covers the premium and everything after is a large saving. On a long agent
659/// session with a fixed system prompt and tool set that is a clear win; on single-shot traffic it
660/// is a 25% surcharge on the prefix for nothing. Which one an operator has is a question about
661/// their traffic, not about this code, so it is configured rather than assumed.
662///
663/// Idempotent: a caller already using `cache_control` keeps their own breakpoints and gets none
664/// added, since they have placed them with knowledge this code does not have.
665/// Smallest serialized prefix worth marking, in characters.
666///
667/// Anthropic's minimum cacheable prefix is 1024 tokens (2048 on Haiku). At roughly 4 characters per
668/// token that is ~4096 characters; this floor sits deliberately below it, so the guard only skips
669/// prefixes that could not possibly qualify rather than second-guessing the tokenizer.
670const MIN_CACHEABLE_PREFIX_CHARS: usize = 3000;
671
672pub fn add_cache_breakpoints(body: &mut serde_json::Map<String, Value>) {
673    if body_has_cache_control(body) {
674        return;
675    }
676    // Anthropic refuses to cache a prefix below a per-model minimum (1024 tokens for Sonnet/Opus,
677    // 2048 for Haiku). Marking a shorter one is not merely wasted — it is a request the API can
678    // reject outright. Estimated from serialized bytes at the usual ~4 chars/token, floored well
679    // under the real minimum so this only skips prefixes that are clearly too small to qualify.
680    let prefix_chars = body.get("system").map_or(0, |v| v.to_string().len())
681        + body.get("tools").map_or(0, |v| v.to_string().len());
682    if prefix_chars < MIN_CACHEABLE_PREFIX_CHARS {
683        return;
684    }
685    let marker = serde_json::json!({ "type": "ephemeral" });
686
687    // `system` may be a bare string; caching requires the block form.
688    match body.get("system") {
689        Some(Value::String(text)) if !text.is_empty() => {
690            body.insert(
691                "system".to_owned(),
692                serde_json::json!([{
693                    "type": "text", "text": text, "cache_control": marker,
694                }]),
695            );
696        }
697        Some(Value::Array(blocks)) if !blocks.is_empty() => {
698            let mut blocks = blocks.clone();
699            if let Some(last) = blocks.last_mut().and_then(Value::as_object_mut) {
700                last.insert("cache_control".to_owned(), marker.clone());
701            }
702            body.insert("system".to_owned(), Value::Array(blocks));
703        }
704        _ => {}
705    }
706
707    // Tool definitions are the other half of the stable prefix, and on an agent request usually
708    // the larger half.
709    if let Some(Value::Array(tools)) = body.get("tools")
710        && !tools.is_empty()
711    {
712        let mut tools = tools.clone();
713        if let Some(last) = tools.last_mut().and_then(Value::as_object_mut) {
714            last.insert("cache_control".to_owned(), marker);
715        }
716        body.insert("tools".to_owned(), Value::Array(tools));
717    }
718}
719
720/// Whether the caller already placed cache breakpoints of their own.
721fn body_has_cache_control(body: &serde_json::Map<String, Value>) -> bool {
722    fn any_in(v: &Value) -> bool {
723        match v {
724            Value::Array(items) => items.iter().any(any_in),
725            Value::Object(o) => o.contains_key("cache_control") || o.values().any(any_in),
726            _ => false,
727        }
728    }
729    body.values().any(any_in)
730}
731
732/// Speaks `POST {base}/v1/chat/completions` (OpenAI Chat Completions API).
733///
734// LIVE-UNVERIFIED: the `wire_model` prefix-strip fix is applied here too, but the OpenAI path has
735// not yet been exercised against a real endpoint (only Anthropic has). Verify against a real key
736// before relying on it in production.
737#[derive(Debug, Clone)]
738pub struct OpenAiProvider {
739    /// Ladder prefix / trace label for this provider (`"openai"`, `"groq"`, `"together"`, …).
740    pub id: String,
741    /// Base URL, e.g. `https://api.openai.com` or `https://api.groq.com/openai`.
742    pub base_url: String,
743    /// Env var the API key is read from, e.g. `"GROQ_API_KEY"`. `None` for the built-in `openai`
744    /// provider (resolves via [`Auth`]: `authorization` header or `OPENAI_API_KEY`) and for keyless
745    /// local endpoints (Ollama / vLLM).
746    pub api_key_env: Option<String>,
747    /// Shared, connection-pooled HTTP client.
748    pub http: reqwest::Client,
749}
750
751#[async_trait]
752impl Provider for OpenAiProvider {
753    fn id(&self) -> &str {
754        &self.id
755    }
756
757    fn carries_structured_verbatim(&self, inbound: firstpass_core::Dialect) -> bool {
758        inbound == firstpass_core::Dialect::Openai
759    }
760
761    async fn complete(
762        &self,
763        req: &ModelRequest,
764        auth: &Auth,
765    ) -> Result<ModelResponse, ProviderError> {
766        let key = resolve_api_key(self.api_key_env.as_deref(), auth.openai_key.as_deref());
767        let body = openai_wire_body(req);
768
769        let url = format!(
770            "{}/v1/chat/completions",
771            self.base_url.trim_end_matches('/')
772        );
773        let resp = self
774            .http
775            .post(url)
776            .header(axum::http::header::AUTHORIZATION, format!("Bearer {key}"))
777            .json(&body)
778            .send()
779            .await
780            .map_err(|e| ProviderError::Transport(e.to_string()))?;
781
782        let status = resp.status();
783        let bytes = resp
784            .bytes()
785            .await
786            .map_err(|e| ProviderError::Transport(e.to_string()))?;
787
788        if !status.is_success() {
789            return Err(ProviderError::Http {
790                status: status.as_u16(),
791                body: String::from_utf8_lossy(&bytes).into_owned(),
792            });
793        }
794
795        let json: Value =
796            serde_json::from_slice(&bytes).map_err(|e| ProviderError::Decode(e.to_string()))?;
797
798        // `content` is null for tool-call-only responses; treat as empty text rather than an error.
799        let text = json
800            .pointer("/choices/0/message/content")
801            .and_then(Value::as_str)
802            .unwrap_or("")
803            .to_owned();
804
805        let in_tokens = json
806            .pointer("/usage/prompt_tokens")
807            .and_then(Value::as_u64)
808            .unwrap_or(0);
809        let out_tokens = json
810            .pointer("/usage/completion_tokens")
811            .and_then(Value::as_u64)
812            .unwrap_or(0);
813
814        Ok(ModelResponse {
815            // This provider reports no prompt-cache split.
816            cache_write_tokens: 0,
817            cache_read_tokens: 0,
818            model: req.model.clone(),
819            text,
820            in_tokens,
821            out_tokens,
822            raw: json,
823        })
824    }
825}
826
827/// Build the Gemini `generateContent` request body from a normalized [`ModelRequest`]. Split out
828/// (pure, no I/O) so the translation is unit-tested offline. Gemini uses `contents` with roles
829/// `user` / `model` (not `assistant`) and a separate `system_instruction`; the system prompt and the
830/// per-message text projection ([`ChatMessage::text_view`]) are what we send. Tool/multimodal blocks
831/// for Gemini (its `functionCall` / `functionResponse` / `inlineData` shapes) are a follow-on — this
832/// adapter routes text, matching the OpenAI adapter's current scope.
833fn gemini_request_body(req: &ModelRequest) -> Value {
834    let contents: Vec<Value> = req
835        .messages
836        .iter()
837        .map(|m| {
838            let role = if m.role == "assistant" {
839                "model"
840            } else {
841                "user"
842            };
843            serde_json::json!({ "role": role, "parts": [{ "text": m.text_view() }] })
844        })
845        .collect();
846    let mut body = serde_json::json!({
847        "contents": contents,
848        "generationConfig": { "maxOutputTokens": req.max_tokens },
849    });
850    if let Some(system) = req.system.as_deref() {
851        body["system_instruction"] = serde_json::json!({ "parts": [{ "text": system }] });
852    }
853    // This builder reconstructs from normalized fields, so the caller's reasoning request is only
854    // in `raw` — carry it across rather than dropping it on the Gemini rung.
855    if let (Some(effort), Some(map)) = (effort_of(&req.raw), body.as_object_mut()) {
856        let mut carry = serde_json::Map::new();
857        carry.insert(
858            "reasoning_effort".to_owned(),
859            Value::String(effort.as_str().to_owned()),
860        );
861        carry.insert(
862            "generationConfig".to_owned(),
863            map["generationConfig"].clone(),
864        );
865        normalize_reasoning(&mut carry, Wire::Gemini);
866        map.insert(
867            "generationConfig".to_owned(),
868            carry["generationConfig"].clone(),
869        );
870    }
871    body
872}
873
874/// Extract `(text, in_tokens, out_tokens)` from a Gemini `generateContent` response. `text` is the
875/// concatenation of the first candidate's text parts; token counts come from `usageMetadata`.
876fn gemini_parse_response(json: &Value) -> Result<(String, u64, u64), ProviderError> {
877    let parts = json
878        .pointer("/candidates/0/content/parts")
879        .and_then(Value::as_array)
880        .ok_or_else(|| ProviderError::Decode("missing candidates[0].content.parts".to_owned()))?;
881    let text = parts
882        .iter()
883        .filter_map(|p| p.get("text").and_then(Value::as_str))
884        .collect::<Vec<_>>()
885        .join("");
886    let in_tokens = json
887        .pointer("/usageMetadata/promptTokenCount")
888        .and_then(Value::as_u64)
889        .unwrap_or(0);
890    let out_tokens = json
891        .pointer("/usageMetadata/candidatesTokenCount")
892        .and_then(Value::as_u64)
893        .unwrap_or(0);
894    Ok((text, in_tokens, out_tokens))
895}
896
897/// Speaks `POST {base}/v1beta/models/{model}:generateContent` (Google Gemini Generative Language
898/// API). The API key goes in the `x-goog-api-key` header — never the URL query string, so it stays
899/// out of logs and proxies.
900///
901// LIVE-VERIFIED (2026-08-03): served `google/gemini-3.5-flash-lite` end to end through the real
902// proxy against the real endpoint, with a receipt, in the `provider-smoke` matrix. Note the
903// timestamp — that is a claim about a commit, not a standing property.
904#[derive(Debug, Clone)]
905pub struct GeminiProvider {
906    /// Ladder prefix / trace label (usually `"gemini"` or `"google"`).
907    pub id: String,
908    /// Base URL, e.g. `https://generativelanguage.googleapis.com`.
909    pub base_url: String,
910    /// Env var the API key is read from, e.g. `"GEMINI_API_KEY"`.
911    pub api_key_env: Option<String>,
912    /// Shared, connection-pooled HTTP client.
913    pub http: reqwest::Client,
914}
915
916#[async_trait]
917impl Provider for GeminiProvider {
918    fn id(&self) -> &str {
919        &self.id
920    }
921
922    async fn complete(
923        &self,
924        req: &ModelRequest,
925        auth: &Auth,
926    ) -> Result<ModelResponse, ProviderError> {
927        let key = resolve_api_key(self.api_key_env.as_deref(), auth.openai_key.as_deref());
928        let body = gemini_request_body(req);
929        let url = format!(
930            "{}/v1beta/models/{}:generateContent",
931            self.base_url.trim_end_matches('/'),
932            wire_model(&req.model),
933        );
934        let resp = self
935            .http
936            .post(url)
937            .header("x-goog-api-key", key)
938            .json(&body)
939            .send()
940            .await
941            .map_err(|e| ProviderError::Transport(e.to_string()))?;
942
943        let status = resp.status();
944        let bytes = resp
945            .bytes()
946            .await
947            .map_err(|e| ProviderError::Transport(e.to_string()))?;
948        if !status.is_success() {
949            return Err(ProviderError::Http {
950                status: status.as_u16(),
951                body: String::from_utf8_lossy(&bytes).into_owned(),
952            });
953        }
954
955        let json: Value =
956            serde_json::from_slice(&bytes).map_err(|e| ProviderError::Decode(e.to_string()))?;
957        let (text, in_tokens, out_tokens) = gemini_parse_response(&json)?;
958        Ok(ModelResponse {
959            // This provider reports no prompt-cache split.
960            cache_write_tokens: 0,
961            cache_read_tokens: 0,
962            model: req.model.clone(),
963            text,
964            in_tokens,
965            out_tokens,
966            raw: json,
967        })
968    }
969}
970
971/// AWS credentials read fresh from the standard env vars at call time — never cached, never
972/// logged (ADR 0006 P2). `AWS_SESSION_TOKEN` is optional (long-lived IAM user keys have none;
973/// STS-issued temporary credentials do).
974struct AwsEnvCredentials {
975    access_key_id: String,
976    secret_access_key: String,
977    session_token: Option<String>,
978}
979
980impl AwsEnvCredentials {
981    fn from_env() -> Result<Self, ProviderError> {
982        let access_key_id = std::env::var("AWS_ACCESS_KEY_ID")
983            .map_err(|_| ProviderError::Transport("AWS_ACCESS_KEY_ID is not set".to_owned()))?;
984        let secret_access_key = std::env::var("AWS_SECRET_ACCESS_KEY")
985            .map_err(|_| ProviderError::Transport("AWS_SECRET_ACCESS_KEY is not set".to_owned()))?;
986        let session_token = std::env::var("AWS_SESSION_TOKEN").ok();
987        Ok(Self {
988            access_key_id,
989            secret_access_key,
990            session_token,
991        })
992    }
993}
994
995/// Build the Bedrock `invoke` URL for a region + wire model id.
996fn bedrock_url(region: &str, model: &str) -> String {
997    format!("https://bedrock-runtime.{region}.amazonaws.com/model/{model}/invoke")
998}
999
1000/// SigV4-sign a Bedrock `InvokeModel` request, returning the fully-built (headers + body) HTTP
1001/// request ready to hand to reqwest. Delegates all canonical-request construction and HMAC signing
1002/// to `aws-sigv4` (ADR 0006 I3) — this function only wires host/service/region into that crate's
1003/// API and applies the resulting signature. Split out from [`BedrockProvider::complete`] so the
1004/// signing shape (not its cryptographic validity, which only a real AWS call can prove) is
1005/// unit-testable offline with dummy credentials.
1006///
1007// LIVE-UNVERIFIED: tests assert the produced request carries an `AWS4-HMAC-SHA256` authorization
1008// header and the expected host, against dummy credentials. Signature validity is only provable
1009// against a real Bedrock endpoint.
1010fn sign_bedrock(
1011    url: &str,
1012    region: &str,
1013    body: &[u8],
1014    creds: &AwsEnvCredentials,
1015) -> Result<http::Request<Vec<u8>>, ProviderError> {
1016    let host = url
1017        .parse::<http::Uri>()
1018        .ok()
1019        .and_then(|u| u.host().map(str::to_owned))
1020        .ok_or_else(|| ProviderError::Transport(format!("invalid bedrock URL: {url}")))?;
1021
1022    let identity: aws_smithy_runtime_api::client::identity::Identity =
1023        aws_credential_types::Credentials::new(
1024            creds.access_key_id.clone(),
1025            creds.secret_access_key.clone(),
1026            creds.session_token.clone(),
1027            None,
1028            "firstpass",
1029        )
1030        .into();
1031
1032    let signing_params: aws_sigv4::http_request::SigningParams<'_> =
1033        aws_sigv4::sign::v4::SigningParams::builder()
1034            .identity(&identity)
1035            .region(region)
1036            .name("bedrock")
1037            .time(SystemTime::now())
1038            .settings(aws_sigv4::http_request::SigningSettings::default())
1039            .build()
1040            .map_err(|e| ProviderError::Transport(format!("sigv4 signing params: {e}")))?
1041            .into();
1042
1043    let headers = [
1044        ("host", host.as_str()),
1045        ("content-type", "application/json"),
1046    ];
1047    let signable = aws_sigv4::http_request::SignableRequest::new(
1048        "POST",
1049        url,
1050        headers.into_iter(),
1051        aws_sigv4::http_request::SignableBody::Bytes(body),
1052    )
1053    .map_err(|e| ProviderError::Transport(format!("sigv4 signable request: {e}")))?;
1054
1055    let (instructions, _signature) = aws_sigv4::http_request::sign(signable, &signing_params)
1056        .map_err(|e| ProviderError::Transport(format!("sigv4 sign: {e}")))?
1057        .into_parts();
1058
1059    let mut req = http::Request::builder()
1060        .method("POST")
1061        .uri(url)
1062        .header("host", host)
1063        .header("content-type", "application/json")
1064        .body(body.to_vec())
1065        .map_err(|e| ProviderError::Transport(format!("build bedrock request: {e}")))?;
1066    instructions.apply_to_request_http1x(&mut req);
1067    Ok(req)
1068}
1069
1070/// Speaks `POST https://bedrock-runtime.{region}.amazonaws.com/model/{model}/invoke` (Claude on AWS
1071/// Bedrock) — an Anthropic-shaped body ([`anthropic_messages_body`]) authenticated with AWS SigV4
1072/// request signing rather than an API key (ADR 0006 P2). Credentials come from the standard
1073/// `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN` env vars, read fresh per
1074/// call — never logged, never put in the URL (I2).
1075///
1076// LIVE-UNVERIFIED: the request/response translation and signing call shape are unit-tested
1077// offline; this has not been exercised against a real Bedrock endpoint. Verify against real AWS
1078// credentials before relying on it in production.
1079#[derive(Debug, Clone)]
1080pub struct BedrockProvider {
1081    /// Ladder prefix / trace label (usually `"bedrock"`).
1082    pub id: String,
1083    /// AWS region Bedrock is called in, e.g. `"us-east-1"`.
1084    pub region: Option<String>,
1085    /// Shared, connection-pooled HTTP client.
1086    pub http: reqwest::Client,
1087}
1088
1089#[async_trait]
1090impl Provider for BedrockProvider {
1091    fn id(&self) -> &str {
1092        &self.id
1093    }
1094
1095    fn carries_structured_verbatim(&self, inbound: firstpass_core::Dialect) -> bool {
1096        inbound == firstpass_core::Dialect::Anthropic
1097    }
1098
1099    async fn complete(
1100        &self,
1101        req: &ModelRequest,
1102        _auth: &Auth,
1103    ) -> Result<ModelResponse, ProviderError> {
1104        let region = self.region.as_deref().ok_or_else(|| {
1105            ProviderError::Transport("bedrock provider requires a region".to_owned())
1106        })?;
1107        let model = wire_model(&req.model);
1108        let url = bedrock_url(region, model);
1109        let body = anthropic_messages_body(req, "bedrock-2023-05-31");
1110        let body_bytes =
1111            serde_json::to_vec(&body).map_err(|e| ProviderError::Decode(e.to_string()))?;
1112
1113        let creds = AwsEnvCredentials::from_env()?;
1114        let signed = sign_bedrock(&url, region, &body_bytes, &creds)?;
1115        let http_req = reqwest::Request::try_from(signed)
1116            .map_err(|e| ProviderError::Transport(format!("build reqwest request: {e}")))?;
1117
1118        let resp = self
1119            .http
1120            .execute(http_req)
1121            .await
1122            .map_err(|e| ProviderError::Transport(e.to_string()))?;
1123
1124        let status = resp.status();
1125        let bytes = resp
1126            .bytes()
1127            .await
1128            .map_err(|e| ProviderError::Transport(e.to_string()))?;
1129        if !status.is_success() {
1130            return Err(ProviderError::Http {
1131                status: status.as_u16(),
1132                body: String::from_utf8_lossy(&bytes).into_owned(),
1133            });
1134        }
1135
1136        let json: Value =
1137            serde_json::from_slice(&bytes).map_err(|e| ProviderError::Decode(e.to_string()))?;
1138        let u = anthropic_parse_response(&json)?;
1139        let (text, in_tokens, out_tokens) = (u.text, u.in_tokens, u.out_tokens);
1140        let (cache_write_tokens, cache_read_tokens) = (u.cache_write_tokens, u.cache_read_tokens);
1141        Ok(ModelResponse {
1142            cache_write_tokens,
1143            cache_read_tokens,
1144            model: req.model.clone(),
1145            text,
1146            in_tokens,
1147            out_tokens,
1148            raw: json,
1149        })
1150    }
1151}
1152
1153/// Build the Vertex AI `rawPredict` URL for a region + project + wire model id (Claude on Vertex).
1154fn vertex_url(region: &str, project: &str, model: &str) -> String {
1155    format!(
1156        "https://{region}-aiplatform.googleapis.com/v1/projects/{project}/locations/{region}/publishers/anthropic/models/{model}:rawPredict"
1157    )
1158}
1159
1160/// Speaks `POST https://{region}-aiplatform.googleapis.com/.../publishers/anthropic/models/{model}:rawPredict`
1161/// (Claude on Google Vertex AI) — an Anthropic-shaped body ([`anthropic_messages_body`])
1162/// authenticated with a GCP OAuth2 bearer token rather than an API key (ADR 0006 P3). The token is
1163/// minted and cached by `gcp_auth` from `GOOGLE_APPLICATION_CREDENTIALS` or the ambient GCP
1164/// environment — this adapter never caches or logs it, and it never goes in the URL (I2).
1165///
1166// LIVE-UNVERIFIED: the request/response translation is unit-tested offline; this has not been
1167// exercised against a real Vertex endpoint. Verify against a real service account before relying
1168// on it in production.
1169#[derive(Debug, Clone)]
1170pub struct VertexProvider {
1171    /// Ladder prefix / trace label (usually `"vertex"`).
1172    pub id: String,
1173    /// GCP region Vertex is called in, e.g. `"us-central1"`.
1174    pub region: Option<String>,
1175    /// GCP project id.
1176    pub project: Option<String>,
1177    /// Shared, connection-pooled HTTP client.
1178    pub http: reqwest::Client,
1179}
1180
1181#[async_trait]
1182impl Provider for VertexProvider {
1183    fn id(&self) -> &str {
1184        &self.id
1185    }
1186
1187    fn carries_structured_verbatim(&self, inbound: firstpass_core::Dialect) -> bool {
1188        inbound == firstpass_core::Dialect::Anthropic
1189    }
1190
1191    async fn complete(
1192        &self,
1193        req: &ModelRequest,
1194        _auth: &Auth,
1195    ) -> Result<ModelResponse, ProviderError> {
1196        let region = self.region.as_deref().ok_or_else(|| {
1197            ProviderError::Transport("vertex provider requires a region".to_owned())
1198        })?;
1199        let project = self.project.as_deref().ok_or_else(|| {
1200            ProviderError::Transport("vertex provider requires a project".to_owned())
1201        })?;
1202        let model = wire_model(&req.model);
1203        let url = vertex_url(region, project, model);
1204        let body = anthropic_messages_body(req, "vertex-2023-10-16");
1205
1206        // ponytail: gcp_auth re-detects the auth method per call (the token itself is cached inside
1207        // the provider). Cache the provider in a OnceCell if Vertex ever becomes a hot path.
1208        let provider = gcp_auth::provider()
1209            .await
1210            .map_err(|e| ProviderError::Transport(format!("gcp_auth provider: {e}")))?;
1211        let token = provider
1212            .token(&["https://www.googleapis.com/auth/cloud-platform"])
1213            .await
1214            .map_err(|e| ProviderError::Transport(format!("gcp_auth token: {e}")))?;
1215
1216        let resp = self
1217            .http
1218            .post(url)
1219            .header(
1220                axum::http::header::AUTHORIZATION,
1221                format!("Bearer {}", token.as_str()),
1222            )
1223            .json(&body)
1224            .send()
1225            .await
1226            .map_err(|e| ProviderError::Transport(e.to_string()))?;
1227
1228        let status = resp.status();
1229        let bytes = resp
1230            .bytes()
1231            .await
1232            .map_err(|e| ProviderError::Transport(e.to_string()))?;
1233        if !status.is_success() {
1234            return Err(ProviderError::Http {
1235                status: status.as_u16(),
1236                body: String::from_utf8_lossy(&bytes).into_owned(),
1237            });
1238        }
1239
1240        let json: Value =
1241            serde_json::from_slice(&bytes).map_err(|e| ProviderError::Decode(e.to_string()))?;
1242        let u = anthropic_parse_response(&json)?;
1243        let (text, in_tokens, out_tokens) = (u.text, u.in_tokens, u.out_tokens);
1244        let (cache_write_tokens, cache_read_tokens) = (u.cache_write_tokens, u.cache_read_tokens);
1245        Ok(ModelResponse {
1246            cache_write_tokens,
1247            cache_read_tokens,
1248            model: req.model.clone(),
1249            text,
1250            in_tokens,
1251            out_tokens,
1252            raw: json,
1253        })
1254    }
1255}
1256
1257/// Lookup from provider id (`"anthropic"`, `"openai"`, ...) to the [`Provider`] that serves it.
1258#[derive(Clone)]
1259pub struct ProviderRegistry {
1260    providers: HashMap<String, Arc<dyn Provider>>,
1261}
1262
1263impl std::fmt::Debug for ProviderRegistry {
1264    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1265        f.debug_struct("ProviderRegistry")
1266            .field("providers", &self.providers.keys().collect::<Vec<_>>())
1267            .finish()
1268    }
1269}
1270
1271impl ProviderRegistry {
1272    /// One HTTP client shared by every provider. The enforce path is request/response (never
1273    /// streamed through the adapter), so it carries a total request timeout as well as a connect
1274    /// timeout — a hung or slow upstream can't pin a routing decision indefinitely. Falls back to a
1275    /// default client if the builder fails (only on TLS backend init, which is fatal anyway).
1276    fn build_http_client() -> reqwest::Client {
1277        reqwest::Client::builder()
1278            .connect_timeout(std::time::Duration::from_secs(10))
1279            .timeout(std::time::Duration::from_secs(120))
1280            .build()
1281            .unwrap_or_else(|_| reqwest::Client::new())
1282    }
1283
1284    /// Build the standard registry: the built-in `anthropic` + `openai` providers.
1285    #[must_use]
1286    pub fn new(anthropic_base: impl Into<String>, openai_base: impl Into<String>) -> Self {
1287        Self::from_config(&[], anthropic_base, openai_base)
1288    }
1289
1290    /// Build the registry with the built-in `anthropic` / `openai` providers plus every configured
1291    /// `[[provider]]` entry — so a ladder can route to any OpenAI-compatible or Anthropic-compatible
1292    /// endpoint (Groq, Together, Fireworks, DeepSeek, Mistral, xAI, OpenRouter, Ollama, vLLM, Azure,
1293    /// …) by id. A `[[provider]]` whose id is `anthropic` or `openai` overrides the built-in default
1294    /// (e.g. to point `openai` at Azure). Shares one HTTP client across all of them.
1295    #[must_use]
1296    pub fn from_config(
1297        defs: &[firstpass_core::ProviderDef],
1298        anthropic_base: impl Into<String>,
1299        openai_base: impl Into<String>,
1300    ) -> Self {
1301        let http = Self::build_http_client();
1302        let mut providers: HashMap<String, Arc<dyn Provider>> = HashMap::new();
1303        providers.insert(
1304            "anthropic".to_owned(),
1305            Arc::new(AnthropicProvider {
1306                id: "anthropic".to_owned(),
1307                base_url: anthropic_base.into(),
1308                api_key_env: None,
1309                http: http.clone(),
1310            }),
1311        );
1312        providers.insert(
1313            "openai".to_owned(),
1314            Arc::new(OpenAiProvider {
1315                id: "openai".to_owned(),
1316                base_url: openai_base.into(),
1317                api_key_env: None,
1318                http: http.clone(),
1319            }),
1320        );
1321        for def in defs {
1322            // Auth scheme comes first (ADR 0006): `aws_sigv4`/`gcp_oauth` are bespoke-auth
1323            // backends that wrap the Anthropic body shape regardless of `dialect`; `api_key`
1324            // (the default) is today's dialect-driven dispatch, unchanged.
1325            let provider: Arc<dyn Provider> = match def.auth {
1326                firstpass_core::AuthScheme::AwsSigv4 => Arc::new(BedrockProvider {
1327                    id: def.id.clone(),
1328                    region: def.region.clone(),
1329                    http: http.clone(),
1330                }),
1331                firstpass_core::AuthScheme::GcpOauth => Arc::new(VertexProvider {
1332                    id: def.id.clone(),
1333                    region: def.region.clone(),
1334                    project: def.project.clone(),
1335                    http: http.clone(),
1336                }),
1337                firstpass_core::AuthScheme::ApiKey => match def.dialect {
1338                    firstpass_core::Dialect::Anthropic => Arc::new(AnthropicProvider {
1339                        id: def.id.clone(),
1340                        base_url: def.base_url.clone(),
1341                        api_key_env: def.api_key_env.clone(),
1342                        http: http.clone(),
1343                    }),
1344                    firstpass_core::Dialect::Openai => Arc::new(OpenAiProvider {
1345                        id: def.id.clone(),
1346                        base_url: def.base_url.clone(),
1347                        api_key_env: def.api_key_env.clone(),
1348                        http: http.clone(),
1349                    }),
1350                    firstpass_core::Dialect::Gemini => Arc::new(GeminiProvider {
1351                        id: def.id.clone(),
1352                        base_url: def.base_url.clone(),
1353                        api_key_env: def.api_key_env.clone(),
1354                        http: http.clone(),
1355                    }),
1356                },
1357            };
1358            providers.insert(def.id.clone(), provider);
1359        }
1360        Self { providers }
1361    }
1362
1363    /// Build a registry from arbitrary providers — used to wire up [`MockProvider`]s in tests.
1364    #[must_use]
1365    pub fn from_map(providers: HashMap<String, Arc<dyn Provider>>) -> Self {
1366        Self { providers }
1367    }
1368
1369    /// Look up a provider by id.
1370    #[must_use]
1371    pub fn get(&self, provider_id: &str) -> Option<Arc<dyn Provider>> {
1372        self.providers.get(provider_id).cloned()
1373    }
1374}
1375
1376/// Test-only provider: returns a pre-programmed outcome per model, deterministically.
1377#[cfg(test)]
1378#[derive(Debug, Clone, Default)]
1379pub struct MockProvider {
1380    id: String,
1381    outcomes: HashMap<String, Result<ModelResponse, ProviderError>>,
1382    /// Every model string `complete()` was called with — lets speculation tests assert which rungs
1383    /// were actually fired. Shared (`Arc`) so a clone taken before boxing still observes the calls.
1384    calls: Arc<std::sync::Mutex<Vec<String>>>,
1385    /// Simulated per-call latency (0 = respond instantly). Lets a test measure the wall-clock win
1386    /// speculation buys by overlapping rung calls that would otherwise run serially.
1387    delay_ms: u64,
1388}
1389
1390#[cfg(test)]
1391impl MockProvider {
1392    /// Build a mock provider that answers `outcomes[model]` for `complete()`.
1393    #[must_use]
1394    pub fn new(
1395        id: impl Into<String>,
1396        outcomes: HashMap<String, Result<ModelResponse, ProviderError>>,
1397    ) -> Self {
1398        Self {
1399            id: id.into(),
1400            outcomes,
1401            calls: Arc::default(),
1402            delay_ms: 0,
1403        }
1404    }
1405
1406    /// Make `complete()` sleep `ms` before responding, to simulate real per-call latency.
1407    #[must_use]
1408    pub fn with_delay(mut self, ms: u64) -> Self {
1409        self.delay_ms = ms;
1410        self
1411    }
1412
1413    /// A handle to the shared call log; clone it before boxing the provider into a registry, then
1414    /// inspect the models `complete()` saw after the engine runs.
1415    #[must_use]
1416    pub fn call_log(&self) -> Arc<std::sync::Mutex<Vec<String>>> {
1417        Arc::clone(&self.calls)
1418    }
1419}
1420
1421#[cfg(test)]
1422#[async_trait]
1423impl Provider for MockProvider {
1424    fn id(&self) -> &str {
1425        &self.id
1426    }
1427
1428    // ponytail: returns true for all dialects — test-only mock needs to pass the fidelity guard
1429    // for both Anthropic and OpenAI inbound tests without a real dialect-split implementation.
1430    fn carries_structured_verbatim(&self, _inbound: firstpass_core::Dialect) -> bool {
1431        true
1432    }
1433
1434    async fn complete(
1435        &self,
1436        req: &ModelRequest,
1437        _auth: &Auth,
1438    ) -> Result<ModelResponse, ProviderError> {
1439        self.calls.lock().unwrap().push(req.model.clone());
1440        if self.delay_ms > 0 {
1441            tokio::time::sleep(std::time::Duration::from_millis(self.delay_ms)).await;
1442        }
1443        self.outcomes.get(&req.model).cloned().unwrap_or_else(|| {
1444            Err(ProviderError::Decode(format!(
1445                "no mock outcome configured for {}",
1446                req.model
1447            )))
1448        })
1449    }
1450}
1451
1452#[cfg(test)]
1453mod tests {
1454    use super::*;
1455
1456    fn obj(v: Value) -> serde_json::Map<String, Value> {
1457        v.as_object().expect("test literal is an object").clone()
1458    }
1459
1460    #[test]
1461    fn openai_reasoning_effort_crosses_onto_an_anthropic_rung() {
1462        // The bug this exists for: a ladder is routinely cross-vendor, so an OpenAI client that
1463        // set `reasoning_effort` gets escalated onto an Anthropic rung. Forwarded verbatim that
1464        // is a 400 on a request the caller wrote correctly.
1465        let mut body = obj(serde_json::json!({
1466            "model": "claude-sonnet-5", "max_tokens": 8192, "reasoning_effort": "high",
1467        }));
1468
1469        normalize_reasoning(&mut body, Wire::Anthropic);
1470
1471        assert!(
1472            !body.contains_key("reasoning_effort"),
1473            "the foreign spelling must not survive: {body:?}"
1474        );
1475        assert_eq!(body["thinking"]["type"], "enabled");
1476        // Clamped to max_tokens - 1: "high" wants 16384, but Anthropic requires the budget to
1477        // leave room for the answer itself.
1478        assert_eq!(body["thinking"]["budget_tokens"], 8191);
1479    }
1480
1481    #[test]
1482    fn anthropic_thinking_budget_crosses_onto_an_openai_rung_as_a_word() {
1483        let mut body = obj(serde_json::json!({
1484            "model": "gpt-5.5",
1485            "thinking": { "type": "enabled", "budget_tokens": 16384 },
1486        }));
1487
1488        normalize_reasoning(&mut body, Wire::OpenAi);
1489
1490        assert!(!body.contains_key("thinking"));
1491        assert_eq!(body["reasoning_effort"], "high");
1492    }
1493
1494    #[test]
1495    fn thinking_is_dropped_rather_than_sent_invalid_when_max_tokens_cannot_fit_it() {
1496        // Anthropic requires budget >= 1024 AND max_tokens > budget. A caller asking for high
1497        // effort with max_tokens=500 cannot have both; sending it anyway is a 400. Serving
1498        // without extended thinking is the answer the caller can actually use.
1499        let mut body = obj(serde_json::json!({
1500            "model": "claude-sonnet-5", "max_tokens": 500, "reasoning_effort": "high",
1501        }));
1502
1503        normalize_reasoning(&mut body, Wire::Anthropic);
1504
1505        assert!(
1506            !body.contains_key("thinking"),
1507            "must not emit a budget max_tokens cannot satisfy: {body:?}"
1508        );
1509        assert!(!body.contains_key("reasoning_effort"));
1510    }
1511
1512    #[test]
1513    fn enabling_thinking_clears_a_temperature_the_caller_chose_without_knowing() {
1514        // Extended thinking rejects any temperature but the default. The caller set it before the
1515        // router decided to enable thinking, so keeping it would 400.
1516        let mut body = obj(serde_json::json!({
1517            "model": "claude-sonnet-5", "max_tokens": 8192,
1518            "reasoning_effort": "medium", "temperature": 0.2, "top_p": 0.9,
1519        }));
1520
1521        normalize_reasoning(&mut body, Wire::Anthropic);
1522
1523        assert_eq!(body["thinking"]["budget_tokens"], 4096);
1524        assert!(!body.contains_key("temperature"), "{body:?}");
1525        assert!(!body.contains_key("top_p"), "{body:?}");
1526    }
1527
1528    #[test]
1529    fn a_body_that_asked_for_no_reasoning_is_left_alone() {
1530        let before = serde_json::json!({
1531            "model": "claude-sonnet-5", "max_tokens": 1024, "temperature": 0.7,
1532        });
1533        let mut body = obj(before.clone());
1534
1535        normalize_reasoning(&mut body, Wire::Anthropic);
1536
1537        assert_eq!(
1538            Value::Object(body),
1539            before,
1540            "no reasoning request, no rewrite"
1541        );
1542    }
1543
1544    #[test]
1545    fn gemini_gets_a_nested_budget_not_a_top_level_one() {
1546        let mut body = obj(serde_json::json!({
1547            "contents": [], "generationConfig": { "maxOutputTokens": 4096 },
1548            "reasoning_effort": "low",
1549        }));
1550
1551        normalize_reasoning(&mut body, Wire::Gemini);
1552
1553        assert_eq!(
1554            body["generationConfig"]["thinkingConfig"]["thinkingBudget"],
1555            1024
1556        );
1557        assert_eq!(
1558            body["generationConfig"]["maxOutputTokens"], 4096,
1559            "must not clobber the rest of generationConfig"
1560        );
1561        assert!(
1562            !body.contains_key("thinkingConfig"),
1563            "top level is wrong for Gemini"
1564        );
1565    }
1566
1567    #[test]
1568    fn a_same_dialect_body_is_never_rewritten_even_when_the_caller_got_it_wrong() {
1569        // budget_tokens(1024) > max_tokens(512) is invalid at Anthropic — and this request is
1570        // already Anthropic-spelled, so it is not ours to "fix". Rewriting it would serve a
1571        // different request than the caller wrote and hide the error that explains why.
1572        let before = serde_json::json!({
1573            "max_tokens": 512,
1574            "thinking": { "type": "enabled", "budget_tokens": 1024 },
1575        });
1576        let mut body = obj(before.clone());
1577
1578        normalize_reasoning(&mut body, Wire::Anthropic);
1579
1580        assert_eq!(Value::Object(body), before);
1581    }
1582
1583    #[test]
1584    fn disabled_thinking_is_not_read_as_a_request_to_think() {
1585        let body = obj(serde_json::json!({
1586            "thinking": { "type": "disabled", "budget_tokens": 16384 },
1587        }));
1588        assert_eq!(read_effort(&body), None);
1589    }
1590
1591    #[test]
1592    fn a_cached_response_reports_its_cache_tokens_not_just_the_remainder() {
1593        // A real cached Claude Code turn: the prompt is in the cache counters, and `input_tokens`
1594        // is the small uncached remainder. Reading only `input_tokens` — which this did — is how a
1595        // ~$0.70 call banked a receipt reading a fraction of a cent.
1596        let json = serde_json::json!({
1597            "content": [{ "type": "text", "text": "ok" }],
1598            "usage": {
1599                "input_tokens": 20,
1600                "cache_creation_input_tokens": 190_000,
1601                "cache_read_input_tokens": 1_234,
1602                "output_tokens": 400,
1603            },
1604        });
1605
1606        let u = anthropic_parse_response(&json).expect("parses");
1607
1608        assert_eq!(u.in_tokens, 20);
1609        assert_eq!(u.cache_write_tokens, 190_000);
1610        assert_eq!(u.cache_read_tokens, 1_234);
1611        assert_eq!(u.out_tokens, 400);
1612    }
1613
1614    #[test]
1615    fn an_uncached_response_reports_zero_cache_traffic() {
1616        // The overwhelmingly common case must be untouched.
1617        let json = serde_json::json!({
1618            "content": [{ "type": "text", "text": "ok" }],
1619            "usage": { "input_tokens": 1000, "output_tokens": 200 },
1620        });
1621
1622        let u = anthropic_parse_response(&json).expect("parses");
1623
1624        assert_eq!(u.in_tokens, 1000);
1625        assert_eq!(u.cache_write_tokens, 0);
1626        assert_eq!(u.cache_read_tokens, 0);
1627    }
1628
1629    #[test]
1630    fn cache_breakpoints_land_on_the_stable_prefix_only() {
1631        // System prompt and tool definitions are what repeat byte-for-byte across an agent's
1632        // turns. The conversation after them is not cached, and must not be marked.
1633        let mut body = obj(serde_json::json!({
1634            "model": "claude-sonnet-5",
1635            "system": "you are a careful assistant. ".repeat(200),
1636            "tools": [{ "name": "a" }, { "name": "b" }],
1637            "messages": [{ "role": "user", "content": "hi" }],
1638        }));
1639
1640        add_cache_breakpoints(&mut body);
1641
1642        // A bare string system cannot carry cache_control — it must become the block form.
1643        assert_eq!(body["system"][0]["type"], "text");
1644        assert_eq!(body["system"][0]["cache_control"]["type"], "ephemeral");
1645        assert!(
1646            body["system"][0]["text"]
1647                .as_str()
1648                .unwrap()
1649                .starts_with("you are a careful")
1650        );
1651        // Only the LAST tool: a breakpoint marks the end of a prefix, and one per tool would
1652        // spend the write premium several times over for the same prefix.
1653        assert!(body["tools"][0].get("cache_control").is_none());
1654        assert_eq!(body["tools"][1]["cache_control"]["type"], "ephemeral");
1655        assert!(
1656            body["messages"][0].get("cache_control").is_none(),
1657            "the conversation is not the stable prefix"
1658        );
1659    }
1660
1661    #[test]
1662    fn a_prefix_too_small_to_qualify_is_not_marked() {
1663        // Anthropic refuses to cache below a per-model minimum (1024 tokens, 2048 on Haiku), and
1664        // marking a shorter prefix is not merely wasted — it is a request the API can reject.
1665        let mut body = obj(serde_json::json!({
1666            "model": "claude-sonnet-5",
1667            "system": "be terse",
1668            "messages": [{ "role": "user", "content": "hi" }],
1669        }));
1670        let before = body.clone();
1671
1672        add_cache_breakpoints(&mut body);
1673
1674        assert_eq!(body, before, "a two-word system prompt cannot be cached");
1675    }
1676
1677    #[test]
1678    fn a_caller_that_placed_its_own_breakpoints_is_left_alone() {
1679        // They have knowledge of their own prefix that this code does not; adding more would
1680        // exceed Anthropic's breakpoint limit and re-bill the write premium.
1681        let before = serde_json::json!({
1682            "system": [{ "type": "text", "text": "s", "cache_control": { "type": "ephemeral" } }],
1683            "tools": [{ "name": "a" }],
1684        });
1685        let mut body = obj(before.clone());
1686
1687        add_cache_breakpoints(&mut body);
1688
1689        assert_eq!(Value::Object(body), before);
1690    }
1691
1692    #[test]
1693    fn nothing_is_marked_when_there_is_no_stable_prefix() {
1694        let mut body = obj(serde_json::json!({
1695            "model": "claude-sonnet-5",
1696            "messages": [{ "role": "user", "content": "one shot" }],
1697        }));
1698        let before = body.clone();
1699
1700        add_cache_breakpoints(&mut body);
1701
1702        assert_eq!(body, before, "no system, no tools — nothing to cache");
1703    }
1704
1705    #[test]
1706    fn breakpoints_are_off_unless_the_request_asks_for_them() {
1707        // The default path must be byte-identical to before this existed.
1708        let raw = serde_json::json!({
1709            "model": "claude-sonnet-5", "max_tokens": 64,
1710            "system": "a long stable system prefix. ".repeat(200),
1711            "messages": [{ "role": "user", "content": "hi" }],
1712        });
1713        let req = ModelRequest {
1714            model: "anthropic/claude-sonnet-5".to_owned(),
1715            system: Some("a long stable system prefix. ".repeat(200)),
1716            messages: vec![ChatMessage::text("user", "hi")],
1717            max_tokens: 64,
1718            tools: Value::Null,
1719            raw: raw.clone(),
1720            cache_prefix: false,
1721        };
1722
1723        let body = anthropic_wire_body(&req);
1724        assert!(body["system"].is_string(), "unchanged when opted out");
1725
1726        let opted = ModelRequest {
1727            cache_prefix: true,
1728            ..req
1729        };
1730        let body = anthropic_wire_body(&opted);
1731        assert_eq!(body["system"][0]["cache_control"]["type"], "ephemeral");
1732    }
1733
1734    #[test]
1735    fn breakpoints_apply_on_the_normalized_path_too() {
1736        // Found in review. The normalized branch is not a rare fallback — it is what every
1737        // translated request uses, and every CONDENSED one, since condensing clears `raw` on
1738        // purpose. Marking only the raw branch meant `prompt_cache` did nothing for exactly the
1739        // long conversations it exists to pay for.
1740        let req = ModelRequest {
1741            model: "anthropic/claude-sonnet-5".to_owned(),
1742            system: Some("stable prefix. ".repeat(300)),
1743            messages: vec![ChatMessage::text("user", "hi")],
1744            max_tokens: 64,
1745            tools: serde_json::json!([{ "name": "a" }]),
1746            raw: Value::Null, // no raw body → normalized build path
1747            cache_prefix: true,
1748        };
1749
1750        let body = anthropic_wire_body(&req);
1751
1752        assert_eq!(body["system"][0]["cache_control"]["type"], "ephemeral");
1753        assert_eq!(body["tools"][0]["cache_control"]["type"], "ephemeral");
1754    }
1755
1756    #[test]
1757    fn wire_model_strips_the_provider_prefix() {
1758        // Regression: sending "anthropic/claude-haiku-4-5" verbatim 404s at the provider.
1759        assert_eq!(wire_model("anthropic/claude-haiku-4-5"), "claude-haiku-4-5");
1760        assert_eq!(wire_model("openai/gpt-5.5"), "gpt-5.5");
1761        assert_eq!(wire_model("claude-opus-4-8"), "claude-opus-4-8"); // no prefix → unchanged
1762    }
1763
1764    #[test]
1765    fn gemini_request_maps_roles_and_system_instruction() {
1766        let req = ModelRequest {
1767            model: "gemini/gemini-2.0-flash".to_owned(),
1768            system: Some("be terse".to_owned()),
1769            messages: vec![
1770                ChatMessage::text("user", "hi"),
1771                ChatMessage::text("assistant", "hello"),
1772            ],
1773            max_tokens: 256,
1774            tools: Value::Null,
1775            raw: Value::Null,
1776            cache_prefix: false,
1777        };
1778        let body = gemini_request_body(&req);
1779        // System prompt goes in system_instruction, not contents.
1780        assert_eq!(body["system_instruction"]["parts"][0]["text"], "be terse");
1781        assert_eq!(body["generationConfig"]["maxOutputTokens"], 256);
1782        // Anthropic's "assistant" role becomes Gemini's "model"; "user" stays "user".
1783        assert_eq!(body["contents"][0]["role"], "user");
1784        assert_eq!(body["contents"][0]["parts"][0]["text"], "hi");
1785        assert_eq!(body["contents"][1]["role"], "model");
1786        assert_eq!(body["contents"][1]["parts"][0]["text"], "hello");
1787    }
1788
1789    #[test]
1790    fn gemini_response_parses_text_and_usage() {
1791        let json = serde_json::json!({
1792            "candidates": [{ "content": { "role": "model", "parts": [
1793                { "text": "the answer " }, { "text": "is 42" }
1794            ] } }],
1795            "usageMetadata": { "promptTokenCount": 11, "candidatesTokenCount": 4 }
1796        });
1797        let (text, in_tok, out_tok) = gemini_parse_response(&json).unwrap();
1798        assert_eq!(text, "the answer is 42");
1799        assert_eq!(in_tok, 11);
1800        assert_eq!(out_tok, 4);
1801        // A response with no candidates is a decode error, not a fabricated empty answer.
1802        assert!(gemini_parse_response(&serde_json::json!({ "candidates": [] })).is_err());
1803    }
1804
1805    #[test]
1806    fn from_config_wires_the_gemini_dialect() {
1807        let defs = vec![firstpass_core::ProviderDef {
1808            id: "gemini".to_owned(),
1809            dialect: firstpass_core::Dialect::Gemini,
1810            base_url: "https://generativelanguage.googleapis.com".to_owned(),
1811            api_key_env: Some("GEMINI_API_KEY".to_owned()),
1812            auth: firstpass_core::AuthScheme::ApiKey,
1813            region: None,
1814            project: None,
1815        }];
1816        let reg = ProviderRegistry::from_config(
1817            &defs,
1818            "https://api.anthropic.com",
1819            "https://api.openai.com",
1820        );
1821        assert_eq!(reg.get("gemini").unwrap().id(), "gemini");
1822    }
1823
1824    #[test]
1825    fn from_config_registers_custom_providers_alongside_builtins() {
1826        let defs = vec![
1827            firstpass_core::ProviderDef {
1828                id: "groq".to_owned(),
1829                dialect: firstpass_core::Dialect::Openai,
1830                base_url: "https://api.groq.com/openai".to_owned(),
1831                api_key_env: Some("GROQ_API_KEY".to_owned()),
1832                auth: firstpass_core::AuthScheme::ApiKey,
1833                region: None,
1834                project: None,
1835            },
1836            // A custom provider may override a built-in id (e.g. point `openai` at Azure).
1837            firstpass_core::ProviderDef {
1838                id: "openai".to_owned(),
1839                dialect: firstpass_core::Dialect::Openai,
1840                base_url: "https://my-azure.openai.azure.com".to_owned(),
1841                api_key_env: Some("AZURE_OPENAI_KEY".to_owned()),
1842                auth: firstpass_core::AuthScheme::ApiKey,
1843                region: None,
1844                project: None,
1845            },
1846        ];
1847        let reg = ProviderRegistry::from_config(
1848            &defs,
1849            "https://api.anthropic.com",
1850            "https://api.openai.com",
1851        );
1852        // Built-in anthropic is still present; the custom groq resolves and labels itself "groq".
1853        assert_eq!(reg.get("anthropic").unwrap().id(), "anthropic");
1854        assert_eq!(reg.get("groq").unwrap().id(), "groq");
1855        // Unknown provider → None (router fails over rather than guessing).
1856        assert!(reg.get("does-not-exist").is_none());
1857    }
1858
1859    #[test]
1860    fn anthropic_messages_body_omits_model_and_includes_system_only_when_set() {
1861        let req = ModelRequest {
1862            model: "bedrock/anthropic.claude-3-5-haiku".to_owned(),
1863            system: Some("be terse".to_owned()),
1864            messages: vec![
1865                ChatMessage::text("user", "hi"),
1866                ChatMessage {
1867                    role: "assistant".to_owned(),
1868                    content: serde_json::json!([{ "type": "text", "text": "hello" }]),
1869                },
1870            ],
1871            max_tokens: 128,
1872            tools: Value::Null,
1873            raw: Value::Null,
1874            cache_prefix: false,
1875        };
1876        let body = anthropic_messages_body(&req, "bedrock-2023-05-31");
1877        // Model goes in the URL for Bedrock/Vertex, never the body.
1878        assert!(body.get("model").is_none());
1879        assert_eq!(body["anthropic_version"], "bedrock-2023-05-31");
1880        assert_eq!(body["max_tokens"], 128);
1881        assert_eq!(body["system"], "be terse");
1882        assert_eq!(body["messages"][0]["content"], serde_json::json!("hi"));
1883        // Content-block arrays forward verbatim, same as the direct Anthropic adapter (ADR 0005).
1884        assert_eq!(
1885            body["messages"][1]["content"],
1886            serde_json::json!([{ "type": "text", "text": "hello" }])
1887        );
1888
1889        // No system prompt => no `system` key at all (not `null`).
1890        let req_no_system = ModelRequest {
1891            system: None,
1892            ..req
1893        };
1894        let body2 = anthropic_messages_body(&req_no_system, "vertex-2023-10-16");
1895        assert!(body2.get("system").is_none());
1896    }
1897
1898    #[test]
1899    fn bedrock_url_construction_and_missing_region() {
1900        assert_eq!(
1901            bedrock_url("us-east-1", "anthropic.claude-3-5-haiku-20241022-v1:0"),
1902            "https://bedrock-runtime.us-east-1.amazonaws.com/model/anthropic.claude-3-5-haiku-20241022-v1:0/invoke"
1903        );
1904    }
1905
1906    #[tokio::test]
1907    async fn bedrock_complete_errors_without_a_region() {
1908        let provider = BedrockProvider {
1909            id: "bedrock".to_owned(),
1910            region: None,
1911            http: reqwest::Client::new(),
1912        };
1913        let req = ModelRequest {
1914            model: "bedrock/anthropic.claude-3-5-haiku".to_owned(),
1915            system: None,
1916            messages: vec![],
1917            max_tokens: 16,
1918            tools: Value::Null,
1919            raw: Value::Null,
1920            cache_prefix: false,
1921        };
1922        let err = provider.complete(&req, &Auth::default()).await.unwrap_err();
1923        assert!(matches!(err, ProviderError::Transport(_)));
1924    }
1925
1926    #[test]
1927    fn bedrock_signing_produces_a_sigv4_authorization_header() {
1928        // Dummy, non-production credentials — this only proves the *shape* of the signed request
1929        // (algorithm header + host), not cryptographic validity against real AWS (LIVE-UNVERIFIED).
1930        let creds = AwsEnvCredentials {
1931            access_key_id: "AKIDEXAMPLE".to_owned(),
1932            secret_access_key: "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY".to_owned(),
1933            session_token: None,
1934        };
1935        let url = bedrock_url("us-east-1", "anthropic.claude-3-5-haiku");
1936        let body = br#"{"anthropic_version":"bedrock-2023-05-31"}"#;
1937        let signed = sign_bedrock(&url, "us-east-1", body, &creds).unwrap();
1938
1939        let auth_header = signed
1940            .headers()
1941            .get("authorization")
1942            .and_then(|v| v.to_str().ok())
1943            .expect("authorization header present");
1944        assert!(auth_header.starts_with("AWS4-HMAC-SHA256"));
1945
1946        let host_header = signed
1947            .headers()
1948            .get("host")
1949            .and_then(|v| v.to_str().ok())
1950            .expect("host header present");
1951        assert_eq!(host_header, "bedrock-runtime.us-east-1.amazonaws.com");
1952    }
1953
1954    #[test]
1955    fn vertex_url_construction_and_missing_project() {
1956        assert_eq!(
1957            vertex_url("us-central1", "my-project", "claude-3-5-sonnet"),
1958            "https://us-central1-aiplatform.googleapis.com/v1/projects/my-project/locations/us-central1/publishers/anthropic/models/claude-3-5-sonnet:rawPredict"
1959        );
1960    }
1961
1962    #[tokio::test]
1963    async fn vertex_complete_errors_without_a_project() {
1964        let provider = VertexProvider {
1965            id: "vertex".to_owned(),
1966            region: Some("us-central1".to_owned()),
1967            project: None,
1968            http: reqwest::Client::new(),
1969        };
1970        let req = ModelRequest {
1971            model: "vertex/claude-3-5-sonnet".to_owned(),
1972            system: None,
1973            messages: vec![],
1974            max_tokens: 16,
1975            tools: Value::Null,
1976            raw: Value::Null,
1977            cache_prefix: false,
1978        };
1979        let err = provider.complete(&req, &Auth::default()).await.unwrap_err();
1980        assert!(matches!(err, ProviderError::Transport(_)));
1981    }
1982
1983    #[test]
1984    fn from_config_wires_bedrock_and_vertex_auth_schemes() {
1985        let defs = vec![
1986            firstpass_core::ProviderDef {
1987                id: "bedrock".to_owned(),
1988                dialect: firstpass_core::Dialect::Anthropic,
1989                base_url: String::new(),
1990                api_key_env: None,
1991                auth: firstpass_core::AuthScheme::AwsSigv4,
1992                region: Some("us-east-1".to_owned()),
1993                project: None,
1994            },
1995            firstpass_core::ProviderDef {
1996                id: "vertex".to_owned(),
1997                dialect: firstpass_core::Dialect::Anthropic,
1998                base_url: String::new(),
1999                api_key_env: None,
2000                auth: firstpass_core::AuthScheme::GcpOauth,
2001                region: Some("us-central1".to_owned()),
2002                project: Some("my-project".to_owned()),
2003            },
2004        ];
2005        let reg = ProviderRegistry::from_config(
2006            &defs,
2007            "https://api.anthropic.com",
2008            "https://api.openai.com",
2009        );
2010        assert_eq!(reg.get("bedrock").unwrap().id(), "bedrock");
2011        assert_eq!(reg.get("vertex").unwrap().id(), "vertex");
2012    }
2013
2014    #[test]
2015    fn resolve_api_key_prefers_configured_env_then_byok() {
2016        // Use PATH (always present) to exercise the env branch without mutating process env.
2017        let path = std::env::var("PATH").expect("PATH is set");
2018        // Configured env wins over any BYOK override (the env var is *this* provider's key).
2019        assert_eq!(resolve_api_key(Some("PATH"), Some("byok")), path);
2020        // An unset configured env → fall back to the per-request BYOK override.
2021        assert_eq!(
2022            resolve_api_key(Some("FIRSTPASS_DEFINITELY_UNSET_KEY"), Some("byok")),
2023            "byok"
2024        );
2025        // No configured env → fall back to BYOK.
2026        assert_eq!(resolve_api_key(None, Some("byok")), "byok");
2027        // Neither → empty (keyless local endpoint).
2028        assert_eq!(resolve_api_key(None, None), "");
2029    }
2030
2031    #[test]
2032    fn anthropic_wire_forwards_tool_and_image_content_verbatim() {
2033        // ADR 0005 I3 (request side): the Anthropic adapter serializes tool_use / tool_result /
2034        // image content blocks byte-for-byte into the wire body — enforce forwards them, it does not
2035        // flatten them. A plain-string message still serializes as a bare string (I1).
2036        let messages = vec![
2037            ChatMessage::text("user", "hi"),
2038            ChatMessage {
2039                role: "assistant".to_owned(),
2040                content: serde_json::json!([
2041                    { "type": "tool_use", "id": "t1", "name": "calc", "input": { "x": 1 } }
2042                ]),
2043            },
2044            ChatMessage {
2045                role: "user".to_owned(),
2046                content: serde_json::json!([
2047                    { "type": "tool_result", "tool_use_id": "t1", "content": "2" },
2048                    { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "AA==" } }
2049                ]),
2050            },
2051        ];
2052        let wire = anthropic_wire_body(&ModelRequest {
2053            model: "anthropic/claude-haiku-4-5".to_owned(),
2054            system: None,
2055            messages,
2056            max_tokens: 64,
2057            tools: Value::Null,
2058            raw: Value::Null,
2059            cache_prefix: false,
2060        });
2061        assert_eq!(wire["messages"][0]["content"], serde_json::json!("hi"));
2062        assert_eq!(
2063            wire["messages"][1]["content"],
2064            serde_json::json!([{ "type": "tool_use", "id": "t1", "name": "calc", "input": { "x": 1 } }])
2065        );
2066        assert_eq!(
2067            wire["messages"][2]["content"],
2068            serde_json::json!([
2069                { "type": "tool_result", "tool_use_id": "t1", "content": "2" },
2070                { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "AA==" } }
2071            ])
2072        );
2073    }
2074
2075    fn resp(model: &str, text: &str) -> ModelResponse {
2076        ModelResponse {
2077            model: model.to_owned(),
2078            text: text.to_owned(),
2079            in_tokens: 10,
2080            cache_write_tokens: 0,
2081            cache_read_tokens: 0,
2082            out_tokens: 5,
2083            raw: Value::Null,
2084        }
2085    }
2086
2087    #[test]
2088    fn transport_and_5xx_are_failover_eligible() {
2089        assert!(ProviderError::Transport("boom".into()).is_failover_eligible());
2090        assert!(
2091            ProviderError::Http {
2092                status: 503,
2093                body: String::new()
2094            }
2095            .is_failover_eligible()
2096        );
2097    }
2098
2099    #[test]
2100    fn client_errors_and_decode_failures_are_hard() {
2101        assert!(
2102            !ProviderError::Http {
2103                status: 400,
2104                body: String::new()
2105            }
2106            .is_failover_eligible()
2107        );
2108        assert!(!ProviderError::Decode("bad json".into()).is_failover_eligible());
2109    }
2110
2111    #[test]
2112    fn auth_debug_never_prints_key_material() {
2113        let auth = Auth {
2114            anthropic_key: Some("sk-ant-super-secret".to_owned()),
2115            openai_key: Some("sk-oai-super-secret".to_owned()),
2116        };
2117        let debug = format!("{auth:?}");
2118        assert!(!debug.contains("super-secret"));
2119    }
2120
2121    #[tokio::test]
2122    async fn mock_provider_returns_configured_outcome() {
2123        let mut outcomes = HashMap::new();
2124        outcomes.insert(
2125            "anthropic/claude-haiku-4-5".to_owned(),
2126            Ok(resp("anthropic/claude-haiku-4-5", "hello")),
2127        );
2128        let provider = MockProvider::new("anthropic", outcomes);
2129        let req = ModelRequest {
2130            model: "anthropic/claude-haiku-4-5".to_owned(),
2131            system: None,
2132            messages: vec![],
2133            max_tokens: 100,
2134            tools: Value::Null,
2135            raw: Value::Null,
2136            cache_prefix: false,
2137        };
2138        let out = provider.complete(&req, &Auth::default()).await.unwrap();
2139        assert_eq!(out.text, "hello");
2140    }
2141
2142    #[test]
2143    fn anthropic_wire_body_carries_raw_request_verbatim() {
2144        // ADR 0005: with a raw inbound body present, the wire request IS that body — every field
2145        // the caller set (tools, tool_choice, temperature, thinking, ...) survives; only `model`
2146        // is swapped to the rung's wire id and `stream` is stripped (complete() buffers to gate).
2147        let raw = serde_json::json!({
2148            "model": "claude-opus-4-8",
2149            "stream": true,
2150            "max_tokens": 512,
2151            "temperature": 0.2,
2152            "tool_choice": { "type": "auto" },
2153            "tools": [{ "name": "get_weather", "input_schema": { "type": "object" } }],
2154            "thinking": { "type": "enabled", "budget_tokens": 1024 },
2155            "messages": [{ "role": "user", "content": "hi" }]
2156        });
2157        let req = ModelRequest {
2158            model: "anthropic/claude-haiku-4-5".to_owned(),
2159            system: None,
2160            messages: vec![ChatMessage::text("user", "hi")],
2161            max_tokens: 512,
2162            tools: raw["tools"].clone(),
2163            raw: raw.clone(),
2164            cache_prefix: false,
2165        };
2166        let wire = anthropic_wire_body(&req);
2167        assert_eq!(wire["model"], "claude-haiku-4-5", "rung model swapped in");
2168        assert!(wire.get("stream").is_none(), "stream stripped");
2169        for field in [
2170            "temperature",
2171            "tool_choice",
2172            "tools",
2173            "thinking",
2174            "max_tokens",
2175            "messages",
2176        ] {
2177            assert_eq!(
2178                wire[field], raw[field],
2179                "field {field} must survive verbatim"
2180            );
2181        }
2182    }
2183
2184    #[test]
2185    fn bedrock_vertex_body_carries_raw_minus_model_plus_version() {
2186        let raw = serde_json::json!({
2187            "model": "claude-haiku-4-5",
2188            "stream": true,
2189            "max_tokens": 64,
2190            "tools": [{ "name": "t" }],
2191            "messages": [{ "role": "user", "content": "hi" }]
2192        });
2193        let req = ModelRequest {
2194            model: "bedrock/anthropic.claude-haiku".to_owned(),
2195            system: None,
2196            messages: vec![ChatMessage::text("user", "hi")],
2197            max_tokens: 64,
2198            tools: raw["tools"].clone(),
2199            raw: raw.clone(),
2200            cache_prefix: false,
2201        };
2202        let body = anthropic_messages_body(&req, "bedrock-2023-05-31");
2203        assert!(body.get("model").is_none(), "model lives in the URL");
2204        assert!(body.get("stream").is_none());
2205        assert_eq!(body["anthropic_version"], "bedrock-2023-05-31");
2206        assert_eq!(body["tools"], raw["tools"]);
2207        assert_eq!(body["messages"], raw["messages"]);
2208    }
2209
2210    #[test]
2211    fn verbatim_carriers_are_dialect_aware() {
2212        use firstpass_core::Dialect;
2213        let reg = ProviderRegistry::new("http://localhost", "http://localhost");
2214        // Anthropic provider: verbatim for Anthropic inbound, not for OpenAI
2215        assert!(
2216            reg.get("anthropic")
2217                .unwrap()
2218                .carries_structured_verbatim(Dialect::Anthropic)
2219        );
2220        assert!(
2221            !reg.get("anthropic")
2222                .unwrap()
2223                .carries_structured_verbatim(Dialect::Openai)
2224        );
2225        // OpenAI provider: verbatim for OpenAI inbound, not for Anthropic
2226        assert!(
2227            reg.get("openai")
2228                .unwrap()
2229                .carries_structured_verbatim(Dialect::Openai)
2230        );
2231        assert!(
2232            !reg.get("openai")
2233                .unwrap()
2234                .carries_structured_verbatim(Dialect::Anthropic)
2235        );
2236    }
2237
2238    #[test]
2239    fn openai_wire_body_carries_raw_request_verbatim() {
2240        // All-OpenAI-ladder raw carry: same semantics as anthropic_wire_body_carries_raw_request_verbatim.
2241        let raw = serde_json::json!({
2242            "model": "gpt-4o",
2243            "stream": true,
2244            "max_tokens": 256,
2245            "temperature": 0.7,
2246            "response_format": { "type": "json_object" },
2247            "tool_choice": "auto",
2248            "tools": [{ "type": "function", "function": { "name": "get_weather", "parameters": {} } }],
2249            "messages": [{ "role": "user", "content": "hi" }]
2250        });
2251        let req = ModelRequest {
2252            model: "openai/gpt-4.1-mini".to_owned(),
2253            system: None,
2254            messages: vec![ChatMessage::text("user", "hi")],
2255            max_tokens: 256,
2256            tools: Value::Null,
2257            raw: raw.clone(),
2258            cache_prefix: false,
2259        };
2260        let wire = openai_wire_body(&req);
2261        assert_eq!(wire["model"], "gpt-4.1-mini", "rung model swapped in");
2262        assert!(wire.get("stream").is_none(), "stream stripped");
2263        for field in [
2264            "temperature",
2265            "tool_choice",
2266            "tools",
2267            "response_format",
2268            "messages",
2269            "max_tokens",
2270        ] {
2271            assert_eq!(
2272                wire[field], raw[field],
2273                "field {field} must survive verbatim"
2274            );
2275        }
2276    }
2277
2278    #[test]
2279    fn openai_wire_body_falls_back_to_normalized_fields() {
2280        // Translation path (raw = Null): reconstruct from normalized fields.
2281        let req = ModelRequest {
2282            model: "openai/gpt-4.1-mini".to_owned(),
2283            system: Some("be terse".to_owned()),
2284            messages: vec![
2285                ChatMessage::text("user", "hello"),
2286                ChatMessage::text("assistant", "hi"),
2287            ],
2288            max_tokens: 128,
2289            tools: Value::Null,
2290            raw: Value::Null,
2291            cache_prefix: false,
2292        };
2293        let wire = openai_wire_body(&req);
2294        assert_eq!(wire["model"], "gpt-4.1-mini");
2295        // System → injected as first message with role="system"
2296        assert_eq!(wire["messages"][0]["role"], "system");
2297        assert_eq!(wire["messages"][0]["content"], "be terse");
2298        assert_eq!(wire["messages"][1]["role"], "user");
2299        assert_eq!(wire["messages"][2]["role"], "assistant");
2300    }
2301}