donobu 5.60.0 → 5.60.1

package/dist/esm/tools/RunInlineJavaScriptCodeTool.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RunInlineJavaScriptCodeTool = exports.RunInlineJavaScriptCodeGptSchema = exports.RunInlineJavaScriptCodeCoreSchema = void 0;
 const v4_1 = require("zod/v4");
 const ToolSchema_1 = require("../models/ToolSchema");
+const PlaywrightUtils_1 = require("../utils/PlaywrightUtils");
 const TargetUtils_1 = require("../utils/TargetUtils");
 const Tool_1 = require("./Tool");
 exports.RunInlineJavaScriptCodeCoreSchema = v4_1.z.object({
@@ -24,10 +25,50 @@ as well as the overall environment of the webpage itself. The JS code must be of
 \`\`\``, exports.RunInlineJavaScriptCodeCoreSchema, exports.RunInlineJavaScriptCodeGptSchema, false, undefined, ['web']);
     }
     async call(context, parameters) {
-        const result = await (0, TargetUtils_1.webPage)(context).evaluate(parameters.javaScriptCode);
+        let result;
+        try {
+            result = await (0, TargetUtils_1.webPage)(context).evaluate(PlaywrightUtils_1.PlaywrightUtils.asSizeGuardedJavaScriptExpression(parameters.javaScriptCode, { stashOversizedResult: true }));
+        }
+        catch (error) {
+            // Stash variables are wiped by navigation/reload, which surfaces as a
+            // cryptic "cannot read properties of undefined" — give the model the
+            // real story so it re-extracts instead of retrying blind.
+            if (parameters.javaScriptCode.includes('__dnb_result_') &&
+                !PlaywrightUtils_1.PlaywrightUtils.isPageClosedError(error)) {
+                return {
+                    isSuccessful: false,
+                    forLlm: `FAILED! ${error.message}\n` +
+                        'Note: window.__dnb_result_* variables are cleared when the page ' +
+                        'navigates or reloads, and only the most recent ' +
+                        `${PlaywrightUtils_1.PlaywrightUtils.MAX_STASHED_RESULTS} are kept. If the variable ` +
+                        'no longer exists, re-run the code that originally produced it.',
+                    metadata: null,
+                };
+            }
+            throw error;
+        }
+        if (result.oversized) {
+            const sizeNote = result.size === null
+                ? 'it is not JSON-serializable'
+                : `${result.size} characters of JSON`;
+            return {
+                isSuccessful: true,
+                forLlm: `The code ran successfully, but its result was too large to return directly (${sizeNote}). ` +
+                    `The result is ${result.summary}.\n` +
+                    `The full result is saved in the page as \`window.${result.stashedAt}\` and remains ` +
+                    'available until the page navigates or reloads.\n' +
+                    `Retrieve what you need with further ${RunInlineJavaScriptCodeTool.NAME} calls that ` +
+                    'slice, filter, or aggregate it, for example:\n' +
+                    `() => { return window.${result.stashedAt}.slice(0, 100); }\n` +
+                    `Preview of the result:\n${result.preview}`,
+                metadata: null,
+            };
+        }
         return {
             isSuccessful: true,
-            forLlm: '' + JSON.stringify(result),
+            forLlm: result.value === undefined
+                ? 'The code ran successfully and returned undefined.'
+                : '' + JSON.stringify(result.value),
             metadata: null,
         };
     }

package/dist/esm/tools/RunSandboxedJavaScriptCodeTool.js

@@ -4,6 +4,7 @@ exports.RunSandboxedJavaScriptCodeTool = exports.RunSandboxedJavaScriptCodeGptSc
 const playwright_1 = require("playwright");
 const v4_1 = require("zod/v4");
 const ToolSchema_1 = require("../models/ToolSchema");
