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