@nuanu-ai/agentbrowse 0.2.7 → 0.2.8

package/dist/commands/act.js

@@ -1,73 +1,858 @@
 /**
- * browse act "<instruction>" [--variables '<json>'] — Perform an action on the page.
+ * browse act <targetRef> <action> [value] — Perform a deterministic action on a stored target.
  */
-import { connectStagehand, getPageInfo } from '../stagehand.js';
-import { outputJSON, outputError } from '../output.js';
-const ROOT_SELECTORS = new Set(['/', '/html', 'xpath=/', 'xpath=/html']);
-const CONCRETE_TARGET_METHODS = new Set([
-    'click',
-    'doubleClick',
-    'fill',
-    'type',
-    'hover',
-    'dragAndDrop',
-    'selectOption',
-    'selectOptionFromDropdown',
-    'clickAndHold',
-]);
-// Stagehand's act prompt says "return an empty object" when no element matches,
-// but its act schema requires a concrete elementId/method pair. In practice,
-// that contradiction sometimes produces a synthetic page-root action
-// (`xpath=/html`) which Playwright accepts as a successful no-op click/type.
-function isSyntheticRootSuccess(result) {
-    if (!result.success || !Array.isArray(result.actions) || result.actions.length === 0) {
+import { saveSession } from '../session.js';
+import { clearProtectedExposure, getProtectedExposure, getSurface, getTarget, incrementMetric, locatorCandidateKey, markTargetLifecycle, recordActionResult, registerPage, setTargetAvailability, setCurrentPage, updateTarget, } from '../runtime-state.js';
+import { outputContractFailure, outputFailure, outputJSON } from '../output.js';
+import { capturePageObservation, captureLocatorContextHash, captureLocatorState, createAcceptanceProbe, diagnoseNoObservableProgress, locatorStateChanged, pageObservationChanged, rankLocatorCandidates, shouldVerifyObservableProgress, waitForAcceptanceProbe, } from './action-acceptance.js';
+import { captureActionFailureArtifacts, startActionTrace } from './action-artifacts.js';
+import { buildLocator, resolveLocatorRoot } from './action-fallbacks.js';
+import { projectActionValue } from './action-value-projection.js';
+import { applyActionWithFallbacks } from './action-executor.js';
+import { BROWSE_ACTIONS, isBrowseAction } from './browse-actions.js';
+import { isCompatibleMutableFieldBinding, normalizePageSignature, readLocatorBindingSnapshot, readLocatorDomSignature, } from './descriptor-validation.js';
+import { isLocatorUserActionable } from './user-actionable.js';
+import { resolveSurfaceScopeRoot } from './target-resolution.js';
+import { buildProtectedArtifactsSuppressed } from '../secrets/protected-artifact-guard.js';
+import { connectPlaywright, disconnectPlaywright, listPages, resolvePageByRef, syncSessionPage, } from '../playwright-runtime.js';
+function ensureValue(action, value) {
+    if (action === 'click')
+        return undefined;
+    if (typeof value === 'string' && value.length > 0)
+        return value;
+    throw new Error(`Act value is required for action: ${action}`);
+}
+function emitActPreflightFailure(params) {
+    return outputContractFailure({
+        error: params.error,
+        outcomeType: params.outcomeType,
+        message: params.message,
+        reason: params.reason,
+        targetRef: params.targetRef,
+        action: params.action,
+    });
+}
+function reasonForNoObservableProgressDiagnosis(diagnosis) {
+    switch (diagnosis.kind) {
+        case 'validation-blocked':
+            return 'The page stayed in place and surfaced validation blockers after the action.';
+        case 'target-blocked':
+            return 'The target stayed in place but remained blocked or unchanged after the action.';
+        case 'overlay-blocked':
+            return 'A blocking overlay prevented the action from producing observable progress.';
+        case 'site-noop':
+            return 'The page stayed in place and did not expose any observable progress after the action.';
+    }
+}
+function describeActFailure(params) {
+    if (params.staleReason) {
+        const reason = params.staleReason === 'page-signature-mismatch'
+            ? 'The page changed since this target was observed, so the saved page signature no longer matches.'
+            : params.staleReason === 'dom-signature-mismatch'
+                ? 'The target changed since it was observed, so the saved DOM signature no longer matches.'
+                : 'The saved locator no longer resolves to a live element on the page.';
+        return {
+            outcomeType: 'binding_stale',
+            message: 'The requested action cannot continue because the target is stale.',
+            reason,
+        };
+    }
+    if (params.diagnosis) {
+        return {
+            outcomeType: 'blocked',
+            message: 'The action did not produce observable progress.',
+            reason: reasonForNoObservableProgressDiagnosis(params.diagnosis),
+        };
+    }
+    const rawReason = params.failureMessage.replace(/^Act failed:\s*/, '');
+    if (rawReason === 'target_disabled') {
+        return {
+            outcomeType: 'blocked',
+            message: 'The requested action cannot continue because the target is disabled.',
+            reason: 'The runtime resolved the target, but the browser marked it as disabled.',
+        };
+    }
+    if (rawReason === 'target_readonly') {
+        return {
+            outcomeType: 'blocked',
+            message: 'The requested action cannot continue because the target is read-only.',
+            reason: 'The runtime resolved the target, but the browser marked it as read-only.',
+        };
+    }
+    if (rawReason === 'target_surface_inactive') {
+        return {
+            outcomeType: 'blocked',
+            message: 'The requested action cannot continue because the target surface is inactive.',
+            reason: 'The target belongs to a surface that is no longer active or available.',
+        };
+    }
+    return {
+        outcomeType: 'blocked',
+        message: 'The requested action could not be completed.',
+        reason: rawReason,
+    };
+}
+export { BROWSE_ACTIONS, isBrowseAction };
+function redactNoObservableProgressDiagnosis(diagnosis) {
+    return {
+        kind: diagnosis.kind,
+        ...(diagnosis.targetState ? { targetState: diagnosis.targetState } : {}),
+        ...(diagnosis.messages.length > 0
+            ? {
+                messagesRedacted: true,
+                messageCount: diagnosis.messages.length,
+            }
+            : {}),
+        ...(diagnosis.invalidFields.length > 0
+            ? {
+                invalidFieldsRedacted: true,
+                invalidFieldCount: diagnosis.invalidFields.length,
+            }
+            : {}),
+        ...(diagnosis.blockingOverlays.length > 0
+            ? {
+                blockingOverlaysRedacted: true,
+                blockingOverlayCount: diagnosis.blockingOverlays.length,
+            }
+            : {}),
+    };
+}
+function isEditableLikeTarget(target) {
+    if (target.controlFamily === 'text-input' ||
+        target.controlFamily === 'select' ||
+        target.controlFamily === 'datepicker') {
+        return true;
+    }
+    const kind = (target.kind ?? '').toLowerCase();
+    const role = (target.semantics?.role ?? '').toLowerCase();
+    return (['input', 'textarea', 'select', 'combobox'].includes(kind) ||
+        ['textbox', 'combobox', 'searchbox', 'spinbutton'].includes(role) ||
+        target.allowedActions.includes('fill') ||
+        target.allowedActions.includes('type') ||
+        target.allowedActions.includes('select'));
+}
+function shouldWatchForNewPageAfterAction(target, action) {
+    if (action === 'click') {
+        return true;
+    }
+    if (action !== 'press') {
         return false;
     }
-    const [firstAction] = result.actions;
-    const selector = firstAction?.selector?.trim();
-    const method = firstAction?.method?.trim();
-    return ROOT_SELECTORS.has(selector ?? '') && CONCRETE_TARGET_METHODS.has(method ?? '');
+    return !isEditableLikeTarget(target);
+}
+function targetUsesSurfaceAsPrimaryLocator(target, surface) {
+    const surfaceCandidates = new Set(surface.locatorCandidates.map(locatorCandidateKey));
+    return target.locatorCandidates.some((candidate) => surfaceCandidates.has(locatorCandidateKey(candidate)));
+}
+async function resolveActionRoot(page, target, attempts, surface) {
+    const baseRoot = resolveLocatorRoot(page, target.framePath ?? surface?.framePath);
+    if (!surface) {
+        return {
+            baseRoot,
+            locatorRoot: baseRoot,
+            surfaceRoot: null,
+        };
+    }
+    const surfaceRoot = await resolveSurfaceScopeRoot(page, surface, attempts);
+    if (surfaceRoot) {
+        if (targetUsesSurfaceAsPrimaryLocator(target, surface)) {
+            attempts.push('surface.resolve.self-target');
+            return {
+                baseRoot,
+                locatorRoot: baseRoot,
+                surfaceRoot,
+            };
+        }
+        return {
+            baseRoot,
+            locatorRoot: surfaceRoot,
+            surfaceRoot,
+        };
+    }
+    attempts.push('surface.resolve.fallback:page');
+    return {
+        baseRoot,
+        locatorRoot: baseRoot,
+        surfaceRoot: null,
+    };
+}
+function resolveLocatorRootForCandidate(baseRoot, defaultRoot, surfaceRoot, candidate) {
+    if (candidate.scope === 'root') {
+        return baseRoot;
+    }
+    if (candidate.scope === 'surface') {
+        return surfaceRoot;
+    }
+    return defaultRoot;
+}
+async function prepareLocatorForAction(locator, action, strategy, attempts, options) {
+    const count = await locator.count().catch(() => 0);
+    if (count === 0) {
+        attempts.push(`resolve.skip:${strategy}:empty`);
+        return { locator: null };
+    }
+    if (action !== 'click' && count > 1) {
+        attempts.push(`resolve.skip:${strategy}:ambiguous:${count}`);
+        return { locator: null };
+    }
+    let resolvedLocator = locator.first();
+    if (action === 'click' && count > 1) {
+        const visibleCandidates = [];
+        for (let index = 0; index < count; index += 1) {
+            const candidate = locator.nth(index);
+            const visible = await isLocatorUserActionable(candidate);
+            if (!visible) {
+                continue;
+            }
+            visibleCandidates.push(candidate);
+        }
+        if (visibleCandidates.length === 1) {
+            attempts.push(`resolve.visible-unique:${strategy}`);
+            resolvedLocator = visibleCandidates[0] ?? locator.first();
+        }
+        else if (visibleCandidates.length > 1) {
+            attempts.push(`resolve.skip:${strategy}:ambiguous-visible:${visibleCandidates.length}`);
+            return { locator: null };
+        }
+        else {
+            attempts.push(`resolve.skip:${strategy}:hidden`);
+            return { locator: null };
+        }
+    }
+    const visible = await isLocatorUserActionable(resolvedLocator);
+    if (!visible) {
+        attempts.push(`resolve.skip:${strategy}:hidden`);
+        return { locator: null };
+    }
+    const disabled = await resolvedLocator.isDisabled?.().catch(() => false);
+    if (disabled) {
+        attempts.push(`resolve.skip:${strategy}:disabled`);
+        return { locator: null, blockedReason: 'disabled' };
+    }
+    if (action === 'fill' || action === 'type' || options?.allowDescendantPressFallback) {
+        const editable = await resolvedLocator.isEditable().catch(() => false);
+        if (!editable) {
+            const descendantSelector = options?.allowDescendantPressFallback
+                ? 'input:not([type="hidden"]), textarea, select, [contenteditable="true"], [role="textbox"], [role="combobox"]'
+                : 'input:not([type="hidden"]), textarea, select, [contenteditable="true"]';
+            const descendantCandidates = resolvedLocator.locator(descendantSelector);
+            const descendantCount = await descendantCandidates.count().catch(() => 0);
+            const candidateDescendants = [];
+            for (let index = 0; index < descendantCount; index += 1) {
+                const descendant = descendantCandidates.nth(index);
+                const descendantVisible = await isLocatorUserActionable(descendant);
+                if (!descendantVisible)
+                    continue;
+                if (!options?.allowDescendantPressFallback || action === 'fill' || action === 'type') {
+                    const descendantEditable = await descendant.isEditable().catch(() => false);
+                    if (!descendantEditable)
+                        continue;
+                }
+                candidateDescendants.push(descendant);
+            }
+            if (candidateDescendants.length === 1) {
+                attempts.push(options?.allowDescendantPressFallback && action === 'press'
+                    ? `resolve.descendant-press:${strategy}`
+                    : `resolve.descendant-editable:${strategy}`);
+                return { locator: candidateDescendants[0] ?? null };
+            }
+            if (candidateDescendants.length > 1) {
+                attempts.push(`resolve.skip:${strategy}:descendant-ambiguous:${candidateDescendants.length}`);
+                return { locator: null };
+            }
+            if (options?.allowReadonlyFallback) {
+                attempts.push(`resolve.readonly-fallback:${strategy}`);
+                return { locator: resolvedLocator };
+            }
+            attempts.push(`resolve.skip:${strategy}:readonly`);
+            return { locator: null, blockedReason: 'readonly' };
+        }
+    }
+    return { locator: resolvedLocator };
 }
-export async function act(cdpUrl, instruction, variables) {
-    let stagehand;
-    let url = 'unknown';
-    let title = 'unknown';
+async function recoverLocatorFromSurfaceRoot(locatorRoot, target, action, attempts) {
+    if (action !== 'press' ||
+        !(target.controlFamily === 'text-input' ||
+            target.controlFamily === 'select' ||
+            target.controlFamily === 'datepicker') ||
+        typeof locatorRoot.locator !== 'function') {
+        return null;
+    }
+    const descendants = locatorRoot.locator('input:not([type="hidden"]), textarea, select, [contenteditable="true"], [role="textbox"], [role="combobox"]');
+    const count = await descendants.count().catch(() => 0);
+    const visibleDescendants = [];
+    for (let index = 0; index < count; index += 1) {
+        const descendant = descendants.nth(index);
+        const visible = await isLocatorUserActionable(descendant);
+        if (!visible) {
+            continue;
+        }
+        visibleDescendants.push(descendant);
+    }
+    if (visibleDescendants.length === 1) {
+        attempts.push('resolve.surface-descendant:press');
+        return visibleDescendants[0] ?? null;
+    }
+    if (visibleDescendants.length > 1) {
+        attempts.push(`resolve.skip:surface-descendant-ambiguous:${visibleDescendants.length}`);
+    }
+    return null;
+}
+async function capturePopupIfOpened(session, beforePages, afterPages, currentPageRef, attempts) {
+    const popup = afterPages.find((page) => !beforePages.includes(page));
+    if (!popup)
+        return null;
+    const [url, title] = await Promise.all([
+        Promise.resolve(popup.url()),
+        popup.title().catch(() => ''),
+    ]);
+    const page = registerPage(session, {
+        url,
+        title,
+        openerPageRef: currentPageRef,
+        makeCurrent: true,
+    });
+    attempts.push('popup-captured');
+    return page.pageRef;
+}
+async function waitForPopup(context) {
+    try {
+        return await context.waitForEvent('page', { timeout: 500 });
+    }
+    catch {
+        return null;
+    }
+}
+async function waitForLatePage(browser, beforePages, timeoutMs = 2_000) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+        const candidate = listPages(browser).find((page) => !beforePages.includes(page));
+        if (candidate) {
+            return candidate;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    return null;
+}
+export async function act(session, targetRef, action, value) {
+    const target = getTarget(session, targetRef);
+    if (!target) {
+        return emitActPreflightFailure({
+            error: 'unknown_target_ref',
+            outcomeType: 'blocked',
+            message: 'The requested targetRef is unknown.',
+            reason: `No stored target matches targetRef ${targetRef}.`,
+            targetRef,
+            action,
+        });
+    }
+    if (target.lifecycle !== 'live') {
+        return emitActPreflightFailure({
+            error: 'stale_target_ref',
+            outcomeType: 'binding_stale',
+            message: 'The requested target is no longer live.',
+            reason: `Target ${targetRef} is ${target.lifecycle}${target.lifecycleReason ? ` because ${target.lifecycleReason}` : ''}.`,
+            targetRef,
+            action,
+        });
+    }
+    if (target.capability !== 'actionable') {
+        return emitActPreflightFailure({
+            error: 'target_not_actionable',
+            outcomeType: 'unsupported',
+            message: 'The requested target cannot be used for actions.',
+            reason: `Target ${targetRef} has capability ${target.capability}, not actionable.`,
+            targetRef,
+            action,
+        });
+    }
+    if (!target.allowedActions.includes(action)) {
+        return emitActPreflightFailure({
+            error: 'action_not_allowed_for_target',
+            outcomeType: 'unsupported',
+            message: 'The requested action is not allowed for this target.',
+            reason: `Target ${targetRef} allows ${target.allowedActions.join(', ')}, not ${action}.`,
+            targetRef,
+            action,
+        });
+    }
+    if (target.availability.state === 'gated' &&
+        (target.availability.reason === 'occupied' || target.availability.reason === 'not-selectable')) {
+        return emitActPreflightFailure({
+            error: 'target_gated',
+            outcomeType: 'blocked',
+            message: 'The requested target is currently gated.',
+            reason: `Target ${targetRef} is gated${target.availability.reason ? ` because ${target.availability.reason}` : ''}.`,
+            targetRef,
+            action,
+        });
+    }
+    const surface = target.surfaceRef ? getSurface(session, target.surfaceRef) : null;
+    if (surface && surface.lifecycle !== 'live') {
+        setTargetAvailability(session, targetRef, 'surface-inactive', surface.lifecycleReason ?? `surface-${surface.lifecycle}`);
+        saveSession(session);
+        return emitActPreflightFailure({
+            error: 'target_surface_not_live',
+            outcomeType: 'blocked',
+            message: 'The requested target surface is no longer live.',
+            reason: `Surface ${surface.ref} is ${surface.lifecycle}${surface.lifecycleReason ? ` because ${surface.lifecycleReason}` : ''}.`,
+            targetRef,
+            action,
+        });
+    }
+    if (surface && surface.availability.state !== 'available') {
+        setTargetAvailability(session, targetRef, 'surface-inactive', surface.availability.reason ?? `surface-${surface.availability.state}`);
+        saveSession(session);
+        return emitActPreflightFailure({
+            error: 'target_surface_unavailable',
+            outcomeType: 'blocked',
+            message: 'The requested target surface is not currently available.',
+            reason: `Surface ${surface.ref} is ${surface.availability.state}${surface.availability.reason ? ` because ${surface.availability.reason}` : ''}.`,
+            targetRef,
+            action,
+        });
+    }
+    const actionValue = ensureValue(action, value);
+    const attempts = [];
+    const startedAt = Date.now();
+    let browser = null;
     let failureMessage = null;
+    let failureArtifacts;
+    let currentPage = null;
+    let currentPageRef = target.pageRef;
+    const startingPageUrl = session.runtime?.pages?.[target.pageRef]?.url ?? null;
+    const protectedExposureAtStart = getProtectedExposure(session, target.pageRef);
+    let locatorStrategy = null;
+    let recoveredAfterError = false;
+    let recoveredAcceptancePolicy = null;
+    let staleReason = null;
+    let progressProbe = null;
+    let noProgressDiagnosis = null;
+    let liveTarget = target;
+    let trace = {
+        finishSuccess: async () => { },
+        finishFailure: async (_artifactDir) => undefined,
+    };
     try {
-        stagehand = await connectStagehand(cdpUrl);
+        browser = await connectPlaywright(session.cdpUrl);
     }
     catch (err) {
-        return outputError(`Failed to connect to browser: ${err instanceof Error ? err.message : String(err)}`);
+        return emitActPreflightFailure({
+            error: 'browser_connection_failed',
+            outcomeType: 'blocked',
+            message: 'The action could not start because AgentBrowse failed to connect to the browser.',
+            reason: err instanceof Error ? err.message : String(err),
+            targetRef,
+            action,
+        });
     }
     try {
-        const result = await stagehand.act(instruction, variables ? { variables } : undefined);
-        ({ url, title } = await getPageInfo(stagehand));
-        await stagehand.close();
-        if (isSyntheticRootSuccess(result)) {
-            failureMessage =
-                `Act failed: Stagehand selected the page root instead of a concrete element. ` +
-                    `This usually means no actionable match was found for: ${instruction} ` +
-                    `(page: ${title} — ${url})`;
-        }
-        else if (!result.success) {
-            const message = typeof result.message === 'string' && result.message.trim().length > 0
-                ? result.message.trim()
-                : `Stagehand could not complete the requested action: ${instruction}`;
-            failureMessage = `Act failed: ${message} (page: ${title} — ${url})`;
+        const page = await resolvePageByRef(browser, session, target.pageRef);
+        currentPage = page;
+        setCurrentPage(session, target.pageRef);
+        const { url } = await syncSessionPage(session, target.pageRef, page);
+        trace = await startActionTrace(page, {
+            suppressSensitiveArtifacts: Boolean(protectedExposureAtStart),
+        });
+        if (liveTarget.pageSignature && normalizePageSignature(url) !== liveTarget.pageSignature) {
+            staleReason = 'page-signature-mismatch';
+            throw new Error('stale_target_page_signature_changed');
         }
-        else {
-            return outputJSON({
-                success: true,
-                action: result.actionDescription ?? instruction,
-                message: result.message,
-                url,
-                title,
+        const tryRebindMutableFieldTarget = async (resolvedLocator, strategy) => {
+            if (!liveTarget.domSignature) {
+                return false;
+            }
+            const snapshot = await readLocatorBindingSnapshot(resolvedLocator).catch(() => null);
+            if (!snapshot?.domSignature || snapshot.domSignature === liveTarget.domSignature) {
+                return false;
+            }
+            if (!isCompatibleMutableFieldBinding(liveTarget, snapshot)) {
+                return false;
+            }
+            attempts.push(`domSignature.rebound:${strategy}`);
+            const updatedTarget = updateTarget(session, targetRef, {
+                domSignature: snapshot.domSignature,
+                label: snapshot.label ?? liveTarget.label,
+                lifecycle: 'live',
+                lifecycleReason: undefined,
+                availability: { state: 'available' },
+                semantics: {
+                    ...liveTarget.semantics,
+                    name: snapshot.label ?? liveTarget.semantics?.name,
+                    role: snapshot.role ?? liveTarget.semantics?.role,
+                },
             });
+            if (updatedTarget) {
+                liveTarget = updatedTarget;
+            }
+            return true;
+        };
+        const assertResolvedTargetStillValid = async (resolvedLocator, stage) => {
+            if (liveTarget.pageSignature && normalizePageSignature(page.url()) !== liveTarget.pageSignature) {
+                attempts.push(`stale.page-signature:${stage}`);
+                staleReason = 'page-signature-mismatch';
+                throw new Error('stale_target_page_signature_changed');
+            }
+            const liveCount = await resolvedLocator.count().catch(() => 0);
+            if (liveCount === 0) {
+                attempts.push(`stale.locator:${stage}`);
+                staleReason = 'locator-resolution-failed';
+                throw new Error('stale_target_locator_resolution_failed');
+            }
+            if (liveTarget.domSignature) {
+                const rebound = await tryRebindMutableFieldTarget(resolvedLocator, stage);
+                if (!rebound) {
+                    const liveSignature = await readLocatorDomSignature(resolvedLocator).catch(() => null);
+                    if (liveSignature && liveSignature !== liveTarget.domSignature) {
+                        attempts.push(`stale.dom-signature:${stage}`);
+                        staleReason = 'dom-signature-mismatch';
+                        throw new Error('stale_target_dom_signature_changed');
+                    }
+                }
+            }
+        };
+        let resolvedBy = null;
+        const beforePages = listPages(browser);
+        const shouldCheckProgress = shouldVerifyObservableProgress(target, action);
+        const beforePageObservation = shouldCheckProgress ? await capturePageObservation(page) : null;
+        const { baseRoot, locatorRoot, surfaceRoot } = await resolveActionRoot(page, target, attempts, surface);
+        let lastError = null;
+        let sawDomSignatureMismatch = false;
+        let sawDisabledTarget = false;
+        let sawReadonlyTarget = false;
+        const attemptResolvedLocator = async (resolvedLocator, strategy, options) => {
+            if (!options?.skipDomSignature && liveTarget.domSignature) {
+                const rebound = await tryRebindMutableFieldTarget(resolvedLocator, strategy);
+                if (!rebound) {
+                    const liveSignature = await readLocatorDomSignature(resolvedLocator);
+                    if (liveSignature && liveSignature !== liveTarget.domSignature) {
+                        attempts.push(`domSignature.mismatch:${strategy}`);
+                        sawDomSignatureMismatch = true;
+                        return false;
+                    }
+                }
+            }
+            let acceptanceProbe = null;
+            try {
+                const valueProjection = await projectActionValue({
+                    target,
+                    action,
+                    actionValue,
+                    locator: resolvedLocator,
+                    attempts,
+                });
+                const executionValue = valueProjection?.executionValue ?? actionValue;
+                const acceptanceValue = valueProjection?.acceptanceValue ?? actionValue;
+                acceptanceProbe = await createAcceptanceProbe({
+                    session,
+                    page,
+                    target,
+                    action,
+                    actionValue: acceptanceValue,
+                    locator: resolvedLocator,
+                    beforePageObservation,
+                });
+                attempts.push(`resolve:${strategy}`);
+                const usedFallback = await applyActionWithFallbacks(page, locatorRoot, resolvedLocator, action, executionValue, attempts, target.controlFamily, {
+                    guards: {
+                        assertStillValid: async (stage) => {
+                            await assertResolvedTargetStillValid(resolvedLocator, stage);
+                        },
+                    },
+                });
+                if (usedFallback) {
+                    incrementMetric(session, 'fallbackActions');
+                }
+                resolvedBy = 'playwright-locator';
+                locatorStrategy = strategy;
+                progressProbe = acceptanceProbe;
+                setTargetAvailability(session, targetRef, 'available');
+                return true;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                const shouldAttemptAcceptanceRecovery = acceptanceProbe !== null &&
+                    (acceptanceProbe.policy === 'value-change' ||
+                        acceptanceProbe.policy === 'selection' ||
+                        acceptanceProbe.policy === 'date-selection' ||
+                        ((acceptanceProbe.policy === 'navigation' || acceptanceProbe.policy === 'submit') &&
+                            staleReason !== null &&
+                            staleReason !== 'page-signature-mismatch'));
+                if (acceptanceProbe !== null && shouldAttemptAcceptanceRecovery) {
+                    const acceptance = await waitForAcceptanceProbe(acceptanceProbe).catch(() => null);
+                    if (acceptance?.polls && acceptance.polls > 1) {
+                        attempts.push(`acceptance.polled:${acceptance.polls}`);
+                    }
+                    if (acceptance?.accepted) {
+                        attempts.push(`acceptance.recovered:${acceptanceProbe.policy}`);
+                        incrementMetric(session, 'fallbackActions');
+                        resolvedBy = 'playwright-locator';
+                        locatorStrategy = strategy;
+                        progressProbe = null;
+                        lastError = null;
+                        recoveredAfterError = true;
+                        recoveredAcceptancePolicy = acceptanceProbe.policy;
+                        setTargetAvailability(session, targetRef, 'available');
+                        return true;
+                    }
+                }
+                if (staleReason) {
+                    throw lastError;
+                }
+                await assertResolvedTargetStillValid(resolvedLocator, `after-error:${strategy}`);
+                return false;
+            }
+        };
+        const watchForNewPage = shouldWatchForNewPageAfterAction(target, action);
+        const popupPromise = watchForNewPage
+            ? waitForPopup(page.context())
+            : Promise.resolve(null);
+        for (const candidate of rankLocatorCandidates(target.locatorCandidates, action)) {
+            const candidateRoot = resolveLocatorRootForCandidate(baseRoot, locatorRoot, surfaceRoot, candidate);
+            if (!candidateRoot) {
+                attempts.push(`resolve.skip:${candidate.strategy}:surface-unavailable`);
+                continue;
+            }
+            const locator = buildLocator(candidateRoot, candidate);
+            if (!locator)
+                continue;
+            const preparedLocator = await prepareLocatorForAction(locator, action, candidate.strategy, attempts, {
+                allowReadonlyFallback: action === 'fill' && target.controlFamily === 'datepicker',
+                allowDescendantPressFallback: action === 'press' &&
+                    (target.controlFamily === 'text-input' ||
+                        target.controlFamily === 'select' ||
+                        target.controlFamily === 'datepicker'),
+            });
+            if (preparedLocator.blockedReason === 'disabled') {
+                sawDisabledTarget = true;
+            }
+            if (preparedLocator.blockedReason === 'readonly') {
+                sawReadonlyTarget = true;
+            }
+            const resolvedLocator = preparedLocator.locator;
+            if (!resolvedLocator) {
+                continue;
+            }
+            const resolved = await attemptResolvedLocator(resolvedLocator, candidate.strategy);
+            if (resolved) {
+                break;
+            }
+        }
+        if (!resolvedBy && !lastError && surfaceRoot) {
+            const recoveredLocator = await recoverLocatorFromSurfaceRoot(surfaceRoot, target, action, attempts);
+            if (recoveredLocator) {
+                await attemptResolvedLocator(recoveredLocator, 'surface-descendant', {
+                    skipDomSignature: true,
+                });
+            }
         }
+        if (!resolvedBy) {
+            if (sawDomSignatureMismatch) {
+                staleReason = 'dom-signature-mismatch';
+                throw new Error('stale_target_dom_signature_changed');
+            }
+            if (sawDisabledTarget) {
+                setTargetAvailability(session, targetRef, 'gated', 'disabled');
+                throw new Error('target_disabled');
+            }
+            if (sawReadonlyTarget && (action === 'fill' || action === 'type')) {
+                setTargetAvailability(session, targetRef, 'gated', 'readonly');
+                throw new Error('target_readonly');
+            }
+            if (!lastError &&
+                target.surfaceRef &&
+                (target.acceptancePolicy === 'selection' || target.acceptancePolicy === 'date-selection')) {
+                setTargetAvailability(session, targetRef, 'surface-inactive', 'surface-not-active');
+                throw new Error('target_surface_inactive');
+            }
+            if (!resolvedBy) {
+                if (!lastError &&
+                    (target.controlFamily === 'text-input' ||
+                        target.controlFamily === 'select' ||
+                        target.controlFamily === 'datepicker')) {
+                    staleReason = 'locator-resolution-failed';
+                    throw new Error('stale_target_locator_resolution_failed');
+                }
+                if (lastError) {
+                    throw lastError;
+                }
+                throw new Error('deterministic_target_resolution_failed');
+            }
+        }
+        const popup = await popupPromise;
+        const latePage = !popup && watchForNewPage ? await waitForLatePage(browser, beforePages) : null;
+        if (latePage) {
+            attempts.push('late-page-captured');
+        }
+        const discoveredPage = popup ?? latePage;
+        const afterPages = discoveredPage ? [...beforePages, discoveredPage] : listPages(browser);
+        const popupPageRef = await capturePopupIfOpened(session, beforePages, afterPages, target.pageRef, attempts);
+        const finalPageRef = popupPageRef ?? target.pageRef;
+        currentPageRef = finalPageRef;
+        if (popupPageRef) {
+            const popupPage = await resolvePageByRef(browser, session, popupPageRef);
+            await syncSessionPage(session, popupPageRef, popupPage);
+        }
+        else {
+            const syncedPage = await syncSessionPage(session, target.pageRef, page);
+            if (startingPageUrl && syncedPage.url && syncedPage.url !== startingPageUrl) {
+                clearProtectedExposure(session, target.pageRef);
+            }
+            const finalProgressProbe = progressProbe;
+            if (finalProgressProbe) {
+                const acceptance = await waitForAcceptanceProbe(finalProgressProbe);
+                const afterPageObservation = acceptance.afterPageObservation;
+                const accepted = acceptance.accepted;
+                if (acceptance.polls > 1) {
+                    attempts.push(`acceptance.polled:${acceptance.polls}`);
+                }
+                if (!accepted && finalProgressProbe.policy === 'value-change') {
+                    attempts.push(`acceptance.failed:${finalProgressProbe.policy}`);
+                    throw new Error('action_postcondition_failed:value-change');
+                }
+                else if (!accepted &&
+                    (finalProgressProbe.policy === 'selection' ||
+                        finalProgressProbe.policy === 'date-selection') &&
+                    finalProgressProbe.expectedValue !== null) {
+                    attempts.push(`acceptance.failed:${finalProgressProbe.policy}`);
+                    throw new Error(`action_postcondition_failed:${finalProgressProbe.policy}`);
+                }
+                else if (!accepted && finalProgressProbe.policy === 'submit') {
+                    attempts.push(`acceptance.failed:${finalProgressProbe.policy}`);
+                    attempts.push('no-progress.detected');
+                    noProgressDiagnosis = await diagnoseNoObservableProgress(page, finalProgressProbe.locator);
+                    if (noProgressDiagnosis) {
+                        attempts.push(`no-progress.diagnosis:${noProgressDiagnosis.kind}`);
+                    }
+                    throw new Error('no_observable_progress');
+                }
+                else if (!accepted) {
+                    const afterLocatorObservation = finalProgressProbe.trackedStateKeys.length > 0
+                        ? await captureLocatorState(finalProgressProbe.locator, finalProgressProbe.trackedStateKeys)
+                        : null;
+                    const afterContextHash = await captureLocatorContextHash(finalProgressProbe.locator);
+                    const hasComparableSignal = finalProgressProbe.trackedStateKeys.length > 0 ||
+                        Boolean(finalProgressProbe.beforeContextHash || afterContextHash) ||
+                        Boolean(finalProgressProbe.beforePage || afterPageObservation);
+                    if (hasComparableSignal &&
+                        !pageObservationChanged(finalProgressProbe.beforePage, afterPageObservation) &&
+                        finalProgressProbe.beforeContextHash === afterContextHash &&
+                        !locatorStateChanged(finalProgressProbe.beforeLocator, afterLocatorObservation)) {
+                        attempts.push('no-progress.detected');
+                        noProgressDiagnosis = await diagnoseNoObservableProgress(page, finalProgressProbe.locator);
+                        if (noProgressDiagnosis) {
+                            attempts.push(`no-progress.diagnosis:${noProgressDiagnosis.kind}`);
+                        }
+                        throw new Error('no_observable_progress');
+                    }
+                }
+            }
+        }
+        if (resolvedBy === 'playwright-locator') {
+            incrementMetric(session, 'deterministicActions');
+        }
+        recordActionResult(session, true, Date.now() - startedAt);
+        saveSession(session);
+        await trace.finishSuccess();
+        outputJSON({
+            success: true,
+            targetRef,
+            action,
+            value: actionValue,
+            resolvedBy,
+            locatorStrategy,
+            pageRef: finalPageRef,
+            attempts,
+            popup: Boolean(popupPageRef),
+            overlayHandled: attempts.includes('overlay.dismissed'),
+            iframe: Boolean(target.framePath?.length),
+            jsFallback: attempts.some((attempt) => attempt.startsWith('locator.evaluate.')),
+            ...(recoveredAfterError
+                ? {
+                    recoveredAfterError: true,
+                    recoveredAcceptancePolicy: recoveredAcceptancePolicy ?? undefined,
+                }
+                : {}),
+            durationMs: Date.now() - startedAt,
+            metrics: session.runtime?.metrics,
+        });
     }
     catch (err) {
-        await stagehand.close();
-        failureMessage = `Act failed: ${err instanceof Error ? err.message : String(err)} (page: ${title} — ${url})`;
+        failureMessage = `Act failed: ${err instanceof Error ? err.message : String(err)}`;
+        recordActionResult(session, false, Date.now() - startedAt);
+        if (staleReason) {
+            markTargetLifecycle(session, targetRef, 'stale', staleReason);
+        }
+        saveSession(session);
+        if (currentPage) {
+            try {
+                const protectedExposure = getProtectedExposure(session, currentPageRef);
+                if (protectedExposure) {
+                    await trace.finishSuccess();
+                    failureArtifacts = buildProtectedArtifactsSuppressed(protectedExposure);
+                }
+                else {
+                    failureArtifacts = await captureActionFailureArtifacts({
+                        page: currentPage,
+                        targetRef,
+                        action,
+                        pageRef: currentPageRef,
+                        attempts,
+                        locatorStrategy,
+                        popup: attempts.includes('popup-captured'),
+                        overlayHandled: attempts.includes('overlay.dismissed'),
+                        iframe: Boolean(target.framePath?.length),
+                        jsFallback: attempts.some((attempt) => attempt.startsWith('locator.evaluate.')),
+                        durationMs: Date.now() - startedAt,
+                        error: failureMessage,
+                        finishTrace: (artifactDir) => trace.finishFailure(artifactDir),
+                    });
+                }
+            }
+            catch {
+                // Best effort only. Preserve the original action failure.
+            }
+        }
+    }
+    finally {
+        if (browser) {
+            disconnectPlaywright(browser);
+        }
+    }
+    if (failureMessage) {
+        if (failureMessage === 'Act failed: no_observable_progress' && noProgressDiagnosis) {
+            failureMessage = `Act failed: no_observable_progress (${noProgressDiagnosis.kind})`;
+        }
+        const failureContract = describeActFailure({
+            failureMessage,
+            staleReason,
+            diagnosis: noProgressDiagnosis,
+        });
+        const protectedExposure = getProtectedExposure(session, currentPageRef);
+        const outputDiagnosis = protectedExposure && noProgressDiagnosis
+            ? redactNoObservableProgressDiagnosis(noProgressDiagnosis)
+            : noProgressDiagnosis;
+        outputFailure({
+            error: failureMessage,
+            outcomeType: failureContract.outcomeType,
+            message: failureContract.message,
+            reason: failureContract.reason,
+            targetRef,
+            action,
+            value: actionValue,
+            pageRef: currentPageRef,
+            locatorStrategy,
+            attempts,
+            popup: attempts.includes('popup-captured'),
+            overlayHandled: attempts.includes('overlay.dismissed'),
+            iframe: Boolean(target.framePath?.length),
+            jsFallback: attempts.some((attempt) => attempt.startsWith('locator.evaluate.')),
+            durationMs: Date.now() - startedAt,
+            staleTarget: Boolean(staleReason),
+            staleReason: staleReason ?? undefined,
+            diagnosis: outputDiagnosis ?? undefined,
+            artifacts: failureArtifacts,
+            metrics: session.runtime?.metrics,
+        });
     }
-    return outputError(failureMessage ?? `Act failed: Stagehand could not complete the requested action: ${instruction}`);
 }