@vantran-se/openchamber-web 1.24.4 → 2.0.2

package/server/lib/event-stream/translate-v2.js

@@ -0,0 +1,313 @@
+/**
+ * OpenCode v2 wire events -> the vocabulary the server's own consumers speak.
+ *
+ * The browser gets raw wire payloads (the UI translates them itself in
+ * `packages/ui/src/lib/opencode/events.ts`). Everything that reacts on the
+ * server — notifications, the message queue, session activity, goal mode,
+ * permission auto-accept, Linear status — was written against OpenCode v1
+ * event names, so this module is the single place that maps v2 onto them.
+ * Keeping one translator means a consumer never has to know which OpenCode
+ * shape produced its event.
+ *
+ * Two differences from v1 are load-bearing and cannot be papered over:
+ *
+ * - v2 emits no `session.status` and no `session.idle` of its own. Live status
+ *   comes from `session.execution.started|succeeded|interrupted|failed`, so
+ *   those are what synthesize the status vocabulary here.
+ * - a v2 turn is a sequence of steps. Each `session.step.ended` becomes an
+ *   assistant `message.updated`; only the last one carries `finish: "stop"`,
+ *   which is the same signal v1 gave once per turn.
+ */
+
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const trimmed = (value) => (typeof value === 'string' ? value.trim() : '');
+
+const compact = (value) => {
+  const result = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (entry !== undefined) result[key] = entry;
+  }
+  return result;
+};
+
+/** Directory an event belongs to. Execution events carry no location. */
+export const wireEventDirectory = (payload) => {
+  if (!isRecord(payload)) return '';
+  return trimmed(payload.location?.directory);
+};
+
+/** Structured errors travel as `{ type, message }`; consumers still read `name`. */
+const toServerError = (error) => {
+  if (!isRecord(error)) return { name: 'Error', type: 'Error', message: typeof error === 'string' ? error : '' };
+  const type = trimmed(error.type) || 'Error';
+  return compact({ name: type, type, message: trimmed(error.message), status: error.status });
+};
+
+const ABORTED_ERROR = {
+  name: 'MessageAbortedError',
+  type: 'MessageAbortedError',
+  message: 'The running turn was interrupted.',
+};
+
+/**
+ * Translates one v2 wire payload into zero or more server-vocabulary events.
+ *
+ * Every returned event carries the source event id and the directory, because
+ * consumers deduplicate on the id and route their own OpenCode calls by
+ * directory.
+ */
+export function translateWireEvent(payload) {
+  if (!isRecord(payload)) return [];
+  const type = trimmed(payload.type);
+  if (!type) return [];
+  const data = isRecord(payload.data) ? payload.data : {};
+  const directory = wireEventDirectory(payload);
+  const created = Number.isFinite(payload.created) ? payload.created : Date.now();
+
+  const event = (outType, properties) => ({
+    type: outType,
+    id: typeof payload.id === 'string' ? payload.id : '',
+    created,
+    properties: compact({ ...properties, directory: directory || undefined }),
+  });
+
+  const sessionID = trimmed(data.sessionID);
+
+  const status = (statusValue) => event('session.status', { sessionID, status: statusValue });
+
+  switch (type) {
+    case 'server.connected':
+      return [event('server.connected', {})];
+
+    case 'installation.update-available':
+      return [event('installation.update-available', { version: trimmed(data.version) })];
+
+    // --- session lifecycle --------------------------------------------------
+
+    case 'session.created': {
+      if (!sessionID) return [];
+      const location = isRecord(data.location) ? data.location : {};
+      return [event('session.created', {
+        sessionID,
+        info: compact({
+          id: sessionID,
+          parentID: trimmed(data.parentID) || undefined,
+          projectID: trimmed(data.projectID) || undefined,
+          directory: trimmed(location.directory) || directory || undefined,
+          title: typeof data.title === 'string' ? data.title : undefined,
+          agent: trimmed(data.agent) || undefined,
+          model: data.model,
+          metadata: data.metadata,
+          permissions: data.permissions,
+          time: { created, updated: created },
+        }),
+      })];
+    }
+
+    case 'session.renamed':
+      if (!sessionID) return [];
+      return [event('session.updated', {
+        sessionID,
+        info: compact({ id: sessionID, title: typeof data.title === 'string' ? data.title : undefined, directory: directory || undefined, time: { updated: created } }),
+      })];
+
+    case 'session.moved': {
+      if (!sessionID) return [];
+      const location = isRecord(data.location) ? data.location : {};
+      return [event('session.updated', {
+        sessionID,
+        info: compact({ id: sessionID, directory: trimmed(location.directory) || undefined, projectID: trimmed(data.projectID) || undefined, time: { updated: created } }),
+      })];
+    }
+
+    case 'session.usage.updated':
+      if (!sessionID) return [];
+      return [event('session.updated', {
+        sessionID,
+        info: compact({ id: sessionID, directory: directory || undefined, cost: data.cost, tokens: data.tokens, time: { updated: created } }),
+      })];
+
+    case 'session.deleted':
+      if (!sessionID) return [];
+      return [event('session.deleted', { sessionID, info: { id: sessionID } })];
+
+    // --- live status --------------------------------------------------------
+
+    // v2 still declares `session.status` and `session.idle`; a 2.0.2 server was
+    // observed never to emit them, so the execution events below are what
+    // actually drive status. Both paths are translated so a server that does
+    // emit them stays correct.
+    case 'session.status':
+      if (!sessionID || !isRecord(data.status)) return [];
+      return [status(data.status)];
+
+    case 'session.idle':
+      if (!sessionID) return [];
+      return [status({ type: 'idle' }), event('session.idle', { sessionID })];
+
+    case 'session.execution.started':
+      if (!sessionID) return [];
+      return [status({ type: 'busy' })];
+
+    case 'session.execution.succeeded':
+      if (!sessionID) return [];
+      return [status({ type: 'idle' }), event('session.idle', { sessionID })];
+
+    case 'session.execution.interrupted': {
+      if (!sessionID) return [];
+      const reason = trimmed(data.reason) || 'user';
+      // A shutdown is not the end of the turn: OpenCode keeps the execution
+      // claim and the resumed drain continues the same turn after restart
+      // (v2.0.14 `session/execution.ts` settled(), `projector.ts` projectIdle,
+      // `message-updater.ts`), and none of its own projections mark the
+      // session idle. Reporting it as an abort would make the goal runtime
+      // pause the goal as a user stop and the queue hold the next prompt, so
+      // it produces nothing: the session stays busy until OpenCode resumes it
+      // and reports the real terminal outcome.
+      if (reason === 'shutdown') return [];
+      // Every other interruption ends the turn without failing it: consumers
+      // that treat `session.error` as a failure must not fire, but the queue
+      // and goal runtimes still have to know the turn was aborted.
+      return [
+        status({ type: 'idle' }),
+        event('session.idle', { sessionID, aborted: true, reason, error: ABORTED_ERROR }),
+      ];
+    }
+
+    case 'session.execution.failed':
+      if (!sessionID) return [];
+      return [status({ type: 'idle' }), event('session.error', { sessionID, error: toServerError(data.error) })];
+
+    // --- messages -----------------------------------------------------------
+
+    case 'session.inbox.enqueued': {
+      const item = isRecord(data.item) ? data.item : {};
+      const messageID = trimmed(data.inboxID);
+      if (!sessionID || !messageID) return [];
+      const itemPayload = isRecord(item.payload) ? item.payload : {};
+      if (item.type === 'user') {
+        const text = typeof itemPayload.text === 'string' ? itemPayload.text : '';
+        return [event('message.updated', {
+          sessionID,
+          info: compact({
+            id: messageID,
+            sessionID,
+            role: 'user',
+            text,
+            parts: text ? [{ type: 'text', text }] : [],
+            metadata: itemPayload.metadata,
+            time: { created },
+          }),
+          parts: text ? [{ type: 'text', text }] : [],
+        })];
+      }
+      return [];
+    }
+
+    case 'session.step.started': {
+      const messageID = trimmed(data.assistantMessageID);
+      if (!sessionID || !messageID) return [];
+      const model = isRecord(data.model) ? data.model : {};
+      return [event('message.updated', {
+        sessionID,
+        info: compact({
+          id: messageID,
+          sessionID,
+          role: 'assistant',
+          agent: trimmed(data.agent) || undefined,
+          providerID: trimmed(model.providerID) || undefined,
+          modelID: trimmed(model.id) || undefined,
+          time: { created },
+        }),
+      })];
+    }
+
+    case 'session.step.ended': {
+      const messageID = trimmed(data.assistantMessageID);
+      if (!sessionID || !messageID) return [];
+      return [event('message.updated', {
+        sessionID,
+        info: compact({
+          id: messageID,
+          sessionID,
+          role: 'assistant',
+          finish: trimmed(data.finish) || undefined,
+          cost: data.cost,
+          tokens: data.tokens,
+          time: { completed: created },
+        }),
+      })];
+    }
+
+    case 'session.step.failed': {
+      const messageID = trimmed(data.assistantMessageID);
+      if (!sessionID || !messageID) return [];
+      return [event('message.updated', {
+        sessionID,
+        info: compact({
+          id: messageID,
+          sessionID,
+          role: 'assistant',
+          finish: trimmed(data.finish) || 'error',
+          error: toServerError(data.error),
+          cost: data.cost,
+          tokens: data.tokens,
+          time: { completed: created },
+        }),
+      })];
+    }
+
+    // --- requests to the user -------------------------------------------------
+
+    case 'permission.asked': {
+      const requestID = trimmed(data.id);
+      if (!requestID || !sessionID) return [];
+      return [event('permission.asked', compact({
+        id: requestID,
+        sessionID,
+        action: trimmed(data.action),
+        resources: Array.isArray(data.resources) ? data.resources : [],
+        save: Array.isArray(data.save) ? data.save : undefined,
+        metadata: data.metadata,
+        source: data.source,
+        message: typeof data.message === 'string' ? data.message : undefined,
+      }))];
+    }
+
+    case 'permission.replied':
+      if (!sessionID) return [];
+      return [event('permission.replied', { sessionID, requestID: trimmed(data.requestID) })];
+
+    case 'form.created': {
+      const form = isRecord(data.form) ? data.form : null;
+      if (!form || !trimmed(form.id)) return [];
+      return [event('form.created', { sessionID: trimmed(form.sessionID), form })];
+    }
+
+    case 'form.replied':
+    case 'form.cancelled':
+      if (!sessionID) return [];
+      return [event('form.settled', { sessionID, formID: trimmed(data.id) })];
+
+    // --- location-level notices ------------------------------------------------
+
+    case 'vcs.branch.updated':
+      return [event('vcs.branch.updated', { branch: typeof data.branch === 'string' ? data.branch : undefined })];
+
+    case 'mcp.status.changed':
+      return [event('mcp.status.changed', { server: trimmed(data.server) })];
+
+    default:
+      return [];
+  }
+}
+
+/**
+ * Convenience for consumers that hand one payload to one handler: translates
+ * and forwards every resulting event in order.
+ */
+export function forwardTranslatedWireEvent(payload, handle) {
+  if (typeof handle !== 'function') return;
+  for (const translated of translateWireEvent(payload)) handle(translated);
+}

