@reclaimprotocol/agent 0.1.23 → 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,44 +157,21 @@ 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: {
@@ -214,11 +179,7 @@ export function createVersionFromCaptureTool(client, attachRef) {
                     description: 'In-app interception settings, stored as ' +
                         'webSettings.clientOptions.inapp.interceptorOptions — only ' +
                         'needed for a genuine live-interception provider (a real ' +
-                        'HAWKEYE/MSWJS script, not the standard capture→replay flow). ' +
-                        'Document replay (webSettings.clientOptions.inapp' +
-                        '.interceptorOptions.isDocumentRequestReplayEnabled) is ' +
-                        'ALWAYS published disabled regardless of this field — there ' +
-                        'is no way to enable it here.',
+                        'HAWKEYE/MSWJS script, not the standard capture→replay flow).',
                     properties: {
                         interceptorType: {
                             type: 'string',
@@ -229,6 +190,15 @@ export function createVersionFromCaptureTool(client, attachRef) {
                             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/authenticate/authenticate.js

@@ -9,17 +9,12 @@ export function authenticateTool(client, name = 'reclaim_authenticate') {
     return defineTool({
         name,
         description: (name === 'authenticate_builder'
-            ? 'This tool only exists in OLD-DEVTOOLS mode — Builder mode has '
-                + 'no separate version of it; its own reclaim_authenticate '
-                + 'already covers everything below. In old-devtools mode, this '
-                + 'authenticates with Builder for exactly two Builder-exclusive '
-                + 'features: allocating a Popcorn remote browser (attach_browser '
-                + 'mode="builder") and listing Builder organizations '
-                + '(list_builder_organizations — old-devtools has no generated '
-                + 'org tool of its own). It does NOT authorize '
-                + 'create_provider_version_from_capture or get_me_providers, '
-                + 'which need their OWN, separate login via the old-devtools '
-                + 'reclaim_authenticate tool. Check both with get_devtools_mode. '
+            ? 'OLD-DEVTOOLS MODE ONLY, and narrow: it authorizes exactly two '
+                + 'Builder-exclusive features — allocating a remote browser '
+                + '(attach_browser mode="builder") and list_builder_organizations. '
+                + 'It does NOT authorize create_provider_version_from_capture or '
+                + 'get_me_providers; those need the separate old-devtools login, '
+                + 'reclaim_authenticate. Check both with get_devtools_mode. '
             : '')
             + 'Authorize the CLI / MCP to make authenticated API calls. Opens '
             + 'the '
@@ -28,8 +23,9 @@ export function authenticateTool(client, name = 'reclaim_authenticate') {
             'the user to sign in and approve. On success the access token is ' +
             'cached in ~/.reclaim/config.json and activated for this session.\n\n' +
             'Call with no arguments. This bearer token authenticates ' +
-            'dashboard/org-management calls (e.g. list_orgs, issuing an org ' +
-            'secret). Programmatic verification calls use a separate org secret ' +
+            'dashboard/org-management calls (for example, list_orgs, or ' +
+            'issuing an org secret). Programmatic verification calls use a ' +
+            'separate org secret ' +
             '(rorg_…, set as RECLAIM_ORG_SECRET).',
         inputSchema: { type: 'object', properties: {} },
     }, async () => runOAuthLoopback(client));
@@ -63,6 +59,16 @@ openBrowserFn = openBrowser) {
     const codeVerifier = oauth.randomPKCECodeVerifier();
     const codeChallenge = await oauth.calculatePKCECodeChallenge(codeVerifier);
     const state = oauth.randomState();
+    // openid-client/oauth4webapi refuse any non-HTTPS issuer by default
+    // ("only requests to HTTPS are allowed"). Better Auth's own dev default
+    // (`canonicalOrigin()`, packages/app/src/consts.ts) is plain
+    // `http://localhost:4001` — the server side has no HTTPS requirement at
+    // all — so a local `RECLAIM_API_URL=http://localhost:...` would otherwise
+    // always fail here. Loosen it ONLY for loopback hosts, matching what the
+    // server already trusts (`authTrustedOrigins()` defaults to
+    // localhost:4000/4001 outside production); a non-loopback http:// origin
+    // still gets the strict check.
+    const isLoopbackAuthBase = ['localhost', '127.0.0.1', '[::1]'].includes(new URL(authBase).hostname);
     // Bind the callback port first: the client is registered for this exact
     // loopback redirect.
     const callback = await listenForCallback();
@@ -93,6 +99,13 @@ openBrowserFn = openBrowser) {
             // `authorizationCodeGrant` fails instead (confirmed by hitting
             // exactly that when this only checked method === 'POST').
             [oauth.customFetch]: _customFetchForOauth,
+            // Applies to the `Configuration` this call returns, so the later
+            // `buildAuthorizationUrl`/`authorizationCodeGrant` calls below (which
+            // reuse that same `config`) stop enforcing HTTPS too — no separate
+            // opt-in needed for them.
+            ...(isLoopbackAuthBase
+                ? { execute: [oauth.allowInsecureRequests] }
+                : {}),
         });
         openBrowserFn(oauth.buildAuthorizationUrl(config, {
             redirect_uri: callback.redirectUri,

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

@@ -7,7 +7,7 @@ import { type RegisteredTool } from '../../server.ts';
  * `~/.reclaim/config.json` and applied the NEXT time the server starts —
  * the registered tool set, server instructions, and backend client are all
  * fixed at connect time, so the switch requires a restart/reconnect. Follows
- * the `attach_chrome` persist-through-config pattern.
+ * the `attach_browser` persist-through-config pattern.
  *
  * Registered in BOTH modes (so the user can switch either direction) and
  * outside `buildAgentTools` (so it survives `RECLAIM_AGENT_DISABLED=1`). An

package/lib/mcp/tools/mode/mode.js

@@ -20,7 +20,7 @@ function hasValidBuilderSession(config) {
  * `~/.reclaim/config.json` and applied the NEXT time the server starts —
  * the registered tool set, server instructions, and backend client are all
  * fixed at connect time, so the switch requires a restart/reconnect. Follows
- * the `attach_chrome` persist-through-config pattern.
+ * the `attach_browser` persist-through-config pattern.
  *
  * Registered in BOTH modes (so the user can switch either direction) and
  * outside `buildAgentTools` (so it survives `RECLAIM_AGENT_DISABLED=1`). An
@@ -61,27 +61,15 @@ export function buildModeTools(config, currentOldMode) {
         }),
         defineTool({
             name: 'get_devtools_mode',
-            description: 'Report which backend this MCP server is currently targeting: '
-                + '"old" (devtools) or "builder" (the builder '
-                + 'backend). Also reports WHY that mode is in effect (source: '
-                + 'a USE_OLD_DEVTOOLS env override, the persisted config, or '
-                + 'the default) and which mode is persisted for the next '
-                + 'start. Use set_devtools_mode to change it. Also reports '
-                + 'AUTH status for BOTH auth systems — builderAuthenticated (the '
-                + 'Builder OAuth login). In BUILDER mode this is the only login '
-                + 'that exists and covers everything, including org listing '
-                + '(list_orgs) and remote-browser allocation. In OLD-DEVTOOLS '
-                + 'mode it is a SEPARATE, additional login (authenticate_builder) '
-                + 'needed only for two Builder-exclusive features: remote-browser '
-                + '(Popcorn) allocation and org listing (list_builder_organizations '
-                + '— old-devtools has no generated org tool of its own). '
-                + 'oldDevtoolsAuthenticated (the OLD-mode reclaim_authenticate) is '
-                + 'required separately for create_provider_version_from_capture '
-                + 'and get_me_providers, and only exists/matters in old-devtools '
-                + 'mode. Both are presence checks, not '
-                + 'validity checks — a stale old-devtools token still reports '
-                + 'true here; a real publish/list call will surface staleness '
-                + 'with a clear error pointing back at reclaim_authenticate.',
+            description: 'Report which backend this server targets ("old" devtools or '
+                + '"builder"), WHY (a USE_OLD_DEVTOOLS env override, the persisted '
+                + 'config, or the default), and which mode is persisted for the '
+                + 'next start. Change it with set_devtools_mode. Also reports auth '
+                + 'status for both login systems: builderAuthenticated and '
+                + 'oldDevtoolsAuthenticated. Both are PRESENCE checks, not validity '
+                + 'checks — a stale token still reports true; a real call surfaces '
+                + 'the staleness with an error naming the tool to re-run. Which '
+                + 'login authorizes what: how_it_works({ topic: "auth" }).',
             inputSchema: { type: 'object', properties: {} },
         }, async () => {
             const persisted = config.read()?.mode;

package/lib/old/client.d.ts

@@ -51,7 +51,7 @@ export interface RegisterProviderBody {
     /** Interception mechanism (`NONE` = standard replay flow, the default;
      *  `HAWKEYE`/`MSWJS`/`XHOOK` = JS-context interception; `CDP` = browser-
      *  level). Column default is `HAWKEYE` when omitted entirely — unlike
-     *  `stepsToFollow` etc. above, whether the register endpoint actually
+     *  `stepsToFollow`, and so on. above, whether the register endpoint actually
      *  PERSISTS this field is UNVERIFIED (no source access to confirm); sent
      *  here on the chance it does, but the publish tool always follows up
      *  with a config (add-version) call regardless, which is confirmed to

package/lib/old/client.js

@@ -209,7 +209,7 @@ _ReclaimOldClient_identity = new WeakMap(), _ReclaimOldClient_fetch = new WeakMa
     // An identity ALREADY SET (as opposed to `#requireIdentity`'s "never
     // authenticated" case, which never reaches the backend) plus either a
     // 401/403 OR a message that itself names token verification means the
-    // backend rejected a token we had — i.e. it's stale/invalid, not merely
+    // backend rejected a token we had — that is, it's stale/invalid, not merely
     // absent. The message check matters because this backend does NOT
     // reliably use 401/403 for it — confirmed live: an actually-expired
     // Firebase token surfaced as "Error while verifying token" with a

package/lib/old/instructions.d.ts

@@ -1 +1,9 @@
-export declare const OLD_MODE_INSTRUCTIONS: string;
+/**
+ * MCP server instructions shown to the LLM when running in OLD-devtools mode
+ * (`USE_OLD_DEVTOOLS` unset or not `false`). Describes the REDUCED tool
+ * surface — there are no org/credential-link/review flows and no generated
+ * API tools here. Both modes' instructions load together in
+ * `mcp/instructions` (alongside the topic-split authoring guide); re-exported
+ * here so old-mode callers keep importing from their own module.
+ */
+export { OLD_MODE_INSTRUCTIONS } from '../mcp/instructions.ts';

package/lib/old/instructions.js

@@ -2,10 +2,8 @@
  * MCP server instructions shown to the LLM when running in OLD-devtools mode
  * (`USE_OLD_DEVTOOLS` unset or not `false`). Describes the REDUCED tool
  * surface — there are no org/credential-link/review flows and no generated
- * API tools here. The prose lives in `skill/old-mode.md` (published via the
- * `files` array); the path resolves identically from `src/old` (dev) and
- * `lib/old` (published).
+ * API tools here. Both modes' instructions load together in
+ * `mcp/instructions` (alongside the topic-split authoring guide); re-exported
+ * here so old-mode callers keep importing from their own module.
  */
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-export const OLD_MODE_INSTRUCTIONS = readFileSync(fileURLToPath(new URL('../../skill/old-mode.md', import.meta.url)), 'utf8').trim();
+export { OLD_MODE_INSTRUCTIONS } from "../mcp/instructions.js";

package/lib/old/login-cdp.d.ts

@@ -34,8 +34,8 @@ export interface CdpLoginResult {
  * finish signing in, read the resulting Firebase ID token from page storage,
  * then clean up. If we had to launch a dedicated Chrome for this, we close the
  * whole browser afterwards; if we attached to a Chrome that was already up
- * (e.g. the capture flow's), we only close the tab we opened so we don't
- * disrupt it.
+ * (for example, the capture flow's), we only close the tab we opened so we
+ * don't disrupt it.
  */
 export declare function captureFirebaseTokenViaCdp(opts: {
     loginUrl?: string;

package/lib/old/login-cdp.js

@@ -83,12 +83,18 @@ export const EXTRACT_TOKEN_JS = `(async () => {
  * finish signing in, read the resulting Firebase ID token from page storage,
  * then clean up. If we had to launch a dedicated Chrome for this, we close the
  * whole browser afterwards; if we attached to a Chrome that was already up
- * (e.g. the capture flow's), we only close the tab we opened so we don't
- * disrupt it.
+ * (for example, the capture flow's), we only close the tab we opened so we
+ * don't disrupt it.
  */
 export async function captureFirebaseTokenViaCdp(opts) {
     const loginUrl = opts.loginUrl || oldLoginUrl() || DEFAULT_LOGIN_URL;
-    const timeoutMs = opts.timeoutMs ?? 180000;
+    // 6 minutes, not 3. On a FRESH Chrome profile the dashboard is a cold load
+    // of an ~8.6 MB uncompressed bundle before the login form is even
+    // interactive — tens of seconds on a slow link — and only then does the
+    // developer start typing credentials and a 2FA code. The old 3-minute
+    // budget was routinely spent before they could finish, and the retry that
+    // followed looked like a 6-minute hang with no output.
+    const timeoutMs = opts.timeoutMs ?? 360000;
     const pollMs = opts.pollMs ?? 1000;
     const cfg = new ConfigStore().read()?.browser_agent;
     const mode = cfg?.attachMode ?? 'dedicated';
@@ -102,7 +108,7 @@ export async function captureFirebaseTokenViaCdp(opts) {
         if (mode !== 'dedicated') {
             throw new Error(`attach mode: nothing answering CDP on port ${port}. Launch Chrome ` +
                 `with --remote-debugging-port=${port} AND a non-default ` +
-                '--user-data-dir, or switch to dedicated mode (attach_chrome).');
+                '--user-data-dir, or switch to dedicated mode (attach_browser).');
         }
         launchChrome({ port, profileDir: defaultProfileDir() });
         await waitForCdpReady(port, 10000);
@@ -114,6 +120,10 @@ export async function captureFirebaseTokenViaCdp(opts) {
     try {
         const session = await handles.attachToTab(targetId);
         const deadline = Date.now() + timeoutMs;
+        // Tracks how far the page got, so a timeout can say WHICH thing stalled:
+        // a bundle that never finished downloading is a different problem from a
+        // developer who walked away mid-sign-in.
+        let sawInteractivePage = false;
         while (Date.now() < deadline) {
             const result = await session.send('Runtime.evaluate', {
                 expression: EXTRACT_TOKEN_JS,
@@ -124,10 +134,21 @@ export async function captureFirebaseTokenViaCdp(opts) {
             if (typeof value === 'string' && value.length > 0) {
                 return { token: value, closedBrowser: launchedByUs };
             }
+            if (!sawInteractivePage) {
+                sawInteractivePage = await pageIsInteractive(session);
+            }
             await new Promise((resolve) => setTimeout(resolve, pollMs));
         }
-        throw new Error('Timed out waiting for login. Finish signing in at the opened ' +
-            'page, or re-run reclaim_authenticate with a longer timeoutMs.');
+        const waited = Math.round(timeoutMs / 1000);
+        throw new Error(`Timed out after ${waited}s waiting for login. `
+            + (sawInteractivePage
+                ? 'The page finished loading, so sign-in was never completed — '
+                    + 'ask the developer to finish signing in at the opened window, '
+                    + 'then re-run reclaim_authenticate.'
+                : 'The page never became interactive, so the dashboard was still '
+                    + 'loading the whole time. On a fresh Chrome profile its bundle '
+                    + 'is a large cold download. Retry (the profile is now warm), or '
+                    + 'pass a bigger timeoutMs.'));
     }
     finally {
         // Best-effort cleanup — never mask the real result/error.
@@ -145,6 +166,25 @@ export async function captureFirebaseTokenViaCdp(opts) {
         await handles.close().catch(() => { });
     }
 }
+/**
+ * Whether the login page has reached a usable state. `readyState` alone is not
+ * enough for a single-bundle SPA: the document is 'complete' while the app is
+ * still parsing, and nothing is clickable yet. Requiring a rendered root as
+ * well is what distinguishes "still loading" from "waiting for the human".
+ */
+async function pageIsInteractive(session) {
+    try {
+        const result = await session.send('Runtime.evaluate', {
+            expression: 'document.readyState === "complete" '
+                + '&& !!document.body && document.body.innerText.trim().length > 0',
+            returnByValue: true,
+        });
+        return runtimeResultValue(result) === true;
+    }
+    catch {
+        return false;
+    }
+}
 function runtimeResultValue(value) {
     if (typeof value !== 'object' || !value || !('result' in value)) {
         return undefined;

package/lib/old/to-register.d.ts

@@ -26,7 +26,8 @@ export interface OldProviderOpts {
     /** Page-injection script — the devtools name for the builder's
      *  `webSettings.jsUserScripts`. Top-level on register, nested under
      *  `providerConfig` on config (add-version). The backend rejects a few
-     *  deprecated injection APIs (e.g. `window.payloadData`) with a 400. */
+     *  deprecated injection APIs (for example, `window.payloadData`) with a
+     *  400. */
     customInjection?: string;
     /** Accepted at register too (unlike the four fields below, which the
      *  backend only accepts on config/add-version). */
@@ -129,7 +130,7 @@ export interface SemverTriplet {
 /**
  * Pull `{major,minor,patch}` triplets out of a `/versions` response, tolerant
  * of the exact envelope (array, `{ providerVersions: [...] }`, `{ items }`,
- * etc.). Each entry's `version` is the triplet.
+ *, and so on). Each entry's `version` is the triplet.
  */
 export declare function extractVersions(resp: unknown): SemverTriplet[];
 /**

package/lib/old/to-register.js

@@ -184,7 +184,7 @@ export function providerToConfigBody(providers, opts, version, versionInfo) {
 /**
  * Pull `{major,minor,patch}` triplets out of a `/versions` response, tolerant
  * of the exact envelope (array, `{ providerVersions: [...] }`, `{ items }`,
- * etc.). Each entry's `version` is the triplet.
+ *, and so on). Each entry's `version` is the triplet.
  */
 export function extractVersions(resp) {
     const list = pickArray(resp);

package/lib/old/tools/authenticate.js

@@ -36,6 +36,11 @@ export function authenticateTool(client) {
             'and closes the tab. A previously stored identity that is still ' +
             'valid is reused first (pass `useBrowser: true` to force a fresh ' +
             'login). \n\n' +
+            'EXPECT THIS TO TAKE A WHILE ON A FIRST RUN: a fresh Chrome ' +
+            'profile downloads the dashboard cold, so tell the developer it is ' +
+            'loading and that the window is waiting for them — do not re-run ' +
+            'the tool while it is still waiting. It polls for up to 6 minutes ' +
+            'and reports whether the page ever became interactive.\n\n' +
             'Manual overrides:\n' +
             '- `token`: paste a Firebase ID token (skips the browser).\n' +
             '- `ethAddress`: an `eth:0x…` / `0x…` uid for an already-provisioned ' +
@@ -61,7 +66,10 @@ export function authenticateTool(client) {
                 },
                 timeoutMs: {
                     type: 'number',
-                    description: 'How long to wait for sign-in, in ms (default 180000).',
+                    description: 'How long to wait for sign-in, in ms (default 360000, i.e. 6 '
+                        + 'minutes). A fresh Chrome profile loads the dashboard cold, '
+                        + 'which can take tens of seconds before the form is usable — '
+                        + 'that time comes out of this budget.',
                 },
                 useBrowser: {
                     type: 'boolean',