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: 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.ts
index 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.ts
index 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.ts
index 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 = false
snapshots = 0
snapshotBytes = 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.ts
index 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 true
case '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.ts
index 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 = TerminalR
endSnapshot(): void
writeRaw(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.ts
index 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 = 0
private 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 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')