Skip to main content

graphrt_core/
tool.rs

1//! Tool contract shared by the `tool` node, the `agent` node and tool
2//! providers (native Rust tools, MCP servers, HTTP tools...).
3
4use std::fmt;
5use std::sync::Arc;
6
7use futures::future::BoxFuture;
8use serde::{Deserialize, Serialize};
9
10use crate::value::Value;
11
12/// Description of a callable tool, exposed to models for tool calling.
13#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
14pub struct ToolSpec {
15    /// Unique name within a [`ToolRuntime`] (e.g. `search` or `github.create_issue`).
16    pub name: String,
17    pub description: String,
18    /// JSON Schema of the arguments object.
19    pub parameters: serde_json::Value,
20}
21
22/// Result of a tool call.
23#[derive(Clone, Debug, Default, PartialEq)]
24pub struct ToolOutput {
25    /// Text handed back to a model.
26    pub text: String,
27    /// Structured result, if the tool returns one.
28    pub data: Value,
29    /// Whether the tool reported an error (the agent loop may still continue).
30    pub is_error: bool,
31    /// Images shown to the model next to `text` (see [`check_images`] for limits).
32    pub images: Vec<ToolImage>,
33}
34
35impl ToolOutput {
36    pub fn text(text: impl Into<String>) -> Self {
37        Self { text: text.into(), ..Self::default() }
38    }
39
40    pub fn error(text: impl Into<String>) -> Self {
41        Self { text: text.into(), is_error: true, ..Self::default() }
42    }
43
44    /// Attach an image.
45    pub fn with_image(mut self, image: ToolImage) -> Self {
46        self.images.push(image);
47        self
48    }
49}
50
51/// Most images one tool result may carry.
52pub const MAX_TOOL_IMAGES: usize = 4;
53/// Largest decoded size of one tool result image, in bytes (5 MiB).
54pub const MAX_TOOL_IMAGE_BYTES: usize = 5 * 1024 * 1024;
55/// Media types accepted for tool result images (supported by every built-in provider).
56pub const TOOL_IMAGE_MEDIA_TYPES: &[&str] = &["image/png", "image/jpeg", "image/webp", "image/gif"];
57
58/// An image returned by a tool.
59///
60/// Serialized as `{"media_type", "data_base64"}` or `{"url"}` (the plugin
61/// protocol's `tool.call` `images` entries).
62#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
63#[serde(untagged)]
64pub enum ToolImage {
65    /// Inline bytes, base64 encoded (standard alphabet).
66    Base64 { media_type: String, data_base64: String },
67    /// A remote image (`https://` only).
68    Url { url: String },
69}
70
71impl ToolImage {
72    /// An inline PNG from base64 text.
73    pub fn png(data_base64: impl Into<String>) -> Self {
74        Self::Base64 { media_type: "image/png".into(), data_base64: data_base64.into() }
75    }
76
77    /// An inline JPEG from base64 text.
78    pub fn jpeg(data_base64: impl Into<String>) -> Self {
79        Self::Base64 { media_type: "image/jpeg".into(), data_base64: data_base64.into() }
80    }
81
82    /// The image as a URL: `data:<media_type>;base64,<data>` or the remote URL.
83    pub fn to_url(&self) -> String {
84        match self {
85            ToolImage::Base64 { media_type, data_base64 } => format!("data:{media_type};base64,{data_base64}"),
86            ToolImage::Url { url } => url.clone(),
87        }
88    }
89
90    /// Check this image against the media type, encoding and size limits.
91    pub fn check(&self) -> Result<(), ToolImageError> {
92        match self {
93            ToolImage::Url { url } => {
94                if url.len() > 8 && url.get(..8).is_some_and(|scheme| scheme.eq_ignore_ascii_case("https://")) {
95                    Ok(())
96                } else {
97                    Err(ToolImageError::new("image URLs must start with https:// (send inline images as base64)"))
98                }
99            }
100            ToolImage::Base64 { media_type, data_base64 } => {
101                if !TOOL_IMAGE_MEDIA_TYPES.contains(&media_type.as_str()) {
102                    return Err(ToolImageError::new(format!(
103                        "image media type `{media_type}` is not supported (use {})",
104                        TOOL_IMAGE_MEDIA_TYPES.join(", ")
105                    )));
106                }
107                let decoded = base64_decoded_len(data_base64)
108                    .ok_or_else(|| ToolImageError::new("image data is not valid base64"))?;
109                if decoded == 0 {
110                    return Err(ToolImageError::new("image data is empty"));
111                }
112                if decoded > MAX_TOOL_IMAGE_BYTES {
113                    return Err(ToolImageError::new(format!(
114                        "image is {decoded} bytes, above the {MAX_TOOL_IMAGE_BYTES}-byte limit"
115                    )));
116                }
117                Ok(())
118            }
119        }
120    }
121}
122
123/// A tool result image that breaks a limit.
124#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
125#[error("{0}")]
126pub struct ToolImageError(pub String);
127
128impl ToolImageError {
129    fn new(message: impl Into<String>) -> Self {
130        Self(message.into())
131    }
132}
133
134/// Check the images of one tool result: at most [`MAX_TOOL_IMAGES`], each
135/// passing [`ToolImage::check`].
136pub fn check_images(images: &[ToolImage]) -> Result<(), ToolImageError> {
137    if images.len() > MAX_TOOL_IMAGES {
138        return Err(ToolImageError::new(format!(
139            "{} images in one tool result, above the limit of {MAX_TOOL_IMAGES}",
140            images.len()
141        )));
142    }
143    for (index, image) in images.iter().enumerate() {
144        image.check().map_err(|e| ToolImageError::new(format!("image #{index}: {e}")))?;
145    }
146    Ok(())
147}
148
149/// Decoded length of standard base64 text (padding optional), or `None` when
150/// the text is not base64. Validates without allocating.
151fn base64_decoded_len(text: &str) -> Option<usize> {
152    let bytes = text.as_bytes();
153    let body = bytes.strip_suffix(b"==").or_else(|| bytes.strip_suffix(b"=")).unwrap_or(bytes);
154    let alphabet = |b: &u8| b.is_ascii_alphanumeric() || *b == b'+' || *b == b'/';
155    if !body.iter().all(alphabet) {
156        return None;
157    }
158    let padded = body.len() != bytes.len();
159    if padded && bytes.len() % 4 != 0 {
160        return None;
161    }
162    match body.len() % 4 {
163        1 => None,
164        rest => Some(body.len() / 4 * 3 + rest.saturating_sub(1)),
165    }
166}
167
168/// Error calling a tool (transport, unknown tool...).
169#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
170#[error("tool `{tool}`: {message}")]
171pub struct ToolError {
172    pub tool: String,
173    pub message: String,
174}
175
176/// A source of tools.
177pub trait ToolRuntime: Send + Sync + fmt::Debug {
178    /// Tools currently available.
179    fn list(&self) -> BoxFuture<'_, Result<Vec<ToolSpec>, ToolError>>;
180    /// Invoke a tool with a JSON arguments object.
181    fn call<'a>(&'a self, name: &'a str, arguments: serde_json::Value) -> BoxFuture<'a, Result<ToolOutput, ToolError>>;
182}
183
184/// Service registered in [`crate::node::Services`]: named tool providers
185/// (e.g. `builtin`, `mcp:github`). Nodes reference tools as `provider/tool`.
186#[derive(Clone, Default)]
187pub struct ToolRegistry {
188    providers: indexmap::IndexMap<String, Arc<dyn ToolRuntime>>,
189}
190
191impl fmt::Debug for ToolRegistry {
192    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
193        f.debug_list().entries(self.providers.keys()).finish()
194    }
195}
196
197impl ToolRegistry {
198    pub fn new() -> Self {
199        Self::default()
200    }
201
202    pub fn add(&mut self, provider: impl Into<String>, runtime: Arc<dyn ToolRuntime>) -> &mut Self {
203        self.providers.insert(provider.into(), runtime);
204        self
205    }
206
207    pub fn get(&self, provider: &str) -> Option<&Arc<dyn ToolRuntime>> {
208        self.providers.get(provider)
209    }
210
211    pub fn providers(&self) -> impl Iterator<Item = (&str, &Arc<dyn ToolRuntime>)> {
212        self.providers.iter().map(|(k, v)| (k.as_str(), v))
213    }
214}
215
216#[cfg(test)]
217mod tests {
218    use super::*;
219
220    #[test]
221    fn constructors_have_no_images() {
222        assert!(ToolOutput::text("a").images.is_empty());
223        let err = ToolOutput::error("b");
224        assert!(err.is_error && err.images.is_empty());
225        let out = ToolOutput::text("shot").with_image(ToolImage::png("aGVsbG8="));
226        assert_eq!(out.images.len(), 1);
227    }
228
229    #[test]
230    fn image_urls() {
231        assert_eq!(ToolImage::png("AAAA").to_url(), "data:image/png;base64,AAAA");
232        assert_eq!(ToolImage::Url { url: "https://x/a.png".into() }.to_url(), "https://x/a.png");
233    }
234
235    #[test]
236    fn serde_shapes() {
237        let images: Vec<ToolImage> = serde_json::from_value(serde_json::json!([
238            {"media_type": "image/png", "data_base64": "AAAA"},
239            {"url": "https://x/a.png"}
240        ]))
241        .unwrap();
242        assert_eq!(images[0], ToolImage::png("AAAA"));
243        assert_eq!(images[1], ToolImage::Url { url: "https://x/a.png".into() });
244        assert!(serde_json::from_value::<ToolImage>(serde_json::json!({"data": "AAAA"})).is_err());
245    }
246
247    #[test]
248    fn base64_lengths() {
249        assert_eq!(base64_decoded_len("aGVsbG8="), Some(5));
250        assert_eq!(base64_decoded_len("aGVsbG8"), Some(5));
251        assert_eq!(base64_decoded_len("aGVsbA=="), Some(4));
252        assert_eq!(base64_decoded_len("aGVs"), Some(3));
253        assert_eq!(base64_decoded_len("aGVsb"), None);
254        assert_eq!(base64_decoded_len("aGV="), Some(2));
255        assert_eq!(base64_decoded_len("aG V"), None);
256        assert_eq!(base64_decoded_len("aGVsbG8=="), None);
257        assert_eq!(base64_decoded_len(""), Some(0));
258    }
259
260    #[test]
261    fn limits_are_enforced() {
262        assert!(check_images(&[ToolImage::png("aGVsbG8="), ToolImage::jpeg("aGVs")]).is_ok());
263        let too_many = vec![ToolImage::png("aGVs"); MAX_TOOL_IMAGES + 1];
264        assert!(check_images(&too_many).unwrap_err().to_string().contains("limit of 4"));
265        let bmp = ToolImage::Base64 { media_type: "image/bmp".into(), data_base64: "aGVs".into() };
266        assert!(check_images(&[bmp]).unwrap_err().to_string().contains("image/bmp"));
267        assert!(ToolImage::png("not base64!").check().is_err());
268        assert!(ToolImage::png("").check().is_err());
269        let big = "A".repeat((MAX_TOOL_IMAGE_BYTES / 3 + 1) * 4);
270        assert!(ToolImage::png(big).check().unwrap_err().to_string().contains("limit"));
271        let exact = "A".repeat(MAX_TOOL_IMAGE_BYTES / 3 * 4);
272        assert!(ToolImage::png(exact).check().is_ok());
273        assert!(ToolImage::Url { url: "http://x/a.png".into() }.check().is_err());
274        assert!(ToolImage::Url { url: "data:image/png;base64,AAAA".into() }.check().is_err());
275        assert!(ToolImage::Url { url: "HTTPS://x/a.png".into() }.check().is_ok());
276    }
277}