diff --git a/CLAUDE.md b/CLAUDE.md index 6f32876..d099ba7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,8 +5,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Current state Boxmaker is a sovereign personal agent harness written in Rust. There is no Rust code yet. Work -proceeds one milestone per session (M0 to M7, table in `docs/milestones.md`). M0 is mostly done; -check for `AGENTS.md` and `Cargo.toml` to see whether M1 has started. +proceeds one milestone per session (M0 to M7, table in `docs/milestones.md`). M0 is done; check for `AGENTS.md` and `Cargo.toml` to see whether M1 has started. - `docs/design.md` is the binding design brief. If it looks wrong or conflicts with a measurement, stop and say so. Changes to it land as their own commit and are recorded in `docs/decisions.md`, @@ -25,9 +24,10 @@ requests, check `GET /slots?model=ornith-1.5-35b-a3b` so you do not evict someon ## Commands (planned in M1, not yet present) -- `make gate` runs `cargo fmt --check`, clippy with warnings denied, `cargo test`, `cargo-deny`, - and a check that fails on any source file over 500 lines. Run it before calling any work done, - and report the exit status and last lines. +- `make gate` runs offline: `cargo fmt --check`, clippy with warnings denied, `cargo test`, + `cargo-deny`, and a check that fails on any source file over 500 lines. Run it before calling + any work done, and report the exit status and last lines. +- `make verify-device` runs the checks that need straylight, such as the baseline token budget. - Single test: `cargo test -p `. - `bxctl` is the owner CLI (`bxctl chat` from M2, `bxctl reindex` from M5). @@ -42,15 +42,16 @@ Separate binaries in one Cargo workspace. Each role holds as little authority as JSONL audit log. - `gatewayd` is the Mattermost channel. Outbound only, no listening port; approvals arrive as replies or reactions over the WebSocket. -- `inferproxy` is a ~100-line byte forwarder to `llama-server`. Drop it if M0 shows - `llama-server` can serve a Unix socket on the same host. +- `inferproxy` is a ~100-line byte forwarder from a Unix socket to the shared `llama-server` + router on the host. It is required, because `loopd` has no network. - `proto` holds shared types. `toolkit` holds tool container entrypoints. Structural rules that span crates: - No crate depends on another role's crate. Crates depend only on `proto`. -- Authority is encoded in types. A tool can't run without a `Decision`, and only `brokerd`'s - policy module can construct one (covered by a compile-fail test). +- Authority is encoded in types. A tool can't run without a `Decision`. It is defined in + `brokerd` with a private field and no `Deserialize`, so only the policy module can construct + one (covered by a compile-fail test). `proto` carries a plain `DecisionRecord`. - No source file over 500 lines. - Files are the source of truth (`sessions/`, `memory/`, `grants/`, `audit/`). SQLite is only for rebuildable indexes and queues. @@ -63,14 +64,20 @@ its KV cache, so any change to an earlier byte of the prompt forces an expensive - Each turn's request must be a strict extension of the previous one. Volatile content (time, heartbeat notes, memory refreshes, recalled memory) goes only in the newest message, never in the system prompt or earlier history. +- Assistant messages are logged and replayed exactly as the server returned them, including + `reasoning_content` and `tool_calls`. +- The `tools` array is fixed per epoch; changing it re-reads the whole prompt. Other tools are + found with `find_tool` and called through the `call_tool` meta-tool. Never prompt the model to + call an undeclared tool: the server's grammar forces the call into a declared one. - Tool results are size-capped when first appended and never trimmed later. - The baseline (system prompt, tool schemas, `memory/core.md`) stays at 3,000 tokens or less, - measured with the server's tokenizer. Extra tool schemas are added through `find_tool`, not - put in the baseline. + measured with the server's tokenizer. - Compaction happens only when the session is idle, and starts a new epoch (`sessions//.jsonl`). Old logs are kept. -- Main session, subagents and scheduled jobs each use their own server slot. -- Streaming always. Timeouts are "no bytes for N seconds", never total deadlines. +- Every request carries `id_slot`, and a session never changes slot. The server is shared, so + slots are not reserved: a cold cache is a normal event that `loopd` logs, never an error. +- Streaming always, with `return_progress: true`. Timeouts are "no bytes for N seconds", never + total deadlines, plus a longer limit for waiting on a busy slot or a model load. ## Working rules from the brief diff --git a/docs/decisions.md b/docs/decisions.md index 726aec7..006347b 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -18,6 +18,7 @@ Newest first. A decision that changes `docs/design.md` lands in the same commit |---|---| | Secret store backend, and where the v0 file's key lives. straylight has no secrets manager today. | M3 | | Whether cloud-led sessions are ever allowed, and for which data classes. | M6 | +| Where the M5b embedding model runs. The brief says a separate `llama-server` instance, but under the shared router it would be a third model against `--models-max 2` and could unload Ornith or Laguna. | M5b | ## Applied to the design brief @@ -40,7 +41,4 @@ Approved by the owner on 2026-09-17. One commit each. ## Proposed changes to the design brief -From M0 and the kickoff review. None is applied yet. Each lands as its own commit once the owner agrees. - -| # | Change | Evidence | -|---|---|---| +None pending.