@reclaimprotocol/agent 0.1.23 → 0.1.24

package/lib/mcp/instructions.js

@@ -1,51 +1,114 @@
 /**
- * MCP server instructions shown to the LLM when running in BUILDER mode
- * (`USE_OLD_DEVTOOLS=false`). The prose lives in `skill/builder-mode.md`
- * (published via the `files` array) so it can be edited as markdown without
- * touching code. The path resolves identically from `src/mcp` (dev) and
- * `lib/mcp` (published) — both are two levels below the package root.
- * Old-devtools mode has its own reduced set in `../old/instructions.ts`.
+ * The authoring documentation, assembled from `skill/*.md` at module load.
+ *
+ * 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.
  */
 import assert from 'node:assert';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-export const BUILDER_MODE_INSTRUCTIONS = readFileSync(fileURLToPath(new URL('../../skill/builder-mode.md', import.meta.url)), '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) {
-    const sections = {};
-    const re = /<!-- section: (\S+) -->\n([\s\S]*?)(?=\n<!-- section: |$)/g;
+function readSkill(file) {
+    const url = new URL(`../../skill/${file}`, import.meta.url);
+    return readFileSync(fileURLToPath(url), 'utf8')
+        // Strip any leading frontmatter defensively.
+        .replace(/^---\n[\s\S]*?\n---\n/, '')
+        .trim();
+}
+export const BUILDER_MODE_INSTRUCTIONS = readSkill('builder-mode.md');
+export const OLD_MODE_INSTRUCTIONS = readSkill('old-mode.md');
+/** Split `<!-- marker: name -->`-delimited blocks, keeping document order. */
+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 sections are
+        // Trim blank LINES only, not inline indentation — some blocks are
         // list-continuation text that's intentionally indented on its first line.
-        sections[match[1]] = match[2].replace(/^\n+/, '').replace(/\n+$/, '');
+        blocks.set(match[1], match[2].replace(/^\n+/, '').replace(/\n+$/, ''));
     }
-    return sections;
+    return blocks;
 }
-/**
- * The full provider-authoring guide — the deep capture→prove→publish workflow,
- * decision frameworks, and troubleshooting. Served on demand by the
- * `how_it_works` MCP tool so every client (not just Claude Code, which
- * auto-loads skills) can pull it. There's a guide PER MODE so an agent is never
- * shown auth/publish tools that don't exist in its backend: the server picks
- * one by `oldMode` (see `mcp/start.ts`). Same `../../skill/` path resolution as
- * the instructions above; any leading frontmatter is stripped defensively.
- */
-function readGuide(file) {
-    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) => {
-        const section = COMMON_SECTIONS[name];
+const COMMON_SECTIONS = splitBlocks(readSkill('SKILL.common.md'), 'section');
+/** Topics that read the same on both backends, each its own file. */
+const SHARED_TOPIC_FILES = {
+    'user-script': 'user-script.md',
+    'interception': 'interception.md',
+    'hash-validation': 'hash-validation.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.',
+    'auth': 'Signing in to the backend, and which token authorizes what.',
+    'browser': 'Choosing a browser source (local / remote / custom CDP), '
+        + 'geolocation, live view, and launch troubleshooting.',
+    'capture': 'Tabs, login detection, driving the page, and picking an '
+        + 'authenticated request to prove.',
+    'draft': 'The OPRF/privacy decision, propose_provider, and the canonical '
+        + 'drafted shape.',
+    'params': 'Extracted vs consumer-supplied vs secret params, the URL '
+        + 'character budget, and runtime resolution.',
+    'prove': 'replay_request, the mandatory auth-bound check, run_proof, and '
+        + 'diagnosing failures.',
+    'publish': 'Creating/reusing a provider, versions, multi-request providers, '
+        + 'and going live.',
+    'discover': 'Finding the right providers for a dev\'s app and creating a '
+        + 'verification session.',
+    '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.',
+    '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) {
+    const raw = readSkill(file)
+        .replace(/<!-- common: (\S+) -->/g, (_whole, name) => {
+        const section = COMMON_SECTIONS.get(name);
         assert(section, `${file}: no SKILL.common.md section named "${name}"`);
         return section;
+    })
+        .replaceAll('%CTX%', ctxPrefix);
+    const topics = splitBlocks(raw, 'topic');
+    assert(topics.size, `${file}: no <!-- topic: … --> sections found`);
+    for (const [name, path] of Object.entries(SHARED_TOPIC_FILES)) {
+        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}"`);
+        return { topic, summary };
     });
