@reclaimprotocol/agent 0.1.33 → 0.1.35

package/README.md

@@ -25,7 +25,7 @@ This package **is** the Reclaim MCP server (bin: `reclaim-mcp-server`). It depen
 - **Node 20 or later.** Any line works, including non-LTS ones such as 25, but a current LTS line (22 or 24) is recommended.
 - **A local Chrome, Chromium, or Edge**, used for capture and for the dashboard login.
 - **Docker** — only for `attach_browser`'s `container` mode, which runs the Reclaim browser runtime (the same image the hosted browser uses) and gives you a link you can send to whoever holds the account. It is the free way to get that link; the hosted remote browser is the other, and it is chargeable. Not needed if you are doing the work yourself. The image is amd64, so Apple Silicon runs it translated. OrbStack handles that itself; Docker Desktop needs Rosetta enabled. `RECLAIM_BROWSER_RUNTIME_IMAGE` overrides the pinned digest.
-- **`cloudflared`** — only to share a `container` browser with someone remote. The MCP server does not run or install it: `share_browser_view` returns the command, and the agent runs `cloudflared tunnel --url http://localhost:<port>` itself, so install it yourself first.
+- **`cloudflared`** — only to share a `container` browser with someone remote. The MCP server does not run or install it: `share_browser_view` returns the command, and the developer chooses to run `cloudflared tunnel --url http://localhost:<port>` themselves (recommended) or approve the agent running it. Install it first.
 
 The first time you call `run_proof`, the agent downloads the ZK circuit files it needs (about 280 MB), so allow a moment for that first proof. The download is deferred to the first proof rather than run at install time, so the MCP server itself starts immediately.
 
@@ -120,7 +120,7 @@ These capture/synthesis/proof tools are backend-independent and registered in bo
 | `create_provider_version_from_capture`      | Publish a draft as a new immutable semantic version (patch by default)                                         |
 | `authenticate_builder`                      | In old-devtools mode only, sign in to Builder for remote-browser allocation                                   |
 | `list_builder_organizations`                | In old-devtools mode only, list organization ids for a quota-accounted Builder browser                         |
-| `share_browser_view`                        | Share the `container` browser's own live view with someone elsewhere. Returns the local viewer port and the `cloudflared tunnel` command for the agent to run; call it again with the printed `https://*.trycloudflare.com` URL as `publicUrl` to get the link to relay. Container mode only: a `builder` browser already returns a hosted `liveViewUrl`, and a plain local browser has no view to share |
+| `share_browser_view`                        | Share the `container` browser's own live view with someone elsewhere. Returns the local viewer port and the `cloudflared tunnel` command; the developer runs it or approves the agent running it; call it again with the printed `https://*.trycloudflare.com` URL as `publicUrl` to get the link to relay. Container mode only: a `builder` browser already returns a hosted `liveViewUrl`, and a plain local browser has no view to share |
 | `dispose_browser`                           | Stop captures, disconnect CDP, and immediately release a Builder-hosted browser                               |
 | `get_session`, `reset_session`              | Session state                                                                                                  |
 
@@ -134,7 +134,7 @@ The MCP server targets one of two backends. An explicit `USE_OLD_DEVTOOLS` setti
   - `get_me_providers` — list the providers you own (the only provider-listing tool in this mode).
   - `session_analytics_logs` — the milestone events for a verification session, which show how far it got.
   - `session_logs` — the log entries the in-app SDK emitted during that session, each with its event type, log level, and logger name. Filter by event type, level, or substring, page with `limit` and `offset`, or set `saveTo` to write every matching entry to an NDJSON file. The backend searches only the last 3 days unless you pass `startTime` and `endTime`, and it deletes entries after 30 days.
