@thevinci/web 1.0.0

package/server/lib/event-stream/directory-ws-bridge.js

@@ -0,0 +1,185 @@
+import { sendMessageStreamWsEvent, sendMessageStreamWsFrame } from './protocol.js';
+import { createUpstreamSseReader } from './upstream-reader.js';
+
+function shouldTriggerUpstreamHealthCheck(upstream) {
+  if (!upstream) {
+    return true;
+  }
+
+  if (!upstream.body) {
+    return upstream.ok || upstream.status >= 500;
+  }
+
+  return upstream.status >= 500;
+}
+
+export function acceptDirectoryMessageStreamWsConnection({
+  socket,
+  requestedLastEventId,
+  requestedDirectory,
+  buildOpenCodeUrl,
+  getOpenCodeAuthHeaders,
+  processForwardedEventPayload,
+  wsClients,
+  triggerHealthCheck,
+  heartbeatIntervalMs,
+  upstreamStallTimeoutMs,
+  upstreamReconnectDelayMs,
+  fetchImpl,
+}) {
+  const controller = new AbortController();
+  let upstreamConnected = false;
+  let streamReady = false;
+  let reader = null;
+
+  const cleanup = () => {
+    if (!controller.signal.aborted) {
+      controller.abort();
+    }
+    reader?.stop();
+    wsClients.delete(socket);
+  };
+
+  const pingInterval = setInterval(() => {
+    if (socket.readyState !== 1) {
+      return;
+    }
+
+    try {
+      socket.ping();
+    } catch {
+    }
+  }, heartbeatIntervalMs);
+
+  const heartbeatInterval = setInterval(() => {
+    if (!upstreamConnected) {
+      return;
+    }
+
+    sendMessageStreamWsEvent(socket, { type: 'vinci:heartbeat', timestamp: Date.now() }, { directory: 'global' });
+  }, heartbeatIntervalMs);
+
+  socket.on('close', () => {
+    clearInterval(pingInterval);
+    clearInterval(heartbeatInterval);
+    upstreamConnected = false;
+    cleanup();
+  });
+
+  socket.on('error', () => {
+    void 0;
+  });
+
+  const run = async () => {
+    const forwardEvent = ({ envelope, payload }) => {
+      const directory = requestedDirectory || envelope?.directory || 'global';
+
+      sendMessageStreamWsEvent(socket, payload, {
+        directory,
+        eventId: typeof envelope?.eventId === 'string' && envelope.eventId.length > 0 ? envelope.eventId : undefined,
+      });
+
+      processForwardedEventPayload(payload, (syntheticPayload) => {
+        sendMessageStreamWsEvent(socket, syntheticPayload, { directory: 'global' });
+      });
+    };
+
+    try {
+      let buildUrlFailed = false;
+      const closeWithInitialError = ({ message, closeReason = message, triggerHealthCheckFor = null }) => {
+        sendMessageStreamWsFrame(socket, { type: 'error', message });
+        socket.close(1011, closeReason);
+        if (triggerHealthCheckFor === true || (triggerHealthCheckFor && shouldTriggerUpstreamHealthCheck(triggerHealthCheckFor))) {
+          triggerHealthCheck?.();
+        }
+        reader?.stop();
+        cleanup();
+      };
+
+      reader = createUpstreamSseReader({
+        initialLastEventId: requestedLastEventId,
+        signal: controller.signal,
+        stallTimeoutMs: upstreamStallTimeoutMs,
+        reconnectDelayMs: upstreamReconnectDelayMs,
+        fetchImpl,
+        buildUrl: () => {
+          buildUrlFailed = false;
+          let targetUrl;
+          try {
+            targetUrl = new URL(buildOpenCodeUrl('/event', ''));
+          } catch {
+            buildUrlFailed = true;
+            throw new Error('OpenCode service unavailable');
+          }
+
+          if (requestedDirectory) {
+            targetUrl.searchParams.set('directory', requestedDirectory);
+          }
+
+          return targetUrl;
+        },
+        getHeaders: getOpenCodeAuthHeaders,
+        onConnect() {
+          if (!streamReady) {
+            sendMessageStreamWsFrame(socket, {
+              type: 'ready',
+              scope: 'directory',
+            });
+            streamReady = true;
+          }
+
+          upstreamConnected = true;
+        },
+        onDisconnect() {
+          upstreamConnected = false;
+        },
+        onEvent: forwardEvent,
+        onError(error) {
+          if (controller.signal.aborted) {
+            return;
+          }
+
+          if (!streamReady) {
+            if (error?.type === 'upstream_unavailable') {
+              closeWithInitialError({
+                message: `OpenCode event stream unavailable (${error.status})`,
+                closeReason: 'OpenCode event stream unavailable',
+                triggerHealthCheckFor: error.response,
+              });
+              return;
+            }
+
+            closeWithInitialError({
+              message: buildUrlFailed ? 'OpenCode service unavailable' : 'Failed to connect to OpenCode event stream',
+              closeReason: buildUrlFailed ? 'OpenCode service unavailable' : 'Failed to connect to OpenCode event stream',
+              triggerHealthCheckFor: !buildUrlFailed,
+            });
+            return;
+          }
+
+          if (error?.type === 'stream_error') {
+            console.warn('Message stream WS proxy error:', error.error);
+          }
+        },
+      });
+
+      await reader.start();
+    } catch (error) {
+      if (!controller.signal.aborted) {
+        console.warn('Message stream WS proxy error:', error);
+        sendMessageStreamWsFrame(socket, { type: 'error', message: 'Message stream proxy error' });
+        socket.close(1011, 'Message stream proxy error');
+      }
+    } finally {
+      cleanup();
+      try {
+        if (socket.readyState === 1 || socket.readyState === 0) {
+          socket.close();
+        }
+      } catch {
+      }
+    }
+  };
+
+  void run();
+}

