@mercuryo-ai/agentbrowse 0.2.57 → 0.2.61

package/README.md

@@ -9,24 +9,41 @@ web pages — launch a browser, read what's on screen, interact with it, and
 extract structured data. Your app keeps full control of orchestration and
 business logic; AgentBrowse handles the page.
 
-Key capabilities:
-
-- launch a managed browser or attach to an existing CDP session;
-- inspect the page and get stable target references (no raw selectors);
-- click, type, select, and fill through those references;
-- extract structured data with an optional LLM-backed runtime;
-- capture screenshots and check session health.
-
-A good first way to think about it is:
-
-1. launch a browser or attach to one and get a `session`
-2. inspect the page with `observe(...)`
-3. use `act(...)` to interact with what you found
-4. use `extract(...)` when you need structured data instead of an action
-5. close the session when you are done
-
-This makes AgentBrowse fit naturally into a worker, backend service, CLI, or
-agent runtime that already exists.
+Typical workflow:
+
+1. open a browser (or attach to an existing one) and get a `session`;
+2. ask AgentBrowse what's on the page with `observe(...)`;
+3. act on what you found with `act(...)`;
+4. use `extract(...)` when you need structured data instead of an action;
+5. close the session when you are done.
+
+That shape fits naturally into a worker, backend service, CLI, or agent
+runtime you already have.
+
+## Key Terms
+
+Three terms come up repeatedly in the API:
+
+- **`session`** — the handle AgentBrowse returns from `launch(...)` or
+  `attach(...)`. You pass it into every later call. The session carries
+  browser identity, runtime state, and sticky-owner metadata so healthy
+  commands reuse one browser owner instead of opening a fresh root CDP
+  attach for every call. If you persist a session across process runs,
+  the next command may repair that owner while the underlying browser is
+  still alive; otherwise the session fails closed and you should
+  `launch(...)` or `attach(...)` again.
+- **`ref`** (also `targetRef`, `scopeRef`, `fillRef`) — a stable reference
+  returned by `observe(...)`. You act on references, never on raw CSS
+  selectors. **Refs are valid for the page state that produced them, not
+  forever.** Navigation, route changes, or a major DOM re-render
+  invalidate them — call `observe(...)` again to get fresh refs.
+- **CDP** — the Chrome DevTools Protocol. Chrome, Chromium, and Playwright
+  all speak it. If a browser exposes a CDP WebSocket URL, AgentBrowse can
+  attach to it.
+
+Optionally, AgentBrowse can call an LLM to understand pages at a higher
+level. That layer is called the *assistive runtime* and is only required
+for `extract(...)` and goal-driven `observe(session, goal)`.
 
 ## Install
 
@@ -34,24 +51,15 @@ agent runtime that already exists.
 npm i @mercuryo-ai/agentbrowse
 ```
 
-If you want the operator-facing CLI, install `@mercuryo-ai/agentbrowse-cli`.
+If you want the operator-facing CLI command, install the separate global CLI
+package:
 
-## The Core Mental Model
-
-There are four ideas you need to understand before using the library:
+```bash
+npm i -g @mercuryo-ai/agentbrowse-cli@latest
+```
 
-- `session`
-  The handle for a running browser. `launch(...)` or `attach(...)` returns it,
-  and you pass it into the rest of the API.
-- `observe`
-  Reads the page and tells you what AgentBrowse found: targets, scopes,
-  signals, and forms.
-- `ref`
-  A stable reference returned by `observe(...)`. You use it with `act(...)`
-  instead of managing selectors yourself.
-- `assistive runtime`
-  Optional LLM-backed page understanding. You only need it for extraction and
-  for better quality in some goal-based `observe(session, goal)` calls.
+`@mercuryo-ai/agentbrowse` is the library package for imports. It does not
+install the `agentbrowse` shell command.
 
 ## Quick Start
 
@@ -101,8 +109,8 @@ try {
   }
 
   const statusResult = await status(session);
-  if (!statusResult.success) {
-    throw new Error(statusResult.reason ?? statusResult.message);
+  if (!statusResult.alive) {
+    throw new Error('Browser is no longer reachable.');
   }
 } finally {
   await close(session);
@@ -116,30 +124,24 @@ Runnable examples live in [`examples/`](./examples/README.md):
 - `npx tsx examples/attach.ts`
 - `npx tsx examples/extract.ts`
 
-## Managed Launch Runtime Note
+The library entrypoint does not load `.env` files. Environment loading only
+happens in the CLI entrypoint.
 
-When you use `launch(...)`, the package includes `puppeteer` for the managed
-browser connection layer with stealth evasions enabled by default.
-
-The goal is practical: reduce unnecessary anti-bot friction such as extra
-captcha or challenge pages on sensitive sites.
-
-After the browser is up, the normal live browser interaction flow still runs
-over Playwright CDP.
-
-The library entrypoint does not load `.env` files. Environment loading is only
-part of the CLI entrypoint.
+Both `launch(...)` and `attach(...)` bootstrap the same sticky-owner
+lifecycle. That owner may live in-process or in an internal detached host,
+but it is not a user-managed daemon contract.
 
 ## Attach To An Existing Browser
 
-If you already have a browser that exposes a CDP websocket, use `attach(...)`
-instead of `launch(...)`.
+If you already have a browser that exposes a CDP WebSocket URL, use
+`attach(...)` instead of `launch(...)`.
 
-That works for:
+Common sources of a CDP URL:
 
-- a local Chrome or Chromium process started with remote debugging enabled;
-- a cloud browser session that gives you a CDP websocket URL;
-- any other browser runtime that Playwright can reach through CDP.
+- a local Chrome or Chromium started with the `--remote-debugging-port` flag;
+- a managed cloud browser (Browserbase, Browserless, and similar) that hands
+  you a WebSocket URL;
+- any other browser runtime Playwright can reach through CDP.
 
 ```ts
 import { attach, observe } from '@mercuryo-ai/agentbrowse';
