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::{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
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        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
173/// A tool registry under construction; [`ToolServer::run`] turns it into
174/// the shareable [`ToolServerHandle`].
175pub struct ToolServer {
176    owner: Option<String>,
177    /// Retrieval indexes by sample count, keyed once the registry knows its
178    /// owner label.
179    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    /// An empty registry.
191    pub fn new() -> Self {
192        Self {
193            owner: None,
194            retrieval_indexes: Vec::new(),
195            toolset: ToolSet::default(),
196        }
197    }
198
199    /// Name the registry: the owner segment of every key it mints
200    /// (`<owner>/tool:<name>#<n>`, `<owner>/retrieve:tools#<n>`). The
201    /// default is `tools#<m>` from a per-process counter, distinct per
202    /// registry; name it when a host shares one table between registries and
203    /// wants to read the keys.
204    pub fn owner(mut self, label: impl Into<String>) -> Self {
205        self.owner = Some(label.into());
206        self
207    }
208
209    /// Add a typed tool.
210    pub fn tool(mut self, tool: impl Tool + 'static) -> Self {
211        self.toolset.add_tool(tool);
212        self
213    }
214
215    /// Add a runtime-defined tool.
216    pub fn dynamic_tool(mut self, tool: DynamicTool) -> Self {
217        self.toolset.add_dynamic_tool(tool);
218        self
219    }
220
221    /// Add runtime-defined tools.
222    pub fn dynamic_tools(self, tools: Vec<DynamicTool>) -> Self {
223        tools.into_iter().fold(self, Self::dynamic_tool)
224    }
225
226    /// Add a registration built elsewhere.
227    pub fn registered_tool(mut self, tool: RegisteredTool) -> Self {
228        self.toolset.add_registered_tool(tool);
229        self
230    }
231
232    /// Add retrievable tools: `sample` of them are advertised per request,
233    /// chosen by `index`.
234    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    /// Add tools selected per request by a retrieval-family handler answering
243    /// `TopNIds`, registered under a generated retrieval index key.
244    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    /// Start the registry.
257    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/// The shareable, runtime-mutable tool registry.
277#[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    /// Publish every registration onto `table`, now and as they change.
290    pub fn attach(&self, table: &Handlers) {
291        self.state_mut().attach(table);
292    }
293
294    /// The registry's label: the owner segment of the keys it mints.
295    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    /// Add a typed tool.
306    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    /// Add a runtime-defined tool.
314    pub fn add_dynamic_tool(&self, tool: DynamicTool) {
315        self.register(RegisteredTool::from_dynamic(tool));
316    }
317
318    /// Add a registration built elsewhere.
319    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    /// Add `server`'s tools and retrieval indexes, keyed under this
410    /// registry's owner (`server`'s own owner label is not used).
411    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    /// Merge a tool set's registrations.
431    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    /// Remove the tool named `tool_name`.
440    pub fn remove_tool(&self, tool_name: &str) {
441        self.state_mut().remove(tool_name);
442    }
443
444    /// Run `f` over the registry, retiring disconnected tools first: under
445    /// the read lock while every tool is live, the write lock otherwise.
446    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    /// The always-exposed registrations, pinned.
459    pub fn snapshot(&self) -> ToolCatalog {
460        ToolCatalog::from_registered(
461            self.with_registry(|state| snapshot_registered_tools(state, &[])),
462        )
463    }
464
465    /// A fork of the registry's tool set.
466    pub fn toolset(&self) -> ToolSet {
467        self.with_registry(|state| state.toolset.clone())
468    }
469
470    /// Retrieve advertised definitions for `prompt`, returning retrieval failures
471    /// or incompatible result shapes as [`ProviderError::Request`]. The retrieval
472    /// queries run inline on the registry's own handlers: this is a registry
473    /// read, while the engine dispatches the same queries through its handlers.
474    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    /// Return registered retrieval index keys in registration order.
499    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    /// Build one `TopNIds` effect per retrieval index for the supplied prompt.
508    /// Returns no effects without a prompt; pass returned IDs to
509    /// [`Self::snapshot_with_dynamic`] after dispatch.
510    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    /// One `TopNIds` retrieval per index for `prompt`, none without one.
521    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    /// Pin retrieved tools in ID order, then always-exposed tools in registration
547    /// order. Deduplicates names and skips missing registrations.
548    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
555/// The tool ids a `TopNIds` retrieval answered, or the report for any other
556/// answer.
557pub(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;