reef_core/runtime/model.rs
1//! Owned model requests and strict provider-neutral stream grammar.
2//!
3//! The request carries two tool lanes: client-local tools are explicit
4//! descriptors, while provider-hosted capabilities remain opaque extensions.
5//! The stream grammar states delta and final lifecycles explicitly, so a
6//! provider adapter cannot leave a consumer guessing which it received.
7
8use std::collections::{HashMap, HashSet};
9use std::error::Error;
10use std::fmt;
11use std::future::Future;
12
13use futures_core::Stream;
14
15use crate::opaque::{Envelope, Payload};
16use crate::redact;
17use crate::transcript::item::{Assistant, Item, ModelVisibility};
18use crate::value::content::{
19 KnownPartKind, Part, Segment, SegmentExtensions, is_valid_system_instruction,
20};
21use crate::value::tool_call::{self, Id, ToolCall};
22
23/// One client-executed tool advertised to the model.
24#[derive(Clone)]
25pub struct ClientTool {
26 name: tool_call::Name,
27 description: String,
28 input_schema: Payload,
29}
30
31impl fmt::Debug for ClientTool {
32 /// Names the tool and sizes what the model would read about it.
33 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
34 formatter
35 .debug_struct("ClientTool")
36 .field("name", &self.name)
37 .field("description", &redact::Bytes(self.description.len()))
38 .field("input_schema", &self.input_schema)
39 .finish()
40 }
41}
42
43impl ClientTool {
44 /// Creates an owned local-tool descriptor.
45 #[must_use]
46 pub const fn new(name: tool_call::Name, description: String, input_schema: Payload) -> Self {
47 Self {
48 name,
49 description,
50 input_schema,
51 }
52 }
53
54 /// Returns the canonical tool name.
55 #[must_use]
56 pub const fn name(&self) -> &tool_call::Name {
57 &self.name
58 }
59
60 /// Returns the model-facing description.
61 #[must_use]
62 pub fn description(&self) -> &str {
63 &self.description
64 }
65
66 /// Returns the provider-neutral input schema bytes.
67 ///
68 /// Uninterpreted: core never parses them, so this is where a per-tool
69 /// constrained-sampling setting — a strict schema, a grammar, or a provider
70 /// envelope around either — reaches the adapter that wrote it.
71 #[must_use]
72 pub const fn input_schema(&self) -> &Payload {
73 &self.input_schema
74 }
75}
76
77/// Provider-neutral tool-selection behavior.
78#[derive(Clone, Debug)]
79pub enum ToolChoice {
80 /// Let the model decide whether to call a tool.
81 Auto,
82 /// Disable tool calls.
83 None,
84 /// Require some tool call.
85 Required,
86 /// Require one named local tool.
87 Specific(tool_call::Name),
88}
89
90/// Sampling controls for one model request.
91#[derive(Clone, Default)]
92#[non_exhaustive]
93pub struct SamplingParams {
94 /// Sampling temperature; absent delegates to the provider.
95 pub temperature: Option<f64>,
96 /// Provider-neutral reasoning effort label.
97 pub reasoning_effort: Option<String>,
98 /// Maximum generated token count.
99 pub max_output_tokens: Option<u64>,
100 /// Whether parallel tool calls are requested.
101 pub parallel_tool_calls: bool,
102 /// Optional structured-output schema bytes.
103 ///
104 /// This constrains the *response*. Constraining one tool's arguments is a
105 /// per-tool concern and travels in that tool's
106 /// [`ClientTool::input_schema`], which core likewise never parses.
107 pub output_schema: Option<Payload>,
108 /// Ordered generation stop strings.
109 pub stop_sequences: Vec<String>,
110 /// Optional tool-selection constraint.
111 pub tool_choice: Option<ToolChoice>,
112}
113
114impl fmt::Debug for SamplingParams {
115 /// Prints the controls that classify a request and counts the strings.
116 ///
117 /// `stop_sequences` is the one field here that carries text bound for the
118 /// model, and a `Vec<String>` has no element type that redacts itself, so it
119 /// reports a length instead.
120 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
121 formatter
122 .debug_struct("SamplingParams")
123 .field("temperature", &self.temperature)
124 .field("reasoning_effort", &self.reasoning_effort)
125 .field("max_output_tokens", &self.max_output_tokens)
126 .field("parallel_tool_calls", &self.parallel_tool_calls)
127 .field("output_schema", &self.output_schema)
128 .field("stop_sequences", &redact::Items(self.stop_sequences.len()))
129 .field("tool_choice", &self.tool_choice)
130 .finish()
131 }
132}
133
134/// A stable failure while projecting owned transcript items into a model request.
135#[derive(Clone, Debug, Eq, PartialEq)]
136#[non_exhaustive]
137pub enum RequestError {
138 /// A system-instruction text block was empty.
139 #[non_exhaustive]
140 EmptySystemInstructionText {
141 /// Zero-based block position.
142 index: usize,
143 },
144 /// A system-instruction block had a known, non-text kind.
145 #[non_exhaustive]
146 NonTextSystemInstruction {
147 /// Zero-based block position.
148 index: usize,
149 /// Original canonical numeric kind.
150 kind: i64,
151 },
152 /// A system-instruction block had no portable interpretation.
153 #[non_exhaustive]
154 UnknownSystemInstruction {
155 /// Zero-based block position.
156 index: usize,
157 /// Original canonical numeric kind.
158 kind: i64,
159 },
160 /// A new user, system, or assistant item appeared before all preceding calls closed.
161 ToolExchangeNotClosed,
162 /// An assistant tool call had an empty correlation identity.
163 EmptyToolCallId,
164 /// An assistant tool call had an empty tool name.
165 #[non_exhaustive]
166 EmptyToolCallName {
167 /// Nonempty call identity whose name was empty.
168 call_id: String,
169 },
170 /// An assistant tool-call identity was reused anywhere in the request.
171 #[non_exhaustive]
172 DuplicateToolCallId {
173 /// Reused global call identity.
174 call_id: String,
175 },
176 /// A model-visible tool result had an empty correlation identity.
177 EmptyToolResultId,
178 /// A model-visible tool result had an empty tool name.
179 #[non_exhaustive]
180 EmptyToolResultName {
181 /// Nonempty pending call identity.
182 call_id: String,
183 },
184 /// A model-visible tool result did not correspond to a pending call.
185 #[non_exhaustive]
186 OrphanToolResult {
187 /// Result identity that was not pending.
188 call_id: String,
189 },
190 /// A model-visible result named a different tool from its pending call.
191 #[non_exhaustive]
192 ToolResultNameMismatch {
193 /// Pending call identity.
194 call_id: String,
195 /// Tool name recorded by the assistant call.
196 expected: String,
197 /// Tool name recorded by the result.
198 actual: String,
199 },
200 /// End-of-history arrived with calls that had no model-visible results.
201 #[non_exhaustive]
202 UnresolvedToolCalls {
203 /// Number of still-pending calls.
204 count: usize,
205 },
206}
207
208impl fmt::Display for RequestError {
209 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
210 match self {
211 Self::EmptySystemInstructionText { index } => {
212 write!(
213 formatter,
214 "system instruction text at index {index} is empty"
215 )
216 }
217 Self::NonTextSystemInstruction { index, kind } => write!(
218 formatter,
219 "system instruction part at index {index} has non-text kind {kind}"
220 ),
221 Self::UnknownSystemInstruction { index, kind } => write!(
222 formatter,
223 "system instruction part at index {index} has unknown kind {kind}"
224 ),
225 Self::ToolExchangeNotClosed => {
226 formatter.write_str("message appears before the preceding tool exchange is closed")
227 }
228 Self::EmptyToolCallId => formatter.write_str("assistant tool call id is empty"),
229 Self::EmptyToolCallName { call_id } => {
230 write!(formatter, "assistant tool call {call_id} has an empty name")
231 }
232 Self::DuplicateToolCallId { call_id } => {
233 write!(formatter, "duplicate assistant tool call id: {call_id}")
234 }
235 Self::EmptyToolResultId => formatter.write_str("tool result call id is empty"),
236 Self::EmptyToolResultName { call_id } => {
237 write!(formatter, "tool result {call_id} has an empty name")
238 }
239 Self::OrphanToolResult { call_id } => {
240 write!(formatter, "orphan tool result: {call_id}")
241 }
242 Self::ToolResultNameMismatch {
243 call_id,
244 expected,
245 actual,
246 } => write!(
247 formatter,
248 "tool result {call_id} names {actual}, expected {expected}"
249 ),
250 Self::UnresolvedToolCalls { count } => {
251 write!(
252 formatter,
253 "request ends with {count} unresolved tool call(s)"
254 )
255 }
256 }
257 }
258}
259
260impl Error for RequestError {}
261
262/// Mutable preparation for exactly one model request.
263///
264/// ```compile_fail
265/// use reef_core::runtime::model;
266/// let plan = model::RequestPlan::new();
267/// let request = plan.try_into_request(vec![]).unwrap();
268/// plan.sampling_mut(); // freezing consumes the only mutable preparation value
269/// # drop(request);
270/// ```
271#[derive(Clone, Debug, Default)]
272pub struct RequestPlan {
273 system_instruction: Vec<Part>,
274 tools: Vec<ClientTool>,
275 params: SamplingParams,
276 extensions: Vec<Envelope>,
277 ephemeral: Vec<Part>,
278}
279
280impl RequestPlan {
281 /// Creates an empty per-Step preparation value.
282 #[must_use]
283 pub fn new() -> Self {
284 Self::default()
285 }
286
287 /// Returns the ordered system instruction.
288 #[must_use]
289 pub fn system_instruction(&self) -> &[Part] {
290 &self.system_instruction
291 }
292
293 /// Appends one system-instruction block.
294 pub fn push_system_instruction(&mut self, part: Part) -> &mut Self {
295 self.system_instruction.push(part);
296 self
297 }
298
299 /// Appends system-instruction blocks in iteration order.
300 pub fn extend_system_instruction(
301 &mut self,
302 parts: impl IntoIterator<Item = Part>,
303 ) -> &mut Self {
304 self.system_instruction.extend(parts);
305 self
306 }
307
308 /// Removes every system-instruction block.
309 pub fn clear_system_instruction(&mut self) -> &mut Self {
310 self.system_instruction.clear();
311 self
312 }
313
314 /// Returns the client-local tool lane.
315 #[must_use]
316 pub fn tools(&self) -> &[ClientTool] {
317 &self.tools
318 }
319
320 /// Appends one client-local tool descriptor.
321 pub fn push_tool(&mut self, tool: ClientTool) -> &mut Self {
322 self.tools.push(tool);
323 self
324 }
325
326 /// Appends client-local tool descriptors in iteration order.
327 pub fn extend_tools(&mut self, tools: impl IntoIterator<Item = ClientTool>) -> &mut Self {
328 self.tools.extend(tools);
329 self
330 }
331
332 /// Removes every client-local tool descriptor.
333 pub fn clear_tools(&mut self) -> &mut Self {
334 self.tools.clear();
335 self
336 }
337
338 /// Returns the sampling controls for mutation.
339 pub const fn sampling_mut(&mut self) -> &mut SamplingParams {
340 &mut self.params
341 }
342
343 /// Returns the provider-hosted extension lane.
344 #[must_use]
345 pub fn extensions(&self) -> &[Envelope] {
346 &self.extensions
347 }
348
349 /// Appends one provider-hosted extension.
350 pub fn push_extension(&mut self, extension: Envelope) -> &mut Self {
351 self.extensions.push(extension);
352 self
353 }
354
355 /// Appends provider-hosted extensions in iteration order.
356 pub fn extend_extensions(
357 &mut self,
358 extensions: impl IntoIterator<Item = Envelope>,
359 ) -> &mut Self {
360 self.extensions.extend(extensions);
361 self
362 }
363
364 /// Removes every provider-hosted extension.
365 pub fn clear_extensions(&mut self) -> &mut Self {
366 self.extensions.clear();
367 self
368 }
369
370 /// Returns volatile per-Step content.
371 #[must_use]
372 pub fn ephemeral(&self) -> &[Part] {
373 &self.ephemeral
374 }
375
376 /// Appends one volatile per-Step block.
377 pub fn push_ephemeral(&mut self, part: Part) -> &mut Self {
378 self.ephemeral.push(part);
379 self
380 }
381
382 /// Appends volatile per-Step blocks in iteration order.
383 pub fn extend_ephemeral(&mut self, parts: impl IntoIterator<Item = Part>) -> &mut Self {
384 self.ephemeral.extend(parts);
385 self
386 }
387
388 /// Removes every volatile per-Step block.
389 pub fn clear_ephemeral(&mut self) -> &mut Self {
390 self.ephemeral.clear();
391 self
392 }
393
394 /// Consumes the writable window and freezes a validated, model-visible request.
395 ///
396 /// # This is the item-to-message projection
397 ///
398 /// It is the crate's only one, and there is no second message vocabulary to
399 /// project *into*: the projected value is the same closed [`Item`] history
400 /// minus everything the model must not see. Two rules apply, in this order.
401 ///
402 /// 1. **`ModelVisibility`.** Every [`ModelVisibility::Hidden`] record is omitted,
403 /// whatever its variant. A provider therefore never has to consult
404 /// [`Item`] visibility itself: by construction every item in
405 /// [`Request::messages`] is [`ModelVisibility::Visible`].
406 /// 2. **The exchange grammar**, checked over what survives rule 1. Hiding an
407 /// assistant record hides the calls it carries, so a result that is still
408 /// visible has become an orphan and is refused rather than sent; hiding a
409 /// result whose call is visible leaves that call unanswered and is
410 /// refused too. Reef's own commits cannot produce either, because a
411 /// committed result takes the visibility of the record carrying its call.
412 ///
413 /// What this projection deliberately does *not* do is normalise segments
414 /// across providers. Deciding that one provider's [`Segment::Thinking`] is
415 /// unusable by another requires knowing both providers' rules, which core
416 /// does not and must not learn. A composition layer that changes model
417 /// mid-session performs that rewrite in a
418 /// [`ModelHooks::before_model`](crate::runtime::hook::ModelHooks::before_model)
419 /// registration, returning
420 /// [`BeforeModelDecision::Modify`](crate::runtime::hook::BeforeModelDecision::Modify)
421 /// with a request re-frozen through this same boundary.
422 ///
423 /// This is the only `Request` construction boundary: it validates system
424 /// instructions, applies visibility projection, closes tool-call/result
425 /// exchanges, owns both tool lanes, and rejects invalid input before
426 /// [`Client::generate`] can be invoked.
427 ///
428 /// # Errors
429 ///
430 /// Freezing refuses a request no provider should be asked to answer. Nothing
431 /// is validated lazily and no partial [`Request`] escapes, so a caller that
432 /// gets an error has changed nothing.
433 ///
434 /// The system instruction is checked first, block by block, and each variant
435 /// carries the offending block's index:
436 /// [`EmptySystemInstructionText`](RequestError::EmptySystemInstructionText)
437 /// for a text block with no text,
438 /// [`NonTextSystemInstruction`](RequestError::NonTextSystemInstruction) for a
439 /// block whose kind is known but is not text, and
440 /// [`UnknownSystemInstruction`](RequestError::UnknownSystemInstruction) for
441 /// one whose numeric kind has no portable interpretation. A system
442 /// instruction of zero blocks is valid; a present block that says nothing is
443 /// not.
444 ///
445 /// The rest is the exchange grammar, applied to what survives the visibility
446 /// rule above. It fails when the history is not a closed sequence of
447 /// call-and-answer:
448 ///
449 /// - [`ToolExchangeNotClosed`](RequestError::ToolExchangeNotClosed) if a user,
450 /// system, or assistant record appears while an earlier call is still
451 /// unanswered.
452 /// - [`EmptyToolCallId`](RequestError::EmptyToolCallId),
453 /// [`EmptyToolCallName`](RequestError::EmptyToolCallName), or
454 /// [`DuplicateToolCallId`](RequestError::DuplicateToolCallId) for a call
455 /// that cannot be correlated: identities are unique across the whole
456 /// request, not merely within one assistant record.
457 /// - [`EmptyToolResultId`](RequestError::EmptyToolResultId),
458 /// [`EmptyToolResultName`](RequestError::EmptyToolResultName),
459 /// [`OrphanToolResult`](RequestError::OrphanToolResult), or
460 /// [`ToolResultNameMismatch`](RequestError::ToolResultNameMismatch) for a
461 /// result that answers no pending call or answers it under another tool's
462 /// name.
463 /// - [`UnresolvedToolCalls`](RequestError::UnresolvedToolCalls), with a count,
464 /// if the history ends with calls nobody answered.
465 ///
466 /// The last two are also how a half-hidden exchange is refused, and the
467 /// reason is the projection above rather than provider etiquette: hiding an
468 /// assistant record hides the calls it carries, so a still-visible result has
469 /// become an orphan, and hiding only the result leaves its call unanswered.
470 /// Reef's own commits cannot produce either, because a committed result takes
471 /// the visibility of the record carrying its call — so seeing one of these
472 /// from a rewritten history means the rewrite split an exchange in half.
473 pub fn try_into_request(self, messages: Vec<Item>) -> Result<Request, RequestError> {
474 validate_system_instruction(&self.system_instruction)?;
475
476 validate_model_messages(&messages)?;
477 let visible = messages
478 .into_iter()
479 .filter(is_model_visible)
480 .collect::<Vec<_>>();
481
482 Ok(Request {
483 system_instruction: self.system_instruction,
484 messages: visible,
485 tools: self.tools,
486 params: self.params,
487 extensions: self.extensions,
488 ephemeral: self.ephemeral,
489 })
490 }
491}
492
493fn validate_system_instruction(parts: &[Part]) -> Result<(), RequestError> {
494 if is_valid_system_instruction(parts) {
495 return Ok(());
496 }
497
498 let mut invalid_index = 0;
499 for (index, part) in parts.iter().enumerate() {
500 if part.kind().known() != Some(KnownPartKind::Text) || part.fields().text().is_empty() {
501 invalid_index = index;
502 break;
503 }
504 }
505 let part = &parts[invalid_index];
506 match part.kind().known() {
507 None => Err(RequestError::UnknownSystemInstruction {
508 index: invalid_index,
509 kind: part.kind().as_i64(),
510 }),
511 Some(KnownPartKind::Text) => Err(RequestError::EmptySystemInstructionText {
512 index: invalid_index,
513 }),
514 Some(_) => Err(RequestError::NonTextSystemInstruction {
515 index: invalid_index,
516 kind: part.kind().as_i64(),
517 }),
518 }
519}
520
521fn is_model_visible(item: &Item) -> bool {
522 match item {
523 Item::User(user) => user.visibility() == ModelVisibility::Visible,
524 Item::Assistant(assistant) => assistant.visibility() == ModelVisibility::Visible,
525 Item::ToolResult(result) => result.visibility() == ModelVisibility::Visible,
526 Item::System(system) => system.visibility() == ModelVisibility::Visible,
527 }
528}
529
530/// Validates the visible projection and returns every globally used call id.
531///
532/// This is the authoritative exchange walk used both by formal request freezing
533/// and by hook-output validation against the same frozen transcript.
534fn validate_model_messages(messages: &[Item]) -> Result<HashSet<String>, RequestError> {
535 let mut pending = HashMap::<String, String>::new();
536 let mut seen = HashSet::<String>::new();
537 for item in messages.iter().filter(|item| is_model_visible(item)) {
538 match item {
539 Item::User(_) | Item::System(_) if !pending.is_empty() => {
540 return Err(RequestError::ToolExchangeNotClosed);
541 }
542 Item::Assistant(assistant) => {
543 if !pending.is_empty() {
544 return Err(RequestError::ToolExchangeNotClosed);
545 }
546 validate_assistant_tool_calls(assistant, &mut pending, &mut seen)?;
547 }
548 Item::ToolResult(result) => {
549 validate_tool_result(result.call_id(), result.tool_name(), &mut pending)?;
550 }
551 Item::User(_) | Item::System(_) => {}
552 }
553 }
554 if !pending.is_empty() {
555 return Err(RequestError::UnresolvedToolCalls {
556 count: pending.len(),
557 });
558 }
559 Ok(seen)
560}
561
562/// Validates one hook-produced assistant against the frozen transcript.
563///
564/// Visible call identities share the exact global `seen` set built by
565/// [`RequestPlan::try_into_request`]. Hidden records remain outside that set, as
566/// they do during request projection, while their own call shape and within-record
567/// uniqueness are still checked for lifecycle-coordinate safety.
568pub(crate) fn validate_assistant(
569 assistant: &Assistant,
570 transcript: &[Item],
571) -> Result<(), RequestError> {
572 let mut seen = if assistant.visibility() == ModelVisibility::Visible {
573 validate_model_messages(transcript)?
574 } else {
575 HashSet::new()
576 };
577 validate_assistant_tool_calls(assistant, &mut HashMap::new(), &mut seen)
578}
579
580fn validate_assistant_tool_calls(
581 assistant: &Assistant,
582 pending: &mut HashMap<String, String>,
583 seen: &mut HashSet<String>,
584) -> Result<(), RequestError> {
585 for segment in assistant.content() {
586 if let Segment::ToolCall { call, .. } = segment {
587 validate_tool_call(call, pending, seen)?;
588 }
589 }
590 Ok(())
591}
592
593fn validate_tool_call(
594 call: &ToolCall,
595 pending: &mut HashMap<String, String>,
596 seen: &mut HashSet<String>,
597) -> Result<(), RequestError> {
598 let call_id = call.id().as_str();
599 if call_id.is_empty() {
600 return Err(RequestError::EmptyToolCallId);
601 }
602 if call.name().as_str().is_empty() {
603 return Err(RequestError::EmptyToolCallName {
604 call_id: call_id.into(),
605 });
606 }
607 if !seen.insert(call_id.into()) {
608 return Err(RequestError::DuplicateToolCallId {
609 call_id: call_id.into(),
610 });
611 }
612 pending.insert(call_id.into(), call.name().as_str().into());
613 Ok(())
614}
615
616fn validate_tool_result(
617 call_id: &Id,
618 tool_name: &tool_call::Name,
619 pending: &mut HashMap<String, String>,
620) -> Result<(), RequestError> {
621 let call_id = call_id.as_str();
622 if call_id.is_empty() {
623 return Err(RequestError::EmptyToolResultId);
624 }
625 if tool_name.as_str().is_empty() {
626 return Err(RequestError::EmptyToolResultName {
627 call_id: call_id.into(),
628 });
629 }
630 let Some(expected) = pending.get(call_id) else {
631 return Err(RequestError::OrphanToolResult {
632 call_id: call_id.into(),
633 });
634 };
635 if expected != tool_name.as_str() {
636 return Err(RequestError::ToolResultNameMismatch {
637 call_id: call_id.into(),
638 expected: expected.clone(),
639 actual: tool_name.as_str().into(),
640 });
641 }
642 pending.remove(call_id);
643 Ok(())
644}
645
646/// The complete owned input to one model call.
647///
648/// Its fields are immutable from the public API; provider adapters receive an
649/// owned value and must map local tools and hosted extensions through their
650/// distinct lanes.
651#[derive(Clone, Debug)]
652pub struct Request {
653 system_instruction: Vec<Part>,
654 messages: Vec<Item>,
655 tools: Vec<ClientTool>,
656 params: SamplingParams,
657 extensions: Vec<Envelope>,
658 ephemeral: Vec<Part>,
659}
660
661impl Request {
662 /// Returns ordered portable system content.
663 #[must_use]
664 pub fn system_instruction(&self) -> &[Part] {
665 &self.system_instruction
666 }
667 /// Returns the owned transcript projection.
668 ///
669 /// Every item here is [`ModelVisibility::Visible`] and every tool exchange in it is
670 /// closed, because [`RequestPlan::try_into_request`] is the only way to build this
671 /// value and it applies both rules. A provider adapter maps what it is
672 /// given; it never has to decide what the model may see.
673 #[must_use]
674 pub fn messages(&self) -> &[Item] {
675 &self.messages
676 }
677 /// Returns only client-local tools.
678 #[must_use]
679 pub fn tools(&self) -> &[ClientTool] {
680 &self.tools
681 }
682 /// Returns frozen sampling controls.
683 #[must_use]
684 pub const fn sampling(&self) -> &SamplingParams {
685 &self.params
686 }
687 /// Returns only provider-hosted/model-native extensions.
688 #[must_use]
689 pub fn extensions(&self) -> &[Envelope] {
690 &self.extensions
691 }
692 /// Returns volatile tail content for this call.
693 ///
694 /// Ephemeral content is a lane of its own: it is never an [`Item`], never
695 /// enters the transcript, and never survives the Step that produced it. A
696 /// replay or equivalence check drawn over the transcript, or over
697 /// [`Request::messages`], therefore already excludes it and needs no
698 /// separate switch to say so.
699 #[must_use]
700 pub fn ephemeral(&self) -> &[Part] {
701 &self.ephemeral
702 }
703}
704
705/// Static identity and capabilities snapshotted by an Agent revision.
706///
707/// Every [`Client`] has to return one of these, so a later capability flag would
708/// break every provider in existence if callers built it with a struct literal.
709/// Fields are therefore private: construction goes through [`Info::new`] plus the
710/// capability setters, and a capability added later defaults to "unsupported" for
711/// providers that predate it.
712///
713/// # The named capability set is closed
714///
715/// A named field is admissible here only when it states something about a
716/// reef-owned primitive: [`Info::supports_tools`] is a statement about reef's
717/// tool mechanism, [`Info::supports_thinking`] about
718/// [`Segment::Thinking`] and
719/// [`ContentKind::Thinking`], [`Info::supports_vision`] about non-text
720/// [`PartKind`](crate::value::content::PartKind)s, and
721/// [`Info::context_window`] is a count of reef's own
722/// [`Item`] budget. Wire-protocol quirks, thinking formats, pricing tiers and
723/// session-affinity formats describe providers rather than reef primitives, so
724/// they travel in the [`Envelope`] extension channel and core never learns their
725/// vocabulary.
726///
727/// ```
728/// use reef_core::opaque;
729/// use reef_core::runtime::model;
730///
731/// let info = model::Info::new("example-model".to_owned(), 200_000)
732/// .with_tools(true)
733/// .with_thinking(true)
734/// .with_extension(
735/// opaque::Envelope::try_new(
736/// "example.compat".to_owned(),
737/// "matrix".to_owned(),
738/// opaque::Payload::copy_from_slice(br#"{"thinkingFormat":"example"}"#),
739/// )
740/// .unwrap(),
741/// );
742///
743/// assert_eq!(info.id(), "example-model");
744/// assert_eq!(info.context_window(), 200_000);
745/// assert!(info.supports_tools() && info.supports_thinking() && !info.supports_vision());
746/// // Provider-defined bytes; core never parsed them.
747/// let compat = info.extension("example.compat", "matrix").unwrap();
748/// assert_eq!(compat.as_bytes(), br#"{"thinkingFormat":"example"}"#);
749/// assert!(info.extension("example.compat", "absent").is_none());
750/// ```
751///
752/// # Equality
753///
754/// Field by field, and the extension list **in order**. Two snapshots are equal
755/// when they name the same model, state the same context window, answer every
756/// capability the same way, and carry the same extensions in the same
757/// positions; an [`Envelope`] compares by the byte-wise rule that type
758/// documents, so equality here inherits it rather than interpreting a payload.
759/// The identifier compares exactly — no case folding, no trimming — because it
760/// is a provider-owned string core assigns no structure to.
761///
762/// Ordering is part of it because [`Info::extensions`] publishes insertion
763/// order. A set-like equality would let `a == b` hold while
764/// `a.extensions() != b.extensions()`, which is a value disagreeing with its own
765/// accessor; and a provider whose snapshot lists its extensions in a different
766/// order on each call is not returning the immutable snapshot this type is
767/// documented to be, so the stricter reading is also the one that catches that.
768///
769/// The relation is total, so this is an [`Eq`]. Growth stays additive: a
770/// capability added later has a defined "unsupported" default, so two values
771/// that were equal before it existed are still equal after.
772///
773/// ```
774/// use reef_core::opaque;
775/// use reef_core::runtime::model;
776///
777/// let extension = |kind: &str| {
778/// opaque::Envelope::try_new(
779/// "example.compat".to_owned(),
780/// kind.to_owned(),
781/// opaque::Payload::copy_from_slice(b"{}"),
782/// )
783/// .unwrap()
784/// };
785/// let info = |first: &str, second: &str| {
786/// model::Info::new("example-model".to_owned(), 200_000)
787/// .with_extensions([extension(first), extension(second)])
788/// };
789///
790/// assert_eq!(info("a", "b"), info("a", "b"));
791/// // The same two facts, listed the other way round.
792/// assert_ne!(info("a", "b"), info("b", "a"));
793/// ```
794#[derive(Clone, Debug, Eq, PartialEq)]
795pub struct Info {
796 id: String,
797 context_window: u64,
798 supports_tools: bool,
799 supports_vision: bool,
800 supports_thinking: bool,
801 extensions: Vec<Envelope>,
802}
803
804impl Info {
805 /// Creates a capability snapshot that supports nothing beyond plain text.
806 #[must_use]
807 pub const fn new(id: String, context_window: u64) -> Self {
808 Self {
809 id,
810 context_window,
811 supports_tools: false,
812 supports_vision: false,
813 supports_thinking: false,
814 extensions: Vec::new(),
815 }
816 }
817
818 /// Declares whether client-local tool calling is supported.
819 #[must_use]
820 pub const fn with_tools(mut self, supported: bool) -> Self {
821 self.supports_tools = supported;
822 self
823 }
824
825 /// Declares whether image input is supported.
826 #[must_use]
827 pub const fn with_vision(mut self, supported: bool) -> Self {
828 self.supports_vision = supported;
829 self
830 }
831
832 /// Declares whether reasoning output is supported.
833 #[must_use]
834 pub const fn with_thinking(mut self, supported: bool) -> Self {
835 self.supports_thinking = supported;
836 self
837 }
838
839 /// Appends one provider-supplied capability fact.
840 #[must_use]
841 pub fn with_extension(mut self, extension: Envelope) -> Self {
842 self.extensions.push(extension);
843 self
844 }
845
846 /// Appends provider-supplied capability facts in iteration order.
847 #[must_use]
848 pub fn with_extensions(mut self, extensions: impl IntoIterator<Item = Envelope>) -> Self {
849 self.extensions.extend(extensions);
850 self
851 }
852
853 /// Returns the provider model identifier.
854 #[must_use]
855 pub fn id(&self) -> &str {
856 &self.id
857 }
858
859 /// Returns the maximum input size in tokens.
860 #[must_use]
861 pub const fn context_window(&self) -> u64 {
862 self.context_window
863 }
864
865 /// Reports whether client-local tool calling is supported.
866 #[must_use]
867 pub const fn supports_tools(&self) -> bool {
868 self.supports_tools
869 }
870
871 /// Reports whether image input is supported.
872 #[must_use]
873 pub const fn supports_vision(&self) -> bool {
874 self.supports_vision
875 }
876
877 /// Reports whether reasoning output is supported.
878 #[must_use]
879 pub const fn supports_thinking(&self) -> bool {
880 self.supports_thinking
881 }
882
883 /// Returns every provider-supplied capability fact in insertion order.
884 #[must_use]
885 pub fn extensions(&self) -> &[Envelope] {
886 &self.extensions
887 }
888
889 /// Returns the first capability fact matching `namespace` and `kind`.
890 #[must_use]
891 pub fn extension(&self, namespace: &str, kind: &str) -> Option<&Payload> {
892 self.extensions
893 .iter()
894 .find(|extension| extension.namespace() == namespace && extension.kind() == kind)
895 .map(Envelope::data)
896 }
897}
898
899/// Portable semantic reason for generation completion.
900#[derive(Clone, Copy, Debug, Eq, PartialEq)]
901#[non_exhaustive]
902pub enum CompletionReason {
903 /// Provider supplied no portable classification.
904 Unknown,
905 /// The model ended normally.
906 Stop,
907 /// An output limit was reached.
908 Length,
909 /// The model requested one or more tools.
910 ToolCalls,
911 /// Provider safety filtering ended generation.
912 ContentFilter,
913}
914
915/// Token consumption reported by a provider, as one increment.
916///
917/// This is the payload of [`Event::Usage`], which is incremental: these five
918/// numbers describe the tokens consumed since the previous usage event of the
919/// same generation, and a consumer adds them up.
920///
921/// ```
922/// use reef_core::runtime::model;
923///
924/// // The common case: a provider that reports one total per call.
925/// let usage = model::TokenUsage::new(1_200, 340);
926/// assert_eq!(usage.total, 1_540);
927///
928/// // A provider that also breaks its counts down. Neither detail is added to
929/// // the count it belongs to; both are already inside it.
930/// let detailed = model::TokenUsage::new(1_200, 340)
931/// .with_cached(900)
932/// .with_reasoning(210);
933/// assert_eq!(detailed.prompt, 1_200);
934/// assert_eq!(detailed.total, 1_540);
935/// assert_eq!(detailed.cached, 900);
936/// assert_eq!(detailed.reasoning, 210);
937/// ```
938///
939/// # What the five numbers mean
940///
941/// The two detail fields are **parts of** the counts above them, not additions
942/// to them, which is the convention providers that report them already use. An
943/// adapter that added them separately would make every budget over-count.
944///
945/// - `prompt` is every input token, `cached` included.
946/// - `completion` is every output token, `reasoning` included.
947/// - `total` is the provider's own total for this increment. [`Self::new`] sets
948/// it to `prompt + completion`, which is what a provider that reports no
949/// separate total means; [`Self::with_total`] states a different one, for a
950/// provider that does.
951///
952/// # The fields are public, deliberately
953///
954/// Every other value type in this crate hides its fields, and this one does not,
955/// because the rule is about who has to construct the value rather than about
956/// consistency of style. A struct that a trait method *returns* — [`Info`], two
957/// types away — must be buildable by every provider that will ever exist, so a
958/// field added later would break all of them, and its fields are private with a
959/// builder in front. A `TokenUsage` is built inside one optional event, and read
960/// by policies that want all five numbers at once. Privatising the fields would
961/// add five getters to the five setters, make the `#[non_exhaustive]` above a
962/// no-op that then has to be removed, and buy nothing: the attribute already
963/// stops an external struct literal, so a sixth field stays additive either way.
964#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
965#[non_exhaustive]
966pub struct TokenUsage {
967 /// Input tokens consumed, including [`cached`](Self::cached).
968 pub prompt: u64,
969 /// Output tokens generated, including [`reasoning`](Self::reasoning).
970 pub completion: u64,
971 /// Provider-reported total for this increment.
972 pub total: u64,
973 /// The part of [`prompt`](Self::prompt) that was served from cache.
974 pub cached: u64,
975 /// The part of [`completion`](Self::completion) that was reasoning.
976 pub reasoning: u64,
977}
978
979impl TokenUsage {
980 /// Reports one increment of input and output tokens.
981 ///
982 /// `total` becomes `prompt + completion`, saturating; the two detail fields
983 /// are zero. Each is stated separately by the builder below when a provider
984 /// reports it.
985 #[must_use]
986 pub const fn new(prompt: u64, completion: u64) -> Self {
987 Self {
988 prompt,
989 completion,
990 total: prompt.saturating_add(completion),
991 cached: 0,
992 reasoning: 0,
993 }
994 }
995
996 /// States a provider-reported total that is not `prompt + completion`.
997 #[must_use]
998 pub const fn with_total(mut self, total: u64) -> Self {
999 self.total = total;
1000 self
1001 }
1002
1003 /// States how much of [`prompt`](Self::prompt) came from cache.
1004 #[must_use]
1005 pub const fn with_cached(mut self, cached: u64) -> Self {
1006 self.cached = cached;
1007 self
1008 }
1009
1010 /// States how much of [`completion`](Self::completion) was reasoning.
1011 #[must_use]
1012 pub const fn with_reasoning(mut self, reasoning: u64) -> Self {
1013 self.reasoning = reasoning;
1014 self
1015 }
1016}
1017
1018/// Whether a streamed portable content item is answer text or reasoning.
1019#[derive(Clone, Copy, Debug, Eq, PartialEq)]
1020pub enum ContentKind {
1021 /// User-visible assistant answer text.
1022 Text,
1023 /// Model reasoning or thinking content.
1024 Thinking,
1025}
1026
1027/// One normalized event produced by a model provider adapter.
1028///
1029/// Deltas open an item identity and finals close it. Tool calls have an explicit
1030/// start/arguments/final lifecycle; [`StreamGrammar`] validates every pairing.
1031///
1032/// **Deltas are optional.** A provider that answers in one frame emits the final
1033/// alone, and the final's payload is the whole item; see
1034/// [`StreamGrammar::accept`]. What a final may never do is contradict deltas
1035/// that were actually sent.
1036#[derive(Clone)]
1037pub enum Event {
1038 /// A fragment of one text or thinking item.
1039 ContentDelta {
1040 /// Stable item identity.
1041 id: String,
1042 /// Portable content lane.
1043 kind: ContentKind,
1044 /// Next exact text fragment.
1045 delta: String,
1046 },
1047 /// The complete content and extensions for the same item.
1048 ContentFinal {
1049 /// Identity opened by preceding deltas, or by this event when there were
1050 /// none.
1051 id: String,
1052 /// Content lane, matching every delta.
1053 kind: ContentKind,
1054 /// The whole item: the exact concatenation of all deltas, or, when no
1055 /// delta was sent, the content itself.
1056 content: String,
1057 /// Provider data owned by this final item.
1058 extensions: SegmentExtensions,
1059 },
1060 /// Opens a client-local tool call.
1061 ///
1062 /// A provider that delivers a call complete in one frame may omit this and
1063 /// send only [`ToolCallFinal`](Event::ToolCallFinal), which names the tool
1064 /// itself.
1065 ToolCallStart {
1066 /// Model-assigned call identity.
1067 id: Id,
1068 /// Selected local tool name.
1069 name: tool_call::Name,
1070 },
1071 /// Adds opaque argument bytes to the open tool call.
1072 ToolCallArgumentsDelta {
1073 /// Identity of the open call.
1074 id: Id,
1075 /// Next exact argument fragment.
1076 delta: Payload,
1077 },
1078 /// Closes a tool call with the exact accumulated identity, name, and bytes.
1079 ///
1080 /// When no argument delta preceded it, this event *is* the call: its
1081 /// identity, tool name and argument bytes are the whole of what reef records
1082 /// and what the executor receives.
1083 ToolCallFinal {
1084 /// Complete call value.
1085 call: ToolCall,
1086 /// Provider data owned by this call.
1087 extensions: SegmentExtensions,
1088 },
1089 /// Reports token accounting without changing item lifecycle.
1090 ///
1091 /// # Usage is incremental, and normalising it is the adapter's obligation
1092 ///
1093 /// A generation may carry any number of these. **Each one reports the tokens
1094 /// consumed since the previous `Usage` of the same generation**, so a
1095 /// generation's totals are the sum of its usage events, and one event
1096 /// carrying the whole call's totals is the ordinary single-increment case.
1097 ///
1098 /// Reef does not and cannot check this. A provider that reports running
1099 /// totals and a provider that reports increments emit sequences core has no
1100 /// way to tell apart, so the rule is an obligation on the adapter rather than
1101 /// a grammar rule: **an adapter for a provider that reports running totals
1102 /// must emit the difference**, or withhold the numbers and emit one event at
1103 /// the end. An adapter that forwards running totals verbatim is not
1104 /// well-formed, and nothing will say so.
1105 ///
1106 /// The rule is chosen because summation is the only operation available to
1107 /// the consumer that receives these. They reach a hook through
1108 /// [`ObserverHooks::model_event`](crate::runtime::hook::ObserverHooks::model_event)
1109 /// and nowhere else, one event at a time, with no per-generation accumulator
1110 /// of reef's own to subtract from — so a budget policy adds them up. Under
1111 /// the incremental rule that is exact at every scope: within a generation,
1112 /// across the generations of a Run, and across Runs. Forwarded running
1113 /// totals would double-count, and every budget built on them would fire
1114 /// early.
1115 Usage(TokenUsage),
1116 /// The single terminal event.
1117 Done {
1118 /// Provider's verbatim finish label.
1119 finish_reason: String,
1120 /// Portable completion classification.
1121 completion: CompletionReason,
1122 /// Provider data owned by the assistant record.
1123 provider_data: Vec<Envelope>,
1124 },
1125}
1126
1127impl fmt::Debug for Event {
1128 /// Keeps every identity and lane, and sizes the two content fields.
1129 ///
1130 /// `delta` and `content` are the only members of this enum that own model
1131 /// bytes directly. Everything else either identifies an item, classifies a
1132 /// lane, counts tokens, or is a value that already redacts itself — and a
1133 /// stream is debugged by its lifecycle, which those facts describe fully.
1134 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1135 match self {
1136 Self::ContentDelta { id, kind, delta } => formatter
1137 .debug_struct("ContentDelta")
1138 .field("id", id)
1139 .field("kind", kind)
1140 .field("delta", &redact::Bytes(delta.len()))
1141 .finish(),
1142 Self::ContentFinal {
1143 id,
1144 kind,
1145 content,
1146 extensions,
1147 } => formatter
1148 .debug_struct("ContentFinal")
1149 .field("id", id)
1150 .field("kind", kind)
1151 .field("content", &redact::Bytes(content.len()))
1152 .field("extensions", extensions)
1153 .finish(),
1154 Self::ToolCallStart { id, name } => formatter
1155 .debug_struct("ToolCallStart")
1156 .field("id", id)
1157 .field("name", name)
1158 .finish(),
1159 Self::ToolCallArgumentsDelta { id, delta } => formatter
1160 .debug_struct("ToolCallArgumentsDelta")
1161 .field("id", id)
1162 .field("delta", delta)
1163 .finish(),
1164 Self::ToolCallFinal { call, extensions } => formatter
1165 .debug_struct("ToolCallFinal")
1166 .field("call", call)
1167 .field("extensions", extensions)
1168 .finish(),
1169 Self::Usage(usage) => formatter.debug_tuple("Usage").field(usage).finish(),
1170 Self::Done {
1171 finish_reason,
1172 completion,
1173 provider_data,
1174 } => formatter
1175 .debug_struct("Done")
1176 .field("finish_reason", finish_reason)
1177 .field("completion", completion)
1178 .field("provider_data", provider_data)
1179 .finish(),
1180 }
1181 }
1182}
1183
1184/// A stable normalized-stream grammar violation.
1185#[derive(Clone, Debug, Eq, PartialEq)]
1186#[non_exhaustive]
1187pub enum StreamError {
1188 /// An item identity was empty.
1189 EmptyItemId,
1190 /// A tool name was empty.
1191 EmptyToolName,
1192 /// An identity was reopened or reused after completion.
1193 DuplicateItemId(String),
1194 /// An event did not match the identity's active lifecycle.
1195 InvalidLifecycle(String),
1196 /// A final payload differed from accumulated deltas.
1197 FinalPayloadMismatch(String),
1198 /// Terminal arrived while one or more items remained open.
1199 UnfinishedItems,
1200 /// An event was observed after terminal.
1201 EventAfterDone,
1202 /// End-of-stream occurred without terminal.
1203 MissingTerminal,
1204}
1205
1206impl fmt::Display for StreamError {
1207 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1208 match self {
1209 Self::EmptyItemId => formatter.write_str("model stream item id is empty"),
1210 Self::EmptyToolName => formatter.write_str("model stream tool name is empty"),
1211 Self::DuplicateItemId(id) => write!(formatter, "duplicate model stream item id: {id}"),
1212 Self::InvalidLifecycle(id) => {
1213 write!(formatter, "invalid model stream lifecycle for: {id}")
1214 }
1215 Self::FinalPayloadMismatch(id) => {
1216 write!(formatter, "model stream final payload mismatch for: {id}")
1217 }
1218 Self::UnfinishedItems => {
1219 formatter.write_str("model stream terminal has unfinished items")
1220 }
1221 Self::EventAfterDone => {
1222 formatter.write_str("model stream event emitted after terminal")
1223 }
1224 Self::MissingTerminal => formatter.write_str("model stream ended without terminal"),
1225 }
1226 }
1227}
1228
1229impl Error for StreamError {}
1230
1231enum OpenItem {
1232 Content { kind: ContentKind, value: String },
1233 Tool { name: String, arguments: Vec<u8> },
1234}
1235
1236/// Incremental validator for exactly one [`Client`] event stream.
1237#[derive(Default)]
1238pub struct StreamGrammar {
1239 open: HashMap<String, OpenItem>,
1240 seen: HashSet<String>,
1241 done: bool,
1242}
1243
1244impl fmt::Debug for StreamGrammar {
1245 /// Reports the validator's position in the stream, not the stream.
1246 ///
1247 /// The open map accumulates the exact text and argument bytes each item has
1248 /// produced so far, so it is counted rather than shown; the counts and the
1249 /// terminal flag are what a grammar violation is actually diagnosed from.
1250 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1251 formatter
1252 .debug_struct("StreamGrammar")
1253 .field("open", &self.open.len())
1254 .field("seen", &self.seen.len())
1255 .field("done", &self.done)
1256 .finish()
1257 }
1258}
1259
1260impl StreamGrammar {
1261 /// Creates a validator before the first event.
1262 #[must_use]
1263 pub fn new() -> Self {
1264 Self::default()
1265 }
1266
1267 /// Validates one event without taking ownership from its consumer.
1268 ///
1269 /// # Errors
1270 ///
1271 /// A rejected event means the provider's stream is not a well-formed
1272 /// sequence, which the caller must treat as a failed generation rather than
1273 /// as a recoverable gap: the accumulated state is no longer a faithful
1274 /// picture of what the provider sent.
1275 ///
1276 /// - [`EventAfterDone`](StreamError::EventAfterDone) for anything at all
1277 /// after the terminal event. Checked before the event's own shape, because
1278 /// after a terminal there is no lifecycle left to be consistent with.
1279 /// - [`EmptyItemId`](StreamError::EmptyItemId) for an event with no identity,
1280 /// and [`EmptyToolName`](StreamError::EmptyToolName) for a tool event that
1281 /// does not name a tool. Neither can be correlated with anything.
1282 /// - [`DuplicateItemId`](StreamError::DuplicateItemId) if an identity that
1283 /// already completed is opened again. Identities are single-use for the
1284 /// whole stream, so a reused one is a provider defect rather than a second
1285 /// item.
1286 /// - [`InvalidLifecycle`](StreamError::InvalidLifecycle) if the event does not
1287 /// fit the identity's active state — content deltas for a tool call, a
1288 /// tool final for an identity opened as content, or a content kind that
1289 /// changed mid-item.
1290 /// - [`FinalPayloadMismatch`](StreamError::FinalPayloadMismatch) if a final
1291 /// payload is not exactly what the deltas accumulated. This is the check
1292 /// that makes incremental output trustworthy: a consumer that rendered the
1293 /// deltas has already shown the user something, so a final that disagrees
1294 /// cannot be silently preferred.
1295 /// - [`UnfinishedItems`](StreamError::UnfinishedItems) if the terminal event
1296 /// arrives while any identity is still open.
1297 ///
1298 /// # Deltas are optional
1299 ///
1300 /// A final may open its own item. [`Event::ContentFinal`] for an identity no
1301 /// delta ever opened, and [`Event::ToolCallFinal`] whose call accumulated no
1302 /// [`ToolCallArgumentsDelta`](Event::ToolCallArgumentsDelta) — whether or not
1303 /// a [`ToolCallStart`](Event::ToolCallStart) announced it — are both
1304 /// well-formed, and the final's payload is the item. A provider that answers
1305 /// in one frame is not required to synthesise a delta equal to its own
1306 /// payload, which is the workaround every adapter for such a provider would
1307 /// otherwise have to invent.
1308 ///
1309 /// Nothing about the mismatch rule is relaxed by this. What
1310 /// `FinalPayloadMismatch` protects is a consumer that has *already rendered*
1311 /// something, so it applies exactly when deltas were sent: a final that
1312 /// contradicts a non-empty accumulation is still rejected. With no deltas
1313 /// there is nothing rendered for the final to contradict.
1314 ///
1315 /// Identities are spent either way. A single-frame final inserts its
1316 /// identity, so reusing it afterwards is
1317 /// [`DuplicateItemId`](StreamError::DuplicateItemId) exactly as reusing a
1318 /// streamed one is.
1319 pub fn accept(&mut self, event: &Event) -> Result<(), StreamError> {
1320 if self.done {
1321 return Err(StreamError::EventAfterDone);
1322 }
1323 match event {
1324 Event::ContentDelta { id, kind, delta } => self.content_delta(id, *kind, delta),
1325 Event::ContentFinal {
1326 id, kind, content, ..
1327 } => self.content_final(id, *kind, content),
1328 Event::ToolCallStart { id, name } => self.tool_start(id, name),
1329 Event::ToolCallArgumentsDelta { id, delta } => self.tool_delta(id, delta),
1330 Event::ToolCallFinal { call, .. } => self.tool_final(call),
1331 Event::Usage(_) => Ok(()),
1332 Event::Done { .. } if self.open.is_empty() => {
1333 self.done = true;
1334 Ok(())
1335 }
1336 Event::Done { .. } => Err(StreamError::UnfinishedItems),
1337 }
1338 }
1339
1340 /// Verifies that the producer ended after exactly one terminal event.
1341 ///
1342 /// # Errors
1343 ///
1344 /// [`MissingTerminal`](StreamError::MissingTerminal) if the stream ended
1345 /// without one. This is the one violation [`accept`](Self::accept) cannot
1346 /// report, because it is the absence of an event rather than a bad one: a
1347 /// stream that simply stops is indistinguishable, event by event, from one
1348 /// that is still going.
1349 pub fn finish(self) -> Result<(), StreamError> {
1350 if self.done {
1351 Ok(())
1352 } else {
1353 Err(StreamError::MissingTerminal)
1354 }
1355 }
1356
1357 fn content_delta(
1358 &mut self,
1359 id: &str,
1360 kind: ContentKind,
1361 delta: &str,
1362 ) -> Result<(), StreamError> {
1363 self.require_id(id)?;
1364 if let Some(item) = self.open.get_mut(id) {
1365 return match item {
1366 OpenItem::Content {
1367 kind: active,
1368 value,
1369 } if *active == kind => {
1370 value.push_str(delta);
1371 Ok(())
1372 }
1373 _ => Err(StreamError::InvalidLifecycle(id.into())),
1374 };
1375 }
1376 if !self.seen.insert(id.into()) {
1377 return Err(StreamError::DuplicateItemId(id.into()));
1378 }
1379 self.open.insert(
1380 id.into(),
1381 OpenItem::Content {
1382 kind,
1383 value: delta.into(),
1384 },
1385 );
1386 Ok(())
1387 }
1388
1389 fn content_final(
1390 &mut self,
1391 id: &str,
1392 kind: ContentKind,
1393 content: &str,
1394 ) -> Result<(), StreamError> {
1395 self.require_id(id)?;
1396 match self.open.get(id) {
1397 Some(OpenItem::Content {
1398 kind: active,
1399 value,
1400 }) if *active == kind && value == content => {}
1401 Some(OpenItem::Content { kind: active, .. }) if *active == kind => {
1402 return Err(StreamError::FinalPayloadMismatch(id.into()));
1403 }
1404 Some(_) => return Err(StreamError::InvalidLifecycle(id.into())),
1405 // A provider that does not stream sends the whole item in one
1406 // frame. Nothing was accumulated, so nothing can disagree with the
1407 // final, and the identity is spent exactly as a streamed one is.
1408 None => {
1409 if self.seen.insert(id.into()) {
1410 return Ok(());
1411 }
1412 return Err(StreamError::DuplicateItemId(id.into()));
1413 }
1414 }
1415 self.open.remove(id);
1416 Ok(())
1417 }
1418
1419 fn tool_start(&mut self, id: &Id, name: &tool_call::Name) -> Result<(), StreamError> {
1420 let id = id.as_str();
1421 self.require_id(id)?;
1422 if name.as_str().is_empty() {
1423 return Err(StreamError::EmptyToolName);
1424 }
1425 if !self.seen.insert(id.into()) {
1426 return Err(StreamError::DuplicateItemId(id.into()));
1427 }
1428 self.open.insert(
1429 id.into(),
1430 OpenItem::Tool {
1431 name: name.as_str().into(),
1432 arguments: Vec::new(),
1433 },
1434 );
1435 Ok(())
1436 }
1437
1438 fn tool_delta(&mut self, id: &Id, delta: &Payload) -> Result<(), StreamError> {
1439 let id = id.as_str();
1440 self.require_id(id)?;
1441 match self.open.get_mut(id) {
1442 Some(OpenItem::Tool { arguments, .. }) => {
1443 arguments.extend_from_slice(delta.as_bytes());
1444 Ok(())
1445 }
1446 _ => Err(StreamError::InvalidLifecycle(id.into())),
1447 }
1448 }
1449
1450 fn tool_final(&mut self, call: &ToolCall) -> Result<(), StreamError> {
1451 let id = call.id().as_str();
1452 self.require_id(id)?;
1453 if call.name().as_str().is_empty() {
1454 return Err(StreamError::EmptyToolName);
1455 }
1456 match self.open.get(id) {
1457 // An open call with nothing accumulated is the single-frame shape:
1458 // the start announced the call and the final carries all of it.
1459 Some(OpenItem::Tool { name, arguments })
1460 if name == call.name().as_str()
1461 && (arguments.is_empty() || arguments == call.arguments().as_bytes()) => {}
1462 Some(OpenItem::Tool { .. }) => {
1463 return Err(StreamError::FinalPayloadMismatch(id.into()));
1464 }
1465 Some(OpenItem::Content { .. }) => {
1466 return Err(StreamError::InvalidLifecycle(id.into()));
1467 }
1468 // A call announced by its own final, with no start at all.
1469 None => {
1470 if self.seen.insert(id.into()) {
1471 return Ok(());
1472 }
1473 return Err(StreamError::DuplicateItemId(id.into()));
1474 }
1475 }
1476 self.open.remove(id);
1477 Ok(())
1478 }
1479
1480 const fn require_id(&self, id: &str) -> Result<(), StreamError> {
1481 if id.is_empty() {
1482 Err(StreamError::EmptyItemId)
1483 } else {
1484 Ok(())
1485 }
1486 }
1487}
1488
1489/// Narrow, statically dispatched model provider boundary.
1490///
1491/// This is the one trait reef cannot ship an implementation of: it is the
1492/// adapter between reef's [`Request`] and whatever actually answers it. Two
1493/// methods, one of which is a constant.
1494///
1495/// The explicit RPITIT future follows ADR-013 and avoids `async-trait`. The
1496/// returned stream remains provider-owned; callers must apply [`StreamGrammar`].
1497///
1498/// # Implementing it
1499///
1500/// [`Client::Stream`] is bounded by [`Stream`], which lives in `futures-core`.
1501/// That crate is deliberately combinator-free — there is no `stream::iter` and
1502/// no `StreamExt` — so the associated type is a type you write, with a
1503/// `poll_next`, and it is about ten lines. Reach for the bound through
1504/// [`reef_core::futures_core`](crate::futures_core) rather than adding the crate
1505/// yourself, so the two versions cannot disagree.
1506///
1507/// This is the whole of a provider that replays a fixed script, which is what a
1508/// test double looks like:
1509///
1510/// ```
1511/// use std::future::{Future, ready};
1512/// use std::pin::Pin;
1513/// use std::task::{Context, Poll};
1514///
1515/// use reef_core::futures_core::Stream;
1516/// use reef_core::runtime::model;
1517/// use reef_core::value::content;
1518///
1519/// /// The events of one call, oldest first.
1520/// #[derive(Debug)]
1521/// struct Scripted(std::collections::VecDeque<model::Event>);
1522///
1523/// impl Stream for Scripted {
1524/// type Item = Result<model::Event, Unreachable>;
1525///
1526/// fn poll_next(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Option<Self::Item>> {
1527/// // A script is always ready, so this never registers a waker. A real
1528/// // adapter polls its transport here and returns `Poll::Pending` when
1529/// // that transport has registered one.
1530/// Poll::Ready(self.0.pop_front().map(Ok))
1531/// }
1532/// }
1533///
1534/// #[derive(Debug)]
1535/// struct Unreachable;
1536///
1537/// impl std::fmt::Display for Unreachable {
1538/// fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1539/// f.write_str("a scripted provider cannot fail")
1540/// }
1541/// }
1542///
1543/// impl std::error::Error for Unreachable {}
1544///
1545/// #[derive(Debug)]
1546/// struct ScriptedModel;
1547///
1548/// impl model::Client for ScriptedModel {
1549/// type Error = Unreachable;
1550/// type Stream = Scripted;
1551///
1552/// fn info(&self) -> model::Info {
1553/// model::Info::new("scripted/v1".to_owned(), 8_192).with_tools(true)
1554/// }
1555///
1556/// fn generate(
1557/// &self,
1558/// request: model::Request,
1559/// ) -> impl Future<Output = Result<Self::Stream, Self::Error>> + Send {
1560/// // `request.messages()` is already projected: every item in it is
1561/// // model-visible and every tool exchange in it is closed.
1562/// let _turns = request.messages().len();
1563/// ready(Ok(Scripted(
1564/// [
1565/// model::Event::ContentFinal {
1566/// id: "answer".to_owned(),
1567/// kind: model::ContentKind::Text,
1568/// content: "Hello.".to_owned(),
1569/// extensions: content::SegmentExtensions::new(String::new(), None, None),
1570/// },
1571/// model::Event::Usage(model::TokenUsage::new(12, 3)),
1572/// model::Event::Done {
1573/// finish_reason: "stop".to_owned(),
1574/// completion: model::CompletionReason::Stop,
1575/// provider_data: Vec::new(),
1576/// },
1577/// ]
1578/// .into(),
1579/// )))
1580/// }
1581/// }
1582/// ```
1583///
1584/// Every event that stream yields is checked by [`StreamGrammar`] before reef
1585/// acts on it, so an adapter can validate its own output against the same rules
1586/// in its own tests.
1587pub trait Client: Send + Sync {
1588 /// Provider-specific call failure.
1589 type Error: Error + Send + Sync + 'static;
1590 /// Normalized event stream for one call.
1591 type Stream: Stream<Item = Result<Event, Self::Error>> + Send;
1592
1593 /// Returns the immutable model capability snapshot.
1594 fn info(&self) -> Info;
1595 /// Starts one model call from an owned request.
1596 fn generate(
1597 &self,
1598 request: Request,
1599 ) -> impl Future<Output = Result<Self::Stream, Self::Error>> + Send;
1600}