@reclaimprotocol/agent 0.1.43 → 0.1.44

package/skill/ai-sessions.md

@@ -0,0 +1,87 @@
+# AI sessions: the first route for a backend integration
+
+An AI session proves a claim about a user's account on a website. You describe
+the claim. An AI agent completes it in a remote browser. You need no provider,
+no capture, and no org keypair: Builder manages a hidden AI app key for each
+org.
+
+## When to use it
+
+Use AI sessions first for any claim about a user's account on a site, for
+example "prove the user is a student at example.edu". Prefer them over
+authoring a provider and creating regular sessions. Fall back to the provider
+route only as [Fall back to a provider](#fall-back-to-a-provider) describes.
+
+## Set up
+
+1. Sign in (`get_me`, then `authenticate` on 401; topic `auth`) and pick the
+   org with `list_orgs`.
+2. Call `issue_org_token`. It writes `RECLAIM_ORG_SECRET` to the env file.
+   Never print the key.
+3. Add at least one callback subscription with `create_callback_subscription`.
+   For local development, call `proxy_callback_events({ port, path })` as
+   topic `integration` describes. Without a subscription, creating a session
+   returns 409.
+
+## Try it first
+
+1. Call `create_ai_verification_session`:
+   - `prompt`: the claim in plain words.
+   - `dataPoints`: `{ name, description, isOptional }` items. Include exactly
+     one required identifier. Other fields are optional. `isOptional` defaults
+     to `false`. Names match `^[A-Za-z_][A-Za-z0-9_]{0,63}$`. Describe each
+     one. Never invent values.
+   - `loginUrls`: the portal URLs, when the developer knows them.
+   - Omit `verificationClientUrl`. Only the portals verification client
+     supports AI sessions today, and it is the default. Don't pass another
+     client.
+   - Leave `isEmailVerificationAllowed` `false`. The email option isn't
+     working yet.
+2. Call `wait_for_ai_session`. Put the session's `verificationUrl` in the same
+   message as your question to the developer, and end your turn. Then wait
+   until the session is terminal.
+3. Inspect the outcome with `get_verification_session`,
+   `list_verification_events`, `list_verification_deliveries`, and
+   `read_callback_events`.
+
+## Write the backend code
+
+Keep every secret on the server.
+
+1. Create the session server-side: `POST /verifications/ai-sessions` with the
+   org token. Use `reclaim.api('CreateAiVerificationSession', …)` from
+   `@reclaimprotocol/client`, or `fetch`.
+2. Return only `verificationUrl` to the frontend. The frontend opens it in an
+   iframe or a new tab.
+3. Receive the result on the callback endpoint. Verify it with
+   `reclaim.results.receive(body, { reclaimSessionId })` (client 0.1.44 or
+   later accepts results that have no provider). Topic `integration` has the
+   full route, including idempotent storage and `503` for retryable errors.
+4. Read the values from the verified proofs' `extractedParameters`. Every
+   required data point is present.
+5. Handle the three outcomes:
+   - `verification_success`: use the verified data.
+   - `verification_rejected`: read `reasonCode`. `missing-data-points` means a
+     required data point is missing. `context-mismatch` means the context
+     differs from the session's.
+   - `verification_error`: record the failure and offer a retry.
+
+## Verifying results
+
+Builder checks regular sessions against provider recipes. AI-session proofs
+come from Popcorn. Builder verifies them with the ai-sdk `verifyProofs`, then
+checks the required data points and the context pin. AI results omit
+`provider_id` and `resolved_version`. Verify both kinds with
+`reclaim.results.receive` from `@reclaimprotocol/client` 0.1.44 or later.
+Older clients reject AI results.
+
+## Fall back to a provider
+
+Switch to the provider route (`start_integration` with route `provider`:
+capture, provider, regular sessions) when:
+
+- Lookup fails: 404 (no login page) or 422 (not verifiable).
+- The session is rejected after one adjusted retry.
+- The user can't finish it, or it errors or expires repeatedly.
+- `503` persists.
+- The developer prefers a deterministic provider.

package/skill/builder-mode.md

@@ -6,8 +6,8 @@ Provider-authoring and verification tools for the Builder backend.
 
 ## Routing
 
-- "Add Reclaim to my app" or similar: call `start_integration` first and follow its plan. Don't ask what they want to do with the result.
-- A claim they describe (for example, "prove the user is over 18 on example.com"): build a new org-private provider for exactly that claim. Use an existing provider only when they name one or ask to reuse one (topic `discover`).
+- "Add Reclaim to my app" or similar: call `start_integration` first (it defaults to AI sessions) and follow its plan. Don't ask what they want to do with the result.
+- A claim about a user's account on a site (for example, "prove the user is a student at example.edu"): use AI sessions first (topic `ai-sessions`). Author a provider only as the fallback, or when they name or ask to reuse one (topic `discover`).
 - Intent unclear: ask one short question.
 
 ## Authoring rules
@@ -48,5 +48,5 @@ Treat every ID, version, URL, and value as opaque: copy it from the latest tool
 `how_it_works({})` lists topics. Fetch only the one for your next step:
 
 - `overview`: authoring checklist; `prove`, `publish`, `browser`: the details behind each step.
-- `integration`: app integration, trying a session without an app, existing `@reclaimprotocol/js-sdk` projects.
+- `ai-sessions`: the first route for proving a claim; `integration`: app integration, trying a session without an app, existing `@reclaimprotocol/js-sdk` projects.
 - `auth`: sign-in (`get_me`, then `authenticate` on 401) and backend mode.

package/skill/interception.md

@@ -5,7 +5,7 @@
 - The field, per backend
 - Which mechanism to pick, and when to use any of them at all
 - When a site won't load, or won't let the user sign in — ask which clients
-  ship it, bisect, then the remedies
+  ship it, bisect, then the remedies (including the in-app Hawkeye hook mode)
 - The document-replay flag, and why the two backends invert its polarity
 - Recognizing live interception on a provider you didn't author
 - Related topics
@@ -169,6 +169,41 @@ the page differently: old-devtools supports `HAWKEYE`, `MSWJS`, `XHOOK`, and
 `CDP`; Builder supports `HAWKEYE`, `MSWJS`, and `CDP`. `CDP` operates below the
 page's JavaScript but is not supported by every in-page client.
 
+### In-app SDK: change how Hawkeye hooks `fetch`
+
+Under `HAWKEYE`, the InApp SDK can wrap the page's `fetch` three ways, and a
+site can break under one and work under another. Suspect this when the provider
+works in Portals or Builder but the in-app page stalls: for example, a bot-check
+or "one moment" screen that never clears, a sign-in form that never appears, or
+the site's own scripts failing on requests they normally make. Try it before
+removing interception, because it keeps the interceptor working.
+
+Set the mode on the provider version, keeping `interceptorType: "HAWKEYE"`:
+
+```json
+"clientOptions": { "inapp": { "interceptorOptions": {
+	"interceptorType": "HAWKEYE",
+	"interceptorSettings": "{\"interceptionMethod\":\"GETTER_SETTER\"}"
+} } }
+```
+
+`interceptorSettings` is a JSON object **string**. `interceptionMethod` is one
+of:
+
+- `PROXY` (default): wraps `fetch` in a `Proxy`, so `fetch.toString()` still
+  looks native.
+- `GETTER_SETTER`: rebuilds each call as `new Request(input, init)`, and keeps
+  wrapping if the page reassigns `window.fetch`. Try this first.
+- `DIRECT_REPLACEMENT`: the same wrapper, assigned once.
+
+`GETTER_SETTER` and `DIRECT_REPLACEMENT` make `fetch.toString()` non-native. Some
+anti-bot vendors check for that, so confirm with a real in-app verification;
+authoring never exercises the in-app client. Optional `disableFormIntercept`
+(default `true`) and `delayFormSubmitForFetch` (default `false`) go in the same
+object. Keys you leave out keep the SDK's defaults, and other interceptor types
+ignore `interceptorSettings`. If no mode works, go back to the bisect steps
+above.
+
 ⚠️ **The direct-claim remedy needs a client that consumes `window.Reclaim`.**
 The InApp SDK, browser extension, portals, and Builder's built-in client do. The
 built-in client uses the page-supplied request to generate the proof;

package/skill/start-ai-session-integration.md

@@ -0,0 +1,58 @@
+# Plan: let users prove "{{goal}}" in this app with a Builder AI session
+
+Follow this plan end to end. Mark each step done as you go. Do not ask the developer whether to integrate: integrating into this codebase is the goal.
+
+An AI session needs no provider. The user prompt and data points tell Builder what to prove, and Builder finds the site and the login page. Only the portals verification client supports AI sessions today, so omit `verificationClientUrl` (portals is the default). Start with the steps that need the developer (sign in, try a session), and write app code while you wait.
+
+**Asking the developer.** When you need an answer or an action, end your turn with the question. Don't use background or asynchronous question tools: the developer may never see them. Put every link they need in that same message. Ask each question once.
+
+## 1. Sign in and pick the organization
+
+- [ ] Call `reclaim_authenticate` if you are not signed in. Give the developer the returned `signInUrl` to approve in their browser (end your turn first if `browserOpened` is false), then call `wait_for_sign_in`.
+<!-- if:orgId -->
+- [ ] Use organization `{{orgId}}` for every call below.
+<!-- endif -->
+<!-- ifnot:orgId -->
+- [ ] Call `list_orgs`. Use the only organization, or ask the developer which one when there are several.
+<!-- endif -->
+
+## 2. Get an org token
+
+- [ ] If `RECLAIM_ORG_SECRET` is not in the server env file, call `issue_org_token` with the organization, this project's absolute path, and the server env file. It writes the key to that file and never returns it. Never print or commit the key, and confirm the env file is in `.gitignore`.
+
+## 3. Make sure results have a destination
+
+- [ ] Call `list_callback_subscriptions`. If the organization has none, call `create_callback_subscription` for the session-ending events: `verification_success`, `verification_rejected`, `verification_error`, `verification_cancelled`, and `session_expired`.
+- [ ] For local development, start the app's backend and call `proxy_callback_events({ port, path })` with the callback route's port and path. It forwards the org's verification events to that route on localhost, with no public URL. The proxy works only while this coding agent's MCP server runs.
+- [ ] For production, ask the developer for the public callback URL, and call `create_org_callback_subscription` with it. If they have no deployed URL yet, tell them: "When you deploy, ask me to run `create_org_callback_subscription` with your public callback URL, or results will not reach the app."
+
+## 4. Read the guide
+
+- [ ] Call `how_it_works({ topic: "ai-sessions" })` and follow it for request fields, session states, and error codes. Don't repeat its detail here.
+
+## 5. Try a session
+
+- [ ] Call `create_ai_verification_session` with:
+  - `prompt`: a sentence for "{{goal}}", written as the claim to prove.
+  - `dataPoints`: the values the claim needs. Mark one identifier required. Mark the others optional. Add no profile or identity extras.
+  - `loginUrls`: the site's sign-in URLs, when you know them.
+- [ ] Call `wait_for_ai_session` with the returned session ID, until the lookup is ready.
+- [ ] Share the returned `verificationUrl` with the developer, in the same message as the ask: "Open this link, sign in to the site, and tell me when you are done." End your turn.
+- [ ] After they reply, call `wait_for_ai_session` until the session reaches a terminal status. Use `read_callback_events({ sessionId })` to see the delivered result.
+- [ ] The hosted verification page streams the target site as an image, so text or DOM checks of that page come back empty. Check progress with `wait_for_ai_session`, `list_verification_events`, and `get_verification_session`, not by reading the page.
+
+## 6. Write the backend integration
+
+Write this while you wait on the developer. Don't let it delay a step that needs them.
+
+- [ ] Detect the app's framework and package manager from the repository, and use them. Read `how_it_works({ topic: "integration" })`.
+- [ ] Add a backend route that calls `POST /verifications/ai-sessions` server-side, with the same prompt, data points, and login URLs as step 5, and returns `verificationUrl`. Never call it from the browser: it needs the org key.
+- [ ] Add a callback route that verifies each result with `reclaim.results.receive` from `@reclaimprotocol/client` version 0.1.44 or later, then stores only the requested data points. Store every failure on the verification session record and log it server-side. Respond `error.retryable ? 503 : 200`. A result that failed verification gets 2xx, because retrying can't fix it.
+- [ ] Add a status route the frontend polls, and a frontend Verify button that opens `verificationUrl`. Render every state in "UI states" in `how_it_works({ topic: "integration" })`, including **Try again** on failure.
+- [ ] If the org has a key pair (`get_org_keypair`), pass `orgEthPrivateKey` from `RECLAIM_ORG_ETH_PRIVATE_KEY` to `results.receive`. The developer puts that key in the env file, never in chat.
+- [ ] If a permission check blocks a command, follow "Permission blocks" in the server instructions.
+
+## 7. Fall back to a provider when the session cannot work
+
+- [ ] If `wait_for_ai_session` recommends a fallback, adjust the `dataPoints` or `loginUrls` as its result suggests and create one more session.
+- [ ] If the retry also recommends a fallback, call `start_integration` with `route: "provider"` and the same `goal`, and follow the plan it returns. Keep the backend work from step 6: the provider plan reuses the callback route.

package/skill/start-integration.md

@@ -1,5 +1,7 @@
 # Plan: let users prove "{{goal}}" in this app
 
+This is the provider route: the fallback when a Builder AI session cannot prove the claim, or the route you chose explicitly.
+
 Follow this plan end to end. Mark each step done as you go. Do not ask the developer whether to integrate: integrating into this codebase is the goal.
 
 **Order.** Do the steps that need the developer first: sign in to Builder, attach the browser, capture, and prove the provider (step 2). These need the developer at the browser, and they show early whether a proof is possible on this site. Write app code (step 3) after the proof works, or while you wait on the developer. Never spend a long stretch on app code before the developer has signed in and the browser is attached.

package/skill/verification-client-integration.md

@@ -1,5 +1,8 @@
 # Integrate a Builder verification client
 
+For a claim about a user's account on a site, start with topic `ai-sessions`.
+This guide covers the provider route and the shared callback details.
+
 ## Set up an application with the coding agent
 
 For "add Reclaim to my app", call `start_integration` first and follow its

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

@@ -1,5 +1,5 @@
 // AUTO-GENERATED by packages/app/scripts/mcp-tools-gen.ts
-// from packages/app/openapi.yaml (spec v0.1.0, source sha256:c3421d6bcf76).
+// from packages/app/openapi.yaml (spec v0.1.0, source sha256:cbe3daf2a1f3).
 // The hash catches drift the version misses (a spec can change without a
 // version bump) — do not remove it as "redundant" with the version.
 // Run `npm run openapi:gen --workspace=packages/app` to regenerate. Do not edit by hand.
@@ -125,6 +125,7 @@ export const MCP_TOOLS = {
 								"revenue",
 								"usage",
 								"goals",
+								"ai-session-prompts",
 								"tools",
 								"agents",
 								"funnel"
@@ -505,6 +506,117 @@ export const MCP_TOOLS = {
 		}),
 		annotations: {"openWorldHint":false},
 	},
