@reclaimprotocol/agent 0.1.36 → 0.1.38

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

@@ -15,7 +15,9 @@ 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 { exampleAppTool } from "./example-app.js";
 import { howItWorksTool } from "./how-it-works.js";
 import { liveViewTools } from "./live-view.js";
 import { podProofTools } from "./pod-proof.js";
@@ -73,8 +75,14 @@ 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(exampleAppTool());
         tools.push(createVersionFromCaptureTool(client, state.attach, state.captures));
     }
     return tools;

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/example-app.d.ts

@@ -0,0 +1,2 @@
+import { type RegisteredTool } from '../../server.ts';
+export declare function exampleAppTool(fetchFn?: typeof fetch): RegisteredTool;

package/lib/mcp/tools/agent/example-app.js

@@ -0,0 +1,167 @@
+/**
+ * `create_example_app` — write reclaimprotocol/builder-example into the
+ * developer's workspace, so a project with no app starts from a ready-to-run
+ * backend and frontend instead of agent-written code. The MCP server fetches
+ * the files itself (each checked against its git blob hash) and writes them at
+ * the workspace root: the coding agent's later `npm install` and `npm run dev`
+ * then run in the workspace it started in, not in a clone. The backend's
+ * `@reclaimprotocol/client` is set to the latest published version.
+ */
+import { badGateway, badRequest, conflict } from '@hapi/boom';
+import assert from 'node:assert';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, mkdtemp, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join } from 'node:path';
+import { defineTool } from "../../server.js";
+const REPO = 'reclaimprotocol/builder-example';
+const BACKEND_PACKAGE = join('packages', 'backend', 'package.json');
+const CLIENT_PACKAGE = '@reclaimprotocol/client';
+/** The example is ~50 small files; anything far past that isn't it. */
+const MAX_FILES = 500;
+const MAX_BYTES = 10000000;
+export function exampleAppTool(fetchFn = fetch) {
+    return defineTool({
+        name: 'create_example_app',
+        description: 'Writes the Reclaim example app (reclaimprotocol/builder-example: '
+            + 'a Fastify backend and a Vite frontend that create sessions, '
+            + 'verify callbacks, and render every verification state) into '
+            + '`projectDir`, and sets its backend to the latest '
+            + '`@reclaimprotocol/client`. Use it when the workspace has no app '
+            + 'yet, with the workspace root you were started in as '
+            + '`projectDir`; don\'t clone the repository yourself. Refuses '
+            + 'when a file it would write already exists with different '
+            + 'content. Returns the commit, file count, client version, and '
+            + 'next steps.',
+        inputSchema: {
+            type: 'object',
+            required: ['projectDir'],
+            properties: {
+                projectDir: {
+                    type: 'string',
+                    description: 'Absolute path of the workspace root you were started in.',
+                },
+            },
+        },
+        annotations: { openWorldHint: true, destructiveHint: false },
+    }, async ({ projectDir }) => {
+        assert(isAbsolute(projectDir), badRequest('`projectDir` must be an absolute path.'));
+        const commit = await latestCommit();
+        const files = await listFiles(commit);
+        const clientVersion = await latestClientVersion();
+        const staged = await Promise.all(files.map(async (file) => {
+            const bytes = await download(commit, file);
+            return {
+                path: file.path,
+                bytes: file.path === BACKEND_PACKAGE
+                    ? withClientVersion(bytes, clientVersion)
+                    : bytes,
+            };
+        }));
+        const conflicts = staged
+            .filter(({ path, bytes }) => {
+            const dest = join(projectDir, path);
+            return existsSync(dest) && !readFileSync(dest).equals(bytes);
+        })
+            .map(({ path }) => path);
+        assert(!conflicts.length, conflict('These files already exist with different content: '
+            + `${conflicts.join(', ')}. Ask the developer whether to use `
+            + 'another directory or move them.'));
+        // Stage inside projectDir, so the moves below stay on one filesystem.
+        const tmp = await mkdtemp(join(projectDir, '.reclaim-example-'));
+        try {
+            for (const { path, bytes } of staged) {
+                await mkdir(dirname(join(tmp, path)), { recursive: true });
+                await writeFile(join(tmp, path), bytes);
+            }
+            for (const { path } of staged) {
+                const dest = join(projectDir, path);
+                await mkdir(dirname(dest), { recursive: true });
+                await rename(join(tmp, path), dest);
+            }
+        }
+        finally {
+            await rm(tmp, { recursive: true, force: true });
+        }
+        return {
+            projectDir,
+            repository: `https://github.com/${REPO}`,
+            commit,
+            files: staged.length,
+            clientVersion,
+            next: [
+                'Call issue_org_token with this projectDir and envFile '
+                    + '"packages/backend/.env".',
+                'Run `npm install`, then `npm run dev`, from projectDir. The '
+                    + 'backend listens on port 3000; the app opens at '
+                    + 'http://localhost:5173.',
+                'Call proxy_callback_events({ port: 3000, path: '
+                    + '"/reclaim/callback" }).',
+                'Put the provider in packages/backend/config.json and restart '
+                    + 'the backend.',
+            ],
+        };
+    });
+    async function latestCommit() {
+        const res = await fetchFn(`https://api.github.com/repos/${REPO}/commits/main`, { headers: { Accept: 'application/vnd.github.sha' } });
+        assert(res.ok, badGateway(`${REPO} commit lookup: HTTP ${res.status}`));
+        const text = await res.text();
+        const commit = text.trim();
+        assert(/^[0-9a-f]{40}$/.test(commit), badGateway('invalid commit SHA'));
+        return commit;
+    }
+    async function listFiles(commit) {
+        const res = await fetchFn(`https://api.github.com/repos/${REPO}/git/trees/${commit}?recursive=1`, { headers: { Accept: 'application/vnd.github+json' } });
+        assert(res.ok, badGateway(`${REPO} file listing: HTTP ${res.status}`));
+        const tree = await res.json();
+        assert(typeof tree === 'object' && tree !== null && 'tree' in tree
+            && Array.isArray(tree.tree) && !('truncated' in tree && tree.truncated), badGateway(`unexpected ${REPO} file listing`));
+        const files = tree.tree
+            .filter((e) => {
+            return typeof e === 'object' && e !== null && 'type' in e
+                && e.type === 'blob';
+        })
+            .map((entry) => {
+            assert(typeof entry === 'object' && entry !== null
+                && 'path' in entry && typeof entry.path === 'string'
+                && entry.path.split('/').every((s) => /^[\w@.-]+$/.test(s)
+                    && s !== '.' && s !== '..' && s !== '.git')
+                && 'sha' in entry && typeof entry.sha === 'string'
+                && 'size' in entry && typeof entry.size === 'number', badGateway(`unexpected entry in the ${REPO} file listing`));
+            return { path: entry.path, sha: entry.sha, size: entry.size };
+        });
+        assert(files.length > 0 && files.length <= MAX_FILES
+            && files.reduce((n, f) => n + f.size, 0) <= MAX_BYTES, badGateway(`unexpected ${REPO} size`));
+        return files;
+    }
+    async function download(commit, file) {
+        const res = await fetchFn(`https://raw.githubusercontent.com/${REPO}/${commit}/${file.path}`);
+        assert(res.ok, badGateway(`${file.path}: HTTP ${res.status}`));
+        const bytes = Buffer.from(await res.arrayBuffer());
+        assert(gitBlobSha(bytes) === file.sha, badGateway(`${file.path} failed its integrity check`));
+        return bytes;
+    }
+    async function latestClientVersion() {
+        const res = await fetchFn(`https://registry.npmjs.org/${CLIENT_PACKAGE.replace('/', '%2f')}/latest`);
+        assert(res.ok, badGateway(`npm ${CLIENT_PACKAGE}: HTTP ${res.status}`));
+        const body = await res.json();
+        assert(typeof body === 'object' && body !== null && 'version' in body
+            && typeof body.version === 'string'
+            && /^\d+\.\d+\.\d+$/.test(body.version), badGateway(`npm ${CLIENT_PACKAGE}: no version`));
+        return body.version;
+    }
+}
+/** The backend's package.json with the client range set to `^version`. */
+function withClientVersion(bytes, version) {
+    const text = bytes.toString('utf8');
+    const next = text.replace(/("@reclaimprotocol\/client"\s*:\s*")[^"]*(")/, (_, open, close) => `${open}^${version}${close}`);
+    assert(next !== text || text.includes(`"^${version}"`), badGateway(`${BACKEND_PACKAGE} has no ${CLIENT_PACKAGE} dependency`));
+    return Buffer.from(next);
+}
+/** Git's blob object id: sha1 of `blob <size>\0<content>`. */
+function gitBlobSha(bytes) {
+    return createHash('sha1')
+        .update(`blob ${bytes.length}\0`)
+        .update(bytes)
+        .digest('hex');
+}

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;

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

@@ -117,6 +117,10 @@ export function shapeRichProofResult(result, opts) {
     if (result.errorKind !== undefined) {
         out.errorKind = result.errorKind;
     }
+    const blocked = diagnoseBlockedClient(result, opts.lastReplay, opts.egress?.geoLocation);
+    if (blocked !== undefined) {
+        out.diagnosis = blocked;
+    }
     // Trim the LLM-visible logs — full stream goes to runLogPath.
     if (result.attestorLogs !== undefined && result.attestorLogs.length > 0) {
         const logs = result.verified
@@ -158,6 +162,74 @@ export function shapeRichProofResult(result, opts) {
     }
     return out;
 }
+/** HTTP statuses a site's bot protection answers non-browser clients with. */
+const BLOCKING_STATUSES = new Set([403, 406, 429, 503]);
+/** Markers of a bot-protection / challenge page rather than real content. */
+const CHALLENGE_BODY = new RegExp([
+    'captcha', 'challenge', 'cf-chl', 'cf-ray', 'just a moment',
+    'access denied', 'request unsuccessful', '_incapsula_', 'px-captcha',
+    'perimeterx', 'datadome', 'akamai', 'bot detection', 'enable javascript',
+    'are you a robot', 'unusual traffic',
+].join('|'), 'i');
+/** Below this, a response the browser rendered with the value in it is
+ *  likely a shell or challenge page served to a non-browser client. */
+const TINY_BODY_BYTES = 4096;
+/**
+ * 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 function diagnoseBlockedClient(result, lastReplay, geoLocation) {
+    if (result.verified || !result.error) {
+        return undefined;
+    }
+    const replayedInBrowser = lastReplay?.ok === true;
+    const statusMatch = new RegExp('Expected status 2xx, got (\\d{3})|Provider returned error (\\d{3})').exec(result.error);
+    const status = Number(statusMatch?.[1] ?? statusMatch?.[2]) || undefined;
+    const blockedStatus = status !== undefined && BLOCKING_STATUSES.has(status);
+    if (!blockedStatus && !(replayedInBrowser && challengeBody(result.error))) {
+        return undefined;
+    }
+    return {
+        kind: 'blocked-non-browser-client',
+        ...(status !== undefined ? { status } : {}),
+        ...(replayedInBrowser ? { replayedInBrowser: true } : {}),
+        likelyCause: (replayedInBrowser
+            ? 'The same request succeeded from inside the browser, but '
+            : '')
+            + 'the site answered the attestor'
+            + (geoLocation
+                ? `, whose request went out from ${geoLocation}, with `
+                : ', whose request went out from its own network, with ')
+            + (blockedStatus ? `HTTP ${status}` : 'a challenge or shell page')
+            + '. The site blocks traffic from that country, or non-browser '
+            + 'clients (bot protection or TLS fingerprinting). Copying headers or '
+            + 'cookies will not help.',
+        next: 'If the site serves one country (for example, a US airline), retry '
+            + 'run_proof once with `geoLocation` set to that country. If that '
+            + 'verifies, pin it with update_draft({ geoLocation }) so the '
+            + 'published version goes out from there too. Otherwise, try a '
+            + 'different endpoint that returns the value, such as a JSON API the '
+            + 'page calls (find_requests_containing), then propose and prove '
+            + 'that. If none works, stop and report to the developer that this '
+            + 'site blocks the attestor. Do not tweak headers.',
+    };
+}
+/** True when an attestor error embeds a response element (base64, from a
+ *  regex redaction that didn't match) that is tiny or a challenge page. */
+function challengeBody(error) {
+    const b64 = /does not match found element '([A-Za-z0-9+/=]*)/.exec(error)?.[1];
+    if (b64 === undefined) {
+        return false;
+    }
+    // "Tiny" only means something for a whole document; an xPath-selected
+    // element is small by design.
+    const text = Buffer.from(b64, 'base64').toString('utf8');
+    const tinyDocument = Buffer.byteLength(text) < TINY_BODY_BYTES
+        && /<!doctype|<html/i.test(text);
+    return tinyDocument || CHALLENGE_BODY.test(text);
+}
 /**
  * When an unverified proof failed with a network-like error, runs the
  * attestor check once and says whether the attestor or the target site is the

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

@@ -1,9 +1,16 @@
+import { runAttestorProof } from '../../../proof/attestor.ts';
 import { checkAttestor } from '../../../proof/check-attestor.ts';
 import type { RegisteredTool } from '../../server.ts';
 import type { CaptureStore } from './capture.ts';
+export interface ProofEgress {
+    /** ISO country (or param template) the attestor's request goes out from;
+     *  absent when it goes out from the attestor's own network. */
+    geoLocation?: string;
+    source: 'argument' | 'draft' | 'developer-ip' | 'none';
+}
 /** The shared authoring tools mapped to the MCP's shape: resolve each call's
  *  local backend from `args.captureId`, and widen the input schema — every tool
  *  takes `captureId`; `run_proof` also gets the credential-aware contract. The
  *  tools are authored plain in `../../../authoring`; this only wraps them with
  *  `extendTool` (handlers untouched — loose arg parse keeps `captureId`). */
-export declare function sharedAuthoringTools(captures: CaptureStore, check?: typeof checkAttestor): RegisteredTool[];
+export declare function sharedAuthoringTools(captures: CaptureStore, check?: typeof checkAttestor, runProof?: typeof runAttestorProof, lookupCountry?: () => Promise<string | undefined>): RegisteredTool[];