@reclaimprotocol/agent 0.1.22 → 0.1.24

package/src/provider/matcher.ts

@@ -54,7 +54,7 @@ export function synthesizeMatcher(
 			'OPRF hashing requires a target with a known-safe character class '
 			+ '(digits, slug, or email). '
 			+ `Got "${target}" which is free-form. Use a tighter target `
-			+ '(e.g. just the alphanumeric portion of the value) '
+			+ '(for example, just the alphanumeric portion of the value) '
 			+ 'or call propose_provider without `hash`.',
 		)
 	}
@@ -171,7 +171,7 @@ function jsonMatcher(
 		return undefined
 	}
 
-	const anchor = jsonKeyPrefix(body, target)
+	const anchor = jsonKeyPrefix(body, target, lastPathKey(jsonPath))
 	if(!anchor) {
 		return undefined
 	}
@@ -182,15 +182,34 @@ function jsonMatcher(
 	)
 }
 
+/** The trailing object-property name of a jsonPath (`$.total_records` →
+ *  `"total_records"`), or undefined for an array-index/bracket leaf, which
+ *  has no literal key to anchor a search on. */
+function lastPathKey(jsonPath: string | undefined): string | undefined {
+	const m = jsonPath ? /\.([A-Za-z_][A-Za-z0-9_]*)$/.exec(jsonPath) : null
+	return m?.[1]
+}
+
 /**
  * The literal `"key":"` (or `"key":` for a raw number/bool) immediately before
  * `target` in `text`, plus the closing quote (`"` for a string value, `''`
  * otherwise). Returns undefined when the value isn't preceded by a JSON key.
+ *
+ * When `key` is given, anchors the search on occurrences of the KEY (not the
+ * value) — so a short/common value elsewhere in the body (for example, the
+ * digit "5" inside `"investment_amount":354.85`) can't be mistaken for this
+ * field. Only falls back to a whole-body value search when there's no
+ * resolvable key (for example, `findJsonPath` returned an array-index leaf).
  */
 function jsonKeyPrefix(
 	text: string,
 	target: string,
+	key?: string,
 ): { prefix: string, close: string } | undefined {
+	if(key !== undefined) {
+		return jsonKeyPrefixByKey(text, target, key)
+	}
+
 	const { idx } = firstIndex(text, target)
 	if(idx < 0) {
 		return undefined
@@ -227,6 +246,78 @@ function jsonKeyPrefix(
 	return { prefix: text.slice(keyStart, idx), close: quoted ? '"' : '' }
 }
 
+/** `jsonKeyPrefix`'s key-anchored path: scan occurrences of `"key"`, and for
+ *  each, check whether the value that follows its `:` matches `target` (or a
+ *  normalized candidate) before accepting it. */
+function jsonKeyPrefixByKey(
+	text: string,
+	target: string,
+	key: string,
+): { prefix: string, close: string } | undefined {
+	const keyToken = `"${key}"`
+	let from = 0
+	for(;;) {
+		const keyIdx = text.indexOf(keyToken, from)
+		if(keyIdx < 0) {
+			return undefined
+		}
+
+		from = keyIdx + keyToken.length
+		let i = from
+		while(i < text.length && /\s/.test(text[i] ?? '')) {
+			i++
+		}
+
+		if(text[i] !== ':') {
+			continue
+		}
+
+		i++
+		while(i < text.length && /\s/.test(text[i] ?? '')) {
+			i++
+		}
+
+		const matched = matchJsonValueAt(text, i, target)
+		if(matched) {
+			return {
+				prefix: text.slice(keyIdx, matched.valueStart),
+				close: matched.close,
+			}
+		}
+	}
+}
+
+/** Whether the JSON value starting at `pos` in `text` — quoted string or a
+ *  raw number/bool/null token — equals `target` (or a normalized candidate).
+ *  Returns the position right after any opening quote (matching `firstIndex`'s
+ *  convention) and the delimiter to close the match template with. */
+function matchJsonValueAt(
+	text: string,
+	pos: number,
+	target: string,
+): { valueStart: number, close: string } | undefined {
+	const candidates = [target, ...normalizeCandidates(target)]
+	if(text[pos] === '"') {
+		let j = pos + 1
+		while(j < text.length && text[j] !== '"') {
+			j += text[j] === '\\' ? 2 : 1
+		}
+
+		const raw = text.slice(pos + 1, j)
+		return candidates.includes(raw)
+			? { valueStart: pos + 1, close: '"' }
+			: undefined
+	}
+
+	let j = pos
+	while(j < text.length && !/[,}\]\s]/.test(text[j] ?? '')) {
+		j++
+	}
+
+	const raw = text.slice(pos, j)
+	return candidates.includes(raw) ? { valueStart: pos, close: '' } : undefined
+}
+
 function findJsonPath(body: string, target: string): string | undefined {
 	let parsed: unknown
 	try {
@@ -320,7 +411,9 @@ function htmlMatcher(
 	const scriptJson = scriptJsonContent(revealSlice)
 	if(scriptJson) {
 		const jsonPath = findJsonPath(scriptJson, target)
-		const kp = jsonPath ? jsonKeyPrefix(scriptJson, target) : undefined
+		const kp = jsonPath
+			? jsonKeyPrefix(scriptJson, target, lastPathKey(jsonPath))
+			: undefined
 		if(jsonPath && kp) {
 			return keyValueResult(
 				kp.prefix, kp.close, target, paramName, valueClass,
@@ -404,9 +497,9 @@ function portableWindow(
 /** Value is element text content. Left anchor: if only punctuation/whitespace
  *  sits between the opening tag and the value, fold the stable opening tag in;
  *  but if WORDS precede the value in the same text node they may be per-user
- *  (e.g. `<li>Full Name ( {{id}} )` — the name), so drop through the last
- *  alphanumeric and keep only the trailing punctuation as the anchor. Right:
- *  include a closing tag, but stop at a sibling. */
+ *  (for example, `<li>Full Name ( {{id}} )` — the name), so drop through the
+ *  last alphanumeric and keep only the trailing punctuation as the anchor.
+ *  Right: include a closing tag, but stop at a sibling. */
 function textWindow(
 	markup: string,
 	valueIdx: number,
@@ -550,7 +643,7 @@ function contentMatcher(
 		return {
 			match: {
 				type: 'contains',
-				value: buildContextualTemplate(body, target, paramName),
+				value: buildContextualTemplate(body, target, paramName, valueClass),
 			},
 			redaction,
 			paramValues: { [paramName]: target },
@@ -577,18 +670,63 @@ function contentMatcher(
  * must CONTAIN the match template (buildContextualTemplate), so the trailing
  * delimiter is kept unless it's whitespace (which the template also drops).
  */
+/** Indices where `cand` occurs in `body` as a WHOLE match of `valueClass` —
+ * that is, not a substring inside a longer run of the same class (the digit "5"
+ * inside "354.85" is never a whole `\d+` match; "354" and "85" are). Only
+ * meaningful for a structural (non-free-form) class. */
+function wholeTokenIndices(
+	body: string,
+	cand: string,
+	valueClass: string,
+): number[] {
+	const indices: number[] = []
+	let re: RegExp
+	try {
+		re = new RegExp(valueClass, 'g')
+	} catch{
+		return indices
+	}
+
+	let m: RegExpExecArray | null
+	while((m = re.exec(body))) {
+		if(m[0] === cand) {
+			indices.push(m.index)
+		}
+
+		if(re.lastIndex === m.index) {
+			re.lastIndex++
+		}
+	}
+
+	return indices
+}
+
 function buildContentRegex(
 	body: string,
 	target: string,
 	paramName: string,
 	valueClass: string,
 ): string | undefined {
+	const structural = inferValueClass(target) !== undefined
 	for(const cand of normalizeCandidates(target)) {
-		const idx = body.indexOf(cand)
+		const occurrences = structural
+			? wholeTokenIndices(body, cand, valueClass)
+			: undefined
+		const idx = occurrences ? occurrences[0] ?? -1 : body.indexOf(cand)
 		if(idx < 0) {
 			continue
 		}
 
+		if(occurrences && occurrences.length > 1
+			&& cand.replace(/[^A-Za-z0-9]/g, '').length < 4) {
+			throw new Error(
+				`target value "${target}" occurs ${occurrences.length} times as a `
+				+ 'standalone token with no JSON key or HTML anchor to '
+				+ "disambiguate — capture a request where it's unique, or use a "
+				+ 'longer/more specific target.',
+			)
+		}
+
 		const endIdx = idx + cand.length
 		const rawRight = findRightContext(body, endIdx)
 		const right = /^\s/.test(rawRight) ? '' : escapeRegexFlexWs(rawRight)
@@ -624,8 +762,10 @@ function buildContextualTemplate(
 	body: string,
 	target: string,
 	paramName: string,
+	valueClass: string,
 ): string {
-	const idx = body.indexOf(target)
+	const idx = wholeTokenIndices(body, target, valueClass)[0]
+		?? body.indexOf(target)
 	if(idx < 0) {
 		return `{{${paramName}}}`
 	}
@@ -719,7 +859,8 @@ function inferValueClass(target: string): string | undefined {
 		return '\\d+'
 	}
 
-	// Numbers with thousands separators / decimals, e.g. "1,908" or "12,345.6".
+	// Numbers with thousands separators / decimals, for example, "1,908" or
+	// "12,345.6".
 	if(/^[0-9][0-9,.]*[0-9]$/.test(target)) {
 		return '[0-9,.]+'
 	}

package/src/provider/secrets.ts

@@ -126,9 +126,9 @@ export function secretUrlCharBudget(
 }
 
 /** A `paramValues`/context key is secret iff its name contains `SECRET`
- *  (case-insensitive) — e.g. `SECRET_apiKey`, `context.SECRET_apiKey`. Same
- *  naming-convention classifier reclaim-inapp-sdk and reclaim-portal use for
- *  their `witnessParams`/`paramValues` maps (no separate boolean flag). */
+ *  (case-insensitive) — for example, `SECRET_apiKey`, `context.SECRET_apiKey`.
+ *  Same naming-convention classifier reclaim-inapp-sdk and reclaim-portal use
+ *  for their `witnessParams`/`paramValues` maps (no separate boolean flag). */
 export function classifyParamName(name: string): boolean {
 	return name.toUpperCase().includes('SECRET')
 }

package/src/provider/to-version.ts

@@ -41,14 +41,14 @@ export interface DraftRequest {
  *  pagination/optionality flags of `RequestSelectionTemplate`. Reuses the
  *  shared `DraftRequest` shape — no provider `name`/`paramValues` required. */
 export interface AllowedJsRequest extends DraftRequest {
-	/** Allow the template to match many requests (e.g. pagination). Default
-	 *  true. */
+	/** Allow the template to match many requests (for example, pagination).
+	 *  Default true. */
 	multiple?: boolean
 	/** Fail validation if no request matches this template. Default true. */
 	required?: boolean
 	/** Names of `${var}` placeholders in this template's `responseMatches`/
 	 *  `responseRedactions` that get substituted at verify time from the
-	 *  submitted proof's own witness params (e.g. an index list a
+	 *  submitted proof's own witness params (for example, an index list a
 	 *  `Reclaim.requestClaim` call attached alongside its `{{var}}`
 	 *  extractions). Omit (or leave empty) when the template has no such
 	 *  placeholders — verification then matches it literally as-is. */
@@ -69,15 +69,18 @@ export interface CreateVersionOptions {
 	jsUserScripts?: string
 	/** Requests the injection script may fire, as `RequestSelectionTemplate`s. */
 	allowedJsRequests?: AllowedJsRequest[]
-	/** In-app interception options, mapped verbatim to
-	 *  `webSettings.clientOptions.inapp.interceptorOptions`. `interceptorType`
-	 *  is required by the backend whenever the object is present.
-	 *  `isDocumentRequestReplayEnabled` is the INVERSE of old-devtools'
-	 *  `disableRequestReplay` (default false). */
+	/** In-app interception options, mapped to
+	 *  `webSettings.clientOptions.inapp.interceptorOptions` — ONLY when this
+	 *  is explicitly passed (builder's schema has no `NONE` interceptorType;
+	 *  omitting `inapp` entirely IS the "no interception" signal, so omitting
+	 *  this must omit `inapp`, not default it to HAWKEYE). When it IS passed,
+	 *  `isDocumentRequestReplayEnabled` defaults to `false` (disabled) unless
+	 *  explicitly overridden here — see `providerToCreateVersionRequest`. Only
+	 *  meaningful for `HAWKEYE`/`MSWJS`; inert for `CDP`. */
 	interceptorOptions?: {
 		interceptorType: 'HAWKEYE' | 'MSWJS' | 'CDP'
-		isDocumentRequestReplayEnabled?: boolean
 		interceptorSettings?: string
+		isDocumentRequestReplayEnabled?: boolean
 	}
 }
 
@@ -240,14 +243,28 @@ export function providerToCreateVersionRequest(
 			geoLocation: pickGeoLocation(providers),
 			clientOptions: {
 				portal: { useProxy: true },
+				// Builder's schema has NO "NONE" interceptorType — the real
+				// no-interception signal is OMITTING `inapp` entirely (it's not
+				// `required` on `InAppClientOptions`). So `inapp` is only built at
+				// ALL when the author explicitly opts into a real interceptorType;
+				// omitting `interceptorOptions` must omit `inapp` too, or every
+				// standard (non-interception) provider would incorrectly publish
+				// as HAWKEYE. Within that block, `isDocumentRequestReplayEnabled`
+				// defaults to disabled but is author-overridable — see
+				// `CreateVersionOptions.interceptorOptions`'s doc comment.
 				...(interceptorOptions
 					? {
 						inapp: {
 							interceptorOptions: {
-								// openapi `default: false` — the generated type
-								// requires the key even when the author omits it.
-								isDocumentRequestReplayEnabled: false,
-								...interceptorOptions,
+								interceptorType: interceptorOptions.interceptorType,
+								isDocumentRequestReplayEnabled:
+									interceptorOptions.isDocumentRequestReplayEnabled ?? false,
+								...(interceptorOptions.interceptorSettings
+									? {
+										interceptorSettings:
+											interceptorOptions.interceptorSettings,
+									}
+									: {}),
 							},
 						},
 					}

package/src/tools/registry.ts

@@ -70,11 +70,11 @@ export function errorAsToolText(err: unknown): string {
 /**
  * Adapt a tool to a host by WIDENING its input schema — add properties, mark
  * some required, optionally override the description — without touching the
- * handler. A host maps whichever shared tools it needs through this (e.g. the
- * MCP adds its `captureId` session handle + the credential-aware `run_proof`
- * contract). Args parse loosely, so the extra fields flow through to the
- * handler (its backend resolver reads them); the base tool stays untouched for
- * hosts that don't need them.
+ * handler. A host maps whichever shared tools it needs through this (for
+ * example, the MCP adds its `captureId` session handle + the credential-aware
+ * `run_proof` contract). Args parse loosely, so the extra fields flow through
+ * to the handler (its backend resolver reads them); the base tool stays
+ * untouched for hosts that don't need them.
  */
 export function extendTool(
 	tool: RegisteredTool,