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::hook::{self, HookError};
34use crate::runtime::model::{Client, RequestPlan};
35use crate::runtime::run::Run;
36use crate::runtime::session::Session;
37use crate::value::content::Part;
38
39static NEXT_REVISION_ID: AtomicU64 = AtomicU64::new(1);
40
41/// Cloneable handle to one immutable revision and its private teardown authority.
42///
43/// An Agent is configuration that has been frozen: [`Agent::new`] consumes a
44/// [`Config`] and produces a [`Revision`] that never changes again. Starting a
45/// Run against a different model, tool roster or hook roster means building a
46/// second Agent — see [`Revision`] for the exact extent of that rule and for
47/// what it deliberately leaves free.
48///
49/// It is `Clone`, and every clone shares one teardown authority: whichever one
50/// calls [`close`](Agent::close) first runs each hook's `OnClose` exactly once
51/// and every other caller receives that same cached result.
52///
53/// ```
54/// # use std::future::{Future, ready};
55/// # use std::pin::Pin;
56/// # use std::sync::Arc;
57/// # use std::task::{Context, Poll};
58/// # use reef_core::futures_core::Stream;
59/// # use reef_core::runtime::model;
60/// # #[derive(Debug)] struct Offline;
61/// # #[derive(Debug)] struct Once(bool);
62/// # impl Stream for Once {
63/// #     type Item = Result<model::Event, std::convert::Infallible>;
64/// #     fn poll_next(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Option<Self::Item>> {
65/// #         if std::mem::replace(&mut self.0, true) { return Poll::Ready(None); }
66/// #         Poll::Ready(Some(Ok(model::Event::Done { finish_reason: "stop".to_owned(), completion: model::CompletionReason::Stop, provider_data: Vec::new() })))
67/// #     }
68/// # }
69/// # impl model::Client for Offline {
70/// #     type Error = std::convert::Infallible;
71/// #     type Stream = Once;
72/// #     fn info(&self) -> model::Info { model::Info::new("offline".to_owned(), 8_192) }
73/// #     fn generate(&self, _: model::Request) -> impl Future<Output = Result<Self::Stream, Self::Error>> + Send { ready(Ok(Once(false))) }
74/// # }
75/// use reef_core::cancel;
76/// use reef_core::runtime::{agent, hook, session, tool};
77/// use reef_core::value::{content, lifecycle};
78///
79/// # #[tokio::main(flavor = "current_thread")]
80/// # async fn main() {
81/// let config = agent::Config::new(
82///     Arc::new(Offline),
83///     tool::RegistryBuilder::new().build().unwrap(),
84///     hook::RegistryBuilder::new(),
85/// );
86/// let agent = agent::Agent::new(config).unwrap();
87///
88/// let session = session::Session::new("conversation-1".to_owned(), None);
89/// let run = agent
90///     .start(session, vec![content::Part::text("Hi.".to_owned())], cancel::Token::new())
91///     .await
92///     .unwrap();
93/// assert_eq!(run.revision().id(), agent.revision().id());
94///
95/// let mut events = run.take_events().unwrap();
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::Registry,
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    /// Both halves are synchronous: ADR-015 makes admission a straight-line
234    /// sequence that never yields, and spawning the Run task returns as soon as
235    /// the task is queued. `async` here is the caller-facing contract rather
236    /// than an implementation fact — it states that a Tokio runtime must be
237    /// live, which is what makes the spawn legal, and it keeps the facade's
238    /// three lifecycle entries the same shape.
239    ///
240    /// # Errors
241    ///
242    /// Every variant here is **pre-admission**: a `StartError` means no Run exists,
243    /// the Session lease and Agent attachment have been rolled back, and the
244    /// transcript is as it was. Once admission completes, failure is reported by the
245    /// returned Run's terminal instead.
246    ///
247    /// - [`StartError::AgentClosed`] if [`Agent::close`] already won. Checked before
248    ///   the Session is touched, so a closed Agent cannot disturb one.
249    /// - [`StartError::SessionBusy`] if the Session already has an active lease.
250    ///   Retryable once that Run has fully exited; this is the one-active-Run rule,
251    ///   not a transient lock.
252    /// - [`StartError::Cancelled`] if `cancellation` was already observable, or
253    ///   became so, before the last pre-admission commit. A cancellation that first
254    ///   becomes visible at or after that commit yields an admitted Run whose
255    ///   terminal is canceled instead — so a caller racing cancellation against
256    ///   start must handle both.
257    /// - [`StartError::Admission`] if the Session refused the binding set, carrying
258    ///   the [`LeaseError`](crate::runtime::session::LeaseError) that says which
259    ///   rule it broke.
260    /// - [`StartError::Prepare`] if a [`RunHooks::prepare`](super::hook::RunHooks::prepare)
261    ///   registration or a transcript reservation failed, naming the registration.
262    /// - [`StartError::Transcript`] if recording the admitted input failed, carrying
263    ///   the [`store::Error`](crate::transcript::store::Error).
264    /// - [`StartError::InvalidIdentity`] if the Session or Run identity is not a
265    ///   valid coordinate, and [`StartError::RunIdExhausted`] if the process-wide Run
266    ///   identity space is used up.
267    ///
268    /// # Panics
269    ///
270    /// If the Agent state, Session, mailbox, event-control, or hook-fact lock is
271    /// poisoned, per the crate-level
272    /// [lock-poisoning contract](crate#lock-poisoning).
273    #[expect(
274        clippy::unused_async,
275        reason = "ADR-015 keeps the public facade awaited; admission itself never yields"
276    )]
277    pub async fn start(
278        &self,
279        session: Session,
280        input: Vec<Part>,
281        cancellation: Token,
282    ) -> Result<Run<M>, StartError> {
283        let admitted = self.admit_start(session, input, cancellation)?;
284        Ok(Run::spawn(admitted))
285    }
286
287    pub(crate) fn new_with_counter(
288        config: Config<M>,
289        revision_ids: &AtomicU64,
290    ) -> Result<Self, ConfigError> {
291        let Config {
292            model,
293            tools,
294            hooks,
295            tool_gate,
296            system_instruction,
297            sampling,
298            model_extensions,
299        } = config;
300        // `RegistryBuilder::build` is the consuming producer of this registry.
301        let hooks = hooks.build().map_err(ConfigError::Hooks)?;
302
303        // Validate through the real `RequestPlan::try_into_request` producer.
304        let mut defaults = RequestPlan::new();
305        defaults
306            .extend_system_instruction(system_instruction.iter().cloned())
307            .extend_extensions(model_extensions.iter().cloned());
308        *defaults.sampling_mut() = sampling.clone();
309        defaults
310            .try_into_request(Vec::new())
311            .map_err(ConfigError::InvalidDefaults)?;
312
313        let id = allocate_revision_id(revision_ids)?;
314        let revision = Revision {
315            id,
316            model,
317            tools,
318            hook_names: hooks.names().map(str::to_owned).collect(),
319            hook_bindings: hooks.bindings().into(),
320            hooks_require_session_state: hooks.requires_session_state(),
321            tool_gate,
322            system_instruction: system_instruction.into(),
323            sampling,
324            model_extensions: model_extensions.into(),
325        };
326        Ok(Self {
327            inner: Arc::new(AgentInner {
328                revision,
329                hooks,
330                state: Mutex::new(AgentState {
331                    phase: AgentPhase::Open,
332                    active_runs: 0,
333                }),
334                closed: Notify::new(),
335                #[cfg(test)]
336                close_wait_probe: Mutex::new(Arc::new(CloseWaitProbe::new(0))),
337                #[cfg(test)]
338                start_snapshot_results: Mutex::new(VecDeque::new()),
339            }),
340        })
341    }
342
343    /// Returns an owned immutable revision handle without teardown authority.
344    #[must_use]
345    pub fn revision(&self) -> Revision<M> {
346        self.inner.revision.clone()
347    }
348
349    /// Closes an idle Agent exactly once, or reports an exact retryable busy count.
350    ///
351    /// # Errors
352    ///
353    /// - [`CloseError::Busy`], carrying the exact number of attachments observed at
354    ///   the linearization point, if any Run still owns this Agent. This is the
355    ///   retryable one, and it is deliberately inert: admission is not sealed and no
356    ///   teardown callback runs, so a busy close changes nothing and can be repeated
357    ///   after stopping or awaiting the Runs it counted.
358    /// - [`CloseError::Hooks`] if teardown ran and some callbacks failed or panicked.
359    ///   Every registration's `OnClose` ran regardless, in registration order, and
360    ///   [`TeardownError::entries`] lists each failure with its hook's name.
361    ///
362    /// The second is final rather than retryable: the Agent is closed, the result is
363    /// cached, and a later or concurrent close returns this same value without
364    /// invoking teardown again.
365    ///
366    /// # Panics
367    ///
368    /// If the Agent phase lock is poisoned, per the crate-level
369    /// [lock-poisoning contract](crate#lock-poisoning). That lock is the one
370    /// place `Open`, `Closing`, and `Closed` linearize, so a poisoned one means
371    /// the Agent's close authority is no longer trustworthy; a teardown callback
372    /// cannot cause it, because a panicking `OnClose` is caught at its own
373    /// boundary and reported as [`CloseError::Hooks`] instead.
374    pub async fn close(&self) -> Result<(), CloseError> {
375        loop {
376            let notified = self.inner.closed.notified();
377            tokio::pin!(notified);
378            notified.as_mut().enable();
379            match self.close_decision()? {
380                CloseDecision::Winner => break,
381                CloseDecision::Wait => notified.await,
382                CloseDecision::Cached(result) => return result,
383            }
384        }
385
386        let panic_error = HookError::new(ClosePanickedError);
387        let failures = self.inner.hooks.close_isolated(&panic_error);
388        let result = if failures.is_empty() {
389            Ok(())
390        } else {
391            Err(CloseError::Hooks(TeardownError(failures.into())))
392        };
393        let mut state = self.inner.state.lock().expect("Agent state lock poisoned");
394        state.phase = AgentPhase::Closed(result.clone());
395        drop(state);
396        self.inner.closed.notify_waiters();
397        result
398    }
399
400    fn close_decision(&self) -> Result<CloseDecision, CloseError> {
401        let decision = {
402            let mut state = self.inner.state.lock().expect("Agent state lock poisoned");
403            match &state.phase {
404                AgentPhase::Open if state.active_runs != 0 => {
405                    return Err(CloseError::Busy {
406                        active_runs: state.active_runs,
407                    });
408                }
409                AgentPhase::Open => {
410                    state.phase = AgentPhase::Closing;
411                    CloseDecision::Winner
412                }
413                AgentPhase::Closing => CloseDecision::Wait,
414                AgentPhase::Closed(result) => CloseDecision::Cached(result.clone()),
415            }
416        };
417        #[cfg(test)]
418        if matches!(&decision, CloseDecision::Wait) {
419            self.pause_close_waiter_before_await();
420        }
421        Ok(decision)
422    }
423
424    #[cfg(test)]
425    pub(crate) fn install_close_wait_probe(&self, waiters: usize) -> Arc<CloseWaitProbe> {
426        let probe = Arc::new(CloseWaitProbe::new(waiters));
427        *self
428            .inner
429            .close_wait_probe
430            .lock()
431            .expect("close wait probe lock poisoned") = Arc::clone(&probe);
432        probe
433    }
434
435    #[cfg(test)]
436    fn pause_close_waiter_before_await(&self) {
437        let probe = self
438            .inner
439            .close_wait_probe
440            .lock()
441            .expect("close wait probe lock poisoned")
442            .clone();
443        probe.pause_before_await();
444    }
445
446    pub(crate) fn reserve_attachment(&self) -> Result<AttachmentGuard<M>, StartError> {
447        let mut state = self.inner.state.lock().expect("Agent state lock poisoned");
448        match state.phase {
449            AgentPhase::Open => {
450                state.active_runs += 1;
451                Ok(AttachmentGuard {
452                    inner: Arc::clone(&self.inner),
453                })
454            }
455            AgentPhase::Closing | AgentPhase::Closed(_) => Err(StartError::AgentClosed),
456        }
457    }
458}
459
460pub(crate) struct AttachmentGuard<M: Client> {
461    inner: Arc<AgentInner<M>>,
462}
463
464impl<M: Client> Drop for AttachmentGuard<M> {
465    fn drop(&mut self) {
466        let mut state = self.inner.state.lock().expect("Agent state lock poisoned");
467        state.active_runs -= 1;
468    }
469}
470
471#[cfg_attr(
472    coverage,
473    expect(
474        deprecated,
475        reason = "fetch_update preserves Reef's 1.85 MSRV; nightly renamed it to try_update"
476    )
477)]
478pub(crate) fn allocate_revision_id(counter: &AtomicU64) -> Result<NonZeroU64, ConfigError> {
479    match counter.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |value| {
480        value.checked_add(1)
481    }) {
482        Ok(value) => NonZeroU64::new(value).ok_or(ConfigError::RevisionIdExhausted),
483        Err(_) => Err(ConfigError::RevisionIdExhausted),
484    }
485}