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;