@mercuryo-ai/agentbrowse 0.2.57 → 0.2.60

package/docs/getting-started.md

@@ -19,7 +19,19 @@ The normal flow is:
 5. `close(session)` ends the browser session
 
 The `session` is the key object in the whole API. It is the handle that keeps
-the browser connection and runtime state together between calls.
+the browser connection and runtime state together between calls. A session
+stays valid while the underlying browser connection is live; call
+`status(session)` to check if you need to.
+
+Refs returned by `observe(...)` (target refs, scope refs, fill refs) are
+valid for the page state that produced them, not forever. Any of these
+invalidates them:
+
+- navigation to a different page;
+- major DOM re-render (route change, modal open/close);
+- an element removed by script.
+
+After any of the above, call `observe(...)` again and use the new refs.
 
 At a high level, AgentBrowse has three kinds of behavior:
 
@@ -35,13 +47,10 @@ approval, secret, or payment logic.
 
 ## Managed Launch Note
 
-`launch(...)` uses a managed browser session. For that path, the package pulls
-in `puppeteer` for the stealth-enabled connection layer.
-
-This is there to reduce unnecessary captcha or anti-bot challenge pages during
-browser startup on sensitive sites.
-
-After launch, the normal page interaction flow still runs over Playwright CDP.
+`launch(...)` starts a managed browser session. For that path, AgentBrowse
+uses `puppeteer` with stealth evasions to reduce unnecessary captcha or
+anti-bot challenge pages on sensitive sites. Page interaction then runs
+through Playwright over CDP, which is what the rest of the API targets.
 
 ## Basic Example
 

package/docs/integration-checklist.md

@@ -1,7 +1,12 @@
 # AgentBrowse Integration Checklist
 
-Use this checklist when integrating the current `@mercuryo-ai/agentbrowse`
-contract into another package or service.
+Checklist for engineers integrating `@mercuryo-ai/agentbrowse` into another
+package or service. Use it as a final read-through before shipping an
+integration.
+
+> AgentBrowse is pre-1.0. Treat minor-version updates as potential
+> behavior changes and re-run this checklist whenever you move to a newer
+> release.
 
 ## Core Assumptions
 
@@ -28,9 +33,5 @@ contract into another package or service.
 
 - the root library entrypoint does not load `.env`
 - the CLI entrypoint is the only place that loads dotenv support
-- published examples and docs are part of the package contract
-
-## Versioning Expectation
+- published examples and docs are part of what consumers rely on
 
-AgentBrowse is still pre-1.0. Treat minor updates as contract-bearing changes
-and verify this checklist whenever you move to a newer release.

package/docs/protected-fill.md

@@ -34,13 +34,19 @@ Use ordinary `act(..., 'fill', value)` when:
 
 Compared with a normal fill action, protected fill works with:
 
-- a previously observed `fillableForm`
-- structured `protectedValues` keyed by field meaning
-- optional `fieldPolicies`
-- typed execution outcomes
-
-It also validates that the previously observed form bindings still make sense
-before applying values.
+- 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
 
@@ -80,6 +86,33 @@ if (!result.success) {
 }
 ```
 
+### Form purpose values
+
+`fillableForm.purpose` identifies which kind of form AgentBrowse detected.
+The currently surfaced purposes are:
+
+- `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.
+
+### Protected value keys
+
+The keys in `protectedValues` are the standard field names chosen by the
+form detector, not raw DOM attributes. Typical keys per purpose:
+
+- `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`.
+
+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.
+
 ## Where It Fits
 
 Protected fill handles the browser execution step.

package/docs/testing.md

@@ -21,7 +21,8 @@ Use it when:
 
 - your tests wrap `extract(...)`
 - your tests cover goal-based `observe(session, goal)`
-- your package wants to exercise the current public assistive runtime contract
+- your package wants to exercise the current public assistive runtime
+  shape
 
 ## Example
 
