@reclaimprotocol/agent 0.1.28 → 0.1.31

package/src/mcp/api/tools.ts

@@ -5,6 +5,7 @@ import type {
 	IOperationId
 } from '@reclaimprotocol/client/openapi'
 import { remapErrorAsResponse } from '../remap_errors.ts'
+import { successResponse } from '../success-response.ts'
 import { MCP_TOOLS } from './operations.gen.ts'
 
 /**
@@ -23,6 +24,12 @@ function toSnakeCase(name: string): string {
 
 export function registerTools(server: McpServer, client: ReclaimClient) {
 	for(const [opId, shape] of Object.entries(MCP_TOOLS)) {
+		if(!isOperationId(opId)) {
+			throw new Error(
+				`Generated MCP operation is not in the API client: ${opId}`,
+			)
+		}
+
 		// snake_case to match the hand-written tools. A name that collides with
 		// a hand-written tool throws here at startup — intentional: hand-written
 		// and generated names must stay disjoint (see start.ts), so a clash is a
@@ -32,15 +39,15 @@ export function registerTools(server: McpServer, client: ReclaimClient) {
 			shape,
 			async(args: unknown) => {
 				try {
+					if(!isOperationArgs(opId, args)) {
+						throw new Error(`Invalid generated MCP arguments for ${opId}`)
+					}
+
 					const result = await client.call(
-						opId as IOperationId,
-						args as IOperationArgs<IOperationId>,
+						opId,
+						args,
 					)
-					return {
-						content: [{
-							type: 'text' as const, text: JSON.stringify(result.data, null, 2)
-						}],
-					}
+					return successResponse(result.data)
 				} catch(err) {
 					return remapErrorAsResponse(err)
 				}
@@ -48,3 +55,27 @@ export function registerTools(server: McpServer, client: ReclaimClient) {
 		)
 	}
 }
+
+/**
+ * Always true in practice — `value` comes from `Object.entries(MCP_TOOLS)`
+ * itself — but the check still earns its keep: it narrows `opId` to
+ * `IOperationId` for `client.call` below without an unchecked cast, and it
+ * turns "the generator and the API client drifted apart" into a startup
+ * error instead of a silent `as`.
+ */
+function isOperationId(value: string): value is IOperationId {
+	return value in MCP_TOOLS
+}
+
+/**
+ * The MCP SDK parses `args` through the generated Zod schema before invoking
+ * this callback. Keep a runtime object check at this TypeScript boundary so
+ * generated operation arguments retain their operation-specific type without
+ * an unchecked cast.
+ */
+function isOperationArgs<T extends IOperationId>(
+	_operationId: T,
+	value: unknown,
+): value is IOperationArgs<T> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/src/mcp/instructions.ts

@@ -1,29 +1,10 @@
 /**
- * The authoring documentation, assembled from `skill/*.md` at module load.
+ * Loads concise, always-on mode instructions and topic guides served on
+ * demand by `how_it_works`. Keeping detailed guidance out of tool schemas
+ * avoids adding it to every request's context.
  *
- * Two things are served from here:
- *  - the always-on MCP server `instructions` (one file per backend mode) —
- *    deliberately small, since every client pays for them on every turn;
- *  - the deep authoring guide, split into TOPICS and served on demand by the
- *    `how_it_works` tool. Nothing here is inlined into a tool schema: a doc
- *    embedded in an input-schema description is paid for on every request
- *    whether or not it's ever relevant.
- *
- * The prose lives in markdown (published via package.json's `files`) so it
- * can be edited without touching code. Paths resolve identically from
- * `src/mcp` (dev) and `lib/mcp` (published) — both are two levels below the
- * package root.
- *
- * Assembly has three steps:
- *  1. `<!-- common: name -->` splices a shared block out of `SKILL.common.md`
- *     (delimited there by `<!-- section: name -->`), so the two mode guides
- *     don't drift on the ~60% of prose that is identical.
- *  2. `%CTX%` expands to the mode's consumer-param namespace — `context.` on
- *     the builder, `context_` on old-devtools. That is the only textual
- *     difference across most shared blocks, so tokenizing it keeps them
- *     shared.
- *  3. `<!-- topic: name -->` splits the result into the units `how_it_works`
- *     serves. Backend-independent topics come from their own files instead.
+ * `<!-- common: name -->` includes shared sections, `%CTX%` selects the
+ * mode-specific context prefix, and `<!-- topic: name -->` creates a topic.
  */
 import assert from 'node:assert'
 import { readFileSync } from 'node:fs'
