@reclaimprotocol/agent 0.1.23 → 0.1.25

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

@@ -1,24 +1,64 @@
-import { PROVIDER_GUIDE_BUILDER, PROVIDER_GUIDE_OLD, } from "../../instructions.js";
+import { guideFor } from "../../instructions.js";
 import { defineTool } from "../../server.js";
 /**
- * Serves the full provider-authoring guide on demand. The MCP server's
- * always-on `instructions` are a terse tool-flow reference; this tool returns
- * the deep version (workflow, decision frameworks, gotchas, "never do" rules)
- * 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_browser`.
+ * Serves the provider-authoring guide on demand, ONE TOPIC AT A TIME. The
+ * server's always-on `instructions` are a terse tool-flow reference; this tool
+ * is the deep version, so any MCP client — not just Claude Code, which alone
+ * auto-loads skills — can pull it.
+ *
+ * Topic-scoped rather than all-at-once because the full guide is ~7k tokens:
+ * paying that to answer "how do I mark a header secret?" crowds out the actual
+ * task, which is exactly what makes an agent slow and prone to inventing
+ * details. Every response carries the topic index, so a caller that guessed
+ * wrong (or called with no topic at all) always learns what else is available
+ * without a second round-trip.
+ *
+ * `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_browser`.
  */
 export function howItWorksTool(oldMode) {
-    const guide = oldMode ? PROVIDER_GUIDE_OLD : PROVIDER_GUIDE_BUILDER;
+    const guide = guideFor(oldMode);
+    const names = [...guide.topics.keys()];
     return defineTool({
         name: 'how_it_works',
-        description: 'Return the full Reclaim provider-authoring guide for THIS server: '
-            + 'the capture → draft → replay → prove → publish workflow, decision '
-            + 'frameworks (login detection, OPRF privacy, context vs bare params), '
-            + 'multi-request handling, troubleshooting, and what never to do. '
-            + 'Call this BEFORE building a provider unless you are already '
-            + 'fluent in the flow.',
-        inputSchema: { type: 'object', properties: {} },
-    }, async () => ({ guide }));
+        description: 'Reclaim provider-authoring guide for THIS server, by topic. Call it '
+            + 'with no arguments for the overview plus the topic index, then again '
+            + 'for whichever topic you need. Topics: '
+            + names.join(', ')
+            + '. Use `all` for the entire guide at once (large — prefer a topic). '
+            + 'Read the relevant topic BEFORE acting unless you are already fluent '
+            + 'in that part of the flow.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                topic: {
+                    type: 'string',
+                    // Deliberately NOT an `enum`: schema validation runs before the
+                    // handler, so an enum turns a mistyped topic into a validation
+                    // error instead of a response carrying the real topic list. A
+                    // plain string lets the tool answer the mistake usefully.
+                    description: 'Which section to return: ' + names.join(', ')
+                        + ', or `all`. Omit for the overview + topic index. An '
+                        + 'unrecognized value comes back with the list, not an error.',
+                },
+            },
+        },
+    }, async ({ topic }) => {
+        if (topic === 'all') {
+            return { topic: 'all', topics: guide.index, guide: guide.full };
+        }
+        const requested = topic ?? 'overview';
+        const section = guide.topics.get(requested);
+        if (!section) {
+            // Not an error: hand back the index so the caller self-corrects in
+            // the same turn rather than retrying blind.
+            return {
+                error: `Unknown topic "${requested}".`,
+                topics: guide.index,
+                guide: guide.topics.get('overview'),
+            };
+        }
+        return { topic: requested, topics: guide.index, guide: section };
+    });
 }

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

@@ -1,2 +1 @@
-export { buildAgentState, buildAgentTools } from './build.ts';
-export type { AgentState } from './build.ts';
+export { type AgentState, buildAgentState, buildAgentTools, disposeAgentState, } 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 { buildAgentState, buildAgentTools } from "./build.js";
+export { buildAgentState, buildAgentTools, disposeAgentState, } from "./build.js";

package/lib/mcp/tools/agent/live-view.d.ts

@@ -0,0 +1,17 @@
+import { type Tunnel } from '../../../live/tunnel.ts';
+import { type RegisteredTool } from '../../server.ts';
+import { type AttachState } from './attach.ts';
+export interface LiveShare {
+    tunnel: Tunnel;
+    /** The public URL handed to whoever is watching. */
+    url: string;
+}
+export interface LiveShareRef {
+    current?: LiveShare;
+}
+/** Tear down whatever share is running. Safe when none is. Exported so the
+ *  session tools can call it from `dispose_browser` / `reset_session`. */
+export declare function stopLiveShare(ref: LiveShareRef): Promise<boolean>;
+export declare function liveViewTools(attachRef: {
+    current?: AttachState;
+}, shareRef: LiveShareRef): RegisteredTool[];

