@reclaimprotocol/agent 0.1.22 → 0.1.24

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

@@ -1,11 +1,19 @@
 import { type RegisteredTool } from '../../server.ts';
 /**
- * Serves the full provider-authoring guide on demand. The MCP server's
- * always-on `instructions` are a terse tool-flow reference; this tool returns
- * the deep version (workflow, decision frameworks, gotchas, "never do" rules)
- * so any MCP client — not just Claude Code, which alone auto-loads skills — can
- * pull it. `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`.
+ * 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`.
  */
 export declare function howItWorksTool(oldMode: boolean): RegisteredTool;

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

@@ -1,24 +1,64 @@
-import { PROVIDER_GUIDE_BUILDER, PROVIDER_GUIDE_OLD, } from "../../instructions.js";
+import { guideFor } from "../../instructions.js";
 import { defineTool } from "../../server.js";
 /**
- * Serves the full provider-authoring guide on demand. The MCP server's
- * always-on `instructions` are a terse tool-flow reference; this tool returns
- * the deep version (workflow, decision frameworks, gotchas, "never do" rules)
- * so any MCP client — not just Claude Code, which alone auto-loads skills — can
- * pull it. `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`.
+ * 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`.
  */
 export function howItWorksTool(oldMode) {
-    const guide = oldMode ? PROVIDER_GUIDE_OLD : PROVIDER_GUIDE_BUILDER;
+    const guide = guideFor(oldMode);
+    const names = [...guide.topics.keys()];
     return defineTool({
         name: 'how_it_works',
-        description: 'Return the full Reclaim provider-authoring guide for THIS server: '
-            + 'the capture → draft → replay → prove → publish workflow, decision '
-            + 'frameworks (login detection, OPRF privacy, context vs bare params), '
-            + 'multi-request handling, troubleshooting, and what never to do. '
-            + 'Call this BEFORE building a provider unless you are already '
-            + 'fluent in the flow.',
-        inputSchema: { type: 'object', properties: {} },
-    }, async () => ({ guide }));
+        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.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                topic: {
+                    type: 'string',
+                    // Deliberately NOT an `enum`: schema validation runs before the
+                    // handler, so an enum turns a mistyped topic into a validation
+                    // error instead of a response carrying the real topic list. A
+                    // plain string lets the tool answer the mistake usefully.
+                    description: 'Which section to return: ' + names.join(', ')
+                        + ', or `all`. Omit for the overview + topic index. An '
+                        + 'unrecognized value comes back with the list, not an error.',
+                },
+            },
+        },
+    }, async ({ topic }) => {
+        if (topic === 'all') {
+            return { topic: 'all', topics: guide.index, guide: guide.full };
+        }
+        const requested = topic ?? 'overview';
+        const section = guide.topics.get(requested);
+        if (!section) {
+            // Not an error: hand back the index so the caller self-corrects in
+            // the same turn rather than retrying blind.
+            return {
+                error: `Unknown topic "${requested}".`,
+                topics: guide.index,
+                guide: guide.topics.get('overview'),
+            };
+        }
+        return { topic: requested, topics: guide.index, guide: section };
+    });
 }

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

