@reclaimprotocol/agent 0.1.33 → 0.1.34

package/skill/user-script.md

@@ -47,6 +47,70 @@ Do not clear cookies or force another sign-in; inconclusive coverage must not
 block publication. This browser check does not emulate a client-specific
 interceptor.
 
+## Write the navigation script first
+
+Write the navigation script as soon as the developer is signed in, or as soon
+as you know the sign-in page. Then capture through it, so authoring, testing,
+and verification follow the same path.
+
+The script does two things:
+
+1. **Signed out:** send the user to the sign-in page.
+2. **Signed in:** visit each page that holds a data point, in order. Data
+   points can live on different pages. Keep a step index in `sessionStorage` so
+   the script survives reloads and repeated runs.
+
+Loop: `test_user_script({ script, keep: true })` → fix → retest. With `keep:
+true` the script stays installed for every later navigation in the authoring
+browser, as it does at verification. `create_provider_version_from_capture`
+publishes it as `webSettings.jsUserScripts` unless you pass your own.
+
+```js
+(() => {
+	const SIGN_IN = '/login'
+	const STEPS = [
+		{ path: '/account', ready: () => document.querySelector('#dob') },
+		{ path: '/settings/profile', ready: () => document.querySelector('#plan') },
+	]
+	const signedIn = () => document.querySelector('[data-user-menu]')
+		&& !document.querySelector('a[href="/login"]')
+	let tries = 0
+	const timer = setInterval(() => {
+		if(++tries > 120) {
+			return clearInterval(timer)
+		}
+
+		if(!signedIn()) {
+			// stay put on the sign-in page; also covers unknown pages
+			if(location.pathname !== SIGN_IN) {
+				clearInterval(timer)
+				location.assign(SIGN_IN)
+			}
+
+			return
+		}
+
+		const i = Number(sessionStorage.getItem('rc-step') || 0)
+		const step = STEPS[i]
+		if(!step) {
+			return clearInterval(timer)
+		}
+
+		if(location.pathname !== step.path) {
+			clearInterval(timer)
+			return location.assign(step.path)
+		}
+
+		if(step.ready()) {
+			sessionStorage.setItem('rc-step', String(i + 1))
+		}
+	}, 500)
+})()
+```
+
+Adapt the selectors to the site. Each new tab starts at the first step, and a
+reload resumes at the current step.
+
 ## `window.Reclaim` — rarely needed
 
 `window.Reclaim` is an optional bridge for a handful of edge cases. Most

package/skill/verification-client-integration.md

@@ -2,31 +2,38 @@
 
 ## Set up an application with the coding agent
 
-When asked to integrate Reclaim into an app, inspect that 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; the coding agent's file tools edit the app.
+For "add Reclaim to my app", call `start_integration` first and follow its
+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
+relevant checks. The MCP tools configure Builder resources; your file tools
+edit the app.
 
 If the app depends on `@reclaimprotocol/js-sdk`, ask the developer first:
-keep it (call `set_devtools_mode({ mode: "old" })` and have them restart the MCP
-server), or migrate to the Builder session flow below. When
-migrating, remove `@reclaimprotocol/js-sdk` and replace its
-`ReclaimProofRequest` and `verifyProof` calls with the session flow below.
-
-1. Use `get_devtools_mode` to confirm Builder mode and `get_me` or
-   `authenticate` to sign in as the developer. Find the intended organization
-   with `list_orgs`; call `create_org` only when a new organization is wanted.
+keep it (`set_devtools_mode({ mode: "old" })`, then they restart the MCP
+server), or migrate to the session flow below. When migrating, remove
+`@reclaimprotocol/js-sdk` and replace its `ReclaimProofRequest` and
+`verifyProof` calls.
+
+1. `get_devtools_mode` confirms Builder mode. `get_me` or `authenticate` signs
+   in the developer. Find the organization with `list_orgs`; call `create_org`
+   only when they want a new one.
 2. Register a callback URL owned by the app's backend with
    `create_org_callback_subscription`. Include terminal success, rejection,
    error, cancellation, and expiry events. If the app needs encrypted results,
