@openchambery/web 2.0.0-beta.4 → 2.0.0-beta.5

package/server/lib/browser-provider/host.test.js

@@ -0,0 +1,304 @@
+import http from 'node:http';
+
+import { describe, expect, test } from 'vitest';
+
+import {
+  BROWSER_PROVIDER_PATH,
+  extensionDeclaresBrowser,
+  readBrowserProviderRequest,
+} from './contract.js';
+import { BrowserProviderError } from './contract.js';
+import { createBrowserProviderHost } from './host.js';
+
+const declaring = (overrides = {}) => ({
+  id: 'server-chrome',
+  name: 'Server Chrome',
+  service: { provides: ['browser'] },
+  answer: async () => ({ ok: true, data: { url: 'http://127.0.0.1/', title: 'App' } }),
+  ...overrides,
+});
+
+describe('extensionDeclaresBrowser', () => {
+  test('recognizes a browser declaration and ignores other roles', () => {
+    expect(extensionDeclaresBrowser({ service: { provides: ['browser'] } })).toBe(true);
+    expect(extensionDeclaresBrowser({ provides: ['browser'] })).toBe(true);
+    expect(extensionDeclaresBrowser({ contributes: { service: { provides: ['browser'] } } })).toBe(true);
+    expect(extensionDeclaresBrowser({ service: { provides: ['printer'] } })).toBe(false);
+    expect(extensionDeclaresBrowser({ service: { provides: [] } })).toBe(false);
+    expect(extensionDeclaresBrowser({ service: {} })).toBe(false);
+    expect(extensionDeclaresBrowser(null)).toBe(false);
+    expect(extensionDeclaresBrowser({ service: { provides: ['printer'] }, provides: ['browser'] })).toBe(false);
+  });
+});
+
+describe('browser provider host', () => {
+  test('rejects an extension that does not declare browser and does not list it', () => {
+    const host = createBrowserProviderHost();
+    expect(() => host.install({ id: 'other', name: 'Other', answer: async () => ({ ok: true, data: {} }) }))
+      .toThrow(BrowserProviderError);
+    return expect(host.list()).resolves.toEqual([]);
+  });
+
+  test('lists a reachable browser declaration and hides the transport', async () => {
+    const host = createBrowserProviderHost();
+    const answer = async () => ({ ok: true, data: { url: 'http://a/' } });
+    expect(host.install(declaring({ answer, endpoint: 'http://example.com/steal' }))).toEqual({
+      id: 'server-chrome',
+      name: 'Server Chrome',
+      surface: false,
+    });
+    const providers = await host.list();
+    expect(providers).toEqual([{ id: 'server-chrome', name: 'Server Chrome', surface: false }]);
+    expect(JSON.stringify(providers)).not.toContain('endpoint');
+    expect(JSON.stringify(providers)).not.toContain('answer');
+  });
+
+  test('refuses a non-loopback endpoint and does not register it', async () => {
+    const host = createBrowserProviderHost();
+    expect(() => host.install(declaring({
+      answer: undefined,
+      endpoint: 'http://example.com/browser-control',
+    }))).toThrow(/loopback/);
+    await expect(host.list()).resolves.toEqual([]);
+  });
+
+  test('sends the agent action to the selected provider and adopts its data', async () => {
+    const seen = [];
+    const host = createBrowserProviderHost({ createId: () => 'req-1' });
+    host.install(declaring({
+      answer: async (request) => {
+        seen.push(request);
+        return { ok: true, data: { url: 'http://127.0.0.1/', title: 'App', clicked: '#save' } };
+      },
+    }));
+    await host.select('server-chrome');
+    const result = await host.dispatchAgentBrowserAction({
+      action: 'browser.click',
+      parameters: { selector: '#save', extra: 'drop-me' },
+      context: { directory: '/repo', sessionId: 'ses_1' },
+    });
+    expect(result).toEqual({
+      providerId: 'server-chrome',
+      data: { url: 'http://127.0.0.1/', title: 'App', clicked: '#save' },
+    });
+    expect(seen).toEqual([{
+      requestId: 'req-1',
+      action: 'browser.click',
+      parameters: { selector: '#save' },
+      context: { directory: '/repo', sessionId: 'ses_1' },
+    }]);
+    expect(readBrowserProviderRequest(JSON.stringify(seen[0]))).toEqual(seen[0]);
+  });
+
+  test('posts to the extension loopback and adopts that result', async () => {
+    const seen = [];
+    const server = http.createServer((req, res) => {
+      const chunks = [];
+      req.on('data', (chunk) => chunks.push(chunk));
+      req.on('end', () => {
+        seen.push({ method: req.method, url: req.url, body: JSON.parse(Buffer.concat(chunks).toString('utf8')) });
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, data: { url: 'http://127.0.0.1/', title: 'Loop' } }));
+      });
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const { port } = server.address();
+    try {
+      const host = createBrowserProviderHost({ createId: () => 'req-loop' });
+      host.install(declaring({
+        answer: undefined,
+        endpoint: `http://127.0.0.1:${port}`,
+      }));
+      await host.select('server-chrome');
+      const result = await host.dispatchAgentBrowserAction({
+        action: 'browser.open',
+        parameters: { url: 'http://127.0.0.1:3000/app' },
+        context: { directory: '', sessionId: 7 },
+      });
+      expect(result.data).toEqual({ url: 'http://127.0.0.1/', title: 'Loop' });
+      expect(seen[0].method).toBe('POST');
+      expect(seen[0].url).toBe(BROWSER_PROVIDER_PATH);
+      expect(seen[0].body.context).toEqual({ directory: null, sessionId: null });
+      expect(seen[0].body.action).toBe('browser.open');
+    } finally {
+      await new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())));
+    }
+  });
+
+  test('uses the extension error and does not turn it into empty data', async () => {
+    const host = createBrowserProviderHost();
+    host.install(declaring({
+      answer: async () => ({ ok: false, error: 'No element matches #save' }),
+    }));
+    await host.select('server-chrome');
+    await expect(host.dispatchAgentBrowserAction({
+      action: 'browser.click',
+      parameters: { selector: '#save' },
+    })).rejects.toMatchObject({
+      code: 'PROVIDER_REJECTED',
+      status: 400,
+      message: 'No element matches #save',
+    });
+  });
+
+  test('a malformed answer is unknown page state, not success', async () => {
+    const host = createBrowserProviderHost();
+    host.install(declaring({ answer: async () => ({ ok: true }) }));
+    await host.select('server-chrome');
+    await expect(host.dispatchAgentBrowserAction({ action: 'browser.snapshot', parameters: {} }))
+      .rejects.toMatchObject({ code: 'UNKNOWN_RESULT', status: 502 });
+  });
+
+  test('no selected provider rejects and does not call the extension', async () => {
+    const seen = [];
+    const host = createBrowserProviderHost();
+    host.install(declaring({
+      answer: async () => {
+        seen.push('called');
+        return { ok: true, data: {} };
+      },
+    }));
+    await expect(host.dispatchAgentBrowserAction({ action: 'browser.snapshot', parameters: {} }))
+      .rejects.toMatchObject({ code: 'NO_PROVIDER', status: 409 });
+    expect(seen).toEqual([]);
+  });
+
+  test('an unknown selection does not change the current choice or run an action', async () => {
+    const host = createBrowserProviderHost();
+    host.install(declaring());
+    await host.select('server-chrome');
+    await expect(host.select('missing')).rejects.toMatchObject({ code: 'PROVIDER_NOT_FOUND', status: 404 });
+    expect(host.selectedId()).toBe('server-chrome');
+    await expect(host.dispatchAgentBrowserAction({
+      action: 'browser.snapshot',
+      parameters: {},
+      providerId: 'missing',
+    })).rejects.toMatchObject({ code: 'PROVIDER_NOT_FOUND' });
+  });
+
+  test('a catalog read failure is not an empty provider list and does not send the action', async () => {
+    const seen = [];
+    const host = createBrowserProviderHost({
+      readInstalled: async () => {
+        throw new Error('disk');
+      },
+    });
+    await expect(host.list()).rejects.toMatchObject({ code: 'CATALOG_UNAVAILABLE', status: 503 });
+    await expect(host.dispatchAgentBrowserAction({
+      action: 'browser.snapshot',
+      parameters: {},
+      providerId: 'server-chrome',
+    })).rejects.toMatchObject({ code: 'CATALOG_UNAVAILABLE' });
+    expect(seen).toEqual([]);
+  });
+
+  test('a non-array catalog is not treated as no providers', async () => {
+    const host = createBrowserProviderHost({
+      readInstalled: async () => /** @type {any} */ (null),
+    });
+    await expect(host.list()).rejects.toMatchObject({ code: 'CATALOG_UNAVAILABLE' });
+  });
+
+  test('invalid actions are not sent', async () => {
+    const seen = [];
+    const host = createBrowserProviderHost();
+    host.install(declaring({
+      answer: async () => {
+        seen.push('called');
+        return { ok: true, data: {} };
+      },
+    }));
+    await host.select('server-chrome');
+    await expect(host.dispatchAgentBrowserAction({ action: 'browser.explode', parameters: {} }))
+      .rejects.toMatchObject({ code: 'INVALID_ACTION' });
+    await expect(host.dispatchAgentBrowserAction({ action: 'browser.open', parameters: { url: 'file:///tmp/x' } }))
+      .rejects.toMatchObject({ code: 'INVALID_ACTION' });
+    expect(seen).toEqual([]);
+  });
+
+  test('a provider that throws after receiving the action is not reported as unchanged', async () => {
+    const host = createBrowserProviderHost();
+    host.install(declaring({
+      answer: async () => {
+        throw new Error('socket dropped');
+      },
+    }));
+    await host.select('server-chrome');
+    await expect(host.dispatchAgentBrowserAction({ action: 'browser.snapshot', parameters: {} }))
+      .rejects.toMatchObject({ code: 'REQUEST_FAILED', status: 504 });
+  });
+
+  test('a refused connection is not sent and is not success', async () => {
+    const host = createBrowserProviderHost({
+      fetchImpl: async () => {
+        const error = new TypeError('fetch failed');
+        error.cause = Object.assign(new Error('refused'), { code: 'ECONNREFUSED' });
+        throw error;
+      },
+    });
+    host.install(declaring({ answer: undefined, endpoint: 'http://127.0.0.1:9' }));
+    await host.select('server-chrome');
+    await expect(host.dispatchAgentBrowserAction({ action: 'browser.snapshot', parameters: {} }))
+      .rejects.toMatchObject({ code: 'PROVIDER_UNAVAILABLE', status: 503 });
+  });
+
+  test('an HTTP error answer is unknown page state', async () => {
+    const host = createBrowserProviderHost({
+      fetchImpl: async () => new Response('boom', { status: 500 }),
+    });
+    host.install(declaring({ answer: undefined, endpoint: 'http://127.0.0.1:9/browser-control' }));
+    await host.select('server-chrome');
+    await expect(host.dispatchAgentBrowserAction({ action: 'browser.back', parameters: {} }))
+      .rejects.toMatchObject({ code: 'UNKNOWN_RESULT', status: 502 });
+  });
+
+  test('a saved selection is used after restart and a failed save does not change it', async () => {
+    const writes = [];
+    let saved = 'server-chrome';
+    const store = {
+      read: async () => saved,
+      write: async (id) => {
+        writes.push(id);
+        if (id === 'other-chrome') throw new Error('disk');
+        saved = id;
+      },
+    };
+    const restored = createBrowserProviderHost({ selectionStore: store });
+    restored.install(declaring());
+    await expect(restored.dispatchAgentBrowserAction({
+      action: 'browser.snapshot',
+      parameters: {},
+    })).resolves.toMatchObject({ providerId: 'server-chrome' });
+
+    restored.install(declaring({ id: 'other-chrome', name: 'Other Chrome' }));
+    await expect(restored.select('other-chrome')).rejects.toMatchObject({ code: 'SELECTION_UNAVAILABLE' });
+    expect(restored.selectedId()).toBe('server-chrome');
+    expect(writes).toEqual(['other-chrome']);
+    await expect(restored.catalog()).resolves.toMatchObject({ selectedId: 'server-chrome' });
+  });
+
+  test('a saved id that is not installed is not reported as the connected provider', async () => {
+    const host = createBrowserProviderHost({
+      selectionStore: { read: async () => 'server-chrome', write: async () => undefined },
+    });
+    await expect(host.catalog()).resolves.toEqual({ providers: [], selectedId: null });
+    await expect(host.dispatchAgentBrowserAction({ action: 'browser.snapshot', parameters: {} }))
+      .rejects.toMatchObject({ code: 'PROVIDER_NOT_FOUND' });
+  });
+
+  test('a cancelled action is not sent', async () => {
+    const seen = [];
+    const host = createBrowserProviderHost();
+    host.install(declaring({
+      answer: async () => {
+        seen.push('called');
+        return { ok: true, data: {} };
+      },
+    }));
+    await host.select('server-chrome');
+    const signal = AbortSignal.abort();
+    await expect(host.dispatchAgentBrowserAction({ action: 'browser.back', parameters: {}, signal }))
+      .rejects.toMatchObject({ code: 'CANCELLED' });
+    expect(seen).toEqual([]);
+  });
+});