@@ -0,0 +1,21 @@
+import { type Tunnel } from '../../../live/tunnel.ts';
+import { type LiveView } from '../../../live/viewer.ts';
+import { type RegisteredTool } from '../../server.ts';
+import type { AttachState } from './attach.ts';
+import type { CaptureStore } from './capture.ts';
+export interface LiveShare {
+    view: LiveView;
+    tunnel: Tunnel;
+    url: string;
+    interactive: boolean;
+    startedAt: number;
+}
+export interface LiveShareRef {
+    current?: LiveShare;
+}
+/** 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;
+}, captures: CaptureStore, shareRef: LiveShareRef): RegisteredTool[];

package/lib/mcp/tools/agent/live-view.js

@@ -0,0 +1,153 @@
+/**
+ * `share_browser_view` / `stop_browser_view` — put the LOCAL attached tab
+ * behind a public URL so someone who is not at this machine can watch it, and
+ * optionally drive it.
+ *
+ * Scoped to the CDP-attached modes (`dedicated`, `attach`, `custom`) on
+ * purpose. A `builder`-mode browser is a Popcorn pod that already ships its
+ * own hosted live view on `attach_browser`'s `liveViewUrl`; tunnelling a
+ * second one would duplicate it and burn a share URL for nothing, so this
+ * refuses and points at the one that exists.
+ *
+ * The share is deliberately explicit and single-instance: one live view per
+ * attached browser, started only when asked for, and torn down by
+ * `stop_browser_view`, `dispose_browser`, or `reset_session`.
+ */
+import { badRequest, conflict } from '@hapi/boom';
+import assert from 'node:assert';
+import { startTunnel } from "../../../live/tunnel.js";
+import { startLiveView } from "../../../live/viewer.js";
+import { LOGGER } from "../../../logger.js";
+import { defineTool } from "../../server.js";
+/** Modes whose browser we reach over our own CDP connection, and which
+ *  therefore have no hosted live view of their own. */
+const SHAREABLE_MODES = new Set(['dedicated', 'attach', 'custom']);
+/** Tear down whatever share is running. Safe when none is. Exported so the
+ *  session tools can call it from `dispose_browser` / `reset_session`. */
+export async function stopLiveShare(ref) {
+    const share = ref.current;
+    if (!share) {
+        return false;
+    }
+    ref.current = undefined;
+    await share.view.stop().catch((err) => {
+        LOGGER.warn({ err }, 'live view: server stop failed');
+    });
+    await share.tunnel.stop().catch((err) => {
+        LOGGER.warn({ err }, 'live view: tunnel stop failed');
+    });
+    return true;
+}
+export function liveViewTools(attachRef, captures, shareRef) {
+    return [
+        defineTool({
+            name: 'share_browser_view',
+            description: 'Put the attached tab behind a PUBLIC HTTPS URL (a cloudflared '
+                + 'quick tunnel) so someone elsewhere can watch it live, and by '
+                + 'default click and type in it. Use it to hand a login or a 2FA '
+                + 'step to the person who holds the credentials, or to let a '
+                + 'colleague watch a capture. Returns the URL — relay it to the '
+                + 'developer VERBATIM, on its own line. '
+                + 'ONLY for a locally attached browser (attach_browser mode '
+                + '`dedicated`, `attach`, or `custom`). In `builder` mode the '
+                + 'Popcorn browser already has a hosted live view: use the '
+                + '`liveViewUrl` that attach_browser returned instead. '
+                + 'THE URL IS A CREDENTIAL: anyone holding it can see this tab, '
+                + 'and with the default `interactive: true` can act in it as the '
+                + 'signed-in user. Share it only with the person who needs it, and '
+                + 'call stop_browser_view the moment they are done. Pass '
+                + '`interactive: false` for a watch-only link. '
+                + 'Needs cloudflared: an existing install on PATH is used as-is, '
+                + 'otherwise it is downloaded once to ~/.reclaim/bin on first '
+                + 'share (never at install time). Set RECLAIM_CLOUDFLARED_PATH to '
+                + 'point at your own copy instead.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    tabId: {
+                        type: 'string',
+                        description: 'Tab to stream, from list_tabs. Defaults to the tab the '
+                            + 'active capture is on, else the first tab.',
+                    },
+                    interactive: {
+                        type: 'boolean',
+                        description: 'Let the viewer click and type in the page. Default true. '
+                            + 'Set false to stream a read-only view.',
+                    },
+                },
+            },
+        }, async ({ tabId, interactive }) => {
+            const attached = attachRef.current;
+            assert(attached, badRequest('No browser attached. Call attach_browser first.'));
+            assert(SHAREABLE_MODES.has(attached.mode), badRequest(`share_browser_view does not apply to \`${attached.mode}\` mode. `
+                + 'That browser already has a hosted live view — use the '
+                + '`liveViewUrl` from attach_browser'
+                + (attached.liveViewUrl ? `: ${attached.liveViewUrl}` : '')
+                + '.'));
+            assert(!shareRef.current, conflict('A live view is already running at '
+                + `${shareRef.current?.url}. Call stop_browser_view first, or `
+                + 'reuse that URL.'));
+            const tabs = tabId || captures.activeTab
+                ? []
+                : await attached.handles.listTabs();
+            const target = tabId ?? captures.activeTab ?? tabs[0]?.tabId;
+            assert(target, badRequest('No tab to stream. Open a tab, or call list_tabs to pick one.'));
+            const tab = await attached.handles.attachToTab(target);
+            const wantsInput = interactive !== false;
+            const view = await startLiveView({
+                tab,
+                interactive: wantsInput,
+                title: `Reclaim — ${attached.mode} browser`,
+            });
+            let tunnel;
+            try {
+                tunnel = await startTunnel(view.port);
+            }
+            catch (err) {
+                // Don't leave the loopback server behind if the tunnel failed.
+                await view.stop().catch(() => { });
+                throw err;
+            }
+            const url = `${tunnel.url}${view.path}`;
+            const share = {
+                view, tunnel, url, interactive: wantsInput, startedAt: Date.now(),
+            };
+            shareRef.current = share;
+            LOGGER.info({ mode: attached.mode, interactive: wantsInput }, 'live view shared');
+            return {
+                url,
+                interactive: wantsInput,
+                tabId: target,
+                ...(share.tunnel.binary.source === 'downloaded'
+                    ? { cloudflaredInstalled: true }
+                    : {}),
+                ...(share.tunnel.ready ? {} : { propagating: true }),
+                _notes: [
+                    ...(share.tunnel.binary.source === 'downloaded'
+                        ? ['cloudflared was not installed, so it was downloaded once '
+                                + 'to ~/.reclaim/bin. Mention that; later shares reuse it.']
+                        : []),
+                    ...(share.tunnel.ready
+                        ? []
+                        : ['The tunnel had not started routing yet — if the URL '
+                                + 'errors, wait a few seconds and reload.']),
+                    'Relay `url` to the developer verbatim, on its own line.',
+                    'The URL is a credential: it needs no login, and anyone with '
+                        + 'it can see this tab'
+                        + (wantsInput ? ' and act in it as the signed-in user.' : '.'),
+                    'Call stop_browser_view when they are done — the tunnel stays '
+                        + 'open until you do.',
+                ],
+            };
+        }),
+        defineTool({
+            name: 'stop_browser_view',
+            description: 'Close the public live view opened by share_browser_view: stops '
+                + 'the screen stream and shuts the tunnel down, so the URL stops '
+                + 'resolving. Call it as soon as the person you shared with is '
+                + 'finished. The browser itself stays attached and the capture '
+                + 'keeps running.',
+            inputSchema: { type: 'object', properties: {} },
+        }, async () => ({ stopped: await stopLiveShare(shareRef) })),
+    ];
+}

