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}