@trusty-squire/mcp 0.9.13 → 0.9.14-rc.1

package/dist/bot/replay-skill.js

@@ -129,6 +129,23 @@ export async function replaySkill(input) {
     // marker too, so the verifier doesn't DEMOTE an active skill over it (which
     // was eroding OF#1 — measured: brevo demoted on a returning-user nav click).
     let authedViaOAuth = false;
+    // Form-readiness parity with the live bot. Until the FIRST form control
+    // fills/selects successfully, an "input absent" on a fill/select is far
+    // more likely the SPA signup form still hydrating than a genuinely-absent
+    // (already-registered) onboarding field — so we wait + reload + re-validate
+    // before treating it as skippable. Once a form control succeeds the form is
+    // present, and from then on absent fields keep the account-state skip.
+    let reachedForm = false;
+    // Post-click settle parity with the live bot. A click can kick off server
+    // work BEFORE the SPA navigates (zilliz's onboarding Continue provisions a
+    // default org/project/cluster, then routes to the dashboard — several
+    // seconds). The live bot's LLM round-trip gave that window for free; the
+    // replay engine reads the next inventory ~2s after the click, sees the OLD
+    // page, and wrongly skips/fails subsequent steps as "absent". When a step
+    // doesn't resolve and the most recent EXECUTED step was a click/navigate,
+    // poll re-validation before the skip/fail cascade decides. Iteration-
+    // bounded (not wall-clock) so stubbed tests don't spin.
+    let lastExecutedWasClick = false;
     for (let i = 0; i < skill.steps.length; i++) {
         const step = skill.steps[i];
         // Dry-mode short circuit: walk every step before the credential-
@@ -172,7 +189,31 @@ export async function replaySkill(input) {
         }
         // Pre-validate: would this step resolve cleanly against the
         // current page? If not, hand to the LLM fallback.
-        const validation = await preValidateStep(step, browser, templateValues);
+        let validation = await preValidateStep(step, browser, templateValues);
+        // Form-readiness parity: a fill/select that doesn't resolve BEFORE we've
+        // reached the form is usually the SPA still hydrating (zilliz /signup
+        // renders marketing chrome then the form). Wait for hydration + reload
+        // once + re-validate — mirroring the live bot's waitForFormReady +
+        // reload-on-shell loop — before the skip/fail cascade decides it's a
+        // genuinely-absent (already-registered) field. A fresh signup's form
+        // appears; an already-registered one never does and the skip still fires.
+        if (!validation.ok &&
+            !reachedForm &&
+            (step.kind === "fill" || step.kind === "select")) {
+            validation = await waitForFormThenRevalidate(step, browser, templateValues);
+        }
+        if (!validation.ok && lastExecutedWasClick) {
+            for (let poll = 0; poll < 6 && !validation.ok; poll++) {
+                await browser.wait(2);
+                validation = await preValidateStep(step, browser, templateValues);
+            }
+            // One settle window per click. If the page didn't produce this step's
+            // target within it, later steps shouldn't each re-pay the wait — a
+            // genuinely-diverged page (returning-user skips) would otherwise
+            // crawl through every remaining step at +12s apiece.
+            if (!validation.ok)
+                lastExecutedWasClick = false;
+        }
         let stepToExecute = step;
         if (!validation.ok) {
             const fallbackResult = await tryFallback(step, validation.reason, browser, i, skill, llmFallback, candidatesDir);
@@ -245,7 +286,7 @@ export async function replaySkill(input) {
         // the router can decide whether to retry or fall through to the
         // universal bot.
         try {
-            const execOutcome = await executeStep(stepToExecute, browser, templateValues, skill);
+            const execOutcome = await executeStep(stepToExecute, browser, templateValues, skill, input.fetchEmailCode);
             if (execOutcome.kind === "needs_login") {
                 return { kind: "needs_login", provider: execOutcome.provider, stepIndex: i };
             }
@@ -253,6 +294,22 @@ export async function replaySkill(input) {
             // an authenticated returning-user session for the rest of the replay.
             if (stepToExecute.kind === "click_oauth_button")
                 authedViaOAuth = true;
+            // Track form-readiness across DISTINCT forms. A successful fill/select
+            // means the CURRENT form is present; a click/navigate may move us to a
+            // NEW page whose form (zilliz's /information onboarding after the OTP)
+            // can itself still be hydrating — so re-arm the retry. Without the
+            // re-arm, the signup form hydrates but the next form's fields get
+            // eagerly skipped as "already registered".
+            if (execOutcome.kind === "filled" || execOutcome.kind === "selected") {
+                reachedForm = true;
+                lastExecutedWasClick = false;
+            }
+            else if (execOutcome.kind === "clicked" || execOutcome.kind === "navigated") {
+                reachedForm = false;
+                // Stays true across SKIPPED steps (they don't execute), so a step
+                // two slots after the click still gets the settle grace.
+                lastExecutedWasClick = true;
+            }
             if (execOutcome.kind === "extract_ok") {
                 // We extracted a credential successfully. Validate it before
                 // declaring victory — the synthesizer's shape inference is a
@@ -371,6 +428,38 @@ export async function replaySkill(input) {
         reason: "Walked entire skill graph without producing a credential.",
     };
 }
+// Wait for an SPA signup form to hydrate, then re-validate the step — the
+// replay-engine analogue of the live bot's waitForFormReady + reload-on-
+// shell loop. A flaky hydrating SPA (zilliz /signup) renders marketing
+// chrome first, so the one-shot post-navigate validation reads a form-less
+// inventory; the bot retries/reloads until the form appears, and so must
+// replay before it concludes a form control is genuinely absent. Bounded:
+// at most three short attempts with one mid-loop reload. Returns the first
+// passing validation, else the last failure (caller then runs its skip/fail
+// cascade). On an already-registered account the form never appears, so
+// this is a bounded no-op and the account-state skip still fires.
+async function waitForFormThenRevalidate(step, browser, templateValues) {
+    let v = { ok: false, reason: "form not ready" };
+    for (let attempt = 0; attempt < 3; attempt++) {
+        await browser.waitForAuthWidgetHydration?.().catch(() => undefined);
+        await browser.wait(1.5);
+        if (attempt === 1) {
+            // One reload to unstick a wedged loading shell (oauthShellReloads).
+            try {
+                await browser.goto(browser.currentUrl());
+                await browser.wait(2);
+                await browser.waitForInteractiveDom?.().catch(() => undefined);
+            }
+            catch {
+                // navigation hiccup — the next attempt re-validates regardless
+            }
+        }
+        v = await preValidateStep(step, browser, templateValues);
+        if (v.ok)
+            return v;
+    }
+    return v;
+}
 async function preValidateStep(step, browser, templateValues) {
     switch (step.kind) {
         case "navigate": {
@@ -386,6 +475,15 @@ async function preValidateStep(step, browser, templateValues) {
                 return { ok: false, reason: `Invalid URL in navigate step: ${step.url}` };
             }
         }
+        case "await_email_code": {
+            // No meaningful DOM pre-check: the code input is found heuristically
+            // at execute time (it may be unlabeled), and the email may not have
+            // arrived yet. Accept; the executor polls the inbox and fails cleanly
+            // if no code arrives or no input is found. No useful LLM fallback
+            // exists for this step (there's no captured selector to substitute).
+            void templateValues;
+            return { ok: true };
+        }
         case "click_oauth_button": {
             const inventory = await browser.extractInteractiveElements();
             const matches = inventory.filter((el) => matchesClickHint(el, step.text_match));
@@ -550,7 +648,7 @@ async function preValidateStep(step, browser, templateValues) {
         }
         case "select": {
             const inventory = await browser.extractInteractiveElements();
-            const matches = inventory.filter((el) => isFillable(el) && matchesLabelHint(el, step.label_hint));
+            const matches = inventory.filter((el) => isSelectTarget(el) && matchesLabelHint(el, step.label_hint));
             if (matches.length === 0) {
                 return {
                     ok: false,
@@ -713,7 +811,7 @@ export function labelMatchesHint(label, hint) {
         return false;
     return a === b || a.includes(b) || b.includes(a);
 }
-async function executeStep(step, browser, templateValues, skill) {
+async function executeStep(step, browser, templateValues, skill, fetchEmailCode) {
     switch (step.kind) {
         case "navigate": {
             // Rebase a captured per-account subdomain onto the live session's
@@ -730,6 +828,13 @@ async function executeStep(step, browser, templateValues, skill) {
             // content first, with the 2s as a floor for fast/static pages.
             await browser.wait(2);
             await browser.waitForInteractiveDom().catch(() => undefined);
+            // Parity with the live bot's waitForFormReady: an SPA signup page can
+            // render marketing chrome (so waitForInteractiveDom is satisfied)
+            // while the actual auth form is still an async spinner. Without this
+            // the replay reads a form-less inventory and skips the email/password
+            // fills as "absent" (zilliz /signup). Bounded; no-op once the form
+            // is present.
+            await browser.waitForAuthWidgetHydration?.().catch(() => undefined);
             // 0.8.2-rc.22 — URL drift detection. When a skill's signup_url
             // assumes the user is authenticated (Railway's /account/tokens
             // captured after OAuth was done in a prior session), the
@@ -897,21 +1002,53 @@ async function executeStep(step, browser, templateValues, skill) {
             await browser.type(match.selector, value);
             return { kind: "filled" };
         }
+        case "await_email_code": {
+            if (fetchEmailCode === undefined) {
+                throw new Error("await_email_code step requires a fetchEmailCode callback, but the " +
+                    "caller did not wire inbox access into the replay.");
+            }
+            const alias = templateValues.EMAIL_ALIAS;
+            if (alias === undefined || alias.length === 0) {
+                throw new Error("await_email_code step requires templateValues.EMAIL_ALIAS (the run's " +
+                    "inbox alias) to poll for the verification email.");
+            }
+            const code = await fetchEmailCode({ alias });
+            if (code === null || code.length === 0) {
+                throw new Error(`No email verification code arrived for ${alias} within the poll window.`);
+            }
+            const inventory = await browser.extractInteractiveElements();
+            const target = findCodeInput(inventory, step.label_hint);
+            if (target === null) {
+                throw new Error("await_email_code: could not find a verification-code input on the page.");
+            }
+            // browser.type clicks-then-pressSequentially, which auto-distributes
+            // across multi-box single-digit OTP inputs (Porter/Koyeb class) as
+            // well as a single combined box.
+            const otpPageUrl = browser.currentUrl();
+            await browser.type(target.selector, code);
+            // Auto-advance is racy: a keystroke landing during the widget's focus
+            // transition gets dropped by the controlled input, leaving N-1 boxes
+            // filled and the submit disabled (zilliz Verify, observed 2026-06-11).
+            // Read the boxes back and re-type per-box — explicit targeting, no
+            // auto-advance dependency — anything that didn't stick.
+            await fixupOtpDistribution(browser, code, otpPageUrl);
+            return { kind: "filled" };
+        }
         case "select": {
             const inventory = await browser.extractInteractiveElements();
             // 0.8.2-rc.3 — apply near_text_hint filter when present so
             // Sentry-grid rows land on the right <select>. The original
             // `inventory.find` would unilaterally pick the first match.
             //
-            // 0.8.2-rc.21 — also restrict to fillable elements (input /
-            // textarea / select). Without this, a Railway-class form where
-            // a `<label for="select-X">` shares labelText with its
+            // 0.8.2-rc.21 — also restrict to select targets (input /
+            // textarea / select / role=combobox). Without this, a Railway-class
+            // form where a `<label for="select-X">` shares labelText with its
             // `<select id="select-X">` would silently pick the label —
             // and selectOption(label, …) would then route into the
             // combobox path and fail because native selects don't reveal
             // options via DOM patterns. Pre-validation already filters
             // this way; the executor was lagging.
-            const allMatches = inventory.filter((el) => isFillable(el) && matchesLabelHint(el, step.label_hint));
+            const allMatches = inventory.filter((el) => isSelectTarget(el) && matchesLabelHint(el, step.label_hint));
             if (allMatches.length === 0) {
                 throw new Error(`No select matches label_hint=${step.label_hint}`);
             }
@@ -1425,6 +1562,11 @@ async function findValidatedCandidate(browser, validator) {
     try {
         const candidates = await browser.extractCredentialCandidates();
         for (const cand of candidates) {
+            // Same noise gate the heuristic tiers apply — a password-manager
+            // affordance or consent-widget word that happens to satisfy a
+            // length-only validator must not shadow the real key.
+            if (isCredentialNoiseCandidate(cand))
+                continue;
             if (candidateSatisfiesValidatorShape(cand, validator))
                 return cand;
         }
@@ -1669,16 +1811,24 @@ async function maybeDumpReplayDebug(browser, skill, stepIndex, reason) {
             .filter((e) => e.visible)
             .map((e) => ({
             tag: e.tag,
+            type: e.type,
             role: e.role,
             text: (e.visibleText ?? "").slice(0, 60),
             aria: e.ariaLabel,
             label: e.labelText,
             placeholder: e.placeholder,
             href: e.href ?? null,
+            selector: e.selector,
+            // Field state is the diagnostic for "submit stays disabled" failures
+            // (which box is actually empty?). Password values stay redacted.
+            value: e.type === "password" ? (e.value ? "<redacted>" : "") : (e.value ?? null),
         }))
-            .filter((e) => e.text || e.aria || e.label || e.placeholder || e.href);
+            .filter((e) => e.text || e.aria || e.label || e.placeholder || e.href || e.value);
+        // Visible page text (toasts, validation errors, "code expired" banners)
+        // — interactive inventory alone can't show WHY a page refused to move.
+        const pageText = (await browser.extractText().catch(() => "")).slice(0, 1500);
         const path = `/tmp/replay-debug-${skill.service}-step${stepIndex}.json`;
-        writeFileSync(path, JSON.stringify({ service: skill.service, stepIndex, reason, url: browser.currentUrl(), interesting }, null, 2));
+        writeFileSync(path, JSON.stringify({ service: skill.service, stepIndex, reason, url: browser.currentUrl(), pageText, interesting }, null, 2));
         console.error(`[replay-debug] dumped ${path} (${interesting.length} elements)`);
     }
     catch {
@@ -1855,6 +2005,89 @@ function isRuntimeId(id) {
 function isFillable(el) {
     return el.tag === "input" || el.tag === "textarea" || el.tag === "select";
 }
+// A `select` step's target is broader than isFillable: MUI/Radix-class
+// dropdowns render as a non-input element with role="combobox" (zilliz's
+// Job Title is a <div id="mui-component-select-jobTitle" role="combobox">).
+// browser.selectOption already drives those (click + pick option from the
+// popup — the capture-time path); the replay matcher was the only place
+// still requiring a native form tag, which made every MUI select look
+// "absent" and get skipped as account-state onboarding (measured live
+// 2026-06-11: zilliz replay left Job Title unselected, Continue no-opped,
+// and the failure surfaced 5 steps later as a bogus returning-user
+// divergence on "API Keys").
+function isSelectTarget(el) {
+    return isFillable(el) || el.role === "combobox";
+}
+// Locate the verification-code input for an `await_email_code` step.
+// OTP inputs are frequently UNLABELED (single-digit boxes, headless
+// inputs) — that's exactly why a `fill` step can't carry them — so the
+// resolution order is: (1) explicit label_hint when present, (2) an input
+// whose attributes name it a code field, (3) the first code-shaped input
+// on the page. (3) is safe because this step only runs at the
+// verification gate the synthesizer placed it at, where the page is just
+// the code input(s) + a Verify button. Returns null when no plausible
+// input exists. Exported for unit tests.
+export function codeInputCandidates(inventory) {
+    // Code-shaped: a visible text-entry input that is NOT an email/password/
+    // checkbox/radio/etc. (type null/"" covers headless OTP boxes).
+    const TEXT_ENTRY = new Set(["text", "tel", "number", "", "search"]);
+    return inventory.filter((el) => el.tag === "input" &&
+        el.visible !== false &&
+        (el.type === null || TEXT_ENTRY.has(el.type)) &&
+        el.type !== "email" &&
+        el.type !== "password");
+}
+// Post-typing readback for an `await_email_code` step. browser.type relies
+// on the widget's auto-advance to distribute digits across multi-box OTP
+// inputs; a keystroke that fires during the focus transition is silently
+// dropped by the controlled input (React setState hasn't moved focus yet),
+// leaving a box empty and the submit button disabled. Re-read the boxes and
+// re-type any digit that didn't stick — per-box explicit targeting, so the
+// corrective pass has no auto-advance dependency. No-ops when the mapping
+// boxes↔digits isn't unambiguous (extra unrelated inputs on the page) or
+// when the widget auto-submitted on the last digit (URL changed — the new
+// page's inputs are NOT OTP boxes). Exported for unit tests.
+export async function fixupOtpDistribution(browser, code, otpPageUrl) {
+    // Let the widget's controlled-input state settle before reading back.
+    await browser.wait(1);
+    if (browser.currentUrl() !== otpPageUrl)
+        return;
+    const boxes = codeInputCandidates(await browser.extractInteractiveElements());
+    if (boxes.length === 1) {
+        // Single combined input: its value should be the whole code.
+        if ((boxes[0].value ?? "") !== code) {
+            await browser.type(boxes[0].selector, code);
+        }
+        return;
+    }
+    if (boxes.length !== code.length)
+        return;
+    for (let i = 0; i < boxes.length; i++) {
+        if ((boxes[i].value ?? "") === code.charAt(i))
+            continue;
+        console.error(`[replay] await_email_code: OTP box ${i + 1}/${boxes.length} holds ` +
+            `${JSON.stringify(boxes[i].value ?? "")} after auto-advance typing — re-typing it directly.`);
+        await browser.type(boxes[i].selector, code.charAt(i));
+    }
+}
+export function findCodeInput(inventory, labelHint) {
+    const candidates = codeInputCandidates(inventory);
+    if (candidates.length === 0)
+        return null;
+    if (labelHint !== undefined && labelHint.length > 0) {
+        const byLabel = candidates.filter((el) => matchesLabelHint(el, labelHint));
+        if (byLabel.length >= 1)
+            return byLabel[0];
+    }
+    // Word-START boundary only (no trailing \b): "verif" must prefix-match
+    // "verificationCode" / "verification_code", which a trailing \b would
+    // break (it'd require "verif" to be a whole word).
+    const codeRe = /\b(code|otp|verif|pin|one[\s-]?time|2fa|mfa)/i;
+    const byAttr = candidates.filter((el) => codeRe.test(`${el.name ?? ""} ${el.id ?? ""} ${el.placeholder ?? ""} ${el.ariaLabel ?? ""} ${el.labelText ?? ""}`));
+    if (byAttr.length >= 1)
+        return byAttr[0];
+    return candidates[0];
+}
 // rc.24/rc.25 — cascading fill-target disambiguator. Shared by
 // preValidate and executeStep so both arrive at the same input when
 // a label matches more than once (OpenRouter's "Name" input ships