package/lib/mcp/tools/agent/pod-proof.d.ts

@@ -0,0 +1,8 @@
+import type { ConfigStore } from '../../../config/store.ts';
+import { type RegisteredTool } from '../../server.ts';
+import type { AttachState } from './attach.ts';
+import type { CaptureStore } from './capture.ts';
+export declare function podProofTools(attachRef: {
+    current?: AttachState;
+    config: ConfigStore;
+}, captures: CaptureStore): RegisteredTool[];

package/lib/mcp/tools/agent/pod-proof.js

@@ -0,0 +1,64 @@
+/**
+ * Prove a drafted recipe through the Popcorn pod's OWN `/reclaim/prove` — the
+ * remote browser session's own API for creating a proof from that same
+ * session — instead of the local in-process attestor SDK (`run_proof`).
+ * Recommended for any `builder`-mode attach: the pod is the SAME enclave that
+ * holds the browser's TLS session, so proving there reaches the target from
+ * the identical exit IP the browser used — including the country-routed egress
+ * Popcorn applies when the session was allocated with a country. A local SDK
+ * proof runs from the agent's own network instead, which won't match a
+ * country-locked / IP-allowlisted target the remote browser could reach.
+ *
+ * Builder mode only (needs the attach's pod `apiUrl`, from
+ * `CreateAgentBrowserSession`) — throws a clear error otherwise rather than
+ * silently falling back to the local path.
+ */
+import { badRequest } from '@hapi/boom';
+import assert from 'node:assert';
+import { popcornProve } from "../../../proof/pod-prover.js";
+import { buildHttpParams } from "../../../proof/proof-core.js";
+import { defineTool } from "../../server.js";
+import { shapeRichProofResult } from "./proof.js";
+export function podProofTools(attachRef, captures) {
+    const tool = defineTool({
+        name: 'run_proof_via_pod',
+        description: 'Prove the drafted recipe through the Popcorn pod\'s own TEE '
+            + '(/reclaim/prove) instead of the local attestor SDK — this is '
+            + 'the remote browser session\'s own api for creating a proof '
+            + 'from that same session. Use this instead of run_proof '
+            + 'whenever this capture\'s '
+            + 'attach mode is "builder": the pod is the same enclave that '
+            + 'held the browser\'s TLS session (and its country-routed egress, '
+            + 'if any), so '
+            + 'the proof reaches the target from the browser\'s own exit IP. '
+            + 'No ownerAddress needed — the pod signs with the attestor\'s '
+            + 'own TEE key, not a local credential.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                captureId: { type: 'string' },
+                draftId: { type: 'string' },
+            },
+            required: ['captureId', 'draftId'],
+        },
+    }, async ({ captureId, draftId }) => {
+        const apiUrl = attachRef.current?.apiUrl;
+        assert(apiUrl, badRequest('No pod api available for this attach — run_proof_via_pod needs '
+            + 'mode "builder" (attach_browser), not local/custom CDP.'));
+        const entry = captures.sessions.get(captureId);
+        assert(entry, badRequest(`no capture ${captureId} — call start_capture first `
+            + '(it has been reset or never started).'));
+        const draft = entry.drafts.get(draftId);
+        assert(draft, badRequest(`no draft ${draftId} in capture ${captureId}`));
+        const result = await popcornProve({
+            apiUrl,
+            params: buildHttpParams(draft.provider),
+            secretParams: { headers: draft.secrets },
+        });
+        return shapeRichProofResult(result, {
+            provider: draft.provider,
+            hasSecrets: Object.keys(draft.secrets).length > 0,
+        });
+    });
+    return [tool];
+}

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

