npm - @reclaimprotocol/agent - Versions diffs - 0.1.24 → 0.1.26 - Mend

@reclaimprotocol/agent 0.1.24 → 0.1.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (55) hide show

package/README.md +5 -2
package/lib/cdp/claims.d.ts +21 -0
package/lib/cdp/claims.js +129 -0
package/lib/cdp/client.d.ts +0 -10
package/lib/cdp/container.d.ts +85 -0
package/lib/cdp/container.js +481 -0
package/lib/live/tunnel.d.ts +6 -3
package/lib/live/tunnel.js +57 -17
package/lib/mcp/instructions.js +2 -1
package/lib/mcp/start.js +58 -3
package/lib/mcp/tools/agent/attach.d.ts +22 -2
package/lib/mcp/tools/agent/attach.js +197 -55
package/lib/mcp/tools/agent/build.d.ts +5 -0
package/lib/mcp/tools/agent/build.js +9 -2
package/lib/mcp/tools/agent/index.d.ts +1 -2
package/lib/mcp/tools/agent/index.js +1 -1
package/lib/mcp/tools/agent/live-view.d.ts +3 -7
package/lib/mcp/tools/agent/live-view.js +74 -81
package/lib/mcp/tools/agent/session.d.ts +14 -0
package/lib/mcp/tools/agent/session.js +14 -8
package/lib/old/client.d.ts +83 -0
package/lib/old/client.js +46 -0
package/lib/old/tools/build.js +2 -0
package/lib/old/tools/session-logs.d.ts +3 -0
package/lib/old/tools/session-logs.js +310 -0
package/package.json +2 -2
package/skill/SKILL.common.md +115 -38
package/skill/SKILL.old.md +28 -2
package/skill/builder-mode.md +9 -7
package/skill/interception.md +3 -2
package/skill/old-mode.md +14 -10
package/src/cdp/claims.ts +153 -0
package/src/cdp/client.ts +0 -8
package/src/cdp/container.ts +593 -0
package/src/live/tunnel.ts +71 -20
package/src/mcp/instructions.ts +2 -1
package/src/mcp/start.ts +65 -2
package/src/mcp/tools/agent/attach.ts +229 -60
package/src/mcp/tools/agent/build.ts +10 -2
package/src/mcp/tools/agent/index.ts +6 -2
package/src/mcp/tools/agent/live-view.ts +77 -93
package/src/mcp/tools/agent/session.ts +14 -8
package/src/old/client.ts +128 -0
package/src/old/tools/build.ts +2 -0
package/src/old/tools/session-logs.ts +395 -0
package/lib/cdp/browser-proxy.d.ts +0 -78
package/lib/cdp/browser-proxy.js +0 -186
package/lib/live/page.d.ts +0 -20
package/lib/live/page.js +0 -134
package/lib/live/viewer.d.ts +0 -28
package/lib/live/viewer.js +0 -232
package/lib/mcp/tools/agent/proxy.d.ts +0 -3
package/lib/mcp/tools/agent/proxy.js +0 -199
package/src/live/page.ts +0 -145
package/src/live/viewer.ts +0 -293

package/lib/live/page.js DELETED Viewed

