@reclaimprotocol/agent 0.1.35 → 0.1.37

package/skill/old-mode.md

@@ -24,25 +24,30 @@ shorten, or reuse one from memory. When state is missing or ambiguous, inspect
 it with the relevant get/list/status tool or call `how_it_works` before
 answering. State uncertainty plainly instead of guessing.
 
+**Ask blocking questions by ending your turn.** When you need an answer or an
+action from the developer before you can continue, end your turn with the
+question and every link they need. Don't use a background or asynchronous
+question tool for it: the developer may never see it.
+
 **Use the guide as needed.** Call `how_it_works({})` for its topic index, then
 fetch only the topic relevant to the next tool call.
 
-**Ask who is doing the signing in, then offer a browser.** "Yourself, or does
-someone else need to log in?" decides half of `attach_browser`'s list. Doing it
-themselves → `dedicated` or `attach`, both local, neither shareable. Someone
-else, or a phone-only site → `container` (the Reclaim runtime in Docker, free,
-shareable with `share_browser_view`) or `builder` (hosted, no install,
-**chargeable**). Say which costs money, and say `container` exists at all:
-nobody guesses it.
-
-**The flow:** `reclaim_authenticate` once → `attach_browser` (ask the developer
-which browser source — local Chrome, the Reclaim runtime in Docker, a remote
-Builder browser, or a CDP URL they supply) → `start_capture` ⇒ **`captureId`** →
+**Open the browser without asking.** Call `attach_browser()` with no
+arguments: it opens a visible browser on the developer's machine with the
+persistent Reclaim profile, and falls back to Chrome for Testing itself when
+no installed browser can be attached. Don't ask which browser or who signs in.
+Use another `mode` only when that fails too, or when the developer explicitly
+asks for it (topic `browser`). Tell the developer once, as a side note, that a
+shareable link can be set up if a volunteer is helping them sign in; don't ask
+about it or set it up unless they ask.
+
+**The flow:** `reclaim_authenticate` once → `attach_browser()` (no arguments: a
+visible local browser) → `start_capture` ⇒ **`captureId`** →
 drive the page (`navigate`,
 `wait_for_page`, `eval_in_page`) → inspect (`list_requests`, `get_request`,
 `find_requests_containing`) → `propose_provider` ⇒ **`draftId`** →
-`replay_request(captureId, draftId)` → `run_proof(captureId, draftId,
-ownerAddress)` → `create_provider_version_from_capture`.
+`replay_request(captureId, draftId)` → `run_proof(captureId,
+draftId)` → `create_provider_version_from_capture`.
 
 `reclaim_authenticate` itself always uses a local Chrome over loopback CDP. It
 never uses the container, remote Builder, custom-CDP, or shared authoring

package/skill/start-integration.md

@@ -2,9 +2,13 @@
 
 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.
+
+**Asking the developer.** When you need an answer or an action from the developer before you can continue, end your turn with the question. Don't use background or asynchronous question tools for blocking questions: the developer may never see them. Put every link the developer needs, such as a sign-in or verification URL, in that same message.
+
 ## 1. Sign in and pick the organization
 
-- [ ] Call `reclaim_authenticate` if you are not signed in. The developer approves in their browser.
+- [ ] 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 -->
@@ -12,63 +16,75 @@ Follow this plan end to end. Mark each step done as you go. Do not ask the devel
 - [ ] Call `list_orgs`. Use the only organization, or ask the developer which one when there are several.
 <!-- endif -->
 
