@thevinci/web 1.0.0

package/server/lib/event-stream/protocol.js

@@ -0,0 +1,131 @@
+export const MESSAGE_STREAM_GLOBAL_WS_PATH = '/api/global/event/ws';
+export const MESSAGE_STREAM_DIRECTORY_WS_PATH = '/api/event/ws';
+export const MESSAGE_STREAM_WS_HEARTBEAT_INTERVAL_MS = 15 * 1000;
+// Per-client pending outbound WS buffer, not a payload or stream-size limit.
+// Healthy clients stay near 0; this only trips when a client is far behind.
+// Raised from 4 MB → 16 MB to tolerate bursts during long agent sessions
+// (e.g. ultrawork / multi-tool loops) where the browser briefly falls behind.
+export const MESSAGE_STREAM_WS_MAX_BUFFERED_BYTES = 16 * 1024 * 1024;
+
+// Threshold at which we emit a backpressure warning frame so the client can
+// proactively start shedding low-priority updates before the hard disconnect.
+export const MESSAGE_STREAM_WS_BACKPRESSURE_WARN_BYTES = 12 * 1024 * 1024;
+
+export function parseSseEventEnvelope(block) {
+  if (!block || typeof block !== 'string') {
+    return null;
+  }
+
+  const eventId = block
+    .split('\n')
+    .find((line) => line.startsWith('id:'))
+    ?.slice(3)
+    .trim() || null;
+
+  const dataLines = block
+    .split('\n')
+    .filter((line) => line.startsWith('data:'))
+    .map((line) => line.slice(5).replace(/^\s/, ''));
+
+  if (dataLines.length === 0) {
+    return null;
+  }
+
+  const payloadText = dataLines.join('\n').trim();
+  if (!payloadText) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(payloadText);
+    if (
+      parsed &&
+      typeof parsed === 'object' &&
+      typeof parsed.payload === 'object' &&
+      parsed.payload !== null
+    ) {
+      return {
+        eventId,
+        directory: typeof parsed.directory === 'string' && parsed.directory.length > 0 ? parsed.directory : null,
+        payload: parsed.payload,
+      };
+    }
+
+    const directory =
+      typeof parsed?.directory === 'string' && parsed.directory.length > 0
+        ? parsed.directory
+        : typeof parsed?.properties?.directory === 'string' && parsed.properties.directory.length > 0
+          ? parsed.properties.directory
+          : null;
+
+    return {
+      eventId,
+      directory,
+      payload: parsed,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function sendMessageStreamWsFrame(socket, payload) {
+  if (!socket || socket.readyState !== 1) {
+    return false;
+  }
+
+  const buffered = typeof socket.bufferedAmount === 'number' ? socket.bufferedAmount : 0;
+
+  if (buffered > MESSAGE_STREAM_WS_MAX_BUFFERED_BYTES) {
+    try {
+      socket.close(1013, 'Message stream client is too slow');
+    } catch {
+    }
+    return false;
+  }
+
+  try {
+    socket.send(JSON.stringify(payload));
+    const bufferedAfter = typeof socket.bufferedAmount === 'number' ? socket.bufferedAmount : 0;
+    if (bufferedAfter > MESSAGE_STREAM_WS_MAX_BUFFERED_BYTES) {
+      try {
+        socket.close(1013, 'Message stream client is too slow');
+      } catch {
+      }
+      return false;
+    }
+
+    // Emit a one-shot backpressure warning when the buffer is building up.
+    // The flag prevents sending repeated warnings that would themselves
+    // increase the buffer.  It resets once the buffer drains below the
+    // threshold.
+    if (bufferedAfter > MESSAGE_STREAM_WS_BACKPRESSURE_WARN_BYTES) {
+      if (!socket._ocBackpressureWarned) {
+        socket._ocBackpressureWarned = true;
+        try {
+          socket.send(JSON.stringify({
+            type: 'backpressure',
+            bufferedBytes: bufferedAfter,
+            maxBytes: MESSAGE_STREAM_WS_MAX_BUFFERED_BYTES,
+          }));
+        } catch {
+          // Best-effort warning — ignore send failures.
+        }
+      }
+    } else if (socket._ocBackpressureWarned) {
+      socket._ocBackpressureWarned = false;
+    }
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function sendMessageStreamWsEvent(socket, payload, options = {}) {
+  return sendMessageStreamWsFrame(socket, {
+    type: 'event',
+    payload,
+    ...(typeof options.eventId === 'string' && options.eventId.length > 0 ? { eventId: options.eventId } : {}),
+    ...(typeof options.directory === 'string' && options.directory.length > 0 ? { directory: options.directory } : {}),
+  });
+}

package/server/lib/event-stream/protocol.test.js

@@ -0,0 +1,182 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  MESSAGE_STREAM_DIRECTORY_WS_PATH,
+  MESSAGE_STREAM_GLOBAL_WS_PATH,
+  MESSAGE_STREAM_WS_MAX_BUFFERED_BYTES,
+  MESSAGE_STREAM_WS_BACKPRESSURE_WARN_BYTES,
+  parseSseEventEnvelope,
+  sendMessageStreamWsEvent,
+  sendMessageStreamWsFrame,
+} from './protocol.js';
+
+describe('event stream protocol helpers', () => {
+  it('exports stable websocket paths', () => {
+    expect(MESSAGE_STREAM_GLOBAL_WS_PATH).toBe('/api/global/event/ws');
+    expect(MESSAGE_STREAM_DIRECTORY_WS_PATH).toBe('/api/event/ws');
+  });
+
+  it('parses wrapped SSE payloads with event id and directory', () => {
+    const envelope = parseSseEventEnvelope(
+      'id: evt-1\n' +
+      'event: message\n' +
+      'data: {"directory":"/tmp/project","payload":{"type":"session.updated"}}\n'
+    );
+
+    expect(envelope).toEqual({
+      eventId: 'evt-1',
+      directory: '/tmp/project',
+      payload: { type: 'session.updated' },
+    });
+  });
+
+  it('derives directory from payload properties when not wrapped', () => {
+    const envelope = parseSseEventEnvelope(
+      'data: {"type":"vinci:notification","properties":{"directory":"/tmp/project"}}\n'
+    );
+
+    expect(envelope).toEqual({
+      eventId: null,
+      directory: '/tmp/project',
+      payload: {
+        type: 'vinci:notification',
+        properties: { directory: '/tmp/project' },
+      },
+    });
+  });
+
+  it('returns null for malformed SSE blocks', () => {
+    expect(parseSseEventEnvelope('event: message\n')).toBeNull();
+    expect(parseSseEventEnvelope('data: {oops}\n')).toBeNull();
+  });
+
+  it('serializes generic websocket frames', () => {
+    let rawPayload = null;
+    const socket = {
+      readyState: 1,
+      send(payload) {
+        rawPayload = payload;
+      },
+    };
+
+    const sent = sendMessageStreamWsFrame(socket, { type: 'ready' });
+
+    expect(sent).toBe(true);
+    expect(rawPayload).toBe('{"type":"ready"}');
+  });
+
+  it('closes slow websocket clients instead of adding more buffered data', () => {
+    let closeCall = null;
+    let sendCalls = 0;
+    const socket = {
+      readyState: 1,
+      bufferedAmount: MESSAGE_STREAM_WS_MAX_BUFFERED_BYTES + 1,
+      send() {
+        sendCalls += 1;
+      },
+      close(code, reason) {
+        closeCall = { code, reason };
+      },
+    };
+
+    const sent = sendMessageStreamWsFrame(socket, { type: 'ready' });
+
+    expect(sent).toBe(false);
+    expect(sendCalls).toBe(0);
+    expect(closeCall).toEqual({
+      code: 1013,
+      reason: 'Message stream client is too slow',
+    });
+  });
+
+  it('emits a backpressure warning when buffer exceeds the warn threshold', () => {
+    const sentPayloads = [];
+    const socket = {
+      readyState: 1,
+      bufferedAmount: MESSAGE_STREAM_WS_BACKPRESSURE_WARN_BYTES + 1,
+      send(payload) {
+        sentPayloads.push(payload);
+      },
+    };
+
+    const sent = sendMessageStreamWsFrame(socket, { type: 'test' });
+
+    expect(sent).toBe(true);
+    expect(sentPayloads).toHaveLength(2);
+
+    const warning = JSON.parse(sentPayloads[1]);
+    expect(warning.type).toBe('backpressure');
+    expect(warning.bufferedBytes).toBeGreaterThan(0);
+    expect(warning.maxBytes).toBe(MESSAGE_STREAM_WS_MAX_BUFFERED_BYTES);
+  });
+
+  it('does not repeat backpressure warnings while still above threshold', () => {
+    const sentPayloads = [];
+    const socket = {
+      readyState: 1,
+      bufferedAmount: MESSAGE_STREAM_WS_BACKPRESSURE_WARN_BYTES + 1,
+      send(payload) {
+        sentPayloads.push(payload);
+      },
+    };
+
+    sendMessageStreamWsFrame(socket, { type: 'test1' });
+    sendMessageStreamWsFrame(socket, { type: 'test2' });
+
+    // First call: data + warning = 2 sends.  Second call: data only = 1 send.
+    expect(sentPayloads).toHaveLength(3);
+    expect(JSON.parse(sentPayloads[1]).type).toBe('backpressure');
+    expect(JSON.parse(sentPayloads[2])).toEqual({ type: 'test2' });
+  });
+
+  it('resets backpressure warning flag when buffer drains', () => {
+    const sentPayloads = [];
+    const socket = {
+      readyState: 1,
+      bufferedAmount: MESSAGE_STREAM_WS_BACKPRESSURE_WARN_BYTES + 1,
+      send(payload) {
+        sentPayloads.push(payload);
+      },
+    };
+
+    sendMessageStreamWsFrame(socket, { type: 'first' });
+    expect(socket._ocBackpressureWarned).toBe(true);
+
+    // Buffer drains
+    socket.bufferedAmount = 100;
+    sendMessageStreamWsFrame(socket, { type: 'recovered' });
+    expect(socket._ocBackpressureWarned).toBe(false);
+
+    // Buffer spikes again — warning should fire again
+    socket.bufferedAmount = MESSAGE_STREAM_WS_BACKPRESSURE_WARN_BYTES + 1;
+    sendMessageStreamWsFrame(socket, { type: 'again' });
+    const backpressureFrames = sentPayloads
+      .map((p) => JSON.parse(p))
+      .filter((p) => p.type === 'backpressure');
+    expect(backpressureFrames).toHaveLength(2);
+  });
+
+  it('serializes event frames with routing metadata', () => {
+    let rawPayload = null;
+    const socket = {
+      readyState: 1,
+      send(payload) {
+        rawPayload = payload;
+      },
+    };
+
+    const sent = sendMessageStreamWsEvent(
+      socket,
+      { type: 'vinci:heartbeat', timestamp: 1 },
+      { eventId: 'evt-2', directory: '/tmp/project' }
+    );
+
+    expect(sent).toBe(true);
+    expect(JSON.parse(rawPayload)).toEqual({
+      type: 'event',
+      payload: { type: 'vinci:heartbeat', timestamp: 1 },
+      eventId: 'evt-2',
+      directory: '/tmp/project',
+    });
+  });
+});

package/server/lib/event-stream/runtime.js

@@ -0,0 +1,180 @@
+import { WebSocketServer } from 'ws';
+
+import { parseRequestPathname } from '../terminal/index.js';
+import {
+  MESSAGE_STREAM_DIRECTORY_WS_PATH,
+  MESSAGE_STREAM_GLOBAL_WS_PATH,
+  MESSAGE_STREAM_WS_HEARTBEAT_INTERVAL_MS,
+  sendMessageStreamWsEvent,
+} from './protocol.js';
+import { createGlobalMessageStreamHub } from './global-hub.js';
+import { createGlobalMessageStreamWsBridge } from './global-ws-bridge.js';
+import { acceptDirectoryMessageStreamWsConnection } from './directory-ws-bridge.js';
+import {
+  DEFAULT_UPSTREAM_RECONNECT_DELAY_MS,
+  DEFAULT_UPSTREAM_STALL_TIMEOUT_MS,
+} from './upstream-reader.js';
+
+export function createGlobalUiEventBroadcaster({
+  sseClients,
+  wsClients,
+  writeSseEvent,
+}) {
+  return (payload, options = {}) => {
+    const hasSseClients = sseClients.size > 0;
+    const hasWsClients = wsClients.size > 0;
+    if (!hasSseClients && !hasWsClients) {
+      return;
+    }
+
+    if (hasSseClients) {
+      for (const res of sseClients) {
+        try {
+          writeSseEvent(res, payload);
+        } catch {
+        }
+      }
+    }
+
+    if (hasWsClients) {
+      for (const socket of Array.from(wsClients)) {
+        const sent = sendMessageStreamWsEvent(socket, payload, {
+          directory: typeof options.directory === 'string' && options.directory.length > 0 ? options.directory : 'global',
+          eventId: typeof options.eventId === 'string' && options.eventId.length > 0 ? options.eventId : undefined,
+        });
+        if (!sent) {
+          wsClients.delete(socket);
+        }
+      }
+    }
+  };
+}
+
+export function createMessageStreamWsRuntime({
+  server,
+  uiAuthController,
+  isRequestOriginAllowed,
+  rejectWebSocketUpgrade,
+  buildOpenCodeUrl,
+  getOpenCodeAuthHeaders,
+  processForwardedEventPayload,
+  wsClients,
+  triggerHealthCheck,
+  heartbeatIntervalMs = MESSAGE_STREAM_WS_HEARTBEAT_INTERVAL_MS,
+  upstreamStallTimeoutMs = DEFAULT_UPSTREAM_STALL_TIMEOUT_MS,
+  upstreamReconnectDelayMs = DEFAULT_UPSTREAM_RECONNECT_DELAY_MS,
+  fetchImpl = fetch,
+  globalEventHub = null,
+}) {
+  const wsServer = new WebSocketServer({
+    noServer: true,
+  });
+
+  const ownsGlobalHub = !globalEventHub;
+  const globalHub = globalEventHub ?? createGlobalMessageStreamHub({
+    buildOpenCodeUrl,
+    getOpenCodeAuthHeaders,
+    fetchImpl,
+    upstreamStallTimeoutMs,
+    upstreamReconnectDelayMs,
+  });
+
+  const globalBridge = createGlobalMessageStreamWsBridge({
+    globalHub,
+    ownsGlobalHub,
+    wsClients,
+    processForwardedEventPayload,
+    triggerHealthCheck,
+    heartbeatIntervalMs,
+  });
+
+  wsServer.on('connection', (socket, req) => {
+    const rawUrl = typeof req?.url === 'string' ? req.url : MESSAGE_STREAM_GLOBAL_WS_PATH;
+    const pathname = parseRequestPathname(rawUrl);
+    const requestUrl = new URL(rawUrl, 'http://127.0.0.1');
+    const isGlobalStream = pathname === MESSAGE_STREAM_GLOBAL_WS_PATH;
+    const requestedLastEventId = requestUrl.searchParams.get('lastEventId')?.trim() || '';
+    const requestedDirectory = requestUrl.searchParams.get('directory')?.trim() || '';
+
+    if (isGlobalStream) {
+      globalBridge.accept(socket, {
+        requestedLastEventId,
+      });
+      return;
+    }
+
+    acceptDirectoryMessageStreamWsConnection({
+      socket,
+      requestedLastEventId,
+      requestedDirectory,
+      buildOpenCodeUrl,
+      getOpenCodeAuthHeaders,
+      processForwardedEventPayload,
+      wsClients,
+      triggerHealthCheck,
+      heartbeatIntervalMs,
+      upstreamStallTimeoutMs,
+      upstreamReconnectDelayMs,
+      fetchImpl,
+    });
+  });
+
+  const upgradeHandler = (req, socket, head) => {
+    const pathname = parseRequestPathname(req.url);
+    if (pathname !== MESSAGE_STREAM_GLOBAL_WS_PATH && pathname !== MESSAGE_STREAM_DIRECTORY_WS_PATH) {
+      return;
+    }
+
+    const handleUpgrade = async () => {
+      try {
+        if (uiAuthController?.enabled) {
+          const sessionToken = await 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;
+          }
+        }
+
+        wsServer.handleUpgrade(req, socket, head, (ws) => {
+          wsServer.emit('connection', ws, req);
+        });
+      } catch {
+        rejectWebSocketUpgrade(socket, 500, 'Upgrade failed');
+      }
+    };
+
+    void handleUpgrade();
+  };
+
+  server.on('upgrade', upgradeHandler);
+
+  return {
+    wsServer,
+    async close() {
+      server.off('upgrade', upgradeHandler);
+      globalBridge.close();
+
+      try {
+        for (const client of wsServer.clients) {
+          try {
+            client.terminate();
+          } catch {
+          }
+        }
+
+        await new Promise((resolve) => {
+          wsServer.close(() => resolve());
+        });
+      } catch {
+      } finally {
+        wsClients.clear();
+      }
+    },
+  };
+}