+const PlaywrightUtils_1 = require("../utils/PlaywrightUtils");
 const Tool_1 = require("./Tool");
 exports.RunSandboxedJavaScriptCodeCoreSchema = v4_1.z.object({
     javaScriptCode: v4_1.z.string().describe('The JavaScript code to run.'),
@@ -30,10 +31,31 @@ webpage's DOM is *not* available. The JS code must be of the form:
         });
         const sandBoxedPage = await sandBoxedBrowser.newPage();
         try {
-            const result = await sandBoxedPage.evaluate(parameters.javaScriptCode);
+            // No stash on overflow: the sandboxed browser is discarded below, so a
+            // page-side stash could never be read back. Re-running refined code is
+            // free here (it is self-contained computation), so the model is told to
+            // do that instead.
+            const result = await sandBoxedPage.evaluate(PlaywrightUtils_1.PlaywrightUtils.asSizeGuardedJavaScriptExpression(parameters.javaScriptCode, { stashOversizedResult: false }));
+            if (result.oversized) {
+                const sizeNote = result.size === null
+                    ? 'it is not JSON-serializable'
+                    : `${result.size} characters of JSON`;
+                return {
+                    isSuccessful: true,
+                    forLlm: `The code ran successfully, but its result was too large to return (${sizeNote}). ` +
+                        `The result was ${result.summary}.\n` +
+                        'This sandboxed environment is discarded after every call, so the result cannot be ' +
+                        'retrieved later — re-run this tool with code modified to return less data ' +
+                        '(aggregate, filter, slice, or count instead).\n' +
+                        `Preview of the result:\n${result.preview}`,
+                    metadata: null,
+                };
+            }
             return {
                 isSuccessful: true,
-                forLlm: '' + JSON.stringify(result),
+                forLlm: result.value === undefined
+                    ? 'The code ran successfully and returned undefined.'
+                    : '' + JSON.stringify(result.value),
                 metadata: null,
             };
         }

package/dist/esm/utils/PlaywrightUtils.d.ts

@@ -1,9 +1,47 @@
 import type { BrowserContext, Locator, Page, PageScreenshotOptions } from 'playwright';
