@vantran-se/openchamber-web 2.0.4 → 2.0.5

package/server/lib/guests/surface.test.js

@@ -35,8 +35,9 @@ const createFakeService = () => {
   };
   const nextFrameAfter = (seq) => frames.find((frame) => frame.seq > seq) ?? null;
   const completed = [];
-  const openServiceRequest = async ({ path, method, body, query, signal }) => {
-    calls.push({ path, method, body: body ? JSON.parse(body) : undefined, query });
+  let inputStatus = 204;
+  const openServiceRequest = async ({ path, method, body, query, headers, signal }) => {
+    calls.push({ path, method, body: body ? JSON.parse(body) : undefined, query, headers });
     if (failWith) throw failWith;
     if (path === SURFACE_INPUT_PATH && inputGate) {
       const gate = inputGate;
@@ -75,6 +76,8 @@ const createFakeService = () => {
       response = Response.json({ width: 640, height: 400 });
     } else if (path === SURFACE_CLIPBOARD_PATH) {
       response = Response.json({ text: 'copied inside' });
+    } else if (path === SURFACE_INPUT_PATH) {
+      response = new Response(null, { status: inputStatus });
     } else {
       response = new Response(null, { status: 204 });
     }
@@ -85,6 +88,7 @@ const createFakeService = () => {
     completed,
     pushFrame,
     gateNextInput: (promise) => { inputGate = promise; },
+    answerInputWith: (status) => { inputStatus = status; },
     fail: (error) => { failWith = error; for (const wake of waiters.splice(0)) wake(); },
     openServiceRequest,
     callsTo: (path) => calls.filter((call) => call.path === path),
@@ -101,7 +105,8 @@ const openViewer = (port, guestId = 'sim') => new Promise((resolve, reject) => {
   const inbox = [];
   const waiting = [];
   ws.on('message', (data, isBinary) => {
-    const item = isBinary ? { binary: Buffer.from(data) } : JSON.parse(data.toString());
+    // Bun's `ws` hands text frames over as a Uint8Array, not a Buffer.
+    const item = isBinary ? { binary: Buffer.from(data) } : JSON.parse(Buffer.from(data).toString('utf8'));
     const waiter = waiting.shift();
     if (waiter) waiter(item);
     else inbox.push(item);
@@ -214,13 +219,13 @@ describe('guest surface runtime', () => {
     await settle();
     expect(runtime.userControls('sim')).toBe(true);
     expect(service.callsTo(SURFACE_INPUT_PATH)[0].body).toEqual({ events: [click] });
-    expect(service.callsTo(SURFACE_CONTROL_PATH).map((call) => call.body)).toEqual([{ controller: 'user' }]);
+    expect(service.callsTo(SURFACE_CONTROL_PATH).map((call) => call.body)).toEqual([{ controller: 'user', viewer: 'viewer-1' }]);
 
     viewer.send({ type: 'release' });
     expect(await viewer.next()).toEqual({ type: 'control', controller: 'none', mine: false });
     await settle();
     expect(runtime.userControls('sim')).toBe(false);
-    expect(service.callsTo(SURFACE_CONTROL_PATH).map((call) => call.body)).toEqual([{ controller: 'user' }, { controller: 'none' }]);
+    expect(service.callsTo(SURFACE_CONTROL_PATH).map((call) => call.body)).toEqual([{ controller: 'user', viewer: 'viewer-1' }, { controller: 'none' }]);
   });
 
   test('a second viewer cannot take control from the first and is told who has it', async () => {
@@ -367,7 +372,7 @@ describe('guest surface runtime', () => {
     viewer.ws.close();
     await viewer.closed;
     await settle();
-    expect(service.callsTo(SURFACE_CONTROL_PATH).map((call) => call.body)).toEqual([{ controller: 'user' }, { controller: 'none' }]);
+    expect(service.callsTo(SURFACE_CONTROL_PATH).map((call) => call.body)).toEqual([{ controller: 'user', viewer: 'viewer-1' }, { controller: 'none' }]);
   });
 
   test('a queued input from before a hand-back does not take control again', async () => {
@@ -483,4 +488,49 @@ describe('guest surface runtime', () => {
     await again.closed;
     expect(runtime.sessionOf('sim')).toBeNull();
   });
+
+  test('stamps input with the viewer and the service frame it last drew', async () => {
+    const { port, service, runtime } = await createHarness();
+    const viewer = await openViewer(port);
+    await viewer.next(); // hello
+    await viewer.next(); // control
+    const click = { type: 'pointer', action: 'down', x: 1, y: 1, button: 0, buttons: 1, modifiers: { alt: false, ctrl: false, meta: false, shift: false } };
+
+    // Nothing drawn yet: frame 0.
+    viewer.send({ type: 'input', events: [click] });
+    await settle();
+    expect(service.callsTo(SURFACE_INPUT_PATH)[0].headers).toEqual({ 'x-surface-viewer': 'viewer-1', 'x-surface-frame-seq': '0' });
+    expect(service.callsTo(SURFACE_CONTROL_PATH).at(-1).body).toEqual({ controller: 'user', viewer: 'viewer-1' });
+    await viewer.next(); // control: mine
+
+    service.pushFrame({ seq: 7, bytes: Buffer.from('frame-7') });
+    await viewer.next();
+    await viewer.next();
+    // Sent but not yet drawn: input still counts as made on the old picture.
+    viewer.send({ type: 'input', events: [click] });
+    viewer.send({ type: 'ack', seq: 7 });
+    viewer.send({ type: 'input', events: [click] });
+    await settle();
+    const stamped = service.callsTo(SURFACE_INPUT_PATH).map((call) => call.headers['x-surface-frame-seq']);
+    expect(stamped).toEqual(['0', '0', '7']);
+
+    expect(runtime.viewerHeaders('sim', 'viewer-1')).toEqual({ 'x-surface-viewer': 'viewer-1', 'x-surface-viewer-controls': '1', 'x-surface-frame-seq': '7' });
+    expect(runtime.viewerHeaders('sim', 'viewer-2')).toBeNull();
+    expect(runtime.viewerHeaders('other', 'viewer-1')).toBeNull();
+
+    viewer.send({ type: 'release' });
+    await settle();
+    expect(runtime.viewerHeaders('sim', 'viewer-1')['x-surface-viewer-controls']).toBe('0');
+  });
+
+  test('tells the viewer when the service refuses input made on an old picture', async () => {
+    const { port, service } = await createHarness();
+    const viewer = await openViewer(port);
+    await viewer.next();
+    await viewer.next();
+    service.answerInputWith(409);
+    viewer.send({ type: 'input', events: [{ type: 'text', text: 'hi' }] });
+    await viewer.next(); // control: mine
+    expect(await viewer.next()).toMatchObject({ type: 'error', code: 'INPUT_STALE' });
+  });
 });

package/server/lib/notifications/DOCUMENTATION.md

@@ -9,6 +9,7 @@ This module provides notification message preparation utilities for the web serv
 - `packages/web/server/lib/notifications/push-runtime.js`: push subscription persistence, VAPID initialization, and UI visibility runtime.
 - `packages/web/server/lib/notifications/apns-runtime.js`: native iOS APNs device-token persistence + delivery. Two modes: **relay** (default — sign + POST tokens + generic text to the central Cloudflare relay `https://api.openchamber.dev/v1/push/send`, which holds the single project APNs key) and **direct** (fallback — sign ES256 JWT with Node crypto + HTTP/2, when `OPENCHAMBER_PUSH_RELAY_DISABLED=true`). Each server has an auto-generated ECDSA P-256 keypair (`getOrCreateRelayKeypair`, persisted in settings); it binds tokens on the relay (`/v1/push/register-token`) and signs every relay request, so the relay only delivers to tokens bound to that server. APNs is the native app's sole notification channel (no local notifications) and is NOT gated on UI visibility — iOS suppresses the foreground banner instead. Mobile push carries only generic text (scenario title + session name) — see `APNS.md`.
 - `packages/web/server/lib/notifications/emitter-runtime.js`: desktop/stdout + UI SSE notification emission runtime.
+- `packages/web/server/lib/notifications/emit-route.js`: `POST /api/notifications/emit` for OpenCode plugins.
 - `packages/web/server/lib/notifications/runtime.js`: trigger runtime for OpenCode event-driven notification fanout.
 - `packages/web/server/lib/notifications/template-runtime.js`: notification template variables and session text/title enrichment runtime. Zen-model helpers are retained as compatibility stubs only.
 - `packages/web/server/lib/notifications/message.js`: helper implementation module.
@@ -82,6 +83,15 @@ This module provides notification message preparation utilities for the web serv
   - `emitDesktopNotification(payload)`
   - `broadcastUiNotification(payload)`
 
+### Plugin notification route (emit-route.js)
+- `createPluginNotificationEmitter(dependencies)` owns validation, the rate window and delivery; one instance is shared by the HTTP route and the `openchamber_notify` agent tool (`notify.send`).
+- `registerNotificationEmitRoutes(app, dependencies)` returns `registerPluginRoute()` and `registerApiRoute()`. Bootstrap calls the first before API auth and the second after it.
+- Callers: a plugin in the managed OpenCode (agent-tool bearer token, the only reason for the pre-auth registration) or any client that passes regular API auth. No other auth path exists.
+- Body `{ title?, body?, tag?, sessionId?, directory?, showWhenFocused? }`, at least one of title/body; title ≤120, body ≤500 chars, 16kb JSON. `kind` is always `plugin` so callers cannot trigger kinds the UI treats specially.
+- One shared rate window: 10 notifications per 10s, then 429 with `Retry-After`.
+- Follows `nativeNotificationsEnabled` (returns `{ delivered: false }`) and `notificationMode` (`requireHidden`); `showWhenFocused: true` sends `requireHidden: false` so the notice shows even while OpenChamber is focused. Live delivery only: no web push or APNs fanout.
+- Advertised as the `api.notifications.emit.v1` server capability.
+
 ### Template runtime API (template-runtime.js)
 - `createNotificationTemplateRuntime(dependencies)`: creates shared notification/template runtime. Model-backed summarization was retired after the Zen provider became unavailable.
 - Returned API:

package/server/lib/notifications/emit-route.js

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+
+const NOTIFICATION_EMIT_PATH = '/api/notifications/emit';
+
+const RATE_WINDOW_MS = 10_000;
+const RATE_MAX_PER_WINDOW = 10;
+
+const optionalText = (max) => z.string().trim().min(1).max(max).optional();
+
+const emitBodySchema = z.object({
+  title: optionalText(120),
+  body: optionalText(500),
+  tag: optionalText(128),
+  sessionId: optionalText(128),
+  directory: optionalText(4096),
+  // Opt-in for notices that matter even while OpenChamber is in front.
+  showWhenFocused: z.boolean().optional(),
+}).refine((value) => value.title || value.body, { message: 'title or body required' });
+
+/**
+ * Raises a notification on behalf of a plugin or the agent, through the same
+ * live delivery the built-in triggers use. `kind` is always `plugin`, so a
+ * caller cannot impersonate kinds the UI treats specially. One rate window is
+ * shared by every caller, the HTTP route and the agent tool alike.
+ *
+ * `emit` resolves to `{ status, body }`: 200 delivered or skipped by settings,
+ * 400 invalid input, 429 rate limited (with `retryAfter` seconds).
+ */
+export const createPluginNotificationEmitter = (dependencies) => {
+  const {
+    readSettingsFromDiskMigrated,
+    emitDesktopNotification,
+    broadcastUiNotification,
+    now = Date.now,
+  } = dependencies;
+
+  let windowStartedAt = 0;
+  let windowCount = 0;
+
+  const takeRateSlot = () => {
+    const current = now();
+    if (current - windowStartedAt >= RATE_WINDOW_MS) {
+      windowStartedAt = current;
+      windowCount = 0;
+    }
+    if (windowCount >= RATE_MAX_PER_WINDOW) {
+      return Math.ceil((windowStartedAt + RATE_WINDOW_MS - current) / 1000);
+    }
+    windowCount += 1;
+    return 0;
+  };
+
+  const emit = async (input) => {
+    const parsed = emitBodySchema.safeParse(input);
+    if (!parsed.success) {
+      return { status: 400, body: { error: parsed.error.issues[0]?.message ?? 'invalid notification' } };
+    }
+
+    const retryAfter = takeRateSlot();
+    if (retryAfter > 0) {
+      return { status: 429, retryAfter, body: { error: 'too many notifications' } };
+    }
+
+    const settings = await readSettingsFromDiskMigrated();
+    if (settings.nativeNotificationsEnabled === false) {
+      return { status: 200, body: { delivered: false, reason: 'notifications-disabled' } };
+    }
+
+    const payload = {
+      title: parsed.data.title ?? 'OpenChamber',
+      body: parsed.data.body,
+      tag: parsed.data.tag,
+      kind: 'plugin',
+      sessionId: parsed.data.sessionId,
+      directory: parsed.data.directory,
+      requireHidden: parsed.data.showWhenFocused !== true && settings.notificationMode !== 'always',
+    };
+    const desktopNotificationDelivered = emitDesktopNotification(payload) === true;
+    broadcastUiNotification(payload, { desktopNotificationDelivered });
+    return { status: 200, body: { delivered: true } };
+  };
+
+  return { emit };
+};
+
+/**
+ * `POST /api/notifications/emit`. Two callers are accepted: a plugin inside
+ * the managed OpenCode (the agent-tool bearer token, checked before API auth)
+ * and any client that passes the regular API auth.
+ */
+export const registerNotificationEmitRoutes = (app, dependencies) => {
+  const { express, isAgentToolRequestAuthorized, emitter } = dependencies;
+
+  const jsonBody = express.json({ limit: '16kb' });
+
+  const respond = async (req, res, next) => {
+    try {
+      const result = await emitter.emit(req.body);
+      if (result.retryAfter) res.setHeader('Retry-After', String(result.retryAfter));
+      return res.status(result.status).json(result.body);
+    } catch (error) {
+      return next(error);
+    }
+  };
+
+  return {
+    // Registered before API auth: a managed plugin carries no UI session.
+    registerPluginRoute: () => {
+      app.post(NOTIFICATION_EMIT_PATH, jsonBody, (req, res, next) => (
+        isAgentToolRequestAuthorized(req) ? respond(req, res, next) : next()
+      ));
+    },
+    // Registered after API auth: everything else is an ordinary API caller.
+    registerApiRoute: () => {
+      app.post(NOTIFICATION_EMIT_PATH, jsonBody, respond);
+    },
+  };
+};

package/server/lib/notifications/emit-route.test.js

@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest';
+import express from 'express';
+import request from 'supertest';
+import { createPluginNotificationEmitter, registerNotificationEmitRoutes } from './emit-route.js';
+
+const PLUGIN_TOKEN = 'Bearer plugin-token';
+const UI_TOKEN = 'Bearer ui-token';
+
+const createApp = ({ settings = { nativeNotificationsEnabled: true, notificationMode: 'hidden-only' }, now = () => 0 } = {}) => {
+  const delivered = [];
+  const app = express();
+  const emitter = createPluginNotificationEmitter({
+    readSettingsFromDiskMigrated: async () => settings,
+    emitDesktopNotification: () => false,
+    broadcastUiNotification: (payload, options) => delivered.push({ payload, options }),
+    now,
+  });
+  const routes = registerNotificationEmitRoutes(app, {
+    express,
+    isAgentToolRequestAuthorized: (req) => req.headers.authorization === PLUGIN_TOKEN,
+    emitter,
+  });
+  routes.registerPluginRoute();
+  // Stands in for the server's API auth gate between the two registrations.
+  app.use('/api', (req, res, next) => (
+    req.headers.authorization === UI_TOKEN ? next() : res.status(401).json({ error: 'UI session missing' })
+  ));
+  routes.registerApiRoute();
+  return { app, delivered };
+};
+
+describe('POST /api/notifications/emit', () => {
+  it('delivers a plugin notification without a UI session', async () => {
+    const { app, delivered } = createApp();
+    const response = await request(app)
+      .post('/api/notifications/emit')
+      .set('Authorization', PLUGIN_TOKEN)
+      .send({ title: ' Build done ', body: 'Ready', sessionId: 'ses_1' });
+
+    expect(response.status).toBe(200);
+    expect(response.body).toEqual({ delivered: true });
+    expect(delivered).toEqual([{
+      payload: {
+        title: 'Build done',
+        body: 'Ready',
+        tag: undefined,
+        kind: 'plugin',
+        sessionId: 'ses_1',
+        directory: undefined,
+        requireHidden: true,
+      },
+      options: { desktopNotificationDelivered: false },
+    }]);
+  });
+
+  it('accepts an ordinary API caller and rejects an unauthenticated one', async () => {
+    const { app, delivered } = createApp();
+    await request(app).post('/api/notifications/emit').set('Authorization', UI_TOKEN).send({ body: 'Hi' }).expect(200);
+    await request(app).post('/api/notifications/emit').send({ body: 'Hi' }).expect(401);
+    await request(app).post('/api/notifications/emit').set('Authorization', 'Bearer wrong').send({ body: 'Hi' }).expect(401);
+    expect(delivered.map(({ payload }) => payload.title)).toEqual(['OpenChamber']);
+  });
+
+  it('never lets a caller choose the notification kind', async () => {
+    const { app, delivered } = createApp();
+    await request(app)
+      .post('/api/notifications/emit')
+      .set('Authorization', PLUGIN_TOKEN)
+      .send({ title: 'x', kind: 'opencode-restart-interrupted' })
+      .expect(200);
+    expect(delivered[0].payload.kind).toBe('plugin');
+  });
+
+  it('rejects empty and oversized payloads', async () => {
+    const { app, delivered } = createApp();
+    const post = (body) => request(app).post('/api/notifications/emit').set('Authorization', PLUGIN_TOKEN).send(body);
+    await post({}).expect(400);
+    await post({ title: '   ' }).expect(400);
+    await post({ title: 'x'.repeat(121) }).expect(400);
+    await post({ body: 'x'.repeat(501) }).expect(400);
+    expect(delivered).toEqual([]);
+  });
+
+  it('limits the rate and recovers after the window', async () => {
+    let clock = 0;
+    const { app, delivered } = createApp({ now: () => clock });
+    const post = () => request(app).post('/api/notifications/emit').set('Authorization', PLUGIN_TOKEN).send({ body: 'tick' });
+    for (let index = 0; index < 10; index += 1) await post().expect(200);
+    const limited = await post();
+    expect(limited.status).toBe(429);
+    expect(limited.headers['retry-after']).toBe('10');
+    clock = 10_000;
+    await post().expect(200);
+    expect(delivered).toHaveLength(11);
+  });
+
+  it('follows the notifications setting and the always mode', async () => {
+    const off = createApp({ settings: { nativeNotificationsEnabled: false } });
+    const skipped = await request(off.app).post('/api/notifications/emit').set('Authorization', PLUGIN_TOKEN).send({ body: 'x' });
+    expect(skipped.body).toEqual({ delivered: false, reason: 'notifications-disabled' });
+    expect(off.delivered).toEqual([]);
+
+    const always = createApp({ settings: { nativeNotificationsEnabled: true, notificationMode: 'always' } });
+    await request(always.app).post('/api/notifications/emit').set('Authorization', PLUGIN_TOKEN).send({ body: 'x' }).expect(200);
+    expect(always.delivered[0].payload.requireHidden).toBe(false);
+
+    const focused = createApp();
+    await request(focused.app).post('/api/notifications/emit').set('Authorization', PLUGIN_TOKEN).send({ body: 'x', showWhenFocused: true }).expect(200);
+    expect(focused.delivered[0].payload.requireHidden).toBe(false);
+    await request(focused.app).post('/api/notifications/emit').set('Authorization', PLUGIN_TOKEN).send({ body: 'x', showWhenFocused: 'yes' }).expect(400);
+  });
+});

package/server/lib/openchamber-control/actions.js

@@ -38,8 +38,8 @@ export const OPENCHAMBER_AGENT_TOOL_ACTIONS = Object.freeze(
 );
 
 export const OPENCHAMBER_WEB_ACTION_DEFINITIONS = Object.freeze([
-  { action: 'browser.open', title: 'Open a page in the browser panel', description: 'Open url in the in-app browser panel; use it to look at the running app. Set viewport to mobile, tablet or desktop to lay the page out at that size' },
-  { action: 'browser.snapshot', title: 'Read the open page', description: 'Read the open page: url, title, visible text, and interactive elements with the selectors the other browser actions accept. Pass selector to read only that part of a long page. Reports any errors the page logged' },
+  { action: 'browser.open', title: 'Open a page in the browser panel', description: 'Open url in the in-app browser panel; use it to look at the running app. Without tabId it opens a new background tab and answers with its tabId: pass that tabId to the following actions to keep working there. With tabId it loads url in that tab. Set viewport to mobile, tablet or desktop to lay the page out at that size' },
+  { action: 'browser.snapshot', title: 'Read the open page', description: 'Read the open page: url, title, visible text, and interactive elements with the selectors the other browser actions accept. Pass selector to read only that part of a long page. Reports any errors the page logged, and lists the open tabs with the ids tabId accepts' },
   { action: 'browser.click', title: 'Click on the open page', description: 'Click an element; give selector, or text to match a link or button by its visible label' },
   { action: 'browser.type', title: 'Type into the open page', description: 'Type value into the field matched by selector; set submit to press Enter afterwards' },
   { action: 'browser.scroll', title: 'Scroll the open page', description: 'Scroll the page; direction is up, down, top, or bottom, or pass selector to bring one element into view' },
@@ -76,6 +76,18 @@ export const OPENCHAMBER_MEMORY_ACTIONS = Object.freeze(
   OPENCHAMBER_MEMORY_ACTION_DEFINITIONS.map(({ action }) => action),
 );
 
+/**
+ * Notify is its own tool so it can stay off by default and disappear
+ * completely: an agent that can page the user is a choice the user makes.
+ */
+export const OPENCHAMBER_NOTIFY_ACTION_DEFINITIONS = Object.freeze([
+  { action: 'notify.send', title: 'Notify the user', description: 'Send the user a notification; requires title, body is optional. By default it appears only while the user is away from OpenChamber; set showWhenFocused only when it cannot wait' },
+]);
+
+export const OPENCHAMBER_NOTIFY_ACTIONS = Object.freeze(
+  OPENCHAMBER_NOTIFY_ACTION_DEFINITIONS.map(({ action }) => action),
+);
+
 /**
  * Which actions each managed tool may ask for.
  *
@@ -90,6 +102,7 @@ const ACTIONS_BY_TOOL = Object.freeze({
   openchamber: OPENCHAMBER_AGENT_TOOL_ACTIONS,
   openchamber_web: OPENCHAMBER_WEB_ACTIONS,
   openchamber_memory: OPENCHAMBER_MEMORY_ACTIONS,
+  openchamber_notify: OPENCHAMBER_NOTIFY_ACTIONS,
 });
 
 const bareName = (action) => {
@@ -136,4 +149,5 @@ export const OPENCHAMBER_ALL_ACTIONS = Object.freeze([
   ...OPENCHAMBER_CONTROL_ACTIONS,
   ...OPENCHAMBER_WEB_ACTIONS,
   ...OPENCHAMBER_MEMORY_ACTIONS,
+  ...OPENCHAMBER_NOTIFY_ACTIONS,
 ]);

package/server/lib/openchamber-control/service.js

@@ -154,6 +154,7 @@ export const createOpenChamberControlService = (dependencies) => {
     scheduledTaskService,
     browserControl = null,
     fileOpen = null,
+    notifyUser = null,
     agentMemoryActions = null,
     // Archive lives in OpenChamber's own store now — v2 has no route that sets
     // Session.time.archived — so an unwired store simply means nothing is archived.
@@ -365,6 +366,12 @@ export const createOpenChamberControlService = (dependencies) => {
    */
   const browserAction = async (action, input, signal, contextDirectory, contextSessionId) => {
     const parameters = {};
+    // Any action may name a tab; the browser that issued the id resolves it.
+    const tabId = asNonEmptyString(input.tabId);
+    if (tabId) {
+      if (tabId.length > 128) throw new OpenChamberControlError('tabId must be an id from browser.snapshot tabs', 400);
+      parameters.tabId = tabId;
+    }
 
     const readViewport = (required) => {
       const viewport = asNonEmptyString(input.viewport);
@@ -511,6 +518,22 @@ export const createOpenChamberControlService = (dependencies) => {
         }
         return browserAction(action, input, options.signal, contextDirectory, options.contextSessionId);
       }
+      if (action === 'notify.send') {
+        if (!notifyUser) {
+          throw new OpenChamberControlError('Notifications are not available on this server', 503);
+        }
+        const result = await notifyUser({
+          title: input.title,
+          body: input.body,
+          showWhenFocused: input.showWhenFocused,
+          sessionId: asNonEmptyString(options.contextSessionId) || undefined,
+          directory: asNonEmptyString(contextDirectory) || undefined,
+        });
+        if (result.status !== 200) {
+          throw new OpenChamberControlError(result.body.error, result.status);
+        }
+        return result.body;
+      }
       if (action === 'file.open') {
         if (!fileOpen) {
           throw new OpenChamberControlError('The file viewer is not available on this server', 503);

package/server/lib/openchamber-control/service.test.js

@@ -294,6 +294,31 @@ describe('file.open', () => {
   });
 });
 
+describe('notify.send', () => {
+  it('sends the notice for the calling session and returns what was delivered', async () => {
+    const notifyUser = vi.fn(async () => ({ status: 200, body: { delivered: true } }));
+    const { service } = createService({ notifyUser });
+
+    const result = await service.execute('notify.send', { title: 'Done', body: 'All green', showWhenFocused: true }, '/repo', { contextSessionId: 'ses_1' });
+
+    expect(notifyUser).toHaveBeenCalledWith({ title: 'Done', body: 'All green', showWhenFocused: true, sessionId: 'ses_1', directory: '/repo' });
+    expect(result).toEqual({ delivered: true });
+  });
+
+  it('turns a refused notice into an error the agent can read', async () => {
+    const notifyUser = vi.fn(async () => ({ status: 429, retryAfter: 4, body: { error: 'too many notifications' } }));
+    const { service } = createService({ notifyUser });
+
+    await expect(service.execute('notify.send', { title: 'Done' }, '/repo'))
+      .rejects.toMatchObject({ statusCode: 429, message: 'too many notifications' });
+  });
+
+  it('answers 503 when this server has no notifier wired', async () => {
+    const { service } = createService({});
+    await expect(service.execute('notify.send', { title: 'Done' }, '/repo')).rejects.toMatchObject({ statusCode: 503 });
+  });
+});
+
 describe('browser capture', () => {
   const pixel = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
 
@@ -338,6 +363,12 @@ describe('browser capture', () => {
     await expect(service.execute('browser.capture', {})).rejects.toThrow(/directory is required/);
   });
 
+  it('passes the tab the agent named to the browser', async () => {
+    const { service, directory, request } = await createBrowserService({ base64: pixel, mime: 'image/png' });
+    await service.execute('browser.capture', { tabId: ' tab-2 ' }, directory);
+    expect(request).toHaveBeenCalledWith('browser.capture', { tabId: 'tab-2' }, expect.anything());
+  });
+
   it('passes a label through to the browser and leaves other actions untouched', async () => {
     const { service, directory, request } = await createBrowserService({ base64: pixel, mime: 'image/png' });
     await service.execute('browser.capture', { label: 'before' }, directory);

package/server/lib/openchamber-sessions/fork-inheritance.js

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+
+/**
+ * What a fork made through the OpenChamber sessions API (CLI, scheduled tasks)
+ * keeps from its source session's OpenChamber metadata. Server twin of the UI's
+ * `packages/ui/src/lib/sessionForkInheritance.ts`: UI forks call OpenCode
+ * directly and repair themselves; forks made here are repaired here.
+ *
+ * OpenCode 2.x copies the source's `metadata` wholesale into the fork, so the
+ * goal already arrives. Two repairs remain:
+ *
+ * - Source-owned links: the source's btw fork (`btwSessionID`), its review
+ *   session (`reviewSessionID`), and the btw marker when the source is itself a
+ *   btw side thread.
+ * - A file-backed goal objective: the text lives in a file keyed by the session
+ *   id, so the fork needs its own copy. When the copy cannot be written the
+ *   fork's goal carries the text inline instead.
+ */
+
+const NamespaceSchema = z.looseObject({
+  btwSessionID: z.unknown().optional(),
+  reviewSessionID: z.unknown().optional(),
+  kind: z.unknown().optional(),
+  goal: z.unknown().optional(),
+});
+const FileBackedGoalSchema = z.looseObject({ id: z.string().min(1), objectiveFile: z.literal(true) });
+
+const openChamberNamespace = (metadata) => {
+  const parsed = z.looseObject({ openchamber: NamespaceSchema }).safeParse(metadata);
+  return parsed.success ? parsed.data.openchamber : null;
+};
+
+/** Merge patch (RFC 7386) removing source-owned links; null when there are none. */
+export const sourceOwnedLinksPatch = (metadata) => {
+  const namespace = openChamberNamespace(metadata);
+  if (!namespace) return null;
+  const patch = {};
+  for (const key of ['btwSessionID', 'reviewSessionID']) {
+    if (key in namespace) patch[key] = null;
+  }
+  if (namespace.kind === 'btw') {
+    for (const key of ['kind', 'originalSessionID', 'btwBoundaryMessageID']) {
+      if (key in namespace) patch[key] = null;
+    }
+  }
+  // A fork must not pursue the source's goal in parallel: an active goal
+  // arrives paused and the user resumes it (same rule as UI forks).
+  const goal = namespace.goal;
+  if (goal && typeof goal === 'object' && !Array.isArray(goal) && goal.status === 'active') {
+    patch.goal = { status: 'paused', statusReason: 'paused in fork' };
+  }
+  return Object.keys(patch).length > 0 ? patch : null;
+};
+
+const fileBackedGoal = (metadata) => {
+  const parsed = FileBackedGoalSchema.safeParse(openChamberNamespace(metadata)?.goal);
+  return parsed.success ? parsed.data : null;
+};
+
+/**
+ * Repair a freshly created fork. Best-effort: the fork already exists and is
+ * usable, so every failure is logged and swallowed.
+ *
+ * @param {object} options
+ * @param {string} options.sourceSessionID
+ * @param {{ id: string, metadata?: object }} options.fork The fork record OpenCode returned.
+ * @param {(sessionID: string) => Promise<string | null>} options.readObjective
+ * @param {(sessionID: string, content: string) => Promise<unknown>} options.writeObjective Throws on failure.
+ * @param {(sessionID: string, patch: object) => Promise<unknown>} options.writeMetadata
+ */
+export const applyForkInheritance = async ({ sourceSessionID, fork, readObjective, writeObjective, writeMetadata }) => {
+  const metadata = fork?.metadata;
+  const goal = fileBackedGoal(metadata);
+  let inlineObjective = null;
+  if (goal) {
+    try {
+      const content = await readObjective(sourceSessionID);
+      if (content === null) {
+        console.warn('[fork] source goal objective unavailable; fork keeps the inline fallback');
+      } else {
+        try {
+          await writeObjective(fork.id, content);
+        } catch (error) {
+          console.warn('[fork] failed to copy the goal objective file; inlining it', error?.message ?? error);
+          inlineObjective = content;
+        }
+      }
+    } catch (error) {
+      console.warn('[fork] failed to read the source goal objective', error?.message ?? error);
+    }
+  }
+
+  const namespacePatch = sourceOwnedLinksPatch(metadata) ?? {};
+  if (inlineObjective !== null) {
+    namespacePatch.goal = { ...namespacePatch.goal, objective: inlineObjective, objectiveFile: false };
+  }
+  if (Object.keys(namespacePatch).length === 0) return;
+  try {
+    await writeMetadata(fork.id, { openchamber: namespacePatch });
+  } catch (error) {
+    console.warn('[fork] failed to update the fork metadata', error?.message ?? error);
+  }
+};