# klbr

klbr is one continuous agent runtime. Rust owns durable state, scheduling, provider/effect
execution, limits, recovery, and Python worker supervision. Python owns normal skills and
behavior policy. The browser uses one versioned lane protocol.

## active path

- `klbr-daemon`: service composition, scheduling, HTTP/WebSocket server, operator CLI
- `klbr-runtime`: SQLite runtime store, kernels, effects, releases, remote execution
- `klbr-core`: provider adapter, request/context contracts, configuration
- `klbr-ipc`: v2 client/server wire values and cursor logic
- `klbr-discord`: Twilight transport adapter feeding the runtime ingress boundary
- `python/klbr-runtime`: persistent workbench, hooks, and the `klbr` Python SDK
- `klbr-web`: bundled Svelte lane client
- `klbr-tui`: native Rust terminal client of the same v2 daemon

There is no legacy runtime mode, legacy memory database, Rust model-tool registry, benchmark
crate, or v1 client protocol in the normal source tree.

## run from source

These argv commands work from Nushell:

```text
bun run --cwd klbr-web build
cargo run -p klbr-daemon --bin klbr-daemon -- doctor
cargo run -p klbr-daemon --bin klbr-daemon -- serve
```

Open `http://127.0.0.1:8765/`. Set `KLBR_CONFIG` for the primary model and
`KLBR_DATA_DIR` for durable state. See [DOGFOOD.md](DOGFOOD.md) for paths and operator
commands. Source dogfooding is the current path; Nix packaging is deferred.

## native terminal

Start the daemon above, then in another terminal:

```text
cargo run -p klbr-tui -- --session default
```

The terminal keeps the transcript, live activity and composer separate. Prompts appear
immediately; scratchpad, executed Python output and confirmed speech retain their own
labels. `esc` interrupts the turn; `ctrl+c` or `/q` detaches without stopping the daemon.
Wheel or page keys scroll history, `ctrl+end` follows live output, `/t` toggles scratchpad,
`/v` expands cells and diffs, and `/sessions` opens the session picker. Paste is a draft,
never an automatic submission. Use `shift+enter`, `alt+enter` or `ctrl+j` for a newline;
the multiline draft stays in one horizontal composing row. `/` opens completion,
`tab` completes, and `esc` dismisses the menu before interrupting a turn.

`--url ws://127.0.0.1:8765/ws` selects the daemon. Reconnect resumes durable history;
unconfirmed input is **not** resent. `/retry` explicitly retries it with the original
admission id. Client drafts survive session switching, not client exit.

Generation uses niri’s transient action row: inferred reading/writing/editing labels
follow the latest recognized Python statement, alongside the fill/clear/continue code
preview. Unknown or dynamic paths keep a generic label. This is not a claim
that an edit has run. Completed workspace-helper reads/lists/searches and file edits
produce bounded, durable per-cell receipts, including edits before a later exception.
Diffs cover `File.write`, `replace` and `edit`; arbitrary Python, shell writes and
recursive deletion are not watched or inferred. Binary/large diffs are marked unavailable.

See [the source transfer map](klbr-tui/PARITY.md) for tests and explicit v2 API adaptations.
A provider that sends complete tool arguments in one chunk cannot show live typing;
the client does not manufacture it by replaying already-completed code.

Live durable records and reconnect replay both come from Store in sequence; change
notifications only wake the reader. Cell `starting`/`arguments` chunks are transient
generation metadata, not execution results. Trace fields are optional, so older workers
remain readable without inventing missing activity or diffs.

## invariants

- runtime Store is the only normal history/work owner
- admitted input commits before acknowledgement or execution
- one Python tool is model-visible; host effects remain typed
- output is diagnostic unless an explicit delivery operation confirms speech
- operator stop/reset/drain/activation never depend on model cooperation
- model, kernel, context, behavior, and service generations are distinct
- failed or unknown effects remain durable facts; they are never rewritten as success