@reclaimprotocol/agent 0.1.18 → 0.1.21

package/lib/mcp/tools/agent/attach.js

@@ -1,72 +1,162 @@
-import { connectCdp } from "../../../cdp/client.js";
+import { badRequest } from '@hapi/boom';
+import assert from 'node:assert';
+import { connectCdp, connectCdpUrl, } from "../../../cdp/client.js";
 import { defaultProfileDir, launchChrome, waitForCdpReady, } from "../../../cdp/launcher.js";
 import { defaultConfigPath } from "../../../config/store.js";
 import { defineTool } from "../../server.js";
-export function attachTool(state) {
+const DEFAULT_DEPENDENCIES = {
+    connectLocal: connectCdp,
+    connectRemote: connectCdpUrl,
+};
+export function attachTool(state, builderClient, name = 'attach_browser', beforeReplace, dependencies = DEFAULT_DEPENDENCIES) {
     return defineTool({
-        name: 'attach_chrome',
-        description: 'Attach to a Chrome instance via CDP. ' +
-            'Auto-launches a dedicated-profile Chrome ' +
-            'on first call if no attachMode is persisted. ' +
-            'Persists the chosen mode in ~/.reclaim/config.json.',
+        name,
+        description: name === 'attach_chrome'
+            ? 'Backward-compatible alias for attach_browser.'
+            : 'Connect the provider-authoring tools to a browser. Choose '
+                + 'dedicated (launch local Chrome), attach (existing local CDP '
+                + 'port), builder (quota-accounted Popcorn browser with a '
+                + 'shareable live view), or custom (caller-supplied CDP '
+                + 'websocket). '
+                + 'Builder and custom CDP credentials are held in memory and never '
+                + 'returned.',
         inputSchema: {
             type: 'object',
             properties: {
-                attachMode: { type: 'string', enum: ['dedicated', 'attach'] },
-                port: { type: 'number' },
+                mode: {
+                    type: 'string',
+                    enum: ['dedicated', 'attach', 'builder', 'custom'],
+                },
+                attachMode: {
+                    type: 'string',
+                    enum: ['dedicated', 'attach'],
+                    description: 'Deprecated local-mode alias for mode.',
+                },
+                port: { type: 'number', minimum: 1, maximum: 65535 },
+                orgId: { type: 'string', format: 'uuid' },
+                cdpUrl: { type: 'string', maxLength: 4000 },
+                liveViewUrl: { type: 'string', format: 'uri', maxLength: 4000 },
             },
         },
     }, async (parsed) => {
-        let cfg = state.config.read()?.browser_agent;
-        if (parsed.attachMode || parsed.port) {
-            cfg = {
-                attachMode: parsed.attachMode ?? cfg?.attachMode ?? 'dedicated',
-                port: parsed.port ?? cfg?.port ?? 9222,
-            };
-            state.config.write({ browser_agent: cfg });
-        }
-        if (!cfg) {
+        const persisted = state.config.read()?.browser_agent;
+        const mode = parsed.mode ?? parsed.attachMode ?? persisted?.attachMode;
+        if (!mode) {
             return {
                 needsChoice: true,
-                message: 'First-run: choose attach mode. ' +
-                    'Call attach_chrome again with attachMode="dedicated" ' +
-                    '(auto-launch a Chrome profile under ~/.reclaim/chrome-profile) ' +
-                    'or attachMode="attach" ' +
-                    '(connect to a Chrome you launched yourself with ' +
-                    'BOTH --remote-debugging-port=9222 AND ' +
-                    '--user-data-dir=<some-non-default-path>; ' +
-                    'since Chrome 136 the debug-port flag is silently ' +
-                    'ignored if the default profile is in use).',
+                message: 'Choose a browser mode and call attach_browser again: '
+                    + '"dedicated" launches a local dedicated Chrome profile; '
+                    + '"attach" connects to a local Chrome debugging port; '
+                    + '"builder" creates a quota-accounted remote browser and '
+                    + 'requires orgId; "custom" requires a CDP websocket URL.',
                 configPath: defaultConfigPath(),
             };
         }
-        if (cfg.attachMode === 'dedicated') {
-            try {
-                await waitForCdpReady(cfg.port, 500);
-            }
-            catch {
-                launchChrome({ port: cfg.port, profileDir: defaultProfileDir() });
-                await waitForCdpReady(cfg.port, 10000);
-            }
+        const next = await connect(mode, parsed, persisted, builderClient, dependencies);
+        try {
+            await beforeReplace?.();
+            await disposeAttached(state);
         }
-        else {
-            await waitForCdpReady(cfg.port, 2000).catch(() => {
-                throw new Error(`attach mode: nothing answering CDP on port ${cfg.port}. ` +
-                    'Chrome must be launched with BOTH ' +
-                    `--remote-debugging-port=${cfg.port} AND ` +
-                    '--user-data-dir=<some-non-default-path>. ' +
-                    'Since Chrome 136 (May 2025), the debug-port flag is ' +
-                    'silently ignored when the default ' +
-                    "user profile is in use — that's why nothing opens the port. " +
-                    'Either re-launch Chrome with ' +
-                    'a custom --user-data-dir, or switch to attachMode="dedicated".');
-            });
+        catch (err) {
+            await disposeState(next).catch(() => { });
+            throw err;
         }
-        if (state.current) {
-            await state.current.handles.close().catch(() => { });
+        state.current = next;
+        if (mode === 'dedicated' || mode === 'attach') {
+            state.config.write({
+                browser_agent: { attachMode: mode, port: next.port },
+            });
         }
-        const handles = await connectCdp(cfg.port);
-        state.current = { handles, port: cfg.port };
-        return { attached: true, port: cfg.port, mode: cfg.attachMode };
+        return {
+            attached: true,
+            mode,
+            ...(next.port ? { port: next.port } : {}),
+            ...(next.browserSessionId
+                ? { browserSessionId: next.browserSessionId }
+                : {}),
+            ...(next.liveViewUrl ? { liveViewUrl: next.liveViewUrl } : {}),
+        };
     });
 }
+export async function disposeAttached(state) {
+    const current = state.current;
+    if (!current) {
+        return;
+    }
+    delete state.current;
+    await disposeState(current);
+}
+async function connect(mode, parsed, persisted, builderClient, dependencies) {
+    if (mode === 'builder') {
+        assert(builderClient, badRequest('Builder browser service is unavailable'));
+        assert(parsed.orgId, badRequest('orgId is required for builder mode'));
+        const { data } = await builderClient.call('CreateAgentBrowserSession', {
+            params: { orgId: parsed.orgId },
+        });
+        let handles;
+        try {
+            handles = await dependencies.connectRemote(data.cdpUrl);
+        }
+        catch (err) {
+            await builderClient.call('DisposeAgentBrowserSession', {
+                params: {
+                    orgId: parsed.orgId,
+                    browserSessionId: data.id,
+                },
+            }).catch(() => { });
+            throw err;
+        }
+        return {
+            handles,
+            mode,
+            liveViewUrl: data.liveViewUrl,
+            browserSessionId: data.id,
+            orgId: parsed.orgId,
+            disposeRemote: async () => {
+                await builderClient.call('DisposeAgentBrowserSession', {
+                    params: {
+                        orgId: parsed.orgId,
+                        browserSessionId: data.id,
+                    },
+                });
+            },
+        };
+    }
+    if (mode === 'custom') {
+        assert(parsed.cdpUrl, badRequest('cdpUrl is required for custom mode'));
+        const url = new URL(parsed.cdpUrl);
+        assert(url.protocol === 'ws:' || url.protocol === 'wss:', badRequest('cdpUrl must use ws:// or wss://'));
+        return {
+            handles: await dependencies.connectRemote(parsed.cdpUrl),
+            mode,
+            ...(parsed.liveViewUrl ? { liveViewUrl: parsed.liveViewUrl } : {}),
+        };
+    }
+    const port = parsed.port ?? persisted?.port ?? 9222;
+    if (mode === 'dedicated') {
+        try {
+            await waitForCdpReady(port, 500);
+        }
+        catch {
+            launchChrome({ port, profileDir: defaultProfileDir() });
+            await waitForCdpReady(port, 10000);
+        }
+    }
+    else {
+        await waitForCdpReady(port, 2000).catch(() => {
+            throw new Error(`attach mode: nothing answering CDP on port ${port}. Chrome must `
+                + `be launched with --remote-debugging-port=${port} AND `
+                + '--user-data-dir=<some-non-default-path>. Chrome 136+ ignores '
+                + 'the debugging flag for the default profile.');
+        });
+    }
+    return { handles: await dependencies.connectLocal(port), mode, port };
+}
+async function disposeState(state) {
+    try {
+        await state.handles.close();
+    }
+    finally {
+        await state.disposeRemote?.();
+    }
+}

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

@@ -21,9 +21,16 @@ export interface AgentState {
     };
     captures: CaptureStore;
 }
+/** Exported so a mode (e.g. old-devtools) that supplies its own publish tool
+ *  can build the attach/capture state up front and share the SAME instance
+ *  with `buildAgentTools` — letting that publish tool see the live attach
+ *  state (e.g. to remind the caller about a still-open browser session). */
+export declare function buildAgentState(): AgentState;
 /** Build the flat list of `RegisteredTool` entries, ready for
  *  `registerToolList`.
  *  Pass `client` to include the builder `create_provider_version_from_capture`;
  *  omit it (e.g. OLD-devtools mode) to register only the backend-independent
- *  capture/proof tools — old mode supplies its own publish tool. */
-export declare function buildAgentTools(client?: ReclaimClient): RegisteredTool[];
+ *  capture/proof tools — old mode supplies its own publish tool.
+ *  Pass `externalState` to share attach/capture state with tools registered
+ *  elsewhere (e.g. old mode's publish tool) instead of building a fresh one. */
+export declare function buildAgentTools(client?: ReclaimClient, builderClient?: ReclaimClient | undefined, externalState?: AgentState): RegisteredTool[];

package/lib/mcp/tools/agent/build.js

@@ -13,13 +13,17 @@ import { ConfigStore } from "../../../config/store.js";
 import { ensureAttestorCrypto } from "../../../proof/proof-core.js";
 import { analyzeTool } from "./analyze.js";
 import { attachTool } from "./attach.js";
-import { captureTools } from "./capture.js";
+import { captureTools, resetCaptures } from "./capture.js";
 import { listTabsTool } from "./eval.js";
 import { howItWorksTool } from "./how-it-works.js";
 import { createVersionFromCaptureTool } from "./publish.js";
 import { sessionTools } from "./session.js";
 import { sharedAuthoringTools } from "./shared.js";
-function buildAgentState() {
+/** Exported so a mode (e.g. old-devtools) that supplies its own publish tool
+ *  can build the attach/capture state up front and share the SAME instance
+ *  with `buildAgentTools` — letting that publish tool see the live attach
+ *  state (e.g. to remind the caller about a still-open browser session). */
+export function buildAgentState() {
     return {
         attach: { config: new ConfigStore() },
         captures: { sessions: new Map() },
@@ -29,15 +33,19 @@ function buildAgentState() {
  *  `registerToolList`.
  *  Pass `client` to include the builder `create_provider_version_from_capture`;
  *  omit it (e.g. OLD-devtools mode) to register only the backend-independent
- *  capture/proof tools — old mode supplies its own publish tool. */
-export function buildAgentTools(client) {
-    const state = buildAgentState();
+ *  capture/proof tools — old mode supplies its own publish tool.
+ *  Pass `externalState` to share attach/capture state with tools registered
+ *  elsewhere (e.g. old mode's publish tool) instead of building a fresh one. */
+export function buildAgentTools(client, builderClient = client, externalState) {
+    const state = externalState ?? buildAgentState();
     ensureAttestorCrypto();
     const tools = [];
     // Stateless docs tool — serve the mode-specific authoring guide to any
     // client. No `client` ⇒ old-devtools mode (see `mcp/start.ts`).
     tools.push(howItWorksTool(!client));
-    tools.push(attachTool(state.attach));
+    const beforeReplace = () => resetCaptures(state.captures);
+    tools.push(attachTool(state.attach, builderClient, 'attach_browser', beforeReplace));
+    tools.push(attachTool(state.attach, builderClient, 'attach_chrome', beforeReplace));
     tools.push(listTabsTool(state.attach));
     for (const t of captureTools(state.attach, state.captures)) {
         tools.push(t);
@@ -53,7 +61,7 @@ export function buildAgentTools(client) {
         tools.push(t);
     }
     if (client) {
-        tools.push(createVersionFromCaptureTool(client));
+        tools.push(createVersionFromCaptureTool(client, state.attach));
     }
     return tools;
 }

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

@@ -17,6 +17,7 @@ export interface CaptureStore {
     sessions: Map<string, CaptureEntry>;
     activeTab?: string;
 }
+export declare function resetCaptures(captures: CaptureStore): Promise<void>;
 export declare function captureTools(attachRef: {
     current?: AttachState;
 }, captures: CaptureStore): RegisteredTool[];

package/lib/mcp/tools/agent/capture.js

@@ -1,10 +1,17 @@
 import { makeDraftStore } from "../../../authoring/index.js";
 import { startCapture } from "../../../cdp/capture.js";
 import { defineTool } from "../../server.js";
+export async function resetCaptures(captures) {
+    for (const entry of captures.sessions.values()) {
+        await entry.session.stop().catch(() => { });
+    }
+    captures.sessions.clear();
+    delete captures.activeTab;
+}
 export function captureTools(attachRef, captures) {
     const requireAttached = () => {
         if (!attachRef.current) {
-            throw new Error('Not attached. Call attach_chrome first.');
+            throw new Error('Not attached. Call attach_browser first.');
         }
         return attachRef.current;
     };

package/lib/mcp/tools/agent/eval.js

@@ -1,4 +1,3 @@
-import { listTabs } from "../../../cdp/tabs.js";
 import { defineTool } from "../../server.js";
 /** The one browser tool that isn't session-bound: enumerate tabs so the caller
  *  can pick one to `start_capture` on. Navigate/eval/wait are the shared
@@ -10,8 +9,8 @@ export function listTabsTool(attachRef) {
         inputSchema: { type: 'object', properties: {} },
     }, async () => {
         if (!attachRef.current) {
-            throw new Error('Not attached. Call attach_chrome first.');
+            throw new Error('Not attached. Call attach_browser first.');
         }
-        return { tabs: await listTabs(attachRef.current.port) };
+        return { tabs: await attachRef.current.handles.listTabs() };
     });
 }

package/lib/mcp/tools/agent/how-it-works.d.ts

@@ -6,6 +6,6 @@ import { type RegisteredTool } from '../../server.ts';
  * so any MCP client — not just Claude Code, which alone auto-loads skills — can
  * pull it. `oldMode` selects the backend-specific guide so the agent is never
  * told to call auth/publish tools that aren't registered in its mode.
- * Stateless: callable before `attach_chrome`.
+ * Stateless: callable before `attach_browser`.
  */
 export declare function howItWorksTool(oldMode: boolean): RegisteredTool;

package/lib/mcp/tools/agent/how-it-works.js

@@ -7,7 +7,7 @@ import { defineTool } from "../../server.js";
  * so any MCP client — not just Claude Code, which alone auto-loads skills — can
  * pull it. `oldMode` selects the backend-specific guide so the agent is never
  * told to call auth/publish tools that aren't registered in its mode.
- * Stateless: callable before `attach_chrome`.
+ * Stateless: callable before `attach_browser`.
  */
 export function howItWorksTool(oldMode) {
     const guide = oldMode ? PROVIDER_GUIDE_OLD : PROVIDER_GUIDE_BUILDER;

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

@@ -1,2 +1,2 @@
-export { buildAgentTools } from './build.ts';
+export { buildAgentState, buildAgentTools } from './build.ts';
 export type { AgentState } from './build.ts';

package/lib/mcp/tools/agent/index.js

@@ -1,3 +1,3 @@
 // Barrel for the agent tool group (Chrome CDP capture, provider synthesis,
 // replay, zkTLS proof). Import from here, not the individual files.
-export { buildAgentTools } from "./build.js";
+export { buildAgentState, buildAgentTools } from "./build.js";

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

@@ -1,3 +1,6 @@
 import type { ReclaimClient } from '@reclaimprotocol/client';
 import { type RegisteredTool } from '../../server.ts';
-export declare function createVersionFromCaptureTool(client: ReclaimClient): RegisteredTool;
+import type { AttachState } from './attach.ts';
+export declare function createVersionFromCaptureTool(client: ReclaimClient, attachRef?: {
+    current?: AttachState;
+}): RegisteredTool;

package/lib/mcp/tools/agent/publish.js

@@ -97,7 +97,7 @@ const ALLOWED_JS_REQUEST_SCHEMA = {
     },
     required: ['url', 'method'],
 };
-export function createVersionFromCaptureTool(client) {
+export function createVersionFromCaptureTool(client, attachRef) {
     return defineTool({
         name: 'create_provider_version_from_capture',
         description: 'Persist drafted ReclaimProvider(s) as a provider version. ' +
@@ -125,7 +125,11 @@ export function createVersionFromCaptureTool(client) {
             'sessions (verification matches those values exactly; a missing ' +
             'field is a 400 at session create). ' +
             'Refine types/descriptions via `update_provider_version` while ' +
-            'still on draft.',
+            'still on draft. ' +
+            'On success, if a browser is still attached, the response\'s ' +
+            '`_notes` reminds you to confirm with the developer before ' +
+            'calling `dispose_browser` — never close it unprompted, they ' +
+            'may want it for further edits.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -181,7 +185,28 @@ export function createVersionFromCaptureTool(client) {
                     type: 'array',
                     description: 'Extra requests the injection script is allowed to fire ' +
                         '(e.g. paginated API calls), as RequestSelectionTemplates. ' +
-                        '`multiple`/`required` default to true.',
+                        '`multiple`/`required` default to true. ' +
+                        '⚠️ BEFORE populating this to gate ' +
+                        '`verifyProof(proof, { providerId })` (old-devtools calls the ' +
+                        'same concept `allowedInjectedRequestData` — same mechanics, ' +
+                        'different field name): this whole entry (url, method, body, ' +
+                        'responseMatches, responseRedactions) feeds a client-side ' +
+                        'hash-equality check, and `url` is hashed VERBATIM — no regex/ ' +
+                        'template resolution, even with `urlType: REGEX` or ' +
+                        '`TEMPLATE`. If the real captured URL contains ANY per-session ' +
+                        'part (a tracking nonce, CSRF token, cache-busting timestamp), ' +
+                        'no declared spec can EVER hash-match a real proof — populating' +
+                        ' this for such a provider makes verifyProof reject every real ' +
+                        'proof, which is worse than leaving it empty. Diff the same ' +
+                        'endpoint\'s captured URL across two separate sessions before ' +
+                        'wiring this up. If provider-hash validation keeps causing ' +
+                        'problems (unstable url, or any other persistent mismatch), ' +
+                        'the fallback on the verifying side is `verifyProof(proof, { ' +
+                        'dangerouslyDisableContentValidation: true })` — trusts only ' +
+                        'the attestor\'s signature, skips the hash-equality check ' +
+                        'entirely; see the "Provider-hash validation" section of the ' +
+                        'injection script\'s guide for the full mechanics and when to ' +
+                        'reach for it.',
                     items: ALLOWED_JS_REQUEST_SCHEMA,
                 },
                 interceptorOptions: {
@@ -240,6 +265,20 @@ export function createVersionFromCaptureTool(client) {
             ...(args.allowedJsRequests ?? []).map((r, i) => countsFor(`Injected request ${i + 1}`, r)),
         ];
         notes.push(...matchRedactionWarnings(requestCounts));
+        // A browser session left attached after a successful publish is easy
+        // to forget about — surface it so the caller asks the developer
+        // before closing it (a builder-mode session is quota-accounted and
+        // otherwise just sits until its TTL expires).
+        const attached = attachRef?.current;
+        if (attached) {
+            notes.push(`A "${attached.mode}" browser session is still attached` +
+                (attached.browserSessionId
+                    ? ` (browserSessionId: ${attached.browserSessionId})`
+                    : '') +
+                '. Ask the developer whether they want to keep it open for ' +
+                'further edits — only call dispose_browser once they confirm ' +
+                'they\'re done with it.');
+        }
         // Let the dev know how/when the script runs (and the window.Reclaim gap).
         if (args.jsUserScripts?.trim()) {
             notes.push('jsUserScripts will run in the Builder verification client before ' +

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

@@ -1,7 +1,7 @@
 import type { ConfigStore } from '../../../config/store.ts';
 import { type RegisteredTool } from '../../server.ts';
-import type { AttachState } from './attach.ts';
-import type { CaptureStore } from './capture.ts';
+import { type AttachState } from './attach.ts';
+import { type CaptureStore } from './capture.ts';
 export declare function sessionTools(attachRef: {
     current?: AttachState;
     config: ConfigStore;

package/lib/mcp/tools/agent/session.js

@@ -1,4 +1,6 @@
 import { defineTool } from "../../server.js";
+import { disposeAttached } from "./attach.js";
+import { resetCaptures } from "./capture.js";
 export function sessionTools(attachRef, captures) {
     return [
         defineTool({
@@ -8,22 +10,36 @@ export function sessionTools(attachRef, captures) {
         }, async () => ({
             config: attachRef.config.read()?.browser_agent,
             attached: Boolean(attachRef.current),
+            mode: attachRef.current?.mode,
             port: attachRef.current?.port,
+            liveViewUrl: attachRef.current?.liveViewUrl,
+            browserSessionId: attachRef.current?.browserSessionId,
+            orgId: attachRef.current?.orgId,
             captures: [...captures.sessions.keys()],
             activeTab: captures.activeTab,
         })),
+        defineTool({
+            name: 'dispose_browser',
+            description: 'Stop captures, disconnect the current browser, and immediately '
+                + 'delete a Builder-hosted Popcorn session. Custom CDP sessions '
+                + 'are disconnected but never deleted by Reclaim.',
+            inputSchema: { type: 'object', properties: {} },
+        }, async () => {
+            await resetAll(attachRef, captures);
+            return { disposed: true };
+        }),
         defineTool({
             name: 'reset_session',
             description: 'Stop all captures and clear capture state — drops every '
                 + 'session\'s drafts and their in-memory secrets.',
             inputSchema: { type: 'object', properties: {} },
         }, async () => {
-            for (const entry of captures.sessions.values()) {
-                await entry.session.stop().catch(() => { });
-            }
-            captures.sessions.clear();
-            delete captures.activeTab;
+            await resetAll(attachRef, captures);
             return { reset: true };
         }),
     ];
 }
+async function resetAll(attachRef, captures) {
+    await resetCaptures(captures);
+    await disposeAttached(attachRef);
+}

package/lib/mcp/tools/agent/shared.js

@@ -42,14 +42,12 @@ function withLocalOprfMode(provider) {
  *  captured requests, prove via the in-process attestor, replay by re-fetch. */
 function localBackend(entry) {
     const { tabClient, session, drafts } = entry;
-    // The per-tab CDP client is strongly typed to `keyof Commands`; the shared
-    // tools drive it with dynamic method/event names, so view it as string-keyed.
-    const client = tabClient;
     return {
         capture: session,
         drafts,
-        sendCdp: (method, params) => client.send(method, params ?? {}),
+        sendCdp: (method, params) => tabClient.send(method, params ?? {}),
         waitForEvent: (method, timeoutMs) => new Promise((resolve) => {
+            let stopListening = () => { };
             const onEvent = () => {
                 cleanup();
                 resolve('fired');
@@ -60,9 +58,9 @@ function localBackend(entry) {
             }, timeoutMs);
             const cleanup = () => {
                 clearTimeout(timer);
-                client.removeListener(method, onEvent);
+                stopListening();
             };
-            client.once(method, onEvent);
+            stopListening = tabClient.subscribeOnce(method, onEvent);
         }),
         replay: async (draft, opts) => {
             // Auth-bound check: re-fetch with the secrets dropped. replayProvider

package/lib/mcp/tools/authenticate/authenticate.d.ts

@@ -1,3 +1,3 @@
 import type { ReclaimClient } from '@reclaimprotocol/client';
 import { type RegisteredTool } from '../../server.ts';
-export declare function authenticateTool(client: ReclaimClient): RegisteredTool;
+export declare function authenticateTool(client: ReclaimClient, name?: 'reclaim_authenticate' | 'authenticate_builder'): RegisteredTool;

package/lib/mcp/tools/authenticate/authenticate.js

@@ -6,11 +6,17 @@ import { defineTool } from "../../server.js";
 import { writeSession } from "./session-cache.js";
 const SCOPE = 'openid profile email';
 const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000;
-export function authenticateTool(client) {
+export function authenticateTool(client, name = 'reclaim_authenticate') {
     return defineTool({
-        name: 'reclaim_authenticate',
-        description: 'Authorize the CLI / MCP to make authenticated API calls. Opens the ' +
-            'browser to the builder sign-in page (standard OAuth 2.0 ' +
+        name,
+        description: (name === 'authenticate_builder'
+            ? 'Authenticate specifically with Builder. Available regardless '
+                + 'of '
+                + 'the selected publishing backend. '
+            : '')
+            + 'Authorize the CLI / MCP to make authenticated API calls. Opens '
+            + 'the '
+            + 'browser to the builder sign-in page (standard OAuth 2.0 ' +
             'authorization-code + PKCE with a localhost redirect) and waits for ' +
             'the user to sign in and approve. On success the access token is ' +
             'cached in ~/.reclaim/config.json and activated for this session.\n\n' +
@@ -164,8 +170,9 @@ async function exchangeCode(authBase, opts) {
             client_id: opts.clientId,
         }).toString(),
     });
-    assert(res.ok, new Error(`Token exchange failed (${res.status}): ${await res.text()}`));
-    const json = (await res.json());
+    const body = await res.text();
+    assert(res.ok, new Error(`Token exchange failed (${res.status}): ${body}`));
+    const json = JSON.parse(body);
     assert(json.access_token, new Error('Token exchange returned no access_token.'));
     return {
         access_token: json.access_token,

package/lib/mcp/tools/authenticate/builder-access.d.ts

@@ -0,0 +1,8 @@
+import type { ReclaimClient } from '@reclaimprotocol/client';
+import { type RegisteredTool } from '../../server.ts';
+/** Legacy-devtools mode needs a distinct Builder login solely for allocating
+ * quota-accounted Popcorn sessions. Builder mode uses its native auth tool. */
+export declare function buildBuilderAuthenticationTools(client: ReclaimClient): RegisteredTool[];
+/** Legacy-devtools mode lacks generated Builder API tools, so it needs this
+ * narrow organization-discovery bridge for remote-browser allocation. */
+export declare function buildBuilderOrganizationTools(client: ReclaimClient): RegisteredTool[];

package/lib/mcp/tools/authenticate/builder-access.js

@@ -0,0 +1,31 @@
+import { defineTool } from "../../server.js";
+import { authenticateTool } from "./authenticate.js";
+/** Legacy-devtools mode needs a distinct Builder login solely for allocating
+ * quota-accounted Popcorn sessions. Builder mode uses its native auth tool. */
+export function buildBuilderAuthenticationTools(client) {
+    return [authenticateTool(client, 'authenticate_builder')];
+}
+/** Legacy-devtools mode lacks generated Builder API tools, so it needs this
+ * narrow organization-discovery bridge for remote-browser allocation. */
+export function buildBuilderOrganizationTools(client) {
+    return [
+        defineTool({
+            name: 'list_builder_organizations',
+            description: 'List organizations available to the authenticated Builder user. '
+                + 'Use an organization id from this result when calling '
+                + 'attach_browser with mode="builder". Available only in '
+                + 'legacy-devtools publishing mode; Builder mode uses list_orgs.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    cursor: { type: 'string', maxLength: 500 },
+                },
+            },
+        }, async ({ cursor }) => {
+            const { data } = await client.call('ListOrgs', {
+                query: { ...(cursor ? { cursor } : {}) },
+            });
+            return data;
+        }),
+    ];
+}

package/lib/mcp/tools/authenticate/index.d.ts

@@ -1,2 +1,3 @@
+export { buildBuilderAuthenticationTools, buildBuilderOrganizationTools, } from './builder-access.ts';
 export { buildCredentialTools, buildLocalCredentialTools } from './build.ts';
 export { readSession } from './session-cache.ts';

package/lib/mcp/tools/authenticate/index.js

@@ -1,4 +1,5 @@
 // Barrel for the credential tool group: local eth proof-owner key (env/PEM)
 // and the org-token-authenticated builder tools. Import from here.
+export { buildBuilderAuthenticationTools, buildBuilderOrganizationTools, } from "./builder-access.js";
 export { buildCredentialTools, buildLocalCredentialTools } from "./build.js";
 export { readSession } from "./session-cache.js";