surma
11144b947e
Host: - test first: a new version is tested where it lies; only an installed version goes to versions/, and instances run from there - data/ and public/ are shared by all versions; no snapshots; rollback restores code only - no re-delivery, status.json, list, remove/archive, smoke test, data/ hiding, or stdin timeout; rollback needs a version - supervisor.rs split out; one place for installing a version - init only writes the agent folder; run installs it like any actor - console: @actor, text to the agent, /help, /quit Agent: - every text goes out as a broadcast; 5-line prompt; 5 tools that describe themselves; turn.json only marks an active turn Docs: PROTOCOL.md, README.md, DECISIONS.md, AGENTS.md rewritten. Examples: only notes and notes-v2.
61 lines
2.2 KiB
Markdown
61 lines
2.2 KiB
Markdown
# Sausage
|
|
|
|
You can see how the sausage is made.
|
|
|
|
Sausage is a world of small programs ("actors") that you grow by talking to
|
|
it. Each actor is a WASI program with stdin and stdout. Actors send each other
|
|
JSON messages, one per line, through a broker. The agent is an actor too: it
|
|
writes new actors in Rust, builds them, tests them, starts them, and can
|
|
change its own code.
|
|
|
|
## Start
|
|
|
|
You need [Nix](https://nixos.org/download) with flakes.
|
|
|
|
```sh
|
|
nix run -- init # creates ./world and builds the agent (a few minutes)
|
|
nix run -- run # starts the world and a console
|
|
```
|
|
|
|
`init` asks for the API shape (`openai-responses` or `anthropic-messages`),
|
|
the base URL, the model, and the token. It reads `SAUSAGE_API`,
|
|
`SAUSAGE_BASE_URL`, `SAUSAGE_MODEL`, and `SAUSAGE_API_TOKEN` first. The
|
|
values go to `world/actor/agent/data/config.json`. Both commands take another
|
|
folder as an argument, for example `nix run -- run my-world`.
|
|
|
|
In the console:
|
|
|
|
```text
|
|
write an actor "notes" that stores notes, and start it → text to the agent
|
|
@notes {"type":"add","text":"milk"} → a JSON message to an actor
|
|
@agent hello → text to an actor
|
|
/quit
|
|
```
|
|
|
|
## The world folder
|
|
|
|
The folder is the source of truth. Every actor lives in `world/actor/<id>/`:
|
|
|
|
```text
|
|
actor.wasm the current version
|
|
actor.json installed version, running, subscriptions
|
|
source/ the source of the current version
|
|
public/ files that the actor publishes
|
|
data/ the actor's state
|
|
stderr.log what the actor and the broker write about it
|
|
versions/<n>/ every installed version: actor.wasm, source/, meta.json
|
|
```
|
|
|
|
To add or replace an actor by hand, put an `actor.wasm` (and its `source/`,
|
|
with the tests in `source/tests/`) into its folder. Then restart the world or
|
|
send `@broker {"type":"scan"}`. The broker tests the file before it uses it.
|
|
If the tests fail, the old version keeps running, and `stderr.log` says why.
|
|
|
|
## More
|
|
|
|
- [PROTOCOL.md](PROTOCOL.md): messages, the filesystem, the broker, `cargo`.
|
|
Read this to write an actor in any language.
|
|
- [`sdk/`](sdk/): `sausage-actor`, the SDK for Rust actors.
|
|
- [`examples/notes`](examples/notes): a small actor with a test.
|
|
- [AGENTS.md](AGENTS.md): how to work on Sausage itself.
|