@mercuryo-ai/agentbrowse 0.2.50

package/dist/update-check.js

@@ -0,0 +1,182 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getSolverDir } from './solver/config.js';
+const PACKAGE_NAME = '@mercuryo-ai/agentbrowse';
+const PACKAGE_JSON_URL = new URL('../package.json', import.meta.url);
+const REGISTRY_METADATA_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}`;
+const DEFAULT_UPDATE_CHECK_TIMEOUT_MS = 1500;
+const DEFAULT_UPDATE_TTL_MS = 12 * 60 * 60 * 1000;
+export function compareVersions(left, right) {
+    const parsedLeft = parseVersion(left);
+    const parsedRight = parseVersion(right);
+    if (!parsedLeft || !parsedRight) {
+        return left.localeCompare(right, undefined, {
+            numeric: true,
+            sensitivity: 'base',
+        });
+    }
+    for (let i = 0; i < 3; i += 1) {
+        const diff = parsedLeft.core[i] - parsedRight.core[i];
+        if (diff !== 0) {
+            return diff;
+        }
+    }
+    if (!parsedLeft.prerelease && !parsedRight.prerelease) {
+        return 0;
+    }
+    if (!parsedLeft.prerelease) {
+        return 1;
+    }
+    if (!parsedRight.prerelease) {
+        return -1;
+    }
+    const length = Math.max(parsedLeft.prerelease.length, parsedRight.prerelease.length);
+    for (let i = 0; i < length; i += 1) {
+        const leftPart = parsedLeft.prerelease[i];
+        const rightPart = parsedRight.prerelease[i];
+        if (leftPart === undefined) {
+            return -1;
+        }
+        if (rightPart === undefined) {
+            return 1;
+        }
+        if (typeof leftPart === 'number' && typeof rightPart === 'number') {
+            const diff = leftPart - rightPart;
+            if (diff !== 0) {
+                return diff;
+            }
+            continue;
+        }
+        if (typeof leftPart === 'number') {
+            return -1;
+        }
+        if (typeof rightPart === 'number') {
+            return 1;
+        }
+        const diff = leftPart.localeCompare(rightPart);
+        if (diff !== 0) {
+            return diff;
+        }
+    }
+    return 0;
+}
+export async function checkForLaunchUpdate(options = {}) {
+    const currentVersion = readCurrentPackageVersion();
+    const now = options.now ?? new Date();
+    const ttlMs = options.ttlMs ?? DEFAULT_UPDATE_TTL_MS;
+    const cachedState = readUpdateState();
+    const cachedNotice = buildLaunchUpdateNotice(currentVersion, cachedState?.latestVersion);
+    if (cachedState && !isCacheStale(cachedState.lastCheckedAt, now, ttlMs)) {
+        return cachedNotice;
+    }
+    const latestVersion = await fetchLatestVersion({
+        fetchImpl: options.fetchImpl,
+        timeoutMs: options.timeoutMs ?? DEFAULT_UPDATE_CHECK_TIMEOUT_MS,
+    }).catch(() => null);
+    if (!latestVersion) {
+        return cachedNotice;
+    }
+    writeUpdateState({
+        packageName: PACKAGE_NAME,
+        latestVersion,
+        lastCheckedAt: now.toISOString(),
+    });
+    return buildLaunchUpdateNotice(currentVersion, latestVersion);
+}
+function parseVersion(version) {
+    const match = version
+        .trim()
+        .match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+.*)?$/);
+    if (!match) {
+        return null;
+    }
+    const prerelease = match[4]
+        ? match[4].split('.').map((part) => (/^\d+$/.test(part) ? Number(part) : part))
+        : null;
+    return {
+        core: [Number(match[1]), Number(match[2]), Number(match[3])],
+        prerelease,
+    };
+}
+function buildLaunchUpdateNotice(currentVersion, latestVersion) {
+    if (!latestVersion || compareVersions(latestVersion, currentVersion) <= 0) {
+        return null;
+    }
+    return {
+        currentVersion,
+        latestVersion,
+        message: `A newer agentbrowse version is available: ${latestVersion} (current: ${currentVersion}). Update with: npm i -g ${PACKAGE_NAME}@latest`,
+    };
+}
+function readCurrentPackageVersion() {
+    const raw = JSON.parse(readFileSync(PACKAGE_JSON_URL, 'utf-8'));
+    if (!raw.version || typeof raw.version !== 'string') {
+        throw new Error('Package version is missing from package.json.');
+    }
+    return raw.version;
+}
+function readUpdateState() {
+    const updateStatePath = getUpdateStatePath();
+    if (!existsSync(updateStatePath)) {
+        return null;
+    }
+    try {
+        const raw = JSON.parse(readFileSync(updateStatePath, 'utf-8'));
+        if (raw.packageName !== PACKAGE_NAME ||
+            typeof raw.latestVersion !== 'string' ||
+            typeof raw.lastCheckedAt !== 'string') {
+            return null;
+        }
+        return {
+            packageName: raw.packageName,
+            latestVersion: raw.latestVersion,
+            lastCheckedAt: raw.lastCheckedAt,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function writeUpdateState(state) {
+    const solverDir = getSolverDir();
+    mkdirSync(solverDir, { recursive: true });
+    writeFileSync(getUpdateStatePath(), JSON.stringify(state, null, 2) + '\n', 'utf-8');
+}
+function isCacheStale(lastCheckedAt, now, ttlMs) {
+    const lastCheckedAtMs = new Date(lastCheckedAt).getTime();
+    if (!Number.isFinite(lastCheckedAtMs)) {
+        return true;
+    }
+    return now.getTime() - lastCheckedAtMs >= ttlMs;
+}
+async function fetchLatestVersion(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        throw new Error('Global fetch is not available.');
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+    try {
+        const response = await fetchImpl(REGISTRY_METADATA_URL, {
+            headers: {
+                Accept: 'application/json',
+            },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`Registry responded with ${response.status}.`);
+        }
+        const metadata = (await response.json());
+        const latestVersion = metadata['dist-tags']?.latest;
+        if (!latestVersion || typeof latestVersion !== 'string') {
+            throw new Error('Registry metadata does not include dist-tags.latest.');
+        }
+        return latestVersion;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function getUpdateStatePath() {
+    return join(getSolverDir(), 'update-state.json');
+}

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

@@ -0,0 +1,30 @@
+import type { StoredSecretFieldKey } from './secrets/types.js';
+export interface CachedTransientSecretEntry {
+    requestId: string;
+    fillRef: string;
+    storedSecretRef: string;
+    cachedAt: string;
+    approvedAt?: string;
+    expiresAt?: string;
+    values: Partial<Record<StoredSecretFieldKey, string>>;
+}
+export interface BrowseWorkflowContext {
+    browserSessionId?: string;
+    activeRunId?: string;
+    intentSessionId?: string;
+    currentRequestId?: string;
+    lastKnownStatus?: string;
+    lastEventSeq?: number;
+    transientSecretCache?: Record<string, CachedTransientSecretEntry>;
+}
+export declare function cleanupTransientSecretCache(session: BrowseWorkflowContext, options?: {
+    now?: string;
+}): boolean;
+export declare function cacheTransientSecret(session: BrowseWorkflowContext, entry: CachedTransientSecretEntry): CachedTransientSecretEntry;
+export declare function getCachedTransientSecret(session: BrowseWorkflowContext, requestId: string, options?: {
+    now?: string;
+}): CachedTransientSecretEntry | null;
+export declare function deleteCachedTransientSecret(session: BrowseWorkflowContext, requestId: string): boolean;
+export declare function buildWorkflowContextForPersistence(session: BrowseWorkflowContext, resolvedBrowserSessionId: string): BrowseWorkflowContext | null;
+export declare function canHydrateWorkflowContext(resolvedBrowserSessionId: string, workflowContext: BrowseWorkflowContext): boolean;
+//# sourceMappingURL=workflow-session-state.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-session-state.d.ts","sourceRoot":"","sources":["../src/workflow-session-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;CACnE;AAUD,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7B,OAAO,CAqBT;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,EAC9B,KAAK,EAAE,0BAA0B,GAChC,0BAA0B,CAQ5B;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7B,0BAA0B,GAAG,IAAI,CAMnC;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,MAAM,GAChB,OAAO,CAWT;AAED,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,qBAAqB,EAC9B,wBAAwB,EAAE,MAAM,GAC/B,qBAAqB,GAAG,IAAI,CAmB9B;AAED,wBAAgB,yBAAyB,CACvC,wBAAwB,EAAE,MAAM,EAChC,eAAe,EAAE,qBAAqB,GACrC,OAAO,CAKT"}

package/dist/workflow-session-state.js

@@ -0,0 +1,74 @@
+function isExpired(expiresAt, now) {
+    if (!expiresAt) {
+        return false;
+    }
+    return new Date(expiresAt).getTime() <= new Date(now).getTime();
+}
+export function cleanupTransientSecretCache(session, options = {}) {
+    const cache = session.transientSecretCache;
+    if (!cache) {
+        return false;
+    }
+    const now = options.now ?? new Date().toISOString();
+    let changed = false;
+    for (const [requestId, entry] of Object.entries(cache)) {
+        if (isExpired(entry.expiresAt, now)) {
+            delete cache[requestId];
+            changed = true;
+        }
+    }
+    if (Object.keys(cache).length === 0) {
+        delete session.transientSecretCache;
+        changed = true;
+    }
+    return changed;
+}
+export function cacheTransientSecret(session, entry) {
+    cleanupTransientSecretCache(session);
+    const cache = (session.transientSecretCache ??= {});
+    cache[entry.requestId] = {
+        ...entry,
+        values: { ...entry.values },
+    };
+    return cache[entry.requestId];
+}
+export function getCachedTransientSecret(session, requestId, options = {}) {
+    if (cleanupTransientSecretCache(session, options)) {
+        // Keep the in-memory workflow context sanitized for callers that save immediately after load.
+    }
+    return session.transientSecretCache?.[requestId] ?? null;
+}
+export function deleteCachedTransientSecret(session, requestId) {
+    const cache = session.transientSecretCache;
+    if (!cache?.[requestId]) {
+        return false;
+    }
+    delete cache[requestId];
+    if (Object.keys(cache).length === 0) {
+        delete session.transientSecretCache;
+    }
+    return true;
+}
+export function buildWorkflowContextForPersistence(session, resolvedBrowserSessionId) {
+    const workflowContext = {
+        ...((session.activeRunId ||
+            session.intentSessionId ||
+            session.currentRequestId ||
+            session.lastKnownStatus ||
+            session.transientSecretCache) &&
+            resolvedBrowserSessionId
+            ? { browserSessionId: resolvedBrowserSessionId }
+            : {}),
+        ...(session.activeRunId ? { activeRunId: session.activeRunId } : {}),
+        ...(session.intentSessionId ? { intentSessionId: session.intentSessionId } : {}),
+        ...(session.currentRequestId ? { currentRequestId: session.currentRequestId } : {}),
+        ...(session.lastKnownStatus ? { lastKnownStatus: session.lastKnownStatus } : {}),
+        ...(typeof session.lastEventSeq === 'number' ? { lastEventSeq: session.lastEventSeq } : {}),
+        ...(session.transientSecretCache ? { transientSecretCache: session.transientSecretCache } : {}),
+    };
+    return Object.keys(workflowContext).length > 0 ? workflowContext : null;
+}
+export function canHydrateWorkflowContext(resolvedBrowserSessionId, workflowContext) {
+    return (!workflowContext.browserSessionId ||
+        workflowContext.browserSessionId === resolvedBrowserSessionId);
+}

package/docs/README.md

@@ -0,0 +1,25 @@
+# AgentBrowse Docs
+
+Public guides for `@mercuryo-ai/agentbrowse`.
+
+Start here:
+
+- [getting-started.md](./getting-started.md)
+  The first guide to read after the package README. It explains the normal
+  session flow and what each main API is for.
+- [api-reference.md](./api-reference.md)
+  Compact reference for the public API, result shapes, observe payloads, and
+  extraction schema input.
+- [configuration.md](./configuration.md)
+  Persistence, proxy, diagnostics, and client configuration.
+- [assistive-runtime.md](./assistive-runtime.md)
+  How to connect an OpenAI-compatible LLM backend for extraction and better
+  goal-based page understanding.
+- [protected-fill.md](./protected-fill.md)
+  How protected fill works and when to use it instead of a normal fill action.
+- [integration-checklist.md](./integration-checklist.md)
+  Current contract checklist for packages and services that integrate AgentBrowse.
+- [testing.md](./testing.md)
+  Stable testing helpers for packages that wrap AgentBrowse.
+- [troubleshooting.md](./troubleshooting.md)
+  Common launch, observe, extract, and anti-bot issues.

package/docs/api-reference.md

@@ -0,0 +1,242 @@
+# AgentBrowse API Reference
+
+This page is the compact reference for the public `@mercuryo-ai/agentbrowse`
+library surface.
+
+## Main Functions
+
+### `launch(url?, options?)`
+
+Starts a managed browser session.
+
+Success result includes:
+
+- `session`
+- `url`
+- `title`
+
+### `attach(cdpUrl, options?)`
+
+Attaches to an existing browser over CDP.
+
+Success result includes:
+
+- `session`
+- `url`
+- `title`
+
+### `observe(session, goal?)`
+
+Inspects the current page and returns the current page inventory.
+
+Success result includes:
+
+- `targets: ObserveTarget[]`
+- `scopes: ObserveScope[]`
+- `signals: ObserveSignal[]`
+- `fillableForms: ObserveFillableForm[]`
+- `observationMode`
+- `targetCount`
+- `scopeCount`
+- `projectedTargetCount`
+- `pageRef`
+- `url`
+- `title`
+
+### `act(session, targetRef, action, value?)`
+
+Runs a deterministic browser action against a previously observed target.
+
+### `extract(session, schema, scopeRef?)`
+
+Extracts structured data from the current page or a previously observed scope.
+
+`schema` accepts either:
+
+- a plain schema object
+- a Zod schema
+
+Plain schema example:
+
+```ts
+const result = await extract(session, {
+  total: 'number',
+  currency: 'string',
+  flights: [{ code: 'string', fare: 'string' }],
+});
+```
+
+Zod example:
+
+```ts
+const result = await extract(
+  session,
+  z.object({
+    total: z.number(),
+    currency: z.string(),
+  })
+);
+```
+
+### `navigate(session, url)`
+
+Navigates the current page.
+
+### `status(session)`
+
+Returns current liveness and runtime summary information.
+
+The root package also exports `BROWSER_STATUS_OUTCOME_TYPES` for the stable
+outcome categories used by `status(session)`.
+
+### `screenshot(session, path?)`
+
+Captures a screenshot of the current page.
+
+### `close(session)`
+
+Closes the browser session.
+
+## Stable Error Code Arrays
+
+The root package exports stable top-level error code arrays for command
+branching:
+
+- `ACT_ERROR_CODES`
+- `ATTACH_ERROR_CODES`
+- `CLOSE_ERROR_CODES`
+- `EXTRACT_ERROR_CODES`
+- `LAUNCH_ERROR_CODES`
+- `NAVIGATE_ERROR_CODES`
+- `OBSERVE_ERROR_CODES`
+- `SCREENSHOT_ERROR_CODES`
+
+These arrays back the exported `*ErrorCode` types.
+
+## Core Result Shapes
+
+All main commands use the same top-level pattern:
+
+- success: `{ success: true, ... }`
+- failure: `{ success: false, error, outcomeType, message, reason, ... }`
+
+## Observe Types
+
+### `ObserveTarget`
+
+Fields most applications use directly:
+
+- `ref`
+- `label`
+- `kind`
+- `capability`
+- `availability`
+- `surfaceRef`
+
+Additional fields are available for richer UI or routing:
+
+- `displayLabel`
+- `placeholder`
+- `inputName`
+- `inputType`
+- `autocomplete`
+- `validation`
+- `context`
+- `state`
+- `structure`
+- `availabilityReason`
+- `source`
+
+### `ObserveScope`
+
+Represents a scope or container on the page.
+
+Fields:
+
+- `ref`
+- `kind`
+- `label`
+- `parentSurfaceRef`
+- `childSurfaceRefs`
+- `extractScopeLifetime`
+- `targets`
+- `source`
+
+### `ObserveFillableForm`
+
+Represents a form that can be passed into protected fill.
+
+Fields:
+
+- `fillRef`
+- `scopeRef`
+- `purpose`
+- `presence`
+- `fields`
+- `storedSecretCandidates`
+
+### `ObserveSignal`
+
+Represents page-level signals such as notices, status text, or confirmation
+messages.
+
+Fields:
+
+- `kind`
+- `text`
+- `framePath`
+- `source`
+
+## Ref Glossary
+
+- `ref`
+  A stable target or scope reference returned by `observe(...)`.
+- `scopeRef`
+  A scope reference used for scoped extraction or protected-fill bindings.
+- `fillRef`
+  A stable protected-fill binding reference returned inside `fillableForms`.
+- `pageRef`
+  AgentBrowse's current page identity inside the session runtime.
+
+## Extraction Schema Rules
+
+Plain schema objects use a small descriptor language:
+
+- `'string'`
+- `'number'`
+- `'boolean'`
+- nested objects
+- arrays with one schema element, for example `[{ label: 'string' }]`
+
+The extractor uses only the schema you provide. It does not invent missing
+fields and does not treat the schema stringification format as part of the API.
+
+## Assistive Runtime Types
+
+The root package exports the current assistive runtime contract:
+
+- `AgentbrowseAssistiveChatCompletionRequest`
+- `AgentbrowseAssistiveChatCompletionOptions`
+- `AgentbrowseAssistiveChatCompletionResult`
+- `AgentbrowseAssistiveChatMessage`
+- `AgentbrowseAssistiveImageInput`
+- `AgentbrowseAssistiveResponseModel`
+- `AgentbrowseAssistiveLlmUsage`
+
+Your adapter receives `args.options.messages`, optional
+`args.options.response_model`, optional `args.options.image`, and optional
+`temperature` / `maxOutputTokens`.
+
+## Testing Subpath
+
+The package publishes a dedicated testing surface:
+
+```ts
+import {
+  installFetchBackedTestAssistiveRuntime,
+  uninstallTestAssistiveRuntime,
+} from '@mercuryo-ai/agentbrowse/testing';
+```
+
+Use it when a package wraps AgentBrowse and needs a stable fetch-backed
+assistive runtime in tests.

package/docs/assistive-runtime.md

@@ -0,0 +1,148 @@
+# AgentBrowse Assistive Runtime Guide
+
+This guide explains when you need an assistive runtime and how to connect one.
+
+## What "Assistive" Means
+
+AgentBrowse has two broad kinds of behavior:
+
+- browser-only behavior, which does not call an LLM
+- assistive behavior, which can call an LLM to better understand the page or
+  produce structured output
+
+Today, assistive behavior matters mainly for:
+
+- `extract(session, schema, scopeRef?)`
+- higher-quality goal-based `observe(session, goal)`
+
+If you only need browser actions and normal page inspection, you can ignore
+assistive runtime completely.
+
+## The Runtime Contract
+
+AgentBrowse does not ship a built-in OpenAI or OpenRouter adapter.
+
+Instead, you provide a small runtime object with one responsibility:
+create a chat-completions client.
+
+The shape is:
+
+```ts
+{
+  createLlmClient: () => ({
+    async createChatCompletion(args) {
+      const { messages, response_model, image, temperature, maxOutputTokens } = args.options;
+      // map these values to your provider here
+    }
+  })
+}
+```
+
+That means any OpenAI-compatible chat-completions backend can work, as long as
+your adapter returns the expected response shape.
+
+## Recommended Setup
+
+```ts
+import { createAgentbrowseClient } from '@mercuryo-ai/agentbrowse';
+
+const client = createAgentbrowseClient({
+  assistiveRuntime: {
+    createLlmClient: () => ({
+      async createChatCompletion(args) {
+        const { messages, response_model, image, temperature, maxOutputTokens } = args.options;
+
+        const json = await callStructuredProvider({
+          messages,
+          responseModel: response_model,
+          image,
+          temperature,
+          maxOutputTokens,
+        });
+
+        return {
+          data: json.data,
+          usage: json.usage,
+        };
+      },
+    }),
+  },
+});
+```
+
+This pattern works well when:
+
+- your app is multi-tenant
+- you run parallel tests
+- different consumers in one process need different LLM settings
+
+## OpenAI-Compatible Helper Example
+
+You can wrap the adapter once and reuse it:
+
+```ts
+function createOpenAiCompatibleAssistiveRuntime(input: {
+  baseUrl: string;
+  apiKey: string;
+}) {
+  return {
+    createLlmClient: () => ({
+      async createChatCompletion(args) {
+        const { messages, response_model, image, temperature, maxOutputTokens } = args.options;
+
+        const json = await callStructuredProvider({
+          baseUrl: input.baseUrl,
+          apiKey: input.apiKey,
+          messages,
+          responseModel: response_model,
+          image,
+          temperature,
+          maxOutputTokens,
+        });
+
+        return {
+          data: json.data,
+          usage: json.usage,
+        };
+      },
+    }),
+  };
+}
+```
+
+Examples:
+
+- OpenAI base URL:
+  `https://api.openai.com/v1`
+- OpenRouter base URL:
+  `https://openrouter.ai/api/v1`
+
+## Small Script Fallback
+
+For small scripts, you can also use:
+
+```ts
+import { configureAgentbrowseAssistiveRuntime } from '@mercuryo-ai/agentbrowse';
+```
+
+This is a convenience fallback, not the preferred embedded pattern.
+
+## What Happens Without Assistive Runtime
+
+- `extract(...)` cannot run successfully
+- `observe(session, goal)` still runs, but quality may be lower because
+  AgentBrowse falls back to local heuristics instead of LLM-assisted ranking
+
+## Testing Runtime
+
+For test suites that wrap AgentBrowse, use the dedicated testing subpath:
+
+```ts
+import {
+  installFetchBackedTestAssistiveRuntime,
+  uninstallTestAssistiveRuntime,
+} from '@mercuryo-ai/agentbrowse/testing';
+```
+
+That helper installs a fetch-backed runtime with the same public assistive
+runtime contract used by the main package.