Skip to main content

rig_core/providers/anthropic/
streaming.rs

1//! The Messages reply decoder, for a whole message and for the event stream
2//! alike. Each content block becomes one block, in wire order, whose
3//! provider item is the block as the provider states it complete, and only
4//! when the wire would take that item back.
5//!
6//! ```
7//! use rig_core::providers::anthropic::streaming::MessagesDecoder;
8//!
9//! use rig_core::providers::anthropic::wire::Quirks;
10//!
11//! let decoder = MessagesDecoder::new(Quirks::anthropic());
12//! # let _ = decoder;
13//! ```
14
15use std::collections::{BTreeMap, BTreeSet};
16
17use serde_json::{Map, Value, json};
18
19use crate::completion::{FinishReason, token_sum};
20use crate::error::ProviderError;
21use crate::json_utils::Lenient;
22use crate::message::{CallId, DocumentRange, Source, SourceLocation, ToolName};
23use crate::operation::{Block, CallFragment, Completion, Finish};
24use crate::providers::internal::set_fields;
25use crate::providers::internal::wire;
26use crate::wire::{Decoder, Flow, Out, WireCitation, WireEvent, WireFrame};
27
28/// Recognized Messages event tags; any other tag classifies as unknown.
29/// `message` is the whole message a unary reply is.
30const KNOWN_EVENT_TYPES: &[&str] = &[
31    "message",
32    "message_start",
33    "content_block_start",
34    "content_block_delta",
35    "content_block_stop",
36    "message_delta",
37    "message_stop",
38    "ping",
39    "error",
40];
41
42/// One Messages event, or the whole message a unary reply is, as the
43/// provider sent it. The decoder reads each field it needs on its own, so
44/// an invented field, or a known one of another type, never fails a reply.
45#[derive(Debug, Clone, PartialEq)]
46pub struct MessagesEvent {
47    /// The event as sent.
48    pub fields: Value,
49    /// The frame's text when it is an `error` event, whose envelope is
50    /// reported verbatim.
51    raw: Option<String>,
52}
53
54impl MessagesEvent {
55    fn kind(&self) -> &str {
56        self.fields.str("type").unwrap_or_default()
57    }
58
59    /// The content block the event addresses.
60    fn index(&self) -> Result<usize, ProviderError> {
61        self.fields
62            .u64("index")
63            .and_then(|index| usize::try_from(index).ok())
64            .ok_or_else(|| {
65                ProviderError::Response(format!("Anthropic `{}` names no block index", self.kind()))
66            })
67    }
68
69    /// The block or delta under `key`, which must name its `type`.
70    fn item(&self, key: &str) -> Result<&Map<String, Value>, ProviderError> {
71        match self.fields.get(key) {
72            Some(Value::Object(item)) if item.get("type").is_some_and(Value::is_string) => Ok(item),
73            _ => Err(ProviderError::Response(format!(
74                "Anthropic `{}` carries no `{key}` with a string `type`",
75                self.kind()
76            ))),
77        }
78    }
79}
80
81/// Anthropic's usage counters, read leniently.
82#[derive(Debug, Clone, Default, PartialEq)]
83struct Counts {
84    input: Option<u64>,
85    output: Option<u64>,
86    cache_read: Option<u64>,
87    cache_creation: Option<u64>,
88    /// The per-TTL breakdown of `cache_creation`, as sent. A malformed one is
89    /// kept, so it replaces an earlier one and leaves the writes unpriced.
90    cache_creation_split: Option<Value>,
91    thinking: Option<u64>,
92}
93
94impl Counts {
95    fn of(usage: Option<&Value>) -> Self {
96        let count = |pointer: &str| usage?.at(pointer)?.as_u64_lenient();
97        Self {
98            input: count("/input_tokens"),
99            output: count("/output_tokens"),
100            cache_read: count("/cache_read_input_tokens"),
101            cache_creation: count("/cache_creation_input_tokens"),
102            cache_creation_split: usage
103                .and_then(|usage| usage.get("cache_creation"))
104                .filter(|split| !split.is_null())
105                .cloned(),
106            thinking: count("/output_tokens_details/thinking_tokens"),
107        }
108    }
109
110    /// Rig's usage: its input is `input_tokens` plus the cache reads and
111    /// writes counted beside it, its output `output_tokens` (thinking
112    /// included), and its total their sum when both are known; an error
113    /// when a sum overflows.
114    fn usage(&self) -> Result<crate::completion::Usage, ProviderError> {
115        let (read, written) = (
116            self.cache_read.unwrap_or(0),
117            self.cache_creation.unwrap_or(0),
118        );
119        let input = self
120            .input
121            .map(|uncached| token_sum([uncached, read, written]))
122            .transpose()?;
123        let total = input
124            .zip(self.output)
125            .map(|(input, output)| token_sum([input, output]))
126            .transpose()?;
127        Ok(crate::completion::Usage {
128            input_tokens: input,
129            output_tokens: self.output,
130            cached_input_tokens: self.cache_read,
131            cache_creation_input_tokens: self.cache_creation,
132            reasoning_tokens: self.thinking,
133            total_tokens: total,
134            tool_use_prompt_tokens: None,
135            ..Default::default()
136        })
137    }
138
139    /// What the cache writes cost at `pricing` by their TTL split:
140    /// five-minute writes at the write rate, one-hour writes at twice the
141    /// input rate. `None` when the split is absent or does not add up to
142    /// the writes. These are standard API list prices, not subscription
143    /// charges or a custom endpoint's invoice.
144    fn write_cost(&self, pricing: &crate::catalog::Pricing) -> Option<f64> {
145        let written = self.cache_creation.unwrap_or(0);
146        if written == 0 {
147            return Some(0.0);
148        }
149        let split = self.cache_creation_split.as_ref()?;
150        let short = split.get("ephemeral_5m_input_tokens")?.as_u64()?;
151        let long = split.get("ephemeral_1h_input_tokens")?.as_u64()?;
152        if short.checked_add(long)? != written {
153            return None;
154        }
155        let short_cost = if short == 0 {
156            0.0
157        } else {
158            short as f64 * pricing.cache_write?
159        };
160        Some((short_cost + long as f64 * pricing.input * 2.0) / 1_000_000.0)
161    }
162}
163
164/// How a Messages `stop_reason` ends the turn, and the error a refusal
165/// reports. A reason Anthropic does not document is
166/// [`FinishReason::Other`], which fails the turn.
167fn finish_of(reason: &str, details: Option<&Value>) -> (Option<FinishReason>, Option<String>) {
168    let reason = match reason {
169        // `pause_turn` is a server-tool loop that stopped at its limit: the
170        // turn is replayed as it is to resume it (pi's rule).
171        "end_turn" | "stop_sequence" | "pause_turn" => FinishReason::Stop,
172        "max_tokens" | "model_context_window_exceeded" => FinishReason::Length,
173        "tool_use" => FinishReason::ToolCalls,
174        // A refusal fails the turn with its explanation (pi's rule).
175        "refusal" => {
176            let explanation = details
177                .and_then(|details| details.str("explanation"))
178                .filter(|explanation| !explanation.is_empty())
179                .unwrap_or("The model refused to complete the request");
180            return (
181                Some(FinishReason::ContentFilter),
182                Some(explanation.to_owned()),
183            );
184        }
185        other => FinishReason::Other(other.to_owned()),
186    };
187    (Some(reason), None)
188}
189
190/// One Messages citation as a whole-block [`WireCitation`]: Anthropic
191/// cites each text block as a whole. A location kind rig does not know, or
192/// one without the field that names its source, is `None` and stays only in
193/// the block's native item, as does `encrypted_index`. Document ranges end
194/// exclusive, pages count from 1, characters and blocks from 0.
195fn citation_of(citation: &Value) -> Option<WireCitation> {
196    let number = |key: &str| citation.u64(key).and_then(|n| u32::try_from(n).ok());
197    let range = |start: &str, end: &str| Some(number(start)?..number(end)?);
198    let location = match citation.str("type")? {
199        "char_location" => SourceLocation::Document {
200            index: number("document_index"),
201            id: citation.str("file_id").map(str::to_owned),
202            within: citation
203                .u64("start_char_index")
204                .zip(citation.u64("end_char_index"))
205                .map(|(start, end)| DocumentRange::Chars(start..end)),
206        },
207        "page_location" => SourceLocation::Document {
208            index: number("document_index"),
209            id: citation.str("file_id").map(str::to_owned),
210            within: range("start_page_number", "end_page_number").map(DocumentRange::Pages),
211        },
212        "content_block_location" => SourceLocation::Document {
213            index: number("document_index"),
214            id: citation.str("file_id").map(str::to_owned),
215            within: range("start_block_index", "end_block_index").map(DocumentRange::Blocks),
216        },
217        "search_result_location" => SourceLocation::SearchResult {
218            index: number("search_result_index")?,
219            source: citation.str("source")?.to_owned(),
220            blocks: range("start_block_index", "end_block_index"),
221        },
222        "web_search_result_location" => SourceLocation::Url {
223            url: citation.str("url")?.to_owned(),
224        },
225        _ => return None,
226    };
227    let mut source = Source::new(location);
228    if let Some(title) = citation
229        .str("document_title")
230        .or_else(|| citation.str("title"))
231    {
232        source = source.title(title);
233    }
234    if let Some(cited) = citation.str("cited_text") {
235        source = source.cited_text(cited);
236    }
237    Some(WireCitation::new(None, vec![source]))
238}
239
240/// What an open content block is, for the checks its end makes.
241#[derive(Debug, Clone, Copy, PartialEq, Eq)]
242enum Kind {
243    Text,
244    Thinking,
245    Redacted,
246    Call,
247    Opaque,
248}
249
250/// Only a repeated envelope establishes replay context. Compare complete
251/// starts because a gateway may reuse both wire indexes and tool ids.
252fn replayed_start(
253    previous: &[Map<String, Value>],
254    block: &Map<String, Value>,
255    reconnecting: bool,
256) -> bool {
257    reconnecting && previous.contains(block)
258}
259
260/// Decodes Messages replies, a whole message or a stream of events.
261/// `content_block_stop` states a block complete; a stop reason states every
262/// block still open complete, but a call whose input is not yet JSON.
263#[derive(Debug)]
264pub struct MessagesDecoder {
265    /// Each open block's kind and the input JSON streamed to it.
266    open: BTreeMap<usize, (Kind, String)>,
267    /// Every accepted start at each wire index, for identifying reconnect replays.
268    started: BTreeMap<usize, Vec<Map<String, Value>>>,
269    reconnecting: bool,
270    /// Closed blocks replayed by a reconnecting gateway.
271    replayed: BTreeSet<usize>,
272    /// The first valid envelope owns the reply metadata.
273    message_started: bool,
274    /// Whether a block other than a leading `fallback` marker opened.
275    opened: bool,
276    /// Whether the dialect takes thinking back without a signature.
277    unsigned_thinking: bool,
278    /// Whether the dialect prices cache writes by their TTL split
279    /// ([`Quirks::cache_ttl_pricing`](super::wire::Quirks::cache_ttl_pricing)).
280    cache_ttl_pricing: bool,
281    /// The counters `message_start` and each later `message_delta` before the
282    /// last reported, for a terminal `message_delta` that does not repeat them.
283    start: Counts,
284    message_id: Option<String>,
285    response_model: Option<String>,
286    container: Option<Value>,
287}
288
289impl MessagesDecoder {
290    /// A fresh decoder for one reply on a dialect with `quirks`.
291    pub fn new(quirks: super::wire::Quirks) -> Self {
292        Self {
293            open: BTreeMap::new(),
294            started: BTreeMap::new(),
295            reconnecting: false,
296            replayed: BTreeSet::new(),
297            message_started: false,
298            opened: false,
299            unsigned_thinking: quirks.unsigned_thinking,
300            cache_ttl_pricing: quirks.cache_ttl_pricing,
301            start: Counts::default(),
302            message_id: None,
303            response_model: None,
304            container: None,
305        }
306    }
307
308    /// Open the content block at `index` as the provider states it.
309    fn start(
310        &mut self,
311        index: usize,
312        block: Map<String, Value>,
313        out: &mut Out<'_, Completion>,
314    ) -> Result<(), ProviderError> {
315        if self.open.contains_key(&index) {
316            return Ok(());
317        }
318        if self
319            .started
320            .get(&index)
321            .is_some_and(|previous| replayed_start(previous, &block, self.reconnecting))
322        {
323            self.replayed.insert(index);
324            return Ok(());
325        }
326        self.replayed.remove(&index);
327        self.reconnecting = false;
328        self.started.entry(index).or_default().push(block.clone());
329        let block = Value::Object(block);
330        let kind = block.str("type").unwrap_or_default();
331        // A leading `fallback` names the model that took over; one after
332        // output began is a fallback rig cannot represent (pi's rule).
333        if kind == "fallback" {
334            if self.opened {
335                return Err(ProviderError::Response(
336                    "Anthropic performed an unsupported mid-output model fallback".to_owned(),
337                ));
338            }
339            self.open.insert(index, (Kind::Opaque, String::new()));
340            return out.open(index, Block::Opaque { replay: false }, block);
341        }
342        self.opened = true;
343        let (opened, kind, text) = match kind {
344            "text" => (Block::Text, Kind::Text, block.str("text")),
345            "thinking" => (
346                Block::Reasoning { redacted: false },
347                Kind::Thinking,
348                block.str("thinking"),
349            ),
350            "redacted_thinking" => (Block::Reasoning { redacted: true }, Kind::Redacted, None),
351            "tool_use" => {
352                self.open.insert(index, (Kind::Call, String::new()));
353                let id = block.str("id").unwrap_or_default().to_owned();
354                let input = block.get("input").cloned().unwrap_or_default();
355                match ToolName::new(block.str("name").unwrap_or_default()) {
356                    Ok(name) => {
357                        let id = CallId::from_wire(&id);
358                        out.open(index, Block::Call { id, name }, block)?;
359                    }
360                    // A nameless call: the writer drops it with a warning.
361                    Err(_) => out.fragment(
362                        Some(index),
363                        CallFragment {
364                            id: Some(&id),
365                            ..CallFragment::default()
366                        },
367                    )?,
368                }
369                // A whole reply states the input on the block; a stream
370                // streams it, and the fragments win.
371                return out.announce(index, input);
372            }
373            _ => (Block::Opaque { replay: true }, Kind::Opaque, None),
374        };
375        let text = text.unwrap_or_default().to_owned();
376        let citations: Vec<WireCitation> = match kind {
377            Kind::Text => block
378                .arr("citations")
379                .iter()
380                .filter_map(citation_of)
381                .collect(),
382            _ => Vec::new(),
383        };
384        self.open.insert(index, (kind, String::new()));
385        out.open(index, opened, block)?;
386        for citation in citations {
387            out.cite(index, citation);
388        }
389        out.push(index, &text)
390    }
391
392    /// Apply a delta to the open block at `index`: text and reasoning grow
393    /// both the block and its item, input JSON is assembled, a citation is
394    /// appended to the item and cited, and any other delta merges into the
395    /// item by key.
396    fn delta(
397        &mut self,
398        index: usize,
399        delta: &Map<String, Value>,
400        out: &mut Out<'_, Completion>,
401    ) -> Result<(), ProviderError> {
402        if self.replayed.contains(&index) {
403            return Ok(());
404        }
405        let kind = delta
406            .get("type")
407            .and_then(Value::as_str)
408            .unwrap_or_default();
409        // The fragment a block is built from must be text.
410        let fragment = |key: &str| {
411            delta.get(key).and_then(Value::as_str).ok_or_else(|| {
412                ProviderError::Response(format!("Anthropic `{kind}` carries no string `{key}`"))
413            })
414        };
415        // A gateway that skips `content_block_start` still streams the
416        // block's text, so the first delta opens it.
417        if !self.started.contains_key(&index) {
418            let opened = match kind {
419                "text_delta" => Some(json!({"type": "text", "text": ""})),
420                "thinking_delta" => Some(json!({"type": "thinking", "thinking": ""})),
421                _ => None,
422            };
423            if let Some(Value::Object(block)) = opened {
424                self.start(index, block, out)?;
425            }
426        }
427        match kind {
428            "text_delta" => out.push(index, fragment("text")?)?,
429            "thinking_delta" => out.push(index, fragment("thinking")?)?,
430            "input_json_delta" => {
431                let fragment = fragment("partial_json")?;
432                let Some((kind @ (Kind::Call | Kind::Opaque), json)) = self.open.get_mut(&index)
433                else {
434                    return Err(ProviderError::Response(format!(
435                        "Anthropic streamed input to content block {index}, which takes none"
436                    )));
437                };
438                json.push_str(fragment);
439                if *kind == Kind::Call {
440                    out.push(index, fragment)?;
441                }
442                return Ok(());
443            }
444            "citations_delta" => {
445                let citation = delta.get("citation").cloned().unwrap_or_default();
446                let cited = citation_of(&citation);
447                out.edit(index, |item| {
448                    if let Some(item) = item.as_object_mut() {
449                        match item.get_mut("citations") {
450                            Some(Value::Array(citations)) => citations.push(citation),
451                            _ => {
452                                item.insert("citations".to_owned(), Value::Array(vec![citation]));
453                            }
454                        }
455                    }
456                })?;
457                if let Some(cited) = cited {
458                    out.cite(index, cited);
459                }
460                return Ok(());
461            }
462            _ => {}
463        }
464        // Text and signatures concatenate; `compaction_delta` and kinds
465        // rig has never seen land in the item too.
466        out.edit(index, |item| {
467            crate::operation::completion::merge(item, delta)
468        })
469    }
470
471    /// End the block at `index` as stated complete. Its item becomes the
472    /// block's native only when the wire takes it back: text that is not
473    /// blank, thinking with its signature (unless the dialect takes it
474    /// unsigned), redacted thinking with its data, and a call with an
475    /// object `input`, set from what streamed. A hosted item whose input is
476    /// not an object never completed.
477    fn stop(&mut self, index: usize, out: &mut Out<'_, Completion>) -> Result<(), ProviderError> {
478        if self.replayed.remove(&index) {
479            return Ok(());
480        }
481        let Some((kind, json)) = self.open.remove(&index) else {
482            return out.finish(index);
483        };
484        let streamed = (!json.is_empty()).then(|| crate::json_utils::parse_tool_arguments(&json));
485        let unsigned = self.unsigned_thinking;
486        let mut complete = true;
487        out.edit(index, |item| {
488            let input = match streamed {
489                Some(Ok(parsed)) => Ok(Some(parsed)),
490                Some(Err(_)) => Err(()),
491                None => Ok(item.get("input").cloned()),
492            };
493            let kept = match (kind, input) {
494                (Kind::Text, _) => !item.str("text").unwrap_or_default().trim().is_empty(),
495                (Kind::Thinking, _) => {
496                    unsigned || item.str("signature").is_some_and(|s| !s.is_empty())
497                }
498                (Kind::Redacted, _) => item.str("data").is_some_and(|data| !data.is_empty()),
499                (Kind::Opaque, Ok(None)) => true,
500                (Kind::Call | Kind::Opaque, Ok(Some(input @ Value::Object(_)))) => {
501                    crate::operation::completion::merge(
502                        item,
503                        &set_fields([("input", Some(input))]),
504                    );
505                    true
506                }
507                (Kind::Call, Ok(None | Some(Value::Null))) => {
508                    crate::operation::completion::merge(
509                        item,
510                        &set_fields([("input", Some(json!({})))]),
511                    );
512                    true
513                }
514                (Kind::Call, _) => false,
515                (Kind::Opaque, _) => {
516                    complete = false;
517                    true
518                }
519            };
520            if !kept {
521                *item = Value::Null;
522            }
523        })?;
524        if complete {
525            out.finish(index)
526        } else {
527            out.close(index)
528        }
529    }
530
531    /// Note the metadata a whole message or `message_start` states.
532    fn metadata(&mut self, message: &Value) {
533        self.start = Counts::of(message.get("usage"));
534        self.message_id = message.str("id").map(str::to_owned);
535        self.response_model = message.str("model").map(str::to_owned);
536        self.note_container(message.get("container"));
537    }
538
539    fn note_container(&mut self, container: Option<&Value>) {
540        self.container = container
541            .filter(|c| !c.is_null())
542            .or(self.container.as_ref())
543            .cloned();
544    }
545
546    /// End the reply with Anthropic's terminal record. Every block still
547    /// open is complete, but a call whose input is not JSON yet, and any
548    /// call of a reply the output limit cut, whose `content_block_stop`
549    /// never came: the end of the reply closes it unfinished. The container
550    /// the reply ran in is a last opaque block.
551    fn end(
552        &mut self,
553        usage: &Counts,
554        stop_reason: Option<&str>,
555        details: Option<&Value>,
556        mut out: Out<'_, Completion>,
557    ) -> Result<Flow, ProviderError> {
558        let (reason, error) = stop_reason.map_or((None, None), |reason| finish_of(reason, details));
559        let cut = reason.as_ref().is_some_and(FinishReason::truncated_output);
560        let open: Vec<usize> = self
561            .open
562            .iter()
563            .filter(|(_, (kind, json))| {
564                *kind != Kind::Call
565                    || !cut
566                        && (json.is_empty()
567                            || crate::json_utils::parse_tool_arguments(json)
568                                .is_ok_and(|v| v.is_object()))
569            })
570            .map(|(index, _)| *index)
571            .collect();
572        for index in open {
573            self.stop(index, &mut out)?;
574        }
575        if let Some(container) = &self.container {
576            let index = out.fresh_index();
577            let item = json!({ "type": "container", "container": container });
578            out.whole(index, Block::Opaque { replay: true }, item, "")?;
579        }
580        let mut counted = usage.usage()?;
581        if self.cache_ttl_pricing {
582            counted.cost = out
583                .catalog_pricing(self.response_model.as_deref())
584                .and_then(|pricing| {
585                    let write = usage.write_cost(&pricing);
586                    pricing.cost_with_cache_write(&counted, write)
587                });
588        }
589        Ok(out.end(Finish {
590            usage: counted,
591            reason,
592            response_id: self.message_id.clone(),
593            model: self.response_model.clone(),
594            error,
595        }))
596    }
597
598    /// A whole message, written block by block through the calls a stream
599    /// makes, then ended. Empty content is a turn like any other, as it is
600    /// streamed (pi's rule): the stop reason decides how it ends.
601    fn whole(
602        &mut self,
603        mut message: Value,
604        mut out: Out<'_, Completion>,
605    ) -> Result<Flow, ProviderError> {
606        self.metadata(&message);
607        let content = match message.get_mut("content").map(Value::take) {
608            Some(Value::Array(content)) => content,
609            _ => Vec::new(),
610        };
611        for (index, block) in content.into_iter().enumerate() {
612            let block = match block {
613                Value::Object(block) if block.get("type").is_some_and(Value::is_string) => block,
614                _ => {
615                    return Err(ProviderError::Response(format!(
616                        "Anthropic content block {index} has no string `type`"
617                    )));
618                }
619            };
620            self.start(index, block, &mut out)?;
621            self.stop(index, &mut out)?;
622        }
623        let usage = self.start.clone();
624        self.end(
625            &usage,
626            message.str("stop_reason"),
627            message.get("stop_details"),
628            out,
629        )
630    }
631
632    /// Reports the running counters as the usage so far.
633    fn report(&self, out: &mut Out<'_, Completion>) {
634        if let Ok(usage) = self.start.usage() {
635            out.usage(usage);
636        }
637    }
638
639    /// A `message_delta`'s counters, falling back to the running ones for
640    /// those it omits.
641    fn terminal(&self, usage: Option<&Value>) -> Counts {
642        let (terminal, start) = (Counts::of(usage), self.start.clone());
643        Counts {
644            // Zero-as-missing is a gateway heuristic for the input count
645            // only, not a rule for cache counts.
646            input: terminal.input.filter(|tokens| *tokens > 0).or(start.input),
647            cache_read: terminal.cache_read.or(start.cache_read),
648            cache_creation: terminal.cache_creation.or(start.cache_creation),
649            cache_creation_split: terminal.cache_creation_split.or(start.cache_creation_split),
650            ..terminal
651        }
652    }
653}
654
655impl<'id> Decoder<'id, Completion> for MessagesDecoder {
656    type Event = MessagesEvent;
657
658    fn classify(&self, frame: WireFrame) -> WireEvent<MessagesEvent> {
659        let data = frame.as_str();
660        wire::classify_tagged_frame::<Value>(&data, "type", |tag| KNOWN_EVENT_TYPES.contains(&tag))
661            .map(|fields| {
662                // The one event whose payload leaves this crate as bytes rather
663                // than as decoded fields, so it is captured where the frame is
664                // still in hand.
665                let raw = (fields.str("type") == Some("error")).then(|| data.to_string());
666                MessagesEvent { fields, raw }
667            })
668    }
669
670    fn decode(
671        &mut self,
672        event: MessagesEvent,
673        mut out: Out<'id, Completion>,
674    ) -> Result<Flow, ProviderError> {
675        match event.kind() {
676            "message" => return self.whole(event.fields, out),
677            // A `message_start` without a message body (a Bedrock-compatible
678            // gateway sends one) is a no-op.
679            "message_start" => {
680                if self.message_started && event.fields.get("message").is_some_and(Value::is_object)
681                {
682                    self.reconnecting = true;
683                }
684                if !self.message_started
685                    && let Some(message) = event.fields.get("message").filter(|m| m.is_object())
686                {
687                    self.message_started = true;
688                    self.metadata(message);
689                    self.report(&mut out);
690                }
691            }
692            "content_block_start" => {
693                let block = event.item("content_block")?.clone();
694                self.start(event.index()?, block, &mut out)?;
695            }
696            "content_block_delta" => {
697                let delta = event.item("delta")?;
698                self.delta(event.index()?, delta, &mut out)?;
699            }
700            "content_block_stop" => self.stop(event.index()?, &mut out)?,
701            "message_delta" => {
702                let delta = event.fields.get("delta");
703                self.note_container(delta.and_then(|delta| delta.get("container")));
704                // Only a `message_delta` carrying a stop reason is the
705                // provider's end; without one its counters update the
706                // running ones, as they do the reassembled reply.
707                let Some(reason) = delta.and_then(|delta| delta.str("stop_reason")) else {
708                    if let Some(usage) = event.fields.get("usage") {
709                        self.start = self.terminal(Some(usage));
710                        self.report(&mut out);
711                    }
712                    return Ok(Flow::More);
713                };
714                let usage = self.terminal(event.fields.get("usage"));
715                let details = delta.and_then(|delta| delta.get("stop_details"));
716                return self.end(&usage, Some(reason), details, out);
717            }
718            // Preserve the complete error envelope rather than re-encode
719            // modeled fields.
720            "error" => {
721                return Err(ProviderError::from_provider_body(
722                    event.raw.unwrap_or_default(),
723                ));
724            }
725            // `message_stop`, `ping`, and nothing else: the classifier
726            // passes only the listed tags.
727            _ => {}
728        }
729        Ok(Flow::More)
730    }
731}
732
733pub(crate) mod document;
734
735/// The document a Messages reply reassembles into.
736pub use document::Message as MessagesDocument;
737
738#[cfg(test)]
739mod tests;