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::{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 if always_exposed {
129 self.toolset.add_registered_tool(tool);
130 } else {
131 let mut set = ToolSet::default();
132 set.add_registered_tool(tool);
133 self.toolset.add_retrievable_tools(set);
134 }
135 name
136 }
137
138 fn remove(&mut self, name: &str) {
139 self.unpublish(name);
140 self.toolset.remove_tool(name);
141 self.managed_generations.remove(name);
142 }
143
144 fn retire_disconnected_tools(&mut self) {
145 let disconnected = self
146 .toolset
147 .names()
148 .filter(|name| self.toolset.get(name).is_none_or(|tool| !tool.is_live()))
149 .map(str::to_owned)
150 .collect::<Vec<_>>();
151
152 for name in disconnected {
153 self.remove(&name);
154 tracing::debug!(tool_name = %name, "retired disconnected tool registration");
155 }
156 }
157
158 fn attach(&mut self, table: &Handlers) {
159 for (name, tool) in self.toolset.iter() {
160 if self
161 .bindings
162 .get(tool.key().raw())
163 .is_some_and(|owner| owner == name)
164 {
165 register_generated(
166 table.register_erased(tool.key().raw().clone(), tool.handler().clone()),
167 );
168 }
169 }
170 for index in &self.retrieval_indexes {
171 register_generated(table.register_erased(index.key.clone(), index.handler.clone()));
172 }
173 self.tables.push(table.downgrade());
174 }
175}
176
177pub use rig_core::tool::{ManagedToolSink, ManagedToolToken};
178
179pub struct ToolServer {
182 owner: Option<String>,
183 retrieval_indexes: Vec<(usize, rig_core::serve::ErasedHandler)>,
186 toolset: ToolSet,
187}
188
189impl Default for ToolServer {
190 fn default() -> Self {
191 Self::new()
192 }
193}
194
195impl ToolServer {
196 pub fn new() -> Self {
198 Self {
199 owner: None,
200 retrieval_indexes: Vec::new(),
201 toolset: ToolSet::default(),
202 }
203 }
204
205 pub fn owner(mut self, label: impl Into<String>) -> Self {
211 self.owner = Some(label.into());
212 self
213 }
214
215 pub fn tool(mut self, tool: impl Tool + 'static) -> Self {
217 self.toolset.add_tool(tool);
218 self
219 }
220
221 pub fn dynamic_tool(mut self, tool: DynamicTool) -> Self {
223 self.toolset.add_dynamic_tool(tool);
224 self
225 }
226
227 pub fn dynamic_tools(self, tools: Vec<DynamicTool>) -> Self {
229 tools.into_iter().fold(self, Self::dynamic_tool)
230 }
231
232 pub fn registered_tool(mut self, tool: RegisteredTool) -> Self {
234 self.toolset.add_registered_tool(tool);
235 self
236 }
237
238 pub fn retrieved_tools<I, F>(self, sample: usize, index: I, toolset: ToolSet) -> Self
241 where
242 I: VectorStoreIndex<Filter = F> + 'static,
243 F: DynamicSearchFilter + WasmCompatSend + WasmCompatSync + 'static,
244 {
245 self.retrieved_tools_handler(sample, RetrieveAdapter::new(index), toolset)
246 }
247
248 pub fn retrieved_tools_handler(
251 mut self,
252 sample: usize,
253 handler: impl rig_core::serve::Serve + 'static,
254 toolset: ToolSet,
255 ) -> Self {
256 self.retrieval_indexes
257 .push((sample, rig_core::serve::ErasedHandler::new(handler)));
258 self.toolset.add_retrievable_tools(toolset);
259 self
260 }
261
262 pub fn run(mut self) -> ToolServerHandle {
264 let owner = self
265 .owner
266 .take()
267 .unwrap_or_else(|| format!("tools#{}", NEXT_REGISTRY.fetch_add(1, Ordering::Relaxed)));
268 let handle = ToolServerHandle(Arc::new(RwLock::new(ToolServerState {
269 owner,
270 retrieval_indexes: Vec::new(),
271 toolset: ToolSet::default(),
272 managed_generations: HashMap::new(),
273 bindings: HashMap::new(),
274 tables: Vec::new(),
275 next_generation: 0,
276 })));
277 handle.extend(self);
278 handle
279 }
280}
281
282#[derive(Clone)]
284pub struct ToolServerHandle(Arc<RwLock<ToolServerState>>);
285
286impl ToolServerHandle {
287 fn state(&self) -> RwLockReadGuard<'_, ToolServerState> {
288 self.0.read().unwrap_or_else(PoisonError::into_inner)
289 }
290
291 fn state_mut(&self) -> RwLockWriteGuard<'_, ToolServerState> {
292 self.0.write().unwrap_or_else(PoisonError::into_inner)
293 }
294
295 pub fn attach(&self, table: &Handlers) {
297 self.state_mut().attach(table);
298 }
299
300 pub fn owner(&self) -> String {
302 self.state().owner.clone()
303 }
304
305 fn register(&self, tool: RegisteredTool) {
306 let mut state = self.state_mut();
307 let name = state.register(tool, true);
308 state.managed_generations.remove(&name);
309 }
310
311 pub fn add_tool<T>(&self, tool: T)
313 where
314 T: Tool + 'static,
315 {
316 self.register(RegisteredTool::from_tool(tool));
317 }
318
319 pub fn add_dynamic_tool(&self, tool: DynamicTool) {
321 self.register(RegisteredTool::from_dynamic(tool));
322 }
323
324 pub fn add_registered_tool(&self, tool: RegisteredTool) {
326 self.register(tool);
327 }
328
329 fn add_managed(&self, tools: Vec<RegisteredTool>) -> HashMap<String, ManagedToolToken> {
330 let mut state = self.state_mut();
331 let mut managed = HashMap::with_capacity(tools.len());
332
333 for tool in tools {
334 if !tool.is_live() {
335 tracing::debug!(
336 tool_name = %tool.name(),
337 "ignored initial registration from disconnected MCP owner"
338 );
339 continue;
340 }
341
342 let name = state.register(tool, true);
343 let token = ManagedToolToken::new();
344 state
345 .managed_generations
346 .insert(name.clone(), token.clone());
347 managed.insert(name, token);
348 }
349
350 managed
351 }
352
353 fn reconcile_managed(
354 &self,
355 mut expected: HashMap<String, ManagedToolToken>,
356 tools: Vec<RegisteredTool>,
357 ) -> HashMap<String, ManagedToolToken> {
358 let mut state = self.state_mut();
359 let mut refreshed = HashMap::with_capacity(tools.len());
360 let mut managed_order = Vec::with_capacity(tools.len());
361 let mut seen = std::collections::HashSet::with_capacity(tools.len());
362
363 state.retire_disconnected_tools();
364
365 for tool in tools {
366 if !tool.is_live() {
367 tracing::debug!(
368 tool_name = %tool.name(),
369 "ignored registration from disconnected MCP owner"
370 );
371 continue;
372 }
373
374 let name = tool.name();
375 if !seen.insert(name.clone()) {
376 tracing::warn!(tool_name = %name, "ignoring duplicate MCP tool definition");
377 continue;
378 }
379 let present = state.toolset.contains(&name);
380 let may_register = match expected.remove(&name) {
381 Some(token) if present => state.managed_generations.get(&name) == Some(&token),
382 Some(_) => true,
383 None => !present,
384 };
385
386 if may_register {
387 state.register(tool, true);
388 let token = ManagedToolToken::new();
389 state
390 .managed_generations
391 .insert(name.clone(), token.clone());
392 refreshed.insert(name.clone(), token);
393 managed_order.push(name);
394 } else {
395 tracing::debug!(
396 tool_name = name,
397 "MCP refresh left a newer same-name registration intact"
398 );
399 }
400 }
401
402 for (name, token) in expected {
403 if state.managed_generations.get(&name) == Some(&token) {
404 state.remove(&name);
405 }
406 }
407
408 for name in managed_order {
409 state.toolset.move_to_end(&name);
410 }
411
412 refreshed
413 }
414
415 pub(crate) fn extend(&self, server: ToolServer) {
418 {
419 let mut state = self.state_mut();
420 for (samples, handler) in server.retrieval_indexes {
421 let n = state.retrieval_indexes.len();
422 let key = HandlerKey::from(format!("{}/retrieve:tools#{n}", state.owner));
423 for table in state.tables() {
424 register_generated(table.register_erased(key.clone(), handler.clone()));
425 }
426 state.retrieval_indexes.push(RetrievalIndex {
427 samples,
428 key,
429 handler,
430 });
431 }
432 }
433 self.add_tools(server.toolset);
434 }
435
436 pub fn add_tools(&self, toolset: ToolSet) {
438 let mut state = self.state_mut();
439 let exposed: Vec<String> = toolset.always_exposed_names().map(str::to_owned).collect();
440 for (name, tool) in toolset.iter() {
441 let always_exposed = exposed.iter().any(|exposed| exposed == name);
442 let name = state.register(tool.clone(), always_exposed);
443 state.managed_generations.remove(&name);
444 }
445 }
446
447 pub fn remove_tool(&self, tool_name: &str) {
449 self.state_mut().remove(tool_name);
450 }
451
452 fn with_registry<R>(&self, f: impl FnOnce(&ToolServerState) -> R) -> R {
455 {
456 let state = self.state();
457 if state.toolset.iter().all(|(_, tool)| tool.is_live()) {
458 return f(&state);
459 }
460 }
461 let mut state = self.state_mut();
462 state.retire_disconnected_tools();
463 f(&state)
464 }
465
466 pub fn snapshot(&self) -> ToolCatalog {
468 ToolCatalog::from_registered(
469 self.with_registry(|state| snapshot_registered_tools(state, &[])),
470 )
471 }
472
473 pub fn toolset(&self) -> ToolSet {
475 self.with_registry(|state| state.toolset.clone())
476 }
477
478 pub async fn tool_defs(
481 &self,
482 prompt: Option<String>,
483 ) -> Result<Vec<Arc<ToolDefinition>>, ToolServerError> {
484 Ok(self.snapshot_tool_defs(prompt).await?.take_definitions())
485 }
486
487 pub fn retrieval_keys(&self) -> Vec<HandlerKey> {
489 self.state()
490 .retrieval_indexes
491 .iter()
492 .map(|index| index.key.clone())
493 .collect()
494 }
495
496 pub fn retrieval_effects(
500 &self,
501 prompt: Option<String>,
502 ) -> Vec<(HandlerKey, rig_core::effect::EffectKind)> {
503 let Some(text) = prompt else {
504 return Vec::new();
505 };
506 let retrieval_indexes = {
507 let state = self.state();
508 state.retrieval_indexes.clone()
509 };
510 retrieval_indexes
511 .into_iter()
512 .map(|index| {
513 let req = rig_core::vector_store::request::VectorSearchRequest::builder()
514 .query(text.clone())
515 .samples(index.samples as u64)
516 .build();
517 (
518 index.key,
519 rig_core::effect::EffectKind::Retrieve {
520 query: rig_core::effect::RetrieveQuery::TopNIds {
521 req: req.map_filter(rig_core::vector_store::request::Filter::interpret),
522 },
523 },
524 )
525 })
526 .collect()
527 }
528
529 pub fn snapshot_with_dynamic(&self, dynamic_tool_ids: &[String]) -> ToolCatalog {
532 ToolCatalog::from_registered(
533 self.with_registry(|state| snapshot_registered_tools(state, dynamic_tool_ids)),
534 )
535 }
536
537 pub(crate) async fn snapshot_tool_defs(
542 &self,
543 prompt: Option<String>,
544 ) -> Result<ToolCatalog, ToolServerError> {
545 let retrieval_indexes = {
546 let state = self.state();
547 state.retrieval_indexes.clone()
548 };
549
550 let dynamic_tool_ids = if let Some(ref text) = prompt {
551 let search_futures = retrieval_indexes.iter().map(|index| {
552 let text = text.clone();
553 let samples = index.samples;
554 let handler = index.handler.clone();
555
556 async move {
557 let req = rig_core::vector_store::request::VectorSearchRequest::builder()
558 .query(text)
559 .samples(samples as u64)
560 .build();
561 let outcome = rig_core::serve::serve_inline(
564 &handler,
565 rig_core::effect::EffectKind::Retrieve {
566 query: rig_core::effect::RetrieveQuery::TopNIds {
567 req: req
568 .map_filter(rig_core::vector_store::request::Filter::interpret),
569 },
570 },
571 )
572 .await
573 .map_err(|report| {
574 rig_core::vector_store::VectorStoreError::DatastoreError(Box::new(report))
575 })?;
576 let ids = match outcome {
577 rig_core::effect::Answered::Documents(
578 rig_core::effect::RetrievedDocuments::Ids(ids),
579 ) => ids.into_iter().map(|(_, id)| id).collect::<Vec<String>>(),
580 other => {
581 return Err(rig_core::vector_store::VectorStoreError::DatastoreError(
582 Box::new(rig_core::error::ErrorReport::new(
583 rig_core::error::ErrorKind::Internal,
584 format!(
585 "tool retrieval answered with a {} outcome",
586 other.family()
587 ),
588 )),
589 ));
590 }
591 };
592
593 Ok::<_, rig_core::vector_store::VectorStoreError>(ids)
594 }
595 });
596
597 futures::future::try_join_all(search_futures)
598 .await
599 .map_err(|e| ToolServerError::DefinitionError(ProviderError::request(e)))?
600 .into_iter()
601 .flatten()
602 .collect::<Vec<String>>()
603 } else {
604 Vec::new()
605 };
606
607 Ok(ToolCatalog::from_registered(self.with_registry(|state| {
608 snapshot_registered_tools(state, &dynamic_tool_ids)
609 })))
610 }
611}
612
613fn snapshot_registered_tools(
614 state: &ToolServerState,
615 dynamic_tool_ids: &[String],
616) -> IndexMap<String, RegisteredTool> {
617 let mut tools = IndexMap::new();
618 let insert = |tools: &mut IndexMap<String, RegisteredTool>, name: &str, warn_missing| {
619 if tools.contains_key(name) {
620 tracing::debug!(
621 tool_name = %name,
622 "dropping duplicate tool definition from the request"
623 );
624 return;
625 }
626 match state.toolset.get(name).cloned() {
627 Some(tool) => {
628 tools.insert(name.to_string(), tool);
629 }
630 None if warn_missing => {
631 tracing::warn!("Tool implementation not found in toolset: {name}");
632 }
633 None => {}
634 }
635 };
636
637 for name in dynamic_tool_ids {
638 insert(&mut tools, name, true);
639 }
640 for name in state.toolset.always_exposed_names() {
641 insert(&mut tools, name, false);
642 }
643 tools
644}
645
646#[cfg(not(target_family = "wasm"))]
647const _: () = {
648 const fn assert_send_sync_static<T: Send + Sync + 'static>() {}
649 assert_send_sync_static::<ToolSet>();
650 assert_send_sync_static::<ToolCatalog>();
651 assert_send_sync_static::<ToolServerHandle>();
652};
653
654#[derive(Debug, thiserror::Error)]
656pub enum ToolServerError {
657 #[error("Failed to retrieve tool definitions: {0}")]
659 DefinitionError(ProviderError),
660}
661
662impl ManagedToolSink for ToolServerHandle {
663 fn add_managed_tools(&self, tools: Vec<DynamicTool>) -> HashMap<String, ManagedToolToken> {
664 self.add_managed(
665 tools
666 .into_iter()
667 .map(RegisteredTool::from_dynamic)
668 .collect(),
669 )
670 }
671
672 fn reconcile_managed_tools(
673 &self,
674 expected: HashMap<String, ManagedToolToken>,
675 tools: Vec<DynamicTool>,
676 ) -> HashMap<String, ManagedToolToken> {
677 self.reconcile_managed(
678 expected,
679 tools
680 .into_iter()
681 .map(RegisteredTool::from_dynamic)
682 .collect(),
683 )
684 }
685}
686
687#[cfg(test)]
688mod tests;