@moxxy/plugin-browser 0.27.0

package/dist/web-fetch.js

@@ -0,0 +1,253 @@
+import { isIP } from 'node:net';
+import { Agent } from 'undici';
+import { MoxxyError, defineTool, z } from '@moxxy/sdk';
+import { htmlToMarkdown, htmlToPlainText } from './html-extract.js';
+import { assertPublicUrl, setSsrfDnsResolver, SsrfBlockedError, } from './ssrf-guard.js';
+/**
+ * Light-tier web fetch: a single HTTP GET (or HEAD) with HTML→text/markdown
+ * post-processing for the common case of "read this page". Zero new
+ * dependencies — uses Node's built-in `fetch`.
+ *
+ * For JS-heavy / interactive pages, use `browser_session` (Playwright
+ * sidecar) instead. The web-research skill picks the tier.
+ */
+export { htmlToMarkdown, htmlToPlainText } from './html-extract.js';
+const MAX_BYTES_DEFAULT = 2 * 1024 * 1024; // 2 MB
+const MAX_REDIRECTS_DEFAULT = 5;
+const FETCH_TIMEOUT_MS_DEFAULT = 20_000;
+/** Test seam: override DNS resolution so SSRF tests stay hermetic. Pass null to reset. */
+export function setWebFetchDnsResolver(fn) {
+    setSsrfDnsResolver(fn);
+}
+/**
+ * Shared guard, with rejections re-thrown as MoxxyError for the tool surface.
+ * Returns the vetted resolved addresses (null when the host is an IP literal
+ * or resolution failed open) so the fetch can be pinned to exactly what was
+ * checked.
+ */
+async function assertPublicUrlForWebFetch(raw) {
+    try {
+        return await assertPublicUrl(raw, 'web_fetch');
+    }
+    catch (err) {
+        if (err instanceof SsrfBlockedError) {
+            throw new MoxxyError({ code: 'INTERNAL', message: err.message });
+        }
+        throw err;
+    }
+}
+/**
+ * DNS-rebinding (TOCTOU) defense: a lookup function that always answers with
+ * the addresses the SSRF guard just vetted, so the connection provably goes
+ * to the IP that was checked — a second, attacker-controlled DNS answer
+ * between check and connect can never be consulted. Exported for tests.
+ */
+export function createPinnedLookup(addresses) {
+    // Implemented against the runtime contract (net.connect may ask for one
+    // address or, with autoSelectFamily/happy-eyeballs, `all: true`), which is
+    // wider than the single-answer `LookupFunction` type — hence the cast.
+    const lookup = (hostname, options, callback) => {
+        if (addresses.length === 0) {
+            const err = new Error(`web_fetch: no pinned address for "${hostname}"`);
+            err.code = 'ENOTFOUND';
+            callback(err);
+            return;
+        }
+        const all = addresses.map((address) => ({ address, family: isIP(address) }));
+        if (options?.all)
+            callback(null, all);
+        else
+            callback(null, all[0].address, all[0].family);
+    };
+    return lookup;
+}
+/** Per-hop undici dispatcher whose connections resolve via the pinned lookup. */
+function createPinnedDispatcher(addresses) {
+    return new Agent({ connect: { lookup: createPinnedLookup(addresses) } });
+}
+export const webFetchTool = defineTool({
+    name: 'web_fetch',
+    description: 'Fetch a URL over HTTP(S) and return the page content. HTML is post-processed to readable text (or markdown). Use for simple GETs; if the page needs JS execution, clicks, or form fills, use browser_session instead.',
+    inputSchema: z.object({
+        url: z.string().url().describe('Absolute http:// or https:// URL.'),
+        format: z
+            .enum(['text', 'markdown', 'raw'])
+            .optional()
+            .default('text')
+            .describe('How to render the response. `text` strips HTML to readable plain text. `markdown` keeps headings + lists + links. `raw` returns the body as-is (HTML, JSON, etc).'),
+        method: z.enum(['GET', 'HEAD']).optional().default('GET'),
+        headers: z.record(z.string(), z.string()).optional(),
+        maxBytes: z.number().int().positive().max(20_000_000).optional(),
+        timeoutMs: z.number().int().positive().max(120_000).optional(),
+        selector: z
+            .string()
+            .optional()
+            .describe('Optional CSS-like selector for the readability extractor (e.g. "main", "article"). Falls back to whole-body extraction.'),
+    }),
+    permission: { action: 'prompt' },
+    isolation: {
+        capabilities: {
+            net: { mode: 'any' },
+            timeMs: 120_000,
+        },
+    },
+    async handler({ url, format, method, headers, maxBytes, timeoutMs, selector }, ctx) {
+        const cap = maxBytes ?? MAX_BYTES_DEFAULT;
+        const timeout = timeoutMs ?? FETCH_TIMEOUT_MS_DEFAULT;
+        const aborter = new AbortController();
+        const onParentAbort = () => aborter.abort('parent signal');
+        ctx.signal.addEventListener('abort', onParentAbort, { once: true });
+        const timer = setTimeout(() => aborter.abort('fetch timeout'), timeout);
+        let fetched = null;
+        try {
+            const res = await fetchFollowRedirects(url, {
+                method,
+                headers: { 'user-agent': 'moxxy/0.0', ...(headers ?? {}) },
+                signal: aborter.signal,
+                maxRedirects: MAX_REDIRECTS_DEFAULT,
+            });
+            fetched = res;
+            if (method === 'HEAD') {
+                return formatHeadResult(res);
+            }
+            const body = await readCapped(res, cap);
+            const contentType = res.headers.get('content-type') ?? '';
+            const isHtml = contentType.includes('text/html') || contentType.includes('application/xhtml');
+            if (format === 'raw' || !isHtml) {
+                return formatBodyResult({
+                    status: res.status,
+                    url: res.url,
+                    contentType,
+                    body,
+                    truncated: body.truncated,
+                });
+            }
+            const extracted = format === 'markdown'
+                ? htmlToMarkdown(body.text, { selector })
+                : htmlToPlainText(body.text, { selector });
+            return formatBodyResult({
+                status: res.status,
+                url: res.url,
+                contentType,
+                body: { text: extracted, truncated: body.truncated },
+                truncated: body.truncated,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+            ctx.signal.removeEventListener('abort', onParentAbort);
+            // Close the final hop's pinned dispatcher (body is consumed by now).
+            if (fetched)
+                await fetched.dispose();
+        }
+    },
+});
+async function fetchFollowRedirects(initialUrl, opts) {
+    let current = initialUrl;
+    for (let hop = 0; hop <= opts.maxRedirects; hop++) {
+        // Re-validate on every hop — the initial URL AND each redirect target —
+        // so a public URL can't 302 us into the internal network.
+        const vettedAddrs = await assertPublicUrlForWebFetch(current);
+        // DNS-rebinding TOCTOU defense: pin THIS hop's connection to the
+        // addresses the guard just vetted. The hostname (and so TLS SNI/cert
+        // validation) is untouched — only name resolution is overridden. When
+        // there is nothing to pin (IP-literal host already vetted, or fail-open
+        // resolution error where the real fetch fails identically), plain fetch.
+        const dispatcher = vettedAddrs && vettedAddrs.length > 0 ? createPinnedDispatcher(vettedAddrs) : null;
+        const closeDispatcher = async () => {
+            if (dispatcher) {
+                try {
+                    await dispatcher.close();
+                }
+                catch { /* ignore */ }
+            }
+        };
+        let res;
+        try {
+            res = await fetch(current, {
+                method: opts.method,
+                headers: opts.headers,
+                signal: opts.signal,
+                redirect: 'manual',
+                ...(dispatcher ? { dispatcher } : {}),
+            });
+        }
+        catch (err) {
+            await closeDispatcher();
+            throw err;
+        }
+        if (res.status >= 300 && res.status < 400 && res.headers.get('location')) {
+            const next = new URL(res.headers.get('location'), current).toString();
+            current = next;
+            // drain to avoid the connection leaking
+            try {
+                await res.body?.cancel();
+            }
+            catch { /* ignore */ }
+            await closeDispatcher();
+            continue;
+        }
+        return {
+            status: res.status,
+            url: current,
+            headers: res.headers,
+            body: res.body,
+            dispose: closeDispatcher,
+        };
+    }
+    throw new MoxxyError({
+        code: 'INTERNAL',
+        message: `Too many redirects (>${opts.maxRedirects}) starting at ${initialUrl}`,
+    });
+}
+async function readCapped(res, cap) {
+    if (!res.body)
+        return { text: '', truncated: false };
+    const reader = res.body.getReader();
+    // Streaming UTF-8 decode: a multi-byte sequence straddling a chunk boundary —
+    // or the hard byte cut at `cap` — is buffered across `decode({stream:true})`
+    // calls instead of being sliced mid-codepoint into a replacement char. Avoids
+    // the Buffer.concat re-copy too.
+    const decoder = new TextDecoder('utf-8');
+    let text = '';
+    let total = 0;
+    let truncated = false;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (total + value.byteLength > cap) {
+                text += decoder.decode(value.subarray(0, cap - total), { stream: true });
+                total = cap;
+                truncated = true;
+                break;
+            }
+            text += decoder.decode(value, { stream: true });
+            total += value.byteLength;
+        }
+        text += decoder.decode(); // flush any buffered partial sequence
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch { /* ignore */ }
+        try {
+            await res.body.cancel();
+        }
+        catch { /* ignore */ }
+    }
+    return { text, truncated };
+}
+function formatHeadResult(res) {
+    const lines = [`HTTP ${res.status} ${res.url}`];
+    for (const [k, v] of res.headers.entries())
+        lines.push(`${k}: ${v}`);
+    return lines.join('\n');
+}
+function formatBodyResult(r) {
+    const header = `HTTP ${r.status} ${r.url}\ncontent-type: ${r.contentType}${r.truncated ? '\n[response truncated]' : ''}`;
+    return `${header}\n\n${r.body.text}`;
+}
+//# sourceMappingURL=web-fetch.js.map