package/server/lib/browser-provider/routes.js

@@ -0,0 +1,122 @@
+/**
+ * HTTP contract for the browser-provider host.
+ *
+ * These routes are not in the common JSON allowlist, so each mutating route
+ * parses its own body. A missing parser would turn every action into a
+ * validation failure and hide that the provider was never asked.
+ *
+ * List failure is never `{ providers: [] }`. Action failure is never
+ * `{ ok: true, data: {} }`.
+ */
+
+import express from 'express';
+
+import {
+  BROWSER_PROVIDER_ACTIONS_ROUTE,
+  BROWSER_PROVIDER_SELECTION_ROUTE,
+  BROWSER_PROVIDERS_ROUTE,
+  BrowserProviderError,
+} from './contract.js';
+
+const parseSelection = express.json({ limit: '4kb' });
+const parseAction = express.json({ limit: '64kb' });
+
+const readJson = (parser, invalid) => (req, res, next) => {
+  parser(req, res, (error) => {
+    if (!error) {
+      next();
+      return;
+    }
+    const status = error.status || error.statusCode || 400;
+    res.status(status).json(invalid);
+  });
+};
+
+const catalogError = (res, error) => {
+  if (error instanceof BrowserProviderError) {
+    res.status(error.status).json({ error: error.message, code: error.code });
+    return;
+  }
+  res.status(503).json({
+    error: 'OpenChamber could not read the browser provider catalog.',
+    code: 'CATALOG_UNAVAILABLE',
+  });
+};
+
+const actionError = (res, error) => {
+  if (error instanceof BrowserProviderError) {
+    res.status(error.status).json({ ok: false, code: error.code, error: error.message });
+    return;
+  }
+  res.status(500).json({
+    ok: false,
+    code: 'PROVIDER_UNAVAILABLE',
+    error: 'The browser action was not completed. Nothing is known about the page.',
+  });
+};
+
+/**
+ * @param {import('express').Express} app
+ * @param {{ host: { list: Function, selectedId: Function, select: Function, dispatchAgentBrowserAction: Function } }} deps
+ */
+export const registerBrowserProviderRoutes = (app, { host }) => {
+  if (!host || typeof host.catalog !== 'function' || typeof host.dispatchAgentBrowserAction !== 'function') {
+    throw new Error('registerBrowserProviderRoutes requires a browser provider host');
+  }
+
+  app.get(BROWSER_PROVIDERS_ROUTE, async (_req, res) => {
+    try {
+      res.json(await host.catalog());
+    } catch (error) {
+      catalogError(res, error);
+    }
+  });
+
+  app.put(BROWSER_PROVIDER_SELECTION_ROUTE, readJson(parseSelection, {
+    error: 'The selection body could not be read. The selection was not changed.',
+    code: 'INVALID_SELECTION',
+  }), async (req, res) => {
+    const body = req.body;
+    if (!body || typeof body !== 'object' || Array.isArray(body) || typeof body.id !== 'string') {
+      res.status(400).json({
+        error: 'id is required and must be a browser provider id. The selection was not changed.',
+        code: 'INVALID_SELECTION',
+      });
+      return;
+    }
+    try {
+      const selectedId = await host.select(body.id);
+      res.json({ selectedId });
+    } catch (error) {
+      catalogError(res, error);
+    }
+  });
+
+  app.post(BROWSER_PROVIDER_ACTIONS_ROUTE, readJson(parseAction, {
+    ok: false,
+    code: 'INVALID_ACTION',
+    error: 'The action body could not be read. Nothing was sent.',
+  }), async (req, res) => {
+    const controller = new AbortController();
+    const onClose = () => {
+      if (!res.writableEnded) controller.abort();
+    };
+    res.on('close', onClose);
+    try {
+      const body = req.body && typeof req.body === 'object' && !Array.isArray(req.body) ? req.body : {};
+      const result = await host.dispatchAgentBrowserAction({
+        action: body.action,
+        parameters: body.parameters,
+        context: body.context,
+        providerId: body.providerId,
+        signal: controller.signal,
+      });
+      res.json({ ok: true, providerId: result.providerId, data: result.data });
+    } catch (error) {
+      if (res.headersSent || res.writableEnded) return;
+      actionError(res, error);
+    } finally {
+      res.off('close', onClose);
+    }
+  });
+};

