Skip to main content

reef_core/runtime/
run.rs

1//! Public Run handle and the sole tracked runtime owner.
2
3use std::error::Error;
4use std::fmt;
5use std::sync::atomic::{AtomicUsize, Ordering};
6use std::sync::{Arc, Mutex};
7
8use tokio::sync::Notify;
9
10use super::agent::start::AdmittedStart;
11use super::agent::{AttachmentGuard, Revision};
12use super::driver;
13use super::event::{Event, EventSource, InputOrigin, Producer, StopCode, Stream, ValidationError};
14use super::hook::{
15    self, BufferedFact, CallbackResources, FactBuffer, LifecycleEnd, LifecycleObservation,
16};
17use super::model::Client;
18use super::session::{Lease, Session};
19use crate::audit;
20use crate::state::run_state::{self};
21use crate::state::session_state::{self};
22use crate::transcript::controller::TranscriptController;
23use crate::transcript::item::Item;
24use crate::value::lifecycle::{Coord, Outcome};
25use crate::value::tool_call::ToolCall;
26
27/// A cloneable handle to one admitted Run.
28///
29/// A Run exists only because [`Agent::start`](super::agent::Agent::start)
30/// admitted a Session, so by the time you hold one the input is already recorded
31/// and the loop is already running. There are exactly three things to do with
32/// it: take its [`take_events`](Run::take_events) once, ask it to stop, and wait for its
33/// [`Terminal`].
34///
35/// Every clone shares one Run. Dropping the last handle asks it to stop; it does
36/// not wait, and it does not abandon work already in flight.
37///
38/// ```
39/// # use std::future::{Future, ready};
40/// # use std::pin::Pin;
41/// # use std::sync::Arc;
42/// # use std::task::{Context, Poll};
43/// # use reef_core::futures_core::Stream;
44/// # use reef_core::runtime::model;
45/// # #[derive(Debug)] struct Offline;
46/// # #[derive(Debug)] struct Once(bool);
47/// # impl Stream for Once {
48/// #     type Item = Result<model::Event, std::convert::Infallible>;
49/// #     fn poll_next(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Option<Self::Item>> {
50/// #         if std::mem::replace(&mut self.0, true) { return Poll::Ready(None); }
51/// #         Poll::Ready(Some(Ok(model::Event::Done { finish_reason: "stop".to_owned(), completion: model::CompletionReason::Stop, provider_data: Vec::new() })))
52/// #     }
53/// # }
54/// # impl model::Client for Offline {
55/// #     type Error = std::convert::Infallible;
56/// #     type Stream = Once;
57/// #     fn info(&self) -> model::Info { model::Info::new("offline".to_owned(), 8_192) }
58/// #     fn generate(&self, _: model::Request) -> impl Future<Output = Result<Self::Stream, Self::Error>> + Send { ready(Ok(Once(false))) }
59/// # }
60/// use reef_core::cancel;
61/// use reef_core::runtime::{agent, hook, run, session, tool};
62/// use reef_core::value::{content, lifecycle};
63///
64/// # #[tokio::main(flavor = "current_thread")]
65/// # async fn main() {
66/// # let config = agent::Config::new(Arc::new(Offline), tool::RegistryBuilder::new().build().unwrap(), hook::RegistryBuilder::new());
67/// # let agent = agent::Agent::new(config).unwrap();
68/// let session = session::Session::new("conversation-1".to_owned(), None);
69/// let started = agent
70///     .start(session.clone(), vec![content::Part::text("Hi.".to_owned())], cancel::Token::new())
71///     .await
72///     .unwrap();
73///
74/// // Events are single-consumer: the second take fails, on this handle or any
75/// // clone of it.
76/// let mut events = started.take_events().unwrap();
77/// assert!(started.clone().take_events().is_err());
78/// while let Some(delivery) = events.recv().await {
79///     if delivery.decision_point().is_some() {
80///         delivery.accept().unwrap();
81///     }
82/// }
83///
84/// // Every waiter gets the same terminal, and waiting again is free.
85/// let terminal = started.wait().await;
86/// assert_eq!(terminal.outcome(), lifecycle::Outcome::Completed);
87/// assert_eq!(started.wait().await.outcome(), terminal.outcome());
88/// # }
89/// ```
90pub struct Run<M: Client> {
91    inner: Arc<RunInner<M>>,
92}
93
94impl<M: Client> fmt::Debug for Run<M> {
95    /// Locates the Run by session and revision, and counts live handles.
96    ///
97    /// There is no `M: Debug` bound: a Run would otherwise be unprintable for
98    /// every provider that has not opted in, and the model is not what
99    /// distinguishes one Run from another anyway. The three facts here are all
100    /// lock-free, so formatting a Run can never stall the Run.
101    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
102        formatter
103            .debug_struct("Run")
104            .field("session", &self.inner.session.id())
105            .field("revision", &self.inner.revision.id())
106            .field(
107                "handles",
108                &self.inner.public_handles.load(Ordering::Relaxed),
109            )
110            .finish()
111    }
112}
113
114impl<M: Client> Clone for Run<M> {
115    fn clone(&self) -> Self {
116        self.inner.public_handles.fetch_add(1, Ordering::Relaxed);
117        Self {
118            inner: Arc::clone(&self.inner),
119        }
120    }
121}
122
123impl<M: Client> Drop for Run<M> {
124    fn drop(&mut self) {
125        if self.inner.public_handles.fetch_sub(1, Ordering::AcqRel) == 1 {
126            self.inner.source.request_stop();
127        }
128    }
129}
130
131struct RunInner<M: Client> {
132    revision: Revision<M>,
133    session: Session,
134    source: Arc<EventSource>,
135    events: Mutex<Option<Stream>>,
136    terminal: Mutex<Option<Arc<Terminal>>>,
137    done: Notify,
138    public_handles: AtomicUsize,
139    task: Mutex<Option<tokio::task::JoinHandle<()>>>,
140}
141
142/// Linear owner of the post-admission cleanup chain.
143///
144/// Options make every step idempotent if an individual destructor itself unwinds.
145struct TaskCleanup<M: Client> {
146    inner: Arc<RunInner<M>>,
147    lease: Option<Lease>,
148    attachment: Option<AttachmentGuard<M>>,
149    producer: Option<Arc<Producer>>,
150    identity: Coord,
151    armed: bool,
152}
153
154impl<M: Client> TaskCleanup<M> {
155    const fn new(
156        inner: Arc<RunInner<M>>,
157        lease: Lease,
158        attachment: AttachmentGuard<M>,
159        producer: Arc<Producer>,
160        identity: Coord,
161    ) -> Self {
162        Self {
163            inner,
164            lease: Some(lease),
165            attachment: Some(attachment),
166            producer: Some(producer),
167            identity,
168            armed: true,
169        }
170    }
171
172    const fn lease(&self) -> &Lease {
173        self.lease
174            .as_ref()
175            .expect("the Run Lease remains owned until terminal cleanup")
176    }
177
178    const fn producer(&self) -> &Arc<Producer> {
179        self.producer
180            .as_ref()
181            .expect("the event Producer remains open through RunEnd")
182    }
183
184    fn cleanup(&mut self) {
185        // Cancellation is intentionally after terminal freeze on the normal path.
186        // EventSource owns the Run-local child token, so this does not cancel the
187        // caller's parent token.
188        self.inner.source.request_stop();
189        // Lease::drop performs the same idempotent synchronous release.
190        drop(self.lease.take());
191        drop(self.attachment.take());
192        drop(self.producer.take());
193        self.inner.close_events();
194    }
195
196    fn complete(mut self, terminal: Terminal) {
197        self.cleanup();
198        self.armed = false;
199        self.inner.publish(Arc::new(terminal));
200    }
201}
202
203impl<M: Client> Drop for TaskCleanup<M> {
204    fn drop(&mut self) {
205        if !self.armed {
206            return;
207        }
208        self.cleanup();
209        self.armed = false;
210        self.inner.publish(Arc::new(Terminal::failed(
211            self.identity.clone(),
212            FailureKind::Internal,
213            Arc::new(TaskPanickedError),
214        )));
215    }
216}
217
218impl<M: Client + 'static> Run<M> {
219    pub(crate) fn spawn(admitted: AdmittedStart<M>) -> Self {
220        // Parsed from the `AdmittedStart` owner produced and constructed by
221        // `runtime::agent::start`.
222        let AdmittedStart {
223            lease,
224            attachment,
225            revision,
226            session,
227            input,
228            admitted_items,
229            plan,
230            identity,
231            cancellation,
232            producer,
233            mut source,
234            hooks,
235            reservation_resources,
236            run_states,
237            session_state,
238            fact_buffer,
239        } = admitted;
240        let events = source
241            .take_stream()
242            .expect("a freshly admitted Run owns its event stream");
243        let source = Arc::new(source);
244        let inner = Arc::new(RunInner {
245            revision: revision.clone(),
246            session: session.clone(),
247            source: Arc::clone(&source),
248            events: Mutex::new(Some(events)),
249            terminal: Mutex::new(None),
250            done: Notify::new(),
251            public_handles: AtomicUsize::new(1),
252            task: Mutex::new(None),
253        });
254        let task_inner = Arc::clone(&inner);
255
256        let task = tokio::spawn(async move {
257            // Armed before any Driver/core polling. Its Drop is the synchronous
258            // panic fallback required by ADR-015:199-203; it deliberately does
259            // not invoke foreign callbacks while unwinding.
260            let cleanup = TaskCleanup::new(
261                Arc::clone(&task_inner),
262                lease,
263                attachment,
264                producer,
265                identity.clone(),
266            );
267            // The admitted input is already a transcript record (admission commits
268            // it in runtime/agent/start.rs), so it reaches the model the same way every
269            // other record does. `ephemeral` keeps its actual meaning: content
270            // that belongs to one request and to no history.
271            let lifecycle = LifecycleFanout {
272                hooks: &hooks,
273                run_states: &run_states,
274                identity: &identity,
275                session_state: &session_state,
276                session_state_writer: cleanup.lease().state(),
277                emitter: &fact_buffer,
278            };
279            lifecycle.observe(&LifecycleObservation::RunStart {
280                coord: identity.clone(),
281                input,
282            });
283
284            // Admission and `RunStart` both ran synchronous callbacks into the
285            // buffer, and no Producer existed then. Draining before Driver work
286            // preserves their producer FIFO; the loop then owns every drain in
287            // between, and the second drain below picks up `RunEnd`.
288            let report = driver::Report::default();
289            let admission_failure = publish_admission(
290                cleanup.producer(),
291                &fact_buffer,
292                &lifecycle,
293                &admitted_items,
294            )
295            .await
296            .err();
297            let driver_terminal = if let Some(error) = admission_failure {
298                driver::Terminal::Failed(driver::Error::Event(error))
299            } else {
300                let callback_resources = run_states
301                    .iter()
302                    .map(|run_state| {
303                        CallbackResources::new(
304                            &identity,
305                            run_state,
306                            &session_state,
307                            Some(cleanup.lease().state()),
308                            &fact_buffer,
309                        )
310                    })
311                    .collect::<Vec<_>>();
312                let controller = TranscriptController::new(
313                    cleanup.lease(),
314                    &hooks,
315                    &reservation_resources,
316                    &identity,
317                    &fact_buffer,
318                );
319                let gate = revision.tool_gate().cloned();
320                let mut binder =
321                    move |_call: &ToolCall| Ok::<_, driver::ToolBindingError>(gate.clone());
322                let tool_phase = driver::ToolPhase::new(
323                    driver::Outward::new(cleanup.producer(), &fact_buffer),
324                    &hooks,
325                    &callback_resources,
326                    &controller,
327                    &identity,
328                    Some(session.id().to_owned()),
329                    &mut binder,
330                );
331                let inbox = session.input_mailbox();
332                let engine = driver::Driver::new(
333                    revision.model().as_ref(),
334                    cleanup.lease(),
335                    &inbox,
336                    revision.tools(),
337                    &cancellation,
338                )
339                .with_tool_phase(tool_phase)
340                .with_turn_trigger(admitted_items)
341                .with_report(&report);
342                engine.run(plan, &source).await
343            };
344
345            // `Driver::run` is the sole inner join barrier.
346            // Construct one immutable pre-fan-out candidate and give that exact
347            // observation to every registration while the Lease remains held.
348            let stop_code = report.stop_code();
349            let candidate =
350                terminal_from_driver(&driver_terminal, identity.clone(), stop_code.clone());
351            let observation = LifecycleObservation::RunEnd {
352                coord: identity.clone(),
353                end: lifecycle_end(&candidate),
354                turns: report.turns(),
355            };
356            lifecycle.observe(&observation);
357            // RunEnd audits/panic facts append to the same FactBuffer, and the
358            // loop has already published everything queued before it. This is the
359            // last drain there is, so it is also what carries any fact the loop
360            // queued after its own final publication point.
361            let run_end_failure =
362                publish_buffered_facts(cleanup.producer(), &fact_buffer, Some(&lifecycle))
363                    .await
364                    .err();
365
366            // Re-observe only validated control/fatal state after peer fan-out.
367            // TerminalLatch preserves the first nonfatal and first fatal rules.
368            let mut terminal = driver::TerminalLatch::default();
369            terminal.record(driver_terminal);
370            if let Some(error) = run_end_failure {
371                terminal.record(driver::Terminal::Failed(driver::Error::Event(error)));
372            }
373            let terminal = terminal_from_driver(&terminal.finish(&source), identity, stop_code);
374
375            // Freeze is complete before cancellation. Cleanup then performs the
376            // exact cancel -> release -> detach -> event close -> publish order.
377            cleanup.complete(terminal);
378        });
379        *inner.task.lock().expect("Run task lock poisoned") = Some(task);
380
381        Self { inner }
382    }
383}
384
385impl<M: Client> Run<M> {
386    /// Returns the immutable Agent revision frozen for this Run.
387    #[must_use]
388    pub fn revision(&self) -> Revision<M> {
389        self.inner.revision.clone()
390    }
391
392    /// Returns the Session owned by this Run.
393    #[must_use]
394    pub fn session(&self) -> Session {
395        self.inner.session.clone()
396    }
397
398    /// Takes the unique outward event consumer.
399    ///
400    /// # Errors
401    ///
402    /// [`EventsTakenError`] if the [`Stream`] has already been taken — by an earlier
403    /// call, or through any other clone of this handle. Events are single-consumer,
404    /// so this is not contention that clears: the one consumer already exists, and
405    /// whoever holds it is the only party that can observe the Run's events.
406    ///
407    /// # Panics
408    ///
409    /// If the lock guarding the not-yet-taken [`Stream`] is poisoned, per the
410    /// crate-level [lock-poisoning contract](crate#lock-poisoning). It is held
411    /// only for the take itself, so nothing a caller or a hook does runs under
412    /// it.
413    pub fn take_events(&self) -> Result<Stream, EventsTakenError> {
414        self.inner
415            .events
416            .lock()
417            .expect("Run event lock poisoned")
418            .take()
419            .ok_or(EventsTakenError)
420    }
421
422    /// Requests a normal stop without waiting or spawning cleanup work.
423    ///
424    /// # Panics
425    ///
426    /// If an event-control lock is poisoned, per the crate-level
427    /// [lock-poisoning contract](crate#lock-poisoning).
428    pub fn request_stop(&self) {
429        self.inner.source.request_stop();
430    }
431
432    /// Requests a normal stop and waits for complete cleanup.
433    ///
434    /// # Panics
435    ///
436    /// If an event-control or Run terminal lock is poisoned, per the crate-level
437    /// [lock-poisoning contract](crate#lock-poisoning).
438    pub async fn stop(&self) -> Arc<Terminal> {
439        self.request_stop();
440        self.wait().await
441    }
442
443    /// Waits for the shared terminal without requesting a stop.
444    ///
445    /// Every waiter, on this handle or any clone, receives the same
446    /// [`Terminal`], and waiting again after it has resolved returns
447    /// immediately. If its [`outcome`](Terminal::outcome) is
448    /// [`Failed`](Outcome::Failed), read [`Terminal::failure_kind`] and
449    /// [`Terminal::failure`] rather than reporting the outcome alone.
450    ///
451    /// # Panics
452    ///
453    /// If the Run terminal lock is poisoned, per the crate-level
454    /// [lock-poisoning contract](crate#lock-poisoning).
455    pub async fn wait(&self) -> Arc<Terminal> {
456        loop {
457            let notified = self.inner.done.notified();
458            tokio::pin!(notified);
459            notified.as_mut().enable();
460            if let Some(terminal) = self.inner.terminal() {
461                return terminal;
462            }
463            notified.await;
464        }
465    }
466
467    /// Abandons an untaken event consumer, requests stop, and waits for cleanup.
468    ///
469    /// # Panics
470    ///
471    /// If a Run or event-control lock is poisoned, per the crate-level
472    /// [lock-poisoning contract](crate#lock-poisoning).
473    pub async fn close(&self) -> Arc<Terminal> {
474        self.inner.close_events();
475        self.stop().await
476    }
477
478    #[cfg(test)]
479    pub(super) fn terminal_ready(&self) -> bool {
480        self.inner.terminal().is_some()
481    }
482
483    #[cfg(test)]
484    pub(super) async fn join_tracked_task(&self) -> Result<(), tokio::task::JoinError> {
485        let task = self
486            .inner
487            .task
488            .lock()
489            .expect("Run task lock poisoned")
490            .take()
491            .expect("the sole tracked Run task is joined at most once");
492        task.await
493    }
494}
495
496impl<M: Client> RunInner<M> {
497    fn close_events(&self) {
498        drop(self.events.lock().expect("Run event lock poisoned").take());
499    }
500
501    fn terminal(&self) -> Option<Arc<Terminal>> {
502        self.terminal
503            .lock()
504            .expect("Run terminal lock poisoned")
505            .clone()
506    }
507
508    fn publish(&self, terminal: Arc<Terminal>) {
509        let mut slot = self.terminal.lock().expect("Run terminal lock poisoned");
510        debug_assert!(slot.is_none(), "the sole Run task publishes once");
511        *slot = Some(terminal);
512        drop(slot);
513        self.done.notify_waiters();
514    }
515}
516
517/// The Run-scoped half of the observer lifecycle fan-out.
518///
519/// The driver owns every Turn/Step/Generation/ToolCall observation because it
520/// owns those boundaries; `RunStart` and `RunEnd` are the two the Run task owns,
521/// and both need the same borrowed resource set. Binding it once keeps the two
522/// fan-outs from drifting apart.
523pub(super) struct LifecycleFanout<'a> {
524    hooks: &'a hook::Registry,
525    run_states: &'a [run_state::Store],
526    identity: &'a Coord,
527    session_state: &'a session_state::Reader,
528    session_state_writer: &'a session_state::Writer,
529    emitter: &'a FactBuffer,
530}
531
532impl LifecycleFanout<'_> {
533    fn observe_audit(&self, event: &audit::Event) {
534        for adapter in self.hooks.observer_hooks() {
535            let run_state = self
536                .run_states
537                .get(adapter.index())
538                .expect("Run resources cover every hook registration");
539            let resources = CallbackResources::new(
540                self.identity,
541                run_state,
542                self.session_state,
543                Some(self.session_state_writer),
544                self.emitter,
545            );
546            adapter.invoke_audit_event(resources, event);
547        }
548    }
549
550    fn observe(&self, observation: &LifecycleObservation) {
551        for adapter in self.hooks.observer_hooks() {
552            let run_state = self
553                .run_states
554                .get(adapter.index())
555                .expect("Run resources cover every hook registration");
556            let resources = CallbackResources::new(
557                self.identity,
558                run_state,
559                self.session_state,
560                Some(self.session_state_writer),
561                self.emitter,
562            );
563            adapter.invoke_lifecycle(resources, None, observation);
564        }
565    }
566}
567
568/// Publishes everything admission produced, before the loop publishes anything.
569///
570/// Two facts, in the order they became true. The queued callback facts come from
571/// [`RunHooks::prepare`](super::hook::RunHooks::prepare) and
572/// [`ObserverHooks::run_admitted`](super::hook::ObserverHooks::run_admitted), which ran with no Producer in existence;
573/// the admitted record then opens the Run's first Turn, and it is announced here
574/// for the same reason every later batch is announced in the loop — a consumer
575/// rebuilding history from this stream must not have to guess the first turn's
576/// input, which `prepare` may have rewritten before it was recorded.
577///
578/// Nothing is published when admission recorded nothing, which happens when the
579/// caller submitted no parts and no registration composed any.
580async fn publish_admission(
581    producer: &Producer,
582    buffer: &FactBuffer,
583    lifecycle: &LifecycleFanout<'_>,
584    admitted: &[Item],
585) -> Result<(), ValidationError> {
586    publish_buffered_facts(producer, buffer, Some(lifecycle)).await?;
587    if admitted.is_empty() {
588        return Ok(());
589    }
590    producer
591        .emit_input_admitted(
592            InputOrigin::Start,
593            admitted.to_vec(),
594            lifecycle.identity.clone(),
595        )
596        .await?;
597    Ok(())
598}
599
600/// Publishes the Run-owner half of the buffered-fact drain.
601///
602/// The loop owns the drains taken between `RunStart` and `RunEnd`; this one
603/// covers the two edges the loop cannot reach, where the only coordinate that
604/// applies is the Run itself and so no event carries one.
605pub(super) async fn publish_buffered_facts(
606    producer: &Producer,
607    buffer: &FactBuffer,
608    observers: Option<&LifecycleFanout<'_>>,
609) -> Result<(), ValidationError> {
610    for fact in buffer.take_facts() {
611        let event = match fact {
612            BufferedFact::Audit(audit) => {
613                // `OnAuditEvent` observes the fact before it is published, so an
614                // observer and the outward consumer see the same value and the
615                // observer cannot answer an event the consumer already saw.
616                if let Some(observers) = observers {
617                    observers.observe_audit(&audit);
618                }
619                Event::from_audit(audit)?
620            }
621            BufferedFact::Error(error) => Event::from_error(error),
622        };
623        producer
624            .emit(event, None)
625            .await
626            .expect("a successfully constructed ordinary fact remains valid");
627    }
628    Ok(())
629}
630
631fn terminal_from_driver(
632    terminal: &driver::Terminal,
633    coord: Coord,
634    stop_code: Option<StopCode>,
635) -> Terminal {
636    match terminal {
637        driver::Terminal::Completed => Terminal::new(Outcome::Completed, coord, None),
638        // Only a `RunHooks::decide_stop` stop carries a code; a consumer-requested stop
639        // has nothing to name itself with.
640        driver::Terminal::Stopped => Terminal::new(Outcome::Stopped, coord, stop_code),
641        driver::Terminal::Cancelled => Terminal::new(Outcome::Cancelled, coord, None),
642        driver::Terminal::Failed(error) => {
643            let failure = DriverError::from_loop(error);
644            Terminal::failed(coord, failure.kind, Arc::new(failure))
645        }
646    }
647}
648
649fn lifecycle_end(terminal: &Terminal) -> LifecycleEnd {
650    match terminal.outcome {
651        Outcome::Completed => LifecycleEnd::Completed,
652        Outcome::Stopped => LifecycleEnd::Stopped {
653            code: terminal.stop_code.clone(),
654        },
655        Outcome::Cancelled => LifecycleEnd::Cancelled {
656            error: Arc::new(CanceledError),
657        },
658        Outcome::Failed => LifecycleEnd::Failed {
659            error: terminal
660                .failure
661                .as_ref()
662                .expect("a failed terminal always retains failure detail")
663                .clone(),
664        },
665    }
666}
667
668/// Immutable terminal fact shared by every waiter.
669///
670/// [`outcome`](Terminal::outcome) is four words wide, so on its own it does not
671/// say much: **if it is [`Outcome::Failed`], the reason is one call away.**
672/// [`failure_kind`](Terminal::failure_kind) is the matchable classification and
673/// [`failure`](Terminal::failure) is the error itself, whose
674/// [`source`](Error::source) chain reaches the concrete provider or hook error
675/// underneath.
676///
677/// ```
678/// # use reef_core::runtime::run;
679/// # use reef_core::value::lifecycle;
680/// # fn report(terminal: &run::Terminal) -> String {
681/// if terminal.outcome() == lifecycle::Outcome::Failed {
682///     // Never report `Failed` on its own: these two say what happened.
683///     format!(
684///         "failed ({:?}): {}",
685///         terminal.failure_kind(),
686///         terminal.failure().map_or_else(|| "no detail".to_owned(), ToString::to_string),
687///     )
688/// } else {
689///     format!("{:?}", terminal.outcome())
690/// }
691/// # }
692/// ```
693pub struct Terminal {
694    outcome: Outcome,
695    coord: Coord,
696    stop_code: Option<StopCode>,
697    failure: Option<Arc<dyn Error + Send + Sync>>,
698    failure_kind: Option<FailureKind>,
699}
700
701impl fmt::Debug for Terminal {
702    /// States how the Run ended, rendering the failure through `Display`.
703    ///
704    /// The failure is an arbitrary third-party error whose `Debug` this crate
705    /// neither writes nor reviews; `Display` is the operator diagnostic the type
706    /// is contracted to produce, so that is what a terminal reports.
707    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
708        formatter
709            .debug_struct("Terminal")
710            .field("outcome", &self.outcome)
711            .field("coord", &self.coord)
712            .field("stop_code", &self.stop_code)
713            .field(
714                "failure",
715                &self.failure.as_ref().map(|failure| failure.to_string()),
716            )
717            .field("failure_kind", &self.failure_kind)
718            .finish()
719    }
720}
721
722impl Terminal {
723    fn new(outcome: Outcome, coord: Coord, stop_code: Option<StopCode>) -> Self {
724        Self {
725            outcome,
726            coord,
727            stop_code,
728            failure: None,
729            failure_kind: None,
730        }
731    }
732
733    fn failed(coord: Coord, kind: FailureKind, failure: Arc<dyn Error + Send + Sync>) -> Self {
734        Self {
735            outcome: Outcome::Failed,
736            coord,
737            stop_code: None,
738            failure: Some(failure),
739            failure_kind: Some(kind),
740        }
741    }
742
743    /// Returns the authoritative portable outcome.
744    #[must_use]
745    pub const fn outcome(&self) -> Outcome {
746        self.outcome
747    }
748
749    /// Returns the Run coordinate.
750    #[must_use]
751    pub const fn coord(&self) -> &Coord {
752        &self.coord
753    }
754
755    /// Returns an explicit hook stop code when one ended the Run.
756    #[must_use]
757    pub const fn stop_code(&self) -> Option<&StopCode> {
758        self.stop_code.as_ref()
759    }
760
761    /// Returns execution failure detail for a failed Run.
762    ///
763    /// `Some` exactly when [`outcome`](Self::outcome) is
764    /// [`Failed`](Outcome::Failed). Its [`Display`](fmt::Display) is already the
765    /// complete rendered reason, stage and payload together — reef renders each
766    /// failure where it is latched, because the crate-private stage error cannot
767    /// outlive the Run and a classification alone does not diagnose anything.
768    /// [`source`](Error::source) is therefore for *inspecting* the failure rather
769    /// than for re-rendering it: a provider error downcasts back to the
770    /// consumer's own type there. A chain walk that concatenates every link will
771    /// see the tail of the first message repeated, which is why this is worth
772    /// stating.
773    #[must_use]
774    pub fn failure(&self) -> Option<&(dyn Error + Send + Sync + 'static)> {
775        self.failure.as_deref()
776    }
777
778    /// Returns the portable classification of a failed Run.
779    #[must_use]
780    pub const fn failure_kind(&self) -> Option<FailureKind> {
781        self.failure_kind
782    }
783}
784
785/// The unique event consumer was already taken or abandoned.
786#[derive(Clone, Copy, Debug, Eq, PartialEq)]
787pub struct EventsTakenError;
788
789impl fmt::Display for EventsTakenError {
790    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
791        formatter.write_str("Run events were already consumed")
792    }
793}
794
795impl Error for EventsTakenError {}
796
797/// A Run task panic classification reserved for the task-owned unwind boundary.
798#[derive(Clone, Copy, Debug, Eq, PartialEq)]
799pub struct TaskPanickedError;
800
801impl fmt::Display for TaskPanickedError {
802    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
803        formatter.write_str("Run task panicked")
804    }
805}
806
807impl Error for TaskPanickedError {}
808
809#[derive(Debug)]
810struct CanceledError;
811
812impl fmt::Display for CanceledError {
813    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
814        formatter.write_str("Run canceled")
815    }
816}
817
818impl Error for CanceledError {}
819
820/// The portable classification of a failed Run.
821///
822/// A Run can fail for reasons that call for very different handling — a
823/// provider outage, a malformed provider stream, a hook defect, a transcript
824/// conflict — and the concrete failure types belong to crate-private stages that
825/// a consumer could not downcast to even if they were exposed. This enum is the
826/// stable, matchable summary; [`Terminal::failure`] carries the exact text.
827#[derive(Clone, Copy, Debug, Eq, PartialEq)]
828#[non_exhaustive]
829pub enum FailureKind {
830    /// A transcript snapshot or mutation failed.
831    Transcript,
832    /// Resolving the Step's tools failed, usually a name collision.
833    ToolResolution,
834    /// The transcript could not be frozen into a valid model request.
835    Request,
836    /// The provider adapter itself failed.
837    Model,
838    /// The provider's normalized event stream violated the grammar.
839    Stream,
840    /// An outward event could not be constructed or delivered.
841    Event,
842    /// A hook callback failed.
843    Hook,
844    /// Routing or executing a tool batch failed.
845    ToolExecution,
846    /// Committing a tool batch failed.
847    ToolCommit,
848    /// A claimed input batch produced an invalid admission decision.
849    Input,
850    /// A runtime invariant produced a failure with no external cause.
851    ///
852    /// This is a defect in Reef, not in the caller or the provider.
853    Internal,
854}
855
856/// The retained reason a Run driver failed.
857///
858/// The message is rendered from the concrete stage failure at the moment it is
859/// latched, because the crate-private staged error itself is not `Clone` and
860/// cannot outlive the driver. Rendering eagerly keeps the whole reason — stage,
861/// payload, and any hook attribution — instead of the classification alone.
862///
863/// `cause` keeps the same failure as a *value*. Reading a message is enough to
864/// diagnose a Run; deciding what to do about one is not, so the concrete stage
865/// failure is retained and returned from [`Error::source`]. A provider error is
866/// the consumer's own type, so `source()` is downcastable back to it.
867#[derive(Debug)]
868struct DriverError {
869    kind: FailureKind,
870    message: String,
871    cause: Option<Arc<dyn Error + Send + Sync>>,
872}
873
874impl DriverError {
875    fn from_loop(error: &driver::Error) -> Self {
876        Self {
877            kind: error.classify(),
878            message: error.to_string(),
879            cause: error.cause(),
880        }
881    }
882}
883
884impl fmt::Display for DriverError {
885    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
886        formatter.write_str(&self.message)
887    }
888}
889
890impl Error for DriverError {
891    fn source(&self) -> Option<&(dyn Error + 'static)> {
892        self.cause
893            .as_ref()
894            .map(|cause| cause.as_ref() as &(dyn Error + 'static))
895    }
896}