@mercuryo-ai/agentbrowse 0.2.57 → 0.2.60

package/dist/secrets/observed-field-resolution.js

@@ -0,0 +1,223 @@
+import { canonicalFieldKeyOf, directFieldSignalValuesOf, fieldKeyEvidenceTerms, normalizeText, selectorRootOf, signalValuesOf, } from './matching-helpers.js';
+function tokensOf(value) {
+    return value.split(/[^a-z0-9]+/).filter((token) => token.length > 0);
+}
+function evidenceMatchScore(term, signals) {
+    const termTokens = tokensOf(term);
+    let best = 0;
+    for (const signal of signals) {
+        if (signal === term) {
+            return 6;
+        }
+        if (signal.includes(term) || term.includes(signal)) {
+            best = Math.max(best, 4);
+            continue;
+        }
+        const signalTokens = new Set(tokensOf(signal));
+        const sharedTokenCount = termTokens.filter((token) => signalTokens.has(token)).length;
+        if (sharedTokenCount >= 2) {
+            best = Math.max(best, 3);
+            continue;
+        }
+        if (sharedTokenCount === 1 &&
+            termTokens.some((token) => token.length >= 4 && signalTokens.has(token))) {
+            best = Math.max(best, 2);
+        }
+    }
+    return best;
+}
+function candidateEvidenceTerms(candidate) {
+    const terms = new Set();
+    const push = (value) => {
+        const normalized = normalizeText(value);
+        if (normalized) {
+            terms.add(normalized);
+        }
+    };
+    for (const term of fieldKeyEvidenceTerms(candidate.fieldKey)) {
+        push(term);
+    }
+    push(candidate.label);
+    for (const tag of candidate.semanticTags ?? []) {
+        push(tag);
+    }
+    return [...terms];
+}
+function targetValueTypeOf(target) {
+    const inputType = normalizeText(target.inputType);
+    const autocomplete = normalizeText(target.autocomplete);
+    const signals = directFieldSignalValuesOf(target);
+    if (inputType === 'email' || autocomplete.includes('email')) {
+        return 'email';
+    }
+    if (inputType === 'url') {
+        return 'url';
+    }
+    if (inputType === 'number') {
+        return 'number';
+    }
+    if (inputType === 'date' ||
+        autocomplete === 'bday' ||
+        signals.some((signal) => /\b(date of birth|birth date|dob|birthday)\b/.test(signal))) {
+        return 'date';
+    }
+    return 'text';
+}
+function isEmailValue(value) {
+    return typeof value === 'string' && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.trim());
+}
+function isDateValue(value) {
+    return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value.trim());
+}
+function isNumberValue(value) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value);
+    }
+    return typeof value === 'string' && /^-?\d+(?:\.\d+)?$/.test(value.trim());
+}
+function isUrlValue(value) {
+    return typeof value === 'string' && /^https?:\/\//.test(value.trim());
+}
+function isShapeCompatible(target, candidate) {
+    if (candidate.type === 'secret') {
+        return false;
+    }
+    const targetValueType = targetValueTypeOf(target);
+    switch (targetValueType) {
+        case 'email':
+            return (isEmailValue(candidate.value) &&
+                (!candidate.type || candidate.type === 'email' || candidate.type === 'text'));
+        case 'date':
+            return (isDateValue(candidate.value) &&
+                (!candidate.type || candidate.type === 'date' || candidate.type === 'text'));
+        case 'number':
+            return (isNumberValue(candidate.value) &&
+                (!candidate.type || candidate.type === 'number' || candidate.type === 'text'));
+        case 'url':
+            return (isUrlValue(candidate.value) &&
+                (!candidate.type || candidate.type === 'url' || candidate.type === 'text'));
+        case 'text':
+            return ((typeof candidate.value === 'string' || typeof candidate.value === 'number') &&
+                (!candidate.type ||
+                    candidate.type === 'text' ||
+                    candidate.type === 'email' ||
+                    candidate.type === 'number' ||
+                    candidate.type === 'date' ||
+                    candidate.type === 'url'));
+    }
+}
+function isScopeApplicable(candidate, host) {
+    if (!candidate.applicability || candidate.applicability.target === 'global') {
+        return true;
+    }
+    return Boolean(host && normalizeText(candidate.applicability.value) === normalizeText(host));
+}
+function contextCompatibilityScore(target, candidate) {
+    let score = 0;
+    const targetSelectorRoot = normalizeText(selectorRootOf(target) ?? undefined);
+    if (targetSelectorRoot && normalizeText(candidate.selectorRoot) === targetSelectorRoot) {
+        score += 2;
+    }
+    const targetPageFormSelector = normalizeText(target.pageFormSelector?.trim());
+    if (targetPageFormSelector &&
+        normalizeText(candidate.pageFormSelector?.trim()) === targetPageFormSelector) {
+        score += 2;
+    }
+    return score;
+}
+function candidatePriorityScore(candidate, host) {
+    let score = 0;
+    if (candidate.applicability?.target === 'host' &&
+        normalizeText(candidate.applicability.value) === normalizeText(host)) {
+        score += 3;
+    }
+    if (candidate.source === 'session_open_value') {
+        score += 2;
+    }
+    return score;
+}
+function evidenceScore(target, candidate) {
+    const directSignals = directFieldSignalValuesOf(target);
+    const broadSignals = signalValuesOf(target);
+    const terms = candidateEvidenceTerms(candidate);
+    let bestTermScore = 0;
+    for (const term of terms) {
+        bestTermScore = Math.max(bestTermScore, evidenceMatchScore(term, directSignals));
+        bestTermScore = Math.max(bestTermScore, evidenceMatchScore(term, broadSignals) - 1);
+    }
+    return bestTermScore + contextCompatibilityScore(target, candidate) + 1;
+}
+function rankCandidates(target, candidates, options = {}) {
+    return candidates
+        .map((candidate) => ({
+        candidate,
+        canonicalFieldKey: canonicalFieldKeyOf(candidate.fieldKey) || candidate.fieldKey,
+        score: evidenceScore(target, candidate) + candidatePriorityScore(candidate, options.host),
+    }))
+        .sort((left, right) => {
+        if (right.score !== left.score) {
+            return right.score - left.score;
+        }
+        return left.candidate.candidateRef.localeCompare(right.candidate.candidateRef);
+    });
+}
+export function resolveObservedField(target, candidates, options = {}) {
+    if (options.protectedTargetRefs?.has(target.ref)) {
+        return {
+            status: 'no_match',
+            targetRef: target.ref,
+            reason: 'protected_target',
+        };
+    }
+    if (candidates.length === 0) {
+        return {
+            status: 'no_match',
+            targetRef: target.ref,
+            reason: 'no_candidate',
+        };
+    }
+    const scopeEligible = candidates.filter((candidate) => isScopeApplicable(candidate, options.host));
+    if (scopeEligible.length === 0) {
+        return {
+            status: 'no_match',
+            targetRef: target.ref,
+            reason: 'scope_ineligible',
+        };
+    }
+    const shapeEligible = scopeEligible.filter((candidate) => isShapeCompatible(target, candidate));
+    if (shapeEligible.length === 0) {
+        return {
+            status: 'no_match',
+            targetRef: target.ref,
+            reason: 'incompatible_shape',
+        };
+    }
+    const minimumScore = options.minimumScore ?? 5;
+    const clearWinnerDelta = options.clearWinnerDelta ?? 2;
+    const ranked = rankCandidates(target, shapeEligible, { host: options.host });
+    const best = ranked[0];
+    if (!best || best.score < minimumScore) {
+        return {
+            status: 'no_match',
+            targetRef: target.ref,
+            reason: 'low_confidence',
+        };
+    }
+    const ambiguousCandidates = ranked.filter((candidate) => best.score - candidate.score < clearWinnerDelta);
+    if (ambiguousCandidates.length > 1) {
+        return {
+            status: 'ambiguous',
+            targetRef: target.ref,
+            candidates: ambiguousCandidates.map((candidate) => candidate.candidate.candidateRef),
+        };
+    }
+    return {
+        status: 'matched',
+        targetRef: target.ref,
+        fieldKey: best.canonicalFieldKey,
+        value: best.candidate.value,
+        source: best.candidate.source,
+        confidence: best.score >= 7 ? 'high' : 'medium',
+        candidateRef: best.candidate.candidateRef,
+    };
+}

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

