@reclaimprotocol/agent 0.1.28 → 0.1.31

package/lib/mcp/api/tools.js

@@ -1,4 +1,5 @@
 import { remapErrorAsResponse } from "../remap_errors.js";
+import { successResponse } from "../success-response.js";
 import { MCP_TOOLS } from "./operations.gen.js";
 /**
  * The generated `MCP_TOOLS` are keyed by OpenAPI `operationId` (PascalCase,
@@ -15,18 +16,20 @@ function toSnakeCase(name) {
 }
 export function registerTools(server, client) {
     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
         // bug to surface, not silently shadow.
         server.registerTool(toSnakeCase(opId), shape, async (args) => {
             try {
+                if (!isOperationArgs(opId, args)) {
+                    throw new Error(`Invalid generated MCP arguments for ${opId}`);
+                }
                 const result = await client.call(opId, args);
-                return {
-                    content: [{
-                            type: 'text', text: JSON.stringify(result.data, null, 2)
-                        }],
-                };
+                return successResponse(result.data);
             }
             catch (err) {
                 return remapErrorAsResponse(err);
@@ -34,3 +37,22 @@ export function registerTools(server, client) {
         });
     }
 }
+/**
+ * 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) {
+    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(_operationId, value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/lib/mcp/instructions.js

@@ -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';
@@ -31,7 +12,7 @@ import { fileURLToPath } from 'node:url';
 function readSkill(file) {
     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();
 }
@@ -42,7 +23,7 @@ function splitBlocks(text, marker) {
     const blocks = new Map();
     const re = new RegExp(`<!-- ${marker}: (\\S+) -->\\n([\\s\\S]*?)(?=\\n<!-- ${marker}: |$)`, '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+$/, ''));
     }
@@ -55,11 +36,18 @@ const SHARED_TOPIC_FILES = {
     'interception': 'interception.md',
     'hash-validation': 'hash-validation.md',
 };
+/** Detailed topics that exist only in Builder mode. */
+const BUILDER_TOPIC_FILES = {
+    '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 = {
     '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.',
@@ -78,21 +66,22 @@ const TOPIC_SUMMARIES = {
         + '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 '
         + 'next.',
 };
-function buildGuide(file, ctxPrefix) {
+function buildGuide(file, ctxPrefix, modeTopicFiles = {}) {
     const raw = readSkill(file)
         .replace(/<!-- common: (\S+) -->/g, (_whole, name) => {
         const section = COMMON_SECTIONS.get(name);
@@ -105,6 +94,10 @@ function buildGuide(file, ctxPrefix) {
     for (const [name, path] of Object.entries(SHARED_TOPIC_FILES)) {
         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}"`);
@@ -112,7 +105,7 @@ function buildGuide(file, ctxPrefix) {
     });
     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) {
     return oldMode ? GUIDE_OLD : GUIDE_BUILDER;

package/lib/mcp/remap_errors.js

@@ -5,6 +5,12 @@ import { errorAsToolText } from "../tools/registry.js";
 // (shared with the cloud loop); Boom problems also attach structuredContent.
 export const remapErrorAsResponse = (err) => {
     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/lib/mcp/server.js

@@ -1,5 +1,6 @@
 import { toZod } from "./api/to-zod.js";
 import { remapErrorAsResponse } from "./remap_errors.js";
+import { successResponse } from "./success-response.js";
 // 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
 // importing `defineTool`/`RegisteredTool` from the server module.
@@ -16,14 +17,7 @@ export function registerToolList(server, tools) {
             inputSchema: toZod(tool.definition.inputSchema),
         }, async (args) => {
             try {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify(await tool.handler(args), null, 2),
-                        },
-                    ],
-                };
+                return successResponse(await tool.handler(args));
             }
             catch (err) {
                 return remapErrorAsResponse(err);

package/lib/mcp/start.js

@@ -15,7 +15,7 @@ import { buildAgentState, buildAgentTools, buildBuilderAuthenticationTools, buil
 import { BUILDER_MODE_INSTRUCTIONS } from "./instructions.js";
 import { registerToolList } from "./server.js";
 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);
@@ -42,8 +42,7 @@ export async function startMcpServer() {
     // the agent tools are enabled, so a user can always switch either direction.
     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({
@@ -89,8 +88,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/lib/mcp/success-response.d.ts

@@ -0,0 +1,5 @@
+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 declare function successResponse(value: unknown): CallToolResult;

package/lib/mcp/success-response.js

@@ -0,0 +1,21 @@
+/** 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) {
+    return {
+        structuredContent: structured(value),
+        content: [{
+                type: 'text',
+                text: JSON.stringify(value, null, 2) ?? 'null',
+            }],
+    };
+}
+function structured(value) {
+    if (isRecord(value)) {
+        return value;
+    }
+    return { result: value ?? null };
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/lib/mcp/tools/agent/attach.js

@@ -16,22 +16,8 @@ import { ensureLiveViewUrl } from "./live-view-url.js";
  * show — one on this machine is watched by looking at it.
  */
 export const SHAREABLE_MODES = new Set(['container']);
-/**
- * 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',
@@ -103,28 +89,6 @@ const BROWSER_OPTIONS = [
         liveView: 'None, unless you pass your own liveViewUrl alongside the cdpUrl.',
     },
 ];
-/**
- * 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() {
-    const seen = new Set();
-    const lines = [];
-    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(' ');
-}
 const DEFAULT_DEPENDENCIES = {
     connectLocal: connectCdp,
     connectRemote: connectCdpUrl,
@@ -140,34 +104,13 @@ dependencies = {}) {
     };
     return defineTool({
         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" }).',
+        description: '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/lib/mcp/tools/agent/build.d.ts

@@ -14,15 +14,12 @@ import { ConfigStore } from '../../../config/store.ts';
 import { type RegisteredTool } from '../../server.ts';
 import { type AttachState } from './attach.ts';
 import { type CaptureStore } from './capture.ts';
-import { type LiveShareRef } from './live-view.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
  *  publish tool can build the attach/capture state up front and share the SAME

package/lib/mcp/tools/agent/build.js

@@ -30,7 +30,6 @@ export function buildAgentState() {
     return {
         attach: { config: new ConfigStore() },
         captures: { sessions: new Map() },
-        liveShare: {},
     };
 }
 /** Build the flat list of `RegisteredTool` entries, ready for
@@ -54,11 +53,11 @@ export function buildAgentTools(client, builderClient = client, externalState) {
     for (const t of captureTools(state.attach, state.captures)) {
         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);
     }
     for (const t of podProofTools(state.attach, state.captures)) {
@@ -81,5 +80,5 @@ export function buildAgentTools(client, builderClient = client, externalState) {
  * safe when nothing was ever attached.
  */
 export async function disposeAgentState(state) {
-    await resetAll(state.attach, state.captures, state.liveShare);
+    await resetAll(state.attach, state.captures);
 }

package/lib/mcp/tools/agent/how-it-works.d.ts

@@ -1,19 +1,9 @@
 import { 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 declare function howItWorksTool(oldMode: boolean): RegisteredTool;

package/lib/mcp/tools/agent/how-it-works.js

@@ -1,34 +1,21 @@
 import { guideFor } from "../../instructions.js";
 import { defineTool } from "../../server.js";
 /**
- * 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) {
     const guide = guideFor(oldMode);
     const names = [...guide.topics.keys()];
     return defineTool({
         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.',
+        description: '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: {

package/lib/mcp/tools/agent/live-view.d.ts

@@ -1,19 +1,5 @@
-import { startTunnel, type Tunnel } from '../../../live/tunnel.ts';
 import { type RegisteredTool } from '../../server.ts';
 import { type AttachState } from './attach.ts';
-export interface LiveShare {
-    tunnel: Tunnel;
-    /** The public URL handed to whoever is watching. */
-    url: string;
-}
-export interface LiveShareRef {
-    current?: LiveShare;
-}
-type TunnelStarter = typeof startTunnel;
-/** Tear down whatever share is running. Safe when none is. Exported so the
- *  session tools can call it from `dispose_browser` / `reset_session`. */
-export declare function stopLiveShare(ref: LiveShareRef): Promise<boolean>;
 export declare function liveViewTools(attachRef: {
     current?: AttachState;
-}, shareRef: LiveShareRef, openTunnel?: TunnelStarter): RegisteredTool[];
-export {};
+}): RegisteredTool[];