package/server/lib/event-stream/global-hub.js

@@ -0,0 +1,158 @@
+import { createUpstreamSseReader } from './upstream-reader.js';
+
+// Raised from 512 → 2048 to improve recovery after brief disconnects during
+// long-running agent sessions where many events accumulate quickly.
+export const MESSAGE_STREAM_GLOBAL_REPLAY_LIMIT = 2048;
+
+export function createGlobalMessageStreamHub({
+  buildOpenCodeUrl,
+  getOpenCodeAuthHeaders,
+  fetchImpl = fetch,
+  upstreamStallTimeoutMs,
+  upstreamReconnectDelayMs,
+  replayLimit = MESSAGE_STREAM_GLOBAL_REPLAY_LIMIT,
+}) {
+  const eventSubscribers = new Set();
+  const statusSubscribers = new Set();
+  const replay = [];
+
+  let controller = null;
+  let reader = null;
+  let connected = false;
+  let everConnected = false;
+  let buildUrlFailed = false;
+
+  const notifySubscriber = (kind, subscriber, payload) => {
+    try {
+      const result = subscriber(payload);
+      if (result && typeof result.catch === 'function') {
+        result.catch((error) => {
+          console.warn(`Global message stream ${kind} subscriber failed:`, error);
+        });
+      }
+    } catch (error) {
+      console.warn(`Global message stream ${kind} subscriber failed:`, error);
+    }
+  };
+
+  const notifyStatus = (status) => {
+    for (const subscriber of Array.from(statusSubscribers)) {
+      notifySubscriber('status', subscriber, status);
+    }
+  };
+
+  const normalizeEvent = ({ envelope, payload }) => {
+    const directory =
+      typeof envelope?.directory === 'string' && envelope.directory.length > 0 ? envelope.directory : 'global';
+    const eventId = typeof envelope?.eventId === 'string' && envelope.eventId.length > 0 ? envelope.eventId : undefined;
+    return {
+      envelope,
+      payload,
+      directory,
+      eventId,
+    };
+  };
+
+  const start = () => {
+    if (reader) {
+      return;
+    }
+
+    controller = new AbortController();
+    reader = createUpstreamSseReader({
+      signal: controller.signal,
+      stallTimeoutMs: upstreamStallTimeoutMs,
+      reconnectDelayMs: upstreamReconnectDelayMs,
+      fetchImpl,
+      buildUrl: () => {
+        buildUrlFailed = false;
+        try {
+          return new URL(buildOpenCodeUrl('/global/event', ''));
+        } catch {
+          buildUrlFailed = true;
+          throw new Error('OpenCode service unavailable');
+        }
+      },
+      getHeaders: getOpenCodeAuthHeaders,
+      onConnect() {
+        connected = true;
+        const wasReady = everConnected;
+        everConnected = true;
+        notifyStatus({ type: 'connect', wasReady });
+      },
+      onDisconnect({ reason }) {
+        connected = false;
+        notifyStatus({ type: 'disconnect', reason });
+      },
+      onEvent(event) {
+        const normalized = normalizeEvent(event);
+        if (normalized.eventId) {
+          replay.push(normalized);
+          if (replay.length > replayLimit) {
+            replay.splice(0, replay.length - replayLimit);
+          }
+        }
+
+        for (const subscriber of Array.from(eventSubscribers)) {
+          notifySubscriber('event', subscriber, normalized);
+        }
+      },
+      onError(error) {
+        if (controller?.signal.aborted) {
+          return;
+        }
+
+        notifyStatus({
+          type: everConnected ? 'error' : 'initial-error',
+          error,
+          buildUrlFailed,
+        });
+      },
+    });
+
+    void reader.start();
+  };
+
+  const stop = () => {
+    connected = false;
+    reader?.stop();
+    if (controller && !controller.signal.aborted) {
+      controller.abort();
+    }
+    reader = null;
+    controller = null;
+    everConnected = false;
+    buildUrlFailed = false;
+  };
+
+  return {
+    start,
+    stop,
+    isConnected() {
+      return connected;
+    },
+    hasConnected() {
+      return everConnected;
+    },
+    subscribeEvent(subscriber) {
+      eventSubscribers.add(subscriber);
+      return () => {
+        eventSubscribers.delete(subscriber);
+      };
+    },
+    subscribeStatus(subscriber) {
+      statusSubscribers.add(subscriber);
+      return () => {
+        statusSubscribers.delete(subscriber);
+      };
+    },
+    replayAfter(eventId) {
+      if (!eventId) {
+        return [];
+      }
+
+      const index = replay.findIndex((entry) => entry.eventId === eventId);
+      return index === -1 ? [] : replay.slice(index + 1);
+    },
+  };
+}

