@lowdefy/server-dev 6.1.0 → 7.0.0

package/lib/docs/journeyMutantCookie.chromium.test.mjs

@@ -0,0 +1,150 @@
+/*
+  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 http from 'node:http';
+
+import { jest } from '@jest/globals';
+
+import pageReadyScript from '../../test-utils/pageReadyScript.mjs';
+
+// A real Chromium against a small server that resolves every request's
+// cookie header the way createLowdefyContext does, so the browser leg of a
+// mutant run is pinned: the cookie openPage writes is the one the dev server
+// verifies, it rides every request of every actor of the journey and nothing
+// from any other context, page JavaScript cannot read it, and a detached hop
+// forwards it alone. Skipped when no Chromium can be launched.
+jest.unstable_mockModule('../build/config.js', () => ({ default: {} }));
+
+const { getBrowser, openPage } = await import('./getBrowser.js');
+const { default: createJourneyActors } = await import('./createJourneyActors.js');
+const { openMutantRun, readMutantRun } = await import('../server/mutants/mutantRuns.js');
+const { forwardJourneyCookies } = await import('../server/journeyCookies.js');
+const { journeyActorToken } = await import('../server/auth/journeyActor.js');
+
+// The page marks itself ready once its requests finish, so every request the
+// test counts is made before openPage returns.
+function pageHtml(pageId) {
+  return `<!doctype html><html><head><title>loading</title></head><body><script>
+    fetch('/api/page/${pageId}', { credentials: 'same-origin' })
+      .then(() => fetch('/api/request/${pageId}/save', { method: 'POST' }))
+      .then(() => {
+        ${pageReadyScript({ pageId })}
+        document.title = 'done';
+      });
+  </script></body></html>`;
+}
+
+let server;
+let origin;
+const received = [];
+let browser = null;
+try {
+  browser = await getBrowser();
+} catch {
+  browser = null;
+}
+const chromiumTest = browser === null ? test.skip : test;
+
+beforeAll(async () => {
+  server = http.createServer((req, res) => {
+    const [, pageId] = req.url.match(/^\/(?:api\/(?:page|request)\/)?([a-z]+)/) ?? [];
+    received.push({ url: req.url, pageId, cookie: req.headers.cookie });
+    if (!req.url.startsWith('/api/')) {
+      res.writeHead(200, { 'content-type': 'text/html' });
+      res.end(pageHtml(pageId));
+      return;
+    }
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end('{}');
+  });
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  origin = `http://127.0.0.1:${server.address().port}`;
+});
+
+// Closing Chromium on Windows can take longer than Jest's 5 s hook default.
+afterAll(async () => {
+  await browser?.close();
+  server.closeAllConnections();
+  await new Promise((resolve) => server.close(resolve));
+}, 30000);
+
+// What is pinned is which requests carry the cookie, not how fast a page
+// loads: a cold Chromium on a Windows runner can take seconds over the first
+// navigation.
+const PAGE_TIMEOUT = 15000;
+
+chromiumTest(
+  'a mutant cookie reaches only the journey actors, unreadable by the page, and alone on the loopback hop',
+  async () => {
+    const opened = openMutantRun({
+      mutant: {
+        buildId: 'b',
+        artifact: 'pages/journey.json',
+        key: 'k',
+        arg: null,
+        operator: 'drop-block',
+      },
+    });
+    const actors = createJourneyActors({
+      browser,
+      origin,
+      basePath: '',
+      pageId: 'journey',
+      user: 'none',
+      timeout: PAGE_TIMEOUT,
+      mutantCookie: opened.cookiePayload,
+    });
+    let bystander;
+    try {
+      const main = await actors.switchTo('main');
+      await main.page.waitForFunction(() => document.title === 'done');
+      const other = await actors.switchTo('other');
+      await other.page.waitForFunction(() => document.title === 'done');
+      // A developer's tab, open beside the run.
+      bystander = await openPage({
+        browser,
+        origin,
+        pageId: 'bystander',
+        user: 'none',
+        timeout: PAGE_TIMEOUT,
+      });
+      await bystander.page.waitForFunction(() => document.title === 'done');
+
+      expect(await main.page.evaluate(() => document.cookie)).not.toContain('lowdefy_journey');
+
+      const journeyRequests = received.filter((request) => request.pageId === 'journey');
+      const bystanderRequests = received.filter((request) => request.pageId === 'bystander');
+      // Each actor loads the page, then its page config and request: six in all.
+      expect(journeyRequests).toHaveLength(6);
+      expect(bystanderRequests).toHaveLength(3);
+      journeyRequests.forEach((request) => {
+        expect(readMutantRun(request.cookie)).toBe(opened.run);
+        expect(forwardJourneyCookies({ cookieHeader: request.cookie })).toEqual(
+          `lowdefy_journey_mutant=${journeyActorToken}.${opened.cookiePayload}`
+        );
+      });
+      bystanderRequests.forEach((request) => {
+        expect(readMutantRun(request.cookie)).toBeNull();
+        expect(forwardJourneyCookies({ cookieHeader: request.cookie })).toEqual('');
+      });
+    } finally {
+      await bystander?.context.close();
+      await actors.closeAll();
+      opened.close();
+    }
+  },
+  30000
+);

package/lib/docs/journeyRunRecording.js

@@ -0,0 +1,35 @@
+/*
+  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 { createTraceId, type } from '@lowdefy/helpers';
+
+// The recording identity a journey run's browser contexts carry. A run the
+// caller records keeps the identity it was given. Any other run gets one of
+// its own that records nothing (record: false), so the errors its pages and
+// requests cause are still stamped with its run and claimed by its own error
+// buffer, not left in the shared stores. `by` names who started the run.
+function journeyRunRecording({ recording, by }) {
+  if (!type.isUndefined(recording)) {
+    return recording;
+  }
+  return {
+    source: 'journey',
+    run: { id: createTraceId(), by: by ?? null, journey: null },
+    record: false,
+  };
+}
+
+export default journeyRunRecording;

package/lib/docs/journeyRunRecording.test.mjs

@@ -0,0 +1,39 @@
+/*
+  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 } from '@lowdefy/helpers';
+
+import journeyRunRecording from './journeyRunRecording.js';
+
+test('journeyRunRecording keeps the recording a caller passes', () => {
+  const recording = {
+    source: 'journey',
+    run: { id: '20261003T151200Z-p0d4rm', by: 'test', journey: 'a' },
+  };
+  expect(journeyRunRecording({ recording, by: 'tool' })).toBe(recording);
+});
+
+test('journeyRunRecording gives a run with no recording a fresh identity that records nothing', () => {
+  const first = journeyRunRecording({ by: 'test' });
+  const second = journeyRunRecording({ by: 'test' });
+  expect(first).toEqual({
+    source: 'journey',
+    run: { id: expect.any(String), by: 'test', journey: null },
+    record: false,
+  });
+  expect(isTraceId(first.run.id)).toBe(true);
+  expect(second.run.id).not.toEqual(first.run.id);
+});

package/lib/docs/keepEventStreamAlive.js

@@ -0,0 +1,68 @@
+/*
+  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.
+*/
+
+// The interval @hono/mcp pings its GET stream at.
+const KEEP_ALIVE_MS = 30000;
+
+// An SSE comment: every client skips it, and it resets their idle timers.
+const KEEP_ALIVE_COMMENT = new TextEncoder().encode(': keep-alive\n\n');
+
+// A tool call answered as an event stream sends nothing until it is done, and
+// a journey can run for many minutes. HTTP clients end a response body that
+// stays silent too long - Node's fetch after 5 minutes, which is what cut the
+// lowdefy mcp shim off a long journey - and @hono/mcp keeps only its GET
+// stream alive. Comments go between the transport's chunks, each of which is
+// a whole event.
+function keepEventStreamAlive({ response, intervalMs = KEEP_ALIVE_MS }) {
+  const contentType = response.headers.get('content-type') ?? '';
+  if (!contentType.includes('text/event-stream') || response.body === null) {
+    return response;
+  }
+  const reader = response.body.getReader();
+  let timer;
+  const body = new ReadableStream({
+    start(controller) {
+      timer = setInterval(() => controller.enqueue(KEEP_ALIVE_COMMENT), intervalMs);
+    },
+    async pull(controller) {
+      let chunk;
+      try {
+        chunk = await reader.read();
+      } catch (error) {
+        clearInterval(timer);
+        controller.error(error);
+        return;
+      }
+      if (chunk.done) {
+        clearInterval(timer);
+        controller.close();
+        return;
+      }
+      controller.enqueue(chunk.value);
+    },
+    cancel(reason) {
+      clearInterval(timer);
+      return reader.cancel(reason);
+    },
+  });
+  return new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}
+
+export default keepEventStreamAlive;

