npm - @moxxy/plugin-browser - Versions diffs - 0.27.0 - Mend

@moxxy/plugin-browser 0.27.0

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 (59) hide show

package/LICENSE +21 -0
package/dist/browser-session.d.ts +43 -0
package/dist/browser-session.d.ts.map +1 -0
package/dist/browser-session.js +500 -0
package/dist/browser-session.js.map +1 -0
package/dist/browser-surface.d.ts +3 -0
package/dist/browser-surface.d.ts.map +1 -0
package/dist/browser-surface.js +255 -0
package/dist/browser-surface.js.map +1 -0
package/dist/html-extract.d.ts +20 -0
package/dist/html-extract.d.ts.map +1 -0
package/dist/html-extract.js +122 -0
package/dist/html-extract.js.map +1 -0
package/dist/index.d.ts +10 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +24 -0
package/dist/index.js.map +1 -0
package/dist/sidecar/dispatch.d.ts +18 -0
package/dist/sidecar/dispatch.d.ts.map +1 -0
package/dist/sidecar/dispatch.js +294 -0
package/dist/sidecar/dispatch.js.map +1 -0
package/dist/sidecar/install.d.ts +37 -0
package/dist/sidecar/install.d.ts.map +1 -0
package/dist/sidecar/install.js +242 -0
package/dist/sidecar/install.js.map +1 -0
package/dist/sidecar/types.d.ts +97 -0
package/dist/sidecar/types.d.ts.map +1 -0
package/dist/sidecar/types.js +20 -0
package/dist/sidecar/types.js.map +1 -0
package/dist/sidecar.d.ts +31 -0
package/dist/sidecar.d.ts.map +1 -0
package/dist/sidecar.js +165 -0
package/dist/sidecar.js.map +1 -0
package/dist/ssrf-guard.d.ts +43 -0
package/dist/ssrf-guard.d.ts.map +1 -0
package/dist/ssrf-guard.js +164 -0
package/dist/ssrf-guard.js.map +1 -0
package/dist/web-fetch.d.ts +23 -0
package/dist/web-fetch.d.ts.map +1 -0
package/dist/web-fetch.js +253 -0
package/dist/web-fetch.js.map +1 -0
package/package.json +74 -0
package/src/browser-session.test.ts +333 -0
package/src/browser-session.ts +567 -0
package/src/browser-surface.test.ts +367 -0
package/src/browser-surface.ts +275 -0
package/src/html-extract.ts +152 -0
package/src/index.ts +35 -0
package/src/sidecar/dispatch.test.ts +313 -0
package/src/sidecar/dispatch.ts +314 -0
package/src/sidecar/install.ts +283 -0
package/src/sidecar/types.test.ts +26 -0
package/src/sidecar/types.ts +114 -0
package/src/sidecar.test.ts +57 -0
package/src/sidecar.ts +167 -0
package/src/ssrf-guard.test.ts +109 -0
package/src/ssrf-guard.ts +165 -0
package/src/web-fetch.test.ts +305 -0
package/src/web-fetch.ts +311 -0

package/src/web-fetch.test.ts ADDED Viewed

