reef-core 0.4.0

Provider-neutral primitives for building LLM agents: run lifecycle, transcript, tools, hooks
Documentation
//! The single atomic commit boundary of one source-ordered tool batch.
//!
//! This crate-private layer closes the batch that the prepare layer planned and
//! the route layer executed. It does exactly four things:
//!
//! 1. fan [`crate::runtime::hook::ToolHooks::before_tool_result`] out over every source position in registration
//!    order, propagating each rewrite to the next registration,
//! 2. materialize one closed [`item::ToolResult`] per position, retaining the
//!    model-assigned call ID and naming the tool that was actually routed,
//! 3. rewrite the assistant's call segments to those same effective calls, then
//!    assemble it ahead of the complete result set in source order and commit all
//!    records through exactly one
//!    [`TranscriptController::append_batch`], and
//! 4. return the committed [`Version`] together with the source-correlated
//!    finalized records the driver needs.
//!
//! The assistant output and its complete result set are one model-visible
//! exchange: a rewrite failure, an observed
//! cancellation, or a rejected mutation reservation leaves neither half in the
//! transcript, because nothing is committed until every position has been
//! materialized. Execution has already finished by the time this layer runs, so
//! a failure here never unwinds work - it only withholds publication.
//!
//! Producer strong-acceptance seams, [`crate::runtime::hook::ToolHooks::after_tool_commit`], lifecycle
//! observation, and terminal unwinding all remain outside this boundary and are
//! owned by the driver.

use std::num::NonZeroU64;
use std::sync::Arc;

use crate::cancel::Token;

use crate::runtime::hook::{
    self, CallbackResources, DispatchError, StepSnapshot, ToolResultDecision,
};
use crate::runtime::tool::CallDisposition;
use crate::runtime::tool_batch_route::{RoutedToolBatch, ToolRouteRecord};
use crate::transcript::controller::{ControllerError, TranscriptController};
use crate::transcript::item::{self, Assistant, Item};
use crate::transcript::store::Version;
use crate::value::content::Segment;
use crate::value::lifecycle::{Coord, StepIndex};
use crate::value::tool_call::ToolCall;

/// One committed source position, correlated with both sides of the rewrite.
///
/// The retained item is the exact record the transcript now holds, so the driver can
/// publish the committed fact instead of rebuilding a second, possibly
/// divergent, projection of it.
#[derive(Clone)]
pub(crate) struct FinalizedToolCall {
    original_call: ToolCall,
    effective_call: ToolCall,
    disposition: CallDisposition,
    item: item::ToolResult,
}

impl FinalizedToolCall {
    /// Returns the exact model-produced call.
    pub(crate) const fn original_call(&self) -> &ToolCall {
        &self.original_call
    }

    /// Returns the final call that was routed.
    pub(crate) const fn effective_call(&self) -> &ToolCall {
        &self.effective_call
    }

    /// Returns the stable disposition this position reached.
    pub(crate) const fn disposition(&self) -> CallDisposition {
        self.disposition
    }

    /// Returns the committed transcript record.
    pub(crate) const fn item(&self) -> &item::ToolResult {
        &self.item
    }

    /// Transfers the complete correlated commit fact.
    #[cfg(test)]
    pub(crate) fn into_parts(self) -> (ToolCall, ToolCall, CallDisposition, item::ToolResult) {
        (
            self.original_call,
            self.effective_call,
            self.disposition,
            self.item,
        )
    }
}

/// The committed version plus every source-ordered finalized position.
pub(crate) struct ToolBatchCommit {
    // Read only by the two `#[cfg(test)]` accessors above, so a production build
    // holds it and never looks at it. `expect` rather than `cfg(test)` because
    // the field is set by the production commit path.
    #[cfg_attr(
        not(test),
        expect(dead_code, reason = "read only by the test accessors")
    )]
    version: Version,
    finalized: Vec<FinalizedToolCall>,
}

impl ToolBatchCommit {
    /// Returns the version the atomic append advanced the transcript to.
    #[cfg(test)]
    pub(crate) const fn version(&self) -> Version {
        self.version
    }

    /// Returns every finalized position in source order.
    pub(crate) fn finalized(&self) -> &[FinalizedToolCall] {
        &self.finalized
    }

