Skip to content
Python
20.3 KB
Raw Blame
//! Typed, sanitized Responses outcomes. This module never retries or executes tools.
use crate::model::{validate_output, Progress};
use futures_util::StreamExt;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use tokio::sync::mpsc;

#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize, clap::ValueEnum)]
#[serde(rename_all = "lowercase")]
pub enum Kind {
    #[default]
    Openai,
    Anthropic,
}
impl Kind {
    pub fn name(self) -> &'static str {
        match self {
            Self::Openai => "openai",
            Self::Anthropic => "anthropic",
        }
    }
    pub fn key_env(self) -> &'static str {
        match self {
            Self::Openai => "OPENAI_API_KEY",
            Self::Anthropic => "ANTHROPIC_API_KEY",
        }
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Failure {
    RateLimit,
    Transient,
    Transport,
    IncompleteStream,
    InvalidResponse,
    ContextOverflow,
    Truncated,
    Authentication,
    Configuration,
    SafetyBlocked,
}
#[derive(Clone, Debug)]
pub struct Error {
    pub kind: Failure,
    pub retry_after: Option<u64>,
    /// Set only on an HTTP rejection, never on an error inside a stream.
    pub http_status: Option<u16>,
    pub request_id: Option<String>,
    pub api: Option<crate::model_api::Api>,
    /// Fixed parser code or an allowlisted upstream code; never arbitrary text.
    pub code: Option<&'static str>,
}

/// Safe structured context. Never contains request/response bodies or credentials.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Diagnostic {
    pub category: Failure,
    pub retryable: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub http_status: Option<u16>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub request_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub api: Option<crate::model_api::Api>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub code: Option<String>,
}

impl std::fmt::Display for Diagnostic {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Provider {:?}", self.category)?;
        if let Some(status) = self.http_status {
            write!(f, " (HTTP {status})")?;
        }
        if let Some(id) = &self.request_id {
            write!(f, "; request {id}")?;
        }
        if let Some(code) = &self.code {
            write!(f, "; {code}")?;
        }
        Ok(())
    }
}

/// Request IDs are identifiers, not arbitrary upstream diagnostic text.
pub(crate) fn request_id(headers: &reqwest::header::HeaderMap, key: &str) -> Option<String> {
    ["x-request-id", "request-id"].into_iter().find_map(|name| {
        let id = headers.get(name)?.to_str().ok()?;
        (!id.is_empty()
            && id.len() <= 128
            && id
                .bytes()
                .all(|b| b.is_ascii_alphanumeric() || b"-_:".contains(&b))
            && !id.starts_with("sk-")
            && (key.is_empty() || !id.contains(key)))
        .then(|| id.to_owned())
    })
}
impl std::fmt::Display for Error {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "{}; no tool actions accepted from this attempt",
            self.diagnostic()
        )
    }
}
impl std::error::Error for Error {}
impl Error {
    pub fn new(kind: Failure) -> Self {
        Self {
            kind,
            retry_after: None,
            http_status: None,
            request_id: None,
            api: None,
            code: match kind {
                Failure::InvalidResponse => Some("invalid_response"),
                Failure::IncompleteStream => Some("incomplete_stream"),
                _ => None,
            },
        }
    }
    pub fn diagnostic(&self) -> Diagnostic {
        Diagnostic {
            category: self.kind,
            retryable: self.retryable(),
            http_status: self.http_status,
            request_id: self.request_id.clone(),
            api: self.api,
            code: self.code.map(str::to_owned),
        }
    }
    pub fn with_api(mut self, api: crate::model_api::Api) -> Self {
        self.api = Some(api);
        self
    }
    pub fn with_code(mut self, code: &'static str) -> Self {
        self.code = Some(code);
        self
    }
    pub fn retryable(&self) -> bool {
        matches!(
            self.kind,
            Failure::RateLimit
                | Failure::Transient
                | Failure::Transport
                | Failure::IncompleteStream
        ) && self.retry_after.is_none_or(|s| s <= 30)
    }
}

pub(crate) fn upstream_code(value: &Value) -> Option<&'static str> {
    const CODES: &[&str] = &[
        "invalid_api_key",
        "authentication_error",
        "permission_error",
        "invalid_request_error",
        "rate_limit_exceeded",
        "rate_limit_error",
        "insufficient_quota",
        "context_length_exceeded",
        "server_error",
        "api_error",
        "overloaded_error",
        "misalignment_policy_violation",
        "RESOURCE_EXHAUSTED",
        "INVALID_ARGUMENT",
        "UNAUTHENTICATED",
        "PERMISSION_DENIED",
    ];
    CODES
        .iter()
        .copied()
        .find(|code| value["code"] == *code || value["type"] == *code || value["status"] == *code)
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ReasoningKind {
    Summary,
    Thinking,
}

