---
title: "Sidecar windows"
description: "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."
type: "living"
source: "docs/contracts/sidecar-envelope.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **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)

```json
{"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)

```json
{"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)

```json
{"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](/docs/contracts/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](/docs/contracts/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](/docs/contracts/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 <n>", 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](/docs/contracts/panel-card.v1) (a panel's body).
- `benchmarks/fixtures/sidecar-envelope.v1/README.md` (the fixtures).
