@reclaimprotocol/agent 0.1.22 → 0.1.24

package/lib/mcp/tools/authenticate/authenticate.js

@@ -1,7 +1,6 @@
-import assert from 'node:assert';
 import { spawn } from 'node:child_process';
-import { createHash, randomBytes } from 'node:crypto';
 import { createServer } from 'node:http';
+import * as oauth from 'openid-client';
 import { defineTool } from "../../server.js";
 import { writeSession } from "./session-cache.js";
 const SCOPE = 'openid profile email';
@@ -10,9 +9,12 @@ export function authenticateTool(client, name = 'reclaim_authenticate') {
     return defineTool({
         name,
         description: (name === 'authenticate_builder'
-            ? 'Authenticate specifically with Builder. Available regardless '
-                + 'of '
-                + 'the selected publishing backend. '
+            ? '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 '
@@ -21,44 +23,120 @@ 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));
 }
-async function runOAuthLoopback(client) {
+const _customFetchForOauth = async (url, options) => {
+    const res = await fetch(url, options);
+    if (options.method === 'POST' && res.status === 200 &&
+        new URL(url).pathname.endsWith('/oauth2/register')) {
+        return new Response(await res.text(), {
+            status: 201,
+            headers: res.headers,
+        });
+    }
+    return res;
+};
+/**
+ * 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 async function runOAuthLoopback(client, 
+// Overridable only so tests can intercept the authorize URL instead of
+// actually spawning a browser; every real caller uses the default.
+openBrowserFn = openBrowser) {
     const authBase = `${client.baseUrl}/auth`;
-    const verifier = base64url(randomBytes(32));
-    const challenge = base64url(createHash('sha256').update(verifier).digest());
-    const state = base64url(randomBytes(16));
+    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, and the same client_id has to be presented again at the
-    // token endpoint (public clients authenticate by client_id alone).
-    const callback = await listenForCallback(state);
-    let token;
+    // loopback redirect.
+    const callback = await listenForCallback();
+    let tokens;
     try {
-        const clientId = await registerClient(authBase, callback.redirectUri);
-        openBrowser(authorizeUrl(authBase, {
-            clientId,
-            redirectUri: callback.redirectUri,
-            challenge,
+        const config = await oauth.dynamicClientRegistration(new URL(authBase), {
+            client_name: 'Reclaim CLI',
+            redirect_uris: [callback.redirectUri],
+            token_endpoint_auth_method: 'none',
+            grant_types: ['authorization_code', 'refresh_token'],
+            response_types: ['code'],
+            scope: SCOPE,
+        }, undefined, {
+            // Better Auth exposes its metadata at the RFC 8414 well-known path
+            // (`.well-known/oauth-authorization-server`), not the OIDC one.
+            algorithm: 'oauth2',
+            // RFC 7591 §3.2.1 requires 201 Created on a successful registration;
+            // openid-client enforces that strictly. Better Auth's
+            // `oauth-provider` plugin doesn't conform — confirmed live against
+            // the real server: `POST .../oauth2/register` returns 200 with an
+            // otherwise well-formed body, which openid-client rejects outright
+            // ("unexpected HTTP response status code") before ever looking at
+            // it. `customFetch` set here persists onto the returned
+            // `Configuration` for ALL its future calls too (token exchange
+            // included, which correctly returns 200) — so the URL itself, not
+            // just method+status, must gate the rewrite, or a genuine 200 from
+            // the token endpoint gets corrupted into a 201 and
+            // `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,
+            scope: SCOPE,
             state,
-        }));
-        const code = await callback.code;
-        token = await exchangeCode(authBase, {
-            code,
-            verifier,
-            redirectUri: callback.redirectUri,
-            clientId,
+            code_challenge: codeChallenge,
+            code_challenge_method: 'S256',
+        }).href);
+        const callbackUrl = await callback.url;
+        tokens = await oauth.authorizationCodeGrant(config, callbackUrl, {
+            pkceCodeVerifier: codeVerifier,
+            expectedState: state,
         });
     }
+    catch (err) {
+        // A denied or failed authorization surfaces as this error class with
+        // the raw callback params on `.cause` — reword it like the previous
+        // hand-rolled check did (RFC 6749 §4.1.2.1's error/error_description).
+        if (err instanceof oauth.AuthorizationResponseError) {
+            throw new Error(err.cause.get('error_description')
+                ?? err.cause.get('error')
+                ?? 'Sign-in failed or was cancelled.');
+        }
+        throw err;
+    }
     finally {
         callback.close();
     }
-    const expiresAt = new Date(Date.now() + token.expires_in * 1000).toISOString();
-    writeSession({ token: token.access_token, expiresAt });
-    client.setToken(token.access_token);
+    const expiresAt = new Date(Date.now() + (tokens.expires_in ?? 3600) * 1000).toISOString();
+    writeSession({ token: tokens.access_token, expiresAt });
+    client.setToken(tokens.access_token);
     return {
         status: 'AUTHENTICATED',
         note: 'Access token cached in ~/.reclaim/config.json and active now.',
@@ -67,42 +145,23 @@ async function runOAuthLoopback(client) {
 }
 /**
  * Bind an ephemeral loopback port and start listening for the provider's
- * redirect. Resolves as soon as the port is known — the `code` promise settles
+ * redirect. Resolves as soon as the port is known — the `url` promise settles
  * later, when the browser hits `/callback` — so the caller can register a
  * client for this exact redirect URI before sending the user off to authorize.
- * The ephemeral port lets any number of CLIs run concurrently. Defined below
- * its caller per repo convention.
+ * The ephemeral port lets any number of CLIs run concurrently. Hands back the
+ * RAW callback URL rather than picking `code`/`state` apart itself —
+ * `oauth.authorizationCodeGrant` does that validation. Defined below its
+ * caller per repo convention.
  */
-async function listenForCallback(state) {
-    let resolveCode;
-    let rejectCode;
-    const code = new Promise((resolve, reject) => {
-        resolveCode = resolve;
-        rejectCode = reject;
+async function listenForCallback() {
+    let resolveUrl;
+    let rejectUrl;
+    const url = new Promise((resolve, reject) => {
+        resolveUrl = resolve;
+        rejectUrl = reject;
     });
     const server = createServer();
-    const timer = setTimeout(() => rejectCode(new Error('Timed out waiting for sign-in (5 min).')), CALLBACK_TIMEOUT_MS);
-    server.on('request', (req, res) => {
-        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
-        if (url.pathname !== '/callback') {
-            res.writeHead(404).end();
-            return;
-        }
-        res.writeHead(200, { 'content-type': 'text/html' });
-        res.end('<!doctype html><meta charset=utf-8><body style="font:16px '
-            + 'system-ui;padding:3rem;text-align:center">Signed in. You can '
-            + 'close this tab and return to your terminal.</body>');
-        const authCode = url.searchParams.get('code');
-        if (!authCode || url.searchParams.get('state') !== state) {
-            // A denied or failed authorization comes back as `error`/
-            // `error_description` (RFC 6749 §4.1.2.1) — surface it verbatim.
-            const err = url.searchParams.get('error_description')
-                ?? url.searchParams.get('error');
-            rejectCode(new Error(err ?? 'Sign-in failed or was cancelled.'));
-            return;
-        }
-        resolveCode(authCode);
-    });
+    const timer = setTimeout(() => rejectUrl(new Error('Timed out waiting for sign-in (5 min).')), CALLBACK_TIMEOUT_MS);
     const port = await new Promise((resolve, reject) => {
         server.once('error', reject);
         server.listen(0, '127.0.0.1', () => {
@@ -113,75 +172,38 @@ async function listenForCallback(state) {
             }
             resolve(addr.port);
         });
+    }).catch((err) => {
+        // Bind failed before `close()` (returned below) is ever reachable —
+        // clear the timer ourselves, or it fires 5 minutes later and rejects
+        // the now-unobserved `url` promise (unhandled rejection) while keeping
+        // the process alive in the meantime.
+        clearTimeout(timer);
+        throw err;
     });
     // Past bind, a socket error fails the pending wait rather than throwing.
-    server.on('error', (err) => rejectCode(err));
+    server.on('error', (err) => rejectUrl(err));
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    server.on('request', (req, res) => {
+        const reqUrl = new URL(req.url ?? '/', redirectUri);
+        if (reqUrl.pathname !== '/callback') {
+            res.writeHead(404).end();
+            return;
+        }
+        res.writeHead(200, { 'content-type': 'text/html' });
+        res.end('<!doctype html><meta charset=utf-8><body style="font:16px '
+            + 'system-ui;padding:3rem;text-align:center">Signed in. You can '
+            + 'close this tab and return to your terminal.</body>');
+        resolveUrl(reqUrl);
+    });
     return {
-        redirectUri: `http://127.0.0.1:${port}/callback`,
-        code,
+        redirectUri,
+        url,
         close: () => {
             clearTimeout(timer);
             server.close();
         },
     };
 }
-function authorizeUrl(authBase, opts) {
-    return `${authBase}/oauth2/authorize?`
-        + new URLSearchParams({
-            response_type: 'code',
-            client_id: opts.clientId,
-            redirect_uri: opts.redirectUri,
-            scope: SCOPE,
-            state: opts.state,
-            code_challenge: opts.challenge,
-            code_challenge_method: 'S256',
-        }).toString();
-}
-/** Dynamic client registration (RFC 7591) for a public PKCE client. */
-async function registerClient(authBase, redirectUri) {
-    const res = await fetch(`${authBase}/oauth2/register`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({
-            client_name: 'Reclaim CLI',
-            redirect_uris: [redirectUri],
-            token_endpoint_auth_method: 'none',
-            grant_types: ['authorization_code', 'refresh_token'],
-            response_types: ['code'],
-            scope: SCOPE,
-        }),
-    });
-    assert(res.ok, new Error(`Client registration failed (${res.status}).`));
-    const json = (await res.json());
-    assert(json.client_id, new Error('Client registration returned no client_id.'));
-    return json.client_id;
-}
-async function exchangeCode(authBase, opts) {
-    const res = await fetch(`${authBase}/oauth2/token`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/x-www-form-urlencoded' },
-        body: new URLSearchParams({
-            grant_type: 'authorization_code',
-            code: opts.code,
-            redirect_uri: opts.redirectUri,
-            code_verifier: opts.verifier,
-            // Required even though this is a public client with no secret: it's
-            // how the token endpoint identifies the client (RFC 6749 §4.1.3).
-            client_id: opts.clientId,
-        }).toString(),
-    });
-    const body = await res.text();
-    assert(res.ok, new Error(`Token exchange failed (${res.status}): ${body}`));
-    const json = JSON.parse(body);
-    assert(json.access_token, new Error('Token exchange returned no access_token.'));
-    return {
-        access_token: json.access_token,
-        expires_in: json.expires_in ?? 3600,
-    };
-}
-function base64url(buf) {
-    return buf.toString('base64url');
-}
 function openBrowser(url) {
     const cmd = process.platform === 'darwin'
         ? 'open'

package/lib/mcp/tools/authenticate/builder-access.d.ts

@@ -1,8 +1,13 @@
 import type { ReclaimClient } from '@reclaimprotocol/client';
 import { type RegisteredTool } from '../../server.ts';
-/** Legacy-devtools mode needs a distinct Builder login solely for allocating
- * quota-accounted Popcorn sessions. Builder mode uses its native auth tool. */
+/** Legacy-devtools mode needs a distinct Builder login for its two
+ * Builder-exclusive features: allocating quota-accounted Popcorn sessions
+ * (see `buildBuilderOrganizationTools` below) and listing Builder
+ * organizations. Builder mode needs neither — its native auth tool alone
+ * covers both, org listing included (via its generated `list_orgs`). */
 export declare function buildBuilderAuthenticationTools(client: ReclaimClient): RegisteredTool[];
 /** Legacy-devtools mode lacks generated Builder API tools, so it needs this
- * narrow organization-discovery bridge for remote-browser allocation. */
+ * narrow organization-discovery bridge — an org id is required to allocate a
+ * remote-browser (Popcorn) session. Builder mode's own `list_orgs` already
+ * covers this under its native auth. */
 export declare function buildBuilderOrganizationTools(client: ReclaimClient): RegisteredTool[];

package/lib/mcp/tools/authenticate/builder-access.js

@@ -1,12 +1,17 @@
 import { defineTool } from "../../server.js";
 import { authenticateTool } from "./authenticate.js";
-/** Legacy-devtools mode needs a distinct Builder login solely for allocating
- * quota-accounted Popcorn sessions. Builder mode uses its native auth tool. */
+/** Legacy-devtools mode needs a distinct Builder login for its two
+ * Builder-exclusive features: allocating quota-accounted Popcorn sessions
+ * (see `buildBuilderOrganizationTools` below) and listing Builder
+ * organizations. Builder mode needs neither — its native auth tool alone
+ * covers both, org listing included (via its generated `list_orgs`). */
 export function buildBuilderAuthenticationTools(client) {
     return [authenticateTool(client, 'authenticate_builder')];
 }
 /** Legacy-devtools mode lacks generated Builder API tools, so it needs this
- * narrow organization-discovery bridge for remote-browser allocation. */
+ * narrow organization-discovery bridge — an org id is required to allocate a
+ * remote-browser (Popcorn) session. Builder mode's own `list_orgs` already
+ * covers this under its native auth. */
 export function buildBuilderOrganizationTools(client) {
     return [
         defineTool({

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

@@ -1,6 +1,18 @@
 import { defaultConfigPath } from "../../../config/store.js";
 import { oldModeSource } from "../../../consts.js";
 import { defineTool } from "../../server.js";
+/** Whether `config`'s cached builder session token is present and not yet
+ *  expired. Mirrors `readSession`'s check, but against the CALLER's
+ *  `ConfigStore` instance (not always the default `~/.reclaim/config.json`
+ *  path) so this stays test-isolatable and consistent with the rest of this
+ *  tool's config reads. */
+function hasValidBuilderSession(config) {
+    const session = config.read()?.session;
+    if (!session?.token || !session.expiresAt) {
+        return false;
+    }
+    return new Date(session.expiresAt) > new Date();
+}
 /**
  * The `set_devtools_mode` / `get_devtools_mode` tools: persist which backend
  * the MCP server targets (`old` devtools vs the `builder`), and
@@ -8,7 +20,7 @@ import { defineTool } from "../../server.js";
  * `~/.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
@@ -49,20 +61,27 @@ 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.',
+            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;
+            const oldIdentity = config.read()?.old_devtools;
             return {
                 mode: current,
                 source: oldModeSource(persisted),
                 persistedMode: persisted ?? null,
                 configPath: defaultConfigPath(),
+                builderAuthenticated: hasValidBuilderSession(config),
+                oldDevtoolsAuthenticated: !!oldIdentity,
+                oldDevtoolsIdentityKind: oldIdentity?.kind ?? null,
             };
         }),
     ];

package/lib/old/client.d.ts

@@ -48,6 +48,15 @@ export interface RegisterProviderBody {
      *  controller's destructure + its `providerConfig` write, both of which
      *  include it alongside `pageTitle`/`userAgent`. */
     stepsToFollow?: string;
+    /** 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`, 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
+     *  persist it. */
+    injectionType?: 'NONE' | 'MSWJS' | 'XHOOK' | 'CDP' | 'HAWKEYE';
 }
 export interface UpdateProviderConfigBody {
     providerConfig: Record<string, unknown>;

package/lib/old/client.js

@@ -202,10 +202,28 @@ _ReclaimOldClient_identity = new WeakMap(), _ReclaimOldClient_fetch = new WeakMa
         return undefined;
     }
 }, _ReclaimOldClient_asBoom = function _ReclaimOldClient_asBoom(res, json) {
-    const message = (json && typeof json === 'object' &&
+    const rawMessage = (json && typeof json === 'object' &&
         typeof json.message === 'string'
         ? json.message
         : undefined) || res.statusText || 'Old devtools request failed';
+    // 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 — 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
+    // status this narrow check (401/403-only) missed entirely, silently
+    // skipping the enrichment. The backend's own message gives no hint of
+    // the fix, and nothing else distinguishes this from Builder auth, so
+    // append repo-side guidance rather than replacing the raw detail.
+    const staleAuth = !!__classPrivateFieldGet(this, _ReclaimOldClient_identity, "f") && (res.status === 401 || res.status === 403 ||
+        /verify.{0,20}token|token.{0,20}verif/i.test(rawMessage));
+    const message = staleAuth
+        ? `${rawMessage} — your old-devtools login looks stale or invalid `
+            + '(this is separate from Builder auth). Re-run reclaim_authenticate '
+            + 'to refresh it, then retry.'
+        : rawMessage;
     // Shape `data` like a ProblemDetails so remapErrorAsResponse can render
     // `${message}: ${data.detail}` and expose the raw body as structured.
     return new Boom(message, {

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;