-## 2. Set up the app
-
-Setup does not need the provider, so it runs in parallel with step 3 or before it.
-
-**Delegation.** If you can run subagents, hand this step to one subagent and start step 3 now: step 3 needs the developer at the browser, step 2 does not. Give the subagent a self-contained brief:
-
-```
-Goal: let this app's users prove "{{goal}}" with Reclaim.
-Repository: <absolute path>. Organization: <org ID>.
-Task: do step 2 of the plan below and report the file paths you changed, the
-callback route URL, and the env variable that holds the provider ID.
-Do not build the provider. Never print or commit the org key.
-<paste the step 2 checklist>
-```
-
-Without subagents, do step 2 first.
-
-- [ ] Detect the app's framework and package manager from the repository, and use them. Read `how_it_works({ topic: "integration" })`.
-- [ ] 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. Confirm the env file is in `.gitignore`.
-- [ ] Add a backend route that creates a verification session (`POST /verifications/sessions`) and returns `verificationUrl`. Read the provider ID from server config (an env variable such as `RECLAIM_PROVIDER_ID`), so the route works before the provider exists.
-- [ ] Add a callback route that verifies each result with `results.receive` from `@reclaimprotocol/client`, then stores only the requested data points.
-- [ ] Add a frontend Verify button that opens `verificationUrl`, and shows the stored result when it arrives.
-- [ ] Start the app. 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.
-<!-- ifnot:providerIds -->
-- [ ] Call `check_attestor` once. If it fails, tell the developer before they spend time on the provider build: this machine cannot reach the attestor.
-<!-- endif -->
-
-## 3. Get the provider
+## 2. Get the provider and prove it
 
 <!-- if:providerIds -->
 - [ ] Use these existing providers: {{providerIds}}. Read each with `get_provider` and keep only the data points "{{goal}}" needs. Show the developer and use only those; ignore the rest.