-   register its public key with `set_org_keypair`; retain the private key only
-   in the backend.
-3. Reuse a `RECLAIM_ORG_SECRET` the app already has. Otherwise an organization
-   owner calls `issue_org_token`; its `orgSecret` is shown once. Write it with
-   your file tools into the backend's env file (for example
-   `RECLAIM_ORG_SECRET=rorg_…` in `.env`) and make sure that file is
-   gitignored. Keep it out of frontend bundles, logs, source control, and the
-   final response.
+   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.
+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
+   returns only the last four characters and the file path. Make sure that file
+   is gitignored. Never print the key, put it in the conversation, or ask the
+   developer to paste it. Keep it out of frontend bundles, logs, and source
+   control.
 4. Prefer plain HTTP from the backend (see [Code to write](#code-to-write)).
    Create sessions with `POST /verifications/sessions`
    (`Authorization: Bearer $RECLAIM_ORG_SECRET`), save each returned session ID
@@ -60,8 +67,7 @@ The MCP session tools (`create_verification_session`,
 `delete_callback_subscription`, `bind_verification_session_tee_nonce`, and
 `get_verification_result`) call these same production endpoints with the org
 key: pass it as `orgToken`, or let them fall back to the MCP server's
-`RECLAIM_ORG_SECRET`. Use them, or `curl` with the key from `.env`, to test the
-integration end to end.
+`RECLAIM_ORG_SECRET`. Use them to test the integration end to end.
 
 ## Code to write
 

package/src/authoring/backend.ts

@@ -37,6 +37,18 @@ export interface Draft {
 	extractions: Extraction[]
 }
 
+/** A navigation script installed for every later page load of the authoring
+ *  session. `identifier` is the CDP registration, so it can be removed. */
+export interface KeptScript {
+	script: string
+	identifier?: string
+}
+
+/** Holds the session's kept script, replaced by each `keep` call. */
+export interface KeptScriptRef {
+	keptScript?: KeptScript
+}
+
 /** Per-session draft store: `propose` puts, `replay`/`run_proof` get by id. */
 export interface DraftStore {
 	put(draft: Draft): string
@@ -75,6 +87,9 @@ export interface AuthoringBackend {
 	 * out. Cloud authoring enables this; local MCP keeps its existing
 	 * behavior. */
 	readonly readOnlyPageEval?: boolean
+	/** Where `test_user_script` keeps its script. Absent for hosts that do not
+	 * publish it (the cloud loop synthesizes its own navigation script). */
+	readonly kept?: KeptScriptRef
 	/** Send a raw CDP command scoped to this session's page. */
 	sendCdp(method: string, params?: Record<string, unknown>): Promise<unknown>
 	/** Resolve once `method` (a CDP event) fires on this session's page, or

package/src/authoring/index.ts

@@ -4,6 +4,8 @@ export type {
 	AuthoringBackend,
 	Draft,
 	DraftStore,
+	KeptScript,
+	KeptScriptRef,
 	ProveOptions,
 	SecretParams,
 } from './backend.ts'

package/src/authoring/tools.ts

@@ -14,6 +14,7 @@
  * draft (recipe + secrets) is held server-side; the model only sees an opaque
  * `draftId` and the secret-free provider.
  */
+import assert from 'node:assert'
 import { findTool } from '../mcp/tools/agent/find.ts'
 import { proposeTool } from '../mcp/tools/agent/propose.ts'
 import { replayTool } from '../mcp/tools/agent/replay.ts'
@@ -117,13 +118,15 @@ export function authoringTools(
 			{
 				name: 'navigate',
 				description:
-					'Navigate the captured tab to a URL and wait for its load event. '
-					+ 'Returns the URL the tab actually landed on, so you can detect a '
-					+ 'redirect to a login page.',
+					'Navigates the captured tab to a URL and waits for its load event. '
+					+ 'Returns the URL the tab landed on, to detect a redirect to a '
+					+ 'sign-in page. Any navigation script kept by `test_user_script` '
+					+ 'runs on the page.',
 				inputSchema: objectSchema(
 					{ url: { type: 'string' }, timeoutMs: { type: 'number' } },
 					['url'],
 				),
+				annotations: { openWorldHint: true, destructiveHint: false },
 			},
 			async(args) => {
 				const backend = resolveBackend(args)
@@ -147,13 +150,16 @@ export function authoringTools(
 			{
 				name: 'eval_in_page',
 				description:
-					'Evaluate a JavaScript expression in the page and return its value. '
-					+ 'Use it to read the value being proven out of the DOM, to check '
-					+ 'login state, or to trigger the target request (for example, '
-					+ '`location.reload()`).',
+					'Evaluates a JavaScript expression in the page of the remote '
+					+ 'authoring browser, not on this machine, and returns its value. '
+					+ '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.',
 				inputSchema: objectSchema(
 					{ expression: { type: 'string' } }, ['expression'],
 				),
+				annotations: { openWorldHint: true, destructiveHint: false },
 			},
 			(args) => evalInPage(resolveBackend(args), String(args.expression)),
 		),
@@ -161,14 +167,16 @@ export function authoringTools(
 			{
 				name: 'wait_for_page',
 				description:
-					'Poll a JavaScript expression once a second until it is truthy or '
-					+ 'the timeout elapses. Use it to wait for content to appear. To '
-					+ 'wait for a login, use wait_for_login instead — page JavaScript '
-					+ 'cannot see the httpOnly session cookie.',
+					'Evaluates a JavaScript expression in the remote authoring browser '
+					+ 'once a second until it is truthy or the timeout elapses. Returns '
+					+ '{ ready }. Use it to wait for content to appear. To wait for a '
+					+ 'sign-in, use `wait_for_login`: page JavaScript cannot see the '
+					+ 'httpOnly session cookie.',
 				inputSchema: objectSchema(
 					{ expression: { type: 'string' }, timeoutMs: { type: 'number' } },
 					['expression'],
 				),
+				annotations: { readOnlyHint: true, openWorldHint: true },
 			},
 			async(args) => {
 				const backend = resolveBackend(args)
@@ -190,27 +198,34 @@ export function authoringTools(
 			{
 				name: 'test_user_script',
 				description:
-					'Dry-run a USER SCRIPT (the `jsUserScripts` / `customInjection` '
-					+ 'field) in the LIVE attached tab while authoring or after provider '
-					+ 'creation. Installs '
-					+ '`script` via CDP so it runs on the next navigation exactly as '
-					+ 'the real field would, then reports whether it ran and what it '
-					+ 'threw. With `navigateUrl`, it navigates there and removes the '
-					+ 'script once the result is read — self-cleaning, safe to repeat. '
-					+ 'WITHOUT `navigateUrl` the script stays installed (navigate '
-					+ 'yourself, then re-call this tool or read '
-					+ '`window.__reclaimUserScriptResult` via eval_in_page) and keeps '
-					+ 'running on every later navigation until a call WITH '
-					+ '`navigateUrl` removes it — so don\'t stack manual-mode calls. '
-					+ 'Guide: how_it_works({ topic: "user-script" }).',
+					'Installs a navigation script (the `jsUserScripts` field) in the '
+					+ 'remote authoring browser, not on this machine, so it runs before '
+					+ 'each page load, as it does at verification. Reports whether it '
+					+ 'ran and what it threw. With `navigateUrl`, navigates there and '
+					+ 'removes the script after reading the result, unless `keep` is '
+					+ 'true. Without `navigateUrl`, the script stays installed for '
+					+ 'later navigations until a call with `navigateUrl` removes it. '
+					+ 'With `keep: true`, the script stays installed for every later '
+					+ 'navigation in this session, replaces any earlier kept script, and '
+					+ '`create_provider_version_from_capture` publishes it as '
+					+ '`jsUserScripts` unless that call passes its own. '
+					+ 'See how_it_works({ topic: "user-script" }).',
 				inputSchema: objectSchema(
 					{
 						script: { type: 'string' },
 						navigateUrl: { type: 'string' },
 						timeoutMs: { type: 'number' },
+						keep: {
+							type: 'boolean',
+							description:
+								'Keep the script installed for every later navigation in '
+								+ 'this session and use it as the published navigation '
+								+ 'script.',
+						},
 					},
 					['script'],
 				),
+				annotations: { openWorldHint: true, destructiveHint: false },
 			},
 			async(args) => {
 				const backend = resolveBackend(args)
@@ -235,13 +250,37 @@ export function authoringTools(
 						);
 					}
 				`
+				const keep = args.keep === true
+				const kept = keep ? backend.kept : undefined
+				assert(
+					!keep || kept,
+					new Error('This host does not support `keep`.'),
+				)
+				// Replace, never stack: only one kept script runs.
+				const previous = kept?.keptScript?.identifier
+				if(previous) {
+					await backend.sendCdp(
+						'Page.removeScriptToEvaluateOnNewDocument',
+						{ identifier: previous },
+					).catch(() => {})
+				}
+
 				const installed = (await backend.sendCdp(
 					'Page.addScriptToEvaluateOnNewDocument', { source: wrapped },
 				)) as { identifier?: string }
+				if(kept) {
+					kept.keptScript = {
+						script,
+						...(installed.identifier
+							? { identifier: installed.identifier }
+							: {}),
+					}
+				}
 
 				if(typeof args.navigateUrl !== 'string') {
 					return {
 						installed: true,
+						...(keep ? { kept: true } : {}),
 						note:
 							'Installed for the NEXT navigation only — it did not run on '
 							+ 'the current page, and stays installed (runs on every later '
@@ -276,6 +315,7 @@ export function authoringTools(
 						value as { ran?: boolean, errors?: string[] } | undefined
 					return {
 						installed: true,
+						...(keep ? { kept: true } : {}),
 						navigated: true,
 						ran: result?.ran ?? false,
 						errors: result?.errors ?? [],
@@ -283,7 +323,7 @@ export function authoringTools(
 				} finally {
 					// One-shot test: remove it so it doesn't keep running (and
 					// potentially redirecting the tab) on every later navigation.
-					if(installed.identifier) {
+					if(installed.identifier && !keep) {
 						await backend.sendCdp(
 							'Page.removeScriptToEvaluateOnNewDocument',
 							{ identifier: installed.identifier },
@@ -296,13 +336,14 @@ export function authoringTools(
 			{
 				name: 'get_cookies',
 				description:
-					'List the NAMES of cookies currently set for the page (values are '
-					+ 'NEVER returned). The most reliable, language- and DOM-independent '
-					+ 'login signal: after the user logs in, an auth/session cookie '
-					+ 'appears (for example, session, sid, token, auth, jwt, _user, '
-					+ 'logged_in). '
-					+ 'Includes httpOnly cookies the page JS cannot see.',
+					'Returns the names, domains, and flags of the cookies set in the '
+					+ 'remote authoring browser. Values are never returned; they stay '
+					+ 'in the browser and on the server. A new auth or session cookie '
+					+ '(for example, session, sid, auth, jwt) is a reliable sign-in '
+					+ 'signal that does not depend on the page language or DOM. '
+					+ 'Includes httpOnly cookies that page JavaScript cannot see.',
 				inputSchema: objectSchema({}),
+				annotations: { readOnlyHint: true, openWorldHint: true },
 			},
 			async(args) => {
 				const backend = resolveBackend(args)
@@ -337,6 +378,7 @@ export function authoringTools(
 					+ 'navigating to the login page. Does NOT navigate (never yanks '
 					+ 'the user off login/2FA). Returns { loggedIn, newCookies }.',
 				inputSchema: objectSchema({ timeoutMs: { type: 'number' } }),
+				annotations: { readOnlyHint: true, openWorldHint: true },
 			},
 			async(args) => {
 				const backend = resolveBackend(args)
@@ -402,9 +444,10 @@ export function authoringTools(
 			{
 				name: 'list_requests',
 				description:
-					'List captured network requests (method/url/status/size), newest '
-					+ 'last. Optionally filter by method / urlGlob / status range / '
-					+ 'contentType / graphqlOp. Metadata only — secrets never included.',
+					'Lists captured network requests (method, URL, status, size), '
+					+ 'newest last. Filter by method, urlGlob, status range, '
+					+ 'contentType, or graphqlOp. Returns metadata only, never '
+					+ 'secrets.',
 				inputSchema: objectSchema({
 					filter: {
 						type: 'object',
@@ -418,6 +461,7 @@ export function authoringTools(
 						},
 					},
 				}),
+				annotations: { readOnlyHint: true, openWorldHint: false },
 			},
 			async(args) => {
 				const backend = resolveBackend(args)
@@ -434,15 +478,15 @@ export function authoringTools(
 			{
 				name: 'run_proof',
 				description:
-					'Prove the drafted recipe (zkTLS). Only call after replay_request '
-					+ 'looks right. Returns the proof result. NOTE: unlike '
-					+ 'replay_request (which re-issues from inside the live attached '
-					+ 'browser tab), the ATTESTOR calls the target from its OWN '
-					+ 'network/IP, separate from the browser\'s. A request that '
-					+ 'replayed fine can still fail here for geo/IP-bound content '
-					+ '(country-locked pages, IP-allowlisted APIs) — if that happens, '
-					+ 'it\'s a property of the site, not a bug in the draft.',
+					'Proves the drafted recipe (zkTLS). Call it after `replay_request` '
+					+ 'looks right. Returns the proof result. Unlike `replay_request`, '
+					+ 'which re-sends from inside the attached browser tab, the '
+					+ '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.',
 				inputSchema: objectSchema({ draftId: { type: 'string' } }, ['draftId']),
+				annotations: { openWorldHint: true, destructiveHint: false },
 			},
 			// The backend shapes its own result: the cloud returns a lean,
 			// secret-free summary (and records the proven recipe for publish); the

package/src/config/store.ts

@@ -27,6 +27,8 @@ export interface ReclaimAgentConfig {
  *   - `old_devtools`  — externally-supplied identity for OLD-devtools mode
  *                       (USE_OLD_DEVTOOLS); independent of `session`'s
  *                       builder token. Deletable with the rest of `src/old/`.
+ *   - `org_keys`      — organization API keys saved by `issue_org_token`, so
+ *                       the org-key tools work without the key in a transcript
  * Sections are persisted independently via `ConfigStore.write`, which
  * merges rather than replaces, so one subsystem never clobbers another's.
  *
@@ -40,6 +42,15 @@ export interface ReclaimConfig {
 	browser_agent?: ReclaimAgentConfig
 	session?: CachedSession
 	old_devtools?: OldIdentity
+	org_keys?: SavedOrgKeys
+}
+
+/** Organization API keys (`rorg_…`) saved by `issue_org_token`. */
+export interface SavedOrgKeys {
+	/** Key by organization ID. */
+	byOrg: Record<string, string>
+	/** The organization whose key was saved last. */
+	recent?: string
 }
 
 /** Which backend the MCP server targets. See `resolveOldMode` in consts.ts. */