Architecture

Everything flows one way, through one loop:

agent ──hook JSON──▶ vults-hook ──protocol line──▶ ipc ──┐
GitHub (gh) ─────────────▶ connectors runtime ─────────────────┤
island clicks (Allow, open, jump…) ────────────────────────────┤
                                                                ▼
                                        core::reduce(state, input, now) ──▶ effects
                                                                │            (answer the hook,
                                                    State::view ▼             open a URL, jump)
                                                         island renders

Layers

#

The crates form three layers over a small base. A crate depends only on its own layer or a lower one; scripts/check-layers.sh checks it in CI (tests may reach further).

Only app wires the layers together: Connect never calls into Experience, and Core knows neither. That keeps a new surface cheap (it draws State::view and sends intents, ADR 0021) and keeps Zeca optional (ADR 0018): he uses Chat, Voice and Connect, and none of them knows about him. His body is in Experience; his brain is the zeca crate in Connect, which reads the flock but never answers a permission (ADR 0018).

The UI (ui/) is TypeScript with no framework. src/bridge.ts is the only file that talks to Tauri; src/island/ renders the island from the view, src/character/ draws the birds from sprite data, and src/surfaces/ holds every other surface, one folder each (widget/, settings/, nest/) with its main.ts entry and its stylesheet. Code more than one surface uses sits at the root of src/; the exceptions are the chat panel (src/island/chat.ts, with its Markdown and icons) and the GitHub card (src/island/board.ts), which the Nest draws too, and the settings pages’ look (surfaces/settings/pages.css), which the Nest’s Week uses inside a shadow root.

Meaning in core, look in the surface

#

The view says what things mean, so every surface agrees (ADR 0021). Each session carries its attention, an ordered level (quiet < info < done < failed < needs-you), and the view carries the most of them; card marks the session whose card is first in line and still waits on it. The island only chooses the look: which sound a level makes, and how long a state must hold (1.5 s, 3 s for done) before it is news.

The runtime broadcasts the view, when it changed, to every window at once (publish_view), and keeps the last one for a page that loads later (current_view). Events meant for the island alone (pointer, shortcuts, chat) are sent to its label. A plain listen hears every target, so a new surface subscribes to those through window-scoped helpers in bridge.ts (getCurrentWebviewWindow().listen) to stay out of them.

The Nest’s window holds two webviews, the Nest’s and Settings’, one shown at a time under the same header (ADR 0021). Commands check the label of the webview that called: the calls only Settings may make are refused from the Nest’s, which shows agents’ text.

ended lists the cards that left the line most recently, each with its outcome: answered here (allowed, denied, answered), released (sent to the terminal from here), terminal (the agent moved on), expired or rule (an Always on an identical card). The island reads it to say what became of the card it showed. An outcome is information only: it is recorded where a card leaves the line and never answers one.

front is the session in front, by one rule: the session whose card waits, else the one the user put in front (focus, set by Intent::Focus from a click on its row, forgotten when the session leaves), else the first. Work alone never moves it. Sessions come in the order they arrived, the order every surface draws them in, and the one Intent::FocusNext and FocusPrevious (global shortcuts) walk, wrapping. The chat works in the folder of the session in front.

Why the hook waits for an acknowledgement

#

A permission request keeps its connection open. The server only waits for a human once the app’s loop has taken the request and core has queued its card (Effect::AckPermission). If the app is stuck or not listening, the agent gets its answer (silence, so it asks in the terminal) within 800 ms instead of two minutes. The island opens on a queued card and stays open until it is answered; no presence mode may hide it once acknowledged (ADR 0021).

Why only core produces a decision

#

core::reduce turns a PermissionRequested event into pending state, and only a human’s click turns pending state into a RespondPermission effect: Intent::Decide (Allow, Deny) or Intent::DecideAlways, which also saves a rule. A saved rule answers only a request that matches it exactly: the same agent, folder, tool and target (ADR 0004). A question (QuestionAsked) waits the same way, and only an Intent::Answer that fits its questions turns it into an AnswerQuestion effect. A test feeds every other input in every order and checks none of them answers.

The island on Wayland

#

The island is a layer-shell surface mapped once, at a fixed size, and never resized or hidden: KWin stops showing a layer surface resized from the webview. The UI draws the island inside it and reports its rectangle, which becomes the only part that takes the mouse (the input region); everything else falls through to the windows below. WebKit pauses requestAnimationFrame while it thinks the page is hidden, so the UI measures the DOM synchronously and animates with timers.

The platform code is per window: each surface has a LayerSpec (namespace, fixed size, the edges it hangs from, margin, keyboard) and its own input region, kept by window label. A page’s layout and keyboard requests act on the window that sent them, and only if it is a surface (SURFACES in app/src/lib.rs). A new surface gets a spec, its label in the windows of app/capabilities/default.json and, for its own page, a Vite entry.

Trying the island without an agent

#

cargo run -p vults-hook --example replay sends a recorded session through the real hook into the running app: reading, searching, the web, an edit, a permission (it waits for your answer, as an agent would), a command and the end. Pass your own JSONL file (one hook JSON per line) and --delay-ms or --agent codex to change it. ui/lab/ (npm run dev, then /lab/) shows every clip and the island with made-up states, without the app at all.

Decisions

#

Why the app is built this way (Rust only, the safety rules, one core for every surface, Zeca optional, rules before models) is in the decision records.

Documentation

#

docs/ is the source for the docs on the website (rogeriojunior31.github.io/en/docs/vults), published on each release tag; docs/site.json holds the name and summary the website shows. Pages start with a # H1, use relative links, and keep images in docs/assets/. docs/adr/ holds the decision records. docs/dev/ is internal and not published; docs/pt-br/ holds the Brazilian Portuguese translation (see CONTRIBUTING). node tests/visual/docs-shots.mjs retakes the README’s and the guides’ island images from the lab; run it before each release.