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;