@reclaimprotocol/agent 0.1.17 → 0.1.20

package/README.md

@@ -65,7 +65,7 @@ or you can even ask it like:
 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.
+2. **`attach_browser` + `navigate`** — uses local Chrome, a Builder-hosted remote browser, or a custom CDP websocket; **`wait_for_page`** waits while the operator logs 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.
@@ -83,7 +83,8 @@ These capture/synthesis/proof tools are backend-independent and registered in bo
 
 | Tool                                        | Purpose                                                                                                        |
 | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `attach_chrome`                             | Connect to Chrome via CDP — dedicated profile or attach to running instance                                    |
+| `attach_browser`                            | Connect via local Chrome, Builder-hosted Popcorn with a shareable live view, or a custom CDP websocket          |
+| `attach_chrome`                             | Backward-compatible alias for `attach_browser`                                                                  |
 | `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                                                                                      |
@@ -94,6 +95,9 @@ These capture/synthesis/proof tools are backend-independent and registered in bo
 | `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                                                                      |
+| `authenticate_builder`                      | In old-devtools mode only, sign in to Builder for remote-browser allocation                                   |
+| `list_builder_organizations`                | In old-devtools mode only, list organization ids for a quota-accounted Builder browser                         |
+| `dispose_browser`                           | Stop captures, disconnect CDP, and immediately release a Builder-hosted browser                               |
 | `get_session`, `reset_session`              | Session state                                                                                                  |
 
 ## Backends

package/lib/authoring/backend.d.ts

@@ -42,6 +42,10 @@ export interface ProveOptions {
  * its own result, passed straight through as the tool's output.
  */
 export interface AuthoringBackend {
+    /** Ask Chrome to reject page evaluation when side effects cannot be ruled
+     * out. Cloud authoring enables this; local MCP keeps its existing
+     * behavior. */
+    readonly readOnlyPageEval?: boolean;
     /** Send a raw CDP command scoped to this session's page. */
     sendCdp(method: string, params?: Record<string, unknown>): Promise<unknown>;
     /** Resolve once `method` (a CDP event) fires on this session's page, or

package/lib/authoring/tools.js

@@ -49,7 +49,10 @@ function globMatch(pattern, str) {
 }
 async function evalInPage(backend, expression) {
     const res = (await backend.sendCdp('Runtime.evaluate', {
-        expression, returnByValue: true, awaitPromise: true,
+        expression,
+        returnByValue: true,
+        awaitPromise: true,
+        ...(backend.readOnlyPageEval ? { throwOnSideEffect: true } : {}),
     }));
     if (res.exceptionDetails) {
         return {

package/lib/cdp/capture.d.ts

@@ -4,8 +4,8 @@
  * request/response bookkeeping lives in `capture-engine.ts`, shared with the
  * app's remote-Popcorn transport.
  */
-import type CDP from 'chrome-remote-interface';
 import { type CaptureSession, type StartCaptureOptions } from './capture-engine.ts';
+import type { CdpTabClient } from './client.ts';
 export { isStaticAsset, isStaticAssetMime, stripPseudoHeaders, } from './capture-engine.ts';
 export type { CaptureSession, StartCaptureOptions } from './capture-engine.ts';
-export declare function startCapture(tab: CDP.Client, opts?: StartCaptureOptions): Promise<CaptureSession>;
+export declare function startCapture(tab: CdpTabClient, opts?: StartCaptureOptions): Promise<CaptureSession>;

package/lib/cdp/capture.js

@@ -1,35 +1,39 @@
+/**
+ * Local-CDP transport for the capture engine. Binds the page-level `Network.*`
+ * events directly and fetches bodies via the page's `getResponseBody`. All the
+ * request/response bookkeeping lives in `capture-engine.ts`, shared with the
+ * app's remote-Popcorn transport.
+ */
 import { createCaptureEngine, } from "./capture-engine.js";
 export { isStaticAsset, isStaticAssetMime, stripPseudoHeaders, } from "./capture-engine.js";
 export async function startCapture(tab, opts = {}) {
     const engine = createCaptureEngine({
         ...(opts.maxBodyBytes !== undefined && { maxBodyBytes: opts.maxBodyBytes }),
-        fetchBody: (requestId) => tab.Network.getResponseBody({ requestId }),
-    });
-    const { Network } = tab;
-    await Network.enable();
-    Network.requestWillBeSent(engine.onRequestWillBeSent);
-    // 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 }) => {
-        engine.mergeRequestHeaders(requestId, headers);
-    });
-    Network.responseReceived(engine.onResponseReceived);
-    // Same privacy carve-out applies to `Set-Cookie` and other browser-
-    // visible response headers; they arrive on responseReceivedExtraInfo.
-    Network.responseReceivedExtraInfo(({ requestId, headers }) => {
-        engine.mergeResponseHeaders(requestId, headers);
-    });
-    Network.loadingFinished(({ requestId }) => {
-        void engine.onLoadingFinished(requestId);
+        fetchBody: tab.getResponseBody,
     });
+    const unsubscribe = [
+        tab.subscribe('Network.requestWillBeSent', engine.onRequestWillBeSent),
+        tab.subscribe('Network.requestWillBeSentExtraInfo', (event) => {
+            engine.mergeRequestHeaders(event.requestId, event.headers);
+        }),
+        tab.subscribe('Network.responseReceived', engine.onResponseReceived),
+        tab.subscribe('Network.responseReceivedExtraInfo', (event) => {
+            engine.mergeResponseHeaders(event.requestId, event.headers);
+        }),
+        tab.subscribe('Network.loadingFinished', (event) => {
+            void engine.onLoadingFinished(event.requestId);
+        }),
+    ];
+    await tab.send('Network.enable', {});
     return {
         captureId: engine.captureId,
         requests: engine.requests,
         bodies: engine.bodies,
         stop: async () => {
-            await Network.disable();
+            for (const stopListening of unsubscribe) {
+                stopListening();
+            }
+            await tab.send('Network.disable', {}).catch(() => { });
         },
     };
 }

