@reclaimprotocol/agent 0.1.36 → 0.1.38

package/README.md

@@ -22,12 +22,12 @@ This package **is** the Reclaim MCP server (bin: `reclaim-mcp-server`). It depen
 
 **Prerequisites:**
 
-- **Node 20 or later.** Any line works, including non-LTS ones such as 25, but a current LTS line (22 or 24) is recommended.
-- **A local Chrome, Chromium, or Edge**, used for capture and for the dashboard login.
+- **Node 22.12 or later.** Any line from there works, including non-LTS ones such as 25, but a current LTS line (22 or 24) is recommended.
+- **A local Chrome, Chromium, or Edge**, used for capture and for the dashboard login. Without one, the agent downloads Chrome for Testing once into `~/.reclaim/browsers`. On Linux the MCP server needs `DISPLAY` or `WAYLAND_DISPLAY` set, because the browser opens a visible window.
 - **Docker** — only for `attach_browser`'s `container` mode, which runs the Reclaim browser runtime (the same image the hosted browser uses) and gives you a link you can send to whoever holds the account. It is the free way to get that link; the hosted remote browser is the other, and it is chargeable. Not needed if you are doing the work yourself. The image is amd64, so Apple Silicon runs it translated. OrbStack handles that itself; Docker Desktop needs Rosetta enabled. `RECLAIM_BROWSER_RUNTIME_IMAGE` overrides the pinned digest.
 - **`cloudflared`** — only to share a `container` browser with someone remote. The MCP server does not run or install it: `share_browser_view` returns the command, and the developer chooses to run `cloudflared tunnel --url http://localhost:<port>` themselves (recommended) or approve the agent running it. Install it first.
 
-The first time you call `run_proof`, the agent downloads the ZK circuit files it needs (about 280 MB), so allow a moment for that first proof. The download is deferred to the first proof rather than run at install time, so the MCP server itself starts immediately.
+The MCP server downloads the ZK proof files it needs (about 1.5 MB) in the background when it starts, so it starts immediately and the files are usually ready by the first `run_proof`. If that download fails, it falls back to the full circuit archive (about 350 MB). `check_attestor` reports where the download stands.
 
 It runs as a **stdio MCP server**. Point any MCP-capable agent at this command:
 
@@ -89,7 +89,7 @@ Or more loosely:
 The agent orchestrates the tools for you:
 
 1. **`reclaim_authenticate`** — a local Chrome window opens the Reclaim dashboard; you sign in. The token is captured automatically and the tab closes. It never uses a Builder, container, custom-CDP, or shared browser. (Or it reuses a still-valid cached identity.)
-2. **`attach_browser` + `navigate`** — uses local Chrome, a Builder-hosted remote browser, or a custom CDP websocket; **`wait_for_page`** waits while you log in.
+2. **`attach_browser` + `navigate`** — opens a visible local browser with the persistent Reclaim profile (other modes only when you ask for them); **`wait_for_page`** waits while you log in.
 3. **`start_capture` → `find_requests_containing` → `get_request`** — records network traffic and locates the request carrying your value.
 4. **`propose_provider`** — drafts the provider (a `contains` match + `jsonPath`/`xPath`/`regex` redaction), keeping any secret headers server-side.
 5. **`replay_request` → `run_proof`** — pre-flights the draft, then produces a verified zkTLS proof via the attestor.
@@ -107,7 +107,7 @@ These capture/synthesis/proof tools are backend-independent and registered in bo
 
 | Tool                                        | Purpose                                                                                                        |
 | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `attach_browser`                            | Connect to a browser. Grouped by use case: working alone → local Chrome (launched, or the one already open); someone else has to sign in → the Reclaim runtime in Docker (free) or a hosted remote browser (chargeable). The tool description asks which case applies before listing anything, so an agent can put the choice to the developer and connect in one call |
