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.

perf(cli): give the short output window only to the focused loopback terminal

0xken156d41bb099f4b
diff --git a/cli/src/backendSocket.spec.ts b/cli/src/backendSocket.spec.ts
index 8da1cbc47..0b963fc83 100644
--- a/cli/src/backendSocket.spec.ts
+++ b/cli/src/backendSocket.spec.ts
@@ -2418,3 +2418,25 @@ describe('machines_changed relay', () => {
await socket.stop()
})
})
+
+describe('local terminal focus', () => {
+ it('passes a registered window\'s focus to its terminals, and ignores a connection it never registered', async () => {
+ const socket = new BackendSocket('token')
+ const setFocusedAgent = vi.fn()
+ socket.setTerminalStreamManager({
+ setFocusedAgent,
+ closeConnection: vi.fn(async () => undefined),
+ closeConnectionsWhere: vi.fn(async () => undefined),
+ stop: vi.fn(async () => undefined),
+ } as unknown as TerminalStreamManager)
+ socket.registerLocalClient('local:window', { sendFrame: () => true, sendBinary: () => true })
+
+ socket.setLocalTerminalFocus('local:window', 'agent-1')
+ socket.setLocalTerminalFocus('local:window', null)
+ socket.setLocalTerminalFocus('local:stranger', 'agent-1')
+ expect(setFocusedAgent.mock.calls).toEqual([['local:window', 'agent-1'], ['local:window', null]])
+
+ await socket.unregisterLocalClient('local:window')
+ await socket.stop()
+ })
+})
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index 02c87a999..6f7fa2c1d 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -1109,6 +1109,12 @@ export class BackendSocket {
this.enqueueDown(frame, connId, 'local')
}
+ /** The window's focused agent on this local connection — its terminal gets the short output window. */
+ setLocalTerminalFocus(connId: string, agentId: string | null): void {
+ if (!this.localClients.has(connId)) return
+ this.terminalStreams?.setFocusedAgent(connId, agentId)
+ }
+
/** Route an authenticated local terminal frame without applying cloud E2EE. */
async handleLocalBinary(connId: string, frame: TerminalBinaryClear): Promise<void> {
if (!this.localClients.has(connId)) return
diff --git a/cli/src/lib/terminalStreamManager.spec.ts b/cli/src/lib/terminalStreamManager.spec.ts
index 7d29861f1..4608ac2b1 100644
--- a/cli/src/lib/terminalStreamManager.spec.ts
+++ b/cli/src/lib/terminalStreamManager.spec.ts
@@ -878,4 +878,66 @@ describe('TerminalStreamManager', () => {
expect(binarySent.length).toBe(afterLeadingEdge + 1)
expect(Buffer.from(binarySent.at(-1)!.frame.bytes).toString()).toBe('onetwothree')
})
+
+ it('gives the short window only to the terminal the loopback window has focused', async () => {
+ await manager.stop()
+ manager = newManager({ isLoopback: (connId) => connId.startsWith('local:') })
+
+ // A burst after a quiet gap; returns how long its trailing frame took to go out.
+ const trailingWindow = async (): Promise<number> => {
+ await vi.advanceTimersByTimeAsync(20)
+ sink!.onData(Buffer.from('lead'))
+ const afterLeadingEdge = binarySent.length
+ sink!.onData(Buffer.from('one'))
+ sink!.onData(Buffer.from('two'))
+ for (let ms = 1; ms <= 8; ms++) {
+ await vi.advanceTimersByTimeAsync(1)
+ if (binarySent.length > afterLeadingEdge) {
+ expect(Buffer.from(binarySent.at(-1)!.frame.bytes).toString()).toBe('onetwo')
+ return ms
+ }
+ }
+ throw new Error('burst never flushed')
+ }
+
+ // Focus elsewhere before the open: this terminal is a background tile.
+ manager.setFocusedAgent('local:desktop', 'agent-other')
+ await manager.handleFrame('local:desktop', 'terminal_open', {
+ requestId: 'open-focus', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
+ })
+ expect(await trailingWindow()).toBe(8)
+
+ // Focus moves onto it: the open stream follows, no reopen needed.
+ manager.setFocusedAgent('local:desktop', 'agent-1')
+ expect(await trailingWindow()).toBe(2)
+
+ // No terminal focused at all.
+ manager.setFocusedAgent('local:desktop', null)
+ expect(await trailingWindow()).toBe(8)
+
+ // Focus is a loopback matter: anything else keeps 8ms whatever it is told.
+ await manager.handleFrame('web-1', 'terminal_open', {
+ requestId: 'open-web-focus', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
+ })
+ manager.setFocusedAgent('web-1', 'agent-1')
+ expect(await trailingWindow()).toBe(8)
+ })
+
+ it('forgets a loopback window\'s focus when it disconnects', async () => {
+ await manager.stop()
+ manager = newManager({ isLoopback: (connId) => connId.startsWith('local:') })
+ manager.setFocusedAgent('local:desktop', 'agent-other')
+ await manager.closeConnection('local:desktop')
+
+ // Reconnected under the same id and silent about focus: back to the short window.
+ await manager.handleFrame('local:desktop', 'terminal_open', {
+ requestId: 'open-after-close', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
+ })
+ await vi.advanceTimersByTimeAsync(20)
+ sink!.onData(Buffer.from('lead'))
+ const afterLeadingEdge = binarySent.length
+ sink!.onData(Buffer.from('tail'))
+ await vi.advanceTimersByTimeAsync(2)
+ expect(binarySent.length).toBe(afterLeadingEdge + 1)
+ })
})
diff --git a/cli/src/lib/terminalStreamManager.ts b/cli/src/lib/terminalStreamManager.ts
index 83744acfe..99d26cd66 100644
--- a/cli/src/lib/terminalStreamManager.ts
+++ b/cli/src/lib/terminalStreamManager.ts
@@ -78,10 +78,12 @@ const PROTOCOL_VERSION = 3
const HEARTBEAT_TIMEOUT_MS = 30_000
const SYNC_INTERVAL_MS = 5_000
const OUTPUT_FLUSH_MS = 8
-// The loopback desktop gains nothing from the 8ms window: a frame across 127.0.0.1 costs tens of
-// microseconds, and the app already folds every write between two vsyncs into one paint. What the
-// window did cost it was a keystroke echo held up to 8ms whenever a TUI was redrawing — a quarter of
-// them in the benchmark. The relay keeps 8ms, where fewer, larger frames still pay.
+// The terminal the person is typing into on the loopback desktop gains nothing from the 8ms window:
+// a frame across 127.0.0.1 costs tens of microseconds, and the app already folds every write between
+// two vsyncs into one paint. What the window did cost it was a keystroke echo held up to 8ms whenever
+// a TUI was redrawing — a quarter of them in the benchmark. Only the FOCUSED one, though: every frame
+// costs the app a decode and a write, and four streaming tiles all on 2ms took its CPU from 15% to
+// 18% for background tiles that repaint every 80ms anyway. Those, and the relay, keep 8ms.
const LOOPBACK_OUTPUT_FLUSH_MS = 2
const OUTPUT_CHUNK_BYTES = 32 * 1024
const INPUT_MAX_BYTES = 64 * 1024
@@ -110,7 +112,10 @@ interface ActiveStream {
placementKey: string
handle: TerminalStreamHandle
compression: 'none' | 'zlib'
- /** The output coalescing window: OUTPUT_FLUSH_MS, or LOOPBACK_OUTPUT_FLUSH_MS for the desktop on this computer. */
+ /** Whether this stream serves the desktop on this computer (see `TerminalStreamManagerDeps.isLoopback`). */
+ loopback: boolean
+ /** The output coalescing window: LOOPBACK_OUTPUT_FLUSH_MS for the window's focused terminal on this
+ * computer, OUTPUT_FLUSH_MS for everything else. Follows `setFocusedAgent`. */
flushMs: number
expiresAt: number
lastSyncAt: number
@@ -194,6 +199,9 @@ export class TerminalStreamManager {
// Terminal opens from different backend connections can arrive concurrently. Serialize opens for
// the same tmux placement so takeover is deterministic and never leaves two live controllers.
private readonly leaseLocks = new Map<string, Promise<void>>()
+ // The agent each loopback window last said it has focused (`app_focus`), null for none. A window that
+ // never said is absent, and all its terminals keep the short window, as before focus was followed.
+ private readonly focusByConn = new Map<string, string | null>()
private readonly now: () => number
private readonly expiryTimer: ReturnType<typeof setInterval>
@@ -505,7 +513,8 @@ export class TerminalStreamManager {
placementKey,
handle: opened.value,
compression: wantsZlib ? 'zlib' : 'none',
- flushMs: loopback ? LOOPBACK_OUTPUT_FLUSH_MS : OUTPUT_FLUSH_MS,
+ loopback,
+ flushMs: this.flushWindow(connId, session.agentId, loopback),
expiresAt: this.now() + HEARTBEAT_TIMEOUT_MS,
lastSyncAt: this.now(),
nextSeq: 0,
@@ -1254,7 +1263,27 @@ export class TerminalStreamManager {
})
}
+ /**
+ * The loopback window on `connId` focused `agentId` (null: no terminal). That agent's terminal gets the
+ * short output window and the window's other terminals go back to the long one. Applied to open
+ * streams, so a focus move takes effect from the next flush rather than the next open; a batch already
+ * waiting on the long window still waits it out, once.
+ */
+ setFocusedAgent(connId: string, agentId: string | null): void {
+ this.focusByConn.set(connId, agentId)
+ for (const state of this.streams.values()) {
+ if (state.connId === connId) state.flushMs = this.flushWindow(connId, state.agentId, state.loopback)
+ }
+ }
+
+ private flushWindow(connId: string, agentId: string, loopback: boolean): number {
+ if (!loopback) return OUTPUT_FLUSH_MS
+ const focused = this.focusByConn.get(connId)
+ return focused === undefined || focused === agentId ? LOOPBACK_OUTPUT_FLUSH_MS : OUTPUT_FLUSH_MS
+ }
+
async closeConnection(connId: string, reason = 'connection closed', notify = false): Promise<void> {
+ this.focusByConn.delete(connId)
const states = [...this.streams.values()].filter((state) => state.connId === connId)
await Promise.all(states.map((state) => this.closeStream(state, reason, notify)))
}
@@ -1275,6 +1304,7 @@ export class TerminalStreamManager {
async stop(): Promise<void> {
clearInterval(this.expiryTimer)
+ this.focusByConn.clear()
await this.closeAll('terminal manager stopped')
}
}
diff --git a/cli/src/localWsServer.spec.ts b/cli/src/localWsServer.spec.ts
index 4e5c5f33f..5d7db8ea4 100644
--- a/cli/src/localWsServer.spec.ts
+++ b/cli/src/localWsServer.spec.ts
@@ -15,6 +15,7 @@ class FakeBackend implements LocalWsBackend {
frames: Frame[] = []
binaries: TerminalBinaryClear[] = []
unregisters: string[] = []
+ focuses: Array<[string, string | null]> = []
registerLocalClient(connId: string, sink: LocalClientSink): boolean {
this.connId = connId
@@ -30,6 +31,9 @@ class FakeBackend implements LocalWsBackend {
async handleLocalBinary(_connId: string, frame: TerminalBinaryClear): Promise<void> {
this.binaries.push(frame)
}
+ setLocalTerminalFocus(connId: string, agentId: string | null): void {
+ this.focuses.push([connId, agentId])
+ }
}
function onceOpen(ws: WebSocket): Promise<void> {
@@ -314,6 +318,54 @@ describe('local CLI WebSocket', () => {
ws.close()
})
+ it('tells this daemon\'s terminals which one is focused, even when the dial refuses the move', async () => {
+ const backend = new FakeBackend()
+ server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
+ // A stale revision keeps the dial where it is; it says nothing about the terminal in front of the person.
+ local = attachLocalWsServer(server, { machineId, backend, onAppFocusState: () => false })
+ await new Promise<void>(resolve => server!.listen(0, '127.0.0.1', resolve))
+ const ws = new WebSocket(`ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`)
+ 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_focus', payload: { agentId: 'focused', focusRevision: 'old:0' } }))
+ ws.send(JSON.stringify({ type: 'app_focus', payload: { agentId: '' } })) // malformed: ignored
+ ws.send(JSON.stringify({ type: 'app_focus', payload: { agentId: null } }))
+ await vi.waitFor(() => expect(backend.focuses).toHaveLength(2))
+ expect(backend.focuses).toEqual([[backend.connId, 'focused'], [backend.connId, null]])
+ ws.close()
+ })
+
+ it('never hands a relayed machine\'s focus to this daemon\'s terminals', async () => {
+ const backend = new FakeBackend()
+ const relayPool = {
+ acquire: async (_machineId: string, _env: string, _select: Frame, sink: LocalClientSink) => {
+ sink.sendFrame({ type: 'connected', payload: { machineId: 'other-machine', e2ee: false } })
+ return { send: async () => {}, sendBinary: async () => {}, detach: () => {} }
+ },
+ acquireIsolated: async () => { throw new Error('unused') },
+ invalidate: () => {},
+ }
+ const states: Array<string | null> = []
+ server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
+ local = attachLocalWsServer(server, {
+ machineId, backend, autonomousEnv: 'test',
+ relayPool: relayPool as unknown as NonNullable<Parameters<typeof attachLocalWsServer>[1]['relayPool']>,
+ onAppFocusState: (_machine, agent) => { states.push(agent) },
+ })
+ await new Promise<void>(resolve => server!.listen(0, '127.0.0.1', resolve))
+ const ws = new WebSocket(`ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`)
+ await onceOpen(ws)
+ const connected = onceMessage(ws)
+ ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: 'other-machine', localProtocolVersion: 1 } }))
+ await connected
+ ws.send(JSON.stringify({ type: 'app_focus', payload: { agentId: 'remote-agent' } }))
+ await vi.waitFor(() => expect(states).toEqual(['remote-agent']))
+ expect(backend.focuses).toEqual([])
+ ws.close()
+ })
+
it('carries the window\'s answer about a spoken task, and keeps it off the wire', async () => {
const backend = new FakeBackend()
const replies: Array<{ voiceId: string; reply: unknown }> = []
diff --git a/cli/src/localWsServer.ts b/cli/src/localWsServer.ts
index abe2e0881..9913cde1f 100644
--- a/cli/src/localWsServer.ts
+++ b/cli/src/localWsServer.ts
@@ -32,6 +32,8 @@ export interface LocalWsBackend {
unregisterLocalClient: (connId: string) => Promise<void>
handleLocalFrame: (connId: string, frame: Frame) => void
handleLocalBinary: (connId: string, frame: TerminalBinaryClear) => Promise<void>
+ /** The agent this window has focused, or null — which of its terminals gets the short output window. */
+ setLocalTerminalFocus?: (connId: string, agentId: string | null) => void
}
export interface LocalWsServerOptions {
@@ -457,6 +459,10 @@ export function attachLocalWsServer(server: http.Server, options: LocalWsServerO
const agentId = (parsed?.payload as Record<string, unknown> | undefined)?.agentId
if (parsed?.type === 'app_focus') {
if (agentId === null || (typeof agentId === 'string' && agentId)) {
+ // Ahead of the dial's revision check below: that gate is about which agent the voice
+ // follows, and a stale one says nothing about which terminal is in front of the person.
+ // Only this daemon's own streams — a relayed machine's live on that machine's daemon.
+ if (!relay && boundMachineId === options.machineId) options.backend.setLocalTerminalFocus?.(connId, agentId)
const revision = (parsed.payload as Record<string, unknown>)?.focusRevision
if (options.onAppFocusState?.(boundMachineId, agentId, connId,
typeof revision === 'string' ? revision : undefined) === false) return