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}