@reclaimprotocol/agent 0.1.18 → 0.1.20

package/skill/injection-api.md

@@ -221,16 +221,101 @@ 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."
+The same opaque-string hashing (confirmed directly from the attestor-core
+bundle shipped in this repo's `node_modules`) also applies to fields beyond
+`body`. The caller that invokes it against a live submitted claim to gate
+proof acceptance is `@reclaimprotocol/js-sdk`'s `verifyProof` — the next
+section covers how that gate works and how to configure a provider that
+satisfies it.
+
+## Provider-hash validation (`verifyProof(proof, { providerId })`) — how it gates, and how to configure a provider that passes it
+
+The caller for the hashing described above is `@reclaimprotocol/js-sdk`'s
+`verifyProof`. When called with `{ providerId }` (the SDK's own
+integration guide treats this as the normal case), traced directly from
+that package's source (`src/utils/proofValidationUtils.ts`,
+`src/utils/providerUtils.ts`, `src/witness.ts`):
+
+1. `assertValidateProof` → `fetchProviderHashRequirementsBy(providerId, …)`
+   fetches this provider's CURRENT PUBLISHED CONFIG and builds a list of
+   "expected hashes" — one per entry in `requestData` PLUS one per entry in
+   `allowedInjectedRequestData` (old-devtools) / `allowedJsRequests`
+   (builder) — same concept, different field name per backend; don't
+   assume a doc or error naming one applies verbatim to the other.
+2. Each expected hash is `hashRequestSpec` → `hashProofClaimParams({ url,
+   method, body, responseMatches, responseRedactions })` — the SAME
+   opaque-string hashing described above for `body`, applied to the WHOLE
+   spec at once.
+3. The REAL submitted proof's own `claimData.parameters` is hashed the
+   SAME way, with `isOptional`-driven 2^N combinatorial expansion over
+   `responseMatches`/`responseRedactions` PAIRS so an optional field can be
+   either present or absent (`getProviderParamsAsCanonicalizedString`) —
+   but this expansion ONLY touches match/redaction pairs, never `url`.
+4. `assertValidProofsByHash` requires the real proof's hash to exactly
+   equal ONE expected hash. No match → `verifyProof` rejects, even for a
+   perfectly valid, correctly-signed proof whose `responseMatches` are
+   100% correct in shape.
+
+**Key constraint: `url` is hashed VERBATIM, with ZERO template/regex
+resolution — even when `urlType` is `REGEX` or `TEMPLATE`.** Confirmed
+directly from `generateSpecsFromRequestSpecTemplate` (the function that DOES
+resolve `${var}` placeholders in `responseMatches`/`responseRedactions`
+before hashing): it spreads every other field from the template unchanged,
+and never touches `url`. `urlType` is consumed by a DIFFERENT validation
+path entirely (matching an incoming live request against this spec at
+capture time) — never by this hash computation.
+
+**Check this before populating `allowedInjectedRequestData`/
+`allowedJsRequests` for a `verifyProof({ providerId })` use case:** if the
+real captured request URL contains ANY component that varies between two
+otherwise-identical sessions — a tracking nonce, a CSRF token, a
+cache-busting timestamp, a per-request trace id — the hash computed from
+your declared spec can NEVER equal the hash of any real future proof, no
+matter how correct `responseMatches`/`responseRedactions`/`body` are. This
+is common on JS-heavy sites: e.g. Slack regenerates `_x_id`, `_x_csid`, and
+`fp` on every single API call, so a captured `users.profile.getSections`
+URL is never identical twice, even for the same user seconds apart.
+Populating this field for such a provider is actively worse than leaving
+it empty — it converts "no provider-hash check was attempted" into
+"`verifyProof({ providerId })` rejects every real proof from this
+provider, unconditionally."
+
+**Verify before wiring this up**: capture the same endpoint twice, in two
+separate sessions (ideally two different users, or the same user on two
+different days), and diff the full request URL byte-for-byte.
+- Identical every time → safe to populate with `urlType: CONSTANT` and the
+  literal URL.
+- Not identical → do not populate this field expecting it to gate
+  `verifyProof({ providerId })`. There is no way to make a session-unique
+  URL satisfy this specific mechanism, on either backend — this is a
+  property of the hashing itself, not something fixable by editing
+  `responseMatches`, `responseRedactions`, or `body` more carefully. See
+  the fallback below.
+
+Also note, independent of the `url` constraint above: even with a stable URL,
+`responseMatches`/`responseRedactions` must be an EXACT structural match —
+not just similar in spirit. A provider whose extracted field SET varies
+per user (e.g. optional profile fields present for some users, absent for
+others) needs every such field marked `isOptional: true` on BOTH the match
+and its paired redaction, so the 2^N expansion produces a valid hash for
+the "field absent" case too. A field that's sometimes-present but never
+marked optional breaks the hash for any user missing it — the same failure
+mode as the `url` constraint above, just scoped to one field instead of the
+whole spec.
+
+**Fallback if provider-hash validation keeps causing problems.** Whether
+it's an unstable `url`, an un-marked optional field, or any other
+persistent hash mismatch you can't pin down — the way out on the verifying
+side is `verifyProof(proof, { dangerouslyDisableContentValidation: true })`.
+That skips step 1-4 above entirely and trusts only the attestor's
+cryptographic signature over the proof; it does NOT check that the proof's
+`url`/`method`/`body`/`responseMatches`/`responseRedactions` match anything
+you declared. A caller-supplied `{ hashes: [...] }` computed some other way
+is the alternative when you still want hash-equality enforced, just not
+derived from this provider's published config. Reach for
+`dangerouslyDisableContentValidation` deliberately, not as a silent
+default — it trades away the guarantee that the proof is shaped the way
+this provider's spec says it should be.
 
 ## Recognizing this on a provider you didn't author
 

