#![cfg(test)]
use std::collections::VecDeque;
use std::error::Error;
use std::fmt;
use std::future::{Future, ready};
use std::pin::Pin;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::{Arc, Mutex};
use std::task::{Context, Poll};
use crate::cancel::Token;
use futures_core::Stream;
use tokio::sync::Notify;
use super::event::{ToolEmitError, ToolEmitter};
use super::model::{self, Client, CompletionReason, Info, Request, RequestPlan};
use super::tool::*;
use crate::audit;
use crate::opaque::{Envelope, EnvelopeError, Payload};
use crate::redact_tests::{SECRET, assert_redacted, assert_states};
use crate::transcript::item::{Item, ModelVisibility, System};
use crate::transcript::store::{Snapshot, Version};
use crate::value::tool_call::{self, Id, ToolCall, ToolPartError, ToolResult};
fn step_transcript() -> Snapshot {
Snapshot::new(
Version::ZERO,
vec![Item::System(System::new(
"step".to_owned(),
"step top".to_owned(),
ModelVisibility::Visible,
))],
)
}
fn invocation(snapshot: &StepToolSnapshot) -> Invocation {
snapshot.invocation(
Some("session".to_owned()),
Id::new("call".to_owned()),
ToolEmitter::closed(),
)
}
fn descriptor(name: Name) -> Descriptor {
Descriptor::new(
name,
"description".to_owned(),
Payload::copy_from_slice(b"{}"),
)
}
fn hosted_extension(name: &str) -> Envelope {
Envelope::try_new(
"provider".to_owned(),
name.to_owned(),
Payload::copy_from_slice(b"{}"),
)
.unwrap()
}
fn hosted(name: &str) -> Registration {
Registration::hosted(descriptor(local(name)), hosted_extension(name))
}
fn local(name: &str) -> Name {
Name::local(name.to_owned()).unwrap()
}
fn call(name: &str) -> ToolCall {
ToolCall::new(
Id::new("call-1".to_owned()),
tool_call::Name::new(name.to_owned()),
Payload::copy_from_slice(b"{}"),
)
}
struct StringExecutor {
calls: Arc<AtomicUsize>,
outcome: Mutex<Result<String, ExecutorError>>,
}
impl Executor for StringExecutor {
type Output = String;
fn execute(
&self,
_invocation: &Invocation,
_call: &ToolCall,
_cancellation: Token,
) -> impl Future<Output = Result<Self::Output, ExecutorError>> + Send {
self.calls.fetch_add(1, Ordering::SeqCst);
ready(self.outcome.lock().unwrap().clone())
}
}
struct NumberExecutor(Arc<AtomicUsize>);
impl Executor for NumberExecutor {
type Output = usize;
fn execute(
&self,
_invocation: &Invocation,
_call: &ToolCall,
_cancellation: Token,
) -> impl Future<Output = Result<Self::Output, ExecutorError>> + Send {
self.0.fetch_add(1, Ordering::SeqCst);
ready(Ok(7))
}
}
fn string_registration(name: Name, calls: Arc<AtomicUsize>) -> Registration {
Registration::client(
descriptor(name),
Arc::new(StringExecutor {
calls,
outcome: Mutex::new(Ok("mapped".to_owned())),
}),
Arc::new(|output: String| Ok(ToolResult::success_text(output))),
)
}
fn registry_with(registrations: Vec<Registration>) -> Registry {
let mut builder = RegistryBuilder::new();
for registration in registrations {
builder.register(registration);
}
builder.build().unwrap()
}
async fn snapshot(registration: Registration) -> StepToolSnapshot {
registry_with(vec![registration])
.resolve_step(step_transcript(), &Token::new())
.await
.unwrap()
.into_snapshot()
}
#[test]
fn runtime_names_are_nonempty_namespaced_and_unambiguous() {
let plain = Name::local("search".to_owned()).unwrap();
assert_eq!(plain.namespace(), None);
assert_eq!(plain.local_name(), "search");
assert_eq!(plain.canonical(), "search");
let scoped = Name::namespaced("web".to_owned(), "search".to_owned()).unwrap();
assert_eq!(scoped.namespace(), Some("web"));
assert_eq!(scoped.local_name(), "search");
assert_eq!(scoped.canonical(), "web/search");
assert_ne!(plain, scoped);
let cases = [
(
Name::local(String::new()).err().unwrap(),
NameError::EmptyLocal,
"tool local name is empty",
),
(
Name::namespaced(String::new(), "x".to_owned())
.err()
.unwrap(),
NameError::EmptyNamespace,
"tool namespace is empty",
),
(
Name::local("a/b".to_owned()).err().unwrap(),
NameError::ReservedSeparator,
"tool name component contains '/'",
),
(
Name::namespaced("a/b".to_owned(), "c".to_owned())
.err()
.unwrap(),
NameError::ReservedSeparator,
"tool name component contains '/'",
),
];
for (actual, expected, display) in cases {
assert_eq!(actual, expected);
assert_eq!(actual.to_string(), display);
let _: &dyn Error = &actual;
}
}
#[tokio::test]
async fn wire_rendering_and_canonical_parsing_are_inverses_over_the_whole_grammar() {
for name in [
Name::local("search".to_owned()).unwrap(),
Name::namespaced("web".to_owned(), "search".to_owned()).unwrap(),
Name::namespaced("Ünïcode namespace".to_owned(), "with space".to_owned()).unwrap(),
] {
let wire = name.to_wire();
assert_eq!(wire.as_str(), name.canonical());
let recovered = Name::parse_canonical(wire.as_str()).unwrap();
assert_eq!(recovered, name);
assert_eq!(recovered.namespace(), name.namespace());
assert_eq!(recovered.local_name(), name.local_name());
}
for (canonical, expected) in [
("", NameError::EmptyLocal),
("ns/", NameError::EmptyLocal),
("/", NameError::EmptyLocal),
("/x", NameError::EmptyNamespace),
("a/b/c", NameError::ReservedSeparator),
] {
assert_eq!(
Name::parse_canonical(canonical).err().unwrap(),
expected,
"canonical {canonical:?}"
);
}
let registry = registry_with(vec![
hosted("search"),
Registration::hosted(
descriptor(Name::namespaced("web".to_owned(), "search".to_owned()).unwrap()),
hosted_extension("scoped"),
),
]);
let names = registry
.resolve_step(step_transcript(), &Token::new())
.await
.unwrap()
.into_snapshot()
.exposure()
.map(|(descriptor, _)| descriptor.name().canonical().to_owned())
.collect::<Vec<_>>();
assert_eq!(names, ["search", "web/search"]);
}
#[tokio::test]
async fn an_emission_the_name_grammar_rejects_is_still_a_business_result() {
let snapshot = snapshot(hosted("search")).await;
for emitted in ["", "/search", "search/", "a/b/c", "absent"] {
let outcome = snapshot
.execute(&invocation(&snapshot), &call(emitted), &Token::new())
.await
.expect("a name core cannot resolve is a rejection, never a control-path failure");
assert_eq!(outcome.disposition(), CallDisposition::Rejected);
assert!(outcome.result().is_business_error());
assert_eq!(
outcome.result().output().unwrap().user_view(),
Some(format!("unknown tool: {emitted}").as_str()),
"emission {emitted:?} must be reported back exactly as the model spelled it"
);
}
}
#[tokio::test]
async fn builder_owns_fields_freezes_handles_and_exposes_both_lanes() {
let mut description = "description".to_owned();
let name = Name::namespaced("ns".to_owned(), "client".to_owned()).unwrap();
let calls = Arc::new(AtomicUsize::new(0));
let registration = Registration::client(
Descriptor::new(
name.clone(),
description.clone(),
Payload::copy_from_slice(b"{}"),
),
Arc::new(StringExecutor {
calls: Arc::clone(&calls),
outcome: Mutex::new(Ok("ok".to_owned())),
}),
Arc::new(|value: String| Ok(ToolResult::success_text(value))),
);
assert_eq!(registration.lane(), Lane::Client);
assert_eq!(registration.descriptor().name(), &name);
description.push_str(" changed");
let hosted = hosted("hosted");
assert_eq!(hosted.lane(), Lane::Hosted);
let snapshot = snapshot_from(vec![registration, hosted]).await;
let exposed = snapshot.exposure().collect::<Vec<_>>();
assert_eq!(exposed.len(), 2);
assert_eq!(exposed[0].0.description(), "description");
assert_eq!(exposed[0].0.input_schema().as_bytes(), b"{}");
assert_eq!(exposed[1].1, Lane::Hosted);
let model_tools = snapshot.client_model_tools();
assert_eq!(model_tools.len(), 1);
assert_eq!(model_tools[0].name().as_str(), "ns/client");
assert_eq!(model_tools[0].description(), "description");
assert_eq!(model_tools[0].input_schema().as_bytes(), b"{}");
let client_outcome = snapshot
.execute(&invocation(&snapshot), &call("ns/client"), &Token::new())
.await
.unwrap();
assert!(client_outcome.result().has_output());
assert_eq!(
client_outcome.disposition(),
CallDisposition::Executed,
"reaching the executor is the Executed disposition"
);
assert_eq!(calls.load(Ordering::SeqCst), 1);
assert_eq!(
snapshot
.execute(&invocation(&snapshot), &call("hosted"), &Token::new())
.await
.err()
.unwrap(),
ExecutionError::Hosted("hosted".to_owned())
);
}
async fn snapshot_from(registrations: Vec<Registration>) -> StepToolSnapshot {
registry_with(registrations)
.resolve_step(step_transcript(), &Token::new())
.await
.unwrap()
.into_snapshot()
}
#[derive(Debug)]
struct HarnessModelError;
impl fmt::Display for HarnessModelError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str("model harness failure")
}
}
impl Error for HarnessModelError {}
struct HarnessStream(VecDeque<Result<model::Event, HarnessModelError>>);
impl Stream for HarnessStream {
type Item = Result<model::Event, HarnessModelError>;
fn poll_next(mut self: Pin<&mut Self>, _context: &mut Context<'_>) -> Poll<Option<Self::Item>> {
Poll::Ready(self.0.pop_front())
}
}
struct HarnessModel {
calls: Arc<AtomicUsize>,
expected_tools: usize,
expected_extensions: usize,
}
impl Client for HarnessModel {
type Error = HarnessModelError;
type Stream = HarnessStream;
fn info(&self) -> Info {
Info::new("harness".to_owned(), 1024).with_tools(true)
}
fn generate(
&self,
request: Request,
) -> impl Future<Output = Result<Self::Stream, Self::Error>> + Send {
self.calls.fetch_add(1, Ordering::SeqCst);
assert_eq!(request.tools().len(), self.expected_tools);
assert_eq!(request.extensions().len(), self.expected_extensions);
ready(Ok(HarnessStream(VecDeque::from([Ok(
model::Event::Done {
finish_reason: "stop".to_owned(),
completion: CompletionReason::Stop,
provider_data: Vec::new(),
},
)]))))
}
}
#[tokio::test]
async fn one_snapshot_populates_request_lanes_and_hosted_never_dispatches_locally() {
let executor_calls = Arc::new(AtomicUsize::new(0));
let snapshot = snapshot_from(vec![
string_registration(local("client"), Arc::clone(&executor_calls)),
hosted("hosted"),
])
.await;
let mut plan = RequestPlan::new();
snapshot.apply_to_plan(&mut plan);
let request = plan.try_into_request(Vec::new()).unwrap();
assert_eq!(request.tools()[0].name().as_str(), "client");
assert_eq!(request.extensions()[0].namespace(), "provider");
assert_eq!(request.extensions()[0].kind(), "hosted");
let model_calls = Arc::new(AtomicUsize::new(0));
let model = HarnessModel {
calls: Arc::clone(&model_calls),
expected_tools: 1,
expected_extensions: 1,
};
let _events = model.generate(request).await.unwrap();
assert_eq!(model_calls.load(Ordering::SeqCst), 1);
assert_eq!(
snapshot
.execute(&invocation(&snapshot), &call("hosted"), &Token::new())
.await
.err()
.unwrap(),
ExecutionError::Hosted("hosted".to_owned())
);
assert_eq!(executor_calls.load(Ordering::SeqCst), 0);
}
#[tokio::test]
async fn generic_outputs_route_only_to_their_statically_paired_mappers() {
let strings = Arc::new(AtomicUsize::new(0));
let numbers = Arc::new(AtomicUsize::new(0));
let string = string_registration(local("string"), Arc::clone(&strings));
let number = Registration::client(
descriptor(local("number")),
Arc::new(NumberExecutor(Arc::clone(&numbers))),
Arc::new(|value: usize| Ok(ToolResult::success_text(format!("number:{value}")))),
);
let snapshot = snapshot_from(vec![string, number]).await;
let string_result = snapshot
.execute(&invocation(&snapshot), &call("string"), &Token::new())
.await
.unwrap();
let number_result = snapshot
.execute(&invocation(&snapshot), &call("number"), &Token::new())
.await
.unwrap();
assert_eq!(
string_result.result().output().unwrap().user_view(),
Some("mapped")
);
assert_eq!(
number_result.result().output().unwrap().user_view(),
Some("number:7")
);
assert_eq!(string_result.disposition(), CallDisposition::Executed);
assert_eq!(number_result.disposition(), CallDisposition::Executed);
let (owned_result, owned_disposition) = string_result.into_parts();
assert_eq!(owned_result.output().unwrap().user_view(), Some("mapped"));
assert_eq!(owned_disposition, CallDisposition::Executed);
assert_eq!(strings.load(Ordering::SeqCst), 1);
assert_eq!(numbers.load(Ordering::SeqCst), 1);
}
#[test]
fn static_collision_is_typed_and_build_has_no_winner() {
let calls = Arc::new(AtomicUsize::new(0));
let mut builder = RegistryBuilder::new();
builder
.register(string_registration(local("same"), Arc::clone(&calls)))
.register(string_registration(local("same"), calls));
let error = match builder.build() {
Ok(_) => panic!("duplicate static name unexpectedly built"),
Err(error) => error,
};
assert_eq!(error, RegistryError::StaticCollision(local("same")));
assert_eq!(error.to_string(), "duplicate static tool: same");
let _: &dyn Error = &error;
}
struct CountingProvider {
resolutions: Arc<AtomicUsize>,
resolution: Mutex<Option<ProviderResolution>>,
repeat: Option<Registration>,
observed: Arc<Mutex<Vec<(Version, bool)>>>,
}
impl Provider for CountingProvider {
fn resolve<'a>(
&'a self,
transcript: &'a Snapshot,
cancellation: Token,
) -> Pin<Box<dyn Future<Output = ProviderResolution> + Send + 'a>> {
self.resolutions.fetch_add(1, Ordering::SeqCst);
self.observed
.lock()
.unwrap()
.push((transcript.version(), cancellation.is_cancelled()));
Box::pin(ready(if let Some(registration) = &self.repeat {
ProviderResolution::success(vec![registration.clone()])
} else {
self.resolution.lock().unwrap().take().unwrap()
}))
}
}
fn provider_once(resolution: ProviderResolution) -> (Arc<AtomicUsize>, Arc<dyn Provider>) {
let resolutions = Arc::new(AtomicUsize::new(0));
let provider: Arc<dyn Provider> = Arc::new(CountingProvider {
resolutions: Arc::clone(&resolutions),
resolution: Mutex::new(Some(resolution)),
repeat: None,
observed: Arc::new(Mutex::new(Vec::new())),
});
(resolutions, provider)
}
#[tokio::test]
async fn provider_resolves_once_per_step_and_fresh_on_next_step() {
let resolutions = Arc::new(AtomicUsize::new(0));
let observed = Arc::new(Mutex::new(Vec::new()));
let provider: Arc<dyn Provider> = Arc::new(CountingProvider {
resolutions: Arc::clone(&resolutions),
resolution: Mutex::new(None),
repeat: Some(hosted("dynamic")),
observed: Arc::clone(&observed),
});
let mut builder = RegistryBuilder::new();
builder.provider(provider);
let registry = builder.build().unwrap();
let first = registry
.resolve_step(step_transcript(), &Token::new())
.await
.unwrap();
assert_eq!(resolutions.load(Ordering::SeqCst), 1);
assert_eq!(first.snapshot().exposure().len(), 1);
let second = registry
.resolve_step(step_transcript(), &Token::new())
.await
.unwrap();
assert_eq!(resolutions.load(Ordering::SeqCst), 2);
assert_eq!(second.snapshot().exposure().len(), 1);
}
struct CatalogueRequest(Arc<AtomicUsize>);
impl Drop for CatalogueRequest {
fn drop(&mut self) {
self.0.fetch_add(1, Ordering::SeqCst);
}
}
struct AwaitingCatalogue {
started: Arc<Notify>,
release: Arc<Notify>,
resolutions: Arc<AtomicUsize>,
releases: Arc<AtomicUsize>,
executor_calls: Arc<AtomicUsize>,
}
impl Provider for AwaitingCatalogue {
fn resolve<'a>(
&'a self,
_transcript: &'a Snapshot,
_cancellation: Token,
) -> Pin<Box<dyn Future<Output = ProviderResolution> + Send + 'a>> {
Box::pin(async move {
let _in_flight = CatalogueRequest(Arc::clone(&self.releases));
self.started.notify_one();
self.release.notified().await;
self.resolutions.fetch_add(1, Ordering::SeqCst);
ProviderResolution::success(vec![string_registration(
local("catalogued"),
Arc::clone(&self.executor_calls),
)])
})
}
}
fn awaiting_catalogue() -> (Arc<AwaitingCatalogue>, Registry) {
let provider = Arc::new(AwaitingCatalogue {
started: Arc::new(Notify::new()),
release: Arc::new(Notify::new()),
resolutions: Arc::new(AtomicUsize::new(0)),
releases: Arc::new(AtomicUsize::new(0)),
executor_calls: Arc::new(AtomicUsize::new(0)),
});
let mut builder = RegistryBuilder::new();
builder.provider(Arc::clone(&provider) as Arc<dyn Provider>);
let registry = builder.build().unwrap();
(provider, registry)
}
#[tokio::test]
async fn a_step_waits_for_its_catalogue_and_routes_the_tool_it_just_learned_about() {
let (provider, registry) = awaiting_catalogue();
let resolving = tokio::spawn(async move {
registry
.resolve_step(step_transcript(), &Token::new())
.await
.unwrap()
.into_snapshot()
});
provider.started.notified().await;
assert_eq!(provider.resolutions.load(Ordering::SeqCst), 0);
provider.release.notify_one();
let snapshot = resolving.await.unwrap();
let exposed = snapshot
.exposure()
.map(|(descriptor, _)| descriptor.name().canonical().to_owned())
.collect::<Vec<_>>();
assert_eq!(
exposed,
["catalogued"],
"the model is told about the entry this Step waited for"
);
let outcome = snapshot
.execute(&invocation(&snapshot), &call("catalogued"), &Token::new())
.await
.unwrap();
assert_eq!(outcome.disposition(), CallDisposition::Executed);
assert!(outcome.result().has_output());
assert_eq!(provider.executor_calls.load(Ordering::SeqCst), 1);
assert_eq!(provider.resolutions.load(Ordering::SeqCst), 1);
assert_eq!(provider.releases.load(Ordering::SeqCst), 1);
}
#[tokio::test]
async fn dropping_a_parked_resolution_releases_the_provider_and_resolves_nothing() {
let (provider, registry) = awaiting_catalogue();
let cancellation = Token::new();
let mut resolving = Box::pin(registry.resolve_step(step_transcript(), &cancellation));
tokio::select! {
biased;
_resolved = &mut resolving => panic!("a resolution parked on its catalogue cannot complete"),
() = provider.started.notified() => {}
}
assert_eq!(provider.releases.load(Ordering::SeqCst), 0);
drop(resolving);
assert_eq!(
provider.releases.load(Ordering::SeqCst),
1,
"dropping the resolution releases the in-flight catalogue request"
);
assert_eq!(
provider.resolutions.load(Ordering::SeqCst),
0,
"and no resolution was produced for the Step to act on"
);
}
#[test]
#[should_panic(expected = "resolves on its first poll")]
fn the_provider_free_test_helper_refuses_a_registry_that_would_park() {
let (_provider, registry) = awaiting_catalogue();
let _resolved =
registry.resolve_step_without_providers(step_transcript(), &Token::new(), &ExposeAll);
}
#[tokio::test]
async fn providers_snapshot_and_invocations_share_one_frozen_transcript_view() {
let step_version = Version::from_u64(9);
let transcript = Snapshot::new(
step_version,
vec![Item::System(System::new(
"step".to_owned(),
"frozen".to_owned(),
ModelVisibility::Visible,
))],
);
let cancellation = Token::new();
let first_observed = Arc::new(Mutex::new(Vec::new()));
let second_observed = Arc::new(Mutex::new(Vec::new()));
let mut builder = RegistryBuilder::new();
builder
.register(string_registration(
local("shared"),
Arc::new(AtomicUsize::new(0)),
))
.provider(Arc::new(CountingProvider {
resolutions: Arc::new(AtomicUsize::new(0)),
resolution: Mutex::new(None),
repeat: Some(hosted("first-dynamic")),
observed: Arc::clone(&first_observed),
}))
.provider(Arc::new(CountingProvider {
resolutions: Arc::new(AtomicUsize::new(0)),
resolution: Mutex::new(None),
repeat: Some(hosted("second-dynamic")),
observed: Arc::clone(&second_observed),
}));
let snapshot = builder
.build()
.unwrap()
.resolve_step(transcript, &cancellation)
.await
.unwrap()
.into_snapshot();
assert_eq!(
*first_observed.lock().unwrap(),
vec![(step_version, false)],
"every provider receives the frozen Step-top transcript and token"
);
assert_eq!(
*second_observed.lock().unwrap(),
vec![(step_version, false)]
);
assert_eq!(snapshot.transcript().version(), step_version);
assert_eq!(snapshot.transcript().items().len(), 1);
let first = invocation(&snapshot);
let second = snapshot.invocation(None, Id::new("other".to_owned()), ToolEmitter::closed());
assert_eq!(first.transcript().version(), step_version);
assert_eq!(second.transcript().version(), step_version);
assert!(first.transcript().shares_items_with(snapshot.transcript()));
assert!(second.transcript().shares_items_with(snapshot.transcript()));
assert_eq!(first.session_id(), Some("session"));
assert_eq!(second.session_id(), None);
assert_eq!(first.call_id().as_str(), "call");
assert_eq!(second.call_id().as_str(), "other");
assert_eq!(
first
.emitter()
.emit_audit(audit::Event::new("tool.fact".to_owned(), None))
.await,
Err(ToolEmitError::Closed)
);
}
struct CountingCorrection(Arc<AtomicUsize>);
impl ExposureFilter for CountingCorrection {
fn exposed(&self, descriptor: &Descriptor, _lane: Lane) -> bool {
self.0.fetch_add(1, Ordering::SeqCst);
descriptor.name().local_name() != "hidden"
}
}
async fn collision_error(
static_entries: Vec<Registration>,
providers: Vec<Arc<dyn Provider>>,
tool_name: &str,
model_calls: Arc<AtomicUsize>,
) -> StepResolutionError {
let mut builder = RegistryBuilder::new();
for entry in static_entries {
builder.register(entry);
}
for provider in providers {
builder.provider(provider);
}
let registry = builder.build().unwrap();
let resolution = match registry
.resolve_step(step_transcript(), &Token::new())
.await
{
Ok(resolution) => resolution,
Err(error) => return error,
};
let snapshot = resolution.into_snapshot();
let expected_tools = snapshot.client_model_tools().len();
let expected_extensions = snapshot.hosted_model_extensions().len();
let mut plan = RequestPlan::new();
snapshot.apply_to_plan(&mut plan);
let request = plan.try_into_request(Vec::new()).unwrap();
let model = HarnessModel {
calls: model_calls,
expected_tools,
expected_extensions,
};
let _events = model.generate(request).await.unwrap();
let _result = snapshot
.execute(&invocation(&snapshot), &call(tool_name), &Token::new())
.await;
panic!("collision unexpectedly reached the model/executor harness")
}
#[tokio::test]
async fn every_dynamic_collision_precedes_real_model_and_execute_side_effects() {
let model_calls = Arc::new(AtomicUsize::new(0));
let execute_calls = Arc::new(AtomicUsize::new(0));
let (_static_count, static_provider) =
provider_once(ProviderResolution::success(vec![string_registration(
local("static"),
Arc::clone(&execute_calls),
)]));
let error = collision_error(
vec![string_registration(
local("static"),
Arc::clone(&execute_calls),
)],
vec![static_provider],
"static",
Arc::clone(&model_calls),
)
.await;
assert_eq!(error, StepResolutionError::Collision(local("static")));
let (_intra_count, intra_provider) = provider_once(ProviderResolution::success(vec![
string_registration(local("intra"), Arc::clone(&execute_calls)),
string_registration(local("intra"), Arc::clone(&execute_calls)),
]));
let error = collision_error(
Vec::new(),
vec![intra_provider],
"intra",
Arc::clone(&model_calls),
)
.await;
assert_eq!(error, StepResolutionError::Collision(local("intra")));
let (_left_count, left) =
provider_once(ProviderResolution::success(vec![string_registration(
local("inter"),
Arc::clone(&execute_calls),
)]));
let (_right_count, right) =
provider_once(ProviderResolution::success(vec![string_registration(
local("inter"),
Arc::clone(&execute_calls),
)]));
let error = collision_error(
Vec::new(),
vec![left, right],
"inter",
Arc::clone(&model_calls),
)
.await;
assert_eq!(error, StepResolutionError::Collision(local("inter")));
assert_eq!(error.to_string(), "Step tool collision: inter");
assert_eq!(model_calls.load(Ordering::SeqCst), 0);
assert_eq!(execute_calls.load(Ordering::SeqCst), 0);
let _: &dyn Error = &error;
}
#[tokio::test]
async fn failed_provider_discards_partial_set_and_other_sources_survive() {
let partial = hosted("static");
let (failed_count, failed) = provider_once(ProviderResolution::failed(
vec![partial],
ProviderError::new("offline".to_owned()),
));
let (good_count, good) = provider_once(ProviderResolution::success(vec![hosted("dynamic")]));
let mut builder = RegistryBuilder::new();
builder
.register(hosted("static"))
.provider(failed)
.provider(good);
let resolution = builder
.build()
.unwrap()
.resolve_step(step_transcript(), &Token::new())
.await
.unwrap();
assert_eq!(failed_count.load(Ordering::SeqCst), 1);
assert_eq!(good_count.load(Ordering::SeqCst), 1);
assert_eq!(resolution.provider_errors().len(), 1);
assert_eq!(resolution.provider_errors()[0].to_string(), "offline");
let names = resolution
.snapshot()
.exposure()
.map(|(descriptor, _)| descriptor.name().canonical())
.collect::<Vec<_>>();
assert_eq!(names, ["static", "dynamic"]);
}
#[tokio::test]
async fn host_correction_hides_model_and_router_together_after_validation() {
let corrections = Arc::new(AtomicUsize::new(0));
let correction = CountingCorrection(Arc::clone(&corrections));
let registry = registry_with(vec![hosted("visible"), hosted("hidden")]);
let snapshot = registry
.resolve_step_filtered(step_transcript(), &Token::new(), &correction)
.await
.unwrap()
.into_snapshot();
assert_eq!(corrections.load(Ordering::SeqCst), 2);
assert_eq!(snapshot.exposure().len(), 1);
let hidden = snapshot
.execute(&invocation(&snapshot), &call("hidden"), &Token::new())
.await
.expect("a corrected-away tool is a business rejection, never fatal");
assert_eq!(hidden.disposition(), CallDisposition::Rejected);
assert!(hidden.result().is_business_error());
assert_eq!(
hidden.result().output().unwrap().user_view(),
Some("unknown tool: hidden")
);
}
#[tokio::test]
async fn cancellation_observed_before_routing_never_enters_executor() {
let calls = Arc::new(AtomicUsize::new(0));
let snapshot = snapshot(string_registration(local("cancel"), Arc::clone(&calls))).await;
let cancellation = Token::new();
cancellation.cancel();
let error = snapshot
.execute(&invocation(&snapshot), &call("cancel"), &cancellation)
.await
.expect_err("pre-routing cancellation is fatal");
assert_eq!(error, ExecutionError::Cancelled);
assert_eq!(calls.load(Ordering::SeqCst), 0);
}
struct ExecutionBarrier {
started: Notify,
release: Notify,
dropped_after_cancellation: AtomicUsize,
}
struct ExecutionDropProbe {
barrier: Arc<ExecutionBarrier>,
cancellation: Token,
}
impl Drop for ExecutionDropProbe {
fn drop(&mut self) {
if self.cancellation.is_cancelled() {
self.barrier
.dropped_after_cancellation
.fetch_add(1, Ordering::SeqCst);
}
}
}
struct BarrierExecutor {
barrier: Arc<ExecutionBarrier>,
outcome: Result<String, ExecutorError>,
}
impl Executor for BarrierExecutor {
type Output = String;
async fn execute(
&self,
_invocation: &Invocation,
_call: &ToolCall,
cancellation: Token,
) -> Result<Self::Output, ExecutorError> {
let _drop_probe = ExecutionDropProbe {
barrier: Arc::clone(&self.barrier),
cancellation,
};
self.barrier.started.notify_one();
self.barrier.release.notified().await;
self.outcome.clone()
}
}
async fn barrier_snapshot(
outcome: Result<String, ExecutorError>,
mapper_calls: Arc<AtomicUsize>,
) -> (StepToolSnapshot, Arc<ExecutionBarrier>) {
let barrier = Arc::new(ExecutionBarrier {
started: Notify::new(),
release: Notify::new(),
dropped_after_cancellation: AtomicUsize::new(0),
});
let registration = Registration::client(
descriptor(local("barrier")),
Arc::new(BarrierExecutor {
barrier: Arc::clone(&barrier),
outcome,
}),
Arc::new(move |output: String| {
mapper_calls.fetch_add(1, Ordering::SeqCst);
Ok(ToolResult::success_text(output))
}),
);
(snapshot(registration).await, barrier)
}
fn spawn_barrier_execution(
snapshot: StepToolSnapshot,
cancellation: Token,
) -> tokio::task::JoinHandle<Result<ExecutionOutcome, ExecutionError>> {
tokio::spawn(async move {
snapshot
.execute(&invocation(&snapshot), &call("barrier"), &cancellation)
.await
})
}
#[tokio::test]
async fn cancellation_before_executor_completion_drops_error_without_business_result() {
let mapper_calls = Arc::new(AtomicUsize::new(0));
let (snapshot, barrier) = barrier_snapshot(
Err(ExecutorError::new("late error".to_owned())),
Arc::clone(&mapper_calls),
)
.await;
let cancellation = Token::new();
let task = spawn_barrier_execution(snapshot, cancellation.clone());
barrier.started.notified().await;
cancellation.cancel();
let result = tokio::time::timeout(std::time::Duration::from_secs(1), task)
.await
.expect("cancelled route must not await its executor")
.unwrap();
assert_eq!(result.err().unwrap(), ExecutionError::Cancelled);
assert_eq!(mapper_calls.load(Ordering::SeqCst), 0);
assert_eq!(barrier.dropped_after_cancellation.load(Ordering::SeqCst), 1);
}
#[tokio::test]
async fn simultaneous_executor_completion_and_cancellation_prefers_cancellation() {
let mapper_calls = Arc::new(AtomicUsize::new(0));
let (snapshot, barrier) =
barrier_snapshot(Ok("late success".to_owned()), Arc::clone(&mapper_calls)).await;
let cancellation = Token::new();
let task = spawn_barrier_execution(snapshot, cancellation.clone());
barrier.started.notified().await;
cancellation.cancel();
barrier.release.notify_one();
assert_eq!(
task.await.unwrap().err().unwrap(),
ExecutionError::Cancelled
);
assert_eq!(mapper_calls.load(Ordering::SeqCst), 0);
assert_eq!(barrier.dropped_after_cancellation.load(Ordering::SeqCst), 1);
}
#[tokio::test]
async fn executor_completion_before_cancellation_materializes_success_once() {
let mapper_calls = Arc::new(AtomicUsize::new(0));
let (snapshot, barrier) =
barrier_snapshot(Ok("completed".to_owned()), Arc::clone(&mapper_calls)).await;
let cancellation = Token::new();
let task = spawn_barrier_execution(snapshot, cancellation.clone());
barrier.started.notified().await;
barrier.release.notify_one();
let result = task.await.unwrap().unwrap();
cancellation.cancel();
assert_eq!(
result.result().output().unwrap().user_view(),
Some("completed")
);
assert_eq!(result.disposition(), CallDisposition::Executed);
assert_eq!(mapper_calls.load(Ordering::SeqCst), 1);
assert_eq!(barrier.dropped_after_cancellation.load(Ordering::SeqCst), 0);
}
struct PendingBarrier {
started: Notify,
dropped: AtomicUsize,
}
struct PendingDropProbe(Arc<PendingBarrier>);
impl Drop for PendingDropProbe {
fn drop(&mut self) {
self.0.dropped.fetch_add(1, Ordering::SeqCst);
}
}
struct PendingExecutor(Arc<PendingBarrier>);
impl Executor for PendingExecutor {
type Output = String;
async fn execute(
&self,
_invocation: &Invocation,
_call: &ToolCall,
_cancellation: Token,
) -> Result<Self::Output, ExecutorError> {
let _drop_probe = PendingDropProbe(Arc::clone(&self.0));
self.0.started.notify_one();
std::future::pending().await
}
}
#[tokio::test]
async fn cancellation_drops_permanently_pending_executor_that_ignores_token() {
let mapper_calls = Arc::new(AtomicUsize::new(0));
let barrier = Arc::new(PendingBarrier {
started: Notify::new(),
dropped: AtomicUsize::new(0),
});
let registration = Registration::client(
descriptor(local("pending")),
Arc::new(PendingExecutor(Arc::clone(&barrier))),
Arc::new({
let mapper_calls = Arc::clone(&mapper_calls);
move |output: String| {
mapper_calls.fetch_add(1, Ordering::SeqCst);
Ok(ToolResult::success_text(output))
}
}),
);
let snapshot = snapshot(registration).await;
let cancellation = Token::new();
let task_cancellation = cancellation.clone();
let task = tokio::spawn(async move {
snapshot
.execute(&invocation(&snapshot), &call("pending"), &task_cancellation)
.await
});
let result = tokio::time::timeout(std::time::Duration::from_secs(1), async {
barrier.started.notified().await;
cancellation.cancel();
task.await.unwrap()
})
.await
.expect("cancelled route must promptly drop a permanently pending executor");
assert_eq!(result.err().unwrap(), ExecutionError::Cancelled);
assert_eq!(barrier.dropped.load(Ordering::SeqCst), 1);
assert_eq!(mapper_calls.load(Ordering::SeqCst), 0);
}
struct ClosedResultExecutor(ToolResult);
impl Executor for ClosedResultExecutor {
type Output = ToolResult;
fn execute(
&self,
_invocation: &Invocation,
_call: &ToolCall,
_cancellation: Token,
) -> impl Future<Output = Result<Self::Output, ExecutorError>> + Send {
ready(Ok(self.0.clone()))
}
}
#[tokio::test]
async fn mapper_preserves_every_closed_result_state() {
let registrations = [
("none", ToolResult::no_output()),
("success", ToolResult::success_text("ok".to_owned())),
("business", ToolResult::error_text("no".to_owned())),
];
for (name, expected) in registrations {
let registration = Registration::client(
descriptor(local(name)),
Arc::new(ClosedResultExecutor(expected.clone())),
Arc::new(Ok),
);
let closed_snapshot = snapshot(registration).await;
let actual = closed_snapshot
.execute(&invocation(&closed_snapshot), &call(name), &Token::new())
.await
.unwrap();
assert_eq!(actual.result().has_output(), expected.has_output());
assert_eq!(
actual.result().is_business_error(),
expected.is_business_error()
);
assert_eq!(actual.disposition(), CallDisposition::Executed);
}
}
#[tokio::test]
async fn ordinary_executor_error_is_a_business_result() {
let calls = Arc::new(AtomicUsize::new(0));
let registration = Registration::client(
descriptor(local("fallible")),
Arc::new(StringExecutor {
calls: Arc::clone(&calls),
outcome: Mutex::new(Err(ExecutorError::new("ordinary".to_owned()))),
}),
Arc::new(|value: String| Ok(ToolResult::success_text(value))),
);
let fallible_snapshot = snapshot(registration).await;
let outcome = fallible_snapshot
.execute(
&invocation(&fallible_snapshot),
&call("fallible"),
&Token::new(),
)
.await
.unwrap();
assert!(outcome.result().is_business_error());
assert_eq!(
outcome.result().output().unwrap().user_view(),
Some("ordinary")
);
assert_eq!(
outcome.disposition(),
CallDisposition::Executed,
"an ordinary executor error still entered execution"
);
assert_eq!(calls.load(Ordering::SeqCst), 1);
}
#[tokio::test]
async fn every_mapper_error_class_is_fatal_and_preserved() {
let errors = [
MappingError::InvalidPresence("presence".to_owned()),
MappingError::UnsupportedMetadata("metadata".to_owned()),
MappingError::ToolPart(ToolPartError::UnknownKind(99)),
MappingError::OpaqueEnvelope(EnvelopeError::InvalidJson),
MappingError::Protocol("protocol".to_owned()),
];
let displays = [
"invalid output presence: presence",
"unsupported metadata: metadata",
"invalid tool part: unknown tool part kind 99",
"invalid opaque envelope: opaque envelope data is not valid JSON",
"tool mapping protocol failure: protocol",
];
for (index, expected) in errors.into_iter().enumerate() {
let calls = Arc::new(AtomicUsize::new(0));
let mapped = expected.clone();
let registration = Registration::client(
descriptor(local(&format!("mapper-{index}"))),
Arc::new(NumberExecutor(Arc::clone(&calls))),
Arc::new(move |_value: usize| Err(mapped.clone())),
);
let mapper_snapshot = snapshot(registration).await;
let error = mapper_snapshot
.execute(
&invocation(&mapper_snapshot),
&call(&format!("mapper-{index}")),
&Token::new(),
)
.await
.err()
.unwrap();
assert_eq!(error, ExecutionError::Mapping(expected.clone()));
assert_eq!(expected.to_string(), displays[index]);
assert_eq!(calls.load(Ordering::SeqCst), 1);
let _: &dyn Error = &expected;
}
}
#[test]
fn tool_error_displays_are_stable() {
let run_errors = [
ExecutionError::Hosted("x".to_owned()),
ExecutionError::Cancelled,
ExecutionError::Mapping(MappingError::Protocol("x".to_owned())),
];
let expected = [
"hosted tool is not locally dispatchable: x",
"tool run cancelled",
"tool output mapping failed: tool mapping protocol failure: x",
];
for (error, expected) in run_errors.iter().zip(expected) {
assert_eq!(error.to_string(), expected);
let _: &dyn Error = error;
}
}
#[test]
fn tool_mapping_and_run_failures_hand_back_the_value_underneath_them() {
let envelope = MappingError::OpaqueEnvelope(EnvelopeError::EmptyNamespace);
assert_eq!(
envelope
.source()
.and_then(|cause| cause.downcast_ref::<EnvelopeError>())
.copied(),
Some(EnvelopeError::EmptyNamespace)
);
let part = MappingError::ToolPart(ToolPartError::UnknownKind(9));
assert_eq!(
part.source()
.and_then(|cause| cause.downcast_ref::<ToolPartError>())
.copied(),
Some(ToolPartError::UnknownKind(9))
);
for leaf in [
MappingError::InvalidPresence("x".to_owned()),
MappingError::UnsupportedMetadata("x".to_owned()),
MappingError::Protocol("x".to_owned()),
] {
assert!(leaf.source().is_none(), "{leaf} is its own whole content");
}
let run = ExecutionError::Mapping(part);
let mapping = run
.source()
.and_then(|cause| cause.downcast_ref::<MappingError>())
.expect("the run failure retains the mapping failure");
assert!(
mapping
.source()
.and_then(|cause| cause.downcast_ref::<ToolPartError>())
.is_some()
);
for leaf in [
ExecutionError::Hosted("x".to_owned()),
ExecutionError::Cancelled,
] {
assert!(leaf.source().is_none(), "{leaf} is its own whole content");
}
}
#[tokio::test]
async fn an_executor_error_retains_its_cause_without_changing_the_business_result() {
let cause = MappingError::OpaqueEnvelope(EnvelopeError::EmptyNamespace);
let failure =
ExecutorError::new("reading the manifest failed".to_owned()).with_source(cause.clone());
assert_eq!(
failure
.source()
.and_then(|inner| inner.downcast_ref::<MappingError>()),
Some(&cause)
);
assert!(
failure
.source()
.and_then(Error::source)
.and_then(|inner| inner.downcast_ref::<EnvelopeError>())
.is_some()
);
assert!(
ExecutorError::new("bare".to_owned()).source().is_none(),
"a diagnostic with nothing underneath it retains nothing"
);
assert_eq!(
failure,
ExecutorError::new("reading the manifest failed".to_owned())
);
assert_ne!(failure, ExecutorError::new("something else".to_owned()));
assert_eq!(
format!("{failure:?}"),
r#"ExecutorError("reading the manifest failed", "invalid opaque envelope: opaque envelope namespace is empty", "opaque envelope namespace is empty")"#
);
assert_eq!(failure.to_string(), "reading the manifest failed");
let registration = Registration::client(
descriptor(local("fallible")),
Arc::new(StringExecutor {
calls: Arc::new(AtomicUsize::new(0)),
outcome: Mutex::new(Err(failure)),
}),
Arc::new(|value: String| Ok(ToolResult::success_text(value))),
);
let fallible_snapshot = snapshot(registration).await;
let outcome = fallible_snapshot
.execute(
&invocation(&fallible_snapshot),
&call("fallible"),
&Token::new(),
)
.await
.unwrap();
assert_eq!(
outcome.result().output().unwrap().user_view(),
Some("reading the manifest failed"),
"the retained cause is not appended to model-visible content"
);
}
#[test]
fn provider_error_preserves_its_typed_source_and_message_semantics() {
let cause = MappingError::OpaqueEnvelope(EnvelopeError::EmptyNamespace);
let failure =
ProviderError::new("catalogue lookup failed".to_owned()).with_source(cause.clone());
let cloned = failure.clone();
assert_eq!(cloned, failure);
assert_eq!(
failure,
ProviderError::new("catalogue lookup failed".to_owned()),
"equality compares the stable operator message only"
);
assert_ne!(
failure,
ProviderError::new("catalogue authorization failed".to_owned())
);
assert_eq!(failure.to_string(), "catalogue lookup failed");
assert_redacted(&failure);
assert_eq!(
format!("{failure:?}"),
r#"ProviderError("catalogue lookup failed", "invalid opaque envelope: opaque envelope namespace is empty", "opaque envelope namespace is empty")"#
);
assert_eq!(
failure
.source()
.and_then(|inner| inner.downcast_ref::<MappingError>()),
Some(&cause)
);
assert!(
cloned
.source()
.and_then(Error::source)
.and_then(|inner| inner.downcast_ref::<EnvelopeError>())
.is_some(),
"Clone retains the complete Arc-backed source chain"
);
assert!(
ProviderError::new("bare".to_owned()).source().is_none(),
"an error without an attached cause is a leaf"
);
}
#[test]
fn descriptor_debug_names_the_tool_and_sizes_the_schema() {
let secret = Descriptor::new(
local("search"),
SECRET.to_owned(),
Payload::copy_from_slice(SECRET.as_bytes()),
);
assert_redacted(&secret);
assert_states(
&secret,
&[
r#"canonical: "search""#,
"description: <21 bytes>",
"input_schema: <21 bytes>",
],
);
}
#[test]
fn registration_debug_reports_the_lane_by_the_executor_it_holds() {
let client = Registration::client(
descriptor(local("search")),
Arc::new(StringExecutor {
calls: Arc::new(AtomicUsize::new(0)),
outcome: Mutex::new(Ok(SECRET.to_owned())),
}),
Arc::new(|output: String| Ok(ToolResult::success_text(output))),
);
assert_redacted(&client);
assert_states(&client, &["executor: <present>", "hosted_extension: None"]);
let hosted = hosted("compat");
assert_redacted(&hosted);
assert_states(&hosted, &["executor: <absent>", "hosted_extension: Some("]);
}
#[test]
fn registry_and_builder_debug_list_the_names_they_expose() {
let mut builder = RegistryBuilder::new();
assert_eq!(
format!("{builder:?}"),
"RegistryBuilder { static_entries: [], providers: 0 }"
);
builder.register(hosted("alpha"));
builder.register(hosted("beta"));
let (_resolutions, provider) = provider_once(ProviderResolution::success(Vec::new()));
builder.provider(provider);
assert_eq!(
format!("{builder:?}"),
r#"RegistryBuilder { static_entries: ["alpha", "beta"], providers: 1 }"#
);
let registry = builder.build().expect("distinct names build");
assert_eq!(
format!("{registry:?}"),
r#"Registry { static_entries: ["alpha", "beta"], providers: 1 }"#
);
}
#[tokio::test]
async fn step_resolution_family_debug_inherits_redaction() {
let mut builder = RegistryBuilder::new();
builder.register(Registration::client(
Descriptor::new(
local("search"),
SECRET.to_owned(),
Payload::copy_from_slice(SECRET.as_bytes()),
),
Arc::new(StringExecutor {
calls: Arc::new(AtomicUsize::new(0)),
outcome: Mutex::new(Ok(SECRET.to_owned())),
}),
Arc::new(|output: String| Ok(ToolResult::success_text(output))),
));
let resolution = builder
.build()
.expect("one registration builds")
.resolve_step(step_transcript(), &Token::new())
.await
.expect("no collision");
assert_redacted(&resolution);
assert_states(&resolution, &["StepResolution", "description: <21 bytes>"]);
let snapshot = resolution.into_snapshot();
assert_redacted(&snapshot);
assert_states(&snapshot, &["StepToolSnapshot", "executor: <present>"]);
let invocation = invocation(&snapshot);
assert_redacted(&invocation);
assert_states(
&invocation,
&[
r#"session_id: Some("session")"#,
r#"call_id: Id("call")"#,
"emitter: ToolEmitter",
],
);
let outcome = snapshot
.execute(&invocation, &call("search"), &Token::new())
.await
.expect("a registered client tool routes");
assert_redacted(&outcome);
assert_states(&outcome, &["disposition: Executed", "<21 bytes>"]);
}
#[test]
fn expose_all_debug_is_complete_because_it_has_no_state() {
assert_eq!(format!("{ExposeAll:?}"), "ExposeAll");
}
#[test]
fn provider_resolution_debug_shows_entries_and_the_diagnostic() {
let success = ProviderResolution::success(vec![hosted("alpha")]);
assert_redacted(&success);
assert_states(&success, &["error: None", r#"canonical: "alpha""#]);
let failed = ProviderResolution::failed(Vec::new(), ProviderError::new("unreachable".into()));
assert_redacted(&failed);
assert_states(
&failed,
&[
"entries: []",
r#"error: Some(ProviderError("unreachable"))"#,
],
);
}