@reclaimprotocol/agent 0.1.26 → 0.1.28

package/README.md

@@ -69,12 +69,12 @@ Or more loosely:
 
 The agent orchestrates the tools for you:
 
-1. **`reclaim_authenticate`** — a Chrome window opens the Reclaim dashboard; you sign in. The token is captured automatically and the tab closes. (Or it reuses a still-valid cached identity.)
+1. **`reclaim_authenticate`** — a local Chrome window opens the Reclaim dashboard; you sign in. The token is captured automatically and the tab closes. It never uses a Builder, container, custom-CDP, or shared browser. (Or it reuses a still-valid cached identity.)
 2. **`attach_browser` + `navigate`** — uses local Chrome, a Builder-hosted remote browser, or a custom CDP websocket; **`wait_for_page`** waits while you log in.
 3. **`start_capture` → `find_requests_containing` → `get_request`** — records network traffic and locates the request carrying your value.
 4. **`propose_provider`** — drafts the provider (a `contains` match + `jsonPath`/`xPath`/`regex` redaction), keeping any secret headers server-side.
 5. **`replay_request` → `run_proof`** — pre-flights the draft, then produces a verified zkTLS proof via the attestor.
-6. **`create_provider_version_from_capture`** — publishes it. **`get_me_providers`** lists what you own; pass a returned `providerId` back to publish a new version of an existing provider.
+6. **`create_provider_version_from_capture`** — publishes it as a new immutable semantic version. **`get_me_providers`** lists what you own; pass a returned `providerId` back to add a version. Patch is the default; request `major`, `minor`, `patch`, or an exact higher version.
 
 Your only manual steps are signing in when the browser windows open and confirming the value you want to prove.
 
@@ -98,7 +98,7 @@ These capture/synthesis/proof tools are backend-independent and registered in bo
 | `propose_provider`                          | Synthesize a provider — `contains` match + `jsonPath`/`xPath`/`regex` redaction                                |
 | `replay_request`                            | Pre-flight replay via Node `fetch` (no attestor); also used for auth-bound check by omitting `secretParamsRef` |
 | `run_proof`                                 | End-to-end zkTLS proof through the attestor SDK                                                                |
-| `create_provider_version_from_capture`      | Publish a drafted provider to the backend                                                                      |
+| `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`, `stop_browser_view`   | Put the `container` browser's own live view behind a public HTTPS URL (cloudflared quick tunnel), so someone elsewhere can watch it and act in it — from a phone if they like. Container mode only: a `builder` browser already returns a hosted `liveViewUrl`, and a plain local browser has no view to share |
@@ -110,8 +110,8 @@ These capture/synthesis/proof tools are backend-independent and registered in bo
 The MCP server targets one of two backends, selected by `USE_OLD_DEVTOOLS`:
 
 - **Old devtools (default).** The legacy devtools backend is still in production while the new "builder" backend is built, so this is the default — opt into builder with `USE_OLD_DEVTOOLS=false`. In old mode all auto-generated HTTP-API tools are disabled and a small client (`src/old/`) serves:
