@mercuryo-ai/agentbrowse 0.2.57 → 0.2.61

package/docs/getting-started.md

@@ -19,7 +19,28 @@ 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, runtime state, and sticky-owner metadata together
+between calls. Healthy commands reuse that sticky owner instead of issuing a
+fresh root attach on every call. If you persist the session and restart your
+process, the next command may repair the owner while the underlying browser is
+still alive; otherwise the session fails closed and you start fresh. Detached
+sticky owners also have a bounded lifetime, so an idle or expired owner may be
+recreated on the next browser command while the underlying browser session is
+still live.
+
+The sticky owner may live in-process or in an internal detached host. That is
+an implementation detail of AgentBrowse, not a daemon you manage separately.
+Detached hosts default to a 30 minute TTL.
+
+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 +56,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
 
@@ -107,6 +125,11 @@ Success result includes:
 - current `url`
 - current `title`
 
+`attach(...)` bootstraps the same sticky-owner lifecycle as `launch(...)`.
+After attach succeeds, later browser commands use that owner. A new provider-
+level root attach is only attempted again as an explicit repair path after
+owner loss.
+
 ### `observe(session, goal?)`
 
 Reads the current page and returns what AgentBrowse found.
@@ -163,12 +186,17 @@ before calling it.
 Returns local browser/runtime diagnostics for an existing session.
 
 Use it when you want to know whether the browser is still reachable and what
-page AgentBrowse believes it is on.
+page AgentBrowse believes it is on. After restoring a persisted session,
+`status(session)` is the cheapest explicit health check before more expensive
+workflows.
 
 ### `close(session)`
 
 Closes the browser session.
 
+This also terminates the internal sticky owner. Repeated closes and already-
+dead owner hosts are treated as idempotent.
+
 ## How To Handle Results
 
 All main commands use the same broad pattern:
@@ -224,6 +252,11 @@ If you want to restore a browser session between process runs, use:
 - `loadBrowserSession()`
 - `createBrowserSessionStore({ rootDir })`
 
+Persisted session records now require restorable sticky-owner metadata.
+Incompatible reconnect-era records are rejected at load time instead of being
+auto-migrated. Treat `loadBrowserSession() === null` as "no usable session",
+not as a recoverable partial state.
+
 See:
 
 - [Configuration Guide](./configuration.md)

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,161 @@
 # AgentBrowse Troubleshooting
 
-## Browser Does Not Launch Headful
-
-If `launch(...)` fails in a local GUI flow:
-
-- 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
+Common failures and what to do about each.
+
+## `launch(...)` Fails
+
+Most `launch(...)` failures come from the environment, not from AgentBrowse
+itself:
+
+- **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. In the sticky-owner architecture this should only happen
+  during the initial `attach(...)` or an explicit repair attempt after the
+  original owner was lost, not during every healthy command.
+- **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
+
+A `session` handle is valid only while the underlying browser connection
+is live.
+
+- If the detached sticky owner died but the browser is still alive,
+  AgentBrowse may repair ownership on the next command or explicit restore
+  path.
+- If the detached sticky owner hit its TTL, the next browser command may
+  recycle the owner and continue as long as the browser session is still live.
+- If the browser process or remote CDP session died, the next
+  `act(...)` / `observe(...)` call fails closed. 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, or a later command fails with
+  `sticky_owner_unrecoverable`, discard it and start fresh.
+- `close(session)` called twice is safe — the second call is a no-op, and an
+  already-dead owner host is treated as already closed.
+
+## Restored Session Loads As `null`
+
+`loadBrowserSession()` and custom stores intentionally reject incompatible
+older session records that do not contain persistable sticky-owner metadata.
+
+If a session that used to restore now loads as `null`:
+
+- treat it as a stale local record, not as a partial session you should patch
+  by hand;
+- delete the old session file if it is still on disk;
+- run `launch(...)` or `attach(...)` again to create a new session record.
+
+AgentBrowse does not auto-migrate reconnect-era session files.
+
+## `close(session)` Seems Stuck Or The Owner Host Already Died
+
+`close(session)` first terminates the sticky owner and then closes the managed
+browser when the session owns it.
+
+- If the owner host is already gone, close remains idempotent.
+- For detached owner hosts, AgentBrowse escalates from graceful termination to
+  a forced kill internally; there is no separate daemon command to run.
+- In CLI wrappers, a successful close also clears the locally persisted browser
+  session and workflow bindings.
+- If closing the managed browser itself fails, AgentBrowse reports that failure
+  and keeps the session record so you can inspect or retry.
 
 ## Why The Package Uses Both Puppeteer And Playwright
 
