sausage/AGENTS.md

Working on Sausage

Sausage is meant to be read and changed by agents, including its own agent. Keep it that way.

Priorities

1. Correct. Every behavior in PROTOCOL.md has a test in cli/tests/.
2. Simple and short. Prefer the obvious code. No abstraction for one caller. No configuration that nobody asked for.
3. Readable. A new reader must understand a file without the others. Each module starts with a doc comment that says what it owns.
4. Efficient on the paths that run per call.
5. Raw and minimal. Sausage has no permissions, sandboxing beyond WASI, limits, or authentication. Do not add them to the core. Add nothing to the host that a plugin (or the agent, by changing itself) could do.

Layout

• cli/: the host (sausage binary and library): the core, the native cargo plugin, the WASI test runner, and the console.
• vfs/: sausage-vfs, the virtual filesystem for WASI guests. It knows nothing about Sausage.
• interface/: sausage-interface: OpenRPC documents, the compatibility check, and the generator of client code.
• sdk/: sausage-plugin, the SDK for Rust plugins, and sdk/macros/, its macros. Never published: cargo points sausage-plugin = "0.1" at its local copy.
• agent/: the agent plugin. sausage init embeds and builds it.
• examples/: small plugins. They are not workspace members.
• PROTOCOL.md: the contract between the core and the plugins. Change it in the same commit as the behavior. DECISIONS.md says why; when the two disagree, PROTOCOL.md and the code win.

Checks

nix flake check -L      # all tests below; CI runs this on every push
nix develop -c cargo test --workspace     # fast with a warm cache: run it during development
nix develop -c cargo build --release -p agent --target wasm32-wasip2
nix develop -c cargo clippy --workspace

nix run -- init and nix run -- run must keep working without other setup.

Tests must stay fast:

• Only a few tests may wait for a timing (grace periods, deadlines).
• Poll for a condition with a deadline. Do not sleep.
• Do not test unrealistic load, such as many fast cycles.
• #[ignore] only disables a test for a short time, with the reason in the attribute.
• Tests that build plugins use the persistent cache in env!("CARGO_TARGET_TMPDIR").