@@ -164,6 +166,11 @@ const attached = await attach(remoteCdpUrl, {
 });
 ```
 
+`attach(...)` is not a separate reconnect mode. It is the second bootstrap
+path into the same sticky-owner execution model as `launch(...)`. After
+attach succeeds, later browser commands reuse or repair that owner instead of
+performing a fresh provider-level root attach on every healthy command.
+
 ## What Each Main API Does
 
 | API | Use it when | Typical result |
@@ -198,8 +205,8 @@ In practice, that mainly means:
 - `extract(...)`
 - better quality goal-based `observe(session, goal)`
 
-The runtime contract is intentionally small: you provide an object that can
-create an OpenAI-compatible chat-completions client.
+The runtime interface is intentionally small: you provide an object that
+can create an OpenAI-compatible chat-completions client.
 
 ```ts
 // Pseudocode shape only. For a runnable fetch-based adapter, see
@@ -246,6 +253,18 @@ store.save(session);
 const restoredFromCustomRoot = store.load();
 ```
 
+Persisted session files contain versioned sticky-owner metadata, not a live
+Playwright connection. `loadBrowserSession()` and custom stores intentionally
+return `null` for incompatible reconnect-era records or incomplete owner
+metadata instead of auto-migrating them. After loading a session, call
+`status(restored)` or let the next browser command verify or repair
+ownership. If the underlying browser is gone, the session fails closed and
+you start fresh with `launch(...)` or `attach(...)`.
+
+There is no separate daemon API to supervise. `close(session)` is the public
+lifecycle boundary for shutting down the internal owner host and, when
+applicable, the managed browser itself.
+
 If you want to use a proxy, pass it directly to `launch(...)`:
 
 ```ts
@@ -278,7 +297,7 @@ See:
 ## Testing Wrappers Around AgentBrowse
 
 If your package wraps AgentBrowse and you want a stable test helper for the
