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}