@enricai/barnacle 1.9.1 → 1.9.3

package/dist/scraper/flow-runner.js

@@ -2393,11 +2393,21 @@ async function fillTextDatepickerInput(target, selector, value) {
  * Returns null for non-fillable elements (clicks, selects, etc.) — caller
  * knows to skip the check.
  *
+ * Accepts any selector a call site holds: Stagehand's `xpath=…`, an
+ * already-stripped bare XPath, or a non-xpath form (`deeplocator=…`,
+ * `deep-index:N`). Non-xpath forms can't be read via `document.evaluate`, so
+ * the selector is normalized through {@link xpathBodyForEvaluate} and a form
+ * this reader can't resolve returns null (same "couldn't verify — skip" contract
+ * as a non-fillable element) rather than evaluating an invalid XPath expression.
+ *
  * Site-agnostic: works on any <input>, <textarea>, or [contenteditable]
  * element regardless of framework wrapping. Industry-standard pattern
  * (react-testing-library's `getByDisplayValue` does the same readback).
  */
-async function verifyFillReadback(target, xpath, expectedValue) {
+async function verifyFillReadback(target, selector, expectedValue) {
+    const xpath = xpathBodyForEvaluate(selector);
+    if (xpath === null)
+        return null;
     const expr = `(() => {
     const xpath = ${JSON.stringify(xpath)};
     const expected = ${JSON.stringify(expectedValue)};
@@ -2518,6 +2528,22 @@ const STATE_CLASS_METHODS = new Set([
 function xpathBody(selector) {
     return selector.startsWith("xpath=") ? selector.slice("xpath=".length) : null;
 }
+/**
+ * Resolve any selector a caller might hold into a bare XPath body for
+ * `document.evaluate`. `verifyFillReadback` is shared across call sites that
+ * carry different selector forms — Stagehand's `xpath=…` (act path), an
+ * already-stripped body (the datepicker primitive's internal readback), and
+ * non-xpath forms like `deeplocator=… >> nth=N` / `deep-index:N` (deep-locator
+ * cascades) — so a single `xpath=`-strip is insufficient and feeding a
+ * prefixed string straight to `document.evaluate` yields an invalid expression.
+ * Accepts an `xpath=`-prefixed selector or a bare XPath (starts with `/` or
+ * `(`); returns null for every other form so the reader resolves nothing rather
+ * than evaluating garbage.
+ */
+function xpathBodyForEvaluate(selector) {
+    const stripped = selector.startsWith("xpath=") ? selector.slice("xpath=".length) : selector;
+    return stripped.startsWith("/") || stripped.startsWith("(") ? stripped : null;
+}
 /** How long the upload primitive waits for a post-setInputFiles network POST. */
 const UPLOAD_NETWORK_TIMEOUT_MS = 5_000;
 /** Polling interval while waiting for the upload's network signal. */
@@ -3046,23 +3072,31 @@ function parseFillStep(instruction) {
  * canonical `<label> field with '<value>'` shape, so real-world prose that
  * inserts words between the field noun and `with` — e.g. "Fill in the Start
  * Date field FOR WORK EXPERIENCE with '01/2020'" — parses to `null`, missing
- * the fill intent entirely. This looser parser recognizes a fill verb plus a
- * `with '<value>'` clause and returns just the value, so the act-success
- * datepicker guard can key off intent that survives that phrasing drift.
+ * the fill intent entirely. This looser parser recognizes a value-carrying
+ * entry verb and returns just the value, so the act-success datepicker guard
+ * can key off intent that survives that phrasing drift. Two shapes are
+ * accepted: `fill … with '<value>'` and the replanner's own escalation
+ * `type '<value>' into …` — the replanner rewords a stuck date fill as
+ * "Type '01/2020' into the Start Date input", which carries no `fill` verb, so
+ * without the `type` shape the guard could never fire on any replanned step.
  *
  * Deliberately excludes select steps (checked first, mirroring
  * `resolveDeepLocatorActuation`'s precedence) so a `select '…'` step whose
  * prose happens to trail a quoted value is never mistaken for a fill. Returns
- * `null` for clicks, selects, and any step without a quoted `with '…'` value.
+ * `null` for clicks, selects, and any step without a quoted value.
  */
 function parseFillValueIntent(instruction) {
     if (parseSelectStep(instruction))
         return null;
-    if (!/\bfill(?:\s+in)?\b/i.test(instruction))
-        return null;
-    const match = instruction.match(/\bwith\s+'([^']+)'/i);
-    const value = match?.[1]?.trim();
-    return value ? { value } : null;
+    if (/\bfill(?:\s+in)?\b/i.test(instruction)) {
+        const value = instruction.match(/\bwith\s+'([^']+)'/i)?.[1]?.trim();
+        return value ? { value } : null;
+    }
+    if (/\btype\b/i.test(instruction)) {
+        const value = instruction.match(/\btype\s+'([^']+)'/i)?.[1]?.trim();
+        return value ? { value } : null;
+    }
+    return null;
 }
 /**
  * Parse a single-choice RADIO flow step into the option to click and (when
@@ -3316,11 +3350,17 @@ async function applySelectValue(page, target, selIdx, value) {
     const stillInvalid = (await target.evaluate(invalidExpr).catch(() => false));
     return { ok: true, stillInvalid };
 }
+/**
+ * Returns the resolved `<select>`'s DOM id on success (empty string when the
+ * element has no id), or `null` when the step wasn't handled here (no matching
+ * select, no commit) and should fall through to the cascade. The id becomes the
+ * step's stable `targetId` for cross-run convergence.
+ */
 async function trySelectPrimitive(params) {
     const { page, target, instruction, logger, anthropic, captureFn } = params;
     const parsed = parseSelectStep(instruction);
     if (!parsed)
-        return false;
+        return null;
     const { option, questionLabel } = parsed;
     const optLabel = `option "${option.slice(0, 40)}"${questionLabel ? `, question "${questionLabel.slice(0, 40)}"` : ""}`;
     // Phase 1 (browser, no mutation): find the target select — the one whose
@@ -3349,7 +3389,7 @@ async function trySelectPrimitive(params) {
     for (let i = 0; i < selects.length; i++) {
       const opts = Array.from(selects[i].options || []);
       const m = opts.find((o) => norm(o.textContent) === wantOpt || norm(o.value) === wantOpt);
-      if (m) detMatches.push({ selIdx: i, value: m.value, text: m.textContent });
+      if (m) detMatches.push({ selIdx: i, value: m.value, text: m.textContent, id: selects[i].id || "" });
     }
     if (detMatches.length === 1) {
       return { selectPresent: true, detMatch: detMatches[0] };
@@ -3394,7 +3434,7 @@ async function trySelectPrimitive(params) {
       const options = Array.from(sel.options || [])
         .filter((o) => !o.disabled && (o.value || (o.textContent || "").trim()))
         .map((o) => ({ text: (o.textContent || "").replace(/\\s+/g, " ").trim(), value: o.value }));
-      if (options.length > 0) candidates.push({ selIdx: i, label: selLabelText(sel), options });
+      if (options.length > 0) candidates.push({ selIdx: i, id: sel.id || "", label: selLabelText(sel), options });
     }
     if (candidates.length === 0) return { selectPresent: true, candidates: [] };
     return { selectPresent: true, candidates };
@@ -3407,7 +3447,7 @@ async function trySelectPrimitive(params) {
         // fall through to the cascade unchanged; the LLM picker can't help here.
         if (!enumResult?.selectPresent) {
             logger.info(`select primitive: no <select> on page for ${optLabel}; falling through to cascade`);
-            return false;
+            return null;
         }
         // Deterministic unique-option match: set it, settle, and confirm it committed
         // (cleared the required/invalid marker). A set that doesn't clear the marker
@@ -3417,15 +3457,15 @@ async function trySelectPrimitive(params) {
             const { ok, stillInvalid } = await applySelectValue(page, target, enumResult.detMatch.selIdx, enumResult.detMatch.value);
             if (ok && !stillInvalid) {
                 logger.info(`select primitive: set dropdown to "${enumResult.detMatch.text.trim().slice(0, 40)}" (${optLabel})`);
-                return true;
+                return enumResult.detMatch.id;
             }
             logger.info(`select primitive: dropdown value for ${optLabel} did not commit (ok=${ok} stillInvalid=${stillInvalid}); falling through to cascade`);
-            return false;
+            return null;
         }
         const candidates = enumResult.candidates ?? [];
         if (anthropic === null || candidates.length === 0) {
             logger.info(`select primitive: no unique option match for ${optLabel}${anthropic === null ? " (no LLM client)" : ""}; falling through to cascade`);
-            return false;
+            return null;
         }
         // LLM picks WHICH dropdown answers the question and which option in it.
         const verdict = await (0, select_option_1.judgeSelectOptionWithLLM)({
@@ -3442,7 +3482,7 @@ async function trySelectPrimitive(params) {
         });
         if (!verdict || verdict.selectIndex === null || verdict.optionIndex === null) {
             logger.info(`select primitive: LLM found no matching dropdown for ${optLabel}${verdict ? ` (${verdict.reason})` : ""}; falling through to cascade`);
-            return false;
+            return null;
         }
         // biome-ignore lint/style/noNonNullAssertion: guarded above by the verdict.selectIndex === null early-return
         const chosenCandidate = candidates[verdict.selectIndex];
@@ -3454,14 +3494,14 @@ async function trySelectPrimitive(params) {
         const { ok, stillInvalid } = await applySelectValue(page, target, chosenCandidate.selIdx, chosenOption.value);
         if (ok && !stillInvalid) {
             logger.info(`select primitive: LLM chose "${chosenOption.text.slice(0, 40)}" for ${optLabel} (${verdict.reason.slice(0, 60)})`);
-            return true;
+            return chosenCandidate.id;
         }
         logger.info(`select primitive: LLM-chosen value for ${optLabel} did not commit (ok=${ok} stillInvalid=${stillInvalid}); falling through`);
-        return false;
+        return null;
     }
     catch (err) {
         logger.warn(`select primitive: evaluate threw: ${(0, errors_1.toErrorMessage)(err)}; falling through`);
-        return false;
+        return null;
     }
 }
 /** Option texts that answer a required select without volunteering info — used
@@ -3645,11 +3685,16 @@ async function tryFillRequiredSelectsPrimitive(params) {
  * no checkbox groups, or no option fits (fall through to the cascade — which is
  * also where `<select>`-only pages go, since trySelectPrimitive runs first).
  */
+/**
+ * Returns the resolved checkbox's DOM id on success (empty string when it has
+ * no id), or `null` when the step wasn't handled here. See trySelectPrimitive
+ * for the id-as-targetId rationale.
+ */
 async function tryCheckboxPrimitive(params) {
     const { page, target, instruction, logger, anthropic, captureFn } = params;
     const parsed = parseSelectStep(instruction);
     if (!parsed)
-        return false;
+        return null;
     const { option, questionLabel } = parsed;
     const optLabel = `option "${option.slice(0, 40)}"${questionLabel ? `, question "${questionLabel.slice(0, 40)}"` : ""}`;
     // Phase 1 (browser, no mutation): find checkbox GROUPS and their options.
@@ -3723,7 +3768,7 @@ async function tryCheckboxPrimitive(params) {
       const grpEl = groupEls[h.gi];
       const cb = grpEl.querySelectorAll("input[type=checkbox]")[h.bi];
       const ok = cb ? setChecked(cb) : false;
-      return { groupPresent: true, applied: true, ok, chosen: h.text };
+      return { groupPresent: true, applied: true, ok, chosen: h.text, id: cb ? (cb.id || "") : "" };
     }
     // LLM path: return groups (label + option texts) for the picker.
     return { groupPresent: true, applied: false, groups: groups.map((g) => ({ gi: g.gi, label: g.label, options: g.options })) };
@@ -3733,15 +3778,15 @@ async function tryCheckboxPrimitive(params) {
         // (SPA render-lag); poll until it appears or the cap is hit.
         const enumResult = await pollEnumerate(page, target, enumerateExpr, (r) => r?.groupPresent === true);
         if (!enumResult?.groupPresent)
-            return false; // no checkbox groups → cascade
+            return null; // no checkbox groups → cascade
         if (enumResult.applied && enumResult.ok) {
             logger.info(`checkbox primitive: checked "${(enumResult.chosen || "").trim().slice(0, 40)}" (${optLabel})`);
-            return true;
+            return enumResult.id ?? "";
         }
         const groups = enumResult.groups ?? [];
         if (anthropic === null || groups.length === 0) {
             logger.info(`checkbox primitive: no unique option match for ${optLabel}${anthropic === null ? " (no LLM client)" : ""}; falling through to cascade`);
-            return false;
+            return null;
         }
         // LLM picks which group answers the question + which option. Reuse the
         // select-option judge (candidate "dropdowns" == checkbox groups here).
@@ -3759,7 +3804,7 @@ async function tryCheckboxPrimitive(params) {
         });
         if (!verdict || verdict.selectIndex === null || verdict.optionIndex === null) {
             logger.info(`checkbox primitive: LLM found no matching group for ${optLabel}${verdict ? ` (${verdict.reason})` : ""}; falling through to cascade`);
-            return false;
+            return null;
         }
         // biome-ignore lint/style/noNonNullAssertion: guarded above by the verdict.selectIndex === null early-return
         const chosenGroup = groups[verdict.selectIndex];
@@ -3778,19 +3823,19 @@ async function tryCheckboxPrimitive(params) {
         cb.dispatchEvent(new Event("input", { bubbles: true }));
         cb.dispatchEvent(new Event("change", { bubbles: true }));
       }
-      return { ok: cb.checked === true };
+      return { ok: cb.checked === true, id: cb.id || "" };
     })(${JSON.stringify(chosenGroup.gi)}, ${JSON.stringify(chosenOption.bi)})`;
         const applyResult = (await target.evaluate(applyExpr));
         if (applyResult?.ok) {
             logger.info(`checkbox primitive: LLM checked "${chosenOption.text.slice(0, 40)}" for ${optLabel} (${verdict.reason.slice(0, 60)})`);
-            return true;
+            return applyResult.id;
         }
         logger.info(`checkbox primitive: LLM-chosen checkbox did not stick for ${optLabel}; falling through`);
-        return false;
+        return null;
     }
     catch (err) {
         logger.warn(`checkbox primitive: evaluate threw: ${(0, errors_1.toErrorMessage)(err)}; falling through`);
-        return false;
+        return null;
     }
 }
 /**
@@ -3976,7 +4021,7 @@ async function tryRadioPrimitive(params) {
     const { page, target, instruction, logger, anthropic, captureFn } = params;
     const parsed = parseRadioStep(instruction);
     if (!parsed)
-        return false;
+        return null;
     const { option, questionLabel } = parsed;
     const optLabel = `option "${option.slice(0, 40)}"${questionLabel ? `, question "${questionLabel.slice(0, 40)}"` : ""}`;
     // Phase 1 (browser): find radio GROUPS and their options. A group is a
@@ -4048,10 +4093,10 @@ async function tryRadioPrimitive(params) {
     try {
         const enumResult = await pollEnumerate(page, target, enumerateExpr, (r) => r?.groupPresent === true);
         if (!enumResult?.groupPresent)
-            return false; // no radio group → cascade
+            return null; // no radio group → cascade
         const groups = enumResult.groups ?? [];
         if (groups.length === 0)
-            return false;
+            return null;
         // Deterministic + positional selection (excludes already-answered groups,
         // fixes the empty-label universal-match bug). Only genuine labeled ambiguity
         // defers to the LLM.
@@ -4064,19 +4109,19 @@ async function tryRadioPrimitive(params) {
             });
             if (applied) {
                 logger.info(`radio primitive: selected "${(chosenOpt?.text ?? "").trim().slice(0, 40)}" (${optLabel})`);
-                return true;
+                return chosenOpt?.id ?? "";
             }
             logger.info(`radio primitive: chosen radio did not stick for ${optLabel}; falling through`);
-            return false;
+            return null;
         }
         if (selection === null) {
             logger.info(`radio primitive: no group offers option for ${optLabel}; falling through to cascade`);
-            return false;
+            return null;
         }
         // selection === "ambiguous": multiple labeled groups match → let the LLM pick.
         if (anthropic === null) {
             logger.info(`radio primitive: ambiguous labeled match for ${optLabel} (no LLM client); falling through to cascade`);
-            return false;
+            return null;
         }
         // LLM picks which group answers the question + which option. Reuse the
         // select-option judge (candidate "dropdowns" == radio groups here). Only
@@ -4096,7 +4141,7 @@ async function tryRadioPrimitive(params) {
         });
         if (!verdict || verdict.selectIndex === null || verdict.optionIndex === null) {
             logger.info(`radio primitive: LLM found no matching group for ${optLabel}${verdict ? ` (${verdict.reason})` : ""}; falling through to cascade`);
-            return false;
+            return null;
         }
         // biome-ignore lint/style/noNonNullAssertion: guarded above by the verdict.selectIndex === null early-return
         const chosenGroup = llmGroups[verdict.selectIndex];
@@ -4110,14 +4155,14 @@ async function tryRadioPrimitive(params) {
         };
         if (applyResult?.ok) {
             logger.info(`radio primitive: LLM selected "${chosenOption.text.slice(0, 40)}" for ${optLabel} (${verdict.reason.slice(0, 60)})`);
-            return true;
+            return chosenOption.id ?? "";
         }
         logger.info(`radio primitive: LLM-chosen radio did not stick for ${optLabel}; falling through`);
-        return false;
+        return null;
     }
     catch (err) {
         logger.warn(`radio primitive: evaluate threw: ${(0, errors_1.toErrorMessage)(err)}; falling through`);
-        return false;
+        return null;
     }
 }
 /**
@@ -5152,16 +5197,17 @@ async function executeStepWithHealing(params) {
     // falls back to the main-frame target when no frameSelector is set, so this
     // bridge stays behavior-identical for every existing site.
     const selectFrameTarget = frameTarget ?? (0, frame_target_1.mainFrameTarget)(page);
-    if (await trySelectPrimitive({
+    const selectTargetId = await trySelectPrimitive({
         page,
         target: selectFrameTarget,
         instruction: step,
         logger,
         anthropic,
         captureFn,
-    })) {
+    });
+    if (selectTargetId !== null) {
         logger.info(`${formatStepPrefix(stepIndex, totalSteps)} resolved by select primitive`);
-        trajectory?.push({ stepIndex, verifiedBy: "dom" });
+        trajectory?.push({ stepIndex, verifiedBy: "dom", targetId: selectTargetId });
         return "completed";
     }
     // When the step is a "select 'X'" against a multi-select CHECKBOX group
@@ -5169,16 +5215,17 @@ async function executeStepWithHealing(params) {
     // screening questions this way — answer it directly in the DOM. Runs AFTER
     // trySelectPrimitive (which handles <select> and no-ops on checkbox-only
     // pages). No-op (falls through) when there's no checkbox group or no match.
-    if (await tryCheckboxPrimitive({
+    const checkboxTargetId = await tryCheckboxPrimitive({
         page,
         target: selectFrameTarget,
         instruction: step,
         logger,
         anthropic,
         captureFn,
-    })) {
+    });
+    if (checkboxTargetId !== null) {
         logger.info(`${formatStepPrefix(stepIndex, totalSteps)} resolved by checkbox primitive`);
-        trajectory?.push({ stepIndex, verifiedBy: "dom" });
+        trajectory?.push({ stepIndex, verifiedBy: "dom", targetId: checkboxTargetId });
         return "completed";
     }
     // When the step is a single-choice RADIO answer ("Click the 'Yes' answer for
@@ -5187,16 +5234,17 @@ async function executeStepWithHealing(params) {
     // reach the observe cascade's el.click() fallback that fails to commit MUI/
     // React controlled state (the wizard ATS's Basic-Info Step-2 wall). No-op (falls
     // through) when there's no radio group or no confident option match.
-    if (await tryRadioPrimitive({
+    const radioTargetId = await tryRadioPrimitive({
         page,
         target: frameTarget ?? (0, frame_target_1.mainFrameTarget)(page),
         instruction: step,
         logger,
         anthropic,
         captureFn,
-    })) {
+    });
+    if (radioTargetId !== null) {
         logger.info(`${formatStepPrefix(stepIndex, totalSteps)} resolved by radio primitive`);
-        trajectory?.push({ stepIndex, verifiedBy: "dom" });
+        trajectory?.push({ stepIndex, verifiedBy: "dom", targetId: radioTargetId });
         return "completed";
     }
     // On a CATCH-ALL step ("for any remaining … question"), fill every