@mercuryo-ai/agentbrowse 0.2.50

package/docs/configuration.md

@@ -0,0 +1,287 @@
+# AgentBrowse Configuration Guide
+
+This guide covers the parts of AgentBrowse that you may want to configure:
+
+- browser session persistence
+- proxy launch settings
+- diagnostics hooks
+- client-scoped runtime configuration
+
+## Start With The Simplest Default
+
+Most applications can start with this mental model:
+
+1. call `launch(...)` or `attach(...)`
+2. keep the returned `session` in memory
+3. pass that `session` into later calls
+
+You only need more configuration when you want one of these:
+
+- custom LLM integration
+- custom diagnostics or tracing
+- session restore across process runs
+- proxy launch
+
+## Attach To An Existing Browser
+
+If you already have a CDP websocket URL, you do not need `launch(...)`.
+
+```ts
+import { attach } from '@mercuryo-ai/agentbrowse';
+
+const attached = await attach('ws://127.0.0.1:9222/devtools/browser/browser-id');
+```
+
+You can also label an attached session:
+
+```ts
+const attached = await attach(remoteCdpUrl, {
+  provider: 'browserbase',
+});
+```
+
+That provider label is metadata only. AgentBrowse still treats this as a
+generic CDP-attached browser session.
+
+## Client Configuration
+
+```ts
+import { createAgentbrowseClient } from '@mercuryo-ai/agentbrowse';
+
+const client = createAgentbrowseClient({
+  assistiveRuntime: { /* ... */ },
+  diagnostics: { /* ... */ },
+});
+```
+
+This is the best default when you embed AgentBrowse into a larger app because:
+
+- it keeps configuration local to your app or tenant
+- it is safer for parallel tests
+- it avoids process-global configuration collisions
+
+For small scripts, process-global configure helpers also exist, but client
+configuration is the cleaner embedded pattern.
+
+## Browser Session Persistence
+
+Persistence is optional. Use it when you want to restore a browser session
+after a process restart.
+
+### Default Store
+
+```ts
+import { loadBrowserSession, saveBrowserSession } from '@mercuryo-ai/agentbrowse';
+
+saveBrowserSession(session);
+const restored = loadBrowserSession();
+```
+
+Default path:
+
+`~/.agentbrowse/browse-session.json`
+
+### Custom Store
+
+For embedded apps, prefer an explicit store root:
+
+```ts
+import { createBrowserSessionStore } from '@mercuryo-ai/agentbrowse';
+
+const store = createBrowserSessionStore({
+  rootDir: '/tmp/my-app/browser-state',
+});
+
+store.save(session);
+const restored = store.load();
+store.delete();
+```
+
+This avoids hidden machine-level coupling to `~/.agentbrowse`.
+
+## Proxy Configuration
+
+The clearest way to use a proxy is to pass it directly to `launch(...)`.
+
+```ts
+import { launch } from '@mercuryo-ai/agentbrowse';
+
+const launchResult = await launch('https://example.com', {
+  useProxy: true,
+  proxy: 'http://user:pass@proxy.example:8080',
+});
+```
+
+Current launch behavior is:
+
+- if `useProxy` is not `true`, launch is direct
+- if `useProxy` is `true` and `proxy` is provided, that explicit proxy is used
+- if `useProxy` is `true` and `proxy` is omitted, AgentBrowse falls back to
+  `defaults.proxy` from `~/.agentbrowse/config.json`
+
+For embedded library usage, prefer explicit launch options over machine-level
+config files.
+
+## Diagnostics
+
+AgentBrowse is quiet by default. It does not write traces or diagnostics to
+disk unless you provide hooks.
+
+Client-scoped example:
+
+```ts
+import { createAgentbrowseClient } from '@mercuryo-ai/agentbrowse';
+
+const client = createAgentbrowseClient({
+  diagnostics: {
+    startStep(input) {
+      return {
+        finish() {
+          // your tracing or logging hook
+        },
+      };
+    },
+  },
+});
+```
+
+Use diagnostics when you need:
+
+- integration with your own tracing system
+- deeper command-level debugging
+- custom artifact collection
+
+If you do not need that, you can ignore diagnostics completely.
+
+### Diagnostics Contract
+
+Diagnostics hooks are intentionally low-level. They are designed to let your
+application map AgentBrowse command activity into its own tracing, logging, or
+artifact pipeline.
+
+#### `startStep(input)`
+
+Called when a command starts.
+
+Important fields on `input`:
+
+- `runId`
+  Stable run identifier for the surrounding browser workflow.
+- `command`
+  The AgentBrowse command name such as `observe`, `act`, or `extract`.
+- `input`
+  Command-specific input metadata. Examples:
+  `targetUrl`, `instruction`, `scopeRef`, extraction schema summary.
+- `refs`
+  Stable runtime refs such as `pageRef`, `targetRef`, `surfaceRef`, `fillRef`,
+  and `requestId`.
+- `protectedStep`
+  `true` when the current step is happening in a protected-value context.
+
+Return a `DiagnosticStepHandle`:
+
+```ts
+{
+  runId: 'run_123',
+  stepId: 'step_observe_1',
+  command: 'observe',
+}
+```
+
+That handle is then passed back into later diagnostics hooks for the same step.
+
+#### `finishStep(input)`
+
+Called when a command finishes.
+
+Important fields:
+
+- `step`
+  The handle returned from `startStep(...)`
+- `success`
+  Whether the command succeeded
+- `outcomeType`
+  High-level outcome classification
+- `message`
+  Human-readable command summary
+- `reason`
+  Extra failure detail when available
+- `artifactManifestId`
+  Optional link to a separately recorded artifact manifest
+
+#### `captureSnapshot(input)`
+
+Called for before/after/point-in-time snapshots.
+
+Important fields:
+
+- `phase`
+  One of `before`, `after`, or `point-in-time`
+- `pageRef`
+- `url`
+- `title`
+- `artifactRefs`
+  Optional file paths for screenshot, HTML, trace, or log artifacts
+
+#### `recordCommandEvent(input)`
+
+Called for lifecycle events:
+
+- `started`
+- `completed`
+- `failed`
+
+Use `attributes` for structured tracing tags or log enrichment.
+
+#### `recordChildSpan(input)`
+
+Called for nested client-side work such as LLM rerank spans.
+
+Important fields:
+
+- `name`
+- `kind`
+- `startedAt`
+- `endedAt`
+- `statusCode`
+- `statusMessage`
+- `attributes`
+
+#### `recordArtifactManifest(input)`
+
+Called when AgentBrowse has a grouped artifact manifest for a step.
+
+The manifest includes:
+
+- `screenshots`
+- `htmlSnapshots`
+- `traces`
+- `logs`
+- `suppressed`
+
+Each artifact entry includes its local path plus optional storage metadata.
+
+### Mapping To External Tracing
+
+Typical mapping strategy:
+
+- map `runId` to your trace or workflow id
+- map `stepId` to a span or operation id
+- copy `command`, `outcomeType`, and `refs` into structured attributes
+- treat `captureSnapshot(...)` and `recordArtifactManifest(...)` as artifact
+  enrichment, not as the main step identity
+
+Diagnostics hooks are best-effort. AgentBrowse continues its command flow even
+if your diagnostics implementation throws.
+
+## Process-Global Convenience Helpers
+
+AgentBrowse still exposes process-global convenience functions such as:
+
+- `configureAgentbrowseAssistiveRuntime(...)`
+- `configureAgentbrowseDiagnostics(...)`
+
+These are useful for small scripts and quick experiments.
+
+For embedded production usage, client-scoped configuration is the better
+default.

