From b78deaa2ff2f637322bb70966dfd943a72e79827 Mon Sep 17 00:00:00 2001 From: Aubrey Keus Date: Wed, 16 Sep 2026 16:00:21 -0400 Subject: [PATCH] Reorganize documentation and align guides with current behavior --- README.md | 257 ++++------------------------------- docs/demo.md | 10 +- docs/development.md | 66 +++++++++ docs/interface.md | 250 ++++++++++++++-------------------- docs/phase-0-rpc-protocol.md | 221 ++++++++++++++++-------------- docs/security.md | 57 ++++++++ docs/setup.md | 197 ++++++++++++++++++++------- docs/testing.md | 16 ++- docs/ui-ux-redesign.md | 8 +- 9 files changed, 532 insertions(+), 550 deletions(-) create mode 100644 docs/development.md create mode 100644 docs/security.md diff --git a/README.md b/README.md index 6ec90be..7b9feb3 100644 --- a/README.md +++ b/README.md @@ -1,247 +1,40 @@ # bravebot-ui -A macOS interface to `bravebot` — the prompt-injection-resistant coding agent — in -a window instead of a terminal. +A macOS desktop interface to [bravebot](https://github.com/brave/bravebot), the +prompt-injection-resistant coding agent. Built with Electron, React and a Rust bridge, +it uses the agent as a pinned dependency without modifying its sources. -The app does not drive a terminal and does not parse one. It talks to a small Rust library -in this repository, `bravebot-bridge`, which depends on the agent as an ordinary Cargo -dependency and exposes it as a protocol. The agent itself is **never modified**: zero -files, zero new crates, zero refactors. That is a hard constraint on the design, not an -aspiration. +The app shares saved sessions under `~/.bravebot` with the terminal client. It adds +conversation search, drafts and queues, file previews, approval controls, export, +and persistent bots with conversation histories and project memory. -Sessions are the same sessions. The bridge reads and writes the records under `~/.bravebot` -that the terminal client uses, so a session begun in the app resumes with `bravebot --resume`, -and one begun in a terminal shows up in the app. +## Quick start -## Why a subprocess - -The agent runs as a child process (`bravebot-rpc`) speaking newline-delimited JSON, rather than -being linked into Electron as a native addon. The deciding reason is the security model: -across a pipe, "the interface died" *is* a closed pipe, which the protocol already defines -as a refusal — it follows from the shape of the thing rather than from code remembering to -handle it. In-process, a renderer crash and an agent crash are one event, and there is no -surviving side left to refuse anything. - -The full argument, and the alternative that was rejected, is in -[`docs/phase-0-rpc-protocol.md`](docs/phase-0-rpc-protocol.md) §1.1. - - -## What it does - -Three columns, each side one resizable and foldable — **Sessions** (everything under -`~/.bravebot/sessions`, with a second tab for bots), **Transcript**, and **Context** (the -plan, files read, writes, anything quarantined, and a file tree of the working folder). - -Five kinds of question are put in the transcript and answered there: a **write** (as a -diff), a **command** to run (as the argv), whether the planner may **read what a command -printed**, whether to **vouch** for a quarantined path, and a **series of questions** the -planner wants to put to you. The turn blocks until one is answered, and every failure to -answer — a closed window, a crash, a dropped pipe — is a refusal. - -Beyond that: **forking** a conversation in front of one of your own prompts; **export** to -text, Markdown or a PDF drawn by the same React components as the window; **bots**, which -are named persistent agents with a purpose, a memory and a face, each pinned to one -checkout; twenty-two **themes** plus any palette you write into `themes/`; and a menu that -writes down every key. - -The long version — every panel, the fork rules, how a bot's purpose and memory work, the -key table, the directory layout, what is remembered across launches, and the palette format -— is in [`docs/interface.md`](docs/interface.md). - -## Prerequisites - -- **macOS.** The window uses `hiddenInset` traffic lights and `sidebar` vibrancy. -- **Rust 1.88+** (`edition = "2024"`). This matches the agent's own floor; building against - its crates with an older toolchain fails in *its* sources, which is a confusing place to - discover a version problem. `rust-toolchain.toml` selects stable Rust for this checkout - when using rustup; run `rustup update stable` if your installed stable toolchain is older. -- **Node 22+** and npm — though CI builds on Node 24, so that is the version a change is - actually proved against. Electron 44, React 19. -- **The agent, as the `vendor/bravebot` submodule.** - [`brave/bravebot`](https://github.com/brave/bravebot.git), pinned - to a revision by the gitlink this repository commits. `crates/bravebot-bridge` depends on - it by path, so a clone without submodules compiles nothing. Moving the pin, and why it is - pinned at all, is in [`docs/setup.md`](docs/setup.md). -- **`direnv`**, to pick up the agent's credentials at build time. See below. - -## Setup - -One checkout, with the agent inside it. `--recurse-submodules` is not optional: without it -`vendor/bravebot` is an empty directory and the bridge does not build. +Install macOS development tools, current stable Rust, and Node 22.12+ with npm +(Node 24 is used in CI). See [setup](docs/setup.md) for prerequisites and credentials. ```bash git clone --recurse-submodules https://github.com/brave-experiments/brave-bot-ui.git cd brave-bot-ui -npm install +npm ci npm run dev ``` -Already cloned without it? `git submodule update --init`. - -`npm install` also downloads the Electron runtime using Electron's own installer. -Electron 44 installs the npm package without downloading that runtime automatically; -`electron-vite` needs it before launching. If an earlier install left you with -`Error: Electron uninstall`, run `npm run setup:electron`, then `npm start`. -Development and preview commands also run this setup, which reuses an installed runtime. -If downloads fail, check the installer output and retry the setup command. -`ELECTRON_SKIP_BINARY_DOWNLOAD=1` skips runtime setup for typecheck-only CI; unset it -before launching the app. With `--ignore-scripts`, run `npm run setup:electron` manually. - -`npm run dev` builds `bravebot-rpc`, names the development app for the menu bar, and then -starts the app with hot reload. - -(The repository is `brave-bot-ui`; the npm package, the bundle identifier and most prose -here say `bravebot-ui`. The agent's own repository is `brave-bot` and its binary is -`bravebot`. Both spellings are load-bearing where they appear.) - -## Credentials - -`bravebot` captures its backend credentials at **compile** time (its -`crates/config/build.rs`). That is deliberate: a release binary is built where the secrets -are and used anywhere, so it does not demand them again from every directory it starts in. - -This matters more for a window than for a terminal. `bravebot` is run from a shell that -usually has `direnv` loaded, so an unconfigured binary still finds what it needs in the -environment. An app launched from Finder has no such environment, and an unconfigured build -fails at the first inference request with `SERVICES_KEY_AICHAT is not set and was not built -in`. - -So `scripts/build-bridge.sh` builds *through* `direnv`, and says plainly what will happen -when it cannot. It takes a shorter route when the variables are already in its own -environment, and that is the arrangement to prefer — the values in one file outside every -checkout, and a `.envrc` here that reads them: - -```bash -mkdir -p ~/.config/bravebot -$EDITOR ~/.config/bravebot/env # NAME=value lines, one per variable -chmod 600 ~/.config/bravebot/env - -cd brave-bot-ui -echo 'dotenv_if_exists ~/.config/bravebot/env' > .envrc -direnv allow -``` - -The names are the ones the agent's `.envrc.example` *exports* — `SERVICES_KEY_AICHAT`, -`BRAVE_SERVICES_KEY_ID`, `BRAVE_AI_CHAT_ENDPOINT`, `BRAVE_AI_CHAT_DEFAULT_MODEL`, and -`BRAVE_AI_CHAT_PREMIUM_ENDPOINT` if you have one — rather than the `DEV_`/`PROD_` inputs its -`case` builds them from. The first three are required and the build fails without them; the -model name is not, and a build missing it quietly settles for `automatic`. - -Keeping them in `vendor/bravebot/.envrc` instead also works, and `BRAVEBOT_DIR` can point at -an older sibling checkout. [`docs/setup.md`](docs/setup.md) has the argument for preferring -the file outside every checkout. Either way `.envrc` and `~/.config/bravebot/env` are -per-machine and neither is a substitute for building a release with the credentials present. - -**Without credentials the app still starts, lists sessions and opens them — only inference -fails.** That degraded mode is intentional, so the interface can be developed without -secrets. `.cargo/config.toml` sets `BRAVEBOT_ALLOW_UNCONFIGURED_BUILD=1`, which opts -development builds into producing a binary that reads its credentials from the environment -at run time. A packaged release must not rely on it: it has to be built the way the agent's -own releases are, with the credentials present, or it will ship unable to reach the backend. - -## Development - -| Command | What it does | -| --- | --- | -| `npm run dev` | Build the bridge, name the app, run it with hot reload | -| `npm run bridge` | Build `bravebot-rpc` only, through `direnv` where it can | -| `npm run name-dev-app` | Name the development app "Brave Bot" in the menu bar | -| `npm run typecheck` | `tsc --noEmit` | -| `npm run build` | Bridge, typecheck, then bundle main + preload + renderer into `out/` | -| `npm start` | Preview a built bundle without rebuilding | -| `npm run package` | Build a `.app` into `dist/` | -| `npm run drive:*` | Drive the real window with Playwright — see [testing](docs/testing.md) | -| `npm run demo` | Walk the whole product at human speed; `--record` films it | -| `cargo test --all` | The Rust suites, the same command CI runs | - -TypeScript runs `strict`, plus `noUncheckedIndexedAccess`, `noUnusedLocals` and -`noUnusedParameters`; there is no eslint or prettier, and `tsc` is the whole gate on that -side. The Rust side is linted by `cargo clippy --all-targets --all-features -- -D warnings`. -Both, plus `cargo test --all`, are what CI runs on a pull request. - -The interface is tested by driving the real window, because the things worth asserting here -are the ones a screenshot cannot show — that a fold passes through intermediate heights -rather than snapping, that a column comes back at the width it left at, that a control keeps -keyboard focus through an animation. There are nineteen Electron drivers plus an RPC smoke test, and eight of these twenty checks -spend real tokens. [`docs/testing.md`](docs/testing.md) lists what each -one covers and what CI does and does not run. [`docs/demo.md`](docs/demo.md) covers -`npm run demo`, which performs rather than asserts and films itself. - -## Build and packaging - -```bash -npm run build # bridge, typecheck, bundle into out/ -npm start # preview that bundle -npm run package # bridge, bundle, then a .app into dist/ -``` - -`npm run build` is three steps in order: `scripts/build-bridge.sh` produces `bravebot-rpc`, -`tsc --noEmit` gates the types, and `electron-vite` bundles the main process, the preload -and the renderer into `out/`. - -`npm run package` runs the bridge build and the bundle — **not** the typecheck; run -`npm run typecheck` yourself first — and then `@electron/packager` builds -`dist/Brave Bot-darwin-/Brave Bot.app`. `bravebot-rpc` is copied in as a resource, -which is where `Bridge.binaryPath()` looks when `app.isPackaged`; the `target/debug` -fallback is development only, so packaging is the only way that branch is ever exercised. -Naming the bundle is also how the menu bar gets the right word: AppKit reads `CFBundleName` -before any of our code runs. - -A bundle built from a development checkout has no credentials, so it lands in the degraded -mode described above — now inside an app that cannot inherit an environment from a shell. -There is no signing or notarisation step either, so the bundle is for testing rather than -for giving to anybody. -## Security posture - -The app drives a tool whose whole point is that untrusted content cannot reach anything -that decides. A renderer with filesystem access would undo that from the outside, so: - -- The renderer gets **no Node, no remote origins, and no navigation**. `contextIsolation` - and `sandbox` are on, `nodeIntegration` and `webviewTag` are off, `will-navigate` is - refused outright, and a link opens in the user's browser. -- The preload exposes a handful of functions and one subscription. Nothing else. -- **The renderer never composes a filesystem path.** A project directory arrives from a - native picker or from a list the main process keeps; it is never a string the window made - up. The file tree keeps that promise for reading a folder too: it names a *session* and a - path relative to that session's directory, and the main process holds the roots — learned - from what the agent answered when the session was opened, forked or made. There is no - channel that accepts an absolute path, and a handle no session is running under lists - nothing. Two checks, not one: the lexical one (`shared/files.ts`) refuses `..` and anything - absolute before it becomes a syscall, and the main process then resolves the pair and - requires `realpath` to land inside the root's own `realpath` — so a symlink out of the - project is refused rather than followed. Nothing on that channel reads a file's - *contents*, only names and kinds, so it adds no route by which something the agent was - refused could reach the renderer anyway. -- The methods the renderer may call are an **allow-list** in the main process, not a - pass-through. A generic "send anything to the agent" channel would make the preload's - narrowness decorative. -- The bridge is a `Confirmer` implementation like any other, subject to the same rule as - every other one: **every failure resolves to refusal.** A closed pipe, a crashed - renderer, a malformed reply — all refuse. -- Confined content is labelled as confined wherever it appears, and the interface - distinguishes what the planner actually read from what it was only told the name of. -- An answer must be an answer to the question that was asked. Each of the five has its own - reply method, and the bridge checks the request id **and** the kind against what is - actually outstanding — so an approval cannot land on something nobody was shown. -- Answers to a series are held to the questions they answer: an index that names no choice - is dropped, a single-choice question never comes back with two, and a selection with - nothing left in it is a decline rather than an empty choice. -- A command's output reaches the window in full, because the person deciding whether the - planner may read it has to be reading it themselves. It is released for a screen and - stops there: approving is what puts it in the model's context, and that path runs - through the agent. - -## Further reading - -- [`docs/phase-0-rpc-protocol.md`](docs/phase-0-rpc-protocol.md) — the design document for - the bridge and its protocol: the message envelope (§4), every request (§7) and event (§8), - the trust model (§9), concurrency (§10), and what is deliberately out of scope (§11). -- [`docs/interface.md`](docs/interface.md) — the window: every panel, forking and export, - bots, keys, the directory layout, what is remembered, and themes. -- [`docs/setup.md`](docs/setup.md) — why the agent is a pinned submodule and why the - credentials live outside every checkout. -- [`docs/testing.md`](docs/testing.md) — the drivers, and what CI runs. -- [`docs/demo.md`](docs/demo.md) — recording a demo, and why nothing real is filmed. +The app can build and open without backend credentials. Sending prompts requires +[backend configuration](docs/setup.md#credentials); credentials from an existing +terminal installation are not automatically copied into a fresh checkout. + +## Documentation + +- [Setup](docs/setup.md): prerequisites, credentials, submodule updates and troubleshooting. +- [Development and packaging](docs/development.md): commands, builds and macOS bundles. +- [The interface](docs/interface.md): conversations, approvals, bots, memory, keys and themes. +- [Testing](docs/testing.md): regression checks, Electron drivers and CI coverage. +- [Security](docs/security.md): process boundaries, approvals and renderer restrictions. +- [File access and retention](docs/file-access-security.md): previews, attachments and memory storage. +- [Bridge protocol](docs/phase-0-rpc-protocol.md): transport, requests, events and design rationale. +- [Recording a demo](docs/demo.md): fixtures, live calls and recording controls. +- [Redesign audit](docs/ui-ux-redesign.md): historical implementation evidence and reproduction. ## Licence diff --git a/docs/demo.md b/docs/demo.md index 76e7e24..a8177e4 100644 --- a/docs/demo.md +++ b/docs/demo.md @@ -4,7 +4,7 @@ The [drivers](testing.md) assert; `npm run demo` performs. Same Playwright, same class names — but paced in beats rather than in milliseconds, and it films itself: ```bash -npm run demo -- --record # the whole product, no model calls, to a .mov +npm run demo -- --record # cached world: no new model calls; first run seeds it npm run demo -- --record --live # plus a real turn, an approval card, a question, # a bot at work — its face looking down at the page — # writing its own memory, and what it kept @@ -19,8 +19,9 @@ It needs Screen Recording permission for whatever is running it; without that th out empty and the run says so. The capture is then re-encoded, because the raw one is not a file anybody wants to be sent. -`screencapture` records at the display's own resolution and refresh rate — retina, at **120 -fps** — which is around 45 MB for three minutes of a mostly stationary window, and nothing in +`screencapture` records at the display's own resolution and refresh rate — retina at +120 fps on the display used for the original recording — which produced +around 45 MB for three minutes of a mostly stationary window, and nothing in its flag list changes that. So it is fixed afterwards: halved to logical resolution, dropped to 30 fps, and encoded at a CRF where the app's own text is still sharp at 1:1. That is about 4 MB for the same footage. `--width 0` keeps the retina resolution, `--crf` and `--fps` move the @@ -48,6 +49,9 @@ filmed. With both redirections the session list, the recents, the bots, the colu file tree are all the world's. `/Users/Shared` rather than the home directory because every path in it ends up on screen, and a home directory has somebody's name in it. +The projects under `scripts/demo/project/` are fictional demo fixtures; their READMEs +describe the sample world rather than this application's setup. + The world holds two invented checkouts — `harbour-lights` and `tide-tables`, copied out of `scripts/demo/project/` — the sessions the demo earned in them, two resident bots (`RESIDENT_BOTS`: one never spoken to, one with a session and a line in its memory file, so the bots scene has a diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..eb3468c --- /dev/null +++ b/docs/development.md @@ -0,0 +1,66 @@ +# Development and packaging + +Start with [setup](setup.md), then use these commands from the repository root. + +| Command | What it does | +| --- | --- | +| `npm ci` | Install locked npm dependencies and set up Electron | +| `npm run dev` | Set up Electron, build both Rust executables, start hot reload | +| `npm run bridge` | Build `bravebot-rpc` and `bravebot-ui-files`, loading credentials where configured | +| `npm run setup:electron` | Install the Electron runtime if needed and name the development app | +| `npm run name-dev-app` | Restore “Brave Bot” as the development app's menu-bar name | +| `npm run typecheck` | Run `tsc --noEmit` | +| `npm run build` | Build both Rust executables, typecheck, bundle into `out/` | +| `npm start` | Set up Electron and preview the existing bundle; does not rebuild it | +| `npm run package` | Build both Rust executables, bundle, package a macOS `.app`; does not typecheck | +| `cargo test --all` | Test the Rust workspace | +| `cargo clippy --all-targets --all-features -- -D warnings` | Lint the Rust workspace | +| `npm run drive` / `npm run drive:` | Run a named Electron driver; see [testing](testing.md) | +| `npm run demo -- --record` | Record a walkthrough; see [demo costs and setup](demo.md) | + +TypeScript uses strict checking, including `noUncheckedIndexedAccess`, +`noUnusedLocals` and `noUnusedParameters`. There is no ESLint or Prettier gate. +See [testing](testing.md#what-ci-runs) for exactly what CI checks and what must run locally. + +## Build and preview + +```bash +npm run build +npm start +``` + +`scripts/build-bridge.sh` builds the Rust bridge and secure-file helper. TypeScript +then checks the code and electron-vite bundles the main process, preload and React +renderer into `out/`. Development executables are in `target/debug/`. + +The bridge talks to the pinned agent library over a child-process protocol; it does +not drive a terminal. See the [protocol design](phase-0-rpc-protocol.md) and +[security boundaries](security.md). + +## Packaging + +```bash +npm run typecheck +npm run package +``` + +`npm run package` does not typecheck. It builds the Rust executables and Electron +bundles, then `scripts/package.mjs` uses `@electron/packager` to create +`dist/Brave Bot-darwin-/Brave Bot.app`. The architecture follows the Node +process (`arm64` or `x64`). Rust uses its configured toolchain target; for a native +bundle, use matching Node and Rust architectures. + +Both `bravebot-rpc` and `bravebot-ui-files` are copied into the app's Resources. +Packaged builds use those copies; development builds use `target/debug/`. +The script currently packages debug Rust executables, and performs no app signing +or notarisation. The resulting bundle is for local testing, not a completed +release-distribution pipeline. Git commit signatures are separate from macOS app signing. + +A development checkout can produce a configured or unconfigured binary depending +on the build environment. Follow [credentials](setup.md#credentials) before packaging +for inference; Finder does not load shell configuration. Packaging itself does not +check that backend credentials exist. + +To check the bundle, use the [packaged-app drivers](testing.md#current-regression-checks). +AppKit takes the menu-bar name from the bundle's `CFBundleName`; changing +`app.name` would also change Electron's user-data location. diff --git a/docs/interface.md b/docs/interface.md index 292c829..d33bf19 100644 --- a/docs/interface.md +++ b/docs/interface.md @@ -1,7 +1,7 @@ # The interface What the window shows and why it is shaped that way. The setup and build instructions -are in the [README](../README.md); the protocol underneath is in +are in [setup](setup.md) and [development](development.md); the protocol underneath is in [`phase-0-rpc-protocol.md`](phase-0-rpc-protocol.md). - [What it looks like](#what-it-looks-like) @@ -17,7 +17,8 @@ are in the [README](../README.md); the protocol underneath is in Three columns, each side one resizable and foldable: -- **Sessions** — everything under `~/.bravebot/sessions`, newest first, and a button to start a +- **Sessions** — saved conversations under `~/.bravebot/sessions`, with bot histories + accessed through the Bots tab, and a button to start a new one against any directory. A second tab beside it holds the **bots**: named, persistent agents with a purpose and a memory, each pinned to one checkout. See *Bots* below. - **Transcript** — the conversation, with the turn's tool calls gathered into runs that @@ -26,26 +27,35 @@ Three columns, each side one resizable and foldable: **command** to run (as the argv, plus the binary each name resolved to), whether the planner may **read what a command printed** (as the bytes in full), whether to **vouch** for a quarantined path, and a **series of questions** the planner wants to put to you — - choices to pick from, or your own words. The turn blocks until one is answered, and every - failure to answer — a closed window, a crash, a dropped pipe — is a refusal. For the last + choices to pick from, or your own words. The turn blocks until one is answered. + Window close and app shutdown refuse outstanding questions. For the last of the five that means *no answers at all* rather than a decline per question: a decline somebody made and a question that never reached them must not look alike. -- **Context** — what the session has touched: the plan, files read, writes and how far each - got, and anything quarantined. A row of connected buttons at the top of the column turns - each panel on and off; a panel that is off keeps everything it knew, including its fold and - which folders were open in its tree, so turning it back on does not undo any of that — and, last, the one panel that reads the disk rather than the - transcript: a **file tree** of the folder the session is working in. Directories list when - you open one rather than up front, dot-prefixed entries sit behind a toggle, each file - carries a two-letter badge for its type, and a box above the tree filters by name — which - searches what has been read and says so, since the tree is listed a folder at a time. A - double-click hands a file to whichever app the system assigns its type. It re-reads the - folder when a turn finishes, which is the moment its contents can have changed. - -The two side columns fold to nothing from a chevron at either end of the transcript's -header, and their widths and fold states survive a relaunch. - -The layers icon to the left of the message box opens the conversation's model picker. -Search by name, provider, or capability (for example, `vision` or `openrouter reasoning`), +- **Context** — an inspector with **Overview**, **Changes** and **Files** tabs. + Overview summarises the plan, reads and confined material; Changes distinguishes + pending decisions, approved writes and their actual execution outcomes. Files + provides a lazily loaded tree and project-wide filename search, including folders + not yet expanded. Text files can be previewed or opened in their default app. + On narrow windows the inspector opens as a drawer. + +The two side columns fold from controls in the transcript header, and their widths +and fold states survive a relaunch. Focus mode hides the sidebars; density can be +comfortable or compact. + +Drafts and reading positions survive conversation switches and restarts. A running +conversation can continue in the background. Drafting during a run does not send +anything: **Queue message** explicitly queues a follow-up. Stop or an error pauses +the queue; **Resume queue** is required to continue it. Automatic bot-memory +maintenance reserves the session until it finishes. + +Conversation actions include pin, archive and restore. **Find** searches the current +conversation. Code blocks offer copy and wrap controls; local file references can +open previews. **New activity** returns to the latest entries when new events arrive +while you are reading older ones. **Permissions** lists and revokes path and command +grants after the current turn stops. + +The model control in the composer opens the conversation's model picker. +Search by name, provider, or reported capability (for example, `text` or `tools`), then click a model or use the arrow keys and Enter. Escape closes the picker. New conversations use the agent's configured default when available; the default is also marked in the list. A choice applies to subsequent messages and is @@ -53,11 +63,11 @@ remembered locally for that conversation across app restarts. Forks inherit the choice. The picker is disabled while a turn is running. Available models come from the agent's configured backends, including OpenRouter. -Small badges beneath each gateway model show reported capabilities such as Text, Vision, -Tools, and Reasoning. Hover a badge for its meaning. Input and output capabilities are -distinguished: Vision means image understanding, while Images out means image generation. -These describe the provider's model; they do not enable new input or output types in this -app. Models without reported metadata have no badges. +Badges show the capabilities the app exposes: **Text** and **Tools**. The catalogue +may report other capabilities, but selecting such a model does not enable image, +audio or video input/output here. Context-window sizes are shown when available, +and recently chosen models appear near the top. Pricing is not supplied by the catalogue. + Refresh retries discovery if a provider is unavailable; the configured default remains selectable. Choosing a model does not change the agent's global default. @@ -84,11 +94,11 @@ A forked session says so in its header, with a link back to the session it came opens it at the prompt the cut was made in front of. The session list marks a fork beside its name. All three are the same mark — the control on a prompt, the banner, and the row — because they are the same idea. None of it can live in the agent's own record — that has no field for a -parent, and it is rewritten after every turn — so the lineage comes from a file this app keeps -beside the recents list, written by the main process from what the agent answered rather than +parent, and it is rewritten after every turn — so lineage is stored in the `forks` +key beside `recents` in `bravebot-ui.json`. The main process writes it from the agent's answer rather than from anything the window asked for. -An **Export** button sits beside Send, and File › Export offers the same three formats: +An **Export** button sits in the conversation header, and File › Export offers the same three formats: plain text, Markdown, or a PDF that keeps the window's own bubbles. What it writes by default is the *conversation* — what was asked and what came back — and never the diffs, approval cards or confined blobs. That is the same argument the per-entry Copy makes: those things are @@ -113,12 +123,17 @@ whole extra window. The left column has two lists. The **Sessions** tab is everything above; the **Bots** tab is the people who have one. -A bot is a name, a purpose somebody wrote, a memory it keeps, and one checkout it works in. Behind -it is a single session that is *resumed* rather than begun again — so where a session is an -occasion, a bot is somebody, and the tab holds the second because a list that answered both -questions would answer neither well. A bot's sessions do not appear in the sessions list: one -record openable from two places is one that could be open twice, each half of the window believing -it had the conversation. +A bot has a name, purpose, model choice, avatar, project and persistent memory. +Its overview lists its conversations and offers **Continue** and **New conversation**. +Starting a new conversation preserves earlier history; the bot's purpose and project +memory carry across conversations. Bot-associated conversations are accessed through +the bot rather than mixed into the ordinary conversation list. + +The editor keeps the project fixed. **Duplicate into another project** creates a +separate bot. The memory editor offers readable and raw views, explicit saves, +reset with confirmation, and revision history for review and restoration. Reset +preserves history; deleting a bot removes its app-owned history and cached briefing. +See [file retention](file-access-security.md) for what stays in the project. #### Archiving one @@ -148,9 +163,9 @@ question is asked *in the row* rather than in a dialog, for the reason the agent are asked in the transcript: a modal takes the thing being decided off the screen and replaces it with a sentence about it, and here the sentence needs the bot's name still beside it. -What it does is narrower than the word. Nothing is erased — the session stays in `~/.bravebot` -and the memory file stays in the checkout, exactly as they did under Forget. What goes is the -only thing that knew they belonged together, which is why it is final and why it asks. +Deletion removes the bot definition, cached briefing and app-owned memory revision +history. Saved conversations stay under `~/.bravebot`, and the project memory file +stays in the checkout. Deletion is refused while a bot conversation is running. Archiving changes nothing in the sessions tab. An archived bot still owns its session — that is what makes restoring it a restoration — so the conversation does not surface there while the bot @@ -164,89 +179,16 @@ Restore button would be saying something untrue. #### The face -Each bot has a face: a small three-dimensional figure, built with three.js from a seed minted when -the bot was made, turning slowly. The seed is *stored* rather than derived from the name, because a -face that changed when a bot was renamed would not be a face. - -The brief was friendly and approachable, and the figures take that literally — round, large-headed, -big low-set eyes with a white catchlight in each, and no mouth, because a fixed mouth is either a -grin that never fits what the bot just said or a line that reads as sullen. - -Each is painted in **one** colour from a fixed set, with its parts told apart by *shade* of it -rather than by a second hue: the head is the colour itself, the body a deeper version, and the small -pieces on top — an ear, a bobble, a collar — a paler one. So a bot is "the blue one" rather than -"the blue and yellow one", which is a thing somebody can hold in their head about eight bots at -once. The shades are far apart on purpose; one step of difference reads as a shadow rather than as a -different part, and the figure goes back to being one blob at 38 pixels. - -The set is primaries and near-primaries — the colours of moulded plastic — and it deliberately holds -**no orange and no brown**. They are muted rather than pure: each is its primary at roughly two -thirds of full saturation, pulled a little toward mid lightness. Fully saturated versions came -first and shouted — eight of them down a column, each small and each at maximum chroma, is a lot of -noise beside a list of quiet grey text, and the avatar ends up competing with the name it belongs -to. What is kept is the *hue*, which is the part doing the identifying: a bot is still recognisably -the blue one or the green one. `yellow` and `lime` are the pair that needs watching, since muting -moves everything toward grey and two hues 40° apart converge on the way — `lime` is pushed greener -and darker than a straight muting would give it, to keep the two apart at 38 pixels. These were first built in the window's own accent, on -the argument that every colour here means something and a bot picking a hue would say something it -did not mean; that turned out to be wrong in practice for a reason the argument could not see. The -accent is a warm orange, and a warm orange sphere with two eyes in it is not an abstract mark, it is -a *face* — the whole thing read as skin. A figure this simple is read as a body before it is read as -anything else, so the colour has to say "painted object" loudly enough to stop that, which a dusty -blue does and no shade of orange can. A single hue makes that rule stricter rather than -looser: there is no second colour to carry the signal if the first one fails to. - -The cost, stated plainly: the figures no longer follow a theme. A palette somebody writes repaints -the window and leaves the bots alone. That is the right trade for a face — one that changed colour -with the furniture would be a worse identity than one that does not — but it is a trade. - -What else differs between them is the head, what is on top of it, the ears, the set of the eyes, and -the body. - -Every piece has a thin drawn edge around it, in a dark version of its own colour, and the whole -figure sits on a faint neutral disc. Neither is decoration. The pale pieces — a bobble, an ear, a -collar — sit against the *page* rather than against the head, and on a light theme pale paint on an -off-white column was invisible: two of the six traits were being thrown away in light mode. The -edge gives them a line to be seen by on any background and separates an ear from the head it is -pressed against; the disc gives every avatar the same shape in the row and a surface behind it. The -lighting is mostly flat — a strong key on a saturated colour clips a channel and drains the hue — -with a hemisphere light to put the underside of the head into shadow so a sphere reads as a sphere -rather than a disc; the numbers are set so that a surface facing the camera renders at exactly the -paint's hex. - -Two things about it are load-bearing rather than decorative: - -- **One WebGL context, however many bots.** A page gets a limited number — Chromium's cap is around - sixteen, and past it the *oldest* context is dropped rather than the newest refused, so a long - list would silently blank the rows at the top. There is one renderer drawing into one offscreen - canvas, and each avatar is a plain 2D canvas the result is copied into. -- **The motion is a function of the clock, not of frames.** A figure turns at the same rate on a - busy machine as an idle one, a dropped frame is skipped rather than accumulated, and two avatars - mounted a minute apart are at the same point in the turn. Each one's offset into the cycle comes - from its seed — as does the rate of its bob — so a column of them does not move as a block. The - loop stops when nothing is on screen and when the window is hidden, and it draws at thirty frames - a second rather than sixty: at a twenty-four-second turn the difference is a fraction of a pixel - a frame, and half the frames is half the GPU for the same picture. - -The face also knows what its bot is doing, and shows it as posture rather than expression — what a -person shows across a room. A bot in the list looks slowly about; one that has never been spoken to -faces forward and only blinks; the one on screen looks at the reader and holds; one whose turn is -running looks down and a little aside, as at a page, and blinks more often; and one whose last turn -ended in an error tilts its head — "hm" — and lets it go over a few seconds. Coming out of a turn -that did not fail, it nods, once. None of that is a mouth or an eyebrow: an animated expression -beside a stack trace looks like the bot is apologising, and a posture does not. Two smaller things -sell the rest: the blink is lopsided and every fourth one is a double, which is the one aperiodic -thing in the motion; and whatever is on the head — a bobble, an aerial — is on a spring and lags -the head by a frame, which is follow-through, the oldest trick in animation. Under -`prefers-reduced-motion` the continuous motion stops; what is left is a still figure that blinks and -takes up its posture when its state changes. - -Where there is no WebGL to be had, the same seed draws the same face flat instead — head, body, the -two eyes and their catchlights, the same shades and the same drawn edge, read from the same traits — -so a bot is recognisably itself on a machine with no GPU. A list of bots with no faces is a worse -list, but a list that failed to draw its rows because of a graphics driver would be the tail wagging -the dog. See `src/renderer/avatar/` and -`src/renderer/components/BotAvatar.tsx`. +Each bot has a seed-based three-dimensional avatar rendered with three.js. Its stored +seed keeps the identity stable across renames. New avatars use versioned traits; +older seeds retain their original appearance. Avatar colours do not change with themes. + +The avatars share a WebGL renderer rather than allocating a context per bot. +A flat canvas fallback uses the same traits when WebGL is unavailable. Motion is +clock-based and deterministic: quiet pauses, brief glances and irregular blinks, +with posture changes for running and failed turns and a single completion nod. +Reduced-motion preferences suppress continuous movement. See +`src/renderer/avatar/` and `src/renderer/components/BotAvatar.tsx`. #### How a purpose reaches the model @@ -300,17 +242,14 @@ Two things close that, and neither of them attaches anything to an ordinary turn - **A compaction is answered with a turn of the app's own.** A rise in the archive is the one moment memory is unambiguously *for*, since it is the only thing that survived. Instead of waiting for - the next prompt to carry the briefing, the main process sends a turn saying so, grounded — which - is not an extra cost, because that prompt would have carried the briefing anyway. What it spends - is a round trip. + the next prompt to carry the briefing, the main process sends a turn saying so, grounded. This is an additional model request and can incur provider usage and cost. - **A bot that has stopped writing is grounded early.** A count on the bot rises each time one of its turns ends without its memory file's mtime moving, and at six the next turn carries the briefing whether the window thought it was due or not, with one extra paragraph asking whether anything since is worth keeping. It resets on the nudge as well as on a write, so a bot that ignores it gets six more turns of quiet rather than a briefing stapled to everything it is asked. -Both figures are main-written, like the session id and the archive watermark beside them: the form -can say four things about a bot, and when it is reminded to remember is not one of them. +Both figures are main-written, like the session id and the archive watermark beside them: the editor does not control when a bot is reminded to remember. Neither checks that the model wrote anything, because checking would mean parsing what it said, and the rule this feature is built on is that the change the agent applied is the record. The mtime is @@ -366,12 +305,15 @@ Two more things are honestly imperfect and worth knowing: #### What the window cannot do -`turn.send` takes two lists of file paths and admits both to the planner as trusted context. -Nothing else a renderer can say has that reach — the file tree is confined to roots the main -process learnt from the agent, the folder picker is native, and the preload has never carried a -file's contents in either direction. So the renderer may not name either list: they are stripped -from any `turn.send` arriving on the general channel, and a bot's turn goes through -`bravebot:bots:send`, which is handed a *bot* and composes the paths itself. +The bridge protocol accepts `files` and `dropped` paths, both admitted as trusted +context. The main process strips those raw lists from renderer requests. User +attachments instead use native-picker grants bound to the session and revalidated +when sending; bot briefings are composed by the main process from a bot definition. + +The preload does carry file contents for previews and memory editing. These are +bounded, explicit operations rather than unrestricted filesystem access, and previews +do not send contents to a model. See [security](security.md) and +[file access](file-access-security.md). ### The name in the menu bar @@ -385,7 +327,7 @@ It runs from `npm run dev` and from `postinstall`, because an `npm install` rest original. If the menu bar ever says "Electron" again, `npm run name-dev-app` puts it back. In a release there is no hack: `scripts/package.mjs` names the bundle `Brave Bot`, and AppKit -reads that. See [Build and packaging](../README.md#build-and-packaging). +reads that. See [packaging](development.md#packaging). ## Keys @@ -421,9 +363,8 @@ or moved is refused by the bridge with `not_a_directory` rather than failing qui folded group regardless — a heading with nothing under it is the opposite of what somebody who just typed a search asked for — and the fold is still there when the box is cleared. -Grouping and which groups are folded are both remembered between launches, in a file of its -own beside the one holding the column widths: which way you like your list is not a per-run -thought, and one hand-edited preference should not cost you the other. The *folded* ones are +Grouping and collapsed groups are remembered in the `view` key of `bravebot-ui.json`, +separate from the `layout` key holding column widths. The *folded* ones are what is written down rather than the open ones, so a checkout started since last launch arrives open instead of hidden behind a heading nobody has ever collapsed. @@ -458,23 +399,27 @@ The parts worth naming, not every file: ``` crates/bravebot-bridge/ the Rust library and the bravebot-rpc binary src/lib.rs the crate root, and the layering rules the tests assert - src/bridge.rs session store access, turn driving, Confirmer/Reporter/Sink + src/bridge.rs dispatch and session/turn lifecycle src/protocol.rs the request and event types src/wire.rs the JSON projections of the protocol src/store.rs reading and writing the records under ~/.bravebot src/turn.rs one turn, and everything that can block it src/fork.rs cutting a conversation in front of a message src/running.rs what is in flight, and what may answer it - src/emit.rs framing events onto stdout + src/emit.rs events delivered through the listener src/bin/bravebot-rpc.rs read stdin, frame stdout, nothing else tests/ the integration suites, including the refusal guarantees +crates/bravebot-ui-files/ descriptor-based helper for previews and bot memory src/main/ Electron main: one window, one child process, a narrow channel index.ts the window, and the allow-list of what the renderer may call bridge.ts the child process, and its lifetime menu.ts the application menu, built from the shared command list bots.ts the bots, and the two files each one speaks through state.ts bravebot-ui.json: one key replaced at a time, rest untouched - files.ts listing and opening inside a session's own folder + files.ts listing, search, preview, opening and attachment grants + project-files.ts client for the secure-file helper + experience.ts drafts, scroll position, pins, archives and density + memory.ts bot-memory editing and revision history recents.ts the projects opened before, which only this side writes forks.ts which session came out of which export.ts text, Markdown and the second renderer that draws the PDF @@ -489,7 +434,7 @@ src/renderer/ the React app transcript.ts gathering a turn's tool calls into runs theme.ts putting a palette on the window, as DOM rather than as a render export.tsx the PDF entry point, using the components the window uses - components/ twenty of them; ThemePicker, Sidebar, Transcript, FileTree, + components/ ThemePicker, Sidebar, Transcript, FileTree, Diff, TrustPrompt and BotAvatar are the load-bearing ones avatar/stage.ts one WebGL context, however many avatars, and their clock avatar/figure.ts what a friendly figure is made of, and what a seed varies @@ -509,7 +454,7 @@ docs/ the protocol design, this document, testing and the ### What is remembered -One file, `bravebot-ui.json` under `app.getPath('userData')`, with a key per shape: +`bravebot-ui.json` under `app.getPath('userData')` holds application preferences: | Key | What it holds | | --- | --- | @@ -518,11 +463,18 @@ One file, `bravebot-ui.json` under `app.getPath('userData')`, with a key per sha | `panels` | Which panels in the context column are turned **off** | | `recents` | The projects opened before, newest first | | `forks` | Which session came out of which | -| `bots` | The bots defined here: name, purpose, avatar seed, checkout, session and compaction watermark | +| `bots` | The bots defined here: name, purpose, avatar seed, checkout, model, conversation IDs and memory bookkeeping | | `theme` | Which palette the window is painted in, by name | -A file rather than `localStorage`, because the renderer is loaded from `file://` and Chromium -discards storage for that origin between launches — measured, not assumed. +Additional state lives outside this file: + +- `experience.json`: per-conversation drafts, scroll, pins, archives and bot associations; + also density and recent model choices. +- `bots//ground.md` and `memory-history.json`: cached briefing and memory revisions. +- Project `.bravebot-ui/bots/.md`: the bot's persistent memory. +- Renderer `localStorage`: per-conversation model choices, keyed by project and session ID. + +See [file access and retention](file-access-security.md) for retention and permissions. One file, but not one judgement: `src/shared/state.ts` decides nothing itself. It delegates each key whole to the validator that already owned that shape — `parseLayout`, `parseView`, @@ -536,13 +488,11 @@ The renderer reaches five of those keys, and only through a channel of its own p native picker and from what the *agent* answered — the window can read them and has no way to write a line into either. -`bots` is the one key that is written from both sides, and the split runs through the middle of a -single record. A bot's name, purpose and checkout are a preference somebody types and cross from -the window like any other. Its slug, its avatar seed, the id of the session behind it and the count -of what compaction has taken from that session do not: the first two are minted in the main process -so that a string arriving from a window never becomes a path segment, and the last two are read off -what the *agent* answered on `turn.done`, which is the same promise the fork lineage makes one line -up. +Bot records split user preferences from main-process bookkeeping. The editor supplies +name, purpose and model; a native picker supplies the project at creation. The project +cannot change on an existing bot. Main-process code validates the avatar seed, creates +the slug, and records conversation IDs and memory bookkeeping from agent events. +Renderer input cannot replace those bookkeeping fields through the bot editor. This replaces `layout.json`, `view.json`, `recents.json` and `forks.json`. Those are read once, on the first launch after the change, so nobody loses their columns to a rename; they are then left diff --git a/docs/phase-0-rpc-protocol.md b/docs/phase-0-rpc-protocol.md index 59cbae2..ecdfe04 100644 --- a/docs/phase-0-rpc-protocol.md +++ b/docs/phase-0-rpc-protocol.md @@ -1,4 +1,11 @@ -# Phase 0 — `bravebot-bridge`: the library and its protocol +# `bravebot-bridge`: the library and its protocol + +This document began as the Phase 0 design. The request and event descriptions below +cover the current bridge; §13–§14 retain historical implementation notes. For exact +wire shapes, consult [`protocol.rs`](../crates/bravebot-bridge/src/protocol.rs), +[`wire.rs`](../crates/bravebot-bridge/src/wire.rs), +[`bridge.rs`](../crates/bravebot-bridge/src/bridge.rs) and +[the UI types](../src/shared/protocol.ts). Setup instructions live in [setup.md](setup.md). The Electron app does not drive a terminal and does not parse one. It talks to a Rust **library**, `bravebot-bridge`, which lives in this repository and depends on @@ -54,13 +61,15 @@ channel for the reply — the same `mpsc` dance `remote_confirm.rs` already does napi's threadsafe machinery, plus a standing invariant that the JS main thread must never block or the whole app deadlocks. The complexity is relocated, not removed. -**The refusal guarantee stops being structural.** This is the one that decides it. Across -a pipe, "the UI died" *is* a closed pipe, which is *already* a refusal — it follows from -the shape of the thing rather than from code remembering to handle it. In-process, a -renderer crash and an agent crash are one event, and there is no surviving side left to -refuse anything. For a project whose thesis is that protection comes from structure -rather than from a filter that has to recognise an attack, dissolving the process -boundary is the wrong direction. +**Process isolation makes shutdown explicit.** Closing the bridge's stdin drops the +bridge and refuses pending questions. Electron closes stdin on window close and app +quit. A native addon in the main process would share that process's failure boundary; +the renderer remains a separate process in either design. + +This is not a guarantee that every display failure closes the pipe. A renderer-only +crash currently has no dedicated shutdown handler, and the transport ignores stdout +write failures. In those cases a question can remain pending until shutdown or +cancellation, but cannot become an approval. See [security](security.md). **Practical drag.** A native module needs rebuilding and re-testing per Electron ABI, with prebuilds per architecture, where a plain binary is already cross-built by the @@ -76,15 +85,19 @@ None of this is permanent. §2.2 is what keeps it cheap to revisit. Entirely in this repository: ``` -bravebot-ui/ - crates/bravebot-bridge/ - Cargo.toml - src/lib.rs all of it: session store access, turn driving, - src/session.rs the Confirmer / Reporter / Sink implementations, - src/wire.rs the JSON projections of §6 - src/bin/bravebot-rpc.rs ~100 lines: read stdin, frame stdout, nothing else +crates/bravebot-bridge/ + src/lib.rs crate root and public modules + src/bridge.rs dispatch, session lifecycle and turns + src/turn.rs Confirmer, Reporter and audit sink + src/protocol.rs message envelopes and errors + src/wire.rs agent types projected into JSON + src/store.rs shared session records + src/fork.rs conversation cuts + src/running.rs pending replies and cancellation + src/bin/bravebot-rpc.rs stdin/stdout transport ``` + `crates/bravebot-bridge/Cargo.toml` depends on the agent as a normal Cargo dependency — a path dependency into `vendor/bravebot`, which is a git submodule, so the path says where the sources are and the committed gitlink says which revision they are: @@ -103,7 +116,7 @@ This works today, unmodified, and it was checked rather than assumed: - **Every module the bridge needs is already `pub`**: `bravebot_tui::{sessions, store, audit}`, every module of `bravebot_agent`, and `bravebot_core::{event, label, todo, trust}`. - `crates/tui/build.rs` shells out to git to stamp `BRAVEBOT_BUILD` and degrades to - `"0.1.0 (no git)"` when there is none, so it compiles as a git or vendored dependency. + a version string without a git revision when there is none, so it compiles as a git or vendored dependency. ### 2.1 Depend on `bravebot-tui`, and do not extract from it @@ -127,10 +140,9 @@ string with no coordination needed. ### 2.2 Keeping the linkage replaceable -Everything above the transport lives in `lib.rs` and knows nothing about stdio. `bravebot-rpc` -is a framing shim: read a line, call a library method, serialise the result. The library -API mirrors §7 one-to-one — `list_sessions`, `open_session`, `send_turn`, `reply_confirm` -— and takes a callback for events rather than writing them anywhere. +Everything above the transport lives in library modules and knows nothing about stdio. `bravebot-rpc` +is a framing shim: read a line, call a library method, serialise the result. `Bridge::dispatch` routes the methods in §7 and takes a callback for events rather +than writing them directly to stdout. If in-process linkage is wanted later, it is a second front-end beside `bravebot-rpc`, and the library does not change. Two rules preserve that, and reviewers should enforce them: @@ -147,8 +159,9 @@ Honest limits. Two things could eventually want an upstream change, and neither - **Structured `doctor` output.** The checks live in `crates/cli/src/main.rs`, a binary, so they cannot be called as a library. v1 shells out to `bravebot doctor` and shows its text (§7.3). A small upstream extraction would be nicer and is optional. -- **Command approval.** When an exec tool lands it adds a `Confirmer` method, which the - bridge must implement. That is upstream changing under us, not us changing upstream. +- **New approval types.** Command approval is implemented. The v0.8.0 fetch-host, + language-server and manifest-plan requests are currently refused; adding UI support + requires adapting the bridge, not editing upstream. If anything else appears to need an upstream edit, that is a signal the bridge is reaching for something it should not, and it should be raised rather than patched. @@ -177,11 +190,10 @@ reaching for something it should not, and it should be raised rather than patche bravebot-rpc ``` -No arguments in v1. Configuration comes from the environment via `Config::from_env`, -exactly as the CLI does, so `bravebot-rpc` sees credentials on the same terms `bravebot` does and -the app inherits whatever the user's shell already set up. `bravebot-rpc --version` prints the -same `BUILD` string as `bravebot --version` — the same constant, since both read -`bravebot_tui::BUILD` — and the client should surface it, because a transcript read after the +Normal operation takes no arguments. `--version` (or `-V`) prints the bridge version +and the upstream build string. Configuration comes from runtime variables and baked +values via `Config::from_env`; a shell-launched app inherits that shell's environment. +The client should surface the build string, because a transcript read after the fact is read to find out what went wrong and the first question is which build produced it. @@ -190,43 +202,15 @@ one on `PATH`, with the single exception of `doctor` (§7.3, §2.3). ### 3.2 Credentials are a build-time input -`crates/config/build.rs` upstream **bakes the backend credentials into the binary at -compile time** and *fails the build* when they are absent, deliberately: a release binary -is built where the secrets are and used anywhere, so it does not demand them again from -every directory it is started in. - -This matters more for a window than for a terminal, and the difference is what makes it a -trap. `bravebot` is run from a shell that usually has direnv loaded, so even an unconfigured -binary finds what it needs in the environment. **An app launched from Finder, or by -`npm run dev`, has no such environment.** An unconfigured build therefore starts cleanly, -lists sessions, opens them, and fails only at the first inference request with -`SERVICES_KEY_AICHAT is not set and was not built in`. Everything works until the one -thing that matters. - -Two things follow, and both are needed: - -- **Build through direnv.** `scripts/build-bridge.sh` (what `npm run bridge` runs) finds - the agent — `$BRAVEBOT_DIR` if set, otherwise `vendor/bravebot`, which is the same tree - `crates/bravebot-bridge/Cargo.toml` depends on — and builds via `direnv exec` when its - `.envrc` is allowed, so the credentials are captured. `$BRAVEBOT_DIR` is credentials - only now that the submodule decides the sources: it can name an older sibling checkout - holding the `.envrc` without changing what gets compiled. The path is canonicalised first: direnv's allow list is keyed on the physical - path of the `.envrc`, so a checkout reached through a symlink otherwise reads as - un-allowed even after `direnv allow`. It warns loudly rather than silently producing a - binary that cannot infer. Verified: a turn runs from a shell with all three variables - explicitly unset. -- **`BRAVEBOT_ALLOW_UNCONFIGURED_BUILD=1` stays set** in `.cargo/config.toml`, so a checkout - with no secrets still compiles and the 47 tests still run. It only suppresses the - build failure; it does not prevent baking, so it costs nothing when credentials are - present. - -The app also has to fail *well*, because the cause is a build step and nothing the user -does in the window will fix it. A `config` error code (§7.4) is surfaced as its own -screen naming the three steps that fix it, not as a line in a status bar. - -**For packaging:** a release build must be produced the way the agent's own releases are, -with the credentials present. This is the single easiest way to ship an app that looks -fine and cannot answer a question. +The upstream configuration build script bakes available Brave backend values into +`bravebot-rpc`; runtime values override them. This repository opts into unconfigured +builds with `BRAVEBOT_ALLOW_UNCONFIGURED_BUILD=1` in `.cargo/config.toml`, so missing +credentials do not prevent development or CI builds. They do prevent inference unless +configuration is supplied at runtime. See [credentials](setup.md#credentials) for +loading, strict build validation and the difference between shell and Finder launches. + +`agent.info` exposes `configured` for readiness checks. Setup help and diagnostics +explain missing configuration without exposing credential values. ## 4. Message envelope @@ -238,7 +222,8 @@ Three shapes, distinguished by which keys are present. { "id": 17, "method": "turn.send", "params": { ... } } ``` -`id` is a client-chosen positive integer, unique within the process lifetime. +`id` is a client-chosen unsigned integer, unique within the process lifetime. +The parser accepts zero; the Electron client generates increasing IDs. **Response** (agent → client), exactly one per request, `ok` xor `error`: @@ -380,7 +365,8 @@ Loads the `Record` via `sessions::load` and the trail and todos via `sessions::r - `branchNote` / `buildNote` are the existing `sessions::branch_note` and `sessions::build_note` outputs: a sentence, or `null` when there is nothing to say. -`session.open` does **not** start a turn and does **not** ask about trust. It is a read. +`session.open` does **not** start a turn. If the record has no saved trust map, +it emits `trust.request`; the client must answer before sending a turn. #### `session.new` @@ -480,7 +466,7 @@ differently: the front-end puts it in the composer and the person edits it. **Lineage is not in the record.** `Record` has no field for a parent, and adding one is an upstream change (§2); worse, `Handle::save` rebuilds the record wholesale, so a key written beside it would be erased by the fork's first turn. The front-end keeps it instead, in a -`forks.json` of its own under `userData`, written by the main process **from this response** — +`forks` key in `bravebot-ui.json` under `userData`, written by the main process **from this response** — never from what the renderer asked for. That is the same promise the recents list makes: the renderer can read the list and ask for something on it, and has no way to write to it. @@ -545,12 +531,12 @@ file is there immediately before the send, not once when it was first named. Neither list may be named by a renderer in this app; see §9 and `src/main/index.ts`. Spawns the worker thread and calls `turn::resume` with an RPC `Confirmer`, an RPC `Reporter`, and a `Trail` sink — the same call shape as -`crates/tui/src/app.rs:562`, differing only in where the three handles send. +the upstream TUI, differing only in where the three handles send. Returns immediately: `{ "turn": 5 }`, the turn number within the session. Progress arrives as events; completion as `turn.done` or `turn.error`. -The prompt is appended to `~/.bravebot/history` (via the moved `store::append_history`), so +The prompt is appended to `~/.bravebot/history` (via `store::append_history`), so recall works across both front-ends, and it names the session if the session has no name yet. `recall` (optional, default `true`) governs both. A front-end that sends a turn **on its own @@ -571,7 +557,7 @@ flight errors `turn_in_flight`. Different sessions run concurrently. ``` Calls `Cancel::cancel()` on that turn's token — a fresh token per turn, never reused, -matching `app.rs:540`. Returns `{}` immediately; the turn ends with +matching the upstream cancellation model. Returns `{}` immediately; the turn ends with `turn.error` / `Cancelled` when the engine notices. Cancelling when nothing is running is not an error. @@ -589,6 +575,23 @@ covers the race where the question is registered just after the stop request. See §8. Returns `{}`. An unknown or already-answered `request` errors `no_such_request` and changes nothing — an approval is single-use and cannot be replayed. +#### Other decision replies + +`run.reply`, `output.reply`, `vouch.reply` and `ask.reply` all require `session` and +`request`, and must match the pending question's kind as well as its ID. +`run.reply` accepts `decision` and `remember`; only an approval with literal +`remember: true` records a command grant. Output and vouch replies accept `decision`. +`ask.reply` accepts an `answers` array, whose entries contain `typed` text or `chosen` +indices; unreadable entries decline. Choices are fitted to the question before use. + +#### Permissions + +`permissions.list` takes `session` and returns `paths` and `commands`. +`permissions.revoke` takes `session` plus either `kind: "path"` and `path`, or +`kind: "command"` and `command: { program, args }`. It returns the updated lists. +These methods refuse with `turn_in_flight` while the session is running. Revocation +can reduce existing grants; it cannot add trust. + ### 7.3 Trust and diagnostics #### `trust.reply` @@ -612,7 +615,7 @@ machine anyone will try it on. **v1 shells out.** The checks live in `crates/cli/src/main.rs`, a binary, so they cannot be called as a library without an upstream change (§2.3). The bridge runs `bravebot doctor`, -captures stdout, and returns it whole: +captures stdout and stderr, and returns their combined text: ```json { "id": 9, "ok": { "structured": false, "text": "…", "exitCode": 0, @@ -629,7 +632,9 @@ instead. The flag exists so the client can be written once against both. #### `agent.info` -`{ "build": "…", "version": "0.1.0", "home": "/Users/me/.bravebot" }`. Sent as the +`{ "build": "…", "version": "0.1.0", "home": "/Users/me/.bravebot", +"configured": true, "defaultModel": "…" }`. `version` is the bridge package +version; `home` and `defaultModel` may be null. Sent as the `agent.ready` event at startup and also available as a request. ### 7.4 Error codes @@ -649,11 +654,11 @@ instead. The flag exists so the client can be written once against both. ## 8. Events -One per `remote_confirm::ToMain` variant, plus lifecycle. All carry `session`. +Approval, progress and lifecycle events carry `session`, except for `agent.ready`. | event | `data` | source | |---|---|---| -| `agent.ready` | `{ build, version, home }` | startup, no `session` | +| `agent.ready` | `{ build, version, home, configured, defaultModel }` | startup, no `session` | | `turn.started` | `{ turn }` | `turn.send` accepted | | `phase` | `{ phase }` | `Reporter::phase` | | `narration` | `{ text }` | `Reporter::narration`, **empty ones dropped** | @@ -665,6 +670,11 @@ One per `remote_confirm::ToMain` variant, plus lifecycle. All carry `session`. | `tokens` | `{ written }` | `Reporter::output_tokens`, **only when the figure changes** | | `audit` | `{ at, turn, event }` | the `Sink`, via `audit::as_json` | | `confirm.request` | see §8.1 | `Confirmer::confirm_write` | +| `run.request` | `{ request, stages, directory, plan, writes, releasesPrivate, vouches, summary }` | command approval | +| `output.request` | `{ request, command, reference, lines, output, summary }` | admit command output | +| `vouch.request` | preview and label fields from `wire::vouch_request` | trust a quarantined path | +| `ask.request` | `{ request, prompts }` | user questions | +| `trust.request` | `{ directory }` | initial project trust | | `turn.done` | see §8.2 | `Ok(Outcome)` | | `turn.error` | see §8.3 | `Err(TurnError)` | @@ -712,12 +722,14 @@ whose events all share one second cannot say which came first. } } ``` -- `request` is agent-assigned, monotonic per session, and **single-use**. +- `request` is agent-assigned and **single-use** for its pending question. IDs can + recur in later turns; clients must discard pending questions when a turn ends. - `changes` is `WriteRequest::diff()`, already condensed. The full `contents` is **not** sent: the whole point of the design is that a reviewer reads a few lines rather than spotting a difference in a whole file, and shipping the body to the renderer invites a client to show it instead. - `existing` distinguishes create from overwrite without sending the old body. +- `added`, `removed` and `exact` describe the diff counts and whether it is exact. - `untrusted: true` means the body came from somewhere nobody vouched for — a file the planner never read, returned by an isolated processor. The Rust doc comment is explicit that reviewing this is a different act from reviewing the model's own work and the @@ -790,10 +802,12 @@ preferences to this ID just as they do for `turn.done`. Therefore: -- **Every path that cannot deliver a question, or cannot receive an answer, resolves to - `Decision::Reject`.** A closed stdout, a closed stdin, EOF, a serialisation failure, a - client that exits with a confirmation outstanding, `session.close`, or process - shutdown. A channel that cannot carry the question cannot carry consent either. +- **Cancellation, session close and bridge shutdown refuse pending questions.** + EOF on stdin drops the bridge. Malformed decisions never approve. The current + transport ignores stdout write errors, so a closed stdout alone can leave a question + waiting; likewise a renderer-only crash does not automatically stop the child. + These are liveness limitations, not approval paths. + - **There is no timeout-to-approve.** There is no timeout at all in v1: a write waits for a human indefinitely, which is what it should do. If a timeout is ever added it resolves to refusal. @@ -801,8 +815,7 @@ Therefore: because nobody was watching would let the display outrank the work. - **An approval is bound to its `request` id and consumed on use.** A replayed `confirm.reply` errors and changes nothing. -- **A cancel does not answer a pending write.** These are separate decisions and - conflating them would let a cancel approve something. +- **A cancel refuses a pending write.** It wakes the blocked confirmer without approval. These are the protocol's actual security properties. §12 makes them tests. @@ -833,42 +846,37 @@ default: defaulting either way is the mistake this design exists to avoid. - One writer, holding a mutex on stdout, so lines cannot interleave. This is the same reason the kernel never prints. - One worker thread per running turn, holding its own `Cancel`, its own `Egress`, and - cloned `Config` / `Workspace` handles — as `app.rs:544` does. + its configuration and workspace state. - The `Confirmer` blocks its worker on an `mpsc::Receiver`, which the dispatch thread feeds from `confirm.reply`. Unchanged from `RemoteConfirmer`; only the source of the answer moves. -- v1 caps concurrent turns at 4 and errors `turn_in_flight` beyond that, because each - turn is a live model connection and an unbounded fan-out is a bill, not a feature. +- A session permits one running turn. There is currently no global four-turn cap; + different sessions can run concurrently and each can incur model usage. --- -## 11. Out of scope for v1 - -- **Command approval.** There is no exec tool. `crates/agent/src/tools.rs:1988` asserts - no tool name contains `"run"`, and `Confirmer` has exactly one method, - `confirm_write`. The README's "you approve every command" describes the design, not the - current code. When an exec tool lands it will add a `Confirmer` method, and this - protocol grows a `confirm.command` event alongside `confirm.request` — same - request-id and same refusal-by-default rules. -- **Streaming reply tokens.** `Reporter` reports `output_tokens` as a count, not text. - The reply arrives whole, in `turn.done`. Token-by-token streaming would need a change - in the turn engine and is not worth it for v1. -- **MCP configuration**, subscription import (`import-leo-creds`), skills authoring, and - workspace file browsing. All are reachable from the CLI; the app can shell out or wait. -- **Multiple clients on one `bravebot-rpc`.** One process, one client. +## 11. Current limits + +- Fetch-host, language-server and manifest-plan approval requests are refused until + their UI is implemented. Command, output, vouch and question approvals are implemented. +- Replies arrive whole in `turn.done`; output-token events report counts, not text. +- MCP configuration, subscription import and skills authoring have no dedicated UI. +- File browsing, previews and attachments are Electron IPC features, not RPC methods. +- One `bravebot-rpc` process has one client. There is no multi-client transport. --- -## 12. Tests to write with the code +## 12. Verification contracts The first six are the security properties, not nice-to-haves. Each should fail loudly if someone later makes the obvious "simplification". 1. A closed stdin with a confirmation outstanding yields `Decision::Reject`. -2. A write to a closed stdout yields `Decision::Reject` rather than proceeding. +2. Transport-loss coverage must distinguish stdin EOF from a stdout-only failure; + the latter currently has the waiting-state limitation described in §8.4. 3. `session.close` during a pending confirmation rejects it, then joins the worker. 4. A replayed `confirm.reply` for a consumed `request` errors and performs no write. -5. `turn.cancel` leaves a pending confirmation pending — it does not approve it. +5. `turn.cancel` wakes and refuses a pending confirmation; it never approves it. 6. `turn.send` before `trust.reply` on a fresh session is refused. 7. A malformed line is answered or logged and the process survives; the next valid request is served. @@ -890,9 +898,11 @@ someone later makes the obvious "simplification". --- -## 13. Implementation order and status +## 13. Historical implementation order and status -**Built and verified live. 47 tests passing, upstream clean at `1ba33f9`.** +The following records the original Phase 0 milestone: **47 tests passing, upstream +clean at `1ba33f9`**. It is historical evidence, not the current dependency pin or +test count. See [testing](testing.md) for current validation commands. A real turn has now run end to end through `bravebot-rpc` (`scripts/smoke-turn.sh`, in a shell where direnv has loaded the agent's `.envrc`): five tool rounds, a gate refusal, two @@ -934,7 +944,10 @@ rather than waiting for the whole of Phase 0. --- -## 14. Decisions taken, and what is still open +## 14. Historical decisions and follow-ups + +The original decisions below explain the implementation sequence. Later UI work +added grouping and bot lists; live audit streaming is now implemented (§8). Settled: diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 0000000..8aeac85 --- /dev/null +++ b/docs/security.md @@ -0,0 +1,57 @@ +# Security boundaries + +The UI uses the agent's existing library interfaces without modifying the pinned +upstream source. The bridge is a separate `bravebot-rpc` child process, speaking +newline-delimited JSON over pipes. Electron's main process manages its lifetime; +window close and app quit explicitly stop the bridge. A renderer-only crash does +not itself close the pipe: there is currently no `render-process-gone` handler, so +a pending decision may remain waiting until the window closes or the app quits. +A closed stdout alone also does not trigger shutdown in the current transport; +its write errors are ignored. Neither condition grants an approval. + +## Renderer and IPC + +The main window enables `contextIsolation` and `sandbox`, disables `nodeIntegration` +and `webviewTag`, and rejects in-window navigation. External links open through the +system browser. The preload exposes specific IPC operations and subscriptions, +not general Node or filesystem access. The main process allow-lists agent methods. + +Project-file operations use a session handle and a relative path. Main-process +code resolves the session root and validates the path. Text previews and memory +operations use the descriptor-based `bravebot-ui-files` helper; directory listing +and opening files in an external app use separate validation in `src/main/files.ts`. +See [file access and retention](file-access-security.md) for the helper's guarantees +and limits. Do not assume every filesystem operation uses the helper. + +File contents **do** cross IPC for previews and bot-memory editing. These operations +do not themselves send the contents to a model. File attachments require a native +picker, a session-bound grant, validation at send time, and an explicit Send action. +The main process strips raw `files` and `dropped` lists from renderer turn requests +and composes authorized paths itself. Bot briefings are also composed by the main process. + +## Decisions and refusal + +The transcript presents write, command, command-output, path-vouch and user-question +requests. Replies must match both the pending request ID and its kind. Within a turn, an unknown +or consumed ID cannot approve another request. Clients discard pending questions +when a turn ends because IDs may recur in later turns. Malformed decisions decline; +question answers are checked against the offered choices. + +Cancellation wakes pending questions and refuses them. Session close and bridge +shutdown also refuse outstanding questions. There is no timeout that grants approval. +These properties depend on both bridge refusal handling and Electron lifetime handling; +they are covered by the Rust refusal suites and Electron tests in [testing](testing.md). + +The v0.8.0 agent also has fetch-host, language-server and manifest-plan approvals. +The UI does not present those requests yet; the bridge refuses them without taking +an answer intended for another pending question. + +Command-output content is released for display so the person deciding can read it. +Only the agent's approved path admits it to the planner. Confined material is labelled +in the UI; showing it is not evidence that the planner read it. Not every write needs +a prompt: the agent's integrity policy determines that, including for bot memory. +See [memory write policy](interface.md#what-a-memory-write-is-actually-gated-on). + +The bridge protocol and its implementation references are in +[phase-0-rpc-protocol.md](phase-0-rpc-protocol.md). File retention is local storage, +not encryption or a guarantee of secure erasure. diff --git a/docs/setup.md b/docs/setup.md index 1d49b26..b10947a 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -1,58 +1,153 @@ -# Why setup looks like this +# Setup -The commands are in the [README](../README.md). This is the reasoning behind the two parts -of it that look like more ceremony than they need: the pinned submodule and the credentials -file outside every checkout. +## Prerequisites -## Why the agent is a pinned submodule +- **macOS**, with Xcode Command Line Tools (`xcode-select --install`) for native builds. + The window uses macOS traffic lights and sidebar vibrancy. +- **Current stable Rust**, preferably installed with rustup. `rust-toolchain.toml` + selects stable and Clippy; `rustup update stable` updates an existing installation. + The workspace declares Rust 1.88 as its minimum. +- **Node 22.12+ and npm**. CI uses Node 24. The app uses Electron 44 and React 19. +- **Git**, including submodule support. +- **Optional: direnv**, for loading backend credentials. It is unnecessary for + builds without credentials or when the required variables are already exported. -`crates/bravebot-bridge` depends on the agent by path — `../../vendor/bravebot/crates/*` — so -a clone without submodules leaves an empty directory and nothing compiles. -`scripts/build-bridge.sh` says so rather than letting cargo report a missing `Cargo.toml`. +## Clone and run -The pin is the point. The bridge builds against the agent's internals, which carry no -compatibility promise: a field added to a struct it constructs is a build break here, with -nothing changed on this side. Before the submodule that break arrived at whatever moment a -developer next pulled the sibling checkout. Now it arrives when somebody moves the pin -deliberately: +```bash +git clone --recurse-submodules https://github.com/brave-experiments/brave-bot-ui.git +cd brave-bot-ui +npm ci +npm run dev +``` + +`npm ci` installs the locked dependency versions and runs Electron runtime setup. +`npm run dev` builds both Rust executables and starts Electron with hot reload. +To build and preview without hot reload, see [development](development.md). + +For a clone made without submodules: + +```bash +git submodule update --init --recursive +``` + +## Credentials + +A fresh checkout builds without secrets and can display saved sessions. Inference +requires backend configuration. For the Brave backend, supply these exported names: + +| Variable | Purpose | +| --- | --- | +| `SERVICES_KEY_AICHAT` | Backend signing key | +| `BRAVE_SERVICES_KEY_ID` | Key identifier | +| `BRAVE_AI_CHAT_ENDPOINT` | Backend endpoint | +| `BRAVE_AI_CHAT_DEFAULT_MODEL` | Optional default model; otherwise `automatic` | +| `BRAVE_AI_CHAT_PREMIUM_ENDPOINT` | Optional premium endpoint | + +Use the exported names, not the `DEV_`/`PROD_` inputs used by the agent's example +configuration. Keep the values outside the checkout, for example in +`~/.config/bravebot/env`, as `NAME=value` lines. Create it with your editor and set +its permissions to 0600. Do not commit the values. + +With direnv installed, add this line to a `.envrc` in the UI repository (preserve +any existing contents): + +```bash +dotenv_if_exists ~/.config/bravebot/env +``` + +After reviewing that file, allow it and explicitly run the build through it: + +```bash +direnv allow . +direnv exec . npm run build +npm start +``` + +For hot reload with the same environment, use `direnv exec . npm run dev`. +A shell with direnv integration can load these variables automatically; `direnv allow` +alone does not export them into a shell without that integration. + +The agent's configuration build script bakes available Brave backend values into +`bravebot-rpc`. Runtime environment values override baked ones. Keeping a credential +file outside Git lets multiple checkouts use it and keeps it through re-clones. +The file is not automatically discovered: the `.envrc` above is what loads it. + +Alternatively, `scripts/build-bridge.sh` loads an allowed `.envrc` from +`vendor/bravebot` via direnv. `BRAVEBOT_DIR` (or the legacy `BUA_AGENT_DIR`) can point +to a different credential checkout. These variables affect credential loading only; +Cargo still compiles `vendor/bravebot`. The script canonicalises the directory for +direnv's allow list. It first uses an already-exported `SERVICES_KEY_AICHAT` when present. + +### Builds without credentials + +`.cargo/config.toml` sets `BRAVEBOT_ALLOW_UNCONFIGURED_BUILD=1`, allowing missing +credentials during development and CI. This does not prevent baking values that +are present. Missing credentials therefore do **not** make this checkout's build +fail; they prevent inference at runtime. The app offers backend diagnostics and setup help. + +For a Brave-backend build that must fail if required values are missing, run: + +```bash +direnv exec . env BRAVEBOT_ALLOW_UNCONFIGURED_BUILD=0 npm run build +``` + +An app started from a configured shell inherits its environment; Finder does not +load your shell's `.envrc`. A distributable Brave-backend app needs the required +configuration baked in. See [packaging](development.md#packaging). +The agent also supports runtime Bedrock configuration; its variable definitions are +in [`env_var.rs`](../vendor/bravebot/crates/config/src/env_var.rs). Bedrock/AWS values +are not baked into the binary by this build script. + +## Updating an existing checkout + +After pulling changes, synchronise any changed URL and check out the committed pin: + +```bash +git pull --ff-only +git submodule sync --recursive +git submodule update --init --recursive +npm ci +``` + +`vendor/bravebot` points to [brave/bravebot](https://github.com/brave/bravebot), +currently at v0.8.0 (`3259f8b`). A URL update alone does not change that revision. +`npm run bridge` warns if the checked-out submodule differs from the pin. + +### Intentionally updating the pin + +The bridge depends on upstream internals by path. Pinning makes an incompatible +upstream change arrive in a reviewed update rather than during an unrelated build. +Choose an explicit revision, then run the [submodule-update checks](testing.md#current-regression-checks) +and review any lockfile changes before committing: ```bash git -C vendor/bravebot fetch origin -git -C vendor/bravebot checkout # or origin/main -cargo test --all # the upgrade is a test pass, not a version bump -git add vendor/bravebot && git commit -``` - -CI compiles the pinned revision too, from one checkout with `submodules: true`, so an -upstream commit cannot turn this repository red on its own and a bump of the pin is a pull -request that CI runs before it lands. - -After a `git pull` that moves the pin, run `git submodule update` — git leaves the submodule -where it was, and the build that follows would otherwise compile an agent nobody chose. -`npm run bridge` warns when the two disagree. - -## Why the credentials live outside every checkout - -The [README's Credentials section](../README.md#credentials) recommends keeping the values in -`~/.config/bravebot/env` and reading them from a `.envrc` here. Putting them in -`vendor/bravebot/.envrc` also works, and `BRAVEBOT_DIR` can still point at an older sibling -checkout instead. Three things follow from preferring the file outside: - -- **The secret outlives the checkout it was for.** A `.envrc` inside the agent's tree is one - `git clean -xdff`, or one re-clone, away from being gone, and what you lose is the one file - you cannot get back from a remote. The agent's move from a sibling checkout to a submodule - is the same lesson already collected once: that path changed, and anything kept under it - had to move with it. -- **One file feeds the build and the run.** The build bakes the values in; separately, the - agent lets a variable present at run time override a baked one, so an app started from - this shell reaches the backend even when the binary it spawns was built without - credentials. Those are two different failure modes and this answers both. -- **One copy of the secret, in a directory no `git add -A` can reach.** `.envrc` is in this - repository's `.gitignore`, which matters more here than in the agent's tree: there, the - agent's own `.gitignore` was already covering for you. - -`BRAVEBOT_DIR` — and `BUA_AGENT_DIR`, which some shell profiles still set from before the -agent was renamed — are credentials only: cargo compiles the submodule either way. The path -is resolved to its real one, because direnv's allow list is keyed on the physical path and a -checkout reached through a symlink otherwise reads as un-allowed however many times you allow -it. +# Replace with the intended tag or commit. +git -C vendor/bravebot checkout +npm run build +cargo test --all +git add vendor/bravebot Cargo.lock +git commit -S -m "Update the bravebot submodule pin" +``` + +CI checks the committed revision. Commits intended for `main` must have verified +signatures under the repository rules. + +## Electron runtime troubleshooting + +Electron 44's npm package needs a separate runtime download. The repository's +postinstall runs that installer and names the development app **Brave Bot**. +Development and preview commands also run setup and reuse an installed runtime. + +If you see `Error: Electron uninstall`, or installed with `--ignore-scripts`, run: + +```bash +npm run setup:electron +npm run build +npm start +``` + +Unset `ELECTRON_SKIP_BINARY_DOWNLOAD` before launching. CI sets it to `1` because +its TypeScript check does not need an Electron executable. If installation fails, +check the installer output and retry setup after fixing the download problem. diff --git a/docs/testing.md b/docs/testing.md index dea7f62..cfe90da 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -81,10 +81,11 @@ Each driver launches the app, prints a line per assertion and leaves screenshots `/tmp/bravebot-ui/` or a driver-specific path in `/tmp`. Eight of the checks cost real tokens: `drive:markdown`, `drive:run`, `drive:ask`, `drive:bot-turn`, `drive:bot-memory`, `drive-turn.mjs`, `drive-models-live.mjs` and `smoke-turn.sh` send an -actual prompt. Live checks use the backend credentials configured in settings, the environment, -or the agent binary. +actual prompt. Live checks require backend credentials from the process environment or compiled +into the agent binary; the UI's setup help does not store credentials. See +[setup](setup.md#credentials). -The drivers share `bravebot-ui.json`, so one that leaves a column folded — or a panel turned off — +Some older drivers share the default profile's `bravebot-ui.json`, so one that leaves a column folded — or a panel turned off — would make the next one's measurements meaningless. `drive-columns.mjs` normalises the columns at the start of a run and puts them back at the end, `drive-panels.mjs` turns every panel back on before it measures one and again before it finishes, and `drive-tree.mjs` puts the file tree back @@ -108,11 +109,12 @@ table above. Two jobs: revision the gitlink pins, then `cargo clippy --all-targets --all-features -- -D warnings` and `cargo test --all`. +The workflow does not run the Node regression tests, Electron drivers, packaged-app +checks, or the upstream agent's full test suite. Run the applicable local checks above. + So Clippy *is* a lint step, on the Rust side; there is none on the TypeScript side, where `tsc` -is the whole gate. `cargo fmt --all -- --check` is deliberately absent: rustfmt would rewrite -around 490 lines of the bridge crate, mostly breaking method chains and one-line `assert!` -calls that are on one line on purpose, and reformatting the crate is a change to make on its -own rather than as a side effect of turning CI on. The reasoning for each of these lives in +is the whole gate. `cargo fmt --all -- --check` is deliberately absent because the bridge is not +rustfmt-clean; introducing that gate requires a separate formatting change. The reasoning for each of these lives in comments in the workflow itself. No `drive:*` driver runs in CI: they want a macOS runner and a display, and eight of the live checks spend diff --git a/docs/ui-ux-redesign.md b/docs/ui-ux-redesign.md index 822bd7a..25f13ca 100644 --- a/docs/ui-ux-redesign.md +++ b/docs/ui-ux-redesign.md @@ -1,6 +1,8 @@ # UI and UX implementation audit -Branch: `codex/ui-ux-redesign` +Historical audit of `codex/ui-ux-redesign`, subsequently merged through PRs #37, +#39, #40, #41 and #42. Counts and live-run observations below describe the original +implementation, not a fresh test result. Use [testing](testing.md) for current gates. The full review is the scope. Runtime checks use the actual Electron application and isolated test projects. Compilation, interaction assertions, screenshots, and live-agent checks provide @@ -35,8 +37,8 @@ complementary evidence; their boundaries are recorded below. ## Acceptance evidence The Electron driver is `scripts/drive-ux-acceptance.mjs`. It launches the production -build with a fresh user-data directory and disposable project. It records 41 -screenshots and fails on assertion failures or renderer exceptions. Screenshots +build with a fresh user-data directory and disposable project. It records screenshots +(currently 42) and fails on assertion failures or renderer exceptions. Screenshots were opened and visually inspected, including the final dark scrollbar and memory-reset confirmation refinements.