site-agent-pro 1.0.0

package/dist/core/executor.js

@@ -0,0 +1,788 @@
+import { findMatchingSelectOption, fitValueToField, scoreFormFieldTargetMatch, shouldCheckField, } from "./formHeuristics.js";
+import { buildLooseAccessiblePattern, prepareLocatorForInteraction, resolvePreferredFieldLocator, typeLikeHuman, } from "./interaction.js";
+const INTERSTITIAL_PATTERNS = [
+    /just a moment/i,
+    /verification successful/i,
+    /checking your browser/i,
+    /cloudflare/i,
+    /security check/i,
+    /access denied/i,
+    /captcha/i,
+    /human verification/i,
+];
+function cleanErrorMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const withoutAnsi = message.replace(/\u001b\[[0-9;]*m/g, "");
+    return withoutAnsi.replace(/\s+/g, " ").trim() || "Unknown error";
+}
+function normalizeText(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+function normalizeKey(value) {
+    return normalizeText(value).toLowerCase();
+}
+function escapeAttributeValue(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function resolveDecisionTargetLabel(decision) {
+    return decision.target.trim() || decision.target_id.trim();
+}
+function truncateLabel(value, maxLength) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, Math.max(1, maxLength - 1)).trimEnd()}...`;
+}
+function isInterstitialState(state) {
+    const textBlob = `${state.title} ${state.textSnippet} ${state.url}`;
+    return INTERSTITIAL_PATTERNS.some((pattern) => pattern.test(textBlob));
+}
+async function readVisibleState(page) {
+    const title = await page.title().catch(() => "");
+    const url = page.url();
+    const textSnippet = normalizeText(await page
+        .locator("body")
+        .innerText()
+        .catch(() => "")).slice(0, 800);
+    const modalCount = await page
+        .evaluate(() => {
+        return document.querySelectorAll("dialog, [role='dialog'], .modal, [aria-modal='true']").length;
+    })
+        .catch(() => 0);
+    return { url, title, textSnippet, modalCount };
+}
+async function captureClickNeighborhood(locator) {
+    try {
+        return await locator.evaluate((element) => {
+            const container = element.closest("section, article, nav, main, aside, dialog, [role='dialog'], [role='tabpanel'], .modal, .card, .panel, .accordion") || element.parentElement;
+            if (!container) {
+                return "";
+            }
+            return (container.innerHTML || "")
+                .replace(/\s+/g, " ")
+                .trim()
+                .slice(0, 600);
+        });
+    }
+    catch {
+        return "";
+    }
+}
+function describeStateChange(before, after) {
+    const stateChanged = before.url !== after.url ||
+        normalizeText(before.title) !== normalizeText(after.title) ||
+        before.textSnippet !== after.textSnippet ||
+        before.modalCount !== after.modalCount;
+    return {
+        stateChanged,
+        destinationLabel: normalizeText(after.title) || after.url,
+    };
+}
+async function firstVisible(locators) {
+    for (const item of locators) {
+        try {
+            if (await item.locator.first().isVisible({ timeout: 1200 })) {
+                return { locator: item.locator.first(), name: item.name };
+            }
+        }
+        catch {
+            // continue
+        }
+    }
+    return null;
+}
+async function findClickTarget(page, target) {
+    const escapedTarget = escapeAttributeValue(target);
+    const targetPattern = buildLooseAccessiblePattern(target);
+    if (!targetPattern) {
+        return null;
+    }
+    return firstVisible([
+        {
+            locator: page.getByRole("button", { name: targetPattern }),
+            name: "getByRole(button)",
+        },
+        {
+            locator: page.getByRole("link", { name: targetPattern }),
+            name: "getByRole(link)",
+        },
+        {
+            locator: page.getByRole("tab", { name: targetPattern }),
+            name: "getByRole(tab)",
+        },
+        {
+            locator: page.getByRole("menuitem", { name: targetPattern }),
+            name: "getByRole(menuitem)",
+        },
+        {
+            locator: page.locator(`input[type="submit"][value*="${escapedTarget}" i], input[type="button"][value*="${escapedTarget}" i], input[type="reset"][value*="${escapedTarget}" i]`),
+            name: "input[value contains]",
+        },
+        { locator: page.getByText(targetPattern), name: "getByText" },
+        {
+            locator: page.locator(`[aria-label*="${escapedTarget}" i]`),
+            name: "aria-label contains",
+        },
+    ]);
+}
+async function findClickTargetById(page, targetId) {
+    const normalizedTargetId = targetId.trim();
+    if (!normalizedTargetId) {
+        return null;
+    }
+    const locator = page
+        .locator(`[data-site-agent-id="${escapeAttributeValue(normalizedTargetId)}"]`)
+        .first();
+    try {
+        if (await locator.isVisible({ timeout: 1200 })) {
+            return { locator, name: "target_id" };
+        }
+    }
+    catch {
+        // continue
+    }
+    return null;
+}
+async function buildClickIndicator(locator, target) {
+    await locator.scrollIntoViewIfNeeded().catch(() => undefined);
+    const box = await locator.boundingBox().catch(() => null);
+    if (!box || box.width <= 0 || box.height <= 0) {
+        return undefined;
+    }
+    return {
+        x: box.x,
+        y: box.y,
+        width: box.width,
+        height: box.height,
+        targetLabel: truncateLabel(normalizeText(target) || "Click target", 72),
+    };
+}
+export async function prepareClickDecision(page, decision) {
+    const targetLabel = resolveDecisionTargetLabel(decision);
+    const targetId = decision.target_id.trim();
+    if (targetId) {
+        const match = await findClickTargetById(page, targetId);
+        if (!match) {
+            return {
+                note: `Could not find numbered clickable element for target_id '${targetId}'`,
+            };
+        }
+        const clickIndicator = await buildClickIndicator(match.locator, targetLabel || targetId);
+        return {
+            preparedClick: {
+                locator: match.locator,
+                matchedBy: match.name,
+                ...(clickIndicator ? { clickIndicator } : {}),
+            },
+        };
+    }
+    if (!targetLabel) {
+        return { note: "Decision required a target but did not provide one" };
+    }
+    const match = await findClickTarget(page, targetLabel);
+    if (!match) {
+        return { note: `Could not find clickable element for '${targetLabel}'` };
+    }
+    const clickIndicator = await buildClickIndicator(match.locator, targetLabel);
+    return {
+        preparedClick: {
+            locator: match.locator,
+            matchedBy: match.name,
+            ...(clickIndicator ? { clickIndicator } : {}),
+        },
+    };
+}
+async function collectVisibleFillableFields(page) {
+    const fields = await page.evaluate(() => {
+        return Array.from(document.querySelectorAll("input, textarea, select"))
+            .map((element, index) => {
+            const rect = element.getBoundingClientRect();
+            const style = window.getComputedStyle(element);
+            const inputType = element instanceof HTMLInputElement
+                ? (element.type || "text").replace(/\s+/g, " ").trim().toLowerCase()
+                : "";
+            if (rect.width <= 0 ||
+                rect.height <= 0 ||
+                style.visibility === "hidden" ||
+                style.display === "none" ||
+                element.disabled ||
+                inputType === "hidden" ||
+                inputType === "submit" ||
+                inputType === "button" ||
+                inputType === "image") {
+                return null;
+            }
+            const marker = String(index + 1);
+            element.setAttribute("data-site-agent-fill-field", marker);
+            const agentId = (element.getAttribute("data-site-agent-id") || "").trim() || marker;
+            element.setAttribute("data-site-agent-id", agentId);
+            const labelParts = [];
+            if ("labels" in element && element.labels) {
+                for (const label of Array.from(element.labels)) {
+                    labelParts.push((label.innerText || label.textContent || "")
+                        .replace(/\s+/g, " ")
+                        .trim());
+                }
+            }
+            const ariaLabelledBy = element.getAttribute("aria-labelledby");
+            if (ariaLabelledBy) {
+                for (const id of ariaLabelledBy.split(/\s+/)) {
+                    const labelElement = document.getElementById(id);
+                    if (labelElement) {
+                        labelParts.push((labelElement.textContent || "").replace(/\s+/g, " ").trim());
+                    }
+                }
+            }
+            const closestLabel = element.closest("label");
+            if (closestLabel) {
+                labelParts.push((closestLabel.innerText || closestLabel.textContent || "")
+                    .replace(/\s+/g, " ")
+                    .trim());
+            }
+            labelParts.push((element.getAttribute("aria-label") || "")
+                .replace(/\s+/g, " ")
+                .trim());
+            const options = element instanceof HTMLSelectElement
+                ? Array.from(element.options)
+                    .map((option) => (option.textContent || "").replace(/\s+/g, " ").trim())
+                    .filter(Boolean)
+                    .slice(0, 60)
+                : [];
+            return {
+                agentId,
+                marker,
+                label: labelParts
+                    .filter(Boolean)
+                    .join(" ")
+                    .replace(/\s+/g, " ")
+                    .trim(),
+                placeholder: (element.getAttribute("placeholder") || "")
+                    .replace(/\s+/g, " ")
+                    .trim(),
+                name: (element.getAttribute("name") || "")
+                    .replace(/\s+/g, " ")
+                    .trim(),
+                id: (element.id || "").replace(/\s+/g, " ").trim(),
+                tag: element.tagName.toLowerCase(),
+                inputType: inputType || element.tagName.toLowerCase(),
+                autocomplete: (element.getAttribute("autocomplete") || "")
+                    .replace(/\s+/g, " ")
+                    .trim()
+                    .toLowerCase(),
+                inputMode: (element.getAttribute("inputmode") || "")
+                    .replace(/\s+/g, " ")
+                    .trim()
+                    .toLowerCase(),
+                checked: element instanceof HTMLInputElement ? element.checked : undefined,
+                maxLength: element instanceof HTMLInputElement ||
+                    element instanceof HTMLTextAreaElement
+                    ? element.maxLength > 0
+                        ? element.maxLength
+                        : null
+                    : null,
+                options,
+            };
+        })
+            .filter(Boolean);
+    });
+    return fields.filter((field) => Boolean(field));
+}
+function scoreFieldMatch(field, target) {
+    return scoreFormFieldTargetMatch(field, target);
+}
+function findBestFillableField(fields, target) {
+    const ranked = fields
+        .map((field) => ({
+        field,
+        score: scoreFieldMatch(field, target),
+    }))
+        .filter((candidate) => candidate.score > 0)
+        .sort((left, right) => right.score - left.score);
+    return ranked[0]?.field ?? null;
+}
+async function resolveFillableFieldLocator(page, field) {
+    const fallbackLocator = page
+        .locator(`[data-site-agent-fill-field="${escapeAttributeValue(field.marker)}"]`)
+        .first();
+    return resolvePreferredFieldLocator({
+        page,
+        field,
+        fallbackLocator,
+        preferredNames: [
+            field.label,
+            field.placeholder,
+            field.name,
+            field.id,
+        ].filter(Boolean),
+    });
+}
+async function readCheckedState(locator, inputType) {
+    return locator.isChecked().catch(async () => {
+        return locator
+            .evaluate((element, expectedType) => {
+            if (element instanceof HTMLInputElement) {
+                return element.checked;
+            }
+            const nested = element.querySelector(`input[type="${expectedType}"], input[type="checkbox"], input[type="radio"]`);
+            return nested instanceof HTMLInputElement ? nested.checked : false;
+        }, inputType)
+            .catch(() => false);
+    });
+}
+async function setCheckedStateWithDomFallback(locator, inputType) {
+    await locator.evaluate((element, expectedType) => {
+        const nested = element.querySelector(`input[type="${expectedType}"], input[type="checkbox"], input[type="radio"]`);
+        const target = element instanceof HTMLInputElement
+            ? element
+            : nested instanceof HTMLInputElement
+                ? nested
+                : null;
+        if (!target) {
+            if (element instanceof HTMLElement) {
+                element.click();
+            }
+            return;
+        }
+        const prototype = window.HTMLInputElement.prototype;
+        const descriptor = Object.getOwnPropertyDescriptor(prototype, "checked");
+        if (descriptor?.set) {
+            descriptor.set.call(target, true);
+        }
+        else {
+            target.checked = true;
+        }
+        target.dispatchEvent(new Event("input", { bubbles: true }));
+        target.dispatchEvent(new Event("change", { bubbles: true }));
+    }, inputType);
+}
+async function readFieldRuntimeState(locator, field) {
+    if (field.inputType === "checkbox" || field.inputType === "radio") {
+        const checked = await readCheckedState(locator, field.inputType);
+        return {
+            value: checked ? "checked" : "",
+            checked,
+        };
+    }
+    if (field.tag === "select") {
+        const value = await locator
+            .evaluate((element) => {
+            if (!(element instanceof HTMLSelectElement)) {
+                return "";
+            }
+            return (element.selectedOptions[0]?.textContent ||
+                element.value ||
+                "")
+                .replace(/\s+/g, " ")
+                .trim();
+        })
+            .catch(() => "");
+        return {
+            value: normalizeText(value),
+            checked: null,
+        };
+    }
+    const value = await locator.inputValue().catch(async () => {
+        return locator
+            .evaluate((element) => {
+            if (element instanceof HTMLInputElement ||
+                element instanceof HTMLTextAreaElement) {
+                return element.value;
+            }
+            return "";
+        })
+            .catch(() => "");
+    });
+    return {
+        value: normalizeText(value),
+        checked: null,
+    };
+}
+function didFieldStateChange(before, after) {
+    return (normalizeKey(before.value) !== normalizeKey(after.value) ||
+        before.checked !== after.checked);
+}
+function doesFieldStateMatchExpected(args) {
+    if (args.operation.mode === "check") {
+        return args.after.checked === true;
+    }
+    return (normalizeKey(args.after.value) ===
+        normalizeKey(args.operation.expectedValue));
+}
+async function fillFieldValue(args) {
+    if (shouldCheckField(args.value) &&
+        (args.field.inputType === "checkbox" || args.field.inputType === "radio")) {
+        const preparedLocator = await prepareLocatorForInteraction(args.locator).catch(() => args.locator.first());
+        const labelLocator = args.locator
+            .locator("xpath=ancestor::label[1]")
+            .first();
+        const preparedLabelLocator = await prepareLocatorForInteraction(labelLocator).catch(() => null);
+        if (args.field.checked ||
+            (await readCheckedState(preparedLocator, args.field.inputType).catch(() => false))) {
+            return {
+                expectedValue: "checked",
+                mode: "check",
+            };
+        }
+        if (preparedLabelLocator) {
+            await preparedLabelLocator.click({ force: true }).catch(() => undefined);
+        }
+        let checkedAfterAttempt = await readCheckedState(preparedLocator, args.field.inputType).catch(() => false);
+        if (!checkedAfterAttempt) {
+            await preparedLocator.check({ force: true }).catch(async () => {
+                await preparedLocator.click({ force: true }).catch(() => undefined);
+            });
+            checkedAfterAttempt = await readCheckedState(preparedLocator, args.field.inputType).catch(() => false);
+        }
+        if (!checkedAfterAttempt && preparedLabelLocator) {
+            await preparedLabelLocator.click({ force: true }).catch(() => undefined);
+            checkedAfterAttempt = await readCheckedState(preparedLocator, args.field.inputType).catch(() => false);
+        }
+        if (!checkedAfterAttempt) {
+            await setCheckedStateWithDomFallback(preparedLocator, args.field.inputType).catch(() => undefined);
+        }
+        return {
+            expectedValue: "checked",
+            mode: "check",
+        };
+    }
+    if (args.field.tag === "select") {
+        const preparedLocator = await prepareLocatorForInteraction(args.locator);
+        const desired = normalizeText(args.value);
+        const matchedOption = findMatchingSelectOption(args.field.options, [
+            desired,
+        ]);
+        try {
+            await preparedLocator.selectOption({ label: desired });
+            return {
+                expectedValue: desired,
+                mode: "select",
+            };
+        }
+        catch {
+            if (matchedOption) {
+                await preparedLocator.selectOption({ label: matchedOption });
+                return {
+                    expectedValue: matchedOption,
+                    mode: "select",
+                };
+            }
+        }
+    }
+    const fittedValue = fitValueToField(args.field, args.value);
+    // Native date/time inputs require .fill() with ISO format — typeLikeHuman types
+    // individual characters which the browser's native picker interprets incorrectly
+    // (e.g. "1998-04-17" typed char-by-char becomes "12/09/80417").
+    const isNativeDateInput = [
+        "date",
+        "time",
+        "datetime-local",
+        "month",
+        "week",
+    ].includes(args.field.inputType);
+    if (isNativeDateInput) {
+        const preparedLocator = await prepareLocatorForInteraction(args.locator);
+        await preparedLocator.fill(fittedValue);
+        return {
+            expectedValue: fittedValue,
+            mode: "fill",
+        };
+    }
+    await typeLikeHuman(args.locator, fittedValue);
+    return {
+        expectedValue: fittedValue,
+        mode: "fill",
+    };
+}
+async function triggerLocatorClick(locator, options = {}) {
+    const preparedLocator = await prepareLocatorForInteraction(locator);
+    try {
+        await preparedLocator.click({
+            timeout: 4000,
+            ...(options.singleAttempt ? { noWaitAfter: true } : {}),
+        });
+        return options.singleAttempt
+            ? "playwright-click-single-attempt"
+            : "playwright-click";
+    }
+    catch (error) {
+        if (options.singleAttempt) {
+            throw error;
+        }
+        try {
+            await preparedLocator.click({ force: true, timeout: 4000 });
+            return "playwright-force-click";
+        }
+        catch {
+            await preparedLocator.evaluate((element) => {
+                if (!(element instanceof HTMLElement)) {
+                    return;
+                }
+                element.scrollIntoView({ block: "center", inline: "center" });
+                if (element instanceof HTMLButtonElement &&
+                    element.type === "submit" &&
+                    element.form) {
+                    element.form.requestSubmit(element);
+                    return;
+                }
+                if (element instanceof HTMLInputElement &&
+                    element.type === "submit" &&
+                    element.form) {
+                    element.form.requestSubmit(element);
+                    return;
+                }
+                element.click();
+            });
+            return "dom-click";
+        }
+    }
+}
+async function waitForPostActionState(page) {
+    await page.waitForLoadState("domcontentloaded").catch(() => undefined);
+    await page.waitForTimeout(250);
+    return readVisibleState(page);
+}
+function waitForClickDialog(page) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const timeoutId = setTimeout(() => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            page.off("dialog", onDialog);
+            resolve(null);
+        }, 1500);
+        const onDialog = (dialog) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeoutId);
+            const result = {
+                type: dialog.type(),
+                message: dialog.message(),
+                defaultValue: dialog.defaultValue(),
+                action: "accepted"
+            };
+            dialog.accept().then(() => resolve(result), () => resolve({ ...result, action: "dismissed" }));
+        };
+        page.once("dialog", onDialog);
+    });
+}
+export async function executeDecision(page, decision, preparedClick, options = {}) {
+    try {
+        if (decision.action === "scroll") {
+            await page.mouse.wheel(0, 850);
+            const after = await readVisibleState(page);
+            return {
+                success: true,
+                note: "Scrolled down page",
+                destinationUrl: after.url,
+                destinationTitle: after.title,
+                visibleTextSnippet: after.textSnippet,
+            };
+        }
+        if (decision.action === "wait") {
+            const before = await readVisibleState(page);
+            const startedAt = Date.now();
+            const waitContext = `${decision.thought} ${decision.expectation} ${decision.target}`.toLowerCase();
+            const waitMs = /\b(?:transaction|tx|sending|pending|broadcast|confirm|confirmation|settle|receipt)\b/.test(waitContext) ? 5000 : 1500;
+            await page.waitForTimeout(waitMs);
+            const after = await readVisibleState(page);
+            const elapsedMs = Date.now() - startedAt;
+            const { stateChanged, destinationLabel } = describeStateChange(before, after);
+            return {
+                success: true,
+                note: stateChanged
+                    ? `Waited ${elapsedMs}ms and the visible page changed to '${destinationLabel}'`
+                    : `Waited ${elapsedMs}ms with no clear visible page change`,
+                elapsedMs,
+                destinationUrl: after.url,
+                destinationTitle: after.title,
+                stateChanged,
+                visibleTextSnippet: after.textSnippet,
+            };
+        }
+        if (decision.action === "back") {
+            const before = await readVisibleState(page);
+            const startedAt = Date.now();
+            await page
+                .goBack({ waitUntil: "domcontentloaded" })
+                .catch(() => undefined);
+            const after = await readVisibleState(page);
+            const elapsedMs = Date.now() - startedAt;
+            const { stateChanged, destinationLabel } = describeStateChange(before, after);
+            return {
+                success: stateChanged,
+                note: stateChanged
+                    ? `Went back and reached '${destinationLabel}' after ${elapsedMs}ms`
+                    : `Tried to go back, but the visible page did not clearly change after ${elapsedMs}ms`,
+                elapsedMs,
+                destinationUrl: after.url,
+                destinationTitle: after.title,
+                stateChanged,
+                visibleTextSnippet: after.textSnippet,
+            };
+        }
+        if (decision.action === "extract") {
+            const after = await readVisibleState(page);
+            return {
+                success: true,
+                note: `Recorded page state at '${normalizeText(after.title) || after.url}' without interaction`,
+                destinationUrl: after.url,
+                destinationTitle: after.title,
+                visibleTextSnippet: after.textSnippet,
+            };
+        }
+        if (decision.action === "stop") {
+            return {
+                success: true,
+                stop: true,
+                note: "Planner decided to stop due to friction or completion",
+            };
+        }
+        const target = resolveDecisionTargetLabel(decision);
+        const targetId = decision.target_id.trim();
+        if (!target && !targetId) {
+            return {
+                success: false,
+                note: "Decision required a target but did not provide one",
+            };
+        }
+        if (decision.action === "click") {
+            const preparedClickResolution = preparedClick
+                ? { preparedClick }
+                : await prepareClickDecision(page, decision);
+            if (!preparedClickResolution.preparedClick) {
+                return {
+                    success: false,
+                    note: preparedClickResolution.note ??
+                        `Could not find clickable element for '${target || targetId}'`,
+                };
+            }
+            const before = await readVisibleState(page);
+            const neighborhoodBefore = await captureClickNeighborhood(preparedClickResolution.preparedClick.locator);
+            const startedAt = Date.now();
+            const dialogResultPromise = waitForClickDialog(page);
+            const clickStrategy = await triggerLocatorClick(preparedClickResolution.preparedClick.locator, options.singleClickAttempt ? { singleAttempt: true } : {});
+            const dialogResult = await dialogResultPromise;
+            let after = await waitForPostActionState(page);
+            let elapsedMs = Date.now() - startedAt;
+            let { stateChanged, destinationLabel } = describeStateChange(before, after);
+            if (!stateChanged) {
+                await page.waitForTimeout(1200);
+                after = await readVisibleState(page);
+                elapsedMs = Date.now() - startedAt;
+                ({ stateChanged, destinationLabel } = describeStateChange(before, after));
+            }
+            if (!stateChanged) {
+                const neighborhoodAfter = await captureClickNeighborhood(preparedClickResolution.preparedClick.locator);
+                if (neighborhoodBefore &&
+                    neighborhoodAfter &&
+                    neighborhoodBefore !== neighborhoodAfter) {
+                    stateChanged = true;
+                    destinationLabel = normalizeText(after.title) || after.url;
+                }
+            }
+            const blockedByInterstitial = isInterstitialState(after);
+            const dialogNote = dialogResult
+                ? ` Accepted ${dialogResult.type} dialog${dialogResult.message ? `: ${truncateLabel(dialogResult.message, 140)}` : ""}.`
+                : "";
+            if (blockedByInterstitial) {
+                return {
+                    success: false,
+                    note: `Clicked '${target || targetId}' and hit a security or verification interstitial after ${elapsedMs}ms.${dialogNote}`,
+                    matchedBy: `${preparedClickResolution.preparedClick.matchedBy}:${clickStrategy}`,
+                    elapsedMs,
+                    destinationUrl: after.url,
+                    destinationTitle: after.title,
+                    stateChanged,
+                    visibleTextSnippet: after.textSnippet,
+                    ...(preparedClickResolution.preparedClick.clickIndicator
+                        ? {
+                            clickIndicator: preparedClickResolution.preparedClick.clickIndicator,
+                        }
+                        : {}),
+                };
+            }
+            return {
+                success: stateChanged || Boolean(dialogResult),
+                note: stateChanged
+                    ? `Clicked '${target || targetId}' and reached '${destinationLabel}' after ${elapsedMs}ms.${dialogNote}`
+                    : dialogResult
+                        ? `Clicked '${target || targetId}' and accepted a ${dialogResult.type} dialog after ${elapsedMs}ms${dialogResult.message ? `: ${truncateLabel(dialogResult.message, 140)}` : ""}`
+                        : `Clicked '${target || targetId}' but the page showed no clear visible change after ${elapsedMs}ms`,
+                matchedBy: `${preparedClickResolution.preparedClick.matchedBy}:${clickStrategy}`,
+                elapsedMs,
+                destinationUrl: after.url,
+                destinationTitle: after.title,
+                stateChanged: stateChanged || Boolean(dialogResult),
+                visibleTextSnippet: after.textSnippet,
+                ...(preparedClickResolution.preparedClick.clickIndicator
+                    ? {
+                        clickIndicator: preparedClickResolution.preparedClick.clickIndicator,
+                    }
+                    : {}),
+            };
+        }
+        if (decision.action === "type") {
+            const fields = await collectVisibleFillableFields(page);
+            const matchedField = targetId
+                ? (fields.find((field) => field.agentId === targetId) ?? null)
+                : findBestFillableField(fields, target);
+            if (!matchedField) {
+                return {
+                    success: false,
+                    note: `Could not find input for '${target || targetId}'`,
+                };
+            }
+            const resolvedField = await resolveFillableFieldLocator(page, matchedField);
+            const locator = resolvedField.locator;
+            const beforeFieldState = await readFieldRuntimeState(locator, matchedField).catch(() => ({
+                value: "",
+                checked: matchedField.checked ?? null,
+            }));
+            const operation = await fillFieldValue({
+                locator,
+                field: matchedField,
+                value: decision.text || "",
+            });
+            const afterFieldState = await readFieldRuntimeState(locator, matchedField).catch(() => beforeFieldState);
+            const stateChanged = didFieldStateChange(beforeFieldState, afterFieldState);
+            const valueApplied = doesFieldStateMatchExpected({
+                after: afterFieldState,
+                operation,
+            });
+            const after = await readVisibleState(page);
+            if (!valueApplied) {
+                return {
+                    success: false,
+                    note: `Tried to fill '${target || targetId}', but the field did not keep the requested value`,
+                    matchedBy: `target_id:${matchedField.tag}/${matchedField.inputType}:${resolvedField.strategy}`,
+                    destinationUrl: after.url,
+                    destinationTitle: after.title,
+                    stateChanged,
+                    visibleTextSnippet: after.textSnippet,
+                };
+            }
+            return {
+                success: true,
+                note: stateChanged
+                    ? `Filled '${target || targetId}'`
+                    : `Field '${target || targetId}' already held the requested value`,
+                matchedBy: `target_id:${matchedField.tag}/${matchedField.inputType}:${resolvedField.strategy}`,
+                destinationUrl: after.url,
+                destinationTitle: after.title,
+                stateChanged,
+                visibleTextSnippet: after.textSnippet,
+            };
+        }
+        return { success: false, note: `Unsupported action '${decision.action}'` };
+    }
+    catch (error) {
+        return {
+            success: false,
+            note: `Action failed: ${cleanErrorMessage(error)}`,
+        };
+    }
+}