package/lib/docs/keepEventStreamAlive.test.mjs

@@ -0,0 +1,77 @@
+/*
+  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 keepEventStreamAlive from './keepEventStreamAlive.js';
+
+const encoder = new TextEncoder();
+const answer = 'event: message\ndata: {"jsonrpc":"2.0","id":1,"result":{}}\n\n';
+
+// An event stream that says nothing for a while, then answers and ends.
+function slowAnswer({ delayMs }) {
+  const body = new ReadableStream({
+    start(controller) {
+      setTimeout(() => {
+        controller.enqueue(encoder.encode(answer));
+        controller.close();
+      }, delayMs);
+    },
+  });
+  return new Response(body, { headers: { 'content-type': 'text/event-stream' } });
+}
+
+test('keepEventStreamAlive sends comments while a tool call is silent, then the answer', async () => {
+  // The tool call answers only once the client has read two comments, so the
+  // test does not depend on how promptly timers fire.
+  let answerNow;
+  const body = new ReadableStream({
+    start(controller) {
+      answerNow = () => {
+        controller.enqueue(encoder.encode(answer));
+        controller.close();
+      };
+    },
+  });
+  const response = keepEventStreamAlive({
+    response: new Response(body, { headers: { 'content-type': 'text/event-stream' } }),
+    intervalMs: 10,
+  });
+  expect(response.headers.get('content-type')).toEqual('text/event-stream');
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  const read = async () => decoder.decode((await reader.read()).value);
+  expect(await read()).toEqual(': keep-alive\n\n');
+  expect(await read()).toEqual(': keep-alive\n\n');
+  answerNow();
+  let rest = '';
+  let chunk = await reader.read();
+  while (!chunk.done) {
+    rest += decoder.decode(chunk.value);
+    chunk = await reader.read();
+  }
+  expect(rest.endsWith(answer)).toBe(true);
+});
+
+test('keepEventStreamAlive stops its comments when the stream ends', async () => {
+  const response = keepEventStreamAlive({ response: slowAnswer({ delayMs: 0 }), intervalMs: 10 });
+  const text = await response.text();
+  await new Promise((resolve) => setTimeout(resolve, 50));
+  expect(text).toEqual(answer);
+});
+
+test('keepEventStreamAlive leaves a JSON answer alone', () => {
+  const response = new Response('{}', { headers: { 'content-type': 'application/json' } });
+  expect(keepEventStreamAlive({ response })).toBe(response);
+});

package/lib/docs/launchBrowser.js

@@ -0,0 +1,83 @@
+/*
+  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 { type } from '@lowdefy/helpers';
+
+import installHeadlessShell from './installHeadlessShell.js';
+import isHeadlessShellIncomplete from './isHeadlessShellIncomplete.js';
+import registerShownTextEngine from './registerShownTextEngine.js';
+
+// The manager tags every browser this child launches, so it can kill one
+// left behind when the child is killed outright (system Chrome runs in its
+// own process group and outlives a SIGKILLed parent). Chrome and the shell
+// ignore switches they do not know.
+function launchArgs() {
+  const tag = process.env.LOWDEFY_BROWSER_TAG;
+  if (type.isNone(tag) || tag === '') {
+    return [];
+  }
+  return [`--lowdefy-browser-tag=${tag}`];
+}
+
+function isExecutableMissing(error) {
+  return type.isString(error?.message) && error.message.includes("Executable doesn't exist");
+}
+
+// A shell whose install was cut short (a timed-out install this server
+// killed, a dev server killed mid-download) has its executable but no
+// completion marker, and fails to launch with some other error. It is as
+// missing as one never installed, and the installer repairs it.
+async function isShellMissing(error) {
+  if (isExecutableMissing(error)) {
+    return true;
+  }
+  return isHeadlessShellIncomplete();
+}
+
+// Playwright's chromium-headless-shell first: a fifth of system Chrome's
+// memory per page, a launch under a second, and it exits with its parent.
+// System Chrome is the fallback while the shell is missing. playwright-core
+// is imported here, not at the top of the module, so the Vite child does not
+// load it at boot. The journey runner's selector engine is registered first,
+// so every page of the browser can resolve a `containing` target.
+async function launchBrowser() {
+  const { chromium, selectors } = await import('playwright-core');
+  await registerShownTextEngine(selectors);
+  const args = launchArgs();
+  try {
+    return await chromium.launch({ args });
+  } catch (shellError) {
+    const install = (await isShellMissing(shellError)) ? installHeadlessShell() : null;
+    try {
+      return await chromium.launch({ channel: 'chrome', args });
+    } catch {
+      if (type.isNone(install)) {
+        throw shellError;
+      }
+      // No Chrome either: this call waits for the shell download, which
+      // gives up after a time limit (installHeadlessShell.js).
+      const { installed, reason } = await install;
+      if (!installed) {
+        throw new Error(
+          `The chromium-headless-shell install failed (${reason}), and system Chrome is not installed.`
+        );
+      }
+      return await chromium.launch({ args });
+    }
+  }
+}
+
+export default launchBrowser;

package/lib/docs/launchBrowser.test.mjs

@@ -0,0 +1,175 @@
+/*
+  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';
+
+const mockLaunch = jest.fn();
+const mockInstall = jest.fn();
+const mockIsIncomplete = jest.fn(async () => false);
+jest.unstable_mockModule('playwright-core', () => ({
+  chromium: { launch: mockLaunch },
+  selectors: { register: jest.fn(async () => {}) },
+}));
+jest.unstable_mockModule('./installHeadlessShell.js', () => ({ default: mockInstall }));
+jest.unstable_mockModule('./isHeadlessShellIncomplete.js', () => ({ default: mockIsIncomplete }));
+
+const { default: launchBrowser } = await import('./launchBrowser.js');
+
+const shellMissing = new Error(
+  "browserType.launch: Executable doesn't exist at /cache/chromium_headless_shell-1217/chrome-headless-shell"
+);
+const chromeMissing = new Error('browserType.launch: Chromium distribution "chrome" is not found.');
+
+function isChromeLaunch(options) {
+  return options.channel === 'chrome';
+}
+
+afterEach(() => {
+  delete process.env.LOWDEFY_BROWSER_TAG;
+  mockIsIncomplete.mockResolvedValue(false);
+});
+
+test('launchBrowser launches the headless shell and never system Chrome when the shell is installed', async () => {
+  const shell = { name: 'shell' };
+  mockLaunch.mockResolvedValue(shell);
+
+  expect(await launchBrowser()).toBe(shell);
+  expect(mockLaunch).toHaveBeenCalledTimes(1);
+  expect(mockLaunch.mock.calls[0][0]).toEqual({ args: [] });
+  expect(mockInstall).not.toHaveBeenCalled();
+});
+
+test('launchBrowser tags the browser with the tag the manager gave this child', async () => {
+  process.env.LOWDEFY_BROWSER_TAG = 'tag-1';
+  mockLaunch.mockImplementation(async (options) => {
+    if (isChromeLaunch(options)) return { name: 'chrome' };
+    throw shellMissing;
+  });
+  mockInstall.mockReturnValue(null);
+
+  await launchBrowser();
+
+  expect(mockLaunch.mock.calls[0][0]).toEqual({ args: ['--lowdefy-browser-tag=tag-1'] });
+  expect(mockLaunch.mock.calls[1][0]).toEqual({
+    channel: 'chrome',
+    args: ['--lowdefy-browser-tag=tag-1'],
+  });
+});
+
+test('launchBrowser serves the call with system Chrome while the shell installs', async () => {
+  const chrome = { name: 'chrome' };
+  mockLaunch.mockImplementation(async (options) => {
+    if (isChromeLaunch(options)) return chrome;
+    throw shellMissing;
+  });
+  // Never settles: the call must not wait for the download.
+  mockInstall.mockReturnValue(new Promise(() => {}));
+
+  expect(await launchBrowser()).toBe(chrome);
+  expect(mockInstall).toHaveBeenCalledTimes(1);
+});
+
+test('launchBrowser waits for the shell install when system Chrome is missing too', async () => {
+  const shell = { name: 'shell' };
+  let installed = false;
+  mockLaunch.mockImplementation(async (options) => {
+    if (isChromeLaunch(options)) throw chromeMissing;
+    if (!installed) throw shellMissing;
+    return shell;
+  });
+  mockInstall.mockImplementation(async () => {
+    installed = true;
+    return { installed: true };
+  });
+
+  expect(await launchBrowser()).toBe(shell);
+  expect(mockLaunch).toHaveBeenCalledTimes(3);
+});
+
+test('launchBrowser says why when both browsers are missing and the install failed or timed out', async () => {
+  mockLaunch.mockImplementation(async (options) => {
+    throw isChromeLaunch(options) ? chromeMissing : shellMissing;
+  });
+  mockInstall.mockResolvedValue({
+    installed: false,
+    reason: 'the install did not finish within 3 minutes',
+  });
+
+  await expect(launchBrowser()).rejects.toThrow(
+    'The chromium-headless-shell install failed (the install did not finish within 3 minutes), and system Chrome is not installed.'
+  );
+});
+
+test('launchBrowser throws the shell error when both browsers are missing and downloads are off', async () => {
+  mockLaunch.mockImplementation(async (options) => {
+    throw isChromeLaunch(options) ? chromeMissing : shellMissing;
+  });
+  mockInstall.mockReturnValue(null);
+
+  await expect(launchBrowser()).rejects.toBe(shellMissing);
+  expect(mockLaunch).toHaveBeenCalledTimes(2);
+});
+
+test('launchBrowser falls back to system Chrome without installing when the shell fails for another reason', async () => {
+  const chrome = { name: 'chrome' };
+  mockLaunch.mockImplementation(async (options) => {
+    if (isChromeLaunch(options)) return chrome;
+    throw new Error('browserType.launch: Target page, context or browser has been closed');
+  });
+
+  expect(await launchBrowser()).toBe(chrome);
+  expect(mockInstall).not.toHaveBeenCalled();
+});
+
+// A killed install can leave the executable in place without Playwright's
+// INSTALLATION_COMPLETE marker; the shell then fails to launch with an error
+// that does not say the executable is missing.
+const partialShellLaunchError = new Error(
+  'browserType.launch: Browser closed.\n==================== Browser output: ====================\n<launching> /cache/chromium_headless_shell-1217/chrome-headless-shell'
+);
+
+test('launchBrowser installs the shell when the executable exists but its install never completed', async () => {
+  const shell = { name: 'shell' };
+  let installed = false;
+  mockLaunch.mockImplementation(async (options) => {
+    if (isChromeLaunch(options)) throw chromeMissing;
+    if (!installed) throw partialShellLaunchError;
+    return shell;
+  });
+  mockIsIncomplete.mockResolvedValue(true);
+  mockInstall.mockImplementation(async () => {
+    installed = true;
+    return { installed: true };
+  });
+
+  expect(await launchBrowser()).toBe(shell);
+  expect(mockInstall).toHaveBeenCalledTimes(1);
+});
+
+test('launchBrowser says why when an incomplete shell cannot be reinstalled and system Chrome is missing', async () => {
+  mockLaunch.mockImplementation(async (options) => {
+    throw isChromeLaunch(options) ? chromeMissing : partialShellLaunchError;
+  });
+  mockIsIncomplete.mockResolvedValue(true);
+  mockInstall.mockResolvedValue({
+    installed: false,
+    reason: 'the install did not finish within 3 minutes',
+  });
+
+  await expect(launchBrowser()).rejects.toThrow(
+    'The chromium-headless-shell install failed (the install did not finish within 3 minutes), and system Chrome is not installed.'
+  );
+});