@reclaimprotocol/agent 0.1.14 → 0.1.17

package/lib/tools/registry.js

@@ -1,3 +1,17 @@
+/**
+ * The ONE tool primitive for the agent. A tool is authored once with
+ * {@link defineTool} — `{ definition, handler }`, where the handler receives
+ * args already parsed + validated against the definition's JSON Schema (via
+ * zod), so the schema shown to the model and the validation applied to inbound
+ * args cannot drift.
+ *
+ * This lives outside `mcp/` on purpose: it depends only on zod (NOT the MCP
+ * SDK), so non-MCP consumers — the cloud authoring loop — can author and run
+ * these tools without pulling in `@modelcontextprotocol/sdk`. The MCP-specific
+ * glue (`registerToolList` onto an `McpServer`) stays in `mcp/server.ts`, which
+ * re-exports this primitive for the MCP-side tool files.
+ */
+import { isBoom } from '@hapi/boom';
 import { toZod } from "../mcp/api/to-zod.js";
 /**
  * Define a tool with a single inputSchema (JSON Schema) as the source of truth.
@@ -15,6 +29,18 @@ export function defineTool(definition, handler) {
         },
     };
 }
+/**
+ * Render a tool-handler error as the text every host shows the LLM.
+ * Boom errors carrying an RFC 9457 problem include its `detail`; anything
+ * else falls back to the plain message.
+ */
+export function errorAsToolText(err) {
+    if (isBoom(err) && err.output?.statusCode) {
+        const detail = err.data?.detail;
+        return detail ? `${err.message}: ${detail}` : err.message;
+    }
+    return err instanceof Error ? err.message : String(err);
+}
 /**
  * Adapt a tool to a host by WIDENING its input schema — add properties, mark
  * some required, optionally override the description — without touching the
@@ -30,6 +56,9 @@ export function extendTool(tool, extra) {
         ...(base.inputSchema.required ?? []),
         ...(extra.required ?? []),
     ];
+    // The merged `properties` spread carries the base's untyped property values,
+    // which don't structurally match ObjectSchema's strict per-property schema
+    // type — assert the merged shape.
     const inputSchema = {
         ...base.inputSchema,
         properties: {

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.14",
+	"version": "0.1.17",
 	"description": "Reclaim Protocol's tools for agents — Reclaim Protocol lets your app verify **data points** about its users — a follower count, an account balance, an order history. This package gives your AI coding agent the tools to **find, build, test and fix the _data verification providers_** (the recipes that verify a data point) by inspecting and replaying captured requests, checking sessions, evaluate proofs, publishing updates, and much more.",
 	"type": "module",
 	"main": "./lib/index.js",
@@ -33,7 +33,6 @@
 		}
 	},
 	"bin": {
-		"reclaim": "./lib/cli.js",
 		"reclaim-mcp-server": "./lib/mcp-bin.js"
 	},
 	"files": [
@@ -45,7 +44,7 @@
 		"README.md"
 	],
 	"engines": {
-		"node": ">=20"
+		"node": ">=22.0.0"
 	},
 	"repository": {
 		"url": "https://github.com/reclaimprotocol/builder",
@@ -53,12 +52,11 @@
 	},
 	"websiteUrl": "https://docs.reclaimprotocol.org",
 	"scripts": {
-		"build": "tsc && node scripts/prepend-shebang.js && chmod 755 lib/cli.js lib/mcp-bin.js",
+		"build": "tsc && node scripts/prepend-shebang.js && chmod 755 lib/mcp-bin.js",
 		"prepublishOnly": "npm run build",
 		"dev": "tsc --watch",
-		"test": "node --env-file=.test.env --test tests/*.test.ts",
+		"test": "node --env-file=.test.env --test-timeout=120000 --test tests/*.test.ts",
 		"check": "tsc -p tsconfig.test.json",
-		"start:cli": "node lib/cli.js",
 		"start:mcp": "node lib/mcp-bin.js",
 		"inspect": "npx @modelcontextprotocol/inspector node lib/mcp-bin.js",
 		"download:zk-files": "node scripts/download-zk-files.js"
@@ -67,7 +65,6 @@
 		"mcp",
 		"model-context-protocol",
 		"sdk",
-		"cli",
 		"ai",
 		"agent",
 		"chrome-devtools-protocol",
@@ -86,7 +83,7 @@
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@noble/hashes": "^2.2.0",
 		"@reclaimprotocol/attestor-core": "^5.0.8",
-		"@reclaimprotocol/client": "0.1.14",
+		"@reclaimprotocol/client": "0.1.17",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"domhandler": "^6.0.0",

package/scripts/prepend-shebang.js

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url'
 
 const SHEBANG = '#!/usr/bin/env node\n'
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
-const BIN_FILES = ['cli.js', 'mcp-bin.js']
+const BIN_FILES = ['mcp-bin.js']
 
 for(const file of BIN_FILES) {
 	const path = join(ROOT, 'lib', file)

package/skill/injection-api.md

@@ -133,13 +133,104 @@ field isn't touched by `create_provider_version_from_capture` at all).
 ## `bodySniff` — unrelated to the above
 
 A per-request field (sits next to `url`/`method` on each `requestData` entry,
-not a version-level setting): `{ enabled: boolean, template: string }`. Per
-the InApp SDK's own type comment, it's "the template used for matching and
-extracting params from `requestBody`" — the REQUEST-body counterpart of
-`responseMatches`/`responseRedactions`, which only ever look at the response.
-It applies regardless of `injectionType`/`interceptorType`. Both publish
-tools in this package already set it for you from `provider.body` — you
-should not need to touch it directly.
+not a version-level setting): `{ enabled: boolean, template: string }`.
+
+**`bodySniff.enabled` should be `true` whenever the request HAS a body at
+all** — this isn't a special case reserved for dynamic bodies. Only skip it
+(leave `enabled: false` / template empty) when the request genuinely sends
+no body (typically a GET). Both publish tools in this package already set
+`enabled`/`template` for you from `provider.body` for a normal
+capture-and-replay provider — you don't need to touch it directly there.
+Read the rest of this section if you're authoring a claim via live
+interception (`window.Reclaim.requestClaim`) whose body isn't simply the
+one literal string you captured once — most commonly because some SMALL
+part of it is dynamic per user/run (e.g. a user id, not necessarily the
+whole payload).
+
+**What actually gets hashed.** Confirmed directly from attestor-core
+(`hashProviderParams` in `@reclaimprotocol/attestor-core`): the claim/spec
+hash is `keccak256(canonicalStringify({ url, method, body, responseMatches,
+responseRedactions }))`, where `body` is whatever plain string sits in
+`params.body` — attestor-core does **no** template resolution, substitution,
+or `{{}}`-stripping on it; it hashes exactly the string it's given, verbatim.
+`bodySniff` as a concept (the `{enabled, template}` wrapper) doesn't exist
+inside attestor-core at all — it's translated to a plain `body: string`
+one layer up (old-devtools' `providerUtils.ts`: `body: bodySniff.enabled ?
+bodySniff.template : ''`), and THAT literal string — including any
+unresolved `{{paramName}}` text still in it — is what reaches
+`hashProviderParams`.
+
+**The consequence — and why this differs from `templateParams`.** A live
+claim's own `body` field (submitted via `requestClaim`) can ALSO be set to
+a literal template string containing `{{paramName}}`, rather than the real
+substituted content, with the real value supplied separately as a witness
+param. Since attestor-core hashes `body` as an opaque string with no
+resolution, a claim whose `body` is the literal template `T` and a spec
+whose `body`/`bodySniff.template` is that SAME literal template `T` hash
+identically — regardless of what real value the `{{paramName}}` hole stood
+for. This is the OPPOSITE of `templateParams`/`${var}` (used in
+`responseMatches`/`responseRedactions`), which — per the JS SDK's
+`generateSpecsFromRequestSpecTemplate` — genuinely gets substituted with a
+real value at verify time before hashing. Don't conflate the two: `${var}`
+in a match/redaction template IS resolved before hashing;  `{{var}}` in a
+body template is NEVER resolved before hashing, on either side.
+
+**Practical use**: check exactly which part of the body actually changes
+across users/runs — usually it's one small field (an id, a token, a short
+list), not the whole payload. Template ONLY that minimal changing part;
+leave everything else as fixed literal text. For a body like
+`{"request":1,"type":"user_info","id":"12345"}` where only `id` varies, the
+template is `{"request":1,"type":"user_info","id":"{{REQ_BODY_USER_ID}}"}`
+— NOT e.g. `{{whole_body}}` wrapping the entire object, which would throw
+away the ability to structurally pin down everything else about the
+request. Then:
+1. In the claim you build for `requestClaim`, set `bodySniff: { enabled:
+   true, template: '{"request":1,"type":"user_info","id":"{{REQ_BODY_USER_ID}}"}' }`
+   and add a matching witness/extracted param
+   `REQ_BODY_USER_ID: theRealUserId` so the real value is still
+   independently verifiable, just not part of the hash.
+2. In the corresponding `allowedInjectedRequestData` entry, set `body` to
+   that EXACT SAME literal template string (byte-for-byte, same
+   `{{REQ_BODY_USER_ID}}` placeholder, same everything else) — NOT a
+   `${var}` substitution, since `body` doesn't go through that substitution
+   step.
+3. Before publishing, sanity-check by hand that
+   `template.replace('{{REQ_BODY_USER_ID}}', 'a real sample id')`
+   reproduces the real captured/expected request body byte-for-byte — if it
+   doesn't (extra whitespace, different key order, a field that turned out
+   to ALSO vary but wasn't templated, etc.), the hashes won't match either,
+   since the SPEC side uses the literal template as-is and the real claim's
+   body must independently be built to match that same shape when the
+   placeholder(s) are filled in. If MULTIPLE fields vary independently,
+   template each one with its own `{{placeholder}}` and its own witness
+   param — you're not limited to one hole per template.
+
+**Fallback — whole-body placeholder.** If precise per-field templating
+keeps causing hash mismatches (e.g. more fields turn out to vary than
+expected, key order isn't stable, whitespace differs run-to-run) and you
+can't pin down every variable field individually, fall back to templating
+the ENTIRE body as one placeholder instead: `{{REQ_BODY_GRD}}`. The `GRD`
+suffix matters — per the response-matching template engine
+(`convertTemplateToRegex`), a placeholder name ending in `GRD` is treated as
+a GREEDY match (`(.*)`, matching everything including embedded delimiters)
+rather than the default non-greedy `(.*?)` (which stops at the first
+occurrence of whatever comes after it in the template) — for a placeholder
+covering the entire remaining body with nothing fixed after it, greedy is
+what you want. This is strictly a fallback: it means NOTHING about the
+body's structure is pinned down by the hash anymore (any body at all would
+hash the same), so prefer the minimal-placeholder approach above whenever
+you can actually identify which fields vary.
+
+Caveat: I confirmed `hashProviderParams` treats `body` as an opaque string
+with no `{{}}` resolution directly from the attestor-core bundle shipped in
+this repo's `node_modules`. I did NOT find, in this same bundle, the code
+path that actually invokes `hashProviderParams` against a live submitted
+claim to gate proof acceptance — that caller lives elsewhere (the mobile/
+InApp SDK client and/or a server-side verifier not checked into this repo).
+So this is strong but not 100% end-to-end-traced confirmation; treat it as
+"very likely correct, empirically consistent with real proof/verifyProof
+behavior observed in practice" rather than "certain from first-hand
+tracing of the whole call chain."
 
 ## Recognizing this on a provider you didn't author
 

package/src/authoring/index.ts

@@ -14,6 +14,7 @@ export { authoringTools } from './tools.ts'
 // subsystem.
 export {
 	defineTool,
+	errorAsToolText,
 	extendTool,
 	type RegisteredTool,
 	type ToolDefinition,

package/src/authoring/util.ts

@@ -21,6 +21,9 @@ export function objectSchema(
 	properties: Record<string, unknown>,
 	required?: string[],
 ): JSONSchema.ObjectSchema {
+	// `properties` is an untyped Record here (this is a literal shortener, not a
+	// schema validator), so it doesn't structurally match ObjectSchema's strict
+	// per-property schema type — assert the shape.
 	return {
 		type: 'object',
 		properties,

package/src/cdp/launcher.ts

@@ -113,7 +113,7 @@ export function launchChrome(opts: LaunchOptions): ChildProcess {
 export async function waitForCdpReady(
 	port: number,
 	timeoutMs = 10_000,
-): Promise<void> {
+) {
 	const deadline = Date.now() + timeoutMs
 	while(Date.now() < deadline) {
 		try {

package/src/config/store.ts

@@ -18,6 +18,10 @@ export interface ReclaimAgentConfig {
 /**
  * The single on-disk document at `~/.reclaim/config.json`. Each top-level
  * key is an independent section owned by a different subsystem:
+ *   - `mode`          — persisted backend preference (old-devtools vs builder),
+ *                       set via the `set_devtools_mode` tool. Applied at server
+ *                       start; an explicit `USE_OLD_DEVTOOLS` env var overrides
+ *                       it (see `resolveOldMode` in consts.ts).
  *   - `browser_agent` — Chrome attach mode/port (the agent tools)
  *   - `session`       — the auth bearer token (authenticate)
  *   - `old_devtools`  — externally-supplied identity for OLD-devtools mode
@@ -32,11 +36,15 @@ export interface ReclaimAgentConfig {
  */
 export interface ReclaimConfig {
 	version: 1
+	mode?: DevtoolsMode
 	browser_agent?: ReclaimAgentConfig
 	session?: CachedSession
 	old_devtools?: OldIdentity
 }
 
