@mercuryo-ai/agentbrowse 0.2.60 → 0.2.63

package/docs/testing.md

@@ -1,30 +1,36 @@
 # AgentBrowse Testing Guide
 
-Use the published testing subpath when your package wraps AgentBrowse and you
-need a stable assistive-runtime helper in tests.
+Use the published `/testing` subpath when your package wraps AgentBrowse
+and needs a stable, typed set of testing helpers. The subpath covers two
+separate testing concerns: the assistive runtime (needed by
+`extract(...)` and goal-based `observe(...)` callers) and the
+`match` / `resolve` / `fill` primitives.
 
 ## Testing Export
 
 ```ts
 import {
+  // Match / resolve / fill fixtures
+  createFixtureMatchStore,
+  createFixtureGroupStore,
+  createFixtureResolver,
+  fixtureResolvedValue,
+  fixtureResolvedArtifact,
+  // Assistive runtime fixture
   installFetchBackedTestAssistiveRuntime,
   uninstallTestAssistiveRuntime,
 } from '@mercuryo-ai/agentbrowse/testing';
 ```
 
-## What It Does
+All exports are stable across minor versions within the package. Rely on
+them instead of reaching into `src/**/*.test-support.ts` files
+directly — those are implementation detail.
 
-`installFetchBackedTestAssistiveRuntime(...)` installs a process-global
-assistive runtime that sends structured chat requests over `fetch`.
+## Assistive Runtime Fixture
 
-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
-  shape
-
-## Example
+Installs a process-global assistive runtime that sends structured chat
+requests over `fetch`. Use it when your tests wrap `extract(...)` or
+goal-based `observe(session, goal)`.
 
 ```ts
 import {
@@ -45,7 +51,133 @@ afterEach(() => {
 });
 ```
 
-## Scope
-
 This helper targets the assistive runtime only. It does not mock browser
 sessions, pages, or observed targets.
+
+## Match / Resolve / Fill Fixtures
+
+Five builders let you exercise the primitives without constructing the
+internal match result objects by hand (which would bypass the accessor
+pattern and produce results that fail to fill). Prefer these over raw
+object literals in unit tests.
+
+### `createFixtureMatchStore(entries)`
+
+Builds an `AgentbrowseMatchStore` — an opaque single-field candidate
+source. The store's `entries()` returns candidate metadata without
+values; values are only read back through `store.read(candidateRef)`
+when `match(...)` needs them. Use this when your test wants to assert
+that raw values stay inside the store.
+
+```ts
+import { match } from '@mercuryo-ai/agentbrowse';
+import { createFixtureMatchStore } from '@mercuryo-ai/agentbrowse/testing';
+
+const store = createFixtureMatchStore([
+  {
+    candidateRef: 'profile.email.primary',
+    fieldKey: 'email',
+    type: 'email',
+    value: 'traveler@example.com',
+  },
+]);
+
+const matched = await match(emailTarget, { from: store });
+// matched.kind === 'ready' — and JSON.stringify(matched) does not
+// contain 'traveler@example.com'.
+```
+
+### `createFixtureGroupStore(entries)`
+
+The grouped counterpart — builds an `AgentbrowseGroupMatchStore` for
+whole-form candidates with artifacts. Same opacity guarantee:
+artifacts only come out through `store.readArtifact(candidateRef)`.
+
+```ts
+import { createFixtureGroupStore } from '@mercuryo-ai/agentbrowse/testing';
+
+const store = createFixtureGroupStore([
+  {
+    candidateRef: 'vault_login_1',
+    itemRef: 'vault_login_1',
+    label: 'Airline Login',
+    fieldKeys: ['username', 'password'],
+    confidence: 'high',
+    artifact: {
+      kind: 'values',
+      values: { username: 'traveler@example.com', password: 'secret' },
+    },
+  },
+]);
+
+const matched = await match(fillableForm, { from: store });
+```
+
+### `createFixtureResolver(resourcesByCandidateRef, { enableBatch? })`
+
+Builds an `AgentbrowseMatchResolver` adapter that satisfies the
+interface with recorded call history. Returns
+`{ adapter, resolveCalls, resolveBatchCalls }`. Pass
+`{ enableBatch: true }` to also wire up `resolveBatch`.
+
+```ts
+import { resolve, fill } from '@mercuryo-ai/agentbrowse';
+import {
+  createFixtureResolver,
+  fixtureResolvedValue,
+} from '@mercuryo-ai/agentbrowse/testing';
+
+const resolver = createFixtureResolver({
+  'candidate:password:0': fixtureResolvedValue('top-secret-password'),
+});
+
+const ready = await resolve(pendingMatch, { with: resolver.adapter });
+await fill(session, passwordTarget, ready);
+
+expect(resolver.resolveCalls).toHaveLength(1);
+expect(resolver.resolveCalls[0].candidateRef).toBe('candidate:password:0');
+```
+
+### `fixtureResolvedValue(value)` and `fixtureResolvedArtifact(artifact, options?)`
+
+Typed builders for the resource shapes returned by a resolver. Use them
+to avoid redeclaring `{ kind: 'value', ... }` in every fixture call.
+
+```ts
+fixtureResolvedValue('top-secret-password');
+// => { kind: 'value', value: 'top-secret-password' }
+
+fixtureResolvedArtifact(
+  { kind: 'values', values: { username: '…', password: '…' } },
+  { itemRef: 'vault_login_1', requestId: 'req_123' },
+);
+// => { kind: 'artifact', artifact, itemRef, requestId }
+```
+
+### Typing a grouped-only handler
+
+When a test only exercises the `ready_group` → `fill(...)` path, a
+bare `{ fill }` object typed as `AgentbrowseGroupFillHandler` is
+enough — no need to construct a full `AgentbrowseMatchResolver` with a
+stub `resolve`:
+
+```ts
+import type { AgentbrowseGroupFillHandler } from '@mercuryo-ai/agentbrowse';
+
+const applier: AgentbrowseGroupFillHandler = {
+  fill: vi.fn(async () => ({ success: true, outcomeType: 'filled' })),
+};
+
+await fill(session, fillableForm, readyGroupMatch, { resolver: applier });
+```
+
+## Scope
+
+These fixtures target two concerns only: the assistive runtime used by
+`extract` and goal-based `observe`, and the `match` / `resolve` / `fill`
+primitives. They do not mock browser sessions, pages, observed targets,
+or the underlying `act(...)` path — build those from real `launch(...)`
+sessions against a data: URL when an integration test needs them.
+
+See the [Match / Resolve / Fill Guide](./match-resolve-fill.md) for the
+full mental model of the primitives these fixtures exercise.

