@lowdefy/server-dev 6.1.0 → 7.0.0

package/lib/docs/createDocsMcpServer.test.mjs

@@ -14,8 +14,15 @@
   limitations under the License.
 */
 
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { LoggingMessageNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
+
+import { jest } from '@jest/globals';
 
 import setupTestFixtures from './setupTestFixtures.mjs';
 
@@ -24,7 +31,21 @@ import setupTestFixtures from './setupTestFixtures.mjs';
 const fixtureDir = setupTestFixtures();
 process.chdir(fixtureDir);
 
-const { default: createDocsMcpServer } = await import('./createDocsMcpServer.js');
+// runJourney needs a browser; mocked so the tool's result shaping (JSON text
+// followed by image blocks) can be asserted without one.
+const mockRunJourney = jest.fn();
+jest.unstable_mockModule('./runJourney.js', () => ({
+  default: mockRunJourney,
+  runSteps: jest.fn(),
+  MAIN_ACTOR: 'main',
+}));
+const mockScreenshotPage = jest.fn();
+jest.unstable_mockModule('./screenshotPage.js', () => ({ default: mockScreenshotPage }));
+
+const { default: createDocsMcpServer, subscribeMcpServerToDevEvents } = await import(
+  './createDocsMcpServer.js'
+);
+const { publish } = await import('./devEventBus.js');
 
 const EXPECTED_TOOLS = [
   'lowdefy_overview',
@@ -34,15 +55,20 @@ const EXPECTED_TOOLS = [
   'lowdefy_get_examples',
   'lowdefy_get_doc',
   'lowdefy_search_docs',
+  'lowdefy_search_icons',
   'lowdefy_get_plugin_doc',
   'lowdefy_build_status',
+  'lowdefy_check',
   'lowdefy_get_page_config',
   'lowdefy_find_config',
   'lowdefy_screenshot_page',
+  'lowdefy_run_journey',
   'lowdefy_scaffold_page',
   'lowdefy_inspect_state',
   'lowdefy_eval_operator',
   'lowdefy_run_request',
+  'lowdefy_run_endpoint',
+  'lowdefy_restart',
   'lowdefy_app_map',
   'lowdefy_checkpoint',
   'lowdefy_revert_checkpoint',
@@ -50,17 +76,82 @@ const EXPECTED_TOOLS = [
   'lowdefy_load_state',
   'lowdefy_list_state_checkpoints',
   'lowdefy_checkpoint_to_mocks',
+  'lowdefy_journey_session',
 ];
 
 async function connectClient() {
-  const server = createDocsMcpServer({ origin: 'http://localhost:3000' });
+  const { client } = await connectPair();
+  return client;
+}
+
+async function connectPair() {
+  const server = createDocsMcpServer({ origin: 'http://localhost:3000', version: '7.2.0' });
   const client = new Client({ name: 'test-client', version: '1.0.0' });
   const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
   await server.connect(serverTransport);
   await client.connect(clientTransport);
-  return client;
+  return { client, server };
 }
 
+test('MCP server reports the Lowdefy version it is given as its server version', async () => {
+  const client = await connectClient();
+  expect(client.getServerVersion()).toEqual({ name: 'lowdefy', version: '7.2.0' });
+  await client.close();
+});
+
+test('MCP server declares the logging capability and teaches the push channel', async () => {
+  const client = await connectClient();
+  expect(client.getServerCapabilities().logging).toEqual({});
+  const instructions = client.getInstructions();
+  expect(instructions).toContain('notifications/message');
+  expect(instructions).toContain('logger "lowdefy"');
+  await client.close();
+});
+
+test('subscribeMcpServerToDevEvents forwards bus events as notifications/message from logger lowdefy', async () => {
+  const { client, server } = await connectPair();
+  const received = [];
+  client.setNotificationHandler(
+    LoggingMessageNotificationSchema,
+    (notification) => void received.push(notification.params)
+  );
+  const unsubscribe = subscribeMcpServerToDevEvents(server);
+
+  publish({ type: 'client_error', timestamp: '2026-01-01T00:00:00.000Z', message: 'boom' });
+  publish({ type: 'build', timestamp: '2026-01-01T00:00:01.000Z', status: 'error', errorCount: 1 });
+  publish({ type: 'build', timestamp: '2026-01-01T00:00:02.000Z', status: 'ok', errorCount: 0 });
+  await new Promise((resolve) => setTimeout(resolve, 20));
+
+  expect(received).toEqual([
+    {
+      level: 'info',
+      logger: 'lowdefy',
+      data: { type: 'client_error', timestamp: '2026-01-01T00:00:00.000Z', message: 'boom' },
+    },
+    {
+      level: 'error',
+      logger: 'lowdefy',
+      data: {
+        type: 'build',
+        timestamp: '2026-01-01T00:00:01.000Z',
+        status: 'error',
+        errorCount: 1,
+      },
+    },
+    {
+      level: 'info',
+      logger: 'lowdefy',
+      data: { type: 'build', timestamp: '2026-01-01T00:00:02.000Z', status: 'ok', errorCount: 0 },
+    },
+  ]);
+
+  unsubscribe();
+  publish({ type: 'client_error', message: 'after unsubscribe' });
+  await new Promise((resolve) => setTimeout(resolve, 20));
+  expect(received).toHaveLength(3);
+  await client.close();
+});
+
 test('MCP server exposes instructions teaching the feedback loop', async () => {
   const client = await connectClient();
   const instructions = client.getInstructions();
@@ -77,15 +168,26 @@ test('MCP tools/list returns all lowdefy tools', async () => {
   await client.close();
 });
 
+test('MCP tools/list serves exactly the tools in devToolDefinitions, which the stdio shim lists', async () => {
+  const { default: devToolDefinitions } = await import('./devToolDefinitions.js');
+  const client = await connectClient();
+  const { tools } = await client.listTools();
+  expect(tools.map((tool) => tool.name).sort()).toEqual(Object.keys(devToolDefinitions).sort());
+  await client.close();
+});
+
 test('MCP tools that render a page headless advertise an optional user parameter', async () => {
   const client = await connectClient();
   const { tools } = await client.listTools();
 
   [
     'lowdefy_screenshot_page',
+    'lowdefy_run_journey',
     'lowdefy_inspect_state',
     'lowdefy_eval_operator',
     'lowdefy_load_state',
+    'lowdefy_run_request',
+    'lowdefy_run_endpoint',
   ].forEach((name) => {
     const tool = tools.find((candidate) => candidate.name === name);
     expect(tool.inputSchema.properties.user).toBeDefined();
@@ -95,6 +197,137 @@ test('MCP tools that render a page headless advertise an optional user parameter
   await client.close();
 });
 
+test('MCP tools that act as someone take one user option and share one sentence explaining it', async () => {
+  const client = await connectClient();
+  const { tools } = await client.listTools();
+  const sentence =
+    'Pass user to act as someone: a user object such as {"roles":["admin"]}, "none" to act signed out, or the name of a user in the data set that data names';
+
+  [
+    'lowdefy_screenshot_page',
+    'lowdefy_run_journey',
+    'lowdefy_inspect_state',
+    'lowdefy_eval_operator',
+    'lowdefy_load_state',
+    'lowdefy_run_request',
+    'lowdefy_run_endpoint',
+  ].forEach((name) => {
+    const tool = tools.find((candidate) => candidate.name === name);
+    expect(tool.description).toContain(sentence);
+    expect(tool.inputSchema.properties.data.type).toEqual('string');
+    const forms = JSON.stringify(tool.inputSchema.properties.user);
+    expect(forms).toContain('"const":"none"');
+    expect(forms).toContain('"type":"string"');
+    expect(forms).toContain('"type":"object"');
+  });
+
+  await client.close();
+});
+
+test('MCP tools/call lowdefy_screenshot_page passes data and a data set user name through', async () => {
+  mockScreenshotPage.mockResolvedValue({ data: 'AAAA', mimeType: 'image/png', screenshots: [] });
+  const client = await connectClient();
+
+  await client.callTool({
+    name: 'lowdefy_screenshot_page',
+    arguments: { pageId: 'tickets', user: 'member', data: 'crm' },
+  });
+
+  expect(mockScreenshotPage).toHaveBeenCalledWith(
+    expect.objectContaining({ pageId: 'tickets', user: 'member', data: 'crm' })
+  );
+  await client.close();
+});
+
+test('MCP lowdefy_screenshot_page advertises width and height up to 4096, and colorScheme', async () => {
+  const client = await connectClient();
+  const { tools } = await client.listTools();
+  const { properties } = tools.find((tool) => tool.name === 'lowdefy_screenshot_page').inputSchema;
+
+  expect(properties.width).toMatchObject({ type: 'integer', exclusiveMinimum: 0, maximum: 4096 });
+  expect(properties.height).toMatchObject({ type: 'integer', exclusiveMinimum: 0, maximum: 4096 });
+  expect(properties.colorScheme).toMatchObject({ enum: ['light', 'dark'] });
+  await client.close();
+});
+
+test('MCP lowdefy_screenshot_page advertises steps and urlQuery, and passes them on', async () => {
+  mockScreenshotPage.mockResolvedValue({ data: 'AAAA', mimeType: 'image/png', screenshots: [] });
+  const client = await connectClient();
+  const { tools } = await client.listTools();
+  const { properties } = tools.find((tool) => tool.name === 'lowdefy_screenshot_page').inputSchema;
+  expect(properties.steps).toMatchObject({ type: 'array' });
+  expect(properties.urlQuery).toBeDefined();
+
+  const result = await client.callTool({
+    name: 'lowdefy_screenshot_page',
+    arguments: { pageId: 'gates', urlQuery: { framework: 'popia' }, steps: [{ open: 'status' }] },
+  });
+  expect(mockScreenshotPage).toHaveBeenCalledWith(
+    expect.objectContaining({
+      pageId: 'gates',
+      urlQuery: { framework: 'popia' },
+      steps: [{ open: 'status' }],
+    })
+  );
+  expect(result.content).toEqual([{ type: 'image', data: 'AAAA', mimeType: 'image/png' }]);
+  await client.close();
+});
+
+test('MCP lowdefy_screenshot_page returns a failed step beside the image', async () => {
+  mockScreenshotPage.mockResolvedValue({
+    data: 'AAAA',
+    mimeType: 'image/png',
+    screenshots: [],
+    failure: { index: 0, step: { open: 'x' }, message: 'm' },
+  });
+  const client = await connectClient();
+  const result = await client.callTool({
+    name: 'lowdefy_screenshot_page',
+    arguments: { pageId: 'gates', steps: [{ open: 'x' }] },
+  });
+  expect(result.content).toHaveLength(2);
+  expect(JSON.parse(result.content[0].text).failure.index).toBe(0);
+  expect(result.content[1].type).toBe('image');
+  await client.close();
+});
+
+test('MCP lowdefy_screenshot_page returns screenshot step captures after the final capture', async () => {
+  mockScreenshotPage.mockResolvedValue({
+    data: 'AAAA',
+    mimeType: 'image/png',
+    screenshots: [{ name: 'before', data: 'BBBB', mimeType: 'image/png' }],
+  });
+  const client = await connectClient();
+  const result = await client.callTool({
+    name: 'lowdefy_screenshot_page',
+    arguments: { pageId: 'gates', steps: [{ screenshot: 'before' }, { open: 'status' }] },
+  });
+  expect(JSON.parse(result.content[0].text)).toEqual({
+    passed: true,
+    screenshots: [{ name: 'before' }],
+  });
+  expect(result.content.slice(1)).toEqual([
+    { type: 'image', data: 'AAAA', mimeType: 'image/png' },
+    { type: 'image', data: 'BBBB', mimeType: 'image/png' },
+  ]);
+  await client.close();
+});
+
+test('MCP lowdefy_run_journey advertises a state option of true, false or state paths', async () => {
+  const client = await connectClient();
+  const { tools } = await client.listTools();
+  const { properties, required } = tools.find(
+    (tool) => tool.name === 'lowdefy_run_journey'
+  ).inputSchema;
+
+  expect(properties.state.anyOf).toEqual([
+    { type: 'boolean' },
+    { type: 'array', items: { type: 'string', minLength: 1 } },
+  ]);
+  expect(required).not.toContain('state');
+  await client.close();
+});
+
 test('MCP tools/call lowdefy_get_schema returns a block schema', async () => {
   const client = await connectClient();
   const result = await client.callTool({
@@ -106,6 +339,40 @@ test('MCP tools/call lowdefy_get_schema returns a block schema', async () => {
   await client.close();
 });
 
+test('MCP get_schema, get_doc and find_config describe and return hazards', async () => {
+  const client = await connectClient();
+  const { tools } = await client.listTools();
+  for (const name of ['lowdefy_get_schema', 'lowdefy_get_doc', 'lowdefy_find_config']) {
+    expect(tools.find((tool) => tool.name === name).description).toContain(
+      'Results include `hazards`'
+    );
+  }
+
+  const schema = await client.callTool({
+    name: 'lowdefy_get_schema',
+    arguments: { kind: 'blocks', type: 'TestBlock' },
+  });
+  expect(JSON.parse(schema.content[0].text).hazards[0].id).toEqual('test-block-hazard');
+
+  const doc = await client.callTool({
+    name: 'lowdefy_get_doc',
+    arguments: { kind: 'operator', type: '_get' },
+  });
+  expect(doc.content[0].text).toContain('## Hazards');
+  expect(doc.content[0].text).toContain(
+    '**get-fixture-hazard**: _get fixture hazard. (see `operators/_get`)'
+  );
+
+  const found = await client.callTool({
+    name: 'lowdefy_find_config',
+    arguments: { id: 'my_button' },
+  });
+  expect(JSON.parse(found.content[0].text).matches[0].hazards[0].id).toEqual(
+    'visible-false-prunes-state'
+  );
+  await client.close();
+});
+
 test('MCP tools/call lowdefy_build_status returns build status with client errors', async () => {
   const client = await connectClient();
   const result = await client.callTool({ name: 'lowdefy_build_status', arguments: {} });
@@ -125,7 +392,23 @@ test('MCP tools/call lowdefy_find_config locates a block by id', async () => {
   expect(parsed.kind).toEqual('page');
   expect(parsed.pageId).toEqual('home');
   expect(parsed.file).toEqual('pages/home.yaml');
-  expect(parsed.matches[0].location.source).toContain('pages/home.yaml');
+  expect(parsed.matches[0].location.source).toContain(path.join('pages', 'home.yaml'));
+  await client.close();
+});
+
+test('MCP tools/call lowdefy_restart writes the restart sentinel and tells the caller to poll', async () => {
+  const client = await connectClient();
+  const result = await client.callTool({
+    name: 'lowdefy_restart',
+    arguments: { reason: 'edited a request plugin' },
+  });
+  const body = JSON.parse(result.content[0].text);
+  expect(body.requested).toBe(true);
+  expect(body.reason).toBe('edited a request plugin');
+  expect(body.note).toContain('build-status');
+  const sentinelPath = path.join(fixtureDir, 'build', '.restart');
+  expect(JSON.parse(fs.readFileSync(sentinelPath, 'utf8')).reason).toBe('edited a request plugin');
+  fs.rmSync(sentinelPath, { force: true });
   await client.close();
 });
 
@@ -139,3 +422,360 @@ test('MCP tools/call with an unknown type returns isError with guidance', async
   expect(result.content[0].text).toContain('lowdefy_list_types');
   await client.close();
 });
+
+test('MCP lowdefy_get_schema returns the journey step grammar for kind journey-step without a type', async () => {
+  const client = await connectClient();
+  const { tools } = await client.listTools();
+  const getSchemaTool = tools.find((tool) => tool.name === 'lowdefy_get_schema');
+  expect(getSchemaTool.inputSchema.properties.kind.enum).toContain('journey-step');
+  expect(getSchemaTool.inputSchema.required).toEqual(['kind']);
+  const runJourneyTool = tools.find((tool) => tool.name === 'lowdefy_run_journey');
+  expect(runJourneyTool.inputSchema.properties.steps.description).toContain(
+    'lowdefy_get_schema with kind "journey-step"'
+  );
+
+  const all = await client.callTool({
+    name: 'lowdefy_get_schema',
+    arguments: { kind: 'journey-step' },
+  });
+  expect(all.isError).toBeUndefined();
+  expect(JSON.parse(all.content[0].text).schema.title).toEqual('Journey step');
+
+  const wait = await client.callTool({
+    name: 'lowdefy_get_schema',
+    arguments: { kind: 'journey-step', type: 'wait' },
+  });
+  expect(JSON.parse(wait.content[0].text)).toMatchObject({ kind: 'journey-step', type: 'wait' });
+
+  const noType = await client.callTool({
+    name: 'lowdefy_get_schema',
+    arguments: { kind: 'blocks' },
+  });
+  expect(noType.isError).toBe(true);
+  expect(noType.content[0].text).toContain('requires a "type"');
+  await client.close();
+});
+
+// The dev server keeps serving the previous build when a rebuild fails, so
+// every tool result must announce that its answer predates the caller's edits.
+test('MCP tools/call prepends a STALE notice while the last build failed', async () => {
+  const statusPath = path.join(fixtureDir, 'build', 'buildStatus.json');
+  const okStatus = fs.readFileSync(statusPath, 'utf8');
+  fs.writeFileSync(
+    statusPath,
+    JSON.stringify({
+      status: 'error',
+      timestamp: '2026-02-03T04:05:06.000Z',
+      errors: [{ message: 'Block type "Buton" not found.' }],
+      warnings: [],
+    })
+  );
+  try {
+    const client = await connectClient();
+    const result = await client.callTool({
+      name: 'lowdefy_get_schema',
+      arguments: { kind: 'blocks', type: 'Button' },
+    });
+    expect(result.content[0].text.startsWith('STALE: ')).toBe(true);
+    expect(result.content[0].text).toContain('"staleSince":"2026-02-03T04:05:06.000Z"');
+    // The tool's own payload is untouched, just no longer first.
+    const parsed = JSON.parse(result.content[1].text);
+    expect(parsed.schema.properties.title).toBeDefined();
+    await client.close();
+  } finally {
+    fs.writeFileSync(statusPath, okStatus);
+  }
+});
+
+test('MCP tools/call lowdefy_run_journey returns the JSON result followed by one image per screenshot', async () => {
+  mockRunJourney.mockResolvedValue({
+    pageId: 'form',
+    passed: false,
+    steps: [{ index: 0, step: { screenshot: 'before' }, status: 'ok', durationMs: 3 }],
+    failure: { index: 1, step: { click: 'nope' }, expected: 'x', actual: 'y', message: 'm' },
+    screenshots: [
+      { name: 'before', data: 'AAAA', mimeType: 'image/png' },
+      { name: 'after', data: 'BBBB', mimeType: 'image/png' },
+    ],
+    state: { saved: false },
+  });
+  const client = await connectClient();
+
+  const result = await client.callTool({
+    name: 'lowdefy_run_journey',
+    arguments: {
+      pageId: 'form',
+      steps: [{ screenshot: 'before' }, { click: 'nope' }],
+      user: { roles: ['admin'] },
+      urlQuery: { id: '1' },
+      state: ['saved'],
+    },
+  });
+
+  expect(mockRunJourney).toHaveBeenCalledWith({
+    origin: 'http://localhost:3000',
+    pageId: 'form',
+    steps: [{ screenshot: 'before' }, { click: 'nope' }],
+    user: { roles: ['admin'] },
+    urlQuery: { id: '1' },
+    state: ['saved'],
+    basePath: '',
+    recording: {
+      source: 'journey',
+      run: { id: expect.stringMatching(/^\d{8}T\d{6}Z-[a-z0-9]{6}$/), by: 'agent', journey: null },
+    },
+  });
+  expect(result.content).toHaveLength(3);
+  const summary = JSON.parse(result.content[0].text);
+  expect(summary.passed).toBe(false);
+  expect(summary.failure.index).toBe(1);
+  expect(summary.state).toEqual({ saved: false });
+  expect(summary.screenshots).toEqual([{ name: 'before' }, { name: 'after' }]);
+  expect(result.content[1]).toEqual({ type: 'image', data: 'AAAA', mimeType: 'image/png' });
+  expect(result.content[2]).toEqual({ type: 'image', data: 'BBBB', mimeType: 'image/png' });
+  await client.close();
+});
+
+test('MCP tools/call lowdefy_run_journey passes data and a data set user name through', async () => {
+  mockRunJourney.mockResolvedValue({
+    pageId: 'tickets',
+    passed: true,
+    steps: [],
+    screenshots: [],
+    data: { name: 'staging-sample', loadMs: 12, documents: 0 },
+    warnings: [],
+  });
+  const client = await connectClient();
+
+  const result = await client.callTool({
+    name: 'lowdefy_run_journey',
+    arguments: { pageId: 'tickets', steps: [], data: 'staging-sample', user: 'member' },
+  });
+
+  expect(mockRunJourney).toHaveBeenCalledWith(
+    expect.objectContaining({ pageId: 'tickets', data: 'staging-sample', user: 'member' })
+  );
+  expect(JSON.parse(result.content[0].text).data.name).toEqual('staging-sample');
+  await client.close();
+});
+
+test('MCP lowdefy_run_journey advertises data and the name form of user', async () => {
+  const client = await connectClient();
+  const { tools } = await client.listTools();
+  const { properties } = tools.find((tool) => tool.name === 'lowdefy_run_journey').inputSchema;
+  expect(properties.data.type).toEqual('string');
+  expect(properties.user.description).toMatch('the name of a user in the journey');
+  await client.close();
+});
+
+test('MCP tools/call lowdefy_run_journey runs a list of users once each and reports every run', async () => {
+  mockRunJourney.mockImplementation(async ({ user }) => ({
+    pageId: 'tickets',
+    passed: user === 'admin',
+    steps: [],
+    screenshots: [{ name: 'end', data: user === 'admin' ? 'AAAA' : 'BBBB', mimeType: 'image/png' }],
+    ...(user === 'admin'
+      ? {}
+      : { failure: { index: 0, step: { click: 'edit' }, message: 'edit is hidden' } }),
+  }));
+  const client = await connectClient();
+
+  const result = await client.callTool({
+    name: 'lowdefy_run_journey',
+    arguments: { pageId: 'tickets', steps: [], data: 'crm', user: ['admin', 'member'] },
+  });
+
+  expect(mockRunJourney).toHaveBeenCalledTimes(2);
+  expect(mockRunJourney.mock.calls.map(([params]) => params.user)).toEqual(['admin', 'member']);
+  expect(mockRunJourney.mock.calls[0][0]).toEqual(
+    expect.objectContaining({ pageId: 'tickets', data: 'crm' })
+  );
+  const [first, second] = mockRunJourney.mock.calls.map(([params]) => params.recording.run.id);
+  expect(first).not.toEqual(second);
+  const summary = JSON.parse(result.content[0].text);
+  expect(summary.passed).toBe(false);
+  expect(summary.runs.map(({ user, passed }) => ({ user, passed }))).toEqual([
+    { user: 'admin', passed: true },
+    { user: 'member', passed: false },
+  ]);
+  expect(summary.runs[1].failure.message).toBe('edit is hidden');
+  expect(summary.runs[0].screenshots).toEqual([{ name: 'end' }]);
+  expect(result.content.slice(1)).toEqual([
+    { type: 'image', data: 'AAAA', mimeType: 'image/png' },
+    { type: 'image', data: 'BBBB', mimeType: 'image/png' },
+  ]);
+  await client.close();
+});
+
+test('MCP tools/call lowdefy_run_journey reports a run the runner could not do in its run', async () => {
+  mockRunJourney.mockImplementation(async ({ user }) =>
+    user === 'ghost'
+      ? { error: 'Data set "crm" declares no user "ghost".', refused: true }
+      : { pageId: 'tickets', passed: true, steps: [], screenshots: [] }
+  );
+  const client = await connectClient();
+
+  const result = await client.callTool({
+    name: 'lowdefy_run_journey',
+    arguments: { pageId: 'tickets', steps: [], data: 'crm', user: ['admin', 'ghost'] },
+  });
+
+  const summary = JSON.parse(result.content[0].text);
+  expect(summary.passed).toBe(false);
+  expect(summary.runs[1]).toEqual({
+    user: 'ghost',
+    passed: false,
+    error: 'Data set "crm" declares no user "ghost".',
+    screenshots: [],
+  });
+  await client.close();
+});
+
+test.each([
+  [['admin'], undefined, 'declares no "data"'],
+  [['admin', 'admin'], 'crm', 'names "admin" more than once'],
+  [['none'], 'crm', 'Received "none".'],
+])(
+  'MCP tools/call lowdefy_run_journey refuses user list %j with data %j before running',
+  async (user, data, message) => {
+    const client = await connectClient();
+
+    const result = await client.callTool({
+      name: 'lowdefy_run_journey',
+      arguments: { pageId: 'tickets', steps: [], data, user },
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain(message);
+    expect(mockRunJourney).not.toHaveBeenCalled();
+    await client.close();
+  }
+);
+
+test('MCP tools/call lowdefy_run_journey reports a runner error as a tool error', async () => {
+  mockRunJourney.mockResolvedValue({ error: 'Step 0: Unknown journey step "hover".' });
+  const client = await connectClient();
+
+  const result = await client.callTool({
+    name: 'lowdefy_run_journey',
+    arguments: { pageId: 'form', steps: [{ hover: 'a' }] },
+  });
+
+  expect(result.isError).toBe(true);
+  expect(result.content[0].text).toEqual('Step 0: Unknown journey step "hover".');
+  await client.close();
+});
+
+test('MCP instructions teach lowdefy_run_journey as the way to verify behaviour', async () => {
+  const client = await connectClient();
+  const instructions = client.getInstructions();
+  expect(instructions).toContain('lowdefy_run_journey');
+  expect(instructions).toContain('verify behaviour');
+  await client.close();
+});
+
+function writeDevSession({ configDirectory, id, records }) {
+  const directory = path.join(configDirectory, '.lowdefy', 'traces', 'dev', '2026-10-06');
+  fs.mkdirSync(directory, { recursive: true });
+  fs.writeFileSync(
+    path.join(directory, `${id}.jsonl`),
+    records.map((record) => JSON.stringify(record)).join('\n')
+  );
+}
+
+function devRecord({ id, t, kind, page, ...rest }) {
+  return {
+    v: 1,
+    source: 'dev',
+    session: id,
+    t,
+    scope: 'page',
+    kind,
+    page_id: page,
+    roles: [],
+    person: null,
+    org: null,
+    build: null,
+    target: null,
+    event: null,
+    ...rest,
+  };
+}
+
+test('MCP tools/call lowdefy_journey_session lists dev sessions and prints one as a log', async () => {
+  const configDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-mcp-session-'));
+  const previous = process.env.LOWDEFY_DIRECTORY_CONFIG;
+  process.env.LOWDEFY_DIRECTORY_CONFIG = configDirectory;
+  const id = '20261006T100000Z-abcdef';
+  writeDevSession({
+    configDirectory,
+    id,
+    records: [
+      devRecord({
+        id,
+        t: '2026-10-06T10:00:00.000Z',
+        kind: 'pageview',
+        page: 'tickets',
+        url: '/tickets',
+      }),
+      devRecord({
+        id,
+        t: '2026-10-06T10:00:02.000Z',
+        kind: 'click',
+        page: 'tickets',
+        target: {
+          block_id: 'sync',
+          block_type: 'Button',
+          row: null,
+          column: null,
+          text: null,
+          nth: null,
+          option: false,
+        },
+        event: {
+          name: 'onClick',
+          block_id: 'sync',
+          success: true,
+          actions: ['CallAPI'],
+          requests: [],
+          endpoints: [{ id: 'syncTickets', ok: true, ms: 10 }],
+          state_writes: [],
+          url_after: '/tickets',
+        },
+      }),
+    ],
+  });
+  try {
+    const client = await connectClient();
+    const list = await client.callTool({ name: 'lowdefy_journey_session', arguments: {} });
+    expect(list.isError).toBeUndefined();
+    expect(list.content[0].text).toContain(`${id}   `);
+    expect(list.content[0].text).toContain('tickets   1 interaction');
+
+    const log = await client.callTool({ name: 'lowdefy_journey_session', arguments: { id } });
+    expect(log.content[0].text).toBe(
+      [
+        `Session ${id}, 2026-10-06T10:00:00.000Z to 2026-10-06T10:00:02.000Z:`,
+        'page tickets',
+        'click sync → endpoint syncTickets ok',
+      ].join('\n')
+    );
+
+    const unknown = await client.callTool({
+      name: 'lowdefy_journey_session',
+      arguments: { id: 'missing' },
+    });
+    expect(unknown.isError).toBe(true);
+    expect(unknown.content[0].text).toBe(
+      `No session "missing" in this window. The newest sessions are ${id}.`
+    );
+    await client.close();
+  } finally {
+    if (previous === undefined) {
+      delete process.env.LOWDEFY_DIRECTORY_CONFIG;
+    } else {
+      process.env.LOWDEFY_DIRECTORY_CONFIG = previous;
+    }
+    fs.rmSync(configDirectory, { recursive: true, force: true });
+  }
+});