@@ -19,17 +19,40 @@ export function proposeTool(resolveBackend) {
             + 'one match + redaction per target. Returns a draftId + recipe '
             + '(never secrets). Prefer a SINGLE request holding ALL values. '
             + 'Single-value shorthand: `target` + `name`. Per-target `hash` '
-            + 'OPRF-hashes that value.',
+            + 'OPRF-hashes that value. BY DEFAULT each `name` is shortened to '
+            + 'its last alphanumeric token, lowercased, to form the param key '
+            + '(for example, "employer_name" → "name") — pick names that stay '
+            + 'distinct '
+            + 'after shortening ("firstName"/"surname", not "first_name"/'
+            + '"last_name"). Pass `shortenNames: false` to use each `name` '
+            + 'VERBATIM as the param key instead — it becomes both a regex '
+            + 'capture-group name and a paramValues key, so it must be a plain '
+            + 'identifier (letters/digits/underscore, not starting with a '
+            + 'digit); we recommend lower_snake_case (for example, '
+            + '"employer_name"), '
+            + 'but you choose the exact name.',
         inputSchema: objectSchema({
             requestId: { type: 'string' },
             name: { type: 'string' },
+            shortenNames: {
+                type: 'boolean',
+                description: 'Default true: shorten each target `name` to its last '
+                    + 'alphanumeric token, lowercased, to form the param key. '
+                    + 'Set false to use `name` verbatim instead (must be a plain '
+                    + 'identifier — lower_snake_case recommended).',
+            },
             targets: {
                 type: 'array',
                 items: {
                     type: 'object',
                     properties: {
                         value: { type: 'string' },
-                        name: { type: 'string' },
+                        name: {
+                            type: 'string',
+                            description: 'The param key, or the source of one — see '
+                                + '`shortenNames`. Must stay distinct from other targets\' '
+                                + 'names after whichever treatment applies.',
+                        },
                         hash: {
                             type: 'string',
                             enum: ['oprf-raw', 'oprf', 'oprf-mpc'],
@@ -46,6 +69,9 @@ export function proposeTool(resolveBackend) {
         const requestId = String(args.requestId);
         const providerName = String(args.name);
         const defaultHash = args.hash;
+        const shortenNames = typeof args.shortenNames === 'boolean'
+            ? args.shortenNames
+            : true;
         // Explicit multi-value `targets`, else the single `target` shorthand.
         const raw = Array.isArray(args.targets) ? args.targets : [];
         const targets = raw.length
@@ -85,7 +111,7 @@ export function proposeTool(resolveBackend) {
         if (!captured.responseBody) {
             throw new Error(`request body unavailable for ${requestId}`);
         }
-        const { provider, secretRefs, extractions } = draftProvider(captured, targets, providerName, defaultHash);
+        const { provider, secretRefs, extractions } = draftProvider(captured, targets, providerName, defaultHash, { shortenNames });
         // Materialize the real secret header values for later replay/prove;
         // they stay in the server-side draft, never in this result.
         const secrets = {};

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

@@ -0,0 +1,3 @@
+import { type RegisteredTool } from '../../server.ts';
+import type { CaptureStore } from './capture.ts';
+export declare function proxyTools(captures: CaptureStore): RegisteredTool[];

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

@@ -0,0 +1,199 @@
+/**
+ * Native browser-level network proxy for a capture's tab — separate from the
+ * attestor's own egress (`geoLocation`/`useProxy` on a published provider).
+ * Recommended for a Popcorn (`builder`-mode) remote browser session: applied
+ * via the Popcorn extension's `window.__pcn` page API so the browser stays
+ * in its existing kiosk-mode window instead of relaunching with a new proxy
+ * context — see `../../../cdp/browser-proxy.ts` for the mechanism.
+ *
+ * Username/password are ALWAYS explicit caller input — this module never
+ * reads `PROXY_PASSWORD` (there is no such getter) and never applies a
+ * proxy without the caller supplying credentials on the call itself. Env
+ * (`PROXY_SERVER`, `PROXY_USERNAME`) only supplies the vendor's routing
+ * endpoint and username TEMPLATE, for the "templated" convenience mode.
+ */
+import { badRequest } from '@hapi/boom';
+import assert from 'node:assert';
+import { applyBrowserProxy, buildTemplatedProxyUsername, clearBrowserProxy, generateProxySessionId, parseProxyServer, } from "../../../cdp/browser-proxy.js";
+import { suggestCountryFromIp } from "../../../cdp/geo.js";
+import { proxyServer, proxyUsernameTemplate } from "../../../consts.js";
+import { defineTool } from "../../server.js";
+/** `CdpTabClient.subscribe` is typed against a closed `CdpTabEventMap` of
+ *  known capture-engine events; this proxy module deliberately listens for
+ *  CDP `Fetch.*` events outside that map. Same shape of adapter as
+ *  `client.ts`'s `flattenedSessionClient` sender — forwarding a dynamic
+ *  method string the declared type doesn't literally cover. */
+function tabProxySender(tabClient) {
+    return {
+        send: (method, params) => tabClient.send(method, params),
+        subscribe: (method, listener) => {
+            return tabClient.subscribe(method, listener);
+        },
+    };
+}
+const COUNTRY_CODE_PATTERN = '^[A-Za-z]{2}$';
+export function proxyTools(captures) {
+    const requireCapture = (captureId) => {
+        const entry = captures.sessions.get(captureId);
+        assert(entry, badRequest(`no capture ${captureId} — call start_capture first `
+            + '(it has been reset or never started).'));
+        return entry;
+    };
+    const applyTool = defineTool({
+        name: 'apply_browser_proxy',
+        description: 'Route this capture\'s browser tab through a native network proxy. '
+            + 'Recommended for a Popcorn (builder-mode) remote browser session — '
+            + 'applied via the Popcorn extension so the browser stays in its '
+            + 'existing kiosk-mode window instead of relaunching. ALWAYS ask the '
+            + 'developer for the proxy `password`, and for `username` when using '
+            + '"full" mode — never invent or reuse a credential from elsewhere. '
+            + 'Two username modes: "full" (caller supplies the exact string) or '
+            + '"templated" (the server\'s PROXY_USERNAME env template combined '
+            + 'with `countryCode` and `proxySessionId`). Missing `countryCode` '
+            + '(templated mode only) and/or missing `proxySessionId` (always) '
+            + 'come back bundled in ONE `needsChoice` response — a best-known/IP '
+            + 'suggestion for country, and a random 10-character alphanumeric '
+            + 'suggestion for the sticky-session id (deliberately NOT this '
+            + 'capture\'s own id — vendors expect a short alphanumeric token, '
+            + 'and the same value later becomes the attestor\'s proxySessionId '
+            + 'too, so reusing it across calls keeps proofs on the same exit '
+            + 'IP the browser used). Ask the developer to confirm or override '
+            + 'each suggestion, then call again with them set. Reloads the '
+            + 'page once applied, since proxy routing only affects new '
+            + 'connections. Also arms proxy-auth handling over CDP `Fetch` '
+            + '(Popcorn\'s extension only sets host/port routing, not '
+            + 'credentials). Subsequent run_proof calls on this captureId '
+            + 'automatically prove through the same proxy session/country.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                captureId: { type: 'string' },
+                password: { type: 'string', minLength: 1 },
+                username: { type: 'string', minLength: 1 },
+                usernameMode: { type: 'string', enum: ['full', 'templated'] },
+                countryCode: {
+                    type: 'string',
+                    pattern: COUNTRY_CODE_PATTERN,
+                    description: '2-letter ISO country code, e.g. "US".',
+                },
+                proxySessionId: {
+                    type: 'string',
+                    minLength: 1,
+                    maxLength: 64,
+                    description: 'Sticky-session id — same value routes through the same '
+                        + 'exit IP, and later becomes the attestor\'s proxySessionId '
+                        + 'override too. Omit to get a random 10-character '
+                        + 'suggestion back instead of applying anything yet.',
+                },
+                host: {
+                    type: 'string',
+                    description: 'Override the PROXY_SERVER env default. Give both host and '
+                        + 'port, or neither.',
+                },
+                port: { type: 'number', minimum: 1, maximum: 65535 },
+            },
+            required: ['captureId', 'password'],
+        },
+    }, async (args) => {
+        const entry = requireCapture(args.captureId);
+        const mode = args.usernameMode ?? (args.username ? 'full' : 'templated');
+        let template;
+        if (mode === 'full') {
+            assert(args.username, badRequest('username is required when usernameMode is "full"'));
+        }
+        else {
+            template = proxyUsernameTemplate();
+            assert(template, badRequest('usernameMode "templated" needs PROXY_USERNAME configured in '
+                + 'the agent\'s environment. Use usernameMode "full" instead, or '
+                + 'set PROXY_USERNAME.'));
+        }
+        const countryCode = args.countryCode;
+        const needsCountrySuggestion = mode === 'templated' && !countryCode;
+        const needsSessionIdSuggestion = !args.proxySessionId;
+        if (needsCountrySuggestion || needsSessionIdSuggestion) {
+            let suggestedCountryCode;
+            if (needsCountrySuggestion) {
+                const suggestion = await suggestCountryFromIp();
+                suggestedCountryCode = suggestion.countryCode;
+            }
+            return {
+                needsChoice: true,
+                message: 'Confirm or override the suggestion(s) below, then call '
+                    + 'apply_browser_proxy again with them set.',
+                ...(suggestedCountryCode
+                    ? { suggestedCountryCode, suggestionSource: 'caller-ip' }
+                    : {}),
+                ...(needsSessionIdSuggestion
+                    ? { suggestedProxySessionId: generateProxySessionId() }
+                    : {}),
+            };
+        }
+        // Non-null: the `needsChoice` branch above already returned for every
+        // case where `proxySessionId`/`username`/`template`/`countryCode`
+        // (for the applicable mode) could be missing — TS can't see that
+        // across the bundled `needsCountrySuggestion || needsSessionIdSuggestion`
+        // check, since it narrows through direct property tests, not through
+        // intermediate boolean variables.
+        const proxySessionId = args.proxySessionId;
+        const username = mode === 'full'
+            ? args.username
+            : buildTemplatedProxyUsername({
+                template: template, countryCode: countryCode, proxySessionId,
+            });
+        let server;
+        if (args.host && args.port) {
+            server = { host: args.host, port: args.port };
+        }
+        else {
+            const raw = proxyServer();
+            assert(raw, badRequest('No host/port given and PROXY_SERVER is not configured in the '
+                + 'agent\'s environment.'));
+            server = parseProxyServer(raw);
+        }
+        const { appliedViaExtension } = await applyBrowserProxy(tabProxySender(entry.tabClient), {
+            host: server.host,
+            port: server.port,
+            username,
+            password: args.password,
+        });
+        entry.browserProxy = {
+            proxySessionId,
+            ...(countryCode ? { geoLocation: countryCode } : {}),
+        };
+        return {
+            applied: true,
+            appliedViaExtension,
+            host: server.host,
+            port: server.port,
+            maskedUsername: maskUsername(username),
+            ...(countryCode ? { countryCode } : {}),
+            proxySessionId,
+        };
+    });
+    const clearTool = defineTool({
+        name: 'clear_browser_proxy',
+        description: 'Undo apply_browser_proxy for this capture: route its tab direct '
+            + 'again, reload the page, and stop overriding run_proof\'s '
+            + 'geoLocation/proxySessionId.',
+        inputSchema: {
+            type: 'object',
+            properties: { captureId: { type: 'string' } },
+            required: ['captureId'],
+        },
+    }, async ({ captureId }) => {
+        const entry = requireCapture(captureId);
+        const sender = tabProxySender(entry.tabClient);
+        const { cleared } = await clearBrowserProxy(sender);
+        delete entry.browserProxy;
+        return { cleared };
+    });
+    return [applyTool, clearTool];
+}
+/** Never echo a full proxy username verbatim in a tool result — it may embed
+ *  the vendor account id. Short strings mask fully rather than leaking most
+ *  of themselves through the "keep first/last 4" rule. */
+function maskUsername(username) {
+    return username.length <= 8
+        ? '*'.repeat(username.length)
+        : `${username.slice(0, 4)}…${username.slice(-4)}`;
+}