Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
6aee22971This file is pinned to the selected release. Download the original to open it in your design tool.
# The cable protocol — dial ↔ harness daemon
The ESP32 dial has no WiFi, no backend socket, no credential and nothing to pair. It is served entirely
over one USB cable by the `harness` daemon running on the computer it is plugged into. Plugging the cable
in IS the authorization.
This document is the only thing the two halves share. They are written in different languages and import
no code from each other — one is C on a microcontroller, the other TypeScript in a daemon — so every
agreement between them is here or nowhere:
| Half | Where |
|---|---|
| Dial (C) | `device/esp32-circle/main/cable_frame.[ch]`, `cable_link.[ch]`, `cable_client.[ch]` |
| Daemon (TypeScript) | `cli/src/cable/cableFrame.ts`, `serial.ts`, `cableSession.ts`, `cableHost.ts` |
They used to ship from two different repositories, and this document said so. Since the firmware moved
into this one they are a single `git log` apart, which changes what this file is for: it is no longer
the only way to see both sides at once, but it is still the only place the WIRE is specified. A change
to one half that is not written down here is a change the other half will meet at runtime.
The framing is checked against shared vectors; the vocabulary is checked against this page.
## 0. The port
The board enumerates as exactly **one** USB device — `303a:1001`, the SoC's own USB-Serial-JTAG
peripheral. Measured on hardware, 2026-08-24: there is no second bridge, so there is nowhere else to put
the console.
The daemon finds the tty by **USB id and nothing else**. Never by name and never by "the only one there":
a laptop has other serial devices, and on the machine this was written on `/dev/cu.debug-console` sorts
first. On macOS the ids and the device path live on different nodes of the `ioreg` tree — `IOCalloutDevice`
hangs several levels below the USB device node — so the match arms a subtree at the matching node's
indentation and takes the first path inside it. A flat scan pairs a vendor id with whatever path comes next
in the dump, which is a different device.
The tty must be put in **raw mode**. In the default line discipline the kernel maps CR to NL and echoes
what is written back; a mangled frame is indistinguishable from a bad cable at the far end.
**The port is exclusive.** While the daemon holds it, `esptool` and `idf.py monitor` cannot open it, and
they fail in a way that reads exactly like dead hardware. `CABLE_DISABLE=true` leaves the port alone.
## 1. Framing
Little-endian throughout:
```
A5 5A | ver:u8 | type:u8 | len:u16 | payload[len] | crc16:u16
```
- **CRC-16/CCITT-FALSE** — poly `0x1021`, init `0xFFFF`, no reflection, no final xor. Named exactly,
because several 16-bit CRCs share that polynomial. Check value for `"123456789"` is `0x29B1`, asserted by
both suites. It covers `ver..payload`; the magic is a marker, not data.
- **`len` ≤ 8192.** A bound on damage, not a capacity target: a corrupt length field can claim 65535 bytes,
and with no ceiling the reader waits for a frame that is never coming while real ones pile up behind it.
- **Payload types:** `0x01` JSON (the vocabulary) · `0x02` PCM (dial → daemon, during a voice turn) ·
`0x03` firmware slice (daemon → dial) · `0x04` log line (dial → daemon, raw bytes).
- **An unknown type is not an error.** It is surfaced with its raw byte, so a peer running ahead reads as a
version mismatch someone can act on rather than as a link that connects and then goes quiet.
### Reading a stream that starts anywhere
The ROM and the second-stage bootloader print plain text to this port before the firmware owns it, so the
reader walks into the middle of a stream at **every boot**. On a bad CRC or an impossible length the reader
discards **one byte, not the candidate frame** — the magic may have been a coincidence inside noise, and a
real frame can begin one byte further in. A trailing lone `A5` is kept: its `5A` may not have arrived yet.
`discardedBytes` and `corruptFrames` are counters because **the rate is the diagnosis**. A handful at
startup is the bootloader's parting words; a steady trickle during a session means the two sides disagree
about the format or the cable is bad. Bytes of frames that decoded fine are not counted — that would make a
healthy link read as full of noise.
### Vectors
`device/esp32-circle/test/vectors/cable_frame.txt` is generated by
`device/esp32-circle/scripts/gen_cable_vectors.py` — a **third** implementation, written from this page and
from neither half's code, so a misreading shared by both halves shows up as a disagreement instead of being
blessed twice. Run `device/esp32-circle/test/run.sh` (C, on a laptop, no board) and
`npx vitest run src/cable/` (TypeScript). The daemon's copy is refreshed by
`cli/scripts/sync-cable-vectors.sh`.
## 2. Messages
Type `0x01` payloads are UTF-8 JSON objects with a `"t"` discriminator. **Unknown keys must be ignored**, and
a missing key falls back to a zero value rather than failing the whole message: a peer with an extra field
is not a broken peer.
**The vocabulary is the product's: machine → agent → session.** The cable is the TRANSPORT, not the
machine: the dial holds a LIST of the owner's machines and exactly one is SELECTED, and the agents on the
carousel are that machine's. The computer at the other end of the cable is one row among them — always
present, always reachable, and the only one that keeps working when the daemon is signed out or the
backend is down. An agent is a working unit inside a machine, with its own workspace and engine. A session
is one conversation underneath an agent, and the dial never sees one.
**One machine at a time, and the agent id space stays FLAT.** Switching replaces the whole agent list
rather than merging two. That is what lets `turn.*`, `summary`, `question` and every other per-agent
message stay exactly as they were: there is never more than one machine's agents on screen, so an agent id
needs no machine component and events for a machine that is not selected are dropped at the source.
### Dial → daemon
| `t` | Fields | Meaning |
|---|---|---|
| `hello` | `fw`, `proto`, `mac` | First thing after boot, and repeated (below). `mac` is also the USB serial number, so the daemon can tell one dial from another before a byte is exchanged. |
| `pong` | — | The answer to `ping`. Empty: the arrival is the content. |
| `agents.list` | — | Send me the tiles. |
| `machines.list` | — | Send me the machine wheel. |
| `machine.select` | `machineId` | The user tapped a row. Always answered — see Machines. |
| `swarms.list` | — | Send me the window's swarms. |
| `swarm.select` | `swarmId` | The user picked a swarm. NOT answered directly — see Swarms. |
| `focus` | `agentId` | The carousel settled here. A statement about where the user is LOOKING, not a request to run anything. |
| `scroll` | `phase`, `dy`, `v?` | A finger on the glass, in pieces. The dial is a TOUCHPAD here: it reports MOVEMENT, because it cannot know how tall the window at the other end is. `v` travels only on `up`, and becomes the fling. |
| `turn.send` | `agentId`, `text` | The user asked for something. |
| `turn.stop` | `agentId` | Interrupt that agent's turn, and only that one. |
| `answer` | `agentId`, `requestId`, `answers{}` | The user answered a `question`. The keys are the QUESTION's — the ones the daemon asked with — echoed back verbatim. Never the `requestId`: keying the object by that names a question nobody asked. |
| `agent.update` | `agentId`, `model?`, `effort?` | The tile's chips were changed. The daemon reassembles the runtime profile — only it knows the session id and engine. |
| `models.list` | `agentId`, `mode?`, `selected?` | The one round trip (below). |
| `voice.begin` | `agentId?`, `cmd?`, `lang`, `sr` | Start of a capture. See Voice. |
| `voice.end` / `voice.abort` | — / `why?` | |
| `voice.confirm` | `routeId`, `agentId` | Confirms a transcript that arrived with `needsConfirm`. |
| `fw.accept` / `fw.progress` / `fw.done` / `fw.error` | — / `written` / — / `message` | See Firmware update. |
### Daemon → dial
| `t` | Fields |
|---|---|
| `welcome` | `proto`, `app`, `machine:{id,name}`, `selected`, `voiceLang` — `machine` is the CABLED computer's identity (its real machineId, or `cable:<computerId>` when the daemon is signed out), no longer "the one machine". `selected` may name a different one, and is stated here so the ✓ is right before any list arrives. |
| `machines.begin` / `machine` / `machines.end` | the wheel, streamed — `{id,name,state,local}` per row; `end` carries `selected` and `source` |
| `machine.selected` | `machineId` — the switch happened; that machine's agents follow |
| `machine.error` | `machineId`, `code`, `message` — the switch did NOT happen; the selection is unchanged |
| `machine.updated` | one row changed — liveness, a rename, a count |
| `swarms` | `selected`, `items[]` of `{id,name,agents}` — the window's tabs, whole, whenever they change; empty with no window |
| `ping` | — the heartbeat |
| `agents.begin` / `agent` / `agents.end` | the list, streamed — one agent per message |
| `agent.updated` | one agent changed; the dial re-asks |
| `focus` | `agentId` — the daemon's surface moved; the carousel follows |
| `turn.started` / `turn.done` / `turn.error` | `agentId` (+ `message`) |
| `summary` | `agentId`, `recap`, `text`, `restore?` |
| `question` / `question.cancel` | `agentId`, `id`, `questions[]` |
| `models` | `agentId`, `items[]` of `{id}` |
| `voice.transcript` / `voice.error` | `routeId`, `text`, `agentId`, `agentName`, `needsConfirm` / `message` |
| `toast` | `text` |
| `fw.offer` | `version`, `size`, `sha256` |
## 2a. Machines
**The wheel is streamed and DIFFED, and the diff is not an optimisation.** Both halves keep a key over the
rows — `id:name:state:local` in arrival order, plus `selected` and `source` — and say nothing when it
matches. Order is part of it: order is render order, so a swap is a real change.
Two halves, because one is not enough. The daemon's key resets to empty on every port reopen — which any
20 s of silence causes — while the dial's model survives, so the daemon legitimately re-pushes a list the
dial already has. The dial therefore hashes the rows again and returns from `machines.end` **before taking
a display lock** when nothing moved.
The number that makes this normative: an unguarded rebuild on every arriving greeting, on the USB reader
task, measured **31 session restarts per hour** on 2026-08-24, wiping the agent list each time, with the
screen parked on "0 agents" while the daemon's log truthfully said it had sent two. Removing either half
of the guard brings that back, and it looks like broken hardware.
**`state` is one word, not two booleans** — `ready` · `offline` · `unknown` · `needs-link`. One field
cannot contradict itself; an `online` flag beside a `known` flag can, and would, the first time a list
refresh failed halfway through. `needs-link` means the daemon holds no pinned key for that machine and can
read nothing on it: an INSTRUCTION state, not a failure, and the dial shows the two commands that fix it
rather than a toast that flashes past.
**There is no agent count on a row, deliberately.** It was on the wire briefly and came off: the dial does
not draw it, and a field that is diffed but not drawn re-renders the whole wheel every time any machine's
count moves — invisibly, which is the exact failure the diff exists to prevent.
**The local row is named after its machine and marked `local: true`;** the dial turns that flag into the
row's second line, `This computer`. Two facts, one field each — the name says which machine, the flag says
which of them the cable is in. The daemon composes that row itself and DROPS the backend's duplicate of
this computer, so the same machine can never appear twice under two names with the ✓ able to mark only one
of them.
**`source` on `machines.end`** — `backend` · `local` · `signed-out` — is why the list is as short as it is.
Without it a single row reads as "you own one machine", when the truth may be "this daemon is signed out"
or "the backend is unreachable". The dial renders that difference; it is the difference between an empty
screen and an instruction.
**Selecting.** The dial marks the row pending and waits; **the selection is committed only by
`machine.selected`**. An optimistic write leaves the ✓, the Overview eyebrow, the "No agents" eyebrow and
the voice gate all naming a machine the dial is not on, the first time a select is refused. The dial gives
up after **8 s** — a remote select travels dial → daemon → backend → the far daemon, and anything shorter
makes a healthy switch look like a failure.
**Every select is answered, including one for the machine already selected.** Silence strands the dial on
its spinner until its own deadline, which reads as a hang rather than as "done, nothing changed" — the
same rule `models.list` follows.
**The daemon's cloud lane lives and dies with the CABLE.** The daemon holds a socket to the backend on the
dial's behalf — nothing else in the daemon uses it — and it opens the moment a dial greets, whatever is
selected. Connecting is not attaching: the backend's relay starts UNATTACHED and only gains a commander
client from `machine_select`, so a held socket buys device presence and a LIVE machine list without making
any machine believe someone is watching it. Without it the wheel's dots are a REST snapshot up to a minute
old, and a machine that just came up stays grey while the user looks at it.
**The selected machine is announced even when it is the local one.** It costs one frame, and it is the
only thing that keeps `DeviceBinding.activeMachineId` — what the web and the mobile app read to say where
a dial is — true rather than naming whatever was picked last. This computer needs no pinned key to be
selected: its agents are read in-process, never over the relay.
The moment the dial stops being there the lane closes: the account stops showing a device attached to a
machine while the dial sits unplugged in a drawer, and that machine's cards stop being relayed to a screen
nobody is looking at.
A pulled cable and a port that simply went quiet are ONE case — both are "no dial" — so the close path is
the same for both. When the dial greets again the lane is reopened before the state push, because that
push reads the selected machine and for a remote one that is an RPC over the very lane being reopened. A
repeat greeting from the same dial on the same firmware is a keepalive, not an arrival: reopening on every
one would dial the cloud every fifteen seconds for as long as the dial sits there.
Going back to the LOCAL machine is different and lingers instead — the user looked away, the dial is still
here, and flicking between two machines must not pay a fresh dial each way.
**The daemon remembers the selection; the dial does not.** It is re-stated in `welcome.selected` and in
every `machines.end`, so a dial-side copy would be a second source of truth that disagrees the moment the
same account is driven from somewhere else. A restored id is also meaningless until you know whose computer
the cable is in — eagerly re-selecting one on connect is how a spurious "not your machine" toast used to
appear on every boot. Neither side persists it across its own restart: the local machine is the honest
fallback, being the only one that is certainly reachable.
**The agent list is streamed** — begin, one message per agent, end — not sent as one array. A frame is
capped at 8 KB and a hundred agents do not fit in it. One agent per message needs no chunk arithmetic on
either side and bounds the message length by construction rather than by hoping the names stay short.
**Turn messages are unsolicited.** `turn.*` is not a reply to `turn.send`: the daemon reports every turn in
every agent, including ones started at the keyboard. A reader that only expects them after its own send
sits idle through most of what the machine actually does.
**`turn.done` does not ring.** It stops the spinner. The `summary` that follows is what the dial beeps and
notifies on — a turn's completion is announced by the thing a person can act on, and ringing on both is how
an empty turn produced a beep and a blank notification.
**`summary` has two meanings, told apart by `restore`.** Sent unasked it is news: it rings, badges and wakes
the screen. Sent with `restore: true` — which the daemon does for each agent's last few turns right after
`agents.end` — it is history being filled back in, and the dial takes a door that changes no live state.
Without that flag, plugging the cable in announces every turn that finished while it was unplugged.
The summaries are on the daemon's disk (`summaries.json` and `summaries-history.json`), so a dial that
reattaches after a reboot, a replug or a daemon restart gets its tiles back with the work they belong to.
Up to three turns per agent are kept: enough for the voice router to tell one agent's subject from
another's, few enough that one chatty agent cannot crowd the others out of the decision.
## 2b. Swarms
A swarm is one of the desktop window's tabs: a named group of agents arranged on one grid. The window
owns them — they live in its state file and nowhere else, and the daemon has no opinion about their
contents. What crosses this wire is the list of names, which one is on screen, and a pick.
The carousel does not need a swarm to walk one. The daemon's ring is already the window's open panes
(`app_panes` on the local socket → `agents.end.ring`), and the window's open panes ARE the active swarm's,
so switching tabs in the window has always re-shaped the ring. `swarms` adds the NAME of that tab, drawn
above the agent on every tile, and `swarm.select` adds the way to pick another from the glass.
`swarm.select` is relayed to the window as `dial_swarm` on the local socket, and the window switches by
the same path a ⌘] takes. Nothing is answered on the cable: the window re-describes its desk, and the
`swarms` frame (new `selected`) and the agent list (new ring) that follow are the answer. The dial writes
nothing optimistically, for the reason the machine wheel's ✓ waits for `machine.selected`.
With a window present, an EMPTY desk means an empty ring — a fresh swarm has no panes, and the carousel
shows none rather than every agent the window is deliberately not showing. With no window (no `app_swarms`
ever received, or the socket closed) the old fallback holds: the ring is the whole list.
## 3. The session, and how each side knows the other is gone
Over a cable there is no connection to lose: the daemon quitting looks exactly like the daemon having
nothing to say. Both are silence.
| | |
|---|---|
| Daemon sends `ping` | every 5 s, regardless of activity |
| Dial answers `pong` | immediately |
| Dial declares the daemon gone | after **15 s** with no message of any kind |
| Daemon declares the handle dead | after **20 s** with no bytes — then closes the port and reopens it |
| Dial while it thinks nobody is there | re-sends `hello` every 2 s (15 s once a session is up) |
The two windows differ so a single late message cannot trip both at once and have each side conclude the
other left.
**Why the daemon needs `pong` at all:** after the dial reboots, macOS hands back a `/dev/cu.usbmodem*` node
with the same name, the same inode and the same device numbers. Writes to the old handle keep succeeding,
the read stream never completes, and nothing raises. Without a heartbeat the daemon talks to a dead file for
as long as anyone watches.
**Answer every `hello`; re-attach only for a dial you have not already greeted.** Attaching means "this
device knows nothing" and pushes the whole state again. Doing that on every greeting re-sends everything
every 15 seconds and undoes the rule that keeps an idle link idle. Compare the `mac`: a repeat from the same
board is a keepalive.
## 4. Logs share the wire
There is one USB port, so while a session is up the firmware routes `ESP_LOG` through the link as `0x04`
frames and the daemon appends them to `~/.harness/cli/data/dial.log`. That file is the dial's console for as
long as the daemon holds the port.
When no session is up the sink is removed and the port carries ordinary console text, so `idf.py monitor`
behaves exactly as it always has. Framing logs unconditionally would cost the only debugging instrument this
board has, in exactly the situation where it is needed most.
What cannot be framed is by design: the ROM, the bootloader and the **panic handler** write directly. The
decoder walks through them a byte at a time and counts them.
## 5. Voice
The dial captures, the daemon transcribes. The device holds no cloud credential and never talks to one.
```
voice.begin{agentId?, cmd?, lang, sr} → PCM frames (0x02) → voice.end
↓
daemon: concat → STT → route (if no agentId) → deliver
↓
voice.transcript{routeId, text, agentId, agentName}
```
- **PCM is raw**, 16-bit mono at the rate `sr` states. Not base64: the framing carries a length, so there is
no reason to spend a third of the wire escaping binary into text the way a line-delimited protocol had to.
- **`sr` travels.** Describing 8 kHz audio as 16 kHz does not make the speech sound fast — the transcriber
is handed a container that lies about itself and answers with nothing at all.
- **`agentId` is OMITTED, not empty**, when the user spoke from the Overview. Absence is what tells the
daemon it has to route the transcript itself; an empty string reads as "this agent", and there is no agent
called `""`.
- **PCM NEVER CROSSES THE RELAY.** The daemon transcribes and routes locally, and only the resulting turn
travels to a machine that is not this computer — as text, after the words are already words. That is why
reaching another machine needed no change to this section at all, and why there is no second capture
path to keep in step with the one above.
- **Routing is the daemon's.** It scores by name and recent activity and only asks an engine CLI the machine
is already running when the score cannot separate the top two. No key, no relay, no network.
- **`lang` is the dial's decision.** `welcome` carries a `voiceLang` PROPOSAL read from the computer's
locale; the dial keeps its own choice in NVS and states it on every capture, because the person holding it
may well speak something other than the laptop is set to.
## 6. Models — the one round trip
Everything else is fire-and-forget, which is what keeps a spoken turn off the critical path. The picker is
the exception: there is nothing to draw until the catalog is in hand, so `models.list` blocks the dial's
refresh task (never its UI task) for up to 4 s.
**The daemon answers even when the catalog is empty or the provider throws.** Silence strands the dial on a
spinner until its own timeout, which reads as a hang rather than "this engine has no choices".
## 7. Firmware update
The daemon carries the image; the dial applies it over the same cable it is already talking on.
```
fw.offer{version, size, sha256} → fw.accept → 0x03 slices → fw.progress … → fw.done | fw.error
```
**Nothing is sent until `fw.accept`.** The dial decides when it is willing — an update must never begin in
the middle of a turn the user is watching. Declining is simply not answering.
**An offer that FAILS is not offered again for the rest of the session.** Accepting makes the dial erase a
flash slot before it answers, so retrying on every `hello` would spend erase cycles on the user's hardware
every fifteen seconds, and nothing about the next `hello` changes what went wrong.
The dial verifies `sha256` over what it actually **wrote**, not over what it thinks it received, and keeps
running the old image if it does not match. Two OTA slots exist for exactly this, so a failed update costs a
reboot and nothing else.
### Flow control — three numbers that are one decision
| Number | Where | Value |
|---|---|---|
| Credit window | daemon | 16 KB unacknowledged |
| Ack cadence | dial, `fw.progress` | every slice (8192 B) |
| Receive ring | dial, `USJ_RX_BUF` | 32 KB |
`fw.progress` is **not only a progress bar. It is the ACK that opens the credit window.**
Changing any one of these alone reintroduces a bug that fails silently and at the far end. The constraint is
hardware, not taste: **the ESP32-S3 USB Serial/JTAG peripheral has no back-pressure.** Its ISR drains the
hardware FIFO unconditionally and pushes into the ring without checking whether the push succeeded, so bytes
that do not fit are dropped there and neither side is told — no NAK, no short write, no error. Sending
faster than the dial reads does not slow the sender down, it shreds the stream. The dial's reader task is
also the task that writes flash, so it is blocked for ~16 ms per slice with nothing draining the port; the
window must fit in the ring with room to spare for that.
Measured on this hardware by the sibling firmware, not reasoned: a first transfer with a 128 KB window and
an ack every 64 KB wrote **0 of 1,342,160 bytes**.
### Which image, and the trap in it
The daemon offers the image published to GCS (`harness/esp32/ota/metadata.json`), not one bundled into its
own build — the two halves ship from different repositories and pinning them to each other would make every
release a two-repo dance.
The dial reports the version out of the **running image** (`esp_app_get_description()->version`), never a
constant in a header. Two strings from two sources cannot be kept equal by anyone: a sibling firmware had a
macro reading `0.1.0` while the image self-described as `v0.3.38-36-g…`, so every plug looked like a version
mismatch and the daemon would have offered to reflash an identical image, forever.
**A dev build is never offered an update.** A version that does not parse as a clean release semver (it
contains `-g` or `-dirty`) is somebody's local build, and overwriting it with the published one is the
"flashed back to yesterday's image and nothing looked broken" failure the sibling measured.
## 8. Versions
Two numbers, bumped for different reasons:
- **`CABLE_FRAME_VERSION`** — the envelope. Changing it breaks every reader.
- **`CABLE_PROTO_VERSION`** — the vocabulary. Adding a message is a change here and needs no new reader.
**Now 2**: the machine wheel, `welcome.machine` meaning the cabled computer rather than "the" machine,
and `answer` reading the shape the dial has always sent. The envelope did NOT move, and must not for a
change like this — it is what carries `fw.offer`, so bumping it would remove the mechanism that repairs
a mismatch.
Conflating them makes the cheap change look as expensive as the expensive one. A mismatch is **a state to
display, not an error to swallow**: the daemon carries a firmware image and can offer to fix it over the
same cable.