+	"CreateAiVerificationSession": {
+		description: "Start an AI verification session from a prompt\n\nStarts an AI verification session from a plain-language prompt and optional dataPoints/loginUrls; returns the session with verificationUrl to share with the user. Needs the org token and at least one callback subscription (409 otherwise). No provider or org keypair needed: Builder manages the AI app key. Poll with get_ai_verification_session or wait_for_ai_session.",
+		inputSchema: toZod({
+			"type": "object",
+			"properties": {
+				"params": {
+					"type": "object",
+					"properties": {
+
+					}
+				},
+				"query": {
+					"type": "object",
+					"properties": {
+
+					}
+				},
+				"body": {
+					"type": "object",
+					"additionalProperties": false,
+					"description": "Body for `POST /verifications/ai-sessions`. Send a `prompt`, at least one entry in `dataPoints`, or both.",
+					"properties": {
+						"prompt": {
+							"type": "string",
+							"minLength": 0,
+							"maxLength": 10000,
+							"description": "What to verify, in plain language, such as \"verify I'm a student at Manipal University\". Required unless `dataPoints` has at least one item. Builder rejects a prompt that contains credentials, card numbers, instructions for the AI, or a sensitive claim. The prompt and the data point lines together can't exceed 10,000 characters."
+						},
+						"dataPoints": {
+							"type": "array",
+							"maxItems": 32,
+							"description": "The values to verify. Required unless you send a `prompt`. Names must be unique, and at least one data point must be required (its `isOptional` is `false` or absent). When you send data points, Builder keeps them and adds only optional data points that the prompt implies. When you send none, Builder chooses the data points from the prompt. Every required data point must appear in the verified proofs. If one is missing, the session ends as `rejected` with `reasonCode` `missing-data-points`.",
+							"items": {
+								"type": "object",
+								"additionalProperties": false,
+								"required": [
+									"name",
+									"description"
+								],
+								"properties": {
+									"name": {
+										"type": "string",
+										"maxLength": 64,
+										"pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
+										"description": "Name of the value, such as `username`. Starts with a letter or underscore, followed by up to 63 letters, digits, or underscores."
+									},
+									"description": {
+										"type": "string",
+										"minLength": 1,
+										"maxLength": 300,
+										"description": "What the value is and why it proves the claim."
+									},
+									"isOptional": {
+										"type": "boolean",
+										"description": "Defaults to `false`. If `true`, the claim can be proven without this value, and the proofs can omit it. If `false` or absent, the data point is required, and a session whose proofs omit it ends as `rejected` with `reasonCode` `missing-data-points`."
+									}
+								}
+							}
+						},
+						"loginUrls": {
+							"type": "array",
+							"maxItems": 10,
+							"description": "Pages where the user signs in, such as `https://portal.example.edu/login`. Builder shows them first as candidates with source `caller`, and skips the web search. Each URL must use `http` or `https`, can't contain credentials, and must resolve to a public host.",
+							"items": {
+								"type": "string",
+								"format": "uri",
+								"maxLength": 2048
+							}
+						},
+						"isEmailVerificationAllowed": {
+							"type": "boolean",
+							"description": "Defaults to `false`. If `true`, the share page offers the user a choice to verify using email instead of signing in. If you omit it, the page doesn't offer that choice."
+						},
+						"context": {
+							"type": "object",
+							"maxProperties": 50,
+							"additionalProperties": true,
+							"description": "Values you already know, such as `{\"fullName\": \"Asha Rao\"}`. Builder merges them over the values the prompt states and returns the result in `context`. Must not contain `attestationNonce` or `attestationNonceData`; bind those after you create the session. Also must not contain `reclaimSessionId`, `extractedParameters`, or `builderSessionId`. Omit if you have none."
+						},
+						"verificationClientUrl": {
+							"type": "string",
+							"description": "Base URL of the registered verification client the user verifies with, as for `POST /verifications/sessions`. Builder charges this client's quota pool. If you omit it, Builder uses the default (`portals`) client.",
+							"maxLength": 2000,
+							"pattern": "^https?://"
+						},
+						"geoLocation": {
+							"type": "string",
+							"description": "ISO 3166-1 alpha-2 country code, such as `IN`. Builder searches the web from this country (Google's `gl` parameter), so portals for that country rank first. If you omit it, the search has no country preference.",
+							"minLength": 2,
+							"maxLength": 2,
+							"pattern": "^[A-Za-z]{2}$"
+						}
+					}
+				},
+				"orgToken": {
+					"type": "string",
+					"pattern": "^rorg_",
+					"maxLength": 200,
+					"description": "The organization API key (`rorg_…`) this call authenticates with: from `issue_org_token`, or the app's RECLAIM_ORG_SECRET. Defaults to the MCP server's RECLAIM_ORG_SECRET. Never echo it back to the user."
+				}
+			},
+			"required": [
+				"params",
+				"query",
+				"body"
+			],
+			"additionalProperties": false
+		}),
+		orgTokenOnly: true,
+		annotations: {"openWorldHint":false},
+	},
 	"CreateCallbackSubscription": {
 		description: "Register a callback subscription\n\nRegisters a destination for verification results on the organization\nthe presented `OrgToken` resolves to. At least one subscription must\nexist for the org before you can create a verification session.\nDelivery is scoped by org: terminal results are ECIES-encrypted to the\norg's eth public key when its `canEncryptResult` is enabled (see\n`PUT /orgs/{orgId}/keypair`), else delivered as plaintext.\n\nTo receive results at a URL, send `callbackUrl` and `events`. Builder\nPOSTs each delivery to that URL.\n\nTo read results without a public URL during local development, send\n`deliveryMode: \"pull\"`. Builder keeps the deliveries and you read them\nwith `GET /verifications/callback-events`. A pull subscription is a\n90-second lease: it receives events and satisfies the session-creation\ncheck only while the lease is unexpired. Send the same request about\nevery 30 seconds to renew it, and call\n`POST /verifications/callback-listener/release` when you stop. Production\nneeds a webhook subscription. An org has at most one pull subscription.\nIf it already exists, Builder renews it and returns it with status 200.\nIf the body includes `events`, they replace the subscription's events;\nif it omits them, the existing events are kept.\n",
 		inputSchema: toZod({
@@ -5342,6 +5454,50 @@ export const MCP_TOOLS = {
 		}),
 		annotations: {"readOnlyHint":true,"openWorldHint":false},
 	},
+	"GetAiVerificationSession": {
+		description: "Get what an AI verification session's prompt resolved to\n\nGets what the AI session's lookup found: status resolving|ready|started|failed, candidates (login pages), merged dataPoints, error. Use get_verification_session for the overall outcome.",
+		inputSchema: toZod({
+			"type": "object",
+			"properties": {
+				"params": {
+					"type": "object",
+					"properties": {
+						"sessionId": {
+							"type": "string",
+							"format": "uuid",
+							"description": "Verification session id (UUID v7 when supported). Also echoed in the result payload as `reclaimSessionId`."
+						}
+					},
+					"required": [
+						"sessionId"
+					],
+					"additionalProperties": false
+				},
+				"query": {
+					"type": "object",
+					"properties": {
+
+					}
+				},
+				"body": {
+					"type": "object"
+				},
+				"orgToken": {
+					"type": "string",
+					"pattern": "^rorg_",
+					"maxLength": 200,
+					"description": "The organization API key (`rorg_…`) this call authenticates with: from `issue_org_token`, or the app's RECLAIM_ORG_SECRET. Defaults to the MCP server's RECLAIM_ORG_SECRET. Never echo it back to the user."
+				}
+			},
+			"required": [
+				"params",
+				"query"
+			],
+			"additionalProperties": false
+		}),
+		orgTokenOnly: true,
+		annotations: {"readOnlyHint":true,"openWorldHint":false},
+	},
 	"GetMe": {
 		description: "Get the authenticated user\n\nGets the authenticated caller's own profile: id, email, and name. Requires a signed-in user session, not an OrgToken. Use it to confirm who the current credentials belong to.",
 		inputSchema: toZod({

package/src/mcp/instructions.ts

@@ -49,6 +49,7 @@ const SHARED_TOPIC_FILES: Record<string, string> = {
 /** Detailed topics that exist only in Builder mode. */
 const BUILDER_TOPIC_FILES: Record<string, string> = {
 	'contributions': 'community-contributions.md',
+	'ai-sessions': 'ai-sessions.md',
 	'integration': 'verification-client-integration.md',
 }
 
@@ -78,6 +79,9 @@ const TOPIC_SUMMARIES: Record<string, string> = {
 		+ 'providers, and going live.',
 	'discover': 'Reusing existing providers: finding, resolving, copying one '
 		+ 'that needs changes, and creating a verification session.',
+	'ai-sessions': 'The first route for a backend integration: prove a claim '
+		+ 'about a user\'s account with create_ai_verification_session, no '
+		+ 'provider or capture. Setup, backend code, and when to fall back.',
 	'integration': 'After start_integration: org key and keypair, callback '
 		+ '(local proxy_callback_events or deployed webhook), frontend and '
 		+ 'backend over the HTTP session API, js-sdk projects, trying a '

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

@@ -360,7 +360,14 @@ export function createVersionFromCaptureTool(
 							interceptorSettings: {
 								type: 'string',
 								description:
-									'Free-form JSON config for the chosen interceptor.',
+									'Free-form JSON config for the chosen interceptor, '
+									+ 'as a JSON object string. For HAWKEYE in the '
+									+ 'in-app SDK: {"interceptionMethod": PROXY | '
+									+ 'GETTER_SETTER | DIRECT_REPLACEMENT}, plus '
+									+ 'optional disableFormIntercept and '
+									+ 'delayFormSubmitForFetch. Try GETTER_SETTER when '
+									+ 'the in-app page stalls but Portals works; see '
+									+ 'topic interception.',
 							},
 							isDocumentRequestReplayEnabled: {
 								type: 'boolean',

package/src/mcp/tools/agent/start-integration.ts

@@ -8,6 +8,7 @@ interface StartIntegrationArgs {
 	userRequest?: string
 	orgId?: string
 	providerIds?: string[]
+	route?: 'ai-session' | 'provider'
 }
 
 /**
@@ -22,7 +23,10 @@ export function startIntegrationTool(): RegisteredTool {
 			name: 'start_integration',
 			description:
 				'Returns a step-by-step plan for adding Reclaim verification to the '
-				+ 'current codebase: sign in to Builder, attach the browser, capture, '
+				+ 'current codebase. Recommends Builder AI sessions first: no '
+				+ 'provider to build, just a prompt and data points. Use route '
+				+ '"provider" to fall back to provider authoring, which is what '
+				+ 'this describes: sign in to Builder, attach the browser, capture, '
 				+ 'and prove the provider first, then set up the app (session route, '
 				+ 'callback, Verify button, local event proxy) after the proof or '
 				+ 'while waiting on the developer, bootstrapping from the '
@@ -60,7 +64,16 @@ export function startIntegrationTool(): RegisteredTool {
 						maxItems: 10,
 						items: { type: 'string' },
 						description:
-							'Existing provider IDs to use. Omit to build a new provider.',
+							'Existing provider IDs to use. Implies route "provider".',
+					},
+					route: {
+						type: 'string',
+						enum: ['ai-session', 'provider'],
+						description:
+							'"ai-session" (default when providerIds is empty) plans a '
+							+ 'Builder AI session. "provider" (default with providerIds) '
+							+ 'plans provider authoring; use it as the fallback when an '
+							+ 'AI session cannot prove the claim.',
 					},
 				},
 			},
@@ -80,9 +93,15 @@ export function renderStartIntegration(args: StartIntegrationArgs): string {
 		orgId: args.orgId,
 		providerIds,
 	}
+	// An explicit route wins, so 'ai-session' ignores providerIds.
+	const route = args.route
+		?? (providerIds ? 'provider' : 'ai-session')
+	const file = route === 'ai-session'
+		? 'start-ai-session-integration.md'
+		: 'start-integration.md'
 	const template = readFileSync(
 		fileURLToPath(
-			new URL('../../../../skill/start-integration.md', import.meta.url),
+			new URL(`../../../../skill/${file}`, import.meta.url),
 		),
 		'utf8',
 	)

package/src/mcp/tools/verification/build.ts

@@ -2,6 +2,7 @@ import type { RegisteredTool } from '../../server.ts'
 import { proxyCallbackEventsTool } from './proxy-callback-events.ts'
 import { readCallbackEventsTool } from './read-callback-events.ts'
 import { verificationResultTool } from './result.ts'
+import { waitForAiSessionTool } from './wait-for-ai-session.ts'
 
 /**
  * Builder-mode verification tools: higher-level orchestrations over the
@@ -20,5 +21,6 @@ export function buildVerificationTools(): RegisteredTool[] {
 		verificationResultTool(),
 		readCallbackEventsTool(),
 		proxyCallbackEventsTool(),
+		waitForAiSessionTool(),
 	]
 }