package/server/lib/event-stream/translate-v2.test.js

@@ -0,0 +1,209 @@
+import { describe, expect, test } from 'bun:test';
+import { forwardTranslatedWireEvent, translateWireEvent, wireEventDirectory } from './translate-v2.js';
+
+const wire = (type, data, extra = {}) => ({
+  id: 'evt_1',
+  created: 1000,
+  type,
+  data,
+  location: { directory: '/repo' },
+  ...extra,
+});
+
+describe('translateWireEvent', () => {
+  test('ignores non-objects and unknown types', () => {
+    expect(translateWireEvent(null)).toEqual([]);
+    expect(translateWireEvent('nope')).toEqual([]);
+    expect(translateWireEvent(wire('session.tool.progress', { sessionID: 's1' }))).toEqual([]);
+  });
+
+  test('tags every event with its source id and directory', () => {
+    const [event] = translateWireEvent(wire('session.idle', { sessionID: 's1' }));
+    expect(event.id).toBe('evt_1');
+    expect(event.created).toBe(1000);
+    expect(event.properties.directory).toBe('/repo');
+  });
+
+  test('server.connected and update availability pass through', () => {
+    expect(translateWireEvent(wire('server.connected', {}))[0].type).toBe('server.connected');
+    const [update] = translateWireEvent(wire('installation.update-available', { version: '2.1.0' }));
+    expect(update).toMatchObject({ type: 'installation.update-available', properties: { version: '2.1.0' } });
+  });
+
+  test('session.created carries the directory from its location', () => {
+    const [event] = translateWireEvent(wire('session.created', {
+      sessionID: 's1',
+      projectID: 'p1',
+      parentID: 's0',
+      title: 'Fix login',
+      agent: 'build',
+      location: { directory: '/other' },
+    }));
+    expect(event.type).toBe('session.created');
+    expect(event.properties.info).toMatchObject({
+      id: 's1',
+      parentID: 's0',
+      projectID: 'p1',
+      directory: '/other',
+      title: 'Fix login',
+      agent: 'build',
+    });
+  });
+
+  test('rename, move and usage all read as session.updated', () => {
+    expect(translateWireEvent(wire('session.renamed', { sessionID: 's1', title: 'New' }))[0])
+      .toMatchObject({ type: 'session.updated', properties: { info: { id: 's1', title: 'New' } } });
+    expect(translateWireEvent(wire('session.moved', { sessionID: 's1', projectID: 'p2', location: { directory: '/moved' } }))[0])
+      .toMatchObject({ type: 'session.updated', properties: { info: { id: 's1', directory: '/moved', projectID: 'p2' } } });
+    expect(translateWireEvent(wire('session.usage.updated', { sessionID: 's1', cost: 0.5, tokens: { input: 10 } }))[0])
+      .toMatchObject({ type: 'session.updated', properties: { info: { id: 's1', cost: 0.5 } } });
+  });
+
+  test('session.deleted keeps both the id and the legacy info shape', () => {
+    const [event] = translateWireEvent(wire('session.deleted', { sessionID: 's1' }));
+    expect(event).toMatchObject({ type: 'session.deleted', properties: { sessionID: 's1', info: { id: 's1' } } });
+  });
+
+  test('execution events synthesize the status vocabulary v2 no longer emits', () => {
+    expect(translateWireEvent(wire('session.execution.started', { sessionID: 's1' })))
+      .toMatchObject([{ type: 'session.status', properties: { sessionID: 's1', status: { type: 'busy' } } }]);
+
+    const succeeded = translateWireEvent(wire('session.execution.succeeded', { sessionID: 's1' }));
+    expect(succeeded.map((entry) => entry.type)).toEqual(['session.status', 'session.idle']);
+    expect(succeeded[0].properties.status).toEqual({ type: 'idle' });
+  });
+
+  test('an interruption ends the turn without reporting a failure', () => {
+    const events = translateWireEvent(wire('session.execution.interrupted', { sessionID: 's1', reason: 'user' }));
+    expect(events.map((entry) => entry.type)).toEqual(['session.status', 'session.idle']);
+    expect(events[1].properties).toMatchObject({ aborted: true, reason: 'user' });
+    expect(events[1].properties.error.name).toBe('MessageAbortedError');
+    expect(events.some((entry) => entry.type === 'session.error')).toBe(false);
+  });
+
+  test('a shutdown interruption is not an abort: the turn resumes after restart', () => {
+    // OpenCode keeps the execution claim across a shutdown and continues the
+    // turn on restart, so nothing here may read as the user pressing Stop.
+    expect(translateWireEvent(wire('session.execution.interrupted', { sessionID: 's1', reason: 'shutdown' }))).toEqual([]);
+  });
+
+  test('a failed execution reports a structured error', () => {
+    const events = translateWireEvent(wire('session.execution.failed', {
+      sessionID: 's1',
+      error: { type: 'ProviderAuthError', message: 'bad key', status: 401 },
+    }));
+    expect(events.map((entry) => entry.type)).toEqual(['session.status', 'session.error']);
+    expect(events[1].properties.error).toEqual({
+      name: 'ProviderAuthError',
+      type: 'ProviderAuthError',
+      message: 'bad key',
+      status: 401,
+    });
+  });
+
+  test('a passed-through session.status is kept as is', () => {
+    const [event] = translateWireEvent(wire('session.status', { sessionID: 's1', status: { type: 'retry', attempt: 2 } }));
+    expect(event.properties.status).toEqual({ type: 'retry', attempt: 2 });
+  });
+
+  test('an enqueued user prompt becomes a user message with text parts', () => {
+    const [event] = translateWireEvent(wire('session.inbox.enqueued', {
+      sessionID: 's1',
+      inboxID: 'msg_1',
+      item: { type: 'user', payload: { text: 'hello' } },
+    }));
+    expect(event.type).toBe('message.updated');
+    expect(event.properties.info).toMatchObject({ id: 'msg_1', sessionID: 's1', role: 'user', text: 'hello' });
+    expect(event.properties.info.parts).toEqual([{ type: 'text', text: 'hello' }]);
+  });
+
+  test('non-user inbox items are not messages', () => {
+    expect(translateWireEvent(wire('session.inbox.enqueued', {
+      sessionID: 's1',
+      inboxID: 'msg_1',
+      item: { type: 'compaction', payload: {} },
+    }))).toEqual([]);
+  });
+
+  test('steps become assistant message updates', () => {
+    const [started] = translateWireEvent(wire('session.step.started', {
+      sessionID: 's1',
+      assistantMessageID: 'msg_2',
+      agent: 'build',
+      model: { id: 'gpt-5.6-luna', providerID: 'openai' },
+    }));
+    expect(started.properties.info).toMatchObject({
+      id: 'msg_2', role: 'assistant', agent: 'build', providerID: 'openai', modelID: 'gpt-5.6-luna',
+    });
+
+    const [ended] = translateWireEvent(wire('session.step.ended', {
+      sessionID: 's1', assistantMessageID: 'msg_2', finish: 'stop', cost: 1, tokens: { input: 2 },
+    }));
+    expect(ended.properties.info).toMatchObject({ id: 'msg_2', role: 'assistant', finish: 'stop' });
+    expect(ended.properties.info.time.completed).toBe(1000);
+
+    const [failed] = translateWireEvent(wire('session.step.failed', {
+      sessionID: 's1', assistantMessageID: 'msg_2', error: { type: 'Overloaded', message: 'busy' },
+    }));
+    expect(failed.properties.info).toMatchObject({ finish: 'error' });
+    expect(failed.properties.info.error.name).toBe('Overloaded');
+  });
+
+  test('permission requests keep the v2 action and resources', () => {
+    const [event] = translateWireEvent(wire('permission.asked', {
+      id: 'per_1',
+      sessionID: 's1',
+      action: 'bash',
+      resources: ['rm -rf /'],
+      source: { type: 'tool', messageID: 'msg_1', id: 'call_1' },
+    }));
+    expect(event.properties).toMatchObject({
+      id: 'per_1', sessionID: 's1', action: 'bash', resources: ['rm -rf /'],
+    });
+
+    const [replied] = translateWireEvent(wire('permission.replied', { sessionID: 's1', requestID: 'per_1', reply: 'once' }));
+    expect(replied.properties).toMatchObject({ sessionID: 's1', requestID: 'per_1' });
+  });
+
+  test('forms replace questions', () => {
+    const form = { id: 'frm_1', sessionID: 's1', title: 'Switch to plan mode?', fields: [] };
+    const [created] = translateWireEvent(wire('form.created', { form }));
+    expect(created).toMatchObject({ type: 'form.created', properties: { sessionID: 's1', form } });
+
+    expect(translateWireEvent(wire('form.replied', { id: 'frm_1', sessionID: 's1' }))[0])
+      .toMatchObject({ type: 'form.settled', properties: { sessionID: 's1', formID: 'frm_1' } });
+    expect(translateWireEvent(wire('form.cancelled', { id: 'frm_1', sessionID: 's1' }))[0])
+      .toMatchObject({ type: 'form.settled', properties: { sessionID: 's1', formID: 'frm_1' } });
+  });
+
+  test('branch and mcp notices pass through', () => {
+    expect(translateWireEvent(wire('vcs.branch.updated', { branch: 'main' }))[0].properties.branch).toBe('main');
+    expect(translateWireEvent(wire('mcp.status.changed', { server: 'linear' }))[0].properties.server).toBe('linear');
+  });
+
+  test('events without a session id are dropped rather than half-translated', () => {
+    expect(translateWireEvent(wire('session.execution.started', {}))).toEqual([]);
+    expect(translateWireEvent(wire('session.step.ended', { sessionID: 's1' }))).toEqual([]);
+    expect(translateWireEvent(wire('permission.asked', { sessionID: 's1' }))).toEqual([]);
+  });
+});
+
+describe('wireEventDirectory', () => {
+  test('reads location.directory and tolerates its absence', () => {
+    expect(wireEventDirectory(wire('session.idle', { sessionID: 's1' }))).toBe('/repo');
+    expect(wireEventDirectory({ type: 'session.execution.started', data: {} })).toBe('');
+    expect(wireEventDirectory(null)).toBe('');
+  });
+});
+
+describe('forwardTranslatedWireEvent', () => {
+  test('forwards every translated event in order', () => {
+    const seen = [];
+    forwardTranslatedWireEvent(wire('session.execution.succeeded', { sessionID: 's1' }), (event) => seen.push(event.type));
+    expect(seen).toEqual(['session.status', 'session.idle']);
+  });
+
+  test('does nothing without a handler', () => {
+    expect(() => forwardTranslatedWireEvent(wire('session.idle', { sessionID: 's1' }), null)).not.toThrow();
+  });
+});