    /// Transfers the committed version and the finalized positions.
    #[cfg(test)]
    pub(crate) fn into_parts(self) -> (Version, Vec<FinalizedToolCall>) {
        (self.version, self.finalized)
    }
}

/// Why one batch was not committed.
///
/// Every variant leaves the transcript exactly as it was: the batch either never
/// reached the append, or the append itself resolved as a pre-commit failure.
#[derive(Debug)]
pub(crate) enum ToolBatchCommitError {
    /// Cancellation was already observable before any rewrite ran.
    ///
    /// This carries no source index because no source position was reached, so
    /// attributing it to one would invent a fact this layer never learned.
    Cancelled,
    /// The rewrite fan-out at this source position failed.
    Rewrite {
        /// The source position whose fan-out stopped.
        source_index: usize,
        /// The callback failure, or the cancellation observed around it.
        error: DispatchError,
    },
    /// The single atomic append did not commit.
    Controller(ControllerError),
}

impl ToolBatchCommitError {
    /// Returns the source position and dispatch failure of a failed rewrite.
    #[cfg_attr(not(test), expect(dead_code, reason = "reached only by tests so far"))]
    pub(crate) const fn rewrite(&self) -> Option<(usize, &DispatchError)> {
        match self {
            Self::Rewrite {
                source_index,
                error,
            } => Some((*source_index, error)),
            Self::Cancelled | Self::Controller(_) => None,
        }
    }

    /// Returns the pre-commit controller failure, when the append was reached.
    #[cfg_attr(not(test), expect(dead_code, reason = "reached only by tests so far"))]
    pub(crate) const fn controller(&self) -> Option<&ControllerError> {
        match self {
            Self::Controller(error) => Some(error),
            Self::Cancelled | Self::Rewrite { .. } => None,
        }
    }
}

/// Rewrites only committed call segments to the effective routed calls.
///
/// The source order is produced by `Generation::tool_calls` in
/// `runtime/driver.rs` and preserved by `RoutedToolBatch` in
/// `runtime/tool_batch_route.rs`. The committed Assistant must use the same
/// id/name pairs as its `ToolResult` records or the next `RequestPlan` correctly
/// rejects the history as unreplayable.
fn assistant_with_effective_calls(assistant: Assistant, batch: &RoutedToolBatch) -> Assistant {
    let mut effective_calls = batch.records().iter().map(ToolRouteRecord::effective_call);
    let content = assistant
        .content()
        .iter()
        .cloned()
        .map(|segment| match segment {
            Segment::ToolCall { call, extensions } => Segment::ToolCall {
                call: effective_calls.next().cloned().unwrap_or(call),
                extensions,
            },
            Segment::Text { .. } | Segment::Thinking { .. } => segment,
        })
        .collect();
    Assistant::new(content, assistant.provider_data().map(<[_]>::to_vec))
        .with_visibility(assistant.visibility())
}

fn tool_call_coord(generation: &Coord, original: &ToolCall, effective: &ToolCall) -> Coord {
    let turn =
        NonZeroU64::new(generation.turn()).expect("before-tool-result callbacks belong to a turn");
    let step = NonZeroU64::new(generation.step_in_turn())
        .expect("before-tool-result callbacks belong to a step");
    let step_in_run = NonZeroU64::new(generation.step_in_run())
        .expect("before-tool-result callbacks carry the run-wide step");
    let generation_index = NonZeroU64::new(generation.generation())
        .expect("before-tool-result callbacks belong to a real generation");
    let step = StepIndex::new(turn, step, step_in_run)
        .expect("the runtime generation coordinate already has a valid step hierarchy");

    // Correlation identity remains the model's original ID while the name
    // reports the tool actually routed after rewrites.
    Coord::at_tool_call(
        generation.session_id().to_owned(),
        generation.run_id().to_owned(),
        step,
        generation_index,
        original.id().as_str().to_owned(),
        effective.name().as_str().to_owned(),
    )
    .expect("normalized routed calls have non-empty IDs and effective names")
}

