@reclaimprotocol/agent 0.1.17 → 0.1.20

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

@@ -26,4 +26,4 @@ export interface AgentState {
  *  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[];
+export declare function buildAgentTools(client?: ReclaimClient, builderClient?: ReclaimClient | undefined): RegisteredTool[];

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

@@ -13,7 +13,7 @@ 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";
@@ -30,14 +30,16 @@ function buildAgentState() {
  *  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) {
+export function buildAgentTools(client, builderClient = client) {
     const state = 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);

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/publish.js

@@ -13,6 +13,11 @@ const RESPONSE_MATCHES_SCHEMA = {
         properties: {
             type: { type: 'string', enum: ['regex', 'contains'] },
             value: { type: 'string' },
+            isOptional: {
+                type: 'boolean',
+                description: 'Mark this match non-fatal (verification continues when it ' +
+                    'fails). Default false.',
+            },
         },
         required: ['type', 'value'],
     },
@@ -44,6 +49,12 @@ const REQUEST_DRAFT_PROPERTIES = {
     },
     method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH'] },
     body: { type: 'string', description: 'Request body template, if any.' },
+    credentials: {
+        type: 'string',
+        enum: ['omit', 'same-origin', 'include'],
+        description: 'How the verification client supplies cookies/auth when replaying ' +
+            'this request. Default `include`.',
+    },
     responseMatches: RESPONSE_MATCHES_SCHEMA,
     responseRedactions: RESPONSE_REDACTIONS_SCHEMA,
 };
@@ -170,9 +181,51 @@ 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: {
+                    type: 'object',
+                    description: 'In-app interception settings, stored as ' +
+                        'webSettings.clientOptions.inapp.interceptorOptions. ' +
+                        '`isDocumentRequestReplayEnabled` is the INVERSE of ' +
+                        'old-devtools\' `disableRequestReplay`: true replays the ' +
+                        'main document request via the attestor (default false).',
+                    properties: {
+                        interceptorType: {
+                            type: 'string',
+                            enum: ['HAWKEYE', 'MSWJS', 'CDP'],
+                            description: 'How traffic interception is implemented.',
+                        },
+                        isDocumentRequestReplayEnabled: { type: 'boolean' },
+                        interceptorSettings: {
+                            type: 'string',
+                            description: 'Free-form JSON config for the chosen interceptor.',
+                        },
+                    },
+                    required: ['interceptorType'],
+                },
             },
             required: ['providerId', 'initialUrl'],
         },
@@ -192,6 +245,7 @@ export function createVersionFromCaptureTool(client) {
             version: ver,
             jsUserScripts: args.jsUserScripts,
             allowedJsRequests: args.allowedJsRequests,
+            interceptorOptions: args.interceptorOptions,
         });
         const result = await client.call('CreateProviderVersion', {
             params: { providerId: args.providerId },

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' +

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";

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

@@ -1,8 +1,9 @@
 import type { ConfigStore } from '../../../config/store.ts';
 import { type RegisteredTool } from '../../server.ts';
 /**
- * The `set_devtools_mode` tool: persist which backend the MCP server targets
- * (legacy `old` devtools vs the new `builder`). The choice is written to
+ * The `set_devtools_mode` / `get_devtools_mode` tools: persist which backend
+ * the MCP server targets (`old` devtools vs the `builder`), and
+ * report the mode currently in effect. The choice is written to
  * `~/.reclaim/config.json` and applied the NEXT time the server starts —
  * the registered tool set, server instructions, and backend client are all
  * fixed at connect time, so the switch requires a restart/reconnect. Follows

package/lib/mcp/tools/mode/mode.js

@@ -1,8 +1,10 @@
 import { defaultConfigPath } from "../../../config/store.js";
+import { oldModeSource } from "../../../consts.js";
 import { defineTool } from "../../server.js";
 /**
- * The `set_devtools_mode` tool: persist which backend the MCP server targets
- * (legacy `old` devtools vs the new `builder`). The choice is written to
+ * The `set_devtools_mode` / `get_devtools_mode` tools: persist which backend
+ * the MCP server targets (`old` devtools vs the `builder`), and
+ * report the mode currently in effect. The choice is written to
  * `~/.reclaim/config.json` and applied the NEXT time the server starts —
  * the registered tool set, server instructions, and backend client are all
  * fixed at connect time, so the switch requires a restart/reconnect. Follows
@@ -18,8 +20,8 @@ export function buildModeTools(config, currentOldMode) {
     return [
         defineTool({
             name: 'set_devtools_mode',
-            description: 'Choose which backend the MCP server targets: "old" (legacy '
-                + 'Reclaim devtools) or "builder" (the new builder backend). '
+            description: 'Choose which backend the MCP server targets: "old" (devtools) '
+                + 'or "builder" (the builder backend). '
                 + 'Persists the choice to ~/.reclaim/config.json; it takes effect '
                 + 'the next time the MCP server starts, so restart/reconnect after '
                 + 'switching. An explicit USE_OLD_DEVTOOLS env var overrides this.',
@@ -45,5 +47,23 @@ export function buildModeTools(config, currentOldMode) {
                     : `Already running in "${parsed.mode}" mode; nothing to restart.`,
             };
         }),
+        defineTool({
+            name: 'get_devtools_mode',
+            description: 'Report which backend this MCP server is currently targeting: '
+                + '"old" (devtools) or "builder" (the builder '
+                + 'backend). Also reports WHY that mode is in effect (source: '
+                + 'a USE_OLD_DEVTOOLS env override, the persisted config, or '
+                + 'the default) and which mode is persisted for the next '
+                + 'start. Use set_devtools_mode to change it.',
+            inputSchema: { type: 'object', properties: {} },
+        }, async () => {
+            const persisted = config.read()?.mode;
+            return {
+                mode: current,
+                source: oldModeSource(persisted),
+                persistedMode: persisted ?? null,
+                configPath: defaultConfigPath(),
+            };
+        }),
     ];
 }