The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import { readCompanionIdentity, type CompanionIdentity } from './companionProtocol.js'
// The message layer: what the daemon and the dial SAY to each other, on top of the bytes serial.ts moves.
//
// Written twice — here and in devices/harness-device/firmware/main/cable_client.c — with no shared code, because one half
// is TypeScript on a laptop and the other is C on an MCU. The framing underneath agrees by shared vectors;
// this layer agrees by docs/cable-protocol.md and by being small enough to read in one sitting.
//
// THE VOCABULARY IS THE PRODUCT'S: machine → agent → session. The machine is this computer, the agents
// are what the registry holds, and a session is one conversation underneath an agent.
//
// Three rules here were paid for on real hardware and are not style:
//
// 1. ANSWER EVERY `hello`, RE-ATTACH ONLY FOR A DIAL NOT ALREADY GREETED. The dial greets on a cadence
// because it has no port-open event to wait on. Attaching means "this device knows nothing" and
// pushes the whole state again; doing that on every greeting re-sends everything every 15 seconds.
//
// 2. PING EVEN WHEN IDLE, AND REOPEN THE PORT ON SILENCE. 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 never completes, and nothing raises. Without a heartbeat
// this daemon would talk to a dead file for as long as anyone watched.
//
// 3. SAY NOTHING WHEN NOTHING CHANGED. That is what keeps the link idle during a long turn, and it is
// why rule 2 has to exist at all.
import { CABLE_MAX_PAYLOAD, CableDecoder, CableType, encodeCableFrame } from './cableFrame.js'
import { DialLog } from './dialLog.js'
import { FirmwareTransfer, otaKeyFor } from './fwPush.js'
import { PACK_VERSION } from './pets/pack.js'
import { planPetSync } from './pets/sync.js'
import type { PetStore } from './pets/store.js'
import type { PetDialState } from './pets/sync.js'
import { SerialLink, findDialPort } from './serial.js'
import { PLAYER_PAGE_SIZE, playerPage, type PlayerSession } from './playerLibrary.js'
import { PassageCarry, withCarriedPassage, type CarryRead } from './passageCarry.js'
import { VoiceDraft, type DraftPin } from './voiceDraft.js'
import { SUPER_TAB_REQUEST_PREFIX } from '../core/api.js'
import { QuestionInbox, type ReviewedAnswer, type AnswerReceipt, type QuestionSpeech } from './questionInbox.js'
import { notificationReadToken, type UnreadNotification } from '../lib/notificationRead.js'
/** Bumped when the VOCABULARY changes. Separate from the frame version, which is the envelope. */
export const CABLE_PROTO_VERSION = 3 // 3: + question.close (a question answered on another client)
const PING_EVERY_MS = 5_000
/** No bytes of any kind for this long → the handle is dead. Longer than the dial's own 15 s window, so a
* single late message cannot trip both sides at once and have each conclude the other left. */
const SILENCE_MS = 20_000
/** How often a connected port's traffic counters go to the dial's log. */
const LINK_LOG_MS = 60_000
/** Non-frame text kept per logging interval, and the shortest printable run worth keeping. */
const NOISE_MAX = 200
const NOISE_RUN_MIN = 4
const REOPEN_EVERY_MS = 2_000
// How long one attempt at opening the port may take before it is abandoned.
//
// ⚠️ THIS IS WHAT KEEPS THE `opening` GUARD FROM BECOMING A PERMANENT STALL. That guard exists to stop
// two opens racing (which stranded read loops on one tty and shredded the stream), but a guard released
// only when the attempt finishes is a guard held forever by an attempt that never does. Opening spawns
// `stty` against a device that may have just re-enumerated mid-flash; if that call hangs, the dial is
// gone until the daemon is restarted — no error, no retry, no log line saying why. Observed once: the
// link closed at 14:14 and nothing tried again for twelve minutes.
//
// TWENTY SECONDS, RAISED FROM EIGHT, because eight was under the cost of the thing it was timing.
// Measured on a dial that had just re-enumerated after a flash — the whole reason this budget mentions
// re-enumeration in the first place:
//
// 22:26:28.077 cannot open the dial: open timed out after 8000ms ← gave up
// 22:26:29.660 dial 28:84:85:90:5F:78 on fw 0.0.58 proto 3 ← opened, 1.58s late
// 22:26:29.661 machines → 3 · agents → 8 (attach) ← FULL handshake, succeeded
// 22:26:29.662 closed (abandoned — open timed out) ← and thrown away
//
// The open costs about 9.6s there, every time, so the deadline never once let a working link live: the
// cycle repeated on an exact 8-second beat for as long as anyone watched, and the dial sat on "Not
// connected" while the daemon greeted it successfully every eight seconds and hung up on it. That is
// the worst shape a timeout can take — not a slow failure, a discarded success.
//
// The stall this guards against is a `stty` that never returns, which twenty seconds catches as surely
// as eight. What it costs is the wait after a replug, and the honest number for that is the ~10s the
// open actually takes, not the 8 it was being given.
const OPEN_TIMEOUT_MS = 20_000
/** What this dial must call itself. A greeting that does not say exactly this is another product's. */
const CABLE_PRODUCT = 'harness'
// How long a port may deliver BYTES WITHOUT A SINGLE DECODABLE FRAME before it is written off as another
// product's dial.
//
// The magic (cableFrame.ts) makes the sibling product's frames undecodable here, which is the point — but
// it also means a foreign dial looks exactly like a chatty port that says nothing we understand. Left
// alone we would hold that port open forever, and two daemons reading one tty is not a stalemate: each
// takes a share of the other's bytes, so frames arrive interleaved and BOTH links fail. Measured on this
// hardware: five readers on one stream cost 18 of 22 greetings.
//
// Generous on purpose. Our own dial is silent-then-noisy across a reboot — the ROM and the bootloader
// write plain text to this same wire before the application starts framing anything — so a short window
// would evict a dial that was merely booting.
const FOREIGN_AFTER_MS = 12_000
// Most firmware writes one dial may take in an hour. A real release is one; anything repeating is two
// pieces of software disagreeing about who owns the board, and the dial pays for that in erase cycles.
const FW_WRITES_PER_HOUR = 3
/** How often the machine list is re-read. Slower than the agent list because it is an HTTP read, not a
* map lookup — and because a machine appearing is not something anyone is waiting on a stopwatch for. */
const MACHINES_POLL_MS = 15_000
/**
* A programmatic focus write may be followed by the dial reporting the tile it was painting just before
* that write. Real hardware delivered that stale report 23 ms after the machine switch completed; keep
* a short transaction open until the commanded tile echoes, without making the dial feel unresponsive.
*/
/**
* How long a focus COMMANDED by the window keeps the dial's own reports out.
*
* Deliberately SHORT, and it was briefly 4s — which broke the thing it was meant to protect. The echo it
* guards against is gone at the source now: a dial told where to look moves through code, and a move made
* by code is not reported at all (carousel_goto in ui_screens.c). What a long window does instead is
* swallow a REAL swipe made in the seconds after any click in the window — the two screens then sit on
* different agents with nothing to correct them, which is exactly the report that followed.
*
* So it stays only as long as a stale echo from an OLDER firmware could take, and every report it drops
* now says so in the log.
*/
const APP_FOCUS_SETTLE_MS = 750
/**
* How long after an app-driven switch begins its own repaint can still arrive.
*
* The switch itself is NOT the measure, and using it as one is what broke: selecting a remote machine
* takes seconds — ten, measured — and while `drivingAppFocus` was true every report was discarded, so a
* swipe made during it vanished and the two screens ended up on different agents.
*
* A repaint answers the command almost at once; a hand does not. So the guard lasts as long as the first,
* not as long as the whole errand.
*/
const APP_SWITCH_REPAINT_MS = 1_000
/** What a `voice.begin` without an `sr` is assumed to be — firmware old enough not to say. */
const DEFAULT_VOICE_RATE = 16_000
/** A voice turn longer than this is a stuck dial, not a person talking. 16 kHz mono 16-bit ≈ 32 KB/s. */
const VOICE_MAX_BYTES = 10 * 60 * 32_000
/** What a `swarms` item's `members` says about one member id (see CableSession.memberMeta). */
export interface SwarmMemberMeta { id: string; name: string; engine: string; machine: string; online: boolean }
/** The live footer of an agent's pane, and what a `activity: 'steps-v1'` device is told beside it. */
export interface ActivitySnapshot {
text: string
/** The footer's own timer, in seconds. */
elapsedSeconds?: number
/** The latest paragraph the assistant wrote; independent of the footer. */
action?: string
}
/** The device keeps 192 B of the agent's latest sentence (cable.md); a longer one is cut on a character boundary. */
const ACTION_MAX_BYTES = 188
/** What the Pro's firmware holds of a swarms frame: 24 tabs, 24 ids each, and 512 JSON tokens (480 here). */
const SWARMS_MAX = 24
/** The Pro's Swarm cards: at most 16 Swarms of 12 Leads, a change held this long so a burst is one push. */
const SWARM_CARDS_MAX = 16
const SWARM_LEADS_MAX = 12
const SWARM_CARDS_DEBOUNCE_MS = 300
/** A Super Tab, project or agent id as the backend writes them. */
/** The Pro keeps an id in 48 bytes with its NUL. */
const CARD_ID = /^[A-Za-z0-9_-]{1,47}$/
/** A `supertab.recap` frame the Pro takes at most this many bytes of JSON for. */
const RECAP_FRAME_MAX = 6 * 1024
/** Repeats of one Lead's recap request inside this are ignored; a device that picks another stale announce within this is not followed. */
const RECAP_REPEAT_MS = 1000
const PICK_ECHO_MS = 2000
/** Cards still not read this long after attach: the dial is told there are none, not left on a list nobody vouches for. */
const CARDS_UNREAD_MS = 10_000
/** The recap frame, its text shortened (on a character) until the whole JSON fits what the Pro reads. A chat's recap names
* its chat (`chatId`), for a round dial that speaks swarmChat; any other is today's frame. */
export function recapFrame(r: LeadRecap): Message {
return fitText(r.text, (text) => ({ t: 'supertab.recap', tab: r.tabId, lead: r.leadId, text, at: r.at, none: r.none, ...(r.chatId ? { chatId: r.chatId } : {}) }))
}
/** A Lead's entry for a swarmChat dial: its face chat, `work` only for a working group (with that group's clock), and never
* `ask` or `stuck`, which a group's state used to raise. A Lead whose chat did not come through reads as its Lead chat. */
function chatLead(l: SwarmLead, chat: SwarmChat | null | undefined = l.chat): Record<string, unknown> {
const working = chat?.kind === 'group' && chat.working
return { id: l.id, projectId: l.projectId, project: l.project, engine: l.engine, owner: l.owner, local: l.local,
state: working ? 'work' : 'done', order: l.order, ...(working && chat.since !== undefined ? { since: chat.since } : {}),
...(chat ? { chat: chat.kind, chatId: chat.id, chatName: chat.name } : {}) }
}
/** A Lead's entry for a swarmBuddy dial (spec 2026-10-29-round-dial-pm-buddy): the face on the side it keeps, and while the
* Swarm has Buddies on, `buddies` and the reader's Buddy. With Buddies off it is a swarmChat dial's entry. */
/** The Buddy as the dial draws it: its session id stays on this computer. */
function dialBuddy({ local: _local, ...drawn }: SwarmBuddy): Record<string, unknown> {
return { ...drawn }
}
function buddyLead(l: SwarmLead): Record<string, unknown> {
return { ...chatLead(l, l.sideChat ?? null), ...(l.buddies ? { buddies: true } : {}), ...(l.buddies && l.buddy ? { buddy: dialBuddy(l.buddy) } : {}) }
}
/** A Swarm agent's id as the backend makes it; a harness's id is a UUID, so the two never meet. */
const SWARM_AGENT_ID = /^[0-9a-f]{24}$/
/** The byte cuts a name is shortened through, on a character, when a frame would not fit. */
const NAME_CUTS = [24, 12, 6, 3, 1, 0]
/**
* A `supertab` frame shortened until it fits the cable's payload: a frame over the cap fails the write and closes the link.
* The Buddies' names go first (their avatars still tell them apart), then every name together; ids and engines, which the
* dial routes and draws by, are never touched. With the backend's ids, 12 Leads with every name at 48 bytes and a Buddy each
* fit whole; with every id at the 47 characters a dial holds they came to 8,211 bytes, and names of quotes, which JSON
* doubles, past it even with no Buddy names at all (review of #2146). Last, whole Buddy blocks go, from the least urgent Lead
* up: engines of control characters (six bytes each in JSON) leave a Buddy frame at 8,275 bytes with every name empty, and
* without its Buddies a frame is today's swarmChat one, about 5.3 KB at most. A frame that fits is sent as it is.
* With `tokens`, as for every dial, whose guard refuses a JSON frame over 512 tokens whole (firmware cable_json_guard.h), a
* frame fits only if it is also within that many JSON tokens. Shorter names do not lower that count, so the Buddy blocks go
* (task #2525: 12 Leads came to 513 tokens, and the dial dropped every frame).
* Returns how many Buddy blocks went, for the caller's log.
*/
function fitFrame(frame: { name: string; leads: Array<Record<string, unknown>> }, tokens?: number): { buddies: number } {
const small = () => Buffer.byteLength(JSON.stringify(frame)) < CABLE_MAX_PAYLOAD
const fits = () => small() && (tokens === undefined || jsonTokens(frame) <= tokens)
type Named = { [key: string]: unknown }
const buddies: Array<[Named, string]> = frame.leads.map((l) => l.buddy as Named | undefined).filter((b) => b !== undefined).map((b) => [b, 'name'])
const names: Array<[Named, string]> = [[frame, 'name'], ...frame.leads.flatMap((l) => ['project', 'owner', 'chatName'].filter((key) => key in l).map((key): [Named, string] => [l, key]))]
for (const fields of [buddies, [...buddies, ...names]]) {
for (const bytes of NAME_CUTS) {
if (small()) break
for (const [holder, key] of fields) holder[key] = truncateUtf8(String(holder[key]), bytes)
}
}
let blocks = 0
for (let i = frame.leads.length - 1; i >= 0 && !fits(); i--) if (frame.leads[i].buddy !== undefined) { delete frame.leads[i].buddy; blocks++ }
return { buddies: blocks }
}
/** A Lead's new message as the round dial's alert, sized as the recap is. */
function noticeFrame(tab: string, lead: string, n: LeadNotice): Message {
return fitText(n.text, (text) => ({ t: 'supertab.notice', tab, lead, chat: n.chat, chatId: n.chatId, id: n.id, text, at: n.at }))
}
/** `make(text)`, with the text shortened (on a character) until the whole JSON fits what a dial reads: escapes can grow
* 1,500 bytes of text past it. */
function fitText(full: string, make: (text: string) => Message): Message {
let text = full
while (text && Buffer.byteLength(JSON.stringify(make(text))) > RECAP_FRAME_MAX) text = truncateUtf8(text, Math.floor(Buffer.byteLength(text) * 0.9))
return make(text)
}
let nextCardSession = 0
const SWARM_IDS_MAX = 24
const SWARM_TOKENS_MAX = 480
/** The firmware's JSON guard itself (cable_json_guard.h): a frame of more tokens is dropped whole. A round dial's frames carry
* no seq, so they are fitted to it; a Pro's keep SWARM_TOKENS_MAX's margin for theirs. */
const GUARD_TOKENS_MAX = 512
/** The models a dial's picker holds (ui_habitat.c): more are never sent. */
const MODELS_MAX = 48
/** Tokens as `cable_json_guard.c` counts them: every object, array, string (keys too) and bare value. */
function jsonTokens(value: unknown): number {
if (Array.isArray(value)) return 1 + value.reduce((n: number, v) => n + jsonTokens(v), 0)
if (value && typeof value === 'object') return 1 + Object.entries(value).reduce((n, [, v]) => n + 1 + jsonTokens(v), 0)
return 1
}
/** Whether a message fits one frame as the device reads it: the cable's payload cap, with a margin for anything the
* frame carries beyond this JSON (its seq), and the firmware's JSON guard, which refuses a frame of more than 512
* tokens whole. */
function fitsFrame(m: unknown): boolean {
return Buffer.byteLength(JSON.stringify(m), 'utf8') <= CABLE_MAX_PAYLOAD - 256 && jsonTokens(m) <= SWARM_TOKENS_MAX
}
function clipUtf8(text: string, max: number): string {
const flat = text.replace(/[\r\n\t]+/g, ' ')
if (Buffer.byteLength(flat, 'utf8') <= max) return flat
const decoded = new TextDecoder('utf-8').decode(Buffer.from(flat, 'utf8').subarray(0, max - 3))
return `${decoded.replace(/\uFFFD+$/, '')}\u2026`
}
export interface CableAgent {
id: string
name: string
engine?: string
model?: string
effort?: string
/**
* The machine this agent lives on, and that machine's name.
*
* A tab can hold panes from several machines at once, so an agent that does not say where it lives
* cannot be driven: the daemon routes each turn, stop and answer by this id, and the dial prints the
* name under the agent's.
*/
machineId?: string
machine?: string
}
/**
* One row of the dial's machine wheel.
*
* `state` is the ONLY liveness word on the wire, deliberately as one tri-value rather than an `online`
* boolean beside a `known` one: one field cannot contradict itself, two can — and would, the first time a
* list refresh fails halfway through.
*/
export interface CableMachine {
id: string
name: string
state: 'ready' | 'offline' | 'unknown' | 'needs-link'
/** Exactly one row carries this: the computer at the other end of the cable. */
local: boolean
}
/**
* One of the window's swarms — a named group of agents arranged on one grid. The window owns them
* entirely (they live in its state file and nowhere else); the daemon relays the list so the dial can
* name the one on screen and offer the others, and relays a pick straight back.
*/
export interface CableSwarm {
id: string
name: string
/** How many agents it holds — the dial draws the count, never the members. */
agents: number
/** The agents it holds, in the window's own order. Sent only to a device that named `swarms: 'members-v1'`. */
agentIds?: string[]
/**
* How many TILES it holds, of any kind — agents, shells, viewers.
*
* Separate from `agents` because the two answer different questions, and the dial needs the second
* one: a tab holding only a terminal drives no agent, so `agents` is 0 for it exactly as it is for
* an untouched New Harness tab. Filtering the switcher on `agents` therefore hid a tab that had
* real content in it, with no way back to it from the dial. Nothing here ever becomes a roster
* entry — a shell is still never named to the dial.
*/
panes: number
/** The Super Tab (Swarm) this tab shows, when it is one: how the Harness Pro's Swarm card finds its desk tab. */
superTabId?: string
}
/**
* ONE TILE OF THE ACTIVE SWARM'S GRID, exactly where the window put it.
*
* Unit rectangle in THOUSANDTHS of the grid, so it crosses as integers and a device can scale it to
* whatever face it has. `agentId` is empty for a tile the device cannot drive — a shell, a viewer —
* which still holds its place, because a shape with a tile missing is not that shape.
*
* Relayed, never computed here. The window is the only side that knows whether this grid came from a
* preset, from `auto` (whose column count it measures against its own width) or from a hand-dragged
* resize, and the one rule `pane_preset.dart` asks of everybody is that the shape is described once.
*/
export interface CableTile {
x1: number
y1: number
x2: number
y2: number
agentId: string
}
/** The window's swarms as it last described them, or null while no window is connected. */
export interface AppSwarms {
active: string
swarms: Array<{
id: string; name: string; agentIds: string[]; panes: number
/** A Super Tab (Swarm) tab: which Swarm it shows and the project the window has open in it. Absent on any other tab. */
superTabId?: string; projectId?: string
/** The conversation the window has open in that Swarm tab, when it is one (its Lead's, Chat with PM or a group). */
conversationId?: string
/** The root of the thread whose pane is on screen beside that conversation, which the round dial's face follows. */
threadRoot?: string
}>
/** The ACTIVE swarm's grid. Empty from a window that predates the field, or one with no panes. */
tiles: CableTile[]
/** This announce was caused by a device's pick (`supertab.select`): the device is not told to follow it back. */
fromDevice?: boolean
}
/** Why the list is as short as it is. The dial renders this, instead of drawing an empty wheel. */
export type CableMachineSource = 'backend' | 'local' | 'signed-out'
/**
* What a Super Tab member's wait adds to its `question` (superTabs/inCore/attention.ts): the tab's name and whether it needs a
* decision or is stuck. The Harness Pro makes it an alert whose toast stays; firmware without it, and the round dial,
* read the words alone. Nobody answers it on a device.
*/
export interface SuperTabAsk { superTab: string; attention: 'decision' | 'stuck' }
/** Why the dial sent an `agent.open`: a tap (absent) or a question screen that came up on its own. */
export type OpenReason = 'question'
export type { WindowRoute } from './windowRoute.js'
import type { WindowRoute } from './windowRoute.js'
import { withSelectedPassage, type SelectionCommand, type SelectionResult } from './windowSelection.js'
import type { VisitCommand, VisitResult } from './windowVisit.js'
import type { FormCommand, FormResult } from './windowForm.js'
import { deriveLongRecap, extendShortRecap } from '../lib/deviceRecap.js'
import type { TurnStatsFields } from './turnStats.js'
import type { Tier } from '../lib/notifyTier.js'
import type { CardChat, CardSide, LeadNotice, LeadRecap, SaidOnCard, SwarmBuddy, SwarmCard, SwarmChat, SwarmLead } from '../superTabs/cards.js'
import { truncateUtf8 } from '../lib/deviceRecentTrim.js'
export interface RouteDecision {
agentId: string
confidence: number
reason: string
}
/**
* Everything the session needs from the rest of the daemon. An interface rather than a direct import so
* the protocol can be tested against a fake — the alternative is a suite that needs tmux, a microphone
* and a network to prove that `hello` gets a `welcome`.
*/
export interface CableHost {
/** The computer at the other end of the cable — its identity, not "the" machine's. */
localMachine(): { id: string; name: string }
/** Every machine the owner has, local row included. Never rejects: `source` explains a short list. */
listMachines(): Promise<{ machines: CableMachine[]; source: CableMachineSource }>
/** Which one the agent list currently belongs to. */
selectedMachine(): string
/**
* Switch. Resolves to a discriminated result and NEVER throws — a refusal is data here, the same way
* `firmwareFor()` returning null is. `code` is the daemon's; `message` is shown to a person verbatim,
* so the dial needs no table for a set it does not own.
*/
selectMachine(machineId: string): Promise<{ ok: true } | { ok: false; code: string; message: string }>
/** The machine a pick is still on its way to, or '' when none is. Picking the selected machine then has to replace it. */
pendingPick?(): string
/** The window's swarms and which is on screen. Empty with no window: the dial then draws no swarm line. */
listSwarms(): { selected: string; swarms: CableSwarm[]; tiles: CableTile[] }
/** The dial picked a swarm. Relayed to the window, which switches and re-describes its desk. */
selectSwarm(swarmId: string): void
/** The Swarm cards the core last told the devices (superTabs/inCore/cards.ts); null until it has, which is not "no Swarms". */
swarmCards?(): SwarmCard[] | null
/** A device that speaks `swarmCard: 'v1'` is attached (true) or gone (false): the core starts or stops reading the Swarms. */
swarmCardsWanted?(on: boolean): void
/** One Lead's last message, read on request; null when it could not be read. */
swarmCardRecap?(tabId: string, leadId: string, chat?: CardChat): Promise<LeadRecap | null>
/** The recap a device has open (its Lead), or null once it closes: the only one pushed when its text changes. */
swarmCardOpen?(session: string, tabId: string, leadId: string | null, chat?: CardChat): void
/** A round dial that speaks swarmBuddy swiped to a side of a Swarm: the cards show that side's face. */
/** Words for a Lead that runs here: posted as the person in its Swarm chat. Not `said`: not a Lead, send the turn as before;
* `refused`: the backend refused the post, whose words are never typed anywhere instead. `chatId`: the chat they were
* spoken to, the only one they may be posted in. */
swarmSay?(harnessId: string, text: string, chat?: CardChat, chatId?: string, reviewed?: boolean): Promise<SaidOnCard>
/** A device picked a Lead: the window opens that Swarm tab and project. `chat` (a round dial that speaks swarmBuddy): the
* reader's Buddy chat there ('buddy') or the project's Lead chat ('pm'), so the desktop follows the dial's side. */
superTabSelected?(superTabId: string, projectId: string, chat?: CardSide): void
/** The Swarm tab the window has on screen and the project open in it ('' when none is); null when the active tab is not a Swarm or there is no window. */
activeSwarmProject?(): { superTabId: string; projectId: string; conversationId?: string; threadRoot?: string; fromDevice: boolean } | null
appName(): string
voiceLang(): string
/** The window's latest selected pane, including selections made before this dial attached. */
appFocus?(): { machineId: string; agentId: string } | undefined
/** The active tab's agents, in tile order — and nothing else. Empty with no window or an empty tab. */
listAgents(): Promise<CableAgent[]>
/** Pane rows and workspace identity from the same desktop announcement. */
listAgentSnapshot?(): Promise<{ agents: CableAgent[]; tab: string; total: number }>
/** Every agent across the account — the overview's number. The dial gets the count, never the rows. */
agentTotal(): number
/** The active tab's id, or '' with no window: what lets the dial tell an empty tab from a shut app. */
activeSwarm(): string
/** Who an agent is, for a card about one the dial does not hold. Undefined for an id never listed. */
describe(agentId: string): { name: string; engine: string; machine: string } | undefined
activityText?(agentId: string): Promise<string | null>
/** `activityText` plus the timer and the assistant's latest paragraph. Preferred when present. */
activitySnapshot?(agentId: string): Promise<ActivitySnapshot | null>
/** Every session the library can page through, in the order to show them. Absent: no library. */
playerLibrary?(): Promise<PlayerSession[]>
sendTurn(agentId: string, text: string): void | { ok: true } | { ok: false; machine?: string; reason?: string }
stopTurn(agentId: string): void
/**
* The user answered a `question`. `answers` is keyed by the QUESTION keys the daemon itself asked with
* and travels verbatim — re-deriving it, or keying it by the requestId, is how a rename at either end
* becomes an answer nobody gave.
*/
answer(agentId: string, requestId: string, answers: Record<string, string>): void
answerReviewed?(answer: ReviewedAnswer): Promise<AnswerReceipt>
canSpeakQuestion?(agentId: string): boolean
focus(agentId: string): void
/**
* "Put this one in front of me" — a NOTIFICATION was tapped.
*
* A different verb from [focus], and the difference is the whole point: focus
* says where the eye is and the window moves a tile to match, while this asks
* for a tile of its own. A turn that just finished is a new thing to look at,
* not a replacement for whatever the person was already watching.
*
* `reason` is why the dial sent it: absent for a person's tap; `'question'` when a question screen
* came up on its own — the window then only brings the agent forward if it is already on screen,
* because a reconnect re-shows every unanswered question and each used to open a tab.
*/
openAgent(agentId: string, reason?: OpenReason): void
readNotification?(agentId: string, readToken: string): void
/** The dial asked for a fork of this agent — a second one with its history, opened in the window. */
forkAgent(agentId: string): Promise<{ ok: true; agentId: string } | { ok: false; error: string; detail?: string }>
/**
* Does this daemon's own agent list hold that id?
*
* Only for saying so. A `focus` for an agent the dial has no tile for lands on nothing, and from the
* outside that is indistinguishable from the dial ignoring the window — which is exactly the report
* that took a morning to explain. Optional, so a host that cannot answer simply says nothing.
*/
knows?(agentId: string): boolean
/** A finger moving on the dial's glass, on its way to whatever window is open on this computer. `superTabId`: the device has a Lead
* of that Swarm open (a Pro's Lead view), so the window scrolls that Swarm's chat rather than a pane. */
scrolled(phase: 'down' | 'move' | 'up', dy: number, velocity: number, superTabId?: string): void
updateAgent(agentId: string, model?: string, effort?: string): void
/** PCM is 16-bit mono at `sampleRate`; the daemon owns the credential this needs. */
transcribe(pcm: Buffer, sampleRate: number, lang: string): Promise<string>
/** Which agent the words belong to. Scored locally first; only a genuine tie should cost a network call. */
route(transcript: string, agents: CableAgent[]): Promise<RouteDecision>
/**
* Offer the words to the desktop window FIRST, and let its palette decide.
*
* The window's ⌘B router is the one that gets looked after — fifteen candidates in rail order, recaps
* cut to sixty characters, a twenty-second budget, and a picker when it is not sure. [route] is the
* same idea a version behind, so this is asked first and that is the fallback rather than the default.
*
* Optional: a host with no window to ask simply omits it, and voice behaves exactly as it always has.
*/
routeInWindow?(text: string, cmd?: string): Promise<WindowRoute>
selectPassage?(command: SelectionCommand): Promise<SelectionResult>
visit?(command: VisitCommand): Promise<VisitResult>
form?(command: FormCommand): Promise<FormResult>
/** The runtime model/effort catalog for one agent, as opaque profile ids the dial groups and shows. */
listModels(agentId: string): Promise<string[]>
/** One agent's last turn summaries, newest first — what a reattached dial needs to redraw its tiles. */
recentSummaries(agentId: string): Promise<Array<{ recap: string; text: string; fullText?: string }>>
/** What the window still has unread, newest first — replayed to a dial that has just attached. */
listUnread(): UnreadNotification[]
/**
* The custom pets kept on this computer, or null when there is no store (a host that never heard of pets).
* Read by the session itself on every sync, so a mapping changed while a dial is attached is the one it sees.
*/
pets?(): PetStore | null
/**
* The image to offer a dial running `runningVersion`, or null for "nothing to do" — which covers a
* dial that is current, a dev build that must not be touched, and an unreachable manifest. `keepalive`
* says the same dial on the same image greeted again, so a recent manifest read may answer it.
*/
firmwareFor?(runningVersion: string, key: string, keepalive?: boolean): Promise<{ version: string; image: Buffer; sha256: string } | null>
/**
* A dial greeted us, or the port went away.
*
* The daemon holds its cloud lane ON THE DIAL'S BEHALF — nothing else in this process uses it. So with
* no dial there is nobody to hold it for, and holding it anyway leaves the account showing a device
* that is attached to a machine while sitting unplugged in a drawer.
*/
onDialAttached?(): void
onDialGone?(): void
/**
* The port this session opened turned out not to be a Harness dial: it talked in something else, or
* never said anything at all. Told once, so whoever owns discovery can stop offering the port — a
* second ESP32 board on the desk is somebody's work in progress, not ours to keep probing.
* Never called for a device that has been a dial.
*/
onForeignPort?(path: string, why: string): void
/**
* Something this session does threw, or the far end is flooding the port with what no dial sends. Told
* every time, so whoever owns the session can drop this dial alone, and look at its port again later,
* rather than let one device's fault reach every other one in the process. A dial is hardware speaking
* whatever its firmware says: a fault here is expected to happen, and to be this dial's alone.
*/
onFault?(error: unknown, hostile?: boolean): void
/**
* The dial as a window would draw it: there or not, on which firmware, and whether an update is
* going over the cable right now. Fired on every change and never on a keepalive — the window
* shows this in its rail, and a rail that redraws four times a minute to say "still here" is a rail
* nobody can afford. What is NOT here: anything a hand did (that is `focused`/`opened`/`scrolled`).
*/
onDialStatus?(status: DialStatus): void
log(line: string): void
}
/**
* The settings a device owns and an app may change, exactly as they cross the cable.
*
* Named booleans rather than the firmware's NVS bitmask: those bit positions are the device's private
* arrangement, and an app that knew them would have to ship in step with a header it cannot see.
*
* `round` is not a preference — it is the face. A square device has no curved title, so the app HIDES
* that row rather than greying out a control for a setting that does not exist there.
*/
export interface DeviceSettings {
brightness: number
character: number
/** The glass, in pixels across. Informational: a support line reads it, nobody chooses it. */
face: number
muted: boolean
quiet: boolean
straightTitle: boolean
focusFace: boolean
scrollReversed: boolean
round: boolean
/** Harness Pro only: which interface the screen shows. Absent from round dials and older Pro firmware. */
uiSkin?: 'classic' | 'console'
voiceLang: string
/** Presence advertises companion.set support. Omitted by older firmware. */
followCompanion?: boolean
/** Active transient companion; null means the saved device skin is showing. */
companion?: string | null
companionProtocol?: number
companionDetails?: CompanionIdentity | null
}
/** The fields a `settings.set` may name. Absent means unchanged — see handle_settings_set on the device. */
export type DeviceSettingsPatch = Partial<Omit<DeviceSettings, 'round' | 'face' | 'companion' | 'companionProtocol' | 'companionDetails'>>
/** What a window needs to draw the device row. `updating` names the version on its way over. */
export interface DialStatus {
attached: boolean
/**
* Which device this is, when there is more than one. The fleet's key — the USB serial, or the port
* path when the descriptor has none. Absent from a session running without a fleet around it.
*/
id?: string
/** The device's own address, from `hello.mac`. Survives being moved to another port; `id` may not. */
mac?: string
/**
* What the device holds, as IT last reported — never what this computer last sent. Absent until the
* first greeting, and from a firmware that does not carry settings at all (the LVGL build).
*/
settings?: DeviceSettings
fw?: string
/** Which of the two dials this is — `cst9217+axp2101`, `cst816s`, … — as the firmware detected itself
* at boot (device: board.h). Absent from a firmware that predates the field. Informational. */
hw?: string
/** `hello.board`; "pro" is the square Harness Pro. Absent = a round dial. */
board?: string
updating?: string
/** Something the person has to do about this device, in words shown as they are (cableFleet.ts: a silent Harness Pro). */
problem?: string
/**
* Every device on this computer, when a fleet is reporting. Present only on the primary status, and
* the primary is one of these rows — the flat fields above repeat it so a window that predates this
* still draws something true.
*
* It exists because one desk can hold two devices and the settings pane has to name which one it is
* changing. Before this the fleet picked a row and threw the rest away, and the app drew one robot
* however many were plugged in.
*/
devices?: DialStatus[]
}
/** The chat on a dial's face as the person began to speak, and the project it belongs to (a review names both). */
type SwarmFace = SwarmChat & { project: string }
interface Message {
t: string
[key: string]: unknown
}
/**
* The part of a port this layer uses. An interface rather than the class, so the protocol can be driven
* by a loopback in tests — proving that `hello` gets a `welcome` should not require a dial on the desk.
*/
export interface CablePort {
readonly path: string
readonly isOpen: boolean
write(bytes: Uint8Array): Promise<void>
close(why?: string): Promise<void>
}
/** Open the dial's port, or null when it is not there. Both are ordinary answers. */
export type PortOpener = (
onData: (chunk: Buffer) => void,
onClosed: (why: string) => void,
) => Promise<CablePort | null>
/** The real one: find the tty by USB id, open it raw. */
export const openDialPort: PortOpener = async (onData, onClosed) => {
const port = await findDialPort()
if (!port) return null
return SerialLink.open(port.path, onData, onClosed)
}
/**
* Read a device's reported settings, or undefined.
*
* Every field must be there and be the right type. A partial object is refused whole rather than
* filled with defaults: a default is a value this computer invented, and the pane would then show a
* setting the device does not have — the exact failure `settings.state` exists to prevent.
*/
/** True when the device's settings carry a `uiSkin` at all (an older firmware has none and would ignore the patch). */
const hasUiSkin = (value: unknown): boolean => typeof value === 'object' && value !== null && 'uiSkin' in value
function readSettings(value: unknown): DeviceSettings | undefined {
if (!value || typeof value !== 'object') return undefined
const raw = value as Record<string, unknown>
const flags = ['muted', 'quiet', 'straightTitle', 'focusFace', 'scrollReversed', 'round'] as const
for (const key of flags) if (typeof raw[key] !== 'boolean') return undefined
if (typeof raw.brightness !== 'number' || !Number.isFinite(raw.brightness)) return undefined
if (typeof raw.character !== 'number' || !Number.isFinite(raw.character)) return undefined
if (typeof raw.face !== 'number' || !Number.isFinite(raw.face)) return undefined
if (typeof raw.voiceLang !== 'string') return undefined
return {
brightness: Math.max(0, Math.min(100, Math.round(raw.brightness))),
character: Math.round(raw.character),
face: Math.round(raw.face),
muted: raw.muted as boolean,
quiet: raw.quiet as boolean,
straightTitle: raw.straightTitle as boolean,
focusFace: raw.focusFace as boolean,
scrollReversed: raw.scrollReversed as boolean,
round: raw.round as boolean,
voiceLang: raw.voiceLang,
...(raw.uiSkin === 'classic' || raw.uiSkin === 'console' ? { uiSkin: raw.uiSkin as 'classic' | 'console' } : {}),
...(raw.companionProtocol === 2 ? {companionProtocol:2, companionDetails:readCompanionIdentity(raw.companionDetails)} : {}),
...(typeof raw.followCompanion === 'boolean' &&
(raw.companion === null || typeof raw.companion === 'string')
? { followCompanion: raw.followCompanion, companion: raw.companion as string | null } : {}),
}
}
/** A pet transfer with no pet.accept / pet.progress for this long is abandoned for the rest of the link. */
const PET_STALL_MS = 10_000
/** A firmware transfer whose acked byte count has not advanced for this long is over (the dial aborts at 10 s itself). */
const FW_STALL_MS = 30_000
/** How long a pet.done outranks a greeting that does not list the pack (see petDoneAt). */
const PET_DONE_TRUST_MS = 3_000
/** A dial that refused a pack for memory right after we dropped another is given the room a moment to free. */
const PET_RETRY_MS = 1500
/** Refusals that say nothing about the pack itself, so a later hello or a changed mapping may try again. */
const PET_TRANSIENT = new Set(['timeout', 'unreadable', 'memory', 'busy'])
export class CableSession {
private link: CablePort | null = null
private decoder = new CableDecoder()
/** This port's traffic since it opened, logged once a minute and when it closes (see logLink). */
private traffic = { at: 0, tx: 0, txFrames: 0, rx: 0, rxFrames: 0, corrupt: 0, discarded: 0, run: '', noise: '' }
private timer: NodeJS.Timeout | null = null
private greetedMac: string | null = null
/** This session has spoken with a real dial at least once. Never reset: a port that has been a dial
* can go quiet (a hung firmware, a reboot) without ever becoming somebody else's. */
private everGreeted = false
/** The board this device says it is (`hello.hw`). Decides which firmware it may be offered. */
private greetedHw: string | undefined
/** `hello.board` (absent on rounds and the old Player-1 Pro build). "pro" is the standalone Pod firmware. */
private greetedBoard: string | undefined
private greetedOta: string | undefined
/** What the device last SAID its settings are. Never what this computer last asked for. */
private greetedSettings: DeviceSettings | undefined
private greetedFw: string | null = null
private lastRx = 0
private stopped = false
/** What the dial was last told the agent list is. Empty = it has been told nothing. */
private lastAgentsKey = ''
// What the hello NAMED. Each switches on only its own fields; a hello that names none gets the frames it
// always got. A positive string match, per session (see hello).
/** `swarms: 'members-v1'`: `agentIds` and `members` on the swarms items. */
private swarmMembers = false
/** `recap: 'long-v1'`: `full` on a summary. */
private longRecap = false
/** `activity: 'steps-v1'`: `action`, `elapsedSeconds` and `step` on turn.activity. */
private stepsActivity = false
/** `stats: 'turn-v1'`: the `turn.stats` frame before turn.done. */
private statsTurn = false
/** `player: 'library-v1'`: the paged `player.library`. */
private playerCapable = false
/** `superTab: 'wait-v1'`: a `question` with `superTab` and `attention` is shown as a Super Tab wait, which nobody
* answers on the device. Any other device is not sent one: the round dial would open a question screen for it that
* cannot load. */
private superTabWaits = false
/** `swarmCard: 'v1'` (a Pro): the Swarm cards, their Leads' recaps and the Swarm focus travel on the cable. */
private swarmCard = false
/** `swarmChat: 'v1'` (the round dial, design 2026-10-28-round-dial-swarm-chat): each Lead's face is the chat the desktop has
* open in its project, its recap is that chat's, `work` only for a working group, and the alerts are the Lead's new
* messages (`supertab.notice`). Any other device gets today's frames byte for byte. */
private swarmChat = false
/** `swarmBuddy: 'v1'` beside swarmChat (spec 2026-10-29-round-dial-pm-buddy): the dial shows the reader's Buddy only (task #3908; its
* side swipes are ignored), each Lead carries `buddies` and the reader's Buddy, and the Buddy's word is a quiet notice. A
* swarmChat dial without it gets today's frames byte for byte. */
private swarmBuddy = false
/** `swarmNeedsYou: 'v1'` beside swarmChat (spec 2026-11-05-dial-lead-pm-buddy-pair): the bell and inbox hold only what needs the
* reader, so the Buddy's quiet notices are never sent to it. */
private swarmNeedsYou = false
/** `swarmReview: 'v1'` beside swarmChat (docs/device-voice-swarm-chat.md): the dial reviews every word for a Swarm chat
* before it is posted, so one that comes unreviewed is refused before it is transcribed. */
private swarmReview = false
private playerOffset = 0
private playerRequest = 0
private playerLibraryKey = ''
private playerLibraryAt = 0
private swarmsTrimmedKey = ''
/** `hello.board === 'pro'`: every JSON frame to it carries a `seq` (a USB loss on its path is silent, and a hole in
* the count is how it notices). Per session: each welcome restarts it at 0. A round dial's frames stay as they were. */
private seqOn = false
private seq = 0
private resyncAt = 0
/** For the greeting's log line: which capabilities this hello named, or nothing. */
private capabilitiesNamed(): string {
const named = [this.swarmMembers && 'swarms', this.longRecap && 'recap', this.stepsActivity && 'activity', this.statsTurn && 'stats', this.playerCapable && 'player', this.superTabWaits && 'superTab', this.swarmCard && 'swarmCard', this.swarmChat && 'swarmChat', this.swarmBuddy && 'swarmBuddy', this.swarmNeedsYou && 'swarmNeedsYou', this.swarmReview && 'swarmReview']
.filter(Boolean)
return named.length ? ` caps ${named.join(',')}` : ''
}
private resetCapabilities(): void {
this.swarmMembers = this.longRecap = this.stepsActivity = this.statsTurn = this.playerCapable = this.superTabWaits = false
this.swarmCard = this.swarmChat = this.swarmBuddy = this.swarmNeedsYou = this.swarmReview = false
this.dropCards()
this.seqOn = false
this.seq = 0
this.resyncAt = 0
this.playerOffset = this.playerRequest = 0
this.playerLibraryKey = ''
this.playerLibraryAt = 0
}
/** Bytes and frames seen since this port opened — the evidence for the foreign-dial verdict. */
private bytesSinceOpen = 0
private framesSinceOpen = 0
/** Ports written off as another product's, and when it becomes worth looking again. */
private foreignPort: string | null = null
private foreignRetryAt = 0
/** Which images have already been written to which dial, and when. Survives the port, unlike `offered`. */
private readonly written = new Set<string>()
private readonly writeLog = new Map<string, number[]>()
/**
* THE agent both screens are meant to be on. One memory, written by whichever side moved last.
*
* There were two — where the dial was, and what the window last said — and they drifted apart in the
* one case that matters most: when the WINDOW follows the DIAL, `followApp` returns early (the dial is
* already there), so the window's memory was never updated and kept an older agent. Anything that then
* re-asserted "where the window is" sent that stale agent, the dial jumped back to it, and the window's
* next report pulled it forward again. Measured on the real dial as a tile going 3 → 4 → 3 → 4.
*
* A single field cannot disagree with itself. Both sides write it on a real move, the last write wins,
* and it is the only thing the daemon ever re-asserts.
*/
private desiredFocus = ''
/** A superseded list refresh can record the selection without ever writing its focus frame. */
private appFocusUnsent = false
/** Keep list-before-focus writes ordered, coalescing superseded desktop selections. */
private appFocusTail: Promise<void> = Promise.resolve()
/** A remote attachment can take seconds. It must not hold the next pane's focus behind it. */
private appMachineTail: Promise<void> = Promise.resolve()
private appFocusGeneration = 0
/** When the app-driven switch began — see APP_SWITCH_REPAINT_MS. */
private drivingSince = 0
/** While the app is rebuilding the dial's machine/list state, focus reports describe that rebuild. */
private drivingAppFocus = false
/** The dial may echo a focus command after its write promise resolves; consume that one echo. */
private expectedAppFocusEcho = ''
private expectedAppFocusEchoUntil = 0
/** The same, for the machine wheel. Both reset together on any new port — see `tryOpen`. */
private lastMachinesKey = ''
/** Throttle for the machine list, which costs an HTTP read where the agent list costs a map lookup. */
private machinesAt = 0
/** A recap lookup must not replay an older inbox over a newer clear. */
private notificationReplay?: { seen: Set<string> }
/**
* Serialises every STREAMED push (begin / rows / end).
*
* ⚠️ NOT a precaution. `onMessage` is fired from the decoder callback and never awaited, so a dial that
* greets and then asks for both lists has three pushes in flight at once — each awaiting a write
* between every row. Their frames interleave, and the far end sees `begin, begin, 8 rows, end, end`:
* it stages one machine list twice over and reports eight machines where the daemon sent four.
*
* Measured on hardware 2026-08-25, first plug-in of the proto-2 firmware. The dial's own hash gate does
* not help here — it faithfully gates a list that was already shredded on the way in.
*/
private pushChain: Promise<void> = Promise.resolve()
/** Run `body` after every push already queued, and before any queued later. */
private queued(body: () => Promise<void>): Promise<void> {
const next = this.pushChain.then(body)
// The tail swallows so one failed push cannot strand the ones behind it; the caller still sees it.
this.pushChain = next.catch(() => {})
return next
}
/** A firmware transfer in flight, and the versions already tried this session. */
private transfer: FirmwareTransfer | null = null
/**
* Custom pets. A transfer of its own, never `transfer`: the firmware one and this one must never be mistaken for each
* other by fw.progress / pet.progress, and pets wait while a firmware image is in flight (see syncPets).
* All of it is per LINK: a cut cable forgets it, and the next hello (its petIds without the pack) offers again.
*/
private petTransfer: { id: string; xfer: FirmwareTransfer; size: number; written: number } | null = null
/** `hello.pets`: the newest pack version the dial understands (a number >= 1). Absent means old firmware: no pet traffic of any kind. */
private petDialMax = 0
private petsSupported = false
/** A pet.drop went out on this link: the dial's memory may still be settling, so a memory refusal is retried once. */
private petDropSent = false
private petRetried = new Set<string>()
private petRetryTimers = new Set<ReturnType<typeof setTimeout>>()
/** Pack ids the dial holds: its hello's petIds, plus each pet.done, minus each pet.drop we sent. */
private petHeld = new Set<string>()
/**
* When each pack's pet.done arrived. A greeting the dial assembled while a pack was still arriving can land after its
* pet.done and list it as missing — seen 2026-10-08, when both packs went over twice. A pack confirmed this recently
* is believed over such a greeting.
*/
private petDoneAt = new Map<string, number>()
/** Packs the dial refused on this link, by reason. Not offered again until the link comes back. */
private petErrors = new Map<string, string>()
/** The last `pet.map` sent on this link, so a keepalive hello does not repeat it. */
private petMapSent = ''
/** Runs one sync at a time: hello, pet.done and a changed mapping can all ask for one at once. */
private petChain: Promise<void> = Promise.resolve()
/** Fires when a pet transfer has made no progress (offer, accept, progress) for PET_STALL_MS. */
private petStall: ReturnType<typeof setTimeout> | null = null
/** `<mac>:<version>` already offered on this port. The durable, cross-port guard is `mayOffer`. */
private offered = new Set<string>()
/** `<mac>:<version>` of the firmware transfer in flight, so fw.done can record it and a failure can free it. */
private offeringKey = ''
/** The last acked byte count of that transfer, and the timer that fires when it stops advancing. */
private fwAcked = 0
private fwStall: ReturnType<typeof setTimeout> | null = null
/** Devices already logged as having no image channel this session (the hello repeats every ~15 s). */
private noChannelLogged = new Set<string>()
/** Voice capture in flight: PCM chunks as they arrive, plus what `voice.begin` said about them. */
private voice: { agentId?: string; cmd?: string; lang: string; rate: number; chunks: Buffer[]; bytes: number;
selectionId?: string; selection?: Promise<SelectionResult>;
carry?: CarryRead;
question?: { pin?: QuestionSpeech };
draft?: { pin?: DraftPin };
search?: { command?: SelectionCommand; pin: Promise<SelectionResult> };
form?: { command?: FormCommand; pin: Promise<FormResult> };
/** The chat on this dial's face for that agent's Swarm project as the person began to speak: the words go there or
* nowhere, and a Buddy chat's never reach a terminal (review of #2146). */
swarmFace?: SwarmFace;
/** That Lead runs on another machine: named by its Swarm id, it has no terminal here. */
swarmRemote?: true } | null = null
private voiceSearch?: SelectionCommand
private voiceForm?: FormCommand
private voiceCarryId?: string
private readonly passageCarry = new PassageCarry({
select: command => this.host.selectPassage?.(command) ??
Promise.resolve({ ok: false, error: 'Update Harness to carry text.' }),
name: async id => (await this.host.listAgents()).find(a => a.id === id)?.name ?? 'Harness',
})
private readonly voiceDraft = new VoiceDraft()
private voiceDraftCreation?: { uploadId: string; id: string }
private readonly questionInbox = new QuestionInbox()
private voiceGeneration = 0
private voiceUploadId = ''
constructor(
private readonly host: CableHost,
/** The dial's console, as a file: framed device logs and this side's `cable:` events, one day each. */
private readonly dialLog: DialLog,
private readonly openPort: PortOpener = openDialPort,
) {}
/**
* Every `cable:` event goes two ways: to the daemon's console as before, and into the dial's log with a
* `[daemon]` prefix — the stuck-dial report is read end to end from ONE file, device lines and what the
* desk did to it interleaved.
*/
private log(line: string): void {
this.host.log(line)
this.dialLog.daemon(line.replace(/^cable: /, ''))
}
get isConnected(): boolean {
return this.link?.isOpen === true && this.greetedMac !== null
}
start(): void {
this.stopped = false
this.timer = setInterval(() => this.ticked(), 1_000)
this.ticked()
}
async stop(): Promise<void> {
this.stopped = true
if (this.timer) clearInterval(this.timer)
this.timer = null
await this.link?.close('daemon stopping')
this.link = null
}
/** One tick, its failure this dial's: a rejection left unhandled would end the whole devices process. */
private ticked(): void {
void this.tick().catch((error: unknown) => this.fault(error))
}
/** This dial's fault, told to whoever owns the session (CableHost.onFault). */
private fault(error: unknown, hostile = false): void {
this.log(`cable: ${hostile ? 'flooded' : 'fault'} · ${error instanceof Error ? error.message : String(error)}`)
this.host.onFault?.(error, hostile)
}
// ── port lifecycle ────────────────────────────────────────────────────────────────────────────────
private reportForeign(path: string, why: string): void {
if (this.everGreeted) return
this.host.onForeignPort?.(path, why)
}
private async tick(): Promise<void> {
if (this.stopped) return
// The firmware beats once a minute; the gap is marked in the dial's own log, where it is read.
this.dialLog.tick(this.isConnected)
if (this.isConnected && Date.now() - this.traffic.at >= LINK_LOG_MS) this.logLink('link')
if (!this.link?.isOpen) {
await this.tryOpen()
return
}
// BYTES BUT NO FRAMES = SOMEBODY ELSE'S DIAL. Nothing we can read has arrived, and something is
// plainly talking — which is what the sibling product's panel looks like from here now that the two
// framings no longer overlap. Holding the port would leave both daemons reading one tty and taking
// turns stealing each other's bytes, so this side lets go and remembers not to come back for it.
if (this.link?.isOpen
&& this.framesSinceOpen === 0
&& this.bytesSinceOpen > 0
&& Date.now() - this.openAt > FOREIGN_AFTER_MS) {
this.foreignPort = this.link.path
// Long enough not to fight over it, short enough to notice a swap. In practice the other daemon
// takes the port the moment this one lets go and a tty is exclusive on macOS, so the next probes
// fail to open rather than steal it back — this interval only decides how soon we would find OUR
// dial if the user unplugged theirs and plugged ours into the same socket.
this.foreignRetryAt = Date.now() + 60_000
this.log(`cable: ${this.link.path} is not a Harness dial (${this.bytesSinceOpen} B, no frames) — releasing it`)
this.reportForeign(this.link.path, `${this.bytesSinceOpen} B, no frames`)
await this.link.close('not ours')
this.link = null
return
}
// Rule 2. The read never fails on a dead handle, so silence is the only symptom there is.
if (Date.now() - this.lastRx > SILENCE_MS) {
// Silent since the moment it opened and never a dial: a board with nothing to say to us. Reopening
// it every few seconds for ever is how a second ESP32 on the desk gets its serial port stolen
// mid-flash, so say so instead of retrying.
if (this.framesSinceOpen === 0 && !this.everGreeted) this.reportForeign(this.link.path, 'silent')
this.log('cable: silent, reopening the port')
// close() runs onClosed, which is where onDialGone fires — one path for "the dial is not there",
// whether the cable was pulled or the far end simply stopped answering.
await this.link.close('silence')
this.link = null
return
}
// The cadence is the contract: the dial reads a gap as absence, and the tick that watches for that
// gap runs far more often than the ping that prevents it.
if (Date.now() - this.lastPing >= PING_EVERY_MS) {
this.lastPing = Date.now()
await this.send({ t: 'ping' })
}
// "Say nothing when nothing changed" has to be paired with "say something when something did".
// Without this the list was sent ONCE per session and never corrected — and a daemon that has just
// restarted greets the dial before its registry has finished loading, so the one thing it ever said
// was "no agents". The dial removed both tiles and sat empty while the daemon knew about two.
if (this.greetedMac !== null) {
// Machines FIRST. The dial paints its Overview eyebrow from the machine list, so an agent list that
// lands first shows a nameless "Machine" for a frame.
if (Date.now() - this.machinesAt >= MACHINES_POLL_MS) {
this.machinesAt = Date.now()
await this.syncMachines()
}
// Swarms BEFORE agents: a swarm switch is a new swarm line and a new ring, and the line naming
// the tab should not lag the tiles that belong to it.
await this.syncSwarms()
await this.syncAgents()
await this.syncPlayerLibrary()
void this.refreshFocusedActivity()
}
}
private openAt = 0
private opening = false
/**
* The version an OTA is moving TO, or '' when none is in flight.
*
* Read by the device row the window draws — see onDialStatus. A dial that is
* taking an update is neither simply present nor absent, and the row says so.
*/
private offeringTo = ''
private lastPing = 0
/**
* Open the dial's port, at most ONE attempt at a time.
*
* ⚠️ THE `opening` FLAG IS THE FIX FOR A BUG THAT LOOKED LIKE BROKEN HARDWARE. `tick()` is fired by
* setInterval and never awaited, so runs overlap freely, and opening a port is not instant — it spawns
* `stty` and waits for it before it opens the descriptor. Under load that outlasts REOPEN_EVERY_MS, the
* next tick walks straight past the throttle below, and a second open begins while the first is still in
* flight. Only the last one is stored in `this.link`. The others are orphaned WITH THEIR READ LOOPS
* STILL RUNNING.
*
* That is not a descriptor quietly wasted. Every orphan reads the SAME tty and feeds the SAME decoder,
* so one byte stream arrives interleaved from several readers: frames are shredded, CRCs fail, and the
* dial's greetings disappear into the noise.
*
* Measured 2026-08-24 — five descriptors open on one port inside one process (`lsof` names them all),
* the daemon receiving 4 of the dial's 22 greetings in 45s, and a 20-byte ping taking 15 SECONDS to
* write. That last number is the dial's own silence deadline, so the session died and restarted forever
* and the screen sat on "0 agents" while this side logged, truthfully, that it had sent two.
*
* The dial was never at fault: sniffed directly with the daemon stopped, it emits one clean 71-byte
* greeting every 2.0s, indefinitely.
*/
private async tryOpen(): Promise<void> {
if (this.opening) return
if (this.foreignPort && Date.now() < this.foreignRetryAt) return
if (Date.now() - this.openAt < REOPEN_EVERY_MS) return
this.opening = true
this.openAt = Date.now()
let opened: CablePort | null
try {
// A late port must not be left running: the attempt we gave up on can still succeed afterwards, and
// an unowned open port with a live read loop is exactly the stranded reader this guard exists to
// prevent. So the loser of the race is closed rather than dropped.
const attempt = this.openPort(
(chunk) => this.onBytes(chunk),
(why) => this.onClosed(why),
)
let timer: ReturnType<typeof setTimeout> | undefined
const expiry = new Promise<never>((_, reject) => {
timer = setTimeout(() => reject(new Error(`open timed out after ${OPEN_TIMEOUT_MS}ms`)), OPEN_TIMEOUT_MS)
})
try {
opened = await Promise.race([attempt, expiry])
} catch (err) {
void attempt.then((late) => late?.close('abandoned — open timed out')).catch(() => {})
throw err
} finally {
clearTimeout(timer)
}
} catch (err) {
// A port that another process holds is the ordinary case, not a fault: esptool, a serial monitor,
// or a second daemon. Say so and try again on the next tick.
this.log(`cable: cannot open the dial: ${(err as Error).message}`)
return
} finally {
this.opening = false
}
if (!opened) return // no dial plugged in — this daemon's resting state
if (this.stopped) { await opened.close('stopped while opening'); return }
// Nothing reaches this line holding a live port — tick() only calls in when the link is closed — but
// assigning over one would strand it exactly as above, and the cost of being sure is one branch.
if (this.link) await this.link.close('replaced')
// A port that earned the verdict once is presumed foreign until it proves otherwise, but the evidence
// is gathered fresh every time: a dial that was replaced behind the same path gets a clean hearing.
if (opened.path !== this.foreignPort) this.foreignPort = null
this.bytesSinceOpen = 0
this.framesSinceOpen = 0
this.traffic = {
at: Date.now(), tx: 0, txFrames: 0, rx: 0, rxFrames: 0,
corrupt: this.decoder.corruptFrames, discarded: this.decoder.discardedBytes, run: '', noise: '',
}
this.link = opened
// Leftover bytes belong to a session that has ended; carrying them across would put a stale
// half-frame in front of the first real frame of the new one.
this.decoder.reset()
this.greetedMac = null
this.greetedFw = null
this.appFocusGeneration += 1
this.drivingAppFocus = false
this.expectedAppFocusEcho = ''
this.expectedAppFocusEchoUntil = 0
// A new port is a new dial until proven otherwise; tell it everything.
this.lastAgentsKey = ''
this.lastMachinesKey = ''
this.resetCapabilities()
// INCLUDING which images it has been offered. `offered` holds bare version strings and named no dial,
// so without this it outlived the session its comment claims it belongs to and became per-DAEMON:
// offer 0.0.42 to one dial, unplug it, plug in a second still on 0.0.41, and the second is refused
// because the version — not the board — had already been offered. It sat there on the old image with
// nothing in the log to say why.
//
// Clearing it does NOT reopen the flash loop this guards against. That is `mayOffer`'s job, and it is
// keyed by MAC and outlives the port precisely so this one does not have to.
this.offered.clear()
this.lastRx = Date.now()
this.log(`cable: open on ${opened.path}`)
}
private onClosed(why: string): void {
if (this.traffic.rx || this.traffic.tx) this.logLink('link at close')
this.log(`cable: closed (${why})`)
this.cancelFormVoice()
this.cancelSearchVoice()
this.passageCarry.clear()
this.voiceDraft.clear()
this.voiceDraftCreation = undefined
this.voiceCarryId = undefined
this.host.onDialGone?.()
this.activityReads.clear()
this.activityRefreshAt = 0
this.activityRefreshAgent = ''
this.activityLabels.clear()
// Unplugged, but not forgotten: the mac and the last settings ride along so the app can show the
// device's rows read-only rather than emptying the pane. The settings are kept on the session too —
// a device that comes back on the same port should not make the pane blink through empty.
this.host.onDialStatus?.({
attached: false,
...(this.greetedMac ? { mac: this.greetedMac } : {}),
...(this.greetedSettings ? { settings: this.greetedSettings } : {}),
})
this.link = null
this.greetedMac = null
this.greetedFw = null
this.appFocusGeneration += 1
this.expectedAppFocusEcho = ''
this.expectedAppFocusEchoUntil = 0
this.lastAgentsKey = ''
this.lastMachinesKey = ''
this.resetCapabilities()
this.voice = null
this.voiceGeneration++
// The dial keeps its running image; the half-written slot is erased again by the next accepted offer.
this.endFirmware('interrupted by the port closing')
// The dial discards a half-received pack when the link drops (it keeps showing the old pet), so there
// is nothing to resume: the next hello says what it holds and the missing pack is offered from byte 0.
this.petTransfer?.xfer.finish('interrupted by the port closing')
this.petTransfer = null
this.clearPetStall()
this.petsSupported = false
this.petHeld.clear()
this.petDoneAt.clear()
this.petErrors.clear()
this.petMapSent = ''
this.petDialMax = 0
this.petDropSent = false
this.petRetried.clear()
for (const timer of this.petRetryTimers) clearTimeout(timer)
this.petRetryTimers.clear()
}
// ── inbound ───────────────────────────────────────────────────────────────────────────────────────
/**
* What a dial may send in a second before it reads as hostile: a byte stream that is mostly not frames, a
* flood of frames, or bytes that take the decoder longer than it may spend. A dial sends a few dozen
* frames a second at most (voice is 16-bit PCM at 16 kHz, about 32 KB/s in frames of up to 8 KB), and its
* boot noise is a few hundred bytes; the decoder's worst case is a CRC over 8 KB for every eight bytes of
* a crafted stream, which at USB speed would hold the event loop for seconds at a time.
*/
static readonly BUDGET = { garbageBytes: 64 * 1024, frames: 2_000, decodeMs: 500 }
private budget = { since: 0, garbage: 0, frames: 0, ms: 0 }
/**
* This port's counters in the dial's log, to read beside the firmware's own `alive` line: a gap between
* what one side wrote and the other decoded is the lossy link. Plus the printable runs of the bytes the
* decoder stepped over (at most NOISE_MAX characters a minute), so a device panic's text is kept.
*/
private logLink(label: string): void {
const t = this.traffic
this.keepRun()
this.log(`cable: ${label} · tx ${t.tx} B in ${t.txFrames} frames · rx ${t.rx} B in ${t.rxFrames} frames · corrupt ${this.decoder.corruptFrames - t.corrupt} · discarded ${this.decoder.discardedBytes - t.discarded} B${t.noise ? ` · non-frame text: ${t.noise}` : ''}`)
t.at = Date.now()
t.noise = ''
}
/** Close the current run of printable discarded bytes into the minute's text, if it is long enough to read. */
private keepRun(): void {
const t = this.traffic
if (t.run.length >= NOISE_RUN_MIN && t.noise.length < NOISE_MAX) {
t.noise = `${t.noise}${t.noise ? ' | ' : ''}${t.run}`.slice(0, NOISE_MAX)
}
t.run = ''
}
private noted = (bytes: Uint8Array): void => {
for (const b of bytes) {
if (b >= 0x20 && b < 0x7f) {
if (this.traffic.run.length < NOISE_MAX) this.traffic.run += String.fromCharCode(b)
} else this.keepRun()
}
}
/** One frame to the dial, counted. */
private async put(link: CablePort, bytes: Uint8Array): Promise<void> {
await link.write(bytes)
this.traffic.tx += bytes.length
this.traffic.txFrames++
}
private onBytes(chunk: Buffer): void {
const started = performance.now()
const discarded = this.decoder.discardedBytes
let frames = 0
try {
this.decode(chunk, () => { frames++ })
} catch (error) {
// A throw inside the decoder's callback (the console log's write, the voice buffer) is this dial's
// fault: thrown out of the port's `data` event it would end the whole devices process.
this.fault(error)
}
const now = Date.now()
if (now - this.budget.since >= 1_000) this.budget = { since: now, garbage: 0, frames: 0, ms: 0 }
this.budget.garbage += this.decoder.discardedBytes - discarded
this.budget.frames += frames
this.budget.ms += performance.now() - started
const over = this.budget.garbage > CableSession.BUDGET.garbageBytes ? `${this.budget.garbage} B that are no frames`
: this.budget.frames > CableSession.BUDGET.frames ? `${this.budget.frames} frames`
: this.budget.ms > CableSession.BUDGET.decodeMs ? `${Math.round(this.budget.ms)} ms of decoding` : ''
if (over) {
this.budget = { since: now, garbage: 0, frames: 0, ms: 0 }
this.fault(new Error(`${over} in a second, more than a dial sends`), true)
}
}
private decode(chunk: Buffer, counted: () => void): void {
this.lastRx = Date.now()
this.bytesSinceOpen += chunk.length
this.traffic.rx += chunk.length
this.decoder.onDiscard = this.noted
this.decoder.feed(chunk, (frame) => {
counted()
this.traffic.rxFrames++
this.framesSinceOpen += 1
if (frame.type === CableType.Json) {
let msg: Message
try {
msg = JSON.parse(Buffer.from(frame.payload).toString('utf8')) as Message
} catch {
return // unreadable payloads are counted by the decoder, never fatal
}
// Its failure is this dial's: a rejection left unhandled would end the whole devices process.
void this.onMessage(msg).catch((error: unknown) => this.fault(error))
return
}
if (frame.type === CableType.Log) {
// The dial's console. It shares its one USB port with this protocol, so these frames are the only
// way its log survives at all while the daemon holds the port.
this.dialLog.device(Buffer.from(frame.payload).toString('utf8'))
return
}
if (frame.type === CableType.Pcm) {
this.onPcm(Buffer.from(frame.payload))
return
}
// An unknown type is a dial running ahead of this daemon. Visible, never fatal.
this.log(`cable: unknown frame type 0x${frame.type.toString(16)}`)
})
}
private async onMessage(msg: Message): Promise<void> {
const str = (key: string): string | undefined =>
typeof msg[key] === 'string' ? (msg[key] as string) : undefined
switch (msg.t) {
case 'hello': {
// ⚠️ A POSITIVE MATCH, AND ABSENCE MEANS NO. The framing magic already stops the sibling product's
// dial from ever getting this far, so reaching here with the wrong product means something changed
// that this code cannot see — a re-unified magic, a fork of this firmware, a third product. The
// safe reading of "I do not recognise you" is never "you are probably mine".
//
// Answered with nothing at all: a `welcome` is what starts a session, and there is no session to
// have with a dial that is not ours. The port is released on the next tick by the same rule that
// handles a dial we cannot decode.
const product = str('product')
if (product !== CABLE_PRODUCT) {
if (this.foreignPort !== this.link?.path) {
this.log(`cable: greeted by a '${product ?? 'nameless'}' dial, not a ${CABLE_PRODUCT} one — releasing the port`)
}
this.foreignPort = this.link?.path ?? null
this.foreignRetryAt = Date.now() + 60_000
if (this.link) this.reportForeign(this.link.path, `greeted as '${product ?? 'nameless'}'`)
await this.link?.close('another product')
this.link = null
return
}
// Named before the welcome, which advertises the library only to a device that asked for it.
this.swarmMembers = str('swarms') === 'members-v1'
this.longRecap = str('recap') === 'long-v1'
this.stepsActivity = str('activity') === 'steps-v1'
this.statsTurn = str('stats') === 'turn-v1'
this.playerCapable = str('player') === 'library-v1'
this.superTabWaits = str('superTab') === 'wait-v1'
this.swarmCard = str('swarmCard') === 'v1'
this.swarmChat = this.swarmCard && str('swarmChat') === 'v1'
this.swarmBuddy = this.swarmChat && str('swarmBuddy') === 'v1'
this.swarmNeedsYou = this.swarmChat && str('swarmNeedsYou') === 'v1'
this.swarmReview = this.swarmChat && str('swarmReview') === 'v1'
this.wantCards(this.swarmCard)
this.seqOn = str('board') === 'pro'
this.seq = 0
const mac = str('mac') ?? ''
// Rule 1: every greeting is answered, but only an unfamiliar dial gets the full state.
await this.send({
t: 'welcome',
proto: CABLE_PROTO_VERSION,
app: this.host.appName(),
// The CABLED computer's identity — no longer "the one machine". It was the dial's own mac here
// until proto 2, which was simply wrong: a mac is not a machine id and nothing could select it.
machine: this.host.localMachine(),
// Stated up front so the ✓ is correct from the first frame, before any list arrives — which
// matters after a dial reboot that lands mid-session on a remote selection.
selected: this.host.selectedMachine(),
voiceLang: this.host.voiceLang(),
// Optional controls must be advertised: a new dial can remain useful
// with an older daemon instead of waiting on commands it ignores.
features: [
'voice.draft',
'agents.refresh',
...(this.playerCapable && this.host.playerLibrary ? ['player.library'] : []),
// Only a Pro numbers its frames and asks for `resync`; a round dial's feature list stays as it was.
...(this.seqOn ? ['resync'] : []),
...(this.host.form ? ['form'] : []),
...(this.host.selectPassage ? ['selection'] : []),
...(this.host.visit ? ['visit'] : []),
...(this.host.answerReviewed ? ['question.review'] : []),
// Words reviewed on a Swarm face are posted in its chat by Send. A dial asks for review there only when it sees
// this: an older daemon would type the reviewed words into the Lead's terminal.
// swarm.remote: a dial names a Lead on another machine by its Swarm id, which an older daemon would hand to the
// pane focused in the window.
...(this.host.swarmSay ? ['swarm.review', 'swarm.remote'] : []),
// The desktop will carry this device's preferences. A device that does not see this keeps
// its own settings screens and never reports.
'settings',
],
})
// Log a dial that is new OR that came back running something else. The version half of that test
// is not decoration: a dial reboots into its new image after an update and greets with the SAME
// mac, so keying the line on the mac alone suppresses the one line anybody wants after an OTA —
// "it came back, and on which version". Losing it left a successful 0.0.37 install unverifiable
// from the log on 2026-08-24.
const fw = str('fw') ?? '?'
const hw = str('hw')
const board = str('board')
this.greetedHw = hw || undefined
this.greetedBoard = board || undefined
this.greetedOta = str('ota') || undefined
// Read before the change test below, so a device that only changed a setting still corrects the
// pane: its fw and mac are the same, and without this the greeting would be treated as a keepalive.
const settings = readSettings(msg.settings)
const settingsChanged = JSON.stringify(settings) !== JSON.stringify(this.greetedSettings)
this.greetedSettings = settings
this.skinReported = hasUiSkin(msg.settings)
const keepalive = mac === this.greetedMac && fw === this.greetedFw
if (settingsChanged && keepalive) this.report()
if (!keepalive) {
this.playerOffset = this.playerRequest = 0
this.playerLibraryKey = ''
const returning = mac === this.greetedMac
this.greetedMac = mac
this.everGreeted = true
this.greetedFw = fw
this.log(`cable: dial ${mac} ${returning ? 'back ' : ''}on fw ${fw} proto ${msg.proto}${hw ? ` hw ${hw}` : ''}${board ? ` board ${board}` : ''}${this.capabilitiesNamed()}`)
this.dialLog.greeted()
this.report({ fw })
// BEFORE the state push, not after: the push reads the selected machine, and for a remote one
// that means an RPC over a lane this is what re-opens.
this.host.onDialAttached?.()
// Both halves of the test above mean the same thing to this line: a dial with nothing on its
// screen. A repeat greeting from the same dial on the same image is a keepalive and is skipped,
// which is the whole reason the branch exists.
await this.pushAgents()
const focused = this.host.appFocus?.()
if (focused) await this.followApp(focused.machineId, focused.agentId)
}
// Offered on every greeting, but only ONCE per version per session: accepting makes the dial erase
// a flash slot before it answers, so a cadence of retries would spend erase cycles on the user's
// hardware every fifteen seconds, and nothing about the next greeting changes what went wrong.
await this.maybeOfferFirmware(str('fw') ?? '', keepalive)
// AFTER the firmware offer, so a pending image is already `this.transfer` and the pets wait for it.
this.readPetHello(msg)
await this.syncPets()
return
}
case 'pong':
return
case 'agents.list':
await this.pushAgents()
// A Pro asks for this as its session comes back, having dropped every question with the link (pro_app_link):
// the Super Tab waits still open are asked again. The same alert, so it does not beep twice.
await this.resendSuperTabAsks()
return
case 'agents.refresh':
// A workspace receipt needs the roster, not machines, notices and history.
await this.syncAgents(true)
return
case 'machines.list':
await this.syncMachines(true)
return
case 'machine.select':
await this.selectMachine(str('machineId') ?? '')
return
case 'swarms.list':
await this.syncSwarms(true)
return
case 'resync':
await this.resync()
return
case 'supertab.recap.get':
case 'supertab.open':
case 'supertab.select':
await this.onSuperTab(msg.t, str('tab') ?? '', str('lead') ?? '')
return
case 'swarm.select':
// Not answered here: the window switches, its desk changes, and the new `swarms` and ring
// pushes are the answer — the same shape as `machine.select`, minus the refusal, because the
// window never refuses to show a tab it has.
this.host.selectSwarm(str('swarmId') ?? '')
return
case 'models.list': {
// The one round trip in this protocol: the dial cannot draw a picker until the catalog is in hand,
// so it waits on this — briefly, and off its own UI task.
const agentId = str('agentId') ?? ''
let items: string[] = []
try {
items = await this.host.listModels(agentId)
} catch (err) {
this.log(`cable: models for ${agentId} failed (${(err as Error).message})`)
}
// Answered either way. An empty catalog closes the dial's picker cleanly; silence strands it on a
// spinner until its own timeout, which reads as a hang rather than "this engine has no choices".
// Additive correlation: older firmware ignores this and older hosts
// still identify replies by agentId. Never echo an unbounded value.
const serial = msg.request
const request = typeof serial === 'number' && Number.isInteger(serial)
&& serial > 0 && serial <= 0x7fffffff ? serial : undefined
// One frame, as the dial keeps it: the model it has selected first, then the catalog in order, up to the 48 its
// picker holds and only while the frame stays within the cap (bytes, and tokens as cable_json_guard.c counts
// them). A Kilo agent lists about 325 ids, about 32 KB against the 8 KB cap (Diego, 2026-11-03).
const selected = str('selected')
const ordered = selected && items.includes(selected) ? [selected, ...items.filter((id) => id !== selected)] : items
const reply: Message = { t: 'models', agentId, ...(request === undefined ? {} : { request }), items: [] as Array<{ id: string }> }
const kept = reply.items as Array<{ id: string }>
for (const id of ordered) {
if (kept.length >= MODELS_MAX) break
kept.push({ id })
// An id that does not fit is left out; a shorter one after it may still.
if (!fitsFrame(reply)) kept.pop()
}
if (kept.length < ordered.length) this.log(`cable: models for ${agentId}: ${kept.length} of ${ordered.length} fit one frame`)
await this.send(reply)
return
}
case 'focus':
if (str('agentId')) {
const agentId = str('agentId')!
const now = Date.now()
const expectationActive = this.expectedAppFocusEcho !== ''
&& now <= this.expectedAppFocusEchoUntil
if (expectationActive) {
// Until the commanded tile echoes, every other focus is from the carousel/list repaint that
// command caused. Do not even update the record: the daemon already commanded the newer truth.
if (agentId === this.expectedAppFocusEcho) {
this.expectedAppFocusEcho = ''
this.expectedAppFocusEchoUntil = 0
} else {
// SAID OUT LOUD. A dropped report is a dial and a window on different agents, and dropping
// it silently is how that state became impossible to explain from the log.
this.log(`cable: dropped dial focus ${agentId} — waiting for ${this.expectedAppFocusEcho}`)
}
return
}
if (now > this.expectedAppFocusEchoUntil) {
this.expectedAppFocusEcho = ''
this.expectedAppFocusEchoUntil = 0
}
// A machine switch re-paints the carousel and may report its OLD tile while the new list is in
// flight. That one report is not a hand and must not drive the window back.
//
// ONLY that one. This used to drop everything for as long as the switch took, and a remote
// machine's switch takes seconds — measured at ten. Every swipe made in that window vanished,
// so the dial walked on and the window stayed where it was, with the two screens naming
// different agents and nothing left to correct them. A dial that reports a move it did not make
// is fixed at the source now (carousel_goto in the firmware), which leaves only the stale repeat
// of the tile the dial was already on to guard against.
if (this.drivingAppFocus && now - this.drivingSince < APP_SWITCH_REPAINT_MS) {
this.log(`cable: dropped dial focus ${agentId} — repaint from the switch in flight`)
return
}
// Remember where the dial IS, not just that it said so: followApp() compares against this to
// avoid echoing the dial's own move back at it.
this.desiredFocus = agentId
this.appFocusUnsent = false
this.host.focus(agentId)
}
return
case 'notif.read': {
const agentId = str('agentId')
const token = notificationReadToken(msg.readToken)
if (agentId && token) this.host.readNotification?.(agentId, token)
return
}
case 'player.library.get': {
if (!this.playerCapable || !Number.isSafeInteger(msg.offset) || (msg.offset as number) < 0 ||
(msg.offset as number) > 1_000_000 || !Number.isSafeInteger(msg.request) ||
(msg.request as number) < 0 || (msg.request as number) > 0xffffffff) return
this.playerOffset = msg.offset as number
this.playerRequest = msg.request as number
await this.syncPlayerLibrary(true)
return
}
case 'agent.open': {
// Only the one reason the window knows; anything else reads as a tap, the older frame's meaning.
const agentId = str('agentId'), reason = str('reason') === 'question' ? 'question' as const : undefined
if (!agentId) return
// A tap on the reader's Buddy or a Lead running here opens its chat in the Swarm tab: a terminal tab of its own is
// one whose close stopped the Buddy (Diego, 10-30). A question screen brings the agent forward as before.
const swarm = reason ? null : this.swarmSessionOf(agentId)
if (swarm) this.openSwarmChat(swarm.tab, swarm.projectId, swarm.chat)
else this.host.openAgent(agentId, reason)
return
}
case 'agent.fork': {
// The dial's Fork action. The host opens the new agent in the window itself; the dial only needs
// to hear a refusal, as a toast, so a press that did nothing is not a press that was lost.
const id = str('agentId')
if (!id) return
void this.host.forkAgent(id).then((result) => {
if (!result.ok) return this.toast(result.detail ?? result.error)
}).catch((err) => this.toast((err as Error).message))
return
}
case 'scroll': {
// Forwarded verbatim, including the reports carrying no travel: the two ends of a stroke are the
// whole point of the message. A `down` with nothing in it stops a fling still running, and an `up`
// with nothing in it is a finger that came to rest before it lifted and must not be thrown.
const phase = str('phase')
if (phase !== 'down' && phase !== 'move' && phase !== 'up') return
const dy = typeof msg.dy === 'number' ? msg.dy : 0
const v = typeof msg.v === 'number' ? msg.v : 0
if (this.openLead) this.host.scrolled(phase, dy, v, this.openLead.tabId)
else this.host.scrolled(phase, dy, v)
return
}
case 'selection': {
const agentId = str('agentId')
const op = str('op')
const requestId = str('requestId')
if (!agentId || !requestId || requestId.length > 64 || !op || !['begin', 'step', 'extend', 'cancel', 'match', 'lines'].includes(op)) return
const command: SelectionCommand = { agentId, op: op as SelectionCommand['op'],
selectionId: str('selectionId'), revision: typeof msg.revision === 'number' ? msg.revision : undefined,
delta: typeof msg.delta === 'number' ? msg.delta : undefined, extend: typeof msg.extend === 'boolean' ? msg.extend : undefined }
const link = this.link
const result = await (this.host.selectPassage?.(command) ?? Promise.resolve({ ok: false as const, error: 'Update Harness to select text.' }))
if (this.link === link) await this.send({ t: 'selection.state', requestId, ...result })
return
}
case 'carry.prepare': {
const id = str('carryId') ?? '', requestId = str('requestId')
if (!requestId || requestId.length > 64) return
const link = this.link
const result = await this.passageCarry.prepare(id, { op: 'pin', agentId: str('agentId') ?? '',
selectionId: str('selectionId'), revision: typeof msg.revision === 'number' ? msg.revision : undefined })
if (this.link === link) await this.send({ t: 'carry.state', requestId, carryId: id, ...result })
return
}
case 'carry.cancel': {
const id = str('carryId')
if (!id) return
this.passageCarry.clear(id)
if (this.voiceCarryId === id) {
this.voiceGeneration++
this.voice = null
this.voiceCarryId = undefined
}
return
}
case 'form': {
const op = str('op'), formId = str('formId'), requestId = str('requestId')
if (!formId || !requestId || requestId.length > 64 || !op ||
!['open', 'state', 'move', 'activate', 'back', 'close'].includes(op)) return
const link = this.link
const result = await (this.host.form?.({ op: op as FormCommand['op'], formId,
...(msg.surface !== undefined ? { surface: msg.surface as FormCommand['surface'] } : {}),
revision: typeof msg.revision === 'number' ? msg.revision : undefined,
delta: typeof msg.delta === 'number' ? msg.delta : undefined }) ??
Promise.resolve({ ok: false, active: false, error: 'Update Harness for New Harness.' }))
if (this.link === link) await this.send({ t: 'form.state', requestId, formId, ...result })
return
}
case 'visit': {
const op = str('op'), visitId = str('visitId'), requestId = str('requestId')
if (!visitId || !requestId || requestId.length > 64 || !op ||
!['open', 'latest', 'back', 'cancel'].includes(op)) return
const link = this.link
const result = await (this.host.visit?.({ op: op as VisitCommand['op'], visitId, agentId: str('agentId') }) ??
Promise.resolve({ ok: false, active: false, error: 'Update Harness to visit an alert.' }))
if (this.link === link) await this.send({ t: 'visit.state', requestId, visitId, ...result })
return
}
case 'turn.send':
if (str('agentId') && str('text')) this.host.sendTurn(str('agentId')!, str('text')!)
return
case 'turn.stop':
if (str('agentId')) this.host.stopTurn(str('agentId')!)
return
case 'draft.command': {
const id = str('draftId'), requestId = str('requestId'), op = str('op'), revision = msg.revision
if (!id || !requestId || requestId.length > 64 || !op || !Number.isSafeInteger(revision)) return
const link = this.link
const state = await this.voiceDraft.command(id, revision as number, op,
typeof msg.delta === 'number' ? msg.delta : 0)
if (this.link === link) await this.send({ t: 'draft.state', requestId, ...state })
return
}
case 'question.read': {
const agentId = str('agentId'), requestId = str('requestId')
if (!agentId || !requestId || requestId.length > 64) return
const state = this.questionInbox.read(agentId)
if (state.ok && !this.host.canSpeakQuestion?.(agentId))
state.questions = state.questions.map(q => ({ ...q, canText: false }))
await this.send({ t: 'question.state', agentId, requestId, ...this.whoIs(agentId), ...state })
return
}
case 'answer.reviewed': {
const agentId = str('agentId'), token = str('token'), requestId = str('requestId')
if (!agentId || !token || !requestId || requestId.length > 64) return
const link = this.link
const receipt = await this.questionInbox.submit(agentId, token, msg.choices,
answer => this.host.answerReviewed?.(answer) ?? Promise.resolve({ ok: false,
error: 'Update Harness to answer this question.' }), msg.drafts)
if (this.link === link) await this.send({ t: 'answer.receipt', agentId, token, requestId, ...receipt })
return
}
case 'answer': {
// `answers` is the dial's own object, one entry per question, keyed by the keys WE asked with. It
// travels verbatim. Until proto 2 this case demanded `{id, optionId}` — a shape the dial has never
// sent — so every answer from the question screen was silently dropped on the floor.
const agentId = str('agentId')
const requestId = str('requestId')
const answers = msg.answers
if (agentId && requestId && answers && typeof answers === 'object' && !Array.isArray(answers)) {
const flat: Record<string, string> = {}
for (const [k, v] of Object.entries(answers as Record<string, unknown>)) {
if (typeof v === 'string') flat[k] = v
}
this.host.answer(agentId, requestId, flat)
}
return
}
case 'agent.update':
if (str('agentId')) this.host.updateAgent(str('agentId')!, str('model'), str('effort'))
return
case 'voice.begin': {
this.cancelFormVoice()
this.cancelSearchVoice()
this.voiceDraftCreation = undefined
this.voiceGeneration++
this.voiceUploadId = str('uploadId') ?? ''
this.voiceCarryId = str('carryId')
// Presence, even malformed, selects this purpose. It can never fall back
// to task routing or an agent's terminal.
const formVoice = 'formId' in msg || 'formRevision' in msg
const searchVoice = 'searchId' in msg || 'searchRevision' in msg
const draftVoice = 'draftId' in msg || 'draftRevision' in msg || 'draftOp' in msg
const questionVoice = 'questionToken' in msg || 'questionIndex' in msg
const carryVoice = 'carryId' in msg
const carry: CarryRead | undefined = !formVoice && !questionVoice && !draftVoice && !searchVoice && carryVoice
? (typeof msg.carryId === 'string' && str('agentId') && !('cmd' in msg) && !('selectionId' in msg)
? this.passageCarry.read(msg.carryId)
: { ok: false, error: 'Choose the carried text and its recipient again.' }) : undefined
let draft: { pin?: DraftPin } | undefined
if (draftVoice) {
const id = str('draftId'), revision = msg.draftRevision
draft = { pin: id && Number.isSafeInteger(revision) &&
!formVoice && !questionVoice && !carryVoice && !searchVoice && !('agentId' in msg) && !('cmd' in msg) && !('selectionId' in msg)
? this.voiceDraft.pin(id, revision as number, msg.draftOp) : undefined }
}
let question: { pin?: QuestionSpeech } | undefined
if (questionVoice) {
const agentId = str('agentId'), token = str('questionToken'), index = msg.questionIndex
const pin = agentId && token && Number.isInteger(index) &&
!formVoice && !carryVoice && !draftVoice && !searchVoice && !('cmd' in msg) && !('selectionId' in msg)
? { agentId, token, index: index as number } : undefined
question = { pin: pin && this.host.canSpeakQuestion?.(pin.agentId) &&
this.questionInbox.canSpeak(pin) ? pin : undefined }
}
let form: { command?: FormCommand; pin: Promise<FormResult> } | undefined
if (formVoice) {
const formId = str('formId'), revision = msg.formRevision, queryId = this.voiceUploadId
const valid = formId && /^[a-zA-Z0-9-]{1,48}$/.test(formId) &&
/^[a-zA-Z0-9-]{1,64}$/.test(queryId) && Number.isSafeInteger(revision) &&
(revision as number) >= 0 && !('agentId' in msg) && !('selectionId' in msg) && !('cmd' in msg) && !carryVoice && !questionVoice && !draftVoice && !searchVoice
const command: FormCommand | undefined = valid
? { formId, op: 'query.begin', revision: revision as number, queryId } : undefined
this.voiceForm = command
form = { command, pin: (command && this.host.form ? this.host.form(command)
: Promise.resolve({ ok: false, active: false, error: 'Open a field and say its name again.' }))
.catch(() => ({ ok: false, active: false, error: 'Could not open voice search. Try again.' })) }
}
let search: { command?: SelectionCommand; pin: Promise<SelectionResult> } | undefined
if (searchVoice) {
const selectionId = str('searchId'), revision = msg.searchRevision, agentId = str('agentId')
const valid = selectionId && /^[a-zA-Z0-9-]{1,48}$/.test(selectionId) && agentId && agentId.length <= 200 &&
/^[a-zA-Z0-9-]{1,64}$/.test(this.voiceUploadId) && Number.isSafeInteger(revision) &&
(revision as number) > 0 && (revision as number) <= 0x7fffffff &&
!formVoice && !questionVoice && !draftVoice && !carryVoice && !('selectionId' in msg) && !('cmd' in msg)
const command: SelectionCommand | undefined = valid ? { op: 'read', selectionId, revision: revision as number, agentId } : undefined
this.voiceSearch = command
search = { command, pin: (command && this.host.selectPassage ? this.host.selectPassage(command)
: Promise.resolve({ ok: false, error: 'Choose a passage before searching.' } as const))
.catch(() => ({ ok: false, error: 'Could not open output search. Try again.' })) }
}
// The dial can still name the previous pane while a focus frame is in flight, or after the
// devices process restarted. Ordinary dictation belongs to the window's selection at capture
// start. Quoted text, carried text, questions and edits already have their own pinned targets.
// Except words for a Swarm face's chat: the dial shows that chat, so a pane focused in the window never takes them.
const plain = str('agentId') && !formVoice && !searchVoice && !draftVoice && !questionVoice && !carryVoice && !('selectionId' in msg)
// A Pro says `face` when the words were spoken on its Lead view, which shows that chat (Swarm parity, part 3).
const proFace = msg.face === true
const dialFace = plain ? this.voiceFaceOf(str('agentId')!, proFace) : undefined
// A Swarm Lead's id (the backend's 24 hex; a harness's is a UUID) with no card here yet (the devices process just
// restarted) or any more: words for a Lead on another machine, which the focused pane must not take (review of #2232).
const swarmId = plain && !dialFace && SWARM_AGENT_ID.test(str('agentId')!)
const focused = plain && !dialFace && !swarmId ? this.host.appFocus?.() : undefined
const agentId = focused?.agentId ?? str('agentId')
const swarmFace = dialFace ?? (agentId ? this.voiceFaceOf(agentId, proFace) : undefined)
this.voice = {
agentId,
...(swarmFace ? { swarmFace } : {}),
...((swarmFace && agentId && !this.swarmLeadHere(agentId)) || swarmId ? { swarmRemote: true } : {}),
cmd: str('cmd'),
lang: str('lang') ?? this.host.voiceLang(),
// The DIAL's rate, never this side's guess. 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.
rate: typeof msg.sr === 'number' && msg.sr > 0 ? msg.sr : DEFAULT_VOICE_RATE,
chunks: [],
bytes: 0,
form,
carry,
question,
draft,
search,
...(!formVoice && !carryVoice && !questionVoice && !draftVoice && !searchVoice && str('selectionId') ? {
selectionId: str('selectionId'),
selection: (str('agentId') && this.host.selectPassage
? this.host.selectPassage({ op: 'pin', agentId: str('agentId')!, selectionId: str('selectionId'),
revision: typeof msg.selectionRevision === 'number' ? msg.selectionRevision : undefined })
: Promise.resolve({ ok: false as const, error: 'Choose the text again.' }))
.catch(() => ({ ok: false as const, error: 'Could not attach that text. Choose it again.' })),
} : {}),
}
return
}
case 'voice.abort':
// An abort queued for the previous recording must not cancel its replacement.
if (str('uploadId') && str('uploadId') !== this.voiceUploadId) return
if (this.voiceDraftCreation?.uploadId === this.voiceUploadId) {
this.voiceDraft.cancelCreation(this.voiceDraftCreation.id)
this.voiceDraftCreation = undefined
}
this.cancelFormVoice()
this.cancelSearchVoice()
if (this.voice?.selectionId && this.voice.agentId) void this.host.selectPassage?.({
op: 'cancel', agentId: this.voice.agentId, selectionId: this.voice.selectionId })
this.voiceGeneration++
this.voice = null
this.voiceCarryId = undefined
return
case 'voice.end':
if (str('uploadId') && str('uploadId') !== this.voiceUploadId) return
await this.finishVoice(msg.review === true)
return
case 'voice.confirm':
if (str('routeId') && str('agentId')) this.host.focus(str('agentId')!)
return
case 'settings.state': {
// The device's answer to a `settings.set`, and also what it sends unprompted after a change made
// on the glass. Carries the values READ BACK, so a refusal corrects the pane rather than leaving
// it hopeful — which is why the settings are taken even when `ok` is false.
const settings = readSettings(msg.settings)
if (settings) this.greetedSettings = settings
if (hasUiSkin(msg.settings)) this.skinReported = true
if (msg.ok === false) this.log(`cable: device refused a settings change: ${str('error') ?? 'no reason given'}`)
this.report()
return
}
case 'fw.accept':
// The dial has erased its slot and is expecting bytes. Nothing was sent before this.
// The window is told NOW rather than at the offer: an offer the dial refuses is nothing to
// show, and the minute that matters — do not unplug it — starts here.
this.report({ updating: this.offeringTo })
this.armFwStall()
await this.transfer?.pump()
return
case 'fw.progress':
// Not only a progress bar: this ack IS the credit that lets the next slices go.
if (typeof msg.written === 'number') {
if (msg.written > this.fwAcked) {
this.fwAcked = msg.written
this.armFwStall()
}
if (msg.resend === true && this.transfer) {
// The device dropped a slice (CRC) and wants the image again from `written`.
await this.transfer.onResend(msg.written)
if (this.transfer.isDone) {
this.endFirmware('too many resends')
this.report()
void this.syncPets()
}
} else await this.transfer?.onProgress(msg.written)
}
return
case 'fw.done':
// WHETHER AN UPDATE LANDS is not something the release process can see:
// a version is published, and after that the only evidence is the next
// `hello` from a dial that may never have taken it.
this.endFirmware('installed — the dial is rebooting', true)
// Still attached from the window's side: the reboot re-greets within seconds and the fw
// field corrects itself then. Clearing `updating` is what matters.
this.report()
return
case 'fw.error':
// The outcome is `refused`, not the dial's message: that string is the
// firmware's own text and this stream carries short codes.
this.endFirmware(`refused: ${str('message') ?? 'no reason given'}`)
this.report()
// Pets that waited behind the image go now.
await this.syncPets()
return
case 'pet.accept':
// Only for the pack in flight; a stale accept for another id must not start slices of this one.
if (this.petTransfer && str('id') === this.petTransfer.id) {
this.armPetStall()
await this.petTransfer.xfer.pump()
}
return
case 'pet.progress':
// The credit that lets the next slices go, exactly as fw.progress is.
if (this.petTransfer && str('id') === this.petTransfer.id && typeof msg.written === 'number') {
this.petTransfer.written = msg.written
this.armPetStall()
await this.petTransfer.xfer.onProgress(msg.written)
}
return
case 'pet.done': {
const id = str('id')
if (!id) return
if (this.petTransfer?.id === id) {
this.petTransfer.xfer.finish('stored')
this.petTransfer = null
this.clearPetStall()
}
this.petHeld.add(id)
this.petDoneAt.set(id, Date.now())
// The next pack, one at a time.
await this.syncPets()
return
}
case 'pet.error': {
const id = str('id')
const reason = str('reason') ?? 'unknown'
if (!id) return
// memory and busy will not change within this link; crc, version and shape would fail identically on a
// resend of the same bytes. All are recorded and none retried until the link comes back.
this.petErrors.set(id, reason)
this.log(`cable: dial refused pet ${id}: ${reason}`)
if (this.petTransfer?.id === id) {
this.petTransfer.xfer.finish(`refused: ${reason}`)
this.petTransfer = null
this.clearPetStall()
}
// A swap near full memory: the pack we dropped may not be freed yet. Once per pack and link, offer again.
if ((reason === 'memory' || reason === 'busy') && this.petDropSent && !this.petRetried.has(id)) {
this.petRetried.add(id)
const timer = setTimeout(() => {
this.petRetryTimers.delete(timer)
if (this.petErrors.get(id) === reason) this.petErrors.delete(id)
void this.syncPets()
}, PET_RETRY_MS)
timer.unref?.()
this.petRetryTimers.add(timer)
}
await this.syncPets()
return
}
default:
this.log(`cable: unhandled message '${msg.t}'`)
}
}
/** Offer an update if there is one, the dial is not on it, and this session has not tried it already. */
/**
* May this version be written to this dial at all?
*
* DEFENCE IN DEPTH, AND IT IS THE LAYER THAT PROTECTS THE HARDWARE. Everything above decides whether a
* dial is ours; this decides how badly a wrong answer can hurt. An OTA writes three megabytes and
* reboots, so a pair of daemons that disagree about ownership do not merely argue — they take turns
* flashing the same board every fifteen seconds, which is about 700 MB an hour into a flash rated in
* erase cycles. The device is unusable throughout, and nothing about it looks like a loop from either
* side: each daemon sees a dial on an unexpected version and does the reasonable thing.
*
* `offered` alone does not cover it: that set is per SESSION, and every one of those flashes ends in a
* reboot that starts a new one. This memory is keyed by the dial and outlives the port.
*/
private mayOffer(mac: string, version: string): boolean {
const key = `${mac}:${version}`
// `written` means INSTALLED (fw.done). A refused, interrupted or stalled offer is not in it and is offered
// again at the next hello, but every attempt is in `writeLog`, so the hourly cap still bounds the retries.
if (this.written.has(key)) {
this.log(`cable: firmware ${version} already written to ${mac} — not offering it again`)
return false
}
const now = Date.now()
const recent = (this.writeLog.get(mac) ?? []).filter((at) => now - at < 60 * 60 * 1000)
if (recent.length >= FW_WRITES_PER_HOUR) {
this.log(`cable: ${mac} has taken ${recent.length} firmware writes this hour — holding off`)
return false
}
this.writeLog.set(mac, [...recent, now])
return true
}
/** Close the firmware transfer. Only `installed` makes the version final; anything else may be offered again. */
private endFirmware(reason: string, installed = false): void {
this.transfer?.finish(reason)
this.transfer = null
this.offeringTo = ''
if (this.fwStall) clearTimeout(this.fwStall)
this.fwStall = null
if (this.offeringKey) {
if (installed) this.written.add(this.offeringKey)
else this.offered.delete(this.offeringKey)
}
this.offeringKey = ''
}
/** (Re)start the no-progress timer for the image in flight; a silently aborted one would block offers and pets forever. */
private armFwStall(): void {
if (this.fwStall) clearTimeout(this.fwStall)
this.fwStall = null
const t = this.transfer
if (!t) return
this.fwStall = setTimeout(() => {
this.fwStall = null
if (this.transfer !== t) return
this.log(`cable: firmware ${t.version} stalled for ${FW_STALL_MS / 1000} s, giving up on this transfer`)
this.endFirmware('timed out')
this.report()
void this.syncPets()
}, FW_STALL_MS)
this.fwStall.unref?.()
}
private async maybeOfferFirmware(runningVersion: string, keepalive: boolean): Promise<void> {
// A pack in flight also holds it back: the reader task that writes flash is busy with the pack, and the
// next hello (every fifteen seconds) asks again.
if (!this.host.firmwareFor || this.transfer || this.petTransfer || !runningVersion) return
// Which manifest entry this device's image comes from is decided from its own hello, never defaulted —
// see otaKeyFor. An unknown board, a Pro that does not say `ota: "v1"` and an old Player-1 Pro get none.
const key = otaKeyFor(this.greetedHw, this.greetedBoard, this.greetedOta)
if (!key) {
const who = this.greetedMac ?? 'unknown'
if (!this.noChannelLogged.has(who)) {
this.noChannelLogged.add(who)
this.log(`cable: not offering firmware — board "${this.greetedBoard ?? this.greetedHw}" has no image channel`)
}
return
}
const ask = keepalive ? this.host.firmwareFor(runningVersion, key, true) : this.host.firmwareFor(runningVersion, key)
const candidate = await ask.catch(() => null)
// A pet transfer may have started while that await was parked (petsChanged); never start an image beside it.
if (this.petTransfer || this.transfer) return
// Keyed by DIAL as well as version. Holding bare version strings made this a statement about the
// image rather than about the board: offer 0.0.42 to one dial, swap in a second still on 0.0.41, and
// the second was refused because that version had been offered — to someone else. It then sat on the
// old image with nothing in the log to say why, which is how it was found.
if (!candidate) return
const mac = this.greetedMac ?? 'unknown'
const offerKey = `${mac}:${candidate.version}`
if (this.offered.has(offerKey)) return
if (!this.mayOffer(mac, candidate.version)) return
this.offered.add(offerKey)
this.log(`cable: offering firmware ${candidate.version} (${candidate.image.length} B)`)
this.offeringTo = candidate.version
this.offeringKey = offerKey
this.fwAcked = 0
this.transfer = new FirmwareTransfer(
candidate.image,
candidate.version,
async (slice) => {
if (!this.link?.isOpen) throw new Error('port closed mid-transfer')
await this.put(this.link, encodeCableFrame(CableType.Fw, slice))
},
(line) => this.log(line),
{ offsets: this.greetedBoard === 'pro' && this.greetedOta === 'v1' },
)
this.armFwStall()
await this.send({ t: 'fw.offer', version: candidate.version, size: candidate.image.length, sha256: candidate.sha256 })
}
// ── custom pets ───────────────────────────────────────────────────────────────────────────────────
private readPetHello(msg: Message): void {
const was = this.petHeld
this.petDialMax = typeof msg.pets === 'number' && Number.isFinite(msg.pets) ? Math.floor(msg.pets) : 0
this.petsSupported = this.petDialMax >= 1
// Each greeting forgives what was only the moment's trouble; a pack the dial found wrong stays refused.
this.clearTransientPetErrors()
const ids = Array.isArray(msg.petIds) ? msg.petIds.filter((v): v is string => typeof v === 'string' && /^[0-9a-f]{16}$/.test(v)) : []
this.petHeld = new Set(this.petsSupported ? ids : [])
const now = Date.now()
for (const [id, at] of this.petDoneAt) {
if (now - at >= PET_DONE_TRUST_MS) this.petDoneAt.delete(id)
else if (this.petsSupported && was.has(id)) this.petHeld.add(id)
}
// A dial that holds less than it did has rebooted under a link that stayed open: it has forgotten the
// map too, so it is sent again.
const shrank = [...was].some((id) => !this.petHeld.has(id))
if (shrank) this.petMapSent = ''
// ...and it has forgotten a transfer in flight too (it reboots without the link closing): that one is over. A
// hello that lists the pack in flight means it was stored and its pet.done went missing.
const t = this.petTransfer
if (t && (shrank || this.petHeld.has(t.id))) {
t.xfer.finish(this.petHeld.has(t.id) ? 'stored' : 'dial restarted')
this.petTransfer = null
this.clearPetStall()
}
}
private clearTransientPetErrors(): void {
for (const [id, reason] of this.petErrors) if (PET_TRANSIENT.has(reason)) this.petErrors.delete(id)
}
/** What the Devices tab shows for this dial's pets. */
petDial(): PetDialState & { errors: Record<string, string> } {
const t = this.petTransfer
return {
supported: this.petsSupported,
held: [...this.petHeld],
sending: t ? { id: t.id, percent: t.size > 0 ? Math.min(100, Math.floor((t.written / t.size) * 100)) : 0 } : null,
errors: Object.fromEntries(this.petErrors),
}
}
/** The mapping changed on this computer: tell the dial and send what it is missing. */
async petsChanged(): Promise<void> {
// A different mapping is a different question: whatever was refused before may be answered otherwise now.
this.petErrors.clear()
await this.syncPets()
}
private syncPets(): Promise<void> {
const next = this.petChain.then(() => this.runPetSync())
this.petChain = next.catch(() => {})
// A failed sync is this dial's log line, never a failed hello.
return next.catch((error: unknown) => this.log(`cable: pet sync failed: ${error instanceof Error ? error.message : String(error)}`))
}
private async runPetSync(): Promise<void> {
const store = this.host.pets?.()
if (!store || !this.petsSupported || !this.link?.isOpen || this.greetedMac === null) return
const plan = planPetSync(store.mapping(), [...this.petHeld])
const mapKey = JSON.stringify(plan.map)
if (mapKey !== this.petMapSent) {
this.petMapSent = mapKey
await this.send({ t: 'pet.map', all: plan.map.all, engines: plan.map.engines })
}
for (const id of plan.drop) {
this.petHeld.delete(id)
this.petDropSent = true
await this.send({ t: 'pet.drop', id })
}
// ONE transfer at a time, and never beside a firmware image: both stream into the same reader task on the dial.
// A firmware transfer ending (fw.error here, or the reboot after fw.done and its hello) runs this again.
if (this.petTransfer || this.transfer) return
for (const id of plan.send) {
if (this.petErrors.has(id)) continue
// The newest version both sides know: a dial that says pets:1 gets the version 1 pack of the very same id.
const pack = await store.pack(id, Math.min(this.petDialMax, PACK_VERSION)).catch((error: unknown) => {
this.log(`cable: pet ${id} unreadable: ${error instanceof Error ? error.message : String(error)}`)
this.petErrors.set(id, 'unreadable')
return null
})
if (!pack || pack.length < 22) continue
// Never a pack newer than the dial reads (or than we write): it would only be refused as 'version'.
if (pack[4] > Math.min(this.petDialMax, PACK_VERSION)) {
this.log(`cable: pet ${id} is pack version ${pack[4]}, the dial reads up to ${this.petDialMax}`)
continue
}
if (this.petTransfer || this.transfer || !this.link?.isOpen) return
this.log(`cable: offering pet ${id} (${pack.length} B)`)
this.petTransfer = {
id,
size: pack.length,
written: 0,
xfer: new FirmwareTransfer(
pack,
id,
async (slice) => {
if (!this.link?.isOpen) throw new Error('port closed mid-transfer')
await this.put(this.link, encodeCableFrame(CableType.Pet, slice))
},
(line) => this.log(line.replace('firmware', 'pet')),
),
}
// The CRC-32 is the pack's own header field (offset 18), so the dial checks what it received against it.
this.armPetStall()
await this.send({ t: 'pet.offer', id, size: pack.length, crc: pack.readUInt32LE(18) })
return
}
}
private clearPetStall(): void {
if (this.petStall) clearTimeout(this.petStall)
this.petStall = null
}
/** (Re)start the no-progress timer for the pack in flight; a stalled one would block firmware offers forever. */
private armPetStall(): void {
this.clearPetStall()
const t = this.petTransfer
if (!t) return
this.petStall = setTimeout(() => {
this.petStall = null
if (this.petTransfer !== t) return
this.log(`cable: pet ${t.id} stalled for ${PET_STALL_MS / 1000} s, giving up on this link`)
t.xfer.finish('timed out')
this.petErrors.set(t.id, 'timeout')
this.petTransfer = null
// The dial keeps the partial pack until told otherwise; this frees it.
void this.send({ t: 'pet.drop', id: t.id }).catch(() => undefined)
void this.syncPets()
}, PET_STALL_MS)
this.petStall.unref?.()
}
private onPcm(chunk: Buffer): void {
if (!this.voice) return // audio outside a turn is a dial that restarted mid-capture
this.voice.bytes += chunk.length
if (this.voice.bytes > VOICE_MAX_BYTES) {
this.log('cable: voice over the length cap, dropped')
this.cancelFormVoice()
this.cancelSearchVoice()
this.voice = null
return
}
this.voice.chunks.push(chunk)
}
private async finishVoice(review = false): Promise<void> {
const turn = this.voice
const generation = this.voiceGeneration
const uploadId = this.voiceUploadId
const current = () => generation === this.voiceGeneration
const reply = (message: Message) => {
// Every way a turn ends in an error is logged, with the words the dial shows: several ended silently (Diego, 2026-11-04).
if (message.t === 'voice.error' && current()) this.log(`cable: voice → error "${String(message.message)}"`)
return current() ? this.send({ ...message, ...(uploadId ? { uploadId } : {}) }) : Promise.resolve(false)
}
this.voice = null
if (turn?.draft && (!turn.draft.pin || !this.voiceDraft.current(turn.draft.pin))) {
await reply({ t: 'voice.error', message: 'That draft changed. Review it again.' }); return
}
if (turn?.question && (!turn.question.pin || !this.questionInbox.canSpeak(turn.question.pin) ||
!this.host.canSpeakQuestion?.(turn.question.pin.agentId))) {
await reply({ t: 'voice.error', message: 'This question changed. Open it again.' })
return
}
if (turn?.carry && !turn.carry.ok) {
await reply({ t: 'voice.error', message: turn.carry.error })
return
}
const searchPin = await turn?.search?.pin
if (!current()) return
if (turn?.search && (!searchPin?.ok || !turn.search.command)) {
this.cancelSearchVoice()
await reply({ t: 'voice.error', message: searchPin && !searchPin.ok ? searchPin.error : 'Choose the passage again.' }); return
}
const formPin = await turn?.form?.pin
if (!current()) return
if (formPin && (!formPin.ok || !formPin.active || !formPin.canQuery)) {
this.cancelFormVoice()
await reply({ t: 'voice.error', message: formPin.error || 'Open the field and try again.' })
return
}
const selection = await turn?.selection
if (turn?.selectionId && turn.agentId) void this.host.selectPassage?.({
op: 'cancel', agentId: turn.agentId, selectionId: turn.selectionId })
if (!current()) return
if (selection && (!selection.ok || !selection.text)) {
await reply({ t: 'voice.error', message: selection.ok ? 'Choose the text again.' : selection.error })
return
}
if (!turn || turn.bytes === 0) {
this.cancelFormVoice()
this.cancelSearchVoice()
await reply({ t: 'voice.error', message: "Didn't catch that" })
return
}
if (this.swarmReview && turn.swarmFace && !review) {
await reply({ t: 'voice.error', message: 'Review the words before they are posted.' }); return
}
const seconds = turn.bytes / (turn.rate * 2)
this.log(`cable: voice ${seconds.toFixed(1)}s (${Math.round(turn.bytes / 1024)} KB) → stt`)
let transcript: string
try {
transcript = (await this.host.transcribe(Buffer.concat(turn.chunks), turn.rate, turn.lang)).trim()
} catch (err) {
if (current()) { this.cancelFormVoice(); this.cancelSearchVoice() }
await reply({ t: 'voice.error', message: (err as Error).message })
return
}
if (!current()) return
if (!transcript) {
this.cancelFormVoice()
this.cancelSearchVoice()
await reply({ t: 'voice.error', message: "Didn't catch that" })
return
}
if (turn.search) {
// Speech service punctuation is not part of a remembered phrase. Preserve
// all internal punctuation (paths, identifiers, and code) literally.
const query = transcript.replace(/[.!?]$/, '').trim()
if (!query || Buffer.byteLength(query, 'utf8') > 120 || /[\x00-\x1f\x7f-\x9f]/.test(query)) {
this.cancelSearchVoice()
await reply({ t: 'voice.error', message: 'Say a short phrase to find.' }); return
}
const result = await this.host.selectPassage!({ ...turn.search.command!, op: 'search', query })
.catch(() => ({ ok: false, error: 'Search did not finish. Try again.' } as const))
if (!current()) return
if (!result.ok) { this.cancelSearchVoice(); await reply({ t: 'voice.error', message: result.error }); return }
this.voiceSearch = undefined
await reply({ t: 'voice.search', agentId: turn.search.command!.agentId, ...result }); return
}
if (turn.draft) {
const state = this.voiceDraft.edit(turn.draft.pin!, transcript)
if (!state.ok) { await reply({ t: 'voice.error', message: state.error }); return }
await reply({ t: 'voice.draft', ...state }); return
}
if (turn.question) {
const pin = turn.question.pin!
const draft = this.host.canSpeakQuestion?.(pin.agentId) ? this.questionInbox.draft(pin, transcript)
: { ok: false as const, error: 'Use the terminal to answer this question.' }
if (!draft.ok) { await reply({ t: 'voice.error', message: draft.error }); return }
await reply({ t: 'voice.question', agentId: pin.agentId, token: pin.token,
questionIndex: pin.index, draftId: draft.draftId, text: draft.text })
return
}
if (turn.form) {
const command = turn.form.command
if (!command || transcript.length > 240) {
this.cancelFormVoice()
await reply({ t: 'voice.error', message: 'Say a short harness or project name.' })
return
}
const result = await this.host.form!({ ...command, op: 'query', text: transcript })
.catch(() => ({ ok: false, active: false, error: 'Search did not finish. Try again.' }))
if (!current()) return
this.cancelFormVoice()
await reply({ t: 'voice.form', formId: command.formId, ...result })
return
}
// Named an agent: the dial was on a tile and there is nothing to decide.
let agentId = turn.agentId
let agentName = ''
const agents = await this.host.listAgents()
if (!current()) return
if (review && !agentId) {
await reply({ t: 'voice.error', message: 'Choose a recipient before drafting.' }); return
}
if (!agentId) {
// NOBODY NAMED, SO THE WINDOW DECIDES. It opens its palette with these words already in the field
// and runs the route a typed task would have run — the same fifteen candidates, the same trimmed
// recaps, the same threshold, and the same picker when the answer is not good enough to act on.
//
// The window DELIVERS what it picks, so there is nothing left to send here: a `sent` outcome is
// already on its way to an agent, and calling sendTurn on it would deliver the sentence twice.
const inWindow = this.host.routeInWindow
? await this.host.routeInWindow(transcript, turn.cmd)
: ({ t: 'unavailable' } as const)
if (!current()) return
if (inWindow.t === 'sent') {
this.log(`cable: the window routed the spoken task → ${inWindow.agentId.slice(0, 8)}`)
await reply({
t: 'voice.transcript',
routeId: '',
text: transcript,
agentId: inWindow.agentId,
// Only a name the DIAL's own list knows: it draws this, and an agent the window reached on a
// machine the carousel has not been told about yet has no tile here to put a name on. The ring
// that follows the window's focus brings both along a moment later.
agentName: agents.find((a) => a.id === inWindow.agentId)?.name ?? '',
needsConfirm: false,
})
return
}
if (inWindow.t === 'cancelled') {
// A person closed the palette. Nothing was sent and nothing should be — but the dial is still
// showing the sending overlay, so it has to be told, or it sits there until its own watchdog.
await reply({ t: 'voice.error', message: 'Cancelled in the window' })
return
}
if (inWindow.t === 'abandoned') {
// It took the words and went quiet. Routing here now would race a pick that may still be coming,
// and two turns from one sentence is worse than none — so say where the words went instead.
await reply({ t: 'voice.error', message: 'Still waiting on the window' })
return
}
try {
const decision = await this.host.route(transcript, agents)
if (!current()) return
agentId = decision.agentId
this.log(`cable: routed → ${agentId} (${decision.reason})`)
} catch (err) {
await reply({ t: 'voice.error', message: (err as Error).message })
return
}
}
agentName = agents.find((a) => a.id === agentId)?.name ?? ''
if (!agentId) {
await reply({ t: 'voice.error', message: 'No harness to send that to' })
return
}
const instruction = turn.cmd ? `/${turn.cmd} ${transcript}` : transcript
const carried = turn.carry?.ok ? turn.carry.passage : undefined
// An explicit target that vanished never becomes an inferred recipient.
if (carried && !agents.some(a => a.id === agentId)) {
await reply({ t: 'voice.error', message: 'That recipient is no longer available. Choose it again.' })
return
}
// Reviewed on a Swarm face: Send posts the words in the chat that was on the face, as the person, and never in a terminal.
if (review && turn.swarmFace && !carried && !selection?.ok) {
if (!this.host.swarmSay) { await reply({ t: 'voice.error', message: 'Could not reach the Swarm. Try again.' }); return }
const face = turn.swarmFace, say = this.host.swarmSay.bind(this.host), recipient = agentId
const state = this.voiceDraft.create({ agentId: recipient, name: `${face.project} · ${face.name}`, text: transcript,
context: 'Swarm chat',
submit: async words => {
const [chat] = this.sayArgs(face)
const said = await say(recipient, turn.cmd ? `/${turn.cmd} ${words}` : words, chat, face.id, true)
.catch((): SaidOnCard => ({ said: false }))
if (said.said) return { ok: true }
return { ok: false, error: said.refused?.message ?? (face.kind === 'buddy' ? 'Could not reach your Buddy. Try again.' : 'Could not reach the Swarm. Try again.') }
} })
if (!state.ok) { await reply({ t: 'voice.error', message: state.error }); return }
this.voiceDraftCreation = { uploadId, id: state.id }
await reply({ t: 'voice.draft', ...state }); return
}
// A Lead on another machine with no card here: no draft, whose Send would type into no harness and say it was sent
// (review of #2232).
if (review && turn.swarmRemote && !turn.swarmFace) { await reply({ t: 'voice.error', message: 'Could not reach the Swarm. Try again.' }); return }
if (review) {
const recipient = agentId
const state = this.voiceDraft.create({ agentId: recipient, name: agentName || 'Harness', text: transcript,
context: carried ? `With text from ${carried.sourceName}` : selection?.ok && selection.text ? 'With selected text' : '',
carryId: carried?.id,
submit: async words => {
const edited = turn.cmd ? `/${turn.cmd} ${words}` : words
const text = carried ? withCarriedPassage(edited, carried)
: selection?.ok && selection.text ? withSelectedPassage(edited, selection.text) : edited
const result = this.host.sendTurn(recipient, text)
if (result && !result.ok) return { ok: false, error: 'Could not reach that harness. Check its connection.' }
if (carried) this.passageCarry.clear(carried.id)
return { ok: true }
} })
if (!state.ok) { await reply({ t: 'voice.error', message: state.error }); return }
this.voiceDraftCreation = { uploadId, id: state.id }
await reply({ t: 'voice.draft', ...state }); return
}
// Spoken to a Swarm Lead (its card or its tile): the words go to the Swarm chat as the person's, where everyone in the
// tab sees them, not typed into the Lead's terminal. Any other harness, or a backend that could not be reached, gets the
// turn as before; a post the backend refused, and any word for the reader's Buddy, never does (spec 2026-10-29 Voice): a
// refused post for a read-only Chat with PM was typed into the PM's terminal.
if (turn.agentId && !carried && !selection?.ok && this.host.swarmSay) {
const face = turn.swarmFace
const said = await this.host.swarmSay(agentId, instruction, ...this.sayArgs(face)).catch((err: Error): SaidOnCard => {
this.log(`cable: voice → Swarm chat of ${agentId.slice(0, 8)} failed (${err?.message ?? err})`)
return { said: false }
})
if (!current()) return
if (said.said) {
this.log(`cable: voice → Swarm chat of ${agentId.slice(0, 8)}`)
await reply({ t: 'voice.transcript', routeId: '', text: transcript, agentId, agentName, needsConfirm: false })
return
}
if (said.refused) {
this.log(`cable: voice → Swarm chat of ${agentId.slice(0, 8)} refused (${said.refused.code})`)
await reply({ t: 'voice.error', message: said.refused.message })
return
}
// Words for the reader's Buddy chat (a swarmBuddy dial's Buddy face, an older dial's PM face), which the PM cannot read.
if (face?.kind === 'buddy') { await reply({ t: 'voice.error', message: 'Could not reach your Buddy. Try again.' }); return }
// A Lead on another machine has no terminal here to fall back to: its Swarm id names no harness.
if (face?.kind === 'pm' || turn.swarmRemote) { await reply({ t: 'voice.error', message: 'Could not reach the Swarm. Try again.' }); return }
}
const text = carried ? withCarriedPassage(instruction, carried)
: selection?.ok && selection.text ? withSelectedPassage(instruction, selection.text) : instruction
try {
const submitted = this.host.sendTurn(agentId, text)
if (submitted && !submitted.ok) {
await reply({ t: 'voice.error', message: carried
? 'Could not reach that harness. Your carried text is still here.'
: 'Could not reach that harness. Check its connection and try again.' })
return
}
} catch (_) {
await reply({ t: 'voice.error', message: 'Could not send. Check the terminal before trying again.' })
return
}
if (carried) {
this.passageCarry.clear(carried.id)
this.voiceCarryId = undefined
}
await reply({ t: 'voice.transcript', routeId: '', text: transcript, agentId, agentName, needsConfirm: false,
...(carried ? { carryId: carried.id } : {}) })
}
private cancelSearchVoice(): void {
const command = this.voiceSearch
this.voiceSearch = undefined
if (command) void this.host.selectPassage?.({ ...command, op: 'cancel' }).catch(() => {})
}
private cancelFormVoice(): void {
const command = this.voiceForm
this.voiceForm = undefined
if (command) void this.host.form?.({ ...command, op: 'query.cancel' }).catch(() => {})
}
// ── outbound ──────────────────────────────────────────────────────────────────────────────────────
/**
* Every status line this session emits. It exists so identity and settings ride on all of them: a
* window that learned the settings from the greeting and then received a bare `{attached:true}` from
* a firmware transfer would blank the pane in the middle of an update.
*/
private report(extra: Partial<DialStatus> = {}): void {
this.host.onDialStatus?.({
attached: true,
fw: this.greetedFw ?? undefined,
...(this.greetedHw ? { hw: this.greetedHw } : {}),
...(this.greetedBoard ? { board: this.greetedBoard } : {}),
...(this.greetedMac ? { mac: this.greetedMac } : {}),
...(this.greetedSettings ? { settings: this.greetedSettings } : {}),
...extra,
})
}
/**
* Ask the device to change the named settings. Absent fields are not sent, so two windows open on the
* same device cannot overwrite each other with the values each last saw.
*
* Resolves when the frame is on the wire, NOT when the device has agreed: the answer is a
* `settings.state`, which arrives as a status update like any other. A caller that waited here would
* be waiting on a device that may be asleep.
*/
private skinReported = false
async setSettings(patch: DeviceSettingsPatch): Promise<boolean> {
// `id` addresses the DEVICE; it is not one of its settings and must not be sent as one.
const fields = Object.entries(patch).filter(([key, value]) => value !== undefined && key !== 'id' && key !== 'companion' && key !== 'companionDetails' && key !== 'companionProtocol')
if (!fields.length) return true
if (patch.uiSkin !== undefined && !this.skinReported) {
this.log('cable: uiSkin not written — this device did not report one (older firmware)')
return false
}
const sent = await this.send({ t: 'settings.set', ...Object.fromEntries(fields) })
if (!sent) this.log('cable: settings change not written — the device is not on the wire')
return sent
}
private async send(msg: Message): Promise<boolean> {
if (!this.link?.isOpen) return false
// A message over the frame cap is this side's bug, never a dead port: it is dropped and said, and the link stays up.
// Closing over it took the whole dial down on every tap of a long model list (Diego, 2026-11-03).
let frame: Uint8Array
try {
const framed = this.seqOn ? { ...msg, seq: this.seq } : msg
frame = encodeCableFrame(CableType.Json, Buffer.from(JSON.stringify(framed), 'utf8'))
} catch (err) {
this.log(`cable: dropped a ${String(msg.t)} frame (${(err as Error).message})`)
return false
}
if (this.seqOn) this.seq++
try {
await this.put(this.link, frame)
return true
} catch (err) {
this.log(`cable: write failed (${(err as Error).message})`)
await this.link.close('write failed')
return false
}
}
/**
* Push the agent list, STREAMED — begin, one message per agent, end.
*
* 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.
*/
/** What the dial has been told, as one comparable string. */
private static agentsKey(agents: CableAgent[]): string {
// `machine` is in the key, not just `machineId`: the dial DRAWS the name, so a machine being renamed
// has to reach the screen even though not one agent has changed.
return agents.map((a) => `${a.id}:${a.name}:${a.engine ?? ''}:${a.model ?? ''}:${a.effort ?? ''}:${a.machineId ?? ''}:${a.machine ?? ''}`).join('|')
}
/**
* Send the agent list IF it differs from what the dial was last told.
*
* Called on attach and on every tick. The tick is not belt-and-braces: the list can be wrong through no
* fault of the dial — a daemon restarting answers `hello` before its registry has finished loading, and
* the honest answer at that instant is "no agents". Something has to say the true one a second later.
*/
async syncAgents(force = false): Promise<void> {
return this.queued(() => this.syncAgentsNow(force))
}
/** `{ full }` for a `recap: 'long-v1'` device and an answer with something to say; nothing otherwise. */
private fullField(fullText?: string): { full?: string } {
const full = this.longRecap && fullText ? deriveLongRecap(fullText) : null
return full ? { full } : {}
}
/** One page of the library for a `player: 'library-v1'` device, when it differs or ten seconds have passed. */
async syncPlayerLibrary(force = false): Promise<void> {
return this.queued(async () => {
if (!this.playerCapable || !this.host.playerLibrary) return
const offset = this.playerOffset, request = this.playerRequest
const sessions = (await this.host.playerLibrary()).map((row) => {
const live = this.liveTurns.get(row.id)
return live ? { ...row, status: live } : row
})
// The device has asked for another page while this one was being read; its reply is the one that counts.
if (request !== this.playerRequest) return
const page = playerPage(sessions, offset)
const machines = new Set(sessions.map((row) => row.machineId)).size
// The age advances on the device, so an unchanged page is refreshed at most every 10 s.
const key = JSON.stringify([page.offset, page.total, machines, sessions.slice(page.offset, page.offset + PLAYER_PAGE_SIZE)])
if (!force && key === this.playerLibraryKey && Date.now() - this.playerLibraryAt < 10_000) return
if (await this.send({ t: 'player.library', request, ...page, machines })) {
this.playerOffset = page.offset
this.playerLibraryKey = key
this.playerLibraryAt = Date.now()
}
})
}
private async syncAgentsNow(force: boolean): Promise<void> {
const snapshot = this.host.listAgentSnapshot ? await this.host.listAgentSnapshot() : {
agents: await this.host.listAgents(), tab: this.host.activeSwarm(), total: this.host.agentTotal(),
}
const { agents, tab, total } = snapshot
// WHETHER there is a window is in the key, not WHICH tab: an empty tab after the window shut sends the
// same zero rows and draws a different screen, so that flip has to push. The tab's id does not — the
// dial names the tab from the `swarms` frame — and keying on it made every tab switch push twice,
// once when `app_swarms` named the new tab over the old panes and again when `app_panes` arrived.
const key = `${tab ? 'window' : ''}|${CableSession.agentsKey(agents)}`
if (!force && key === this.lastAgentsKey) return
this.lastAgentsKey = key
// Every push, and only pushes. The dial showing a different number from the daemon is a question this
// line answers in one look: either the daemon never said it, or it said it and the dial disagreed.
this.log(`cable: agents → ${agents.length} of ${total}${force ? ' (requested)' : ''}`)
await this.send({ t: 'agents.begin' })
for (const a of agents) {
await this.send({
t: 'agent',
id: a.id,
name: a.name,
engine: a.engine ?? '',
model: a.model ?? '',
effort: a.effort ?? '',
// Where it lives. The id is what the dial sends back for every action, the name is what it draws
// under the agent's, and the id is also how a machine row finds its first agent.
machineId: a.machineId ?? '',
machine: a.machine ?? '',
})
}
// Every agent sent is walked. What travels beside them: `total`, the account-wide count the overview
// prints (the rows behind it stay here), and `tab`, the active tab's id — '' with no window, which is
// how the dial tells "the app is shut" from "this tab is empty" when both send zero agents.
await this.send({ t: 'agents.end', total, tab })
// The list just changed shape under the dial, so say again which agent both screens are on.
//
// This is the ONLY thing the daemon re-asserts, and it is the current record rather than a second
// memory of it — see desiredFocus. A re-anchor after a push is silent by design (the dial reports
// nothing it did not do itself), so without this a dial that landed on the wrong tile would sit there
// with nobody to notice.
//
// Only for an agent the list just sent. The record can name one on another tab — the window focused
// it there, then switched — and a focus the dial cannot land is a frame it holds for five seconds and
// a warning per push; the tab switch is what un-focused it, and the next click sets a new record.
if (this.desiredFocus && agents.some((a) => a.id === this.desiredFocus)) {
this.expectedAppFocusEcho = this.desiredFocus
this.expectedAppFocusEchoUntil = Date.now() + APP_FOCUS_SETTLE_MS
await this.focusAgent(this.desiredFocus)
}
// A tile that has just appeared has no history on the dial. The usual case is a remote machine: its
// agents reach the cache seconds after the greeting, long after the attach pushed everyone else's.
// Cheap to say on every change — [restored] makes it a no-op for every tile already carrying one.
this.restoreInBackground()
}
/**
* What each agent was last doing.
*
* A tile with a name and no recap has forgotten the work it belongs to, and that is what a dial shows
* every time it is replugged or the daemon restarts — the summaries were on disk the whole time, nobody
* had sent them.
*
* `restore: true` is the load-bearing part: history, not news. No beep, no notification, no busy state.
* Without it, plugging the cable in announces every turn that finished while it was unplugged.
*
* Sent on attach only. The list is re-sent whenever it changes; the history behind it does not, or every
* rename would replay a week of recaps.
*/
/**
* Agents whose history the dial has already been given.
*
* THE DIAL KEEPS WHAT IT IS TOLD. Re-sending a tile's recaps buys nothing and costs 55 frames down a
* cable that the `focus` somebody just clicked has to share — measured: a switch every second kept the
* link saturated, and the focus, written in 20 ms, reached the glass 1.7 s later.
*
* Cleared on attach, which is the one moment the dial genuinely has nothing: a replug, a reboot, an OTA.
*/
private readonly restored = new Set<string>()
/** A background restore already walking the list, so a second trigger joins it rather than racing it. */
private restoring = false
async pushRestores(): Promise<void> {
// READ FIRST, QUEUE SECOND, and the split is the whole point. A remote agent's history is a cloud
// round trip and there is one per agent; asking for them from INSIDE the push chain holds every frame
// behind them — including the `focus` the person who just clicked is waiting for. Measured on the
// desk: a click from a local agent to a remote one took 1.5 s, of which 0.7 s was this loop waiting
// on the first `agent_recent` while the dial sat on the old tile.
const rows: Array<{ id: string; past: Array<{ recap: string; text: string; fullText?: string }> }> = []
for (const a of await this.host.listAgents()) {
// Marked as it is ASKED FOR, not as it is sent: the answer is a cloud round trip, and a tick
// arriving mid-loop would otherwise start a second walk over the same agents.
if (this.restored.has(a.id)) continue
this.restored.add(a.id)
rows.push({ id: a.id, past: await this.host.recentSummaries(a.id) })
}
if (!rows.length) return
return this.queued(async () => {
for (const row of rows) {
// Oldest first, so the newest ends up on top of the tile's stack.
for (const s of [...row.past].reverse()) {
if (!s.recap && !s.text) continue
await this.send(this.withinCap({ t: 'summary', agentId: row.id, recap: s.recap, text: s.text, ...this.fullField(s.fullText), restore: true }))
}
}
})
}
/**
* The same history, off the critical path.
*
* A machine switch owes the person two things and they are not equally urgent: the tile they clicked,
* NOW, and what every tile was last doing, eventually. `restore: true` says the second one is history —
* no beep, no notification — so nothing about it is worth a second of staring at the old tile.
*/
private restoreInBackground(): void {
if (this.restoring) return
this.restoring = true
void this.pushRestores()
.catch((err) => this.log(`cable: restores failed (${(err as Error).message})`))
.finally(() => { this.restoring = false })
}
/** Attach: tell the dial everything, whether or not any of it looks unchanged from here. */
async pushAgents(): Promise<void> {
// A dial that has just greeted us has no history at all — it rebooted, or the cable was out. This is
// the one place that says so; everywhere else, [restored] is what keeps the link quiet.
this.restored.clear()
// Attach owns this walk. Held across the list push so the trigger inside it does not start the same
// one from the other end and leave the caller awaiting a restore that has nothing left to send.
this.restoring = true
try {
await this.syncMachines(true)
await this.syncSwarms(true)
await this.syncSwarmCards(true)
await this.syncAgents(true)
await this.syncPlayerLibrary(true)
} finally {
this.restoring = false
}
await this.pushRestores()
// …and the drawer, which is the one thing a dial that has just greeted us is KNOWN to have lost:
// its rows live in RAM. Last, because it names agents the pushes above put on the carousel.
await this.replaceNotifications(this.host.listUnread())
}
/**
* A Pro saw a hole in `seq` (or a frame that failed its CRC): resend what a lost frame could have carried. The attach
* push minus the history replay, plus the open questions — a replayed `summary` is heavy, and a second burst on a link
* that just dropped bytes is what the rate limit (once per 2 s, here and on the device) is there to avoid.
*/
private async resync(): Promise<void> {
const now = Date.now()
if (now - this.resyncAt < 2_000) return
this.resyncAt = now
await this.syncMachines(true)
await this.syncSwarms(true)
await this.syncSwarmCards(true)
await this.syncAgents(true)
await this.replaceNotifications(this.host.listUnread())
for (const { agentId, id, questions } of this.questionInbox.open()) {
if (this.liveTurns.get(agentId) === 'question') await this.send({ t: 'question', agentId, ...this.whoIs(agentId), id, questions })
}
await this.resendSuperTabAsks()
}
// ── swarm cards (a Pro that named `swarmCard: 'v1'`) ────────────────────────────────────────────────
/** What this session told the core: that a capable device is here (see wantCards). */
private cardsWanted = false
/** Each Swarm's `supertab` frame as the Pro was last sent it, and the ids list: only a difference is sent again. */
private readonly cardKeys = new Map<string, string>()
private cardIdsKey = ''
private cardsUnread: ReturnType<typeof setTimeout> | null = null
private cardTimer: ReturnType<typeof setTimeout> | null = null
/** The Lead whose recap the Pro has open: the only one a changed text is pushed for. */
private openLead: { tabId: string; leadId: string } | null = null
/** The Swarm project the Pro was last pointed at (or picked itself), so a repeat announce sends nothing. */
private focusedKey = ''
/** The last focus decision logged, so a burst of the same answer is one line. */
private focusLogged = ''
/** This cable session's name for the service, so one Pro closing its recap does not close another's. */
private readonly cardSession = `c${++nextCardSession}`
/** The project this Pro itself picked last and when: the desktop's announce of it is no news, and a stale one of another is held off. */
private picked: { key: string; at: number } | null = null
private lastRecapGet: { key: string; at: number; read: Promise<LeadRecap | null> } | null = null
/** `${lead} ${why}` of each recap that came back with nothing and was logged (recapMissed). */
private readonly recapsMissed = new Set<string>()
/** A swarmChat dial's alerts (`${tab}:${lead}`): the notice it was last given or shown as already there, and whether it
* was read on the desktop since. A notice is sent once, never on an attach or resync (it was there before), never for
* the chat the desktop has open (a thread reply: that thread); `notice.read` once when the desktop opens the chat (or the
* thread) of one that was sent. */
private readonly notices = new Map<string, { id: string; chatId: string; open: boolean }>()
/** Until this session has seen a list with Swarms in it: the first one is a replay too. A dial can attach before its
* process has the cards (the devices' process started again), and the core's replay of the last list then comes as an
* ordinary push, whose notices are old. */
private noticesReplay = true
/** The chat on this dial's face for the Lead that runs as `harnessId` here; none for a device without chats. */
private swarmFaceOf(harnessId: string): SwarmFace | undefined {
if (!this.swarmChat) return undefined
for (const card of this.host.swarmCards?.() ?? []) {
// A Lead on another machine is named by its Swarm id: its card has no harness here (Diego's dial, 2026-10-29).
const lead = card.leads.find((l) => l.local === harnessId || (!l.local && l.id === harnessId))
const face = lead && (this.swarmBuddy ? lead.sideChat ?? lead.chat : lead.chat)
if (lead) return face && { ...face, project: lead.project }
}
return undefined
}
/**
* The chat words spoken to this Lead are posted in: its face chat, for a dial that names where words go. Never for a Pro:
* it shows the face chat but no "Sending to", and its plain agent room shows no chat at all, so following the desktop's
* open chat would post the person's words in a group or PM chat they cannot see they are talking to (review of #2298). Its
* words go to the Lead conversation, as before it said swarmChat, unless its voice.begin says `face`: spoken on its Lead
* view, which shows the face chat and the PM | Buddy side (Swarm parity, part 3). Without it, a Buddy-side word would be
* posted in the shared Lead chat.
*/
private voiceFaceOf(harnessId: string, proFace: boolean): SwarmFace | undefined {
return this.seqOn && !proFace ? undefined : this.swarmFaceOf(harnessId)
}
/** Whether `harnessId` is a Swarm Lead's harness on this machine. */
private swarmLeadHere(harnessId: string): boolean {
return (this.host.swarmCards?.() ?? []).some((card) => card.leads.some((l) => l.local === harnessId))
}
/** The extra arguments of words spoken to a Swarm Lead: the dial's chat flag, and the chat they were spoken to. */
private sayArgs(face: SwarmFace | undefined): [chat?: CardChat, chatId?: string, reviewed?: boolean] {
// A chat flag with no id means "the chat open on the desktop" to the Swarm service: a Pro sends neither unless its words
// were for the face chat it showed (voiceFaceOf), and then names that chat.
if (this.seqOn && !face) return []
const [chat] = this.chatFlag()
if (chat === undefined) return []
return face ? [chat, face.id] : [chat]
}
/** The extra argument a swarmChat dial's requests carry ('buddy' for a swarmBuddy dial's); none for any other device, whose
* calls stay as they were. */
private chatFlag(): [] | [CardChat] { return this.swarmBuddy ? ['buddy'] : this.swarmChat ? [true] : [] }
/** Tell the core a capable device is here (or gone), once per change: it reads the Swarms only while one is. */
private wantCards(on: boolean): void {
if (on === this.cardsWanted) return
this.cardsWanted = on
this.host.swarmCardsWanted?.(on)
}
/** The link ended: forget what the Pro was told and had open, and stop asking the core for Swarms on its behalf. */
private dropCards(): void {
if (this.cardTimer) clearTimeout(this.cardTimer)
this.cardTimer = null
if (this.cardsUnread) clearTimeout(this.cardsUnread)
this.cardsUnread = null
this.cardKeys.clear()
this.cardIdsKey = ''
this.focusedKey = ''
this.focusLogged = ''
this.picked = null
this.lastRecapGet = null
this.notices.clear()
this.noticesReplay = true
if (this.openLead) this.host.swarmCardOpen?.(this.cardSession, this.openLead.tabId, null, ...this.chatFlag())
this.openLead = null
this.wantCards(false)
}
/**
* Push the Swarm cards IF they differ from what the Pro was last told: `supertabs` (ids, in order) when the set or order
* moved, then one `supertab` per Swarm that changed — the Pro refuses a frame over 512 JSON tokens, and 16 Swarms of 12
* Leads do not fit in one. A change is held 300 ms so a burst of backend reads and desk announcements is one push;
* `force` (attach, resync) sends everything at once.
*/
async syncSwarmCards(force = false): Promise<void> {
if (!this.swarmCard) return
if (force) {
if (this.cardTimer) clearTimeout(this.cardTimer)
this.cardTimer = null
return this.queued(() => this.pushSwarmCards(true))
}
if (this.cardTimer) return
this.cardTimer = setTimeout(() => {
this.cardTimer = null
this.queued(() => this.pushSwarmCards(false)).catch((err) => this.log(`cable: swarm cards failed (${(err as Error).message})`))
}, SWARM_CARDS_DEBOUNCE_MS)
this.cardTimer.unref?.()
}
private async pushSwarmCards(force: boolean): Promise<void> {
if (!this.swarmCard) return
if (force) { this.cardKeys.clear(); this.cardIdsKey = ''; this.focusedKey = '' }
// Nothing until the core has read them: an empty list on a daemon that had just started sent the dial off the Swarm on
// its face, onto TABS, 2 s before the real list came (Diego, 2026-10-29). Empty only ever means no Swarms, as it does for
// a host with no cards at all.
const read = this.host.swarmCards ? this.host.swarmCards() : []
if (!read) {
// Bounded: a daemon that came back signed out never reads them, and a dial that kept its link would show the old
// Swarms on. After CARDS_UNREAD_MS it is told there are none; the real list replaces that whenever it comes.
if (force && !this.cardsUnread) {
this.cardsUnread = setTimeout(() => {
this.cardsUnread = null
if (this.host.swarmCards?.() || this.cardIdsKey) return
this.cardIdsKey = '[]'
this.queued(async () => { await this.send({ t: 'supertabs', ids: [] }) }).catch((err) => this.log(`cable: swarm cards failed (${(err as Error).message})`))
}, CARDS_UNREAD_MS)
this.cardsUnread.unref?.()
}
return
}
if (this.cardsUnread) { clearTimeout(this.cardsUnread); this.cardsUnread = null }
const cards = read.slice(0, SWARM_CARDS_MAX)
const desk = this.host.listSwarms().swarms
const ids = JSON.stringify(cards.map((c) => c.id))
if (ids !== this.cardIdsKey) {
this.cardIdsKey = ids
await this.send({ t: 'supertabs', ids: cards.map((c) => c.id) })
}
for (const id of [...this.cardKeys.keys()]) if (!cards.some((c) => c.id === id)) this.cardKeys.delete(id)
for (const card of cards) {
// The desk tab of the same Swarm, when the window has one: empty when it is closed or never opened it.
const tab = desk.find((s) => s.superTabId === card.id)?.id ?? ''
// A swarmBuddy dial follows the Swarm's side as the daemon's (review of #2218); no other device hears one.
const frame = { t: 'supertab', id: card.id, tab, name: card.name, count: card.count, ...(card.personal ? { personal: true } : {}), ...(this.swarmBuddy ? { side: 'buddy' } : {}), // the Buddy face is the only one: firmware before task #3928 still reads this field
leads: card.leads.slice(0, SWARM_LEADS_MAX).map((l) => this.swarmBuddy ? buddyLead(l) : this.swarmChat ? chatLead(l, l.chat) : { id: l.id, projectId: l.projectId, project: l.project,
engine: l.engine, owner: l.owner, local: l.local, state: l.state, order: l.order, ...(l.since === undefined ? {} : { since: l.since }) }) }
// Every dial's guard drops a frame over 512 tokens whole, a round dial's too (task #2525).
const dropped = fitFrame(frame, this.seqOn ? SWARM_TOKENS_MAX : GUARD_TOKENS_MAX)
const key = JSON.stringify(frame)
if (this.cardKeys.get(card.id) === key) continue
this.cardKeys.set(card.id, key)
// Once per frame sent: those Leads show "No Buddy here yet" though they have one (spec 2026-10-30-harness-pro-swarm-parity,
// Scale), and the other Leads read their chat's main stream.
const cuts = [dropped.buddies && `${dropped.buddies} Buddy block(s)`].filter(Boolean)
if (cuts.length) this.log(`cable: supertab ${card.id.slice(0, 8)} too large — ${cuts.join(', ')} dropped`)
await this.send(frame)
}
if (this.swarmChat) await this.pushNotices(cards, force)
await this.pushSwarmFocus()
}
/**
* A swarmChat dial's alerts, after the Leads they name. `replay` (attach, resync): the notices there now were there before
* the dial came, so they are noted and not sent; one that arrives later is sent once. One for the chat the desktop has
* open is read there already: noted, not sent. A sent one whose chat the desktop then opens is read on the dial too.
*/
private async pushNotices(cards: SwarmCard[], force: boolean): Promise<void> {
const replay = force || this.noticesReplay
if (cards.length) this.noticesReplay = false
const open = this.host.activeSwarmProject?.()
const live = new Set<string>()
for (const card of cards) {
for (const lead of card.leads.slice(0, SWARM_LEADS_MAX)) {
// The Buddy's quiet notice is held apart (spec 2026-10-29 Alerts), and only a swarmBuddy dial hears it.
// A decision asked of the reader is heard by a swarmNeedsYou dial alone; any other keeps the tag it covers, else none.
const heard = lead.notice?.decision && !this.swarmNeedsYou ? lead.notice.tag : lead.notice
const notices: Array<[string, LeadNotice | undefined]> = [[`${card.id}:${lead.id}`, heard]]
if (this.swarmBuddy && !this.swarmNeedsYou) notices.push([`${card.id}:${lead.id}:buddy`, lead.buddyNotice])
for (const [key, notice] of notices) {
live.add(key)
await this.pushNotice(key, card.id, lead.id, notice, replay, open?.superTabId === card.id ? open : undefined)
}
}
}
for (const key of [...this.notices.keys()]) if (!live.has(key)) this.notices.delete(key)
}
/**
* The dial showed the Buddy side of a Swarm. The reader's one Swarm Buddy speaks on every card, so one word badged them
* all, and the dial clears only the Lead it shows (review of #2500): the others' badges for the same chat are read here,
* so seeing the Buddy once is reading it once. A chat only one Lead's notice names (an older Swarm's own) is left alone.
*/
private async readSharedBuddyNotices(tab: string): Promise<void> {
const leads = this.host.swarmCards?.()?.find((c) => c.id === tab)?.leads.slice(0, SWARM_LEADS_MAX) ?? []
for (const lead of leads) {
const notice = lead.buddyNotice
if (!notice || leads.filter((l) => l.buddyNotice?.chatId === notice.chatId).length < 2) continue
const held = this.notices.get(`${tab}:${lead.id}:buddy`)
if (!held?.open || held.id !== notice.id) continue
held.open = false
await this.send({ t: 'supertab.notice.read', tab, lead: lead.id, chatId: notice.chatId })
}
}
/** One alert of a Lead (held at `key`): sent once when it is new, unless replayed or read on the desktop (`open`, the
* conversation the window has open in that Swarm and the thread beside it); read on the dial once the desktop opens the
* chat of one it was sent. A thread reply is read only by opening that thread: the chat shows it collapsed under "1
* reply", and the PM's answer in a task thread used to ring nowhere while its chat was open (Diego, 2026-10-29). */
private async pushNotice(key: string, tab: string, lead: string, notice: LeadNotice | undefined, replay: boolean, open: { conversationId?: string; threadRoot?: string } | undefined): Promise<void> {
const held = this.notices.get(key)
if (!notice) { this.notices.delete(key); return }
const opened = open?.conversationId !== undefined && open.conversationId === notice.chatId && (notice.thread === undefined || open.threadRoot === notice.thread)
if (held?.id !== notice.id) {
// Replayed or read on the desktop: noted as not open on the dial, so nothing is sent for it now or later.
const sent = !replay && !opened
this.notices.set(key, { id: notice.id, chatId: notice.chatId, open: sent })
if (sent) await this.send(noticeFrame(tab, lead, notice))
return
}
if (held.open && opened) {
held.open = false
await this.send({ t: 'supertab.notice.read', tab, lead, chatId: held.chatId })
}
}
/**
* Point the Pro at the Lead of the project the window has open, once per change and never at its own pick. A Swarm tab
* with no project open (its Chat with PM, a DM) still takes the device into that Swarm: `lead: ''` lets it open on the
* Lead it last showed there, else its first. A device from before that ignores an empty Lead, as it always has.
*
* Every decision is logged, once per change. This used to log nothing, and "the dial stayed on an empty tab" could
* not be told apart from "no project", "no Lead" or "already sent" from the logs (Diego's dial, 2026-10-28).
*/
private async pushSwarmFocus(): Promise<void> {
const open = this.host.activeSwarmProject?.()
if (!open) { this.focusedKey = ''; this.logFocus('cable: swarm focus · not a Swarm tab'); return }
const key = `${open.superTabId}/${open.projectId}`
const named = open.projectId ? key : `${open.superTabId} (no project)`
if (key === this.focusedKey) { this.logFocus(`cable: swarm focus ${named} · already sent`); return }
// Only the Pro that picked has nothing to follow; every other Pro still goes where the window went.
if (open.fromDevice && this.picked?.key === key) { this.focusedKey = key; this.logFocus(`cable: swarm focus ${named} · the device's own pick`); return }
// The desktop's announce from before it heard the pick: not where the window is going.
if (!open.fromDevice && this.picked && this.picked.key !== key && Date.now() - this.picked.at < PICK_ECHO_MS) {
this.logFocus(`cable: swarm focus ${named} · held: the device just picked another`)
return
}
// Not in the list yet: asked again when it arrives.
const card = this.host.swarmCards?.()?.find((c) => c.id === open.superTabId)
if (!card) { this.logFocus(`cable: swarm focus ${named} · held: no such Swarm in the list`); return }
const lead = open.projectId ? card.leads.find((l) => l.projectId === open.projectId) : undefined
if (open.projectId && !lead) { this.logFocus(`cable: swarm focus ${named} · held: no Lead for that project`); return }
this.focusedKey = key
// A send is always logged: one again after the dial rebooted on an update read as "never sent" (Diego's dial, 2026-10-28).
this.focusLogged = ''
this.logFocus(`cable: swarm focus ${named} → ${lead ? lead.id : 'its Leads'}`)
await this.send({ t: 'supertab.focus', tab: open.superTabId, lead: lead?.id ?? '' })
}
private logFocus(line: string): void {
if (line === this.focusLogged) return
this.focusLogged = line
this.log(line)
}
/** A Lead's changed text, for the Pro that has that Lead's recap open. */
async swarmCardRecap(recap: LeadRecap): Promise<void> {
// A newer text than the read a repeat request would be answered from: that read is not handed out again.
if (this.lastRecapGet?.key === `${recap.tabId}/${recap.leadId}`) this.lastRecapGet = null
if (!this.swarmCard || this.openLead?.tabId !== recap.tabId || this.openLead.leadId !== recap.leadId) return
// The service pushes a Lead's recap and each dial's face chat's apart: each device takes only the kind it asked for.
if (this.swarmChat !== (recap.chatId !== undefined) || this.swarmBuddy !== (recap.buddy === true)) return
return this.queued(async () => { await this.send(recapFrame(recap)) })
}
/** The Pro's three requests about Swarm cards. Ids that are not ids are ignored, like any frame this daemon cannot use. */
private async onSuperTab(type: string, tab: string, lead: string): Promise<void> {
if (!this.swarmCard) return
// The recap closing names no Lead: it is the one request that may leave a field empty.
if (type === 'supertab.open' && lead === '') {
this.openLead = null
this.host.swarmCardOpen?.(this.cardSession, tab, null, ...this.chatFlag())
return
}
if (!CARD_ID.test(tab) || !CARD_ID.test(lead)) return
if (type === 'supertab.open') {
this.openLead = { tabId: tab, leadId: lead }
this.host.swarmCardOpen?.(this.cardSession, tab, lead, ...this.chatFlag())
// The Buddy face is on the dial: seeing it once reads the shared Buddy's word on every card.
if (this.swarmBuddy) this.queued(() => this.readSharedBuddyNotices(tab)).catch((err) => this.log(`cable: Buddy notices not cleared (${(err as Error).message})`))
return
}
if (type === 'supertab.select') {
const projectId = this.host.swarmCards?.()?.find((c) => c.id === tab)?.leads.find((l) => l.id === lead)?.projectId
if (!projectId) { this.log(`cable: ignored pick of unknown Lead ${lead}`); return }
// A swarmBuddy dial shows only Buddies: the next project's Buddy chat, where the reader has one there.
const card = this.host.swarmCards?.()?.find((c) => c.id === tab)
const onBuddy = this.swarmBuddy && !!card && this.buddyIn(card, projectId)
this.openSwarmChat(tab, projectId, onBuddy ? 'buddy' : undefined)
return
}
// A repeat for the same Lead inside a second is answered from the first read, not read again. Dropping it left a dial
// that had emptied its face on the resting pet until its own 5 s retry (Diego, 2026-10-29).
// Only while the Lead is still in the cards: one whose access went is read again, and the host refuses it.
const asked = `${tab}/${lead}`, now = Date.now()
const listed = this.host.swarmCards?.()?.find((c) => c.id === tab)?.leads.some((l) => l.id === lead) ?? false
if (this.lastRecapGet?.key !== asked || now - this.lastRecapGet.at >= RECAP_REPEAT_MS || !listed) {
const read = Promise.resolve()
.then(() => this.host.swarmCardRecap?.(tab, lead, ...this.chatFlag()) ?? null)
.then((recap) => { this.recapMissed(lead, recap ? null : 'came back empty'); return recap },
(err) => { this.recapMissed(lead, `failed (${(err as Error).message})`); return null })
this.lastRecapGet = { key: asked, at: now, read }
}
const recap = await this.lastRecapGet.read
// Nothing on a failure: the Pro keeps its "…" and asks again on the next open.
if (recap) await this.queued(async () => { await this.send(recapFrame(recap)) })
}
/** A recap the dial asked for that came back with nothing leaves its face on the resting pet: said once per Lead and why,
* and again after one came back (`why` null). */
private recapMissed(lead: string, why: string | null): void {
if (why === null) { for (const key of [...this.recapsMissed]) if (key.startsWith(`${lead} `)) this.recapsMissed.delete(key); return }
if (this.recapsMissed.has(`${lead} ${why}`)) return
this.recapsMissed.add(`${lead} ${why}`)
this.log(`cable: recap for ${lead} ${why}`)
}
/** Open a project's chat in its Swarm tab for this dial. Remembered before the window answers, so its announce of this very
* project is not sent back as a focus. */
private openSwarmChat(tab: string, projectId: string, chat: CardSide | undefined): void {
this.focusedKey = `${tab}/${projectId}`
this.picked = { key: this.focusedKey, at: Date.now() }
if (chat) this.host.superTabSelected?.(tab, projectId, chat)
else this.host.superTabSelected?.(tab, projectId)
}
/** The reader's Buddy in a project of a card, when Buddies are on and they have one there. */
private buddyIn(card: SwarmCard, projectId: string): boolean {
const lead = card.leads.find((l) => l.projectId === projectId)
return lead?.buddies === true && lead.buddy !== undefined
}
/**
* The Swarm session a round dial's tap names: the reader's Buddy ('buddy') or a Lead ('pm') whose session runs on this
* computer, by the session id the cards hold for it. Any round dial, older ones too (PM ruling, 10-30): the tap is a
* notification's, not a Buddy screen's. The Pro keeps its tile: it picks Leads on its own cards, has no Buddy screen,
* and Diego's proposal and the ruling are the round dial's. An id the cards hold twice is no one session's, and opens a
* tile as before; so does every other agent.
*/
private swarmSessionOf(agentId: string): { tab: string; projectId: string; chat: CardSide } | null {
if (this.greetedBoard === 'pro') return null
const found: Array<{ tab: string; projectId: string; chat: CardSide }> = []
for (const card of this.host.swarmCards?.() ?? []) {
for (const lead of card.leads) {
if (lead.local === agentId) found.push({ tab: card.id, projectId: lead.projectId, chat: 'pm' })
if (lead.buddies && lead.buddy?.local === agentId) found.push({ tab: card.id, projectId: lead.projectId, chat: 'buddy' })
}
}
if (found.length === 1) return found[0]
// The reader's one Swarm Buddy is every project's Buddy, so its session is on each card of its Swarm: a tap on it opens
// the chat in the project the dial is on, else the first. Two sessions of different Swarms, or a Lead beside it, stay
// ambiguous, as before.
const [first] = found
if (first?.chat === 'buddy' && found.every((f) => f.chat === 'buddy' && f.tab === first.tab)) {
return found.find((f) => `${f.tab}/${f.projectId}` === this.focusedKey) ?? first
}
return null
}
// ── swarms ────────────────────────────────────────────────────────────────────────────────────────
private lastSwarmsKey = ''
/** Push the window's swarms IF they differ from what the dial was last told. Same rule as the wheel:
* the diff is what keeps the link idle while nothing changes. */
async syncSwarms(force = false): Promise<void> {
return this.queued(() => this.syncSwarmsNow(force))
}
private async syncSwarmsNow(force: boolean): Promise<void> {
const { selected, swarms, tiles } = this.host.listSwarms()
const meta = await this.memberMeta(swarms)
// `panes` belongs in the key as much as `agents` does. Opening a terminal on a tab that holds no
// agent moves only the tile count, and a key blind to it would swallow that push and leave the
// dial showing a tab it still believes is empty — the very row this field exists to keep.
// The active tab's SHAPE belongs in the key too, and it is the only part of this that can change
// with no row changing at all: re-arranging four panes moves every tile and leaves the counts
// exactly where they were, which a key blind to it would swallow — leaving the device drawing the
// shape the tab used to have.
const shape = tiles.map((t) => `${t.x1},${t.y1},${t.x2},${t.y2},${t.agentId}`).join(';')
// A device that asked for members is also told when WHO sits in a tab changes (a reorder moves no count),
// and when a member's machine goes offline. One that did not keeps the key it always had.
const members = this.swarmMembers
? `|${swarms.map((s) => (s.agentIds ?? []).join(',')).join(';')}|${[...meta].map(([id, m]) => `${id}=${m.name}/${m.engine}/${m.machine}/${m.online ? 1 : 0}`).join(',')}`
: ''
const key = `${selected}|${swarms.map((s) => `${s.id}:${s.name}:${s.agents}:${s.panes}`).join('|')}|${shape}${members}`
if (!force && key === this.lastSwarmsKey) return
this.lastSwarmsKey = key
this.log(`cable: swarms → ${swarms.length}${selected ? ` (on ${selected})` : ''}${force ? ' [push]' : ''}`)
// ONE frame, not a begin/row/end stream: two dozen rows of an id, a name and a count fit in a
// kilobyte, and the dial replaces the whole list on arrival either way.
await this.send(this.swarmsMessage(selected, swarms, tiles, key, meta))
}
/**
* What the daemon knows about every member of every tab: name, engine, machine and whether that machine
* is online. A tab can hold an agent of a machine that is offline: it is in the window's `agentIds` but in
* nobody's roster, so the device had only an id to draw. Empty for a device that did not ask for members,
* and an id the daemon has never heard of simply has no entry.
*/
private async memberMeta(swarms: CableSwarm[]): Promise<Map<string, SwarmMemberMeta>> {
const out = new Map<string, SwarmMemberMeta>()
if (!this.swarmMembers) return out
let machines: CableMachine[] = []
try { machines = (await this.host.listMachines()).machines } catch { /* unknown liveness reads as online */ }
for (const sw of swarms) {
for (const id of sw.agentIds ?? []) {
if (out.has(id)) continue
const who = this.host.describe(id)
if (!who || (!who.name && !who.machine)) continue
const m = who.machine ? machines.find((x) => x.name === who.machine) : undefined
out.set(id, { id, name: who.name, engine: who.engine, machine: who.machine, online: !m || m.state !== 'offline' })
}
}
return out
}
/**
* Build the swarms frame, member ids only for a device that asked for them and only as many as fit.
* `encodeCableFrame` throws over 8192 bytes, `send` treats that as a dead link and closes it, and the
* reconnect would send the same frame again: one oversized frame is a loop.
*/
private swarmsMessage(selected: string, swarms: CableSwarm[], tiles: CableTile[], key: string,
meta: Map<string, SwarmMemberMeta>): Message {
// Flat quads plus an id, rather than objects: this is read by a C parser on a device, and four
// numbers in a row cost it nothing to walk.
const flatTiles = tiles.map((t) => ({ x1: t.x1, y1: t.y1, x2: t.x2, y2: t.y2, a: t.agentId }))
const build = (list: CableSwarm[], withIds: (s: CableSwarm) => boolean, withMeta = false, withTiles = true): Message => ({
t: 'swarms', selected,
items: list.map((s) => {
const ids = (s.agentIds ?? []).slice(0, SWARM_IDS_MAX)
const members = withMeta && withIds(s) ? ids.flatMap((id) => meta.get(id) ?? []) : []
return {
id: s.id, name: s.name, agents: s.agents, ...(withIds(s) ? { agentIds: ids } : {}),
...(members.length ? { members } : {}), panes: s.panes,
}
}),
tiles: withTiles ? flatTiles : [],
})
if (!this.swarmMembers) return build(swarms, () => false)
// Both of the device's limits (fitsFrame): a frame over the JSON guard is refused WHOLE, leaving the Tabs screen empty.
const selectedRow = swarms.find((s) => s.id === selected)
const capped = swarms.length <= SWARMS_MAX ? swarms
: swarms.slice(0, SWARMS_MAX).some((s) => s === selectedRow) || !selectedRow ? swarms.slice(0, SWARMS_MAX)
: [...swarms.slice(0, SWARMS_MAX - 1), selectedRow]
// Fewer tabs only once nothing smaller per tab fits. Names go first: ids are what the device lists,
// names only cover the ones it cannot find elsewhere.
for (let n = capped.length; n >= 1; n--) {
const others = capped.filter((s) => s !== selectedRow).slice(0, selectedRow ? n - 1 : n)
const list = capped.filter((s) => s === selectedRow || others.includes(s))
const attempts = [build(list, () => true, true), build(list, () => true), build(list, (s) => s.id === selected), build(list, () => false)]
const at = attempts.findIndex(fitsFrame)
if (at < 0) continue
if (at > 0 || n < capped.length) this.noteTrimmed(key, `${at === 1 ? 'member names' : at === 2 ? 'ids of the other tabs' : at === 3 ? 'member ids' : ''} dropped${n < capped.length ? `, ${capped.length - n} tab(s) left out` : ''}`)
return attempts[at]
}
this.noteTrimmed(key, 'tiles dropped, selected tab only')
return build(selectedRow ? [selectedRow] : capped.slice(0, 1), () => false, false, false)
}
private noteTrimmed(key: string, what: string): void {
if (this.swarmsTrimmedKey === key) return
this.swarmsTrimmedKey = key
this.log(`cable: swarms too large for one frame — ${what}`)
}
// ── machines ──────────────────────────────────────────────────────────────────────────────────────
/** What the dial has been told about the wheel, as one comparable string. Order counts: it is render
* order, so two lists that differ only by a swap are a real change. */
private static machinesKey(machines: CableMachine[], source: string, selected: string): string {
return `${source}|${selected}|${machines
.map((m) => `${m.id}:${m.name}:${m.state}:${m.local ? 1 : 0}`)
.join('|')}`
}
/**
* Push the machine wheel IF it differs from what the dial was last told.
*
* The diff is not an optimisation. `ui_local_machine_set` on the dial once rebuilt its wheel on every
* arriving greeting, on the USB reader task, and that measured out at 31 session restarts an hour with
* the agent list wiped each time — the screen sat on "0 agents" while the daemon believed it had said
* otherwise. The dial hashes the rows again on its side; this is the half that stops the bytes leaving.
*/
async syncMachines(force = false): Promise<void> {
return this.queued(() => this.syncMachinesNow(force))
}
private async syncMachinesNow(force: boolean): Promise<void> {
const { machines, source } = await this.host.listMachines()
const selected = this.host.selectedMachine()
const key = CableSession.machinesKey(machines, source, selected)
if (!force && key === this.lastMachinesKey) return
this.lastMachinesKey = key
this.log(`cable: machines → ${machines.length} (${source})${force ? ' [push]' : ''}`)
await this.send({ t: 'machines.begin' })
for (const m of machines) {
await this.send({ t: 'machine', id: m.id, name: m.name, state: m.state, local: m.local })
}
await this.send({ t: 'machines.end', selected, source })
}
/**
* Switch the dial to another machine.
*
* Always answered, including for the machine already selected: silence strands the dial on a spinner
* until its own deadline, which reads as a hang rather than as "done, nothing changed" — the same rule
* `models.list` follows.
*/
private async selectMachine(machineId: string, isCurrent = () => true): Promise<void> {
if (!machineId) return
// Not while a pick is on its way elsewhere: this one replaces it, so the host has to hear of it. Answered here alone,
// the slow pick landed afterwards and moved the check mark to a machine the person had left (Diego's Buddy, 11-02).
if (machineId === this.host.selectedMachine() && !this.host.pendingPick?.()) {
await this.send({ t: 'machine.selected', machineId })
await this.syncAgents()
this.restoreInBackground()
return
}
const result = await this.host.selectMachine(machineId)
// An app selection may have moved again, or its cable closed, during the remote attachment.
// The next queued selection corrects the host; never publish this obsolete acknowledgement.
if (!isCurrent()) return
if (!result.ok) {
this.log(`cable: machine.select ${machineId} refused (${result.code})`)
await this.send({ t: 'machine.error', machineId, code: result.code, message: result.message })
return
}
this.log(`cable: machine.select → ${machineId}`)
await this.send({ t: 'machine.selected', machineId })
// NOT FORCED, and that is the fix for a switch that felt slow at random.
//
// Forcing both was right when the carousel showed ONE machine at a time: selecting another machine
// replaced every tile, so the list and its history had to be re-streamed. The carousel now spans every
// machine — `listAgentsFlat` reads the same 22 agents whichever row wears the ✓ — so a forced push
// re-sends a list and a history the dial already has, 55 frames of it, and the `focus` the person is
// waiting on queues behind them on the wire. Measured: 20 ms to write the focus, 1.7 s to land it.
//
// The diff still sends anything that GENUINELY changed, including a machine whose agents have only
// just arrived in the cache — and [restored] means those, and only those, bring their history along.
await this.syncAgents()
await this.syncMachines() // the ✓ moved: `machinesKey` carries the selection, so this pushes
this.restoreInBackground()
}
/** One row changed — liveness, a rename, a count. Cheaper than re-streaming the wheel. */
async machineState(machine: CableMachine): Promise<void> {
await this.send({ t: 'machine.updated', id: machine.id, name: machine.name, state: machine.state, local: machine.local })
}
// Turn state is UNSOLICITED: the daemon reports every turn in every agent, including ones started at the
// keyboard. A dial that only saw answers to its own sends would sit idle through most of what the
// machine actually does.
/**
* `text` is the status line the tile draws — "Working…", the tool that is running, what it is waiting on.
* It travels because without it the dial gets a card with a state and nothing to render: the tile knows
* a turn is live and shows the user nothing that says so.
*/
async turnStarted(agentId: string, text = '', update?: string): Promise<void> {
this.activityEndedAt.delete(agentId)
this.markLive(agentId)
const read = {}
this.activityReads.set(agentId, read)
await this.send({ t: 'turn.started', agentId, text })
// The paragraph the agent last wrote, so the working screen has a sentence before the footer is read.
if (this.stepsActivity && update) await this.send({ t: 'turn.activity', agentId, text, action: clipUtf8(update, ACTION_MAX_BYTES) })
if (!this.link?.isOpen || !this.canReadActivity()) { this.activityReads.delete(agentId); return }
let activity: ActivitySnapshot | null = null
try { activity = await this.readActivity(agentId) } catch { /* unavailable is not a status */ }
// A terminal capture must never revive a completed turn or overwrite a newer heartbeat.
if (this.activityReads.get(agentId) !== read) return
this.activityReads.delete(agentId)
await this.sendActivity(agentId, activity)
}
/** Whether there is any footer to read for this device: a round dial reads `activityText`, as it always did. */
private canReadActivity(): boolean {
return !!this.host.activityText || (this.stepsActivity && !!this.host.activitySnapshot)
}
private async readActivity(agentId: string): Promise<ActivitySnapshot | null> {
// The snapshot is a newer door than the footer; only the device that asks for its extras depends on it,
// and if it fails (an older core) that device still gets the footer.
if (this.stepsActivity && this.host.activitySnapshot) {
try { return await this.host.activitySnapshot(agentId) } catch { if (!this.host.activityText) throw new Error('no activity') }
}
const text = await this.host.activityText?.(agentId)
return text ? { text } : null
}
/** The footer, and for a `steps-v1` device the agent's own sentence and the footer's timer beside it. */
private async sendActivity(agentId: string, activity: ActivitySnapshot | null): Promise<void> {
const steps = this.stepsActivity
const seconds = activity?.elapsedSeconds
await this.send({ t: 'turn.activity', agentId, text: activity?.text ?? '',
...(steps && activity?.action ? { action: clipUtf8(activity.action, ACTION_MAX_BYTES) } : {}),
...(steps && Number.isSafeInteger(seconds) && seconds! >= 0 && seconds! <= 2_592_000 ? { elapsedSeconds: seconds } : {}) })
}
private readonly activityReads = new Map<string, object>()
/**
* The turns this daemon has seen start and not end, and the questions still open: the library's status for a
* `player: 'library-v1'` device. The host's rows carry no status of their own (`idle` for every one), and a page
* that said `idle` every ten seconds put a working agent to rest on the device until its next event.
*/
private readonly liveTurns = new Map<string, 'working' | 'question'>()
private markLive(agentId: string): void {
this.turnOpen.add(agentId)
if (this.turnOpen.size > 256) this.turnOpen.delete(this.turnOpen.values().next().value!)
if (this.liveTurns.get(agentId) === 'question') return
if (!this.liveTurns.has(agentId) && this.liveTurns.size >= 256) this.liveTurns.delete(this.liveTurns.keys().next().value!)
this.liveTurns.set(agentId, 'working')
}
private readonly activityEndedAt = new Map<string, number>()
private readonly activityLabels = new Map<string, string>()
private activityRefreshAt = 0
private activityRefreshAgent = ''
private activityRefreshPending = false
/** A turn may predate this bridge, or continue through a transcript compaction. */
private async refreshFocusedActivity(): Promise<void> {
const agentId = this.desiredFocus
const link = this.link
const now = Date.now()
if (this.stopped || !this.isConnected || !agentId || !this.canReadActivity()
|| this.activityRefreshPending || this.activityReads.has(agentId)
|| now - (this.activityEndedAt.get(agentId) ?? -Infinity) < 3_000
|| (this.activityRefreshAgent === agentId && now - this.activityRefreshAt < 3_000)) return
this.activityRefreshAt = now
this.activityRefreshAgent = agentId
this.activityRefreshPending = true
const read = {}
this.activityReads.set(agentId, read)
const current = () => !this.stopped && this.isConnected && this.link === link
&& this.desiredFocus === agentId && this.activityReads.get(agentId) === read
try {
const activity = await this.readActivity(agentId)
if (!current()) return
// A visible engine footer is direct evidence of work. Recover liveness even
// when the transcript's turn.started happened before we attached.
if (activity) this.markLive(agentId)
if (activity) await this.send({ t: 'turn.started', agentId, text: activity.text })
if (!current()) return
await this.sendActivity(agentId, activity)
if (this.activityLabels.get(agentId) !== (activity?.text ?? '')) {
this.activityLabels.set(agentId, activity?.text ?? '')
this.log(`cable: terminal activity ${agentId}: ${activity?.text || '(no live footer)'}`)
}
} catch { /* A capture failure says nothing about whether the turn ended. */ }
finally {
if (this.activityReads.get(agentId) === read) this.activityReads.delete(agentId)
this.activityRefreshPending = false
}
}
/** The tool the turn just started, as one line for a `steps-v1` device's working screen. Nobody else is told. */
async turnStep(agentId: string, step: string): Promise<void> {
this.markLive(agentId)
if (!this.stepsActivity) return
await this.send({ t: 'turn.activity', agentId, text: '', step })
}
/** The agent's reply as it streams: its latest paragraph as `action`, for a `steps-v1` device's working screen. Nobody else is told. */
async turnReply(agentId: string, action: string): Promise<void> {
if (!this.stepsActivity || !action) return
await this.send({ t: 'turn.activity', agentId, text: '', action: clipUtf8(action, ACTION_MAX_BYTES) })
}
/** A connected device that wants `turn.stats`: the token reads are only worth doing for one. */
get wantsStats(): boolean { return this.statsTurn && this.isConnected }
/** The turn's test and commit counts, for a `stats: 'turn-v1'` device; nothing when none were seen. */
async turnStats(agentId: string, stats: TurnStatsFields): Promise<void> {
if (!this.statsTurn || !Object.keys(stats).length) return
await this.send({ t: 'turn.stats', agentId, ...stats })
}
async turnDone(agentId: string): Promise<void> {
this.endLive(agentId)
this.activityReads.delete(agentId)
this.activityEndedAt.set(agentId, Date.now())
await this.send({ t: 'turn.done', agentId })
}
/**
* A finished turn's recap.
*
* `tier` is how loudly to tell (lib/notifyTier.ts): `alert` beeps and wakes; `list` is a drawer entry only (`quiet`);
* `silent` draws the tile only (`silent`). `quiet`/`silent` ride along as well as
* `tier`, so firmware that predates `tier` still behaves. `subagent`: a sub-agent's end is not its main agent's.
*/
async summary(agentId: string, recap: string, text: string, tier: Tier = 'alert', fullText?: string, subagent = false): Promise<void> {
if (!subagent) this.endLive(agentId) // a sub-agent's end is not its main agent's
this.activityReads.delete(agentId)
this.activityEndedAt.set(agentId, Date.now())
recap = extendShortRecap(recap, text)
const who = this.whoIs(agentId)
// The card carries the answer; the host is asked only when it did not, and not for long.
const full = this.fullField(this.longRecap ? fullText ?? await this.storedFullText(agentId, text) : undefined)
await this.send(this.withinCap({ t: 'summary', agentId, ...who, recap, text, ...full, tier, ...(tier === 'list' ? { quiet: true } : {}), ...(tier === 'silent' ? { silent: true } : {}) }))
}
/**
* A frame over the cap makes `encodeCableFrame` throw, `send` closes the link, and the reconnect sends the
* same frame again. `full` is the one optional part of a summary, so it is what goes.
*/
private withinCap(msg: Message): Message {
if (!('full' in msg) || Buffer.byteLength(JSON.stringify(msg), 'utf8') <= CABLE_MAX_PAYLOAD - 256) return msg
const { full: _full, ...rest } = msg as Message & { full?: string }
return rest
}
/** The whole answer behind a card, from the host's newest stored turn, if that turn IS this card's. */
private async storedFullText(agentId: string, text: string): Promise<string | undefined> {
let timer: ReturnType<typeof setTimeout> | undefined
try {
const wait = new Promise<undefined>((resolve) => { timer = setTimeout(() => resolve(undefined), 750) })
const newest = (await Promise.race([this.host.recentSummaries(agentId), wait]))?.[0]
return newest && newest.text === text ? newest.fullText : undefined
} catch { return undefined } finally { clearTimeout(timer) }
}
/**
* The name, engine and machine that ride on every `summary` and `question`.
*
* The dial holds ONE TAB's agents, and a turn can finish on any of them — the drawer row and the
* question card for an agent off this tab have nobody to ask but the frame. Sent on every card rather
* than only the off-tab ones: the dial then has one path, and a tab switch mid-flight cannot strand a
* card with an id and no name.
*/
private whoIs(agentId: string): { name: string; engine: string; machine: string } {
return this.host.describe(agentId) ?? { name: '', engine: '', machine: '' }
}
/**
* Replace the dial's whole drawer with what the window still has unread.
*
* Sent once per attach, because that is the one moment the dial is known to have nothing: its rows
* live in RAM and an OTA, a replug or a flash takes them. Measured on a flash: a turn ended at
* 17:46:19, the dial came back at 17:46:26, a question arrived at 17:46:28 — and the pill read 1
* against the window's 2 from then on, with nothing to bring them back together.
*
* The window sends ids and kinds; the name, machine and recap are filled in HERE, from what this
* daemon already knows, so those never have a second source that can disagree.
*/
async replaceNotifications(
items: UnreadNotification[],
): Promise<void> {
const replay = { seen: new Set<string>() }
this.notificationReplay = replay
const link = this.link
const rows = await Promise.all(items.slice(0, 8).map(async (item) => {
const who = this.whoIs(item.agentId)
// A QUESTION BRINGS ITS OWN WORDS; a finished turn takes the recap this daemon summarised. The
// dial cannot supply either after a reboot, and a row with neither renders as the word its type
// used to assume — "done", on a question nobody has answered.
let summary = item.text
if (!item.question && summary.trim().length < 20) {
try {
const saved = (await this.host.recentSummaries(item.agentId))[0]
summary = summary ? extendShortRecap(summary, saved?.text ?? '') : saved?.recap ?? ''
} catch { /* keep the supplied text if history cannot be read */ }
}
return { agentId: item.agentId, name: who.name, machine: who.machine, summary, question: item.question,
...(notificationReadToken(item.readToken) ? { readToken: item.readToken } : {}) }
}))
if (this.notificationReplay !== replay) return
this.notificationReplay = undefined
if (this.link !== link || this.stopped) return
// Reading clears the notice, not the underlying question. Versioned clears
// cannot eat a newer turn whose history happened to take longer to load.
await this.send({ t: 'notif.replace', items: rows.filter(row =>
(row.question || !replay.seen.has(row.agentId)) && !replay.seen.has(`${row.agentId}\0${row.readToken}`)) })
}
/**
* A harness the window has now looked at — drop its drawer row on the dial.
*
* The dial's own gesture is a tap, which already reaches the window as
* `agent.open`. This is the other direction, and without it the two counts
* separate the moment somebody switches to the tab a notification was about.
*
* Fire and forget, like every other card: a dial that predates the message
* counts it as unknown and drops it, which is the behaviour it has today.
*/
async agentSeen(agentId: string, readToken?: string): Promise<void> {
if (!agentId) return
if (readToken !== undefined && !notificationReadToken(readToken)) return
this.notificationReplay?.seen.add(readToken ? `${agentId}\0${readToken}` : agentId)
await this.send({ t: 'notif.seen', agentId, ...(readToken ? { readToken } : {}) })
}
async turnError(agentId: string, message: string): Promise<void> {
this.endLive(agentId)
this.activityReads.delete(agentId)
this.activityEndedAt.set(agentId, Date.now())
await this.send({ t: 'turn.error', agentId, message })
}
/**
* An agent stopped to ask.
*
* NO `quiet` HERE, and the reason is that a question is a job rather than news. A summary's `quiet`
* asks "is somebody looking at this right now" and that is the whole of what a finished turn needed.
* A question outlives the glance: it is answered or it is not, and until it is answered it is still
* owed (owner, 2026-09-24).
*
* Asking it anyway was self-defeating besides. Showing a question asks the window to bring that agent
* forward, so by the time anyone could answer "is it on screen" the answer was yes — every question
* came through quiet, no row was ever recorded, and looking away later left nothing behind.
*/
async question(agentId: string, id: string, questions: unknown, superTab?: SuperTabAsk): Promise<void> {
if (superTab && !this.superTabWaits) return
this.questionInbox.set(agentId, id, questions)
this.liveTurns.set(agentId, 'question')
// The inbox keeps only questions a device can answer, so a Super Tab wait is kept here for a resync.
if (superTab) this.superTabAsks.set(agentId, { id, questions, superTab })
else this.superTabAsks.delete(agentId)
await this.send({ t: 'question', agentId, ...this.whoIs(agentId), id, questions, ...(superTab ? { superTab: superTab.superTab, attention: superTab.attention } : {}) })
}
/** Asks a Pro again for every Super Tab wait still open (a resync, a relink). */
private async resendSuperTabAsks(): Promise<void> {
if (!this.superTabWaits) return
for (const [agentId, { id, questions, superTab }] of this.superTabAsks) {
await this.send({ t: 'question', agentId, ...this.whoIs(agentId), id, questions, ...superTab })
}
}
/** The agents whose turn this session saw start and not end, whatever their question says. */
private readonly turnOpen = new Set<string>()
/** The Super Tab waits the device was last shown, by agent (`question`), for `resync`. */
private readonly superTabAsks = new Map<string, { id: string; questions: unknown; superTab: SuperTabAsk }>()
/**
* A turn ended. A Super Tab wait outlives the agent's turns (the Pro keeps it through them, pod_model `set_state`), so
* its agent stays `question` in the library page; any other is no longer live.
*/
private endLive(agentId: string): void {
this.turnOpen.delete(agentId)
if (this.superTabAsks.has(agentId)) this.liveTurns.set(agentId, 'question')
else this.liveTurns.delete(agentId)
}
/**
* That question is no longer waiting — answered in the app, or in the pane by hand.
*
* Carries the id so a dial showing a DIFFERENT question cannot be closed by a stale message: the two
* screens are minutes apart on a slow question, and closing the wrong one loses an answer the user was
* halfway through giving.
*/
async questionClose(agentId: string, id: string): Promise<void> {
const wait = this.superTabAsks.get(agentId)
// A wait this device was never sent (it cannot show one) has nothing to close.
if (id.startsWith(SUPER_TAB_REQUEST_PREFIX) && wait?.id !== id) return
if (!this.questionInbox.close(agentId, id)) return
this.superTabAsks.delete(agentId)
// Answered: the turn goes on (its end clears it). A Super Tab wait outlived its turns: working only if one is open.
if (this.liveTurns.get(agentId) === 'question') {
if (!wait || this.turnOpen.has(agentId)) this.liveTurns.set(agentId, 'working')
else this.liveTurns.delete(agentId)
}
await this.send({ t: 'question.close', agentId, id })
}
async focusAgent(agentId: string): Promise<void> {
this.desiredFocus = agentId
const sent = await this.send({ t: 'focus', agentId })
if (sent && this.desiredFocus === agentId) this.appFocusUnsent = false
}
/**
* The desktop window moved to an agent — bring the dial with it.
*
* ⚠️ THE `desiredFocus` GUARD IS WHAT KEEPS THIS FROM OSCILLATING. The two screens drive each other: the
* dial's own carousel reports `focus` up, the daemon hands that to the app, the app opens that agent's
* terminal, and the app opening a terminal is exactly what calls this. Answering it with another `focus`
* closes the ring. So: say nothing when the record already names that agent.
*
* The record is one field written by both sides (see desiredFocus). It used to be two, and the ring
* closed through the gap between them.
*
* The list comes first, but attaching to the machine does not. The dial now holds the active tab's
* panes across all machines. Waiting for the separate remote attachment held even a newer LOCAL
* selection behind the network, leaving the round unit on the old pane. Update the machine wheel
* separately, still in order, so a slow attachment cannot block the selected pane.
*/
async followApp(machineId: string, agentId: string): Promise<void> {
if (!this.link?.isOpen || this.greetedMac === null) return
if (!agentId) return
// Read now: the focus step below writes the record. Desktop re-sends the same focus whenever its visible panes change,
// and a dial's own turn comes back as an echo: neither is anyone choosing anything (review of #2504).
const moved = agentId !== this.desiredFocus || this.appFocusUnsent
const generation = ++this.appFocusGeneration
const task = this.appFocusTail.then(async () => {
// A newer desktop selection made this queued one obsolete before it started.
if (generation !== this.appFocusGeneration) return
this.drivingSince = Date.now()
this.drivingAppFocus = true
try {
// Already where the window is: nothing to command. The record is right either way — this is the
// window FOLLOWING the dial, and the dial's own report wrote it.
if (agentId === this.desiredFocus && !this.appFocusUnsent) return
// Said before the frame goes out, not after: the frame itself succeeds either way.
const unknown = this.host.knows?.(agentId) === false
this.log(`cable: following the app to agent ${agentId}${unknown ? ' — NOT in this daemon\'s list, the dial has no tile for it' : ''}`)
this.expectedAppFocusEcho = agentId
this.expectedAppFocusEchoUntil = Date.now() + APP_FOCUS_SETTLE_MS
// THE LIST FIRST, THEN THE FOCUS — the fix for "clicking a rail agent that has no tile does not
// move the dial".
//
// A focus names a tile the dial has to CENTRE, and the dial can only centre what its ring walks.
// The click that brought us here is usually the very thing that changed the ring: opening an
// agent that had no tile puts it on the desk, and until that list is pushed the dial is still
// walking a ring where that agent sits off it — where the device drops the focus, by design, with
// no column to move to. Racing the two produced exactly the reported symptom: mostly it worked
// (the tick's push arrived first), sometimes it did not, and nothing in either log said which.
//
// The record is written BEFORE the push so the re-assert at the end of syncAgents names the agent
// we are moving to, not the one we are leaving — otherwise the dial visibly steps onto the old
// tile on its way. Cheap when nothing changed: syncAgents returns without sending a frame.
this.desiredFocus = agentId
this.appFocusUnsent = true
await this.syncAgents()
if (generation !== this.appFocusGeneration) return
await this.focusAgent(agentId) // writes the record
} finally {
this.drivingAppFocus = false
}
})
// Keep the queue usable after one transport failure. The local websocket intentionally
// fire-and-forgets followApp, so the session log is the only place an unexpected rejection would
// otherwise be visible; consume it here rather than creating an unhandled rejection.
const focused = this.appFocusTail = task.catch((err) => {
this.log(`cable: could not follow app focus (${(err as Error).message})`)
})
const machineTask = this.appMachineTail.then(async () => {
await focused
const isCurrent = () => generation === this.appFocusGeneration
if (!isCurrent() || !machineId) return
// Only a focus that really moved replaces a pick on its way elsewhere (see selectMachine).
if (machineId === this.host.selectedMachine() && !(moved && this.host.pendingPick?.())) {
// An older attachment to this same machine may have finished without acknowledging it,
// because a newer pane superseded that request. The wheel still needs its selection.
await this.syncMachines()
return
}
this.log(`cable: following the app to machine ${machineId}`)
await this.selectMachine(machineId, isCurrent)
})
const selected = this.appMachineTail = machineTask.catch((err) => {
this.log(`cable: could not follow app machine (${(err as Error).message})`)
})
await Promise.all([focused, selected])
}
async toast(text: string): Promise<void> {
await this.send({ t: 'toast', text })
}
}