Skip to main content

rig_agent/tool/
server.rs

1//! Mutable tool registries that publish their registrations to attached
2//! handler tables.
3//!
4//! A registration under the default `tool:<name>` key is served under a fresh
5//! generation key (`<owner>/tool:<name>#<n>`); an explicit key is used
6//! verbatim. A replaced generation leaves the tables at once: a request
7//! catalog keeps the registration it pinned and runs it directly.
8//!
9//! ```
10//! use rig_agent::tool::server::ToolServer;
11//! let registry = ToolServer::new().owner("assistant").run();
12//! assert!(registry.snapshot().is_empty());
13//! ```
14
15use 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
38/// The per-process counter behind a registry's default owner label.
39static NEXT_REGISTRY: AtomicU64 = AtomicU64::new(0);
40
41/// A retrieval index registered for tool retrieval: its key and how many
42/// tools to sample.
43#[derive(Clone)]
44struct RetrievalIndex {
45    samples: usize,
46    key: HandlerKey,
47    handler: rig_core::serve::ErasedHandler,
48}
49
50struct ToolServerState {
51    /// The registry's label, the owner segment of every key it mints.
52    owner: String,
53    retrieval_indexes: Vec<RetrievalIndex>,
54    toolset: ToolSet,
55    managed_generations: HashMap<String, ManagedToolToken>,
56    /// The name whose registration was published last under each key: an
57    /// explicit key can be reused across names.
58    bindings: HashMap<HandlerKey, String>,
59    /// The tables this registry publishes onto, while they live.
60    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    /// The tables still alive, forgetting the dropped ones.
72    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    /// Take the key of `name`'s registration off the tables, unless a later
93    /// registration was published under it.
94    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    /// Insert a registration under a fresh generation, publishing it.
107    fn register(&mut self, tool: RegisteredTool, always_exposed: bool) -> String {
108        let name = tool.name();
109        // A registration under the default `tool:<name>` key gets a fresh
110        // generation; an explicit key (a replayer's recorded key, a host's
111        // own) is served as given.
112        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        // An explicit key that is the live key replaces the handler in place.
119        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
179/// A tool registry under construction; [`ToolServer::run`] turns it into
180/// the shareable [`ToolServerHandle`].
181pub struct ToolServer {
182    owner: Option<String>,
183    /// Retrieval indexes by sample count, keyed once the registry knows its
184    /// owner label.
185    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    /// An empty registry.
197    pub fn new() -> Self {
198        Self {
199            owner: None,
200            retrieval_indexes: Vec::new(),
201            toolset: ToolSet::default(),
202        }
203    }
204
205    /// Name the registry: the owner segment of every key it mints
206    /// (`<owner>/tool:<name>#<n>`, `<owner>/retrieve:tools#<n>`). The
207    /// default is `tools#<m>` from a per-process counter, distinct per
208    /// registry; name it when a host shares one table between registries and
209    /// wants to read the keys.
210    pub fn owner(mut self, label: impl Into<String>) -> Self {
211        self.owner = Some(label.into());
212        self
213    }
214
215    /// Add a typed tool.
216    pub fn tool(mut self, tool: impl Tool + 'static) -> Self {
217        self.toolset.add_tool(tool);
218        self
219    }
220
221    /// Add a runtime-defined tool.
222    pub fn dynamic_tool(mut self, tool: DynamicTool) -> Self {
223        self.toolset.add_dynamic_tool(tool);
224        self
225    }
226
227    /// Add runtime-defined tools.
228    pub fn dynamic_tools(self, tools: Vec<DynamicTool>) -> Self {
229        tools.into_iter().fold(self, Self::dynamic_tool)
230    }
231
232    /// Add a registration built elsewhere.
233    pub fn registered_tool(mut self, tool: RegisteredTool) -> Self {
234        self.toolset.add_registered_tool(tool);
235        self
236    }
237
238    /// Add retrievable tools: `sample` of them are advertised per request,
239    /// chosen by `index`.
240    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    /// Add tools selected per request by a retrieval-family handler answering
249    /// `TopNIds`, registered under a generated retrieval index key.
250    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    /// Start the registry.
263    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/// The shareable, runtime-mutable tool registry.
283#[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    /// Publish every registration onto `table`, now and as they change.
296    pub fn attach(&self, table: &Handlers) {
297        self.state_mut().attach(table);
298    }
299
300    /// The registry's label: the owner segment of the keys it mints.
301    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    /// Add a typed tool.
312    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    /// Add a runtime-defined tool.
320    pub fn add_dynamic_tool(&self, tool: DynamicTool) {
321        self.register(RegisteredTool::from_dynamic(tool));
322    }
323
324    /// Add a registration built elsewhere.
325    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    /// Add `server`'s tools and retrieval indexes, keyed under this
416    /// registry's owner (`server`'s own owner label is not used).
417    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    /// Merge a tool set's registrations.
437    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    /// Remove the tool named `tool_name`.
448    pub fn remove_tool(&self, tool_name: &str) {
449        self.state_mut().remove(tool_name);
450    }
451
452    /// Run `f` over the registry, retiring disconnected tools first: under
453    /// the read lock while every tool is live, the write lock otherwise.
454    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    /// The always-exposed registrations, pinned.
467    pub fn snapshot(&self) -> ToolCatalog {
468        ToolCatalog::from_registered(
469            self.with_registry(|state| snapshot_registered_tools(state, &[])),
470        )
471    }
472
473    /// A fork of the registry's tool set.
474    pub fn toolset(&self) -> ToolSet {
475        self.with_registry(|state| state.toolset.clone())
476    }
477
478    /// Retrieve advertised definitions for `prompt`, returning retrieval failures
479    /// or incompatible result shapes as definition errors.
480    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    /// Return registered retrieval index keys in registration order.
488    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    /// Build one `TopNIds` effect per retrieval index for the supplied prompt.
497    /// Returns no effects without a prompt; pass returned IDs to
498    /// [`Self::snapshot_with_dynamic`] after dispatch.
499    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    /// Pin retrieved tools in ID order, then always-exposed tools in registration
530    /// order. Deduplicates names and skips missing registrations.
531    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    /// The registrations a request with `prompt` advertises, answering the
538    /// retrieval queries inline on the registry's own handlers. This is the
539    /// standalone registry read ([`ToolServerHandle::tool_defs`]); the
540    /// engine dispatches the same queries through its handlers instead.
541    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                    // Retrieval for advertisement runs inline on the registry's
562                    // own handler: it is a registry read, not a run effect.
563                    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/// Errors from reading the registry.
655#[derive(Debug, thiserror::Error)]
656pub enum ToolServerError {
657    /// The advertised definitions could not be computed.
658    #[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;