use std::collections::HashSet;
use std::error::Error;
use std::fmt::{self, Debug, Display, Formatter};
use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;
use std::task::Poll;
#[cfg(test)]
use std::task::{Context, Waker};
use crate::cancel::Token;
use crate::opaque::{Envelope, EnvelopeError, Payload};
use crate::redact;
use crate::runtime::event::ToolEmitter;
use crate::runtime::model::{ClientTool, RequestPlan};
use crate::transcript::store::Snapshot;
use crate::value::tool_call::{self, Id, ToolCall, ToolPartError, ToolResult};
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum NameError {
EmptyLocal,
EmptyNamespace,
ReservedSeparator,
}
impl Display for NameError {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
match self {
Self::EmptyLocal => formatter.write_str("tool local name is empty"),
Self::EmptyNamespace => formatter.write_str("tool namespace is empty"),
Self::ReservedSeparator => formatter.write_str("tool name component contains '/'"),
}
}
}
impl Error for NameError {}
#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct Name {
namespace: Option<String>,
local: String,
canonical: String,
}
impl Name {
pub fn local(local: String) -> Result<Self, NameError> {
Self::from_parts(None, local)
}
pub fn namespaced(namespace: String, local: String) -> Result<Self, NameError> {
Self::from_parts(Some(namespace), local)
}
pub fn parse_canonical(canonical: &str) -> Result<Self, NameError> {
match canonical.split_once('/') {
Some((namespace, local)) => {
Self::from_parts(Some(namespace.to_owned()), local.to_owned())
}
None => Self::from_parts(None, canonical.to_owned()),
}
}
fn from_parts(namespace: Option<String>, local: String) -> Result<Self, NameError> {
if local.is_empty() {
return Err(NameError::EmptyLocal);
}
if local.contains('/') {
return Err(NameError::ReservedSeparator);
}
if matches!(namespace.as_deref(), Some("")) {
return Err(NameError::EmptyNamespace);
}
if namespace
.as_deref()
.is_some_and(|value| value.contains('/'))
{
return Err(NameError::ReservedSeparator);
}
let canonical = namespace
.as_ref()
.map_or_else(|| local.clone(), |value| format!("{value}/{local}"));
Ok(Self {
namespace,
local,
canonical,
})
}
#[must_use]
pub fn namespace(&self) -> Option<&str> {
self.namespace.as_deref()
}
#[must_use]
pub fn local_name(&self) -> &str {
&self.local
}
#[must_use]
pub fn canonical(&self) -> &str {
&self.canonical
}
#[must_use]
pub fn to_wire(&self) -> tool_call::Name {
tool_call::Name::new(self.canonical.clone())
}
}
#[derive(Clone)]
pub struct Descriptor {
name: Name,
description: String,
input_schema: Payload,
}
impl Debug for Descriptor {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Descriptor")
.field("name", &self.name)
.field("description", &redact::Bytes(self.description.len()))
.field("input_schema", &self.input_schema)
.finish()
}
}
impl Descriptor {
#[must_use]
pub const fn new(name: Name, description: String, input_schema: Payload) -> Self {
Self {
name,
description,
input_schema,
}
}
#[must_use]
pub const fn name(&self) -> &Name {
&self.name
}
#[must_use]
pub fn description(&self) -> &str {
&self.description
}
#[must_use]
pub const fn input_schema(&self) -> &Payload {
&self.input_schema
}
fn client_model_tool(&self) -> ClientTool {
ClientTool::new(
self.name.to_wire(),
self.description.clone(),
self.input_schema.clone(),
)
}
}
#[derive(Clone)]
pub struct ExecutorError {
message: String,
source: Option<Arc<dyn Error + Send + Sync>>,
}
impl ExecutorError {
#[must_use]
pub const fn new(message: String) -> Self {
Self {
message,
source: None,
}
}
#[must_use]
pub fn with_source(mut self, source: impl Error + Send + Sync + 'static) -> Self {
self.source = Some(Arc::new(source));
self
}
}
impl fmt::Debug for ExecutorError {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
let mut tuple = formatter.debug_tuple("ExecutorError");
tuple.field(&self.message);
let mut link = Error::source(self);
while let Some(error) = link {
tuple.field(&error.to_string());
link = error.source();
}
tuple.finish()
}
}
impl Display for ExecutorError {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
formatter.write_str(&self.message)
}
}
impl PartialEq for ExecutorError {
fn eq(&self, other: &Self) -> bool {
self.message == other.message
}
}
impl Eq for ExecutorError {}
impl Error for ExecutorError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
self.source
.as_ref()
.map(|source| source.as_ref() as &(dyn Error + 'static))
}
}
#[derive(Debug)]
pub struct Invocation {
session_id: Option<String>,
transcript: Snapshot,
call_id: Id,
emitter: ToolEmitter,
}
impl Invocation {
#[must_use]
pub fn session_id(&self) -> Option<&str> {
self.session_id.as_deref()
}
#[must_use]
pub const fn transcript(&self) -> &Snapshot {
&self.transcript
}
#[must_use]
pub const fn call_id(&self) -> &Id {
&self.call_id
}
#[must_use]
pub const fn emitter(&self) -> &ToolEmitter {
&self.emitter
}
pub(crate) const fn new(
session_id: Option<String>,
transcript: Snapshot,
call_id: Id,
emitter: ToolEmitter,
) -> Self {
Self {
session_id,
transcript,
call_id,
emitter,
}
}
}
pub trait Executor: Send + Sync + 'static {
type Output: Send + 'static;
fn execute(
&self,
invocation: &Invocation,
call: &ToolCall,
cancellation: Token,
) -> impl Future<Output = Result<Self::Output, ExecutorError>> + Send;
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum MappingError {
InvalidPresence(String),
UnsupportedMetadata(String),
ToolPart(ToolPartError),
OpaqueEnvelope(EnvelopeError),
Protocol(String),
}
impl Display for MappingError {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
match self {
Self::InvalidPresence(context) => {
write!(formatter, "invalid output presence: {context}")
}
Self::UnsupportedMetadata(context) => {
write!(formatter, "unsupported metadata: {context}")
}
Self::ToolPart(error) => write!(formatter, "invalid tool part: {error}"),
Self::OpaqueEnvelope(error) => write!(formatter, "invalid opaque envelope: {error}"),
Self::Protocol(context) => {
write!(formatter, "tool mapping protocol failure: {context}")
}
}
}
}
impl Error for MappingError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
match self {
Self::ToolPart(error) => Some(error),
Self::OpaqueEnvelope(error) => Some(error),
Self::InvalidPresence(_) | Self::UnsupportedMetadata(_) | Self::Protocol(_) => None,
}
}
}
type ErasedFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;
type DeferredMapping = Box<dyn FnOnce() -> Result<ToolResult, MappingError> + Send>;
enum ErasedExecutionError {
Cancelled,
Mapping(MappingError),
}
fn linearize_execution<'a>(
mut execution: ErasedFuture<'a, Result<DeferredMapping, ExecutorError>>,
cancellation: Token,
executor_cancellation: Token,
) -> ErasedFuture<'a, Result<ToolResult, ErasedExecutionError>> {
Box::pin(async move {
let mut cancellation_wait = Box::pin(cancellation.cancelled());
let outcome = std::future::poll_fn(|context| {
if cancellation_wait.as_mut().poll(context).is_ready() {
return Poll::Ready(None);
}
execution.as_mut().poll(context).map(Some)
})
.await;
match outcome {
None => {
executor_cancellation.cancel();
drop(execution);
Err(ErasedExecutionError::Cancelled)
}
Some(Ok(mapper)) => mapper().map_err(ErasedExecutionError::Mapping),
Some(Err(error)) => Ok(ToolResult::error_text(error.to_string())),
}
})
}
trait ErasedExecutor: Send + Sync {
fn execute_mapped<'a>(
&'a self,
invocation: &'a Invocation,
call: &'a ToolCall,
cancellation: Token,
) -> ErasedFuture<'a, Result<ToolResult, ErasedExecutionError>>;
}
struct TypedExecutor<E: Executor> {
executor: Arc<E>,
mapper: Arc<dyn Fn(E::Output) -> Result<ToolResult, MappingError> + Send + Sync>,
}
impl<E> ErasedExecutor for TypedExecutor<E>
where
E: Executor,
{
fn execute_mapped<'a>(
&'a self,
invocation: &'a Invocation,
call: &'a ToolCall,
cancellation: Token,
) -> ErasedFuture<'a, Result<ToolResult, ErasedExecutionError>> {
let executor_cancellation = cancellation.child_token();
let execution_token = executor_cancellation.clone();
let mapper = Arc::clone(&self.mapper);
let execution: ErasedFuture<'a, Result<DeferredMapping, ExecutorError>> =
Box::pin(async move {
self.executor
.execute(invocation, call, execution_token)
.await
.map(|output| Box::new(move || mapper(output)) as DeferredMapping)
});
linearize_execution(execution, cancellation, executor_cancellation)
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum Lane {
Client,
Hosted,
}
#[derive(Clone)]
pub struct Registration {
descriptor: Descriptor,
executor: Option<Arc<dyn ErasedExecutor>>,
hosted_extension: Option<Envelope>,
}
impl Debug for Registration {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Registration")
.field("descriptor", &self.descriptor)
.field("executor", &redact::Presence(self.executor.is_some()))
.field("hosted_extension", &self.hosted_extension)
.finish()
}
}
impl Registration {
#[must_use]
pub fn client<E, M>(descriptor: Descriptor, executor: Arc<E>, mapper: Arc<M>) -> Self
where
E: Executor,
M: Fn(E::Output) -> Result<ToolResult, MappingError> + Send + Sync + 'static,
{
Self {
descriptor,
executor: Some(Arc::new(TypedExecutor { executor, mapper })),
hosted_extension: None,
}
}
#[must_use]
pub fn hosted(descriptor: Descriptor, extension: Envelope) -> Self {
Self {
descriptor,
executor: None,
hosted_extension: Some(extension),
}
}
#[must_use]
pub const fn descriptor(&self) -> &Descriptor {
&self.descriptor
}
#[must_use]
pub const fn lane(&self) -> Lane {
if self.executor.is_some() {
Lane::Client
} else {
Lane::Hosted
}
}
}
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum RegistryError {
StaticCollision(Name),
}
impl Display for RegistryError {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
match self {
Self::StaticCollision(name) => {
write!(formatter, "duplicate static tool: {}", name.canonical())
}
}
}
}
impl Error for RegistryError {}
#[derive(Clone)]
pub struct ProviderError {
message: String,
source: Option<Arc<dyn Error + Send + Sync>>,
}
impl ProviderError {
#[must_use]
pub const fn new(message: String) -> Self {
Self {
message,
source: None,
}
}
#[must_use]
pub fn with_source(mut self, source: impl Error + Send + Sync + 'static) -> Self {
self.source = Some(Arc::new(source));
self
}
}
impl fmt::Debug for ProviderError {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
let mut tuple = formatter.debug_tuple("ProviderError");
tuple.field(&self.message);
let mut link = Error::source(self);
while let Some(error) = link {
tuple.field(&error.to_string());
link = error.source();
}
tuple.finish()
}
}
impl Display for ProviderError {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
formatter.write_str(&self.message)
}
}
impl PartialEq for ProviderError {
fn eq(&self, other: &Self) -> bool {
self.message == other.message
}
}
impl Eq for ProviderError {}
impl Error for ProviderError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
self.source
.as_ref()
.map(|source| source.as_ref() as &(dyn Error + 'static))
}
}
#[derive(Debug)]
pub struct ProviderResolution {
entries: Vec<Registration>,
error: Option<ProviderError>,
}
impl ProviderResolution {
#[must_use]
pub const fn success(entries: Vec<Registration>) -> Self {
Self {
entries,
error: None,
}
}
#[must_use]
pub const fn failed(partial_entries: Vec<Registration>, error: ProviderError) -> Self {
Self {
entries: partial_entries,
error: Some(error),
}
}
}
pub trait Provider: Send + Sync + 'static {
fn resolve<'a>(
&'a self,
transcript: &'a Snapshot,
cancellation: Token,
) -> Pin<Box<dyn Future<Output = ProviderResolution> + Send + 'a>>;
}
#[derive(Default)]
pub struct RegistryBuilder {
static_entries: Vec<Registration>,
providers: Vec<Arc<dyn Provider>>,
}
impl Debug for RegistryBuilder {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
debug_registry(
"RegistryBuilder",
&self.static_entries,
&self.providers,
formatter,
)
}
}
fn debug_registry(
name: &str,
static_entries: &[Registration],
providers: &[Arc<dyn Provider>],
formatter: &mut Formatter<'_>,
) -> fmt::Result {
formatter
.debug_struct(name)
.field(
"static_entries",
&static_entries
.iter()
.map(|entry| entry.descriptor.name.canonical())
.collect::<Vec<_>>(),
)
.field("providers", &providers.len())
.finish()
}
impl RegistryBuilder {
#[must_use]
pub fn new() -> Self {
Self::default()
}
pub fn register(&mut self, registration: Registration) -> &mut Self {
self.static_entries.push(registration);
self
}
pub fn provider(&mut self, provider: Arc<dyn Provider>) -> &mut Self {
self.providers.push(provider);
self
}
pub fn build(self) -> Result<Registry, RegistryError> {
let mut names = HashSet::new();
for entry in &self.static_entries {
if !names.insert(entry.descriptor.name.clone()) {
return Err(RegistryError::StaticCollision(
entry.descriptor.name.clone(),
));
}
}
Ok(Registry {
static_entries: self.static_entries,
providers: self.providers,
})
}
}
#[derive(Clone)]
pub struct Registry {
static_entries: Vec<Registration>,
providers: Vec<Arc<dyn Provider>>,
}
impl Debug for Registry {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
debug_registry("Registry", &self.static_entries, &self.providers, formatter)
}
}
pub(crate) trait ExposureFilter: Sync {
fn exposed(&self, descriptor: &Descriptor, lane: Lane) -> bool;
}
#[derive(Debug)]
pub(crate) struct ExposeAll;
impl ExposureFilter for ExposeAll {
fn exposed(&self, _descriptor: &Descriptor, _lane: Lane) -> bool {
true
}
}
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum StepResolutionError {
Collision(Name),
}
impl Display for StepResolutionError {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
match self {
Self::Collision(name) => write!(formatter, "Step tool collision: {}", name.canonical()),
}
}
}
impl Error for StepResolutionError {}
#[derive(Debug)]
pub struct StepResolution {
snapshot: StepToolSnapshot,
provider_errors: Vec<ProviderError>,
}
impl StepResolution {
#[must_use]
pub const fn snapshot(&self) -> &StepToolSnapshot {
&self.snapshot
}
#[must_use]
pub fn into_snapshot(self) -> StepToolSnapshot {
self.snapshot
}
#[must_use]
pub(crate) fn into_parts(self) -> (StepToolSnapshot, Vec<ProviderError>) {
(self.snapshot, self.provider_errors)
}
#[must_use]
pub fn provider_errors(&self) -> &[ProviderError] {
&self.provider_errors
}
}
impl Registry {
pub async fn resolve_step(
&self,
transcript: Snapshot,
cancellation: &Token,
) -> Result<StepResolution, StepResolutionError> {
self.resolve_step_filtered(transcript, cancellation, &ExposeAll)
.await
}
pub(crate) async fn resolve_step_filtered(
&self,
transcript: Snapshot,
cancellation: &Token,
correction: &dyn ExposureFilter,
) -> Result<StepResolution, StepResolutionError> {
let mut entries = self.static_entries.clone();
let mut provider_errors = Vec::new();
for provider in &self.providers {
let resolution = provider.resolve(&transcript, cancellation.clone()).await;
if let Some(error) = resolution.error {
provider_errors.push(error);
} else {
entries.extend(resolution.entries);
}
}
let mut names = HashSet::new();
for entry in &entries {
if !names.insert(entry.descriptor.name.clone()) {
return Err(StepResolutionError::Collision(
entry.descriptor.name.clone(),
));
}
}
entries.retain(|entry| correction.exposed(&entry.descriptor, entry.lane()));
Ok(StepResolution {
snapshot: StepToolSnapshot {
entries,
transcript,
},
provider_errors,
})
}
#[cfg(test)]
pub(crate) fn resolve_step_without_providers(
&self,
transcript: Snapshot,
cancellation: &Token,
correction: &dyn ExposureFilter,
) -> Result<StepResolution, StepResolutionError> {
let mut resolving =
Box::pin(self.resolve_step_filtered(transcript, cancellation, correction));
match resolving
.as_mut()
.poll(&mut Context::from_waker(Waker::noop()))
{
Poll::Ready(resolved) => resolved,
Poll::Pending => {
panic!("a registry with no dynamic provider resolves on its first poll")
}
}
}
}
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum ExecutionError {
Hosted(String),
Cancelled,
Mapping(MappingError),
}
impl Display for ExecutionError {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
match self {
Self::Hosted(name) => {
write!(formatter, "hosted tool is not locally dispatchable: {name}")
}
Self::Cancelled => formatter.write_str("tool run cancelled"),
Self::Mapping(error) => write!(formatter, "tool output mapping failed: {error}"),
}
}
}
impl Error for ExecutionError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
match self {
Self::Mapping(error) => Some(error),
Self::Hosted(_) | Self::Cancelled => None,
}
}
}
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[non_exhaustive]
pub enum CallDisposition {
Executed,
ShortCircuited,
Blocked,
Rejected,
Truncated,
NotExecuted,
}
#[derive(Clone, Debug)]
pub struct ExecutionOutcome {
result: ToolResult,
disposition: CallDisposition,
}
impl ExecutionOutcome {
#[must_use]
pub const fn result(&self) -> &ToolResult {
&self.result
}
#[must_use]
pub const fn disposition(&self) -> CallDisposition {
self.disposition
}
#[must_use]
pub fn into_parts(self) -> (ToolResult, CallDisposition) {
(self.result, self.disposition)
}
}
#[derive(Debug)]
pub struct StepToolSnapshot {
entries: Vec<Registration>,
transcript: Snapshot,
}
impl StepToolSnapshot {
#[must_use]
pub(crate) fn shallow_clone(&self) -> Self {
Self {
entries: self.entries.clone(),
transcript: self.transcript.clone(),
}
}
#[must_use]
pub const fn transcript(&self) -> &Snapshot {
&self.transcript
}
#[must_use]
pub fn exposure(&self) -> impl ExactSizeIterator<Item = (&Descriptor, Lane)> {
self.entries
.iter()
.map(|entry| (&entry.descriptor, entry.lane()))
}
#[must_use]
pub fn client_model_tools(&self) -> Vec<ClientTool> {
self.entries
.iter()
.filter(|entry| entry.lane() == Lane::Client)
.map(|entry| entry.descriptor.client_model_tool())
.collect()
}
#[must_use]
pub fn hosted_model_extensions(&self) -> Vec<Envelope> {
self.entries
.iter()
.filter_map(|entry| entry.hosted_extension.clone())
.collect()
}
pub fn apply_to_plan(&self, plan: &mut RequestPlan) {
plan.extend_tools(self.client_model_tools())
.extend_extensions(self.hosted_model_extensions());
}
#[must_use]
pub fn invocation(
&self,
session_id: Option<String>,
call_id: Id,
emitter: ToolEmitter,
) -> Invocation {
Invocation::new(session_id, self.transcript.clone(), call_id, emitter)
}
pub async fn execute(
&self,
invocation: &Invocation,
call: &ToolCall,
cancellation: &Token,
) -> Result<ExecutionOutcome, ExecutionError> {
if cancellation.is_cancelled() {
return Err(ExecutionError::Cancelled);
}
let emitted = call.name().as_str();
let Some(entry) = Name::parse_canonical(emitted).ok().and_then(|name| {
self.entries
.iter()
.find(|candidate| candidate.descriptor.name == name)
}) else {
return Ok(rejected(format!("unknown tool: {emitted}")));
};
let Some(executor) = &entry.executor else {
return Err(ExecutionError::Hosted(emitted.to_owned()));
};
match executor
.execute_mapped(invocation, call, cancellation.clone())
.await
{
Ok(result) => Ok(ExecutionOutcome {
result,
disposition: CallDisposition::Executed,
}),
Err(ErasedExecutionError::Cancelled) => Err(ExecutionError::Cancelled),
Err(ErasedExecutionError::Mapping(error)) => Err(ExecutionError::Mapping(error)),
}
}
}
fn rejected(message: String) -> ExecutionOutcome {
ExecutionOutcome {
result: ToolResult::error_text(message),
disposition: CallDisposition::Rejected,
}
}