package/lib/cdp/client.d.ts

@@ -1,9 +1,47 @@
 import CDP from 'chrome-remote-interface';
+import type { RequestWillBeSentLike, ResponseReceivedLike } from './capture-engine.ts';
+import type { TabInfo } from './tabs.ts';
+interface CdpTabEventMap {
+    'Network.requestWillBeSent': RequestWillBeSentLike;
+    'Network.requestWillBeSentExtraInfo': {
+        requestId: string;
+        headers: Record<string, string>;
+    };
+    'Network.responseReceived': ResponseReceivedLike & {
+        response: ResponseReceivedLike['response'] & {
+            url: string;
+        };
+    };
+    'Network.responseReceivedExtraInfo': {
+        requestId: string;
+        headers: Record<string, string>;
+    };
+    'Network.loadingFinished': {
+        requestId: string;
+    };
+}
+export interface CdpTabClient {
+    send: (method: string, params?: object) => Promise<unknown>;
+    getResponseBody: (requestId: string) => Promise<{
+        body: string;
+        base64Encoded: boolean;
+    }>;
+    subscribe: <K extends keyof CdpTabEventMap>(method: K, listener: (params: CdpTabEventMap[K]) => void) => () => void;
+    subscribeOnce: (method: string, listener: () => void) => () => void;
+    close: () => Promise<void>;
+}
 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>;
+    attachToTab: (targetId: string) => Promise<CdpTabClient>;
+    /** Enumerate page targets without assuming a localhost discovery endpoint. */
+    listTabs: () => Promise<TabInfo[]>;
     close: () => Promise<void>;
 }
 export declare function connectCdp(port: number): Promise<CdpHandles>;
+/** Connect to a browser-level or page-level CDP websocket. Browser-level
+ *  endpoints (including Popcorn) use flattened Target sessions; a page-level
+ *  custom endpoint is exposed as one synthetic tab and used directly. */
+export declare function connectCdpUrl(webSocketUrl: string): Promise<CdpHandles>;
+export {};

package/lib/cdp/client.js

@@ -1,11 +1,135 @@
 import CDP from 'chrome-remote-interface';
