Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,10 @@ 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.
- 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.
- 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.

Expand Down
8 changes: 4 additions & 4 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"] }
Expand Down
19 changes: 11 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,23 +9,26 @@ 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/rm` | `Delete` | A stub |
| `std/glob` | `Glob` | A stub |
| `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` | 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 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.
- 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 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

```text
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::<plugin_std::Std>` to the Harness's `insert_plugin`.

Expand Down
9 changes: 7 additions & 2 deletions crates/plugin-std/schemas/EDITS.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,20 @@ 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.
- 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` 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

- 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

Expand Down
2 changes: 1 addition & 1 deletion crates/plugin-std/schemas/replace.json
Original file line number Diff line number Diff line change
@@ -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 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": {
Expand Down
2 changes: 1 addition & 1 deletion crates/plugin-std/schemas/rm.json
Original file line number Diff line number Diff line change
@@ -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": {
Expand Down
2 changes: 1 addition & 1 deletion crates/plugin-std/schemas/write.json
Original file line number Diff line number Diff line change
@@ -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 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": {
Expand Down
11 changes: 6 additions & 5 deletions crates/plugin-std/src/dir.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<ToolOutput, ToolError> {
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<'_>,
Expand All @@ -53,15 +53,16 @@ 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)));
}
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)))
}
Expand Down
58 changes: 53 additions & 5 deletions crates/plugin-std/src/dir/tests.rs
Original file line number Diff line number Diff line change
@@ -1,18 +1,20 @@
//! 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;
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};
Expand All @@ -38,7 +40,7 @@ fn definition() -> &'static Definition {
fn list(files: &impl Source, args: &Value) -> Result<ToolOutput, ToolError> {
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`.
Expand All @@ -55,7 +57,53 @@ 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>(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<F> Source for Lister<F>
where
F: Fn(&str) -> Result<Vec<DirEntry>, FileError>,
{
async fn stat(&self, path: &str) -> Result<Stat, FileError> {
panic!("the walk asked what {path} names")
}

async fn list(&self, path: &str) -> Result<Vec<DirEntry>, FileError> {
(self.0)(path)
}

async fn read_prefix(&self, path: &str, _len: u64) -> Result<Vec<u8>, FileError> {
panic!("the walk read {path}")
}

async fn write(&self, path: &str, _bytes: Vec<u8>) -> 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
/// `ignore`, under the byte cap `cap`.
fn walk_listed(
target: &str,
ignore: &[Matcher],
cap: usize,
list: impl Fn(&str) -> Result<Vec<DirEntry>, FileError>,
) -> Result<Tree, Failure> {
block_on(walk(&Lister(list), target, ignore, cap))
}

/// The text of a successful listing, which must be untrusted output.
Expand Down
5 changes: 2 additions & 3 deletions crates/plugin-std/src/dir/tests/ignore.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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"
Expand Down
Loading
Loading