Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 is crates/convo_feed/src/envelope.rs (Producer): a snapshot, then a checked patch per change of the feed. The consumer is the GPUI window apps/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, in crates/sidecar_envelope/src/lines.rs (lines::Word, lines::word_of). Each word after toggle is additive: a window built without it ignores the line, and a malformed argument is no word.
  • show. Vulpine.app writes show when 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 is vulpine-glyphctl capture send <id>. A user_line that carried a capture has the optional props capture (its id) and capture_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’s getMouth) 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 is lines::Mouth; the writer is apps/glyph/src-tauri/src/convo_mouth.rs, fed by apps/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’s getInputVolume in whole percent, when it moved by a point and at most one every 25 ms. A quiet mic writes nothing. level off is written once when the mic is turned off, and the strip forgets what it heard. The type is lines::Level; the writer is apps/glyph/src-tauri/src/convo_level.rs, fed by apps/glyph/src/convoVoice.ts. Numbers only.
  • mouth and level never 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 parts turn.<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_ms is 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 value is 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).

Was this page helpful?