+import assert from 'node:assert';
+import { EventEmitter } from 'node:events';
+import { listTabs } from "./tabs.js";
+const DIRECT_TARGET_ID = '__direct_cdp_target__';
 export async function connectCdp(port) {
     const browser = await CDP({ port });
+    const tabs = new Set();
     return {
         browser,
-        attachToTab: (targetId) => CDP({ port, target: targetId }),
+        attachToTab: async (targetId) => {
+            const tab = adaptCdpClient(await CDP({ port, target: targetId }));
+            tabs.add(tab);
+            return tab;
+        },
+        listTabs: () => listTabs(port),
+        close: async () => {
+            for (const tab of tabs) {
+                await tab.close().catch(() => { });
+            }
+            await browser.close();
+        },
+    };
+}
+/** Connect to a browser-level or page-level CDP websocket. Browser-level
+ *  endpoints (including Popcorn) use flattened Target sessions; a page-level
+ *  custom endpoint is exposed as one synthetic tab and used directly. */
+export async function connectCdpUrl(webSocketUrl) {
+    const browser = await CDP({ target: webSocketUrl, local: true });
+    let browserLevel = true;
+    try {
+        await browser.send('Target.getTargets');
+    }
+    catch {
+        browserLevel = false;
+    }
+    const tabs = new Set();
+    const directTab = browserLevel ? undefined : adaptCdpClient(browser);
+    return {
+        browser,
+        listTabs: async () => {
+            if (!browserLevel) {
+                return [{
+                        tabId: DIRECT_TARGET_ID, url: '', title: 'Direct CDP target',
+                    }];
+            }
+            const { targetInfos } = await browser.send('Target.getTargets');
+            return targetInfos
+                .filter((target) => target.type === 'page')
+                .map((target) => ({
+                tabId: target.targetId,
+                url: target.url,
+                title: target.title,
+            }));
+        },
+        attachToTab: async (targetId) => {
+            if (!browserLevel) {
+                if (targetId !== DIRECT_TARGET_ID) {
+                    throw new Error(`Unknown direct CDP target ${targetId}`);
+                }
+                assert(directTab);
+                return directTab;
+            }
+            const { sessionId } = await browser.send('Target.attachToTarget', {
+                targetId,
+                flatten: true,
+            });
+            const tab = flattenedSessionClient(browser, sessionId);
+            tabs.add(tab);
+            return tab;
+        },
         close: async () => {
+            for (const tab of tabs) {
+                await tab.close().catch(() => { });
+            }
             await browser.close();
         },
     };
 }
+/** Adapt a flattened browser Target session to the small tab-client surface
+ *  consumed by capture and authoring. Events are filtered by session id so
+ *  concurrent tabs cannot observe each other's traffic. */
+function flattenedSessionClient(browser, sessionId) {
+    const events = new EventEmitter();
+    // The declaration only accepts literal protocol method names; this adapter
+    // deliberately forwards the shared authoring layer's dynamic method string.
+    const sender = browser.send.bind(browser);
+    const onEvent = (message) => {
+        if (message.sessionId !== sessionId) {
+            return;
+        }
+        events.emit('event', message);
+        events.emit(message.method, message.params);
+    };
+    browser.on('event', onEvent);
+    return tabClient(events, (method, params) => {
+        return sender(method, params ?? {}, sessionId);
+    }, (requestId) => {
+        return sender('Network.getResponseBody', { requestId }, sessionId);
+    }, async () => {
+        EventEmitter.prototype.removeListener.call(browser, 'event', onEvent);
+        await browser.send('Target.detachFromTarget', { sessionId }).catch(() => { });
+    });
+}
+function adaptCdpClient(client) {
+    const events = new EventEmitter();
+    const onEvent = (message) => {
+        events.emit(message.method, message.params);
+    };
+    client.on('event', onEvent);
+    // CRI intentionally types send against protocol literals. This adapter is
+    // the single boundary where shared authoring commands arrive dynamically.
+    const send = client.send.bind(client);
+    return tabClient(events, send, (requestId) => {
+        return client.send('Network.getResponseBody', { requestId });
+    }, async () => {
+        EventEmitter.prototype.removeListener.call(client, 'event', onEvent);
+        await client.close();
+    });
+}
+function tabClient(events, send, getResponseBody, close) {
+    return {
+        send,
+        getResponseBody,
+        subscribe(method, listener) {
+            events.on(method, listener);
+            return () => events.removeListener(method, listener);
+        },
+        subscribeOnce(method, listener) {
+            events.once(method, listener);
+            return () => events.removeListener(method, listener);
+        },
+        close,
+    };
+}

package/lib/consts.d.ts

@@ -44,6 +44,13 @@ export declare function useOldDevtools(): boolean;
  * `ConfigStore` (which would create an import cycle).
  */
 export declare function resolveOldMode(persisted?: 'old' | 'builder'): boolean;