package/lib/mcp/tools/agent/live-view.js

@@ -0,0 +1,146 @@
+/**
+ * `share_browser_view` / `stop_browser_view` — put the LOCAL attached tab
+ * behind a public URL so someone who is not at this machine can watch it, and
+ * optionally drive it.
+ *
+ * Scoped to the CDP-attached modes (`dedicated`, `attach`, `custom`) on
+ * purpose. A `builder`-mode browser is a Popcorn pod that already ships its
+ * own hosted live view on `attach_browser`'s `liveViewUrl`; tunnelling a
+ * second one would duplicate it and burn a share URL for nothing, so this
+ * refuses and points at the one that exists.
+ *
+ * The share is deliberately explicit and single-instance: one live view per
+ * attached browser, started only when asked for, and torn down by
+ * `stop_browser_view`, `dispose_browser`, or `reset_session`.
+ */
+import { badRequest, conflict } from '@hapi/boom';
+import assert from 'node:assert';
+import { startTunnel } from "../../../live/tunnel.js";
+import { LOGGER } from "../../../logger.js";
+import { defineTool } from "../../server.js";
+import { SHAREABLE_MODES } from "./attach.js";
+/** Tear down whatever share is running. Safe when none is. Exported so the
+ *  session tools can call it from `dispose_browser` / `reset_session`. */
+export async function stopLiveShare(ref) {
+    const share = ref.current;
+    if (!share) {
+        return false;
+    }
+    ref.current = undefined;
+    // Only the tunnel is ours to close. The browser and its viewer belong to the
+    // container, which keeps running until the browser is disposed.
+    await share.tunnel.stop().catch((err) => {
+        LOGGER.warn({ err }, 'live view: tunnel stop failed');
+    });
+    return true;
+}
+export function liveViewTools(attachRef, shareRef) {
+    return [
+        defineTool({
+            name: 'share_browser_view',
+            description: 'Put the attached browser\'s live view behind a PUBLIC HTTPS URL (a '
+                + 'cloudflared quick tunnel) so someone elsewhere can watch it and '
+                + 'act in it. Use it to hand a login or a 2FA step to the person '
+                + 'who holds the credentials, or to let a colleague watch a '
+                + 'capture. Returns the URL — relay it to the developer VERBATIM, '
+                + 'on its own line. '
+                + 'ONLY for `container` mode, whose browser runs its own viewer. '
+                + 'A `builder` browser already has a hosted live view: use the '
+                + '`liveViewUrl` attach_browser returned. A local browser '
+                + '(`dedicated`, `attach`, `custom`) cannot be shared at all — no '
+                + 'tunnel can fix that, because there is no viewer behind it. Tell '
+                + 'them so, and offer to re-attach: `container` is free and needs '
+                + 'Docker, `builder` needs no install but is chargeable. '
+                + 'THE URL IS THE ONLY CREDENTIAL: the random hostname is the whole '
+                + 'secret, with no token or login behind it, so anyone who learns '
+                + 'it can see and drive this browser as the signed-in user. Share '
+                + 'it only with the person who needs it, and call stop_browser_view '
+                + 'the moment they are done. '
+                + 'Needs cloudflared: an existing install on PATH is used as-is, '
+                + 'otherwise it is downloaded once to ~/.reclaim/bin on first '
+                + 'share (never at install time). Set RECLAIM_CLOUDFLARED_PATH to '
+                + 'point at your own copy instead.',
+            inputSchema: { type: 'object', properties: {} },
+        }, async () => {
+            const attached = attachRef.current;
+            assert(attached, badRequest('No browser attached. Call attach_browser first.'));
+            assert(SHAREABLE_MODES.has(attached.mode), badRequest(`share_browser_view does not apply to \`${attached.mode}\` mode. `
+                + (attached.liveViewUrl
+                    ? 'That browser already has a hosted live view — use the '
+                        + `\`liveViewUrl\` from attach_browser: ${attached.liveViewUrl}`
+                    : 'That browser has no live view to put behind a URL. To let '
+                        + 'someone else in, re-attach with mode "container" (the '
+                        + 'Reclaim runtime in Docker — free, needs Docker) or '
+                        + '"builder" (hosted, no install, chargeable)')
+                + '.'));
+            assert(!shareRef.current, conflict('A live view is already running at '
+                + `${shareRef.current?.url}. Call stop_browser_view first, or `
+                + 'reuse that URL.'));
+            // The container publishes its viewer on loopback and its full CDP
+            // port beside it. Only the VIEWER is ever tunnelled: the CDP port is
+            // unauthenticated, total control of the browser, and putting it on a
+            // public URL would hand that to anyone with the link.
+            const viewerPort = attached.viewerPort;
+            assert(viewerPort, badRequest('This browser reports no live-view port. Re-attach with mode '
+                + '"container".'));
+            const tunnel = await startTunnel(viewerPort);
+            // The path is the runtime's own viewer page; `magnify=1` is what makes
+            // it lay out for the device that opens it.
+            const url = `${tunnel.url}/liveview.html?magnify=1`;
+            const share = {
+                tunnel, url,
+            };
+            shareRef.current = share;
+            LOGGER.info({ mode: attached.mode }, 'live view shared');
+            return {
+                url,
+                ...(share.tunnel.binary.source === 'downloaded'
+                    ? { cloudflaredInstalled: true }
+                    : {}),
+                ...(share.tunnel.ready
+                    ? {}
+                    : {
+                        propagating: true,
+                        // cloudflared's own last words. Without them, "the URL does
+                        // not connect" is unactionable: the tunnel, the local server
+                        // and this machine's egress all look identical from outside.
+                        ...(share.tunnel.diagnostics
+                            ? { cloudflaredLog: share.tunnel.diagnostics }
+                            : {}),
+                    }),
+                _notes: [
+                    ...(share.tunnel.binary.source === 'downloaded'
+                        ? ['cloudflared was not installed, so it was downloaded once '
+                                + 'to ~/.reclaim/bin. Mention that; later shares reuse it.']
+                        : []),
+                    ...(share.tunnel.ready
+                        ? []
+                        : ['The tunnel never confirmed a connection to Cloudflare, so '
+                                + 'the URL may not resolve yet. Give it ~10s and reload '
+                                + 'first. If it still fails, say so and offer to retry '
+                                + '(stop_browser_view then share_browser_view) — a quick '
+                                + 'tunnel does sometimes fail to register. '
+                                + '`cloudflaredLog` has its output if it keeps happening.']),
+                    'Relay `url` to the developer verbatim, on its own line.',
+                    'The URL is a credential: it needs no login, and anyone with it '
+                        + 'can see this browser and act in it as the signed-in user.',
+                    'It shows the whole browser, so a sign-in that opens a separate '
+                        + 'window is visible too — unlike a single-tab stream.',
+                    'Opening it on a phone lays the page out for that phone, with '
+                        + 'touch, pinch-zoom and the soft keyboard.',
+                    'Call stop_browser_view when they are done. That closes the '
+                        + 'tunnel only — the browser keeps running.',
+                ],
+            };
+        }),
+        defineTool({
+            name: 'stop_browser_view',
+            description: 'Close the public URL opened by share_browser_view: shuts the '
+                + 'tunnel down, so the URL stops resolving for whoever still has '
+                + 'it. Call it as soon as the person you shared with is finished. '
+                + 'Nothing else changes — the browser stays attached, its own live '
+                + 'view keeps serving locally, and any capture keeps running.',
+            inputSchema: { type: 'object', properties: {} },
+        }, async () => ({ stopped: await stopLiveShare(shareRef) })),
+    ];
+}

package/lib/mcp/tools/agent/pod-proof.d.ts

@@ -0,0 +1,8 @@
+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';
+export declare function podProofTools(attachRef: {
+    current?: AttachState;
+    config: ConfigStore;
+}, captures: CaptureStore): RegisteredTool[];

package/lib/mcp/tools/agent/pod-proof.js

@@ -0,0 +1,64 @@
+/**
+ * Prove a drafted recipe through the Popcorn pod's OWN `/reclaim/prove` — the
+ * remote browser session's own API for creating a proof from that same
+ * session — instead of the local in-process attestor SDK (`run_proof`).
+ * Recommended for any `builder`-mode attach: the pod is the SAME enclave that
+ * holds the browser's TLS session, so proving there reaches the target from
+ * the identical exit IP the browser used — including the country-routed egress
+ * Popcorn applies when the session was allocated with a country. A local SDK
+ * proof runs from the agent's own network instead, which won't match a
+ * country-locked / IP-allowlisted target the remote browser could reach.
+ *
+ * Builder mode only (needs the attach's pod `apiUrl`, from
+ * `CreateAgentBrowserSession`) — throws a clear error otherwise rather than
+ * silently falling back to the local path.
+ */
+import { badRequest } from '@hapi/boom';
+import assert from 'node:assert';
+import { popcornProve } from "../../../proof/pod-prover.js";
+import { buildHttpParams } from "../../../proof/proof-core.js";
+import { defineTool } from "../../server.js";
+import { shapeRichProofResult } from "./proof.js";
+export function podProofTools(attachRef, captures) {
+    const tool = defineTool({
+        name: 'run_proof_via_pod',
+        description: 'Prove the drafted recipe through the Popcorn pod\'s own TEE '
+            + '(/reclaim/prove) instead of the local attestor SDK — this is '
+            + 'the remote browser session\'s own api for creating a proof '
+            + 'from that same session. Use this instead of run_proof '
+            + 'whenever this capture\'s '
+            + 'attach mode is "builder": the pod is the same enclave that '
+            + 'held the browser\'s TLS session (and its country-routed egress, '
+            + 'if any), so '
+            + 'the proof reaches the target from the browser\'s own exit IP. '
+            + 'No ownerAddress needed — the pod signs with the attestor\'s '
+            + 'own TEE key, not a local credential.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                captureId: { type: 'string' },
+                draftId: { type: 'string' },
+            },
+            required: ['captureId', 'draftId'],
+        },
+    }, async ({ captureId, draftId }) => {
+        const apiUrl = attachRef.current?.apiUrl;
+        assert(apiUrl, badRequest('No pod api available for this attach — run_proof_via_pod needs '
+            + 'mode "builder" (attach_browser), not local/custom CDP.'));
+        const entry = captures.sessions.get(captureId);
+        assert(entry, badRequest(`no capture ${captureId} — call start_capture first `
+            + '(it has been reset or never started).'));
+        const draft = entry.drafts.get(draftId);
+        assert(draft, badRequest(`no draft ${draftId} in capture ${captureId}`));
+        const result = await popcornProve({
+            apiUrl,
+            params: buildHttpParams(draft.provider),
+            secretParams: { headers: draft.secrets },
+        });
+        return shapeRichProofResult(result, {
+            provider: draft.provider,
+            hasSecrets: Object.keys(draft.secrets).length > 0,
+        });
+    });
+    return [tool];
+}

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

@@ -21,13 +21,15 @@ export function proposeTool(resolveBackend) {
             + 'Single-value shorthand: `target` + `name`. Per-target `hash` '
             + 'OPRF-hashes that value. BY DEFAULT each `name` is shortened to '
             + 'its last alphanumeric token, lowercased, to form the param key '
-            + '(e.g. "employer_name" → "name") — pick names that stay distinct '
+            + '(for example, "employer_name" → "name") — pick names that stay '
+            + 'distinct '
             + 'after shortening ("firstName"/"surname", not "first_name"/'
             + '"last_name"). Pass `shortenNames: false` to use each `name` '
             + 'VERBATIM as the param key instead — it becomes both a regex '
             + 'capture-group name and a paramValues key, so it must be a plain '
             + 'identifier (letters/digits/underscore, not starting with a '
-            + 'digit); we recommend lower_snake_case (e.g. "employer_name"), '
+            + 'digit); we recommend lower_snake_case (for example, '
+            + '"employer_name"), '
             + 'but you choose the exact name.',
         inputSchema: objectSchema({
             requestId: { type: 'string' },

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

@@ -1,4 +1,4 @@
-import { INJECTION_GUIDE } from "../../../provider/injection-doc.js";
+import { ALLOWED_REQUESTS_HINT, USER_SCRIPT_HINT, } from "../../../provider/injection-doc.js";
 import { countsFor, matchRedactionWarnings, } from "../../../provider/match-redaction-warning.js";
 import { nextVersion, providerToCreateVersionRequest, } from "../../../provider/to-version.js";
 import { defineTool } from "../../server.js";
@@ -62,7 +62,8 @@ const REQUEST_DRAFT_PROPERTIES = {
 const PROVIDER_SCHEMA = {
     type: 'object',
     description: 'A `provider` object from propose_provider, passed through verbatim — ' +
-        'the tool builds the version body (the requests[] entry etc.) for you.',
+        'the tool builds the version body (the requests[] entry and so on) ' +
+        'for you.',
     properties: {
         name: { type: 'string', description: 'Verification name.' },
         ...REQUEST_DRAFT_PROPERTIES,
@@ -73,7 +74,7 @@ const PROVIDER_SCHEMA = {
         },
         paramValues: {
             type: 'object',
-            description: 'Real values for the {{param}} placeholders, e.g. ' +
+            description: 'Real values for the {{param}} placeholders, for example, ' +
                 '{ "username": "Syed" }.',
         },
     },
@@ -87,8 +88,8 @@ const ALLOWED_JS_REQUEST_SCHEMA = {
         ...REQUEST_DRAFT_PROPERTIES,
         multiple: {
             type: 'boolean',
-            description: 'Allow the template to match many requests (e.g. pagination). ' +
-                'Default true.',
+            description: 'Allow the template to match many requests (for example, ' +
+                'pagination). Default true.',
         },
         required: {
             type: 'boolean',
@@ -100,36 +101,21 @@ const ALLOWED_JS_REQUEST_SCHEMA = {
 export function createVersionFromCaptureTool(client, attachRef) {
     return defineTool({
         name: 'create_provider_version_from_capture',
-        description: 'Persist drafted ReclaimProvider(s) as a provider version. ' +
-            'Call this after run_proof succeeds, passing the `provider` ' +
-            'object(s) from propose_provider VERBATIM. This tool builds the ' +
-            'body (the requests[] array, webSettings, etc.) for you — do NOT ' +
-            'hand-construct that shape or call create_provider_version directly. ' +
-            'For a MULTI-REQUEST provider, pass `providers: [...]` (each entry a ' +
-            'proven draft) — every entry becomes one request in the version, and ' +
-            'all are required at verification time. Pass a single `provider` ' +
-            'for the one-request case (exactly one of `provider`/`providers`). ' +
-            'For data gated behind login/navigation, supply `jsUserScripts` (a ' +
-            'page-injection script that drives the page to where the request ' +
-            'fires) and/or `allowedJsRequests` (extra requests the script may ' +
-            'fire, e.g. pagination). ' +
-            'Omit `version` to have the tool auto-select the next available ' +
-            'version (it lists existing versions and bumps past the highest). ' +
-            'The version lands on the draft branch — to go live, call ' +
-            '`publish_provider_version` (PRIVATE) or ' +
-            '`submit_provider_version_for_review` (PUBLIC) afterwards. ' +
+        description: 'Persist drafted ReclaimProvider(s) as a provider version, after ' +
+            'run_proof succeeds. Pass the `provider` object(s) from ' +
+            'propose_provider VERBATIM — this tool builds the version body ' +
+            '(requests[], webSettings, …) for you; do NOT hand-construct that ' +
+            'shape or call create_provider_version directly. Exactly one of ' +
+            '`provider` (one request) or `providers` (a multi-request provider — ' +
+            'every entry is required at verification time). Omit `version` to ' +
+            'auto-bump past the highest existing one. The version lands on the ' +
+            'draft branch: call `publish_provider_version` (PRIVATE) or ' +
+            '`submit_provider_version_for_review` (PUBLIC) to go live. ' +
             '`requiredContext` is derived from any {{context.<name>}} ' +
-            'placeholders across ALL requests (plus injected requests / script) ' +
-            'and returned on the created version — when present, tell the dev ' +
-            'verbatim which context fields consumers MUST send when creating ' +
-            '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. ' +
-            '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.',
+            'placeholders and returned on the created version — relay it to the ' +
+            'dev verbatim, since a session missing those fields is a 400. Always ' +
+            'read the response\'s `_notes`. ' +
+            'Full walkthrough: how_it_works({ topic: "publish" }).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -149,12 +135,14 @@ export function createVersionFromCaptureTool(client, attachRef) {
                 initialUrl: {
                     type: 'string',
                     description: 'The website URL the user landed on to trigger the request ' +
-                        '(e.g. https://github.com/Syed). The URL the verification ' +
-                        'flow opens for end-users — NOT the API URL inside the provider.',
+                        '(for example, https://github.com/Syed). The URL the ' +
+                        'verification flow opens for end-users — NOT the API URL ' +
+                        'inside the provider.',
                 },
                 notes: {
                     type: 'string',
-                    description: 'Short change note (e.g. "Initial draft from browser capture").',
+                    description: 'Short change note (for example, "Initial draft from ' +
+                        'browser capture").',
                 },
                 version: {
                     type: 'object',
@@ -169,44 +157,21 @@ export function createVersionFromCaptureTool(client, attachRef) {
                 },
                 jsUserScripts: {
                     type: 'string',
-                    description: 'Plain JavaScript injected into the provider page before every ' +
-                        'page load (stored as webSettings.jsUserScripts). Use standard ' +
-                        'browser APIs (window.location, element.click(), forms) to ' +
-                        'drive login/navigation so the target request fires — the ' +
-                        'client already intercepts page requests, and window.Reclaim ' +
-                        'is only for rare edge cases, not navigation. The Builder ' +
-                        'verification client installs this to run before every page ' +
-                        'load (before navigating to initialUrl), matching old-devtool ' +
-                        'customInjection; window.Reclaim itself is not yet exposed ' +
-                        'there, so prefer plain browser JS. Guide:\n\n' +
-                        INJECTION_GUIDE,
+                    description: USER_SCRIPT_HINT +
+                        ' Stored as webSettings.jsUserScripts; the Builder ' +
+                        'verification client runs it before every page load ' +
+                        '(including before navigating to initialUrl), matching ' +
+                        'old-devtools customInjection. window.Reclaim is not exposed ' +
+                        'there yet, so prefer plain browser JS.',
                 },
                 allowedJsRequests: {
                     type: 'array',
-                    description: 'Extra requests the injection script is allowed to fire ' +
-                        '(e.g. paginated API calls), as RequestSelectionTemplates. ' +
-                        '`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.',
+                    description: 'Extra requests the user script is allowed to fire (for ' +
+                        'example, paginated API calls), as ' +
+                        'RequestSelectionTemplates. ' +
+                        '`multiple`/`required` default to true. Old-devtools calls the ' +
+                        'same concept `allowedInjectedRequestData`. ' +
+                        ALLOWED_REQUESTS_HINT,
                     items: ALLOWED_JS_REQUEST_SCHEMA,
                 },
                 interceptorOptions: {
@@ -214,11 +179,7 @@ export function createVersionFromCaptureTool(client, attachRef) {
                     description: 'In-app interception settings, stored as ' +
                         'webSettings.clientOptions.inapp.interceptorOptions — only ' +
                         'needed for a genuine live-interception provider (a real ' +
-                        'HAWKEYE/MSWJS script, not the standard capture→replay flow). ' +
-                        'Document replay (webSettings.clientOptions.inapp' +
-                        '.interceptorOptions.isDocumentRequestReplayEnabled) is ' +
-                        'ALWAYS published disabled regardless of this field — there ' +
-                        'is no way to enable it here.',
+                        'HAWKEYE/MSWJS script, not the standard capture→replay flow).',
                     properties: {
                         interceptorType: {
                             type: 'string',
@@ -229,6 +190,15 @@ export function createVersionFromCaptureTool(client, attachRef) {
                             type: 'string',
                             description: 'Free-form JSON config for the chosen interceptor.',
                         },
+                        isDocumentRequestReplayEnabled: {
+                            type: 'boolean',
+                            description: 'Whether the page\'s own document/navigation request is ' +
+                                'genuinely replayed through the interceptor, rather than ' +
+                                'constructed locally. Defaults to `false` (disabled) when ' +
+                                'omitted. Only meaningful for HAWKEYE/MSWJS — pass `true` ' +
+                                'when the target value is embedded in the page\'s own HTML ' +
+                                'rather than a separate API call. Inert for CDP.',
+                        },
                     },
                     required: ['interceptorType'],
                 },

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

@@ -2,7 +2,22 @@ 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 LiveShareRef } from './live-view.ts';
 export declare function sessionTools(attachRef: {
     current?: AttachState;
     config: ConfigStore;
-}, captures: CaptureStore): RegisteredTool[];
+}, captures: CaptureStore, liveShare: LiveShareRef): RegisteredTool[];
+/**
+ * Release everything a session holds: the public tunnel, the captures, and the
+ * browser itself.
+ *
+ * Exported because a session can end WITHOUT anyone calling `dispose_browser` —
+ * the developer closes their agent, the client kills the server, the transport
+ * drops. Nothing runs on its own then, so `start.ts` runs this. Without it a
+ * container keeps running and, worse, a public URL to a live browser outlives
+ * the session that created it.
+ */
+export declare function resetAll(attachRef: {
+    current?: AttachState;
+    config: ConfigStore;
+}, captures: CaptureStore, liveShare: LiveShareRef): Promise<void>;