-  - `reclaim_authenticate` — by default opens the dashboard in Chrome via CDP, waits for sign-in, reads the Firebase token from page storage, and closes the tab (or pass a `token` / `ethAddress` to skip the browser).
-  - `create_provider_version_from_capture` — registers a new provider, or adds a version to an existing one when given a `providerId`.
+  - `reclaim_authenticate` — by default opens the dashboard in local Chrome over loopback CDP, waits for sign-in, reads the Firebase token from page storage, and closes the tab. It never uses a remote or shared authoring browser. Pass a `token` / `ethAddress` to skip the browser.
+  - `create_provider_version_from_capture` — registers a new provider, or adds a new immutable semantic version when given a `providerId`. It never edits an existing version.
   - `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.

package/lib/authoring/tools.js

@@ -129,7 +129,8 @@ export function authoringTools(resolveBackend) {
         defineTool({
             name: 'test_user_script',
             description: 'Dry-run a USER SCRIPT (the `jsUserScripts` / `customInjection` '
-                + 'field) in the LIVE attached tab, BEFORE publishing. Installs '
+                + '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 '

package/lib/consts.d.ts

@@ -15,7 +15,7 @@
  *
  * Each var's default/fallback literal is co-located with its getter.
  */
-import { DEFAULT_BASE_URL } from '@reclaimprotocol/client';
+import { DEFAULT_BASE_URL } from '@reclaimprotocol/client/api';
 import { DEFAULT_OLD_API_URL, DEFAULT_OLD_LOGS_URL } from './old/client.ts';
 import { DEFAULT_SDK_API_URL } from './old/sdk-client.ts';
 /** Public attestor websocket URL — fallback for `RECLAIM_ATTESTOR_URL`. */

package/lib/consts.js

@@ -15,7 +15,7 @@
  *
  * Each var's default/fallback literal is co-located with its getter.
  */
-import { DEFAULT_BASE_URL } from '@reclaimprotocol/client';
+import { DEFAULT_BASE_URL } from '@reclaimprotocol/client/api';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { DEFAULT_OLD_API_URL, DEFAULT_OLD_LOGS_URL } from "./old/client.js";

package/lib/live/tunnel.d.ts

@@ -2,13 +2,10 @@ import { type CloudflaredBinary } from './cloudflared.ts';
 export interface Tunnel {
     /** The public HTTPS origin Cloudflare assigned. */
     url: string;
-    /** Whether the tunnel was carrying traffic before {@link READY_TIMEOUT_MS}
-     *  elapsed. False means it may still be propagating rather than broken — say
-     *  so rather than treating the share as failed. */
+    /** Whether the public viewer answered during the initial readiness probe. */
     ready: boolean;
-    /** cloudflared's own last words, for when `ready` is false and someone has
-     *  to work out why. Absent when the tunnel came up normally. */
-    diagnostics?: string;
+    /** Bounded cloudflared output when the edge is still propagating. */
+    cloudflaredLog?: string;
     /** Terminate the tunnel. Safe to call more than once. */
     stop: () => Promise<void>;
     /** Which cloudflared ran, and whether we had to fetch it. */
@@ -21,6 +18,12 @@ export interface Tunnel {
  * Rejects with an actionable message when `cloudflared` is not installed,
  * exits early, or never reports a hostname.
  */
-export declare function startTunnel(port: number, { autoInstall }?: {
+export declare function startTunnel(port: number, { autoInstall, probePath, readyPollMs, readyTimeoutMs, }?: {
     autoInstall?: boolean;
+    /** Public path that must answer before the tunnel is returned. */
+    probePath?: string;
+    /** Test-only timing override. */
+    readyPollMs?: number;
+    /** Test-only timing override. */
+    readyTimeoutMs?: number;
 }): Promise<Tunnel>;

package/lib/live/tunnel.js

@@ -23,58 +23,44 @@ import { LOGGER } from "../logger.js";
 import { resolveCloudflared } from "./cloudflared.js";
 /** How long to wait for cloudflared to report its hostname before giving up. */
 const URL_TIMEOUT_MS = 30000;
-/** After the hostname is printed, Cloudflare needs a moment before the edge
- *  routes to it — measured at ~3s. Wait for it so the caller never hands out a
- *  URL that errors, but don't fail the share if it's slow. */
+/** After the hostname is printed, Cloudflare needs time before the edge routes
+ *  to it. Probe briefly, then return the still-running tunnel as propagating so
+ *  slow DNS or edge setup does not destroy an otherwise healthy share. */
 const READY_TIMEOUT_MS = 20000;
 const READY_POLL_MS = 1000;
+const STOP_TIMEOUT_MS = 5000;
 /** `https://<something>.trycloudflare.com`, as printed on cloudflared's log
  *  stream. Anchored to the scheme so a hostname inside prose can't match. */
 const QUICK_TUNNEL_URL = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i;
