reef-core 0.4.0

Provider-neutral primitives for building LLM agents: run lifecycle, transcript, tools, hooks
Documentation
//! Synchronous Run admission and its linear pre-spawn owner.

use std::sync::Arc;
use std::sync::atomic::{AtomicU64, Ordering};

use crate::cancel::Token;

use super::{Agent, AttachmentGuard, Revision, StartError};
use crate::runtime::event::{EventSource, Producer, channel};
use crate::runtime::hook::{
    self, CallbackResources, DispatchError, FactBuffer, PrepareDecision, StagedTranscript,
};
use crate::runtime::model::{Client, RequestPlan};
use crate::runtime::session::{Lease, LeaseError, Session};
use crate::state::run_state::{self};
use crate::state::session_state::{self};
use crate::transcript::controller::{ControllerError, ReservationResources, TranscriptController};
use crate::transcript::item::{Item, ModelVisibility, User};
use crate::transcript::store;
use crate::value::content::Part;
use crate::value::lifecycle::Coord;

static NEXT_RUN_ID: AtomicU64 = AtomicU64::new(1);

/// The complete, admitted pre-spawn owner transferred to the Run task.
///
/// Dropping this value before the Run task consumes it releases the Session lease
/// and detaches the Agent through the two RAII guards it owns. Admission spawns no
/// task, so every field is already stable when it returns.
pub(crate) struct AdmittedStart<M: Client> {
    // Field order is cleanup order: release Session authority before detaching
    // the Agent, matching the terminal owner order frozen by ADR-015.
    pub(crate) lease: Lease,
    pub(crate) attachment: AttachmentGuard<M>,
    pub(crate) revision: Revision<M>,
    pub(crate) session: Session,
    pub(crate) input: Vec<Part>,
    /// The admitted input exactly as it was recorded, if anything was.
    ///
    /// This is what opened the Run's first Turn, and the loop needs the record
    /// rather than the parts: nothing in the committed history distinguishes it
    /// from a later turn's input.
    pub(crate) admitted_items: Vec<Item>,
    pub(crate) plan: RequestPlan,
    pub(crate) identity: Coord,
    pub(crate) cancellation: Token,
    pub(crate) producer: Arc<Producer>,
    pub(crate) source: EventSource,
    pub(crate) hooks: hook::RuntimeRegistry,
    pub(crate) reservation_resources: ReservationResources,
    pub(crate) run_states: Vec<run_state::Store>,
    pub(crate) session_state: session_state::Reader,
    /// The queue every synchronous callback in this Run writes its facts to.
    ///
    /// Admission fills it before the Run task exists, which is why it is
    /// transferred rather than created by the task; the loop then keeps draining
    /// the same queue at each of its own publication points.
    pub(crate) fact_buffer: FactBuffer,
}

