Skip to content

About

Runvil harness standard tool pack

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

runvil-plugin-std

The std Plugin for runvil, built as a dynamic library that a Host loads from its Plugin directory. It speaks the C contract in runvil-plugin-api through runvil-plugin-sdk, and depends on nothing else from runvil.

The Plugin inserts one Pack, runvil/std, which gives a run the standard file tools a coding agent needs. A prompt declares it with uses: [std], a script calls a tool by its Lua id, and a model calls it by its wire name. Each wire name is Cursor's name for the same tool, except ListDir, which is this Pack's own.

Lua id Name the model calls In this build
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 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 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

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. 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.

Working on this repository

Task Command
Test, including the structural checks cargo test --locked --workspace --all-features
Lint, with CARGO_BUILD_WARNINGS=deny cargo clippy --locked --workspace --all-targets --all-features
Format cargo fmt --all --check
Docs, with RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --no-deps --all-features --document-private-items
The library Plugin cargo build --locked -p plugin-std --release

CI runs these five. AGENTS.md holds the rules the code follows. Sizes are limited on functions and types, never on files: clippy.toml sets the function limits, and crates/build-checks checks the type limits as a test.

Platform notes

  • Windows: the Harness resolves a library Plugin's own DLL dependencies only from the Plugin's directory and System32. This repository links with the static CRT (.cargo/config.toml), so the Plugin does not need the MSVC runtime DLLs.
  • Keep Cargo's default panic = "unwind". With panic = "abort", a panic in the Plugin aborts the Host's process instead of becoming a refusal or a failed tool call.

License

Boost Software License 1.0; see LICENSE.

About

Runvil harness standard tool pack

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages