@reclaimprotocol/agent 0.1.35 → 0.1.37

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

@@ -3,8 +3,7 @@ import assert from 'node:assert';
 import { connectCdp, connectCdpUrl, } from "../../../cdp/client.js";
 import { dockerAvailable, dockerMissingMessage, startContainer, } from "../../../cdp/container.js";
 import { suggestCountryFromIp } from "../../../cdp/geo.js";
-import { defaultProfileDir, launchChrome, waitForCdpReady, } from "../../../cdp/launcher.js";
-import { defaultConfigPath } from "../../../config/store.js";
+import { defaultProfileDir, launchLocalBrowser, waitForCdpReady, } from "../../../cdp/launcher.js";
 import { defineTool } from "../../server.js";
 import { ensureLiveViewUrl } from "./live-view-url.js";
 /**
@@ -16,84 +15,13 @@ import { ensureLiveViewUrl } from "./live-view-url.js";
  * show — one on this machine is watched by looking at it.
  */
 export const SHAREABLE_MODES = new Set(['container']);
-/** Browser sources returned when the caller omits `mode`. Keep selection detail
- * here instead of repeating it in the always-loaded tool description. */
-const BROWSER_OPTIONS = [
-    {
-        mode: 'dedicated',
-        useCase: 'Working on your own machine',
-        label: 'Local Chrome, launched for you',
-        detail: 'Launches Chrome with a dedicated profile under '
-            + '~/.reclaim/chrome-profile. Nothing to set up, and the profile '
-            + 'persists, so a site you sign in to stays signed in. The easiest '
-            + 'choice when you are doing the work yourself.',
-        requires: [],
-        liveView: 'None, and none needed — the browser is on your screen.',
-    },
-    {
-        mode: 'attach',
-        useCase: 'Working on your own machine',
-        label: 'The Chrome you already have open',
-        detail: 'Connects to a Chrome you started yourself, keeping the tabs, '
-            + 'extensions and logins already in it. That Chrome must have been '
-            + 'started with BOTH --remote-debugging-port AND a non-default '
-            + '--user-data-dir: since Chrome 136 the debug flag is silently '
-            + 'ignored on the default profile.',
-        requires: ['port (default 9222)'],
-        liveView: 'None, and none needed — the browser is on your screen.',
-    },
-    {
-        mode: 'container',
-        useCase: 'Someone else has to sign in, or you need a phone',
-        label: 'Reclaim runtime in Docker — free, runs on your machine',
-        detail: 'Runs the Reclaim browser runtime (the same image the remote browser '
-            + 'uses) as a container on this machine, and gives you a link you can '
-            + 'send to whoever holds the account. They open it in any browser, '
-            + 'including a phone, and can see and click in it. Free — it is your '
-            + 'Docker and your bandwidth. Costs a 432 MB first-run download and '
-            + 'about 2 GB of RAM. The image is amd64, so Apple Silicon runs it '
-            + 'translated. OrbStack handles that itself; Docker Desktop needs '
-            + 'Rosetta enabled.',
-        requires: ['Docker running'],
-        liveView: 'Built in. This call returns a local `viewerUrl`, and '
-            + 'share_browser_view turns that into a public link for the person '
-            + 'helping you.',
-    },
-    {
-        mode: 'builder',
-        useCase: 'Someone else has to sign in, or you need a phone',
-        label: 'Remote browser, hosted by Reclaim — CHARGEABLE',
-        detail: 'A browser allocated in Reclaim\'s cloud, billed against the '
-            + 'organization\'s quota. Nothing to install, and the shareable link '
-            + 'comes back immediately. It is also the only way to browse a site '
-            + 'from a SPECIFIC COUNTRY — its whole egress is routed there. '
-            + 'Geolocation is optional: omit countryCode to be offered a '
-            + 'suggestion, or pass skipCountry to allocate without geo-routing.',
-        requires: [
-            'Builder authentication',
-            'orgId (auto-resolved when you have only one)',
-            'quota — this one costs money',
-        ],
-        liveView: 'Included. This call returns a hosted liveViewUrl to pass on; '
-            + 'share_browser_view does not apply.',
-    },
-    {
-        mode: 'custom',
-        useCase: 'Advanced',
-        label: 'A CDP endpoint you supply',
-        detail: 'Connects to any ws:// or wss:// CDP websocket — a browser you run '
-            + 'elsewhere, or another tool\'s. The URL is treated as a credential: '
-            + 'never logged, persisted, or returned. Only pick this if you were '
-            + 'given an endpoint and know why.',
-        requires: ['cdpUrl'],
-        liveView: 'None, unless you pass your own liveViewUrl alongside the cdpUrl.',
-    },
-];
 const DEFAULT_DEPENDENCIES = {
     connectLocal: connectCdp,
     connectRemote: connectCdpUrl,
     dockerAvailable,
     startContainer,
+    launchLocal: launchLocalBrowser,
+    waitForCdp: waitForCdpReady,
 };
 export function attachTool(state, builderClient, beforeReplace, 
 // Partial so a caller can stub one thing without restating the rest — the
@@ -104,16 +32,15 @@ dependencies = {}) {
     };
     return defineTool({
         name: 'attach_browser',
-        description: 'Connects the authoring tools to a browser that loads the '
-            + 'developer\'s sign-in page and target site. `builder` and '
-            + '`container` run the browser remotely or in Docker, away from the '
-            + 'developer\'s own profile; `dedicated`, `attach`, and `custom` use a '
-            + 'local or supplied Chrome. Call without `mode` to receive the '
-            + 'options, ask the developer to choose, then call again once with '
-            + 'the chosen mode. `builder` consumes quota. Only `container` and '
-            + '`builder` support a shareable live view. Relay returned live-view '
-            + 'URLs verbatim. See how_it_works({ topic: "browser" }) for '
-            + 'selection, geolocation, and lifecycle.',
+        description: 'Opens a visible browser on the developer\'s own machine for '
+            + 'sign-in and capture. Call it with no arguments and do not ask '
+            + 'which browser to use: it launches installed Chrome (else '
+            + 'Chromium, Edge, or a one-time Chrome for Testing download) with '
+            + 'the persistent Reclaim profile. Pass `mode` only when the '
+            + 'developer explicitly asks for that mode: `attach` (their running '
+            + 'Chrome on `port`), `container` (Docker), `custom` (`cdpUrl`), or '
+            + '`builder` (billed). Never offer or pick those yourself. See '
+            + 'how_it_works({ topic: "browser" }).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -122,6 +49,8 @@ dependencies = {}) {
                     enum: [
                         'dedicated', 'attach', 'container', 'builder', 'custom',
                     ],
+                    description: 'Omit for the default local browser (`dedicated`). Set '
+                        + 'only to a mode the developer explicitly asked for.',
                 },
                 attachMode: {
                     type: 'string',
@@ -159,31 +88,12 @@ dependencies = {}) {
         annotations: { openWorldHint: true, destructiveHint: false },
     }, async (parsed) => {
         const persisted = state.config.read()?.browser_agent;
-        // Deliberately NOT falling back to the persisted mode: which browser
-        // to drive is the developer's call every time (a remote one costs
-        // quota, a local one exposes their own profile), and silently reusing
-        // last session's answer takes that decision away from them. The
-        // persisted choice is offered back as a default to suggest, not
-        // applied.
-        const mode = parsed.mode ?? parsed.attachMode;
-        if (!mode) {
-            return {
-                needsChoice: true,
-                message: 'Ask FIRST whether they will be doing this themselves or '
-                    + 'someone else has to sign in — that answer decides half the '
-                    + 'list. Themselves: `dedicated` or `attach`. Someone else, or '
-                    + 'a phone-only site: `container` (free, needs Docker) or '
-                    + '`builder` (no install, chargeable) — the only two that give '
-                    + 'you a link to send. Then present the matching options and '
-                    + 'call attach_browser again with the `mode` they pick. Do not '
-                    + 'pick one for them.',
-                options: BROWSER_OPTIONS,
-                ...(persisted?.attachMode
-                    ? { previouslyUsed: persisted.attachMode }
-                    : {}),
-                configPath: defaultConfigPath(),
-            };
-        }
+        // The default is a visible browser on the developer's own machine,
+        // with no question first. Every other mode costs something (Docker,
+        // quota, the developer's own profile) and is used only when the
+        // developer asked for it by name, so a persisted choice is never
+        // reapplied either.
+        const mode = parsed.mode ?? parsed.attachMode ?? 'dedicated';
         let orgId = parsed.orgId;
         if (mode === 'builder' && !orgId) {
             assert(builderClient, badRequest('Builder browser service is unavailable'));
@@ -279,7 +189,17 @@ dependencies = {}) {
             ...(next.countryCode ? { countryCode: next.countryCode } : {}),
             ...(next.containerName ? { containerName: next.containerName } : {}),
             ...(canShare ? { liveViewAvailable: true } : {}),
+            ...(next.launched ? { browser: next.launched.source } : {}),
             _notes: [
+                ...(next.launched?.source === 'chrome-for-testing'
+                    ? ['Launched Chrome for Testing'
+                            + (next.launched.downloaded
+                                ? ', downloaded just now into ~/.reclaim/browsers (later '
+                                    + 'launches reuse it)'
+                                : ' from ~/.reclaim/browsers')
+                            + `, because: ${next.launched.fallbackReason}. Mention `
+                            + 'this to the developer in one line.']
+                    : []),
                 ...(next.imagePulled
                     ? ['The browser runtime image was downloaded just now (about '
                             + '432 MB, about 1.3 GB on disk). Mention it — later attaches '
@@ -303,9 +223,12 @@ dependencies = {}) {
                     : []),
                 ...(!localView && !hostedView
                     ? ['This browser has no live view: it runs on the developer\'s '
-                            + 'own machine, so they watch it by looking at it. If someone '
-                            + 'ELSE needs to see or drive it, say that `container` mode '
-                            + 'runs a browser with a shareable live view built in.']
+                            + 'own machine, so they watch it by looking at it. Do not '
+                            + 'offer other modes. Tell the developer once, as a side '
+                            + 'note, that if a volunteer is helping them sign in, a '
+                            + 'shareable link can be set up (`container` mode and '
+                            + 'share_browser_view); do not ask or set it up unless they '
+                            + 'ask.']
                     : []),
             ],
         };
@@ -398,24 +321,41 @@ async function connect(mode, parsed, persisted, builderClient, dependencies) {
         }
     }
     const port = parsed.port ?? persisted?.port ?? 9222;
+    let launched;
     if (mode === 'dedicated') {
         try {
-            await waitForCdpReady(port, 500);
+            // Reuse the browser an earlier attach launched on this port.
+            await dependencies.waitForCdp(port, 500);
         }
         catch {
-            launchChrome({ port, profileDir: defaultProfileDir() });
-            await waitForCdpReady(port, 10000);
+            const browser = await dependencies
+                .launchLocal({ port, profileDir: defaultProfileDir() });
+            // The browser outlives this attach on purpose, so its process handle
+            // is not kept.
+            launched = {
+                binary: browser.binary,
+                source: browser.source,
+                downloaded: browser.downloaded,
+                ...(browser.fallbackReason
+                    ? { fallbackReason: browser.fallbackReason }
+                    : {}),
+            };
         }
     }
     else {
-        await waitForCdpReady(port, 2000).catch(() => {
+        await dependencies.waitForCdp(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 };
+    return {
+        handles: await dependencies.connectLocal(port),
+        mode,
+        port,
+        ...(launched ? { launched } : {}),
+    };
 }
 async function disposeState(state) {
     try {

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

@@ -15,6 +15,7 @@ import { analyzeTool } from "./analyze.js";
 import { attachTool } from "./attach.js";
 import { captureTools, resetCaptures } from "./capture.js";
 import { checkAttestorTool } from "./check-attestor.js";
+import { draftTools } from "./draft-tools.js";
 import { listTabsTool } from "./eval.js";
 import { howItWorksTool } from "./how-it-works.js";
 import { liveViewTools } from "./live-view.js";
@@ -73,6 +74,11 @@ export function buildAgentTools(client, builderClient = client, externalState) {
     for (const t of sharedAuthoringTools(state.captures)) {
         tools.push(t);
     }
+    // check_matchers / update_draft: offline matcher check + in-place draft
+    // edits, keyed by captureId like run_proof_via_pod.
+    for (const t of draftTools(state.captures)) {
+        tools.push(t);
+    }
     if (client) {
         tools.push(startIntegrationTool());
         tools.push(createVersionFromCaptureTool(client, state.attach, state.captures));

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

@@ -1,4 +1,5 @@
 import { makeDraftStore, } from "../../../authoring/index.js";
+import { DEFAULT_MAX_CHARS, TEXT_WINDOW_PROPERTIES, textWindow, } from "../../../authoring/util.js";
 import { startCapture } from "../../../cdp/capture.js";
 import { defineTool } from "../../server.js";
 export async function resetCaptures(captures) {
@@ -57,21 +58,27 @@ export function captureTools(attachRef, captures) {
     });
     const getTool = defineTool({
         name: 'get_request',
-        description: 'Returns the full headers and bodies of one captured request, to '
-            + 'inspect a candidate that `find_requests_containing` ranked. Unlike '
-            + 'the other tools, headers are raw: cookie and authorization values '
-            + 'are visible. Read them for diagnosis; do not repeat them to the '
-            + 'developer or write them to a file.',
+        description: 'Returns the headers and bodies of one captured request, to inspect '
+            + 'a candidate that `find_requests_containing` ranked. Each body is '
+            + `cut to ${DEFAULT_MAX_CHARS} characters by default; a cut body `
+            + 'comes with `requestBodyTruncation` or `responseBodyTruncation` '
+            + '(total size and `nextOffset`). Page with `offset`, or pass '
+            + '`maxChars` or `full`. Unlike the other tools, headers are raw: '
+            + 'cookie and authorization values are visible. Read them for '
+            + 'diagnosis; do not repeat them to the developer or write them to '
+            + 'a file.',
         inputSchema: {
             type: 'object',
             properties: {
                 captureId: { type: 'string' },
                 requestId: { type: 'string' },
+                ...TEXT_WINDOW_PROPERTIES,
             },
             required: ['captureId', 'requestId'],
         },
         annotations: { readOnlyHint: true, openWorldHint: false },
-    }, async ({ captureId, requestId }) => {
+    }, async (args) => {
+        const { captureId, requestId } = args;
         const entry = captures.sessions.get(captureId);
         if (!entry) {
             throw new Error(`no capture ${captureId}`);
@@ -80,11 +87,27 @@ export function captureTools(attachRef, captures) {
         if (!r) {
             throw new Error(`no request ${requestId} in capture ${captureId}`);
         }
+        const { requestBody, responseBody, ...meta } = r;
         const body = entry.session.bodies.get(requestId);
-        if (!body.available) {
-            return { ...r, bodyAvailable: false, reason: body.reason };
-        }
-        return { ...r, responseBody: body.body, bodyAvailable: true };
+        const result = {
+            ...meta,
+            ...windowed('requestBody', requestBody, args),
+            ...windowed('responseBody', body.available ? body.body : responseBody, args),
+        };
+        return body.available
+            ? { ...result, bodyAvailable: true }
+            : { ...result, bodyAvailable: false, reason: body.reason };
     });
     return [startTool, stopTool, getTool];
 }
+/** `{ [key]: text window }`, plus `[key]Truncation` when the window cut it. */
+function windowed(key, text, args) {
+    if (text === undefined) {
+        return {};
+    }
+    const { text: part, truncation } = textWindow(text, args);
+    return {
+        [key]: part,
+        ...(truncation ? { [`${key}Truncation`]: truncation } : {}),
+    };
+}

package/lib/mcp/tools/agent/check-attestor.js

@@ -11,13 +11,21 @@ export function checkAttestorTool(check = checkAttestor) {
             + 'seconds (about 8 when healthy). Call it once when you set up a '
             + 'new provider build, and after `run_proof` fails with a network '
             + 'error. Returns `{ ok, attestorUrl, durationMs, '
-            + 'extractedParameters, error, errorKind }`. If `ok` is true, the '
-            + 'attestor is fine and a failing proof points to the target site. '
-            + 'If `errorKind` is `attestor-unreachable`, this machine cannot '
-            + 'reach the attestor (network, VPN, firewall, or proxy): tell the '
-            + 'developer. If it is `setup-failed`, the ZK file download failed '
-            + 'before the attestor was contacted: tell the developer to check '
-            + 'network access to the circuit download. If it is '
+            + 'extractedParameters, error, errorKind, proofFiles }`. '
+            + '`proofFiles` is the proof file download state: `{ status }` is '
+            + '`idle`, `ready`, `downloading` (with `method`, `elapsedMs`, and '
+            + '`bytesDownloaded`/`totalBytes` when known), or `failed` (with '
+            + '`reason`). If `ok` is true, the attestor is fine and a failing '
+            + 'proof points to the target site. If `errorKind` is '
+            + '`proof-files-downloading`, the one-time proof file download is '
+            + 'still running and the attestor was not contacted: call this tool '
+            + 'again shortly; do not report a network problem. If it is '
+            + '`proof-files-failed`, the download failed: tell the developer '
+            + '`error` (usually no access to github.com or '
+            + 'raw.githubusercontent.com). If it is `attestor-unreachable`, the '
+            + 'proof files are ready but this machine cannot reach the attestor '
+            + '(network, VPN, firewall, or proxy): tell the developer. If it is '
+            + '`setup-failed`, other local setup failed: report `error`. If it is '
             + '`attestor-error`, the attestor rejected the claim: report '
             + '`error`.',
         inputSchema: {

package/lib/mcp/tools/agent/draft-tools.d.ts

@@ -0,0 +1,3 @@
+import { type RegisteredTool } from '../../server.ts';
+import type { CaptureStore } from './capture.ts';
+export declare function draftTools(captures: CaptureStore): RegisteredTool[];

package/lib/mcp/tools/agent/draft-tools.js

@@ -0,0 +1,170 @@
+/**
+ * `check_matchers` and `update_draft` — inspect and edit a draft's matchers
+ * without leaving MCP. `check_matchers` runs a recipe's redactions + matches
+ * against a captured response with attestor-core's own engine, offline (see
+ * proof/check-matchers.ts); `update_draft` replaces a draft's matchers in place
+ * after the same validation and portability gate `propose_provider` applies.
+ */
+import { badRequest } from '@hapi/boom';
+import assert from 'node:assert';
+import { checkMatchersOffline } from "../../../proof/check-matchers.js";
+import { editDraftProvider } from "../../../provider/draft.js";
+import { verificationWarnings } from "../../../provider/verification-checks.js";
+import { defineTool } from "../../server.js";
+const MATCHES_SCHEMA = {
+    type: 'array',
+    minItems: 1,
+    items: {
+        type: 'object',
+        properties: {
+            type: { type: 'string', enum: ['contains', 'regex'] },
+            value: { type: 'string' },
+            invert: { type: 'boolean' },
+        },
+        required: ['type', 'value'],
+    },
+};
+const REDACTIONS_SCHEMA = {
+    type: 'array',
+    items: {
+        type: 'object',
+        properties: {
+            xPath: { type: 'string' },
+            jsonPath: { type: 'string' },
+            regex: { type: 'string' },
+            hash: { type: 'string', enum: ['oprf', 'oprf-raw', 'oprf-mpc'] },
+        },
+    },
+};
+const PARAM_VALUES_SCHEMA = {
+    type: 'object',
+    additionalProperties: { type: 'string' },
+};
+export function draftTools(captures) {
+    const checkMatchers = defineTool({
+        name: 'check_matchers',
+        description: 'Checks a draft\'s `responseRedactions` and `responseMatches` '
+            + 'against the captured response, offline, with the attestor\'s own '
+            + 'redaction and match engine. No network call. Returns `ok`, '
+            + '`failedAt` and `reason` on failure, `extractedParameters`, and the '
+            + '`revealed` body slices the attestor would see (truncated). Pass '
+            + '`responseMatches`, `responseRedactions`, or `paramValues` to try '
+            + 'an edit without saving it, and `requestId` to check against a '
+            + 'different captured request. Run it before `run_proof`.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                captureId: { type: 'string' },
+                draftId: { type: 'string' },
+                requestId: {
+                    type: 'string',
+                    description: 'Captured request whose response to check. '
+                        + 'Defaults to the request the draft was proposed from.',
+                },
+                responseMatches: MATCHES_SCHEMA,
+                responseRedactions: REDACTIONS_SCHEMA,
+                paramValues: PARAM_VALUES_SCHEMA,
+            },
+            required: ['captureId', 'draftId'],
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async (args) => {
+        const { entry, draft } = resolveDraft(captures, args);
+        const provider = hasEdit(args)
+            ? editDraftProvider(draft.provider, draft.extractions, args).provider
+            : draft.provider;
+        return checkCaptured(entry, args.requestId ?? draft.requestId, provider);
+    });
+    const updateDraft = defineTool({
+        name: 'update_draft',
+        description: 'Replaces a draft\'s `responseMatches`, `responseRedactions`, '
+            + '`paramValues`, or `geoLocation` in place; the `draftId` stays '
+            + 'the same. Validates '
+            + 'regexes and selectors and rejects a matcher that bakes a captured '
+            + 'value in as a literal, or redactions that reveal more of the '
+            + 'captured response than the draft did. Returns the secret-free '
+            + 'provider and, unless `check` is false, a `check_matchers` '
+            + 'result for the edit. '
+            + 'Prefer `propose_provider` with a better request or target; use '
+            + 'this to narrow or fix what it drafted.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                captureId: { type: 'string' },
+                draftId: { type: 'string' },
+                responseMatches: MATCHES_SCHEMA,
+                responseRedactions: REDACTIONS_SCHEMA,
+                paramValues: PARAM_VALUES_SCHEMA,
+                geoLocation: {
+                    type: 'string',
+                    description: 'ISO country the published version\'s request goes out from, '
+                        + 'for example `US`, or `{{DYNAMIC_GEO}}` (the default) for '
+                        + 'the verifying user\'s own country. Pin a country when '
+                        + 'run_proof only verified with that `geoLocation`.',
+                },
+                check: {
+                    type: 'boolean',
+                    description: 'Default true: run `check_matchers` on the edit.',
+                },
+            },
+            required: ['captureId', 'draftId'],
+        },
+        annotations: { openWorldHint: false, destructiveHint: false },
+    }, async (args) => {
+        const { entry, draft } = resolveDraft(captures, args);
+        assert(hasEdit(args), badRequest('Pass at least one of responseMatches, responseRedactions, '
+            + 'paramValues, or geoLocation.'));
+        const edited = editDraftProvider(draft.provider, draft.extractions, args);
+        // Redactions are what the attestor doesn't see, so an edit may narrow
+        // them but never reveal more of the captured response than the draft.
+        const before = checkCaptured(entry, draft.requestId, draft.provider);
+        const check = checkCaptured(entry, draft.requestId, edited.provider);
+        assert(check.failedAt !== 'request' && check.failedAt !== 'redaction', badRequest('the edited recipe doesn\'t apply to the captured response '
+            + `(${check.failedAt}): ${check.reason}`));
+        const comparable = before.failedAt !== 'request'
+            && before.failedAt !== 'redaction';
+        assert(!comparable || check.revealedBytes <= before.revealedBytes, badRequest(`the edit reveals ${check.revealedBytes} bytes of the response `
+            + `to the attestor, more than the draft's ${before.revealedBytes}. `
+            + 'Keep redactions that hide everything except the proved values.'));
+        // The recipe changed, so an earlier replay no longer describes it.
+        const { lastReplay: _stale, ...rest } = draft;
+        void _stale;
+        entry.drafts.set(args.draftId, {
+            ...rest,
+            provider: edited.provider,
+            extractions: edited.extractions,
+        });
+        const verification = verificationWarnings(edited.provider);
+        return {
+            draftId: args.draftId,
+            provider: edited.provider,
+            secretRefs: draft.secretRefs,
+            ...(edited.warnings.length ? { warnings: edited.warnings } : {}),
+            ...(verification.length
+                ? { verificationWarnings: verification }
+                : {}),
+            ...(args.check === false ? {} : { check }),
+        };
+    });
+    return [checkMatchers, updateDraft];
+}
+function resolveDraft(captures, { captureId, draftId }) {
+    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}`));
+    return { entry, draft };
+}
+function hasEdit(edit) {
+    return edit.responseMatches !== undefined
+        || edit.responseRedactions !== undefined
+        || edit.paramValues !== undefined
+        || edit.geoLocation !== undefined;
+}
+function checkCaptured(entry, requestId, provider) {
+    const captured = entry.session.requests.get(requestId);
+    assert(captured, badRequest(`no captured request ${requestId}`));
+    assert(captured.responseBody, badRequest(`response body unavailable for ${requestId}`));
+    return { requestId, ...checkMatchersOffline(provider, captured) };
+}

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

@@ -27,7 +27,10 @@ export function podProofTools(attachRef, captures) {
             + 'instead of `run_proof` when the attach mode is "builder": the '
             + 'proof then reaches the target from the browser\'s own exit IP and '
             + 'country. Needs no `ownerAddress`; the pod signs with its own TEE '
-            + 'key.',
+            + 'key. It matches the browser\'s exit IP and country, not '
+            + 'necessarily its TLS fingerprint, so it is not a way past bot '
+            + 'protection: if `run_proof` reported '
+            + '`blocked-non-browser-client`, expect the same here.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -54,6 +57,7 @@ export function podProofTools(attachRef, captures) {
         return shapeRichProofResult(result, {
             provider: draft.provider,
             hasSecrets: Object.keys(draft.secrets).length > 0,
+            ...(draft.lastReplay ? { lastReplay: draft.lastReplay } : {}),
         });
     });
     return [tool];

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

@@ -11,7 +11,35 @@ export declare function shapeRichProofResult(result: ProofResult, opts: {
     provider: unknown;
     hasSecrets: boolean;
     attestorUrl?: string;
+    /** The draft's latest authenticated in-browser replay, when tracked. */
+    lastReplay?: {
+        status: number;
+        ok: boolean;
+    };
+    /** Where the attestor's request went out from. */
+    egress?: {
+        geoLocation?: string;
+    };
 }): Record<string, unknown>;
+export interface BlockedClientDiagnosis {
+    kind: 'blocked-non-browser-client';
+    /** HTTP status the attestor's request got, when the error carries one. */
+    status?: number;
+    /** Set when the same draft's in-browser replay succeeded. */
+    replayedInBrowser?: true;
+    likelyCause: string;
+    next: string;
+}
+/**
+ * Says when a failed proof looks like the site blocking non-browser clients:
+ * the attestor's request got 403/406/429/503, or a tiny or challenge-looking
+ * page where the browser got the real one. Returns undefined for verified
+ * proofs and other failures. The raw `error` stays on the result.
+ */
+export declare function diagnoseBlockedClient(result: Pick<ProofResult, 'verified' | 'error'>, lastReplay?: {
+    status: number;
+    ok: boolean;
+}, geoLocation?: string): BlockedClientDiagnosis | undefined;
 export interface ProofDiagnosis {
     attestor: AttestorCheckResult;
     likelyCause: string;