@@ -32,7 +13,7 @@ import { fileURLToPath } from 'node:url'
 function readSkill(file: string): string {
 	const url = new URL(`../../skill/${file}`, import.meta.url)
 	return readFileSync(fileURLToPath(url), 'utf8')
-		// Strip any leading frontmatter defensively.
+		// These files are internal topic fragments, but tolerate skill frontmatter.
 		.replace(/^---\n[\s\S]*?\n---\n/, '')
 		.trim()
 }
@@ -48,7 +29,7 @@ function splitBlocks(text: string, marker: string): Map<string, string> {
 		'g',
 	)
 	for(const match of text.matchAll(re)) {
-		// Trim blank LINES only, not inline indentation — some blocks are
+		// Trim blank lines only, not inline indentation. Some blocks are
 		// list-continuation text that's intentionally indented on its first line.
 		blocks.set(match[1], match[2].replace(/^\n+/, '').replace(/\n+$/, ''))
 	}
@@ -65,11 +46,19 @@ const SHARED_TOPIC_FILES: Record<string, string> = {
 	'hash-validation': 'hash-validation.md',
 }
 
+/** Detailed topics that exist only in Builder mode. */
+const BUILDER_TOPIC_FILES: Record<string, string> = {
+	'contributions': 'community-contributions.md',
+	'integration': 'verification-client-integration.md',
+}
+
 /** One line per topic, shown in the `how_it_works` index so a caller can pick
  *  the right one without fetching several. Keyed across both modes; only the
  *  topics a mode actually has are listed back to it. */
 const TOPIC_SUMMARIES: Record<string, string> = {
 	'overview': 'Terminology, your stance, and the whole loop at a glance.',
+	'contributions': 'Contributing a public provider as a volunteer: the '
+		+ 'candidate-and-review workflow and the extra rules it adds.',
 	'auth': 'Signing in to the backend, and which token authorizes what.',
 	'devtools-migration': 'Importing a public legacy provider with the same '
 		+ 'UUID.',
@@ -88,15 +77,16 @@ const TOPIC_SUMMARIES: Record<string, string> = {
 		+ 'and going live.',
 	'discover': 'Finding providers, resolving them, and creating a verification '
 		+ 'session.',
-	'integration': 'Builder Verification Client integration: the `api=2` bridge, '
-		+ 'result verification, and optional TEE binding.',
+	'integration': 'Set up a Builder token, callback, frontend and backend '
+		+ 'with @reclaimprotocol/client; direct `api=2` API and result '
+		+ 'verification.',
 	'user-script': 'Authoring jsUserScripts / customInjection to drive '
 		+ 'login-gated pages.',
 	'interception': 'injectionType / interceptorType, live interception, the '
 		+ 'document-replay flag, and what to do when a site won\'t load or '
 		+ 'won\'t let the user sign in.',
-	'hash-validation': 'bodySniff, and how verifyProof({ providerId }) gates on '
-		+ 'the declared spec hash.',
+	'hash-validation': 'bodySniff, and how verifyRequestProof({ providerId }) '
+		+ 'gates on the declared spec hash.',
 	'credentials': 'The eth proof-owner key run_proof signs with.',
 	'never-do': 'The short list of things that always break a provider.',
 	'troubleshooting': 'Expired drafts, browser problems, and where to look '
@@ -112,7 +102,11 @@ export interface Guide {
 	full: string
 }
 
-function buildGuide(file: string, ctxPrefix: string): Guide {
+function buildGuide(
+	file: string,
+	ctxPrefix: string,
+	modeTopicFiles: Record<string, string> = {},
+): Guide {
 	const raw = readSkill(file)
 		.replace(/<!-- common: (\S+) -->/g, (_whole, name: string) => {
 			const section = COMMON_SECTIONS.get(name)
@@ -127,6 +121,11 @@ function buildGuide(file: string, ctxPrefix: string): Guide {
 		topics.set(name, readSkill(path))
 	}
 
+	for(const [name, path] of Object.entries(modeTopicFiles)) {
+		assert(topics.has(name), `${file}: no topic marker named "${name}"`)
+		topics.set(name, readSkill(path))
+	}
+
 	const index = [...topics.keys()].map((topic) => {
 		const summary = TOPIC_SUMMARIES[topic]
 		assert(summary, `${file}: no TOPIC_SUMMARIES entry for "${topic}"`)
@@ -136,7 +135,11 @@ function buildGuide(file: string, ctxPrefix: string): Guide {
 	return { topics, index, full: [...topics.values()].join('\n\n') }
 }
 
-export const GUIDE_BUILDER = buildGuide('SKILL.builder.md', 'context.')
+export const GUIDE_BUILDER = buildGuide(
+	'SKILL.builder.md',
+	'context.',
+	BUILDER_TOPIC_FILES,
+)
 export const GUIDE_OLD = buildGuide('SKILL.old.md', 'context_')
 
 export function guideFor(oldMode: boolean): Guide {

package/src/mcp/remap_errors.ts

@@ -10,6 +10,12 @@ export const remapErrorAsResponse = (
 ): CallToolResult => {
 	const text = errorAsToolText(err)
 
+	// Two unrelated things can carry structured data here: the client's own
+	// ProblemError (an RFC 9457 response from a Builder API call), and a
+	// hand-thrown Boom error whose second argument is arbitrary tool context,
+	// for example `badRequest('invalid provider', { field: 'providerId' })`.
+	// `isProblemDetails` only rejects a wrongly typed KNOWN field, so it lets
+	// that arbitrary shape through too — this isn't a strict RFC 9457 check.
 	const data = isProblemError(err)
 		? err.data
 		: isBoom(err) && err.output?.statusCode

package/src/mcp/server.ts

@@ -2,6 +2,7 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { type RegisteredTool } from '../tools/registry.ts'
 import { toZod } from './api/to-zod.ts'
 import { remapErrorAsResponse } from './remap_errors.ts'
+import { successResponse } from './success-response.ts'
 
 // The tool primitive lives in `../tools/registry.ts` (SDK-free, so the cloud
 // loop can use it too). Re-exported here so the MCP-side tool files can keep
@@ -27,14 +28,7 @@ export function registerToolList(server: McpServer, tools: RegisteredTool[]) {
 			},
 			async(args) => {
 				try {
-					return {
-						content: [
-							{
-								type: 'text' as const,
-								text: JSON.stringify(await tool.handler(args), null, 2),
-							},
-						],
-					}
+					return successResponse(await tool.handler(args))
 				} catch(err) {
 					return remapErrorAsResponse(err)
 				}

package/src/mcp/start.ts

@@ -36,7 +36,7 @@ import { BUILDER_MODE_INSTRUCTIONS } from './instructions.ts'
 import { registerToolList } from './server.ts'
 
 export async function startMcpServer() {
-	// Mode precedence: explicit USE_OLD_DEVTOOLS env → persisted config → old.
+	// Mode precedence: explicit env → persisted config → builder.
 	// The same store instance backs the set_devtools_mode toggle below.
 	const config = new ConfigStore()
 	const oldMode = resolveOldMode(config.read()?.mode)
@@ -69,8 +69,7 @@ export async function startMcpServer() {
 	registerToolList(server, buildModeTools(config, oldMode))
 
 	if(oldMode) {
-		// OLD-devtools mode (the default): the legacy backend is still in
-		// production while builder is built. All auto-generated builder tools
+		// Explicit OLD-devtools mode. All auto-generated builder tools
 		// are disabled; a small ReclaimOldClient serves authenticate / publish /
 		// get_me_providers instead.
 		const oldClient = new ReclaimOldClient({
@@ -128,8 +127,7 @@ export async function startMcpServer() {
 	// Anything the session holds has to be released when the session ends, and
 	// the session can end without a single tool call: the developer closes their
 	// agent, the client kills the server, stdin drops. Nothing ran here before,
-	// which left a container up and — worse — a public tunnel still pointing at a
-	// live browser after the session that made it was gone.
+	// which left a container up after the session that made it was gone.
 	if(agentToolsEnabled) {
 		installShutdownHooks(() => agentState)
 	}

package/src/mcp/success-response.ts

@@ -0,0 +1,26 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
+
+/** Return successful tool data in both MCP representations. Older clients read
+ * the JSON text; newer clients can consume `structuredContent` without asking
+ * the model to parse or reconstruct identifiers, URLs, and state. */
+export function successResponse(value: unknown): CallToolResult {
+	return {
+		structuredContent: structured(value),
+		content: [{
+			type: 'text',
+			text: JSON.stringify(value, null, 2) ?? 'null',
+		}],
+	}
+}
+
+function structured(value: unknown): Record<string, unknown> {
+	if(isRecord(value)) {
+		return value
+	}
+
+	return { result: value ?? null }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === 'object' && !Array.isArray(value)
+}

package/src/mcp/tools/agent/attach.ts

@@ -85,22 +85,8 @@ interface AttachArgs {
 	viewerPort?: number
 }
 
-/**
- * The browser sources, written once and used twice: rendered into this tool's
- * DESCRIPTION (so an agent can put the choice to the developer straight from
- * the tool list, without a discovery round-trip) and returned verbatim as
- * structured `options` when the tool is called without a `mode` anyway.
- *
- * Being the single source for both is the point — an option list that a model
- * reads in the description but that disagrees with what the tool returns is
- * worse than either alone.
- *
- * Ordered and labelled BY USE CASE, because that is the question a developer
- * can actually answer. "Which CDP transport?" is not; "does anyone else need to
- * get into this browser?" is, and it decides two of the four. `useCase` is the
- * grouping key, so the rendered list reads as two pairs rather than four
- * unrelated transports.
- */
+/** Browser sources returned when the caller omits `mode`. Keep selection detail
+ * here instead of repeating it in the always-loaded tool description. */
 const BROWSER_OPTIONS = [
 	{
 		mode: 'dedicated',
@@ -181,33 +167,6 @@ const BROWSER_OPTIONS = [
 	},
 ] as const
 
-/**
- * The options as prose, grouped by use case.
- *
- * The grouping is the useful part: it turns "pick one of five transports" into
- * "answer one question, then pick one of two".
- */
-function renderBrowserOptions(): string {
-	const seen = new Set<string>()
-	const lines: string[] = []
-	for(const option of BROWSER_OPTIONS) {
-		if(!seen.has(option.useCase)) {
-			seen.add(option.useCase)
-			lines.push(`— ${option.useCase.toUpperCase()} —`)
-		}
-
-		const needs = option.requires.length
-			? ` Needs: ${option.requires.join('; ')}.`
-			: ''
-		lines.push(
-			`(${option.mode}) ${option.label}. ${option.detail}${needs}`
-			+ ` Live view: ${option.liveView}`,
-		)
-	}
-
-	return lines.join(' ')
-}
-
 interface AttachDependencies {
 	connectLocal: typeof connectCdp
 	connectRemote: typeof connectCdpUrl
@@ -238,34 +197,13 @@ export function attachTool(
 		{
 			name: 'attach_browser',
 			description:
-				'Connect the provider-authoring tools to a browser. Never choose '
-				+ 'for them, never assume a previous session\'s choice still '
-				+ 'applies, and call this ONCE with the `mode` they pick. '
-				+ 'ASK THIS FIRST, before listing anything: "Will you be doing this '
-				+ 'yourself, or does someone else need to sign in — for example the '
-				+ 'person whose account it is?" That answer decides half the list, '
-				+ 'and a developer can answer it without knowing what CDP is. '
-				+ 'THEMSELVES → offer `dedicated` or `attach`. SOMEONE ELSE, or the '
-				+ 'site only works on a phone → offer `container` or `builder`, '
-				+ 'which are the only two that produce a link another person can '
-				+ 'open. Say which of those two costs money: `container` is free '
-				+ 'but needs Docker, `builder` needs no install but is billed '
-				+ 'against the org\'s quota. '
-				+ 'Then relay the matching options with their live-view lines. You '
-				+ 'do not need a discovery call — the full list is here, and calling '
-				+ 'with no `mode` returns it as structured `options` if you would '
-				+ 'rather read it back verbatim. '
-				+ 'OPTIONS — ' + renderBrowserOptions() + ' '
-				+ 'A `container` browser returns a local `viewerUrl`; relay it. When '
-				+ 'someone remote needs in, call share_browser_view and relay the '
-				+ 'FULL public url verbatim, on its own line. `builder` returns a '
-				+ 'hosted `liveViewUrl` — relay that the same way. `dedicated`, '
-				+ '`attach` and `custom` cannot be shared at all: if they ask for a '
-				+ 'link after picking one, say so and offer to re-attach with '
-				+ '`container`. '
-				+ 'Builder and custom CDP credentials are held in memory and are '
-				+ 'never returned. '
-				+ 'More: how_it_works({ topic: "browser" }).',
+				'Connects provider-authoring tools to a browser. Call without '
+				+ '`mode` to receive the current options, then ask the developer to '
+				+ 'choose; `builder` consumes quota and only `container` and `builder` '
+				+ 'support a shareable live view. Call again once with the chosen '
+				+ 'mode. Relay returned live-view URLs verbatim. For selection, '
+				+ 'geolocation, and lifecycle guidance, call '
+				+ 'how_it_works({ topic: "browser" }).',
 			inputSchema: {
 				type: 'object',
 				properties: {

package/src/mcp/tools/agent/build.ts

@@ -19,7 +19,7 @@ import { type AttachState, attachTool } from './attach.ts'
 import { type CaptureStore, captureTools, resetCaptures } from './capture.ts'
 import { listTabsTool } from './eval.ts'
 import { howItWorksTool } from './how-it-works.ts'
-import { type LiveShareRef, liveViewTools } from './live-view.ts'
+import { liveViewTools } from './live-view.ts'
 import { podProofTools } from './pod-proof.ts'
 import { createVersionFromCaptureTool } from './publish.ts'
 import { resetAll, sessionTools } from './session.ts'
@@ -28,8 +28,6 @@ import { sharedAuthoringTools } from './shared.ts'
 export interface AgentState {
 	attach: { current?: AttachState, config: ConfigStore }
 	captures: CaptureStore
-	/** The one public live view, when `share_browser_view` has opened it. */
-	liveShare: LiveShareRef
 }
 
 /** Exported so a mode (for example, old-devtools) that supplies its own
@@ -41,7 +39,6 @@ export function buildAgentState(): AgentState {
 	return {
 		attach: { config: new ConfigStore() },
 		captures: { sessions: new Map() },
-		liveShare: {},
 	}
 }
 
@@ -71,12 +68,12 @@ export function buildAgentTools(
 		tools.push(t)
 	}
 
-	for(const t of sessionTools(state.attach, state.captures, state.liveShare)) {
+	for(const t of sessionTools(state.attach, state.captures)) {
 		tools.push(t)
 	}
 
 	// Local-CDP only: a builder-mode browser already has a hosted live view.
-	for(const t of liveViewTools(state.attach, state.liveShare)) {
+	for(const t of liveViewTools(state.attach)) {
 		tools.push(t)
 	}
 
@@ -104,5 +101,5 @@ export function buildAgentTools(
  * safe when nothing was ever attached.
  */
 export async function disposeAgentState(state: AgentState): Promise<void> {
-	await resetAll(state.attach, state.captures, state.liveShare)
+	await resetAll(state.attach, state.captures)
 }

package/src/mcp/tools/agent/how-it-works.ts

@@ -2,21 +2,11 @@ import { guideFor } from '../../instructions.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 
 /**
- * Serves the provider-authoring guide on demand, ONE TOPIC AT A TIME. The
- * server's always-on `instructions` are a terse tool-flow reference; this tool
- * is the deep version, so any MCP client — not just Claude Code, which alone
- * auto-loads skills — can pull it.
- *
- * Topic-scoped rather than all-at-once because the full guide is ~7k tokens:
- * paying that to answer "how do I mark a header secret?" crowds out the actual
- * task, which is exactly what makes an agent slow and prone to inventing
- * details. Every response carries the topic index, so a caller that guessed
- * wrong (or called with no topic at all) always learns what else is available
- * without a second round-trip.
- *
- * `oldMode` selects the backend-specific guide, so the agent is never told to
- * call auth/publish tools that aren't registered in its mode. Stateless:
- * callable before `attach_browser`.
+ * Serve one mode-specific guide topic without loading the full guide (~7k
+ * tokens) — paying that cost to answer one question would crowd out the
+ * actual task. Every response includes the topic index, so a caller that
+ * guessed the topic name wrong still learns what else exists in the same
+ * round-trip.
  */
 export function howItWorksTool(oldMode: boolean): RegisteredTool {
 	const guide = guideFor(oldMode)
@@ -26,13 +16,10 @@ export function howItWorksTool(oldMode: boolean): RegisteredTool {
 		{
 			name: 'how_it_works',
 			description:
-				'Reclaim provider-authoring guide for THIS server, by topic. Call it '
-				+ 'with no arguments for the overview plus the topic index, then again '
-				+ 'for whichever topic you need. Topics: '
-				+ names.join(', ')
-				+ '. Use `all` for the entire guide at once (large — prefer a topic). '
-				+ 'Read the relevant topic BEFORE acting unless you are already fluent '
-				+ 'in that part of the flow.',
+				'Returns topic-specific provider-authoring guidance for the active '
+				+ 'backend. Call without a topic for the overview and index. Before an '
+				+ 'unfamiliar or sensitive step, request that topic. Prefer one topic; '
+				+ '`all` returns the much larger complete guide.',
 			inputSchema: {
 				type: 'object',
 				properties: {