donobu 5.33.0 → 5.35.0

package/dist/lib/ai/locate/locateElement.js

@@ -4,6 +4,7 @@ exports.locateElement = locateElement;
 const v4_1 = require("zod/v4");
 const Logger_1 = require("../../../utils/Logger");
 const PlaywrightUtils_1 = require("../../../utils/PlaywrightUtils");
+const TemplateInterpolator_1 = require("../../../utils/TemplateInterpolator");
 const buildLocator_1 = require("./buildLocator");
 const domSnapshot_1 = require("./domSnapshot");
 const LocateException_1 = require("./LocateException");
@@ -27,14 +28,15 @@ const SNIPPET_MAX_CHARS = 200;
  * callers can cache the result for deterministic replay.
  */
 async function locateElement(page, description, gptClient, options) {
+    const envData = options?.envData;
     const screenshot = await PlaywrightUtils_1.PlaywrightUtils.takeViewportScreenshot(page);
     const domSnapshot = await (0, domSnapshot_1.captureDomSnapshot)(page);
     Logger_1.appLogger.debug(`locate: DOM snapshot captured (${domSnapshot.html.length} chars, ${domSnapshot.omittedCount} nodes omitted)`);
-    const systemMessage = buildSystemMessage(page.url(), await page.title());
+    const systemMessage = buildSystemMessage(page.url(), await page.title(), description, envData);
     const userMessage = buildUserMessage(description, screenshot, domSnapshot.html);
     // First attempt
     const firstResult = await callLlm(gptClient, systemMessage, userMessage, options?.signal);
-    const firstLocator = (0, buildLocator_1.buildLocator)(page, firstResult);
+    const firstLocator = (0, buildLocator_1.buildLocator)(page, firstResult, envData);
     const firstCount = await safeCount(firstLocator);
     Logger_1.appLogger.debug(`locate: first attempt matched ${firstCount} element(s)`);
     if (firstCount === 1) {
@@ -42,7 +44,7 @@ async function locateElement(page, description, gptClient, options) {
     }
     // Disambiguation: small number of matches — show snippets and let LLM pick
     if (firstCount > 1 && firstCount <= DISAMBIGUATE_THRESHOLD) {
-        return await disambiguate(page, description, gptClient, firstLocator, firstResult, firstCount, options?.signal);
+        return await disambiguate(page, description, gptClient, firstLocator, firstResult, firstCount, envData, options?.signal);
     }
     // Retry: zero matches or too many
     const previousAttempt = summarizeLocateResult(firstResult);
@@ -58,14 +60,14 @@ async function locateElement(page, description, gptClient, options) {
         : `Your locator matched ${firstCount} elements, which is too many to disambiguate. Your previous attempt was: ${previousAttempt}. Write a more specific locator.`;
     const retryMessage = buildRetryMessage(description, feedback, screenshot, retryDomHtml);
     const retryResult = await callLlm(gptClient, systemMessage, retryMessage, options?.signal);
-    const retryLocator = (0, buildLocator_1.buildLocator)(page, retryResult);
+    const retryLocator = (0, buildLocator_1.buildLocator)(page, retryResult, envData);
     const retryCount = await safeCount(retryLocator);
     Logger_1.appLogger.debug(`locate: retry matched ${retryCount} element(s)`);
     if (retryCount === 1) {
         return { locator: retryLocator, result: retryResult };
     }
     if (retryCount > 1 && retryCount <= DISAMBIGUATE_THRESHOLD) {
-        return await disambiguate(page, description, gptClient, retryLocator, retryResult, retryCount, options?.signal);
+        return await disambiguate(page, description, gptClient, retryLocator, retryResult, retryCount, envData, options?.signal);
     }
     // Give up
     const reason = retryCount === 0 ? 'no_matches' : 'too_many_matches';
@@ -77,7 +79,7 @@ async function locateElement(page, description, gptClient, options) {
  * Show HTML snippets of each match to the LLM and ask it to pick the
  * correct one. Returns the original locator with `.nth(n)` appended.
  */
-async function disambiguate(page, description, gptClient, locator, locateResult, count, signal) {
+async function disambiguate(page, description, gptClient, locator, locateResult, count, envData, signal) {
     const snippets = [];
     for (let i = 0; i < count; i++) {
         const nth = locator.nth(i);
@@ -111,6 +113,12 @@ async function disambiguate(page, description, gptClient, locator, locateResult,
             .max(count - 1)
             .describe('Zero-based index of the element that best matches the description.'),
     });
+    // Disambiguation output is just an index — never cached and never fed back
+    // through `buildLocator`. Show the LLM the resolved description so it can
+    // match candidate HTML directly without doing mental env-var substitution.
+    const resolvedDescription = envData && description.includes('{{')
+        ? (0, TemplateInterpolator_1.interpolateString)(description, { env: envData, calls: [] })
+        : description;
     const systemMsg = {
         type: 'system',
         text: `You are resolving an ambiguous element lookup. The user described an element and your locator matched ${count} candidates. Choose the one that best matches the description.`,
@@ -120,7 +128,7 @@ async function disambiguate(page, description, gptClient, locator, locateResult,
         items: [
             {
                 type: 'text',
-                text: `Description: "${description}"\n\nCandidates:\n${snippetText}\n\nReturn the index of the best match.`,
+                text: `Description: "${resolvedDescription}"\n\nCandidates:\n${snippetText}\n\nReturn the index of the best match.`,
             },
         ],
     };
@@ -131,7 +139,7 @@ async function disambiguate(page, description, gptClient, locator, locateResult,
         nth: resp.output.index,
     };
     return {
-        locator: (0, buildLocator_1.buildLocator)(page, disambiguatedResult),
+        locator: (0, buildLocator_1.buildLocator)(page, disambiguatedResult, envData),
         result: disambiguatedResult,
     };
 }
@@ -139,7 +147,54 @@ async function callLlm(gptClient, systemMessage, userMessage, signal) {
     const resp = await gptClient.getStructuredOutput([systemMessage, userMessage], locateSchema_1.LocateResultSchema, { signal });
     return resp.output;
 }
-function buildSystemMessage(pageUrl, pageTitle) {
+function buildSystemMessage(pageUrl, pageTitle, description, envData) {
+    // Only annotate the prompt with env-var guidance when the raw description
+    // actually references at least one provided env var. Keeps the prompt small
+    // for the common case.
+    const envEntries = Object.entries(envData ?? {});
+    const referencedEnvEntries = envEntries.filter(([name]) => description.includes(`{{$.env.${name}}}`));
+    const envBlock = referencedEnvEntries.length > 0
+        ? `
+
+The user's description contains environment variable references using the syntax
+\`{{$.env.NAME}}\`. To keep cached locators valid across runs with different env
+values, you MUST emit those same placeholders in any LocatorStep \`text\`,
+\`name\`, or \`testId\` field whose contents come from an env var. Do NOT bake
+the literal current value into the step.
+
+Original (uninterpolated) description: "${description}"
+
+Current env mapping (use these to identify which substrings on the page came
+from which env var, then emit the placeholder rather than the literal):
+${referencedEnvEntries.map(([name, value]) => `  - {{$.env.${name}}} = ${JSON.stringify(value)}`).join('\n')}
+
+Hard rules for env-var emission:
+- Use placeholders ONLY in \`text\`, \`name\`, or \`testId\` fields.
+- NEVER emit \`{{$.env.*}}\` inside \`selector\` (CSS/XPath) — interpolating
+  raw values into a CSS selector can produce invalid syntax. Use a semantic
+  locator (getByRole/getByText/getByLabel/getByPlaceholder/getByTestId)
+  instead when an env-derived value is involved.
+- NEVER emit \`{{$.env.*}}\` inside any \`frames[]\` entry (iframe selectors
+  or iframe \`name\` attributes are not env-driven).
+
+Examples:
+- Description "The user row for {{$.env.TEST_EMAIL}}", TEST_EMAIL="alice@x.com",
+  page text shows "alice@x.com" →
+    [{ method: "getByText", text: "{{$.env.TEST_EMAIL}}" }]
+- Description "The {{$.env.PROJECT_NAME}} tab", PROJECT_NAME="Apollo" →
+    [{ method: "getByRole", role: "tab", name: "{{$.env.PROJECT_NAME}}" }]
+- Description "The submit button" (no env vars referenced) → emit literal text
+  as you normally would.
+
+Combining env vars with regex: env interpolation runs BEFORE regex compilation,
+so you can mix them. Prefer this when the env value should be matched alongside
+dynamic page content. Example — description "The row for {{$.env.USER}} with
+their score", USER="alice" →
+    [{ method: "getByText", text: "alice — \\\\d+ pts", textIsRegex: true }]
+  (Here the AI substituted the env value because it's part of a regex pattern;
+  the placeholder syntax also works — \`text: "{{$.env.USER}} — \\\\d+ pts"\` —
+  and is preferred when you want cache stability across env value changes.)`
+        : '';
     return {
         type: 'system',
         text: `You are a Playwright locator expert. Given a viewport screenshot and a pruned DOM snapshot of a webpage, return a structured locator that targets the element matching the user's description.
@@ -151,8 +206,50 @@ Rules:
 - If the element is inside an iframe, specify the frame(s) in the "frames" field.
 - Do NOT set "nth" unless you are certain the chain matches multiple elements and you know which index is correct. When unsure, omit it — the system will handle disambiguation.
 
+Stability rules — locators are CACHED and replayed across runs. The page may
+change between runs (vote counts increment, "3 hours ago" becomes "5 hours ago",
+new posts shift positions, prices fluctuate). Choose locators that survive these
+drifts:
+
+- POSITIONAL DESCRIPTIONS: when the description references position ("first",
+  "third", "fourth from the top", "last"), translate that into a structural
+  chain plus \`nth\` rather than baking position-specific page text into a step.
+  Example — "the fourth comments link" should be a locator over ALL comment
+  links with \`nth: 3\`, not the literal "36 comments" you happen to see today.
+
+- DYNAMIC TEXT: if the value you would put into \`name\` or \`text\` looks
+  dynamic — contains digits, timestamps, "X ago", "$X.XX", counts, scores,
+  vote totals — emit a regex pattern via \`nameIsRegex: true\` (for getByRole)
+  or \`textIsRegex: true\` (for getByText/getByLabel/getByPlaceholder) instead
+  of the literal value. Anchor the pattern with \`^\` / \`$\` when the whole
+  string should match, otherwise it acts as a substring match.
+
+- DO NOT combine \`exact: true\` with \`nameIsRegex\`/\`textIsRegex\`. They are
+  mutually exclusive — set \`exact\` only for literal-string steps with stable
+  fixed labels like "Submit" or "Sign In".
+
+- SAFE LITERALS: keep literal values for genuinely stable strings — fixed UI
+  labels, button text like "Submit"/"Cancel", section headings, unique
+  test-ids. Only escape to regex when stability is at risk.
+
+Examples:
+- "The fourth comments link" →
+    steps: [{ method: "getByRole", role: "link", name: "\\\\d+\\\\s+comments?$", nameIsRegex: true }]
+    nth: 3
+- "The headline of the third story" → structural row selector + nth: 2 (literal name)
+- "The submit button" → literal name: "Submit", optionally exact: true
+- "The price tag for the cart total" →
+    steps: [{ method: "getByText", text: "\\\\$\\\\d+(\\\\.\\\\d+)?", textIsRegex: true }]
+- "The 'posted 5 hours ago' label" →
+    steps: [{ method: "getByText", text: "posted \\\\d+ (minute|hour|day)s? ago", textIsRegex: true }]
+
+Regex format: emit a JS-style regex source string (no leading/trailing slash,
+no flags). Backslashes inside JSON must be doubled (\`\\\\d+\` not \`\\d+\`).
+Invalid patterns silently fall back to literal matching, so prefer simple,
+well-tested patterns.
+
 Page URL: ${pageUrl}
-Page title: ${pageTitle}`,
+Page title: ${pageTitle}${envBlock}`,
     };
 }
 function buildUserMessage(description, screenshot, domHtml) {

package/dist/lib/ai/locate/locateSchema.d.ts

@@ -27,6 +27,8 @@ export declare const LocateResultSchema: z.ZodObject<{
         testId: z.ZodOptional<z.ZodString>;
         selector: z.ZodOptional<z.ZodString>;
         exact: z.ZodOptional<z.ZodBoolean>;
+        nameIsRegex: z.ZodOptional<z.ZodBoolean>;
+        textIsRegex: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     nth: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;

package/dist/lib/ai/locate/locateSchema.js

@@ -46,7 +46,15 @@ const LocatorStepSchema = v4_1.z
     exact: v4_1.z
         .boolean()
         .optional()
-        .describe('Whether text/name matching should be exact. Applies to getByRole (name), getByText, getByLabel, getByPlaceholder.'),
+        .describe('Whether text/name matching should be exact. Applies to getByRole (name), getByText, getByLabel, getByPlaceholder. Mutually exclusive with nameIsRegex / textIsRegex.'),
+    nameIsRegex: v4_1.z
+        .boolean()
+        .optional()
+        .describe('Set true when "name" is a regex pattern (compiled via new RegExp(name)). Use this for dynamic accessible names — e.g. "\\d+ comments" matches any "N comments" link. Used with getByRole. Do not combine with exact:true.'),
+    textIsRegex: v4_1.z
+        .boolean()
+        .optional()
+        .describe('Set true when "text" is a regex pattern (compiled via new RegExp(text)). Use this for dynamic page text — counts, dates, prices, "X ago" timestamps. Used with getByText / getByLabel / getByPlaceholder. Do not combine with exact:true.'),
 })
     .describe('A single Playwright locator step.');
 const FrameStepSchema = v4_1.z

package/dist/lib/ai/locate/locateTypes.d.ts

@@ -20,6 +20,24 @@ export type LocatorStep = {
     selector?: string;
     /** Whether text/name matching should be exact. */
     exact?: boolean;
+    /**
+     * When true, `name` is treated as a regex pattern compiled via
+     * `new RegExp(name)` rather than a literal string. Mutually exclusive
+     * with `exact: true`. Used with `getByRole`.
+     *
+     * Env-var placeholders are interpolated **before** regex compilation, so
+     * `'\\d+ {{$.env.NOUN}}'` with `NOUN='comments'` compiles as
+     * `/\d+ comments/`.
+     */
+    nameIsRegex?: boolean;
+    /**
+     * When true, `text` is treated as a regex pattern compiled via
+     * `new RegExp(text)` rather than a literal string. Mutually exclusive with
+     * `exact: true`. Used with `getByText`, `getByLabel`, `getByPlaceholder`.
+     *
+     * Env-var placeholders are interpolated **before** regex compilation.
+     */
+    textIsRegex?: boolean;
 };
 /**
  * Identifies an iframe to scope into before applying {@link LocatorStep}s.
@@ -49,9 +67,48 @@ export type LocateResult = {
  */
 export type LocateOptions = {
     gptClient?: GptClient | Exclude<LanguageModel, string>;
-    /** Timeout in milliseconds for the entire locate operation (default: 30 000). */
+    /**
+     * Timeout in milliseconds for the entire locate operation (default: 30 000).
+     *
+     * On cache hit this budgets the hydration patience window — the cached
+     * locator gets up to this long to attach to a matching element before the
+     * cache is treated as stale and the AI is re-run. On cache miss (or
+     * stale-cache fallthrough) this budgets the AI call. Whatever the cache
+     * path consumes is deducted from the AI path's remaining budget; the total
+     * never exceeds `timeout`.
+     */
     timeout?: number;
-    /** Whether to use the on-disk cache. Defaults to true. */
+    /**
+     * Whether to use the on-disk cache. Defaults to true.
+     *
+     * Cached `LocateResult` step fields preserve `{{$.env.*}}` placeholders for
+     * any value that came from an env var, so changing an env value between
+     * runs replays the same cached locator with the new value rather than
+     * re-invoking the AI.
+     */
     cache?: boolean;
+    /**
+     * Explicit environment variable names (in addition to the heuristically
+     * derived ones) that the description may read via `{{$.env.*}}`
+     * interpolations.
+     */
+    envVars?: string[];
+    /**
+     * Explicitly supply environment variable values that amend (or override)
+     * the environment observed by this `page.ai.locate` call. Keys are merged
+     * with any names derived from {@link LocateOptions.envVars} and from
+     * `{{$.env.*}}` interpolations in the description.
+     *
+     * - A `string` value sets or overrides the variable for this invocation.
+     * - An `undefined` value *removes* the variable, even if it would
+     *   otherwise be resolved from persistence.
+     *
+     * Only the **names** (keys) influence cache lookup; changing a value
+     * replays the cached locator with the new value via `{{$.env.*}}`
+     * placeholder substitution rather than busting the cache. If a referenced
+     * env var is absent at replay, the placeholder is left literal — the
+     * locator will then match zero elements and fail loudly.
+     */
+    envVals?: Record<string, string | undefined>;
 };
 //# sourceMappingURL=locateTypes.d.ts.map

package/dist/lib/page/DonobuExtendedPage.d.ts

@@ -40,8 +40,32 @@ export type AssertOptions = {
      * and generates equivalent Playwright code which is cached. Subsequent
      * runs execute the cached code directly, skipping the AI call entirely.
      * Defaults to `true`.
+     *
+     * Cached steps preserve `{{$.env.*}}` placeholders for any value that came
+     * from an env var, so changing an env value between runs replays the same
+     * cached steps with the new value rather than re-invoking the AI.
      */
     cache?: boolean;
+    /**
+     * Explicit environment variable names (in addition to the heuristically
+     * derived ones) that the assertion may read via `{{$.env.*}}` interpolations.
+     */
+    envVars?: string[];
+    /**
+     * Explicitly supply environment variable values that amend (or override)
+     * the environment observed by this `page.ai.assert` call. Keys are merged
+     * with any names derived from {@link AssertOptions.envVars} and from
+     * `{{$.env.*}}` interpolations in the assertion text.
+     *
+     * - A `string` value sets or overrides the variable for this invocation.
+     * - An `undefined` value *removes* the variable, even if it would
+     *   otherwise be resolved from persistence.
+     *
+     * Only the **names** (keys) influence cache lookup; changing a value
+     * replays the cached steps with the new value via `{{$.env.*}}` placeholder
+     * substitution rather than busting the cache.
+     */
+    envVals?: Record<string, string | undefined>;
 };
 type PageAiAct = {
     <Schema extends z.ZodObject>(instruction: string, options?: PageAiActWithSchemaOptions<Schema>): Promise<z.infer<Schema>>;

package/dist/lib/page/extendPage.js

@@ -10,6 +10,7 @@ const GptApiKeysNotSetupException_1 = require("../../exceptions/GptApiKeysNotSet
 const TestNotFoundException_1 = require("../../exceptions/TestNotFoundException");
 const ToolCallFailedException_1 = require("../../exceptions/ToolCallFailedException");
 const ToolRequiresGptException_1 = require("../../exceptions/ToolRequiresGptException");
+const DonobuFlowsManager_1 = require("../../managers/DonobuFlowsManager");
 const InteractionVisualizer_1 = require("../../managers/InteractionVisualizer");
 const ToolManager_1 = require("../../managers/ToolManager");
 const WebTargetInspector_1 = require("../../managers/WebTargetInspector");
@@ -220,6 +221,33 @@ Valid options:
             const clearCache = sharedState.runtimeDirectives?.clearPageAiCache ?? false;
             const retries = options?.retries ?? 0;
             const retryDelaySeconds = options?.retryDelaySeconds ?? 3;
+            // Distill env var names from `{{$.env.*}}` interpolations in the
+            // assertion plus any explicitly provided names/overrides. Cached
+            // Playwright steps may carry the same `{{$.env.X}}` placeholders in
+            // their `value`/`attributeValue` fields, so we resolve env data at
+            // replay time and let the executor interpolate before applying.
+            const envVarNames = (0, DonobuFlowsManager_1.distillAllowedEnvVariableNames)(assertion, [
+                ...(options?.envVars ?? []),
+                ...Object.keys(options?.envVals ?? {}),
+            ]);
+            const hasEnvRefs = envVarNames.length > 0;
+            const resolveEnvData = async () => {
+                if (!hasEnvRefs) {
+                    return undefined;
+                }
+                const envData = await sharedState.donobuStack.envDataManager.getByNames(envVarNames);
+                if (options?.envVals) {
+                    for (const [k, v] of Object.entries(options.envVals)) {
+                        if (v === undefined) {
+                            delete envData[k];
+                        }
+                        else {
+                            envData[k] = v;
+                        }
+                    }
+                }
+                return envData;
+            };
             // --- Cache lookup (when enabled and not clearing) ---
             if (useCache && !clearCache) {
                 const cache = getOrInitPageAiCache();
@@ -227,6 +255,7 @@ Valid options:
                 const cached = await cache.getAssert({ pageUrl, assertion });
                 if (cached) {
                     Logger_1.appLogger.debug(`Assert cache HIT for: "${assertion}" - running cached Playwright assertion`);
+                    const envData = await resolveEnvData();
                     let lastError = null;
                     for (let attempt = 0; attempt <= retries; attempt++) {
                         if (attempt > 0) {
@@ -234,7 +263,7 @@ Valid options:
                             await page.waitForTimeout(retryDelaySeconds * 1000);
                         }
                         try {
-                            await cached.run({ page });
+                            await cached.run({ page, envData });
                             return; // Assertion passed
                         }
                         catch (error) {
@@ -263,12 +292,28 @@ Valid options:
                 await cache.deleteAssert({ pageUrl, assertion });
                 Logger_1.appLogger.debug(`Assert cache invalidated for: "${assertion}"`);
             }
-            // --- Cache miss or cache disabled: run AI assertion ---
-            const result = await runTool(page, AssertTool_1.AssertTool.NAME, {
-                assertionToTestFor: assertion,
-                retries: options?.retries,
-                retryWaitSeconds: options?.retryDelaySeconds,
-            }, options?.gptClient);
+            // Make env vars available to runTool's envData for `{{$.env.*}}`
+            // interpolation inside `assertionToTestFor` and so AssertTool can
+            // instruct the AI to emit placeholders in cached step values. Mirrors
+            // PageAi.ai for `act`: metadata.envVars is set (overwriting), envVals
+            // is restored.
+            if (hasEnvRefs) {
+                sharedState.donobuFlowMetadata.envVars = envVarNames;
+            }
+            const previousEnvVals = sharedState.envVals;
+            sharedState.envVals = options?.envVals;
+            let result;
+            try {
+                // --- Cache miss or cache disabled: run AI assertion ---
+                result = await runTool(page, AssertTool_1.AssertTool.NAME, {
+                    assertionToTestFor: assertion,
+                    retries: options?.retries,
+                    retryWaitSeconds: options?.retryDelaySeconds,
+                }, options?.gptClient);
+            }
+            finally {
+                sharedState.envVals = previousEnvVals;
+            }
             if (!result.outcome.isSuccessful) {
                 throw new ToolCallFailedException_1.ToolCallFailedException(AssertTool_1.AssertTool.NAME, result.outcome);
             }
@@ -363,33 +408,86 @@ Use this information to return an appropriate JSON object.`,
             const useCache = options?.cache !== false;
             const clearCache = sharedState.runtimeDirectives?.clearPageAiCache ?? false;
             const pageUrl = (0, cacheLocator_1.extractCacheKeyHostname)(page.url());
-            // --- Cache lookup (when enabled and not clearing) ---
-            if (useCache && !clearCache) {
-                const cache = getOrInitPageAiCache();
-                const cached = await cache.getLocate({ pageUrl, description });
-                if (cached) {
-                    Logger_1.appLogger.debug(`Locate cache HIT for: "${description}" — rebuilding locator from cache`);
-                    return cached.run({ page });
+            // Distill env var names referenced by the description plus any
+            // explicitly provided names/overrides. Resolve env data locally — locate
+            // does not flow through `runTool`, so we don't mutate sharedState here.
+            const envVarNames = (0, DonobuFlowsManager_1.distillAllowedEnvVariableNames)(description, [
+                ...(options?.envVars ?? []),
+                ...Object.keys(options?.envVals ?? {}),
+            ]);
+            const hasEnvRefs = envVarNames.length > 0;
+            const resolveEnvData = async () => {
+                if (!hasEnvRefs) {
+                    return undefined;
                 }
-            }
-            // --- Cache invalidation (when clearing) ---
-            if (useCache && clearCache) {
-                const cache = getOrInitPageAiCache();
-                await cache.deleteLocate({ pageUrl, description });
-                Logger_1.appLogger.debug(`Locate cache invalidated for: "${description}"`);
-            }
-            // --- Cache miss or cache disabled: run AI locate ---
-            const gptClient = getGptClient(page, options?.gptClient);
-            if (!gptClient) {
-                throw new ToolRequiresGptException_1.ToolRequiresGptException('locate');
-            }
+                const envData = await sharedState.donobuStack.envDataManager.getByNames(envVarNames);
+                if (options?.envVals) {
+                    for (const [k, v] of Object.entries(options.envVals)) {
+                        if (v === undefined) {
+                            delete envData[k];
+                        }
+                        else {
+                            envData[k] = v;
+                        }
+                    }
+                }
+                return envData;
+            };
+            // The user-supplied `timeout` (default 30s) is the budget for the
+            // ENTIRE locate operation — cache-hit hydration wait + AI fallback.
+            // We start the abort timer here so the cache path's `waitFor` and the
+            // AI path share one bounded clock.
             const timeoutMillis = options?.timeout ?? 30_000;
+            const startedAt = Date.now();
             const abortController = new AbortController();
             const timeoutId = setTimeout(() => {
                 abortController.abort(`Locate operation timed out after ${timeoutMillis} milliseconds`);
             }, timeoutMillis);
             try {
-                const { locator, result } = await (0, locateElement_1.locateElement)(page, description, gptClient, { signal: abortController.signal });
+                // --- Cache lookup (when enabled and not clearing) ---
+                if (useCache && !clearCache) {
+                    const cache = getOrInitPageAiCache();
+                    const cached = await cache.getLocate({ pageUrl, description });
+                    if (cached) {
+                        const envData = await resolveEnvData();
+                        const candidate = cached.run({ page, envData });
+                        // Cache replay can outrun page hydration — the no-cache path
+                        // gets an implicit hydration window from the AI round-trip
+                        // latency, but a cache hit fires immediately and may see a
+                        // partially-mounted DOM. Wait (within the operation's overall
+                        // budget) for the locator to attach before validating.
+                        const remaining = Math.max(timeoutMillis - (Date.now() - startedAt), 100);
+                        try {
+                            await candidate.first().waitFor({
+                                state: 'attached',
+                                timeout: remaining,
+                            });
+                            Logger_1.appLogger.debug(`Locate cache HIT for: "${description}" — rebuilt locator from cache`);
+                            return candidate;
+                        }
+                        catch {
+                            // Locator did not attach within the patience window. Either
+                            // the page has drifted or the cache is genuinely stale.
+                            // Invalidate and fall through to the AI path; the AI call
+                            // gets whatever budget remains on the abort timer.
+                            Logger_1.appLogger.debug(`Locate cache STALE for "${description}" (no match within ${remaining}ms) — re-running AI`);
+                            await cache.deleteLocate({ pageUrl, description });
+                        }
+                    }
+                }
+                // --- Cache invalidation (when clearing) ---
+                if (useCache && clearCache) {
+                    const cache = getOrInitPageAiCache();
+                    await cache.deleteLocate({ pageUrl, description });
+                    Logger_1.appLogger.debug(`Locate cache invalidated for: "${description}"`);
+                }
+                // --- Cache miss / cache disabled / stale-cache fallthrough: run AI ---
+                const gptClient = getGptClient(page, options?.gptClient);
+                if (!gptClient) {
+                    throw new ToolRequiresGptException_1.ToolRequiresGptException('locate');
+                }
+                const envData = await resolveEnvData();
+                const { locator, result } = await (0, locateElement_1.locateElement)(page, description, gptClient, { signal: abortController.signal, envData });
                 // --- Cache the result for future runs ---
                 if (useCache) {
                     try {

package/dist/managers/ToolManager.js

@@ -87,6 +87,9 @@ class ToolManager {
                     startedAt: startedAt,
                     completedAt: null,
                 });
+                // Expose the un-interpolated parameters so tools that need to
+                // preserve `{{...}}` references (e.g. AssertTool) can read them.
+                context.rawParameters = toolParameters;
                 // Use the interpolated parameters when calling the tool.
                 toolCallResult = isFromGpt
                     ? await tool.callFromGpt(context, tool.inputSchemaForGpt.parse(interpolatedParameters))

package/dist/models/ToolCallContext.d.ts

@@ -22,5 +22,16 @@ export type ToolCallContext = {
     readonly invokedToolCalls: ToolCall[];
     readonly metadata: FlowMetadata;
     readonly toolCallId: string;
+    /**
+     * Original (un-interpolated) parameters supplied to the current tool call.
+     *
+     * `ToolManager.invokeTool` interpolates `{{...}}` expressions in the tool's
+     * parameters before invoking the tool, but a tool may need the raw text to
+     * preserve env var references in its output (e.g. `AssertTool` emits
+     * Playwright steps that retain `{{$.env.X}}` so cached replays stay correct
+     * across env value changes). Set by `ToolManager` immediately before the
+     * tool runs; absent for direct/legacy invocation paths.
+     */
+    rawParameters?: Record<string, any>;
 };
 //# sourceMappingURL=ToolCallContext.d.ts.map

package/dist/tools/AssertTool.js

@@ -124,6 +124,36 @@ It will use a screenshot of the current viewport of the webpage, the webpage's t
                 Logger_1.appLogger.warn(msg);
                 return msg;
             });
+            const rawAssertion = typeof context.rawParameters?.assertionToTestFor === 'string'
+                ? context.rawParameters.assertionToTestFor
+                : parameters.assertionToTestFor;
+            const envEntries = Object.entries(context.envData ?? {});
+            // Only treat env vars as "in play" when the raw assertion actually
+            // references one — keeps the prompt small for the common case.
+            const referencedEnvEntries = envEntries.filter(([name]) => rawAssertion.includes(`{{$.env.${name}}}`));
+            const hasEnvRefs = referencedEnvEntries.length > 0;
+            const envBlock = hasEnvRefs
+                ? `
+
+The user's original assertion contains environment variable references using the
+syntax \`{{$.env.NAME}}\`. To keep cached Playwright steps valid across runs with
+different env values, you MUST emit those same placeholders in any
+playwrightAssertionStep \`value\`/\`attributeValue\` field whose contents come from
+an env var. Do NOT bake the literal current value into the step.
+
+Original (uninterpolated) assertion: ${rawAssertion}
+
+Current env mapping (use these to identify which substrings on the page came
+from which env var, then emit the placeholder rather than the literal):
+${referencedEnvEntries.map(([name, value]) => `  - {{$.env.${name}}} = ${JSON.stringify(value)}`).join('\n')}
+
+Examples:
+- Raw assertion "Welcome banner says hello {{$.env.USERNAME}}", USERNAME="alice", page shows "Welcome alice" →
+    [{ locator: "text", role: null, value: "{{$.env.USERNAME}}", valueIsRegex: false, assertion: "toBeVisible", attributeValue: null }]
+- Raw assertion "The username field shows {{$.env.USERNAME}}", USERNAME="alice", page input value is "alice" →
+    [{ locator: "label", role: null, value: "Username", valueIsRegex: false, assertion: "toHaveValue", attributeValue: "{{$.env.USERNAME}}" }]
+- For literal page text unrelated to env vars, keep the literal value as usual.`
+                : '';
             const promptMessages = [
                 {
                     type: 'system',
@@ -142,7 +172,7 @@ CRITICAL RULES for generating structured steps — follow these precisely:
 - Text input / textarea content: use 'toHaveValue' with locator='label' and set attributeValue to the expected text. Do NOT use 'toBeVisible' on the textbox.
 - Selected tabs, pills, or items with aria-selected: use 'toHaveAttribute' with value='aria-selected' and attributeValue='true', NOT 'toBeVisible' on the text.
 - Text content within an element: use 'toContainText' with attributeValue set to the substring, NOT 'toBeVisible'.
-- Only use 'toBeVisible' when the assertion is genuinely about whether something is visible — not as a fallback for state or value checks.`,
+- Only use 'toBeVisible' when the assertion is genuinely about whether something is visible — not as a fallback for state or value checks.${envBlock}`,
                 },
                 {
                     type: 'user',
@@ -184,7 +214,7 @@ careful positioning lost, etc. A screenshot of the webpage has also been provide
                 verifiedSteps.length > 0) {
                 try {
                     const executor = (0, assertCache_1.buildAssertExecutor)(verifiedSteps);
-                    await executor({ page: page });
+                    await executor({ page: page, envData: context.envData });
                 }
                 catch (error) {
                     Logger_1.appLogger.debug(`Structured assertion steps failed verification for: "${parameters.assertionToTestFor}" — discarding steps. Error: ${error.message}`);

package/package.json

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