/// Provider-designated display text only. Opaque signatures never enter this type.
#[derive(Clone, Debug)]
pub struct ReasoningDelta {
    pub kind: ReasoningKind,
    pub text: String,
    pub block_index: u64,
}

#[cfg(test)]
mod diagnostics_tests {
    use super::*;
    use serde_json::json;
    #[test]
    fn safe_diagnostics_exclude_credentials_and_unbounded_header_text() {
        let mut headers = reqwest::header::HeaderMap::new();
        for value in [
            "sk-secret-token",
            "Bearer token",
            "arbitrary\ttext",
            "credential-sentinel",
        ] {
            headers.insert("x-request-id", value.parse().unwrap());
            assert!(request_id(&headers, "credential-sentinel").is_none());
        }
        headers.insert("x-request-id", "req_fixture-123".parse().unwrap());
        assert_eq!(
            request_id(&headers, "credential-sentinel").as_deref(),
            Some("req_fixture-123")
        );
        let mut e = Error::new(Failure::RateLimit).with_api(crate::model_api::Api::Responses);
        e.http_status = Some(429);
        e.request_id = request_id(&headers, "");
        assert_eq!(
            serde_json::to_value(e.diagnostic()).unwrap(),
            json!({"category":"rate_limit","retryable":true,"http_status":429,"request_id":"req_fixture-123","api":"responses"})
        );
    }
    #[test]
    fn responses_only_exposes_designated_summary_deltas() {
        let mut d = Decoder::default();
        for event in [
            json!({"type":"response.reasoning_text.delta","delta":"hidden"}),
            json!({"type":"response.output_item.added","item":{"type":"reasoning","encrypted_content":"opaque"}}),
        ] {
            assert!(d.event(&event).unwrap().is_none());
            assert!(d.take_reasoning().is_none());
        }
        d.event(&json!({"type":"response.reasoning_summary_text.delta","delta":"Display summary","output_index":0})).unwrap();
        let delta = d.take_reasoning().unwrap();
        assert_eq!(delta.kind, ReasoningKind::Summary);
        assert_eq!(delta.text, "Display summary");
        assert!(d.take_reasoning().is_none());
    }
}
#[derive(Clone, Debug, Default, Serialize, Deserialize)]
pub struct Usage {
    pub input_tokens: u64,
    pub output_tokens: u64,
    pub cached_input_tokens: u64,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cache_read_input_tokens: Option<u64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cache_write_input_tokens: Option<u64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reasoning_output_tokens: Option<u64>,
}
impl Usage {
    pub fn reported(&self) -> crate::telemetry::TokenUsage {
        let bounded = |n: u64| (n <= i64::MAX as u64).then_some(n);
        let mut u = crate::telemetry::TokenUsage {
            input: bounded(self.input_tokens),
            output: bounded(self.output_tokens),
            cache_read: self
                .cache_read_input_tokens
                .filter(|n| *n <= self.input_tokens),
            cache_write: self
                .cache_write_input_tokens
                .filter(|n| *n <= self.input_tokens),
            reasoning: self
                .reasoning_output_tokens
                .filter(|n| *n <= self.output_tokens),
        };
        if u.cache_read
            .zip(u.cache_write)
            .is_some_and(|(a, b)| a.checked_add(b).is_none_or(|n| n > self.input_tokens))
        {
            u.cache_read = None;
            u.cache_write = None;
        }
        if !u.validate() {
            crate::telemetry::TokenUsage::default()
        } else {
            u
        }
    }
}
fn response_usage(u: &Value) -> Option<Usage> {
    Some(Usage {
        input_tokens: u["input_tokens"].as_u64()?,
        output_tokens: u["output_tokens"].as_u64()?,
        cached_input_tokens: u["input_tokens_details"]["cached_tokens"]
            .as_u64()
            .unwrap_or(0),
        cache_read_input_tokens: u["input_tokens_details"]["cached_tokens"].as_u64(),
        cache_write_input_tokens: None,
        reasoning_output_tokens: u["output_tokens_details"]["reasoning_tokens"].as_u64(),
    })
}
#[derive(Clone, Debug)]
pub struct Completion {
    pub output: Vec<Value>,
    pub usage: Option<Usage>,
}

pub fn classify(status: u16, code: &str) -> Failure {
    match code {
        "misalignment_policy_violation" => Failure::SafetyBlocked,
        "context_length_exceeded" => Failure::ContextOverflow,
        "rate_limit_exceeded" => Failure::RateLimit,
        "insufficient_quota" => Failure::Configuration,
        "invalid_api_key" | "authentication_error" => Failure::Authentication,
        "invalid_request_error" => Failure::Configuration,
        "server_error" => Failure::Transient,
        _ => match status {
            401 | 403 => Failure::Authentication,
            408 | 409 | 500 | 502 | 503 | 504 => Failure::Transient,
            429 => Failure::RateLimit,
            _ => Failure::Configuration,
        },
    }
}

