@reclaimprotocol/agent 0.1.25 → 0.1.27

package/README.md

@@ -113,6 +113,8 @@ The MCP server targets one of two backends, selected by `USE_OLD_DEVTOOLS`:
   - `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`.
   - `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 (`USE_OLD_DEVTOOLS=false`).** Registers the auto-generated HTTP-API tools plus the authentication/credential tools (`authenticate` device-pairing login, `issue_credentials` / `import_credentials` to set up the local eth proof-owner key, `resolve_owner_key`) and a verification-result helper (`get_verification_result`).
 
 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/live/tunnel.d.ts

@@ -2,13 +2,6 @@ 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. */
-    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;
     /** Terminate the tunnel. Safe to call more than once. */
     stop: () => Promise<void>;
     /** Which cloudflared ran, and whether we had to fetch it. */
@@ -21,6 +14,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

@@ -25,56 +25,42 @@ import { resolveCloudflared } from "./cloudflared.js";
 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. */
+ *  URL that errors. */
 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,42 @@ 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);
             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(async (ready) => {
                         if (ready) {
-                            resolve({ url, ready, stop, binary });
+                            resolve({ url, stop, binary });
                             return;
                         }
-                        LOGGER.warn({ url, tail }, 'tunnel never registered with an edge; returning anyway');
-                        resolve({ url, ready, stop, binary, diagnostics: tail });
+                        await stop();
+                        LOGGER.warn({ url, tail }, 'tunnel public URL never became reachable');
+                        reject(new Error('cloudflared created a hostname, but the public viewer did '
+                            + `not become reachable within ${readyTimeoutMs / 1000}s. `
+                            + 'Retry share_browser_view. cloudflared output:\n'
+                            + tail));
                     });
                 });
             }
@@ -157,4 +150,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

@@ -111,6 +111,10 @@ export declare const MCP_TOOLS: {
         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>>;

package/lib/mcp/api/operations.gen.js

@@ -1812,6 +1812,46 @@ export const MCP_TOOLS = {
             "additionalProperties": false
         }),
     },
+    "ImportDevtoolsProvider": {
+        description: "Import a provider from devtools\n\nImport the latest version of a public provider from the legacy devtools\nservice. Use this when moving an existing provider to Builder instead\nof recreating it.\n\nThe import preserves the legacy provider UUID. The server reads the\ncurrent configuration from\n`https://api.reclaimprotocol.org/api/providers/{providerId}` and\ntranslates it to the Builder schema.\n\nIf the provider already exists in the seeded anonymous catalog, the\nimport assigns that record to the target organization and adds the\nimported version idempotently. A provider owned by another Builder\norganization returns `409`.\n",
+        inputSchema: toZod({
+            "type": "object",
+            "properties": {
+                "params": {
+                    "type": "object",
+                    "properties": {}
+                },
+                "query": {
+                    "type": "object",
+                    "properties": {}
+                },
+                "body": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                        "orgId",
+                        "providerId"
+                    ],
+                    "properties": {
+                        "orgId": {
+                            "type": "string",
+                            "format": "uuid"
+                        },
+                        "providerId": {
+                            "type": "string",
+                            "format": "uuid"
+                        }
+                    }
+                }
+            },
+            "required": [
+                "params",
+                "query",
+                "body"
+            ],
+            "additionalProperties": false
+        }),
+    },
     "IssueOrgToken": {
         description: "Issue a new organization API key\n\nIssues a fresh per-organization API key (`rorg_…`). The caller must be an active **OWNER** of the organization. An org may hold several keys; issuing a new one does **not** invalidate existing keys (revoke those explicitly). The plaintext key is returned **only once** in this response (the server stores only its HMAC); treat it like a password.",
         inputSchema: toZod({

package/lib/mcp/instructions.js

@@ -61,6 +61,8 @@ const SHARED_TOPIC_FILES = {
 const TOPIC_SUMMARIES = {
     'overview': 'Terminology, your stance, and the whole loop at a glance.',
     'auth': 'Signing in to the backend, and which token authorizes what.',
+    'devtools-migration': 'Importing a public legacy provider with the same '
+        + 'UUID.',
     'browser': 'Choosing a browser source (local Chrome, the Reclaim runtime in '
         + 'Docker, a remote Popcorn browser, or a custom CDP endpoint), '
         + 'geolocation, live view, and launch troubleshooting.',

package/lib/mcp/tools/agent/live-view.js

@@ -83,7 +83,9 @@ export function liveViewTools(attachRef, shareRef) {
             const viewerPort = attached.viewerPort;
             assert(viewerPort, badRequest('This browser reports no live-view port. Re-attach with mode '
                 + '"container".'));
-            const tunnel = await startTunnel(viewerPort);
+            const tunnel = await startTunnel(viewerPort, {
+                probePath: '/liveview.html?magnify=1',
+            });
             // The path is the runtime's own viewer page; `magnify=1` is what makes
             // it lay out for the device that opens it.
             const url = `${tunnel.url}/liveview.html?magnify=1`;
@@ -97,30 +99,11 @@ export function liveViewTools(attachRef, shareRef) {
                 ...(share.tunnel.binary.source === 'downloaded'
                     ? { cloudflaredInstalled: true }
                     : {}),
-                ...(share.tunnel.ready
-                    ? {}
-                    : {
-                        propagating: true,
-                        // cloudflared's own last words. Without them, "the URL does
-                        // not connect" is unactionable: the tunnel, the local server
-                        // and this machine's egress all look identical from outside.
-                        ...(share.tunnel.diagnostics
-                            ? { cloudflaredLog: share.tunnel.diagnostics }
-                            : {}),
-                    }),
                 _notes: [
                     ...(share.tunnel.binary.source === 'downloaded'
                         ? ['cloudflared was not installed, so it was downloaded once '
                                 + 'to ~/.reclaim/bin. Mention that; later shares reuse it.']
                         : []),
-                    ...(share.tunnel.ready
-                        ? []
-                        : ['The tunnel never confirmed a connection to Cloudflare, so '
-                                + 'the URL may not resolve yet. Give it ~10s and reload '
-                                + 'first. If it still fails, say so and offer to retry '
-                                + '(stop_browser_view then share_browser_view) — a quick '
-                                + 'tunnel does sometimes fail to register. '
-                                + '`cloudflaredLog` has its output if it keeps happening.']),
                     'Relay `url` to the developer verbatim, on its own line.',
                     'The URL is a credential: it needs no login, and anyone with it '
                         + 'can see this browser and act in it as the signed-in user.',

package/lib/old/client.d.ts

@@ -94,6 +94,70 @@ export interface LinkNonce {
     nonce: string;
     expiresInSeconds: number;
 }
+/** Log-level filter accepted by the devtools backend's session-logs route.
+ *  It validates against this exact list and rejects anything else with a 400,
+ *  including the comma-separated lists the log-stream service itself would
+ *  accept. Each value is hierarchical at the log-stream end: `fine` means
+ *  FINE+CONFIG+INFO+WARNING+SEVERE, `info` means INFO+WARNING+SEVERE, and so
+ *  on. `finer`/`finest` (the PII tiers) are not reachable through this route
+ *  at all. */
+export type SessionLogLevel = 'fine' | 'config' | 'info' | 'warning' | 'severe' | 'unknown';
+/** Filters for {@link ReclaimOldClient.getSessionLogs}. Every one is optional
+ *  and forwarded verbatim; the session id itself is the route's path param, so
+ *  `providerId`/`deviceId` narrow WITHIN one session rather than searching
+ *  across sessions. */
+export interface SessionLogsQuery {
+    deviceId?: string;
+    source?: string;
+    /** The client-side logger NAME (log-stream's `log_type` column, the SDK's
+     *  `LogEntry.type`) — not the event type. */
+    logType?: string;
+    logLevel?: SessionLogLevel;
+    providerId?: string;
+    /** ISO-8601. Omitting BOTH bounds makes the log-stream service default to
+     *  the last 3 days. */
+    startTime?: string;
+    endTime?: string;
+    /** Substring match against the log line (`LIKE %…%`). */
+    logLine?: string;
+    /** Exact `LogEventType` name, for example `REQUEST_MATCHED`. */
+    eventType?: string;
+    /** Capped at 1000 by the log-stream service. */
+    limit?: number;
+    offset?: number;
+    includeCount?: boolean;
+}
+/** One raw log line, in the log-stream service's snake_case ClickHouse shape,
+ *  passed through unchanged by the devtools backend. `event_type` is the SDK's
+ *  `LogEventType` milestone marker (`REQUEST_MATCHED`,
+ *  `CLAIM_CREATION_STARTED`, `PROOF_GENERATED`, …); it is `''` on the majority
+ *  of lines, which carry no event. */
+export interface SessionLogRow {
+    timestamp: string;
+    request_id: string;
+    session_id: string;
+    device_id: string;
+    source: string;
+    app_id: string;
+    provider_id: string;
+    log_type: string;
+    log_level: string;
+    log_line: string;
+    event_type?: string;
+    metadata?: string;
+}
+/** `GET /api/logger/:sessionId`'s `data` envelope. The backend queries every
+ *  region that holds the session, concatenates the pages, sorts them
+ *  newest-first and re-slices to `limit`, so `data` is one page and
+ *  `totalCount` is the match count across all of them. */
+export interface SessionLogsPage {
+    data: SessionLogRow[];
+    count: number;
+    totalCount?: number;
+    /** Regions whose log-stream query failed — the page is INCOMPLETE when
+     *  this is present. */
+    failedRegions?: string[];
+}
 /**
  * Minimal REST client for the OLD devtools Express backend (base `/api`).
  * Deliberately NOT a clone of `@reclaimprotocol/client`'s operationId
@@ -133,6 +197,25 @@ export declare class ReclaimOldClient {
      *  `#request`). Attaches the caller identity when one is set; queried
      *  anonymously otherwise. */
     getSessionAnalyticsLogs(sessionId: string): Promise<unknown>;
+    /**
+     * Raw log LINES for a verification session — the SDK's own diagnostic
+     * logging, the thing the dashboard's session "logs" tab renders, and a
+     * strictly richer signal than `getSessionAnalyticsLogs`'s milestone events.
+     *
+     * This is the devtools backend (`GET /api/logger/:sessionId`), NOT the
+     * analytics-logs host — hence `#request`, and hence the same identity and
+     * ownership rules as every other authed call here: the session's app must
+     * be one you created (admins excepted), or the route 404s.
+     *
+     * The backend fans the query out to the per-region log-stream services,
+     * which read the ClickHouse `logs` table. Two defaults applied down there
+     * bite hard if you don't override them:
+     *   - no `startTime`/`endTime` → only the last 3 days are searched;
+     *   - no `logLevel` → INFO and above only, so every FINE/CONFIG line is
+     *     invisible.
+     * Entries are dropped entirely after 30 days (table TTL).
+     */
+    getSessionLogs(sessionId: string, query?: SessionLogsQuery): Promise<SessionLogsPage>;
     /** Mint a brand-new, unassociated (sandboxed) app — no auth required. Link
      *  it to an account afterwards with `getLinkNonce` + `linkAppToAccount`, or
      *  use it as-is within the sandbox session limit. */

package/lib/old/client.js

@@ -89,6 +89,52 @@ export class ReclaimOldClient {
         }
         return json;
     }
+    /**
+     * Raw log LINES for a verification session — the SDK's own diagnostic
+     * logging, the thing the dashboard's session "logs" tab renders, and a
+     * strictly richer signal than `getSessionAnalyticsLogs`'s milestone events.
+     *
+     * This is the devtools backend (`GET /api/logger/:sessionId`), NOT the
+     * analytics-logs host — hence `#request`, and hence the same identity and
+     * ownership rules as every other authed call here: the session's app must
+     * be one you created (admins excepted), or the route 404s.
+     *
+     * The backend fans the query out to the per-region log-stream services,
+     * which read the ClickHouse `logs` table. Two defaults applied down there
+     * bite hard if you don't override them:
+     *   - no `startTime`/`endTime` → only the last 3 days are searched;
+     *   - no `logLevel` → INFO and above only, so every FINE/CONFIG line is
+     *     invisible.
+     * Entries are dropped entirely after 30 days (table TTL).
+     */
+    async getSessionLogs(sessionId, query = {}) {
+        const res = await __classPrivateFieldGet(this, _ReclaimOldClient_instances, "m", _ReclaimOldClient_request).call(this, 'GET', `/logger/${encodeURIComponent(sessionId)}`, {
+            auth: true,
+            query: {
+                deviceId: query.deviceId,
+                source: query.source,
+                logType: query.logType,
+                logLevel: query.logLevel,
+                providerId: query.providerId,
+                startTime: query.startTime,
+                endTime: query.endTime,
+                logLine: query.logLine,
+                eventType: query.eventType,
+                limit: query.limit,
+                offset: query.offset,
+                includeCount: query.includeCount === undefined
+                    ? undefined
+                    : String(query.includeCount),
+            },
+        });
+        const page = res.data;
+        return {
+            data: page?.data ?? [],
+            count: page?.count ?? page?.data?.length ?? 0,
+            totalCount: page?.totalCount,
+            failedRegions: page?.failedRegions,
+        };
+    }
     /** Mint a brand-new, unassociated (sandboxed) app — no auth required. Link
      *  it to an account afterwards with `getLinkNonce` + `linkAppToAccount`, or
      *  use it as-is within the sandbox session limit. */

package/lib/old/tools/build.js

@@ -8,6 +8,7 @@ import { getMeProvidersTool } from "./me-providers.js";
 import { createVersionFromCaptureTool } from "./publish.js";
 import { scaffoldDemoServerTool } from "./scaffold-demo-server.js";
 import { sessionAnalyticsLogsTool } from "./session-analytics-logs.js";
+import { sessionLogsTool } from "./session-logs.js";
 import { updateProviderMetadataTool } from "./update-provider-metadata.js";
 import { verifySdkSetupTool } from "./verify-sdk-setup.js";
 /**
@@ -32,6 +33,7 @@ export function buildOldBackendTools(client, sdkClient, attachRef) {
         getProviderInfoTool(sdkClient),
         updateProviderMetadataTool(client),
         sessionAnalyticsLogsTool(client),
+        sessionLogsTool(client),
         issueAppCredentialsTool(client),
         linkAppTool(client),
         checkAppStatusTool(client),

package/lib/old/tools/session-logs.d.ts

@@ -0,0 +1,3 @@
+import { type RegisteredTool } from '../../mcp/server.ts';
+import type { ReclaimOldClient } from '../client.ts';
+export declare function sessionLogsTool(client: ReclaimOldClient): RegisteredTool;