@reclaimprotocol/agent 0.1.3 → 0.1.5

package/lib/cdp/capture-engine.js

@@ -25,6 +25,64 @@ export function stripPseudoHeaders(headers) {
     }
     return out;
 }
+/** Extensions for static assets we never prove over — scripts, styles, fonts,
+ *  images, media, source maps. A real page pulls hundreds of these; tracking
+ *  them (and fetching their bodies) just bloats the request map and body store
+ *  with traffic no recipe ever matches. Note: `.json` is deliberately absent —
+ *  that's the API shape recipes care about. */
+const STATIC_ASSET_EXTENSIONS = new Set([
+    'js', 'mjs', 'cjs', 'css', 'map',
+    'png', 'jpg', 'jpeg', 'gif', 'svg', 'webp', 'avif', 'ico', 'bmp',
+    'woff', 'woff2', 'ttf', 'otf', 'eot',
+    'mp4', 'webm', 'mp3', 'ogg', 'wav',
+]);
+/** True when the URL's path names a static asset (by file extension; query and
+ *  hash are ignored, so `chunk.js?v=1` still counts). The capture engine drops
+ *  these up front — they never carry JSON/HTML a recipe matches. */
+export function isStaticAsset(url) {
+    let path;
+    try {
+        path = new URL(url).pathname;
+    }
+    catch {
+        path = url.split(/[?#]/)[0] || url;
+    }
+    // Extension of the last path segment only, so `/v1.2/data` isn't misread.
+    const base = path.slice(path.lastIndexOf('/') + 1);
+    const dot = base.lastIndexOf('.');
+    if (dot <= 0) {
+        return false;
+    }
+    return STATIC_ASSET_EXTENSIONS.has(base.slice(dot + 1).toLowerCase());
+}
+/** Response Content-Types for static assets. The URL-extension filter misses
+ *  extension-less bundler/CDN URLs (e.g. `/assets/3b8f1c`), so we also drop by
+ *  MIME at response time. `text/html`, `application/json`, and `text/plain`
+ *  are NOT here — those are the document/API shapes recipes match. */
+const STATIC_ASSET_MIME_EXACT = new Set([
+    'text/css',
+    'application/javascript', 'text/javascript', 'application/x-javascript',
+    'application/ecmascript', 'text/ecmascript',
+    'application/wasm',
+    'application/font-woff', 'application/font-woff2',
+    'application/vnd.ms-fontobject', 'application/x-font-ttf',
+]);
+const STATIC_ASSET_MIME_PREFIXES = ['image/', 'font/', 'audio/', 'video/'];
+/** True when a response Content-Type is a static asset (scripts/styles/fonts/
+ *  images/media). Parameters (`; charset=…`) and case are ignored. */
+export function isStaticAssetMime(mimeType) {
+    if (!mimeType) {
+        return false;
+    }
+    const m = mimeType.toLowerCase().split(';')[0].trim();
+    if (!m) {
+        return false;
+    }
+    if (STATIC_ASSET_MIME_PREFIXES.some((p) => m.startsWith(p))) {
+        return true;
+    }
+    return STATIC_ASSET_MIME_EXACT.has(m);
+}
 export function createCaptureEngine(opts) {
     const captureId = randomUUID();
     const requests = new Map();
@@ -79,6 +137,13 @@ export function createCaptureEngine(opts) {
         pendingResponseExtra.set(requestId, { ...buffered, ...clean });
     }
     function onRequestWillBeSent(p) {
+        // Static assets never match a recipe — never track them (so we don't
+        // fetch their bodies or grow the store). Drop any extra-info that raced
+        // ahead of this event so it can't linger.
+        if (isStaticAsset(p.request.url)) {
+            pendingRequestExtra.delete(p.requestId);
+            return;
+        }
         const f = {
             requestId: p.requestId,
             method: p.request.method,
@@ -100,6 +165,19 @@ export function createCaptureEngine(opts) {
     function onResponseReceived(p) {
         const f = inFlight.get(p.requestId);
         if (!f) {
+            // No in-flight entry → the request was skipped (e.g. a static asset)
+            // or never seen. Discard any buffered response extra-info so a skipped
+            // asset can't leave a dangling entry.
+            pendingResponseExtra.delete(p.requestId);
+            return;
+        }
+        // Second-line asset filter by Content-Type: catches extension-less
+        // bundler/CDN URLs the request-time URL filter can't. Forget the
+        // in-flight entry so it never reaches `requests` and a later
+        // loadingFinished/extra-info for it becomes a no-op.
+        if (isStaticAssetMime(p.response.mimeType)) {
+            inFlight.delete(p.requestId);
+            pendingResponseExtra.delete(p.requestId);
             return;
         }
         const captured = {

package/lib/cdp/capture.d.ts

@@ -6,6 +6,6 @@
  */
 import type CDP from 'chrome-remote-interface';
 import { type CaptureSession, type StartCaptureOptions } from './capture-engine.ts';
-export { stripPseudoHeaders } from './capture-engine.ts';
+export { isStaticAsset, isStaticAssetMime, stripPseudoHeaders, } from './capture-engine.ts';
 export type { CaptureSession, StartCaptureOptions } from './capture-engine.ts';
 export declare function startCapture(tab: CDP.Client, opts?: StartCaptureOptions): Promise<CaptureSession>;

package/lib/cdp/capture.js

@@ -1,5 +1,5 @@
 import { createCaptureEngine, } from "./capture-engine.js";
-export { stripPseudoHeaders } from "./capture-engine.js";
+export { isStaticAsset, isStaticAssetMime, stripPseudoHeaders, } from "./capture-engine.js";
 export async function startCapture(tab, opts = {}) {
     const engine = createCaptureEngine({
         ...(opts.maxBodyBytes !== undefined && { maxBodyBytes: opts.maxBodyBytes }),

package/lib/consts.d.ts

@@ -16,12 +16,12 @@
  * Each var's default/fallback literal is co-located with its getter.
  */
 import { DEFAULT_BASE_URL } from '@reclaimprotocol/client';
-import { DEFAULT_OLD_API_URL } from './old/client.ts';
+import { DEFAULT_OLD_API_URL, DEFAULT_OLD_LOGS_URL } from './old/client.ts';
 /** Public attestor websocket URL — fallback for `RECLAIM_ATTESTOR_URL`. */
 export declare const FALLBACK_ATTESTOR_URL = "wss://attestor.reclaimprotocol.org:444/ws";
 /** The devtools dashboard login page — fallback for `RECLAIM_OLD_LOGIN_URL`. */
 export declare const DEFAULT_LOGIN_URL = "https://dev.reclaimprotocol.org";
-export { DEFAULT_BASE_URL, DEFAULT_OLD_API_URL };
+export { DEFAULT_BASE_URL, DEFAULT_OLD_API_URL, DEFAULT_OLD_LOGS_URL };
 /** Pino log level. Read once at logger construction, so an eager const is
  *  safe (no test mutates LOG_LEVEL at runtime). */
 export declare const LOG_LEVEL: string;
@@ -45,6 +45,8 @@ export declare function chromePath(): string | undefined;
 export declare function agentDisabled(): boolean;
 /** Old-devtools backend base URL. */
 export declare function oldApiUrl(): string;
+/** Old-devtools analytics-logs service base URL (separate host). */
+export declare function oldLogsUrl(): string;
 /** Builder backend base URL. Shared by mcp/start and the verification tool. */
 export declare function apiUrl(): string;
 /** Explicit builder API token (overrides the cached session token). */

package/lib/consts.js

@@ -18,7 +18,7 @@
 import { DEFAULT_BASE_URL } from '@reclaimprotocol/client';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { DEFAULT_OLD_API_URL } from "./old/client.js";
+import { DEFAULT_OLD_API_URL, DEFAULT_OLD_LOGS_URL } from "./old/client.js";
 // ---------------------------------------------------------------------------
 // Default / fallback literals (used only as env fallbacks).
 // ---------------------------------------------------------------------------
@@ -28,7 +28,7 @@ export const FALLBACK_ATTESTOR_URL = 'wss://attestor.reclaimprotocol.org:444/ws'
 export const DEFAULT_LOGIN_URL = 'https://dev.reclaimprotocol.org';
 // Re-export the two non-env-fallback defaults so callers can keep importing
 // their URL defaults from a single place if they wish.
-export { DEFAULT_BASE_URL, DEFAULT_OLD_API_URL };
+export { DEFAULT_BASE_URL, DEFAULT_OLD_API_URL, DEFAULT_OLD_LOGS_URL };
 // ---------------------------------------------------------------------------
 // Logging.
 // ---------------------------------------------------------------------------
@@ -79,6 +79,10 @@ export function agentDisabled() {
 export function oldApiUrl() {
     return process.env.RECLAIM_OLD_API_URL || DEFAULT_OLD_API_URL;
 }
+/** Old-devtools analytics-logs service base URL (separate host). */
+export function oldLogsUrl() {
+    return process.env.RECLAIM_OLD_LOGS_URL || DEFAULT_OLD_LOGS_URL;
+}
 /** Builder backend base URL. Shared by mcp/start and the verification tool. */
 export function apiUrl() {
     return process.env.RECLAIM_API_URL || DEFAULT_BASE_URL;

package/lib/mcp/api/operations.gen.js

@@ -92,7 +92,7 @@ export const MCP_TOOLS = {
         }),
     },
     "AdminProviders": {
-        description: "All verifications (admin-only)\n\nAdmin only. Lists all verifications across all organizations. Supports filtering by visibility, status, and free-text search on title/domain/slug.",
+        description: "All providers (admin-only)\n\nAdmin only. Lists all providers across all organizations. Supports filtering by visibility, status, and free-text search on title/domain/slug.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -455,7 +455,7 @@ export const MCP_TOOLS = {
         }),
     },
     "CreateProvider": {
-        description: "Create a verification\n\nCreate a new Reclaim verification. Use this only after `providers` returned nothing useful for the domain. The caller must be an active member of the target organization.\nCreates a new verification in the specified organization. `visibility` is coerced to `PRIVATE` at creation regardless of what's sent; the author may toggle to `PUBLIC` later via `PATCH /providers/{id}`. While `PRIVATE`, versions go to the go live freely; once `PUBLIC`, non-admin versions need admin review. See `Provider.visibility`.\nThe server also seeds an initial `0.1.0` version on the `draft` branch in the same transaction so the verification is immediately editable. Its `initialUrl` defaults to `https://<domain>`; all other version fields fall back to their schema-declared defaults (structured verification, empty requests, empty web settings). `Provider.latestVersion` stays `null` until the draft is promoted to the live channel.",
+        description: "Create a provider\n\nCreate a new Reclaim provider. Use this only after `providers` returned nothing useful for the domain. The caller must be an active member of the target organization.\nCreates a new provider in the specified organization. `visibility` is coerced to `PRIVATE` at creation regardless of what's sent; the author may toggle to `PUBLIC` later via `PATCH /providers/{id}`. While `PRIVATE`, versions go to the go live freely; once `PUBLIC`, non-admin versions need admin review. See `Provider.visibility`.\nThe server also seeds an initial `0.1.0` version on the `draft` branch in the same transaction so the provider is immediately editable. Its `initialUrl` defaults to `https://<domain>`; all other version fields fall back to their schema-declared defaults (a `structured` verificationType, empty requests, empty web settings). `Provider.latestVersion` stays `null` until the draft is promoted to the live channel.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -582,7 +582,7 @@ export const MCP_TOOLS = {
         }),
     },
     "CreateProviderVersion": {
-        description: "Create a new verification version\n\nCreates a new version of the verification. The starting branch\ndepends on the verification's `visibility` and the caller's role:\n\n- `PRIVATE` verification (any caller): the live channel (no review).\n\n- `PUBLIC` verification, admin caller (Reclaim staff): the live channel\n  (no review).\n\n- `PUBLIC` verification, non-admin caller: `draft` (or `ai` if\n  authored by the AI assistant). Must pass review (see\n  `POST /providers/{id}/versions/{version}/review`) before\n  reaching the live channel.\n",
+        description: "Create a new provider version\n\nCreates a new version of the provider. The starting branch\ndepends on the provider's `visibility` and the caller's role:\n\n- `PRIVATE` provider (any caller): the live channel (no review).\n\n- `PUBLIC` provider, admin caller (Reclaim staff): the live channel\n  (no review).\n\n- `PUBLIC` provider, non-admin caller: `draft` (or `ai` if\n  authored by the AI assistant). Must pass review (see\n  `POST /providers/{id}/versions/{version}/review`) before\n  reaching the live channel.\n",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -606,7 +606,7 @@ export const MCP_TOOLS = {
                 "body": {
                     "type": "object",
                     "additionalProperties": false,
-                    "description": "Body for creating a new version of a provider. Every new version starts on the `draft` branch — see `CreateProviderVersion`. The request body never sets `branch` directly; going live is a separate, explicit step (publish for PRIVATE, submit-for-review → approve for PUBLIC). The version's `verificationType` is always `structured` and is not settable here; a `prompt` field is reserved for a future AI authoring flow and is also not accepted on this surface.",
+                    "description": "Body for creating a new version of a provider. Every new version starts on the `draft` branch — see `CreateProviderVersion`. The request body never sets `branch` directly; going live is a separate, explicit step (publish for PRIVATE, submit-for-review → approve for PUBLIC). `verificationType` defaults to `structured`; pass `llm` with a `prompt` to author an AI-verification provider.",
                     "required": [
                         "initialUrl",
                         "requests",
@@ -614,6 +614,20 @@ export const MCP_TOOLS = {
                         "webSettings"
                     ],
                     "properties": {
+                        "verificationType": {
+                            "type": "string",
+                            "description": "How a provider version verifies a claim. `structured` uses the explicit match rules on this version (the `matches` / `allowedJsMatches` and related settings). `llm` defers the verification decision to a language model and requires `prompt` to be set.",
+                            "enum": [
+                                "llm",
+                                "structured"
+                            ]
+                        },
+                        "prompt": {
+                            "type": "string",
+                            "description": "Extraction prompt, used (and required) when `verificationType` is `llm`.",
+                            "minLength": 0,
+                            "maxLength": 1000000
+                        },
                         "version": {
                             "type": "object",
                             "additionalProperties": false,
@@ -1165,7 +1179,7 @@ export const MCP_TOOLS = {
         }),
     },
     "DecideProviderVersionReview": {
-        description: "Record a decision on a verification version review\n\nAdmin only (Reclaim staff). Approves or rejects a verification version currently on the `in_review` branch. `APPROVED` clears the branch tag and promotes the version to the live channel; `REJECTED` moves it to the `rejected` branch where the author can address feedback and resubmit. A rejected version stays rejected — the author either fixes and resubmits, or abandons it.\nUntil RBAC is designed, \"admin\" is detected via the user's email domain (`@reclaimprotocol.org`). Non-admin callers receive a 403.",
+        description: "Record a decision on a provider version review\n\nAdmin only (Reclaim staff). Approves or rejects a provider version currently on the `in_review` branch. `APPROVED` clears the branch tag and promotes the version to the live channel; `REJECTED` moves it to the `rejected` branch where the author can address feedback and resubmit. A rejected version stays rejected — the author either fixes and resubmits, or abandons it.\nUntil RBAC is designed, \"admin\" is detected via the user's email domain (`@reclaimprotocol.org`). Non-admin callers receive a 403.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -1330,7 +1344,7 @@ export const MCP_TOOLS = {
         }),
     },
     "DeleteProvider": {
-        description: "Delete a verification\n\nOwner of the verification's organization only. Soft-archives the verification (sets `status` to `ARCHIVED`) so historical references remain resolvable. Supports optimistic concurrency via `If-Match`.",
+        description: "Delete a provider\n\nOwner of the provider's organization only. Soft-archives the provider (sets `status` to `ARCHIVED`) so historical references remain resolvable. Supports optimistic concurrency via `If-Match`.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -1373,7 +1387,7 @@ export const MCP_TOOLS = {
         }),
     },
     "DeleteProviderVersion": {
-        description: "Delete a verification version\n\nSoft-archives a version on the `draft`, `ai`, or `rejected` branch — sets `status` to `ARCHIVED` so history is preserved. Trunk (live) and `in_review` versions cannot be archived this way; archive the parent verification instead. Supports optimistic concurrency via `If-Match`.",
+        description: "Delete a provider version\n\nSoft-archives a version on the `draft`, `ai`, or `rejected` branch — sets `status` to `ARCHIVED` so history is preserved. Trunk (live) and `in_review` versions cannot be archived this way; archive the parent provider instead. Supports optimistic concurrency via `If-Match`.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -1461,7 +1475,7 @@ export const MCP_TOOLS = {
         }),
     },
     "DiscoverResolve": {
-        description: "Resolve a website + data points to verification providers\n\nProvider resolution: given a website and the data points the user wants their users to prove, return the smallest set of existing providers whose data points COVER the selection (greedy combine), the `requiredContext` inputs the consumer must supply, and any `uncovered` points no provider exposes yet (`needsCreation` is true then — author a provider with the agent tools). When the chosen providers can be fused into one (same start page, no clashing page scripts) `merge.mergeable` is true.\n\nAgent flow: pick a website (`GET /discover/data-points` lists what's verifiable there), confirm the data points with the user, call this to get the `providers` + `requiredContext`, collect those context values from the user, then `POST /verifications/sessions` with `providers` (pass every id) and `context` to mint a verification.",
+        description: "Resolve a website + data points to providers\n\nProvider resolution: given a website and the data points the user wants their users to prove, return the smallest set of existing providers whose data points COVER the selection (greedy combine), the `requiredContext` inputs the consumer must supply, and any `uncovered` points no provider exposes yet (`needsCreation` is true then — author a provider with the agent tools). When the chosen providers can be fused into one (same start page, no clashing page scripts) `merge.mergeable` is true.\n\nAgent flow: pick a website (`GET /discover/data-points` lists what's verifiable there), confirm the data points with the user, call this to get the `providers` + `requiredContext`, collect those context values from the user, then `POST /verifications/sessions` with `providers` (pass every id) and `context` to mint a verification.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -1718,7 +1732,7 @@ export const MCP_TOOLS = {
         }),
     },
     "GetProvider": {
-        description: "Get a verification\n\nFetch a single Reclaim verification by id. Returns every field needed\nto integrate it into a flow: domain, the live version (initialUrl + requests),\nand the data points it can prove. Use `providers` first if you only\nhave a query string.\n\nReturns the verification record.\n\n**Canonical URL.** For SEO and stable sharing, the canonical\nHTML URL for a verification is `/providers/{providerId}/{slug}`\n(see `GetProviderBySlug`). HTML callers (`Accept: text/html`)\nthat hit this route — which omits the slug — receive a `301`\nredirect to the slugged URL. JSON callers\n(`Accept: application/json`) receive the body directly without\nredirect; the slug is on the response.\n",
+        description: "Get a provider\n\nFetch a single Reclaim provider by id. Returns every field needed\nto integrate it into a flow: domain, the live version (initialUrl + requests),\nand the data points it can prove. Use `providers` first if you only\nhave a query string.\n\nReturns the provider record.\n\n**Canonical URL.** For SEO and stable sharing, the canonical\nHTML URL for a provider is `/providers/{providerId}/{slug}`\n(see `GetProviderBySlug`). HTML callers (`Accept: text/html`)\nthat hit this route — which omits the slug — receive a `301`\nredirect to the slugged URL. JSON callers\n(`Accept: application/json`) receive the body directly without\nredirect; the slug is on the response.\n",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -1751,7 +1765,7 @@ export const MCP_TOOLS = {
         }),
     },
     "GetProviderVersion": {
-        description: "Get a specific verification version",
+        description: "Get a specific provider version",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -2069,7 +2083,7 @@ export const MCP_TOOLS = {
         }),
     },
     "ListProviderVersions": {
-        description: "List a verification's versions\n\nLists versions visible to the caller. Non-public branches (`ai`, `draft`, `in_review`, `rejected`) are only visible to members of the verification's owning organization.",
+        description: "List a provider's versions\n\nLists versions visible to the caller. Non-public branches (`ai`, `draft`, `in_review`, `rejected`) are only visible to members of the provider's owning organization.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -2218,7 +2232,7 @@ export const MCP_TOOLS = {
         }),
     },
     "Providers": {
-        description: "Search verifications\n\nSearch published Reclaim verifications by domain or data point. A verification is the recipe an end-user follows to prove something about themselves (e.g. \"I have N followers on Twitter\"). Returns a list of matches. Call this BEFORE `create_provider` — most popular domains already have a public verification you can reuse.\nCatalog page listing all verifications. Returns a paginated list of verifications the caller can see. Public verifications are visible to everyone; private verifications are only visible to org members.",
+        description: "Search providers\n\nSearch published Reclaim providers by domain or data point. A provider is the recipe an end-user follows to prove something about themselves (e.g. \"I have N followers on Twitter\"). Returns a list of matches. Call this BEFORE `create_provider` — most popular domains already have a public provider you can reuse.\nCatalog page listing all providers. Returns a paginated list of providers the caller can see. Public providers are visible to everyone; private providers are only visible to org members.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -2262,7 +2276,7 @@ export const MCP_TOOLS = {
         }),
     },
     "PublishProviderVersion": {
-        description: "Publish a draft version directly (PRIVATE providers only)\n\nPublishes a verification version on the `draft` branch directly to the live channel (trunk). Only allowed for PRIVATE providers — PUBLIC providers must use the review flow (`POST .../review` → admin decision). On success the version's branch transitions from `draft` to `null` (trunk/live).",
+        description: "Publish a draft version directly (PRIVATE providers only)\n\nPublishes a provider version on the `draft` branch directly to the live channel (trunk). Only allowed for PRIVATE providers — PUBLIC providers must use the review flow (`POST .../review` → admin decision). On success the version's branch transitions from `draft` to `null` (trunk/live).",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -2503,7 +2517,7 @@ export const MCP_TOOLS = {
         }),
     },
     "SubmitProviderVersionForReview": {
-        description: "Submit a verification version for review\n\nSubmits a verification version (currently on the `draft` or `rejected` branch) for admin review. On success the version's branch transitions to `in_review`. Callable by any authenticated member of the verification's owning org. Meaningful only on `PUBLIC` verifications — on `PRIVATE` verifications new versions go to the live channel directly and never need review.",
+        description: "Submit a provider version for review\n\nSubmits a provider version (currently on the `draft` or `rejected` branch) for admin review. On success the version's branch transitions to `in_review`. Callable by any authenticated member of the provider's owning org. Meaningful only on `PUBLIC` providers — on `PRIVATE` providers new versions go to the live channel directly and never need review.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -2552,7 +2566,7 @@ export const MCP_TOOLS = {
         }),
     },
     "TransferProvider": {
-        description: "Transfer a verification to a different workspace\n\nAdmin-only. Moves the verification's `orgId` to the supplied workspace; preserves slug, versions, members. SQL function `builder.transfer_provider` enforces the admin gate and target existence atomically.",
+        description: "Transfer a provider to a different workspace\n\nAdmin-only. Moves the provider's `orgId` to the supplied workspace; preserves slug, versions, members. SQL function `builder.transfer_provider` enforces the admin gate and target existence atomically.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -2705,7 +2719,7 @@ export const MCP_TOOLS = {
         }),
     },
     "UpdateProvider": {
-        description: "Update a verification\n\nUpdate a Reclaim verification's metadata. Partial PATCH — pass only fields you want to change. The caller must be an active member of the owning organization. To change the verification's recipe (initialUrl, requests, …) cut a new version via the dashboard. Use `seo` to control how the verification appears in search results and social shares; omit a subfield to keep the server default.\nCaller must be a member of the verification's owning organization. `id`, `orgId`, and `slug` are immutable. Supports optimistic concurrency via `If-Match`.",
+        description: "Update a provider\n\nUpdate a Reclaim provider's metadata. Partial PATCH — pass only fields you want to change. The caller must be an active member of the owning organization. To change the provider's recipe (initialUrl, requests, …) cut a new version via the dashboard. Use `seo` to control how the provider appears in search results and social shares; omit a subfield to keep the server default.\nCaller must be a member of the provider's owning organization. `id`, `orgId`, and `slug` are immutable. Supports optimistic concurrency via `If-Match`.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -2840,7 +2854,7 @@ export const MCP_TOOLS = {
         }),
     },
     "UpdateProviderVersion": {
-        description: "Update a verification version\n\nMutable only while the version is on the `draft` or `rejected` branch. Versions on `in_review` or the live channel reject all writes here. Caller must be a member of the verification's owning organization. Supports optimistic concurrency via `If-Match`.",
+        description: "Update a provider version\n\nMutable only while the version is on the `draft` or `rejected` branch. Versions on `in_review` or the live channel reject all writes here. Caller must be a member of the provider's owning organization. Supports optimistic concurrency via `If-Match`.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -2880,13 +2894,27 @@ export const MCP_TOOLS = {
                 "body": {
                     "type": "object",
                     "additionalProperties": false,
-                    "description": "Partial update of a provider version. Mutable only while the version is on the `draft` or `rejected` branch; versions on `in_review` or the live channel reject all writes here. The semver does not change on update — `build_number` increments instead, giving callers a monotonic revision counter without touching the (major, minor, patch) PK. `verificationType` / `prompt` are not accepted; see `ProviderVersion` for why.",
+                    "description": "Partial update of a provider version. Mutable only while the version is on the `draft` or `rejected` branch; versions on `in_review` or the live channel reject all writes here. The semver does not change on update — `build_number` increments instead, giving callers a monotonic revision counter without touching the (major, minor, patch) PK. `verificationType` and `prompt` may be updated; omit either to carry the prior build's value forward.",
                     "properties": {
                         "initialUrl": {
                             "type": "string",
                             "format": "uri",
                             "maxLength": 300
                         },
+                        "verificationType": {
+                            "type": "string",
+                            "description": "How a provider version verifies a claim. `structured` uses the explicit match rules on this version (the `matches` / `allowedJsMatches` and related settings). `llm` defers the verification decision to a language model and requires `prompt` to be set.",
+                            "enum": [
+                                "llm",
+                                "structured"
+                            ]
+                        },
+                        "prompt": {
+                            "type": "string",
+                            "description": "Extraction prompt, used when `verificationType` is `llm`.",
+                            "minLength": 0,
+                            "maxLength": 1000000
+                        },
                         "requests": {
                             "type": "array",
                             "minItems": 0,

package/lib/mcp/instructions.d.ts

@@ -1 +1,3 @@
 export declare const BUILDER_MODE_INSTRUCTIONS: string;
+export declare const PROVIDER_GUIDE_BUILDER: string;
+export declare const PROVIDER_GUIDE_OLD: string;

package/lib/mcp/instructions.js

@@ -9,3 +9,19 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 export const BUILDER_MODE_INSTRUCTIONS = readFileSync(fileURLToPath(new URL('../../skill/builder-mode.md', import.meta.url)), 'utf8').trim();
+/**
+ * The full provider-authoring guide — the deep capture→prove→publish workflow,
+ * decision frameworks, and troubleshooting. Served on demand by the
+ * `how_it_works` MCP tool so every client (not just Claude Code, which
+ * auto-loads skills) can pull it. There's a guide PER MODE so an agent is never
+ * shown auth/publish tools that don't exist in its backend: the server picks
+ * one by `oldMode` (see `mcp/start.ts`). Same `../../skill/` path resolution as
+ * the instructions above; any leading frontmatter is stripped defensively.
+ */
+function readGuide(file) {
+    return readFileSync(fileURLToPath(new URL(file, import.meta.url)), 'utf8')
+        .replace(/^---\n[\s\S]*?\n---\n/, '')
+        .trim();
+}
+export const PROVIDER_GUIDE_BUILDER = readGuide('../../skill/SKILL.builder.md');
+export const PROVIDER_GUIDE_OLD = readGuide('../../skill/SKILL.old.md');

package/lib/mcp/server.d.ts

@@ -5,16 +5,32 @@ export interface ToolDefinition {
     description: string;
     inputSchema: JSONSchema.ObjectSchema;
 }
+/**
+ * Passed to every tool handler alongside its parsed args. Long-running,
+ * human-in-the-loop tools (e.g. a browser login flow that waits for someone
+ * to sign in) should call `reportProgress` every few seconds while waiting.
+ * MCP clients that attach a progress token to their request (most desktop
+ * clients do) treat an incoming `notifications/progress` as proof the call
+ * is still alive and reset their own request timeout instead of giving up —
+ * the SDK's client-side default is 60s, far shorter than a human can be
+ * expected to take to log in. A no-op when the client didn't request
+ * progress tracking for this call.
+ */
+export interface ToolContext {
+    reportProgress: (message: string) => Promise<void>;
+}
 export interface RegisteredTool {
     definition: ToolDefinition;
     /**
      * @param args Tool arguments
+     * @param ctx Progress-reporting context (see {@link ToolContext}).
+     *   Optional so direct/test callers can omit it.
      * @returns A JSON stringifiable content to be returned to the llm
      * @throws Any error encountered during tool execution will be caught and
      * returned as a response using
      * [remapErrorAsResponse](./src/mcp/remap_errors.ts).
      */
-    handler: (args: unknown) => Promise<unknown>;
+    handler: (args: unknown, ctx?: ToolContext) => Promise<unknown>;
 }
 /**
  * Define a tool with a single inputSchema (JSON Schema) used as the
@@ -23,7 +39,7 @@ export interface RegisteredTool {
  * so the description sent to the MCP client and the validation applied
  * to inbound args cannot drift.
  */
-export declare function defineTool<TArgs>(definition: ToolDefinition, handler: (args: TArgs) => Promise<unknown>): RegisteredTool;
+export declare function defineTool<TArgs>(definition: ToolDefinition, handler: (args: TArgs, ctx: ToolContext) => Promise<unknown>): RegisteredTool;
 /**
  * Registers a list of RegisteredTool entries on a high-level McpServer.
  * Converts JSON Schema definitions to Zod and provides consistent

package/lib/mcp/server.js

@@ -1,5 +1,6 @@
 import { toZod } from "./api/to-zod.js";
 import { remapErrorAsResponse } from "./remap_errors.js";
+const NOOP_CONTEXT = { reportProgress: async () => { } };
 /**
  * Define a tool with a single inputSchema (JSON Schema) used as the
  * source of truth. The handler receives args already parsed and
@@ -11,9 +12,9 @@ export function defineTool(definition, handler) {
     const schema = toZod(definition.inputSchema);
     return {
         definition,
-        handler: async (raw) => {
+        handler: async (raw, ctx = NOOP_CONTEXT) => {
             const args = schema.parse(raw);
-            return await handler(args);
+            return await handler(args, ctx);
         },
     };
 }
@@ -27,13 +28,27 @@ export function registerToolList(server, tools) {
         server.registerTool(tool.definition.name, {
             description: tool.definition.description,
             inputSchema: toZod(tool.definition.inputSchema),
-        }, async (args) => {
+        }, async (args, extra) => {
             try {
+                const progressToken = extra?._meta?.progressToken;
+                let progress = 0;
+                const ctx = {
+                    reportProgress: async (message) => {
+                        if (progressToken === undefined) {
+                            return;
+                        }
+                        progress += 1;
+                        await extra.sendNotification({
+                            method: 'notifications/progress',
+                            params: { progressToken, progress, message },
+                        }).catch(() => { });
+                    },
+                };
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: JSON.stringify(await tool.handler(args), null, 2),
+                            text: JSON.stringify(await tool.handler(args, ctx), null, 2),
                         },
                     ],
                 };

package/lib/mcp/start.js

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ReclaimClient } from '@reclaimprotocol/client';
-import { agentDisabled, apiToken, apiUrl, oldApiUrl, useOldDevtools, } from "../consts.js";
+import { agentDisabled, apiToken, apiUrl, oldApiUrl, oldLogsUrl, useOldDevtools, } from "../consts.js";
 import { ReclaimOldClient } from "../old/client.js";
 import { resolveInitialIdentity } from "../old/identity.js";
 import { OLD_MODE_INSTRUCTIONS } from "../old/instructions.js";
@@ -30,6 +30,7 @@ export async function startMcpServer() {
         // get_me_providers instead.
         const oldClient = new ReclaimOldClient({
             baseUrl: oldApiUrl(),
+            logsBaseUrl: oldLogsUrl(),
             identity: resolveInitialIdentity(),
         });
         registerToolList(server, buildLocalCredentialTools());

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

@@ -14,6 +14,7 @@ import { attachTool } from "./attach.js";
 import { captureTools } from "./capture.js";
 import { browserTools } from "./eval.js";
 import { findTool } from "./find.js";
+import { howItWorksTool } from "./how-it-works.js";
 import { proofTool } from "./proof.js";
 import { makeSecretStore, proposeTool, } from "./propose.js";
 import { createVersionFromCaptureTool } from "./publish.js";
@@ -35,6 +36,9 @@ export function buildAgentTools(client) {
     const state = buildAgentState();
     ensureAttestorCrypto();
     const tools = [];
+    // Stateless docs tool — serve the mode-specific authoring guide to any
+    // client. No `client` ⇒ old-devtools mode (see `mcp/start.ts`).
+    tools.push(howItWorksTool(!client));
     tools.push(attachTool(state.attach));
     for (const t of captureTools(state.attach, state.captures)) {
         tools.push(t);

package/lib/mcp/tools/agent/how-it-works.d.ts

@@ -0,0 +1,11 @@
+import { type RegisteredTool } from '../../server.ts';
+/**
+ * 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_chrome`.
+ */
+export declare function howItWorksTool(oldMode: boolean): RegisteredTool;

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

@@ -0,0 +1,24 @@
+import { PROVIDER_GUIDE_BUILDER, PROVIDER_GUIDE_OLD, } 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_chrome`.
+ */
+export function howItWorksTool(oldMode) {
+    const guide = oldMode ? PROVIDER_GUIDE_OLD : PROVIDER_GUIDE_BUILDER;
+    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 }));
+}

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

@@ -89,7 +89,7 @@ const ALLOWED_JS_REQUEST_SCHEMA = {
 export function createVersionFromCaptureTool(client) {
     return defineTool({
         name: 'create_provider_version_from_capture',
-        description: 'Persist drafted ReclaimProvider(s) as a verification version. ' +
+        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 ' +
@@ -120,7 +120,7 @@ export function createVersionFromCaptureTool(client) {
             properties: {
                 providerId: {
                     type: 'string',
-                    description: 'UUID of the verification to publish the version on.',
+                    description: 'UUID of the provider to publish the version on.',
                 },
                 provider: PROVIDER_SCHEMA,
                 providers: {

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

@@ -0,0 +1,6 @@
+import type { RegisteredTool } from '../../server.ts';
+import type { CaptureStore } from './capture.ts';
+/** The shared authoring tools as MCP `RegisteredTool`s: each resolves its
+ *  capture's local backend from `args.captureId`; the schema carries
+ *  `captureId` plus the rich `run_proof` contract. */
+export declare function sharedAuthoringTools(captures: CaptureStore): RegisteredTool[];