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
1271/// OpenAI-compatible providers registered out of the box: `(id, base_url, api_key_env)`.
1272///
1273/// Every one of these speaks the OpenAI Chat Completions wire format, so a ladder can name
1274/// `groq/…` or `deepseek/…` without a `[[provider]]` block. A user block with the same id still
1275/// wins — this is a default, not a lock.
1276///
1277/// **Endpoints only, deliberately no prices.** A base URL is a stable fact; a price is not. Model
1278/// pricing on these platforms changes without notice, and a stale built-in price would write a
1279/// wrong `cost_usd` into a tamper-evident receipt and quietly mis-feed `[budget]` caps — the exact
1280/// defect class 0.4.0 shipped a breaking change to eliminate. So a rung on one of these providers
1281/// still requires an explicit `[[price]]`, and `Config::parse` refuses to start without it, naming
1282/// the model and printing the block to paste. Declaring the number you are actually billed is a
1283/// second of work; discovering months later that every receipt was wrong is not.
1284///
1285/// A self-hosted runtime (Ollama, vLLM, LM Studio) has no key and no fixed host, so it stays a
1286/// `[[provider]]` block: guessing `localhost:11434` for someone would be a default that silently
1287/// points at the wrong machine.
1288const BUILTIN_OPENAI_COMPATIBLE: &[(&str, &str, &str)] = &[
1289    ("groq", "https://api.groq.com/openai", "GROQ_API_KEY"),
1290    ("deepseek", "https://api.deepseek.com", "DEEPSEEK_API_KEY"),
1291    ("together", "https://api.together.xyz", "TOGETHER_API_KEY"),
1292    (
1293        "fireworks",
1294        "https://api.fireworks.ai/inference",
1295        "FIREWORKS_API_KEY",
1296    ),
1297    ("mistral", "https://api.mistral.ai", "MISTRAL_API_KEY"),
1298    (
1299        "openrouter",
1300        "https://openrouter.ai/api",
1301        "OPENROUTER_API_KEY",
1302    ),
1303    ("xai", "https://api.x.ai", "XAI_API_KEY"),
1304    ("cerebras", "https://api.cerebras.ai", "CEREBRAS_API_KEY"),
1305];
1306
1307/// The env var a built-in OpenAI-compatible provider reads its key from, if `id` is one.
1308///
1309/// Exposed so `doctor` can report a missing key at setup time rather than letting the first real
1310/// request discover it.
1311#[must_use]
1312pub fn builtin_key_env(id: &str) -> Option<&'static str> {
1313    BUILTIN_OPENAI_COMPATIBLE
1314        .iter()
1315        .find(|(p, _, _)| *p == id)
1316        .map(|(_, _, k)| *k)
1317}
1318
1319impl ProviderRegistry {
1320    /// One HTTP client shared by every provider. The enforce path is request/response (never
1321    /// streamed through the adapter), so it carries a total request timeout as well as a connect
1322    /// timeout — a hung or slow upstream can't pin a routing decision indefinitely. Falls back to a
1323    /// default client if the builder fails (only on TLS backend init, which is fatal anyway).
1324    fn build_http_client() -> reqwest::Client {
1325        reqwest::Client::builder()
1326            .connect_timeout(std::time::Duration::from_secs(10))
1327            .timeout(std::time::Duration::from_secs(120))
1328            .build()
1329            .unwrap_or_else(|_| reqwest::Client::new())
1330    }
1331
1332    /// Build the standard registry: the built-in `anthropic` + `openai` providers.
1333    #[must_use]
1334    pub fn new(anthropic_base: impl Into<String>, openai_base: impl Into<String>) -> Self {
1335        Self::from_config(&[], anthropic_base, openai_base)
1336    }
1337
1338    /// Build the registry with the built-in `anthropic` / `openai` providers plus every configured
1339    /// `[[provider]]` entry — so a ladder can route to any OpenAI-compatible or Anthropic-compatible
1340    /// endpoint (Groq, Together, Fireworks, DeepSeek, Mistral, xAI, OpenRouter, Ollama, vLLM, Azure,
1341    /// …) by id. A `[[provider]]` whose id is `anthropic` or `openai` overrides the built-in default
1342    /// (e.g. to point `openai` at Azure). Shares one HTTP client across all of them.
1343    #[must_use]
1344    pub fn from_config(
1345        defs: &[firstpass_core::ProviderDef],
1346        anthropic_base: impl Into<String>,
1347        openai_base: impl Into<String>,
1348    ) -> Self {
1349        let http = Self::build_http_client();
1350        let mut providers: HashMap<String, Arc<dyn Provider>> = HashMap::new();
1351        providers.insert(
1352            "anthropic".to_owned(),
1353            Arc::new(AnthropicProvider {
1354                id: "anthropic".to_owned(),
1355                base_url: anthropic_base.into(),
1356                api_key_env: None,
1357                http: http.clone(),
1358            }),
1359        );
1360        providers.insert(
1361            "openai".to_owned(),
1362            Arc::new(OpenAiProvider {
1363                id: "openai".to_owned(),
1364                base_url: openai_base.into(),
1365                api_key_env: None,
1366                http: http.clone(),
1367            }),
1368        );
1369        // Registered BEFORE user `[[provider]]` blocks so an explicit definition overrides the
1370        // built-in — an operator pointing `groq` at a proxy of their own must win over our default.
1371        for (id, base, key_env) in BUILTIN_OPENAI_COMPATIBLE {
1372            providers.insert(
1373                (*id).to_owned(),
1374                Arc::new(OpenAiProvider {
1375                    id: (*id).to_owned(),
1376                    base_url: (*base).to_owned(),
1377                    api_key_env: Some((*key_env).to_owned()),
1378                    http: http.clone(),
1379                }),
1380            );
1381        }
1382        for def in defs {
1383            // Auth scheme comes first (ADR 0006): `aws_sigv4`/`gcp_oauth` are bespoke-auth
1384            // backends that wrap the Anthropic body shape regardless of `dialect`; `api_key`
1385            // (the default) is today's dialect-driven dispatch, unchanged.
1386            let provider: Arc<dyn Provider> = match def.auth {
1387                firstpass_core::AuthScheme::AwsSigv4 => Arc::new(BedrockProvider {
1388                    id: def.id.clone(),
1389                    region: def.region.clone(),
1390                    http: http.clone(),
1391                }),
1392                firstpass_core::AuthScheme::GcpOauth => Arc::new(VertexProvider {
1393                    id: def.id.clone(),
1394                    region: def.region.clone(),
1395                    project: def.project.clone(),
1396                    http: http.clone(),
1397                }),
1398                firstpass_core::AuthScheme::ApiKey => match def.dialect {
1399                    firstpass_core::Dialect::Anthropic => Arc::new(AnthropicProvider {
1400                        id: def.id.clone(),
1401                        base_url: def.base_url.clone(),
1402                        api_key_env: def.api_key_env.clone(),
1403                        http: http.clone(),
1404                    }),
1405                    firstpass_core::Dialect::Openai => Arc::new(OpenAiProvider {
1406                        id: def.id.clone(),
1407                        base_url: def.base_url.clone(),
1408                        api_key_env: def.api_key_env.clone(),
1409                        http: http.clone(),
1410                    }),
1411                    firstpass_core::Dialect::Gemini => Arc::new(GeminiProvider {
1412                        id: def.id.clone(),
1413                        base_url: def.base_url.clone(),
1414                        api_key_env: def.api_key_env.clone(),
1415                        http: http.clone(),
1416                    }),
1417                },
1418            };
1419            providers.insert(def.id.clone(), provider);
1420        }
1421        Self { providers }
1422    }
1423
1424    /// Build a registry from arbitrary providers — used to wire up [`MockProvider`]s in tests.
1425    #[must_use]
1426    pub fn from_map(providers: HashMap<String, Arc<dyn Provider>>) -> Self {
1427        Self { providers }
1428    }
1429
1430    /// Look up a provider by id.
1431    #[must_use]
1432    pub fn get(&self, provider_id: &str) -> Option<Arc<dyn Provider>> {
1433        self.providers.get(provider_id).cloned()
1434    }
1435}
1436
1437/// Test-only provider: returns a pre-programmed outcome per model, deterministically.
1438#[cfg(test)]
1439#[derive(Debug, Clone, Default)]
1440pub struct MockProvider {
1441    id: String,
1442    outcomes: HashMap<String, Result<ModelResponse, ProviderError>>,
1443    /// Every model string `complete()` was called with — lets speculation tests assert which rungs
1444    /// were actually fired. Shared (`Arc`) so a clone taken before boxing still observes the calls.
1445    calls: Arc<std::sync::Mutex<Vec<String>>>,
1446    /// Simulated per-call latency (0 = respond instantly). Lets a test measure the wall-clock win
1447    /// speculation buys by overlapping rung calls that would otherwise run serially.
1448    delay_ms: u64,
1449}
1450
1451#[cfg(test)]
1452impl MockProvider {
1453    /// Build a mock provider that answers `outcomes[model]` for `complete()`.
1454    #[must_use]
1455    pub fn new(
1456        id: impl Into<String>,
1457        outcomes: HashMap<String, Result<ModelResponse, ProviderError>>,
1458    ) -> Self {
1459        Self {
1460            id: id.into(),
1461            outcomes,
1462            calls: Arc::default(),
1463            delay_ms: 0,
1464        }
1465    }
1466
1467    /// Make `complete()` sleep `ms` before responding, to simulate real per-call latency.
1468    #[must_use]
1469    pub fn with_delay(mut self, ms: u64) -> Self {
1470        self.delay_ms = ms;
1471        self
1472    }
1473
1474    /// A handle to the shared call log; clone it before boxing the provider into a registry, then
1475    /// inspect the models `complete()` saw after the engine runs.
1476    #[must_use]
1477    pub fn call_log(&self) -> Arc<std::sync::Mutex<Vec<String>>> {
1478        Arc::clone(&self.calls)
1479    }
1480}
1481
1482#[cfg(test)]
1483#[async_trait]
1484impl Provider for MockProvider {
1485    fn id(&self) -> &str {
1486        &self.id
1487    }
1488
1489    // ponytail: returns true for all dialects — test-only mock needs to pass the fidelity guard
1490    // for both Anthropic and OpenAI inbound tests without a real dialect-split implementation.
1491    fn carries_structured_verbatim(&self, _inbound: firstpass_core::Dialect) -> bool {
1492        true
1493    }
1494
1495    async fn complete(
1496        &self,
1497        req: &ModelRequest,
1498        _auth: &Auth,
1499    ) -> Result<ModelResponse, ProviderError> {
1500        self.calls.lock().unwrap().push(req.model.clone());
1501        if self.delay_ms > 0 {
1502            tokio::time::sleep(std::time::Duration::from_millis(self.delay_ms)).await;
1503        }
1504        self.outcomes.get(&req.model).cloned().unwrap_or_else(|| {
1505            Err(ProviderError::Decode(format!(
1506                "no mock outcome configured for {}",
1507                req.model
1508            )))
1509        })
1510    }
1511}
1512
1513#[cfg(test)]
1514mod tests {
1515    use super::*;
1516
1517    fn obj(v: Value) -> serde_json::Map<String, Value> {
1518        v.as_object().expect("test literal is an object").clone()
1519    }
1520
1521    #[test]
1522    fn openai_reasoning_effort_crosses_onto_an_anthropic_rung() {
1523        // The bug this exists for: a ladder is routinely cross-vendor, so an OpenAI client that
1524        // set `reasoning_effort` gets escalated onto an Anthropic rung. Forwarded verbatim that
1525        // is a 400 on a request the caller wrote correctly.
1526        let mut body = obj(serde_json::json!({
1527            "model": "claude-sonnet-5", "max_tokens": 8192, "reasoning_effort": "high",
1528        }));
1529
1530        normalize_reasoning(&mut body, Wire::Anthropic);
1531
1532        assert!(
1533            !body.contains_key("reasoning_effort"),
1534            "the foreign spelling must not survive: {body:?}"
1535        );
1536        assert_eq!(body["thinking"]["type"], "enabled");
1537        // Clamped to max_tokens - 1: "high" wants 16384, but Anthropic requires the budget to
1538        // leave room for the answer itself.
1539        assert_eq!(body["thinking"]["budget_tokens"], 8191);
1540    }
1541
1542    #[test]
1543    fn anthropic_thinking_budget_crosses_onto_an_openai_rung_as_a_word() {
1544        let mut body = obj(serde_json::json!({
1545            "model": "gpt-5.5",
1546            "thinking": { "type": "enabled", "budget_tokens": 16384 },
1547        }));
1548
1549        normalize_reasoning(&mut body, Wire::OpenAi);
1550
1551        assert!(!body.contains_key("thinking"));
1552        assert_eq!(body["reasoning_effort"], "high");
1553    }
1554
1555    #[test]
1556    fn thinking_is_dropped_rather_than_sent_invalid_when_max_tokens_cannot_fit_it() {
1557        // Anthropic requires budget >= 1024 AND max_tokens > budget. A caller asking for high
1558        // effort with max_tokens=500 cannot have both; sending it anyway is a 400. Serving
1559        // without extended thinking is the answer the caller can actually use.
1560        let mut body = obj(serde_json::json!({
1561            "model": "claude-sonnet-5", "max_tokens": 500, "reasoning_effort": "high",
1562        }));
1563
1564        normalize_reasoning(&mut body, Wire::Anthropic);
1565
1566        assert!(
1567            !body.contains_key("thinking"),
1568            "must not emit a budget max_tokens cannot satisfy: {body:?}"
1569        );
1570        assert!(!body.contains_key("reasoning_effort"));
1571    }
1572
1573    #[test]
1574    fn enabling_thinking_clears_a_temperature_the_caller_chose_without_knowing() {
1575        // Extended thinking rejects any temperature but the default. The caller set it before the
1576        // router decided to enable thinking, so keeping it would 400.
1577        let mut body = obj(serde_json::json!({
1578            "model": "claude-sonnet-5", "max_tokens": 8192,
1579            "reasoning_effort": "medium", "temperature": 0.2, "top_p": 0.9,
1580        }));
1581
1582        normalize_reasoning(&mut body, Wire::Anthropic);
1583
1584        assert_eq!(body["thinking"]["budget_tokens"], 4096);
1585        assert!(!body.contains_key("temperature"), "{body:?}");
1586        assert!(!body.contains_key("top_p"), "{body:?}");
1587    }
1588
1589    #[test]
1590    fn a_body_that_asked_for_no_reasoning_is_left_alone() {
1591        let before = serde_json::json!({
1592            "model": "claude-sonnet-5", "max_tokens": 1024, "temperature": 0.7,
1593        });
1594        let mut body = obj(before.clone());
1595
1596        normalize_reasoning(&mut body, Wire::Anthropic);
1597
1598        assert_eq!(
1599            Value::Object(body),
1600            before,
1601            "no reasoning request, no rewrite"
1602        );
1603    }
1604
1605    #[test]
1606    fn gemini_gets_a_nested_budget_not_a_top_level_one() {
1607        let mut body = obj(serde_json::json!({
1608            "contents": [], "generationConfig": { "maxOutputTokens": 4096 },
1609            "reasoning_effort": "low",
1610        }));
1611
1612        normalize_reasoning(&mut body, Wire::Gemini);
1613
1614        assert_eq!(
1615            body["generationConfig"]["thinkingConfig"]["thinkingBudget"],
1616            1024
1617        );
1618        assert_eq!(
1619            body["generationConfig"]["maxOutputTokens"], 4096,
1620            "must not clobber the rest of generationConfig"
1621        );
1622        assert!(
1623            !body.contains_key("thinkingConfig"),
1624            "top level is wrong for Gemini"
1625        );
1626    }
1627
1628    #[test]
1629    fn a_same_dialect_body_is_never_rewritten_even_when_the_caller_got_it_wrong() {
1630        // budget_tokens(1024) > max_tokens(512) is invalid at Anthropic — and this request is
1631        // already Anthropic-spelled, so it is not ours to "fix". Rewriting it would serve a
1632        // different request than the caller wrote and hide the error that explains why.
1633        let before = serde_json::json!({
1634            "max_tokens": 512,
1635            "thinking": { "type": "enabled", "budget_tokens": 1024 },
1636        });
1637        let mut body = obj(before.clone());
1638
1639        normalize_reasoning(&mut body, Wire::Anthropic);
1640
1641        assert_eq!(Value::Object(body), before);
1642    }
1643
1644    #[test]
1645    fn disabled_thinking_is_not_read_as_a_request_to_think() {
1646        let body = obj(serde_json::json!({
1647            "thinking": { "type": "disabled", "budget_tokens": 16384 },
1648        }));
1649        assert_eq!(read_effort(&body), None);
1650    }
1651
1652    #[test]
1653    fn a_cached_response_reports_its_cache_tokens_not_just_the_remainder() {
1654        // A real cached Claude Code turn: the prompt is in the cache counters, and `input_tokens`
1655        // is the small uncached remainder. Reading only `input_tokens` — which this did — is how a
1656        // ~$0.70 call banked a receipt reading a fraction of a cent.
1657        let json = serde_json::json!({
1658            "content": [{ "type": "text", "text": "ok" }],
1659            "usage": {
1660                "input_tokens": 20,
1661                "cache_creation_input_tokens": 190_000,
1662                "cache_read_input_tokens": 1_234,
1663                "output_tokens": 400,
1664            },
1665        });
1666
1667        let u = anthropic_parse_response(&json).expect("parses");
1668
1669        assert_eq!(u.in_tokens, 20);
1670        assert_eq!(u.cache_write_tokens, 190_000);
1671        assert_eq!(u.cache_read_tokens, 1_234);
1672        assert_eq!(u.out_tokens, 400);
1673    }
1674
1675    #[test]
1676    fn an_uncached_response_reports_zero_cache_traffic() {
1677        // The overwhelmingly common case must be untouched.
1678        let json = serde_json::json!({
1679            "content": [{ "type": "text", "text": "ok" }],
1680            "usage": { "input_tokens": 1000, "output_tokens": 200 },
1681        });
1682
1683        let u = anthropic_parse_response(&json).expect("parses");
1684
1685        assert_eq!(u.in_tokens, 1000);
1686        assert_eq!(u.cache_write_tokens, 0);
1687        assert_eq!(u.cache_read_tokens, 0);
1688    }
1689
1690    #[test]
1691    fn cache_breakpoints_land_on_the_stable_prefix_only() {
1692        // System prompt and tool definitions are what repeat byte-for-byte across an agent's
1693        // turns. The conversation after them is not cached, and must not be marked.
1694        let mut body = obj(serde_json::json!({
1695            "model": "claude-sonnet-5",
1696            "system": "you are a careful assistant. ".repeat(200),
1697            "tools": [{ "name": "a" }, { "name": "b" }],
1698            "messages": [{ "role": "user", "content": "hi" }],
1699        }));
1700
1701        add_cache_breakpoints(&mut body);
1702
1703        // A bare string system cannot carry cache_control — it must become the block form.
1704        assert_eq!(body["system"][0]["type"], "text");
1705        assert_eq!(body["system"][0]["cache_control"]["type"], "ephemeral");
1706        assert!(
1707            body["system"][0]["text"]
1708                .as_str()
1709                .unwrap()
1710                .starts_with("you are a careful")
1711        );
1712        // Only the LAST tool: a breakpoint marks the end of a prefix, and one per tool would
1713        // spend the write premium several times over for the same prefix.
1714        assert!(body["tools"][0].get("cache_control").is_none());
1715        assert_eq!(body["tools"][1]["cache_control"]["type"], "ephemeral");
1716        assert!(
1717            body["messages"][0].get("cache_control").is_none(),
1718            "the conversation is not the stable prefix"
1719        );
1720    }
1721
1722    #[test]
1723    fn a_prefix_too_small_to_qualify_is_not_marked() {
1724        // Anthropic refuses to cache below a per-model minimum (1024 tokens, 2048 on Haiku), and
1725        // marking a shorter prefix is not merely wasted — it is a request the API can reject.
1726        let mut body = obj(serde_json::json!({
1727            "model": "claude-sonnet-5",
1728            "system": "be terse",
1729            "messages": [{ "role": "user", "content": "hi" }],
1730        }));
1731        let before = body.clone();
1732
1733        add_cache_breakpoints(&mut body);
1734
1735        assert_eq!(body, before, "a two-word system prompt cannot be cached");
1736    }
1737
1738    #[test]
1739    fn a_caller_that_placed_its_own_breakpoints_is_left_alone() {
1740        // They have knowledge of their own prefix that this code does not; adding more would
1741        // exceed Anthropic's breakpoint limit and re-bill the write premium.
1742        let before = serde_json::json!({
1743            "system": [{ "type": "text", "text": "s", "cache_control": { "type": "ephemeral" } }],
1744            "tools": [{ "name": "a" }],
1745        });
1746        let mut body = obj(before.clone());
1747
1748        add_cache_breakpoints(&mut body);
1749
1750        assert_eq!(Value::Object(body), before);
1751    }
1752
1753    #[test]
1754    fn nothing_is_marked_when_there_is_no_stable_prefix() {
1755        let mut body = obj(serde_json::json!({
1756            "model": "claude-sonnet-5",
1757            "messages": [{ "role": "user", "content": "one shot" }],
1758        }));
1759        let before = body.clone();
1760
1761        add_cache_breakpoints(&mut body);
1762
1763        assert_eq!(body, before, "no system, no tools — nothing to cache");
1764    }
1765
1766    #[test]
1767    fn breakpoints_are_off_unless_the_request_asks_for_them() {
1768        // The default path must be byte-identical to before this existed.
1769        let raw = serde_json::json!({
1770            "model": "claude-sonnet-5", "max_tokens": 64,
1771            "system": "a long stable system prefix. ".repeat(200),
1772            "messages": [{ "role": "user", "content": "hi" }],
1773        });
1774        let req = ModelRequest {
1775            model: "anthropic/claude-sonnet-5".to_owned(),
1776            system: Some("a long stable system prefix. ".repeat(200)),
1777            messages: vec![ChatMessage::text("user", "hi")],
1778            max_tokens: 64,
1779            tools: Value::Null,
1780            raw: raw.clone(),
1781            cache_prefix: false,
1782        };
1783
1784        let body = anthropic_wire_body(&req);
1785        assert!(body["system"].is_string(), "unchanged when opted out");
1786
1787        let opted = ModelRequest {
1788            cache_prefix: true,
1789            ..req
1790        };
1791        let body = anthropic_wire_body(&opted);
1792        assert_eq!(body["system"][0]["cache_control"]["type"], "ephemeral");
1793    }
1794
1795    #[test]
1796    fn breakpoints_apply_on_the_normalized_path_too() {
1797        // Found in review. The normalized branch is not a rare fallback — it is what every
1798        // translated request uses, and every CONDENSED one, since condensing clears `raw` on
1799        // purpose. Marking only the raw branch meant `prompt_cache` did nothing for exactly the
1800        // long conversations it exists to pay for.
1801        let req = ModelRequest {
1802            model: "anthropic/claude-sonnet-5".to_owned(),
1803            system: Some("stable prefix. ".repeat(300)),
1804            messages: vec![ChatMessage::text("user", "hi")],
1805            max_tokens: 64,
1806            tools: serde_json::json!([{ "name": "a" }]),
1807            raw: Value::Null, // no raw body → normalized build path
1808            cache_prefix: true,
1809        };
1810
1811        let body = anthropic_wire_body(&req);
1812
1813        assert_eq!(body["system"][0]["cache_control"]["type"], "ephemeral");
1814        assert_eq!(body["tools"][0]["cache_control"]["type"], "ephemeral");
1815    }
1816
1817    #[test]
1818    fn common_openai_compatible_providers_work_without_a_config_block() {
1819        // The breadth gap: a ladder naming `groq/…` previously needed a `[[provider]]` block, so
1820        // "bring your own provider" meant boilerplate before the first request.
1821        let reg = ProviderRegistry::from_config(
1822            &[],
1823            "https://api.anthropic.com",
1824            "https://api.openai.com",
1825        );
1826        for id in [
1827            "groq",
1828            "deepseek",
1829            "together",
1830            "fireworks",
1831            "mistral",
1832            "openrouter",
1833            "xai",
1834            "cerebras",
1835        ] {
1836            assert!(reg.get(id).is_some(), "{id} should be built in");
1837        }
1838        // The originals are untouched.
1839        assert!(reg.get("anthropic").is_some());
1840        assert!(reg.get("openai").is_some());
1841        assert!(reg.get("not-a-provider").is_none());
1842    }
1843
1844    #[test]
1845    fn an_explicit_provider_block_overrides_the_builtin() {
1846        // An operator pointing `groq` at a gateway of their own must win over our default —
1847        // otherwise the built-in silently routes their traffic to the public endpoint instead.
1848        let defs = vec![firstpass_core::ProviderDef {
1849            id: "groq".to_owned(),
1850            base_url: "https://internal.example.com/groq".to_owned(),
1851            api_key_env: Some("MY_KEY".to_owned()),
1852            dialect: firstpass_core::Dialect::Openai,
1853            auth: firstpass_core::AuthScheme::ApiKey,
1854            region: None,
1855            project: None,
1856        }];
1857
1858        let reg = ProviderRegistry::from_config(
1859            &defs,
1860            "https://api.anthropic.com",
1861            "https://api.openai.com",
1862        );
1863
1864        let p = reg.get("groq").expect("groq present");
1865        assert!(
1866            format!("{p:?}").contains("internal.example.com"),
1867            "the explicit block must win: {p:?}"
1868        );
1869    }
1870
1871    #[test]
1872    fn wire_model_strips_the_provider_prefix() {
1873        // Regression: sending "anthropic/claude-haiku-4-5" verbatim 404s at the provider.
1874        assert_eq!(wire_model("anthropic/claude-haiku-4-5"), "claude-haiku-4-5");
1875        assert_eq!(wire_model("openai/gpt-5.5"), "gpt-5.5");
1876        assert_eq!(wire_model("claude-opus-4-8"), "claude-opus-4-8"); // no prefix → unchanged
1877    }
1878
1879    #[test]
1880    fn gemini_request_maps_roles_and_system_instruction() {
1881        let req = ModelRequest {
1882            model: "gemini/gemini-2.0-flash".to_owned(),
1883            system: Some("be terse".to_owned()),
1884            messages: vec![
1885                ChatMessage::text("user", "hi"),
1886                ChatMessage::text("assistant", "hello"),
1887            ],
1888            max_tokens: 256,
1889            tools: Value::Null,
1890            raw: Value::Null,
1891            cache_prefix: false,
1892        };
1893        let body = gemini_request_body(&req);
1894        // System prompt goes in system_instruction, not contents.
1895        assert_eq!(body["system_instruction"]["parts"][0]["text"], "be terse");
1896        assert_eq!(body["generationConfig"]["maxOutputTokens"], 256);
1897        // Anthropic's "assistant" role becomes Gemini's "model"; "user" stays "user".
1898        assert_eq!(body["contents"][0]["role"], "user");
1899        assert_eq!(body["contents"][0]["parts"][0]["text"], "hi");
1900        assert_eq!(body["contents"][1]["role"], "model");
1901        assert_eq!(body["contents"][1]["parts"][0]["text"], "hello");
1902    }
1903
1904    #[test]
1905    fn gemini_response_parses_text_and_usage() {
1906        let json = serde_json::json!({
1907            "candidates": [{ "content": { "role": "model", "parts": [
1908                { "text": "the answer " }, { "text": "is 42" }
1909            ] } }],
1910            "usageMetadata": { "promptTokenCount": 11, "candidatesTokenCount": 4 }
1911        });
1912        let (text, in_tok, out_tok) = gemini_parse_response(&json).unwrap();
1913        assert_eq!(text, "the answer is 42");
1914        assert_eq!(in_tok, 11);
1915        assert_eq!(out_tok, 4);
1916        // A response with no candidates is a decode error, not a fabricated empty answer.
1917        assert!(gemini_parse_response(&serde_json::json!({ "candidates": [] })).is_err());
1918    }
1919
1920    #[test]
1921    fn from_config_wires_the_gemini_dialect() {
1922        let defs = vec![firstpass_core::ProviderDef {
1923            id: "gemini".to_owned(),
1924            dialect: firstpass_core::Dialect::Gemini,
1925            base_url: "https://generativelanguage.googleapis.com".to_owned(),
1926            api_key_env: Some("GEMINI_API_KEY".to_owned()),
1927            auth: firstpass_core::AuthScheme::ApiKey,
1928            region: None,
1929            project: None,
1930        }];
1931        let reg = ProviderRegistry::from_config(
1932            &defs,
1933            "https://api.anthropic.com",
1934            "https://api.openai.com",
1935        );
1936        assert_eq!(reg.get("gemini").unwrap().id(), "gemini");
1937    }
1938
1939    #[test]
1940    fn from_config_registers_custom_providers_alongside_builtins() {
1941        let defs = vec![
1942            firstpass_core::ProviderDef {
1943                id: "groq".to_owned(),
1944                dialect: firstpass_core::Dialect::Openai,
1945                base_url: "https://api.groq.com/openai".to_owned(),
1946                api_key_env: Some("GROQ_API_KEY".to_owned()),
1947                auth: firstpass_core::AuthScheme::ApiKey,
1948                region: None,
1949                project: None,
1950            },
1951            // A custom provider may override a built-in id (e.g. point `openai` at Azure).
1952            firstpass_core::ProviderDef {
1953                id: "openai".to_owned(),
1954                dialect: firstpass_core::Dialect::Openai,
1955                base_url: "https://my-azure.openai.azure.com".to_owned(),
1956                api_key_env: Some("AZURE_OPENAI_KEY".to_owned()),
1957                auth: firstpass_core::AuthScheme::ApiKey,
1958                region: None,
1959                project: None,
1960            },
1961        ];
1962        let reg = ProviderRegistry::from_config(
1963            &defs,
1964            "https://api.anthropic.com",
1965            "https://api.openai.com",
1966        );
1967        // Built-in anthropic is still present; the custom groq resolves and labels itself "groq".
1968        assert_eq!(reg.get("anthropic").unwrap().id(), "anthropic");
1969        assert_eq!(reg.get("groq").unwrap().id(), "groq");
1970        // Unknown provider → None (router fails over rather than guessing).
1971        assert!(reg.get("does-not-exist").is_none());
1972    }
1973
1974    #[test]
1975    fn anthropic_messages_body_omits_model_and_includes_system_only_when_set() {
1976        let req = ModelRequest {
1977            model: "bedrock/anthropic.claude-3-5-haiku".to_owned(),
1978            system: Some("be terse".to_owned()),
1979            messages: vec![
1980                ChatMessage::text("user", "hi"),
1981                ChatMessage {
1982                    role: "assistant".to_owned(),
1983                    content: serde_json::json!([{ "type": "text", "text": "hello" }]),
1984                },
1985            ],
1986            max_tokens: 128,
1987            tools: Value::Null,
1988            raw: Value::Null,
1989            cache_prefix: false,
1990        };
1991        let body = anthropic_messages_body(&req, "bedrock-2023-05-31");
1992        // Model goes in the URL for Bedrock/Vertex, never the body.
1993        assert!(body.get("model").is_none());
1994        assert_eq!(body["anthropic_version"], "bedrock-2023-05-31");
1995        assert_eq!(body["max_tokens"], 128);
1996        assert_eq!(body["system"], "be terse");
1997        assert_eq!(body["messages"][0]["content"], serde_json::json!("hi"));
1998        // Content-block arrays forward verbatim, same as the direct Anthropic adapter (ADR 0005).
1999        assert_eq!(
2000            body["messages"][1]["content"],
2001            serde_json::json!([{ "type": "text", "text": "hello" }])
2002        );
2003
2004        // No system prompt => no `system` key at all (not `null`).
2005        let req_no_system = ModelRequest {
2006            system: None,
2007            ..req
2008        };
2009        let body2 = anthropic_messages_body(&req_no_system, "vertex-2023-10-16");
2010        assert!(body2.get("system").is_none());
2011    }
2012
2013    #[test]
2014    fn bedrock_url_construction_and_missing_region() {
2015        assert_eq!(
2016            bedrock_url("us-east-1", "anthropic.claude-3-5-haiku-20241022-v1:0"),
2017            "https://bedrock-runtime.us-east-1.amazonaws.com/model/anthropic.claude-3-5-haiku-20241022-v1:0/invoke"
2018        );
2019    }
2020
2021    #[tokio::test]
2022    async fn bedrock_complete_errors_without_a_region() {
2023        let provider = BedrockProvider {
2024            id: "bedrock".to_owned(),
2025            region: None,
2026            http: reqwest::Client::new(),
2027        };
2028        let req = ModelRequest {
2029            model: "bedrock/anthropic.claude-3-5-haiku".to_owned(),
2030            system: None,
2031            messages: vec![],
2032            max_tokens: 16,
2033            tools: Value::Null,
2034            raw: Value::Null,
2035            cache_prefix: false,
2036        };
2037        let err = provider.complete(&req, &Auth::default()).await.unwrap_err();
2038        assert!(matches!(err, ProviderError::Transport(_)));
2039    }
2040
2041    #[test]
2042    fn bedrock_signing_produces_a_sigv4_authorization_header() {
2043        // Dummy, non-production credentials — this only proves the *shape* of the signed request
2044        // (algorithm header + host), not cryptographic validity against real AWS (LIVE-UNVERIFIED).
2045        let creds = AwsEnvCredentials {
2046            access_key_id: "AKIDEXAMPLE".to_owned(),
2047            secret_access_key: "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY".to_owned(),
2048            session_token: None,
2049        };
2050        let url = bedrock_url("us-east-1", "anthropic.claude-3-5-haiku");
2051        let body = br#"{"anthropic_version":"bedrock-2023-05-31"}"#;
2052        let signed = sign_bedrock(&url, "us-east-1", body, &creds).unwrap();
2053
2054        let auth_header = signed
2055            .headers()
2056            .get("authorization")
2057            .and_then(|v| v.to_str().ok())
2058            .expect("authorization header present");
2059        assert!(auth_header.starts_with("AWS4-HMAC-SHA256"));
2060
2061        let host_header = signed
2062            .headers()
2063            .get("host")
2064            .and_then(|v| v.to_str().ok())
2065            .expect("host header present");
2066        assert_eq!(host_header, "bedrock-runtime.us-east-1.amazonaws.com");
2067    }
2068
2069    #[test]
2070    fn vertex_url_construction_and_missing_project() {
2071        assert_eq!(
2072            vertex_url("us-central1", "my-project", "claude-3-5-sonnet"),
2073            "https://us-central1-aiplatform.googleapis.com/v1/projects/my-project/locations/us-central1/publishers/anthropic/models/claude-3-5-sonnet:rawPredict"
2074        );
2075    }
2076
2077    #[tokio::test]
2078    async fn vertex_complete_errors_without_a_project() {
2079        let provider = VertexProvider {
2080            id: "vertex".to_owned(),
2081            region: Some("us-central1".to_owned()),
2082            project: None,
2083            http: reqwest::Client::new(),
2084        };
2085        let req = ModelRequest {
2086            model: "vertex/claude-3-5-sonnet".to_owned(),
2087            system: None,
2088            messages: vec![],
2089            max_tokens: 16,
2090            tools: Value::Null,
2091            raw: Value::Null,
2092            cache_prefix: false,
2093        };
2094        let err = provider.complete(&req, &Auth::default()).await.unwrap_err();
2095        assert!(matches!(err, ProviderError::Transport(_)));
2096    }
2097
2098    #[test]
2099    fn from_config_wires_bedrock_and_vertex_auth_schemes() {
2100        let defs = vec![
2101            firstpass_core::ProviderDef {
2102                id: "bedrock".to_owned(),
2103                dialect: firstpass_core::Dialect::Anthropic,
2104                base_url: String::new(),
2105                api_key_env: None,
2106                auth: firstpass_core::AuthScheme::AwsSigv4,
2107                region: Some("us-east-1".to_owned()),
2108                project: None,
2109            },
2110            firstpass_core::ProviderDef {
2111                id: "vertex".to_owned(),
2112                dialect: firstpass_core::Dialect::Anthropic,
2113                base_url: String::new(),
2114                api_key_env: None,
2115                auth: firstpass_core::AuthScheme::GcpOauth,
2116                region: Some("us-central1".to_owned()),
2117                project: Some("my-project".to_owned()),
2118            },
2119        ];
2120        let reg = ProviderRegistry::from_config(
2121            &defs,
2122            "https://api.anthropic.com",
2123            "https://api.openai.com",
2124        );
2125        assert_eq!(reg.get("bedrock").unwrap().id(), "bedrock");
2126        assert_eq!(reg.get("vertex").unwrap().id(), "vertex");
2127    }
2128
2129    #[test]
2130    fn resolve_api_key_prefers_configured_env_then_byok() {
2131        // Use PATH (always present) to exercise the env branch without mutating process env.
2132        let path = std::env::var("PATH").expect("PATH is set");
2133        // Configured env wins over any BYOK override (the env var is *this* provider's key).
2134        assert_eq!(resolve_api_key(Some("PATH"), Some("byok")), path);
2135        // An unset configured env → fall back to the per-request BYOK override.
2136        assert_eq!(
2137            resolve_api_key(Some("FIRSTPASS_DEFINITELY_UNSET_KEY"), Some("byok")),
2138            "byok"
2139        );
2140        // No configured env → fall back to BYOK.
2141        assert_eq!(resolve_api_key(None, Some("byok")), "byok");
2142        // Neither → empty (keyless local endpoint).
2143        assert_eq!(resolve_api_key(None, None), "");
2144    }
2145
2146    #[test]
2147    fn anthropic_wire_forwards_tool_and_image_content_verbatim() {
2148        // ADR 0005 I3 (request side): the Anthropic adapter serializes tool_use / tool_result /
2149        // image content blocks byte-for-byte into the wire body — enforce forwards them, it does not
2150        // flatten them. A plain-string message still serializes as a bare string (I1).
2151        let messages = vec![
2152            ChatMessage::text("user", "hi"),
2153            ChatMessage {
2154                role: "assistant".to_owned(),
2155                content: serde_json::json!([
2156                    { "type": "tool_use", "id": "t1", "name": "calc", "input": { "x": 1 } }
2157                ]),
2158            },
2159            ChatMessage {
2160                role: "user".to_owned(),
2161                content: serde_json::json!([
2162                    { "type": "tool_result", "tool_use_id": "t1", "content": "2" },
2163                    { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "AA==" } }
2164                ]),
2165            },
2166        ];
2167        let wire = anthropic_wire_body(&ModelRequest {
2168            model: "anthropic/claude-haiku-4-5".to_owned(),
2169            system: None,
2170            messages,
2171            max_tokens: 64,
2172            tools: Value::Null,
2173            raw: Value::Null,
2174            cache_prefix: false,
2175        });
2176        assert_eq!(wire["messages"][0]["content"], serde_json::json!("hi"));
2177        assert_eq!(
2178            wire["messages"][1]["content"],
2179            serde_json::json!([{ "type": "tool_use", "id": "t1", "name": "calc", "input": { "x": 1 } }])
2180        );
2181        assert_eq!(
2182            wire["messages"][2]["content"],
2183            serde_json::json!([
2184                { "type": "tool_result", "tool_use_id": "t1", "content": "2" },
2185                { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "AA==" } }
2186            ])
2187        );
2188    }
2189
2190    fn resp(model: &str, text: &str) -> ModelResponse {
2191        ModelResponse {
2192            model: model.to_owned(),
2193            text: text.to_owned(),
2194            in_tokens: 10,
2195            cache_write_tokens: 0,
2196            cache_read_tokens: 0,
2197            out_tokens: 5,
2198            raw: Value::Null,
2199        }
2200    }
2201
2202    #[test]
2203    fn transport_and_5xx_are_failover_eligible() {
2204        assert!(ProviderError::Transport("boom".into()).is_failover_eligible());
2205        assert!(
2206            ProviderError::Http {
2207                status: 503,
2208                body: String::new()
2209            }
2210            .is_failover_eligible()
2211        );
2212    }
2213
2214    #[test]
2215    fn client_errors_and_decode_failures_are_hard() {
2216        assert!(
2217            !ProviderError::Http {
2218                status: 400,
2219                body: String::new()
2220            }
2221            .is_failover_eligible()
2222        );
2223        assert!(!ProviderError::Decode("bad json".into()).is_failover_eligible());
2224    }
2225
2226    #[test]
2227    fn auth_debug_never_prints_key_material() {
2228        let auth = Auth {
2229            anthropic_key: Some("sk-ant-super-secret".to_owned()),
2230            openai_key: Some("sk-oai-super-secret".to_owned()),
2231        };
2232        let debug = format!("{auth:?}");
2233        assert!(!debug.contains("super-secret"));
2234    }
2235
2236    #[tokio::test]
2237    async fn mock_provider_returns_configured_outcome() {
2238        let mut outcomes = HashMap::new();
2239        outcomes.insert(
2240            "anthropic/claude-haiku-4-5".to_owned(),
2241            Ok(resp("anthropic/claude-haiku-4-5", "hello")),
2242        );
2243        let provider = MockProvider::new("anthropic", outcomes);
2244        let req = ModelRequest {
2245            model: "anthropic/claude-haiku-4-5".to_owned(),
2246            system: None,
2247            messages: vec![],
2248            max_tokens: 100,
2249            tools: Value::Null,
2250            raw: Value::Null,
2251            cache_prefix: false,
2252        };
2253        let out = provider.complete(&req, &Auth::default()).await.unwrap();
2254        assert_eq!(out.text, "hello");
2255    }
2256
2257    #[test]
2258    fn anthropic_wire_body_carries_raw_request_verbatim() {
2259        // ADR 0005: with a raw inbound body present, the wire request IS that body — every field
2260        // the caller set (tools, tool_choice, temperature, thinking, ...) survives; only `model`
2261        // is swapped to the rung's wire id and `stream` is stripped (complete() buffers to gate).
2262        let raw = serde_json::json!({
2263            "model": "claude-opus-4-8",
2264            "stream": true,
2265            "max_tokens": 512,
2266            "temperature": 0.2,
2267            "tool_choice": { "type": "auto" },
2268            "tools": [{ "name": "get_weather", "input_schema": { "type": "object" } }],
2269            "thinking": { "type": "enabled", "budget_tokens": 1024 },
2270            "messages": [{ "role": "user", "content": "hi" }]
2271        });
2272        let req = ModelRequest {
2273            model: "anthropic/claude-haiku-4-5".to_owned(),
2274            system: None,
2275            messages: vec![ChatMessage::text("user", "hi")],
2276            max_tokens: 512,
2277            tools: raw["tools"].clone(),
2278            raw: raw.clone(),
2279            cache_prefix: false,
2280        };
2281        let wire = anthropic_wire_body(&req);
2282        assert_eq!(wire["model"], "claude-haiku-4-5", "rung model swapped in");
2283        assert!(wire.get("stream").is_none(), "stream stripped");
2284        for field in [
2285            "temperature",
2286            "tool_choice",
2287            "tools",
2288            "thinking",
2289            "max_tokens",
2290            "messages",
2291        ] {
2292            assert_eq!(
2293                wire[field], raw[field],
2294                "field {field} must survive verbatim"
2295            );
2296        }
2297    }
2298
2299    #[test]
2300    fn bedrock_vertex_body_carries_raw_minus_model_plus_version() {
2301        let raw = serde_json::json!({
2302            "model": "claude-haiku-4-5",
2303            "stream": true,
2304            "max_tokens": 64,
2305            "tools": [{ "name": "t" }],
2306            "messages": [{ "role": "user", "content": "hi" }]
2307        });
2308        let req = ModelRequest {
2309            model: "bedrock/anthropic.claude-haiku".to_owned(),
2310            system: None,
2311            messages: vec![ChatMessage::text("user", "hi")],
2312            max_tokens: 64,
2313            tools: raw["tools"].clone(),
2314            raw: raw.clone(),
2315            cache_prefix: false,
2316        };
2317        let body = anthropic_messages_body(&req, "bedrock-2023-05-31");
2318        assert!(body.get("model").is_none(), "model lives in the URL");
2319        assert!(body.get("stream").is_none());
2320        assert_eq!(body["anthropic_version"], "bedrock-2023-05-31");
2321        assert_eq!(body["tools"], raw["tools"]);
2322        assert_eq!(body["messages"], raw["messages"]);
2323    }
2324
2325    #[test]
2326    fn verbatim_carriers_are_dialect_aware() {
2327        use firstpass_core::Dialect;
2328        let reg = ProviderRegistry::new("http://localhost", "http://localhost");
2329        // Anthropic provider: verbatim for Anthropic inbound, not for OpenAI
2330        assert!(
2331            reg.get("anthropic")
2332                .unwrap()
2333                .carries_structured_verbatim(Dialect::Anthropic)
2334        );
2335        assert!(
2336            !reg.get("anthropic")
2337                .unwrap()
2338                .carries_structured_verbatim(Dialect::Openai)
2339        );
2340        // OpenAI provider: verbatim for OpenAI inbound, not for Anthropic
2341        assert!(
2342            reg.get("openai")
2343                .unwrap()
2344                .carries_structured_verbatim(Dialect::Openai)
2345        );
2346        assert!(
2347            !reg.get("openai")
2348                .unwrap()
2349                .carries_structured_verbatim(Dialect::Anthropic)
2350        );
2351    }
2352
2353    #[test]
2354    fn openai_wire_body_carries_raw_request_verbatim() {
2355        // All-OpenAI-ladder raw carry: same semantics as anthropic_wire_body_carries_raw_request_verbatim.
2356        let raw = serde_json::json!({
2357            "model": "gpt-4o",
2358            "stream": true,
2359            "max_tokens": 256,
2360            "temperature": 0.7,
2361            "response_format": { "type": "json_object" },
2362            "tool_choice": "auto",
2363            "tools": [{ "type": "function", "function": { "name": "get_weather", "parameters": {} } }],
2364            "messages": [{ "role": "user", "content": "hi" }]
2365        });
2366        let req = ModelRequest {
2367            model: "openai/gpt-4.1-mini".to_owned(),
2368            system: None,
2369            messages: vec![ChatMessage::text("user", "hi")],
2370            max_tokens: 256,
2371            tools: Value::Null,
2372            raw: raw.clone(),
2373            cache_prefix: false,
2374        };
2375        let wire = openai_wire_body(&req);
2376        assert_eq!(wire["model"], "gpt-4.1-mini", "rung model swapped in");
2377        assert!(wire.get("stream").is_none(), "stream stripped");
2378        for field in [
2379            "temperature",
2380            "tool_choice",
2381            "tools",
2382            "response_format",
2383            "messages",
2384            "max_tokens",
2385        ] {
2386            assert_eq!(
2387                wire[field], raw[field],
2388                "field {field} must survive verbatim"
2389            );
2390        }
2391    }
2392
2393    #[test]
2394    fn openai_wire_body_falls_back_to_normalized_fields() {
2395        // Translation path (raw = Null): reconstruct from normalized fields.
2396        let req = ModelRequest {
2397            model: "openai/gpt-4.1-mini".to_owned(),
2398            system: Some("be terse".to_owned()),
2399            messages: vec![
2400                ChatMessage::text("user", "hello"),
2401                ChatMessage::text("assistant", "hi"),
2402            ],
2403            max_tokens: 128,
2404            tools: Value::Null,
2405            raw: Value::Null,
2406            cache_prefix: false,
2407        };
2408        let wire = openai_wire_body(&req);
2409        assert_eq!(wire["model"], "gpt-4.1-mini");
2410        // System → injected as first message with role="system"
2411        assert_eq!(wire["messages"][0]["role"], "system");
2412        assert_eq!(wire["messages"][0]["content"], "be terse");
2413        assert_eq!(wire["messages"][1]["role"], "user");
2414        assert_eq!(wire["messages"][2]["role"], "assistant");
2415    }
2416}