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
feat: implement terminal_scroll support using tmux copy-mode for reliable remote scrolling
0xken15cee0552210e8
diff --git a/cli/src/lib/e2ee/core.test.ts b/cli/src/lib/e2ee/core.test.tsindex 865a18a94..94bfeabba 100644--- a/cli/src/lib/e2ee/core.test.ts+++ b/cli/src/lib/e2ee/core.test.ts@@ -187,6 +187,6 @@ describe('e2ee core — interop keystone', () => {it('core.ts still hashes to the pinned value shared with the other implementations', () => {const here = dirname(fileURLToPath(import.meta.url))const actual = createHash('sha256').update(readFileSync(join(here, 'core.ts'))).digest('hex')- expect(actual).toBe('d90702b3385c2b2a75e5cdce49094a5646bb9831e2abaefb73f513185beb853a')+ expect(actual).toBe('5ce871815e610561cd829fc7dd7c5f280767e95355a05dacc996fb902d7ee11f')})})diff --git a/cli/src/lib/e2ee/core.ts b/cli/src/lib/e2ee/core.tsindex 5b48c236d..ad7c987dd 100644--- a/cli/src/lib/e2ee/core.ts+++ b/cli/src/lib/e2ee/core.ts@@ -369,7 +369,7 @@ export const ENCRYPTED_DOWN_TYPES = new Set<string>([// Remote terminal control is always pairwise E2EE. The relay may route by outer type/connId but must// never see agent ids, terminal bytes, dimensions, sequence numbers, or capability metadata.'terminal_capabilities', 'terminal_open', 'terminal_alive', 'terminal_ack', 'terminal_input',- 'terminal_resize', 'terminal_resync', 'terminal_close',+ 'terminal_resize', 'terminal_resync', 'terminal_close', 'terminal_scroll',])export function isEncryptedUpType(t: string): boolean { return ENCRYPTED_UP_TYPES.has(t) }export function isEncryptedRpcResultType(t: string): boolean { return ENCRYPTED_RPC_RESULT_TYPES.has(t) }diff --git a/cli/src/lib/terminalStreamManager.spec.ts b/cli/src/lib/terminalStreamManager.spec.tsindex 820f442f5..8105cca3e 100644--- a/cli/src/lib/terminalStreamManager.spec.ts+++ b/cli/src/lib/terminalStreamManager.spec.ts@@ -10,6 +10,7 @@ class FakeStream implements TerminalStreamHandle {readonly runtime = { backend: 'tmux' as const, paneId: '%1' }writes: Uint8Array[] = []sizes: Array<{ cols: number; rows: number }> = []+ scrolls: Array<{ direction: 'up' | 'down'; lines: number }> = []closed = falsesnapshots = 0snapshotBytes = Buffer.from('\u001bcfixture')@@ -29,6 +30,7 @@ class FakeStream implements TerminalStreamHandle {endSnapshot() { this.snapshotEnds++; this.onEndSnapshot?.() }async writeRaw(bytes: Uint8Array) { this.writes.push(bytes); return TERMINAL_ACTION_SUCCEEDED }async resize(size: { cols: number; rows: number }) { this.sizes.push(size); return TERMINAL_ACTION_SUCCEEDED }+ async scroll(direction: 'up' | 'down', lines: number) { this.scrolls.push({ direction, lines }); return TERMINAL_ACTION_SUCCEEDED }async pauseOutput() { this.pauses++; return TERMINAL_ACTION_SUCCEEDED }async resumeOutput() { this.resumes++; return TERMINAL_ACTION_SUCCEEDED }async close(): Promise<void> { this.closed = true }@@ -158,6 +160,24 @@ describe('TerminalStreamManager', () => {expect(stream.sizes.at(-1)).toEqual({ cols: 140, rows: 50 })})+ it('routes terminal_scroll to the stream handle, and rejects a malformed one', async () => {+ await manager.handleFrame('web-1', 'terminal_open', {+ requestId: 'open-scroll', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,+ })+ const streamId = sent[0].payload.streamId as string++ await manager.handleFrame('web-1', 'terminal_scroll', { streamId, direction: 'up', lines: 3 })+ expect(stream.scrolls.at(-1)).toEqual({ direction: 'up', lines: 3 })++ await manager.handleFrame('web-1', 'terminal_scroll', { streamId, direction: 'sideways', lines: 3 })+ expect(stream.scrolls).toHaveLength(1)+ expect(sent.at(-1)?.payload.code).toBe('TERMINAL_SCROLL_INVALID')++ await manager.handleFrame('web-1', 'terminal_scroll', { streamId, direction: 'down', lines: 0 })+ expect(stream.scrolls).toHaveLength(1)+ expect(sent.at(-1)?.payload.code).toBe('TERMINAL_SCROLL_INVALID')+ })+it('does not replay pre-snapshot repaint bytes after the authoritative keyframe', async () => {outputBeforeOpen = Buffer.from('\u001b[2Jstale repaint')stream.snapshotBytes = Buffer.from('\u001bcnew prompt text')diff --git a/cli/src/lib/terminalStreamManager.ts b/cli/src/lib/terminalStreamManager.tsindex e90380bdd..f4093ff9f 100644--- a/cli/src/lib/terminalStreamManager.ts+++ b/cli/src/lib/terminalStreamManager.ts@@ -149,6 +149,9 @@ export class TerminalStreamManager {case 'terminal_resize':await this.resize(connId, payload)return true+ case 'terminal_scroll':+ await this.scroll(connId, payload)+ return truecase 'terminal_resync':await this.resyncRequested(connId, payload)return true@@ -399,6 +402,27 @@ export class TerminalStreamManager {await this.sendKeyframe(state)}+ /** 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. */+ private async scroll(connId: string, payload: FramePayload): Promise<void> {+ const state = this.streamFor(connId, payload)+ if (!state) return+ const direction = payload.direction+ const lines = Number(payload.lines)+ if ((direction !== 'up' && direction !== 'down') || !Number.isSafeInteger(lines) || lines <= 0) {+ this.sendError(connId, 'TERMINAL_SCROLL_INVALID', { streamId: state.streamId })+ return+ }+ state.expiresAt = this.now() + HEARTBEAT_TIMEOUT_MS+ const result = await state.handle.scroll(direction, lines)+ if (result.state !== 'succeeded') {+ this.sendError(connId, 'TERMINAL_SCROLL_FAILED', { streamId: state.streamId, message: result.reason })+ }+ }+private async resyncRequested(connId: string, payload: FramePayload): Promise<void> {const state = this.streamFor(connId, payload)if (state) {diff --git a/cli/src/lib/terminalTypes.ts b/cli/src/lib/terminalTypes.tsindex 942c0543d..0d6d95ccf 100644--- a/cli/src/lib/terminalTypes.ts+++ b/cli/src/lib/terminalTypes.ts@@ -148,6 +148,12 @@ export interface TerminalStreamHandle<Ref extends TerminalRuntimeRef = TerminalRendSnapshot(): voidwriteRaw(bytes: Uint8Array): 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(direction: 'up' | 'down', lines: number): Promise<TerminalActionResult>pauseOutput(): Promise<TerminalActionResult>resumeOutput(): Promise<TerminalActionResult>close(): Promise<void>diff --git a/cli/src/lib/tmuxStream.ts b/cli/src/lib/tmuxStream.tsindex 0c08b2d77..0062bb583 100644--- a/cli/src/lib/tmuxStream.ts+++ b/cli/src/lib/tmuxStream.ts@@ -426,6 +426,9 @@ 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 = falseprivate constructor(paneId: string,@@ -650,9 +653,18 @@ 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.- const sends: Array<Promise<ControlCommandResult>> = []for (let offset = 0; offset < bytes.length; offset += INPUT_CHUNK_BYTES) {const chunk = bytes.subarray(offset, offset + INPUT_CHUNK_BYTES)const hex = [...chunk].map((byte) => byte.toString(16).padStart(2, '0')).join(' ')@@ -666,6 +678,26 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {: terminalActionPossiblyExecuted('tmux raw input stopped after a partial write')}+ /** 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. */+ 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}`,+ )+ if (!scrolled.ok) return terminalActionPossiblyExecuted('tmux scroll did not complete')+ return TERMINAL_ACTION_SUCCEEDED+ }+async resize(requested: TerminalStreamSize): Promise<TerminalActionResult> {return this.serializeOperation(async () => {if (this.closed) return terminalActionNotStarted('terminal stream is closed')