package/docs/getting-started.md

@@ -0,0 +1,237 @@
+# AgentBrowse Getting Started
+
+This guide is for a developer who wants to embed `@mercuryo-ai/agentbrowse` as a
+library into their own application.
+
+Read the package README first. This page is the practical follow-up: it turns
+the high-level overview into a simple working model for the main APIs.
+
+## Mental Model
+
+The normal flow is:
+
+1. `launch(...)` starts a managed browser, or `attach(...)` connects to an
+   existing CDP browser, and returns a `session`
+2. `observe(session)` inspects the current page
+3. `act(session, targetRef, ...)` interacts with targets returned by `observe`
+4. `extract(session, schema)` returns structured JSON from the page when
+   you need data instead of actions
+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.
+
+At a high level, AgentBrowse has three kinds of behavior:
+
+- normal browser execution for `launch`, `navigate`, `observe`, `act`,
+  `status`, `screenshot`, and `close`
+- assistive page understanding for `extract` and some goal-based
+  `observe(session, goal)` calls
+- protected fill for applying sensitive values you already have through a
+  guarded form execution path
+
+Most applications pair these browser primitives with their own orchestration,
+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.
+
+## Basic Example
+
+```ts
+import { act, close, launch, observe } from '@mercuryo-ai/agentbrowse';
+
+const launchResult = await launch('https://example.com/login');
+if (!launchResult.success) {
+  throw new Error(launchResult.reason ?? launchResult.message);
+}
+
+const { session } = launchResult;
+
+try {
+  const observeResult = await observe(session);
+  if (!observeResult.success) {
+    throw new Error(observeResult.reason ?? observeResult.message);
+  }
+
+  const emailTarget = observeResult.targets.find((target) =>
+    target.label?.toLowerCase().includes('email')
+  );
+
+  if (!emailTarget?.ref) {
+    throw new Error('Could not find an email field.');
+  }
+
+  const fillResult = await act(session, emailTarget.ref, 'fill', 'user@example.com');
+  if (!fillResult.success) {
+    throw new Error(fillResult.reason ?? fillResult.message);
+  }
+} finally {
+  await close(session);
+}
+```
+
+## What Each Main Command Is For
+
+### `launch(url?, options?)`
+
+Starts a new browser session. If you pass a URL, AgentBrowse opens it during
+launch.
+
+Success result includes:
+
+- `session`
+- current `url`
+- current `title`
+
+### `attach(cdpUrl, options?)`
+
+Connects AgentBrowse to an already running browser over CDP.
+
+This is the right entrypoint when:
+
+- your app launched Chrome itself;
+- your infrastructure gives you a CDP websocket URL;
+- you are reusing a cloud browser session.
+
+Success result includes:
+
+- `session`
+- current `url`
+- current `title`
+
+### `observe(session, goal?)`
+
+Reads the current page and returns what AgentBrowse found.
+
+Typical things in the result:
+
+- `targets`
+- `scopes`
+- `signals`
+- `fillableForms`
+
+Use `observe(session)` when you want a general inventory of the page.
+
+Use `observe(session, goal)` when you want a focused answer such as:
+
+- `"find the checkout total"`
+- `"find the email field"`
+- `"find the primary continue button"`
+
+`observe(session)` and `observe(session, goal)` share the same API, but they
+serve different intents:
+
+- `observe(session)` is for general page inspection
+- `observe(session, goal)` is for a focused question
+
+### `act(session, targetRef, action, value?)`
+
+Executes a browser action against a `targetRef` returned by `observe(...)`.
+
+Typical actions:
+
+- `click`
+- `fill`
+- `type`
+- `select`
+- `press`
+
+### `extract(session, schema, scopeRef?)`
+
+Returns structured JSON that matches the schema you provide.
+
+Pass either:
+
+- a plain schema object such as `{ total: 'number', currency: 'string' }`
+- a Zod schema
+
+This is the right tool when you want data, not a browser action.
+
+`extract(...)` currently needs an assistive runtime, so you must configure one
+before calling it.
+
+### `status(session)`
+
+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.
+
+### `close(session)`
+
+Closes the browser session.
+
+## How To Handle Results
+
+All main commands use the same broad pattern:
+
+```ts
+const result = await observe(session);
+
+if (!result.success) {
+  throw new Error(result.reason ?? result.message);
+}
+```
+
+If `success` is `true`, the rest of the fields describe the successful outcome.
+
+If `success` is `false`, the result tells you:
+
+- `error`
+- `message`
+- `reason`
+
+You can usually log `message` and use `reason` for debugging or developer logs.
+
+## When To Use Assistive Features
+
+You do not need an assistive runtime for:
+
+- `launch`
+- `attach`
+- `observe(session)` without a goal
+- `navigate`
+- `act`
+- `status`
+- `screenshot`
+- `close`
+
+You do need it for:
+
+- `extract`
+- better quality goal-based `observe(session, goal)`
+
+See:
+
+- [Assistive Runtime Guide](./assistive-runtime.md)
+
+## Persistence
+
+If your process is long-lived, you can keep the `session` in memory and ignore
+disk persistence completely.
+
+If you want to restore a browser session between process runs, use:
+
+- `saveBrowserSession(session)`
+- `loadBrowserSession()`
+- `createBrowserSessionStore({ rootDir })`
+
+See:
+
+- [Configuration Guide](./configuration.md)
+
+## Next Docs
+
+- [API Reference](./api-reference.md)
+- [Configuration Guide](./configuration.md)
+- [Assistive Runtime Guide](./assistive-runtime.md)
+- [Protected Fill Guide](./protected-fill.md)
+- [Troubleshooting](./troubleshooting.md)

