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::{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        let mut visible = Vec::with_capacity(messages.len());
477        let mut pending = HashMap::<String, String>::new();
478        let mut seen = HashSet::<String>::new();
479        for item in messages {
480            match &item {
481                Item::User(user) if user.visibility() == ModelVisibility::Hidden => continue,
482                Item::Assistant(assistant) if assistant.visibility() == ModelVisibility::Hidden => {
483                    continue;
484                }
485                Item::ToolResult(result) if result.visibility() == ModelVisibility::Hidden => {
486                    continue;
487                }
488                Item::System(system) if system.visibility() == ModelVisibility::Hidden => continue,
489                Item::User(_) | Item::System(_) if !pending.is_empty() => {
490                    return Err(RequestError::ToolExchangeNotClosed);
491                }
492                Item::Assistant(assistant) => {
493                    if !pending.is_empty() {
494                        return Err(RequestError::ToolExchangeNotClosed);
495                    }
496                    for segment in assistant.content() {
497                        if let Segment::ToolCall { call, .. } = segment {
498                            validate_tool_call(call, &mut pending, &mut seen)?;
499                        }
500                    }
501                }
502                Item::ToolResult(result) => {
503                    validate_tool_result(result.call_id(), result.tool_name(), &mut pending)?;
504                }
505                Item::User(_) | Item::System(_) => {}
506            }
507            visible.push(item);
508        }
509        if !pending.is_empty() {
510            return Err(RequestError::UnresolvedToolCalls {
511                count: pending.len(),
512            });
513        }
514
515        Ok(Request {
516            system_instruction: self.system_instruction,
517            messages: visible,
518            tools: self.tools,
519            params: self.params,
520            extensions: self.extensions,
521            ephemeral: self.ephemeral,
522        })
523    }
524}
525
526fn validate_system_instruction(parts: &[Part]) -> Result<(), RequestError> {
527    if is_valid_system_instruction(parts) {
528        return Ok(());
529    }
530
531    let mut invalid_index = 0;
532    for (index, part) in parts.iter().enumerate() {
533        if part.kind().known() != Some(KnownPartKind::Text) || part.fields().text().is_empty() {
534            invalid_index = index;
535            break;
536        }
537    }
538    let part = &parts[invalid_index];
539    match part.kind().known() {
540        None => Err(RequestError::UnknownSystemInstruction {
541            index: invalid_index,
542            kind: part.kind().as_i64(),
543        }),
544        Some(KnownPartKind::Text) => Err(RequestError::EmptySystemInstructionText {
545            index: invalid_index,
546        }),
547        Some(_) => Err(RequestError::NonTextSystemInstruction {
548            index: invalid_index,
549            kind: part.kind().as_i64(),
550        }),
551    }
552}
553
554fn validate_tool_call(
555    call: &ToolCall,
556    pending: &mut HashMap<String, String>,
557    seen: &mut HashSet<String>,
558) -> Result<(), RequestError> {
559    let call_id = call.id().as_str();
560    if call_id.is_empty() {
561        return Err(RequestError::EmptyToolCallId);
562    }
563    if call.name().as_str().is_empty() {
564        return Err(RequestError::EmptyToolCallName {
565            call_id: call_id.into(),
566        });
567    }
568    if !seen.insert(call_id.into()) {
569        return Err(RequestError::DuplicateToolCallId {
570            call_id: call_id.into(),
571        });
572    }
573    pending.insert(call_id.into(), call.name().as_str().into());
574    Ok(())
575}
576
577fn validate_tool_result(
578    call_id: &Id,
579    tool_name: &tool_call::Name,
580    pending: &mut HashMap<String, String>,
581) -> Result<(), RequestError> {
582    let call_id = call_id.as_str();
583    if call_id.is_empty() {
584        return Err(RequestError::EmptyToolResultId);
585    }
586    if tool_name.as_str().is_empty() {
587        return Err(RequestError::EmptyToolResultName {
588            call_id: call_id.into(),
589        });
590    }
591    let Some(expected) = pending.get(call_id) else {
592        return Err(RequestError::OrphanToolResult {
593            call_id: call_id.into(),
594        });
595    };
596    if expected != tool_name.as_str() {
597        return Err(RequestError::ToolResultNameMismatch {
598            call_id: call_id.into(),
599            expected: expected.clone(),
600            actual: tool_name.as_str().into(),
601        });
602    }
603    pending.remove(call_id);
604    Ok(())
605}
606
607/// The complete owned input to one model call.
608///
609/// Its fields are immutable from the public API; provider adapters receive an
610/// owned value and must map local tools and hosted extensions through their
611/// distinct lanes.
612#[derive(Clone, Debug)]
613pub struct Request {
614    system_instruction: Vec<Part>,
615    messages: Vec<Item>,
616    tools: Vec<ClientTool>,
617    params: SamplingParams,
618    extensions: Vec<Envelope>,
619    ephemeral: Vec<Part>,
620}
621
622impl Request {
623    /// Returns ordered portable system content.
624    #[must_use]
625    pub fn system_instruction(&self) -> &[Part] {
626        &self.system_instruction
627    }
628    /// Returns the owned transcript projection.
629    ///
630    /// Every item here is [`ModelVisibility::Visible`] and every tool exchange in it is
631    /// closed, because [`RequestPlan::try_into_request`] is the only way to build this
632    /// value and it applies both rules. A provider adapter maps what it is
633    /// given; it never has to decide what the model may see.
634    #[must_use]
635    pub fn messages(&self) -> &[Item] {
636        &self.messages
637    }
638    /// Returns only client-local tools.
639    #[must_use]
640    pub fn tools(&self) -> &[ClientTool] {
641        &self.tools
642    }
643    /// Returns frozen sampling controls.
644    #[must_use]
645    pub const fn sampling(&self) -> &SamplingParams {
646        &self.params
647    }
648    /// Returns only provider-hosted/model-native extensions.
649    #[must_use]
650    pub fn extensions(&self) -> &[Envelope] {
651        &self.extensions
652    }
653    /// Returns volatile tail content for this call.
654    ///
655    /// Ephemeral content is a lane of its own: it is never an [`Item`], never
656    /// enters the transcript, and never survives the Step that produced it. A
657    /// replay or equivalence check drawn over the transcript, or over
658    /// [`Request::messages`], therefore already excludes it and needs no
659    /// separate switch to say so.
660    #[must_use]
661    pub fn ephemeral(&self) -> &[Part] {
662        &self.ephemeral
663    }
664}
665
666/// Static identity and capabilities snapshotted by an Agent revision.
667///
668/// Every [`Client`] has to return one of these, so a later capability flag would
669/// break every provider in existence if callers built it with a struct literal.
670/// Fields are therefore private: construction goes through [`Info::new`] plus the
671/// capability setters, and a capability added later defaults to "unsupported" for
672/// providers that predate it.
673///
674/// # The named capability set is closed
675///
676/// A named field is admissible here only when it states something about a
677/// reef-owned primitive: [`Info::supports_tools`] is a statement about reef's
678/// tool mechanism, [`Info::supports_thinking`] about
679/// [`Segment::Thinking`] and
680/// [`ContentKind::Thinking`], [`Info::supports_vision`] about non-text
681/// [`PartKind`](crate::value::content::PartKind)s, and
682/// [`Info::context_window`] is a count of reef's own
683/// [`Item`] budget. Wire-protocol quirks, thinking formats, pricing tiers and
684/// session-affinity formats describe providers rather than reef primitives, so
685/// they travel in the [`Envelope`] extension channel and core never learns their
686/// vocabulary.
687///
688/// ```
689/// use reef_core::opaque;
690/// use reef_core::runtime::model;
691///
692/// let info = model::Info::new("example-model".to_owned(), 200_000)
693///     .with_tools(true)
694///     .with_thinking(true)
695///     .with_extension(
696///         opaque::Envelope::try_new(
697///             "example.compat".to_owned(),
698///             "matrix".to_owned(),
699///             opaque::Payload::copy_from_slice(br#"{"thinkingFormat":"example"}"#),
700///         )
701///         .unwrap(),
702///     );
703///
704/// assert_eq!(info.id(), "example-model");
705/// assert_eq!(info.context_window(), 200_000);
706/// assert!(info.supports_tools() && info.supports_thinking() && !info.supports_vision());
707/// // Provider-defined bytes; core never parsed them.
708/// let compat = info.extension("example.compat", "matrix").unwrap();
709/// assert_eq!(compat.as_bytes(), br#"{"thinkingFormat":"example"}"#);
710/// assert!(info.extension("example.compat", "absent").is_none());
711/// ```
712///
713/// # Equality
714///
715/// Field by field, and the extension list **in order**. Two snapshots are equal
716/// when they name the same model, state the same context window, answer every
717/// capability the same way, and carry the same extensions in the same
718/// positions; an [`Envelope`] compares by the byte-wise rule that type
719/// documents, so equality here inherits it rather than interpreting a payload.
720/// The identifier compares exactly — no case folding, no trimming — because it
721/// is a provider-owned string core assigns no structure to.
722///
723/// Ordering is part of it because [`Info::extensions`] publishes insertion
724/// order. A set-like equality would let `a == b` hold while
725/// `a.extensions() != b.extensions()`, which is a value disagreeing with its own
726/// accessor; and a provider whose snapshot lists its extensions in a different
727/// order on each call is not returning the immutable snapshot this type is
728/// documented to be, so the stricter reading is also the one that catches that.
729///
730/// The relation is total, so this is an [`Eq`]. Growth stays additive: a
731/// capability added later has a defined "unsupported" default, so two values
732/// that were equal before it existed are still equal after.
733///
734/// ```
735/// use reef_core::opaque;
736/// use reef_core::runtime::model;
737///
738/// let extension = |kind: &str| {
739///     opaque::Envelope::try_new(
740///         "example.compat".to_owned(),
741///         kind.to_owned(),
742///         opaque::Payload::copy_from_slice(b"{}"),
743///     )
744///     .unwrap()
745/// };
746/// let info = |first: &str, second: &str| {
747///     model::Info::new("example-model".to_owned(), 200_000)
748///         .with_extensions([extension(first), extension(second)])
749/// };
750///
751/// assert_eq!(info("a", "b"), info("a", "b"));
752/// // The same two facts, listed the other way round.
753/// assert_ne!(info("a", "b"), info("b", "a"));
754/// ```
755#[derive(Clone, Debug, Eq, PartialEq)]
756pub struct Info {
757    id: String,
758    context_window: u64,
759    supports_tools: bool,
760    supports_vision: bool,
761    supports_thinking: bool,
762    extensions: Vec<Envelope>,
763}
764
765impl Info {
766    /// Creates a capability snapshot that supports nothing beyond plain text.
767    #[must_use]
768    pub const fn new(id: String, context_window: u64) -> Self {
769        Self {
770            id,
771            context_window,
772            supports_tools: false,
773            supports_vision: false,
774            supports_thinking: false,
775            extensions: Vec::new(),
776        }
777    }
778
779    /// Declares whether client-local tool calling is supported.
780    #[must_use]
781    pub const fn with_tools(mut self, supported: bool) -> Self {
782        self.supports_tools = supported;
783        self
784    }
785
786    /// Declares whether image input is supported.
787    #[must_use]
788    pub const fn with_vision(mut self, supported: bool) -> Self {
789        self.supports_vision = supported;
790        self
791    }
792
793    /// Declares whether reasoning output is supported.
794    #[must_use]
795    pub const fn with_thinking(mut self, supported: bool) -> Self {
796        self.supports_thinking = supported;
797        self
798    }
799
800    /// Appends one provider-supplied capability fact.
801    #[must_use]
802    pub fn with_extension(mut self, extension: Envelope) -> Self {
803        self.extensions.push(extension);
804        self
805    }
806
807    /// Appends provider-supplied capability facts in iteration order.
808    #[must_use]
809    pub fn with_extensions(mut self, extensions: impl IntoIterator<Item = Envelope>) -> Self {
810        self.extensions.extend(extensions);
811        self
812    }
813
814    /// Returns the provider model identifier.
815    #[must_use]
816    pub fn id(&self) -> &str {
817        &self.id
818    }
819
820    /// Returns the maximum input size in tokens.
821    #[must_use]
822    pub const fn context_window(&self) -> u64 {
823        self.context_window
824    }
825
826    /// Reports whether client-local tool calling is supported.
827    #[must_use]
828    pub const fn supports_tools(&self) -> bool {
829        self.supports_tools
830    }
831
832    /// Reports whether image input is supported.
833    #[must_use]
834    pub const fn supports_vision(&self) -> bool {
835        self.supports_vision
836    }
837
838    /// Reports whether reasoning output is supported.
839    #[must_use]
840    pub const fn supports_thinking(&self) -> bool {
841        self.supports_thinking
842    }
843
844    /// Returns every provider-supplied capability fact in insertion order.
845    #[must_use]
846    pub fn extensions(&self) -> &[Envelope] {
847        &self.extensions
848    }
849
850    /// Returns the first capability fact matching `namespace` and `kind`.
851    #[must_use]
852    pub fn extension(&self, namespace: &str, kind: &str) -> Option<&Payload> {
853        self.extensions
854            .iter()
855            .find(|extension| extension.namespace() == namespace && extension.kind() == kind)
856            .map(Envelope::data)
857    }
858}
859
860/// Portable semantic reason for generation completion.
861#[derive(Clone, Copy, Debug, Eq, PartialEq)]
862#[non_exhaustive]
863pub enum CompletionReason {
864    /// Provider supplied no portable classification.
865    Unknown,
866    /// The model ended normally.
867    Stop,
868    /// An output limit was reached.
869    Length,
870    /// The model requested one or more tools.
871    ToolCalls,
872    /// Provider safety filtering ended generation.
873    ContentFilter,
874}
875
876/// Token consumption reported by a provider, as one increment.
877///
878/// This is the payload of [`Event::Usage`], which is incremental: these five
879/// numbers describe the tokens consumed since the previous usage event of the
880/// same generation, and a consumer adds them up.
881///
882/// ```
883/// use reef_core::runtime::model;
884///
885/// // The common case: a provider that reports one total per call.
886/// let usage = model::TokenUsage::new(1_200, 340);
887/// assert_eq!(usage.total, 1_540);
888///
889/// // A provider that also breaks its counts down. Neither detail is added to
890/// // the count it belongs to; both are already inside it.
891/// let detailed = model::TokenUsage::new(1_200, 340)
892///     .with_cached(900)
893///     .with_reasoning(210);
894/// assert_eq!(detailed.prompt, 1_200);
895/// assert_eq!(detailed.total, 1_540);
896/// assert_eq!(detailed.cached, 900);
897/// assert_eq!(detailed.reasoning, 210);
898/// ```
899///
900/// # What the five numbers mean
901///
902/// The two detail fields are **parts of** the counts above them, not additions
903/// to them, which is the convention providers that report them already use. An
904/// adapter that added them separately would make every budget over-count.
905///
906/// - `prompt` is every input token, `cached` included.
907/// - `completion` is every output token, `reasoning` included.
908/// - `total` is the provider's own total for this increment. [`Self::new`] sets
909///   it to `prompt + completion`, which is what a provider that reports no
910///   separate total means; [`Self::with_total`] states a different one, for a
911///   provider that does.
912///
913/// # The fields are public, deliberately
914///
915/// Every other value type in this crate hides its fields, and this one does not,
916/// because the rule is about who has to construct the value rather than about
917/// consistency of style. A struct that a trait method *returns* — [`Info`], two
918/// types away — must be buildable by every provider that will ever exist, so a
919/// field added later would break all of them, and its fields are private with a
920/// builder in front. A `TokenUsage` is built inside one optional event, and read
921/// by policies that want all five numbers at once. Privatising the fields would
922/// add five getters to the five setters, make the `#[non_exhaustive]` above a
923/// no-op that then has to be removed, and buy nothing: the attribute already
924/// stops an external struct literal, so a sixth field stays additive either way.
925#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
926#[non_exhaustive]
927pub struct TokenUsage {
928    /// Input tokens consumed, including [`cached`](Self::cached).
929    pub prompt: u64,
930    /// Output tokens generated, including [`reasoning`](Self::reasoning).
931    pub completion: u64,
932    /// Provider-reported total for this increment.
933    pub total: u64,
934    /// The part of [`prompt`](Self::prompt) that was served from cache.
935    pub cached: u64,
936    /// The part of [`completion`](Self::completion) that was reasoning.
937    pub reasoning: u64,
938}
939
940impl TokenUsage {
941    /// Reports one increment of input and output tokens.
942    ///
943    /// `total` becomes `prompt + completion`, saturating; the two detail fields
944    /// are zero. Each is stated separately by the builder below when a provider
945    /// reports it.
946    #[must_use]
947    pub const fn new(prompt: u64, completion: u64) -> Self {
948        Self {
949            prompt,
950            completion,
951            total: prompt.saturating_add(completion),
952            cached: 0,
953            reasoning: 0,
954        }
955    }
956
957    /// States a provider-reported total that is not `prompt + completion`.
958    #[must_use]
959    pub const fn with_total(mut self, total: u64) -> Self {
960        self.total = total;
961        self
962    }
963
964    /// States how much of [`prompt`](Self::prompt) came from cache.
965    #[must_use]
966    pub const fn with_cached(mut self, cached: u64) -> Self {
967        self.cached = cached;
968        self
969    }
970
971    /// States how much of [`completion`](Self::completion) was reasoning.
972    #[must_use]
973    pub const fn with_reasoning(mut self, reasoning: u64) -> Self {
974        self.reasoning = reasoning;
975        self
976    }
977}
978
979/// Whether a streamed portable content item is answer text or reasoning.
980#[derive(Clone, Copy, Debug, Eq, PartialEq)]
981pub enum ContentKind {
982    /// User-visible assistant answer text.
983    Text,
984    /// Model reasoning or thinking content.
985    Thinking,
986}
987
988/// One normalized event produced by a model provider adapter.
989///
990/// Deltas open an item identity and finals close it. Tool calls have an explicit
991/// start/arguments/final lifecycle; [`StreamGrammar`] validates every pairing.
992///
993/// **Deltas are optional.** A provider that answers in one frame emits the final
994/// alone, and the final's payload is the whole item; see
995/// [`StreamGrammar::accept`]. What a final may never do is contradict deltas
996/// that were actually sent.
997#[derive(Clone)]
998pub enum Event {
999    /// A fragment of one text or thinking item.
1000    ContentDelta {
1001        /// Stable item identity.
1002        id: String,
1003        /// Portable content lane.
1004        kind: ContentKind,
1005        /// Next exact text fragment.
1006        delta: String,
1007    },
1008    /// The complete content and extensions for the same item.
1009    ContentFinal {
1010        /// Identity opened by preceding deltas, or by this event when there were
1011        /// none.
1012        id: String,
1013        /// Content lane, matching every delta.
1014        kind: ContentKind,
1015        /// The whole item: the exact concatenation of all deltas, or, when no
1016        /// delta was sent, the content itself.
1017        content: String,
1018        /// Provider data owned by this final item.
1019        extensions: SegmentExtensions,
1020    },
1021    /// Opens a client-local tool call.
1022    ///
1023    /// A provider that delivers a call complete in one frame may omit this and
1024    /// send only [`ToolCallFinal`](Event::ToolCallFinal), which names the tool
1025    /// itself.
1026    ToolCallStart {
1027        /// Model-assigned call identity.
1028        id: Id,
1029        /// Selected local tool name.
1030        name: tool_call::Name,
1031    },
1032    /// Adds opaque argument bytes to the open tool call.
1033    ToolCallArgumentsDelta {
1034        /// Identity of the open call.
1035        id: Id,
1036        /// Next exact argument fragment.
1037        delta: Payload,
1038    },
1039    /// Closes a tool call with the exact accumulated identity, name, and bytes.
1040    ///
1041    /// When no argument delta preceded it, this event *is* the call: its
1042    /// identity, tool name and argument bytes are the whole of what reef records
1043    /// and what the executor receives.
1044    ToolCallFinal {
1045        /// Complete call value.
1046        call: ToolCall,
1047        /// Provider data owned by this call.
1048        extensions: SegmentExtensions,
1049    },
1050    /// Reports token accounting without changing item lifecycle.
1051    ///
1052    /// # Usage is incremental, and normalising it is the adapter's obligation
1053    ///
1054    /// A generation may carry any number of these. **Each one reports the tokens
1055    /// consumed since the previous `Usage` of the same generation**, so a
1056    /// generation's totals are the sum of its usage events, and one event
1057    /// carrying the whole call's totals is the ordinary single-increment case.
1058    ///
1059    /// Reef does not and cannot check this. A provider that reports running
1060    /// totals and a provider that reports increments emit sequences core has no
1061    /// way to tell apart, so the rule is an obligation on the adapter rather than
1062    /// a grammar rule: **an adapter for a provider that reports running totals
1063    /// must emit the difference**, or withhold the numbers and emit one event at
1064    /// the end. An adapter that forwards running totals verbatim is not
1065    /// well-formed, and nothing will say so.
1066    ///
1067    /// The rule is chosen because summation is the only operation available to
1068    /// the consumer that receives these. They reach a hook through
1069    /// [`ObserverHooks::model_event`](crate::runtime::hook::ObserverHooks::model_event)
1070    /// and nowhere else, one event at a time, with no per-generation accumulator
1071    /// of reef's own to subtract from — so a budget policy adds them up. Under
1072    /// the incremental rule that is exact at every scope: within a generation,
1073    /// across the generations of a Run, and across Runs. Forwarded running
1074    /// totals would double-count, and every budget built on them would fire
1075    /// early.
1076    Usage(TokenUsage),
1077    /// The single terminal event.
1078    Done {
1079        /// Provider's verbatim finish label.
1080        finish_reason: String,
1081        /// Portable completion classification.
1082        completion: CompletionReason,
1083        /// Provider data owned by the assistant record.
1084        provider_data: Vec<Envelope>,
1085    },
1086}
1087
1088impl fmt::Debug for Event {
1089    /// Keeps every identity and lane, and sizes the two content fields.
1090    ///
1091    /// `delta` and `content` are the only members of this enum that own model
1092    /// bytes directly. Everything else either identifies an item, classifies a
1093    /// lane, counts tokens, or is a value that already redacts itself — and a
1094    /// stream is debugged by its lifecycle, which those facts describe fully.
1095    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1096        match self {
1097            Self::ContentDelta { id, kind, delta } => formatter
1098                .debug_struct("ContentDelta")
1099                .field("id", id)
1100                .field("kind", kind)
1101                .field("delta", &redact::Bytes(delta.len()))
1102                .finish(),
1103            Self::ContentFinal {
1104                id,
1105                kind,
1106                content,
1107                extensions,
1108            } => formatter
1109                .debug_struct("ContentFinal")
1110                .field("id", id)
1111                .field("kind", kind)
1112                .field("content", &redact::Bytes(content.len()))
1113                .field("extensions", extensions)
1114                .finish(),
1115            Self::ToolCallStart { id, name } => formatter
1116                .debug_struct("ToolCallStart")
1117                .field("id", id)
1118                .field("name", name)
1119                .finish(),
1120            Self::ToolCallArgumentsDelta { id, delta } => formatter
1121                .debug_struct("ToolCallArgumentsDelta")
1122                .field("id", id)
1123                .field("delta", delta)
1124                .finish(),
1125            Self::ToolCallFinal { call, extensions } => formatter
1126                .debug_struct("ToolCallFinal")
1127                .field("call", call)
1128                .field("extensions", extensions)
1129                .finish(),
1130            Self::Usage(usage) => formatter.debug_tuple("Usage").field(usage).finish(),
1131            Self::Done {
1132                finish_reason,
1133                completion,
1134                provider_data,
1135            } => formatter
1136                .debug_struct("Done")
1137                .field("finish_reason", finish_reason)
1138                .field("completion", completion)
1139                .field("provider_data", provider_data)
1140                .finish(),
1141        }
1142    }
1143}
1144
1145/// A stable normalized-stream grammar violation.
1146#[derive(Clone, Debug, Eq, PartialEq)]
1147#[non_exhaustive]
1148pub enum StreamError {
1149    /// An item identity was empty.
1150    EmptyItemId,
1151    /// A tool name was empty.
1152    EmptyToolName,
1153    /// An identity was reopened or reused after completion.
1154    DuplicateItemId(String),
1155    /// An event did not match the identity's active lifecycle.
1156    InvalidLifecycle(String),
1157    /// A final payload differed from accumulated deltas.
1158    FinalPayloadMismatch(String),
1159    /// Terminal arrived while one or more items remained open.
1160    UnfinishedItems,
1161    /// An event was observed after terminal.
1162    EventAfterDone,
1163    /// End-of-stream occurred without terminal.
1164    MissingTerminal,
1165}
1166
1167impl fmt::Display for StreamError {
1168    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1169        match self {
1170            Self::EmptyItemId => formatter.write_str("model stream item id is empty"),
1171            Self::EmptyToolName => formatter.write_str("model stream tool name is empty"),
1172            Self::DuplicateItemId(id) => write!(formatter, "duplicate model stream item id: {id}"),
1173            Self::InvalidLifecycle(id) => {
1174                write!(formatter, "invalid model stream lifecycle for: {id}")
1175            }
1176            Self::FinalPayloadMismatch(id) => {
1177                write!(formatter, "model stream final payload mismatch for: {id}")
1178            }
1179            Self::UnfinishedItems => {
1180                formatter.write_str("model stream terminal has unfinished items")
1181            }
1182            Self::EventAfterDone => {
1183                formatter.write_str("model stream event emitted after terminal")
1184            }
1185            Self::MissingTerminal => formatter.write_str("model stream ended without terminal"),
1186        }
1187    }
1188}
1189
1190impl Error for StreamError {}
1191
1192enum OpenItem {
1193    Content { kind: ContentKind, value: String },
1194    Tool { name: String, arguments: Vec<u8> },
1195}
1196
1197/// Incremental validator for exactly one [`Client`] event stream.
1198#[derive(Default)]
1199pub struct StreamGrammar {
1200    open: HashMap<String, OpenItem>,
1201    seen: HashSet<String>,
1202    done: bool,
1203}
1204
1205impl fmt::Debug for StreamGrammar {
1206    /// Reports the validator's position in the stream, not the stream.
1207    ///
1208    /// The open map accumulates the exact text and argument bytes each item has
1209    /// produced so far, so it is counted rather than shown; the counts and the
1210    /// terminal flag are what a grammar violation is actually diagnosed from.
1211    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1212        formatter
1213            .debug_struct("StreamGrammar")
1214            .field("open", &self.open.len())
1215            .field("seen", &self.seen.len())
1216            .field("done", &self.done)
1217            .finish()
1218    }
1219}
1220
1221impl StreamGrammar {
1222    /// Creates a validator before the first event.
1223    #[must_use]
1224    pub fn new() -> Self {
1225        Self::default()
1226    }
1227
1228    /// Validates one event without taking ownership from its consumer.
1229    ///
1230    /// # Errors
1231    ///
1232    /// A rejected event means the provider's stream is not a well-formed
1233    /// sequence, which the caller must treat as a failed generation rather than
1234    /// as a recoverable gap: the accumulated state is no longer a faithful
1235    /// picture of what the provider sent.
1236    ///
1237    /// - [`EventAfterDone`](StreamError::EventAfterDone) for anything at all
1238    ///   after the terminal event. Checked before the event's own shape, because
1239    ///   after a terminal there is no lifecycle left to be consistent with.
1240    /// - [`EmptyItemId`](StreamError::EmptyItemId) for an event with no identity,
1241    ///   and [`EmptyToolName`](StreamError::EmptyToolName) for a tool event that
1242    ///   does not name a tool. Neither can be correlated with anything.
1243    /// - [`DuplicateItemId`](StreamError::DuplicateItemId) if an identity that
1244    ///   already completed is opened again. Identities are single-use for the
1245    ///   whole stream, so a reused one is a provider defect rather than a second
1246    ///   item.
1247    /// - [`InvalidLifecycle`](StreamError::InvalidLifecycle) if the event does not
1248    ///   fit the identity's active state — content deltas for a tool call, a
1249    ///   tool final for an identity opened as content, or a content kind that
1250    ///   changed mid-item.
1251    /// - [`FinalPayloadMismatch`](StreamError::FinalPayloadMismatch) if a final
1252    ///   payload is not exactly what the deltas accumulated. This is the check
1253    ///   that makes incremental output trustworthy: a consumer that rendered the
1254    ///   deltas has already shown the user something, so a final that disagrees
1255    ///   cannot be silently preferred.
1256    /// - [`UnfinishedItems`](StreamError::UnfinishedItems) if the terminal event
1257    ///   arrives while any identity is still open.
1258    ///
1259    /// # Deltas are optional
1260    ///
1261    /// A final may open its own item. [`Event::ContentFinal`] for an identity no
1262    /// delta ever opened, and [`Event::ToolCallFinal`] whose call accumulated no
1263    /// [`ToolCallArgumentsDelta`](Event::ToolCallArgumentsDelta) — whether or not
1264    /// a [`ToolCallStart`](Event::ToolCallStart) announced it — are both
1265    /// well-formed, and the final's payload is the item. A provider that answers
1266    /// in one frame is not required to synthesise a delta equal to its own
1267    /// payload, which is the workaround every adapter for such a provider would
1268    /// otherwise have to invent.
1269    ///
1270    /// Nothing about the mismatch rule is relaxed by this. What
1271    /// `FinalPayloadMismatch` protects is a consumer that has *already rendered*
1272    /// something, so it applies exactly when deltas were sent: a final that
1273    /// contradicts a non-empty accumulation is still rejected. With no deltas
1274    /// there is nothing rendered for the final to contradict.
1275    ///
1276    /// Identities are spent either way. A single-frame final inserts its
1277    /// identity, so reusing it afterwards is
1278    /// [`DuplicateItemId`](StreamError::DuplicateItemId) exactly as reusing a
1279    /// streamed one is.
1280    pub fn accept(&mut self, event: &Event) -> Result<(), StreamError> {
1281        if self.done {
1282            return Err(StreamError::EventAfterDone);
1283        }
1284        match event {
1285            Event::ContentDelta { id, kind, delta } => self.content_delta(id, *kind, delta),
1286            Event::ContentFinal {
1287                id, kind, content, ..
1288            } => self.content_final(id, *kind, content),
1289            Event::ToolCallStart { id, name } => self.tool_start(id, name),
1290            Event::ToolCallArgumentsDelta { id, delta } => self.tool_delta(id, delta),
1291            Event::ToolCallFinal { call, .. } => self.tool_final(call),
1292            Event::Usage(_) => Ok(()),
1293            Event::Done { .. } if self.open.is_empty() => {
1294                self.done = true;
1295                Ok(())
1296            }
1297            Event::Done { .. } => Err(StreamError::UnfinishedItems),
1298        }
1299    }
1300
1301    /// Verifies that the producer ended after exactly one terminal event.
1302    ///
1303    /// # Errors
1304    ///
1305    /// [`MissingTerminal`](StreamError::MissingTerminal) if the stream ended
1306    /// without one. This is the one violation [`accept`](Self::accept) cannot
1307    /// report, because it is the absence of an event rather than a bad one: a
1308    /// stream that simply stops is indistinguishable, event by event, from one
1309    /// that is still going.
1310    pub fn finish(self) -> Result<(), StreamError> {
1311        if self.done {
1312            Ok(())
1313        } else {
1314            Err(StreamError::MissingTerminal)
1315        }
1316    }
1317
1318    fn content_delta(
1319        &mut self,
1320        id: &str,
1321        kind: ContentKind,
1322        delta: &str,
1323    ) -> Result<(), StreamError> {
1324        self.require_id(id)?;
1325        if let Some(item) = self.open.get_mut(id) {
1326            return match item {
1327                OpenItem::Content {
1328                    kind: active,
1329                    value,
1330                } if *active == kind => {
1331                    value.push_str(delta);
1332                    Ok(())
1333                }
1334                _ => Err(StreamError::InvalidLifecycle(id.into())),
1335            };
1336        }
1337        if !self.seen.insert(id.into()) {
1338            return Err(StreamError::DuplicateItemId(id.into()));
1339        }
1340        self.open.insert(
1341            id.into(),
1342            OpenItem::Content {
1343                kind,
1344                value: delta.into(),
1345            },
1346        );
1347        Ok(())
1348    }
1349
1350    fn content_final(
1351        &mut self,
1352        id: &str,
1353        kind: ContentKind,
1354        content: &str,
1355    ) -> Result<(), StreamError> {
1356        self.require_id(id)?;
1357        match self.open.get(id) {
1358            Some(OpenItem::Content {
1359                kind: active,
1360                value,
1361            }) if *active == kind && value == content => {}
1362            Some(OpenItem::Content { kind: active, .. }) if *active == kind => {
1363                return Err(StreamError::FinalPayloadMismatch(id.into()));
1364            }
1365            Some(_) => return Err(StreamError::InvalidLifecycle(id.into())),
1366            // A provider that does not stream sends the whole item in one
1367            // frame. Nothing was accumulated, so nothing can disagree with the
1368            // final, and the identity is spent exactly as a streamed one is.
1369            None => {
1370                if self.seen.insert(id.into()) {
1371                    return Ok(());
1372                }
1373                return Err(StreamError::DuplicateItemId(id.into()));
1374            }
1375        }
1376        self.open.remove(id);
1377        Ok(())
1378    }
1379
1380    fn tool_start(&mut self, id: &Id, name: &tool_call::Name) -> Result<(), StreamError> {
1381        let id = id.as_str();
1382        self.require_id(id)?;
1383        if name.as_str().is_empty() {
1384            return Err(StreamError::EmptyToolName);
1385        }
1386        if !self.seen.insert(id.into()) {
1387            return Err(StreamError::DuplicateItemId(id.into()));
1388        }
1389        self.open.insert(
1390            id.into(),
1391            OpenItem::Tool {
1392                name: name.as_str().into(),
1393                arguments: Vec::new(),
1394            },
1395        );
1396        Ok(())
1397    }
1398
1399    fn tool_delta(&mut self, id: &Id, delta: &Payload) -> Result<(), StreamError> {
1400        let id = id.as_str();
1401        self.require_id(id)?;
1402        match self.open.get_mut(id) {
1403            Some(OpenItem::Tool { arguments, .. }) => {
1404                arguments.extend_from_slice(delta.as_bytes());
1405                Ok(())
1406            }
1407            _ => Err(StreamError::InvalidLifecycle(id.into())),
1408        }
1409    }
1410
1411    fn tool_final(&mut self, call: &ToolCall) -> Result<(), StreamError> {
1412        let id = call.id().as_str();
1413        self.require_id(id)?;
1414        if call.name().as_str().is_empty() {
1415            return Err(StreamError::EmptyToolName);
1416        }
1417        match self.open.get(id) {
1418            // An open call with nothing accumulated is the single-frame shape:
1419            // the start announced the call and the final carries all of it.
1420            Some(OpenItem::Tool { name, arguments })
1421                if name == call.name().as_str()
1422                    && (arguments.is_empty() || arguments == call.arguments().as_bytes()) => {}
1423            Some(OpenItem::Tool { .. }) => {
1424                return Err(StreamError::FinalPayloadMismatch(id.into()));
1425            }
1426            Some(OpenItem::Content { .. }) => {
1427                return Err(StreamError::InvalidLifecycle(id.into()));
1428            }
1429            // A call announced by its own final, with no start at all.
1430            None => {
1431                if self.seen.insert(id.into()) {
1432                    return Ok(());
1433                }
1434                return Err(StreamError::DuplicateItemId(id.into()));
1435            }
1436        }
1437        self.open.remove(id);
1438        Ok(())
1439    }
1440
1441    const fn require_id(&self, id: &str) -> Result<(), StreamError> {
1442        if id.is_empty() {
1443            Err(StreamError::EmptyItemId)
1444        } else {
1445            Ok(())
1446        }
1447    }
1448}
1449
1450/// Narrow, statically dispatched model provider boundary.
1451///
1452/// This is the one trait reef cannot ship an implementation of: it is the
1453/// adapter between reef's [`Request`] and whatever actually answers it. Two
1454/// methods, one of which is a constant.
1455///
1456/// The explicit RPITIT future follows ADR-013 and avoids `async-trait`. The
1457/// returned stream remains provider-owned; callers must apply [`StreamGrammar`].
1458///
1459/// # Implementing it
1460///
1461/// [`Client::Stream`] is bounded by [`Stream`], which lives in `futures-core`.
1462/// That crate is deliberately combinator-free — there is no `stream::iter` and
1463/// no `StreamExt` — so the associated type is a type you write, with a
1464/// `poll_next`, and it is about ten lines. Reach for the bound through
1465/// [`reef_core::futures_core`](crate::futures_core) rather than adding the crate
1466/// yourself, so the two versions cannot disagree.
1467///
1468/// This is the whole of a provider that replays a fixed script, which is what a
1469/// test double looks like:
1470///
1471/// ```
1472/// use std::future::{Future, ready};
1473/// use std::pin::Pin;
1474/// use std::task::{Context, Poll};
1475///
1476/// use reef_core::futures_core::Stream;
1477/// use reef_core::runtime::model;
1478/// use reef_core::value::content::SegmentExtensions;
1479///
1480/// /// The events of one call, oldest first.
1481/// #[derive(Debug)]
1482/// struct Scripted(std::collections::VecDeque<model::Event>);
1483///
1484/// impl Stream for Scripted {
1485///     type Item = Result<model::Event, Unreachable>;
1486///
1487///     fn poll_next(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Option<Self::Item>> {
1488///         // A script is always ready, so this never registers a waker. A real
1489///         // adapter polls its transport here and returns `Poll::Pending` when
1490///         // that transport has registered one.
1491///         Poll::Ready(self.0.pop_front().map(Ok))
1492///     }
1493/// }
1494///
1495/// #[derive(Debug)]
1496/// struct Unreachable;
1497///
1498/// impl std::fmt::Display for Unreachable {
1499///     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1500///         f.write_str("a scripted provider cannot fail")
1501///     }
1502/// }
1503///
1504/// impl std::error::Error for Unreachable {}
1505///
1506/// #[derive(Debug)]
1507/// struct ScriptedModel;
1508///
1509/// impl model::Client for ScriptedModel {
1510///     type Error = Unreachable;
1511///     type Stream = Scripted;
1512///
1513///     fn info(&self) -> model::Info {
1514///         model::Info::new("scripted/v1".to_owned(), 8_192).with_tools(true)
1515///     }
1516///
1517///     fn generate(
1518///         &self,
1519///         request: model::Request,
1520///     ) -> impl Future<Output = Result<Self::Stream, Self::Error>> + Send {
1521///         // `request.messages()` is already projected: every item in it is
1522///         // model-visible and every tool exchange in it is closed.
1523///         let _turns = request.messages().len();
1524///         ready(Ok(Scripted(
1525///             [
1526///                 model::Event::ContentFinal {
1527///                     id: "answer".to_owned(),
1528///                     kind: model::ContentKind::Text,
1529///                     content: "Hello.".to_owned(),
1530///                     extensions: SegmentExtensions::new(String::new(), None, None),
1531///                 },
1532///                 model::Event::Usage(model::TokenUsage::new(12, 3)),
1533///                 model::Event::Done {
1534///                     finish_reason: "stop".to_owned(),
1535///                     completion: model::CompletionReason::Stop,
1536///                     provider_data: Vec::new(),
1537///                 },
1538///             ]
1539///             .into(),
1540///         )))
1541///     }
1542/// }
1543/// ```
1544///
1545/// Every event that stream yields is checked by [`StreamGrammar`] before reef
1546/// acts on it, so an adapter can validate its own output against the same rules
1547/// in its own tests.
1548pub trait Client: Send + Sync {
1549    /// Provider-specific call failure.
1550    type Error: Error + Send + Sync + 'static;
1551    /// Normalized event stream for one call.
1552    type Stream: Stream<Item = Result<Event, Self::Error>> + Send;
1553
1554    /// Returns the immutable model capability snapshot.
1555    fn info(&self) -> Info;
1556    /// Starts one model call from an owned request.
1557    fn generate(
1558        &self,
1559        request: Request,
1560    ) -> impl Future<Output = Result<Self::Stream, Self::Error>> + Send;
1561}