@reclaimprotocol/agent 0.1.4 → 0.1.5

package/skill/SKILL.builder.md

@@ -1,10 +1,14 @@
-# Authoring a Reclaim Provider / Verification
-
-> **Terminology note:** "provider" and "verification" refer to the same
-> thing. The API and tool parameters use **provider** / **providerId**
-> (the technical term). Conversations with developers prefer
-> **verification** (the user-facing term). Either is acceptable — never
-> correct the developer for using one or the other.
+# Authoring a Reclaim Provider
+
+> **Terminology note:** A **provider** is the recipe you author here — the
+> instructions for extracting a data point from a website (the
+> `responseMatches` / `responseRedactions` spec, identified by a
+> `providerId`). Always call it a **provider**; never call a provider a
+> "verification." A **verification** (or **verification session**) is the
+> separate runtime act in which an end-user proves a data point *using* a
+> provider — reserve that word for the session/result, never for the recipe.
+> If a developer calls the recipe a "verification," gently use "provider"
+> yourself rather than correcting them.
 
 You drive the browser through the capture → draft → replay → prove loop using the `reclaim-agent` MCP server. **Your default stance is driver, not orchestrator.** Only pause to ask the dev for things that genuinely require a human: typing credentials, completing 2FA, solving a captcha, confirming an ambiguous value. Navigation, reloads, DOM inspection, request capture — all yours.
 
@@ -175,7 +179,7 @@ replace with `{{context.<name>}}`. E.g. `https://github.com/Scratch-net/repos`
 
 13. **Publish the proved provider.** `provider` is the exact JSON from step 9 with the step-10 URL parameterisation applied, and `initialUrl` is the page where the user logs in / the value is displayed (e.g. `https://github.com/Syed`) — **not** the API endpoint URL inside the provider.
 
-    1. **Create the verification if it doesn't exist:** `create_verification(orgId, domain, slug, title, description)` — find `orgId` via `list_orgs`. `domain` e.g. `github.com`; `slug` e.g. `github-username`; `title` e.g. "GitHub Username". Starts PRIVATE with an empty seed version. Skip if the dev already has a `providerId`.
+    1. **Create the provider if it doesn't exist:** `create_provider(orgId, domain, slug, title, description)` — find `orgId` via `list_orgs`. `domain` e.g. `github.com`; `slug` e.g. `github-username`; `title` e.g. "GitHub Username". Starts PRIVATE with an empty seed version. Skip if the dev already has a `providerId`.
     2. **Persist the version:** `create_provider_version_from_capture(providerId, provider, initialUrl, notes)` — `notes` e.g. `"Initial draft from browser capture"`. The version lands on the `draft` branch.
     3. **`requiredContext` is derived for you.** The publish tool scans the recipe's url/body for `{{context.<name>}}` placeholders (step 10) and emits a JSON Schema requiring each one — the Builder then validates every session-create's `context` against it (a clear 400 instead of a late attestor failure). Extra context fields are always allowed. The derived properties are plain strings; to refine types or add human-readable descriptions, call `update_provider_version` with a `requiredContext` override while the version is on `draft`, e.g.:
 
