The contract between a runvil Host and its Plugins, and nothing else: runvil_plugin.h, runvil-plugin-sys (its raw Rust mirror), and runvil-plugin-sdk (a safe Rust layer over the mirror). The Engine, the Harness, and Workshop live in other repositories and depend on this one; this repository depends on none of them.
These terms have exactly one meaning each, everywhere in this repository, as in the Engine's repository. Write them capitalized.
- Engine: the crates that parse a prompt and step a run. They never see this contract.
- Harness: the crates that step the Engine and perform its effects. The Harness's loader is the only code that calls a Plugin's entry point in production.
- Host: an application that runs prompts through the Harness, such as Workshop. The Host chooses which Plugins load.
- Pack: code which installs an optional native prelude, an optional Lua prelude, and zero or more tools.
- Plugin: an entry point which installs zero or more Packs. A library Plugin is a dynamic library that exports
runvil_plugin; a linked Plugin is compiled into the Host under a name of its own crate's choosing.
Anything else gets a qualified lowercase name, such as Rust's built-in test harness or a C compiler's plugin. Names defined outside this repository, such as Cargo's links key, are used exactly as defined.
crates/runvil-plugin-sys/src/lib.rsis the single source of the contract.crates/runvil-plugin-sys/include/runvil_plugin.his generated from it bycargo xtask headerand never edited by hand; its crate docs, up to## Invariants, become the header's opening comment.- A status code, verb, result kind, file type, file error kind, tool flag, or field keeps its number and position in every version. A reserved verb number is never reused for anything else.
- The
runvil-plugin-sysversion is the contract's version,RV_API_MAJOR.RV_API_MINOR; a unit test checks it. Changing the contract means changing both. - While the major version is 0, each version is its own contract, and the SDK accepts only a Host that reports exactly its version. From 1.0, a minor version only adds, at the end of a struct, or as a new verb with an arguments struct of its own.
RvHostholds only what is true on every call. Each function a Plugin may call back belongs to one verb and sits in that verb's arguments struct, beside thectxit takes first, under that verb's own lifetime and thread rules.- A Host keeps the
ctxof a load valid while the Plugin is loaded, untilRV_PLUGIN_UNLOADreturns, and answers a call through anyctxoutside its verb's rules withRV_ERR_MISUSE; it never reads through actxit has not matched to the call open on the calling thread. - The contract stays minimal. A verb, a field, or a function joins only when a Plugin that exists needs it, and each one says who calls it, on which thread, how long what it passes stays valid, and who frees what.
- JSON crosses the contract as text. Neither crate here parses it, so neither needs a JSON library.
- A tool reaches its run's files only through the file functions of its step, so the run's policy applies to every operation. A file function only takes a request, and the call's next step receives the answer. The answer belongs to the Host and is valid for that step alone, so the SDK copies it before it polls the tool's future.
- Every file function has that one form, a request in one step and its answer in the next, whether it reads a file or changes one, so that the Harness can perform each file operation of a tool as an effect and record it. The file methods of the SDK return futures.
runvil-plugin-syshas no dependencies and nounsafe.runvil-plugin-sdkdepends onrunvil-plugin-sysalone. Neither ever depends on an Engine or Harness crate.- A Plugin shares its process with the Host, so nothing here installs process-global state, such as a panic hook (
clippy.tomlbansstd::panic::set_hook), and no panic ever unwinds across the C boundary. testingin the SDK checks a Plugin's calls the way the Harness's loader does: the same order of checks, the same bounds, the same rules on names, versions, and tool infos, and the same words for each misuse. When the loader's checks change, this changes with them.
- Prefer types and compiler checks, then behavior tests. A rule a Plugin's constants must follow is checked when the Plugin is compiled, as
entrychecksPlugin::NAMEandPlugin::VERSION. - Behavior changes ship with tests in the same change.
- Unsafe code stays in its explicitly owned boundary: in the SDK,
entryand its child modules, theexport_plugin!expansion, andtesting; intests/c-layout, the test-only calls. Everyunsafeblock has a// SAFETY:comment, and everyunsafe fna# Safetysection. - Comments explain a non-obvious constraint, ordering requirement, or workaround.
- New unit tests go in a
#[cfg(test)] mod testsblock in the file under test. - Error and status messages are written for a model to read: concise, factual, and self-contained, naming what is missing or unmet.
- Tests, including the header freshness check and the C and C++ layout check:
cargo test --workspace --all-features. - Linter:
cargo clippy --workspace --all-targets --all-features, gated withCARGO_BUILD_WARNINGS=deny. - Formatter:
cargo fmt --all --check. - Docs:
cargo doc --workspace --no-deps --all-featureswithRUSTDOCFLAGS="-D warnings". - Toolchain floor of the two crates a Plugin depends on:
cargo +1.85 check -p runvil-plugin-sys -p runvil-plugin-sdk --all-features.