-/**
- * cloudflared says this once per edge connection it establishes, and until it
- * does, the hostname resolves but routes nowhere.
- *
- * This is the signal to trust, because it is LOCAL. Asking whether we can fetch
- * the public URL ourselves conflates two questions — is the tunnel up, and does
- * this machine have egress to Cloudflare's edge — and reports "not ready" when
- * only the second fails. Observed: a tunnel printed its hostname and registered
- * nothing for 12s, which is indistinguishable from a blocked fetch unless you
- * read cloudflared's own account of it.
- */
-const REGISTERED = /Registered tunnel connection|connIndex=/i;
 /** Tail of cloudflared's log kept for error messages. */
 const LOG_TAIL_BYTES = 4096;
 /**
  * Wait until the tunnel is actually carrying traffic.
  *
- * Two independent signals, either of which is proof:
- *  - cloudflared reported an edge registration (see {@link REGISTERED}). Local,
- *    so it works regardless of this machine's own egress.
- *  - the public origin answered. ANY HTTP response counts, including a 404:
- *    the live-view server 404s unknown paths, so a status code at all proves
- *    the hop is live. Kept as a second opinion in case a cloudflared release
- *    rewords its log.
+ * A cloudflared "Registered tunnel connection" log is not enough: Cloudflare
+ * can report one while the assigned hostname still returns DNS NXDOMAIN. The
+ * public viewer itself must return a successful response.
  */
-async function waitUntilRouted(url, isRegistered) {
-    const deadline = Date.now() + READY_TIMEOUT_MS;
+async function waitUntilRouted(url, { isRunning, pollMs, timeoutMs, }) {
+    const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        if (isRegistered()) {
-            return true;
+        if (!isRunning()) {
+            return false;
         }
         try {
-            await fetch(url, {
+            const response = await fetch(url, {
                 method: 'GET',
                 redirect: 'manual',
-                signal: AbortSignal.timeout(READY_POLL_MS * 2),
+                signal: AbortSignal.timeout(pollMs * 2),
             });
-            return true;
-        }
-        catch {
-            await new Promise((r) => setTimeout(r, READY_POLL_MS));
+            if (response.ok) {
+                return true;
+            }
         }
+        catch { }
+        await new Promise((r) => setTimeout(r, pollMs));
     }
-    return isRegistered();
+    return false;
 }
 /**
  * Open a quick tunnel to `http://127.0.0.1:<port>` and resolve once
@@ -83,7 +69,7 @@ async function waitUntilRouted(url, isRegistered) {
  * Rejects with an actionable message when `cloudflared` is not installed,
  * exits early, or never reports a hostname.
  */
-export async function startTunnel(port, { autoInstall = true } = {}) {
+export async function startTunnel(port, { autoInstall = true, probePath = '/', readyPollMs = READY_POLL_MS, readyTimeoutMs = READY_TIMEOUT_MS, } = {}) {
     // Resolves an existing cloudflared, or fetches one on first use. Throws
     // with an actionable message when neither is possible.
     const binary = await resolveCloudflared({ autoInstall });
@@ -92,20 +78,12 @@ export async function startTunnel(port, { autoInstall = true } = {}) {
         '--no-autoupdate',
         '--url', `http://127.0.0.1:${port}`,
     ], { stdio: ['ignore', 'pipe', 'pipe'] });
-    const stop = async () => {
-        if (!child.killed) {
-            child.kill('SIGTERM');
-        }
-    };
+    const exited = new Promise((resolve) => {
+        child.once('exit', () => resolve());
+    });
+    let stopPromise;
+    const stop = () => stopPromise ?? (stopPromise = stopChild());
     return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
-            void stop();
-            reject(new Error('cloudflared did not report a tunnel hostname within '
-                + `${URL_TIMEOUT_MS / 1000}s. Check network egress to Cloudflare, `
-                + 'or run `cloudflared tunnel --url http://127.0.0.1:'
-                + `${port}` + '` by hand to see its output.'));
-        }, URL_TIMEOUT_MS);
-        let registered = false;
         let tail = '';
         let settled = false;
         const finish = (fn) => {
@@ -116,27 +94,51 @@ export async function startTunnel(port, { autoInstall = true } = {}) {
             clearTimeout(timer);
             fn();
         };
+        const timer = setTimeout(() => {
+            finish(() => {
+                void stop().then(() => reject(new Error('cloudflared did not report a tunnel hostname within '
+                    + `${URL_TIMEOUT_MS / 1000}s. Check network egress to `
+                    + 'Cloudflare, or run `cloudflared tunnel --url '
+                    + `http://127.0.0.1:${port}` + '` by hand to see its output.')));
+            });
+        }, URL_TIMEOUT_MS);
         // cloudflared logs the assigned hostname to stderr, not stdout. Watch
         // both so a future version that switches streams still works.
         const onChunk = (chunk) => {
             const text = chunk.toString();
-            // Keep watching after the hostname: registration lands a beat later, and
-            // on a bad run it never lands at all, which is the case worth reporting.
+            // Keep watching after the hostname so a readiness failure can include
+            // cloudflared's account of what happened.
             tail = (tail + text).slice(-LOG_TAIL_BYTES);
-            if (REGISTERED.test(text)) {
-                registered = true;
-            }
-            const match = QUICK_TUNNEL_URL.exec(text);
+            // Search the accumulated tail so a URL split across stream chunks is not
+            // missed. The tail is bounded and the URL appears near startup.
+            const match = QUICK_TUNNEL_URL.exec(tail);
             if (match) {
                 const url = match[0];
                 finish(() => {
-                    void waitUntilRouted(url, () => registered).then((ready) => {
+                    const probeUrl = new URL(probePath, `${url}/`).toString();
+                    void waitUntilRouted(probeUrl, {
+                        isRunning: () => child.exitCode === null
+                            && child.signalCode === null,
+                        pollMs: readyPollMs,
+                        timeoutMs: readyTimeoutMs,
+                    }).then((ready) => {
                         if (ready) {
                             resolve({ url, ready, stop, binary });
                             return;
                         }
-                        LOGGER.warn({ url, tail }, 'tunnel never registered with an edge; returning anyway');
-                        resolve({ url, ready, stop, binary, diagnostics: tail });
+                        if (child.exitCode !== null || child.signalCode !== null) {
+                            reject(new Error('cloudflared exited before the public viewer became reachable. '
+                                + 'cloudflared output:\n' + tail));
+                            return;
+                        }
+                        LOGGER.warn({ url, tail }, 'tunnel still propagating; returning the live hostname');
+                        resolve({
+                            url,
+                            ready,
+                            cloudflaredLog: tail,
+                            stop,
+                            binary,
+                        });
                     });
                 });
             }
@@ -157,4 +159,24 @@ export async function startTunnel(port, { autoInstall = true } = {}) {
                 + 'hostname.')));
         });
     });
