@reclaimprotocol/agent 0.1.22 → 0.1.24

package/lib/mcp/tools/agent/publish.js

@@ -1,4 +1,4 @@
-import { INJECTION_GUIDE } from "../../../provider/injection-doc.js";
+import { ALLOWED_REQUESTS_HINT, USER_SCRIPT_HINT, } from "../../../provider/injection-doc.js";
 import { countsFor, matchRedactionWarnings, } from "../../../provider/match-redaction-warning.js";
 import { nextVersion, providerToCreateVersionRequest, } from "../../../provider/to-version.js";
 import { defineTool } from "../../server.js";
@@ -62,7 +62,8 @@ const REQUEST_DRAFT_PROPERTIES = {
 const PROVIDER_SCHEMA = {
     type: 'object',
     description: 'A `provider` object from propose_provider, passed through verbatim — ' +
-        'the tool builds the version body (the requests[] entry etc.) for you.',
+        'the tool builds the version body (the requests[] entry and so on) ' +
+        'for you.',
     properties: {
         name: { type: 'string', description: 'Verification name.' },
         ...REQUEST_DRAFT_PROPERTIES,
@@ -73,7 +74,7 @@ const PROVIDER_SCHEMA = {
         },
         paramValues: {
             type: 'object',
-            description: 'Real values for the {{param}} placeholders, e.g. ' +
+            description: 'Real values for the {{param}} placeholders, for example, ' +
                 '{ "username": "Syed" }.',
         },
     },
@@ -87,8 +88,8 @@ const ALLOWED_JS_REQUEST_SCHEMA = {
         ...REQUEST_DRAFT_PROPERTIES,
         multiple: {
             type: 'boolean',
-            description: 'Allow the template to match many requests (e.g. pagination). ' +
-                'Default true.',
+            description: 'Allow the template to match many requests (for example, ' +
+                'pagination). Default true.',
         },
         required: {
             type: 'boolean',
@@ -100,36 +101,21 @@ const ALLOWED_JS_REQUEST_SCHEMA = {
 export function createVersionFromCaptureTool(client, attachRef) {
     return defineTool({
         name: 'create_provider_version_from_capture',
-        description: 'Persist drafted ReclaimProvider(s) as a provider version. ' +
-            'Call this after run_proof succeeds, passing the `provider` ' +
-            'object(s) from propose_provider VERBATIM. This tool builds the ' +
-            'body (the requests[] array, webSettings, etc.) for you — do NOT ' +
-            'hand-construct that shape or call create_provider_version directly. ' +
-            'For a MULTI-REQUEST provider, pass `providers: [...]` (each entry a ' +
-            'proven draft) — every entry becomes one request in the version, and ' +
-            'all are required at verification time. Pass a single `provider` ' +
-            'for the one-request case (exactly one of `provider`/`providers`). ' +
-            'For data gated behind login/navigation, supply `jsUserScripts` (a ' +
-            'page-injection script that drives the page to where the request ' +
-            'fires) and/or `allowedJsRequests` (extra requests the script may ' +
-            'fire, e.g. pagination). ' +
-            'Omit `version` to have the tool auto-select the next available ' +
-            'version (it lists existing versions and bumps past the highest). ' +
-            'The version lands on the draft branch — to go live, call ' +
-            '`publish_provider_version` (PRIVATE) or ' +
-            '`submit_provider_version_for_review` (PUBLIC) afterwards. ' +
+        description: 'Persist drafted ReclaimProvider(s) as a provider version, after ' +
+            'run_proof succeeds. Pass the `provider` object(s) from ' +
+            'propose_provider VERBATIM — this tool builds the version body ' +
+            '(requests[], webSettings, …) for you; do NOT hand-construct that ' +
+            'shape or call create_provider_version directly. Exactly one of ' +
+            '`provider` (one request) or `providers` (a multi-request provider — ' +
+            'every entry is required at verification time). Omit `version` to ' +
+            'auto-bump past the highest existing one. The version lands on the ' +
+            'draft branch: call `publish_provider_version` (PRIVATE) or ' +
+            '`submit_provider_version_for_review` (PUBLIC) to go live. ' +
             '`requiredContext` is derived from any {{context.<name>}} ' +
-            'placeholders across ALL requests (plus injected requests / script) ' +
-            'and returned on the created version — when present, tell the dev ' +
-            'verbatim which context fields consumers MUST send when creating ' +
-            'sessions (verification matches those values exactly; a missing ' +
-            'field is a 400 at session create). ' +
-            'Refine types/descriptions via `update_provider_version` while ' +
-            'still on draft. ' +
-            'On success, if a browser is still attached, the response\'s ' +
-            '`_notes` reminds you to confirm with the developer before ' +
-            'calling `dispose_browser` — never close it unprompted, they ' +
-            'may want it for further edits.',
+            'placeholders and returned on the created version — relay it to the ' +
+            'dev verbatim, since a session missing those fields is a 400. Always ' +
+            'read the response\'s `_notes`. ' +
+            'Full walkthrough: how_it_works({ topic: "publish" }).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -149,12 +135,14 @@ export function createVersionFromCaptureTool(client, attachRef) {
                 initialUrl: {
                     type: 'string',
                     description: 'The website URL the user landed on to trigger the request ' +
-                        '(e.g. https://github.com/Syed). The URL the verification ' +
-                        'flow opens for end-users — NOT the API URL inside the provider.',
+                        '(for example, https://github.com/Syed). The URL the ' +
+                        'verification flow opens for end-users — NOT the API URL ' +
+                        'inside the provider.',
                 },
                 notes: {
                     type: 'string',
-                    description: 'Short change note (e.g. "Initial draft from browser capture").',
+                    description: 'Short change note (for example, "Initial draft from ' +
+                        'browser capture").',
                 },
                 version: {
                     type: 'object',
@@ -169,64 +157,48 @@ export function createVersionFromCaptureTool(client, attachRef) {
                 },
                 jsUserScripts: {
                     type: 'string',
-                    description: 'Plain JavaScript injected into the provider page before every ' +
-                        'page load (stored as webSettings.jsUserScripts). Use standard ' +
-                        'browser APIs (window.location, element.click(), forms) to ' +
-                        'drive login/navigation so the target request fires — the ' +
-                        'client already intercepts page requests, and window.Reclaim ' +
-                        'is only for rare edge cases, not navigation. The Builder ' +
-                        'verification client installs this to run before every page ' +
-                        'load (before navigating to initialUrl), matching old-devtool ' +
-                        'customInjection; window.Reclaim itself is not yet exposed ' +
-                        'there, so prefer plain browser JS. Guide:\n\n' +
-                        INJECTION_GUIDE,
+                    description: USER_SCRIPT_HINT +
+                        ' Stored as webSettings.jsUserScripts; the Builder ' +
+                        'verification client runs it before every page load ' +
+                        '(including before navigating to initialUrl), matching ' +
+                        'old-devtools customInjection. window.Reclaim is not exposed ' +
+                        'there yet, so prefer plain browser JS.',
                 },
                 allowedJsRequests: {
                     type: 'array',
-                    description: 'Extra requests the injection script is allowed to fire ' +
-                        '(e.g. paginated API calls), as RequestSelectionTemplates. ' +
-                        '`multiple`/`required` default to true. ' +
-                        '⚠️ BEFORE populating this to gate ' +
-                        '`verifyProof(proof, { providerId })` (old-devtools calls the ' +
-                        'same concept `allowedInjectedRequestData` — same mechanics, ' +
-                        'different field name): this whole entry (url, method, body, ' +
-                        'responseMatches, responseRedactions) feeds a client-side ' +
-                        'hash-equality check, and `url` is hashed VERBATIM — no regex/ ' +
-                        'template resolution, even with `urlType: REGEX` or ' +
-                        '`TEMPLATE`. If the real captured URL contains ANY per-session ' +
-                        'part (a tracking nonce, CSRF token, cache-busting timestamp), ' +
-                        'no declared spec can EVER hash-match a real proof — populating' +
-                        ' this for such a provider makes verifyProof reject every real ' +
-                        'proof, which is worse than leaving it empty. Diff the same ' +
-                        'endpoint\'s captured URL across two separate sessions before ' +
-                        'wiring this up. If provider-hash validation keeps causing ' +
-                        'problems (unstable url, or any other persistent mismatch), ' +
-                        'the fallback on the verifying side is `verifyProof(proof, { ' +
-                        'dangerouslyDisableContentValidation: true })` — trusts only ' +
-                        'the attestor\'s signature, skips the hash-equality check ' +
-                        'entirely; see the "Provider-hash validation" section of the ' +
-                        'injection script\'s guide for the full mechanics and when to ' +
-                        'reach for it.',
+                    description: 'Extra requests the user script is allowed to fire (for ' +
+                        'example, paginated API calls), as ' +
+                        'RequestSelectionTemplates. ' +
+                        '`multiple`/`required` default to true. Old-devtools calls the ' +
+                        'same concept `allowedInjectedRequestData`. ' +
+                        ALLOWED_REQUESTS_HINT,
                     items: ALLOWED_JS_REQUEST_SCHEMA,
                 },
                 interceptorOptions: {
                     type: 'object',
                     description: 'In-app interception settings, stored as ' +
-                        'webSettings.clientOptions.inapp.interceptorOptions. ' +
-                        '`isDocumentRequestReplayEnabled` is the INVERSE of ' +
-                        'old-devtools\' `disableRequestReplay`: true replays the ' +
-                        'main document request via the attestor (default false).',
+                        'webSettings.clientOptions.inapp.interceptorOptions — only ' +
+                        'needed for a genuine live-interception provider (a real ' +
+                        'HAWKEYE/MSWJS script, not the standard capture→replay flow).',
                     properties: {
                         interceptorType: {
                             type: 'string',
                             enum: ['HAWKEYE', 'MSWJS', 'CDP'],
                             description: 'How traffic interception is implemented.',
                         },
-                        isDocumentRequestReplayEnabled: { type: 'boolean' },
                         interceptorSettings: {
                             type: 'string',
                             description: 'Free-form JSON config for the chosen interceptor.',
                         },
+                        isDocumentRequestReplayEnabled: {
+                            type: 'boolean',
+                            description: 'Whether the page\'s own document/navigation request is ' +
+                                'genuinely replayed through the interceptor, rather than ' +
+                                'constructed locally. Defaults to `false` (disabled) when ' +
+                                'omitted. Only meaningful for HAWKEYE/MSWJS — pass `true` ' +
+                                'when the target value is embedded in the page\'s own HTML ' +
+                                'rather than a separate API call. Inert for CDP.',
+                        },
                     },
                     required: ['interceptorType'],
                 },

package/lib/mcp/tools/agent/session.d.ts

@@ -2,7 +2,8 @@ import type { ConfigStore } from '../../../config/store.ts';
 import { type RegisteredTool } from '../../server.ts';
 import { type AttachState } from './attach.ts';
 import { type CaptureStore } from './capture.ts';
+import { type LiveShareRef } from './live-view.ts';
 export declare function sessionTools(attachRef: {
     current?: AttachState;
     config: ConfigStore;
-}, captures: CaptureStore): RegisteredTool[];
+}, captures: CaptureStore, liveShare: LiveShareRef): RegisteredTool[];

package/lib/mcp/tools/agent/session.js

@@ -1,11 +1,14 @@
 import { defineTool } from "../../server.js";
 import { disposeAttached } from "./attach.js";
 import { resetCaptures } from "./capture.js";
-export function sessionTools(attachRef, captures) {
+import { stopLiveShare } from "./live-view.js";
+export function sessionTools(attachRef, captures, liveShare) {
     return [
         defineTool({
             name: 'get_session',
-            description: 'Return current attach state, active captures, and persisted config.',
+            description: 'Report the current attach state, the live captureIds, and the '
+                + 'persisted browser config. Call it to check whether a browser is '
+                + 'still attached before reattaching, or to recover a captureId.',
             inputSchema: { type: 'object', properties: {} },
         }, async () => ({
             config: attachRef.config.read()?.browser_agent,
@@ -17,29 +20,45 @@ export function sessionTools(attachRef, captures) {
             orgId: attachRef.current?.orgId,
             captures: [...captures.sessions.keys()],
             activeTab: captures.activeTab,
+            // The public share, when one is open — so a caller that lost the
+            // URL can recover it instead of opening a second tunnel.
+            ...(liveShare.current
+                ? {
+                    sharedView: {
+                        url: liveShare.current.url,
+                        interactive: liveShare.current.interactive,
+                        viewers: liveShare.current.view.viewers(),
+                    },
+                }
+                : {}),
         })),
         defineTool({
             name: 'dispose_browser',
             description: 'Stop captures, disconnect the current browser, and immediately '
                 + 'delete a Builder-hosted Popcorn session. Custom CDP sessions '
-                + 'are disconnected but never deleted by Reclaim.',
+                + 'are disconnected but never deleted by Reclaim. Also closes a '
+                + 'public live view opened by share_browser_view.',
             inputSchema: { type: 'object', properties: {} },
         }, async () => {
-            await resetAll(attachRef, captures);
+            await resetAll(attachRef, captures, liveShare);
             return { disposed: true };
         }),
         defineTool({
             name: 'reset_session',
             description: 'Stop all captures and clear capture state — drops every '
-                + 'session\'s drafts and their in-memory secrets.',
+                + 'session\'s drafts and their in-memory secrets, and closes a '
+                + 'public live view opened by share_browser_view.',
             inputSchema: { type: 'object', properties: {} },
         }, async () => {
-            await resetAll(attachRef, captures);
+            await resetAll(attachRef, captures, liveShare);
             return { reset: true };
         }),
     ];
 }
-async function resetAll(attachRef, captures) {
+async function resetAll(attachRef, captures, liveShare) {
+    // Before the captures: the live view holds a tab session of its own, and a
+    // public URL must never outlive the browser it points at.
+    await stopLiveShare(liveShare);
     await resetCaptures(captures);
     await disposeAttached(attachRef);
 }

package/lib/mcp/tools/agent/shared.js

@@ -9,7 +9,7 @@
  */
 import { authoringTools, extendTool, } from "../../../authoring/index.js";
 import { runAttestorProof } from "../../../proof/attestor.js";
-import { replayProvider } from "../../../proof/replay.js";
+import { replayProviderInPage } from "../../../proof/page-replay.js";
 import { shapeRichProofResult } from "./proof.js";
 /**
  * OPRF mode this LOCAL (non-TEE) attestor can actually run. Recipes carry
@@ -39,13 +39,17 @@ function withLocalOprfMode(provider) {
     };
 }
 /** The local backend for one capture: drive its tab over CDP, read its
- *  captured requests, prove via the in-process attestor, replay by re-fetch. */
+ *  captured requests, prove via the in-process attestor, replay by re-fetching
+ *  FROM INSIDE the tab (real cookies/session — see proof/page-replay.ts). */
 function localBackend(entry) {
     const { tabClient, session, drafts } = entry;
+    const sendCdp = (method, params) => {
+        return tabClient.send(method, params ?? {});
+    };
     return {
         capture: session,
         drafts,
-        sendCdp: (method, params) => tabClient.send(method, params ?? {}),
+        sendCdp,
         waitForEvent: (method, timeoutMs) => new Promise((resolve) => {
             let stopListening = () => { };
             const onEvent = () => {
@@ -63,10 +67,9 @@ function localBackend(entry) {
             stopListening = tabClient.subscribeOnce(method, onEvent);
         }),
         replay: async (draft, opts) => {
-            // Auth-bound check: re-fetch with the secrets dropped. replayProvider
-            // already does a live Node fetch, so empty secrets == anonymous.
-            const secrets = opts?.withoutSecrets ? {} : draft.secrets;
-            const result = await replayProvider(draft.provider, secrets);
+            // Replayed FROM INSIDE the attached tab (real cookies/session), not
+            // a detached Node fetch — see proof/page-replay.ts.
+            const result = await replayProviderInPage({ sendCdp }, draft.provider, draft.secrets, opts);
             return {
                 status: result.status,
                 matchesOriginal: result.matchesOriginal,
@@ -105,7 +108,13 @@ const RUN_PROOF_EXTRAS = {
         + 'specific alternative — do NOT invent backup URLs. `ownerAddress` '
         + '(the credential to sign with) is REQUIRED — call resolve_owner_key '
         + 'first. errorKind="missing-owner-key" means that address has no known '
-        + 'private key; re-run resolve_owner_key or issue/import a credential.',
+        + 'private key; re-run resolve_owner_key or issue/import a credential. '
+        + '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.',
     properties: {
         ownerAddress: {
             type: 'string',

package/lib/mcp/tools/authenticate/authenticate.d.ts

@@ -1,3 +1,14 @@
 import type { ReclaimClient } from '@reclaimprotocol/client';
 import { type RegisteredTool } from '../../server.ts';
 export declare function authenticateTool(client: ReclaimClient, name?: 'reclaim_authenticate' | 'authenticate_builder'): RegisteredTool;
+/**
+ * Standard OAuth 2.0 Authorization Code + PKCE, native-app style (RFC 8252):
+ * dynamically register a public client (RFC 7591 — Better Auth's
+ * `oauth-provider` plugin issues no secret for it), send the user to the
+ * browser, and catch the redirect on a loopback server. `openid-client`
+ * handles PKCE, `state` CSRF protection, and authorization-response
+ * validation (including a denied/failed login surfacing as
+ * `AuthorizationResponseError`) — this function only wires those calls
+ * together and owns the loopback server (no library spins that up for you).
+ */
+export declare function runOAuthLoopback(client: ReclaimClient, openBrowserFn?: (url: string) => void): Promise<unknown>;