use std::sync::Arc;
use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
use std::time::Duration;
use futures::StreamExt;
use rig_core::message::{CallId, ToolCall};
use tokio::sync::Notify;
use super::MultiTurnStreamItem;
use crate::agent::hook::{AgentHook, HookContext};
use crate::agent::{
AgentBuilder, DispatchAction, DispatchEvent, InvalidToolCallAction, InvalidToolCallContext,
};
use crate::test_utils::{
MockAddTool, MockCompletionModel, MockOperationArgs, MockStreamEvent, MockToolError,
};
use crate::tool::{Tool, ToolContext};
fn started(item: &MultiTurnStreamItem) -> Option<&ToolCall> {
match item {
MultiTurnStreamItem::ToolExecutionStarted { tool_call } => Some(tool_call),
_ => None,
}
}
#[derive(Clone)]
struct WaitTool {
gate: Arc<Notify>,
}
impl Tool for WaitTool {
const NAME: &'static str = "wait";
type Error = MockToolError;
type Args = MockOperationArgs;
type Output = i32;
fn description(&self) -> String {
"Wait for a signal".to_string()
}
fn parameters(&self) -> serde_json::Value {
MockAddTool.parameters()
}
async fn call(
&self,
_context: &mut ToolContext,
_args: Self::Args,
) -> Result<Self::Output, Self::Error> {
self.gate.notified().await;
Ok(0)
}
}
#[derive(Clone)]
struct ObservedAdd {
starts_taken: Arc<AtomicUsize>,
runs: Arc<AtomicUsize>,
late: Arc<AtomicBool>,
}
impl Tool for ObservedAdd {
const NAME: &'static str = "add";
type Error = MockToolError;
type Args = MockOperationArgs;
type Output = i32;
fn description(&self) -> String {
MockAddTool.description()
}
fn parameters(&self) -> serde_json::Value {
MockAddTool.parameters()
}
async fn call(
&self,
_context: &mut ToolContext,
_args: Self::Args,
) -> Result<Self::Output, Self::Error> {
let earlier_runs = self.runs.fetch_add(1, Ordering::SeqCst);
if self.starts_taken.load(Ordering::SeqCst) <= earlier_runs {
self.late.store(true, Ordering::SeqCst);
}
Ok(0)
}
}
fn two_call_model(first: &str, second: &str) -> MockCompletionModel {
MockCompletionModel::from_stream_turns([
vec![
MockStreamEvent::tool_call("part_1", first, serde_json::json!({"x": 1, "y": 2}))
.with_call_id("call_1"),
MockStreamEvent::tool_call("part_2", second, serde_json::json!({"x": 3, "y": 4}))
.with_call_id("call_2"),
MockStreamEvent::final_response_with_total_tokens(4),
],
vec![
MockStreamEvent::text("done"),
MockStreamEvent::final_response_with_total_tokens(6),
],
])
}
#[tokio::test]
async fn a_call_start_reaches_the_consumer_while_its_sibling_still_runs() {
let gate = Arc::new(Notify::new());
let agent = AgentBuilder::new(two_call_model("wait", "add"))
.tool(WaitTool { gate: gate.clone() })
.tool(MockAddTool)
.build();
let mut stream = agent
.prompt("use tools")
.max_turns(3)
.tool_concurrency(2)
.stream();
let mut items = Vec::new();
let drained = tokio::time::timeout(Duration::from_secs(5), async {
while let Some(item) = stream.next().await {
let item = item.expect("the run succeeds");
if started(&item).is_some_and(|call| call.function.name.as_str() == "add") {
gate.notify_one();
}
items.push(item);
}
})
.await;
assert!(
drained.is_ok(),
"the start of `add` must reach the consumer while `wait` still runs"
);
let order: Vec<String> = items
.iter()
.filter_map(|item| match item {
MultiTurnStreamItem::ToolCall { tool_call } => Some(format!("call:{}", tool_call.id)),
MultiTurnStreamItem::ToolExecutionStarted { tool_call } => {
Some(format!("start:{}", tool_call.id))
}
MultiTurnStreamItem::ToolExecutionCommitted { tool_call } => {
Some(format!("ran:{}", tool_call.id))
}
MultiTurnStreamItem::ToolResult { tool_result } => {
Some(format!("result:{}", tool_result.call))
}
_ => None,
})
.collect();
let id = |wire: &str| CallId::from_wire(wire).to_string();
let (one, two) = (id("call_1"), id("call_2"));
assert_eq!(
order,
[
format!("call:{one}"),
format!("call:{two}"),
format!("start:{one}"),
format!("start:{two}"),
format!("ran:{one}"),
format!("result:{one}"),
format!("ran:{two}"),
format!("result:{two}"),
]
);
}
#[tokio::test]
async fn a_sequential_call_start_arrives_before_its_body_runs() {
let tool = ObservedAdd {
starts_taken: Arc::new(AtomicUsize::new(0)),
runs: Arc::new(AtomicUsize::new(0)),
late: Arc::new(AtomicBool::new(false)),
};
let agent = AgentBuilder::new(two_call_model("add", "add"))
.tool(tool.clone())
.build();
let mut stream = agent.prompt("use tools").max_turns(3).stream();
while let Some(item) = stream.next().await {
if started(&item.expect("the run succeeds")).is_some() {
tool.starts_taken.fetch_add(1, Ordering::SeqCst);
}
}
assert_eq!(tool.starts_taken.load(Ordering::SeqCst), 2);
assert_eq!(tool.runs.load(Ordering::SeqCst), 2);
assert!(
!tool.late.load(Ordering::SeqCst),
"a body ran before the consumer took its start"
);
}
struct StopFirstToolCall;
impl AgentHook for StopFirstToolCall {
async fn on_dispatch(&self, _: &HookContext, event: DispatchEvent<'_>) -> DispatchAction {
match event.tool_args() {
Some(args) if args.contains("\"x\":1") => DispatchAction::stop("stop the run"),
_ => DispatchAction::proceed(),
}
}
}
#[tokio::test]
async fn a_call_dropped_by_a_sibling_ending_the_run_reports_no_start() {
let agent = AgentBuilder::new(two_call_model("add", "add"))
.tool(MockAddTool)
.build();
let mut stream = agent
.prompt("use tools")
.max_turns(3)
.add_hook(StopFirstToolCall)
.stream();
let (mut started_ids, mut settled, mut failed) = (Vec::new(), 0, false);
while let Some(item) = stream.next().await {
match item {
Ok(MultiTurnStreamItem::ToolExecutionStarted { tool_call }) => {
started_ids.push(tool_call.id.to_string());
}
Ok(
MultiTurnStreamItem::ToolExecutionCommitted { .. }
| MultiTurnStreamItem::ToolResult { .. },
) => settled += 1,
Ok(_) => {}
Err(_) => failed = true,
}
}
assert!(failed, "the hook ends the run");
assert_eq!(started_ids, [CallId::from_wire("call_1").to_string()]);
assert_eq!(settled, 0, "a failed batch surfaces no commit or result");
}
struct SkipEveryToolCall;
impl AgentHook for SkipEveryToolCall {
async fn on_dispatch(&self, _: &HookContext, event: DispatchEvent<'_>) -> DispatchAction {
match event.tool_args() {
Some(_) => DispatchAction::skip("blocked by policy"),
None => DispatchAction::proceed(),
}
}
}
#[tokio::test]
async fn a_hook_skipped_call_reports_a_start_but_no_commit() {
let model = MockCompletionModel::from_stream_turns([
vec![
MockStreamEvent::tool_call("part_1", "add", serde_json::json!({"x": 1, "y": 2}))
.with_call_id("call_1"),
MockStreamEvent::final_response_with_total_tokens(4),
],
vec![
MockStreamEvent::text("done"),
MockStreamEvent::final_response_with_total_tokens(6),
],
]);
let agent = AgentBuilder::new(model).tool(MockAddTool).build();
let mut stream = agent
.prompt("use tools")
.max_turns(3)
.add_hook(SkipEveryToolCall)
.stream();
let (mut starts, mut commits, mut results) = (0, 0, 0);
while let Some(item) = stream.next().await {
match item.expect("the run succeeds") {
MultiTurnStreamItem::ToolExecutionStarted { .. } => starts += 1,
MultiTurnStreamItem::ToolExecutionCommitted { .. } => commits += 1,
MultiTurnStreamItem::ToolResult { .. } => results += 1,
_ => {}
}
}
assert_eq!((starts, commits, results), (1, 0, 1));
}
struct SkipUnknownTool;
impl AgentHook for SkipUnknownTool {
async fn on_invalid_tool_call(
&self,
_ctx: &HookContext,
_context: &InvalidToolCallContext,
) -> Option<InvalidToolCallAction> {
Some(InvalidToolCallAction::skip("no such tool"))
}
}
#[tokio::test]
async fn a_turn_answered_by_invalid_call_recovery_reports_no_start() {
let agent = AgentBuilder::new(two_call_model("missing", "add"))
.tool(MockAddTool)
.build();
let mut stream = agent
.prompt("use tools")
.max_turns(3)
.add_hook(SkipUnknownTool)
.stream();
let (mut starts, mut results) = (0, 0);
while let Some(item) = stream.next().await {
match item.expect("the run succeeds") {
MultiTurnStreamItem::ToolExecutionStarted { .. } => starts += 1,
MultiTurnStreamItem::ToolResult { .. } => results += 1,
_ => {}
}
}
assert_eq!(starts, 0, "no call of the recovered turn is dispatched");
assert!(results > 0, "the recovered turn is still answered");
}