-assistive runtime contract, use the dedicated testing subpath:
+assistive runtime, use the dedicated testing subpath:
 
 ```ts
 import {

package/dist/browser-session-state.d.ts

@@ -4,6 +4,29 @@ import type { ProxyConfig } from './solver/types.js';
 export interface BrowserSessionCapabilities {
     captchaSolve?: boolean;
 }
+export declare const STICKY_OWNER_SCHEMA_VERSION: 1;
+export type StickyOwnerState = 'bootstrapping' | 'active' | 'recovering' | 'dead';
+export interface StickyOwnerPlaywrightBindTransport {
+    type: 'playwright_bind';
+    endpoint: string;
+    mode: 'pipe' | 'ws';
+}
+export interface StickyOwnerInProcessTransport {
+    type: 'in_process';
+}
+export type StickyOwnerTransport = StickyOwnerPlaywrightBindTransport | StickyOwnerInProcessTransport;
+export interface StickyOwnerMetadata {
+    version: typeof STICKY_OWNER_SCHEMA_VERSION;
+    hostId: string;
+    state: StickyOwnerState;
+    startedAt: string;
+    lastUsedAt?: string;
+    ttlMs?: number;
+    touchPath?: string;
+    browserSessionId: string;
+    transport: StickyOwnerTransport;
+    pid?: number;
+}
 /** Persisted browser session state shared across AgentBrowse commands. */
 export interface BrowserSessionState {
     cdpUrl: string;
@@ -15,6 +38,7 @@ export interface BrowserSessionState {
     transport?: BrowseSessionTransport;
     capabilities?: BrowserSessionCapabilities;
     runtime?: BrowseRuntimeState;
+    stickyOwner?: StickyOwnerMetadata;
 }
 /** Browser session state plus transient run-scoped metadata. */
 export interface BrowserCommandSession extends BrowserSessionState {
@@ -53,6 +77,21 @@ type AttachedBrowserSessionInput = Omit<BrowserSessionState, 'port' | 'identity'
     browserInstanceRef?: string;
     provider?: string;
 };
+export declare function isStickyOwnerMetadata(value: unknown): value is StickyOwnerMetadata;
+export declare function canPersistStickyOwnerMetadata(value: unknown): value is StickyOwnerMetadata & {
+    transport: StickyOwnerPlaywrightBindTransport;
+};
+export declare function buildStickyOwnerMetadata(input: {
+    hostId: string;
+    state: StickyOwnerState;
+    startedAt: string;
+    lastUsedAt?: string;
+    ttlMs?: number;
+    touchPath?: string;
+    browserSessionId: string;
+    transport: StickyOwnerTransport;
+    pid?: number;
+}): StickyOwnerMetadata;
 export declare function parseSessionPort(cdpUrl: string): number | undefined;
 /** Converts a CDP websocket or HTTP endpoint into the matching DevTools HTTP endpoint. */
 export declare function buildCdpHttpEndpointUrl(cdpUrl: string, resourcePath?: '/json/version' | '/json/list'): string | null;

package/dist/browser-session-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-session-state.d.ts","sourceRoot":"","sources":["../src/browser-session-state.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"browser-session-state.d.ts","sourceRoot":"","sources":["../src/browser-session-state.ts"],"names":[],"mappings":"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"}

package/dist/browser-session-state.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, wr
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { scrubProtectedExactValues } from './secrets/protected-exact-value-redaction.js';
+export const STICKY_OWNER_SCHEMA_VERSION = 1;
 const BLOCKED_SESSION_KEYS = new Set([
     'rawValue',
     'rawValues',
@@ -21,6 +22,67 @@ function ensureStateDir(stateDir) {
         mkdirSync(stateDir, { recursive: true });
     }
 }
+function isStickyOwnerTransport(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    if (candidate.type === 'in_process') {
+        return true;
+    }
+    if (candidate.type !== 'playwright_bind') {
+        return false;
+    }
+    const endpointCandidate = candidate.endpoint;
+    const endpoint = typeof endpointCandidate === 'string' ? endpointCandidate.trim() : '';
+    const mode = candidate.mode;
+    return endpoint.length > 0 && (mode === 'pipe' || mode === 'ws');
+}
+function isStickyOwnerState(value) {
+    return (value === 'bootstrapping' || value === 'active' || value === 'recovering' || value === 'dead');
+}
+export function isStickyOwnerMetadata(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    return (candidate.version === STICKY_OWNER_SCHEMA_VERSION &&
+        typeof candidate.hostId === 'string' &&
+        candidate.hostId.trim().length > 0 &&
+        isStickyOwnerState(candidate.state) &&
+        typeof candidate.startedAt === 'string' &&
+        candidate.startedAt.trim().length > 0 &&
+        (candidate.lastUsedAt === undefined ||
+            (typeof candidate.lastUsedAt === 'string' && candidate.lastUsedAt.trim().length > 0)) &&
+        (candidate.ttlMs === undefined ||
+            (typeof candidate.ttlMs === 'number' &&
+                Number.isFinite(candidate.ttlMs) &&
+                candidate.ttlMs > 0)) &&
+        (candidate.touchPath === undefined ||
+            (typeof candidate.touchPath === 'string' && candidate.touchPath.trim().length > 0)) &&
+        typeof candidate.browserSessionId === 'string' &&
+        candidate.browserSessionId.trim().length > 0 &&
+        isStickyOwnerTransport(candidate.transport) &&
+        (candidate.pid === undefined ||
+            (typeof candidate.pid === 'number' && Number.isFinite(candidate.pid) && candidate.pid > 0)));
+}
+export function canPersistStickyOwnerMetadata(value) {
+    return isStickyOwnerMetadata(value) && value.transport.type === 'playwright_bind';
+}
+export function buildStickyOwnerMetadata(input) {
+    return {
+        version: STICKY_OWNER_SCHEMA_VERSION,
+        hostId: input.hostId,
+        state: input.state,
+        startedAt: input.startedAt,
+        ...(input.lastUsedAt ? { lastUsedAt: input.lastUsedAt } : {}),
+        ...(typeof input.ttlMs === 'number' ? { ttlMs: input.ttlMs } : {}),
+        ...(input.touchPath ? { touchPath: input.touchPath } : {}),
+        browserSessionId: input.browserSessionId,
+        transport: input.transport,
+        ...(typeof input.pid === 'number' ? { pid: input.pid } : {}),
+    };
+}
 function atomicWriteJson(path, contents) {
     const tempPath = `${path}.${process.pid}.tmp`;
     try {
@@ -136,7 +198,7 @@ export function createBrowserSessionStore(options = {}) {
             }
             try {
                 const raw = JSON.parse(readFileSync(sessionPath, 'utf-8'));
-                if (!raw.cdpUrl) {
+                if (!raw.cdpUrl || !canPersistStickyOwnerMetadata(raw.stickyOwner)) {
                     return null;
                 }
                 return raw;

package/dist/command-name.js

@@ -1,8 +1,8 @@
-const DEFAULT_BROWSE_COMMAND = 'agentbrowse';
 function normalizeCommandName(value, fallback) {
     const normalized = value?.trim().replace(/\s+/g, ' ');
     return normalized && normalized.length > 0 ? normalized : fallback;
 }
+const DEFAULT_BROWSE_COMMAND = 'agentbrowse';
 export function browseCommandName() {
     return normalizeCommandName(process.env.AGENTBROWSE_COMMAND, DEFAULT_BROWSE_COMMAND);
 }

package/dist/commands/act.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/commands/act.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAYzE,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AA6BtB,OAAO,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AA4CxF,2DAA2D;AAC3D,eAAO,MAAM,eAAe,oWAgBlB,CAAC;AAEX,uDAAuD;AACvD,eAAO,MAAM,iBAAiB,8FAMpB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAC5D,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,8CAA8C;AAC9C,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG;IAC5C,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,yEAAyE;AACzE,MAAM,MAAM,yBAAyB,GAAG,qBAAqB,GAAG;IAC9D,OAAO,EAAE,KAAK,CAAC;IACf,cAAc,EAAE,UAAU,CAAC;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC,cAAc,EAAE,eAAe,GAAG,SAAS,GAAG,aAAa,CAAC,CAAC;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,yBAAyB,GAAG,YAAY,GAAG;IACrD,OAAO,EAAE,KAAK,CAAC;IACf,cAAc,EAAE,QAAQ,CAAC;IACzB,KAAK,EAAE,YAAY,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC,cAAc,EAAE,eAAe,GAAG,SAAS,CAAC,CAAC;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,yBAAyB,GAAG,yBAAyB,CAAC;AAErF,MAAM,MAAM,SAAS,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAmK5D,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,CAAC;AAC1C,YAAY,EAAE,YAAY,EAAE,CAAC;AA+Q7B,wBAAsB,UAAU,CAC9B,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,EACpB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,SAAS,CAAC,CAg2BpB;AAED,wBAAsB,GAAG,CACvB,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,EACpB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAaf"}
+{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/commands/act.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAgBzE,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AA6BtB,OAAO,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAwCxF,2DAA2D;AAC3D,eAAO,MAAM,eAAe,oWAgBlB,CAAC;AAEX,uDAAuD;AACvD,eAAO,MAAM,iBAAiB,8FAMpB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAC5D,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,8CAA8C;AAC9C,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG;IAC5C,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,yEAAyE;AACzE,MAAM,MAAM,yBAAyB,GAAG,qBAAqB,GAAG;IAC9D,OAAO,EAAE,KAAK,CAAC;IACf,cAAc,EAAE,UAAU,CAAC;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC,cAAc,EAAE,eAAe,GAAG,SAAS,GAAG,aAAa,CAAC,CAAC;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,yBAAyB,GAAG,YAAY,GAAG;IACrD,OAAO,EAAE,KAAK,CAAC;IACf,cAAc,EAAE,QAAQ,CAAC;IACzB,KAAK,EAAE,YAAY,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC,cAAc,EAAE,eAAe,GAAG,SAAS,CAAC,CAAC;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,yBAAyB,GAAG,yBAAyB,CAAC;AAErF,MAAM,MAAM,SAAS,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAmK5D,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,CAAC;AAC1C,YAAY,EAAE,YAAY,EAAE,CAAC;AA+Q7B,wBAAsB,UAAU,CAC9B,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,EACpB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,SAAS,CAAC,CA+3BpB;AAED,wBAAsB,GAAG,CACvB,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,EACpB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAaf"}