@mercuryo-ai/agentbrowse 0.2.61 → 0.2.63

package/docs/protected-fill.md

@@ -1,60 +1,69 @@
 # AgentBrowse Protected Fill Guide
 
-Protected fill solves a specific problem:
-
-You already have sensitive values from your own approval or secret-management
-flow, and you want AgentBrowse to apply those values to a previously observed
-form in a guarded way.
-
-Normal fill and protected fill solve different problems.
+Protected fill applies caller-supplied sensitive values to a form AgentBrowse
+already observed. It is a typed, guarded alternative to calling
+`act(targetRef, 'fill', value)` by hand for every secret field.
+
+You bring the values from your own approval or secret-management flow.
+AgentBrowse handles the browser execution step: resolving targets, ordering
+fields, validating that the form bindings still apply, and returning a
+typed outcome you can branch on.
+
+> **What "protected" means here.** The values passed into
+> `fillProtectedForm(...)` travel from your code into the browser **without
+> being placed in an LLM prompt**. The orchestrating model decides *when*
+> to trigger the fill; it does not read the values. That is the sole
+> security guarantee of this code path. It is **not** a sandbox, and it
+> does not protect values from a compromised browser, host, or runtime —
+> by the time the fill happens, the value is in the browser's memory. If
+> you need the broader threat model (prompt leakage vs. compromised host,
+> screenshots after fill, post-submit side channels), see
+> [MagicPay SDK — Security Model](../../magicpay-sdk/docs/security-model.md).
 
 ## When To Use Protected Fill
 
-Use protected fill when all of these are true:
-
-- you already observed the page and have a form description
-- you already have the sensitive values in your own application
-- you want AgentBrowse to apply them through a typed execution path
+Use `fillProtectedForm(...)` when all of these are true:
 
-Examples:
+- `observe(...)` has already returned a `fillableForm` for the current page;
+- you already have the sensitive values in your own application;
+- you want AgentBrowse to apply them through a guarded execution path instead
+  of a loose sequence of per-field `act(...)` calls.
 
-- card number, expiry, CVV
-- password or one-time code
-- any field set that should not be treated like ordinary page text input
+Typical cases: card entry, password entry, identity-document entry, one-time
+code entry.
 
-## When A Normal `act(..., 'fill', value)` Is Enough
+## When Normal `act(..., 'fill', value)` Is Enough
 
-Use ordinary `act(..., 'fill', value)` when:
+Use ordinary `act(targetRef, 'fill', value)` when:
 
-- the value is not sensitive
-- you are filling one simple field directly
-- you do not need form-level guarded execution
+- the value is not sensitive;
+- you are filling one isolated field that is not part of an observed protected
+  form;
+- you do not need stale-binding guards or field-policy handling.
 
-## What Protected Fill Adds
+## Mental Model
 
-Compared with a normal fill action, protected fill works with:
+Protected fill is a contract between three inputs:
 