+    return { topics, index, full: [...topics.values()].join('\n\n') };
+}
+export const GUIDE_BUILDER = buildGuide('SKILL.builder.md', 'context.');
+export const GUIDE_OLD = buildGuide('SKILL.old.md', 'context_');
+export function guideFor(oldMode) {
+    return oldMode ? GUIDE_OLD : GUIDE_BUILDER;
 }
-export const PROVIDER_GUIDE_BUILDER = readGuide('../../skill/SKILL.builder.md');
-export const PROVIDER_GUIDE_OLD = readGuide('../../skill/SKILL.old.md');

package/lib/mcp/start.js

@@ -50,7 +50,8 @@ export async function startMcpServer() {
         });
         const sdkClient = new ReclaimSdkClient({ baseUrl: sdkApiUrl() });
         // Shared with buildAgentTools below so the old-mode publish tool can see
-        // the live attach state (e.g. to flag a still-open browser session).
+        // the live attach state (for example, to flag a still-open browser
+        // session).
         const agentState = buildAgentState();
         registerToolList(server, buildBuilderAuthenticationTools(builderClient));
         registerToolList(server, buildBuilderOrganizationTools(builderClient));
@@ -71,8 +72,8 @@ export async function startMcpServer() {
         // collision instead of one tool silently shadowing the other.
         // Register credential tools for ETH credential management.
         registerToolList(server, buildCredentialTools(client));
-        // Higher-level verification orchestrations (e.g. fetch + decrypt result).
-        // Authenticates with RECLAIM_ORG_SECRET, not the session client.
+        // Higher-level verification orchestrations (for example, fetch + decrypt
+        // result). Authenticates with RECLAIM_ORG_SECRET, not the session client.
         registerToolList(server, buildVerificationTools());
         // Add auto-generated tools with snake_case wrappers
         // for every MCP-tagged operation.

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

@@ -3,7 +3,11 @@ import { defineTool } from "../../server.js";
 export function analyzeTool(captures) {
     return defineTool({
         name: 'analyze_request_constraints',
-        description: 'Flag potential provider-authoring concerns for a captured request.',
+        description: 'Flag provider-authoring concerns for one captured request — signed '
+            + 'request, CSRF dependency, bot challenge, short-lived token, '
+            + 'GraphQL. Call it on each top candidate from '
+            + 'find_requests_containing before drafting, and relay the returned '
+            + '`concerns` to the developer verbatim.',
         inputSchema: {
             type: 'object',
             properties: {

package/lib/mcp/tools/agent/attach.d.ts

@@ -10,6 +10,13 @@ export interface AttachState {
     liveViewUrl?: string;
     browserSessionId?: string;
     orgId?: string;
+    /** The Popcorn pod's own TEE api base (builder mode only) — lets
+     *  `run_proof_via_pod` prove through the SAME enclave that holds the
+     *  browser's TLS session (and its country-routed egress), instead of the
+     *  local in-process attestor SDK. */
+    apiUrl?: string;
+    /** The exit country this remote browser was allocated with, if any. */
+    countryCode?: string;
     disposeRemote?: () => Promise<void>;
 }
 export interface AttachRef {
@@ -20,6 +27,6 @@ interface AttachDependencies {
     connectLocal: typeof connectCdp;
     connectRemote: typeof connectCdpUrl;
 }
-export declare function attachTool(state: AttachRef, builderClient?: ReclaimClient, name?: 'attach_browser' | 'attach_chrome', beforeReplace?: () => Promise<void>, dependencies?: AttachDependencies): RegisteredTool;
+export declare function attachTool(state: AttachRef, builderClient?: ReclaimClient, beforeReplace?: () => Promise<void>, dependencies?: AttachDependencies): RegisteredTool;
 export declare function disposeAttached(state: AttachRef): Promise<void>;
 export {};

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

@@ -1,30 +1,109 @@
 import { badRequest } from '@hapi/boom';
 import assert from 'node:assert';
 import { connectCdp, connectCdpUrl, } from "../../../cdp/client.js";
+import { suggestCountryFromIp } from "../../../cdp/geo.js";
 import { defaultProfileDir, launchChrome, waitForCdpReady, } from "../../../cdp/launcher.js";
 import { defaultConfigPath } from "../../../config/store.js";
 import { defineTool } from "../../server.js";
+/**
+ * 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.
+ *
+ * `liveView` is here for the same reason. How a developer watches the browser
+ * differs per mode — Popcorn hands back a hosted URL, a local Chrome needs
+ * `share_browser_view` to tunnel one — and nobody discovers that by guessing.
+ * Advertising it alongside the mode is the only place it lands BEFORE the
+ * choice is made.
+ */
+const BROWSER_OPTIONS = [
+    {
+        mode: 'dedicated',
+        label: 'Local Chrome, launched for you',
+        detail: 'Launches Chrome with a dedicated profile under '
+            + '~/.reclaim/chrome-profile. Easiest local option; nothing to set up.',
+        requires: [],
+        liveView: 'On this machine only, until you share it: share_browser_view puts the '
+            + 'tab behind a public URL (needs cloudflared) so someone elsewhere can '
+            + 'watch, and by default click and type.',
+    },
+    {
+        mode: 'attach',
+        label: 'Local Chrome the developer is already running',
+        detail: 'Connects to an existing Chrome debugging port. That Chrome must have '
+            + 'been started with BOTH --remote-debugging-port AND a non-default '
+            + '--user-data-dir: since Chrome 136 the debug flag is silently ignored '
+            + 'on the default profile.',
+        requires: ['port (default 9222)'],
+        liveView: 'On this machine only, until you share it: share_browser_view puts the '
+            + 'tab behind a public URL (needs cloudflared) so someone elsewhere can '
+            + 'watch, and by default click and type.',
+    },
+    {
+        mode: 'builder',
+        label: 'Remote Builder browser (Popcorn), with a shareable live view',
+        detail: 'Quota-accounted remote browser; returns a liveViewUrl the developer '
+            + 'can open or share. The only way to browse a site from a SPECIFIC '
+            + 'COUNTRY — its whole egress is routed there. Geolocation is '
+            + 'optional: '
+            + 'omit countryCode to be offered a suggestion, or pass skipCountry '
+            + 'to allocate without geo-routing.',
+        requires: [
+            'Builder authentication',
+            'orgId (auto-resolved when you have only one)',
+        ],
+        liveView: 'Included — this call returns a hosted liveViewUrl straight from '
+            + 'Popcorn. Nothing to start, and share_browser_view does not apply.',
+    },
+    {
+        mode: 'custom',
+        label: 'A CDP endpoint the developer supplies',
+        detail: 'Connects to any ws:// or wss:// CDP websocket. The URL is treated as '
+            + 'a credential — it is never logged, persisted, or returned.',
+        requires: ['cdpUrl'],
+        liveView: 'Shareable on request: share_browser_view puts the tab behind a public '
+            + 'URL (needs cloudflared). The developer\'s own cdpUrl is never '
+            + 'exposed by it.',
+    },
+];
+/** Flatten {@link BROWSER_OPTIONS} into the tool description. */
+function renderBrowserOptions() {
+    return BROWSER_OPTIONS
+        .map((option) => {
+        const needs = option.requires.length
+            ? ` Needs: ${option.requires.join('; ')}.`
+            : '';
+        return `(${option.mode}) ${option.label}. ${option.detail}${needs}`
+            + ` Live view: ${option.liveView}`;
+    })
+        .join(' ');
+}
 const DEFAULT_DEPENDENCIES = {
     connectLocal: connectCdp,
     connectRemote: connectCdpUrl,
 };
-export function attachTool(state, builderClient, name = 'attach_browser', beforeReplace, dependencies = DEFAULT_DEPENDENCIES) {
+export function attachTool(state, builderClient, beforeReplace, dependencies = DEFAULT_DEPENDENCIES) {
     return defineTool({
-        name,
-        description: name === 'attach_chrome'
-            ? 'Backward-compatible alias for attach_browser.'
-            : 'Connect the provider-authoring tools to a browser. Choose '
-                + 'dedicated (launch local Chrome), attach (existing local CDP '
-                + 'port), builder (quota-accounted Popcorn browser with a '
-                + 'shareable live view), or custom (caller-supplied CDP '
-                + 'websocket). '
-                + 'For builder mode, orgId may be omitted: it auto-resolves to '
-                + 'the account\'s only organization, or — if there is more '
-                + 'than one — returns needsChoice with the full list so the '
-                + 'caller can ask the developer which to use and re-call with '
-                + 'that orgId. '
-                + 'Builder and custom CDP credentials are held in memory and never '
-                + 'returned.',
+        name: 'attach_browser',
+        description: 'Connect the provider-authoring tools to a browser. ASK THE '
+            + 'DEVELOPER which of the four options below they want, then call '
+            + 'this ONCE with their chosen `mode` — never choose for them, and '
+            + 'never assume a previous session\'s choice still applies. You do '
+            + 'not need a discovery call: the options are listed here. '
+            + '(Calling with no `mode` returns the same list as structured '
+            + '`options`, if you\'d rather relay it verbatim.) '
+            + 'When you put the choice to them, INCLUDE each option\'s live-view '
+            + 'line: how they watch the browser differs per mode, and nobody '
+            + 'discovers share_browser_view on their own. '
+            + 'OPTIONS — ' + renderBrowserOptions() + ' '
+            + 'Builder and custom CDP credentials are held in memory and are '
+            + 'never returned. '
+            + 'More: how_it_works({ topic: "browser" }).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -41,19 +120,41 @@ export function attachTool(state, builderClient, name = 'attach_browser', before
                 orgId: { type: 'string', format: 'uuid' },
                 cdpUrl: { type: 'string', maxLength: 4000 },
                 liveViewUrl: { type: 'string', format: 'uri', maxLength: 4000 },
+                countryCode: {
+                    type: 'string',
+                    pattern: '^[A-Za-z]{2}$',
+                    description: 'Builder mode only. ISO 3166-1 alpha-2 country the remote '
+                        + 'browser browses from, fixed for the whole session. Omit to '
+                        + 'get a suggested country back (needsChoice) instead of '
+                        + 'allocating a browser.',
+                },
+                skipCountry: {
+                    type: 'boolean',
+                    description: 'Builder mode only. Allocate without geo-routing, skipping '
+                        + 'the country prompt. Pass this once the developer has said '
+                        + 'they don\'t need a specific country.',
+                },
             },
         },
     }, async (parsed) => {
         const persisted = state.config.read()?.browser_agent;
-        const mode = parsed.mode ?? parsed.attachMode ?? persisted?.attachMode;
+        // Deliberately NOT falling back to the persisted mode: which browser
+        // to drive is the developer's call every time (a remote one costs
+        // quota, a local one exposes their own profile), and silently reusing
+        // last session's answer takes that decision away from them. The
+        // persisted choice is offered back as a default to suggest, not
+        // applied.
+        const mode = parsed.mode ?? parsed.attachMode;
         if (!mode) {
             return {
                 needsChoice: true,
-                message: 'Choose a browser mode and call attach_browser again: '
-                    + '"dedicated" launches a local dedicated Chrome profile; '
-                    + '"attach" connects to a local Chrome debugging port; '
-                    + '"builder" creates a quota-accounted remote browser and '
-                    + 'requires orgId; "custom" requires a CDP websocket URL.',
+                message: 'Ask the developer which browser to use, then call '
+                    + 'attach_browser again with their chosen `mode`. Present all '
+                    + 'the options below — do not pick one for them.',
+                options: BROWSER_OPTIONS,
+                ...(persisted?.attachMode
+                    ? { previouslyUsed: persisted.attachMode }
+                    : {}),
                 configPath: defaultConfigPath(),
             };
         }
@@ -80,6 +181,44 @@ export function attachTool(state, builderClient, name = 'attach_browser', before
             }
             orgId = orgs[0].id;
         }
+        // A remote browser's exit country is fixed for the whole session —
+        // Popcorn applies it at allocation and it can't be changed later. So
+        // confirm it with the developer BEFORE spending a quota-accounted
+        // browser on the wrong one, the same way orgId is confirmed above.
+        // Geo-routing is OPTIONAL though, so this asks rather than demands:
+        // `skipCountry` is the "no particular country" answer, and it must be
+        // as reachable as naming one.
+        if (mode === 'builder' && !parsed.countryCode && !parsed.skipCountry) {
+            const suggestion = await suggestCountryFromIp();
+            return {
+                needsChoice: true,
+                message: 'Ask the developer which country this browser should browse '
+                    + 'from — its egress is routed through that country for the '
+                    + 'whole session and cannot be changed afterwards. Geolocation '
+                    + 'is optional; offer all three answers below. Nothing has been '
+                    + 'allocated yet, so this costs nothing.',
+                choices: [
+                    {
+                        answer: 'The suggested country',
+                        howToCall: `attach_browser({ mode: "builder", countryCode: "${suggestion.countryCode}" })`,
+                    },
+                    {
+                        answer: 'A specific country the site must be seen from',
+                        howToCall: 'attach_browser({ mode: "builder", countryCode: "<ISO '
+                            + '3166-1 alpha-2>" })',
+                    },
+                    {
+                        answer: 'No particular country',
+                        howToCall: 'attach_browser({ mode: "builder", skipCountry: true })',
+                    },
+                ],
+                suggestedCountryCode: suggestion.countryCode,
+                suggestionSource: 'caller-ip',
+                ...(suggestion.country ? { country: suggestion.country } : {}),
+                ...(suggestion.region ? { region: suggestion.region } : {}),
+                ...(suggestion.city ? { city: suggestion.city } : {}),
+            };
+        }
         const next = await connect(mode, { ...parsed, orgId }, persisted, builderClient, dependencies);
         try {
             await beforeReplace?.();
@@ -103,6 +242,7 @@ export function attachTool(state, builderClient, name = 'attach_browser', before
                 ? { browserSessionId: next.browserSessionId }
                 : {}),
             ...(next.liveViewUrl ? { liveViewUrl: next.liveViewUrl } : {}),
+            ...(next.countryCode ? { countryCode: next.countryCode } : {}),
         };
     });
 }
@@ -118,8 +258,10 @@ async function connect(mode, parsed, persisted, builderClient, dependencies) {
     if (mode === 'builder') {
         assert(builderClient, badRequest('Builder browser service is unavailable'));
         assert(parsed.orgId, badRequest('orgId is required for builder mode'));
+        const countryCode = parsed.countryCode?.trim().toUpperCase();
         const { data } = await builderClient.call('CreateAgentBrowserSession', {
             params: { orgId: parsed.orgId },
+            body: countryCode ? { countryCode } : {},
         });
         let handles;
         try {
@@ -140,6 +282,8 @@ async function connect(mode, parsed, persisted, builderClient, dependencies) {
             liveViewUrl: data.liveViewUrl,
             browserSessionId: data.id,
             orgId: parsed.orgId,
+            ...(data.apiUrl ? { apiUrl: data.apiUrl } : {}),
+            ...(countryCode ? { countryCode } : {}),
             disposeRemote: async () => {
                 await builderClient.call('DisposeAgentBrowserSession', {
                     params: {

package/lib/mcp/tools/agent/build.d.ts

@@ -14,23 +14,28 @@ 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 (e.g. old-devtools) that supplies its own publish tool
- *  can build the attach/capture state up front and share the SAME instance
- *  with `buildAgentTools` — letting that publish tool see the live attach
- *  state (e.g. to remind the caller about a still-open browser session). */
+/** 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
+ *  instance with `buildAgentTools` — letting that publish tool see the live
+ *  attach state (for example, to remind the caller about a still-open browser
+ *  session). */
 export declare function buildAgentState(): AgentState;
 /** Build the flat list of `RegisteredTool` entries, ready for
  *  `registerToolList`.
  *  Pass `client` to include the builder `create_provider_version_from_capture`;
- *  omit it (e.g. OLD-devtools mode) to register only the backend-independent
- *  capture/proof tools — old mode supplies its own publish tool.
- *  Pass `externalState` to share attach/capture state with tools registered
- *  elsewhere (e.g. old mode's publish tool) instead of building a fresh one. */
+ *  omit it (for example, OLD-devtools mode) to register only the
+ *  backend-independent capture/proof tools — old mode supplies its own publish
+ *  tool. Pass `externalState` to share attach/capture state with tools
+ *  registered elsewhere (for example, old mode's publish tool) instead of
+ *  building a fresh one. */
 export declare function buildAgentTools(client?: ReclaimClient, builderClient?: ReclaimClient | undefined, externalState?: AgentState): RegisteredTool[];

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

@@ -16,26 +16,31 @@ import { attachTool } from "./attach.js";
 import { captureTools, resetCaptures } from "./capture.js";
 import { listTabsTool } from "./eval.js";
 import { howItWorksTool } from "./how-it-works.js";
+import { liveViewTools } from "./live-view.js";
+import { podProofTools } from "./pod-proof.js";
 import { createVersionFromCaptureTool } from "./publish.js";
 import { sessionTools } from "./session.js";
 import { sharedAuthoringTools } from "./shared.js";
-/** Exported so a mode (e.g. old-devtools) that supplies its own publish tool
- *  can build the attach/capture state up front and share the SAME instance
- *  with `buildAgentTools` — letting that publish tool see the live attach
- *  state (e.g. to remind the caller about a still-open browser session). */
+/** 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
+ *  instance with `buildAgentTools` — letting that publish tool see the live
+ *  attach state (for example, to remind the caller about a still-open browser
+ *  session). */
 export function buildAgentState() {
     return {
         attach: { config: new ConfigStore() },
         captures: { sessions: new Map() },
+        liveShare: {},
     };
 }
 /** Build the flat list of `RegisteredTool` entries, ready for
  *  `registerToolList`.
  *  Pass `client` to include the builder `create_provider_version_from_capture`;
- *  omit it (e.g. OLD-devtools mode) to register only the backend-independent
- *  capture/proof tools — old mode supplies its own publish tool.
- *  Pass `externalState` to share attach/capture state with tools registered
- *  elsewhere (e.g. old mode's publish tool) instead of building a fresh one. */
+ *  omit it (for example, OLD-devtools mode) to register only the
+ *  backend-independent capture/proof tools — old mode supplies its own publish
+ *  tool. Pass `externalState` to share attach/capture state with tools
+ *  registered elsewhere (for example, old mode's publish tool) instead of
+ *  building a fresh one. */
 export function buildAgentTools(client, builderClient = client, externalState) {
     const state = externalState ?? buildAgentState();
     ensureAttestorCrypto();
@@ -44,13 +49,19 @@ export function buildAgentTools(client, builderClient = client, externalState) {
     // client. No `client` ⇒ old-devtools mode (see `mcp/start.ts`).
     tools.push(howItWorksTool(!client));
     const beforeReplace = () => resetCaptures(state.captures);
-    tools.push(attachTool(state.attach, builderClient, 'attach_browser', beforeReplace));
-    tools.push(attachTool(state.attach, builderClient, 'attach_chrome', beforeReplace));
+    tools.push(attachTool(state.attach, builderClient, beforeReplace));
     tools.push(listTabsTool(state.attach));
     for (const t of captureTools(state.attach, state.captures)) {
         tools.push(t);
     }
-    for (const t of sessionTools(state.attach, state.captures)) {
+    for (const t of sessionTools(state.attach, state.captures, state.liveShare)) {
+        tools.push(t);
+    }
+    // Local-CDP only: a builder-mode browser already has a hosted live view.
+    for (const t of liveViewTools(state.attach, state.captures, state.liveShare)) {
+        tools.push(t);
+    }
+    for (const t of podProofTools(state.attach, state.captures)) {
         tools.push(t);
     }
     tools.push(analyzeTool(state.captures));

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

@@ -54,7 +54,11 @@ export function captureTools(attachRef, captures) {
     });
     const getTool = defineTool({
         name: 'get_request',
-        description: 'Return full headers + bodies for a specific captured request.',
+        description: 'Return the full headers and bodies of one captured request. Use it '
+            + 'to inspect a candidate that find_requests_containing ranked. '
+            + 'Unlike every other tool here, the headers are RAW — cookie and '
+            + 'authorization values are visible. Read them; never repeat them to '
+            + 'the developer or write them to a file.',
         inputSchema: {
             type: 'object',
             properties: {

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

@@ -5,7 +5,9 @@ import { defineTool } from "../../server.js";
 export function listTabsTool(attachRef) {
     return defineTool({
         name: 'list_tabs',
-        description: 'List open Chrome tabs.',
+        description: 'List the open tabs in the attached browser, with their tabId, title '
+            + 'and URL. Call it after attach_browser to pick the tabId to pass to '
+            + 'start_capture.',
         inputSchema: { type: 'object', properties: {} },
     }, async () => {
         if (!attachRef.current) {

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

@@ -15,9 +15,10 @@ export function findTool(resolveBackend) {
             + 'URL/JSON/HTML-escaped, …). Returns a ranked candidate list with '
             + 'the matched variant, score, and a short snippet — used to locate '
             + 'the request that returns a target. Also finds SPLIT matches: when '
-            + '`value` is multi-word (e.g. a full name), a response that carries '
-            + 'every word SEPARATELY (a JSON profile API with first/last name in '
-            + 'distinct fields) is returned with `splitMatch:true` — prove those '
+            + '`value` is multi-word (for example, a full name), a response '
+            + 'that carries every word SEPARATELY (a JSON profile API with '
+            + 'first and last name in distinct fields) is returned with '
+            + '`splitMatch:true` — prove those '
             + 'per-field (a redaction per part) rather than as one string. '
             + 'Server-side; bodies stay here.',
         inputSchema: objectSchema({ value: { type: 'string' }, limit: { type: 'number' } }, ['value']),
@@ -60,8 +61,8 @@ export function findTool(resolveBackend) {
                 });
                 continue;
             }
-            // Split match: every word present separately (e.g. first/last name
-            // in distinct JSON fields). Requires ≥2 tokens so it's specific.
+            // Split match: every word present separately (for example, first/last
+            // name in distinct JSON fields). Requires ≥2 tokens so it's specific.
             if (tokens.length >= 2 && tokens.every((t) => body.includes(t))) {
                 ranked.push({
                     ...publicRequest(r),