@reclaimprotocol/agent 0.1.4 → 0.1.5

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

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

@@ -0,0 +1,115 @@
+/**
+ * Build the shared authoring tools for the MCP, bound to a per-capture LOCAL
+ * backend: a Chrome tab over CDP + the in-process attestor SDK. The tool logic
+ * (navigate/inspect/propose/replay/prove) is authored once in `../../../
+ * authoring` with the shared `defineTool` primitive; this only supplies the
+ * MCP host — resolve the backend from `captureId` (the session handle from
+ * `start_capture`, since one capture bundles the tab, its requests, and its
+ * drafts) and the rich, credential-aware `run_proof` schema.
+ */
+import { buildAuthoringTools, } from "../../../authoring/index.js";
+import { runAttestorProof } from "../../../proof/attestor.js";
+import { replayProvider } from "../../../proof/replay.js";
+import { shapeRichProofResult } from "./proof.js";
+/** The local backend for one capture: drive its tab over CDP, read its
+ *  captured requests, prove via the in-process attestor, replay by re-fetch. */
+function localBackend(entry) {
+    const { tabClient, session, drafts } = entry;
+    // The per-tab CDP client is strongly typed to `keyof Commands`; the shared
+    // tools drive it with dynamic method/event names, so view it as string-keyed.
+    const client = tabClient;
+    return {
+        capture: session,
+        drafts,
+        sendCdp: (method, params) => client.send(method, params ?? {}),
+        waitForEvent: (method, timeoutMs) => new Promise((resolve) => {
+            const onEvent = () => {
+                cleanup();
+                resolve('fired');
+            };
+            const timer = setTimeout(() => {
+                cleanup();
+                resolve('timeout');
+            }, timeoutMs);
+            const cleanup = () => {
+                clearTimeout(timer);
+                client.removeListener(method, onEvent);
+            };
+            client.once(method, onEvent);
+        }),
+        replay: async (draft, opts) => {
+            // Auth-bound check: re-fetch with the secrets dropped. replayProvider
+            // already does a live Node fetch, so empty secrets == anonymous.
+            const secrets = opts?.withoutSecrets ? {} : draft.secrets;
+            const result = await replayProvider(draft.provider, secrets);
+            return {
+                status: result.status,
+                matchesOriginal: result.matchesOriginal,
+                bodySnippet: result.body.slice(0, 256),
+                ...(result.hints !== undefined ? { hints: result.hints } : {}),
+            };
+        },
+        prove: async (draft, opts) => {
+            const result = await runAttestorProof(draft.provider, draft.secrets, {
+                ...(opts?.ownerAddress ? { ownerAddress: opts.ownerAddress } : {}),
+                ...(opts?.attestorUrl ? { attestorUrl: opts.attestorUrl } : {}),
+            });
+            return shapeRichProofResult(result, {
+                provider: draft.provider,
+                hasSecrets: Object.keys(draft.secrets).length > 0,
+                ...(opts?.attestorUrl ? { attestorUrl: opts.attestorUrl } : {}),
+            });
+        },
+    };
+}
+/** The MCP's rich, credential-aware `run_proof` schema, merged onto the shared
+ *  tool by the host below (the cloud's TEE signs in-enclave, so it needs none
+ *  of this). */
+const RUN_PROOF_EXTRAS = {
+    description: 'Run a full zkTLS proof of the drafted recipe through the Reclaim '
+        + 'attestor SDK. Use only after replay_request looks right — attestor '
+        + 'calls are expensive. Writes the full claim to '
+        + '~/.reclaim/claims/<timestamp>.json and returns identifier + '
+        + 'extractedParameters + claimPath + a prettified `claim` (request '
+        + 'dropped, byte arrays as base64). With RECLAIM_AGENT_TRACE=1, also '
+        + 'writes a per-call diagnostic dump (input provider, sentParams, full '
+        + 'attestor log stream, result) and returns it as `runLogPath`. '
+        + '`attestorUrl` overrides the default only when the dev supplies a '
+        + 'specific alternative — do NOT invent backup URLs. `ownerAddress` '
+        + '(the credential to sign with) is REQUIRED — call resolve_owner_key '
+        + 'first. errorKind="missing-owner-key" means that address has no known '
+        + 'private key; re-run resolve_owner_key or issue/import a credential.',
+    properties: {
+        ownerAddress: {
+            type: 'string',
+            pattern: '^0x[0-9a-fA-F]{40}$',
+            description: 'ETH address of the credential to sign the claim with. Get it '
+                + 'from resolve_owner_key first. The private key is resolved '
+                + 'locally (cache / env / .env) — never passed here.',
+        },
+        attestorUrl: { type: 'string' },
+    },
+    required: ['ownerAddress'],
+};
+/** 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 function sharedAuthoringTools(captures) {
+    const host = {
+        resolveBackend: (args) => {
+            const captureId = String(args.captureId);
+            const entry = captures.sessions.get(captureId);
+            if (!entry) {
+                throw new Error(`no capture ${captureId} — call start_capture first `
+                    + '(it has been reset or never started).');
+            }
+            return localBackend(entry);
+        },
+        sessionSchema: {
+            properties: { captureId: { type: 'string' } },
+            required: ['captureId'],
+        },
+        toolExtras: { run_proof: RUN_PROOF_EXTRAS },
+    };
+    return buildAuthoringTools(host);
+}

package/lib/old/login-cdp.d.ts

@@ -17,4 +17,9 @@ export declare function captureFirebaseTokenViaCdp(opts: {
     loginUrl?: string;
     timeoutMs?: number;
     pollMs?: number;
+    /** Called every ~10s while waiting for the human to finish signing in, so
+     *  MCP clients that track progress on this call can reset their own
+     *  request timeout instead of giving up on a login that's still in
+     *  flight (see `ToolContext` in `mcp/server.ts`). */
+    onProgress?: (message: string) => Promise<void>;
 }): Promise<CdpLoginResult>;

