Skip to main content

haest_core/
tool.rs

1//! The tool contract every haest tool implements.
2//!
3//! Tools are provider-neutral: the parameter schema is plain JSON Schema, and a
4//! tool reports both what the MODEL sees (`content`) and an optional canonical
5//! result envelope a host renders (`result`). Each tool states its canonical
6//! `kind` itself ("file.read", "shell.exec", ...), so no host has to guess.
7//!
8//! PLUG POINT: implement [`Tool`] to add a tool; implement [`ToolServices`] to receive
9//! what tools publish, report and log. A [`ToolSource`] (a [`Tools`] list is
10//! one) hands an agent its tools through
11//! [`AgentDeps::tools`](crate::AgentDeps::tools). The loop holds each tool
12//! by a [`ToolRef`].
13//!
14//! The loop gives every call a [`ToolContext`] (working directory, cancel
15//! token, workspace, the host's services) and turns whatever comes back, an
16//! error or a panic included, into exactly one result in history. The
17//! `req_*` / `opt_*` helpers read arguments the way models actually send them,
18//! and [`slug`] makes a name (a file's, an id) from free text.
19
20mod args;
21mod context;
22mod error;
23mod list;
24mod resume;
25#[cfg(test)]
26mod tests;
27mod truncate;
28mod wrap;
29
30use async_trait::async_trait;
31use serde::{Deserialize, Serialize};
32use serde_json::{Map, Value};
33
34pub use args::{input, opt_bool, opt_count, opt_num, opt_str, req_num, req_str, spelled};
35pub use context::ToolContext;
36pub use error::ToolError;
37pub use list::Tools;
38pub use resume::{Attempt, OnResume};
39pub use truncate::{TRUNCATE_CHARS, truncate_middle};
40pub use wrap::{ToolOverride, ToolWrapper};
41
42pub use crate::slug::slug;
43
44use crate::messages::{MediaPart, ToolCall};
45
46/// A tool call's arguments: a JSON object.
47pub type JsonMap = Map<String, Value>;
48
49/// What a tool's run produced.
50///
51/// The model reads `content` (and sees `media`); everything else is for the
52/// host and the loop's accounting. [`ToolOutput::text`] and
53/// [`ToolOutput::error`] cover most tools.
54#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
55#[serde(rename_all = "camelCase")]
56pub struct ToolOutput {
57    /// What the model receives.
58    pub content: String,
59    /// The call failed; `content` says why to the model.
60    #[serde(default)]
61    pub is_error: bool,
62    /// Canonical envelope for a host's transcript (`{"kind": "text" | "shell" | "file" | ...}`);
63    /// None = a text envelope of `content`.
64    #[serde(default, skip_serializing_if = "Option::is_none")]
65    pub result: Option<Value>,
66    /// Images / PDFs the model should SEE, not read about.
67    #[serde(default, skip_serializing_if = "Vec::is_empty")]
68    pub media: Vec<MediaPart>,
69    /// What the tool itself spent (an image model's bill): added to the turn's cost AND charged to the ledger.
70    #[serde(default, skip_serializing_if = "Option::is_none")]
71    pub cost_usd: Option<f64>,
72    /// Spend an agent the tool ran already charged itself (a subagent's model
73    /// calls): added to the turn's cost so the turn cap sees it, never charged twice.
74    #[serde(default, skip_serializing_if = "Option::is_none")]
75    pub child_cost_usd: Option<f64>,
76    /// The tool already fit `content` to its own budget: the generic spill must not touch it.
77    /// Otherwise `content` over [`MAX_TOOL_OUTPUT`]
78    /// characters goes to a file and the model gets a preview.
79    #[serde(default)]
80    pub sized: bool,
81    /// The finished call's title for a host's display, when only the outcome can
82    /// tell ("Notified you: X", "Took you to X"); None = the host's own title for
83    /// the call. The model never sees it.
84    #[serde(default, skip_serializing_if = "Option::is_none")]
85    pub title: Option<String>,
86}
87
88impl ToolOutput {
89    /// A successful result: `content` for the model, nothing else.
90    pub fn text(content: impl Into<String>) -> Self {
91        Self {
92            content: content.into(),
93            ..Default::default()
94        }
95    }
96    /// A failed result: `content` tells the model what went wrong.
97    ///
98    /// The model reads `content` as is, as it would a [`ToolError::Input`].
99    pub fn error(content: impl Into<String>) -> Self {
100        Self {
101            content: content.into(),
102            is_error: true,
103            ..Default::default()
104        }
105    }
106    /// The same output with `result` as the host's envelope.
107    #[must_use]
108    pub fn with_result(mut self, result: Value) -> Self {
109        self.result = Some(result);
110        self
111    }
112    /// The same output with `title` as the host's title for the finished call.
113    #[must_use]
114    pub fn with_title(mut self, title: impl Into<String>) -> Self {
115        self.title = Some(title.into());
116        self
117    }
118}
119
120/// A tool call made by another tool (call `parent_id`): a transcript row of its own, not a model turn.
121///
122/// Reported through [`ToolServices::on_inner_call`]: a `Start`, then an `End`
123/// with the same call.
124#[derive(Debug, Clone)]
125#[non_exhaustive]
126pub enum InnerCallEvent {
127    /// The inner call is about to run.
128    Start {
129        /// The id of the tool call that made it.
130        parent_id: String,
131        /// The inner call.
132        call: ToolCall,
133    },
134    /// The inner call finished.
135    End {
136        /// The id of the tool call that made it.
137        parent_id: String,
138        /// The inner call.
139        call: ToolCall,
140        /// What it produced.
141        output: ToolOutput,
142        /// How long it ran.
143        duration_ms: u64,
144    },
145}
146
147/// What the host offers every tool. All optional: the defaults do nothing.
148///
149/// Set it with [`SharedDeps::with_services`](crate::SharedDeps::with_services);
150/// a tool reaches it through [`ToolContext::services`]. [`NoServices`]
151/// offers nothing.
152#[async_trait]
153pub trait ToolServices: Send + Sync {
154    /// Put bytes where the host's transcript can show them; the URL, or None.
155    async fn publish(&self, _data: Vec<u8>, _media_type: &str) -> Option<String> {
156        None
157    }
158    /// A tool that runs OTHER tools (Code) reports each one here, so the human sees it.
159    fn on_inner_call(&self, _ev: InnerCallEvent) {}
160    /// A line for haest's diagnostic log (what it does under the hood),
161    /// which the human need not see. Default: dropped.
162    fn debug(&self, _message: &str) {}
163}
164
165crate::plug_ref! {
166    /// A [`ToolServices`], shared: what [`SharedDeps::services`](crate::SharedDeps::services)
167    /// and every [`ToolContext`] hold.
168    pub struct ToolServicesRef(dyn ToolServices);
169}
170
171/// Services that offer nothing: publish returns no URL, the rest is dropped.
172#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
173pub struct NoServices;
174
175impl ToolServices for NoServices {}
176
177/// A tool the model can call.
178///
179/// Implement it with `#[async_trait]` (from the `async-trait` crate) and hand
180/// the tool to an agent through a [`ToolSource`]. The model sees `name`,
181/// `description` and `parameters`; the host sees `kind` and
182/// `canonical_input`.
183///
184/// # Examples
185///
186/// ```
187/// use async_trait::async_trait;
188/// use haest_core::{JsonMap, ShutWorkspace, Tool, ToolContext, ToolError, ToolOutput, req_num, tool};
189/// use serde_json::{Value, json};
190///
191/// /// Adds two numbers.
192/// struct Add;
193///
194/// #[async_trait]
195/// impl Tool for Add {
196///     fn name(&self) -> &str {
197///         "Add"
198///     }
199///     fn description(&self) -> String {
200///         "Add two numbers.".into()
201///     }
202///     fn parameters(&self) -> Value {
203///         json!({
204///             "type": "object",
205///             "properties": {"a": {"type": "number"}, "b": {"type": "number"}},
206///             "required": ["a", "b"]
207///         })
208///     }
209///     fn kind(&self) -> &str {
210///         "math.add"
211///     }
212///     fn read_only(&self) -> bool {
213///         true // it changes nothing, so calls may run in parallel
214///     }
215///     async fn execute(&self, input: JsonMap, _ctx: &ToolContext) -> Result<ToolOutput, ToolError> {
216///         let (a, b) = (req_num(&input, "a")?, req_num(&input, "b")?);
217///         Ok(ToolOutput::text((a + b).to_string()))
218///     }
219/// }
220///
221/// # #[tokio::main(flavor = "current_thread")]
222/// # async fn main() -> Result<(), haest_core::BoxError> {
223/// // Outside the loop: a context of its own. The loop builds one per call.
224/// let ctx = ToolContext::new("/", ShutWorkspace);
225/// let input = tool::input(json!({"a": 2, "b": "3"}))?; // models send numbers as strings too
226/// let out = Add.execute(input, &ctx).await?;
227/// assert_eq!(out.content, "5");
228/// # Ok(())
229/// # }
230/// ```
231#[async_trait]
232pub trait Tool: Send + Sync {
233    /// The name the model calls it by. A [`Tools`] list holds one tool per
234    /// name: a tool added under a name already listed replaces that one.
235    fn name(&self) -> &str;
236    /// What the tool does and when to use it, for the model.
237    fn description(&self) -> String;
238    /// One line for the system prompt's tool guide: how to use this tool
239    /// well beside the others (`Use Edit for changes to existing files`).
240    /// The guide lists the line of every tool a call advertises, in the
241    /// list's order ([`tool_guide`](crate::context::tool_guide)). None, the
242    /// default, says nothing: the description is enough.
243    fn prompt_guide(&self) -> Option<String> {
244        None
245    }
246    /// JSON Schema of the input object.
247    fn parameters(&self) -> Value;
248    /// Canonical kind, e.g. "file.read" or "mcp.server.tool".
249    fn kind(&self) -> &str;
250    /// Touches nothing another call could see (no writes, no side effects): may run in parallel.
251    ///
252    /// Consecutive read-only calls of one model response run at the same
253    /// time; any other call runs alone.
254    fn read_only(&self) -> bool {
255        false
256    }
257    /// What a resumed durable run ([`crate::run`]) does with a call of this
258    /// tool that may have run before the stop: it started, and its result
259    /// never landed.
260    ///
261    /// The default: a read-only tool runs again ([`OnResume::Rerun`]), any
262    /// other is answered as interrupted ([`OnResume::Report`]). Only durable
263    /// runs ask; a plain turn never does.
264    fn on_resume(&self) -> OnResume {
265        if self.read_only() {
266            OnResume::Rerun
267        } else {
268            OnResume::Report
269        }
270    }
271    /// Canonical input shape for a host's transcript. Defaults to the raw input.
272    fn canonical_input(&self, input: &JsonMap) -> JsonMap {
273        input.clone()
274    }
275    /// Run one call with the model's arguments.
276    ///
277    /// The model reads the returned [`ToolOutput`]. A result longer than
278    /// [`MAX_TOOL_OUTPUT`] characters goes
279    /// to a file and the model gets a preview, unless [`ToolOutput::sized`] is set.
280    ///
281    /// # Errors
282    ///
283    /// [`ToolError::Input`] for a call the model can fix (its message goes
284    /// back verbatim), [`ToolError::Failed`] for anything else. Either way the
285    /// model gets an error result and the turn goes on; a panic is answered
286    /// the same way, as a failure.
287    ///
288    /// # Cancellation
289    ///
290    /// The loop does not interrupt a running call: a tool that runs for long
291    /// watches [`ToolContext::cancel`] and returns when it fires.
292    async fn execute(&self, input: JsonMap, ctx: &ToolContext) -> Result<ToolOutput, ToolError>;
293}
294
295crate::plug_ref! {
296    /// A [`Tool`], shared: how a [`Tools`] list and the loop hold one.
297    /// Built from the tool itself, or from an `Arc` of one.
298    pub struct ToolRef(dyn Tool);
299    debug(tool, f) {
300        f.debug_tuple("ToolRef").field(&tool.name()).finish()
301    }
302}
303
304/// Where the loop gets its tools, asked again before every model call (deferred
305/// tools and MCP servers change the list mid-conversation).
306///
307/// A [`Tools`] list is a fixed one, every tool advertised.
308pub trait ToolSource: Send + Sync {
309    /// The tools the next model call advertises.
310    fn tools(&self) -> Tools;
311    /// The tools a call may run: the advertised ones, plus any the source keeps
312    /// back (a deferred tool the model calls by name runs instead of failing).
313    fn callable(&self) -> Tools {
314        self.tools()
315    }
316}
317
318crate::plug_ref! {
319    /// A [`ToolSource`], shared: what [`AgentDeps::tools`](crate::AgentDeps::tools) holds.
320    pub struct ToolSourceRef(dyn ToolSource);
321}
322
323/// The most any one tool result may put into the model's context (~5k
324/// tokens), in characters. A longer result goes to a file and the model gets
325/// a preview, unless the tool set [`ToolOutput::sized`].
326pub const MAX_TOOL_OUTPUT: usize = 20_000;