Files

T

ci / check (push) Successful in 15m52s

Details

YAML configuration, init without a wizard, and openai-chat-completions

- /config/agent.yaml and /config/boot.yaml replace the JSON files, read
  with serde_yaml_ng (also in the agent, inside WASM).
- sausage init asks nothing and reads no SAUSAGE_* variables. It writes
  commented templates with an example for each API, and prints the path
  to edit. Until the agent is configured, agent.chat names the missing
  field. allow_no_token: true permits a local model without a key.
- The agent speaks openai-chat-completions, the format of OpenRouter,
  Ollama, and most providers. base_url follows each SDK: with /v1 for
  the OpenAI shapes, without it for Anthropic.
- Checked against the proxy with glm-5.3-flash: the agent wrote, built,
  and activated a counter plugin in 55 s.

2026-10-23 11:27:48 +01:00

5.2 KiB

Raw Blame History

Decisions

Why Sausage is the way it is. PROTOCOL.md and the code own the details. When this file disagrees with them, they win.

The shape

JSON-RPC, not component interfaces. Every language can read and write lines of JSON, and models know JSON-RPC from LSP and MCP. A call has a result, like an LLM tool call.
A process per call. WASI has no threads, so processes give parallelism. A new version applies at the next call, and old processes retire after a grace period.
Attached by default. A process does not outlive its caller by accident. A long-running process must ask for detach.
Services in one file. Only the core starts and restarts them, so upgrades and singletons need no logic in plugins.
Files to inspect, calls to act. This keeps the core API small, and the agent's file tools are enough to explore the world.
The core accepts only .wasm files. It knows no source language. cargo is one way to get a .wasm file.
The world folder is the source of truth. Copy a plugin folder into another world, and it works there.
The agent is a normal plugin. It can read and upgrade its own source, and change how it does inference.

Interfaces

Generated imports and interface checks, without version numbers. A model that translates a description by hand makes errors. A generator does not. The check catches the most common error in a world that changes itself: a change to one plugin breaks another one.
A small schema subset. With Draft 7 and a fixed subset, our own check can decide every case. It never has to guess.
Docs are part of the interface. Other agents work from them, so the SDK requires a doc comment on each method, type, and field.
The check covers calls, not state. Old and new versions share /state. A plugin keeps its state format compatible, or migrates it in rpc.retired.

Minimal on purpose

The core does only what a plugin cannot do for itself. Everything else can be a plugin, or a change that the agent makes to itself.

No permissions, no limits, no hiding. Any process can call, upgrade, or stop any plugin, read and write every file, and use the network. The checks protect against mistakes, not against plugins. Locks are advisory.
Locks are in the core. A plugin cannot see that another process died, so it cannot release that process's lock. The core can.
Our own VFS, in its own crate. It works on Linux and macOS, it makes /proc live, and plugin-served files need it later. Mounts now, overlays later.
TCP endpoints for now. They need no host code. VFS pipes can replace them later behind the same SDK API.
Simple scheduling for now. An epoch tick every 10 milliseconds keeps the core responsive and makes kills reliable.
The agent is dumb. It has a short prompt, a few tools, an append-only history that it sends in full, and no compaction. When the context is too large, it stops sending the oldest turns, so it never gets stuck.

Small choices

YAML for configuration, JSON for data. A person edits configuration, so it needs comments. init writes commented templates instead of asking questions, so there is one way to configure a world.
Plain POSIX files. Programs like tempfile, git, and SQLite expect normal files. Atomic writes use a temporary file and rename.
Tests run under WASI. cargo test on the host cannot find failures that occur only in WASI, for example a missing WASI function or a panic at start. The test runner uses the same Wasmtime and the same mounts as the core.
The SDK is not published. cargo points sausage-plugin = "0.1" at its own copy, which it also shows in /plugins/cargo/sdk/.
Compiled code is a cache, not state. It lives outside the world, in one cache folder that all worlds share: wasmtime/ (owned by Wasmtime, whose cleanup deletes unknown entries), cargo-target/, and sdk/<hash>/. A path that depends only on the content of the SDK lets cargo reuse the compiled SDK in every world. Tests run in the release profile, so that they share compiled crates with the release build.
mold links host code where Nix provides it. On Linux, the dev shell, the Nix builds, and the packaged sausage (for the proc macros and build scripts of plugins) link with mold, much faster than GNU ld. Plugins for wasm32-wasip2 link with rust-lld. Without Nix, the default linker stays.
No LTO. Measured: fat LTO makes the binary 28 % smaller, but compiles plugins and answers calls at most 5–8 % faster, for 4 more minutes per release build. Thin LTO brings nothing.
Discovery has a deadline of 10 seconds. It is an internal call of the core, not a limit on plugins. Without it, one plugin that does not answer would block every activation.
A broken plugin blocks nobody. A plugin without a document is already broken, so the check cannot protect it. The graph shows it as "unavailable", and core.revert and force always work.
rpc.retired is best effort. It does not run if the host stops first. A persistent queue of retirements would be more core for a rare case, so a new version checks its own migration marker instead.