@openchambery/web 1.19.22-beta.1 → 2.0.0-beta.10

package/server/lib/event-stream/DOCUMENTATION.md

@@ -33,7 +33,7 @@ The following APIs are exported by their owning modules. `event-stream/index.js`
 ### Reasoning projection helpers (`reasoning-projection.js`)
 Import from the module file (not the event-stream barrel). Public surface:
 - `shouldIncludeReasoning` / `readIncludeReasoningQuery` / `readIncludeReasoningFromUrl` / `stripIncludeReasoningParam`
-- `projectMessagesPayloadForReasoning` / `projectMessagesPayloadWithoutReasoning` — array / `{ records }` / `{ record }` / `{ parts }` only
+- `projectMessagesPayloadForReasoning` / `projectMessagesPayloadWithoutReasoning` — array / `{ records }` / `{ record }` / `{ parts }`, plus native v2 `{ data }` list/context envelopes and assistant `content[]`. Filtering preserves message identities, cursor, text/tool content and token totals.
 - `createReasoningOutboundFilter` — per-connection stream filter (version-suffix-aware type match; preserves original `type` on kept events)
 - `filterSseBlock` / `createSseBlockSplitter` — SSE disabled path (CR-safe chunk boundaries)
 
@@ -49,6 +49,8 @@ Import from the module file (not the event-stream barrel). Public surface:
 - `createUpstreamSseReader(...)`: creates a start/stop reader for OpenCode SSE streams. The reader parses SSE blocks, tracks the latest `Last-Event-ID`, reconnects after closed or stalled upstream streams, and reports events through callbacks.
 
 ## Runtime behavior
+
+Native v2 `session.reasoning.*` events are filtered at the same outbound boundary as legacy `session.next.reasoning.*`. Both `/api/session/:id/message` and `/api/session/:id/context` use the snapshot projection before relay encryption.
 - Browser clients connect to the WS endpoints above.
 - OpenChamber still fetches OpenCode upstream event streams over SSE.
 - The web server creates one shared global message-stream hub. OpenCode watcher side effects and global WS clients subscribe to that hub, so there is one upstream `/global/event` SSE reader for both server-side processing and browser fan-out.

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

