@reclaimprotocol/agent 0.1.0-dev.1

package/README.md

@@ -0,0 +1,287 @@
+# @reclaimprotocol/agent
+
+Chrome-CDP + zkTLS provider-authoring tools. The agent captures network traffic from a browser, synthesizes Reclaim provider definitions from it (`contains` matchers + `jsonPath` / `xPath` / `regex` redactions), runs a local replay diagnostic, and produces a verified attestor proof via `@reclaimprotocol/attestor-core`.
+
+This package **is** the Reclaim MCP server (bin: `reclaim-mcp-server`). It depends on `@reclaimprotocol/client` for the typed HTTP client and registers the provider-authoring tools below alongside the backend-facing tools (credentials, publishing) in a single MCP surface. A standalone entry (`src/index.ts`) re-exports the client SDK plus `buildAgentTools` for embedding.
+
+## Install
+
+**Prerequisites:** Node ≥ 22.18 and a local Chrome / Chromium / Edge (used for capture and the dashboard login). The first run downloads the ZK circuit files needed by `run_proof` (a `postinstall` step), so allow a moment on first launch.
+
+It runs as a **stdio MCP server**. Point any MCP-capable agent at this command:
+
+```bash
+npx -y -p @reclaimprotocol/agent reclaim-mcp-server
+```
+
+> The `-p` (`--package`) flag selects the `reclaim-mcp-server` binary from the package. Prefer a global install? Run `npm i -g @reclaimprotocol/agent` and use `reclaim-mcp-server` directly as the `command` (drop the `npx` wrapper and its `args`).
+
+### Claude Code
+
+```bash
+# project scope → writes .mcp.json; add `-s user` for a global install
+claude mcp add reclaim -- npx -y -p @reclaimprotocol/agent reclaim-mcp-server
+```
+
+…or add it to `.mcp.json` yourself:
+
+```json
+{
+  "mcpServers": {
+    "reclaim": {
+      "command": "npx",
+      "args": ["-y", "-p", "@reclaimprotocol/agent", "reclaim-mcp-server"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "reclaim": {
+      "command": "npx",
+      "args": ["-y", "-p", "@reclaimprotocol/agent", "reclaim-mcp-server"]
+    }
+  }
+}
+```
+
+### opencode
+
+Add to `opencode.json` (project) or `~/.config/opencode/opencode.json` (global):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "reclaim": {
+      "type": "local",
+      "command": ["npx", "-y", "-p", "@reclaimprotocol/agent", "reclaim-mcp-server"],
+      "enabled": true
+    }
+  }
+}
+```
+
+### Antigravity, Windsurf, VS Code, Cline & other MCP clients
+
+These all use the standard `mcpServers` shape — add a server through the app's MCP settings (or its `mcp`/`mcpServers` config file) with:
+
+```json
+{
+  "mcpServers": {
+    "reclaim": {
+      "command": "npx",
+      "args": ["-y", "-p", "@reclaimprotocol/agent", "reclaim-mcp-server"]
+    }
+  }
+}
+```
+
+### Optional environment
+
+Defaults target the production old-devtools backend, so **no env is needed for the common case**. To override, add an `env` block (or `environment` in opencode) to the config above:
+
+```json
+"env": {
+  "USE_OLD_DEVTOOLS": "true",
+  "RECLAIM_OLD_API_URL": "https://devapi.reclaimprotocol.org"
+}
+```
+
+See [Backends](#backends) for builder mode (`USE_OLD_DEVTOOLS=false`) and the full env-var list.
+
+### Companion skill (optional, recommended)
+
+The MCP server is all you need to start — but installing the companion skill makes the agent markedly better at the capture → prove → publish flow (login detection, choosing auth-bound endpoints, OPRF decisions, troubleshooting). See [Skill](#skill) for install steps.
+
+## Using it from your agent
+
+Optional but recommended: install the [skill](#skill) so the agent follows the full authoring flow.
+
+Then just ask in plain language, e.g.:
+
+> "Use Reclaim to create a provider that proves my GitHub follower count."
+
+or you can even ask it like:
+
+> "I want to verify Github follow count"
+
+The agent orchestrates the tools for you:
+
+1. **`reclaim_authenticate`** — a Chrome window opens the Reclaim dashboard; you sign in. The token is captured automatically and the tab closes. (Or it reuses a still-valid cached identity.)
+2. **`attach_chrome` + `navigate`** — opens the target site (e.g. `github.com`); **`wait_for_page`** waits while you log in there.
+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.
+6. **`create_provider_version_from_capture`** — publishes it. **`get_me_providers`** lists what you own; pass a returned `providerId` back to publish a new version of an existing provider.
+
+Your only manual steps are signing in when the browser windows open and confirming the value you want to prove.
+
+## Skill
+
+Optional but recommended. The companion skill (`skill/SKILL.md`) is a Claude Code **Agent Skill** that teaches the agent the full mode-aware authoring flow — it ships inside the npm package and is also in this repo.
+
+```bash
+# macOS / Linux — from a global install of the package
+npm i -g @reclaimprotocol/agent
+mkdir -p ~/.claude/skills/reclaim-provider
+cp "$(npm root -g)/@reclaimprotocol/agent/skill/SKILL.md" ~/.claude/skills/reclaim-provider/SKILL.md
+
+# …or from a checkout of this repo
+cp packages/agent/skill/SKILL.md ~/.claude/skills/reclaim-provider/SKILL.md
+```
+
+```powershell
+# Windows (PowerShell) — from a global install
+npm i -g @reclaimprotocol/agent
+New-Item -ItemType Directory -Force $env:USERPROFILE\.claude\skills\reclaim-provider | Out-Null
+Copy-Item "$(npm root -g)\@reclaimprotocol\agent\skill\SKILL.md" $env:USERPROFILE\.claude\skills\reclaim-provider\SKILL.md
+```
+
+Claude Code auto-loads it once it's in `~/.claude/skills/`. **Other MCP clients** (Cursor, opencode, Antigravity, …) don't read `SKILL.md` automatically — the server's built-in instructions already cover the essentials, and you can paste or adapt the skill's content into that client's rules / system-prompt for the same depth.
+
+## Provider-authoring tools
+
+These capture/synthesis/proof tools are backend-independent and registered in both modes (see [Backends](#backends)):
+
+| Tool                                        | Purpose                                                                                                        |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `attach_chrome`                             | Connect to Chrome via CDP — dedicated profile or attach to running instance                                    |
+| `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                                                                                      |
+| `list_requests`, `get_request`              | Inspect captured traffic                                                                                       |
+| `find_requests_containing`                  | Deterministic search for a target value across captured responses                                              |
+| `analyze_request_constraints`               | Flag concerns (signed, csrf, graphql, etc.)                                                                    |
+| `propose_provider`                          | Synthesize a provider — `contains` match + `jsonPath`/`xPath`/`regex` redaction                                |
+| `replay_request`                            | Pre-flight replay via Node `fetch` (no attestor); also used for auth-bound check by omitting `secretParamsRef` |
+| `run_proof`                                 | End-to-end zkTLS proof through the attestor SDK                                                                |
+| `create_provider_version_from_capture`      | Publish a drafted provider to the backend                                                                      |
+| `get_session`, `reset_session`              | Session state                                                                                                  |
+
+## Backends
+
+The MCP server targets one of two backends, selected by `USE_OLD_DEVTOOLS`:
+
+- **Old devtools (default).** The legacy devtools backend is still in production while the new "builder" backend is built, so this is the default — opt into builder with `USE_OLD_DEVTOOLS=false`. In old mode all auto-generated HTTP-API tools are disabled and a small client (`src/old/`) serves:
+  - `reclaim_authenticate` — by default opens the dashboard in Chrome via CDP, waits for sign-in, reads the Firebase token from page storage, and closes the tab (or pass a `token` / `ethAddress` to skip the browser).
+  - `create_provider_version_from_capture` — registers a new provider, or adds a version to an existing one when given a `providerId`.
+  - `get_me_providers` — list the providers you own (the only provider-listing tool in this mode).
+- **Builder (`USE_OLD_DEVTOOLS=false`).** Registers the auto-generated HTTP-API tools plus the builder credential tools (`reclaim_authenticate` device-code flow, `reclaim_status`, and the local credential tools).
+
+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`.
+
+## Local development (from source)
+
+For working on the package inside the monorepo (consumers should use [Install](#install) instead). A workspace install fetches dependencies and runs this package's postinstall, which downloads the ZK circuit resources needed by `@reclaimprotocol/attestor-core` at proof time:
+
+```bash
+npm install
+```
+
+If postinstall is skipped (`npm ci --ignore-scripts`, or a corp policy disabling postinstall), run it manually:
+
+```bash
+npm run download:zk-files --workspace=packages/agent
+```
+
+## Platform notes
+
+- **Node >=22.18** is required (declared in `engines`). The floor is 22.18 because the package's `postinstall` and helper scripts run as bare `.ts` files, and unflagged TypeScript type-stripping landed in Node 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`.
+
+## Tests
+
+`npm test` runs the unit + integration suite (no Chrome needed).
+
+The Chrome CDP end-to-end test at `tests/e2e-chrome.test.ts` is gated behind an env var. It launches headless Chrome with a dedicated temp profile, captures a navigation against a local fixture server, and asserts the synthesiser finds the right request. To run it:
+
+```bash
+# bash / macOS / Linux
+RECLAIM_AGENT_E2E=1 npm test --workspace=packages/agent
+
+# Windows PowerShell
+$env:RECLAIM_AGENT_E2E=1; npm test --workspace=packages/agent
+```
+
+Requires Chrome / Chromium / Edge installed somewhere `findChromeBinary` can locate (or `RECLAIM_AGENT_CHROME_PATH` set). The test self-skips if no binary is found.
+
+## Disabling
+
+The MCP server registers the provider-authoring (Chrome/CDP) tools by default in both modes. To disable them (e.g. in hosted deployments where no local Chrome is available):
+
+```bash
+RECLAIM_AGENT_DISABLED=1
+```
+
+## For contributors — wiring a local build into Claude Code / opencode
+
+> This section is for working **on this package from a checkout**. Consumers should use the published package via [Install](#install) instead.
+
+First build so `lib/mcp-bin.js` exists, then point your agent at that file by absolute path (not `npx`):
+
+```bash
+npm install                              # once, from the repo root
+npm run build --workspace=packages/agent # rebuild after changes (or `npm run dev` to watch)
+```
+
+### MCP server
+
+**Claude Code** — register the local binary:
+
+```bash
+# from the repo root; -s user for a global install (omit for project scope → .mcp.json)
+claude mcp add reclaim -- node "$(pwd)/packages/agent/lib/mcp-bin.js"
+```
+
+…or add it to `.mcp.json` yourself, using an **absolute path**:
+
+```json
+{
+  "mcpServers": {
+    "reclaim": {
+      "command": "node",
+      "args": ["/abs/path/to/builder/packages/agent/lib/mcp-bin.js"]
+    }
+  }
+}
+```
+
+**opencode** — add to `opencode.json` (project) or `~/.config/opencode/opencode.json` (global), again with an absolute path:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "reclaim": {
+      "type": "local",
+      "command": ["node", "/absolute/path/to/builder/packages/agent/lib/mcp-bin.js"],
+      "enabled": true
+    }
+  }
+}
+```
+
+To target a specific backend while developing, add an `env` block (Claude Code / `.mcp.json`) or `environment` (opencode) — e.g. `"USE_OLD_DEVTOOLS": "false"` for builder mode. See [Backends](#backends).
+
+### Skill
+
+Symlink the source `skill/` folder into `~/.claude/skills/` so edits to `SKILL.md` are picked up live (no re-copy):
+
+```bash
+# macOS / Linux — from the repo root
+ln -s "$(pwd)/packages/agent/skill" ~/.claude/skills/reclaim-provider
+```
+
+```powershell
+# Windows (PowerShell, Developer Mode or elevated) — from the repo root
+New-Item -ItemType SymbolicLink -Path $env:USERPROFILE\.claude\skills\reclaim-provider -Target (Resolve-Path packages\agent\skill)
+```
+
+Claude Code auto-loads it once linked. opencode doesn't read `SKILL.md` automatically — paste or adapt its content into that client's rules / system-prompt for the same depth.

package/lib/cdp/capture.d.ts

@@ -0,0 +1,22 @@
+import type CDP from 'chrome-remote-interface';
+import type { Protocol } from 'devtools-protocol';
+import type { CapturedRequest } from '../provider/schema.ts';
+import { BodyStore } from './eviction.ts';
+/** Drop HTTP/2 pseudo-headers (`:authority`, `:method`, `:path`, `:scheme`,
+ *  `:status`) from a CDP header map. Chrome emits them on HTTP/2 requests,
+ *  but they're a transport-layer abstraction with no place in our domain:
+ *  the URL already carries authority/path/scheme, the request object carries
+ *  method, and Node's `fetch` (undici) throws on any header starting with
+ *  `:`. Stripping at capture time keeps every downstream consumer
+ *  (`get_request`, draft, replay, proof) clean by construction. */
+export declare function stripPseudoHeaders(headers: Protocol.Network.Headers): Record<string, string>;
+export interface CaptureSession {
+    captureId: string;
+    requests: Map<string, CapturedRequest>;
+    bodies: BodyStore;
+    stop: () => Promise<void>;
+}
+export interface StartCaptureOptions {
+    maxBodyBytes?: number;
+}
+export declare function startCapture(tab: CDP.Client, opts?: StartCaptureOptions): Promise<CaptureSession>;

package/lib/cdp/capture.js

@@ -0,0 +1,159 @@
+import { randomUUID } from 'node:crypto';
+import { extractGraphqlOp } from "../provider/graphql.js";
+import { BodyStore } from "./eviction.js";
+/** Drop HTTP/2 pseudo-headers (`:authority`, `:method`, `:path`, `:scheme`,
+ *  `:status`) from a CDP header map. Chrome emits them on HTTP/2 requests,
+ *  but they're a transport-layer abstraction with no place in our domain:
+ *  the URL already carries authority/path/scheme, the request object carries
+ *  method, and Node's `fetch` (undici) throws on any header starting with
+ *  `:`. Stripping at capture time keeps every downstream consumer
+ *  (`get_request`, draft, replay, proof) clean by construction. */
+export function stripPseudoHeaders(headers) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers)) {
+        if (!k.startsWith(':')) {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+export async function startCapture(tab, opts = {}) {
+    const captureId = randomUUID();
+    const requests = new Map();
+    const inFlight = new Map();
+    const bodies = new BodyStore({
+        maxBytes: opts.maxBodyBytes ?? 200 * 1024 * 1024,
+    });
+    // CDP doesn't guarantee `requestWillBeSent` arrives before
+    // `requestWillBeSentExtraInfo` (same for the response pair). When extra
+    // info lands first, buffer it here and drain on the matching primary
+    // event. Without this, headers (Cookie, Authorization, …) get silently
+    // dropped for any request whose events race in the unlucky order.
+    const pendingRequestExtra = new Map();
+    const pendingResponseExtra = new Map();
+    const { Network } = tab;
+    await Network.enable();
+    /** Merge extra headers from the ...ExtraInfo events into either the
+     *  in-flight entry or the finalized captured request, whichever has
+     *  arrived. If neither exists yet (extra-info-first race), buffer the
+     *  headers and drain on the matching primary event. */
+    function mergeRequestHeaders(requestId, extra) {
+        const clean = stripPseudoHeaders(extra);
+        const f = inFlight.get(requestId);
+        if (f) {
+            f.requestHeaders = { ...f.requestHeaders, ...clean };
+            return;
+        }
+        const r = requests.get(requestId);
+        if (r) {
+            r.requestHeaders = { ...r.requestHeaders, ...clean };
+            return;
+        }
+        const buffered = pendingRequestExtra.get(requestId) ?? {};
+        pendingRequestExtra.set(requestId, { ...buffered, ...clean });
+    }
+    function mergeResponseHeaders(requestId, extra) {
+        const clean = stripPseudoHeaders(extra);
+        const r = requests.get(requestId);
+        if (r) {
+            r.responseHeaders = { ...r.responseHeaders, ...clean };
+            return;
+        }
+        const buffered = pendingResponseExtra.get(requestId) ?? {};
+        pendingResponseExtra.set(requestId, { ...buffered, ...clean });
+    }
+    Network.requestWillBeSent(({ requestId, request }) => {
+        const f = {
+            requestId,
+            method: request.method,
+            url: request.url,
+            requestHeaders: stripPseudoHeaders(request.headers),
+            startedAt: Date.now(),
+        };
+        if (request.postData !== undefined) {
+            f.requestBody = request.postData;
+        }
+        // Drain any extra-info that arrived before us.
+        const buffered = pendingRequestExtra.get(requestId);
+        if (buffered) {
+            f.requestHeaders = { ...f.requestHeaders, ...buffered };
+            pendingRequestExtra.delete(requestId);
+        }
+        inFlight.set(requestId, f);
+    });
+    // CDP intentionally omits `Cookie` (and other browser-injected headers)
+    // from `requestWillBeSent.request.headers` for privacy. The real
+    // outgoing headers — including Cookie — arrive on the matching
+    // `requestWillBeSentExtraInfo` event.
+    Network.requestWillBeSentExtraInfo(({ requestId, headers }) => {
+        mergeRequestHeaders(requestId, headers);
+    });
+    Network.responseReceived(({ requestId, response }) => {
+        const f = inFlight.get(requestId);
+        if (!f) {
+            return;
+        }
+        const captured = {
+            requestId,
+            method: f.method,
+            url: f.url,
+            status: response.status,
+            contentType: response.mimeType,
+            size: response.encodedDataLength,
+            requestHeaders: f.requestHeaders,
+            responseHeaders: stripPseudoHeaders(response.headers),
+            finishedAt: 0,
+        };
+        // Drain any response extra-info that arrived before us.
+        const bufferedResp = pendingResponseExtra.get(requestId);
+        if (bufferedResp) {
+            captured.responseHeaders = {
+                ...captured.responseHeaders,
+                ...bufferedResp,
+            };
+            pendingResponseExtra.delete(requestId);
+        }
+        if (f.requestBody !== undefined) {
+            captured.requestBody = f.requestBody;
+        }
+        const op = extractGraphqlOp(f.requestBody);
+        if (op !== undefined) {
+            captured.graphqlOp = op;
+        }
+        requests.set(requestId, captured);
+    });
+    // Same privacy carve-out applies to `Set-Cookie` and other browser-
+    // visible response headers; they arrive on responseReceivedExtraInfo.
+    Network.responseReceivedExtraInfo(({ requestId, headers }) => {
+        mergeResponseHeaders(requestId, headers);
+    });
+    Network.loadingFinished(async ({ requestId }) => {
+        const r = requests.get(requestId);
+        if (!r) {
+            return;
+        }
+        try {
+            const { body, base64Encoded } = await Network.getResponseBody({
+                requestId,
+            });
+            const text = base64Encoded
+                ? Buffer.from(body, 'base64').toString('utf8')
+                : body;
+            bodies.set(requestId, text);
+            r.responseBody = text;
+            r.finishedAt = Date.now();
+        }
+        catch {
+            // Body might be unavailable for
+            // some content-types (e.g. websocket). Skip.
+        }
+    });
+    return {
+        captureId,
+        requests,
+        bodies,
+        stop: async () => {
+            await Network.disable();
+        },
+    };
+}

package/lib/cdp/client.d.ts

@@ -0,0 +1,9 @@
+import CDP from 'chrome-remote-interface';
+export interface CdpHandles {
+    /** Browser-level connection (target list, attach). */
+    browser: CDP.Client;
+    /** Returns a per-target session bound to a tab. */
+    attachToTab: (targetId: string) => Promise<CDP.Client>;
+    close: () => Promise<void>;
+}
+export declare function connectCdp(port: number): Promise<CdpHandles>;

package/lib/cdp/client.js

@@ -0,0 +1,11 @@
+import CDP from 'chrome-remote-interface';
+export async function connectCdp(port) {
+    const browser = await CDP({ port });
+    return {
+        browser,
+        attachToTab: (targetId) => CDP({ port, target: targetId }),
+        close: async () => {
+            await browser.close();
+        },
+    };
+}

package/lib/cdp/eviction.d.ts

@@ -0,0 +1,16 @@
+export type BodyLookup = {
+    available: true;
+    body: string;
+} | {
+    available: false;
+    reason: string;
+};
+export interface BodyStoreOptions {
+    maxBytes: number;
+}
+export declare class BodyStore {
+    #private;
+    constructor(opts: BodyStoreOptions);
+    set(requestId: string, body: string): void;
+    get(requestId: string): BodyLookup;
+}

package/lib/cdp/eviction.js

@@ -0,0 +1,38 @@
+export class BodyStore {
+    #store = new Map(); // insertion order = LRU order
+    #bytes = 0;
+    #opts;
+    constructor(opts) {
+        this.#opts = opts;
+    }
+    set(requestId, body) {
+        if (this.#store.has(requestId)) {
+            this.#bytes -= byteLen(this.#store.get(requestId));
+            this.#store.delete(requestId);
+        }
+        this.#store.set(requestId, body);
+        this.#bytes += byteLen(body);
+        while (this.#bytes > this.#opts.maxBytes && this.#store.size > 0) {
+            const oldestKey = this.#store.keys().next().value;
+            const oldestVal = this.#store.get(oldestKey);
+            this.#bytes -= byteLen(oldestVal);
+            this.#store.delete(oldestKey);
+        }
+    }
+    get(requestId) {
+        const body = this.#store.get(requestId);
+        if (body === undefined) {
+            return {
+                available: false,
+                reason: 'evicted from in-memory LRU body store',
+            };
+        }
+        // Refresh LRU position by re-inserting.
+        this.#store.delete(requestId);
+        this.#store.set(requestId, body);
+        return { available: true, body };
+    }
+}
+function byteLen(s) {
+    return Buffer.byteLength(s, 'utf8');
+}

package/lib/cdp/launcher.d.ts

@@ -0,0 +1,14 @@
+import { type ChildProcess } from 'node:child_process';
+export interface LaunchOptions {
+    /** Port for --remote-debugging-port. */
+    port: number;
+    /** Path to user-data-dir. Created if missing. */
+    profileDir: string;
+    /** If true, launch without a visible window (--headless=new). Useful
+     *  for tests and CI; user-driven flows want it false. */
+    headless?: boolean;
+}
+export declare function defaultProfileDir(): string;
+export declare function findChromeBinary(): string;
+export declare function launchChrome(opts: LaunchOptions): ChildProcess;
+export declare function waitForCdpReady(port: number, timeoutMs?: number): Promise<void>;

package/lib/cdp/launcher.js

@@ -0,0 +1,102 @@
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+import { reclaimHomeDirPath } from "../paths.js";
+/**
+ * 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.
+ */
+function browserCandidates() {
+    switch (platform()) {
+        case 'darwin':
+            return [
+                '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+                join(homedir(), 'Applications/Google Chrome.app/Contents/MacOS/Google Chrome'),
+                '/Applications/Chromium.app/Contents/MacOS/Chromium',
+                '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+            ];
+        case 'win32': {
+            const localAppData = process.env['LOCALAPPDATA'] ?? join(homedir(), 'AppData', 'Local');
+            return [
+                // System-wide Chrome
+                'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+                'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+                // Per-user Chrome ("Install for me only")
+                join(localAppData, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+                // Edge — Chromium-based, preinstalled on Win 10/11
+                'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe',
+                'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+            ];
+        }
+        case 'linux':
+            return [
+                '/usr/bin/google-chrome',
+                '/usr/bin/google-chrome-stable',
+                '/usr/bin/chromium',
+                '/usr/bin/chromium-browser',
+                '/snap/bin/chromium',
+                '/usr/bin/microsoft-edge',
+            ];
+        default:
+            return [];
+    }
+}
+export function defaultProfileDir() {
+    return join(reclaimHomeDirPath(), 'chrome-profile');
+}
+export function findChromeBinary() {
+    const candidates = browserCandidates();
+    for (const c of candidates) {
+        if (existsSync(c)) {
+            return c;
+        }
+    }
+    throw new Error(`No Chromium-family browser found on ${platform()}. Tried:\n  ` +
+        candidates.join('\n  ') +
+        '\nSet RECLAIM_AGENT_CHROME_PATH to point at ' +
+        'your chrome.exe / msedge.exe / chromium binary.');
+}
+export function launchChrome(opts) {
+    const binary = process.env.RECLAIM_AGENT_CHROME_PATH ?? findChromeBinary();
+    if (!existsSync(opts.profileDir)) {
+        mkdirSync(opts.profileDir, { recursive: true });
+    }
+    const args = [
+        `--remote-debugging-port=${opts.port}`,
+        `--user-data-dir=${opts.profileDir}`,
+        '--no-first-run',
+        '--no-default-browser-check',
+    ];
+    if (opts.headless) {
+        args.push('--headless=new', '--disable-gpu');
+    }
+    const child = spawn(binary, args, {
+        stdio: 'ignore',
+        detached: false,
+    });
+    return child;
+}
+export async function waitForCdpReady(port, timeoutMs = 10_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetch(`http://127.0.0.1:${port}/json/version`);
+            if (res.ok) {
+                return;
+            }
+        }
+        catch {
+            // retry
+        }
+        await new Promise((r) => setTimeout(r, 150));
+    }
+    throw new Error(`Chrome CDP did not become ready on port ${port} within ${timeoutMs}ms`);
+}

package/lib/cdp/tabs.d.ts

@@ -0,0 +1,6 @@
+export interface TabInfo {
+    tabId: string;
+    url: string;
+    title: string;
+}
+export declare function listTabs(port: number): Promise<TabInfo[]>;