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}