package/docs/integration-checklist.md

@@ -0,0 +1,36 @@
+# AgentBrowse Integration Checklist
+
+Use this checklist when integrating the current `@mercuryo-ai/agentbrowse`
+contract into another package or service.
+
+## Core Assumptions
+
+- use `observeResult.targets` as the default flat inventory
+- use `target.ref` as the input to `act(...)`
+- pass a plain schema object or a Zod schema to `extract(...)`
+- branch on stable top-level `error` codes, not on `reason`
+- treat `reason` as human-readable diagnostics, not as a stable switch key
+
+## Assistive Runtime
+
+- the assistive runtime adapter receives `args.options`
+- provider adapters should map `messages`, optional `response_model`, optional
+  `image`, and optional `temperature` / `maxOutputTokens`
+- assistive adapters return `{ data, usage? }`
+
+## Testing
+
+- use `@mercuryo-ai/agentbrowse/testing` for the stable fetch-backed assistive
+  runtime helper
+- do not depend on internal fixtures or unexported runtime-state helpers
+
+## Packaging
+
+- 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
+
+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

@@ -0,0 +1,112 @@
+# AgentBrowse Protected Fill Guide
+
+Protected fill solves a specific problem:
+
+You already have sensitive values from your own approval or secret-management
+flow, and you want AgentBrowse to apply those values to a previously observed
+form in a guarded way.
+
+Normal fill and protected fill solve different problems.
+
+## When To Use Protected Fill
+
+Use protected fill when all of these are true:
+
+- you already observed the page and have a form description
+- you already have the sensitive values in your own application
+- you want AgentBrowse to apply them through a typed execution path
+
+Examples:
+
+- card number, expiry, CVV
+- password or one-time code
+- any field set that should not be treated like ordinary page text input
+
+## When A Normal `act(..., 'fill', value)` Is Enough
+
+Use ordinary `act(..., 'fill', value)` when:
+
+- the value is not sensitive
+- you are filling one simple field directly
+- you do not need form-level guarded execution
+
+## What Protected Fill Adds
+
+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.
+
+## Import
+
+```ts
+import { fillProtectedForm } from '@mercuryo-ai/agentbrowse/protected-fill';
+```
+
+## Example
+
+```ts
+import { observe } from '@mercuryo-ai/agentbrowse';
+import { fillProtectedForm } from '@mercuryo-ai/agentbrowse/protected-fill';
+
+const observeResult = await observe(session);
+if (!observeResult.success) {
+  throw new Error(observeResult.reason ?? observeResult.message);
+}
+
+const fillableForm = observeResult.fillableForms.find((form) => form.purpose === 'payment_card');
+if (!fillableForm) {
+  throw new Error('Could not find a payment_card form.');
+}
+
+const result = await fillProtectedForm({
+  session,
+  fillableForm,
+  protectedValues: {
+    card_number: '4111111111111111',
+    exp_month: '12',
+    exp_year: '2030',
+    cvv: '123',
+  },
+});
+
+if (!result.success) {
+  throw new Error(result.reason ?? result.message);
+}
+```
+
+## Where It Fits
+
+Protected fill handles the browser execution step.
+
+Applications usually pair it with their own:
+
+- secret storage
+- approval flow
+- policy decisions
+- claims or grants
+
+## What You Need Before Calling It
+
+Before protected fill, you usually need:
+
+1. a launched browser `session`
+2. a `fillableForm` produced by `observe(...)`
+3. the sensitive values from your own trusted source
+
+## Result Shape
+
+Protected fill returns a typed result that tells you whether the fill:
+
+- succeeded
+- failed because bindings became stale
+- failed validation
+- failed for another execution reason
+
+That makes it safer than treating every sensitive field as a raw one-off
+string fill.

