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;
#[derive(Clone)]
pub(crate) struct FinalizedToolCall {
original_call: ToolCall,
effective_call: ToolCall,
disposition: CallDisposition,
item: item::ToolResult,
}
impl FinalizedToolCall {
pub(crate) const fn original_call(&self) -> &ToolCall {
&self.original_call
}
pub(crate) const fn effective_call(&self) -> &ToolCall {
&self.effective_call
}
pub(crate) const fn disposition(&self) -> CallDisposition {
self.disposition
}
pub(crate) const fn item(&self) -> &item::ToolResult {
&self.item
}
#[cfg(test)]
pub(crate) fn into_parts(self) -> (ToolCall, ToolCall, CallDisposition, item::ToolResult) {
(
self.original_call,
self.effective_call,
self.disposition,
self.item,
)
}
}
pub(crate) struct ToolBatchCommit {
#[cfg_attr(
not(test),
expect(dead_code, reason = "read only by the test accessors")
)]
version: Version,
finalized: Vec<FinalizedToolCall>,
}
impl ToolBatchCommit {
#[cfg(test)]
pub(crate) const fn version(&self) -> Version {
self.version
}
pub(crate) fn finalized(&self) -> &[FinalizedToolCall] {
&self.finalized
}
#[cfg(test)]
pub(crate) fn into_parts(self) -> (Version, Vec<FinalizedToolCall>) {
(self.version, self.finalized)
}
}
#[derive(Debug)]
pub(crate) enum ToolBatchCommitError {
Cancelled,
Rewrite {
source_index: usize,
error: DispatchError,
},
Controller(ControllerError),
}
impl ToolBatchCommitError {
#[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,
}
}
#[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,
}
}
}
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");
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")
}
#[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() {
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,
});
}
let version = controller
.append_batch(items, cancellation)
.map_err(ToolBatchCommitError::Controller)?;
Ok(ToolBatchCommit { version, finalized })
}