impl<M: Client + 'static> Agent<M> {
    #[cfg(test)]
    pub(crate) fn install_start_snapshot_results(&self, results: Vec<Option<store::Error>>) {
        *self
            .inner
            .start_snapshot_results
            .lock()
            .expect("start snapshot-result lock poisoned") = results.into();
    }

    // The body is the identity outside a test build, where `const` is both
    // possible and pointless; inside one it takes a lock, so the same signature
    // cannot carry the keyword. Producing different output under `cfg(test)` is
    // the defect, not the missing `const`.
    #[cfg_attr(
        not(test),
        expect(
            clippy::missing_const_for_fn,
            reason = "the cfg(test) body of this same function locks a mutex"
        )
    )]
    fn start_snapshot<T>(&self, result: Result<T, store::Error>) -> Result<T, store::Error> {
        #[cfg(test)]
        if let Some(injected) = self
            .inner
            .start_snapshot_results
            .lock()
            .expect("start snapshot-result lock poisoned")
            .pop_front()
            .flatten()
        {
            return Err(injected);
        }
        result
    }

    /// Completes the synchronous half of `Agent::start` without spawning work.
    ///
    /// The ordering is the accepted admission sequence: attachment, lease, owned
    /// runtime freeze, the admitted barrier, registration-order prepare, one live
    /// controller commit, staged Session-state commit, then admitted observers.
    pub(crate) fn admit_start(
        &self,
        session: Session,
        input: Vec<Part>,
        cancellation: Token,
    ) -> Result<AdmittedStart<M>, StartError> {
        self.admit_start_with_run_ids(session, input, cancellation, &NEXT_RUN_ID)
    }

    pub(crate) fn admit_start_with_run_ids(
        &self,
        session: Session,
        input: Vec<Part>,
        cancellation: Token,
        run_ids: &AtomicU64,
    ) -> Result<AdmittedStart<M>, StartError> {
        // Closing wins before Session::try_acquire is touched (ADR-015:166-167).
        let attachment = self.reserve_attachment()?;
        let lease = session.try_acquire().ok_or(StartError::SessionBusy)?;

        let revision = self.inner.revision.clone();
        let hooks = self.inner.hooks.clone();
        let identity = run_coord(&session, revision.id().get(), run_ids)?;
        let plan = plan_from_revision(&revision);
        let (producer, source) = channel(&cancellation);
        let fact_buffer = FactBuffer::default();
        let session_state = lease.state().reader();
        let run_states = (0..hooks.len())
            .map(|_| run_state::Store::new())
            .collect::<Vec<_>>();
        let reservation_resources =
            ReservationResources::shared(&run_states, lease.state().reader());

        lease.admit().map_err(StartError::Admission)?;

        let controller = TranscriptController::new(
            &lease,
            &hooks,
            &reservation_resources,
            &identity,
            &fact_buffer,
        );
        // Shared staging plus one final replacement: hook dispatch and the live
        // transcript controller share one reserve/CAS/publish boundary.
        let staged_store = map_snapshot(controller.staging_store())?;
        let staged_transcript = StagedTranscript::from_store(&staged_store);
        let base_version = map_snapshot(self.start_snapshot(staged_store.version()))?;
        let staged_state = lease.state().staged();
        let mut prepared_input = input;
        let mut run_hooks = hooks.run_hooks().peekable();
        let base = if run_hooks.peek().is_some() {
            Some(map_snapshot(staged_store.snapshot_reader().snapshot())?)
        } else {
            None
        };

        for adapter in run_hooks {
            let run_state = run_states
                .get(adapter.index())
                .expect("Run resources cover every hook registration");
            let resources = CallbackResources::new(
                &identity,
                run_state,
                &session_state,
                Some(lease.state()),
                &fact_buffer,
            );
            let decision = adapter
                .invoke_prepare(
                    resources,
                    &staged_transcript,
                    Some(&staged_state),
                    base.as_ref()
                        .expect("Run hook dispatch materializes the base snapshot"),
                    &prepared_input,
                    &cancellation,
                )
                .map_err(map_dispatch)?;
            match decision {
                PrepareDecision::Continue => {}
                PrepareDecision::Modify(replacement) => prepared_input = replacement,
            }
        }
        drop(base);

        let staged_version = map_snapshot(self.start_snapshot(staged_store.version()))?;
        drop(staged_transcript);
        let staged_snapshot = if staged_version != base_version {
            Some(staged_store)
        } else {
            drop(staged_store);
            None
        };
        // The admitted input is model-visible, so it is recorded here rather than
        // carried as per-request content. Anything the model reads that the
        // transcript never saw is invisible to persistence, resume, compaction and
        // replay, which is why "model-visible implies recorded" holds everywhere
        // else in the crate. Empty here means the caller submitted no parts and
        // no registration composed any, so recording a `User` would assert
        // something nobody said. A registration cannot reach this branch by
        // blanking the input: `PrepareDecision::Continue` leaves earlier parts
        // alone and an empty `Modify` is refused at the dispatch boundary.
        let admitted_items = if prepared_input.is_empty() {
            Vec::new()
        } else {
            vec![Item::User(User::new(
                prepared_input.clone(),
                ModelVisibility::Visible,
            ))]
        };
        if let Some(staged_store) = staged_snapshot {
            // One transaction, so a hook's staged history and the input it was
            // shown cannot reach the transcript separately. The staged history
            // and admitted suffix are materialized together at most once.
            let snapshot =
                map_snapshot(staged_store.into_snapshot_with_suffix(admitted_items.clone()))?;
            controller
                .replace_snapshot(snapshot, base_version, &cancellation)
                .map_err(map_controller)?;
        } else if !admitted_items.is_empty() {
            controller
                .append_batch(admitted_items.clone(), &cancellation)
                .map_err(map_controller)?;
        } else if cancellation.is_cancelled() {
            // With no live transcript mutation at all, this is the final
            // pre-commit cut. Cancellation after this branch belongs to the
            // admitted Run.
            return Err(StartError::Cancelled);
        }

        // A retained lease makes this commit infallible. Crossing the controller
        // commit (or the no-transcript cut above) means later cancellation cannot
        // reclassify Start as an error.
        staged_state
            .commit()
            .expect("an owned admitted lease keeps staged Session state writable");

        let transcript = lease.transcript_reader();
        for adapter in hooks.observer_hooks() {
            let run_state = run_states
                .get(adapter.index())
                .expect("Run resources cover every hook registration");
            let resources = CallbackResources::new(
                &identity,
                run_state,
                &session_state,
                Some(lease.state()),
                &fact_buffer,
            );
            adapter.invoke_run_admitted(resources, &transcript);
        }

        Ok(AdmittedStart {
            attachment,
            lease,
            revision,
            session,
            input: prepared_input,
            admitted_items,
            plan,
            identity,
            cancellation,
            producer,
            source,
            hooks,
            reservation_resources,
            run_states,
            session_state,
            fact_buffer,
        })
    }
}