@@ -21,6 +21,8 @@ export function acceptDirectoryMessageStreamWsConnection({
   buildOpenCodeUrl,
   getOpenCodeAuthHeaders,
   processForwardedEventPayload,
+  /** Optional Host archive/metadata projection for session lifecycle events. */
+  projectOutboundSessionPayload = null,
   wsClients,
   triggerHealthCheck,
   heartbeatIntervalMs,
@@ -78,14 +80,23 @@ export function acceptDirectoryMessageStreamWsConnection({
   const run = async () => {
     const forwardEvent = ({ envelope, payload }) => {
       const directory = requestedDirectory || envelope?.directory || 'global';
+      let outbound = payload;
+      if (typeof projectOutboundSessionPayload === 'function') {
+        try {
+          const projected = projectOutboundSessionPayload(payload);
+          if (projected != null) outbound = projected;
+        } catch (error) {
+          console.warn('[event-stream] directory session projection failed:', error?.message ?? error);
+        }
+      }
 
-      sendMessageStreamWsEvent(socket, payload, {
+      sendMessageStreamWsEvent(socket, outbound, {
         directory,
         eventId: typeof envelope?.eventId === 'string' && envelope.eventId.length > 0 ? envelope.eventId : undefined,
         reasoningFilter,
       });
 
-      processForwardedEventPayload(payload, (syntheticPayload) => {
+      processForwardedEventPayload(outbound, (syntheticPayload) => {
         sendMessageStreamWsEvent(socket, syntheticPayload, {
           directory: 'global',
           reasoningFilter,

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

@@ -64,6 +64,13 @@ export function createGlobalMessageStreamHub({
   upstreamReconnectDelayMs,
   replayLimit = MESSAGE_STREAM_GLOBAL_REPLAY_LIMIT,
   getRuntimeIdentity = null,
+  /**
+   * Optional Host authority projection for session.created / session.updated
+   * (and GlobalEvent wrap). Applied before fan-out and replay so browser and
+   * server subscribers share the same archive view. Must be sync and cheap.
+   * @type {((payload: unknown) => unknown) | null}
+   */
+  projectOutboundSessionPayload = null,
 }) {
   const eventSubscribers = new Set();
   const statusSubscribers = new Set();
@@ -97,12 +104,19 @@ export function createGlobalMessageStreamHub({
     }
   };
 
+  let sessionPayloadProjector = typeof projectOutboundSessionPayload === 'function'
+    ? projectOutboundSessionPayload
+    : null;
+
+  /**
+   * Diff-summarize only. Host archive projection is applied at fan-out and
+   * replayAfter time against the *current* committed store — never baked into
+   * the replay buffer (stale archive stamps must not stick after Host writes).
+   */
   const normalizeEvent = ({ envelope, payload, connectionContext }) => {
     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;
-    // Summarize FileDiff bodies before fan-out and replay buffering so reconnect
-    // replay cannot re-amplify full patch frames into >64KB WS payloads.
     const outboundPayload = summarizeOutboundEventPayload(payload);
     return {
       envelope,
@@ -113,6 +127,19 @@ export function createGlobalMessageStreamHub({
     };
   };
 
+  const projectForOutbound = (payload) => {
+    if (typeof sessionPayloadProjector !== 'function') return payload;
+    try {
+      const projected = sessionPayloadProjector(payload);
+      // null = Host not ready; suppress this lifecycle frame.
+      if (projected == null) return null;
+      return projected;
+    } catch (error) {
+      console.warn('[event-stream] session payload projection failed:', error?.message ?? error);
+      return payload;
+    }
+  };
+
   const start = () => {
     if (reader) {
       return;
@@ -127,7 +154,8 @@ export function createGlobalMessageStreamHub({
       buildUrl: () => {
         buildUrlFailed = false;
         try {
-          return new URL(buildOpenCodeUrl('/global/event', ''));
+          // v2 serves the event stream at `/api/event`; `/api/global/event` is gone.
+          return new URL(buildOpenCodeUrl('/event', ''));
         } catch {
           buildUrlFailed = true;
           throw new Error('OpenCode service unavailable');
@@ -160,6 +188,7 @@ export function createGlobalMessageStreamHub({
           ...event,
           connectionContext: event?.connectionContext ?? activeConnectionRuntimeIdentity,
         });
+        // Buffer the unprojected payload so reconnect replay uses current Host authority.
         if (normalized.eventId) {
           replay.push(normalized);
           if (replay.length > replayLimit) {
@@ -167,8 +196,14 @@ export function createGlobalMessageStreamHub({
           }
         }
 
+        const projectedPayload = projectForOutbound(normalized.payload);
+        if (projectedPayload == null) return;
+        const outbound = projectedPayload === normalized.payload
+          ? normalized
+          : { ...normalized, payload: projectedPayload };
+
         for (const subscriber of Array.from(eventSubscribers)) {
-          notifySubscriber('event', subscriber, normalized);
+          notifySubscriber('event', subscriber, outbound);
         }
       },
       onError(error) {
@@ -226,10 +261,21 @@ export function createGlobalMessageStreamHub({
       }
 
       const index = replay.findIndex((entry) => entry.eventId === eventId);
-      return index === -1 ? [] : replay.slice(index + 1);
+      if (index === -1) return [];
+      // Re-project with current committed Host authority at replay time.
+      const out = [];
+      for (const entry of replay.slice(index + 1)) {
+        const projectedPayload = projectForOutbound(entry.payload);
+        if (projectedPayload == null) continue;
+        out.push(projectedPayload === entry.payload ? entry : { ...entry, payload: projectedPayload });
+      }
+      return out;
     },
     setRuntimeIdentityProvider(provider) {
       runtimeIdentityProvider = typeof provider === 'function' ? provider : null;
     },
+    setSessionPayloadProjector(projector) {
+      sessionPayloadProjector = typeof projector === 'function' ? projector : null;
+    },
   };
 }

package/server/lib/event-stream/reasoning-projection.js

@@ -96,6 +96,10 @@ function projectParts(parts) {
  * @param {unknown} record
  */
 function projectRecord(record) {
+  if (isPlainObject(record) && record.type === 'assistant' && Array.isArray(record.content)) {
+    const content = projectParts(record.content);
+    return content === record.content ? record : { ...record, content };
+  }
   if (!isPlainObject(record) || !Array.isArray(record.parts)) return record;
   const parts = projectParts(record.parts);
   return parts === record.parts ? record : { ...record, parts };
@@ -126,6 +130,17 @@ export function projectMessagesPayloadWithoutReasoning(payload) {
   let next = payload;
   let changed = false;
 
+  if (Array.isArray(payload.data)) {
+    const data = projectMessagesPayloadWithoutReasoning(payload.data);
+    if (data !== payload.data) {
+      next = { ...next, data };
+      changed = true;
+    }
+  }
+  if (payload.type === 'assistant' && Array.isArray(payload.content)) {
+    return projectRecord(payload);
+  }
+
   if (Array.isArray(payload.records)) {
     const records = projectMessagesPayloadWithoutReasoning(payload.records);
     if (records !== payload.records) {
@@ -222,7 +237,7 @@ export function createReasoningOutboundFilter() {
     const type = baseEventType(rawType);
 
     // session.next.reasoning.* (incl. versioned …reasoning.delta.1)
-    if (type.startsWith('session.next.reasoning.')) return null;
+    if (type.startsWith('session.next.reasoning.') || type.startsWith('session.reasoning.')) return null;
 
     if (type === 'message.part.updated') {
       const body = eventBodyOf(payload);

package/server/lib/event-stream/reasoning-projection.test.js

@@ -13,6 +13,21 @@ import {
 } from './reasoning-projection.js';
 
 describe('shouldIncludeReasoning / query helpers', () => {
+  it('projects v2 list/context and exact snapshots without dropping rows or cursor', () => {
+    const row = { id: 'm', type: 'assistant', tokens: { reasoning: 12 }, content: [
+      { type: 'reasoning', text: 'hidden' }, { type: 'text', text: 'visible' },
+    ] };
+    const payload = { data: [row], cursor: { next: 'older' } };
+    const projected = projectMessagesPayloadForReasoning(payload, false);
+    expect(projected).toEqual({ data: [{ ...row, content: [row.content[1]] }], cursor: payload.cursor });
+    expect(projectMessagesPayloadForReasoning(row, false)).toEqual(projected.data[0]);
+    expect(projectMessagesPayloadForReasoning(payload, true)).toBe(payload);
+    expect(row.content).toHaveLength(2);
+    const filter = createReasoningOutboundFilter();
+    expect(filter.projectEvent({ type: 'session.reasoning.delta.1', data: { delta: 'hidden' } })).toBeNull();
+    const text = { type: 'session.text.delta', data: { delta: 'visible' } };
+    expect(filter.projectEvent(text)).toBe(text);
+  });
   it('only treats the strict string false as disabled', () => {
     expect(shouldIncludeReasoning(undefined)).toBe(true);
     expect(shouldIncludeReasoning(null)).toBe(true);

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

@@ -6,6 +6,7 @@ import {
   MESSAGE_STREAM_GLOBAL_WS_PATH,
   MESSAGE_STREAM_WS_HEARTBEAT_INTERVAL_MS,
   sendMessageStreamWsEvent,
+  sendMessageStreamWsFrame,
 } from './protocol.js';
 import { createGlobalMessageStreamHub } from './global-hub.js';
 import { createGlobalMessageStreamWsBridge } from './global-ws-bridge.js';
@@ -62,6 +63,9 @@ export function createMessageStreamWsRuntime({
   buildOpenCodeUrl,
   getOpenCodeAuthHeaders,
   processForwardedEventPayload,
+  projectOutboundSessionPayload = null,
+  /** Await Host metadata ready before directory WS attaches upstream. */
+  ensureSessionMetadataReady = null,
   wsClients,
   triggerHealthCheck,
   heartbeatIntervalMs = MESSAGE_STREAM_WS_HEARTBEAT_INTERVAL_MS,
@@ -104,29 +108,62 @@ export function createMessageStreamWsRuntime({
     const includeReasoning = shouldIncludeReasoning(requestUrl.searchParams.get('includeReasoning'));
     const reasoningFilter = includeReasoning ? null : createReasoningOutboundFilter();
 
-    if (isGlobalStream) {
-      globalBridge.accept(socket, {
+    // Host metadata readiness gates *both* global and directory streams before
+    // accept/hub.start — otherwise globalBridge.accept → hub.start bypasses the
+    // gate and lifecycle frames can fan out while the store is still unknown.
+    void (async () => {
+      if (typeof ensureSessionMetadataReady === 'function') {
+        try {
+          const ready = await ensureSessionMetadataReady();
+          if (!ready) {
+            sendMessageStreamWsFrame(socket, {
+              type: 'error',
+              message: 'session metadata is unavailable',
+              code: 'session_metadata_unavailable',
+              retryable: true,
+            });
+            socket.close(1013, 'session metadata unavailable');
+            return;
+          }
+        } catch {
+          sendMessageStreamWsFrame(socket, {
+            type: 'error',
+            message: 'session metadata is unavailable',
+            code: 'session_metadata_unavailable',
+            retryable: true,
+          });
+          socket.close(1013, 'session metadata unavailable');
+          return;
+        }
+      }
+
+      if (socket.readyState !== 1) return;
+
+      if (isGlobalStream) {
+        globalBridge.accept(socket, {
+          requestedLastEventId,
+          reasoningFilter,
+        });
+        return;
+      }
+
+      acceptDirectoryMessageStreamWsConnection({
+        socket,
         requestedLastEventId,
+        requestedDirectory,
         reasoningFilter,
+        buildOpenCodeUrl,
+        getOpenCodeAuthHeaders,
+        processForwardedEventPayload,
+        projectOutboundSessionPayload,
+        wsClients,
+        triggerHealthCheck,
+        heartbeatIntervalMs,
+        upstreamStallTimeoutMs,
+        upstreamReconnectDelayMs,
+        fetchImpl,
       });
-      return;
-    }
-
-    acceptDirectoryMessageStreamWsConnection({
-      socket,
-      requestedLastEventId,
-      requestedDirectory,
-      reasoningFilter,
-      buildOpenCodeUrl,
-      getOpenCodeAuthHeaders,
-      processForwardedEventPayload,
-      wsClients,
-      triggerHealthCheck,
-      heartbeatIntervalMs,
-      upstreamStallTimeoutMs,
-      upstreamReconnectDelayMs,
-      fetchImpl,
-    });
+    })();
   });
 
   const upgradeHandler = (req, socket, head) => {

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

@@ -126,6 +126,118 @@ describe('event stream broadcaster', () => {
   });
 });
 
+describe('message stream websocket runtime Host metadata readiness', () => {
+  it('does not accept/start global hub while metadata load is pending', async () => {
+    const server = new EventEmitter();
+    const wsClients = new Set();
+    let fetchCalls = 0;
+    let releaseReady;
+    const readyGate = new Promise((resolve) => { releaseReady = resolve; });
+
+    const runtime = createMessageStreamWsRuntime({
+      server,
+      uiAuthController: null,
+      isRequestOriginAllowed: async () => true,
+      rejectWebSocketUpgrade() {},
+      buildOpenCodeUrl: (path) => `http://127.0.0.1:4096${path}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      processForwardedEventPayload() {},
+      ensureSessionMetadataReady: async () => {
+        await readyGate;
+        return true;
+      },
+      wsClients,
+      upstreamReconnectDelayMs: 0,
+      fetchImpl: async (_url, options) => {
+        fetchCalls += 1;
+        return createSseResponse({
+          signal: options.signal,
+          holdOpen: true,
+          blocks: [
+            'id: evt-1\ndata: {"type":"session.updated","properties":{"info":{"id":"ses_1","time":{}}}}\n\n',
+          ],
+        });
+      },
+    });
+
+    const socket = new FakeSocket();
+    runtime.wsServer.emit('connection', socket, { url: '/api/global/event/ws' });
+    await new Promise((resolve) => setTimeout(resolve, 15));
+
+    // Still pending → no hub.start → no upstream fetch, no accept frames yet.
+    expect(fetchCalls).toBe(0);
+    expect(socket.closeCalls).toEqual([]);
+    expect(socket.sent.some((f) => f.type === 'event')).toBe(false);
+
+    releaseReady(true);
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    expect(fetchCalls).toBe(1);
+    expect(socket.sent.some((f) => f.type === 'event'
+      && f.payload?.type === 'session.updated')).toBe(true);
+
+    socket.close();
+    await runtime.close();
+  });
+
+  it('rejects global connection when metadata ready fails', async () => {
+    const server = new EventEmitter();
+    const runtime = createMessageStreamWsRuntime({
+      server,
+      uiAuthController: null,
+      isRequestOriginAllowed: async () => true,
+      rejectWebSocketUpgrade() {},
+      buildOpenCodeUrl: (path) => `http://127.0.0.1:4096${path}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      processForwardedEventPayload() {},
+      ensureSessionMetadataReady: async () => false,
+      wsClients: new Set(),
+      upstreamReconnectDelayMs: 0,
+      fetchImpl: async () => {
+        throw new Error('upstream must not start');
+      },
+    });
+
+    const socket = new FakeSocket();
+    runtime.wsServer.emit('connection', socket, { url: '/api/global/event/ws' });
+    await new Promise((resolve) => setTimeout(resolve, 15));
+
+    expect(socket.sent.some((f) => f.type === 'error'
+      && f.code === 'session_metadata_unavailable'
+      && f.retryable === true)).toBe(true);
+    expect(socket.closeCalls.some((c) => c.code === 1013)).toBe(true);
+
+    await runtime.close();
+  });
+
+  it('gates directory stream the same way as global', async () => {
+    const server = new EventEmitter();
+    const runtime = createMessageStreamWsRuntime({
+      server,
+      uiAuthController: null,
+      isRequestOriginAllowed: async () => true,
+      rejectWebSocketUpgrade() {},
+      buildOpenCodeUrl: (path) => `http://127.0.0.1:4096${path}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      processForwardedEventPayload() {},
+      ensureSessionMetadataReady: async () => false,
+      wsClients: new Set(),
+      upstreamReconnectDelayMs: 0,
+      fetchImpl: async () => {
+        throw new Error('upstream must not start');
+      },
+    });
+
+    const socket = new FakeSocket();
+    runtime.wsServer.emit('connection', socket, { url: '/api/event/ws?directory=/repo' });
+    await new Promise((resolve) => setTimeout(resolve, 15));
+
+    expect(socket.sent.some((f) => f.code === 'session_metadata_unavailable')).toBe(true);
+    expect(socket.closeCalls.some((c) => c.code === 1013)).toBe(true);
+    await runtime.close();
+  });
+});
+
 describe('message stream websocket runtime', () => {
   it('filters reasoning events per connection when includeReasoning=false', async () => {
     const server = new EventEmitter();