@@ -46,5 +47,5 @@ afterEach(() => {
 
 ## Scope
 
-This helper is for the assistive runtime contract. It does not mock browser
-sessions, pages, or observed target inventories.
+This helper targets the assistive runtime only. It does not mock browser
+sessions, pages, or observed targets.

package/docs/troubleshooting.md

@@ -1,71 +1,125 @@
 # AgentBrowse Troubleshooting
 
-## Browser Does Not Launch Headful
+Common failures and what to do about each.
 
-If `launch(...)` fails in a local GUI flow:
+## `launch(...)` Fails
 
-- confirm that Chrome or Chromium can start outside AgentBrowse
-- try `headless: true` to separate browser-launch problems from page problems
-- verify that the host has a usable display server if you expect a visible window
+Most `launch(...)` failures come from the environment, not from AgentBrowse
+itself:
 
-## Why The Package Uses Both Puppeteer And Playwright
+- **Missing or unreachable browser binary.** Confirm that Chrome or Chromium
+  starts outside AgentBrowse first.
+- **No display server.** If you expect a visible window, verify the host
+  actually has one. To isolate launch-vs-page problems, retry with
+  `headless: true`.
+- **Conflicting debug port.** If another Chrome instance is already
+  listening on the CDP port you need, the launch cannot bind.
+
+Inspect the `error` and `reason` fields on the `launch(...)` failure result
+(typed by `LAUNCH_ERROR_CODES`) before deciding whether to retry.
+
+## `attach(...)` Fails
+
+- **Unreachable CDP WebSocket URL.** Verify the URL with a simple
+  WebSocket client or `curl`.
+- **Session already owned.** Some providers reject a second CDP attach for
+  the same session.
+- **Version mismatch.** Very old or very new Chrome versions may not match
+  Playwright's expected CDP shape; `status(session)` after attach returns
+  details in that case.
+
+## Browser Session Becomes Invalid
 
-`launch(...)` uses Puppeteer for the managed browser connection layer with
-stealth evasions enabled.
+A `session` handle is valid only while the underlying browser connection
+is live.
 
-After the browser is up, normal page interaction runs through Playwright CDP.
+- If the browser process died, the next `act(...)` / `observe(...)` call
+  will fail with a connection error. Use `status(session)` to confirm, then
+  call `launch(...)` or `attach(...)` again.
+- If you restored a session from `loadBrowserSession()` or a custom store,
+  call `status(session)` right after loading. If it reports the session is
+  no longer reachable, discard it and start fresh.
+- `close(session)` called twice is safe — the second call is a no-op.
 
-That split exists to reduce unnecessary anti-bot friction during managed launch
-while keeping the live runtime on the Playwright side.
+## Why The Package Uses Both Puppeteer And Playwright
+
+`launch(...)` uses Puppeteer with stealth evasions to connect to the
+managed browser — this reduces unnecessary anti-bot friction on sensitive
+sites. Live page interaction runs through Playwright over CDP, which is
+what the rest of the API targets.
+
+You do not need to know the split to use the library; it only matters when
+a stack trace points at one runtime or the other.
 
 ## `observe(...)` Returned Zero Targets
 
 This usually means one of three things:
 
-- the page has not reached the state you expect yet
-- the goal was too narrow for the current page state
-- the page is mostly blocked by a gate, overlay, or challenge
+- the page has not reached the state you expect yet;
+- the goal was too narrow for the current page state;
+- the page is mostly blocked by a gate, overlay, or challenge.
 
 What to do:
 
-- run `observe(session)` without a goal first
-- inspect `signals`
-- inspect `fillableForms`
-- check `status(session)` and current `url`
+- run `observe(session)` without a goal first;
+- inspect `signals` for notices, errors, or challenge messages;
+- inspect `fillableForms` — there may be a form target without a clear goal
+  match;
+- check `status(session)` and the current `url`.
 
 ## `act(...)` Fails With A Stale Or Missing Target
 
-Target refs are durable within the observed page state, not forever.
+A `ref` returned by `observe(...)` is valid for the page state that
+produced it, not forever. Any of these invalidates it:
 
-If the page rerendered, navigated, or replaced a surface, re-run `observe(...)`
-and use the new `ref` values.
+- navigation to a different page;
+- major DOM re-render (route change, modal open/close, framework patch);
+- element removed by script.
+
+After any of the above, call `observe(...)` again and use the new `ref`
+values. `act(...)` failures from a stale ref surface as an error code in
+`ACT_ERROR_CODES`; check the error field before retrying the same ref.
 
 ## Scoped `extract(...)` Fails With A Stale Scope
 
-`scopeRef` is tied to the observed scope binding that produced it.
+`scopeRef` is tied to the observed scope that produced it. If the page
+changed enough that the scope no longer maps cleanly, `extract(...)`
+surfaces a stale-scope error.
 
-If the page changed enough that the scope no longer resolves cleanly, run
-`observe(...)` again and use the current `scopeRef`.
+Run `observe(...)` again and use the fresh `scopeRef`.
 
 ## `extract(...)` Fails Immediately
 
 Two common causes:
 
-- no assistive runtime is configured
-- the schema input is invalid
+- **No assistive runtime configured.** `extract(...)` calls an LLM through
+  the assistive runtime. Without one, the call fails with
+  `AgentbrowseAssistiveRuntimeMissingError`. See the
+  [Assistive Runtime Guide](./assistive-runtime.md).
+- **Invalid schema input.** Valid inputs are a plain schema object
+  (`{ field: 'string' }`) or a Zod schema. Other shapes are rejected.
+
+If the LLM returns a structured output that was cut off mid-response,
+AgentBrowse throws `AssistiveStructuredOutputTruncatedError` — usually a
+signal to increase the assistive-runtime token budget.
 
-Valid schema inputs are:
+## Protected Fill Reports Stale Bindings
 
-- a plain schema object
-- a Zod schema
+`fillProtectedForm(...)` validates that the previously observed form
+bindings still make sense. If the page changed between `observe(...)` and
+`fillProtectedForm(...)`, the call returns a stale-binding failure. Re-run
+`observe(...)`, find the updated `fillableForm`, and call
+`fillProtectedForm(...)` again with the new reference.
 
 ## You Keep Hitting Captcha Or Anti-Bot Pages
 
-Managed `launch(...)` enables a stealth-oriented Puppeteer connection layer, but
-that only reduces unnecessary friction. It does not guarantee bypass.
+Managed `launch(...)` enables a stealth-oriented Puppeteer connection
+layer, but that only reduces unnecessary friction. It does not guarantee
+bypass.
 
 If a site still gates the session:
 
-- retry with a normal local browser profile if your flow permits it
-- confirm that the site is reachable outside automation
-- treat the page as a site policy or anti-abuse boundary until proven otherwise
+- retry with a normal local browser profile if your flow permits it;
+- confirm that the site is reachable outside automation;
+- treat the page as a site policy or anti-abuse boundary until proven
+  otherwise.

package/examples/README.md

@@ -20,8 +20,15 @@ npx tsx examples/extract.ts
 Examples:
 
 - `basic.ts`
-  Launches a managed browser, observes the page, and prints a small target summary.
+  Launches a managed browser, observes the page, and prints a small target
+  summary.
 - `attach.ts`
   Attaches to an existing CDP browser session.
 - `extract.ts`
-  Runs structured extraction with an assistive runtime and a plain schema object.
+  Runs structured extraction with an assistive runtime and a plain schema
+  object.
+
+For protected-fill usage (paying with a card, filling login credentials
+from a user's vault), see [../docs/protected-fill.md](../docs/protected-fill.md).
+The example in that guide is self-contained and uses the same `observe(...)` →
+`fillProtectedForm(...)` pattern.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercuryo-ai/agentbrowse",
-  "version": "0.2.57",
+  "version": "0.2.60",
   "type": "module",
   "description": "Browser automation primitives library for AI agents",
   "license": "MIT",
@@ -70,11 +70,16 @@
     "vitest": "^4.0.18"
   },
   "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist',{ recursive: true, force: true })\" && tsc -p tsconfig.build.json",
+    "build": "node -e \"require('node:fs').rmSync('dist',{ recursive: true, force: true, maxRetries: 10, retryDelay: 50 })\" && tsc -p tsconfig.build.json",
     "agentbrowse": "tsx src/index.ts",
-    "test": "npm run test:unit && npm run test:e2e",
+    "test": "npm run test:full",
+    "test:full": "npm run test:unit && npm run test:e2e",
     "test:unit": "vitest run --exclude \"src/__tests__/*.e2e.test.ts\"",
     "test:e2e": "vitest run --no-file-parallelism --maxWorkers=1 src/__tests__/observe-stagehand.e2e.test.ts src/__tests__/extract.e2e.test.ts src/__tests__/runtime.e2e.test.ts",
+    "test:autonomous:scenarios": "npm run test:autonomous:scenarios:bare",
+    "test:autonomous:scenarios:bare": "vitest run --no-file-parallelism --maxWorkers=1 src/__tests__/runtime.e2e.test.ts src/commands/act-locator-resolution.test.ts src/secrets/form-matcher.contract.test.ts src/secrets/form-matcher.test.ts -t \"\\\\[S\"",
+    "test:e2e:autonomous": "npm run test:autonomous:scenarios",
+    "test:e2e:autonomous:bare": "npm run test:autonomous:scenarios:bare",
     "check-types": "tsc --noEmit",
     "lint": "biome check src docs README.md",
     "pack:verify": "node scripts/verify-pack-artifact.mjs",