+/**
+ * Where the effective mode came from — the same precedence as
+ * `resolveOldMode`: explicit `USE_OLD_DEVTOOLS` env var → persisted config
+ * `mode` → default (old). Surfaced by the `get_devtools_mode` tool so the
+ * user can tell why the server is in the mode it reports.
+ */
+export declare function oldModeSource(persisted?: 'old' | 'builder'): 'env' | 'config' | 'default';
 /** `%LOCALAPPDATA%` on Windows, used to probe a per-user Chrome install. */
 export declare function localAppData(): string | undefined;
 /** Explicit Chrome/Edge/Chromium binary path override. */

package/lib/consts.js

@@ -76,6 +76,21 @@ export function resolveOldMode(persisted) {
     }
     return true;
 }
+/**
+ * Where the effective mode came from — the same precedence as
+ * `resolveOldMode`: explicit `USE_OLD_DEVTOOLS` env var → persisted config
+ * `mode` → default (old). Surfaced by the `get_devtools_mode` tool so the
+ * user can tell why the server is in the mode it reports.
+ */
+export function oldModeSource(persisted) {
+    if (oldDevtoolsEnvSet()) {
+        return 'env';
+    }
+    if (persisted) {
+        return 'config';
+    }
+    return 'default';
+}
 // ---------------------------------------------------------------------------
 // Chrome / CDP launcher.
 // ---------------------------------------------------------------------------

package/lib/mcp/api/operations.gen.js

