@trusty-squire/mcp 1.1.14-rc.8 → 1.1.14

package/README.md

@@ -15,169 +15,66 @@
 </p>
 
 <p align="center"><strong>Empower agents with auth and payments.</strong></p>
-<p align="center">MCP tools to automate auth and pay — your keys and card never leave the vault.</p>
+<p align="center">MCP tools to automate auth and pay — your keys and card stay out of agent context.</p>
 
 Trusty Squire is an **MCP server that lets Claude Code, Codex, Cursor, OpenCode, Goose, and other coding agents sign up, provision, and purchase on your behalf**. It opens a real browser, works through signup, sign-in, setup, and checkout flows one step at a time, clears the bot-detection and email-verification steps that make operator tools stall, and hands the job back to a person only when one is actually required. That covers wiring up OAuth and API keys for the app you're building as much as it covers paying a checkout, sending a gift, or booking something — the same operator primitives drive all of it.
 
 Provider secrets and payment cards are write-only: the agent's credential tools return references and authenticated results, never stored plaintext. The raw secret never needs to enter the agent's context, so it can't be pasted into a commit, leaked in a log, or read back out over chat. When a task genuinely needs the plaintext somewhere the agent controls, `fetch_credential` releases it — for one credential, once, and only after you sign that exact request with your passkey. Backend access is a host-scoped, rate-limited, independently revocable grant, so a leaked token is killed without rotating the provider key — and you connect Google or GitHub yourself in a real browser, so the agent never types your password. Full [threat model below](#security-and-threat-model).
 
