@browserless.io/mcp 1.6.0

package/build/src/lib/agent-client.js

@@ -0,0 +1,530 @@
+import WebSocket from 'ws';
+import { z } from 'zod';
+import { createSkillState } from '../skills/index.js';
+import { hashToken, isMeaningfulBody } from './utils.js';
+/* ------------------------------------------------------------------ */
+/*  Proxy schemas — used by agent.ts's AgentParamsSchema and by the    */
+/*  session key fingerprinting below. Co-located here to avoid a       */
+/*  circular dep with agent.ts.                                         */
+/* ------------------------------------------------------------------ */
+const ProxyOptionsObjectSchema = z.object({
+    proxy: z
+        .enum(['residential'])
+        .optional()
+        .describe('Routing tier. Only "residential" is supported today.'),
+    proxyCountry: z
+        .string()
+        .regex(/^[A-Za-z]{2}$/, 'Must be a 2-letter ISO-2 country code')
+        .transform((v) => v.toLowerCase())
+        .optional()
+        .describe('ISO-2 country code (e.g. "us", "de"). Normalized to lowercase.'),
+    proxyState: z
+        .string()
+        .optional()
+        .describe('US state name (whitespace replaced with underscores, e.g. "new_york"). ' +
+        'Plan-gated — non-eligible tokens get a 401.'),
+    proxyCity: z
+        .string()
+        .optional()
+        .describe('City-level targeting. Requires paid/enterprise plan — non-eligible tokens get a 401.'),
+    proxySticky: z
+        .boolean()
+        .optional()
+        .describe('Stable IP while the underlying WebSocket stays open. Reconnects ' +
+        '(idle drop, network blip, browser crash) allocate a new sticky id.'),
+    proxyLocaleMatch: z
+        .boolean()
+        .optional()
+        .describe('Match navigator locale to the proxy IP country.'),
+    proxyPreset: z
+        .string()
+        .optional()
+        .describe('Named proxy preset (e.g. "px_amazon01"). Supported presets are ' +
+        'plan-dependent; ask Browserless support for the list available to your token.'),
+    externalProxyServer: z
+        .string()
+        .regex(/^https?:\/\//i, 'externalProxyServer must start with http:// or https://')
+        .optional()
+        .describe('Bring-your-own upstream, e.g. http://user:pass@host:port'),
+});
+const DEPENDENT_PROXY_FIELDS = [
+    'proxyCountry',
+    'proxyState',
+    'proxyCity',
+    'proxySticky',
+    'proxyLocaleMatch',
+    'proxyPreset',
+];
+export const ProxyOptionsSchema = ProxyOptionsObjectSchema.refine((v) => {
+    const hasDependent = DEPENDENT_PROXY_FIELDS.some((k) => v[k] !== undefined);
+    return (!hasDependent || v.proxy === 'residential' || !!v.externalProxyServer);
+}, {
+    message: 'proxyCountry/proxyState/proxyCity/proxySticky/proxyLocaleMatch/proxyPreset ' +
+        "require proxy: 'residential' or externalProxyServer to be set; otherwise the API silently ignores them.",
+});
+export const PROXY_FIELDS = Object.keys(ProxyOptionsObjectSchema.shape);
+/**
+ * Thrown when the agent WebSocket upgrade is rejected with a non-101 HTTP
+ * response. Carries the status code and body so the tool layer can render a
+ * status-specific UserError.
+ */
+export class UpgradeError extends Error {
+    statusCode;
+    statusMessage;
+    body;
+    constructor(statusCode, statusMessage, body) {
+        const detail = body.trim() || statusMessage || 'no body';
+        super(`Agent WebSocket upgrade rejected: HTTP ${statusCode} — ${detail}`);
+        this.statusCode = statusCode;
+        this.statusMessage = statusMessage;
+        this.body = body;
+        this.name = 'UpgradeError';
+    }
+}
+/**
+ * UpgradeError specialization for the profile-not-found case (404 on the WS
+ * upgrade when `?profile=` was supplied). Mirrors api-client.ts so all tools
+ * surface profile errors through the same UserError pattern.
+ */
+export class ProfileNotFoundError extends UpgradeError {
+    profile;
+    constructor(profile, statusMessage, body) {
+        super(404, statusMessage, body);
+        this.profile = profile;
+        this.name = 'ProfileNotFoundError';
+        const trimmed = body.trim();
+        this.message = isMeaningfulBody(trimmed)
+            ? trimmed
+            : `Profile "${profile}" was not found for the configured token.`;
+    }
+}
+// Upgrade statuses where a one-shot retry cannot help: bad request (400),
+// bad auth (401), forbidden by plan/policy (403), or missing resource (404).
+// Retrying just wastes time and emits a misleading "second attempt failed".
+const NON_RETRYABLE_UPGRADE_STATUSES = new Set([400, 401, 403, 404]);
+export const isRetryableUpgradeError = (err) => {
+    if (err instanceof UpgradeError) {
+        return !NON_RETRYABLE_UPGRADE_STATUSES.has(err.statusCode);
+    }
+    return true;
+};
+const sessions = new Map();
+// In-flight session creations keyed by session key. Concurrent
+// getOrCreateSession callers await the same promise instead of each
+// opening their own WebSocket.
+const pending = new Map();
+const DEFAULT_TIMEOUT = 60_000;
+const IDLE_TTL_MS = 15 * 60 * 1000;
+const MAX_SESSIONS = 500;
+const closeAndDelete = (key, reason) => {
+    const session = sessions.get(key);
+    if (!session)
+        return;
+    try {
+        session.ws.close();
+    }
+    catch {
+        /* ignore */
+    }
+    sessions.delete(key);
+    console.error(`[agent-client] evicted session key=${key} reason=${reason}`);
+};
+// Sweep idle sessions and enforce a hard cap. Called on every
+// getOrCreateSession; cheap because the map is bounded.
+const sweepSessions = () => {
+    const now = Date.now();
+    for (const [key, session] of sessions) {
+        if (now - session.lastUsedAt > IDLE_TTL_MS) {
+            closeAndDelete(key, 'idle');
+        }
+    }
+    if (sessions.size <= MAX_SESSIONS)
+        return;
+    const overage = sessions.size - MAX_SESSIONS;
+    const oldest = [...sessions.entries()]
+        .sort(([, a], [, b]) => a.lastUsedAt - b.lastUsedAt)
+        .slice(0, overage);
+    for (const [key] of oldest) {
+        closeAndDelete(key, 'cap');
+    }
+};
+// Separator between the host segment (mcpSessionId or stdio:<hash>) and
+// the proxy fingerprint in a session key. NUL is illegal in any
+// user-supplied field, so the two segments cannot ambiguously concatenate.
+const KEY_SEP = '\u0000';
+// Hash externalProxyServer rather than serialize it raw: the session key is
+// logged on eviction and the URL may carry user:pass credentials. Hashing
+// keeps per-upstream distinctness without putting secrets in stderr.
+const fingerprintValue = (field, value) => field === 'externalProxyServer'
+    ? `external#${hashToken(String(value))}`
+    : String(value);
+/**
+ * Build a stable, credential-free key segment for a proxy config — identical
+ * configs fingerprint the same regardless of key order. `externalProxyServer`
+ * is SHA-256 hashed so credentials never land in the eviction log.
+ */
+export const proxyFingerprint = (proxy) => {
+    if (!proxy)
+        return '';
+    const parts = PROXY_FIELDS.map((k) => proxy[k] === undefined ? null : `${k}=${fingerprintValue(k, proxy[k])}`).filter(Boolean);
+    return parts.length ? KEY_SEP + parts.join('&') : '';
+};
+// Hash the profile rather than serialize it raw: like externalProxyServer,
+// the eviction-logged session key may otherwise leak a user-identifying
+// profile name. Hashing keeps per-profile distinctness without that leak.
+const getSessionKey = (mcpSessionId, token, proxy, profile) => (mcpSessionId ?? `stdio:${hashToken(token)}`) +
+    proxyFingerprint(proxy) +
+    (profile ? KEY_SEP + 'profile#' + hashToken(profile) : '');
+/**
+ * Build the WebSocket URL for `/chromium/agent`: normalize trailing slashes,
+ * swap http(s)→ws(s), and append `token` plus proxy params. Boolean proxy
+ * flags follow the API's presence-only contract (set only when truthy).
+ */
+export const buildAgentWsUrl = (apiUrl, token, proxy, profile) => {
+    const base = apiUrl.replace(/^http/i, 'ws').replace(/\/+$/, '');
+    const url = new URL(base + '/chromium/agent');
+    url.searchParams.set('token', token);
+    if (proxy?.proxy)
+        url.searchParams.set('proxy', proxy.proxy);
+    if (proxy?.proxyCountry)
+        url.searchParams.set('proxyCountry', proxy.proxyCountry);
+    if (proxy?.proxyState)
+        url.searchParams.set('proxyState', proxy.proxyState);
+    if (proxy?.proxyCity)
+        url.searchParams.set('proxyCity', proxy.proxyCity);
+    if (proxy?.proxySticky)
+        url.searchParams.set('proxySticky', 'true');
+    if (proxy?.proxyLocaleMatch)
+        url.searchParams.set('proxyLocaleMatch', 'true');
+    if (proxy?.proxyPreset)
+        url.searchParams.set('proxyPreset', proxy.proxyPreset);
+    if (proxy?.externalProxyServer)
+        url.searchParams.set('externalProxyServer', proxy.externalProxyServer);
+    if (profile)
+        url.searchParams.set('profile', profile);
+    return url.toString();
+};
+// HTTP-status failures arrive on `unexpected-response` (typed as
+// UpgradeError), so a 1006 close here only means a transport failure or a
+// server crash before any HTTP response.
+const describeConnectCloseCode = (code, reason) => {
+    if (reason)
+        return `code=${code}, reason="${reason}"`;
+    if (code === 1006)
+        return 'code=1006 (abnormal close before HTTP response — likely a network failure or server crash)';
+    if (code === 1008)
+        return 'code=1008 (policy violation)';
+    if (code === 1011)
+        return 'code=1011 (server error during upgrade)';
+    return `code=${code}`;
+};
+// Decode the Node `Error.code` field that `ws` propagates from the underlying
+// socket on transport failure (DNS, refused connection, TLS validation).
+const describeConnectErrorCode = (err) => {
+    if (!err || typeof err !== 'object')
+        return;
+    const code = err.code;
+    if (typeof code !== 'string')
+        return;
+    switch (code) {
+        case 'ENOTFOUND':
+            return 'DNS resolution failed (ENOTFOUND) — verify the apiUrl host';
+        case 'ECONNREFUSED':
+            return 'Connection refused (ECONNREFUSED) — server may be down or the port is blocked';
+        case 'ETIMEDOUT':
+            return 'Connection timed out (ETIMEDOUT) — network or firewall issue';
+        case 'ECONNRESET':
+            return 'Connection reset by peer (ECONNRESET)';
+        case 'CERT_HAS_EXPIRED':
+            return 'TLS certificate expired (CERT_HAS_EXPIRED)';
+        case 'UNABLE_TO_VERIFY_LEAF_SIGNATURE':
+        case 'DEPTH_ZERO_SELF_SIGNED_CERT':
+        case 'SELF_SIGNED_CERT_IN_CHAIN':
+            return `TLS verification failed (${code})`;
+        default:
+            return `network error (${code})`;
+    }
+};
+// Bound the body buffer so a misbehaving or malicious server can't OOM the
+// MCP process by streaming gigabytes into an error response. 64 KiB is far
+// more than any legitimate plain-text error or sanitized HTML page needs.
+const MAX_UPGRADE_BODY_BYTES = 64 * 1024;
+const TRUNCATION_MARKER = `\n…[response truncated at ${MAX_UPGRADE_BODY_BYTES} bytes]`;
+const READ_TIMEOUT_MARKER = '\n…[response body read timed out]';
+// Bound the body-read phase so a server that sends non-101 headers and then
+// stalls the body stream can't hang connect() indefinitely. The connect-level
+// 30s timeout has already been cleared by the time we get here.
+const UPGRADE_BODY_READ_TIMEOUT_MS = 10_000;
+const readUpgradeError = (res, profile) => new Promise((resolve) => {
+    const chunks = [];
+    let total = 0;
+    let truncated = false;
+    let timedOut = false;
+    let settled = false;
+    const readTimeout = setTimeout(() => {
+        if (settled)
+            return;
+        timedOut = true;
+        // res.destroy() fires 'close' → finish() → resolve with whatever
+        // bytes arrived before the deadline.
+        res.destroy();
+    }, UPGRADE_BODY_READ_TIMEOUT_MS);
+    const onData = (chunk) => {
+        if (settled)
+            return;
+        total += chunk.length;
+        if (total > MAX_UPGRADE_BODY_BYTES) {
+            const overflow = total - MAX_UPGRADE_BODY_BYTES;
+            chunks.push(chunk.subarray(0, chunk.length - overflow));
+            truncated = true;
+            // Resolve eagerly with the truncated payload — `res.destroy()` may
+            // suppress the 'end' event, so don't wait for it.
+            res.destroy();
+            finish();
+            return;
+        }
+        chunks.push(chunk);
+    };
+    const onError = (err) => {
+        // Stream errors mid-body (TLS abort, decompression failure) would
+        // otherwise vanish into an UpgradeError with a partial body. Log so
+        // operators see the root cause; still settle with whatever was buffered.
+        console.error(`[agent-client] upgrade-response stream error: ${err.message}`);
+        finish();
+    };
+    const finish = () => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(readTimeout);
+        res.off('data', onData);
+        res.off('end', finish);
+        res.off('error', onError);
+        res.off('close', finish);
+        // Some upstream stacks prepend an extra CRLF between the header block
+        // and the body — trim so renderers don't open with a blank line.
+        let body = Buffer.concat(chunks).toString('utf8').trim();
+        if (truncated)
+            body += TRUNCATION_MARKER;
+        else if (timedOut)
+            body += READ_TIMEOUT_MARKER;
+        const status = res.statusCode ?? 0;
+        const statusMessage = res.statusMessage ?? '';
+        if (status === 404 && profile) {
+            resolve(new ProfileNotFoundError(profile, statusMessage, body));
+            return;
+        }
+        resolve(new UpgradeError(status, statusMessage, body));
+    };
+    res.on('data', onData);
+    res.on('end', finish);
+    res.on('error', onError);
+    // `res.destroy()` can fire 'close' without 'end' or 'error'; settle here too.
+    res.on('close', finish);
+});
+const connect = (apiUrl, token, proxy, profile) => new Promise((resolve, reject) => {
+    const wsUrl = buildAgentWsUrl(apiUrl, token, proxy, profile);
+    const ws = new WebSocket(wsUrl);
+    let settled = false;
+    const settle = (err, value) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timeout);
+        if (err) {
+            try {
+                ws.terminate();
+            }
+            catch {
+                /* ignore */
+            }
+            reject(err);
+        }
+        else {
+            resolve(value);
+        }
+    };
+    const timeout = setTimeout(() => {
+        settle(new Error('Agent WebSocket connection timed out after 30s'));
+    }, 30_000);
+    ws.on('open', () => settle(null, ws));
+    // Claim `settled` synchronously so the close/error events that race the
+    // async body read can't overwrite the typed UpgradeError we're building.
+    ws.on('unexpected-response', (_req, res) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timeout);
+        readUpgradeError(res, profile).then((err) => {
+            try {
+                ws.terminate();
+            }
+            catch {
+                /* ignore */
+            }
+            reject(err);
+        });
+    });
+    ws.on('error', (err) => {
+        const decoded = describeConnectErrorCode(err);
+        const detail = decoded ?? err.message ?? '';
+        settle(new Error(`Agent WebSocket connection failed${detail ? `: ${detail}` : ''}`));
+    });
+    // Close before settle means the transport dropped without ever producing
+    // an HTTP response; auth/proxy/profile failures are handled by the
+    // `unexpected-response` branch above.
+    ws.on('close', (code, reason) => {
+        settle(new Error(`Agent WebSocket closed during connect: ${describeConnectCloseCode(code, reason?.toString('utf8') || '')}`));
+    });
+});
+const sendMessage = (ws, msg, timeoutMs = DEFAULT_TIMEOUT) => new Promise((resolve, reject) => {
+    const cleanup = () => {
+        clearTimeout(timeout);
+        ws.off('message', handler);
+        ws.off('close', closeHandler);
+    };
+    const timeout = setTimeout(() => {
+        cleanup();
+        reject(new Error(`Agent command "${msg.method}" timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    const closeHandler = () => {
+        cleanup();
+        reject(new Error(`WebSocket closed while waiting for "${msg.method}" response`));
+    };
+    const handler = (data) => {
+        let response;
+        const raw = data.toString('utf8');
+        try {
+            response = JSON.parse(raw);
+        }
+        catch {
+            console.error('[agent-client] dropping unparseable WS frame:', raw.slice(0, 200));
+            return;
+        }
+        // Only accept the response whose id matches the request we sent.
+        if (response.id !== msg.id)
+            return;
+        cleanup();
+        resolve(response);
+    };
+    ws.on('message', handler);
+    ws.on('close', closeHandler);
+    ws.send(JSON.stringify(msg));
+});
+export const getOrCreateSession = async (mcpSessionId, apiUrl, token, proxy, profile) => {
+    sweepSessions();
+    const key = getSessionKey(mcpSessionId, token, proxy, profile);
+    const existing = sessions.get(key);
+    if (existing && existing.ws.readyState === WebSocket.OPEN) {
+        existing.lastUsedAt = Date.now();
+        return existing;
+    }
+    // Another caller is already creating a session for this key — share it.
+    const inFlight = pending.get(key);
+    if (inFlight)
+        return inFlight;
+    // Clean up stale session if any
+    if (existing) {
+        try {
+            existing.ws.close();
+        }
+        catch {
+            /* ignore */
+        }
+        sessions.delete(key);
+    }
+    const creation = (async () => {
+        const ws = await connect(apiUrl, token, proxy, profile);
+        const session = {
+            ws,
+            msgId: 0,
+            apiUrl,
+            token,
+            proxy,
+            profile,
+            skillState: createSkillState(),
+            lastUsedAt: Date.now(),
+        };
+        // Auto-cleanup on close
+        ws.on('close', (code, reason) => {
+            if (code !== 1000) {
+                console.error(`[agent-client] WebSocket closed unexpectedly: code=${code} reason=${reason?.toString('utf8') || 'none'}`);
+            }
+            const current = sessions.get(key);
+            if (current?.ws === ws) {
+                sessions.delete(key);
+            }
+        });
+        sessions.set(key, session);
+        return session;
+    })();
+    pending.set(key, creation);
+    try {
+        return await creation;
+    }
+    finally {
+        // Clear the placeholder whether connect succeeded or threw, so a failed
+        // attempt doesn't block future retries.
+        if (pending.get(key) === creation) {
+            pending.delete(key);
+        }
+    }
+};
+export const send = async (session, method, params = {}, timeoutMs) => {
+    if (session.ws.readyState !== WebSocket.OPEN) {
+        if (!session.reconnecting) {
+            session.reconnecting = connect(session.apiUrl, session.token, session.proxy, session.profile).finally(() => {
+                session.reconnecting = undefined;
+            });
+        }
+        const ws = await session.reconnecting;
+        if (session.ws !== ws) {
+            session.ws = ws;
+            session.msgId = 0;
+            const key = [...sessions.entries()].find(([, s]) => s === session)?.[0];
+            if (key) {
+                ws.on('close', () => {
+                    const current = sessions.get(key);
+                    if (current?.ws === ws) {
+                        sessions.delete(key);
+                    }
+                });
+            }
+        }
+    }
+    session.msgId++;
+    session.lastUsedAt = Date.now();
+    return sendMessage(session.ws, { id: session.msgId, method, params }, timeoutMs);
+};
+export const closeSession = (mcpSessionId, token, proxy, profile) => {
+    const key = getSessionKey(mcpSessionId, token, proxy, profile);
+    const session = sessions.get(key);
+    if (session) {
+        try {
+            session.ws.close();
+        }
+        catch {
+            /* ignore */
+        }
+        sessions.delete(key);
+    }
+};
+/**
+ * Force-destroy a session after a browser crash or unrecoverable state, so
+ * the next call reconnects fresh. Unlike `closeSession`, it also drops any
+ * in-flight connect for the key so a concurrent caller can't reuse a dead WS.
+ */
+export const destroySession = (mcpSessionId, token, proxy, profile) => {
+    const key = getSessionKey(mcpSessionId, token, proxy, profile);
+    const session = sessions.get(key);
+    if (session) {
+        try {
+            session.ws.close();
+        }
+        catch {
+            /* ignore */
+        }
+        sessions.delete(key);
+    }
+    pending.delete(key);
+};

package/build/src/lib/agent-format.d.ts

@@ -0,0 +1,35 @@
+import type { SnapshotResult } from '../@types/types.js';
+export type { SnapshotResult, SnapshotElement, TabInfo, } from '../@types/types.js';
+/**
+ * Build the cross-origin notice shown above a snapshot when the page changed
+ * origin (protocol + host + port) since the last snapshot. Returns '' when
+ * origins match or either URL is missing or unparseable.
+ */
+export declare const buildCrossOriginNotice: (previousUrl: string | undefined, newUrl: string | undefined) => string;
+/**
+ * Format the body of a classified error response (without skill blocks).
+ * Used by both the resp.error branch and the WS-send-catch branch so the
+ * agent always sees the same `Category:` / `[CODE]` / `Recovery:` shape.
+ */
+export declare const formatErrorMessage: (opts: {
+    category: string;
+    code?: string;
+    prefix: string;
+    message: string;
+    suggestion?: string;
+    recovery: string;
+    snapshotText?: string;
+}) => string;
+/**
+ * Sanitize a server-returned error body for a UserError. Nginx default error
+ * pages (502/503/504) arrive as full HTML that bloats the message and
+ * confuses the LLM — strip tags and cap the length to keep it readable.
+ */
+export declare const sanitizeUpgradeBody: (body: string) => string;
+/**
+ * Translate a connect-time error into UserError-ready text. Typed
+ * UpgradeErrors carry the HTTP response for status-aware guidance; anything
+ * else (network, timeout, post-upgrade) falls through to the plain message.
+ */
+export declare const formatConnectError: (err: unknown) => string;
+export declare const formatSnapshot: (snapshot: SnapshotResult) => string;