Skip to main content

mutil_ai/adapter/
mod.rs

1mod anthropic;
2mod endpoint;
3mod gemini;
4mod openai_chat;
5mod openai_responses;
6
7use std::future::Future;
8use std::pin::Pin;
9use std::time::Instant;
10
11use async_trait::async_trait;
12use reqwest::header::{CONTENT_TYPE, HeaderMap, HeaderName, HeaderValue};
13use serde_json::Value;
14
15use crate::audit::{AuditContext, AuditOutcome};
16use crate::cancel::CancellationToken;
17use crate::error::{Error, Result};
18use crate::headers::{RequestOptions, TransportConfig};
19use crate::normalize::Protocol;
20use crate::profile::{
21    ProfileSelector, ProviderProfile, ProviderRequestOptions, ToolCallContentMode,
22};
23use crate::report::{CompletionReport, WireAction, WireFeature};
24use crate::retry::{RetryPolicy, RetryProvider, next_delay, parse_retry_headers};
25use crate::security::RequestBudget;
26use crate::stream::{ModelStream, StreamReconnectPolicy, sse_stream_with_reconnect};
27use crate::types::{ChatRequest, ResponseMetadata, ToolChoice, ToolSpec};
28
29pub use anthropic::{Anthropic, AnthropicMessages};
30pub use endpoint::{EndpointAdapter, OpenAICompatible};
31pub use gemini::{Gemini, GeminiGenerateContent};
32pub use openai_chat::{OpenAI, OpenAIChat};
33pub use openai_responses::OpenAIResponses;
34
35pub(crate) fn secure_http_client() -> reqwest::Client {
36    reqwest::Client::builder()
37        .redirect(reqwest::redirect::Policy::none())
38        .build()
39        .expect("static SDK HTTP client configuration must be valid")
40}
41
42/// A provider adapter.
43///
44/// The adapter receives a provider-neutral [`ChatRequest`] and is responsible
45/// for:
46///
47/// 1. calling the crate's normalization layer;
48/// 2. serializing the normalized conversation to the provider wire format;
49/// 3. mapping the provider response back to [`crate::ChatResponse`].
50#[async_trait]
51pub trait ModelAdapter: Send + Sync {
52    /// Stable identifier of the provider behind this adapter,
53    /// e.g. `"anthropic-messages"`.
54    fn provider_name(&self) -> &'static str;
55
56    /// Model identifier used for this adapter, e.g. `"claude-sonnet-4"`.
57    fn model_name(&self) -> &str;
58
59    /// Complete a request with default [`RequestOptions`].
60    ///
61    /// # Errors
62    ///
63    /// Returns an error if the request cannot be normalized, the provider
64    /// rejects it, or the response fails to parse.
65    async fn complete(&self, request: &ChatRequest) -> Result<crate::ChatResponse> {
66        let options = RequestOptions::default();
67        self.complete_with(request, &options).await
68    }
69
70    /// Complete a request with explicit [`RequestOptions`].
71    ///
72    /// This is the primary entry point for non-streaming inference: the
73    /// adapter normalizes the [`ChatRequest`], serializes it to the provider
74    /// wire format, sends it, and parses the response back into
75    /// [`crate::ChatResponse`].
76    ///
77    /// # Errors
78    ///
79    /// Returns an error if the request cannot be normalized or validated,
80    /// the provider returns an error status, or the response fails to parse.
81    async fn complete_with(
82        &self,
83        request: &ChatRequest,
84        options: &RequestOptions,
85    ) -> Result<crate::ChatResponse>;
86
87    /// Start a streaming response with default request options.
88    async fn stream(&self, request: &ChatRequest) -> Result<ModelStream> {
89        let options = RequestOptions::default();
90        self.stream_with(request, &options).await
91    }
92
93    /// Start a streaming response.
94    ///
95    /// The default implementation reports that streaming is unsupported.
96    /// Built-in adapters override this method.
97    async fn stream_with(
98        &self,
99        _request: &ChatRequest,
100        _options: &RequestOptions,
101    ) -> Result<ModelStream> {
102        Err(Error::Unsupported(format!(
103            "{} does not implement streaming",
104            self.provider_name()
105        )))
106    }
107}
108
109pub(crate) fn validate_server_tools(protocol: Protocol, request: &ChatRequest) -> Result<()> {
110    if !request.server_tools.is_empty() && protocol != Protocol::OpenAiResponses {
111        return Err(Error::Unsupported(format!(
112            "{protocol:?} does not implement generic server-side tools"
113        )));
114    }
115    Ok(())
116}
117
118pub(crate) fn validate_tool_choice(tools: &[ToolSpec], choice: Option<&ToolChoice>) -> Result<()> {
119    match choice {
120        None | Some(ToolChoice::None) => Ok(()),
121        Some(ToolChoice::Auto | ToolChoice::Required) if tools.is_empty() => Err(
122            Error::InvalidRequest("tool_choice requires at least one tool".to_string()),
123        ),
124        Some(ToolChoice::Tool(name)) if tools.is_empty() => Err(Error::InvalidRequest(format!(
125            "tool_choice `{name}` requires at least one tool"
126        ))),
127        Some(ToolChoice::Tool(name)) if !tools.iter().any(|tool| tool.name == *name) => Err(
128            Error::InvalidRequest(format!("tool_choice references unknown tool `{name}`")),
129        ),
130        _ => Ok(()),
131    }
132}
133
134pub(crate) fn json_body_bytes(body: &Value) -> Result<u64> {
135    Ok(serde_json::to_vec(body)?.len() as u64)
136}
137
138pub(crate) fn merge_extra_body(
139    body: &mut Value,
140    request: &ChatRequest,
141    protocol: Protocol,
142    profile: Option<&ProviderProfile>,
143) -> Result<()> {
144    let reserved = reserved_body_fields(protocol);
145    let body = body.as_object_mut().ok_or_else(|| {
146        Error::InvalidProfile(format!("{protocol:?} request body must be a JSON object"))
147    })?;
148
149    if let Some(profile) = profile {
150        merge_body_fields(body, &profile.request.extra_body, protocol, reserved)?;
151    }
152    merge_body_fields(body, &request.extra_body, protocol, reserved)
153}
154
155fn merge_body_fields(
156    body: &mut serde_json::Map<String, Value>,
157    fields: &serde_json::Map<String, Value>,
158    protocol: Protocol,
159    reserved: &[&str],
160) -> Result<()> {
161    for (key, value) in fields {
162        if reserved.contains(&key.as_str()) {
163            return Err(Error::ReservedExtraBodyField {
164                protocol: protocol_name(protocol),
165                field: key.clone(),
166            });
167        }
168        body.insert(key.clone(), value.clone());
169    }
170    Ok(())
171}
172
173fn reserved_body_fields(protocol: Protocol) -> &'static [&'static str] {
174    match protocol {
175        Protocol::OpenAiChat => &[
176            "model",
177            "messages",
178            "stream",
179            "stream_options",
180            "tools",
181            "temperature",
182            "max_tokens",
183            "max_completion_tokens",
184        ],
185        Protocol::OpenAiResponses => &[
186            "model",
187            "input",
188            "instructions",
189            "stream",
190            "tools",
191            "temperature",
192            "max_output_tokens",
193            "reasoning",
194            "include",
195        ],
196        Protocol::AnthropicMessages => &[
197            "model",
198            "max_tokens",
199            "messages",
200            "system",
201            "tools",
202            "temperature",
203            "thinking",
204            "stream",
205        ],
206        Protocol::GeminiGenerateContent => {
207            &["contents", "systemInstruction", "tools", "generationConfig"]
208        }
209    }
210}
211
212pub(crate) fn protocol_name(protocol: Protocol) -> &'static str {
213    match protocol {
214        Protocol::OpenAiChat => "openai-chat",
215        Protocol::OpenAiResponses => "openai-responses",
216        Protocol::AnthropicMessages => "anthropic-messages",
217        Protocol::GeminiGenerateContent => "gemini-generate-content",
218    }
219}
220
221pub(crate) fn validate_profile_selector(selector: &ProfileSelector) -> Result<()> {
222    match selector {
223        ProfileSelector::Generic | ProfileSelector::Custom(_) => Ok(()),
224        ProfileSelector::Builtin(id) => {
225            if crate::profile::ProfileRegistry::new().resolve(id).is_some() {
226                Ok(())
227            } else {
228                Err(Error::Unsupported(format!(
229                    "built-in provider profile `{id}` is not registered; use ProfileSelector::Custom"
230                )))
231            }
232        }
233    }
234}
235
236pub(crate) fn resolve_api_key(
237    provider: &'static str,
238    explicit: Option<&str>,
239    env_name: &'static str,
240) -> Result<String> {
241    if let Some(key) = explicit
242        && !key.trim().is_empty()
243    {
244        return Ok(key.to_string());
245    }
246
247    let _ = provider;
248    match std::env::var(env_name) {
249        Ok(value) if !value.trim().is_empty() => Ok(value),
250        _ => Err(Error::MissingApiKey(env_name.to_string())),
251    }
252}
253
254pub(crate) async fn prepare_headers(
255    transport: &TransportConfig,
256    base_headers: &HeaderMap,
257    options: &RequestOptions,
258) -> Result<HeaderMap> {
259    let mut headers = base_headers.clone();
260    transport.apply_to_async(&mut headers, options).await?;
261    // Sensitivity is log metadata, not a wire change. Mark custom auth as well.
262    for value in headers.values_mut() {
263        value.set_sensitive(true);
264    }
265    Ok(headers)
266}
267
268pub(crate) fn effective_retry_policy(
269    policy: &RetryPolicy,
270    options: &RequestOptions,
271) -> RetryPolicy {
272    let mut policy = policy.clone();
273    if policy.require_idempotency_key && options.idempotency_key.is_none() {
274        policy.max_attempts = 1;
275    }
276    policy
277}
278
279pub(crate) fn audit_outcome_for_error(error: &Error) -> AuditOutcome {
280    if matches!(error, Error::Cancelled) {
281        AuditOutcome::Cancelled
282    } else {
283        AuditOutcome::Failure
284    }
285}
286
287pub(crate) fn effective_provider_request_options(
288    profile: Option<&ProviderProfile>,
289    request: &ProviderRequestOptions,
290) -> ProviderRequestOptions {
291    let mut effective = profile
292        .map(|profile| profile.request_options.clone())
293        .unwrap_or_default();
294    if request.tool_call_content.is_some() {
295        effective.tool_call_content = request.tool_call_content;
296    }
297    if request.require_provider_parameters.is_some() {
298        effective.require_provider_parameters = request.require_provider_parameters;
299    }
300    if request.do_sample.is_some() {
301        effective.do_sample = request.do_sample;
302    }
303    if request.include_stream_usage.is_some() {
304        effective.include_stream_usage = request.include_stream_usage;
305    }
306    if request.prompt_cache_key.is_some() {
307        effective
308            .prompt_cache_key
309            .clone_from(&request.prompt_cache_key);
310    }
311    if request.user.is_some() {
312        effective.user.clone_from(&request.user);
313    }
314    effective
315}
316
317pub(crate) fn apply_provider_request_options(
318    body: &mut Value,
319    protocol: Protocol,
320    options: &ProviderRequestOptions,
321    streaming: bool,
322) -> Result<()> {
323    let body = body.as_object_mut().ok_or_else(|| {
324        Error::InvalidProfile(format!("{protocol:?} request body must be a JSON object"))
325    })?;
326
327    if let Some(prompt_cache_key) = &options.prompt_cache_key
328        && matches!(protocol, Protocol::OpenAiChat | Protocol::OpenAiResponses)
329    {
330        body.insert(
331            "prompt_cache_key".to_string(),
332            Value::String(prompt_cache_key.clone()),
333        );
334    }
335    if let Some(user) = &options.user
336        && protocol == Protocol::OpenAiChat
337    {
338        body.insert("user".to_string(), Value::String(user.clone()));
339    }
340    if let Some(do_sample) = options.do_sample {
341        body.insert("do_sample".to_string(), Value::Bool(do_sample));
342    }
343    if let Some(require_provider_parameters) = options.require_provider_parameters {
344        body.insert(
345            "require_provider_parameters".to_string(),
346            Value::Bool(require_provider_parameters),
347        );
348    }
349    if streaming
350        && protocol == Protocol::OpenAiChat
351        && let Some(include_usage) = options.include_stream_usage
352    {
353        let stream_options = body
354            .entry("stream_options".to_string())
355            .or_insert_with(|| Value::Object(serde_json::Map::new()));
356        if let Some(stream_options) = stream_options.as_object_mut() {
357            stream_options.insert("include_usage".to_string(), Value::Bool(include_usage));
358        }
359    }
360
361    if protocol == Protocol::OpenAiChat
362        && let Some(mode) = options.tool_call_content
363        && let Some(messages) = body.get_mut("messages").and_then(Value::as_array_mut)
364    {
365        // Tripwire: 非空 content 是真实转录数据,任何模式下都不得被改写。
366        // 0.5.0 曾无条件清空(消费方模型"失忆"五个月),此断言保证回归即炸。
367        let non_empty_before: Vec<usize> = messages
368            .iter()
369            .enumerate()
370            .filter(|(_, m)| m.get("tool_calls").is_some_and(Value::is_array))
371            .filter(|(_, m)| {
372                matches!(m.get("content"), Some(Value::String(s)) if !s.is_empty())
373            })
374            .map(|(i, _)| i)
375            .collect();
376        for message in messages.iter_mut() {
377            if !message.get("tool_calls").is_some_and(Value::is_array) {
378                continue;
379            }
380            // Only shape EMPTY content. Non-empty assistant text next to
381            // tool_calls is real transcript data: clobbering it here silently
382            // blinded consumers' models (qaqh-backend regression, fixed
383            // 2026-10-14 — the model lost its own previous narration and kept
384            // re-deriving context in its reasoning). Consumers that truly need
385            // to strip non-empty content must use `request_transform`.
386            let content_empty = match message.get("content") {
387                None | Some(Value::Null) => true,
388                Some(Value::String(s)) => s.is_empty(),
389                _ => false,
390            };
391            if !content_empty {
392                continue;
393            }
394            match mode {
395                ToolCallContentMode::Auto => {}
396                ToolCallContentMode::Null => {
397                    message["content"] = Value::Null;
398                }
399                ToolCallContentMode::Omit => {
400                    if let Some(message) = message.as_object_mut() {
401                        message.remove("content");
402                    }
403                }
404                ToolCallContentMode::Empty => {
405                    message["content"] = Value::String(String::new());
406                }
407            }
408        }
409        for i in non_empty_before {
410            let preserved = matches!(
411                messages[i].get("content"),
412                Some(Value::String(s)) if !s.is_empty()
413            );
414            if !preserved {
415                eprintln!(
416                    "[mutil-ai][WIRE-LOSS] tool_call_content mode={mode:?} altered non-empty \
417                     assistant content (message #{i}) — transcript data loss regression"
418                );
419                debug_assert!(
420                    false,
421                    "tool_call_content clobbered non-empty assistant content"
422                );
423            }
424        }
425    }
426
427    Ok(())
428}
429
430pub(crate) fn apply_request_transform<'a>(
431    request: &'a ChatRequest,
432    options: &RequestOptions,
433) -> Result<std::borrow::Cow<'a, ChatRequest>> {
434    match &options.request_transform {
435        Some(transform) => Ok(std::borrow::Cow::Owned(transform.transform(request)?)),
436        None => Ok(std::borrow::Cow::Borrowed(request)),
437    }
438}
439
440pub(crate) fn completion_report(
441    protocol: Protocol,
442    request: &ChatRequest,
443    normalization: crate::normalize::NormalizeStats,
444    transform_applied: bool,
445) -> CompletionReport {
446    let mut report = CompletionReport::from_normalization(normalization);
447    report.transform_applied = transform_applied;
448    let mut downgraded_tool_results = 0_u32;
449    let mut unsupported_provider_items = 0_u32;
450    let mut unsupported_tool_metadata = 0_u32;
451    for message in &request.messages {
452        for part in &message.parts {
453            match part {
454                crate::types::Part::ToolResult(result) => {
455                    let has_structured = result
456                        .parts
457                        .iter()
458                        .any(|part| !matches!(part, crate::types::ToolResultPart::Text { .. }));
459                    if has_structured
460                        && matches!(protocol, Protocol::OpenAiChat | Protocol::OpenAiResponses)
461                    {
462                        downgraded_tool_results += 1;
463                    }
464                    if result.status.is_some() || result.metadata.is_some() {
465                        unsupported_tool_metadata += 1;
466                    }
467                }
468                crate::types::Part::ProviderItem(item)
469                    if item.provider_state.format != protocol.provider_state_format() =>
470                {
471                    unsupported_provider_items += 1;
472                }
473                _ => {}
474            }
475        }
476    }
477    if downgraded_tool_results > 0 {
478        report.wire.push(WireAction::Downgraded {
479            feature: WireFeature::StructuredToolResult,
480            to: "text".to_string(),
481            count: downgraded_tool_results,
482        });
483    }
484    if unsupported_provider_items > 0 {
485        report.wire.push(WireAction::Unsupported {
486            feature: WireFeature::ProviderItem,
487            count: unsupported_provider_items,
488        });
489    }
490    if unsupported_tool_metadata > 0 {
491        report.wire.push(WireAction::Unsupported {
492            feature: WireFeature::RequestField,
493            count: unsupported_tool_metadata,
494        });
495    }
496    if !request.server_tools.is_empty() && protocol != Protocol::OpenAiResponses {
497        report.wire.push(WireAction::Unsupported {
498            feature: WireFeature::ServerTool,
499            count: request.server_tools.len() as u32,
500        });
501    }
502    report
503}
504
505pub(crate) struct ReconnectRequest {
506    budget: RequestBudget,
507    provider: &'static str,
508    client: reqwest::Client,
509    retry_policy: RetryPolicy,
510    retry_provider: RetryProvider,
511    transport: TransportConfig,
512    options: RequestOptions,
513    audit: Option<AuditContext>,
514    url: String,
515    base_headers: HeaderMap,
516    query: Vec<(String, String)>,
517    body: Value,
518}
519
520pub(crate) struct ReconnectRequestParts {
521    pub budget: RequestBudget,
522    pub provider: &'static str,
523    pub client: reqwest::Client,
524    pub retry_policy: RetryPolicy,
525    pub retry_provider: RetryProvider,
526    pub transport: TransportConfig,
527    pub options: RequestOptions,
528    pub audit: Option<AuditContext>,
529    pub url: String,
530    pub base_headers: HeaderMap,
531    pub query: Vec<(String, String)>,
532    pub body: Value,
533}
534
535impl ReconnectRequest {
536    pub(crate) fn new(parts: ReconnectRequestParts) -> Self {
537        Self {
538            budget: parts.budget,
539            provider: parts.provider,
540            client: parts.client,
541            retry_policy: parts.retry_policy,
542            retry_provider: parts.retry_provider,
543            transport: parts.transport,
544            options: parts.options,
545            audit: parts.audit,
546            url: parts.url,
547            base_headers: parts.base_headers,
548            query: parts.query,
549            body: parts.body,
550        }
551    }
552
553    fn connect(
554        &self,
555        last_event_id: Option<String>,
556    ) -> Pin<Box<dyn Future<Output = Result<reqwest::Response>> + Send>> {
557        let provider = self.provider;
558        let client = self.client.clone();
559        let retry_policy = self.retry_policy.clone();
560        let retry_provider = self.retry_provider;
561        let transport = self.transport.clone();
562        let options = self.options.clone();
563        let audit = self.audit.clone();
564        let url = self.url.clone();
565        let base_headers = self.base_headers.clone();
566        let query = self.query.clone();
567        let body = self.body.clone();
568        let budget = self.budget.clone();
569
570        Box::pin(async move {
571            let cancellation = options.cancellation.clone();
572            send_stream_retry(
573                provider,
574                retry_provider,
575                &retry_policy,
576                audit.as_ref(),
577                cancellation.as_ref(),
578                &budget,
579                || async {
580                    let mut headers = prepare_headers(&transport, &base_headers, &options).await?;
581                    if let Some(last_event_id) = &last_event_id {
582                        headers.insert(
583                            HeaderName::from_static("last-event-id"),
584                            HeaderValue::from_str(last_event_id)?,
585                        );
586                    }
587                    let mut request_builder =
588                        client.post(&url).headers(headers).query(&query).json(&body);
589                    if let Some(timeout) = options.timeout {
590                        request_builder = request_builder.timeout(timeout);
591                    }
592                    Ok(request_builder)
593                },
594            )
595            .await
596        })
597    }
598}
599
600#[allow(clippy::too_many_arguments)]
601pub(crate) fn finish_sse_stream<M>(
602    response: reqwest::Response,
603    mut mapper: M,
604    policy: Option<StreamReconnectPolicy>,
605    reconnect: Option<ReconnectRequest>,
606    cancellation: Option<CancellationToken>,
607    idle_timeout: Option<std::time::Duration>,
608    audit: Option<AuditContext>,
609    budget: RequestBudget,
610) -> ModelStream
611where
612    M: crate::stream::SseMapper,
613{
614    mapper.configure_limits(budget.limits);
615    match (policy, reconnect) {
616        (Some(policy), Some(reconnect)) => sse_stream_with_reconnect(
617            response,
618            mapper,
619            policy,
620            move |last_event_id| reconnect.connect(last_event_id),
621            cancellation,
622            idle_timeout,
623            audit,
624            budget,
625        ),
626        _ => crate::stream::sse_stream_with_audit(
627            response,
628            mapper,
629            cancellation,
630            idle_timeout,
631            audit,
632            budget,
633        ),
634    }
635}
636
637#[allow(clippy::too_many_arguments)]
638pub(crate) async fn send_json(
639    provider: &'static str,
640    retry_provider: RetryProvider,
641    request: reqwest::RequestBuilder,
642    audit: Option<&AuditContext>,
643    attempt: u32,
644    attempt_started: Instant,
645    cancellation: Option<&CancellationToken>,
646    budget: &RequestBudget,
647) -> Result<(Value, ResponseMetadata)> {
648    let response = send_request(request, cancellation).await?;
649    let metadata = ResponseMetadata::from_response(&response);
650    let status = response.status();
651    if let Some(audit) = audit {
652        audit.response_headers(
653            attempt,
654            attempt_started.elapsed(),
655            status.as_u16(),
656            metadata.request_id.clone(),
657            status.is_success(),
658        );
659    }
660    let retry_directive = parse_retry_headers(retry_provider, response.headers());
661    let retry_after = retry_directive.map(|directive| directive.delay);
662    let retry_source = retry_directive.map(|directive| directive.source);
663    let text = read_response_text(response, cancellation, budget).await?;
664    if let Some(audit) = audit {
665        audit.add_response_bytes(text.len());
666    }
667
668    if !status.is_success() {
669        return Err(Error::Api {
670            provider,
671            status: status.as_u16(),
672            body: text,
673            retry_after,
674            retry_source,
675            request_id: metadata.request_id.clone(),
676        });
677    }
678
679    let value = serde_json::from_str(&text).map_err(Error::from)?;
680    Ok((value, metadata))
681}
682
683async fn send_request(
684    request: reqwest::RequestBuilder,
685    cancellation: Option<&CancellationToken>,
686) -> Result<reqwest::Response> {
687    if let Some(cancellation) = cancellation {
688        if cancellation.is_cancelled() {
689            return Err(Error::Cancelled);
690        }
691        tokio::select! {
692            biased;
693            _ = cancellation.cancelled() => Err(Error::Cancelled),
694            response = request.send() => response.map_err(Error::from),
695        }
696    } else {
697        request.send().await.map_err(Error::from)
698    }
699}
700
701async fn read_response_text(
702    mut response: reqwest::Response,
703    cancellation: Option<&CancellationToken>,
704    budget: &RequestBudget,
705) -> Result<String> {
706    let mut bytes = Vec::new();
707    loop {
708        let chunk = if let Some(token) = cancellation {
709            if token.is_cancelled() {
710                return Err(Error::Cancelled);
711            }
712            tokio::select! {
713                biased;
714                _ = token.cancelled() => return Err(Error::Cancelled),
715                chunk = response.chunk() => chunk.map_err(Error::from)?,
716            }
717        } else {
718            response.chunk().await.map_err(Error::from)?
719        };
720        let Some(chunk) = chunk else {
721            break;
722        };
723        budget.add_bytes(chunk.len())?;
724        bytes.extend_from_slice(&chunk);
725    }
726    Ok(String::from_utf8_lossy(&bytes).into_owned())
727}
728
729async fn sleep_or_cancel(
730    delay: std::time::Duration,
731    cancellation: Option<&CancellationToken>,
732) -> Result<()> {
733    if let Some(cancellation) = cancellation {
734        if cancellation.is_cancelled() {
735            return Err(Error::Cancelled);
736        }
737        tokio::select! {
738            biased;
739            _ = cancellation.cancelled() => Err(Error::Cancelled),
740            _ = tokio::time::sleep(delay) => Ok(()),
741        }
742    } else {
743        tokio::time::sleep(delay).await;
744        Ok(())
745    }
746}
747
748async fn build_request_or_cancel<Fut>(
749    future: Fut,
750    cancellation: Option<&CancellationToken>,
751) -> Result<reqwest::RequestBuilder>
752where
753    Fut: Future<Output = Result<reqwest::RequestBuilder>>,
754{
755    if let Some(cancellation) = cancellation {
756        if cancellation.is_cancelled() {
757            return Err(Error::Cancelled);
758        }
759        tokio::select! {
760            biased;
761            _ = cancellation.cancelled() => Err(Error::Cancelled),
762            request = future => request,
763        }
764    } else {
765        future.await
766    }
767}
768
769pub(crate) async fn send_json_retry<F, Fut>(
770    provider: &'static str,
771    retry_provider: RetryProvider,
772    policy: &RetryPolicy,
773    audit: Option<&AuditContext>,
774    cancellation: Option<&CancellationToken>,
775    budget: &RequestBudget,
776    mut make_request: F,
777) -> Result<(Value, ResponseMetadata)>
778where
779    F: FnMut() -> Fut,
780    Fut: Future<Output = Result<reqwest::RequestBuilder>>,
781{
782    budget
783        .run(async {
784            if policy.max_attempts == 0 {
785                return Err(Error::InvalidRetryPolicy(
786                    "max_attempts must be at least 1".to_string(),
787                ));
788            }
789
790            for attempt in 0..policy.max_attempts {
791                if cancellation.is_some_and(CancellationToken::is_cancelled) {
792                    return Err(Error::Cancelled);
793                }
794                if let Some(audit) = audit {
795                    audit.attempt_started(attempt);
796                }
797                let attempt_started = Instant::now();
798                let request = match build_request_or_cancel(make_request(), cancellation).await {
799                    Ok(request) => request,
800                    Err(error) => {
801                        if let Some(audit) = audit {
802                            audit.attempt_finished_with_request_id(
803                                attempt,
804                                attempt_started.elapsed(),
805                                None,
806                                None,
807                                Some(&error),
808                            );
809                        }
810                        let Some(delay) = next_delay(policy, attempt, &error) else {
811                            return Err(error);
812                        };
813                        if let Some(audit) = audit {
814                            audit.retry_scheduled(attempt, attempt + 1, delay, &error);
815                        }
816                        sleep_or_cancel(delay, cancellation).await?;
817                        continue;
818                    }
819                };
820
821                match send_json(
822                    provider,
823                    retry_provider,
824                    request,
825                    audit,
826                    attempt,
827                    attempt_started,
828                    cancellation,
829                    budget,
830                )
831                .await
832                {
833                    Ok(response) => {
834                        if let Some(audit) = audit {
835                            audit.attempt_finished_with_request_id(
836                                attempt,
837                                attempt_started.elapsed(),
838                                Some(response.1.status),
839                                response.1.request_id.clone(),
840                                None,
841                            );
842                        }
843                        return Ok(response);
844                    }
845                    Err(error) => {
846                        if let Some(audit) = audit {
847                            audit.attempt_finished_with_request_id(
848                                attempt,
849                                attempt_started.elapsed(),
850                                error.status(),
851                                error.request_id().map(str::to_string),
852                                Some(&error),
853                            );
854                        }
855                        let Some(delay) = next_delay(policy, attempt, &error) else {
856                            return Err(error);
857                        };
858                        if let Some(audit) = audit {
859                            audit.retry_scheduled(attempt, attempt + 1, delay, &error);
860                        }
861                        sleep_or_cancel(delay, cancellation).await?;
862                    }
863                }
864            }
865
866            unreachable!("the loop returns on success or on the final error")
867        })
868        .await
869}
870
871pub(crate) async fn send_stream_retry<F, Fut>(
872    provider: &'static str,
873    retry_provider: RetryProvider,
874    policy: &RetryPolicy,
875    audit: Option<&AuditContext>,
876    cancellation: Option<&CancellationToken>,
877    budget: &RequestBudget,
878    mut make_request: F,
879) -> Result<reqwest::Response>
880where
881    F: FnMut() -> Fut,
882    Fut: Future<Output = Result<reqwest::RequestBuilder>>,
883{
884    budget
885        .run(async {
886            if policy.max_attempts == 0 {
887                return Err(Error::InvalidRetryPolicy(
888                    "max_attempts must be at least 1".to_string(),
889                ));
890            }
891
892            for attempt in 0..policy.max_attempts {
893                if cancellation.is_some_and(CancellationToken::is_cancelled) {
894                    return Err(Error::Cancelled);
895                }
896                if let Some(audit) = audit {
897                    audit.attempt_started(attempt);
898                }
899                let attempt_started = Instant::now();
900                let request = match build_request_or_cancel(make_request(), cancellation).await {
901                    Ok(request) => request,
902                    Err(error) => {
903                        if let Some(audit) = audit {
904                            audit.attempt_finished_with_request_id(
905                                attempt,
906                                attempt_started.elapsed(),
907                                None,
908                                None,
909                                Some(&error),
910                            );
911                        }
912                        let Some(delay) = next_delay(policy, attempt, &error) else {
913                            return Err(error);
914                        };
915                        if let Some(audit) = audit {
916                            audit.retry_scheduled(attempt, attempt + 1, delay, &error);
917                        }
918                        sleep_or_cancel(delay, cancellation).await?;
919                        continue;
920                    }
921                };
922
923                let response = match send_request(request, cancellation).await {
924                    Ok(response) => response,
925                    Err(error) => {
926                        if let Some(audit) = audit {
927                            audit.attempt_finished_with_request_id(
928                                attempt,
929                                attempt_started.elapsed(),
930                                error.status(),
931                                None,
932                                Some(&error),
933                            );
934                        }
935                        let Some(delay) = next_delay(policy, attempt, &error) else {
936                            return Err(error);
937                        };
938                        if let Some(audit) = audit {
939                            audit.retry_scheduled(attempt, attempt + 1, delay, &error);
940                        }
941                        sleep_or_cancel(delay, cancellation).await?;
942                        continue;
943                    }
944                };
945
946                let status = response.status();
947                let metadata = ResponseMetadata::from_response(&response);
948                if let Some(audit) = audit {
949                    audit.response_headers(
950                        attempt,
951                        attempt_started.elapsed(),
952                        status.as_u16(),
953                        metadata.request_id.clone(),
954                        status.is_success(),
955                    );
956                }
957                if status.is_success() {
958                    if let Some(content_type) = response.headers().get(CONTENT_TYPE)
959                        && let Ok(content_type) = content_type.to_str()
960                        && !content_type
961                            .to_ascii_lowercase()
962                            .contains("text/event-stream")
963                    {
964                        let error = Error::StreamProtocol(format!(
965                            "{provider} returned {content_type}, expected text/event-stream"
966                        ));
967                        if let Some(audit) = audit {
968                            audit.attempt_finished_with_request_id(
969                                attempt,
970                                attempt_started.elapsed(),
971                                Some(status.as_u16()),
972                                metadata.request_id,
973                                Some(&error),
974                            );
975                        }
976                        return Err(error);
977                    }
978                    if let Some(audit) = audit {
979                        audit.attempt_finished_with_request_id(
980                            attempt,
981                            attempt_started.elapsed(),
982                            Some(status.as_u16()),
983                            metadata.request_id,
984                            None,
985                        );
986                    }
987                    return Ok(response);
988                }
989
990                let retry_directive = parse_retry_headers(retry_provider, response.headers());
991                let retry_after = retry_directive.map(|directive| directive.delay);
992                let retry_source = retry_directive.map(|directive| directive.source);
993                let request_id = ResponseMetadata::from_response(&response).request_id;
994                let body = read_response_text(response, cancellation, budget).await?;
995                if let Some(audit) = audit {
996                    audit.add_response_bytes(body.len());
997                }
998                let error = Error::Api {
999                    provider,
1000                    status: status.as_u16(),
1001                    body,
1002                    retry_after,
1003                    retry_source,
1004                    request_id,
1005                };
1006                if let Some(audit) = audit {
1007                    audit.attempt_finished_with_request_id(
1008                        attempt,
1009                        attempt_started.elapsed(),
1010                        error.status(),
1011                        error.request_id().map(str::to_string),
1012                        Some(&error),
1013                    );
1014                }
1015
1016                let Some(delay) = next_delay(policy, attempt, &error) else {
1017                    return Err(error);
1018                };
1019                if let Some(audit) = audit {
1020                    audit.retry_scheduled(attempt, attempt + 1, delay, &error);
1021                }
1022                sleep_or_cancel(delay, cancellation).await?;
1023            }
1024
1025            unreachable!("the loop returns on success or on the final error")
1026        })
1027        .await
1028}
1029
1030/// Normalize a request with protocol defaults plus profile overrides.
1031///
1032/// System placement is an OpenAI-protocol capability: Anthropic and Gemini
1033/// keep merged top-level system behavior regardless of the profile.
1034pub(crate) fn normalize_for_protocol(
1035    request: &crate::types::ChatRequest,
1036    protocol: crate::normalize::Protocol,
1037    profile: Option<&crate::profile::ProviderProfile>,
1038) -> crate::error::Result<(
1039    crate::normalize::NormalizedChat,
1040    crate::normalize::NormalizeReport,
1041)> {
1042    let mut options = crate::normalize::NormalizeOptions::for_protocol(protocol);
1043    if let Some(profile) = profile
1044        && matches!(
1045            protocol,
1046            crate::normalize::Protocol::OpenAiChat | crate::normalize::Protocol::OpenAiResponses
1047        )
1048    {
1049        options.system_placement = profile.normalize.system_placement;
1050    }
1051    crate::normalize::normalize_with_options(request, options)
1052}
1053
1054#[cfg(test)]
1055mod tool_call_content_tests {
1056    //! 回归:`ToolCallContentMode` 只允许整形**空** content。
1057    //! 0.5.0 及之前会把带 tool_calls 的 assistant 消息的非空 content
1058    //! 一并清掉(Null 置 null / Omit 删键 / Empty 置空串),导致消费方
1059    //! 模型看不到自己历史轮的可见文本。
1060
1061    use super::apply_provider_request_options;
1062    use crate::normalize::Protocol;
1063    use crate::profile::{ProviderRequestOptions, ToolCallContentMode};
1064    use serde_json::{Value, json};
1065
1066    fn sample_body() -> Value {
1067        json!({
1068            "model": "m",
1069            "messages": [
1070                {"role": "user", "content": "hi"},
1071                {
1072                    "role": "assistant",
1073                    "content": "ACK-TEXT",
1074                    "tool_calls": [{"id": "c1", "type": "function",
1075                        "function": {"name": "read", "arguments": "{}"}}]
1076                },
1077                {"role": "tool", "tool_call_id": "c1", "content": "ok"},
1078                {
1079                    "role": "assistant",
1080                    "tool_calls": [{"id": "c2", "type": "function",
1081                        "function": {"name": "read", "arguments": "{}"}}]
1082                }
1083            ]
1084        })
1085    }
1086
1087    #[test]
1088    fn non_empty_content_is_never_clobbered() {
1089        for mode in [
1090            ToolCallContentMode::Auto,
1091            ToolCallContentMode::Null,
1092            ToolCallContentMode::Omit,
1093            ToolCallContentMode::Empty,
1094        ] {
1095            let mut body = sample_body();
1096            apply_provider_request_options(
1097                &mut body,
1098                Protocol::OpenAiChat,
1099                &ProviderRequestOptions {
1100                    tool_call_content: Some(mode),
1101                    ..Default::default()
1102                },
1103                true,
1104            )
1105            .unwrap();
1106            let assistant = &body["messages"][1];
1107            assert_eq!(
1108                assistant["content"], "ACK-TEXT",
1109                "mode {mode:?} clobbered non-empty content"
1110            );
1111        }
1112    }
1113
1114    #[test]
1115    fn empty_content_is_shaped_per_mode() {
1116        for (mode, expect_present, expect_value) in [
1117            (ToolCallContentMode::Auto, false, Value::Null),
1118            (ToolCallContentMode::Null, true, Value::Null),
1119            (ToolCallContentMode::Omit, false, Value::Null),
1120            (ToolCallContentMode::Empty, true, json!("")),
1121        ] {
1122            let mut body = sample_body();
1123            apply_provider_request_options(
1124                &mut body,
1125                Protocol::OpenAiChat,
1126                &ProviderRequestOptions {
1127                    tool_call_content: Some(mode),
1128                    ..Default::default()
1129                },
1130                true,
1131            )
1132            .unwrap();
1133            let assistant = &body["messages"][3];
1134            assert_eq!(
1135                assistant.get("content").is_some(),
1136                expect_present,
1137                "mode {mode:?} content presence"
1138            );
1139            if expect_present {
1140                assert_eq!(assistant["content"], expect_value, "mode {mode:?} value");
1141            }
1142        }
1143    }
1144
1145    #[test]
1146    fn messages_without_tool_calls_are_untouched() {
1147        for mode in [
1148            ToolCallContentMode::Null,
1149            ToolCallContentMode::Omit,
1150            ToolCallContentMode::Empty,
1151        ] {
1152            let mut body = sample_body();
1153            apply_provider_request_options(
1154                &mut body,
1155                Protocol::OpenAiChat,
1156                &ProviderRequestOptions {
1157                    tool_call_content: Some(mode),
1158                    ..Default::default()
1159                },
1160                true,
1161            )
1162            .unwrap();
1163            assert_eq!(body["messages"][0]["content"], "hi");
1164            assert_eq!(body["messages"][2]["content"], "ok");
1165        }
1166    }
1167}
1168