package/lib/old/login-cdp.js

@@ -65,6 +65,8 @@ export async function captureFirebaseTokenViaCdp(opts) {
     const loginUrl = opts.loginUrl || oldLoginUrl() || DEFAULT_LOGIN_URL;
     const timeoutMs = opts.timeoutMs ?? 180_000;
     const pollMs = opts.pollMs ?? 1000;
+    const onProgress = opts.onProgress ?? (async () => { });
+    const progressIntervalMs = 10_000;
     const cfg = new ConfigStore().read()?.browser_agent;
     const mode = cfg?.attachMode ?? 'dedicated';
     const port = cfg?.port ?? 9222;
@@ -89,7 +91,9 @@ export async function captureFirebaseTokenViaCdp(opts) {
     try {
         const session = await handles.attachToTab(targetId);
         const { Runtime } = session;
-        const deadline = Date.now() + timeoutMs;
+        const startedAt = Date.now();
+        const deadline = startedAt + timeoutMs;
+        let lastProgressAt = startedAt;
         while (Date.now() < deadline) {
             const r = await Runtime.evaluate({
                 expression: EXTRACT_TOKEN_JS,
@@ -100,6 +104,13 @@ export async function captureFirebaseTokenViaCdp(opts) {
             if (typeof value === 'string' && value.length > 0) {
                 return { token: value, closedBrowser: launchedByUs };
             }
+            const now = Date.now();
+            if (now - lastProgressAt >= progressIntervalMs) {
+                lastProgressAt = now;
+                const remainingSec = Math.round((deadline - now) / 1000);
+                await onProgress(`Still waiting for sign-in at ${loginUrl} ` +
+                    `(${remainingSec}s left before this call times out).`);
+            }
             await new Promise((resolve) => setTimeout(resolve, pollMs));
         }
         throw new Error('Timed out waiting for login. Finish signing in at the opened ' +

package/lib/old/tools/authenticate.js

@@ -1,5 +1,5 @@
 import { agentDisabled } from "../../consts.js";
-import { defineTool } from "../../mcp/server.js";
+import { defineTool, } from "../../mcp/server.js";
 import { persistIdentity, toEthUid } from "../identity.js";
 import { captureFirebaseTokenViaCdp } from "../login-cdp.js";
 /**
@@ -69,7 +69,7 @@ export function authenticateTool(client) {
                 },
             },
         },
-    }, async ({ token, ethAddress, loginUrl, timeoutMs, useBrowser }) => {
+    }, async ({ token, ethAddress, loginUrl, timeoutMs, useBrowser }, ctx) => {
         if (token && ethAddress) {
             throw new Error('Provide only ONE of `token` or `ethAddress`, not both.');
         }
@@ -113,7 +113,11 @@ export function authenticateTool(client) {
             throw new Error('Browser login is unavailable (RECLAIM_AGENT_DISABLED=1). Pass a ' +
                 '`token` (Firebase ID token) or `ethAddress` instead.');
         }
-        const result = await captureFirebaseTokenViaCdp({ loginUrl, timeoutMs });
+        const result = await captureFirebaseTokenViaCdp({
+            loginUrl,
+            timeoutMs,
+            onProgress: ctx.reportProgress,
+        });
         const identity = { kind: 'bearer', token: result.token };
         await validate(identity);
         persistIdentity(identity);

package/lib/proof/proof-core.d.ts

@@ -18,7 +18,7 @@ export declare function ensureAttestorCrypto(): void;
  *  default. Resolved per-call so an env change or per-request override takes
  *  effect without restarting. */
 export declare function resolveAttestorUrl(override?: string): string;
-/** Map a verification's provider recipe straight to the attestor's HTTP
+/** Map a provider's recipe straight to the attestor's HTTP
  *  params — never synthesized from captured traffic. */
 export declare function buildHttpParams(provider: ReclaimProvider): ProviderParams<'http'>;
 export interface ParsedClaim {

package/lib/proof/proof-core.js

@@ -21,7 +21,7 @@ export function ensureAttestorCrypto() {
 export function resolveAttestorUrl(override) {
     return (override ?? attestorUrlOverride() ?? FALLBACK_ATTESTOR_URL);
 }
-/** Map a verification's provider recipe straight to the attestor's HTTP
+/** Map a provider's recipe straight to the attestor's HTTP
  *  params — never synthesized from captured traffic. */
 export function buildHttpParams(provider) {
     // A blank egress is treated as unset: omit it so the local proof uses the

package/lib/tools/registry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The ONE tool primitive for the agent. A tool is authored once with
+ * {@link defineTool} — `{ definition, handler }`, where the handler receives
+ * args already parsed + validated against the definition's JSON Schema (via
+ * zod), so the schema shown to the model and the validation applied to inbound
+ * args cannot drift.
+ *
+ * This lives outside `mcp/` on purpose: it depends only on zod (NOT the MCP
+ * SDK), so non-MCP consumers — the cloud authoring loop — can author and run
+ * these tools without pulling in `@modelcontextprotocol/sdk`. The MCP-specific
+ * glue (`registerToolList` onto an `McpServer`) stays in `mcp/server.ts`, which
+ * re-exports this primitive for the MCP-side tool files.
+ */
+import type { JSONSchema } from 'zod/v4/core';
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema.ObjectSchema;
+}
+export interface RegisteredTool {
+    definition: ToolDefinition;
+    /**
+     * @param args Tool arguments (already zod-validated against the schema).
+     * @returns A JSON-stringifiable value to return to the LLM.
+     * @throws Any error; the host (MCP `registerToolList` / the cloud loop)
+     * catches it and surfaces it as an error tool-result.
+     */
+    handler: (args: unknown) => Promise<unknown>;
+}
+/**
+ * Define a tool with a single inputSchema (JSON Schema) as the source of truth.
+ * The handler receives args already parsed and type-narrowed via a Zod schema
+ * derived from that same JSON Schema — so the description sent to the client
+ * and the validation applied to inbound args cannot drift.
+ */
+export declare function defineTool<TArgs>(definition: ToolDefinition, handler: (args: TArgs) => Promise<unknown>): RegisteredTool;

package/lib/tools/registry.js

@@ -0,0 +1,17 @@
+import { toZod } from "../mcp/api/to-zod.js";
+/**
+ * Define a tool with a single inputSchema (JSON Schema) as the source of truth.
+ * The handler receives args already parsed and type-narrowed via a Zod schema
+ * derived from that same JSON Schema — so the description sent to the client
+ * and the validation applied to inbound args cannot drift.
+ */
+export function defineTool(definition, handler) {
+    const schema = toZod(definition.inputSchema);
+    return {
+        definition,
+        handler: async (raw) => {
+            const args = schema.parse(raw);
+            return await handler(args);
+        },
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.4",
+	"version": "0.1.5",
 	"description": "Reclaim Protocol agent — SDK, CLI, and MCP server in one package. SDK + CLI talk to the builder backend; MCP server adds Chrome CDP capture, provider synthesis, replay, and zkTLS proof.",
 	"type": "module",
 	"main": "./lib/index.js",