package/docs/testing.md

@@ -0,0 +1,50 @@
+# AgentBrowse Testing Guide
+
+Use the published testing subpath when your package wraps AgentBrowse and you
+need a stable assistive-runtime helper in tests.
+
+## Testing Export
+
+```ts
+import {
+  installFetchBackedTestAssistiveRuntime,
+  uninstallTestAssistiveRuntime,
+} from '@mercuryo-ai/agentbrowse/testing';
+```
+
+## What It Does
+
+`installFetchBackedTestAssistiveRuntime(...)` installs a process-global
+assistive runtime that sends structured chat requests over `fetch`.
+
+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
+
+## Example
+
+```ts
+import {
+  installFetchBackedTestAssistiveRuntime,
+  uninstallTestAssistiveRuntime,
+} from '@mercuryo-ai/agentbrowse/testing';
+
+beforeEach(() => {
+  installFetchBackedTestAssistiveRuntime({
+    apiUrl: 'http://127.0.0.1:8787/api',
+    apiKey: 'test-key',
+    model: 'test-model',
+  });
+});
+
+afterEach(() => {
+  uninstallTestAssistiveRuntime();
+});
+```
+
+## Scope
+
+This helper is for the assistive runtime contract. It does not mock browser
+sessions, pages, or observed target inventories.