+/**
+ * Envelope resolved by expressions built with
+ * {@link PlaywrightUtils.asSizeGuardedJavaScriptExpression}. Small results
+ * come back inline in `value`; oversized (or non-JSON-serializable) results
+ * come back as a structural summary plus preview, with `stashedAt` naming the
+ * `window.__dnb_result_<n>` variable holding the full value when stashing was
+ * requested.
+ */
+export type SizeGuardedEvaluationResult = {
+    __dnbGuard: true;
+    oversized: false;
+    value: unknown;
+} | {
+    __dnbGuard: true;
+    oversized: true;
+    /** Serialized size in JSON characters, or null if not JSON-serializable. */
+    size: number | null;
+    summary: string;
+    preview: string;
+    stashedAt: string | null;
+};
 /**
  * Miscellaneous utility functions for working with the Playwright SDK. If you are looking to
  * instantiate a Playwright instance, see PlaywrightSetup instead.
  */
 export declare class PlaywrightUtils {
+    /**
+     * Maximum serialized size (in JSON characters) of an evaluation result that
+     * {@link asSizeGuardedJavaScriptExpression} returns inline. Results above
+     * this go into the conversation history verbatim, so this bounds prompt
+     * growth per tool call.
+     */
+    static readonly MAX_INLINE_RESULT_JSON_CHARS = 32000;
+    /**
+     * Number of characters of the serialized result included as a preview when
+     * a result is too large to return inline.
+     */
+    static readonly OVERSIZED_RESULT_PREVIEW_CHARS = 2000;
+    /**
+     * Number of oversized results kept alive in the page via
+     * `window.__dnb_result_<n>` stash variables before the oldest is released.
+     */
+    static readonly MAX_STASHED_RESULTS = 3;
     private static _blankJpeg;
     private static _blankPng;
     private static readonly _browserInstallPromises;
@@ -49,6 +87,43 @@ export declare class PlaywrightUtils {
      * scripts.
      */
     static setupBasicBrowserContext(browserContext: BrowserContext): Promise<void>;
+    /**
+     * Wraps arbitrary JavaScript code so that it can be passed as a string to
+     * Playwright's evaluate(). Playwright evaluates string arguments as bare
+     * expressions, so function-form code like `() => {...}` would evaluate to
+     * an (unserializable) function object that is never invoked, and the caller
+     * would get back undefined. The returned expression invokes function-form
+     * code and passes plain expressions through unchanged. Promise results
+     * (e.g. from async function-form code) are awaited by evaluate() itself.
+     *
+     * The wrapped code is placed on its own lines so that a trailing `//`
+     * comment cannot swallow the closing parenthesis.
+     */
+    static asInvokedJavaScriptExpression(code: string): string;
+    /**
+     * Like {@link asInvokedJavaScriptExpression}, but the result is measured
+     * page-side before it crosses the Playwright wire, so an enormous result
+     * never gets serialized over CDP into this process. The returned expression
+     * always resolves to a {@link SizeGuardedEvaluationResult} envelope.
+     *
+     * When the serialized result exceeds `maxInlineChars`, the envelope carries
+     * a structural summary and a short preview instead of the value. With
+     * `stashOversizedResult`, the value itself (a reference, not a copy) is
+     * additionally kept in the page as `window.__dnb_result_<n>` so follow-up
+     * evaluations can slice or aggregate it. The stash counter lives on
+     * `window`, so it resets with the page — names stay deterministic across
+     * cached replays because navigations replay too. Only the most recent
+     * {@link MAX_STASHED_RESULTS} stashes are kept alive.
+     *
+     * Results that fail JSON serialization (circular structures, BigInt, etc.)
+     * are treated as oversized with a `null` size, since they could not be
+     * returned through the tool result either.
+     */
+    static asSizeGuardedJavaScriptExpression(code: string, options: {
+        stashOversizedResult: boolean;
+        maxInlineChars?: number;
+        previewChars?: number;
+    }): string;
     /**
      * Returned true IFF the given error is a Playwright error regarding page closing,
      * of if the given error is an instance of {@link PageClosedException}.

package/dist/esm/utils/PlaywrightUtils.js

@@ -133,6 +133,111 @@ class PlaywrightUtils {
         await browserContext.addInitScript(dialog_prompt_tracker_1.installDialogPromptTracker);
         await browserContext.addInitScript(smart_selector_generator_1.installSmartSelectorGenerator);
     }
+    /**
+     * Wraps arbitrary JavaScript code so that it can be passed as a string to
+     * Playwright's evaluate(). Playwright evaluates string arguments as bare
+     * expressions, so function-form code like `() => {...}` would evaluate to
+     * an (unserializable) function object that is never invoked, and the caller
+     * would get back undefined. The returned expression invokes function-form
+     * code and passes plain expressions through unchanged. Promise results
+     * (e.g. from async function-form code) are awaited by evaluate() itself.
+     *
+     * The wrapped code is placed on its own lines so that a trailing `//`
+     * comment cannot swallow the closing parenthesis.
+     */
+    static asInvokedJavaScriptExpression(code) {
+        return `(() => {
+  const __donobuEvalResult = (
+${code}
+  );
+  return typeof __donobuEvalResult === 'function'
+    ? __donobuEvalResult()
+    : __donobuEvalResult;
+})()`;
+    }
+    /**
+     * Like {@link asInvokedJavaScriptExpression}, but the result is measured
+     * page-side before it crosses the Playwright wire, so an enormous result
+     * never gets serialized over CDP into this process. The returned expression
+     * always resolves to a {@link SizeGuardedEvaluationResult} envelope.
+     *
+     * When the serialized result exceeds `maxInlineChars`, the envelope carries
+     * a structural summary and a short preview instead of the value. With
+     * `stashOversizedResult`, the value itself (a reference, not a copy) is
+     * additionally kept in the page as `window.__dnb_result_<n>` so follow-up
+     * evaluations can slice or aggregate it. The stash counter lives on
+     * `window`, so it resets with the page — names stay deterministic across
+     * cached replays because navigations replay too. Only the most recent
+     * {@link MAX_STASHED_RESULTS} stashes are kept alive.
+     *
+     * Results that fail JSON serialization (circular structures, BigInt, etc.)
+     * are treated as oversized with a `null` size, since they could not be
+     * returned through the tool result either.
+     */
+    static asSizeGuardedJavaScriptExpression(code, options) {
+        const maxInlineChars = options.maxInlineChars ?? PlaywrightUtils.MAX_INLINE_RESULT_JSON_CHARS;
+        const previewChars = options.previewChars ?? PlaywrightUtils.OVERSIZED_RESULT_PREVIEW_CHARS;
+        const stashSnippet = options.stashOversizedResult
+            ? `{
+      const __w = window;
+      __w.__dnb_stash_count = (__w.__dnb_stash_count || 0) + 1;
+      __stashedAt = '__dnb_result_' + __w.__dnb_stash_count;
+      __w[__stashedAt] = __value;
+      __w.__dnb_stash_names = __w.__dnb_stash_names || [];
+      __w.__dnb_stash_names.push(__stashedAt);
+      while (__w.__dnb_stash_names.length > ${PlaywrightUtils.MAX_STASHED_RESULTS}) {
+        delete __w[__w.__dnb_stash_names.shift()];
+      }
+    }`
+            : '';
+        return `(() => {
+  const __pending = Promise.resolve(
+${PlaywrightUtils.asInvokedJavaScriptExpression(code)}
+  );
+  return __pending.then((__value) => {
+    if (__value === undefined) {
+      return { __dnbGuard: true, oversized: false, value: __value };
+    }
+    let __json;
+    try {
+      __json = JSON.stringify(__value);
+    } catch {
+      __json = undefined;
+    }
+    if (__json !== undefined && __json.length <= ${maxInlineChars}) {
+      return { __dnbGuard: true, oversized: false, value: __value };
+    }
+    const __summary = (() => {
+      if (Array.isArray(__value)) {
+        const __first = __value.find((el) => el && typeof el === 'object');
+        const __keys = __first ? Object.keys(__first).slice(0, 12).join(', ') : null;
+        return 'an array of ' + __value.length + ' elements' +
+          (__keys ? ' (element keys: ' + __keys + ')' : '');
+      }
+      if (typeof __value === 'object' && __value !== null) {
+        return 'an object with keys: ' + Object.keys(__value).slice(0, 24).join(', ');
+      }
+      return 'a ' + typeof __value;
+    })();
+    let __preview = '';
+    try {
+      __preview = (__json !== undefined ? __json : String(__value)).slice(0, ${previewChars});
+    } catch {
+      // Leave the preview empty if the value cannot be stringified at all.
+    }
+    let __stashedAt = null;
+    ${stashSnippet}
+    return {
+      __dnbGuard: true,
+      oversized: true,
+      size: __json === undefined ? null : __json.length,
+      summary: __summary,
+      preview: __preview,
+      stashedAt: __stashedAt,
+    };
+  });
+})()`;
+    }
     /**
      * Returned true IFF the given error is a Playwright error regarding page closing,
      * of if the given error is an instance of {@link PageClosedException}.
@@ -297,6 +402,23 @@ class PlaywrightUtils {
     }
 }
 exports.PlaywrightUtils = PlaywrightUtils;
+/**
+ * Maximum serialized size (in JSON characters) of an evaluation result that
+ * {@link asSizeGuardedJavaScriptExpression} returns inline. Results above
+ * this go into the conversation history verbatim, so this bounds prompt
+ * growth per tool call.
+ */
+PlaywrightUtils.MAX_INLINE_RESULT_JSON_CHARS = 32_000;
+/**
+ * Number of characters of the serialized result included as a preview when
+ * a result is too large to return inline.
+ */
+PlaywrightUtils.OVERSIZED_RESULT_PREVIEW_CHARS = 2_000;
+/**
+ * Number of oversized results kept alive in the page via
+ * `window.__dnb_result_<n>` stash variables before the oldest is released.
+ */
+PlaywrightUtils.MAX_STASHED_RESULTS = 3;
 // Per-browser in-flight install promises — deduplicate concurrent requests.
 PlaywrightUtils._browserInstallPromises = new Map();
 //# sourceMappingURL=PlaywrightUtils.js.map

package/dist/tools/RunInlineJavaScriptCodeTool.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RunInlineJavaScriptCodeTool = exports.RunInlineJavaScriptCodeGptSchema = exports.RunInlineJavaScriptCodeCoreSchema = void 0;
 const v4_1 = require("zod/v4");
 const ToolSchema_1 = require("../models/ToolSchema");
+const PlaywrightUtils_1 = require("../utils/PlaywrightUtils");
 const TargetUtils_1 = require("../utils/TargetUtils");
 const Tool_1 = require("./Tool");
 exports.RunInlineJavaScriptCodeCoreSchema = v4_1.z.object({
@@ -24,10 +25,50 @@ as well as the overall environment of the webpage itself. The JS code must be of
 \`\`\``, exports.RunInlineJavaScriptCodeCoreSchema, exports.RunInlineJavaScriptCodeGptSchema, false, undefined, ['web']);
     }
     async call(context, parameters) {
-        const result = await (0, TargetUtils_1.webPage)(context).evaluate(parameters.javaScriptCode);
+        let result;
+        try {
+            result = await (0, TargetUtils_1.webPage)(context).evaluate(PlaywrightUtils_1.PlaywrightUtils.asSizeGuardedJavaScriptExpression(parameters.javaScriptCode, { stashOversizedResult: true }));
+        }
+        catch (error) {
+            // Stash variables are wiped by navigation/reload, which surfaces as a
+            // cryptic "cannot read properties of undefined" — give the model the
+            // real story so it re-extracts instead of retrying blind.
+            if (parameters.javaScriptCode.includes('__dnb_result_') &&
+                !PlaywrightUtils_1.PlaywrightUtils.isPageClosedError(error)) {
+                return {
+                    isSuccessful: false,
+                    forLlm: `FAILED! ${error.message}\n` +
+                        'Note: window.__dnb_result_* variables are cleared when the page ' +
+                        'navigates or reloads, and only the most recent ' +
+                        `${PlaywrightUtils_1.PlaywrightUtils.MAX_STASHED_RESULTS} are kept. If the variable ` +
+                        'no longer exists, re-run the code that originally produced it.',
+                    metadata: null,
+                };
+            }
+            throw error;
+        }
+        if (result.oversized) {
+            const sizeNote = result.size === null
+                ? 'it is not JSON-serializable'
+                : `${result.size} characters of JSON`;
+            return {
+                isSuccessful: true,
+                forLlm: `The code ran successfully, but its result was too large to return directly (${sizeNote}). ` +
+                    `The result is ${result.summary}.\n` +
+                    `The full result is saved in the page as \`window.${result.stashedAt}\` and remains ` +
+                    'available until the page navigates or reloads.\n' +
+                    `Retrieve what you need with further ${RunInlineJavaScriptCodeTool.NAME} calls that ` +
+                    'slice, filter, or aggregate it, for example:\n' +
+                    `() => { return window.${result.stashedAt}.slice(0, 100); }\n` +
+                    `Preview of the result:\n${result.preview}`,
+                metadata: null,
+            };
+        }
         return {
             isSuccessful: true,
-            forLlm: '' + JSON.stringify(result),
+            forLlm: result.value === undefined
+                ? 'The code ran successfully and returned undefined.'
+                : '' + JSON.stringify(result.value),
             metadata: null,
         };
     }

package/dist/tools/RunSandboxedJavaScriptCodeTool.js

@@ -4,6 +4,7 @@ exports.RunSandboxedJavaScriptCodeTool = exports.RunSandboxedJavaScriptCodeGptSc
 const playwright_1 = require("playwright");
 const v4_1 = require("zod/v4");
 const ToolSchema_1 = require("../models/ToolSchema");
+const PlaywrightUtils_1 = require("../utils/PlaywrightUtils");
 const Tool_1 = require("./Tool");
 exports.RunSandboxedJavaScriptCodeCoreSchema = v4_1.z.object({
     javaScriptCode: v4_1.z.string().describe('The JavaScript code to run.'),
@@ -30,10 +31,31 @@ webpage's DOM is *not* available. The JS code must be of the form:
         });
         const sandBoxedPage = await sandBoxedBrowser.newPage();
         try {
-            const result = await sandBoxedPage.evaluate(parameters.javaScriptCode);
+            // No stash on overflow: the sandboxed browser is discarded below, so a
+            // page-side stash could never be read back. Re-running refined code is
+            // free here (it is self-contained computation), so the model is told to
+            // do that instead.
+            const result = await sandBoxedPage.evaluate(PlaywrightUtils_1.PlaywrightUtils.asSizeGuardedJavaScriptExpression(parameters.javaScriptCode, { stashOversizedResult: false }));
+            if (result.oversized) {
+                const sizeNote = result.size === null
+                    ? 'it is not JSON-serializable'
+                    : `${result.size} characters of JSON`;
+                return {
+                    isSuccessful: true,
+                    forLlm: `The code ran successfully, but its result was too large to return (${sizeNote}). ` +
+                        `The result was ${result.summary}.\n` +
+                        'This sandboxed environment is discarded after every call, so the result cannot be ' +
+                        'retrieved later — re-run this tool with code modified to return less data ' +
+                        '(aggregate, filter, slice, or count instead).\n' +
+                        `Preview of the result:\n${result.preview}`,
+                    metadata: null,
+                };
+            }
             return {
                 isSuccessful: true,
-                forLlm: '' + JSON.stringify(result),
+                forLlm: result.value === undefined
+                    ? 'The code ran successfully and returned undefined.'
+                    : '' + JSON.stringify(result.value),
                 metadata: null,
             };
         }

package/dist/utils/PlaywrightUtils.d.ts

@@ -1,9 +1,47 @@
 import type { BrowserContext, Locator, Page, PageScreenshotOptions } from 'playwright';
+/**
+ * Envelope resolved by expressions built with
+ * {@link PlaywrightUtils.asSizeGuardedJavaScriptExpression}. Small results
+ * come back inline in `value`; oversized (or non-JSON-serializable) results
+ * come back as a structural summary plus preview, with `stashedAt` naming the
+ * `window.__dnb_result_<n>` variable holding the full value when stashing was
+ * requested.
+ */
+export type SizeGuardedEvaluationResult = {
+    __dnbGuard: true;
+    oversized: false;
+    value: unknown;
+} | {
+    __dnbGuard: true;
+    oversized: true;
+    /** Serialized size in JSON characters, or null if not JSON-serializable. */
+    size: number | null;
+    summary: string;
+    preview: string;
+    stashedAt: string | null;
+};
 /**
  * Miscellaneous utility functions for working with the Playwright SDK. If you are looking to
  * instantiate a Playwright instance, see PlaywrightSetup instead.
  */
 export declare class PlaywrightUtils {
+    /**
+     * Maximum serialized size (in JSON characters) of an evaluation result that
+     * {@link asSizeGuardedJavaScriptExpression} returns inline. Results above
+     * this go into the conversation history verbatim, so this bounds prompt
+     * growth per tool call.
+     */
+    static readonly MAX_INLINE_RESULT_JSON_CHARS = 32000;
+    /**
+     * Number of characters of the serialized result included as a preview when
+     * a result is too large to return inline.
+     */
+    static readonly OVERSIZED_RESULT_PREVIEW_CHARS = 2000;
+    /**
+     * Number of oversized results kept alive in the page via
+     * `window.__dnb_result_<n>` stash variables before the oldest is released.
+     */
+    static readonly MAX_STASHED_RESULTS = 3;
     private static _blankJpeg;
     private static _blankPng;
     private static readonly _browserInstallPromises;
@@ -49,6 +87,43 @@ export declare class PlaywrightUtils {
      * scripts.
      */
     static setupBasicBrowserContext(browserContext: BrowserContext): Promise<void>;
+    /**
+     * Wraps arbitrary JavaScript code so that it can be passed as a string to
+     * Playwright's evaluate(). Playwright evaluates string arguments as bare
+     * expressions, so function-form code like `() => {...}` would evaluate to
+     * an (unserializable) function object that is never invoked, and the caller
+     * would get back undefined. The returned expression invokes function-form
+     * code and passes plain expressions through unchanged. Promise results
+     * (e.g. from async function-form code) are awaited by evaluate() itself.
+     *
+     * The wrapped code is placed on its own lines so that a trailing `//`
+     * comment cannot swallow the closing parenthesis.
+     */
+    static asInvokedJavaScriptExpression(code: string): string;
+    /**
+     * Like {@link asInvokedJavaScriptExpression}, but the result is measured
+     * page-side before it crosses the Playwright wire, so an enormous result
+     * never gets serialized over CDP into this process. The returned expression
+     * always resolves to a {@link SizeGuardedEvaluationResult} envelope.
+     *
+     * When the serialized result exceeds `maxInlineChars`, the envelope carries
+     * a structural summary and a short preview instead of the value. With
+     * `stashOversizedResult`, the value itself (a reference, not a copy) is
+     * additionally kept in the page as `window.__dnb_result_<n>` so follow-up
+     * evaluations can slice or aggregate it. The stash counter lives on
+     * `window`, so it resets with the page — names stay deterministic across
+     * cached replays because navigations replay too. Only the most recent
+     * {@link MAX_STASHED_RESULTS} stashes are kept alive.
+     *
+     * Results that fail JSON serialization (circular structures, BigInt, etc.)
+     * are treated as oversized with a `null` size, since they could not be
+     * returned through the tool result either.
+     */
+    static asSizeGuardedJavaScriptExpression(code: string, options: {
+        stashOversizedResult: boolean;
+        maxInlineChars?: number;
+        previewChars?: number;
+    }): string;
     /**
      * Returned true IFF the given error is a Playwright error regarding page closing,
      * of if the given error is an instance of {@link PageClosedException}.

package/dist/utils/PlaywrightUtils.js

@@ -133,6 +133,111 @@ class PlaywrightUtils {
         await browserContext.addInitScript(dialog_prompt_tracker_1.installDialogPromptTracker);
         await browserContext.addInitScript(smart_selector_generator_1.installSmartSelectorGenerator);
     }
+    /**
+     * Wraps arbitrary JavaScript code so that it can be passed as a string to
+     * Playwright's evaluate(). Playwright evaluates string arguments as bare
+     * expressions, so function-form code like `() => {...}` would evaluate to
+     * an (unserializable) function object that is never invoked, and the caller
+     * would get back undefined. The returned expression invokes function-form
+     * code and passes plain expressions through unchanged. Promise results
+     * (e.g. from async function-form code) are awaited by evaluate() itself.
+     *
+     * The wrapped code is placed on its own lines so that a trailing `//`
+     * comment cannot swallow the closing parenthesis.
+     */
+    static asInvokedJavaScriptExpression(code) {
+        return `(() => {
+  const __donobuEvalResult = (
+${code}
+  );
+  return typeof __donobuEvalResult === 'function'
+    ? __donobuEvalResult()
+    : __donobuEvalResult;
+})()`;
+    }
+    /**
+     * Like {@link asInvokedJavaScriptExpression}, but the result is measured
+     * page-side before it crosses the Playwright wire, so an enormous result
+     * never gets serialized over CDP into this process. The returned expression
+     * always resolves to a {@link SizeGuardedEvaluationResult} envelope.
+     *
+     * When the serialized result exceeds `maxInlineChars`, the envelope carries
+     * a structural summary and a short preview instead of the value. With
+     * `stashOversizedResult`, the value itself (a reference, not a copy) is
+     * additionally kept in the page as `window.__dnb_result_<n>` so follow-up
+     * evaluations can slice or aggregate it. The stash counter lives on
+     * `window`, so it resets with the page — names stay deterministic across
+     * cached replays because navigations replay too. Only the most recent
+     * {@link MAX_STASHED_RESULTS} stashes are kept alive.
+     *
+     * Results that fail JSON serialization (circular structures, BigInt, etc.)
+     * are treated as oversized with a `null` size, since they could not be
+     * returned through the tool result either.
+     */
+    static asSizeGuardedJavaScriptExpression(code, options) {
+        const maxInlineChars = options.maxInlineChars ?? PlaywrightUtils.MAX_INLINE_RESULT_JSON_CHARS;
+        const previewChars = options.previewChars ?? PlaywrightUtils.OVERSIZED_RESULT_PREVIEW_CHARS;
+        const stashSnippet = options.stashOversizedResult
+            ? `{
+      const __w = window;
+      __w.__dnb_stash_count = (__w.__dnb_stash_count || 0) + 1;
+      __stashedAt = '__dnb_result_' + __w.__dnb_stash_count;
+      __w[__stashedAt] = __value;
+      __w.__dnb_stash_names = __w.__dnb_stash_names || [];
+      __w.__dnb_stash_names.push(__stashedAt);
+      while (__w.__dnb_stash_names.length > ${PlaywrightUtils.MAX_STASHED_RESULTS}) {
+        delete __w[__w.__dnb_stash_names.shift()];
+      }
+    }`
+            : '';
+        return `(() => {
+  const __pending = Promise.resolve(
+${PlaywrightUtils.asInvokedJavaScriptExpression(code)}
+  );
+  return __pending.then((__value) => {
+    if (__value === undefined) {
+      return { __dnbGuard: true, oversized: false, value: __value };
+    }
+    let __json;
+    try {
+      __json = JSON.stringify(__value);
+    } catch {
+      __json = undefined;
+    }
+    if (__json !== undefined && __json.length <= ${maxInlineChars}) {
+      return { __dnbGuard: true, oversized: false, value: __value };
+    }
+    const __summary = (() => {
+      if (Array.isArray(__value)) {
+        const __first = __value.find((el) => el && typeof el === 'object');
+        const __keys = __first ? Object.keys(__first).slice(0, 12).join(', ') : null;
+        return 'an array of ' + __value.length + ' elements' +
+          (__keys ? ' (element keys: ' + __keys + ')' : '');
+      }
+      if (typeof __value === 'object' && __value !== null) {
+        return 'an object with keys: ' + Object.keys(__value).slice(0, 24).join(', ');
+      }
+      return 'a ' + typeof __value;
+    })();
+    let __preview = '';
+    try {
+      __preview = (__json !== undefined ? __json : String(__value)).slice(0, ${previewChars});
+    } catch {
+      // Leave the preview empty if the value cannot be stringified at all.
+    }
+    let __stashedAt = null;
+    ${stashSnippet}
+    return {
+      __dnbGuard: true,
+      oversized: true,
+      size: __json === undefined ? null : __json.length,
+      summary: __summary,
+      preview: __preview,
+      stashedAt: __stashedAt,
+    };
+  });
+})()`;
+    }
     /**
      * Returned true IFF the given error is a Playwright error regarding page closing,
      * of if the given error is an instance of {@link PageClosedException}.
@@ -297,6 +402,23 @@ class PlaywrightUtils {
     }
 }
 exports.PlaywrightUtils = PlaywrightUtils;
+/**
+ * Maximum serialized size (in JSON characters) of an evaluation result that
+ * {@link asSizeGuardedJavaScriptExpression} returns inline. Results above
+ * this go into the conversation history verbatim, so this bounds prompt
+ * growth per tool call.
+ */
+PlaywrightUtils.MAX_INLINE_RESULT_JSON_CHARS = 32_000;
+/**
+ * Number of characters of the serialized result included as a preview when
+ * a result is too large to return inline.
+ */
+PlaywrightUtils.OVERSIZED_RESULT_PREVIEW_CHARS = 2_000;
+/**
+ * Number of oversized results kept alive in the page via
+ * `window.__dnb_result_<n>` stash variables before the oldest is released.
+ */
+PlaywrightUtils.MAX_STASHED_RESULTS = 3;
 // Per-browser in-flight install promises — deduplicate concurrent requests.
 PlaywrightUtils._browserInstallPromises = new Map();
 //# sourceMappingURL=PlaywrightUtils.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "donobu",
-  "version": "5.60.0",
+  "version": "5.60.1",
   "description": "Create browser automations with an LLM agent and replay them as Playwright scripts.",
   "main": "dist/main.js",
   "module": "dist/esm/main.js",