@vantran-se/openchamber-web 1.24.3 → 2.0.1

package/server/lib/notifications/push-runtime.js

@@ -15,7 +15,8 @@ export const createPushRuntime = (deps) => {
   const {
     fsPromises,
     path,
-    webPush,
+    // Resolves the web-push module; it is loaded on first use, not with the server.
+    loadWebPush,
     PUSH_SUBSCRIPTIONS_FILE_PATH,
     readSettingsFromDiskMigrated,
     writeSettingsToDisk,
@@ -86,6 +87,7 @@ export const createPushRuntime = (deps) => {
       return { publicKey: existing.publicKey, privateKey: existing.privateKey };
     }
 
+    const webPush = await loadWebPush();
     const generated = webPush.generateVAPIDKeys();
     const next = {
       ...settings,
@@ -210,6 +212,7 @@ export const createPushRuntime = (deps) => {
     };
 
     try {
+      const webPush = await loadWebPush();
       await webPush.sendNotification(pushSubscription, body);
     } catch (error) {
       const statusCode = typeof error?.statusCode === 'number' ? error.statusCode : null;
@@ -344,6 +347,7 @@ export const createPushRuntime = (deps) => {
       console.warn('[Push] No public origin configured for VAPID; set OPENCHAMBER_VAPID_SUBJECT or enable push once from a real origin.');
     }
 
+    const webPush = await loadWebPush();
     webPush.setVapidDetails(subject, keys.publicKey, keys.privateKey);
     pushInitialized = true;
   };

package/server/lib/notifications/push-runtime.test.js

@@ -9,11 +9,11 @@ const createRuntime = () => createPushRuntime({
     writeFile: vi.fn(async () => {}),
   },
   path: { dirname: () => '/tmp' },
-  webPush: {
+  loadWebPush: async () => ({
     generateVAPIDKeys: vi.fn(() => ({ publicKey: 'public', privateKey: 'private' })),
     sendNotification: vi.fn(async () => {}),
     setVapidDetails: vi.fn(),
-  },
+  }),
   PUSH_SUBSCRIPTIONS_FILE_PATH: '/tmp/push-subscriptions.json',
   readSettingsFromDiskMigrated: vi.fn(async () => ({})),
   writeSettingsToDisk: vi.fn(async () => {}),

package/server/lib/notifications/routes.js

@@ -297,7 +297,7 @@ export const registerNotificationRoutes = (app, dependencies) => {
   });
 
   // Cross-project seed for clients that do not initialize every directory:
-  // live status per session plus the permission and question requests still
+  // live status per session plus the permission requests and forms still
   // waiting for an answer. Both come from the server's single upstream stream.
   app.get('/api/sessions/status', async (_req, res) => {
     await ensureSessionWatcher();

package/server/lib/notifications/runtime.js

@@ -1,3 +1,7 @@
+import { unwrapOpenCodeResponse } from '../opencode/response-envelope.js';
+import { createSessionActivityProbe } from '../opencode/session-activity.js';
+
+
 export const createNotificationTriggerRuntime = (deps) => {
   const {
     readSettingsFromDisk,
@@ -14,8 +18,22 @@ export const createNotificationTriggerRuntime = (deps) => {
     isAnyInteractiveClientVisible,
     buildOpenCodeUrl,
     getOpenCodeAuthHeaders,
+    // OpenChamber's own session metadata (the goal lives there, not on the
+    // OpenCode record). Optional: without it no goal can suppress a push.
+    readSessionMetadata = null,
   } = deps;
   let getIsSessionAutoAccepting = deps.getIsSessionAutoAccepting;
+  const activityProbe = createSessionActivityProbe({ buildOpenCodeUrl, getOpenCodeAuthHeaders, timeoutMs: 2000 });
+
+  // A parent goes idle while a background subagent still works; OpenCode then
+  // hands the result back and the parent runs again. That first idle is a
+  // pause, so it announces nothing. When the check cannot be made, the idle is
+  // announced as before: a missed "ready" is worse than an early one.
+  const isPausedForSubagents = async (sessionId) => {
+    const statuses = await activityProbe.fetchActiveSessionStatuses();
+    if (!statuses) return false;
+    return (await activityProbe.hasWorkingChildren(sessionId, statuses)) === true;
+  };
   const setGetIsSessionAutoAccepting = (resolver) => {
     getIsSessionAutoAccepting = typeof resolver === 'function' ? resolver : undefined;
   };
@@ -157,8 +175,57 @@ export const createNotificationTriggerRuntime = (deps) => {
   const getParentIdFromPayload = (payload) => {
     if (!payload || typeof payload !== 'object') return undefined;
     if (payload.type !== 'session.created' && payload.type !== 'session.updated') return undefined;
-    const parentID = payload.properties?.info?.parentID ?? null;
-    return typeof parentID === 'string' && parentID.length > 0 ? parentID : null;
+    const parentID = payload.properties?.info?.parentID;
+    if (typeof parentID === 'string' && parentID.length > 0) return parentID;
+    // Only the full record from `session.created` proves a session has no
+    // parent. `session.updated` also carries partial records (usage, title)
+    // without `parentID`, and reading those as "no parent" turned a subagent
+    // into a main session, so its finish announced "ready" with subagent
+    // notifications turned off.
+    return payload.type === 'session.created' ? null : undefined;
+  };
+
+  // v2 splits one assistant turn over two events: `session.step.started`
+  // names the agent and model, `session.step.ended` carries the finish. The
+  // translator hands both over as `message.updated` on the same message id,
+  // so the start is remembered here and folded into the finish, which is the
+  // event the "ready" push is built from. Bounded: a session emits a handful
+  // of steps and the map is per process.
+  const ASSISTANT_STEP_CACHE_LIMIT = 500;
+  const assistantStepMeta = new Map();
+  // The reply a turn ended on: the idle event names only the session, so the
+  // ready notification borrows this step's id for its agent, model and text.
+  const lastAssistantStepBySession = new Map();
+  const rememberAssistantStep = (info) => {
+    if (!info || info.role !== 'assistant') return;
+    const id = String(info.id ?? '');
+    const agent = String(info.agent ?? info.mode ?? '');
+    const modelID = String(info.modelID ?? '');
+    if (!id || (!agent && !modelID)) return;
+    assistantStepMeta.delete(id);
+    assistantStepMeta.set(id, { agent, modelID });
+    const sessionId = String(info.sessionID ?? '');
+    if (sessionId) {
+      lastAssistantStepBySession.delete(sessionId);
+      lastAssistantStepBySession.set(sessionId, id);
+      while (lastAssistantStepBySession.size > ASSISTANT_STEP_CACHE_LIMIT) {
+        lastAssistantStepBySession.delete(lastAssistantStepBySession.keys().next().value);
+      }
+    }
+    while (assistantStepMeta.size > ASSISTANT_STEP_CACHE_LIMIT) {
+      assistantStepMeta.delete(assistantStepMeta.keys().next().value);
+    }
+  };
+  const withRememberedStep = (info) => {
+    const remembered = info ? assistantStepMeta.get(String(info.id ?? '')) : undefined;
+    if (!remembered) return info;
+    const merged = { ...info };
+    if (!merged.agent && !merged.mode) {
+      merged.agent = remembered.agent;
+      merged.mode = remembered.agent;
+    }
+    if (!merged.modelID) merged.modelID = remembered.modelID;
+    return merged;
   };
 
   const maybeCacheSessionParentFromPayload = (payload) => {
@@ -177,7 +244,7 @@ export const createNotificationTriggerRuntime = (deps) => {
     if (cached !== undefined) return cached;
 
     try {
-      const base = buildOpenCodeUrl(`/session/${encodeURIComponent(sessionId)}`, '');
+      const base = buildOpenCodeUrl(`/api/session/${encodeURIComponent(sessionId)}`, '');
       const url = directory ? `${base}?directory=${encodeURIComponent(directory)}` : base;
       const response = await fetch(url, {
         method: 'GET',
@@ -190,7 +257,7 @@ export const createNotificationTriggerRuntime = (deps) => {
       if (!response.ok) {
         return undefined;
       }
-      const session = await response.json().catch(() => null);
+      const session = unwrapOpenCodeResponse(await response.json().catch(() => null));
       if (!session || typeof session !== 'object') {
         return undefined;
       }
@@ -281,19 +348,11 @@ export const createNotificationTriggerRuntime = (deps) => {
   // A session with an ACTIVE goal suppresses per-turn ready notifications;
   // the session-goal runtime sends its own notification when the goal
   // settles. Fetch failures fall through to normal notification behavior.
-  const hasActiveSessionGoal = async (sessionId, directory) => {
-    if (!sessionId) return false;
+  const hasActiveSessionGoal = async (sessionId) => {
+    if (!sessionId || typeof readSessionMetadata !== 'function') return false;
     try {
-      const base = buildOpenCodeUrl(`/session/${encodeURIComponent(sessionId)}`, '');
-      const url = directory ? `${base}?directory=${encodeURIComponent(directory)}` : base;
-      const response = await fetch(url, {
-        method: 'GET',
-        headers: { Accept: 'application/json', ...getOpenCodeAuthHeaders() },
-        signal: AbortSignal.timeout(2000),
-      });
-      if (!response.ok) return false;
-      const session = await response.json().catch(() => null);
-      const goal = session?.metadata?.openchamber?.goal;
+      const metadata = await readSessionMetadata(sessionId);
+      const goal = metadata?.openchamber?.goal;
       return Boolean(goal && typeof goal === 'object' && goal.status === 'active');
     } catch {
       return false;
@@ -309,7 +368,16 @@ export const createNotificationTriggerRuntime = (deps) => {
 
     const sessionId = extractSessionIdFromPayload(payload);
     const notificationDirectory = extractDirectoryFromPayload(payload);
+    // A user abort arrives as `session.idle` with `aborted: true`: the turn
+    // did not finish, so there is nothing to announce as ready.
+    if (payload.type === 'session.idle' && payload.properties?.aborted === true) {
+      return;
+    }
+
     if ((payload.type === 'session.idle' || payload.type === 'session.error') && sessionId) {
+      if (payload.type === 'session.idle' && await isPausedForSubagents(sessionId)) {
+        return;
+      }
       const error = payload.properties?.error;
       const errorText = typeof error?.message === 'string'
         ? error.message
@@ -319,7 +387,10 @@ export const createNotificationTriggerRuntime = (deps) => {
         type: 'message.updated',
         properties: {
           ...payload.properties,
+          // Only a turn end announces readiness; a step's `stop` does not.
+          turnEnded: true,
           info: {
+            id: lastAssistantStepBySession.get(sessionId),
             sessionID: sessionId,
             role: 'assistant',
             finish: payload.type === 'session.error' ? 'error' : 'stop',
@@ -331,8 +402,13 @@ export const createNotificationTriggerRuntime = (deps) => {
     }
 
     if (payload.type === 'message.updated') {
-      const info = payload.properties?.info;
-      if (info?.role === 'assistant' && info?.finish === 'stop' && sessionId) {
+      rememberAssistantStep(payload.properties?.info);
+      const info = withRememberedStep(payload.properties?.info);
+      // v2 ends every step with a `message.updated`; the last one says `stop`,
+      // but the execution can still drain steering input after it. Readiness
+      // is announced from the execution's terminal `session.idle` instead.
+      if (info?.role === 'assistant' && info?.finish === 'stop' && sessionId && payload.properties?.turnEnded === true) {
+        payload = { ...payload, properties: { ...payload.properties, info } };
         const settings = await readSettingsFromDisk();
 
         if (settings.notifyOnSubtasks === false) {
@@ -353,7 +429,7 @@ export const createNotificationTriggerRuntime = (deps) => {
         // While a goal drives the session, per-turn "ready" notifications are
         // noise produced by the goal loop itself — the goal's own settle
         // notification (complete/blocked/budget) is the final word instead.
-        if (await hasActiveSessionGoal(sessionId, notificationDirectory)) {
+        if (await hasActiveSessionGoal(sessionId)) {
           return;
         }
 
@@ -504,7 +580,7 @@ export const createNotificationTriggerRuntime = (deps) => {
       return;
     }
 
-    if (payload.type === 'question.asked' && sessionId) {
+    if (payload.type === 'form.created' && sessionId) {
       const existingTimer = pushQuestionDebounceTimers.get(sessionId);
       if (existingTimer) {
         clearTimeout(existingTimer);
@@ -522,9 +598,14 @@ export const createNotificationTriggerRuntime = (deps) => {
           return;
         }
 
-        const firstQuestion = payload.properties?.questions?.[0];
-        const header = typeof firstQuestion?.header === 'string' ? firstQuestion.header.trim() : '';
-        const questionText = typeof firstQuestion?.question === 'string' ? firstQuestion.question.trim() : '';
+        // v2 replaced questions with forms: the form's title is the ask, and
+        // the first field carries the detail a question used to put in its body.
+        const form = payload.properties?.form;
+        const header = typeof form?.title === 'string' ? form.title.trim() : '';
+        const firstField = Array.isArray(form?.fields) ? form.fields[0] : null;
+        const fieldTitle = typeof firstField?.title === 'string' ? firstField.title.trim() : '';
+        const fieldDescription = typeof firstField?.description === 'string' ? firstField.description.trim() : '';
+        const questionText = fieldDescription || fieldTitle;
 
         let title = /plan\s*mode/i.test(header)
           ? 'Switch to plan mode'
@@ -604,7 +685,15 @@ export const createNotificationTriggerRuntime = (deps) => {
 
     if (payload.type === 'permission.asked' && sessionId) {
       const requestId = payload.properties?.id ?? payload.properties?.requestID ?? payload.properties?.requestId;
-      const permission = payload.properties?.permission;
+      // v2 describes a permission request as an action plus the resources it
+      // touches; the v1 single `permission` string is gone.
+      const permissionAction = typeof payload.properties?.action === 'string' ? payload.properties.action.trim() : '';
+      const permissionResource = Array.isArray(payload.properties?.resources)
+        ? String(payload.properties.resources[0] ?? '').trim()
+        : '';
+      const permissionMessage = typeof payload.properties?.message === 'string' ? payload.properties.message.trim() : '';
+      const permission = permissionMessage
+        || (permissionAction && permissionResource ? `${permissionAction}: ${permissionResource}` : permissionAction);
       const requestKey = typeof requestId === 'string' ? `${sessionId}:${requestId}` : null;
       if (requestKey && notifiedPermissionRequests.has(requestKey)) {
         return;
@@ -713,7 +802,7 @@ export const createNotificationTriggerRuntime = (deps) => {
   const sendGoalSettlePush = async ({ sessionId, directory, status, title, body }) => {
     let sessionName = '';
     try {
-      const base = buildOpenCodeUrl(`/session/${encodeURIComponent(sessionId)}`, '');
+      const base = buildOpenCodeUrl(`/api/session/${encodeURIComponent(sessionId)}`, '');
       const url = directory ? `${base}?directory=${encodeURIComponent(directory)}` : base;
       const response = await fetch(url, {
         method: 'GET',
@@ -721,7 +810,7 @@ export const createNotificationTriggerRuntime = (deps) => {
         signal: AbortSignal.timeout(2000),
       });
       if (response.ok) {
-        const session = await response.json().catch(() => null);
+        const session = unwrapOpenCodeResponse(await response.json().catch(() => null));
         if (typeof session?.title === 'string') sessionName = session.title.trim();
       }
     } catch {

package/server/lib/notifications/template-runtime.js

@@ -1,4 +1,5 @@
 import { summarizeText as summarizeSharedText } from '../text/summarization.js';
+import { unwrapOpenCodeResponse } from '../opencode/response-envelope.js';
 
 export const createNotificationTemplateRuntime = (deps) => {
   const {
@@ -136,7 +137,7 @@ export const createNotificationTemplateRuntime = (deps) => {
     if (!sessionId) return '';
 
     try {
-      const url = buildOpenCodeUrl(`/session/${encodeURIComponent(sessionId)}/message`, '');
+      const url = buildOpenCodeUrl(`/api/session/${encodeURIComponent(sessionId)}/message`, '');
       const response = await fetch(`${url}?limit=5`, {
         method: 'GET',
         headers: {
@@ -148,26 +149,23 @@ export const createNotificationTemplateRuntime = (deps) => {
 
       if (!response.ok) return '';
 
-      const messages = await response.json().catch(() => null);
-      if (!Array.isArray(messages)) return '';
+      // v2 pages messages as `{ data, cursor }`, newest first, and a message is
+      // a flat record: an assistant one carries `content[]`, not `parts`.
+      const page = await response.json().catch(() => null);
+      const messages = Array.isArray(page?.data) ? page.data : null;
+      if (!messages) return '';
 
       let target = null;
       if (messageId) {
-        target = messages.find((message) => message?.info?.id === messageId && message?.info?.role === 'assistant');
+        target = messages.find((message) => message?.id === messageId && message?.type === 'assistant');
       }
       if (!target) {
-        for (let i = messages.length - 1; i >= 0; i -= 1) {
-          const message = messages[i];
-          if (message?.info?.role === 'assistant' && message?.info?.finish === 'stop') {
-            target = message;
-            break;
-          }
-        }
+        target = messages.find((message) => message?.type === 'assistant' && message?.finish === 'stop') ?? null;
       }
 
-      if (!target || !Array.isArray(target.parts)) return '';
+      if (!target || !Array.isArray(target.content)) return '';
 
-      return extractTextFromParts(target.parts, maxLength);
+      return extractTextFromParts(target.content, maxLength);
     } catch {
       return '';
     }
@@ -201,7 +199,7 @@ export const createNotificationTemplateRuntime = (deps) => {
     }
 
     try {
-      const url = buildOpenCodeUrl(`/session/${encodeURIComponent(sessionId)}`, '');
+      const url = buildOpenCodeUrl(`/api/session/${encodeURIComponent(sessionId)}`, '');
       const response = await fetch(url, {
         method: 'GET',
         headers: { Accept: 'application/json' },
@@ -211,7 +209,7 @@ export const createNotificationTemplateRuntime = (deps) => {
         console.warn(`[Notification] fetchSessionInfo: ${response.status} for session ${sessionId}`);
         return null;
       }
-      const data = await response.json().catch(() => null);
+      const data = unwrapOpenCodeResponse(await response.json().catch(() => null));
       if (data && typeof data === 'object') {
         sessionInfoCache.set(sessionId, { data, at: Date.now() });
         return data;

package/server/lib/notifications/template-runtime.test.js

@@ -69,15 +69,22 @@ describe('notification template message extraction', () => {
 
   it('excludes reasoning parts when fetching assistant messages', async () => {
     const runtime = createRuntime();
-    globalThis.fetch = vi.fn(async () => new Response(JSON.stringify([
-      {
-        info: { id: 'msg-1', role: 'assistant', finish: 'stop' },
-        parts: [
-          { type: 'reasoning', text: 'private chain of thought' },
-          { type: 'text', text: 'final answer' },
-        ],
-      },
-    ])));
+    // v2 pages messages as `{ data, cursor }` and an assistant message is a
+    // flat record carrying `content[]`.
+    globalThis.fetch = vi.fn(async () => new Response(JSON.stringify({
+      data: [
+        {
+          id: 'msg-1',
+          type: 'assistant',
+          finish: 'stop',
+          content: [
+            { type: 'reasoning', text: 'private chain of thought' },
+            { type: 'text', text: 'final answer' },
+          ],
+        },
+      ],
+      cursor: {},
+    })));
 
     await expect(runtime.fetchLastAssistantMessageText('session-1', 'msg-1')).resolves.toBe('final answer');
   });

package/server/lib/notifications/trigger-runtime.test.js

@@ -0,0 +1,187 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { createNotificationTriggerRuntime } from './runtime.js';
+
+/**
+ * The "ready" push is built from the translated `message.updated` events.
+ * v2 splits a turn: the step start names agent and model, the step end
+ * carries the finish. What is pinned here: the finish is announced with the
+ * agent and model from the start, a user abort announces nothing, and an
+ * active goal (which lives in OpenChamber's own metadata) silences the push.
+ */
+const makeRuntime = ({ metadata = {} } = {}) => {
+  const emitDesktopNotification = vi.fn(() => true);
+  const runtime = createNotificationTriggerRuntime({
+    readSettingsFromDisk: async () => ({ nativeNotificationsEnabled: true, notificationMode: 'always', notifyOnCompletion: true }),
+    prepareNotificationLastMessage: async ({ message }) => message,
+    buildTemplateVariables: async () => ({}),
+    extractLastMessageText: () => 'done',
+    fetchLastAssistantMessageText: async () => 'done',
+    resolveNotificationTemplate: () => '',
+    shouldApplyResolvedTemplateMessage: () => false,
+    emitDesktopNotification,
+    broadcastUiNotification: vi.fn(),
+    sendPushToAllUiSessions: vi.fn(async () => undefined),
+    sendApnsToAllUiSessions: vi.fn(async () => undefined),
+    isAnyInteractiveClientVisible: () => true,
+    buildOpenCodeUrl: (path) => `http://opencode.test${path}`,
+    getOpenCodeAuthHeaders: () => ({}),
+    readSessionMetadata: async () => metadata,
+  });
+  return { runtime, emitDesktopNotification };
+};
+
+const stepStarted = (sessionID, id) => ({
+  type: 'message.updated',
+  properties: { sessionID, info: { id, sessionID, role: 'assistant', agent: 'build', providerID: 'anthropic', modelID: 'claude-sonnet-5', time: { created: 1 } } },
+});
+const stepEnded = (sessionID, id) => ({
+  type: 'message.updated',
+  properties: { sessionID, info: { id, sessionID, role: 'assistant', finish: 'stop', time: { completed: 2 } } },
+});
+
+const turnEnded = (sessionID) => ({ type: 'session.idle', properties: { sessionID } });
+
+describe('ready notification on v2 step events', () => {
+  it('announces the turn end with the agent and model of its last step', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const { runtime, emitDesktopNotification } = makeRuntime();
+
+    await runtime.maybeSendPushForTrigger(stepStarted('ses_1', 'msg_1'));
+    expect(emitDesktopNotification).not.toHaveBeenCalled();
+
+    // A step's `stop` is not the end of the turn: the execution may still
+    // drain steering input, so only its idle event announces readiness.
+    await runtime.maybeSendPushForTrigger(stepEnded('ses_1', 'msg_1'));
+    expect(emitDesktopNotification).not.toHaveBeenCalled();
+
+    await runtime.maybeSendPushForTrigger(turnEnded('ses_1'));
+    expect(emitDesktopNotification).toHaveBeenCalledTimes(1);
+    expect(emitDesktopNotification.mock.calls[0][0]).toMatchObject({
+      kind: 'ready',
+      title: 'Build agent is ready',
+      body: 'Claude Sonnet 5 completed the task',
+    });
+  });
+
+  it('announces nothing for a user abort', async () => {
+    const { runtime, emitDesktopNotification } = makeRuntime();
+
+    await runtime.maybeSendPushForTrigger({
+      type: 'session.idle',
+      properties: { sessionID: 'ses_2', aborted: true, reason: 'user', error: { name: 'MessageAbortedError', message: 'aborted' } },
+    });
+
+    expect(emitDesktopNotification).not.toHaveBeenCalled();
+  });
+
+  it('stays quiet while a goal from OpenChamber\'s own metadata is active', async () => {
+    const { runtime, emitDesktopNotification } = makeRuntime({
+      metadata: { openchamber: { goal: { id: 'g', status: 'active', objective: 'x' } } },
+    });
+
+    await runtime.maybeSendPushForTrigger(stepStarted('ses_3', 'msg_3'));
+    await runtime.maybeSendPushForTrigger(stepEnded('ses_3', 'msg_3'));
+    await runtime.maybeSendPushForTrigger(turnEnded('ses_3'));
+
+    expect(emitDesktopNotification).not.toHaveBeenCalled();
+  });
+});
+
+describe('ready notification while background subagents run', () => {
+  const stubOpenCode = ({ active, children }) => {
+    vi.stubGlobal('fetch', vi.fn(async (input) => {
+      const url = new URL(String(input));
+      if (url.pathname === '/api/session/active') return Response.json({ data: active() });
+      if (url.pathname === '/api/session') return Response.json({ data: children, cursor: {} });
+      return Response.json({});
+    }));
+  };
+
+  it('stays silent on the pause and announces the real turn end', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    let active = { ses_child: { type: 'running' } };
+    stubOpenCode({ active: () => active, children: [{ id: 'ses_child', parentID: 'ses_1' }] });
+    const { runtime, emitDesktopNotification } = makeRuntime();
+
+    await runtime.maybeSendPushForTrigger(stepStarted('ses_1', 'msg_1'));
+    await runtime.maybeSendPushForTrigger(turnEnded('ses_1'));
+    expect(emitDesktopNotification).not.toHaveBeenCalled();
+
+    // The subagent finished and OpenCode ran the parent again with its result.
+    active = {};
+    await runtime.maybeSendPushForTrigger(turnEnded('ses_1'));
+    expect(emitDesktopNotification).toHaveBeenCalledTimes(1);
+    vi.unstubAllGlobals();
+  });
+
+  it('announces the idle when the subagent check cannot be made', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    vi.stubGlobal('fetch', vi.fn(async () => new Response('down', { status: 503 })));
+    const { runtime, emitDesktopNotification } = makeRuntime();
+
+    await runtime.maybeSendPushForTrigger(stepStarted('ses_1', 'msg_1'));
+    await runtime.maybeSendPushForTrigger(turnEnded('ses_1'));
+    expect(emitDesktopNotification).toHaveBeenCalledTimes(1);
+    vi.unstubAllGlobals();
+  });
+});
+
+describe('subagent finish with subagent notifications off', () => {
+  const makeSubtaskRuntime = () => {
+    const emitDesktopNotification = vi.fn(() => true);
+    const runtime = createNotificationTriggerRuntime({
+      readSettingsFromDisk: async () => ({ nativeNotificationsEnabled: true, notificationMode: 'always', notifyOnCompletion: true, notifyOnSubtasks: false }),
+      prepareNotificationLastMessage: async ({ message }) => message,
+      buildTemplateVariables: async () => ({}),
+      extractLastMessageText: () => 'done',
+      fetchLastAssistantMessageText: async () => 'done',
+      resolveNotificationTemplate: () => '',
+      shouldApplyResolvedTemplateMessage: () => false,
+      emitDesktopNotification,
+      broadcastUiNotification: vi.fn(),
+      sendPushToAllUiSessions: vi.fn(async () => undefined),
+      sendApnsToAllUiSessions: vi.fn(async () => undefined),
+      isAnyInteractiveClientVisible: () => true,
+      buildOpenCodeUrl: (path) => `http://opencode.test${path}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      readSessionMetadata: async () => ({}),
+    });
+    return { runtime, emitDesktopNotification };
+  };
+
+  // OpenCode answers `GET /api/session/:id` as `{ data }` with no `location`.
+  const stubSessionRecord = () => {
+    vi.stubGlobal('fetch', vi.fn(async (input) => {
+      const url = new URL(String(input));
+      if (url.pathname === '/api/session/active') return Response.json({ data: {} });
+      if (url.pathname === '/api/session/ses_child') return Response.json({ data: { id: 'ses_child', parentID: 'ses_parent' } });
+      return Response.json({ data: [], cursor: {} });
+    }));
+  };
+
+  it('reads the parent from the session record envelope', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    stubSessionRecord();
+    const { runtime, emitDesktopNotification } = makeSubtaskRuntime();
+
+    await runtime.maybeSendPushForTrigger(stepStarted('ses_child', 'msg_c'));
+    await runtime.maybeSendPushForTrigger(turnEnded('ses_child'));
+    expect(emitDesktopNotification).not.toHaveBeenCalled();
+    vi.unstubAllGlobals();
+  });
+
+  it('a partial session update does not erase a known parent', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    vi.stubGlobal('fetch', vi.fn(async () => new Response('down', { status: 503 })));
+    const { runtime, emitDesktopNotification } = makeSubtaskRuntime();
+
+    await runtime.maybeSendPushForTrigger({ type: 'session.created', properties: { sessionID: 'ses_child', info: { id: 'ses_child', parentID: 'ses_parent' } } });
+    // Usage updates arrive as `session.updated` with a partial record.
+    await runtime.maybeSendPushForTrigger({ type: 'session.updated', properties: { sessionID: 'ses_child', info: { id: 'ses_child', cost: 1 } } });
+    await runtime.maybeSendPushForTrigger(stepStarted('ses_child', 'msg_c'));
+    await runtime.maybeSendPushForTrigger(turnEnded('ses_child'));
+    expect(emitDesktopNotification).not.toHaveBeenCalled();
+    vi.unstubAllGlobals();
+  });
+});

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

@@ -59,6 +59,16 @@ other.
   directory and does not erase other session results.
 - Destructive session/worktree deletion and project-path registration are not
   part of the action contract.
+- `file.open` shows a file in the user's viewer. `file-open.js` resolves a
+  relative path against the session directory (an explicit `directory` wins),
+  refuses a relative path with no directory at all, checks the target is an
+  existing file, then hands `{ path, directory, sessionId }` to the injected
+  `emit`, which `index.js` writes to every UI control stream as
+  `openchamber:file-open-request`. Nothing comes back: opening a tab does not
+  fail quietly on a client, so the count of clients reached is the signal, and
+  zero is a 503, never a claimed success. Paths outside the workspace are
+  allowed on purpose: screenshots and recordings often land in a temp
+  directory, and the viewer already reads such files.
 - `browser.capture` writes its image on the server, into
   `.openchamber/screenshots/` under the scoped project directory, and returns
   the project-relative path rather than the image bytes. The client that took

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

@@ -22,6 +22,7 @@ export const OPENCHAMBER_CONTROL_ACTION_DEFINITIONS = Object.freeze([
   { action: 'schedule.run', title: 'Run a scheduled task', description: 'Run taskId; scope with projectId or directory' },
   { action: 'schedule.delete', title: 'Delete a scheduled task', description: 'Delete taskId; scope with projectId or directory' },
   { action: 'schedule.toggle', title: 'Enable or disable a scheduled task', description: 'Enable or disable taskId; requires the disabled boolean' },
+  { action: 'file.open', title: 'Show a file to the user', description: 'Open path in the user\'s file panel, in front of whatever they had open, so they can look at a result you produced: a screenshot, report, CSV, recording, or generated page. Relative to the session directory. Use it only when seeing the file moves the work forward, not for every file you touch' },
 ]);
 
 const OPENCHAMBER_CONTROL_ACTIONS = Object.freeze(
@@ -65,9 +66,9 @@ export const OPENCHAMBER_WEB_ACTIONS = Object.freeze(
  * reads as a complete fact is exactly the one whose conditions get lost.
  */
 export const OPENCHAMBER_MEMORY_ACTION_DEFINITIONS = Object.freeze([
-  { action: 'memory.read', title: 'Read a stored memory', description: 'Read the full text of one memory listed in the session index. The index shows titles only, and a title omits the conditions that decide how the memory applies, so read before acting rather than working from the title. Requires title (as the index spells it) or memoryId; scope is optional and both stores are searched without it' },
+  { action: 'memory.read', title: 'Read a stored memory', description: 'Read the full text of one memory listed in the session index. The index shows titles only, and a title omits the conditions that decide how the memory applies, so read before acting rather than working from the title. Once read, an entry stays in your context; do not read it again in the same conversation. Requires title (as the index spells it) or memoryId; scope is optional and both stores are searched without it' },
   { action: 'memory.list', title: 'List stored memories', description: 'List stored memory titles when the session index is missing or stale; scope is global, project, or both (default)' },
-  { action: 'memory.save', title: 'Remember something', description: 'Store a durable fact, preference, or reference; requires title and body, plus scope global (about the user) or project (about this codebase). Restating something already stored updates it. Do not store secrets, one-off task state, or anything the user asked you not to keep' },
+  { action: 'memory.save', title: 'Remember something', description: 'Store a durable fact, preference, or reference; requires title and body, plus scope global (about the user) or project (about this codebase). Restating something already stored updates it. Do not store secrets, one-off task state, or anything the user asked you not to keep; when the user explicitly asks you to remember something, store it unless it is a secret' },
   { action: 'memory.delete', title: 'Forget a memory', description: 'Delete a memory that turned out to be wrong or obsolete; requires memoryId and scope' },
 ]);
 

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

@@ -10,7 +10,7 @@ export class OpenChamberControlError extends Error {
 export const asControlError = (error, fallbackMessage, fallbackStatus = 500) => {
   if (error instanceof OpenChamberControlError) return error;
   const message = error instanceof Error ? error.message : fallbackMessage;
-  return new OpenChamberControlError(message || fallbackMessage, Number(error?.statusCode) || fallbackStatus, {
+  return new OpenChamberControlError(message || fallbackMessage, Number(error?.statusCode) || Number(error?.status) || fallbackStatus, {
     ...(error?.goalConfigured === true ? { goalConfigured: true } : {}),
   });
 };