Sidecar windows
Draft: the bounded tree a sidecar window draws (the Glyph's conversation window first): thirteen closed node kinds with stable ids, props, roles and stable accessibility labels; one snapshot then patches with a generation and a base revision; 1 MiB, 4,096 nodes and depth 64; resync on a gap; the closed refusals with their paths; checked by crates/sidecar_envelope.
Living doc, checked against the code 2026-11-14
sidecar-envelope.v1 — the bounded tree a sidecar window draws: one snapshot, then revisioned patches
- Status: draft, additive: nothing on the gateway’s wire changes. The validator is
crates/sidecar_envelope(serde only). The producer iscrates/convo_feed/src/envelope.rs(Producer): a snapshot, then a checked patch per change of the feed. The consumer is the GPUI windowapps/convo-gpui, which holds both halves in one process and draws one view per node. - Scope: a producer reduces what it knows to a tree of typed nodes and sends a snapshot of the tree, then patches. A consumer (a sidecar window’s view) keeps the tree, draws it, and asks for a fresh snapshot when it falls behind. Every frame is bounded, every node kind is closed, and every node carries its accessible name.
- One flow in v1: the conversation window’s
feed, from the feed reducer (
crates/convo_feed/src/feed.rs) to the view that draws it. Both halves can live in one process or on two ends of a pipe; the frames and the checks are the same. The Admin’s pop-out windows do not speak this envelope.
Frames
One JSON object per frame, tagged by type. On a pipe, one frame per line (NDJSON), and a line is at most 1 MiB.
snapshot (producer → consumer)
{"type": "snapshot", "generation": 1, "revision": 1, "root": "window", "nodes": [
{"id": "window", "kind": "window", "label": "Conversation window", "props": {}, "children": ["header", "log", "jobs"]},
{"id": "header", "kind": "header", "label": "Conversation status", "value": "listening",
"props": {"phase": "listening"}, "children": []}
]}
| field | type | rule |
|---|---|---|
generation |
integer ≥ 1 | the producer’s epoch: a new one after the producer restarts or rebuilds its tree from scratch |
revision |
integer ≥ 1 | the tree’s revision within the generation |
root |
id | a node of kind window |
nodes |
array of nodes | at most 4,096; ids unique; every node reachable from root; each node held by one parent |
patch (producer → consumer)
{"type": "patch", "generation": 1, "base_revision": 1, "revision": 2,
"upsert": [{"id": "turn.t2.reply", "kind": "reply", "label": "Reply", "description": "streaming",
"props": {"text": "Which room, the office or the kitchen?", "state": "streaming", "voice": "brain"},
"children": []}],
"remove": []}
| field | type | rule |
|---|---|---|
generation |
integer ≥ 1 | the generation of the tree it changes |
base_revision |
integer | the revision it builds on |
revision |
integer | exactly base_revision + 1 |
upsert |
array of nodes | at most 4,096; a new id adds a node, a known id replaces it whole |
remove |
array of ids | at most 4,096; never the root; never an id that is also upserted |
A patch is applied whole or not at all. To add a child, the producer upserts the parent with its new children and
the child itself. To remove one, it upserts the parent without it and removes the child (and the child’s own
children). A reply that streams is one upsert of its own node per patch: nothing else in the tree is touched.
resync (consumer → producer)
{"type": "resync", "generation": 1, "revision": 2, "reason": "gap"}
The tree the consumer holds (generation, revision; both 0 before any snapshot) and why it wants a snapshot:
gap, generation, no_snapshot or refused. The producer answers with a snapshot of its current tree.
Nodes
| field | type | rule |
|---|---|---|
id |
string | 1 to 128 bytes of [A-Za-z0-9._:-]; stable for the node’s life in a generation |
kind |
one of the kinds below | stable: a patch that changes a known id’s kind is refused (kind_changed) |
label |
string | the accessible name: 1 to 512 bytes, not blank, no control character; stable: a patch that changes a known id’s label is refused (label_changed) |
description |
string, optional | live words (a state, a duration): at most 2,048 bytes; newlines and tabs allowed |
value |
string, optional | the live value (the phase, a reply’s tail): at most 2,048 bytes; newlines and tabs allowed |
props |
object | the kind’s props only (the table); an unknown prop, a missing required one or a word outside its list is bad_prop |
children |
array of ids | the kinds the kind may hold, in drawing order; no id twice |
The role a renderer publishes is fixed by the kind (the table), so it is not on the wire and cannot disagree with it.
The kinds (closed)
Short strings refuse any control character; texts allow newlines and tabs. Every bound is in bytes.
| kind | role | holds | props (required) | from the feed (feed.rs) |
|---|---|---|---|---|
window |
group | header, log, jobs (each at most once) |
none; always the root | the window |
header |
status | nothing | phase (≤ 64), model (≤ 128), tools_bound (count) |
Feed.phase_word, model, tools_bound |
log |
list | turn, divider, notice |
none | Feed.items |
turn |
group | user_line, reply, ask (each at most once), action, panel |
none | Item::Turn |
user_line |
text | nothing | text (≤ 16 KiB), final, typed, revised (booleans), capture (a capture’s id, ≤ 64), capture_words (its counts, ≤ 160; capture.v1) |
UserLine |
reply |
text | nothing | text (≤ 64 KiB), state (waiting, streaming, done, interrupted), voice (brain, gateway, readout, relay, herdr) |
Turn.reply, reply_state, voice |
action |
text | nothing | name (≤ 128), via (brain, door), state (running, ok, error), detail (≤ 512), ms (count) |
Action |
ask |
group | nothing | title (≤ 512), options (≤ 16 strings of ≤ 128), answer (≤ 512), outcome (≤ 64) |
AskBack |
panel |
image | nothing | render_id (≤ 128), panel_kind (≤ 64), status (partial, complete), title (≤ 160), data (an object) |
Panel |
divider |
text | nothing | words (≤ 160) |
Item::Divider |
notice |
status | nothing | code (≤ 64), words (≤ 512) |
Item::Notice |
jobs |
list | job |
none | Feed.jobs |
job |
list_item | nothing | job_kind (background, herdr, reading, alarm), title (≤ 160), state (running, paused, blocked, ringing, done, failed, cancelled), inferred (boolean), detail (≤ 512), elapsed_ms (count) |
Job |
A panel’s data is the render’s body as the gateway sent it. The envelope bounds only its share of the frame’s bytes,
and the consumer checks it with the body’s own contract (panel-card.v1 for card.v1) before it
draws.
Accessibility
Every node’s label is its stable name: “Reply”, “Turn 3”, “Tool: weather”, “Background job: search”. What changes goes
in value or description: a reply’s state (“streaming”), a job’s state and duration (“running, 12 s”), the phase
(“listening”). A consumer publishes each node with its id, the kind’s role and the label (.id() + .role() +
.aria_label() in GPUI). So every node is named from the first snapshot, and a streaming reply posts no title change.
A consumer that virtualises its log publishes the rows it draws: convo-gpui’s log (a gpui-fast list()) publishes the
rows on screen.
The consumer’s rules
State::apply in crates/sidecar_envelope/src/lib.rs is the reference.
| frame | the tree holds | outcome |
|---|---|---|
| snapshot | nothing; an older generation; the same generation at an older or equal revision | applied: the tree is replaced |
| snapshot | a newer generation, or the same generation at a newer revision | ignored: the tree never rewinds |
| patch | no snapshot yet | resync no_snapshot |
| patch | an older generation | resync generation |
| patch | a newer generation | refused, stale_generation |
| patch | a revision newer than base_revision |
refused, stale_base |
| patch | a revision older than base_revision |
resync gap (a patch was lost) |
| patch | exactly base_revision |
applied whole, or refused whole |
A refused frame and a resync leave the tree exactly as it was. After a refusal the consumer may send resync
refused to start clean. After a resync it drops patches until a snapshot comes.
check_stream (crates/sidecar_envelope/src/stream.rs) applies a recorded stream, one frame per line, to one
fresh tree by these rules. It reports the counts, each refused line’s reason and the final tree’s panel labels.
convo-gpui --envelope-out <file> records a live window’s frames; convo-gpui --check-envelope <file> checks them.
Errors
Each refusal names a closed reason and where: a path of field names and indexes joined by dots (nodes.3.label),
or tree.<id> and tree.<id>.children.<n> for a fault in the tree’s shape.
| reason | example | at |
|---|---|---|
too_large |
a frame over 1 MiB (refused before it is parsed) | (empty) |
shape_mismatch |
an unknown kind, an unknown field on a node, a frame that is not JSON | (empty) |
bad_revision |
generation 0; a patch whose revision is not its base + 1 | generation, revision |
too_many_nodes |
4,097 nodes in a snapshot; a patch upserting 4,097; a patch that would grow the tree past 4,096 | nodes, upsert, tree |
bad_id |
div s1 (a space) |
nodes.3.id |
duplicate |
an id twice in a snapshot; an id upserted and removed in one patch | nodes.16.id, remove.0 |
bad_label |
a blank label; one over 512 bytes | nodes.3.label |
bad_text |
a control character in a notice’s words; a description over 2,048 bytes | nodes.13.props.words |
bad_prop |
color on a divider; a reply without state; voice: robot |
nodes.3.props.color |
missing_node |
a child that is not among the nodes; removing an id the tree lacks | tree.jobs.children.1, remove.0 |
cycle |
a node held by two parents, or the root held by one | tree.turn.t1.children.4 |
too_deep |
a node at depth 65 (the root is depth 1) | tree.turn.62 |
unreachable |
a node the root does not reach | tree.notice.n2 |
bad_child |
a root that is not a window; a leaf with children; a reply under the log; two replies in a turn | tree.log, tree.div.s1, tree.log.children.4 |
label_changed |
a patch renaming “Reply” to “Reply, streaming” | upsert.0.label |
kind_changed |
a patch turning a reply into a notice | upsert.0.kind |
root_removed |
a patch removing the window | remove.0 |
stale_base |
a patch on base 1 when the tree is at 2 | base_revision |
stale_generation |
a generation-1 patch when the tree is generation 2 | generation |
Compatibility
- v1 is closed: an unknown kind, an unknown field on a node or a frame, or an unknown prop is refused, not skipped. A
new kind or prop is a new contract version (
sidecar-envelope.v2). Within the one Vulpine.app bundle both ends ship together. - The stdin words (
session <id>,toggle,show,capture,mouth,level) are not envelope frames. A window that takes frames on the same pipe tells them apart by the first byte ({) and ignores any other line. The words are spelled once, incrates/sidecar_envelope/src/lines.rs(lines::Word,lines::word_of). Each word aftertoggleis additive: a window built without it ignores the line, and a malformed argument is no word. show. Vulpine.app writesshowwhen a render card for its own session arrives while the window runs and its “Cards open in” option names the window. The window slides in (a shown window stays shown) and draws the panel it held while hidden in the show’s one patch. The app then draws no corner card, and still sends the render receipt. A window never shows itself on a panel: the app decides.capture region/capture window(capture.v1).vulpine-glyphctl capture [--window|--region]and Vulpine.app’s menu item Capture… write it. The conversation window opens its capture flow (macOS’s picker, then the mark-up window). The window answers nothing on the pipe: its Send isvulpine-glyphctl capture send <id>. Auser_linethat carried a capture has the optional propscapture(its id) andcapture_words(its counts).mouth <open> <form> [viseme]. The played audio’s mouth for the fox window’s Avatar portrait. While the window runs with the Avatar look, the app writes each reading its playback analyzer (Client Core’sgetMouth) takes of the reply: the opening and the form (round 0 to wide 100) in whole percent, and the vowel it heard (aa,ih,ou,ee,oh) when it heard one. The type islines::Mouth; the writer isapps/glyph/src-tauri/src/convo_mouth.rs, fed byapps/glyph/src/portraitMouth.ts. It writes at most one reading per sampler poll (33 ms), renewed every 200 ms while the mouth is open, and the shut reading once. Numbers only.level <percent>/level off. The mic’s level for the conversation window’s voice strip, under its header. While the window runs and the app’s mic listens (listening or armed), the app writes each reading of Client Core’sgetInputVolumein whole percent, when it moved by a point and at most one every 25 ms. A quiet mic writes nothing.level offis written once when the mic is turned off, and the strip forgets what it heard. The type islines::Level; the writer isapps/glyph/src-tauri/src/convo_level.rs, fed byapps/glyph/src/convoVoice.ts. Numbers only.mouthandlevelnever start a window.
The producer’s choices
convo_feed::envelope maps the feed as the table says, and adds what the table leaves open:
- Ids.
turn.<n>from the feed’s own turn key, its partsturn.<n>.user,.reply,.ask,.action.<i>and.panel.<render id>;div.<key>,notice.<key>,job.<key>, any character outside the id alphabet as_. - Labels stay the names first sent. The producer remembers the label it gave each id and keeps it (a divider whose
words gain the model, a panel whose title arrives with its complete body), so it never sends
label_changed. A turn is “Turn”, numbered in the order the producer first saw it. - A running clock is no patch. A job’s
elapsed_msis resent only with another change to the job. The consumer ticks the clock itself from when it got the value. - Bounds. Texts are clipped at a character boundary to their props’ limits (a reply’s
valueis its last 2,048 bytes), and a tree over 4,096 nodes or the frame budget drops its oldest log entries first.
See also
- ADR 0046 (the sidecar, as amended).
- panel-card.v1 (a panel’s body).
benchmarks/fixtures/sidecar-envelope.v1/README.md(the fixtures).