Skip to main content

agent_framework_openai/
responses.rs

1//! [`OpenAIChatClient`]: a [`ChatClient`] for the OpenAI Responses API
2//! (`POST /v1/responses`).
3//!
4//! The Responses API uses an item-based `input`/`output` shape rather than
5//! the `messages` array used by Chat Completions, and supports a dedicated
6//! `previous_response_id` for service-side conversation state. Wire framing
7//! (SSE parsing style, error handling) mirrors [`crate::OpenAIChatCompletionClient`].
8//!
9//! ```no_run
10//! use agent_framework_openai::responses::OpenAIChatClient;
11//! use agent_framework_core::prelude::*;
12//!
13//! # async fn demo() -> Result<()> {
14//! let client = OpenAIChatClient::new("sk-...", "gpt-4o-mini");
15//! let agent = Agent::builder(client)
16//!     .instructions("You are concise.")
17//!     .build();
18//! let reply = agent.run_once("Say hi").await?;
19//! println!("{}", reply.text());
20//! # Ok(())
21//! # }
22//! ```
23
24use std::collections::{HashMap, VecDeque};
25use std::sync::Arc;
26
27use agent_framework_core::client::{ChatClient, ChatStream};
28use agent_framework_core::error::{Error, Result};
29use agent_framework_core::streaming::Utf8StreamDecoder;
30use agent_framework_core::tools::ToolDefinition;
31use agent_framework_core::types::{
32    Annotation, ChatOptions, ChatResponse, ChatResponseUpdate, Content, DataContent, FinishReason,
33    FunctionApprovalRequestContent, FunctionArguments, FunctionCallContent, FunctionResultContent,
34    Message, ResponseFormat, Role, TextContent, TextReasoningContent, TextSpanRegion, ToolMode,
35    UriContent, UsageContent, UsageDetails,
36};
37use futures::StreamExt;
38use serde_json::{json, Map, Value};
39
40use crate::convert::{
41    audio_format, data_content_media_type, function_arguments_to_string, result_to_string,
42    top_level_media_type, DEFAULT_FILENAME,
43};
44use crate::{ByteStream, DEFAULT_BASE_URL};
45
46/// An OpenAI Responses API chat client (`POST /v1/responses`).
47#[derive(Clone)]
48pub struct OpenAIChatClient {
49    inner: Arc<Inner>,
50}
51
52#[derive(Clone)]
53struct Inner {
54    http: reqwest::Client,
55    api_key: String,
56    base_url: String,
57    model: String,
58    organization: Option<String>,
59}
60
61impl std::fmt::Debug for OpenAIChatClient {
62    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
63        f.debug_struct("OpenAIChatClient")
64            .field("base_url", &self.inner.base_url)
65            .field("model", &self.inner.model)
66            .field("organization", &self.inner.organization)
67            .finish_non_exhaustive()
68    }
69}
70
71impl OpenAIChatClient {
72    /// Create a client for the given API key and default model.
73    pub fn new(api_key: impl Into<String>, model: impl Into<String>) -> Self {
74        Self {
75            inner: Arc::new(Inner {
76                http: reqwest::Client::new(),
77                api_key: api_key.into(),
78                base_url: DEFAULT_BASE_URL.to_string(),
79                model: model.into(),
80                organization: None,
81            }),
82        }
83    }
84
85    /// Build a client from the `OPENAI_API_KEY` (and optional
86    /// `OPENAI_BASE_URL`) environment variables.
87    pub fn from_env(model: impl Into<String>) -> Result<Self> {
88        let key = std::env::var("OPENAI_API_KEY")
89            .map_err(|_| Error::Configuration("OPENAI_API_KEY is not set".into()))?;
90        let mut client = Self::new(key, model);
91        if let Ok(base) = std::env::var("OPENAI_BASE_URL") {
92            client = client.with_base_url(base);
93        }
94        Ok(client)
95    }
96
97    /// Override the base URL (for Azure OpenAI or compatible servers).
98    pub fn with_base_url(mut self, base_url: impl Into<String>) -> Self {
99        Arc::make_mut(&mut self.inner).base_url = base_url.into();
100        self
101    }
102
103    /// Set the organization header.
104    pub fn with_organization(mut self, org: impl Into<String>) -> Self {
105        Arc::make_mut(&mut self.inner).organization = Some(org.into());
106        self
107    }
108
109    /// The default model id.
110    pub fn model(&self) -> &str {
111        &self.inner.model
112    }
113
114    fn build_body(&self, messages: &[Message], options: &ChatOptions, stream: bool) -> Value {
115        let mut body = Map::new();
116        let model = options
117            .model
118            .clone()
119            .unwrap_or_else(|| self.inner.model.clone());
120        body.insert("model".into(), json!(model));
121
122        let (instructions, rest) = extract_instructions(messages, options.instructions.as_deref());
123        if let Some(instructions) = instructions {
124            body.insert("instructions".into(), json!(instructions));
125        }
126        body.insert("input".into(), json!(messages_to_input(rest)));
127
128        if let Some(conversation_id) = &options.conversation_id {
129            body.insert("previous_response_id".into(), json!(conversation_id));
130        }
131        if let Some(t) = options.temperature {
132            body.insert("temperature".into(), json!(t));
133        }
134        if let Some(t) = options.top_p {
135            body.insert("top_p".into(), json!(t));
136        }
137        if let Some(mt) = options.max_tokens {
138            body.insert("max_output_tokens".into(), json!(mt));
139        }
140        if let Some(store) = options.store {
141            body.insert("store".into(), json!(store));
142        }
143        if let Some(user) = &options.user {
144            body.insert("user".into(), json!(user));
145        }
146        if let Some(metadata) = &options.metadata {
147            body.insert("metadata".into(), json!(metadata));
148        }
149
150        if !options.tools.is_empty() {
151            let tools: Vec<Value> = options.tools.iter().map(tool_to_responses_spec).collect();
152            body.insert("tools".into(), json!(tools));
153            if let Some(allow_multi) = options.allow_multiple_tool_calls {
154                body.insert("parallel_tool_calls".into(), json!(allow_multi));
155            }
156        }
157        if let Some(tool_choice) = &options.tool_choice {
158            body.insert("tool_choice".into(), tool_choice_to_responses(tool_choice));
159        }
160        if let Some(fmt) = &options.response_format {
161            body.insert(
162                "text".into(),
163                json!({ "format": response_format_to_text(fmt) }),
164            );
165        }
166
167        // Inserted before the `additional_properties` pass below, whose
168        // A caller's own `include` entries are already folded in here.
169        if let Some(include) = responses_include(options, true) {
170            body.insert("include".into(), include);
171        }
172
173        for (k, v) in &options.additional_properties {
174            // `include` belongs to `responses_include` alone. Letting it
175            // through would resurrect a value that function deliberately
176            // dropped — an explicit empty array would land as `include: []`,
177            // the one shape it exists to avoid.
178            if k == "include" {
179                continue;
180            }
181            body.entry(k.clone()).or_insert_with(|| v.clone());
182        }
183
184        if stream {
185            body.insert("stream".into(), json!(true));
186        }
187        Value::Object(body)
188    }
189
190    async fn post(&self, body: &Value) -> Result<reqwest::Response> {
191        let url = format!("{}/responses", self.inner.base_url.trim_end_matches('/'));
192        let mut req = self
193            .inner
194            .http
195            .post(&url)
196            .bearer_auth(&self.inner.api_key)
197            .json(body);
198        if let Some(org) = &self.inner.organization {
199            req = req.header("OpenAI-Organization", org);
200        }
201        let resp = req
202            .send()
203            .await
204            .map_err(|e| Error::service(format!("request failed: {e}")))?;
205        if !resp.status().is_success() {
206            let status = resp.status();
207            let retry_after = crate::parse_retry_after(resp.headers());
208            let text = resp.text().await.unwrap_or_default();
209            return Err(crate::classify_service_error(
210                status.as_u16(),
211                &text,
212                format!("OpenAI API error {status}: {text}"),
213                retry_after,
214            ));
215        }
216        Ok(resp)
217    }
218}
219
220#[async_trait::async_trait]
221impl ChatClient for OpenAIChatClient {
222    async fn get_response(
223        &self,
224        messages: Vec<Message>,
225        options: ChatOptions,
226    ) -> Result<ChatResponse> {
227        let body = self.build_body(&messages, &options, false);
228        let resp = self.post(&body).await?;
229        let value: Value = resp
230            .json()
231            .await
232            .map_err(|e| Error::service(format!("invalid response json: {e}")))?;
233        if let Some(err) = response_failure_error(&value) {
234            return Err(err);
235        }
236        Ok(parse_response(&value, options.store))
237    }
238
239    async fn get_streaming_response(
240        &self,
241        messages: Vec<Message>,
242        options: ChatOptions,
243    ) -> Result<ChatStream> {
244        let body = self.build_body(&messages, &options, true);
245        let resp = self.post(&body).await?;
246        Ok(parse_responses_sse_stream(resp, options.store).boxed())
247    }
248
249    fn model(&self) -> Option<&str> {
250        Some(&self.inner.model)
251    }
252}
253
254// region: request conversion
255
256/// The `include` entry that asks a reasoning model to return its *encrypted*
257/// reasoning item alongside the summary.
258pub const ENCRYPTED_REASONING_INCLUDE: &str = "reasoning.encrypted_content";
259
260/// Build the Responses request's `include` array.
261///
262/// A reasoning item must be replayed verbatim on the follow-up turn of a tool
263/// loop, and the service only accepts it when it carries its `id` *and*
264/// `encrypted_content`. When the conversation is held service-side the model
265/// already has that item, but on a stateless request nothing is stored — so
266/// unless the request asks for `reasoning.encrypted_content`, the item comes
267/// back without it and the replay in [`messages_to_input`] has nothing valid
268/// to re-send. This adds it implicitly in exactly that case, mirroring
269/// upstream's `_prepare_options`.
270///
271/// A caller's own `include` entries (passed through
272/// `ChatOptions::additional_properties`) are always preserved, and an explicit
273/// `reasoning.encrypted_content` is honored even when `implicit` is `false` —
274/// `implicit` gates only whether it is added on the caller's behalf. Foundry
275/// passes `false` here: it does not want encrypted reasoning unless asked for
276/// it by name (upstream #7536).
277///
278/// Returns `None` when the array would be empty, so a request that needs no
279/// `include` does not carry an empty one.
280///
281/// `pub` for the same reason as [`extract_instructions`]: `agent-framework-azure`'s
282/// Responses client builds its own body and reuses this step rather than
283/// reimplementing it.
284pub fn responses_include(options: &ChatOptions, implicit: bool) -> Option<Value> {
285    let mut include: Vec<Value> = options
286        .additional_properties
287        .get("include")
288        .and_then(Value::as_array)
289        .cloned()
290        .unwrap_or_default();
291
292    // Upstream keys this off the service-side-storage indicators, not `store`:
293    // a request continuing a stored conversation needs nothing echoed back.
294    let uses_service_side_storage = options
295        .conversation_id
296        .as_deref()
297        .is_some_and(|id| !id.is_empty());
298
299    let already_present = include
300        .iter()
301        .any(|v| v.as_str() == Some(ENCRYPTED_REASONING_INCLUDE));
302    if implicit && !uses_service_side_storage && !already_present {
303        include.push(json!(ENCRYPTED_REASONING_INCLUDE));
304    }
305
306    (!include.is_empty()).then(|| json!(include))
307}
308
309/// Split a leading system message (and/or `ChatOptions::instructions`) out
310/// into the Responses API's top-level `instructions` field, returning the
311/// remaining messages to convert into `input` items.
312///
313/// `pub` (rather than private) so `agent-framework-azure`'s Responses client
314/// can reuse this exact instructions-extraction step ahead of
315/// [`messages_to_input`] when building the Azure OpenAI Responses request
316/// body, instead of reimplementing it.
317pub fn extract_instructions<'a>(
318    messages: &'a [Message],
319    options_instructions: Option<&str>,
320) -> (Option<String>, &'a [Message]) {
321    let mut parts = Vec::new();
322    if let Some(instr) = options_instructions {
323        if !instr.is_empty() {
324            parts.push(instr.to_string());
325        }
326    }
327    let mut rest = messages;
328    if let Some(first) = messages.first() {
329        if first.role == Role::system() {
330            let text = first.text();
331            if !text.is_empty() {
332                parts.push(text);
333            }
334            rest = &messages[1..];
335        }
336    }
337    if parts.is_empty() {
338        (None, rest)
339    } else {
340        (Some(parts.join("\n\n")), rest)
341    }
342}
343
344/// Convert framework messages into the Responses API's `input` item array.
345///
346/// `pub` so `agent-framework-azure`'s Responses client can reuse this
347/// conversion verbatim rather than reimplementing it (Azure OpenAI's
348/// Responses API shares the exact same `input` item wire shape).
349pub fn messages_to_input(messages: &[Message]) -> Vec<Value> {
350    let mut out = Vec::new();
351    for msg in messages {
352        let role = msg.role.as_str();
353        if role == Role::TOOL {
354            for content in &msg.contents {
355                if let Content::FunctionResult(fr) = content {
356                    out.push(function_result_to_item(fr));
357                }
358            }
359            continue;
360        }
361
362        let mut buffered: Vec<Value> = Vec::new();
363        for content in &msg.contents {
364            match content {
365                // A refusal is its own output content part — `{"type":
366                // "refusal", "refusal": "..."}` — sitting beside `output_text`
367                // in an output message. Re-emitting it as `output_text` would
368                // replay a decline to the provider as an answer. Only
369                // meaningful on the assistant side: an *input* message's
370                // content list admits only input_text/input_image/input_file,
371                // so a refusal on any other role has no wire form and is
372                // dropped rather than mis-encoded.
373                Content::Text(t) if t.refusal => {
374                    if role == Role::ASSISTANT {
375                        buffered.push(json!({ "type": "refusal", "refusal": t.text }));
376                    }
377                }
378                Content::Text(t) => {
379                    let text_type = if role == Role::ASSISTANT {
380                        "output_text"
381                    } else {
382                        "input_text"
383                    };
384                    buffered.push(json!({ "type": text_type, "text": t.text }));
385                }
386                Content::Uri(u) => {
387                    if let Some(part) = content_to_input_part(&u.uri, Some(&u.media_type)) {
388                        buffered.push(part);
389                    }
390                }
391                Content::Data(d) => {
392                    if let Some(part) =
393                        content_to_input_part(&d.uri, data_content_media_type(d).as_deref())
394                    {
395                        buffered.push(part);
396                    }
397                }
398                Content::HostedFile(h) => {
399                    buffered.push(json!({ "type": "input_file", "file_id": h.file_id }));
400                }
401                Content::FunctionCall(fc) => {
402                    flush_text(&mut out, &mut buffered, role);
403                    out.push(json!({
404                        "type": "function_call",
405                        "call_id": fc.call_id,
406                        "name": fc.name,
407                        "arguments": function_arguments_to_string(&fc.arguments),
408                    }));
409                }
410                Content::FunctionResult(fr) => {
411                    flush_text(&mut out, &mut buffered, role);
412                    out.push(function_result_to_item(fr));
413                }
414                Content::FunctionApprovalResponse(r) => {
415                    flush_text(&mut out, &mut buffered, role);
416                    out.push(json!({
417                        "type": "mcp_approval_response",
418                        "approval_request_id": r.id,
419                        "approve": r.approved,
420                    }));
421                }
422                Content::FunctionApprovalRequest(r) => {
423                    flush_text(&mut out, &mut buffered, role);
424                    out.push(json!({
425                        "type": "mcp_approval_request",
426                        "id": r.id,
427                        "name": r.function_call.name,
428                        "arguments": function_arguments_to_string(&r.function_call.arguments),
429                    }));
430                }
431                Content::TextReasoning(tr) => {
432                    // Re-emit the original reasoning item verbatim (store:false
433                    // replay). A summary-only reasoning content with no
434                    // preserved item has no valid input form (it lacks the
435                    // required id/encrypted_content), so it is dropped.
436                    if let Some(raw) = &tr.raw_representation {
437                        flush_text(&mut out, &mut buffered, role);
438                        out.push(raw.clone());
439                    }
440                }
441                _ => {}
442            }
443        }
444        flush_text(&mut out, &mut buffered, role);
445    }
446    out
447}
448
449/// Map a URI/data content item to a Responses API input content part, or `None`
450/// when it has no wire mapping (mirrors upstream `_openai_content_parser`).
451/// Handles images (`input_image`), audio (`input_audio`), and `application/*`
452/// data (`input_file`).
453fn content_to_input_part(uri: &str, media_type: Option<&str>) -> Option<Value> {
454    let media_type = media_type?;
455    match top_level_media_type(media_type).as_str() {
456        // `detail` defaults to "auto"; the Rust content types carry no override.
457        "image" => Some(json!({
458            "type": "input_image",
459            "image_url": uri,
460            "detail": "auto",
461        })),
462        "audio" => {
463            let format = audio_format(media_type)?;
464            // `input_audio.data` is the raw base64 payload, not a data URI —
465            // same wire rule as the Chat Completions converter.
466            Some(json!({
467                "type": "input_audio",
468                "input_audio": {
469                    "data": crate::convert::strip_data_uri_prefix(uri),
470                    "format": format,
471                },
472            }))
473        }
474        "application" => Some(json!({
475            "type": "input_file",
476            "file_data": uri,
477            "filename": DEFAULT_FILENAME,
478        })),
479        _ => None,
480    }
481}
482
483fn flush_text(out: &mut Vec<Value>, buffered: &mut Vec<Value>, role: &str) {
484    if !buffered.is_empty() {
485        out.push(json!({ "type": "message", "role": role, "content": std::mem::take(buffered) }));
486    }
487}
488
489fn function_result_to_item(fr: &FunctionResultContent) -> Value {
490    json!({
491        "type": "function_call_output",
492        "call_id": fr.call_id,
493        "output": result_to_string(fr),
494    })
495}
496
497/// The flat Responses-API tool spec: `{"type":"function","name":...}`, unlike
498/// Chat Completions' `{"type":"function","function":{...}}` nesting.
499///
500/// `pub` so `agent-framework-azure`'s Responses client can reuse this
501/// mapping rather than reimplementing it.
502pub fn tool_to_responses_spec(tool: &ToolDefinition) -> Value {
503    use agent_framework_core::tools::ToolKind;
504    match &tool.kind {
505        ToolKind::HostedWebSearch => {
506            let mut spec = Map::new();
507            spec.insert("type".into(), json!("web_search"));
508            if let Some(loc) = tool.parameters.get("user_location") {
509                spec.insert("user_location".into(), user_location_to_responses(loc));
510            }
511            Value::Object(spec)
512        }
513        ToolKind::HostedCodeInterpreter => {
514            let mut spec = Map::new();
515            spec.insert("type".into(), json!("code_interpreter"));
516            // A caller-supplied `container` wins; otherwise default to `auto`
517            // and attach any `file_ids` (`_responses_client.py:264-278`).
518            if let Some(container) = tool.parameters.get("container") {
519                spec.insert("container".into(), container.clone());
520            } else {
521                let mut container = Map::new();
522                container.insert("type".into(), json!("auto"));
523                if let Some(file_ids) = tool.parameters.get("file_ids") {
524                    container.insert("file_ids".into(), file_ids.clone());
525                }
526                spec.insert("container".into(), Value::Object(container));
527            }
528            Value::Object(spec)
529        }
530        ToolKind::HostedFileSearch { max_results } => {
531            let mut spec = Map::new();
532            spec.insert("type".into(), json!("file_search"));
533            // The Responses API requires vector-store ids; the marker itself
534            // carries none, so honor ids supplied via the definition's
535            // parameters object when present.
536            if let Some(ids) = tool.parameters.get("vector_store_ids") {
537                spec.insert("vector_store_ids".into(), ids.clone());
538            }
539            // Prefer the marker's `max_results`; fall back to a parameters key.
540            let max = (*max_results)
541                .map(|n| json!(n))
542                .or_else(|| tool.parameters.get("max_results").cloned());
543            if let Some(n) = max {
544                spec.insert("max_num_results".into(), n);
545            }
546            Value::Object(spec)
547        }
548        ToolKind::HostedMcp { url, allowed_tools } => {
549            let mut spec = Map::new();
550            spec.insert("type".into(), json!("mcp"));
551            spec.insert("server_label".into(), json!(tool.name.replace(' ', "_")));
552            spec.insert("server_url".into(), json!(url));
553            if !tool.description.is_empty() {
554                spec.insert("server_description".into(), json!(tool.description));
555            }
556            if let Some(headers) = tool.parameters.get("headers") {
557                spec.insert("headers".into(), headers.clone());
558            }
559            if let Some(allowed) = allowed_tools {
560                spec.insert("allowed_tools".into(), json!(allowed));
561            }
562            spec.insert("require_approval".into(), mcp_require_approval(tool));
563            Value::Object(spec)
564        }
565        ToolKind::HostedImageGeneration => {
566            let mut spec = Map::new();
567            spec.insert("type".into(), json!("image_generation"));
568            // Pass through any caller-supplied generation options (size,
569            // quality, background, …) carried on the marker's parameters.
570            if let Value::Object(params) = &tool.parameters {
571                for (k, v) in params {
572                    if k != "type" && k != "properties" {
573                        spec.insert(k.clone(), v.clone());
574                    }
575                }
576            }
577            Value::Object(spec)
578        }
579        ToolKind::Function => json!({
580            "type": "function",
581            "name": tool.name,
582            "description": tool.description,
583            "parameters": tool.parameters,
584        }),
585    }
586}
587
588/// Build the Responses `web_search.user_location` object from a hosted-tool
589/// `user_location` parameter (`_responses_client.py:310-329`).
590fn user_location_to_responses(location: &Value) -> Value {
591    let mut loc = Map::new();
592    loc.insert("type".into(), json!("approximate"));
593    for key in ["city", "country", "region", "timezone"] {
594        if let Some(v) = location.get(key) {
595            loc.insert(key.into(), v.clone());
596        }
597    }
598    Value::Object(loc)
599}
600
601/// Build the Responses MCP `require_approval` value. A `parameters.approval_mode`
602/// override — either the string `"always_require"`/`"never_require"` or an
603/// object `{"always": [...], "never": [...]}` — takes precedence over the
604/// definition's [`ApprovalMode`]; mirrors `get_mcp_tool`
605/// (`_responses_client.py:365-386`).
606fn mcp_require_approval(tool: &ToolDefinition) -> Value {
607    use agent_framework_core::tools::ApprovalMode;
608    match tool.parameters.get("approval_mode") {
609        Some(Value::String(s)) => {
610            return json!(if s == "always_require" {
611                "always"
612            } else {
613                "never"
614            });
615        }
616        Some(Value::Object(modes)) => {
617            let mut req = Map::new();
618            if let Some(always) = modes.get("always") {
619                req.insert("always".into(), json!({ "tool_names": always }));
620            }
621            if let Some(never) = modes.get("never") {
622                req.insert("never".into(), json!({ "tool_names": never }));
623            }
624            if !req.is_empty() {
625                return Value::Object(req);
626            }
627        }
628        _ => {}
629    }
630    json!(match tool.approval_mode {
631        ApprovalMode::AlwaysRequire => "always",
632        ApprovalMode::NeverRequire => "never",
633    })
634}
635
636/// `pub` so `agent-framework-azure`'s Responses client can reuse this
637/// mapping rather than reimplementing it.
638pub fn tool_choice_to_responses(mode: &ToolMode) -> Value {
639    match mode {
640        ToolMode::Auto => json!("auto"),
641        ToolMode::None => json!("none"),
642        ToolMode::Required(Some(name)) => json!({ "type": "function", "name": name }),
643        ToolMode::Required(None) => json!("required"),
644    }
645}
646
647/// Convert a `ChatOptions::response_format` into a Responses API
648/// `text.format` object. Unlike Chat Completions (which nests the schema
649/// under `json_schema`), the Responses API uses a flat object.
650///
651/// `pub` so `agent-framework-azure`'s Responses client can reuse this
652/// mapping rather than reimplementing it.
653pub fn response_format_to_text(format: &ResponseFormat) -> Value {
654    match format {
655        ResponseFormat::Text => json!({ "type": "text" }),
656        ResponseFormat::JsonObject => json!({ "type": "json_object" }),
657        ResponseFormat::JsonSchema {
658            name,
659            description,
660            schema,
661            strict,
662        } => {
663            let mut obj = Map::new();
664            obj.insert("type".into(), json!("json_schema"));
665            obj.insert("name".into(), json!(name));
666            if let Some(d) = description {
667                obj.insert("description".into(), json!(d));
668            }
669            obj.insert("schema".into(), schema.clone());
670            if let Some(st) = strict {
671                obj.insert("strict".into(), json!(st));
672            }
673            Value::Object(obj)
674        }
675    }
676}
677
678// endregion
679
680// region: response conversion
681
682/// Parse a full (non-streaming) Responses API response.
683///
684/// Map a Responses body whose `status` is `"failed"` to a classified error,
685/// or `None` for a non-failed response. A failed run reports `status:
686/// "failed"` with a 2xx HTTP status, so the error is pulled from the body:
687/// `error.code == "content_filter"` becomes [`Error::ServiceContentFilter`]
688/// (matching the HTTP-level classification in `classify_service_error`),
689/// anything else a generic service error.
690///
691/// `pub` so `agent-framework-azure`'s Responses client can share the exact
692/// classification.
693pub fn response_failure_error(value: &Value) -> Option<Error> {
694    if value.get("status").and_then(Value::as_str) != Some("failed") {
695        return None;
696    }
697    let error = value.get("error");
698    let msg = error
699        .and_then(|e| e.get("message"))
700        .and_then(Value::as_str)
701        .unwrap_or("response failed")
702        .to_string();
703    let code = error.and_then(|e| e.get("code")).and_then(Value::as_str);
704    Some(match code {
705        Some("content_filter") => Error::service_content_filter(msg),
706        _ => Error::service(msg),
707    })
708}
709
710/// `pub` so `agent-framework-azure`'s Responses client (whose wire format is
711/// otherwise identical) can reuse this parser — including `parse_output_item`,
712/// `parse_annotations`, and usage/finish-reason handling — rather than
713/// reimplementing it.
714pub fn parse_response(value: &Value, store: Option<bool>) -> ChatResponse {
715    let mut response = ChatResponse {
716        response_id: value.get("id").and_then(Value::as_str).map(String::from),
717        model: value.get("model").and_then(Value::as_str).map(String::from),
718        ..Default::default()
719    };
720
721    let mut contents: Vec<Content> = Vec::new();
722    if let Some(items) = value.get("output").and_then(Value::as_array) {
723        for item in items {
724            parse_output_item(item, &mut contents);
725        }
726    }
727
728    let mut message = Message::with_contents(Role::assistant(), contents);
729    message.message_id = response.response_id.clone();
730    response.messages.push(message);
731
732    response.finish_reason = finish_reason_from_response(value);
733
734    if let Some(usage) = value.get("usage") {
735        response.usage_details = Some(parse_responses_usage(usage));
736    }
737    if store != Some(false) {
738        response.conversation_id = response.response_id.clone();
739    }
740    response
741}
742
743fn parse_output_item(item: &Value, contents: &mut Vec<Content>) {
744    match item.get("type").and_then(Value::as_str) {
745        Some("message") => {
746            if let Some(parts) = item.get("content").and_then(Value::as_array) {
747                for part in parts {
748                    match part.get("type").and_then(Value::as_str) {
749                        Some("output_text") => {
750                            if let Some(text) = part.get("text").and_then(Value::as_str) {
751                                let mut tc = TextContent::new(text);
752                                tc.annotations = parse_annotations(part);
753                                contents.push(Content::Text(tc));
754                            }
755                        }
756                        Some("refusal") => {
757                            if let Some(text) = part.get("refusal").and_then(Value::as_str) {
758                                // Marked, so `Message::text` withholds it
759                                // rather than presenting it as the answer.
760                                contents.push(Content::Text(TextContent::refusal(text)));
761                            }
762                        }
763                        _ => {}
764                    }
765                }
766            }
767        }
768        Some("function_call") => {
769            let call_id = item
770                .get("call_id")
771                .and_then(Value::as_str)
772                .unwrap_or_default()
773                .to_string();
774            let name = item
775                .get("name")
776                .and_then(Value::as_str)
777                .unwrap_or_default()
778                .to_string();
779            let args = item
780                .get("arguments")
781                .and_then(Value::as_str)
782                .unwrap_or("{}")
783                .to_string();
784            contents.push(Content::FunctionCall(FunctionCallContent::new(
785                call_id,
786                name,
787                Some(FunctionArguments::Raw(args)),
788            )));
789        }
790        Some("reasoning") => {
791            let summaries: Vec<String> = item
792                .get("summary")
793                .and_then(Value::as_array)
794                .map(|arr| {
795                    arr.iter()
796                        .filter_map(|s| s.get("text").and_then(Value::as_str))
797                        .map(str::to_string)
798                        .collect()
799                })
800                .unwrap_or_default();
801            // Preserve the raw reasoning item so a store:false tool-loop replay
802            // can re-send it verbatim — reasoning models require the original
803            // item (id + encrypted_content), not just the summary, on the
804            // follow-up turn. `messages_to_input` re-emits it from
805            // `raw_representation`; it is attached to exactly one content so a
806            // multi-summary item yields exactly one reasoning input item.
807            let raw = Some(item.clone());
808            if summaries.is_empty() {
809                // No summary (e.g. encrypted reasoning) — still carry the item.
810                contents.push(Content::TextReasoning(TextReasoningContent {
811                    text: String::new(),
812                    annotations: None,
813                    raw_representation: raw,
814                    protected_data: None,
815                }));
816            } else {
817                let n = summaries.len();
818                for (i, text) in summaries.into_iter().enumerate() {
819                    contents.push(Content::TextReasoning(TextReasoningContent {
820                        text,
821                        annotations: None,
822                        raw_representation: (i == n - 1).then(|| raw.clone()).flatten(),
823                        protected_data: None,
824                    }));
825                }
826            }
827        }
828        // Code-interpreter runs surface `logs` as text and `image` outputs as
829        // URIs; a bare `code` (no outputs) is a text fallback
830        // (`_create_response_content:748-764`).
831        Some("code_interpreter_call") => {
832            let outputs = item
833                .get("outputs")
834                .and_then(Value::as_array)
835                .filter(|a| !a.is_empty());
836            if let Some(outputs) = outputs {
837                for output in outputs {
838                    match output.get("type").and_then(Value::as_str) {
839                        Some("logs") => {
840                            if let Some(logs) = output.get("logs").and_then(Value::as_str) {
841                                contents.push(Content::Text(TextContent::new(logs)));
842                            }
843                        }
844                        Some("image") => {
845                            if let Some(url) = output.get("url").and_then(Value::as_str) {
846                                contents.push(Content::Uri(UriContent {
847                                    uri: url.to_string(),
848                                    media_type: "image".to_string(),
849                                }));
850                            }
851                        }
852                        _ => {}
853                    }
854                }
855            } else if let Some(code) = item.get("code").and_then(Value::as_str) {
856                contents.push(Content::Text(TextContent::new(code)));
857            }
858        }
859        // A generated image is returned as base64; default to image/png unless
860        // the result is a data URI that states its own type
861        // (`_create_response_content:788-811`).
862        Some("image_generation_call") => {
863            if let Some(result) = item.get("result").and_then(Value::as_str) {
864                let (uri, media_type) = if result.starts_with("data:") {
865                    let media_type = if result.contains(';') {
866                        result
867                            .strip_prefix("data:")
868                            .and_then(|r| r.split(';').next())
869                            .filter(|s| !s.is_empty())
870                            .map(String::from)
871                    } else {
872                        None
873                    };
874                    (result.to_string(), media_type)
875                } else {
876                    (
877                        format!("data:image/png;base64,{result}"),
878                        Some("image/png".to_string()),
879                    )
880                };
881                contents.push(Content::Data(DataContent { uri, media_type }));
882            }
883        }
884        // An MCP approval request round-trips its `id` as the call id so a
885        // later `FunctionApprovalResponse` refers back to it
886        // (`_create_response_content:775-787`).
887        Some("mcp_approval_request") => {
888            let id = item
889                .get("id")
890                .and_then(Value::as_str)
891                .unwrap_or_default()
892                .to_string();
893            let name = item
894                .get("name")
895                .and_then(Value::as_str)
896                .unwrap_or_default()
897                .to_string();
898            let args = item
899                .get("arguments")
900                .and_then(Value::as_str)
901                .unwrap_or("{}")
902                .to_string();
903            contents.push(Content::FunctionApprovalRequest(
904                FunctionApprovalRequestContent {
905                    id: id.clone(),
906                    function_call: FunctionCallContent::new(
907                        id,
908                        name,
909                        Some(FunctionArguments::Raw(args)),
910                    ),
911                },
912            ));
913        }
914        _ => {}
915    }
916}
917
918/// Parse the `annotations` on an `output_text` part into [`Annotation`]s
919/// (`_create_response_content:667-724`). The core annotation type has no free
920/// `additional_properties`, so upstream's `index`/`container_id` extras are
921/// dropped.
922fn parse_annotations(part: &Value) -> Option<Vec<Annotation>> {
923    let arr = part.get("annotations").and_then(Value::as_array)?;
924    let mut out = Vec::new();
925    for ann in arr {
926        let str_field = |k: &str| ann.get(k).and_then(Value::as_str).map(String::from);
927        let regions = || {
928            Some(vec![TextSpanRegion {
929                start_index: ann.get("start_index").and_then(Value::as_i64),
930                end_index: ann.get("end_index").and_then(Value::as_i64),
931            }])
932        };
933        match ann.get("type").and_then(Value::as_str) {
934            Some("file_path") => out.push(Annotation {
935                file_id: str_field("file_id"),
936                ..Default::default()
937            }),
938            Some("file_citation") => out.push(Annotation {
939                url: str_field("filename"),
940                file_id: str_field("file_id"),
941                ..Default::default()
942            }),
943            Some("url_citation") => out.push(Annotation {
944                title: str_field("title"),
945                url: str_field("url"),
946                annotated_regions: regions(),
947                ..Default::default()
948            }),
949            Some("container_file_citation") => out.push(Annotation {
950                file_id: str_field("file_id"),
951                url: str_field("filename"),
952                annotated_regions: regions(),
953                ..Default::default()
954            }),
955            _ => {}
956        }
957    }
958    if out.is_empty() {
959        None
960    } else {
961        Some(out)
962    }
963}
964
965fn finish_reason_from_response(value: &Value) -> Option<FinishReason> {
966    let has_function_call = value
967        .get("output")
968        .and_then(Value::as_array)
969        .map(|items| {
970            items
971                .iter()
972                .any(|i| i.get("type").and_then(Value::as_str) == Some("function_call"))
973        })
974        .unwrap_or(false);
975    if has_function_call {
976        return Some(FinishReason::tool_calls());
977    }
978    let status = value.get("status").and_then(Value::as_str)?;
979    Some(match status {
980        "completed" => FinishReason::stop(),
981        "incomplete" => match value
982            .get("incomplete_details")
983            .and_then(|d| d.get("reason"))
984            .and_then(Value::as_str)
985        {
986            Some("max_output_tokens") => FinishReason::new(FinishReason::LENGTH),
987            Some("content_filter") => FinishReason::new(FinishReason::CONTENT_FILTER),
988            Some(other) => FinishReason::new(other),
989            None => FinishReason::new("incomplete"),
990        },
991        other => FinishReason::new(other),
992    })
993}
994
995fn parse_responses_usage(usage: &Value) -> UsageDetails {
996    let mut details = UsageDetails {
997        input_token_count: usage.get("input_tokens").and_then(Value::as_u64),
998        output_token_count: usage.get("output_tokens").and_then(Value::as_u64),
999        total_token_count: usage.get("total_tokens").and_then(Value::as_u64),
1000        ..Default::default()
1001    };
1002    if let Some(cached) = usage
1003        .get("input_tokens_details")
1004        .and_then(|d| d.get("cached_tokens"))
1005        .and_then(Value::as_u64)
1006    {
1007        details
1008            .additional_counts
1009            .insert("openai.cached_input_tokens".into(), cached);
1010        // Mirror upstream: also surface as the typed, cross-language field.
1011        details.cache_read_input_token_count = Some(cached);
1012    }
1013    // Cache *writes* are reported separately from cache reads. Absent when the
1014    // provider does not report them (older API versions).
1015    if let Some(cache_write) = usage
1016        .get("input_tokens_details")
1017        .and_then(|d| d.get("cache_write_tokens"))
1018        .and_then(Value::as_u64)
1019    {
1020        details
1021            .additional_counts
1022            .insert("openai.cache_write_tokens".into(), cache_write);
1023        details.cache_creation_input_token_count = Some(cache_write);
1024    }
1025    if let Some(reasoning) = usage
1026        .get("output_tokens_details")
1027        .and_then(|d| d.get("reasoning_tokens"))
1028        .and_then(Value::as_u64)
1029    {
1030        details
1031            .additional_counts
1032            .insert("openai.reasoning_tokens".into(), reasoning);
1033        details.reasoning_output_token_count = Some(reasoning);
1034    }
1035    details
1036}
1037
1038// endregion
1039
1040// region: streaming
1041
1042/// Turn a Responses API SSE HTTP response into a stream of updates.
1043///
1044/// `pub` so `agent-framework-azure`'s Responses client can reuse this exact
1045/// SSE event parser (Azure OpenAI's Responses API streams the same event
1046/// shapes) rather than reimplementing it.
1047pub fn parse_responses_sse_stream(
1048    resp: reqwest::Response,
1049    store: Option<bool>,
1050) -> impl futures::Stream<Item = Result<ChatResponseUpdate>> + Send {
1051    let byte_stream: ByteStream = Box::pin(resp.bytes_stream());
1052    futures::stream::unfold(
1053        ResponsesSseState {
1054            byte_stream,
1055            buffer: String::new(),
1056            utf8: Utf8StreamDecoder::new(),
1057            queued: VecDeque::new(),
1058            call_ids: HashMap::new(),
1059            done: false,
1060            store,
1061        },
1062        |mut state| async move {
1063            loop {
1064                if let Some(update) = state.queued.pop_front() {
1065                    return Some((Ok(update), state));
1066                }
1067                if state.done {
1068                    return None;
1069                }
1070                match state.byte_stream.next().await {
1071                    Some(Ok(bytes)) => {
1072                        let decoded = state.utf8.push(&bytes);
1073                        state.buffer.push_str(&decoded);
1074                        while let Some(pos) = state.buffer.find('\n') {
1075                            let line = state.buffer[..pos].trim().to_string();
1076                            state.buffer.drain(..=pos);
1077                            let Some(data) = line.strip_prefix("data:") else {
1078                                continue;
1079                            };
1080                            let data = data.trim();
1081                            if data.is_empty() {
1082                                continue;
1083                            }
1084                            let Ok(value) = serde_json::from_str::<Value>(data) else {
1085                                continue;
1086                            };
1087                            match parse_responses_event(&value, &mut state.call_ids, state.store) {
1088                                EventOutcome::Update(update) => state.queued.push_back(update),
1089                                EventOutcome::Error(e) => {
1090                                    state.done = true;
1091                                    return Some((Err(e), state));
1092                                }
1093                                EventOutcome::None => {}
1094                            }
1095                        }
1096                    }
1097                    Some(Err(e)) => {
1098                        state.done = true;
1099                        return Some((Err(Error::service(format!("stream error: {e}"))), state));
1100                    }
1101                    None => return None,
1102                }
1103            }
1104        },
1105    )
1106}
1107
1108struct ResponsesSseState {
1109    byte_stream: ByteStream,
1110    buffer: String,
1111    utf8: Utf8StreamDecoder,
1112    queued: VecDeque<ChatResponseUpdate>,
1113    /// `output_index` -> `call_id`, resolved when the call is first announced
1114    /// via `response.output_item.added` and used to route later
1115    /// `response.function_call_arguments.delta` fragments.
1116    call_ids: HashMap<i64, String>,
1117    done: bool,
1118    store: Option<bool>,
1119}
1120
1121// A transient control-flow value: produced per SSE event and immediately
1122// destructured in the stream loop, never stored in bulk. Boxing the `Update`
1123// variant to equalize sizes would add a heap allocation on every streamed
1124// token, so the size skew is accepted here.
1125#[allow(clippy::large_enum_variant)]
1126enum EventOutcome {
1127    Update(ChatResponseUpdate),
1128    Error(Error),
1129    None,
1130}
1131
1132/// Wrap streamed reasoning text as a [`TextReasoningContent`] update, or
1133/// [`EventOutcome::None`] when empty.
1134fn reasoning_update(text: &str) -> EventOutcome {
1135    if text.is_empty() {
1136        return EventOutcome::None;
1137    }
1138    EventOutcome::Update(ChatResponseUpdate {
1139        contents: vec![Content::TextReasoning(TextReasoningContent {
1140            text: text.to_string(),
1141            annotations: None,
1142            ..Default::default()
1143        })],
1144        role: Some(Role::assistant()),
1145        ..Default::default()
1146    })
1147}
1148
1149/// Parse one Responses API SSE event (already-decoded JSON `data:` payload).
1150fn parse_responses_event(
1151    value: &Value,
1152    call_ids: &mut HashMap<i64, String>,
1153    store: Option<bool>,
1154) -> EventOutcome {
1155    let event_type = value.get("type").and_then(Value::as_str).unwrap_or("");
1156    match event_type {
1157        "response.created" => {
1158            let resp = value.get("response");
1159            let response_id = resp
1160                .and_then(|r| r.get("id"))
1161                .and_then(Value::as_str)
1162                .map(String::from);
1163            let model = resp
1164                .and_then(|r| r.get("model"))
1165                .and_then(Value::as_str)
1166                .map(String::from);
1167            if response_id.is_none() && model.is_none() {
1168                return EventOutcome::None;
1169            }
1170            EventOutcome::Update(ChatResponseUpdate {
1171                role: Some(Role::assistant()),
1172                response_id,
1173                model,
1174                ..Default::default()
1175            })
1176        }
1177        "response.output_text.delta" => {
1178            let text = value.get("delta").and_then(Value::as_str).unwrap_or("");
1179            if text.is_empty() {
1180                return EventOutcome::None;
1181            }
1182            EventOutcome::Update(ChatResponseUpdate {
1183                contents: vec![Content::Text(TextContent::new(text))],
1184                role: Some(Role::assistant()),
1185                ..Default::default()
1186            })
1187        }
1188        // A refusal streams on its own channel. Only the incremental `.delta`
1189        // is consumed: the terminal `response.refusal.done` repeats the whole
1190        // refusal, which aggregation would append to the fragments already
1191        // collected, doubling it — the same reason the text channel above
1192        // does not consume its `.done`. Dropping these events entirely, as
1193        // this parser used to, let a streamed decline reach the caller as an
1194        // empty response.
1195        "response.refusal.delta" => {
1196            let text = value.get("delta").and_then(Value::as_str).unwrap_or("");
1197            if text.is_empty() {
1198                return EventOutcome::None;
1199            }
1200            EventOutcome::Update(ChatResponseUpdate {
1201                contents: vec![Content::Text(TextContent::refusal(text))],
1202                role: Some(Role::assistant()),
1203                ..Default::default()
1204            })
1205        }
1206        // Reasoning (chain-of-thought / summary) streams as its own text
1207        // channel. Both the incremental `.delta` and the terminal `.done`
1208        // (full text) map to `TextReasoningContent`, mirroring upstream
1209        // `_create_streaming_response_content` (`_responses_client.py:917-928`).
1210        "response.reasoning_text.delta" | "response.reasoning_summary_text.delta" => {
1211            reasoning_update(value.get("delta").and_then(Value::as_str).unwrap_or(""))
1212        }
1213        // `.done` carries the *full* completed text, not another increment —
1214        // the deltas above already streamed it, so emitting it again would
1215        // duplicate the reasoning in the aggregated response (adjacent
1216        // reasoning contents coalesce by appending). Treated as terminal
1217        // metadata, like `response.output_text.done`.
1218        "response.reasoning_text.done" | "response.reasoning_summary_text.done" => {
1219            EventOutcome::None
1220        }
1221        "response.output_item.added" => {
1222            let item = value.get("item");
1223            if item.and_then(|i| i.get("type")).and_then(Value::as_str) != Some("function_call") {
1224                return EventOutcome::None;
1225            }
1226            let output_index = value
1227                .get("output_index")
1228                .and_then(Value::as_i64)
1229                .unwrap_or(0);
1230            let call_id = item
1231                .and_then(|i| i.get("call_id"))
1232                .and_then(Value::as_str)
1233                .unwrap_or_default()
1234                .to_string();
1235            let name = item
1236                .and_then(|i| i.get("name"))
1237                .and_then(Value::as_str)
1238                .unwrap_or_default()
1239                .to_string();
1240            call_ids.insert(output_index, call_id.clone());
1241            EventOutcome::Update(ChatResponseUpdate {
1242                contents: vec![Content::FunctionCall(FunctionCallContent::new(
1243                    call_id, name, None,
1244                ))],
1245                role: Some(Role::assistant()),
1246                ..Default::default()
1247            })
1248        }
1249        "response.function_call_arguments.delta" => {
1250            let output_index = value
1251                .get("output_index")
1252                .and_then(Value::as_i64)
1253                .unwrap_or(0);
1254            let delta = value.get("delta").and_then(Value::as_str).unwrap_or("");
1255            match call_ids.get(&output_index) {
1256                Some(call_id) => EventOutcome::Update(ChatResponseUpdate {
1257                    contents: vec![Content::FunctionCall(FunctionCallContent::new(
1258                        call_id.clone(),
1259                        "",
1260                        Some(FunctionArguments::Raw(delta.to_string())),
1261                    ))],
1262                    role: Some(Role::assistant()),
1263                    ..Default::default()
1264                }),
1265                None => EventOutcome::None,
1266            }
1267        }
1268        // `response.incomplete` is the terminal event for a turn cut off by
1269        // the content filter or the token budget — the same payload as
1270        // `response.completed`, under a name that says it did not finish.
1271        // Handled here rather than ignored, or a truncated or filtered
1272        // stream would lose its finish reason, usage and response id
1273        // entirely, which is exactly the information the distinct event
1274        // name exists to deliver.
1275        "response.completed" | "response.incomplete" => {
1276            let resp = value.get("response");
1277            let response_id = resp
1278                .and_then(|r| r.get("id"))
1279                .and_then(Value::as_str)
1280                .map(String::from);
1281            let model = resp
1282                .and_then(|r| r.get("model"))
1283                .and_then(Value::as_str)
1284                .map(String::from);
1285            let mut contents = Vec::new();
1286            if let Some(usage) = resp.and_then(|r| r.get("usage")) {
1287                contents.push(Content::Usage(UsageContent {
1288                    details: parse_responses_usage(usage),
1289                }));
1290            }
1291            let finish_reason = resp.and_then(finish_reason_from_response);
1292            let conversation_id = if store != Some(false) {
1293                response_id.clone()
1294            } else {
1295                None
1296            };
1297            EventOutcome::Update(ChatResponseUpdate {
1298                contents,
1299                role: Some(Role::assistant()),
1300                response_id,
1301                model,
1302                conversation_id,
1303                finish_reason,
1304                ..Default::default()
1305            })
1306        }
1307        "response.failed" | "error" => {
1308            let resp = value.get("response");
1309            let err_obj = resp
1310                .and_then(|r| r.get("error"))
1311                .or_else(|| value.get("error"));
1312            let msg = err_obj
1313                .and_then(|e| e.get("message"))
1314                .and_then(Value::as_str)
1315                .unwrap_or("response failed")
1316                .to_string();
1317            // Same classification as the non-streaming `response_failure_error`
1318            // so callers branching on content filters see one behavior for
1319            // streamed and non-streamed Responses.
1320            let code = err_obj.and_then(|e| e.get("code")).and_then(Value::as_str);
1321            EventOutcome::Error(match code {
1322                Some("content_filter") => Error::service_content_filter(msg),
1323                _ => Error::service(msg),
1324            })
1325        }
1326        // Recognized but carry no additional content: the arguments are
1327        // already fully accumulated via `.delta` events, and item/part
1328        // lifecycle markers don't themselves map to a `Content`.
1329        "response.function_call_arguments.done"
1330        | "response.output_item.done"
1331        | "response.content_part.added"
1332        | "response.content_part.done"
1333        | "response.in_progress" => EventOutcome::None,
1334        _ => EventOutcome::None,
1335    }
1336}
1337
1338// endregion
1339
1340#[cfg(test)]
1341mod tests {
1342    use super::*;
1343    use agent_framework_core::tools::{ApprovalMode, ToolDefinition, ToolKind};
1344    use agent_framework_core::types::{
1345        FunctionApprovalResponseContent, FunctionResultContent, HostedFileContent,
1346    };
1347
1348    fn user(text: &str) -> Message {
1349        Message::user(text)
1350    }
1351
1352    fn user_with(contents: Vec<Content>) -> Message {
1353        Message::with_contents(Role::user(), contents)
1354    }
1355
1356    /// Parse a single Responses output item into its content list.
1357    fn parse_item(item: Value) -> Vec<Content> {
1358        let mut contents = Vec::new();
1359        parse_output_item(&item, &mut contents);
1360        contents
1361    }
1362
1363    fn client() -> OpenAIChatClient {
1364        OpenAIChatClient::new("test-key", "gpt-4o-mini")
1365    }
1366
1367    // region: request body building
1368
1369    #[test]
1370    fn build_body_simple_text() {
1371        let c = client();
1372        let body = c.build_body(&[user("Hello there")], &ChatOptions::new(), false);
1373        assert_eq!(
1374            body,
1375            json!({
1376                "model": "gpt-4o-mini",
1377                "input": [
1378                    { "type": "message", "role": "user", "content": [
1379                        { "type": "input_text", "text": "Hello there" }
1380                    ]}
1381                ],
1382                // Nothing is stored service-side on this request, so the
1383                // encrypted reasoning item is requested for the replay path.
1384                "include": ["reasoning.encrypted_content"],
1385            })
1386        );
1387    }
1388
1389    #[test]
1390    fn responses_usage_parses_cache_write_tokens() {
1391        // Cache *writes* are reported separately from cache reads (upstream #7369).
1392        let d = parse_responses_usage(&json!({
1393            "input_tokens": 2000,
1394            "output_tokens": 60,
1395            "total_tokens": 2060,
1396            "input_tokens_details": { "cached_tokens": 0, "cache_write_tokens": 1024 },
1397        }));
1398        assert_eq!(d.cache_creation_input_token_count, Some(1024));
1399        assert_eq!(d.cache_read_input_token_count, Some(0));
1400        assert_eq!(
1401            d.additional_counts.get("openai.cache_write_tokens"),
1402            Some(&1024)
1403        );
1404    }
1405
1406    #[test]
1407    fn responses_usage_omits_cache_write_tokens_when_not_reported() {
1408        let d = parse_responses_usage(&json!({
1409            "input_tokens": 100,
1410            "output_tokens": 20,
1411            "input_tokens_details": { "cached_tokens": 40 },
1412        }));
1413        assert_eq!(d.cache_creation_input_token_count, None);
1414        assert!(!d
1415            .additional_counts
1416            .contains_key("openai.cache_write_tokens"));
1417    }
1418
1419    #[test]
1420    fn build_body_extracts_leading_system_message_as_instructions() {
1421        let c = client();
1422        let messages = vec![Message::system("Be terse."), user("Hi")];
1423        let body = c.build_body(&messages, &ChatOptions::new(), false);
1424        assert_eq!(body["instructions"], json!("Be terse."));
1425        assert_eq!(
1426            body["input"],
1427            json!([
1428                { "type": "message", "role": "user", "content": [
1429                    { "type": "input_text", "text": "Hi" }
1430                ]}
1431            ])
1432        );
1433    }
1434
1435    #[test]
1436    fn build_body_combines_options_instructions_and_system_message() {
1437        let c = client();
1438        let messages = vec![Message::system("Also be nice."), user("Hi")];
1439        let options = ChatOptions::new().with_instructions("Be terse.");
1440        let body = c.build_body(&messages, &options, false);
1441        assert_eq!(body["instructions"], json!("Be terse.\n\nAlso be nice."));
1442    }
1443
1444    #[test]
1445    fn build_body_assistant_text_uses_output_text_type() {
1446        let c = client();
1447        let messages = vec![user("Hi"), Message::assistant("Hello!")];
1448        let body = c.build_body(&messages, &ChatOptions::new(), false);
1449        assert_eq!(
1450            body["input"][1],
1451            json!({ "type": "message", "role": "assistant", "content": [
1452                { "type": "output_text", "text": "Hello!" }
1453            ]})
1454        );
1455    }
1456
1457    #[test]
1458    fn build_body_function_call_round_trip() {
1459        let c = client();
1460        let call = FunctionCallContent::new(
1461            "call_1",
1462            "get_weather",
1463            Some(FunctionArguments::Raw(r#"{"city":"Paris"}"#.to_string())),
1464        );
1465        let assistant_msg =
1466            Message::with_contents(Role::assistant(), vec![Content::FunctionCall(call)]);
1467        let tool_msg = Message::with_contents(
1468            Role::tool(),
1469            vec![Content::FunctionResult(FunctionResultContent::new(
1470                "call_1",
1471                Some(json!("18C and sunny")),
1472            ))],
1473        );
1474        let body = c.build_body(
1475            &[user("weather?"), assistant_msg, tool_msg],
1476            &ChatOptions::new(),
1477            false,
1478        );
1479        assert_eq!(
1480            body["input"],
1481            json!([
1482                { "type": "message", "role": "user", "content": [
1483                    { "type": "input_text", "text": "weather?" }
1484                ]},
1485                { "type": "function_call", "call_id": "call_1", "name": "get_weather", "arguments": "{\"city\":\"Paris\"}" },
1486                { "type": "function_call_output", "call_id": "call_1", "output": "18C and sunny" },
1487            ])
1488        );
1489    }
1490
1491    #[test]
1492    fn build_body_tools_are_flat_not_nested() {
1493        let c = client();
1494        let tool = ToolDefinition {
1495            name: "get_weather".into(),
1496            description: "Get the weather".into(),
1497            parameters: json!({ "type": "object", "properties": {} }),
1498            kind: ToolKind::Function,
1499            approval_mode: ApprovalMode::NeverRequire,
1500            executor: None,
1501        };
1502        let options = ChatOptions::new().with_tool(tool);
1503        let body = c.build_body(&[user("hi")], &options, false);
1504        assert_eq!(
1505            body["tools"],
1506            json!([{
1507                "type": "function",
1508                "name": "get_weather",
1509                "description": "Get the weather",
1510                "parameters": { "type": "object", "properties": {} },
1511            }])
1512        );
1513    }
1514
1515    #[test]
1516    fn build_body_tool_choice_required_named() {
1517        let c = client();
1518        let options =
1519            ChatOptions::new().with_tool_choice(ToolMode::Required(Some("get_weather".into())));
1520        let body = c.build_body(&[user("hi")], &options, false);
1521        assert_eq!(
1522            body["tool_choice"],
1523            json!({ "type": "function", "name": "get_weather" })
1524        );
1525    }
1526
1527    #[test]
1528    fn stateless_request_asks_for_the_encrypted_reasoning_item() {
1529        // A reasoning item is only replayable on the next turn if it carries
1530        // `encrypted_content`, and the service only returns that when asked.
1531        let c = client();
1532        let body = c.build_body(&[user("hi")], &ChatOptions::new(), false);
1533        assert_eq!(body["include"], json!(["reasoning.encrypted_content"]));
1534    }
1535
1536    #[test]
1537    fn a_service_side_conversation_needs_no_encrypted_reasoning() {
1538        // The service already holds the reasoning item, so echoing it back is
1539        // pointless — and upstream keys this off the storage indicators, not
1540        // off `store`.
1541        let mut options = ChatOptions::new();
1542        options.conversation_id = Some("resp_abc123".into());
1543        let body = client().build_body(&[user("hi")], &options, false);
1544        assert!(
1545            body.get("include").is_none(),
1546            "no include expected, got: {}",
1547            body
1548        );
1549    }
1550
1551    #[test]
1552    fn an_empty_conversation_id_is_not_service_side_storage() {
1553        // An empty id is no id: it would not continue anything server-side, so
1554        // the request is still stateless and still needs the item echoed back.
1555        let mut options = ChatOptions::new();
1556        options.conversation_id = Some(String::new());
1557        let body = client().build_body(&[user("hi")], &options, false);
1558        assert_eq!(body["include"], json!(["reasoning.encrypted_content"]));
1559    }
1560
1561    #[test]
1562    fn a_callers_own_include_entries_survive_and_are_not_duplicated() {
1563        // The caller's entries are preserved alongside the implicit one...
1564        let mut options = ChatOptions::new();
1565        options
1566            .additional_properties
1567            .insert("include".into(), json!(["file_search_call.results"]));
1568        let body = client().build_body(&[user("hi")], &options, false);
1569        assert_eq!(
1570            body["include"],
1571            json!(["file_search_call.results", "reasoning.encrypted_content"])
1572        );
1573
1574        // ...and asking for the encrypted item by name does not get it twice.
1575        let mut options = ChatOptions::new();
1576        options
1577            .additional_properties
1578            .insert("include".into(), json!(["reasoning.encrypted_content"]));
1579        let body = client().build_body(&[user("hi")], &options, false);
1580        assert_eq!(body["include"], json!(["reasoning.encrypted_content"]));
1581    }
1582
1583    #[test]
1584    fn an_explicit_empty_include_is_omitted_not_sent_as_an_empty_array() {
1585        // `responses_include` drops an empty array, and the
1586        // `additional_properties` pass must not put it back: `include` is
1587        // that function's alone. Reached here via a stored conversation, which
1588        // suppresses the implicit entry that would otherwise fill the array.
1589        let mut options = ChatOptions::new();
1590        options.conversation_id = Some("resp_abc123".into());
1591        options
1592            .additional_properties
1593            .insert("include".into(), json!([]));
1594        let body = client().build_body(&[user("hi")], &options, false);
1595        assert!(
1596            body.get("include").is_none(),
1597            "an empty include should be omitted entirely, got: {}",
1598            body
1599        );
1600    }
1601
1602    #[test]
1603    fn other_additional_properties_still_pass_through() {
1604        // Only `include` is intercepted; everything else the caller sets still
1605        // reaches the body.
1606        let mut options = ChatOptions::new();
1607        options
1608            .additional_properties
1609            .insert("safety_identifier".into(), json!("user-123"));
1610        let body = client().build_body(&[user("hi")], &options, false);
1611        assert_eq!(body["safety_identifier"], json!("user-123"));
1612    }
1613
1614    #[test]
1615    fn build_body_conversation_id_becomes_previous_response_id() {
1616        let c = client();
1617        let mut options = ChatOptions::new();
1618        options.conversation_id = Some("resp_abc123".into());
1619        let body = c.build_body(&[user("hi")], &options, false);
1620        assert_eq!(body["previous_response_id"], json!("resp_abc123"));
1621    }
1622
1623    #[test]
1624    fn build_body_max_tokens_becomes_max_output_tokens() {
1625        let c = client();
1626        let options = ChatOptions::new().with_max_tokens(256);
1627        let body = c.build_body(&[user("hi")], &options, false);
1628        assert_eq!(body["max_output_tokens"], json!(256));
1629        assert!(body.get("max_tokens").is_none());
1630    }
1631
1632    #[test]
1633    fn build_body_response_format_becomes_text_format() {
1634        let c = client();
1635        let mut options = ChatOptions::new();
1636        options.response_format = Some(ResponseFormat::JsonSchema {
1637            name: "answer".into(),
1638            description: None,
1639            schema: json!({"type": "object"}),
1640            strict: Some(true),
1641        });
1642        let body = c.build_body(&[user("hi")], &options, false);
1643        assert_eq!(
1644            body["text"]["format"],
1645            json!({ "type": "json_schema", "name": "answer", "schema": {"type": "object"}, "strict": true })
1646        );
1647    }
1648
1649    #[test]
1650    fn build_body_stream_flag() {
1651        let c = client();
1652        let body = c.build_body(&[user("hi")], &ChatOptions::new(), true);
1653        assert_eq!(body["stream"], json!(true));
1654    }
1655
1656    // endregion
1657
1658    // region: response parsing
1659
1660    #[test]
1661    fn parse_response_text_and_usage() {
1662        let value = json!({
1663            "id": "resp_123",
1664            "model": "gpt-4o-mini",
1665            "status": "completed",
1666            "output": [
1667                { "type": "message", "role": "assistant", "content": [
1668                    { "type": "output_text", "text": "Hello!" }
1669                ]}
1670            ],
1671            "usage": { "input_tokens": 10, "output_tokens": 5, "total_tokens": 15 },
1672        });
1673        let resp = parse_response(&value, None);
1674        assert_eq!(resp.response_id.as_deref(), Some("resp_123"));
1675        assert_eq!(resp.conversation_id.as_deref(), Some("resp_123"));
1676        assert_eq!(resp.text(), "Hello!");
1677        assert_eq!(resp.finish_reason, Some(FinishReason::stop()));
1678        let usage = resp.usage_details.unwrap();
1679        assert_eq!(usage.input_token_count, Some(10));
1680        assert_eq!(usage.output_token_count, Some(5));
1681        assert_eq!(usage.total_token_count, Some(15));
1682    }
1683
1684    #[test]
1685    fn parse_response_store_false_omits_conversation_id() {
1686        let value = json!({
1687            "id": "resp_123",
1688            "status": "completed",
1689            "output": [],
1690        });
1691        let resp = parse_response(&value, Some(false));
1692        assert_eq!(resp.conversation_id, None);
1693    }
1694
1695    #[test]
1696    fn parse_response_function_call_sets_tool_calls_finish_reason() {
1697        let value = json!({
1698            "id": "resp_123",
1699            "status": "completed",
1700            "output": [
1701                { "type": "function_call", "call_id": "call_1", "name": "get_weather", "arguments": "{\"city\":\"Paris\"}" }
1702            ],
1703        });
1704        let resp = parse_response(&value, None);
1705        assert_eq!(resp.finish_reason, Some(FinishReason::tool_calls()));
1706        let calls = resp.function_calls();
1707        assert_eq!(calls.len(), 1);
1708        assert_eq!(calls[0].call_id, "call_1");
1709        assert_eq!(calls[0].name, "get_weather");
1710    }
1711
1712    #[test]
1713    fn parse_response_incomplete_max_output_tokens_is_length() {
1714        let value = json!({
1715            "id": "resp_123",
1716            "status": "incomplete",
1717            "incomplete_details": { "reason": "max_output_tokens" },
1718            "output": [],
1719        });
1720        let resp = parse_response(&value, None);
1721        assert_eq!(
1722            resp.finish_reason,
1723            Some(FinishReason::new(FinishReason::LENGTH))
1724        );
1725    }
1726
1727    /// `response.incomplete` is the terminal event for a stream cut off by
1728    /// the content filter or the token budget. Ignoring it — which this
1729    /// did — dropped the finish reason, usage and response id for exactly
1730    /// the streams whose distinct event name exists to report them, and
1731    /// left a client unable to tell a truncated answer from a complete one.
1732    #[test]
1733    fn a_streamed_response_incomplete_carries_its_terminal_metadata() {
1734        let mut call_ids = HashMap::new();
1735        let event = json!({
1736            "type": "response.incomplete",
1737            "response": {
1738                "id": "resp_123",
1739                "model": "gpt-4o",
1740                "status": "incomplete",
1741                "incomplete_details": { "reason": "content_filter" },
1742                "output": [],
1743                "usage": { "input_tokens": 3, "output_tokens": 5, "total_tokens": 8 },
1744            },
1745        });
1746        let EventOutcome::Update(update) = parse_responses_event(&event, &mut call_ids, None)
1747        else {
1748            panic!("response.incomplete must produce a terminal update");
1749        };
1750        assert_eq!(
1751            update.finish_reason,
1752            Some(FinishReason::new(FinishReason::CONTENT_FILTER))
1753        );
1754        assert_eq!(update.response_id.as_deref(), Some("resp_123"));
1755        assert_eq!(update.model.as_deref(), Some("gpt-4o"));
1756        let usage = update
1757            .contents
1758            .iter()
1759            .find_map(|c| match c {
1760                Content::Usage(u) => Some(&u.details),
1761                _ => None,
1762            })
1763            .expect("usage rides the terminal update");
1764        assert_eq!(usage.input_token_count, Some(3));
1765        assert_eq!(usage.output_token_count, Some(5));
1766    }
1767
1768    /// And a `response.completed` is unchanged by sharing the arm.
1769    #[test]
1770    fn a_streamed_response_completed_still_carries_its_metadata() {
1771        let mut call_ids = HashMap::new();
1772        let event = json!({
1773            "type": "response.completed",
1774            "response": {
1775                "id": "resp_456",
1776                "status": "completed",
1777                "output": [],
1778            },
1779        });
1780        let EventOutcome::Update(update) = parse_responses_event(&event, &mut call_ids, None)
1781        else {
1782            panic!("response.completed produces a terminal update");
1783        };
1784        assert_eq!(update.finish_reason, Some(FinishReason::stop()));
1785        assert_eq!(update.response_id.as_deref(), Some("resp_456"));
1786    }
1787
1788    #[test]
1789    fn parse_response_reasoning_becomes_text_reasoning() {
1790        let value = json!({
1791            "id": "resp_123",
1792            "status": "completed",
1793            "output": [
1794                { "type": "reasoning", "summary": [{ "type": "summary_text", "text": "thinking..." }] },
1795                { "type": "message", "role": "assistant", "content": [{ "type": "output_text", "text": "done" }] },
1796            ],
1797        });
1798        let resp = parse_response(&value, None);
1799        let contents = &resp.messages[0].contents;
1800        assert!(matches!(&contents[0], Content::TextReasoning(t) if t.text == "thinking..."));
1801        assert!(matches!(&contents[1], Content::Text(t) if t.text == "done"));
1802    }
1803
1804    #[test]
1805    fn reasoning_item_round_trips_through_input_for_store_false_replay() {
1806        // A store:false tool-loop replay must re-send the original reasoning
1807        // item (id + encrypted_content), not just its summary text.
1808        let reasoning_item = json!({
1809            "type": "reasoning",
1810            "id": "rs_abc",
1811            "encrypted_content": "ENC",
1812            "summary": [{ "type": "summary_text", "text": "thinking..." }],
1813        });
1814        let value = json!({
1815            "id": "resp_1",
1816            "status": "completed",
1817            "output": [
1818                reasoning_item,
1819                { "type": "function_call", "call_id": "c1", "name": "f", "arguments": "{}" },
1820            ],
1821        });
1822        let resp = parse_response(&value, Some(false));
1823        // The parsed reasoning content preserves the raw item.
1824        let reasoning = resp.messages[0]
1825            .contents
1826            .iter()
1827            .find_map(|c| match c {
1828                Content::TextReasoning(t) => Some(t),
1829                _ => None,
1830            })
1831            .expect("reasoning content");
1832        assert_eq!(
1833            reasoning.raw_representation.as_ref().unwrap()["id"],
1834            "rs_abc"
1835        );
1836
1837        // Replaying that assistant message back through the input mapper
1838        // re-emits the reasoning item verbatim, ahead of the function call.
1839        let input = messages_to_input(&resp.messages);
1840        let reasoning_pos = input
1841            .iter()
1842            .position(|i| i.get("type") == Some(&json!("reasoning")))
1843            .expect("reasoning item re-emitted");
1844        assert_eq!(input[reasoning_pos]["id"], "rs_abc");
1845        assert_eq!(input[reasoning_pos]["encrypted_content"], "ENC");
1846        let call_pos = input
1847            .iter()
1848            .position(|i| i.get("type") == Some(&json!("function_call")))
1849            .expect("function call present");
1850        assert!(reasoning_pos < call_pos, "reasoning must precede the call");
1851    }
1852
1853    #[test]
1854    fn summary_only_reasoning_is_not_re_emitted_as_input() {
1855        // A reasoning content with no preserved raw item (e.g. from streaming
1856        // display) has no valid input form and must be dropped, not sent as a
1857        // bogus reasoning item lacking id/encrypted_content.
1858        let msg = Message::with_contents(
1859            Role::assistant(),
1860            vec![Content::TextReasoning(TextReasoningContent {
1861                text: "just display".into(),
1862                annotations: None,
1863                raw_representation: None,
1864                protected_data: None,
1865            })],
1866        );
1867        let input = messages_to_input(&[msg]);
1868        assert!(input
1869            .iter()
1870            .all(|i| i.get("type") != Some(&json!("reasoning"))));
1871    }
1872
1873    // endregion
1874
1875    // region: streaming
1876
1877    fn sse_body(events: &[(&str, Value)]) -> String {
1878        let mut out = String::new();
1879        for (event, data) in events {
1880            out.push_str(&format!("event: {event}\ndata: {}\n\n", data));
1881        }
1882        out
1883    }
1884
1885    async fn collect_updates(text: String) -> Vec<ChatResponseUpdate> {
1886        // Build a fake reqwest::Response backed by the given SSE text using a
1887        // tiny local HTTP server would be overkill; instead we drive the
1888        // event parser directly through the same state machine by feeding
1889        // the byte stream via `futures::stream::once`.
1890        let stream =
1891            futures::stream::once(async move { Ok::<_, reqwest::Error>(bytes::Bytes::from(text)) });
1892        let byte_stream: ByteStream = Box::pin(stream);
1893        let mut state = ResponsesSseState {
1894            byte_stream,
1895            buffer: String::new(),
1896            utf8: Utf8StreamDecoder::new(),
1897            queued: VecDeque::new(),
1898            call_ids: HashMap::new(),
1899            done: false,
1900            store: None,
1901        };
1902        let mut updates = Vec::new();
1903        // Drain the single chunk manually (mirrors the real unfold body).
1904        if let Some(Ok(bytes)) = state.byte_stream.next().await {
1905            let decoded = state.utf8.push(&bytes);
1906            state.buffer.push_str(&decoded);
1907            while let Some(pos) = state.buffer.find('\n') {
1908                let line = state.buffer[..pos].trim().to_string();
1909                state.buffer.drain(..=pos);
1910                let Some(data) = line.strip_prefix("data:") else {
1911                    continue;
1912                };
1913                let data = data.trim();
1914                if data.is_empty() {
1915                    continue;
1916                }
1917                let value: Value = serde_json::from_str(data).unwrap();
1918                if let EventOutcome::Update(u) =
1919                    parse_responses_event(&value, &mut state.call_ids, state.store)
1920                {
1921                    updates.push(u);
1922                }
1923            }
1924        }
1925        updates
1926    }
1927
1928    #[tokio::test]
1929    async fn stream_text_only_accumulates() {
1930        let text = sse_body(&[
1931            (
1932                "response.created",
1933                json!({ "type": "response.created", "response": { "id": "resp_1", "model": "gpt-4o-mini" } }),
1934            ),
1935            (
1936                "response.output_text.delta",
1937                json!({ "type": "response.output_text.delta", "delta": "Hel" }),
1938            ),
1939            (
1940                "response.output_text.delta",
1941                json!({ "type": "response.output_text.delta", "delta": "lo!" }),
1942            ),
1943            (
1944                "response.completed",
1945                json!({ "type": "response.completed", "response": { "id": "resp_1", "model": "gpt-4o-mini", "status": "completed", "output": [], "usage": { "input_tokens": 3, "output_tokens": 2 } } }),
1946            ),
1947        ]);
1948        let updates = collect_updates(text).await;
1949        let resp = ChatResponse::from_updates(updates);
1950        assert_eq!(resp.text(), "Hello!");
1951        assert_eq!(resp.response_id.as_deref(), Some("resp_1"));
1952        assert_eq!(resp.finish_reason, Some(FinishReason::stop()));
1953        let usage = resp.usage_details.unwrap();
1954        assert_eq!(usage.input_token_count, Some(3));
1955        assert_eq!(usage.output_token_count, Some(2));
1956    }
1957
1958    #[tokio::test]
1959    async fn stream_tool_call_accumulates_arguments() {
1960        let text = sse_body(&[
1961            (
1962                "response.output_item.added",
1963                json!({ "type": "response.output_item.added", "output_index": 0, "item": { "type": "function_call", "call_id": "call_1", "name": "get_weather" } }),
1964            ),
1965            (
1966                "response.function_call_arguments.delta",
1967                json!({ "type": "response.function_call_arguments.delta", "output_index": 0, "delta": "{\"city\":" }),
1968            ),
1969            (
1970                "response.function_call_arguments.delta",
1971                json!({ "type": "response.function_call_arguments.delta", "output_index": 0, "delta": "\"Paris\"}" }),
1972            ),
1973            (
1974                "response.completed",
1975                json!({ "type": "response.completed", "response": { "id": "resp_2", "status": "completed", "output": [{"type":"function_call","call_id":"call_1","name":"get_weather","arguments":"{\"city\":\"Paris\"}"}] } }),
1976            ),
1977        ]);
1978        let updates = collect_updates(text).await;
1979        let resp = ChatResponse::from_updates(updates);
1980        let calls = resp.function_calls();
1981        assert_eq!(calls.len(), 1);
1982        assert_eq!(calls[0].call_id, "call_1");
1983        assert_eq!(calls[0].name, "get_weather");
1984        assert_eq!(
1985            calls[0].parse_arguments().unwrap().get("city").unwrap(),
1986            &json!("Paris")
1987        );
1988        assert_eq!(resp.finish_reason, Some(FinishReason::tool_calls()));
1989    }
1990
1991    #[tokio::test]
1992    async fn stream_failed_event_is_error() {
1993        let text = sse_body(&[(
1994            "response.failed",
1995            json!({ "type": "response.failed", "response": { "error": { "message": "boom" } } }),
1996        )]);
1997        let stream =
1998            futures::stream::once(async move { Ok::<_, reqwest::Error>(bytes::Bytes::from(text)) });
1999        let byte_stream: ByteStream = Box::pin(stream);
2000        let mut state = ResponsesSseState {
2001            byte_stream,
2002            buffer: String::new(),
2003            utf8: Utf8StreamDecoder::new(),
2004            queued: VecDeque::new(),
2005            call_ids: HashMap::new(),
2006            done: false,
2007            store: None,
2008        };
2009        let bytes = state.byte_stream.next().await.unwrap().unwrap();
2010        let decoded = state.utf8.push(&bytes);
2011        state.buffer.push_str(&decoded);
2012        let mut saw_error = false;
2013        while let Some(pos) = state.buffer.find('\n') {
2014            let line = state.buffer[..pos].trim().to_string();
2015            state.buffer.drain(..=pos);
2016            let Some(data) = line.strip_prefix("data:") else {
2017                continue;
2018            };
2019            let data = data.trim();
2020            if data.is_empty() {
2021                continue;
2022            }
2023            let value: Value = serde_json::from_str(data).unwrap();
2024            if let EventOutcome::Error(e) =
2025                parse_responses_event(&value, &mut state.call_ids, state.store)
2026            {
2027                assert!(e.to_string().contains("boom"));
2028                saw_error = true;
2029            }
2030        }
2031        assert!(
2032            saw_error,
2033            "expected a response.failed event to surface an error"
2034        );
2035    }
2036
2037    #[test]
2038    fn stream_failed_event_classifies_content_filter() {
2039        // Streamed and non-streamed Responses failures must classify alike
2040        // (mirrors `response_failure_error`).
2041        let mut call_ids = HashMap::new();
2042        let filtered = parse_responses_event(
2043            &json!({
2044                "type": "response.failed",
2045                "response": { "error": { "code": "content_filter", "message": "blocked" } }
2046            }),
2047            &mut call_ids,
2048            None,
2049        );
2050        let EventOutcome::Error(err) = filtered else {
2051            panic!("expected an error outcome");
2052        };
2053        assert!(matches!(err, Error::ServiceContentFilter { .. }));
2054
2055        let generic = parse_responses_event(
2056            &json!({
2057                "type": "response.failed",
2058                "response": { "error": { "code": "server_error", "message": "boom" } }
2059            }),
2060            &mut call_ids,
2061            None,
2062        );
2063        let EventOutcome::Error(err) = generic else {
2064            panic!("expected an error outcome");
2065        };
2066        assert!(matches!(err, Error::Service(_)));
2067    }
2068
2069    // endregion
2070
2071    // region: env-var constructor
2072
2073    /// Guards `OPENAI_API_KEY` / `OPENAI_BASE_URL` mutation: `cargo test` runs
2074    /// tests in the same process on multiple threads, and env vars are
2075    /// process-global, so concurrent set/remove across tests would be racy
2076    /// without serializing access.
2077    static ENV_MUTEX: std::sync::Mutex<()> = std::sync::Mutex::new(());
2078
2079    #[test]
2080    fn from_env_reads_api_key_and_base_url() {
2081        let _guard = ENV_MUTEX.lock().unwrap();
2082        // SAFETY: serialized by ENV_MUTEX against the other env-var test in
2083        // this module; no other test in this crate touches these variables.
2084        unsafe {
2085            std::env::set_var("OPENAI_API_KEY", "sk-test-123");
2086            std::env::set_var("OPENAI_BASE_URL", "https://example.test/v1");
2087        }
2088        let client = OpenAIChatClient::from_env("gpt-4o-mini").unwrap();
2089        assert_eq!(client.inner.api_key, "sk-test-123");
2090        assert_eq!(client.inner.base_url, "https://example.test/v1");
2091        unsafe {
2092            std::env::remove_var("OPENAI_API_KEY");
2093            std::env::remove_var("OPENAI_BASE_URL");
2094        }
2095    }
2096
2097    #[test]
2098    fn from_env_errors_when_api_key_missing() {
2099        let _guard = ENV_MUTEX.lock().unwrap();
2100        // SAFETY: serialized by ENV_MUTEX; see above.
2101        unsafe {
2102            std::env::remove_var("OPENAI_API_KEY");
2103            std::env::remove_var("OPENAI_BASE_URL");
2104        }
2105        let result = OpenAIChatClient::from_env("gpt-4o-mini");
2106        assert!(result.is_err());
2107    }
2108    #[test]
2109    fn build_body_maps_hosted_tools_to_responses_types() {
2110        use agent_framework_core::tools::{
2111            hosted_code_interpreter, hosted_file_search, hosted_mcp, hosted_web_search,
2112        };
2113        let c = client();
2114        let mut options = ChatOptions::new();
2115        options.tools = vec![
2116            hosted_web_search(),
2117            hosted_code_interpreter(),
2118            hosted_file_search(Some(7)),
2119            hosted_mcp(
2120                "docs",
2121                "https://mcp.example/sse",
2122                Some(vec!["search".into()]),
2123            ),
2124        ];
2125        let body = c.build_body(&[user("hi")], &options, false);
2126        let tools = body["tools"].as_array().unwrap();
2127        assert_eq!(tools[0], json!({ "type": "web_search" }));
2128        assert_eq!(
2129            tools[1],
2130            json!({ "type": "code_interpreter", "container": { "type": "auto" } })
2131        );
2132        assert_eq!(tools[2]["type"], "file_search");
2133        assert_eq!(tools[2]["max_num_results"], json!(7));
2134        assert_eq!(tools[3]["type"], "mcp");
2135        assert_eq!(tools[3]["server_url"], "https://mcp.example/sse");
2136        assert_eq!(tools[3]["allowed_tools"], json!(["search"]));
2137        assert_eq!(tools[3]["require_approval"], "never");
2138    }
2139
2140    // endregion
2141
2142    // region: multimodal input (Responses)
2143
2144    #[test]
2145    fn input_image_uri_becomes_input_image_part() {
2146        let msg = user_with(vec![Content::Uri(UriContent {
2147            uri: "https://example.com/cat.png".into(),
2148            media_type: "image/png".into(),
2149        })]);
2150        let input = messages_to_input(&[msg]);
2151        assert_eq!(
2152            input[0],
2153            json!({ "type": "message", "role": "user", "content": [
2154                { "type": "input_image", "image_url": "https://example.com/cat.png", "detail": "auto" }
2155            ]})
2156        );
2157    }
2158
2159    #[test]
2160    fn input_audio_file_and_hosted_file_parts() {
2161        let msg = user_with(vec![
2162            Content::Data(DataContent {
2163                uri: "data:audio/wav;base64,QQ".into(),
2164                media_type: Some("audio/wav".into()),
2165            }),
2166            Content::Data(DataContent {
2167                uri: "data:application/pdf;base64,JV".into(),
2168                media_type: Some("application/pdf".into()),
2169            }),
2170            Content::HostedFile(HostedFileContent {
2171                file_id: "file-123".into(),
2172            }),
2173        ]);
2174        let input = messages_to_input(&[msg]);
2175        // `input_audio.data` is the raw base64 payload (data-URI prefix
2176        // stripped), the same wire rule as Chat Completions; file inputs keep
2177        // the full data URI in `file_data`.
2178        assert_eq!(
2179            input[0]["content"],
2180            json!([
2181                { "type": "input_audio", "input_audio": { "data": "QQ", "format": "wav" } },
2182                { "type": "input_file", "file_data": "data:application/pdf;base64,JV", "filename": "file" },
2183                { "type": "input_file", "file_id": "file-123" },
2184            ])
2185        );
2186    }
2187
2188    #[test]
2189    fn approval_response_becomes_mcp_approval_response_item() {
2190        let resp = FunctionApprovalResponseContent {
2191            approved: true,
2192            id: "appr_1".into(),
2193            function_call: FunctionCallContent::new("appr_1", "search", None),
2194        };
2195        let msg = user_with(vec![Content::FunctionApprovalResponse(resp)]);
2196        let input = messages_to_input(&[msg]);
2197        assert_eq!(
2198            input[0],
2199            json!({
2200                "type": "mcp_approval_response",
2201                "approval_request_id": "appr_1",
2202                "approve": true,
2203            })
2204        );
2205    }
2206
2207    #[test]
2208    fn approval_request_becomes_mcp_approval_request_item() {
2209        let req = FunctionApprovalRequestContent {
2210            id: "appr_1".into(),
2211            function_call: FunctionCallContent::new(
2212                "appr_1",
2213                "search",
2214                Some(FunctionArguments::Raw(r#"{"q":"x"}"#.into())),
2215            ),
2216        };
2217        let msg = Message::with_contents(
2218            Role::assistant(),
2219            vec![Content::FunctionApprovalRequest(req)],
2220        );
2221        let input = messages_to_input(&[msg]);
2222        assert_eq!(
2223            input[0],
2224            json!({
2225                "type": "mcp_approval_request",
2226                "id": "appr_1",
2227                "name": "search",
2228                "arguments": r#"{"q":"x"}"#,
2229            })
2230        );
2231    }
2232
2233    // endregion
2234
2235    // region: output parsing (annotations, code interpreter, images, approvals)
2236
2237    #[test]
2238    fn output_text_url_citation_annotation() {
2239        let contents = parse_item(json!({
2240            "type": "message", "role": "assistant", "content": [{
2241                "type": "output_text", "text": "See source.",
2242                "annotations": [{
2243                    "type": "url_citation", "title": "Src", "url": "https://ex.com",
2244                    "start_index": 0, "end_index": 3,
2245                }],
2246            }],
2247        }));
2248        let Content::Text(t) = &contents[0] else {
2249            panic!("expected text content");
2250        };
2251        let ann = t.annotations.as_ref().unwrap();
2252        assert_eq!(ann[0].title.as_deref(), Some("Src"));
2253        assert_eq!(ann[0].url.as_deref(), Some("https://ex.com"));
2254        let region = &ann[0].annotated_regions.as_ref().unwrap()[0];
2255        assert_eq!(region.start_index, Some(0));
2256        assert_eq!(region.end_index, Some(3));
2257    }
2258
2259    #[test]
2260    fn output_text_file_and_container_citations() {
2261        let contents = parse_item(json!({
2262            "type": "message", "role": "assistant", "content": [{
2263                "type": "output_text", "text": "x",
2264                "annotations": [
2265                    { "type": "file_citation", "filename": "doc.pdf", "file_id": "file-1", "index": 2 },
2266                    { "type": "file_path", "file_id": "file-2", "index": 0 },
2267                    { "type": "container_file_citation", "filename": "c.txt", "file_id": "file-3",
2268                      "container_id": "cont-1", "start_index": 1, "end_index": 4 },
2269                ],
2270            }],
2271        }));
2272        let Content::Text(t) = &contents[0] else {
2273            panic!("expected text content");
2274        };
2275        let ann = t.annotations.as_ref().unwrap();
2276        assert_eq!(ann[0].url.as_deref(), Some("doc.pdf"));
2277        assert_eq!(ann[0].file_id.as_deref(), Some("file-1"));
2278        assert_eq!(ann[1].file_id.as_deref(), Some("file-2"));
2279        assert_eq!(ann[2].file_id.as_deref(), Some("file-3"));
2280        assert_eq!(ann[2].url.as_deref(), Some("c.txt"));
2281        assert_eq!(
2282            ann[2].annotated_regions.as_ref().unwrap()[0].end_index,
2283            Some(4)
2284        );
2285    }
2286
2287    #[test]
2288    fn code_interpreter_outputs_become_text_and_uri() {
2289        let contents = parse_item(json!({
2290            "type": "code_interpreter_call",
2291            "outputs": [
2292                { "type": "logs", "logs": "hello stdout" },
2293                { "type": "image", "url": "https://ex.com/plot.png" },
2294            ],
2295        }));
2296        assert!(matches!(&contents[0], Content::Text(t) if t.text == "hello stdout"));
2297        assert!(
2298            matches!(&contents[1], Content::Uri(u) if u.uri == "https://ex.com/plot.png" && u.media_type == "image")
2299        );
2300    }
2301
2302    #[test]
2303    fn code_interpreter_without_outputs_falls_back_to_code() {
2304        let contents = parse_item(json!({
2305            "type": "code_interpreter_call", "code": "print(1)",
2306        }));
2307        assert!(matches!(&contents[0], Content::Text(t) if t.text == "print(1)"));
2308    }
2309
2310    #[test]
2311    fn image_generation_raw_base64_becomes_png_data() {
2312        let contents = parse_item(json!({
2313            "type": "image_generation_call", "result": "AAAABBBB",
2314        }));
2315        let Content::Data(d) = &contents[0] else {
2316            panic!("expected data content");
2317        };
2318        assert_eq!(d.uri, "data:image/png;base64,AAAABBBB");
2319        assert_eq!(d.media_type.as_deref(), Some("image/png"));
2320    }
2321
2322    #[test]
2323    fn image_generation_data_uri_keeps_stated_media_type() {
2324        let contents = parse_item(json!({
2325            "type": "image_generation_call", "result": "data:image/webp;base64,ZZZ",
2326        }));
2327        let Content::Data(d) = &contents[0] else {
2328            panic!("expected data content");
2329        };
2330        assert_eq!(d.uri, "data:image/webp;base64,ZZZ");
2331        assert_eq!(d.media_type.as_deref(), Some("image/webp"));
2332    }
2333
2334    #[test]
2335    fn mcp_approval_request_output_round_trips_into_response() {
2336        let contents = parse_item(json!({
2337            "type": "mcp_approval_request",
2338            "id": "appr_9", "name": "search", "arguments": r#"{"q":"rust"}"#,
2339            "server_label": "docs",
2340        }));
2341        let Content::FunctionApprovalRequest(req) = &contents[0] else {
2342            panic!("expected approval request");
2343        };
2344        assert_eq!(req.id, "appr_9");
2345        assert_eq!(req.function_call.call_id, "appr_9");
2346        assert_eq!(req.function_call.name, "search");
2347
2348        // The id round-trips into the request's response item (item 5).
2349        let msg = user_with(vec![Content::FunctionApprovalResponse(
2350            req.create_response(true),
2351        )]);
2352        let input = messages_to_input(&[msg]);
2353        assert_eq!(input[0]["type"], json!("mcp_approval_response"));
2354        assert_eq!(input[0]["approval_request_id"], json!("appr_9"));
2355        assert_eq!(input[0]["approve"], json!(true));
2356    }
2357
2358    // endregion
2359
2360    // region: streaming reasoning
2361
2362    fn reasoning_event(value: Value) -> EventOutcome {
2363        let mut ids = HashMap::new();
2364        parse_responses_event(&value, &mut ids, None)
2365    }
2366
2367    #[test]
2368    fn a_replayed_refusal_becomes_a_refusal_content_part() {
2369        // Beside `output_text` in an output message, a refusal has its own
2370        // part type. Re-emitting it as `output_text` replays a decline to the
2371        // provider as an answer.
2372        let input = messages_to_input(&[Message::with_contents(
2373            Role::assistant(),
2374            vec![
2375                Content::Text(TextContent::new("here is half")),
2376                Content::Text(TextContent::refusal("I can't do the rest")),
2377            ],
2378        )]);
2379        let content = &input[0]["content"];
2380        assert_eq!(
2381            content[0],
2382            json!({"type": "output_text", "text": "here is half"})
2383        );
2384        assert_eq!(
2385            content[1],
2386            json!({"type": "refusal", "refusal": "I can't do the rest"})
2387        );
2388    }
2389
2390    #[test]
2391    fn a_refusal_on_a_non_assistant_role_is_dropped_rather_than_mis_encoded() {
2392        // An *input* message's content list admits only
2393        // input_text/input_image/input_file — there is no refusal part — so
2394        // emitting one would be rejected by the API. Dropping it is the only
2395        // correct option, and it cannot arise from a parsed provider response
2396        // anyway (refusals are assistant output).
2397        let input = messages_to_input(&[Message::with_contents(
2398            Role::user(),
2399            vec![
2400                Content::Text(TextContent::new("hello")),
2401                Content::Text(TextContent::refusal("stray")),
2402            ],
2403        )]);
2404        let content = &input[0]["content"];
2405        assert_eq!(content.as_array().map(Vec::len), Some(1));
2406        assert_eq!(content[0], json!({"type": "input_text", "text": "hello"}));
2407    }
2408
2409    #[test]
2410    fn a_streamed_refusal_is_marked_and_its_done_event_is_not_duplicated() {
2411        // Before this, `response.refusal.delta` fell through the catch-all
2412        // and a streamed decline reached the caller as an empty response —
2413        // the non-streaming path marked refusals while the streaming path
2414        // dropped them.
2415        let EventOutcome::Update(delta) =
2416            reasoning_event(json!({ "type": "response.refusal.delta", "delta": "I can't" }))
2417        else {
2418            panic!("expected update");
2419        };
2420        assert!(matches!(&delta.contents[0], Content::Text(t) if t.refusal && t.text == "I can't"));
2421
2422        // `.done` repeats the whole refusal; emitting it would double the
2423        // text already streamed, exactly as for the text channel.
2424        let done =
2425            reasoning_event(json!({ "type": "response.refusal.done", "refusal": "I can't help" }));
2426        assert!(matches!(done, EventOutcome::None));
2427    }
2428
2429    #[test]
2430    fn reasoning_text_delta_streams_and_done_is_terminal_metadata() {
2431        let EventOutcome::Update(delta) =
2432            reasoning_event(json!({ "type": "response.reasoning_text.delta", "delta": "Th" }))
2433        else {
2434            panic!("expected update");
2435        };
2436        assert!(matches!(&delta.contents[0], Content::TextReasoning(t) if t.text == "Th"));
2437
2438        // `.done` carries the full text the deltas already streamed — emitting
2439        // it again would duplicate the reasoning in the aggregate.
2440        let done =
2441            reasoning_event(json!({ "type": "response.reasoning_text.done", "text": "Think" }));
2442        assert!(matches!(done, EventOutcome::None));
2443    }
2444
2445    #[test]
2446    fn reasoning_summary_text_events_map_to_reasoning_content() {
2447        let EventOutcome::Update(delta) = reasoning_event(
2448            json!({ "type": "response.reasoning_summary_text.delta", "delta": "sum" }),
2449        ) else {
2450            panic!("expected update");
2451        };
2452        assert!(matches!(&delta.contents[0], Content::TextReasoning(t) if t.text == "sum"));
2453
2454        let done = reasoning_event(
2455            json!({ "type": "response.reasoning_summary_text.done", "text": "summary" }),
2456        );
2457        assert!(matches!(done, EventOutcome::None));
2458    }
2459
2460    #[test]
2461    fn response_failure_error_classifies_content_filter() {
2462        let filtered = json!({
2463            "status": "failed",
2464            "error": { "code": "content_filter", "message": "blocked" }
2465        });
2466        assert!(matches!(
2467            response_failure_error(&filtered),
2468            Some(Error::ServiceContentFilter { .. })
2469        ));
2470
2471        let generic = json!({
2472            "status": "failed",
2473            "error": { "code": "server_error", "message": "boom" }
2474        });
2475        assert!(matches!(
2476            response_failure_error(&generic),
2477            Some(Error::Service(_))
2478        ));
2479
2480        assert!(response_failure_error(&json!({ "status": "completed" })).is_none());
2481    }
2482
2483    #[test]
2484    fn input_audio_data_strips_data_uri_prefix() {
2485        let part = content_to_input_part("data:audio/wav;base64,QUJD", Some("audio/wav"))
2486            .expect("audio part");
2487        assert_eq!(part["input_audio"]["data"], "QUJD");
2488        assert_eq!(part["input_audio"]["format"], "wav");
2489    }
2490
2491    // endregion
2492
2493    // region: hosted-tool config passthrough
2494
2495    fn hosted(kind: ToolKind, name: &str, params: Value) -> ToolDefinition {
2496        ToolDefinition {
2497            name: name.into(),
2498            description: String::new(),
2499            parameters: params,
2500            kind,
2501            approval_mode: ApprovalMode::NeverRequire,
2502            executor: None,
2503        }
2504    }
2505
2506    #[test]
2507    fn web_search_passes_through_user_location() {
2508        let tool = hosted(
2509            ToolKind::HostedWebSearch,
2510            "web_search",
2511            json!({ "user_location": { "city": "Paris", "country": "FR" } }),
2512        );
2513        assert_eq!(
2514            tool_to_responses_spec(&tool),
2515            json!({
2516                "type": "web_search",
2517                "user_location": { "type": "approximate", "city": "Paris", "country": "FR" },
2518            })
2519        );
2520    }
2521
2522    #[test]
2523    fn file_search_passes_vector_store_ids_and_max_results_param() {
2524        let tool = hosted(
2525            ToolKind::HostedFileSearch { max_results: None },
2526            "file_search",
2527            json!({ "vector_store_ids": ["vs_1"], "max_results": 12 }),
2528        );
2529        let spec = tool_to_responses_spec(&tool);
2530        assert_eq!(spec["vector_store_ids"], json!(["vs_1"]));
2531        assert_eq!(spec["max_num_results"], json!(12));
2532    }
2533
2534    #[test]
2535    fn image_generation_maps_to_responses_tool_with_passthrough_params() {
2536        let tool = hosted(
2537            ToolKind::HostedImageGeneration,
2538            "image_generation",
2539            json!({ "size": "1024x1024", "quality": "high" }),
2540        );
2541        let spec = tool_to_responses_spec(&tool);
2542        assert_eq!(spec["type"], json!("image_generation"));
2543        assert_eq!(spec["size"], json!("1024x1024"));
2544        assert_eq!(spec["quality"], json!("high"));
2545    }
2546
2547    #[test]
2548    fn code_interpreter_passes_file_ids_and_container_override() {
2549        let with_files = hosted(
2550            ToolKind::HostedCodeInterpreter,
2551            "ci",
2552            json!({ "file_ids": ["file-1", "file-2"] }),
2553        );
2554        assert_eq!(
2555            tool_to_responses_spec(&with_files)["container"],
2556            json!({ "type": "auto", "file_ids": ["file-1", "file-2"] })
2557        );
2558        let with_container = hosted(
2559            ToolKind::HostedCodeInterpreter,
2560            "ci",
2561            json!({ "container": { "type": "secure", "id": "c1" } }),
2562        );
2563        assert_eq!(
2564            tool_to_responses_spec(&with_container)["container"],
2565            json!({ "type": "secure", "id": "c1" })
2566        );
2567    }
2568
2569    #[test]
2570    fn mcp_passes_headers_and_string_approval_mode_override() {
2571        let tool = hosted(
2572            ToolKind::HostedMcp {
2573                url: "https://mcp/sse".into(),
2574                allowed_tools: None,
2575            },
2576            "docs",
2577            json!({ "headers": { "Authorization": "Bearer x" }, "approval_mode": "always_require" }),
2578        );
2579        // The enum default is NeverRequire; the parameter overrides it.
2580        let spec = tool_to_responses_spec(&tool);
2581        assert_eq!(spec["headers"], json!({ "Authorization": "Bearer x" }));
2582        assert_eq!(spec["require_approval"], json!("always"));
2583    }
2584
2585    #[test]
2586    fn mcp_object_approval_mode_maps_to_tool_name_lists() {
2587        let tool = hosted(
2588            ToolKind::HostedMcp {
2589                url: "https://mcp/sse".into(),
2590                allowed_tools: None,
2591            },
2592            "docs",
2593            json!({ "approval_mode": { "always": ["delete"], "never": ["read"] } }),
2594        );
2595        assert_eq!(
2596            tool_to_responses_spec(&tool)["require_approval"],
2597            json!({ "always": { "tool_names": ["delete"] }, "never": { "tool_names": ["read"] } })
2598        );
2599    }
2600
2601    // endregion
2602}