@reclaimprotocol/agent 0.1.36 → 0.1.37

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;

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[];