/// Exposed as a pure seam for recorded-event and fault-injection tests.
#[derive(Default)]
pub struct Decoder {
    completion: Option<Completion>,
    reported: Option<Usage>,
    output_started: bool,
    reasoning: Option<ReasoningDelta>,
}
impl Decoder {
    pub fn event(&mut self, event: &Value) -> Result<Option<String>, Error> {
        if let Some(u) = response_usage(&event["response"]["usage"]) {
            self.reported = Some(u);
        }
        if matches!(
            event["type"].as_str(),
            Some("response.output_text.delta" | "response.function_call_arguments.delta")
        ) && event["delta"].as_str().is_some_and(|s| !s.is_empty())
            || event["type"] == "response.output_item.added"
                && event["item"]["type"] == "function_call"
                && event["item"]["name"].is_string()
        {
            self.output_started = true;
        }
        if event["response"]["error"]["code"] == "misalignment_policy_violation"
            || event["code"] == "misalignment_policy_violation"
        {
            self.completion = None;
            return Err(Error::new(Failure::SafetyBlocked));
        }
        if self.completion.is_some() {
            return Err(Error::new(Failure::InvalidResponse));
        }
        match event["type"].as_str().unwrap_or("") {
            "response.reasoning_summary_text.delta" => {
                self.reasoning = Some(ReasoningDelta {
                    kind: ReasoningKind::Summary,
                    text: event["delta"]
                        .as_str()
                        .ok_or_else(|| Error::new(Failure::InvalidResponse))?
                        .to_owned(),
                    block_index: event["output_index"]
                        .as_u64()
                        .ok_or_else(|| Error::new(Failure::InvalidResponse))?,
                });
                Ok(None)
            }
            "response.output_text.delta" => Ok(Some(
                event["delta"]
                    .as_str()
                    .ok_or_else(|| Error::new(Failure::InvalidResponse))?
                    .to_owned(),
            )),
            "response.completed" => {
                let r = &event["response"];
                if r["status"] != "completed" {
                    return Err(Error::new(Failure::InvalidResponse));
                }
                let output = r["output"]
                    .as_array()
                    .cloned()
                    .ok_or_else(|| Error::new(Failure::InvalidResponse))?;
                if output.is_empty() || validate_output(&output).is_err() {
                    return Err(Error::new(Failure::InvalidResponse));
                }
                let usage = if r["usage"]["input_tokens"].is_u64()
                    && r["usage"]["output_tokens"].is_u64()
                {
                    Some(Usage {
                        input_tokens: r["usage"]["input_tokens"].as_u64().unwrap(),
                        output_tokens: r["usage"]["output_tokens"].as_u64().unwrap(),
                        cached_input_tokens: r["usage"]["input_tokens_details"]["cached_tokens"]
                            .as_u64()
                            .unwrap_or(0),
                        cache_read_input_tokens: r["usage"]["input_tokens_details"]
                            ["cached_tokens"]
                            .as_u64(),
                        cache_write_input_tokens: None,
                        reasoning_output_tokens: r["usage"]["output_tokens_details"]
                            ["reasoning_tokens"]
                            .as_u64(),
                    })
                } else {
                    None
                };
                self.completion = Some(Completion { output, usage });
                Ok(None)
            }
            "response.incomplete" => Err(Error::new(
                if event["response"]["incomplete_details"]["reason"] == "max_output_tokens" {
                    Failure::Truncated
                } else {
                    Failure::InvalidResponse
                },
            )),
            "response.failed" | "error" => {
                let code = event["response"]["error"]["code"]
                    .as_str()
                    .or(event["code"].as_str())
                    .unwrap_or("");
                Err(Error::new(classify(0, code)))
            }
            _ => Ok(None),
        }
    }
    pub fn finish(self) -> Result<Completion, Error> {
        self.completion
            .ok_or_else(|| Error::new(Failure::IncompleteStream))
    }
}

pub async fn request(
    client: &reqwest::Client,
    url: &str,
    key: &str,
    body: Value,
    tx: mpsc::Sender<Progress>,
) -> Result<(), Error> {
    request_decoded(client, url, key, body, tx, Decoder::default()).await
}

