@lowdefy/server-dev 6.1.0 → 7.0.0

package/lib/docs/evalOperator.js

@@ -22,25 +22,27 @@ 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, 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 };
   }
 
   if (tryTab) {
-    const result = await evalOperatorInTab({ pageId, expression });
+    const result = await evalOperatorInTab({ pageId, pathParams, expression });
     if (!result?.error) {
       return { ...result, source: 'tab' };
     }
   }
 
-  const result = await evalOperatorHeadless({ origin, pageId, expression, user });
+  const result = await evalOperatorHeadless({ origin, pageId, pathParams, expression, user, data });
   return { ...result, source: 'headless' };
 }
 

package/lib/docs/evalOperatorHeadless.js

@@ -17,15 +17,32 @@
 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's own route, using the page's
+// headless Chromium tab navigated to the page instance's own route (`pathParams`
+// fill a patterned page's placeholders), read under the instance key, using the page's
 // own WebParser instance so results match runtime exactly. Mirrors
 // Inspector.jsx's evalExpression (the live-tab equivalent).
-async function evalOperatorHeadless({ origin, pageId, expression, user, timeout = 15000 }) {
+async function evalOperatorHeadless({
+  origin,
+  pageId,
+  pathParams,
+  expression,
+  user,
+  data,
+  timeout = 15000,
+}) {
   if (type.isNone(origin) || !type.isString(origin)) {
     return {
-      error: `evalOperatorHeadless requires an "origin" string. Received ${JSON.stringify(origin)}.`,
+      error: `evalOperatorHeadless requires an "origin" string. Received ${JSON.stringify(
+        origin
+      )}.`,
     };
   }
   if (type.isNone(pageId) || !type.isString(pageId)) {
@@ -37,30 +54,77 @@ async function evalOperatorHeadless({ origin, pageId, expression, user, timeout
     return { error: 'evalOperatorHeadless requires an "expression".' };
   }
 
+  const instance = resolvePageInstance({ pageId, pathParams });
+  if (!type.isUndefined(instance.error)) {
+    return { error: instance.error, invalidInput: true };
+  }
+
+  const caller = await resolveToolCaller({ user, data });
+  if (!type.isUndefined(caller.error)) {
+    return caller;
+  }
+
+  return withBrowserSlot({
+    task: () =>
+      withDataSession({
+        dataSet: caller.dataSet,
+        task: ({ dataCookie }) =>
+          evalOperatorInBrowser({
+            origin,
+            pageId,
+            pathParams,
+            instance,
+            expression,
+            user: caller.user,
+            dataCookie,
+            timeout,
+          }),
+      }),
+  });
+}
+
+// The part of evalOperatorHeadless that runs in the browser, inside a browser slot.
+async function evalOperatorInBrowser({
+  origin,
+  pageId,
+  pathParams,
+  instance,
+  expression,
+  user,
+  dataCookie,
+  timeout,
+}) {
   let browser;
   try {
     browser = await getBrowser();
   } catch (error) {
-    return {
-      error: `No Chromium available. Run: npx playwright install chromium (${error.message})`,
-    };
+    return { error: noBrowserError(error) };
   }
 
-  const url = buildPageUrl({ origin, pageId });
+  const url = buildPageUrl({ origin, pageId, path: instance.path, pathParams });
 
   let context;
   try {
-    const opened = await openPage({ browser, origin, pageId, user, timeout });
+    const opened = await openPage({
+      browser,
+      origin,
+      pageId,
+      path: instance.path,
+      pathParams,
+      user,
+      dataCookie,
+      timeout,
+    });
     context = opened.context;
     // Passed through as JSON so the page-side parser always receives a plain
     // value, matching how it arrives at Inspector.jsx's eval-request handler.
     const expressionJson = JSON.stringify(expression);
     const result = await opened.page.evaluate(
-      ({ id, exprJson }) => {
+      ({ id, instanceKey, path, exprJson }) => {
         const lowdefy = window.lowdefy;
-        const pageContext = lowdefy?.contexts?.[`page:${id}`];
+        const pageContext = lowdefy?.contexts?.[instanceKey];
         if (!pageContext) {
-          return { error: `No live context for page "${id}".` };
+          return { error: `No live context for page "${id}" at "/${path}".` };
         }
         const input = JSON.parse(exprJson);
         const { output, errors } = pageContext._internal.parser.parse({
@@ -72,8 +136,16 @@ async function evalOperatorHeadless({ origin, pageId, expression, user, timeout
           errors: errors.map((error) => error.message),
         };
       },
-      { id: pageId, exprJson: expressionJson }
+      {
+        id: pageId,
+        instanceKey: instance.instanceKey,
+        path: instance.path,
+        exprJson: expressionJson,
+      }
     );
+    if (!opened.ready) {
+      return { ...result, ready: false, note: unsettledPageNote({ timeout }) };
+    }
     return result;
   } catch (error) {
     return { error: `Failed to evaluate operator at "${url}": ${error.message}` };

package/lib/docs/evalOperatorHeadless.test.mjs

@@ -25,7 +25,10 @@ import { jest } from '@jest/globals';
 // screenshotPage.test.mjs, which exercises the same getBrowser.js singleton.
 jest.unstable_mockModule('playwright-core', () => ({
   chromium: { launch: jest.fn().mockRejectedValue(new Error("Executable doesn't exist")) },
+  selectors: { register: jest.fn(async () => {}) },
 }));
+// A missing shell would otherwise start a real download.
+jest.unstable_mockModule('./installHeadlessShell.js', () => ({ default: () => null }));
 
 // lib/build/config.js reads build/config.json from process.cwd() at import
 // time — chdir into a fixture that has one before getBrowser.js (which
@@ -35,6 +38,7 @@ const originalCwd = process.cwd();
 const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-eval-operator-test-'));
 fs.mkdirSync(path.join(fixtureDir, 'build'), { recursive: true });
 fs.writeFileSync(path.join(fixtureDir, 'build', 'config.json'), JSON.stringify({ basePath: '' }));
+fs.writeFileSync(path.join(fixtureDir, 'build', 'routes.json'), JSON.stringify([]));
 process.chdir(fixtureDir);
 
 const { default: evalOperatorHeadless } = await import('./evalOperatorHeadless.js');
@@ -68,5 +72,7 @@ test('evalOperatorHeadless returns an actionable error when no browser is availa
     pageId: 'home',
     expression: { _state: 'x' },
   });
-  expect(result.error).toMatch(/No Chromium available. Run: npx playwright install chromium/);
+  expect(result.error).toMatch(
+    /No Chromium available. Run: npx playwright install chromium-headless-shell/
+  );
 });

package/lib/docs/evalOperatorInTab.js

@@ -26,12 +26,13 @@ import { requestFromTab } from './tabChannel.js';
 // (see tabChannel.js) — `{ value, errors }` on success, or an `{ error }`
 // object if no tab is connected, the request timed out, or Inspector.jsx
 // itself failed to evaluate the expression.
-async function evalOperatorInTab({ pageId, expression }) {
+async function evalOperatorInTab({ pageId, pathParams, expression }) {
   if (type.isNone(expression)) {
     throw new Error('evalOperatorInTab requires an "expression".');
   }
   const response = await requestFromTab({
     pageId,
+    pathParams,
     event: 'eval-request',
     payload: { expression },
   });

package/lib/docs/findConfig.js

@@ -15,10 +15,12 @@
 */
 
 import path from 'node:path';
-import { resolveConfigLocation } from '@lowdefy/errors';
+import { ConfigError, resolveConfigLocation } from '@lowdefy/errors';
 import { type } from '@lowdefy/helpers';
 
 import buildPageIfNeeded from '../server/jitPageBuilder.js';
+import readMergedMaps from '../server/readMergedMaps.js';
+import getHazards from './getHazards.js';
 import readBuildArtifact from './readBuildArtifact.js';
 
 const MAX_MATCHES = 20;
@@ -45,16 +47,11 @@ function buildIdPattern(id) {
 // (`root.pages[N:pageId]...`) carry the page segment inline, so a containment
 // pattern covers those.
 function buildPageScope({ pageId, keyMap }) {
-  let rootKeyId = findPageRootKeyId({ pageId, keyMap });
-  // A page built during the skeleton build (e.g. the default 404 page) chains
-  // to the global config root, which every skeleton entry shares — useless as
-  // a page discriminator. Those pages' keys carry the page segment inline, so
-  // the pattern branch identifies them instead.
-  if (!type.isNone(rootKeyId) && rootKeyId === findGlobalRootId(keyMap)) {
-    rootKeyId = null;
-  }
+  // A page built during the skeleton build (e.g. the default 404 page) has
+  // no JIT root at all — its keys carry the page segment inline, so the
+  // pattern branch identifies them instead.
   return {
-    rootKeyId,
+    rootKeyId: findPageRootKeyId({ pageId, keyMap }),
     pagePattern: new RegExp(`\\bpages\\[\\d+:${escapeRegExp(pageId)}(:[^\\]]*)?\\]`),
   };
 }
@@ -68,38 +65,32 @@ function findGlobalRootId(keyMap) {
   return null;
 }
 
+// A built page artifact mixes keys from two trees: the skeleton build keys
+// the page stub (its `auth`, for one), chaining to the global config root,
+// while the JIT build keys the page content under its own root. Only the
+// JIT root discriminates pages, so skip keys that chain to the global root.
 function findPageRootKeyId({ pageId, keyMap }) {
   const artifact = readBuildArtifact({ name: `pages/${pageId}.json`, deserialize: true });
-  const keyId = findFirstKeyId(artifact);
-  if (type.isNone(keyId)) {
-    return null;
+  const globalRootId = findGlobalRootId(keyMap);
+  for (const keyId of collectKeyIds(artifact)) {
+    const rootKeyId = resolveChainRootId({ keyId, keyMap });
+    if (rootKeyId !== globalRootId) {
+      return rootKeyId;
+    }
   }
-  return resolveChainRootId({ keyId, keyMap });
+  return null;
 }
 
-function findFirstKeyId(node) {
+function collectKeyIds(node, keyIds = []) {
   if (type.isString(node?.['~k'])) {
-    return node['~k'];
+    keyIds.push(node['~k']);
   }
   if (type.isArray(node)) {
-    for (const item of node) {
-      const keyId = findFirstKeyId(item);
-      if (keyId) {
-        return keyId;
-      }
-    }
-    return null;
-  }
-  if (!type.isObject(node)) {
-    return null;
+    node.forEach((item) => collectKeyIds(item, keyIds));
+  } else if (type.isObject(node)) {
+    Object.keys(node).forEach((key) => collectKeyIds(node[key], keyIds));
   }
-  for (const key of Object.keys(node)) {
-    const keyId = findFirstKeyId(node[key]);
-    if (keyId) {
-      return keyId;
-    }
-  }
-  return null;
+  return keyIds;
 }
 
 // Walk ~k_parent to the top of the entry's subtree. addKeys assigns the tree
@@ -129,7 +120,46 @@ function belongsToPage({ keyId, entry, keyMap, pageScope }) {
   return resolveChainRootId({ keyId, keyMap }) === pageScope.rootKeyId;
 }
 
-function scanKeyMap({ id, keyMap, refMap, configDirectory, pageScope }) {
+// A key path ends in the matched node's own segment, `blocks[2:my_button:Button]`
+// (addKeys recArray writes `name[index:id:type]`), which is all the kind and
+// type information hazards need.
+const NODE_SEGMENT = /([A-Za-z_]+)\[\d+:([^\]:]+)(?::([^\]]*))?\]$/;
+const SEGMENT_KINDS = {
+  blocks: 'blocks',
+  connections: 'connections',
+  pages: 'pages',
+  requests: 'requests',
+};
+
+// writeRequests strips connectionId off the page's requests array after
+// writing the per-request artifact, so a request's connection is only
+// readable there. Without a pageId the match's page is not known, so the
+// registry's pages are tried in turn — a requestId is unique within a page.
+function findRequestConnectionId({ requestId, requestPageIds }) {
+  for (const pageId of requestPageIds) {
+    const request = readBuildArtifact({ name: `pages/${pageId}/requests/${requestId}.json` });
+    if (!type.isNone(request)) {
+      return request.connectionId ?? null;
+    }
+  }
+  return null;
+}
+
+function hazardsForMatch({ keyPath, requestPageIds }) {
+  const segment = NODE_SEGMENT.exec(keyPath);
+  if (type.isNone(segment)) {
+    return [];
+  }
+  const [, arrayName, id, nodeType] = segment;
+  const kind = SEGMENT_KINDS[arrayName] ?? null;
+  let connectionId = null;
+  if (kind === 'requests') {
+    connectionId = findRequestConnectionId({ requestId: id, requestPageIds });
+  }
+  return getHazards({ kind, type: nodeType ?? null, connectionId });
+}
+
+function scanKeyMap({ id, keyMap, refMap, configDirectory, pageScope, requestPageIds }) {
   const pattern = buildIdPattern(id);
   const matches = [];
   for (const [keyId, entry] of Object.entries(keyMap)) {
@@ -148,6 +178,7 @@ function scanKeyMap({ id, keyMap, refMap, configDirectory, pageScope }) {
     matches.push({
       keyPath: entry.key,
       location: resolveConfigLocation({ configKey: keyId, keyMap, refMap, configDirectory }),
+      hazards: hazardsForMatch({ keyPath: entry.key, requestPageIds }),
     });
   }
   return matches;
@@ -163,8 +194,8 @@ function deIndexId(id) {
   return id.replace(/\.\d+(?=\.|$)/g, () => '.$');
 }
 
-function scanKeyMapWithDeIndex({ id, keyMap, refMap, configDirectory, pageScope }) {
-  const matches = scanKeyMap({ id, keyMap, refMap, configDirectory, pageScope });
+function scanKeyMapWithDeIndex({ id, keyMap, refMap, configDirectory, pageScope, requestPageIds }) {
+  const matches = scanKeyMap({ id, keyMap, refMap, configDirectory, pageScope, requestPageIds });
   if (matches.length > 0) {
     return matches;
   }
@@ -172,17 +203,25 @@ function scanKeyMapWithDeIndex({ id, keyMap, refMap, configDirectory, pageScope
   if (deIndexedId === id) {
     return matches;
   }
-  return scanKeyMap({ id: deIndexedId, keyMap, refMap, configDirectory, pageScope });
+  return scanKeyMap({
+    id: deIndexedId,
+    keyMap,
+    refMap,
+    configDirectory,
+    pageScope,
+    requestPageIds,
+  });
 }
 
 // Locates a block/request/connection/etc by id, or a page by pageId. Block
-// content only exists in keyMap once its page has been JIT-built (see
-// lib/server/jitPageBuilder.js), so pass `pageId` to force-build and scan a
-// specific page. Never throws on not-found — agents should be able to treat
+// content is only in the key maps once its page has been JIT-built (see
+// lib/server/jitPageBuilder.js), and the dev server keeps the jitMaps/ files of
+// its current and previous build contexts only, so pass `pageId` to force-build
+// and scan a specific page. Never throws on not-found — agents should be able to treat
 // "no matches" as a normal result and try another id or pageId.
 async function findConfig({ id, pageId }) {
   if (type.isNone(id) || !type.isString(id)) {
-    throw new Error(
+    throw new ConfigError(
       `findConfig requires an "id" string. Received ${JSON.stringify(id)}. ` +
         'Use GET /lowdefy-docs/find/:id.'
     );
@@ -190,6 +229,7 @@ async function findConfig({ id, pageId }) {
 
   const pageRegistry = readBuildArtifact({ name: 'pageRegistry.json' }) ?? {};
   const configDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd();
+  const buildDirectory = path.join(process.cwd(), 'build');
 
   // A page's root block renders with blockId === pageId, so open-in-editor
   // and feedback enrichment hit this branch for it — they read
@@ -202,6 +242,7 @@ async function findConfig({ id, pageId }) {
       matches.push({
         keyPath: `pages[${id}]`,
         location: { source: path.resolve(configDirectory, refPath) },
+        hazards: getHazards({ kind: 'pages' }),
       });
     }
     return { kind: 'page', pageId: id, file: refPath, matches };
@@ -217,7 +258,6 @@ async function findConfig({ id, pageId }) {
       };
     }
 
-    const buildDirectory = path.join(process.cwd(), 'build');
     try {
       await buildPageIfNeeded({ pageId, buildDirectory, configDirectory });
     } catch (error) {
@@ -227,14 +267,14 @@ async function findConfig({ id, pageId }) {
       };
     }
 
-    const keyMap = readBuildArtifact({ name: 'keyMap.json' }) ?? {};
-    const refMap = readBuildArtifact({ name: 'refMap.json' }) ?? {};
+    const { keyMap, refMap } = await readMergedMaps({ buildDirectory });
     const matches = scanKeyMapWithDeIndex({
       id,
       keyMap,
       refMap,
       configDirectory,
       pageScope: buildPageScope({ pageId, keyMap }),
+      requestPageIds: [pageId],
     });
     return matches.length > 0
       ? { matches }
@@ -246,14 +286,20 @@ async function findConfig({ id, pageId }) {
         };
   }
 
-  const keyMap = readBuildArtifact({ name: 'keyMap.json' }) ?? {};
-  const refMap = readBuildArtifact({ name: 'refMap.json' }) ?? {};
-  const matches = scanKeyMapWithDeIndex({ id, keyMap, refMap, configDirectory });
+  const { keyMap, refMap } = await readMergedMaps({ buildDirectory });
+  const matches = scanKeyMapWithDeIndex({
+    id,
+    keyMap,
+    refMap,
+    configDirectory,
+    requestPageIds: Object.keys(pageRegistry),
+  });
   return {
     matches,
     note:
-      'Scanned without a pageId — content on pages that have not been JIT-built yet is not ' +
-      'in keyMap and was not covered. Pass ?pageId= to force-build and scan a specific page.',
+      'Scanned without a pageId — only pages built since the last two page edits are ' +
+      'covered; content on other pages was not scanned. Pass ?pageId= to force-build and ' +
+      'scan a specific page.',
   };
 }
 

package/lib/docs/fitResponse.js

@@ -0,0 +1,81 @@
+/*
+  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 crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Largest response returned inline, in serialized characters. The tool result
+// is pretty-printed, which adds roughly half again, so this keeps a result
+// inside the output budget of common MCP clients.
+const MAX_INLINE_RESPONSE_CHARS = 40_000;
+
+// Saved responses kept per app; the oldest beyond this are deleted on write.
+const MAX_SAVED_RESPONSES = 20;
+
+function pruneResponseFiles({ directory }) {
+  const files = fs
+    .readdirSync(directory)
+    .filter((fileName) => fileName.endsWith('.json'))
+    .map((fileName) => {
+      const filePath = path.join(directory, fileName);
+      return { filePath, mtime: fs.statSync(filePath).mtimeMs };
+    })
+    .sort((a, b) => b.mtime - a.mtime);
+  files.slice(MAX_SAVED_RESPONSES).forEach(({ filePath }) => fs.rmSync(filePath, { force: true }));
+}
+
+function writeResponseFile({ name, response }) {
+  const configDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd();
+  const directory = path.join(configDirectory, '.lowdefy', 'responses');
+  const safeName = name.replace(/[^a-zA-Z0-9_.-]/g, '_');
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const suffix = crypto.randomBytes(3).toString('hex');
+  const filePath = path.join(directory, `${safeName}-${stamp}-${suffix}.json`);
+  fs.mkdirSync(directory, { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(response, null, 2));
+  pruneResponseFiles({ directory });
+  return filePath;
+}
+
+// Returns the result untouched when its response fits inline. A larger
+// response, or any response when saveResponse is set, is written in full to
+// .lowdefy/responses/ in the config directory, and the result carries the
+// file's path and size in its place, so nothing is cut and an agent can read
+// or query the whole value.
+function fitResponse({ result, name, saveResponse = false }) {
+  // A request can resolve with no response; it is written as null.
+  const { response = null, ...rest } = result;
+  const json = JSON.stringify(response);
+  if (!saveResponse && json.length <= MAX_INLINE_RESPONSE_CHARS) {
+    return result;
+  }
+  const fitted = {
+    ...rest,
+    responseFile: writeResponseFile({ name, response }),
+    responseChars: json.length,
+  };
+  if (Array.isArray(response)) {
+    fitted.responseItems = response.length;
+  }
+  fitted.note = saveResponse
+    ? 'The full response was written to responseFile.'
+    : `The response is ${json.length} characters, over the ${MAX_INLINE_RESPONSE_CHARS} returned inline, so it was written in full to responseFile. Read or query that file instead.`;
+  return fitted;
+}
+
+export { MAX_INLINE_RESPONSE_CHARS, MAX_SAVED_RESPONSES };
+export default fitResponse;

package/lib/docs/fitResponse.test.mjs

@@ -0,0 +1,128 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import fitResponse, { MAX_INLINE_RESPONSE_CHARS, MAX_SAVED_RESPONSES } from './fitResponse.js';
+
+let configDirectory;
+
+beforeEach(() => {
+  configDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-fit-response-'));
+  process.env.LOWDEFY_DIRECTORY_CONFIG = configDirectory;
+});
+
+afterEach(() => {
+  delete process.env.LOWDEFY_DIRECTORY_CONFIG;
+});
+
+test('fitResponse returns the result untouched when the response fits', () => {
+  const result = { refused: false, response: [{ _id: 1 }], status: 'success' };
+
+  expect(fitResponse({ result, name: 'home.get_rows' })).toBe(result);
+  expect(fs.existsSync(path.join(configDirectory, '.lowdefy'))).toBe(false);
+});
+
+test('fitResponse keeps a null response untouched', () => {
+  const result = { response: null, status: 'success' };
+
+  expect(fitResponse({ result, name: 'home.get_rows' })).toBe(result);
+});
+
+test('fitResponse keeps a result with no response untouched', () => {
+  // A failed routine, or one that ends without :return, has no response.
+  const result = {
+    error: { '~e': { name: 'ServiceError', message: 'Something went wrong.' } },
+    response: undefined,
+    status: 'error',
+    success: false,
+  };
+
+  expect(fitResponse({ result, name: 'search' })).toBe(result);
+  expect(fs.existsSync(path.join(configDirectory, '.lowdefy'))).toBe(false);
+});
+
+test('fitResponse writes an oversized response to a file and returns its path in its place', () => {
+  const rows = Array.from({ length: 500 }, (_, index) => ({ _id: index, title: 'x'.repeat(100) }));
+  const result = { response: rows, status: 'success', error: null };
+
+  const fitted = fitResponse({ result, name: 'tasks/list.get_rows' });
+
+  expect(fitted.response).toBeUndefined();
+  expect(fitted.status).toBe('success');
+  expect(fitted.error).toBeNull();
+  expect(fitted.responseItems).toBe(500);
+  expect(fitted.responseChars).toBe(JSON.stringify(rows).length);
+  expect(fitted.responseChars).toBeGreaterThan(MAX_INLINE_RESPONSE_CHARS);
+  expect(fitted.note).toContain('written in full to responseFile');
+  expect(path.dirname(fitted.responseFile)).toBe(
+    path.join(configDirectory, '.lowdefy', 'responses')
+  );
+  expect(path.basename(fitted.responseFile).startsWith('tasks_list.get_rows-')).toBe(true);
+  expect(JSON.parse(fs.readFileSync(fitted.responseFile, 'utf8'))).toEqual(rows);
+  expect(result.response).toBe(rows);
+});
+
+test('fitResponse writes a small response to a file when saveResponse is set', () => {
+  const result = { response: { total: 3 }, status: 'success' };
+
+  const fitted = fitResponse({ result, name: 'report', saveResponse: true });
+
+  expect(fitted.response).toBeUndefined();
+  expect(fitted.responseItems).toBeUndefined();
+  expect(fitted.note).toBe('The full response was written to responseFile.');
+  expect(JSON.parse(fs.readFileSync(fitted.responseFile, 'utf8'))).toEqual({ total: 3 });
+});
+
+test('fitResponse writes a missing response as null when saveResponse is set', () => {
+  const result = { status: 'success' };
+
+  const fitted = fitResponse({ result, name: 'home.update_row', saveResponse: true });
+
+  expect(fitted.responseChars).toBe(4);
+  expect(JSON.parse(fs.readFileSync(fitted.responseFile, 'utf8'))).toBeNull();
+});
+
+test('fitResponse gives every saved response its own file', () => {
+  const files = Array.from({ length: 5 }, (_, index) =>
+    fitResponse({ result: { response: { index } }, name: 'same', saveResponse: true })
+  ).map(({ responseFile }) => responseFile);
+
+  expect(new Set(files).size).toBe(5);
+  files.forEach((file, index) => {
+    expect(JSON.parse(fs.readFileSync(file, 'utf8'))).toEqual({ index });
+  });
+});
+
+test('fitResponse keeps only the most recent saved responses', () => {
+  const directory = path.join(configDirectory, '.lowdefy', 'responses');
+  fs.mkdirSync(directory, { recursive: true });
+  const old = path.join(directory, 'old-response.json');
+  fs.writeFileSync(old, '{}');
+  const longAgo = new Date('2000-01-01T00:00:00.000Z');
+  fs.utimesSync(old, longAgo, longAgo);
+
+  const files = Array.from({ length: MAX_SAVED_RESPONSES }, (_, index) =>
+    fitResponse({ result: { response: { index } }, name: 'report', saveResponse: true })
+  ).map(({ responseFile }) => responseFile);
+
+  const kept = fs.readdirSync(directory).map((fileName) => path.join(directory, fileName));
+  expect(kept).toHaveLength(MAX_SAVED_RESPONSES);
+  expect(kept).not.toContain(old);
+  expect(kept.sort()).toEqual([...files].sort());
+});