-`launch(...)` uses Puppeteer for the managed browser connection layer with
-stealth evasions enabled.
-
-After the browser is up, normal page interaction runs through Playwright CDP.
+`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.
 
-That split exists to reduce unnecessary anti-bot friction during managed launch
-while keeping the live runtime on the Playwright side.
+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.61",
   "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",

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

@@ -1,22 +0,0 @@
-import type { BrowserSessionState } from './browser-session-state.js';
-import { type ProtectedFillExecutionResult } from './secrets/protected-fill.js';
-import type { PersistedFillableForm, StoredSecretFieldPolicies, StoredSecretFieldKey } from './secrets/types.js';
-export type FillProtectedFormBrowserResult = {
-    success: true;
-    pageRef: string;
-    url: string;
-    title: string;
-    execution: ProtectedFillExecutionResult;
-} | {
-    success: false;
-    error: 'browser_connection_failed' | 'page_resolution_failed';
-    message: string;
-    reason: string;
-};
-export declare function fillProtectedFormBrowser(params: {
-    session: BrowserSessionState;
-    fillableForm: PersistedFillableForm;
-    protectedValues: Partial<Record<StoredSecretFieldKey, string>>;
-    fieldPolicies?: StoredSecretFieldPolicies;
-}): Promise<FillProtectedFormBrowserResult>;
-//# sourceMappingURL=protected-fill-browser.d.ts.map

package/dist/protected-fill-browser.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"protected-fill-browser.d.ts","sourceRoot":"","sources":["../src/protected-fill-browser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAOtE,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EACV,qBAAqB,EACrB,yBAAyB,EACzB,oBAAoB,EACrB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,8BAA8B,GACtC;IACE,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,4BAA4B,CAAC;CACzC,GACD;IACE,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,2BAA2B,GAAG,wBAAwB,CAAC;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEN,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,OAAO,EAAE,mBAAmB,CAAC;IAC7B,YAAY,EAAE,qBAAqB,CAAC;IACpC,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/D,aAAa,CAAC,EAAE,yBAAyB,CAAC;CAC3C,GAAG,OAAO,CAAC,8BAA8B,CAAC,CAqD1C"}

package/dist/protected-fill-browser.js

@@ -1,52 +0,0 @@
-import { connectPlaywright, disconnectPlaywright, resolvePageByRef, syncSessionPage, } from './playwright-runtime.js';
-import { executeProtectedFill, } from './secrets/protected-fill.js';
-export async function fillProtectedFormBrowser(params) {
-    let browser = null;
-    try {
-        browser = await connectPlaywright(params.session.cdpUrl);
-    }
-    catch (error) {
-        return {
-            success: false,
-            error: 'browser_connection_failed',
-            message: 'Protected fill could not connect to the browser.',
-            reason: error instanceof Error ? error.message : String(error),
-        };
-    }
-    try {
-        const page = await resolvePageByRef(browser, params.session, params.fillableForm.pageRef).catch((error) => {
-            throw new Error(error instanceof Error ? error.message : String(error));
-        });
-        const { url, title } = await syncSessionPage(params.session, params.fillableForm.pageRef, page);
-        const execution = await executeProtectedFill({
-            session: params.session,
-            page,
-            fillableForm: params.fillableForm,
-            protectedValues: Object.fromEntries(Object.entries(params.protectedValues).filter((entry) => {
-                const value = entry[1];
-                return typeof value === 'string' && value.length > 0;
-            })),
-            fieldPolicies: params.fieldPolicies,
-        });
-        return {
-            success: true,
-            pageRef: params.fillableForm.pageRef,
-            url,
-            title,
-            execution,
-        };
-    }
-    catch (error) {
-        return {
-            success: false,
-            error: 'page_resolution_failed',
-            message: 'Protected fill could not resolve the target page in the browser.',
-            reason: error instanceof Error ? error.message : String(error),
-        };
-    }
-    finally {
-        if (browser) {
-            await disconnectPlaywright(browser);
-        }
-    }
-}