package/skill/old-mode.md

@@ -3,14 +3,14 @@ This server is running against the devtools backend, so its capabilities are int
 **Provider-authoring flow:**
 
 1. `reclaim_authenticate` — by default opens the dashboard in Chrome, waits for you to sign in, captures the token automatically, and closes the tab (or paste a `token` / pass an eth `ethAddress` to skip the browser). Do this once before publishing or listing.
-2. `attach_chrome` → `start_capture` → drive the page (`navigate`, `wait_for_page`) → inspect (`list_requests`, `get_request`, `find_requests_containing`).
+2. `attach_browser` → `start_capture` → drive the page (`navigate`, `wait_for_page`) → inspect (`list_requests`, `get_request`, `find_requests_containing`). Browser source is independent of this publishing mode: local Chrome works as before; `builder` uses `authenticate_builder` + `list_builder_organizations` to allocate a quota-accounted Popcorn browser and returns a shareable live-view URL; `custom` accepts a caller-supplied CDP websocket.
 3. `propose_provider` to draft a provider, `replay_request` to pre-flight, `run_proof` to verify with the attestor. OPRF/`hash` redactions are optional and supported. When the data spans MULTIPLE requests (e.g. a landing call + a details call), propose + `run_proof` EACH request to get one proven draft per request.
 4. `create_provider_version_from_capture` to publish. With NO `providerId` it REGISTERS A NEW provider (re-running creates a duplicate); pass a `providerId` from `get_me_providers` to add a new version to an existing provider instead. For a MULTI-REQUEST provider, pass `providers: [draftA, draftB, …]` (every proven draft) so EACH becomes a parallel `requestData` entry on the one version — passing a single `provider` saves only that one request.
 5. `get_me_providers` lists the providers you own (the only provider-listing tool available in this mode).
 
 **Editing / new versions (ownership):** you can only add a version to a provider **you own** — the `providerId` must come from `get_me_providers`. Trying to version a public provider you don't own fails with a permission error; that is expected. To publish your own version of such a site, re-run `create_provider_version_from_capture` **without** `providerId` to register your own copy (a separate provider you own). If versioning a provider you *do* own fails, confirm you authenticated as the account that created it.
 
-Only GET/POST endpoints can be captured into providers here. There is no organization, credential-linking, or public-review workflow in this mode.
+Only GET/POST endpoints can be captured into providers here. There is no Builder organization-management, credential-linking, or public-review workflow in this mode; the narrow `authenticate_builder` and `list_builder_organizations` exception exists only to allocate Builder-hosted authoring browsers.
 
 **Diagnosing a session:** `session_analytics_logs` fetches the analytics logs for a verification session by id (from the logs service) — use it to see what happened in a session (matches, claims, failures).
 

