//! A tool as data, [`ToolInfo`]; what one call of it is lent, //! [`ToolCall`]; how the call ends, [`ToolOutput`] or [`ToolError`]; and //! [`next_step`], which splits a long call into steps. use std::fmt; use std::future::Future; use std::pin::Pin; use std::task::{Context, Poll}; use crate::file::{Answer, Request, Requests}; use crate::{DirEntry, FileFuture, Stat}; /// A tool described as data, which a [`Pack`](crate::Pack) lists in /// [`Pack::tools`](crate::Pack::tools). #[derive(Clone, Debug, PartialEq, Eq)] #[non_exhaustive] pub struct ToolInfo { /// The tool's name within its Pack: 1 to 64 bytes of lowercase ASCII /// letters, digits, `-`, `_`, and `.`, such as `fetch`. The Host puts /// the Pack id before it to form the tool's id, as in `url/fetch`. pub name: String, /// The name a model calls the tool by: 1 to 64 bytes of ASCII letters, /// digits, `_`, and `-`. `None` lets the Host derive it from the /// tool's id, as `url_fetch` from `url/fetch`. pub wire_name: Option, /// What the tool does, for a model to read: non-empty, at most 65536 /// bytes. pub description: String, /// The tool's parameters: the JSON text of a JSON Schema whose value /// is an object, at most 65536 bytes. pub parameters: String, /// Whether a call of the tool changes files of its run. Of the calls /// that one reply of a model asks for, the Host runs a call of such a /// tool by itself, after the calls the reply lists before it, so two /// changes of one reply happen in the order the reply lists them. pub changes_files: bool, } impl ToolInfo { /// A tool named `name`, with the description a model reads and the /// JSON text of its parameter schema, under the wire name the Host /// derives. It says that its calls change no file. #[must_use] pub fn new( name: impl Into, description: impl Into, parameters: impl Into, ) -> ToolInfo { ToolInfo { name: name.into(), wire_name: None, description: description.into(), parameters: parameters.into(), changes_files: false, } } /// Sets the name a model calls the tool by. #[must_use] pub fn wire_name(mut self, wire_name: impl Into) -> ToolInfo { self.wire_name = Some(wire_name.into()); self } /// Says that a call of the tool changes files of its run. A tool /// that awaits [`ToolCall::write`], [`ToolCall::append`], /// [`ToolCall::mkdir`], [`ToolCall::remove`], [`ToolCall::rename`], or /// [`ToolCall::copy`] says so. #[must_use] pub fn changes_files(mut self) -> ToolInfo { self.changes_files = true; self } } /// What one tool call lends its [`Pack`](crate::Pack): the tool's name, /// the call's arguments, and the files of the call's run. It borrows from /// the call, so a Pack cannot keep it past the call's end. /// /// The file methods ask the Host, so the run's policy applies to every /// operation, and one the policy denies fails like any other. Each /// method returns a [`FileFuture`]. Awaiting it ends the step: the Host /// performs the operation, and a later step of the call goes on with the /// answer. So a file method is awaited inside the future that /// [`Pack::call`](crate::Pack::call) returns. Code that runs in /// `Pack::call` itself, before that future is first polled, can make the /// future of a file method and cannot have its answer. /// /// [`write`](ToolCall::write), [`append`](ToolCall::append), /// [`mkdir`](ToolCall::mkdir), [`remove`](ToolCall::remove), /// [`rename`](ToolCall::rename), and [`copy`](ToolCall::copy) change the /// run's files. A tool that awaits one of them says so in its /// [`ToolInfo`], with [`ToolInfo::changes_files`]. /// /// A path names a file of the run, with `/` between its segments, is at /// most 4096 bytes long, and is taken from the run's root whether or not /// it begins with `/`. #[derive(Clone, Copy, Debug)] pub struct ToolCall<'a> { state: &'a CallState, } impl<'a> ToolCall<'a> { /// The handle over one call's state. pub(crate) fn new(state: &'a CallState) -> ToolCall<'a> { ToolCall { state } } /// The name of the called tool, as [`ToolInfo::name`] gave it. A Pack /// with several tools matches on it to pick one. #[must_use] pub fn tool(&self) -> &'a str { &self.state.tool } /// The call's arguments: the JSON text of the value the caller passed. /// The Plugin parses it with a JSON library of its own. #[must_use] pub fn arguments(&self) -> &'a str { &self.state.arguments } /// What `path` names. A link is reported as a link, not as what it /// leads to. /// /// The future resolves to a [`FileError`](crate::FileError) when /// nothing is at `path`, when the run's policy denies the read, or /// when the Host fails it. pub fn stat(&self, path: &str) -> FileFuture<'a, Stat> { self.ask(Request::Stat(path.to_owned()), |answer| answer.stat) } /// The entries of the directory at `path`, in no promised order. An /// entry that is a link is reported as a link. /// /// The future resolves to a [`FileError`](crate::FileError) when /// `path` names no directory, when the run's policy denies the read, /// or when the Host fails it. pub fn list(&self, path: &str) -> FileFuture<'a, Vec> { self.ask(Request::List(path.to_owned()), |answer| answer.entries) } /// The whole contents of the file at `path`. The Host holds them in /// memory, so a tool checks [`stat`](ToolCall::stat) first, or uses /// [`read_range`](ToolCall::read_range), when the file may be large. /// /// The future resolves to a [`FileError`](crate::FileError) when /// `path` names no file, when the run's policy denies the read, or /// when the Host fails it. pub fn read(&self, path: &str) -> FileFuture<'a, Vec> { self.read_range(path, 0, u64::MAX) } /// Up to `len` bytes of the file at `path`, from the byte `offset` /// on: fewer when the file ends first, and none when `offset` is at /// or past its end. /// /// The future resolves to a [`FileError`](crate::FileError) when /// `path` names no file, when the run's policy denies the read, or /// when the Host fails it. pub fn read_range(&self, path: &str, offset: u64, len: u64) -> FileFuture<'a, Vec> { let path = path.to_owned(); self.ask(Request::Read { path, offset, len }, |answer| answer.bytes) } /// Writes `bytes` as the whole contents of the file at `path`. The /// file is made when it is absent, with each directory on the way to /// it. One write takes at most /// [`RV_MAX_WRITE`](crate::sys::RV_MAX_WRITE) bytes, which is 16 MiB, /// so a tool writes a longer file with one `write` and then /// [`append`](ToolCall::append) for each further part. /// /// The future resolves to a [`FileError`](crate::FileError) when /// `path` names a directory, when `bytes` is longer than one write /// takes, when the run's policy denies the write, or when the Host /// fails it. pub fn write(&self, path: &str, bytes: impl Into>) -> FileFuture<'a, ()> { let (path, bytes) = (path.to_owned(), bytes.into()); self.ask(Request::Write { path, bytes }, drop) } /// Adds `bytes` to the end of the file at `path`. The file is made /// when it is absent, as [`write`](ToolCall::write) makes it. One /// append takes as many bytes as one write does. /// /// The future resolves to a [`FileError`](crate::FileError) when /// `path` names a directory, when `bytes` is longer than one append /// takes, when the run's policy denies the append, or when the Host /// fails it. pub fn append(&self, path: &str, bytes: impl Into>) -> FileFuture<'a, ()> { let (path, bytes) = (path.to_owned(), bytes.into()); self.ask(Request::Append { path, bytes }, drop) } /// Makes a directory at `path`. With `recursive` each absent /// directory on the way to it is made too, and without it every one /// of them must be there. /// /// The future resolves to a [`FileError`](crate::FileError) when /// something is at `path` already, when the run's policy denies the /// change, or when the Host fails it. pub fn mkdir(&self, path: &str, recursive: bool) -> FileFuture<'a, ()> { let path = path.to_owned(); self.ask(Request::Mkdir { path, recursive }, drop) } /// Removes the file or the directory at `path`. With `recursive` a /// directory goes with everything in it, and without it a directory /// must be empty. /// /// The future resolves to a [`FileError`](crate::FileError) when /// nothing is at `path`, when a directory has entries and /// `recursive` is off, when the run's policy denies the change, or /// when the Host fails it. pub fn remove(&self, path: &str, recursive: bool) -> FileFuture<'a, ()> { let path = path.to_owned(); self.ask(Request::Remove { path, recursive }, drop) } /// Moves the file or the directory at `from` to `to`. A directory /// moves with everything in it, and each absent directory on the way /// to `to` is made. /// /// The future resolves to a [`FileError`](crate::FileError) when /// nothing is at `from`, when the run's policy denies the change, or /// when the Host fails it. pub fn rename(&self, from: &str, to: &str) -> FileFuture<'a, ()> { let (from, to) = (from.to_owned(), to.to_owned()); self.ask(Request::Rename { from, to }, drop) } /// Copies the file at `from` to `to`. The file at `to` is made when /// it is absent, with each directory on the way to it. /// /// The future resolves to a [`FileError`](crate::FileError) when /// `from` names no file, when `to` names a directory, when the run's /// policy denies the change, or when the Host fails it. pub fn copy(&self, from: &str, to: &str) -> FileFuture<'a, ()> { let (from, to) = (from.to_owned(), to.to_owned()); self.ask(Request::Copy { from, to }, drop) } /// The future of `request`, which resolves to what `pick` takes out /// of the Host's answer. fn ask(self, request: Request, pick: fn(Answer) -> T) -> FileFuture<'a, T> { FileFuture::new(&self.state.requests, request, pick) } } /// What one tool call keeps for all of its steps: the copies of its tool /// name and arguments that a [`ToolCall`] reads, and the file requests /// its file methods make. #[derive(Debug)] pub(crate) struct CallState { pub(crate) tool: String, pub(crate) arguments: String, /// The call's file requests: its futures queue them, and its steps /// take them to the Host and bring the answers back. pub(crate) requests: Requests, } impl CallState { /// The state of a call of `tool` with `arguments`, which has asked /// for no file. pub(crate) fn new(tool: &str, arguments: &str) -> CallState { CallState { tool: tool.to_owned(), arguments: arguments.to_owned(), requests: Requests::default(), } } } /// The text a successful tool call returns, and whether the Plugin /// vouches for it. #[derive(Clone, Debug, PartialEq, Eq)] pub struct ToolOutput { text: String, trusted: bool, } impl ToolOutput { /// An output the Plugin vouches for: it wrote every byte of `text`, /// which a model reads as is. #[must_use] pub fn trusted(text: impl Into) -> ToolOutput { ToolOutput { text: text.into(), trusted: true, } } /// An output that may hold data an attacker can influence, such as /// the contents of a file or a web page. The Host marks it before a /// model reads it. #[must_use] pub fn untrusted(text: impl Into) -> ToolOutput { ToolOutput { text: text.into(), trusted: false, } } /// The output's text. #[must_use] pub fn text(&self) -> &str { &self.text } /// Whether the Plugin vouches for the text. #[must_use] pub fn is_trusted(&self) -> bool { self.trusted } } /// Why a tool call failed. #[derive(Clone, Copy, Debug, PartialEq, Eq)] #[non_exhaustive] pub enum ToolErrorKind { /// The arguments do not match the tool's parameters. InvalidArguments, /// What the tool reaches refused or failed the request. Backend, /// The request never got through. Transport, /// Any other reason. Other, } /// A failed tool call: why it failed, and a message a model can read that /// says what went wrong. #[derive(Clone, Debug, PartialEq, Eq)] pub struct ToolError { kind: ToolErrorKind, message: String, } impl ToolError { /// A failure of `kind` with `message`, which a model reads, so it /// names what was wrong and holds nothing private. #[must_use] pub fn new(kind: ToolErrorKind, message: impl Into) -> ToolError { ToolError { kind, message: message.into(), } } /// Why the call failed. #[must_use] pub fn kind(&self) -> ToolErrorKind { self.kind } /// The message a model reads. #[must_use] pub fn message(&self) -> &str { &self.message } } impl fmt::Display for ToolError { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.write_str(&self.message) } } impl std::error::Error for ToolError {} /// Ends the current step of a tool call and goes on at the next one. /// /// A [`Pack::call`](crate::Pack::call) future that does a long job awaits /// this every so often, so that no step works for long and the Host can /// abandon the call between two steps. Awaiting a file method of the /// [`ToolCall`] ends the step too, so a job needs this only where it /// works for long between two file methods. pub fn next_step() -> NextStep { NextStep { ended: false } } /// The future [`next_step`] returns: `Pending` for one poll, then `Ready`. #[derive(Debug)] #[must_use = "a future does nothing unless it is awaited"] pub struct NextStep { /// Whether the one `Pending` has been returned. ended: bool, } impl Future for NextStep { type Output = (); fn poll(mut self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<()> { if self.ended { return Poll::Ready(()); } self.ended = true; Poll::Pending } } #[cfg(test)] mod tests { use std::future::Future; use std::pin::{Pin, pin}; use std::task::{Context, Poll, Waker}; use super::{CallState, ToolCall, ToolError, ToolErrorKind, ToolInfo, ToolOutput, next_step}; use crate::file::Request; use crate::{FileError, FileErrorKind}; #[test] fn a_tool_info_keeps_what_it_was_built_from_and_has_no_wire_name_until_one_is_set() { let info = ToolInfo::new("fetch", "Fetches a page.", r#"{"type":"object"}"#); assert_eq!(info.name, "fetch"); assert_eq!(info.description, "Fetches a page."); assert_eq!(info.parameters, r#"{"type":"object"}"#); assert_eq!(info.wire_name, None); assert_eq!(info.wire_name("Fetch").wire_name.as_deref(), Some("Fetch")); } #[test] fn a_tool_info_says_its_calls_change_files_only_once_it_is_told_so() { let info = ToolInfo::new("save", "Saves a page.", r#"{"type":"object"}"#); assert!(!info.changes_files); assert!(info.changes_files().changes_files); } #[test] fn a_tool_call_lends_the_tool_name_and_the_arguments() { let state = CallState::new("fetch", r#"{"url":"x"}"#); let call = ToolCall::new(&state); assert_eq!(call.tool(), "fetch"); assert_eq!(call.arguments(), r#"{"url":"x"}"#); } /// Polls `future` once and returns the request the call's next send /// hands the Host. fn asked(state: &CallState, mut future: impl Future + Unpin) -> Request { let mut cx = Context::from_waker(Waker::noop()); assert!(Pin::new(&mut future).poll(&mut cx).is_pending()); let mut asked = None; state.requests.send(|request| { asked = Some(request.clone()); Ok(()) }); // The Host answers, so that the next request can go out. state .requests .answered(Err(FileError::new(FileErrorKind::Other, "no file"))); asked.expect("the first poll queued a request") } #[test] fn each_file_method_asks_for_what_it_was_called_with() { let state = CallState::new("fetch", "{}"); let call = ToolCall::new(&state); assert_eq!( asked(&state, call.stat("/a")), Request::Stat("/a".to_owned()) ); assert_eq!(asked(&state, call.list("/")), Request::List("/".to_owned())); assert_eq!( asked(&state, call.read("/a")), Request::Read { path: "/a".to_owned(), offset: 0, len: u64::MAX } ); assert_eq!( asked(&state, call.read_range("/a", 1, 3)), Request::Read { path: "/a".to_owned(), offset: 1, len: 3 } ); } #[test] fn each_method_that_changes_files_asks_for_what_it_was_called_with() { let state = CallState::new("save", "{}"); let call = ToolCall::new(&state); let (path, from, to) = ("/a".to_owned(), "/a".to_owned(), "/b".to_owned()); assert_eq!( asked(&state, call.write("/a", "text")), Request::Write { path: path.clone(), bytes: b"text".to_vec() } ); assert_eq!( asked(&state, call.append("/a", vec![0xff_u8])), Request::Append { path: path.clone(), bytes: vec![0xff] } ); assert_eq!( asked(&state, call.mkdir("/a", true)), Request::Mkdir { path: path.clone(), recursive: true } ); assert_eq!( asked(&state, call.remove("/a", false)), Request::Remove { path, recursive: false } ); assert_eq!( asked(&state, call.rename("/a", "/b")), Request::Rename { from: from.clone(), to: to.clone() } ); assert_eq!( asked(&state, call.copy("/a", "/b")), Request::Copy { from, to } ); } #[test] fn a_file_method_copies_its_path_when_its_future_is_made() { let state = CallState::new("fetch", "{}"); let call = ToolCall::new(&state); let future = { let path = String::from("/gone/before/the/poll"); call.read(&path) }; assert_eq!( asked(&state, future), Request::Read { path: "/gone/before/the/poll".to_owned(), offset: 0, len: u64::MAX } ); } #[test] fn an_output_carries_its_text_and_whether_it_is_trusted() { let trusted = ToolOutput::trusted("done"); assert_eq!((trusted.text(), trusted.is_trusted()), ("done", true)); let untrusted = ToolOutput::untrusted("page text"); assert_eq!( (untrusted.text(), untrusted.is_trusted()), ("page text", false) ); } #[test] fn an_error_carries_its_kind_and_displays_its_message() { let error = ToolError::new(ToolErrorKind::InvalidArguments, "url is missing"); assert_eq!(error.kind(), ToolErrorKind::InvalidArguments); assert_eq!(error.message(), "url is missing"); assert_eq!(error.to_string(), "url is missing"); } #[test] fn next_step_is_pending_for_one_poll_and_then_ready() { let mut step = pin!(next_step()); let mut cx = Context::from_waker(Waker::noop()); assert_eq!(step.as_mut().poll(&mut cx), Poll::Pending); assert_eq!(step.as_mut().poll(&mut cx), Poll::Ready(())); } }