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::{BTreeMap, 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, CodeInterpreterToolCallContent,
33    CodeInterpreterToolResultContent, Content, ContinuationToken, DataContent, FinishReason,
34    FunctionApprovalRequestContent, FunctionArguments, FunctionCallContent, FunctionResultContent,
35    McpServerToolCallContent, McpServerToolResultContent, Message, OauthConsentRequestContent,
36    OperationState, ResponseFormat, Role, TextContent, TextReasoningContent, TextSpanRegion,
37    ToolMode, UriContent, UsageContent, UsageDetails,
38};
39use futures::StreamExt;
40use serde_json::{json, Map, Value};
41
42use crate::convert::{
43    audio_format, data_content_media_type, function_arguments_to_string, result_to_string,
44    top_level_media_type, DEFAULT_FILENAME,
45};
46use crate::{ByteStream, DEFAULT_BASE_URL};
47
48/// The continuation token of a Responses API background operation.
49///
50/// Mirrors upstream Python `OpenAIContinuationToken` (`{"response_id": ...}`),
51/// plus the stream position .NET's Responses client keeps
52/// (`sequence_number`): the last stream event the caller received, so a
53/// resumed stream continues after it (`starting_after`) instead of replaying
54/// the whole response. It travels inside the opaque core
55/// [`ContinuationToken`] as JSON; [`Self::from_token`] also accepts a bare
56/// response id.
57#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
58pub struct OpenAIContinuationToken {
59    /// The Responses API response id (`resp_...`).
60    pub response_id: String,
61    /// The `sequence_number` of the last stream event delivered, when the
62    /// token came from a stream.
63    #[serde(default, skip_serializing_if = "Option::is_none")]
64    pub sequence_number: Option<u64>,
65    /// The function calls the stream announced before this position, as
66    /// `output_index` → `call_id`. A resumed stream starts after the
67    /// `response.output_item.added` event that announced a call, so without
68    /// these its later `response.function_call_arguments.delta` fragments
69    /// could not be routed to the call they belong to.
70    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
71    pub function_calls: BTreeMap<i64, String>,
72}
73
74impl OpenAIContinuationToken {
75    /// A token for `response_id`, with no stream position.
76    pub fn new(response_id: impl Into<String>) -> Self {
77        Self {
78            response_id: response_id.into(),
79            sequence_number: None,
80            function_calls: BTreeMap::new(),
81        }
82    }
83
84    /// The opaque core token carrying this one.
85    pub fn to_token(&self) -> ContinuationToken {
86        ContinuationToken::new(serde_json::to_string(self).unwrap_or_default())
87    }
88
89    /// Read a token issued by this client (or a bare response id).
90    pub fn from_token(token: &ContinuationToken) -> Result<Self> {
91        let raw = token.as_str().trim();
92        if raw.starts_with('{') {
93            return serde_json::from_str::<Self>(raw)
94                .ok()
95                .filter(|t| !t.response_id.is_empty())
96                .ok_or_else(|| {
97                    Error::Configuration(format!(
98                        "not an OpenAI Responses continuation token: {raw}"
99                    ))
100                });
101        }
102        if raw.is_empty() {
103            return Err(Error::Configuration(
104                "an OpenAI Responses continuation token needs a response id".into(),
105            ));
106        }
107        Ok(Self::new(raw))
108    }
109}
110
111/// Whether a Responses API `status` means the operation is still running.
112fn is_pending_status(status: Option<&str>) -> bool {
113    matches!(status, Some("queued" | "in_progress"))
114}
115
116/// An OpenAI Responses API chat client (`POST /v1/responses`).
117#[derive(Clone)]
118pub struct OpenAIChatClient {
119    inner: Arc<Inner>,
120}
121
122#[derive(Clone)]
123struct Inner {
124    http: reqwest::Client,
125    api_key: String,
126    base_url: String,
127    model: String,
128    organization: Option<String>,
129}
130
131impl std::fmt::Debug for OpenAIChatClient {
132    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
133        f.debug_struct("OpenAIChatClient")
134            .field("base_url", &self.inner.base_url)
135            .field("model", &self.inner.model)
136            .field("organization", &self.inner.organization)
137            .finish_non_exhaustive()
138    }
139}
140
141impl OpenAIChatClient {
142    /// Create a client for the given API key and default model.
143    pub fn new(api_key: impl Into<String>, model: impl Into<String>) -> Self {
144        Self {
145            inner: Arc::new(Inner {
146                http: crate::http_client(),
147                api_key: api_key.into(),
148                base_url: DEFAULT_BASE_URL.to_string(),
149                model: model.into(),
150                organization: None,
151            }),
152        }
153    }
154
155    /// Build a client from the `OPENAI_API_KEY` (and optional
156    /// `OPENAI_BASE_URL`) environment variables.
157    pub fn from_env(model: impl Into<String>) -> Result<Self> {
158        let key = std::env::var("OPENAI_API_KEY")
159            .map_err(|_| Error::Configuration("OPENAI_API_KEY is not set".into()))?;
160        let mut client = Self::new(key, model);
161        if let Ok(base) = std::env::var("OPENAI_BASE_URL") {
162            client = client.with_base_url(base);
163        }
164        Ok(client)
165    }
166
167    /// Override the base URL (for Azure OpenAI or compatible servers).
168    pub fn with_base_url(mut self, base_url: impl Into<String>) -> Self {
169        Arc::make_mut(&mut self.inner).base_url = base_url.into();
170        self
171    }
172
173    /// Set the organization header.
174    pub fn with_organization(mut self, org: impl Into<String>) -> Self {
175        Arc::make_mut(&mut self.inner).organization = Some(org.into());
176        self
177    }
178
179    /// The default model id.
180    pub fn model(&self) -> &str {
181        &self.inner.model
182    }
183
184    fn build_body(&self, messages: &[Message], options: &ChatOptions, stream: bool) -> Value {
185        let mut body = Map::new();
186        let model = options
187            .model
188            .clone()
189            .unwrap_or_else(|| self.inner.model.clone());
190        body.insert("model".into(), json!(model));
191
192        let (instructions, rest) = extract_instructions(messages, options.instructions.as_deref());
193        if let Some(instructions) = instructions {
194            body.insert("instructions".into(), json!(instructions));
195        }
196        let input = if uses_service_side_storage(options) {
197            messages_to_continuation_input(rest)
198        } else {
199            messages_to_input(rest)
200        };
201        body.insert("input".into(), json!(input));
202
203        if let Some(conversation_id) = &options.conversation_id {
204            body.insert("previous_response_id".into(), json!(conversation_id));
205        }
206        if let Some(t) = options.temperature {
207            body.insert("temperature".into(), json!(t));
208        }
209        if let Some(t) = options.top_p {
210            body.insert("top_p".into(), json!(t));
211        }
212        if let Some(mt) = options.max_tokens {
213            body.insert("max_output_tokens".into(), json!(mt));
214        }
215        if let Some(store) = options.store {
216            body.insert("store".into(), json!(store));
217        }
218        if let Some(user) = &options.user {
219            body.insert("user".into(), json!(user));
220        }
221        if let Some(metadata) = &options.metadata {
222            body.insert("metadata".into(), json!(metadata));
223        }
224        if let Some(background) = options.background {
225            body.insert("background".into(), json!(background));
226        }
227
228        if !options.tools.is_empty() {
229            let tools: Vec<Value> = options.tools.iter().map(tool_to_responses_spec).collect();
230            body.insert("tools".into(), json!(tools));
231            if let Some(allow_multi) = options.allow_multiple_tool_calls {
232                body.insert("parallel_tool_calls".into(), json!(allow_multi));
233            }
234        }
235        if let Some(tool_choice) = &options.tool_choice {
236            body.insert("tool_choice".into(), tool_choice_to_responses(tool_choice));
237        }
238        if let Some(fmt) = &options.response_format {
239            body.insert(
240                "text".into(),
241                json!({ "format": response_format_to_text(fmt) }),
242            );
243        }
244
245        // Inserted before the `additional_properties` pass below, whose
246        // A caller's own `include` entries are already folded in here.
247        if let Some(include) = responses_include(options, true) {
248            body.insert("include".into(), include);
249        }
250
251        for (k, v) in &options.additional_properties {
252            // `include` belongs to `responses_include` alone. Letting it
253            // through would resurrect a value that function deliberately
254            // dropped — an explicit empty array would land as `include: []`,
255            // the one shape it exists to avoid.
256            if k == "include" {
257                continue;
258            }
259            body.entry(k.clone()).or_insert_with(|| v.clone());
260        }
261
262        if stream {
263            body.insert("stream".into(), json!(true));
264        }
265        Value::Object(body)
266    }
267
268    fn responses_url(&self) -> String {
269        format!("{}/responses", self.inner.base_url.trim_end_matches('/'))
270    }
271
272    async fn post(&self, body: &Value) -> Result<reqwest::Response> {
273        let req = self.inner.http.post(self.responses_url()).json(body);
274        self.send(req).await
275    }
276
277    /// `GET /responses/{id}`: poll a background response, or (with
278    /// `stream`) resume its event stream after `starting_after`.
279    async fn retrieve(
280        &self,
281        token: &OpenAIContinuationToken,
282        stream: bool,
283    ) -> Result<reqwest::Response> {
284        let url = format!("{}/{}", self.responses_url(), token.response_id);
285        let mut req = self.inner.http.get(url);
286        if stream {
287            req = req.query(&[("stream", "true")]);
288            if let Some(after) = token.sequence_number {
289                req = req.query(&[("starting_after", after)]);
290            }
291        }
292        self.send(req).await
293    }
294
295    async fn send(&self, req: reqwest::RequestBuilder) -> Result<reqwest::Response> {
296        let mut req = req.bearer_auth(&self.inner.api_key);
297        if let Some(org) = &self.inner.organization {
298            req = req.header("OpenAI-Organization", org);
299        }
300        let resp = req.send().await.map_err(|e| {
301            Error::service(format!(
302                "request failed: {}",
303                agent_framework_core::error::error_chain(&e)
304            ))
305        })?;
306        if !resp.status().is_success() {
307            let status = resp.status();
308            let retry_after = crate::parse_retry_after(resp.headers());
309            let text = resp.text().await.unwrap_or_default();
310            return Err(crate::classify_service_error(
311                status.as_u16(),
312                &text,
313                format!("OpenAI API error {status}: {text}"),
314                retry_after,
315            ));
316        }
317        Ok(resp)
318    }
319}
320
321#[async_trait::async_trait]
322impl ChatClient for OpenAIChatClient {
323    async fn get_response(
324        &self,
325        messages: Vec<Message>,
326        options: ChatOptions,
327    ) -> Result<ChatResponse> {
328        // A continuation token polls the background response it names
329        // (upstream `responses.retrieve(response_id)`); the messages are not
330        // sent, since that response already has its input.
331        let resp = match &options.continuation_token {
332            Some(token) => {
333                let token = OpenAIContinuationToken::from_token(token)?;
334                self.retrieve(&token, false).await?
335            }
336            None => {
337                let body = self.build_body(&messages, &options, false);
338                self.post(&body).await?
339            }
340        };
341        let value: Value = resp
342            .json()
343            .await
344            .map_err(|e| Error::service(format!("invalid response json: {e}")))?;
345        if let Some(err) = response_failure_error(&value) {
346            return Err(err);
347        }
348        Ok(parse_response(&value, options.store))
349    }
350
351    async fn get_streaming_response(
352        &self,
353        messages: Vec<Message>,
354        options: ChatOptions,
355    ) -> Result<ChatStream> {
356        // A continuation token resumes the background response's event
357        // stream after the last event the caller saw.
358        if let Some(token) = &options.continuation_token {
359            let token = OpenAIContinuationToken::from_token(token)?;
360            let resp = self.retrieve(&token, true).await?;
361            return Ok(
362                parse_background_responses_sse_stream(resp, options.store, Some(token)).boxed(),
363            );
364        }
365        let body = self.build_body(&messages, &options, true);
366        let resp = self.post(&body).await?;
367        if options.background == Some(true) {
368            return Ok(parse_background_responses_sse_stream(resp, options.store, None).boxed());
369        }
370        Ok(sse_stream(resp, options.store, None, HashMap::new()).boxed())
371    }
372
373    fn model(&self) -> Option<&str> {
374        Some(&self.inner.model)
375    }
376
377    fn service_url(&self) -> Option<&str> {
378        Some(&self.inner.base_url)
379    }
380}
381
382// region: request conversion
383
384/// The `include` entry that asks a reasoning model to return its *encrypted*
385/// reasoning item alongside the summary.
386pub const ENCRYPTED_REASONING_INCLUDE: &str = "reasoning.encrypted_content";
387
388/// Build the Responses request's `include` array.
389///
390/// A reasoning item must be replayed verbatim on the follow-up turn of a tool
391/// loop, and the service only accepts it when it carries its `id` *and*
392/// `encrypted_content`. When the conversation is held service-side the model
393/// already has that item, but on a stateless request nothing is stored — so
394/// unless the request asks for `reasoning.encrypted_content`, the item comes
395/// back without it and the replay in [`messages_to_input`] has nothing valid
396/// to re-send. This adds it implicitly in exactly that case, mirroring
397/// upstream's `_prepare_options`.
398///
399/// A caller's own `include` entries (passed through
400/// `ChatOptions::additional_properties`) are always preserved, and an explicit
401/// `reasoning.encrypted_content` is honored even when `implicit` is `false` —
402/// `implicit` gates only whether it is added on the caller's behalf. Foundry
403/// passes `false` here: it does not want encrypted reasoning unless asked for
404/// it by name (upstream #7536).
405///
406/// Returns `None` when the array would be empty, so a request that needs no
407/// `include` does not carry an empty one.
408///
409/// `pub` for the same reason as [`extract_instructions`]: `agent-framework-azure`'s
410/// Responses client builds its own body and reuses this step rather than
411/// reimplementing it.
412pub fn responses_include(options: &ChatOptions, implicit: bool) -> Option<Value> {
413    let mut include: Vec<Value> = options
414        .additional_properties
415        .get("include")
416        .and_then(Value::as_array)
417        .cloned()
418        .unwrap_or_default();
419
420    // Upstream keys this off the service-side-storage indicators, not `store`:
421    // a request continuing a stored conversation needs nothing echoed back.
422    let uses_service_side_storage = uses_service_side_storage(options);
423
424    let already_present = include
425        .iter()
426        .any(|v| v.as_str() == Some(ENCRYPTED_REASONING_INCLUDE));
427    if implicit && !uses_service_side_storage && !already_present {
428        include.push(json!(ENCRYPTED_REASONING_INCLUDE));
429    }
430
431    (!include.is_empty()).then(|| json!(include))
432}
433
434/// Whether a request continues a service-stored response chain: it carries a
435/// non-empty `conversation_id`, sent as `previous_response_id`
436/// (upstream's `request_uses_service_side_storage`).
437///
438/// `pub` so `agent-framework-azure`'s Responses client makes the same call
439/// when choosing between [`messages_to_input`] and
440/// [`messages_to_continuation_input`].
441pub fn uses_service_side_storage(options: &ChatOptions) -> bool {
442    options
443        .conversation_id
444        .as_deref()
445        .is_some_and(|id| !id.is_empty())
446}
447
448/// Split a leading system message (and/or `ChatOptions::instructions`) out
449/// into the Responses API's top-level `instructions` field, returning the
450/// remaining messages to convert into `input` items.
451///
452/// `pub` (rather than private) so `agent-framework-azure`'s Responses client
453/// can reuse this exact instructions-extraction step ahead of
454/// [`messages_to_input`] when building the Azure OpenAI Responses request
455/// body, instead of reimplementing it.
456pub fn extract_instructions<'a>(
457    messages: &'a [Message],
458    options_instructions: Option<&str>,
459) -> (Option<String>, &'a [Message]) {
460    let mut parts = Vec::new();
461    if let Some(instr) = options_instructions {
462        if !instr.is_empty() {
463            parts.push(instr.to_string());
464        }
465    }
466    let mut rest = messages;
467    if let Some(first) = messages.first() {
468        if first.role == Role::system() {
469            let text = first.text();
470            if !text.is_empty() {
471                parts.push(text);
472            }
473            rest = &messages[1..];
474        }
475    }
476    if parts.is_empty() {
477        (None, rest)
478    } else {
479        (Some(parts.join("\n\n")), rest)
480    }
481}
482
483/// Convert framework messages into the Responses API's `input` item array.
484///
485/// `pub` so `agent-framework-azure`'s Responses client can reuse this
486/// conversion verbatim rather than reimplementing it (Azure OpenAI's
487/// Responses API shares the exact same `input` item wire shape).
488pub fn messages_to_input(messages: &[Message]) -> Vec<Value> {
489    convert_messages(messages, false)
490}
491
492/// Convert framework messages into `input` items for a request that continues
493/// a stored response chain (`previous_response_id`, see
494/// [`uses_service_side_storage`]).
495///
496/// The service already holds every item the earlier responses produced, and
497/// rejects an inline copy of one with a server-issued `id` as a duplicate
498/// ("Duplicate item found with id ..."). So hosted `mcp_call` items (and the
499/// results folded into them), `mcp_approval_request` items and reasoning items
500/// are left out here, as upstream's `_prepare_message_for_openai` does under
501/// `request_uses_service_side_storage` (microsoft/agent-framework#3295).
502/// Approval responses and function results still go out: they are new input
503/// the service pairs to its stored items by id.
504pub fn messages_to_continuation_input(messages: &[Message]) -> Vec<Value> {
505    convert_messages(messages, true)
506}
507
508fn convert_messages(messages: &[Message], continues_stored: bool) -> Vec<Value> {
509    let mut out = Vec::new();
510    for msg in messages {
511        let role = msg.role.as_str();
512        if role == Role::TOOL {
513            for content in &msg.contents {
514                match content {
515                    Content::FunctionResult(fr) => out.push(function_result_to_item(fr)),
516                    Content::McpServerToolResult(r) => attach_mcp_output(&mut out, r),
517                    #[cfg(feature = "experimental-computer-use")]
518                    Content::ComputerToolResult(r) => {
519                        if let Some(item) = computer::result_to_item(r) {
520                            out.push(item);
521                        }
522                    }
523                    _ => {}
524                }
525            }
526            continue;
527        }
528
529        let mut buffered: Vec<Value> = Vec::new();
530        for content in &msg.contents {
531            match content {
532                // A refusal is its own output content part — `{"type":
533                // "refusal", "refusal": "..."}` — sitting beside `output_text`
534                // in an output message. Re-emitting it as `output_text` would
535                // replay a decline to the provider as an answer. Only
536                // meaningful on the assistant side: an *input* message's
537                // content list admits only input_text/input_image/input_file,
538                // so a refusal on any other role has no wire form and is
539                // dropped rather than mis-encoded.
540                Content::Text(t) if t.refusal => {
541                    if role == Role::ASSISTANT {
542                        buffered.push(json!({ "type": "refusal", "refusal": t.text }));
543                    }
544                }
545                Content::Text(t) => {
546                    let text_type = if role == Role::ASSISTANT {
547                        "output_text"
548                    } else {
549                        "input_text"
550                    };
551                    buffered.push(json!({ "type": text_type, "text": t.text }));
552                }
553                Content::Uri(u) => {
554                    if let Some(part) = content_to_input_part(&u.uri, Some(&u.media_type)) {
555                        buffered.push(part);
556                    }
557                }
558                Content::Data(d) => {
559                    if let Some(part) =
560                        content_to_input_part(&d.uri, data_content_media_type(d).as_deref())
561                    {
562                        buffered.push(part);
563                    }
564                }
565                Content::HostedFile(h) => {
566                    buffered.push(json!({ "type": "input_file", "file_id": h.file_id }));
567                }
568                Content::FunctionCall(fc) => {
569                    flush_text(&mut out, &mut buffered, role);
570                    out.push(json!({
571                        "type": "function_call",
572                        "call_id": fc.call_id,
573                        "name": fc.name,
574                        "arguments": function_arguments_to_string(&fc.arguments),
575                    }));
576                }
577                Content::FunctionResult(fr) => {
578                    flush_text(&mut out, &mut buffered, role);
579                    out.push(function_result_to_item(fr));
580                }
581                Content::FunctionApprovalResponse(r) => {
582                    flush_text(&mut out, &mut buffered, role);
583                    out.push(json!({
584                        "type": "mcp_approval_response",
585                        "approval_request_id": r.id,
586                        "approve": r.approved,
587                    }));
588                }
589                // Already stored service-side under continuation; re-sending
590                // its `id` would duplicate it.
591                Content::FunctionApprovalRequest(_) if continues_stored => {}
592                Content::FunctionApprovalRequest(r) => {
593                    flush_text(&mut out, &mut buffered, role);
594                    out.push(json!({
595                        "type": "mcp_approval_request",
596                        "id": r.id,
597                        "name": r.function_call.name,
598                        "arguments": function_arguments_to_string(&r.function_call.arguments),
599                    }));
600                }
601                // A hosted MCP call and its result are one `mcp_call` input
602                // item carrying both `arguments` and `output`
603                // (`_prepare_content_for_openai` + `_coalesce_pending_mcp_results`).
604                // Replayed after its approval pair, it tells the service the
605                // approved call already ran, so local history does not ask
606                // for it again. Under continuation the service already has
607                // the item by its `id`, so it is not re-sent (and its result,
608                // finding no call to attach to, is dropped with it).
609                Content::McpServerToolCall(call) => {
610                    if !continues_stored && !call.call_id.is_empty() {
611                        flush_text(&mut out, &mut buffered, role);
612                        out.push(json!({
613                            "type": "mcp_call",
614                            "id": call.call_id,
615                            "server_label": call.server_name.clone().unwrap_or_default(),
616                            "name": call.tool_name,
617                            "arguments": function_arguments_to_string(&call.arguments),
618                        }));
619                        // Links the completed call to its replayed approval
620                        // request/response pair.
621                        if let (Some(id), Some(Value::Object(item))) =
622                            (&call.approval_request_id, out.last_mut())
623                        {
624                            item.insert("approval_request_id".into(), Value::String(id.clone()));
625                        }
626                    }
627                }
628                Content::McpServerToolResult(result) => {
629                    flush_text(&mut out, &mut buffered, role);
630                    attach_mcp_output(&mut out, result);
631                }
632                // Under service-side storage the call is already stored; only
633                // its output is sent (upstream skips outbound replay there).
634                #[cfg(feature = "experimental-computer-use")]
635                Content::ComputerToolCall(call) => {
636                    if !continues_stored {
637                        flush_text(&mut out, &mut buffered, role);
638                        out.push(computer::call_to_item(call));
639                    }
640                }
641                #[cfg(feature = "experimental-computer-use")]
642                Content::ComputerToolResult(result) => {
643                    flush_text(&mut out, &mut buffered, role);
644                    if let Some(item) = computer::result_to_item(result) {
645                        out.push(item);
646                    }
647                }
648                Content::TextReasoning(tr) => {
649                    // Re-emit the original reasoning item verbatim (store:false
650                    // replay). A summary-only reasoning content with no
651                    // preserved item has no valid input form (it lacks the
652                    // required id/encrypted_content), so it is dropped.
653                    // Under continuation the service already holds the item.
654                    let raw = tr.raw_representation.as_ref().filter(|_| !continues_stored);
655                    if let Some(raw) = raw {
656                        flush_text(&mut out, &mut buffered, role);
657                        out.push(raw.clone());
658                    }
659                }
660                _ => {}
661            }
662        }
663        flush_text(&mut out, &mut buffered, role);
664    }
665    out
666}
667
668/// Set a hosted MCP result's output on the latest `mcp_call` input item with
669/// its id that has none yet. A result with no such call is dropped: the
670/// Responses API has no standalone MCP output item
671/// (`_coalesce_pending_mcp_results`).
672fn attach_mcp_output(out: &mut [Value], result: &McpServerToolResultContent) {
673    if result.call_id.is_empty() {
674        return;
675    }
676    let target = out.iter_mut().rev().find(|item| {
677        item.get("type").and_then(Value::as_str) == Some("mcp_call")
678            && item.get("id").and_then(Value::as_str) == Some(result.call_id.as_str())
679    });
680    if let Some(Value::Object(item)) = target {
681        let unfinished = item.get("output").is_none_or(Value::is_null)
682            && item.get("error").is_none_or(Value::is_null);
683        if !unfinished {
684            return;
685        }
686        // A failed call can carry an error and no output; replaying its
687        // error is what marks it as finished rather than still running.
688        let error = result.error.as_ref().filter(|e| !e.is_null());
689        if result.output.is_some() || error.is_none() {
690            item.insert(
691                "output".into(),
692                Value::String(stringify_mcp_output(result.output.as_ref())),
693            );
694        }
695        if let Some(error) = error {
696            item.insert("error".into(), error.clone());
697        }
698    }
699}
700
701/// Render a hosted MCP result as the string `mcp_call.output` field
702/// (`_stringify_mcp_output`): a string as is, text entries joined, anything
703/// else as JSON.
704fn stringify_mcp_output(output: Option<&Value>) -> String {
705    match output {
706        None | Some(Value::Null) => String::new(),
707        Some(Value::String(s)) => s.clone(),
708        Some(Value::Array(entries)) => entries
709            .iter()
710            .map(|entry| match entry {
711                Value::String(s) => s.clone(),
712                other => match other.get("text").and_then(Value::as_str) {
713                    Some(text) => text.to_string(),
714                    None => other.to_string(),
715                },
716            })
717            .collect(),
718        Some(other) => other.to_string(),
719    }
720}
721
722/// Parse a hosted `mcp_call` output item into its call and, once it has run,
723/// its result (`_create_response_content`'s `mcp_call` arm). The item's `id`
724/// is the call id, falling back to `call_id`. A call that failed carries its
725/// `error` on the result, with or without an `output`.
726fn mcp_call_item_contents(item: &Value) -> Vec<Content> {
727    let call_id = item
728        .get("id")
729        .and_then(Value::as_str)
730        .filter(|s| !s.is_empty())
731        .or_else(|| item.get("call_id").and_then(Value::as_str))
732        .unwrap_or_default()
733        .to_string();
734    let mut contents = vec![Content::McpServerToolCall(McpServerToolCallContent {
735        call_id: call_id.clone(),
736        tool_name: item
737            .get("name")
738            .and_then(Value::as_str)
739            .unwrap_or_default()
740            .to_string(),
741        server_name: item
742            .get("server_label")
743            .and_then(Value::as_str)
744            .map(String::from),
745        arguments: item
746            .get("arguments")
747            .and_then(Value::as_str)
748            .map(|a| FunctionArguments::Raw(a.to_string())),
749        approval_request_id: item
750            .get("approval_request_id")
751            .and_then(Value::as_str)
752            .filter(|s| !s.is_empty())
753            .map(String::from),
754    })];
755    let output = item.get("output").filter(|o| !o.is_null()).cloned();
756    let error = item.get("error").filter(|e| !e.is_null()).cloned();
757    if output.is_some() || error.is_some() {
758        contents.push(Content::McpServerToolResult(McpServerToolResultContent {
759            call_id,
760            output,
761            error,
762        }));
763    }
764    contents
765}
766
767/// Map a URI/data content item to a Responses API input content part, or `None`
768/// when it has no wire mapping (mirrors upstream `_openai_content_parser`).
769/// Handles images (`input_image`), audio (`input_audio`), and `application/*`
770/// data (`input_file`).
771fn content_to_input_part(uri: &str, media_type: Option<&str>) -> Option<Value> {
772    let media_type = media_type?;
773    match top_level_media_type(media_type).as_str() {
774        // `detail` defaults to "auto"; the Rust content types carry no override.
775        "image" => Some(json!({
776            "type": "input_image",
777            "image_url": uri,
778            "detail": "auto",
779        })),
780        "audio" => {
781            let format = audio_format(media_type)?;
782            // `input_audio.data` is the raw base64 payload, not a data URI —
783            // same wire rule as the Chat Completions converter.
784            Some(json!({
785                "type": "input_audio",
786                "input_audio": {
787                    "data": crate::convert::strip_data_uri_prefix(uri),
788                    "format": format,
789                },
790            }))
791        }
792        // Inline bytes go in `file_data`; a remote file goes by `file_url`.
793        // Putting a URL in `file_data` makes the service read the URL
794        // itself as the file's contents.
795        // The service identifies an inline file by its name, so a known
796        // document type gets a matching extension rather than a bare `file`.
797        "application" if uri.starts_with("data:") => Some(json!({
798            "type": "input_file",
799            "file_data": uri,
800            "filename": application_filename(media_type),
801        })),
802        "application" => Some(json!({ "type": "input_file", "file_url": uri })),
803        // Text, Markdown and CSV attachments are files too. There was no arm
804        // for them, so they were dropped without a word. The service infers
805        // a file's type from its name, so inline text gets a matching
806        // extension rather than the bare default.
807        "text" if uri.starts_with("data:") => Some(json!({
808            "type": "input_file",
809            "file_data": uri,
810            "filename": text_filename(media_type),
811        })),
812        "text" => Some(json!({ "type": "input_file", "file_url": uri })),
813        _ => None,
814    }
815}
816
817/// A filename for an inline `application/*` file: the bare default with the
818/// extension its media type implies, or the bare default when it implies
819/// none (`application/octet-stream`).
820fn application_filename(media_type: &str) -> String {
821    let subtype = media_type
822        .split(';')
823        .next()
824        .and_then(|t| t.split_once('/'))
825        .map(|(_, sub)| sub.trim().to_ascii_lowercase());
826    let ext = match subtype.as_deref() {
827        Some("pdf") => "pdf",
828        Some("msword") => "doc",
829        Some("vnd.openxmlformats-officedocument.wordprocessingml.document") => "docx",
830        Some("vnd.ms-excel") => "xls",
831        Some("vnd.openxmlformats-officedocument.spreadsheetml.sheet") => "xlsx",
832        Some("vnd.ms-powerpoint") => "ppt",
833        Some("vnd.openxmlformats-officedocument.presentationml.presentation") => "pptx",
834        Some("json") => "json",
835        Some("rtf") => "rtf",
836        Some("xml") => "xml",
837        Some("zip") => "zip",
838        _ => return DEFAULT_FILENAME.to_string(),
839    };
840    format!("{DEFAULT_FILENAME}.{ext}")
841}
842
843/// A filename for an inline `text/*` file, whose extension tells the
844/// service what it holds.
845fn text_filename(media_type: &str) -> String {
846    let subtype = media_type
847        .split(';')
848        .next()
849        .and_then(|t| t.split_once('/'))
850        .map(|(_, sub)| sub.trim().to_ascii_lowercase());
851    let ext = match subtype.as_deref() {
852        Some("markdown") => "md",
853        Some("csv") => "csv",
854        Some("html") => "html",
855        Some("xml") => "xml",
856        _ => "txt",
857    };
858    format!("{DEFAULT_FILENAME}.{ext}")
859}
860
861fn flush_text(out: &mut Vec<Value>, buffered: &mut Vec<Value>, role: &str) {
862    if !buffered.is_empty() {
863        out.push(json!({ "type": "message", "role": role, "content": std::mem::take(buffered) }));
864    }
865}
866
867fn function_result_to_item(fr: &FunctionResultContent) -> Value {
868    json!({
869        "type": "function_call_output",
870        "call_id": fr.call_id,
871        "output": result_to_string(fr),
872    })
873}
874
875/// The flat Responses-API tool spec: `{"type":"function","name":...}`, unlike
876/// Chat Completions' `{"type":"function","function":{...}}` nesting.
877///
878/// `pub` so `agent-framework-azure`'s Responses client can reuse this
879/// mapping rather than reimplementing it.
880pub fn tool_to_responses_spec(tool: &ToolDefinition) -> Value {
881    use agent_framework_core::tools::ToolKind;
882    match &tool.kind {
883        ToolKind::HostedWebSearch => {
884            let mut spec = Map::new();
885            spec.insert("type".into(), json!("web_search"));
886            if let Some(loc) = tool.parameters.get("user_location") {
887                spec.insert("user_location".into(), user_location_to_responses(loc));
888            }
889            Value::Object(spec)
890        }
891        ToolKind::HostedCodeInterpreter => {
892            let mut spec = Map::new();
893            spec.insert("type".into(), json!("code_interpreter"));
894            // A caller-supplied `container` wins; otherwise default to `auto`
895            // and attach any `file_ids` (`_responses_client.py:264-278`).
896            if let Some(container) = tool.parameters.get("container") {
897                spec.insert("container".into(), container.clone());
898            } else {
899                let mut container = Map::new();
900                container.insert("type".into(), json!("auto"));
901                if let Some(file_ids) = tool.parameters.get("file_ids") {
902                    container.insert("file_ids".into(), file_ids.clone());
903                }
904                spec.insert("container".into(), Value::Object(container));
905            }
906            Value::Object(spec)
907        }
908        ToolKind::HostedFileSearch { max_results } => {
909            let mut spec = Map::new();
910            spec.insert("type".into(), json!("file_search"));
911            // The Responses API requires vector-store ids; the marker itself
912            // carries none, so honor ids supplied via the definition's
913            // parameters object when present.
914            if let Some(ids) = tool.parameters.get("vector_store_ids") {
915                spec.insert("vector_store_ids".into(), ids.clone());
916            }
917            // Prefer the marker's `max_results`; fall back to a parameters key.
918            let max = (*max_results)
919                .map(|n| json!(n))
920                .or_else(|| tool.parameters.get("max_results").cloned());
921            if let Some(n) = max {
922                spec.insert("max_num_results".into(), n);
923            }
924            Value::Object(spec)
925        }
926        ToolKind::HostedMcp { url, allowed_tools } => {
927            let mut spec = Map::new();
928            spec.insert("type".into(), json!("mcp"));
929            spec.insert("server_label".into(), json!(tool.name.replace(' ', "_")));
930            spec.insert("server_url".into(), json!(url));
931            if !tool.description.is_empty() {
932                spec.insert("server_description".into(), json!(tool.description));
933            }
934            if let Some(headers) = tool.parameters.get("headers") {
935                spec.insert("headers".into(), headers.clone());
936            }
937            if let Some(allowed) = allowed_tools {
938                spec.insert("allowed_tools".into(), json!(allowed));
939            }
940            spec.insert("require_approval".into(), mcp_require_approval(tool));
941            Value::Object(spec)
942        }
943        ToolKind::HostedImageGeneration => {
944            let mut spec = Map::new();
945            spec.insert("type".into(), json!("image_generation"));
946            // Pass through any caller-supplied generation options (size,
947            // quality, background, …) carried on the marker's parameters.
948            if let Value::Object(params) = &tool.parameters {
949                for (k, v) in params {
950                    if k != "type" && k != "properties" {
951                        spec.insert(k.clone(), v.clone());
952                    }
953                }
954            }
955            Value::Object(spec)
956        }
957        // Upstream `get_computer_tool()`.
958        ToolKind::HostedComputer => json!({ "type": "computer" }),
959        ToolKind::Function => json!({
960            "type": "function",
961            "name": tool.name,
962            "description": tool.description,
963            "parameters": tool.parameters,
964        }),
965    }
966}
967
968/// Build the Responses `web_search.user_location` object from a hosted-tool
969/// `user_location` parameter (`_responses_client.py:310-329`).
970fn user_location_to_responses(location: &Value) -> Value {
971    let mut loc = Map::new();
972    loc.insert("type".into(), json!("approximate"));
973    for key in ["city", "country", "region", "timezone"] {
974        if let Some(v) = location.get(key) {
975            loc.insert(key.into(), v.clone());
976        }
977    }
978    Value::Object(loc)
979}
980
981/// The contents of a `code_interpreter_call` output item: a
982/// [`Content::CodeInterpreterToolCall`] carrying the submitted code, and a
983/// [`Content::CodeInterpreterToolResult`] carrying its `logs` (as text) and
984/// `image` outputs (as URIs), as upstream's
985/// `from_code_interpreter_tool_call` / `_tool_result`.
986///
987/// These used to be flattened into ordinary [`Content::Text`] — the run's
988/// console output, or its source when there was none — so the tool's
989/// output read as part of the model's answer, in `text()` and in anything
990/// built from it. Used for both a full response and the streamed
991/// `response.output_item.done`, which is the only event that carries
992/// `outputs` during streaming (upstream #9744).
993fn code_interpreter_contents(item: &Value) -> Vec<Content> {
994    let call_id = item
995        .get("call_id")
996        .or_else(|| item.get("id"))
997        .and_then(Value::as_str)
998        .map(String::from);
999    let mut outputs = Vec::new();
1000    for output in item
1001        .get("outputs")
1002        .and_then(Value::as_array)
1003        .into_iter()
1004        .flatten()
1005    {
1006        match output.get("type").and_then(Value::as_str) {
1007            Some("logs") => {
1008                if let Some(logs) = output.get("logs").and_then(Value::as_str) {
1009                    outputs.push(Content::Text(TextContent::new(logs)));
1010                }
1011            }
1012            Some("image") => {
1013                if let Some(url) = output.get("url").and_then(Value::as_str) {
1014                    outputs.push(Content::Uri(UriContent {
1015                        uri: url.to_string(),
1016                        media_type: "image".to_string(),
1017                    }));
1018                }
1019            }
1020            _ => {}
1021        }
1022    }
1023    let mut contents = Vec::new();
1024    if let Some(code) = item
1025        .get("code")
1026        .and_then(Value::as_str)
1027        .filter(|c| !c.is_empty())
1028    {
1029        contents.push(Content::CodeInterpreterToolCall(
1030            CodeInterpreterToolCallContent {
1031                call_id: call_id.clone(),
1032                inputs: Some(vec![Content::Text(TextContent::new(code))]),
1033            },
1034        ));
1035    }
1036    contents.push(Content::CodeInterpreterToolResult(
1037        CodeInterpreterToolResultContent {
1038            call_id,
1039            outputs: Some(outputs),
1040        },
1041    ));
1042    contents
1043}
1044
1045/// Build the Responses MCP `require_approval` value. A `parameters.approval_mode`
1046/// override — either the string `"always_require"`/`"never_require"` or an
1047/// object `{"always": [...], "never": [...]}` — takes precedence over the
1048/// definition's [`ApprovalMode`]; mirrors `get_mcp_tool`
1049/// (`_responses_client.py:365-386`).
1050fn mcp_require_approval(tool: &ToolDefinition) -> Value {
1051    use agent_framework_core::tools::ApprovalMode;
1052    match tool.parameters.get("approval_mode") {
1053        Some(Value::String(s)) => {
1054            return json!(if s == "always_require" {
1055                "always"
1056            } else {
1057                "never"
1058            });
1059        }
1060        Some(Value::Object(modes)) => {
1061            let mut req = Map::new();
1062            if let Some(always) = modes.get("always") {
1063                req.insert("always".into(), json!({ "tool_names": always }));
1064            }
1065            if let Some(never) = modes.get("never") {
1066                req.insert("never".into(), json!({ "tool_names": never }));
1067            }
1068            if !req.is_empty() {
1069                return Value::Object(req);
1070            }
1071        }
1072        _ => {}
1073    }
1074    json!(match tool.approval_mode {
1075        ApprovalMode::AlwaysRequire => "always",
1076        ApprovalMode::NeverRequire => "never",
1077    })
1078}
1079
1080/// `pub` so `agent-framework-azure`'s Responses client can reuse this
1081/// mapping rather than reimplementing it.
1082pub fn tool_choice_to_responses(mode: &ToolMode) -> Value {
1083    match mode {
1084        ToolMode::Auto => json!("auto"),
1085        ToolMode::None => json!("none"),
1086        ToolMode::Required(Some(name)) => json!({ "type": "function", "name": name }),
1087        ToolMode::Required(None) => json!("required"),
1088    }
1089}
1090
1091/// Convert a `ChatOptions::response_format` into a Responses API
1092/// `text.format` object. Unlike Chat Completions (which nests the schema
1093/// under `json_schema`), the Responses API uses a flat object.
1094///
1095/// `pub` so `agent-framework-azure`'s Responses client can reuse this
1096/// mapping rather than reimplementing it.
1097pub fn response_format_to_text(format: &ResponseFormat) -> Value {
1098    match format {
1099        ResponseFormat::Text => json!({ "type": "text" }),
1100        ResponseFormat::JsonObject => json!({ "type": "json_object" }),
1101        ResponseFormat::JsonSchema {
1102            name,
1103            description,
1104            schema,
1105            strict,
1106        } => {
1107            let mut obj = Map::new();
1108            obj.insert("type".into(), json!("json_schema"));
1109            obj.insert("name".into(), json!(name));
1110            if let Some(d) = description {
1111                obj.insert("description".into(), json!(d));
1112            }
1113            obj.insert("schema".into(), schema.clone());
1114            if let Some(st) = strict {
1115                obj.insert("strict".into(), json!(st));
1116            }
1117            Value::Object(obj)
1118        }
1119    }
1120}
1121
1122// endregion
1123
1124// region: response conversion
1125
1126/// Parse a full (non-streaming) Responses API response.
1127///
1128/// Map a Responses body whose `status` is `"failed"` to a classified error,
1129/// or `None` for a non-failed response. A failed run reports `status:
1130/// "failed"` with a 2xx HTTP status, so the error is pulled from the body:
1131/// `error.code == "content_filter"` becomes [`Error::ServiceContentFilter`]
1132/// (matching the HTTP-level classification in `classify_service_error`),
1133/// anything else a generic service error.
1134///
1135/// `pub` so `agent-framework-azure`'s Responses client can share the exact
1136/// classification.
1137pub fn response_failure_error(value: &Value) -> Option<Error> {
1138    if value.get("status").and_then(Value::as_str) != Some("failed") {
1139        return None;
1140    }
1141    let error = value.get("error");
1142    let msg = error
1143        .and_then(|e| e.get("message"))
1144        .and_then(Value::as_str)
1145        .unwrap_or("response failed")
1146        .to_string();
1147    let code = error.and_then(|e| e.get("code")).and_then(Value::as_str);
1148    Some(match code {
1149        Some("content_filter") => Error::service_content_filter(msg),
1150        _ => Error::service(msg),
1151    })
1152}
1153
1154/// `pub` so `agent-framework-azure`'s Responses client (whose wire format is
1155/// otherwise identical) can reuse this parser — including `parse_output_item`,
1156/// `parse_annotations`, and usage/finish-reason handling — rather than
1157/// reimplementing it.
1158pub fn parse_response(value: &Value, store: Option<bool>) -> ChatResponse {
1159    let mut response = ChatResponse {
1160        response_id: value.get("id").and_then(Value::as_str).map(String::from),
1161        model: value.get("model").and_then(Value::as_str).map(String::from),
1162        ..Default::default()
1163    };
1164
1165    // One assistant message per `message` output item, carrying that item's
1166    // id (upstream #9768). Other items (reasoning, tool calls) join the
1167    // message being built; a message item with a new id starts the next one,
1168    // and the first message item names a message that has no id yet.
1169    let mut messages: Vec<Message> = Vec::new();
1170    if let Some(items) = value.get("output").and_then(Value::as_array) {
1171        for item in items {
1172            let item_id = (item.get("type").and_then(Value::as_str) == Some("message"))
1173                .then(|| item.get("id").and_then(Value::as_str))
1174                .flatten()
1175                .filter(|id| !id.is_empty());
1176            let starts_new = match (messages.last(), item_id) {
1177                (None, _) => true,
1178                (Some(last), Some(id)) => last.message_id.as_deref().is_some_and(|m| m != id),
1179                _ => false,
1180            };
1181            if starts_new {
1182                messages.push(Message::with_contents(Role::assistant(), Vec::new()));
1183            }
1184            let current = messages.last_mut().expect("pushed above");
1185            if let Some(id) = item_id {
1186                current.message_id = Some(id.to_string());
1187            }
1188            parse_output_item(item, &mut current.contents);
1189        }
1190    }
1191    if messages.is_empty() {
1192        messages.push(Message::with_contents(Role::assistant(), Vec::new()));
1193    }
1194    #[cfg(feature = "experimental-computer-use")]
1195    computer::mark_completed_calls(&mut messages);
1196    response.messages = messages;
1197
1198    response.finish_reason = finish_reason_from_response(value);
1199
1200    if let Some(usage) = value.get("usage") {
1201        response.usage_details = Some(parse_responses_usage(usage));
1202    }
1203    if store != Some(false) {
1204        response.conversation_id = response.response_id.clone();
1205    }
1206    // A background response still queued or running hands back a token to
1207    // poll it with (upstream `_parse_response_from_openai`).
1208    if is_pending_status(value.get("status").and_then(Value::as_str)) {
1209        if let Some(id) = &response.response_id {
1210            response.continuation_token = Some(OpenAIContinuationToken::new(id).to_token());
1211        }
1212    }
1213    response
1214}
1215
1216/// Build the consent content for an `oauth_consent_request` output item,
1217/// or `None` when its link cannot be trusted.
1218///
1219/// An Azure AI Foundry project's Responses endpoint emits this item when a
1220/// hosted tool needs the user to complete an OAuth consent flow; OpenAI's
1221/// own Responses API does not. It is handled in this shared parser because
1222/// `agent-framework-azure` and `agent-framework-foundry` both reuse it
1223/// verbatim rather than re-implementing the Responses wire — a Foundry-only
1224/// item type that costs an unreachable match arm on the OpenAI path.
1225///
1226/// The link is checked before it is handed on. It is a URL the framework is
1227/// asking a human to open and authenticate at, arriving from the service as
1228/// free-form text, so a `http://` or `javascript:` one is dropped with a
1229/// warning rather than surfaced as something to click. Upstream validates
1230/// the same two things: an HTTPS scheme and a non-empty host.
1231fn oauth_consent_content(item: &Value) -> Option<Content> {
1232    let item_id = item.get("id").and_then(Value::as_str);
1233    let consent_link = item
1234        .get("consent_link")
1235        .and_then(Value::as_str)
1236        .unwrap_or_default();
1237    if !is_https_url(consent_link) {
1238        tracing::warn!(
1239            item_id = item_id.unwrap_or("<unknown>"),
1240            "dropping oauth_consent_request without an https consent_link"
1241        );
1242        return None;
1243    }
1244    let mut content = OauthConsentRequestContent::new(consent_link);
1245    content.id = item_id.filter(|id| !id.is_empty()).map(str::to_string);
1246    Some(Content::OauthConsentRequest(content))
1247}
1248
1249/// Whether `link` is an `https` URL with a real host.
1250///
1251/// Two checks, because each alone has a gap. The literal one — an
1252/// `https://` prefix followed by a non-empty authority — accepts
1253/// `https://user@/consent` and `https://:443/consent`, whose authority names
1254/// no host. The WHATWG parser `reqwest` re-exports (so no new dependency)
1255/// rejects those, but repairs `https:///consent` into `https://consent/`, as
1256/// a browser would. A consent link only usable after such a repair is not
1257/// one to hand a human, so it must pass both.
1258fn is_https_url(link: &str) -> bool {
1259    let literal = link
1260        .get(..8)
1261        .filter(|scheme| scheme.eq_ignore_ascii_case("https://"))
1262        .map(|_| &link[8..])
1263        .is_some_and(|authority| {
1264            let end = authority.find(['/', '?', '#']).unwrap_or(authority.len());
1265            !authority[..end].is_empty()
1266        });
1267    literal
1268        && reqwest::Url::parse(link).is_ok_and(|url| {
1269            url.scheme() == "https" && url.host_str().is_some_and(|host| !host.is_empty())
1270        })
1271}
1272
1273fn parse_output_item(item: &Value, contents: &mut Vec<Content>) {
1274    match item.get("type").and_then(Value::as_str) {
1275        Some("message") => {
1276            if let Some(parts) = item.get("content").and_then(Value::as_array) {
1277                for part in parts {
1278                    match part.get("type").and_then(Value::as_str) {
1279                        Some("output_text") => {
1280                            if let Some(text) = part.get("text").and_then(Value::as_str) {
1281                                let mut tc = TextContent::new(text);
1282                                tc.annotations = parse_annotations(part);
1283                                contents.push(Content::Text(tc));
1284                            }
1285                        }
1286                        Some("refusal") => {
1287                            if let Some(text) = part.get("refusal").and_then(Value::as_str) {
1288                                // Marked, so `Message::text` withholds it
1289                                // rather than presenting it as the answer.
1290                                contents.push(Content::Text(TextContent::refusal(text)));
1291                            }
1292                        }
1293                        _ => {}
1294                    }
1295                }
1296            }
1297        }
1298        // Foundry only — see `oauth_consent_content`. Upstream surfaced it
1299        // on the stream first and from the completed response later
1300        // (#8976); a non-streaming run that needed consent otherwise came
1301        // back as an empty answer with no way to learn why.
1302        Some("oauth_consent_request") => {
1303            contents.extend(oauth_consent_content(item));
1304        }
1305        Some("function_call") => {
1306            let call_id = item
1307                .get("call_id")
1308                .and_then(Value::as_str)
1309                .unwrap_or_default()
1310                .to_string();
1311            let name = item
1312                .get("name")
1313                .and_then(Value::as_str)
1314                .unwrap_or_default()
1315                .to_string();
1316            let args = item
1317                .get("arguments")
1318                .and_then(Value::as_str)
1319                .unwrap_or("{}")
1320                .to_string();
1321            contents.push(Content::FunctionCall(FunctionCallContent::new(
1322                call_id,
1323                name,
1324                Some(FunctionArguments::Raw(args)),
1325            )));
1326        }
1327        Some("reasoning") => {
1328            let summaries: Vec<String> = item
1329                .get("summary")
1330                .and_then(Value::as_array)
1331                .map(|arr| {
1332                    arr.iter()
1333                        .filter_map(|s| s.get("text").and_then(Value::as_str))
1334                        .map(str::to_string)
1335                        .collect()
1336                })
1337                .unwrap_or_default();
1338            // Preserve the raw reasoning item so a store:false tool-loop replay
1339            // can re-send it verbatim — reasoning models require the original
1340            // item (id + encrypted_content), not just the summary, on the
1341            // follow-up turn. `messages_to_input` re-emits it from
1342            // `raw_representation`; it is attached to exactly one content so a
1343            // multi-summary item yields exactly one reasoning input item.
1344            let raw = Some(item.clone());
1345            if summaries.is_empty() {
1346                // No summary (e.g. encrypted reasoning) — still carry the item.
1347                contents.push(Content::TextReasoning(TextReasoningContent {
1348                    text: String::new(),
1349                    annotations: None,
1350                    raw_representation: raw,
1351                    protected_data: None,
1352                }));
1353            } else {
1354                let n = summaries.len();
1355                for (i, text) in summaries.into_iter().enumerate() {
1356                    contents.push(Content::TextReasoning(TextReasoningContent {
1357                        text,
1358                        annotations: None,
1359                        raw_representation: (i == n - 1).then(|| raw.clone()).flatten(),
1360                        protected_data: None,
1361                    }));
1362                }
1363            }
1364        }
1365        // A code-interpreter run is a hosted tool call and its result, not
1366        // assistant text (see `code_interpreter_contents`).
1367        Some("code_interpreter_call") => contents.extend(code_interpreter_contents(item)),
1368        // A generated image is returned as base64; default to image/png unless
1369        // the result is a data URI that states its own type
1370        // (`_create_response_content:788-811`).
1371        Some("image_generation_call") => {
1372            if let Some(result) = item.get("result").and_then(Value::as_str) {
1373                let (uri, media_type) = if result.starts_with("data:") {
1374                    let media_type = if result.contains(';') {
1375                        result
1376                            .strip_prefix("data:")
1377                            .and_then(|r| r.split(';').next())
1378                            .filter(|s| !s.is_empty())
1379                            .map(String::from)
1380                    } else {
1381                        None
1382                    };
1383                    (result.to_string(), media_type)
1384                } else {
1385                    (
1386                        format!("data:image/png;base64,{result}"),
1387                        Some("image/png".to_string()),
1388                    )
1389                };
1390                contents.push(Content::Data(DataContent { uri, media_type }));
1391            }
1392        }
1393        // An MCP approval request round-trips its `id` as the call id so a
1394        // later `FunctionApprovalResponse` refers back to it
1395        // (`_create_response_content:775-787`).
1396        Some("mcp_call") => contents.extend(mcp_call_item_contents(item)),
1397        #[cfg(feature = "experimental-computer-use")]
1398        Some("computer_call") => contents.extend(computer::parse_call(item)),
1399        #[cfg(feature = "experimental-computer-use")]
1400        Some("computer_call_output") => contents.extend(computer::parse_result(item)),
1401        Some("mcp_approval_request") => {
1402            let id = item
1403                .get("id")
1404                .and_then(Value::as_str)
1405                .unwrap_or_default()
1406                .to_string();
1407            let name = item
1408                .get("name")
1409                .and_then(Value::as_str)
1410                .unwrap_or_default()
1411                .to_string();
1412            let args = item
1413                .get("arguments")
1414                .and_then(Value::as_str)
1415                .unwrap_or("{}")
1416                .to_string();
1417            contents.push(Content::FunctionApprovalRequest(
1418                FunctionApprovalRequestContent {
1419                    id: id.clone(),
1420                    function_call: FunctionCallContent::new(
1421                        id,
1422                        name,
1423                        Some(FunctionArguments::Raw(args)),
1424                    ),
1425                },
1426            ));
1427        }
1428        _ => {}
1429    }
1430}
1431
1432/// Parse the `annotations` on an `output_text` part into [`Annotation`]s
1433/// (`_create_response_content:667-724`), keeping upstream's `index` and
1434/// `container_id` extras in `additional_properties`.
1435fn parse_annotations(part: &Value) -> Option<Vec<Annotation>> {
1436    let arr = part.get("annotations").and_then(Value::as_array)?;
1437    let mut out = Vec::new();
1438    for ann in arr {
1439        let str_field = |k: &str| ann.get(k).and_then(Value::as_str).map(String::from);
1440        let extras = |keys: &[&str]| {
1441            keys.iter()
1442                .filter_map(|k| ann.get(*k).map(|v| (k.to_string(), v.clone())))
1443                .collect::<serde_json::Map<String, Value>>()
1444        };
1445        let regions = || {
1446            Some(vec![TextSpanRegion {
1447                start_index: ann.get("start_index").and_then(Value::as_i64),
1448                end_index: ann.get("end_index").and_then(Value::as_i64),
1449            }])
1450        };
1451        match ann.get("type").and_then(Value::as_str) {
1452            Some("file_path") => out.push(Annotation {
1453                file_id: str_field("file_id"),
1454                additional_properties: extras(&["index"]),
1455                ..Default::default()
1456            }),
1457            Some("file_citation") => out.push(Annotation {
1458                url: str_field("filename"),
1459                file_id: str_field("file_id"),
1460                additional_properties: extras(&["index"]),
1461                ..Default::default()
1462            }),
1463            Some("url_citation") => out.push(Annotation {
1464                title: str_field("title"),
1465                url: str_field("url"),
1466                annotated_regions: regions(),
1467                ..Default::default()
1468            }),
1469            Some("container_file_citation") => out.push(Annotation {
1470                file_id: str_field("file_id"),
1471                url: str_field("filename"),
1472                annotated_regions: regions(),
1473                additional_properties: extras(&["container_id"]),
1474                ..Default::default()
1475            }),
1476            _ => {}
1477        }
1478    }
1479    if out.is_empty() {
1480        None
1481    } else {
1482        Some(out)
1483    }
1484}
1485
1486fn finish_reason_from_response(value: &Value) -> Option<FinishReason> {
1487    let has_function_call = value
1488        .get("output")
1489        .and_then(Value::as_array)
1490        .map(|items| {
1491            items
1492                .iter()
1493                .any(|i| i.get("type").and_then(Value::as_str) == Some("function_call"))
1494        })
1495        .unwrap_or(false);
1496    if has_function_call {
1497        return Some(FinishReason::tool_calls());
1498    }
1499    let status = value.get("status").and_then(Value::as_str)?;
1500    // A background response that has not finished has no finish reason yet.
1501    if is_pending_status(Some(status)) {
1502        return None;
1503    }
1504    Some(match status {
1505        "completed" => FinishReason::stop(),
1506        "incomplete" => match value
1507            .get("incomplete_details")
1508            .and_then(|d| d.get("reason"))
1509            .and_then(Value::as_str)
1510        {
1511            Some("max_output_tokens") => FinishReason::new(FinishReason::LENGTH),
1512            Some("content_filter") => FinishReason::new(FinishReason::CONTENT_FILTER),
1513            Some(other) => FinishReason::new(other),
1514            None => FinishReason::new("incomplete"),
1515        },
1516        other => FinishReason::new(other),
1517    })
1518}
1519
1520fn parse_responses_usage(usage: &Value) -> UsageDetails {
1521    let mut details = UsageDetails {
1522        input_token_count: usage.get("input_tokens").and_then(Value::as_u64),
1523        output_token_count: usage.get("output_tokens").and_then(Value::as_u64),
1524        total_token_count: usage.get("total_tokens").and_then(Value::as_u64),
1525        ..Default::default()
1526    };
1527    if let Some(cached) = usage
1528        .get("input_tokens_details")
1529        .and_then(|d| d.get("cached_tokens"))
1530        .and_then(Value::as_u64)
1531    {
1532        details
1533            .additional_counts
1534            .insert("openai.cached_input_tokens".into(), cached);
1535        // Mirror upstream: also surface as the typed, cross-language field.
1536        details.cache_read_input_token_count = Some(cached);
1537    }
1538    // Cache *writes* are reported separately from cache reads. Absent when the
1539    // provider does not report them (older API versions).
1540    if let Some(cache_write) = usage
1541        .get("input_tokens_details")
1542        .and_then(|d| d.get("cache_write_tokens"))
1543        .and_then(Value::as_u64)
1544    {
1545        details
1546            .additional_counts
1547            .insert("openai.cache_write_tokens".into(), cache_write);
1548        details.cache_creation_input_token_count = Some(cache_write);
1549    }
1550    if let Some(reasoning) = usage
1551        .get("output_tokens_details")
1552        .and_then(|d| d.get("reasoning_tokens"))
1553        .and_then(Value::as_u64)
1554    {
1555        details
1556            .additional_counts
1557            .insert("openai.reasoning_tokens".into(), reasoning);
1558        details.reasoning_output_token_count = Some(reasoning);
1559    }
1560    details
1561}
1562
1563// endregion
1564
1565// region: streaming
1566
1567/// Turn a Responses API SSE HTTP response into a stream of updates.
1568///
1569/// `pub` so `agent-framework-azure`'s Responses client can reuse this exact
1570/// SSE event parser (Azure OpenAI's Responses API streams the same event
1571/// shapes) rather than reimplementing it.
1572pub fn parse_responses_sse_stream(
1573    resp: reqwest::Response,
1574    store: Option<bool>,
1575) -> impl futures::Stream<Item = Result<ChatResponseUpdate>> + Send {
1576    sse_stream(resp, store, None, HashMap::new())
1577}
1578
1579/// [`parse_responses_sse_stream`] for a background response: every update
1580/// carries an [`OpenAIContinuationToken`] while the response is still
1581/// running. `resume` is the token a resumed stream continues from (`None`
1582/// for a fresh `background: true` submission). `pub` so
1583/// `agent-framework-azure`'s Responses client can reuse it.
1584pub fn parse_background_responses_sse_stream(
1585    resp: reqwest::Response,
1586    store: Option<bool>,
1587    resume: Option<OpenAIContinuationToken>,
1588) -> impl futures::Stream<Item = Result<ChatResponseUpdate>> + Send {
1589    match resume {
1590        Some(token) => {
1591            let state = BackgroundStream {
1592                response_id: Some(token.response_id),
1593                sequence_number: token.sequence_number,
1594            };
1595            sse_stream(
1596                resp,
1597                store,
1598                Some(state),
1599                token.function_calls.into_iter().collect(),
1600            )
1601        }
1602        None => sse_stream(
1603            resp,
1604            store,
1605            Some(BackgroundStream::default()),
1606            HashMap::new(),
1607        ),
1608    }
1609}
1610
1611/// Where a background response's stream stands, so every update can carry
1612/// a [`OpenAIContinuationToken`] to resume it from.
1613#[derive(Debug, Clone, Default)]
1614struct BackgroundStream {
1615    /// The response id, from the token being resumed or `response.created`.
1616    response_id: Option<String>,
1617    /// The `sequence_number` of the latest event seen.
1618    sequence_number: Option<u64>,
1619}
1620
1621impl BackgroundStream {
1622    /// Note the position of `event` (its response id and sequence number).
1623    fn observe(&mut self, event: &Value) {
1624        if let Some(seq) = event.get("sequence_number").and_then(Value::as_u64) {
1625            self.sequence_number = Some(seq);
1626        }
1627        if let Some(id) = event
1628            .get("response")
1629            .and_then(|r| r.get("id"))
1630            .and_then(Value::as_str)
1631            .filter(|id| !id.is_empty())
1632        {
1633            self.response_id = Some(id.to_string());
1634        }
1635    }
1636
1637    /// Stamp `update` with where the operation stands after `event`: a
1638    /// terminal event ends it (no token), anything else leaves it running,
1639    /// resumable from this event on. Mirrors upstream's streaming
1640    /// `operation_state` / `continuation_token` handling.
1641    fn stamp(
1642        &self,
1643        event: &Value,
1644        update: &mut ChatResponseUpdate,
1645        store: Option<bool>,
1646        call_ids: &HashMap<i64, String>,
1647    ) {
1648        let event_type = event.get("type").and_then(Value::as_str).unwrap_or("");
1649        let status = event
1650            .get("response")
1651            .and_then(|r| r.get("status"))
1652            .and_then(Value::as_str);
1653        let terminal = matches!(
1654            event_type,
1655            "response.completed"
1656                | "response.incomplete"
1657                | "response.failed"
1658                | "response.cancelled"
1659                | "error"
1660        ) || matches!(
1661            status,
1662            Some("completed" | "incomplete" | "failed" | "cancelled")
1663        );
1664        if terminal {
1665            update.operation_state = Some(OperationState::Terminal);
1666            update.continuation_token = None;
1667            return;
1668        }
1669        let Some(response_id) = &self.response_id else {
1670            return;
1671        };
1672        update.operation_state = Some(OperationState::InProgress);
1673        update.continuation_token = Some(
1674            OpenAIContinuationToken {
1675                response_id: response_id.clone(),
1676                sequence_number: self.sequence_number,
1677                function_calls: call_ids
1678                    .iter()
1679                    .map(|(index, id)| (*index, id.clone()))
1680                    .collect(),
1681            }
1682            .to_token(),
1683        );
1684        if store != Some(false) && update.conversation_id.is_none() {
1685            update.conversation_id = Some(response_id.clone());
1686        }
1687    }
1688}
1689
1690/// [`parse_responses_sse_stream`], stamping continuation tokens on the
1691/// updates of a background response (`background` is `Some`). `call_ids`
1692/// are the function calls a resumed stream's earlier events announced.
1693fn sse_stream(
1694    resp: reqwest::Response,
1695    store: Option<bool>,
1696    background: Option<BackgroundStream>,
1697    call_ids: HashMap<i64, String>,
1698) -> impl futures::Stream<Item = Result<ChatResponseUpdate>> + Send {
1699    let byte_stream: ByteStream = Box::pin(resp.bytes_stream());
1700    futures::stream::unfold(
1701        ResponsesSseState {
1702            byte_stream,
1703            buffer: String::new(),
1704            utf8: Utf8StreamDecoder::new(),
1705            queued: VecDeque::new(),
1706            call_ids,
1707            done: false,
1708            store,
1709            background,
1710        },
1711        |mut state| async move {
1712            loop {
1713                if let Some(update) = state.queued.pop_front() {
1714                    return Some((Ok(update), state));
1715                }
1716                if state.done {
1717                    return None;
1718                }
1719                match state.byte_stream.next().await {
1720                    Some(Ok(bytes)) => {
1721                        let decoded = state.utf8.push(&bytes);
1722                        state.buffer.push_str(&decoded);
1723                        while let Some(pos) = state.buffer.find('\n') {
1724                            let line = state.buffer[..pos].trim().to_string();
1725                            state.buffer.drain(..=pos);
1726                            let Some(data) = line.strip_prefix("data:") else {
1727                                continue;
1728                            };
1729                            let data = data.trim();
1730                            if data.is_empty() {
1731                                continue;
1732                            }
1733                            let Ok(value) = serde_json::from_str::<Value>(data) else {
1734                                continue;
1735                            };
1736                            if let Some(bg) = state.background.as_mut() {
1737                                bg.observe(&value);
1738                            }
1739                            match parse_responses_event(&value, &mut state.call_ids, state.store) {
1740                                EventOutcome::Update(mut update) => {
1741                                    if let Some(bg) = &state.background {
1742                                        bg.stamp(&value, &mut update, state.store, &state.call_ids);
1743                                    }
1744                                    state.queued.push_back(update)
1745                                }
1746                                EventOutcome::Error(e) => {
1747                                    state.done = true;
1748                                    return Some((Err(e), state));
1749                                }
1750                                EventOutcome::None => {}
1751                            }
1752                        }
1753                    }
1754                    Some(Err(e)) => {
1755                        state.done = true;
1756                        return Some((Err(Error::service(format!("stream error: {e}"))), state));
1757                    }
1758                    None => return None,
1759                }
1760            }
1761        },
1762    )
1763}
1764
1765struct ResponsesSseState {
1766    byte_stream: ByteStream,
1767    buffer: String,
1768    utf8: Utf8StreamDecoder,
1769    queued: VecDeque<ChatResponseUpdate>,
1770    /// `output_index` -> `call_id`, resolved when the call is first announced
1771    /// via `response.output_item.added` and used to route later
1772    /// `response.function_call_arguments.delta` fragments.
1773    call_ids: HashMap<i64, String>,
1774    done: bool,
1775    store: Option<bool>,
1776    /// Set for a background response, whose updates carry continuation
1777    /// tokens.
1778    background: Option<BackgroundStream>,
1779}
1780
1781// A transient control-flow value: produced per SSE event and immediately
1782// destructured in the stream loop, never stored in bulk. Boxing the `Update`
1783// variant to equalize sizes would add a heap allocation on every streamed
1784// token, so the size skew is accepted here.
1785#[allow(clippy::large_enum_variant)]
1786enum EventOutcome {
1787    Update(ChatResponseUpdate),
1788    Error(Error),
1789    None,
1790}
1791
1792/// Wrap streamed reasoning text as a [`TextReasoningContent`] update, or
1793/// [`EventOutcome::None`] when empty.
1794fn reasoning_update(text: &str) -> EventOutcome {
1795    if text.is_empty() {
1796        return EventOutcome::None;
1797    }
1798    EventOutcome::Update(ChatResponseUpdate {
1799        contents: vec![Content::TextReasoning(TextReasoningContent {
1800            text: text.to_string(),
1801            annotations: None,
1802            ..Default::default()
1803        })],
1804        role: Some(Role::assistant()),
1805        ..Default::default()
1806    })
1807}
1808
1809/// The output item a streamed text or refusal delta belongs to, so the
1810/// aggregated response keeps one message per `message` item (upstream #9768).
1811fn stream_item_id(value: &Value) -> Option<String> {
1812    value
1813        .get("item_id")
1814        .and_then(Value::as_str)
1815        .filter(|id| !id.is_empty())
1816        .map(str::to_string)
1817}
1818
1819/// Parse one Responses API SSE event (already-decoded JSON `data:` payload).
1820fn parse_responses_event(
1821    value: &Value,
1822    call_ids: &mut HashMap<i64, String>,
1823    store: Option<bool>,
1824) -> EventOutcome {
1825    let event_type = value.get("type").and_then(Value::as_str).unwrap_or("");
1826    match event_type {
1827        "response.created" => {
1828            let resp = value.get("response");
1829            let response_id = resp
1830                .and_then(|r| r.get("id"))
1831                .and_then(Value::as_str)
1832                .map(String::from);
1833            let model = resp
1834                .and_then(|r| r.get("model"))
1835                .and_then(Value::as_str)
1836                .map(String::from);
1837            if response_id.is_none() && model.is_none() {
1838                return EventOutcome::None;
1839            }
1840            EventOutcome::Update(ChatResponseUpdate {
1841                role: Some(Role::assistant()),
1842                response_id,
1843                model,
1844                ..Default::default()
1845            })
1846        }
1847        "response.output_text.delta" => {
1848            let text = value.get("delta").and_then(Value::as_str).unwrap_or("");
1849            if text.is_empty() {
1850                return EventOutcome::None;
1851            }
1852            EventOutcome::Update(ChatResponseUpdate {
1853                contents: vec![Content::Text(TextContent::new(text))],
1854                role: Some(Role::assistant()),
1855                message_id: stream_item_id(value),
1856                ..Default::default()
1857            })
1858        }
1859        // A refusal streams on its own channel. Only the incremental `.delta`
1860        // is consumed: the terminal `response.refusal.done` repeats the whole
1861        // refusal, which aggregation would append to the fragments already
1862        // collected, doubling it — the same reason the text channel above
1863        // does not consume its `.done`. Dropping these events entirely, as
1864        // this parser used to, let a streamed decline reach the caller as an
1865        // empty response.
1866        "response.refusal.delta" => {
1867            let text = value.get("delta").and_then(Value::as_str).unwrap_or("");
1868            if text.is_empty() {
1869                return EventOutcome::None;
1870            }
1871            EventOutcome::Update(ChatResponseUpdate {
1872                contents: vec![Content::Text(TextContent::refusal(text))],
1873                role: Some(Role::assistant()),
1874                message_id: stream_item_id(value),
1875                ..Default::default()
1876            })
1877        }
1878        // Reasoning (chain-of-thought / summary) streams as its own text
1879        // channel. Both the incremental `.delta` and the terminal `.done`
1880        // (full text) map to `TextReasoningContent`, mirroring upstream
1881        // `_create_streaming_response_content` (`_responses_client.py:917-928`).
1882        "response.reasoning_text.delta" | "response.reasoning_summary_text.delta" => {
1883            reasoning_update(value.get("delta").and_then(Value::as_str).unwrap_or(""))
1884        }
1885        // `.done` carries the *full* completed text, not another increment —
1886        // the deltas above already streamed it, so emitting it again would
1887        // duplicate the reasoning in the aggregated response (adjacent
1888        // reasoning contents coalesce by appending). Treated as terminal
1889        // metadata, like `response.output_text.done`.
1890        "response.reasoning_text.done" | "response.reasoning_summary_text.done" => {
1891            EventOutcome::None
1892        }
1893        "response.output_item.added" => {
1894            let item = value.get("item");
1895            let item_type = item.and_then(|i| i.get("type")).and_then(Value::as_str);
1896            // A consent request is complete the moment it is added — it
1897            // has no deltas to wait for, and the run is blocked on the
1898            // user until it is answered, so holding it back to `done`
1899            // would be holding back the one thing the caller needs.
1900            if item_type == Some("oauth_consent_request") {
1901                return match item.and_then(oauth_consent_content) {
1902                    Some(content) => EventOutcome::Update(ChatResponseUpdate {
1903                        contents: vec![content],
1904                        role: Some(Role::assistant()),
1905                        ..Default::default()
1906                    }),
1907                    None => EventOutcome::None,
1908                };
1909            }
1910            // A hosted MCP call is emitted whole from `done` (below): on
1911            // `added` its arguments are still empty and only stream in
1912            // through `response.mcp_call_arguments.*`, so a call recorded
1913            // here would replay with `{}` arguments.
1914            if item_type != Some("function_call") {
1915                return EventOutcome::None;
1916            }
1917            let output_index = value
1918                .get("output_index")
1919                .and_then(Value::as_i64)
1920                .unwrap_or(0);
1921            let call_id = item
1922                .and_then(|i| i.get("call_id"))
1923                .and_then(Value::as_str)
1924                .unwrap_or_default()
1925                .to_string();
1926            let name = item
1927                .and_then(|i| i.get("name"))
1928                .and_then(Value::as_str)
1929                .unwrap_or_default()
1930                .to_string();
1931            call_ids.insert(output_index, call_id.clone());
1932            EventOutcome::Update(ChatResponseUpdate {
1933                contents: vec![Content::FunctionCall(FunctionCallContent::new(
1934                    call_id, name, None,
1935                ))],
1936                role: Some(Role::assistant()),
1937                ..Default::default()
1938            })
1939        }
1940        // Foundry also emits the consent request as a top-level event
1941        // rather than an output item, carrying the link on the event
1942        // itself. Same content either way.
1943        "response.oauth_consent_requested" => match oauth_consent_content(value) {
1944            Some(content) => EventOutcome::Update(ChatResponseUpdate {
1945                contents: vec![content],
1946                role: Some(Role::assistant()),
1947                ..Default::default()
1948            }),
1949            None => EventOutcome::None,
1950        },
1951        "response.function_call_arguments.delta" => {
1952            let output_index = value
1953                .get("output_index")
1954                .and_then(Value::as_i64)
1955                .unwrap_or(0);
1956            let delta = value.get("delta").and_then(Value::as_str).unwrap_or("");
1957            match call_ids.get(&output_index) {
1958                Some(call_id) => EventOutcome::Update(ChatResponseUpdate {
1959                    contents: vec![Content::FunctionCall(FunctionCallContent::new(
1960                        call_id.clone(),
1961                        "",
1962                        Some(FunctionArguments::Raw(delta.to_string())),
1963                    ))],
1964                    role: Some(Role::assistant()),
1965                    ..Default::default()
1966                }),
1967                None => EventOutcome::None,
1968            }
1969        }
1970        // `response.incomplete` is the terminal event for a turn cut off by
1971        // the content filter or the token budget — the same payload as
1972        // `response.completed`, under a name that says it did not finish.
1973        // Handled here rather than ignored, or a truncated or filtered
1974        // stream would lose its finish reason, usage and response id
1975        // entirely, which is exactly the information the distinct event
1976        // name exists to deliver.
1977        // `response.cancelled` (a background response cancelled mid-stream)
1978        // ends the stream the same way: a final update with the response's
1979        // metadata, which a background stream stamps as terminal so the
1980        // aggregated continuation token is cleared.
1981        "response.completed" | "response.incomplete" | "response.cancelled" => {
1982            let resp = value.get("response");
1983            let response_id = resp
1984                .and_then(|r| r.get("id"))
1985                .and_then(Value::as_str)
1986                .map(String::from);
1987            let model = resp
1988                .and_then(|r| r.get("model"))
1989                .and_then(Value::as_str)
1990                .map(String::from);
1991            let mut contents = Vec::new();
1992            if let Some(usage) = resp.and_then(|r| r.get("usage")) {
1993                contents.push(Content::Usage(UsageContent {
1994                    details: parse_responses_usage(usage),
1995                }));
1996            }
1997            let finish_reason = resp.and_then(finish_reason_from_response);
1998            let conversation_id = if store != Some(false) {
1999                response_id.clone()
2000            } else {
2001                None
2002            };
2003            EventOutcome::Update(ChatResponseUpdate {
2004                contents,
2005                role: Some(Role::assistant()),
2006                response_id,
2007                model,
2008                conversation_id,
2009                finish_reason,
2010                ..Default::default()
2011            })
2012        }
2013        "response.failed" | "error" => {
2014            let resp = value.get("response");
2015            let err_obj = resp
2016                .and_then(|r| r.get("error"))
2017                .filter(|e| !e.is_null())
2018                .or_else(|| value.get("error").filter(|e| !e.is_null()))
2019                // A flat `error` event carries `code` / `message` / `param`
2020                // on the event itself rather than nested under an `error`
2021                // key (upstream's `ResponseErrorEvent`). Without this
2022                // fallback none of the three was found and every such event
2023                // collapsed to the generic "response failed", discarding
2024                // whatever the provider actually said. `response.failed`
2025                // events are unaffected: they carry no top-level `message`,
2026                // so they still fall through to that default.
2027                .or(Some(value));
2028            let message = err_obj
2029                .and_then(|e| e.get("message"))
2030                .and_then(Value::as_str)
2031                .unwrap_or("response failed");
2032            let code = err_obj.and_then(|e| e.get("code")).and_then(Value::as_str);
2033            let param = err_obj.and_then(|e| e.get("param")).and_then(Value::as_str);
2034            // Keep the provider's `code` and `param` in the surfaced error
2035            // (upstream #9616). Only `message` used to survive, so a streamed
2036            // `400` arrived as bare text like "Invalid value" with nothing
2037            // naming the field that was wrong — the one detail that makes it
2038            // actionable. Upstream carries them as attributes on its own
2039            // exception type; `Error::service` carries a string, so they go
2040            // in the message, formatted as upstream formats its own.
2041            let mut detail = match code {
2042                Some(code) => format!("{code}: {message}"),
2043                None => message.to_string(),
2044            };
2045            if let Some(param) = param {
2046                detail.push_str(&format!(" (parameter: {param})"));
2047            }
2048            // Same classification as the non-streaming `response_failure_error`
2049            // so callers branching on content filters see one behavior for
2050            // streamed and non-streamed Responses.
2051            EventOutcome::Error(match code {
2052                Some("content_filter") => Error::service_content_filter(detail),
2053                _ => Error::service(detail),
2054            })
2055        }
2056        "response.output_item.done" => {
2057            // A finished code-interpreter run: the done item is the only
2058            // place its `outputs` arrive while streaming, and its `code` is
2059            // final. Emitted whole, once. (Upstream also streams the code
2060            // live from `code_interpreter_call_code.delta` with a merge mode
2061            // this port's content model has no counterpart for, so the code
2062            // arrives here instead of in fragments.)
2063            if let Some(item) = value
2064                .get("item")
2065                .filter(|i| i.get("type").and_then(Value::as_str) == Some("code_interpreter_call"))
2066            {
2067                return EventOutcome::Update(ChatResponseUpdate {
2068                    contents: code_interpreter_contents(item),
2069                    role: Some(Role::assistant()),
2070                    ..Default::default()
2071                });
2072            }
2073            #[cfg(feature = "experimental-computer-use")]
2074            if let Some(item) = value.get("item").filter(|i| {
2075                matches!(
2076                    i.get("type").and_then(Value::as_str),
2077                    Some("computer_call" | "computer_call_output")
2078                )
2079            }) {
2080                let mut contents = Vec::new();
2081                parse_output_item(item, &mut contents);
2082                return EventOutcome::Update(ChatResponseUpdate {
2083                    contents,
2084                    role: Some(Role::assistant()),
2085                    ..Default::default()
2086                });
2087            }
2088            // A function call this stream never announced — a resumed
2089            // stream that started after its `output_item.added` and had no
2090            // routing for it — arrives whole here: the done item carries
2091            // the call id, name and complete arguments, as .NET builds its
2092            // calls. A call that was announced streamed its arguments
2093            // already, so it is not repeated.
2094            if let Some(item) = value
2095                .get("item")
2096                .filter(|i| i.get("type").and_then(Value::as_str) == Some("function_call"))
2097            {
2098                let output_index = value
2099                    .get("output_index")
2100                    .and_then(Value::as_i64)
2101                    .unwrap_or(0);
2102                if call_ids.contains_key(&output_index) {
2103                    return EventOutcome::None;
2104                }
2105                let field = |name: &str| {
2106                    item.get(name)
2107                        .and_then(Value::as_str)
2108                        .unwrap_or_default()
2109                        .to_string()
2110                };
2111                let call_id = field("call_id");
2112                call_ids.insert(output_index, call_id.clone());
2113                return EventOutcome::Update(ChatResponseUpdate {
2114                    contents: vec![Content::FunctionCall(FunctionCallContent::new(
2115                        call_id,
2116                        field("name"),
2117                        Some(FunctionArguments::Raw(field("arguments"))),
2118                    ))],
2119                    role: Some(Role::assistant()),
2120                    ..Default::default()
2121                });
2122            }
2123            let Some(item) = value
2124                .get("item")
2125                .filter(|i| i.get("type").and_then(Value::as_str) == Some("mcp_call"))
2126            else {
2127                return EventOutcome::None;
2128            };
2129            // The completed item carries the final arguments and the
2130            // output or error, so the call and its result come from here.
2131            EventOutcome::Update(ChatResponseUpdate {
2132                contents: mcp_call_item_contents(item),
2133                role: Some(Role::assistant()),
2134                ..Default::default()
2135            })
2136        }
2137        // Recognized but carry no additional content: the arguments are
2138        // already fully accumulated via `.delta` events, and item/part
2139        // lifecycle markers don't themselves map to a `Content`.
2140        "response.function_call_arguments.done"
2141        | "response.mcp_call_arguments.delta"
2142        | "response.mcp_call_arguments.done"
2143        | "response.content_part.added"
2144        | "response.content_part.done"
2145        | "response.in_progress" => EventOutcome::None,
2146        _ => EventOutcome::None,
2147    }
2148}
2149
2150// endregion
2151
2152/// Computer use (experimental `COMPUTER_USE`): `computer_call` /
2153/// `computer_call_output` items to and from
2154/// [`ComputerToolCallContent`](agent_framework_core::types::ComputerToolCallContent) /
2155/// [`ComputerToolResultContent`](agent_framework_core::types::ComputerToolResultContent)
2156/// (upstream `_chat_client.py`). Malformed provider items are skipped with a
2157/// warning; upstream raises.
2158#[cfg(feature = "experimental-computer-use")]
2159#[cfg_attr(docsrs, doc(cfg(feature = "experimental-computer-use")))]
2160pub use computer::{SCREENSHOT_DETAIL_KEY, SCREENSHOT_FILE_ID_KEY, SCREENSHOT_IMAGE_URL_KEY};
2161
2162#[cfg(feature = "experimental-computer-use")]
2163mod computer {
2164    use agent_framework_core::types::{
2165        ComputerSafetyCheck, ComputerToolCallContent, ComputerToolResultContent, Content,
2166        DataContent, HostedFileContent, Message, UriContent,
2167    };
2168    use serde_json::{json, Map, Value};
2169
2170    /// Marks a call parsed from the preview single-`action` form, so it is
2171    /// replayed in that form.
2172    const ACTION_FORMAT_KEY: &str = "computer_action_format";
2173
2174    fn safety_checks(value: Option<&Value>) -> Option<Vec<ComputerSafetyCheck>> {
2175        let items = value?.as_array()?;
2176        Some(
2177            items
2178                .iter()
2179                .filter_map(|c| serde_json::from_value(c.clone()).ok())
2180                .collect(),
2181        )
2182    }
2183
2184    pub(super) fn parse_call(item: &Value) -> Option<Content> {
2185        let (actions, single) = match (item.get("actions"), item.get("action")) {
2186            (Some(Value::Array(actions)), _) => (actions.clone(), false),
2187            (None, Some(action)) => (vec![action.clone()], true),
2188            _ => (Vec::new(), false),
2189        };
2190        let id = item.get("id").and_then(Value::as_str).unwrap_or_default();
2191        let call_id = item
2192            .get("call_id")
2193            .and_then(Value::as_str)
2194            .unwrap_or_default();
2195        if id.is_empty() || call_id.is_empty() || actions.is_empty() {
2196            tracing::warn!("Responses: skipping a computer_call without an id, call_id or actions");
2197            return None;
2198        }
2199        if actions.iter().any(|a| !a.is_object()) {
2200            tracing::warn!("Responses: skipping a computer_call whose actions are not objects");
2201            return None;
2202        }
2203        let mut additional_properties = Map::new();
2204        if single {
2205            additional_properties.insert(ACTION_FORMAT_KEY.into(), json!("single"));
2206        }
2207        Some(Content::ComputerToolCall(ComputerToolCallContent {
2208            id: id.into(),
2209            call_id: call_id.into(),
2210            actions,
2211            status: item
2212                .get("status")
2213                .and_then(Value::as_str)
2214                .map(str::to_string),
2215            pending_safety_checks: safety_checks(item.get("pending_safety_checks")),
2216            user_input_request: true,
2217            additional_properties,
2218        }))
2219    }
2220
2221    /// Result `additional_properties` keys carrying the screenshot metadata
2222    /// the screenshot content cannot hold: OpenAI's image `detail`, and the
2223    /// secondary reference when a screenshot has both an image URL and a
2224    /// file id (upstream keeps these on the screenshot content).
2225    pub const SCREENSHOT_DETAIL_KEY: &str = "screenshot_detail";
2226    /// See [`SCREENSHOT_DETAIL_KEY`]: the file id alongside an image URL.
2227    pub const SCREENSHOT_FILE_ID_KEY: &str = "screenshot_file_id";
2228    /// See [`SCREENSHOT_DETAIL_KEY`]: the image URL alongside a file id.
2229    pub const SCREENSHOT_IMAGE_URL_KEY: &str = "screenshot_image_url";
2230
2231    pub(super) fn parse_result(item: &Value) -> Option<Content> {
2232        let output = item
2233            .get("output")
2234            .filter(|o| o.get("type").and_then(Value::as_str) == Some("computer_screenshot"));
2235        let call_id = item
2236            .get("call_id")
2237            .and_then(Value::as_str)
2238            .unwrap_or_default();
2239        let (Some(output), false) = (output, call_id.is_empty()) else {
2240            tracing::warn!(
2241                "Responses: skipping a computer_call_output without a call_id or computer screenshot"
2242            );
2243            return None;
2244        };
2245        let image_url = output
2246            .get("image_url")
2247            .and_then(Value::as_str)
2248            .filter(|u| !u.is_empty());
2249        let file_id = output
2250            .get("file_id")
2251            .and_then(Value::as_str)
2252            .filter(|f| !f.is_empty());
2253        let screenshot = match (image_url, file_id) {
2254            (Some(url), _) if url.starts_with("data:") => Content::Data(DataContent {
2255                uri: url.into(),
2256                media_type: DataContent::media_type_from_uri(url).ok(),
2257            }),
2258            (Some(url), _) => Content::Uri(UriContent {
2259                uri: url.into(),
2260                media_type: "image/png".into(),
2261            }),
2262            (None, Some(file_id)) => Content::HostedFile(HostedFileContent {
2263                file_id: file_id.into(),
2264            }),
2265            (None, None) => {
2266                tracing::warn!(
2267                    "Responses: skipping a computer screenshot without an image URL or file id"
2268                );
2269                return None;
2270            }
2271        };
2272        let mut additional_properties = Map::new();
2273        if let Some(detail) = output.get("detail").filter(|d| !d.is_null()) {
2274            additional_properties.insert(SCREENSHOT_DETAIL_KEY.into(), detail.clone());
2275        }
2276        match (image_url, file_id) {
2277            (Some(_), Some(file_id)) => {
2278                additional_properties.insert(SCREENSHOT_FILE_ID_KEY.into(), json!(file_id));
2279            }
2280            (None, Some(_)) => {}
2281            _ => {}
2282        }
2283        Some(Content::ComputerToolResult(ComputerToolResultContent {
2284            call_id: call_id.into(),
2285            id: item.get("id").and_then(Value::as_str).map(str::to_string),
2286            status: item
2287                .get("status")
2288                .and_then(Value::as_str)
2289                .map(str::to_string),
2290            screenshot: Some(Box::new(screenshot)),
2291            acknowledged_safety_checks: safety_checks(item.get("acknowledged_safety_checks")),
2292            additional_properties,
2293        }))
2294    }
2295
2296    pub(super) fn call_to_item(call: &ComputerToolCallContent) -> Value {
2297        let mut item = Map::new();
2298        item.insert("type".into(), json!("computer_call"));
2299        item.insert("id".into(), json!(call.id));
2300        item.insert("call_id".into(), json!(call.call_id));
2301        let single = call.additional_properties.get(ACTION_FORMAT_KEY) == Some(&json!("single"))
2302            && call.actions.len() == 1;
2303        if single {
2304            item.insert("action".into(), call.actions[0].clone());
2305        } else {
2306            item.insert("actions".into(), json!(call.actions));
2307        }
2308        if let Some(status) = &call.status {
2309            item.insert("status".into(), json!(status));
2310        }
2311        if let Some(checks) = &call.pending_safety_checks {
2312            item.insert("pending_safety_checks".into(), json!(checks));
2313        }
2314        Value::Object(item)
2315    }
2316
2317    /// `None` (with a warning) when the result has no screenshot the
2318    /// Responses API can take; upstream raises.
2319    pub(super) fn result_to_item(result: &ComputerToolResultContent) -> Option<Value> {
2320        let mut output = Map::new();
2321        output.insert("type".into(), json!("computer_screenshot"));
2322        match result.screenshot.as_deref() {
2323            Some(Content::Uri(u)) => {
2324                output.insert("image_url".into(), json!(u.uri));
2325            }
2326            Some(Content::Data(d)) => {
2327                output.insert("image_url".into(), json!(d.uri));
2328            }
2329            Some(Content::HostedFile(f)) => {
2330                output.insert("file_id".into(), json!(f.file_id));
2331            }
2332            _ => {
2333                tracing::warn!(
2334                    call_id = %result.call_id,
2335                    "Responses: a computer result needs a screenshot (image URL or file id); dropping it"
2336                );
2337                return None;
2338            }
2339        }
2340        let extra = |key: &str| {
2341            result
2342                .additional_properties
2343                .get(key)
2344                .filter(|v| v.as_str().is_some_and(|s| !s.is_empty()))
2345        };
2346        if output.contains_key("image_url") {
2347            if let Some(file_id) = extra(SCREENSHOT_FILE_ID_KEY) {
2348                output.insert("file_id".into(), file_id.clone());
2349            }
2350        } else if let Some(url) = extra(SCREENSHOT_IMAGE_URL_KEY) {
2351            output.insert("image_url".into(), url.clone());
2352        }
2353        if let Some(detail) = extra(SCREENSHOT_DETAIL_KEY) {
2354            output.insert("detail".into(), detail.clone());
2355        }
2356        let mut item = Map::new();
2357        item.insert("type".into(), json!("computer_call_output"));
2358        item.insert("call_id".into(), json!(result.call_id));
2359        item.insert("output".into(), Value::Object(output));
2360        if let Some(id) = &result.id {
2361            item.insert("id".into(), json!(id));
2362        }
2363        if let Some(status) = &result.status {
2364            item.insert("status".into(), json!(status));
2365        }
2366        if let Some(checks) = &result.acknowledged_safety_checks {
2367            item.insert("acknowledged_safety_checks".into(), json!(checks));
2368        }
2369        Some(Value::Object(item))
2370    }
2371
2372    /// A call answered by a completed result no longer awaits the
2373    /// application (upstream `_mark_completed_computer_calls`).
2374    pub(super) fn mark_completed_calls(messages: &mut [Message]) {
2375        let completed: Vec<String> = messages
2376            .iter()
2377            .flat_map(|m| m.contents.iter())
2378            .filter_map(|c| match c {
2379                Content::ComputerToolResult(r)
2380                    if matches!(r.status.as_deref(), None | Some("completed")) =>
2381                {
2382                    Some(r.call_id.clone())
2383                }
2384                _ => None,
2385            })
2386            .collect();
2387        let mut remaining = completed;
2388        for content in messages.iter_mut().flat_map(|m| m.contents.iter_mut()) {
2389            if let Content::ComputerToolCall(call) = content {
2390                if let Some(i) = remaining.iter().position(|id| *id == call.call_id) {
2391                    call.user_input_request = false;
2392                    remaining.remove(i);
2393                }
2394            }
2395        }
2396    }
2397}
2398
2399#[cfg(all(test, feature = "experimental-computer-use"))]
2400mod computer_tests {
2401    use super::*;
2402    use agent_framework_core::types::{ComputerSafetyCheck, ComputerToolResultContent, UriContent};
2403
2404    #[test]
2405    fn screenshot_detail_and_secondary_references_round_trip() {
2406        for output in [
2407            json!({"type": "computer_screenshot", "image_url": "https://x/s.png",
2408                   "file_id": "file_1", "detail": "high"}),
2409            json!({"type": "computer_screenshot", "file_id": "file_2",
2410                   "image_url": "https://x/t.png", "detail": "low"}),
2411        ] {
2412            let response = response_with(vec![
2413                computer_call("cu_1"),
2414                json!({"type": "computer_call_output", "call_id": "call_1", "output": output}),
2415            ]);
2416            let msgs = response.messages.clone();
2417            let input = messages_to_input(&msgs);
2418            let replayed = input
2419                .iter()
2420                .find(|i| i["type"] == "computer_call_output")
2421                .expect("the result is replayed");
2422            assert_eq!(replayed["output"], output, "{replayed}");
2423        }
2424    }
2425
2426    fn response_with(items: Vec<Value>) -> ChatResponse {
2427        parse_response(&json!({"id": "resp_1", "output": items}), None)
2428    }
2429
2430    fn computer_call(id: &str) -> Value {
2431        json!({
2432            "type": "computer_call", "id": id, "call_id": "call_1", "status": "completed",
2433            "actions": [{"type": "click", "x": 1, "y": 2, "button": "left"}],
2434            "pending_safety_checks": [{"id": "sc_1", "code": "irrelevant_domain", "message": "check"}]
2435        })
2436    }
2437
2438    fn contents(response: &ChatResponse) -> Vec<Content> {
2439        response
2440            .messages
2441            .iter()
2442            .flat_map(|m| m.contents.clone())
2443            .collect()
2444    }
2445
2446    #[test]
2447    fn the_computer_tool_is_declared() {
2448        assert_eq!(
2449            tool_to_responses_spec(&agent_framework_core::tools::hosted_computer()),
2450            json!({"type": "computer"})
2451        );
2452    }
2453
2454    #[test]
2455    fn computer_calls_parse_and_stay_pending_until_answered() {
2456        let response = response_with(vec![computer_call("cu_1")]);
2457        let all = contents(&response);
2458        let [Content::ComputerToolCall(call)] = all.as_slice() else {
2459            panic!("one computer call: {all:?}");
2460        };
2461        assert_eq!(call.call_id, "call_1");
2462        assert_eq!(call.actions[0]["type"], "click");
2463        assert!(call.user_input_request);
2464        assert_eq!(
2465            call.pending_safety_checks,
2466            Some(vec![ComputerSafetyCheck {
2467                id: "sc_1".into(),
2468                code: Some("irrelevant_domain".into()),
2469                message: Some("check".into()),
2470            }])
2471        );
2472
2473        // A completed output for the call clears it.
2474        let answered = response_with(vec![
2475            computer_call("cu_1"),
2476            json!({"type": "computer_call_output", "call_id": "call_1", "status": "completed",
2477                   "output": {"type": "computer_screenshot", "image_url": "https://x/s.png"}}),
2478        ]);
2479        let all = contents(&answered);
2480        assert!(matches!(&all[0], Content::ComputerToolCall(c) if !c.user_input_request));
2481        assert!(matches!(&all[1], Content::ComputerToolResult(r)
2482            if matches!(r.screenshot.as_deref(), Some(Content::Uri(u)) if u.uri == "https://x/s.png")));
2483
2484        // Malformed items are skipped.
2485        assert!(contents(&response_with(vec![
2486            json!({"type": "computer_call", "id": "x"})
2487        ]))
2488        .is_empty());
2489    }
2490
2491    #[test]
2492    fn preview_single_action_calls_replay_in_their_form() {
2493        let response = response_with(vec![json!({
2494            "type": "computer_call", "id": "cu_2", "call_id": "call_2",
2495            "action": {"type": "screenshot"}
2496        })]);
2497        let msgs = response.messages.clone();
2498        let input = messages_to_input(&msgs);
2499        assert_eq!(input[0]["type"], "computer_call");
2500        assert_eq!(input[0]["action"]["type"], "screenshot");
2501        assert!(input[0].get("actions").is_none());
2502    }
2503
2504    #[test]
2505    fn results_become_computer_call_outputs() {
2506        let call = contents(&response_with(vec![computer_call("cu_1")]));
2507        let result = ComputerToolResultContent::new("call_1")
2508            .unwrap()
2509            .with_screenshot(Content::Uri(UriContent {
2510                uri: "https://x/after.png".into(),
2511                media_type: "image/png".into(),
2512            }))
2513            .unwrap()
2514            .with_acknowledged_safety_checks(vec![ComputerSafetyCheck {
2515                id: "sc_1".into(),
2516                ..Default::default()
2517            }]);
2518        let messages = vec![
2519            Message::with_contents(Role::assistant(), call),
2520            Message::with_contents(Role::tool(), vec![Content::ComputerToolResult(result)]),
2521        ];
2522        let input = messages_to_input(&messages);
2523        assert_eq!(input[0]["type"], "computer_call");
2524        assert_eq!(input[0]["actions"][0]["type"], "click");
2525        assert_eq!(
2526            input[1],
2527            json!({"type": "computer_call_output", "call_id": "call_1",
2528                   "output": {"type": "computer_screenshot", "image_url": "https://x/after.png"},
2529                   "acknowledged_safety_checks": [{"id": "sc_1"}]})
2530        );
2531        // Continuing a stored response sends only the output.
2532        let continued = messages_to_continuation_input(&messages);
2533        assert_eq!(continued.len(), 1);
2534        assert_eq!(continued[0]["type"], "computer_call_output");
2535    }
2536
2537    #[test]
2538    fn a_streamed_computer_call_arrives_with_its_done_item() {
2539        let EventOutcome::Update(update) = parse_responses_event(
2540            &json!({"type": "response.output_item.done", "output_index": 0, "item": computer_call("cu_9")}),
2541            &mut HashMap::new(),
2542            None,
2543        ) else {
2544            panic!("an update");
2545        };
2546        assert!(matches!(&update.contents[0], Content::ComputerToolCall(c) if c.id == "cu_9"));
2547    }
2548}
2549
2550#[cfg(test)]
2551mod tests {
2552    use super::*;
2553
2554    #[test]
2555    fn service_url_reports_the_configured_base_url() {
2556        // Read by the observability layer as `server.address` (#9225, #9222).
2557        let client =
2558            OpenAIChatClient::new("k", "gpt-4o-mini").with_base_url("http://gateway.example/v1");
2559        assert_eq!(client.service_url(), Some("http://gateway.example/v1"));
2560    }
2561    use agent_framework_core::tools::{ApprovalMode, ToolDefinition, ToolKind};
2562    use agent_framework_core::types::{
2563        FunctionApprovalResponseContent, FunctionResultContent, HostedFileContent,
2564    };
2565
2566    fn user(text: &str) -> Message {
2567        Message::user(text)
2568    }
2569
2570    fn user_with(contents: Vec<Content>) -> Message {
2571        Message::with_contents(Role::user(), contents)
2572    }
2573
2574    /// Parse a single Responses output item into its content list.
2575    fn parse_item(item: Value) -> Vec<Content> {
2576        let mut contents = Vec::new();
2577        parse_output_item(&item, &mut contents);
2578        contents
2579    }
2580
2581    fn client() -> OpenAIChatClient {
2582        OpenAIChatClient::new("test-key", "gpt-4o-mini")
2583    }
2584
2585    // region: request body building
2586
2587    #[test]
2588    fn build_body_simple_text() {
2589        let c = client();
2590        let body = c.build_body(&[user("Hello there")], &ChatOptions::new(), false);
2591        assert_eq!(
2592            body,
2593            json!({
2594                "model": "gpt-4o-mini",
2595                "input": [
2596                    { "type": "message", "role": "user", "content": [
2597                        { "type": "input_text", "text": "Hello there" }
2598                    ]}
2599                ],
2600                // Nothing is stored service-side on this request, so the
2601                // encrypted reasoning item is requested for the replay path.
2602                "include": ["reasoning.encrypted_content"],
2603            })
2604        );
2605    }
2606
2607    #[test]
2608    fn responses_usage_parses_cache_write_tokens() {
2609        // Cache *writes* are reported separately from cache reads (upstream #7369).
2610        let d = parse_responses_usage(&json!({
2611            "input_tokens": 2000,
2612            "output_tokens": 60,
2613            "total_tokens": 2060,
2614            "input_tokens_details": { "cached_tokens": 0, "cache_write_tokens": 1024 },
2615        }));
2616        assert_eq!(d.cache_creation_input_token_count, Some(1024));
2617        assert_eq!(d.cache_read_input_token_count, Some(0));
2618        assert_eq!(
2619            d.additional_counts.get("openai.cache_write_tokens"),
2620            Some(&1024)
2621        );
2622    }
2623
2624    #[test]
2625    fn responses_usage_omits_cache_write_tokens_when_not_reported() {
2626        let d = parse_responses_usage(&json!({
2627            "input_tokens": 100,
2628            "output_tokens": 20,
2629            "input_tokens_details": { "cached_tokens": 40 },
2630        }));
2631        assert_eq!(d.cache_creation_input_token_count, None);
2632        assert!(!d
2633            .additional_counts
2634            .contains_key("openai.cache_write_tokens"));
2635    }
2636
2637    #[test]
2638    fn build_body_extracts_leading_system_message_as_instructions() {
2639        let c = client();
2640        let messages = vec![Message::system("Be terse."), user("Hi")];
2641        let body = c.build_body(&messages, &ChatOptions::new(), false);
2642        assert_eq!(body["instructions"], json!("Be terse."));
2643        assert_eq!(
2644            body["input"],
2645            json!([
2646                { "type": "message", "role": "user", "content": [
2647                    { "type": "input_text", "text": "Hi" }
2648                ]}
2649            ])
2650        );
2651    }
2652
2653    #[test]
2654    fn build_body_combines_options_instructions_and_system_message() {
2655        let c = client();
2656        let messages = vec![Message::system("Also be nice."), user("Hi")];
2657        let options = ChatOptions::new().with_instructions("Be terse.");
2658        let body = c.build_body(&messages, &options, false);
2659        assert_eq!(body["instructions"], json!("Be terse.\n\nAlso be nice."));
2660    }
2661
2662    #[test]
2663    fn build_body_assistant_text_uses_output_text_type() {
2664        let c = client();
2665        let messages = vec![user("Hi"), Message::assistant("Hello!")];
2666        let body = c.build_body(&messages, &ChatOptions::new(), false);
2667        assert_eq!(
2668            body["input"][1],
2669            json!({ "type": "message", "role": "assistant", "content": [
2670                { "type": "output_text", "text": "Hello!" }
2671            ]})
2672        );
2673    }
2674
2675    #[test]
2676    fn build_body_function_call_round_trip() {
2677        let c = client();
2678        let call = FunctionCallContent::new(
2679            "call_1",
2680            "get_weather",
2681            Some(FunctionArguments::Raw(r#"{"city":"Paris"}"#.to_string())),
2682        );
2683        let assistant_msg =
2684            Message::with_contents(Role::assistant(), vec![Content::FunctionCall(call)]);
2685        let tool_msg = Message::with_contents(
2686            Role::tool(),
2687            vec![Content::FunctionResult(FunctionResultContent::new(
2688                "call_1",
2689                Some(json!("18C and sunny")),
2690            ))],
2691        );
2692        let body = c.build_body(
2693            &[user("weather?"), assistant_msg, tool_msg],
2694            &ChatOptions::new(),
2695            false,
2696        );
2697        assert_eq!(
2698            body["input"],
2699            json!([
2700                { "type": "message", "role": "user", "content": [
2701                    { "type": "input_text", "text": "weather?" }
2702                ]},
2703                { "type": "function_call", "call_id": "call_1", "name": "get_weather", "arguments": "{\"city\":\"Paris\"}" },
2704                { "type": "function_call_output", "call_id": "call_1", "output": "18C and sunny" },
2705            ])
2706        );
2707    }
2708
2709    #[test]
2710    fn build_body_tools_are_flat_not_nested() {
2711        let c = client();
2712        let tool = ToolDefinition {
2713            name: "get_weather".into(),
2714            description: "Get the weather".into(),
2715            parameters: json!({ "type": "object", "properties": {} }),
2716            kind: ToolKind::Function,
2717            approval_mode: ApprovalMode::NeverRequire,
2718            executor: None,
2719        };
2720        let options = ChatOptions::new().with_tool(tool);
2721        let body = c.build_body(&[user("hi")], &options, false);
2722        assert_eq!(
2723            body["tools"],
2724            json!([{
2725                "type": "function",
2726                "name": "get_weather",
2727                "description": "Get the weather",
2728                "parameters": { "type": "object", "properties": {} },
2729            }])
2730        );
2731    }
2732
2733    #[test]
2734    fn build_body_tool_choice_required_named() {
2735        let c = client();
2736        let options =
2737            ChatOptions::new().with_tool_choice(ToolMode::Required(Some("get_weather".into())));
2738        let body = c.build_body(&[user("hi")], &options, false);
2739        assert_eq!(
2740            body["tool_choice"],
2741            json!({ "type": "function", "name": "get_weather" })
2742        );
2743    }
2744
2745    #[test]
2746    fn stateless_request_asks_for_the_encrypted_reasoning_item() {
2747        // A reasoning item is only replayable on the next turn if it carries
2748        // `encrypted_content`, and the service only returns that when asked.
2749        let c = client();
2750        let body = c.build_body(&[user("hi")], &ChatOptions::new(), false);
2751        assert_eq!(body["include"], json!(["reasoning.encrypted_content"]));
2752    }
2753
2754    #[test]
2755    fn a_service_side_conversation_needs_no_encrypted_reasoning() {
2756        // The service already holds the reasoning item, so echoing it back is
2757        // pointless — and upstream keys this off the storage indicators, not
2758        // off `store`.
2759        let mut options = ChatOptions::new();
2760        options.conversation_id = Some("resp_abc123".into());
2761        let body = client().build_body(&[user("hi")], &options, false);
2762        assert!(
2763            body.get("include").is_none(),
2764            "no include expected, got: {}",
2765            body
2766        );
2767    }
2768
2769    #[test]
2770    fn an_empty_conversation_id_is_not_service_side_storage() {
2771        // An empty id is no id: it would not continue anything server-side, so
2772        // the request is still stateless and still needs the item echoed back.
2773        let mut options = ChatOptions::new();
2774        options.conversation_id = Some(String::new());
2775        let body = client().build_body(&[user("hi")], &options, false);
2776        assert_eq!(body["include"], json!(["reasoning.encrypted_content"]));
2777    }
2778
2779    #[test]
2780    fn a_callers_own_include_entries_survive_and_are_not_duplicated() {
2781        // The caller's entries are preserved alongside the implicit one...
2782        let mut options = ChatOptions::new();
2783        options
2784            .additional_properties
2785            .insert("include".into(), json!(["file_search_call.results"]));
2786        let body = client().build_body(&[user("hi")], &options, false);
2787        assert_eq!(
2788            body["include"],
2789            json!(["file_search_call.results", "reasoning.encrypted_content"])
2790        );
2791
2792        // ...and asking for the encrypted item by name does not get it twice.
2793        let mut options = ChatOptions::new();
2794        options
2795            .additional_properties
2796            .insert("include".into(), json!(["reasoning.encrypted_content"]));
2797        let body = client().build_body(&[user("hi")], &options, false);
2798        assert_eq!(body["include"], json!(["reasoning.encrypted_content"]));
2799    }
2800
2801    #[test]
2802    fn an_explicit_empty_include_is_omitted_not_sent_as_an_empty_array() {
2803        // `responses_include` drops an empty array, and the
2804        // `additional_properties` pass must not put it back: `include` is
2805        // that function's alone. Reached here via a stored conversation, which
2806        // suppresses the implicit entry that would otherwise fill the array.
2807        let mut options = ChatOptions::new();
2808        options.conversation_id = Some("resp_abc123".into());
2809        options
2810            .additional_properties
2811            .insert("include".into(), json!([]));
2812        let body = client().build_body(&[user("hi")], &options, false);
2813        assert!(
2814            body.get("include").is_none(),
2815            "an empty include should be omitted entirely, got: {}",
2816            body
2817        );
2818    }
2819
2820    #[test]
2821    fn other_additional_properties_still_pass_through() {
2822        // Only `include` is intercepted; everything else the caller sets still
2823        // reaches the body.
2824        let mut options = ChatOptions::new();
2825        options
2826            .additional_properties
2827            .insert("safety_identifier".into(), json!("user-123"));
2828        let body = client().build_body(&[user("hi")], &options, false);
2829        assert_eq!(body["safety_identifier"], json!("user-123"));
2830    }
2831
2832    #[test]
2833    fn build_body_conversation_id_becomes_previous_response_id() {
2834        let c = client();
2835        let mut options = ChatOptions::new();
2836        options.conversation_id = Some("resp_abc123".into());
2837        let body = c.build_body(&[user("hi")], &options, false);
2838        assert_eq!(body["previous_response_id"], json!("resp_abc123"));
2839    }
2840
2841    #[test]
2842    fn build_body_max_tokens_becomes_max_output_tokens() {
2843        let c = client();
2844        let options = ChatOptions::new().with_max_tokens(256);
2845        let body = c.build_body(&[user("hi")], &options, false);
2846        assert_eq!(body["max_output_tokens"], json!(256));
2847        assert!(body.get("max_tokens").is_none());
2848    }
2849
2850    #[test]
2851    fn build_body_response_format_becomes_text_format() {
2852        let c = client();
2853        let mut options = ChatOptions::new();
2854        options.response_format = Some(ResponseFormat::JsonSchema {
2855            name: "answer".into(),
2856            description: None,
2857            schema: json!({"type": "object"}),
2858            strict: Some(true),
2859        });
2860        let body = c.build_body(&[user("hi")], &options, false);
2861        assert_eq!(
2862            body["text"]["format"],
2863            json!({ "type": "json_schema", "name": "answer", "schema": {"type": "object"}, "strict": true })
2864        );
2865    }
2866
2867    #[test]
2868    fn build_body_stream_flag() {
2869        let c = client();
2870        let body = c.build_body(&[user("hi")], &ChatOptions::new(), true);
2871        assert_eq!(body["stream"], json!(true));
2872    }
2873
2874    // endregion
2875
2876    // region: response parsing
2877
2878    #[test]
2879    fn parse_response_text_and_usage() {
2880        let value = json!({
2881            "id": "resp_123",
2882            "model": "gpt-4o-mini",
2883            "status": "completed",
2884            "output": [
2885                { "type": "message", "role": "assistant", "content": [
2886                    { "type": "output_text", "text": "Hello!" }
2887                ]}
2888            ],
2889            "usage": { "input_tokens": 10, "output_tokens": 5, "total_tokens": 15 },
2890        });
2891        let resp = parse_response(&value, None);
2892        assert_eq!(resp.response_id.as_deref(), Some("resp_123"));
2893        assert_eq!(resp.conversation_id.as_deref(), Some("resp_123"));
2894        assert_eq!(resp.text(), "Hello!");
2895        assert_eq!(resp.finish_reason, Some(FinishReason::stop()));
2896        let usage = resp.usage_details.unwrap();
2897        assert_eq!(usage.input_token_count, Some(10));
2898        assert_eq!(usage.output_token_count, Some(5));
2899        assert_eq!(usage.total_token_count, Some(15));
2900    }
2901
2902    #[test]
2903    fn parse_response_keeps_one_message_per_message_item() {
2904        let value = json!({
2905            "id": "resp_1",
2906            "status": "completed",
2907            "output": [
2908                { "type": "reasoning", "id": "rs_1", "summary": [{ "type": "summary_text", "text": "think" }] },
2909                { "type": "message", "id": "msg_1", "role": "assistant", "content": [
2910                    { "type": "output_text", "text": "Checking the refund policy." }
2911                ]},
2912                { "type": "message", "id": "msg_2", "role": "assistant", "content": [
2913                    { "type": "output_text", "text": "The refund requires approval." }
2914                ]},
2915                { "type": "function_call", "call_id": "c1", "name": "approve", "arguments": "{}" }
2916            ],
2917        });
2918        let resp = parse_response(&value, None);
2919        let ids: Vec<_> = resp
2920            .messages
2921            .iter()
2922            .map(|m| m.message_id.as_deref())
2923            .collect();
2924        assert_eq!(ids, [Some("msg_1"), Some("msg_2")]);
2925        assert_eq!(resp.messages[0].text(), "Checking the refund policy.");
2926        assert!(matches!(
2927            resp.messages[0].contents[0],
2928            Content::TextReasoning(_)
2929        ));
2930        assert_eq!(resp.messages[1].text(), "The refund requires approval.");
2931        assert!(matches!(
2932            resp.messages[1].contents[1],
2933            Content::FunctionCall(_)
2934        ));
2935        assert_eq!(resp.response_id.as_deref(), Some("resp_1"));
2936    }
2937
2938    #[test]
2939    fn parse_response_without_message_items_has_one_unnamed_message() {
2940        let value = json!({"id": "resp_1", "output": [
2941            { "type": "function_call", "call_id": "c1", "name": "f", "arguments": "{}" }
2942        ]});
2943        let resp = parse_response(&value, None);
2944        assert_eq!(resp.messages.len(), 1);
2945        assert_eq!(resp.messages[0].message_id, None);
2946    }
2947
2948    #[test]
2949    fn parse_response_store_false_omits_conversation_id() {
2950        let value = json!({
2951            "id": "resp_123",
2952            "status": "completed",
2953            "output": [],
2954        });
2955        let resp = parse_response(&value, Some(false));
2956        assert_eq!(resp.conversation_id, None);
2957    }
2958
2959    #[test]
2960    fn parse_response_function_call_sets_tool_calls_finish_reason() {
2961        let value = json!({
2962            "id": "resp_123",
2963            "status": "completed",
2964            "output": [
2965                { "type": "function_call", "call_id": "call_1", "name": "get_weather", "arguments": "{\"city\":\"Paris\"}" }
2966            ],
2967        });
2968        let resp = parse_response(&value, None);
2969        assert_eq!(resp.finish_reason, Some(FinishReason::tool_calls()));
2970        let calls = resp.function_calls();
2971        assert_eq!(calls.len(), 1);
2972        assert_eq!(calls[0].call_id, "call_1");
2973        assert_eq!(calls[0].name, "get_weather");
2974    }
2975
2976    #[test]
2977    fn parse_response_incomplete_max_output_tokens_is_length() {
2978        let value = json!({
2979            "id": "resp_123",
2980            "status": "incomplete",
2981            "incomplete_details": { "reason": "max_output_tokens" },
2982            "output": [],
2983        });
2984        let resp = parse_response(&value, None);
2985        assert_eq!(
2986            resp.finish_reason,
2987            Some(FinishReason::new(FinishReason::LENGTH))
2988        );
2989    }
2990
2991    /// `response.incomplete` is the terminal event for a stream cut off by
2992    /// the content filter or the token budget. Ignoring it — which this
2993    /// did — dropped the finish reason, usage and response id for exactly
2994    /// the streams whose distinct event name exists to report them, and
2995    /// left a client unable to tell a truncated answer from a complete one.
2996    #[test]
2997    fn a_streamed_response_incomplete_carries_its_terminal_metadata() {
2998        let mut call_ids = HashMap::new();
2999        let event = json!({
3000            "type": "response.incomplete",
3001            "response": {
3002                "id": "resp_123",
3003                "model": "gpt-4o",
3004                "status": "incomplete",
3005                "incomplete_details": { "reason": "content_filter" },
3006                "output": [],
3007                "usage": { "input_tokens": 3, "output_tokens": 5, "total_tokens": 8 },
3008            },
3009        });
3010        let EventOutcome::Update(update) = parse_responses_event(&event, &mut call_ids, None)
3011        else {
3012            panic!("response.incomplete must produce a terminal update");
3013        };
3014        assert_eq!(
3015            update.finish_reason,
3016            Some(FinishReason::new(FinishReason::CONTENT_FILTER))
3017        );
3018        assert_eq!(update.response_id.as_deref(), Some("resp_123"));
3019        assert_eq!(update.model.as_deref(), Some("gpt-4o"));
3020        let usage = update
3021            .contents
3022            .iter()
3023            .find_map(|c| match c {
3024                Content::Usage(u) => Some(&u.details),
3025                _ => None,
3026            })
3027            .expect("usage rides the terminal update");
3028        assert_eq!(usage.input_token_count, Some(3));
3029        assert_eq!(usage.output_token_count, Some(5));
3030    }
3031
3032    /// And a `response.completed` is unchanged by sharing the arm.
3033    #[test]
3034    fn a_streamed_response_completed_still_carries_its_metadata() {
3035        let mut call_ids = HashMap::new();
3036        let event = json!({
3037            "type": "response.completed",
3038            "response": {
3039                "id": "resp_456",
3040                "status": "completed",
3041                "output": [],
3042            },
3043        });
3044        let EventOutcome::Update(update) = parse_responses_event(&event, &mut call_ids, None)
3045        else {
3046            panic!("response.completed produces a terminal update");
3047        };
3048        assert_eq!(update.finish_reason, Some(FinishReason::stop()));
3049        assert_eq!(update.response_id.as_deref(), Some("resp_456"));
3050    }
3051
3052    #[test]
3053    fn parse_response_reasoning_becomes_text_reasoning() {
3054        let value = json!({
3055            "id": "resp_123",
3056            "status": "completed",
3057            "output": [
3058                { "type": "reasoning", "summary": [{ "type": "summary_text", "text": "thinking..." }] },
3059                { "type": "message", "role": "assistant", "content": [{ "type": "output_text", "text": "done" }] },
3060            ],
3061        });
3062        let resp = parse_response(&value, None);
3063        let contents = &resp.messages[0].contents;
3064        assert!(matches!(&contents[0], Content::TextReasoning(t) if t.text == "thinking..."));
3065        assert!(matches!(&contents[1], Content::Text(t) if t.text == "done"));
3066    }
3067
3068    #[test]
3069    fn reasoning_item_round_trips_through_input_for_store_false_replay() {
3070        // A store:false tool-loop replay must re-send the original reasoning
3071        // item (id + encrypted_content), not just its summary text.
3072        let reasoning_item = json!({
3073            "type": "reasoning",
3074            "id": "rs_abc",
3075            "encrypted_content": "ENC",
3076            "summary": [{ "type": "summary_text", "text": "thinking..." }],
3077        });
3078        let value = json!({
3079            "id": "resp_1",
3080            "status": "completed",
3081            "output": [
3082                reasoning_item,
3083                { "type": "function_call", "call_id": "c1", "name": "f", "arguments": "{}" },
3084            ],
3085        });
3086        let resp = parse_response(&value, Some(false));
3087        // The parsed reasoning content preserves the raw item.
3088        let reasoning = resp.messages[0]
3089            .contents
3090            .iter()
3091            .find_map(|c| match c {
3092                Content::TextReasoning(t) => Some(t),
3093                _ => None,
3094            })
3095            .expect("reasoning content");
3096        assert_eq!(
3097            reasoning.raw_representation.as_ref().unwrap()["id"],
3098            "rs_abc"
3099        );
3100
3101        // Replaying that assistant message back through the input mapper
3102        // re-emits the reasoning item verbatim, ahead of the function call.
3103        let input = messages_to_input(&resp.messages);
3104        let reasoning_pos = input
3105            .iter()
3106            .position(|i| i.get("type") == Some(&json!("reasoning")))
3107            .expect("reasoning item re-emitted");
3108        assert_eq!(input[reasoning_pos]["id"], "rs_abc");
3109        assert_eq!(input[reasoning_pos]["encrypted_content"], "ENC");
3110        let call_pos = input
3111            .iter()
3112            .position(|i| i.get("type") == Some(&json!("function_call")))
3113            .expect("function call present");
3114        assert!(reasoning_pos < call_pos, "reasoning must precede the call");
3115    }
3116
3117    #[test]
3118    fn summary_only_reasoning_is_not_re_emitted_as_input() {
3119        // A reasoning content with no preserved raw item (e.g. from streaming
3120        // display) has no valid input form and must be dropped, not sent as a
3121        // bogus reasoning item lacking id/encrypted_content.
3122        let msg = Message::with_contents(
3123            Role::assistant(),
3124            vec![Content::TextReasoning(TextReasoningContent {
3125                text: "just display".into(),
3126                annotations: None,
3127                raw_representation: None,
3128                protected_data: None,
3129            })],
3130        );
3131        let input = messages_to_input(&[msg]);
3132        assert!(input
3133            .iter()
3134            .all(|i| i.get("type") != Some(&json!("reasoning"))));
3135    }
3136
3137    // endregion
3138
3139    // region: streaming
3140
3141    fn sse_body(events: &[(&str, Value)]) -> String {
3142        let mut out = String::new();
3143        for (event, data) in events {
3144            out.push_str(&format!("event: {event}\ndata: {}\n\n", data));
3145        }
3146        out
3147    }
3148
3149    async fn collect_updates(text: String) -> Vec<ChatResponseUpdate> {
3150        // Build a fake reqwest::Response backed by the given SSE text using a
3151        // tiny local HTTP server would be overkill; instead we drive the
3152        // event parser directly through the same state machine by feeding
3153        // the byte stream via `futures::stream::once`.
3154        let stream =
3155            futures::stream::once(async move { Ok::<_, reqwest::Error>(bytes::Bytes::from(text)) });
3156        let byte_stream: ByteStream = Box::pin(stream);
3157        let mut state = ResponsesSseState {
3158            byte_stream,
3159            buffer: String::new(),
3160            utf8: Utf8StreamDecoder::new(),
3161            queued: VecDeque::new(),
3162            call_ids: HashMap::new(),
3163            done: false,
3164            store: None,
3165            background: None,
3166        };
3167        let mut updates = Vec::new();
3168        // Drain the single chunk manually (mirrors the real unfold body).
3169        if let Some(Ok(bytes)) = state.byte_stream.next().await {
3170            let decoded = state.utf8.push(&bytes);
3171            state.buffer.push_str(&decoded);
3172            while let Some(pos) = state.buffer.find('\n') {
3173                let line = state.buffer[..pos].trim().to_string();
3174                state.buffer.drain(..=pos);
3175                let Some(data) = line.strip_prefix("data:") else {
3176                    continue;
3177                };
3178                let data = data.trim();
3179                if data.is_empty() {
3180                    continue;
3181                }
3182                let value: Value = serde_json::from_str(data).unwrap();
3183                if let EventOutcome::Update(u) =
3184                    parse_responses_event(&value, &mut state.call_ids, state.store)
3185                {
3186                    updates.push(u);
3187                }
3188            }
3189        }
3190        updates
3191    }
3192
3193    #[tokio::test]
3194    async fn stream_keeps_one_message_per_output_item() {
3195        let mut events = vec![(
3196            "response.created",
3197            json!({ "type": "response.created", "response": { "id": "resp_1" } }),
3198        )];
3199        for (i, text) in [
3200            "Checking the refund policy.",
3201            "The refund requires approval.",
3202        ]
3203        .iter()
3204        .enumerate()
3205        {
3206            events.push((
3207                "response.output_text.delta",
3208                json!({ "type": "response.output_text.delta", "item_id": format!("msg_{i}"), "delta": text }),
3209            ));
3210        }
3211        let resp = ChatResponse::from_updates(collect_updates(sse_body(&events)).await);
3212        let texts: Vec<_> = resp.messages.iter().map(|m| m.text()).collect();
3213        assert_eq!(
3214            texts,
3215            [
3216                "Checking the refund policy.",
3217                "The refund requires approval."
3218            ]
3219        );
3220        assert_eq!(resp.messages[0].message_id.as_deref(), Some("msg_0"));
3221        assert_eq!(resp.messages[1].message_id.as_deref(), Some("msg_1"));
3222    }
3223
3224    #[tokio::test]
3225    async fn stream_text_only_accumulates() {
3226        let text = sse_body(&[
3227            (
3228                "response.created",
3229                json!({ "type": "response.created", "response": { "id": "resp_1", "model": "gpt-4o-mini" } }),
3230            ),
3231            (
3232                "response.output_text.delta",
3233                json!({ "type": "response.output_text.delta", "delta": "Hel" }),
3234            ),
3235            (
3236                "response.output_text.delta",
3237                json!({ "type": "response.output_text.delta", "delta": "lo!" }),
3238            ),
3239            (
3240                "response.completed",
3241                json!({ "type": "response.completed", "response": { "id": "resp_1", "model": "gpt-4o-mini", "status": "completed", "output": [], "usage": { "input_tokens": 3, "output_tokens": 2 } } }),
3242            ),
3243        ]);
3244        let updates = collect_updates(text).await;
3245        let resp = ChatResponse::from_updates(updates);
3246        assert_eq!(resp.text(), "Hello!");
3247        assert_eq!(resp.response_id.as_deref(), Some("resp_1"));
3248        assert_eq!(resp.finish_reason, Some(FinishReason::stop()));
3249        let usage = resp.usage_details.unwrap();
3250        assert_eq!(usage.input_token_count, Some(3));
3251        assert_eq!(usage.output_token_count, Some(2));
3252    }
3253
3254    #[tokio::test]
3255    async fn stream_tool_call_accumulates_arguments() {
3256        let text = sse_body(&[
3257            (
3258                "response.output_item.added",
3259                json!({ "type": "response.output_item.added", "output_index": 0, "item": { "type": "function_call", "call_id": "call_1", "name": "get_weather" } }),
3260            ),
3261            (
3262                "response.function_call_arguments.delta",
3263                json!({ "type": "response.function_call_arguments.delta", "output_index": 0, "delta": "{\"city\":" }),
3264            ),
3265            (
3266                "response.function_call_arguments.delta",
3267                json!({ "type": "response.function_call_arguments.delta", "output_index": 0, "delta": "\"Paris\"}" }),
3268            ),
3269            (
3270                "response.completed",
3271                json!({ "type": "response.completed", "response": { "id": "resp_2", "status": "completed", "output": [{"type":"function_call","call_id":"call_1","name":"get_weather","arguments":"{\"city\":\"Paris\"}"}] } }),
3272            ),
3273        ]);
3274        let updates = collect_updates(text).await;
3275        let resp = ChatResponse::from_updates(updates);
3276        let calls = resp.function_calls();
3277        assert_eq!(calls.len(), 1);
3278        assert_eq!(calls[0].call_id, "call_1");
3279        assert_eq!(calls[0].name, "get_weather");
3280        assert_eq!(
3281            calls[0].parse_arguments().unwrap().get("city").unwrap(),
3282            &json!("Paris")
3283        );
3284        assert_eq!(resp.finish_reason, Some(FinishReason::tool_calls()));
3285    }
3286
3287    #[tokio::test]
3288    async fn stream_failed_event_is_error() {
3289        let text = sse_body(&[(
3290            "response.failed",
3291            json!({ "type": "response.failed", "response": { "error": { "message": "boom" } } }),
3292        )]);
3293        let stream =
3294            futures::stream::once(async move { Ok::<_, reqwest::Error>(bytes::Bytes::from(text)) });
3295        let byte_stream: ByteStream = Box::pin(stream);
3296        let mut state = ResponsesSseState {
3297            byte_stream,
3298            buffer: String::new(),
3299            utf8: Utf8StreamDecoder::new(),
3300            queued: VecDeque::new(),
3301            call_ids: HashMap::new(),
3302            done: false,
3303            store: None,
3304            background: None,
3305        };
3306        let bytes = state.byte_stream.next().await.unwrap().unwrap();
3307        let decoded = state.utf8.push(&bytes);
3308        state.buffer.push_str(&decoded);
3309        let mut saw_error = false;
3310        while let Some(pos) = state.buffer.find('\n') {
3311            let line = state.buffer[..pos].trim().to_string();
3312            state.buffer.drain(..=pos);
3313            let Some(data) = line.strip_prefix("data:") else {
3314                continue;
3315            };
3316            let data = data.trim();
3317            if data.is_empty() {
3318                continue;
3319            }
3320            let value: Value = serde_json::from_str(data).unwrap();
3321            if let EventOutcome::Error(e) =
3322                parse_responses_event(&value, &mut state.call_ids, state.store)
3323            {
3324                assert!(e.to_string().contains("boom"));
3325                saw_error = true;
3326            }
3327        }
3328        assert!(
3329            saw_error,
3330            "expected a response.failed event to surface an error"
3331        );
3332    }
3333
3334    #[test]
3335    fn a_streamed_error_keeps_the_provider_code_and_param() {
3336        // Only `message` used to survive, so a streamed 400 arrived as bare
3337        // text with nothing naming the offending field (upstream #9616).
3338        let mut call_ids = HashMap::new();
3339        let outcome = parse_responses_event(
3340            &json!({
3341                "type": "error",
3342                "code": "invalid_value",
3343                "message": "Invalid value",
3344                "param": "tools[0].name",
3345            }),
3346            &mut call_ids,
3347            None,
3348        );
3349        let EventOutcome::Error(err) = outcome else {
3350            panic!("expected an error outcome");
3351        };
3352        let text = err.to_string();
3353        assert!(text.contains("invalid_value"), "missing code: {text}");
3354        assert!(text.contains("Invalid value"), "missing message: {text}");
3355        assert!(text.contains("tools[0].name"), "missing param: {text}");
3356    }
3357
3358    #[test]
3359    fn a_streamed_error_without_a_code_or_param_is_just_its_message() {
3360        // The common shape must not grow "None:" noise.
3361        let mut call_ids = HashMap::new();
3362        let outcome = parse_responses_event(
3363            &json!({ "type": "error", "message": "plain failure" }),
3364            &mut call_ids,
3365            None,
3366        );
3367        let EventOutcome::Error(err) = outcome else {
3368            panic!("expected an error outcome");
3369        };
3370        let text = err.to_string();
3371        assert!(text.contains("plain failure"), "{text}");
3372        assert!(!text.contains("None"), "no placeholder noise: {text}");
3373        assert!(
3374            !text.contains("parameter:"),
3375            "no empty param clause: {text}"
3376        );
3377    }
3378
3379    #[test]
3380    fn a_content_filter_block_keeps_its_classification_and_its_code() {
3381        // Enriching the message must not change how the error classifies.
3382        let mut call_ids = HashMap::new();
3383        let outcome = parse_responses_event(
3384            &json!({
3385                "type": "response.failed",
3386                "response": { "error": { "code": "content_filter", "message": "blocked" } }
3387            }),
3388            &mut call_ids,
3389            None,
3390        );
3391        let EventOutcome::Error(err) = outcome else {
3392            panic!("expected an error outcome");
3393        };
3394        assert!(matches!(err, Error::ServiceContentFilter { .. }));
3395        let text = err.to_string();
3396        assert!(text.contains("content_filter"), "{text}");
3397        assert!(text.contains("blocked"), "{text}");
3398    }
3399
3400    #[test]
3401    fn stream_failed_event_classifies_content_filter() {
3402        // Streamed and non-streamed Responses failures must classify alike
3403        // (mirrors `response_failure_error`).
3404        let mut call_ids = HashMap::new();
3405        let filtered = parse_responses_event(
3406            &json!({
3407                "type": "response.failed",
3408                "response": { "error": { "code": "content_filter", "message": "blocked" } }
3409            }),
3410            &mut call_ids,
3411            None,
3412        );
3413        let EventOutcome::Error(err) = filtered else {
3414            panic!("expected an error outcome");
3415        };
3416        assert!(matches!(err, Error::ServiceContentFilter { .. }));
3417
3418        let generic = parse_responses_event(
3419            &json!({
3420                "type": "response.failed",
3421                "response": { "error": { "code": "server_error", "message": "boom" } }
3422            }),
3423            &mut call_ids,
3424            None,
3425        );
3426        let EventOutcome::Error(err) = generic else {
3427            panic!("expected an error outcome");
3428        };
3429        assert!(matches!(err, Error::Service(_)));
3430    }
3431
3432    // endregion
3433
3434    // region: env-var constructor
3435
3436    /// Guards `OPENAI_API_KEY` / `OPENAI_BASE_URL` mutation: `cargo test` runs
3437    /// tests in the same process on multiple threads, and env vars are
3438    /// process-global, so concurrent set/remove across tests would be racy
3439    /// without serializing access.
3440    static ENV_MUTEX: std::sync::Mutex<()> = std::sync::Mutex::new(());
3441
3442    #[test]
3443    fn from_env_reads_api_key_and_base_url() {
3444        let _guard = ENV_MUTEX.lock().unwrap();
3445        // SAFETY: serialized by ENV_MUTEX against the other env-var test in
3446        // this module; no other test in this crate touches these variables.
3447        unsafe {
3448            std::env::set_var("OPENAI_API_KEY", "sk-test-123");
3449            std::env::set_var("OPENAI_BASE_URL", "https://example.test/v1");
3450        }
3451        let client = OpenAIChatClient::from_env("gpt-4o-mini").unwrap();
3452        assert_eq!(client.inner.api_key, "sk-test-123");
3453        assert_eq!(client.inner.base_url, "https://example.test/v1");
3454        unsafe {
3455            std::env::remove_var("OPENAI_API_KEY");
3456            std::env::remove_var("OPENAI_BASE_URL");
3457        }
3458    }
3459
3460    #[test]
3461    fn from_env_errors_when_api_key_missing() {
3462        let _guard = ENV_MUTEX.lock().unwrap();
3463        // SAFETY: serialized by ENV_MUTEX; see above.
3464        unsafe {
3465            std::env::remove_var("OPENAI_API_KEY");
3466            std::env::remove_var("OPENAI_BASE_URL");
3467        }
3468        let result = OpenAIChatClient::from_env("gpt-4o-mini");
3469        assert!(result.is_err());
3470    }
3471    #[test]
3472    fn build_body_maps_hosted_tools_to_responses_types() {
3473        use agent_framework_core::tools::{
3474            hosted_code_interpreter, hosted_file_search, hosted_mcp, hosted_web_search,
3475        };
3476        let c = client();
3477        let mut options = ChatOptions::new();
3478        options.tools = vec![
3479            hosted_web_search(),
3480            hosted_code_interpreter(),
3481            hosted_file_search(Some(7)),
3482            hosted_mcp(
3483                "docs",
3484                "https://mcp.example/sse",
3485                Some(vec!["search".into()]),
3486            ),
3487        ];
3488        let body = c.build_body(&[user("hi")], &options, false);
3489        let tools = body["tools"].as_array().unwrap();
3490        assert_eq!(tools[0], json!({ "type": "web_search" }));
3491        assert_eq!(
3492            tools[1],
3493            json!({ "type": "code_interpreter", "container": { "type": "auto" } })
3494        );
3495        assert_eq!(tools[2]["type"], "file_search");
3496        assert_eq!(tools[2]["max_num_results"], json!(7));
3497        assert_eq!(tools[3]["type"], "mcp");
3498        assert_eq!(tools[3]["server_url"], "https://mcp.example/sse");
3499        assert_eq!(tools[3]["allowed_tools"], json!(["search"]));
3500        assert_eq!(tools[3]["require_approval"], "never");
3501    }
3502
3503    // endregion
3504
3505    // region: multimodal input (Responses)
3506
3507    #[test]
3508    fn an_inline_document_is_named_for_its_type() {
3509        let docx = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
3510        let uri = format!("data:{docx};base64,UEs=");
3511        assert_eq!(
3512            content_to_input_part(&uri, Some(docx)).unwrap()["filename"],
3513            "file.docx"
3514        );
3515        let bin = "data:application/octet-stream;base64,AA==";
3516        assert_eq!(
3517            content_to_input_part(bin, Some("application/octet-stream")).unwrap()["filename"],
3518            "file"
3519        );
3520    }
3521
3522    #[test]
3523    fn a_text_file_is_sent_as_a_file() {
3524        assert_eq!(
3525            content_to_input_part("data:text/plain;base64,aGk=", Some("text/plain")),
3526            Some(
3527                json!({ "type": "input_file", "file_data": "data:text/plain;base64,aGk=", "filename": "file.txt" })
3528            )
3529        );
3530        assert_eq!(
3531            content_to_input_part("data:text/markdown;base64,Iw==", Some("text/markdown")).unwrap()
3532                ["filename"],
3533            "file.md"
3534        );
3535        assert_eq!(
3536            content_to_input_part("https://example.com/notes.csv", Some("text/csv")),
3537            Some(json!({ "type": "input_file", "file_url": "https://example.com/notes.csv" }))
3538        );
3539    }
3540
3541    #[test]
3542    fn a_consent_link_must_name_a_real_host() {
3543        assert!(is_https_url("https://login.example.com/consent?x=1"));
3544        assert!(is_https_url("HTTPS://login.example.com/consent"));
3545        for bad in [
3546            "https://user@/consent",
3547            "https://:443/consent",
3548            "https:///consent",
3549            "http://login.example.com/consent",
3550            "javascript:alert(1)",
3551            "not a url",
3552        ] {
3553            assert!(!is_https_url(bad), "{bad} accepted");
3554        }
3555    }
3556
3557    #[test]
3558    fn a_remote_file_uri_goes_by_file_url() {
3559        assert_eq!(
3560            content_to_input_part("https://example.com/report.pdf", Some("application/pdf")),
3561            Some(json!({ "type": "input_file", "file_url": "https://example.com/report.pdf" }))
3562        );
3563        assert_eq!(
3564            content_to_input_part("data:application/pdf;base64,JV", Some("application/pdf")),
3565            Some(
3566                json!({ "type": "input_file", "file_data": "data:application/pdf;base64,JV", "filename": "file.pdf" })
3567            )
3568        );
3569    }
3570
3571    #[test]
3572    fn input_image_uri_becomes_input_image_part() {
3573        let msg = user_with(vec![Content::Uri(UriContent {
3574            uri: "https://example.com/cat.png".into(),
3575            media_type: "image/png".into(),
3576        })]);
3577        let input = messages_to_input(&[msg]);
3578        assert_eq!(
3579            input[0],
3580            json!({ "type": "message", "role": "user", "content": [
3581                { "type": "input_image", "image_url": "https://example.com/cat.png", "detail": "auto" }
3582            ]})
3583        );
3584    }
3585
3586    #[test]
3587    fn input_audio_file_and_hosted_file_parts() {
3588        let msg = user_with(vec![
3589            Content::Data(DataContent {
3590                uri: "data:audio/wav;base64,QQ".into(),
3591                media_type: Some("audio/wav".into()),
3592            }),
3593            Content::Data(DataContent {
3594                uri: "data:application/pdf;base64,JV".into(),
3595                media_type: Some("application/pdf".into()),
3596            }),
3597            Content::HostedFile(HostedFileContent {
3598                file_id: "file-123".into(),
3599            }),
3600        ]);
3601        let input = messages_to_input(&[msg]);
3602        // `input_audio.data` is the raw base64 payload (data-URI prefix
3603        // stripped), the same wire rule as Chat Completions; file inputs keep
3604        // the full data URI in `file_data`.
3605        assert_eq!(
3606            input[0]["content"],
3607            json!([
3608                { "type": "input_audio", "input_audio": { "data": "QQ", "format": "wav" } },
3609                { "type": "input_file", "file_data": "data:application/pdf;base64,JV", "filename": "file.pdf" },
3610                { "type": "input_file", "file_id": "file-123" },
3611            ])
3612        );
3613    }
3614
3615    #[test]
3616    fn approval_response_becomes_mcp_approval_response_item() {
3617        let resp = FunctionApprovalResponseContent {
3618            approved: true,
3619            id: "appr_1".into(),
3620            function_call: FunctionCallContent::new("appr_1", "search", None),
3621        };
3622        let msg = user_with(vec![Content::FunctionApprovalResponse(resp)]);
3623        let input = messages_to_input(&[msg]);
3624        assert_eq!(
3625            input[0],
3626            json!({
3627                "type": "mcp_approval_response",
3628                "approval_request_id": "appr_1",
3629                "approve": true,
3630            })
3631        );
3632    }
3633
3634    #[test]
3635    fn approval_request_becomes_mcp_approval_request_item() {
3636        let req = FunctionApprovalRequestContent {
3637            id: "appr_1".into(),
3638            function_call: FunctionCallContent::new(
3639                "appr_1",
3640                "search",
3641                Some(FunctionArguments::Raw(r#"{"q":"x"}"#.into())),
3642            ),
3643        };
3644        let msg = Message::with_contents(
3645            Role::assistant(),
3646            vec![Content::FunctionApprovalRequest(req)],
3647        );
3648        let input = messages_to_input(&[msg]);
3649        assert_eq!(
3650            input[0],
3651            json!({
3652                "type": "mcp_approval_request",
3653                "id": "appr_1",
3654                "name": "search",
3655                "arguments": r#"{"q":"x"}"#,
3656            })
3657        );
3658    }
3659
3660    // endregion
3661
3662    // region: output parsing (annotations, code interpreter, images, approvals)
3663
3664    #[test]
3665    fn output_text_url_citation_annotation() {
3666        let contents = parse_item(json!({
3667            "type": "message", "role": "assistant", "content": [{
3668                "type": "output_text", "text": "See source.",
3669                "annotations": [{
3670                    "type": "url_citation", "title": "Src", "url": "https://ex.com",
3671                    "start_index": 0, "end_index": 3,
3672                }],
3673            }],
3674        }));
3675        let Content::Text(t) = &contents[0] else {
3676            panic!("expected text content");
3677        };
3678        let ann = t.annotations.as_ref().unwrap();
3679        assert_eq!(ann[0].title.as_deref(), Some("Src"));
3680        assert_eq!(ann[0].url.as_deref(), Some("https://ex.com"));
3681        let region = &ann[0].annotated_regions.as_ref().unwrap()[0];
3682        assert_eq!(region.start_index, Some(0));
3683        assert_eq!(region.end_index, Some(3));
3684    }
3685
3686    #[test]
3687    fn output_text_file_and_container_citations() {
3688        let contents = parse_item(json!({
3689            "type": "message", "role": "assistant", "content": [{
3690                "type": "output_text", "text": "x",
3691                "annotations": [
3692                    { "type": "file_citation", "filename": "doc.pdf", "file_id": "file-1", "index": 2 },
3693                    { "type": "file_path", "file_id": "file-2", "index": 0 },
3694                    { "type": "container_file_citation", "filename": "c.txt", "file_id": "file-3",
3695                      "container_id": "cont-1", "start_index": 1, "end_index": 4 },
3696                ],
3697            }],
3698        }));
3699        let Content::Text(t) = &contents[0] else {
3700            panic!("expected text content");
3701        };
3702        let ann = t.annotations.as_ref().unwrap();
3703        assert_eq!(ann[0].url.as_deref(), Some("doc.pdf"));
3704        assert_eq!(ann[0].file_id.as_deref(), Some("file-1"));
3705        assert_eq!(ann[1].file_id.as_deref(), Some("file-2"));
3706        assert_eq!(ann[2].file_id.as_deref(), Some("file-3"));
3707        assert_eq!(ann[2].url.as_deref(), Some("c.txt"));
3708        assert_eq!(
3709            ann[2].annotated_regions.as_ref().unwrap()[0].end_index,
3710            Some(4)
3711        );
3712    }
3713
3714    #[test]
3715    fn a_code_interpreter_run_is_a_hosted_call_and_result_not_answer_text() {
3716        // Its console output and source used to be flattened into ordinary
3717        // text, so they read as part of the model's answer.
3718        let contents = parse_item(json!({
3719            "type": "code_interpreter_call",
3720            "id": "ci_1",
3721            "code": "print('hello stdout')",
3722            "outputs": [
3723                { "type": "logs", "logs": "hello stdout" },
3724                { "type": "image", "url": "https://ex.com/plot.png" },
3725            ],
3726        }));
3727        assert!(
3728            contents.iter().all(|c| !matches!(c, Content::Text(_))),
3729            "{contents:?}"
3730        );
3731        let Content::CodeInterpreterToolCall(call) = &contents[0] else {
3732            panic!("expected the call first: {contents:?}");
3733        };
3734        assert_eq!(call.call_id.as_deref(), Some("ci_1"));
3735        assert!(
3736            matches!(&call.inputs.as_ref().unwrap()[0], Content::Text(t) if t.text == "print('hello stdout')")
3737        );
3738        let Content::CodeInterpreterToolResult(result) = &contents[1] else {
3739            panic!("expected the result second: {contents:?}");
3740        };
3741        let outputs = result.outputs.as_ref().unwrap();
3742        assert!(matches!(&outputs[0], Content::Text(t) if t.text == "hello stdout"));
3743        assert!(
3744            matches!(&outputs[1], Content::Uri(u) if u.uri == "https://ex.com/plot.png" && u.media_type == "image")
3745        );
3746    }
3747
3748    #[test]
3749    fn a_code_interpreter_run_with_no_outputs_still_reports_its_result() {
3750        let contents = parse_item(json!({
3751            "type": "code_interpreter_call", "call_id": "ci_2", "code": "x = 1",
3752        }));
3753        assert_eq!(contents.len(), 2);
3754        assert!(
3755            matches!(&contents[1], Content::CodeInterpreterToolResult(r) if r.outputs.as_deref() == Some(&[][..]))
3756        );
3757    }
3758
3759    #[test]
3760    fn a_streamed_code_interpreter_run_is_captured_from_output_item_done() {
3761        // The done item is the only streaming event that carries `outputs`
3762        // (upstream #9744); before this they were never seen while streaming.
3763        let mut call_ids = HashMap::new();
3764        let outcome = parse_responses_event(
3765            &json!({
3766                "type": "response.output_item.done",
3767                "item": {
3768                    "type": "code_interpreter_call", "id": "ci_3", "code": "1+1",
3769                    "outputs": [{ "type": "logs", "logs": "2" }]
3770                }
3771            }),
3772            &mut call_ids,
3773            None,
3774        );
3775        let EventOutcome::Update(update) = outcome else {
3776            panic!("expected an update");
3777        };
3778        assert!(matches!(
3779            &update.contents[0],
3780            Content::CodeInterpreterToolCall(_)
3781        ));
3782        let Content::CodeInterpreterToolResult(r) = &update.contents[1] else {
3783            panic!("{:?}", update.contents);
3784        };
3785        assert!(matches!(&r.outputs.as_ref().unwrap()[0], Content::Text(t) if t.text == "2"));
3786    }
3787
3788    #[test]
3789    fn image_generation_raw_base64_becomes_png_data() {
3790        let contents = parse_item(json!({
3791            "type": "image_generation_call", "result": "AAAABBBB",
3792        }));
3793        let Content::Data(d) = &contents[0] else {
3794            panic!("expected data content");
3795        };
3796        assert_eq!(d.uri, "data:image/png;base64,AAAABBBB");
3797        assert_eq!(d.media_type.as_deref(), Some("image/png"));
3798    }
3799
3800    #[test]
3801    fn image_generation_data_uri_keeps_stated_media_type() {
3802        let contents = parse_item(json!({
3803            "type": "image_generation_call", "result": "data:image/webp;base64,ZZZ",
3804        }));
3805        let Content::Data(d) = &contents[0] else {
3806            panic!("expected data content");
3807        };
3808        assert_eq!(d.uri, "data:image/webp;base64,ZZZ");
3809        assert_eq!(d.media_type.as_deref(), Some("image/webp"));
3810    }
3811
3812    #[test]
3813    fn mcp_approval_request_output_round_trips_into_response() {
3814        let contents = parse_item(json!({
3815            "type": "mcp_approval_request",
3816            "id": "appr_9", "name": "search", "arguments": r#"{"q":"rust"}"#,
3817            "server_label": "docs",
3818        }));
3819        let Content::FunctionApprovalRequest(req) = &contents[0] else {
3820            panic!("expected approval request");
3821        };
3822        assert_eq!(req.id, "appr_9");
3823        assert_eq!(req.function_call.call_id, "appr_9");
3824        assert_eq!(req.function_call.name, "search");
3825
3826        // The id round-trips into the request's response item (item 5).
3827        let msg = user_with(vec![Content::FunctionApprovalResponse(
3828            req.create_response(true),
3829        )]);
3830        let input = messages_to_input(&[msg]);
3831        assert_eq!(input[0]["type"], json!("mcp_approval_response"));
3832        assert_eq!(input[0]["approval_request_id"], json!("appr_9"));
3833        assert_eq!(input[0]["approve"], json!(true));
3834    }
3835
3836    #[test]
3837    fn mcp_call_output_item_parses_into_call_and_result() {
3838        let contents = parse_item(json!({
3839            "type": "mcp_call", "id": "mcp_1", "name": "search",
3840            "server_label": "docs", "arguments": r#"{"q":"rust"}"#,
3841            "output": "found it",
3842        }));
3843        let [Content::McpServerToolCall(call), Content::McpServerToolResult(result)] =
3844            contents.as_slice()
3845        else {
3846            panic!("expected hosted call and result, got {contents:?}");
3847        };
3848        assert_eq!(call.call_id, "mcp_1");
3849        assert_eq!(call.tool_name, "search");
3850        assert_eq!(call.server_name.as_deref(), Some("docs"));
3851        assert_eq!(result.call_id, "mcp_1");
3852        assert_eq!(result.output, Some(json!("found it")));
3853    }
3854
3855    /// A hosted approval replayed from local history carries the completed
3856    /// `mcp_call` after its request/response pair, so the service sees the
3857    /// approved call as already run instead of an approval still to act on.
3858    #[test]
3859    fn replayed_hosted_approval_carries_its_completed_mcp_call() {
3860        let request = parse_item(json!({
3861            "type": "mcp_approval_request",
3862            "id": "appr_9", "name": "search", "arguments": r#"{"q":"rust"}"#,
3863            "server_label": "docs",
3864        }));
3865        let Content::FunctionApprovalRequest(req) = &request[0] else {
3866            panic!("expected approval request");
3867        };
3868        let response = req.create_response(true);
3869        let completed = parse_item(json!({
3870            "type": "mcp_call", "id": "mcp_1", "approval_request_id": "appr_9",
3871            "name": "search", "server_label": "docs",
3872            "arguments": r#"{"q":"rust"}"#, "output": "found it",
3873        }));
3874        let history = vec![
3875            Message::with_contents(Role::assistant(), request),
3876            user_with(vec![Content::FunctionApprovalResponse(response)]),
3877            Message::with_contents(Role::assistant(), completed),
3878            user("and now?"),
3879        ];
3880        let input = messages_to_input(&history);
3881        let types: Vec<_> = input.iter().map(|i| i["type"].clone()).collect();
3882        assert_eq!(
3883            types,
3884            vec![
3885                json!("mcp_approval_request"),
3886                json!("mcp_approval_response"),
3887                json!("mcp_call"),
3888                json!("message"),
3889            ]
3890        );
3891        assert_eq!(input[2]["id"], json!("mcp_1"));
3892        assert_eq!(input[2]["server_label"], json!("docs"));
3893        assert_eq!(input[2]["name"], json!("search"));
3894        assert_eq!(input[2]["arguments"], json!(r#"{"q":"rust"}"#));
3895        assert_eq!(input[2]["output"], json!("found it"));
3896        assert_eq!(input[2]["approval_request_id"], json!("appr_9"));
3897    }
3898
3899    #[test]
3900    fn orphan_mcp_result_is_dropped_from_input() {
3901        let input = messages_to_input(&[Message::with_contents(
3902            Role::assistant(),
3903            vec![Content::McpServerToolResult(McpServerToolResultContent {
3904                call_id: "mcp_missing".into(),
3905                output: Some(json!("x")),
3906                error: None,
3907            })],
3908        )]);
3909        assert!(input.is_empty(), "{input:?}");
3910    }
3911
3912    /// A streamed `mcp_call` starts with empty arguments on `added`; the
3913    /// final arguments only arrive on the completed item, so the call is
3914    /// recorded from `done` and replays with them rather than `{}`.
3915    #[test]
3916    fn streamed_mcp_call_records_the_completed_arguments() {
3917        let mut ids = HashMap::new();
3918        let added = parse_responses_event(
3919            &json!({"type": "response.output_item.added", "output_index": 0, "item": {
3920                "type": "mcp_call", "id": "mcp_2", "name": "search",
3921                "server_label": "docs", "arguments": "",
3922            }}),
3923            &mut ids,
3924            None,
3925        );
3926        assert!(matches!(added, EventOutcome::None));
3927        for event in [
3928            json!({"type": "response.mcp_call_arguments.delta", "output_index": 0,
3929                   "item_id": "mcp_2", "delta": "{\"q\":"}),
3930            json!({"type": "response.mcp_call_arguments.done", "output_index": 0,
3931                   "item_id": "mcp_2", "arguments": "{\"q\":\"rust\"}"}),
3932        ] {
3933            assert!(matches!(
3934                parse_responses_event(&event, &mut ids, None),
3935                EventOutcome::None
3936            ));
3937        }
3938        let EventOutcome::Update(done) = parse_responses_event(
3939            &json!({"type": "response.output_item.done", "output_index": 0, "item": {
3940                "type": "mcp_call", "id": "mcp_2", "name": "search",
3941                "server_label": "docs", "arguments": "{\"q\":\"rust\"}", "output": "ok",
3942                "approval_request_id": "appr_2",
3943            }}),
3944            &mut ids,
3945            None,
3946        ) else {
3947            panic!("expected an update on done");
3948        };
3949        let response = ChatResponse::from_updates(vec![done]);
3950        let input = messages_to_input(&response.messages);
3951        assert_eq!(
3952            input,
3953            vec![json!({
3954                "type": "mcp_call", "id": "mcp_2", "server_label": "docs",
3955                "name": "search", "arguments": "{\"q\":\"rust\"}", "output": "ok",
3956                "approval_request_id": "appr_2",
3957            })]
3958        );
3959    }
3960
3961    /// A turn continuing a stored response (`previous_response_id`) with the
3962    /// local history provider still attached must not re-send items the
3963    /// service already holds by their server-issued `id` (hosted `mcp_call`,
3964    /// `mcp_approval_request`, reasoning): OpenAI rejects them as duplicates.
3965    /// The new approval response and the text still go out; a stateless
3966    /// request keeps replaying everything.
3967    #[test]
3968    fn continuation_request_does_not_resend_stored_hosted_items() {
3969        let mut assistant = vec![
3970            Content::TextReasoning(TextReasoningContent {
3971                text: String::new(),
3972                annotations: None,
3973                raw_representation: Some(json!({
3974                    "type": "reasoning", "id": "rs_1", "summary": [],
3975                })),
3976                protected_data: None,
3977            }),
3978            Content::FunctionApprovalRequest(FunctionApprovalRequestContent {
3979                id: "mcpr_1".into(),
3980                function_call: FunctionCallContent::new(
3981                    "mcpr_1",
3982                    "search",
3983                    Some(FunctionArguments::Raw("{}".into())),
3984                ),
3985            }),
3986        ];
3987        assistant.extend(mcp_call_item_contents(&json!({
3988            "type": "mcp_call", "id": "mcp_1", "name": "search",
3989            "server_label": "docs", "arguments": "{}", "output": "ok",
3990        })));
3991        assistant.push(Content::text("done"));
3992        let history = vec![
3993            user("find it"),
3994            Message::with_contents(Role::assistant(), assistant),
3995            user_with(vec![Content::FunctionApprovalResponse(
3996                FunctionApprovalResponseContent {
3997                    approved: true,
3998                    id: "mcpr_2".into(),
3999                    function_call: FunctionCallContent::new("mcpr_2", "search", None),
4000                },
4001            )]),
4002        ];
4003        let types = |body: &Value| -> Vec<String> {
4004            body["input"]
4005                .as_array()
4006                .unwrap()
4007                .iter()
4008                .map(|item| item["type"].as_str().unwrap_or("message").to_string())
4009                .collect()
4010        };
4011
4012        let c = client();
4013        let mut options = ChatOptions::new();
4014        options.conversation_id = Some("resp_1".into());
4015        let body = c.build_body(&history, &options, false);
4016        assert_eq!(body["previous_response_id"], json!("resp_1"));
4017        assert_eq!(
4018            types(&body),
4019            ["message", "message", "mcp_approval_response"],
4020            "{body}"
4021        );
4022
4023        let body = c.build_body(&history, &ChatOptions::new(), false);
4024        assert_eq!(
4025            types(&body),
4026            [
4027                "message",
4028                "reasoning",
4029                "mcp_approval_request",
4030                "mcp_call",
4031                "message",
4032                "mcp_approval_response",
4033            ],
4034            "{body}"
4035        );
4036    }
4037
4038    /// An `mcp_call` that failed carries an `error` and no `output`; the
4039    /// error is kept and replayed, so the call does not look unfinished.
4040    #[test]
4041    fn failed_mcp_call_replays_its_error() {
4042        let item = json!({
4043            "type": "mcp_call", "id": "mcp_3", "name": "search",
4044            "server_label": "docs", "arguments": "{}",
4045            "status": "failed", "error": "server unreachable",
4046        });
4047        let contents = mcp_call_item_contents(&item);
4048        let [Content::McpServerToolCall(_), Content::McpServerToolResult(result)] =
4049            contents.as_slice()
4050        else {
4051            panic!("expected call + result, got {contents:?}");
4052        };
4053        assert_eq!(result.output, None);
4054        assert_eq!(result.error, Some(json!("server unreachable")));
4055        let input = messages_to_input(&[Message::with_contents(Role::assistant(), contents)]);
4056        assert_eq!(
4057            input,
4058            vec![json!({
4059                "type": "mcp_call", "id": "mcp_3", "server_label": "docs",
4060                "name": "search", "arguments": "{}", "error": "server unreachable",
4061            })]
4062        );
4063    }
4064
4065    // endregion
4066
4067    // region: streaming reasoning
4068
4069    fn reasoning_event(value: Value) -> EventOutcome {
4070        let mut ids = HashMap::new();
4071        parse_responses_event(&value, &mut ids, None)
4072    }
4073
4074    #[test]
4075    fn a_replayed_refusal_becomes_a_refusal_content_part() {
4076        // Beside `output_text` in an output message, a refusal has its own
4077        // part type. Re-emitting it as `output_text` replays a decline to the
4078        // provider as an answer.
4079        let input = messages_to_input(&[Message::with_contents(
4080            Role::assistant(),
4081            vec![
4082                Content::Text(TextContent::new("here is half")),
4083                Content::Text(TextContent::refusal("I can't do the rest")),
4084            ],
4085        )]);
4086        let content = &input[0]["content"];
4087        assert_eq!(
4088            content[0],
4089            json!({"type": "output_text", "text": "here is half"})
4090        );
4091        assert_eq!(
4092            content[1],
4093            json!({"type": "refusal", "refusal": "I can't do the rest"})
4094        );
4095    }
4096
4097    #[test]
4098    fn a_refusal_on_a_non_assistant_role_is_dropped_rather_than_mis_encoded() {
4099        // An *input* message's content list admits only
4100        // input_text/input_image/input_file — there is no refusal part — so
4101        // emitting one would be rejected by the API. Dropping it is the only
4102        // correct option, and it cannot arise from a parsed provider response
4103        // anyway (refusals are assistant output).
4104        let input = messages_to_input(&[Message::with_contents(
4105            Role::user(),
4106            vec![
4107                Content::Text(TextContent::new("hello")),
4108                Content::Text(TextContent::refusal("stray")),
4109            ],
4110        )]);
4111        let content = &input[0]["content"];
4112        assert_eq!(content.as_array().map(Vec::len), Some(1));
4113        assert_eq!(content[0], json!({"type": "input_text", "text": "hello"}));
4114    }
4115
4116    #[test]
4117    fn a_streamed_refusal_is_marked_and_its_done_event_is_not_duplicated() {
4118        // Before this, `response.refusal.delta` fell through the catch-all
4119        // and a streamed decline reached the caller as an empty response —
4120        // the non-streaming path marked refusals while the streaming path
4121        // dropped them.
4122        let EventOutcome::Update(delta) =
4123            reasoning_event(json!({ "type": "response.refusal.delta", "delta": "I can't" }))
4124        else {
4125            panic!("expected update");
4126        };
4127        assert!(matches!(&delta.contents[0], Content::Text(t) if t.refusal && t.text == "I can't"));
4128
4129        // `.done` repeats the whole refusal; emitting it would double the
4130        // text already streamed, exactly as for the text channel.
4131        let done =
4132            reasoning_event(json!({ "type": "response.refusal.done", "refusal": "I can't help" }));
4133        assert!(matches!(done, EventOutcome::None));
4134    }
4135
4136    // region: Foundry oauth consent
4137
4138    #[test]
4139    fn a_completed_response_surfaces_its_oauth_consent_request() {
4140        // A Foundry hosted tool that needs consent finishes the turn with
4141        // an `oauth_consent_request` output item and no text. Ignored, the
4142        // run came back as an empty answer and the caller had no way to
4143        // learn what it was waiting for (upstream #8976).
4144        let value = json!({
4145            "id": "resp_1",
4146            "status": "completed",
4147            "output": [
4148                {
4149                    "type": "oauth_consent_request",
4150                    "id": "oauth_7",
4151                    "consent_link": "https://login.example.com/consent?state=abc",
4152                }
4153            ],
4154        });
4155        let resp = parse_response(&value, None);
4156        let Content::OauthConsentRequest(consent) = &resp.messages[0].contents[0] else {
4157            panic!(
4158                "expected a consent request, got {:?}",
4159                resp.messages[0].contents
4160            );
4161        };
4162        assert_eq!(
4163            consent.consent_link,
4164            "https://login.example.com/consent?state=abc"
4165        );
4166        // The id is what a workflow registers the request under, so the
4167        // user's answer has something to correlate against.
4168        assert_eq!(consent.id.as_deref(), Some("oauth_7"));
4169    }
4170
4171    #[test]
4172    fn a_streamed_oauth_consent_request_is_emitted_when_the_item_is_added() {
4173        // It has no deltas to wait for and the run is blocked on the user
4174        // until it is answered, so it is emitted on `added` rather than
4175        // held back to `done` like a hosted MCP call.
4176        let EventOutcome::Update(update) = reasoning_event(json!({
4177            "type": "response.output_item.added",
4178            "output_index": 0,
4179            "item": {
4180                "type": "oauth_consent_request",
4181                "id": "oauth_7",
4182                "consent_link": "https://login.example.com/consent",
4183            },
4184        })) else {
4185            panic!("expected an update");
4186        };
4187        assert!(matches!(
4188            &update.contents[0],
4189            Content::OauthConsentRequest(c)
4190                if c.consent_link == "https://login.example.com/consent"
4191                    && c.id.as_deref() == Some("oauth_7")
4192        ));
4193    }
4194
4195    #[test]
4196    fn a_top_level_oauth_consent_event_carries_the_same_content() {
4197        // Foundry also emits the request as a top-level event with the link
4198        // on the event itself rather than on an output item.
4199        let EventOutcome::Update(update) = reasoning_event(json!({
4200            "type": "response.oauth_consent_requested",
4201            "id": "oauth_9",
4202            "consent_link": "https://login.example.com/consent",
4203        })) else {
4204            panic!("expected an update");
4205        };
4206        assert!(matches!(
4207            &update.contents[0],
4208            Content::OauthConsentRequest(c) if c.id.as_deref() == Some("oauth_9")
4209        ));
4210    }
4211
4212    #[test]
4213    fn an_untrustworthy_consent_link_is_dropped_rather_than_surfaced() {
4214        // The framework is asking a human to open this URL and
4215        // authenticate at it, and it arrives from the service as free-form
4216        // text. Anything that is not https with a host is dropped.
4217        for link in [
4218            json!("http://login.example.com/consent"),
4219            json!("javascript:alert(1)"),
4220            json!("https:///no-host"),
4221            json!(""),
4222            Value::Null,
4223        ] {
4224            let value = json!({
4225                "id": "resp_1",
4226                "status": "completed",
4227                "output": [
4228                    { "type": "oauth_consent_request", "id": "oauth_7", "consent_link": link }
4229                ],
4230            });
4231            let resp = parse_response(&value, None);
4232            let found = resp
4233                .messages
4234                .iter()
4235                .flat_map(|m| &m.contents)
4236                .any(|c| matches!(c, Content::OauthConsentRequest(_)));
4237            assert!(!found, "accepted consent_link {link:?}");
4238        }
4239
4240        // The scheme is case-insensitive, so an upper-case one is accepted.
4241        let value = json!({
4242            "id": "resp_1",
4243            "status": "completed",
4244            "output": [
4245                {
4246                    "type": "oauth_consent_request",
4247                    "consent_link": "HTTPS://login.example.com/consent",
4248                }
4249            ],
4250        });
4251        let resp = parse_response(&value, None);
4252        let Content::OauthConsentRequest(consent) = &resp.messages[0].contents[0] else {
4253            panic!("expected a consent request");
4254        };
4255        // No `id` on the item: the content carries none rather than an
4256        // empty string that would correlate against nothing.
4257        assert_eq!(consent.id, None);
4258    }
4259
4260    // endregion
4261
4262    #[test]
4263    fn reasoning_text_delta_streams_and_done_is_terminal_metadata() {
4264        let EventOutcome::Update(delta) =
4265            reasoning_event(json!({ "type": "response.reasoning_text.delta", "delta": "Th" }))
4266        else {
4267            panic!("expected update");
4268        };
4269        assert!(matches!(&delta.contents[0], Content::TextReasoning(t) if t.text == "Th"));
4270
4271        // `.done` carries the full text the deltas already streamed — emitting
4272        // it again would duplicate the reasoning in the aggregate.
4273        let done =
4274            reasoning_event(json!({ "type": "response.reasoning_text.done", "text": "Think" }));
4275        assert!(matches!(done, EventOutcome::None));
4276    }
4277
4278    #[test]
4279    fn reasoning_summary_text_events_map_to_reasoning_content() {
4280        let EventOutcome::Update(delta) = reasoning_event(
4281            json!({ "type": "response.reasoning_summary_text.delta", "delta": "sum" }),
4282        ) else {
4283            panic!("expected update");
4284        };
4285        assert!(matches!(&delta.contents[0], Content::TextReasoning(t) if t.text == "sum"));
4286
4287        let done = reasoning_event(
4288            json!({ "type": "response.reasoning_summary_text.done", "text": "summary" }),
4289        );
4290        assert!(matches!(done, EventOutcome::None));
4291    }
4292
4293    #[test]
4294    fn response_failure_error_classifies_content_filter() {
4295        let filtered = json!({
4296            "status": "failed",
4297            "error": { "code": "content_filter", "message": "blocked" }
4298        });
4299        assert!(matches!(
4300            response_failure_error(&filtered),
4301            Some(Error::ServiceContentFilter { .. })
4302        ));
4303
4304        let generic = json!({
4305            "status": "failed",
4306            "error": { "code": "server_error", "message": "boom" }
4307        });
4308        assert!(matches!(
4309            response_failure_error(&generic),
4310            Some(Error::Service(_))
4311        ));
4312
4313        assert!(response_failure_error(&json!({ "status": "completed" })).is_none());
4314    }
4315
4316    #[test]
4317    fn input_audio_data_strips_data_uri_prefix() {
4318        let part = content_to_input_part("data:audio/wav;base64,QUJD", Some("audio/wav"))
4319            .expect("audio part");
4320        assert_eq!(part["input_audio"]["data"], "QUJD");
4321        assert_eq!(part["input_audio"]["format"], "wav");
4322    }
4323
4324    // endregion
4325
4326    // region: hosted-tool config passthrough
4327
4328    fn hosted(kind: ToolKind, name: &str, params: Value) -> ToolDefinition {
4329        ToolDefinition {
4330            name: name.into(),
4331            description: String::new(),
4332            parameters: params,
4333            kind,
4334            approval_mode: ApprovalMode::NeverRequire,
4335            executor: None,
4336        }
4337    }
4338
4339    #[test]
4340    fn web_search_passes_through_user_location() {
4341        let tool = hosted(
4342            ToolKind::HostedWebSearch,
4343            "web_search",
4344            json!({ "user_location": { "city": "Paris", "country": "FR" } }),
4345        );
4346        assert_eq!(
4347            tool_to_responses_spec(&tool),
4348            json!({
4349                "type": "web_search",
4350                "user_location": { "type": "approximate", "city": "Paris", "country": "FR" },
4351            })
4352        );
4353    }
4354
4355    #[test]
4356    fn file_search_passes_vector_store_ids_and_max_results_param() {
4357        let tool = hosted(
4358            ToolKind::HostedFileSearch { max_results: None },
4359            "file_search",
4360            json!({ "vector_store_ids": ["vs_1"], "max_results": 12 }),
4361        );
4362        let spec = tool_to_responses_spec(&tool);
4363        assert_eq!(spec["vector_store_ids"], json!(["vs_1"]));
4364        assert_eq!(spec["max_num_results"], json!(12));
4365    }
4366
4367    #[test]
4368    fn image_generation_maps_to_responses_tool_with_passthrough_params() {
4369        let tool = hosted(
4370            ToolKind::HostedImageGeneration,
4371            "image_generation",
4372            json!({ "size": "1024x1024", "quality": "high" }),
4373        );
4374        let spec = tool_to_responses_spec(&tool);
4375        assert_eq!(spec["type"], json!("image_generation"));
4376        assert_eq!(spec["size"], json!("1024x1024"));
4377        assert_eq!(spec["quality"], json!("high"));
4378    }
4379
4380    #[test]
4381    fn code_interpreter_passes_file_ids_and_container_override() {
4382        let with_files = hosted(
4383            ToolKind::HostedCodeInterpreter,
4384            "ci",
4385            json!({ "file_ids": ["file-1", "file-2"] }),
4386        );
4387        assert_eq!(
4388            tool_to_responses_spec(&with_files)["container"],
4389            json!({ "type": "auto", "file_ids": ["file-1", "file-2"] })
4390        );
4391        let with_container = hosted(
4392            ToolKind::HostedCodeInterpreter,
4393            "ci",
4394            json!({ "container": { "type": "secure", "id": "c1" } }),
4395        );
4396        assert_eq!(
4397            tool_to_responses_spec(&with_container)["container"],
4398            json!({ "type": "secure", "id": "c1" })
4399        );
4400    }
4401
4402    #[test]
4403    fn mcp_passes_headers_and_string_approval_mode_override() {
4404        let tool = hosted(
4405            ToolKind::HostedMcp {
4406                url: "https://mcp/sse".into(),
4407                allowed_tools: None,
4408            },
4409            "docs",
4410            json!({ "headers": { "Authorization": "Bearer x" }, "approval_mode": "always_require" }),
4411        );
4412        // The enum default is NeverRequire; the parameter overrides it.
4413        let spec = tool_to_responses_spec(&tool);
4414        assert_eq!(spec["headers"], json!({ "Authorization": "Bearer x" }));
4415        assert_eq!(spec["require_approval"], json!("always"));
4416    }
4417
4418    #[test]
4419    fn mcp_object_approval_mode_maps_to_tool_name_lists() {
4420        let tool = hosted(
4421            ToolKind::HostedMcp {
4422                url: "https://mcp/sse".into(),
4423                allowed_tools: None,
4424            },
4425            "docs",
4426            json!({ "approval_mode": { "always": ["delete"], "never": ["read"] } }),
4427        );
4428        assert_eq!(
4429            tool_to_responses_spec(&tool)["require_approval"],
4430            json!({ "always": { "tool_names": ["delete"] }, "never": { "tool_names": ["read"] } })
4431        );
4432    }
4433
4434    // endregion
4435}