From 3426eb5f6f85ff7ed3ae2354ca295ff85c7ff869 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Almeida?= <57680069+zeval@users.noreply.github.com> Date: Thu, 19 Mar 2026 12:02:33 +0000 Subject: [PATCH] fix(terminal): improve keyboard navigation for macOS shortcuts (#448) --- .../agentctl/server/process/runner.go | 6 + .../gateway/websocket/terminal_handler.go | 11 +- .../components/task/passthrough-terminal.tsx | 15 +- apps/web/components/task/shell-terminal.tsx | 43 +++++ .../components/task/terminal-buffer-reader.ts | 19 ++ .../task/use-passthrough-terminal.ts | 95 ++++++---- apps/web/e2e/tests/terminal-keyboard.spec.ts | 172 ++++++++++++++++++ 7 files changed, 318 insertions(+), 43 deletions(-) create mode 100644 apps/web/components/task/terminal-buffer-reader.ts create mode 100644 apps/web/e2e/tests/terminal-keyboard.spec.ts diff --git a/apps/backend/internal/agentctl/server/process/runner.go b/apps/backend/internal/agentctl/server/process/runner.go index a9b83afa7f..c039ce2767 100644 --- a/apps/backend/internal/agentctl/server/process/runner.go +++ b/apps/backend/internal/agentctl/server/process/runner.go @@ -643,6 +643,12 @@ func mergeEnv(env map[string]string) []string { } } + // Set terminal type for xterm.js PTY connections. The parent process's TERM + // reflects its own terminal (e.g. "screen" in tmux), not the xterm.js frontend, + // so we always override it. Custom env vars (below) can still override if needed. + base["TERM"] = "xterm-256color" + base["COLORTERM"] = "truecolor" + // Override with custom variables for k, v := range env { base[k] = v diff --git a/apps/backend/internal/gateway/websocket/terminal_handler.go b/apps/backend/internal/gateway/websocket/terminal_handler.go index 50c787f283..9f6c1b7c44 100644 --- a/apps/backend/internal/gateway/websocket/terminal_handler.go +++ b/apps/backend/internal/gateway/websocket/terminal_handler.go @@ -104,6 +104,13 @@ func checkWebSocketOrigin(r *http.Request) bool { // First byte 0x01 indicates resize, followed by JSON {cols, rows}. const resizeCommandByte = 0x01 +// isResizeCommand checks whether a binary frame is a resize command. +// Resize messages use 0x01 as a prefix followed by a JSON object (starts with '{'). +// A bare 0x01 or 0x01 followed by non-JSON data is regular PTY input (e.g. Ctrl+A). +func isResizeCommand(data []byte) bool { + return len(data) >= 2 && data[0] == resizeCommandByte && data[1] == '{' +} + const ( passthroughReadyTimeout = 30 * time.Second shellExecutionTimeout = 15 * time.Second @@ -535,7 +542,7 @@ func (h *TerminalHandler) runTerminalBridge( continue } - if data[0] == resizeCommandByte { + if isResizeCommand(data) { newID, newDirect := h.handleResizeCommand(data[1:], sessionID, processID, interactiveRunner, wsw, directOutputSet, &ptyWriter) processID = newID directOutputSet = newDirect @@ -1032,7 +1039,7 @@ func (h *TerminalHandler) runUserShellBridge( continue } - if data[0] == resizeCommandByte { + if isResizeCommand(data) { directOutputSet = h.handleUserShellResizeCommand( data[1:], sessionID, terminalID, processID, interactiveRunner, wsw, directOutputSet, &ptyWriter, diff --git a/apps/web/components/task/passthrough-terminal.tsx b/apps/web/components/task/passthrough-terminal.tsx index 50cffe204c..58259cd246 100644 --- a/apps/web/components/task/passthrough-terminal.tsx +++ b/apps/web/components/task/passthrough-terminal.tsx @@ -13,12 +13,12 @@ import { useSessionAgentctl } from "@/hooks/domains/session/use-session-agentctl import { getBackendConfig } from "@/lib/config"; import { useTerminalLinkHandler } from "@/hooks/use-terminal-link-handler"; import { - log, MIN_WIDTH, MIN_HEIGHT, useTerminalInit, useWebSocketConnection, useSendResize, + useSendInput, useFitAndResize, } from "./use-passthrough-terminal"; @@ -73,15 +73,10 @@ export function PassthroughTerminal(props: PassthroughTerminalProps) { }, []); const [isTerminalReady, setIsTerminalReady] = useState(false); - const onTerminalReady = useCallback(() => { - log("Terminal ready — will trigger WebSocket connection"); - setIsTerminalReady(true); - }, []); + const onTerminalReady = useCallback(() => setIsTerminalReady(true), []); - // Track which session has an active WebSocket connection. The loading - // overlay is shown whenever the current sessionId doesn't match the - // connected one — this naturally resets on session switches without - // needing a separate effect that calls setState. + // Track which session has an active WebSocket connection. The loading overlay + // resets on session switches without needing a separate setState effect. const [connectedSessionId, setConnectedSessionId] = useState(null); const isConnected = sessionId != null && connectedSessionId === sessionId; const onConnected = useCallback(() => { @@ -99,6 +94,7 @@ export function PassthroughTerminal(props: PassthroughTerminalProps) { sendResize, }); + const sendInput = useSendInput(wsRef); const toggleBottomTerminal = useAppStore((s) => s.toggleBottomTerminal); useTerminalInit({ terminalRef, @@ -112,6 +108,7 @@ export function PassthroughTerminal(props: PassthroughTerminalProps) { onReady: onTerminalReady, linkHandler, onToggleBottomTerminal: toggleBottomTerminal, + sendInput, }); useWebSocketConnection({ diff --git a/apps/web/components/task/shell-terminal.tsx b/apps/web/components/task/shell-terminal.tsx index 17b9beadc1..f8db7104c0 100644 --- a/apps/web/components/task/shell-terminal.tsx +++ b/apps/web/components/task/shell-terminal.tsx @@ -11,6 +11,7 @@ import { useSession } from "@/hooks/domains/session/use-session"; import { useSessionAgentctl } from "@/hooks/domains/session/use-session-agentctl"; import { getTerminalTheme } from "@/lib/theme/terminal-theme"; import { useTerminalLinkHandler } from "@/hooks/use-terminal-link-handler"; +import { exposeBufferReader } from "./terminal-buffer-reader"; type ShellTerminalProps = { sessionId?: string; @@ -44,6 +45,7 @@ function useTerminalInit( convertEol: isReadOnlyMode, fontSize: isReadOnlyMode ? 12 : 13, fontFamily: 'Menlo, Monaco, "Courier New", monospace', + macOptionIsMeta: true, theme: getTerminalTheme(terminalRef.current), }); const fitAddon = new FitAddon(); @@ -51,6 +53,7 @@ function useTerminalInit( const webLinksAddon = new WebLinksAddon(linkHandler); terminal.loadAddon(webLinksAddon); terminal.open(terminalRef.current); + exposeBufferReader(terminalRef.current, terminal); fitAddon.fit(); xtermRef.current = terminal; fitAddonRef.current = fitAddon; @@ -238,6 +241,44 @@ function useTerminalOutputWrite( }, [xtermRef, shellOutput, processOutput, isReadOnlyMode, lastOutputLengthRef]); } +/** Cmd+Arrow → Home/End on macOS for the shell terminal. */ +function useCmdArrowHandler( + xtermRef: React.RefObject, + isReadOnlyMode: boolean, + sessionId: string | null | undefined, + send: (action: string, payload: Record) => void, +) { + // Use a ref so the handler (attached once) always reads the latest values + // without needing cleanup (attachCustomKeyEventHandler has no dispose). + const stateRef = useRef({ sessionId, send }); + useEffect(() => { + stateRef.current = { sessionId, send }; + }); + + const attachedRef = useRef(false); + useEffect(() => { + if (!xtermRef.current || isReadOnlyMode || !sessionId || attachedRef.current) return; + attachedRef.current = true; + xtermRef.current.attachCustomKeyEventHandler((event) => { + const { sessionId: sid, send: sendFn } = stateRef.current; + if ( + event.type === "keydown" && + event.metaKey && + !event.ctrlKey && + !event.altKey && + sid && + (event.key === "ArrowLeft" || event.key === "ArrowRight") + ) { + event.preventDefault(); + const seq = event.key === "ArrowLeft" ? "\x01" : "\x05"; + sendFn("shell.input", { session_id: sid, data: seq }); + return false; + } + return true; + }); + }, [xtermRef, sessionId, send, isReadOnlyMode, stateRef]); +} + export function ShellTerminal({ sessionId: propSessionId, processOutput, @@ -301,6 +342,8 @@ export function ShellTerminal({ onDataDisposableRef.current = null; }; }, [taskId, sessionId, send, isReadOnlyMode]); + + useCmdArrowHandler(xtermRef, isReadOnlyMode, sessionId, send); useTerminalOutputWrite(xtermRef, isReadOnlyMode, processOutput, shellOutput, lastOutputLengthRef); useShellSubscription({ diff --git a/apps/web/components/task/terminal-buffer-reader.ts b/apps/web/components/task/terminal-buffer-reader.ts new file mode 100644 index 0000000000..75b783f479 --- /dev/null +++ b/apps/web/components/task/terminal-buffer-reader.ts @@ -0,0 +1,19 @@ +import type { Terminal } from "@xterm/xterm"; + +type TerminalContainerWithBuffer = HTMLDivElement & { __xtermReadBuffer?: () => string }; + +/** Expose buffer reader on the container for e2e tests (xterm renders to canvas). */ +export function exposeBufferReader(container: HTMLDivElement, terminal: Terminal) { + (container as TerminalContainerWithBuffer).__xtermReadBuffer = () => { + const buf = terminal.buffer.active; + const lines: string[] = []; + for (let i = 0; i <= buf.baseY + buf.cursorY; i++) { + lines.push(buf.getLine(i)?.translateToString(true) ?? ""); + } + return lines.join("\n"); + }; +} + +export function clearBufferReader(container: HTMLDivElement) { + (container as TerminalContainerWithBuffer).__xtermReadBuffer = undefined; +} diff --git a/apps/web/components/task/use-passthrough-terminal.ts b/apps/web/components/task/use-passthrough-terminal.ts index 8740ddc5ec..15ece50388 100644 --- a/apps/web/components/task/use-passthrough-terminal.ts +++ b/apps/web/components/task/use-passthrough-terminal.ts @@ -9,6 +9,7 @@ import { getTerminalTheme } from "@/lib/theme/terminal-theme"; import { startReconnectLoop } from "./ws-reconnect"; import { SHORTCUTS } from "@/lib/keyboard/constants"; import { matchesShortcut } from "@/lib/keyboard/utils"; +import { exposeBufferReader, clearBufferReader } from "./terminal-buffer-reader"; // Debug flag - set to true to see detailed logs const DEBUG = false; @@ -20,20 +21,6 @@ export const log = (...args: unknown[]) => { export const MIN_WIDTH = 100; export const MIN_HEIGHT = 100; -type TerminalContainerWithBuffer = HTMLDivElement & { __xtermReadBuffer?: () => string }; - -/** Expose buffer reader on the container for e2e tests (xterm renders to canvas). */ -function exposeBufferReader(container: HTMLDivElement, terminal: Terminal) { - (container as TerminalContainerWithBuffer).__xtermReadBuffer = () => { - const buf = terminal.buffer.active; - const lines: string[] = []; - for (let i = 0; i <= buf.baseY + buf.cursorY; i++) { - lines.push(buf.getLine(i)?.translateToString(true) ?? ""); - } - return lines.join("\n"); - }; -} - export type TerminalInitOptions = { terminalRef: React.RefObject; xtermRef: React.MutableRefObject; @@ -46,6 +33,40 @@ export type TerminalInitOptions = { onReady: () => void; }; +type TerminalKeyHandlerOptions = { + onToggleBottomTerminal?: () => void; + sendInput?: (data: string) => void; +}; + +/** Handles app-level shortcuts and Cmd+Arrow→Home/End mapping for macOS. */ +function createKeyEventHandler(options: TerminalKeyHandlerOptions) { + return (event: KeyboardEvent): boolean => { + if (matchesShortcut(event, SHORTCUTS.BOTTOM_TERMINAL)) { + event.preventDefault(); + if (event.type === "keydown" && options.onToggleBottomTerminal) { + options.onToggleBottomTerminal(); + } + return false; + } + // Cmd+Arrow → beginning/end of line on macOS (same as iTerm2) + if ( + event.type === "keydown" && + event.metaKey && + !event.ctrlKey && + !event.altKey && + (event.key === "ArrowLeft" || event.key === "ArrowRight") + ) { + event.preventDefault(); + // Ctrl+A (0x01) = beginning-of-line, Ctrl+E (0x05) = end-of-line + // Works universally in bash/zsh emacs mode (the default) + const seq = event.key === "ArrowLeft" ? "\x01" : "\x05"; + options.sendInput?.(seq); + return false; + } + return true; + }; +} + function initTerminalInstance( termContainer: HTMLDivElement, refs: Pick< @@ -58,8 +79,7 @@ function initTerminalInstance( | "resizeTimeoutRef" >, fitAndResize: (force?: boolean) => void, - linkHandler?: (event: MouseEvent, uri: string) => void, - onToggleBottomTerminal?: () => void, + options: { linkHandler?: (event: MouseEvent, uri: string) => void } & TerminalKeyHandlerOptions, ) { if (refs.isInitializedRef.current || refs.xtermRef.current) return undefined; refs.isInitializedRef.current = true; @@ -73,6 +93,7 @@ function initTerminalInstance( scrollback: 5000, fontSize: 13, fontFamily: 'Menlo, Monaco, "Courier New", monospace', + macOptionIsMeta: true, theme: getTerminalTheme(termContainer), }); const fitAddon = new FitAddon(); @@ -80,18 +101,10 @@ function initTerminalInstance( const unicode11Addon = new Unicode11Addon(); terminal.loadAddon(unicode11Addon); terminal.unicode.activeVersion = "11"; - const webLinksAddon = new WebLinksAddon(linkHandler); + const webLinksAddon = new WebLinksAddon(options.linkHandler); terminal.loadAddon(webLinksAddon); terminal.open(termContainer); - // Intercept bottom terminal shortcut to toggle panel - terminal.attachCustomKeyEventHandler((event) => { - if (matchesShortcut(event, SHORTCUTS.BOTTOM_TERMINAL)) { - event.preventDefault(); - if (event.type === "keydown" && onToggleBottomTerminal) onToggleBottomTerminal(); - return false; - } - return true; - }); + terminal.attachCustomKeyEventHandler(createKeyEventHandler(options)); try { fitAddon.fit(); refs.lastDimensionsRef.current = { cols: terminal.cols, rows: terminal.rows }; @@ -143,7 +156,7 @@ function initTerminalInstance( refs.webglAddonRef.current = null; } terminal.dispose(); - (termContainer as TerminalContainerWithBuffer).__xtermReadBuffer = undefined; + clearBufferReader(termContainer); refs.xtermRef.current = null; refs.fitAddonRef.current = null; refs.isInitializedRef.current = false; @@ -151,10 +164,10 @@ function initTerminalInstance( }; } -type TerminalInitHookOptions = TerminalInitOptions & { - linkHandler?: (event: MouseEvent, uri: string) => void; - onToggleBottomTerminal?: () => void; -}; +type TerminalInitHookOptions = TerminalInitOptions & + TerminalKeyHandlerOptions & { + linkHandler?: (event: MouseEvent, uri: string) => void; + }; export function useTerminalInit({ terminalRef, @@ -168,6 +181,7 @@ export function useTerminalInit({ onReady, linkHandler, onToggleBottomTerminal, + sendInput, }: TerminalInitHookOptions) { const refs = { xtermRef, @@ -194,7 +208,11 @@ export function useTerminalInit({ const rect = container.getBoundingClientRect(); log("Init check: dimensions", rect.width, "x", rect.height); if (rect.width >= MIN_WIDTH && rect.height >= MIN_HEIGHT) { - initTerminalInstance(container, refs, fitAndResize, linkHandler, onToggleBottomTerminal); + initTerminalInstance(container, refs, fitAndResize, { + linkHandler, + onToggleBottomTerminal, + sendInput, + }); onReady(); return true; } @@ -494,6 +512,19 @@ export function useSendResize(wsRef: React.MutableRefObject) { ); } +/** Returns a stable ref whose `.current` sends raw string data to the PTY via WebSocket. */ +export function useSendInput(wsRef: React.MutableRefObject) { + return useCallback( + (data: string) => { + const ws = wsRef.current; + if (ws && ws.readyState === WebSocket.OPEN) { + ws.send(new TextEncoder().encode(data)); + } + }, + [wsRef], + ); +} + export type FitAndResizeOptions = { xtermRef: React.MutableRefObject; fitAddonRef: React.MutableRefObject; diff --git a/apps/web/e2e/tests/terminal-keyboard.spec.ts b/apps/web/e2e/tests/terminal-keyboard.spec.ts new file mode 100644 index 0000000000..c64b3084b9 --- /dev/null +++ b/apps/web/e2e/tests/terminal-keyboard.spec.ts @@ -0,0 +1,172 @@ +import { type Page } from "@playwright/test"; +import { test, expect } from "../fixtures/test-base"; +import type { SeedData } from "../fixtures/test-base"; +import type { ApiClient } from "../helpers/api-client"; +import { SessionPage } from "../pages/session-page"; + +// --------------------------------------------------------------------------- +// Helpers +// --------------------------------------------------------------------------- + +/** Create a non-TUI task and navigate to its session. Waits for agent idle. */ +async function seedTaskWithSession( + testPage: Page, + apiClient: ApiClient, + seedData: SeedData, + title: string, +): Promise { + const task = await apiClient.createTaskWithAgent( + seedData.workspaceId, + title, + seedData.agentProfileId, + { + description: "/e2e:simple-message", + workflow_id: seedData.workflowId, + workflow_step_id: seedData.startStepId, + repository_ids: [seedData.repositoryId], + }, + ); + + if (!task.session_id) throw new Error("createTaskWithAgent did not return a session_id"); + + await testPage.goto(`/s/${task.session_id}`); + const session = new SessionPage(testPage); + await session.waitForLoad(); + await expect(session.idleInput()).toBeVisible({ timeout: 30_000 }); + return session; +} + +/** Focus the terminal and wait for the shell to be ready (prompt visible). */ +async function focusTerminal(page: Page, session: SessionPage): Promise { + await expect(session.terminal).toBeVisible({ timeout: 15_000 }); + await expect + .poll( + async () => { + const buf = await readTerminalBuffer(page); + return buf.length > 0; + }, + { timeout: 15_000, message: "Waiting for terminal shell to connect" }, + ) + .toBe(true); + + const xterm = session.terminal.locator(".xterm"); + await xterm.click(); +} + +/** Read the terminal panel's xterm buffer text. */ +async function readTerminalBuffer(page: Page): Promise { + return page.evaluate(() => { + const panel = document.querySelector('[data-testid="terminal-panel"]'); + if (!panel) return ""; + const xtermEl = panel.querySelector(".xterm"); + type XC = HTMLElement & { __xtermReadBuffer?: () => string }; + const container = xtermEl?.parentElement as XC | null | undefined; + return container?.__xtermReadBuffer?.() ?? ""; + }); +} + +// --------------------------------------------------------------------------- +// Tests +// --------------------------------------------------------------------------- + +test.describe("Terminal keyboard navigation", () => { + // Standalone executor can fail on cold start; retry once for transient failures. + test.describe.configure({ retries: 1 }); + + test("TERM is set to xterm-256color", async ({ testPage, apiClient, seedData }) => { + const session = await seedTaskWithSession(testPage, apiClient, seedData, "TERM Check"); + await focusTerminal(testPage, session); + + await testPage.keyboard.type("echo $TERM"); + await testPage.keyboard.press("Enter"); + + await session.expectTerminalHasText("xterm-256color"); + }); + + test("COLORTERM is set to truecolor", async ({ testPage, apiClient, seedData }) => { + const session = await seedTaskWithSession(testPage, apiClient, seedData, "COLORTERM Check"); + await focusTerminal(testPage, session); + + await testPage.keyboard.type("echo $COLORTERM"); + await testPage.keyboard.press("Enter"); + + await session.expectTerminalHasText("truecolor"); + }); + + test("Ctrl+Arrow moves cursor between words", async ({ testPage, apiClient, seedData }) => { + const session = await seedTaskWithSession(testPage, apiClient, seedData, "CtrlArrow Test"); + await focusTerminal(testPage, session); + + // Start bash explicitly — it has Ctrl+Arrow bindings via /etc/inputrc + // (zsh without .zshrc doesn't bind Ctrl+Arrow by default) + await testPage.keyboard.type("bash --norc --noprofile"); + await testPage.keyboard.press("Enter"); + // Wait for bash prompt (bash --norc uses "bash-X.Y$ " pattern) + await expect + .poll(async () => (await readTerminalBuffer(testPage)).includes("bash"), { + timeout: 5_000, + message: "Waiting for bash prompt", + }) + .toBe(true); + + // Type a multi-word echo command (don't press Enter yet) + await testPage.keyboard.type("echo aaa bbb ccc"); + + // Ctrl+Left twice: end → start of "ccc" → start of "bbb" + await testPage.keyboard.press("Control+ArrowLeft"); + await testPage.keyboard.press("Control+ArrowLeft"); + + // Insert "X" at cursor (before "bbb") → "echo aaa Xbbb ccc" + await testPage.keyboard.type("X"); + await testPage.keyboard.press("Enter"); + + // The shell should output "aaa Xbbb ccc" + await session.expectTerminalHasText("aaa Xbbb ccc"); + }); + + test("Meta+Arrow moves cursor to start/end of line", async ({ + testPage, + apiClient, + seedData, + }) => { + const session = await seedTaskWithSession(testPage, apiClient, seedData, "MetaArrow Test"); + await focusTerminal(testPage, session); + + // Start bash for a clean prompt + await testPage.keyboard.type("bash --norc --noprofile"); + await testPage.keyboard.press("Enter"); + await expect + .poll(async () => (await readTerminalBuffer(testPage)).includes("bash"), { + timeout: 5_000, + message: "Waiting for bash prompt", + }) + .toBe(true); + + // Type text without "echo " prefix (just raw text, not a valid command) + await testPage.keyboard.type("aaa bbb ccc"); + + // Meta+Left → Home (cursor moves to start of line, sends Ctrl+A) + await testPage.keyboard.press("Meta+ArrowLeft"); + + // Type "echo " at the beginning → line becomes "echo aaa bbb ccc" + await testPage.keyboard.type("echo "); + await testPage.keyboard.press("Enter"); + + // If Home worked, "echo " was inserted at the start and output is "aaa bbb ccc". + // If Home failed, "echo " was appended and the command would fail. + // Use a unique marker in the output to avoid matching the typed command itself. + await expect + .poll( + async () => { + const buf = await readTerminalBuffer(testPage); + // Find lines that contain "aaa bbb ccc" but NOT "echo" (output lines, not command lines) + const lines = buf.split("\n"); + return lines.some( + (line) => line.includes("aaa bbb ccc") && !line.includes("echo") && !line.includes("$"), + ); + }, + { timeout: 10_000, message: "Expected output line with 'aaa bbb ccc'" }, + ) + .toBe(true); + }); +});