+/** Which backend the MCP server targets. See `resolveOldMode` in consts.ts. */
+export type DevtoolsMode = 'old' | 'builder'
+
 /**
  * Read/write the unified Reclaim config document. The file holds the
  * (short-lived) session bearer token, so it is always locked to `0600` and

package/src/consts.ts

@@ -72,6 +72,30 @@ export function useOldDevtools(): boolean {
 	return (process.env.USE_OLD_DEVTOOLS ?? '').trim().toLowerCase() !== 'false'
 }
 
+/** True when `USE_OLD_DEVTOOLS` is set to a non-empty value (explicit). */
+function oldDevtoolsEnvSet(): boolean {
+	return (process.env.USE_OLD_DEVTOOLS ?? '').trim() !== ''
+}
+
+/**
+ * Effective mode, layering the persisted preference under the env var:
+ * explicit `USE_OLD_DEVTOOLS` wins → persisted config `mode` → default (old).
+ * The persisted value comes from `~/.reclaim/config.json` (set via the
+ * `set_devtools_mode` tool); the caller reads it so this module needn't import
+ * `ConfigStore` (which would create an import cycle).
+ */
+export function resolveOldMode(persisted?: 'old' | 'builder'): boolean {
+	if(oldDevtoolsEnvSet()) {
+		return useOldDevtools()
+	}
+
+	if(persisted) {
+		return persisted === 'old'
+	}
+
+	return true
+}
+
 // ---------------------------------------------------------------------------
 // Chrome / CDP launcher.
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -1,5 +1,5 @@
 // Package entry — SDK re-exports + agent public API.
-// The CLI lives at ./cli.ts, the MCP server bin at ./mcp-bin.ts.
+// The MCP server bin lives at ./mcp-bin.ts.
 
 // SDK — re-export everything from @reclaimprotocol/client so consumers
 // only need one package for both the typed HTTP client and the agent tools.