@@ -0,0 +1,305 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createPinnedLookup, htmlToMarkdown, htmlToPlainText, setWebFetchDnsResolver, webFetchTool } from './web-fetch.js';
+import { asSessionId, asToolCallId, asTurnId } from '@moxxy/sdk';
+import type { ToolContext } from '@moxxy/sdk';
+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('htmlToPlainText', () => {
+  it('strips tags + scripts + styles', () => {
+    const html = `
+      <html><head><style>body{color:red}</style></head>
+      <body>
+        <script>alert('xss')</script>
+        <h1>Title</h1>
+        <p>Para one.</p>
+        <p>Para <b>two</b>.</p>
+      </body></html>`;
+    const text = htmlToPlainText(html);
+    expect(text).toContain('Title');
+    expect(text).toContain('Para one.');
+    expect(text).toContain('Para two.');
+    expect(text).not.toContain('alert');
+    expect(text).not.toContain('color:red');
+  });
+  it('decodes HTML entities', () => {
+    expect(htmlToPlainText('<p>a&amp;b &lt; c &gt; d &quot;e&quot;</p>')).toBe('a&b < c > d "e"');
+  });
+  it('extracts a selector block when provided', () => {
+    const html = '<div>outside</div><main>inside main</main><footer>footer</footer>';
+    expect(htmlToPlainText(html, { selector: 'main' })).toBe('inside main');
+  });
+  it('selector by id', () => {
+    const html = '<p>noise</p><div id="content">payload</div><p>noise2</p>';
+    expect(htmlToPlainText(html, { selector: '#content' })).toBe('payload');
+  });
+});
+describe('htmlToMarkdown', () => {
+  it('emits markdown headings, lists, links', () => {
+    const html = `
+      <h1>Title</h1>
+      <p>Intro.</p>
+      <ul><li>one</li><li>two</li></ul>
+      <p>See <a href="https://example.com">example</a>.</p>`;
+    const md = htmlToMarkdown(html);
+    expect(md).toContain('# Title');
+    expect(md).toContain('- one');
+    expect(md).toContain('- two');
+    expect(md).toContain('[example](https://example.com)');
+  });
+  it('keeps single-quoted and unquoted href URLs', () => {
+    const html = `
+      <p>See <a href='https://single.example'>single</a>.</p>
+      <p>And <a href=https://unquoted.example>unquoted</a>.</p>`;
+    const md = htmlToMarkdown(html);
+    expect(md).toContain('[single](https://single.example)');
+    expect(md).toContain('[unquoted](https://unquoted.example)');
+  });
+});
+describe('web_fetch handler', () => {
+  let origFetch: typeof globalThis.fetch;
+  beforeEach(() => {
+    origFetch = globalThis.fetch;
+    // Keep tests hermetic: never hit real DNS — example.com "resolves" public.
+    setWebFetchDnsResolver(async () => ['93.184.216.34']);
+  });
+  afterEach(() => {
+    globalThis.fetch = origFetch;
+    setWebFetchDnsResolver(null);
+  });
+  it('returns text body for an HTML page', async () => {
+    globalThis.fetch = vi.fn(async () =>
+      mkResponse('<html><body><h1>Hello</h1></body></html>', { 'content-type': 'text/html' }),
+    ) as never;
+    const out = (await webFetchTool.handler(
+      { url: 'https://example.com', format: 'text', method: 'GET' },
+      baseCtx(),
+    )) as string;
+    expect(out).toContain('HTTP 200');
+    expect(out).toContain('Hello');
+  });
+  it('returns raw body for non-HTML content-type', async () => {
+    const body = '{"ok":true}';
+    globalThis.fetch = vi.fn(async () =>
+      mkResponse(body, { 'content-type': 'application/json' }),
+    ) as never;
+    const out = (await webFetchTool.handler(
+      { url: 'https://example.com/api.json', format: 'text', method: 'GET' },
+      baseCtx(),
+    )) as string;
+    expect(out).toContain('{"ok":true}');
+  });
+  it('truncates to maxBytes', async () => {
+    const huge = 'x'.repeat(2_000_000);
+    globalThis.fetch = vi.fn(async () =>
+      mkResponse(huge, { 'content-type': 'text/plain' }),
+    ) as never;
+    const out = (await webFetchTool.handler(
+      { url: 'https://example.com', format: 'raw', method: 'GET', maxBytes: 1024 },
+      baseCtx(),
+    )) as string;
+    expect(out).toContain('[response truncated]');
+    expect(out.length).toBeLessThan(20_000);
+  });
+  it('follows redirects', async () => {
+    const calls: string[] = [];
+    globalThis.fetch = vi.fn(async (url: string) => {
+      calls.push(url);
+      if (url === 'https://example.com/a') {
+        return mkResponse('', { location: 'https://example.com/b' }, 302);
+      }
+      return mkResponse('arrived', { 'content-type': 'text/plain' });
+    }) as never;
+    const out = (await webFetchTool.handler(
+      { url: 'https://example.com/a', format: 'raw', method: 'GET' },
+      baseCtx(),
+    )) as string;
+    expect(out).toContain('arrived');
+    expect(calls).toEqual(['https://example.com/a', 'https://example.com/b']);
+  });
+});
+describe('web_fetch SSRF guard', () => {
+  let origFetch: typeof globalThis.fetch;
+  beforeEach(() => {
+    origFetch = globalThis.fetch;
+    // Default fetch must NOT be reached for blocked URLs; make it loud if it is.
+    globalThis.fetch = vi.fn(async () => {
+      throw new Error('fetch should not be called for a blocked URL');
+    }) as never;
+  });
+  afterEach(() => {
+    globalThis.fetch = origFetch;
+    setWebFetchDnsResolver(null);
+  });
+  async function run(url: string): Promise<string> {
+    return (await webFetchTool.handler({ url, format: 'raw', method: 'GET' }, baseCtx())) as string;
+  }
+  it('blocks the loopback hostname without any DNS or fetch', async () => {
+    setWebFetchDnsResolver(async () => {
+      throw new Error('resolver should not be consulted for localhost');
+    });
+    await expect(run('http://localhost:8080/admin')).rejects.toThrow(/loopback/);
+  });
+  it('blocks the cloud metadata IP literal', async () => {
+    await expect(run('http://169.254.169.254/latest/meta-data/')).rejects.toThrow(/private|loopback/);
+  });
+  it('blocks a public hostname that resolves to a private address', async () => {
+    setWebFetchDnsResolver(async () => ['10.0.0.5']);
+    await expect(run('https://intranet.example.com/')).rejects.toThrow(/private|loopback/);
+  });
+  it('blocks non-HTTP schemes', async () => {
+    await expect(run('file:///etc/passwd')).rejects.toThrow(/scheme/);
+  });
+  it('blocks a redirect from a public host into the internal network', async () => {
+    setWebFetchDnsResolver(async (host: string) =>
+      host === 'evil.example.com' ? ['93.184.216.34'] : ['127.0.0.1'],
+    );
+    globalThis.fetch = vi.fn(async () =>
+      mkResponse('', { location: 'http://127.0.0.1:6379/' }, 302),
+    ) as never;
+    await expect(run('https://evil.example.com/start')).rejects.toThrow(/private|loopback/);
+  });
+  it('allows a genuinely public URL', async () => {
+    setWebFetchDnsResolver(async () => ['93.184.216.34']);
+    globalThis.fetch = vi.fn(async () =>
+      mkResponse('ok', { 'content-type': 'text/plain' }),
+    ) as never;
+    const out = await run('https://example.com/');
+    expect(out).toContain('ok');
+  });
+});
+describe('web_fetch DNS pinning (rebinding TOCTOU)', () => {
+  let origFetch: typeof globalThis.fetch;
+  beforeEach(() => {
+    origFetch = globalThis.fetch;
+  });
+  afterEach(() => {
+    globalThis.fetch = origFetch;
+    setWebFetchDnsResolver(null);
+  });
+  const invokeLookup = (
+    lookup: ReturnType<typeof createPinnedLookup>,
+    options: { all?: boolean },
+  ): Promise<unknown> =>
+    new Promise((resolve, reject) => {
+      (lookup as unknown as (h: string, o: unknown, cb: (err: Error | null, addr?: unknown, fam?: unknown) => void) => void)(
+        'example.com',
+        options,
+        (err, addr, fam) => (err ? reject(err) : resolve({ addr, fam })),
+      );
+    });
+  it('createPinnedLookup answers ONLY with the vetted addresses — it never re-resolves, so a rebinding second answer is unreachable', async () => {
+    // Simulated rebinding: by the time the connection is made, "DNS" now
+    // says 127.0.0.1. The pinned lookup must keep answering the vetted IP.
+    setWebFetchDnsResolver(async () => ['127.0.0.1']);
+    const lookup = createPinnedLookup(['93.184.216.34']);
+    expect(await invokeLookup(lookup, {})).toEqual({ addr: '93.184.216.34', fam: 4 });
+    expect(await invokeLookup(lookup, { all: true })).toEqual({
+      addr: [{ address: '93.184.216.34', family: 4 }],
+      fam: undefined,
+    });
+  });
+  it('createPinnedLookup fails closed when there is nothing pinned', async () => {
+    const lookup = createPinnedLookup([]);
+    await expect(invokeLookup(lookup, {})).rejects.toThrow(/no pinned address/);
+  });
+  it('resolves each hostname exactly ONCE per hop and pins the fetch to it (dispatcher attached)', async () => {
+    const resolutions: string[] = [];
+    // A rebinding resolver: first answer public, every later answer private.
+    // With pinning the fetch must still succeed (it never asks again) and
+    // the request must carry a pinned dispatcher.
+    let calls = 0;
+    setWebFetchDnsResolver(async (host: string) => {
+      resolutions.push(host);
+      calls++;
+      return calls === 1 ? ['93.184.216.34'] : ['127.0.0.1'];
+    });
+    const inits: Array<{ dispatcher?: unknown }> = [];
+    globalThis.fetch = vi.fn(async (_url: string, init: { dispatcher?: unknown }) => {
+      inits.push(init);
+      return mkResponse('ok', { 'content-type': 'text/plain' });
+    }) as never;
+    const out = (await webFetchTool.handler(
+      { url: 'https://example.com/', format: 'raw', method: 'GET' },
+      baseCtx(),
+    )) as string;
+    expect(out).toContain('ok');
+    // One resolution for the single hop — the connection itself consumes the
+    // pinned answer, not a fresh (rebindable) one.
+    expect(resolutions).toEqual(['example.com']);
+    expect(inits).toHaveLength(1);
+    expect(inits[0]!.dispatcher).toBeDefined();
+  });
+  it('re-pins every redirect hop with that hop\'s own vetted address', async () => {
+    const resolutions: string[] = [];
+    setWebFetchDnsResolver(async (host: string) => {
+      resolutions.push(host);
+      return ['93.184.216.34'];
+    });
+    const inits: Array<{ dispatcher?: unknown }> = [];
+    globalThis.fetch = vi.fn(async (url: string, init: { dispatcher?: unknown }) => {
+      inits.push(init);
+      if (url === 'https://a.example.com/start') {
+        return mkResponse('', { location: 'https://b.example.com/end' }, 302);
+      }
+      return mkResponse('arrived', { 'content-type': 'text/plain' });
+    }) as never;
+    const out = (await webFetchTool.handler(
+      { url: 'https://a.example.com/start', format: 'raw', method: 'GET' },
+      baseCtx(),
+    )) as string;
+    expect(out).toContain('arrived');
+    expect(resolutions).toEqual(['a.example.com', 'b.example.com']);
+    expect(inits).toHaveLength(2);
+    expect(inits[0]!.dispatcher).toBeDefined();
+    expect(inits[1]!.dispatcher).toBeDefined();
+    // Each hop gets its OWN pinned dispatcher.
+    expect(inits[0]!.dispatcher).not.toBe(inits[1]!.dispatcher);
+  });
+});
+function mkResponse(
+  body: string,
+  headers: Record<string, string> = {},
+  status = 200,
+): Response {
+  return new Response(body, { status, headers });
+}

