# Envoy browser integration — internal preview

Status: deployed internal beta. On 15 September 2026, Instinct reported phone pairing and successful balance/five-transaction reads from a genuinely fresh task after the login writer was released. Purchase execution, bank 3DS and merchant confirmation are separate acceptance checks.

Setup contract: saved-browser-v1. For setup decisions and failure reporting, follow [the Instinct entry guide](https://agent.envoy.money/instinct.md).

## Connect once from another device

Acquire a write lease on the user’s current default saved browser profile and open https://agent.envoy.money/browser.html. Click **Connect on your phone**. Send the displayed pairing link and pairing code to the account owner. This link starts login; it does not contain an access token or the secret used to collect the connection.

The user opens the link on their own phone, checks the matching pairing code and completes phone-number/OTP login on Envoy. Do not ask for the OTP in chat. Keep the agent page open under the write lease: it polls automatically and shows Connected when login finishes. Only then release the writer to save the session cookie. The link expires after five minutes; generate a fresh link if it expires. Do not repeatedly start pairing while a valid link is in use. If polling is interrupted, use Check existing pairing before minting another link. This resumes the existing attempt; it does not initiate a payment.

The existing **Sign in in this browser** option remains available where the host provides a user takeover mechanism. Instinct reported no such mechanism; use phone pairing there.

Do not copy cookies or login credentials into chat, scripts, memory, URLs or local files. Keep different users’ profiles separate. The connected browser retains the existing internal-beta mandate.

## Future tasks

Discover the available profiles and current default on every task; do not hardcode config-a or config-b. Remember which user-owned profile was connected, but verify it is still available. If the default changes or the connected profile is missing, stop and explain the mismatch rather than silently switching or claiming the connection was lost. Instinct reported an unavailable old test profile and a new profile without its marker; the cause is unverified.

Verify the actual returned profile matches the intended one. For pairing, reconnect and disconnect, verify persist=true: requesting a write lease does not prove it was granted. If unavailable, wait for the owner or report contention. Explicitly release only your own lease; deleting a task is not lease cleanup. Never release another active task's lease.

Wait for Checking connection to settle to Connected or an explicit error before acting. A loading message is not failed authentication. If the request times out, inspect the displayed error before retrying.

Acquire a fresh read lease for that exact same saved profile and reopen the stable browser page after the login writer has released its lease. An already-open reader does not receive newly saved cookies; release it and acquire a new reader. No prior tab or local installation is required. If the profile is missing, report the mismatch. If account access expires, use the saved-profile renewal flow below when available; otherwise reconnect through normal login. Do not use another user’s profile.

Browser access expires after 30 days. When the renewal service is enabled, explicit saved-profile maintenance can renew access without another phone login while the renewal grant, original key and upstream authorization remain valid. Browser reads do not renew cookies. This is not a promise of permanent storage or authorization. Save profile changes through a write lease after reconnect or disconnect. Only one writer can hold a profile at a time. Use a write lease for login, reconnect and disconnect, and release it after completion; cookie changes are saved on release. Read leases can use the saved login without changing the cookie. Instinct has not guaranteed profile lifetime or reset behavior.

## Default payment preference

The page has no active default-setting prompts; the host owns the default. During onboarding, consult the host's saved choice. If none exists and the question has not been answered in this conversation, ask yes/no/later and save the explicit answer in the host's memory/settings. Do not repeat declined or deferred choices unless the user asks to change them. A failed host read is not an absent choice; disclose unavailable persistence and keep the answer in the current conversation only.

Consult the host-saved default before selecting a payment method; an explicit per-purchase choice wins. Do not call legacy preference APIs to save the agent's default. Using Envoy and the merchant in separate tabs of the same saved profile avoids extra browser sessions. Read the returned card only for the authorized checkout; the page clears it when hidden. Do not weaken that clearing behavior or persist card details for convenience.

## Operations

- Check balance and limits before checkout. Latest five transactions exposes the existing issuer history.
- Initiate payment with the real merchant, final total in minor units, purpose, time observed and checkout context. The context JSON accepts `source`, `items`, `totals` and `missing_data` from the shared contract. Supply actual basket/breakdown data when available; otherwise give the actual missing-data reason. Do not invent data.
- Keep the request ID, returned purchase ID and merchant checkout outcome in ordinary task context for recovery. They are not login credentials. Save this task’s recovery bookmark before leaving. Opening it fills a locator only; explicitly confirm its task source and recover to read historical context. Never silently generate a new purchase ID to recover from a timeout.
- Recover status first after funding. Follow the internal v1 contract below; no automatic checkout retry occurs.
- Report checkout outcome using the exact shared JSON contract. This can include order reference, confirmation/status/tracking URLs, estimated delivery and actual total. Merchant outcome is separate from a verified charge or settlement.

The current integration returns an existing reusable card. It does not issue fresh single-use cards. Card details appear only in the result area and are cleared on page hiding or after two minutes; this does not revoke details already copied elsewhere. Do not save card details in task memory or logs. Bank 3DS may require the user to complete the bank's challenge.

Errors remain visible as JSON, including the error code, input field and retry guidance when supplied. Follow those instructions; a failed request does not authorize a fresh purchase.

## Disconnect

Acquire a write lease, click Disconnect this browser, then release the write lease so the saved profile is updated. The backend revokes this browser connection immediately, including copied versions of its cookie. Other Envoy connections are unaffected. Previously disclosed card details cannot be recalled by disconnecting.

Contracts: https://agent.envoy.money/contracts.txt


## Shared agent payment guidance

Website login does not install a host skill. For Grok, ChatGPT and Claude, follow the [host-specific purchase-skill setup](https://agent.envoy.money/default-payments.md). The host owns its saved default across supported transports. A saved choice does not grant a new connection access or authorize a purchase.

## Purchase attribution

New browser pairing automatically binds a cryptographic key to this saved browser profile. No agent-name entry is needed. Envoy checks a fresh signed proof on account reads, purchases, reports and disconnect. “Paired installation verified” establishes possession of the paired key; it does not prove that the host is Instinct, Codex or another platform. The optional Agent label remains unverified.

The saved profile must preserve IndexedDB as well as cookies. Verify a read from a genuinely fresh task before claiming cross-task persistence. If the key is missing, use the original saved profile or explicitly reconnect; do not fall back to a copied cookie, another profile, or an unsigned request. Existing legacy connections remain explicitly unverified and can be upgraded using Verify this browser followed by owner-approved pairing. Never restart pairing or upgrade an existing connection without the user's intent to reconnect.

If you actually observed the matching issuer transaction in account history, you may include `transaction_reference` in the checkout report JSON. Use the issuer reference, never the merchant order number. If none was observed, omit it. Bank evidence and merchant checkout reports are stored separately; missing bank evidence never authorizes a retry.

## Internal v1 purchase and recovery contract

Verify account access with `get_account` without waiting for the user to ask for balance. This is separate from host default recall and does not replace the current funds check inside `initiate_payment`. No routine Envoy user approval is added between preparation and merchant checkout.

Supply the observed merchant, final amount/currency and purpose. Include actual basket/breakdown when available; record missing data instead of inventing it. Existing credentials may include cardholder name; billing address remains explicitly unavailable. Merchant shopping and submission belong to the agent.

Before preparation, preserve the original initiate request ID in this task. Save the returned purchase ID; browser agents save the page's task bookmark, including its attempt metadata. These locators are not authorization. Never save card responses, OTPs, tokens, full receipts or raw tool results. Do not use a shared profile's last purchase for another task. Browser bookmarks are copyable account locators, not task-isolation credentials. Opening one does not load purchase data automatically: confirm it came from this task’s saved context, then use Recover. Never use a restored shared-profile tab as evidence of task ownership. To start an unrelated purchase, use the explicit new-purchase confirmation only after a merchant-reported placed order. Pending funding stays attached to the current task; never replace it or unresolved checkout. No cancellation action is provided here.

On funding return or interruption, call `get_purchase_status` with exactly one of `purchase_id` or original `initiate_request_id`. It refreshes issuer success-feed evidence, but its cart and funds preparation are historical. Read `context_revision`, `preparation.checked_at`, merchant report/receipt time and `bank_evidence.checkedAt` separately. Failed or incomplete reads can retain older `lastSuccessfulCheck`; missing debit is not proof of failure and merchant placement is not proof of charge.

Only `resume_preparation` permits the ordinary funding-return path: inspect the current merchant cart, refresh the actual context and call `initiate_payment` on the same purchase. Identical input retains its request ID; changed input uses a new ID. The service checks current funds, never identifies a matched top-up merely because the user returned. Show the exact new shortfall and the same fixed Elixir Add money link if still short. No duplicate funding request or automatic merchant submission is created. A status response never authorizes submitting an order.

For `review_required`, prior credential preparation, an uncertain submission or `inspect_merchant_order`, inspect the existing merchant session/order. Do not create a replacement purchase, invent a callback, or use a new request ID/retry assertion to reopen it. Keep the merchant tab through supported bank OTP/3DS handoff. The user authenticates with the bank; Envoy cannot fetch, relay or approve OTP. If the host cannot hand off or resume, stop safely and report that limitation.

Report the observed merchant result as `placed`, `failed` or `unknown`, with a concise reason when required. Use an issuer transaction reference only if actually observed; never substitute a merchant order number. Envoy's separate issuer checks do not confirm delivery or settlement. Do not disconnect after an ordinary task. Reconnection must preserve the host's declined/deferred default choice.

Acceptance is recorded separately for service tests, synthetic checkout, account continuity, host default recall, merchant confirmation and bank evidence. Start real-host acceptance with Grok; Claude, ChatGPT, ChatGPT Work and permitted Instinct browser access each need their own result. Installing this guide or passing synthetic tests proves none of those real-host gates. Live purchases require agreed testers, selected purchases and a total budget.

## Saved-profile renewal (requires rollout activation)

Preserve cookies AND IndexedDB. Acquire a write lease for the original saved profile before Enable renewal or Renew saved connection, confirm the lease assertion on the page, then save/release the writer and verify `get_account` from a fresh reader. The checkbox cannot establish host lease ownership. Ordinary page load and account reads never renew cookies. If a renewal response is lost, retain the tab's pending attempt and retry that same maintenance action with the latest saved profile; do not start competing writers.

An existing valid key-bound connection can enroll when rollout is enabled. An expired legacy session with no renewal grant cannot. Missing key means recover the original profile or explicitly reconnect, never generate a substitute key. A revoked connection cannot renew; upstream-login-required means external login. A disabled rollout or unavailable writer is a limitation, not success. A host refusal must be respected; do not bypass it with repeated persuasion, native integration or a disposable CLI.

Use a write lease to disconnect, then save/release it. If access has expired but a renewal cookie remains, the saved-renewal disconnect control is available. Disconnect stops further Envoy access but cannot invalidate reusable card details already returned. Renewal persistence, normal cleanup preserving designated storage, and a real new-task account read remain host-specific acceptance gates.