+| `attach_browser`                            | Connect to a browser. With no arguments it launches a visible local browser (Chrome, then Chromium, then Edge, else a one-time Chrome for Testing download) with the persistent Reclaim profile, without asking. `attach` (your open Chrome), `container` (Docker), `builder` (hosted, chargeable), and `custom` (a CDP websocket) are used only when you ask for them |
 | `list_tabs`                                 | List open Chrome tabs                                                                                          |
 | `navigate`, `wait_for_page`, `eval_in_page` | Drive the tab; poll for login completion                                                                       |
 | `start_capture`, `stop_capture`             | Network capture lifecycle                                                                                      |
@@ -134,7 +134,7 @@ The MCP server targets one of two backends. An explicit `USE_OLD_DEVTOOLS` setti
   - `get_me_providers` — list the providers you own (the only provider-listing tool in this mode).
   - `session_analytics_logs` — the milestone events for a verification session, which show how far it got.
   - `session_logs` — the log entries the in-app SDK emitted during that session, each with its event type, log level, and logger name. Filter by event type, level, or substring, page with `limit` and `offset`, or set `saveTo` to write every matching entry to an NDJSON file. The backend searches only the last 3 days unless you pass `startTime` and `endTime`, and it deletes entries after 30 days.
-- **Builder (default).** Registers the auto-generated HTTP-API tools, including `create_org`, `issue_org_token`, and `create_org_callback_subscription`, plus authentication/credential tools, `get_verification_result`, `read_callback_events` (read the org's pull-listener events), `proxy_callback_events` (forward them to a localhost callback route; the pull listener lives only while the MCP server runs), and `check_attestor`. `issue_credentials` creates a local proof-owner key; `issue_org_token` issues the organization's API secret.
+- **Builder (default).** Registers the auto-generated HTTP-API tools, including `create_org`, `issue_org_token`, and `create_org_callback_subscription`, plus authentication/credential tools, `get_verification_result`, `read_callback_events` (read the org's pull-listener events), `proxy_callback_events` (forward them to a localhost callback route; the pull listener lives only while the MCP server runs), and `check_attestor`. `issue_credentials` creates a local proof-owner key; `issue_org_token` issues the organization's API secret; `create_example_app` writes the builder-example app into a workspace that has none; `issue_org_keypair` creates the organization's key pair for session binding and encrypted results, writing the private key to the app's env file.
 
 Relevant env vars: `RECLAIM_OLD_API_URL` (default `https://devapi.reclaimprotocol.org`), `RECLAIM_OLD_API_TOKEN` / `RECLAIM_OLD_ETH_UID` (headless identity), `RECLAIM_OLD_LOGIN_URL` (default `https://dev.reclaimprotocol.org`); builder mode uses `RECLAIM_API_URL` / `RECLAIM_API_TOKEN`.
 
@@ -154,9 +154,9 @@ npm run download:zk-files --workspace=packages/agent
 
 ## Platform notes
 
-- **Node 20 or later** is required to run the published package (declared in `engines`). The package ships compiled `lib/*.js`, so no TypeScript type-stripping is needed at runtime.
+- **Node 22.12 or later** is required to run the published package (declared in `engines`; `@puppeteer/browsers`, used to download Chrome for Testing, needs it). The package ships compiled `lib/*.js`, so no TypeScript type-stripping is needed at runtime.
 
-  Any line works, including non-LTS ones such as 25. The one native addon that used to break this, `re2`, became an **optional** dependency in `@reclaimprotocol/attestor-core` 5.0.8 and degrades to the native `RegExp` when its binary is absent. The other native dependency, `koffi`, is N-API, so it ships ABI-independent prebuilts for every platform and was never version-sensitive. An LTS line (22 or 24) is still recommended, because `re2` is present there and gives faster, ReDoS-safe matching.
+  Any line from 22.12 works, including non-LTS ones such as 25. The one native addon that used to break this, `re2`, became an **optional** dependency in `@reclaimprotocol/attestor-core` 5.0.8 and degrades to the native `RegExp` when its binary is absent. The other native dependency, `koffi`, is N-API, so it ships ABI-independent prebuilts for every platform and was never version-sensitive. An LTS line (22 or 24) is still recommended, because `re2` is present there and gives faster, ReDoS-safe matching.
 
   Working on the package **from a checkout** additionally needs **Node 22.18 or later**: the test suite and the dev workflow run bare `.ts` files directly, and unflagged TypeScript type-stripping landed in 22.18.
 - **Chrome 136+ silently disables `--remote-debugging-port`** when launched against the default user profile. `dedicated` mode (the default) sidesteps this by always passing `--user-data-dir=~/.reclaim/chrome-profile`.

package/lib/authoring/backend.d.ts

@@ -20,6 +20,13 @@ export interface Draft {
     /** One entry per extracted value (value + its redaction), so replay can
      *  validate each against its own selector. */
     extractions: Extraction[];
+    /** Outcome of the latest authenticated in-browser replay, recorded by
+     *  backends that track it. Lets a failed proof tell "the site blocks
+     *  non-browser clients" apart from a broken recipe. */
+    lastReplay?: {
+        status: number;
+        ok: boolean;
+    };
 }
 /** A navigation script installed for every later page load of the authoring
  *  session. `identifier` is the CDP registration, so it can be removed. */
@@ -31,10 +38,12 @@ export interface KeptScript {
 export interface KeptScriptRef {
     keptScript?: KeptScript;
 }
-/** Per-session draft store: `propose` puts, `replay`/`run_proof` get by id. */
+/** Per-session draft store: `propose` puts, `replay`/`run_proof` get by id,
+ *  `update_draft` replaces one in place (same id). */
 export interface DraftStore {
     put(draft: Draft): string;
     get(id: string): Draft | undefined;
+    set(id: string, draft: Draft): void;
 }
 export declare function makeDraftStore(): DraftStore;
 /** Options for a proof run. `ownerAddress` selects the local signing credential
@@ -43,6 +52,8 @@ export declare function makeDraftStore(): DraftStore;
 export interface ProveOptions {
     ownerAddress?: string;
     attestorUrl?: string;
+    /** ISO country the attestor's request goes out from (local proofs). */
+    geoLocation?: string;
 }
 /**
  * Everything the shared authoring tools need from one live session. Browser ops

package/lib/authoring/backend.js

@@ -20,5 +20,8 @@ export function makeDraftStore() {
             return id;
         },
         get: (id) => map.get(id),
+        set: (id, draft) => {
+            map.set(id, draft);
+        },
     };
 }

package/lib/authoring/tools.js

@@ -19,7 +19,7 @@ import { findTool } from "../mcp/tools/agent/find.js";
 import { proposeTool } from "../mcp/tools/agent/propose.js";
 import { replayTool } from "../mcp/tools/agent/replay.js";
 import { defineTool } from "../tools/registry.js";
-import { objectSchema, publicRequest } from "./util.js";
+import { DEFAULT_MAX_CHARS, objectSchema, publicRequest, TEXT_WINDOW_PROPERTIES, textWindow, } from "./util.js";
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function matchesFilter(r, f) {
     if (f.method && r.method !== f.method.toUpperCase()) {
@@ -108,10 +108,32 @@ export function authoringTools(resolveBackend) {
                 + 'Use it to read a data point from the DOM, check sign-in state, '
                 + 'or trigger the target request (for example, `location.reload()`). '
                 + 'The page cannot reach files or processes on this machine. Return '
-                + 'only the values you need, never cookies or tokens.',
-            inputSchema: objectSchema({ expression: { type: 'string' } }, ['expression']),
+                + 'only the values you need, never cookies or tokens. A result '
+                + `longer than ${DEFAULT_MAX_CHARS} characters comes back `
+                + 'truncated (objects as JSON text) with `valueTruncation`; page '
+                + 'with `offset`, or pass `maxChars` or `full`.',
+            inputSchema: objectSchema({ expression: { type: 'string' }, ...TEXT_WINDOW_PROPERTIES }, ['expression']),
             annotations: { openWorldHint: true, destructiveHint: false },
-        }, (args) => evalInPage(resolveBackend(args), String(args.expression))),
+        }, async (args) => {
+            const res = await evalInPage(resolveBackend(args), String(args.expression));
+            if (res.value === undefined) {
+                return res;
+            }
+            const text = typeof res.value === 'string'
+                ? res.value
+                : JSON.stringify(res.value);
+            const slice = textWindow(text, args);
+            if (!slice.truncation) {
+                return res;
+            }
+            return {
+                value: slice.text,
+                valueTruncation: {
+                    ...slice.truncation,
+                    ...(typeof res.value === 'string' ? {} : { format: 'json' }),
+                },
+            };
+        }),
         defineTool({
             name: 'wait_for_page',
             description: 'Evaluates a JavaScript expression in the remote authoring browser '
@@ -369,7 +391,10 @@ export function authoringTools(resolveBackend) {
                 + 'attestor calls the target from its own network and IP. A request '
                 + 'that replayed can still fail here for geo- or IP-bound content '
                 + '(country-locked pages, IP-allowlisted APIs); that is a property '
-                + 'of the site, not a bug in the draft.',
+                + 'of the site, not a bug in the draft. HTTP 403/406/429/503 or a '
+                + 'challenge page from the attestor while the replay succeeded '
+                + 'means the site blocks non-browser clients: copying headers or '
+                + 'cookies will not help, so try a different endpoint or stop.',
             inputSchema: objectSchema({ draftId: { type: 'string' } }, ['draftId']),
             annotations: { openWorldHint: true, destructiveHint: false },
         }, 
@@ -391,6 +416,9 @@ export function authoringTools(resolveBackend) {
             if (typeof args.attestorUrl === 'string') {
                 opts.attestorUrl = args.attestorUrl;
             }
+            if (typeof args.geoLocation === 'string') {
+                opts.geoLocation = args.geoLocation;
+            }
             return backend.prove(draft, opts);
         }),
     ];

package/lib/authoring/util.d.ts

@@ -25,3 +25,46 @@ export declare function publicRequest(r: CapturedRequest): {
     contentType: string;
     size: number;
 };
+/** Characters a long text field returns by default (about 20 KB of ASCII),
+ *  so one page body or eval result can't flood the caller's context. */
+export declare const DEFAULT_MAX_CHARS = 20000;
+export interface TextWindowArgs {
+    maxChars?: unknown;
+    offset?: unknown;
+    full?: unknown;
+}
+/** Input properties that let a caller page through, or opt out of, the
+ *  window {@link textWindow} applies. */
+export declare const TEXT_WINDOW_PROPERTIES: {
+    maxChars: {
+        type: "integer";
+        minimum: number;
+        description: string;
+    };
+    offset: {
+        type: "integer";
+        minimum: number;
+        description: string;
+    };
+    full: {
+        type: "boolean";
+        description: string;
+    };
+};
+/**
+ * Returns characters `[offset, offset + maxChars)` of `text`. When that isn't
+ * the whole text, `truncation` reports the total size and how to get the rest.
+ */
+export declare function textWindow(text: string, args: TextWindowArgs): {
+    text: string;
+    truncation?: undefined;
+} | {
+    text: string;
+    truncation: {
+        note: string;
+        nextOffset?: number | undefined;
+        totalChars: number;
+        offset: number;
+        returnedChars: number;
+    };
+};

package/lib/authoring/util.js

@@ -22,3 +22,57 @@ export function publicRequest(r) {
         ...(r.graphqlOp ? { graphqlOp: r.graphqlOp } : {}),
     };
 }
+/** Characters a long text field returns by default (about 20 KB of ASCII),
+ *  so one page body or eval result can't flood the caller's context. */
+export const DEFAULT_MAX_CHARS = 20000;
+/** Input properties that let a caller page through, or opt out of, the
+ *  window {@link textWindow} applies. */
+export const TEXT_WINDOW_PROPERTIES = {
+    maxChars: {
+        type: 'integer',
+        minimum: 1,
+        description: `Maximum characters to return. Default ${DEFAULT_MAX_CHARS}.`,
+    },
+    offset: {
+        type: 'integer',
+        minimum: 0,
+        description: 'Character offset to start from, such as a previous '
+            + '`nextOffset`. Default 0.',
+    },
+    full: {
+        type: 'boolean',
+        description: 'Return the whole text, ignoring `maxChars`. It can be '
+            + 'megabytes, so prefer paging with `offset`.',
+    },
+};
+/**
+ * Returns characters `[offset, offset + maxChars)` of `text`. When that isn't
+ * the whole text, `truncation` reports the total size and how to get the rest.
+ */
+export function textWindow(text, args) {
+    const totalChars = text.length;
+    const offset = Math.min(Math.max(Number(args.offset) || 0, 0), totalChars);
+    const maxChars = args.full === true
+        ? totalChars
+        : Math.max(Number(args.maxChars) || DEFAULT_MAX_CHARS, 1);
+    const end = Math.min(offset + maxChars, totalChars);
+    if (offset === 0 && end === totalChars) {
+        return { text };
+    }
+    const part = text.slice(offset, end);
+    const more = end < totalChars;
+    return {
+        text: part,
+        truncation: {
+            totalChars,
+            offset,
+            returnedChars: part.length,
+            ...(more ? { nextOffset: end } : {}),
+            note: `Returned characters ${offset}-${end} of ${totalChars}.`
+                + (more
+                    ? ` Call again with offset: ${end} for more, or full: true `
+                        + 'for the whole text.'
+                    : ''),
+        },
+    };
+}

package/lib/cdp/chrome-for-testing.d.ts

@@ -0,0 +1,14 @@
+export interface ChromeForTestingInstall {
+    executablePath: string;
+    /** True when this call downloaded it; false when an earlier one had. */
+    downloaded: boolean;
+}
+/** Where downloaded browsers live: `~/.reclaim/browsers`. */
+export declare function browsersDirPath(): string;
+/**
+ * Chrome for Testing, the fallback when no local Chromium-family browser is
+ * installed or the installed one will not start. Downloaded once into
+ * `~/.reclaim/browsers` and reused after that, so only the first fallback pays
+ * the ~150 MB download.
+ */
+export declare function installChromeForTesting(cacheDir?: string): Promise<ChromeForTestingInstall>;

package/lib/cdp/chrome-for-testing.js

@@ -0,0 +1,43 @@
+import { failedDependency } from '@hapi/boom';
+import assert from 'node:assert';
+import { existsSync } from 'node:fs';
+import { arch, platform } from 'node:os';
+import { join } from 'node:path';
+import { LOGGER } from "../logger.js";
+import { reclaimHomeDirPath } from "../paths.js";
+/** Where downloaded browsers live: `~/.reclaim/browsers`. */
+export function browsersDirPath() {
+    return join(reclaimHomeDirPath(), 'browsers');
+}
+/**
+ * Chrome for Testing, the fallback when no local Chromium-family browser is
+ * installed or the installed one will not start. Downloaded once into
+ * `~/.reclaim/browsers` and reused after that, so only the first fallback pays
+ * the ~150 MB download.
+ */
+export async function installChromeForTesting(cacheDir = browsersDirPath()) {
+    // Loaded on demand: only the fallback path needs it.
+    const { Browser, detectBrowserPlatform, getInstalledBrowsers, getVersionComparator, install, resolveBuildId, } = await import('@puppeteer/browsers');
+    const browserPlatform = detectBrowserPlatform();
+    assert(browserPlatform, failedDependency(`Chrome for Testing has no build for ${platform()}/${arch()}.`));
+    const compare = getVersionComparator(Browser.CHROME);
+    const all = await getInstalledBrowsers({ cacheDir });
+    const installed = all
+        .filter((b) => b.browser === Browser.CHROME
+        && b.platform === browserPlatform
+        && existsSync(b.executablePath))
+        .sort((a, b) => compare(a.buildId, b.buildId));
+    const newest = installed.at(-1);
+    if (newest) {
+        return { executablePath: newest.executablePath, downloaded: false };
+    }
+    const buildId = await resolveBuildId(Browser.CHROME, browserPlatform, 'stable');
+    LOGGER.info({ buildId, cacheDir }, 'downloading Chrome for Testing');
+    const result = await install({
+        browser: Browser.CHROME,
+        platform: browserPlatform,
+        buildId,
+        cacheDir,
+    });
+    return { executablePath: result.executablePath, downloaded: true };
+}

package/lib/cdp/geo.d.ts

@@ -8,3 +8,6 @@ export interface IpGeolocation {
  *  lookup failure just loses the "best guess" convenience, falling back to
  *  {@link FALLBACK_COUNTRY_CODE} rather than blocking applying a proxy. */
 export declare function suggestCountryFromIp(fetchImpl?: typeof fetch): Promise<IpGeolocation>;
+/** The calling machine's public-IP country, or undefined when the lookup
+ *  fails: unlike {@link suggestCountryFromIp}, no guessed fallback. */
+export declare function lookupIpCountry(fetchImpl?: typeof fetch): Promise<string | undefined>;

package/lib/cdp/geo.js

@@ -5,6 +5,7 @@
  * public-IP country, resolved the same way reclaim-portal's `ip-geolocation`
  * util does.
  */
+import assert from 'node:assert';
 import { LOGGER } from "../logger.js";
 const IPINFO_URL = 'https://ipinfo.io/json';
 const FALLBACK_COUNTRY_CODE = 'US';
@@ -13,24 +14,35 @@ const FALLBACK_COUNTRY_CODE = 'US';
  *  {@link FALLBACK_COUNTRY_CODE} rather than blocking applying a proxy. */
 export async function suggestCountryFromIp(fetchImpl = fetch) {
     try {
-        const res = await fetchImpl(IPINFO_URL);
-        if (!res.ok) {
-            throw new Error(`ipinfo.io ${res.status}`);
-        }
-        const data = await res.json();
-        const countryCode = data.country?.toUpperCase();
-        if (!countryCode) {
-            throw new Error('ipinfo.io response had no country');
-        }
-        return {
-            countryCode,
-            country: data.country,
-            region: data.region,
-            city: data.city,
-        };
+        return await fetchIpGeolocation(fetchImpl);
     }
     catch (err) {
         LOGGER.warn({ err }, 'suggestCountryFromIp failed; using fallback');
         return { countryCode: FALLBACK_COUNTRY_CODE };
     }
 }
+/** The calling machine's public-IP country, or undefined when the lookup
+ *  fails: unlike {@link suggestCountryFromIp}, no guessed fallback. */
+export async function lookupIpCountry(fetchImpl = fetch) {
+    try {
+        const { countryCode } = await fetchIpGeolocation(fetchImpl);
+        return countryCode;
+    }
+    catch (err) {
+        LOGGER.warn({ err }, 'IP country lookup failed');
+        return undefined;
+    }
+}
+async function fetchIpGeolocation(fetchImpl) {
+    const res = await fetchImpl(IPINFO_URL);
+    assert(res.ok, new Error(`ipinfo.io ${res.status}`));
+    const data = await res.json();
+    const countryCode = data.country?.toUpperCase();
+    assert(countryCode, new Error('ipinfo.io response had no country'));
+    return {
+        countryCode,
+        country: data.country,
+        region: data.region,
+        city: data.city,
+    };
+}

package/lib/cdp/launcher.d.ts

@@ -1,4 +1,8 @@
 import { type ChildProcess } from 'node:child_process';
+import { installChromeForTesting } from './chrome-for-testing.ts';
+/** How long a launched browser gets to answer CDP. A cold first start on a
+ *  slow disk, or Chrome for Testing's first run, can take well over 10s. */
+export declare const CDP_READY_TIMEOUT_MS = 30000;
 export interface LaunchOptions {
     /** Port for --remote-debugging-port. */
     port: number;
@@ -7,8 +11,82 @@ export interface LaunchOptions {
     /** If true, launch without a visible window (--headless=new). Useful
      *  for tests and CI; user-driven flows want it false. */
     headless?: boolean;
+    /** How long to wait for CDP to answer. */
+    timeoutMs?: number;
 }
+export type LocalBrowserSource = 'installed' | 'override' | 'chrome-for-testing';
+export interface LocalBrowser {
+    binary: string;
+    source: LocalBrowserSource;
+    process: ChildProcess;
+    /** Chrome for Testing was downloaded by this launch. */
+    downloaded: boolean;
+    /** Why the installed browser was passed over for Chrome for Testing. */
+    fallbackReason?: string;
+}
+export interface LocalBrowserDependencies {
+    platform: () => NodeJS.Platform;
+    env: () => NodeJS.ProcessEnv;
+    /** Explicit binary override (`RECLAIM_AGENT_CHROME_PATH`). */
+    chromePath: () => string | undefined;
+    /** Installed Chromium-family browsers, most preferred first. */
+    findInstalled: () => string[];
+    installChromeForTesting: typeof installChromeForTesting;
+}
+/**
+ * Build the platform-specific list of Chromium-family binaries to probe.
+ * Order matters: Chrome first, then Chromium, then Edge (Edge is
+ * Chromium-based, supports CDP, and is preinstalled on Win 10/11 — a
+ * useful fallback when Chrome itself isn't installed).
+ *
+ * On Windows we also probe the per-user Chrome install under
+ * %LOCALAPPDATA%, which is what you get when Chrome was installed
+ * without admin rights ("Install for me only"). Skipping this was the
+ * #1 first-run failure observed in the field.
+ */
+export declare function browserCandidates(os?: NodeJS.Platform): string[];
+/** The candidates that exist on this machine, in preference order. */
+export declare function findInstalledBrowsers(candidates?: string[]): string[];
 export declare function defaultProfileDir(): string;
 export declare function findChromeBinary(): string;
-export declare function launchChrome(opts: LaunchOptions): ChildProcess;
+/**
+ * Why a visible browser cannot open here, or undefined when it can. Only
+ * Linux needs a display server named in the environment; an MCP server
+ * started outside the desktop session (a sandboxed agent, a service) often
+ * has neither variable, and Chrome then exits before CDP ever answers.
+ */
+export declare function missingDisplayReason(os?: NodeJS.Platform, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Launch a visible browser on this machine with the given profile, and wait
+ * until it answers CDP.
+ *
+ * Uses `RECLAIM_AGENT_CHROME_PATH` when set, else the first installed browser
+ * (Chrome, then Chromium, then Edge). When none is installed, or that one
+ * fails to start, it falls back to Chrome for Testing, downloaded once into
+ * `~/.reclaim/browsers`. A missing display fails fast instead: no browser can
+ * open without one, so a download would only waste time.
+ */
+export declare function launchLocalBrowser(opts: LaunchOptions, dependencies?: Partial<LocalBrowserDependencies>): Promise<LocalBrowser>;
+/**
+ * Spawn `binary` on `opts.profileDir` and wait for CDP. On failure the
+ * process is stopped and the error says why: it could not be spawned, it
+ * exited (with its code and the tail of its stderr), or it never answered.
+ */
+export declare function startChrome(binary: string, opts: LaunchOptions): Promise<ChildProcess>;
+/**
+ * Remove a dead browser's claim on `profileDir` so a new launch can take it.
+ *
+ * Chrome on POSIX claims a profile with `SingletonLock -> <hostname>-<pid>`.
+ * If that process is gone (a crash, a killed session) the links stay behind
+ * and the next launch hands off to the missing owner and exits. A lock whose
+ * PID is alive on this host belongs to a running browser, and is left alone:
+ * that browser must be closed first. A lock from another hostname is treated
+ * as stale: `~/.reclaim` is local, and a sandbox or container that changes the
+ * hostname between runs is the usual way to get one. Callers reach this only
+ * after nothing answered CDP on the port.
+ */
+export declare function releaseStaleProfileLock(profileDir: string, os?: NodeJS.Platform): void;
+/**
+ * Wait until something answers CDP on `port`, polling every 150ms.
+ */
 export declare function waitForCdpReady(port: number, timeoutMs?: number): Promise<void>;