kyle/boxmaker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Brief: add a one-sentence purpose for every role and crate

Browse Source 
Requested by the owner so that future readers, agents included, learn
what each piece is for first. No behaviour changes.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
kyle
2026-09-17 13:00:21 -07:00
co-authored by Claude Fable 5.1
parent 7bff156d7e
commit a49db39b54
2 changed files with 21 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design.md
+15 -9
View File
@@ -44,13 +44,13 @@ cloud-led orchestration as the default, in-process third-party code of any kind.
## Roles (separate binaries, narrow interfaces)
| Role | Holds | Can reach | Never holds |
|---|---|---|---|
| `gatewayd` | Mattermost bot token, allowlist, message queue | Mattermost server (outbound only), `loopd` socket | Tool secrets, grants |
| `loopd` | Session logs, prompt assembly, memory files | Three Unix sockets: `gatewayd`, `brokerd`, `inferproxy` | Any credential, any network interface |
| `inferproxy` | The `llama-server` address | `llama-server` only | Anything else; it forwards bytes and logs nothing |
| `brokerd` | Grants (read-only), secrets, audit log | Container runtime, `gatewayd` socket (for approvals) | Conversation history |
| tool containers | Only what one call was granted | Only what one call was granted | Anything persistent |
| Role | Purpose | Holds | Can reach | Never holds |
|---|---|---|---|---|
| `gatewayd` | Carries messages between the owner's Mattermost and the harness. | Mattermost bot token, allowlist, message queue | Mattermost server (outbound only), `loopd` socket | Tool secrets, grants |
| `loopd` | Runs the conversation: builds each prompt, calls the model, and asks `brokerd` for every tool call. | Session logs, prompt assembly, memory files | Three Unix sockets: `gatewayd`, `brokerd`, `inferproxy` | Any credential, any network interface |
| `inferproxy` | Lets `loopd` reach the model without having a network. | The `llama-server` address | `llama-server` only | Anything else; it forwards bytes and logs nothing |
| `brokerd` | Decides whether each tool call may run, runs it in a fresh container, and records the decision. | Grants (read-only), secrets, audit log | Container runtime, `gatewayd` socket (for approvals) | Conversation history |
| tool containers | Do one approved tool call and then cease to exist. | Only what one call was granted | Only what one call was granted | Anything persistent |
v0 runs all roles on one host. The interfaces must not assume co-location with `llama-server`.
@@ -211,8 +211,14 @@ Files are the source of truth. SQLite is allowed only for rebuildable indexes an
## Code constraints
- Rust stable, Cargo workspace. Crates: `proto` (shared types), `loopd`, `brokerd`, `gatewayd`,
`inferproxy`, `toolkit` (tool container entrypoints), `bxctl` (owner CLI).
- Rust stable, Cargo workspace. One crate per role in the table above (`loopd`, `brokerd`,
`gatewayd`, `inferproxy`), plus three that are not roles:
| Crate | Purpose |
|---|---|
| `proto` | Defines the data every role shares and the frame format they exchange it in. |
| `toolkit` | Holds the programs that run inside tool containers. |
| `bxctl` | Is the owner's command line: chat, local approvals, checks and maintenance. |
- No source file over 500 lines. No crate depends on another role's crate, only on `proto`.
- Authority is encoded in types: a tool cannot execute without a `Decision` value that only
`brokerd`'s policy module can construct. `Decision` is defined in `brokerd`, has a private