Sausage: host, broker, commit-on-close filesystem, cargo actor, console, agent
Imported from the spike branch, with: - a library crate (Host API) for the CLI and the tests - JSON test scenarios for candidates - commit on close only for new or truncated files - a Nix flake: nix run -- init, nix run -- run
This commit is contained in:
@@ -0,0 +1,65 @@
|
||||
# Sausage
|
||||
|
||||
You can see how the sausage is made.
|
||||
|
||||
Sausage is a system of actors that you grow by talking to it. Every actor is a
|
||||
WASI program (a `.wasm` file) with stdin and stdout. Actors send each other
|
||||
newline-delimited JSON messages through a broker. The agent is an actor too:
|
||||
it does inference over HTTP, writes new actors, and can change its own code.
|
||||
|
||||
Inspired by [Jiti](https://ghuntley.com/lisp/), but with WASM instead of a
|
||||
Lisp image.
|
||||
|
||||
## Quick start
|
||||
|
||||
```sh
|
||||
nix develop
|
||||
cargo build --release
|
||||
export SAUSAGE_API_TOKEN=... # or type it at the prompt
|
||||
./target/release/sausage init world --api openai-responses \
|
||||
--base-url https://api.example.com --model some-model
|
||||
./target/release/sausage run world
|
||||
```
|
||||
|
||||
`init` builds the agent (the first build takes a few minutes) and writes its
|
||||
configuration to `world/private/agent/data/config.json`. The source contains
|
||||
no endpoint and no token.
|
||||
|
||||
In the console:
|
||||
|
||||
```text
|
||||
hello → text to the agent
|
||||
@notes {"type":"add","text":"milk"} → a JSON message to an actor
|
||||
@agent what actors exist? → text to an actor
|
||||
/deploy notes examples/notes → build with cargo, then spawn or upgrade
|
||||
/list → list actors
|
||||
/await agent 300 → wait for the next message (scripts)
|
||||
/quit
|
||||
```
|
||||
|
||||
## Concepts
|
||||
|
||||
- **Actor**: a `wasi:cli/command` program. It reads messages on stdin and
|
||||
writes messages on stdout. Logs go to stderr.
|
||||
- **Message**: `{"id", "from", "reply_to"?, "body"}` on stdin;
|
||||
`{"to"?, "id"?, "reply_to"?, "body"}` on stdout. No `to` = publish to
|
||||
subscribers. There is no request/response: a reply is a new message with
|
||||
`reply_to`. Delivery is at most once.
|
||||
- **Broker**: routes messages, owns mailboxes, and runs actors. It accepts
|
||||
only `.wasm` files: `spawn`, `upgrade`, `rollback`, `stop`, `start`,
|
||||
`remove`, `subscribe`, `unsubscribe`, `list`.
|
||||
- **cargo**: the built-in Rust compiler actor. `build` a source folder, get a
|
||||
`.wasm` path back. Other actors can add other languages.
|
||||
- **Filesystem** of each actor:
|
||||
- `/data`: private state
|
||||
- `/public`: its public files
|
||||
- `/actor/<id>/{public,source,status.json,stderr.log}`: every actor, read-only
|
||||
|
||||
A write becomes visible when the writer closes the file (commit on close).
|
||||
- **Upgrade**: the broker tests the candidate on a copy of `/data` and
|
||||
`/public` (transcripts in `source/tests/*.jsonl`). Then it holds new
|
||||
messages, stops the old version, starts the new one, and delivers the held
|
||||
messages. A new version that crashes 3 times in 30 seconds is rolled back.
|
||||
|
||||
See [DECISIONS.md](DECISIONS.md) for every design decision and
|
||||
[SPIKE.md](SPIKE.md) for the spike results.
|
||||
Reference in New Issue
Block a user