use std::collections::HashMap;
use std::sync::{
Arc, PoisonError, RwLock, RwLockReadGuard, RwLockWriteGuard, Weak,
atomic::{AtomicU64, Ordering},
};
use crate::bus::Registrar;
use indexmap::IndexMap;
use rig_core::error::ProviderError;
use rig_core::serve::adapters::RetrieveAdapter;
use rig_core::{
effect::Key,
effect::{HandlerKey, family},
vector_store::{VectorStoreIndex, request::DynamicSearchFilter},
wasm_compat::{WasmCompatSend, WasmCompatSync},
};
use crate::{
completion::ToolDefinition,
tool::{
DynamicTool, RegisteredTool, Tool, ToolCatalog, ToolContext, ToolDispatch, ToolLease,
ToolResult, ToolSet, execute_tool,
},
};
static NEXT_REGISTRY: AtomicU64 = AtomicU64::new(0);
#[derive(Clone)]
struct RetrievalIndex {
samples: usize,
key: HandlerKey,
handler: rig_core::serve::ErasedHandler,
}
struct PendingRetrievalIndex {
samples: usize,
index: usize,
handler: rig_core::serve::ErasedHandler,
}
struct LeaseToken {
registry: Weak<RwLock<ToolServerState>>,
}
impl Drop for LeaseToken {
fn drop(&mut self) {
let Some(registry) = self.registry.upgrade() else {
return;
};
if let Ok(mut state) = registry.try_write() {
state.sweep_retired();
}
}
}
struct RetiredGeneration {
key: HandlerKey,
lease: Weak<LeaseToken>,
}
struct ToolServerState {
owner: String,
registry: Weak<RwLock<ToolServerState>>,
retrieval_indexes: Vec<RetrievalIndex>,
toolset: ToolSet,
leases: HashMap<String, Arc<LeaseToken>>,
bindings: HashMap<HandlerKey, Weak<LeaseToken>>,
retired: Vec<RetiredGeneration>,
managed_generations: HashMap<String, ManagedToolToken>,
buses: Vec<Registrar>,
next_generation: u64,
}
impl ToolServerState {
fn generation_key(&mut self, name: &str) -> Key<family::Tool> {
let n = self.next_generation;
self.next_generation += 1;
Key::new_unchecked(HandlerKey::from(format!("{}/tool:{name}#{n}", self.owner)))
}
fn lease(&self) -> Arc<LeaseToken> {
Arc::new(LeaseToken {
registry: self.registry.clone(),
})
}
fn publish(&self, tool: &RegisteredTool) {
for bus in &self.buses {
crate::agent::drive::register_generated(
bus.register_erased(tool.key().raw().clone(), tool.handler().clone()),
);
}
}
fn unpublish(&self, key: &HandlerKey) {
for bus in &self.buses {
bus.deregister(key);
}
}
fn retire(&mut self, name: &str) {
if let (Some(tool), Some(lease)) = (self.toolset.get(name), self.leases.remove(name)) {
self.retired.push(RetiredGeneration {
key: tool.key().raw().clone(),
lease: Arc::downgrade(&lease),
});
drop(lease);
}
}
fn sweep_retired(&mut self) {
let retired = std::mem::take(&mut self.retired);
let mut kept = Vec::with_capacity(retired.len());
for retired in retired {
if !self
.bindings
.get(&retired.key)
.is_some_and(|owner| Weak::ptr_eq(owner, &retired.lease))
{
continue;
}
if retired.lease.strong_count() == 0 {
self.unpublish(&retired.key);
self.bindings.remove(&retired.key);
} else {
kept.push(retired);
}
}
self.retired = kept;
self.buses.retain(|bus| !bus.is_closed());
}
fn register(&mut self, tool: RegisteredTool, always_exposed: bool) -> String {
let name = tool.name();
let tool = if tool.has_default_key() {
let key = self.generation_key(&name);
tool.with_key(key)
} else {
tool
};
let same_key = self
.toolset
.get(&name)
.is_some_and(|live| live.key() == tool.key());
if !same_key {
self.retire(&name);
}
let lease = self
.leases
.get(&name)
.cloned()
.unwrap_or_else(|| self.lease());
self.bindings
.insert(tool.key().raw().clone(), Arc::downgrade(&lease));
self.leases.insert(name.clone(), lease);
self.publish(&tool);
if always_exposed {
self.toolset.add_registered_tool(tool);
} else {
let mut set = ToolSet::default();
set.add_registered_tool(tool);
self.toolset.add_retrievable_tools(set);
}
self.sweep_retired();
name
}
fn remove(&mut self, name: &str) {
self.retire(name);
self.toolset.remove_tool(name);
self.managed_generations.remove(name);
self.sweep_retired();
}
fn retire_disconnected_tools(&mut self) {
let disconnected = self
.toolset
.names()
.filter(|name| self.toolset.get(name).is_none_or(|tool| !tool.is_live()))
.map(str::to_owned)
.collect::<Vec<_>>();
for name in disconnected {
self.remove(&name);
tracing::debug!(tool_name = %name, "retired disconnected tool registration");
}
self.sweep_retired();
}
fn attach(&mut self, bus: &Registrar) {
for (name, tool) in self.toolset.iter() {
let owns_binding = self.leases.get(name).is_some_and(|lease| {
self.bindings
.get(tool.key().raw())
.is_some_and(|owner| Weak::ptr_eq(owner, &Arc::downgrade(lease)))
});
if !owns_binding {
continue;
}
crate::agent::drive::register_generated(
bus.register_erased(tool.key().raw().clone(), tool.handler().clone()),
);
}
for index in &self.retrieval_indexes {
crate::agent::drive::register_generated(
bus.register_erased(index.key.clone(), index.handler.clone()),
);
}
self.buses.push(bus.clone());
}
}
pub use rig_core::tool::{ManagedToolSink, ManagedToolToken};
pub struct ToolServer {
owner: Option<String>,
retrieval_indexes: Vec<PendingRetrievalIndex>,
toolset: ToolSet,
next_index: usize,
}
impl Default for ToolServer {
fn default() -> Self {
Self::new()
}
}
impl ToolServer {
pub fn new() -> Self {
Self {
owner: None,
retrieval_indexes: Vec::new(),
toolset: ToolSet::default(),
next_index: 0,
}
}
pub fn owner(mut self, label: impl Into<String>) -> Self {
self.owner = Some(label.into());
self
}
pub fn tool(mut self, tool: impl Tool + 'static) -> Self {
self.toolset.add_tool(tool);
self
}
pub fn dynamic_tool(mut self, tool: DynamicTool) -> Self {
self.toolset.add_dynamic_tool(tool);
self
}
pub fn dynamic_tools(self, tools: Vec<DynamicTool>) -> Self {
tools.into_iter().fold(self, Self::dynamic_tool)
}
pub fn registered_tool(mut self, tool: RegisteredTool) -> Self {
self.toolset.add_registered_tool(tool);
self
}
pub fn retrieved_tools<I, F>(mut self, sample: usize, index: I, toolset: ToolSet) -> Self
where
I: VectorStoreIndex<Filter = F> + 'static,
F: DynamicSearchFilter + WasmCompatSend + WasmCompatSync + 'static,
{
let n = self.next_index;
self.next_index += 1;
self.retrieval_indexes.push(PendingRetrievalIndex {
samples: sample,
index: n,
handler: rig_core::serve::ErasedHandler::new(RetrieveAdapter::new(index)),
});
self.toolset.add_retrievable_tools(toolset);
self
}
pub fn retrieved_tools_handler(
mut self,
sample: usize,
handler: impl rig_core::serve::Serve + 'static,
toolset: ToolSet,
) -> Self {
let n = self.next_index;
self.next_index += 1;
self.retrieval_indexes.push(PendingRetrievalIndex {
samples: sample,
index: n,
handler: rig_core::serve::ErasedHandler::new(handler),
});
self.toolset.add_retrievable_tools(toolset);
self
}
pub fn run(self) -> ToolServerHandle {
let owner = self
.owner
.unwrap_or_else(|| format!("tools#{}", NEXT_REGISTRY.fetch_add(1, Ordering::Relaxed)));
let retrieval_indexes = self
.retrieval_indexes
.into_iter()
.map(|pending| RetrievalIndex {
samples: pending.samples,
key: HandlerKey::from(format!("{owner}/retrieve:tools#{}", pending.index)),
handler: pending.handler,
})
.collect();
let registry = Arc::new_cyclic(|registry| {
RwLock::new(ToolServerState {
owner,
registry: registry.clone(),
retrieval_indexes,
toolset: ToolSet::default(),
leases: HashMap::new(),
bindings: HashMap::new(),
retired: Vec::new(),
managed_generations: HashMap::new(),
buses: Vec::new(),
next_generation: 0,
})
});
let handle = ToolServerHandle(registry);
let exposed: Vec<String> = self
.toolset
.always_exposed_names()
.map(str::to_owned)
.collect();
{
let mut state = handle.state_mut();
for (name, tool) in self.toolset.iter() {
state.register(tool.clone(), exposed.iter().any(|exposed| exposed == name));
}
}
handle
}
}
#[derive(Clone)]
pub struct ToolServerHandle(Arc<RwLock<ToolServerState>>);
impl ToolServerHandle {
fn state(&self) -> RwLockReadGuard<'_, ToolServerState> {
self.0.read().unwrap_or_else(PoisonError::into_inner)
}
fn state_mut(&self) -> RwLockWriteGuard<'_, ToolServerState> {
self.0.write().unwrap_or_else(PoisonError::into_inner)
}
pub fn attach(&self, bus: &Registrar) {
self.state_mut().attach(bus);
}
pub fn owner(&self) -> String {
self.state().owner.clone()
}
fn register(&self, tool: RegisteredTool) {
let mut state = self.state_mut();
let name = state.register(tool, true);
state.managed_generations.remove(&name);
}
pub fn add_tool<T>(&self, tool: T)
where
T: Tool + 'static,
{
self.register(RegisteredTool::from_tool(tool));
}
pub fn add_dynamic_tool(&self, tool: DynamicTool) {
self.register(RegisteredTool::from_dynamic(tool));
}
pub fn add_registered_tool(&self, tool: RegisteredTool) {
self.register(tool);
}
fn add_managed(&self, tools: Vec<RegisteredTool>) -> HashMap<String, ManagedToolToken> {
let mut state = self.state_mut();
let mut managed = HashMap::with_capacity(tools.len());
for tool in tools {
if !tool.is_live() {
tracing::debug!(
tool_name = %tool.name(),
"ignored initial registration from disconnected MCP owner"
);
continue;
}
let name = state.register(tool, true);
let token = ManagedToolToken::new();
state
.managed_generations
.insert(name.clone(), token.clone());
managed.insert(name, token);
}
managed
}
fn reconcile_managed(
&self,
mut expected: HashMap<String, ManagedToolToken>,
tools: Vec<RegisteredTool>,
) -> HashMap<String, ManagedToolToken> {
let mut state = self.state_mut();
let mut refreshed = HashMap::with_capacity(tools.len());
let mut managed_order = Vec::with_capacity(tools.len());
let mut seen = std::collections::HashSet::with_capacity(tools.len());
state.retire_disconnected_tools();
for tool in tools {
if !tool.is_live() {
tracing::debug!(
tool_name = %tool.name(),
"ignored registration from disconnected MCP owner"
);
continue;
}
let name = tool.name();
if !seen.insert(name.clone()) {
tracing::warn!(tool_name = %name, "ignoring duplicate MCP tool definition");
continue;
}
let present = state.toolset.contains(&name);
let may_register = match expected.remove(&name) {
Some(token) if present => state.managed_generations.get(&name) == Some(&token),
Some(_) => true,
None => !present,
};
if may_register {
state.register(tool, true);
let token = ManagedToolToken::new();
state
.managed_generations
.insert(name.clone(), token.clone());
refreshed.insert(name.clone(), token);
managed_order.push(name);
} else {
tracing::debug!(
tool_name = name,
"MCP refresh left a newer same-name registration intact"
);
}
}
for (name, token) in expected {
if state.managed_generations.get(&name) == Some(&token) {
state.remove(&name);
}
}
for name in managed_order {
state.toolset.move_to_end(&name);
}
refreshed
}
pub fn add_tools(&self, toolset: ToolSet) {
let mut state = self.state_mut();
let exposed: Vec<String> = toolset.always_exposed_names().map(str::to_owned).collect();
for (name, tool) in toolset.iter() {
let always_exposed = exposed.iter().any(|exposed| exposed == name);
let name = state.register(tool.clone(), always_exposed);
state.managed_generations.remove(&name);
}
}
pub fn remove_tool(&self, tool_name: &str) {
let mut state = self.state_mut();
state.remove(tool_name);
state.sweep_retired();
}
pub async fn execute(
&self,
tool_name: &str,
args: &str,
context: &mut ToolContext,
) -> ToolResult {
context.clear_dispatch_result();
let dispatch = self.execute_scoped(tool_name, args, context).await;
dispatch.publish_to(context)
}
fn with_registry<R>(&self, f: impl FnOnce(&ToolServerState) -> R) -> R {
let mut state = self.state_mut();
state.retire_disconnected_tools();
f(&state)
}
pub(crate) async fn execute_scoped(
&self,
tool_name: &str,
args: &str,
context: &ToolContext,
) -> ToolDispatch {
let tool = self.with_registry(|state| state.toolset.get(tool_name).cloned());
execute_tool(tool_name, args.to_string(), tool, context).await
}
pub fn snapshot(&self) -> ToolCatalog {
let (tools, leases) = self.with_registry(|state| snapshot_registered_tools(state, &[]));
ToolCatalog::from_registered(tools).with_leases(leases)
}
pub fn static_tool_defs(&self) -> Vec<ToolDefinition> {
let mut snapshot = self.snapshot();
snapshot.take_definitions()
}
pub fn toolset(&self) -> ToolSet {
self.with_registry(|state| state.toolset.clone())
}
pub async fn tool_defs(
&self,
prompt: Option<String>,
) -> Result<Vec<ToolDefinition>, ToolServerError> {
Ok(self.snapshot_tool_defs(prompt).await?.take_definitions())
}
pub fn retrieval_keys(&self) -> Vec<HandlerKey> {
self.state()
.retrieval_indexes
.iter()
.map(|index| index.key.clone())
.collect()
}
pub fn retrieval_effects(
&self,
prompt: Option<String>,
) -> Vec<(HandlerKey, rig_core::effect::EffectKind)> {
let Some(text) = prompt else {
return Vec::new();
};
let retrieval_indexes = {
let state = self.state();
state.retrieval_indexes.clone()
};
retrieval_indexes
.into_iter()
.map(|index| {
let req = rig_core::vector_store::request::VectorSearchRequest::builder()
.query(text.clone())
.samples(index.samples as u64)
.build();
(
index.key,
rig_core::effect::EffectKind::Retrieve {
query: rig_core::effect::RetrieveQuery::TopNIds {
req: req.map_filter(rig_core::vector_store::request::Filter::interpret),
},
},
)
})
.collect()
}
pub fn snapshot_with_dynamic(&self, dynamic_tool_ids: &[String]) -> ToolCatalog {
let (tools, leases) =
self.with_registry(|state| snapshot_registered_tools(state, dynamic_tool_ids));
ToolCatalog::from_registered(tools).with_leases(leases)
}
pub(crate) async fn snapshot_tool_defs(
&self,
prompt: Option<String>,
) -> Result<ToolCatalog, ToolServerError> {
let retrieval_indexes = {
let state = self.state();
state.retrieval_indexes.clone()
};
let dynamic_tool_ids = if let Some(ref text) = prompt {
let search_futures = retrieval_indexes.iter().map(|index| {
let text = text.clone();
let samples = index.samples;
let handler = index.handler.clone();
async move {
let req = rig_core::vector_store::request::VectorSearchRequest::builder()
.query(text)
.samples(samples as u64)
.build();
let outcome = rig_core::serve::serve_inline(
&handler,
rig_core::effect::EffectKind::Retrieve {
query: rig_core::effect::RetrieveQuery::TopNIds {
req: req
.map_filter(rig_core::vector_store::request::Filter::interpret),
},
},
)
.await
.map_err(|report| {
rig_core::vector_store::VectorStoreError::DatastoreError(Box::new(report))
})?;
let ids = match outcome {
rig_core::effect::Outcome::Documents(
rig_core::effect::RetrievedDocuments::Ids(ids),
) => ids.into_iter().map(|(_, id)| id).collect::<Vec<String>>(),
other => {
return Err(rig_core::vector_store::VectorStoreError::DatastoreError(
Box::new(rig_core::error::ErrorReport::new(
rig_core::error::ErrorKind::Internal,
format!(
"tool retrieval answered with a {} outcome",
other.family()
),
)),
));
}
};
Ok::<_, rig_core::vector_store::VectorStoreError>(ids)
}
});
futures::future::try_join_all(search_futures)
.await
.map_err(|e| ToolServerError::DefinitionError(ProviderError::request(e)))?
.into_iter()
.flatten()
.collect::<Vec<String>>()
} else {
Vec::new()
};
let (tools, leases) =
self.with_registry(|state| snapshot_registered_tools(state, &dynamic_tool_ids));
Ok(ToolCatalog::from_registered(tools).with_leases(leases))
}
}
fn snapshot_registered_tools(
state: &ToolServerState,
dynamic_tool_ids: &[String],
) -> (IndexMap<String, RegisteredTool>, Vec<ToolLease>) {
let mut tools = IndexMap::new();
let mut leases = Vec::new();
let mut insert = |tools: &mut IndexMap<String, RegisteredTool>, name: &str, warn_missing| {
if tools.contains_key(name) {
tracing::debug!(
tool_name = %name,
"dropping duplicate tool definition from the request"
);
return;
}
match state.toolset.get(name).cloned() {
Some(tool) => {
if let Some(lease) = state.leases.get(name) {
leases.push(lease.clone() as ToolLease);
}
tools.insert(name.to_string(), tool);
}
None if warn_missing => {
tracing::warn!("Tool implementation not found in toolset: {name}");
}
None => {}
}
};
for name in dynamic_tool_ids {
insert(&mut tools, name, true);
}
for name in state.toolset.always_exposed_names() {
insert(&mut tools, name, false);
}
(tools, leases)
}
#[cfg(not(target_family = "wasm"))]
const _: () = {
const fn assert_send_sync_static<T: Send + Sync + 'static>() {}
assert_send_sync_static::<ToolSet>();
assert_send_sync_static::<ToolCatalog>();
assert_send_sync_static::<ToolServerHandle>();
};
#[derive(Debug, thiserror::Error)]
pub enum ToolServerError {
#[error("Failed to retrieve tool definitions: {0}")]
DefinitionError(ProviderError),
}
impl ManagedToolSink for ToolServerHandle {
fn add_managed_tools(&self, tools: Vec<DynamicTool>) -> HashMap<String, ManagedToolToken> {
self.add_managed(
tools
.into_iter()
.map(RegisteredTool::from_dynamic)
.collect(),
)
}
fn reconcile_managed_tools(
&self,
expected: HashMap<String, ManagedToolToken>,
tools: Vec<DynamicTool>,
) -> HashMap<String, ManagedToolToken> {
self.reconcile_managed(
expected,
tools
.into_iter()
.map(RegisteredTool::from_dynamic)
.collect(),
)
}
}
#[cfg(test)]
mod tests;