@@ -183,7 +187,7 @@ replace with `{{context.<name>}}`. E.g. `https://github.com/Scratch-net/repos`
        { "requiredContext": { "type": "object", "required": ["username"], "properties": { "username": { "type": "string", "description": "GitHub username to verify" } } } }
        ```
     4. **Go live:** PRIVATE → `publish_provider_version`; PUBLIC → `submit_provider_version_for_review(providerId, version)` and tell the dev it's awaiting admin review.
-    5. **Tell the dev how consumers call it:** sessions for this verification must include the context params, e.g. `context: { "username": "..." }` in `POST /verifications/sessions`. Quote the `requiredContext` returned on the created version — a session missing those fields gets a 400, and verification matches the supplied values exactly.
+    5. **Tell the dev how consumers call it:** sessions for this provider must include the context params, e.g. `context: { "username": "..." }` in `POST /verifications/sessions`. Quote the `requiredContext` returned on the created version — a session missing those fields gets a 400, and verification matches the supplied values exactly.
 
     When done, tell the developer the version is live (PRIVATE) or submitted for review (PUBLIC), and that they can integrate using the `providerId`.
 

package/skill/SKILL.old.md

@@ -1,10 +1,14 @@
-# Authoring a Reclaim Provider / Verification
-
-> **Terminology note:** "provider" and "verification" refer to the same
-> thing. The API and tool parameters use **provider** / **providerId**
-> (the technical term). Conversations with developers prefer
-> **verification** (the user-facing term). Either is acceptable — never
-> correct the developer for using one or the other.
+# Authoring a Reclaim Provider
+
+> **Terminology note:** A **provider** is the recipe you author here — the
+> instructions for extracting a data point from a website (the
+> `responseMatches` / `responseRedactions` spec, identified by a
+> `providerId`). Always call it a **provider**; never call a provider a
+> "verification." A **verification** (or **verification session**) is the
+> separate runtime act in which an end-user proves a data point *using* a
+> provider — reserve that word for the session/result, never for the recipe.
+> If a developer calls the recipe a "verification," gently use "provider"
+> yourself rather than correcting them.
 
 You drive the browser through the capture → draft → replay → prove loop using the `reclaim-agent` MCP server. **Your default stance is driver, not orchestrator.** Only pause to ask the dev for things that genuinely require a human: typing credentials, completing 2FA, solving a captcha, confirming an ambiguous value. Navigation, reloads, DOM inspection, request capture — all yours.
 
@@ -164,9 +168,9 @@ Call `reclaim_authenticate({})` with no arguments. It opens the Reclaim dashboar
 13. **Publish the proved provider.** `provider` is the exact JSON from step 9 with the step-10 URL parameterisation applied, and `initialUrl` is the page where the user logs in / the value is displayed (e.g. `https://github.com/Syed`) — **not** the API endpoint URL inside the provider.
 
     Call `create_provider_version_from_capture`:
-    - **New verification:** omit `providerId`. It registers a new provider (version 1.0.0). Pass `provider`, `initialUrl`, and optionally `description`, `geoLocation`, `providerType` (`PRIVATE` default | `PUBLIC`).
-    - **New version of an existing verification:** pass its `providerId` — the patch is auto-bumped above the highest existing version. Pass `notes` (≥10 chars) as the change note.
-    - `get_me_providers({ searchQuery? })` lists the verifications you own — use it to find a `providerId` or to confirm the result. It's the only provider-listing tool in this mode.
+    - **New provider:** omit `providerId`. It registers a new provider (version 1.0.0). Pass `provider`, `initialUrl`, and optionally `description`, `geoLocation`, `providerType` (`PRIVATE` default | `PUBLIC`).
+    - **New version of an existing provider:** pass its `providerId` — the patch is auto-bumped above the highest existing version. Pass `notes` (≥10 chars) as the change note.
+    - `get_me_providers({ searchQuery? })` lists the providers you own — use it to find a `providerId` or to confirm the result. It's the only provider-listing tool in this mode.
     - There's no separate "create-then-version" step and no org / public-review workflow here.
     - Consumer-supplied params (step 10) keep the `{{context_<name>}}` form in this mode; there is no `requiredContext` declaration on the legacy backend.
 

package/src/cdp/capture-engine.ts

