1use std::collections::HashMap;
15use std::sync::{
16 Arc, PoisonError, RwLock, RwLockReadGuard, RwLockWriteGuard, Weak,
17 atomic::{AtomicU64, Ordering},
18};
19
20use crate::bus::Registrar;
21use indexmap::IndexMap;
22use rig_core::error::ProviderError;
23use rig_core::serve::adapters::RetrieveAdapter;
24use rig_core::{
25 effect::Key,
26 effect::{HandlerKey, family},
27 vector_store::{VectorStoreIndex, request::DynamicSearchFilter},
28 wasm_compat::{WasmCompatSend, WasmCompatSync},
29};
30
31use crate::{
32 completion::ToolDefinition,
33 tool::{
34 DynamicTool, RegisteredTool, Tool, ToolCatalog, ToolContext, ToolDispatch, ToolLease,
35 ToolResult, ToolSet, execute_tool,
36 },
37};
38
39static NEXT_REGISTRY: AtomicU64 = AtomicU64::new(0);
41
42#[derive(Clone)]
45struct RetrievalIndex {
46 samples: usize,
47 key: HandlerKey,
48 handler: rig_core::serve::ErasedHandler,
49}
50
51struct PendingRetrievalIndex {
54 samples: usize,
55 index: usize,
56 handler: rig_core::serve::ErasedHandler,
57}
58
59struct LeaseToken {
62 registry: Weak<RwLock<ToolServerState>>,
63}
64
65impl Drop for LeaseToken {
66 fn drop(&mut self) {
67 let Some(registry) = self.registry.upgrade() else {
68 return;
69 };
70 if let Ok(mut state) = registry.try_write() {
74 state.sweep_retired();
75 }
76 }
77}
78
79struct RetiredGeneration {
81 key: HandlerKey,
82 lease: Weak<LeaseToken>,
83}
84
85struct ToolServerState {
86 owner: String,
88 registry: Weak<RwLock<ToolServerState>>,
90 retrieval_indexes: Vec<RetrievalIndex>,
91 toolset: ToolSet,
92 leases: HashMap<String, Arc<LeaseToken>>,
94 bindings: HashMap<HandlerKey, Weak<LeaseToken>>,
97 retired: Vec<RetiredGeneration>,
98 managed_generations: HashMap<String, ManagedToolToken>,
99 buses: Vec<Registrar>,
101 next_generation: u64,
102}
103
104impl ToolServerState {
105 fn generation_key(&mut self, name: &str) -> Key<family::Tool> {
106 let n = self.next_generation;
107 self.next_generation += 1;
108 Key::new_unchecked(HandlerKey::from(format!("{}/tool:{name}#{n}", self.owner)))
109 }
110
111 fn lease(&self) -> Arc<LeaseToken> {
112 Arc::new(LeaseToken {
113 registry: self.registry.clone(),
114 })
115 }
116
117 fn publish(&self, tool: &RegisteredTool) {
118 for bus in &self.buses {
119 crate::agent::drive::register_generated(
120 bus.register_erased(tool.key().raw().clone(), tool.handler().clone()),
121 );
122 }
123 }
124
125 fn unpublish(&self, key: &HandlerKey) {
126 for bus in &self.buses {
127 bus.deregister(key);
128 }
129 }
130
131 fn retire(&mut self, name: &str) {
134 if let (Some(tool), Some(lease)) = (self.toolset.get(name), self.leases.remove(name)) {
135 self.retired.push(RetiredGeneration {
136 key: tool.key().raw().clone(),
137 lease: Arc::downgrade(&lease),
138 });
139 drop(lease);
142 }
143 }
144
145 fn sweep_retired(&mut self) {
146 let retired = std::mem::take(&mut self.retired);
147 let mut kept = Vec::with_capacity(retired.len());
148 for retired in retired {
149 if !self
150 .bindings
151 .get(&retired.key)
152 .is_some_and(|owner| Weak::ptr_eq(owner, &retired.lease))
153 {
154 continue;
155 }
156 if retired.lease.strong_count() == 0 {
157 self.unpublish(&retired.key);
158 self.bindings.remove(&retired.key);
159 } else {
160 kept.push(retired);
161 }
162 }
163 self.retired = kept;
164 self.buses.retain(|bus| !bus.is_closed());
165 }
166
167 fn register(&mut self, tool: RegisteredTool, always_exposed: bool) -> String {
169 let name = tool.name();
170 let tool = if tool.has_default_key() {
174 let key = self.generation_key(&name);
175 tool.with_key(key)
176 } else {
177 tool
178 };
179 let same_key = self
183 .toolset
184 .get(&name)
185 .is_some_and(|live| live.key() == tool.key());
186 if !same_key {
187 self.retire(&name);
188 }
189 let lease = self
190 .leases
191 .get(&name)
192 .cloned()
193 .unwrap_or_else(|| self.lease());
194 self.bindings
195 .insert(tool.key().raw().clone(), Arc::downgrade(&lease));
196 self.leases.insert(name.clone(), lease);
197 self.publish(&tool);
198 if always_exposed {
199 self.toolset.add_registered_tool(tool);
200 } else {
201 let mut set = ToolSet::default();
202 set.add_registered_tool(tool);
203 self.toolset.add_retrievable_tools(set);
204 }
205 self.sweep_retired();
206 name
207 }
208
209 fn remove(&mut self, name: &str) {
210 self.retire(name);
211 self.toolset.remove_tool(name);
212 self.managed_generations.remove(name);
213 self.sweep_retired();
214 }
215
216 fn retire_disconnected_tools(&mut self) {
217 let disconnected = self
218 .toolset
219 .names()
220 .filter(|name| self.toolset.get(name).is_none_or(|tool| !tool.is_live()))
221 .map(str::to_owned)
222 .collect::<Vec<_>>();
223
224 for name in disconnected {
225 self.remove(&name);
226 tracing::debug!(tool_name = %name, "retired disconnected tool registration");
227 }
228 self.sweep_retired();
229 }
230
231 fn attach(&mut self, bus: &Registrar) {
232 for (name, tool) in self.toolset.iter() {
233 let owns_binding = self.leases.get(name).is_some_and(|lease| {
234 self.bindings
235 .get(tool.key().raw())
236 .is_some_and(|owner| Weak::ptr_eq(owner, &Arc::downgrade(lease)))
237 });
238 if !owns_binding {
239 continue;
240 }
241 crate::agent::drive::register_generated(
242 bus.register_erased(tool.key().raw().clone(), tool.handler().clone()),
243 );
244 }
245 for index in &self.retrieval_indexes {
246 crate::agent::drive::register_generated(
247 bus.register_erased(index.key.clone(), index.handler.clone()),
248 );
249 }
250 self.buses.push(bus.clone());
251 }
252}
253
254pub use rig_core::tool::{ManagedToolSink, ManagedToolToken};
255
256pub struct ToolServer {
259 owner: Option<String>,
260 retrieval_indexes: Vec<PendingRetrievalIndex>,
261 toolset: ToolSet,
262 next_index: usize,
263}
264
265impl Default for ToolServer {
266 fn default() -> Self {
267 Self::new()
268 }
269}
270
271impl ToolServer {
272 pub fn new() -> Self {
274 Self {
275 owner: None,
276 retrieval_indexes: Vec::new(),
277 toolset: ToolSet::default(),
278 next_index: 0,
279 }
280 }
281
282 pub fn owner(mut self, label: impl Into<String>) -> Self {
288 self.owner = Some(label.into());
289 self
290 }
291
292 pub fn tool(mut self, tool: impl Tool + 'static) -> Self {
294 self.toolset.add_tool(tool);
295 self
296 }
297
298 pub fn dynamic_tool(mut self, tool: DynamicTool) -> Self {
300 self.toolset.add_dynamic_tool(tool);
301 self
302 }
303
304 pub fn dynamic_tools(self, tools: Vec<DynamicTool>) -> Self {
306 tools.into_iter().fold(self, Self::dynamic_tool)
307 }
308
309 pub fn registered_tool(mut self, tool: RegisteredTool) -> Self {
311 self.toolset.add_registered_tool(tool);
312 self
313 }
314
315 pub fn retrieved_tools<I, F>(mut self, sample: usize, index: I, toolset: ToolSet) -> Self
318 where
319 I: VectorStoreIndex<Filter = F> + 'static,
320 F: DynamicSearchFilter + WasmCompatSend + WasmCompatSync + 'static,
321 {
322 let n = self.next_index;
323 self.next_index += 1;
324 self.retrieval_indexes.push(PendingRetrievalIndex {
325 samples: sample,
326 index: n,
327 handler: rig_core::serve::ErasedHandler::new(RetrieveAdapter::new(index)),
328 });
329 self.toolset.add_retrievable_tools(toolset);
330 self
331 }
332
333 pub fn retrieved_tools_handler(
336 mut self,
337 sample: usize,
338 handler: impl rig_core::serve::Serve + 'static,
339 toolset: ToolSet,
340 ) -> Self {
341 let n = self.next_index;
342 self.next_index += 1;
343 self.retrieval_indexes.push(PendingRetrievalIndex {
344 samples: sample,
345 index: n,
346 handler: rig_core::serve::ErasedHandler::new(handler),
347 });
348 self.toolset.add_retrievable_tools(toolset);
349 self
350 }
351
352 pub fn run(self) -> ToolServerHandle {
354 let owner = self
355 .owner
356 .unwrap_or_else(|| format!("tools#{}", NEXT_REGISTRY.fetch_add(1, Ordering::Relaxed)));
357 let retrieval_indexes = self
358 .retrieval_indexes
359 .into_iter()
360 .map(|pending| RetrievalIndex {
361 samples: pending.samples,
362 key: HandlerKey::from(format!("{owner}/retrieve:tools#{}", pending.index)),
363 handler: pending.handler,
364 })
365 .collect();
366 let registry = Arc::new_cyclic(|registry| {
367 RwLock::new(ToolServerState {
368 owner,
369 registry: registry.clone(),
370 retrieval_indexes,
371 toolset: ToolSet::default(),
372 leases: HashMap::new(),
373 bindings: HashMap::new(),
374 retired: Vec::new(),
375 managed_generations: HashMap::new(),
376 buses: Vec::new(),
377 next_generation: 0,
378 })
379 });
380 let handle = ToolServerHandle(registry);
381 let exposed: Vec<String> = self
382 .toolset
383 .always_exposed_names()
384 .map(str::to_owned)
385 .collect();
386 {
387 let mut state = handle.state_mut();
388 for (name, tool) in self.toolset.iter() {
389 state.register(tool.clone(), exposed.iter().any(|exposed| exposed == name));
390 }
391 }
392 handle
393 }
394}
395
396#[derive(Clone)]
398pub struct ToolServerHandle(Arc<RwLock<ToolServerState>>);
399
400impl ToolServerHandle {
401 fn state(&self) -> RwLockReadGuard<'_, ToolServerState> {
402 self.0.read().unwrap_or_else(PoisonError::into_inner)
403 }
404
405 fn state_mut(&self) -> RwLockWriteGuard<'_, ToolServerState> {
406 self.0.write().unwrap_or_else(PoisonError::into_inner)
407 }
408
409 pub fn attach(&self, bus: &Registrar) {
411 self.state_mut().attach(bus);
412 }
413
414 pub fn owner(&self) -> String {
416 self.state().owner.clone()
417 }
418
419 fn register(&self, tool: RegisteredTool) {
420 let mut state = self.state_mut();
421 let name = state.register(tool, true);
422 state.managed_generations.remove(&name);
423 }
424
425 pub fn add_tool<T>(&self, tool: T)
427 where
428 T: Tool + 'static,
429 {
430 self.register(RegisteredTool::from_tool(tool));
431 }
432
433 pub fn add_dynamic_tool(&self, tool: DynamicTool) {
435 self.register(RegisteredTool::from_dynamic(tool));
436 }
437
438 pub fn add_registered_tool(&self, tool: RegisteredTool) {
440 self.register(tool);
441 }
442
443 fn add_managed(&self, tools: Vec<RegisteredTool>) -> HashMap<String, ManagedToolToken> {
444 let mut state = self.state_mut();
445 let mut managed = HashMap::with_capacity(tools.len());
446
447 for tool in tools {
448 if !tool.is_live() {
449 tracing::debug!(
450 tool_name = %tool.name(),
451 "ignored initial registration from disconnected MCP owner"
452 );
453 continue;
454 }
455
456 let name = state.register(tool, true);
457 let token = ManagedToolToken::new();
458 state
459 .managed_generations
460 .insert(name.clone(), token.clone());
461 managed.insert(name, token);
462 }
463
464 managed
465 }
466
467 fn reconcile_managed(
468 &self,
469 mut expected: HashMap<String, ManagedToolToken>,
470 tools: Vec<RegisteredTool>,
471 ) -> HashMap<String, ManagedToolToken> {
472 let mut state = self.state_mut();
473 let mut refreshed = HashMap::with_capacity(tools.len());
474 let mut managed_order = Vec::with_capacity(tools.len());
475 let mut seen = std::collections::HashSet::with_capacity(tools.len());
476
477 state.retire_disconnected_tools();
478
479 for tool in tools {
480 if !tool.is_live() {
481 tracing::debug!(
482 tool_name = %tool.name(),
483 "ignored registration from disconnected MCP owner"
484 );
485 continue;
486 }
487
488 let name = tool.name();
489 if !seen.insert(name.clone()) {
490 tracing::warn!(tool_name = %name, "ignoring duplicate MCP tool definition");
491 continue;
492 }
493 let present = state.toolset.contains(&name);
494 let may_register = match expected.remove(&name) {
495 Some(token) if present => state.managed_generations.get(&name) == Some(&token),
496 Some(_) => true,
497 None => !present,
498 };
499
500 if may_register {
501 state.register(tool, true);
502 let token = ManagedToolToken::new();
503 state
504 .managed_generations
505 .insert(name.clone(), token.clone());
506 refreshed.insert(name.clone(), token);
507 managed_order.push(name);
508 } else {
509 tracing::debug!(
510 tool_name = name,
511 "MCP refresh left a newer same-name registration intact"
512 );
513 }
514 }
515
516 for (name, token) in expected {
517 if state.managed_generations.get(&name) == Some(&token) {
518 state.remove(&name);
519 }
520 }
521
522 for name in managed_order {
523 state.toolset.move_to_end(&name);
524 }
525
526 refreshed
527 }
528
529 pub fn add_tools(&self, toolset: ToolSet) {
531 let mut state = self.state_mut();
532 let exposed: Vec<String> = toolset.always_exposed_names().map(str::to_owned).collect();
533 for (name, tool) in toolset.iter() {
534 let always_exposed = exposed.iter().any(|exposed| exposed == name);
535 let name = state.register(tool.clone(), always_exposed);
536 state.managed_generations.remove(&name);
537 }
538 }
539
540 pub fn remove_tool(&self, tool_name: &str) {
542 let mut state = self.state_mut();
543 state.remove(tool_name);
544 state.sweep_retired();
545 }
546
547 pub async fn execute(
550 &self,
551 tool_name: &str,
552 args: &str,
553 context: &mut ToolContext,
554 ) -> ToolResult {
555 context.clear_dispatch_result();
556 let dispatch = self.execute_scoped(tool_name, args, context).await;
557 dispatch.publish_to(context)
558 }
559
560 fn with_registry<R>(&self, f: impl FnOnce(&ToolServerState) -> R) -> R {
561 let mut state = self.state_mut();
562 state.retire_disconnected_tools();
563 f(&state)
564 }
565
566 pub(crate) async fn execute_scoped(
567 &self,
568 tool_name: &str,
569 args: &str,
570 context: &ToolContext,
571 ) -> ToolDispatch {
572 let tool = self.with_registry(|state| state.toolset.get(tool_name).cloned());
573 execute_tool(tool_name, args.to_string(), tool, context).await
574 }
575
576 pub fn snapshot(&self) -> ToolCatalog {
578 let (tools, leases) = self.with_registry(|state| snapshot_registered_tools(state, &[]));
579 ToolCatalog::from_registered(tools).with_leases(leases)
580 }
581
582 pub fn static_tool_defs(&self) -> Vec<ToolDefinition> {
584 let mut snapshot = self.snapshot();
585 snapshot.take_definitions()
586 }
587
588 pub fn toolset(&self) -> ToolSet {
590 self.with_registry(|state| state.toolset.clone())
591 }
592
593 pub async fn tool_defs(
596 &self,
597 prompt: Option<String>,
598 ) -> Result<Vec<ToolDefinition>, ToolServerError> {
599 Ok(self.snapshot_tool_defs(prompt).await?.take_definitions())
600 }
601
602 pub fn retrieval_keys(&self) -> Vec<HandlerKey> {
604 self.state()
605 .retrieval_indexes
606 .iter()
607 .map(|index| index.key.clone())
608 .collect()
609 }
610
611 pub fn retrieval_effects(
615 &self,
616 prompt: Option<String>,
617 ) -> Vec<(HandlerKey, rig_core::effect::EffectKind)> {
618 let Some(text) = prompt else {
619 return Vec::new();
620 };
621 let retrieval_indexes = {
622 let state = self.state();
623 state.retrieval_indexes.clone()
624 };
625 retrieval_indexes
626 .into_iter()
627 .map(|index| {
628 let req = rig_core::vector_store::request::VectorSearchRequest::builder()
629 .query(text.clone())
630 .samples(index.samples as u64)
631 .build();
632 (
633 index.key,
634 rig_core::effect::EffectKind::Retrieve {
635 query: rig_core::effect::RetrieveQuery::TopNIds {
636 req: req.map_filter(rig_core::vector_store::request::Filter::interpret),
637 },
638 },
639 )
640 })
641 .collect()
642 }
643
644 pub fn snapshot_with_dynamic(&self, dynamic_tool_ids: &[String]) -> ToolCatalog {
647 let (tools, leases) =
648 self.with_registry(|state| snapshot_registered_tools(state, dynamic_tool_ids));
649 ToolCatalog::from_registered(tools).with_leases(leases)
650 }
651
652 pub(crate) async fn snapshot_tool_defs(
657 &self,
658 prompt: Option<String>,
659 ) -> Result<ToolCatalog, ToolServerError> {
660 let retrieval_indexes = {
661 let state = self.state();
662 state.retrieval_indexes.clone()
663 };
664
665 let dynamic_tool_ids = if let Some(ref text) = prompt {
666 let search_futures = retrieval_indexes.iter().map(|index| {
667 let text = text.clone();
668 let samples = index.samples;
669 let handler = index.handler.clone();
670
671 async move {
672 let req = rig_core::vector_store::request::VectorSearchRequest::builder()
673 .query(text)
674 .samples(samples as u64)
675 .build();
676 let outcome = rig_core::serve::serve_inline(
679 &handler,
680 rig_core::effect::EffectKind::Retrieve {
681 query: rig_core::effect::RetrieveQuery::TopNIds {
682 req: req
683 .map_filter(rig_core::vector_store::request::Filter::interpret),
684 },
685 },
686 )
687 .await
688 .map_err(|report| {
689 rig_core::vector_store::VectorStoreError::DatastoreError(Box::new(report))
690 })?;
691 let ids = match outcome {
692 rig_core::effect::Outcome::Documents(
693 rig_core::effect::RetrievedDocuments::Ids(ids),
694 ) => ids.into_iter().map(|(_, id)| id).collect::<Vec<String>>(),
695 other => {
696 return Err(rig_core::vector_store::VectorStoreError::DatastoreError(
697 Box::new(rig_core::error::ErrorReport::new(
698 rig_core::error::ErrorKind::Internal,
699 format!(
700 "tool retrieval answered with a {} outcome",
701 other.family()
702 ),
703 )),
704 ));
705 }
706 };
707
708 Ok::<_, rig_core::vector_store::VectorStoreError>(ids)
709 }
710 });
711
712 futures::future::try_join_all(search_futures)
713 .await
714 .map_err(|e| ToolServerError::DefinitionError(ProviderError::request(e)))?
715 .into_iter()
716 .flatten()
717 .collect::<Vec<String>>()
718 } else {
719 Vec::new()
720 };
721
722 let (tools, leases) =
723 self.with_registry(|state| snapshot_registered_tools(state, &dynamic_tool_ids));
724
725 Ok(ToolCatalog::from_registered(tools).with_leases(leases))
726 }
727}
728
729fn snapshot_registered_tools(
730 state: &ToolServerState,
731 dynamic_tool_ids: &[String],
732) -> (IndexMap<String, RegisteredTool>, Vec<ToolLease>) {
733 let mut tools = IndexMap::new();
734 let mut leases = Vec::new();
735 let mut insert = |tools: &mut IndexMap<String, RegisteredTool>, name: &str, warn_missing| {
736 if tools.contains_key(name) {
737 tracing::debug!(
738 tool_name = %name,
739 "dropping duplicate tool definition from the request"
740 );
741 return;
742 }
743 match state.toolset.get(name).cloned() {
744 Some(tool) => {
745 if let Some(lease) = state.leases.get(name) {
746 leases.push(lease.clone() as ToolLease);
747 }
748 tools.insert(name.to_string(), tool);
749 }
750 None if warn_missing => {
751 tracing::warn!("Tool implementation not found in toolset: {name}");
752 }
753 None => {}
754 }
755 };
756
757 for name in dynamic_tool_ids {
758 insert(&mut tools, name, true);
759 }
760 for name in state.toolset.always_exposed_names() {
761 insert(&mut tools, name, false);
762 }
763 (tools, leases)
764}
765
766#[cfg(not(target_family = "wasm"))]
767const _: () = {
768 const fn assert_send_sync_static<T: Send + Sync + 'static>() {}
769 assert_send_sync_static::<ToolSet>();
770 assert_send_sync_static::<ToolCatalog>();
771 assert_send_sync_static::<ToolServerHandle>();
772};
773
774#[derive(Debug, thiserror::Error)]
776pub enum ToolServerError {
777 #[error("Failed to retrieve tool definitions: {0}")]
779 DefinitionError(ProviderError),
780}
781
782impl ManagedToolSink for ToolServerHandle {
783 fn add_managed_tools(&self, tools: Vec<DynamicTool>) -> HashMap<String, ManagedToolToken> {
784 self.add_managed(
785 tools
786 .into_iter()
787 .map(RegisteredTool::from_dynamic)
788 .collect(),
789 )
790 }
791
792 fn reconcile_managed_tools(
793 &self,
794 expected: HashMap<String, ManagedToolToken>,
795 tools: Vec<DynamicTool>,
796 ) -> HashMap<String, ManagedToolToken> {
797 self.reconcile_managed(
798 expected,
799 tools
800 .into_iter()
801 .map(RegisteredTool::from_dynamic)
802 .collect(),
803 )
804 }
805}
806
807#[cfg(test)]
808mod tests;