Skip to main content

reef_core/runtime/
agent.rs

1//! Immutable Agent configuration and linearizable teardown ownership.
2
3mod config;
4mod error;
5pub(crate) mod start;
6
7pub use config::{Config, Revision};
8pub use error::{CloseError, ClosePanickedError, ConfigError, StartError, TeardownError};
9#[cfg(not(test))]
10#[expect(
11    unused_imports,
12    reason = "admission freezes the linear owner that the Run module will consume"
13)]
14pub(crate) use start::AdmittedStart;
15#[cfg(test)]
16pub(crate) use start::AdmittedStart;
17
18use std::num::NonZeroU64;
19use std::sync::atomic::{AtomicU64, Ordering};
20use std::sync::{Arc, Mutex};
21
22use crate::cancel::Token;
23#[cfg(test)]
24use crate::transcript::store;
25#[cfg(test)]
26use std::collections::VecDeque;
27#[cfg(test)]
28use std::sync::Barrier;
29#[cfg(test)]
30use std::sync::atomic::AtomicUsize;
31use tokio::sync::Notify;
32
33use crate::runtime::event::Stream;
34use crate::runtime::hook;
35use crate::runtime::model::{Client, RequestPlan};
36use crate::runtime::run::Run;
37use crate::runtime::session::Session;
38use crate::value::content::Part;
39
40static NEXT_REVISION_ID: AtomicU64 = AtomicU64::new(1);
41
42/// Cloneable handle to one immutable revision and its private teardown authority.
43///
44/// An Agent is configuration that has been frozen: [`Agent::new`] consumes a
45/// [`Config`] and produces a [`Revision`] that never changes again. Starting a
46/// Run against a different model, tool roster or hook roster means building a
47/// second Agent — see [`Revision`] for the exact extent of that rule and for
48/// what it deliberately leaves free.
49///
50/// It is `Clone`, and every clone shares one teardown authority: whichever one
51/// calls [`close`](Agent::close) first runs each hook's `OnClose` exactly once
52/// and every other caller receives that same cached result.
53///
54/// ```
55/// # use std::future::{Future, ready};
56/// # use std::pin::Pin;
57/// # use std::sync::Arc;
58/// # use std::task::{Context, Poll};
59/// # use reef_core::futures_core::Stream;
60/// # use reef_core::runtime::model;
61/// # #[derive(Debug)] struct Offline;
62/// # #[derive(Debug)] struct Once(bool);
63/// # impl Stream for Once {
64/// #     type Item = Result<model::Event, std::convert::Infallible>;
65/// #     fn poll_next(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Option<Self::Item>> {
66/// #         if std::mem::replace(&mut self.0, true) { return Poll::Ready(None); }
67/// #         Poll::Ready(Some(Ok(model::Event::Done { finish_reason: "stop".to_owned(), completion: model::CompletionReason::Stop, provider_data: Vec::new() })))
68/// #     }
69/// # }
70/// # impl model::Client for Offline {
71/// #     type Error = std::convert::Infallible;
72/// #     type Stream = Once;
73/// #     fn info(&self) -> model::Info { model::Info::new("offline".to_owned(), 8_192) }
74/// #     fn generate(&self, _: model::Request) -> impl Future<Output = Result<Self::Stream, Self::Error>> + Send { ready(Ok(Once(false))) }
75/// # }
76/// use reef_core::cancel;
77/// use reef_core::runtime::{agent, hook, session, tool};
78/// use reef_core::value::{content, lifecycle};
79///
80/// # #[tokio::main(flavor = "current_thread")]
81/// # async fn main() {
82/// let config = agent::Config::new(
83///     Arc::new(Offline),
84///     tool::RegistryBuilder::new().build().unwrap(),
85///     hook::RegistryBuilder::new(),
86/// );
87/// let agent = agent::Agent::new(config).unwrap();
88///
89/// let session = session::Session::new("conversation-1".to_owned(), None);
90/// let (run, mut events) = agent
91///     .start_observed(session, vec![content::Part::text("Hi.".to_owned())], cancel::Token::new())
92///     .await
93///     .unwrap();
94/// assert_eq!(run.revision().id(), agent.revision().id());
95///
96/// while events.recv().await.is_some() {}
97/// let terminal = run.wait().await;
98/// assert_eq!(terminal.outcome(), lifecycle::Outcome::Completed);
99///
100/// // Closing is refused while a Run is attached, and is exactly once after.
101/// agent.close().await.unwrap();
102/// assert!(agent.close().await.is_ok());
103/// # }
104/// ```
105pub struct Agent<M: Client> {
106    inner: Arc<AgentInner<M>>,
107}
108
109impl<M: Client> std::fmt::Debug for Agent<M> {
110    /// Identifies the agent by the revision every Run of it will freeze.
111    ///
112    /// The phase behind the state mutex is deliberately not read: an agent's
113    /// phase changes under the reader, and a formatter that took that lock
114    /// could block inside teardown, which is the one moment it is most likely
115    /// to be called from.
116    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
117        formatter
118            .debug_struct("Agent")
119            .field("revision", &self.inner.revision.id())
120            .finish()
121    }
122}
123
124impl<M: Client> Clone for Agent<M> {
125    fn clone(&self) -> Self {
126        Self {
127            inner: Arc::clone(&self.inner),
128        }
129    }
130}
131
132struct AgentInner<M: Client> {
133    revision: Revision<M>,
134    hooks: hook::RuntimeRegistry,
135    state: Mutex<AgentState>,
136    closed: Notify,
137    #[cfg(test)]
138    close_wait_probe: Mutex<Arc<CloseWaitProbe>>,
139    #[cfg(test)]
140    start_snapshot_results: Mutex<VecDeque<Option<store::Error>>>,
141}
142
143#[cfg(test)]
144pub(crate) struct CloseWaitProbe {
145    waiters: usize,
146    observations: AtomicUsize,
147    observed_closing: Barrier,
148    resume: Barrier,
149    rechecked_closing: Barrier,
150}
151
152#[cfg(test)]
153impl CloseWaitProbe {
154    fn new(waiters: usize) -> Self {
155        Self {
156            waiters,
157            observations: AtomicUsize::new(0),
158            observed_closing: Barrier::new(waiters + 1),
159            resume: Barrier::new(waiters + 1),
160            rechecked_closing: Barrier::new(waiters + 1),
161        }
162    }
163
164    fn pause_before_await(&self) {
165        if self.observations.fetch_add(1, Ordering::SeqCst) < self.waiters {
166            self.observed_closing.wait();
167            self.resume.wait();
168        } else {
169            self.rechecked_closing.wait();
170        }
171    }
172
173    pub(crate) fn wait_until_closing_observed(&self) {
174        self.observed_closing.wait();
175    }
176
177    pub(crate) fn notify_waiters_one_by_one<M: Client>(&self, agent: &Agent<M>) {
178        for _ in 0..self.waiters {
179            agent.inner.closed.notify_one();
180        }
181    }
182
183    pub(crate) fn resume_waiters(&self) {
184        self.resume.wait();
185    }
186
187    pub(crate) fn wait_until_closing_rechecked(&self) {
188        self.rechecked_closing.wait();
189    }
190}
191
192struct AgentState {
193    phase: AgentPhase,
194    active_runs: usize,
195}
196
197enum AgentPhase {
198    Open,
199    Closing,
200    Closed(Result<(), CloseError>),
201}
202
203enum CloseDecision {
204    Winner,
205    Wait,
206    Cached(Result<(), CloseError>),
207}
208
209impl<M: Client + 'static> Agent<M> {
210    /// Consumes configuration, validates defaults, and freezes a fresh revision.
211    ///
212    /// # Errors
213    ///
214    /// - [`ConfigError::Hooks`] if the hook roster does not build: an unnamed
215    ///   or duplicated registration, as [`hook::RegistryError`] describes.
216    /// - [`ConfigError::InvalidDefaults`] if the default request material is not a
217    ///   valid request. The defaults are frozen through the real request boundary
218    ///   against an empty history, so an unusable system instruction is reported
219    ///   here rather than at the first Step of every Run this Agent would start.
220    /// - [`ConfigError::RevisionIdExhausted`] if the process-wide revision identity
221    ///   space is used up. Identities are nonzero and monotonic for the life of the
222    ///   process and are never reused, so this is reachable only after more than
223    ///   `u64::MAX` revisions.
224    ///
225    /// Configuration is consumed either way. A rejected configuration cannot be
226    /// corrected and retried; rebuild it.
227    pub fn new(config: Config<M>) -> Result<Self, ConfigError> {
228        Self::new_with_counter(config, &NEXT_REVISION_ID)
229    }
230
231    /// Admits one Session use, spawns its sole Run task, and returns its public handle.
232    ///
233    /// This compatibility entry point leaves the unique event stream on the Run for
234    /// [`Run::take_events`](crate::runtime::run::Run::take_events). If outward events
235    /// are required, prefer [`Agent::start_observed`], which transfers that stream
236    /// before the task can run and therefore has no start-then-take race.
237    ///
238    /// Both halves are synchronous: ADR-015 makes admission a straight-line
239    /// sequence that never yields, and spawning the Run task returns as soon as
240    /// the task is queued. `async` here is the caller-facing contract rather
241    /// than an implementation fact — it states that a Tokio runtime must be
242    /// live, which is what makes the spawn legal, and it keeps the facade's
243    /// three lifecycle entries the same shape.
244    ///
245    /// # Errors
246    ///
247    /// Every variant here is **pre-admission**: a `StartError` means no Run exists,
248    /// the Session lease and Agent attachment have been rolled back, and the
249    /// transcript is as it was. Once admission completes, failure is reported by the
250    /// returned Run's terminal instead.
251    ///
252    /// - [`StartError::AgentClosed`] if [`Agent::close`] already won. Checked before
253    ///   the Session is touched, so a closed Agent cannot disturb one.
254    /// - [`StartError::SessionBusy`] if the Session already has an active lease.
255    ///   Retryable once that Run has fully exited; this is the one-active-Run rule,
256    ///   not a transient lock.
257    /// - [`StartError::Cancelled`] if `cancellation` was already observable, or
258    ///   became so, before the last pre-admission commit. A cancellation that first
259    ///   becomes visible at or after that commit yields an admitted Run whose
260    ///   terminal is canceled instead — so a caller racing cancellation against
261    ///   start must handle both.
262    /// - [`StartError::Admission`] if a lease-bound admission or prepare
263    ///   transaction is rejected, carrying the
264    ///   [`LeaseError`](crate::runtime::session::LeaseError).
265    /// - [`StartError::Prepare`] if a [`RunHooks::prepare`](super::hook::RunHooks::prepare)
266    ///   registration or a transcript reservation failed, naming the registration.
267    /// - [`StartError::Transcript`] if recording the admitted input failed, carrying
268    ///   the [`store::Error`](crate::transcript::store::Error).
269    /// - [`StartError::InvalidIdentity`] if the Session or Run identity is not a
270    ///   valid coordinate, and [`StartError::RunIdExhausted`] if the process-wide Run
271    ///   identity space is used up.
272    ///
273    /// # Panics
274    ///
275    /// If no Tokio runtime is active to spawn the Run task, or if the Agent state,
276    /// Session, mailbox, event-control, or hook-fact lock is poisoned, per the
277    /// crate-level [lock-poisoning contract](crate#lock-poisoning).
278    #[expect(
279        clippy::unused_async,
280        reason = "ADR-015 keeps the public facade awaited; admission itself never yields"
281    )]
282    pub async fn start(
283        &self,
284        session: Session,
285        input: Vec<Part>,
286        cancellation: Token,
287    ) -> Result<Run<M>, StartError> {
288        let admitted = self.admit_start(session, input, cancellation)?;
289        Ok(Run::spawn(admitted))
290    }
291
292    /// Admits one Session use and atomically returns its Run and outward event stream.
293    ///
294    /// This has the same admission, execution, and failure semantics as [`Agent::start`],
295    /// but transfers the unique [`Stream`] to the caller before the Run task is spawned.
296    /// Use this entry point when outward observation is required: even if the Run finishes
297    /// before the caller is scheduled again, terminal cleanup cannot discard the returned
298    /// stream or its queued events.
299    ///
300    /// The paired Run has no stream left to take, so
301    /// [`Run::take_events`](crate::runtime::run::Run::take_events) returns
302    /// [`EventsTakenError`](crate::runtime::run::EventsTakenError). Holding the returned
303    /// stream without polling it retains queued ordinary events and leaves strong
304    /// deliveries waiting for their existing accept-or-reject decision.
305    ///
306    /// # Errors
307    ///
308    /// Returns the same pre-admission [`StartError`] variants as [`Agent::start`]. No Run
309    /// or stream is returned on error.
310    ///
311    /// # Panics
312    ///
313    /// Under the same conditions as [`Agent::start`], including when no Tokio runtime is
314    /// active to spawn the Run task.
315    #[expect(
316        clippy::unused_async,
317        reason = "ADR-015 keeps the public facade awaited; admission itself never yields"
318    )]
319    pub async fn start_observed(
320        &self,
321        session: Session,
322        input: Vec<Part>,
323        cancellation: Token,
324    ) -> Result<(Run<M>, Stream), StartError> {
325        let admitted = self.admit_start(session, input, cancellation)?;
326        Ok(Run::spawn_observed(admitted))
327    }
328
329    pub(crate) fn new_with_counter(
330        config: Config<M>,
331        revision_ids: &AtomicU64,
332    ) -> Result<Self, ConfigError> {
333        let Config {
334            model,
335            tools,
336            hooks,
337            system_instruction,
338            sampling,
339            model_extensions,
340        } = config;
341        // Only Agent construction consumes the public hook roster into the
342        // teardown-bearing crate-private runtime registry.
343        let hooks = hooks.build_runtime().map_err(ConfigError::Hooks)?;
344
345        // Validate through the real `RequestPlan::try_into_request` producer.
346        let mut defaults = RequestPlan::new();
347        defaults
348            .extend_system_instruction(system_instruction.iter().cloned())
349            .extend_extensions(model_extensions.iter().cloned());
350        *defaults.sampling_mut() = sampling.clone();
351        defaults
352            .try_into_request(Vec::new())
353            .map_err(ConfigError::InvalidDefaults)?;
354
355        let id = allocate_revision_id(revision_ids)?;
356        let revision = Revision {
357            id,
358            model,
359            tools,
360            hook_names: hooks.names().map(str::to_owned).collect(),
361            hooks_require_session_state: hooks.requires_session_state(),
362            system_instruction: system_instruction.into(),
363            sampling,
364            model_extensions: model_extensions.into(),
365        };
366        Ok(Self {
367            inner: Arc::new(AgentInner {
368                revision,
369                hooks,
370                state: Mutex::new(AgentState {
371                    phase: AgentPhase::Open,
372                    active_runs: 0,
373                }),
374                closed: Notify::new(),
375                #[cfg(test)]
376                close_wait_probe: Mutex::new(Arc::new(CloseWaitProbe::new(0))),
377                #[cfg(test)]
378                start_snapshot_results: Mutex::new(VecDeque::new()),
379            }),
380        })
381    }
382
383    /// Returns an owned immutable revision handle without teardown authority.
384    #[must_use]
385    pub fn revision(&self) -> Revision<M> {
386        self.inner.revision.clone()
387    }
388
389    /// Closes an idle Agent exactly once, or reports an exact retryable busy count.
390    ///
391    /// # Errors
392    ///
393    /// - [`CloseError::Busy`], carrying the exact number of attachments observed at
394    ///   the linearization point, if any Run still owns this Agent. This is the
395    ///   retryable one, and it is deliberately inert: admission is not sealed and no
396    ///   teardown callback runs, so a busy close changes nothing and can be repeated
397    ///   after stopping or awaiting the Runs it counted.
398    /// - [`CloseError::Hooks`] if teardown ran and some callbacks failed or panicked.
399    ///   Every registration's `OnClose` ran regardless, in registration order, and
400    ///   [`TeardownError::entries`] lists each failure with its hook's name. To keep
401    ///   that guarantee even for a legal panic payload whose destructor also panics,
402    ///   each captured panic payload is deliberately forgotten. This leaks one
403    ///   payload value per panicking callback, on this pathological path only.
404    ///
405    /// The second is final rather than retryable: the Agent is closed, the result is
406    /// cached, and a later or concurrent close returns this same value without
407    /// invoking teardown again.
408    ///
409    /// # Panics
410    ///
411    /// If the Agent phase lock is poisoned, per the crate-level
412    /// [lock-poisoning contract](crate#lock-poisoning). That lock is the one
413    /// place `Open`, `Closing`, and `Closed` linearize, so a poisoned one means
414    /// the Agent's close authority is no longer trustworthy; a teardown callback
415    /// cannot cause it, because a panicking `OnClose` is caught at its own
416    /// boundary and reported as [`CloseError::Hooks`] instead.
417    pub async fn close(&self) -> Result<(), CloseError> {
418        loop {
419            let notified = self.inner.closed.notified();
420            tokio::pin!(notified);
421            notified.as_mut().enable();
422            match self.close_decision()? {
423                CloseDecision::Winner => break,
424                CloseDecision::Wait => notified.await,
425                CloseDecision::Cached(result) => return result,
426            }
427        }
428
429        let failures = self.inner.hooks.close();
430        let result = if failures.is_empty() {
431            Ok(())
432        } else {
433            Err(CloseError::Hooks(TeardownError(failures.into())))
434        };
435        let mut state = self.inner.state.lock().expect("Agent state lock poisoned");
436        state.phase = AgentPhase::Closed(result.clone());
437        drop(state);
438        self.inner.closed.notify_waiters();
439        result
440    }
441
442    fn close_decision(&self) -> Result<CloseDecision, CloseError> {
443        let decision = {
444            let mut state = self.inner.state.lock().expect("Agent state lock poisoned");
445            match &state.phase {
446                AgentPhase::Open if state.active_runs != 0 => {
447                    return Err(CloseError::Busy {
448                        active_runs: state.active_runs,
449                    });
450                }
451                AgentPhase::Open => {
452                    state.phase = AgentPhase::Closing;
453                    CloseDecision::Winner
454                }
455                AgentPhase::Closing => CloseDecision::Wait,
456                AgentPhase::Closed(result) => CloseDecision::Cached(result.clone()),
457            }
458        };
459        #[cfg(test)]
460        if matches!(&decision, CloseDecision::Wait) {
461            self.pause_close_waiter_before_await();
462        }
463        Ok(decision)
464    }
465
466    #[cfg(test)]
467    pub(crate) fn install_close_wait_probe(&self, waiters: usize) -> Arc<CloseWaitProbe> {
468        let probe = Arc::new(CloseWaitProbe::new(waiters));
469        *self
470            .inner
471            .close_wait_probe
472            .lock()
473            .expect("close wait probe lock poisoned") = Arc::clone(&probe);
474        probe
475    }
476
477    #[cfg(test)]
478    fn pause_close_waiter_before_await(&self) {
479        let probe = self
480            .inner
481            .close_wait_probe
482            .lock()
483            .expect("close wait probe lock poisoned")
484            .clone();
485        probe.pause_before_await();
486    }
487
488    pub(crate) fn reserve_attachment(&self) -> Result<AttachmentGuard<M>, StartError> {
489        let mut state = self.inner.state.lock().expect("Agent state lock poisoned");
490        match state.phase {
491            AgentPhase::Open => {
492                state.active_runs += 1;
493                Ok(AttachmentGuard {
494                    inner: Arc::clone(&self.inner),
495                })
496            }
497            AgentPhase::Closing | AgentPhase::Closed(_) => Err(StartError::AgentClosed),
498        }
499    }
500}
501
502pub(crate) struct AttachmentGuard<M: Client> {
503    inner: Arc<AgentInner<M>>,
504}
505
506impl<M: Client> Drop for AttachmentGuard<M> {
507    fn drop(&mut self) {
508        let mut state = self.inner.state.lock().expect("Agent state lock poisoned");
509        state.active_runs -= 1;
510    }
511}
512
513#[cfg_attr(
514    coverage,
515    expect(
516        deprecated,
517        reason = "fetch_update preserves Reef's 1.85 MSRV; nightly renamed it to try_update"
518    )
519)]
520pub(crate) fn allocate_revision_id(counter: &AtomicU64) -> Result<NonZeroU64, ConfigError> {
521    match counter.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |value| {
522        value.checked_add(1)
523    }) {
524        Ok(value) => NonZeroU64::new(value).ok_or(ConfigError::RevisionIdExhausted),
525        Err(_) => Err(ConfigError::RevisionIdExhausted),
526    }
527}