@@ -1 +1 @@
-{"version":3,"file":"protected-field-semantics.d.ts","sourceRoot":"","sources":["../../src/secrets/protected-field-semantics.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpG,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,SAAS,EAAE,yBAAyB,CAAC;CACtC;AAiED,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,gBAAgB,GACvB,yBAAyB,EAAE,CAwJ7B"}
+{"version":3,"file":"protected-field-semantics.d.ts","sourceRoot":"","sources":["../../src/secrets/protected-field-semantics.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpG,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,SAAS,EAAE,yBAAyB,CAAC;CACtC;AAiED,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,gBAAgB,GACvB,yBAAyB,EAAE,CAyJ7B"}

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

@@ -1,5 +1,5 @@
 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_USERNAME_SIGNAL_RE = /\b(email|e-mail|username|user name|login|account(?:[ _-]?(?:email|name|id|login|username))|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;
@@ -65,7 +65,8 @@ export function inferProtectedFieldMeaningFromTarget(target) {
     if (autocomplete.includes('username') ||
         autocomplete.includes('email') ||
         inputType === 'email' ||
-        /\b(user(name)?|login|email|account)\b/.test(inputName) ||
+        /\b(user(name)?|login|email)\b/.test(inputName) ||
+        /\b(account|member)(?:_?(?:email|name|id|login|username))\b/.test(inputName) ||
         signals.some((signal) => LOGIN_USERNAME_SIGNAL_RE.test(signal))) {
         hints.push({ kind: 'login', fieldKey: 'username', valueHint: 'direct' });
     }

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

@@ -1,5 +1,6 @@
 import type { Page } from 'playwright-core';
 import type { BrowserSessionState } from '../browser-session-state.js';
+import { type DateValueNormalizationErrorReason } from '../date-value-normalization.js';
 import { type TargetDescriptor } from '../runtime-state.js';
 import type { PersistedFillableForm, StoredSecretFieldPolicies, StoredSecretFieldKey } from './types.js';
 type ProtectedFillAction = 'fill' | 'select' | 'type';
@@ -11,6 +12,7 @@ export interface ProtectedFieldError extends ProtectedFilledField {
     reason: 'client_validation_rejected' | 'value_not_applied';
     validationTextRedacted?: true;
 }
+type ProtectedUnexpectedErrorReason = 'missing_protected_value' | 'unsupported_protected_field_group' | 'deterministic_only_resolution_failed' | 'assisted_value_resolution_failed' | 'action_failed' | DateValueNormalizationErrorReason;
 type ProtectedBindingStaleReason = 'target_missing' | 'target_not_live' | 'page_signature_mismatch' | 'dom_signature_mismatch' | 'locator_resolution_failed' | 'target_blocked';
 export type ProtectedFillExecutionResult = {
     kind: 'success';
@@ -27,7 +29,7 @@ export type ProtectedFillExecutionResult = {
     fieldErrors: ProtectedFieldError[];
 } | {
     kind: 'unexpected_error';
-    reason: 'missing_protected_value' | 'unsupported_protected_field_group' | 'deterministic_only_resolution_failed' | 'assisted_value_resolution_failed' | 'action_failed';
+    reason: ProtectedUnexpectedErrorReason;
 };
 declare function actionForTarget(target: TargetDescriptor): ProtectedFillAction;
 declare function formatCardExpiry(month: string, year: string): string;

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;AAErD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,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,mBAAmB,CAAC;IAC7B,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,CAgNxC;AAED,eAAO,MAAM,mBAAmB;;;qCAIjB,aAAa,CAAC,oBAAoB,CAAC,mBAC7B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,WAC9B,gBAAgB;CAuB5B,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;AAErD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,EAEL,KAAK,iCAAiC,EAEvC,MAAM,gCAAgC,CAAC;AACxC,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,8BAA8B,GAC/B,yBAAyB,GACzB,mCAAmC,GACnC,sCAAsC,GACtC,kCAAkC,GAClC,eAAe,GACf,iCAAiC,CAAC;AAEtC,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,EAAE,8BAA8B,CAAC;CACxC,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;AAwUD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,mBAAmB,CAAC;IAC7B,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,CAgOxC;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,4 +1,5 @@
 import { AgentbrowseAssistiveRuntimeMissingError } from '../assistive-runtime.js';
+import { isDateValueNormalizationErrorReason, normalizeStructuredDateValue, } from '../date-value-normalization.js';
 import { getSurface, getTarget } from '../runtime-state.js';
 import { createAcceptanceProbe, waitForAcceptanceProbe } from '../commands/action-acceptance.js';
 import { applyActionWithFallbacks } from '../commands/action-executor.js';
@@ -44,6 +45,18 @@ function resolveBindingValue(fields, target, protectedValues, fieldPolicies, ass
         if (typeof deterministicValue === 'string' && deterministicValue.length > 0) {
             return deterministicValue;
         }
+        if (field.fieldKey === 'date_of_birth') {
+            const rawDateValue = protectedValues.date_of_birth;
+            if (typeof rawDateValue === 'string' && rawDateValue.trim().length > 0) {
+                const normalizedDate = normalizeStructuredDateValue(rawDateValue);
+                if (normalizedDate.kind === 'error') {
+                    throw new Error(normalizedDate.reason);
+                }
+                if (normalizedDate.kind === 'not_date_like') {
+                    throw new Error('invalid_date_value');
+                }
+            }
+        }
         if ((field.valueHint ?? 'direct') !== 'direct') {
             throw new Error('deterministic_only_resolution_failed');
         }
@@ -253,6 +266,10 @@ function staleReasonFromError(error) {
     }
     return null;
 }
+function unexpectedReasonFromError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return isDateValueNormalizationErrorReason(message) ? message : null;
+}
 export async function executeProtectedFill(params) {
     const preparedBindings = await prepareBindings(params.session, params.page, params.fillableForm);
     if (!Array.isArray(preparedBindings)) {
@@ -305,6 +322,13 @@ export async function executeProtectedFill(params) {
             actionValue = resolveBindingValue(binding.fields, binding.target, params.protectedValues, params.fieldPolicies, assistedValues);
         }
         catch (error) {
+            const unexpectedReason = unexpectedReasonFromError(error);
+            if (unexpectedReason) {
+                return {
+                    kind: 'unexpected_error',
+                    reason: unexpectedReason,
+                };
+            }
             const message = error instanceof Error ? error.message : String(error);
             if (message === 'missing_protected_value') {
                 return {
@@ -383,6 +407,13 @@ export async function executeProtectedFill(params) {
             filledFields.push(...flattenFilledFields(binding.fieldKeys, binding.targetRef));
         }
         catch (error) {
+            const unexpectedReason = unexpectedReasonFromError(error);
+            if (unexpectedReason) {
+                return {
+                    kind: 'unexpected_error',
+                    reason: unexpectedReason,
+                };
+            }
             if (acceptanceProbe) {
                 acceptanceResult =
                     acceptanceResult ?? (await waitForAcceptanceProbe(acceptanceProbe).catch(() => null));

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,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"}
+{"version":3,"file":"protected-value-adapters.d.ts","sourceRoot":"","sources":["../../src/secrets/protected-value-adapters.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,wBAAwB,EAAwB,MAAM,YAAY,CAAC;AA+EjF,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

@@ -1,3 +1,4 @@
+import { normalizeStructuredDateValue } from '../date-value-normalization.js';
 function normalizeWhitespace(value) {
     return value.replace(/\s+/g, ' ').trim();
 }
@@ -11,18 +12,9 @@ function directStoredValue(protectedValues, fieldKey) {
     const value = protectedValues[fieldKey];
     return typeof value === 'string' && value.trim().length > 0 ? value : null;
 }
-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 normalizeDateValue(value) {
+    const normalized = normalizeStructuredDateValue(value);
+    return normalized.kind === 'normalized' ? normalized : null;
 }
 function monthName(month) {
     const names = [
@@ -65,29 +57,29 @@ export function resolveDeterministicProtectedBindingValue(binding, protectedValu
         if (!dateOfBirth) {
             return null;
         }
+        const normalizedDate = normalizeDateValue(dateOfBirth);
+        if (!normalizedDate) {
+            return null;
+        }
         const valueHint = binding.valueHint ?? 'direct';
         if (valueHint === 'direct') {
-            return dateOfBirth;
-        }
-        const parsed = parseIsoDate(dateOfBirth);
-        if (!parsed) {
-            return null;
+            return normalizedDate.iso;
         }
         if (valueHint === 'date_of_birth.day') {
-            return String(Number(parsed.day));
+            return String(Number(normalizedDate.day));
         }
         if (valueHint === 'date_of_birth.year') {
-            return parsed.year;
+            return normalizedDate.year;
         }
         if (valueHint === 'date_of_birth.month') {
             const style = monthProjectionStyle(target);
             if (style === 'name') {
-                return monthName(parsed.month);
+                return monthName(normalizedDate.month);
             }
             if (style === 'short') {
-                return monthShortName(parsed.month);
+                return monthShortName(normalizedDate.month);
             }
-            return parsed.month;
+            return normalizedDate.month;
         }
         return null;
     }

package/dist/secrets/types.d.ts

@@ -11,6 +11,7 @@ export type LoginFieldKey = (typeof LOGIN_FIELD_KEYS)[number];
 export type IdentityFieldKey = (typeof IDENTITY_FIELD_KEYS)[number];
 export type PaymentCardFieldKey = (typeof PAYMENT_CARD_FIELD_KEYS)[number];
 export type StoredSecretFieldKey = LoginFieldKey | IdentityFieldKey | PaymentCardFieldKey;
+export type LoginStepKind = 'full' | 'identifier' | 'password';
 export type StoredSecretScope = 'site' | 'global';
 export type ProtectedFieldPolicy = 'deterministic_only' | 'llm_assisted';
 export declare const PROTECTED_BINDING_VALUE_HINTS: readonly ["direct", "full_name.given", "full_name.family", "date_of_birth.day", "date_of_birth.month", "date_of_birth.year"];
@@ -60,7 +61,9 @@ export interface PersistedFillableForm {
     fillRef: string;
     pageRef: string;
     scopeRef?: string;
+    pageFormSelector?: string;
     purpose: string;
+    loginStep?: LoginStepKind;
     presence?: FillableFormPresence;
     scopeEpoch?: number;
     fields: FillableFormFieldBinding[];

package/dist/secrets/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/secrets/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/secrets/types.ts"],"names":[],"mappings":"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"}

package/docs/README.md

@@ -2,7 +2,20 @@
 
 Public guides for `@mercuryo-ai/agentbrowse`.
 
-Start here:
+**Reading order for a new integration:**
+
+1. [Package README](../README.md) — 5-minute overview and Quick Start.
+2. [getting-started.md](./getting-started.md) — extended tutorial that
+   turns the Quick Start into a working model for every main API.
+3. [api-reference.md](./api-reference.md) — lookup for types, result
+   shapes, and error codes (keep open while coding).
+4. Only-when-needed: [configuration.md](./configuration.md),
+   [assistive-runtime.md](./assistive-runtime.md),
+   [protected-fill.md](./protected-fill.md).
+5. Before shipping: [integration-checklist.md](./integration-checklist.md)
+   and [troubleshooting.md](./troubleshooting.md).
+
+Full list:
 
 - [getting-started.md](./getting-started.md)
   The first guide to read after the package README. It explains the normal
@@ -18,7 +31,7 @@ Start here:
 - [protected-fill.md](./protected-fill.md)
   How protected fill works and when to use it instead of a normal fill action.
 - [integration-checklist.md](./integration-checklist.md)
-  Current contract checklist for packages and services that integrate AgentBrowse.
+  Checklist for packages and services that integrate AgentBrowse.
 - [testing.md](./testing.md)
   Stable testing helpers for packages that wrap AgentBrowse.
 - [troubleshooting.md](./troubleshooting.md)

package/docs/api-reference.md

@@ -1,7 +1,7 @@
 # AgentBrowse API Reference
 
 This page is the compact reference for the public `@mercuryo-ai/agentbrowse`
-library surface.
+library API.
 
 ## Main Functions
 
@@ -113,6 +113,16 @@ branching:
 
 These arrays back the exported `*ErrorCode` types.
 
+## Error Classes
+
+For code paths that want `instanceof` checks instead of string matching on
+`error` codes:
+
+- `AgentbrowseAssistiveRuntimeMissingError` — thrown when an assistive-only
+  command runs without an assistive runtime configured.
+- `AssistiveStructuredOutputTruncatedError` — thrown when the assistive
+  runtime returns a structured output that was cut off mid-response.
+
 ## Core Result Shapes
 
 All main commands use the same top-level pattern:
@@ -213,7 +223,7 @@ fields and does not treat the schema stringification format as part of the API.
 
 ## Assistive Runtime Types
 
-The root package exports the current assistive runtime contract:
+The root package exports the types that describe the assistive runtime:
 
 - `AgentbrowseAssistiveChatCompletionRequest`
 - `AgentbrowseAssistiveChatCompletionOptions`
@@ -229,7 +239,7 @@ Your adapter receives `args.options.messages`, optional
 
 ## Testing Subpath
 
-The package publishes a dedicated testing surface:
+The package publishes a dedicated `/testing` subpath:
 
 ```ts
 import {

package/docs/assistive-runtime.md

@@ -18,15 +18,13 @@ Today, assistive behavior matters mainly for:
 If you only need browser actions and normal page inspection, you can ignore
 assistive runtime completely.
 
-## The Runtime Contract
+## The Runtime Shape
 
 AgentBrowse does not ship a built-in OpenAI or OpenRouter adapter.
 
 Instead, you provide a small runtime object with one responsibility:
 create a chat-completions client.
 
-The shape is:
-
 ```ts
 {
   createLlmClient: () => ({
@@ -38,8 +36,66 @@ The shape is:
 }
 ```
 
-That means any OpenAI-compatible chat-completions backend can work, as long as
-your adapter returns the expected response shape.
+Any OpenAI-compatible chat-completions backend can work, as long as your
+adapter returns the expected response shape.
+
+### `options.response_model`
+
+When AgentBrowse needs structured JSON (from `extract(...)` or certain
+goal-driven `observe(...)` paths), it passes `response_model` describing
+the expected output:
+
+```ts
+{
+  name: string;        // short identifier for the schema (e.g. "checkout_total")
+  schema: ZodType;     // a Zod schema AgentBrowse wants the LLM to conform to
+}
+```
+
+Your adapter is responsible for translating `response_model.schema` into
+whatever structured-output mechanism your provider supports. For OpenAI,
+this usually means:
+
+1. Convert the Zod schema to JSON Schema (e.g. with
+   `@browserbasehq/stagehand`'s `toJsonSchema`, or your own helper).
+2. Pass it as `response_format: { type: 'json_schema', json_schema: { ... } }`.
+3. Parse `choices[0].message.content` and return `{ data, usage? }`.
+
+If your provider does not support structured outputs, you can prompt the
+model to return JSON and parse the result yourself — as long as the
+returned `data` conforms to the schema, AgentBrowse does not care how it
+was produced.
+
+### `options.image`
+
+For vision-assisted extraction, AgentBrowse passes a screenshot:
+
+```ts
+{
+  buffer: Buffer;             // raw image bytes
+  description?: string;        // short hint about what's in the image
+}
+```
+
+Most adapters encode the buffer as a base64 data URL and inject it as a
+user-turn content block. See the helper below.
+
+### Errors
+
+Your adapter throws on provider errors; AgentBrowse maps them to typed
+failures on the calling command:
+
+- HTTP errors (401/403/429/5xx): throw a normal `Error` with a descriptive
+  message. AgentBrowse surfaces it as a command failure.
+- Missing/empty content: throw; do not return `{ data: null }`.
+- Truncated structured output: AgentBrowse detects this and throws
+  `AssistiveStructuredOutputTruncatedError` — usually a signal to raise
+  `maxOutputTokens`.
+
+The `AgentbrowseAssistiveLlmClient` type exported from the root package
+describes the client object returned by `createLlmClient()`. Use it when you
+want your adapter to conform to the expected shape without redefining it
+by hand.
 
 ## Recommended Setup
 
@@ -203,5 +259,5 @@ import {
 } from '@mercuryo-ai/agentbrowse/testing';
 ```
 
-That helper installs a fetch-backed runtime with the same public assistive
-runtime contract used by the main package.
+That helper installs a fetch-backed runtime with the same public
+assistive-runtime shape used by the main package.

package/docs/configuration.md

@@ -40,8 +40,8 @@ const attached = await attach(remoteCdpUrl, {
 });
 ```
 
-That provider label is metadata only. AgentBrowse still treats this as a
-generic CDP-attached browser session.
+The provider label is metadata only — AgentBrowse treats the connection as
+a generic CDP-attached browser session regardless of the label.
 
 ## Client Configuration
 
@@ -71,10 +71,19 @@ after a process restart.
 ### Default Store
 
 ```ts
-import { loadBrowserSession, saveBrowserSession } from '@mercuryo-ai/agentbrowse';
+import { loadBrowserSession, saveBrowserSession, status } from '@mercuryo-ai/agentbrowse';
 
 saveBrowserSession(session);
 const restored = loadBrowserSession();
+
+// Always check a restored session before using it — the browser it points
+// at may already be gone.
+if (restored) {
+  const check = await status(restored);
+  if (!check.success) {
+    // The session is no longer reachable. Discard and relaunch.
+  }
+}
 ```
 
 Default path:
@@ -276,12 +285,11 @@ if your diagnostics implementation throws.
 
 ## Process-Global Convenience Helpers
 
-AgentBrowse still exposes process-global convenience functions such as:
+For small scripts and quick experiments, AgentBrowse exposes process-global
+helpers:
 
 - `configureAgentbrowseAssistiveRuntime(...)`
 - `configureAgentbrowseDiagnostics(...)`
 
-These are useful for small scripts and quick experiments.
-
-For embedded production usage, client-scoped configuration is the better
-default.
+For embedded production usage, prefer client-scoped configuration through
+`createAgentbrowseClient(...)`.