feat(terminal): add persistent websocket transport for low-latency input (#348)

* fix(server): resolve terminal WebSocket proxy conflict and implement server-side transport

- Disables proxy websocket handling conflict in server proxy config to fix 1006 abnormal closes.
- Implements server-side WebSocket upgrade and connection handling for terminal input.
- Adds server-side debug instrumentation for WS lifecycle events.
- Includes terminal input WS protocol definition and unit tests.

* feat(ui): implement hardened terminal WebSocket transport with idempotency and diagnostics

- Adds client-side WebSocket transport manager with automatic reconnection and jitter.
- Implements idempotency and debug instrumentation for terminal input WS.
- Adds HMR dispose cleanup for terminal WS transport manager.
- Primes terminal input transport when terminal view becomes active.
- Updates terminal session types to include input capabilities.

* refactor(terminal): remove temporary websocket debug instrumentation

packages/web/server/TERMINAL_INPUT_WS_PROTOCOL.md

@@ -0,0 +1,44 @@
+# Terminal Input WS Protocol
+
+## Goal
+Reduce terminal input latency by replacing per-keystroke HTTP requests with a persistent WebSocket input channel, while keeping SSE output and HTTP endpoints as compatibility fallback.
+
+## Scope
+- Input path: WebSocket (`/api/terminal/input-ws`)
+- Output path: SSE (`/api/terminal/:sessionId/stream`)
+- HTTP input fallback remains: `POST /api/terminal/:sessionId/input`
+
+## Framing
+- Text frame: terminal keystroke payload (hot path)
+  - Examples: `"\r"`, `"\u001b[A"`, `"\u0003"`
+- Binary frame: control envelope
+  - Byte 0: tag (`0x01` = JSON control)
+  - Bytes 1..N: UTF-8 JSON payload
+
+## Control Messages
+- Bind active socket to terminal session:
+  - client -> server: `{"t":"b","s":"<sessionId>","v":1}`
+- Keepalive ping:
+  - client -> server: `{"t":"p","v":1}`
+  - server -> client: `{"t":"po","v":1}`
+- Server control responses:
+  - ready: `{"t":"ok","v":1}`
+  - bind ok: `{"t":"bok","v":1}`
+  - error: `{"t":"e","c":"<code>","f":true|false}`
+
+## Multiplexing Model
+- Single shared socket per client runtime.
+- Socket has one mutable `boundSessionId`.
+- Client sends bind control when active terminal changes.
+- Keystroke frames apply to currently bound session.
+- Client keeps socket open and sends periodic keepalive pings so the channel stays ready for next input.
+- Client primes/opens this socket when the Terminal tab is opened (not per keystroke).
+
+## Security
+- UI auth session required when UI password is enabled.
+- Origin validation enforced for cookie-authenticated browser upgrades.
+- Invalid/malformed frames are rate-limited and may close socket.
+
+## Fallback Behavior
+- On WS unavailable/error/close, client falls back to HTTP input immediately.
+- Existing terminal behavior remains functional during mixed-version rollout.

packages/web/server/index.js

@@ -4,11 +4,22 @@ import path from 'path';
 import { spawn, spawnSync } from 'child_process';
 import fs from 'fs';
 import http from 'http';
+import { WebSocketServer } from 'ws';
 import { fileURLToPath } from 'url';
 import os from 'os';
 import crypto from 'crypto';
 import { createUiAuth } from './lib/ui-auth.js';
 import { startCloudflareTunnel, printTunnelWarning, checkCloudflaredAvailable } from './lib/cloudflare-tunnel.js';
+import {
+  TERMINAL_INPUT_WS_MAX_PAYLOAD_BYTES,
+  TERMINAL_INPUT_WS_PATH,
+  createTerminalInputWsControlFrame,
+  isRebindRateLimited,
+  normalizeTerminalInputWsMessageToText,
+  parseRequestPathname,
+  pruneRebindTimestamps,
+  readTerminalInputWsControlFrame,
+} from './lib/terminal-input-ws-protocol.js';
 import { createOpencodeServer } from '@opencode-ai/sdk/server';
 import webPush from 'web-push';
 
@@ -1437,6 +1448,96 @@ const getUiSessionTokenFromRequest = (req) => {
   return null;
 };
 
+const TERMINAL_INPUT_WS_MAX_REBINDS_PER_WINDOW = 128;
+const TERMINAL_INPUT_WS_REBIND_WINDOW_MS = 60 * 1000;
+const TERMINAL_INPUT_WS_HEARTBEAT_INTERVAL_MS = 15 * 1000;
+
+const rejectWebSocketUpgrade = (socket, statusCode, reason) => {
+  if (!socket || socket.destroyed) {
+    return;
+  }
+
+  const message = typeof reason === 'string' && reason.trim().length > 0 ? reason.trim() : 'Bad Request';
+  const body = Buffer.from(message, 'utf8');
+  const statusText = {
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+    500: 'Internal Server Error',
+  }[statusCode] || 'Bad Request';
+
+  try {
+    socket.write(
+      `HTTP/1.1 ${statusCode} ${statusText}\r\n` +
+      'Connection: close\r\n' +
+      'Content-Type: text/plain; charset=utf-8\r\n' +
+      `Content-Length: ${body.length}\r\n\r\n`
+    );
+    socket.write(body);
+  } catch {
+  }
+
+  try {
+    socket.destroy();
+  } catch {
+  }
+};
+
+
+const getRequestOriginCandidates = async (req) => {
+  const origins = new Set();
+  const forwardedProto = typeof req.headers['x-forwarded-proto'] === 'string'
+    ? req.headers['x-forwarded-proto'].split(',')[0].trim().toLowerCase()
+    : '';
+  const protocol = forwardedProto || (req.socket?.encrypted ? 'https' : 'http');
+
+  const forwardedHost = typeof req.headers['x-forwarded-host'] === 'string'
+    ? req.headers['x-forwarded-host'].split(',')[0].trim()
+    : '';
+  const host = forwardedHost || (typeof req.headers.host === 'string' ? req.headers.host.trim() : '');
+
+  if (host) {
+    origins.add(`${protocol}://${host}`);
+    const [hostname, port] = host.split(':');
+    const normalizedHost = typeof hostname === 'string' ? hostname.toLowerCase() : '';
+    const portSuffix = typeof port === 'string' && port.length > 0 ? `:${port}` : '';
+    if (normalizedHost === 'localhost') {
+      origins.add(`${protocol}://127.0.0.1${portSuffix}`);
+      origins.add(`${protocol}://[::1]${portSuffix}`);
+    } else if (normalizedHost === '127.0.0.1' || normalizedHost === '[::1]') {
+      origins.add(`${protocol}://localhost${portSuffix}`);
+    }
+  }
+
+  try {
+    const settings = await readSettingsFromDiskMigrated();
+    if (typeof settings?.publicOrigin === 'string' && settings.publicOrigin.trim().length > 0) {
+      origins.add(new URL(settings.publicOrigin.trim()).origin);
+    }
+  } catch {
+  }
+
+  return origins;
+};
+
+const isRequestOriginAllowed = async (req) => {
+  const originHeader = typeof req.headers.origin === 'string' ? req.headers.origin.trim() : '';
+  if (!originHeader) {
+    return false;
+  }
+
+  let normalizedOrigin = '';
+  try {
+    normalizedOrigin = new URL(originHeader).origin;
+  } catch {
+    return false;
+  }
+
+  const allowedOrigins = await getRequestOriginCandidates(req);
+  return allowedOrigins.has(normalizedOrigin);
+};
+
 const normalizePushSubscriptions = (record) => {
   if (!Array.isArray(record)) return [];
   return record
@@ -2028,6 +2129,7 @@ let openCodeNotReadySince = 0;
 let exitOnShutdown = true;
 let uiAuthController = null;
 let cloudflareTunnelController = null;
+let terminalInputWsServer = null;
 
 // Sync helper - call after modifying any HMR state variable
 const syncToHmrState = () => {
@@ -3855,7 +3957,7 @@ function setupProxy(app) {
 
       return suffix;
     },
-    ws: true,
+    ws: false,
     onError: (err, req, res) => {
       console.error(`Proxy error: ${err.message}`);
       if (!res.headersSent) {
@@ -3930,6 +4032,24 @@ async function gracefulShutdown(options = {}) {
     clearInterval(healthCheckInterval);
   }
 
+  if (terminalInputWsServer) {
+    try {
+      for (const client of terminalInputWsServer.clients) {
+        try {
+          client.terminate();
+        } catch {
+        }
+      }
+
+      await new Promise((resolve) => {
+        terminalInputWsServer.close(() => resolve());
+      });
+    } catch {
+    } finally {
+      terminalInputWsServer = null;
+    }
+  }
+
   // Only stop OpenCode if we started it ourselves (not when using external server)
   if (!ENV_SKIP_OPENCODE_START) {
     const portToKill = openCodePort;
@@ -8414,6 +8534,192 @@ Context:
   const terminalSessions = new Map();
   const MAX_TERMINAL_SESSIONS = 20;
   const TERMINAL_IDLE_TIMEOUT = 30 * 60 * 1000;
+  const terminalInputCapabilities = {
+    input: {
+      preferred: 'ws',
+      transports: ['http', 'ws'],
+      ws: {
+        path: TERMINAL_INPUT_WS_PATH,
+        v: 1,
+        enc: 'text+json-bin-control',
+      },
+    },
+  };
+
+  const sendTerminalInputWsControl = (socket, payload) => {
+    if (!socket || socket.readyState !== 1) {
+      return;
+    }
+
+    try {
+      socket.send(createTerminalInputWsControlFrame(payload), { binary: true });
+    } catch {
+    }
+  };
+
+  terminalInputWsServer = new WebSocketServer({
+    noServer: true,
+    maxPayload: TERMINAL_INPUT_WS_MAX_PAYLOAD_BYTES,
+  });
+
+  terminalInputWsServer.on('connection', (socket) => {
+    const connectionState = {
+      boundSessionId: null,
+      invalidFrames: 0,
+      rebindTimestamps: [],
+      lastActivityAt: Date.now(),
+    };
+
+    sendTerminalInputWsControl(socket, { t: 'ok', v: 1 });
+
+    const heartbeatInterval = setInterval(() => {
+      if (socket.readyState !== 1) {
+        return;
+      }
+
+      try {
+        socket.ping();
+      } catch {
+      }
+    }, TERMINAL_INPUT_WS_HEARTBEAT_INTERVAL_MS);
+
+    socket.on('pong', () => {
+      connectionState.lastActivityAt = Date.now();
+    });
+
+    socket.on('message', (message, isBinary) => {
+      connectionState.lastActivityAt = Date.now();
+
+      if (isBinary) {
+        const controlMessage = readTerminalInputWsControlFrame(message);
+        if (!controlMessage || typeof controlMessage.t !== 'string') {
+          connectionState.invalidFrames += 1;
+          sendTerminalInputWsControl(socket, {
+            t: 'e',
+            c: 'BAD_FRAME',
+            f: connectionState.invalidFrames >= 10,
+          });
+          if (connectionState.invalidFrames >= 10) {
+            socket.close(1008, 'protocol violation');
+          }
+          return;
+        }
+
+        if (controlMessage.t === 'p') {
+          sendTerminalInputWsControl(socket, { t: 'po', v: 1 });
+          return;
+        }
+
+        if (controlMessage.t !== 'b' || typeof controlMessage.s !== 'string') {
+          connectionState.invalidFrames += 1;
+          sendTerminalInputWsControl(socket, {
+            t: 'e',
+            c: 'BAD_FRAME',
+            f: connectionState.invalidFrames >= 10,
+          });
+          if (connectionState.invalidFrames >= 10) {
+            socket.close(1008, 'protocol violation');
+          }
+          return;
+        }
+
+        const now = Date.now();
+        connectionState.rebindTimestamps = pruneRebindTimestamps(
+          connectionState.rebindTimestamps,
+          now,
+          TERMINAL_INPUT_WS_REBIND_WINDOW_MS
+        );
+
+        if (isRebindRateLimited(connectionState.rebindTimestamps, TERMINAL_INPUT_WS_MAX_REBINDS_PER_WINDOW)) {
+          sendTerminalInputWsControl(socket, { t: 'e', c: 'RATE_LIMIT', f: false });
+          return;
+        }
+
+        const nextSessionId = controlMessage.s.trim();
+        const targetSession = terminalSessions.get(nextSessionId);
+        if (!targetSession) {
+          connectionState.boundSessionId = null;
+          sendTerminalInputWsControl(socket, { t: 'e', c: 'SESSION_NOT_FOUND', f: false });
+          return;
+        }
+
+        connectionState.rebindTimestamps.push(now);
+        connectionState.boundSessionId = nextSessionId;
+        sendTerminalInputWsControl(socket, { t: 'bok', v: 1 });
+        return;
+      }
+
+      const payload = normalizeTerminalInputWsMessageToText(message);
+      if (payload.length === 0) {
+        return;
+      }
+
+      if (!connectionState.boundSessionId) {
+        sendTerminalInputWsControl(socket, { t: 'e', c: 'NOT_BOUND', f: false });
+        return;
+      }
+
+      const session = terminalSessions.get(connectionState.boundSessionId);
+      if (!session) {
+        connectionState.boundSessionId = null;
+        sendTerminalInputWsControl(socket, { t: 'e', c: 'SESSION_NOT_FOUND', f: false });
+        return;
+      }
+
+      try {
+        session.ptyProcess.write(payload);
+        session.lastActivity = Date.now();
+      } catch {
+        sendTerminalInputWsControl(socket, { t: 'e', c: 'WRITE_FAIL', f: false });
+      }
+    });
+
+    socket.on('close', () => {
+      clearInterval(heartbeatInterval);
+    });
+
+    socket.on('error', (error) => {
+      void error;
+    });
+  });
+
+  server.on('upgrade', (req, socket, head) => {
+    const pathname = parseRequestPathname(req.url);
+    if (pathname !== TERMINAL_INPUT_WS_PATH) {
+      return;
+    }
+
+    const handleUpgrade = async () => {
+      try {
+        if (uiAuthController?.enabled) {
+          const sessionToken = uiAuthController?.ensureSessionToken?.(req, null);
+          if (!sessionToken) {
+            rejectWebSocketUpgrade(socket, 401, 'UI authentication required');
+            return;
+          }
+
+          const originAllowed = await isRequestOriginAllowed(req);
+          if (!originAllowed) {
+            rejectWebSocketUpgrade(socket, 403, 'Invalid origin');
+            return;
+          }
+        }
+
+        if (!terminalInputWsServer) {
+          rejectWebSocketUpgrade(socket, 500, 'Terminal WebSocket unavailable');
+          return;
+        }
+
+        terminalInputWsServer.handleUpgrade(req, socket, head, (ws) => {
+          terminalInputWsServer.emit('connection', ws, req);
+        });
+      } catch {
+        rejectWebSocketUpgrade(socket, 500, 'Upgrade failed');
+      }
+    };
+
+    void handleUpgrade();
+  });
 
   setInterval(() => {
     const now = Date.now();
@@ -8484,7 +8790,7 @@ Context:
       });
 
       console.log(`Created terminal session: ${sessionId} in ${cwd}`);
-      res.json({ sessionId, cols: cols || 80, rows: rows || 24 });
+      res.json({ sessionId, cols: cols || 80, rows: rows || 24, capabilities: terminalInputCapabilities });
     } catch (error) {
       console.error('Failed to create terminal session:', error);
       res.status(500).json({ error: error.message || 'Failed to create terminal session' });
@@ -8705,7 +9011,7 @@ Context:
       });
 
       console.log(`Restarted terminal session: ${sessionId} -> ${newSessionId} in ${cwd}`);
-      res.json({ sessionId: newSessionId, cols: cols || 80, rows: rows || 24 });
+      res.json({ sessionId: newSessionId, cols: cols || 80, rows: rows || 24, capabilities: terminalInputCapabilities });
     } catch (error) {
       console.error('Failed to restart terminal session:', error);
       res.status(500).json({ error: error.message || 'Failed to restart terminal session' });

packages/web/server/lib/terminal-input-ws-protocol.js

@@ -0,0 +1,66 @@
+export const TERMINAL_INPUT_WS_PATH = '/api/terminal/input-ws';
+export const TERMINAL_INPUT_WS_CONTROL_TAG_JSON = 0x01;
+export const TERMINAL_INPUT_WS_MAX_PAYLOAD_BYTES = 64 * 1024;
+
+export const parseRequestPathname = (requestUrl) => {
+  if (typeof requestUrl !== 'string' || requestUrl.length === 0) {
+    return '';
+  }
+
+  try {
+    return new URL(requestUrl, 'http://localhost').pathname;
+  } catch {
+    return '';
+  }
+};
+
+export const normalizeTerminalInputWsMessageToBuffer = (rawData) => {
+  if (Buffer.isBuffer(rawData)) {
+    return rawData;
+  }
+
+  if (Array.isArray(rawData)) {
+    return Buffer.concat(rawData.map((chunk) => (Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))));
+  }
+
+  return Buffer.from(rawData);
+};
+
+export const normalizeTerminalInputWsMessageToText = (rawData) => {
+  if (typeof rawData === 'string') {
+    return rawData;
+  }
+
+  return normalizeTerminalInputWsMessageToBuffer(rawData).toString('utf8');
+};
+
+export const readTerminalInputWsControlFrame = (rawData) => {
+  if (!rawData) {
+    return null;
+  }
+
+  const buffer = normalizeTerminalInputWsMessageToBuffer(rawData);
+  if (buffer.length < 2 || buffer[0] !== TERMINAL_INPUT_WS_CONTROL_TAG_JSON) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(buffer.subarray(1).toString('utf8'));
+    if (!parsed || typeof parsed !== 'object') {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+};
+
+export const createTerminalInputWsControlFrame = (payload) => {
+  const jsonBytes = Buffer.from(JSON.stringify(payload), 'utf8');
+  return Buffer.concat([Buffer.from([TERMINAL_INPUT_WS_CONTROL_TAG_JSON]), jsonBytes]);
+};
+
+export const pruneRebindTimestamps = (timestamps, now, windowMs) =>
+  timestamps.filter((timestamp) => now - timestamp < windowMs);
+
+export const isRebindRateLimited = (timestamps, maxPerWindow) => timestamps.length >= maxPerWindow;

packages/web/server/lib/terminal-input-ws-protocol.test.js

@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  TERMINAL_INPUT_WS_CONTROL_TAG_JSON,
+  TERMINAL_INPUT_WS_PATH,
+  createTerminalInputWsControlFrame,
+  isRebindRateLimited,
+  normalizeTerminalInputWsMessageToBuffer,
+  normalizeTerminalInputWsMessageToText,
+  parseRequestPathname,
+  pruneRebindTimestamps,
+  readTerminalInputWsControlFrame,
+} from './terminal-input-ws-protocol.js';
+
+describe('terminal input websocket protocol', () => {
+  it('uses fixed websocket path', () => {
+    expect(TERMINAL_INPUT_WS_PATH).toBe('/api/terminal/input-ws');
+  });
+
+  it('encodes control frames with control tag prefix', () => {
+    const frame = createTerminalInputWsControlFrame({ t: 'ok', v: 1 });
+    expect(frame[0]).toBe(TERMINAL_INPUT_WS_CONTROL_TAG_JSON);
+  });
+
+  it('roundtrips control frame payload', () => {
+    const payload = { t: 'b', s: 'abc123', v: 1 };
+    const frame = createTerminalInputWsControlFrame(payload);
+    expect(readTerminalInputWsControlFrame(frame)).toEqual(payload);
+  });
+
+  it('rejects control frame without protocol tag', () => {
+    const frame = Buffer.from(JSON.stringify({ t: 'b', s: 'abc123' }), 'utf8');
+    expect(readTerminalInputWsControlFrame(frame)).toBeNull();
+  });
+
+  it('rejects malformed control json', () => {
+    const frame = Buffer.concat([
+      Buffer.from([TERMINAL_INPUT_WS_CONTROL_TAG_JSON]),
+      Buffer.from('{not json', 'utf8'),
+    ]);
+    expect(readTerminalInputWsControlFrame(frame)).toBeNull();
+  });
+
+  it('rejects empty control payloads', () => {
+    expect(readTerminalInputWsControlFrame(null)).toBeNull();
+    expect(readTerminalInputWsControlFrame(undefined)).toBeNull();
+    expect(readTerminalInputWsControlFrame(Buffer.alloc(0))).toBeNull();
+  });
+
+  it('rejects control json that is not object', () => {
+    const frame = Buffer.concat([
+      Buffer.from([TERMINAL_INPUT_WS_CONTROL_TAG_JSON]),
+      Buffer.from('"str"', 'utf8'),
+    ]);
+    expect(readTerminalInputWsControlFrame(frame)).toBeNull();
+  });
+
+  it('parses control frame from chunk arrays', () => {
+    const frame = createTerminalInputWsControlFrame({ t: 'bok', v: 1 });
+    const chunks = [frame.subarray(0, 2), frame.subarray(2)];
+    expect(readTerminalInputWsControlFrame(chunks)).toEqual({ t: 'bok', v: 1 });
+  });
+
+  it('normalizes buffer passthrough', () => {
+    const raw = Buffer.from('abc', 'utf8');
+    const normalized = normalizeTerminalInputWsMessageToBuffer(raw);
+    expect(normalized).toBe(raw);
+    expect(normalized.toString('utf8')).toBe('abc');
+  });
+
+  it('normalizes uint8 arrays', () => {
+    const normalized = normalizeTerminalInputWsMessageToBuffer(new Uint8Array([97, 98, 99]));
+    expect(normalized.toString('utf8')).toBe('abc');
+  });
+
+  it('normalizes array buffer payloads', () => {
+    const source = new Uint8Array([97, 98, 99]).buffer;
+    const normalized = normalizeTerminalInputWsMessageToBuffer(source);
+    expect(normalized.toString('utf8')).toBe('abc');
+  });
+
+  it('normalizes chunk array payloads', () => {
+    const normalized = normalizeTerminalInputWsMessageToBuffer([
+      Buffer.from('ab', 'utf8'),
+      Buffer.from('c', 'utf8'),
+    ]);
+    expect(normalized.toString('utf8')).toBe('abc');
+  });
+
+  it('normalizes text payload from string', () => {
+    expect(normalizeTerminalInputWsMessageToText('\u001b[A')).toBe('\u001b[A');
+  });
+
+  it('normalizes text payload from binary data', () => {
+    expect(normalizeTerminalInputWsMessageToText(Buffer.from('\r', 'utf8'))).toBe('\r');
+  });
+
+  it('parses relative request pathname', () => {
+    expect(parseRequestPathname('/api/terminal/input-ws?x=1')).toBe('/api/terminal/input-ws');
+  });
+
+  it('parses absolute request pathname', () => {
+    expect(parseRequestPathname('http://localhost:3000/api/terminal/input-ws')).toBe('/api/terminal/input-ws');
+  });
+
+  it('returns empty pathname for non-string request url', () => {
+    expect(parseRequestPathname(null)).toBe('');
+  });
+
+  it('returns empty pathname for invalid request url', () => {
+    expect(parseRequestPathname('http://')).toBe('');
+    expect(parseRequestPathname('')).toBe('');
+  });
+
+  it('prunes stale rebind timestamps', () => {
+    const now = 1_000;
+    const pruned = pruneRebindTimestamps([100, 200, 950, 999], now, 100);
+    expect(pruned).toEqual([950, 999]);
+  });
+
+  it('keeps rebind timestamps within active window', () => {
+    const now = 1_000;
+    const pruned = pruneRebindTimestamps([920, 950, 999], now, 100);
+    expect(pruned).toEqual([920, 950, 999]);
+  });
+
+  it('does not rate limit below threshold', () => {
+    expect(isRebindRateLimited([1, 2, 3], 4)).toBe(false);
+  });
+
+  it('does not rate limit empty window', () => {
+    expect(isRebindRateLimited([], 1)).toBe(false);
+  });
+
+  it('rate limits at threshold', () => {
+    expect(isRebindRateLimited([1, 2, 3, 4], 4)).toBe(true);
+  });
+});