1use std::{collections::BTreeSet, fmt, mem};
7
8use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
9use serde::{Deserialize, Deserializer, Serialize, Serializer, de};
10use thiserror::Error;
11
12use crate::{
13 ArtifactRef, AttemptId, BoundedJson, BoundedJsonError, ByteCount, CapabilityIdentity,
14 ContentMetadata, ContentPart, ContentSource, ExecutionCount, Extensions, JsonContent,
15 JsonLimits, LanguageTag, ModelCapabilityMismatch, ModelDescriptor, ModelFinishReason,
16 ModelOutputItem, ModelOutputItemError, ModelOutputItemKind, ModelProviderToolCallId,
17 ModelRequest, ModelResponse, ModelResponseError, ModelResponseMode, ModelResponseProvenance,
18 ModelToolCallProposal, ModelToolCallProposalError, ModelUsage, SchemaReference, TextContent,
19 TextContentError, TokenCount,
20};
21
22const KIBIBYTE: usize = 1024;
23const MAX_EVENTS_PER_ATTEMPT_VALUE: u64 = 1_048_576;
24
25#[derive(Clone, Eq, Hash, Ord, PartialEq, PartialOrd)]
32pub struct ModelStreamChunk(Box<str>);
33
34impl ModelStreamChunk {
35 pub const MAX_BYTES: usize = 64 * KIBIBYTE;
37
38 pub fn new(value: impl Into<String>) -> Result<Self, ModelStreamChunkError> {
45 let value = value.into();
46 validate_stream_chunk(&value)?;
47 Ok(Self(value.into_boxed_str()))
48 }
49
50 #[must_use]
52 pub fn as_str(&self) -> &str {
53 &self.0
54 }
55
56 #[must_use]
58 pub fn len_bytes(&self) -> usize {
59 self.0.len()
60 }
61
62 #[must_use]
64 pub fn into_string(self) -> String {
65 self.0.into()
66 }
67}
68
69fn validate_stream_chunk(value: &str) -> Result<(), ModelStreamChunkError> {
70 if value.is_empty() {
71 return Err(ModelStreamChunkError::Empty);
72 }
73 if value.len() > ModelStreamChunk::MAX_BYTES {
74 return Err(ModelStreamChunkError::TooLong {
75 maximum: ModelStreamChunk::MAX_BYTES,
76 actual: value.len(),
77 });
78 }
79 if let Some((byte_index, _)) = value.char_indices().find(|(_, scalar)| {
80 (scalar.is_control() && !matches!(scalar, '\t' | '\n' | '\r'))
81 || is_unicode_noncharacter(*scalar)
82 }) {
83 return Err(ModelStreamChunkError::DisallowedCodePoint { byte_index });
84 }
85 Ok(())
86}
87
88const fn is_unicode_noncharacter(value: char) -> bool {
89 let value = value as u32;
90 (value >= 0xfdd0 && value <= 0xfdef) || (value & 0xfffe) == 0xfffe
91}
92
93impl AsRef<str> for ModelStreamChunk {
94 fn as_ref(&self) -> &str {
95 self.as_str()
96 }
97}
98
99impl fmt::Debug for ModelStreamChunk {
100 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
101 formatter
102 .debug_struct("ModelStreamChunk")
103 .field("bytes", &self.len_bytes())
104 .finish_non_exhaustive()
105 }
106}
107
108impl Serialize for ModelStreamChunk {
109 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
110 where
111 S: Serializer,
112 {
113 serializer.serialize_str(self.as_str())
114 }
115}
116
117impl<'de> Deserialize<'de> for ModelStreamChunk {
118 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
119 where
120 D: Deserializer<'de>,
121 {
122 struct Visitor;
123
124 impl de::Visitor<'_> for Visitor {
125 type Value = ModelStreamChunk;
126
127 fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
128 formatter.write_str("a non-empty bounded model stream fragment")
129 }
130
131 fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
132 where
133 E: de::Error,
134 {
135 ModelStreamChunk::new(value).map_err(E::custom)
136 }
137
138 fn visit_string<E>(self, value: String) -> Result<Self::Value, E>
139 where
140 E: de::Error,
141 {
142 ModelStreamChunk::new(value).map_err(E::custom)
143 }
144 }
145
146 deserializer.deserialize_string(Visitor)
147 }
148}
149
150impl JsonSchema for ModelStreamChunk {
151 fn schema_name() -> std::borrow::Cow<'static, str> {
152 "ModelStreamChunk".into()
153 }
154
155 fn schema_id() -> std::borrow::Cow<'static, str> {
156 concat!(module_path!(), "::ModelStreamChunk").into()
157 }
158
159 fn json_schema(_: &mut SchemaGenerator) -> Schema {
160 json_schema!({
161 "type": "string",
162 "minLength": 1,
163 "maxLength": 65_536,
164 "description": "Exact UTF-8 fragment. maxLength is a necessary code-point ceiling; runtime validation separately enforces 65536 bytes and excludes disallowed controls and Unicode noncharacters."
165 })
166 }
167
168 fn inline_schema() -> bool {
169 true
170 }
171}
172
173#[derive(Clone, Debug, Eq, Error, PartialEq)]
175#[non_exhaustive]
176pub enum ModelStreamChunkError {
177 #[error("model stream chunk must not be empty")]
179 Empty,
180 #[error("model stream chunk is {actual} UTF-8 bytes; maximum is {maximum}")]
182 TooLong {
183 maximum: usize,
185 actual: usize,
187 },
188 #[error("model stream chunk contains a disallowed Unicode scalar at byte {byte_index}")]
190 DisallowedCodePoint {
191 byte_index: usize,
193 },
194}
195
196#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
202#[serde(
203 tag = "type",
204 content = "content",
205 rename_all = "snake_case",
206 deny_unknown_fields
207)]
208pub enum ModelOutputStart {
209 Text {
211 #[serde(skip_serializing_if = "Option::is_none")]
213 language: Option<LanguageTag>,
214 metadata: ContentMetadata,
216 },
217 Json {
219 #[serde(skip_serializing_if = "Option::is_none")]
221 schema: Option<SchemaReference>,
222 metadata: ContentMetadata,
224 },
225 Artifact(Box<ArtifactRef>),
227 ReasoningSummary {
229 #[serde(skip_serializing_if = "Option::is_none")]
231 language: Option<LanguageTag>,
232 metadata: ContentMetadata,
234 },
235 ToolCall {
237 tool: CapabilityIdentity,
239 #[serde(skip_serializing_if = "Option::is_none")]
241 provider_call_id: Option<ModelProviderToolCallId>,
242 extensions: Extensions,
244 },
245}
246
247impl ModelOutputStart {
248 pub fn text(
250 language: Option<LanguageTag>,
251 metadata: ContentMetadata,
252 ) -> Result<Self, ModelOutputItemError> {
253 let value = Self::Text { language, metadata };
254 value.validate_intrinsic()?;
255 Ok(value)
256 }
257
258 pub fn json(
260 schema: Option<SchemaReference>,
261 metadata: ContentMetadata,
262 ) -> Result<Self, ModelOutputItemError> {
263 let value = Self::Json { schema, metadata };
264 value.validate_intrinsic()?;
265 Ok(value)
266 }
267
268 pub fn artifact(artifact: ArtifactRef) -> Result<Self, ModelOutputItemError> {
270 let value = Self::Artifact(Box::new(artifact));
271 value.validate_intrinsic()?;
272 Ok(value)
273 }
274
275 pub fn reasoning_summary(
277 language: Option<LanguageTag>,
278 metadata: ContentMetadata,
279 ) -> Result<Self, ModelOutputItemError> {
280 let value = Self::ReasoningSummary { language, metadata };
281 value.validate_intrinsic()?;
282 Ok(value)
283 }
284
285 #[must_use]
287 pub fn tool_call(
288 tool: CapabilityIdentity,
289 provider_call_id: Option<ModelProviderToolCallId>,
290 extensions: Extensions,
291 ) -> Self {
292 Self::ToolCall {
293 tool,
294 provider_call_id,
295 extensions,
296 }
297 }
298
299 #[must_use]
301 pub const fn kind(&self) -> ModelOutputItemKind {
302 match self {
303 Self::Text { .. } | Self::Json { .. } | Self::Artifact(_) => {
304 ModelOutputItemKind::Content
305 }
306 Self::ReasoningSummary { .. } => ModelOutputItemKind::ReasoningSummary,
307 Self::ToolCall { .. } => ModelOutputItemKind::ToolCall,
308 }
309 }
310
311 #[must_use]
313 pub const fn delta_kind(&self) -> Option<ModelOutputDeltaKind> {
314 match self {
315 Self::Text { .. } => Some(ModelOutputDeltaKind::Text),
316 Self::Json { .. } => Some(ModelOutputDeltaKind::Json),
317 Self::Artifact(_) => None,
318 Self::ReasoningSummary { .. } => Some(ModelOutputDeltaKind::ReasoningSummary),
319 Self::ToolCall { .. } => Some(ModelOutputDeltaKind::ToolArguments),
320 }
321 }
322
323 fn validate_intrinsic(&self) -> Result<(), ModelOutputItemError> {
324 match self {
325 Self::Text { metadata, .. } | Self::Json { metadata, .. } => {
326 crate::model_response::validate_output_metadata(
327 ModelOutputItemKind::Content,
328 metadata,
329 ContentSource::Model,
330 )
331 }
332 Self::Artifact(artifact) => crate::model_response::validate_output_metadata(
333 ModelOutputItemKind::Content,
334 artifact.metadata(),
335 ContentSource::Artifact,
336 ),
337 Self::ReasoningSummary { metadata, .. } => {
338 crate::model_response::validate_output_metadata(
339 ModelOutputItemKind::ReasoningSummary,
340 metadata,
341 ContentSource::Model,
342 )
343 }
344 Self::ToolCall { .. } => Ok(()),
345 }
346 }
347
348 fn inline_header_bytes(&self) -> usize {
349 match self {
350 Self::ToolCall { extensions, .. } => extensions.compact_bytes(),
351 Self::Text { .. }
352 | Self::Json { .. }
353 | Self::Artifact(_)
354 | Self::ReasoningSummary { .. } => 0,
355 }
356 }
357}
358
359#[derive(Deserialize)]
360#[serde(
361 tag = "type",
362 content = "content",
363 rename_all = "snake_case",
364 deny_unknown_fields
365)]
366enum ModelOutputStartWire {
367 Text {
368 #[serde(default)]
369 language: Option<LanguageTag>,
370 metadata: ContentMetadata,
371 },
372 Json {
373 #[serde(default)]
374 schema: Option<SchemaReference>,
375 metadata: ContentMetadata,
376 },
377 Artifact(Box<ArtifactRef>),
378 ReasoningSummary {
379 #[serde(default)]
380 language: Option<LanguageTag>,
381 metadata: ContentMetadata,
382 },
383 ToolCall {
384 tool: CapabilityIdentity,
385 #[serde(default)]
386 provider_call_id: Option<ModelProviderToolCallId>,
387 extensions: Extensions,
388 },
389}
390
391impl<'de> Deserialize<'de> for ModelOutputStart {
392 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
393 where
394 D: Deserializer<'de>,
395 {
396 let value = match ModelOutputStartWire::deserialize(deserializer)? {
397 ModelOutputStartWire::Text { language, metadata } => Self::Text { language, metadata },
398 ModelOutputStartWire::Json { schema, metadata } => Self::Json { schema, metadata },
399 ModelOutputStartWire::Artifact(artifact) => Self::Artifact(artifact),
400 ModelOutputStartWire::ReasoningSummary { language, metadata } => {
401 Self::ReasoningSummary { language, metadata }
402 }
403 ModelOutputStartWire::ToolCall {
404 tool,
405 provider_call_id,
406 extensions,
407 } => Self::ToolCall {
408 tool,
409 provider_call_id,
410 extensions,
411 },
412 };
413 value.validate_intrinsic().map_err(de::Error::custom)?;
414 Ok(value)
415 }
416}
417
418#[derive(
420 Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, Ord, PartialEq, PartialOrd, Serialize,
421)]
422#[non_exhaustive]
423#[serde(rename_all = "snake_case")]
424pub enum ModelOutputDeltaKind {
425 Text,
427 Json,
429 ReasoningSummary,
431 ToolArguments,
433}
434
435#[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
437#[serde(
438 tag = "type",
439 content = "delta",
440 rename_all = "snake_case",
441 deny_unknown_fields
442)]
443pub enum ModelOutputDelta {
444 Text(ModelStreamChunk),
446 Json(ModelStreamChunk),
448 ReasoningSummary(ModelStreamChunk),
450 ToolArguments(ModelStreamChunk),
452}
453
454impl ModelOutputDelta {
455 #[must_use]
457 pub const fn kind(&self) -> ModelOutputDeltaKind {
458 match self {
459 Self::Text(_) => ModelOutputDeltaKind::Text,
460 Self::Json(_) => ModelOutputDeltaKind::Json,
461 Self::ReasoningSummary(_) => ModelOutputDeltaKind::ReasoningSummary,
462 Self::ToolArguments(_) => ModelOutputDeltaKind::ToolArguments,
463 }
464 }
465
466 #[must_use]
468 pub const fn chunk(&self) -> &ModelStreamChunk {
469 match self {
470 Self::Text(chunk)
471 | Self::Json(chunk)
472 | Self::ReasoningSummary(chunk)
473 | Self::ToolArguments(chunk) => chunk,
474 }
475 }
476
477 fn into_chunk(self) -> ModelStreamChunk {
478 match self {
479 Self::Text(chunk)
480 | Self::Json(chunk)
481 | Self::ReasoningSummary(chunk)
482 | Self::ToolArguments(chunk) => chunk,
483 }
484 }
485}
486
487#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
494#[serde(deny_unknown_fields)]
495pub struct ModelEvent {
496 attempt_id: AttemptId,
497 sequence: ExecutionCount,
498 event: ModelEventKind,
499}
500
501impl ModelEvent {
502 pub const MAX_EVENTS_PER_ATTEMPT: ExecutionCount =
504 ExecutionCount::new(MAX_EVENTS_PER_ATTEMPT_VALUE);
505 pub const MAX_SEQUENCE: ExecutionCount = ExecutionCount::new(MAX_EVENTS_PER_ATTEMPT_VALUE - 1);
507
508 pub fn new(
515 attempt_id: AttemptId,
516 sequence: ExecutionCount,
517 event: ModelEventKind,
518 ) -> Result<Self, ModelEventError> {
519 if sequence >= Self::MAX_EVENTS_PER_ATTEMPT {
520 return Err(ModelEventError::SequenceOutOfRange {
521 maximum: Self::MAX_SEQUENCE,
522 actual: sequence,
523 });
524 }
525 if let Some(output_index) = event.output_index() {
526 let maximum_exclusive = ExecutionCount::new(ModelResponse::MAX_OUTPUT_ITEMS as u64);
527 if output_index >= maximum_exclusive {
528 return Err(ModelEventError::OutputIndexOutOfRange {
529 maximum_exclusive,
530 actual: output_index,
531 });
532 }
533 }
534 match &event {
535 ModelEventKind::Started { provenance } if provenance.attempt_id() != attempt_id => {
536 return Err(ModelEventError::StartedAttemptMismatch {
537 event: attempt_id,
538 provenance: provenance.attempt_id(),
539 });
540 }
541 ModelEventKind::OutputStarted { start, .. } => start
542 .validate_intrinsic()
543 .map_err(|error| ModelEventError::InvalidOutputStart { error })?,
544 ModelEventKind::Started { .. }
545 | ModelEventKind::OutputDelta { .. }
546 | ModelEventKind::OutputCompleted { .. }
547 | ModelEventKind::UsageUpdated { .. }
548 | ModelEventKind::Completed { .. } => {}
549 }
550 Ok(Self {
551 attempt_id,
552 sequence,
553 event,
554 })
555 }
556
557 #[must_use]
559 pub const fn attempt_id(&self) -> AttemptId {
560 self.attempt_id
561 }
562
563 #[must_use]
565 pub const fn sequence(&self) -> ExecutionCount {
566 self.sequence
567 }
568
569 #[must_use]
571 pub const fn event(&self) -> &ModelEventKind {
572 &self.event
573 }
574}
575
576#[derive(Deserialize)]
577#[serde(deny_unknown_fields)]
578struct ModelEventWire {
579 attempt_id: AttemptId,
580 sequence: ExecutionCount,
581 event: ModelEventKind,
582}
583
584impl<'de> Deserialize<'de> for ModelEvent {
585 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
586 where
587 D: Deserializer<'de>,
588 {
589 let wire = ModelEventWire::deserialize(deserializer)?;
590 Self::new(wire.attempt_id, wire.sequence, wire.event).map_err(de::Error::custom)
591 }
592}
593
594#[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
596#[serde(
597 tag = "type",
598 content = "content",
599 rename_all = "snake_case",
600 deny_unknown_fields
601)]
602pub enum ModelEventKind {
603 Started {
605 provenance: ModelResponseProvenance,
607 },
608 OutputStarted {
610 output_index: ExecutionCount,
612 start: Box<ModelOutputStart>,
614 },
615 OutputDelta {
617 output_index: ExecutionCount,
619 delta: ModelOutputDelta,
621 },
622 OutputCompleted {
624 output_index: ExecutionCount,
626 },
627 UsageUpdated {
629 usage: ModelUsage,
631 },
632 Completed {
634 finish_reason: ModelFinishReason,
636 usage: ModelUsage,
638 extensions: Extensions,
640 },
641}
642
643impl ModelEventKind {
644 fn output_index(&self) -> Option<ExecutionCount> {
645 match self {
646 Self::OutputStarted { output_index, .. }
647 | Self::OutputDelta { output_index, .. }
648 | Self::OutputCompleted { output_index } => Some(*output_index),
649 Self::Started { .. } | Self::UsageUpdated { .. } | Self::Completed { .. } => None,
650 }
651 }
652}
653
654#[derive(Clone, Debug, Eq, Error, PartialEq)]
656#[non_exhaustive]
657pub enum ModelEventError {
658 #[error("model event sequence {actual} exceeds maximum {maximum}")]
660 SequenceOutOfRange {
661 maximum: ExecutionCount,
663 actual: ExecutionCount,
665 },
666 #[error("model output index {actual} must be less than {maximum_exclusive}")]
668 OutputIndexOutOfRange {
669 maximum_exclusive: ExecutionCount,
671 actual: ExecutionCount,
673 },
674 #[error("model event attempt {event} does not match start provenance attempt {provenance}")]
676 StartedAttemptMismatch {
677 event: AttemptId,
679 provenance: AttemptId,
681 },
682 #[error("invalid streamed model output header: {error}")]
684 InvalidOutputStart {
685 #[source]
687 error: ModelOutputItemError,
688 },
689}
690
691#[derive(
693 Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, Ord, PartialEq, PartialOrd, Serialize,
694)]
695#[non_exhaustive]
696#[serde(rename_all = "snake_case")]
697pub enum ModelUsageField {
698 InputTokens,
700 CachedInputTokens,
702 OutputTokens,
704 ReasoningTokens,
706}
707
708enum OutputSlot {
709 Active {
710 start: ModelOutputStart,
711 buffer: String,
712 },
713 Completed(ModelOutputItem),
714 Transitioning,
715}
716
717pub struct ModelEventAccumulator<'a> {
724 descriptor: &'a ModelDescriptor,
725 request: &'a ModelRequest,
726 attempt_id: AttemptId,
727 next_sequence: ExecutionCount,
728 started: bool,
729 poisoned: bool,
730 provenance: Option<ModelResponseProvenance>,
731 slots: Vec<OutputSlot>,
732 content_items: usize,
733 tool_calls: usize,
734 provider_call_ids: BTreeSet<ModelProviderToolCallId>,
735 retained_inline_bytes: usize,
736 last_usage: Option<ModelUsage>,
737 response: Option<ModelResponse>,
738}
739
740impl<'a> ModelEventAccumulator<'a> {
741 pub fn new(
750 attempt_id: AttemptId,
751 descriptor: &'a ModelDescriptor,
752 request: &'a ModelRequest,
753 ) -> Result<Self, ModelEventStreamError> {
754 if request.response_mode() != ModelResponseMode::Streaming {
755 return Err(ModelEventStreamError::RequestNotStreaming);
756 }
757 descriptor
758 .capabilities()
759 .satisfies(request.requirements())
760 .map_err(|mismatch| ModelEventStreamError::CapabilityMismatch { mismatch })?;
761 Ok(Self {
762 descriptor,
763 request,
764 attempt_id,
765 next_sequence: ExecutionCount::ZERO,
766 started: false,
767 poisoned: false,
768 provenance: None,
769 slots: Vec::new(),
770 content_items: 0,
771 tool_calls: 0,
772 provider_call_ids: BTreeSet::new(),
773 retained_inline_bytes: 0,
774 last_usage: None,
775 response: None,
776 })
777 }
778
779 pub fn push(&mut self, event: ModelEvent) -> Result<(), ModelEventStreamError> {
785 if self.poisoned {
786 return Err(ModelEventStreamError::Poisoned);
787 }
788 if self.response.is_some() {
789 self.poisoned = true;
790 return Err(ModelEventStreamError::AlreadyCompleted);
791 }
792 if let Err(error) = self.try_push(event) {
793 self.poisoned = true;
794 return Err(error);
795 }
796 Ok(())
797 }
798
799 pub fn finish(self) -> Result<ModelResponse, ModelEventStreamError> {
806 if self.poisoned {
807 return Err(ModelEventStreamError::Poisoned);
808 }
809 self.response.ok_or(ModelEventStreamError::UnexpectedEnd {
810 next_sequence: self.next_sequence,
811 })
812 }
813
814 #[must_use]
816 pub const fn attempt_id(&self) -> AttemptId {
817 self.attempt_id
818 }
819
820 #[must_use]
822 pub const fn next_sequence(&self) -> ExecutionCount {
823 self.next_sequence
824 }
825
826 #[must_use]
828 pub const fn is_complete(&self) -> bool {
829 self.response.is_some() && !self.poisoned
830 }
831
832 #[must_use]
834 pub const fn is_poisoned(&self) -> bool {
835 self.poisoned
836 }
837
838 fn try_push(&mut self, event: ModelEvent) -> Result<(), ModelEventStreamError> {
839 let ModelEvent {
840 attempt_id,
841 sequence,
842 event,
843 } = event;
844 if attempt_id != self.attempt_id {
845 return Err(ModelEventStreamError::AttemptMismatch {
846 expected: self.attempt_id,
847 actual: attempt_id,
848 });
849 }
850 if sequence != self.next_sequence {
851 return Err(ModelEventStreamError::SequenceMismatch {
852 expected: self.next_sequence,
853 actual: sequence,
854 });
855 }
856
857 let is_start = matches!(event, ModelEventKind::Started { .. });
858 if !self.started && !is_start {
859 return Err(ModelEventStreamError::EventBeforeStart);
860 }
861 if self.started && is_start {
862 return Err(ModelEventStreamError::DuplicateStart);
863 }
864
865 match event {
866 ModelEventKind::Started { provenance } => self.process_start(provenance)?,
867 ModelEventKind::OutputStarted {
868 output_index,
869 start,
870 } => self.process_output_start(output_index, *start)?,
871 ModelEventKind::OutputDelta {
872 output_index,
873 delta,
874 } => self.process_output_delta(output_index, delta)?,
875 ModelEventKind::OutputCompleted { output_index } => {
876 self.process_output_completed(output_index)?;
877 }
878 ModelEventKind::UsageUpdated { usage } => self.process_usage(usage)?,
879 ModelEventKind::Completed {
880 finish_reason,
881 usage,
882 extensions,
883 } => self.process_completed(finish_reason, usage, extensions)?,
884 }
885
886 self.next_sequence = ExecutionCount::new(
887 sequence
888 .get()
889 .checked_add(1)
890 .expect("intrinsically bounded model event sequence cannot overflow"),
891 );
892 Ok(())
893 }
894
895 fn process_start(
896 &mut self,
897 provenance: ModelResponseProvenance,
898 ) -> Result<(), ModelEventStreamError> {
899 let expected = self.descriptor.metadata().identity();
900 if provenance.model() != expected {
901 return Err(invalid_response(
902 ModelResponseError::ModelIdentityMismatch {
903 expected: Box::new(expected.clone()),
904 actual: Box::new(provenance.model().clone()),
905 },
906 ));
907 }
908 self.provenance = Some(provenance);
909 self.started = true;
910 Ok(())
911 }
912
913 fn process_output_start(
914 &mut self,
915 output_index: ExecutionCount,
916 start: ModelOutputStart,
917 ) -> Result<(), ModelEventStreamError> {
918 let expected = ExecutionCount::new(self.slots.len() as u64);
919 if output_index != expected {
920 return Err(ModelEventStreamError::OutputStartOutOfOrder {
921 expected,
922 actual: output_index,
923 });
924 }
925
926 match start.kind() {
927 ModelOutputItemKind::Content | ModelOutputItemKind::ReasoningSummary => {
928 if self.content_items == ModelResponse::MAX_CONTENT_ITEMS {
929 return Err(invalid_response(ModelResponseError::TooManyContentItems {
930 max: ModelResponse::MAX_CONTENT_ITEMS,
931 observed: ModelResponse::MAX_CONTENT_ITEMS + 1,
932 }));
933 }
934 self.content_items += 1;
935 }
936 ModelOutputItemKind::ToolCall => {
937 if self.tool_calls == ModelResponse::MAX_TOOL_CALLS {
938 return Err(invalid_response(ModelResponseError::TooManyToolCalls {
939 max: ModelResponse::MAX_TOOL_CALLS,
940 observed: ModelResponse::MAX_TOOL_CALLS + 1,
941 }));
942 }
943 let next_calls = self.tool_calls + 1;
944 if ExecutionCount::new(next_calls as u64)
945 > self.request.max_tool_calls_per_response()
946 {
947 return Err(invalid_response(
948 ModelResponseError::ToolCallsExceedRequest {
949 maximum: self.request.max_tool_calls_per_response(),
950 actual: ExecutionCount::new(next_calls as u64),
951 },
952 ));
953 }
954 if let ModelOutputStart::ToolCall {
955 provider_call_id: Some(provider_call_id),
956 ..
957 } = &start
958 {
959 if !self.provider_call_ids.insert(provider_call_id.clone()) {
960 return Err(invalid_response(
961 ModelResponseError::DuplicateProviderToolCallId,
962 ));
963 }
964 }
965 self.tool_calls = next_calls;
966 }
967 }
968
969 let observed = self
970 .retained_inline_bytes
971 .checked_add(start.inline_header_bytes())
972 .ok_or(ModelEventStreamError::PayloadAccountingOverflow)?;
973 validate_aggregate_payload(observed)?;
974 self.retained_inline_bytes = observed;
975 self.slots.push(OutputSlot::Active {
976 start,
977 buffer: String::new(),
978 });
979 Ok(())
980 }
981
982 fn process_output_delta(
983 &mut self,
984 output_index: ExecutionCount,
985 delta: ModelOutputDelta,
986 ) -> Result<(), ModelEventStreamError> {
987 let index = usize::try_from(output_index.get())
988 .expect("intrinsically bounded model output index fits usize");
989 let slot = self
990 .slots
991 .get_mut(index)
992 .ok_or(ModelEventStreamError::OutputNotStarted { output_index })?;
993 let (start, buffer) = match slot {
994 OutputSlot::Active { start, buffer } => (start, buffer),
995 OutputSlot::Completed(_) | OutputSlot::Transitioning => {
996 return Err(ModelEventStreamError::OutputAlreadyCompleted { output_index });
997 }
998 };
999
1000 let actual_kind = delta.kind();
1001 let Some(expected_kind) = start.delta_kind() else {
1002 return Err(ModelEventStreamError::OutputDoesNotAcceptDeltas { output_index });
1003 };
1004 if actual_kind != expected_kind {
1005 return Err(ModelEventStreamError::DeltaKindMismatch {
1006 output_index,
1007 expected: expected_kind,
1008 actual: actual_kind,
1009 });
1010 }
1011
1012 let chunk = delta.into_chunk();
1013 let observed_item = buffer
1014 .len()
1015 .checked_add(chunk.len_bytes())
1016 .ok_or(ModelEventStreamError::PayloadAccountingOverflow)?;
1017 let maximum = match expected_kind {
1018 ModelOutputDeltaKind::Text | ModelOutputDeltaKind::ReasoningSummary => {
1019 TextContent::MAX_BYTES
1020 }
1021 ModelOutputDeltaKind::Json | ModelOutputDeltaKind::ToolArguments => {
1022 JsonLimits::DEFAULT.max_bytes()
1023 }
1024 };
1025 if observed_item > maximum {
1026 return Err(ModelEventStreamError::OutputPayloadTooLarge {
1027 output_index,
1028 maximum,
1029 actual: observed_item,
1030 });
1031 }
1032 let observed_total = self
1033 .retained_inline_bytes
1034 .checked_add(chunk.len_bytes())
1035 .ok_or(ModelEventStreamError::PayloadAccountingOverflow)?;
1036 validate_aggregate_payload(observed_total)?;
1037
1038 buffer.push_str(chunk.as_str());
1039 self.retained_inline_bytes = observed_total;
1040 Ok(())
1041 }
1042
1043 fn process_output_completed(
1044 &mut self,
1045 output_index: ExecutionCount,
1046 ) -> Result<(), ModelEventStreamError> {
1047 let index = usize::try_from(output_index.get())
1048 .expect("intrinsically bounded model output index fits usize");
1049 let slot = self
1050 .slots
1051 .get_mut(index)
1052 .ok_or(ModelEventStreamError::OutputNotStarted { output_index })?;
1053 let active = match mem::replace(slot, OutputSlot::Transitioning) {
1054 OutputSlot::Active { start, buffer } => (start, buffer),
1055 OutputSlot::Completed(item) => {
1056 *slot = OutputSlot::Completed(item);
1057 return Err(ModelEventStreamError::OutputAlreadyCompleted { output_index });
1058 }
1059 OutputSlot::Transitioning => {
1060 return Err(ModelEventStreamError::OutputAlreadyCompleted { output_index });
1061 }
1062 };
1063 let old_bytes = active
1064 .0
1065 .inline_header_bytes()
1066 .checked_add(active.1.len())
1067 .ok_or(ModelEventStreamError::PayloadAccountingOverflow)?;
1068 let item = finish_output_item(output_index, active.0, active.1)?;
1069 let base = self
1070 .retained_inline_bytes
1071 .checked_sub(old_bytes)
1072 .ok_or(ModelEventStreamError::PayloadAccountingOverflow)?;
1073 let observed = base
1074 .checked_add(item.inline_payload_bytes())
1075 .ok_or(ModelEventStreamError::PayloadAccountingOverflow)?;
1076 validate_aggregate_payload(observed)?;
1077 self.retained_inline_bytes = observed;
1078 *slot = OutputSlot::Completed(item);
1079 Ok(())
1080 }
1081
1082 fn process_usage(&mut self, usage: ModelUsage) -> Result<(), ModelEventStreamError> {
1083 validate_usage_progress(self.last_usage.as_ref(), &usage)?;
1084 validate_usage_limits(self.request, &usage)?;
1085 self.last_usage = Some(usage);
1086 Ok(())
1087 }
1088
1089 fn process_completed(
1090 &mut self,
1091 finish_reason: ModelFinishReason,
1092 usage: ModelUsage,
1093 extensions: Extensions,
1094 ) -> Result<(), ModelEventStreamError> {
1095 validate_usage_progress(self.last_usage.as_ref(), &usage)?;
1096 validate_usage_limits(self.request, &usage)?;
1097 if let Some((index, _)) = self
1098 .slots
1099 .iter()
1100 .enumerate()
1101 .find(|(_, slot)| !matches!(slot, OutputSlot::Completed(_)))
1102 {
1103 return Err(ModelEventStreamError::OutputStillOpen {
1104 output_index: ExecutionCount::new(index as u64),
1105 });
1106 }
1107
1108 let provenance = self
1109 .provenance
1110 .take()
1111 .expect("a terminal model event is impossible before a validated start");
1112 let output = mem::take(&mut self.slots)
1113 .into_iter()
1114 .map(|slot| match slot {
1115 OutputSlot::Completed(item) => item,
1116 OutputSlot::Active { .. } | OutputSlot::Transitioning => {
1117 unreachable!("all streamed model outputs were checked complete")
1118 }
1119 })
1120 .collect::<Vec<_>>();
1121 let response = ModelResponse::new(
1122 provenance,
1123 self.descriptor,
1124 self.request,
1125 output,
1126 finish_reason,
1127 usage,
1128 extensions,
1129 )
1130 .map_err(invalid_response)?;
1131 debug_assert_eq!(
1132 response.inline_payload_bytes().get(),
1133 self.retained_inline_bytes as u64
1134 );
1135 self.response = Some(response);
1136 Ok(())
1137 }
1138}
1139
1140impl fmt::Debug for ModelEventAccumulator<'_> {
1141 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1142 formatter
1143 .debug_struct("ModelEventAccumulator")
1144 .field("attempt_id", &self.attempt_id)
1145 .field("next_sequence", &self.next_sequence)
1146 .field("started", &self.started)
1147 .field("poisoned", &self.poisoned)
1148 .field("output_slots", &self.slots.len())
1149 .field("content_items", &self.content_items)
1150 .field("tool_calls", &self.tool_calls)
1151 .field("retained_inline_bytes", &self.retained_inline_bytes)
1152 .field("has_usage", &self.last_usage.is_some())
1153 .field("complete", &self.is_complete())
1154 .finish_non_exhaustive()
1155 }
1156}
1157
1158fn finish_output_item(
1159 output_index: ExecutionCount,
1160 start: ModelOutputStart,
1161 buffer: String,
1162) -> Result<ModelOutputItem, ModelEventStreamError> {
1163 match start {
1164 ModelOutputStart::Text { language, metadata } => {
1165 let content =
1166 TextContent::from_string(buffer, language, metadata).map_err(|error| {
1167 ModelEventStreamError::InvalidTextPayload {
1168 output_index,
1169 error,
1170 }
1171 })?;
1172 ModelOutputItem::content(ContentPart::Text(content)).map_err(|error| {
1173 ModelEventStreamError::InvalidOutputItem {
1174 output_index,
1175 error,
1176 }
1177 })
1178 }
1179 ModelOutputStart::Json { schema, metadata } => {
1180 let value = BoundedJson::from_slice(buffer.as_bytes()).map_err(|error| {
1181 ModelEventStreamError::InvalidJsonPayload {
1182 output_index,
1183 error,
1184 }
1185 })?;
1186 ModelOutputItem::content(ContentPart::Json(JsonContent::new(value, schema, metadata)))
1187 .map_err(|error| ModelEventStreamError::InvalidOutputItem {
1188 output_index,
1189 error,
1190 })
1191 }
1192 ModelOutputStart::Artifact(artifact) => {
1193 debug_assert!(buffer.is_empty());
1194 ModelOutputItem::content(ContentPart::Artifact(artifact)).map_err(|error| {
1195 ModelEventStreamError::InvalidOutputItem {
1196 output_index,
1197 error,
1198 }
1199 })
1200 }
1201 ModelOutputStart::ReasoningSummary { language, metadata } => {
1202 let content =
1203 TextContent::from_string(buffer, language, metadata).map_err(|error| {
1204 ModelEventStreamError::InvalidTextPayload {
1205 output_index,
1206 error,
1207 }
1208 })?;
1209 ModelOutputItem::reasoning_summary(content).map_err(|error| {
1210 ModelEventStreamError::InvalidOutputItem {
1211 output_index,
1212 error,
1213 }
1214 })
1215 }
1216 ModelOutputStart::ToolCall {
1217 tool,
1218 provider_call_id,
1219 extensions,
1220 } => {
1221 let arguments = BoundedJson::from_slice(buffer.as_bytes()).map_err(|error| {
1222 ModelEventStreamError::InvalidJsonPayload {
1223 output_index,
1224 error,
1225 }
1226 })?;
1227 let proposal =
1228 ModelToolCallProposal::new(tool, provider_call_id, arguments, extensions).map_err(
1229 |error| ModelEventStreamError::InvalidToolCall {
1230 output_index,
1231 error,
1232 },
1233 )?;
1234 Ok(ModelOutputItem::tool_call(proposal))
1235 }
1236 }
1237}
1238
1239fn validate_aggregate_payload(observed: usize) -> Result<(), ModelEventStreamError> {
1240 let maximum = ModelResponse::MAX_INLINE_PAYLOAD_BYTES;
1241 if observed as u64 > maximum.get() {
1242 return Err(ModelEventStreamError::InlinePayloadTooLarge {
1243 maximum,
1244 observed: ByteCount::new(observed as u64),
1245 });
1246 }
1247 Ok(())
1248}
1249
1250fn validate_usage_limits(
1251 request: &ModelRequest,
1252 usage: &ModelUsage,
1253) -> Result<(), ModelEventStreamError> {
1254 if usage.input_tokens() > request.limits().max_input_tokens() {
1255 return Err(invalid_response(
1256 ModelResponseError::InputUsageExceedsRequest {
1257 maximum: request.limits().max_input_tokens(),
1258 actual: usage.input_tokens(),
1259 },
1260 ));
1261 }
1262 if usage.output_tokens() > request.limits().max_output_tokens() {
1263 return Err(invalid_response(
1264 ModelResponseError::OutputUsageExceedsRequest {
1265 maximum: request.limits().max_output_tokens(),
1266 actual: usage.output_tokens(),
1267 },
1268 ));
1269 }
1270 Ok(())
1271}
1272
1273fn validate_usage_progress(
1274 previous: Option<&ModelUsage>,
1275 actual: &ModelUsage,
1276) -> Result<(), ModelEventStreamError> {
1277 let Some(previous) = previous else {
1278 return Ok(());
1279 };
1280 validate_required_usage_field(
1281 ModelUsageField::InputTokens,
1282 previous.input_tokens(),
1283 actual.input_tokens(),
1284 )?;
1285 validate_optional_usage_field(
1286 ModelUsageField::CachedInputTokens,
1287 previous.cached_input_tokens(),
1288 actual.cached_input_tokens(),
1289 )?;
1290 validate_required_usage_field(
1291 ModelUsageField::OutputTokens,
1292 previous.output_tokens(),
1293 actual.output_tokens(),
1294 )?;
1295 validate_optional_usage_field(
1296 ModelUsageField::ReasoningTokens,
1297 previous.reasoning_tokens(),
1298 actual.reasoning_tokens(),
1299 )
1300}
1301
1302fn validate_required_usage_field(
1303 field: ModelUsageField,
1304 previous: TokenCount,
1305 actual: TokenCount,
1306) -> Result<(), ModelEventStreamError> {
1307 if actual < previous {
1308 return Err(ModelEventStreamError::UsageDecreased {
1309 field,
1310 previous,
1311 actual,
1312 });
1313 }
1314 Ok(())
1315}
1316
1317fn validate_optional_usage_field(
1318 field: ModelUsageField,
1319 previous: Option<TokenCount>,
1320 actual: Option<TokenCount>,
1321) -> Result<(), ModelEventStreamError> {
1322 match (previous, actual) {
1323 (Some(_), None) => Err(ModelEventStreamError::UsageBreakdownDisappeared { field }),
1324 (Some(previous), Some(actual)) => validate_required_usage_field(field, previous, actual),
1325 (None, None | Some(_)) => Ok(()),
1326 }
1327}
1328
1329fn invalid_response(error: ModelResponseError) -> ModelEventStreamError {
1330 ModelEventStreamError::InvalidResponse { error }
1331}
1332
1333#[derive(Clone, Debug, Eq, Error, PartialEq)]
1335#[non_exhaustive]
1336pub enum ModelEventStreamError {
1337 #[error("model event accumulator requires a streaming model request")]
1339 RequestNotStreaming,
1340 #[error("model descriptor cannot satisfy streaming request: {mismatch}")]
1342 CapabilityMismatch {
1343 #[source]
1345 mismatch: ModelCapabilityMismatch,
1346 },
1347 #[error("model event accumulator is poisoned by a prior validation failure")]
1349 Poisoned,
1350 #[error("model event stream is already complete")]
1352 AlreadyCompleted,
1353 #[error("model event attempt {actual} does not match expected attempt {expected}")]
1355 AttemptMismatch {
1356 expected: AttemptId,
1358 actual: AttemptId,
1360 },
1361 #[error("model event sequence {actual} does not match expected sequence {expected}")]
1363 SequenceMismatch {
1364 expected: ExecutionCount,
1366 actual: ExecutionCount,
1368 },
1369 #[error("model event stream must begin with started")]
1371 EventBeforeStart,
1372 #[error("model event stream contains more than one started event")]
1374 DuplicateStart,
1375 #[error("model output start index {actual} does not match next index {expected}")]
1377 OutputStartOutOfOrder {
1378 expected: ExecutionCount,
1380 actual: ExecutionCount,
1382 },
1383 #[error("model output index {output_index} has not started")]
1385 OutputNotStarted {
1386 output_index: ExecutionCount,
1388 },
1389 #[error("model output index {output_index} is already complete")]
1391 OutputAlreadyCompleted {
1392 output_index: ExecutionCount,
1394 },
1395 #[error("model output index {output_index} does not accept deltas")]
1397 OutputDoesNotAcceptDeltas {
1398 output_index: ExecutionCount,
1400 },
1401 #[error("model output index {output_index} expected {expected:?} delta, got {actual:?}")]
1403 DeltaKindMismatch {
1404 output_index: ExecutionCount,
1406 expected: ModelOutputDeltaKind,
1408 actual: ModelOutputDeltaKind,
1410 },
1411 #[error("model output index {output_index} accumulated {actual} bytes; maximum is {maximum}")]
1413 OutputPayloadTooLarge {
1414 output_index: ExecutionCount,
1416 maximum: usize,
1418 actual: usize,
1420 },
1421 #[error("model event stream payload-byte accounting overflowed")]
1423 PayloadAccountingOverflow,
1424 #[error("model event stream retains {observed} inline bytes; maximum is {maximum}")]
1426 InlinePayloadTooLarge {
1427 maximum: ByteCount,
1429 observed: ByteCount,
1431 },
1432 #[error("model output index {output_index} contains invalid text: {error}")]
1434 InvalidTextPayload {
1435 output_index: ExecutionCount,
1437 #[source]
1439 error: TextContentError,
1440 },
1441 #[error("model output index {output_index} contains invalid JSON: {error}")]
1443 InvalidJsonPayload {
1444 output_index: ExecutionCount,
1446 #[source]
1448 error: BoundedJsonError,
1449 },
1450 #[error("model output index {output_index} contains an invalid tool call: {error}")]
1452 InvalidToolCall {
1453 output_index: ExecutionCount,
1455 #[source]
1457 error: ModelToolCallProposalError,
1458 },
1459 #[error("model output index {output_index} is invalid: {error}")]
1461 InvalidOutputItem {
1462 output_index: ExecutionCount,
1464 #[source]
1466 error: ModelOutputItemError,
1467 },
1468 #[error("model usage {field:?} decreased from {previous} to {actual}")]
1470 UsageDecreased {
1471 field: ModelUsageField,
1473 previous: TokenCount,
1475 actual: TokenCount,
1477 },
1478 #[error("model usage {field:?} disappeared after it was reported")]
1480 UsageBreakdownDisappeared {
1481 field: ModelUsageField,
1483 },
1484 #[error("model output index {output_index} is still open at stream completion")]
1486 OutputStillOpen {
1487 output_index: ExecutionCount,
1489 },
1490 #[error("invalid assembled model response: {error}")]
1492 InvalidResponse {
1493 #[source]
1495 error: ModelResponseError,
1496 },
1497 #[error("model event stream ended before completion; next sequence is {next_sequence}")]
1499 UnexpectedEnd {
1500 next_sequence: ExecutionCount,
1502 },
1503}
1504
1505#[cfg(test)]
1506mod tests {
1507 use super::*;
1508 use crate::{
1509 Instruction, ModelProviderModelId, ModelProviderResponseId, ModelRequestBuilder,
1510 ModelRequestLimits, ModelTextOutputFormat, ModelToolSelection, SecurityLabel,
1511 ToolDescriptor,
1512 };
1513 use proptest::prelude::*;
1514 use serde_json::{Value, from_value, json, to_value};
1515
1516 const MEBIBYTE: u64 = 1024 * 1024;
1517
1518 fn fixture(path: &[&str], source: &str) -> Value {
1519 let mut value = serde_json::from_str::<Value>(source).unwrap();
1520 for segment in path {
1521 value = value[*segment].clone();
1522 }
1523 value
1524 }
1525
1526 fn descriptor(name: &str) -> ModelDescriptor {
1527 let values = fixture(
1528 &["descriptors", "valid"],
1529 include_str!("../tests/fixtures/core-model-descriptor-v1.json"),
1530 );
1531 let mut value = values[0].clone();
1532 value["metadata"]["identity"]["capability"]["name"] = Value::from(name);
1533 value["capabilities"] = fixture(
1534 &["capabilities", "valid"],
1535 include_str!("../tests/fixtures/core-model-capability-v1.json"),
1536 )[1]
1537 .clone();
1538 from_value(value).unwrap()
1539 }
1540
1541 fn non_streaming_descriptor(name: &str) -> ModelDescriptor {
1542 let values = fixture(
1543 &["descriptors", "valid"],
1544 include_str!("../tests/fixtures/core-model-descriptor-v1.json"),
1545 );
1546 let mut value = values[0].clone();
1547 value["metadata"]["identity"]["capability"]["name"] = Value::from(name);
1548 from_value(value).unwrap()
1549 }
1550
1551 fn instruction() -> Instruction {
1552 let values = fixture(
1553 &["instructions", "valid"],
1554 include_str!("../tests/fixtures/core-message-v1.json"),
1555 );
1556 from_value(values[0].clone()).unwrap()
1557 }
1558
1559 fn tool(name: &str) -> ToolDescriptor {
1560 let values = fixture(
1561 &["descriptors", "valid"],
1562 include_str!("../tests/fixtures/core-tool-v1.json"),
1563 );
1564 let mut value = values[0].clone();
1565 value["metadata"]["identity"]["capability"]["name"] = Value::from(name);
1566 from_value(value).unwrap()
1567 }
1568
1569 fn limits() -> ModelRequestLimits {
1570 ModelRequestLimits::new(
1571 TokenCount::new(8_192),
1572 TokenCount::new(1_024),
1573 ByteCount::new(MEBIBYTE),
1574 )
1575 .unwrap()
1576 }
1577
1578 fn streaming_builder() -> ModelRequestBuilder {
1579 ModelRequest::builder(limits())
1580 .instruction(instruction())
1581 .response_mode(ModelResponseMode::Streaming)
1582 }
1583
1584 fn streaming_request() -> ModelRequest {
1585 streaming_builder().build().unwrap()
1586 }
1587
1588 fn attempt() -> AttemptId {
1589 "01912345-6789-7abc-8def-0123456789ab".parse().unwrap()
1590 }
1591
1592 fn provenance(descriptor: &ModelDescriptor) -> ModelResponseProvenance {
1593 ModelResponseProvenance::new(
1594 attempt(),
1595 descriptor.metadata().identity().clone(),
1596 Some(ModelProviderModelId::new("provider/model-v1").unwrap()),
1597 Some(ModelProviderResponseId::new("response_opaque-42").unwrap()),
1598 )
1599 }
1600
1601 fn model_metadata() -> ContentMetadata {
1602 ContentMetadata::untrusted(
1603 ContentSource::Model,
1604 SecurityLabel::new("internal/model-output").unwrap(),
1605 )
1606 }
1607
1608 fn usage(input: u64, cached: Option<u64>, output: u64, reasoning: Option<u64>) -> ModelUsage {
1609 ModelUsage::new(
1610 TokenCount::new(input),
1611 cached.map(TokenCount::new),
1612 TokenCount::new(output),
1613 reasoning.map(TokenCount::new),
1614 )
1615 .unwrap()
1616 }
1617
1618 fn event(sequence: u64, event: ModelEventKind) -> ModelEvent {
1619 ModelEvent::new(attempt(), ExecutionCount::new(sequence), event).unwrap()
1620 }
1621
1622 fn started(sequence: u64, descriptor: &ModelDescriptor) -> ModelEvent {
1623 event(
1624 sequence,
1625 ModelEventKind::Started {
1626 provenance: provenance(descriptor),
1627 },
1628 )
1629 }
1630
1631 fn text_start(sequence: u64, index: u64) -> ModelEvent {
1632 event(
1633 sequence,
1634 ModelEventKind::OutputStarted {
1635 output_index: ExecutionCount::new(index),
1636 start: Box::new(ModelOutputStart::text(None, model_metadata()).unwrap()),
1637 },
1638 )
1639 }
1640
1641 fn text_delta(sequence: u64, index: u64, value: &str) -> ModelEvent {
1642 event(
1643 sequence,
1644 ModelEventKind::OutputDelta {
1645 output_index: ExecutionCount::new(index),
1646 delta: ModelOutputDelta::Text(ModelStreamChunk::new(value).unwrap()),
1647 },
1648 )
1649 }
1650
1651 fn output_completed(sequence: u64, index: u64) -> ModelEvent {
1652 event(
1653 sequence,
1654 ModelEventKind::OutputCompleted {
1655 output_index: ExecutionCount::new(index),
1656 },
1657 )
1658 }
1659
1660 fn completed(sequence: u64, finish_reason: ModelFinishReason, usage: ModelUsage) -> ModelEvent {
1661 event(
1662 sequence,
1663 ModelEventKind::Completed {
1664 finish_reason,
1665 usage,
1666 extensions: Extensions::default(),
1667 },
1668 )
1669 }
1670
1671 #[test]
1672 fn stream_chunks_are_exact_bounded_redacted_values() {
1673 let chunk = ModelStreamChunk::new("confidential\n片段").unwrap();
1674 assert_eq!(chunk.as_str(), "confidential\n片段");
1675 assert_eq!(chunk.len_bytes(), "confidential\n片段".len());
1676 assert_eq!(to_value(&chunk).unwrap(), "confidential\n片段");
1677 assert_eq!(
1678 from_value::<ModelStreamChunk>(json!("exact"))
1679 .unwrap()
1680 .as_str(),
1681 "exact"
1682 );
1683 assert!(!format!("{chunk:?}").contains("confidential"));
1684
1685 assert_eq!(ModelStreamChunk::new(""), Err(ModelStreamChunkError::Empty));
1686 assert!(matches!(
1687 ModelStreamChunk::new("x".repeat(ModelStreamChunk::MAX_BYTES + 1)),
1688 Err(ModelStreamChunkError::TooLong { .. })
1689 ));
1690 assert!(matches!(
1691 ModelStreamChunk::new("bad\u{0000}"),
1692 Err(ModelStreamChunkError::DisallowedCodePoint { .. })
1693 ));
1694 assert!(matches!(
1695 ModelStreamChunk::new("bad\u{ffff}"),
1696 Err(ModelStreamChunkError::DisallowedCodePoint { .. })
1697 ));
1698 assert!(from_value::<ModelStreamChunk>(json!(42)).is_err());
1699
1700 let schema = to_value(schemars::schema_for!(ModelStreamChunk)).unwrap();
1701 assert_eq!(schema["minLength"], 1);
1702 assert_eq!(schema["maxLength"], ModelStreamChunk::MAX_BYTES);
1703 }
1704
1705 #[test]
1706 fn output_headers_reject_false_trust_and_wrong_sources() {
1707 let controlled = ContentMetadata::new(
1708 ContentSource::Model,
1709 crate::ContentTrust::ApplicationControlled,
1710 SecurityLabel::new("internal/model-output").unwrap(),
1711 crate::RedactionState::NotApplied,
1712 );
1713 assert!(matches!(
1714 ModelOutputStart::text(None, controlled),
1715 Err(ModelOutputItemError::InvalidTrust { .. })
1716 ));
1717
1718 let wrong = ContentMetadata::untrusted(
1719 ContentSource::User,
1720 SecurityLabel::new("internal/model-output").unwrap(),
1721 );
1722 assert!(matches!(
1723 ModelOutputStart::json(None, wrong),
1724 Err(ModelOutputItemError::InvalidSource { .. })
1725 ));
1726
1727 let mut encoded =
1728 to_value(ModelOutputStart::text(None, model_metadata()).unwrap()).unwrap();
1729 encoded["content"]["metadata"]["trust"] = Value::from("application_controlled");
1730 assert!(from_value::<ModelOutputStart>(encoded).is_err());
1731 }
1732
1733 #[test]
1734 fn event_envelopes_enforce_attempt_and_resource_bounds() {
1735 let descriptor = descriptor("models.primary");
1736 let other_attempt = "01912345-6789-7abc-8def-0123456789ac".parse().unwrap();
1737 assert!(matches!(
1738 ModelEvent::new(
1739 other_attempt,
1740 ExecutionCount::ZERO,
1741 ModelEventKind::Started {
1742 provenance: provenance(&descriptor)
1743 }
1744 ),
1745 Err(ModelEventError::StartedAttemptMismatch { .. })
1746 ));
1747 assert!(matches!(
1748 ModelEvent::new(
1749 attempt(),
1750 ModelEvent::MAX_EVENTS_PER_ATTEMPT,
1751 ModelEventKind::UsageUpdated {
1752 usage: usage(1, None, 0, None)
1753 }
1754 ),
1755 Err(ModelEventError::SequenceOutOfRange { .. })
1756 ));
1757 assert!(matches!(
1758 ModelEvent::new(
1759 attempt(),
1760 ExecutionCount::ZERO,
1761 ModelEventKind::OutputCompleted {
1762 output_index: ExecutionCount::new(ModelResponse::MAX_OUTPUT_ITEMS as u64)
1763 }
1764 ),
1765 Err(ModelEventError::OutputIndexOutOfRange { .. })
1766 ));
1767
1768 let encoded = to_value(started(0, &descriptor)).unwrap();
1769 assert_eq!(encoded["sequence"], "0");
1770 assert_eq!(
1771 from_value::<ModelEvent>(encoded.clone()).unwrap(),
1772 started(0, &descriptor)
1773 );
1774 let mut unknown = encoded;
1775 unknown["unknown"] = Value::Bool(true);
1776 assert!(from_value::<ModelEvent>(unknown).is_err());
1777 }
1778
1779 #[test]
1780 fn text_stream_converges_to_one_bound_response() {
1781 let descriptor = descriptor("models.primary");
1782 let request = streaming_request();
1783 let mut accumulator = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
1784 let events = [
1785 started(0, &descriptor),
1786 text_start(1, 0),
1787 text_delta(2, 0, "hel"),
1788 event(
1789 3,
1790 ModelEventKind::UsageUpdated {
1791 usage: usage(120, Some(20), 1, None),
1792 },
1793 ),
1794 text_delta(4, 0, "lo"),
1795 output_completed(5, 0),
1796 completed(
1797 6,
1798 ModelFinishReason::Completed,
1799 usage(120, Some(20), 2, None),
1800 ),
1801 ];
1802 for event in events {
1803 accumulator.push(event).unwrap();
1804 }
1805
1806 assert!(accumulator.is_complete());
1807 let response = accumulator.finish().unwrap();
1808 assert_eq!(response.provenance(), &provenance(&descriptor));
1809 assert_eq!(response.finish_reason(), ModelFinishReason::Completed);
1810 assert_eq!(response.usage(), &usage(120, Some(20), 2, None));
1811 assert_eq!(response.inline_payload_bytes(), ByteCount::new(5));
1812 assert_eq!(
1813 response.output()[0]
1814 .as_content()
1815 .and_then(|content| match content {
1816 ContentPart::Text(text) => Some(text.text()),
1817 ContentPart::Json(_) | ContentPart::Artifact(_) => None,
1818 }),
1819 Some("hello")
1820 );
1821 }
1822
1823 #[test]
1824 fn json_fragments_are_parsed_once_when_the_item_closes() {
1825 let descriptor = descriptor("models.primary");
1826 let request = streaming_builder()
1827 .text_output_format(Some(ModelTextOutputFormat::json()))
1828 .build()
1829 .unwrap();
1830 let mut accumulator = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
1831 let events = [
1832 started(0, &descriptor),
1833 event(
1834 1,
1835 ModelEventKind::OutputStarted {
1836 output_index: ExecutionCount::ZERO,
1837 start: Box::new(ModelOutputStart::json(None, model_metadata()).unwrap()),
1838 },
1839 ),
1840 event(
1841 2,
1842 ModelEventKind::OutputDelta {
1843 output_index: ExecutionCount::ZERO,
1844 delta: ModelOutputDelta::Json(ModelStreamChunk::new("{\"answer\":").unwrap()),
1845 },
1846 ),
1847 event(
1848 3,
1849 ModelEventKind::OutputDelta {
1850 output_index: ExecutionCount::ZERO,
1851 delta: ModelOutputDelta::Json(ModelStreamChunk::new("42}").unwrap()),
1852 },
1853 ),
1854 output_completed(4, 0),
1855 completed(5, ModelFinishReason::Completed, usage(10, None, 3, None)),
1856 ];
1857 for event in events {
1858 accumulator.push(event).unwrap();
1859 }
1860 let response = accumulator.finish().unwrap();
1861 let json = match response.output()[0].as_content().unwrap() {
1862 ContentPart::Json(json) => json,
1863 ContentPart::Text(_) | ContentPart::Artifact(_) => panic!("expected JSON"),
1864 };
1865 assert_eq!(json.value().as_value(), &json!({"answer": 42}));
1866 }
1867
1868 #[test]
1869 fn malformed_or_duplicate_json_poison_the_stream() {
1870 for raw in ["{", "{\"a\":1,\"a\":2}", "{} trailing"] {
1871 let descriptor = descriptor("models.primary");
1872 let request = streaming_builder()
1873 .text_output_format(Some(ModelTextOutputFormat::json()))
1874 .build()
1875 .unwrap();
1876 let mut accumulator =
1877 ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
1878 accumulator.push(started(0, &descriptor)).unwrap();
1879 accumulator
1880 .push(event(
1881 1,
1882 ModelEventKind::OutputStarted {
1883 output_index: ExecutionCount::ZERO,
1884 start: Box::new(ModelOutputStart::json(None, model_metadata()).unwrap()),
1885 },
1886 ))
1887 .unwrap();
1888 accumulator
1889 .push(event(
1890 2,
1891 ModelEventKind::OutputDelta {
1892 output_index: ExecutionCount::ZERO,
1893 delta: ModelOutputDelta::Json(ModelStreamChunk::new(raw).unwrap()),
1894 },
1895 ))
1896 .unwrap();
1897 assert!(matches!(
1898 accumulator.push(output_completed(3, 0)),
1899 Err(ModelEventStreamError::InvalidJsonPayload { .. })
1900 ));
1901 assert_eq!(
1902 accumulator.push(completed(
1903 3,
1904 ModelFinishReason::Completed,
1905 usage(1, None, 1, None)
1906 )),
1907 Err(ModelEventStreamError::Poisoned)
1908 );
1909 }
1910 }
1911
1912 #[test]
1913 fn already_started_outputs_may_interleave_without_reordering_results() {
1914 let descriptor = descriptor("models.primary");
1915 let request = streaming_builder()
1916 .reasoning_summaries(true)
1917 .build()
1918 .unwrap();
1919 let mut accumulator = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
1920 let events = [
1921 started(0, &descriptor),
1922 text_start(1, 0),
1923 text_delta(2, 0, "visible "),
1924 event(
1925 3,
1926 ModelEventKind::OutputStarted {
1927 output_index: ExecutionCount::new(1),
1928 start: Box::new(
1929 ModelOutputStart::reasoning_summary(None, model_metadata()).unwrap(),
1930 ),
1931 },
1932 ),
1933 event(
1934 4,
1935 ModelEventKind::OutputDelta {
1936 output_index: ExecutionCount::new(1),
1937 delta: ModelOutputDelta::ReasoningSummary(
1938 ModelStreamChunk::new("summary").unwrap(),
1939 ),
1940 },
1941 ),
1942 text_delta(5, 0, "answer"),
1943 output_completed(6, 1),
1944 output_completed(7, 0),
1945 completed(8, ModelFinishReason::Completed, usage(10, None, 4, Some(1))),
1946 ];
1947 for event in events {
1948 accumulator.push(event).unwrap();
1949 }
1950 let response = accumulator.finish().unwrap();
1951 assert_eq!(response.output()[0].kind(), ModelOutputItemKind::Content);
1952 assert_eq!(
1953 response.output()[1].kind(),
1954 ModelOutputItemKind::ReasoningSummary
1955 );
1956 }
1957
1958 #[test]
1959 fn tool_argument_fragments_become_an_unapproved_proposal() {
1960 let descriptor = descriptor("models.primary");
1961 let requested_tool = tool("tools.lookup");
1962 let request = streaming_builder()
1963 .tool(requested_tool.clone())
1964 .tool_selection(ModelToolSelection::auto())
1965 .max_tool_calls_per_response(ExecutionCount::new(2))
1966 .build()
1967 .unwrap();
1968 let mut accumulator = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
1969 let events = [
1970 started(0, &descriptor),
1971 event(
1972 1,
1973 ModelEventKind::OutputStarted {
1974 output_index: ExecutionCount::ZERO,
1975 start: Box::new(ModelOutputStart::tool_call(
1976 requested_tool.metadata().identity().clone(),
1977 Some(ModelProviderToolCallId::new("call_42").unwrap()),
1978 Extensions::default(),
1979 )),
1980 },
1981 ),
1982 event(
1983 2,
1984 ModelEventKind::OutputDelta {
1985 output_index: ExecutionCount::ZERO,
1986 delta: ModelOutputDelta::ToolArguments(
1987 ModelStreamChunk::new("{\"incident_id\":").unwrap(),
1988 ),
1989 },
1990 ),
1991 event(
1992 3,
1993 ModelEventKind::OutputDelta {
1994 output_index: ExecutionCount::ZERO,
1995 delta: ModelOutputDelta::ToolArguments(ModelStreamChunk::new("42}").unwrap()),
1996 },
1997 ),
1998 output_completed(4, 0),
1999 completed(5, ModelFinishReason::ToolCalls, usage(20, None, 8, None)),
2000 ];
2001 for event in events {
2002 accumulator.push(event).unwrap();
2003 }
2004 let response = accumulator.finish().unwrap();
2005 let proposal = response.tool_calls().next().unwrap();
2006 assert_eq!(proposal.tool(), requested_tool.metadata().identity());
2007 assert_eq!(proposal.provider_call_id().unwrap().as_str(), "call_42");
2008 assert_eq!(proposal.arguments().as_value(), &json!({"incident_id": 42}));
2009 }
2010
2011 #[test]
2012 fn duplicate_tool_ids_and_non_object_arguments_never_commit() {
2013 let descriptor = descriptor("models.primary");
2014 let requested_tool = tool("tools.lookup");
2015 let request = streaming_builder()
2016 .tool(requested_tool.clone())
2017 .tool_selection(ModelToolSelection::auto())
2018 .max_tool_calls_per_response(ExecutionCount::new(2))
2019 .build()
2020 .unwrap();
2021
2022 let start = |sequence, index| {
2023 event(
2024 sequence,
2025 ModelEventKind::OutputStarted {
2026 output_index: ExecutionCount::new(index),
2027 start: Box::new(ModelOutputStart::tool_call(
2028 requested_tool.metadata().identity().clone(),
2029 Some(ModelProviderToolCallId::new("call_duplicate").unwrap()),
2030 Extensions::default(),
2031 )),
2032 },
2033 )
2034 };
2035 let mut duplicate = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2036 duplicate.push(started(0, &descriptor)).unwrap();
2037 duplicate.push(start(1, 0)).unwrap();
2038 assert!(matches!(
2039 duplicate.push(start(2, 1)),
2040 Err(ModelEventStreamError::InvalidResponse {
2041 error: ModelResponseError::DuplicateProviderToolCallId
2042 })
2043 ));
2044
2045 let mut scalar = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2046 scalar.push(started(0, &descriptor)).unwrap();
2047 scalar.push(start(1, 0)).unwrap();
2048 scalar
2049 .push(event(
2050 2,
2051 ModelEventKind::OutputDelta {
2052 output_index: ExecutionCount::ZERO,
2053 delta: ModelOutputDelta::ToolArguments(ModelStreamChunk::new("42").unwrap()),
2054 },
2055 ))
2056 .unwrap();
2057 assert!(matches!(
2058 scalar.push(output_completed(3, 0)),
2059 Err(ModelEventStreamError::InvalidToolCall {
2060 error: ModelToolCallProposalError::ArgumentsMustBeObject,
2061 ..
2062 })
2063 ));
2064 }
2065
2066 #[test]
2067 fn noncomplete_text_may_commit_but_tool_fragments_cannot_masquerade_as_output() {
2068 let descriptor = descriptor("models.primary");
2069 let text_request = streaming_request();
2070 let mut partial =
2071 ModelEventAccumulator::new(attempt(), &descriptor, &text_request).unwrap();
2072 for event in [
2073 started(0, &descriptor),
2074 text_start(1, 0),
2075 text_delta(2, 0, "partial but typed"),
2076 output_completed(3, 0),
2077 completed(4, ModelFinishReason::OutputLimit, usage(5, None, 3, None)),
2078 ] {
2079 partial.push(event).unwrap();
2080 }
2081 let response = partial.finish().unwrap();
2082 assert_eq!(response.finish_reason(), ModelFinishReason::OutputLimit);
2083 assert_eq!(response.output().len(), 1);
2084
2085 let requested_tool = tool("tools.lookup");
2086 let tool_request = streaming_builder()
2087 .tool(requested_tool.clone())
2088 .tool_selection(ModelToolSelection::auto())
2089 .max_tool_calls_per_response(ExecutionCount::new(1))
2090 .build()
2091 .unwrap();
2092 let mut tool_stream =
2093 ModelEventAccumulator::new(attempt(), &descriptor, &tool_request).unwrap();
2094 tool_stream.push(started(0, &descriptor)).unwrap();
2095 tool_stream
2096 .push(event(
2097 1,
2098 ModelEventKind::OutputStarted {
2099 output_index: ExecutionCount::ZERO,
2100 start: Box::new(ModelOutputStart::tool_call(
2101 requested_tool.metadata().identity().clone(),
2102 None,
2103 Extensions::default(),
2104 )),
2105 },
2106 ))
2107 .unwrap();
2108 tool_stream
2109 .push(event(
2110 2,
2111 ModelEventKind::OutputDelta {
2112 output_index: ExecutionCount::ZERO,
2113 delta: ModelOutputDelta::ToolArguments(
2114 ModelStreamChunk::new("{\"id\":").unwrap(),
2115 ),
2116 },
2117 ))
2118 .unwrap();
2119 assert!(matches!(
2120 tool_stream.push(completed(
2121 3,
2122 ModelFinishReason::OutputLimit,
2123 usage(5, None, 3, None)
2124 )),
2125 Err(ModelEventStreamError::OutputStillOpen { .. })
2126 ));
2127 }
2128
2129 #[test]
2130 fn stream_order_attempt_and_delta_type_fail_closed() {
2131 let descriptor = descriptor("models.primary");
2132 let request = streaming_request();
2133
2134 let mut before_start =
2135 ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2136 assert_eq!(
2137 before_start.push(text_start(0, 0)),
2138 Err(ModelEventStreamError::EventBeforeStart)
2139 );
2140 assert!(before_start.is_poisoned());
2141
2142 let mut gap = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2143 gap.push(started(0, &descriptor)).unwrap();
2144 assert!(matches!(
2145 gap.push(text_start(2, 0)),
2146 Err(ModelEventStreamError::SequenceMismatch { .. })
2147 ));
2148
2149 let mut output_gap = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2150 output_gap.push(started(0, &descriptor)).unwrap();
2151 assert!(matches!(
2152 output_gap.push(text_start(1, 1)),
2153 Err(ModelEventStreamError::OutputStartOutOfOrder { .. })
2154 ));
2155
2156 let mut wrong_delta = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2157 wrong_delta.push(started(0, &descriptor)).unwrap();
2158 wrong_delta.push(text_start(1, 0)).unwrap();
2159 assert!(matches!(
2160 wrong_delta.push(event(
2161 2,
2162 ModelEventKind::OutputDelta {
2163 output_index: ExecutionCount::ZERO,
2164 delta: ModelOutputDelta::Json(ModelStreamChunk::new("{}").unwrap())
2165 }
2166 )),
2167 Err(ModelEventStreamError::DeltaKindMismatch { .. })
2168 ));
2169
2170 let mut wrong_attempt =
2171 ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2172 wrong_attempt.push(started(0, &descriptor)).unwrap();
2173 let other_attempt = "01912345-6789-7abc-8def-0123456789ac".parse().unwrap();
2174 let other = ModelEvent::new(
2175 other_attempt,
2176 ExecutionCount::new(1),
2177 ModelEventKind::UsageUpdated {
2178 usage: usage(1, None, 0, None),
2179 },
2180 )
2181 .unwrap();
2182 assert!(matches!(
2183 wrong_attempt.push(other),
2184 Err(ModelEventStreamError::AttemptMismatch { .. })
2185 ));
2186 }
2187
2188 #[test]
2189 fn usage_snapshots_are_cumulative_monotonic_and_bounded() {
2190 let descriptor = descriptor("models.primary");
2191 let request = streaming_request();
2192 let mut accumulator = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2193 accumulator.push(started(0, &descriptor)).unwrap();
2194 accumulator
2195 .push(event(
2196 1,
2197 ModelEventKind::UsageUpdated {
2198 usage: usage(100, Some(20), 10, Some(2)),
2199 },
2200 ))
2201 .unwrap();
2202 assert!(matches!(
2203 accumulator.push(event(
2204 2,
2205 ModelEventKind::UsageUpdated {
2206 usage: usage(100, Some(19), 11, Some(2))
2207 }
2208 )),
2209 Err(ModelEventStreamError::UsageDecreased {
2210 field: ModelUsageField::CachedInputTokens,
2211 ..
2212 })
2213 ));
2214
2215 let mut disappeared = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2216 disappeared.push(started(0, &descriptor)).unwrap();
2217 disappeared
2218 .push(event(
2219 1,
2220 ModelEventKind::UsageUpdated {
2221 usage: usage(100, Some(20), 10, None),
2222 },
2223 ))
2224 .unwrap();
2225 assert!(matches!(
2226 disappeared.push(completed(
2227 2,
2228 ModelFinishReason::Completed,
2229 usage(100, None, 11, None)
2230 )),
2231 Err(ModelEventStreamError::UsageBreakdownDisappeared {
2232 field: ModelUsageField::CachedInputTokens
2233 })
2234 ));
2235
2236 let mut excessive = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2237 excessive.push(started(0, &descriptor)).unwrap();
2238 assert!(matches!(
2239 excessive.push(event(
2240 1,
2241 ModelEventKind::UsageUpdated {
2242 usage: usage(8_193, None, 1, None)
2243 }
2244 )),
2245 Err(ModelEventStreamError::InvalidResponse {
2246 error: ModelResponseError::InputUsageExceedsRequest { .. }
2247 })
2248 ));
2249 }
2250
2251 #[test]
2252 fn open_or_truncated_streams_never_become_responses() {
2253 let descriptor = descriptor("models.primary");
2254 let request = streaming_request();
2255 let mut open = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2256 open.push(started(0, &descriptor)).unwrap();
2257 open.push(text_start(1, 0)).unwrap();
2258 open.push(text_delta(2, 0, "partial")).unwrap();
2259 assert!(matches!(
2260 open.push(completed(
2261 3,
2262 ModelFinishReason::OutputLimit,
2263 usage(4, None, 2, None)
2264 )),
2265 Err(ModelEventStreamError::OutputStillOpen { .. })
2266 ));
2267
2268 let mut truncated = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2269 truncated.push(started(0, &descriptor)).unwrap();
2270 assert_eq!(
2271 truncated.finish(),
2272 Err(ModelEventStreamError::UnexpectedEnd {
2273 next_sequence: ExecutionCount::new(1)
2274 })
2275 );
2276 }
2277
2278 #[test]
2279 fn empty_plain_completion_needs_only_start_and_terminal() {
2280 let descriptor = descriptor("models.primary");
2281 let request = streaming_request();
2282 let mut accumulator = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2283 accumulator.push(started(0, &descriptor)).unwrap();
2284 accumulator
2285 .push(completed(
2286 1,
2287 ModelFinishReason::Completed,
2288 usage(4, None, 1, None),
2289 ))
2290 .unwrap();
2291 assert!(accumulator.finish().unwrap().output().is_empty());
2292 }
2293
2294 #[test]
2295 fn trailing_events_poison_an_otherwise_complete_stream() {
2296 let descriptor = descriptor("models.primary");
2297 let request = streaming_request();
2298 let mut accumulator = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2299 accumulator.push(started(0, &descriptor)).unwrap();
2300 accumulator
2301 .push(completed(
2302 1,
2303 ModelFinishReason::Completed,
2304 usage(4, None, 1, None),
2305 ))
2306 .unwrap();
2307 assert!(accumulator.is_complete());
2308 assert_eq!(
2309 accumulator.push(event(
2310 2,
2311 ModelEventKind::UsageUpdated {
2312 usage: usage(4, None, 1, None)
2313 }
2314 )),
2315 Err(ModelEventStreamError::AlreadyCompleted)
2316 );
2317 assert!(accumulator.is_poisoned());
2318 assert!(!accumulator.is_complete());
2319 assert_eq!(accumulator.finish(), Err(ModelEventStreamError::Poisoned));
2320 }
2321
2322 #[test]
2323 fn complete_requests_and_wrong_model_provenance_are_rejected() {
2324 let primary = descriptor("models.primary");
2325 let complete_request = ModelRequest::builder(limits())
2326 .instruction(instruction())
2327 .build()
2328 .unwrap();
2329 assert!(matches!(
2330 ModelEventAccumulator::new(attempt(), &primary, &complete_request),
2331 Err(ModelEventStreamError::RequestNotStreaming)
2332 ));
2333
2334 let request = streaming_request();
2335 let non_streaming = non_streaming_descriptor("models.primary");
2336 assert!(matches!(
2337 ModelEventAccumulator::new(attempt(), &non_streaming, &request),
2338 Err(ModelEventStreamError::CapabilityMismatch { .. })
2339 ));
2340
2341 let other = descriptor("models.other");
2342 let mut accumulator = ModelEventAccumulator::new(attempt(), &primary, &request).unwrap();
2343 assert!(matches!(
2344 accumulator.push(started(0, &other)),
2345 Err(ModelEventStreamError::InvalidResponse {
2346 error: ModelResponseError::ModelIdentityMismatch { .. }
2347 })
2348 ));
2349 }
2350
2351 #[test]
2352 fn per_item_stream_buffer_is_bounded_before_materialization() {
2353 let descriptor = descriptor("models.primary");
2354 let request = streaming_request();
2355 let mut accumulator = ModelEventAccumulator::new(attempt(), &descriptor, &request).unwrap();
2356 accumulator.push(started(0, &descriptor)).unwrap();
2357 accumulator.push(text_start(1, 0)).unwrap();
2358 let full_chunk = "x".repeat(ModelStreamChunk::MAX_BYTES);
2359 for sequence in 2..6 {
2360 accumulator
2361 .push(text_delta(sequence, 0, &full_chunk))
2362 .unwrap();
2363 }
2364 assert!(matches!(
2365 accumulator.push(text_delta(6, 0, "x")),
2366 Err(ModelEventStreamError::OutputPayloadTooLarge {
2367 maximum: TextContent::MAX_BYTES,
2368 actual,
2369 ..
2370 }) if actual == TextContent::MAX_BYTES + 1
2371 ));
2372 }
2373
2374 #[test]
2375 fn event_schemas_close_envelopes_and_tagged_variants() {
2376 let event = to_value(schemars::schema_for!(ModelEvent)).unwrap();
2377 assert_eq!(event["type"], "object");
2378 assert_eq!(event["additionalProperties"], false);
2379 let required = event["required"].as_array().unwrap();
2380 for field in ["attempt_id", "sequence", "event"] {
2381 assert!(required.contains(&Value::from(field)));
2382 }
2383
2384 for schema in [
2385 to_value(schemars::schema_for!(ModelOutputStart)).unwrap(),
2386 to_value(schemars::schema_for!(ModelOutputDelta)).unwrap(),
2387 to_value(schemars::schema_for!(ModelEventKind)).unwrap(),
2388 ] {
2389 let variants = schema["oneOf"].as_array().unwrap();
2390 assert!(!variants.is_empty());
2391 assert!(
2392 variants
2393 .iter()
2394 .all(|variant| variant["additionalProperties"] == false)
2395 );
2396 }
2397 }
2398
2399 proptest! {
2400 #[test]
2401 fn safe_ascii_chunks_round_trip_exactly(value in "[ -~\\n\\r\\t]{1,4096}") {
2402 let chunk = ModelStreamChunk::new(value.clone()).unwrap();
2403 let encoded = to_value(&chunk).unwrap();
2404 let decoded = from_value::<ModelStreamChunk>(encoded).unwrap();
2405 prop_assert_eq!(decoded.as_str(), value);
2406 }
2407 }
2408}