Skip to main content

rig_core/tool/
context.rs

1//! Typed inbound context and explicitly published host-only tool-result metadata.
2//!
3//! ```
4//! use rig_core::tool::{ContextValue, ToolContext};
5//! #[derive(serde::Serialize, serde::Deserialize)]
6//! struct Session(String);
7//! impl ContextValue for Session { const KEY: &'static str = "session"; }
8//! let mut context = ToolContext::new();
9//! context.insert(Session("example".into()))?;
10//! assert_eq!(context.require::<Session>()?.0, "example");
11//! # Ok::<(), rig_core::tool::ToolContextError>(())
12//! ```
13
14use std::any::Any;
15use std::collections::BTreeMap;
16
17use serde::{Deserialize, Serialize, de::DeserializeOwned};
18
19use super::ToolExecutionError;
20use crate::conversation::CallRef;
21
22/// Context passed to every tool execution.
23///
24/// Callers insert typed inbound values with [`insert`](Self::insert). Tools read
25/// those values with [`get`](Self::get) or [`require`](Self::require), and attach
26/// host-only result metadata with [`insert_result`](Self::insert_result). Result
27/// hooks inspect that metadata through [`result`](Self::result). Neither inbound
28/// values nor result metadata are sent to the model.
29///
30/// Every value is **data**: inserting serializes it, reading deserializes it,
31/// and the whole context is itself `Serialize + Deserialize`. Explicit scene
32/// serialization can therefore contain sensitive inbound values and must be
33/// protected by the host. Effect logs record only [`ToolResultContext`]:
34/// values explicitly published through `insert_result`, never inbound slots
35/// or runtime scopes. Replay uses the current dispatch's inbound context;
36/// code must not treat mutations to inbound slots as durable output. Values with
37/// interior sharing (`Arc<Mutex<_>>`, atomics, channels) do not belong here;
38/// they belong to the tool instance.
39///
40/// Registry, server, and agent dispatch clone inbound values once per call.
41/// Map-level mutations (inserting, replacing, or removing typed slots) affect
42/// only that execution. The dispatch surface returns result metadata without
43/// replacing the caller's inbound slots.
44///
45/// Slots use the value type's declared [`ContextValue::KEY`]. Accessors need
46/// no key argument; types must use distinct keys to occupy distinct slots.
47#[derive(Default, Clone, Serialize, Deserialize)]
48pub struct ToolContext {
49    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
50    inbound: BTreeMap<String, serde_json::Value>,
51    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
52    result: BTreeMap<String, serde_json::Value>,
53    /// Live runtime scopes, excluded from serialization and equality.
54    /// Publication clears them before the result is resolved.
55    #[serde(skip)]
56    scopes: Vec<std::sync::Arc<dyn Any + Send + Sync>>,
57}
58
59/// Explicitly published, durable tool-result metadata. Unlike [`ToolContext`],
60/// this contains no inbound credentials or live runtime scopes. Values are
61/// keyed by [`ContextValue::KEY`]; applications own their schema versions.
62#[derive(Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
63#[serde(transparent)]
64pub struct ToolResultContext(BTreeMap<String, serde_json::Value>);
65
66impl std::fmt::Debug for ToolResultContext {
67    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
68        f.debug_tuple("ToolResultContext")
69            .field(&self.0.keys().collect::<Vec<_>>())
70            .finish()
71    }
72}
73
74/// The key [`ToolResultContext::with_at`] keeps its call under.
75const AT: &str = "rig.at";
76
77impl ToolResultContext {
78    /// Read a published value without exposing ambient execution inputs.
79    pub fn get<T: ContextValue>(&self) -> Result<Option<T>, ToolContextError> {
80        get_slot(&self.0)
81    }
82
83    /// Whether nothing was published.
84    pub fn is_empty(&self) -> bool {
85        self.0.is_empty()
86    }
87
88    /// The call these values were kept for with its result
89    /// ([`with_at`](Self::with_at)); `None` when no call was recorded, as
90    /// in a session saved before calls were.
91    pub fn at(&self) -> Option<CallRef> {
92        crate::json_utils::from_value(self.0.get(AT)?).ok()
93    }
94
95    /// These values, kept for the call `at`, so a reply that repeats a
96    /// call id still finds each call's own.
97    #[must_use]
98    pub fn with_at(mut self, at: CallRef) -> Self {
99        if let Ok(value) = serde_json::to_value(at) {
100            self.0.insert(AT.to_owned(), value);
101        }
102        self
103    }
104
105    /// These values as a conversation keeps them with the call's result
106    /// ([`ResultFacts`](crate::conversation::ResultFacts)), for a view to
107    /// draw the call from after a resume: the whole old text of each
108    /// changed file ([`FileChange::before_text`]) left out, since the hunks
109    /// show the change, and, past `max_bytes` of JSON, the largest values
110    /// left out, so a small one such as an exit status stays. The result
111    /// encodes to at most `max_bytes.max(2)`: an empty map's `{}` is the
112    /// floor, kept for any smaller budget.
113    ///
114    /// ```
115    /// use rig_core::tool::{ExitStatus, FileChange, FilesChanged, ToolContext};
116    ///
117    /// let mut context = ToolContext::new();
118    /// context.insert_result(ExitStatus::Exited(0))?;
119    /// let change = FileChange::modified("a.rs", 1, 1).with_before_text("old\n");
120    /// context.insert_result(FilesChanged(vec![change]))?;
121    /// let kept = context.result_context().kept(64 * 1024);
122    /// assert_eq!(kept.get::<ExitStatus>()?, Some(ExitStatus::Exited(0)));
123    /// let changed = kept.get::<FilesChanged>()?.unwrap_or_default();
124    /// assert_eq!(changed.0.first().map(|change| change.before_text.is_none()), Some(true));
125    /// # Ok::<(), rig_core::tool::ToolContextError>(())
126    /// ```
127    ///
128    /// [`FileChange::before_text`]: super::FileChange::before_text
129    #[must_use]
130    pub fn kept(&self, max_bytes: usize) -> Self {
131        let mut kept = self.0.clone();
132        if let Ok(Some(mut changed)) = get_slot::<super::FilesChanged>(&kept) {
133            for change in &mut changed.0 {
134                change.before_text = None;
135            }
136            // A value that decoded encodes again; one that did not stays.
137            insert_slot(&mut kept, changed).ok();
138        }
139        // Each entry's JSON with its `:` and a `,`; the map's braces first.
140        let mut sized: Vec<(usize, String, serde_json::Value)> = kept
141            .into_iter()
142            .filter_map(|(key, value)| {
143                let key_size = serde_json::to_vec(&key).ok()?.len();
144                let size = serde_json::to_vec(&value).ok()?.len();
145                Some((key_size.saturating_add(size).saturating_add(2), key, value))
146            })
147            .collect();
148        sized.sort_by_key(|(size, ..)| *size);
149        let mut room = max_bytes.saturating_sub(2);
150        let mut fits = BTreeMap::new();
151        for (size, key, value) in sized {
152            if size <= room {
153                room = room.saturating_sub(size);
154                fits.insert(key, value);
155            }
156        }
157        Self(fits)
158    }
159}
160
161impl PartialEq for ToolContext {
162    fn eq(&self, other: &Self) -> bool {
163        self.inbound == other.inbound && self.result == other.result
164    }
165}
166
167impl Eq for ToolContext {}
168
169/// Serializable context data with a stable slot key. Distinct value types must
170/// use distinct keys, and persisted keys must remain stable across schema changes.
171/// The derive macro defaults to the type name; `#[context(key = "…")]` overrides it.
172#[diagnostic::on_unimplemented(
173    message = "`{Self}` declares no `ToolContext` key",
174    label = "not a `ContextValue`",
175    note = "derive it (`#[derive(rig::ContextValue)]`, optionally `#[context(key = \"…\")]`) or write `impl ContextValue for {Self} {{ const KEY: &'static str = \"…\"; }}`; a bare `String`, integer or `serde_json::Value` cannot be stored — wrap it in a newtype"
176)]
177pub trait ContextValue: Serialize + DeserializeOwned + 'static {
178    /// The slot this value lives under.
179    const KEY: &'static str;
180}
181
182fn encode<T: ContextValue>(value: &T) -> Result<serde_json::Value, ToolContextError> {
183    serde_json::to_value(value).map_err(|error| ToolContextError::Encode {
184        key: T::KEY,
185        source: error,
186    })
187}
188
189fn decode<T: ContextValue>(value: &serde_json::Value) -> Result<T, ToolContextError> {
190    crate::json_utils::from_value(value).map_err(|error| ToolContextError::Decode {
191        key: T::KEY,
192        source: error,
193    })
194}
195
196/// Replaces a slot after successful encoding, returning the displaced value
197/// only if it decodes as `T`.
198fn insert_slot<T: ContextValue>(
199    map: &mut BTreeMap<String, serde_json::Value>,
200    value: T,
201) -> Result<Option<T>, ToolContextError> {
202    let encoded = encode(&value)?;
203    Ok(map
204        .insert(T::KEY.to_owned(), encoded)
205        .and_then(|previous| decode(&previous).ok()))
206}
207
208/// `Ok(None)` when the slot is empty, `Err(Decode)` when it holds something
209/// that is not a `T`: absence and a shape mismatch are different facts.
210fn get_slot<T: ContextValue>(
211    map: &BTreeMap<String, serde_json::Value>,
212) -> Result<Option<T>, ToolContextError> {
213    map.get(T::KEY).map(decode).transpose()
214}
215
216impl ToolContext {
217    /// Create an empty context.
218    pub const fn new() -> Self {
219        Self {
220            inbound: BTreeMap::new(),
221            result: BTreeMap::new(),
222            scopes: Vec::new(),
223        }
224    }
225
226    /// Insert an inbound typed value, returning the displaced value if it decodes
227    /// as `T`. A differently shaped displaced value is replaced successfully and
228    /// returns `None`; decoding the previous value cannot undo a successful write.
229    ///
230    /// Returns an encoding error if serialization fails, leaving the slot unchanged.
231    pub fn insert<T: ContextValue>(&mut self, value: T) -> Result<Option<T>, ToolContextError> {
232        insert_slot(&mut self.inbound, value)
233    }
234
235    /// Read an inbound typed value: `Ok(None)` when absent, a decode error when
236    /// the stored value does not match `T`.
237    pub fn get<T: ContextValue>(&self) -> Result<Option<T>, ToolContextError> {
238        get_slot(&self.inbound)
239    }
240
241    /// Require an inbound typed value.
242    pub fn require<T: ContextValue>(&self) -> Result<T, ToolContextError> {
243        get_slot(&self.inbound)?.ok_or(ToolContextError::Missing(T::KEY))
244    }
245
246    /// Remove an inbound typed value. The slot is removed even if decoding its
247    /// former value fails.
248    pub fn remove<T: ContextValue>(&mut self) -> Result<Option<T>, ToolContextError> {
249        self.inbound
250            .remove(T::KEY)
251            .map(|value| decode(&value))
252            .transpose()
253    }
254
255    /// Attach host-only metadata to this execution's result.
256    pub fn insert_result<T: ContextValue>(
257        &mut self,
258        value: T,
259    ) -> Result<Option<T>, ToolContextError> {
260        insert_slot(&mut self.result, value)
261    }
262
263    /// Read host-only result metadata.
264    pub fn result<T: ContextValue>(&self) -> Result<Option<T>, ToolContextError> {
265        get_slot(&self.result)
266    }
267
268    /// Whether this context contains the inbound type `T`.
269    pub fn contains<T: ContextValue>(&self) -> bool {
270        self.inbound.contains_key(T::KEY)
271    }
272
273    /// Whether both maps are empty.
274    pub fn is_empty(&self) -> bool {
275        self.inbound.is_empty() && self.result.is_empty()
276    }
277
278    /// Build the snapshot one dispatch runs against: the same inbound values
279    /// and no result metadata. Runtimes call this per tool call so map-level
280    /// mutations inside the call cannot leak into the caller's context.
281    pub fn for_dispatch(&self) -> Self {
282        Self {
283            inbound: self.inbound.clone(),
284            result: BTreeMap::new(),
285            scopes: self.scopes.clone(),
286        }
287    }
288
289    /// Attach one of the driver's scopes for the call (see the field).
290    pub fn with_scope(mut self, scope: std::sync::Arc<dyn Any + Send + Sync>) -> Self {
291        self.scopes.push(scope);
292        self
293    }
294
295    /// Attach the driver's scopes for the call, as the sink carries them.
296    pub fn with_scopes(mut self, scopes: Vec<std::sync::Arc<dyn Any + Send + Sync>>) -> Self {
297        self.scopes.extend(scopes);
298        self
299    }
300
301    /// Returns the first attached scope of type `T`, or `None` if absent.
302    pub fn scope<T: Any + Send + Sync>(&self) -> Option<std::sync::Arc<T>> {
303        self.scopes
304            .iter()
305            .find_map(|scope| std::sync::Arc::downcast::<T>(scope.clone()).ok())
306    }
307
308    /// Drop the scopes: the call is over and the context is data again.
309    pub fn clear_scope(&mut self) {
310        self.scopes.clear();
311    }
312
313    /// Publish the result metadata a dispatch produced (see
314    /// [`Self::for_dispatch`]) while keeping the caller's inbound values.
315    pub fn accept_dispatch_result(&mut self, dispatched: Self) {
316        self.result = dispatched.result;
317    }
318
319    /// Snapshot only the values explicitly published with `insert_result`.
320    pub fn result_context(&self) -> ToolResultContext {
321        ToolResultContext(self.result.clone())
322    }
323
324    /// The values explicitly published with `insert_result`, taken.
325    pub fn into_result_context(self) -> ToolResultContext {
326        ToolResultContext(self.result)
327    }
328
329    /// Restore durable output while preserving this dispatch's inbound values.
330    pub fn with_result_context(mut self, result: ToolResultContext) -> Self {
331        self.result = result.0;
332        self
333    }
334
335    /// Drop the previous dispatch's result metadata before starting another.
336    pub fn clear_dispatch_result(&mut self) {
337        self.result.clear();
338    }
339}
340
341impl std::fmt::Debug for ToolContext {
342    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
343        f.debug_struct("ToolContext")
344            .field("inbound_types", &self.inbound.keys().collect::<Vec<_>>())
345            .field("result_types", &self.result.keys().collect::<Vec<_>>())
346            .finish()
347    }
348}
349
350/// What one dispatch published beside its answer, passed back beside the
351/// sink rather than on the wire. A tool's adapter fills it with the tool's
352/// whole context (a second publish replaces the first); any other layer,
353/// such as a stream rewrite
354/// ([`ErasedHandler::map_stream`](crate::serve::ErasedHandler::map_stream)),
355/// adds single facts with [`insert`](Self::insert).
356#[derive(Debug, Default)]
357pub struct PublishedContext(std::sync::Mutex<Option<ToolContext>>);
358
359impl PublishedContext {
360    /// An empty one, shared between the driver and the sink.
361    pub fn new() -> std::sync::Arc<Self> {
362        std::sync::Arc::new(Self::default())
363    }
364
365    /// The recorder's non-consuming snapshot. Publish before resolving the
366    /// sink; values published after resolution are not part of that outcome.
367    pub fn result_context(&self) -> Option<ToolResultContext> {
368        crate::lock(&self.0)
369            .as_ref()
370            .map(ToolContext::result_context)
371    }
372
373    /// The adapter's write: the context after the tool ran, scopes cleared.
374    /// All publication must finish before resolving the sink. Publishing
375    /// afterward violates the delivery contract: consumers and recorders may
376    /// observe different versions. The slot does not enforce this ordering.
377    pub fn publish(&self, mut context: ToolContext) {
378        context.clear_scope();
379        *crate::lock(&self.0) = Some(context);
380    }
381
382    /// Adds `value` to what is published, beside what is there, as
383    /// [`ToolContext::insert_result`] does, and returns the value it
384    /// replaced. Publish before the dispatch's answer is resolved, as for
385    /// [`publish`](Self::publish).
386    ///
387    /// # Errors
388    ///
389    /// When `value` cannot be encoded; nothing changes then.
390    pub fn insert<T: ContextValue>(&self, value: T) -> Result<Option<T>, ToolContextError> {
391        crate::lock(&self.0)
392            .get_or_insert_with(ToolContext::new)
393            .insert_result(value)
394    }
395
396    /// The driver's read: what was published, if anything, leaving nothing.
397    pub fn take(&self) -> Option<ToolContext> {
398        crate::lock(&self.0).take()
399    }
400}
401
402/// A [`ToolContext`] slot could not be read or written.
403#[derive(Debug, thiserror::Error)]
404pub enum ToolContextError {
405    /// A required typed value was absent.
406    #[error("required tool context value `{0}` was not found")]
407    Missing(&'static str),
408    /// A value could not be represented as JSON.
409    #[error("tool context value `{key}` could not be encoded: {source}")]
410    Encode {
411        /// The slot's type name.
412        key: &'static str,
413        /// The serializer's failure.
414        #[source]
415        source: serde_json::Error,
416    },
417    /// A stored value could not be decoded as the requested type.
418    #[error("tool context value `{key}` could not be decoded: {source}")]
419    Decode {
420        /// The slot's type name.
421        key: &'static str,
422        /// The deserializer's failure.
423        #[source]
424        source: serde_json::Error,
425    },
426}
427
428impl From<ToolContextError> for ToolExecutionError {
429    fn from(error: ToolContextError) -> Self {
430        ToolExecutionError::other(error.to_string()).with_source(error)
431    }
432}
433
434// The context crosses the effect wire: it must serialize and cross threads on
435// every target, browser wasm included.
436const _: fn() = || {
437    fn assert_wire<T: Send + Sync + 'static + Serialize + DeserializeOwned>() {}
438    assert_wire::<ToolContext>();
439    fn assert_shared<T: Send + Sync + 'static>() {}
440    assert_shared::<PublishedContext>();
441};
442
443#[cfg(test)]
444mod tests;
445
446#[cfg(test)]
447mod migrated_tests;