pub(crate) trait StreamDecoder {
    fn event(&mut self, value: &Value) -> Result<Option<String>, Error>;
    fn done(&mut self) -> Result<(), Error> {
        Ok(())
    }
    fn finish(self) -> Result<Completion, Error>;
    fn usage_report(&self) -> Option<crate::telemetry::TokenUsage> {
        None
    }
    fn output_started(&self) -> bool {
        false
    }
    fn take_reasoning(&mut self) -> Option<ReasoningDelta> {
        None
    }
}
impl StreamDecoder for Decoder {
    fn take_reasoning(&mut self) -> Option<ReasoningDelta> {
        self.reasoning.take()
    }
    fn usage_report(&self) -> Option<crate::telemetry::TokenUsage> {
        self.reported.as_ref().map(Usage::reported)
    }
    fn output_started(&self) -> bool {
        self.output_started
    }
    fn event(&mut self, value: &Value) -> Result<Option<String>, Error> {
        self.event(value)
    }
    fn finish(self) -> Result<Completion, Error> {
        self.finish()
    }
}
pub(crate) async fn request_decoded<D: StreamDecoder>(
    client: &reqwest::Client,
    url: &str,
    key: &str,
    body: Value,
    tx: mpsc::Sender<Progress>,
    mut decoder: D,
) -> Result<(), Error> {
    let request = client.post(url);
    let request = if key.is_empty() {
        request
    } else {
        request.bearer_auth(key)
    };
    let response = request
        .json(&body)
        .send()
        .await
        .map_err(|_| Error::new(Failure::Transport))?;
    if !response.status().is_success() {
        let status = response.status().as_u16();
        let request_id = request_id(response.headers(), key);
        let retry_after = response
            .headers()
            .get("retry-after")
            .and_then(|h| h.to_str().ok())
            .and_then(|h| h.parse().ok());
        let mut stream = response.bytes_stream();
        let mut bytes = vec![];
        while let Some(chunk) = stream.next().await {
            let chunk = chunk.map_err(|_| Error {
                kind: classify(status, ""),
                retry_after,
                http_status: Some(status),
                request_id: request_id.clone(),
                api: None,
                code: Some("http_error_body_unavailable"),
            })?;
            if bytes.len() + chunk.len() > 16384 {
                break;
            }
            bytes.extend_from_slice(&chunk);
        }
        let error: Value = serde_json::from_slice(&bytes).unwrap_or(Value::Null);
        return Err(Error {
            kind: classify(status, error["error"]["code"].as_str().unwrap_or("")),
            retry_after,
            http_status: Some(status),
            request_id,
            api: None,
            code: upstream_code(&error["error"]),
        });
    }
    let mut stream = response.bytes_stream();
    let mut buffer = vec![];
    let mut total = 0usize;
    let mut previous_usage = None;
    let mut first_sent = false;
    while let Some(chunk) = stream.next().await {
        let chunk = chunk.map_err(|_| Error::new(Failure::Transport))?;
        total += chunk.len();
        if total > 8 * 1024 * 1024 {
            return Err(Error::new(Failure::InvalidResponse));
        }
        buffer.extend_from_slice(&chunk);
        while let Some(i) = buffer.iter().position(|&c| c == b'\n') {
            let line = buffer.drain(..=i).collect::<Vec<_>>();
            let line = std::str::from_utf8(&line)
                .map_err(|_| Error::new(Failure::InvalidResponse))?
                .trim();
            let Some(data) = line.strip_prefix("data:") else {
                continue;
            };
            if data.trim() == "[DONE]" {
                decoder.done()?;
                continue;
            }
            let event: Value = serde_json::from_str(data).map_err(|_| {
                Error::new(Failure::InvalidResponse).with_code("invalid_stream_json")
            })?;
            let decoded = decoder.event(&event);
            if let Some(usage) = decoder
                .usage_report()
                .filter(|u| u.present() && Some(*u) != previous_usage)
            {
                tx.send(Progress::Usage(usage))
                    .await
                    .map_err(|_| Error::new(Failure::Transport))?;
                previous_usage = Some(usage);
            }
            let decoded = decoded?;
            if let Some(delta) = decoder.take_reasoning() {
                tx.send(Progress::Reasoning(delta))
                    .await
                    .map_err(|_| Error::new(Failure::Transport))?;
            }
            if !first_sent && decoder.output_started() {
                tx.send(Progress::OutputStarted)
                    .await
                    .map_err(|_| Error::new(Failure::Transport))?;
                first_sent = true;
            }
            if let Some(text) = decoded {
                tx.send(Progress::Delta(text))
                    .await
                    .map_err(|_| Error::new(Failure::Transport))?;
            }
        }
    }
    if !buffer.iter().all(u8::is_ascii_whitespace) {
        return Err(Error::new(Failure::InvalidResponse));
    }
    tx.send(Progress::Complete(decoder.finish()?))
        .await
        .map_err(|_| Error::new(Failure::Transport))?;
    Ok(())
}