package/src/authoring/backend.ts

@@ -71,6 +71,10 @@ export interface ProveOptions {
  * its own result, passed straight through as the tool's output.
  */
 export interface AuthoringBackend {
+	/** Ask Chrome to reject page evaluation when side effects cannot be ruled
+	 * out. Cloud authoring enables this; local MCP keeps its existing
+	 * behavior. */
+	readonly readOnlyPageEval?: boolean
 	/** Send a raw CDP command scoped to this session's page. */
 	sendCdp(method: string, params?: Record<string, unknown>): Promise<unknown>
 	/** Resolve once `method` (a CDP event) fires on this session's page, or

package/src/authoring/tools.ts

@@ -80,7 +80,10 @@ async function evalInPage(
 	expression: string,
 ): Promise<{ value?: unknown, error?: string }> {
 	const res = (await backend.sendCdp('Runtime.evaluate', {
-		expression, returnByValue: true, awaitPromise: true,
+		expression,
+		returnByValue: true,
+		awaitPromise: true,
+		...(backend.readOnlyPageEval ? { throwOnSideEffect: true } : {}),
 	})) as EvalResult
 	if(res.exceptionDetails) {
 		return {

package/src/cdp/capture.ts

@@ -4,12 +4,12 @@
  * request/response bookkeeping lives in `capture-engine.ts`, shared with the
  * app's remote-Popcorn transport.
  */
-import type CDP from 'chrome-remote-interface'
 import {
 	type CaptureSession,
 	createCaptureEngine,
 	type StartCaptureOptions,
 } from './capture-engine.ts'
+import type { CdpTabClient } from './client.ts'
 
 export {
 	isStaticAsset,
@@ -19,41 +19,41 @@ export {
 export type { CaptureSession, StartCaptureOptions } from './capture-engine.ts'
 
 export async function startCapture(
-	tab: CDP.Client,
+	tab: CdpTabClient,
 	opts: StartCaptureOptions = {},
 ): Promise<CaptureSession> {
 	const engine = createCaptureEngine({
 		...(opts.maxBodyBytes !== undefined && { maxBodyBytes: opts.maxBodyBytes }),
-		fetchBody: (requestId) => tab.Network.getResponseBody({ requestId }),
+		fetchBody: tab.getResponseBody,
 	})
 
-	const { Network } = tab
-	await Network.enable()
-
-	Network.requestWillBeSent(engine.onRequestWillBeSent)
-	// CDP intentionally omits `Cookie` (and other browser-injected headers)
-	// from `requestWillBeSent.request.headers` for privacy. The real
-	// outgoing headers — including Cookie — arrive on the matching
-	// `requestWillBeSentExtraInfo` event.
-	Network.requestWillBeSentExtraInfo(({ requestId, headers }) => {
-		engine.mergeRequestHeaders(requestId, headers)
-	})
-	Network.responseReceived(engine.onResponseReceived)
-	// Same privacy carve-out applies to `Set-Cookie` and other browser-
-	// visible response headers; they arrive on responseReceivedExtraInfo.
-	Network.responseReceivedExtraInfo(({ requestId, headers }) => {
-		engine.mergeResponseHeaders(requestId, headers)
-	})
-	Network.loadingFinished(({ requestId }) => {
-		void engine.onLoadingFinished(requestId)
-	})
+	const unsubscribe = [
+		tab.subscribe(
+			'Network.requestWillBeSent', engine.onRequestWillBeSent,
+		),
+		tab.subscribe('Network.requestWillBeSentExtraInfo', (event) => {
+			engine.mergeRequestHeaders(event.requestId, event.headers)
+		}),
+		tab.subscribe('Network.responseReceived', engine.onResponseReceived),
+		tab.subscribe('Network.responseReceivedExtraInfo', (event) => {
+			engine.mergeResponseHeaders(event.requestId, event.headers)
+		}),
+		tab.subscribe('Network.loadingFinished', (event) => {
+			void engine.onLoadingFinished(event.requestId)
+		}),
+	]
+	await tab.send('Network.enable', {})
 
 	return {
 		captureId: engine.captureId,
 		requests: engine.requests,
 		bodies: engine.bodies,
 		stop: async() => {
-			await Network.disable()
+			for(const stopListening of unsubscribe) {
+				stopListening()
+			}
+
+			await tab.send('Network.disable', {}).catch(() => {})
 		},
 	}
 }

package/src/cdp/client.ts

@@ -1,20 +1,215 @@
 import CDP from 'chrome-remote-interface'
+import assert from 'node:assert'
+import { EventEmitter } from 'node:events'
+import type {
+	RequestWillBeSentLike,
+	ResponseReceivedLike,
+} from './capture-engine.ts'
+import type { TabInfo } from './tabs.ts'
+import { listTabs } from './tabs.ts'
+
+const DIRECT_TARGET_ID = '__direct_cdp_target__'
+
+interface CdpEventMessage {
+	method: string
+	params: object
+	sessionId?: string
+}
+
+interface CdpTabEventMap {
+	'Network.requestWillBeSent': RequestWillBeSentLike
+	'Network.requestWillBeSentExtraInfo': {
+		requestId: string
+		headers: Record<string, string>
+	}
+	'Network.responseReceived': ResponseReceivedLike & {
+		response: ResponseReceivedLike['response'] & { url: string }
+	}
+	'Network.responseReceivedExtraInfo': {
+		requestId: string
+		headers: Record<string, string>
+	}
+	'Network.loadingFinished': { requestId: string }
+}
+
+export interface CdpTabClient {
+	send: (method: string, params?: object) => Promise<unknown>
+	getResponseBody: (
+		requestId: string,
+	) => Promise<{ body: string, base64Encoded: boolean }>
+	subscribe: <K extends keyof CdpTabEventMap>(
+		method: K,
+		listener: (params: CdpTabEventMap[K]) => void,
+	) => () => void
+	subscribeOnce: (method: string, listener: () => void) => () => void
+	close: () => Promise<void>
+}
 
 export interface CdpHandles {
 	/** Browser-level connection (target list, attach). */
 	browser: CDP.Client
 	/** Returns a per-target session bound to a tab. */
-	attachToTab: (targetId: string) => Promise<CDP.Client>
+	attachToTab: (targetId: string) => Promise<CdpTabClient>
+	/** Enumerate page targets without assuming a localhost discovery endpoint. */
+	listTabs: () => Promise<TabInfo[]>
 	close: () => Promise<void>
 }
 
 export async function connectCdp(port: number): Promise<CdpHandles> {
 	const browser = await CDP({ port })
+	const tabs = new Set<CdpTabClient>()
+	return {
+		browser,
+		attachToTab: async(targetId) => {
+			const tab = adaptCdpClient(await CDP({ port, target: targetId }))
+			tabs.add(tab)
+			return tab
+		},
+		listTabs: () => listTabs(port),
+		close: async() => {
+			for(const tab of tabs) {
+				await tab.close().catch(() => {})
+			}
+
+			await browser.close()
+		},
+	}
+}
+
+/** Connect to a browser-level or page-level CDP websocket. Browser-level
+ *  endpoints (including Popcorn) use flattened Target sessions; a page-level
+ *  custom endpoint is exposed as one synthetic tab and used directly. */
+export async function connectCdpUrl(webSocketUrl: string): Promise<CdpHandles> {
+	const browser = await CDP({ target: webSocketUrl, local: true })
+	let browserLevel = true
+	try {
+		await browser.send('Target.getTargets')
+	} catch{
+		browserLevel = false
+	}
+
+	const tabs = new Set<CdpTabClient>()
+	const directTab = browserLevel ? undefined : adaptCdpClient(browser)
 	return {
 		browser,
-		attachToTab: (targetId) => CDP({ port, target: targetId }),
+		listTabs: async() => {
+			if(!browserLevel) {
+				return [{
+					tabId: DIRECT_TARGET_ID, url: '', title: 'Direct CDP target',
+				}]
+			}
+
+			const { targetInfos } = await browser.send('Target.getTargets')
+			return targetInfos
+				.filter((target) => target.type === 'page')
+				.map((target) => ({
+					tabId: target.targetId,
+					url: target.url,
+					title: target.title,
+				}))
+		},
+		attachToTab: async(targetId) => {
+			if(!browserLevel) {
+				if(targetId !== DIRECT_TARGET_ID) {
+					throw new Error(`Unknown direct CDP target ${targetId}`)
+				}
+
+				assert(directTab)
+				return directTab
+			}
+
+			const { sessionId } = await browser.send('Target.attachToTarget', {
+				targetId,
+				flatten: true,
+			})
+			const tab = flattenedSessionClient(browser, sessionId)
+			tabs.add(tab)
+			return tab
+		},
 		close: async() => {
+			for(const tab of tabs) {
+				await tab.close().catch(() => {})
+			}
+
 			await browser.close()
 		},
 	}
 }
+
+/** Adapt a flattened browser Target session to the small tab-client surface
+ *  consumed by capture and authoring. Events are filtered by session id so
+ *  concurrent tabs cannot observe each other's traffic. */
+function flattenedSessionClient(
+	browser: CDP.Client,
+	sessionId: string,
+): CdpTabClient {
+	const events = new EventEmitter()
+	// The declaration only accepts literal protocol method names; this adapter
+	// deliberately forwards the shared authoring layer's dynamic method string.
+	const sender = browser.send.bind(browser) as <T>(
+		method: string, params: object, sessionId?: string,
+	) => Promise<T>
+	const onEvent = (message: CdpEventMessage) => {
+		if(message.sessionId !== sessionId) {
+			return
+		}
+
+		events.emit('event', message)
+		events.emit(message.method, message.params)
+	}
+
+	browser.on('event', onEvent)
+
+	return tabClient(events, (method, params) => {
+		return sender(method, params ?? {}, sessionId)
+	}, (requestId) => {
+		return sender<{ body: string, base64Encoded: boolean }>(
+			'Network.getResponseBody', { requestId }, sessionId,
+		)
+	}, async() => {
+		EventEmitter.prototype.removeListener.call(browser, 'event', onEvent)
+		await browser.send(
+			'Target.detachFromTarget', { sessionId },
+		).catch(() => {})
+	})
+}
+
+function adaptCdpClient(client: CDP.Client): CdpTabClient {
+	const events = new EventEmitter()
+	const onEvent = (message: CdpEventMessage) => {
+		events.emit(message.method, message.params)
+	}
+
+	client.on('event', onEvent)
+
+	// CRI intentionally types send against protocol literals. This adapter is
+	// the single boundary where shared authoring commands arrive dynamically.
+	const send = client.send.bind(client)
+	return tabClient(events, send, (requestId) => {
+		return client.send('Network.getResponseBody', { requestId })
+	}, async() => {
+		EventEmitter.prototype.removeListener.call(client, 'event', onEvent)
+		await client.close()
+	})
+}
+
+function tabClient(
+	events: EventEmitter,
+	send: CdpTabClient['send'],
+	getResponseBody: CdpTabClient['getResponseBody'],
+	close: CdpTabClient['close'],
+): CdpTabClient {
+	return {
+		send,
+		getResponseBody,
+		subscribe(method, listener) {
+			events.on(method, listener)
+			return () => events.removeListener(method, listener)
+		},
+		subscribeOnce(method, listener) {
+			events.once(method, listener)
+			return () => events.removeListener(method, listener)
+		},
+		close,
+	}
+}

package/src/mcp/api/operations.gen.ts

@@ -173,7 +173,7 @@ export const MCP_TOOLS = {
 		}),
 	},
 	"AdminSessions": {
-		description: "Explore verification sessions (admin-only)\n\nAdmin only. Search verification sessions across all organizations — paste a session id, provider id, or consumer ETH address into `q`, optionally filter by `status`. Rows link to the org-scoped session detail page (admins can open any org's pages). Capped at 100, newest first.",
+		description: "Explore verification sessions (admin-only)\n\nAdmin only. Search verification sessions across all organizations — filter by `sessionId` (prefix match, at least 5 characters), `providerId`, `claimantClientId`, `orgId` (all exact match), `status`, and a `createdAfter`/`createdBefore` time range. Rows link to the org-scoped session detail page (admins can open any org's pages). Capped at 100, newest first.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -186,7 +186,19 @@ export const MCP_TOOLS = {
 				"query": {
 					"type": "object",
 					"properties": {
-						"q": {
+						"sessionId": {
+							"type": "string",
+							"maxLength": 100
+						},
+						"providerId": {
+							"type": "string",
+							"maxLength": 100
+						},
+						"claimantClientId": {
+							"type": "string",
+							"maxLength": 100
+						},
+						"orgId": {
 							"type": "string",
 							"maxLength": 100
 						},
@@ -200,6 +212,14 @@ export const MCP_TOOLS = {
 								"error",
 								"expired"
 							]
+						},
+						"createdAfter": {
+							"type": "string",
+							"format": "date-time"
+						},
+						"createdBefore": {
+							"type": "string",
+							"format": "date-time"
 						}
 					}
 				},
@@ -623,9 +643,9 @@ export const MCP_TOOLS = {
 						},
 						"prompt": {
 							"type": "string",
-							"description": "Extraction prompt, used (and required) when `verificationType` is `llm`.",
+							"description": "Extraction prompt, used (and required) when `verificationType` is `llm`. Gated by the prompt guard before it is stored (docs/prompt-guard.md).",
 							"minLength": 0,
-							"maxLength": 1000000
+							"maxLength": 4000
 						},
 						"version": {
 							"type": "object",
@@ -2058,7 +2078,7 @@ export const MCP_TOOLS = {
 		}),
 	},
 	"ListOrgVerificationSessions": {
-		description: "List an organization's verification sessions\n\nReturns verification sessions created under the organization, newest first. Optionally filter by `providerId`, `status`, `resolvedVersion`, `claimantClientId`, and a `createdAfter`/`createdBefore` time range. Caller must be an active member of the org. Opaque cursor pagination.\n\nNote: `status` filters on the stored column. A session that has passed `expiresAt` but has not yet been swept is reported as `expired` in its body while still stored as `pending`, so `status=expired` may not match such sessions until the sweep runs.",
+		description: "List an organization's verification sessions\n\nReturns verification sessions created under the organization, newest first. Optionally filter by `sessionId` (prefix match, at least 5 characters), `providerId`, `status`, `resolvedVersion`, `claimantClientId`, and a `createdAfter`/`createdBefore` time range. Caller must be an active member of the org. Opaque cursor pagination.\n\nNote: `status` filters on the stored column. A session that has passed `expiresAt` but has not yet been swept is reported as `expired` in its body while still stored as `pending`, so `status=expired` may not match such sessions until the sweep runs.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -2078,9 +2098,13 @@ export const MCP_TOOLS = {
 				"query": {
 					"type": "object",
 					"properties": {
+						"sessionId": {
+							"type": "string",
+							"maxLength": 100
+						},
 						"providerId": {
 							"type": "string",
-							"format": "uuid"
+							"maxLength": 100
 						},
 						"status": {
 							"type": "string",
@@ -2099,7 +2123,7 @@ export const MCP_TOOLS = {
 						},
 						"claimantClientId": {
 							"type": "string",
-							"format": "uuid"
+							"maxLength": 100
 						},
 						"createdAfter": {
 							"type": "string",
@@ -2967,9 +2991,9 @@ export const MCP_TOOLS = {
 						},
 						"prompt": {
 							"type": "string",
-							"description": "Extraction prompt, used when `verificationType` is `llm`.",
+							"description": "Extraction prompt, used when `verificationType` is `llm`. Gated by the prompt guard before it is stored (docs/prompt-guard.md).",
 							"minLength": 0,
-							"maxLength": 1000000
+							"maxLength": 4000
 						},
 						"requests": {
 							"type": "array",

package/src/mcp/instructions.ts

@@ -6,6 +6,7 @@
  * `lib/mcp` (published) — both are two levels below the package root.
  * Old-devtools mode has its own reduced set in `../old/instructions.ts`.
  */
+import assert from 'node:assert'
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
@@ -14,6 +15,32 @@ export const BUILDER_MODE_INSTRUCTIONS = readFileSync(
 	'utf8',
 ).trim()
 
+/**
+ * `SKILL.builder.md` and `SKILL.old.md` share a lot of prose (steps that are
+ * identical regardless of backend, "never do" rules, common troubleshooting).
+ * That shared text lives once in `skill/SKILL.common.md`, split into named
+ * `<!-- section: name -->`-delimited blocks; each mode file splices a block
+ * back in at `<!-- common: name -->`. Parsed once at module load.
+ */
+const COMMON_SECTIONS = parseCommonSections(
+	readFileSync(
+		fileURLToPath(new URL('../../skill/SKILL.common.md', import.meta.url)),
+		'utf8',
+	),
+)
+
+function parseCommonSections(text: string): Record<string, string> {
+	const sections: Record<string, string> = {}
+	const re = /<!-- section: (\S+) -->\n([\s\S]*?)(?=\n<!-- section: |$)/g
+	for(const match of text.matchAll(re)) {
+		// Trim blank LINES only, not inline indentation — some sections are
+		// list-continuation text that's intentionally indented on its first line.
+		sections[match[1]] = match[2].replace(/^\n+/, '').replace(/\n+$/, '')
+	}
+
+	return sections
+}
+
 /**
  * The full provider-authoring guide — the deep capture→prove→publish workflow,
  * decision frameworks, and troubleshooting. Served on demand by the
@@ -24,9 +51,15 @@ export const BUILDER_MODE_INSTRUCTIONS = readFileSync(
  * the instructions above; any leading frontmatter is stripped defensively.
  */
 function readGuide(file: string): string {
-	return readFileSync(fileURLToPath(new URL(file, import.meta.url)), 'utf8')
-		.replace(/^---\n[\s\S]*?\n---\n/, '')
-		.trim()
+	const url = new URL(file, import.meta.url)
+	const raw = readFileSync(fileURLToPath(url), 'utf8')
+	const stripped = raw.replace(/^---\n[\s\S]*?\n---\n/, '').trim()
+
+	return stripped.replace(/<!-- common: (\S+) -->/g, (whole, name: string) => {
+		const section = COMMON_SECTIONS[name]
+		assert(section, `${file}: no SKILL.common.md section named "${name}"`)
+		return section
+	})
 }
 
 export const PROVIDER_GUIDE_BUILDER = readGuide('../../skill/SKILL.builder.md')

package/src/mcp/start.ts

@@ -20,6 +20,8 @@ import { NAME, VERSION } from '../pkg.ts'
 import { registerTools } from './api/tools.ts'
 import {
 	buildAgentTools,
+	buildBuilderAuthenticationTools,
+	buildBuilderOrganizationTools,
 	buildCredentialTools,
 	buildLocalCredentialTools,
 	buildModeTools,
@@ -49,7 +51,13 @@ export async function startMcpServer() {
 	// deployments — set RECLAIM_AGENT_DISABLED=1 to register only the API
 	// surface.
 	const agentToolsEnabled = !agentDisabled()
-
+	const builderClient = new ReclaimClient({
+		baseUrl: apiUrl(),
+		// Builder access is orthogonal to publishing mode. A legacy-devtools
+		// session can authenticate here solely to allocate a remote browser.
+		token: apiToken() || readSession()?.token,
+		headers: { 'User-Agent': `${NAME}/${VERSION}` },
+	})
 	// Backend-mode toggle — available in both modes and regardless of whether
 	// the agent tools are enabled, so a user can always switch either direction.
 	registerToolList(server, buildModeTools(config, oldMode))
@@ -66,20 +74,17 @@ export async function startMcpServer() {
 		})
 		const sdkClient = new ReclaimSdkClient({ baseUrl: sdkApiUrl() })
 
+		registerToolList(server, buildBuilderAuthenticationTools(builderClient))
+		registerToolList(server, buildBuilderOrganizationTools(builderClient))
 		registerToolList(server, buildLocalCredentialTools())
 		registerToolList(server, buildOldBackendTools(oldClient, sdkClient))
 		if(agentToolsEnabled) {
 			// No builder client → no builder publish tool (old mode has its own).
-			registerToolList(server, buildAgentTools())
+			registerToolList(server, buildAgentTools(undefined, builderClient))
 		}
 		// NOTE: registerTools() is intentionally NOT called — generated tools off.
 	} else {
-		const client = new ReclaimClient({
-			baseUrl: apiUrl(),
-			// Priority: explicit env var → cached session token → unauthenticated
-			token: apiToken() || readSession()?.token,
-			headers: { 'User-Agent': `${NAME}/${VERSION}` },
-		})
+		const client = builderClient
 
 		// Tool names must stay disjoint across these three groups: hand-written
 		// tools are higher-level orchestrations (multi-call flows, ReclaimProvider