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
Stop Grok wheel from scrolling stale TUI frames
Catalin Waack1021cf05a02f
diff --git a/cli/src/lib/terminalStreamManager.spec.ts b/cli/src/lib/terminalStreamManager.spec.tsindex 0806b3752..b38eb2032 100644--- a/cli/src/lib/terminalStreamManager.spec.ts+++ b/cli/src/lib/terminalStreamManager.spec.ts@@ -25,11 +25,13 @@ class FakeStream implements TerminalStreamHandle {resumes = 0snapshotBegins = 0snapshotEnds = 0+ snapshotOptions: Array<{ tuiOwnsScrollback?: boolean } | undefined> = []onEndSnapshot: (() => void) | null = nullbeginSnapshot() { this.snapshotBegins++ }- async snapshot(): Promise<{ state: 'succeeded'; value: { bytes: Uint8Array; cols: number; rows: number } }> {+ async snapshot(options?: { tuiOwnsScrollback?: boolean }): Promise<{ state: 'succeeded'; value: { bytes: Uint8Array; cols: number; rows: number } }> {this.snapshots+++ this.snapshotOptions.push(options)this.onSnapshot?.(this.snapshots)return { state: 'succeeded', value: { bytes: this.snapshotBytes, cols: 120, rows: 40 } }}@@ -135,6 +137,19 @@ describe('TerminalStreamManager', () => {expect(sent.at(-1)?.payload.code).toBe('TERMINAL_AGENT_NOT_FOUND')})+ it('tells a Grok snapshot not to seed tmux history, and leaves other engines alone', async () => {+ await manager.handleFrame('web-1', 'terminal_open', {+ requestId: 'open-codex', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,+ })+ expect(stream.snapshotOptions.at(-1)).toBeUndefined()++ agents.set('grok-1', session('grok', 'grok-1'))+ await manager.handleFrame('web-1', 'terminal_open', {+ requestId: 'open-grok', protocolVersion: 3, agentId: 'grok-1', cols: 120, rows: 40,+ })+ expect(stream.snapshotOptions.at(-1)).toEqual({ tuiOwnsScrollback: true })+ })+it('opens with a keyframe, streams coalesced output, and writes ordered raw input', async () => {await manager.handleFrame('web-1', 'terminal_open', {requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40, compression: ['zlib'],diff --git a/cli/src/lib/terminalStreamManager.ts b/cli/src/lib/terminalStreamManager.tsindex f438af183..77a3d4dec 100644--- a/cli/src/lib/terminalStreamManager.ts+++ b/cli/src/lib/terminalStreamManager.ts@@ -754,9 +754,9 @@ export class TerminalStreamManager {/** Scroll gestures arrive stream-scoped, same as resize — no ordering/seq guard needed since,* unlike input, an out-of-order or dropped scroll frame just means one gesture scrolled a little- * more or less than intended, never a corrupted stream. The pane's live output stream (already- * flowing via `sink.onData`) naturally carries the scrolled copy-mode view back to the client, so- * no explicit keyframe push is needed here the way resize needs one. */+ * more or less than intended, never a corrupted stream. PageUp/PageDown are written into the+ * pty, so the program's own redraw rides the live output stream (`sink.onData`) back to the+ * client; no explicit keyframe push is needed here the way resize needs one. */private async scroll(connId: string, payload: FramePayload): Promise<void> {const state = this.streamFor(connId, payload)if (!state) return@@ -923,7 +923,9 @@ export class TerminalStreamManager {reason: 'tmux snapshot did not run',}try {- snapshot = await state.handle.snapshot()+ snapshot = await state.handle.snapshot(+ state.engineId === 'grok' ? { tuiOwnsScrollback: true } : undefined,+ )} catch (error) {snapshot = { state: 'failed', reason: error instanceof Error ? error.message : 'tmux snapshot failed' }}diff --git a/cli/src/lib/terminalTypes.ts b/cli/src/lib/terminalTypes.tsindex 908575213..c4255f96b 100644--- a/cli/src/lib/terminalTypes.ts+++ b/cli/src/lib/terminalTypes.ts@@ -162,8 +162,13 @@ export interface TerminalStreamHandle<Ref extends TerminalRuntimeRef = TerminalRbeginSnapshot(): void/** Capture only the authoritative visible viewport. Terminal scrollback can* contain prior full-screen TUI repaint frames and must never be replayed as- * part of a keyframe. */- snapshot(): Promise<TerminalReadResult<TerminalStreamSnapshot>>+ * part of a keyframe.+ *+ * `tuiOwnsScrollback` is for a full-screen TUI that paints in tmux's *normal*+ * buffer (Grok). Its tmux history is prior repaint frames, not a shell+ * transcript, and must not be seeded; the snapshot is labelled as the+ * alternate screen so the receiver routes the wheel to the program. */+ snapshot(options?: { tuiOwnsScrollback?: boolean }): Promise<TerminalReadResult<TerminalStreamSnapshot>>/** Release output produced strictly after the snapshot cut. */endSnapshot(): voidwriteRaw(bytes: Uint8Array): Promise<TerminalActionResult>@@ -171,11 +176,12 @@ export interface TerminalStreamHandle<Ref extends TerminalRuntimeRef = TerminalR* `pasteRawIntoTmux` for why a paste needs its own path instead of reusing the keystroke one. */pasteRaw(text: string): Promise<TerminalActionResult>resize(size: TerminalStreamSize): Promise<TerminalActionResult>- /** Scroll via the backend's own history mechanism (tmux copy-mode for `TmuxControlStream`) rather- * than writing bytes into the pty — a program that owns terminal mouse-tracking but doesn't- * itself understand SGR wheel reports (confirmed live for Grok: it echoes the raw escape bytes- * into its own prompt instead of scrolling) would otherwise treat wheel input as garbage- * keystrokes. Backends with no such concept (anything not tmux-backed) may no-op. */+ /** Scroll a full-screen TUI that owns mouse-tracking but mishandles SGR wheel+ * reports (confirmed live for Grok: it echoes the raw escape bytes into its+ * own prompt). The tmux backend sends PageUp/PageDown into the pty — Grok+ * scrolls its conversation with those keys even while the prompt is focused.+ * Do not use tmux copy-mode: alt-screen history is prior TUI repaint frames.+ * Backends with no such concept (anything not tmux-backed) may no-op. */scroll(direction: 'up' | 'down', lines: number): Promise<TerminalActionResult>pauseOutput(): Promise<TerminalActionResult>resumeOutput(): Promise<TerminalActionResult>diff --git a/cli/src/lib/tmuxStream.real.spec.ts b/cli/src/lib/tmuxStream.real.spec.tsindex dfbb0b691..f0ff494d6 100644--- a/cli/src/lib/tmuxStream.real.spec.ts+++ b/cli/src/lib/tmuxStream.real.spec.ts@@ -80,6 +80,11 @@ run('TmuxControlStream real tmux', () => {}expect(Buffer.concat(chunks).includes(Buffer.from('HARNESS_STREAM_OK'))).toBe(true)+ expect((await opened.value.scroll('up', 5)).state).toBe('succeeded')+ expect(await tmux(['display-message', '-p', '-t', paneId, '#{pane_in_mode}'])).toBe('0')+ expect((await opened.value.scroll('down', 1)).state).toBe('succeeded')+ expect(await tmux(['display-message', '-p', '-t', paneId, '#{pane_in_mode}'])).toBe('0')+expect((await opened.value.resize({ cols: 110, rows: 35 })).state).toBe('succeeded')expect(await tmux(['display-message', '-p', '-t', paneId, '#{pane_width}x#{pane_height}'])).toBe('110x35')await opened.value.close()diff --git a/cli/src/lib/tmuxStream.spec.ts b/cli/src/lib/tmuxStream.spec.tsindex ff4a769bb..7a26b02c8 100644--- a/cli/src/lib/tmuxStream.spec.ts+++ b/cli/src/lib/tmuxStream.spec.ts@@ -6,8 +6,19 @@ import {normalizeTmuxCaptureLines,parseTmuxControlOutput,synthesizeTmuxSnapshot,+ tuiScrollPageCount,} from './tmuxStream.js'+describe('tuiScrollPageCount', () => {+ it('is one page per gesture, never a stack', () => {+ expect(tuiScrollPageCount(0)).toBe(0)+ expect(tuiScrollPageCount(-1)).toBe(0)+ expect(tuiScrollPageCount(1)).toBe(1)+ expect(tuiScrollPageCount(12)).toBe(1)+ expect(tuiScrollPageCount(400)).toBe(1)+ })+})+describe('tmux control-mode output decoding', () => {it('decodes octal bytes without corrupting adjacent UTF-8', () => {const decoded = decodeTmuxControlData('hello\\040世界\\015\\012\\033[31m')diff --git a/cli/src/lib/tmuxStream.ts b/cli/src/lib/tmuxStream.tsindex 7352c58dd..17b82fe73 100644--- a/cli/src/lib/tmuxStream.ts+++ b/cli/src/lib/tmuxStream.ts@@ -25,6 +25,17 @@ const SNAPSHOT_BUFFER_MAX_BYTES = 2 * 1024 * 1024const SNAPSHOT_QUIET_MS = 8const SNAPSHOT_QUIET_MAX_MS = 40const SNAPSHOT_HISTORY_LINES = 500+/** Grok only exposes PageUp/PageDown while the prompt is focused, so a wheel+ * burst is one page, never a stack of them. The desktop may still emit+ * several `terminal_scroll` frames per flick (16ms coalesce on shipped+ * builds); the interval below drops the extras. */+const TUI_SCROLL_MIN_INTERVAL_MS = 180++/** How many PageUp/PageDown keys a coalesced wheel burst should become. */+export function tuiScrollPageCount(lines: number): number {+ if (!Number.isFinite(lines) || lines <= 0) return 0+ return 1+}const PANE_META_FORMAT = ['#{session_id}', '#{window_id}', '#{window_panes}', '#{window_width}', '#{window_height}','#{pane_width}', '#{pane_height}', '#{alternate_on}', '#{cursor_x}', '#{cursor_y}',@@ -427,9 +438,7 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {private snapshotPostCut: Buffer[] = []private snapshotPostCutBytes = 0private snapshotLastOutputAt = 0- // Set by scroll() when it enters tmux copy-mode. Copy-mode swallows keyboard input for its own- // navigation, so writeRaw() must exit it before the next real keystroke — see writeRaw()'s doc.- private inCopyMode = false+ private lastTuiScrollAt = 0private constructor(paneId: string,@@ -586,7 +595,7 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {}}- async snapshot(): Promise<TerminalReadResult<TerminalStreamSnapshot>> {+ async snapshot(options?: { tuiOwnsScrollback?: boolean }): Promise<TerminalReadResult<TerminalStreamSnapshot>> {return this.serializeOperation(async () => {if (!this.snapshotGated) return { state: 'failed', reason: 'tmux snapshot gate is not active' }// -N is required for TUI fidelity: styled blank cells (for example the@@ -610,7 +619,14 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {// local scrollback. It preserves SGR attributes without replaying old// TUI cursor movement. Read it before the authoritative visible-grid cut// so concurrent output is included there or in a post-cut delta.- const history = meta.alternateOn+ //+ // Grok (and any TUI that paints in the normal buffer) is the other+ // history trap: tmux reports alternate_on=0, so a naive capture would+ // seed hundreds of prior full-screen repaint frames. The window then+ // shows stacked empty chrome above the live header, and the wheel+ // scrolls that junk locally instead of the program.+ const tuiOwnsScrollback = options?.tuiOwnsScrollback === true+ const history = (meta.alternateOn || tuiOwnsScrollback)? Buffer.alloc(0): (await this.runControlCommand(`capture-pane -p -e -N -t ${this.runtime.paneId} -S -${SNAPSHOT_HISTORY_LINES} -E -1`,@@ -622,10 +638,11 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {this.snapshotPostCutBytes = 0})if (!capture.ok) return { state: 'failed', reason: 'tmux snapshot failed' }+ const screenMeta = tuiOwnsScrollback ? { ...meta, alternateOn: true } : metareturn {state: 'succeeded',value: {- bytes: synthesizeTmuxSnapshot(capture.stdout, meta, history),+ bytes: synthesizeTmuxSnapshot(capture.stdout, screenMeta, history),cols: meta.paneWidth,rows: meta.paneHeight,},@@ -654,16 +671,7 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {async writeRaw(bytes: Uint8Array): Promise<TerminalActionResult> {if (this.closed) return terminalActionNotStarted('terminal stream is closed')if (bytes.length === 0) return TERMINAL_ACTION_SUCCEEDED- // scroll() below leaves the pane in copy-mode, which captures all keyboard input for its own- // navigation. Cancel it before the very next real keystroke, queued ahead of the input chunks- // (the ControlCommandQueue is strict FIFO) so the pane is back to normal by the time tmux- // applies them — otherwise the first keystroke after a scroll silently vanishes into copy-mode- // instead of reaching the program, trading "can't scroll" for "can't type".const sends: Array<Promise<ControlCommandResult>> = []- if (this.inCopyMode) {- this.inCopyMode = false- sends.push(this.runControlCommand(`send-keys -X -t ${this.runtime.paneId} cancel`))- }// Every chunk is handed to the queue before any reply is awaited, so a paste costs one// round-trip rather than one per chunk. tmux applies them in the order they were written.for (let offset = 0; offset < bytes.length; offset += INPUT_CHUNK_BYTES) {@@ -694,23 +702,32 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {: terminalActionNotStarted('tmux paste-buffer could not be sent')}- /** Scroll via tmux's own copy-mode rather than writing bytes into the pty. Some remote CLIs (e.g.- * Claude Code) declare terminal mouse-tracking and correctly handle SGR wheel reports themselves;- * others declare it but don't (confirmed live for Grok: it echoes the raw escape bytes into its- * own prompt as literal characters instead of scrolling) — copy-mode works regardless, since it- * never depends on the program in the pane understanding anything about the bytes at all. */+ /** Scroll a full-screen TUI by sending PageUp/PageDown into the pty.+ *+ * Grok declares mouse-tracking but echoes SGR wheel reports as literal+ * characters, so the desktop does not send wheel bytes. tmux copy-mode is+ * the wrong substitute: for an alt-screen TUI, tmux history is prior+ * full-screen repaint frames, which stacked as empty Grok chrome above the+ * live screen. Grok's own PageUp/PageDown scroll the conversation even+ * while the prompt is focused. */async scroll(direction: 'up' | 'down', lines: number): Promise<TerminalActionResult> {if (this.closed) return terminalActionNotStarted('terminal stream is closed')- if (lines <= 0) return TERMINAL_ACTION_SUCCEEDED- // Idempotent — safe even if already in copy-mode from a previous scroll.- const entered = await this.runControlCommand(`copy-mode -t ${this.runtime.paneId}`)- if (!entered.ok) return terminalActionNotStarted('tmux copy-mode could not be entered')- this.inCopyMode = true- const command = direction === 'up' ? 'scroll-up' : 'scroll-down'- const scrolled = await this.runControlCommand(- `send-keys -N ${lines} -X -t ${this.runtime.paneId} ${command}`,+ const pages = tuiScrollPageCount(lines)+ if (pages <= 0) return TERMINAL_ACTION_SUCCEEDED+ const now = Date.now()+ if (now - this.lastTuiScrollAt < TUI_SCROLL_MIN_INTERVAL_MS) return TERMINAL_ACTION_SUCCEEDED+ this.lastTuiScrollAt = now+ // Leave copy-mode if an older daemon (or a leftover gesture) parked there.+ // `send-keys -X` fails when the pane is not in a mode; that is the common+ // case and is ignored. Both commands are queued before either reply so+ // cancel still runs first (the queue is FIFO) without an extra round-trip.+ const key = direction === 'up' ? 'PageUp' : 'PageDown'+ const cancel = this.runControlCommand(`send-keys -X -t ${this.runtime.paneId} cancel`)+ const scrolled = this.runControlCommand(+ `send-keys -N ${pages} -t ${this.runtime.paneId} ${key}`,)- if (!scrolled.ok) return terminalActionPossiblyExecuted('tmux scroll did not complete')+ await cancel+ if (!(await scrolled).ok) return terminalActionPossiblyExecuted('tmux TUI scroll did not complete')return TERMINAL_ACTION_SUCCEEDED}