@reclaimprotocol/agent 0.1.22 → 0.1.24

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). */
@@ -51,13 +52,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 {
     value: string;
@@ -118,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

@@ -133,6 +133,9 @@ export function providerToRegisterBody(providers, opts) {
     if (opts.stepsToFollow !== undefined) {
         body.stepsToFollow = opts.stepsToFollow;
     }
+    if (opts.injectionType !== undefined) {
+        body.injectionType = opts.injectionType;
+    }
     return body;
 }
 /** Body for `POST /api/providers/:providerId/config` — adds a new version to
@@ -173,12 +176,15 @@ export function providerToConfigBody(providers, opts, version, versionInfo) {
     if (opts.disableRequestReplay !== undefined) {
         providerConfig.disableRequestReplay = opts.disableRequestReplay;
     }
+    if (opts.injectionType !== undefined) {
+        providerConfig.injectionType = opts.injectionType;
+    }
     return { providerConfig, 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',

package/lib/old/tools/get-provider-info.js

@@ -1,8 +1,8 @@
 import { isBoom } from '@hapi/boom';
 import { defineTool } from "../../mcp/server.js";
 /** 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, call) {
     try {
         return { ok: true, value: await call() };
@@ -44,8 +44,9 @@ export function getProviderInfoTool(client) {
             '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',
@@ -56,7 +57,7 @@ export function getProviderInfoTool(client) {
                 },
                 versionNumber: {
                     type: 'string',
-                    description: 'Specific version, e.g. "1.0.2". Omit for the ' +
+                    description: 'Specific version, for example, "1.0.2". Omit for the ' +
                         "provider's current latest version.",
                 },
             },

package/lib/old/tools/issue-app-credentials.js

@@ -18,8 +18,9 @@ export function issueAppCredentialsTool(client) {
             '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 () => {
         const { appId, appSecret } = await client.issueCredentials();

package/lib/old/tools/me-providers.js

@@ -13,7 +13,9 @@ export function getMeProvidersTool(client) {
             '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: {

package/lib/old/tools/publish.d.ts

@@ -4,7 +4,7 @@ import type { ReclaimOldClient } from '../client.ts';
 /**
  * Publish a drafted provider to the OLD devtools backend. Keeps the builder
  * tool NAME (`create_provider_version_from_capture`) so the skill flow is
- * unchanged, but the behaviour differs:
+ * unchanged, but the behavior differs:
  *
  *   - WITHOUT `providerId` → `POST /api/providers/register`: creates a
  *     brand-new provider + version 1.0.0. Re-running creates a DUPLICATE.

package/lib/old/tools/publish.js

@@ -1,6 +1,6 @@
 import { Boom, isBoom } from '@hapi/boom';
 import { defineTool } from "../../mcp/server.js";
-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 { bumpPatchString, extractVersions, injectedRequestDataFrom, providerToConfigBody, providerToRegisterBody, } from "../to-register.js";
 const DEFAULT_VERSION_INFO = 'Updated from MCP browser capture';
@@ -15,8 +15,8 @@ function extractProviderId(resp) {
  * `providerId` for a public provider (or anyone else's) comes back as
  * 401/403/404 — the dev's likely intent is to publish their OWN version of that
  * site, which on this backend means registering a separate copy. Rethrow those
- * failures with that actionable suggestion; leave other errors (e.g. a 400
- * version collision) untouched so their real detail surfaces.
+ * failures with that actionable suggestion; leave other errors (for example, a
+ * 400 version collision) untouched so their real detail surfaces.
  */
 function rethrowOwnershipError(err, providerId) {
     const status = isBoom(err) ? err.output.statusCode : undefined;
@@ -37,7 +37,7 @@ function rethrowOwnershipError(err, providerId) {
 /**
  * Publish a drafted provider to the OLD devtools backend. Keeps the builder
  * tool NAME (`create_provider_version_from_capture`) so the skill flow is
- * unchanged, but the behaviour differs:
+ * unchanged, but the behavior differs:
  *
  *   - WITHOUT `providerId` → `POST /api/providers/register`: creates a
  *     brand-new provider + version 1.0.0. Re-running creates a DUPLICATE.
@@ -56,54 +56,38 @@ function rethrowOwnershipError(err, providerId) {
 export function createVersionFromCaptureTool(client, attachRef) {
     return defineTool({
         name: 'create_provider_version_from_capture',
-        description: 'Publish drafted ReclaimProvider(s) to the devtools backend. ' +
-            'Pass the `provider` object from propose_provider VERBATIM and the ' +
-            '`initialUrl` the user landed on (the login/landing page, NOT the ' +
-            'API url). \n\n' +
-            'For a MULTI-REQUEST provider, pass `providers: [...]` (each entry a ' +
-            'proven draft from propose_provider) — every entry becomes one ' +
-            '`requestData` entry on the SAME version, and all are verified ' +
-            'together. Pass a single `provider` for the one-request case ' +
-            '(provide exactly one of `provider` / `providers`). \n\n' +
-            'Omit `providerId` to REGISTER A NEW provider (creates it + version ' +
-            '1.0.0; re-running creates a duplicate). Pass `providerId` (from ' +
-            'get_me_providers) to add a NEW VERSION to that existing provider ' +
-            '(the patch is auto-bumped). \n\n' +
-            'You can only add versions to a provider YOU own — the `providerId` ' +
-            'must come from get_me_providers. To publish your own version of a ' +
-            "PUBLIC provider you don't own, omit `providerId` to register your " +
-            'own copy (you cannot edit someone else\'s provider here). \n\n' +
-            'For data gated behind login/navigation, pass `customInjection` — a ' +
-            'page-injection script (the devtools name for the builder\'s ' +
-            'jsUserScripts) that drives the page to where the request fires. \n\n' +
-            'BY DESIGN, this backend only ever CREATES A NEW VERSION (POST) — ' +
-            'there is no partial-patch/edit endpoint, and this tool does NOT ' +
-            'read or carry anything forward from the previous version. Every ' +
-            'new version replaces the WHOLE providerConfig with exactly what ' +
-            'you pass in THIS call. Therefore any field you want present in the ' +
-            'new version MUST be supplied here — `customInjection`, `userAgent`, ' +
-            '`pageTitle`, `allowedInjectedRequestData`, `stepsToFollow`, ' +
-            '`useIncognitoWebview`, `extensionConfig`, and `requestData` (via ' +
-            '`provider`/`providers`). Anything you OMIT is published blank/' +
-            'default in the new version, NOT preserved. To change one field ' +
-            'while keeping the rest, first read the current version with ' +
-            'get_provider_info, then pass the full desired config (the existing ' +
-            'values plus your change) back into this call. ' +
-            '`allowedInjectedRequestData`/`useIncognitoWebview`/' +
-            '`extensionConfig` only take effect on add-version — the register ' +
-            'endpoint (no `providerId`) ignores them. `disableRequestReplay` ' +
-            'is also add-version-only, but when it is true the tool follows ' +
-            'a register up with an add-version call automatically so it takes ' +
-            'effect on new providers too. Per-request fields you may set on ' +
-            '`provider`/`providers`: `credentials` (omit/same-origin/include, ' +
-            'default include), `urlType` (REGEX/CONSTANT/TEMPLATE, default ' +
-            'derived from {{placeholders}}), and `isOptional` on each ' +
-            'responseMatch (default false). \n\n' +
-            'Captured requests must be GET/POST. OPRF redactions are supported. ' +
-            '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.',
+        description: 'Publish drafted ReclaimProvider(s) to the devtools backend. Needs '
+            + 'its OWN reclaim_authenticate login — authenticate_builder does NOT '
+            + 'authorize this call. Pass the `provider` object(s) from '
+            + 'propose_provider VERBATIM, plus the `initialUrl` the user landed '
+            + 'on (the login/landing page, NOT the API url). Exactly one of '
+            + '`provider` (one request) or `providers` (a multi-request '
+            + 'provider — every entry becomes a parallel requestData entry, all '
+            + 'verified together). Captured requests must be GET/POST; OPRF '
+            + 'redactions are supported.\n\n'
+            + 'Omit `providerId` to REGISTER A NEW provider (creates it + '
+            + 'version 1.0.0 — re-running creates a DUPLICATE). Pass '
+            + '`providerId` (from get_me_providers) to add a NEW VERSION to it; '
+            + 'the patch auto-bumps. You can only version a provider YOU own — '
+            + 'to publish your own take on one you don\'t own, omit '
+            + '`providerId` to register your own copy.\n\n'
+            + 'THIS BACKEND ONLY EVER CREATES A NEW VERSION — there is no '
+            + 'partial-patch endpoint, and this tool carries NOTHING forward '
+            + 'from the previous version: every version replaces the WHOLE '
+            + 'providerConfig with exactly what you pass in THIS call. Any '
+            + 'field you want to survive must be re-supplied here '
+            + '(`customInjection`, `userAgent`, `pageTitle`, '
+            + '`allowedInjectedRequestData`, `stepsToFollow`, '
+            + '`useIncognitoWebview`, `extensionConfig`, `requestData`); '
+            + 'anything omitted is published blank. To change one field, read '
+            + 'the current config with get_provider_info first and pass it back '
+            + 'with your edit. `allowedInjectedRequestData`/'
+            + '`useIncognitoWebview`/`extensionConfig` apply on add-version '
+            + 'only, so a fresh register auto-follows with an add-version call '
+            + 'that applies them (and disables document replay — see '
+            + '`disableRequestReplay`).\n\n'
+            + 'Always read the response\'s `_notes`. '
+            + 'Full walkthrough: how_it_works({ topic: "publish" }).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -205,15 +189,11 @@ export function createVersionFromCaptureTool(client, attachRef) {
                 },
                 customInjection: {
                     type: 'string',
-                    description: 'Plain JavaScript injected into the provider page before every ' +
-                        'page load — old-devtools\' name for what the builder calls ' +
-                        '`webSettings.jsUserScripts`. Use standard browser APIs ' +
-                        '(window.location, element.click(), forms) to drive login/' +
-                        'navigation so the target request fires — window.Reclaim is ' +
-                        'only for rare edge cases, not navigation. The backend rejects ' +
-                        'a few deprecated injection APIs (e.g. window.payloadData, ' +
-                        'window.ReclaimInjected) with a 400. Guide:\n\n' +
-                        INJECTION_GUIDE,
+                    description: USER_SCRIPT_HINT
+                        + ' Old-devtools\' name for what the builder calls '
+                        + 'webSettings.jsUserScripts. The backend rejects a few '
+                        + 'deprecated injection APIs (window.payloadData, '
+                        + 'window.ReclaimInjected) with a 400.',
                 },
                 userAgent: {
                     type: 'object',
@@ -230,39 +210,15 @@ export function createVersionFromCaptureTool(client, attachRef) {
                 },
                 allowedInjectedRequestData: {
                     type: 'array',
-                    description: 'Extra requests the customInjection script is allowed to ' +
-                        'fire (e.g. pagination) — add-version ONLY, the register ' +
-                        'endpoint ignores this. Each item has the same shape as ' +
-                        '`provider`, plus `multiple`/`required` (default true). ' +
-                        'IMPORTANT whenever a claim\'s request HAS a body: set `body` ' +
-                        'here (see its own description below) — if only a small part ' +
-                        'of the real body varies per user/run (e.g. one id field, not ' +
-                        'the whole payload), template just that part with ' +
-                        '`{{paramName}}` and keep the rest as fixed literal text; see ' +
-                        'the "bodySniff" section of the customInjection field\'s guide ' +
-                        'for the exact mechanics and a worked example. ' +
-                        '⚠️ BEFORE populating this to gate ' +
-                        '`verifyProof(proof, { providerId })`: 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, no matter ' +
-                        'how correct the rest of this entry is — populating' +
-                        'it for such ' +
-                        'a provider makes verifyProof reject every real proof,' +
-                        'which is ' +
-                        'worse than leaving this field 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 ' +
-                        'customInjection field\'s guide for the full mechanics and ' +
-                        'when to reach for it.',
+                    description: 'Extra requests the customInjection user script is allowed to '
+                        + 'fire (for example, pagination) — add-version ONLY, the '
+                        + 'register '
+                        + 'endpoint ignores it. Each item has the same shape as '
+                        + '`provider`, plus `multiple`/`required` (default true). Set '
+                        + '`body` whenever the request has one (see its own description '
+                        + 'below). The builder calls the same concept '
+                        + '`allowedJsRequests`. '
+                        + ALLOWED_REQUESTS_HINT,
                     items: {
                         type: 'object',
                         properties: {
@@ -282,7 +238,8 @@ export function createVersionFromCaptureTool(client, attachRef) {
                                     'body at all (skip only for a genuinely bodyless ' +
                                     'request, typically GET). If the real body is FIXED ' +
                                     '(identical for every user/run), put that literal body ' +
-                                    'text here verbatim. If only PART of it varies (e.g. ' +
+                                    'text here verbatim. If only PART of it varies (for ' +
+                                    'example, ' +
                                     '`{"request":1,"type":"user_info","id":"12345"}` where ' +
                                     'only `id` differs per user), template ONLY that part: ' +
                                     '`{"request":1,"type":"user_info",' +
@@ -305,7 +262,7 @@ export function createVersionFromCaptureTool(client, attachRef) {
                                     'reproduces the real captured request body ' +
                                     'byte-for-byte. Fallback if per-field templating keeps ' +
                                     'mismatching (more fields vary than expected, unstable ' +
-                                    'key order, etc.) and you can\'t pin down every ' +
+                                    'key order, and so on) and you can\'t pin down every ' +
                                     'variable field: template the WHOLE body as one ' +
                                     'placeholder instead, `{{REQ_BODY_GRD}}` — the `GRD` ' +
                                     'suffix makes it a greedy match (captures everything) ' +
@@ -322,7 +279,7 @@ export function createVersionFromCaptureTool(client, attachRef) {
                                     '`value` must literally appear (or match, if `regex`) ' +
                                     'somewhere in the response body for the claim to be ' +
                                     'accepted; it commonly embeds one or more ' +
-                                    '`{{paramName}}` extraction placeholders (e.g. ' +
+                                    '`{{paramName}}` extraction placeholders (for example, ' +
                                     '`"name":"{{name_0}}"`) whose real value is redacted ' +
                                     'out and supplied separately as a witness/extracted ' +
                                     'param. Use `${var}` (not `{{var}}`) inside this string ' +
@@ -337,7 +294,8 @@ export function createVersionFromCaptureTool(client, attachRef) {
                                 description: 'Each item: `{ jsonPath?: string, xPath?: string, ' +
                                     'regex?: string, hash?: string }`. Identifies WHICH ' +
                                     'part of the response the matching `{{paramName}}` in ' +
-                                    '`responseMatches` actually redacts/extracts — e.g. ' +
+                                    '`responseMatches` actually redacts or extracts — for ' +
+                                    'example, ' +
                                     '`jsonPath: "$.data.items[0].name"` for a JSON response. ' +
                                     'Order/count should line up with `responseMatches`\' ' +
                                     'placeholders one-to-one for a typical claim.',
@@ -388,13 +346,34 @@ export function createVersionFromCaptureTool(client, attachRef) {
                     description: 'Free-form JSON passed through to the client. Add-version ' +
                         'ONLY.',
                 },
+                injectionType: {
+                    type: 'string',
+                    enum: ['NONE', 'MSWJS', 'XHOOK', 'CDP', 'HAWKEYE'],
+                    description: 'Interception mechanism for this version. Omit to leave it ' +
+                        'unset — the devtools backend\'s own column default ' +
+                        '(`HAWKEYE`) applies, which is inert and harmless for the ' +
+                        'standard capture→replay flow with no interceptor script ' +
+                        'installed. Only set `HAWKEYE`/`MSWJS`/`XHOOK` when you are ' +
+                        'ALSO supplying a `customInjection` script that calls ' +
+                        '`window.reclaimInterceptor.addResponseMiddleware(...)` for ' +
+                        'genuine live interception, or set `NONE` explicitly to be ' +
+                        'certain none is configured. Builder calls the equivalent ' +
+                        'concept `interceptorType` (no `NONE` there — omitting the ' +
+                        'whole `interceptorOptions` object is its no-interception ' +
+                        'signal instead). What each value actually does: ' +
+                        'how_it_works({ topic: "interception" }).',
+                },
                 disableRequestReplay: {
                     type: 'boolean',
-                    description: 'Skip replaying the main document request (HAWKEYE ' +
-                        'provider-level flag). Honored on add-version; for a ' +
-                        'provider (no `providerId`) the register endpoint ignores ' +
-                        'it, so when true the tool automatically follows the ' +
-                        'register up with an add-version call that applies it.',
+                    description: 'Whether the page\'s own document/navigation request is ' +
+                        'skipped (constructed locally) instead of genuinely replayed ' +
+                        'through the interceptor. Defaults to `true` (disabled) when ' +
+                        'omitted. Only meaningful for `injectionType` ' +
+                        'HAWKEYE/MSWJS/XHOOK — pass `false` to enable real document ' +
+                        'replay for those (for example, the target value is embedded ' +
+                        'in the page\'s own HTML). Inert when `injectionType` is ' +
+                        '`CDP` or ' +
+                        'unset.',
                 },
             },
             required: ['initialUrl'],
@@ -429,7 +408,13 @@ export function createVersionFromCaptureTool(client, attachRef) {
             stepsToFollow: args.stepsToFollow,
             useIncognitoWebview: args.useIncognitoWebview,
             extensionConfig: args.extensionConfig,
-            disableRequestReplay: args.disableRequestReplay,
+            // Author-settable, no forced default — the backend's own HAWKEYE
+            // column default applies when omitted, same as before this field
+            // existed at all.
+            injectionType: args.injectionType,
+            // Author-settable; defaults to disabled (see tool description).
+            // Only meaningful for HAWKEYE/MSWJS/XHOOK — inert for CDP.
+            disableRequestReplay: args.disableRequestReplay ?? true,
             allowedInjectedRequestData: args.allowedInjectedRequestData
                 ? injectedRequestDataFrom(args.allowedInjectedRequestData)
                 : undefined
@@ -468,11 +453,12 @@ export function createVersionFromCaptureTool(client, attachRef) {
                     'every page load (before navigating to initialUrl), matching ' +
                     'the builder\'s jsUserScripts.');
             }
-            // disableRequestReplay is honored ONLY on add-version, so a
-            // register can't set it — when true we immediately follow the
-            // register with an add-version call (which also lands any other
-            // register-ignored fields).
-            const followUp = args.disableRequestReplay === true;
+            // disableRequestReplay is honored ONLY on add-version — so every
+            // register is immediately followed by an add-version call that
+            // actually applies it (whatever value — default or author-set;
+            // which also lands an explicit injectionType, when passed —
+            // unverified whether register persists it — and any other
+            // register-ignored fields the caller passed).
             const REGISTER_IGNORED_KEYS = [
                 'allowedInjectedRequestData',
                 'useIncognitoWebview',
@@ -484,38 +470,55 @@ export function createVersionFromCaptureTool(client, attachRef) {
                 notes.push(`${ignoredOnRegister.join(', ')} ` +
                     `${ignoredOnRegister.length > 1 ? 'are' : 'is'} ` +
                     'ignored on register (no providerId) — the devtools backend only ' +
-                    'reads them when adding a version. ' +
-                    (followUp
-                        ? 'They were applied by the follow-up version the tool ' +
-                            'created to set disableRequestReplay.'
-                        : 'Publish once to create the provider, then call this ' +
-                            'again WITH the returned providerId to set them.'));
+                    'reads them when adding a version. They were applied by the ' +
+                    'automatic follow-up version this tool always creates to apply ' +
+                    'disableRequestReplay.');
             }
             const body = providerToRegisterBody(providers, opts);
             const registered = await client.registerProvider(body);
-            if (followUp) {
-                const newProviderId = extractProviderId(registered);
-                if (newProviderId) {
+            const newProviderId = extractProviderId(registered);
+            if (newProviderId) {
+                // The provider already exists as of the register call above —
+                // a failure past this point must NOT reject the tool and
+                // discard `registered`/`newProviderId`, or a retry without
+                // `providerId` would register a DUPLICATE provider. Catch and
+                // warn instead, telling the caller to resume WITH this
+                // providerId.
+                try {
                     const versionsResp = await client.listVersions(newProviderId);
                     const followVersion = bumpPatchString(extractVersions(versionsResp));
-                    const configBody = providerToConfigBody(providers, { ...opts, disableRequestReplay: true }, followVersion, DEFAULT_VERSION_INFO);
+                    const configBody = providerToConfigBody(providers, opts, followVersion, DEFAULT_VERSION_INFO);
                     await client.updateProviderConfig(newProviderId, configBody);
-                    notes.push('disableRequestReplay is ignored by the register endpoint — ' +
-                        `applied it via a follow-up version (${followVersion}) on ` +
-                        'the new provider, which also lands any register-ignored ' +
-                        'fields you passed.');
+                    notes.push(`Created an automatic follow-up version (${followVersion}) to ` +
+                        `apply disableRequestReplay (${opts.disableRequestReplay})` +
+                        (opts.injectionType !== undefined
+                            ? ` and set injectionType (${opts.injectionType})`
+                            : '') +
+                        ' — the register endpoint ignores/may ignore those fields, so ' +
+                        'every fresh register gets one. It also landed any other ' +
+                        'register-ignored fields you passed.');
                 }
-                else {
-                    notes.push('Could not apply disableRequestReplay: the register ' +
-                        'response did not include the new providerId. Call this ' +
-                        'tool again WITH `providerId` and `disableRequestReplay: ' +
-                        'true` to set it.');
+                catch (err) {
+                    const detail = isBoom(err) ? err.message : String(err);
+                    notes.push(`Provider ${newProviderId} WAS created, but the automatic ` +
+                        `follow-up version (to force-disable document replay${opts.injectionType !== undefined
+                            ? ' and set injectionType'
+                            : ''}) failed: ${detail}. Do NOT retry without providerId — that ` +
+                        'would register a duplicate. Instead, re-run ' +
+                        'create_provider_version_from_capture WITH ' +
+                        `providerId: "${newProviderId}" to add the follow-up version.`);
                 }
             }
+            else {
+                notes.push('Could not apply disableRequestReplay: the ' +
+                    'register response did not include the new providerId. Call ' +
+                    'this tool again WITH `providerId` to create a version that ' +
+                    'applies them.');
+            }
             return withNotes(registered);
         }
         // New version of an existing provider — pick the next patch above
-        // the highest existing version. A provider you don't own (e.g. a
+        // the highest existing version. A provider you don't own (for example, a
         // public one) fails here with 401/403/404; surface the register-a-copy
         // workaround instead of a bare permission error.
         const providerId = args.providerId;

package/lib/old/tools/update-provider-metadata.d.ts

@@ -7,7 +7,7 @@ import type { ReclaimOldClient } from '../client.ts';
  * `create_provider_version_from_capture` paths: it does NOT touch
  * `providerConfig`/versions at all, and only the fields you pass here
  * change — everything else on the provider is left untouched (no need to
- * re-supply `requestData`/`customInjection`/etc., and
+ * re-supply `requestData`/`customInjection`, and so on, and
  * no new version is created).
  *
  * The backend 403s if you don't own the provider (and aren't an admin) —

package/lib/old/tools/update-provider-metadata.js

@@ -6,7 +6,7 @@ import { defineTool } from "../../mcp/server.js";
  * `create_provider_version_from_capture` paths: it does NOT touch
  * `providerConfig`/versions at all, and only the fields you pass here
  * change — everything else on the provider is left untouched (no need to
- * re-supply `requestData`/`customInjection`/etc., and
+ * re-supply `requestData`/`customInjection`, and so on, and
  * no new version is created).
  *
  * The backend 403s if you don't own the provider (and aren't an admin) —

package/lib/old/tools/verify-sdk-setup.js

@@ -101,7 +101,7 @@ export function verifySdkSetupTool(client) {
                 : 'PUBLIC_URL not set — fine if you only read the proof from the ' +
                     'frontend flow, but the async webhook callback needs a ' +
                     'publicly-reachable URL or it will never fire. Get one via a ' +
-                    'tunnel (e.g. `ngrok http <port>`) or by deploying to a ' +
+                    'tunnel (for example, `ngrok http <port>`) or by deploying to a ' +
                     'dev/staging server you already have — ask the user which they ' +
                     'prefer.',
         });

package/lib/proof/attestor.d.ts

@@ -24,13 +24,13 @@ export interface RunAttestorProofOptions {
     /** When resolving the key from env/.env/file, the address the caller expects
      *  to sign with (sanity check). Ignored when `ownerPrivateKey` is given. */
     ownerAddress?: string;
-    /** Sign with this key directly (e.g. the app/VC's ephemeral per-session key)
-     *  instead of resolving from env/.env/file. */
+    /** Sign with this key directly (for example, the app or VC's ephemeral
+     *  per-session key) instead of resolving from env/.env/file. */
     ownerPrivateKey?: string;
     /** ZK engine for `createClaimOnAttestor`. Defaults to `'stwo'` — a pure-WASM
      *  prover that runs everywhere (no native shared library, so it works on
      *  Windows where `'gnark'` fails to load its `.dll`). Server-side paths that
-     *  want gnark's speed pin it explicitly (e.g. the verify runner). */
+     *  want gnark's speed pin it explicitly (for example, the verify runner). */
     zkEngine?: 'gnark' | 'snarkjs' | 'stwo';
     /** Extract the structured {@link AttestorClaim} (claim + attestor signature)
      *  onto the result for nested-proof construction. */