-- **Builder (default).** Registers the auto-generated HTTP-API tools, including `create_org`, `issue_org_token`, and `create_org_callback_subscription`, plus authentication/credential tools and `get_verification_result`. `issue_credentials` creates a local proof-owner key; `issue_org_token` issues the organization's API secret.
+- **Builder (default).** Registers the auto-generated HTTP-API tools, including `create_org`, `issue_org_token`, and `create_org_callback_subscription`, plus authentication/credential tools, `get_verification_result`, `read_callback_events` (read the org's pull-listener events), `proxy_callback_events` (forward them to a localhost callback route; the pull listener lives only while the MCP server runs), and `check_attestor`. `issue_credentials` creates a local proof-owner key; `issue_org_token` issues the organization's API secret.
 
 Relevant env vars: `RECLAIM_OLD_API_URL` (default `https://devapi.reclaimprotocol.org`), `RECLAIM_OLD_API_TOKEN` / `RECLAIM_OLD_ETH_UID` (headless identity), `RECLAIM_OLD_LOGIN_URL` (default `https://dev.reclaimprotocol.org`); builder mode uses `RECLAIM_API_URL` / `RECLAIM_API_TOKEN`.
 

package/lib/authoring/backend.d.ts

@@ -21,6 +21,16 @@ export interface Draft {
      *  validate each against its own selector. */
     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;
@@ -46,6 +56,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/lib/authoring/index.d.ts

@@ -1,4 +1,4 @@
-export type { AuthoringBackend, Draft, DraftStore, ProveOptions, SecretParams, } from './backend.ts';
+export type { AuthoringBackend, Draft, DraftStore, KeptScript, KeptScriptRef, ProveOptions, SecretParams, } from './backend.ts';
 export { makeDraftStore } from './backend.ts';
 export { authoringTools } from './tools.ts';
 export { defineTool, errorAsToolText, extendTool, type RegisteredTool, type ToolDefinition, } from '../tools/registry.ts';

package/lib/authoring/tools.js

@@ -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.js";
 import { proposeTool } from "../mcp/tools/agent/propose.js";
 import { replayTool } from "../mcp/tools/agent/replay.js";
@@ -80,10 +81,12 @@ export function authoringTools(resolveBackend) {
     return [
         defineTool({
             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.',
+            description: '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);
             const timeoutMs = Number(args.timeoutMs) || 30000;
@@ -100,19 +103,24 @@ export function authoringTools(resolveBackend) {
         }),
         defineTool({
             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()`).',
+            description: '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))),
         defineTool({
             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.',
+            description: '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);
             const expr = String(args.expression);
@@ -128,24 +136,30 @@ export function authoringTools(resolveBackend) {
         }),
         defineTool({
             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" }).',
+            description: '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);
             const script = String(args.script);
@@ -169,10 +183,27 @@ export function authoringTools(resolveBackend) {
 						);
 					}
 				`;
+            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 }));
+            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 '
                         + 'navigation too) until a follow-up call with navigateUrl '
@@ -198,6 +229,7 @@ export function authoringTools(resolveBackend) {
                 const result = value;
                 return {
                     installed: true,
+                    ...(keep ? { kept: true } : {}),
                     navigated: true,
                     ran: result?.ran ?? false,
                     errors: result?.errors ?? [],
@@ -206,20 +238,21 @@ export function authoringTools(resolveBackend) {
             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 });
                 }
             }
         }),
         defineTool({
             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.',
+            description: '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);
             const res = (await backend.sendCdp('Network.getCookies'));
@@ -243,6 +276,7 @@ export function authoringTools(resolveBackend) {
                 + '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);
             const deadline = Date.now() + (Number(args.timeoutMs) || 180000);
@@ -299,9 +333,10 @@ export function authoringTools(resolveBackend) {
         }),
         defineTool({
             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.',
+            description: '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',
@@ -315,6 +350,7 @@ export function authoringTools(resolveBackend) {
                     },
                 },
             }),
+            annotations: { readOnlyHint: true, openWorldHint: false },
         }, async (args) => {
             const backend = resolveBackend(args);
             const filter = (args.filter ?? {});
@@ -327,15 +363,15 @@ export function authoringTools(resolveBackend) {
         replayTool(resolveBackend),
         defineTool({
             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.',
+            description: '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/lib/config/store.d.ts

@@ -16,6 +16,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.
  *
@@ -29,6 +31,14 @@ 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. */
 export type DevtoolsMode = 'old' | 'builder';