@reclaimprotocol/agent 0.1.22 → 0.1.24

package/src/old/client.ts

@@ -47,6 +47,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 {
@@ -353,11 +362,31 @@ export class ReclaimOldClient {
 	}
 
 	#asBoom(res: Response, json: unknown): Boom {
-		const message =
+		const rawMessage =
 			(json && typeof json === 'object' &&
 				typeof (json as { message?: unknown }).message === 'string'
 				? (json as { message: string }).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 = !!this.#identity && (
+			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/src/old/instructions.ts

@@ -2,14 +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.ts'

package/src/old/login-cdp.ts

@@ -97,8 +97,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 async function captureFirebaseTokenViaCdp(opts: {
 	loginUrl?: string
@@ -107,7 +107,13 @@ export async function captureFirebaseTokenViaCdp(opts: {
 }): Promise<CdpLoginResult> {
 	const loginUrl =
 		opts.loginUrl || oldLoginUrl() || DEFAULT_LOGIN_URL
-	const timeoutMs = opts.timeoutMs ?? 180_000
+	// 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 ?? 360_000
 	const pollMs = opts.pollMs ?? 1000
 
 	const cfg = new ConfigStore().read()?.browser_agent
@@ -123,7 +129,7 @@ export async function captureFirebaseTokenViaCdp(opts: {
 			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).',
 			)
 		}
 
@@ -139,6 +145,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,
@@ -150,12 +160,24 @@ export async function captureFirebaseTokenViaCdp(opts: {
 				return { token: value, closedBrowser: launchedByUs }
 			}
 
+			if(!sawInteractivePage) {
+				sawInteractivePage = await pageIsInteractive(session)
+			}
+
 			await new Promise((resolve) => setTimeout(resolve, pollMs))
 		}
 
+		const waited = Math.round(timeoutMs / 1000)
 		throw new Error(
-			'Timed out waiting for login. Finish signing in at the opened ' +
-			'page, or re-run reclaim_authenticate with a longer timeoutMs.',
+			`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.
@@ -173,6 +195,28 @@ export async function captureFirebaseTokenViaCdp(opts: {
 	}
 }
 
+/**
+ * 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: { send: (m: string, p?: object) => Promise<unknown> },
+): Promise<boolean> {
+	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: unknown): unknown {
 	if(typeof value !== 'object' || !value || !('result' in value)) {
 		return undefined

package/src/old/to-register.ts

@@ -39,7 +39,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). */
@@ -61,13 +62,24 @@ export interface OldProviderOpts {
 	 *  field from the request body. Free-form JSON. */
 	extensionConfig?: unknown
 	/** Provider-level `disableRequestReplay` (HAWKEYE document replay skip).
-	 *  Config (add-version) ONLY: the register endpoint hardcodes it to false
-	 *  — the publish tool follows a register up with an add-version call to
-	 *  apply it for new providers (see `old/tools/publish.ts`). NOTE the
-	 *  builder backend has NO equivalent; its inverse is
-	 *  `webSettings.clientOptions.inapp.interceptorOptions
-	 *  .isDocumentRequestReplayEnabled`. */
+	 *  The publish tool always forces this `true` — there is no author-facing
+	 *  way to enable document replay. Config (add-version) ONLY: the register
+	 *  endpoint hardcodes it to false regardless of what's sent, so the
+	 *  publish tool always follows a register up with an add-version call to
+	 *  actually apply it (see `old/tools/publish.ts`). The builder backend's
+	 *  inverse-named equivalent, `webSettings.clientOptions.inapp
+	 *  .interceptorOptions.isDocumentRequestReplayEnabled`, is likewise always
+	 *  force-disabled by `providerToCreateVersionRequest`. */
 	disableRequestReplay?: boolean
+	/** Interception mechanism — `NONE` (the publish tool's default) for the
+	 *  standard capture→replay flow; `HAWKEYE`/`MSWJS`/`XHOOK`/`CDP` for a
+	 *  genuine live-interception provider. Old-devtools calls this
+	 *  `injectionType`; builder's equivalent is `webSettings.clientOptions
+	 *  .inapp.interceptorOptions.interceptorType` (no `NONE` value there —
+	 *  omitting the whole object is builder's no-interception signal
+	 *  instead). See `old/client.ts`'s `RegisterProviderBody.injectionType`
+	 *  doc for the register-persistence caveat. */
+	injectionType?: 'NONE' | 'MSWJS' | 'XHOOK' | 'CDP' | 'HAWKEYE'
 }
 
 interface OldResponseMatch {
@@ -269,6 +281,10 @@ export function providerToRegisterBody(
 		body.stepsToFollow = opts.stepsToFollow
 	}
 
+	if(opts.injectionType !== undefined) {
+		body.injectionType = opts.injectionType
+	}
+
 	return body
 }
 
@@ -323,6 +339,10 @@ export function providerToConfigBody(
 		providerConfig.disableRequestReplay = opts.disableRequestReplay
 	}
 
+	if(opts.injectionType !== undefined) {
+		providerConfig.injectionType = opts.injectionType
+	}
+
 	return { providerConfig, version, versionInfo }
 }
 
@@ -336,7 +356,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 function extractVersions(resp: unknown): SemverTriplet[] {
 	const list = pickArray(resp)

package/src/old/tools/authenticate.ts

@@ -46,6 +46,11 @@ export function authenticateTool(client: ReclaimOldClient): RegisteredTool {
 				'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 ' +
@@ -73,7 +78,10 @@ export function authenticateTool(client: ReclaimOldClient): RegisteredTool {
 					timeoutMs: {
 						type: 'number',
 						description:
-							'How long to wait for sign-in, in ms (default 180000).',
+							'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',

package/src/old/tools/get-provider-info.ts

@@ -3,8 +3,8 @@ import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
 import type { ReclaimSdkClient } from '../sdk-client.ts'
 
 /** Best-effort call: resolve to the response, or to an error string instead
- *  of throwing — one endpoint 404ing (e.g. a bad `versionNumber`) shouldn't
- *  hide a result the other endpoint DID have. */
+ *  of throwing — one endpoint 404ing (for example, a bad `versionNumber`)
+ *  shouldn't hide a result the other endpoint DID have. */
 async function attempt(
 	label: string,
 	call: () => Promise<unknown>,
@@ -51,8 +51,9 @@ export function getProviderInfoTool(client: ReclaimSdkClient): RegisteredTool {
 				'computed `isScriptRequestingClaim` flag). Read `provider` here ' +
 				'BEFORE create_provider_version_from_capture so you can pass the ' +
 				'whole existing config back — that tool always creates a new ' +
-				'version and carries nothing forward. One endpoint failing (e.g. ' +
-				'an invalid `versionNumber`) is reported under `errors` without ' +
+				'version and carries nothing forward. One endpoint failing (for ' +
+				'example, an invalid `versionNumber`) is reported under `errors` ' +
+				'without ' +
 				'hiding a result the other endpoint did return.',
 			inputSchema: {
 				type: 'object',
@@ -64,7 +65,7 @@ export function getProviderInfoTool(client: ReclaimSdkClient): RegisteredTool {
 					versionNumber: {
 						type: 'string',
 						description:
-							'Specific version, e.g. "1.0.2". Omit for the ' +
+							'Specific version, for example, "1.0.2". Omit for the ' +
 							"provider's current latest version.",
 					},
 				},

package/src/old/tools/issue-app-credentials.ts

@@ -24,8 +24,9 @@ export function issueAppCredentialsTool(
 				'starts UNLINKED and sandboxed (100 sessions) — call ' +
 				'link_app_to_account to attach it to your dashboard account and ' +
 				'check_app_status to check its state. Store `appSecret` like a ' +
-				'password (e.g. in a gitignored .env as RECLAIM_APP_SECRET) — it ' +
-				'is returned once and cannot be recovered from the server.',
+				'password (for example, in a gitignored .env as ' +
+				'RECLAIM_APP_SECRET) — it is returned once and cannot be ' +
+				'recovered from the server.',
 			inputSchema: { type: 'object', properties: {} },
 		},
 		async() => {

package/src/old/tools/me-providers.ts

@@ -21,7 +21,9 @@ export function getMeProvidersTool(client: ReclaimOldClient): RegisteredTool {
 				'first). Returns provider metadata including each `providerId` — ' +
 				'pass one back to create_provider_version_from_capture to publish a ' +
 				'new version of that provider instead of creating a duplicate. ' +
-				'Requires reclaim_authenticate first.',
+				'Requires reclaim_authenticate (old-devtools login) first — this ' +
+					'is separate from authenticate_builder/Builder auth, which does ' +
+					'not authorize this call. Check status with get_devtools_mode.',
 			inputSchema: {
 				type: 'object',
 				properties: {