package/src/web-fetch.ts ADDED Viewed

@@ -0,0 +1,311 @@
+import { isIP } from 'node:net';
+import type { LookupFunction } 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,
+  type DnsResolver,
+} 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;
+// --- SSRF guard -------------------------------------------------------------
+// web_fetch can be driven by the model, so it must not be a confused-deputy
+// that reaches loopback, RFC-1918, link-local (incl. the 169.254.169.254 cloud
+// metadata endpoint), or non-HTTP schemes. The guard itself lives in
+// `./ssrf-guard.js` (shared with browser_session and the Playwright sidecar);
+// here we validate the initial URL AND every redirect hop (a public URL can
+// 302 to an internal one).
+export type { DnsResolver } from './ssrf-guard.js';
+/** Test seam: override DNS resolution so SSRF tests stay hermetic. Pass null to reset. */
+export function setWebFetchDnsResolver(fn: DnsResolver | null): void {
+  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: string): Promise<ReadonlyArray<string> | null> {
+  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: ReadonlyArray<string>): LookupFunction {
+  // 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: string,
+    options: { all?: boolean } | undefined,
+    callback: (
+      err: NodeJS.ErrnoException | null,
+      address?: string | Array<{ address: string; family: number }>,
+      family?: number,
+    ) => void,
+  ): void => {
+    if (addresses.length === 0) {
+      const err: NodeJS.ErrnoException = 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 as unknown as LookupFunction;
+}
+/** Per-hop undici dispatcher whose connections resolve via the pinned lookup. */
+function createPinnedDispatcher(addresses: ReadonlyArray<string>): Agent {
+  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 = (): void => aborter.abort('parent signal');
+    ctx.signal.addEventListener('abort', onParentAbort, { once: true });
+    const timer = setTimeout(() => aborter.abort('fetch timeout'), timeout);
+    let fetched: FetchResult | null = 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();
+    }
+  },
+});
+interface FetchResult {
+  readonly status: number;
+  readonly url: string;
+  readonly headers: Headers;
+  readonly body: ReadableStream<Uint8Array> | null;
+  /** Close the pinned dispatcher (if any) once the body has been consumed. */
+  dispose(): Promise<void>;
+}
+async function fetchFollowRedirects(
+  initialUrl: string,
+  opts: {
+    method: 'GET' | 'HEAD';
+    headers: Record<string, string>;
+    signal: AbortSignal;
+    maxRedirects: number;
+  },
+): Promise<FetchResult> {
+  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 (): Promise<void> => {
+      if (dispatcher) {
+        try { await dispatcher.close(); } catch { /* ignore */ }
+      }
+    };
+    let res: Response;
+    try {
+      res = await fetch(current, {
+        method: opts.method,
+        headers: opts.headers,
+        signal: opts.signal,
+        redirect: 'manual',
+        ...(dispatcher ? { dispatcher } : {}),
+      } as RequestInit);
+    } 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}`,
+  });
+}
+interface CappedBody {
+  readonly text: string;
+  readonly truncated: boolean;
+}
+async function readCapped(res: FetchResult, cap: number): Promise<CappedBody> {
+  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: FetchResult): string {
+  const lines = [`HTTP ${res.status} ${res.url}`];
+  for (const [k, v] of res.headers.entries()) lines.push(`${k}: ${v}`);
+  return lines.join('\n');
+}
+interface BodyResult {
+  status: number;
+  url: string;
+  contentType: string;
+  body: CappedBody;
+  truncated: boolean;
+}
+function formatBodyResult(r: BodyResult): string {
+  const header = `HTTP ${r.status} ${r.url}\ncontent-type: ${r.contentType}${
+    r.truncated ? '\n[response truncated]' : ''
+  }`;
+  return `${header}\n\n${r.body.text}`;
+}