@reclaimprotocol/agent 0.1.18 → 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

@@ -181,7 +181,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: {

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/old/login-cdp.js

@@ -113,15 +113,14 @@ export async function captureFirebaseTokenViaCdp(opts) {
     const { targetId } = await Target.createTarget({ url: loginUrl });
     try {
         const session = await handles.attachToTab(targetId);
-        const { Runtime } = session;
         const deadline = Date.now() + timeoutMs;
         while (Date.now() < deadline) {
-            const r = await Runtime.evaluate({
+            const result = await session.send('Runtime.evaluate', {
                 expression: EXTRACT_TOKEN_JS,
                 awaitPromise: true,
                 returnByValue: true,
             });
-            const value = r.result?.value;
+            const value = runtimeResultValue(result);
             if (typeof value === 'string' && value.length > 0) {
                 return { token: value, closedBrowser: launchedByUs };
             }
@@ -146,3 +145,12 @@ export async function captureFirebaseTokenViaCdp(opts) {
         await handles.close().catch(() => { });
     }
 }
+function runtimeResultValue(value) {
+    if (typeof value !== 'object' || !value || !('result' in value)) {
+        return undefined;
+    }
+    const result = value.result;
+    return typeof result === 'object' && result && 'value' in result
+        ? result.value
+        : undefined;
+}

package/lib/old/tools/publish.js

@@ -230,7 +230,29 @@ export function createVersionFromCaptureTool(client) {
                         'the whole payload), template just that part with ' +
                         '`{{paramName}}` and keep the rest as fixed literal text; see ' +
                         'the "bodySniff" section of the customInjection field\'s guide ' +
-                        'for the exact mechanics and a worked example.',
+                        'for the exact mechanics and a worked example. ' +
+                        '⚠️ BEFORE populating this to gate ' +
+                        '`verifyProof(proof, { providerId })`: 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, no matter ' +
+                        'how correct the rest of this entry is — populating' +
+                        'it for such ' +
+                        'a provider makes verifyProof reject every real proof,' +
+                        'which is ' +
+                        'worse than leaving this field 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 ' +
+                        'customInjection field\'s guide for the full mechanics and ' +
+                        'when to reach for it.',
                     items: {
                         type: 'object',
                         properties: {

package/lib/provider/draft.d.ts

@@ -37,4 +37,24 @@ export interface DraftResult {
  *  `{{param}}`. Throwing discards the draft so the agent re-captures or
  *  re-proposes rather than shipping a provider pinned to this one user. */
 export declare function assertPortableMatches(matches: ResponseMatch[], redactions: ResponseRedaction[], targets: DraftTarget[]): void;
+/** Reject a draft that OPRF-hashes a target whose value ALSO appears in the
+ *  request URL. The whole point of `hash` is that the attestor never sees
+ *  the value in cleartext — but URL `paramValues` are always signed into the
+ *  attestor's context in the clear (attestor-core: "those in URL... will be
+ *  put into context and signed"), so a value that's both hashed in the
+ *  response AND present in the URL is visible there anyway. This isn't a
+ *  privacy nuance the author can weigh (unlike {@link assertPortableMatches}
+ *  bare-literal cases) — it doesn't verify. Throwing here, at draft time,
+ *  surfaces that immediately instead of a confusing later proof failure. */
+export declare function assertNoOprfUrlConflict(url: string, targets: DraftTarget[], effectiveHashes: (OprfMode | undefined)[]): void;
+/** Reject a draft whose URL bakes in a secret header/cookie's value beyond
+ *  what write-redaction can actually hide there. A secret value used in the
+ *  URL is NOT an automatic leak — write-redaction (`key-update`/`zk`) can
+ *  redact it from the attestor's view up to {@link secretUrlCharBudget}
+ *  characters, summed across every secret value that appears in that URL
+ *  (not per-value). Below the budget the header buys real privacy; at or
+ *  over it, the value is effectively visible regardless of hiding the
+ *  header (same class of problem as {@link assertNoOprfUrlConflict} for
+ *  OPRF-hashed targets, which has no such budget at all). */
+export declare function assertNoSecretUrlConflict(url: string, secrets: Record<string, string>, writeRedactionMode?: ReclaimProvider['writeRedactionMode']): void;
 export declare function draftProvider(req: CapturedRequest, targets: DraftTarget[], name: string, hash?: OprfMode): DraftResult;