-- [ ] If a provider needs any change (a missing data point, inputs the developer didn't ask for, a different value), make your own copy as the server instructions describe ("Choose the provider"). Otherwise skip to step 4.
+- [ ] If a provider needs any change (a missing data point, inputs the developer didn't ask for, a different value), make your own copy as the server instructions describe ("Choose the provider"). Otherwise go on to step 3.
 <!-- endif -->
 <!-- ifnot:providerIds -->
 Build a new organization-private provider for exactly "{{goal}}". Do not search published providers first.
 
+- [ ] Call `check_attestor` once. If it fails, tell the developer before they spend time on the provider build: this machine cannot reach the attestor.
 - [ ] If the site, the account, or the value to prove is unclear, ask one concise question. Otherwise do not ask.
 - [ ] Choose the minimum data points: only the values the claim needs, usually one or two. Add no profile or identity extras.
 - [ ] If the developer names an existing provider, use only the data points they asked for and ignore the rest. If it needs any change, make your own copy: a new version when the organization owns it, otherwise a new organization provider from a copy of its config.
 - [ ] Call `how_it_works` with topics `overview`, `user-script`, `capture`, and `publish` before you start. Do not repeat their detail here.
-- [ ] Call `attach_browser` without `mode`, ask the developer which browser to use, then call it again with their choice. Use `start_capture` on the tab.
+- [ ] Call `attach_browser()` with no arguments. It opens a visible local browser, falling back to Chrome for Testing when no installed browser can be attached; don't ask which browser to use. Use another mode only if that fails too (topic `browser`). Mention once, as a side note, that a shareable link can be set up if a volunteer is helping the developer sign in; don't ask or set it up unless they ask. Use `start_capture` on the tab.
 - [ ] Open the sign-in page with `navigate`. The developer signs in; use `wait_for_login`.
 - [ ] Write the navigation script first. Signed out, it goes to the sign-in page. After sign-in, it visits each data page in order. It must stay correct across reloads.
 - [ ] Test it with `test_user_script` and `keep: true`. The kept script stays installed for every later navigation and is published with the provider version.
 - [ ] While the script drives the browser, find the request that returns each data point (`find_requests_containing`, then `analyze_request_constraints`).
 - [ ] Call `propose_provider` with only the needed data points.
 - [ ] Call `replay_request`, then `replay_request` with `withoutSecrets: true` to confirm the request is auth-bound.
-- [ ] Call `resolve_owner_key`, then `run_proof`.
+- [ ] Call `run_proof`. It creates a local test signing key if none exists; tell the developer once afterwards.
 - [ ] Call `create_provider_version_from_capture`. It publishes the kept script as `jsUserScripts`. Follow its `_notes`, then publish the version.
 - [ ] Call `dispose_browser` after asking the developer.
 <!-- endif -->
 
+## 3. Set up the app
+
+Setup does not need the provider. Start it after step 2 has a working proof, or while you wait on the developer during step 2 (for example, while they sign in to the site). Don't let it delay a step that needs the developer.
+
+**Delegation.** If you can run subagents, hand this step to one subagent as soon as you are signed in, and keep working on step 2: step 2 needs the developer at the browser, step 3 does not. Give the subagent a self-contained brief:
+
+```
+Goal: let this app's users prove "{{goal}}" with Reclaim.
+Repository: <absolute path>. Organization: <org ID>.
+Task: do step 3 of the plan below and report the file paths you changed, the
+callback route URL, and the env variable that holds the provider ID.
+Do not build the provider. Never print or commit the org key.
+<paste the step 3 checklist>
+```
+
+Without subagents, do step 2 first, and fill waits for the developer with this step.
+
+**No app yet?** If the workspace has no app to add verification to (it is empty, or has no backend or frontend), don't write one. Bootstrap from [builder-example](https://github.com/reclaimprotocol/builder-example), a ready-to-run Fastify backend and Vite frontend that already create sessions, verify callbacks, poll status, and render every UI state:
+
+- [ ] Clone it: `git clone --depth 1 https://github.com/reclaimprotocol/builder-example <dir>` (use the workspace itself when it is empty), then delete the clone's `.git` directory so the code becomes the developer's own.
+- [ ] Call `issue_org_token` with the clone's absolute path as `projectDir` and `envFile: "packages/backend/.env"`.
+- [ ] Only when the developer asks for session binding or encrypted results: call `issue_org_keypair` with the same `projectDir` and `envFile` (add `encryptResults: true` for encrypted results). It writes `RECLAIM_ORG_ETH_PRIVATE_KEY` and registers the public key. Then pass `orgEthPrivateKey: process.env.RECLAIM_ORG_ETH_PRIVATE_KEY` to `reclaim.sessions.create` in `packages/backend/src/routes/verifications.ts` (binding) and to `reclaim.results.receive` in `packages/backend/src/routes/callback.ts` (decryption and TEE proof checks), and add an empty `RECLAIM_ORG_ETH_PRIVATE_KEY=` line to `packages/backend/example.env`.
+- [ ] From the clone's root, run `npm install`, then `npm install @reclaimprotocol/client@latest -w packages/backend` so the backend uses the latest client rather than the version in the example's lockfile. Then run `npm run dev`. The backend listens on port 3000; the app opens at <http://localhost:5173>.
+- [ ] Call `proxy_callback_events({ port: 3000, path: "/reclaim/callback" })`.
+- [ ] Skip the rest of this step. In step 4, the provider goes in `packages/backend/config.json`: replace the example entry with `{ "id": "<provider ID>", "name": "<what it proves>" }`, then restart the backend, because it reads the file at startup.
+
+**Existing app.** Add verification to it:
+
+- [ ] Detect the app's framework and package manager from the repository, and use them. Read `how_it_works({ topic: "integration" })`.
+- [ ] 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. Confirm the env file is in `.gitignore`.
+- [ ] Add a backend route that creates a verification session (`POST /verifications/sessions`) and returns `verificationUrl`. Read the provider ID from server config (an env variable such as `RECLAIM_PROVIDER_ID`), so the route works before the provider exists.
+- [ ] Only when the developer asks for session binding or encrypted results: call `issue_org_keypair` with the server env file (`encryptResults: true` for encrypted results), and pass `orgEthPrivateKey` from that env variable to `sessions.create` and `results.receive`.
+- [ ] Add a callback route that verifies each result with `results.receive` from `@reclaimprotocol/client`, then stores only the requested data points. Store every failure on the verification session record and log it server-side: a failure event (`verification_rejected`, `verification_error`, `verification_cancelled`, `session_expired`), or a thrown `ResultVerificationError` (`error.reason` plus each failing proof's `reason`). Respond `error.retryable ? 503 : 200`. A result that failed verification gets 2xx, because retrying can't fix it. Read the exact pattern in `how_it_works({ topic: "integration" })`.
+- [ ] Add a status route the frontend polls. It returns the stored status, data points, and failure reason. While the app has no result, it also reads `GET /verifications/sessions/{sessionId}`, so a session that ended in Builder never stays pending.
+- [ ] Add a frontend Verify button that opens `verificationUrl`, and render every state in "UI states" in `how_it_works({ topic: "integration" })`: idle, waiting in the other tab, verifying, verified (with the data points), failed (plain-language reason and **Try again**), and expired or cancelled (**Try again**). Never leave a spinner as the only feedback.
+- [ ] Start the app. 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.
+
 ## 4. Wire the provider and test end to end
 
 - [ ] Set the provider ID in the app's server config.
-- [ ] Confirm the callback route is forwarding: `proxy_callback_events` with no `stop` returns its status.
-- [ ] Tell the developer exactly how to test: open the app, click Verify, sign in, and see the stored result.
-- [ ] After they click Verify, read the delivered events from `proxy_callback_events` status (`recent`) or `read_callback_events`. If the result did not arrive, call `list_verification_deliveries` and fix the cause. Repeat until the app shows the stored result.
+- [ ] Confirm the callback route is forwarding: `proxy_callback_events` with no `stop` returns its status. If `blocked` is not empty, the app rejected that session's event: read the callback route's response and logs, fix the app, and check again.
+- [ ] Tell the developer exactly how to test: open the app, click Verify, sign in, and see the stored result. Also test one failure, such as cancelling in the verification tab, and confirm the app shows the failed state with **Try again**.
+- [ ] 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 `list_verification_events` and `get_verification_session`, not by reading the page.
+- [ ] After they click Verify, read the delivered events from `proxy_callback_events` status (`recent`) or `read_callback_events`. If the result did not arrive, or the app shows an unexpected failure, call `list_verification_deliveries` and fix the cause. Repeat until the app shows the stored result.
 - [ ] Ask the developer to set up the production callback. The local listener works only while this coding agent's MCP server runs; once it stops, the deployed app receives no results. Call `create_org_callback_subscription` with the deployed app's public callback route URL for all five session-ending events: `verification_success`, `verification_rejected`, `verification_error`, `verification_cancelled`, and `session_expired`.
 - [ ] 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."

package/skill/verification-client-integration.md

@@ -7,8 +7,18 @@ plan. Don't ask whether to try, integrate, or create an app. Ask one short
 question only when intent is unclear. The steps below are the detail behind
 that plan.
 
-Inspect the app's frontend, backend, package manager, configuration, and
-callback conventions. Complete the integration in its codebase and run its
+Prove the provider before you write app code: sign in to Builder, attach the
+browser, capture, and run the proof first. Those steps need the developer, and
+they show whether a proof is possible on the site. Write the app code after the
+proof works, or while you wait on the developer. When you need the developer
+to answer or act, end your turn with the question and every link they need;
+don't ask through a background or asynchronous question tool.
+
+When the workspace has no app yet, bootstrap from
+[builder-example](https://github.com/reclaimprotocol/builder-example) as the
+`start_integration` plan describes, instead of writing a new backend and
+frontend. Otherwise, inspect the app's frontend, backend, package manager,
+configuration, and callback conventions. Complete the integration in its codebase and run its
 relevant checks. The MCP tools configure Builder resources; your file tools
 edit the app.
 
@@ -27,10 +37,11 @@ server), or migrate to the session flow below. When migrating, remove
    production): register a
    public callback URL with `create_org_callback_subscription`, including
    all five session-ending events. If the
-   app needs encrypted results, register its public key with `set_org_keypair`;
-   keep the private key only in the backend. `set_org_keypair` refuses to
-   replace an existing key unless you pass `replace: true`; pass it only when
-   the developer asks.
+   app needs encrypted results or session binding, call `issue_org_keypair`
+   (`encryptResults: true` for encrypted results). It writes the private key to
+   the backend's env file and registers only the public key. It returns 409
+   when the org already has a different key: ask the developer for that key
+   rather than replacing it.
 3. Org key: reuse the `RECLAIM_ORG_SECRET` the app already has. Otherwise an
    organization owner calls `issue_org_token`. It writes the key to the
    project's env file (default `.env`, variable `RECLAIM_ORG_SECRET`) and
@@ -47,18 +58,32 @@ server), or migrate to the session flow below. When migrating, remove
    is not proof of success. Use `@reclaimprotocol/client`
    (`ReclaimVerification.create({ orgSecret })`, `sessions.create`) only when
    the developer asks for it.
-5. Add a backend callback endpoint. Persist each delivery idempotently and load
+5. Add a backend callback route. Persist each delivery idempotently and load
    the expected session ID and org ID from app storage. To verify the result on
-   your callback, install `@reclaimprotocol/client` in the backend and call
+   your callback route, install `@reclaimprotocol/client` in the backend and call
    `reclaim.results.receive(body, { reclaimSessionId, expectedAud,
    orgEthPrivateKey })`. Use the verified proof data to update app state.
-   Handle callback retries and terminal failure outcomes.
+   Store every failure on the verification session record: failure events, and
+   a thrown `ResultVerificationError` (`error.reason` and each
+   `error.outcome.proofs[].reason`). Respond `error.retryable ? 503 : 200`.
+   A result that failed verification gets 2xx: retrying can't fix it, and an
+   unacknowledged delivery holds back that session's later events. Respond 5xx
+   for any other temporary problem too, such as a database outage.
+   Add a status route that returns the stored status, data points, and failure
+   reason. While the app has no result, it also reads
+   `GET /verifications/sessions/{sessionId}`, so a session Builder has ended
+   never stays pending in the app. Render the frontend per
+   [UI states](#ui-states).
 6. Exercise one session through the selected registered Verification Client,
    inspect its Builder events, and test the app's success and failure paths.
    Omit `verificationClientUrl` to use the Portal, or select another client
    from `VerificationClient` in the SDK. Do not send an unregistered URL or
    call a legacy backend for an `api=2` session.
 
+   The hosted verification page streams the target site as an image, so text
+   and DOM checks of that page come back empty. Check a session's progress
+   with `list_verification_events` and `get_verification_session` instead.
+
 The one-time management calls above use the developer's Builder login. The
 consumer backend uses the separate organization token. The SDK's API-only
 entry point, `@reclaimprotocol/client/api`, is available when an application
@@ -125,16 +150,37 @@ Receive and verify the result on the callback route. This is the one place the
 client package is needed:
 
 ```js
-import { ReclaimVerification } from '@reclaimprotocol/client'
+import { ReclaimVerification, ResultVerificationError } from '@reclaimprotocol/client'
 
 const reclaim = ReclaimVerification.create({
   orgSecret: process.env.RECLAIM_ORG_SECRET,
 })
 
 app.post('/reclaim/callback', async(req, res) => {
-  const outcome = await reclaim.results.receive(req.body, {
-    reclaimSessionId: sessionId, // the id you stored
-  })
+  let outcome
+  try {
+    outcome = await reclaim.results.receive(req.body, {
+      reclaimSessionId: sessionId, // the id you stored
+    })
+  } catch(error) {
+    if(!(error instanceof ResultVerificationError)) {
+      throw error
+    }
+
+    if(error.retryable) {
+      return res.sendStatus(503) // temporary: Builder retries the delivery
+    }
+
+    // Retrying can't fix a result that failed verification. Store the failure
+    // where the status route returns it, then acknowledge the delivery.
+    const proofReasons = (error.outcome.proofs ?? [])
+      .filter((proof) => !proof.proofValid)
+      .map((proof) => proof.reason)
+    console.warn('result failed verification', error.reason, proofReasons)
+    await markSessionFailed(sessionId, error.reason) // your app's storage
+    return res.sendStatus(200)
+  }
+
   if(outcome.kind === 'result') {
     console.log(outcome.result.payload) // verified
   }
@@ -143,8 +189,34 @@ app.post('/reclaim/callback', async(req, res) => {
 })
 ```
 
-Check or investigate a session, from the backend (optional, e.g. a status
-endpoint the frontend polls) or by hand with `curl`. All take the org key:
+### UI states
+
+Apply these rules when you write the frontend. Test each state, including one
+failure.
+
+| State | Render |
+| --- | --- |
+| Idle | The **Verify** button. |
+| Waiting in the other tab | The current step ("Finish verifying in the new tab") and a way to reopen `verificationUrl`. After about 30 seconds, say what is happening and offer **Cancel** or **Try again**. |
+| Verifying | "Checking your result". |
+| Verified | The requested data points. |
+| Failed | A plain-language reason and what to do next, near the **Verify** button, with **Try again**. |
+| Expired or cancelled | Say which, with **Try again**. |
+
+- Show the current step, never an indefinite spinner (Nielsen heuristic 1,
+  visibility of system status).
+- Write errors in plain language that says what happened and what to do next,
+  visible next to the action, with a recovery action (Nielsen Norman Group
+  error-message guidelines).
+- Send reason codes (`error.reason`, proof `reason`) to logs or an expandable
+  **Details** section, not the headline.
+- Announce changes: `role="status"` (or `aria-live="polite"`) for progress,
+  `role="alert"` for failures (WCAG 2.2 SC 4.1.3).
+- Pair color with text or an icon (WCAG 2.2 SC 1.4.1).
+- Stop the waiting state when the status route reports a terminal status.
+
+Check or investigate a session from the status route or by hand with `curl`.
+All routes take the org key:
 
 | Route | Use |
 | --- | --- |

package/src/authoring/backend.ts

@@ -35,6 +35,10 @@ export interface Draft {
 	/** One entry per extracted value (value + its redaction), so replay can
 	 *  validate each against its own selector. */
 	extractions: Extraction[]
+	/** Outcome of the latest authenticated in-browser replay, recorded by
+	 *  backends that track it. Lets a failed proof tell "the site blocks
+	 *  non-browser clients" apart from a broken recipe. */
+	lastReplay?: { status: number, ok: boolean }
 }
 
 /** A navigation script installed for every later page load of the authoring
@@ -49,10 +53,12 @@ export interface KeptScriptRef {
 	keptScript?: KeptScript
 }
 
-/** Per-session draft store: `propose` puts, `replay`/`run_proof` get by id. */
+/** Per-session draft store: `propose` puts, `replay`/`run_proof` get by id,
+ *  `update_draft` replaces one in place (same id). */
 export interface DraftStore {
 	put(draft: Draft): string
 	get(id: string): Draft | undefined
+	set(id: string, draft: Draft): void
 }
 
 export function makeDraftStore(): DraftStore {
@@ -64,6 +70,9 @@ export function makeDraftStore(): DraftStore {
 			return id
 		},
 		get: (id) => map.get(id),
+		set: (id, draft) => {
+			map.set(id, draft)
+		},
 	}
 }
 
@@ -73,6 +82,8 @@ export function makeDraftStore(): DraftStore {
 export interface ProveOptions {
 	ownerAddress?: string
 	attestorUrl?: string
+	/** ISO country the attestor's request goes out from (local proofs). */
+	geoLocation?: string
 }
 
 /**

package/src/authoring/tools.ts

@@ -20,8 +20,15 @@ import { proposeTool } from '../mcp/tools/agent/propose.ts'
 import { replayTool } from '../mcp/tools/agent/replay.ts'
 import type { CapturedRequest } from '../provider/schema.ts'
 import { defineTool, type RegisteredTool } from '../tools/registry.ts'
-import type { AuthoringBackend } from './backend.ts'
-import { objectSchema, publicRequest, type ResolveBackend } from './util.ts'
+import type { AuthoringBackend, ProveOptions } from './backend.ts'
+import {
+	DEFAULT_MAX_CHARS,
+	objectSchema,
+	publicRequest,
+	type ResolveBackend,
+	TEXT_WINDOW_PROPERTIES,
+	textWindow,
+} from './util.ts'
 
 const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms))
 
@@ -155,13 +162,40 @@ export function authoringTools(
 					+ 'Use it to read a data point from the DOM, check sign-in state, '
 					+ 'or trigger the target request (for example, `location.reload()`). '
 					+ 'The page cannot reach files or processes on this machine. Return '
-					+ 'only the values you need, never cookies or tokens.',
+					+ 'only the values you need, never cookies or tokens. A result '
+					+ `longer than ${DEFAULT_MAX_CHARS} characters comes back `
+					+ 'truncated (objects as JSON text) with `valueTruncation`; page '
+					+ 'with `offset`, or pass `maxChars` or `full`.',
 				inputSchema: objectSchema(
-					{ expression: { type: 'string' } }, ['expression'],
+					{ expression: { type: 'string' }, ...TEXT_WINDOW_PROPERTIES },
+					['expression'],
 				),
 				annotations: { openWorldHint: true, destructiveHint: false },
 			},
-			(args) => evalInPage(resolveBackend(args), String(args.expression)),
+			async(args) => {
+				const res = await evalInPage(
+					resolveBackend(args), String(args.expression),
+				)
+				if(res.value === undefined) {
+					return res
+				}
+
+				const text = typeof res.value === 'string'
+					? res.value
+					: JSON.stringify(res.value)
+				const slice = textWindow(text, args)
+				if(!slice.truncation) {
+					return res
+				}
+
+				return {
+					value: slice.text,
+					valueTruncation: {
+						...slice.truncation,
+						...(typeof res.value === 'string' ? {} : { format: 'json' }),
+					},
+				}
+			},
 		),
 		defineTool<Record<string, unknown>>(
 			{
@@ -484,7 +518,10 @@ export function authoringTools(
 					+ 'attestor calls the target from its own network and IP. A request '
 					+ 'that replayed can still fail here for geo- or IP-bound content '
 					+ '(country-locked pages, IP-allowlisted APIs); that is a property '
-					+ 'of the site, not a bug in the draft.',
+					+ 'of the site, not a bug in the draft. HTTP 403/406/429/503 or a '
+					+ 'challenge page from the attestor while the replay succeeded '
+					+ 'means the site blocks non-browser clients: copying headers or '
+					+ 'cookies will not help, so try a different endpoint or stop.',
 				inputSchema: objectSchema({ draftId: { type: 'string' } }, ['draftId']),
 				annotations: { openWorldHint: true, destructiveHint: false },
 			},
@@ -500,7 +537,7 @@ export function authoringTools(
 					throw new Error(`no draft ${String(args.draftId)}`)
 				}
 
-				const opts: { ownerAddress?: string, attestorUrl?: string } = {}
+				const opts: ProveOptions = {}
 				if(typeof args.ownerAddress === 'string') {
 					opts.ownerAddress = args.ownerAddress
 				}
@@ -509,6 +546,10 @@ export function authoringTools(
 					opts.attestorUrl = args.attestorUrl
 				}
 
+				if(typeof args.geoLocation === 'string') {
+					opts.geoLocation = args.geoLocation
+				}
+
 				return backend.prove(draft, opts)
 			},
 		),

package/src/authoring/util.ts

@@ -43,3 +43,67 @@ export function publicRequest(r: CapturedRequest) {
 		...(r.graphqlOp ? { graphqlOp: r.graphqlOp } : {}),
 	}
 }
+
+/** Characters a long text field returns by default (about 20 KB of ASCII),
+ *  so one page body or eval result can't flood the caller's context. */
+export const DEFAULT_MAX_CHARS = 20_000
+
+export interface TextWindowArgs {
+	maxChars?: unknown
+	offset?: unknown
+	full?: unknown
+}
+
+/** Input properties that let a caller page through, or opt out of, the
+ *  window {@link textWindow} applies. */
+export const TEXT_WINDOW_PROPERTIES = {
+	maxChars: {
+		type: 'integer',
+		minimum: 1,
+		description: `Maximum characters to return. Default ${DEFAULT_MAX_CHARS}.`,
+	},
+	offset: {
+		type: 'integer',
+		minimum: 0,
+		description: 'Character offset to start from, such as a previous '
+			+ '`nextOffset`. Default 0.',
+	},
+	full: {
+		type: 'boolean',
+		description: 'Return the whole text, ignoring `maxChars`. It can be '
+			+ 'megabytes, so prefer paging with `offset`.',
+	},
+} satisfies Record<string, JSONSchema.BaseSchema>
+
+/**
+ * Returns characters `[offset, offset + maxChars)` of `text`. When that isn't
+ * the whole text, `truncation` reports the total size and how to get the rest.
+ */
+export function textWindow(text: string, args: TextWindowArgs) {
+	const totalChars = text.length
+	const offset = Math.min(Math.max(Number(args.offset) || 0, 0), totalChars)
+	const maxChars = args.full === true
+		? totalChars
+		: Math.max(Number(args.maxChars) || DEFAULT_MAX_CHARS, 1)
+	const end = Math.min(offset + maxChars, totalChars)
+	if(offset === 0 && end === totalChars) {
+		return { text }
+	}
+
+	const part = text.slice(offset, end)
+	const more = end < totalChars
+	return {
+		text: part,
+		truncation: {
+			totalChars,
+			offset,
+			returnedChars: part.length,
+			...(more ? { nextOffset: end } : {}),
+			note: `Returned characters ${offset}-${end} of ${totalChars}.`
+				+ (more
+					? ` Call again with offset: ${end} for more, or full: true `
+						+ 'for the whole text.'
+					: ''),
+		},
+	}
+}

package/src/cdp/chrome-for-testing.ts

@@ -0,0 +1,66 @@
+import { failedDependency } from '@hapi/boom'
+import assert from 'node:assert'
+import { existsSync } from 'node:fs'
+import { arch, platform } from 'node:os'
+import { join } from 'node:path'
+import { LOGGER } from '../logger.ts'
+import { reclaimHomeDirPath } from '../paths.ts'
+
+export interface ChromeForTestingInstall {
+	executablePath: string
+	/** True when this call downloaded it; false when an earlier one had. */
+	downloaded: boolean
+}
+
+/** Where downloaded browsers live: `~/.reclaim/browsers`. */
+export function browsersDirPath() {
+	return join(reclaimHomeDirPath(), 'browsers')
+}
+
+/**
+ * Chrome for Testing, the fallback when no local Chromium-family browser is
+ * installed or the installed one will not start. Downloaded once into
+ * `~/.reclaim/browsers` and reused after that, so only the first fallback pays
+ * the ~150 MB download.
+ */
+export async function installChromeForTesting(
+	cacheDir = browsersDirPath(),
+): Promise<ChromeForTestingInstall> {
+	// Loaded on demand: only the fallback path needs it.
+	const {
+		Browser,
+		detectBrowserPlatform,
+		getInstalledBrowsers,
+		getVersionComparator,
+		install,
+		resolveBuildId,
+	} = await import('@puppeteer/browsers')
+	const browserPlatform = detectBrowserPlatform()
+	assert(browserPlatform, failedDependency(
+		`Chrome for Testing has no build for ${platform()}/${arch()}.`,
+	))
+
+	const compare = getVersionComparator(Browser.CHROME)
+	const all = await getInstalledBrowsers({ cacheDir })
+	const installed = all
+		.filter((b) => b.browser === Browser.CHROME
+			&& b.platform === browserPlatform
+			&& existsSync(b.executablePath))
+		.sort((a, b) => compare(a.buildId, b.buildId))
+	const newest = installed.at(-1)
+	if(newest) {
+		return { executablePath: newest.executablePath, downloaded: false }
+	}
+
+	const buildId = await resolveBuildId(
+		Browser.CHROME, browserPlatform, 'stable',
+	)
+	LOGGER.info({ buildId, cacheDir }, 'downloading Chrome for Testing')
+	const result = await install({
+		browser: Browser.CHROME,
+		platform: browserPlatform,
+		buildId,
+		cacheDir,
+	})
+	return { executablePath: result.executablePath, downloaded: true }
+}