/// Rewrites, materializes, and atomically commits one routed batch.
///
/// `batch` is the linear source-order proof returned by the route layer
/// (`runtime/tool_batch_route.rs`). `assistant` is the closed record the model
/// produced for this Step; this layer replaces its call segments with the final
/// effective calls, wraps it as [`Item::Assistant`], and places it ahead of the
/// results, because the calls and their results are one replayable exchange.
///
/// Each registration observes the previous registration's rewrite, so the
/// committed record, the outward result event the driver publishes, and any later
/// observation all report the same output. Every adapter receives the callback
/// resources at its full registry index, so a registration that mounts no tool
/// hooks still owns a slot and cannot collapse resource identity.
///
/// Each materialized record keeps the model-assigned call ID of the *original*
/// call, since that is the correlation identity the model will match, and names
/// the *effective* call, since that is the tool that actually ran. Item metadata
/// is deliberately left absent: it is an independent transport channel that is
/// never reconstructed from [`crate::value::tool_call::ToolResult`] output
/// metadata (see `Item`'s metadata transport contract), and the result retains
/// its own metadata presence unchanged.
///
/// Each record takes `assistant`'s own [`item::ModelVisibility`], because the calls
/// and their answers are one exchange and the projection in
/// [`RequestPlan::try_into_request`](crate::runtime::model::RequestPlan::try_into_request) removes
/// exchanges whole. Committing results as [`item::ModelVisibility::Visible`] beneath a
/// hidden record would leave orphan answers that the next Step's projection
/// refuses — the same "never write the damage" rule the atomic append already
/// applies to interruption.
///
/// # Errors
///
/// Returns [`ToolBatchCommitError`] when cancellation is already observable,
/// when any rewrite reports a callback failure or an observed cancellation, or
/// when the single append does not commit. Nothing is appended on any of those
/// paths, so a caller can never observe half of the exchange; a partially
/// rewritten batch is dropped locally and is therefore unobservable too.
#[expect(
    clippy::too_many_arguments,
    reason = "the linear batch plus seven independent frozen commit resources form this internal boundary"
)]
pub(crate) fn commit_tool_batch(
    batch: RoutedToolBatch,
    assistant: Assistant,
    generation_coord: &Coord,
    registry: &hook::RuntimeRegistry,
    resources: &[CallbackResources<'_>],
    snapshot: Arc<StepSnapshot>,
    controller: &TranscriptController<'_>,
    cancellation: &Token,
) -> Result<ToolBatchCommit, ToolBatchCommitError> {
    if cancellation.is_cancelled() {
        return Err(ToolBatchCommitError::Cancelled);
    }

    let assistant = assistant_with_effective_calls(assistant, &batch);
    let records = batch.into_records();
    let mut finalized = Vec::with_capacity(records.len());
    let mut items = Vec::with_capacity(records.len() + 1);
    let visibility = assistant.visibility();
    items.push(Item::Assistant(assistant));
    for (source_index, record) in records.into_iter().enumerate() {
        // `ToolRouteRecord` is produced by the route stage; the
        // pair of calls it retains is the only authority for both the model's
        // correlation ID and the tool that was actually routed.
        let (original_call, effective_call, outcome) = record.into_parts();
        let (mut result, disposition) = outcome.into_parts();
        let callback_coord = tool_call_coord(generation_coord, &original_call, &effective_call);
        for adapter in registry.tool_hooks() {
            let registration_resources = *resources
                .get(adapter.index())
                .expect("before-tool-result resources cover every registry index");
            let callback_resources = registration_resources.with_coord(&callback_coord);
            let decision = adapter
                .invoke_before_tool_result(
                    callback_resources,
                    &snapshot,
                    &effective_call,
                    disposition,
                    &result,
                    cancellation,
                )
                .map_err(|error| ToolBatchCommitError::Rewrite {
                    source_index,
                    error,
                })?;
            match decision {
                ToolResultDecision::Continue => {}
                ToolResultDecision::Modify(modified) => result = modified,
            }
        }
        let item = item::ToolResult::new(
            original_call.id().clone(),
            effective_call.name().clone(),
            result,
            visibility,
            None,
        );
        items.push(Item::ToolResult(item.clone()));
        finalized.push(FinalizedToolCall {
            original_call,
            effective_call,
            disposition,
            item,
        });
    }

    // One append for the whole exchange: the controller reserves, compare-and-set
    // commits, and publishes without any gap.
    let version = controller
        .append_batch(items, cancellation)
        .map_err(ToolBatchCommitError::Controller)?;
    Ok(ToolBatchCommit { version, finalized })
}