Files

T

Alex Blank c754984df8 feat: high-performance web terminal with asyncio-native I/O

Complete rewrite of the terminal pipeline for VS Code Server-level
responsiveness. Key improvements:

Backend:
- Replace blocking select.select(0.1) with asyncio.add_reader() for
  event-driven PTY reading (eliminates ~110ms polling latency)
- Add output batching (2ms window) to reduce WebSocket frame overhead
- Add flow control: client acks processed bytes, server pauses PTY reads
  at 64KB threshold, resumes at 32KB
- Add 5s ack timeout fallback to prevent stuck sessions

Frontend:
- Switch WebSocket to binary mode (binaryType = 'arraybuffer')
- Eliminate Blob -> arrayBuffer async conversion overhead
- Add flow control ack messages (every 4096 bytes or 100ms)
- Add xterm-addon-webgl with graceful DOM fallback
- Add performance tuning (scrollback=10000, fastScrollSensitivity)

SDD artifacts:
- openspec/explorations/terminal-responsiveness.md
- openspec/proposals/terminal-responsiveness.md
- openspec/specs/terminal-responsiveness.md
- openspec/designs/terminal-responsiveness.md
- openspec/tasks/terminal-responsiveness.md

Quality gates: pytest (19 passed, 1 skipped), tsc --noEmit clean

2026-06-02 14:40:32 +02:00

2.0 KiB

Raw Permalink Blame History

Tasks: High-Performance Web Terminal

Task 1: Rewrite TerminalSession with asyncio-native I/O

Status: pending Files: apps/api/src/services/terminal_session.py (full rewrite) Description:

Replace select.select() with asyncio.add_reader() for event-driven PTY reading
Add output batching (2ms window)
Add flow control (pause/resume based on client ack)
Keep docker exec subprocess (optimized)
Remove circular buffer (not needed with event-driven architecture)

Task 2: Update TerminalManager for new session class

Status: pending Files: apps/api/src/services/terminal_manager.py Description:

Update imports to use rewritten TerminalSession
Verify session lifecycle methods still work
Update DB persistence calls

Task 3: Update WebSocket endpoint for binary frames + flow control

Status: pending Files: apps/api/src/api/terminal.py Description:

Accept binary output frames from TerminalSession
Handle ack flow control messages from client
Send ping heartbeat
Maintain existing auth and session management

Task 4: Update frontend for binary WebSocket + WebGL

Status: pending Files: apps/web/src/components/terminal.tsx, apps/web/package.json Description:

Set ws.binaryType = "arraybuffer"
Send flow control ack messages
Add xterm-addon-webgl with DOM fallback
Optimize resize handling

Task 5: Add performance benchmarks

Status: pending Files: apps/api/tests/benchmark_terminal.py Description:

Input latency benchmark
Output throughput benchmark
Resize latency benchmark
Reconnection time benchmark

Task 6: Update/fix unit tests

Status: pending Files: apps/api/tests/unit/test_tool_instances_legacy.py, new tests Description:

Fix any tests broken by terminal changes
Add tests for new TerminalSession features

Task 7: Run full test suite

Status: pending Description:

Run all API tests
Verify no regressions
Report quality gate results

2.0 KiB Raw Permalink Blame History