Skip to main content

rig_core/providers/openai/responses_api/
streaming.rs

1//! Responses frame classification and event decoding: one block per output
2//! item, in the order the items arrive, each holding the item as the
3//! provider stated it complete.
4//!
5//! Frames are read as JSON and classified by their `type` alone, and every
6//! field is read leniently, so a gateway that omits or retypes a field no
7//! block or finish needs never fails a reply.
8//!
9//! ```
10//! use rig_core::providers::openai::responses_api::streaming::ResponsesDecoder;
11//! let decoder = ResponsesDecoder::new();
12//! # let _ = decoder;
13//! ```
14
15use std::borrow::Cow;
16use std::collections::{HashMap, HashSet};
17
18use serde_json::{Value, json};
19
20use crate::completion::{FinishReason, Usage};
21use crate::error::ProviderError;
22use crate::json_utils::Lenient;
23use crate::json_utils::remove_preserving_order;
24use crate::message::{Source, SourceLocation};
25use crate::operation::{Block, CallFragment, Completion, Finish};
26use crate::providers::internal::wire;
27use crate::providers::openai::wire::chat::reported;
28use crate::wire::{Decoder, Flow, Out, WireCitation, WireEvent, WireFrame};
29
30/// Whether `kind` is a Responses event type this decoder reads. A frame of
31/// any other type passes through as unknown. `keepalive` is ChatGPT's idle
32/// heartbeat, read and skipped.
33fn is_known_responses_event_type(kind: &str) -> bool {
34    matches!(kind, "error" | "keepalive")
35        || is_lifecycle_event(kind)
36        || matches!(
37            kind.strip_prefix("response."),
38            Some(
39                "output_item.added"
40                    | "output_item.done"
41                    | "content_part.added"
42                    | "content_part.done"
43                    | "output_text.delta"
44                    | "output_text.done"
45                    | "refusal.delta"
46                    | "refusal.done"
47                    | "function_call_arguments.delta"
48                    | "function_call_arguments.done"
49                    | "custom_tool_call_input.delta"
50                    | "custom_tool_call_input.done"
51                    | "reasoning_summary_part.added"
52                    | "reasoning_summary_part.done"
53                    | "reasoning_summary_text.delta"
54                    | "reasoning_summary_text.done"
55                    | "reasoning_text.delta"
56                    | "reasoning_text.done"
57            )
58        )
59}
60
61/// Whether `kind` is a response lifecycle event, which carries the response
62/// object under `response`.
63pub(crate) fn is_lifecycle_event(kind: &str) -> bool {
64    matches!(
65        kind.strip_prefix("response."),
66        Some("created" | "queued" | "in_progress" | "completed" | "failed" | "incomplete")
67    )
68}
69
70/// A classified Responses payload.
71#[derive(Debug)]
72pub enum ResponsesEvent {
73    /// A stream event of a known `type`, as the provider sent it.
74    Frame {
75        /// The event's `type`.
76        kind: String,
77        /// The event.
78        frame: Value,
79        /// The payload of a `response.failed` event, verbatim, for the
80        /// error the failed reply reports; `None` for every other event.
81        raw: Option<String>,
82    },
83    /// The unary reply: the response object itself, which carries no `type`
84    /// because it is not an event.
85    Whole(Value),
86    /// The provider's error, as the stream's `error` event or a success
87    /// body holding an error envelope instead of a response.
88    Failure(String),
89    /// The `[DONE]` sentinel. The provider's end is `response.completed`.
90    Sentinel,
91}
92
93/// The keys a response object, or the error envelope a success body can
94/// hold instead, always has one of.
95const WHOLE_BODY_MARKERS: &[&str] = &["object", "output", "status", "id", "error"];
96
97/// A payload that names its `type`, read as the JSON it is.
98struct Tagged(Value);
99
100impl<'de> serde::Deserialize<'de> for Tagged {
101    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
102    where
103        D: serde::Deserializer<'de>,
104    {
105        let value = Value::deserialize(deserializer)?;
106        if value.str("type").is_some() {
107            Ok(Self(value))
108        } else {
109            Err(serde::de::Error::custom("the payload names no `type`"))
110        }
111    }
112}
113
114/// Classify one payload by its `type`; a payload without one is the unary
115/// response object or an error envelope.
116pub fn classify_responses_payload(data: &str) -> WireEvent<ResponsesEvent> {
117    if data.trim() == "[DONE]" {
118        return WireEvent::Known(ResponsesEvent::Sentinel);
119    }
120    wire::classify_or_untagged(
121        data,
122        "type",
123        is_known_responses_event_type,
124        |Tagged(frame)| match frame.str("type") {
125            Some("error") => ResponsesEvent::Failure(data.to_owned()),
126            kind => ResponsesEvent::Frame {
127                raw: (kind == Some("response.failed")).then(|| data.to_owned()),
128                kind: kind.unwrap_or_default().to_owned(),
129                frame,
130            },
131        },
132        |data| {
133            wire::classify_marker_keyed_frame::<Value>(data, WHOLE_BODY_MARKERS).map(|body| {
134                let error = body.get("error").is_some_and(|error| !error.is_null());
135                if error && body.get("output").is_none() && body.get("status").is_none() {
136                    ResponsesEvent::Failure(data.to_owned())
137                } else {
138                    ResponsesEvent::Whole(body)
139                }
140            })
141        },
142    )
143}
144
145/// What an output item becomes.
146#[derive(Clone, Copy, PartialEq, Eq, Debug)]
147enum Kind {
148    Message,
149    Reasoning,
150    Call,
151    Opaque,
152}
153
154impl Kind {
155    fn of(item: &Value) -> Self {
156        match item.str("type") {
157            Some("message") => Self::Message,
158            Some("reasoning") => Self::Reasoning,
159            Some("function_call" | "custom_tool_call") => Self::Call,
160            _ => Self::Opaque,
161        }
162    }
163}
164
165/// One output item of the reply, as the decoder saw it.
166struct Slot {
167    /// The writer index its block opened at.
168    at: usize,
169    kind: Kind,
170    /// The item id it states.
171    id: Option<String>,
172    open: bool,
173    /// The text its deltas wrote, and the field and part that last
174    /// extended it: a new part of reasoning starts a paragraph, and a second
175    /// field restating the same reasoning is not appended.
176    text: String,
177    field: Option<&'static str>,
178    part: u64,
179    /// A call's streamed argument text, or a custom call's input.
180    arguments: String,
181    custom: bool,
182    /// Whether the call's id was stated.
183    named: bool,
184    /// Whether the call's tool name was stated.
185    titled: bool,
186}
187
188/// The item types the client executes, which nothing in rig answers: they
189/// are kept in history and never sent back.
190const CLIENT_EXECUTED: &[&str] = &[
191    "computer_call",
192    "local_shell_call",
193    "shell_call",
194    "apply_patch_call",
195    "mcp_approval_request",
196];
197
198fn item_id(item: &Value) -> Option<&str> {
199    item.str("id").filter(|id| !id.is_empty())
200}
201
202/// The argument JSON a done call states: a function call's `arguments`, a
203/// custom call's `input` as `{"input": ...}`; `None` when it states none.
204fn arguments_of(item: &Value) -> Option<String> {
205    if item.str("type") == Some("custom_tool_call") {
206        return item
207            .str("input")
208            .map(|input| json!({ "input": input }).to_string());
209    }
210    match item.get("arguments")? {
211        Value::String(arguments) if arguments.is_empty() => None,
212        Value::String(arguments) => Some(arguments.clone()),
213        Value::Null => None,
214        arguments => Some(arguments.to_string()),
215    }
216}
217
218/// The text a done item states: a message's parts joined, refusals
219/// included; reasoning's summary, or its raw content when it has none.
220fn text_of(item: &Value) -> String {
221    let texts = |key: &str| -> Vec<&str> {
222        match item.get(key) {
223            Some(Value::String(text)) => vec![text.as_str()],
224            _ => item
225                .arr(key)
226                .iter()
227                .filter_map(|part| {
228                    part.as_str()
229                        .or_else(|| part.str("text"))
230                        .or_else(|| part.str("refusal"))
231                })
232                .collect(),
233        }
234    };
235    match Kind::of(item) {
236        Kind::Message => texts("content").concat(),
237        Kind::Reasoning => Some(texts("summary"))
238            .filter(|summary| !summary.is_empty())
239            .unwrap_or_else(|| texts("content"))
240            .join("\n\n"),
241        Kind::Call | Kind::Opaque => String::new(),
242    }
243}
244
245/// `item`, a done item that states no text, stating `text`, so the item
246/// replays as the block it is.
247fn stating(mut item: Value, kind: Kind, text: &str) -> Value {
248    let (key, part) = match kind {
249        Kind::Message => (
250            "content",
251            json!({"type": "output_text", "text": text, "annotations": []}),
252        ),
253        _ => ("summary", json!({"type": "summary_text", "text": text})),
254    };
255    if let Some(fields) = item.as_object_mut() {
256        fields.insert(key.to_owned(), json!([part]));
257    }
258    item
259}
260
261/// The provider's own words for a failed or cancelled response.
262fn provider_message(response: &Value, fallback: &str) -> String {
263    let parts: Vec<&str> = ["/error/code", "/error/message"]
264        .iter()
265        .filter_map(|pointer| response.at(pointer).and_then(Value::as_str))
266        .collect();
267    if parts.is_empty() {
268        fallback.to_owned()
269    } else {
270        parts.join(": ")
271    }
272}
273
274/// How the turn ended, for every status the API documents. A response
275/// without a status ended with a stop. A status that is
276/// not a documented end, including one still `queued` or `in_progress`, is
277/// a failed turn.
278pub(crate) fn finish_reason_of(response: &Value) -> (FinishReason, Option<String>) {
279    let reason = response
280        .at("/incomplete_details/reason")
281        .and_then(Value::as_str)
282        .filter(|reason| !reason.is_empty());
283    let other = |reason: &str, error: String| (FinishReason::Other(reason.to_owned()), Some(error));
284    match response.str("status") {
285        None | Some("completed") => (FinishReason::Stop, None),
286        Some("incomplete") => match reason {
287            Some("max_output_tokens") => (FinishReason::Length, None),
288            Some("content_filter") => (FinishReason::ContentFilter, None),
289            Some(reason) => other(
290                &format!("incomplete: {reason}"),
291                format!("Response incomplete: {reason}"),
292            ),
293            None => other(
294                "incomplete",
295                "Response incomplete without a provider reason".to_owned(),
296            ),
297        },
298        Some(status @ ("failed" | "cancelled")) => other(
299            status,
300            provider_message(response, &format!("Response {status}")),
301        ),
302        Some(status @ ("queued" | "in_progress")) => {
303            other(status, format!("Response ended while {status}"))
304        }
305        Some(status) => other(
306            status,
307            format!("Response ended with the unknown status `{status}`"),
308        ),
309    }
310}
311
312/// The usage a Responses `usage` value reports; a counter that is absent or
313/// not a count is unreported. Its cost is the one the provider reports.
314pub(crate) fn usage_of(usage: &Value) -> Usage {
315    let count = |pointer: &str| usage.at(pointer).and_then(Lenient::as_u64_lenient);
316    Usage {
317        input_tokens: count("/input_tokens"),
318        output_tokens: count("/output_tokens"),
319        total_tokens: count("/total_tokens"),
320        cached_input_tokens: count("/input_tokens_details/cached_tokens"),
321        cache_creation_input_tokens: count("/input_tokens_details/cache_write_tokens"),
322        reasoning_tokens: count("/output_tokens_details/reasoning_tokens"),
323        ..Usage::default()
324    }
325    .cost(reported::cost(Some(usage), &serde_json::Map::new()))
326}
327
328/// The citations a message item's `output_text` parts state, in part order.
329/// The API does not document the unit of `start_index` and `end_index` and
330/// quotes no text, so each cites the whole block and its offsets stay in the
331/// item.
332fn citations_of(item: &Value) -> Vec<WireCitation> {
333    item.arr("content")
334        .iter()
335        .flat_map(|part| part.arr("annotations"))
336        .filter_map(source_of)
337        .map(|source| WireCitation::new(None, vec![source]))
338        .collect()
339}
340
341/// The source an annotation names; `None` for an annotation that names
342/// none or is of an unknown type.
343fn source_of(annotation: &Value) -> Option<Source> {
344    let text = |key: &str| {
345        annotation
346            .str(key)
347            .filter(|text| !text.is_empty())
348            .map(str::to_owned)
349    };
350    let location = match annotation.str("type")? {
351        "url_citation" => SourceLocation::Url { url: text("url")? },
352        "file_citation" | "file_path" | "container_file_citation" => SourceLocation::File {
353            file_id: text("file_id")?,
354            filename: text("filename"),
355            container_id: text("container_id"),
356        },
357        _ => return None,
358    };
359    let source = Source::new(location);
360    Some(match text("title") {
361        Some(title) => source.title(title),
362        None => source,
363    })
364}
365
366/// The OpenAI Responses wire's decoder: one state machine for the SSE
367/// stream, the unary body and the websocket session.
368///
369/// Each output item becomes one block. It opens when it is announced, or at
370/// its first delta, with no provider item, and its done item closes it,
371/// becoming the block's native: an item the provider never stated complete
372/// replays from its canonical fields. A done item merges into what streamed:
373/// a call keeps the id and name it was announced with and the arguments it
374/// streamed when its done item leaves them out, and text the done item
375/// leaves out stays, written into the item. The terminal response is the
376/// whole output: it finishes the items no done event carried, writes the
377/// ones the stream never stated, which is how a unary body decodes, and
378/// backfills the ciphertext of reasoning done without it.
379#[derive(Default)]
380pub struct ResponsesDecoder {
381    /// Every item, in the order it arrived.
382    slots: Vec<Slot>,
383    /// The latest slot at each output index the provider named.
384    indexed: HashMap<usize, usize>,
385    /// The slot the last item event addressed.
386    current: Option<usize>,
387    /// The writer indices of reasoning done and waiting for the item after
388    /// it to complete.
389    held: Vec<usize>,
390}
391
392impl ResponsesDecoder {
393    /// A decoder for one reply of a Responses endpoint.
394    pub fn new() -> Self {
395        Self::default()
396    }
397
398    /// The slot `frame` addresses, an event for an item of `kind`: the one
399    /// at its output index, else the one its item id names, else the open
400    /// one the stream is on, when the frame names no index or that item
401    /// was opened by a frame that named none (an envelope-less delta, then
402    /// its envelope-full done item). `None` for an item no slot holds yet.
403    fn addressed(&self, frame: &Value, kind: Kind) -> Result<Option<usize>, ProviderError> {
404        let index = output_index(frame)?;
405        if let Some(slot) = index.and_then(|index| self.indexed.get(&index)) {
406            return Ok(Some(*slot));
407        }
408        let id = frame
409            .at("/item/id")
410            .and_then(Value::as_str)
411            .or_else(|| frame.str("item_id"));
412        if let Some(slot) = id.filter(|id| !id.is_empty()).and_then(|id| {
413            self.slots
414                .iter()
415                .rposition(|slot| slot.id.as_deref() == Some(id))
416        }) {
417            return Ok(Some(slot));
418        }
419        Ok(self.current.filter(|current| {
420            (index.is_none() || !self.indexed.values().any(|slot| slot == current))
421                && self
422                    .slots
423                    .get(*current)
424                    .is_some_and(|slot| slot.open && slot.kind == kind)
425        }))
426    }
427
428    /// Open the block of `item` as a new slot at output `index`, closing what
429    /// is still open there.
430    fn added(
431        &mut self,
432        index: Option<usize>,
433        item: &Value,
434        out: &mut Out<'_, Completion>,
435    ) -> Result<usize, ProviderError> {
436        if let Some(previous) = index.and_then(|index| self.indexed.get(&index).copied()) {
437            self.vacate(previous, out)?;
438        }
439        let at = match index {
440            Some(index) if !self.slots.iter().any(|slot| slot.at == index) => index,
441            _ => out.fresh_index(),
442        };
443        let kind = Kind::of(item);
444        let custom = item.str("type") == Some("custom_tool_call");
445        match kind {
446            Kind::Message => out.open(at, Block::Text, Value::Null)?,
447            Kind::Reasoning => out.open(at, Block::Reasoning { redacted: false }, Value::Null)?,
448            Kind::Call => out.fragment(
449                Some(at),
450                CallFragment {
451                    id: item.str("call_id"),
452                    name: item.str("name"),
453                    arguments: None,
454                },
455            )?,
456            // An item that names no type is kept and never sent back.
457            Kind::Opaque => {
458                let replay = item
459                    .str("type")
460                    .is_some_and(|kind| !CLIENT_EXECUTED.contains(&kind));
461                out.open(at, Block::Opaque { replay }, item.clone())?;
462            }
463        }
464        self.slots.push(Slot {
465            at,
466            kind,
467            id: item_id(item).map(str::to_owned),
468            open: true,
469            text: String::new(),
470            field: None,
471            part: 0,
472            arguments: String::new(),
473            custom,
474            named: item.str("call_id").is_some_and(|id| !id.is_empty()),
475            titled: item.str("name").is_some_and(|name| !name.is_empty()),
476        });
477        let slot = self.slots.len() - 1;
478        if let Some(index) = index {
479            self.indexed.insert(index, slot);
480        }
481        self.current = Some(slot);
482        if let Some(call) = self
483            .slots
484            .get_mut(slot)
485            .filter(|slot| slot.kind == Kind::Call)
486        {
487            let arguments = item.str(if custom { "input" } else { "arguments" });
488            send(call, arguments.unwrap_or_default(), out)?;
489        }
490        Ok(slot)
491    }
492
493    /// Close the slot's block before another item takes its place: the
494    /// provider never stated it complete. A call keeps what streamed.
495    fn vacate(&mut self, slot: usize, out: &mut Out<'_, Completion>) -> Result<(), ProviderError> {
496        let Some(open) = self.slots.get_mut(slot).filter(|slot| slot.open) else {
497            return Ok(());
498        };
499        open.open = false;
500        let at = open.at;
501        if open.kind == Kind::Call {
502            flush(open, out)?;
503        }
504        out.close(at)?;
505        self.release(false, out)
506    }
507
508    /// End the reasoning held for the item after it: complete when that
509    /// item completed, else as never stated complete.
510    fn release(
511        &mut self,
512        complete: bool,
513        out: &mut Out<'_, Completion>,
514    ) -> Result<(), ProviderError> {
515        std::mem::take(&mut self.held)
516            .into_iter()
517            .try_for_each(|at| {
518                if complete {
519                    out.finish(at)
520                } else {
521                    out.close(at)
522                }
523            })
524    }
525
526    /// Append a text delta of `field` to the item `frame` addresses,
527    /// opening a block for an item the stream never announced.
528    fn text(
529        &mut self,
530        frame: &Value,
531        field: &'static str,
532        part: &str,
533        out: &mut Out<'_, Completion>,
534    ) -> Result<(), ProviderError> {
535        let delta = frame.str("delta").unwrap_or_default();
536        if delta.is_empty() {
537            return Ok(());
538        }
539        let part = frame.u64(part).unwrap_or(0);
540        let kind = match field {
541            "message" => Kind::Message,
542            _ => Kind::Reasoning,
543        };
544        let known = self.addressed(frame, kind)?.and_then(|at| {
545            let slot = self.slots.get(at)?;
546            Some((at, slot.open, slot.kind == kind))
547        });
548        let slot = match known {
549            Some((slot, true, true)) => slot,
550            // A delta for an item that already closed is left to the item,
551            // which states its text.
552            Some((_, false, true)) => return Ok(()),
553            _ => self.added(
554                output_index(frame)?,
555                &json!({"type": if kind == Kind::Message { "message" } else { "reasoning" }}),
556                out,
557            )?,
558        };
559        let Some(streamed) = self.slots.get_mut(slot).filter(|slot| slot.open) else {
560            return Ok(());
561        };
562        if streamed.field.is_some_and(|known| known != field) {
563            return Ok(());
564        }
565        if streamed.part != part && kind != Kind::Message && !streamed.text.is_empty() {
566            streamed.text.push_str("\n\n");
567            out.push(streamed.at, "\n\n")?;
568        }
569        streamed.field = Some(field);
570        streamed.part = part;
571        streamed.text.push_str(delta);
572        out.push(streamed.at, delta)
573    }
574
575    /// Append an argument delta to the call `frame` addresses and write
576    /// it to the call, which streams it.
577    fn arguments(
578        &mut self,
579        frame: &Value,
580        out: &mut Out<'_, Completion>,
581    ) -> Result<(), ProviderError> {
582        let slot = self.addressed(frame, Kind::Call)?;
583        if let Some(call) = slot
584            .and_then(|slot| self.slots.get_mut(slot))
585            .filter(|slot| slot.open && slot.kind == Kind::Call)
586        {
587            send(call, frame.str("delta").unwrap_or_default(), out)?;
588        }
589        Ok(())
590    }
591
592    /// The item at `slot` is done: it merges into what streamed and becomes
593    /// the block's native. A call the item states `incomplete`, as one the
594    /// output limit cut, closes as never stated complete.
595    fn done(
596        &mut self,
597        slot: usize,
598        item: Value,
599        out: &mut Out<'_, Completion>,
600    ) -> Result<(), ProviderError> {
601        let Some(done) = self.slots.get_mut(slot) else {
602            return Ok(());
603        };
604        done.open = false;
605        if done.id.is_none() {
606            done.id = item_id(&item).map(str::to_owned);
607        }
608        let at = done.at;
609        let mut item = item;
610        let mut nameless = false;
611        let incomplete = done.kind == Kind::Call && item.str("status") == Some("incomplete");
612        match done.kind {
613            Kind::Call => {
614                nameless = !done.titled && item.str("name").is_none_or(str::is_empty);
615                let arguments = arguments_of(&item).unwrap_or_else(|| streamed_arguments(done));
616                let rest = remainder(done, &arguments, out)?;
617                out.fragment(
618                    Some(at),
619                    CallFragment {
620                        id: item.str("call_id").filter(|_| !done.named),
621                        name: item.str("name"),
622                        arguments: Some(&rest),
623                    },
624                )?;
625            }
626            Kind::Message | Kind::Reasoning => {
627                let text = text_of(&item);
628                if text.is_empty() {
629                    // Raw reasoning text the done item leaves out stays out:
630                    // written in as a summary, it would replay one the
631                    // provider never produced.
632                    if !done.text.is_empty() && done.field != Some("reasoning") {
633                        item = stating(item, done.kind, &done.text);
634                    }
635                } else if let Some(rest) = text.strip_prefix(done.text.as_str()) {
636                    out.push(at, rest)?;
637                } else {
638                    // The done item states the whole text, as pi takes it.
639                    out.restate(at, &text)?;
640                }
641                let citations = citations_of(&item);
642                if done.kind == Kind::Message && !citations.is_empty() {
643                    // The item restates every annotation, so its list
644                    // replaces any an earlier snapshot gave.
645                    out.set_citations(at, citations);
646                }
647            }
648            Kind::Opaque => {}
649        }
650        let reasoning = done.kind == Kind::Reasoning;
651        out.edit(at, |native| *native = item)?;
652        if reasoning {
653            // Reasoning is sent only with the item it precedes, so it is
654            // complete only once that item is.
655            self.held.push(at);
656            return Ok(());
657        }
658        if incomplete {
659            out.close(at)?;
660        } else {
661            out.finish(at)?;
662        }
663        // The writer drops a call with no name, so the reasoning it held
664        // has no item to go with.
665        self.release(!nameless && !incomplete, out)
666    }
667
668    /// Write one output-item event into the reply.
669    fn item_event(
670        &mut self,
671        kind: &str,
672        mut frame: Value,
673        out: &mut Out<'_, Completion>,
674    ) -> Result<(), ProviderError> {
675        match kind {
676            "response.output_item.added" | "response.output_item.done" => {
677                let Some(item) = frame.get("item").filter(|item| item.is_object()) else {
678                    return Ok(());
679                };
680                let index = output_index(&frame)?;
681                if kind == "response.output_item.added" {
682                    return self.added(index, item, out).map(|_| ());
683                }
684                let known = self.addressed(&frame, Kind::of(item))?;
685                // At a named output index the item is the one there, as pi
686                // reads it, whatever id it states.
687                let restates = |slot: &Slot| {
688                    slot.kind == Kind::of(item)
689                        && (index.is_some()
690                            || item_id(item)
691                                .zip(slot.id.as_deref())
692                                .is_none_or(|(id, known)| id == known))
693                };
694                let known = known.and_then(|at| {
695                    let slot = self.slots.get(at)?;
696                    let same = item_id(item).is_some() && slot.id.as_deref() == item_id(item);
697                    Some((at, slot.open && restates(slot), same))
698                });
699                let slot = match known {
700                    Some((slot, true, _)) => slot,
701                    // The item this one restates is already done.
702                    Some((_, false, true)) => return Ok(()),
703                    _ => self.added(index, item, out)?,
704                };
705                let item = frame
706                    .as_object_mut()
707                    .and_then(|frame| remove_preserving_order(frame, "item"))
708                    .unwrap_or_default();
709                self.done(slot, item, out)
710            }
711            // A refusal is the assistant's message for that turn.
712            "response.output_text.delta" | "response.refusal.delta" => {
713                self.text(&frame, "message", "content_index", out)
714            }
715            "response.reasoning_summary_text.delta" => {
716                self.text(&frame, "summary", "summary_index", out)
717            }
718            "response.reasoning_text.delta" => self.text(&frame, "reasoning", "content_index", out),
719            "response.function_call_arguments.delta" | "response.custom_tool_call_input.delta" => {
720                self.arguments(&frame, out)
721            }
722            _ => Ok(()),
723        }
724    }
725
726    /// The slot the terminal's item at output `index` restates, among those
727    /// no earlier terminal item took: the one with its id; else the one the
728    /// stream gave that index when it is of the item's kind, whatever id it
729    /// states; else the first of its kind the stream
730    /// gave no index and no other id; else the first of its kind with no
731    /// other id that the stream put at an index the terminal holds no item
732    /// of that kind at, a stream whose indices are shifted against it.
733    fn restated(
734        &self,
735        index: usize,
736        item: &Value,
737        kinds: &[Kind],
738        taken: &HashSet<usize>,
739    ) -> Option<usize> {
740        let id = item_id(item);
741        let free = |at: &usize| {
742            !taken.contains(at)
743                && self
744                    .slots
745                    .get(*at)
746                    .is_some_and(|slot| slot.kind == Kind::of(item))
747        };
748        let find = |fits: &dyn Fn(usize, &Slot) -> bool| {
749            self.slots
750                .iter()
751                .enumerate()
752                .find(|(at, slot)| free(at) && fits(*at, slot))
753                .map(|(at, _)| at)
754        };
755        id.and_then(|id| find(&|_, slot| slot.id.as_deref() == Some(id)))
756            .or_else(|| self.indexed.get(&index).copied().filter(free))
757            .or_else(|| {
758                find(&|at, slot| {
759                    !self.indexed.values().any(|indexed| *indexed == at)
760                        && (id.is_none() || slot.id.is_none())
761                })
762            })
763            .or_else(|| {
764                find(&|at, slot| {
765                    (id.is_none() || slot.id.is_none())
766                        && self.indexed.iter().any(|(streamed, indexed)| {
767                            *indexed == at
768                                && kinds.get(*streamed).is_none_or(|other| *other != slot.kind)
769                        })
770                })
771            })
772    }
773
774    /// The terminal response: finish or write each item of its output,
775    /// backfill the ciphertext of reasoning done without it, then end with
776    /// how the turn ended. A body that reports its reasoning as one
777    /// top-level string and no reasoning item is written that reasoning
778    /// first.
779    fn finish(
780        &mut self,
781        mut response: Value,
782        mut out: Out<'_, Completion>,
783    ) -> Result<Flow, ProviderError> {
784        let output = match response.get_mut("output") {
785            Some(Value::Array(output)) => std::mem::take(output),
786            _ => Vec::new(),
787        };
788        if self.slots.is_empty()
789            && !output.iter().any(|item| Kind::of(item) == Kind::Reasoning)
790            && let Some(reasoning) = response.str("reasoning").filter(|text| !text.is_empty())
791        {
792            // Index 0 orders it before the output; it closes at once, so the
793            // output's first item may open there after it.
794            out.whole(
795                0,
796                Block::Reasoning { redacted: false },
797                Value::Null,
798                reasoning,
799            )?;
800        }
801        let mut taken = HashSet::new();
802        let kinds: Vec<Kind> = output.iter().map(Kind::of).collect();
803        for (index, item) in output
804            .into_iter()
805            .enumerate()
806            .filter(|(_, item)| item.is_object())
807        {
808            let known = self.restated(index, &item, &kinds, &taken).and_then(|at| {
809                let slot = self.slots.get(at)?;
810                Some((at, slot.open, slot.kind, slot.at))
811            });
812            let slot = match known {
813                Some((slot, false, kind, at)) => {
814                    taken.insert(slot);
815                    let ciphertext = item
816                        .get("encrypted_content")
817                        .filter(|cipher| cipher.as_str().is_some_and(|cipher| !cipher.is_empty()));
818                    if let (Kind::Reasoning, Some(ciphertext)) = (kind, ciphertext) {
819                        out.edit(at, |native| {
820                            let stated = native
821                                .str("encrypted_content")
822                                .is_some_and(|cipher| !cipher.is_empty());
823                            if let (false, Some(fields)) = (stated, native.as_object_mut()) {
824                                fields.insert("encrypted_content".to_owned(), ciphertext.clone());
825                            }
826                        })?;
827                    }
828                    continue;
829                }
830                Some((slot, ..)) => slot,
831                None => self.added(
832                    Some(index).filter(|index| !self.indexed.contains_key(index)),
833                    &item,
834                    &mut out,
835                )?,
836            };
837            taken.insert(slot);
838            self.done(slot, item, &mut out)?;
839        }
840        // Reasoning still waiting is complete when nothing after it is left
841        // open.
842        let open = self.slots.iter().any(|slot| slot.open);
843        self.release(!open, &mut out)?;
844        // A call never done shows what streamed, in a turn that fails.
845        for slot in self.slots.iter_mut().filter(|slot| slot.open) {
846            if slot.kind == Kind::Call {
847                flush(slot, &mut out)?;
848            }
849        }
850        let (reason, error) = finish_reason_of(&response);
851        let end = Finish {
852            usage: response.get("usage").map(usage_of).unwrap_or_default(),
853            reason: Some(reason),
854            response_id: item_id(&response).map(str::to_owned),
855            model: response
856                .str("model")
857                .filter(|model| !model.is_empty())
858                .map(str::to_owned),
859            error,
860        };
861        Ok(out.end(end))
862    }
863}
864
865/// Give `slot`'s call what it streamed, before it closes undone.
866fn flush(slot: &Slot, out: &mut Out<'_, Completion>) -> Result<(), ProviderError> {
867    let arguments = streamed_arguments(slot);
868    let rest = remainder(slot, &arguments, out)?;
869    let fragment = CallFragment {
870        arguments: Some(&rest),
871        ..CallFragment::default()
872    };
873    out.fragment(Some(slot.at), fragment)
874}
875
876/// Append `delta` to `slot`'s call and write it to the call, which
877/// streams it. A custom call's input streams inside its `{"input": ...}`
878/// object, escaped as the object's string, so its fragments join to the
879/// object its end states: JSON escapes each character on its own, so the
880/// escaped delta extends what was written.
881fn send(slot: &mut Slot, delta: &str, out: &mut Out<'_, Completion>) -> Result<(), ProviderError> {
882    if delta.is_empty() {
883        return Ok(());
884    }
885    let fragment = if slot.custom {
886        let quoted = serde_json::to_string(delta)?;
887        let open = quoted.strip_suffix('"').unwrap_or(&quoted);
888        Cow::Owned(match open.strip_prefix('"') {
889            Some(escaped) if !slot.arguments.is_empty() => escaped.to_owned(),
890            _ => format!("{{\"input\":{open}"),
891        })
892    } else {
893        Cow::Borrowed(delta)
894    };
895    slot.arguments.push_str(delta);
896    let fragment = CallFragment {
897        arguments: Some(&fragment),
898        ..CallFragment::default()
899    };
900    out.fragment(Some(slot.at), fragment)
901}
902
903/// What of `arguments`, the whole JSON `slot`'s call states, the call has
904/// not been given yet. When `arguments` does not extend what streamed, it
905/// replaces the call's text and nothing more streams: the call's end states
906/// it.
907fn remainder(
908    slot: &Slot,
909    arguments: &str,
910    out: &mut Out<'_, Completion>,
911) -> Result<String, ProviderError> {
912    // What `send` wrote: the streamed JSON, a custom call's input still open.
913    let streamed = streamed_arguments(slot);
914    let sent = if slot.arguments.is_empty() {
915        ""
916    } else if slot.custom {
917        streamed.strip_suffix("\"}").unwrap_or(&streamed)
918    } else {
919        &streamed
920    };
921    Ok(match arguments.strip_prefix(sent) {
922        Some(rest) => rest.to_owned(),
923        None => {
924            out.restate(slot.at, arguments)?;
925            String::new()
926        }
927    })
928}
929
930/// The argument JSON of what `slot`'s call streamed.
931fn streamed_arguments(slot: &Slot) -> String {
932    if slot.custom {
933        json!({ "input": slot.arguments }).to_string()
934    } else {
935        slot.arguments.clone()
936    }
937}
938
939/// The output index `frame` names.
940fn output_index(frame: &Value) -> Result<Option<usize>, ProviderError> {
941    frame
942        .u64("output_index")
943        .map(|index| {
944            usize::try_from(index).map_err(|_| {
945                ProviderError::Response(format!("output_index {index} is out of range"))
946            })
947        })
948        .transpose()
949}
950
951impl<'id> Decoder<'id, Completion> for ResponsesDecoder {
952    type Event = ResponsesEvent;
953
954    fn classify(&self, frame: WireFrame) -> WireEvent<ResponsesEvent> {
955        classify_responses_payload(&frame.as_str())
956    }
957
958    fn decode(
959        &mut self,
960        event: ResponsesEvent,
961        mut out: Out<'id, Completion>,
962    ) -> Result<Flow, ProviderError> {
963        // A terminal may state items the stream never announced; they take
964        // their place by output index.
965        out.order_by_index();
966        match event {
967            ResponsesEvent::Frame {
968                kind,
969                mut frame,
970                raw,
971            } => match kind.as_str() {
972                // `response.incomplete` is a genuine terminal that keeps the
973                // partial output and usage. It is incomplete whatever its
974                // `status` says, where pi reads a missing status as a stop.
975                "response.completed" | "response.incomplete" => {
976                    let mut response = frame
977                        .as_object_mut()
978                        .and_then(|frame| remove_preserving_order(frame, "response"))
979                        .filter(Value::is_object)
980                        .unwrap_or_else(|| json!({}));
981                    if let (true, Some(fields)) =
982                        (kind == "response.incomplete", response.as_object_mut())
983                    {
984                        fields.insert("status".to_owned(), json!("incomplete"));
985                    }
986                    self.finish(response, out)
987                }
988                "response.failed" => {
989                    Err(ProviderError::from_provider_body(raw.unwrap_or_default()))
990                }
991                "keepalive" => Ok(Flow::More),
992                kind if is_lifecycle_event(kind) => Ok(Flow::More),
993                kind => {
994                    self.item_event(kind, frame, &mut out)?;
995                    Ok(Flow::More)
996                }
997            },
998            // The unary reply is the terminal response with no stream before it.
999            ResponsesEvent::Whole(body) => self.finish(body, out),
1000            ResponsesEvent::Failure(raw) => Err(ProviderError::from_provider_body(raw)),
1001            // Nothing to write: the provider's end is `response.completed`.
1002            ResponsesEvent::Sentinel => Ok(Flow::More),
1003        }
1004    }
1005}
1006
1007pub(crate) mod document;
1008
1009#[cfg(test)]
1010mod tests;