@enricai/barnacle 1.6.9 → 1.6.11

package/dist/scraper/flow-runner.js

@@ -87,11 +87,13 @@ const schemas_1 = require("../lib/llm/schemas");
 const logging_1 = require("../lib/logging");
 const call_capture_1 = require("../lib/telemetry/call-capture");
 const call_types_1 = require("../lib/telemetry/call-types");
+const deep_locator_candidates_1 = require("../scraper/deep-locator-candidates");
 const errors_2 = require("../scraper/errors");
 const frame_target_1 = require("../scraper/frame-target");
 const phantom_click_1 = require("../scraper/phantom-click");
 const stagehand_guard_1 = require("../scraper/stagehand-guard");
 const submit_control_1 = require("../scraper/submit-control");
+const watchdog_1 = require("../scraper/watchdog");
 const recon_shared_1 = require("../scripts/recon-shared");
 const logger = (0, logging_1.getLogger)({ name: "scraper/flow-runner" });
 /** Cap on the rolling capture-filename window held in memory for failure dumps. */
@@ -521,9 +523,12 @@ async function snapshotPage(target, signalCounter) {
  * body HTML and url instead of pairing a child frame's DOM with the top
  * document's url. `title()` intentionally still reads the top document for
  * a child frame (see `frame-target.ts`); `url()` is the frame discriminator.
+ * Routed through `mainFrameTarget(page)` (rather than a raw `page.title()`)
+ * when no `frameTarget` is resolved so this CDP read is watchdog-bounded the
+ * same way a resolved `FrameTarget`'s `title()` already is.
  */
 async function resolveDumpPageIdentity(page, frameTarget) {
-    const pageTitle = await (frameTarget ?? page).title().catch(() => "");
+    const pageTitle = await (frameTarget ?? (0, frame_target_1.mainFrameTarget)(page)).title().catch(() => "");
     const pageUrl = await (frameTarget ? frameTarget.url() : Promise.resolve(page.url())).catch(() => page.url());
     return { pageTitle, pageUrl };
 }
@@ -4408,6 +4413,28 @@ async function probeFormValidityBeforeSubmit(params) {
         return [];
     }
 }