package/server/lib/browser-provider/routes.test.js

@@ -0,0 +1,120 @@
+import express from 'express';
+import request from 'supertest';
+import { describe, expect, test } from 'vitest';
+
+import { createBrowserProviderHost } from './host.js';
+import { registerBrowserProviderRoutes } from './routes.js';
+
+const createApp = (host = createBrowserProviderHost()) => {
+  const app = express();
+  registerBrowserProviderRoutes(app, { host });
+  return { app, host };
+};
+
+describe('browser provider routes', () => {
+  test('an empty catalog is an authoritative empty list, not a failure', async () => {
+    const { app } = createApp();
+    const response = await request(app).get('/api/browser-providers');
+    expect(response.status).toBe(200);
+    expect(response.body).toEqual({ providers: [], selectedId: null });
+  });
+
+  test('a catalog read failure is not an empty successful list', async () => {
+    const host = createBrowserProviderHost({
+      readInstalled: async () => {
+        throw new Error('disk');
+      },
+    });
+    const { app } = createApp(host);
+    const response = await request(app).get('/api/browser-providers');
+    expect(response.status).toBe(503);
+    expect(response.body.code).toBe('CATALOG_UNAVAILABLE');
+    expect(response.body.providers).toBeUndefined();
+  });
+
+  test('selects a provider and sends one action to it', async () => {
+    const { app, host } = createApp();
+    host.install({
+      id: 'server-chrome',
+      name: 'Server Chrome',
+      service: { provides: ['browser'] },
+      answer: async (action) => ({
+        ok: true,
+        data: { echoed: action.action, selector: action.parameters.selector },
+      }),
+    });
+
+    const selected = await request(app)
+      .put('/api/browser-providers/selection')
+      .send({ id: 'server-chrome' });
+    expect(selected.status).toBe(200);
+    expect(selected.body).toEqual({ selectedId: 'server-chrome' });
+
+    const acted = await request(app)
+      .post('/api/browser-providers/actions')
+      .send({
+        action: 'browser.click',
+        parameters: { selector: '#save' },
+        context: { directory: '/repo', sessionId: 'ses_1' },
+      });
+    expect(acted.status).toBe(200);
+    expect(acted.body).toEqual({
+      ok: true,
+      providerId: 'server-chrome',
+      data: { echoed: 'browser.click', selector: '#save' },
+    });
+  });
+
+  test('no provider is an explicit refusal, not an empty success', async () => {
+    const { app } = createApp();
+    const response = await request(app)
+      .post('/api/browser-providers/actions')
+      .send({ action: 'browser.snapshot', parameters: {} });
+    expect(response.status).toBe(409);
+    expect(response.body.ok).toBe(false);
+    expect(response.body.code).toBe('NO_PROVIDER');
+    expect(response.body.data).toBeUndefined();
+  });
+
+  test('an unknown selection is not stored', async () => {
+    const { app, host } = createApp();
+    const response = await request(app)
+      .put('/api/browser-providers/selection')
+      .send({ id: 'missing' });
+    expect(response.status).toBe(404);
+    expect(response.body.code).toBe('PROVIDER_NOT_FOUND');
+    expect(host.selectedId()).toBeNull();
+  });
+
+  test('a provider rejection is not ok data', async () => {
+    const { app, host } = createApp();
+    host.install({
+      id: 'server-chrome',
+      name: 'Server Chrome',
+      provides: ['browser'],
+      answer: async () => ({ ok: false, error: 'No element matches #save' }),
+    });
+    await host.select('server-chrome');
+    const response = await request(app)
+      .post('/api/browser-providers/actions')
+      .send({ action: 'browser.click', parameters: { selector: '#save' } });
+    expect(response.status).toBe(400);
+    expect(response.body).toEqual({
+      ok: false,
+      code: 'PROVIDER_REJECTED',
+      error: 'No element matches #save',
+    });
+  });
+
+  test('invalid JSON is not sent and is not success', async () => {
+    const { app } = createApp();
+    const response = await request(app)
+      .post('/api/browser-providers/actions')
+      .set('content-type', 'application/json')
+      .send('{');
+    expect(response.status).toBe(400);
+    expect(response.body.ok).toBe(false);
+    expect(response.body.code).toBe('INVALID_ACTION');
+    expect(response.body.data).toBeUndefined();
+  });
+});

