@lowdefy/server-dev 0.0.0-experimental-20261007090522 → 0.0.0-experimental-20261007124348

package/lib/docs/createDocsMcpServer.js

@@ -129,8 +129,8 @@ function createDocsMcpServer({ origin, honoContext, version } = {}) {
     });
   }
 
-  registerDevTool('lowdefy_inspect_state', async ({ pageId, pathParams, source, user }) => {
-    const result = await inspectState({ origin, pageId, pathParams, source, user });
+  registerDevTool('lowdefy_inspect_state', async ({ pageId, pathParams, source, user, data }) => {
+    const result = await inspectState({ origin, pageId, pathParams, source, user, data });
     if (result.error) {
       return notFoundResult(result.error);
     }
@@ -139,8 +139,16 @@ function createDocsMcpServer({ origin, honoContext, version } = {}) {
 
   registerDevTool(
     'lowdefy_eval_operator',
-    async ({ pageId, pathParams, expression, source, user }) => {
-      const result = await evalOperator({ origin, pageId, pathParams, expression, source, user });
+    async ({ pageId, pathParams, expression, source, user, data }) => {
+      const result = await evalOperator({
+        origin,
+        pageId,
+        pathParams,
+        expression,
+        source,
+        user,
+        data,
+      });
       if (result.error) {
         return notFoundResult(result.error);
       }
@@ -150,15 +158,17 @@ function createDocsMcpServer({ origin, honoContext, version } = {}) {
 
   registerDevTool(
     'lowdefy_run_request',
-    async ({ pageId, requestId, payload, user, saveResponse }) =>
-      textResult(await runRequest({ pageId, requestId, payload, user, saveResponse, honoContext }))
+    async ({ pageId, requestId, payload, user, data, saveResponse }) =>
+      textResult(
+        await runRequest({ pageId, requestId, payload, user, data, saveResponse, honoContext })
+      )
   );
 
   registerDevTool(
     'lowdefy_run_endpoint',
-    async ({ endpointId, payload, user, system, saveResponse }) =>
+    async ({ endpointId, payload, user, data, system, saveResponse }) =>
       textResult(
-        await runEndpoint({ endpointId, payload, user, system, saveResponse, honoContext })
+        await runEndpoint({ endpointId, payload, user, data, system, saveResponse, honoContext })
       )
   );
 
@@ -190,8 +200,8 @@ function createDocsMcpServer({ origin, honoContext, version } = {}) {
     }
   );
 
-  registerDevTool('lowdefy_load_state', async ({ name, mode, user }) => {
-    const result = await loadState({ origin, name, mode, user });
+  registerDevTool('lowdefy_load_state', async ({ name, mode, user, data }) => {
+    const result = await loadState({ origin, name, mode, user, data });
     if (result.error) {
       return notFoundResult(result.error);
     }
@@ -257,6 +267,7 @@ function createDocsMcpServer({ origin, honoContext, version } = {}) {
       scrollX,
       scrollY,
       user,
+      data,
       width,
       height,
       colorScheme,
@@ -275,6 +286,7 @@ function createDocsMcpServer({ origin, honoContext, version } = {}) {
         scrollX,
         scrollY,
         user,
+        data,
         width,
         height,
         colorScheme,

package/lib/docs/createDocsMcpServer.test.mjs

@@ -197,6 +197,48 @@ 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();
@@ -381,6 +423,39 @@ test('MCP tools/call with an unknown type returns isError with guidance', async
   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 () => {

package/lib/docs/dataSets/resolveJourneyDataSet.js

@@ -43,9 +43,13 @@ function describeDeclaredUsers({ users }) {
 //   which is bound to the real auth database while its requests read the data set;
 // - any data-set journey while a dev mock user is active: the mock user wins over the injected
 //   caller, so the journey would silently act as someone outside the data set.
+//
+// `subject` names the run in the refusals: "journey" for a journey, "call" for the other dev tools
+// that act as someone (resolveToolCaller), which take the same user and data.
 async function resolveJourneyDataSet({
   data,
   user,
+  subject = 'journey',
   configDirectory,
   buildDirectory,
   authConfigured,
@@ -54,31 +58,30 @@ async function resolveJourneyDataSet({
   if (type.isNone(data)) {
     if (user === 'none' && mockUserActive) {
       return {
-        error:
-          'The journey has user "none", which cannot run while a dev mock user is active (auth.dev.mockUser or LOWDEFY_DEV_USER): with no caller of its own, every request would act as the mock user, not signed out. Remove the mock user to run journeys signed out, or give the journey a user.',
+        error: `The ${subject} has user "none", which cannot run while a dev mock user is active (auth.dev.mockUser or LOWDEFY_DEV_USER): with no caller of its own, every request would act as the mock user, not signed out. Remove the mock user to run signed out, or give the ${subject} a user.`,
       };
     }
     if (isUserName(user)) {
       return {
-        error: `The journey's user ${JSON.stringify(
+        error: `The ${subject}'s user ${JSON.stringify(
           user
-        )} names a data set user, but the journey has no "data". Add data: <data set name>, or give user as an object.`,
+        )} names a data set user, but the ${subject} has no "data". Add data: <data set name>, or give user as an object.`,
       };
     }
     return { user };
   }
   if (mockUserActive) {
     return {
-      error: `The journey on data set ${JSON.stringify(
+      error: `The ${subject} on data set ${JSON.stringify(
         data
-      )} cannot run while a dev mock user is active (auth.dev.mockUser or LOWDEFY_DEV_USER): every request would act as the mock user, who is not in the data set. Remove the mock user to run journeys on data sets.`,
+      )} cannot run while a dev mock user is active (auth.dev.mockUser or LOWDEFY_DEV_USER): every request would act as the mock user, who is not in the data set. Remove the mock user to run on data sets.`,
     };
   }
   if (user === 'none' && authConfigured) {
     return {
-      error: `The journey on data set ${JSON.stringify(
+      error: `The ${subject} on data set ${JSON.stringify(
         data
-      )} has user "none", which is refused while auth is configured: signing in through the app would write to the app's real auth database. Name a data set user instead; journeys that sign in stay off data sets.`,
+      )} has user "none", which is refused while auth is configured: signing in through the app would write to the app's real auth database. Name a data set user instead; runs that sign in stay off data sets.`,
     };
   }
   let dataSet;

package/lib/docs/devToolDefinitions.js

@@ -37,7 +37,7 @@ Live state: lowdefy_inspect_state reads the ACTUAL state, request results, and e
 
 Behaviour, not just layout: a screenshot shows what rendered, not what works. To verify behaviour, drive the page with lowdefy_run_journey — a declarative list of steps (click, fill, select, press, back, goto, email, as, wait, screenshot, expect) addressed by blockId — and assert on state, visibility, text, url or title. A failing step stops the journey and comes back as data (passed: false, failure with expected/actual, the remaining steps skipped) together with the final page state, so you can read what the app actually did and write the next assertion. A large final state comes back as a summary of its keys; pass state with the paths you need. Pass user to act as a real member (e.g. {"roles":["admin"]}) when the flow is role-gated, or user "none" to test auth itself (sign-up, sign-in, invitations) through the app's own pages and sessions.
 
-Role-gated pages: the headless renderer signs in as a roleless user, so a page or request gated on a role renders empty or refused. Pass user to lowdefy_screenshot_page, lowdefy_run_journey, lowdefy_inspect_state, lowdefy_eval_operator, lowdefy_load_state, lowdefy_run_request or lowdefy_run_endpoint to act as a specific caller — e.g. user {"roles":["admin"]} — and vary it per call to compare what different roles see. A request run without user runs as a roleless anonymous caller, so a tenant-walled or role-gated request returns empty rather than an error.
+Role-gated pages: the headless renderer signs in as a roleless user, so a page or request gated on a role renders empty or refused. Pass user to lowdefy_screenshot_page, lowdefy_run_journey, lowdefy_inspect_state, lowdefy_eval_operator, lowdefy_load_state, lowdefy_run_request or lowdefy_run_endpoint to act as a specific caller, in the same forms on every one: a user object (e.g. {"roles":["admin"]}), "none" to act signed out, or the name of a data set user together with data (e.g. user "member", data "crm"), which runs the call on that data set's own database. Vary it per call to compare what different roles see. A request run without user runs as a roleless anonymous caller, so a tenant-walled or role-gated request returns empty rather than an error.
 
 Safety: lowdefy_checkpoint snapshots the config files before risky multi-file changes; lowdefy_revert_checkpoint restores them.
 
@@ -48,15 +48,27 @@ State checkpoints (testing): lowdefy_snapshot_state captures a page's live state
 const HAZARDS_NOTE =
   ' Results include `hazards`: behaviours of this type that its schema does not show. Read them before writing config.';
 
-// Shared by every tool that renders a page headless, so one call can act as an
-// admin and the next as a plain member — each headless call gets its own browser
-// context, so they never share an identity.
+// One sentence, shared by the description of every tool that acts as someone,
+// so the caller option reads the same wherever an agent meets it.
+const CALLER_NOTE =
+  ' 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 (tests/data/<name>.yaml), which also runs the call on that data set\'s own database.';
+
+// Shared by every tool that acts as someone, in the forms a journey takes, so
+// one call can act as an admin and the next as a plain member - each headless
+// call gets its own browser context, so they never share an identity.
 const userSchema = z
-  .object({})
-  .passthrough()
+  .union([z.literal('none'), z.string().min(1), z.object({}).passthrough()])
+  .optional()
+  .describe(
+    'Who the call acts as. Omitted: the default roleless headless user. An object: that injected caller, e.g. {"roles":["user-admin"]}, merged over the default, so include email/profile/attributes fields too if the page reads them; no auth engine runs for an injected caller, so nothing derives them. "none": no injected caller, so the app\'s own auth decides and the call runs signed out. Any other string: the name of a user in the data set named by data, e.g. "member". Headless only: it is never applied to a page the developer opens in their own browser, so combining it with source "tab" or load_state mode "registry-only" is an error rather than a silently dropped role.'
+  );
+
+// Shared by every tool that takes userSchema.
+const dataSchema = z
+  .string()
   .optional()
   .describe(
-    'Act as this caller instead of the default roleless headless user, e.g. {"roles":["user-admin"]} to render a role-gated page. Merged over the default, so include email/profile/attributes fields too if the page reads them — no auth engine runs for an injected caller, so nothing derives them. Headless only: it is never applied to a page the developer opens in their own browser, so combining it with source "tab" or load_state mode "registry-only" is an error rather than a silently dropped role, and on lowdefy_run_request / lowdefy_run_endpoint it sets the caller the request or routine runs as.'
+    'The name of a data set in tests/data/<name>.yaml. The call then runs against a fresh in-memory database of its own, loaded with the data set, as a journey with data does, and user can name one of its users. Headless only, like user.'
   );
 
 // Shared by every tool that names a page instance: a page whose `path` has
@@ -79,7 +91,8 @@ const saveResponseSchema = z
 const devToolDefinitions = {
   lowdefy_inspect_state: {
     description:
-      "Read the LIVE state of a running page: state, request results, event log (recent actions fired), global, user, input, and urlQuery. If the developer has the page open in a browser it reads their actual tab (ask them to interact first, then inspect); otherwise it runs the page headless. Use this to see what the app's data model really looks like.",
+      "Read the LIVE state of a running page: state, request results, event log (recent actions fired), global, user, input, and urlQuery. If the developer has the page open in a browser it reads their actual tab (ask them to interact first, then inspect); otherwise it runs the page headless. Use this to see what the app's data model really looks like." +
+      CALLER_NOTE,
     inputSchema: {
       pageId: z.string().describe('The page id to inspect.'),
       pathParams: pathParamsSchema.describe(
@@ -90,12 +103,14 @@ const devToolDefinitions = {
         .optional()
         .describe('Force a source. Default: live tab if connected, else headless.'),
       user: userSchema,
+      data: dataSchema,
     },
   },
 
   lowdefy_eval_operator: {
     description:
-      'Evaluate a Lowdefy operator expression against the live state of a running page — a REPL for config. Pass the operator object in the "expression" argument — any JSON value, e.g. {"_state": "customer.name"} or {"_if": {...}}. Evaluates in the real browser runtime (live tab if connected, else headless).',
+      'Evaluate a Lowdefy operator expression against the live state of a running page — a REPL for config. Pass the operator object in the "expression" argument — any JSON value, e.g. {"_state": "customer.name"} or {"_if": {...}}. Evaluates in the real browser runtime (live tab if connected, else headless).' +
+      CALLER_NOTE,
     inputSchema: {
       pageId: z.string().describe('The page id whose context to evaluate against.'),
       pathParams: pathParamsSchema.describe(
@@ -106,28 +121,33 @@ const devToolDefinitions = {
         .describe('The operator expression — any JSON value, e.g. {"_state": "key"}.'),
       source: z.enum(['tab', 'headless']).optional(),
       user: userSchema,
+      data: dataSchema,
     },
   },
 
   lowdefy_run_request: {
     description:
-      'Execute a request in dev with a test payload to verify the data shape a page receives. The page is built first when it changed since its last build, so the request that runs is the one in the config now; a page that fails to build is refused with its build errors. Read-only request types always run; write requests are refused unless the app opts in (cli.agentTools.allowWriteRequests in lowdefy.yaml). A response too large to return inline is written in full to responseFile.',
+      'Execute a request in dev with a test payload to verify the data shape a page receives. The page is built first when it changed since its last build, so the request that runs is the one in the config now; a page that fails to build is refused with its build errors. Read-only request types always run; write requests are refused unless the app opts in (cli.agentTools.allowWriteRequests in lowdefy.yaml). A response too large to return inline is written in full to responseFile.' +
+      CALLER_NOTE,
     inputSchema: {
       pageId: z.string().describe('The page the request is defined on.'),
       requestId: z.string().describe('The request id.'),
       payload: z.record(z.any()).optional().describe('Test payload for _payload operators.'),
       user: userSchema,
+      data: dataSchema,
       saveResponse: saveResponseSchema,
     },
   },
 
   lowdefy_run_endpoint: {
     description:
-      'Execute an Api endpoint routine in dev with a test payload and caller, to verify what it returns, rejects or throws. Requires agent write access (cli.agentTools.allowWriteRequests) because routines are not classified read-only. A :reject or :throw comes back as data (success: false, status "reject"/"error" with the routine\'s own error), not as a tool failure. Pass system: true to run it as a system context the way a cron or detached run does — no user (_user undefined), endpoint auth not checked, InternalApi endpoints allowed — which is the local test path for scheduled (schedules) and detached-only routines. Nested CallApi steps with detached: true still dispatch over HTTP and need CRON_SECRET set on the dev server; they are not faked.',
+      'Execute an Api endpoint routine in dev with a test payload and caller, to verify what it returns, rejects or throws. Requires agent write access (cli.agentTools.allowWriteRequests) because routines are not classified read-only. A :reject or :throw comes back as data (success: false, status "reject"/"error" with the routine\'s own error), not as a tool failure. Pass system: true to run it as a system context the way a cron or detached run does — no user (_user undefined), endpoint auth not checked, InternalApi endpoints allowed — which is the local test path for scheduled (schedules) and detached-only routines. Nested CallApi steps with detached: true still dispatch over HTTP and need CRON_SECRET set on the dev server; they are not faked.' +
+      CALLER_NOTE,
     inputSchema: {
       endpointId: z.string().describe('The Api endpoint id.'),
       payload: z.record(z.any()).optional().describe('Test payload for _payload operators.'),
       user: userSchema,
+      data: dataSchema,
       system: z
         .boolean()
         .optional()
@@ -169,11 +189,13 @@ const devToolDefinitions = {
 
   lowdefy_load_state: {
     description:
-      "Put the app back into a saved state checkpoint. mode 'headless' (default) verifies the restored state itself; mode 'registry-only' loads the recorded request data into the dev server and returns a ?_checkpoint URL the developer can open to manually test the app in that exact state.",
+      "Put the app back into a saved state checkpoint. mode 'headless' (default) verifies the restored state itself; mode 'registry-only' loads the recorded request data into the dev server and returns a ?_checkpoint URL the developer can open to manually test the app in that exact state." +
+      CALLER_NOTE,
     inputSchema: {
       name: z.string().describe('The checkpoint name.'),
       mode: z.enum(['headless', 'registry-only']).optional(),
       user: userSchema,
+      data: dataSchema,
     },
   },
 
@@ -250,7 +272,8 @@ const devToolDefinitions = {
 
   lowdefy_screenshot_page: {
     description:
-      'Screenshot a page of the running dev server (headless Chromium) to visually verify layout and rendering. Returns a PNG image. Set width (and height) to check a narrow or phone layout, e.g. width 390, and colorScheme "dark" to check dark mode. To capture a state beyond the page as it loads — an OPEN Selector / MultipleSelector / AutoComplete / DateSelector (calendar) / Cascader / TreeSelector dropdown, a modal a button opens — pass steps, e.g. [{"open": "status"}]: they run after the page settles and before the capture. Popups antd renders in a portal are included, also with fullPage. Pass urlQuery for a page that reads _url_query, and pathParams for a page whose path has placeholders.',
+      'Screenshot a page of the running dev server (headless Chromium) to visually verify layout and rendering. Returns a PNG image. Set width (and height) to check a narrow or phone layout, e.g. width 390, and colorScheme "dark" to check dark mode. To capture a state beyond the page as it loads — an OPEN Selector / MultipleSelector / AutoComplete / DateSelector (calendar) / Cascader / TreeSelector dropdown, a modal a button opens — pass steps, e.g. [{"open": "status"}]: they run after the page settles and before the capture. Popups antd renders in a portal are included, also with fullPage. Pass urlQuery for a page that reads _url_query, and pathParams for a page whose path has placeholders.' +
+      CALLER_NOTE,
     inputSchema: {
       pageId: z.string().describe('The page id to screenshot.'),
       pathParams: pathParamsSchema,
@@ -305,18 +328,20 @@ const devToolDefinitions = {
           'The colour scheme the page\'s prefers-color-scheme reports. Default "light". An app that follows the system theme renders dark with "dark"; a darkMode fixed in the app config wins.'
         ),
       user: userSchema,
+      data: dataSchema,
     },
   },
 
   lowdefy_run_journey: {
     description:
-      'Drive a page of the running dev server headless through declarative steps and assert what happens — the way to verify behaviour (a form submits, a modal opens, a filter works), not just layout. Blocks are addressed by blockId; a target object narrows to a grid row/cell ({"blockId": "grid", "row": 1, "column": "actions"}), to the control with exactly some text ({"blockId": "grid", "row": 1, "text": "Edit"}), or reaches portal-rendered controls page-wide by text alone ({"text": "OK"} for a confirm dialog or modal footer button, a menu item). A step that fails stops the journey and is returned as data (passed: false, failure with index/step/expected/actual/message, later steps "skipped") — never as a tool error. A journey also fails at the step that causes an app error its own browsers raised (an action failing with an error that is not a user error, an uncaught page error, a server error or 5xx from a request or endpoint): failure.kind "app-error" with errors [{kind, message, source, configKey, key}], or phase "open" when opening the page raised it. A failed Validate, a Throw action and 401/403 refusals never count. Where an error is the intended outcome, {"expect": {"error": text}} straight after the interaction claims its errors whose message contains text. Returns the final page state (whole when small, otherwise stateOmitted with its size and top-level keys; see the state param) and any screenshots taken (as images after the JSON text).',
+      'Drive a page of the running dev server headless through declarative steps and assert what happens — the way to verify behaviour (a form submits, a modal opens, a filter works), not just layout. Blocks are addressed by blockId; a target object narrows to a grid row/cell ({"blockId": "grid", "row": 1, "column": "actions"}), to the control with exactly some text ({"blockId": "grid", "row": 1, "text": "Edit"}), or reaches portal-rendered controls page-wide by text alone ({"text": "OK"} for a confirm dialog or modal footer button, a menu item). A step that fails stops the journey and is returned as data (passed: false, failure with index/step/expected/actual/message, later steps "skipped") — never as a tool error. A journey also fails at the step that causes an app error its own browsers raised (an action failing with an error that is not a user error, an uncaught page error, a server error or 5xx from a request or endpoint): failure.kind "app-error" with errors [{kind, message, source, configKey, key}], or phase "open" when opening the page raised it. A failed Validate, a Throw action and 401/403 refusals never count. Where an error is the intended outcome, {"expect": {"error": text}} straight after the interaction claims its errors whose message contains text. Returns the final page state (whole when small, otherwise stateOmitted with its size and top-level keys; see the state param) and any screenshots taken (as images after the JSON text).' +
+      CALLER_NOTE,
     inputSchema: {
       pageId: z.string().describe('The page id to open.'),
       steps: z
         .array(z.record(z.any()))
         .describe(
-          'Ordered steps, one key each: {"click": target} (a target object may add "count": 2 or 3 for that many clicks in quick succession, a double click, before the runner settles) | {"open": target} (open an input\'s dropdown or picker popup - Selector, MultipleSelector, AutoComplete, DateSelector, Cascader... - and wait for it to show, so a following screenshot step captures it) | {"fill": {...target, "value"}} | {"fill": {...target, "fromEmail": {"to", "subject"?, "match"}}} (type text read from the newest email to that address, like the email step, without leaving the page: the first match of the regular expression "match", or its first capture group, e.g. "\\\\b\\\\d{6}\\\\b" for a one-time sign-in code) | {"select": {...target, "value"}} (option by exact text: a dropdown option, or a radio, button or segmented option in the block) | {"press": "Enter" | "Mod+k"} (Mod is Meta/Control per platform) | {"back": true} (the browser Back button) | {"goto": pageId | {"pageId", "pathParams", "urlQuery"}} (load an app page like a typed URL, its path built from pathParams, one string per placeholder of the page\'s path; a protected page may redirect to sign-in) | {"email": {"to", "subject"?}} (open the newest email to that address, subject containing the text, that arrived during this journey, waiting for it if needed; opening it again opens the same message; then click its links by text, e.g. {"click": {"text": "Verify email address"}}; needs the dev server started with LOWDEFY_DEV_SMTP_PORT and the app\'s SMTP connection pointed at 127.0.0.1 on that port) | {"as": name} (switch to another person, each with their own browser and cookies; the journey starts as "main", and a new name opens the journey\'s page) | {"wait": {"ms": n} | {"request": requestId} (a call started since the last interaction, or since the page opened, has finished) | {"state": path}} | {"screenshot": name?} | {"expect": {"state": {"path", "equals"}} | {"visible": target} | {"hidden": target} (nothing the target names is visible; passes at once when nothing matches yet, so pair it with something that must be present first) | {"text": {...target, "contains"}} | {"url": {"contains"}} | {"title": {"equals"} | {"contains"}} | {"calls": {"request", "pageId"?, "count"} | {"endpoint", "count"}} | {"error": text} | {"effect": true}} (title is the document title; calls compares, once the page settles, how many times this actor called the request - on pageId, default the current page - or the endpoint since the journey started; error must directly follow an interaction step and claims the app errors it raised whose message contains text, with the failed action that reported them; effect must directly follow an interaction step and fails when that interaction did nothing: no event ran, the page did not change, no request or endpoint was called and the URL stayed the same, which proves a dead click). A target is a blockId string, or an object of {"blockId", "row" (zero-based grid row as displayed), "column" (grid col-id), "text" (exact text of the interactive control to use), "containing" (text the element shows, e.g. the email a list row shows; a click on it reaches the row\'s click handler), "nth" (zero-based pick among several matches; a click, open, fill or select whose text or containing matches more than one visible element fails without it)}; "text" without "blockId" searches the whole page, which is how confirm dialog / modal footer buttons, dropdown menu items and email links are reached. fill, select and expect.text need a blockId. Every blockId, requestId, endpoint and goto pageId a step names is checked against the build before it runs (and an "as" name against the data set\'s users on a data set run): an unknown one fails the step and names it. fill, select and expect.state take an optional "from": "recorded" (the value came from a recorded trace) or "shape" (value: null, a placeholder a trace could not hold); a journey holding a from: shape placeholder is refused until it is filled in. Each step gets 5s, or the journey\'s timeout: every wait for something to happen (a control to be actionable, an expect to match, a request, state or email to arrive) is bounded by it; page opens get at least 15s; after an interaction the runner waits at most 5s for the page\'s pending events and requests to settle, without failing; wait.ms is exact.'
+          'Ordered steps, one key each: {"click": target} (a target object may add "count": 2 or 3 for that many clicks in quick succession, a double click, before the runner settles) | {"open": target} (open an input\'s dropdown or picker popup - Selector, MultipleSelector, AutoComplete, DateSelector, Cascader... - and wait for it to show, so a following screenshot step captures it) | {"fill": {...target, "value"}} | {"fill": {...target, "fromEmail": {"to", "subject"?, "match"}}} (type text read from the newest email to that address, like the email step, without leaving the page: the first match of the regular expression "match", or its first capture group, e.g. "\\\\b\\\\d{6}\\\\b" for a one-time sign-in code) | {"select": {...target, "value"}} (option by exact text: a dropdown option, or a radio, button or segmented option in the block) | {"press": "Enter" | "Mod+k"} (Mod is Meta/Control per platform) | {"back": true} (the browser Back button) | {"goto": pageId | {"pageId", "pathParams", "urlQuery"}} (load an app page like a typed URL, its path built from pathParams, one string per placeholder of the page\'s path; a protected page may redirect to sign-in) | {"email": {"to", "subject"?}} (open the newest email to that address, subject containing the text, that arrived during this journey, waiting for it if needed; opening it again opens the same message; then click its links by text, e.g. {"click": {"text": "Verify email address"}}; needs the dev server started with LOWDEFY_DEV_SMTP_PORT and the app\'s SMTP connection pointed at 127.0.0.1 on that port) | {"as": name} (switch to another person, each with their own browser and cookies; the journey starts as "main", and a new name opens the journey\'s page) | {"wait": {"ms": n} | {"request": requestId} (a call started since the last interaction, or since the page opened, has finished) | {"state": path}} | {"screenshot": name?} | {"expect": {"state": {"path", "equals"}} | {"visible": target} | {"hidden": target} (nothing the target names is visible; passes at once when nothing matches yet, so pair it with something that must be present first) | {"text": {...target, "contains"}} | {"url": {"contains"}} | {"title": {"equals"} | {"contains"}} | {"calls": {"request", "pageId"?, "count"} | {"endpoint", "count"}} | {"error": text} | {"effect": true}} (title is the document title; calls compares, once the page settles, how many times this actor called the request - on pageId, default the current page - or the endpoint since the journey started; error must directly follow an interaction step and claims the app errors it raised whose message contains text, with the failed action that reported them; effect must directly follow an interaction step and fails when that interaction did nothing: no event ran, the page did not change, no request or endpoint was called and the URL stayed the same, which proves a dead click). A target is a blockId string, or an object of {"blockId", "row" (zero-based grid row as displayed), "column" (grid col-id), "text" (exact text of the interactive control to use), "containing" (text the element shows, e.g. the email a list row shows; a click on it reaches the row\'s click handler), "nth" (zero-based pick among several matches; a click, open, fill or select whose text or containing matches more than one visible element fails without it)}; "text" without "blockId" searches the whole page, which is how confirm dialog / modal footer buttons, dropdown menu items and email links are reached. fill, select and expect.text need a blockId. Every blockId, requestId, endpoint and goto pageId a step names is checked against the build before it runs (and an "as" name against the data set\'s users on a data set run): an unknown one fails the step and names it. fill, select and expect.state take an optional "from": "recorded" (the value came from a recorded trace) or "shape" (value: null, a placeholder a trace could not hold); a journey holding a from: shape placeholder is refused until it is filled in. Each step gets 5s, or the journey\'s timeout: every wait for something to happen (a control to be actionable, an expect to match, a request, state or email to arrive) is bounded by it; page opens get at least 15s; after an interaction the runner waits at most 5s for the page\'s pending events and requests to settle, without failing; wait.ms is exact. lowdefy_get_schema with kind "journey-step" returns this grammar as a JSON schema, with examples of every step.'
         ),
       user: z
         .union([
@@ -409,9 +434,16 @@ const devToolDefinitions = {
       HAZARDS_NOTE,
     inputSchema: {
       kind: z
-        .enum(['blocks', 'operators', 'actions', 'connections', 'requests'])
-        .describe('The kind of the type.'),
-      type: z.string().describe('The exact type name, e.g. "Button", "_get", "MongoDBFind".'),
+        .enum(['blocks', 'operators', 'actions', 'connections', 'requests', 'journey-step'])
+        .describe(
+          'The kind of the type. "journey-step" returns the lowdefy_run_journey step grammar, with examples of every step.'
+        ),
+      type: z
+        .string()
+        .optional()
+        .describe(
+          'The exact type name, e.g. "Button", "_get", "MongoDBFind". Required, except for kind "journey-step", where it names one step (e.g. "wait") and is omitted for every step.'
+        ),
     },
   },
 

package/lib/docs/docs.test.mjs

@@ -158,6 +158,29 @@ test('getSchema returns null for unknown type', () => {
 
 test('getSchema throws for kinds without schemas', () => {
   expect(() => getSchema({ kind: 'websockets', type: 'X' })).toThrow('No schemas available');
+  expect(() => getSchema({ kind: 'tool', type: 'run_journey' })).toThrow(
+    'or journey-step for the journey step grammar'
+  );
+});
+
+test('getSchema throws when a type kind is given no type', () => {
+  expect(() => getSchema({ kind: 'blocks' })).toThrow(
+    'Getting a blocks schema requires a "type", the exact type name. Received undefined.'
+  );
+});
+
+test('getSchema returns the journey step grammar for kind journey-step', () => {
+  const result = getSchema({ kind: 'journey-step' });
+  expect(result.kind).toEqual('journey-step');
+  expect(result.schema.title).toEqual('Journey step');
+  expect(result.schema.oneOf.map((step) => step.required[0])).toContain('wait');
+});
+
+test('getSchema returns one journey step schema when type names the step', () => {
+  const result = getSchema({ kind: 'journey-step', type: 'wait' });
+  expect(result).toMatchObject({ kind: 'journey-step', type: 'wait' });
+  expect(result.schema.properties.wait.examples).toContainEqual({ wait: { ms: 500 } });
+  expect(getSchema({ kind: 'journey-step', type: 'hover' })).toBeNull();
 });
 
 test('getExamples reads example yaml from plugin dist by convention', () => {

package/lib/docs/evalOperator.js

@@ -22,13 +22,14 @@ import resolveSource from './resolveSource.js';
 // headless-only. Falls back to headless whenever the tab path isn't usable
 // (no tab connected, or `source: 'tab'` was requested but it errored) so
 // agents always get an answer.
-async function evalOperator({ origin, pageId, pathParams, expression, source, user }) {
+async function evalOperator({ origin, pageId, pathParams, expression, source, user, data }) {
   const { tryTab, error, invalidInput } = resolveSource({
     name: 'evalOperator',
     pageId,
     pathParams,
     source,
     user,
+    data,
   });
   if (error) {
     return { error, invalidInput };
@@ -41,7 +42,7 @@ async function evalOperator({ origin, pageId, pathParams, expression, source, us
     }
   }
 
-  const result = await evalOperatorHeadless({ origin, pageId, pathParams, expression, user });
+  const result = await evalOperatorHeadless({ origin, pageId, pathParams, expression, user, data });
   return { ...result, source: 'headless' };
 }
 

package/lib/docs/evalOperatorHeadless.js

@@ -19,8 +19,10 @@ import { type } from '@lowdefy/helpers';
 import { getBrowser, openPage, buildPageUrl } from './getBrowser.js';
 import noBrowserError from './noBrowserError.js';
 import resolvePageInstance from './resolvePageInstance.js';
+import resolveToolCaller from './resolveToolCaller.js';
 import unsettledPageNote from './unsettledPageNote.js';
 import withBrowserSlot from './withBrowserSlot.js';
+import withDataSession from './withDataSession.js';
 
 // Evaluates an operator expression against the live client state of a
 // headless Chromium tab navigated to the page instance's own route (`pathParams`
@@ -33,6 +35,7 @@ async function evalOperatorHeadless({
   pathParams,
   expression,
   user,
+  data,
   timeout = 15000,
 }) {
   if (type.isNone(origin) || !type.isString(origin)) {
@@ -56,9 +59,27 @@ async function evalOperatorHeadless({
     return { error: instance.error, invalidInput: true };
   }
 
+  const caller = await resolveToolCaller({ user, data });
+  if (!type.isUndefined(caller.error)) {
+    return caller;
+  }
+
   return withBrowserSlot({
     task: () =>
-      evalOperatorInBrowser({ origin, pageId, pathParams, instance, expression, user, timeout }),
+      withDataSession({
+        dataSet: caller.dataSet,
+        task: ({ dataCookie }) =>
+          evalOperatorInBrowser({
+            origin,
+            pageId,
+            pathParams,
+            instance,
+            expression,
+            user: caller.user,
+            dataCookie,
+            timeout,
+          }),
+      }),
   });
 }
 
@@ -70,6 +91,7 @@ async function evalOperatorInBrowser({
   instance,
   expression,
   user,
+  dataCookie,
   timeout,
 }) {
   let browser;
@@ -90,6 +112,7 @@ async function evalOperatorInBrowser({
       path: instance.path,
       pathParams,
       user,
+      dataCookie,
       timeout,
     });
     context = opened.context;

package/lib/docs/getSchema.js

@@ -15,6 +15,7 @@
 */
 
 import { type } from '@lowdefy/helpers';
+import { JOURNEY_STEP_SCHEMAS, journeyStepSchema } from '@lowdefy/node-utils';
 
 import getHazards from './getHazards.js';
 import normalizeTypeKind from './normalizeTypeKind.js';
@@ -28,13 +29,40 @@ const SCHEMA_ARTIFACTS = {
   requests: 'plugins/requestSchemas.json',
 };
 
+const JOURNEY_STEP_KINDS = ['journey-step', 'journey-steps'];
+
+// kind journey-step returns the journey step grammar: every step, or the one
+// step `type` names.
+function getJourneyStepSchema({ typeName }) {
+  if (type.isNone(typeName) || typeName === '' || typeName === 'all') {
+    return { kind: 'journey-step', schema: journeyStepSchema };
+  }
+  const schema = JOURNEY_STEP_SCHEMAS[typeName];
+  if (type.isNone(schema)) {
+    return null;
+  }
+  return { kind: 'journey-step', type: typeName, schema };
+}
+
 function getSchema({ kind, type: typeName }) {
+  if (JOURNEY_STEP_KINDS.includes(String(kind ?? '').toLowerCase())) {
+    return getJourneyStepSchema({ typeName });
+  }
   const normalizedKind = normalizeTypeKind({ kind });
   if (type.isNone(SCHEMA_ARTIFACTS[normalizedKind])) {
     throw new Error(
       `No schemas available for type kind. Received ${JSON.stringify(
         kind
-      )}. Use one of: blocks, operators, actions, connections, requests.`
+      )}. Use one of: blocks, operators, actions, connections, requests, or journey-step for the journey step grammar.`
+    );
+  }
+  // type is optional only for journey-step, so a type kind without one is
+  // refused rather than looked up as "undefined".
+  if (type.isNone(typeName) || typeName === '') {
+    throw new Error(
+      `Getting a ${normalizedKind} schema requires a "type", the exact type name. Received ${JSON.stringify(
+        typeName
+      )}.`
     );
   }
   const schemas = readBuildArtifact({ name: SCHEMA_ARTIFACTS[normalizedKind] }) ?? {};

package/lib/docs/inspectState.js

@@ -22,13 +22,14 @@ import resolveSource from './resolveSource.js';
 // headless-only. Falls back to headless whenever the tab path isn't usable
 // (no tab connected, or `source: 'tab'` was requested but it errored) so
 // agents always get an answer.
-async function inspectState({ origin, pageId, pathParams, source, user }) {
+async function inspectState({ origin, pageId, pathParams, source, user, data }) {
   const { tryTab, error, invalidInput } = resolveSource({
     name: 'inspectState',
     pageId,
     pathParams,
     source,
     user,
+    data,
   });
   if (error) {
     return { error, invalidInput };
@@ -41,7 +42,7 @@ async function inspectState({ origin, pageId, pathParams, source, user }) {
     }
   }
 
-  const result = await inspectStateHeadless({ origin, pageId, pathParams, user });
+  const result = await inspectStateHeadless({ origin, pageId, pathParams, user, data });
   return { ...result, source: 'headless' };
 }