1use std::collections::HashMap;
16use std::sync::{
17 Arc, PoisonError, RwLock, RwLockReadGuard, RwLockWriteGuard,
18 atomic::{AtomicU64, Ordering},
19};
20
21use crate::handlers::{Handlers, WeakHandlers};
22use indexmap::IndexMap;
23use rig_core::error::ProviderError;
24use rig_core::serve::adapters::RetrieveAdapter;
25use rig_core::{
26 effect::Key,
27 effect::{Family, HandlerKey, family},
28 vector_store::{VectorStoreIndex, request::DynamicSearchFilter},
29 wasm_compat::{WasmCompatSend, WasmCompatSync},
30};
31
32use crate::{
33 agent::register_generated,
34 completion::ToolDefinition,
35 tool::{DynamicTool, RegisteredTool, Tool, ToolCatalog, ToolSet},
36};
37
38static NEXT_REGISTRY: AtomicU64 = AtomicU64::new(0);
40
41#[derive(Clone)]
44struct RetrievalIndex {
45 samples: usize,
46 key: HandlerKey,
47 handler: rig_core::serve::ErasedHandler,
48}
49
50struct ToolServerState {
51 owner: String,
53 retrieval_indexes: Vec<RetrievalIndex>,
54 toolset: ToolSet,
55 managed_generations: HashMap<String, ManagedToolToken>,
56 bindings: HashMap<HandlerKey, String>,
59 tables: Vec<WeakHandlers>,
61 next_generation: u64,
62}
63
64impl ToolServerState {
65 fn generation_key(&mut self, name: &str) -> Key<family::Tool> {
66 let n = self.next_generation;
67 self.next_generation += 1;
68 Key::new_unchecked(HandlerKey::from(format!("{}/tool:{name}#{n}", self.owner)))
69 }
70
71 fn tables(&mut self) -> Vec<Handlers> {
73 let mut live = Vec::with_capacity(self.tables.len());
74 self.tables.retain(|table| match table.upgrade() {
75 Some(table) => {
76 live.push(table);
77 true
78 }
79 None => false,
80 });
81 live
82 }
83
84 fn publish(&mut self, tool: &RegisteredTool) {
85 for table in self.tables() {
86 register_generated(
87 table.register_erased(tool.key().raw().clone(), tool.handler().clone()),
88 );
89 }
90 }
91
92 fn unpublish(&mut self, name: &str) {
95 let Some(key) = self.toolset.get(name).map(|tool| tool.key().raw().clone()) else {
96 return;
97 };
98 if self.bindings.get(&key).is_some_and(|owner| owner == name) {
99 self.bindings.remove(&key);
100 for table in self.tables() {
101 table.deregister(&key);
102 }
103 }
104 }
105
106 fn register(&mut self, tool: RegisteredTool, always_exposed: bool) -> String {
108 let name = tool.name();
109 let tool = if tool.has_default_key() {
113 let key = self.generation_key(&name);
114 tool.with_key(key)
115 } else {
116 tool
117 };
118 let same_key = self
120 .toolset
121 .get(&name)
122 .is_some_and(|live| live.key() == tool.key());
123 if !same_key {
124 self.unpublish(&name);
125 }
126 self.publish(&tool);
127 self.bindings.insert(tool.key().raw().clone(), name.clone());
128 self.toolset.insert(tool, always_exposed);
129 name
130 }
131
132 fn remove(&mut self, name: &str) {
133 self.unpublish(name);
134 self.toolset.remove_tool(name);
135 self.managed_generations.remove(name);
136 }
137
138 fn retire_disconnected_tools(&mut self) {
139 let disconnected = self
140 .toolset
141 .names()
142 .filter(|name| self.toolset.get(name).is_none_or(|tool| !tool.is_live()))
143 .map(str::to_owned)
144 .collect::<Vec<_>>();
145
146 for name in disconnected {
147 self.remove(&name);
148 tracing::debug!(tool_name = %name, "retired disconnected tool registration");
149 }
150 }
151
152 fn attach(&mut self, table: &Handlers) {
153 for (name, tool) in self.toolset.iter() {
154 if self
155 .bindings
156 .get(tool.key().raw())
157 .is_some_and(|owner| owner == name)
158 {
159 register_generated(
160 table.register_erased(tool.key().raw().clone(), tool.handler().clone()),
161 );
162 }
163 }
164 for index in &self.retrieval_indexes {
165 register_generated(table.register_erased(index.key.clone(), index.handler.clone()));
166 }
167 self.tables.push(table.downgrade());
168 }
169}
170
171pub use rig_core::tool::{ManagedToolSink, ManagedToolToken};
172
173pub struct ToolServer {
176 owner: Option<String>,
177 retrieval_indexes: Vec<(usize, rig_core::serve::ErasedHandler)>,
180 toolset: ToolSet,
181}
182
183impl Default for ToolServer {
184 fn default() -> Self {
185 Self::new()
186 }
187}
188
189impl ToolServer {
190 pub fn new() -> Self {
192 Self {
193 owner: None,
194 retrieval_indexes: Vec::new(),
195 toolset: ToolSet::default(),
196 }
197 }
198
199 pub fn owner(mut self, label: impl Into<String>) -> Self {
205 self.owner = Some(label.into());
206 self
207 }
208
209 pub fn tool(mut self, tool: impl Tool + 'static) -> Self {
211 self.toolset.add_tool(tool);
212 self
213 }
214
215 pub fn dynamic_tool(mut self, tool: DynamicTool) -> Self {
217 self.toolset.add_dynamic_tool(tool);
218 self
219 }
220
221 pub fn dynamic_tools(self, tools: Vec<DynamicTool>) -> Self {
223 tools.into_iter().fold(self, Self::dynamic_tool)
224 }
225
226 pub fn registered_tool(mut self, tool: RegisteredTool) -> Self {
228 self.toolset.add_registered_tool(tool);
229 self
230 }
231
232 pub fn retrieved_tools<I, F>(self, sample: usize, index: I, toolset: ToolSet) -> Self
235 where
236 I: VectorStoreIndex<Filter = F> + 'static,
237 F: DynamicSearchFilter + WasmCompatSend + WasmCompatSync + 'static,
238 {
239 self.retrieved_tools_handler(sample, RetrieveAdapter::new(index), toolset)
240 }
241
242 pub fn retrieved_tools_handler(
245 mut self,
246 sample: usize,
247 handler: impl rig_core::serve::Serve + 'static,
248 toolset: ToolSet,
249 ) -> Self {
250 self.retrieval_indexes
251 .push((sample, rig_core::serve::ErasedHandler::new(handler)));
252 self.toolset.add_retrievable_tools(toolset);
253 self
254 }
255
256 pub fn run(mut self) -> ToolServerHandle {
258 let owner = self
259 .owner
260 .take()
261 .unwrap_or_else(|| format!("tools#{}", NEXT_REGISTRY.fetch_add(1, Ordering::Relaxed)));
262 let handle = ToolServerHandle(Arc::new(RwLock::new(ToolServerState {
263 owner,
264 retrieval_indexes: Vec::new(),
265 toolset: ToolSet::default(),
266 managed_generations: HashMap::new(),
267 bindings: HashMap::new(),
268 tables: Vec::new(),
269 next_generation: 0,
270 })));
271 handle.extend(self);
272 handle
273 }
274}
275
276#[derive(Clone)]
278pub struct ToolServerHandle(Arc<RwLock<ToolServerState>>);
279
280impl ToolServerHandle {
281 fn state(&self) -> RwLockReadGuard<'_, ToolServerState> {
282 self.0.read().unwrap_or_else(PoisonError::into_inner)
283 }
284
285 fn state_mut(&self) -> RwLockWriteGuard<'_, ToolServerState> {
286 self.0.write().unwrap_or_else(PoisonError::into_inner)
287 }
288
289 pub fn attach(&self, table: &Handlers) {
291 self.state_mut().attach(table);
292 }
293
294 pub fn owner(&self) -> String {
296 self.state().owner.clone()
297 }
298
299 fn register(&self, tool: RegisteredTool) {
300 let mut state = self.state_mut();
301 let name = state.register(tool, true);
302 state.managed_generations.remove(&name);
303 }
304
305 pub fn add_tool<T>(&self, tool: T)
307 where
308 T: Tool + 'static,
309 {
310 self.register(RegisteredTool::from_tool(tool));
311 }
312
313 pub fn add_dynamic_tool(&self, tool: DynamicTool) {
315 self.register(RegisteredTool::from_dynamic(tool));
316 }
317
318 pub fn add_registered_tool(&self, tool: RegisteredTool) {
320 self.register(tool);
321 }
322
323 fn add_managed(&self, tools: Vec<RegisteredTool>) -> HashMap<String, ManagedToolToken> {
324 let mut state = self.state_mut();
325 let mut managed = HashMap::with_capacity(tools.len());
326
327 for tool in tools {
328 if !tool.is_live() {
329 tracing::debug!(
330 tool_name = %tool.name(),
331 "ignored initial registration from disconnected MCP owner"
332 );
333 continue;
334 }
335
336 let name = state.register(tool, true);
337 let token = ManagedToolToken::new();
338 state
339 .managed_generations
340 .insert(name.clone(), token.clone());
341 managed.insert(name, token);
342 }
343
344 managed
345 }
346
347 fn reconcile_managed(
348 &self,
349 mut expected: HashMap<String, ManagedToolToken>,
350 tools: Vec<RegisteredTool>,
351 ) -> HashMap<String, ManagedToolToken> {
352 let mut state = self.state_mut();
353 let mut refreshed = HashMap::with_capacity(tools.len());
354 let mut managed_order = Vec::with_capacity(tools.len());
355 let mut seen = std::collections::HashSet::with_capacity(tools.len());
356
357 state.retire_disconnected_tools();
358
359 for tool in tools {
360 if !tool.is_live() {
361 tracing::debug!(
362 tool_name = %tool.name(),
363 "ignored registration from disconnected MCP owner"
364 );
365 continue;
366 }
367
368 let name = tool.name();
369 if !seen.insert(name.clone()) {
370 tracing::warn!(tool_name = %name, "ignoring duplicate MCP tool definition");
371 continue;
372 }
373 let present = state.toolset.contains(&name);
374 let may_register = match expected.remove(&name) {
375 Some(token) if present => state.managed_generations.get(&name) == Some(&token),
376 Some(_) => true,
377 None => !present,
378 };
379
380 if may_register {
381 state.register(tool, true);
382 let token = ManagedToolToken::new();
383 state
384 .managed_generations
385 .insert(name.clone(), token.clone());
386 refreshed.insert(name.clone(), token);
387 managed_order.push(name);
388 } else {
389 tracing::debug!(
390 tool_name = name,
391 "MCP refresh left a newer same-name registration intact"
392 );
393 }
394 }
395
396 for (name, token) in expected {
397 if state.managed_generations.get(&name) == Some(&token) {
398 state.remove(&name);
399 }
400 }
401
402 for name in managed_order {
403 state.toolset.move_to_end(&name);
404 }
405
406 refreshed
407 }
408
409 pub(crate) fn extend(&self, server: ToolServer) {
412 {
413 let mut state = self.state_mut();
414 for (samples, handler) in server.retrieval_indexes {
415 let n = state.retrieval_indexes.len();
416 let key = HandlerKey::from(format!("{}/retrieve:tools#{n}", state.owner));
417 for table in state.tables() {
418 register_generated(table.register_erased(key.clone(), handler.clone()));
419 }
420 state.retrieval_indexes.push(RetrievalIndex {
421 samples,
422 key,
423 handler,
424 });
425 }
426 }
427 self.add_tools(server.toolset);
428 }
429
430 pub fn add_tools(&self, toolset: ToolSet) {
432 let mut state = self.state_mut();
433 for registration in toolset.tools.into_values() {
434 let name = state.register(registration.tool, registration.always_exposed);
435 state.managed_generations.remove(&name);
436 }
437 }
438
439 pub fn remove_tool(&self, tool_name: &str) {
441 self.state_mut().remove(tool_name);
442 }
443
444 fn with_registry<R>(&self, f: impl FnOnce(&ToolServerState) -> R) -> R {
447 {
448 let state = self.state();
449 if state.toolset.iter().all(|(_, tool)| tool.is_live()) {
450 return f(&state);
451 }
452 }
453 let mut state = self.state_mut();
454 state.retire_disconnected_tools();
455 f(&state)
456 }
457
458 pub fn snapshot(&self) -> ToolCatalog {
460 ToolCatalog::from_registered(
461 self.with_registry(|state| snapshot_registered_tools(state, &[])),
462 )
463 }
464
465 pub fn toolset(&self) -> ToolSet {
467 self.with_registry(|state| state.toolset.clone())
468 }
469
470 pub async fn tool_defs(
475 &self,
476 prompt: Option<String>,
477 ) -> Result<Vec<Arc<ToolDefinition>>, ProviderError> {
478 let searches = self
479 .retrieval_queries(prompt)
480 .into_iter()
481 .map(|(index, kind)| async move {
482 rig_core::serve::serve_inline(&index.handler, kind)
483 .await
484 .and_then(retrieved_ids)
485 .map_err(|report| {
486 rig_core::vector_store::VectorStoreError::DatastoreError(Box::new(report))
487 })
488 });
489 let dynamic_tool_ids = futures::future::try_join_all(searches)
490 .await
491 .map_err(ProviderError::request)?
492 .concat();
493 Ok(self
494 .snapshot_with_dynamic(&dynamic_tool_ids)
495 .take_definitions())
496 }
497
498 pub fn retrieval_keys(&self) -> Vec<HandlerKey> {
500 self.state()
501 .retrieval_indexes
502 .iter()
503 .map(|index| index.key.clone())
504 .collect()
505 }
506
507 pub fn retrieval_effects(
511 &self,
512 prompt: Option<String>,
513 ) -> Vec<(HandlerKey, rig_core::effect::EffectKind)> {
514 self.retrieval_queries(prompt)
515 .into_iter()
516 .map(|(index, kind)| (index.key, kind))
517 .collect()
518 }
519
520 fn retrieval_queries(
522 &self,
523 prompt: Option<String>,
524 ) -> Vec<(RetrievalIndex, rig_core::effect::EffectKind)> {
525 let Some(text) = prompt else {
526 return Vec::new();
527 };
528 let retrieval_indexes = self.state().retrieval_indexes.clone();
529 retrieval_indexes
530 .into_iter()
531 .map(|index| {
532 let req = rig_core::vector_store::request::VectorSearchRequest::builder()
533 .query(text.clone())
534 .samples(index.samples as u64)
535 .build();
536 let kind = rig_core::effect::EffectKind::Retrieve {
537 query: rig_core::effect::RetrieveQuery::TopNIds {
538 req: req.map_filter(rig_core::vector_store::request::Filter::interpret),
539 },
540 };
541 (index, kind)
542 })
543 .collect()
544 }
545
546 pub fn snapshot_with_dynamic(&self, dynamic_tool_ids: &[String]) -> ToolCatalog {
549 ToolCatalog::from_registered(
550 self.with_registry(|state| snapshot_registered_tools(state, dynamic_tool_ids)),
551 )
552 }
553}
554
555pub(crate) fn retrieved_ids(
558 outcome: rig_core::effect::Answered,
559) -> Result<Vec<String>, rig_core::error::ErrorReport> {
560 match family::Retrieve::unwrap(outcome)? {
561 rig_core::effect::RetrievedDocuments::Ids(ids) => {
562 Ok(ids.into_iter().map(|(_, id)| id).collect())
563 }
564 rig_core::effect::RetrievedDocuments::Scored(_) => Err(rig_core::error::ErrorReport::new(
565 rig_core::error::ErrorKind::Internal,
566 "expected retrieved ids, the handler answered scored documents",
567 )),
568 }
569}
570
571fn snapshot_registered_tools(
572 state: &ToolServerState,
573 dynamic_tool_ids: &[String],
574) -> IndexMap<String, RegisteredTool> {
575 let mut tools = IndexMap::new();
576 let insert = |tools: &mut IndexMap<String, RegisteredTool>, name: &str, warn_missing| {
577 if tools.contains_key(name) {
578 tracing::debug!(
579 tool_name = %name,
580 "dropping duplicate tool definition from the request"
581 );
582 return;
583 }
584 match state.toolset.get(name).cloned() {
585 Some(tool) => {
586 tools.insert(name.to_string(), tool);
587 }
588 None if warn_missing => {
589 tracing::warn!("Tool implementation not found in toolset: {name}");
590 }
591 None => {}
592 }
593 };
594
595 for name in dynamic_tool_ids {
596 insert(&mut tools, name, true);
597 }
598 for name in state.toolset.always_exposed_names() {
599 insert(&mut tools, name, false);
600 }
601 tools
602}
603
604#[cfg(not(target_family = "wasm"))]
605const _: () = {
606 const fn assert_send_sync_static<T: Send + Sync + 'static>() {}
607 assert_send_sync_static::<ToolSet>();
608 assert_send_sync_static::<ToolCatalog>();
609 assert_send_sync_static::<ToolServerHandle>();
610};
611
612impl ManagedToolSink for ToolServerHandle {
613 fn add_managed_tools(&self, tools: Vec<DynamicTool>) -> HashMap<String, ManagedToolToken> {
614 self.add_managed(
615 tools
616 .into_iter()
617 .map(RegisteredTool::from_dynamic)
618 .collect(),
619 )
620 }
621
622 fn reconcile_managed_tools(
623 &self,
624 expected: HashMap<String, ManagedToolToken>,
625 tools: Vec<DynamicTool>,
626 ) -> HashMap<String, ManagedToolToken> {
627 self.reconcile_managed(
628 expected,
629 tools
630 .into_iter()
631 .map(RegisteredTool::from_dynamic)
632 .collect(),
633 )
634 }
635}
636
637#[cfg(test)]
638mod tests;