package/server/lib/browser-provider/selection-store.js

@@ -0,0 +1,43 @@
+/**
+ * Persists only the selected provider id. A missing file is no selection.
+ * A read that fails is not "nothing selected": the caller must not overwrite
+ * the file or treat the catalog as an empty success.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { readBrowserProviderId } from './contract.js';
+
+/**
+ * @param {string} filePath
+ */
+export const createBrowserProviderSelectionStore = (filePath) => ({
+  async read() {
+    let raw;
+    try {
+      raw = await fs.readFile(filePath, 'utf8');
+    } catch (error) {
+      if (error?.code === 'ENOENT') return null;
+      throw error;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (error) {
+      throw error;
+    }
+    return readBrowserProviderId(parsed?.selectedId);
+  },
+
+  async write(id) {
+    const selectedId = readBrowserProviderId(id);
+    if (!selectedId) {
+      throw new Error('browser provider selection id is invalid');
+    }
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const temp = `${filePath}.${process.pid}.tmp`;
+    await fs.writeFile(temp, `${JSON.stringify({ selectedId })}\n`, 'utf8');
+    await fs.rename(temp, filePath);
+  },
+});

package/server/lib/browser-provider/selection-store.test.js

@@ -0,0 +1,35 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, describe, expect, test } from 'vitest';
+
+import { createBrowserProviderSelectionStore } from './selection-store.js';
+
+const dirs = [];
+
+afterEach(async () => {
+  await Promise.all(dirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+});
+
+describe('browser provider selection store', () => {
+  test('a missing file is no selection, and a write round-trips only the id', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'browser-provider-'));
+    dirs.push(dir);
+    const store = createBrowserProviderSelectionStore(path.join(dir, 'nested', 'browser-provider-selection.json'));
+    await expect(store.read()).resolves.toBeNull();
+    await store.write('server-chrome');
+    await expect(store.read()).resolves.toBe('server-chrome');
+    const raw = await fs.readFile(path.join(dir, 'nested', 'browser-provider-selection.json'), 'utf8');
+    expect(JSON.parse(raw)).toEqual({ selectedId: 'server-chrome' });
+  });
+
+  test('a corrupt file is a read failure, not an empty selection', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'browser-provider-'));
+    dirs.push(dir);
+    const filePath = path.join(dir, 'browser-provider-selection.json');
+    await fs.writeFile(filePath, '{', 'utf8');
+    const store = createBrowserProviderSelectionStore(filePath);
+    await expect(store.read()).rejects.toThrow();
+  });
+});

