@vantran-se/openchamber-web 2.0.3 → 2.0.5

package/server/lib/agent-tool/runtime.js

@@ -3,6 +3,8 @@ import {
   OPENCHAMBER_AGENT_TOOL_ACTIONS,
   OPENCHAMBER_MEMORY_ACTION_DEFINITIONS,
   OPENCHAMBER_MEMORY_ACTIONS,
+  OPENCHAMBER_NOTIFY_ACTION_DEFINITIONS,
+  OPENCHAMBER_NOTIFY_ACTIONS,
   resolveAgentToolAction,
   OPENCHAMBER_WEB_ACTION_DEFINITIONS,
   OPENCHAMBER_WEB_ACTIONS,
@@ -12,12 +14,18 @@ const TOOL_SCHEMA_VERSION = 1;
 const PLUGIN_ID = 'openchamber-agent-tool';
 // Everything either managed tool may ask for; the agent allowlist stays
 // narrower than the full control surface.
-const ACTIONS = new Set([...OPENCHAMBER_AGENT_TOOL_ACTIONS, ...OPENCHAMBER_WEB_ACTIONS, ...OPENCHAMBER_MEMORY_ACTIONS]);
+const ACTIONS = new Set([
+  ...OPENCHAMBER_AGENT_TOOL_ACTIONS,
+  ...OPENCHAMBER_WEB_ACTIONS,
+  ...OPENCHAMBER_MEMORY_ACTIONS,
+  ...OPENCHAMBER_NOTIFY_ACTIONS,
+]);
 const AGENT_TOOL_ACTION_TITLES = Object.fromEntries(
   [
     ...OPENCHAMBER_AGENT_TOOL_ACTION_DEFINITIONS,
     ...OPENCHAMBER_WEB_ACTION_DEFINITIONS,
     ...OPENCHAMBER_MEMORY_ACTION_DEFINITIONS,
+    ...OPENCHAMBER_NOTIFY_ACTION_DEFINITIONS,
   ].map(({ action, title }) => [action, title]),
 );
 
@@ -28,7 +36,7 @@ const AGENT_TOOL_ACTION_TITLES = Object.fromEntries(
  * in the other tool's schema, which is both misleading and paid for in context
  * on every call.
  */
-const WEB_PARAMETER_NAMES = ['url', 'selector', 'text', 'value', 'submit', 'direction', 'viewport', 'label'];
+const WEB_PARAMETER_NAMES = ['url', 'selector', 'text', 'value', 'submit', 'direction', 'viewport', 'label', 'tabId'];
 // `title` is shared with the control tool, so it is not listed here — only the
 // names memory alone introduces are kept out of the other schemas.
 const MEMORY_ONLY_PARAMETER_NAMES = ['body', 'scope', 'memoryId', 'type'];
@@ -87,6 +95,7 @@ const ALL_PARAMETER_PROPERTIES = {
   direction: { type: 'string', enum: ['up', 'down', 'top', 'bottom'], description: 'Scroll direction for browser.scroll' },
   viewport: { type: 'string', enum: ['mobile', 'tablet', 'desktop', 'fill'], description: 'Page layout size; snapshots report which one is in effect' },
   label: { type: 'string', description: 'Short name for a browser.capture image, such as before-fix' },
+  tabId: { type: 'string', description: 'Browser tab to act on, an id from the tabs a browser.snapshot lists. Omit to use the tab the user is looking at' },
   body: { type: 'string', description: 'Full text of the memory; state it so it still makes sense in a session that has none of this conversation' },
   scope: { type: 'string', enum: ['global', 'project', 'both'], description: 'global is about the user and applies everywhere; project is about this codebase. both is only valid for memory.list' },
   memoryId: { type: 'string', description: 'Memory ID from a memory.list or memory.read result' },
@@ -108,12 +117,22 @@ const MEMORY_PARAMETER_PROPERTIES = {
   ...MEMORY_PARAMETER_OVERRIDES,
 };
 
+// Its own names, not the shared map: `title` and `body` mean something else in
+// the control and memory tools.
+const NOTIFY_PARAMETER_PROPERTIES = {
+  title: { type: 'string', description: 'Short headline the user reads first, up to 120 characters' },
+  body: { type: 'string', description: 'One or two sentences of detail, up to 500 characters' },
+  showWhenFocused: { type: 'boolean', description: 'Show it even while the user is looking at OpenChamber. Only for something that cannot wait' },
+};
+
 const CONTROL_TOOL_DESCRIPTION = "Control OpenChamber projects, sessions, and scheduled tasks on the user's behalf. Sessions and scheduled tasks you create are for the user to follow and interact with. Do not decide on your own to hand parts of your current task to another session; when the user asks you to create a session, send a prompt to one, or schedule a task, do it, including when the work relates to your current task. Use one action per call. Scope with projectId or directory; omit both to use the current session directory. Session dispatches return immediately by default and you receive no notification when a dispatched session finishes, so never promise to report back on it; the user follows it in OpenChamber; a dispatched session needs no follow-up from you. If the user later asks how it went, use session.messages (add wait to block until it is idle, lastAssistant for just the final answer) — session.send always sends a NEW prompt and never just waits. Set wait only when the user asks or the next step requires the completed result. Session and worktree deletion are unavailable.";
 
 const WEB_TOOL_DESCRIPTION = "Look at and interact with a web page in OpenChamber's browser panel, so you can check your own work rather than describing what you expect. Use one action per call. Open a page, snapshot it to read its text and its interactive elements, then click, type or scroll using the selectors the snapshot returned; snapshots also report any errors the page logged. Pass a selector to browser.snapshot to read one part of a long page. browser.inspect returns computed styles when the question is how something renders. Set viewport to check a layout at mobile, tablet or desktop size. The page runs with the user's real logins, so treat what you see as their live session.";
 
 const MEMORY_TOOL_DESCRIPTION = "Keep what you learn across sessions, so the user does not have to explain the same thing twice. Use one action per call. The session already lists the titles of what is stored. A title is an abbreviation, not the memory: read the entry with memory.read once before acting on it (it then stays in your context; do not re-read it on later turns), because titles leave out the conditions and exceptions that decide how the memory applies, and the ones that look self-explanatory hide them most often. Save something only when it will still be true in a later session — a stable preference, a project convention, a decision and its reason, or a hard-won pointer. Do not save one-off task state, anything you can read from the code, secrets or credentials, or anything the user asked you not to keep; when the user explicitly asks you to remember something, save it, unless it is a secret or credential. Choose the scope deliberately: global is about the user and reaches every project, so put a project's conventions in project scope. Save in the moment, without asking first, when the user corrects how you work or states a preference, confirms that a non-obvious approach worked, or when you learn a project fact that took real effort to find. One fact per entry. The user can review and remove what you save, so save when it fits and mention it briefly.";
 
+const NOTIFY_TOOL_DESCRIPTION = "Send the user a notification through OpenChamber, so they learn about something without watching the session. Use it when you finish work that took long enough for the user to step away, when you are blocked on something only the user can resolve, or when the user asked to be told about something. Do not use it for routine progress, for every finished step, or to repeat what your reply already says to a user who is present. Keep the title short and put detail in the body.";
+
 const asNonEmptyString = (value) => {
   if (typeof value !== 'string') return null;
   const trimmed = value.trim();
@@ -167,6 +186,40 @@ const resolveConcreteBoundAddress = (value) => {
  * answer with an empty completion instead of an error, and the `oneOf` branches
  * are what carry the per-action descriptions the model reads.
  */
+const createEnvironmentExecutionSource = (name) => `const endpoint = process.env.OPENCHAMBER_AGENT_TOOL_URL
+        const token = process.env.OPENCHAMBER_AGENT_TOOL_TOKEN
+        const callbackHeaders = {}
+        if (!endpoint || !token) {
+          return failure({ schemaVersion: ${TOOL_SCHEMA_VERSION}, ok: false, action: args.action, error: { message: "OpenChamber managed tool connection is unavailable" } })
+        }
+
+        try {
+          const response = await fetch(endpoint, {
+            method: "POST",
+            headers: {
+              authorization: "Bearer " + token,
+              "content-type": "application/json",
+              ...callbackHeaders,
+            },
+            // OpenCode 2 no longer hands a tool its session directory, so the
+            // session id goes over instead and OpenChamber resolves the
+            // directory on its own side. The signal fires when the session is
+            // aborted, so the OpenChamber side stops the action too.
+            body: JSON.stringify({ input: args, sessionID: context.sessionID, tool: ${JSON.stringify(name)} }),
+            signal: context.signal,
+          })
+          const content = await response.text()
+          let result = null
+          try { result = JSON.parse(content) } catch {}
+          const valid = result?.schemaVersion === ${TOOL_SCHEMA_VERSION} && typeof result?.ok === "boolean" && typeof result?.action === "string"
+          await progress({ ok: valid && result.ok === true })
+          if (valid) return { content, metadata: { openchamber: { schemaVersion: ${TOOL_SCHEMA_VERSION}, action: args.action, description: title, ok: result.ok === true } } }
+          return failure({ schemaVersion: ${TOOL_SCHEMA_VERSION}, ok: false, action: args.action, error: { message: "OpenChamber returned an invalid response", kind: "runtime", status: response.status } })
+        } catch (error) {
+          return failure({ schemaVersion: ${TOOL_SCHEMA_VERSION}, ok: false, action: args.action, error: { message: error instanceof Error ? error.message : String(error), kind: "runtime" } })
+        }`;
+
+
 const createToolEntry = ({ name, description, definitions, parameters }) => String.raw`    tools.add({
       name: ${JSON.stringify(name)},
       description: ${JSON.stringify(description)},
@@ -199,8 +252,6 @@ const createToolEntry = ({ name, description, definitions, parameters }) => Stri
           },
         })
         await progress()
-        const endpoint = process.env.OPENCHAMBER_AGENT_TOOL_URL
-        const token = process.env.OPENCHAMBER_AGENT_TOOL_TOKEN
         // No output schema is declared, so a result must never carry an output
         // field: OpenCode rejects that with "Tool result declared output
         // without an output schema". The envelope travels as text content.
@@ -208,39 +259,12 @@ const createToolEntry = ({ name, description, definitions, parameters }) => Stri
           content: JSON.stringify(payload),
           metadata: { openchamber: { schemaVersion: ${TOOL_SCHEMA_VERSION}, action: args.action, description: title, ok: false } },
         })
-        if (!endpoint || !token) {
-          return failure({ schemaVersion: ${TOOL_SCHEMA_VERSION}, ok: false, action: args.action, error: { message: "OpenChamber managed tool connection is unavailable" } })
-        }
-
-        try {
-          const response = await fetch(endpoint, {
-            method: "POST",
-            headers: {
-              authorization: "Bearer " + token,
-              "content-type": "application/json",
-            },
-            // OpenCode 2 no longer hands a tool its session directory, so the
-            // session id goes over instead and OpenChamber resolves the
-            // directory on its own side. The signal fires when the session is
-            // aborted, so the OpenChamber side stops the action too.
-            body: JSON.stringify({ input: args, sessionID: context.sessionID, tool: ${JSON.stringify(name)} }),
-            signal: context.signal,
-          })
-          const content = await response.text()
-          let result = null
-          try { result = JSON.parse(content) } catch {}
-          const valid = result?.schemaVersion === ${TOOL_SCHEMA_VERSION} && typeof result?.ok === "boolean" && typeof result?.action === "string"
-          await progress({ ok: valid && result.ok === true })
-          if (valid) return { content, metadata: { openchamber: { schemaVersion: ${TOOL_SCHEMA_VERSION}, action: args.action, description: title, ok: result.ok === true } } }
-          return failure({ schemaVersion: ${TOOL_SCHEMA_VERSION}, ok: false, action: args.action, error: { message: "OpenChamber returned an invalid response", kind: "runtime", status: response.status } })
-        } catch (error) {
-          return failure({ schemaVersion: ${TOOL_SCHEMA_VERSION}, ok: false, action: args.action, error: { message: error instanceof Error ? error.message : String(error), kind: "runtime" } })
-        }
+        ${createEnvironmentExecutionSource(name)}
       },
     })
 `;
 
-const createPluginSource = ({ includeControl, includeWeb, includeMemory }) => {
+export const createPluginSource = ({ includeControl, includeWeb, includeMemory, includeNotify }) => {
   const entries = [];
   if (includeControl) {
     entries.push(createToolEntry({
@@ -266,16 +290,22 @@ const createPluginSource = ({ includeControl, includeWeb, includeMemory }) => {
       parameters: MEMORY_PARAMETER_PROPERTIES,
     }));
   }
+  if (includeNotify) {
+    entries.push(createToolEntry({
+      name: 'openchamber_notify',
+      description: NOTIFY_TOOL_DESCRIPTION,
+      definitions: OPENCHAMBER_NOTIFY_ACTION_DEFINITIONS,
+      parameters: NOTIFY_PARAMETER_PROPERTIES,
+    }));
+  }
 
-  // The callback carries the per-child token over plain HTTP. With a proxy in
-  // the child's environment, fetch would hand a non-loopback callback, token
-  // included, to that proxy, and no per-request option turns that off. The
-  // exemption is added inside the child because only there is the final
-  // NO_PROXY, merged from the shell and server environments, visible.
-  return `const exemptCallbackFromProxy = () => {
-  const endpoint = process.env.OPENCHAMBER_AGENT_TOOL_URL
-  if (!endpoint || !URL.canParse(endpoint)) return
-  const host = new URL(endpoint).hostname.replace(/^\\[|\\]$/g, "")
+  // The callback carries a bearer token over plain HTTP. With a proxy in the
+  // OpenCode environment, fetch could hand a non-loopback callback and token to
+  // that proxy. Add the callback host to both proxy exemption variables before
+  // a request.
+  return `const exemptCallbackFromProxy = (callbackEndpoint = process.env.OPENCHAMBER_AGENT_TOOL_URL) => {
+  if (!callbackEndpoint || !URL.canParse(callbackEndpoint)) return
+  const host = new URL(callbackEndpoint).hostname.replace(/^\\[|\\]$/g, "")
   for (const key of ["NO_PROXY", "no_proxy"]) {
     const entries = (process.env[key] || "").split(",").map((entry) => entry.trim()).filter(Boolean)
     if (!entries.includes(host)) process.env[key] = [...entries, host].join(",")
@@ -295,7 +325,7 @@ ${entries.join('')}    })
 
 // A configured plugin has to be a directory carrying a package.json that
 // resolves an entrypoint; OpenCode skips a plain .js path.
-const PLUGIN_PACKAGE_JSON = `${JSON.stringify({
+export const AGENT_TOOL_PLUGIN_PACKAGE_JSON = `${JSON.stringify({
   name: 'openchamber-agent-tool',
   version: '0.0.0',
   private: true,
@@ -329,13 +359,13 @@ export const createAgentToolRuntime = (dependencies) => {
    * change while it runs, so the source on disk always matches the settings —
    * the running OpenCode reloads the directory it already has configured.
    */
-  const materializePlugin = async ({ includeControl = true, includeWeb = true, includeMemory = true } = {}) => {
-    if (!includeControl && !includeWeb && !includeMemory) {
+  const materializePlugin = async ({ includeControl = true, includeWeb = true, includeMemory = true, includeNotify = false } = {}) => {
+    if (!includeControl && !includeWeb && !includeMemory && !includeNotify) {
       throw new Error('At least one OpenChamber managed tool must be enabled to inject the plugin');
     }
     await fsPromises.mkdir(pluginDirectory, { recursive: true });
-    await fsPromises.writeFile(pluginManifestPath, PLUGIN_PACKAGE_JSON, { mode: 0o600 });
-    await fsPromises.writeFile(pluginPath, createPluginSource({ includeControl, includeWeb, includeMemory }), { mode: 0o600 });
+    await fsPromises.writeFile(pluginManifestPath, AGENT_TOOL_PLUGIN_PACKAGE_JSON, { mode: 0o600 });
+    await fsPromises.writeFile(pluginPath, createPluginSource({ includeControl, includeWeb, includeMemory, includeNotify }), { mode: 0o600 });
     return pluginDirectory;
   };
 
@@ -371,15 +401,21 @@ export const createAgentToolRuntime = (dependencies) => {
     return boundAddress !== null && normalizeAddress(value) === boundAddress;
   };
 
-  const authorize = (req) => {
-    if (!activeToken || !isSameMachineAddress(req.socket?.remoteAddress)) return false;
+  const verifyBearer = (req, token) => {
+    if (!token) return false;
     const header = asNonEmptyString(req.headers?.authorization);
     if (!header?.startsWith('Bearer ')) return false;
     const provided = Buffer.from(header.slice(7));
-    const expected = Buffer.from(activeToken);
+    const expected = Buffer.from(token);
     return provided.length === expected.length && crypto.timingSafeEqual(provided, expected);
   };
 
+
+  const authorizeManagedChild = (req) => (
+    isSameMachineAddress(req.socket?.remoteAddress) && verifyBearer(req, activeToken)
+  );
+
+
   const execute = async (payload = {}, options = {}) => {
     const requested = asNonEmptyString(payload.input?.action);
     // Resolved against the calling tool's own actions: models drop the
@@ -455,8 +491,9 @@ export const createAgentToolRuntime = (dependencies) => {
   };
 
   const registerRoutes = (app, express) => {
+
     app.post('/api/openchamber/agent-tool', express.json({ limit: '1mb' }), async (req, res) => {
-      if (!authorize(req)) return res.status(401).json({ error: 'Unauthorized' });
+      if (!authorizeManagedChild(req)) return res.status(401).json({ error: 'Unauthorized' });
       const controller = new AbortController();
       const abortOnDisconnect = () => {
         if (!res.writableEnded) controller.abort();
@@ -484,6 +521,7 @@ export const createAgentToolRuntime = (dependencies) => {
     pluginDirectory,
     materializePlugin,
     createChildEnv,
+    authorizeRequest: authorizeManagedChild,
     registerRoutes,
     execute,
     abortSession,

package/server/lib/agent-tool/runtime.test.js

@@ -249,6 +249,21 @@ describe('managed agent tool runtime', () => {
     expect(Object.keys(tool)).toEqual(['openchamber_memory']);
   });
 
+  it('exposes notify as its own tool only when switched on', async () => {
+    const { runtime, dataDir } = await createRuntime();
+    await prepareManagedEnv(runtime, { includeControl: true, includeWeb: false, includeMemory: false, includeNotify: true });
+    const tool = await loadTools(dataDir, 'notify');
+
+    expect(Object.keys(tool)).toEqual(['openchamber', 'openchamber_notify']);
+    expect(Object.keys(tool.openchamber_notify.input.properties.parameters.properties).sort())
+      .toEqual(['body', 'showWhenFocused', 'title']);
+    expect(Object.keys(tool.openchamber.input.properties.parameters.properties)).not.toContain('showWhenFocused');
+
+    const { runtime: plain, dataDir: plainDir } = await createRuntime();
+    await prepareManagedEnv(plain, { includeControl: true, includeWeb: false, includeMemory: false });
+    expect(Object.keys(await loadTools(plainDir, 'nonotify'))).toEqual(['openchamber']);
+  });
+
   it('refuses to inject a plugin with no tools in it', async () => {
     const { runtime } = await createRuntime();
     let failed = false;
@@ -445,6 +460,8 @@ describe('managed agent tool runtime', () => {
     expect(response.body).toEqual(expect.objectContaining({ ok: true, action: 'projects.list' }));
   });
 
+
+
   it.each([
     ['0.0.0.0', 'http://127.0.0.1:3901/api/openchamber/agent-tool'],
     ['::', 'http://127.0.0.1:3901/api/openchamber/agent-tool'],

package/server/lib/browser-control/DOCUMENTATION.md

@@ -46,8 +46,20 @@ itself; it can only ask and wait.
   `browser.*` actions of the `openchamber_web` tool onto the router's
   `request()` (same signature as the broker) and owns their parameter
   validation.
-- The client half is `packages/ui/src/lib/browser/controlClient.ts`, which
-  registers the mounted browser pane as the one responder.
+- The client half is `packages/ui/src/lib/browser/controlClient.ts`. Every
+  mounted browser tab registers its pane under its context-panel tab id. An
+  action with `tabId` runs in that tab; without one it runs in the browser tab
+  the user last had in front of them (`setShownBrowserTab`, set by
+  `ContextPanel`), never in whichever pane registered last, and never switches
+  the user to the tab it acts in. `browser.open` without `tabId` never
+  navigates an existing tab: the registered opener (`ContextPanel`,
+  `useUIStore.openAgentBrowserTab`) makes a new background tab and the answer
+  carries its `tabId`. `browser.snapshot` answers carry `tabs`
+  (`id`, `title`, `url`, `active`). A client without the named tab waits
+  briefly, so the client that has it claims first, then claims and answers
+  "no such tab". `tabId` is validated and passed through by
+  `../openchamber-control/service.js` for every action, so an extension
+  provider receives it untouched (`BrowserTabTarget` in `@openchamber/sdk`).
 
 ## Invariants
 

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

@@ -29,7 +29,7 @@ This module contains the OpenChamber message-stream WebSocket protocol and runti
 - `serializeMessageStreamWsEvent(payload, options)` and `sendSerializedMessageStreamWsFrame(socket, frame)` separate encoding from per-socket delivery. Delivery retains ready-state and backpressure checks.
 
 ### Runtime helpers
-- `createGlobalMessageStreamHub(...)`: creates a shared `/global/event` upstream SSE hub with event/status subscribers and bounded event-id replay.
+- `createGlobalMessageStreamHub(...)`: creates a shared `/global/event` upstream SSE hub with event/status subscribers and bounded event-id replay. The composition root owns the singleton and stops it during application shutdown; watchers and WebSocket bridges that receive it are borrowers and must not stop it.
 - `createGlobalUiEventBroadcaster({ sseClients, wsClients, writeSseEvent })`: returns a broadcaster that fans out the same synthetic UI event to SSE and WS clients.
 - `createMessageStreamWsRuntime(...)`: mounts the message-stream WS server, upgrade handler, and SSE-to-WS bridge onto the web HTTP server.
 
@@ -59,7 +59,7 @@ This module contains the OpenChamber message-stream WebSocket protocol and runti
 - The hub numbers every event that arrives without an SSE id (`oc-<process>-<sequence>`). OpenCode 1.18 sends no ids at all, and an event without an id used to skip the replay buffer, so reconnecting clients had no cursor and lost whatever fell into the gap. The process prefix makes a cursor from before a server restart miss, which reports `replayReset`, instead of matching an unrelated sequence number.
 - Directory WS clients still attach one upstream `/event?directory=...` SSE reader per connection because directory streams are scoped.
 - If an upstream SSE stream stalls after the browser WS is already ready, the reader aborts that upstream fetch and reconnects upstream with `Last-Event-ID`, keeping the browser WS alive when recovery is fast.
-- When the shared global upstream reconnects after it was previously ready, the global WS bridge sends a fresh `ready` frame to already-ready browser clients. The browser treats this as a reconnect edge and can run scoped state repair without requiring the browser WS to close.
+- When the shared global upstream reconnects after it was previously ready, the global WS bridge sends a fresh `ready` frame to already-ready browser clients. The browser treats this as a reconnect edge and runs its established scoped authoritative repair without requiring the browser WS to close. Shared-service recovery uses this edge rather than manufacturing a server-side interruption. Rebinding retires the old reader generation before starting its replacement, so delayed events, errors, and disconnect completion from the old reader cannot overwrite the replacement's connection state.
 - Health checks are reserved for initial upstream connect failures and explicit upstream-unavailable responses, not for ordinary stall recovery on an already-established stream.
 - Global synthetic events such as `openchamber:session-status`, `openchamber:session-activity`, `openchamber:notification`, and `openchamber:heartbeat` are preserved on the WS path, but heartbeat frames are emitted only while an upstream SSE stream is actively attached.
 - Global UI broadcasts are fan-out capable across both SSE and WS clients.

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

@@ -24,6 +24,8 @@ export function createGlobalMessageStreamHub({
     throw new RangeError('Replay limits must be nonnegative safe integers');
   }
   const eventSubscribers = new Set();
+  // The event subscribers that also take the events of isolated spaces.
+  const spaceSubscribers = new Set();
   const statusSubscribers = new Set();
   const replay = [];
   let replayBytes = 0;
@@ -40,9 +42,9 @@ export function createGlobalMessageStreamHub({
 
   let controller = null;
   let reader = null;
+  let readerGeneration = 0;
   let connected = false;
   let everConnected = false;
-  let buildUrlFailed = false;
 
   const notifySubscriber = (kind, subscriber, payload) => {
     try {
@@ -69,6 +71,10 @@ export function createGlobalMessageStreamHub({
     const eventId = typeof envelope?.eventId === 'string' && envelope.eventId.length > 0
       ? envelope.eventId
       : `${replayIdPrefix}${String(++replaySequence).padStart(12, '0')}`;
+    // An event of an isolated space carries the space's id; subscribers see it only when they
+    // asked for space events, because a consumer that acts on the host's OpenCode by
+    // directory must never act on a space's directory.
+    const spaceId = typeof envelope?.spaceId === 'string' && envelope.spaceId.length > 0 ? envelope.spaceId : null;
     let serializedFrame;
     let translated;
     return {
@@ -76,6 +82,7 @@ export function createGlobalMessageStreamHub({
       payload,
       directory,
       eventId,
+      spaceId,
       serialize() {
         serializedFrame ??= serializeMessageStreamWsEvent(payload, { directory, eventId });
         return serializedFrame;
@@ -112,6 +119,7 @@ export function createGlobalMessageStreamHub({
     }
 
     for (const subscriber of Array.from(eventSubscribers)) {
+      if (normalized.spaceId !== null && !spaceSubscribers.has(subscriber)) continue;
       notifySubscriber('event', subscriber, normalized);
     }
   };
@@ -124,8 +132,11 @@ export function createGlobalMessageStreamHub({
     }
 
     controller = new AbortController();
+    const generation = ++readerGeneration;
+    const currentController = controller;
+    let buildUrlFailed = false;
     reader = createUpstreamSseReader({
-      signal: controller.signal,
+      signal: currentController.signal,
       stallTimeoutMs: upstreamStallTimeoutMs,
       reconnectDelayMs: upstreamReconnectDelayMs,
       fetchImpl,
@@ -140,20 +151,23 @@ export function createGlobalMessageStreamHub({
       },
       getHeaders: getOpenCodeAuthHeaders,
       onConnect() {
+        if (generation !== readerGeneration) return;
         connected = true;
         const wasReady = everConnected;
         everConnected = true;
         notifyStatus({ type: 'connect', wasReady });
       },
       onDisconnect({ reason }) {
+        if (generation !== readerGeneration) return;
         connected = false;
         notifyStatus({ type: 'disconnect', reason });
       },
       onEvent(event) {
+        if (generation !== readerGeneration) return;
         coalescer.push(event);
       },
       onError(error) {
-        if (controller?.signal.aborted) {
+        if (generation !== readerGeneration || currentController.signal.aborted) {
           return;
         }
 
@@ -168,8 +182,9 @@ export function createGlobalMessageStreamHub({
     void reader.start();
   };
 
-  const stop = () => {
+  const stopReader = ({ resetConnectionHistory }) => {
     connected = false;
+    readerGeneration += 1;
     // Text that already arrived belongs in the retained replay suffix.
     coalescer.flush();
     reader?.stop();
@@ -178,25 +193,48 @@ export function createGlobalMessageStreamHub({
     }
     reader = null;
     controller = null;
-    everConnected = false;
-    buildUrlFailed = false;
+    if (resetConnectionHistory) {
+      everConnected = false;
+    }
+  };
+
+  const stop = () => {
+    stopReader({ resetConnectionHistory: true });
   };
 
   return {
     start,
     stop,
+    rebind() {
+      stopReader({ resetConnectionHistory: false });
+      start();
+    },
     isConnected() {
       return connected;
     },
     hasConnected() {
       return everConnected;
     },
-    subscribeEvent(subscriber) {
+    /**
+     * `spaces: true` also delivers the events of isolated spaces, which carry `spaceId`.
+     * Without it a subscriber sees the host's events only, as every consumer did before spaces.
+     */
+    subscribeEvent(subscriber, { spaces = false } = {}) {
       eventSubscribers.add(subscriber);
+      if (spaces) spaceSubscribers.add(subscriber);
       return () => {
         eventSubscribers.delete(subscriber);
+        spaceSubscribers.delete(subscriber);
       };
     },
+    /**
+     * One event of an isolated space, from that space's own connection, entered here as if it
+     * had arrived upstream: numbered, coalesced, replayed and fanned out with the host's, so
+     * a client keeps one cursor for everything. `directory` is the space's, `spaceId` marks it.
+     */
+    injectEvent({ payload, directory, spaceId }) {
+      coalescer.push({ envelope: { directory, spaceId }, payload });
+    },
     subscribeStatus(subscriber) {
       statusSubscribers.add(subscriber);
       return () => {

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

@@ -25,7 +25,7 @@ it('bounds a contiguous replay suffix by UTF-8 bytes and event count', async ()
   } finally { hub.stop(); }
 });
 
-function createSseResponse({ blocks = [] } = {}) {
+function createSseResponse({ blocks = [], signal, holdOpen = false } = {}) {
   const encoder = new TextEncoder();
   let index = 0;
 
@@ -38,7 +38,18 @@ function createSseResponse({ blocks = [] } = {}) {
             if (index < blocks.length) {
               return { value: encoder.encode(blocks[index++]), done: false };
             }
-            return { value: undefined, done: true };
+            if (!holdOpen) {
+              return { value: undefined, done: true };
+            }
+            return new Promise((_resolve, reject) => {
+              const onAbort = () => {
+                signal.removeEventListener('abort', onAbort);
+                const error = new Error('Aborted');
+                error.name = 'AbortError';
+                reject(error);
+              };
+              signal.addEventListener('abort', onAbort, { once: true });
+            });
           },
         };
       },
@@ -224,6 +235,86 @@ describe('delta coalescing in the global hub', () => {
 });
 
 describe('createGlobalMessageStreamHub', () => {
+  it('uses the replacement service endpoint and auth after rebind', async () => {
+    let generation = 0;
+    const urls = ['http://127.0.0.1:4096/api/event', 'http://127.0.0.1:5096/api/event'];
+    const auth = ['Basic first', 'Basic second'];
+    const fetchImpl = vi.fn(async (_url, options) => createSseResponse({
+      signal: options.signal,
+      holdOpen: true,
+    }));
+    const hub = createGlobalMessageStreamHub({
+      buildOpenCodeUrl: () => urls[generation],
+      getOpenCodeAuthHeaders: () => ({ Authorization: auth[generation] }),
+      fetchImpl,
+      upstreamReconnectDelayMs: 60_000,
+    });
+
+    try {
+      hub.start();
+      await waitForAssertion(() => expect(fetchImpl).toHaveBeenCalledTimes(1));
+
+      generation = 1;
+      hub.rebind();
+
+      await waitForAssertion(() => expect(fetchImpl).toHaveBeenCalledTimes(2));
+      expect(fetchImpl).toHaveBeenLastCalledWith(urls[1], expect.objectContaining({
+        headers: expect.objectContaining({ Authorization: auth[1] }),
+      }));
+    } finally {
+      hub.stop();
+    }
+  });
+
+  it('ignores a retired reader disconnect that completes after its replacement connects', async () => {
+    let finishRetiredRead;
+    let fetchCount = 0;
+    const statuses = [];
+    const fetchImpl = vi.fn(async (_url, options) => {
+      fetchCount += 1;
+      if (fetchCount === 1) {
+        return {
+          ok: true,
+          body: {
+            getReader() {
+              return {
+                read() {
+                  return new Promise((resolve) => {
+                    finishRetiredRead = () => resolve({ value: undefined, done: true });
+                  });
+                },
+              };
+            },
+          },
+        };
+      }
+      return createSseResponse({ signal: options.signal, holdOpen: true });
+    });
+    const hub = createGlobalMessageStreamHub({
+      buildOpenCodeUrl: (pathname) => `http://127.0.0.1:4096${pathname}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      fetchImpl,
+      upstreamReconnectDelayMs: 60_000,
+    });
+    hub.subscribeStatus((status) => statuses.push(status.type));
+
+    try {
+      hub.start();
+      await waitForAssertion(() => expect(statuses).toEqual(['connect']));
+
+      hub.rebind();
+      await waitForAssertion(() => expect(statuses).toEqual(['connect', 'connect']));
+      expect(hub.isConnected()).toBe(true);
+
+      finishRetiredRead();
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      expect(statuses).toEqual(['connect', 'connect']);
+      expect(hub.isConnected()).toBe(true);
+    } finally {
+      hub.stop();
+    }
+  });
+
   it('continues fanout when an event subscriber throws', async () => {
     const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
     const received = [];
@@ -321,3 +412,38 @@ describe('createGlobalMessageStreamHub', () => {
     }
   });
 });
+
+describe('events of isolated spaces in the global hub', () => {
+  const makeHub = () => createGlobalMessageStreamHub({
+    buildOpenCodeUrl: path => `http://127.0.0.1:4096${path}`,
+    getOpenCodeAuthHeaders: () => ({}),
+    deltaCoalesceWindowMs: 0,
+    fetchImpl: async () => createSseResponse({ blocks: [] }),
+  });
+
+  it('delivers an injected space event to subscribers that asked for spaces only, numbered and replayable like the host\'s', () => {
+    const hub = makeHub();
+    const plain = [];
+    const withSpaces = [];
+    hub.subscribeEvent(event => plain.push(event));
+    hub.subscribeEvent(event => withSpaces.push(event), { spaces: true });
+    hub.injectEvent({ payload: { type: 'session.execution.started', data: { sessionID: 's1' } }, directory: '/spaces/a1b2c3d4e5f6/repo', spaceId: 'a1b2c3d4e5f6' });
+    expect(plain).toHaveLength(0);
+    expect(withSpaces).toHaveLength(1);
+    expect(withSpaces[0]).toMatchObject({ spaceId: 'a1b2c3d4e5f6', directory: '/spaces/a1b2c3d4e5f6/repo' });
+    expect(withSpaces[0].eventId).toMatch(/^oc-/);
+    expect(withSpaces[0].translated()).toEqual([expect.objectContaining({ type: 'session.status' })]);
+    expect(JSON.parse(withSpaces[0].serialize())).toMatchObject({ type: 'event', directory: '/spaces/a1b2c3d4e5f6/repo', payload: { type: 'session.execution.started' } });
+    hub.injectEvent({ payload: { type: 'session.execution.succeeded', data: { sessionID: 's1' } }, directory: '/spaces/a1b2c3d4e5f6/repo', spaceId: 'a1b2c3d4e5f6' });
+    expect(hub.replayAfter(withSpaces[0].eventId).map(entry => entry.eventId)).toEqual([withSpaces[1].eventId]);
+  });
+
+  it('marks a host event with no space, so every subscriber sees it', () => {
+    const hub = makeHub();
+    const seen = [];
+    hub.subscribeEvent(event => seen.push(event.spaceId));
+    hub.subscribeEvent(event => seen.push(event.spaceId), { spaces: true });
+    hub.injectEvent({ payload: { type: 'session.execution.started', data: { sessionID: 's1' } }, directory: '/home/me', spaceId: null });
+    expect(seen).toEqual([null, null]);
+  });
+});

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

@@ -86,6 +86,8 @@ export function createGlobalMessageStreamWsBridge({
     }
   };
 
+  // Browser clients take the events of isolated spaces too: each frame carries its directory,
+  // and a space's directory is one more project directory to the UI.
   const unsubscribeEvent = globalHub.subscribeEvent((event) => {
     const { payload } = event;
     for (const socket of Array.from(clients)) {
@@ -111,7 +113,7 @@ export function createGlobalMessageStreamWsBridge({
         }
       }
     });
-  });
+  }, { spaces: true });
 
   const unsubscribeStatus = globalHub.subscribeStatus((status) => {
     if (status.type === 'connect') {