@@ -1,134 +0,0 @@
-/**
- * The live-view page served to whoever opens the tunnel URL.
- *
- * Deliberately dependency-free and inline: it is delivered through a throwaway
- * tunnel, so it cannot rely on a CDN, a bundler, or anything cached.
- *
- * Frames arrive as base64 JPEG over Server-Sent Events rather than a
- * WebSocket. SSE is one plain GET, so it survives tunnels and proxies that
- * mishandle upgrades, and it reconnects on its own. Input goes the other way
- * as small POSTs.
- */
-/** Escape a value for embedding in a single-quoted JS string literal. */
-function js(value) {
-    return value
-        .replace(/\\/g, '\\\\')
-        .replace(/'/g, "\\'")
-        .replace(/</g, '\\x3c');
-}
-export function renderViewerPage(opts) {
-    return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<meta name="robots" content="noindex, nofollow">
-<title>Reclaim live view</title>
-<style>
-  :root { color-scheme: dark; }
-  * { box-sizing: border-box; }
-  body { margin: 0; background: #0b0b0c; color: #e7e7ea; display: flex;
-    flex-direction: column; height: 100vh;
-    font: 14px/1.4 ui-sans-serif, system-ui, sans-serif; }
-  header { display: flex; align-items: center; gap: .75rem;
-    padding: .5rem .75rem; border-bottom: 1px solid #26262b; }
-  .dot { width: .5rem; height: .5rem; border-radius: 50%; background: #f5a524; }
-  .dot.live { background: #17c964; }
-  .title { color: #9a9aa4; overflow: hidden; text-overflow: ellipsis;
-    white-space: nowrap; }
-  .badge { margin-left: auto; font-size: 12px; padding: .15rem .4rem;
-    border: 1px solid #26262b; border-radius: .25rem; color: #9a9aa4; }
-  main { flex: 1; min-height: 0; display: grid; place-items: center;
-    padding: .75rem; }
-  img { max-width: 100%; max-height: 100%; display: block;
-    background: #fff; border-radius: .25rem; }
-  img.interactive { cursor: crosshair; }
-  .msg { color: #9a9aa4; }
-</style>
-</head>
-<body>
-<header>
-  <span class="dot" id="dot"></span>
-  <span class="title" id="title">${js(opts.title)}</span>
-  <span class="badge">${opts.interactive ? 'interactive' : 'view only'}</span>
-</header>
-<main><img id="screen" alt="Live view of the browser tab"><p class="msg"
-  id="msg">Connecting…</p></main>
-<script>
-(function () {
-  var BASE = '${js(opts.base)}';
-  var INTERACTIVE = ${opts.interactive ? 'true' : 'false'};
-  var screen = document.getElementById('screen');
-  var msg = document.getElementById('msg');
-  var dot = document.getElementById('dot');
-  var title = document.getElementById('title');
-  var es = new EventSource(BASE + '/stream');
-  es.addEventListener('frame', function (e) {
-    var payload = JSON.parse(e.data);
-    screen.src = 'data:image/jpeg;base64,' + payload.data;
-    if (payload.title) { title.textContent = payload.title; }
-    msg.style.display = 'none';
-    dot.className = 'dot live';
-  });
-  es.onerror = function () {
-    dot.className = 'dot';
-    msg.style.display = '';
-    msg.textContent = 'Reconnecting…';
-  };
-  if (!INTERACTIVE) { return; }
-  screen.className = 'interactive';
-  // The <img> is letterboxed by object-fit, so a click at some point in the
-  // element maps to page coordinates by the ratio of natural to rendered size.
-  function toPage(ev) {
-    var r = screen.getBoundingClientRect();
-    if (!screen.naturalWidth || !r.width) { return null; }
-    return {
-      x: Math.round((ev.clientX - r.left) * (screen.naturalWidth / r.width)),
-      y: Math.round((ev.clientY - r.top) * (screen.naturalHeight / r.height))
-    };
-  }
-  function post(body) {
-    return fetch(BASE + '/input', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify(body)
-    }).catch(function () {});
-  }
-  screen.addEventListener('mousedown', function (ev) {
-    var p = toPage(ev); if (!p) { return; }
-    ev.preventDefault();
-    post({ kind: 'mouse', type: 'mousePressed', x: p.x, y: p.y,
-      button: 'left', clickCount: 1 });
-  });
-  screen.addEventListener('mouseup', function (ev) {
-    var p = toPage(ev); if (!p) { return; }
-    post({ kind: 'mouse', type: 'mouseReleased', x: p.x, y: p.y,
-      button: 'left', clickCount: 1 });
-  });
-  screen.addEventListener('wheel', function (ev) {
-    var p = toPage(ev); if (!p) { return; }
-    ev.preventDefault();
-    post({ kind: 'mouse', type: 'mouseWheel', x: p.x, y: p.y,
-      deltaX: ev.deltaX, deltaY: ev.deltaY });
-  }, { passive: false });
-  // Typing goes to the page, so the viewer never needs to focus anything.
-  window.addEventListener('keydown', function (ev) {
-    if (ev.metaKey || ev.ctrlKey) { return; }
-    ev.preventDefault();
-    post({ kind: 'key', type: 'keyDown', key: ev.key, code: ev.code });
-  });
-  window.addEventListener('keyup', function (ev) {
-    if (ev.metaKey || ev.ctrlKey) { return; }
-    post({ kind: 'key', type: 'keyUp', key: ev.key, code: ev.code });
-  });
-})();
-</script>
-</body>
-</html>`;
-}

package/lib/live/viewer.d.ts DELETED Viewed

@@ -1,28 +0,0 @@
-import type { CdpTabClient } from '../cdp/client.ts';
-export interface LiveViewOptions {
-    /** The tab to stream. */
-    tab: CdpTabClient;
-    /** Forward viewer input into the page. */
-    interactive: boolean;
-    /** Shown in the viewer's header. */
-    title?: string;
-}
-export interface LiveView {
-    /** Loopback origin the tunnel should point at. */
-    localUrl: string;
-    /** Port the server bound to. */
-    port: number;
-    /** Unguessable path segment guarding every route. */
-    token: string;
-    /** Path prefix, `/v/<token>`. Append this to the public origin. */
-    path: string;
-    /** Number of viewers currently streaming. */
-    viewers: () => number;
-    stop: () => Promise<void>;
-}
-/**
- * Start the loopback live-view server for `tab`. Resolves once it is
- * listening; the screencast starts with the first viewer and stops with the
- * last, so an idle share costs the page nothing.
- */
-export declare function startLiveView(opts: LiveViewOptions): Promise<LiveView>;

package/lib/live/viewer.js DELETED Viewed

@@ -1,232 +0,0 @@
-/**
- * Interactive live view of one attached tab, over a public URL.
- *
- * Two halves:
- *  - OUT: CDP `Page.startScreencast` pushes JPEG frames; each is forwarded to
- *    every connected browser as a Server-Sent Event and acked back to CDP.
- *  - IN: the viewer POSTs pointer and key events, which are replayed into the
- *    page with `Input.dispatch*`.
- *
- * Only ever bound to 127.0.0.1. Reaching it from outside is the tunnel's job
- * (see `tunnel.ts`), and because a quick tunnel is unauthenticated, EVERY
- * route sits behind an unguessable token in the path. A request without it
- * gets a flat 404 — not a 401, which would confirm the server exists.
- *
- * Interactivity is the caller's choice. `interactive: false` still streams,
- * but the input route refuses, which is the right setting for showing someone
- * a run rather than handing them the wheel.
- */
-import { randomBytes } from 'node:crypto';
-import { createServer, } from 'node:http';
-import { LOGGER } from "../logger.js";
-import { renderViewerPage } from "./page.js";
-/** JPEG quality for streamed frames. 60 keeps a text-heavy page readable
- *  while staying small enough for a tunnel's uplink. */
-const FRAME_QUALITY = 60;
-/** Cap the streamed frame size. Screencast scales to fit, so this bounds
- *  bandwidth without changing the page's own layout viewport. */
-const MAX_FRAME_WIDTH = 1280;
-const MAX_FRAME_HEIGHT = 800;
-/** Bytes accepted on an input POST. Events are tiny; anything larger is
- *  either a bug or someone probing. */
-const MAX_INPUT_BYTES = 4096;
-/**
- * Start the loopback live-view server for `tab`. Resolves once it is
- * listening; the screencast starts with the first viewer and stops with the
- * last, so an idle share costs the page nothing.
- */
-export async function startLiveView(opts) {
-    const token = randomBytes(24).toString('base64url');
-    const path = `/v/${token}`;
-    const clients = new Set();
-    let streaming = false;
-    let unsubscribe;
-    const startScreencast = async () => {
-        if (streaming) {
-            return;
-        }
-        streaming = true;
-        unsubscribe = opts.tab.subscribe('Page.screencastFrame', (frame) => {
-            // Ack first: CDP sends at most one un-acked frame, so a slow or failed
-            // write must not stall the stream.
-            void opts.tab
-                .send('Page.screencastFrameAck', { sessionId: frame.sessionId })
-                .catch(() => { });
-            const payload = JSON.stringify({ data: frame.data });
-            for (const res of clients) {
-                res.write(`event: frame\ndata: ${payload}\n\n`);
-            }
-        });
-        await opts.tab.send('Page.enable');
-        await opts.tab.send('Page.startScreencast', {
-            format: 'jpeg',
-            quality: FRAME_QUALITY,
-            maxWidth: MAX_FRAME_WIDTH,
-            maxHeight: MAX_FRAME_HEIGHT,
-            everyNthFrame: 1,
-        });
-    };
-    const stopScreencast = async () => {
-        if (!streaming) {
-            return;
-        }
-        streaming = false;
-        unsubscribe?.();
-        unsubscribe = undefined;
-        await opts.tab.send('Page.stopScreencast').catch(() => { });
-    };
-    const server = createServer((req, res) => {
-        const url = req.url ?? '/';
-        // Constant prefix check: everything is scoped under the token, so an
-        // unmatched path is indistinguishable from a server that isn't there.
-        if (!url.startsWith(path)) {
-            res.writeHead(404).end('not found');
-            return;
-        }
-        const route = url.slice(path.length) || '/';
-        if (req.method === 'GET' && (route === '/' || route.startsWith('/?'))) {
-            const body = renderViewerPage({
-                base: path,
-                interactive: opts.interactive,
-                title: opts.title ?? 'Attached tab',
-            });
-            res.writeHead(200, {
-                'content-type': 'text/html; charset=utf-8',
-                // A share URL must never be cached or indexed by anything between
-                // the viewer and here.
-                'cache-control': 'no-store',
-                'referrer-policy': 'no-referrer',
-            }).end(body);
-            return;
-        }
-        if (req.method === 'GET' && route === '/stream') {
-            res.writeHead(200, {
-                'content-type': 'text/event-stream',
-                'cache-control': 'no-store',
-                connection: 'keep-alive',
-                // Defeat proxy buffering, which would otherwise hold frames back.
-                'x-accel-buffering': 'no',
-            });
-            res.write(': connected\n\n');
-            clients.add(res);
-            void startScreencast().catch((err) => {
-                LOGGER.warn({ err }, 'live view: screencast failed to start');
-            });
-            req.on('close', () => {
-                clients.delete(res);
-                if (!clients.size) {
-                    void stopScreencast();
-                }
-            });
-            return;
-        }
-        if (req.method === 'POST' && route === '/input') {
-            if (!opts.interactive) {
-                res.writeHead(403).end('view only');
-                return;
-            }
-            readJson(req, MAX_INPUT_BYTES)
-                .then((body) => dispatchInput(opts.tab, body))
-                .then(() => res.writeHead(204).end())
-                .catch((err) => {
-                LOGGER.debug({ err }, 'live view: input rejected');
-                res.writeHead(400).end('bad input');
-            });
-            return;
-        }
-        res.writeHead(404).end('not found');
-    });
-    await new Promise((resolve) => {
-        server.listen(0, '127.0.0.1', resolve);
-    });
-    const port = server.address().port;
-    return {
-        localUrl: `http://127.0.0.1:${port}`,
-        port,
-        token,
-        path,
-        viewers: () => clients.size,
-        stop: async () => {
-            await stopScreencast();
-            for (const res of clients) {
-                res.end();
-            }
-            clients.clear();
-            await closeServer(server);
-        },
-    };
-}
-function closeServer(server) {
-    return new Promise((resolve) => {
-        server.close(() => resolve());
-        // A held-open SSE response would otherwise keep the server alive.
-        server.closeAllConnections?.();
-    });
-}
-function readJson(req, limit) {
-    return new Promise((resolve, reject) => {
-        let size = 0;
-        const chunks = [];
-        req.on('data', (chunk) => {
-            size += chunk.length;
-            if (size > limit) {
-                reject(new Error('input too large'));
-                req.destroy();
-                return;
-            }
-            chunks.push(chunk);
-        });
-        req.on('end', () => {
-            try {
-                resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
-            }
-            catch (err) {
-                reject(err instanceof Error ? err : new Error('bad json'));
-            }
-        });
-        req.on('error', reject);
-    });
-}
-/** Replay one viewer event into the page. Unknown shapes throw, so the route
- *  answers 400 rather than forwarding something arbitrary to CDP. */
-async function dispatchInput(tab, body) {
-    const num = (v) => (typeof v === 'number' && Number.isFinite(v)
-        ? v
-        : 0);
-    if (body.kind === 'mouse') {
-        const type = String(body.type);
-        if (!['mousePressed', 'mouseReleased', 'mouseMoved', 'mouseWheel']
-            .includes(type)) {
-            throw new Error(`unsupported mouse type ${type}`);
-        }
-        await tab.send('Input.dispatchMouseEvent', {
-            type,
-            x: num(body.x),
-            y: num(body.y),
-            button: type === 'mouseWheel' ? 'none' : 'left',
-            clickCount: type === 'mouseWheel' ? 0 : 1,
-            ...(type === 'mouseWheel'
-                ? { deltaX: num(body.deltaX), deltaY: num(body.deltaY) }
-                : {}),
-        });
-        return;
-    }
-    if (body.kind === 'key') {
-        const type = String(body.type);
-        if (type !== 'keyDown' && type !== 'keyUp') {
-            throw new Error(`unsupported key type ${type}`);
-        }
-        const key = String(body.key ?? '');
-        // A single printable character needs `text` as well, or the page sees the
-        // keypress but no character is inserted.
-        const text = key.length === 1 ? key : undefined;
-        await tab.send('Input.dispatchKeyEvent', {
-            type,
-            key,
-            code: String(body.code ?? ''),
-            ...(text && type === 'keyDown' ? { text } : {}),
-        });
-        return;
-    }
-    throw new Error('unknown event kind');
-}

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

@@ -1,3 +0,0 @@
-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 DELETED Viewed

@@ -1,199 +0,0 @@
-/**
- * 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)}`;
-}