fn plan_from_revision<M: Client>(revision: &Revision<M>) -> RequestPlan {
    let mut plan = RequestPlan::new();
    plan.extend_system_instruction(revision.system_instruction().iter().cloned())
        .extend_extensions(revision.model_extensions().iter().cloned());
    *plan.sampling_mut() = revision.sampling().clone();
    plan
}

#[cfg_attr(
    coverage,
    expect(
        deprecated,
        reason = "fetch_update preserves Reef's 1.85 MSRV; nightly renamed it to try_update"
    )
)]
fn run_coord(
    session: &Session,
    revision_id: u64,
    run_ids: &AtomicU64,
) -> Result<Coord, StartError> {
    let sequence = run_ids
        .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |value| {
            value.checked_add(1)
        })
        .map_err(|_| StartError::RunIdExhausted)?;
    if sequence == 0 {
        return Err(StartError::RunIdExhausted);
    }
    Coord::at_run(
        session.id().to_owned(),
        format!("revision-{revision_id}-run-{sequence}"),
    )
    .map_err(StartError::InvalidIdentity)
}

fn map_dispatch(error: DispatchError) -> StartError {
    match error {
        DispatchError::Cancelled => StartError::Cancelled,
        DispatchError::Callback(failure) => StartError::Prepare(failure),
    }
}

pub(crate) fn map_snapshot<T>(result: Result<T, store::Error>) -> Result<T, StartError> {
    result.map_err(StartError::Transcript)
}

pub(crate) fn map_controller(error: ControllerError) -> StartError {
    match error {
        ControllerError::Dispatch(error) => map_dispatch(error),
        ControllerError::Lease(LeaseError::Transcript(error)) => StartError::Transcript(error),
        ControllerError::Lease(error) => StartError::Admission(error),
        ControllerError::InvalidTransition { previous, delta } => {
            StartError::Transcript(store::Error::VersionOverflow {
                current: previous,
                delta,
            })
        }
    }
}