-- a `fillableForm` returned by a previous `observe(...)` call;
-- structured `protectedValues` keyed by field meaning (e.g. `card_number`,
-  `password`), not by raw DOM selector;
-- optional `fieldPolicies` that pin per-field behavior such as
-  `strict: true` (abort if the expected target is missing) or
-  `allowPartial: true` (apply what you can, skip the rest);
-- typed execution outcomes so your code can distinguish success from
-  stale bindings, validation failure, and generic execution errors.
-
-It also validates that the form bindings returned by `observe(...)` still
-apply to the current DOM. If the page changed between observation and
-fill, protected fill fails with a stale-binding result instead of trying
-to fill a moved or removed target.
-
-## Import
+1. **The `fillableForm` from `observe(...)`** — the shape of the protected
+   form AgentBrowse recognised. It lists every field AgentBrowse wants you
+   to fill, each tagged with a stable `fieldKey` and a `targetRef` it will
+   drive in the browser.
+2. **Your `protectedValues`** — a plain object keyed by the `fieldKey`
+   values from the form. You look up each value in your own vault or
+   approval result and hand it in.
+3. **Optional `fieldPolicies`** — per-field overrides that switch a field
+   from deterministic lookup to LLM-assisted resolution (see
+   [Split Fields And Assistive Runtime](#split-fields-and-assistive-runtime)).
 
-```ts
-import { fillProtectedForm } from '@mercuryo-ai/agentbrowse/protected-fill';
-```
+The rule that matters most: **you build `protectedValues` from the field
+keys that the form actually lists**, not from a hard-coded template. The
+set of keys present in `fillableForm.fields` is the authoritative contract
+for that page at that moment. A card page may surface only `pan` + `cvv`,
+or the full five fields, or a combined month/year input — always match the
+form.
 
-## Example
+## Quick Example
 
 ```ts
 import { observe } from '@mercuryo-ai/agentbrowse';
@@ -65,81 +74,354 @@ if (!observeResult.success) {
   throw new Error(observeResult.reason ?? observeResult.message);
 }
 
-const fillableForm = observeResult.fillableForms.find((form) => form.purpose === 'payment_card');
+const fillableForm = observeResult.fillableForms.find(
+  (form) => form.purpose === 'payment_card'
+);
 if (!fillableForm) {
-  throw new Error('Could not find a payment_card form.');
+  throw new Error('No payment_card form on this page.');
 }
 
+// Build protectedValues from the keys the form actually declared.
+const myVault: Partial<Record<string, string>> = {
+  cardholder: 'Jane Doe',
+  pan: '4111111111111111',
+  exp_month: '12',
+  exp_year: '2030',
+  cvv: '123',
+};
+
+const protectedValues = Object.fromEntries(
+  fillableForm.fields
+    .map((field) => [field.fieldKey, myVault[field.fieldKey]] as const)
+    .filter(([, value]) => typeof value === 'string' && value.length > 0)
+);
+
 const result = await fillProtectedForm({
   session,
   fillableForm,
-  protectedValues: {
-    card_number: '4111111111111111',
-    exp_month: '12',
-    exp_year: '2030',
-    cvv: '123',
-  },
+  protectedValues,
 });
 
 if (!result.success) {
-  throw new Error(result.reason ?? result.message);
+  // Browser-level failure (see "Top-Level Result" below).
+  throw new Error(`${result.error}: ${result.message}`);
+}
+
+// The fill was attempted. Branch on the execution kind to decide next step.
+switch (result.execution.kind) {
+  case 'success':
+    // All fields applied.
+    break;
+  case 'binding_stale':
+    // Re-observe and retry (see "Stale Binding Recovery").
+    break;
+  case 'validation_failed':
+    // Page-level client validation rejected at least one field.
+    break;
+  case 'unexpected_error':
+    // See "Execution Kinds" for the full reason vocabulary.
+    break;
+}
+```
+
+## Workflow
+
+### 1. Observe the page
+
+`observe(session)` returns `fillableForms: PersistedFillableForm[]`. Each
+entry describes one recognised protected form.
+
+Relevant top-level fields on a form:
+
+- `fillRef`, `pageRef`, `scopeRef?` — stable refs carried back into
+  `fillProtectedForm(...)`.
+- `purpose` — `'login' | 'identity' | 'payment_card'`. Use this to pick the
+  form you want.
+- `loginStep?` — `'full' | 'identifier' | 'password'`, only on login forms.
+- `presence?` — `'present' | 'unknown' | 'absent'`. If `'absent'`, the form
+  is no longer on the page and you should re-observe.
+- `fields` — the per-field contract (next section).
+
+### 2. Pick the form
+
+Typical selection:
+
+```ts
+const form = observeResult.fillableForms.find(
+  (f) => f.purpose === 'payment_card' && f.presence !== 'absent'
+);
+```
+
+If several forms match (for example, two login stages on a multi-step page),
+branch on `loginStep` too.
+
+### 3. Build `protectedValues` from `fillableForm.fields`
+
+Each entry in `fillableForm.fields` is a `FillableFormFieldBinding`:
+
+| Field | Meaning |
+| --- | --- |
+| `fieldKey` | The stable key you use in `protectedValues` (see next section for the full list). |
+| `targetRef` | The observed browser target AgentBrowse will drive. You do not pass this in `protectedValues` — AgentBrowse uses it internally. |
+| `label?` | Human-readable label from the page, useful for diagnostics. |
+| `required?` | Whether the page marks the field as required. |
+| `valueHint?` | `'direct'` (default) or a split-field hint such as `'full_name.given'`. See [Split Fields And Assistive Runtime](#split-fields-and-assistive-runtime). |
+
+The same `fieldKey` can appear more than once with different `valueHint`
+values (for example, a page that splits `full_name` into two inputs will
+emit two entries with the same `fieldKey` and different `valueHint`s).
+You still pass `full_name` once in `protectedValues`; the runtime splits it.
+
+### 4. Call `fillProtectedForm(...)`
+
+```ts
+const result = await fillProtectedForm({
+  session,        // required — the sticky-owner browser session
+  fillableForm,   // required — the form object from observe(...)
+  protectedValues, // required — keyed by fieldKey
+  fieldPolicies,  // optional — see the fieldPolicies section
+});
+```
+
+Empty-string and missing values in `protectedValues` are dropped silently.
+Keys that the form did not declare are ignored.
+
+### 5. Handle the result
+
+See [Top-Level Result](#top-level-result) and [Execution Kinds](#execution-kinds)
+for the full vocabulary.
+
+## Field Keys By Purpose
+
+These are the standard `fieldKey` values AgentBrowse may put in
+`fillableForm.fields` for each `purpose`. The form only lists the subset
+that actually exists on the page.
+
+### `purpose: 'login'`
+
+| fieldKey | Meaning |
+| --- | --- |
+| `username` | Username or email identifier. |
+| `password` | Password or one-time code. |
+
+### `purpose: 'identity'`
+
+| fieldKey | Meaning |
+| --- | --- |
+| `full_name` | Full legal name. May be split into given/family via `valueHint`. |
+| `document_number` | Passport/ID/driver-license number. |
+| `date_of_birth` | Date of birth. May be split into day/month/year via `valueHint`. |
+| `nationality` | Nationality. |
+| `issue_date` | Document issue date. |
+| `expiry_date` | Document expiry date. |
+| `issuing_country` | Country that issued the document. |
+
+### `purpose: 'payment_card'`
+
+| fieldKey | Meaning |
+| --- | --- |
+| `cardholder` | Cardholder name as printed on the card. |
+| `pan` | Primary account number (the long card number). |
+| `exp_month` | Expiry month. Combined input `MM/YY` is handled automatically when the form declares both `exp_month` and `exp_year`. |
+| `exp_year` | Expiry year. |
+| `cvv` | Card verification value. |
+
+There is no `wallet` purpose in the current type surface. If you need to
+fill crypto wallet fields, use ordinary `act(...)` calls.
+
+## Split Fields And Assistive Runtime
+
+Some pages split one logical value across multiple inputs: `full_name` into
+separate first-name and family-name inputs, `date_of_birth` into three
+selects (day / month / year). AgentBrowse emits these as multiple field
+entries with the same `fieldKey` and different `valueHint` values.
+
+Possible `valueHint` values:
+
+- `'direct'` (default) — the whole stored value goes into the target as-is.
+- `'full_name.given'`, `'full_name.family'` — one part of a split name.
+- `'date_of_birth.day'`, `'date_of_birth.month'`, `'date_of_birth.year'` —
+  one part of a split date.
+
+You still pass `full_name` and `date_of_birth` once each in
+`protectedValues`. The runtime then needs to derive the per-input value
+(e.g. the given name from "Jane Doe", or the month number from
+`"1990-05-12"`).
+
+- For `date_of_birth` splits, AgentBrowse normalises the date
+  deterministically and does not require an assistive runtime.
+- For `full_name` splits and for any page-localised value (for example, a
+  `nationality` dropdown that needs "Россия" on a Russian page), AgentBrowse
+  needs an **assistive runtime** (LLM client). Without one, the call
+  returns `{ kind: 'unexpected_error', reason: 'assisted_value_resolution_failed' }`.
+
+See [assistive-runtime.md](./assistive-runtime.md) for how to install the
+runtime. If you know your target forms never split values, you can skip it.
+
+## `fieldPolicies`
+
+`fieldPolicies` is an optional per-field override:
+
+```ts
+fieldPolicies: {
+  full_name: 'llm_assisted',     // force LLM resolution even if valueHint='direct'
+  date_of_birth: 'deterministic_only', // refuse LLM, fail if not deterministic
 }
 ```
 
-### Form purpose values
+- `'deterministic_only'` — only use the stored value as-is (or deterministic
+  splits like dates). Fails with `deterministic_only_resolution_failed` if
+  an LLM would be required.
+- `'llm_assisted'` — route the field through the assistive runtime even
+  when the stored value looks directly usable.
+
+Most integrations do not set `fieldPolicies`. Use it when you have a reason
+to pin a field to one mode (policy, cost control, test determinism).
 
-`fillableForm.purpose` identifies which kind of form AgentBrowse detected.
-The currently surfaced purposes are:
+## Top-Level Result
 
-- `login` — username/password or email/password form.
-- `identity` — identity-verification fields (name, address, document
-  details).
-- `payment_card` — credit/debit card entry.
-- `wallet` — crypto wallet address/chain fields.
+`fillProtectedForm(...)` returns either a success wrapper or a browser-level
+failure:
 
-### Protected value keys
+```ts
+type FillProtectedFormResult =
+  | { success: true; pageRef; url; title; execution }
+  | { success: false; error; message; reason };
+```
+
+Browser-level `error` values:
 
-The keys in `protectedValues` are the standard field names chosen by the
-form detector, not raw DOM attributes. Typical keys per purpose:
+| error | When | Action |
+| --- | --- | --- |
+| `browser_connection_failed` | The sticky-owner browser session could not be reached. | Re-check the session, possibly re-attach. |
+| `page_resolution_failed` | `pageRef` from the form no longer maps to an open page. | Re-navigate and re-observe before retrying. |
 
-- `login`: `username`, `password` (or `email`, `password`).
-- `identity`: `given_name`, `family_name`, `date_of_birth`, `country`,
-  `document_number`, etc.
-- `payment_card`: `card_number`, `cardholder_name`, `exp_month`,
-  `exp_year`, `cvv`.
-- `wallet`: `address`, `chain`.
+If `success` is `true`, the fill attempt reached the page. The detailed
+outcome is in `execution`.
 
-The exact set of keys expected for a given `fillableForm` is listed in
-`fillableForm.fields`. Always build `protectedValues` from that list rather
-than assuming defaults.
+## Execution Kinds
 
-## Where It Fits
+`execution.kind` tells you what happened during the fill itself.
 
-Protected fill handles the browser execution step.
+### `kind: 'success'`
+
+```ts
+{ kind: 'success'; filledFields: Array<{ fieldKey; targetRef }> }
+```
 
-Applications usually pair it with their own:
+All declared fields applied. `filledFields` lists what was touched.
 
-- secret storage
-- approval flow
-- policy decisions
-- claims or grants
+### `kind: 'binding_stale'`
 
-## What You Need Before Calling It
+```ts
+{
+  kind: 'binding_stale';
+  targetRef; fieldKeys;
+  reason: 'target_missing' | 'target_not_live' | 'page_signature_mismatch'
+        | 'dom_signature_mismatch' | 'locator_resolution_failed' | 'target_blocked';
+  attempts: string[];
+}
+```
 
-Before protected fill, you usually need:
+The form was observed earlier but the DOM has changed. See
+[Stale Binding Recovery](#stale-binding-recovery) for the retry flow.
 
-1. a launched browser `session`
-2. a `fillableForm` produced by `observe(...)`
-3. the sensitive values from your own trusted source
+### `kind: 'validation_failed'`
 
-## Result Shape
+```ts
+{
+  kind: 'validation_failed';
+  filledFields: Array<{ fieldKey; targetRef }>;
+  fieldErrors: Array<{
+    fieldKey; targetRef;
+    reason: 'client_validation_rejected' | 'value_not_applied';
+    validationTextRedacted?: true;
+  }>;
+}
+```
 
-Protected fill returns a typed result that tells you whether the fill:
+At least one field was rejected by client-side validation (HTML5 validity,
+`aria-invalid`, inline error text, or the value simply did not land in the
+control). `filledFields` lists what did apply before the failure.
 
-- succeeded
-- failed because bindings became stale
-- failed validation
-- failed for another execution reason
+`validationTextRedacted: true` means there was a visible validation
+message, but it is not echoed back — protected fields never surface raw
+page text that may contain the submitted value.
+
+### `kind: 'unexpected_error'`
+
+```ts
+{ kind: 'unexpected_error'; reason: ... }
+```
+
+Reasons:
+
+| reason | Meaning | Action |
+| --- | --- | --- |
+| `missing_protected_value` | The form declared a `fieldKey` that was not present in `protectedValues`. | Check that your vault covers every key in `fillableForm.fields`. |
+| `unsupported_protected_field_group` | The form grouped fields on one target in a shape protected fill cannot yet combine (only `exp_month + exp_year` is combinable today). | Fall back to ordinary `act(...)` for the odd target, or report the case. |
+| `deterministic_only_resolution_failed` | A `'deterministic_only'` policy blocked LLM resolution for a value that required it. | Relax the policy or provide a pre-split value. |
+| `assisted_value_resolution_failed` | The assistive runtime is missing or errored. | Install an assistive runtime (see [assistive-runtime.md](./assistive-runtime.md)). |
+| `action_failed` | The browser command itself failed (navigation, detached frame, etc.). | Treat similarly to a stale binding: re-observe and retry. |
+| `ambiguous_date_value` / `incomplete_date_value` / `invalid_date_value` | The `date_of_birth` value could not be normalised. | Check the stored format (ISO `YYYY-MM-DD` is safest). |
+
+## Stale Binding Recovery
+
+A `binding_stale` result is not a hard error — it means the page moved on
+since `observe(...)` ran. The recovery pattern is:
+
+```ts
+if (!result.success) {
+  // browser/page problem — handle separately
+} else if (result.execution.kind === 'binding_stale') {
+  // Re-observe the page and pick a fresh fillableForm before retrying.
+  const next = await observe(session);
+  // ... pick the form again, rebuild protectedValues, retry fill
+}
+```
+
+Do **not** reuse the old `fillableForm` after a stale result — its
+`targetRef` / signature references are what went stale in the first place.
+
+## What Stays Outside Protected Fill
+
+Protected fill does not own:
+
+- secret storage — you bring values from your own vault;
+- approval UX — you decide when to release secrets to this call;
+- form submission — `fillProtectedForm(...)` only fills; the final click/
+  submit is a separate `act(...)` call or a provider-specific step.
+
+## Import
+
+```ts
+import { fillProtectedForm } from '@mercuryo-ai/agentbrowse/protected-fill';
+```
 
-That makes it safer than treating every sensitive field as a raw one-off
-string fill.
+`fillProtectedForm` is intentionally exported from the `/protected-fill`
+subpath, not from the root `@mercuryo-ai/agentbrowse`. This keeps the
+secret-handling surface separate from the general browsing surface in
+callers that want to restrict imports.
+
+## Relation To `match / resolve / fill`
+
+`fillProtectedForm(...)` is the low-level direct API. It assumes you
+already have the protected values in hand (for example, an artifact
+returned by a MagicPay `data.waitForResult(...)` call) and only does the
+guarded browser apply step.
+
+The `match`, `resolve`, and `fill` primitives from the root package
+cover a wider pipeline: deciding which candidate value fits the form,
+resolving values stored behind a vault or approval adapter, and then
+applying them through the same protected-fill guardrails. In that flow,
+`resolver.fill` — a capability on the same `AgentbrowseMatchResolver`
+adapter that owns `resolve` — is the place where `fillProtectedForm(...)`
+is typically invoked. See the
+[Match / Resolve / Fill Guide](./match-resolve-fill.md) for the grouped
+walk-through and the [API Reference](./api-reference.md) for the
+resolver shape.
+
+Use `fillProtectedForm(...)` directly when you already have the values
+and do not need match/resolve orchestration on top. Use
+`fill(session, form, plan, { resolver })` when you want one deterministic
+surface that covers deciding, resolving, and applying.