@nuanu-ai/agentbrowse 0.2.47 → 0.2.49

package/dist/secrets/protected-field-semantics.js

@@ -0,0 +1,154 @@
+import { inferComparableValueTypeFromFacts } from '../control-semantics.js';
+const LOGIN_USERNAME_SIGNAL_RE = /\b(email|e-mail|username|user name|login|account(?: email| name)?|member(?: email| name| id)?)\b/i;
+const LOGIN_PASSWORD_SIGNAL_RE = /\b(password|passcode|pass word)\b/i;
+const PAYMENT_CARD_NAME_SIGNAL_RE = /\b(cardholder|card holder|name on card|cardholder name|full name)\b/i;
+const PAYMENT_CARD_PAN_SIGNAL_RE = /\b(card number|card no|cc-number|cc number)\b/i;
+const PAYMENT_CARD_EXP_SIGNAL_RE = /\b(expiration|expiry|exp(?:iry)? date|exp date|mm\s*\/\s*yy|mmyy|mm\/yy)\b/i;
+const PAYMENT_CARD_CVV_SIGNAL_RE = /\b(security code|cvv|cvc)\b/i;
+const IDENTITY_DOCUMENT_SIGNAL_RE = /\b(passport|document(?: number| no)?|id(?: number| no)?|identity(?: number)?)\b/i;
+const IDENTITY_BIRTH_SIGNAL_RE = /\b(date of birth|birth date|dob)\b/i;
+const IDENTITY_NATIONALITY_SIGNAL_RE = /\b(nationality|citizenship)\b/i;
+const IDENTITY_ISSUING_COUNTRY_SIGNAL_RE = /\b(issuing country|country of issue|country\/region of issue|issuing state)\b/i;
+const IDENTITY_ISSUE_DATE_SIGNAL_RE = /\b(issue date|date of issue)\b/i;
+const IDENTITY_EXPIRY_DATE_SIGNAL_RE = /\b(expiry date|expiration date|date of expiry)\b/i;
+function normalizeText(value) {
+    return value?.replace(/\s+/g, ' ').trim().toLowerCase() ?? '';
+}
+function directFieldSignals(target) {
+    const values = new Set();
+    const push = (value) => {
+        const normalized = normalizeText(value);
+        if (normalized) {
+            values.add(normalized);
+        }
+    };
+    push(target.label);
+    push(target.displayLabel);
+    push(target.placeholder);
+    push(target.inputName);
+    push(target.inputType);
+    push(target.autocomplete);
+    push(target.semantics?.name);
+    return [...values];
+}
+function uniqueMeaningHints(hints) {
+    const seen = new Set();
+    const result = [];
+    for (const hint of hints) {
+        const key = `${hint.kind}:${hint.fieldKey}:${hint.valueHint}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        result.push(hint);
+    }
+    return result;
+}
+export function inferProtectedFieldMeaningFromTarget(target) {
+    const autocomplete = normalizeText(target.autocomplete);
+    const inputType = normalizeText(target.inputType);
+    const inputName = normalizeText(target.inputName);
+    const signals = directFieldSignals(target);
+    const comparableValueType = inferComparableValueTypeFromFacts({
+        kind: target.kind,
+        role: target.semantics?.role,
+        label: target.label,
+        displayLabel: target.displayLabel,
+        placeholder: target.placeholder,
+        inputName: target.inputName,
+        inputType: target.inputType,
+        autocomplete: target.autocomplete,
+        states: target.semantics?.states,
+        structure: target.structure,
+    });
+    const hints = [];
+    if (autocomplete.includes('username') ||
+        autocomplete.includes('email') ||
+        inputType === 'email' ||
+        /\b(user(name)?|login|email|account)\b/.test(inputName) ||
+        signals.some((signal) => LOGIN_USERNAME_SIGNAL_RE.test(signal))) {
+        hints.push({ kind: 'login', fieldKey: 'username', valueHint: 'direct' });
+    }
+    if (autocomplete.includes('current-password') ||
+        inputType === 'password' ||
+        /\bpassword\b/.test(inputName) ||
+        signals.some((signal) => LOGIN_PASSWORD_SIGNAL_RE.test(signal))) {
+        hints.push({ kind: 'login', fieldKey: 'password', valueHint: 'direct' });
+    }
+    if (autocomplete.includes('cc-number') || comparableValueType === 'card-number') {
+        hints.push({ kind: 'payment_card', fieldKey: 'pan', valueHint: 'direct' });
+    }
+    else if (/\b(card[-_ ]?number|cardnumber|cc-?number)\b/.test(inputName) ||
+        signals.some((signal) => PAYMENT_CARD_PAN_SIGNAL_RE.test(signal))) {
+        hints.push({ kind: 'payment_card', fieldKey: 'pan', valueHint: 'direct' });
+    }
+    if (autocomplete.includes('cc-exp') || comparableValueType === 'expiry') {
+        hints.push({ kind: 'payment_card', fieldKey: 'exp_month', valueHint: 'direct' });
+        hints.push({ kind: 'payment_card', fieldKey: 'exp_year', valueHint: 'direct' });
+    }
+    else if (/\b(exp|expiry|expiration)\b/.test(inputName) ||
+        signals.some((signal) => PAYMENT_CARD_EXP_SIGNAL_RE.test(signal))) {
+        hints.push({ kind: 'payment_card', fieldKey: 'exp_month', valueHint: 'direct' });
+        hints.push({ kind: 'payment_card', fieldKey: 'exp_year', valueHint: 'direct' });
+    }
+    if (autocomplete.includes('cc-csc') || comparableValueType === 'cvc') {
+        hints.push({ kind: 'payment_card', fieldKey: 'cvv', valueHint: 'direct' });
+    }
+    else if (/\b(cvv|cvc|security)\b/.test(inputName) ||
+        signals.some((signal) => PAYMENT_CARD_CVV_SIGNAL_RE.test(signal))) {
+        hints.push({ kind: 'payment_card', fieldKey: 'cvv', valueHint: 'direct' });
+    }
+    if (autocomplete.includes('cc-name') ||
+        /\b(cardholder|card-holder|cc-name)\b/.test(inputName) ||
+        signals.some((signal) => PAYMENT_CARD_NAME_SIGNAL_RE.test(signal))) {
+        hints.push({ kind: 'payment_card', fieldKey: 'cardholder', valueHint: 'direct' });
+    }
+    if (autocomplete.includes('given-name')) {
+        hints.push({ kind: 'identity', fieldKey: 'full_name', valueHint: 'full_name.given' });
+    }
+    if (autocomplete.includes('family-name')) {
+        hints.push({ kind: 'identity', fieldKey: 'full_name', valueHint: 'full_name.family' });
+    }
+    if (autocomplete === 'name' ||
+        /\bfull_?name\b/.test(inputName) ||
+        signals.some((signal) => /\bfull name\b/.test(signal))) {
+        hints.push({ kind: 'identity', fieldKey: 'full_name', valueHint: 'direct' });
+    }
+    if (/\b(first|given|forename)_?name\b/.test(inputName) ||
+        signals.some((signal) => /\b(first name|given name|forename)\b/.test(signal))) {
+        hints.push({ kind: 'identity', fieldKey: 'full_name', valueHint: 'full_name.given' });
+    }
+    if (/\b(last|family|surname)_?name\b/.test(inputName) ||
+        signals.some((signal) => /\b(last name|family name|surname)\b/.test(signal))) {
+        hints.push({ kind: 'identity', fieldKey: 'full_name', valueHint: 'full_name.family' });
+    }
+    if (autocomplete.includes('bday') ||
+        (comparableValueType === 'date' &&
+            (/\b(date_?of_?birth|birth_?date|dob)\b/.test(inputName) ||
+                signals.some((signal) => IDENTITY_BIRTH_SIGNAL_RE.test(signal))))) {
+        hints.push({ kind: 'identity', fieldKey: 'date_of_birth', valueHint: 'direct' });
+    }
+    if (/\b(passport|document|identity|id)(?:_?number|_?no)?\b/.test(inputName) ||
+        signals.some((signal) => IDENTITY_DOCUMENT_SIGNAL_RE.test(signal))) {
+        hints.push({ kind: 'identity', fieldKey: 'document_number', valueHint: 'direct' });
+    }
+    if (/\b(nationality|citizenship)\b/.test(inputName) ||
+        signals.some((signal) => IDENTITY_NATIONALITY_SIGNAL_RE.test(signal))) {
+        hints.push({ kind: 'identity', fieldKey: 'nationality', valueHint: 'direct' });
+    }
+    if (/\b(issuing_?country|country_?of_?issue|issuing_?state)\b/.test(inputName) ||
+        signals.some((signal) => IDENTITY_ISSUING_COUNTRY_SIGNAL_RE.test(signal))) {
+        hints.push({ kind: 'identity', fieldKey: 'issuing_country', valueHint: 'direct' });
+    }
+    if (comparableValueType === 'date' &&
+        (/\b(issue(?:_?date)?)\b/.test(inputName) ||
+            signals.some((signal) => IDENTITY_ISSUE_DATE_SIGNAL_RE.test(signal)))) {
+        hints.push({ kind: 'identity', fieldKey: 'issue_date', valueHint: 'direct' });
+    }
+    if (comparableValueType === 'date' &&
+        (/\b(expiry|expiration)(?:_?date)?\b/.test(inputName) ||
+            signals.some((signal) => IDENTITY_EXPIRY_DATE_SIGNAL_RE.test(signal)))) {
+        hints.push({ kind: 'identity', fieldKey: 'expiry_date', valueHint: 'direct' });
+    }
+    return uniqueMeaningHints(hints);
+}

package/dist/secrets/protected-field-values.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protected-field-values.d.ts","sourceRoot":"","sources":["../../src/secrets/protected-field-values.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAG5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAInD,OAAO,KAAK,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAyDtF,wBAAsB,mCAAmC,CAAC,MAAM,EAAE;IAChE,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,aAAa,CAAC;QACtB,OAAO,EAAE,wBAAwB,CAAC;QAClC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;KACjC,CAAC,CAAC;IACH,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,aAAa,CAAC,EAAE,yBAAyB,CAAC;CAC3C,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA4G/B"}
+{"version":3,"file":"protected-field-values.d.ts","sourceRoot":"","sources":["../../src/secrets/protected-field-values.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAG5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAInD,OAAO,KAAK,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAyDtF,wBAAsB,mCAAmC,CAAC,MAAM,EAAE;IAChE,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,aAAa,CAAC;QACtB,OAAO,EAAE,wBAAwB,CAAC;QAClC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;KACjC,CAAC,CAAC;IACH,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,aAAa,CAAC,EAAE,yBAAyB,CAAC;CAC3C,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA6G/B"}

package/dist/secrets/protected-field-values.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { AgentpayStagehandLlmClient } from '../agentpay-stagehand-llm.js';
 import { tryResolveAgentpayGatewayConfig } from '../agentpay-gateway.js';
-import { recordLlmUsage, recordPayloadBudget } from '../runtime-state.js';
+import { recordLlmUsage, recordPayloadBudget } from '../runtime-metrics.js';
 import { resolveProtectedFieldPolicy } from './field-policy.js';
 import { resolveDeterministicProtectedBindingValue } from './protected-value-adapters.js';
 import { protectedBindingKey, protectedBindingValueHintSchema } from './protected-bindings.js';
@@ -56,8 +56,8 @@ export async function resolveAssistedProtectedFieldValues(params) {
         return new Map();
     }
     const resolvedValues = new Map();
-    const unresolvedBindings = assistedBindings.filter(({ binding }) => {
-        const deterministicValue = resolveDeterministicProtectedBindingValue(binding, params.protectedValues);
+    const unresolvedBindings = assistedBindings.filter(({ binding, target }) => {
+        const deterministicValue = resolveDeterministicProtectedBindingValue(binding, params.protectedValues, target ?? undefined);
         if (typeof deterministicValue !== 'string' ||
             deterministicValue.trim().length === 0 ||
             !canUseDeterministicValueForPolicy(binding, params.fieldPolicies)) {

package/dist/secrets/protected-fill.d.ts

@@ -41,7 +41,7 @@ export declare function executeProtectedFill(params: {
 export declare const __testProtectedFill: {
     actionForTarget: typeof actionForTarget;
     formatCardExpiry: typeof formatCardExpiry;
-    resolveBindingValue: (fieldKeys: ReadonlyArray<StoredSecretFieldKey>, protectedValues: Record<string, string>) => string;
+    resolveBindingValue: (fieldKeys: ReadonlyArray<StoredSecretFieldKey>, protectedValues: Record<string, string>, target?: TargetDescriptor) => string;
 };
 export {};
 //# sourceMappingURL=protected-fill.d.ts.map

package/dist/secrets/protected-fill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protected-fill.d.ts","sourceRoot":"","sources":["../../src/secrets/protected-fill.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAyB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAqBnF,OAAO,KAAK,EAEV,qBAAqB,EACrB,yBAAyB,EACzB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAGpB,KAAK,mBAAmB,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAoB,SAAQ,oBAAoB;IAC/D,MAAM,EAAE,4BAA4B,GAAG,mBAAmB,CAAC;IAC3D,sBAAsB,CAAC,EAAE,IAAI,CAAC;CAC/B;AAED,KAAK,2BAA2B,GAC5B,gBAAgB,GAChB,iBAAiB,GACjB,yBAAyB,GACzB,wBAAwB,GACxB,2BAA2B,GAC3B,gBAAgB,CAAC;AAarB,MAAM,MAAM,4BAA4B,GACpC;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,YAAY,EAAE,oBAAoB,EAAE,CAAC;CACtC,GACD;IACE,IAAI,EAAE,eAAe,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,oBAAoB,EAAE,CAAC;IAClC,MAAM,EAAE,2BAA2B,CAAC;IACpC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,GACD;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,YAAY,EAAE,oBAAoB,EAAE,CAAC;IACrC,WAAW,EAAE,mBAAmB,EAAE,CAAC;CACpC,GACD;IACE,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EACF,yBAAyB,GACzB,mCAAmC,GACnC,sCAAsC,GACtC,kCAAkC,GAClC,eAAe,CAAC;CACrB,CAAC;AAoIN,iBAAS,eAAe,CAAC,MAAM,EAAE,gBAAgB,GAAG,mBAAmB,CActE;AAED,iBAAS,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAK7D;AA2VD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,aAAa,CAAC;IACvB,IAAI,EAAE,IAAI,CAAC;IACX,YAAY,EAAE,qBAAqB,CAAC;IACpC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,aAAa,CAAC,EAAE,yBAAyB,CAAC;CAC3C,GAAG,OAAO,CAAC,4BAA4B,CAAC,CA6KxC;AAED,eAAO,MAAM,mBAAmB;;;qCAIjB,aAAa,CAAC,oBAAoB,CAAC,mBAC7B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAY1C,CAAC"}
+{"version":3,"file":"protected-fill.d.ts","sourceRoot":"","sources":["../../src/secrets/protected-fill.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAyB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAiBnF,OAAO,KAAK,EAEV,qBAAqB,EACrB,yBAAyB,EACzB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAGpB,KAAK,mBAAmB,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAoB,SAAQ,oBAAoB;IAC/D,MAAM,EAAE,4BAA4B,GAAG,mBAAmB,CAAC;IAC3D,sBAAsB,CAAC,EAAE,IAAI,CAAC;CAC/B;AAED,KAAK,2BAA2B,GAC5B,gBAAgB,GAChB,iBAAiB,GACjB,yBAAyB,GACzB,wBAAwB,GACxB,2BAA2B,GAC3B,gBAAgB,CAAC;AAarB,MAAM,MAAM,4BAA4B,GACpC;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,YAAY,EAAE,oBAAoB,EAAE,CAAC;CACtC,GACD;IACE,IAAI,EAAE,eAAe,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,oBAAoB,EAAE,CAAC;IAClC,MAAM,EAAE,2BAA2B,CAAC;IACpC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,GACD;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,YAAY,EAAE,oBAAoB,EAAE,CAAC;IACrC,WAAW,EAAE,mBAAmB,EAAE,CAAC;CACpC,GACD;IACE,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EACF,yBAAyB,GACzB,mCAAmC,GACnC,sCAAsC,GACtC,kCAAkC,GAClC,eAAe,CAAC;CACrB,CAAC;AAEN,iBAAS,eAAe,CAAC,MAAM,EAAE,gBAAgB,GAAG,mBAAmB,CActE;AAED,iBAAS,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAK7D;AAsTD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,aAAa,CAAC;IACvB,IAAI,EAAE,IAAI,CAAC;IACX,YAAY,EAAE,qBAAqB,CAAC;IACpC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,aAAa,CAAC,EAAE,yBAAyB,CAAC;CAC3C,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAuLxC;AAED,eAAO,MAAM,mBAAmB;;;qCAIjB,aAAa,CAAC,oBAAoB,CAAC,mBAC7B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,WAC9B,gBAAgB;CAuB5B,CAAC"}

package/dist/secrets/protected-fill.js

@@ -1,98 +1,13 @@
 import { getSurface, getTarget } from '../runtime-state.js';
-import { createAcceptanceProbe, rankLocatorCandidates, waitForAcceptanceProbe, } from '../commands/action-acceptance.js';
-import { buildLocator, resolveLocatorRoot, } from '../commands/action-fallbacks.js';
+import { createAcceptanceProbe, waitForAcceptanceProbe } from '../commands/action-acceptance.js';
 import { applyActionWithFallbacks } from '../commands/action-executor.js';
 import { normalizePageSignature, readLocatorDomSignature, } from '../commands/descriptor-validation.js';
-import { resolveSurfaceScopeRoot } from '../commands/target-resolution.js';
+import { assertStoredBindingStillValid, resolvePreparedLocatorCandidates, resolveInteractionRoots, } from '../commands/interaction-kernel.js';
 import { resolveProtectedFieldPolicy } from './field-policy.js';
 import { protectedBindingKey } from './protected-bindings.js';
 import { resolveAssistedProtectedFieldValues } from './protected-field-values.js';
 import { resolveDeterministicProtectedBindingValue } from './protected-value-adapters.js';
 import { sortProtectedBindingsForExecution } from './fill-ordering.js';
-function targetUsesSurfaceAsPrimaryLocator(target, surface) {
-    const surfaceCandidateKeys = new Set(surface.locatorCandidates.map((candidate) => [
-        candidate.strategy,
-        candidate.name ?? '',
-        candidate.value,
-        candidate.attribute ?? '',
-        candidate.scope ?? '',
-    ].join(':')));
-    return target.locatorCandidates.some((candidate) => surfaceCandidateKeys.has([
-        candidate.strategy,
-        candidate.name ?? '',
-        candidate.value,
-        candidate.attribute ?? '',
-        candidate.scope ?? '',
-    ].join(':')));
-}
-function resolveLocatorRootForCandidate(baseRoot, defaultRoot, surfaceRoot, scope) {
-    if (scope === 'root') {
-        return baseRoot;
-    }
-    if (scope === 'surface') {
-        return surfaceRoot;
-    }
-    return defaultRoot;
-}
-async function prepareLocator(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 (count > 1) {
-        attempts.push(`resolve.skip:${strategy}:ambiguous:${count}`);
-        return { locator: null };
-    }
-    const resolvedLocator = locator.first();
-    const visible = await resolvedLocator.isVisible().catch(() => false);
-    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') {
-        const editable = await resolvedLocator.isEditable().catch(() => false);
-        if (!editable) {
-            const descendants = resolvedLocator.locator('input:not([type="hidden"]), textarea, select, [contenteditable="true"]');
-            const descendantCount = await descendants.count().catch(() => 0);
-            const visibleEditableDescendants = [];
-            for (let index = 0; index < descendantCount; index += 1) {
-                const descendant = descendants.nth(index);
-                const descendantVisible = await descendant.isVisible().catch(() => false);
-                if (!descendantVisible) {
-                    continue;
-                }
-                const descendantEditable = await descendant.isEditable().catch(() => false);
-                if (!descendantEditable) {
-                    continue;
-                }
-                visibleEditableDescendants.push(descendant);
-            }
-            if (visibleEditableDescendants.length === 1) {
-                attempts.push(`resolve.descendant-editable:${strategy}`);
-                return { locator: visibleEditableDescendants[0] ?? null };
-            }
-            if (visibleEditableDescendants.length > 1) {
-                attempts.push(`resolve.skip:${strategy}:descendant-ambiguous:${visibleEditableDescendants.length}`);
-                return { locator: null };
-            }
-            const readonly = await resolvedLocator
-                .getAttribute?.('readonly')
-                .then((value) => value !== null)
-                .catch(() => false);
-            if (readonly && !options?.allowReadonlyFallback) {
-                attempts.push(`resolve.skip:${strategy}:readonly`);
-                return { locator: null, blockedReason: 'readonly' };
-            }
-        }
-    }
-    return { locator: resolvedLocator };
-}
 function actionForTarget(target) {
     if (target.controlFamily === 'select') {
         return 'select';
@@ -113,11 +28,11 @@ function formatCardExpiry(month, year) {
     const normalizedYear = year.trim().length > 2 ? year.trim().slice(-2) : year.trim().padStart(2, '0');
     return `${normalizedMonth}/${normalizedYear}`;
 }
-function resolveBindingValue(fields, protectedValues, fieldPolicies, assistedValues) {
+function resolveBindingValue(fields, target, protectedValues, fieldPolicies, assistedValues) {
     if (fields.length === 1) {
         const field = fields[0];
         const policy = resolveProtectedFieldPolicy(fieldPolicies, field.fieldKey);
-        const deterministicValue = resolveDeterministicProtectedBindingValue(field, protectedValues);
+        const deterministicValue = resolveDeterministicProtectedBindingValue(field, protectedValues, target);
         if (policy === 'llm_assisted') {
             const assistedValue = assistedValues.get(protectedBindingKey(field));
             if (typeof assistedValue === 'string' && assistedValue.length > 0) {
@@ -266,52 +181,37 @@ async function prepareBindings(session, page, fillableForm) {
             };
         }
         const surface = target.surfaceRef ? getSurface(session, target.surfaceRef) : null;
-        const baseRoot = resolveLocatorRoot(page, target.framePath ?? surface?.framePath);
-        let locatorRoot = baseRoot;
-        let surfaceRoot = null;
-        if (surface) {
-            surfaceRoot = await resolveSurfaceScopeRoot(page, surface, attempts).catch(() => null);
-            if (surfaceRoot && !targetUsesSurfaceAsPrimaryLocator(target, surface)) {
-                locatorRoot = surfaceRoot;
-            }
-            else if (!surfaceRoot) {
-                attempts.push('surface.resolve.fallback:page');
-            }
-        }
+        const { baseRoot, locatorRoot, surfaceRoot } = await resolveInteractionRoots(page, target, surface, attempts);
         let resolvedLocator = null;
         let sawDomSignatureMismatch = false;
         let sawBlockedTarget = false;
         const action = actionForTarget(target);
-        for (const candidate of rankLocatorCandidates(target.locatorCandidates, action)) {
-            const candidateRoot = resolveLocatorRootForCandidate(baseRoot, locatorRoot, surfaceRoot, candidate.scope);
-            if (!candidateRoot) {
-                attempts.push(`resolve.skip:${candidate.strategy}:surface-unavailable`);
-                continue;
-            }
-            const locator = buildLocator(candidateRoot, candidate);
-            if (!locator) {
-                continue;
-            }
-            const prepared = await prepareLocator(locator, action, candidate.strategy, attempts, {
+        const resolution = await resolvePreparedLocatorCandidates({
+            target,
+            action,
+            baseRoot,
+            locatorRoot,
+            surfaceRoot,
+            attempts,
+            prepareOptions: {
                 allowReadonlyFallback: action === 'fill' && target.controlFamily === 'datepicker',
-            });
-            if (prepared.blockedReason === 'disabled' || prepared.blockedReason === 'readonly') {
-                sawBlockedTarget = true;
-            }
-            if (!prepared.locator) {
-                continue;
-            }
-            if (target.domSignature) {
-                const liveSignature = await readLocatorDomSignature(prepared.locator).catch(() => null);
-                if (liveSignature && liveSignature !== target.domSignature) {
-                    sawDomSignatureMismatch = true;
-                    attempts.push(`domSignature.mismatch:${candidate.strategy}`);
-                    continue;
+            },
+            onPreparedLocator: async (preparedLocator, strategy) => {
+                if (target.domSignature) {
+                    const liveSignature = await readLocatorDomSignature(preparedLocator).catch(() => null);
+                    if (liveSignature && liveSignature !== target.domSignature) {
+                        sawDomSignatureMismatch = true;
+                        attempts.push(`domSignature.mismatch:${strategy}`);
+                        return false;
+                    }
                 }
-            }
-            resolvedLocator = prepared.locator;
-            attempts.push(`resolve:${candidate.strategy}`);
-            break;
+                resolvedLocator = preparedLocator;
+                attempts.push(`resolve:${strategy}`);
+                return true;
+            },
+        });
+        if (resolution.sawDisabledTarget || resolution.sawReadonlyTarget) {
+            sawBlockedTarget = true;
         }
         if (!resolvedLocator) {
             return {
@@ -339,22 +239,6 @@ async function prepareBindings(session, page, fillableForm) {
     }
     return preparedBindings;
 }
-async function assertBindingStillValid(page, binding, stage) {
-    if (binding.target.pageSignature &&
-        normalizePageSignature(page.url()) !== binding.target.pageSignature) {
-        throw new Error(`binding_stale:page_signature_mismatch:${stage}`);
-    }
-    const liveCount = await binding.locator.count().catch(() => 0);
-    if (liveCount === 0) {
-        throw new Error(`binding_stale:locator_resolution_failed:${stage}`);
-    }
-    if (binding.target.domSignature) {
-        const liveSignature = await readLocatorDomSignature(binding.locator).catch(() => null);
-        if (liveSignature && liveSignature !== binding.target.domSignature) {
-            throw new Error(`binding_stale:dom_signature_mismatch:${stage}`);
-        }
-    }
-}
 function staleReasonFromError(error) {
     const message = error instanceof Error ? error.message : String(error);
     if (message.includes('page_signature_mismatch')) {
@@ -398,7 +282,7 @@ export async function executeProtectedFill(params) {
         let acceptanceProbe = null;
         let acceptanceResult = null;
         try {
-            actionValue = resolveBindingValue(binding.fields, params.protectedValues, params.fieldPolicies, assistedValues);
+            actionValue = resolveBindingValue(binding.fields, binding.target, params.protectedValues, params.fieldPolicies, assistedValues);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -438,7 +322,9 @@ export async function executeProtectedFill(params) {
             await applyActionWithFallbacks(params.page, binding.root, binding.locator, binding.action, actionValue, binding.attempts, binding.target.controlFamily, {
                 guards: {
                     assertStillValid: async (stage) => {
-                        await assertBindingStillValid(params.page, binding, stage);
+                        await assertStoredBindingStillValid(params.page, binding.locator, binding.target, stage, {
+                            errorForReason: (reason, validationStage) => `binding_stale:${reason}:${validationStage}`,
+                        });
                     },
                 },
             });
@@ -522,9 +408,19 @@ export async function executeProtectedFill(params) {
 export const __testProtectedFill = {
     actionForTarget,
     formatCardExpiry,
-    resolveBindingValue: (fieldKeys, protectedValues) => resolveBindingValue(fieldKeys.map((fieldKey) => ({
+    resolveBindingValue: (fieldKeys, protectedValues, target) => resolveBindingValue(fieldKeys.map((fieldKey) => ({
         fieldKey,
         targetRef: 't_test',
         valueHint: 'direct',
-    })), protectedValues, undefined, new Map()),
+    })), target ??
+        {
+            ref: 't_test',
+            pageRef: 'p0',
+            capability: 'actionable',
+            lifecycle: 'live',
+            availability: { state: 'available' },
+            allowedActions: ['fill'],
+            locatorCandidates: [],
+            createdAt: 0,
+        }, protectedValues, undefined, new Map()),
 };

package/dist/secrets/protected-value-adapters.d.ts

@@ -1,3 +1,4 @@
+import type { TargetDescriptor } from '../runtime-state.js';
 import type { FillableFormFieldBinding } from './types.js';
-export declare function resolveDeterministicProtectedBindingValue(binding: Pick<FillableFormFieldBinding, 'fieldKey' | 'valueHint'>, protectedValues: Record<string, string>): string | null;
+export declare function resolveDeterministicProtectedBindingValue(binding: Pick<FillableFormFieldBinding, 'fieldKey' | 'valueHint'>, protectedValues: Record<string, string>, target?: Pick<TargetDescriptor, 'label' | 'displayLabel' | 'context'>): string | null;
 //# sourceMappingURL=protected-value-adapters.d.ts.map

package/dist/secrets/protected-value-adapters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protected-value-adapters.d.ts","sourceRoot":"","sources":["../../src/secrets/protected-value-adapters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAwB,MAAM,YAAY,CAAC;AAqBjF,wBAAgB,yCAAyC,CACvD,OAAO,EAAE,IAAI,CAAC,wBAAwB,EAAE,UAAU,GAAG,WAAW,CAAC,EACjE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtC,MAAM,GAAG,IAAI,CA+Bf"}
+{"version":3,"file":"protected-value-adapters.d.ts","sourceRoot":"","sources":["../../src/secrets/protected-value-adapters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,wBAAwB,EAAwB,MAAM,YAAY,CAAC;AAwFjF,wBAAgB,yCAAyC,CACvD,OAAO,EAAE,IAAI,CAAC,wBAAwB,EAAE,UAAU,GAAG,WAAW,CAAC,EACjE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACvC,MAAM,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAAC,GACpE,MAAM,GAAG,IAAI,CAqEf"}

package/dist/secrets/protected-value-adapters.js

@@ -11,7 +11,86 @@ function directStoredValue(protectedValues, fieldKey) {
     const value = protectedValues[fieldKey];
     return typeof value === 'string' && value.trim().length > 0 ? value : null;
 }
-export function resolveDeterministicProtectedBindingValue(binding, protectedValues) {
+function parseIsoDate(value) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value.trim());
+    if (!match) {
+        return null;
+    }
+    const year = match[1];
+    const month = match[2];
+    const day = match[3];
+    if (!year || !month || !day) {
+        return null;
+    }
+    return { year, month, day };
+}
+function monthName(month) {
+    const names = [
+        'January',
+        'February',
+        'March',
+        'April',
+        'May',
+        'June',
+        'July',
+        'August',
+        'September',
+        'October',
+        'November',
+        'December',
+    ];
+    return names[Number(month) - 1] ?? month;
+}
+function monthShortName(month) {
+    return monthName(month).slice(0, 3);
+}
+function monthProjectionStyle(target) {
+    const context = [target?.label, target?.displayLabel, target?.context?.hintText]
+        .filter(Boolean)
+        .join(' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase();
+    if (/\bjanuary\b|\bfebruary\b|\bmarch\b|\bapril\b|\bmay\b|\bjune\b|\bjuly\b|\baugust\b|\bseptember\b|\boctober\b|\bnovember\b|\bdecember\b/.test(context)) {
+        return 'name';
+    }
+    if (/\bjan\b|\bfeb\b|\bmar\b|\bapr\b|\bjun\b|\bjul\b|\baug\b|\bsep\b|\boct\b|\bnov\b|\bdec\b/.test(context)) {
+        return 'short';
+    }
+    return 'numeric';
+}
+export function resolveDeterministicProtectedBindingValue(binding, protectedValues, target) {
+    if (binding.fieldKey === 'date_of_birth') {
+        const dateOfBirth = directStoredValue(protectedValues, 'date_of_birth');
+        if (!dateOfBirth) {
+            return null;
+        }
+        const valueHint = binding.valueHint ?? 'direct';
+        if (valueHint === 'direct') {
+            return dateOfBirth;
+        }
+        const parsed = parseIsoDate(dateOfBirth);
+        if (!parsed) {
+            return null;
+        }
+        if (valueHint === 'date_of_birth.day') {
+            return String(Number(parsed.day));
+        }
+        if (valueHint === 'date_of_birth.year') {
+            return parsed.year;
+        }
+        if (valueHint === 'date_of_birth.month') {
+            const style = monthProjectionStyle(target);
+            if (style === 'name') {
+                return monthName(parsed.month);
+            }
+            if (style === 'short') {
+                return monthShortName(parsed.month);
+            }
+            return parsed.month;
+        }
+        return null;
+    }
     if (binding.fieldKey !== 'full_name') {
         return binding.valueHint === 'direct'
             ? directStoredValue(protectedValues, binding.fieldKey)

package/dist/secrets/request-output.d.ts

@@ -0,0 +1,11 @@
+import type { SecretRequestSnapshot, SecretRequestStatus, SecretRequestType } from './types.js';
+export declare function serializeSecretRequest(snapshot: SecretRequestSnapshot): Record<string, unknown>;
+export declare function serializeSecretRequestContext(snapshot: SecretRequestSnapshot): Record<string, unknown>;
+export type SecretRequestStatusContract = {
+    message: string;
+    reason: string;
+    nextAction?: string;
+    outcomeType?: 'approval_pending' | 'approval_denied' | 'request_expired';
+};
+export declare function describeSecretRequestStatus(status: SecretRequestStatus, requestType: SecretRequestType): SecretRequestStatusContract;
+//# sourceMappingURL=request-output.d.ts.map

package/dist/secrets/request-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-output.d.ts","sourceRoot":"","sources":["../../src/secrets/request-output.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEhG,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAc/F;AAED,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWzB;AAED,MAAM,MAAM,2BAA2B,GAAG;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,kBAAkB,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;CAC1E,CAAC;AAQF,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,mBAAmB,EAC3B,WAAW,EAAE,iBAAiB,GAC7B,2BAA2B,CA0C7B"}

package/dist/secrets/request-output.js

@@ -0,0 +1,75 @@
+export function serializeSecretRequest(snapshot) {
+    return {
+        requestId: snapshot.requestId,
+        fillRef: snapshot.fillRef,
+        requestType: snapshot.requestType,
+        status: snapshot.status,
+        ...(snapshot.storedSecretRef ? { storedSecretRef: snapshot.storedSecretRef } : {}),
+        ...(snapshot.kind ? { kind: snapshot.kind } : {}),
+        createdAt: snapshot.createdAt,
+        updatedAt: snapshot.updatedAt,
+        ...(snapshot.expiresAt ? { expiresAt: snapshot.expiresAt } : {}),
+        ...(snapshot.resolvedAt ? { resolvedAt: snapshot.resolvedAt } : {}),
+        ...(snapshot.claimedAt ? { claimedAt: snapshot.claimedAt } : {}),
+    };
+}
+export function serializeSecretRequestContext(snapshot) {
+    return {
+        requestType: snapshot.requestType,
+        ...(snapshot.storedSecretRef ? { storedSecretRef: snapshot.storedSecretRef } : {}),
+        ...(snapshot.kind ? { kind: snapshot.kind } : {}),
+        createdAt: snapshot.createdAt,
+        updatedAt: snapshot.updatedAt,
+        ...(snapshot.expiresAt ? { expiresAt: snapshot.expiresAt } : {}),
+        ...(snapshot.resolvedAt ? { resolvedAt: snapshot.resolvedAt } : {}),
+        ...(snapshot.claimedAt ? { claimedAt: snapshot.claimedAt } : {}),
+    };
+}
+function fulfilledReasonForType(type) {
+    return type === 'secret_read'
+        ? 'AgentPay approved access to the saved secret values for this request.'
+        : 'The user supplied the requested secret values for this request.';
+}
+export function describeSecretRequestStatus(status, requestType) {
+    switch (status) {
+        case 'pending':
+            return {
+                outcomeType: 'approval_pending',
+                message: 'Protected secret request is waiting for user approval.',
+                reason: 'AgentPay has not approved this secret request yet.',
+                nextAction: 'poll-secret',
+            };
+        case 'fulfilled':
+            return {
+                message: 'Protected secret request is approved and ready to fill.',
+                reason: fulfilledReasonForType(requestType),
+                nextAction: 'fill-secret',
+            };
+        case 'denied':
+            return {
+                outcomeType: 'approval_denied',
+                message: 'Protected secret request was denied and cannot be used.',
+                reason: 'AgentPay reports that the user denied this protected request.',
+                nextAction: 'ask-user',
+            };
+        case 'expired':
+            return {
+                outcomeType: 'request_expired',
+                message: 'Protected secret request is no longer usable.',
+                reason: 'AgentPay reports that this secret request expired before it could be claimed.',
+                nextAction: 'request-secret',
+            };
+        case 'failed':
+            return {
+                message: 'Protected secret request failed and cannot be used.',
+                reason: 'AgentPay reports that this secret request failed before it could be claimed.',
+                nextAction: 'request-secret',
+            };
+        case 'canceled':
+            return {
+                message: 'Protected secret request was canceled and cannot be used.',
+                reason: 'AgentPay reports that this secret request was canceled before it could be claimed.',
+                nextAction: 'request-secret',
+            };
+    }
+}