# 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. ## Architecture - **(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. ## Messages - **(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 `"/"`, so IDs cannot collide or be faked. Without an `id`, the broker assigns `m-`. - **(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. ## Filesystem - **(you)** `/data` private, `/public` own public files, `/actor//public` and `/actor//source` read-only for everyone. - **(spike)** The broker also writes `/actor//status.json` and `/actor//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. ## 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///`, 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//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)** `@ `, 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.