Skip to content

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.

feat(cable): stay quiet about a turn that finished in plain sight

0xdiego25a83740059d52
diff --git a/cli/src/cable/cableSession.spec.ts b/cli/src/cable/cableSession.spec.ts
index 87a23de42..ffef1ea6c 100644
--- a/cli/src/cable/cableSession.spec.ts
+++ b/cli/src/cable/cableSession.spec.ts
@@ -562,6 +562,21 @@ describe('cable session', () => {
await session.stop()
})
+ it('marks a summary quiet when the window already has that agent on screen', async () => {
+ const { session, port } = await connect(makeHost({}))
+ port.say({ t: 'hello', product: 'harness', mac: 'aa:bb' })
+
+ await session.summary('a1', 'recap one', 'body one')
+ await session.summary('a2', 'recap two', 'body two', true)
+
+ const sent = port.sent.filter((m) => m.t === 'summary' && !m.restore)
+ // Absent, not false, on the ordinary path: firmware that predates the flag must keep notifying
+ // exactly as it did, and it reads a missing field as false.
+ expect(sent.find((m) => m.agentId === 'a1')).not.toHaveProperty('quiet')
+ // The recap still travels — the tile draws it either way. Only the beep and the drawer are withheld.
+ expect(sent.find((m) => m.agentId === 'a2')).toMatchObject({ quiet: true, recap: 'recap two' })
+ })
+
it('redraws a reattached dial with what each agent was last doing', async () => {
// The summaries were on disk the whole time; a tile with a name and no recap has forgotten the work
// it belongs to. Newest LAST on the wire so it ends up on top of the tile's stack.
diff --git a/cli/src/cable/cableSession.ts b/cli/src/cable/cableSession.ts
index 2f4baddfc..a6582bc49 100644
--- a/cli/src/cable/cableSession.ts
+++ b/cli/src/cable/cableSession.ts
@@ -1011,8 +1011,16 @@ export class CableSession {
async turnDone(agentId: string): Promise<void> {
await this.send({ t: 'turn.done', agentId })
}
- async summary(agentId: string, recap: string, text: string): Promise<void> {
- await this.send({ t: 'summary', agentId, recap, text })
+ /**
+ * A finished turn's recap.
+ *
+ * `quiet` means the window already has this agent on screen: draw the tile,
+ * skip the beep and the notification drawer. An extra field rather than a
+ * different frame, so firmware that predates it simply notifies as it always
+ * did instead of losing the recap.
+ */
+ async summary(agentId: string, recap: string, text: string, quiet = false): Promise<void> {
+ await this.send(quiet ? { t: 'summary', agentId, recap, text, quiet: true } : { t: 'summary', agentId, recap, text })
}
async turnError(agentId: string, message: string): Promise<void> {
await this.send({ t: 'turn.error', agentId, message })
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 68504b1a1..ea6dd3ec3 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -1100,6 +1100,8 @@ async function runForeground(session: AuthSession): Promise<void> {
// machine selected, because the carousel held one machine's agents at a time; it now holds every
// machine's at once, so this computer's tiles are on screen whichever machine the wheel last landed on
// and skipping the recap here would leave them permanently blank.
+ /** Agents with a tile open in the desktop window right now. Empty when no window is attached. */
+ let openPaneAgents = new Set<string>()
const cableWatchingLocal = (): boolean => cableRef?.isConnected === true
const deviceIsWatching = (): boolean => backend.hasCommander() || cableWatchingLocal()
@@ -2566,6 +2568,22 @@ async function runForeground(session: AuthSession): Promise<void> {
// The window and the dial are one desk: opening an agent in the app brings the dial to it, switching
// the dial's machine first when the app moved to another one.
onAppFocus: (machineId, agentId) => { void cableRef?.followApp(machineId, agentId) },
+ // Agents the window has a tile for. A finished turn on one of these is
+ // already in front of the person, so the dial updates its tile in silence
+ // rather than beeping about something being looked at.
+ //
+ // An OPEN tile counts as seen, deliberately — not a focused one. With four
+ // tiles on a grid all four are on screen, and asking which one the eye is
+ // on is a question the window cannot answer honestly anyway.
+ onAppPanes: (agentIds) => {
+ const next = new Set(agentIds)
+ // Logged on CHANGE only. It fires on every pane add, close and reconnect,
+ // and it is the one place the whole feature is observable from — without
+ // it, "the dial went quiet" and "the roster never arrived" look identical.
+ const changed = next.size !== openPaneAgents.size || [...next].some((id) => !openPaneAgents.has(id))
+ openPaneAgents = next
+ if (changed) console.log(`[cable] window tiles: ${next.size ? [...next].map(sid).join(' ') : '(none)'}`)
+ },
machineId: backend.machineId,
backend,
relayPool,
@@ -3385,7 +3403,12 @@ async function runForeground(session: AuthSession): Promise<void> {
if (!event) return
if (event.kind === 'processing') void cable.turnStarted(event.agentId, event.text)
else if (event.kind === 'done') void cable.turnDone(event.agentId)
- else if (event.kind === 'summary') void cable.summary(event.agentId, event.recap || event.text, event.text)
+ else if (event.kind === 'summary') {
+ // Quiet when the window already has this agent on screen. The tile still
+ // updates — the recap is what it draws — only the beep and the drawer
+ // entry are withheld, because they exist for a turn nobody is watching.
+ void cable.summary(event.agentId, event.recap || event.text, event.text, openPaneAgents.has(event.agentId))
+ }
else void cable.turnError(event.agentId, event.text)
}
@@ -3403,7 +3426,12 @@ async function runForeground(session: AuthSession): Promise<void> {
if (event.kind === 'question') { void cable.question(event.agentId, event.requestId, event.questions); return }
if (event.kind === 'processing') void cable.turnStarted(event.agentId, event.text)
else if (event.kind === 'done') void cable.turnDone(event.agentId)
- else if (event.kind === 'summary') void cable.summary(event.agentId, event.recap || event.text, event.text)
+ else if (event.kind === 'summary') {
+ // Quiet when the window already has this agent on screen. The tile still
+ // updates — the recap is what it draws — only the beep and the drawer
+ // entry are withheld, because they exist for a turn nobody is watching.
+ void cable.summary(event.agentId, event.recap || event.text, event.text, openPaneAgents.has(event.agentId))
+ }
else void cable.turnError(event.agentId, event.text)
})
diff --git a/cli/src/localWsServer.spec.ts b/cli/src/localWsServer.spec.ts
index 680d01473..e666d7cfd 100644
--- a/cli/src/localWsServer.spec.ts
+++ b/cli/src/localWsServer.spec.ts
@@ -1,6 +1,6 @@
import http from 'node:http'
import type { AddressInfo } from 'node:net'
-import { afterEach, describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
import { WebSocket } from 'ws'
import type { Frame, LocalClientSink } from './backendSocket.js'
import { attachLocalWsServer, type LocalWsBackend, type LocalWsServer } from './localWsServer.js'
@@ -105,6 +105,37 @@ describe('local CLI WebSocket', () => {
ws.close()
})
+ it('takes the window\'s tile roster, keeps it off the wire, and forgets it on close', async () => {
+ const backend = new FakeBackend()
+ const rosters: string[][] = []
+ server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
+ local = attachLocalWsServer(server, {
+ machineId,
+ backend,
+ onAppPanes: (ids) => rosters.push(ids),
+ })
+ await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
+ const url = `ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`
+
+ const ws = new WebSocket(url)
+ await onceOpen(ws)
+ const connected = onceMessage(ws)
+ ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
+ await connected
+
+ ws.send(JSON.stringify({ type: 'app_panes', payload: { agentIds: ['a1', 'a2', '', 7, null] } }))
+ await new Promise((resolve) => setTimeout(resolve, 20))
+ // Anything that is not a usable id is dropped rather than trusted.
+ expect(rosters).toEqual([['a1', 'a2']])
+ // Like app_focus: it describes a screen at this desk, so the machine never sees it.
+ expect(backend.frames.map((frame) => frame.type)).toEqual([])
+
+ ws.close()
+ // A window that went away has no tiles open. Left standing, the roster would go on silencing the
+ // dial for agents nobody can see any more — backwards, and permanently.
+ await vi.waitFor(() => expect(rosters).toEqual([['a1', 'a2'], []]))
+ })
+
it('follows an explicit app_focus, and keeps it off the wire', async () => {
const backend = new FakeBackend()
const moves: Array<{ machineId: string; agentId: string }> = []
diff --git a/cli/src/localWsServer.ts b/cli/src/localWsServer.ts
index 53f859921..ca3f17285 100644
--- a/cli/src/localWsServer.ts
+++ b/cli/src/localWsServer.ts
@@ -29,6 +29,8 @@ export interface LocalWsServerOptions {
/** The desktop app opened an agent's terminal — which agent, and on which machine. Lets the dial follow
* the window, so the two screens stay one desk. */
onAppFocus?: (machineId: string, agentId: string) => void
+ /** Every agent the window currently has a tile for, across all its machines. */
+ onAppPanes?: (agentIds: string[]) => void
}
export interface LocalWsServer {
@@ -111,6 +113,8 @@ export function attachLocalWsServer(server: http.Server, options: LocalWsServerO
// fixed for the life of the connection — set once, beside `selected`.
let boundMachineId: string | null = null
let relay: RelaySession | null = null
+ /** Whether this connection ever reported a tile roster — only then is clearing it ours to do. */
+ let sentPanes = false
let alive = true
let chain = Promise.resolve()
@@ -188,6 +192,24 @@ export function attachLocalWsServer(server: http.Server, options: LocalWsServerO
// Sniffed here rather than in the backend socket because that path never sees a RELAYED machine's
// frames: those are forwarded upstream a few lines below and would be invisible, which is exactly
// the case that matters — the dial has to follow the window onto ANOTHER machine too.
+ // The window's tile ROSTER. Consumed here like `app_focus` — it describes
+ // a screen at this desk, not anything the machine could act on.
+ //
+ // It carries every agent the window has open, INCLUDING ones belonging
+ // to other machines, and the app sends the same list to every daemon it
+ // is connected to. That is deliberate: the dial is served by whichever
+ // daemon owns the cable, and only a full picture lets that one decide
+ // whether a finished turn is already in front of the person.
+ if (!isBinary && options.onAppPanes) {
+ const roster = jsonFrame(raw)
+ if (roster?.type === 'app_panes') {
+ const raw = (roster.payload as Record<string, unknown> | undefined)?.agentIds
+ const ids = Array.isArray(raw) ? raw.filter((id): id is string => typeof id === 'string' && id !== '') : []
+ sentPanes = true
+ options.onAppPanes(ids)
+ return
+ }
+ }
if (!isBinary && options.onAppFocus && boundMachineId) {
const moved = jsonFrame(raw)
const agentId = (moved?.payload as Record<string, unknown> | undefined)?.agentId
@@ -246,6 +268,10 @@ export function attachLocalWsServer(server: http.Server, options: LocalWsServerO
const cleanup = (): void => {
clearInterval(heartbeat)
+ // A window that went away has no tiles open. Left standing, the roster
+ // would keep silencing the dial for agents nobody can see any more —
+ // exactly backwards, and permanently.
+ if (sentPanes) options.onAppPanes?.([])
if (relay) { relay.detach(); relay = null }
else if (selected) void options.backend.unregisterLocalClient(connId)
selected = false