package/server/lib/event-stream/upstream-reader.test.js

@@ -65,12 +65,12 @@ describe('createUpstreamSseReader', () => {
     let reader;
 
     reader = createUpstreamSseReader({
-      buildUrl: () => 'http://127.0.0.1:4096/global/event',
+      buildUrl: () => 'http://127.0.0.1:4096/api/event',
       reconnectDelayMs: 0,
       fetchImpl: async (_url, options) => createSseResponse({
         signal: options.signal,
         blocks: [
-          'id: evt-1\r\ndata: {"type":"server.connected","properties":{"directory":"/tmp/project"}}\r\n\r\n',
+          'data: {"id":"evt-1","type":"session.renamed","location":{"directory":"/tmp/project"},"data":{"sessionID":"s1","title":"t"}}\r\n\r\n',
         ],
       }),
       onEvent(event) {
@@ -85,10 +85,10 @@ describe('createUpstreamSseReader', () => {
     expect(events[0].eventId).toBe('evt-1');
     expect(events[0].directory).toBe('/tmp/project');
     expect(events[0].payload).toEqual({
-      type: 'server.connected',
-      properties: {
-        directory: '/tmp/project',
-      },
+      id: 'evt-1',
+      type: 'session.renamed',
+      location: { directory: '/tmp/project' },
+      data: { sessionID: 's1', title: 't' },
     });
     expect(reader.getLastEventId()).toBe('evt-1');
   });
@@ -100,7 +100,7 @@ describe('createUpstreamSseReader', () => {
     let reader;
 
     reader = createUpstreamSseReader({
-      buildUrl: () => 'http://127.0.0.1:4096/global/event',
+      buildUrl: () => 'http://127.0.0.1:4096/api/event',
       stallTimeoutMs: 10,
       reconnectDelayMs: 0,
       fetchImpl: async (_url, options) => {
@@ -112,7 +112,7 @@ describe('createUpstreamSseReader', () => {
             signal: options.signal,
             holdOpen: true,
             blocks: [
-              'id: evt-1\ndata: {"type":"server.connected","properties":{}}\n\n',
+              'data: {"id":"evt-1","type":"server.connected","properties":{}}\n\n',
             ],
           });
         }
@@ -120,7 +120,7 @@ describe('createUpstreamSseReader', () => {
         return createSseResponse({
           signal: options.signal,
           blocks: [
-            'id: evt-2\ndata: {"type":"session.updated","properties":{}}\n\n',
+            'data: {"id":"evt-2","type":"session.updated","properties":{}}\n\n',
           ],
         });
       },
@@ -146,7 +146,7 @@ describe('createUpstreamSseReader', () => {
     let reader;
 
     reader = createUpstreamSseReader({
-      buildUrl: () => 'http://127.0.0.1:4096/global/event',
+      buildUrl: () => 'http://127.0.0.1:4096/api/event',
       stallTimeoutMs: () => currentTimeout,
       reconnectDelayMs: 0,
       fetchImpl: async (_url, options) => {
@@ -158,7 +158,7 @@ describe('createUpstreamSseReader', () => {
             signal: options.signal,
             holdOpen: true,
             blocks: [
-              'id: evt-1\ndata: {"type":"server.connected","properties":{}}\n\n',
+              'data: {"id":"evt-1","type":"server.connected","properties":{}}\n\n',
             ],
           });
         }
@@ -166,7 +166,7 @@ describe('createUpstreamSseReader', () => {
         return createSseResponse({
           signal: options.signal,
           blocks: [
-            'id: evt-2\ndata: {"type":"session.updated","properties":{}}\n\n',
+            'data: {"id":"evt-2","type":"session.updated","properties":{}}\n\n',
           ],
         });
       },
@@ -191,7 +191,7 @@ describe('createUpstreamSseReader', () => {
     let reader;
 
     reader = createUpstreamSseReader({
-      buildUrl: () => 'http://127.0.0.1:4096/global/event',
+      buildUrl: () => 'http://127.0.0.1:4096/api/event',
       reconnectDelayMs: 0,
       fetchImpl: async (_url, options) => {
         attempt += 1;
@@ -210,7 +210,7 @@ describe('createUpstreamSseReader', () => {
         return createSseResponse({
           signal: options.signal,
           blocks: [
-            'id: evt-1\ndata: {"type":"server.connected","properties":{}}\n\n',
+            'data: {"id":"evt-1","type":"server.connected","properties":{}}\n\n',
           ],
         });
       },
@@ -240,7 +240,7 @@ describe('createUpstreamSseReader', () => {
     let reader;
 
     reader = createUpstreamSseReader({
-      buildUrl: () => 'http://127.0.0.1:4096/global/event',
+      buildUrl: () => 'http://127.0.0.1:4096/api/event',
       reconnectDelayMs: 1,
       signal: tracked.signal,
       fetchImpl: async (_url, options) => {
@@ -258,7 +258,7 @@ describe('createUpstreamSseReader', () => {
         return createSseResponse({
           signal: options.signal,
           blocks: [
-            'id: evt-1\ndata: {"type":"server.connected","properties":{}}\n\n',
+            'data: {"id":"evt-1","type":"server.connected","properties":{}}\n\n',
           ],
         });
       },

package/server/lib/fs/DOCUMENTATION.md

@@ -53,9 +53,11 @@ twelve children.
 - Workspace checks accept, besides the active workspace and its worktrees, the **managed roots**: the OpenChamber config root and the managed chats root (`managedChatsRoot` dependency; `OPENCHAMBER_CHATS_DIR` upstream, default `<config root>/chats`). Chat worktrees may legitimately live outside every project workspace.
 - `GET /api/fs/home` preserves `{ home, chatsRoot }` and adds `canonicalChatsRoot` and `canonicalLegacyChatsRoot`, resolved by the server's filesystem. If a root does not exist yet, it resolves the nearest existing ancestor and appends the missing segments, without creating directories. Errors resolving the configured root fail the request. A failed legacy lookup warns and omits only that optional alias, retaining exact legacy matching without blocking an accessible relocated root. Clients use confirmed aliases for exact membership while keeping the original roots as folder/scope identities. `chatsRoot` is the server-resolved managed chats root; clients must use it instead of joining `home` + the well-known segment (a relocated root does not contain that segment).
 - Workspace authorization accepts both the configured managed paths and their filesystem-confirmed canonical roots. Canonical lookup runs only when lexical workspace/managed-root checks fail. One failed managed-root lookup cannot reject an independently authorized root or worktree. Path comparisons remain case-sensitive on POSIX: distinct Linux directories named `chats` and `Chats` never become aliases through string folding. Shared UI keeps exact root membership for classification and directory cleanup.
-- Filesystem `EPERM`/`EACCES` failures use the stable `reason: "os-permission"` response marker. Policy denials such as workspace-boundary or missing-grant failures must not use that marker because a native folder picker cannot remediate them.
+- Filesystem `EPERM`/`EACCES` failures use the stable `reason: "os-permission"` response marker. Workspace-boundary policy denials must not use that marker because a native folder picker cannot remediate them.
 - `GET /api/fs/directory-stat?path=...` uses one `stat` without listing contents or resolving project topology. It follows the same authenticated directory-discovery path policy as `/api/fs/list`, including targets outside the active workspace. A directory returns `{ isDirectory: true }`; `ENOENT` returns `not-found`, and a file or `ENOTDIR` returns `not-directory`. Permission and other failures remain distinct from a missing path. VS Code explicitly returns 501, so the shared client treats its probe as unknown.
-- Read-only routes authorize the requested path against the workspace before resolving symlinks. A symlink reached through the workspace may therefore target a file outside it, while a directly requested outside path still requires an exact-path grant. Write routes keep canonical-target boundary checks.
+- A page shown through `GET /api/fs/serve/…` loads its relative images, styles and scripts without a token; `ui-auth.js` accepts the page's own `oc_url_token` from the `Referer` for a subresource, but only when both URLs sit under `/api/fs/serve/`. Without this, HTML previews on desktop (no session cookie on the loopback API origin) show broken images.
+- `GET /api/fs/raw` answers one `Range: bytes=…` span with `206`, `Content-Range` and a stream from disk (`byte-range.js` reduces the header to a span). Media elements send a span on every seek, and Chromium and WebKit refuse to seek without a `206`, so the viewer's audio and video players depend on this; a whole-file request still reads and sends the buffer. The MIME table (`FILE_MIME_MAP`) is shared with `/api/fs/serve` and covers images, PDF, audio, video, fonts, CSV/TSV and Mermaid.
+- File read, raw and stat routes accept outside paths with `allowOutsideWorkspace=true` under the normal server authentication and OS permissions. They do not require a separate file grant. Legacy grant parameters are ignored. Workspace-scoped reads resolve symlinks after checking the requested path. Write routes keep canonical-target boundary checks.
 - If adding new `/api/fs/*` endpoints, add them in `routes.js` and extend this document.
 - `GET /api/fs/list` may resolve symlinks with `realpath` to read directory contents, but the response `path` and each entry `path` must stay in the caller's requested path space (`path.join(requestedPath, name)`). Returning real paths breaks file-tree expansion for directories reached through workspace symlinks.
 - `POST /api/fs/upload` accepts one `application/octet-stream` body with `path` and optional `overwrite=true` query parameters. The body streams into a same-directory temp file with a 100 MiB default cap configurable through `OPENCHAMBER_FS_UPLOAD_MAX_BYTES`; failed and oversized uploads clean up that temp file. New files commit through an atomic no-replace link, existing files return `409` unless overwrite is explicit, directory targets are rejected, and the destination parent resolves before writing so uploads cannot escape through workspace symlinks.