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): coalesce loopback terminal output on a 2ms window, not 8ms

0xken1570867437337d
diff --git a/cli/src/lib/terminalStreamManager.spec.ts b/cli/src/lib/terminalStreamManager.spec.ts
index 19adaa437..7d29861f1 100644
--- a/cli/src/lib/terminalStreamManager.spec.ts
+++ b/cli/src/lib/terminalStreamManager.spec.ts
@@ -845,4 +845,37 @@ describe('TerminalStreamManager', () => {
expect(binarySent.length).toBe(afterLeadingEdge + 1)
expect(Buffer.from(binarySent.at(-1)!.frame.bytes).toString()).toBe('onetwothree')
})
+
+ it('coalesces a loopback burst on a 2ms window while the relay keeps 8ms', async () => {
+ await manager.stop()
+ manager = newManager({ isLoopback: (connId) => connId.startsWith('local:') })
+
+ const burst = async (connId: string, requestId: string): Promise<number> => {
+ await manager.handleFrame(connId, 'terminal_open', {
+ requestId, protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
+ })
+ await vi.advanceTimersByTimeAsync(20) // a quiet gap, so 'lead' takes the leading edge
+ sink!.onData(Buffer.from('lead'))
+ const afterLeadingEdge = binarySent.length
+ sink!.onData(Buffer.from('one'))
+ sink!.onData(Buffer.from('two'))
+ sink!.onData(Buffer.from('three'))
+ expect(binarySent.length).toBe(afterLeadingEdge)
+ return afterLeadingEdge
+ }
+
+ // The desktop on this computer: the burst goes out after 2ms, as one frame.
+ let afterLeadingEdge = await burst('local:desktop', 'open-local-burst')
+ await vi.advanceTimersByTimeAsync(2)
+ expect(binarySent.length).toBe(afterLeadingEdge + 1)
+ expect(Buffer.from(binarySent.at(-1)!.frame.bytes).toString()).toBe('onetwothree')
+
+ // Anything else still waits the full 8ms window.
+ afterLeadingEdge = await burst('web-1', 'open-web-burst')
+ await vi.advanceTimersByTimeAsync(2)
+ expect(binarySent.length).toBe(afterLeadingEdge)
+ await vi.advanceTimersByTimeAsync(6)
+ expect(binarySent.length).toBe(afterLeadingEdge + 1)
+ expect(Buffer.from(binarySent.at(-1)!.frame.bytes).toString()).toBe('onetwothree')
+ })
})
diff --git a/cli/src/lib/terminalStreamManager.ts b/cli/src/lib/terminalStreamManager.ts
index 5cebeaa75..83744acfe 100644
--- a/cli/src/lib/terminalStreamManager.ts
+++ b/cli/src/lib/terminalStreamManager.ts
@@ -78,6 +78,11 @@ 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.
+const LOOPBACK_OUTPUT_FLUSH_MS = 2
const OUTPUT_CHUNK_BYTES = 32 * 1024
const INPUT_MAX_BYTES = 64 * 1024
const PAUSE_HIGH_WATERMARK_BYTES = 384 * 1024
@@ -105,6 +110,8 @@ 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. */
+ flushMs: number
expiresAt: number
lastSyncAt: number
nextSeq: number
@@ -486,7 +493,8 @@ export class TerminalStreamManager {
// every TUI redraw for nothing. Decided here rather than in the app because the app cannot
// tell this daemon's own machine from one it reaches through the relay — where the same
// frames DO cross the internet and zlib still earns its keep.
- const wantsZlib = requestedCompression.includes('zlib') && !this.deps.isLoopback?.(connId)
+ const loopback = this.deps.isLoopback?.(connId) ?? false
+ const wantsZlib = requestedCompression.includes('zlib') && !loopback
state = {
connId,
...(client ? { client } : {}),
@@ -497,6 +505,7 @@ export class TerminalStreamManager {
placementKey,
handle: opened.value,
compression: wantsZlib ? 'zlib' : 'none',
+ flushMs: loopback ? LOOPBACK_OUTPUT_FLUSH_MS : OUTPUT_FLUSH_MS,
expiresAt: this.now() + HEARTBEAT_TIMEOUT_MS,
lastSyncAt: this.now(),
nextSeq: 0,
@@ -952,14 +961,14 @@ export class TerminalStreamManager {
return
}
// Leading edge: the first output after a quiet gap goes out immediately, which is what a
- // keystroke echo is. Waiting the full window for it cost every echo 8ms for no benefit —
+ // keystroke echo is. Waiting the full window for it cost every echo the window for no benefit —
// there was nothing else to coalesce it with. A burst still lands on the trailing timer
- // below, so the frame rate ceiling is unchanged.
- if (!state.flushTimer && this.now() - state.lastFlushAt >= OUTPUT_FLUSH_MS) {
+ // below, so the frame rate stays capped at one frame per `state.flushMs`.
+ if (!state.flushTimer && this.now() - state.lastFlushAt >= state.flushMs) {
this.flushOutput(state)
return
}
- state.flushTimer ??= setTimeout(() => this.flushOutput(state), OUTPUT_FLUSH_MS)
+ state.flushTimer ??= setTimeout(() => this.flushOutput(state), state.flushMs)
}
private flushOutput(state: ActiveStream): void {