mod config;
mod error;
pub(crate) mod start;
pub use config::{Config, Revision};
pub use error::{CloseError, ClosePanickedError, ConfigError, StartError, TeardownError};
#[cfg(not(test))]
#[expect(
unused_imports,
reason = "admission freezes the linear owner that the Run module will consume"
)]
pub(crate) use start::AdmittedStart;
#[cfg(test)]
pub(crate) use start::AdmittedStart;
use std::num::NonZeroU64;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, Mutex};
use crate::cancel::Token;
#[cfg(test)]
use crate::transcript::store;
#[cfg(test)]
use std::collections::VecDeque;
#[cfg(test)]
use std::sync::Barrier;
#[cfg(test)]
use std::sync::atomic::AtomicUsize;
use tokio::sync::Notify;
use crate::runtime::event::Stream;
use crate::runtime::hook;
use crate::runtime::model::{Client, RequestPlan};
use crate::runtime::run::Run;
use crate::runtime::session::Session;
use crate::value::content::Part;
static NEXT_REVISION_ID: AtomicU64 = AtomicU64::new(1);
pub struct Agent<M: Client> {
inner: Arc<AgentInner<M>>,
}
impl<M: Client> std::fmt::Debug for Agent<M> {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter
.debug_struct("Agent")
.field("revision", &self.inner.revision.id())
.finish()
}
}
impl<M: Client> Clone for Agent<M> {
fn clone(&self) -> Self {
Self {
inner: Arc::clone(&self.inner),
}
}
}
struct AgentInner<M: Client> {
revision: Revision<M>,
hooks: hook::RuntimeRegistry,
state: Mutex<AgentState>,
closed: Notify,
#[cfg(test)]
close_wait_probe: Mutex<Arc<CloseWaitProbe>>,
#[cfg(test)]
start_snapshot_results: Mutex<VecDeque<Option<store::Error>>>,
}
#[cfg(test)]
pub(crate) struct CloseWaitProbe {
waiters: usize,
observations: AtomicUsize,
observed_closing: Barrier,
resume: Barrier,
rechecked_closing: Barrier,
}
#[cfg(test)]
impl CloseWaitProbe {
fn new(waiters: usize) -> Self {
Self {
waiters,
observations: AtomicUsize::new(0),
observed_closing: Barrier::new(waiters + 1),
resume: Barrier::new(waiters + 1),
rechecked_closing: Barrier::new(waiters + 1),
}
}
fn pause_before_await(&self) {
if self.observations.fetch_add(1, Ordering::SeqCst) < self.waiters {
self.observed_closing.wait();
self.resume.wait();
} else {
self.rechecked_closing.wait();
}
}
pub(crate) fn wait_until_closing_observed(&self) {
self.observed_closing.wait();
}
pub(crate) fn notify_waiters_one_by_one<M: Client>(&self, agent: &Agent<M>) {
for _ in 0..self.waiters {
agent.inner.closed.notify_one();
}
}
pub(crate) fn resume_waiters(&self) {
self.resume.wait();
}
pub(crate) fn wait_until_closing_rechecked(&self) {
self.rechecked_closing.wait();
}
}
struct AgentState {
phase: AgentPhase,
active_runs: usize,
}
enum AgentPhase {
Open,
Closing,
Closed(Result<(), CloseError>),
}
enum CloseDecision {
Winner,
Wait,
Cached(Result<(), CloseError>),
}
impl<M: Client + 'static> Agent<M> {
pub fn new(config: Config<M>) -> Result<Self, ConfigError> {
Self::new_with_counter(config, &NEXT_REVISION_ID)
}
#[expect(
clippy::unused_async,
reason = "ADR-015 keeps the public facade awaited; admission itself never yields"
)]
pub async fn start(
&self,
session: Session,
input: Vec<Part>,
cancellation: Token,
) -> Result<Run<M>, StartError> {
let admitted = self.admit_start(session, input, cancellation)?;
Ok(Run::spawn(admitted))
}
#[expect(
clippy::unused_async,
reason = "ADR-015 keeps the public facade awaited; admission itself never yields"
)]
pub async fn start_observed(
&self,
session: Session,
input: Vec<Part>,
cancellation: Token,
) -> Result<(Run<M>, Stream), StartError> {
let admitted = self.admit_start(session, input, cancellation)?;
Ok(Run::spawn_observed(admitted))
}
pub(crate) fn new_with_counter(
config: Config<M>,
revision_ids: &AtomicU64,
) -> Result<Self, ConfigError> {
let Config {
model,
tools,
hooks,
system_instruction,
sampling,
model_extensions,
} = config;
let hooks = hooks.build_runtime().map_err(ConfigError::Hooks)?;
let mut defaults = RequestPlan::new();
defaults
.extend_system_instruction(system_instruction.iter().cloned())
.extend_extensions(model_extensions.iter().cloned());
*defaults.sampling_mut() = sampling.clone();
defaults
.try_into_request(Vec::new())
.map_err(ConfigError::InvalidDefaults)?;
let id = allocate_revision_id(revision_ids)?;
let revision = Revision {
id,
model,
tools,
hook_names: hooks.names().map(str::to_owned).collect(),
hooks_require_session_state: hooks.requires_session_state(),
system_instruction: system_instruction.into(),
sampling,
model_extensions: model_extensions.into(),
};
Ok(Self {
inner: Arc::new(AgentInner {
revision,
hooks,
state: Mutex::new(AgentState {
phase: AgentPhase::Open,
active_runs: 0,
}),
closed: Notify::new(),
#[cfg(test)]
close_wait_probe: Mutex::new(Arc::new(CloseWaitProbe::new(0))),
#[cfg(test)]
start_snapshot_results: Mutex::new(VecDeque::new()),
}),
})
}
#[must_use]
pub fn revision(&self) -> Revision<M> {
self.inner.revision.clone()
}
pub async fn close(&self) -> Result<(), CloseError> {
loop {
let notified = self.inner.closed.notified();
tokio::pin!(notified);
notified.as_mut().enable();
match self.close_decision()? {
CloseDecision::Winner => break,
CloseDecision::Wait => notified.await,
CloseDecision::Cached(result) => return result,
}
}
let failures = self.inner.hooks.close();
let result = if failures.is_empty() {
Ok(())
} else {
Err(CloseError::Hooks(TeardownError(failures.into())))
};
let mut state = self.inner.state.lock().expect("Agent state lock poisoned");
state.phase = AgentPhase::Closed(result.clone());
drop(state);
self.inner.closed.notify_waiters();
result
}
fn close_decision(&self) -> Result<CloseDecision, CloseError> {
let decision = {
let mut state = self.inner.state.lock().expect("Agent state lock poisoned");
match &state.phase {
AgentPhase::Open if state.active_runs != 0 => {
return Err(CloseError::Busy {
active_runs: state.active_runs,
});
}
AgentPhase::Open => {
state.phase = AgentPhase::Closing;
CloseDecision::Winner
}
AgentPhase::Closing => CloseDecision::Wait,
AgentPhase::Closed(result) => CloseDecision::Cached(result.clone()),
}
};
#[cfg(test)]
if matches!(&decision, CloseDecision::Wait) {
self.pause_close_waiter_before_await();
}
Ok(decision)
}
#[cfg(test)]
pub(crate) fn install_close_wait_probe(&self, waiters: usize) -> Arc<CloseWaitProbe> {
let probe = Arc::new(CloseWaitProbe::new(waiters));
*self
.inner
.close_wait_probe
.lock()
.expect("close wait probe lock poisoned") = Arc::clone(&probe);
probe
}
#[cfg(test)]
fn pause_close_waiter_before_await(&self) {
let probe = self
.inner
.close_wait_probe
.lock()
.expect("close wait probe lock poisoned")
.clone();
probe.pause_before_await();
}
pub(crate) fn reserve_attachment(&self) -> Result<AttachmentGuard<M>, StartError> {
let mut state = self.inner.state.lock().expect("Agent state lock poisoned");
match state.phase {
AgentPhase::Open => {
state.active_runs += 1;
Ok(AttachmentGuard {
inner: Arc::clone(&self.inner),
})
}
AgentPhase::Closing | AgentPhase::Closed(_) => Err(StartError::AgentClosed),
}
}
}
pub(crate) struct AttachmentGuard<M: Client> {
inner: Arc<AgentInner<M>>,
}
impl<M: Client> Drop for AttachmentGuard<M> {
fn drop(&mut self) {
let mut state = self.inner.state.lock().expect("Agent state lock poisoned");
state.active_runs -= 1;
}
}
#[cfg_attr(
coverage,
expect(
deprecated,
reason = "fetch_update preserves Reef's 1.85 MSRV; nightly renamed it to try_update"
)
)]
pub(crate) fn allocate_revision_id(counter: &AtomicU64) -> Result<NonZeroU64, ConfigError> {
match counter.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |value| {
value.checked_add(1)
}) {
Ok(value) => NonZeroU64::new(value).ok_or(ConfigError::RevisionIdExhausted),
Err(_) => Err(ConfigError::RevisionIdExhausted),
}
}