@mercuryo-ai/agentbrowse 0.2.57 → 0.2.61

package/dist/sticky-owner.js

@@ -0,0 +1,431 @@
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { chromium } from 'playwright-core';
+import { buildStickyOwnerMetadata, isSessionAlive, resolveBrowserSessionId, } from './browser-session-state.js';
+import { connectPlaywright, disconnectPlaywright } from './playwright-runtime.js';
+const HOST_READY_TIMEOUT_MS = 5_000;
+const HOST_READY_POLL_MS = 50;
+const HOST_CONNECT_TIMEOUT_MS = 3_000;
+const HOST_STOP_TIMEOUT_MS = 1_000;
+const DEFAULT_STICKY_OWNER_TTL_MS = 30 * 60 * 1_000;
+const STICKY_OWNER_HEARTBEAT_FLOOR_MS = 5_000;
+const STICKY_OWNER_HEARTBEAT_CEILING_MS = 60_000;
+const inProcessOwners = new WeakMap();
+function resolveStickyOwnerBootstrapMode() {
+    const explicit = process.env.AGENTBROWSE_STICKY_OWNER_MODE?.trim().toLowerCase();
+    if (explicit === 'detached_process') {
+        return 'detached_process';
+    }
+    if (explicit === 'in_process') {
+        return 'in_process';
+    }
+    if (process.env.VITEST) {
+        return 'in_process';
+    }
+    return 'detached_process';
+}
+function createHostId() {
+    return `owner_${randomUUID().replace(/-/g, '')}`;
+}
+function resolveStickyOwnerTtlMs() {
+    const raw = process.env.AGENTBROWSE_STICKY_OWNER_TTL_MS?.trim();
+    if (!raw) {
+        return DEFAULT_STICKY_OWNER_TTL_MS;
+    }
+    const ttlMs = Number(raw);
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+        return DEFAULT_STICKY_OWNER_TTL_MS;
+    }
+    return ttlMs;
+}
+function getStickyOwnerTouchPath(hostId) {
+    return join(tmpdir(), `agentbrowse-sticky-owner-${hostId}.touch`);
+}
+function buildInProcessStickyOwner(session, options = {}) {
+    return buildStickyOwnerMetadata({
+        hostId: options.hostId ?? session.stickyOwner?.hostId ?? createHostId(),
+        state: options.state ?? 'active',
+        startedAt: options.startedAt ?? session.stickyOwner?.startedAt ?? new Date().toISOString(),
+        browserSessionId: resolveBrowserSessionId(session),
+        transport: {
+            type: 'in_process',
+        },
+    });
+}
+function readStickyOwnerLastUsedMs(stickyOwner) {
+    if (stickyOwner.touchPath) {
+        try {
+            if (existsSync(stickyOwner.touchPath)) {
+                return statSync(stickyOwner.touchPath).mtimeMs;
+            }
+        }
+        catch {
+            // Fall through to metadata timestamps.
+        }
+    }
+    const candidate = stickyOwner.lastUsedAt ?? stickyOwner.startedAt;
+    const parsed = Date.parse(candidate);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function isStickyOwnerExpired(stickyOwner) {
+    if (stickyOwner.transport.type !== 'playwright_bind') {
+        return false;
+    }
+    const ttlMs = stickyOwner.ttlMs ?? DEFAULT_STICKY_OWNER_TTL_MS;
+    return Date.now() - readStickyOwnerLastUsedMs(stickyOwner) >= ttlMs;
+}
+function removeStickyOwnerTouchFile(stickyOwner) {
+    if (!stickyOwner?.touchPath) {
+        return;
+    }
+    rmSync(stickyOwner.touchPath, { force: true });
+}
+function touchStickyOwnerLease(session) {
+    if (!session.stickyOwner || session.stickyOwner.transport.type !== 'playwright_bind') {
+        return;
+    }
+    const touchedAt = new Date().toISOString();
+    if (session.stickyOwner.touchPath) {
+        writeFileSync(session.stickyOwner.touchPath, touchedAt);
+    }
+    session.stickyOwner = {
+        ...session.stickyOwner,
+        lastUsedAt: touchedAt,
+    };
+}
+function startStickyOwnerLeaseHeartbeat(session) {
+    if (!session.stickyOwner || session.stickyOwner.transport.type !== 'playwright_bind') {
+        return () => undefined;
+    }
+    const ttlMs = session.stickyOwner.ttlMs ?? DEFAULT_STICKY_OWNER_TTL_MS;
+    const heartbeatMs = Math.max(STICKY_OWNER_HEARTBEAT_FLOOR_MS, Math.min(Math.floor(ttlMs / 3), STICKY_OWNER_HEARTBEAT_CEILING_MS));
+    const timer = setInterval(() => {
+        try {
+            touchStickyOwnerLease(session);
+        }
+        catch {
+            // Best-effort heartbeat; restore path will handle stale or dead owners later.
+        }
+    }, heartbeatMs);
+    timer.unref?.();
+    return () => clearInterval(timer);
+}
+function markStickyOwnerState(session, state) {
+    if (!session.stickyOwner) {
+        return;
+    }
+    session.stickyOwner = {
+        ...session.stickyOwner,
+        state,
+    };
+}
+function isProcessAlive(pid) {
+    if (typeof pid !== 'number' || !Number.isFinite(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForProcessExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isProcessAlive(pid)) {
+            return true;
+        }
+        await sleep(50);
+    }
+    return !isProcessAlive(pid);
+}
+async function canConnectToStickyOwnerEndpoint(endpoint) {
+    let browser = null;
+    try {
+        browser = await chromium.connect(endpoint, {
+            timeout: HOST_CONNECT_TIMEOUT_MS,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (browser) {
+            await disconnectPlaywright(browser);
+        }
+    }
+}
+function getStickyOwnerHostEntryPath() {
+    const currentPath = fileURLToPath(import.meta.url);
+    const suffix = currentPath.endsWith('.ts') ? '.ts' : '.js';
+    return fileURLToPath(new URL(`./sticky-owner-host-entry${suffix}`, import.meta.url));
+}
+function getStickyOwnerHostSpawnArgs(entryPath, manifestPath, cdpUrl, hostId, browserSessionId, touchPath, ttlMs) {
+    const args = [
+        entryPath,
+        '--manifest',
+        manifestPath,
+        '--cdp-url',
+        cdpUrl,
+        '--host-id',
+        hostId,
+        '--browser-session-id',
+        browserSessionId,
+        '--touch-path',
+        touchPath,
+        '--ttl-ms',
+        String(ttlMs),
+    ];
+    if (entryPath.endsWith('.ts')) {
+        return ['--import', 'tsx', ...args];
+    }
+    return args;
+}
+async function waitForStickyOwnerManifest(manifestPath) {
+    const deadline = Date.now() + HOST_READY_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (existsSync(manifestPath)) {
+            const payload = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+            if (typeof payload.endpoint === 'string' &&
+                payload.endpoint.trim().length > 0 &&
+                typeof payload.pid === 'number' &&
+                Number.isFinite(payload.pid) &&
+                payload.pid > 0 &&
+                typeof payload.startedAt === 'string' &&
+                payload.startedAt.trim().length > 0) {
+                rmSync(manifestPath, { force: true });
+                return {
+                    endpoint: payload.endpoint,
+                    pid: payload.pid,
+                    startedAt: payload.startedAt,
+                };
+            }
+        }
+        await sleep(HOST_READY_POLL_MS);
+    }
+    throw new Error('sticky_owner_bootstrap_timeout');
+}
+async function bootstrapDetachedStickyOwner(session) {
+    const hostId = session.stickyOwner?.hostId ?? createHostId();
+    const browserSessionId = resolveBrowserSessionId(session);
+    const ttlMs = session.stickyOwner?.ttlMs ?? resolveStickyOwnerTtlMs();
+    const manifestPath = join(tmpdir(), `agentbrowse-sticky-owner-${hostId}.json`);
+    const touchPath = session.stickyOwner?.touchPath ?? getStickyOwnerTouchPath(hostId);
+    const touchedAt = new Date().toISOString();
+    writeFileSync(touchPath, touchedAt);
+    const entryPath = getStickyOwnerHostEntryPath();
+    const child = spawn(process.execPath, getStickyOwnerHostSpawnArgs(entryPath, manifestPath, session.cdpUrl, hostId, browserSessionId, touchPath, ttlMs), {
+        detached: true,
+        stdio: 'ignore',
+    });
+    child.unref();
+    try {
+        const ready = await waitForStickyOwnerManifest(manifestPath);
+        return buildStickyOwnerMetadata({
+            hostId,
+            state: 'active',
+            startedAt: ready.startedAt,
+            lastUsedAt: touchedAt,
+            ttlMs,
+            touchPath,
+            browserSessionId,
+            pid: ready.pid,
+            transport: {
+                type: 'playwright_bind',
+                endpoint: ready.endpoint,
+                mode: 'pipe',
+            },
+        });
+    }
+    catch (error) {
+        if (isProcessAlive(child.pid)) {
+            process.kill(child.pid, 'SIGTERM');
+            await waitForProcessExit(child.pid, HOST_STOP_TIMEOUT_MS).catch(() => undefined);
+        }
+        rmSync(manifestPath, { force: true });
+        rmSync(touchPath, { force: true });
+        throw error;
+    }
+}
+async function ensureInProcessOwner(session) {
+    const existing = inProcessOwners.get(session);
+    if (existing) {
+        return existing;
+    }
+    const browser = await connectPlaywright(session.cdpUrl);
+    const owner = {
+        browser,
+        hostId: session.stickyOwner?.hostId ?? createHostId(),
+        startedAt: session.stickyOwner?.startedAt ?? new Date().toISOString(),
+    };
+    inProcessOwners.set(session, owner);
+    session.stickyOwner = buildInProcessStickyOwner(session, {
+        hostId: owner.hostId,
+        startedAt: owner.startedAt,
+    });
+    return owner;
+}
+export async function initializeBrowserSessionOwner(session) {
+    if (resolveStickyOwnerBootstrapMode() === 'in_process') {
+        session.stickyOwner = buildInProcessStickyOwner(session, {
+            state: 'active',
+        });
+        return session;
+    }
+    session.stickyOwner = await bootstrapDetachedStickyOwner(session);
+    return session;
+}
+export async function terminateBrowserSessionOwner(session) {
+    if (!session?.stickyOwner) {
+        return;
+    }
+    if (session.stickyOwner.transport.type === 'in_process') {
+        const owner = inProcessOwners.get(session);
+        inProcessOwners.delete(session);
+        if (owner) {
+            await disconnectPlaywright(owner.browser);
+        }
+        markStickyOwnerState(session, 'dead');
+        return;
+    }
+    const ownerPid = session.stickyOwner.pid;
+    if (isProcessAlive(ownerPid)) {
+        process.kill(ownerPid, 'SIGTERM');
+        const exited = await waitForProcessExit(ownerPid, HOST_STOP_TIMEOUT_MS);
+        if (!exited && isProcessAlive(ownerPid)) {
+            process.kill(ownerPid, 'SIGKILL');
+            await waitForProcessExit(ownerPid, HOST_STOP_TIMEOUT_MS).catch(() => undefined);
+        }
+    }
+    removeStickyOwnerTouchFile(session.stickyOwner);
+    markStickyOwnerState(session, 'dead');
+}
+export async function restoreBrowserSessionOwner(session) {
+    const stickyOwner = session.stickyOwner;
+    if (!stickyOwner) {
+        if (resolveStickyOwnerBootstrapMode() === 'in_process') {
+            try {
+                await ensureInProcessOwner(session);
+                return {
+                    success: true,
+                    session,
+                    restored: true,
+                };
+            }
+            catch {
+                return {
+                    success: false,
+                    reason: 'sticky_owner_unrecoverable',
+                };
+            }
+        }
+        if (!(await isSessionAlive(session))) {
+            return {
+                success: false,
+                reason: 'sticky_owner_unrecoverable',
+            };
+        }
+        try {
+            session.stickyOwner = await bootstrapDetachedStickyOwner(session);
+            return {
+                success: true,
+                session,
+                restored: true,
+            };
+        }
+        catch {
+            return {
+                success: false,
+                reason: 'sticky_owner_unrecoverable',
+            };
+        }
+    }
+    if (stickyOwner.transport.type === 'in_process') {
+        try {
+            await ensureInProcessOwner(session);
+            return {
+                success: true,
+                session,
+                restored: false,
+            };
+        }
+        catch {
+            return {
+                success: false,
+                reason: 'sticky_owner_unrecoverable',
+            };
+        }
+    }
+    if (stickyOwner.state === 'active' &&
+        !isStickyOwnerExpired(stickyOwner) &&
+        isProcessAlive(stickyOwner.pid) &&
+        (await canConnectToStickyOwnerEndpoint(stickyOwner.transport.endpoint))) {
+        return {
+            success: true,
+            session,
+            restored: false,
+        };
+    }
+    await terminateBrowserSessionOwner(session);
+    if (!(await isSessionAlive(session))) {
+        return {
+            success: false,
+            reason: 'sticky_owner_unrecoverable',
+        };
+    }
+    try {
+        markStickyOwnerState(session, 'recovering');
+        session.stickyOwner = await bootstrapDetachedStickyOwner(session);
+        return {
+            success: true,
+            session,
+            restored: true,
+        };
+    }
+    catch {
+        session.stickyOwner = {
+            ...stickyOwner,
+            state: 'dead',
+        };
+        return {
+            success: false,
+            reason: 'sticky_owner_unrecoverable',
+        };
+    }
+}
+export async function withStickyOwnerBrowser(session, operation) {
+    const stickyOwner = session.stickyOwner;
+    if (!stickyOwner || stickyOwner.transport.type === 'playwright_bind') {
+        const restored = await restoreBrowserSessionOwner(session);
+        if (!restored.success || !session.stickyOwner) {
+            throw new Error('sticky_owner_unrecoverable');
+        }
+    }
+    if (session.stickyOwner?.transport.type === 'playwright_bind') {
+        touchStickyOwnerLease(session);
+        const browser = await chromium.connect(session.stickyOwner.transport.endpoint, {
+            timeout: HOST_CONNECT_TIMEOUT_MS,
+        });
+        const stopHeartbeat = startStickyOwnerLeaseHeartbeat(session);
+        try {
+            return await operation(browser);
+        }
+        finally {
+            stopHeartbeat();
+            touchStickyOwnerLease(session);
+            await disconnectPlaywright(browser);
+        }
+    }
+    const owner = await ensureInProcessOwner(session);
+    return operation(owner.browser);
+}

package/docs/README.md

@@ -2,7 +2,20 @@
 
 Public guides for `@mercuryo-ai/agentbrowse`.
 
-Start here:
+**Reading order for a new integration:**
+
+1. [Package README](../README.md) — 5-minute overview and Quick Start.
+2. [getting-started.md](./getting-started.md) — extended tutorial that
+   turns the Quick Start into a working model for every main API.
+3. [api-reference.md](./api-reference.md) — lookup for types, result
+   shapes, and error codes (keep open while coding).
+4. Only-when-needed: [configuration.md](./configuration.md),
+   [assistive-runtime.md](./assistive-runtime.md),
+   [protected-fill.md](./protected-fill.md).
+5. Before shipping: [integration-checklist.md](./integration-checklist.md)
+   and [troubleshooting.md](./troubleshooting.md).
+
+Full list:
 
 - [getting-started.md](./getting-started.md)
   The first guide to read after the package README. It explains the normal
@@ -18,7 +31,7 @@ Start here:
 - [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.
+  Checklist for packages and services that integrate AgentBrowse.
 - [testing.md](./testing.md)
   Stable testing helpers for packages that wrap AgentBrowse.
 - [troubleshooting.md](./troubleshooting.md)

package/docs/api-reference.md

@@ -1,7 +1,7 @@
 # AgentBrowse API Reference
 
 This page is the compact reference for the public `@mercuryo-ai/agentbrowse`
-library surface.
+library API.
 
 ## Main Functions
 
@@ -113,6 +113,16 @@ branching:
 
 These arrays back the exported `*ErrorCode` types.
 
+## Error Classes
+
+For code paths that want `instanceof` checks instead of string matching on
+`error` codes:
+
+- `AgentbrowseAssistiveRuntimeMissingError` — thrown when an assistive-only
+  command runs without an assistive runtime configured.
+- `AssistiveStructuredOutputTruncatedError` — thrown when the assistive
+  runtime returns a structured output that was cut off mid-response.
+
 ## Core Result Shapes
 
 All main commands use the same top-level pattern:
@@ -213,7 +223,7 @@ 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:
+The root package exports the types that describe the assistive runtime:
 
 - `AgentbrowseAssistiveChatCompletionRequest`
 - `AgentbrowseAssistiveChatCompletionOptions`
@@ -229,7 +239,7 @@ Your adapter receives `args.options.messages`, optional
 
 ## Testing Subpath
 
-The package publishes a dedicated testing surface:
+The package publishes a dedicated `/testing` subpath:
 
 ```ts
 import {

package/docs/assistive-runtime.md

@@ -18,15 +18,13 @@ Today, assistive behavior matters mainly for:
 If you only need browser actions and normal page inspection, you can ignore
 assistive runtime completely.
 
-## The Runtime Contract
+## The Runtime Shape
 
 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: () => ({
@@ -38,8 +36,66 @@ The shape is:
 }
 ```
 
-That means any OpenAI-compatible chat-completions backend can work, as long as
-your adapter returns the expected response shape.
+Any OpenAI-compatible chat-completions backend can work, as long as your
+adapter returns the expected response shape.
+
+### `options.response_model`
+
+When AgentBrowse needs structured JSON (from `extract(...)` or certain
+goal-driven `observe(...)` paths), it passes `response_model` describing
+the expected output:
+
+```ts
+{
+  name: string;        // short identifier for the schema (e.g. "checkout_total")
+  schema: ZodType;     // a Zod schema AgentBrowse wants the LLM to conform to
+}
+```
+
+Your adapter is responsible for translating `response_model.schema` into
+whatever structured-output mechanism your provider supports. For OpenAI,
+this usually means:
+
+1. Convert the Zod schema to JSON Schema (e.g. with
+   `@browserbasehq/stagehand`'s `toJsonSchema`, or your own helper).
+2. Pass it as `response_format: { type: 'json_schema', json_schema: { ... } }`.
+3. Parse `choices[0].message.content` and return `{ data, usage? }`.
+
+If your provider does not support structured outputs, you can prompt the
+model to return JSON and parse the result yourself — as long as the
+returned `data` conforms to the schema, AgentBrowse does not care how it
+was produced.
+
+### `options.image`
+
+For vision-assisted extraction, AgentBrowse passes a screenshot:
+
+```ts
+{
+  buffer: Buffer;             // raw image bytes
+  description?: string;        // short hint about what's in the image
+}
+```
+
+Most adapters encode the buffer as a base64 data URL and inject it as a
+user-turn content block. See the helper below.
+
+### Errors
+
+Your adapter throws on provider errors; AgentBrowse maps them to typed
+failures on the calling command:
+
+- HTTP errors (401/403/429/5xx): throw a normal `Error` with a descriptive
+  message. AgentBrowse surfaces it as a command failure.
+- Missing/empty content: throw; do not return `{ data: null }`.
+- Truncated structured output: AgentBrowse detects this and throws
+  `AssistiveStructuredOutputTruncatedError` — usually a signal to raise
+  `maxOutputTokens`.
+
+The `AgentbrowseAssistiveLlmClient` type exported from the root package
+describes the client object returned by `createLlmClient()`. Use it when you
+want your adapter to conform to the expected shape without redefining it
+by hand.
 
 ## Recommended Setup
 
@@ -203,5 +259,5 @@ import {
 } from '@mercuryo-ai/agentbrowse/testing';
 ```
 
-That helper installs a fetch-backed runtime with the same public assistive
-runtime contract used by the main package.
+That helper installs a fetch-backed runtime with the same public
+assistive-runtime shape used by the main package.

package/docs/configuration.md

@@ -15,6 +15,12 @@ Most applications can start with this mental model:
 2. keep the returned `session` in memory
 3. pass that `session` into later calls
 
+Both bootstrap the same sticky-owner lifecycle. AgentBrowse may keep that
+owner in-process or in an internal detached host, but consumers do not manage
+that host directly. Detached hosts default to a 30 minute TTL and may be
+recreated on the next browser command if the browser session itself is still
+alive.
+
 You only need more configuration when you want one of these:
 
 - custom LLM integration
@@ -40,8 +46,12 @@ const attached = await attach(remoteCdpUrl, {
 });
 ```
 
-That provider label is metadata only. AgentBrowse still treats this as a
-generic CDP-attached browser session.
+The provider label is metadata only — AgentBrowse treats the connection as
+a generic CDP-attached browser session regardless of the label.
+
+`attach(...)` creates the same sticky-owner metadata as `launch(...)`. Later
+browser commands reuse that owner and only attempt a fresh root attach again
+as a repair path after owner loss.
 
 ## Client Configuration
 
@@ -68,19 +78,46 @@ configuration is the cleaner embedded pattern.
 Persistence is optional. Use it when you want to restore a browser session
 after a process restart.
 
+Persisted session files store browser identity plus versioned sticky-owner
+metadata. They do not serialize a live Playwright connection.
+
 ### Default Store
 
 ```ts
-import { loadBrowserSession, saveBrowserSession } from '@mercuryo-ai/agentbrowse';
+import { loadBrowserSession, saveBrowserSession, status } from '@mercuryo-ai/agentbrowse';
 
 saveBrowserSession(session);
 const restored = loadBrowserSession();
+
+// `null` means there is no usable persisted session. That includes
+// incompatible reconnect-era records and incomplete owner metadata.
+if (restored) {
+  const check = await status(restored);
+  if (!check.alive) {
+    // The session is no longer reachable. Discard and relaunch or re-attach.
+  }
+}
 ```
 
 Default path:
 
 `~/.agentbrowse/browse-session.json`
 
+If the detached owner host is gone but the underlying browser session is still
+alive, the first command after restore may repair ownership. If the browser is
+gone, AgentBrowse fails closed and you should start a fresh session.
+
+### Sticky Owner TTL
+
+Detached sticky-owner hosts use a bounded lifetime by default:
+
+- default TTL: `30` minutes
+- env override: `AGENTBROWSE_STICKY_OWNER_TTL_MS=<milliseconds>`
+
+This TTL is a resource guard for the detached owner host, not for the browser
+session itself. If the TTL expires and the browser is still reachable, the next
+browser command may bootstrap a fresh owner and continue.
+
 ### Custom Store
 
 For embedded apps, prefer an explicit store root:
@@ -99,6 +136,10 @@ store.delete();
 
 This avoids hidden machine-level coupling to `~/.agentbrowse`.
 
+`store.load()` follows the same contract as `loadBrowserSession()`: it returns
+`null` for missing files, incompatible old records, or unusable sticky-owner
+metadata.
+
 ## Proxy Configuration
 
 The clearest way to use a proxy is to pass it directly to `launch(...)`.
@@ -276,12 +317,11 @@ if your diagnostics implementation throws.
 
 ## Process-Global Convenience Helpers
 
-AgentBrowse still exposes process-global convenience functions such as:
+For small scripts and quick experiments, AgentBrowse exposes process-global
+helpers:
 
 - `configureAgentbrowseAssistiveRuntime(...)`
 - `configureAgentbrowseDiagnostics(...)`
 
-These are useful for small scripts and quick experiments.
-
-For embedded production usage, client-scoped configuration is the better
-default.
+For embedded production usage, prefer client-scoped configuration through
+`createAgentbrowseClient(...)`.