From f2719fff1a9178ed2717702c3082c00fcc99a806 Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Sun, 15 Nov 2026 11:08:26 -0800 Subject: [PATCH 01/13] Say what Write, StrReplace, and Delete wait for `AGENTS.md` gains one rule. Write, StrReplace, and Delete wait for file methods of the SDK that return futures, and `Source` becomes async with them. - No code changes. --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index feefc84..ed51ba9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,6 +27,7 @@ Anything else gets a qualified lowercase name, such as Rust's built-in test harn - Behavior changes ship with tests in the same change. Preserve behavior tests during refactors. - The Plugin crate depends on `runvil-plugin-sdk` and outside libraries alone, and writes no `unsafe`. The SDK owns the C boundary. - A tool reads files only through `Source` (`crates/plugin-std/src/source.rs`), which the call's `ToolCall` implements, so every read goes through the Host and the run's policy applies to it. A test runs a tool's own code over the SDK's `testing::Files` tree, or over `FakeSource` (`crates/plugin-std/src/fake.rs`) for what that tree cannot hold. +- Write, StrReplace, and Delete wait for file methods of the SDK that return futures, and `Source` becomes async with them. Each file operation of a tool is to become an effect that the Harness records. - A tool's description and parameter schema come from its JSON file under `crates/plugin-std/schemas`. `EDITS.md` beside them records every difference from Cursor's definition, and a change to a JSON file changes `EDITS.md` with it. - A tool that does a long job awaits `next_step()` after each bounded slice of work, as Grep does every 32 files or directories and every 2 MiB read, so that no step of its call works for long and the Host can abandon the call between two steps. - A Plugin shares its process with the Host, so nothing here installs process-global state, such as a panic hook (`clippy.toml` bans `std::panic::set_hook`), and nothing starts a thread that outlives the Plugin's unload. What every run shares lives in the Plugin instance and never in a `static`, so an unload frees it. From c7ee62cb29e359a3da57a28b90c000fda2fbd381 Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Tue, 17 Nov 2026 23:35:08 -0800 Subject: [PATCH 02/13] Make `Source` async over the file futures of SDK 0.5 Contract 0.5 answers a file request in a later step of the call, so each file method of `ToolCall` returns a future. The pin of `runvil-plugin-sdk` moves to 0.5.0, the four methods of `Source` become `async fn`, and Read, ListDir, and Grep await them. `walk` takes the `Source` in place of its `list` closure. - `Source` declares its methods as `async fn` and puts no bound on their futures. `read_file`, `list_directory`, `walk`, `root_file`, and `visit` become async to await them. - The three implementations of `Source` in tests answer at once. Each expects `clippy::unused_async_trait_impl`, with its reason. - `block_on` moves to `fake.rs`, and the tests of `read`, `dir`, `grep`, and `pack` share it. `Lister` in the tests of `dir` wraps a closure as a `Source`, so the eleven walks over listings written by hand keep their closures and go through `walk_listed`. - Each file operation ends a step of its call. A search over 1000 files in one directory takes `2 + FILES + FILES / 32` steps before its last step, and a test holds that number. - Grep pauses every `slice_entries` files or directories, and the pause by bytes read goes. `slice_bytes`, `since_bytes`, and `SLICE_BYTES` go with the test of that pause. - A new test shows the pause for files that a `glob` leaves unread, where no file operation ends a step. - `AGENTS.md`, `README.md`, and the crate docs state the steps as they are. `AGENTS.md` says that Write, StrReplace, and Delete are stubs until `Source` has the methods that change files. - No test counts the steps of Read or ListDir. The integration tests check their answers through the fake Host. Plan: runvil-harness/plan/2026-11-16-1-tool-file-effects.plan.md --- AGENTS.md | 4 +- Cargo.lock | 8 ++-- Cargo.toml | 4 +- README.md | 2 +- crates/plugin-std/src/dir.rs | 11 ++--- crates/plugin-std/src/dir/tests.rs | 54 ++++++++++++++++++++--- crates/plugin-std/src/dir/tests/ignore.rs | 5 +-- crates/plugin-std/src/dir/tests/tree.rs | 26 ++++++----- crates/plugin-std/src/dir/walk.rs | 26 +++++------ crates/plugin-std/src/fake.rs | 45 ++++++++++++++----- crates/plugin-std/src/grep/find.rs | 44 +++++++++--------- crates/plugin-std/src/grep/found.rs | 6 --- crates/plugin-std/src/grep/tests.rs | 12 +---- crates/plugin-std/src/grep/tests/skips.rs | 18 +++++--- crates/plugin-std/src/lib.rs | 18 ++++---- crates/plugin-std/src/pack-tests.rs | 14 ++---- crates/plugin-std/src/pack.rs | 4 +- crates/plugin-std/src/read.rs | 9 ++-- crates/plugin-std/src/read/tests.rs | 5 ++- crates/plugin-std/src/source.rs | 49 +++++++++++--------- crates/plugin-std/tests/it/grep.rs | 16 ++++--- 21 files changed, 219 insertions(+), 161 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ed51ba9..5c4cff6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,9 +27,9 @@ Anything else gets a qualified lowercase name, such as Rust's built-in test harn - Behavior changes ship with tests in the same change. Preserve behavior tests during refactors. - The Plugin crate depends on `runvil-plugin-sdk` and outside libraries alone, and writes no `unsafe`. The SDK owns the C boundary. - A tool reads files only through `Source` (`crates/plugin-std/src/source.rs`), which the call's `ToolCall` implements, so every read goes through the Host and the run's policy applies to it. A test runs a tool's own code over the SDK's `testing::Files` tree, or over `FakeSource` (`crates/plugin-std/src/fake.rs`) for what that tree cannot hold. -- Write, StrReplace, and Delete wait for file methods of the SDK that return futures, and `Source` becomes async with them. Each file operation of a tool is to become an effect that the Harness records. +- Write, StrReplace, and Delete are stubs until each is built on the file methods of the SDK that change files, which `Source` gains with them. - A tool's description and parameter schema come from its JSON file under `crates/plugin-std/schemas`. `EDITS.md` beside them records every difference from Cursor's definition, and a change to a JSON file changes `EDITS.md` with it. -- A tool that does a long job awaits `next_step()` after each bounded slice of work, as Grep does every 32 files or directories and every 2 MiB read, so that no step of its call works for long and the Host can abandon the call between two steps. +- A tool that does a long job awaits `next_step()` after each bounded slice of work, as Grep does every 32 files or directories, so that no step of its call works for long and the Host can abandon the call between two steps. - A Plugin shares its process with the Host, so nothing here installs process-global state, such as a panic hook (`clippy.toml` bans `std::panic::set_hook`), and nothing starts a thread that outlives the Plugin's unload. What every run shares lives in the Plugin instance and never in a `static`, so an unload frees it. - Comments explain a non-obvious constraint, ordering requirement, or workaround. A platform or external-bug workaround cites its upstream issue URL. diff --git a/Cargo.lock b/Cargo.lock index 2efd066..8ae599d 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -154,16 +154,16 @@ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4" [[package]] name = "runvil-plugin-sdk" -version = "0.4.0" -source = "git+https://github.com/cppalliance/runvil-plugin-api?rev=03a9fa37d2fe690d42ee0aa5c7a8289173e8e0f2#03a9fa37d2fe690d42ee0aa5c7a8289173e8e0f2" +version = "0.5.0" +source = "git+https://github.com/cppalliance/runvil-plugin-api?rev=52a4905aca0a9c945a93dc4ee7ea815db85612e4#52a4905aca0a9c945a93dc4ee7ea815db85612e4" dependencies = [ "runvil-plugin-sys", ] [[package]] name = "runvil-plugin-sys" -version = "0.4.0" -source = "git+https://github.com/cppalliance/runvil-plugin-api?rev=03a9fa37d2fe690d42ee0aa5c7a8289173e8e0f2#03a9fa37d2fe690d42ee0aa5c7a8289173e8e0f2" +version = "0.5.0" +source = "git+https://github.com/cppalliance/runvil-plugin-api?rev=52a4905aca0a9c945a93dc4ee7ea815db85612e4#52a4905aca0a9c945a93dc4ee7ea815db85612e4" [[package]] name = "rustix" diff --git a/Cargo.toml b/Cargo.toml index cb662bd..c182bf8 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -7,9 +7,9 @@ edition = "2024" license = "BSL-1.0" [workspace.dependencies] -# The Plugin SDK at contract 0.4, pinned to a commit. A Host loads this +# The Plugin SDK at contract 0.5, pinned to a commit. A Host loads this # Plugin only when its Harness speaks the same contract version. -runvil-plugin-sdk = { version = "0.4.0", git = "https://github.com/cppalliance/runvil-plugin-api", rev = "03a9fa37d2fe690d42ee0aa5c7a8289173e8e0f2" } +runvil-plugin-sdk = { version = "0.5.0", git = "https://github.com/cppalliance/runvil-plugin-api", rev = "52a4905aca0a9c945a93dc4ee7ea815db85612e4" } # Each tool's definition is embedded JSON, and a call's arguments arrive # as JSON text. serde = { version = "1", features = ["derive"] } diff --git a/README.md b/README.md index 5dfd8b6..779daed 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ The Plugin inserts one Pack, `runvil/std`, which gives a run the standard file t - Each tool's wire name, description, and parameter schema is a JSON file under `crates/plugin-std/schemas`, and `EDITS.md` beside them lists how each differs from Cursor's definition. - Every file a tool reads goes through the Host, so the run's policy applies to each read. A read the policy denies fails the call with the policy's own reason. The one exception is an entry below the path a Grep call names, which Grep skips and counts. - File text and file names come back as untrusted output. The Host marks them before a model reads them. -- A search ends its step every 32 files or directories, or every 2 MiB read, so the Host can cancel it between two steps. +- A tool call ends its step at each file operation, and the Host performs the operation before the next step. A search also ends its step every 32 files or directories, so the Host can cancel a call between two steps. ## Building diff --git a/crates/plugin-std/src/dir.rs b/crates/plugin-std/src/dir.rs index 98a14cc..932f2e8 100644 --- a/crates/plugin-std/src/dir.rs +++ b/crates/plugin-std/src/dir.rs @@ -33,18 +33,18 @@ use self::args::Request; /// Returns an invalid-arguments [`ToolError`] naming the parameter for a /// bad argument, and a message error for any other failure, worded for a /// model to read. -pub(crate) fn call( +pub(crate) async fn call( source: &impl Source, definition: &Definition, args: &Value, ) -> Result { let request = args::parse(definition, args)?; - list_directory(source, &definition.wire_name, &request, BODY_CAP) + list_directory(source, &definition.wire_name, &request, BODY_CAP).await } /// Lists the directory `request` names, with at most `cap` bytes of tree /// lines. `tool` is the name the model called the tool by. -fn list_directory( +async fn list_directory( source: &impl Source, tool: &str, request: &Request<'_>, @@ -53,7 +53,7 @@ fn list_directory( let target = request.target; let message = |text: String| ToolError::new(ToolErrorKind::Other, text); let failed = |error: FileError| message(refusal(tool, target, &error)); - let stat = match source.stat(target) { + let stat = match source.stat(target).await { Ok(stat) => stat, Err(error) if error.kind() == FileErrorKind::NotFound => { return Err(message(missing_root(target))); @@ -61,7 +61,8 @@ fn list_directory( Err(error) => return Err(failed(error)), }; check_directory(target, stat.file_type).map_err(message)?; - let tree = walk::walk(target, &request.ignore, cap, |path| source.list(path)) + let tree = walk::walk(source, target, &request.ignore, cap) + .await .map_err(|failure| message(refusal(tool, &failure.path, &failure.error)))?; Ok(ToolOutput::untrusted(render::render(&tree))) } diff --git a/crates/plugin-std/src/dir/tests.rs b/crates/plugin-std/src/dir/tests.rs index 1f8a2fd..75874a7 100644 --- a/crates/plugin-std/src/dir/tests.rs +++ b/crates/plugin-std/src/dir/tests.rs @@ -1,7 +1,7 @@ //! Unit tests for the `ListDir` tool. This file holds the helpers the -//! topic files share: a tree of files held in memory, and the two ways to +//! topic files share: a tree of files held in memory, the two ways to //! drive ListDir over it, through its arguments and through a lowered -//! byte cap. +//! byte cap, and a walk over listings a test writes out by hand. mod arguments; mod cap; @@ -9,10 +9,12 @@ mod ignore; mod tree; use runvil_plugin_sdk::testing::Files; -use runvil_plugin_sdk::{ToolError, ToolOutput}; +use runvil_plugin_sdk::{DirEntry, FileError, Stat, ToolError, ToolOutput}; use serde_json::Value; use super::args::Request; +use super::walk::{Failure, Tree, walk}; +use crate::fake::block_on; use crate::matcher::Matcher; use crate::source::Source; use crate::spec::{self, Definition}; @@ -38,7 +40,7 @@ fn definition() -> &'static Definition { fn list(files: &impl Source, args: &Value) -> Result { let definition = definition(); crate::check::check(&definition.wire_name, &definition.parameters, args)?; - super::call(files, definition, args) + block_on(super::call(files, definition, args)) } /// Lists `target`, leaving out `ignore`, under the byte cap `cap`. @@ -55,7 +57,49 @@ fn list_capped( .map(|pattern| Matcher::new(pattern).expect("the pattern is valid")) .collect(), }; - super::list_directory(files, "ListDir", &request, cap) + block_on(super::list_directory(files, "ListDir", &request, cap)) +} + +/// A [`Source`] whose listings a test writes out by hand: `list` answers +/// for each directory the walk enters, so a test can hold any kind of +/// entry, fail any listing, and panic on a directory that must not be +/// entered. The walk only lists, so every other operation panics. +struct Lister(F); + +#[expect( + clippy::unused_async_trait_impl, + reason = "the methods are async for a Host that answers in a later step, and a listing written by hand answers at once" +)] +impl Source for Lister +where + F: Fn(&str) -> Result, FileError>, +{ + async fn stat(&self, path: &str) -> Result { + panic!("the walk asked what {path} names") + } + + async fn list(&self, path: &str) -> Result, FileError> { + (self.0)(path) + } + + async fn read(&self, path: &str) -> Result, FileError> { + panic!("the walk read {path}") + } + + async fn read_prefix(&self, path: &str, _len: u64) -> Result, FileError> { + panic!("the walk read {path}") + } +} + +/// Walks `target` over the listings `list` answers with, leaving out +/// `ignore`, under the byte cap `cap`. +fn walk_listed( + target: &str, + ignore: &[Matcher], + cap: usize, + list: impl Fn(&str) -> Result, FileError>, +) -> Result { + block_on(walk(&Lister(list), target, ignore, cap)) } /// The text of a successful listing, which must be untrusted output. diff --git a/crates/plugin-std/src/dir/tests/ignore.rs b/crates/plugin-std/src/dir/tests/ignore.rs index cada9fb..fc08ce4 100644 --- a/crates/plugin-std/src/dir/tests/ignore.rs +++ b/crates/plugin-std/src/dir/tests/ignore.rs @@ -4,8 +4,7 @@ use runvil_plugin_sdk::{DirEntry, FileError, FileType, Stat, ToolErrorKind}; use serde_json::json; -use super::{failure_of, list, seeded, text_of}; -use crate::dir::walk::walk; +use super::{failure_of, list, seeded, text_of, walk_listed}; use crate::matcher::Matcher; /// A tree with `node_modules`, `.log` files, and a `build` directory at @@ -97,7 +96,7 @@ fn a_matching_directory_is_not_entered() { } }; let ignore = [Matcher::new("node_modules").expect("the pattern is valid")]; - let tree = walk("/p", &ignore, 15_000, lister).expect("the walk succeeds"); + let tree = walk_listed("/p", &ignore, 15_000, lister).expect("the walk succeeds"); assert_eq!( crate::dir::render::render(&tree), "/p/\n - src/\n - a.rs" diff --git a/crates/plugin-std/src/dir/tests/tree.rs b/crates/plugin-std/src/dir/tests/tree.rs index ad516bf..bb2388b 100644 --- a/crates/plugin-std/src/dir/tests/tree.rs +++ b/crates/plugin-std/src/dir/tests/tree.rs @@ -5,10 +5,10 @@ use runvil_plugin_sdk::testing::Files; use runvil_plugin_sdk::{DirEntry, FileError, FileErrorKind, FileType, Stat}; use serde_json::json; -use super::{failure_of, list, seeded, text_of}; +use super::{failure_of, list, seeded, text_of, walk_listed}; use crate::dir::check_directory; use crate::dir::render::render; -use crate::dir::walk::{Failure, walk}; +use crate::dir::walk::Failure; use crate::fake::{FakeSource, Node}; use crate::matcher::Matcher; use crate::refusal::refusal; @@ -273,7 +273,7 @@ fn a_symlink_is_listed_by_name_without_a_slash_and_is_never_entered() { other => panic!("the walk entered {other}"), } }; - let tree = walk("/p", &[], 15_000, lister).expect("the walk succeeds"); + let tree = walk_listed("/p", &[], 15_000, lister).expect("the walk succeeds"); assert_eq!( render(&tree), "/p/\n - file\n - link\n - sub/\n - inner" @@ -288,7 +288,7 @@ fn every_other_kind_of_node_is_listed_as_a_plain_name() { entry("sock", FileType::Other), ]) }; - let tree = walk("/dev", &[], 15_000, lister).expect("the walk succeeds"); + let tree = walk_listed("/dev", &[], 15_000, lister).expect("the walk succeeds"); assert_eq!(render(&tree), "/dev/\n - fifo\n - sock"); } @@ -306,7 +306,7 @@ fn the_pack_sorts_each_listing_itself_because_list_promises_no_order() { other => panic!("the walk entered {other}"), } }; - let tree = walk("/p", &[], 15_000, lister).expect("the walk succeeds"); + let tree = walk_listed("/p", &[], 15_000, lister).expect("the walk succeeds"); assert_eq!( render(&tree), "/p/\n - B\n - a-b\n - a/\n - Z\n - z\n - b" @@ -321,7 +321,8 @@ fn a_failure_listing_the_root_is_returned_for_the_tool_to_word() { format!("not a directory: {path}"), )) }; - let failure = walk("/link/", &[], 15_000, lister).expect_err("the root cannot be listed"); + let failure = + walk_listed("/link/", &[], 15_000, lister).expect_err("the root cannot be listed"); assert_eq!( failure, Failure { @@ -350,7 +351,7 @@ fn a_subdirectory_that_is_gone_or_no_longer_a_directory_is_shown_without_childre other => panic!("the walk entered {other}"), } }; - let tree = walk("/p", &[], 15_000, lister).expect("an empty look at these is true"); + let tree = walk_listed("/p", &[], 15_000, lister).expect("an empty look at these is true"); assert_eq!( render(&tree), "/p/\n - gone/\n - open/\n - a\n - swapped/" @@ -371,7 +372,7 @@ fn a_subdirectory_that_cannot_be_listed_for_any_other_reason_fails_the_walk() { other => panic!("the walk entered {other}"), } }; - let failure = walk("/p", &[], 15_000, lister).expect_err(label); + let failure = walk_listed("/p", &[], 15_000, lister).expect_err(label); assert_eq!( failure.path, "/p/locked", "{label}: the directory that failed" @@ -405,7 +406,8 @@ fn a_conflict_below_the_root_is_worded_for_the_directory_that_conflicted() { other => panic!("the walk entered {other}"), } }; - let failure = walk("notes", &[], 15_000, lister).expect_err("the conflict fails the walk"); + let failure = + walk_listed("notes", &[], 15_000, lister).expect_err("the conflict fails the walk"); assert_eq!( refusal("ListDir", &failure.path, &failure.error), "notes/locked was changed, or is being changed, by another call in this round, so it \ @@ -496,7 +498,7 @@ fn a_directory_with_a_control_character_in_its_name_is_never_entered() { other => panic!("the walk entered {other:?}"), } }; - let tree = walk("/p", &[], 15_000, lister).expect("the walk succeeds"); + let tree = walk_listed("/p", &[], 15_000, lister).expect("the walk succeeds"); assert_eq!(tree.unprintable, 2, "one at each level"); assert_eq!( render(&tree), @@ -514,7 +516,7 @@ fn an_ignored_entry_and_dot_git_are_not_counted_whatever_their_names() { ]) }; let ignore = [Matcher::new("*.log").expect("the pattern is valid")]; - let tree = walk("/p", &ignore, 15_000, lister).expect("the walk succeeds"); + let tree = walk_listed("/p", &ignore, 15_000, lister).expect("the walk succeeds"); assert_eq!(tree.unprintable, 0); assert_eq!(render(&tree), "/p/\n - kept"); } @@ -529,7 +531,7 @@ fn the_note_for_names_follows_the_note_of_a_cut_listing() { ]) }; // The root line and the line of `a` fit, and the line of `b` does not. - let tree = walk("/p", &[], 10, lister).expect("the walk succeeds"); + let tree = walk_listed("/p", &[], 10, lister).expect("the walk succeeds"); assert!(tree.truncated); let text = render(&tree); assert!( diff --git a/crates/plugin-std/src/dir/walk.rs b/crates/plugin-std/src/dir/walk.rs index d8210c2..4bbf1c7 100644 --- a/crates/plugin-std/src/dir/walk.rs +++ b/crates/plugin-std/src/dir/walk.rs @@ -11,6 +11,7 @@ use runvil_plugin_sdk::{DirEntry, FileError, FileErrorKind, FileType}; use crate::matcher::Matcher; use crate::order::{GIT, has_control, sorted}; +use crate::source::Source; /// One line of the tree: a name under its parent. #[derive(Debug)] @@ -58,14 +59,14 @@ pub(super) struct Failure { struct Pending { /// Its index in the tree's nodes. node: usize, - /// The path the lister is given for it. + /// The path it is listed by. path: String, /// The depth of the entries under it: 1 for the root's. depth: usize, } -/// Walks the directory `target`, breadth first, calling `list` for each -/// directory it enters. +/// Walks the directory `target`, breadth first, listing each directory it +/// enters through `source`. /// /// `target` is the path as the model wrote it. `ignore` leaves out each /// entry whose absolute virtual path a pattern matches, and a left-out @@ -78,23 +79,20 @@ struct Pending { /// is marked. /// /// # Errors -/// Returns the lister's error, with the directory it was for, when the -/// root cannot be listed, and for a directory below the root when the +/// Returns the error of a listing, with the directory it was for, when +/// the root cannot be listed, and for a directory below the root when the /// failure is anything but the directory being gone or no longer a /// directory. A claim conflict or a refusal by policy is returned rather /// than shown as an empty directory, because the model would read /// `locked/` as empty when its contents were never seen. Only a directory /// that is gone, or is no longer a directory, is shown with no children, /// because an empty look at it is true. -pub(super) fn walk( +pub(super) async fn walk( + source: &impl Source, target: &str, ignore: &[Matcher], cap: usize, - mut list: F, -) -> Result -where - F: FnMut(&str) -> Result, FileError>, -{ +) -> Result { let root_line = root_line(target); let mut used = root_line.len() + 1; let mut nodes = vec![Node { @@ -111,7 +109,7 @@ where let mut truncated = false; let mut unprintable = 0; while let Some(pending) = queue.pop_front() { - let entries = match list(&pending.path) { + let entries = match source.list(&pending.path).await { Ok(entries) => entries, Err(error) if pending.node != 0 && is_gone(&error) => Vec::new(), Err(error) => { @@ -218,8 +216,8 @@ fn join(directory: &str, name: &str) -> String { } } -/// The path the lister is given for the root: the target as written, -/// without a trailing `/`, and `/` alone for the filesystem root. +/// The path the root is listed by: the target as written, without a +/// trailing `/`, and `/` alone for the filesystem root. fn directory_path(target: &str) -> String { let trimmed = target.trim_end_matches('/'); if trimmed.is_empty() { diff --git a/crates/plugin-std/src/fake.rs b/crates/plugin-std/src/fake.rs index bb0f300..5465f8c 100644 --- a/crates/plugin-std/src/fake.rs +++ b/crates/plugin-std/src/fake.rs @@ -1,18 +1,39 @@ -//! A [`Source`] the tests of every tool build by hand, for what the fake -//! Host's tree cannot hold: a link to a directory or to a file, a pipe, a -//! file whose listed size differs from its bytes, and a directory or a -//! file that fails only when it is listed or read. A name may hold any -//! character, a control character among them. +//! What the tests of every tool share: [`FakeSource`], a [`Source`] they +//! build by hand, and [`block_on`], which runs a tool's future to its +//! end. +//! +//! The fake holds what the fake Host's tree cannot: a link to a directory +//! or to a file, a pipe, a file whose listed size differs from its bytes, +//! and a directory or a file that fails only when it is listed or read. A +//! name may hold any character, a control character among them. //! //! Every node sits directly under `/`, or under a [`Node::Link`], which //! lists as a directory. use std::collections::BTreeMap; +use std::future::Future; +use std::pin::pin; +use std::task::{Context, Poll, Waker}; use runvil_plugin_sdk::{DirEntry, FileError, FileErrorKind, FileType, Stat}; use crate::source::Source; +/// Runs `future` to its output, polling it again after each `Pending`. +/// +/// A tool's future waits on no waker. Over a tree held in memory each +/// file operation answers at once, so the only `Pending` is a pause, +/// which the next poll ends. +pub(crate) fn block_on(future: F) -> F::Output { + let mut future = pin!(future); + let mut cx = Context::from_waker(Waker::noop()); + loop { + if let Poll::Ready(output) = future.as_mut().poll(&mut cx) { + return output; + } + } +} + /// One node of the fake tree. #[derive(Debug, Clone)] pub(crate) enum Node { @@ -84,8 +105,12 @@ fn split(path: &str) -> (&str, &str) { } } +#[expect( + clippy::unused_async_trait_impl, + reason = "the methods are async for a Host that answers in a later step, and a tree held in memory answers at once" +)] impl Source for FakeSource { - fn stat(&self, path: &str) -> Result { + async fn stat(&self, path: &str) -> Result { if path == "/" { return Ok(Stat::new(FileType::Directory, 0)); } @@ -95,7 +120,7 @@ impl Source for FakeSource { .ok_or_else(|| Self::missing(path)) } - fn list(&self, path: &str) -> Result, FileError> { + async fn list(&self, path: &str) -> Result, FileError> { if path != "/" { match self.nodes.get(path) { None => return Err(Self::missing(path)), @@ -119,7 +144,7 @@ impl Source for FakeSource { .collect()) } - fn read(&self, path: &str) -> Result, FileError> { + async fn read(&self, path: &str) -> Result, FileError> { match self.nodes.get(path) { Some(Node::File(bytes) | Node::Sized(_, bytes) | Node::LinkToFile(bytes)) => { Ok(bytes.clone()) @@ -133,8 +158,8 @@ impl Source for FakeSource { } } - fn read_prefix(&self, path: &str, len: u64) -> Result, FileError> { - let mut bytes = self.read(path)?; + async fn read_prefix(&self, path: &str, len: u64) -> Result, FileError> { + let mut bytes = self.read(path).await?; bytes.truncate(usize::try_from(len).unwrap_or(usize::MAX)); Ok(bytes) } diff --git a/crates/plugin-std/src/grep/find.rs b/crates/plugin-std/src/grep/find.rs index 6146c5a..ba78268 100644 --- a/crates/plugin-std/src/grep/find.rs +++ b/crates/plugin-std/src/grep/find.rs @@ -3,9 +3,8 @@ //! //! [`find`] is a pure function of its [`Source`]: it reads no clock, keeps //! nothing between calls, and returns what it found without writing any -//! text. It ends its step after every slice of entries or bytes its -//! [`Limits`] name, so the Host can abandon a running search between two -//! steps. +//! text. It ends its step after every slice of entries its [`Limits`] +//! name, so the Host can abandon a running search between two steps. use runvil_plugin_sdk::{DirEntry, FileError, FileErrorKind, FileType, next_step}; @@ -99,7 +98,7 @@ pub(super) async fn find( limits: &Limits, ) -> Result { let root = request.path.unwrap_or("/"); - let stat = match source.stat(root) { + let stat = match source.stat(root).await { Ok(stat) => stat, Err(error) if error.kind() == FileErrorKind::NotFound => return Err(missing_root(root)), Err(error) => return Err(refusal(tool, root, &error)), @@ -114,12 +113,11 @@ pub(super) async fn find( considered: 0, bytes: 0, since_entries: 0, - since_bytes: 0, finished: false, }; match stat.file_type { FileType::Directory => search.directory(root).await?, - FileType::File => search.root_file(root, Some(stat.len))?, + FileType::File => search.root_file(root, Some(stat.len)).await?, FileType::Symlink => search.link(root).await?, _ => return Err(neither_file_nor_directory(root)), } @@ -149,8 +147,6 @@ pub(super) struct Search<'a, 'r, S: Source> { /// The files considered and the directories listed since the last /// pause. since_entries: usize, - /// The bytes read since the last pause. - since_bytes: u64, /// Whether the search has everything it needs, or hit a limit. pub(super) finished: bool, } @@ -162,6 +158,7 @@ impl Search<'_, '_, S> { let entries = self .source .list(&node.access) + .await .map_err(|error| refusal(self.tool, root, &error))?; self.walk(node, entries).await; Ok(()) @@ -171,13 +168,13 @@ impl Search<'_, '_, S> { /// and as a file when it does not. async fn link(&mut self, root: &str) -> Result<(), String> { let node = Node::directory(root); - match self.source.list(&node.access) { + match self.source.list(&node.access).await { Ok(entries) => { self.walk(node, entries).await; Ok(()) } Err(error) if error.kind() == FileErrorKind::NotADirectory => { - self.root_file(root, None) + self.root_file(root, None).await } Err(error) => Err(refusal(self.tool, root, &error)), } @@ -188,7 +185,7 @@ impl Search<'_, '_, S> { /// /// `size` is the file's size when the stat gave it, and `None` for a /// link, whose own size says nothing about its target. - fn root_file(&mut self, root: &str, size: Option) -> Result<(), String> { + async fn root_file(&mut self, root: &str, size: Option) -> Result<(), String> { let node = Node::file(root); self.considered += 1; let bytes = if let Some(size) = size { @@ -196,10 +193,11 @@ impl Search<'_, '_, S> { self.skip(Reason::OverSize, Some(&node.shown)); return Ok(()); } - self.source.read(&node.access) + self.source.read(&node.access).await } else { self.source .read_prefix(&node.access, self.limits.max_file_size.saturating_add(1)) + .await } .map_err(|error| refusal(self.tool, root, &error))?; if size.is_none() && length(&bytes) > self.limits.max_file_size { @@ -237,7 +235,7 @@ impl Search<'_, '_, S> { match entry.stat.file_type { FileType::Symlink => self.skip(Reason::SymbolicLink, Some(&child.shown)), FileType::Directory => { - match self.source.list(&child.access) { + match self.source.list(&child.access).await { Ok(entries) => stack.push(Frame { dir: child, entries: sorted(entries).into_iter(), @@ -250,7 +248,7 @@ impl Search<'_, '_, S> { self.pace().await; } FileType::File => { - self.visit(&child, &entry.name, entry.stat.len); + self.visit(&child, &entry.name, entry.stat.len).await; self.pace().await; } // A pipe, a socket, or a device is never opened: reading one @@ -262,7 +260,7 @@ impl Search<'_, '_, S> { /// Visits one file the walk met: counts it, applies the filters, /// reads it, and searches it. - fn visit(&mut self, node: &Node, name: &str, size: u64) { + async fn visit(&mut self, node: &Node, name: &str, size: u64) { if self.considered >= self.limits.max_files { self.finish(Stop::Files); return; @@ -287,25 +285,23 @@ impl Search<'_, '_, S> { self.finish(Stop::Bytes); return; } - match self.source.read(&node.access) { + match self.source.read(&node.access).await { Ok(bytes) => { self.bytes += length(&bytes); - self.since_bytes += length(&bytes); self.consume(&node.shown, &bytes); } Err(error) => self.skip(file_reason(&error), Some(&node.shown)), } } - /// Pauses when enough entries or bytes have gone by since the last - /// pause: ends the step, so that no step works for long and a cancel - /// or a stop can drop the future between two steps. + /// Pauses when enough entries have gone by since the last pause: ends + /// the step, so that no step works for long and a cancel or a stop + /// can drop the future between two steps. A listing or a read through + /// the Host ends the step too, so the pause is what bounds a run of + /// files that a filter leaves unread. async fn pace(&mut self) { - if self.since_entries >= self.limits.slice_entries - || self.since_bytes >= self.limits.slice_bytes - { + if self.since_entries >= self.limits.slice_entries { self.since_entries = 0; - self.since_bytes = 0; next_step().await; } } diff --git a/crates/plugin-std/src/grep/found.rs b/crates/plugin-std/src/grep/found.rs index 75786ad..dd4b66b 100644 --- a/crates/plugin-std/src/grep/found.rs +++ b/crates/plugin-std/src/grep/found.rs @@ -18,9 +18,6 @@ const MAX_BYTES: u64 = 1_073_741_824; /// pauses. const SLICE_ENTRIES: usize = 32; -/// How many bytes are read between two pauses: 2 MiB. -const SLICE_BYTES: u64 = 2_097_152; - /// How many skipped paths the skip line names. const FIRST_KEPT: usize = 5; @@ -36,8 +33,6 @@ pub(super) struct Limits { pub(super) max_file_size: u64, /// The files considered and directories listed between two pauses. pub(super) slice_entries: usize, - /// The bytes read between two pauses. - pub(super) slice_bytes: u64, /// The most bytes of body in the answer. pub(super) body_cap: usize, /// How much of a long line is shown. @@ -51,7 +46,6 @@ impl Default for Limits { max_bytes: MAX_BYTES, max_file_size: MAX_FILE_BYTES, slice_entries: SLICE_ENTRIES, - slice_bytes: SLICE_BYTES, body_cap: BODY_CAP, window: Window::default(), } diff --git a/crates/plugin-std/src/grep/tests.rs b/crates/plugin-std/src/grep/tests.rs index 7d11f4d..89460c6 100644 --- a/crates/plugin-std/src/grep/tests.rs +++ b/crates/plugin-std/src/grep/tests.rs @@ -23,20 +23,10 @@ use serde_json::Value; use super::args; use super::found::Limits; +use crate::fake::block_on; use crate::source::Source; use crate::spec::{self, Definition}; -/// Drives a future to its output, polling again after each `Pending`. -fn block_on(future: F) -> F::Output { - let mut future = pin!(future); - let mut cx = Context::from_waker(Waker::noop()); - loop { - if let Poll::Ready(output) = future.as_mut().poll(&mut cx) { - return output; - } - } -} - /// Drives a future to its output and counts how many times it returned /// `Pending` on the way. fn count_pendings(future: F) -> (F::Output, usize) { diff --git a/crates/plugin-std/src/grep/tests/skips.rs b/crates/plugin-std/src/grep/tests/skips.rs index 9801e98..4a992c5 100644 --- a/crates/plugin-std/src/grep/tests/skips.rs +++ b/crates/plugin-std/src/grep/tests/skips.rs @@ -370,21 +370,27 @@ fn a_tree_of_directories_with_no_files_still_pauses_once_per_slice() { } #[test] -fn the_search_pauses_once_per_slice_of_bytes() { +fn a_run_of_files_that_a_filter_leaves_unread_still_pauses_once_per_slice() { let mut source = FakeSource::default(); for index in 0..10 { - source = source.file(&format!("/f{index}"), "0123456789"); + source = source.file(&format!("/f{index}.log"), "x\n"); } let limits = Limits { - slice_bytes: 25, + slice_entries: 3, ..Limits::default() }; let definition = definition(); - let args = json!({ "pattern": "x" }); + let args = json!({ "pattern": "x", "glob": "*.txt" }); let request = args::parse(definition, &args).expect("the arguments parse"); let (output, pending) = count_pendings(crate::grep::search(&source, "Grep", &request, &limits)); - assert!(output.is_ok()); - assert_eq!(pending, 3, "after files 3, 6, and 9, at 30 bytes each time"); + assert!( + output + .expect("the search succeeds") + .text() + .starts_with("No matches found. Searched 0 files."), + "no file passes the glob, so none is read" + ); + assert_eq!(pending, 3, "after files 3, 6, and 9"); } #[test] diff --git a/crates/plugin-std/src/lib.rs b/crates/plugin-std/src/lib.rs index 968b9c7..d9ddef1 100644 --- a/crates/plugin-std/src/lib.rs +++ b/crates/plugin-std/src/lib.rs @@ -63,9 +63,8 @@ //! not counted, a call with an `offset` pages through the same result, //! and a binary file, a link, an over-size file, and an entry that cannot //! be read are skipped and counted, never a failure. A search ends its -//! step every 32 files or directories, or every 2 MiB read, so a cancel -//! or a stop can drop it between two steps. File text comes back as -//! untrusted output. +//! step every 32 files or directories, so a cancel or a stop can drop it +//! between two steps. File text comes back as untrusted output. //! //! Write, StrReplace, Delete, and Glob are still stubs: a call with //! arguments that match the schema answers [`NOT_IMPLEMENTED`]. For every @@ -77,12 +76,13 @@ //! //! Every filesystem operation a tool performs goes through its //! [`ToolCall`](runvil_plugin_sdk::ToolCall), never the disk directly. -//! The Host answers each one under the run's policy, so a read the policy -//! denies fails without the Pack deciding anything. A tool reports the -//! [`FileError`](runvil_plugin_sdk::FileError) for the path its call -//! names as a tool error the model can read. Below that path, ListDir -//! fails the same way on a directory that is there and cannot be listed, -//! and Grep skips the entry and counts it. +//! Each one ends the step of its call: the Host performs the operation +//! under the run's policy, and a later step goes on with the answer. So +//! a read the policy denies fails without the Pack deciding anything. A +//! tool reports the [`FileError`](runvil_plugin_sdk::FileError) for the +//! path its call names as a tool error the model can read. Below that +//! path, ListDir fails the same way on a directory that is there and +//! cannot be listed, and Grep skips the entry and counts it. //! //! Shell is deliberately absent. An in-process shell over the same //! filesystem is a separate Pack, so a run that wants one declares it. diff --git a/crates/plugin-std/src/pack-tests.rs b/crates/plugin-std/src/pack-tests.rs index d4e2322..761aadf 100644 --- a/crates/plugin-std/src/pack-tests.rs +++ b/crates/plugin-std/src/pack-tests.rs @@ -1,27 +1,19 @@ //! Unit tests for the `std` Pack's stub text, the definitions it builds //! from, the arguments it parses, and the tool a call's name picks. -use std::future::Future; -use std::pin::pin; use std::sync::Arc; -use std::task::{Context, Poll, Waker}; use runvil_plugin_sdk::testing::Files; use runvil_plugin_sdk::{ToolError, ToolErrorKind, ToolOutput}; use super::{INFO, NOT_IMPLEMENTED, StdPack, parse, run}; +use crate::fake::block_on; use crate::spec::{self, Definition}; /// Runs one call of the tool `name` with `arguments` over `files` to its -/// end, polling again after each `Pending`. +/// end. fn ran(name: &str, arguments: &str, files: &Files) -> Result { - let mut future = pin!(run(spec::all(), name, arguments, files)); - let mut cx = Context::from_waker(Waker::noop()); - loop { - if let Poll::Ready(result) = future.as_mut().poll(&mut cx) { - return result; - } - } + block_on(run(spec::all(), name, arguments, files)) } #[test] diff --git a/crates/plugin-std/src/pack.rs b/crates/plugin-std/src/pack.rs index 913e1b4..cc807b0 100644 --- a/crates/plugin-std/src/pack.rs +++ b/crates/plugin-std/src/pack.rs @@ -95,8 +95,8 @@ async fn run( let args = parse(&definition.wire_name, arguments)?; crate::check::check(&definition.wire_name, &definition.parameters, &args)?; match definition.segment { - "read" => crate::read::call(source, definition, &args), - "dir" => crate::dir::call(source, definition, &args), + "read" => crate::read::call(source, definition, &args).await, + "dir" => crate::dir::call(source, definition, &args).await, "grep" => crate::grep::call(source, definition, &args).await, _ => Ok(ToolOutput::trusted(stub(&definition.wire_name))), } diff --git a/crates/plugin-std/src/read.rs b/crates/plugin-std/src/read.rs index 46007a0..09b0bd3 100644 --- a/crates/plugin-std/src/read.rs +++ b/crates/plugin-std/src/read.rs @@ -35,19 +35,19 @@ pub(crate) const BYTE_CAP: usize = 100_000; /// Returns an invalid-arguments [`ToolError`] naming the parameter for a /// bad argument, and a message error for any other failure, worded for a /// model to read. -pub(crate) fn call( +pub(crate) async fn call( source: &impl Source, definition: &Definition, args: &Value, ) -> Result { let request = args::parse(definition, args)?; - read_file(source, &definition.wire_name, &request, BYTE_CAP) + read_file(source, &definition.wire_name, &request, BYTE_CAP).await } /// Reads the file `request` names, in the window it asks for, with at /// most `cap` bytes of numbered lines. `tool` is the name the model /// called the tool by. -fn read_file( +async fn read_file( source: &impl Source, tool: &str, request: &Request<'_>, @@ -56,10 +56,11 @@ fn read_file( let path = request.path; let message = |text: String| ToolError::new(ToolErrorKind::Other, text); let failed = |error: FileError| message(refusal(tool, path, &error)); - let stat = source.stat(path).map_err(failed)?; + let stat = source.stat(path).await.map_err(failed)?; check_type(path, stat.file_type).map_err(message)?; let bytes = source .read_prefix(path, MAX_FILE_BYTES + 1) + .await .map_err(failed)?; if u64::try_from(bytes.len()).unwrap_or(u64::MAX) > MAX_FILE_BYTES { return Err(message(format!( diff --git a/crates/plugin-std/src/read/tests.rs b/crates/plugin-std/src/read/tests.rs index 6f24d1e..d5da8e3 100644 --- a/crates/plugin-std/src/read/tests.rs +++ b/crates/plugin-std/src/read/tests.rs @@ -13,6 +13,7 @@ use runvil_plugin_sdk::{ToolError, ToolOutput}; use serde_json::Value; use super::args::Request; +use crate::fake::block_on; use crate::source::Source; use crate::spec::{self, Definition}; @@ -34,7 +35,7 @@ fn definition() -> &'static Definition { fn read(files: &impl Source, args: &Value) -> Result { let definition = definition(); crate::check::check(&definition.wire_name, &definition.parameters, args)?; - super::call(files, definition, args) + block_on(super::call(files, definition, args)) } /// Reads `path` with the window `offset` and `limit` under the byte cap @@ -51,7 +52,7 @@ fn read_capped( offset, limit, }; - super::read_file(files, "Read", &request, cap) + block_on(super::read_file(files, "Read", &request, cap)) } /// The text of a successful read, which must be untrusted output. diff --git a/crates/plugin-std/src/source.rs b/crates/plugin-std/src/source.rs index ca243f7..6c3ac59 100644 --- a/crates/plugin-std/src/source.rs +++ b/crates/plugin-std/src/source.rs @@ -1,63 +1,70 @@ //! The file operations the tools need, behind a trait. //! //! The call's [`ToolCall`] implements it, so every operation a tool -//! performs goes through the Host, and the run's policy applies. The seam -//! exists so that a test can run a tool's own code over a tree it builds: -//! the SDK's `testing::Files`, or this crate's `FakeSource` for what that -//! tree cannot hold, such as a link, a pipe, and a read that fails after -//! the stat succeeded. +//! performs goes through the Host, and the run's policy applies. Each +//! method is async, because the Host answers a file operation in a later +//! step of the call: awaiting one ends the step. The seam exists so that +//! a test can run a tool's own code over a tree it builds: the SDK's +//! `testing::Files`, or this crate's `FakeSource` for what that tree +//! cannot hold, such as a link, a pipe, and a read that fails after the +//! stat succeeded. Both answer at once, so a test polls a tool's future +//! to its end with no Host around it. use runvil_plugin_sdk::{DirEntry, FileError, Stat, ToolCall}; /// Where a tool reads the run's files from. pub(crate) trait Source { /// Metadata for `path`, without following a link. - fn stat(&self, path: &str) -> Result; + async fn stat(&self, path: &str) -> Result; /// The entries of the directory at `path`, in no promised order. - fn list(&self, path: &str) -> Result, FileError>; + async fn list(&self, path: &str) -> Result, FileError>; /// The whole contents of the file at `path`. - fn read(&self, path: &str) -> Result, FileError>; + async fn read(&self, path: &str) -> Result, FileError>; /// At most the first `len` bytes of the file at `path`, for a path /// whose size is not known beforehand. - fn read_prefix(&self, path: &str, len: u64) -> Result, FileError>; + async fn read_prefix(&self, path: &str, len: u64) -> Result, FileError>; } impl Source for ToolCall<'_> { - fn stat(&self, path: &str) -> Result { - ToolCall::stat(self, path) + async fn stat(&self, path: &str) -> Result { + ToolCall::stat(self, path).await } - fn list(&self, path: &str) -> Result, FileError> { - ToolCall::list(self, path) + async fn list(&self, path: &str) -> Result, FileError> { + ToolCall::list(self, path).await } - fn read(&self, path: &str) -> Result, FileError> { - ToolCall::read(self, path) + async fn read(&self, path: &str) -> Result, FileError> { + ToolCall::read(self, path).await } - fn read_prefix(&self, path: &str, len: u64) -> Result, FileError> { - ToolCall::read_range(self, path, 0, len) + async fn read_prefix(&self, path: &str, len: u64) -> Result, FileError> { + ToolCall::read_range(self, path, 0, len).await } } #[cfg(test)] +#[expect( + clippy::unused_async_trait_impl, + reason = "the methods are async for a Host that answers in a later step, and a tree held in memory answers at once" +)] impl Source for runvil_plugin_sdk::testing::Files { - fn stat(&self, path: &str) -> Result { + async fn stat(&self, path: &str) -> Result { runvil_plugin_sdk::testing::Files::stat(self, path) } - fn list(&self, path: &str) -> Result, FileError> { + async fn list(&self, path: &str) -> Result, FileError> { runvil_plugin_sdk::testing::Files::list(self, path) } - fn read(&self, path: &str) -> Result, FileError> { + async fn read(&self, path: &str) -> Result, FileError> { runvil_plugin_sdk::testing::Files::read(self, path, 0, u64::MAX) } - fn read_prefix(&self, path: &str, len: u64) -> Result, FileError> { + async fn read_prefix(&self, path: &str, len: u64) -> Result, FileError> { runvil_plugin_sdk::testing::Files::read(self, path, 0, len) } } diff --git a/crates/plugin-std/tests/it/grep.rs b/crates/plugin-std/tests/it/grep.rs index c66c48e..1ede1a6 100644 --- a/crates/plugin-std/tests/it/grep.rs +++ b/crates/plugin-std/tests/it/grep.rs @@ -1,6 +1,6 @@ -//! Grep's steps, seen from the Host's side of the contract: a search over -//! many files ends its step before it completes, so the Host can abandon -//! it, and an abandoned search leaves the Pack instance usable. +//! Grep's steps, seen from the Host's side of the contract: a search ends +//! its step at each file operation and at each pause, so the Host can +//! abandon it, and an abandoned search leaves the Pack instance usable. use plugin_std::Std; use runvil_plugin_sdk::testing::{self, Files}; @@ -25,7 +25,7 @@ fn args() -> String { } #[test] -fn a_search_over_a_thousand_files_takes_many_steps_before_it_completes() { +fn a_search_over_a_thousand_files_ends_a_step_at_each_file_operation_and_each_pause() { let loaded = testing::load::().expect("the Plugin loads"); let pack = loaded .new_pack(PACK) @@ -39,9 +39,11 @@ fn a_search_over_a_thousand_files_takes_many_steps_before_it_completes() { None => pending += 1, } }; - assert!( - pending >= 31, - "a step ends after each 32 of {FILES} files, and the search took {pending} extra steps" + assert_eq!( + pending, + 2 + FILES + FILES / 32, + "a step ends at the stat of the root, at its listing, at the read of each file, and \ + at the pause after each 32 files" ); let output = result.expect("the search completes with its result"); assert!(!output.is_trusted()); From 2ea8f8d0998e1189df73ac90841edcb7451ebe6e Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Tue, 17 Nov 2026 23:44:13 -0800 Subject: [PATCH 03/13] Implement Write with one `write` through `Source` A run needs a tool that makes a file or replaces the whole contents of one. Write hands `contents` to the Host as one `write` through `Source`, and it answers the count of bytes as trusted output. Its `ToolInfo` carries `changes_files`, which tells the Host to run each of its calls by itself among the calls of one model reply. - `Source` gains `write`, which takes the bytes as a `Vec`. `ToolCall` and the `Files` tree perform it, `FakeSource` fails it with a fixed error, and the listing fake of the `dir` tests panics. - `changes_files` in `pack.rs` names the flagged tools by segment, and `StdPack::new` sets the flag. One test in `pack-tests.rs` and one in `changes.rs` hold the list at `write`. - `write_refusal` in `refusal.rs` words a write that fails because something is not a directory as "Path has a parent that is not a directory", because a write needs a directory only on the way to its file. Every other failure reads as `refusal` words it. - Write asks the Host for the write and for nothing else, so what was at the path is gone. A test counts two steps for one call. - Contents over `RV_MAX_WRITE` bytes fail as invalid arguments that name `contents` and the limit, before any request to the Host. The `{write_limit}` placeholder puts the same number in the description. - Write refuses an undeclared key, then a blank `path`, then contents over the limit. - The answer holds fixed text and a count and no path, so no text from outside is in trusted output. - `write.json` gains a `Usage` list, and `EDITS.md` records it. `README.md`, `AGENTS.md`, and the crate docs say that Write is real, and `AGENTS.md` widens the rule on `Source` to every file operation. - StrReplace, Delete, and Glob stay stubs. - `write_refusal` passes a conflict to `refusal`, whose sentence speaks of a read. No test covers a write to a link or to a special file, because Write does not ask what the path names. Plan: runvil-harness/plan/2026-11-16-1-tool-file-effects.plan.md --- AGENTS.md | 5 +- README.md | 9 +- crates/plugin-std/schemas/EDITS.md | 3 +- crates/plugin-std/schemas/write.json | 2 +- crates/plugin-std/src/dir/tests.rs | 4 + crates/plugin-std/src/fake.rs | 9 +- crates/plugin-std/src/lib.rs | 40 ++-- crates/plugin-std/src/pack-tests.rs | 29 ++- crates/plugin-std/src/pack.rs | 29 ++- crates/plugin-std/src/refusal.rs | 24 ++- crates/plugin-std/src/refusal/tests.rs | 47 ++++- crates/plugin-std/src/source.rs | 15 +- crates/plugin-std/src/spec-tests.rs | 29 +++ crates/plugin-std/src/spec.rs | 4 + crates/plugin-std/src/write-tests.rs | 275 +++++++++++++++++++++++++ crates/plugin-std/src/write.rs | 66 ++++++ crates/plugin-std/tests/it/changes.rs | 152 ++++++++++++++ crates/plugin-std/tests/it/main.rs | 5 +- crates/plugin-std/tests/it/tools.rs | 5 - 19 files changed, 707 insertions(+), 45 deletions(-) create mode 100644 crates/plugin-std/src/write-tests.rs create mode 100644 crates/plugin-std/src/write.rs create mode 100644 crates/plugin-std/tests/it/changes.rs diff --git a/AGENTS.md b/AGENTS.md index 5c4cff6..bae135f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,8 +26,9 @@ Anything else gets a qualified lowercase name, such as Rust's built-in test harn - Prefer types and compiler checks, then behavior tests. Gate on yes/no properties, never on a score threshold that ordinary work edits. - Behavior changes ship with tests in the same change. Preserve behavior tests during refactors. - The Plugin crate depends on `runvil-plugin-sdk` and outside libraries alone, and writes no `unsafe`. The SDK owns the C boundary. -- A tool reads files only through `Source` (`crates/plugin-std/src/source.rs`), which the call's `ToolCall` implements, so every read goes through the Host and the run's policy applies to it. A test runs a tool's own code over the SDK's `testing::Files` tree, or over `FakeSource` (`crates/plugin-std/src/fake.rs`) for what that tree cannot hold. -- Write, StrReplace, and Delete are stubs until each is built on the file methods of the SDK that change files, which `Source` gains with them. +- A tool reaches files only through `Source` (`crates/plugin-std/src/source.rs`), which the call's `ToolCall` implements, so every file operation goes through the Host and the run's policy applies to it. A test runs a tool's own code over the SDK's `testing::Files` tree, or over `FakeSource` (`crates/plugin-std/src/fake.rs`) for what that tree cannot hold. +- A tool that changes files says so with `ToolInfo::changes_files`, so the Host runs each of its calls by itself among the calls of one model reply. +- StrReplace and Delete are stubs until each is built on the file methods of the SDK that change files, which `Source` gains with them. - A tool's description and parameter schema come from its JSON file under `crates/plugin-std/schemas`. `EDITS.md` beside them records every difference from Cursor's definition, and a change to a JSON file changes `EDITS.md` with it. - A tool that does a long job awaits `next_step()` after each bounded slice of work, as Grep does every 32 files or directories, so that no step of its call works for long and the Host can abandon the call between two steps. - A Plugin shares its process with the Host, so nothing here installs process-global state, such as a panic hook (`clippy.toml` bans `std::panic::set_hook`), and nothing starts a thread that outlives the Plugin's unload. What every run shares lives in the Plugin instance and never in a `static`, so an unload frees it. diff --git a/README.md b/README.md index 779daed..1ebd563 100644 --- a/README.md +++ b/README.md @@ -9,14 +9,15 @@ The Plugin inserts one Pack, `runvil/std`, which gives a run the standard file t | `std/read` | `Read` | Returns a window of a text file's lines, each with its line number | | `std/dir` | `ListDir` | Returns a bullet tree of a directory, listed breadth first | | `std/grep` | `Grep` | Searches the files under a path with a Rust regular expression | -| `std/write` | `Write` | A stub: answers that the tool is not implemented | -| `std/replace` | `StrReplace` | A stub | +| `std/write` | `Write` | Creates a file, or replaces the whole contents of one | +| `std/replace` | `StrReplace` | A stub: answers that the tool is not implemented | | `std/rm` | `Delete` | A stub | | `std/glob` | `Glob` | A stub | - Each tool's wire name, description, and parameter schema is a JSON file under `crates/plugin-std/schemas`, and `EDITS.md` beside them lists how each differs from Cursor's definition. -- Every file a tool reads goes through the Host, so the run's policy applies to each read. A read the policy denies fails the call with the policy's own reason. The one exception is an entry below the path a Grep call names, which Grep skips and counts. -- File text and file names come back as untrusted output. The Host marks them before a model reads them. +- Every file operation of a tool goes through the Host, so the run's policy applies to each one. An operation the policy denies fails the call with the policy's own reason. The one exception is an entry below the path a Grep call names, which Grep skips and counts. +- File text and file names come back as untrusted output. The Host marks them before a model reads them. The answer to a change is fixed text and a count, which is trusted output. +- Write says to the Host that it changes files. The Host runs a call of such a tool by itself among the calls of one model reply, so two changes of one reply happen in the order the reply lists them. - A tool call ends its step at each file operation, and the Host performs the operation before the next step. A search also ends its step every 32 files or directories, so the Host can cancel a call between two steps. ## Building diff --git a/crates/plugin-std/schemas/EDITS.md b/crates/plugin-std/schemas/EDITS.md index 5fe03ce..dc1d117 100644 --- a/crates/plugin-std/schemas/EDITS.md +++ b/crates/plugin-std/schemas/EDITS.md @@ -16,7 +16,8 @@ Each file in this directory except `dir.json` is Cursor's definition of the tool ## write.json -- Cursor's `Write` description, which is about creating or overwriting a file. Reworded to name `StrReplace` for targeted changes and to require a read before overwriting, matching Cursor's own guidance. No behavior was added; only the wording is ours. +- Cursor's `Write` description, which is about creating or overwriting a file. Reworded to name `StrReplace` for targeted changes and to require a read before overwriting, matching Cursor's own guidance. The parameters, their types, and the `required` list are Cursor's. +- Added a `Usage` list that states what Write does: the directories on the way to the file are created, `contents` is written exactly as given and holds at most `{write_limit}` bytes, a path that names a directory fails, and the calls in one response that change files run one after another in the order listed. The placeholder is filled when the definition is built, from the SDK's limit on one write, which the code enforces, so the text and the limit cannot drift apart. ## replace.json diff --git a/crates/plugin-std/schemas/write.json b/crates/plugin-std/schemas/write.json index e9ca390..6734106 100644 --- a/crates/plugin-std/schemas/write.json +++ b/crates/plugin-std/schemas/write.json @@ -1,6 +1,6 @@ { "wire_name": "Write", - "description": "Creates or overwrites a file at the specified path. Use this tool to create a new file or to replace the whole contents of an existing one. If the destination file already exists, you MUST first read it before writing, so a change you did not make is never overwritten. For a targeted change to an existing file, prefer StrReplace.", + "description": "Creates or overwrites a file at the specified path. Use this tool to create a new file or to replace the whole contents of an existing one. If the destination file already exists, you MUST first read it before writing, so a change you did not make is never overwritten. For a targeted change to an existing file, prefer StrReplace.\n\nUsage:\n- The directories on the way to the file are created when they do not exist.\n- contents is written exactly as given, as the whole file. It holds at most {write_limit} bytes.\n- A path that names a directory fails.\n- The calls in one response that change files run one after another, in the order you list them.", "parameters": { "type": "object", "properties": { diff --git a/crates/plugin-std/src/dir/tests.rs b/crates/plugin-std/src/dir/tests.rs index 75874a7..605727d 100644 --- a/crates/plugin-std/src/dir/tests.rs +++ b/crates/plugin-std/src/dir/tests.rs @@ -89,6 +89,10 @@ where async fn read_prefix(&self, path: &str, _len: u64) -> Result, FileError> { panic!("the walk read {path}") } + + async fn write(&self, path: &str, _bytes: Vec) -> Result<(), FileError> { + panic!("the walk wrote {path}") + } } /// Walks `target` over the listings `list` answers with, leaving out diff --git a/crates/plugin-std/src/fake.rs b/crates/plugin-std/src/fake.rs index 5465f8c..8969214 100644 --- a/crates/plugin-std/src/fake.rs +++ b/crates/plugin-std/src/fake.rs @@ -8,7 +8,7 @@ //! name may hold any character, a control character among them. //! //! Every node sits directly under `/`, or under a [`Node::Link`], which -//! lists as a directory. +//! lists as a directory. The tree never changes: it fails every change. use std::collections::BTreeMap; use std::future::Future; @@ -163,4 +163,11 @@ impl Source for FakeSource { bytes.truncate(usize::try_from(len).unwrap_or(usize::MAX)); Ok(bytes) } + + async fn write(&self, path: &str, _bytes: Vec) -> Result<(), FileError> { + Err(FileError::new( + FileErrorKind::Other, + format!("the fake tree takes no change: {path}"), + )) + } } diff --git a/crates/plugin-std/src/lib.rs b/crates/plugin-std/src/lib.rs index d9ddef1..643e4ab 100644 --- a/crates/plugin-std/src/lib.rs +++ b/crates/plugin-std/src/lib.rs @@ -66,11 +66,17 @@ //! step every 32 files or directories, so a cancel or a stop can drop it //! between two steps. File text comes back as untrusted output. //! -//! Write, StrReplace, Delete, and Glob are still stubs: a call with -//! arguments that match the schema answers [`NOT_IMPLEMENTED`]. For every -//! tool, a call whose arguments do not match fails with an -//! invalid-arguments [`ToolError`](runvil_plugin_sdk::ToolError) naming -//! the parameter. +//! Write is real. It makes a file, or replaces the whole contents of one, +//! with one write, and the Host makes each directory on the way to the +//! file. It reads nothing first, so what was at the path is gone. It +//! refuses contents over 16 MiB, the most one write takes. Its answer is +//! the count of bytes written in fixed text, so it comes back as trusted +//! output. +//! +//! StrReplace, Delete, and Glob are still stubs: a call with arguments +//! that match the schema answers [`NOT_IMPLEMENTED`]. For every tool, a +//! call whose arguments do not match fails with an invalid-arguments +//! [`ToolError`](runvil_plugin_sdk::ToolError) naming the parameter. //! //! # Where the file access goes //! @@ -78,11 +84,17 @@ //! [`ToolCall`](runvil_plugin_sdk::ToolCall), never the disk directly. //! Each one ends the step of its call: the Host performs the operation //! under the run's policy, and a later step goes on with the answer. So -//! a read the policy denies fails without the Pack deciding anything. A -//! tool reports the [`FileError`](runvil_plugin_sdk::FileError) for the -//! path its call names as a tool error the model can read. Below that -//! path, ListDir fails the same way on a directory that is there and -//! cannot be listed, and Grep skips the entry and counts it. +//! an operation the policy denies fails without the Pack deciding +//! anything. A tool reports the +//! [`FileError`](runvil_plugin_sdk::FileError) for the path its call +//! names as a tool error the model can read. Below that path, ListDir +//! fails the same way on a directory that is there and cannot be listed, +//! and Grep skips the entry and counts it. +//! +//! A tool that changes files says so to the Host, as Write does. The Host +//! runs a call of such a tool by itself among the calls of one model +//! reply, after the calls the reply lists before it, so two changes of +//! one reply happen in the order the reply lists them. //! //! Shell is deliberately absent. An in-process shell over the same //! filesystem is a separate Pack, so a run that wants one declares it. @@ -111,9 +123,12 @@ //! arguments, so a model can tell a bad call from a missing //! implementation. //! - A key the schema does not declare is refused by name, with the -//! parameters listed, by the three real tools, Read, ListDir, and -//! Grep. The stubs let it through. Grep alone accepts `-n` when it is +//! parameters listed, by the four real tools, Read, ListDir, Grep, and +//! Write. The stubs let it through. Grep alone accepts `-n` when it is //! `true`, because Cursor's definition once declared it. +//! - A tool that changes files is flagged with +//! [`ToolInfo::changes_files`](runvil_plugin_sdk::ToolInfo::changes_files), +//! and a test holds the flags in place. mod check; mod dir; @@ -128,6 +143,7 @@ mod refusal; mod source; mod spec; mod text; +mod write; use std::sync::Arc; diff --git a/crates/plugin-std/src/pack-tests.rs b/crates/plugin-std/src/pack-tests.rs index 761aadf..cdeb19f 100644 --- a/crates/plugin-std/src/pack-tests.rs +++ b/crates/plugin-std/src/pack-tests.rs @@ -1,5 +1,6 @@ //! Unit tests for the `std` Pack's stub text, the definitions it builds -//! from, the arguments it parses, and the tool a call's name picks. +//! from, the arguments it parses, the tool a call's name picks, and the +//! tools it says change files. use std::sync::Arc; @@ -134,8 +135,28 @@ fn a_call_goes_to_the_tool_its_name_picks() { assert_eq!(dir.text(), "/p/\n - a.md\n - b.md"); let grep = ran("grep", r#"{"pattern":"needle"}"#, &files).expect("the tree searches"); assert_eq!(grep.text(), "/p/a.md\n 1:needle"); - let stub = ran("write", r#"{"path":"/p/c.md","contents":"x"}"#, &files) - .expect("a stub answers its text"); - assert_eq!(stub.text(), NOT_IMPLEMENTED.replace("", "Write")); + let write = + ran("write", r#"{"path":"/p/c.md","contents":"x"}"#, &files).expect("the file is written"); + assert_eq!(write.text(), "Wrote 1 byte."); + assert_eq!(files.read("/p/c.md", 0, u64::MAX), Ok(b"x".to_vec())); + let stub = ran( + "replace", + r#"{"path":"/p/c.md","old_string":"x","new_string":"y"}"#, + &files, + ) + .expect("a stub answers its text"); + assert_eq!(stub.text(), NOT_IMPLEMENTED.replace("", "StrReplace")); assert!(stub.is_trusted()); } + +#[test] +fn an_instance_flags_the_tools_that_change_files_and_no_other() { + let pack = StdPack::new(spec::load().expect("every definition parses").into()); + let flagged: Vec<&str> = pack + .tools + .iter() + .filter(|tool| tool.changes_files) + .map(|tool| tool.name.as_str()) + .collect(); + assert_eq!(flagged, ["write"]); +} diff --git a/crates/plugin-std/src/pack.rs b/crates/plugin-std/src/pack.rs index cc807b0..7e09c83 100644 --- a/crates/plugin-std/src/pack.rs +++ b/crates/plugin-std/src/pack.rs @@ -1,7 +1,7 @@ //! The `std` Pack: its [`INFO`], [`StdPack`], one run's instance, which //! lists the Pack's tools and hands each call to its tool's module, and -//! the stub that every tool but Read, ListDir, and Grep still answers -//! with in this build. +//! the stub that every tool but Read, ListDir, Grep, and Write still +//! answers with in this build. use std::sync::Arc; @@ -15,8 +15,8 @@ use crate::source::Source; use crate::spec::Definition; /// What a call to a tool that is still a stub answers in this build, when -/// its arguments match the schema. Read, ListDir, and Grep are real and -/// never answer this. +/// its arguments match the schema. Read, ListDir, Grep, and Write are +/// real and never answer this. /// /// The text says the implementation is missing rather than that the call /// was wrong, because a model that reads it should stop calling the tool. @@ -44,23 +44,37 @@ pub(crate) struct StdPack { } impl StdPack { - /// Makes the instance, naming each tool by its definition's segment. + /// Makes the instance, naming each tool by its definition's segment + /// and saying which tools change files. pub(crate) fn new(definitions: Arc<[Definition]>) -> StdPack { let tools = definitions .iter() .map(|definition| { - ToolInfo::new( + let tool = ToolInfo::new( definition.segment, definition.description.clone(), definition.parameters.to_string(), ) - .wire_name(definition.wire_name.clone()) + .wire_name(definition.wire_name.clone()); + if changes_files(definition.segment) { + tool.changes_files() + } else { + tool + } }) .collect(); StdPack { definitions, tools } } } +/// Whether a call of the tool with the id segment `segment` changes files +/// of its run. The Host runs a call of such a tool by itself among the +/// calls of one model reply, after the calls the reply lists before it, +/// so two changes of one reply happen in the order the reply lists them. +fn changes_files(segment: &str) -> bool { + segment == "write" +} + /// The stub text for the tool the model calls `wire_name`. fn stub(wire_name: &str) -> String { NOT_IMPLEMENTED.replace("", wire_name) @@ -98,6 +112,7 @@ async fn run( "read" => crate::read::call(source, definition, &args).await, "dir" => crate::dir::call(source, definition, &args).await, "grep" => crate::grep::call(source, definition, &args).await, + "write" => crate::write::call(source, definition, &args).await, _ => Ok(ToolOutput::trusted(stub(&definition.wire_name))), } } diff --git a/crates/plugin-std/src/refusal.rs b/crates/plugin-std/src/refusal.rs index cf08e87..926097c 100644 --- a/crates/plugin-std/src/refusal.rs +++ b/crates/plugin-std/src/refusal.rs @@ -12,10 +12,10 @@ use runvil_plugin_sdk::{FileError, FileErrorKind}; /// The model-readable sentence for `error`, from the tool called `tool` /// (the name the model uses) on `path` (as the model wrote it). /// -/// A sentence names no tool other than `tool`. A read the run's policy -/// denies, and a failure the contract has no kind for, read as the Host's -/// own words alone. An I/O failure reads as the path and then the Host's -/// words. +/// A sentence names no tool other than `tool`. An operation the run's +/// policy denies, and a failure of a kind that has no sentence here, read +/// as the Host's own words alone. An I/O failure reads as the path and +/// then the Host's words. pub(crate) fn refusal(tool: &str, path: &str, error: &FileError) -> String { match error.kind() { FileErrorKind::NotFound => format!("File not found: {path}"), @@ -30,6 +30,22 @@ pub(crate) fn refusal(tool: &str, path: &str, error: &FileError) -> String { } } +/// The model-readable sentence for `error`, from a write that the tool +/// called `tool` made to `path` (as the model wrote it). +/// +/// A write needs a directory only on the way to its file, so a failure +/// for something that is not a directory is about a parent of `path`, +/// where [`refusal`] would say that `path` itself is not a directory. +/// Every other failure reads as [`refusal`] words it. +pub(crate) fn write_refusal(tool: &str, path: &str, error: &FileError) -> String { + match error.kind() { + FileErrorKind::NotADirectory => { + format!("Path has a parent that is not a directory: {path}") + } + _ => refusal(tool, path, error), + } +} + /// The sentence for a root the model named that does not exist. /// /// A tool that starts from a directory words its own missing root, because diff --git a/crates/plugin-std/src/refusal/tests.rs b/crates/plugin-std/src/refusal/tests.rs index 336c5af..f5b46af 100644 --- a/crates/plugin-std/src/refusal/tests.rs +++ b/crates/plugin-std/src/refusal/tests.rs @@ -3,7 +3,7 @@ use runvil_plugin_sdk::{FileError, FileErrorKind}; -use super::{missing_root, neither_file_nor_directory, not_a_directory, refusal}; +use super::{missing_root, neither_file_nor_directory, not_a_directory, refusal, write_refusal}; /// The path the model wrote, and the resolved path every error text /// below names, which differs so a test can tell which one a sentence @@ -95,6 +95,22 @@ fn a_failure_of_no_other_kind_reads_as_the_hosts_words() { } } +#[test] +fn a_failure_of_a_kind_that_only_a_change_has_reads_as_the_hosts_words() { + for (kind, text) in [ + ( + FileErrorKind::AlreadyExists, + "already exists: /resolved/a.md", + ), + ( + FileErrorKind::NotEmpty, + "directory not empty: /resolved/a.md", + ), + ] { + assert_eq!(say(&FileError::new(kind, text)), text, "{kind:?}"); + } +} + #[test] fn a_relative_path_is_echoed_as_written_and_never_as_the_resolved_one() { let error = FileError::new(FileErrorKind::NotFound, "not found: /notes/a.md"); @@ -123,6 +139,35 @@ fn no_message_names_a_tool_other_than_the_one_called() { assert!(!neither_file_nor_directory("p").contains("Shell")); } +#[test] +fn a_write_under_something_that_is_not_a_directory_says_that_a_parent_is_not_one() { + assert_eq!( + write_refusal("Write", WRITTEN, &error(FileErrorKind::NotADirectory)), + "Path has a parent that is not a directory: notes/a.md" + ); +} + +#[test] +fn every_other_failure_of_a_write_reads_as_the_shared_sentence() { + for kind in [ + FileErrorKind::NotFound, + FileErrorKind::IsADirectory, + FileErrorKind::Conflict, + FileErrorKind::Io, + FileErrorKind::Denied, + FileErrorKind::AlreadyExists, + FileErrorKind::NotEmpty, + FileErrorKind::Other, + ] { + let error = error(kind); + assert_eq!( + write_refusal("Write", WRITTEN, &error), + refusal("Write", WRITTEN, &error), + "{kind:?}" + ); + } +} + #[test] fn a_root_that_does_not_exist_says_the_path_does_not_exist() { assert_eq!( diff --git a/crates/plugin-std/src/source.rs b/crates/plugin-std/src/source.rs index 6c3ac59..9a927b9 100644 --- a/crates/plugin-std/src/source.rs +++ b/crates/plugin-std/src/source.rs @@ -12,7 +12,7 @@ use runvil_plugin_sdk::{DirEntry, FileError, Stat, ToolCall}; -/// Where a tool reads the run's files from. +/// Where a tool reaches the run's files. pub(crate) trait Source { /// Metadata for `path`, without following a link. async fn stat(&self, path: &str) -> Result; @@ -26,6 +26,11 @@ pub(crate) trait Source { /// At most the first `len` bytes of the file at `path`, for a path /// whose size is not known beforehand. async fn read_prefix(&self, path: &str, len: u64) -> Result, FileError>; + + /// 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. + async fn write(&self, path: &str, bytes: Vec) -> Result<(), FileError>; } impl Source for ToolCall<'_> { @@ -44,6 +49,10 @@ impl Source for ToolCall<'_> { async fn read_prefix(&self, path: &str, len: u64) -> Result, FileError> { ToolCall::read_range(self, path, 0, len).await } + + async fn write(&self, path: &str, bytes: Vec) -> Result<(), FileError> { + ToolCall::write(self, path, bytes).await + } } #[cfg(test)] @@ -67,4 +76,8 @@ impl Source for runvil_plugin_sdk::testing::Files { async fn read_prefix(&self, path: &str, len: u64) -> Result, FileError> { runvil_plugin_sdk::testing::Files::read(self, path, 0, len) } + + async fn write(&self, path: &str, bytes: Vec) -> Result<(), FileError> { + runvil_plugin_sdk::testing::Files::write(self, path, bytes) + } } diff --git a/crates/plugin-std/src/spec-tests.rs b/crates/plugin-std/src/spec-tests.rs index 9c5761e..f38bf99 100644 --- a/crates/plugin-std/src/spec-tests.rs +++ b/crates/plugin-std/src/spec-tests.rs @@ -141,6 +141,35 @@ fn the_read_description_holds_the_limits_the_code_uses_and_no_unfilled_placehold } } +#[test] +fn the_write_description_holds_the_limit_of_one_write_and_states_what_the_tool_does() { + let definitions = all(); + let write = definitions + .iter() + .find(|definition| definition.segment == "write") + .expect("the write definition exists"); + let text = &write.description; + assert!( + text.contains("at most 16777216 bytes"), + "the limit of one write is named: {text}" + ); + assert!( + !text.contains("{write_limit}"), + "{{write_limit}} is filled in: {text}" + ); + for phrase in [ + "directories on the way", + "exactly as given", + "names a directory fails", + "one after another", + ] { + assert!( + text.contains(phrase), + "the description names {phrase}: {text}" + ); + } +} + #[test] fn the_dir_description_holds_the_body_cap_and_no_unfilled_placeholder() { let definitions = all(); diff --git a/crates/plugin-std/src/spec.rs b/crates/plugin-std/src/spec.rs index aafa6af..73e884c 100644 --- a/crates/plugin-std/src/spec.rs +++ b/crates/plugin-std/src/spec.rs @@ -90,6 +90,10 @@ fn fill(segment: &str, description: &str) -> String { "read" => description .replace("{byte_cap}", &crate::read::BYTE_CAP.to_string()) .replace("{file_ceiling}", &crate::text::MAX_FILE_BYTES.to_string()), + "write" => description.replace( + "{write_limit}", + &runvil_plugin_sdk::sys::RV_MAX_WRITE.to_string(), + ), "dir" => description.replace("{body_cap}", &crate::text::BODY_CAP.to_string()), "grep" => description .replace("{body_cap}", &crate::text::BODY_CAP.to_string()) diff --git a/crates/plugin-std/src/write-tests.rs b/crates/plugin-std/src/write-tests.rs new file mode 100644 index 0000000..2b95ac1 --- /dev/null +++ b/crates/plugin-std/src/write-tests.rs @@ -0,0 +1,275 @@ +//! Unit tests for the `Write` tool: what a write leaves in the files, +//! what it answers, and what it refuses before and after it asks for the +//! write. + +use runvil_plugin_sdk::testing::Files; +use runvil_plugin_sdk::{ + FileError, FileErrorKind, FileType, Stat, ToolError, ToolErrorKind, ToolOutput, +}; +use serde_json::{Value, json}; + +use crate::fake::{FakeSource, block_on}; +use crate::source::Source; +use crate::spec::{self, Definition}; + +/// The `write` definition the Pack builds the tool from. +fn definition() -> &'static Definition { + spec::all() + .iter() + .find(|definition| definition.segment == "write") + .expect("the write definition exists") +} + +/// Calls Write over `files` with `args` as the Pack does: the schema +/// check first, then the tool. +fn write(files: &impl Source, args: &Value) -> Result { + let definition = definition(); + crate::check::check(&definition.wire_name, &definition.parameters, args)?; + block_on(super::call(files, definition, args)) +} + +/// Writes `contents` to `path` in `files`. +fn write_to(files: &impl Source, path: &str, contents: &str) -> Result { + write(files, &json!({ "path": path, "contents": contents })) +} + +/// The whole contents of the file at `path`. +fn contents(files: &Files, path: &str) -> Vec { + files.read(path, 0, u64::MAX).expect("the file is there") +} + +/// The text of a successful write, which must be trusted output. +fn text_of(result: Result) -> String { + let output = result.expect("the write succeeds"); + assert!(output.is_trusted(), "{}", output.text()); + output.text().to_owned() +} + +/// The message of a failed write, which must not be an +/// invalid-arguments failure. +fn failure_of(result: Result) -> String { + match result { + Ok(output) => panic!("the write fails, but it answered {:?}", output.text()), + Err(error) => { + assert_eq!(error.kind(), ToolErrorKind::Other, "{error}"); + error.to_string() + } + } +} + +/// The message of a write whose arguments are refused. +fn refused(result: Result) -> String { + match result { + Ok(output) => panic!("the call is refused, but it answered {:?}", output.text()), + Err(error) => { + assert_eq!(error.kind(), ToolErrorKind::InvalidArguments, "{error}"); + error.to_string() + } + } +} + +#[test] +fn a_write_makes_a_file_and_every_directory_on_the_way_to_it() { + let files = Files::new(); + assert_eq!( + text_of(write_to(&files, "/notes/deep/a.md", "one\ntwo\n")), + "Wrote 8 bytes." + ); + assert_eq!(contents(&files, "/notes/deep/a.md"), b"one\ntwo\n"); + assert_eq!( + files.stat("/notes/deep"), + Ok(Stat::new(FileType::Directory, 0)) + ); +} + +#[test] +fn a_write_replaces_the_whole_contents_of_a_file() { + let files = Files::new().file("/a.md", "a long first version\n"); + assert_eq!( + text_of(write_to(&files, "/a.md", "short")), + "Wrote 5 bytes." + ); + assert_eq!(contents(&files, "/a.md"), b"short"); +} + +#[test] +fn the_contents_are_written_exactly_as_given() { + let files = Files::new(); + let text = "caf\u{e9}\r\n\ttab, no final newline"; + assert!(write_to(&files, "/a.txt", text).is_ok()); + assert_eq!(contents(&files, "/a.txt"), text.as_bytes()); +} + +#[test] +fn the_answer_counts_the_bytes_written_and_not_the_characters() { + let files = Files::new(); + assert_eq!(text_of(write_to(&files, "/none", "")), "Wrote 0 bytes."); + assert_eq!(contents(&files, "/none"), b""); + assert_eq!(text_of(write_to(&files, "/one", "a")), "Wrote 1 byte."); + assert_eq!( + text_of(write_to(&files, "/two", "\u{e9}")), + "Wrote 2 bytes." + ); +} + +#[test] +fn a_path_without_a_leading_slash_is_written_from_the_root() { + let files = Files::new(); + assert!(write_to(&files, "notes/a.md", "x").is_ok()); + assert_eq!(contents(&files, "/notes/a.md"), b"x"); +} + +#[test] +fn contents_over_the_limit_of_one_write_are_refused_by_name_and_nothing_is_written() { + let files = Files::new(); + let over = "a".repeat(16_777_217); + assert_eq!( + refused(write_to(&files, "/big.txt", &over)), + "std_Write: `contents` is 16777217 bytes, and one write takes at most 16777216 bytes" + ); + assert_eq!(files, Files::new()); +} + +#[test] +fn contents_exactly_at_the_limit_are_written() { + let files = Files::new(); + let most = "a".repeat(16_777_216); + assert_eq!( + text_of(write_to(&files, "/edge.txt", &most)), + "Wrote 16777216 bytes." + ); + assert_eq!( + files.stat("/edge.txt"), + Ok(Stat::new(FileType::File, 16_777_216)) + ); +} + +#[test] +fn a_path_that_names_a_directory_fails_with_the_directory_text() { + let files = Files::new().file("/notes/a.md", "x"); + let before = files.clone(); + assert_eq!( + failure_of(write_to(&files, "/notes", "y")), + "Path is a directory, not a file: /notes" + ); + assert_eq!( + failure_of(write_to(&files, "/", "y")), + "Path is a directory, not a file: /" + ); + assert_eq!(files, before); +} + +#[test] +fn a_path_under_a_file_fails_saying_that_a_parent_is_not_a_directory() { + let files = Files::new().file("/a.md", "x"); + let before = files.clone(); + assert_eq!( + failure_of(write_to(&files, "/a.md/b.md", "y")), + "Path has a parent that is not a directory: /a.md/b.md" + ); + assert_eq!(files, before); +} + +#[test] +fn a_failure_echoes_the_path_as_the_model_wrote_it() { + let files = Files::new().file("/notes/a.md", "x"); + assert_eq!( + failure_of(write_to(&files, "notes", "y")), + "Path is a directory, not a file: notes" + ); + assert_eq!( + failure_of(write_to(&files, "notes/a.md/b", "y")), + "Path has a parent that is not a directory: notes/a.md/b" + ); +} + +#[test] +fn a_write_the_policy_denies_fails_with_the_policys_own_reason_and_changes_nothing() { + let reason = "Mode::Ask allows no write of /vault.md"; + let files = Files::new().fails("/vault.md", FileError::new(FileErrorKind::Denied, reason)); + let before = files.clone(); + assert_eq!(failure_of(write_to(&files, "/vault.md", "x")), reason); + assert_eq!(failure_of(write_to(&files, "/vault.md/in", "x")), reason); + assert_eq!(files, before); +} + +#[test] +fn a_write_that_fails_for_another_reason_is_worded_by_its_kind() { + let files = Files::new().fails( + "/disk.md", + FileError::new(FileErrorKind::Io, "storage full: no space left"), + ); + assert_eq!( + failure_of(write_to(&files, "/disk.md", "x")), + "I/O failure on /disk.md: storage full: no space left" + ); + // A failure of no named kind reads as the words it came with. + assert_eq!( + failure_of(write_to(&FakeSource::default(), "/a.md", "x")), + "the fake tree takes no change: /a.md" + ); +} + +#[test] +fn a_missing_path_or_contents_names_the_parameter() { + let files = Files::new(); + assert_eq!( + refused(write(&files, &json!({ "contents": "x" }))), + "std_Write: `path` is required, and the call left it out" + ); + assert_eq!( + refused(write(&files, &json!({ "path": "/a.md" }))), + "std_Write: `contents` is required, and the call left it out" + ); + assert_eq!( + refused(write(&files, &json!({ "path": "/a.md", "contents": 7 }))), + "std_Write: `contents` must be a JSON string, and the call passed 7" + ); + assert_eq!(files, Files::new()); +} + +#[test] +fn an_undeclared_key_is_refused_and_the_parameters_are_named() { + let files = Files::new(); + assert_eq!( + refused(write( + &files, + &json!({ "path": "/a.md", "contents": "x", "append": true }) + )), + "std_Write: `append` is not a parameter of this tool. \ + The parameters are `contents` and `path`." + ); + assert_eq!(files, Files::new()); +} + +#[test] +fn a_blank_path_is_refused_before_anything_is_written() { + let files = Files::new(); + for blank in ["", " ", "\t\n"] { + assert_eq!( + refused(write_to(&files, blank, "x")), + format!( + "std_Write: `path` is empty or only whitespace, and the call passed \"{blank}\"" + ) + ); + } + assert_eq!(files, Files::new()); +} + +#[test] +fn the_refusals_come_in_a_fixed_order() { + let files = Files::new(); + let over = "a".repeat(16_777_217); + assert_eq!( + refused(write( + &files, + &json!({ "path": " ", "contents": over, "mode": 7 }) + )), + "std_Write: `mode` is not a parameter of this tool. \ + The parameters are `contents` and `path`." + ); + assert_eq!( + refused(write_to(&files, " ", &over)), + "std_Write: `path` is empty or only whitespace, and the call passed \" \"" + ); +} diff --git a/crates/plugin-std/src/write.rs b/crates/plugin-std/src/write.rs new file mode 100644 index 0000000..61126b5 --- /dev/null +++ b/crates/plugin-std/src/write.rs @@ -0,0 +1,66 @@ +//! The `Write` tool: makes a file, or replaces the whole contents of one. +//! +//! Write hands the call's contents to the Host as one write through the +//! call's [`Source`], so the run's policy applies. The Host makes the +//! file when it is absent, with each directory on the way to it. Write +//! asks for nothing else: it takes no stat and no read first, so what +//! was at the path is gone when the write succeeds. Contents over +//! [`RV_MAX_WRITE`] bytes, the most one write takes, are refused before +//! the Host is asked for anything. The answer is fixed text and a count, +//! so it is trusted output. + +use runvil_plugin_sdk::sys::RV_MAX_WRITE; +use runvil_plugin_sdk::{ToolError, ToolErrorKind, ToolOutput}; +use serde_json::Value; + +use crate::check::{make_invalid_arguments_error, plural, refuse_blank, refuse_unknown}; +use crate::refusal::write_refusal; +use crate::source::Source; +use crate::spec::Definition; + +/// Runs one `Write` call whose arguments already passed the shared schema +/// check. +/// +/// The order of the refusals is fixed: an undeclared key, then a blank +/// path, then contents over the limit, so a call that breaks two rules +/// always hears about the same one. +/// +/// # Errors +/// Returns an invalid-arguments [`ToolError`] naming the parameter for a +/// bad argument, and a message error for a write the Host fails, worded +/// for a model to read. +pub(crate) async fn call( + source: &impl Source, + definition: &Definition, + args: &Value, +) -> Result { + let tool = definition.wire_name.as_str(); + refuse_unknown(tool, &definition.parameters, args)?; + let path = args.get("path").and_then(Value::as_str).unwrap_or_default(); + refuse_blank(tool, "path", path)?; + let contents = args + .get("contents") + .and_then(Value::as_str) + .unwrap_or_default(); + if contents.len() > RV_MAX_WRITE { + return Err(make_invalid_arguments_error( + tool, + format!( + "`contents` is {} bytes, and one write takes at most {RV_MAX_WRITE} bytes", + contents.len() + ), + )); + } + source + .write(path, contents.as_bytes().to_vec()) + .await + .map_err(|error| ToolError::new(ToolErrorKind::Other, write_refusal(tool, path, &error)))?; + Ok(ToolOutput::trusted(format!( + "Wrote {}.", + plural(contents.len(), "byte") + ))) +} + +#[cfg(test)] +#[path = "write-tests.rs"] +mod tests; diff --git a/crates/plugin-std/tests/it/changes.rs b/crates/plugin-std/tests/it/changes.rs new file mode 100644 index 0000000..61aa792 --- /dev/null +++ b/crates/plugin-std/tests/it/changes.rs @@ -0,0 +1,152 @@ +//! The tools that change files, through the Plugin's entry point: which +//! tools say to the Host that they change files, what a call leaves in +//! the files of its run, what it answers, and how many requests it makes. + +use plugin_std::Std; +use runvil_plugin_sdk::testing::{self, Files}; +use runvil_plugin_sdk::{FileError, FileErrorKind, ToolError, ToolErrorKind, ToolOutput}; +use serde_json::{Value, json}; + +use crate::tools::PACK; + +/// Calls the tool `name` with `args` over `files`, and returns what the +/// call answered beside the files as the call left them. +fn change(files: Files, name: &str, args: &Value) -> (Result, Files) { + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded + .new_pack(PACK) + .expect("the Pack instance is made") + .with_files(files); + let result = pack + .call(name, &args.to_string()) + .expect("the call follows the contract"); + (result, pack.files().clone()) +} + +/// How many steps a call of the tool `name` with `args` over `files` +/// takes to its end. Each file request ends one step, so a call that +/// makes `n` requests takes `n + 1` steps. +fn steps(files: Files, name: &str, args: &Value) -> usize { + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded + .new_pack(PACK) + .expect("the Pack instance is made") + .with_files(files); + let mut call = pack.start(name, &args.to_string()); + let mut steps = 1; + while call + .step() + .expect("each step follows the contract") + .is_none() + { + steps += 1; + } + steps +} + +/// The whole contents of the file at `path` in `files`. +fn contents(files: &Files, path: &str) -> Result, FileError> { + files.read(path, 0, u64::MAX) +} + +#[test] +fn the_tools_that_change_files_say_so_to_the_host_and_no_other_tool_does() { + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded.new_pack(PACK).expect("the Pack instance is made"); + let flagged: Vec<&str> = pack + .tools() + .iter() + .filter(|tool| tool.changes_files) + .map(|tool| tool.name.as_str()) + .collect(); + assert_eq!(flagged, ["write"]); +} + +#[test] +fn write_makes_a_file_and_answers_the_byte_count_as_trusted_output() { + let (result, files) = change( + Files::new(), + "write", + &json!({ "path": "/notes/a.md", "contents": "hello\n" }), + ); + let output = result.expect("the file is written"); + assert_eq!(output.text(), "Wrote 6 bytes."); + assert!(output.is_trusted()); + assert_eq!(contents(&files, "/notes/a.md"), Ok(b"hello\n".to_vec())); +} + +#[test] +fn write_replaces_the_whole_contents_of_a_file() { + let (result, files) = change( + Files::new().file("/a.md", "a long first version\n"), + "write", + &json!({ "path": "/a.md", "contents": "short" }), + ); + assert!(result.is_ok()); + assert_eq!(contents(&files, "/a.md"), Ok(b"short".to_vec())); +} + +#[test] +fn write_asks_the_host_for_one_write_and_nothing_else() { + let args = json!({ "path": "/a.md", "contents": "x" }); + assert_eq!(steps(Files::new(), "write", &args), 2); +} + +#[test] +fn a_write_the_policy_denies_fails_with_the_policys_own_reason_and_changes_nothing() { + let reason = "Mode::Ask allows no write of /vault.md"; + let before = Files::new() + .file("/a.md", "kept") + .fails("/vault.md", FileError::new(FileErrorKind::Denied, reason)); + let (result, after) = change( + before.clone(), + "write", + &json!({ "path": "/vault.md", "contents": "x" }), + ); + let error = result.expect_err("the policy denies the write"); + assert_eq!(error.message(), reason); + assert_eq!(error.kind(), ToolErrorKind::Other); + assert_eq!(after, before); +} + +#[test] +fn contents_over_the_limit_of_one_write_fail_naming_the_limit_before_the_host_is_asked() { + let args = json!({ "path": "/big.txt", "contents": "a".repeat(16_777_217) }); + let (result, files) = change(Files::new(), "write", &args); + let error = result.expect_err("the contents are over the limit"); + assert_eq!( + error.message(), + "std_Write: `contents` is 16777217 bytes, and one write takes at most 16777216 bytes" + ); + assert_eq!(error.kind(), ToolErrorKind::InvalidArguments); + assert_eq!(files, Files::new()); + assert_eq!(steps(Files::new(), "write", &args), 1); +} + +#[test] +fn a_path_longer_than_the_contract_takes_fails_before_the_host_is_asked() { + let args = json!({ "path": format!("/{}", "a".repeat(4096)), "contents": "x" }); + let (result, files) = change(Files::new(), "write", &args); + let error = result.expect_err("the path is over the limit"); + assert_eq!(error.message(), "the path is longer than 4096 bytes"); + assert_eq!(files, Files::new()); + assert_eq!(steps(Files::new(), "write", &args), 1); +} + +#[test] +fn a_later_call_of_the_run_reads_what_a_write_left() { + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded.new_pack(PACK).expect("the Pack instance is made"); + let written = pack + .call( + "write", + &json!({ "path": "/notes/a.md", "contents": "one\ntwo\n" }).to_string(), + ) + .expect("the call follows the contract"); + assert!(written.is_ok()); + let read = pack + .call("read", r#"{"path":"/notes/a.md"}"#) + .expect("the call follows the contract") + .expect("the file reads"); + assert_eq!(read.text(), " 1|one\n 2|two\n"); +} diff --git a/crates/plugin-std/tests/it/main.rs b/crates/plugin-std/tests/it/main.rs index 1f84e29..7948306 100644 --- a/crates/plugin-std/tests/it/main.rs +++ b/crates/plugin-std/tests/it/main.rs @@ -1,11 +1,12 @@ //! Integration tests for `plugin-std`, through its entry point and the //! SDK's fake Host: the Pack the Plugin inserts, the tools one run's -//! instance adds, and what a call answers with arguments that match or -//! miss the schema. +//! instance adds, what a call answers with arguments that match or miss +//! the schema, and what a call that changes files leaves in its run. #![expect( clippy::expect_used, reason = "test helpers panic on setup failure, which is the desired behavior" )] +mod changes; mod grep; mod tools; diff --git a/crates/plugin-std/tests/it/tools.rs b/crates/plugin-std/tests/it/tools.rs index 7d099ce..3f79e6a 100644 --- a/crates/plugin-std/tests/it/tools.rs +++ b/crates/plugin-std/tests/it/tools.rs @@ -73,11 +73,6 @@ fn each_run_gets_an_instance_of_its_own_with_the_same_tools() { #[test] fn every_stub_answers_the_not_implemented_text_naming_itself() { for (name, wire_name, args) in [ - ( - "write", - "Write", - json!({ "path": "/notes.md", "contents": "hi" }), - ), ( "replace", "StrReplace", From caad57df163096fc136fbeb3285501a72764c796 Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Tue, 17 Nov 2026 23:52:26 -0800 Subject: [PATCH 04/13] Implement StrReplace as a read and then a `write` A run needs a tool that edits a part of a file. StrReplace reads the file with `load` of `read.rs`, requires UTF-8, counts `old_string`, and hands the edited text to the Host as one `write`. The text must occur exactly once unless `replace_all` is set, and a failure states the count. - `load` comes out of `read_file` and is `pub(crate)`: the stat, the check of the file type, the read under `MAX_FILE_BYTES`, and the refusal of a larger file. Read and StrReplace refuse the same paths in the same sentences, and StrReplace never opens a pipe or a device. - `changes_files` flags `replace` too, so the Host runs each call of StrReplace by itself among the calls of one model reply. - `Node::Guarded` in `fake.rs` is a file that reads and that fails each change with its error. The tests use it for a write that the Host fails after the read succeeded. - The count is `text.matches(request.old).count()`, so matches do not overlap. No match fails every call, and more than one match fails a call without `replace_all`. - The match is exact and nothing is decoded, so a byte order mark and the line endings stay. A file that is not UTF-8 is refused. - An edit that leaves the file with more than `RV_MAX_WRITE` bytes is refused before the write. - StrReplace refuses an undeclared key, a blank `path`, an empty `old_string`, and a `new_string` equal to `old_string`, in that order, before it reads. - The answer holds fixed text and the count of replacements, so it is trusted output. - An edit takes four steps: the stat, the read, the write, and the answer. A call that fails on the count takes three, and a test holds both numbers. - `replace.json` gains a `Usage` list with the `{file_ceiling}` placeholder, and `EDITS.md` records it. `README.md`, `AGENTS.md`, and the crate docs say that StrReplace is real. - The edit is two requests to the Host, so a change that another task makes to the file between the read and the write is lost. The docs say so, and no test covers it. - StrReplace does not run the binary check of Read, so it edits a file of valid UTF-8 that Read refuses as binary. No test covers that. - Delete and Glob stay stubs. Plan: runvil-harness/plan/2026-11-16-1-tool-file-effects.plan.md --- AGENTS.md | 2 +- README.md | 7 +- crates/plugin-std/schemas/EDITS.md | 1 + crates/plugin-std/schemas/replace.json | 2 +- crates/plugin-std/src/fake.rs | 41 ++- crates/plugin-std/src/lib.rs | 32 +- crates/plugin-std/src/pack-tests.rs | 11 +- crates/plugin-std/src/pack.rs | 10 +- crates/plugin-std/src/read.rs | 48 ++- crates/plugin-std/src/replace-tests.rs | 408 +++++++++++++++++++++++++ crates/plugin-std/src/replace.rs | 147 +++++++++ crates/plugin-std/src/spec-tests.rs | 31 ++ crates/plugin-std/src/spec.rs | 3 + crates/plugin-std/tests/it/changes.rs | 88 +++++- crates/plugin-std/tests/it/tools.rs | 5 - 15 files changed, 780 insertions(+), 56 deletions(-) create mode 100644 crates/plugin-std/src/replace-tests.rs create mode 100644 crates/plugin-std/src/replace.rs diff --git a/AGENTS.md b/AGENTS.md index bae135f..c8819bc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,7 +28,7 @@ Anything else gets a qualified lowercase name, such as Rust's built-in test harn - The Plugin crate depends on `runvil-plugin-sdk` and outside libraries alone, and writes no `unsafe`. The SDK owns the C boundary. - A tool reaches files only through `Source` (`crates/plugin-std/src/source.rs`), which the call's `ToolCall` implements, so every file operation goes through the Host and the run's policy applies to it. A test runs a tool's own code over the SDK's `testing::Files` tree, or over `FakeSource` (`crates/plugin-std/src/fake.rs`) for what that tree cannot hold. - A tool that changes files says so with `ToolInfo::changes_files`, so the Host runs each of its calls by itself among the calls of one model reply. -- StrReplace and Delete are stubs until each is built on the file methods of the SDK that change files, which `Source` gains with them. +- Delete is a stub until it is built on the file method of the SDK that removes a file, which `Source` gains with it. - A tool's description and parameter schema come from its JSON file under `crates/plugin-std/schemas`. `EDITS.md` beside them records every difference from Cursor's definition, and a change to a JSON file changes `EDITS.md` with it. - A tool that does a long job awaits `next_step()` after each bounded slice of work, as Grep does every 32 files or directories, so that no step of its call works for long and the Host can abandon the call between two steps. - A Plugin shares its process with the Host, so nothing here installs process-global state, such as a panic hook (`clippy.toml` bans `std::panic::set_hook`), and nothing starts a thread that outlives the Plugin's unload. What every run shares lives in the Plugin instance and never in a `static`, so an unload frees it. diff --git a/README.md b/README.md index 1ebd563..a5eaa1e 100644 --- a/README.md +++ b/README.md @@ -10,14 +10,15 @@ The Plugin inserts one Pack, `runvil/std`, which gives a run the standard file t | `std/dir` | `ListDir` | Returns a bullet tree of a directory, listed breadth first | | `std/grep` | `Grep` | Searches the files under a path with a Rust regular expression | | `std/write` | `Write` | Creates a file, or replaces the whole contents of one | -| `std/replace` | `StrReplace` | A stub: answers that the tool is not implemented | -| `std/rm` | `Delete` | A stub | +| `std/replace` | `StrReplace` | Replaces a text that occurs once in a file, or every occurrence of it | +| `std/rm` | `Delete` | A stub: answers that the tool is not implemented | | `std/glob` | `Glob` | A stub | - Each tool's wire name, description, and parameter schema is a JSON file under `crates/plugin-std/schemas`, and `EDITS.md` beside them lists how each differs from Cursor's definition. - Every file operation of a tool goes through the Host, so the run's policy applies to each one. An operation the policy denies fails the call with the policy's own reason. The one exception is an entry below the path a Grep call names, which Grep skips and counts. - File text and file names come back as untrusted output. The Host marks them before a model reads them. The answer to a change is fixed text and a count, which is trusted output. -- Write says to the Host that it changes files. The Host runs a call of such a tool by itself among the calls of one model reply, so two changes of one reply happen in the order the reply lists them. +- Write and StrReplace say to the Host that they change files. The Host runs a call of such a tool by itself among the calls of one model reply, so two changes of one reply happen in the order the reply lists them. +- StrReplace edits a file with a read and then a write, so a change that another task makes to the file between the two is lost. - A tool call ends its step at each file operation, and the Host performs the operation before the next step. A search also ends its step every 32 files or directories, so the Host can cancel a call between two steps. ## Building diff --git a/crates/plugin-std/schemas/EDITS.md b/crates/plugin-std/schemas/EDITS.md index dc1d117..ee77371 100644 --- a/crates/plugin-std/schemas/EDITS.md +++ b/crates/plugin-std/schemas/EDITS.md @@ -22,6 +22,7 @@ Each file in this directory except `dir.json` is Cursor's definition of the tool ## replace.json - Cursor's `StrReplace` definition. The wording is ours; the parameters, their types, and the `required` list are Cursor's. +- Added a `Usage` list that states what StrReplace does: `old_string` is matched exactly, and the line number and the pipe that Read shows are not part of the file; a call fails with the count when `old_string` does not occur exactly once, and with `replace_all` it fails only when there is no occurrence; only UTF-8 text is edited, and a file over `{file_ceiling}` bytes is refused; and the calls in one response that change files run one after another in the order listed. The placeholder is filled when the definition is built, from the constant the code enforces, so the text and the limit cannot drift apart. ## rm.json diff --git a/crates/plugin-std/schemas/replace.json b/crates/plugin-std/schemas/replace.json index aa7718e..6d7d516 100644 --- a/crates/plugin-std/schemas/replace.json +++ b/crates/plugin-std/schemas/replace.json @@ -1,6 +1,6 @@ { "wire_name": "StrReplace", - "description": "Replaces an exact string in a file with a new string. The old string must be unique in the file unless replace_all is true, so include enough surrounding context to identify the one occurrence you mean. Read the file first.", + "description": "Replaces an exact string in a file with a new string. The old string must be unique in the file unless replace_all is true, so include enough surrounding context to identify the one occurrence you mean. Read the file first.\n\nUsage:\n- old_string is matched exactly, so whitespace, indentation, and line endings count. The line number and the pipe that Read shows are not part of the file.\n- When old_string does not occur exactly once, the call fails and says how many times it occurs. With replace_all set to true, the call replaces every occurrence, and it fails only when there is none.\n- Only UTF-8 text is edited. A file over {file_ceiling} bytes is refused.\n- The calls in one response that change files run one after another, in the order you list them.", "parameters": { "type": "object", "properties": { diff --git a/crates/plugin-std/src/fake.rs b/crates/plugin-std/src/fake.rs index 8969214..1ca0fce 100644 --- a/crates/plugin-std/src/fake.rs +++ b/crates/plugin-std/src/fake.rs @@ -4,11 +4,13 @@ //! //! The fake holds what the fake Host's tree cannot: a link to a directory //! or to a file, a pipe, a file whose listed size differs from its bytes, -//! and a directory or a file that fails only when it is listed or read. A -//! name may hold any character, a control character among them. +//! a directory or a file that fails only when it is listed or read, and a +//! file that fails only a change. A name may hold any +//! character, a control character among them. //! //! Every node sits directly under `/`, or under a [`Node::Link`], which -//! lists as a directory. The tree never changes: it fails every change. +//! lists as a directory. The tree never changes: it fails every change, +//! with the error of a [`Node::Guarded`] where the path names one. use std::collections::BTreeMap; use std::future::Future; @@ -55,6 +57,9 @@ pub(crate) enum Node { ListFails(FileError), /// A file whose read fails with this error. ReadFails(FileError), + /// A file with these bytes that fails each change with this error, as + /// a file that the run's policy lets a tool read and not change. + Guarded(Vec, FileError), } /// A tree of nodes by absolute path, with `/` always a directory. @@ -79,7 +84,9 @@ impl FakeSource { /// The metadata of `node`. fn stat_of(node: &Node) -> Stat { match node { - Node::File(bytes) => Stat::new(FileType::File, bytes.len() as u64), + Node::File(bytes) | Node::Guarded(bytes, _) => { + Stat::new(FileType::File, bytes.len() as u64) + } Node::Sized(size, _) => Stat::new(FileType::File, *size), Node::ReadFails(_) => Stat::new(FileType::File, 1), Node::ListFails(_) => Stat::new(FileType::Directory, 0), @@ -94,6 +101,18 @@ impl FakeSource { fn missing(path: &str) -> FileError { FileError::new(FileErrorKind::NotFound, format!("not found: {path}")) } + + /// The error of a change to `path`, which the tree never takes: the + /// error of a [`Node::Guarded`], and a fixed one for any other path. + fn refused(&self, path: &str) -> FileError { + match self.nodes.get(path) { + Some(Node::Guarded(_, error)) => error.clone(), + _ => FileError::new( + FileErrorKind::Other, + format!("the fake tree takes no change: {path}"), + ), + } + } } /// The directory that holds `path`, and the name it has there. @@ -146,9 +165,12 @@ impl Source for FakeSource { async fn read(&self, path: &str) -> Result, FileError> { match self.nodes.get(path) { - Some(Node::File(bytes) | Node::Sized(_, bytes) | Node::LinkToFile(bytes)) => { - Ok(bytes.clone()) - } + Some( + Node::File(bytes) + | Node::Sized(_, bytes) + | Node::LinkToFile(bytes) + | Node::Guarded(bytes, _), + ) => Ok(bytes.clone()), Some(Node::ReadFails(error) | Node::LinkFails(error)) => Err(error.clone()), Some(Node::Link | Node::ListFails(_)) => Err(FileError::new( FileErrorKind::IsADirectory, @@ -165,9 +187,6 @@ impl Source for FakeSource { } async fn write(&self, path: &str, _bytes: Vec) -> Result<(), FileError> { - Err(FileError::new( - FileErrorKind::Other, - format!("the fake tree takes no change: {path}"), - )) + Err(self.refused(path)) } } diff --git a/crates/plugin-std/src/lib.rs b/crates/plugin-std/src/lib.rs index 643e4ab..6ba6f3a 100644 --- a/crates/plugin-std/src/lib.rs +++ b/crates/plugin-std/src/lib.rs @@ -73,9 +73,19 @@ //! the count of bytes written in fixed text, so it comes back as trusted //! output. //! -//! StrReplace, Delete, and Glob are still stubs: a call with arguments -//! that match the schema answers [`NOT_IMPLEMENTED`]. For every tool, a -//! call whose arguments do not match fails with an invalid-arguments +//! StrReplace is real. It reads a file as Read does, with the same +//! refusals of a directory, a special file, and a file over 16 MiB, and +//! it writes the file back with one text in place of another. The file +//! must hold UTF-8, and nothing outside the matches changes. The text to +//! replace must occur exactly once, unless `replace_all` is set, and a +//! failure states how many times it occurs. The edit is a read and then a +//! write, so a change that another task makes to the file between the two +//! is lost. Its answer is the count of replacements in fixed +//! text, so it comes back as trusted output. +//! +//! Delete and Glob are still stubs: a call with arguments that match the +//! schema answers [`NOT_IMPLEMENTED`]. For every tool, a call whose +//! arguments do not match fails with an invalid-arguments //! [`ToolError`](runvil_plugin_sdk::ToolError) naming the parameter. //! //! # Where the file access goes @@ -91,10 +101,10 @@ //! fails the same way on a directory that is there and cannot be listed, //! and Grep skips the entry and counts it. //! -//! A tool that changes files says so to the Host, as Write does. The Host -//! runs a call of such a tool by itself among the calls of one model -//! reply, after the calls the reply lists before it, so two changes of -//! one reply happen in the order the reply lists them. +//! A tool that changes files says so to the Host, as Write and StrReplace +//! do. The Host runs a call of such a tool by itself among the calls of +//! one model reply, after the calls the reply lists before it, so two +//! changes of one reply happen in the order the reply lists them. //! //! Shell is deliberately absent. An in-process shell over the same //! filesystem is a separate Pack, so a run that wants one declares it. @@ -123,9 +133,10 @@ //! arguments, so a model can tell a bad call from a missing //! implementation. //! - A key the schema does not declare is refused by name, with the -//! parameters listed, by the four real tools, Read, ListDir, Grep, and -//! Write. The stubs let it through. Grep alone accepts `-n` when it is -//! `true`, because Cursor's definition once declared it. +//! parameters listed, by the five real tools, Read, ListDir, Grep, +//! Write, and StrReplace. The stubs let it through. Grep alone accepts +//! `-n` when it is `true`, because Cursor's definition once declared +//! it. //! - A tool that changes files is flagged with //! [`ToolInfo::changes_files`](runvil_plugin_sdk::ToolInfo::changes_files), //! and a test holds the flags in place. @@ -140,6 +151,7 @@ mod order; mod pack; mod read; mod refusal; +mod replace; mod source; mod spec; mod text; diff --git a/crates/plugin-std/src/pack-tests.rs b/crates/plugin-std/src/pack-tests.rs index cdeb19f..286147e 100644 --- a/crates/plugin-std/src/pack-tests.rs +++ b/crates/plugin-std/src/pack-tests.rs @@ -139,13 +139,16 @@ fn a_call_goes_to_the_tool_its_name_picks() { ran("write", r#"{"path":"/p/c.md","contents":"x"}"#, &files).expect("the file is written"); assert_eq!(write.text(), "Wrote 1 byte."); assert_eq!(files.read("/p/c.md", 0, u64::MAX), Ok(b"x".to_vec())); - let stub = ran( + let replace = ran( "replace", r#"{"path":"/p/c.md","old_string":"x","new_string":"y"}"#, &files, ) - .expect("a stub answers its text"); - assert_eq!(stub.text(), NOT_IMPLEMENTED.replace("", "StrReplace")); + .expect("the file is edited"); + assert_eq!(replace.text(), "Made 1 replacement."); + assert_eq!(files.read("/p/c.md", 0, u64::MAX), Ok(b"y".to_vec())); + let stub = ran("rm", r#"{"path":"/p/c.md"}"#, &files).expect("a stub answers its text"); + assert_eq!(stub.text(), NOT_IMPLEMENTED.replace("", "Delete")); assert!(stub.is_trusted()); } @@ -158,5 +161,5 @@ fn an_instance_flags_the_tools_that_change_files_and_no_other() { .filter(|tool| tool.changes_files) .map(|tool| tool.name.as_str()) .collect(); - assert_eq!(flagged, ["write"]); + assert_eq!(flagged, ["write", "replace"]); } diff --git a/crates/plugin-std/src/pack.rs b/crates/plugin-std/src/pack.rs index 7e09c83..f927eb8 100644 --- a/crates/plugin-std/src/pack.rs +++ b/crates/plugin-std/src/pack.rs @@ -1,7 +1,6 @@ //! The `std` Pack: its [`INFO`], [`StdPack`], one run's instance, which //! lists the Pack's tools and hands each call to its tool's module, and -//! the stub that every tool but Read, ListDir, Grep, and Write still -//! answers with in this build. +//! the stub that Delete and Glob still answer with in this build. use std::sync::Arc; @@ -15,8 +14,8 @@ use crate::source::Source; use crate::spec::Definition; /// What a call to a tool that is still a stub answers in this build, when -/// its arguments match the schema. Read, ListDir, Grep, and Write are -/// real and never answer this. +/// its arguments match the schema. Delete and Glob are the stubs, and +/// every other tool is real and never answers this. /// /// The text says the implementation is missing rather than that the call /// was wrong, because a model that reads it should stop calling the tool. @@ -72,7 +71,7 @@ impl StdPack { /// calls of one model reply, after the calls the reply lists before it, /// so two changes of one reply happen in the order the reply lists them. fn changes_files(segment: &str) -> bool { - segment == "write" + matches!(segment, "write" | "replace") } /// The stub text for the tool the model calls `wire_name`. @@ -113,6 +112,7 @@ async fn run( "dir" => crate::dir::call(source, definition, &args).await, "grep" => crate::grep::call(source, definition, &args).await, "write" => crate::write::call(source, definition, &args).await, + "replace" => crate::replace::call(source, definition, &args).await, _ => Ok(ToolOutput::trusted(stub(&definition.wire_name))), } } diff --git a/crates/plugin-std/src/read.rs b/crates/plugin-std/src/read.rs index 09b0bd3..572b517 100644 --- a/crates/plugin-std/src/read.rs +++ b/crates/plugin-std/src/read.rs @@ -55,18 +55,7 @@ async fn read_file( ) -> Result { let path = request.path; let message = |text: String| ToolError::new(ToolErrorKind::Other, text); - let failed = |error: FileError| message(refusal(tool, path, &error)); - let stat = source.stat(path).await.map_err(failed)?; - check_type(path, stat.file_type).map_err(message)?; - let bytes = source - .read_prefix(path, MAX_FILE_BYTES + 1) - .await - .map_err(failed)?; - if u64::try_from(bytes.len()).unwrap_or(u64::MAX) > MAX_FILE_BYTES { - return Err(message(format!( - "File is too large to read: {path} is over the limit of {MAX_FILE_BYTES} bytes." - ))); - } + let bytes = load(source, tool, path).await.map_err(message)?; if sniff_binary(&bytes) { return Err(message(format!( "File content is binary data, not text: {path}" @@ -90,14 +79,43 @@ async fn read_file( ))) } -/// Decides from the kind of node at `path` whether Read goes on: a file -/// or a link does, and anything else gets the sentence that says why not. +/// The bytes of the file at `path`, for a tool that works on a file's +/// text: Read, and StrReplace, which edits what Read shows. `tool` is the +/// name the model called the tool by. +/// +/// The stat comes first, so a directory and a special file are refused +/// and never opened. The read stops one byte past the ceiling, so a file +/// over it is refused and never held whole. +/// +/// # Errors +/// Returns the sentence a model reads when the path is missing, names a +/// directory or a special file, holds more than [`MAX_FILE_BYTES`] bytes, +/// or cannot be read. +pub(crate) async fn load(source: &impl Source, tool: &str, path: &str) -> Result, String> { + let failed = |error: FileError| refusal(tool, path, &error); + let stat = source.stat(path).await.map_err(failed)?; + check_type(path, stat.file_type)?; + let bytes = source + .read_prefix(path, MAX_FILE_BYTES + 1) + .await + .map_err(failed)?; + if u64::try_from(bytes.len()).unwrap_or(u64::MAX) > MAX_FILE_BYTES { + return Err(format!( + "File is too large to read: {path} is over the limit of {MAX_FILE_BYTES} bytes." + )); + } + Ok(bytes) +} + +/// Decides from the kind of node at `path` whether its bytes are read: a +/// file or a link is read, and anything else gets the sentence that says +/// why not. fn check_type(path: &str, file_type: FileType) -> Result<(), String> { match file_type { FileType::File | FileType::Symlink => Ok(()), FileType::Directory => Err(format!("Path is a directory, not a file: {path}")), // A pipe, a socket, or a device, and any kind added later: none - // of them is text Read can window. + // of them holds text, and a read of one can block for good. _ => Err(neither_file_nor_directory(path)), } } diff --git a/crates/plugin-std/src/replace-tests.rs b/crates/plugin-std/src/replace-tests.rs new file mode 100644 index 0000000..cb6864a --- /dev/null +++ b/crates/plugin-std/src/replace-tests.rs @@ -0,0 +1,408 @@ +//! Unit tests for the `StrReplace` tool: what an edit leaves in the file, +//! what it answers, how it counts the text to replace, and what it +//! refuses before it reads and before it writes. + +use runvil_plugin_sdk::testing::Files; +use runvil_plugin_sdk::{ + FileError, FileErrorKind, FileType, Stat, ToolError, ToolErrorKind, ToolOutput, +}; +use serde_json::{Value, json}; + +use crate::fake::{FakeSource, Node, block_on}; +use crate::source::Source; +use crate::spec::{self, Definition}; + +/// The `replace` definition the Pack builds the tool from. +fn definition() -> &'static Definition { + spec::all() + .iter() + .find(|definition| definition.segment == "replace") + .expect("the replace definition exists") +} + +/// Calls StrReplace over `files` with `args` as the Pack does: the schema +/// check first, then the tool. +fn replace(files: &impl Source, args: &Value) -> Result { + let definition = definition(); + crate::check::check(&definition.wire_name, &definition.parameters, args)?; + block_on(super::call(files, definition, args)) +} + +/// Replaces `old` with `new` in the file at `path`, where `old` must +/// occur once. +fn edit(files: &impl Source, path: &str, old: &str, new: &str) -> Result { + replace( + files, + &json!({ "path": path, "old_string": old, "new_string": new }), + ) +} + +/// Replaces every `old` with `new` in the file at `path`. +fn edit_all( + files: &impl Source, + path: &str, + old: &str, + new: &str, +) -> Result { + replace( + files, + &json!({ "path": path, "old_string": old, "new_string": new, "replace_all": true }), + ) +} + +/// The whole contents of the file at `path`. +fn contents(files: &Files, path: &str) -> Vec { + files.read(path, 0, u64::MAX).expect("the file is there") +} + +/// The text of a successful edit, which must be trusted output. +fn text_of(result: Result) -> String { + let output = result.expect("the edit succeeds"); + assert!(output.is_trusted(), "{}", output.text()); + output.text().to_owned() +} + +/// The message of a failed edit, which must not be an invalid-arguments +/// failure. +fn failure_of(result: Result) -> String { + match result { + Ok(output) => panic!("the edit fails, but it answered {:?}", output.text()), + Err(error) => { + assert_eq!(error.kind(), ToolErrorKind::Other, "{error}"); + error.to_string() + } + } +} + +/// The message of an edit whose arguments are refused. +fn refused(result: Result) -> String { + match result { + Ok(output) => panic!("the call is refused, but it answered {:?}", output.text()), + Err(error) => { + assert_eq!(error.kind(), ToolErrorKind::InvalidArguments, "{error}"); + error.to_string() + } + } +} + +#[test] +fn the_new_text_takes_the_place_of_the_one_occurrence_and_the_rest_of_the_file_stays() { + let files = Files::new().file("/a.md", "one\ntwo\nthree\n"); + assert_eq!( + text_of(edit(&files, "/a.md", "two", "2")), + "Made 1 replacement." + ); + assert_eq!(contents(&files, "/a.md"), b"one\n2\nthree\n"); +} + +#[test] +fn an_old_string_may_span_lines_and_the_new_string_may_be_empty() { + let files = Files::new().file("/a.md", "one\ntwo\nthree\n"); + assert!(edit(&files, "/a.md", "one\ntwo\n", "").is_ok()); + assert_eq!(contents(&files, "/a.md"), b"three\n"); +} + +#[test] +fn replace_all_replaces_every_occurrence_and_counts_them() { + let files = Files::new().file("/a.rs", "let x = x + x;\n"); + assert_eq!( + text_of(edit_all(&files, "/a.rs", "x", "total")), + "Made 3 replacements." + ); + assert_eq!(contents(&files, "/a.rs"), b"let total = total + total;\n"); +} + +#[test] +fn replace_all_with_one_occurrence_replaces_it() { + let files = Files::new().file("/a.md", "one two\n"); + assert_eq!( + text_of(edit_all(&files, "/a.md", "two", "2")), + "Made 1 replacement." + ); + assert_eq!(contents(&files, "/a.md"), b"one 2\n"); +} + +#[test] +fn an_old_string_that_occurs_more_than_once_fails_with_the_count_and_changes_nothing() { + let files = Files::new().file("/a.rs", "let x = x + x;\n"); + let before = files.clone(); + assert_eq!( + failure_of(edit(&files, "/a.rs", "x", "total")), + "`old_string` occurs 3 times in /a.rs, and it must occur exactly once. Add text around \ + it until it names one occurrence, or set `replace_all` to replace every one." + ); + assert_eq!(files, before); +} + +#[test] +fn an_old_string_that_is_absent_fails_with_the_count_and_changes_nothing() { + let files = Files::new().file("/a.md", "one\ntwo\n"); + let before = files.clone(); + assert_eq!( + failure_of(edit(&files, "/a.md", "three", "3")), + "`old_string` occurs 0 times in /a.md, and it must occur exactly once. It is matched \ + exactly, so whitespace and line endings count." + ); + assert_eq!( + failure_of(edit_all(&files, "/a.md", "three", "3")), + "`old_string` occurs 0 times in /a.md, and it must occur at least once. It is matched \ + exactly, so whitespace and line endings count." + ); + assert_eq!(files, before); +} + +#[test] +fn replace_all_that_is_false_or_null_needs_one_occurrence() { + let files = Files::new().file("/a.md", "x x\n"); + for flag in [json!(false), json!(null)] { + let args = json!({ + "path": "/a.md", "old_string": "x", "new_string": "y", "replace_all": flag + }); + assert!( + failure_of(replace(&files, &args)).starts_with("`old_string` occurs 2 times"), + "{args}" + ); + } +} + +#[test] +fn the_match_is_exact_in_case_whitespace_and_line_endings() { + let files = Files::new().file("/a.txt", "Alpha\r\n beta\r\n"); + for miss in ["alpha", " beta\r\n ", "Alpha\n beta"] { + assert!( + failure_of(edit(&files, "/a.txt", miss, "x")) + .starts_with("`old_string` occurs 0 times"), + "{miss:?}" + ); + } + assert!(edit(&files, "/a.txt", "Alpha\r\n beta", "gamma").is_ok()); + assert_eq!(contents(&files, "/a.txt"), b"gamma\r\n"); +} + +#[test] +fn a_byte_order_mark_and_the_line_endings_stay_as_they_are() { + let files = Files::new().file("/a.txt", "\u{feff}one\r\ntwo\r\n"); + assert!(edit(&files, "/a.txt", "two", "2").is_ok()); + assert_eq!( + contents(&files, "/a.txt"), + "\u{feff}one\r\n2\r\n".as_bytes() + ); +} + +#[test] +fn the_text_put_in_is_not_searched_again() { + let files = Files::new().file("/a.txt", "a a"); + assert_eq!( + text_of(edit_all(&files, "/a.txt", "a", "aa")), + "Made 2 replacements." + ); + assert_eq!(contents(&files, "/a.txt"), b"aa aa"); +} + +#[test] +fn matches_are_counted_from_the_start_and_never_overlap() { + let files = Files::new().file("/a.txt", "aaa"); + assert_eq!( + text_of(edit(&files, "/a.txt", "aa", "b")), + "Made 1 replacement." + ); + assert_eq!(contents(&files, "/a.txt"), b"ba"); +} + +#[test] +fn a_file_that_is_not_utf8_is_refused_and_stays_as_it_is() { + let mut utf16 = vec![0xFF, 0xFE]; + for unit in "one\n".encode_utf16() { + utf16.extend_from_slice(&unit.to_le_bytes()); + } + let files = Files::new() + .file("/latin.txt", b"caf\xE9 one\n") + .file("/utf16.txt", &utf16); + let before = files.clone(); + for path in ["/latin.txt", "/utf16.txt"] { + assert_eq!( + failure_of(edit(&files, path, "one", "1")), + format!("File is not UTF-8 text, so it cannot be edited: {path}") + ); + } + assert_eq!(files, before); +} + +#[test] +fn a_missing_file_and_a_directory_fail_as_they_do_for_a_read() { + let files = Files::new().file("/dir/a.md", "x\n"); + assert_eq!( + failure_of(edit(&files, "/nope.md", "x", "y")), + "File not found: /nope.md" + ); + assert_eq!( + failure_of(edit(&files, "notes/a.md", "x", "y")), + "File not found: notes/a.md" + ); + assert_eq!( + failure_of(edit(&files, "/dir", "x", "y")), + "Path is a directory, not a file: /dir" + ); +} + +#[test] +fn a_pipe_is_refused_by_its_stat_and_never_read() { + // The fake fails a read of the pipe as not found, so this text shows + // that the edit stopped at the stat. + let source = FakeSource::default().with("/pipe", Node::Pipe); + assert_eq!( + failure_of(edit(&source, "/pipe", "x", "y")), + "Path is neither a file nor a directory: /pipe" + ); +} + +#[test] +fn a_link_is_read_through_and_a_link_to_a_directory_is_a_directory() { + let source = FakeSource::default() + .with("/filelink", Node::LinkToFile(b"one two\n".to_vec())) + .with("/dirlink", Node::Link); + // The fake takes no change, so this text shows that the edit read + // the link's file, found its one match, and asked for the write. + assert_eq!( + failure_of(edit(&source, "/filelink", "two", "2")), + "the fake tree takes no change: /filelink" + ); + assert_eq!( + failure_of(edit(&source, "/dirlink", "two", "2")), + "Path is a directory, not a file: /dirlink" + ); +} + +#[test] +fn a_file_over_the_ceiling_is_refused_and_never_edited() { + let files = Files::new().file("/big.txt", vec![b'a'; 16_777_217]); + assert_eq!( + failure_of(edit_all(&files, "/big.txt", "a", "b")), + "File is too large to read: /big.txt is over the limit of 16777216 bytes." + ); + assert_eq!( + files.read("/big.txt", 0, 4), + Ok(b"aaaa".to_vec()), + "the file stays as it was" + ); +} + +#[test] +fn an_edit_that_grows_the_file_past_one_write_is_refused_and_one_at_the_limit_is_written() { + let mut text = String::from("X"); + text.push_str(&"a".repeat(16_777_215)); + let files = Files::new().file("/edge.txt", &text); + assert_eq!( + failure_of(edit(&files, "/edge.txt", "X", "XY")), + "The edit would leave /edge.txt with 16777217 bytes, and one write takes at most \ + 16777216 bytes." + ); + assert_eq!(files.read("/edge.txt", 0, 2), Ok(b"Xa".to_vec())); + assert!(edit(&files, "/edge.txt", "X", "Y").is_ok()); + assert_eq!(files.read("/edge.txt", 0, 2), Ok(b"Ya".to_vec())); + assert_eq!( + files.stat("/edge.txt"), + Ok(Stat::new(FileType::File, 16_777_216)) + ); +} + +#[test] +fn a_read_the_policy_denies_fails_with_the_policys_own_reason() { + let reason = "Mode::Plan allows only markdown paths, and /secret.rs is not one"; + let files = Files::new().fails("/secret.rs", FileError::new(FileErrorKind::Denied, reason)); + assert_eq!(failure_of(edit(&files, "/secret.rs", "x", "y")), reason); + let source = FakeSource::default().with( + "/late.rs", + Node::ReadFails(FileError::new(FileErrorKind::Denied, reason)), + ); + assert_eq!(failure_of(edit(&source, "/late.rs", "x", "y")), reason); +} + +#[test] +fn a_write_the_host_fails_after_the_read_succeeded_is_worded_by_its_kind() { + let guarded = + |kind, text: &str| Node::Guarded(b"one two\n".to_vec(), FileError::new(kind, text)); + let reason = "Mode::Ask allows no write of /ask.md"; + let source = FakeSource::default() + .with("/ask.md", guarded(FileErrorKind::Denied, reason)) + .with( + "/disk.md", + guarded(FileErrorKind::Io, "storage full: no space left"), + ); + assert_eq!(failure_of(edit(&source, "/ask.md", "two", "2")), reason); + assert_eq!( + failure_of(edit(&source, "/disk.md", "two", "2")), + "I/O failure on /disk.md: storage full: no space left" + ); +} + +#[test] +fn a_missing_parameter_or_one_of_the_wrong_type_names_the_parameter() { + let files = Files::new(); + assert_eq!( + refused(replace( + &files, + &json!({ "path": "/a.md", "old_string": "x" }) + )), + "std_StrReplace: `new_string` is required, and the call left it out" + ); + assert_eq!( + refused(replace( + &files, + &json!({ + "path": "/a.md", "old_string": "x", "new_string": "y", "replace_all": "yes" + }) + )), + "std_StrReplace: `replace_all` must be a JSON boolean, and the call passed \"yes\"" + ); +} + +#[test] +fn an_undeclared_key_is_refused_and_the_parameters_are_named() { + let files = Files::new(); + assert_eq!( + refused(replace( + &files, + &json!({ "path": "/a.md", "old_string": "x", "new_string": "y", "count": 2 }) + )), + "std_StrReplace: `count` is not a parameter of this tool. \ + The parameters are `new_string`, `old_string`, `path` and `replace_all`." + ); +} + +#[test] +fn an_empty_old_string_and_a_new_string_equal_to_it_are_refused_before_any_read() { + // No file is there, so a call that got as far as its read would say + // that the file was not found. + let files = Files::new(); + assert_eq!( + refused(edit(&files, "/a.md", "", "y")), + "std_StrReplace: `old_string` is empty. Pass the text to replace." + ); + assert_eq!( + refused(edit(&files, "/a.md", "same", "same")), + "std_StrReplace: `new_string` is the same as `old_string`, so the call would change \ + nothing" + ); +} + +#[test] +fn the_refusals_come_in_a_fixed_order() { + let files = Files::new(); + assert_eq!( + refused(replace( + &files, + &json!({ "path": " ", "old_string": "", "new_string": "", "all": true }) + )), + "std_StrReplace: `all` is not a parameter of this tool. \ + The parameters are `new_string`, `old_string`, `path` and `replace_all`." + ); + assert_eq!( + refused(edit(&files, " ", "", "")), + "std_StrReplace: `path` is empty or only whitespace, and the call passed \" \"" + ); + assert_eq!( + refused(edit(&files, "/a.md", "", "")), + "std_StrReplace: `old_string` is empty. Pass the text to replace." + ); +} diff --git a/crates/plugin-std/src/replace.rs b/crates/plugin-std/src/replace.rs new file mode 100644 index 0000000..f59e1fe --- /dev/null +++ b/crates/plugin-std/src/replace.rs @@ -0,0 +1,147 @@ +//! The `StrReplace` tool: replaces a text in a file with another text. +//! +//! StrReplace reads the file as Read does, through the call's +//! [`Source`], so the run's policy applies and the same paths are +//! refused: a directory, a special file, and a file over 16 MiB. The file +//! must hold UTF-8. Nothing is decoded, and nothing outside the matches +//! changes, so a byte order mark and the line endings stay as they are. +//! The text to replace must occur exactly once, unless `replace_all` is +//! set, and a failure states how many times it occurs. +//! +//! The edit is a read and then a write, each a request to the Host of its +//! own. A change that another task makes to the file between the two is +//! lost, because the write holds the whole file as the read found it. +//! +//! The answer is fixed text and a count, so it is trusted output. + +use runvil_plugin_sdk::sys::RV_MAX_WRITE; +use runvil_plugin_sdk::{ToolError, ToolErrorKind, ToolOutput}; +use serde_json::Value; + +use crate::check::{make_invalid_arguments_error, plural, refuse_blank, refuse_unknown}; +use crate::refusal::write_refusal; +use crate::source::Source; +use crate::spec::Definition; + +/// What a call asks StrReplace for. +#[derive(Debug)] +struct Request<'a> { + /// The path as the model wrote it. + path: &'a str, + /// The text to replace, which is not empty. + old: &'a str, + /// The text that takes its place, which differs from `old`. + new: &'a str, + /// Whether the new text goes in at every occurrence. Otherwise the + /// text must occur exactly once. + all: bool, +} + +/// Runs one `StrReplace` call whose arguments already passed the shared +/// schema check. +/// +/// # Errors +/// Returns an invalid-arguments [`ToolError`] naming the parameter for a +/// bad argument, and a message error for any other failure, worded for a +/// model to read. Every refusal comes before the write, so it leaves the +/// file as it was. +pub(crate) async fn call( + source: &impl Source, + definition: &Definition, + args: &Value, +) -> Result { + let request = parse(definition, args)?; + let tool = definition.wire_name.as_str(); + let path = request.path; + let message = |text: String| ToolError::new(ToolErrorKind::Other, text); + let bytes = crate::read::load(source, tool, path) + .await + .map_err(message)?; + let Ok(text) = String::from_utf8(bytes) else { + return Err(message(format!( + "File is not UTF-8 text, so it cannot be edited: {path}" + ))); + }; + let count = text.matches(request.old).count(); + if count == 0 || (count > 1 && !request.all) { + return Err(message(miscount(path, count, request.all))); + } + let edited = text.replace(request.old, request.new); + if edited.len() > RV_MAX_WRITE { + return Err(message(format!( + "The edit would leave {path} with {} bytes, and one write takes at most \ + {RV_MAX_WRITE} bytes.", + edited.len() + ))); + } + source + .write(path, edited.into_bytes()) + .await + .map_err(|error| message(write_refusal(tool, path, &error)))?; + Ok(ToolOutput::trusted(format!( + "Made {}.", + plural(count, "replacement") + ))) +} + +/// Reads the call's arguments after the shared schema check. +/// +/// The order is fixed: an undeclared key, then a blank path, then an +/// empty `old_string`, then a `new_string` equal to it, so a call that +/// breaks two rules always hears about the same one. +/// +/// # Errors +/// Returns an invalid-arguments [`ToolError`] naming the parameter. +fn parse<'a>(definition: &Definition, args: &'a Value) -> Result, ToolError> { + let tool = definition.wire_name.as_str(); + refuse_unknown(tool, &definition.parameters, args)?; + let text = |name: &str| args.get(name).and_then(Value::as_str).unwrap_or_default(); + let path = text("path"); + refuse_blank(tool, "path", path)?; + let (old, new) = (text("old_string"), text("new_string")); + if old.is_empty() { + return Err(make_invalid_arguments_error( + tool, + "`old_string` is empty. Pass the text to replace.", + )); + } + if old == new { + return Err(make_invalid_arguments_error( + tool, + "`new_string` is the same as `old_string`, so the call would change nothing", + )); + } + let all = args + .get("replace_all") + .and_then(Value::as_bool) + .unwrap_or(false); + Ok(Request { + path, + old, + new, + all, + }) +} + +/// The sentence for a text to replace that occurs `count` times in the +/// file at `path`, where the call needs it once, or at least once when it +/// replaces `all`. +fn miscount(path: &str, count: usize, all: bool) -> String { + let occurs = format!("`old_string` occurs {} in {path}", plural(count, "time")); + if count == 0 { + let needed = if all { "at least once" } else { "exactly once" }; + format!( + "{occurs}, and it must occur {needed}. It is matched exactly, so whitespace and \ + line endings count." + ) + } else { + format!( + "{occurs}, and it must occur exactly once. Add text around it until it names one \ + occurrence, or set `replace_all` to replace every one." + ) + } +} + +#[cfg(test)] +#[path = "replace-tests.rs"] +mod tests; diff --git a/crates/plugin-std/src/spec-tests.rs b/crates/plugin-std/src/spec-tests.rs index f38bf99..cb5a674 100644 --- a/crates/plugin-std/src/spec-tests.rs +++ b/crates/plugin-std/src/spec-tests.rs @@ -170,6 +170,37 @@ fn the_write_description_holds_the_limit_of_one_write_and_states_what_the_tool_d } } +#[test] +fn the_replace_description_holds_the_file_ceiling_and_states_what_the_tool_does() { + let definitions = all(); + let replace = definitions + .iter() + .find(|definition| definition.segment == "replace") + .expect("the replace definition exists"); + let text = &replace.description; + assert!( + text.contains("over 16777216 bytes"), + "the file ceiling is named: {text}" + ); + assert!( + !text.contains("{file_ceiling}"), + "{{file_ceiling}} is filled in: {text}" + ); + for phrase in [ + "matched exactly", + "line endings", + "how many times it occurs", + "replaces every occurrence", + "UTF-8", + "one after another", + ] { + assert!( + text.contains(phrase), + "the description names {phrase}: {text}" + ); + } +} + #[test] fn the_dir_description_holds_the_body_cap_and_no_unfilled_placeholder() { let definitions = all(); diff --git a/crates/plugin-std/src/spec.rs b/crates/plugin-std/src/spec.rs index 73e884c..d29d98a 100644 --- a/crates/plugin-std/src/spec.rs +++ b/crates/plugin-std/src/spec.rs @@ -94,6 +94,9 @@ fn fill(segment: &str, description: &str) -> String { "{write_limit}", &runvil_plugin_sdk::sys::RV_MAX_WRITE.to_string(), ), + "replace" => { + description.replace("{file_ceiling}", &crate::text::MAX_FILE_BYTES.to_string()) + } "dir" => description.replace("{body_cap}", &crate::text::BODY_CAP.to_string()), "grep" => description .replace("{body_cap}", &crate::text::BODY_CAP.to_string()) diff --git a/crates/plugin-std/tests/it/changes.rs b/crates/plugin-std/tests/it/changes.rs index 61aa792..a791587 100644 --- a/crates/plugin-std/tests/it/changes.rs +++ b/crates/plugin-std/tests/it/changes.rs @@ -59,7 +59,7 @@ fn the_tools_that_change_files_say_so_to_the_host_and_no_other_tool_does() { .filter(|tool| tool.changes_files) .map(|tool| tool.name.as_str()) .collect(); - assert_eq!(flagged, ["write"]); + assert_eq!(flagged, ["write", "replace"]); } #[test] @@ -150,3 +150,89 @@ fn a_later_call_of_the_run_reads_what_a_write_left() { .expect("the file reads"); assert_eq!(read.text(), " 1|one\n 2|two\n"); } + +#[test] +fn str_replace_edits_the_one_occurrence_and_answers_the_count_as_trusted_output() { + let (result, files) = change( + Files::new().file("/a.md", "one\ntwo\nthree\n"), + "replace", + &json!({ "path": "/a.md", "old_string": "two", "new_string": "2" }), + ); + let output = result.expect("the file is edited"); + assert_eq!(output.text(), "Made 1 replacement."); + assert!(output.is_trusted()); + assert_eq!(contents(&files, "/a.md"), Ok(b"one\n2\nthree\n".to_vec())); +} + +#[test] +fn str_replace_with_replace_all_edits_every_occurrence() { + let (result, files) = change( + Files::new().file("/a.rs", "let x = x + x;\n"), + "replace", + &json!({ + "path": "/a.rs", "old_string": "x", "new_string": "total", "replace_all": true + }), + ); + let output = result.expect("the file is edited"); + assert_eq!(output.text(), "Made 3 replacements."); + assert_eq!( + contents(&files, "/a.rs"), + Ok(b"let total = total + total;\n".to_vec()) + ); +} + +#[test] +fn str_replace_asks_the_host_for_a_stat_a_read_and_a_write() { + let files = Files::new().file("/a.md", "one two\n"); + let args = json!({ "path": "/a.md", "old_string": "two", "new_string": "2" }); + assert_eq!(steps(files, "replace", &args), 4); +} + +#[test] +fn an_edit_whose_text_does_not_occur_once_fails_with_the_count_before_any_write() { + let before = Files::new().file("/a.rs", "let x = x + x;\n"); + let args = json!({ "path": "/a.rs", "old_string": "x", "new_string": "total" }); + let (result, after) = change(before.clone(), "replace", &args); + let error = result.expect_err("the text occurs three times"); + assert_eq!( + error.message(), + "`old_string` occurs 3 times in /a.rs, and it must occur exactly once. Add text around \ + it until it names one occurrence, or set `replace_all` to replace every one." + ); + assert_eq!(error.kind(), ToolErrorKind::Other); + assert_eq!(after, before); + assert_eq!(steps(before, "replace", &args), 3, "the stat and the read"); +} + +#[test] +fn an_edit_the_policy_denies_fails_with_the_policys_own_reason_and_changes_nothing() { + let reason = "Mode::Ask allows no read of /vault.md"; + let before = Files::new() + .file("/a.md", "kept") + .fails("/vault.md", FileError::new(FileErrorKind::Denied, reason)); + let (result, after) = change( + before.clone(), + "replace", + &json!({ "path": "/vault.md", "old_string": "a", "new_string": "b" }), + ); + let error = result.expect_err("the policy denies the edit"); + assert_eq!(error.message(), reason); + assert_eq!(after, before); +} + +#[test] +fn two_edits_of_one_file_in_a_run_both_apply() { + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded + .new_pack(PACK) + .expect("the Pack instance is made") + .with_files(Files::new().file("/a.md", "one two three\n")); + for (old, new) in [("one", "1"), ("three", "3")] { + let args = json!({ "path": "/a.md", "old_string": old, "new_string": new }); + let edited = pack + .call("replace", &args.to_string()) + .expect("the call follows the contract"); + assert!(edited.is_ok(), "{old}"); + } + assert_eq!(contents(pack.files(), "/a.md"), Ok(b"1 two 3\n".to_vec())); +} diff --git a/crates/plugin-std/tests/it/tools.rs b/crates/plugin-std/tests/it/tools.rs index 3f79e6a..193f48f 100644 --- a/crates/plugin-std/tests/it/tools.rs +++ b/crates/plugin-std/tests/it/tools.rs @@ -73,11 +73,6 @@ fn each_run_gets_an_instance_of_its_own_with_the_same_tools() { #[test] fn every_stub_answers_the_not_implemented_text_naming_itself() { for (name, wire_name, args) in [ - ( - "replace", - "StrReplace", - json!({ "path": "/notes.md", "old_string": "a", "new_string": "b" }), - ), ("rm", "Delete", json!({ "path": "/notes.md" })), ("glob", "Glob", json!({ "glob_pattern": "**/*.md" })), ] { From 8f4d6c1c4fd35eb27ff2d30ca884a2e316d4b1b3 Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Tue, 17 Nov 2026 23:58:31 -0800 Subject: [PATCH 05/13] Implement Delete as a `stat` and then a `remove` A run needs a tool that deletes a file. Delete asks the Host what the path names, refuses a directory with a sentence, and then asks for the removal with one `remove` through `Source`. The `stat` comes first because the removal also takes a directory that has no entries. - `Source` gains `remove`, which is `ToolCall::remove(self, path, false)`, so it never takes a directory with its entries. The `Files` tree performs it, `FakeSource` fails it as it fails a write, and the listing fake of the `dir` tests panics. - `changes_files` flags `rm` too, so the Host runs each call of Delete by itself among the calls of one model reply. - `is_a_directory` in `refusal.rs` holds the sentence for a directory where a file was needed. `refusal`, `check_type` in `read.rs`, and Delete share it. - A file, a link, and a pipe all go to the removal. A link goes as a link, and the answer says that what it leads to stays. - A path where nothing is fails as not found, and a directory fails with or without entries. Each takes two steps, and a delete takes three, and a test holds both numbers. - Delete refuses an undeclared key and then a blank `path`, before the `stat`. - The answer is fixed text, so it is trusted output. - `rm.json` names a directory in its list of failures and gains a `Usage` list, and `EDITS.md` records both. - Glob is the one stub that stays. The docs of `pack.rs`, `README.md`, and the crate docs say so, and `AGENTS.md` loses its line about the stubs. - The trees of the tests hold no link and no pipe that a call can remove. The tests show that such a path gets as far as the removal, and one test holds the answers of `deleted`. - Another task can change what is at the path between the `stat` and the `remove`. No test covers that. Plan: runvil-harness/plan/2026-11-16-1-tool-file-effects.plan.md --- AGENTS.md | 1 - README.md | 8 +- crates/plugin-std/schemas/EDITS.md | 4 +- crates/plugin-std/schemas/rm.json | 2 +- crates/plugin-std/src/dir/tests.rs | 4 + crates/plugin-std/src/fake.rs | 4 + crates/plugin-std/src/lib.rs | 31 ++-- crates/plugin-std/src/pack-tests.rs | 10 +- crates/plugin-std/src/pack.rs | 9 +- crates/plugin-std/src/read.rs | 4 +- crates/plugin-std/src/refusal.rs | 8 +- crates/plugin-std/src/refusal/tests.rs | 17 +- crates/plugin-std/src/rm-tests.rs | 209 +++++++++++++++++++++++++ crates/plugin-std/src/rm.rs | 58 +++++++ crates/plugin-std/src/source.rs | 12 ++ crates/plugin-std/src/spec-tests.rs | 20 +++ crates/plugin-std/tests/it/changes.rs | 95 ++++++++++- crates/plugin-std/tests/it/tools.rs | 17 +- 18 files changed, 470 insertions(+), 43 deletions(-) create mode 100644 crates/plugin-std/src/rm-tests.rs create mode 100644 crates/plugin-std/src/rm.rs diff --git a/AGENTS.md b/AGENTS.md index c8819bc..64c0532 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,7 +28,6 @@ Anything else gets a qualified lowercase name, such as Rust's built-in test harn - The Plugin crate depends on `runvil-plugin-sdk` and outside libraries alone, and writes no `unsafe`. The SDK owns the C boundary. - A tool reaches files only through `Source` (`crates/plugin-std/src/source.rs`), which the call's `ToolCall` implements, so every file operation goes through the Host and the run's policy applies to it. A test runs a tool's own code over the SDK's `testing::Files` tree, or over `FakeSource` (`crates/plugin-std/src/fake.rs`) for what that tree cannot hold. - A tool that changes files says so with `ToolInfo::changes_files`, so the Host runs each of its calls by itself among the calls of one model reply. -- Delete is a stub until it is built on the file method of the SDK that removes a file, which `Source` gains with it. - A tool's description and parameter schema come from its JSON file under `crates/plugin-std/schemas`. `EDITS.md` beside them records every difference from Cursor's definition, and a change to a JSON file changes `EDITS.md` with it. - A tool that does a long job awaits `next_step()` after each bounded slice of work, as Grep does every 32 files or directories, so that no step of its call works for long and the Host can abandon the call between two steps. - A Plugin shares its process with the Host, so nothing here installs process-global state, such as a panic hook (`clippy.toml` bans `std::panic::set_hook`), and nothing starts a thread that outlives the Plugin's unload. What every run shares lives in the Plugin instance and never in a `static`, so an unload frees it. diff --git a/README.md b/README.md index a5eaa1e..715aca2 100644 --- a/README.md +++ b/README.md @@ -11,13 +11,13 @@ The Plugin inserts one Pack, `runvil/std`, which gives a run the standard file t | `std/grep` | `Grep` | Searches the files under a path with a Rust regular expression | | `std/write` | `Write` | Creates a file, or replaces the whole contents of one | | `std/replace` | `StrReplace` | Replaces a text that occurs once in a file, or every occurrence of it | -| `std/rm` | `Delete` | A stub: answers that the tool is not implemented | -| `std/glob` | `Glob` | A stub | +| `std/rm` | `Delete` | Deletes a file or a link, and refuses a directory | +| `std/glob` | `Glob` | A stub: answers that the tool is not implemented | - Each tool's wire name, description, and parameter schema is a JSON file under `crates/plugin-std/schemas`, and `EDITS.md` beside them lists how each differs from Cursor's definition. - Every file operation of a tool goes through the Host, so the run's policy applies to each one. An operation the policy denies fails the call with the policy's own reason. The one exception is an entry below the path a Grep call names, which Grep skips and counts. -- File text and file names come back as untrusted output. The Host marks them before a model reads them. The answer to a change is fixed text and a count, which is trusted output. -- Write and StrReplace say to the Host that they change files. The Host runs a call of such a tool by itself among the calls of one model reply, so two changes of one reply happen in the order the reply lists them. +- File text and file names come back as untrusted output. The Host marks them before a model reads them. The answer to a change holds fixed text and at most a count, so it is trusted output. +- Write, StrReplace, and Delete say to the Host that they change files. The Host runs a call of such a tool by itself among the calls of one model reply, so two changes of one reply happen in the order the reply lists them. - StrReplace edits a file with a read and then a write, so a change that another task makes to the file between the two is lost. - A tool call ends its step at each file operation, and the Host performs the operation before the next step. A search also ends its step every 32 files or directories, so the Host can cancel a call between two steps. diff --git a/crates/plugin-std/schemas/EDITS.md b/crates/plugin-std/schemas/EDITS.md index ee77371..830d4fe 100644 --- a/crates/plugin-std/schemas/EDITS.md +++ b/crates/plugin-std/schemas/EDITS.md @@ -26,7 +26,9 @@ Each file in this directory except `dir.json` is Cursor's definition of the tool ## rm.json -- Verbatim. Cursor's `Delete` description and schema are kept exactly. +- Cursor's `Delete` description and schema, with two additions to the description. +- `The path is a directory` joined the list of failures, because Delete removes a file and refuses a directory. +- Added a `Usage` list that states that a link is deleted as a link, so what it leads to stays, and that the calls in one response that change files run one after another in the order listed. ## glob.json diff --git a/crates/plugin-std/schemas/rm.json b/crates/plugin-std/schemas/rm.json index 5acd238..00063b5 100644 --- a/crates/plugin-std/schemas/rm.json +++ b/crates/plugin-std/schemas/rm.json @@ -1,6 +1,6 @@ { "wire_name": "Delete", - "description": "Deletes a file at the specified path. The operation will fail gracefully if:\n - The file doesn't exist\n - The operation is rejected for security reasons\n - The file cannot be deleted", + "description": "Deletes a file at the specified path. The operation will fail gracefully if:\n - The file doesn't exist\n - The path is a directory\n - The operation is rejected for security reasons\n - The file cannot be deleted\n\nUsage:\n- A link is deleted as a link, and what it leads to stays.\n- The calls in one response that change files run one after another, in the order you list them.", "parameters": { "type": "object", "properties": { diff --git a/crates/plugin-std/src/dir/tests.rs b/crates/plugin-std/src/dir/tests.rs index 605727d..59e1bb2 100644 --- a/crates/plugin-std/src/dir/tests.rs +++ b/crates/plugin-std/src/dir/tests.rs @@ -93,6 +93,10 @@ where async fn write(&self, path: &str, _bytes: Vec) -> Result<(), FileError> { panic!("the walk wrote {path}") } + + async fn remove(&self, path: &str) -> Result<(), FileError> { + panic!("the walk removed {path}") + } } /// Walks `target` over the listings `list` answers with, leaving out diff --git a/crates/plugin-std/src/fake.rs b/crates/plugin-std/src/fake.rs index 1ca0fce..a221d26 100644 --- a/crates/plugin-std/src/fake.rs +++ b/crates/plugin-std/src/fake.rs @@ -189,4 +189,8 @@ impl Source for FakeSource { async fn write(&self, path: &str, _bytes: Vec) -> Result<(), FileError> { Err(self.refused(path)) } + + async fn remove(&self, path: &str) -> Result<(), FileError> { + Err(self.refused(path)) + } } diff --git a/crates/plugin-std/src/lib.rs b/crates/plugin-std/src/lib.rs index 6ba6f3a..6848ebf 100644 --- a/crates/plugin-std/src/lib.rs +++ b/crates/plugin-std/src/lib.rs @@ -80,12 +80,17 @@ //! replace must occur exactly once, unless `replace_all` is set, and a //! failure states how many times it occurs. The edit is a read and then a //! write, so a change that another task makes to the file between the two -//! is lost. Its answer is the count of replacements in fixed -//! text, so it comes back as trusted output. +//! is lost. Its answer is the count of replacements in fixed text, so it +//! comes back as trusted output. //! -//! Delete and Glob are still stubs: a call with arguments that match the -//! schema answers [`NOT_IMPLEMENTED`]. For every tool, a call whose -//! arguments do not match fails with an invalid-arguments +//! Delete is real. It asks what the path names and then asks for its +//! removal. It refuses a directory with a sentence, and it fails on a +//! path where nothing is. A link goes as a link, so what it leads to +//! stays. Its answer is fixed text, so it comes back as trusted output. +//! +//! Glob is still a stub: a call with arguments that match the schema +//! answers [`NOT_IMPLEMENTED`]. For every tool, a call whose arguments do +//! not match fails with an invalid-arguments //! [`ToolError`](runvil_plugin_sdk::ToolError) naming the parameter. //! //! # Where the file access goes @@ -101,10 +106,10 @@ //! fails the same way on a directory that is there and cannot be listed, //! and Grep skips the entry and counts it. //! -//! A tool that changes files says so to the Host, as Write and StrReplace -//! do. The Host runs a call of such a tool by itself among the calls of -//! one model reply, after the calls the reply lists before it, so two -//! changes of one reply happen in the order the reply lists them. +//! A tool that changes files says so to the Host, as Write, StrReplace, +//! and Delete do. The Host runs a call of such a tool by itself among the +//! calls of one model reply, after the calls the reply lists before it, +//! so two changes of one reply happen in the order the reply lists them. //! //! Shell is deliberately absent. An in-process shell over the same //! filesystem is a separate Pack, so a run that wants one declares it. @@ -133,10 +138,9 @@ //! arguments, so a model can tell a bad call from a missing //! implementation. //! - A key the schema does not declare is refused by name, with the -//! parameters listed, by the five real tools, Read, ListDir, Grep, -//! Write, and StrReplace. The stubs let it through. Grep alone accepts -//! `-n` when it is `true`, because Cursor's definition once declared -//! it. +//! parameters listed, by every real tool. Glob, the one stub, lets it +//! through. Grep alone accepts `-n` when it is `true`, because Cursor's +//! definition once declared it. //! - A tool that changes files is flagged with //! [`ToolInfo::changes_files`](runvil_plugin_sdk::ToolInfo::changes_files), //! and a test holds the flags in place. @@ -152,6 +156,7 @@ mod pack; mod read; mod refusal; mod replace; +mod rm; mod source; mod spec; mod text; diff --git a/crates/plugin-std/src/pack-tests.rs b/crates/plugin-std/src/pack-tests.rs index 286147e..8d1605a 100644 --- a/crates/plugin-std/src/pack-tests.rs +++ b/crates/plugin-std/src/pack-tests.rs @@ -147,8 +147,12 @@ fn a_call_goes_to_the_tool_its_name_picks() { .expect("the file is edited"); assert_eq!(replace.text(), "Made 1 replacement."); assert_eq!(files.read("/p/c.md", 0, u64::MAX), Ok(b"y".to_vec())); - let stub = ran("rm", r#"{"path":"/p/c.md"}"#, &files).expect("a stub answers its text"); - assert_eq!(stub.text(), NOT_IMPLEMENTED.replace("", "Delete")); + let rm = ran("rm", r#"{"path":"/p/c.md"}"#, &files).expect("the file is deleted"); + assert_eq!(rm.text(), "Deleted the file."); + assert!(files.stat("/p/c.md").is_err()); + let stub = + ran("glob", r#"{"glob_pattern":"*.md"}"#, &files).expect("the stub answers its text"); + assert_eq!(stub.text(), NOT_IMPLEMENTED.replace("", "Glob")); assert!(stub.is_trusted()); } @@ -161,5 +165,5 @@ fn an_instance_flags_the_tools_that_change_files_and_no_other() { .filter(|tool| tool.changes_files) .map(|tool| tool.name.as_str()) .collect(); - assert_eq!(flagged, ["write", "replace"]); + assert_eq!(flagged, ["write", "replace", "rm"]); } diff --git a/crates/plugin-std/src/pack.rs b/crates/plugin-std/src/pack.rs index f927eb8..af35275 100644 --- a/crates/plugin-std/src/pack.rs +++ b/crates/plugin-std/src/pack.rs @@ -1,6 +1,6 @@ //! The `std` Pack: its [`INFO`], [`StdPack`], one run's instance, which //! lists the Pack's tools and hands each call to its tool's module, and -//! the stub that Delete and Glob still answer with in this build. +//! the stub that Glob still answers with in this build. use std::sync::Arc; @@ -14,8 +14,8 @@ use crate::source::Source; use crate::spec::Definition; /// What a call to a tool that is still a stub answers in this build, when -/// its arguments match the schema. Delete and Glob are the stubs, and -/// every other tool is real and never answers this. +/// its arguments match the schema. Glob is the one stub, and every other +/// tool is real and never answers this. /// /// The text says the implementation is missing rather than that the call /// was wrong, because a model that reads it should stop calling the tool. @@ -71,7 +71,7 @@ impl StdPack { /// calls of one model reply, after the calls the reply lists before it, /// so two changes of one reply happen in the order the reply lists them. fn changes_files(segment: &str) -> bool { - matches!(segment, "write" | "replace") + matches!(segment, "write" | "replace" | "rm") } /// The stub text for the tool the model calls `wire_name`. @@ -113,6 +113,7 @@ async fn run( "grep" => crate::grep::call(source, definition, &args).await, "write" => crate::write::call(source, definition, &args).await, "replace" => crate::replace::call(source, definition, &args).await, + "rm" => crate::rm::call(source, definition, &args).await, _ => Ok(ToolOutput::trusted(stub(&definition.wire_name))), } } diff --git a/crates/plugin-std/src/read.rs b/crates/plugin-std/src/read.rs index 572b517..4e5d025 100644 --- a/crates/plugin-std/src/read.rs +++ b/crates/plugin-std/src/read.rs @@ -17,7 +17,7 @@ use runvil_plugin_sdk::{FileError, FileType, ToolError, ToolErrorKind, ToolOutpu use serde_json::Value; use crate::check::plural; -use crate::refusal::{neither_file_nor_directory, refusal}; +use crate::refusal::{is_a_directory, neither_file_nor_directory, refusal}; use crate::source::Source; use crate::spec::Definition; use crate::text::{MAX_FILE_BYTES, decode, sniff_binary, split_lines}; @@ -113,7 +113,7 @@ pub(crate) async fn load(source: &impl Source, tool: &str, path: &str) -> Result fn check_type(path: &str, file_type: FileType) -> Result<(), String> { match file_type { FileType::File | FileType::Symlink => Ok(()), - FileType::Directory => Err(format!("Path is a directory, not a file: {path}")), + FileType::Directory => Err(is_a_directory(path)), // A pipe, a socket, or a device, and any kind added later: none // of them holds text, and a read of one can block for good. _ => Err(neither_file_nor_directory(path)), diff --git a/crates/plugin-std/src/refusal.rs b/crates/plugin-std/src/refusal.rs index 926097c..0d0b5df 100644 --- a/crates/plugin-std/src/refusal.rs +++ b/crates/plugin-std/src/refusal.rs @@ -19,7 +19,7 @@ use runvil_plugin_sdk::{FileError, FileErrorKind}; pub(crate) fn refusal(tool: &str, path: &str, error: &FileError) -> String { match error.kind() { FileErrorKind::NotFound => format!("File not found: {path}"), - FileErrorKind::IsADirectory => format!("Path is a directory, not a file: {path}"), + FileErrorKind::IsADirectory => is_a_directory(path), FileErrorKind::NotADirectory => not_a_directory(path), FileErrorKind::Conflict => format!( "{path} was changed, or is being changed, by another call in this round, so it \ @@ -54,6 +54,12 @@ pub(crate) fn missing_root(path: &str) -> String { format!("Path does not exist: {path}") } +/// The sentence for a path that names a directory where a file was +/// needed. +pub(crate) fn is_a_directory(path: &str) -> String { + format!("Path is a directory, not a file: {path}") +} + /// The sentence for a path that names something other than a directory /// where a directory was needed. pub(crate) fn not_a_directory(path: &str) -> String { diff --git a/crates/plugin-std/src/refusal/tests.rs b/crates/plugin-std/src/refusal/tests.rs index f5b46af..fef173c 100644 --- a/crates/plugin-std/src/refusal/tests.rs +++ b/crates/plugin-std/src/refusal/tests.rs @@ -3,7 +3,10 @@ use runvil_plugin_sdk::{FileError, FileErrorKind}; -use super::{missing_root, neither_file_nor_directory, not_a_directory, refusal, write_refusal}; +use super::{ + is_a_directory, missing_root, neither_file_nor_directory, not_a_directory, refusal, + write_refusal, +}; /// The path the model wrote, and the resolved path every error text /// below names, which differs so a test can tell which one a sentence @@ -189,6 +192,18 @@ fn a_missing_root_is_worded_apart_from_a_missing_file() { assert_eq!(missing_root(WRITTEN), "Path does not exist: notes/a.md"); } +#[test] +fn the_is_a_directory_sentence_is_the_one_the_refusal_gives() { + assert_eq!( + say(&error(FileErrorKind::IsADirectory)), + is_a_directory(WRITTEN) + ); + assert_eq!( + is_a_directory("/a/b"), + "Path is a directory, not a file: /a/b" + ); +} + #[test] fn the_not_a_directory_sentence_is_the_one_the_refusal_gives() { assert_eq!( diff --git a/crates/plugin-std/src/rm-tests.rs b/crates/plugin-std/src/rm-tests.rs new file mode 100644 index 0000000..6f78a38 --- /dev/null +++ b/crates/plugin-std/src/rm-tests.rs @@ -0,0 +1,209 @@ +//! Unit tests for the `Delete` tool: what a call removes, what it +//! refuses, what it answers, and how a failure of the Host reads. + +use runvil_plugin_sdk::testing::Files; +use runvil_plugin_sdk::{FileError, FileErrorKind, FileType, ToolError, ToolErrorKind, ToolOutput}; +use serde_json::{Value, json}; + +use super::deleted; +use crate::fake::{FakeSource, Node, block_on}; +use crate::source::Source; +use crate::spec::{self, Definition}; + +/// The `rm` definition the Pack builds the tool from. +fn definition() -> &'static Definition { + spec::all() + .iter() + .find(|definition| definition.segment == "rm") + .expect("the rm definition exists") +} + +/// Calls Delete over `files` with `args` as the Pack does: the schema +/// check first, then the tool. +fn delete(files: &impl Source, args: &Value) -> Result { + let definition = definition(); + crate::check::check(&definition.wire_name, &definition.parameters, args)?; + block_on(super::call(files, definition, args)) +} + +/// Deletes what is at `path` in `files`. +fn delete_at(files: &impl Source, path: &str) -> Result { + delete(files, &json!({ "path": path })) +} + +/// The text of a successful delete, which must be trusted output. +fn text_of(result: Result) -> String { + let output = result.expect("the delete succeeds"); + assert!(output.is_trusted(), "{}", output.text()); + output.text().to_owned() +} + +/// The message of a failed delete, which must not be an +/// invalid-arguments failure. +fn failure_of(result: Result) -> String { + match result { + Ok(output) => panic!("the delete fails, but it answered {:?}", output.text()), + Err(error) => { + assert_eq!(error.kind(), ToolErrorKind::Other, "{error}"); + error.to_string() + } + } +} + +/// The message of a delete whose arguments are refused. +fn refused(result: Result) -> String { + match result { + Ok(output) => panic!("the call is refused, but it answered {:?}", output.text()), + Err(error) => { + assert_eq!(error.kind(), ToolErrorKind::InvalidArguments, "{error}"); + error.to_string() + } + } +} + +#[test] +fn a_delete_removes_the_file_and_leaves_what_is_beside_it() { + let files = Files::new() + .file("/notes/a.md", "one") + .file("/notes/b.md", "two"); + assert_eq!( + text_of(delete_at(&files, "/notes/a.md")), + "Deleted the file." + ); + assert_eq!(files, Files::new().file("/notes/b.md", "two")); +} + +#[test] +fn the_directory_that_held_the_file_stays() { + let files = Files::new().file("/notes/a.md", "one"); + assert!(delete_at(&files, "/notes/a.md").is_ok()); + assert_eq!(files, Files::new().dir("/notes")); +} + +#[test] +fn a_path_without_a_leading_slash_is_deleted_from_the_root() { + let files = Files::new().file("/notes/a.md", "one"); + assert!(delete_at(&files, "notes/a.md").is_ok()); + assert_eq!(files, Files::new().dir("/notes")); +} + +#[test] +fn a_missing_path_fails_with_the_not_found_text() { + let files = Files::new().file("/notes/a.md", "one"); + let before = files.clone(); + assert_eq!( + failure_of(delete_at(&files, "/nope.md")), + "File not found: /nope.md" + ); + assert_eq!( + failure_of(delete_at(&files, "notes/gone.md")), + "File not found: notes/gone.md" + ); + assert_eq!(files, before); +} + +#[test] +fn a_directory_is_refused_with_a_sentence_and_stays() { + let files = Files::new().file("/full/a.md", "one").dir("/empty"); + let before = files.clone(); + for directory in ["/full", "/empty", "empty", "/"] { + assert_eq!( + failure_of(delete_at(&files, directory)), + format!("Path is a directory, not a file: {directory}") + ); + } + assert_eq!(files, before); +} + +#[test] +fn a_file_a_link_and_a_pipe_all_get_as_far_as_the_removal() { + // The fake takes no change, so this text shows that the call passed + // the stat and asked for the removal. + let source = FakeSource::default() + .file("/file", "x") + .with("/filelink", Node::LinkToFile(b"x".to_vec())) + .with("/dirlink", Node::Link) + .with("/pipe", Node::Pipe); + for path in ["/file", "/filelink", "/dirlink", "/pipe"] { + assert_eq!( + failure_of(delete_at(&source, path)), + format!("the fake tree takes no change: {path}") + ); + } +} + +#[test] +fn the_answer_says_that_what_a_link_leads_to_stays() { + assert_eq!(deleted(FileType::File), "Deleted the file."); + assert_eq!(deleted(FileType::Other), "Deleted the file."); + assert_eq!( + deleted(FileType::Symlink), + "Deleted the link. What it leads to stays." + ); +} + +#[test] +fn a_stat_the_policy_denies_fails_with_the_policys_own_reason_and_removes_nothing() { + let reason = "Mode::Ask allows no change of /vault.md"; + let files = Files::new().fails("/vault.md", FileError::new(FileErrorKind::Denied, reason)); + let before = files.clone(); + assert_eq!(failure_of(delete_at(&files, "/vault.md")), reason); + assert_eq!(files, before); +} + +#[test] +fn a_removal_the_host_fails_after_the_stat_succeeded_is_worded_by_its_kind() { + let guarded = |kind, text: &str| Node::Guarded(b"x".to_vec(), FileError::new(kind, text)); + let reason = "Mode::Ask allows no change of /ask.md"; + let source = FakeSource::default() + .with("/ask.md", guarded(FileErrorKind::Denied, reason)) + .with( + "/disk.md", + guarded(FileErrorKind::Io, "permission denied: access denied"), + ) + .with( + "/gone.md", + guarded(FileErrorKind::NotFound, "not found: /gone.md"), + ); + assert_eq!(failure_of(delete_at(&source, "/ask.md")), reason); + assert_eq!( + failure_of(delete_at(&source, "/disk.md")), + "I/O failure on /disk.md: permission denied: access denied" + ); + assert_eq!( + failure_of(delete_at(&source, "/gone.md")), + "File not found: /gone.md" + ); +} + +#[test] +fn a_missing_path_argument_or_one_of_the_wrong_type_names_the_parameter() { + let files = Files::new(); + assert_eq!( + refused(delete(&files, &json!({}))), + "std_Delete: `path` is required, and the call left it out" + ); + assert_eq!( + refused(delete(&files, &json!({ "path": ["/a.md"] }))), + "std_Delete: `path` must be a JSON string, and the call passed [\"/a.md\"]" + ); +} + +#[test] +fn an_undeclared_key_is_refused_before_a_blank_path() { + let files = Files::new().file("/a.md", "one"); + let before = files.clone(); + assert_eq!( + refused(delete(&files, &json!({ "path": " ", "recursive": true }))), + "std_Delete: `recursive` is not a parameter of this tool. The parameters are `path`." + ); + for blank in ["", " ", "\t\n"] { + assert_eq!( + refused(delete_at(&files, blank)), + format!( + "std_Delete: `path` is empty or only whitespace, and the call passed \"{blank}\"" + ) + ); + } + assert_eq!(files, before); +} diff --git a/crates/plugin-std/src/rm.rs b/crates/plugin-std/src/rm.rs new file mode 100644 index 0000000..5d0aff5 --- /dev/null +++ b/crates/plugin-std/src/rm.rs @@ -0,0 +1,58 @@ +//! The `Delete` tool: removes one file. +//! +//! Delete asks what the path names and then asks for its removal, both +//! through the call's [`Source`], so the run's policy applies. The stat +//! comes first because the removal the Host offers also takes a +//! directory with no entries, and Delete removes no directory: it +//! refuses one with a sentence. A link goes as a link, so what it leads +//! to stays. The answer is fixed text, so it is trusted output. + +use runvil_plugin_sdk::{FileError, FileType, ToolError, ToolErrorKind, ToolOutput}; +use serde_json::Value; + +use crate::check::{refuse_blank, refuse_unknown}; +use crate::refusal::{is_a_directory, refusal}; +use crate::source::Source; +use crate::spec::Definition; + +/// Runs one `Delete` call whose arguments already passed the shared +/// schema check. +/// +/// # Errors +/// Returns an invalid-arguments [`ToolError`] naming the parameter for a +/// bad argument, and a message error for any other failure, worded for a +/// model to read: nothing is at the path, the path names a directory, or +/// the Host fails the stat or the removal. +pub(crate) async fn call( + source: &impl Source, + definition: &Definition, + args: &Value, +) -> Result { + let tool = definition.wire_name.as_str(); + refuse_unknown(tool, &definition.parameters, args)?; + let path = args.get("path").and_then(Value::as_str).unwrap_or_default(); + refuse_blank(tool, "path", path)?; + let message = |text: String| ToolError::new(ToolErrorKind::Other, text); + let failed = |error: FileError| message(refusal(tool, path, &error)); + let stat = source.stat(path).await.map_err(failed)?; + if stat.file_type == FileType::Directory { + return Err(message(is_a_directory(path))); + } + source.remove(path).await.map_err(failed)?; + Ok(ToolOutput::trusted(deleted(stat.file_type))) +} + +/// What a call answers after it removed something of `file_type`. A link +/// goes as a link, so the answer says that what it leads to stays. A +/// pipe, a socket, or a device goes as a file does. +fn deleted(file_type: FileType) -> &'static str { + if file_type == FileType::Symlink { + "Deleted the link. What it leads to stays." + } else { + "Deleted the file." + } +} + +#[cfg(test)] +#[path = "rm-tests.rs"] +mod tests; diff --git a/crates/plugin-std/src/source.rs b/crates/plugin-std/src/source.rs index 9a927b9..f120bff 100644 --- a/crates/plugin-std/src/source.rs +++ b/crates/plugin-std/src/source.rs @@ -31,6 +31,10 @@ pub(crate) trait Source { /// file is made when it is absent, with each directory on the way to /// it. async fn write(&self, path: &str, bytes: Vec) -> Result<(), FileError>; + + /// Removes what is at `path`: a file, a link, or a directory with no + /// entries. A link goes as a link, and what it leads to stays. + async fn remove(&self, path: &str) -> Result<(), FileError>; } impl Source for ToolCall<'_> { @@ -53,6 +57,10 @@ impl Source for ToolCall<'_> { async fn write(&self, path: &str, bytes: Vec) -> Result<(), FileError> { ToolCall::write(self, path, bytes).await } + + async fn remove(&self, path: &str) -> Result<(), FileError> { + ToolCall::remove(self, path, false).await + } } #[cfg(test)] @@ -80,4 +88,8 @@ impl Source for runvil_plugin_sdk::testing::Files { async fn write(&self, path: &str, bytes: Vec) -> Result<(), FileError> { runvil_plugin_sdk::testing::Files::write(self, path, bytes) } + + async fn remove(&self, path: &str) -> Result<(), FileError> { + runvil_plugin_sdk::testing::Files::remove(self, path, false) + } } diff --git a/crates/plugin-std/src/spec-tests.rs b/crates/plugin-std/src/spec-tests.rs index cb5a674..fae2463 100644 --- a/crates/plugin-std/src/spec-tests.rs +++ b/crates/plugin-std/src/spec-tests.rs @@ -201,6 +201,26 @@ fn the_replace_description_holds_the_file_ceiling_and_states_what_the_tool_does( } } +#[test] +fn the_rm_description_says_that_a_directory_fails_and_that_a_link_goes_as_a_link() { + let definitions = all(); + let rm = definitions + .iter() + .find(|definition| definition.segment == "rm") + .expect("the rm definition exists"); + let text = &rm.description; + for phrase in [ + "The path is a directory", + "A link is deleted as a link", + "one after another", + ] { + assert!( + text.contains(phrase), + "the description names {phrase}: {text}" + ); + } +} + #[test] fn the_dir_description_holds_the_body_cap_and_no_unfilled_placeholder() { let definitions = all(); diff --git a/crates/plugin-std/tests/it/changes.rs b/crates/plugin-std/tests/it/changes.rs index a791587..55501d1 100644 --- a/crates/plugin-std/tests/it/changes.rs +++ b/crates/plugin-std/tests/it/changes.rs @@ -59,7 +59,7 @@ fn the_tools_that_change_files_say_so_to_the_host_and_no_other_tool_does() { .filter(|tool| tool.changes_files) .map(|tool| tool.name.as_str()) .collect(); - assert_eq!(flagged, ["write", "replace"]); + assert_eq!(flagged, ["write", "replace", "rm"]); } #[test] @@ -236,3 +236,96 @@ fn two_edits_of_one_file_in_a_run_both_apply() { } assert_eq!(contents(pack.files(), "/a.md"), Ok(b"1 two 3\n".to_vec())); } + +#[test] +fn delete_removes_a_file_and_answers_fixed_text_as_trusted_output() { + let (result, files) = change( + Files::new() + .file("/notes/a.md", "one") + .file("/notes/b.md", "two"), + "rm", + &json!({ "path": "/notes/a.md" }), + ); + let output = result.expect("the file is deleted"); + assert_eq!(output.text(), "Deleted the file."); + assert!(output.is_trusted()); + assert_eq!(files, Files::new().file("/notes/b.md", "two")); +} + +#[test] +fn delete_asks_the_host_for_a_stat_and_then_a_removal() { + let files = Files::new().file("/a.md", "one"); + assert_eq!(steps(files, "rm", &json!({ "path": "/a.md" })), 3); +} + +#[test] +fn delete_refuses_a_directory_after_its_stat_and_removes_nothing() { + let before = Files::new().file("/notes/a.md", "one").dir("/empty"); + for directory in ["/notes", "/empty"] { + let args = json!({ "path": directory }); + let (result, after) = change(before.clone(), "rm", &args); + let error = result.expect_err("the path names a directory"); + assert_eq!( + error.message(), + format!("Path is a directory, not a file: {directory}") + ); + assert_eq!(error.kind(), ToolErrorKind::Other); + assert_eq!(after, before); + assert_eq!(steps(before.clone(), "rm", &args), 2, "the stat alone"); + } +} + +#[test] +fn delete_of_a_missing_path_fails_with_the_not_found_text() { + let args = json!({ "path": "/nope.md" }); + let (result, files) = change(Files::new(), "rm", &args); + let error = result.expect_err("nothing is at the path"); + assert_eq!(error.message(), "File not found: /nope.md"); + assert_eq!(files, Files::new()); + assert_eq!(steps(Files::new(), "rm", &args), 2, "the stat alone"); +} + +#[test] +fn a_delete_the_policy_denies_fails_with_the_policys_own_reason_and_changes_nothing() { + let reason = "Mode::Ask allows no change of /vault.md"; + let before = Files::new() + .file("/a.md", "kept") + .fails("/vault.md", FileError::new(FileErrorKind::Denied, reason)); + let (result, after) = change(before.clone(), "rm", &json!({ "path": "/vault.md" })); + let error = result.expect_err("the policy denies the delete"); + assert_eq!(error.message(), reason); + assert_eq!(after, before); +} + +#[test] +fn the_calls_of_one_run_write_edit_read_and_delete_one_file_in_turn() { + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded.new_pack(PACK).expect("the Pack instance is made"); + let call = |name: &str, args: Value| { + pack.call(name, &args.to_string()) + .expect("the call follows the contract") + }; + let answer = |name: &str, args: Value| { + let output = call(name, args).unwrap_or_else(|error| panic!("{name} fails: {error}")); + output.text().to_owned() + }; + let path = "/notes/a.md"; + assert_eq!( + answer("write", json!({ "path": path, "contents": "one\ntwo\n" })), + "Wrote 8 bytes." + ); + assert_eq!( + answer( + "replace", + json!({ "path": path, "old_string": "two", "new_string": "2" }) + ), + "Made 1 replacement." + ); + assert_eq!( + answer("read", json!({ "path": path })), + " 1|one\n 2|2\n" + ); + assert_eq!(answer("rm", json!({ "path": path })), "Deleted the file."); + let gone = call("read", json!({ "path": path })).expect_err("the file is gone"); + assert_eq!(gone.message(), "File not found: /notes/a.md"); +} diff --git a/crates/plugin-std/tests/it/tools.rs b/crates/plugin-std/tests/it/tools.rs index 193f48f..5443426 100644 --- a/crates/plugin-std/tests/it/tools.rs +++ b/crates/plugin-std/tests/it/tools.rs @@ -71,16 +71,11 @@ fn each_run_gets_an_instance_of_its_own_with_the_same_tools() { } #[test] -fn every_stub_answers_the_not_implemented_text_naming_itself() { - for (name, wire_name, args) in [ - ("rm", "Delete", json!({ "path": "/notes.md" })), - ("glob", "Glob", json!({ "glob_pattern": "**/*.md" })), - ] { - let output = call(name, &args).expect("a matching call succeeds"); - let expected = NOT_IMPLEMENTED.replace("", wire_name); - assert_eq!(output.text(), expected, "{name}"); - assert!(output.is_trusted(), "{name}"); - } +fn glob_the_one_stub_answers_the_not_implemented_text_naming_itself() { + let output = + call("glob", &json!({ "glob_pattern": "**/*.md" })).expect("a matching call succeeds"); + assert_eq!(output.text(), NOT_IMPLEMENTED.replace("", "Glob")); + assert!(output.is_trusted()); } #[test] @@ -259,7 +254,7 @@ fn grep_of_a_missing_path_fails_with_the_does_not_exist_text() { } #[test] -fn grep_refuses_an_undeclared_key_by_name_while_the_stubs_let_it_through() { +fn grep_refuses_an_undeclared_key_by_name_while_the_stub_lets_it_through() { let error = call("grep", &json!({ "pattern": "x", "context": 3 })) .expect_err("context is not a parameter"); assert_eq!(error.kind(), ToolErrorKind::InvalidArguments); From 17cbb216ef249af424596d48f841af90989bbc1f Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Wed, 18 Nov 2026 07:32:52 -0800 Subject: [PATCH 06/13] Refuse an oversized StrReplace edit before it is built StrReplace built the whole edited text and then compared its length with the most that one write takes. A call with `replace_all` could make that text many times longer than the file, so the Plugin could ask for more memory than its Host has. The length now follows from the count of matches, in `edited_len`, and the refusal comes before `text.replace`. - `edited_len` uses saturating arithmetic, so a length past the range of `usize` is its largest value, and the call refuses it like any other length over the limit. - The sentence of the refusal and the limit stay the same. The sentence holds the number of bytes that the built text had. - A new test asks for an edit of 16 TiB, which no call could answer if it built the text first. A second test compares `edited_len` with the length that `replace` gives, for four edits. - Nothing compares the computed length with the built text when a call runs. Plan: runvil-harness/plan/2026-11-16-1-tool-file-effects.plan.md --- crates/plugin-std/src/replace-tests.rs | 45 ++++++++++++++++++++++++++ crates/plugin-std/src/replace.rs | 28 ++++++++++++---- 2 files changed, 67 insertions(+), 6 deletions(-) diff --git a/crates/plugin-std/src/replace-tests.rs b/crates/plugin-std/src/replace-tests.rs index cb6864a..545b9fc 100644 --- a/crates/plugin-std/src/replace-tests.rs +++ b/crates/plugin-std/src/replace-tests.rs @@ -8,6 +8,7 @@ use runvil_plugin_sdk::{ }; use serde_json::{Value, json}; +use super::edited_len; use crate::fake::{FakeSource, Node, block_on}; use crate::source::Source; use crate::spec::{self, Definition}; @@ -306,6 +307,50 @@ fn an_edit_that_grows_the_file_past_one_write_is_refused_and_one_at_the_limit_is ); } +#[test] +fn an_edit_far_past_one_write_is_refused_from_the_count_before_it_is_built() { + // Each of the 1 MiB of matches would become 16 MiB, which is 16 TiB + // in all. No machine holds a text of that length, so a call that + // built the edited text before it checked the length could not + // answer. + let files = Files::new().file("/wide.txt", "a".repeat(1_048_576)); + let wide = 1_048_576_usize.saturating_mul(16_777_216); + assert_eq!( + failure_of(edit_all(&files, "/wide.txt", "a", &"b".repeat(16_777_216))), + format!( + "The edit would leave /wide.txt with {wide} bytes, and one write takes at most \ + 16777216 bytes." + ) + ); + assert_eq!( + files.read("/wide.txt", 0, 4), + Ok(b"aaaa".to_vec()), + "the file stays as it was" + ); +} + +#[test] +fn the_length_of_an_edit_follows_from_the_count_of_its_matches() { + for (text, old, new) in [ + ("x x x", "x", "yy"), + ("x x x", "x ", ""), + ("aaa", "aa", "b"), + ("caf\u{e9} caf\u{e9}", "\u{e9}", "e"), + ] { + let count = text.matches(old).count(); + assert_eq!( + edited_len(text.len(), count, old.len(), new.len()), + text.replace(old, new).len(), + "{text:?}: {old:?} to {new:?}" + ); + } + assert_eq!( + edited_len(usize::MAX, usize::MAX, 1, usize::MAX), + usize::MAX, + "a length past the range of usize is its largest value" + ); +} + #[test] fn a_read_the_policy_denies_fails_with_the_policys_own_reason() { let reason = "Mode::Plan allows only markdown paths, and /secret.rs is not one"; diff --git a/crates/plugin-std/src/replace.rs b/crates/plugin-std/src/replace.rs index f59e1fe..549879c 100644 --- a/crates/plugin-std/src/replace.rs +++ b/crates/plugin-std/src/replace.rs @@ -6,7 +6,9 @@ //! must hold UTF-8. Nothing is decoded, and nothing outside the matches //! changes, so a byte order mark and the line endings stay as they are. //! The text to replace must occur exactly once, unless `replace_all` is -//! set, and a failure states how many times it occurs. +//! set, and a failure states how many times it occurs. An edit that would +//! leave the file longer than one write takes is refused from the count +//! of matches, before the edited text is built. //! //! The edit is a read and then a write, each a request to the Host of its //! own. A change that another task makes to the file between the two is @@ -66,14 +68,18 @@ pub(crate) async fn call( if count == 0 || (count > 1 && !request.all) { return Err(message(miscount(path, count, request.all))); } - let edited = text.replace(request.old, request.new); - if edited.len() > RV_MAX_WRITE { + // The length of the edited text follows from the count, so an edit + // that is too long is refused before any of it is built. A call with + // `replace_all` could otherwise ask for far more memory than the + // file and its arguments hold. + let len = edited_len(text.len(), count, request.old.len(), request.new.len()); + if len > RV_MAX_WRITE { return Err(message(format!( - "The edit would leave {path} with {} bytes, and one write takes at most \ - {RV_MAX_WRITE} bytes.", - edited.len() + "The edit would leave {path} with {len} bytes, and one write takes at most \ + {RV_MAX_WRITE} bytes." ))); } + let edited = text.replace(request.old, request.new); source .write(path, edited.into_bytes()) .await @@ -123,6 +129,16 @@ fn parse<'a>(definition: &Definition, args: &'a Value) -> Result, To }) } +/// The length in bytes of a text of `len` bytes once each of its `count` +/// matches, of `old` bytes, has given way to `new` bytes. The matches do +/// not overlap, so together they take up no more than `len` bytes. A +/// length past the range of `usize` is its largest value, which is over +/// every limit. +fn edited_len(len: usize, count: usize, old: usize, new: usize) -> usize { + len.saturating_sub(count.saturating_mul(old)) + .saturating_add(count.saturating_mul(new)) +} + /// The sentence for a text to replace that occurs `count` times in the /// file at `path`, where the call needs it once, or at least once when it /// replaces `all`. From c29051969194463d91daa6950be2b5fe365a2d22 Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Wed, 18 Nov 2026 07:36:33 -0800 Subject: [PATCH 07/13] Bound each read of Grep to one byte past its size limit Grep took the size of a file from its listing and then asked for the whole file, so a file that grew after the listing was held whole and searched, whatever its length. Each read now goes through `read_prefix` and asks for one byte past `max_file_size`, and a file that is longer is skipped as `Reason::OverSize`. `Source` loses `read`, its one method with no bound, because no tool calls it. - `read` of `Search` holds the rule, and the file that a call names and the files that a walk meets both use it. A size over the limit that a stat or a listing gives still skips the file with no read. - With the default limit of 16777216 bytes, the request for a file names 16777217 bytes, where `ToolCall::read` asked for the whole file. - A file that is longer than its listing said is counted with the files over the size limit, and the skip line names it. A file exactly at the limit is searched. - Two tests give `FakeSource` a `Node::Sized` whose bytes are longer than its listed size, one for a walk and one for a named file. A third makes a file longer through the fake Host, between the step of the listing and the step of the read. - `FakeSource` keeps the bytes of a node in `bytes_at`, where its `read` was. - No test sees the `len` of a request, because the fake Host does not show it. Plan: runvil-harness/plan/2026-11-16-1-tool-file-effects.plan.md --- crates/plugin-std/src/dir/tests.rs | 4 -- crates/plugin-std/src/fake.rs | 38 +++++++++-------- crates/plugin-std/src/grep.rs | 15 +++---- crates/plugin-std/src/grep/find.rs | 43 ++++++++++++------- crates/plugin-std/src/grep/found.rs | 6 ++- crates/plugin-std/src/grep/tests/skips.rs | 51 +++++++++++++++++++++++ crates/plugin-std/src/source.rs | 17 ++------ crates/plugin-std/tests/it/grep.rs | 31 ++++++++++++++ 8 files changed, 145 insertions(+), 60 deletions(-) diff --git a/crates/plugin-std/src/dir/tests.rs b/crates/plugin-std/src/dir/tests.rs index 59e1bb2..1bfcfd1 100644 --- a/crates/plugin-std/src/dir/tests.rs +++ b/crates/plugin-std/src/dir/tests.rs @@ -82,10 +82,6 @@ where (self.0)(path) } - async fn read(&self, path: &str) -> Result, FileError> { - panic!("the walk read {path}") - } - async fn read_prefix(&self, path: &str, _len: u64) -> Result, FileError> { panic!("the walk read {path}") } diff --git a/crates/plugin-std/src/fake.rs b/crates/plugin-std/src/fake.rs index a221d26..5bc3dd4 100644 --- a/crates/plugin-std/src/fake.rs +++ b/crates/plugin-std/src/fake.rs @@ -102,6 +102,25 @@ impl FakeSource { FileError::new(FileErrorKind::NotFound, format!("not found: {path}")) } + /// Every byte of the file at `path`, as a read of the whole file + /// would give them. + fn bytes_at(&self, path: &str) -> Result, FileError> { + match self.nodes.get(path) { + Some( + Node::File(bytes) + | Node::Sized(_, bytes) + | Node::LinkToFile(bytes) + | Node::Guarded(bytes, _), + ) => Ok(bytes.clone()), + Some(Node::ReadFails(error) | Node::LinkFails(error)) => Err(error.clone()), + Some(Node::Link | Node::ListFails(_)) => Err(FileError::new( + FileErrorKind::IsADirectory, + format!("is a directory: {path}"), + )), + Some(Node::Pipe) | None => Err(Self::missing(path)), + } + } + /// The error of a change to `path`, which the tree never takes: the /// error of a [`Node::Guarded`], and a fixed one for any other path. fn refused(&self, path: &str) -> FileError { @@ -163,25 +182,8 @@ impl Source for FakeSource { .collect()) } - async fn read(&self, path: &str) -> Result, FileError> { - match self.nodes.get(path) { - Some( - Node::File(bytes) - | Node::Sized(_, bytes) - | Node::LinkToFile(bytes) - | Node::Guarded(bytes, _), - ) => Ok(bytes.clone()), - Some(Node::ReadFails(error) | Node::LinkFails(error)) => Err(error.clone()), - Some(Node::Link | Node::ListFails(_)) => Err(FileError::new( - FileErrorKind::IsADirectory, - format!("is a directory: {path}"), - )), - Some(Node::Pipe) | None => Err(Self::missing(path)), - } - } - async fn read_prefix(&self, path: &str, len: u64) -> Result, FileError> { - let mut bytes = self.read(path).await?; + let mut bytes = self.bytes_at(path)?; bytes.truncate(usize::try_from(len).unwrap_or(usize::MAX)); Ok(bytes) } diff --git a/crates/plugin-std/src/grep.rs b/crates/plugin-std/src/grep.rs index f4603da..d8a466c 100644 --- a/crates/plugin-std/src/grep.rs +++ b/crates/plugin-std/src/grep.rs @@ -2,13 +2,14 @@ //! path. //! //! Grep walks the tree through the call's [`Source`], so the run's policy -//! applies, and reads each file whole, never more than 16 MiB of it. -//! Files come in path order, the order Glob uses. The lines of the answer -//! stop at 15,000 bytes, with the notes under them not counted, and every -//! call runs from the start, so a call with an `offset` pages through the -//! same result. An entry below the path the call names that cannot be -//! searched is skipped and counted, never a failure. The text of the -//! files is returned as untrusted output. +//! applies. It reads each file with one request, which asks for no more +//! than one byte past 16 MiB, so a longer file is skipped and never held +//! whole. Files come in path order, the order Glob uses. The lines of the +//! answer stop at 15,000 bytes, with the notes under them not counted, +//! and every call runs from the start, so a call with an `offset` pages +//! through the same result. An entry below the path the call names that +//! cannot be searched is skipped and counted, never a failure. The text +//! of the files is returned as untrusted output. mod args; mod collect; diff --git a/crates/plugin-std/src/grep/find.rs b/crates/plugin-std/src/grep/find.rs index ba78268..2382bf0 100644 --- a/crates/plugin-std/src/grep/find.rs +++ b/crates/plugin-std/src/grep/find.rs @@ -184,31 +184,41 @@ impl Search<'_, '_, S> { /// type applies, because the model named it. /// /// `size` is the file's size when the stat gave it, and `None` for a - /// link, whose own size says nothing about its target. + /// link, whose own size says nothing about its target. A size over + /// the limit skips the file with no read. async fn root_file(&mut self, root: &str, size: Option) -> Result<(), String> { let node = Node::file(root); self.considered += 1; - let bytes = if let Some(size) = size { - if size > self.limits.max_file_size { - self.skip(Reason::OverSize, Some(&node.shown)); - return Ok(()); - } - self.source.read(&node.access).await - } else { - self.source - .read_prefix(&node.access, self.limits.max_file_size.saturating_add(1)) - .await - } - .map_err(|error| refusal(self.tool, root, &error))?; - if size.is_none() && length(&bytes) > self.limits.max_file_size { + if size.is_some_and(|size| size > self.limits.max_file_size) { self.skip(Reason::OverSize, Some(&node.shown)); return Ok(()); } + let read = self + .read(&node.access) + .await + .map_err(|error| refusal(self.tool, root, &error))?; + let Some(bytes) = read else { + self.skip(Reason::OverSize, Some(&node.shown)); + return Ok(()); + }; self.bytes += length(&bytes); self.consume(&node.shown, &bytes); Ok(()) } + /// The bytes of the file at `path`, or `None` for a file over the + /// largest size a search takes. The read asks for one byte past that + /// size and no more, so a file that is longer than its listing or its + /// stat said shows as over the size and is never held whole. + async fn read(&self, path: &str) -> Result>, FileError> { + let most = self.limits.max_file_size; + let bytes = self + .source + .read_prefix(path, most.saturating_add(1)) + .await?; + Ok((length(&bytes) <= most).then_some(bytes)) + } + /// Walks the directory `root`, whose `entries` are already listed, /// depth first. async fn walk(&mut self, root: Node, entries: Vec) { @@ -285,11 +295,12 @@ impl Search<'_, '_, S> { self.finish(Stop::Bytes); return; } - match self.source.read(&node.access).await { - Ok(bytes) => { + match self.read(&node.access).await { + Ok(Some(bytes)) => { self.bytes += length(&bytes); self.consume(&node.shown, &bytes); } + Ok(None) => self.skip(Reason::OverSize, Some(&node.shown)), Err(error) => self.skip(file_reason(&error), Some(&node.shown)), } } diff --git a/crates/plugin-std/src/grep/found.rs b/crates/plugin-std/src/grep/found.rs index dd4b66b..199339b 100644 --- a/crates/plugin-std/src/grep/found.rs +++ b/crates/plugin-std/src/grep/found.rs @@ -29,7 +29,9 @@ pub(super) struct Limits { pub(super) max_files: usize, /// The most bytes read before the search stops. pub(super) max_bytes: u64, - /// The largest file, by the size its listing gives, that is searched. + /// The largest file that is searched. A longer one is skipped by the + /// size its listing gives, and failing that by a read that stops one + /// byte past this size. pub(super) max_file_size: u64, /// The files considered and directories listed between two pauses. pub(super) slice_entries: usize, @@ -61,7 +63,7 @@ pub(super) enum Reason { UnreadableDirectory, /// A file that could not be read. UnreadableFile, - /// A file whose listed size is over the limit. + /// A file over the size limit, by its listed size or by its bytes. OverSize, /// A symbolic link, which is never entered or read. SymbolicLink, diff --git a/crates/plugin-std/src/grep/tests/skips.rs b/crates/plugin-std/src/grep/tests/skips.rs index 4a992c5..99e9ae7 100644 --- a/crates/plugin-std/src/grep/tests/skips.rs +++ b/crates/plugin-std/src/grep/tests/skips.rs @@ -199,6 +199,39 @@ fn a_file_over_the_size_limit_is_skipped_before_any_read() { ); } +#[test] +fn a_file_that_is_longer_than_its_listing_said_is_skipped_and_not_searched() { + // The listing says 10 bytes, so the file passes the check before the + // read, and the read then finds more bytes than the limit. + let mut longer = b"NEEDLE\n".to_vec(); + longer.resize(500, b'a'); + let source = FakeSource::default() + .with("/grew.log", Node::Sized(10, longer)) + .file("/ok.txt", "NEEDLE\n"); + let output = text_of(grep_over( + &source, + &json!({ "pattern": "NEEDLE" }), + &small_files(), + )); + assert_eq!( + output, + "/ok.txt\n 1:NEEDLE\n\n[Skipped 1 entry: 1 file over 100 bytes. First: /grew.log]" + ); +} + +#[test] +fn a_file_exactly_at_the_size_limit_is_searched() { + let mut edge = b"NEEDLE\n".to_vec(); + edge.resize(100, b'a'); + let source = FakeSource::default().with("/edge.txt", Node::File(edge)); + let output = text_of(grep_over( + &source, + &json!({ "pattern": "NEEDLE" }), + &small_files(), + )); + assert_eq!(output, "/edge.txt\n 1:NEEDLE"); +} + #[test] fn a_missing_path_fails_with_the_does_not_exist_text() { let source = FakeSource::default().file("/a.txt", "x\n"); @@ -269,6 +302,24 @@ fn a_named_file_over_the_size_limit_is_a_skip() { ); } +#[test] +fn a_named_file_that_is_longer_than_its_stat_said_is_a_skip() { + let source = FakeSource::default().with("/grew", Node::Sized(10, vec![b'a'; 500])); + let output = grep_over( + &source, + &json!({ "pattern": "a", "path": "/grew" }), + &small_files(), + ) + .expect("the search succeeds"); + assert!( + output + .text() + .starts_with("No matches found. Searched 0 files.\n\n[Skipped 1 entry: 1 file over 100 bytes. First: /grew]"), + "{}", + output.text() + ); +} + #[test] fn a_named_link_is_searched_through_as_a_directory_and_then_as_a_file() { let source = FakeSource::default() diff --git a/crates/plugin-std/src/source.rs b/crates/plugin-std/src/source.rs index f120bff..46f5c54 100644 --- a/crates/plugin-std/src/source.rs +++ b/crates/plugin-std/src/source.rs @@ -20,11 +20,10 @@ pub(crate) trait Source { /// The entries of the directory at `path`, in no promised order. async fn list(&self, path: &str) -> Result, FileError>; - /// The whole contents of the file at `path`. - async fn read(&self, path: &str) -> Result, FileError>; - - /// At most the first `len` bytes of the file at `path`, for a path - /// whose size is not known beforehand. + /// At most the first `len` bytes of the file at `path`. It is the one + /// read there is: a tool asks for one byte more than the largest file + /// it takes, so a longer file shows as such and is never held whole, + /// whatever a stat or a listing said of its size. async fn read_prefix(&self, path: &str, len: u64) -> Result, FileError>; /// Writes `bytes` as the whole contents of the file at `path`. The @@ -46,10 +45,6 @@ impl Source for ToolCall<'_> { ToolCall::list(self, path).await } - async fn read(&self, path: &str) -> Result, FileError> { - ToolCall::read(self, path).await - } - async fn read_prefix(&self, path: &str, len: u64) -> Result, FileError> { ToolCall::read_range(self, path, 0, len).await } @@ -77,10 +72,6 @@ impl Source for runvil_plugin_sdk::testing::Files { runvil_plugin_sdk::testing::Files::list(self, path) } - async fn read(&self, path: &str) -> Result, FileError> { - runvil_plugin_sdk::testing::Files::read(self, path, 0, u64::MAX) - } - async fn read_prefix(&self, path: &str, len: u64) -> Result, FileError> { runvil_plugin_sdk::testing::Files::read(self, path, 0, len) } diff --git a/crates/plugin-std/tests/it/grep.rs b/crates/plugin-std/tests/it/grep.rs index 1ede1a6..cb06882 100644 --- a/crates/plugin-std/tests/it/grep.rs +++ b/crates/plugin-std/tests/it/grep.rs @@ -57,6 +57,37 @@ fn a_search_over_a_thousand_files_ends_a_step_at_each_file_operation_and_each_pa assert_eq!(rows.last(), Some(&"/f0999.txt:1")); } +#[test] +fn a_file_that_grows_past_the_limit_after_its_listing_is_skipped_and_not_searched() { + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded + .new_pack(PACK) + .expect("the Pack instance is made") + .with_files(Files::new().file("/grew.txt", "x\n")); + let mut call = pack.start("grep", &args()); + // The stat of the root, and then its listing, which says 2 bytes. + assert_eq!(call.step(), Ok(None)); + assert_eq!(call.step(), Ok(None)); + // Another task makes the file longer than a search takes, before the + // search asks for its bytes. + pack.files() + .write("/grew.txt", vec![b'x'; 16_777_218]) + .expect("the file is written"); + let result = loop { + if let Some(result) = call.step().expect("each step follows the contract") { + break result; + } + }; + let output = result.expect("the search completes with its result"); + assert_eq!( + output.text(), + "No matches found. Searched 0 files.\n\n\ + [Skipped 1 entry: 1 file over 16777216 bytes. First: /grew.txt]\n\ + [No ignore rules ran: .gitignore is not applied, and only entries named .git are \ + skipped.]" + ); +} + #[test] fn abandoning_a_search_after_its_first_step_leaves_the_instance_usable() { let loaded = testing::load::().expect("the Plugin loads"); From fb9471d798db60bd0da5fd7ef2d6e90b8667aa1b Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Wed, 18 Nov 2026 07:38:41 -0800 Subject: [PATCH 08/13] Make the Write and StrReplace texts say what the code does Three statements that a model reads said more than the code does. The description of StrReplace said that a call with `replace_all` fails only when there is no occurrence, and it named no limit on the edited file. The description of Write said that a read before a write keeps a change by someone else from being overwritten. - `replace.json` says that a call with `replace_all` needs at least one occurrence, and that an edit that would leave the file with more than `{write_limit}` bytes is refused. `fill` puts `RV_MAX_WRITE` in that placeholder, as it does for `write.json`. - `write.json` asks for the read "so that you know what the write replaces". A write also replaces a change that another task made after the read, so the text promises no protection. - `EDITS.md` records both changes. - `README.md` says that the Plugin speaks contract 0.5 and that a Host loads it only when its Harness speaks the same version. - The two tests of these descriptions hold the new sentences and both filled limits, and one holds that the words "never overwritten" are gone. - No code of a tool changes. Plan: runvil-harness/plan/2026-11-16-1-tool-file-effects.plan.md --- README.md | 2 +- crates/plugin-std/schemas/EDITS.md | 3 ++- crates/plugin-std/schemas/replace.json | 2 +- crates/plugin-std/schemas/write.json | 2 +- crates/plugin-std/src/spec-tests.rs | 21 ++++++++++++++++----- crates/plugin-std/src/spec.rs | 9 ++++++--- 6 files changed, 27 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 715aca2..db5b2eb 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ The Plugin inserts one Pack, `runvil/std`, which gives a run the standard file t cargo build -p plugin-std --release ``` -This writes `plugin_std.dll` (Windows), `libplugin_std.so` (Linux), or `libplugin_std.dylib` (macOS) to `target/release`. That one file goes in the Host's Plugin directory. +This writes `plugin_std.dll` (Windows), `libplugin_std.so` (Linux), or `libplugin_std.dylib` (macOS) to `target/release`. That one file goes in the Host's Plugin directory. The Plugin speaks contract 0.5, the version that the pin of `runvil-plugin-sdk` in `Cargo.toml` names, and a Host loads it only when its Harness speaks the same version. A Host can also link the crate in. It turns the `dll` feature off, so the crate exports no symbol, and passes `runvil_plugin_sdk::entry::` to the Harness's `insert_plugin`. diff --git a/crates/plugin-std/schemas/EDITS.md b/crates/plugin-std/schemas/EDITS.md index 830d4fe..afecf78 100644 --- a/crates/plugin-std/schemas/EDITS.md +++ b/crates/plugin-std/schemas/EDITS.md @@ -17,12 +17,13 @@ Each file in this directory except `dir.json` is Cursor's definition of the tool ## write.json - Cursor's `Write` description, which is about creating or overwriting a file. Reworded to name `StrReplace` for targeted changes and to require a read before overwriting, matching Cursor's own guidance. The parameters, their types, and the `required` list are Cursor's. +- The reason the text gives for that read is that the model then knows what the write replaces. The text does not say that the read protects a change, because a write also replaces a change that another task made after the read. - Added a `Usage` list that states what Write does: the directories on the way to the file are created, `contents` is written exactly as given and holds at most `{write_limit}` bytes, a path that names a directory fails, and the calls in one response that change files run one after another in the order listed. The placeholder is filled when the definition is built, from the SDK's limit on one write, which the code enforces, so the text and the limit cannot drift apart. ## replace.json - Cursor's `StrReplace` definition. The wording is ours; the parameters, their types, and the `required` list are Cursor's. -- Added a `Usage` list that states what StrReplace does: `old_string` is matched exactly, and the line number and the pipe that Read shows are not part of the file; a call fails with the count when `old_string` does not occur exactly once, and with `replace_all` it fails only when there is no occurrence; only UTF-8 text is edited, and a file over `{file_ceiling}` bytes is refused; and the calls in one response that change files run one after another in the order listed. The placeholder is filled when the definition is built, from the constant the code enforces, so the text and the limit cannot drift apart. +- Added a `Usage` list that states what StrReplace does: `old_string` is matched exactly, and the line number and the pipe that Read shows are not part of the file; a call fails with the count when `old_string` does not occur exactly once, and with `replace_all` the call needs at least one occurrence; only UTF-8 text is edited, a file over `{file_ceiling}` bytes is refused, and so is an edit that would leave the file with more than `{write_limit}` bytes; and the calls in one response that change files run one after another in the order listed. The two placeholders are filled when the definition is built, from the constants the code enforces, so the text and the limits cannot drift apart. ## rm.json diff --git a/crates/plugin-std/schemas/replace.json b/crates/plugin-std/schemas/replace.json index 6d7d516..cba1755 100644 --- a/crates/plugin-std/schemas/replace.json +++ b/crates/plugin-std/schemas/replace.json @@ -1,6 +1,6 @@ { "wire_name": "StrReplace", - "description": "Replaces an exact string in a file with a new string. The old string must be unique in the file unless replace_all is true, so include enough surrounding context to identify the one occurrence you mean. Read the file first.\n\nUsage:\n- old_string is matched exactly, so whitespace, indentation, and line endings count. The line number and the pipe that Read shows are not part of the file.\n- When old_string does not occur exactly once, the call fails and says how many times it occurs. With replace_all set to true, the call replaces every occurrence, and it fails only when there is none.\n- Only UTF-8 text is edited. A file over {file_ceiling} bytes is refused.\n- The calls in one response that change files run one after another, in the order you list them.", + "description": "Replaces an exact string in a file with a new string. The old string must be unique in the file unless replace_all is true, so include enough surrounding context to identify the one occurrence you mean. Read the file first.\n\nUsage:\n- old_string is matched exactly, so whitespace, indentation, and line endings count. The line number and the pipe that Read shows are not part of the file.\n- When old_string does not occur exactly once, the call fails and says how many times it occurs. With replace_all set to true, the call replaces every occurrence and needs at least one.\n- Only UTF-8 text is edited. A file over {file_ceiling} bytes is refused, and so is an edit that would leave the file with more than {write_limit} bytes.\n- The calls in one response that change files run one after another, in the order you list them.", "parameters": { "type": "object", "properties": { diff --git a/crates/plugin-std/schemas/write.json b/crates/plugin-std/schemas/write.json index 6734106..aa1cf1f 100644 --- a/crates/plugin-std/schemas/write.json +++ b/crates/plugin-std/schemas/write.json @@ -1,6 +1,6 @@ { "wire_name": "Write", - "description": "Creates or overwrites a file at the specified path. Use this tool to create a new file or to replace the whole contents of an existing one. If the destination file already exists, you MUST first read it before writing, so a change you did not make is never overwritten. For a targeted change to an existing file, prefer StrReplace.\n\nUsage:\n- The directories on the way to the file are created when they do not exist.\n- contents is written exactly as given, as the whole file. It holds at most {write_limit} bytes.\n- A path that names a directory fails.\n- The calls in one response that change files run one after another, in the order you list them.", + "description": "Creates or overwrites a file at the specified path. Use this tool to create a new file or to replace the whole contents of an existing one. If the destination file already exists, you MUST first read it before writing, so that you know what the write replaces. For a targeted change to an existing file, prefer StrReplace.\n\nUsage:\n- The directories on the way to the file are created when they do not exist.\n- contents is written exactly as given, as the whole file. It holds at most {write_limit} bytes.\n- A path that names a directory fails.\n- The calls in one response that change files run one after another, in the order you list them.", "parameters": { "type": "object", "properties": { diff --git a/crates/plugin-std/src/spec-tests.rs b/crates/plugin-std/src/spec-tests.rs index fae2463..bfb5090 100644 --- a/crates/plugin-std/src/spec-tests.rs +++ b/crates/plugin-std/src/spec-tests.rs @@ -162,16 +162,21 @@ fn the_write_description_holds_the_limit_of_one_write_and_states_what_the_tool_d "exactly as given", "names a directory fails", "one after another", + "so that you know what the write replaces", ] { assert!( text.contains(phrase), "the description names {phrase}: {text}" ); } + assert!( + !text.contains("never overwritten"), + "a read before a write protects no change that comes after it: {text}" + ); } #[test] -fn the_replace_description_holds_the_file_ceiling_and_states_what_the_tool_does() { +fn the_replace_description_holds_both_byte_limits_and_states_what_the_tool_does() { let definitions = all(); let replace = definitions .iter() @@ -179,18 +184,24 @@ fn the_replace_description_holds_the_file_ceiling_and_states_what_the_tool_does( .expect("the replace definition exists"); let text = &replace.description; assert!( - text.contains("over 16777216 bytes"), + text.contains("A file over 16777216 bytes is refused"), "the file ceiling is named: {text}" ); assert!( - !text.contains("{file_ceiling}"), - "{{file_ceiling}} is filled in: {text}" + text.contains("with more than 16777216 bytes"), + "the limit of one write is named for the edited file: {text}" ); + for placeholder in ["{file_ceiling}", "{write_limit}"] { + assert!( + !text.contains(placeholder), + "{placeholder} is filled in: {text}" + ); + } for phrase in [ "matched exactly", "line endings", "how many times it occurs", - "replaces every occurrence", + "replaces every occurrence and needs at least one", "UTF-8", "one after another", ] { diff --git a/crates/plugin-std/src/spec.rs b/crates/plugin-std/src/spec.rs index d29d98a..53cd174 100644 --- a/crates/plugin-std/src/spec.rs +++ b/crates/plugin-std/src/spec.rs @@ -94,9 +94,12 @@ fn fill(segment: &str, description: &str) -> String { "{write_limit}", &runvil_plugin_sdk::sys::RV_MAX_WRITE.to_string(), ), - "replace" => { - description.replace("{file_ceiling}", &crate::text::MAX_FILE_BYTES.to_string()) - } + "replace" => description + .replace("{file_ceiling}", &crate::text::MAX_FILE_BYTES.to_string()) + .replace( + "{write_limit}", + &runvil_plugin_sdk::sys::RV_MAX_WRITE.to_string(), + ), "dir" => description.replace("{body_cap}", &crate::text::BODY_CAP.to_string()), "grep" => description .replace("{body_cap}", &crate::text::BODY_CAP.to_string()) From 06cf8beb1ece41580e3f423961d3f2e53f1a7447 Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Wed, 18 Nov 2026 07:42:34 -0800 Subject: [PATCH 09/13] Test each step of a change and a cancel late in a search Three tests of the tools that change files counted the steps of a call and checked nothing else, so a call with the right number of requests in the wrong order, or with a wrong answer, passed them. The test of an abandoned search dropped the call after its first step, before the search had read a file. - The three tests in `tests/it/changes.rs` step the call by hand. Each tells which operation a step asked for by the files that the step leaves, and each checks the answer of the last step. - The test of `replace` puts other bytes in the file after the first step, and the edit is made on those bytes. This shows that the first request is not the read. - The test in `tests/it/grep.rs` abandons a search three times: at its first request, at the read of a file, and at `FIRST_PAUSE`, where 32 files are searched and no request is open. - The tests of calls that fail early still count their steps with `steps`. - No code of a tool changes. Plan: runvil-harness/plan/2026-11-16-1-tool-file-effects.plan.md --- crates/plugin-std/tests/it/changes.rs | 62 ++++++++++++++++++++++++--- crates/plugin-std/tests/it/grep.rs | 24 ++++++++--- 2 files changed, 73 insertions(+), 13 deletions(-) diff --git a/crates/plugin-std/tests/it/changes.rs b/crates/plugin-std/tests/it/changes.rs index 55501d1..0807c0f 100644 --- a/crates/plugin-std/tests/it/changes.rs +++ b/crates/plugin-std/tests/it/changes.rs @@ -1,6 +1,7 @@ //! The tools that change files, through the Plugin's entry point: which //! tools say to the Host that they change files, what a call leaves in -//! the files of its run, what it answers, and how many requests it makes. +//! the files of its run, what it answers, and what it asks the Host for, +//! step by step. use plugin_std::Std; use runvil_plugin_sdk::testing::{self, Files}; @@ -88,8 +89,19 @@ fn write_replaces_the_whole_contents_of_a_file() { #[test] fn write_asks_the_host_for_one_write_and_nothing_else() { + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded.new_pack(PACK).expect("the Pack instance is made"); let args = json!({ "path": "/a.md", "contents": "x" }); - assert_eq!(steps(Files::new(), "write", &args), 2); + let mut call = pack.start("write", &args.to_string()); + // The first step ends at a request, which the Host has performed + // when the step returns: it is the write. + assert_eq!(call.step(), Ok(None)); + assert_eq!(contents(pack.files(), "/a.md"), Ok(b"x".to_vec())); + // The second step has the answer and ends the call. + assert_eq!( + call.step(), + Ok(Some(Ok(ToolOutput::trusted("Wrote 1 byte.")))) + ); } #[test] @@ -183,9 +195,32 @@ fn str_replace_with_replace_all_edits_every_occurrence() { #[test] fn str_replace_asks_the_host_for_a_stat_a_read_and_a_write() { - let files = Files::new().file("/a.md", "one two\n"); + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded + .new_pack(PACK) + .expect("the Pack instance is made") + .with_files(Files::new().file("/a.md", "one two\n")); let args = json!({ "path": "/a.md", "old_string": "two", "new_string": "2" }); - assert_eq!(steps(files, "replace", &args), 4); + let mut call = pack.start("replace", &args.to_string()); + // The first request changes nothing, and it reads none of the bytes + // that the edit works on: the test puts other bytes in the file once + // the Host has performed it, and the edit is made on those. + assert_eq!(call.step(), Ok(None)); + assert_eq!(contents(pack.files(), "/a.md"), Ok(b"one two\n".to_vec())); + pack.files() + .write("/a.md", "uno two\n") + .expect("the file is written"); + // The second request is the read, which changes nothing. + assert_eq!(call.step(), Ok(None)); + assert_eq!(contents(pack.files(), "/a.md"), Ok(b"uno two\n".to_vec())); + // The third request is the write of the edited text. + assert_eq!(call.step(), Ok(None)); + assert_eq!(contents(pack.files(), "/a.md"), Ok(b"uno 2\n".to_vec())); + // The fourth step has the answer and ends the call. + assert_eq!( + call.step(), + Ok(Some(Ok(ToolOutput::trusted("Made 1 replacement.")))) + ); } #[test] @@ -254,8 +289,23 @@ fn delete_removes_a_file_and_answers_fixed_text_as_trusted_output() { #[test] fn delete_asks_the_host_for_a_stat_and_then_a_removal() { - let files = Files::new().file("/a.md", "one"); - assert_eq!(steps(files, "rm", &json!({ "path": "/a.md" })), 3); + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded + .new_pack(PACK) + .expect("the Pack instance is made") + .with_files(Files::new().file("/a.md", "one")); + let mut call = pack.start("rm", &json!({ "path": "/a.md" }).to_string()); + // The first request is the stat, which removes nothing. + assert_eq!(call.step(), Ok(None)); + assert_eq!(contents(pack.files(), "/a.md"), Ok(b"one".to_vec())); + // The second request is the removal. + assert_eq!(call.step(), Ok(None)); + assert_eq!(pack.files(), &Files::new()); + // The third step has the answer and ends the call. + assert_eq!( + call.step(), + Ok(Some(Ok(ToolOutput::trusted("Deleted the file.")))) + ); } #[test] diff --git a/crates/plugin-std/tests/it/grep.rs b/crates/plugin-std/tests/it/grep.rs index cb06882..ad7eeba 100644 --- a/crates/plugin-std/tests/it/grep.rs +++ b/crates/plugin-std/tests/it/grep.rs @@ -88,20 +88,30 @@ fn a_file_that_grows_past_the_limit_after_its_listing_is_skipped_and_not_searche ); } +/// How many steps a search of the seeded tree takes up to its first +/// pause: the stat of the root, its listing, the reads of 32 files, and +/// the step that ends at the pause. +const FIRST_PAUSE: usize = 2 + 32 + 1; + #[test] -fn abandoning_a_search_after_its_first_step_leaves_the_instance_usable() { +fn abandoning_a_search_at_a_request_or_at_its_first_pause_leaves_the_instance_usable() { let loaded = testing::load::().expect("the Plugin loads"); let pack = loaded .new_pack(PACK) .expect("the Pack instance is made") .with_files(seeded()); - { + // The search is abandoned at the stat of the root, then at the read + // of a file with some files searched, and then at its first pause, + // with 32 files searched and no request with the Host. + for steps in [1, 10, FIRST_PAUSE] { let mut abandoned = pack.start("grep", &args()); - assert_eq!( - abandoned.step(), - Ok(None), - "the search ends its first step before it can finish" - ); + for step in 1..=steps { + assert_eq!( + abandoned.step(), + Ok(None), + "step {step} of {steps} ends before the search can finish" + ); + } // Dropping the call sends `RV_TOOL_CANCEL`, as a canceled run does. } let read = pack From 25569ddebb80317de30653a4db6fb9231ab8fe2c Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Wed, 18 Nov 2026 08:16:41 -0800 Subject: [PATCH 10/13] Refuse a StrReplace text that overlaps itself A call without `replace_all` needs the text to occur exactly once, but the count came from `str::matches`, which leaves out an occurrence that overlaps the one before it. So `ana` counted once in `banana`, and the call edited the first of the two places where it starts. StrReplace now refuses such a text, because a refused edit costs a model one more call and a wrong edit can go unseen. - `starts_twice` makes one more search, which begins one character past the first place. It finds a second place and does not count the places, so its work stays in proportion to the length of the file. - The failure says that `old_string` starts at more than one place, in occurrences that overlap, and tells the model to add text around it. It does not offer `replace_all`, which would replace the first place alone. - A call with `replace_all` does what it did: it replaces the occurrences that do not overlap, from the start of the file. The description in `replace.json` states both rules in one sentence, and `EDITS.md` records it. - A text that occurs at two places that do not overlap still fails with its count. - `matches_are_counted_from_the_start_and_never_overlap` held the old rule and is gone. Three unit tests and one test through the entry point hold the new one. Plan: runvil-harness/plan/2026-11-16-1-tool-file-effects.plan.md --- crates/plugin-std/schemas/EDITS.md | 2 +- crates/plugin-std/schemas/replace.json | 2 +- crates/plugin-std/src/replace-tests.rs | 50 +++++++++++++++++++++++--- crates/plugin-std/src/replace.rs | 36 +++++++++++++++++-- crates/plugin-std/src/spec-tests.rs | 2 ++ crates/plugin-std/tests/it/changes.rs | 27 ++++++++++++++ 6 files changed, 110 insertions(+), 9 deletions(-) diff --git a/crates/plugin-std/schemas/EDITS.md b/crates/plugin-std/schemas/EDITS.md index afecf78..90c2126 100644 --- a/crates/plugin-std/schemas/EDITS.md +++ b/crates/plugin-std/schemas/EDITS.md @@ -23,7 +23,7 @@ Each file in this directory except `dir.json` is Cursor's definition of the tool ## replace.json - Cursor's `StrReplace` definition. The wording is ours; the parameters, their types, and the `required` list are Cursor's. -- Added a `Usage` list that states what StrReplace does: `old_string` is matched exactly, and the line number and the pipe that Read shows are not part of the file; a call fails with the count when `old_string` does not occur exactly once, and with `replace_all` the call needs at least one occurrence; only UTF-8 text is edited, a file over `{file_ceiling}` bytes is refused, and so is an edit that would leave the file with more than `{write_limit}` bytes; and the calls in one response that change files run one after another in the order listed. The two placeholders are filled when the definition is built, from the constants the code enforces, so the text and the limits cannot drift apart. +- Added a `Usage` list that states what StrReplace does: `old_string` is matched exactly, and the line number and the pipe that Read shows are not part of the file; a call fails with the count when `old_string` does not occur exactly once, and with `replace_all` the call needs at least one occurrence; where occurrences overlap, a call without `replace_all` fails and a call with it replaces the ones that do not overlap, from the start of the file; only UTF-8 text is edited, a file over `{file_ceiling}` bytes is refused, and so is an edit that would leave the file with more than `{write_limit}` bytes; and the calls in one response that change files run one after another in the order listed. The two placeholders are filled when the definition is built, from the constants the code enforces, so the text and the limits cannot drift apart. ## rm.json diff --git a/crates/plugin-std/schemas/replace.json b/crates/plugin-std/schemas/replace.json index cba1755..c48a571 100644 --- a/crates/plugin-std/schemas/replace.json +++ b/crates/plugin-std/schemas/replace.json @@ -1,6 +1,6 @@ { "wire_name": "StrReplace", - "description": "Replaces an exact string in a file with a new string. The old string must be unique in the file unless replace_all is true, so include enough surrounding context to identify the one occurrence you mean. Read the file first.\n\nUsage:\n- old_string is matched exactly, so whitespace, indentation, and line endings count. The line number and the pipe that Read shows are not part of the file.\n- When old_string does not occur exactly once, the call fails and says how many times it occurs. With replace_all set to true, the call replaces every occurrence and needs at least one.\n- Only UTF-8 text is edited. A file over {file_ceiling} bytes is refused, and so is an edit that would leave the file with more than {write_limit} bytes.\n- The calls in one response that change files run one after another, in the order you list them.", + "description": "Replaces an exact string in a file with a new string. The old string must be unique in the file unless replace_all is true, so include enough surrounding context to identify the one occurrence you mean. Read the file first.\n\nUsage:\n- old_string is matched exactly, so whitespace, indentation, and line endings count. The line number and the pipe that Read shows are not part of the file.\n- When old_string does not occur exactly once, the call fails and says how many times it occurs. With replace_all set to true, the call replaces every occurrence and needs at least one. Where occurrences of old_string overlap, a call without replace_all fails, and a call with it replaces the ones that do not overlap, from the start of the file.\n- Only UTF-8 text is edited. A file over {file_ceiling} bytes is refused, and so is an edit that would leave the file with more than {write_limit} bytes.\n- The calls in one response that change files run one after another, in the order you list them.", "parameters": { "type": "object", "properties": { diff --git a/crates/plugin-std/src/replace-tests.rs b/crates/plugin-std/src/replace-tests.rs index 545b9fc..cc0f059 100644 --- a/crates/plugin-std/src/replace-tests.rs +++ b/crates/plugin-std/src/replace-tests.rs @@ -201,13 +201,55 @@ fn the_text_put_in_is_not_searched_again() { } #[test] -fn matches_are_counted_from_the_start_and_never_overlap() { - let files = Files::new().file("/a.txt", "aaa"); +fn replace_all_replaces_the_occurrences_that_do_not_overlap_from_the_start_of_the_file() { + let files = Files::new() + .file("/a.txt", "aaaaa") + .file("/b.txt", "banana"); + assert_eq!( + text_of(edit_all(&files, "/a.txt", "aa", "b")), + "Made 2 replacements." + ); + assert_eq!(contents(&files, "/a.txt"), b"bba"); + assert_eq!( + text_of(edit_all(&files, "/b.txt", "ana", "X")), + "Made 1 replacement." + ); + assert_eq!(contents(&files, "/b.txt"), b"bXna"); +} + +#[test] +fn an_old_string_that_starts_at_two_places_that_overlap_is_refused_and_changes_nothing() { + let files = Files::new() + .file("/a.txt", "aaa") + .file("/b.txt", "banana") + .file("/c.txt", "\u{e9}\u{e9}\u{e9}"); + let before = files.clone(); + for (path, old) in [ + ("/a.txt", "aa"), + ("/b.txt", "ana"), + ("/c.txt", "\u{e9}\u{e9}"), + ] { + assert_eq!( + failure_of(edit(&files, path, old, "X")), + format!( + "`old_string` starts at more than one place in {path}, in occurrences that \ + overlap, and it must occur exactly once. Add text around it until it names one \ + occurrence." + ), + "{old:?}" + ); + } + assert_eq!(files, before); +} + +#[test] +fn more_text_around_an_old_string_that_overlaps_itself_names_one_occurrence() { + let files = Files::new().file("/b.txt", "banana"); assert_eq!( - text_of(edit(&files, "/a.txt", "aa", "b")), + text_of(edit(&files, "/b.txt", "bana", "X")), "Made 1 replacement." ); - assert_eq!(contents(&files, "/a.txt"), b"ba"); + assert_eq!(contents(&files, "/b.txt"), b"Xna"); } #[test] diff --git a/crates/plugin-std/src/replace.rs b/crates/plugin-std/src/replace.rs index 549879c..6efed83 100644 --- a/crates/plugin-std/src/replace.rs +++ b/crates/plugin-std/src/replace.rs @@ -6,9 +6,12 @@ //! must hold UTF-8. Nothing is decoded, and nothing outside the matches //! changes, so a byte order mark and the line endings stay as they are. //! The text to replace must occur exactly once, unless `replace_all` is -//! set, and a failure states how many times it occurs. An edit that would -//! leave the file longer than one write takes is refused from the count -//! of matches, before the edited text is built. +//! set, and a failure states how many times it occurs. A text that starts +//! at more than one place does not occur once, even where the places +//! overlap, and with `replace_all` the occurrences that do not overlap are +//! replaced, from the start of the file. An edit that would leave the file +//! longer than one write takes is refused from the count of matches, +//! before the edited text is built. //! //! The edit is a read and then a write, each a request to the Host of its //! own. A change that another task makes to the file between the two is @@ -68,6 +71,11 @@ pub(crate) async fn call( if count == 0 || (count > 1 && !request.all) { return Err(message(miscount(path, count, request.all))); } + // The count leaves out an occurrence that overlaps the one before + // it, so a text that is counted once can start at a second place. + if !request.all && starts_twice(&text, request.old) { + return Err(message(overlap(path))); + } // The length of the edited text follows from the count, so an edit // that is too long is refused before any of it is built. A call with // `replace_all` could otherwise ask for far more memory than the @@ -129,6 +137,18 @@ fn parse<'a>(definition: &Definition, args: &'a Value) -> Result, To }) } +/// Whether `old` starts at more than one place in `text`. A second place +/// can lie inside the first occurrence, as `ana` starts at two places in +/// `banana`, and [`str::matches`] counts such a text once. +fn starts_twice(text: &str, old: &str) -> bool { + // The second search begins one character past the first place, so it + // also finds a place inside the first occurrence. + let step = old.chars().next().map_or(1, char::len_utf8); + text.find(old) + .and_then(|first| text.get(first + step..)) + .is_some_and(|rest| rest.contains(old)) +} + /// The length in bytes of a text of `len` bytes once each of its `count` /// matches, of `old` bytes, has given way to `new` bytes. The matches do /// not overlap, so together they take up no more than `len` bytes. A @@ -158,6 +178,16 @@ fn miscount(path: &str, count: usize, all: bool) -> String { } } +/// The sentence for a text to replace that starts at more than one place +/// in the file at `path`, in occurrences that overlap, where the call +/// needs it once. +fn overlap(path: &str) -> String { + format!( + "`old_string` starts at more than one place in {path}, in occurrences that overlap, \ + and it must occur exactly once. Add text around it until it names one occurrence." + ) +} + #[cfg(test)] #[path = "replace-tests.rs"] mod tests; diff --git a/crates/plugin-std/src/spec-tests.rs b/crates/plugin-std/src/spec-tests.rs index bfb5090..cf9ff28 100644 --- a/crates/plugin-std/src/spec-tests.rs +++ b/crates/plugin-std/src/spec-tests.rs @@ -202,6 +202,8 @@ fn the_replace_description_holds_both_byte_limits_and_states_what_the_tool_does( "line endings", "how many times it occurs", "replaces every occurrence and needs at least one", + "a call without replace_all fails", + "replaces the ones that do not overlap, from the start of the file", "UTF-8", "one after another", ] { diff --git a/crates/plugin-std/tests/it/changes.rs b/crates/plugin-std/tests/it/changes.rs index 0807c0f..7c34502 100644 --- a/crates/plugin-std/tests/it/changes.rs +++ b/crates/plugin-std/tests/it/changes.rs @@ -239,6 +239,33 @@ fn an_edit_whose_text_does_not_occur_once_fails_with_the_count_before_any_write( assert_eq!(steps(before, "replace", &args), 3, "the stat and the read"); } +#[test] +fn an_edit_whose_text_overlaps_itself_fails_before_any_write_unless_it_replaces_all() { + let before = Files::new().file("/b.txt", "banana"); + let args = json!({ "path": "/b.txt", "old_string": "ana", "new_string": "X" }); + let (result, after) = change(before.clone(), "replace", &args); + let error = result.expect_err("the text starts at two places"); + assert_eq!( + error.message(), + "`old_string` starts at more than one place in /b.txt, in occurrences that overlap, and \ + it must occur exactly once. Add text around it until it names one occurrence." + ); + assert_eq!(error.kind(), ToolErrorKind::Other); + assert_eq!(after, before); + assert_eq!( + steps(before.clone(), "replace", &args), + 3, + "the stat and the read" + ); + let all = json!({ + "path": "/b.txt", "old_string": "ana", "new_string": "X", "replace_all": true + }); + let (result, after) = change(before, "replace", &all); + let output = result.expect("the occurrence that starts first is replaced"); + assert_eq!(output.text(), "Made 1 replacement."); + assert_eq!(contents(&after, "/b.txt"), Ok(b"bXna".to_vec())); +} + #[test] fn an_edit_the_policy_denies_fails_with_the_policys_own_reason_and_changes_nothing() { let reason = "Mode::Ask allows no read of /vault.md"; From ac72aa695e4791e10f6b722cacd262305ff12286 Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Wed, 18 Nov 2026 08:19:00 -0800 Subject: [PATCH 11/13] Count a read over the size limit toward Grep's byte limit A search stops when it has read `max_bytes` bytes, but a read that brought more than the size limit was skipped with no count. So files that grew after their listing could bring far more bytes than that limit allows, one bounded read after another. `read` now adds the length of every answer to `self.bytes`, and the two places that call it no longer do. - `read` takes `&mut self` and keeps the count itself, so a place that calls it cannot leave the count out. - A file that is skipped as over the size after its read counts as many bytes as the read brought, which is one more than the size limit. When the count reaches the limit, the search stops before the next read and says so in its notice. - A file whose listing or stat already gives a size over the limit is still skipped with no read, and it adds nothing. - The new test lists three files as 10 bytes that hold 500, under a size limit of 100 bytes and a byte limit of 202. Two reads of 101 bytes reach the limit, so the third file is never read. - A call that names one file makes one read, so the limit cannot stop it, and no test covers the count there. Plan: runvil-harness/plan/2026-11-16-1-tool-file-effects.plan.md --- crates/plugin-std/src/grep/find.rs | 13 ++++++------ crates/plugin-std/src/grep/tests/skips.rs | 26 +++++++++++++++++++++++ 2 files changed, 32 insertions(+), 7 deletions(-) diff --git a/crates/plugin-std/src/grep/find.rs b/crates/plugin-std/src/grep/find.rs index 2382bf0..3ab4800 100644 --- a/crates/plugin-std/src/grep/find.rs +++ b/crates/plugin-std/src/grep/find.rs @@ -201,7 +201,6 @@ impl Search<'_, '_, S> { self.skip(Reason::OverSize, Some(&node.shown)); return Ok(()); }; - self.bytes += length(&bytes); self.consume(&node.shown, &bytes); Ok(()) } @@ -209,13 +208,16 @@ impl Search<'_, '_, S> { /// The bytes of the file at `path`, or `None` for a file over the /// largest size a search takes. The read asks for one byte past that /// size and no more, so a file that is longer than its listing or its - /// stat said shows as over the size and is never held whole. - async fn read(&self, path: &str) -> Result>, FileError> { + /// stat said shows as over the size and is never held whole. Every + /// byte that the read brings counts toward the most a search reads, + /// the bytes of a file that is then skipped among them. + async fn read(&mut self, path: &str) -> Result>, FileError> { let most = self.limits.max_file_size; let bytes = self .source .read_prefix(path, most.saturating_add(1)) .await?; + self.bytes += length(&bytes); Ok((length(&bytes) <= most).then_some(bytes)) } @@ -296,10 +298,7 @@ impl Search<'_, '_, S> { return; } match self.read(&node.access).await { - Ok(Some(bytes)) => { - self.bytes += length(&bytes); - self.consume(&node.shown, &bytes); - } + Ok(Some(bytes)) => self.consume(&node.shown, &bytes), Ok(None) => self.skip(Reason::OverSize, Some(&node.shown)), Err(error) => self.skip(file_reason(&error), Some(&node.shown)), } diff --git a/crates/plugin-std/src/grep/tests/skips.rs b/crates/plugin-std/src/grep/tests/skips.rs index 99e9ae7..a5aa47e 100644 --- a/crates/plugin-std/src/grep/tests/skips.rs +++ b/crates/plugin-std/src/grep/tests/skips.rs @@ -219,6 +219,32 @@ fn a_file_that_is_longer_than_its_listing_said_is_skipped_and_not_searched() { ); } +#[test] +fn a_read_that_turns_out_over_the_size_limit_counts_toward_the_byte_limit() { + // Each listing says 10 bytes, and each read brings 101, one more than + // the size limit. The second read brings the count to the byte limit, + // so the search stops before it reads the third file. + let grown = Node::Sized(10, vec![b'a'; 500]); + let source = FakeSource::default() + .with("/a.log", grown.clone()) + .with("/b.log", grown.clone()) + .with("/c.log", grown); + let limits = Limits { + max_bytes: 202, + ..small_files() + }; + let output = + grep_over(&source, &json!({ "pattern": "a" }), &limits).expect("the search succeeds"); + assert_eq!( + output.text(), + "No matches found. Searched 0 files.\n\n\ + [Skipped 2 entries: 2 files over 100 bytes. First: /a.log, /b.log]\n\ + [No ignore rules ran: .gitignore is not applied, and only entries named .git are \ + skipped.]\n\ + [Search stopped after reading 202 bytes. Narrow path, glob or type to search the rest.]" + ); +} + #[test] fn a_file_exactly_at_the_size_limit_is_searched() { let mut edge = b"NEEDLE\n".to_vec(); From 218ece0a56b30d107cb31cb9633047aa64c35110 Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Wed, 18 Nov 2026 08:20:16 -0800 Subject: [PATCH 12/13] State the window between Delete's stat and its removal Delete asks what a path names in one request and removes it in the next, and the removal that the Host offers also takes a directory with no entries. The docs said that Delete refuses a directory, and they did not say that another task can put such a directory at the path between the two requests. Three places now say so, each in one sentence. - `README.md` has the sentence as a point of its own, after the point on the change that StrReplace can lose. - The docs of `rm.rs` and the crate docs in `lib.rs` have it after their sentence on the refusal of a directory. - No code changes, so the window stays open. Plan: runvil-harness/plan/2026-11-16-1-tool-file-effects.plan.md --- README.md | 1 + crates/plugin-std/src/lib.rs | 6 ++++-- crates/plugin-std/src/rm.rs | 6 ++++-- 3 files changed, 9 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index db5b2eb..4eff52d 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ The Plugin inserts one Pack, `runvil/std`, which gives a run the standard file t - File text and file names come back as untrusted output. The Host marks them before a model reads them. The answer to a change holds fixed text and at most a count, so it is trusted output. - Write, StrReplace, and Delete say to the Host that they change files. The Host runs a call of such a tool by itself among the calls of one model reply, so two changes of one reply happen in the order the reply lists them. - StrReplace edits a file with a read and then a write, so a change that another task makes to the file between the two is lost. +- Delete asks what a path names and then asks for its removal, so a directory with no entries that another task puts at the path between the two is removed. - A tool call ends its step at each file operation, and the Host performs the operation before the next step. A search also ends its step every 32 files or directories, so the Host can cancel a call between two steps. ## Building diff --git a/crates/plugin-std/src/lib.rs b/crates/plugin-std/src/lib.rs index 6848ebf..f9e73a3 100644 --- a/crates/plugin-std/src/lib.rs +++ b/crates/plugin-std/src/lib.rs @@ -85,8 +85,10 @@ //! //! Delete is real. It asks what the path names and then asks for its //! removal. It refuses a directory with a sentence, and it fails on a -//! path where nothing is. A link goes as a link, so what it leads to -//! stays. Its answer is fixed text, so it comes back as trusted output. +//! path where nothing is. The delete is a stat and then a removal, so a +//! directory with no entries that another task puts at the path between +//! the two is removed. A link goes as a link, so what it leads to stays. +//! Its answer is fixed text, so it comes back as trusted output. //! //! Glob is still a stub: a call with arguments that match the schema //! answers [`NOT_IMPLEMENTED`]. For every tool, a call whose arguments do diff --git a/crates/plugin-std/src/rm.rs b/crates/plugin-std/src/rm.rs index 5d0aff5..f40eeef 100644 --- a/crates/plugin-std/src/rm.rs +++ b/crates/plugin-std/src/rm.rs @@ -4,8 +4,10 @@ //! through the call's [`Source`], so the run's policy applies. The stat //! comes first because the removal the Host offers also takes a //! directory with no entries, and Delete removes no directory: it -//! refuses one with a sentence. A link goes as a link, so what it leads -//! to stays. The answer is fixed text, so it is trusted output. +//! refuses one with a sentence. The two are requests of their own, so a +//! directory with no entries that another task puts at the path between +//! them is removed. A link goes as a link, so what it leads to stays. The +//! answer is fixed text, so it is trusted output. use runvil_plugin_sdk::{FileError, FileType, ToolError, ToolErrorKind, ToolOutput}; use serde_json::Value; From a806bf63e3b0a23c85f3599a1b03fea578c77a2d Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Wed, 18 Nov 2026 08:22:37 -0800 Subject: [PATCH 13/13] Pin the length that each read of Grep asks for The tests of a file that is longer than its listing said check that Grep skips the file, so a search that read such a file whole and then skipped it would pass them. A new test checks the length that each read asks for. - `FakeSource` keeps the `len` of each `read_prefix` in `asked`. The field is a `RefCell`, because a read takes `&self`. - The test expects 101 for each of the two reads of a walk under a size limit of 100 bytes, and 16777217 for the read of a named file under the default limit. - No code of a tool changes. Plan: runvil-harness/plan/2026-11-16-1-tool-file-effects.plan.md --- crates/plugin-std/src/fake.rs | 10 ++++++++++ crates/plugin-std/src/grep/tests/skips.rs | 18 ++++++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/crates/plugin-std/src/fake.rs b/crates/plugin-std/src/fake.rs index 5bc3dd4..c1ea50f 100644 --- a/crates/plugin-std/src/fake.rs +++ b/crates/plugin-std/src/fake.rs @@ -12,6 +12,7 @@ //! lists as a directory. The tree never changes: it fails every change, //! with the error of a [`Node::Guarded`] where the path names one. +use std::cell::RefCell; use std::collections::BTreeMap; use std::future::Future; use std::pin::pin; @@ -67,9 +68,17 @@ pub(crate) enum Node { pub(crate) struct FakeSource { /// Every node but the root. nodes: BTreeMap, + /// The most bytes that each read asked for, in the order of the reads. + asked: RefCell>, } impl FakeSource { + /// The most bytes that each read of the tree asked for, in the order + /// of the reads. + pub(crate) fn asked(&self) -> Vec { + self.asked.borrow().clone() + } + /// The tree with `node` added at `path`. pub(crate) fn with(mut self, path: &str, node: Node) -> FakeSource { self.nodes.insert(path.to_owned(), node); @@ -183,6 +192,7 @@ impl Source for FakeSource { } async fn read_prefix(&self, path: &str, len: u64) -> Result, FileError> { + self.asked.borrow_mut().push(len); let mut bytes = self.bytes_at(path)?; bytes.truncate(usize::try_from(len).unwrap_or(usize::MAX)); Ok(bytes) diff --git a/crates/plugin-std/src/grep/tests/skips.rs b/crates/plugin-std/src/grep/tests/skips.rs index a5aa47e..e36fa71 100644 --- a/crates/plugin-std/src/grep/tests/skips.rs +++ b/crates/plugin-std/src/grep/tests/skips.rs @@ -219,6 +219,24 @@ fn a_file_that_is_longer_than_its_listing_said_is_skipped_and_not_searched() { ); } +#[test] +fn each_read_asks_for_one_byte_past_the_size_limit_and_no_more() { + let source = FakeSource::default() + .with("/grew.log", Node::Sized(10, vec![b'a'; 500])) + .file("/ok.txt", "NEEDLE\n"); + // A walk reads both files, and the call after it reads the one file + // that it names, under the limit of 16 MiB that a real search has. + let walked = grep_over(&source, &json!({ "pattern": "NEEDLE" }), &small_files()); + assert!(walked.is_ok()); + let named = grep_over( + &source, + &json!({ "pattern": "NEEDLE", "path": "/ok.txt" }), + &Limits::default(), + ); + assert!(named.is_ok()); + assert_eq!(source.asked(), [101, 101, 16_777_217]); +} + #[test] fn a_read_that_turns_out_over_the_size_limit_counts_toward_the_byte_limit() { // Each listing says 10 bytes, and each read brings 101, one more than