-## One prompt
-
-```text
-Add Google OAuth to this app in one prompt: create the OAuth client, save the client secret, and wire it in without putting the raw key in chat, code, or .env.
-```
-
-Your coding agent plans the job. Trusty Squire operates the website, stores the generated key, and can issue your backend a scoped grant. The backend calls the provider through Trusty Squire, which injects the provider key on the server side.
-
-Other useful asks:
-
-- “Set up Stripe payments for this app and keep the API key out of this conversation.”
-- “Create a Render API key for deployment automation and keep it out of this conversation.”
-- “Pay this checkout with my saved work card and ask me to approve it on my phone.”
-- “Send a gift to my friend without sharing their address with me.”
-- “Book this dinner reservation for me.”
-- “That app grant leaked. Revoke it without rotating the provider key.”
-
-For supported card checkouts, save a card in the Vault from a passkey-capable
-device or let your first `operate_pay` approval link collect one just in time.
-When no card is specified, Trusty Squire uses the only saved card, starts the
-add-card ceremony if none exists, or asks you to choose when several exist. The
-new card is encrypted in your browser with a passkey-derived key and bound to
-that purchase before approval; if you add it but do not approve in time, it
-remains saved for a faster retry.
-
-Recognized Visa, Mastercard, Amex, Discover, Diners Club, and JCB cards show
-their network mark in the Vault while keeping the full bank/network label. Open
-a card row to see its masked number; `reveal` runs the passkey ceremony in your
-browser before showing the number, name, expiry, and billing address. The CVV is
-never shown, even after reveal. The Activity page also records card additions
-and removals, payments, and app-grant changes without storing a PAN or CVV.
-
-`operate_pay` requires a non-empty item and reason (calls that omit either
-receive a validation error). On a single-page checkout it prefers a machine-read
-checkout total, sends you a short-lived approval link, and submits only after you
-approve the purchase. A clean visible labeled total wins; when none is readable,
-strict schema.org `Order`/`Invoice.totalPaymentDue` structured data can supply the
-amount and currency. If neither source exposes a total, caller-supplied
-`amount_cents` and `currency` become the authoritative approval amount; an omitted
-merchant name falls back to the checkout URL's hostname. Product and offer prices
-never qualify as machine-read checkout totals. An unambiguous ISO currency on the
-page remains authoritative. A notation that cannot identify one ISO currency by
-itself, such as a shared currency symbol or an FX-preview selector, falls through to
-the currency already selected or approved for the purchase instead of refusing the
-checkout. Any live amount or currency drift still fails closed; the authoritative
-binding contract lives in the [security model](SECURITY.md#client-encrypted-card-data).
-Approval, 3-D Secure, Activity, and notification amounts use the currency's minor-unit
-precision (for example, whole yen for JPY and two decimals for USD). After you
-sign in, the owner-only approval page shows the merchant, checkout origin, amount
-and currency, item, and reason directly from the short-lived server record before
-one passkey ceremony authorizes those canonical payment values. You also see the
-requesting MCP client (for example, Hermes) and the bound card's label plus last
-four digits (or its label alone for a legacy card) before clicking **Approve
-payment** to relay the operator-sealed final authorization. Before submitting that
-authorization, you can instead choose **Deny payment**; a denial closes that
-approval attempt and prevents any later operator confirmation. When the pre-submission
-checkout can be machine-read, the payment is refused if its merchant, origin, amount,
-or currency has changed since approval. If that resume read cannot recover a total,
-Trusty Squire reuses the original mandate-bound checkout values. Card entry requires the PAN,
-expiry, and CVV fields; cardholder name and other explicitly labeled billing fields
-are filled best-effort, so a missing name field does not abort the payment. Sealing
-and cleanup touch only those selected payment controls; merchant shipping address and
-country controls remain untouched. If the checkout has a selected merchant-saved card
-alongside the newly filled card, Trusty Squire selects the sole unambiguous new-card
-radio and verifies both that choice and the filled fields again immediately before
-submission; ambiguous choices, selected saved-card options, and failed verification
-are refused with `payment_card_selection_ambiguous`. A charge is treated as
-dispatched only after the browser observes a concrete charge/order request, a
-terminal merchant outcome, or genuine 3-D Secure evidence; native form validation
-alone does not claim a dispatch. A submit is reported as `payment_submitted` only
-after the checkout reaches a new merchant order-confirmation URL with a substantive
-order or receipt identity. The browser completes 3-D Secure natively, including
-out-of-band bank-app challenges — Trusty Squire never manipulates or intercepts the
-challenge; it uses read-only checks while polling for that same order-confirmation
-signal. At that last observable boundary, a mismatch between the released card and
-issuer, network, or last-four evidence rendered by the 3-D Secure issuer/app is
-returned as a structured `warning` with `kind: "payment_instrument_mismatch"` and
-expected-versus-observed evidence. The warning persists through resumable
-`operate_payment_status` calls; it neither changes the payment status nor cancels,
-approves, or modifies the challenge, so the cardholder retains the decision whether
-to continue. A dispatched attempt with no confirmed merchant outcome and no genuine
-3-D Secure evidence remains `payment_outcome_unknown`, including across resumable
-status checks; Trusty Squire never relabels that uncertainty as 3-D Secure. A detected
-challenge that remains unresolved on timeout stays `payment_3ds_required` with
-`needs_user.wall: "3ds"`, handing control back for user completion. Neither status is
-success or permits blind resubmission: manually check the merchant's order state
-before any retry.
-
-`operate_pay` surfaces the approval link before its bounded server-side wait. It
-may wait up to one minute for approval, denial, or expiry; if it returns
-`approval_pending` first, call `operate_pay` again with the same arguments. That
-call resumes the same approval and one-passkey boundary instead of creating a new
-link. `operate_payment_status` is a non-charging alternative for inspecting the
-pre-charge approval and is the continuation tool for an already-submitted unknown
-or 3-D Secure outcome. Its `wait_seconds` accepts 0-60 (default 0) to bound-wait
-instead of taking an instant peek. Denial or expiry is terminal for that session's
-attempt: repeated calls return the same result and never mint a replacement
-approval. Close the session and start a fresh one before making a genuinely new
-payment attempt.
-
-Every payment response includes its `session_id`. Pass that same ID to every
-follow-up payment call. Omitting `session_id` remains compatible only while this
-MCP process has exactly one session; it never selects a newest or arbitrary checkout.
-
-Some split checkouts collect the card before the final order-confirmation step. On the
-card-entry page, `operate_pay { phase: "fill_card" }` first reads the live total. A
-subtotal qualifies as that payable amount only when the same order summary says
-shipping is free; recommendation and related-product prices are excluded. If that
-page exposes no total, caller-supplied `amount_cents` and `currency` take precedence
-as the approval amount. If they are omitted, Trusty Squire may use the most recent real
-total observed earlier in the same browser session, such as the cart subtotal, only
-when the checkout origin still matches. One phone approval
-binds that amount and releases the card; Trusty Squire fills the card without
-submitting and its role in the purchase ends there. It fills only the merchant's own
-HTTPS frames or recognized payment-provider frames. The card stays in the page as
-filled fields while the agent advances to the review step and places the order;
-those fields are ordinary page content in `operate_observe` and
-`operate_screenshot`, not masked. Verify the live final total against the approved
-`amount_cents`/currency yourself before placing the order; Trusty Squire no longer
-re-reads the total or submits anything. For `operate_click`, a control whose
-label looks like pay/place-order may fire only once for that approval. A second
-recognized attempt is refused and requires a fresh `operate_pay` approval in a new
-session. Non-charge-labeled clicks, key presses, and OAuth controls remain ungated.
-After a recognized click dispatches, Trusty Squire best-effort records a secret-free
-`payment_place_order_attempted` Activity event bound to the approval, optional
-mandate, approved amount/currency, merchant, and opaque card reference. This records
-an attempt, not a verified charge outcome.
-
-`operate_pay { phase: "confirm" }` just releases the session's pending-fill lock and
-reports the approved terms back — it makes no browser or provider call, records no
-audit event itself, and never charges. It can be called any time after the fill — it does not
-need to happen before you place the order, and it never reads a total or verifies an
-amount. If a payment gets stuck or a card is declined, recover with `operate_finish`
-and start a fresh session; `operate_pay` does not support refilling a different card
-mid-session.
-
-Before an initial single-page or `fill_card` call, Trusty Squire follows the actual
-visible card-number field and hands the checkout back when that field is hosted by
-PayPal or Braintree. A separate PayPal express button does not block fillable merchant
-or Shopify PCI card fields. Trusty Squire does not sign in to PayPal or use vaulted
-PayPal credentials. After any submit that has not yet reached a confirmed order,
-Trusty Squire waits 180 seconds by default for native completion, including
-out-of-band bank-app approval. A linked Telegram chat receives a challenge-specific
-nudge only after 3-D Secure is detected. Standard cross-processor 3-D Secure signals and recognized
-CardinalCommerce or Stripe challenge frames classify the first case only when the
-containing frame is visibly rendered. Hidden 3-D Secure Method pre-authentication and
-captcha-hosted frames never count as 3-D Secure, and an ordinary Shopify PCI card-field
-host alone does not either. It reports a visible decline and hands an unresolved outcome
-back on timeout, noting whether the Telegram nudge actually went out.
-`three_ds_wait_seconds` accepts whole seconds from 0 to 600; set it to `0` on
-`operate_pay` to skip the notification and waiting and receive the handoff
-immediately.
-
-Connect Telegram under Vault Settings to receive secret-free alerts for
-credential, card, payment, and app-grant lifecycle changes. Routine credential
-retrieval and proxy access stay in Activity instead of sending a push for every
-request.
+## Direct payment observation
+
+The agent drives the live checkout from ordinary browser evidence. It reads the
+amount, currency, DCC choice, card controls, validation errors, requests, and
+rendered state with `operate_observe`, `operate_network`, and
+`operate_screenshot`, then uses the ordinary click, type, select, press, scroll,
+and wait loop to advance the purchase. A spinner is evidence; the operator does
+not translate it into a payment stage.
+
+When card fields are ready, call `list_payment_cards` and then
+`inject_card` with the addressed session, the purchase terms, the selected
+`card_ref`, and an observation ref for each field to fill. `inject_card` uses the
+existing single human approval for that purchase, verifies the signed release,
+and opens the card only inside the operator. A pending approval is resumed with
+the returned `approval_id`; retries may supply changed field refs under that same
+still-valid approval. The primitive fills only the named fields and returns a
+per-field `filled`, `not_found`, `detached`, or `native_error` result. It never
+searches for a provider, chooses a saved-card UI, rereads the total, submits,
+clears fields, or diagnoses the checkout.
+
+Hosted-field providers can render decoy autofill or focus-helper inputs beside
+the actual field (notably Braintree and Stripe). Choose the ref for the visible
+card control, not a helper input. Before placing the order, re-observe and
+confirm that no competing merchant-saved-card radio or option remains selected.
+If a 3-D Secure challenge appears, the operator detects it on the next
+observation or action result, notifies the cardholder once through the purchase
+notification path, and reports `three_ds` with state `challenge_detected`; keep
+observing the live checkout while the cardholder completes it. `three_ds` can
+also carry state `sdk_error_retryable`: no challenge rendered and nothing
+notified, because the processor's own SDK failed to launch its challenge UI
+(e.g. `THREEDS_CARDINAL_SDK_ERROR` in the page's error telemetry). That failure
+is transient — the checkout re-arms, and resubmitting the payment is expected
+to launch the challenge. It is advisory only: nothing is gated, and a detected
+challenge always takes precedence. Once a challenge has rendered in the
+session, the advisory is never reported again, so a resubmit prompt can never
+ride a checkout that already completed one.
+
+Before the first card write, the operator installs a session-lifetime output
+mask for that released PAN and security code. Normal DOM/AX observations, raw
+attribute/subtree reads, network headers and bodies, errors, console evidence,
+and screenshots replace or cover complete values and ordinary PAN prefixes of
+at least eight digits. Merchant last4, brand, name, expiry, billing address,
+amounts, currency/DCC, HTTP errors, API keys, and 3-D Secure controls remain
+visible. The agent re-observes partial fills, retries targets if needed, selects
+currency, clicks place order, and follows 3-D Secure from the same generic
+evidence stream. There is no `operate_payment_status` or operator-owned
+submit/outcome state machine.
+
+This is a narrow ordinary-checkout boundary, not hostile-page information-flow
+containment. It is designed for ordinary forms and reachable hosted fields;
+provider-specific behavior still has to be verified from the returned field
+results and fresh observations. A hostile page can split, encode, or
+canvas-render a card value so it no longer matches the released value; the
+operator does not add a broad secret scanner or claim to defeat that page.
 
 ## Install
 
@@ -272,16 +169,19 @@ The result contains a host-scoped egress `base_url` and a `token`, not the Clerk
 - App grants are host-scoped, auditable, rate-limitable, and independently revocable. A leaked grant can be revoked without rotating the provider key.
 - You connect Google or GitHub in a real browser. Trusty Squire does not ask the coding agent to type those passwords.
 - Saved cards are encrypted in your browser with a passkey-derived key. For a
-  single-page payment, your phone releases the card only after approving the
-  exact purchase details shown on the approval page. On a split checkout, one
-  amount-bound approval releases the card; Trusty Squire's role ends at the fill
-  and the caller places the order and verifies the final total itself. The API
+  purchase, your phone releases the card only after approving the exact purchase
+  details shown on the approval page. The caller then observes the live checkout,
+  places the order, and verifies the result through the generic operator tools. The API
   temporarily relays only operator-sealed card ciphertext and its signed mandate.
-  Trusty Squire's API and the coding-agent model never receive plaintext PAN or
-  CVV. See the
+  Trusty Squire's API never receives plaintext PAN or CVV. The normal operator
+  read path masks the released PAN (including ordinary formatted spellings and
+  prefixes of at least eight digits) and security code before model-facing
+  output; hostile transformed page output is outside that narrow boundary. See the
   [security model](https://github.com/trusty-squire/trusty-squire/blob/main/SECURITY.md#client-encrypted-card-data)
   for the signed mandate's binding contract.
-- Browser screenshots and diagnostics can contain whatever a website visibly rendered. Treat diagnostic artifacts as sensitive and do not ask an agent to re-observe a page after a secret is shown.
+- Browser screenshots and diagnostics remain verbatim except for the released
+  card's narrow PAN/security-code mask. Treat all other rendered values as
+  potentially sensitive.
 - Trusty Squire does not bypass phone verification, hard CAPTCHAs, 3-D Secure,
   payment authorization, or decisions that belong to a person. It stops for
   human input.
@@ -294,22 +194,24 @@ for the system and data flows.
 ## MCP tools
 
 The default MCP registry exposes 29 tools (31 when maintainer diagnostics are
-enabled). The 18-tool operator driving surface uses flat, single-purpose verbs:
+enabled). The 20-tool operator driving surface uses flat, single-purpose verbs:
 `operate_start`, `operate_finish`, `operate_observe`, `operate_screenshot`,
-`operate_navigate`, `operate_click`, `operate_type`, `operate_select`,
-`operate_press`, `operate_scroll`, `operate_allow_host`, `operate_login`,
-`operate_fill_credential`, `operate_extract`, `operate_pay`,
-`operate_payment_status`, `list_credentials`, and `list_payment_cards`.
+`operate_network`, `operate_navigate`, `operate_click`, `operate_type`, `operate_select`,
+`operate_press`, `operate_scroll`, `operate_wait`, `operate_read_inbox`, `operate_login`,
+`operate_fill_credential`, `operate_extract`, `inject_card`, `list_credentials`,
+`list_payment_cards`, and `edit_payment_card`.
 Recipe and vault/account tools remain separate surfaces. The complete migration
 table and input contracts are in [operator-tool-surface.md](docs/operator-tool-surface.md).
-Continue a pending pre-charge approval by re-calling
-`operate_pay` with the same arguments; use
-`operate_payment_status(wait_seconds)` as a non-charging alternative and for
-post-submit outcome checks. `operate_screenshot(session_id,
+The evidence required to qualify an operator build is in
+[operator-acceptance-runbook.md](docs/operator-acceptance-runbook.md).
+Continue a pending card release by re-calling `inject_card` with its returned
+`approval_id`. `operate_screenshot(session_id,
 frame_index?, frame_url_contains?, full_page?)` is a read-only debugging capture
 (page or one isolated frame, e.g. a cross-origin 3-D Secure/captcha challenge)
-returned as an actual MCP image. It returns the page's real pixels: there is no
-redaction pass and no refusal when the page is showing a secret or a card value.
+returned as an actual MCP image. It returns real pixels, with only injected
+PAN/security-code controls and identified ordinary copies covered after card release.
+For controls visible only in the image, see
+[screenshot-coordinate clicks](docs/operator-tool-surface.md#clicking-a-screenshot-visible-control).
 The maintainer-only `list_extract_failures` → `get_extract_failure`
 DOM-diagnostics pair is excluded from that surface; set
 `TRUSTY_SQUIRE_DIAGNOSTICS=1` in the MCP server environment to opt into the
@@ -321,21 +223,21 @@ button, link, textbox, select, checkbox, radio, tab, menuitem, and file
 control, including those outside the viewport. Non-control markup and page text
 are absent from that shape by construction, never redacted. Use `query`,
 `role`, or `cursor` to filter or page the same map, then scroll or act on a
-returned ref. Use `format:"full"` only when the unchanged, verbatim
-`browser-use-dom` tree is needed for page text, attributes, or layout context;
-neither format masks or screens emitted content. The authoritative observation
+returned ref. Use `format:"full"` only when the DOM tree is needed for page
+text, attributes, or layout context. Both formats are otherwise verbatim, with
+the same narrow released-card value mask. The authoritative observation
 contract is [observation-model.md](docs/observation-model.md), and the detailed
 full-DOM structure is in
 [browser-use-serializer-port.md](docs/browser-use-serializer-port.md). A browser action can
-require re-observation before a ref is used again. Maintainers can select the
-legacy V1 `el_table`/snapshot contract with
-`TRUSTY_SQUIRE_OBSERVE_V2=off`, or exercise the browser-use DOM serializer
-without emitting it with `shadow`; the detailed DOM-tree contract lives in
-[browser-use-serializer-port.md](docs/browser-use-serializer-port.md).
+require re-observation before a ref is used again. Click, type, select, press,
+and scroll also default to compact observations; pass `format:"full"` on that
+action only when its verbatim DOM is needed. See the observation contract above
+for delta handling and response envelopes. The detailed DOM-tree contract lives
+in [browser-use-serializer-port.md](docs/browser-use-serializer-port.md).
 
 - Rejected tool calls return a JSON `error` envelope with a stable `code` and
   message. Malformed and unknown calls fail only that request; they do not stop
-  the shared stdio process or discard its active in-memory operator session.
+  the stdio process or discard the broker-owned operator session.
   `server_unavailable` includes `retry.max_attempts: 1`: retry once, and never
   kill or restart the shared operator process.
 - `operate_start` opens a scoped website session and `operate_observe` reads its
@@ -345,31 +247,26 @@ without emitting it with `shadow`; the detailed DOM-tree contract lives in
   `operate_type` accepts either literal `text` or a protected session `slot`,
   never both. `operate_click` alone may use its guarded internal DOM-dispatch
   fallback after a proven non-dispatch; it is not a public alternative action.
-  Frame scope and stale-ref handling remain fail-closed. For ordinary actions,
-  an owned popup becomes the active page; unrelated/no-opener pages do not.
+  Frame scope and stale-ref handling remain fail-closed. For click-triggered
+  pickers, follow the [picker and popup guidance](docs/operator-tool-surface.md#pickers-and-popup-return).
   Use `operate_login` for atomic OAuth and the username/password lifecycle,
-  `operate_extract` to capture
-  credentials, and `operate_fill_credential` to load protected slots. CAPTCHA
-  solving, inbox polling, local upload, and specialized cart mutation are not
-  operator verbs; inspect and drive the page's ordinary UI or hand the task back
-  to the user.
-  In a live operator session, in-page XHR/fetch calls to merchant API sibling
-  subdomains are automatically in scope only when they share the registrable
-  domain of a host trusted at session start. Calls outside the session scope fail
-  promptly instead of hanging; page-load resources continue normally, and a
-  mid-session `allow_host` does not seed sibling-domain widening. A small set of
-  always-in-scope hosts (recognized payment-provider frames, OAuth/captcha
-  providers, and 3-D Secure ACS/directory-server hosts) is exempt from that
-  session-start-trust requirement — otherwise a checkout's own out-of-band 3DS
-  challenge could never complete its own status poll.
-  Every operator task uses the user's Chrome profile directly. Before it starts,
+  `operate_extract` to [capture credentials](docs/operator-tool-surface.md#credential-capture-and-retrieval),
+  and `operate_fill_credential` to load protected slots. The only mailbox
+  access is `operate_read_inbox`, the consent-gated Gmail verification read;
+  CAPTCHA solving, general inbox polling, local upload, and specialized cart
+  mutation are not operator verbs; inspect and drive the page's ordinary UI or
+  hand the task back to the user.
+  Browser requests need no host declarations. See the
+  [egress contract](docs/operator-tool-surface.md#browser-egress-is-unrestricted)
+  for legacy parameter compatibility and the unchanged payment/vault boundaries.
+  Operator servers automatically share the [browser broker](docs/browser-broker.md),
+  which owns the user's Chrome profile. Before a session starts,
   the operator checks the live Google My Account identity; if the profile is
   signed out, it returns a clear login handoff before navigating to the service.
-  To route only that browser session through a proxy, pass `proxy` to
-  `operate_start` as an HTTP or HTTPS URL (credentials are optional), or as an
-  unauthenticated SOCKS5 URL. The value is launch-only and sensitive: it is not
-  returned in session status, action traces, or saved recipes. Omitting it uses
-  direct egress.
+  If a restart or reconnect leaves the browser profile busy, follow the
+  [reconnect recovery guide](docs/DESIGN-warm-browser-reuse.md#recovering-after-reconnect).
+  For proxy configuration and shared-browser compatibility, see the
+  [broker configuration guide](docs/browser-broker.md#configuration-and-operation).
   Under the browser-use DOM format, an expired, forged, wrong-generation, cross-page, or drifted
   `@e:` handle fails opaquely with `reobserve_required`; re-observe and choose a
   current handle. Under V1, DOM churn returns `target_stale` with the last
@@ -378,8 +275,13 @@ without emitting it with `shadow`; the detailed DOM-tree contract lives in
   Malformed flat-verb calls return `error.code: "invalid_arguments"` without
   ending the shared server process or discarding the active session. For a
   provider login, pass the observed provider-button ref to `operate_login`.
-  It retains the product tab across provider-owned popup
-  redirects and closes. When it observes the authorized return destination still
+  It retains the product tab across provider-owned popup redirects and closes.
+  Completion requires attempt-local navigation evidence from the selected
+  provider to the exact declared return path and fixed query. A declared chain
+  may contain one return destination or one callback followed by one dashboard;
+  in the two-destination case, only the terminal dashboard completes login. An
+  unrelated same-origin page, a longer chain, or a chain that returns to the
+  provider remains pending. When the authorized completion destination is still
   open, that destination becomes the session's operation page: its post-login
   observation and later page-bound operations (actions, reads, screenshots,
   navigation, verification, and checkout) stay bound to it, leaving the retained
@@ -404,27 +306,33 @@ without emitting it with `shadow`; the detailed DOM-tree contract lives in
   the session. A consent screen or a 2FA/verification challenge is usually still
   showing, so re-observe and drive it; the session stays open and usable. A
   denial the provider actually reported (an OAuth `error=` code on the return
-  URL) is the one case that fails the action, with that code in the message. If
-  an observation races the transition, it reports `oauth.state: "in_progress"`
+  URL) fails the action, with that code in the message. For interrupted clicks,
+  retained popups, and pre-dispatch failures, follow the
+  [OAuth error and recovery contract](docs/operator-tool-surface.md#using-the-rest-of-the-surface).
+  If an observation races the transition, it reports `oauth.state: "in_progress"`
   and directs the host to observe again.
-- Observed card controls are marked `payment_field` and
-  `interaction: "vaulted_card_only"`, with `operate_pay { phase: "fill_card" }`
-  as the recommended action. Typing a Luhn-valid, card-number-shaped value
-  manually through `operate_type` is refused with `safe_alternative: "operate_pay"`
-  and the missing prerequisite `verified_cart_total`.
-- `operate_finish` closes the session and optionally accepts a nested `outcome`.
-  `none` only closes; `credentials` requires `store` and preserves credential
-  extraction, vault storage, and auto-promotion; `result` requires `summary` or
-  `data`. A result is eligible to save portable login state only when
-  `verify_recipe` confirms it or `data.confirmed` is `true`; credential outcomes
-  qualify only after unblocked extraction and vault storage. `none`, failed or
-  unconfirmed outcomes, and payment-sensitive sessions preserve the prior saved
-  snapshot. Finish first stops new calls and drains calls already using that
-  session within a bounded terminal transition, then closes its browser and
-  schedules private-profile removal. Sessions also close automatically after 10 minutes without an
-  operation and begin terminal teardown at 30 minutes; only an active payment
-  receives the short bounded close grace. Callers should finish promptly instead
-  of treating an open browser as durable background state.
+- Call `inject_card` with the exact observed refs for the card-entry fields.
+  It fills only those refs under the existing purchase approval; the agent
+  observes partial results and drives every later checkout action itself. Pick
+  the real visible field rather than a hosted-provider autofill/focus helper;
+  before placing the order, re-observe for a competing selected saved card. A
+  rendered 3-D Secure challenge is detected by the operator, which notifies the
+  cardholder once and reports `three_ds` with state `challenge_detected`; keep
+  observing while the cardholder completes it. The other state,
+  `sdk_error_retryable`, reports that the processor's SDK failed to launch the
+  challenge UI at all — nothing is notified and nothing is gated; the checkout
+  re-arms and a resubmitted payment is expected to launch the challenge.
+- `operate_finish` closes the session with a flat `outcome` enum — never a
+  nested union. `none` only closes; `credentials` requires `store` and preserves
+  credential extraction and vault storage; `result` requires `summary` or
+  `data`. Agent-provided result data is reported information, not proof that a
+  login, provisioning operation, or mutation completed. Finish first fences new
+  calls and drives the owned terminal transition; callers must not infer closure
+  merely from a delivery timeout. Callers should finish promptly instead of
+  treating an open browser as durable background state. The current server advertises an additive receipt through `tools/list` with `session_id`,
+  `operation_id`, `execution`, `mutation`, `cleanup`, and `closed:boolean`.
+  Closure is established only when `closed` is true. Older servers may omit
+  these fields; a missing receipt never proves cleanup.
 - `operate_recipe_save` saves a postcondition-verified local recipe under a
   closed task verb plus the service's registrable domain. It records stable target
   attributes and exact provenance for Squire-supplied values, not observed refs
@@ -438,20 +346,20 @@ without emitting it with `shadow`; the detailed DOM-tree contract lives in
   navigation and continues with cold driving. On one ordinary missed step,
   replay returns a local repair point and can continue in the same session.
   Older name-only recipes remain planning hints.
-- `list_payment_cards` returns saved-card labels and opaque references;
-  `operate_pay` accepts an explicit `session_id` and `phase` of `"single"`
-  (the default, also implied by omitting phase), `"fill_card"`, or `"confirm"`.
-  It can use a selected card, the only card on file, or a just-in-time
-  add-card approval. The single-page flow fills the checkout and applies the
-  post-submit outcome wait described above before handing back unresolved
-  outcomes. Split checkouts use the `fill_card` then `confirm` flow described
-  above.
-  `operate_payment_status` follows the [payment guide](#one-prompt) bounded-wait
-  contract. It returns the session ID and includes it in every follow-up tool
-  hint, so an approval or submitted outcome is always observed in its originating
-  browser. Malformed calls return normal `invalid_arguments` handling, including a safe resolution
-  when `card_ref` and `card_label` conflict.
+- `list_payment_cards` returns saved-card labels and opaque references.
+  `inject_card` takes one explicit `card_ref`, purchase terms, and per-field
+  refs plus the addressed `session_id`. It creates or resumes the single approval
+  and returns per-field browser outcomes plus approval metadata and last4; it
+  never returns PAN/CVV or submits.
 - `list_credentials` and `use_credential` find saved credentials and make authenticated API calls without returning raw values.
+  Before provisioning, call `list_credentials` with
+  `{"service":["exa","groq","cartesia"],"fields":"summary"}` to check for
+  existing keys without returning the whole inventory. `service` accepts one
+  string or a nonempty array and matches exact service names after trimming
+  whitespace and ignoring case. `fields: "summary"` selects compact metadata;
+  calling with `{}` preserves the full metadata inventory. Discover the exact
+  projection and inputs through the installed server's `tools/list` description
+  and schema.
 - `fetch_credential` returns a credential's raw value to the agent — the one path that does. It first returns an approval link and no value; you open it and sign with your passkey; the agent resumes with the returned `approval_id` and receives the value once. Denial or expiry releases nothing, and a mutation or payment approval cannot be used here. Reach for it only when the key must land somewhere the agent controls (a GitHub Actions secret, a `.env`) with no server-side injection path — `use_credential` is the right tool for calling an API.
 - `edit_credential` changes only an existing credential's non-secret name,
   `allowed_hosts`, or `login_hosts`; `delete_credential` soft-deletes one. Each

package/dist/api-client.d.ts

@@ -16,11 +16,6 @@ export interface ApiClientConfig {
     agentIdentity?: string;
     accountId?: string;
 }
-export interface ApiAuditContext {
-    taskId: string;
-    invocationId: string;
-    purpose: string;
-}
 export interface ProvisionInput {
     service: string;
     plan: string;
@@ -66,6 +61,7 @@ export interface VaultCredentialSummary {
     created_at: string;
     last_retrieved_at: string | null;
     retrieval_count: number;
+    stale?: boolean;
 }
 export interface CredentialMutationApproval {
     approval_id: string;
@@ -92,6 +88,30 @@ export interface CredentialMutationApproval {
     expires_at: string;
     error?: string;
 }
+export interface CardMutationApproval {
+    approval_id: string;
+    approval_url: string;
+    status: "pending" | "approved" | "failed" | "expired";
+    operation: "edit_card";
+    card: {
+        id: string;
+        label: string;
+        brand: string | null;
+        last4: string | null;
+    };
+    before: {
+        label: string;
+        brand: string | null;
+        last4: string | null;
+    };
+    after: {
+        label: string;
+        brand: string | null;
+        last4: string | null;
+    } | null;
+    expires_at: string;
+    error?: string;
+}
 export interface CredentialFetchApproval {
     approval_id: string;
     approval_url: string;
@@ -143,14 +163,32 @@ export interface PaymentApproval {
     sealed_card: string | null;
     expires_at: string;
 }
+export interface HeightenedAuthNotificationInput {
+    service: string;
+    attempt_id: string;
+    challenge_revision: string;
+    digit: string | null;
+    observed_at: string;
+    expires_at: string | null;
+    window_seconds: number;
+}
+export interface HeightenedAuthNotificationResult {
+    sent: boolean;
+    deduped: boolean;
+    attempt_id: string;
+    challenge_revision: string;
+    delivery: {
+        channel: "telegram" | "email" | null;
+        status: "sent" | "failed";
+        error?: string;
+    };
+}
 export declare class ApiClient {
     private readonly config;
     private readonly fetchImpl;
     private requestingAgent;
-    private readonly auditContext;
     constructor(config: ApiClientConfig);
     setRequestingAgent(name: string): void;
-    withAuditContext<T>(context: ApiAuditContext, fn: () => Promise<T>): Promise<T>;
     createRun(input: ProvisionInput): Promise<CreateRunResponse>;
     getRun(runId: string): Promise<RunSummary>;
     createPaymentApproval(input: {
@@ -188,6 +226,7 @@ export declare class ApiClient {
     notifyThreeDs(approvalId: string, mode: "detected_challenge" | "possible_out_of_band"): Promise<{
         sent: boolean;
     }>;
+    notifyHeightenedAuth(input: HeightenedAuthNotificationInput, signal?: AbortSignal): Promise<HeightenedAuthNotificationResult>;
     auditPayment(input: {
         merchant: string;
         amount_cents: number;
@@ -204,6 +243,7 @@ export declare class ApiClient {
         credentials: VaultCredentialSummary[];
     }>;
     storeCredential(input: {
+        write_id?: string;
         service: string;
         label?: string;
         value?: string;
@@ -245,6 +285,12 @@ export declare class ApiClient {
         };
     }): Promise<CredentialMutationApproval>;
     getCredentialMutationApproval(id: string): Promise<CredentialMutationApproval>;
+    createCardMutationApproval(input: {
+        operation: "edit_card";
+        card_id?: string;
+        label?: string;
+    }): Promise<CardMutationApproval>;
+    getCardMutationApproval(id: string): Promise<CardMutationApproval>;
     createCredentialFetchApproval(input: {
         reference?: string;
         service?: string;