package/dist/web-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-fetch.js","sourceRoot":"","sources":["../src/web-fetch.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@moxxy/plugin-browser",
+  "version": "0.27.0",
+  "description": "Browser capabilities for moxxy: web_fetch (zero-deps light tier) + browser_session (Playwright sidecar for JS-heavy / interactive pages).",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "browser",
+    "playwright",
+    "tools"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/plugin-browser"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "moxxy-browser-sidecar": "./dist/sidecar.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "skills"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "skills": "./skills"
+    }
+  },
+  "dependencies": {
+    "undici": "^6.26.0",
+    "@moxxy/sdk": "0.27.0"
+  },
+  "peerDependencies": {
+    "playwright": "^1.40.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/vitest-preset": "0.0.0",
+    "@moxxy/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/sidecar.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/browser-session.test.ts

@@ -0,0 +1,333 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { PassThrough } from 'node:stream';
+import { asSessionId, asToolCallId, asTurnId } from '@moxxy/sdk';
+import type { ToolContext } from '@moxxy/sdk';
+import {
+  browserSidecarCall,
+  buildBrowserSessionTool,
+  closeBrowserSidecar,
+  resolveBrowserInstallRoot,
+  type SidecarStream,
+} from './browser-session.js';
+import { setSsrfDnsResolver } from './ssrf-guard.js';
+
+// Hermetic DNS for the parent-side SSRF guard on `goto`: every hostname
+// "resolves" public so tests never hit real DNS.
+beforeEach(() => setSsrfDnsResolver(async () => ['93.184.216.34']));
+afterEach(() => setSsrfDnsResolver(null));
+
+/**
+ * The sidecar is exercised via a fake `spawnFn` that drives a scripted
+ * protocol — keeps Playwright out of the test loop entirely.
+ */
+
+const baseCtx = (): ToolContext => ({
+  sessionId: asSessionId('s'),
+  turnId: asTurnId('t'),
+  callId: asToolCallId('c'),
+  cwd: '/tmp',
+  signal: new AbortController().signal,
+  log: { length: 0, at: () => undefined, slice: () => [], ofType: () => [], byTurn: () => [], toJSON: () => [] },
+  logger: { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} },
+});
+
+describe('resolveBrowserInstallRoot', () => {
+  it('returns the prefix root (the node_modules parent) for a packaged sidecar path', () => {
+    // The real installed layout: <root>/node_modules/@moxxy/cli/dist/sidecar.js
+    const sidecarPath = '/Users/me/Library/App/cli/node_modules/@moxxy/cli/dist/sidecar.js';
+    expect(resolveBrowserInstallRoot({ sidecarPath })).toBe('/Users/me/Library/App/cli');
+  });
+
+  it('falls back to the sidecar dir when no node_modules is on the path', () => {
+    expect(resolveBrowserInstallRoot({ sidecarPath: '/opt/app/dist/sidecar.js' })).toBe('/opt/app/dist');
+  });
+});
+
+function makeFakeSpawn(handler: (req: { id: string; method: string; params?: unknown }) => unknown): {
+  spawn: (path: string) => SidecarStream;
+  receivedRequests: Array<{ id: string; method: string; params?: unknown }>;
+} {
+  const receivedRequests: Array<{ id: string; method: string; params?: unknown }> = [];
+
+  const spawn = (_scriptPath: string): SidecarStream => {
+    const stdin = new PassThrough();
+    const stdout = new PassThrough();
+    let buf = '';
+    stdin.on('data', (chunk) => {
+      buf += chunk.toString('utf8');
+      let nl: number;
+      while ((nl = buf.indexOf('\n')) !== -1) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        if (!line.trim()) continue;
+        const req = JSON.parse(line);
+        receivedRequests.push(req);
+        const result = handler(req);
+        const reply = { id: req.id, ok: true, result };
+        stdout.write(JSON.stringify(reply) + '\n');
+      }
+    });
+    const exitListeners: Array<(code: number | null) => void> = [];
+    const stream: SidecarStream = {
+      stdin,
+      stdout,
+      kill: () => {
+        for (const l of exitListeners) l(0);
+        return true;
+      },
+      once: (_event, listener) => {
+        exitListeners.push(listener as (code: number | null) => void);
+      },
+    };
+    return stream;
+  };
+  return { spawn, receivedRequests };
+}
+
+describe('browser_session tool (sidecar protocol)', () => {
+  it('drives `goto` and returns the result', async () => {
+    const { spawn, receivedRequests } = makeFakeSpawn((req) => {
+      if (req.method === 'goto') return { url: (req.params as { url: string }).url };
+      return null;
+    });
+
+    const tool = buildBrowserSessionTool({ sidecarPath: '/fake.js', spawnFn: spawn });
+    const out = await tool.handler(
+      { action: { kind: 'goto', url: 'https://example.com' } },
+      baseCtx(),
+    );
+    expect(out).toEqual({ url: 'https://example.com' });
+    expect(receivedRequests).toHaveLength(1);
+    expect(receivedRequests[0]!.method).toBe('goto');
+
+    await closeBrowserSidecar();
+  });
+
+  it('drives `text` after `goto` on the same sidecar (shared page)', async () => {
+    const { spawn, receivedRequests } = makeFakeSpawn((req) => {
+      if (req.method === 'goto') return { url: 'https://x' };
+      if (req.method === 'text') return 'hello world';
+      return null;
+    });
+
+    const tool = buildBrowserSessionTool({ sidecarPath: '/fake.js', spawnFn: spawn });
+    await tool.handler({ action: { kind: 'goto', url: 'https://x' } }, baseCtx());
+    const text = await tool.handler({ action: { kind: 'text', selector: 'main' } }, baseCtx());
+    expect(text).toBe('hello world');
+    expect(receivedRequests.map((r) => r.method)).toEqual(['goto', 'text']);
+
+    await closeBrowserSidecar();
+  });
+
+  it('forwards eval expression to the sidecar', async () => {
+    const { spawn, receivedRequests } = makeFakeSpawn((req) => {
+      if (req.method === 'eval') return 42;
+      return null;
+    });
+    const tool = buildBrowserSessionTool({ sidecarPath: '/fake.js', spawnFn: spawn });
+    const out = await tool.handler(
+      { action: { kind: 'eval', expression: '1 + 41' } },
+      baseCtx(),
+    );
+    expect(out).toBe(42);
+    expect((receivedRequests[0]!.params as { expression: string }).expression).toBe('1 + 41');
+    await closeBrowserSidecar();
+  });
+});
+
+/** A sidecar that consumes requests but NEVER replies — drives the
+ *  parent-side per-call timeout path. */
+function makeSilentSpawn(): {
+  spawn: (path: string) => SidecarStream;
+  receivedRequests: Array<{ id: string; method: string }>;
+} {
+  const receivedRequests: Array<{ id: string; method: string }> = [];
+  const spawn = (_p: string): SidecarStream => {
+    const stdin = new PassThrough();
+    const stdout = new PassThrough();
+    let buf = '';
+    stdin.on('data', (chunk) => {
+      buf += chunk.toString('utf8');
+      let nl: number;
+      while ((nl = buf.indexOf('\n')) !== -1) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        if (line.trim()) receivedRequests.push(JSON.parse(line));
+      }
+      // deliberately never writes a reply
+    });
+    const exitListeners: Array<(code: number | null) => void> = [];
+    return {
+      stdin,
+      stdout,
+      kill: () => {
+        for (const l of exitListeners) l(0);
+        return true;
+      },
+      once: (_e, listener) => {
+        exitListeners.push(listener as (code: number | null) => void);
+      },
+    };
+  };
+  return { spawn, receivedRequests };
+}
+
+describe('browser_session parent-side per-call timeout', () => {
+  it('rejects a hung sidecar op after the configured timeout instead of hanging forever', async () => {
+    const { spawn, receivedRequests } = makeSilentSpawn();
+    // 50ms timeout via the deps seam so the test is fast.
+    const tool = buildBrowserSessionTool({ sidecarPath: '/fake.js', spawnFn: spawn, callTimeoutMs: 50 });
+    await expect(
+      tool.handler({ action: { kind: 'url' } }, baseCtx()),
+    ).rejects.toThrow(/timed out/);
+    expect(receivedRequests).toHaveLength(1); // the request WAS sent; just never answered
+    await closeBrowserSidecar();
+  });
+
+  it('a later reply for a timed-out call is ignored (no unhandled settle)', async () => {
+    // The pending entry is deleted on timeout, so a straggling reply is a no-op.
+    const { spawn } = makeSilentSpawn();
+    const tool = buildBrowserSessionTool({ sidecarPath: '/fake.js', spawnFn: spawn, callTimeoutMs: 30 });
+    await expect(tool.handler({ action: { kind: 'url' } }, baseCtx())).rejects.toThrow(/timed out/);
+    // No throw / no hang on cleanup proves the entry was dropped.
+    await closeBrowserSidecar();
+  });
+});
+
+describe('browser_session pending-map bound (MAX_PENDING)', () => {
+  it('rejects with "busy" once the queued-request ceiling is hit, instead of growing pending unbounded', async () => {
+    // A wedged sidecar head (never replies) + a chatty caller (surface polls at
+    // 3/s) must NOT let the parent accumulate pending entries without limit. The
+    // bound is 256; the 257th call degrades to a clean "busy" rejection rather
+    // than an OOM. Earlier calls stay pending (a long timeout keeps them alive
+    // for the duration of the test) and the shared sidecar is untouched.
+    const { spawn } = makeSilentSpawn();
+    // Long per-call timeout so the first 256 stay pending while we probe the 257th.
+    const deps = { sidecarPath: '/fake.js', spawnFn: spawn, callTimeoutMs: 60_000 };
+    const pending: Array<Promise<unknown>> = [];
+    for (let i = 0; i < 256; i++) {
+      // Swallow each eventual rejection (closeBrowserSidecar rejects them all on
+      // teardown) so they don't surface as unhandled rejections.
+      pending.push(browserSidecarCall('url', {}, deps).catch(() => undefined));
+    }
+    // The 257th must be rejected synchronously-ish with a bounded "busy" error.
+    await expect(browserSidecarCall('url', {}, deps)).rejects.toThrow(/busy/i);
+    // Tear down: closing rejects every still-pending call (sidecar "exited").
+    await closeBrowserSidecar();
+    await Promise.all(pending);
+  });
+});
+
+/**
+ * A sidecar whose child IGNORES SIGTERM — only a SIGKILL emits `exit`. Drives
+ * the close() escalation path: SIGTERM first, then SIGKILL after the grace
+ * timeout, so a wedged child can't survive as an orphan after session shutdown.
+ */
+function makeStubbornSpawn(): {
+  spawn: (path: string) => SidecarStream;
+  signalsSent: string[];
+} {
+  const signalsSent: string[] = [];
+  const spawn = (_p: string): SidecarStream => {
+    const stdin = new PassThrough();
+    const stdout = new PassThrough();
+    // Consume input but never reply — close()'s `close` RPC will time out fast
+    // (callTimeoutMs), then the SIGTERM→SIGKILL escalation runs.
+    stdin.on('data', () => {});
+    const exitListeners: Array<(code: number | null) => void> = [];
+    return {
+      stdin,
+      stdout,
+      kill: (signal?: NodeJS.Signals) => {
+        signalsSent.push(signal ?? 'SIGTERM');
+        // Only SIGKILL actually terminates this stubborn child.
+        if (signal === 'SIGKILL') for (const l of exitListeners) l(null);
+        return true;
+      },
+      once: (_e, listener) => {
+        exitListeners.push(listener as (code: number | null) => void);
+      },
+    };
+  };
+  return { spawn, signalsSent };
+}
+
+describe('browser_session close() SIGKILL escalation', () => {
+  it('escalates SIGTERM → SIGKILL when the child ignores SIGTERM, and still resolves', async () => {
+    vi.useFakeTimers();
+    try {
+      const { spawn, signalsSent } = makeStubbornSpawn();
+      // Short call timeout so the best-effort `close` RPC inside close() gives up fast.
+      const deps = { sidecarPath: '/fake.js', spawnFn: spawn, callTimeoutMs: 20 };
+      // Spawn the singleton via a normal call (which will itself time out — swallow it).
+      void browserSidecarCall('url', {}, deps).catch(() => undefined);
+      // Drive the close: advance through the close-RPC timeout, then the 2s SIGKILL grace.
+      const closing = closeBrowserSidecar();
+      await vi.advanceTimersByTimeAsync(20); // close RPC times out
+      await vi.advanceTimersByTimeAsync(2000); // SIGTERM grace elapses → SIGKILL
+      await closing; // must resolve, not hang
+      expect(signalsSent).toContain('SIGTERM');
+      expect(signalsSent).toContain('SIGKILL');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe('browser_session eval opt-out', () => {
+  afterEach(() => {
+    delete process.env.MOXXY_BROWSER_DISABLE_EVAL;
+  });
+  it('refuses eval when MOXXY_BROWSER_DISABLE_EVAL=1 without reaching the sidecar', async () => {
+    process.env.MOXXY_BROWSER_DISABLE_EVAL = '1';
+    const { spawn, receivedRequests } = makeFakeSpawn(() => 42);
+    const tool = buildBrowserSessionTool({ sidecarPath: '/fake.js', spawnFn: spawn });
+    await expect(
+      tool.handler({ action: { kind: 'eval', expression: '1+1' } }, baseCtx()),
+    ).rejects.toThrow(/disabled/);
+    expect(receivedRequests.some((r) => r.method === 'eval')).toBe(false);
+    await closeBrowserSidecar();
+  });
+});
+
+describe('browser_session SSRF guard (parent layer)', () => {
+  it.each([
+    'http://169.254.169.254/latest/meta-data/',
+    'http://localhost:3000/',
+    'http://10.0.0.5/internal',
+  ])('rejects goto %s before any RPC reaches the sidecar', async (url) => {
+    const { spawn, receivedRequests } = makeFakeSpawn(() => null);
+    const tool = buildBrowserSessionTool({ sidecarPath: '/fake.js', spawnFn: spawn });
+    await expect(
+      tool.handler({ action: { kind: 'goto', url } }, baseCtx()),
+    ).rejects.toThrow(/private|loopback/);
+    expect(receivedRequests).toHaveLength(0); // never sent to the sidecar
+    await closeBrowserSidecar();
+  });
+
+  it('rejects a hostname resolving to a private address', async () => {
+    setSsrfDnsResolver(async () => ['10.1.2.3']);
+    const { spawn, receivedRequests } = makeFakeSpawn(() => null);
+    const tool = buildBrowserSessionTool({ sidecarPath: '/fake.js', spawnFn: spawn });
+    await expect(
+      tool.handler({ action: { kind: 'goto', url: 'https://intranet.example.com/' } }, baseCtx()),
+    ).rejects.toThrow(/private|loopback/);
+    expect(receivedRequests).toHaveLength(0);
+    await closeBrowserSidecar();
+  });
+
+  it('allows a public URL through to the sidecar', async () => {
+    const { spawn, receivedRequests } = makeFakeSpawn((req) => {
+      if (req.method === 'goto') return { url: (req.params as { url: string }).url };
+      return null;
+    });
+    const tool = buildBrowserSessionTool({ sidecarPath: '/fake.js', spawnFn: spawn });
+    const out = await tool.handler(
+      { action: { kind: 'goto', url: 'https://example.com/' } },
+      baseCtx(),
+    );
+    expect(out).toEqual({ url: 'https://example.com/' });
+    expect(receivedRequests).toHaveLength(1);
+    await closeBrowserSidecar();
+  });
+});