@lowdefy/server-dev 6.1.0 → 7.0.0

package/src/routes/devInspect.test.mjs

@@ -17,7 +17,7 @@
 import { Hono } from 'hono';
 import { jest } from '@jest/globals';
 
-const { listTabs, registerTab, requestFromTab, unregisterTab } = await import(
+const { listTabs, registerTab, requestFromTab, unregisterTab, updateTabPage } = await import(
   '../../lib/docs/tabChannel.js'
 );
 const { default: devInspectHandler } = await import('./devInspect.js');
@@ -41,8 +41,13 @@ afterEach(() => {
   listTabs().forEach((tab) => unregisterTab({ id: tab.id }));
 });
 
+function connectTab({ id, pageId, send = jest.fn() }) {
+  registerTab({ id, send });
+  updateTabPage({ id, pageId, pathParams: {}, instanceKey: `page:${pageId}` });
+}
+
 test('GET /api/dev-inspect lists connected tabs', async () => {
-  registerTab({ id: 'tab-1', pageId: 'home', send: jest.fn() });
+  connectTab({ id: 'tab-1', pageId: 'home' });
   const res = await createApp().request('/api/dev-inspect');
   expect(res.status).toBe(200);
   const body = await res.json();
@@ -51,7 +56,7 @@ test('GET /api/dev-inspect lists connected tabs', async () => {
 });
 
 test('POST /api/dev-inspect/page returns 403 when the Origin header is missing', async () => {
-  registerTab({ id: 'tab-1', pageId: 'home', send: jest.fn() });
+  connectTab({ id: 'tab-1', pageId: 'home' });
   const res = await createApp().request('/api/dev-inspect/page', {
     method: 'POST',
     headers: { host: 'localhost:3001', 'content-type': 'application/json' },
@@ -62,17 +67,49 @@ test('POST /api/dev-inspect/page returns 403 when the Origin header is missing',
 });
 
 test('POST /api/dev-inspect/page moves a connected tab to the posted page', async () => {
-  registerTab({ id: 'tab-1', pageId: 'home', send: jest.fn() });
+  connectTab({ id: 'tab-1', pageId: 'home' });
   const res = await createApp().request('/api/dev-inspect/page', {
     method: 'POST',
     headers: sameOriginHeaders,
-    body: JSON.stringify({ tabId: 'tab-1', pageId: 'about' }),
+    body: JSON.stringify({ tabId: 'tab-1', pageId: 'about', instanceKey: 'page:about' }),
   });
   expect(res.status).toBe(200);
   expect(await res.json()).toEqual({ ok: true });
   expect(listTabs()[0].pageId).toBe('about');
 });
 
+test('POST /api/dev-inspect/page records the page instance a tab shows', async () => {
+  connectTab({ id: 'tab-1', pageId: 'home' });
+  const res = await createApp().request('/api/dev-inspect/page', {
+    method: 'POST',
+    headers: sameOriginHeaders,
+    body: JSON.stringify({
+      tabId: 'tab-1',
+      pageId: 'ticket',
+      pathParams: { space: 's', ticket_id: '2' },
+      instanceKey: 'page:ticket#tickets/s/2',
+    }),
+  });
+  expect(res.status).toBe(200);
+  expect(listTabs()[0]).toMatchObject({
+    pageId: 'ticket',
+    pathParams: { space: 's', ticket_id: '2' },
+    instanceKey: 'page:ticket#tickets/s/2',
+  });
+});
+
+test('POST /api/dev-inspect/page returns 400 when the instance key is missing', async () => {
+  connectTab({ id: 'tab-1', pageId: 'home' });
+  const res = await createApp().request('/api/dev-inspect/page', {
+    method: 'POST',
+    headers: sameOriginHeaders,
+    body: JSON.stringify({ tabId: 'tab-1', pageId: 'about' }),
+  });
+  expect(res.status).toBe(400);
+  expect(await res.json()).toEqual({ error: 'Missing "pageId" or "instanceKey".' });
+  expect(listTabs()[0].pageId).toBe('home');
+});
+
 test('POST /api/dev-inspect/page returns 400 when tabId is missing', async () => {
   const res = await createApp().request('/api/dev-inspect/page', {
     method: 'POST',
@@ -87,7 +124,7 @@ test('POST /api/dev-inspect/page for a tab that already disconnected returns ok'
   const res = await createApp().request('/api/dev-inspect/page', {
     method: 'POST',
     headers: sameOriginHeaders,
-    body: JSON.stringify({ tabId: 'gone', pageId: 'about' }),
+    body: JSON.stringify({ tabId: 'gone', pageId: 'about', instanceKey: 'page:about' }),
   });
   expect(res.status).toBe(200);
   expect(listTabs()).toHaveLength(0);
@@ -95,7 +132,7 @@ test('POST /api/dev-inspect/page for a tab that already disconnected returns ok'
 
 test('POST /api/dev-inspect resolves a pending tab request with the posted result', async () => {
   const send = jest.fn();
-  registerTab({ id: 'tab-1', pageId: 'home', send });
+  connectTab({ id: 'tab-1', pageId: 'home', send });
   const pending = requestFromTab({ pageId: 'home', event: 'inspect-request' });
   const [, { requestId }] = send.mock.calls[0];
 

package/src/routes/devRecording.js

@@ -0,0 +1,113 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { isTraceId, omit, type } from '@lowdefy/helpers';
+
+import appendRecords from '../../lib/server/recording/appendRecords.js';
+import getBuildId from '../../lib/docs/getBuildId.js';
+import readRecordingCookie from '../../lib/server/recording/readRecordingCookie.js';
+import servedBuilds from '../../lib/server/recording/servedBuilds.js';
+import { getConfigDirectory } from '../../lib/docs/checkpointPaths.js';
+
+const MAX_RECORDS = 500;
+
+// This route writes to disk, so unlike localDevToolsOnly it does not let a
+// request with no Origin through: only the recorder in a same-origin dev tab
+// posts here. Agents and curl have no reason to.
+function isSameOrigin(c) {
+  const origin = c.req.header('origin');
+  if (!origin) {
+    return false;
+  }
+  try {
+    return new URL(origin).host === c.req.header('host');
+  } catch {
+    return false;
+  }
+}
+
+async function readBody(c) {
+  try {
+    return await c.req.json();
+  } catch {
+    return null;
+  }
+}
+
+function isValidBody(body) {
+  return (
+    type.isObject(body) &&
+    isTraceId(body.session) &&
+    type.isArray(body.records) &&
+    body.records.length <= MAX_RECORDS &&
+    body.records.every((record) => type.isObject(record))
+  );
+}
+
+// The page names the build of the config it rendered when each interaction
+// happened (jitPage.js serves it as `_buildId`). It is kept when this process
+// served it, else (missing, unknown, from before a restart) replaced with the
+// build served now. The cookie decides source and run, never the page: a
+// headless journey run is marked by the dev server's own browser,
+// and everything else records as dev.
+function stampRecord({ record, currentBuild, cookie }) {
+  const rest = omit({ ...record }, ['source', 'run']);
+  const build = servedBuilds.has(record.build) ? record.build : currentBuild;
+  if (cookie === null) {
+    return { ...rest, build, source: 'dev' };
+  }
+  return { ...rest, build, source: cookie.source, run: cookie.run };
+}
+
+// POST /api/dev-recording: the dev recorder (client/Recorder.jsx) posts
+// batches of interaction records here. Each keeps the build its page ran on
+// (or the build served now) and is appended to the trace file of its tab
+// session (dev) or run (journey).
+async function devRecordingHandler(c) {
+  if (!isSameOrigin(c)) {
+    return c.json({ error: 'Forbidden' }, 403);
+  }
+  if (process.env.LOWDEFY_DEV_RECORD === 'false') {
+    return c.body(null, 204);
+  }
+  const cookie = readRecordingCookie(c.req.header('cookie'));
+  if (cookie === 'off' || cookie?.record === false) {
+    return c.body(null, 204);
+  }
+  const body = await readBody(c);
+  if (!isValidBody(body)) {
+    return c.json(
+      {
+        error: `Expected { session, records } with a trace id session and at most ${MAX_RECORDS} record objects.`,
+      },
+      400
+    );
+  }
+  if (body.records.length === 0) {
+    return c.body(null, 204);
+  }
+  const currentBuild = getBuildId();
+  const records = body.records.map((record) => stampRecord({ record, currentBuild, cookie }));
+  appendRecords({
+    configDirectory: getConfigDirectory(),
+    source: cookie === null ? 'dev' : cookie.source,
+    id: cookie === null ? body.session : cookie.run.id,
+    records,
+  });
+  return c.body(null, 204);
+}
+
+export default devRecordingHandler;

package/src/routes/devRecording.test.mjs

@@ -0,0 +1,253 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { Hono } from 'hono';
+import { bodyLimit } from 'hono/body-limit';
+import { jest } from '@jest/globals';
+
+jest.unstable_mockModule('../../lib/docs/getBuildId.js', () => ({
+  default: () => '2026-10-03T14:02:00.000Z',
+}));
+
+const { default: devRecordingHandler } = await import('./devRecording.js');
+const { default: servedBuilds } = await import('../../lib/server/recording/servedBuilds.js');
+const { default: localDevToolsOnly } = await import('../middleware/localDevToolsOnly.js');
+const { JOURNEY_COOKIES, writeJourneyCookie } = await import('../../lib/server/journeyCookies.js');
+const { default: recordingCookiePayload } = await import(
+  '../../lib/server/recording/recordingCookiePayload.js'
+);
+
+const SESSION = '20261003T140311Z-k3x9qa';
+const RUN_ID = '20261003T151200Z-p0d4rm';
+const origin = 'http://localhost:3001';
+let configDirectory;
+
+function createApp() {
+  const app = new Hono();
+  app.use('/api/dev-recording', localDevToolsOnly());
+  app.post('/api/dev-recording', bodyLimit({ maxSize: 1024 * 1024 }), devRecordingHandler);
+  return app;
+}
+
+function record(extra = {}) {
+  return {
+    v: 1,
+    session: SESSION,
+    t: '2026-10-03T14:03:12.000Z',
+    kind: 'click',
+    scope: 'page',
+    page_id: 'tickets',
+    event: null,
+    ...extra,
+  };
+}
+
+function cookieFor(payload) {
+  const cookie = writeJourneyCookie({ name: JOURNEY_COOKIES.recording.name, payload, origin });
+  return `${cookie.name}=${cookie.value}`;
+}
+
+function post({ body, headers = {} }) {
+  return createApp().request('/api/dev-recording', {
+    method: 'POST',
+    headers: {
+      host: 'localhost:3001',
+      origin,
+      'content-type': 'application/json',
+      ...headers,
+    },
+    body: typeof body === 'string' ? body : JSON.stringify(body),
+  });
+}
+
+function readLines(...segments) {
+  const filePath = path.join(configDirectory, '.lowdefy', 'traces', ...segments);
+  return fs
+    .readFileSync(filePath, 'utf8')
+    .split('\n')
+    .filter((line) => line !== '')
+    .map((line) => JSON.parse(line));
+}
+
+function tracesExist() {
+  return fs.existsSync(path.join(configDirectory, '.lowdefy', 'traces'));
+}
+
+beforeEach(() => {
+  configDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-dev-recording-'));
+  process.env.LOWDEFY_DIRECTORY_CONFIG = configDirectory;
+  delete process.env.LOWDEFY_DEV_RECORD;
+});
+
+afterEach(() => {
+  fs.rmSync(configDirectory, { recursive: true, force: true });
+  delete process.env.LOWDEFY_DIRECTORY_CONFIG;
+  delete process.env.LOWDEFY_DEV_RECORD;
+});
+
+test('POST /api/dev-recording refuses a cross-site request', async () => {
+  const res = await post({
+    body: { session: SESSION, records: [record()] },
+    headers: { origin: 'https://evil.example' },
+  });
+  expect(res.status).toBe(403);
+  expect(tracesExist()).toBe(false);
+});
+
+test('POST /api/dev-recording refuses a request with no Origin', async () => {
+  const res = await createApp().request('/api/dev-recording', {
+    method: 'POST',
+    headers: { host: 'localhost:3001', 'content-type': 'application/json' },
+    body: JSON.stringify({ session: SESSION, records: [record()] }),
+  });
+  expect(res.status).toBe(403);
+  expect(tracesExist()).toBe(false);
+});
+
+test('POST /api/dev-recording answers 400 for a session id that is not a trace id', async () => {
+  for (const session of ['../x', '', `${SESSION}/../../x`]) {
+    const res = await post({ body: { session, records: [record()] } });
+    expect(res.status).toBe(400);
+  }
+  expect(tracesExist()).toBe(false);
+});
+
+test('POST /api/dev-recording answers 400 for more than 500 records or non-object records', async () => {
+  const many = Array.from({ length: 501 }, () => record());
+  expect((await post({ body: { session: SESSION, records: many } })).status).toBe(400);
+  expect((await post({ body: { session: SESSION, records: ['x'] } })).status).toBe(400);
+  expect((await post({ body: 'not json' })).status).toBe(400);
+  expect(tracesExist()).toBe(false);
+});
+
+test('POST /api/dev-recording refuses a body over 1 MiB', async () => {
+  const big = 'x'.repeat(1024 * 1024 + 1);
+  const res = await post({ body: { session: SESSION, records: [record({ big })] } });
+  expect(res.status).toBe(413);
+  expect(tracesExist()).toBe(false);
+});
+
+test('POST /api/dev-recording writes nothing when LOWDEFY_DEV_RECORD is false', async () => {
+  process.env.LOWDEFY_DEV_RECORD = 'false';
+  const res = await post({ body: { session: SESSION, records: [record()] } });
+  expect(res.status).toBe(204);
+  expect(tracesExist()).toBe(false);
+});
+
+test('POST /api/dev-recording writes nothing when the recording cookie is off', async () => {
+  const res = await post({
+    body: { session: SESSION, records: [record()] },
+    headers: { cookie: cookieFor('off') },
+  });
+  expect(res.status).toBe(204);
+  expect(tracesExist()).toBe(false);
+});
+
+test('POST /api/dev-recording writes nothing for a journey run that records nothing', async () => {
+  const payload = recordingCookiePayload({
+    recording: {
+      source: 'journey',
+      run: { id: '20261003T160000Z-77abcd', by: 'agent', journey: 'save-ticket' },
+      record: false,
+    },
+  });
+  const res = await post({
+    body: { session: SESSION, records: [record()] },
+    headers: { cookie: cookieFor(payload) },
+  });
+  expect(res.status).toBe(204);
+  expect(tracesExist()).toBe(false);
+});
+
+test('POST /api/dev-recording appends lines to the dev session file, stamped with build and source', async () => {
+  await post({ body: { session: SESSION, records: [record(), record({ kind: 'change' })] } });
+  const res = await post({
+    body: { session: SESSION, records: [record({ source: 'journey', run: { id: RUN_ID } })] },
+  });
+  expect(res.status).toBe(204);
+  const lines = readLines('dev', '2026-10-03', `${SESSION}.jsonl`);
+  expect(lines).toHaveLength(3);
+  lines.forEach((line) => {
+    expect(line.build).toBe('2026-10-03T14:02:00.000Z');
+    expect(line.source).toBe('dev');
+    expect(line).not.toHaveProperty('run');
+  });
+  expect(lines[1].kind).toBe('change');
+});
+
+test('POST /api/dev-recording writes a journey cookie run to its run file, overriding a client source', async () => {
+  const run = {
+    id: RUN_ID,
+    by: 'test',
+    journey: 'tests/journeys/tickets.yaml#Assign a ticket',
+    actor: 'main',
+  };
+  const res = await post({
+    body: { session: SESSION, records: [record({ source: 'dev' })] },
+    headers: {
+      cookie: cookieFor(recordingCookiePayload({ recording: { source: 'journey', run } })),
+    },
+  });
+  expect(res.status).toBe(204);
+  const [line] = readLines('journey', '2026-10-03', `${RUN_ID}.jsonl`);
+  expect(line).toMatchObject({ source: 'journey', run, session: SESSION });
+  expect(fs.existsSync(path.join(configDirectory, '.lowdefy', 'traces', 'dev'))).toBe(false);
+});
+
+test('POST /api/dev-recording records a forged recording cookie as dev', async () => {
+  const payload = recordingCookiePayload({
+    recording: { source: 'journey', run: { id: RUN_ID, by: 'test' } },
+  });
+  const res = await post({
+    body: { session: SESSION, records: [record()] },
+    headers: { cookie: `lowdefy_recording=forged-token.${payload}` },
+  });
+  expect(res.status).toBe(204);
+  const [line] = readLines('dev', '2026-10-03', `${SESSION}.jsonl`);
+  expect(line.source).toBe('dev');
+});
+
+test('POST /api/dev-recording keeps a build the process served a page config under', async () => {
+  servedBuilds.add('2026-10-03T13:58:00.000Z');
+  const res = await post({
+    body: { session: SESSION, records: [record({ build: '2026-10-03T13:58:00.000Z' })] },
+  });
+  expect(res.status).toBe(204);
+  const [line] = readLines('dev', '2026-10-03', `${SESSION}.jsonl`);
+  expect(line.build).toBe('2026-10-03T13:58:00.000Z');
+});
+
+test('POST /api/dev-recording replaces a missing, unknown or non-string build with the build served now', async () => {
+  servedBuilds.add('2026-10-03T13:58:00.000Z');
+  const res = await post({
+    body: {
+      session: SESSION,
+      records: [
+        record(),
+        record({ build: null }),
+        record({ build: '2026-10-03T09:00:00.000Z' }),
+        record({ build: 42 }),
+        record({ build: { id: '2026-10-03T13:58:00.000Z' } }),
+      ],
+    },
+  });
+  expect(res.status).toBe(204);
+  const lines = readLines('dev', '2026-10-03', `${SESSION}.jsonl`);
+  expect(lines.map((line) => line.build)).toEqual(Array(5).fill('2026-10-03T14:02:00.000Z'));
+});

package/src/routes/docs/buildStatus.js

@@ -15,9 +15,17 @@
 */
 
 import getBuildStatus from '../../../lib/docs/getBuildStatus.js';
+import getBuildStatusAfterEdits from '../../../lib/docs/getBuildStatusAfterEdits.js';
+import readProxyBuildWait from '../../../lib/docs/readProxyBuildWait.js';
 
-function docsBuildStatusHandler(c) {
-  return c.json(getBuildStatus());
+// ?wait=true answers once the dev server has processed the latest edits and
+// built the pages they touched.
+async function docsBuildStatusHandler(c) {
+  if (c.req.query('wait') === 'true') {
+    const proxyWait = readProxyBuildWait({ getHeader: (name) => c.req.header(name) });
+    return c.json(await getBuildStatusAfterEdits({ proxyWait }));
+  }
+  return c.json(await getBuildStatus());
 }
 
 export default docsBuildStatusHandler;

package/src/routes/docs/buildStatus.test.mjs

@@ -0,0 +1,46 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { jest } from '@jest/globals';
+import { Hono } from 'hono';
+
+jest.unstable_mockModule('../../../lib/docs/clientErrorStore.js', () => ({
+  default: { list: () => [] },
+}));
+jest.unstable_mockModule('../../../lib/docs/serverErrorStore.js', () => ({
+  default: { list: () => [] },
+}));
+jest.unstable_mockModule('../../../lib/docs/getBuildId.js', () => ({
+  default: () => '2026-10-03T08:00:00.000Z',
+}));
+jest.unstable_mockModule('../../../lib/docs/getPageBuildStatus.js', () => ({
+  default: () => ({ unbuilt: 0 }),
+}));
+jest.unstable_mockModule('../../../lib/docs/readBuildArtifact.js', () => ({
+  default: () => ({ status: 'ok', errors: [], warnings: [] }),
+}));
+
+const { default: docsBuildStatusHandler } = await import('./buildStatus.js');
+
+test('GET /lowdefy-docs/build-status includes the buildId of the build being served', async () => {
+  const app = new Hono();
+  app.get('/lowdefy-docs/build-status', docsBuildStatusHandler);
+
+  const res = await app.request('/lowdefy-docs/build-status');
+
+  expect(res.status).toBe(200);
+  expect((await res.json()).buildId).toBe('2026-10-03T08:00:00.000Z');
+});

package/src/routes/docs/content.js

@@ -14,14 +14,16 @@
   limitations under the License.
 */
 
-import getCoreDoc from '../../../lib/docs/getCoreDoc.js';
+import getDoc from '../../../lib/docs/getDoc.js';
 
 function docsContentHandler(c) {
   const slug = c.req.param('slug');
-  const doc = getCoreDoc({ slug });
+  const doc = getDoc({ slug });
   if (doc === null) {
     return c.json(
-      { error: `No doc found for slug "${slug}". Use GET /lowdefy-docs/search?q=... to find the right slug.` },
+      {
+        error: `No doc found for slug "${slug}". Use GET /lowdefy-docs/search?q=... to find the right slug.`,
+      },
       404
     );
   }

package/src/routes/docs/evalOperator.js

@@ -15,6 +15,7 @@
 */
 
 import evalOperator from '../../../lib/docs/evalOperator.js';
+import parsePathParamsParam from './parsePathParamsParam.js';
 import parseUserParam from './parseUserParam.js';
 
 async function docsEvalOperatorHandler(c) {
@@ -42,7 +43,20 @@ async function docsEvalOperatorHandler(c) {
     return c.json({ error: userError }, 400);
   }
 
-  const result = await evalOperator({ origin, pageId, expression, source, user });
+  const { pathParams, error: pathParamsError } = parsePathParamsParam({ value: body.pathParams });
+  if (pathParamsError) {
+    return c.json({ error: pathParamsError }, 400);
+  }
+
+  const result = await evalOperator({
+    origin,
+    pageId,
+    pathParams,
+    expression,
+    source,
+    user,
+    data: body.data,
+  });
   if (result.error) {
     // A contradictory call (`user` with `source: 'tab'`) is the caller's
     // mistake, not a failed render — 502 would read as "the renderer broke" and

package/src/routes/docs/events.js

@@ -0,0 +1,50 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { streamSSE } from 'hono/streaming';
+
+import { bootedAt, subscribe } from '../../../lib/docs/devEventBus.js';
+
+// SSE push channel for agents without MCP support: the same dev events the MCP
+// endpoint delivers as notifications/message, one SSE frame each, named by
+// event type. The first frame is always the restart event so a reconnecting
+// client can tell a server restart from a dropped connection.
+async function docsEventsHandler(c) {
+  return streamSSE(c, async (stream) => {
+    let open = true;
+    const writeEvent = (event) =>
+      stream.writeSSE({ event: event.type, data: JSON.stringify(event) });
+
+    // Subscribe and arm the abort hook before the first await: onAbort does not
+    // fire for a listener added after the client has already gone.
+    const unsubscribe = subscribe(writeEvent);
+    stream.onAbort(() => {
+      open = false;
+      unsubscribe();
+    });
+
+    await writeEvent({ type: 'restart', timestamp: new Date().toISOString(), bootedAt });
+
+    while (open) {
+      await stream.sleep(15000);
+      if (open) {
+        await stream.writeSSE({ event: 'ping', data: '' });
+      }
+    }
+  });
+}
+
+export default docsEventsHandler;