+/**
+ * Adapts `resolveDeepLocatorCandidates` results into `Action`-shaped
+ * evidence for `rephraseWithLLM`, which only knows about Stagehand's
+ * `Action` type. Never throws: `resolveDeepLocatorCandidates` itself
+ * degrades to `[]` on a resolver failure, so this only feeds the rephrase
+ * prompt richer evidence when available — a frame-scoped step whose
+ * observe AND deepLocator both come back empty just gets the same `[]`
+ * evidence it would have gotten before this fix.
+ *
+ * `instruction` is forwarded to `resolveDeepLocatorCandidates` so the
+ * evidence list is ranked by relevance to the step, same as the act path —
+ * an unranked `[]`-then-DOM-order list would feed the rephrase LLM its
+ * worst evidence first instead of its best.
+ */
+async function deepLocatorCandidatesAsActions(page, frameSelector, instruction) {
+    const candidates = await (0, deep_locator_candidates_1.resolveDeepLocatorCandidates)(page, frameSelector, "*", instruction);
+    return candidates.map((c) => ({
+        selector: c.selector,
+        description: c.accessibleText || "(no accessible text)",
+        method: "click",
+    }));
+}
 /**
  * Cheap pre-cascade reachability gate. Runs before the 5-attempt healing cascade
  * (and any global replan) so a step aimed at the wrong page state fails fast
@@ -4419,10 +4446,16 @@ async function probeFormValidityBeforeSubmit(params) {
  *
  * `frameTarget` scopes both observe calls to a resolved cross-origin child
  * frame when the flow declared `frameSelector`; omitted (main frame) is
- * byte-identical to today's unscoped calls.
+ * byte-identical to today's unscoped calls. When `frameTarget.frame` is a
+ * resolved child frame, `observe()` is blind to it (measured against a
+ * cross-origin OOPIF — see `deep-locator-candidates.ts`'s module docblock),
+ * so a 0-candidate focused+unfocused observe pair additionally falls back to
+ * `resolveDeepLocatorCandidates` before declaring the step "absent" — a
+ * frame-scoped step must not short-circuit to replan before the cascade
+ * (which itself now routes through the same resolver) ever runs.
  */
 async function probeStepBeforeAttempts(params) {
-    const { stagehand, step, stepIndex, totalSteps, logger, captureFn, frameTarget } = params;
+    const { stagehand, page, step, stepIndex, totalSteps, logger, captureFn, frameTarget, reresolveFrameTarget, } = params;
     try {
         const candidates = await (0, stagehand_guard_1.guardedObserve)(stagehand, step, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget);
         if (candidates.length === 0) {
@@ -4442,6 +4475,16 @@ async function probeStepBeforeAttempts(params) {
                 logger.info(`${formatStepPrefix(stepIndex, totalSteps)}: focused probe found 0 candidates but unfocused observe found ${unfocused.length} — treating as present (let cascade resolve)`);
                 return "present";
             }
+            const effectiveFrameTarget = reresolveFrameTarget
+                ? await reresolveFrameTarget()
+                : frameTarget;
+            if (effectiveFrameTarget?.frame) {
+                const deepLocatorCandidates = await (0, deep_locator_candidates_1.resolveDeepLocatorCandidates)(page, effectiveFrameTarget.frameSelector, "*");
+                if (deepLocatorCandidates.length > 0) {
+                    logger.info(`${formatStepPrefix(stepIndex, totalSteps)}: observe found 0 candidates (focused and unfocused) but deepLocator found ${deepLocatorCandidates.length} — treating as present (let cascade resolve)`);
+                    return "present";
+                }
+            }
             logger.info(`${formatStepPrefix(stepIndex, totalSteps)}: probe found 0 candidates (focused and unfocused) — treating as absent (skip cascade, route to replan if required)`);
             return "absent";
         }
@@ -4456,7 +4499,45 @@ async function probeStepBeforeAttempts(params) {
     }
 }
 async function executeStepWithHealing(params) {
-    const { stagehand, page, frameTarget, step, optional, upload, submitStep, stepIndex, totalSteps, phase, signalCounter, recentCaptures, recentCaptureMeta, anthropic, logger, captureFn, resumeFixture, isFinalStep, submitEndpointPattern, submittedStateSelectors, requireSubmitEndpointMatch, advanceTransitionBodyPattern, successUrlFragments, successPageTitleHints, ownBackendHostnames, knownErrorClassPrefixes, wizardExitButtonLabels, getSuppressedAisdkElementIdErrorCount, trajectory, onStepFailure, } = params;
+    const { stagehand, page, step, optional, upload, submitStep, stepIndex, totalSteps, phase, signalCounter, recentCaptures, recentCaptureMeta, anthropic, logger, captureFn, resumeFixture, isFinalStep, submitEndpointPattern, submittedStateSelectors, requireSubmitEndpointMatch, advanceTransitionBodyPattern, successUrlFragments, successPageTitleHints, ownBackendHostnames, knownErrorClassPrefixes, wizardExitButtonLabels, getSuppressedAisdkElementIdErrorCount, trajectory, onStepFailure, } = params;
+    // Mutable (not the destructured const above) so a lost frame-attach race
+    // can be upgraded in place once the OOPIF attaches later in the cascade —
+    // see reresolveFrameTargetIfLost below. Every existing reference in this
+    // function keeps reading `frameTarget` unchanged; only its declaration
+    // moved so it can be reassigned.
+    let frameTarget = params.frameTarget;
+    let frameReresolveAttempted = false;
+    /**
+     * Re-resolves a frame that lost the attach race at step entry —
+     * `resolveFrameTarget`'s per-step poll (called once in the runner's step
+     * loop, before `executeStepWithHealing` even starts) gives up and pins
+     * `frameTarget.frame` to `null` for the rest of the step, so every
+     * deepLocator gate below tests a stale "unresolved" handle even after the
+     * OOPIF actually attaches moments later (the run 5 vs. run 6 divergence in
+     * the bug report). Called just before each gate; re-checks with
+     * `timeoutMs: 0` — a single presence probe, no added poll delay — so a
+     * frame that has since attached is picked up without making the deadline
+     * that already elapsed matter again. Memoized (`frameReresolveAttempted`)
+     * so the cascade's several gates share one attempt instead of each
+     * re-checking; a target with no `declaredFrameSelector` (the frame was
+     * never declared, or resolution already succeeded) returns immediately
+     * without calling `resolveFrameTarget` at all, so main-frame-only flows do
+     * zero extra work.
+     */
+    const reresolveFrameTargetIfLost = async () => {
+        if (frameReresolveAttempted)
+            return;
+        frameReresolveAttempted = true;
+        if (frameTarget?.frame || !frameTarget?.declaredFrameSelector)
+            return;
+        const reresolved = await (0, frame_target_1.resolveFrameTarget)(page, frameTarget.declaredFrameSelector, {
+            timeoutMs: 0,
+        });
+        if (!reresolved.frame)
+            return;
+        logger.info(`${formatStepPrefix(stepIndex, totalSteps)} frame ${frameTarget.declaredFrameSelector} attached after step entry — re-resolved before deepLocator gate`);
+        frameTarget = reresolved;
+    };
     // Read-once to suppress "unused" — knownErrorClassPrefixes is threaded
     // through executeStepWithHealing's signature so the cascade has it in
     // scope when the invalid-fields judge migration (Task #43) lands. The
@@ -4587,12 +4668,17 @@ async function executeStepWithHealing(params) {
     // burning 4 attempts on a page that clearly isn't the right one.
     const probeResult = await probeStepBeforeAttempts({
         stagehand,
+        page,
         step,
         stepIndex,
         totalSteps,
         logger,
         captureFn,
         frameTarget,
+        reresolveFrameTarget: async () => {
+            await reresolveFrameTargetIfLost();
+            return frameTarget;
+        },
     });
     if (probeResult === "absent") {
         if (optional) {
@@ -4650,7 +4736,16 @@ async function executeStepWithHealing(params) {
             .evaluate("document.body ? document.body.outerHTML : null")
             .catch(() => null);
         const bodyOuterHtml = typeof bodyOuterHtmlRaw === "string" ? bodyOuterHtmlRaw.slice(0, 100_000) : null;
-        const unfocusedObserve = await (0, stagehand_guard_1.guardedObserve)(stagehand, undefined, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget).catch(() => []);
+        const probeAbsentObservedUnfocused = await (0, stagehand_guard_1.guardedObserve)(stagehand, undefined, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget).catch(() => []);
+        // observe() is blind to a cross-origin OOPIF, so a frame-scoped empty
+        // result degrades to the deep-locator resolver for dump evidence — this
+        // dump feeds replanRemainingFlow's diagnostic prompt, and an empty
+        // candidate list there returns "repeat the failed step", burning the
+        // replan budget on every frame-scoped probe-absent failure.
+        await reresolveFrameTargetIfLost();
+        const unfocusedObserve = probeAbsentObservedUnfocused.length === 0 && frameTarget?.frame
+            ? await deepLocatorCandidatesAsActions(page, frameTarget.frameSelector)
+            : probeAbsentObservedUnfocused;
         const dumpPath = onStepFailure?.({
             stepIndex,
             phase,
@@ -4973,7 +5068,59 @@ async function executeStepWithHealing(params) {
                     ? { ignoreSelectors: [...triedSelectors], timeout: exports.STEP_WATCHDOG_MS }
                     : { timeout: exports.STEP_WATCHDOG_MS };
                 const candidates = await (0, stagehand_guard_1.guardedObserve)(stagehand, step, observeOptions, captureFn, frameTarget);
-                if (candidates.length === 0) {
+                // observe() is blind to a cross-origin OOPIF (see
+                // deep-locator-candidates.ts's module docblock) — when the step is
+                // frame-scoped and observe came back empty, fall back to the deep
+                // locator resolver before declaring the attempt candidate-less.
+                // Passing `step` ranks candidates by relevance to the instruction
+                // (see resolveDeepLocatorCandidates) so the top pick below is the
+                // element the step actually names, not just DOM order.
+                // Attempt 4's ignoreSelectors has no deepLocator equivalent, so the
+                // exclusion is applied here by filtering resolved (already-ranked)
+                // candidates against triedSelectors instead — otherwise attempt 4
+                // would re-pick the same failed element and burn the attempt.
+                await reresolveFrameTargetIfLost();
+                const deepLocatorCandidates = candidates.length === 0 && frameTarget?.frame
+                    ? (await (0, deep_locator_candidates_1.resolveDeepLocatorCandidates)(page, frameTarget.frameSelector, "*", step)).filter((c) => !triedSelectors.includes(c.selector))
+                    : [];
+                if (candidates.length === 0 && deepLocatorCandidates.length > 0) {
+                    const top = deepLocatorCandidates[0];
+                    if (top) {
+                        record.instruction = `deepLocator: ${top.accessibleText || "(no accessible text)"}`;
+                        // Deny-list guard: mirrors the observe branch's refusal below —
+                        // never act on a wizard-exit control regardless of which
+                        // candidate source (observe vs. deepLocator) surfaced it.
+                        if (isWizardExitAction(top.accessibleText, wizardExitButtonLabels)) {
+                            record.errorMessage = `refused wizard-exit control: "${top.accessibleText.slice(0, 60)}"`;
+                            triedSelectors.push(top.selector);
+                            record.triedSelectors = [top.selector];
+                            attempts.push(record);
+                            failureReasons.push(record.errorMessage);
+                            logger.info(`${formatStepPrefix(stepIndex, totalSteps)} attempt ${attempt}: ${record.errorMessage}`);
+                            continue;
+                        }
+                        triedSelectors.push(top.selector);
+                        record.triedSelectors = [top.selector];
+                        try {
+                            await (0, deep_locator_candidates_1.clickDeepLocatorCandidate)(page, frameTarget?.frameSelector, "*", top.index);
+                            record.actResultSuccess = true;
+                            record.actResultDescription = `deepLocator clicked "${top.accessibleText || top.selector}"`;
+                            // Synthesize a click action so downstream verification (network
+                            // / url / dom) treats this exactly like any other resolved
+                            // click — same idiom as deep-submit-locator/structured-click.
+                            resolvedAction = {
+                                selector: top.selector,
+                                description: record.actResultDescription,
+                                method: "click",
+                            };
+                        }
+                        catch (err) {
+                            record.actResultSuccess = false;
+                            record.errorMessage = `deepLocator: click threw ${(0, errors_1.toErrorMessage)(err)}`;
+                        }
+                    }
+                }
+                else if (candidates.length === 0) {
                     record.errorMessage = "observe returned no candidates";
                     // Optional-step short-circuit: when attempt 2 confirms no candidates
                     // match AND the step was marked optional in the flow, skip cleanly.
@@ -5240,7 +5387,16 @@ async function executeStepWithHealing(params) {
                         "anthropic billing exhausted (FATAL_BILLING already logged); skipping rephrase";
                 }
                 else {
-                    const candidates = await (0, stagehand_guard_1.guardedObserve)(stagehand, step, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget).catch(() => []);
+                    const observedCandidates = await (0, stagehand_guard_1.guardedObserve)(stagehand, step, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget).catch(() => []);
+                    // observe() is blind to a cross-origin OOPIF, so a frame-scoped
+                    // empty result degrades to the deep-locator resolver for prompt
+                    // evidence rather than hard-failing — lower stakes than the
+                    // attempt-2/4 click path since this only feeds the rephrase
+                    // prompt, so a resolver error/empty result is fine to swallow.
+                    await reresolveFrameTargetIfLost();
+                    const candidates = observedCandidates.length === 0 && frameTarget?.frame
+                        ? await deepLocatorCandidatesAsActions(page, frameTarget.frameSelector, step)
+                        : observedCandidates;
                     // Fetch live-page evidence so the rephrase prompt can reason about
                     // form state, not just observe candidates. Mirrors the same
                     // extraction the cascade-exhaust dump path already does.
@@ -5255,7 +5411,10 @@ async function executeStepWithHealing(params) {
                     // frameTarget: for a frame-scoped flow the ambient UI that matters
                     // (the wizard's own Save/Close controls) lives inside the iframe
                     // alongside the failed step, not in the top document.
-                    const unfocused = await (0, stagehand_guard_1.guardedObserve)(stagehand, undefined, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget).catch(() => []);
+                    const observedUnfocused = await (0, stagehand_guard_1.guardedObserve)(stagehand, undefined, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget).catch(() => []);
+                    const unfocused = observedUnfocused.length === 0 && frameTarget?.frame
+                        ? await deepLocatorCandidatesAsActions(page, frameTarget.frameSelector)
+                        : observedUnfocused;
                     const submitFailureList = extractSubmitFailureEvidence(recentCaptures, ownBackendHostnames);
                     const gaEventList = extractGaEventEvidence(recentCaptures);
                     const priorAttemptsForPrompt = attempts.map((a, i) => ({
@@ -5431,7 +5590,10 @@ async function executeStepWithHealing(params) {
             // structural ng-invalid containers is not fuzzy matching, just
             // observing existence).
             const invalidMarkerCount = await countNgInvalidContainers(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page)).catch(() => 0);
-            const pageTitle = await page.title().catch(() => "");
+            const pageTitle = await (0, watchdog_1.withWatchdog)(() => page.title(), {
+                timeoutMs: config_1.config.scraper.frameEvaluateTimeoutMs,
+                label: "flow-runner: submit-verification page title probe",
+            }).catch(() => "");
             const matchedSubmittedSelectors = domSubmittedMatch !== null ? [domSubmittedMatch] : [];
             const judgeVerdict = await (0, verify_submit_1.verifySubmitWithLLM)({
                 client: anthropic,
@@ -5664,7 +5826,10 @@ async function executeStepWithHealing(params) {
                         }
                         const unfocusedForJudge = await (0, stagehand_guard_1.guardedObserve)(stagehand, undefined, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget).catch(() => []);
                         const invalidMarkerCount = await countNgInvalidContainers(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page)).catch(() => 0);
-                        const pageTitle = await page.title().catch(() => "");
+                        const pageTitle = await (0, watchdog_1.withWatchdog)(() => page.title(), {
+                            timeoutMs: config_1.config.scraper.frameEvaluateTimeoutMs,
+                            label: "flow-runner: submit-verification retry page title probe",
+                        }).catch(() => "");
                         const matchedSubmittedSelectors = domSubmittedMatch !== null ? [domSubmittedMatch] : [];
                         const judgeVerdict = await (0, verify_submit_1.verifySubmitWithLLM)({
                             client: anthropic,
@@ -5862,16 +6027,28 @@ async function executeStepWithHealing(params) {
             }
         }
     }
-    const finalObserve = await (0, stagehand_guard_1.guardedObserve)(stagehand, step, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget).catch(() => []);
+    const cascadeExhaustObservedFinal = await (0, stagehand_guard_1.guardedObserve)(stagehand, step, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget).catch(() => []);
+    // observe() is blind to a cross-origin OOPIF, so a frame-scoped empty
+    // result degrades to the deep-locator resolver for dump evidence — this
+    // dump feeds replanRemainingFlow's diagnostic prompt, and an empty
+    // candidate list there returns "repeat the failed step", burning the
+    // replan budget on every frame-scoped cascade-exhaust failure.
+    await reresolveFrameTargetIfLost();
+    const finalObserve = cascadeExhaustObservedFinal.length === 0 && frameTarget?.frame
+        ? await deepLocatorCandidatesAsActions(page, frameTarget.frameSelector, step)
+        : cascadeExhaustObservedFinal;
     const { pageTitle, pageUrl } = await resolveDumpPageIdentity(page, frameTarget);
     // Discriminator data for "Stagehand sees nothing" failures: capture the raw
     // DOM and an unfocused observe so a triager can tell empty-page from
     // Stagehand-can't-see-it without reproducing the failure.
-    const bodyOuterHtmlRaw = await (frameTarget ?? page)
+    const bodyOuterHtmlRaw = await (frameTarget ?? (0, frame_target_1.mainFrameTarget)(page))
         .evaluate("document.body ? document.body.outerHTML : null")
         .catch(() => null);
     const bodyOuterHtml = typeof bodyOuterHtmlRaw === "string" ? bodyOuterHtmlRaw.slice(0, 100_000) : null;
-    const unfocusedObserve = await (0, stagehand_guard_1.guardedObserve)(stagehand, undefined, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget).catch(() => []);
+    const cascadeExhaustObservedUnfocused = await (0, stagehand_guard_1.guardedObserve)(stagehand, undefined, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget).catch(() => []);
+    const unfocusedObserve = cascadeExhaustObservedUnfocused.length === 0 && frameTarget?.frame
+        ? await deepLocatorCandidatesAsActions(page, frameTarget.frameSelector)
+        : cascadeExhaustObservedUnfocused;
     const dumpPath = onStepFailure?.({
         stepIndex,
         phase,
@@ -5902,6 +6079,16 @@ const SPA_MIN_BODY_LENGTH = 5_000;
  * the entire flow. The recon CLI has this gate inline; generated plugins call it
  * here so they inherit the same behavior. Polls `document.body.outerHTML.length`
  * up to a threshold, then proceeds regardless (best-effort, never throws).
+ *
+ * Each `document.body.outerHTML.length` read is itself bounded by a watchdog
+ * (capped to one poll interval) and treated as "still 0 chars" on timeout —
+ * same pattern as `waitForChildFrameReady`'s `isReady()` probe. Without this,
+ * a single wedged CDP round-trip inside `readBodyLength` would pend forever
+ * and the `while (Date.now() < deadline)` loop below would never be
+ * re-entered, defeating the very deadline it exists to enforce.
+ * `page.waitForTimeout(pollMs)` is left unguarded: it is a plain delay (no
+ * DOM/network read whose response can be lost), so it does not carry the
+ * "wedged read" failure mode this fix targets.
  */
 async function waitForSpaReady(page, logger, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? SPA_READINESS_TIMEOUT_MS;
@@ -5909,7 +6096,10 @@ async function waitForSpaReady(page, logger, opts = {}) {
     const minBodyLength = opts.minBodyLength ?? SPA_MIN_BODY_LENGTH;
     const bodyLengthExpr = "document.body ? document.body.outerHTML.length : 0";
     const readBodyLength = async () => {
-        const raw = await page.evaluate(bodyLengthExpr).catch(() => 0);
+        const raw = await (0, watchdog_1.withWatchdog)(() => page.evaluate(bodyLengthExpr), {
+            timeoutMs: pollMs,
+            label: "flow-runner: spa readiness body-length probe",
+        }).catch(() => 0);
         return typeof raw === "number" ? raw : 0;
     };
     let bodyLength = await readBodyLength();