Skip to main content

rig_core/serve/
handler.rs

1//! Handler dispatch, owned replies, and delivery observation.
2//!
3//! ```
4//! use rig_core::{effect::EffectId, serve::Dispatch};
5//!
6//! let dispatch = Dispatch::new(EffectId::from_raw(1), false);
7//! assert!(!dispatch.is_stream());
8//! ```
9
10use std::{
11    sync::{
12        Arc, Mutex,
13        atomic::{AtomicUsize, Ordering},
14    },
15    task::Poll,
16};
17
18use futures::StreamExt;
19
20use crate::lock;
21use crate::{
22    completion::UnsupportedOption,
23    effect::{Answered, EffectId, EffectKind, HandlerDescriptor, HandlerKey},
24    error::{ErrorKind, ErrorReport},
25    streaming::{Relayed, StreamEvents},
26    tool::Touches,
27    wasm_compat::{WasmBoxedFuture, WasmCompatSend, WasmCompatSync},
28};
29
30#[cfg(test)]
31mod tests;
32
33/// Boxed handler reply future, `Send` on native targets and locally polled on WASM.
34pub type HandlerFuture<'a> = WasmBoxedFuture<'a, Reply>;
35
36/// A registered effect handler returning an outcome or an owned stream.
37///
38/// Provider and tool authors do not implement this directly: the adapters
39/// in [`crate::serve::adapters`] wrap models, tools and indexes
40/// (`Model`, `Tool`, `VectorStoreIndex`). A
41/// host implements it for out-of-tree kinds ([`EffectKind::Custom`], typed
42/// through [`crate::effect::CustomEffect`]) or for a replayer.
43///
44/// A handler returns an outcome or an owned stream. The driver adapts that
45/// reply to the requested delivery mode. Stream execution continues after
46/// this method returns; dropping the reply cancels that work.
47///
48/// The returned future must be `Send` natively (it runs inside the driver's
49/// task; the bound is the crate's `WasmCompatSend` marker, a no-op on
50/// browser wasm). `Self::Family` is what a typed key can be proven against
51/// (a typed registration); a handler with no one
52/// family names [`crate::effect::family::Dynamic`].
53///
54/// A handler holding an `Rc` or a `Cell` is refused natively:
55///
56/// ```compile_fail
57/// use std::rc::Rc;
58/// use rig_core::{serve::{Dispatch, Reply, Serve}, effect::{EffectKind, HandlerDescriptor, family}};
59///
60/// struct Local(Rc<u8>);
61/// impl Serve for Local {
62///     type Family = family::Dynamic;
63///     fn descriptor(&self) -> HandlerDescriptor { unimplemented!() }
64///     async fn serve(&self, _kind: EffectKind, _dispatch: Dispatch) -> Reply { unimplemented!() }
65/// }
66/// ```
67///
68/// ```compile_fail
69/// use std::cell::Cell;
70/// use rig_core::{serve::{Dispatch, Reply, Serve}, effect::{EffectKind, HandlerDescriptor, family}};
71///
72/// struct Local(Cell<u8>);
73/// impl Serve for Local {
74///     type Family = family::Dynamic;
75///     fn descriptor(&self) -> HandlerDescriptor { unimplemented!() }
76///     async fn serve(&self, _kind: EffectKind, _dispatch: Dispatch) -> Reply { unimplemented!() }
77/// }
78/// ```
79pub trait Serve: WasmCompatSend + WasmCompatSync {
80    /// The family this handler serves, or `Dynamic`.
81    type Family: crate::effect::Served;
82
83    /// What this handler is: the family-keyed description a typed view
84    /// checks at bind time and a scene serializes.
85    fn descriptor(&self) -> HandlerDescriptor;
86
87    /// The [descriptor](Self::descriptor)'s key. A handler whose
88    /// descriptor is costly to build, such as a tool's argument schema,
89    /// says it without building one.
90    fn key(&self) -> HandlerKey {
91        self.descriptor().key
92    }
93
94    /// Prepare an outcome or an owned stream for the driver to consume.
95    fn serve(
96        &self,
97        kind: EffectKind,
98        dispatch: Dispatch,
99    ) -> impl Future<Output = Reply> + WasmCompatSend + use<'_, Self>;
100
101    /// What dispatching `kind` may read and change, for a tool's handler
102    /// ([`Tool::footprint`](crate::tool::Tool::footprint)); `None` when it
103    /// cannot say, such as for arguments that do not parse.
104    fn footprint(&self, kind: &EffectKind) -> Option<Touches> {
105        let _ = kind;
106        None
107    }
108
109    /// The options of `kind` this handler would leave out when it serves
110    /// it, with nothing sent: for a model's handler, what its wire or model
111    /// cannot honour ([`DynModel::check`](crate::driver::DynModel::check)).
112    /// Empty when it leaves nothing out or cannot say, as by default.
113    fn check(&self, kind: &EffectKind) -> Vec<UnsupportedOption> {
114        let _ = kind;
115        Vec::new()
116    }
117}
118
119/// Object-safe handler interface implemented for every [`Serve`].
120pub(crate) trait Handler: WasmCompatSend + WasmCompatSync {
121    fn descriptor(&self) -> HandlerDescriptor;
122    fn handle(&self, kind: EffectKind, dispatch: Dispatch) -> HandlerFuture<'_>;
123    fn footprint(&self, kind: &EffectKind) -> Option<Touches>;
124    fn check(&self, kind: &EffectKind) -> Vec<UnsupportedOption>;
125}
126
127// A type that is not a `Serve` should be told to implement `Serve`, never
128// the crate-private `Handler` this blanket impl provides.
129#[diagnostic::do_not_recommend]
130impl<T: Serve> Handler for T {
131    fn descriptor(&self) -> HandlerDescriptor {
132        Serve::descriptor(self)
133    }
134
135    fn handle(&self, kind: EffectKind, dispatch: Dispatch) -> HandlerFuture<'_> {
136        let observer = dispatch.observer.clone();
137        let folded = dispatch.folded.clone();
138        let streaming = dispatch.is_stream();
139        let level = Level::enter(&dispatch.serving);
140        Box::pin(async move {
141            let reply = self.serve(kind, dispatch).await;
142            // A handler that serves the dispatch inside another one, such
143            // as a wrapper's inner handler, leaves the observer to the
144            // outermost: what the wrapper publishes once its inner handler
145            // answered is part of the record.
146            if !level.outermost() {
147                return reply.observed(streaming, None, None);
148            }
149            let seen = observer.and_then(|slot| lock(&slot).take());
150            reply.observed(streaming, seen, folded)
151        })
152    }
153
154    fn footprint(&self, kind: &EffectKind) -> Option<Touches> {
155        Serve::footprint(self, kind)
156    }
157
158    fn check(&self, kind: &EffectKind) -> Vec<UnsupportedOption> {
159        Serve::check(self, kind)
160    }
161}
162
163/// A shared handler is a handler: `Arc<H>` forwards, so one handler can be
164/// registered under several keys.
165impl<H: Serve + ?Sized> Serve for Arc<H> {
166    type Family = H::Family;
167
168    fn descriptor(&self) -> HandlerDescriptor {
169        (**self).descriptor()
170    }
171
172    fn key(&self) -> HandlerKey {
173        (**self).key()
174    }
175
176    async fn serve(&self, kind: EffectKind, dispatch: Dispatch) -> Reply {
177        (**self).serve(kind, dispatch).await
178    }
179
180    fn footprint(&self, kind: &EffectKind) -> Option<Touches> {
181        (**self).footprint(kind)
182    }
183
184    fn check(&self, kind: &EffectKind) -> Vec<UnsupportedOption> {
185        (**self).check(kind)
186    }
187}
188
189/// One handler serving a dispatch, counted in the dispatch's handlers that
190/// serve it one inside another until it answers or is dropped.
191struct Level(Arc<AtomicUsize>);
192
193impl Level {
194    fn enter(serving: &Arc<AtomicUsize>) -> Self {
195        serving.fetch_add(1, Ordering::AcqRel);
196        Self(serving.clone())
197    }
198
199    /// Whether no handler serves the dispatch around this one: the inner
200    /// ones answered or were dropped by now.
201    fn outermost(&self) -> bool {
202        self.0.load(Ordering::Acquire) == 1
203    }
204}
205
206impl Drop for Level {
207    fn drop(&mut self) {
208        self.0.fetch_sub(1, Ordering::AcqRel);
209    }
210}
211
212/// Shared, type-erased handler. Clones retain the same handler allocation.
213/// Implements `Send + Sync` on native targets, but not on WASM.
214#[derive(Clone)]
215pub struct ErasedHandler {
216    inner: ErasedInner,
217    /// The handler's [key](Serve::key), read once.
218    key: HandlerKey,
219}
220
221#[cfg(not(target_family = "wasm"))]
222type ErasedInner = Arc<dyn Handler + Send + Sync>;
223#[cfg(target_family = "wasm")]
224type ErasedInner = Arc<dyn Handler>;
225
226impl ErasedHandler {
227    /// Erase `handler`.
228    pub fn new(handler: impl Serve + 'static) -> Self {
229        Self {
230            key: handler.key(),
231            inner: Arc::new(handler),
232        }
233    }
234
235    /// A handler that serves nothing: it is `descriptor`, and every effect
236    /// it gets is answered [`ErrorKind::HandlerUnavailable`] with `why`. For
237    /// a model whose calls a plugin answers itself, such as from a batch,
238    /// so a call that reaches the handler by mistake fails plainly while
239    /// records still name the model.
240    ///
241    /// ```
242    /// use rig_core::completion::ModelRef;
243    /// use rig_core::effect::{FamilyDescriptor, HandlerDescriptor, model_key};
244    /// use rig_core::serve::ErasedHandler;
245    ///
246    /// let descriptor = HandlerDescriptor {
247    ///     key: model_key("batch/claude"),
248    ///     family: FamilyDescriptor::Completion {
249    ///         model: ModelRef::from("batch/claude"),
250    ///         capabilities: Default::default(),
251    ///     },
252    ///     layers: Vec::new(),
253    /// };
254    /// let handler = ErasedHandler::unavailable(descriptor, "answered from the batch API");
255    /// assert_eq!(handler.key(), &model_key("batch/claude"));
256    /// ```
257    pub fn unavailable(descriptor: HandlerDescriptor, why: impl Into<String>) -> Self {
258        Self::new(Unavailable {
259            descriptor,
260            why: why.into(),
261        })
262    }
263
264    /// Wrap this handler in a [`Layer`](super::Layer): `intercept` sees
265    /// every dispatch before this handler does and every answer after.
266    /// `handler.layered(a).layered(b)` calls `b.before` first and `a.after` first.
267    pub fn layered(self, intercept: impl super::Intercept) -> Self {
268        Self::new(super::Layer::new(self, intercept))
269    }
270
271    /// Rewrite this handler's completion streams: every item of each reply
272    /// passes through a fresh `make(published)` in order, and the items it
273    /// returns go on in its place. It sees the [`Relayed::Done`](crate::streaming::Relayed::Done)
274    /// too, so a rewrite of the events also rewrites the response the reply
275    /// ends with. A unary completion is rewritten as its events, so both
276    /// delivery modes answer alike; other outcomes and errors pass as they
277    /// are. `name` joins the descriptor's layers.
278    ///
279    /// `published` is the dispatch's
280    /// [`PublishedContext`](crate::tool::PublishedContext): a fact the
281    /// rewrite inserts there before it passes the `Done` on, such as that
282    /// it split reasoning out of this reply, comes back to the driver beside
283    /// the reply and is recorded with it.
284    ///
285    /// Unlike a [`Layer`](super::Layer), the rewrite is recorded: the
286    /// record of a dispatch is the reply the consumer receives, so a replay
287    /// of it does not rewrite twice.
288    pub fn map_stream<M, F>(self, name: impl Into<String>, make: M) -> Self
289    where
290        M: Fn(Arc<crate::tool::PublishedContext>) -> F + WasmCompatSend + WasmCompatSync + 'static,
291        F: FnMut(Relayed) -> Vec<Relayed> + WasmCompatSend + 'static,
292    {
293        Self::new(super::map::MapStream::new(self, name.into(), make))
294    }
295
296    /// What the erased handler is.
297    pub fn descriptor(&self) -> HandlerDescriptor {
298        self.inner.descriptor()
299    }
300
301    /// The key of its [descriptor](Self::descriptor), without building one.
302    pub fn key(&self) -> &HandlerKey {
303        &self.key
304    }
305
306    /// Serve one effect: the driver's call, straight to the boxed handler.
307    pub fn handle(&self, kind: EffectKind, dispatch: Dispatch) -> HandlerFuture<'_> {
308        self.inner.handle(kind, dispatch)
309    }
310
311    /// What dispatching `kind` to this handler may read and change
312    /// ([`Serve::footprint`]).
313    pub fn footprint(&self, kind: &EffectKind) -> Option<Touches> {
314        self.inner.footprint(kind)
315    }
316
317    /// The options of `kind` this handler would leave out ([`Serve::check`]).
318    pub fn check(&self, kind: &EffectKind) -> Vec<UnsupportedOption> {
319        self.inner.check(kind)
320    }
321
322    /// Whether two erased handlers are the same allocation.
323    pub fn ptr_eq(&self, other: &Self) -> bool {
324        Arc::ptr_eq(&self.inner, &other.inner)
325    }
326}
327
328impl std::fmt::Debug for ErasedHandler {
329    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
330        f.debug_struct("ErasedHandler")
331            .field("key", &self.key)
332            .finish_non_exhaustive()
333    }
334}
335
336/// What [`ErasedHandler::unavailable`] erases: it answers every effect
337/// `HandlerUnavailable` with `why`.
338struct Unavailable {
339    descriptor: HandlerDescriptor,
340    why: String,
341}
342
343impl Serve for Unavailable {
344    type Family = crate::effect::family::Dynamic;
345
346    fn descriptor(&self) -> HandlerDescriptor {
347        self.descriptor.clone()
348    }
349
350    async fn serve(&self, _kind: EffectKind, _dispatch: Dispatch) -> Reply {
351        Reply::Outcome(Err(ErrorReport::new(
352            ErrorKind::HandlerUnavailable,
353            self.why.clone(),
354        )))
355    }
356}
357
358/// Forwards serving to the wrapped handler; re-erasure adds another boxed future.
359impl Serve for ErasedHandler {
360    type Family = crate::effect::family::Dynamic;
361
362    fn descriptor(&self) -> HandlerDescriptor {
363        self.inner.descriptor()
364    }
365
366    fn key(&self) -> HandlerKey {
367        self.key.clone()
368    }
369
370    async fn serve(&self, kind: EffectKind, dispatch: Dispatch) -> Reply {
371        self.handle(kind, dispatch).await
372    }
373
374    fn footprint(&self, kind: &EffectKind) -> Option<Touches> {
375        self.inner.footprint(kind)
376    }
377
378    fn check(&self, kind: &EffectKind) -> Vec<UnsupportedOption> {
379        self.inner.check(kind)
380    }
381}
382
383/// What a unary consumer, the record, or a layer's verdict takes from a
384/// stream: its outcome, the response the stream ends with or the first
385/// error item. The origin folded the response; the tap only watches for it.
386#[derive(Default)]
387pub struct StreamTap {
388    /// The tap yielded its outcome.
389    finished: bool,
390}
391
392impl StreamTap {
393    /// A new stream tap.
394    pub fn new() -> Self {
395        Self::default()
396    }
397
398    /// Returns the stream's outcome once: the response it ends with, or the
399    /// first error item. Every later call returns `None`.
400    pub fn observe(
401        &mut self,
402        item: &Result<Relayed, ErrorReport>,
403    ) -> Option<Result<Answered, ErrorReport>> {
404        if self.finished {
405            return None;
406        }
407        let outcome = match item {
408            Ok(Relayed::Origin(_) | Relayed::Item(_) | Relayed::Usage(_)) => None,
409            Ok(Relayed::Done(response)) => Some(Ok(Answered::Completion(Arc::clone(response)))),
410            Err(report) => Some(Err(report.clone())),
411        };
412        self.finished = outcome.is_some();
413        outcome
414    }
415}
416
417/// The retryable report of a reply that ended before the provider ended it
418/// ([`ProviderError::Truncated`](crate::error::ProviderError::Truncated)).
419/// Retryability does not guarantee a subsequent attempt will succeed.
420pub fn stream_truncated() -> ErrorReport {
421    ErrorReport::from(&crate::error::ProviderError::Truncated)
422}
423
424/// An answer, or an owned stream whose execution belongs to the driver.
425pub enum Reply {
426    /// The completed unary answer or a setup error.
427    Outcome(Result<Answered, ErrorReport>),
428    /// Events, including any frames after the first terminal record.
429    Stream(StreamEvents),
430}
431
432impl Reply {
433    /// Fold a stream to its first outcome, or return the unary answer.
434    pub async fn into_outcome(self) -> Result<Answered, ErrorReport> {
435        self.folded_outcome(None).await
436    }
437
438    pub(crate) async fn folded_outcome(
439        self,
440        folded: Option<Folded>,
441    ) -> Result<Answered, ErrorReport> {
442        match self {
443            Self::Outcome(outcome) => outcome,
444            Self::Stream(mut stream) => {
445                let mut fold = StreamTap::new();
446                while let Some(item) = stream.next().await {
447                    let outcome = match &folded {
448                        Some(folded) => lock(folded).take(),
449                        None => fold.observe(&item),
450                    };
451                    if let Some(outcome) = outcome {
452                        return outcome;
453                    }
454                }
455                Err(stream_truncated())
456            }
457        }
458    }
459
460    /// Convert a completion into its events, then the response;
461    /// incompatible outcomes become errors.
462    pub fn into_stream(self) -> StreamEvents {
463        match self {
464            Self::Stream(stream) => stream,
465            Self::Outcome(outcome) => Box::pin(futures::stream::iter(match outcome {
466                Ok(Answered::Completion(response)) => {
467                    let items = crate::operation::completion::events_of(&response);
468                    std::iter::once(Ok(Relayed::Origin(response.origin.clone())))
469                        .chain(items.into_iter().map(|item| Ok(Relayed::Item(item))))
470                        .chain(std::iter::once(Ok(Relayed::Done(response))))
471                        .collect()
472                }
473                Ok(other) => vec![Err(wrong_stream_answer(&other))],
474                Err(report) => vec![Err(report)],
475            })),
476        }
477    }
478
479    fn observed(self, streaming: bool, mut seen: Option<Observed>, folded: Option<Folded>) -> Self {
480        if !streaming && let Self::Outcome(outcome) = self {
481            if let Some(seen) = &mut seen {
482                seen.outcome(outcome.clone());
483            }
484            return Self::Outcome(outcome);
485        }
486        if seen.is_none() && folded.is_none() {
487            return if streaming {
488                Self::Stream(self.into_stream())
489            } else {
490                self
491            };
492        }
493        let mut original = match &self {
494            Self::Outcome(Ok(Answered::Completion(response))) => {
495                Some(Ok(Answered::Completion(response.clone())))
496            }
497            _ => None,
498        };
499        let mut stream = self.into_stream();
500        let mut fold = StreamTap::new();
501        let mut finished = false;
502        Self::Stream(Box::pin(futures::stream::poll_fn(move |cx| {
503            let item = match stream.as_mut().poll_next(cx) {
504                Poll::Pending => return Poll::Pending,
505                Poll::Ready(item) => item,
506            };
507            if let Some(item) = &item {
508                let mut outcome = if finished { None } else { fold.observe(item) };
509                finished |= outcome.is_some();
510                if let Some(seen) = &mut seen {
511                    // A unary answer made a stream is recorded as answered;
512                    // the fold's slot, when there is one, keeps the outcome.
513                    let recorded = match &outcome {
514                        None => None,
515                        Some(_) if matches!(item, Ok(Relayed::Done(_))) && original.is_some() => {
516                            original.take()
517                        }
518                        Some(_) if folded.is_none() => outcome.take(),
519                        Some(outcome) => Some(outcome.clone()),
520                    };
521                    if streaming {
522                        seen.item(item, recorded);
523                    } else if let Some(recorded) = recorded {
524                        seen.outcome(recorded);
525                    }
526                }
527                if let (Some(outcome), Some(folded)) = (outcome, &folded) {
528                    *lock(folded) = Some(outcome);
529                }
530            } else if !finished {
531                finished = true;
532                let outcome = Err(stream_truncated());
533                if let Some(seen) = &mut seen {
534                    seen.outcome(outcome.clone());
535                }
536                if let Some(folded) = &folded {
537                    *lock(folded) = Some(outcome);
538                }
539            }
540            Poll::Ready(item)
541        })))
542    }
543}
544
545// A layer and the recorder at its immediate inner boundary use the same fold.
546// Each outer boundary gets its own slot: a verdict can change that view.
547pub(crate) type Folded = Arc<Mutex<Option<Result<Answered, ErrorReport>>>>;
548
549/// An effect's identity, requested delivery mode, and driver-provided scopes.
550/// Reply transport and cancellation remain owned by the driver.
551pub struct Dispatch {
552    id: EffectId,
553    streaming: bool,
554    scopes: Vec<Arc<dyn std::any::Any + Send + Sync>>,
555    observer: Option<Arc<Mutex<Option<Observed>>>>,
556    /// How many handlers serve it now, one inside another: only the
557    /// outermost tells the observer and the fold, once it answered.
558    serving: Arc<AtomicUsize>,
559    folded: Option<Folded>,
560}
561
562impl Dispatch {
563    /// Construct the context for one effect.
564    pub fn new(id: EffectId, streaming: bool) -> Self {
565        Self {
566            id,
567            streaming,
568            scopes: Vec::new(),
569            observer: None,
570            serving: Arc::default(),
571            folded: None,
572        }
573    }
574
575    /// The effect being served.
576    pub const fn id(&self) -> EffectId {
577        self.id
578    }
579
580    /// Whether the consumer requested streaming delivery.
581    pub const fn is_stream(&self) -> bool {
582        self.streaming
583    }
584
585    /// Attach a driver scope.
586    pub fn with_scope(mut self, scope: Arc<dyn std::any::Any + Send + Sync>) -> Self {
587        self.scopes.push(scope);
588        self
589    }
590
591    /// Find a scope by its concrete type.
592    pub fn scope<T: std::any::Any + Send + Sync>(&self) -> Option<Arc<T>> {
593        self.scopes
594            .iter()
595            .find_map(|scope| Arc::downcast::<T>(scope.clone()).ok())
596    }
597
598    /// Copy the scope handles for an inline or tool dispatch.
599    pub fn scopes(&self) -> Vec<Arc<dyn std::any::Any + Send + Sync>> {
600        self.scopes.clone()
601    }
602
603    /// This dispatch observed by `recorder` under its id, as a recording
604    /// driver installs it after [`begin`](super::Recorder::begin): its
605    /// outcome, stream, origin and layer decisions, and the tool output its
606    /// handler publishes into a [`PublishedContext`](crate::tool::PublishedContext)
607    /// scope, whatever a layer's verdict. Add the scopes first. A handler
608    /// that serves the dispatch through an inner one, passing it on, is
609    /// recorded once it answered, with what it published by then; a
610    /// [`Layer`](super::Layer) hands the recorder to the handler it wraps.
611    pub fn recorded_by(mut self, recorder: Arc<dyn super::Recorder + Send + Sync>) -> Self {
612        let published = self.scope::<crate::tool::PublishedContext>();
613        self.observer = Some(Arc::new(Mutex::new(Some(Observed {
614            recorder,
615            id: self.id,
616            published,
617            streamed: false,
618            told: false,
619        }))));
620        self
621    }
622
623    pub(crate) fn patched(&mut self, kind: &EffectKind) {
624        if let Some(slot) = &self.observer
625            && let Some(seen) = lock(slot).as_mut()
626        {
627            seen.recorder.patch(seen.id, kind.clone());
628        }
629    }
630
631    /// A layer decided the dispatch before any handler saw it: the record
632    /// is dropped, since replay reruns the layers.
633    pub(crate) fn discard(&mut self) {
634        if let Some(slot) = &self.observer
635            && let Some(mut seen) = lock(slot).take()
636        {
637            seen.told = true;
638            seen.recorder.discard(seen.id);
639        }
640    }
641
642    pub(crate) fn inner(&mut self, folded: Option<Folded>) -> Self {
643        let observer = self.observer.as_ref().and_then(|slot| lock(slot).take());
644        Self {
645            id: self.id,
646            streaming: self.streaming,
647            scopes: self.scopes.clone(),
648            observer: observer.map(|seen| Arc::new(Mutex::new(Some(seen)))),
649            serving: Arc::default(),
650            folded,
651        }
652    }
653}
654
655/// The recorder of one dispatch, told its outcome once.
656struct Observed {
657    recorder: Arc<dyn super::Recorder + Send + Sync>,
658    id: EffectId,
659    published: Option<Arc<crate::tool::PublishedContext>>,
660    /// Whether an item streamed yet.
661    streamed: bool,
662    told: bool,
663}
664
665impl Observed {
666    /// The outcome, after the tool output the handler published, if any.
667    fn outcome(&mut self, outcome: Result<Answered, ErrorReport>) {
668        if std::mem::replace(&mut self.told, true) {
669            return;
670        }
671        if let Some(output) = self
672            .published
673            .as_ref()
674            .and_then(|published| published.result_context())
675        {
676            self.recorder.tool_output(self.id, output);
677        }
678        self.recorder.resolve(self.id, outcome);
679    }
680
681    fn item(
682        &mut self,
683        item: &Result<Relayed, ErrorReport>,
684        outcome: Option<Result<Answered, ErrorReport>>,
685    ) {
686        match item {
687            // Past the first, an item matters only to a recorder that keeps them.
688            Ok(Relayed::Item(item)) => {
689                if !std::mem::replace(&mut self.streamed, true) || self.recorder.keep_events() {
690                    self.recorder.event(self.id, item);
691                }
692            }
693            Ok(Relayed::Origin(origin)) if self.recorder.keep_events() => {
694                self.recorder.origin(self.id, origin);
695            }
696            Err(error) if self.recorder.keep_events() => self.recorder.stream_error(self.id, error),
697            _ => {}
698        }
699        if let Some(outcome) = outcome {
700            self.outcome(outcome);
701        }
702    }
703}
704
705impl Drop for Observed {
706    fn drop(&mut self) {
707        self.outcome(Err(cancelled()));
708    }
709}
710
711fn wrong_stream_answer(other: &Answered) -> ErrorReport {
712    ErrorReport::new(
713        ErrorKind::Internal,
714        format!(
715            "a streaming dispatch was answered with a {} outcome",
716            other.family()
717        ),
718    )
719}
720
721/// The consumer stopped listening before an answer was observed.
722pub fn cancelled() -> ErrorReport {
723    ErrorReport::new(
724        ErrorKind::Cancelled,
725        "the consumer cancelled the dispatch before it was answered",
726    )
727    .with_retryable(false)
728}
729
730/// The receiver of an external answer or writer has been dropped.
731#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
732#[error("the dispatch's consumer is gone")]
733pub struct SinkClosed;
734
735/// Serve an effect inline, using the same reply conversions as a driver.
736pub async fn serve_inline(
737    handler: &ErasedHandler,
738    kind: EffectKind,
739) -> Result<Answered, ErrorReport> {
740    serve_inline_with(handler, kind, Vec::new()).await
741}
742
743/// Serve inline with driver scopes, including tool context and publication.
744pub async fn serve_inline_with(
745    handler: &ErasedHandler,
746    kind: EffectKind,
747    scopes: Vec<Arc<dyn std::any::Any + Send + Sync>>,
748) -> Result<Answered, ErrorReport> {
749    let mut dispatch = Dispatch::new(EffectId::from_raw(0), false);
750    for scope in scopes {
751        dispatch = dispatch.with_scope(scope);
752    }
753    handler.handle(kind, dispatch).await.into_outcome().await
754}