package/server/lib/event-stream/global-hub.test.js

@@ -0,0 +1,140 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { createGlobalMessageStreamHub } from './global-hub.js';
+
+function createSseResponse({ blocks = [] } = {}) {
+  const encoder = new TextEncoder();
+  let index = 0;
+
+  return {
+    ok: true,
+    body: {
+      getReader() {
+        return {
+          async read() {
+            if (index < blocks.length) {
+              return { value: encoder.encode(blocks[index++]), done: false };
+            }
+            return { value: undefined, done: true };
+          },
+        };
+      },
+    },
+  };
+}
+
+async function waitForAssertion(assertion) {
+  const deadline = Date.now() + 1000;
+  let lastError;
+
+  while (Date.now() < deadline) {
+    try {
+      assertion();
+      return;
+    } catch (error) {
+      lastError = error;
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+  }
+
+  throw lastError;
+}
+
+describe('createGlobalMessageStreamHub', () => {
+  it('continues fanout when an event subscriber throws', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const received = [];
+    const hub = createGlobalMessageStreamHub({
+      buildOpenCodeUrl: (pathname) => `http://127.0.0.1:4096${pathname}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      upstreamReconnectDelayMs: 100,
+      fetchImpl: async () => createSseResponse({
+        blocks: [
+          'id: evt-1\ndata: {"type":"session.updated","properties":{}}\n\n',
+        ],
+      }),
+    });
+
+    hub.subscribeEvent(() => {
+      throw new Error('subscriber failed');
+    });
+    hub.subscribeEvent((event) => {
+      received.push(event.eventId);
+    });
+
+    try {
+      hub.start();
+      await waitForAssertion(() => {
+        expect(received).toEqual(['evt-1']);
+      });
+      expect(warnSpy).toHaveBeenCalled();
+    } finally {
+      hub.stop();
+      warnSpy.mockRestore();
+    }
+  });
+
+  it('continues status fanout when a status subscriber throws', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const received = [];
+    const hub = createGlobalMessageStreamHub({
+      buildOpenCodeUrl: (pathname) => `http://127.0.0.1:4096${pathname}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      upstreamReconnectDelayMs: 100,
+      fetchImpl: async () => createSseResponse(),
+    });
+
+    hub.subscribeStatus(() => {
+      throw new Error('status subscriber failed');
+    });
+    hub.subscribeStatus((status) => {
+      received.push(status.type);
+    });
+
+    try {
+      hub.start();
+      await waitForAssertion(() => {
+        expect(received).toContain('connect');
+      });
+      expect(warnSpy).toHaveBeenCalled();
+    } finally {
+      hub.stop();
+      warnSpy.mockRestore();
+    }
+  });
+
+  it('continues fanout when an async event subscriber rejects', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const received = [];
+    const hub = createGlobalMessageStreamHub({
+      buildOpenCodeUrl: (pathname) => `http://127.0.0.1:4096${pathname}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      upstreamReconnectDelayMs: 100,
+      fetchImpl: async () => createSseResponse({
+        blocks: [
+          'id: evt-1\ndata: {"type":"session.updated","properties":{}}\n\n',
+        ],
+      }),
+    });
+
+    hub.subscribeEvent(async () => {
+      throw new Error('async subscriber failed');
+    });
+    hub.subscribeEvent((event) => {
+      received.push(event.eventId);
+    });
+
+    try {
+      hub.start();
+      await waitForAssertion(() => {
+        expect(received).toEqual(['evt-1']);
+      });
+      await waitForAssertion(() => {
+        expect(warnSpy).toHaveBeenCalled();
+      });
+    } finally {
+      hub.stop();
+      warnSpy.mockRestore();
+    }
+  });
+});

package/server/lib/event-stream/global-ws-bridge.js

@@ -0,0 +1,206 @@
+import { sendMessageStreamWsEvent, sendMessageStreamWsFrame } from './protocol.js';
+
+function shouldTriggerUpstreamHealthCheck(upstream) {
+  if (!upstream) {
+    return true;
+  }
+
+  if (!upstream.body) {
+    return upstream.ok || upstream.status >= 500;
+  }
+
+  return upstream.status >= 500;
+}
+
+export function createGlobalMessageStreamWsBridge({
+  globalHub,
+  ownsGlobalHub,
+  wsClients,
+  processForwardedEventPayload,
+  triggerHealthCheck,
+  heartbeatIntervalMs,
+}) {
+  const clients = new Set();
+  const clientLastEventIds = new Map();
+  const readyClients = new Set();
+
+  const removeClient = (socket) => {
+    clients.delete(socket);
+    clientLastEventIds.delete(socket);
+    readyClients.delete(socket);
+    wsClients.delete(socket);
+  };
+
+  const replayEvents = (socket, requestedLastEventId) => {
+    for (const entry of globalHub.replayAfter(requestedLastEventId)) {
+      const sent = sendMessageStreamWsEvent(socket, entry.payload, {
+        directory: entry.directory,
+        eventId: entry.eventId,
+      });
+      if (!sent) {
+        removeClient(socket);
+        return;
+      }
+    }
+  };
+
+  const markReady = (socket, requestedLastEventId) => {
+    if (socket.readyState !== 1) {
+      return;
+    }
+
+    const sent = sendMessageStreamWsFrame(socket, {
+      type: 'ready',
+      scope: 'global',
+    });
+    if (!sent) {
+      removeClient(socket);
+      return;
+    }
+
+    readyClients.add(socket);
+    wsClients.add(socket);
+    replayEvents(socket, requestedLastEventId);
+  };
+
+  const stopHubIfUnused = () => {
+    if (ownsGlobalHub && clients.size === 0) {
+      globalHub.stop();
+    }
+  };
+
+  const closeClientsWithInitialError = ({ message, closeReason = message, triggerHealthCheckFor = null }) => {
+    for (const socket of Array.from(clients)) {
+      sendMessageStreamWsFrame(socket, { type: 'error', message });
+      try {
+        socket.close(1011, closeReason);
+      } catch {
+      }
+      removeClient(socket);
+    }
+
+    if (triggerHealthCheckFor === true || (triggerHealthCheckFor && shouldTriggerUpstreamHealthCheck(triggerHealthCheckFor))) {
+      triggerHealthCheck?.();
+    }
+
+    if (ownsGlobalHub) {
+      globalHub.stop();
+    }
+  };
+
+  const unsubscribeEvent = globalHub.subscribeEvent(({ payload, directory, eventId }) => {
+    for (const socket of Array.from(clients)) {
+      if (!readyClients.has(socket)) {
+        continue;
+      }
+      const sent = sendMessageStreamWsEvent(socket, payload, {
+        directory,
+        eventId,
+      });
+      if (!sent) {
+        removeClient(socket);
+      }
+    }
+
+    processForwardedEventPayload(payload, (syntheticPayload) => {
+      for (const socket of Array.from(clients)) {
+        if (!readyClients.has(socket)) {
+          continue;
+        }
+        const sent = sendMessageStreamWsEvent(socket, syntheticPayload, { directory: 'global' });
+        if (!sent) {
+          removeClient(socket);
+        }
+      }
+    });
+  });
+
+  const unsubscribeStatus = globalHub.subscribeStatus((status) => {
+    if (status.type === 'connect') {
+      for (const socket of Array.from(clients)) {
+        if (!readyClients.has(socket)) {
+          markReady(socket, clientLastEventIds.get(socket) ?? '');
+        }
+      }
+      return;
+    }
+
+    if (status.type === 'initial-error') {
+      const error = status.error;
+      if (error?.type === 'upstream_unavailable') {
+        closeClientsWithInitialError({
+          message: `OpenCode event stream unavailable (${error.status})`,
+          closeReason: 'OpenCode event stream unavailable',
+          triggerHealthCheckFor: error.response,
+        });
+        return;
+      }
+
+      closeClientsWithInitialError({
+        message: status.buildUrlFailed ? 'OpenCode service unavailable' : 'Failed to connect to OpenCode event stream',
+        closeReason: status.buildUrlFailed ? 'OpenCode service unavailable' : 'Failed to connect to OpenCode event stream',
+        triggerHealthCheckFor: !status.buildUrlFailed,
+      });
+      return;
+    }
+
+    if (status.type === 'error' && status.error?.type === 'stream_error') {
+      console.warn('Message stream WS proxy error:', status.error.error);
+    }
+  });
+
+  const accept = (socket, { requestedLastEventId = '' } = {}) => {
+    const pingInterval = setInterval(() => {
+      if (socket.readyState !== 1) {
+        return;
+      }
+
+      try {
+        socket.ping();
+      } catch {
+      }
+    }, heartbeatIntervalMs);
+
+    const heartbeatInterval = setInterval(() => {
+      if (!globalHub.isConnected()) {
+        return;
+      }
+
+      sendMessageStreamWsEvent(socket, { type: 'vinci:heartbeat', timestamp: Date.now() }, { directory: 'global' });
+    }, heartbeatIntervalMs);
+
+    socket.on('close', () => {
+      clearInterval(pingInterval);
+      clearInterval(heartbeatInterval);
+      removeClient(socket);
+      stopHubIfUnused();
+    });
+
+    socket.on('error', () => {
+      void 0;
+    });
+
+    clients.add(socket);
+    clientLastEventIds.set(socket, requestedLastEventId);
+    globalHub.start();
+    if (globalHub.isConnected()) {
+      markReady(socket, requestedLastEventId);
+    }
+  };
+
+  const close = () => {
+    unsubscribeEvent();
+    unsubscribeStatus();
+    if (ownsGlobalHub) {
+      globalHub.stop();
+    }
+    for (const socket of Array.from(clients)) {
+      removeClient(socket);
+    }
+  };
+
+  return {
+    accept,
+    close,
+  };
+}

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

@@ -0,0 +1,25 @@
+export {
+  MESSAGE_STREAM_GLOBAL_WS_PATH,
+  MESSAGE_STREAM_DIRECTORY_WS_PATH,
+  MESSAGE_STREAM_WS_HEARTBEAT_INTERVAL_MS,
+  parseSseEventEnvelope,
+  sendMessageStreamWsFrame,
+  sendMessageStreamWsEvent,
+} from './protocol.js';
+
+export {
+  createGlobalUiEventBroadcaster,
+  createMessageStreamWsRuntime,
+} from './runtime.js';
+
+export {
+  MESSAGE_STREAM_GLOBAL_REPLAY_LIMIT,
+  createGlobalMessageStreamHub,
+} from './global-hub.js';
+
+export {
+  DEFAULT_UPSTREAM_RECONNECT_DELAY_MS,
+  DEFAULT_UPSTREAM_STALL_TIMEOUT_MS,
+  UPSTREAM_STALL_TIMEOUT_CONCURRENT_MS,
+  createUpstreamSseReader,
+} from './upstream-reader.js';