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}
81
82/// A provider-agnostic model response.
83#[derive(Debug, Clone, Serialize, Deserialize)]
84pub struct ModelResponse {
85    /// `provider/model` that produced this response.
86    pub model: String,
87    /// Concatenated text output.
88    pub text: String,
89    /// Input tokens billed.
90    pub in_tokens: u64,
91    /// Output tokens billed.
92    pub out_tokens: u64,
93    /// The raw wire response, kept for debugging/audit — never logged wholesale.
94    pub raw: Value,
95}
96
97/// Failure modes of a provider call.
98#[derive(Debug, Clone, thiserror::Error)]
99pub enum ProviderError {
100    /// The request never got a response (connection failure, timeout).
101    #[error("transport error: {0}")]
102    Transport(String),
103    /// The provider responded with a non-2xx status.
104    #[error("http {status}: {body}")]
105    Http {
106        /// HTTP status code.
107        status: u16,
108        /// Response body (truncated upstream, not by us).
109        body: String,
110    },
111    /// The response body didn't parse into the shape we expected.
112    #[error("decode error: {0}")]
113    Decode(String),
114}
115
116impl ProviderError {
117    /// Whether this failure should trigger cross-rung/cross-provider failover (transport
118    /// errors and 5xx) rather than being treated as a hard, non-retryable error (4xx, decode).
119    #[must_use]
120    pub fn is_failover_eligible(&self) -> bool {
121        match self {
122            ProviderError::Transport(_) => true,
123            ProviderError::Http { status, .. } => *status >= 500,
124            ProviderError::Decode(_) => false,
125        }
126    }
127}
128
129/// BYOK credentials for one request, extracted from headers with env-var fallback.
130///
131/// Never logged or persisted — [`std::fmt::Debug`] redacts both fields.
132#[derive(Clone, Default)]
133pub struct Auth {
134    /// Anthropic API key (`x-api-key` header, or `ANTHROPIC_API_KEY`).
135    pub anthropic_key: Option<String>,
136    /// OpenAI API key (`authorization: Bearer ...` header, or `OPENAI_API_KEY`).
137    pub openai_key: Option<String>,
138}
139
140impl std::fmt::Debug for Auth {
141    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
142        f.debug_struct("Auth")
143            .field("anthropic_key", &self.anthropic_key.as_ref().map(|_| "***"))
144            .field("openai_key", &self.openai_key.as_ref().map(|_| "***"))
145            .finish()
146    }
147}
148
149impl Auth {
150    /// Extract BYOK credentials from request headers, falling back to `ANTHROPIC_API_KEY` /
151    /// `OPENAI_API_KEY` environment variables.
152    #[must_use]
153    pub fn from_headers(headers: &HeaderMap) -> Self {
154        let anthropic_key = headers
155            .get("x-api-key")
156            .and_then(|v| v.to_str().ok())
157            .map(str::to_owned)
158            .or_else(|| std::env::var("ANTHROPIC_API_KEY").ok());
159        let openai_key = headers
160            .get(axum::http::header::AUTHORIZATION)
161            .and_then(|v| v.to_str().ok())
162            .and_then(|v| v.strip_prefix("Bearer "))
163            .map(str::to_owned)
164            .or_else(|| std::env::var("OPENAI_API_KEY").ok());
165        Self {
166            anthropic_key,
167            openai_key,
168        }
169    }
170}
171
172/// A normalized model backend. Implementations translate [`ModelRequest`]/[`ModelResponse`]
173/// to/from one wire API.
174#[async_trait]
175pub trait Provider: Send + Sync + std::fmt::Debug {
176    /// Call the model and normalize the result.
177    ///
178    /// # Errors
179    /// Returns [`ProviderError`] on transport failure, a non-2xx response, or a response
180    /// that doesn't decode into the expected shape.
181    async fn complete(
182        &self,
183        req: &ModelRequest,
184        auth: &Auth,
185    ) -> Result<ModelResponse, ProviderError>;
186
187    /// Provider identity, e.g. `"anthropic"`.
188    fn id(&self) -> &str;
189
190    /// Whether this provider carries structured content (tool_use / tool_result / image blocks
191    /// and top-level `tools`) **verbatim** on the wire for the given *inbound* dialect.
192    ///
193    /// - Anthropic-dialect providers (Anthropic / Bedrock / Vertex) return `true` iff
194    ///   `inbound == Dialect::Anthropic`: the raw inbound body is forwarded with only the model
195    ///   swapped, so every caller field — `tools`, `tool_choice`, `thinking`, … — survives
196    ///   intact (ADR 0005 P4).
197    /// - `OpenAiProvider` returns `true` iff `inbound == Dialect::Openai`: same verbatim-carry
198    ///   rule for all-OpenAI-dialect ladders.
199    /// - All other providers (Gemini, unknown) return `false` — no verbatim-carry built yet.
200    ///
201    /// The enforce path's fidelity guard uses this to decide: verbatim-carry path (all rungs
202    /// return `true` for the inbound dialect), translation path (OpenAI → Anthropic when
203    /// content is translatable), or transparent observe passthrough (safe fallback).
204    fn carries_structured_verbatim(&self, _inbound: firstpass_core::Dialect) -> bool {
205        false
206    }
207}
208
209/// Strip the `provider/` prefix from a ladder model id for the provider's wire API — Anthropic and
210/// OpenAI expect the bare model (`claude-haiku-4-5`), not `anthropic/claude-haiku-4-5`. The full
211/// prefixed id is still what the ladder/trace use; only the wire call is stripped.
212fn wire_model(model: &str) -> &str {
213    model.split_once('/').map_or(model, |(_, m)| m)
214}
215
216/// Resolve the API key for a provider call. A configured `api_key_env` wins (that env var is *this*
217/// provider's key — e.g. `GROQ_API_KEY` for a Groq rung); otherwise fall back to the per-request
218/// BYOK override from headers/env (the built-in `anthropic`/`openai` path). Empty string when
219/// neither is set (a keyless local endpoint).
220fn resolve_api_key(api_key_env: Option<&str>, byok_override: Option<&str>) -> String {
221    api_key_env
222        .and_then(|e| std::env::var(e).ok())
223        .or_else(|| byok_override.map(str::to_owned))
224        .unwrap_or_default()
225}
226
227/// Build the Anthropic Messages wire body for `req`: the original inbound JSON **verbatim** with
228/// only `model` swapped to the rung's wire id and `stream` stripped (`complete` is the buffered
229/// call — the gate needs the whole candidate). Falls back to the normalized fields when there is
230/// no raw body (synthesized judge/consistency requests). Pure, so fidelity is unit-testable.
231#[must_use]
232pub fn anthropic_wire_body(req: &ModelRequest) -> Value {
233    if let Value::Object(raw) = &req.raw {
234        let mut body = raw.clone();
235        body.insert(
236            "model".to_owned(),
237            Value::String(wire_model(&req.model).to_owned()),
238        );
239        body.remove("stream");
240        return Value::Object(body);
241    }
242    let messages: Vec<Value> = req
243        .messages
244        .iter()
245        .map(|m| serde_json::json!({ "role": m.role, "content": m.content }))
246        .collect();
247    let mut body = serde_json::json!({
248        "model": wire_model(&req.model),
249        "max_tokens": req.max_tokens,
250        "messages": messages,
251    });
252    if let Some(system) = req.system.as_deref() {
253        body["system"] = serde_json::json!(system);
254    }
255    if !req.tools.is_null() {
256        body["tools"] = req.tools.clone();
257    }
258    body
259}
260
261/// Speaks `POST {base}/v1/messages` (Anthropic Messages API).
262///
263// LIVE-VERIFIED (2026-07-10): exercised against real Anthropic through the running proxy's enforce
264// path — a haiku completion served end-to-end. The `anthropic/` prefix must be stripped for the
265// wire call (see `wire_model`); sending it verbatim 404s.
266#[derive(Debug, Clone)]
267pub struct AnthropicProvider {
268    /// Ladder prefix / trace label for this provider (usually `"anthropic"`).
269    pub id: String,
270    /// Base URL, e.g. `https://api.anthropic.com`.
271    pub base_url: String,
272    /// Env var the API key is read from when no per-request BYOK header is present. `None` for the
273    /// built-in provider, which resolves the key via [`Auth`] (`x-api-key` header or env).
274    pub api_key_env: Option<String>,
275    /// Shared, connection-pooled HTTP client.
276    pub http: reqwest::Client,
277}
278
279#[async_trait]
280impl Provider for AnthropicProvider {
281    fn id(&self) -> &str {
282        &self.id
283    }
284
285    fn carries_structured_verbatim(&self, inbound: firstpass_core::Dialect) -> bool {
286        inbound == firstpass_core::Dialect::Anthropic
287    }
288
289    async fn complete(
290        &self,
291        req: &ModelRequest,
292        auth: &Auth,
293    ) -> Result<ModelResponse, ProviderError> {
294        let key = resolve_api_key(self.api_key_env.as_deref(), auth.anthropic_key.as_deref());
295        let body = anthropic_wire_body(req);
296
297        let url = format!("{}/v1/messages", self.base_url.trim_end_matches('/'));
298        let resp = self
299            .http
300            .post(url)
301            .header("x-api-key", key)
302            .header("anthropic-version", "2023-06-01")
303            .json(&body)
304            .send()
305            .await
306            .map_err(|e| ProviderError::Transport(e.to_string()))?;
307
308        let status = resp.status();
309        let bytes = resp
310            .bytes()
311            .await
312            .map_err(|e| ProviderError::Transport(e.to_string()))?;
313
314        if !status.is_success() {
315            return Err(ProviderError::Http {
316                status: status.as_u16(),
317                body: String::from_utf8_lossy(&bytes).into_owned(),
318            });
319        }
320
321        let json: Value =
322            serde_json::from_slice(&bytes).map_err(|e| ProviderError::Decode(e.to_string()))?;
323        let (text, in_tokens, out_tokens) = anthropic_parse_response(&json)?;
324
325        Ok(ModelResponse {
326            model: req.model.clone(),
327            text,
328            in_tokens,
329            out_tokens,
330            raw: json,
331        })
332    }
333}
334
335/// Extract `(text, in_tokens, out_tokens)` from an Anthropic Messages API response. Shared by
336/// [`AnthropicProvider`] and every auth scheme that wraps the Anthropic body shape (Bedrock,
337/// Vertex — ADR 0006): they all get the same response back, only the request's auth/URL differ.
338fn anthropic_parse_response(json: &Value) -> Result<(String, u64, u64), ProviderError> {
339    let text = json
340        .get("content")
341        .and_then(Value::as_array)
342        .map(|blocks| {
343            blocks
344                .iter()
345                .filter_map(|b| b.get("text").and_then(Value::as_str))
346                .collect::<Vec<_>>()
347                .join("")
348        })
349        .ok_or_else(|| ProviderError::Decode("missing content[].text".to_owned()))?;
350
351    let in_tokens = json
352        .pointer("/usage/input_tokens")
353        .and_then(Value::as_u64)
354        .unwrap_or(0);
355    let out_tokens = json
356        .pointer("/usage/output_tokens")
357        .and_then(Value::as_u64)
358        .unwrap_or(0);
359
360    Ok((text, in_tokens, out_tokens))
361}
362
363/// Build an Anthropic Messages-shaped request body with the model **omitted** — Bedrock and Vertex
364/// both put the model in the URL, not the body (ADR 0006 P2/P3), unlike direct Anthropic API calls
365/// which need `model` in the body ([`AnthropicWireRequest`]). `anthropic_version` is the dialect
366/// version string each host expects (`bedrock-2023-05-31` / `vertex-2023-10-16`).
367fn anthropic_messages_body(req: &ModelRequest, anthropic_version: &str) -> Value {
368    // Same verbatim-carry rule as `anthropic_wire_body`, adapted to hosts that put the model in
369    // the URL: original inbound JSON minus `model`/`stream`, plus the host's version string.
370    if let Value::Object(raw) = &req.raw {
371        let mut body = raw.clone();
372        body.remove("model");
373        body.remove("stream");
374        body.insert(
375            "anthropic_version".to_owned(),
376            Value::String(anthropic_version.to_owned()),
377        );
378        return Value::Object(body);
379    }
380    let messages: Vec<Value> = req
381        .messages
382        .iter()
383        .map(|m| serde_json::json!({ "role": m.role, "content": m.content }))
384        .collect();
385    let mut body = serde_json::json!({
386        "anthropic_version": anthropic_version,
387        "max_tokens": req.max_tokens,
388        "messages": messages,
389    });
390    if let Some(system) = req.system.as_deref() {
391        body["system"] = serde_json::json!(system);
392    }
393    if !req.tools.is_null() {
394        body["tools"] = req.tools.clone();
395    }
396    body
397}
398
399/// Build the OpenAI Chat Completions wire body for `req`: the original inbound JSON **verbatim**
400/// with only `model` swapped to the rung's wire id and `stream` stripped (analogous to
401/// [`anthropic_wire_body`] for all-OpenAI-dialect ladders). Falls back to the normalized fields
402/// when there is no raw body (synthesized judge/consistency requests, or translation path).
403/// Pure, so fidelity is unit-testable.
404#[must_use]
405pub fn openai_wire_body(req: &ModelRequest) -> Value {
406    if let Value::Object(raw) = &req.raw {
407        let mut body = raw.clone();
408        body.insert(
409            "model".to_owned(),
410            Value::String(wire_model(&req.model).to_owned()),
411        );
412        body.remove("stream");
413        return Value::Object(body);
414    }
415    // Fallback: reconstruct from normalized fields (translation path or synthesized requests).
416    let mut messages: Vec<Value> = Vec::with_capacity(req.messages.len() + 1);
417    if let Some(system) = req.system.as_deref() {
418        messages.push(serde_json::json!({ "role": "system", "content": system }));
419    }
420    messages.extend(
421        req.messages
422            .iter()
423            .map(|m| serde_json::json!({ "role": m.role, "content": m.content })),
424    );
425    let mut body = serde_json::json!({
426        "model": wire_model(&req.model),
427        "max_tokens": req.max_tokens,
428        "messages": messages,
429    });
430    if !req.tools.is_null() {
431        body["tools"] = req.tools.clone();
432    }
433    body
434}
435
436/// Speaks `POST {base}/v1/chat/completions` (OpenAI Chat Completions API).
437///
438// LIVE-UNVERIFIED: the `wire_model` prefix-strip fix is applied here too, but the OpenAI path has
439// not yet been exercised against a real endpoint (only Anthropic has). Verify against a real key
440// before relying on it in production.
441#[derive(Debug, Clone)]
442pub struct OpenAiProvider {
443    /// Ladder prefix / trace label for this provider (`"openai"`, `"groq"`, `"together"`, …).
444    pub id: String,
445    /// Base URL, e.g. `https://api.openai.com` or `https://api.groq.com/openai`.
446    pub base_url: String,
447    /// Env var the API key is read from, e.g. `"GROQ_API_KEY"`. `None` for the built-in `openai`
448    /// provider (resolves via [`Auth`]: `authorization` header or `OPENAI_API_KEY`) and for keyless
449    /// local endpoints (Ollama / vLLM).
450    pub api_key_env: Option<String>,
451    /// Shared, connection-pooled HTTP client.
452    pub http: reqwest::Client,
453}
454
455#[async_trait]
456impl Provider for OpenAiProvider {
457    fn id(&self) -> &str {
458        &self.id
459    }
460
461    fn carries_structured_verbatim(&self, inbound: firstpass_core::Dialect) -> bool {
462        inbound == firstpass_core::Dialect::Openai
463    }
464
465    async fn complete(
466        &self,
467        req: &ModelRequest,
468        auth: &Auth,
469    ) -> Result<ModelResponse, ProviderError> {
470        let key = resolve_api_key(self.api_key_env.as_deref(), auth.openai_key.as_deref());
471        let body = openai_wire_body(req);
472
473        let url = format!(
474            "{}/v1/chat/completions",
475            self.base_url.trim_end_matches('/')
476        );
477        let resp = self
478            .http
479            .post(url)
480            .header(axum::http::header::AUTHORIZATION, format!("Bearer {key}"))
481            .json(&body)
482            .send()
483            .await
484            .map_err(|e| ProviderError::Transport(e.to_string()))?;
485
486        let status = resp.status();
487        let bytes = resp
488            .bytes()
489            .await
490            .map_err(|e| ProviderError::Transport(e.to_string()))?;
491
492        if !status.is_success() {
493            return Err(ProviderError::Http {
494                status: status.as_u16(),
495                body: String::from_utf8_lossy(&bytes).into_owned(),
496            });
497        }
498
499        let json: Value =
500            serde_json::from_slice(&bytes).map_err(|e| ProviderError::Decode(e.to_string()))?;
501
502        // `content` is null for tool-call-only responses; treat as empty text rather than an error.
503        let text = json
504            .pointer("/choices/0/message/content")
505            .and_then(Value::as_str)
506            .unwrap_or("")
507            .to_owned();
508
509        let in_tokens = json
510            .pointer("/usage/prompt_tokens")
511            .and_then(Value::as_u64)
512            .unwrap_or(0);
513        let out_tokens = json
514            .pointer("/usage/completion_tokens")
515            .and_then(Value::as_u64)
516            .unwrap_or(0);
517
518        Ok(ModelResponse {
519            model: req.model.clone(),
520            text,
521            in_tokens,
522            out_tokens,
523            raw: json,
524        })
525    }
526}
527
528/// Build the Gemini `generateContent` request body from a normalized [`ModelRequest`]. Split out
529/// (pure, no I/O) so the translation is unit-tested offline. Gemini uses `contents` with roles
530/// `user` / `model` (not `assistant`) and a separate `system_instruction`; the system prompt and the
531/// per-message text projection ([`ChatMessage::text_view`]) are what we send. Tool/multimodal blocks
532/// for Gemini (its `functionCall` / `functionResponse` / `inlineData` shapes) are a follow-on — this
533/// adapter routes text, matching the OpenAI adapter's current scope.
534fn gemini_request_body(req: &ModelRequest) -> Value {
535    let contents: Vec<Value> = req
536        .messages
537        .iter()
538        .map(|m| {
539            let role = if m.role == "assistant" {
540                "model"
541            } else {
542                "user"
543            };
544            serde_json::json!({ "role": role, "parts": [{ "text": m.text_view() }] })
545        })
546        .collect();
547    let mut body = serde_json::json!({
548        "contents": contents,
549        "generationConfig": { "maxOutputTokens": req.max_tokens },
550    });
551    if let Some(system) = req.system.as_deref() {
552        body["system_instruction"] = serde_json::json!({ "parts": [{ "text": system }] });
553    }
554    body
555}
556
557/// Extract `(text, in_tokens, out_tokens)` from a Gemini `generateContent` response. `text` is the
558/// concatenation of the first candidate's text parts; token counts come from `usageMetadata`.
559fn gemini_parse_response(json: &Value) -> Result<(String, u64, u64), ProviderError> {
560    let parts = json
561        .pointer("/candidates/0/content/parts")
562        .and_then(Value::as_array)
563        .ok_or_else(|| ProviderError::Decode("missing candidates[0].content.parts".to_owned()))?;
564    let text = parts
565        .iter()
566        .filter_map(|p| p.get("text").and_then(Value::as_str))
567        .collect::<Vec<_>>()
568        .join("");
569    let in_tokens = json
570        .pointer("/usageMetadata/promptTokenCount")
571        .and_then(Value::as_u64)
572        .unwrap_or(0);
573    let out_tokens = json
574        .pointer("/usageMetadata/candidatesTokenCount")
575        .and_then(Value::as_u64)
576        .unwrap_or(0);
577    Ok((text, in_tokens, out_tokens))
578}
579
580/// Speaks `POST {base}/v1beta/models/{model}:generateContent` (Google Gemini Generative Language
581/// API). The API key goes in the `x-goog-api-key` header — never the URL query string, so it stays
582/// out of logs and proxies.
583///
584// LIVE-VERIFIED (2026-08-03): served `google/gemini-3.5-flash-lite` end to end through the real
585// proxy against the real endpoint, with a receipt, in the `provider-smoke` matrix. Note the
586// timestamp — that is a claim about a commit, not a standing property.
587#[derive(Debug, Clone)]
588pub struct GeminiProvider {
589    /// Ladder prefix / trace label (usually `"gemini"` or `"google"`).
590    pub id: String,
591    /// Base URL, e.g. `https://generativelanguage.googleapis.com`.
592    pub base_url: String,
593    /// Env var the API key is read from, e.g. `"GEMINI_API_KEY"`.
594    pub api_key_env: Option<String>,
595    /// Shared, connection-pooled HTTP client.
596    pub http: reqwest::Client,
597}
598
599#[async_trait]
600impl Provider for GeminiProvider {
601    fn id(&self) -> &str {
602        &self.id
603    }
604
605    async fn complete(
606        &self,
607        req: &ModelRequest,
608        auth: &Auth,
609    ) -> Result<ModelResponse, ProviderError> {
610        let key = resolve_api_key(self.api_key_env.as_deref(), auth.openai_key.as_deref());
611        let body = gemini_request_body(req);
612        let url = format!(
613            "{}/v1beta/models/{}:generateContent",
614            self.base_url.trim_end_matches('/'),
615            wire_model(&req.model),
616        );
617        let resp = self
618            .http
619            .post(url)
620            .header("x-goog-api-key", key)
621            .json(&body)
622            .send()
623            .await
624            .map_err(|e| ProviderError::Transport(e.to_string()))?;
625
626        let status = resp.status();
627        let bytes = resp
628            .bytes()
629            .await
630            .map_err(|e| ProviderError::Transport(e.to_string()))?;
631        if !status.is_success() {
632            return Err(ProviderError::Http {
633                status: status.as_u16(),
634                body: String::from_utf8_lossy(&bytes).into_owned(),
635            });
636        }
637
638        let json: Value =
639            serde_json::from_slice(&bytes).map_err(|e| ProviderError::Decode(e.to_string()))?;
640        let (text, in_tokens, out_tokens) = gemini_parse_response(&json)?;
641        Ok(ModelResponse {
642            model: req.model.clone(),
643            text,
644            in_tokens,
645            out_tokens,
646            raw: json,
647        })
648    }
649}
650
651/// AWS credentials read fresh from the standard env vars at call time — never cached, never
652/// logged (ADR 0006 P2). `AWS_SESSION_TOKEN` is optional (long-lived IAM user keys have none;
653/// STS-issued temporary credentials do).
654struct AwsEnvCredentials {
655    access_key_id: String,
656    secret_access_key: String,
657    session_token: Option<String>,
658}
659
660impl AwsEnvCredentials {
661    fn from_env() -> Result<Self, ProviderError> {
662        let access_key_id = std::env::var("AWS_ACCESS_KEY_ID")
663            .map_err(|_| ProviderError::Transport("AWS_ACCESS_KEY_ID is not set".to_owned()))?;
664        let secret_access_key = std::env::var("AWS_SECRET_ACCESS_KEY")
665            .map_err(|_| ProviderError::Transport("AWS_SECRET_ACCESS_KEY is not set".to_owned()))?;
666        let session_token = std::env::var("AWS_SESSION_TOKEN").ok();
667        Ok(Self {
668            access_key_id,
669            secret_access_key,
670            session_token,
671        })
672    }
673}
674
675/// Build the Bedrock `invoke` URL for a region + wire model id.
676fn bedrock_url(region: &str, model: &str) -> String {
677    format!("https://bedrock-runtime.{region}.amazonaws.com/model/{model}/invoke")
678}
679
680/// SigV4-sign a Bedrock `InvokeModel` request, returning the fully-built (headers + body) HTTP
681/// request ready to hand to reqwest. Delegates all canonical-request construction and HMAC signing
682/// to `aws-sigv4` (ADR 0006 I3) — this function only wires host/service/region into that crate's
683/// API and applies the resulting signature. Split out from [`BedrockProvider::complete`] so the
684/// signing shape (not its cryptographic validity, which only a real AWS call can prove) is
685/// unit-testable offline with dummy credentials.
686///
687// LIVE-UNVERIFIED: tests assert the produced request carries an `AWS4-HMAC-SHA256` authorization
688// header and the expected host, against dummy credentials. Signature validity is only provable
689// against a real Bedrock endpoint.
690fn sign_bedrock(
691    url: &str,
692    region: &str,
693    body: &[u8],
694    creds: &AwsEnvCredentials,
695) -> Result<http::Request<Vec<u8>>, ProviderError> {
696    let host = url
697        .parse::<http::Uri>()
698        .ok()
699        .and_then(|u| u.host().map(str::to_owned))
700        .ok_or_else(|| ProviderError::Transport(format!("invalid bedrock URL: {url}")))?;
701
702    let identity: aws_smithy_runtime_api::client::identity::Identity =
703        aws_credential_types::Credentials::new(
704            creds.access_key_id.clone(),
705            creds.secret_access_key.clone(),
706            creds.session_token.clone(),
707            None,
708            "firstpass",
709        )
710        .into();
711
712    let signing_params: aws_sigv4::http_request::SigningParams<'_> =
713        aws_sigv4::sign::v4::SigningParams::builder()
714            .identity(&identity)
715            .region(region)
716            .name("bedrock")
717            .time(SystemTime::now())
718            .settings(aws_sigv4::http_request::SigningSettings::default())
719            .build()
720            .map_err(|e| ProviderError::Transport(format!("sigv4 signing params: {e}")))?
721            .into();
722
723    let headers = [
724        ("host", host.as_str()),
725        ("content-type", "application/json"),
726    ];
727    let signable = aws_sigv4::http_request::SignableRequest::new(
728        "POST",
729        url,
730        headers.into_iter(),
731        aws_sigv4::http_request::SignableBody::Bytes(body),
732    )
733    .map_err(|e| ProviderError::Transport(format!("sigv4 signable request: {e}")))?;
734
735    let (instructions, _signature) = aws_sigv4::http_request::sign(signable, &signing_params)
736        .map_err(|e| ProviderError::Transport(format!("sigv4 sign: {e}")))?
737        .into_parts();
738
739    let mut req = http::Request::builder()
740        .method("POST")
741        .uri(url)
742        .header("host", host)
743        .header("content-type", "application/json")
744        .body(body.to_vec())
745        .map_err(|e| ProviderError::Transport(format!("build bedrock request: {e}")))?;
746    instructions.apply_to_request_http1x(&mut req);
747    Ok(req)
748}
749
750/// Speaks `POST https://bedrock-runtime.{region}.amazonaws.com/model/{model}/invoke` (Claude on AWS
751/// Bedrock) — an Anthropic-shaped body ([`anthropic_messages_body`]) authenticated with AWS SigV4
752/// request signing rather than an API key (ADR 0006 P2). Credentials come from the standard
753/// `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN` env vars, read fresh per
754/// call — never logged, never put in the URL (I2).
755///
756// LIVE-UNVERIFIED: the request/response translation and signing call shape are unit-tested
757// offline; this has not been exercised against a real Bedrock endpoint. Verify against real AWS
758// credentials before relying on it in production.
759#[derive(Debug, Clone)]
760pub struct BedrockProvider {
761    /// Ladder prefix / trace label (usually `"bedrock"`).
762    pub id: String,
763    /// AWS region Bedrock is called in, e.g. `"us-east-1"`.
764    pub region: Option<String>,
765    /// Shared, connection-pooled HTTP client.
766    pub http: reqwest::Client,
767}
768
769#[async_trait]
770impl Provider for BedrockProvider {
771    fn id(&self) -> &str {
772        &self.id
773    }
774
775    fn carries_structured_verbatim(&self, inbound: firstpass_core::Dialect) -> bool {
776        inbound == firstpass_core::Dialect::Anthropic
777    }
778
779    async fn complete(
780        &self,
781        req: &ModelRequest,
782        _auth: &Auth,
783    ) -> Result<ModelResponse, ProviderError> {
784        let region = self.region.as_deref().ok_or_else(|| {
785            ProviderError::Transport("bedrock provider requires a region".to_owned())
786        })?;
787        let model = wire_model(&req.model);
788        let url = bedrock_url(region, model);
789        let body = anthropic_messages_body(req, "bedrock-2023-05-31");
790        let body_bytes =
791            serde_json::to_vec(&body).map_err(|e| ProviderError::Decode(e.to_string()))?;
792
793        let creds = AwsEnvCredentials::from_env()?;
794        let signed = sign_bedrock(&url, region, &body_bytes, &creds)?;
795        let http_req = reqwest::Request::try_from(signed)
796            .map_err(|e| ProviderError::Transport(format!("build reqwest request: {e}")))?;
797
798        let resp = self
799            .http
800            .execute(http_req)
801            .await
802            .map_err(|e| ProviderError::Transport(e.to_string()))?;
803
804        let status = resp.status();
805        let bytes = resp
806            .bytes()
807            .await
808            .map_err(|e| ProviderError::Transport(e.to_string()))?;
809        if !status.is_success() {
810            return Err(ProviderError::Http {
811                status: status.as_u16(),
812                body: String::from_utf8_lossy(&bytes).into_owned(),
813            });
814        }
815
816        let json: Value =
817            serde_json::from_slice(&bytes).map_err(|e| ProviderError::Decode(e.to_string()))?;
818        let (text, in_tokens, out_tokens) = anthropic_parse_response(&json)?;
819        Ok(ModelResponse {
820            model: req.model.clone(),
821            text,
822            in_tokens,
823            out_tokens,
824            raw: json,
825        })
826    }
827}
828
829/// Build the Vertex AI `rawPredict` URL for a region + project + wire model id (Claude on Vertex).
830fn vertex_url(region: &str, project: &str, model: &str) -> String {
831    format!(
832        "https://{region}-aiplatform.googleapis.com/v1/projects/{project}/locations/{region}/publishers/anthropic/models/{model}:rawPredict"
833    )
834}
835
836/// Speaks `POST https://{region}-aiplatform.googleapis.com/.../publishers/anthropic/models/{model}:rawPredict`
837/// (Claude on Google Vertex AI) — an Anthropic-shaped body ([`anthropic_messages_body`])
838/// authenticated with a GCP OAuth2 bearer token rather than an API key (ADR 0006 P3). The token is
839/// minted and cached by `gcp_auth` from `GOOGLE_APPLICATION_CREDENTIALS` or the ambient GCP
840/// environment — this adapter never caches or logs it, and it never goes in the URL (I2).
841///
842// LIVE-UNVERIFIED: the request/response translation is unit-tested offline; this has not been
843// exercised against a real Vertex endpoint. Verify against a real service account before relying
844// on it in production.
845#[derive(Debug, Clone)]
846pub struct VertexProvider {
847    /// Ladder prefix / trace label (usually `"vertex"`).
848    pub id: String,
849    /// GCP region Vertex is called in, e.g. `"us-central1"`.
850    pub region: Option<String>,
851    /// GCP project id.
852    pub project: Option<String>,
853    /// Shared, connection-pooled HTTP client.
854    pub http: reqwest::Client,
855}
856
857#[async_trait]
858impl Provider for VertexProvider {
859    fn id(&self) -> &str {
860        &self.id
861    }
862
863    fn carries_structured_verbatim(&self, inbound: firstpass_core::Dialect) -> bool {
864        inbound == firstpass_core::Dialect::Anthropic
865    }
866
867    async fn complete(
868        &self,
869        req: &ModelRequest,
870        _auth: &Auth,
871    ) -> Result<ModelResponse, ProviderError> {
872        let region = self.region.as_deref().ok_or_else(|| {
873            ProviderError::Transport("vertex provider requires a region".to_owned())
874        })?;
875        let project = self.project.as_deref().ok_or_else(|| {
876            ProviderError::Transport("vertex provider requires a project".to_owned())
877        })?;
878        let model = wire_model(&req.model);
879        let url = vertex_url(region, project, model);
880        let body = anthropic_messages_body(req, "vertex-2023-10-16");
881
882        // ponytail: gcp_auth re-detects the auth method per call (the token itself is cached inside
883        // the provider). Cache the provider in a OnceCell if Vertex ever becomes a hot path.
884        let provider = gcp_auth::provider()
885            .await
886            .map_err(|e| ProviderError::Transport(format!("gcp_auth provider: {e}")))?;
887        let token = provider
888            .token(&["https://www.googleapis.com/auth/cloud-platform"])
889            .await
890            .map_err(|e| ProviderError::Transport(format!("gcp_auth token: {e}")))?;
891
892        let resp = self
893            .http
894            .post(url)
895            .header(
896                axum::http::header::AUTHORIZATION,
897                format!("Bearer {}", token.as_str()),
898            )
899            .json(&body)
900            .send()
901            .await
902            .map_err(|e| ProviderError::Transport(e.to_string()))?;
903
904        let status = resp.status();
905        let bytes = resp
906            .bytes()
907            .await
908            .map_err(|e| ProviderError::Transport(e.to_string()))?;
909        if !status.is_success() {
910            return Err(ProviderError::Http {
911                status: status.as_u16(),
912                body: String::from_utf8_lossy(&bytes).into_owned(),
913            });
914        }
915
916        let json: Value =
917            serde_json::from_slice(&bytes).map_err(|e| ProviderError::Decode(e.to_string()))?;
918        let (text, in_tokens, out_tokens) = anthropic_parse_response(&json)?;
919        Ok(ModelResponse {
920            model: req.model.clone(),
921            text,
922            in_tokens,
923            out_tokens,
924            raw: json,
925        })
926    }
927}
928
929/// Lookup from provider id (`"anthropic"`, `"openai"`, ...) to the [`Provider`] that serves it.
930#[derive(Clone)]
931pub struct ProviderRegistry {
932    providers: HashMap<String, Arc<dyn Provider>>,
933}
934
935impl std::fmt::Debug for ProviderRegistry {
936    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
937        f.debug_struct("ProviderRegistry")
938            .field("providers", &self.providers.keys().collect::<Vec<_>>())
939            .finish()
940    }
941}
942
943impl ProviderRegistry {
944    /// One HTTP client shared by every provider. The enforce path is request/response (never
945    /// streamed through the adapter), so it carries a total request timeout as well as a connect
946    /// timeout — a hung or slow upstream can't pin a routing decision indefinitely. Falls back to a
947    /// default client if the builder fails (only on TLS backend init, which is fatal anyway).
948    fn build_http_client() -> reqwest::Client {
949        reqwest::Client::builder()
950            .connect_timeout(std::time::Duration::from_secs(10))
951            .timeout(std::time::Duration::from_secs(120))
952            .build()
953            .unwrap_or_else(|_| reqwest::Client::new())
954    }
955
956    /// Build the standard registry: the built-in `anthropic` + `openai` providers.
957    #[must_use]
958    pub fn new(anthropic_base: impl Into<String>, openai_base: impl Into<String>) -> Self {
959        Self::from_config(&[], anthropic_base, openai_base)
960    }
961
962    /// Build the registry with the built-in `anthropic` / `openai` providers plus every configured
963    /// `[[provider]]` entry — so a ladder can route to any OpenAI-compatible or Anthropic-compatible
964    /// endpoint (Groq, Together, Fireworks, DeepSeek, Mistral, xAI, OpenRouter, Ollama, vLLM, Azure,
965    /// …) by id. A `[[provider]]` whose id is `anthropic` or `openai` overrides the built-in default
966    /// (e.g. to point `openai` at Azure). Shares one HTTP client across all of them.
967    #[must_use]
968    pub fn from_config(
969        defs: &[firstpass_core::ProviderDef],
970        anthropic_base: impl Into<String>,
971        openai_base: impl Into<String>,
972    ) -> Self {
973        let http = Self::build_http_client();
974        let mut providers: HashMap<String, Arc<dyn Provider>> = HashMap::new();
975        providers.insert(
976            "anthropic".to_owned(),
977            Arc::new(AnthropicProvider {
978                id: "anthropic".to_owned(),
979                base_url: anthropic_base.into(),
980                api_key_env: None,
981                http: http.clone(),
982            }),
983        );
984        providers.insert(
985            "openai".to_owned(),
986            Arc::new(OpenAiProvider {
987                id: "openai".to_owned(),
988                base_url: openai_base.into(),
989                api_key_env: None,
990                http: http.clone(),
991            }),
992        );
993        for def in defs {
994            // Auth scheme comes first (ADR 0006): `aws_sigv4`/`gcp_oauth` are bespoke-auth
995            // backends that wrap the Anthropic body shape regardless of `dialect`; `api_key`
996            // (the default) is today's dialect-driven dispatch, unchanged.
997            let provider: Arc<dyn Provider> = match def.auth {
998                firstpass_core::AuthScheme::AwsSigv4 => Arc::new(BedrockProvider {
999                    id: def.id.clone(),
1000                    region: def.region.clone(),
1001                    http: http.clone(),
1002                }),
1003                firstpass_core::AuthScheme::GcpOauth => Arc::new(VertexProvider {
1004                    id: def.id.clone(),
1005                    region: def.region.clone(),
1006                    project: def.project.clone(),
1007                    http: http.clone(),
1008                }),
1009                firstpass_core::AuthScheme::ApiKey => match def.dialect {
1010                    firstpass_core::Dialect::Anthropic => Arc::new(AnthropicProvider {
1011                        id: def.id.clone(),
1012                        base_url: def.base_url.clone(),
1013                        api_key_env: def.api_key_env.clone(),
1014                        http: http.clone(),
1015                    }),
1016                    firstpass_core::Dialect::Openai => Arc::new(OpenAiProvider {
1017                        id: def.id.clone(),
1018                        base_url: def.base_url.clone(),
1019                        api_key_env: def.api_key_env.clone(),
1020                        http: http.clone(),
1021                    }),
1022                    firstpass_core::Dialect::Gemini => Arc::new(GeminiProvider {
1023                        id: def.id.clone(),
1024                        base_url: def.base_url.clone(),
1025                        api_key_env: def.api_key_env.clone(),
1026                        http: http.clone(),
1027                    }),
1028                },
1029            };
1030            providers.insert(def.id.clone(), provider);
1031        }
1032        Self { providers }
1033    }
1034
1035    /// Build a registry from arbitrary providers — used to wire up [`MockProvider`]s in tests.
1036    #[must_use]
1037    pub fn from_map(providers: HashMap<String, Arc<dyn Provider>>) -> Self {
1038        Self { providers }
1039    }
1040
1041    /// Look up a provider by id.
1042    #[must_use]
1043    pub fn get(&self, provider_id: &str) -> Option<Arc<dyn Provider>> {
1044        self.providers.get(provider_id).cloned()
1045    }
1046}
1047
1048/// Test-only provider: returns a pre-programmed outcome per model, deterministically.
1049#[cfg(test)]
1050#[derive(Debug, Clone, Default)]
1051pub struct MockProvider {
1052    id: String,
1053    outcomes: HashMap<String, Result<ModelResponse, ProviderError>>,
1054    /// Every model string `complete()` was called with — lets speculation tests assert which rungs
1055    /// were actually fired. Shared (`Arc`) so a clone taken before boxing still observes the calls.
1056    calls: Arc<std::sync::Mutex<Vec<String>>>,
1057    /// Simulated per-call latency (0 = respond instantly). Lets a test measure the wall-clock win
1058    /// speculation buys by overlapping rung calls that would otherwise run serially.
1059    delay_ms: u64,
1060}
1061
1062#[cfg(test)]
1063impl MockProvider {
1064    /// Build a mock provider that answers `outcomes[model]` for `complete()`.
1065    #[must_use]
1066    pub fn new(
1067        id: impl Into<String>,
1068        outcomes: HashMap<String, Result<ModelResponse, ProviderError>>,
1069    ) -> Self {
1070        Self {
1071            id: id.into(),
1072            outcomes,
1073            calls: Arc::default(),
1074            delay_ms: 0,
1075        }
1076    }
1077
1078    /// Make `complete()` sleep `ms` before responding, to simulate real per-call latency.
1079    #[must_use]
1080    pub fn with_delay(mut self, ms: u64) -> Self {
1081        self.delay_ms = ms;
1082        self
1083    }
1084
1085    /// A handle to the shared call log; clone it before boxing the provider into a registry, then
1086    /// inspect the models `complete()` saw after the engine runs.
1087    #[must_use]
1088    pub fn call_log(&self) -> Arc<std::sync::Mutex<Vec<String>>> {
1089        Arc::clone(&self.calls)
1090    }
1091}
1092
1093#[cfg(test)]
1094#[async_trait]
1095impl Provider for MockProvider {
1096    fn id(&self) -> &str {
1097        &self.id
1098    }
1099
1100    // ponytail: returns true for all dialects — test-only mock needs to pass the fidelity guard
1101    // for both Anthropic and OpenAI inbound tests without a real dialect-split implementation.
1102    fn carries_structured_verbatim(&self, _inbound: firstpass_core::Dialect) -> bool {
1103        true
1104    }
1105
1106    async fn complete(
1107        &self,
1108        req: &ModelRequest,
1109        _auth: &Auth,
1110    ) -> Result<ModelResponse, ProviderError> {
1111        self.calls.lock().unwrap().push(req.model.clone());
1112        if self.delay_ms > 0 {
1113            tokio::time::sleep(std::time::Duration::from_millis(self.delay_ms)).await;
1114        }
1115        self.outcomes.get(&req.model).cloned().unwrap_or_else(|| {
1116            Err(ProviderError::Decode(format!(
1117                "no mock outcome configured for {}",
1118                req.model
1119            )))
1120        })
1121    }
1122}
1123
1124#[cfg(test)]
1125mod tests {
1126    use super::*;
1127
1128    #[test]
1129    fn wire_model_strips_the_provider_prefix() {
1130        // Regression: sending "anthropic/claude-haiku-4-5" verbatim 404s at the provider.
1131        assert_eq!(wire_model("anthropic/claude-haiku-4-5"), "claude-haiku-4-5");
1132        assert_eq!(wire_model("openai/gpt-5.5"), "gpt-5.5");
1133        assert_eq!(wire_model("claude-opus-4-8"), "claude-opus-4-8"); // no prefix → unchanged
1134    }
1135
1136    #[test]
1137    fn gemini_request_maps_roles_and_system_instruction() {
1138        let req = ModelRequest {
1139            model: "gemini/gemini-2.0-flash".to_owned(),
1140            system: Some("be terse".to_owned()),
1141            messages: vec![
1142                ChatMessage::text("user", "hi"),
1143                ChatMessage::text("assistant", "hello"),
1144            ],
1145            max_tokens: 256,
1146            tools: Value::Null,
1147            raw: Value::Null,
1148        };
1149        let body = gemini_request_body(&req);
1150        // System prompt goes in system_instruction, not contents.
1151        assert_eq!(body["system_instruction"]["parts"][0]["text"], "be terse");
1152        assert_eq!(body["generationConfig"]["maxOutputTokens"], 256);
1153        // Anthropic's "assistant" role becomes Gemini's "model"; "user" stays "user".
1154        assert_eq!(body["contents"][0]["role"], "user");
1155        assert_eq!(body["contents"][0]["parts"][0]["text"], "hi");
1156        assert_eq!(body["contents"][1]["role"], "model");
1157        assert_eq!(body["contents"][1]["parts"][0]["text"], "hello");
1158    }
1159
1160    #[test]
1161    fn gemini_response_parses_text_and_usage() {
1162        let json = serde_json::json!({
1163            "candidates": [{ "content": { "role": "model", "parts": [
1164                { "text": "the answer " }, { "text": "is 42" }
1165            ] } }],
1166            "usageMetadata": { "promptTokenCount": 11, "candidatesTokenCount": 4 }
1167        });
1168        let (text, in_tok, out_tok) = gemini_parse_response(&json).unwrap();
1169        assert_eq!(text, "the answer is 42");
1170        assert_eq!(in_tok, 11);
1171        assert_eq!(out_tok, 4);
1172        // A response with no candidates is a decode error, not a fabricated empty answer.
1173        assert!(gemini_parse_response(&serde_json::json!({ "candidates": [] })).is_err());
1174    }
1175
1176    #[test]
1177    fn from_config_wires_the_gemini_dialect() {
1178        let defs = vec![firstpass_core::ProviderDef {
1179            id: "gemini".to_owned(),
1180            dialect: firstpass_core::Dialect::Gemini,
1181            base_url: "https://generativelanguage.googleapis.com".to_owned(),
1182            api_key_env: Some("GEMINI_API_KEY".to_owned()),
1183            auth: firstpass_core::AuthScheme::ApiKey,
1184            region: None,
1185            project: None,
1186        }];
1187        let reg = ProviderRegistry::from_config(
1188            &defs,
1189            "https://api.anthropic.com",
1190            "https://api.openai.com",
1191        );
1192        assert_eq!(reg.get("gemini").unwrap().id(), "gemini");
1193    }
1194
1195    #[test]
1196    fn from_config_registers_custom_providers_alongside_builtins() {
1197        let defs = vec![
1198            firstpass_core::ProviderDef {
1199                id: "groq".to_owned(),
1200                dialect: firstpass_core::Dialect::Openai,
1201                base_url: "https://api.groq.com/openai".to_owned(),
1202                api_key_env: Some("GROQ_API_KEY".to_owned()),
1203                auth: firstpass_core::AuthScheme::ApiKey,
1204                region: None,
1205                project: None,
1206            },
1207            // A custom provider may override a built-in id (e.g. point `openai` at Azure).
1208            firstpass_core::ProviderDef {
1209                id: "openai".to_owned(),
1210                dialect: firstpass_core::Dialect::Openai,
1211                base_url: "https://my-azure.openai.azure.com".to_owned(),
1212                api_key_env: Some("AZURE_OPENAI_KEY".to_owned()),
1213                auth: firstpass_core::AuthScheme::ApiKey,
1214                region: None,
1215                project: None,
1216            },
1217        ];
1218        let reg = ProviderRegistry::from_config(
1219            &defs,
1220            "https://api.anthropic.com",
1221            "https://api.openai.com",
1222        );
1223        // Built-in anthropic is still present; the custom groq resolves and labels itself "groq".
1224        assert_eq!(reg.get("anthropic").unwrap().id(), "anthropic");
1225        assert_eq!(reg.get("groq").unwrap().id(), "groq");
1226        // Unknown provider → None (router fails over rather than guessing).
1227        assert!(reg.get("does-not-exist").is_none());
1228    }
1229
1230    #[test]
1231    fn anthropic_messages_body_omits_model_and_includes_system_only_when_set() {
1232        let req = ModelRequest {
1233            model: "bedrock/anthropic.claude-3-5-haiku".to_owned(),
1234            system: Some("be terse".to_owned()),
1235            messages: vec![
1236                ChatMessage::text("user", "hi"),
1237                ChatMessage {
1238                    role: "assistant".to_owned(),
1239                    content: serde_json::json!([{ "type": "text", "text": "hello" }]),
1240                },
1241            ],
1242            max_tokens: 128,
1243            tools: Value::Null,
1244            raw: Value::Null,
1245        };
1246        let body = anthropic_messages_body(&req, "bedrock-2023-05-31");
1247        // Model goes in the URL for Bedrock/Vertex, never the body.
1248        assert!(body.get("model").is_none());
1249        assert_eq!(body["anthropic_version"], "bedrock-2023-05-31");
1250        assert_eq!(body["max_tokens"], 128);
1251        assert_eq!(body["system"], "be terse");
1252        assert_eq!(body["messages"][0]["content"], serde_json::json!("hi"));
1253        // Content-block arrays forward verbatim, same as the direct Anthropic adapter (ADR 0005).
1254        assert_eq!(
1255            body["messages"][1]["content"],
1256            serde_json::json!([{ "type": "text", "text": "hello" }])
1257        );
1258
1259        // No system prompt => no `system` key at all (not `null`).
1260        let req_no_system = ModelRequest {
1261            system: None,
1262            ..req
1263        };
1264        let body2 = anthropic_messages_body(&req_no_system, "vertex-2023-10-16");
1265        assert!(body2.get("system").is_none());
1266    }
1267
1268    #[test]
1269    fn bedrock_url_construction_and_missing_region() {
1270        assert_eq!(
1271            bedrock_url("us-east-1", "anthropic.claude-3-5-haiku-20241022-v1:0"),
1272            "https://bedrock-runtime.us-east-1.amazonaws.com/model/anthropic.claude-3-5-haiku-20241022-v1:0/invoke"
1273        );
1274    }
1275
1276    #[tokio::test]
1277    async fn bedrock_complete_errors_without_a_region() {
1278        let provider = BedrockProvider {
1279            id: "bedrock".to_owned(),
1280            region: None,
1281            http: reqwest::Client::new(),
1282        };
1283        let req = ModelRequest {
1284            model: "bedrock/anthropic.claude-3-5-haiku".to_owned(),
1285            system: None,
1286            messages: vec![],
1287            max_tokens: 16,
1288            tools: Value::Null,
1289            raw: Value::Null,
1290        };
1291        let err = provider.complete(&req, &Auth::default()).await.unwrap_err();
1292        assert!(matches!(err, ProviderError::Transport(_)));
1293    }
1294
1295    #[test]
1296    fn bedrock_signing_produces_a_sigv4_authorization_header() {
1297        // Dummy, non-production credentials — this only proves the *shape* of the signed request
1298        // (algorithm header + host), not cryptographic validity against real AWS (LIVE-UNVERIFIED).
1299        let creds = AwsEnvCredentials {
1300            access_key_id: "AKIDEXAMPLE".to_owned(),
1301            secret_access_key: "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY".to_owned(),
1302            session_token: None,
1303        };
1304        let url = bedrock_url("us-east-1", "anthropic.claude-3-5-haiku");
1305        let body = br#"{"anthropic_version":"bedrock-2023-05-31"}"#;
1306        let signed = sign_bedrock(&url, "us-east-1", body, &creds).unwrap();
1307
1308        let auth_header = signed
1309            .headers()
1310            .get("authorization")
1311            .and_then(|v| v.to_str().ok())
1312            .expect("authorization header present");
1313        assert!(auth_header.starts_with("AWS4-HMAC-SHA256"));
1314
1315        let host_header = signed
1316            .headers()
1317            .get("host")
1318            .and_then(|v| v.to_str().ok())
1319            .expect("host header present");
1320        assert_eq!(host_header, "bedrock-runtime.us-east-1.amazonaws.com");
1321    }
1322
1323    #[test]
1324    fn vertex_url_construction_and_missing_project() {
1325        assert_eq!(
1326            vertex_url("us-central1", "my-project", "claude-3-5-sonnet"),
1327            "https://us-central1-aiplatform.googleapis.com/v1/projects/my-project/locations/us-central1/publishers/anthropic/models/claude-3-5-sonnet:rawPredict"
1328        );
1329    }
1330
1331    #[tokio::test]
1332    async fn vertex_complete_errors_without_a_project() {
1333        let provider = VertexProvider {
1334            id: "vertex".to_owned(),
1335            region: Some("us-central1".to_owned()),
1336            project: None,
1337            http: reqwest::Client::new(),
1338        };
1339        let req = ModelRequest {
1340            model: "vertex/claude-3-5-sonnet".to_owned(),
1341            system: None,
1342            messages: vec![],
1343            max_tokens: 16,
1344            tools: Value::Null,
1345            raw: Value::Null,
1346        };
1347        let err = provider.complete(&req, &Auth::default()).await.unwrap_err();
1348        assert!(matches!(err, ProviderError::Transport(_)));
1349    }
1350
1351    #[test]
1352    fn from_config_wires_bedrock_and_vertex_auth_schemes() {
1353        let defs = vec![
1354            firstpass_core::ProviderDef {
1355                id: "bedrock".to_owned(),
1356                dialect: firstpass_core::Dialect::Anthropic,
1357                base_url: String::new(),
1358                api_key_env: None,
1359                auth: firstpass_core::AuthScheme::AwsSigv4,
1360                region: Some("us-east-1".to_owned()),
1361                project: None,
1362            },
1363            firstpass_core::ProviderDef {
1364                id: "vertex".to_owned(),
1365                dialect: firstpass_core::Dialect::Anthropic,
1366                base_url: String::new(),
1367                api_key_env: None,
1368                auth: firstpass_core::AuthScheme::GcpOauth,
1369                region: Some("us-central1".to_owned()),
1370                project: Some("my-project".to_owned()),
1371            },
1372        ];
1373        let reg = ProviderRegistry::from_config(
1374            &defs,
1375            "https://api.anthropic.com",
1376            "https://api.openai.com",
1377        );
1378        assert_eq!(reg.get("bedrock").unwrap().id(), "bedrock");
1379        assert_eq!(reg.get("vertex").unwrap().id(), "vertex");
1380    }
1381
1382    #[test]
1383    fn resolve_api_key_prefers_configured_env_then_byok() {
1384        // Use PATH (always present) to exercise the env branch without mutating process env.
1385        let path = std::env::var("PATH").expect("PATH is set");
1386        // Configured env wins over any BYOK override (the env var is *this* provider's key).
1387        assert_eq!(resolve_api_key(Some("PATH"), Some("byok")), path);
1388        // An unset configured env → fall back to the per-request BYOK override.
1389        assert_eq!(
1390            resolve_api_key(Some("FIRSTPASS_DEFINITELY_UNSET_KEY"), Some("byok")),
1391            "byok"
1392        );
1393        // No configured env → fall back to BYOK.
1394        assert_eq!(resolve_api_key(None, Some("byok")), "byok");
1395        // Neither → empty (keyless local endpoint).
1396        assert_eq!(resolve_api_key(None, None), "");
1397    }
1398
1399    #[test]
1400    fn anthropic_wire_forwards_tool_and_image_content_verbatim() {
1401        // ADR 0005 I3 (request side): the Anthropic adapter serializes tool_use / tool_result /
1402        // image content blocks byte-for-byte into the wire body — enforce forwards them, it does not
1403        // flatten them. A plain-string message still serializes as a bare string (I1).
1404        let messages = vec![
1405            ChatMessage::text("user", "hi"),
1406            ChatMessage {
1407                role: "assistant".to_owned(),
1408                content: serde_json::json!([
1409                    { "type": "tool_use", "id": "t1", "name": "calc", "input": { "x": 1 } }
1410                ]),
1411            },
1412            ChatMessage {
1413                role: "user".to_owned(),
1414                content: serde_json::json!([
1415                    { "type": "tool_result", "tool_use_id": "t1", "content": "2" },
1416                    { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "AA==" } }
1417                ]),
1418            },
1419        ];
1420        let wire = anthropic_wire_body(&ModelRequest {
1421            model: "anthropic/claude-haiku-4-5".to_owned(),
1422            system: None,
1423            messages,
1424            max_tokens: 64,
1425            tools: Value::Null,
1426            raw: Value::Null,
1427        });
1428        assert_eq!(wire["messages"][0]["content"], serde_json::json!("hi"));
1429        assert_eq!(
1430            wire["messages"][1]["content"],
1431            serde_json::json!([{ "type": "tool_use", "id": "t1", "name": "calc", "input": { "x": 1 } }])
1432        );
1433        assert_eq!(
1434            wire["messages"][2]["content"],
1435            serde_json::json!([
1436                { "type": "tool_result", "tool_use_id": "t1", "content": "2" },
1437                { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "AA==" } }
1438            ])
1439        );
1440    }
1441
1442    fn resp(model: &str, text: &str) -> ModelResponse {
1443        ModelResponse {
1444            model: model.to_owned(),
1445            text: text.to_owned(),
1446            in_tokens: 10,
1447            out_tokens: 5,
1448            raw: Value::Null,
1449        }
1450    }
1451
1452    #[test]
1453    fn transport_and_5xx_are_failover_eligible() {
1454        assert!(ProviderError::Transport("boom".into()).is_failover_eligible());
1455        assert!(
1456            ProviderError::Http {
1457                status: 503,
1458                body: String::new()
1459            }
1460            .is_failover_eligible()
1461        );
1462    }
1463
1464    #[test]
1465    fn client_errors_and_decode_failures_are_hard() {
1466        assert!(
1467            !ProviderError::Http {
1468                status: 400,
1469                body: String::new()
1470            }
1471            .is_failover_eligible()
1472        );
1473        assert!(!ProviderError::Decode("bad json".into()).is_failover_eligible());
1474    }
1475
1476    #[test]
1477    fn auth_debug_never_prints_key_material() {
1478        let auth = Auth {
1479            anthropic_key: Some("sk-ant-super-secret".to_owned()),
1480            openai_key: Some("sk-oai-super-secret".to_owned()),
1481        };
1482        let debug = format!("{auth:?}");
1483        assert!(!debug.contains("super-secret"));
1484    }
1485
1486    #[tokio::test]
1487    async fn mock_provider_returns_configured_outcome() {
1488        let mut outcomes = HashMap::new();
1489        outcomes.insert(
1490            "anthropic/claude-haiku-4-5".to_owned(),
1491            Ok(resp("anthropic/claude-haiku-4-5", "hello")),
1492        );
1493        let provider = MockProvider::new("anthropic", outcomes);
1494        let req = ModelRequest {
1495            model: "anthropic/claude-haiku-4-5".to_owned(),
1496            system: None,
1497            messages: vec![],
1498            max_tokens: 100,
1499            tools: Value::Null,
1500            raw: Value::Null,
1501        };
1502        let out = provider.complete(&req, &Auth::default()).await.unwrap();
1503        assert_eq!(out.text, "hello");
1504    }
1505
1506    #[test]
1507    fn anthropic_wire_body_carries_raw_request_verbatim() {
1508        // ADR 0005: with a raw inbound body present, the wire request IS that body — every field
1509        // the caller set (tools, tool_choice, temperature, thinking, ...) survives; only `model`
1510        // is swapped to the rung's wire id and `stream` is stripped (complete() buffers to gate).
1511        let raw = serde_json::json!({
1512            "model": "claude-opus-4-8",
1513            "stream": true,
1514            "max_tokens": 512,
1515            "temperature": 0.2,
1516            "tool_choice": { "type": "auto" },
1517            "tools": [{ "name": "get_weather", "input_schema": { "type": "object" } }],
1518            "thinking": { "type": "enabled", "budget_tokens": 1024 },
1519            "messages": [{ "role": "user", "content": "hi" }]
1520        });
1521        let req = ModelRequest {
1522            model: "anthropic/claude-haiku-4-5".to_owned(),
1523            system: None,
1524            messages: vec![ChatMessage::text("user", "hi")],
1525            max_tokens: 512,
1526            tools: raw["tools"].clone(),
1527            raw: raw.clone(),
1528        };
1529        let wire = anthropic_wire_body(&req);
1530        assert_eq!(wire["model"], "claude-haiku-4-5", "rung model swapped in");
1531        assert!(wire.get("stream").is_none(), "stream stripped");
1532        for field in [
1533            "temperature",
1534            "tool_choice",
1535            "tools",
1536            "thinking",
1537            "max_tokens",
1538            "messages",
1539        ] {
1540            assert_eq!(
1541                wire[field], raw[field],
1542                "field {field} must survive verbatim"
1543            );
1544        }
1545    }
1546
1547    #[test]
1548    fn bedrock_vertex_body_carries_raw_minus_model_plus_version() {
1549        let raw = serde_json::json!({
1550            "model": "claude-haiku-4-5",
1551            "stream": true,
1552            "max_tokens": 64,
1553            "tools": [{ "name": "t" }],
1554            "messages": [{ "role": "user", "content": "hi" }]
1555        });
1556        let req = ModelRequest {
1557            model: "bedrock/anthropic.claude-haiku".to_owned(),
1558            system: None,
1559            messages: vec![ChatMessage::text("user", "hi")],
1560            max_tokens: 64,
1561            tools: raw["tools"].clone(),
1562            raw: raw.clone(),
1563        };
1564        let body = anthropic_messages_body(&req, "bedrock-2023-05-31");
1565        assert!(body.get("model").is_none(), "model lives in the URL");
1566        assert!(body.get("stream").is_none());
1567        assert_eq!(body["anthropic_version"], "bedrock-2023-05-31");
1568        assert_eq!(body["tools"], raw["tools"]);
1569        assert_eq!(body["messages"], raw["messages"]);
1570    }
1571
1572    #[test]
1573    fn verbatim_carriers_are_dialect_aware() {
1574        use firstpass_core::Dialect;
1575        let reg = ProviderRegistry::new("http://localhost", "http://localhost");
1576        // Anthropic provider: verbatim for Anthropic inbound, not for OpenAI
1577        assert!(
1578            reg.get("anthropic")
1579                .unwrap()
1580                .carries_structured_verbatim(Dialect::Anthropic)
1581        );
1582        assert!(
1583            !reg.get("anthropic")
1584                .unwrap()
1585                .carries_structured_verbatim(Dialect::Openai)
1586        );
1587        // OpenAI provider: verbatim for OpenAI inbound, not for Anthropic
1588        assert!(
1589            reg.get("openai")
1590                .unwrap()
1591                .carries_structured_verbatim(Dialect::Openai)
1592        );
1593        assert!(
1594            !reg.get("openai")
1595                .unwrap()
1596                .carries_structured_verbatim(Dialect::Anthropic)
1597        );
1598    }
1599
1600    #[test]
1601    fn openai_wire_body_carries_raw_request_verbatim() {
1602        // All-OpenAI-ladder raw carry: same semantics as anthropic_wire_body_carries_raw_request_verbatim.
1603        let raw = serde_json::json!({
1604            "model": "gpt-4o",
1605            "stream": true,
1606            "max_tokens": 256,
1607            "temperature": 0.7,
1608            "response_format": { "type": "json_object" },
1609            "tool_choice": "auto",
1610            "tools": [{ "type": "function", "function": { "name": "get_weather", "parameters": {} } }],
1611            "messages": [{ "role": "user", "content": "hi" }]
1612        });
1613        let req = ModelRequest {
1614            model: "openai/gpt-4.1-mini".to_owned(),
1615            system: None,
1616            messages: vec![ChatMessage::text("user", "hi")],
1617            max_tokens: 256,
1618            tools: Value::Null,
1619            raw: raw.clone(),
1620        };
1621        let wire = openai_wire_body(&req);
1622        assert_eq!(wire["model"], "gpt-4.1-mini", "rung model swapped in");
1623        assert!(wire.get("stream").is_none(), "stream stripped");
1624        for field in [
1625            "temperature",
1626            "tool_choice",
1627            "tools",
1628            "response_format",
1629            "messages",
1630            "max_tokens",
1631        ] {
1632            assert_eq!(
1633                wire[field], raw[field],
1634                "field {field} must survive verbatim"
1635            );
1636        }
1637    }
1638
1639    #[test]
1640    fn openai_wire_body_falls_back_to_normalized_fields() {
1641        // Translation path (raw = Null): reconstruct from normalized fields.
1642        let req = ModelRequest {
1643            model: "openai/gpt-4.1-mini".to_owned(),
1644            system: Some("be terse".to_owned()),
1645            messages: vec![
1646                ChatMessage::text("user", "hello"),
1647                ChatMessage::text("assistant", "hi"),
1648            ],
1649            max_tokens: 128,
1650            tools: Value::Null,
1651            raw: Value::Null,
1652        };
1653        let wire = openai_wire_body(&req);
1654        assert_eq!(wire["model"], "gpt-4.1-mini");
1655        // System → injected as first message with role="system"
1656        assert_eq!(wire["messages"][0]["role"], "system");
1657        assert_eq!(wire["messages"][0]["content"], "be terse");
1658        assert_eq!(wire["messages"][1]["role"], "user");
1659        assert_eq!(wire["messages"][2]["role"], "assistant");
1660    }
1661}