Skip to main content

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}