+    async function stopChild() {
+        if (child.exitCode !== null || child.signalCode !== null) {
+            return;
+        }
+        let timeout;
+        const timedOut = new Promise((resolve) => {
+            timeout = setTimeout(resolve, STOP_TIMEOUT_MS);
+        });
+        child.kill('SIGTERM');
+        await Promise.race([
+            exited,
+            timedOut,
+        ]);
+        clearTimeout(timeout);
+        if (child.exitCode !== null || child.signalCode !== null) {
+            return;
+        }
+        child.kill('SIGKILL');
+        await exited;
+    }
 }

package/lib/mcp/api/operations.gen.d.ts

@@ -19,6 +19,10 @@ export declare const MCP_TOOLS: {
         description: string;
         inputSchema: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
     };
+    BindVerificationSessionTeeNonce: {
+        description: string;
+        inputSchema: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
+    };
     CancelPublicListingRequest: {
         description: string;
         inputSchema: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
@@ -67,10 +71,6 @@ export declare const MCP_TOOLS: {
         description: string;
         inputSchema: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
     };
-    DeleteProviderVersion: {
-        description: string;
-        inputSchema: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
-    };
     DiscoverDataPoints: {
         description: string;
         inputSchema: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
@@ -107,10 +107,18 @@ export declare const MCP_TOOLS: {
         description: string;
         inputSchema: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
     };
+    GetVerificationFunnel: {
+        description: string;
+        inputSchema: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
+    };
     GetVerificationSession: {
         description: string;
         inputSchema: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
     };
+    ImportDevtoolsProvider: {
+        description: string;
+        inputSchema: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
+    };
     IssueOrgToken: {
         description: string;
         inputSchema: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
@@ -195,10 +203,6 @@ export declare const MCP_TOOLS: {
         description: string;
         inputSchema: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
     };
-    UpdateProviderVersion: {
-        description: string;
-        inputSchema: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
-    };
 };
 export type McpToolName = keyof typeof MCP_TOOLS;
 export type McpToolShape = (typeof MCP_TOOLS)[McpToolName];