package/server/lib/notifications/DOCUMENTATION.md

@@ -107,7 +107,9 @@ This module provides notification message preparation utilities for the web serv
   - `extractLastMessageText(payload, maxLength?)`
   - `fetchLastAssistantMessageText(sessionId, messageId, maxLength?)`
   - `maybeCacheSessionInfoFromEvent(payload)`
-  - `buildTemplateVariables(payload, sessionId)`
+  - `buildTemplateVariables(payload, sessionId)` — `session_name` is the session title. OpenCode 2 returns that title on `GET /api/session/:id` as `{ data: { title } }` and on `session.created` / `session.renamed` as `data.title`. Legacy `properties.info.title` still counts. An empty title stays empty so push can fall back to the localized "Session" label. `agent_name` / `model_name` fall back to that same session record when the triggering event has none. `fetchLastAssistantMessageText` accepts a legacy message array and an OpenCode 2 `{ data }` page (`order=desc`).
+- Question prompts come from legacy `question.asked` or OpenCode 2 `form.created` (`data.form`). Permission prompts read `permission.asked` from `properties` or `data` (`action`, `message`, `id`). `form.replied` / `form.cancelled` cancel a pending question notification the same way `permission.replied` cancels a permission notification.
+- iOS APNs and Android FCM share this payload: native banners stay scenario title + session name. Desktop, in-app, and web-push use the resolved template title and body.
   - `getCachedZenModels()`
 
 ## Constants