@@ -161,7 +161,7 @@ export const MCP_TOOLS = {
         }),
     },
     "AdminSessions": {
-        description: "Explore verification sessions (admin-only)\n\nAdmin only. Search verification sessions across all organizations — paste a session id, provider id, or consumer ETH address into `q`, optionally filter by `status`. Rows link to the org-scoped session detail page (admins can open any org's pages). Capped at 100, newest first.",
+        description: "Explore verification sessions (admin-only)\n\nAdmin only. Search verification sessions across all organizations — filter by `sessionId` (prefix match, at least 5 characters), `providerId`, `claimantClientId`, `orgId` (all exact match), `status`, and a `createdAfter`/`createdBefore` time range. Rows link to the org-scoped session detail page (admins can open any org's pages). Capped at 100, newest first.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -172,7 +172,19 @@ export const MCP_TOOLS = {
                 "query": {
                     "type": "object",
                     "properties": {
-                        "q": {
+                        "sessionId": {
+                            "type": "string",
+                            "maxLength": 100
+                        },
+                        "providerId": {
+                            "type": "string",
+                            "maxLength": 100
+                        },
+                        "claimantClientId": {
+                            "type": "string",
+                            "maxLength": 100
+                        },
+                        "orgId": {
                             "type": "string",
                             "maxLength": 100
                         },
@@ -186,6 +198,14 @@ export const MCP_TOOLS = {
                                 "error",
                                 "expired"
                             ]
+                        },
+                        "createdAfter": {
+                            "type": "string",
+                            "format": "date-time"
+                        },
+                        "createdBefore": {
+                            "type": "string",
+                            "format": "date-time"
                         }
                     }
                 },
@@ -589,9 +609,9 @@ export const MCP_TOOLS = {
                         },
                         "prompt": {
                             "type": "string",
-                            "description": "Extraction prompt, used (and required) when `verificationType` is `llm`.",
+                            "description": "Extraction prompt, used (and required) when `verificationType` is `llm`. Gated by the prompt guard before it is stored (docs/prompt-guard.md).",
                             "minLength": 0,
-                            "maxLength": 1000000
+                            "maxLength": 4000
                         },
                         "version": {
                             "type": "object",
@@ -1968,7 +1988,7 @@ export const MCP_TOOLS = {
         }),
     },
     "ListOrgVerificationSessions": {
-        description: "List an organization's verification sessions\n\nReturns verification sessions created under the organization, newest first. Optionally filter by `providerId`, `status`, `resolvedVersion`, `claimantClientId`, and a `createdAfter`/`createdBefore` time range. Caller must be an active member of the org. Opaque cursor pagination.\n\nNote: `status` filters on the stored column. A session that has passed `expiresAt` but has not yet been swept is reported as `expired` in its body while still stored as `pending`, so `status=expired` may not match such sessions until the sweep runs.",
+        description: "List an organization's verification sessions\n\nReturns verification sessions created under the organization, newest first. Optionally filter by `sessionId` (prefix match, at least 5 characters), `providerId`, `status`, `resolvedVersion`, `claimantClientId`, and a `createdAfter`/`createdBefore` time range. Caller must be an active member of the org. Opaque cursor pagination.\n\nNote: `status` filters on the stored column. A session that has passed `expiresAt` but has not yet been swept is reported as `expired` in its body while still stored as `pending`, so `status=expired` may not match such sessions until the sweep runs.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -1988,9 +2008,13 @@ export const MCP_TOOLS = {
                 "query": {
                     "type": "object",
                     "properties": {
+                        "sessionId": {
+                            "type": "string",
+                            "maxLength": 100
+                        },
                         "providerId": {
                             "type": "string",
-                            "format": "uuid"
+                            "maxLength": 100
                         },
                         "status": {
                             "type": "string",
@@ -2009,7 +2033,7 @@ export const MCP_TOOLS = {
                         },
                         "claimantClientId": {
                             "type": "string",
-                            "format": "uuid"
+                            "maxLength": 100
                         },
                         "createdAfter": {
                             "type": "string",
@@ -2849,9 +2873,9 @@ export const MCP_TOOLS = {
                         },
                         "prompt": {
                             "type": "string",
-                            "description": "Extraction prompt, used when `verificationType` is `llm`.",
+                            "description": "Extraction prompt, used when `verificationType` is `llm`. Gated by the prompt guard before it is stored (docs/prompt-guard.md).",
                             "minLength": 0,
-                            "maxLength": 1000000
+                            "maxLength": 4000
                         },
                         "requests": {
                             "type": "array",

package/lib/mcp/instructions.js

@@ -6,9 +6,28 @@
  * `lib/mcp` (published) — both are two levels below the package root.
  * Old-devtools mode has its own reduced set in `../old/instructions.ts`.
  */
+import assert from 'node:assert';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 export const BUILDER_MODE_INSTRUCTIONS = readFileSync(fileURLToPath(new URL('../../skill/builder-mode.md', import.meta.url)), 'utf8').trim();
+/**
+ * `SKILL.builder.md` and `SKILL.old.md` share a lot of prose (steps that are
+ * identical regardless of backend, "never do" rules, common troubleshooting).
+ * That shared text lives once in `skill/SKILL.common.md`, split into named
+ * `<!-- section: name -->`-delimited blocks; each mode file splices a block
+ * back in at `<!-- common: name -->`. Parsed once at module load.
+ */
+const COMMON_SECTIONS = parseCommonSections(readFileSync(fileURLToPath(new URL('../../skill/SKILL.common.md', import.meta.url)), 'utf8'));
+function parseCommonSections(text) {
+    const sections = {};
+    const re = /<!-- section: (\S+) -->\n([\s\S]*?)(?=\n<!-- section: |$)/g;
+    for (const match of text.matchAll(re)) {
+        // Trim blank LINES only, not inline indentation — some sections are
+        // list-continuation text that's intentionally indented on its first line.
+        sections[match[1]] = match[2].replace(/^\n+/, '').replace(/\n+$/, '');
+    }
+    return sections;
+}
 /**
  * The full provider-authoring guide — the deep capture→prove→publish workflow,
  * decision frameworks, and troubleshooting. Served on demand by the
@@ -19,9 +38,14 @@ export const BUILDER_MODE_INSTRUCTIONS = readFileSync(fileURLToPath(new URL('../
  * the instructions above; any leading frontmatter is stripped defensively.
  */
 function readGuide(file) {
-    return readFileSync(fileURLToPath(new URL(file, import.meta.url)), 'utf8')
-        .replace(/^---\n[\s\S]*?\n---\n/, '')
-        .trim();
+    const url = new URL(file, import.meta.url);
+    const raw = readFileSync(fileURLToPath(url), 'utf8');
+    const stripped = raw.replace(/^---\n[\s\S]*?\n---\n/, '').trim();
+    return stripped.replace(/<!-- common: (\S+) -->/g, (whole, name) => {
+        const section = COMMON_SECTIONS[name];
+        assert(section, `${file}: no SKILL.common.md section named "${name}"`);
+        return section;
+    });
 }
 export const PROVIDER_GUIDE_BUILDER = readGuide('../../skill/SKILL.builder.md');
 export const PROVIDER_GUIDE_OLD = readGuide('../../skill/SKILL.old.md');

package/lib/mcp/start.js

@@ -10,7 +10,7 @@ import { ReclaimSdkClient } from "../old/sdk-client.js";
 import { buildOldBackendTools } from "../old/tools/build.js";
 import { NAME, VERSION } from "../pkg.js";
 import { registerTools } from "./api/tools.js";
-import { buildAgentTools, buildCredentialTools, buildLocalCredentialTools, buildModeTools, buildVerificationTools, readSession, } from "./tools/index.js";
+import { buildAgentTools, buildBuilderAuthenticationTools, buildBuilderOrganizationTools, buildCredentialTools, buildLocalCredentialTools, buildModeTools, buildVerificationTools, readSession, } from "./tools/index.js";
 import { BUILDER_MODE_INSTRUCTIONS } from "./instructions.js";
 import { registerToolList } from "./server.js";
 export async function startMcpServer() {
@@ -28,6 +28,13 @@ export async function startMcpServer() {
     // deployments — set RECLAIM_AGENT_DISABLED=1 to register only the API
     // surface.
     const agentToolsEnabled = !agentDisabled();
+    const builderClient = new ReclaimClient({
+        baseUrl: apiUrl(),
+        // Builder access is orthogonal to publishing mode. A legacy-devtools
+        // session can authenticate here solely to allocate a remote browser.
+        token: apiToken() || readSession()?.token,
+        headers: { 'User-Agent': `${NAME}/${VERSION}` },
+    });
     // Backend-mode toggle — available in both modes and regardless of whether
     // the agent tools are enabled, so a user can always switch either direction.
     registerToolList(server, buildModeTools(config, oldMode));
@@ -42,21 +49,18 @@ export async function startMcpServer() {
             identity: resolveInitialIdentity(),
         });
         const sdkClient = new ReclaimSdkClient({ baseUrl: sdkApiUrl() });
+        registerToolList(server, buildBuilderAuthenticationTools(builderClient));
+        registerToolList(server, buildBuilderOrganizationTools(builderClient));
         registerToolList(server, buildLocalCredentialTools());
         registerToolList(server, buildOldBackendTools(oldClient, sdkClient));
         if (agentToolsEnabled) {
             // No builder client → no builder publish tool (old mode has its own).
-            registerToolList(server, buildAgentTools());
+            registerToolList(server, buildAgentTools(undefined, builderClient));
         }
         // NOTE: registerTools() is intentionally NOT called — generated tools off.
     }
     else {
-        const client = new ReclaimClient({
-            baseUrl: apiUrl(),
-            // Priority: explicit env var → cached session token → unauthenticated
-            token: apiToken() || readSession()?.token,
-            headers: { 'User-Agent': `${NAME}/${VERSION}` },
-        });
+        const client = builderClient;
         // Tool names must stay disjoint across these three groups: hand-written
         // tools are higher-level orchestrations (multi-call flows, ReclaimProvider
         // translation) and must NOT reuse a generated operation's snake_case name.

package/lib/mcp/tools/agent/attach.d.ts

@@ -1,11 +1,25 @@
-import { type CdpHandles } from '../../../cdp/client.ts';
+import type { ReclaimClient } from '@reclaimprotocol/client';
+import { type CdpHandles, connectCdp, connectCdpUrl } from '../../../cdp/client.ts';
 import type { ConfigStore } from '../../../config/store.ts';
 import { type RegisteredTool } from '../../server.ts';
+export type BrowserMode = 'dedicated' | 'attach' | 'builder' | 'custom';
 export interface AttachState {
     handles: CdpHandles;
-    port: number;
+    mode: BrowserMode;
+    port?: number;
+    liveViewUrl?: string;
+    browserSessionId?: string;
+    orgId?: string;
+    disposeRemote?: () => Promise<void>;
 }
-export declare function attachTool(state: {
+export interface AttachRef {
     current?: AttachState;
     config: ConfigStore;
-}): RegisteredTool;
+}
+interface AttachDependencies {
+    connectLocal: typeof connectCdp;
+    connectRemote: typeof connectCdpUrl;
+}
+export declare function attachTool(state: AttachRef, builderClient?: ReclaimClient, name?: 'attach_browser' | 'attach_chrome', beforeReplace?: () => Promise<void>, dependencies?: AttachDependencies): RegisteredTool;
+export declare function disposeAttached(state: AttachRef): Promise<void>;
+export {};