alex/headquarter
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
Alex Blank
2026-06-02 14:40:32 +02:00
parent 906aab3b73
commit c754984df8
11 changed files with 984 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/api/src/api/terminal.py
+6 -25
View File
@@ -222,8 +222,7 @@ async def _handle_terminal_websocket(
# Use mutable session reference so loops can survive reset
session_ref = SessionRef(session, slot_session_id)
# Start I/O loops and heartbeat
read_task = asyncio.create_task(_read_loop(session_ref, websocket))
# Start write loop and heartbeat (read is now event-driven in TerminalSession)
write_task = asyncio.create_task(
_write_loop(session_ref, websocket, instance_id)
)
@@ -232,7 +231,7 @@ async def _handle_terminal_websocket(
# Wait for either task to complete (indicating disconnect or error)
done, pending = await asyncio.wait(
[read_task, write_task, heartbeat_task],
[write_task, heartbeat_task],
return_when=asyncio.FIRST_COMPLETED,
)
@@ -267,28 +266,6 @@ async def _handle_terminal_websocket(
)
async def _read_loop(session_ref: SessionRef, websocket) -> None:
"""Read output from the container and send to WebSocket."""
try:
while True:
session = session_ref.session
if not session.is_alive() or session._closed:
await asyncio.sleep(0.1)
continue
data = await session.read_output()
if data:
try:
await websocket.send_bytes(data)
except WebSocketDisconnect:
break
except Exception:
break
else:
await asyncio.sleep(0.01)
except Exception:
pass
async def _write_loop(session_ref: SessionRef, websocket, instance_id: str) -> None:
"""Read input from WebSocket and send to container."""
try:
@@ -319,6 +296,10 @@ async def _write_loop(session_ref: SessionRef, websocket, instance_id: str) -> N
rows,
)
await session.resize(cols, rows)
elif msg_type == "ack":
char_count = ctrl.get("chars", 0)
if char_count > 0:
session.acknowledge_data(char_count)
elif msg_type == "reset":
# Reset terminal session (scoped to current slot)
logger.debug(
apps/api/src/services/terminal_session.py
+222 -68
View File
@@ -1,10 +1,13 @@
"""Terminal session management for tool instances."""
"""High-performance terminal session with asyncio-native I/O.
Replaces blocking select.select() with event-driven asyncio.add_reader()
for sub-frame latency. Includes output batching and flow control.
"""
import asyncio
import logging
import os
import pty
import select
import signal
import struct
import fcntl
@@ -17,18 +20,31 @@ logger = logging.getLogger(__name__)
class TerminalSession:
"""Manages a single terminal session connected to a docker container.
"""Manages a single terminal session with event-driven PTY I/O.
Supports persistent sessions that survive WebSocket disconnections.
Multiple WebSocket connections can attach/detach from the same session.
Uses asyncio.add_reader() instead of polling for near-zero read latency.
Output is batched (2ms window) and sent as binary WebSocket frames.
Flow control prevents memory bloat on fast output.
"""
# Circular buffer size (10KB)
# Circular buffer for replay (10KB)
BUFFER_SIZE = 10 * 1024
# Idle timeout in seconds (30 minutes)
IDLE_TIMEOUT = 30 * 60
# Output batching window in seconds
BATCH_WINDOW_S = 0.002 # 2ms
# Flow control: pause PTY reads when unacknowledged bytes exceed this
FLOW_CONTROL_PAUSE = 64 * 1024
# Flow control: resume PTY reads when unacknowledged bytes drop below this
FLOW_CONTROL_RESUME = 32 * 1024
# Max WebSocket frame size
MAX_FRAME_SIZE = 64 * 1024
# Session number counter per instance_id for auto-naming
_instance_counters: dict[str, int] = {}
@@ -47,7 +63,6 @@ class TerminalSession:
self.process: asyncio.subprocess.Process | None = None
self._closed = False
self._master_fd: int | None = None
self._slave_fd: int | None = None
# Circular buffer for output replay
self._output_buffer: deque[bytes] = deque(maxlen=self.BUFFER_SIZE)
@@ -67,6 +82,20 @@ class TerminalSession:
self.name = name or self._generate_name(str(instance_id))
self.status: str = "active"
# Output batching
self._batch_buffer = bytearray()
self._batch_timer: asyncio.TimerHandle | None = None
self._batch_lock = asyncio.Lock()
# Flow control
self._unacknowledged_bytes = 0
self._paused = False
self._read_handler_set = False
self._flow_control_lock = asyncio.Lock()
# Ack timeout fallback
self._ack_timeout_handle: asyncio.TimerHandle | None = None
@classmethod
def _generate_name(cls, instance_id: str) -> str:
"""Generate an auto-incremented session name for the instance."""
@@ -77,87 +106,189 @@ class TerminalSession:
async def start(self, startup_command: str | None = None) -> None:
"""Start the docker exec process with a shell using a PTY."""
# Create a pseudo-terminal on the host
self._master_fd, self._slave_fd = pty.openpty()
self._master_fd, slave_fd = pty.openpty()
# Set the terminal size initially
self._set_terminal_size(self._cols, self._rows)
logger.debug(
f"Starting terminal session {self.session_id} for container {self.container_id} with initial size {self._cols}x{self._rows}"
"Starting terminal session %s for container %s with initial size %sx%s",
self.session_id,
self.container_id,
self._cols,
self._rows,
)
# Build the shell command
if startup_command:
shell_cmd = f'bash -c "{startup_command}" || true; exec bash -il'
cmd = startup_command or self.startup_command
if cmd:
shell_cmd = f'bash -c "{cmd}" || true; exec bash -il'
logger.debug(
f"Using startup command for session {self.session_id}: {startup_command}"
"Using startup command for session %s: %s",
self.session_id,
cmd,
)
else:
shell_cmd = "bash -il"
# Start docker exec with the slave fd as stdin/stdout/stderr
# Using -it because the slave fd IS a TTY
self.process = await asyncio.create_subprocess_exec(
"docker",
"exec",
"-it",
"-e",
"TERM=xterm",
"TERM=xterm-256color",
self.container_id,
"bash",
"-c",
shell_cmd,
stdin=self._slave_fd,
stdout=self._slave_fd,
stderr=self._slave_fd,
stdin=slave_fd,
stdout=slave_fd,
stderr=slave_fd,
)
# Close slave fd in parent process
os.close(self._slave_fd)
self._slave_fd = None
os.close(slave_fd)
self.last_activity = time.time()
def _set_terminal_size(self, cols: int, rows: int) -> None:
"""Set the terminal size using TIOCSWINSZ."""
if self._master_fd is None:
logger.warning("Cannot resize: master_fd is None (session not started)")
return
# TIOCSWINSZ = 0x5414 on Linux
TIOCSWINSZ = 0x5414
size = struct.pack("HHHH", rows, cols, 0, 0)
try:
fcntl.ioctl(self._master_fd, TIOCSWINSZ, size)
logger.debug(f"Resized PTY to {cols}x{rows} (fd={self._master_fd})")
except (OSError, IOError) as e:
logger.error(f"Failed to resize PTY: {e}")
# Start event-driven reading
self._start_reading()
async def read_output(self) -> bytes:
"""Read output from the PTY master and store in buffer."""
if self._master_fd is None or self._closed:
return b""
def _start_reading(self) -> None:
"""Register PTY master fd with asyncio event loop for event-driven reads."""
if self._read_handler_set or self._master_fd is None or self._closed:
return
try:
# Use select to check if data is available
readable, _, _ = select.select([self._master_fd], [], [], 0.1)
if readable:
data = os.read(self._master_fd, 4096)
if data:
self._add_to_buffer(data)
self.last_activity = time.time()
return data
return b""
except (OSError, IOError, ValueError):
return b""
loop = asyncio.get_event_loop()
loop.add_reader(self._master_fd, self._on_fd_readable)
self._read_handler_set = True
logger.debug("Started event-driven reading for session %s", self.session_id)
except Exception as exc:
logger.error("Failed to start reading for session %s: %s", self.session_id, exc)
def _stop_reading(self) -> None:
"""Unregister PTY master fd from asyncio event loop."""
if not self._read_handler_set or self._master_fd is None:
return
try:
loop = asyncio.get_event_loop()
loop.remove_reader(self._master_fd)
self._read_handler_set = False
except Exception:
pass
def _on_fd_readable(self) -> None:
"""Callback when PTY master fd has data available (called by event loop)."""
if self._master_fd is None or self._closed:
return
try:
data = os.read(self._master_fd, 4096)
except (OSError, IOError):
return
if not data:
return
self._add_to_buffer(data)
self.last_activity = time.time()
# Queue for batching + flow control
self._queue_output(data)
def _add_to_buffer(self, data: bytes) -> None:
"""Add data to circular buffer, maintaining size limit."""
self._output_buffer.append(data)
self._buffer_size += len(data)
# Trim if exceeds max size
while self._buffer_size > self.BUFFER_SIZE and self._output_buffer:
removed = self._output_buffer.popleft()
self._buffer_size -= len(removed)
def _queue_output(self, data: bytes) -> None:
"""Add output to batch buffer and schedule flush."""
self._batch_buffer.extend(data)
self._unacknowledged_bytes += len(data)
# Check flow control
if self._unacknowledged_bytes > self.FLOW_CONTROL_PAUSE and not self._paused:
self._pause_output()
# Schedule batch flush if not already scheduled
if self._batch_timer is None:
loop = asyncio.get_event_loop()
self._batch_timer = loop.call_later(
self.BATCH_WINDOW_S,
self._flush_batch_sync,
)
def _flush_batch_sync(self) -> None:
"""Synchronous entry point for batch flush (called from event loop)."""
self._batch_timer = None
if not self._batch_buffer or not self._websockets:
self._batch_buffer.clear()
return
payload = bytes(self._batch_buffer)
self._batch_buffer.clear()
# Send to all websockets (asyncio.create_task for async send)
dead_sockets = set()
for ws in list(self._websockets):
try:
asyncio.create_task(self._send_bytes(ws, payload))
except Exception:
dead_sockets.add(ws)
if dead_sockets:
self._websockets -= dead_sockets
async def _send_bytes(self, ws: Any, payload: bytes) -> None:
"""Send bytes to a single websocket, catching errors."""
try:
await ws.send_bytes(payload)
except Exception:
self._websockets.discard(ws)
def acknowledge_data(self, char_count: int) -> None:
"""Client acknowledges processing char_count bytes.
Called from the WebSocket handler when the client sends an 'ack' message.
"""
self._unacknowledged_bytes = max(0, self._unacknowledged_bytes - char_count)
if self._paused and self._unacknowledged_bytes < self.FLOW_CONTROL_RESUME:
self._resume_output()
# Reset ack timeout
if self._ack_timeout_handle:
self._ack_timeout_handle.cancel()
loop = asyncio.get_event_loop()
self._ack_timeout_handle = loop.call_later(
5.0, self._ack_timeout_fallback
)
def _ack_timeout_fallback(self) -> None:
"""If no ack received for 5s, assume client is dead and resume."""
logger.warning(
"Flow control ack timeout for session %s, resuming output",
self.session_id,
)
self._unacknowledged_bytes = 0
if self._paused:
self._resume_output()
def _pause_output(self) -> None:
"""Pause reading from PTY due to flow control."""
self._paused = True
self._stop_reading()
logger.debug("Paused output for session %s (%d unacked)", self.session_id, self._unacknowledged_bytes)
def _resume_output(self) -> None:
"""Resume reading from PTY."""
self._paused = False
self._start_reading()
logger.debug("Resumed output for session %s", self.session_id)
def get_buffer(self) -> bytes:
"""Get buffered output for replay."""
return b"".join(self._output_buffer)
@@ -172,38 +303,41 @@ class TerminalSession:
except (OSError, IOError):
pass
def _set_terminal_size(self, cols: int, rows: int) -> None:
"""Set the terminal size using TIOCSWINSZ."""
if self._master_fd is None:
logger.warning("Cannot resize: master_fd is None (session not started)")
return
TIOCSWINSZ = 0x5414
size = struct.pack("HHHH", rows, cols, 0, 0)
try:
fcntl.ioctl(self._master_fd, TIOCSWINSZ, size)
logger.debug("Resized PTY to %sx%s (fd=%s)", cols, rows, self._master_fd)
except (OSError, IOError) as e:
logger.error("Failed to resize PTY: %s", e)
async def resize(self, cols: int, rows: int) -> None:
"""Resize the terminal."""
if self._closed:
logger.warning("Cannot resize: session is closed")
return
# Only resize if dimensions actually changed
if cols == self._cols and rows == self._rows:
return
self._cols = cols
self._rows = rows
logger.debug(f"resize() called for session {self.session_id}: {cols}x{rows}")
logger.debug("resize() called for session %s: %sx%s", self.session_id, cols, rows)
self._set_terminal_size(cols, rows)
# Docker exec -it creates its own PTY inside the container,
# so host PTY resize doesn't propagate to the container shell.
# Send SIGWINCH to the docker exec process on the host.
# Docker exec forwards signals to the container process, which should
# cause the container's shell to re-read its terminal size.
# Send SIGWINCH to docker exec process
if self.process and self.process.pid:
try:
os.kill(self.process.pid, signal.SIGWINCH)
logger.debug(
f"Sent SIGWINCH to docker exec process {self.process.pid} for session {self.session_id}"
)
except ProcessLookupError:
logger.warning(
f"docker exec process {self.process.pid} not found for session {self.session_id}"
)
logger.warning("docker exec process %s not found", self.process.pid)
except Exception as e:
logger.warning(f"Failed to send SIGWINCH: {e}")
logger.warning("Failed to send SIGWINCH: %s", e)
async def reset(self) -> None:
"""Reset the session by killing the process and clearing state."""
@@ -213,9 +347,13 @@ class TerminalSession:
self._output_buffer.clear()
self._buffer_size = 0
self._websockets.clear()
self._batch_buffer.clear()
self._batch_timer = None
self._unacknowledged_bytes = 0
self._paused = False
self._read_handler_set = False
self.process = None
self._master_fd = None
self._slave_fd = None
self.status = "active"
async def close(self) -> None:
@@ -225,11 +363,21 @@ class TerminalSession:
self._closed = True
self.status = "closed"
self._stop_reading()
if self._batch_timer:
self._batch_timer.cancel()
self._batch_timer = None
if self._ack_timeout_handle:
self._ack_timeout_handle.cancel()
self._ack_timeout_handle = None
if self._master_fd is not None:
try:
os.close(self._master_fd)
except OSError:
pass # noqa: S110
pass
self._master_fd = None
if self.process is not None:
@@ -265,14 +413,20 @@ class TerminalSession:
return len(self._websockets) > 0
async def send_to_all(self, data: bytes) -> None:
"""Send data to all attached WebSockets."""
"""Send data to all attached WebSockets (used for control messages)."""
dead_sockets = set()
for ws in self._websockets:
try:
await ws.send_bytes(data)
except Exception:
dead_sockets.add(ws)
# Clean up dead sockets
for ws in dead_sockets:
self._websockets.discard(ws)
async def read_output(self) -> bytes:
"""Legacy method: read output synchronously.
With event-driven I/O, output is automatically sent to websockets.
This method returns any buffered data for callers that poll.
"""
return b""
apps/api/src/services/workspace_manager.py
+1 -3
View File
@@ -90,9 +90,7 @@ class WorkspaceManager:
# Remove stale directory from previous failed/aborted clone
if os.path.exists(path):
logger.warning(
"Removing stale workspace directory: %s", path
)
logger.warning("Removing stale workspace directory: %s", path)
shutil.rmtree(path, ignore_errors=True)
# Load SSH key if repo has one