Trim the harness to what it needs to keep going
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.
This commit is contained in:
+44
-145
@@ -1,154 +1,53 @@
|
||||
# Decisions
|
||||
|
||||
This file lists the design decisions of the spike. **(you)** marks a decision
|
||||
that Surma made. **(spike)** marks a decision that Scout made alone during the
|
||||
night and that needs review.
|
||||
Why Sausage is the way it is. `PROTOCOL.md` and the code own the details;
|
||||
when this file disagrees with them, they win.
|
||||
|
||||
## Architecture
|
||||
## The shape
|
||||
|
||||
- **(you)** Actors are WASI commands (`wasm32-wasip2`). They use stdin, stdout,
|
||||
files, and HTTP. No WIT interfaces, no component composition.
|
||||
- **(you)** Actors exchange newline-delimited JSON through the host, which is
|
||||
the broker. No built-in request/response. A reply is a message with
|
||||
`reply_to`. Delivery is at most once.
|
||||
- **(you)** The broker accepts only `.wasm` files. It knows no source language.
|
||||
- **(you)** `cargo` is a built-in Rust compiler actor. **(spike)** It is native
|
||||
(host code), because cargo cannot run inside WASM.
|
||||
- **(you)** The agent is a normal WASM actor with the fixed ID `agent`. It can
|
||||
read and upgrade its own source.
|
||||
- **(spike)** Three native actors: `broker`, `console`, `cargo`.
|
||||
- **(you)** One Cargo workspace with two crates: `cli` (binary `sausage`) and
|
||||
`agent`. **(spike)** Example actors are in `examples/`, outside the workspace.
|
||||
- **(you)** `sausage init` builds the agent and asks for the API shape, the
|
||||
endpoint, the model, and the token. **(spike)** The token can also come from
|
||||
`SAUSAGE_API_TOKEN`. The source contains no endpoint and no token.
|
||||
- **Actors are WASI commands, not components with interfaces.** stdin,
|
||||
stdout, files, and HTTP are enough, and every language can do them.
|
||||
- **Messages are JSON lines through a broker, fire and forget.** Like
|
||||
Erlang: no acknowledgments, no request/response. A reply is a message with
|
||||
`reply_to`. Sausage is not a reliable message bus.
|
||||
- **The broker accepts only `.wasm` files.** It knows no source language.
|
||||
`cargo` is one compiler actor; others can add more languages.
|
||||
- **The world folder is the source of truth.** Everything about an actor is
|
||||
in `actor/<id>/`. Copy a folder into another world, and it runs there.
|
||||
- **The agent is a normal WASM actor.** It can read and upgrade its own
|
||||
source, and change how it does inference.
|
||||
|
||||
## Messages
|
||||
## Minimal on purpose
|
||||
|
||||
- **(spike)** Stdin line: `{"id", "from", "reply_to"?, "body"}`.
|
||||
Stdout line: `{"to"?, "id"?, "reply_to"?, "body"}`.
|
||||
- **(spike)** The broker sets `from`. An actor can choose its own `id`. The
|
||||
broker then uses `"<sender>/<id>"`, so IDs cannot collide or be faked.
|
||||
Without an `id`, the broker assigns `m-<n>`.
|
||||
- **(you)** Without `to`, a message goes to the subscribers of the sender.
|
||||
**(spike)** `subscribe` / `unsubscribe` messages to the broker. The registry
|
||||
stores subscriptions, so they survive restarts and upgrades. `init`
|
||||
subscribes `console` to `agent`.
|
||||
- **(spike)** Errors from routing come back as
|
||||
`{"type": "undeliverable", "reason", "to"}` from `broker`.
|
||||
- **(spike)** Lifecycle: `{"type": "shutdown"}` from `broker`, then EOF on stdin.
|
||||
After 5 seconds the broker kills the instance.
|
||||
- **(spike)** Lines on stdout that are not JSON objects with `body` go to the
|
||||
actor's `stderr.log` with a note.
|
||||
The harness does only what it needs to keep going. Everything else can be an
|
||||
actor, or a change that the agent makes to itself.
|
||||
|
||||
## Filesystem
|
||||
- **The host is not self-modifiable; actors are.** So the host keeps only
|
||||
what an actor cannot do for itself: routing, running instances, versions,
|
||||
tests before an install, and the rollback of a version that crash-loops.
|
||||
Without that rollback, a broken self-upgrade would end the agent.
|
||||
- **No permissions, no limits, no hiding.** Any actor can message, upgrade,
|
||||
or stop any actor, read every folder, and use HTTP. People who want rules
|
||||
can build them.
|
||||
- **No re-delivery and no state snapshots.** A crash loses the message, and
|
||||
all versions of an actor share `data/` and `public/`. A rollback restores
|
||||
code, not data.
|
||||
- **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.
|
||||
|
||||
- **(you)** `/data` private, `/public` own public files,
|
||||
`/actor/<id>/public` and `/actor/<id>/source` read-only for everyone.
|
||||
- **(spike)** The broker also writes `/actor/<id>/status.json` and
|
||||
`/actor/<id>/stderr.log`. `ls /actor` is the registry.
|
||||
- **(you)** Commit on close: a write becomes visible only when the writer
|
||||
closes the file. **(spike)** This also applies to `/data`. Implementation: a
|
||||
wrapper around the `wasmtime-wasi` filesystem. An open for write goes to a
|
||||
hidden `.sausage-tmp-*` file next to the target. The descriptor drop renames
|
||||
it into place. Details:
|
||||
- A normal exit commits every open file (process exit closes files).
|
||||
- A trap or kill discards uncommitted writes.
|
||||
- An append or an edit without truncate copies the old content first.
|
||||
- Other descriptors see the old content until the close.
|
||||
- Directory operations take effect immediately.
|
||||
- The layer hides `.sausage-tmp-*` names from listings, `stat`, `open`,
|
||||
`rename`, and `unlink`.
|
||||
- Symlinks are disabled (they would break the path tracking).
|
||||
- No `fsync`. A power loss can lose committed data.
|
||||
- **(spike)** Raw sockets are not available (no network permission), but the
|
||||
`wasi:sockets` interfaces are linked, so programs that import them still
|
||||
start.
|
||||
## Small choices
|
||||
|
||||
## Broker requests
|
||||
|
||||
- **(spike)** `spawn`, `upgrade`, `rollback`, `stop`, `start`, `remove`,
|
||||
`subscribe`, `unsubscribe`, `list`.
|
||||
- **(you)** `spawn` and `upgrade` take `wasm`, plus optional `source` and
|
||||
`built_by` metadata. **(spike)** The broker copies the `.wasm` file and the
|
||||
source folder into `broker/versions/<id>/<n>/`, with `meta.json` (paths,
|
||||
builder, requester, time).
|
||||
- **(spike)** Path resolution: `/actor/...` is global, and `/public/...` and
|
||||
`/data/...` belong to the sender. `..` is rejected. Native senders (the
|
||||
console) can give absolute host paths.
|
||||
- **(you)** Anyone can upgrade anyone. No permissions.
|
||||
- **(spike)** Actor IDs: `a-z`, `0-9`, `-`, `_`, at most 64 characters.
|
||||
- **(spike)** `remove` archives every folder of the actor to `archive/`. Nothing
|
||||
is deleted.
|
||||
|
||||
## Upgrades, tests, rollback
|
||||
|
||||
- **(spike)** The tests are message transcripts in `source/tests/*.jsonl`:
|
||||
`{"send": body}` and `{"expect": subset-of-body, "to"?}`. Each file runs in
|
||||
a fresh candidate on a copy of the actor's `/data` and `/public`. The
|
||||
candidate has no HTTP access. An `expect` waits up to 10 s. Without tests,
|
||||
the candidate must stay up for 2 s (smoke test).
|
||||
- **(spike)** Swap: hold the mailbox, stop the old instance gracefully,
|
||||
snapshot `/data` + `/public` into the old version's folder, install the new
|
||||
source in `/actor/<id>/source`, start the new instance, release the mailbox.
|
||||
- **(spike)** Restart after a crash: backoff 0.5 s × 2ⁿ, at most 30 s. The
|
||||
counter resets after 60 s of uptime.
|
||||
- **(spike)** Parked message: when an instance traps, the broker keeps the
|
||||
last delivered message. It delivers that message again after the next
|
||||
upgrade, not after a plain restart (that would loop).
|
||||
- **(spike)** Crash loop: 3 crashes within 30 s after an upgrade → automatic
|
||||
rollback to the previous version, with its data snapshot. The broker
|
||||
informs the actor that requested the upgrade.
|
||||
- **(spike)** `rollback` without `version` goes to the highest older version.
|
||||
It restores that version's snapshot, and it first snapshots the current
|
||||
state, so a roll-forward is possible.
|
||||
- **(spike)** Versions are per actor, not global.
|
||||
|
||||
## Limits
|
||||
|
||||
- **(spike)** Mailbox: 1,000 messages. When it is full, the sender gets
|
||||
`undeliverable`.
|
||||
- **(spike)** The broker waits 30 s when it writes to an actor's stdin. Then it
|
||||
drops the message and logs it.
|
||||
- **(spike)** Time slices: the epoch advances every 10 ms, and each guest
|
||||
yields at each epoch.
|
||||
- **(spike)** One `sausage run` per world (file lock on `world/.lock`).
|
||||
- **(spike)** HTTP for all running actors, with no allow-list yet.
|
||||
|
||||
## Agent
|
||||
|
||||
- **(you)** API shapes: OpenAI Responses and Anthropic Messages, chosen by
|
||||
`"api"` in `/data/config.json`.
|
||||
- **(spike)** Config fields: `api`, `base_url`, `model`, `token`, optional
|
||||
`reasoning_effort` and `max_tokens` (16,000). OpenAI: `POST
|
||||
{base_url}/v1/responses` with `store: false` and encrypted reasoning passed
|
||||
back. Anthropic: `POST {base_url}/v1/messages` with `x-api-key`.
|
||||
- **(spike)** One shared conversation in `/data/history.json`, in a neutral
|
||||
format, so the API shape can change. The history is limited to 600 entries,
|
||||
with the cut at a user message. There is no compaction yet.
|
||||
- **(spike)** A turn starts only for `{"type": "text"}` messages *without*
|
||||
`reply_to`. Replies never start turns, so two actors cannot keep the agent
|
||||
in an endless loop. Other messages are collected and shown at the next
|
||||
turn.
|
||||
- **(spike)** Tools: `send_message` (with optional wait for the reply),
|
||||
`wait_for_messages`, `read_file`, `list_dir`, `write_file`, `copy_dir`,
|
||||
`remove_path`. At most 40 steps per turn. Tool output is cut at 30 KB.
|
||||
- **(spike)** The final text of a turn goes to the sender, as a reply to the
|
||||
message that started the turn.
|
||||
- **(spike)** A shutdown during a turn saves the turn to `/data/turn.json`. The
|
||||
next start (for example after a self-upgrade) resumes the turn and answers
|
||||
the original message.
|
||||
|
||||
## Console
|
||||
|
||||
- **(spike)** `@<actor> <json|text>`, plain text to `agent`, `/deploy`,
|
||||
`/list`, `/sleep`, `/await`, `/help`, `/quit`. `/sleep` and `/await` exist
|
||||
for scripted tests.
|
||||
|
||||
## Known risks (accepted for now)
|
||||
|
||||
- Build scripts and proc macros run as native code in the host environment.
|
||||
- Any actor can upgrade the agent with code that reads the token.
|
||||
- Any actor can message, stop, upgrade, or remove any actor.
|
||||
- A full copy of `/data` and `/public` at every upgrade is slow for large data.
|
||||
- Mailboxes are in memory. A host crash loses queued messages.
|
||||
- **Commit on close** for new and truncated files, so readers never see half
|
||||
a file, in any language. Appends write in place, so logs stay cheap.
|
||||
- **Test first, then switch.** A new version is tested where it lies. Only
|
||||
a version that passes goes to `versions/`, and the old one runs until
|
||||
then. `versions/` keeps every version that was installed, so a rollback
|
||||
can always go back. A file that fails stays where it was put.
|
||||
- **Tests are JSON transcripts** next to the source. They run on a copy of
|
||||
the actor's state, without HTTP, so a test cannot send real requests.
|
||||
- **`broker` and `cargo` never answer a reply,** so no two actors answer
|
||||
each other forever. The agent starts a turn only for text that is not a
|
||||
reply, for the same reason.
|
||||
- **The SDK is not published.** `cargo` points `sausage-actor = "0.1"` at its
|
||||
own copy, which it also shows in `/actor/cargo/public/sdk/`.
|
||||
|
||||
Reference in New Issue
Block a user