package/docs/troubleshooting.md

@@ -2,6 +2,11 @@
 
 Common failures and what to do about each.
 
+For the full per-command `error` code vocabulary (with short "when /
+action" notes), see
+[`api-reference.md` → Error codes by command](./api-reference.md#error-codes-by-command).
+This guide covers diagnosis patterns; the reference covers the codes.
+
 ## `launch(...)` Fails
 
 Most `launch(...)` failures come from the environment, not from AgentBrowse
@@ -23,7 +28,9 @@ Inspect the `error` and `reason` fields on the `launch(...)` failure result
 - **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.
+  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.
@@ -33,13 +40,47 @@ Inspect the `error` and `reason` fields on the `launch(...)` failure result
 A `session` handle is valid only while the underlying browser connection
 is live.
 
-- 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 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, discard it and start fresh.
-- `close(session)` called twice is safe — the second call is a no-op.
+  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
 

package/examples/README.md

@@ -15,6 +15,7 @@ Then run the examples from `packages/agentbrowse`:
 npx tsx examples/basic.ts
 npx tsx examples/attach.ts
 npx tsx examples/extract.ts
+npx tsx examples/match-resolve-fill.ts
 ```
 
 Examples:
@@ -27,6 +28,12 @@ Examples:
 - `extract.ts`
   Runs structured extraction with an assistive runtime and a plain schema
   object.
+- `match-resolve-fill.ts`
+  Demonstrates `match`, `resolve`, and `fill` against a self-contained
+  data: URL form: `match(...)` picks candidates, `resolve(...)` walks an
+  unresolved plan through a stub vault resolver, and `fill(...)` applies
+  both values through the browser without placing them in the match
+  result itself.
 
 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).

package/examples/match-resolve-fill.ts

@@ -0,0 +1,107 @@
+import {
+  close,
+  fill,
+  launch,
+  match,
+  observe,
+  resolve,
+  type AgentbrowseMatchResolver,
+} from '@mercuryo-ai/agentbrowse';
+
+// Self-contained data URL with two inputs — keeps the example runnable
+// without depending on any external page.
+const FORM_PAGE = `data:text/html;charset=utf-8,${encodeURIComponent(`
+<!doctype html>
+<html lang="en">
+  <head><meta charset="utf-8"><title>Match / Resolve / Fill demo</title></head>
+  <body>
+    <form>
+      <label>Email <input type="email" name="email" autocomplete="email"></label>
+      <label>Password <input type="password" name="password" autocomplete="current-password"></label>
+    </form>
+  </body>
+</html>
+`)}`;
+
+// Fake resolver that stands in for a vault lookup. In production it would
+// call MagicPay, another secret manager, or an approval backend.
+const vaultResolver: AgentbrowseMatchResolver = {
+  async resolve(plan) {
+    if ('fillRef' in plan) {
+      throw new Error('This example does not support grouped resolution plans.');
+    }
+    if (plan.resolve.kind !== 'example_vault' || plan.resolve.key !== 'demo.password') {
+      throw new Error(`Unknown resolution plan: ${plan.resolve.kind} / ${plan.resolve.key}`);
+    }
+    return { kind: 'value', value: 'top-secret-password' };
+  },
+};
+
+const launchResult = await launch(FORM_PAGE, { headless: false });
+if (!launchResult.success) {
+  throw new Error(launchResult.reason ?? launchResult.message);
+}
+
+const { session } = launchResult;
+
+try {
+  const observed = await observe(session);
+  if (!observed.success) {
+    throw new Error(observed.reason ?? observed.message);
+  }
+
+  const emailTarget = observed.targets.find((target) => target.inputType === 'email');
+  const passwordTarget = observed.targets.find((target) => target.inputType === 'password');
+
+  if (!emailTarget || !passwordTarget) {
+    throw new Error('Expected email and password targets on the demo page.');
+  }
+
+  // ---- Simple path: match → fill ----------------------------------------
+  const emailMatch = await match(emailTarget, {
+    from: { email: 'traveler@example.com' },
+  });
+
+  if (emailMatch.kind !== 'ready') {
+    throw new Error(`Unexpected email match kind: ${emailMatch.kind}`);
+  }
+
+  // JSON.stringify proves the value is not in the match result itself.
+  console.info('email match kind:', emailMatch.kind);
+  console.info('email match serialised:', JSON.stringify(emailMatch));
+
+  const emailFill = await fill(session, emailTarget, emailMatch);
+  console.info('email fill success:', emailFill.success);
+
+  // ---- Explicit resolver path: match → resolve → fill -------------------
+  const passwordMatch = await match(passwordTarget, {
+    from: [
+      {
+        fieldKey: 'password',
+        type: 'secret',
+        resolve: { kind: 'example_vault', key: 'demo.password' },
+      },
+    ],
+  });
+
+  if (passwordMatch.kind !== 'needs_resolution') {
+    throw new Error(`Unexpected password match kind: ${passwordMatch.kind}`);
+  }
+
+  // The match result carries the plan, not the value. It is safe to log
+  // or to ship across a process boundary.
+  console.info('password plan:', passwordMatch.plan);
+
+  const passwordReady = await resolve(passwordMatch, { with: vaultResolver });
+  const passwordFill = await fill(session, passwordTarget, passwordReady);
+  console.info('password fill success:', passwordFill.success);
+
+  // ---- Equivalent one-call path -----------------------------------------
+  // `fill(...)` can do the resolve step inline when a resolver is passed:
+  //
+  //   await fill(session, passwordTarget, passwordMatch, { resolver: vaultResolver });
+  //
+  // Use it when you do not need to inspect the ready match between steps.
+} finally {
+  await close(session);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercuryo-ai/agentbrowse",
-  "version": "0.2.60",
+  "version": "0.2.63",
   "type": "module",
   "description": "Browser automation primitives library for AI agents",
   "license": "MIT",
@@ -11,7 +11,8 @@
     "ai-agent",
     "browser-sdk",
     "playwright",
-    "cdp"
+    "cdp",
+    "form-filling"
   ],
   "repository": {
     "type": "git",
@@ -81,6 +82,7 @@
     "test:e2e:autonomous": "npm run test:autonomous:scenarios",
     "test:e2e:autonomous:bare": "npm run test:autonomous:scenarios:bare",
     "check-types": "tsc --noEmit",
+    "check-types:examples": "npm run build && tsc -p tsconfig.examples.json",
     "lint": "biome check src docs README.md",
     "pack:verify": "node scripts/verify-pack-artifact.mjs",
     "smoke:pack-install": "node scripts/verify-pack-install-smoke.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);
-        }
-    }
-}