use std::collections::HashMap;
use std::sync::{
Arc, PoisonError, RwLock, RwLockReadGuard, RwLockWriteGuard,
atomic::{AtomicU64, Ordering},
};
use crate::handlers::{Handlers, WeakHandlers};
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::{
agent::register_generated,
completion::ToolDefinition,
tool::{DynamicTool, RegisteredTool, Tool, ToolCatalog, ToolSet},
};
static NEXT_REGISTRY: AtomicU64 = AtomicU64::new(0);
#[derive(Clone)]
struct RetrievalIndex {
samples: usize,
key: HandlerKey,
handler: rig_core::serve::ErasedHandler,
}
struct ToolServerState {
owner: String,
retrieval_indexes: Vec<RetrievalIndex>,
toolset: ToolSet,
managed_generations: HashMap<String, ManagedToolToken>,
bindings: HashMap<HandlerKey, String>,
tables: Vec<WeakHandlers>,
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 tables(&mut self) -> Vec<Handlers> {
let mut live = Vec::with_capacity(self.tables.len());
self.tables.retain(|table| match table.upgrade() {
Some(table) => {
live.push(table);
true
}
None => false,
});
live
}
fn publish(&mut self, tool: &RegisteredTool) {
for table in self.tables() {
register_generated(
table.register_erased(tool.key().raw().clone(), tool.handler().clone()),
);
}
}
fn unpublish(&mut self, name: &str) {
let Some(key) = self.toolset.get(name).map(|tool| tool.key().raw().clone()) else {
return;
};
if self.bindings.get(&key).is_some_and(|owner| owner == name) {
self.bindings.remove(&key);
for table in self.tables() {
table.deregister(&key);
}
}
}
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.unpublish(&name);
}
self.publish(&tool);
self.bindings.insert(tool.key().raw().clone(), name.clone());
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);
}
name
}
fn remove(&mut self, name: &str) {
self.unpublish(name);
self.toolset.remove_tool(name);
self.managed_generations.remove(name);
}
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");
}
}
fn attach(&mut self, table: &Handlers) {
for (name, tool) in self.toolset.iter() {
if self
.bindings
.get(tool.key().raw())
.is_some_and(|owner| owner == name)
{
register_generated(
table.register_erased(tool.key().raw().clone(), tool.handler().clone()),
);
}
}
for index in &self.retrieval_indexes {
register_generated(table.register_erased(index.key.clone(), index.handler.clone()));
}
self.tables.push(table.downgrade());
}
}
pub use rig_core::tool::{ManagedToolSink, ManagedToolToken};
pub struct ToolServer {
owner: Option<String>,
retrieval_indexes: Vec<(usize, rig_core::serve::ErasedHandler)>,
toolset: ToolSet,
}
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(),
}
}
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>(self, sample: usize, index: I, toolset: ToolSet) -> Self
where
I: VectorStoreIndex<Filter = F> + 'static,
F: DynamicSearchFilter + WasmCompatSend + WasmCompatSync + 'static,
{
self.retrieved_tools_handler(sample, RetrieveAdapter::new(index), toolset)
}
pub fn retrieved_tools_handler(
mut self,
sample: usize,
handler: impl rig_core::serve::Serve + 'static,
toolset: ToolSet,
) -> Self {
self.retrieval_indexes
.push((sample, rig_core::serve::ErasedHandler::new(handler)));
self.toolset.add_retrievable_tools(toolset);
self
}
pub fn run(mut self) -> ToolServerHandle {
let owner = self
.owner
.take()
.unwrap_or_else(|| format!("tools#{}", NEXT_REGISTRY.fetch_add(1, Ordering::Relaxed)));
let handle = ToolServerHandle(Arc::new(RwLock::new(ToolServerState {
owner,
retrieval_indexes: Vec::new(),
toolset: ToolSet::default(),
managed_generations: HashMap::new(),
bindings: HashMap::new(),
tables: Vec::new(),
next_generation: 0,
})));
handle.extend(self);
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, table: &Handlers) {
self.state_mut().attach(table);
}
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(crate) fn extend(&self, server: ToolServer) {
{
let mut state = self.state_mut();
for (samples, handler) in server.retrieval_indexes {
let n = state.retrieval_indexes.len();
let key = HandlerKey::from(format!("{}/retrieve:tools#{n}", state.owner));
for table in state.tables() {
register_generated(table.register_erased(key.clone(), handler.clone()));
}
state.retrieval_indexes.push(RetrievalIndex {
samples,
key,
handler,
});
}
}
self.add_tools(server.toolset);
}
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) {
self.state_mut().remove(tool_name);
}
fn with_registry<R>(&self, f: impl FnOnce(&ToolServerState) -> R) -> R {
{
let state = self.state();
if state.toolset.iter().all(|(_, tool)| tool.is_live()) {
return f(&state);
}
}
let mut state = self.state_mut();
state.retire_disconnected_tools();
f(&state)
}
pub fn snapshot(&self) -> ToolCatalog {
ToolCatalog::from_registered(
self.with_registry(|state| snapshot_registered_tools(state, &[])),
)
}
pub fn toolset(&self) -> ToolSet {
self.with_registry(|state| state.toolset.clone())
}
pub async fn tool_defs(
&self,
prompt: Option<String>,
) -> Result<Vec<Arc<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 {
ToolCatalog::from_registered(
self.with_registry(|state| snapshot_registered_tools(state, dynamic_tool_ids)),
)
}
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::Answered::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()
};
Ok(ToolCatalog::from_registered(self.with_registry(|state| {
snapshot_registered_tools(state, &dynamic_tool_ids)
})))
}
}
fn snapshot_registered_tools(
state: &ToolServerState,
dynamic_tool_ids: &[String],
) -> IndexMap<String, RegisteredTool> {
let mut tools = IndexMap::new();
let 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) => {
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
}
#[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;