@@ -75,7 +75,7 @@ export function isStaticAsset(url: string): boolean {
 	try {
 		path = new URL(url).pathname
 	} catch{
-		path = url.split(/[?#]/)[0] ?? url
+		path = url.split(/[?#]/)[0] || url
 	}
 
 	// Extension of the last path segment only, so `/v1.2/data` isn't misread.

package/src/mcp/api/operations.gen.ts

@@ -98,7 +98,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": {
@@ -485,7 +485,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": {
@@ -618,7 +618,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": {
@@ -644,7 +644,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",
@@ -652,6 +652,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,
@@ -1211,7 +1225,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": {
@@ -1384,7 +1398,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": {
@@ -1429,7 +1443,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": {
@@ -1521,7 +1535,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": {
@@ -1792,7 +1806,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": {
@@ -1827,7 +1841,7 @@ export const MCP_TOOLS = {
 		}),
 	},
 	"GetProviderVersion": {
-		description: "Get a specific verification version",
+		description: "Get a specific provider version",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -2165,7 +2179,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": {
@@ -2320,7 +2334,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": {
@@ -2366,7 +2380,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": {
@@ -2615,7 +2629,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": {
@@ -2666,7 +2680,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": {
@@ -2825,7 +2839,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": {
@@ -2962,7 +2976,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": {
@@ -3004,13 +3018,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/src/mcp/server.ts

@@ -9,16 +9,35 @@ export interface ToolDefinition {
 	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>
+}
+
+const NOOP_CONTEXT: ToolContext = { reportProgress: async() => {} }
+
 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>
 }
 
 /**
@@ -30,14 +49,14 @@ export interface RegisteredTool {
  */
 export function defineTool<TArgs>(
 	definition: ToolDefinition,
-	handler: (args: TArgs) => Promise<unknown>,
+	handler: (args: TArgs, ctx: ToolContext) => Promise<unknown>,
 ): RegisteredTool {
 	const schema = toZod(definition.inputSchema)
 	return {
 		definition,
-		handler: async(raw) => {
+		handler: async(raw, ctx = NOOP_CONTEXT) => {
 			const args = schema.parse(raw) as TArgs
-			return await handler(args)
+			return await handler(args, ctx)
 		},
 	}
 }
@@ -55,13 +74,31 @@ export function registerToolList(server: McpServer, tools: RegisteredTool[]) {
 				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: ToolContext = {
+						reportProgress: async(message) => {
+							if(progressToken === undefined) {
+								return
+							}
+
+							progress += 1
+							await extra.sendNotification({
+								method: 'notifications/progress',
+								params: { progressToken, progress, message },
+							}).catch(() => {})
+						},
+					}
+
 					return {
 						content: [
 							{
 								type: 'text' as const,
-								text: JSON.stringify(await tool.handler(args), null, 2),
+								text: JSON.stringify(
+									await tool.handler(args, ctx), null, 2,
+								),
 							},
 						],
 					}

package/src/mcp/tools/agent/publish.ts

@@ -129,7 +129,7 @@ export function createVersionFromCaptureTool(
 		{
 			name: 'create_provider_version_from_capture',
 			description:
-				'Persist drafted ReclaimProvider(s) as a verification version. ' +
+				'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 ' +
@@ -160,7 +160,7 @@ export function createVersionFromCaptureTool(
 				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/src/old/login-cdp.ts

@@ -79,11 +79,18 @@ export async 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> {
 	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'
@@ -114,7 +121,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,
@@ -126,6 +135,16 @@ export async function captureFirebaseTokenViaCdp(opts: {
 				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))
 		}
 

package/src/old/tools/authenticate.ts

@@ -1,5 +1,9 @@
 import { agentDisabled } from '../../consts.ts'
-import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
+import {
+	defineTool,
+	type RegisteredTool,
+	type ToolContext,
+} from '../../mcp/server.ts'
 import type { OldIdentity, ReclaimOldClient } from '../client.ts'
 import { persistIdentity, toEthUid } from '../identity.ts'
 import { captureFirebaseTokenViaCdp } from '../login-cdp.ts'
@@ -83,7 +87,7 @@ export function authenticateTool(client: ReclaimOldClient): RegisteredTool {
 				},
 			},
 		},
-		async({ token, ethAddress, loginUrl, timeoutMs, useBrowser }) => {
+		async({ token, ethAddress, loginUrl, timeoutMs, useBrowser }, ctx: ToolContext) => {
 			if(token && ethAddress) {
 				throw new Error(
 					'Provide only ONE of `token` or `ethAddress`, not both.',
@@ -136,7 +140,11 @@ export function authenticateTool(client: ReclaimOldClient): RegisteredTool {
 				)
 			}
 
-			const result = await captureFirebaseTokenViaCdp({ loginUrl, timeoutMs })
+			const result = await captureFirebaseTokenViaCdp({
+				loginUrl,
+				timeoutMs,
+				onProgress: ctx.reportProgress,
+			})
 			const identity: OldIdentity = { kind: 'bearer', token: result.token }
 			await validate(identity)
 			persistIdentity(identity)

package/src/proof/proof-core.ts

@@ -38,7 +38,7 @@ export 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 function buildHttpParams(
 	provider: ReclaimProvider,