The plugin kernel
thurbox is the interface to Fleet's sessions, with a Lua-driven renderer. The
kernel owns no pane: the session list, the terminal and every other surface that
shows your work is a plugin under ui/. The bundled set is currently
three — the session list, the agent pane and the search strip — plus four
floats that fill no slot: the new-session flow, the confirmation, the rename
field and the context menu. It does own the system modals — help, settings,
the theme picker and the interface's own file list — which are chrome about
thurbox itself rather than panes (see below). The file list is not a pane: it is
how a broken interface is recovered, so it must not be a file the interface
loads. Written for someone about to change the kernel; if you want to write a
plugin, read docs/thurbox/plugins.md.
Writing a plugin starts at docs/thurbox/plugins.md — Start here, which is four
thurbox-cli plugin commands and needs no terminal.
Code review and an info panel are panes rather than kernel features:
thurbox-code-review (the
first consumer of thurbox.diffs) and
thurbox-info-panel (drawn
entirely from the snapshot). Each is its own repository, installed by clone —
docs/thurbox/plugins.md has the commands.
Shape #
KERNEL (src/kernel/) LUA (ui/)
───────────────────────── ──────────────────────────
node four primitives layout.lua arrangement
layout rects before render lib/theme roles
convert table <-> node lib/ui panel, list, cursor, row…
lib/widgets measure, window, list…
paint node -> ratatui lib/tree decoration helper
host VM, reload, isolation plugins/* 3 panes + 5 floats
registry keys, settings, commands
modals help, settings, theme, files, palette
events derived from the snapshot
snapshot the read side
command the write side
config the user's settings, live and restart-only
repos what the creation flow asks
updates whether a newer release exists
terminal live PTY surfaces
diff review surfaces
files rooted file reads
theme 36 palettes resolved
notify the blocked edge
metrics machine, agent
perf counters
bundled embedded interface, and what was done to your copy of it
inventory which files exist, and which are running
The five rules #
1. Four node kinds, forever. text, box, input, surface. Everything
else composes in Lua — ui/lib/ui.lua, the component layer, over
ui/lib/widgets.lua, the primitive kit. A prior attempt froze its catalog at six
and reached sixteen, because it never built the userland layer and each new
appearance had nowhere else to live. tests/kernel_mvp.rs asserts the count.
A pane's render is not guaranteed once per frame. A pane that declares
pure = true asserts its render is a function of the published tables and its
render context, and the kernel then reuses the tree it last returned while both
stand — skipping the Lua call and the table→node conversion, which together were
the largest cost in a frame. Undeclared panes are called on every frame they are
drawn on, exactly as before. See docs/thurbox/plugins.md → Traps for what disqualifies
a pane, and ADR-P16 in docs/thurbox/performance.md for the measurements.
2. Layout resolves before render. Rects are computed first, then each plugin is called with its own. A plugin that does not know its width cannot wrap, truncate, or derive a scroll window — this was the single biggest gap the prior attempt reported. The circularity is broken by plugins declaring their size statically, in their declaration table, not in render output.
3. Snapshot-read, command-write. Reads are served from an in-memory snapshot and return instantly. Writes are commands that are accepted and surface later. Lua never blocks and never awaits, so no plugin — including ones nobody has written — can stall the loop on Fleet, git, or an unreachable host.
4. Capabilities by absence. An ungranted capability is not in the environment. Not blocked; absent. The file viewer needs file contents, so the kernel reads them and the plugin draws — it does not get a filesystem. The granted set is asserted by a test, so adding one is a deliberate edit.
5. Anything that touches the world runs on a worker. Attaching a terminal,
running a command, computing a diff, sampling metrics and answering the creation
flow's questions all do the same thing: work off the render path, publish the
result. When you add another, follow the pattern. (Attach is the one with the
sharpest teeth: it opens the backend's control-mode connection, so a host that is
down runs out its ssh timeout — inline, that was the whole interface frozen
before its first paint. It also needs the runtime entered on the worker, since
adopting a pane wires its reader and writer as tokio tasks.) (kernel::metrics is the
clearest to copy: sysinfo walks /proc and a pane's pid is a control-mode
round trip — one cadence, one published result. Account quotas are not among
them: a provider query belongs to a plugin granted run, not to the kernel.
kernel::repos is the newest, and adds the one wrinkle the others do not have:
its reads are parameterised — which directory, which repository — and a
plugin cannot call something that waits, so the flow asks by leaving a key in
store and the loop serves it.)
kernel::worker_store::WorkerStore<K, V> provides a reusable bounded pool,
deduplication, aged answers and a change generation. Its first user is
files.read: resolving a session-rooted path and reading its text both run on a
worker. A Lua call returns nil until ready and uses the cached answer during
refresh; changed completions invalidate pure panes. See docs/thurbox/plugins.md for
its bounds and error contract. The existing specialized stores keep their
scheduling and lifecycle contracts; they are not migrated here.
The command bus serializes commands naming the same non-empty session in
dispatch order. Each active session has one worker draining its queue; queued
commands stay Queued until execution starts. Other sessions, commands without
a session and housekeeping run independently, so an unreachable host holds up
only later commands for that session. Empty queues retire without waiting for
the render loop to poll completions.
A capability that cannot be absent and useful #
"Capabilities are absent rather than blocked" is easy while the answer is always
absent: there is no os, no io, no package, and thurbox.yml says so. The
first capability a plugin can be granted breaks that symmetry — it has to be
present for the plugin that may use it and absent for every other, in one Lua
state they all share.
Each plugin runs in an environment of its own (host::api::plugin_env).
Every plugin shares one Lua state, so "the plugin running now" cannot say who
issued a call: a pane that replaced a global another pane calls — type, say —
would run its own code inside that pane's call, holding its grant and stamped
with its path. So identity is bound where a function is made, never read from
who is running. A plugin's chunk gets its own _ENV, and command, run,
files, state and require are created for that plugin with its path bound
in. Code a plugin defines resolves those names through its own environment
wherever it is called from, so a hijacking function acts as its author and
nobody else.
Reads fall through to the shared globals, which hold only what every plugin may
have; writes land in the plugin's own table, so a global one plugin sets is
invisible to the next. _G is the plugin's own table and the environment's
metatable is sealed, so the shared globals are not reachable to write to. The
shared tables are reached only through views of the plugin's own: each plugin
gets an empty table per name over a sealed metatable. string, table, math,
coroutine, utf8 and text read through and refuse a write. store is the
one that takes writes, because it is the bus between panes — a request left for
another pane, a selection the agent pane follows — and every plugin reads what
any plugin wrote. Only data crosses it: a write is converted to a stored value
(strings, numbers, booleans and tables of them; a function or a metatable is
dropped) and every read hands back a fresh copy, so one pane can tell another
something but cannot hand it code to run. A pane acting on a request it read
there issues it with its own command, under its own name: the shipped
confirmation forwards the one in store.confirm only after the user's keypress.
The views are per plugin because rawset writes past __newindex into the view
itself, and one view every plugin shared would carry that write to all of them.
Nothing on a view leads back to the table behind it — __pairs iterates through a
closure rather than returning the table as its state — and the string
metatable is sealed so getmetatable("") cannot hand one out. require has a
cache per plugin and runs a module in the requiring plugin's environment — a
shared module would be a table one plugin could rewrite under another, and a
module's command(…) has to act as the plugin that required it.
thurbox is the published data every plugin reads, so it is read-only all the
way down: each published group is frozen into read-only proxies when it is
built (api::freeze), the top-level table refuses a write, and pairs over
any of them hands back the proxy itself as the state, which the kernel's own
next reads through. Those proxies are shared, which is safe because rawset
— the one way to write past a metatable — is withheld. Their metamethods find
the table behind a proxy through a weak registry map and never capture it: a
captured table is a registry reference, a root the collector cannot see past, and
with one per proxy a rebuilt group took one full collection per nesting level to
free — a long deleted history filled the VM's ceiling within minutes. Each
plugin reads it through a thurbox view of its own, and what the kernel sets
per call (runs, granted) lives in that view: a finalizer runs inside
whichever call the collector interrupts, and through its own environment it
finds only its own plugin's values.
run and files are installed per call: LuaHost::enter puts the
plugin's own run and files into its environment, or takes them out. A plugin
that was not granted one does not get a function that refuses; it gets nothing,
which is the same world every other plugin has always had. Revoking is
therefore immediate. layout.lua runs in an environment of its own that never
holds either.
A capability once sat in the shared globals as __run_impl, and a leading __
is a naming convention rather than a boundary: an untrusted plugin could call
the other name and get a program run with the user's authority. Nothing a
plugin may not have is parked anywhere it can name. tests/kernel_mvp.rs
enumerates every global a plugin can reach and has no blanket exemption for a
leading underscore, and tests/plugin_commands.rs holds the hijack: a pane
that wraps type gets neither another pane's run nor its path on a command.
A capability asked for through command cannot be absent, since every plugin
has command. Those are gated where the command is applied instead: the queue
records the path each plugin's own command was built with, and
Command::requires/Command::refusal decide whether that plugin holds what
the command needs before the loop applies it — run for a URL opened
unasked, sessions for every verb that drives an
agent or loses something for good. Every variant answers in one exhaustive
match with no catch-all arm, so a new verb does not compile until it decides. An
action runs the declaring plugin's handler, so every request carries the
chain of plugins it came through (LuaHost::acting_for, api::requester) and is
allowed only with what every plugin in that chain holds
(Command::refusal_by): neither the asker nor the handler can lend the other a
grant, through any number of hops.
program is checked the same way when its pane is started.
The grant itself comes from one place, packages::granted → trust_of →
Trust::grants, the same decision the Interface tab draws. A bundled file that
is byte for byte what the binary ships is Shipped and holds what it declares
without a trust record — the confirmation and the creation flow need sessions
before anyone could press t — and an edited one is decided like any other file.
The cost, accepted: a plugin must handle the absence, exactly as it handles a
session having no worktree. examples/lua/composite.lua shows the shape — draw
what is missing, not a blank pane.
Events are derived, never raised #
A plugin can declare events = { … } and an on_event(name, payload), and the
loop calls it once per change (kernel::events, coordinator::events). The
kernel's own events come from diffing published state — the snapshot's rows
between two versions, the focus ring between two iterations, the command bus's
completions — never from the code that mutates it. Raising them from the code
that mutates would miss every other process (thurbox-cli, the cron tick, a
second interface, Fleet itself), and is the model where one mutation site
forgets to fire. The four session.post_* names are the only ones raised rather
than derived — from a tracked command finishing — which is why they carry the
operation's facts and fire only for this interface's own work.
One dispatch point per iteration, after the stores and the bus have published
and before the paint, so a handler's writes land in the frame about to be
painted. It is a VecDeque::is_empty on every quiet iteration and never marks
the frame dirty itself: a handler's state write bumps the state version and
its commands go through dispatch_tracked, both of which already do
(frame-cost). Emits from handlers are applied inside the same dispatch, which
is what makes the cascade bound (MAX_DEPTH) a bound rather than a
per-iteration trickle. A reload clears the queue, resets the deriver so the next
snapshot seeds silently, and puts interface.reloaded first.
The set is closed (KERNEL_EVENTS) with three readers — the loader, help and
thurbox-cli plugin events — so a name a plugin may subscribe to is always one
the kernel emits.
Drawn is not the same as focusable #
A switch slot draws one occupant, so an alternate is not on screen — but
focusing it is what brings it forward. Ask "is it drawn?" when deciding whether
focus may rest there and the answer is no, every time, because the slot records
its selection during render and the check runs before it. That is not a near
miss: it made the plugins pane impossible to reach at all, since the focus ring
skipped alternates by the same rule and F11 was undone on the next frame. (That
pane is now a settings tab — see below — but the rule outlives it: the centre is
still a switch slot, so the next pane to share it inherits the fix.)
kernel::focus keeps the two questions apart — is_drawn for what the interface
reports about itself, can_focus for where focus may go. A pane that brings
itself forward by being focused needs the second one.
There is a third question, and it is not can_focus either: should Ctrl+H/
Ctrl+L stop here? A cycle that stopped wherever focus may rest stepped onto
every alternate, and stepping onto one draws it — walking the columns swapped the
agent's terminal for whatever else shared the centre. next_in_cycle makes a
switch slot one stop, its default occupant, and steps an alternate off the slot;
alternates are opened by their own key or pill, which can_focus still lets in.
An open float may consume that cycle with on_focus_cycle("next"|"previous").
The coordinator offers it only to the topmost drawn float, and the host calls it
under the key hook's budget and environment. true leaves pane focus intact;
false, a missing hook or an error continues through next_in_cycle. Item order
and wrapping belong to Lua, so the kernel never learns what a card or row is.
Quit, reload and recovery keys retain their reserved handling.
There is a third fact underneath both, and it is a matter of timing: a pane can
open its own slot. The search strip shows itself and asks for focus in one action,
and panels.show is only read by the arrangement — so at the moment the request
is judged, the slot it named does not exist yet and focus is refused for a rect
that is one frame away. defer_until_placed is the answer: a request focus cannot
take is held for exactly one layout and re-asked there, which is why ctrl+/
leaves you typing in the strip rather than in the pane underneath it. Exactly one
layout, because a slot still unplaced then is one nothing brings forward.
Settings are two halves of one screen #
settings.toml and a plugin's declared settings are edited from the same
modal, and they behave differently on purpose. A plugin's value is in-process,
so it is written the moment the key is pressed. A core value is a file — and
some of them (mouse capture, the notifier thread, the scrollback a parser was
built with) were consumed at startup and cannot be un-consumed — so the core
half is a draft: Ctrl+S writes it, Esc discards it, and ⟳ marks the
rows that will not take effect until the next launch. kernel::config owns that
split; session::settings::FIELDS is its one definition, a row per field saying
Live or NextLaunch, and both Config::adopt and
Settings::restart_only_differs are derived from it so the two cannot drift.
That split has a second edge, and missing it cost the panel its edits: what the
modal shows and drafts from is Config::on_disk, not Config::in_force. A
restart-only change lands in the file and is deliberately withheld from what is
running, so seeding an edit from what is running silently proposes undoing it —
the next save of any row reverted it.
There is no process-wide copy of the settings: session holds no state. The
live half lives in kernel::config; the restart-only half is handed, as loaded,
to whatever is built with it — the backends (history depth), the terminals
(scrollback, how long a hidden grid stays), the snapshot store (git cadence).
Loading first is load-bearing rather than tidy: a process-wide copy that main
never filled would ignore the whole file while every switch looked honoured,
because every default matches.
System chrome is not a pane #
Help, settings and the theme picker are drawn by the kernel (kernel::modals),
above the arrangement and above plugin floats. They were plugins in the centre
slot, and that was the wrong shape: they competed with the terminal for the
slot, they joined the focus ring, and nothing could contribute into them.
So a modal is not in the layout, not in focusable(), captures input while
open, and closes on Esc; one is open at a time, and opening one closes the
other. Modularity moved one level down — plugins contribute data
(Registry::bindings → help, Registry::settings → settings) and the kernel
renders it, so declaring one table field is enough to appear in either. The
theme picker takes no contribution at all: there is nothing a plugin could add
to a list of palettes. The command palette (Ctrl+P,
kernel::modals::palette) is the fourth, and contributes in the other
direction: it lists the registry — keys, chord-less commands declarations, the
kernel's own — and Enter hands the loop a Dispatch that runs through the
same on_action a key press takes, after the modal has closed itself.
The file list — settings' Interface tab (kernel::modals::interface) — is here
for a second reason on top of those three. It is the recovery tool: it is where a
file that failed to load is reported with its error, where a bundled file is
restored (r) and where a plugin of the user's own is switched off (space) to get
a working interface back. A recovery tool that is itself a plugin can be the thing
that is broken, so a bad edit would take away the view you would use to undo it.
Being chrome also fixed its reachability: as a centre-slot pane it needed a chord of
its own, and that chord was F11 — the one F-key terminals commonly claim for
fullscreen. Note the asymmetry the modal has to make legible, since the kernel is
the only thing that knows it: r writes back a copy the binary holds, so it has
no answer for a file the user wrote (space is that answer) or one a package
delivered (thurbox-cli plugin sync is).
The one genuinely modal input in the product lives here too: while help is
capturing a chord, every key is data, ctrl+q included. A plugin could
never be allowed to swallow the quit chord; the kernel can, because it knows
the capture lasts one keystroke.
Two things that will bite you #
The render path must not read the plugin directory. inotify reports a read
as an event, so a per-frame reader makes the host look like it is editing its own
plugins — which pushes the reload debounce forward forever, and auto-reload
silently never fires while F10 works perfectly. layout.lua is loaded once per
reload for exactly this reason.
A click is routed by identity, not by geometry a plugin declares. The paint
walk records a hitbox for every node carrying id/class/role, parents before
children, and the loop scans that list backwards — so the innermost node under
a point wins, and a pane's own rect wins only when nothing inside it matched.
Change the recording order and the collapse chevron on a pane's border silently
starts focusing the pane instead.
A pane cannot emit an escape, so a link has to be re-printed for it. A
plugin returns cells; the kernel paints them. Nothing in that path can put an
OSC 8 sequence on the wire, which is why a url a pane draws was not
Ctrl+Click-able even though the identical text in an agent's transcript was —
the transcript's runs are re-printed wrapped in the escape after the frame
flushes (paint_outer_hyperlinks), and only sessions were offered to that
leg. The url:<link> click verb is that asymmetry closed: the verb's nodes ride
the same re-print, so the outer terminal owns the chord over them, and the
kernel resolves the chord against them too for an emulator that does not
understand OSC 8. The cells are read back out of the frame just drawn rather
than off the tree, so wrapping, alignment and scroll need not be re-derived —
and the covering surfaces are checked explicitly, because a pane's node has no
label to match against the buffer the way a vt100 run does.
Terminal encodings differ, and folding them belongs in the kernel. A legacy
terminal sends a bare J with no SHIFT; a kitty-protocol one sends j plus
SHIFT. ctrl+/ arrives as one of three things. registry::canonical_chord
folds them, so a plugin declares one chord and it works everywhere. Both cases
were found by running it, not by reading the spec.
Where the boundary sits #
What kernel may reference is declared in thurbox's module rules in
crates/architecture.toml, and arch-rules fails on any other edge.
Testing #
tests/kernel_mvp.rs— the kernel against the real bundled plugins, so it fails if either breaks.tests/kernel_limits.rs— the instruction and memory bounds, in their own file because they mutate process-wide limits.
What a frame costs #
Every visible pane is rebuilt in Lua and converted back into nodes on each paint, and cost tracks node count, not data: a synthetic plugin emitting 30 trivial rows costs the same as the real session list, and the Rust-side conversion runs at roughly 9 us per node. Micro-optimising that conversion does not pay; the levers that do produce fewer nodes or run the conversion less often:
- Paint less.
publishruns only before a paint or before dispatching input — the two moments Lua actually runs — and paints are capped at 60fps (MIN_FRAME_INTERVAL). A pane showing a terminal surface is gated on the pane's own output stamp (Terminals::output_stamp), so a quiet agent settles at the redraw floor. - Emit fewer nodes. The session list spends 4 nodes per row (a box plus a
border node either side). Drawing the borders as two full-height columns, as
20_agent.lua'schrome()already does, would take a 30-row list from ~90 nodes to ~32. - Stop probing closed modals. Every floating plugin is rendered full-screen
each frame purely to discover it is not floating, unless the float declares
pure = true(ADR-P16).
Dependencies are built with opt-level = 3 even in dev builds
([profile.dev.package."*"]), because cargo run is the documented way to run
thurbox from a checkout and an unoptimised Lua VM is felt in the UI.