pi-unsloth-webtools 0.3.0 → 0.3.1

package/README.md

@@ -39,6 +39,8 @@ Mirrors Unsloth Studio's `web_search` tool:
 - Transient engine failures (network errors or null responses) are retried once with a short
   backoff inside the same timeout budget (a retry that cannot fit in the remaining budget is
   skipped); timeouts and cancellations are never retried.
+- Sweeps stop as soon as enough results are gathered: engines still in flight are aborted
+  instead of being allowed to run to their timeout.
 
 ### web_fetch
 
@@ -48,11 +50,16 @@ Port of Studio's `_fetch_page_text` / `_fetch_url_raw` pipeline:
 - URL validation: http/https only, no credentials or encoded hostnames, hostname/port checks (any
   port 1–65535 is permitted; SSRF protection is enforced at the resolved-IP layer, not by port
   allowlists).
+  Canonical public IPv4 literals are accepted like IPv6 literals; private literals are still
+  blocked at the resolved-IP layer.
 - DNS resolution with SSRF protection: every resolved address is validated against
   private/loopback/link-local/CGNAT/documentation/multicast/reserved ranges, then the validated IP
   is pinned for the connection (custom `lookup` + SNI `servername`), so DNS cannot rebind between
   validation and fetch; resolution shares the caller's abort signal and the overall deadline,
   so a stuck resolver cannot outlive the fetch.
+  When a host publishes both IPv4 and IPv6 addresses, IPv4 is preferred (broken IPv6 routes
+  cannot stall a fetch), and a connection failure falls back to the next validated address for
+  the same host before giving up.
 - GitHub repo root pages are rewritten to the unauthenticated README API
   (`Accept: application/vnd.github.raw+json`), falling back to the raw README URL
   (`raw.githubusercontent.com`, no API rate limit) and then to the HTML page on failure.

package/engines.ts

@@ -863,6 +863,7 @@ export async function autoTextSearch(
   const seenProviders = new Set<string>();
   const aggregator = new ResultsAggregator();
   const ctx: EngineContext = { region: "us-en", safesearch: "moderate" };
+  const controller = new AbortController();
   let timedOut = false;
   let cancelled = false;
   const uniqueProviders = new Set(engines.map((e) => e.provider)).size;
@@ -872,14 +873,19 @@ export async function autoTextSearch(
   const run = async (engine: Engine) => {
     let results: SearchResult[] | null = null;
     for (let attempt = 0; attempt < 2 && results === null; attempt++) {
+      if (controller.signal.aborted) return;
       const budgetLeft = deadline - Date.now();
       if (budgetLeft <= 0) return;
       if (attempt > 0 && budgetLeft < ENGINE_RETRY_BACKOFF_MS) return;
       const remaining = Math.max(1, budgetLeft);
+      const engineSignal = signal
+        ? AbortSignal.any([signal, controller.signal])
+        : controller.signal;
       try {
-        results = await engine.search(query, ctx, remaining, signal);
+        results = await engine.search(query, ctx, remaining, engineSignal);
       } catch (e) {
         if (e instanceof SearchCancelled) {
+          if (controller.signal.aborted && !signal?.aborted) return;
           cancelled = true;
           return;
         }
@@ -895,15 +901,20 @@ export async function autoTextSearch(
           cancelled = true;
           return;
         }
+        if (controller.signal.aborted) return;
       }
     }
     if (results && results.length) {
       aggregator.extend(results);
       seenProviders.add(engine.provider);
+      if (aggregator.size >= maxResults) controller.abort();
     }
   };
   while (i < engines.length) {
-    if (aggregator.size >= maxResults || cancelled) break;
+    if (aggregator.size >= maxResults || cancelled) {
+      controller.abort();
+      break;
+    }
     const engine = engines[i++];
     if (seenProviders.has(engine.provider)) continue;
     pending.push(run(engine));

package/html-to-md.ts

@@ -228,8 +228,11 @@ interface HtmlHandlers {
   handleCharRef(name: string): void;
 }
 
-const START_TAG_NAME_RE = /^[a-zA-Z][^\s/>]*/;
-const ATTR_NAME_RE = /^[^\s=/>]+/;
+const START_TAG_NAME_RE = /[a-zA-Z][^\s/>]*/y;
+const ATTR_NAME_RE = /[^\s=/>]+/y;
+const ENTITY_NAMED_RE = /&([A-Za-z][A-Za-z0-9.-]*);/y;
+const ENTITY_NUMERIC_RE = /&#([xX][0-9a-fA-F]+|[0-9]+);?/y;
+const ENTITY_LEGACY_RE = /&([A-Za-z][A-Za-z0-9.-]*)(?=[^A-Za-z0-9]|$)/y;
 
 const RAW_TEXT_TAGS = [
   "script",
@@ -242,9 +245,23 @@ const RAW_TEXT_TAGS = [
   "noframes",
 ];
 
-const RAW_TEXT_CLOSERS: Record<string, RegExp> = Object.fromEntries(
-  RAW_TEXT_TAGS.map((name) => [name, new RegExp(`</${name}\\s*>`, "i")]),
-);
+function findRawTextClose(
+  input: string,
+  lowerInput: string,
+  from: number,
+  name: string,
+): { start: number; end: number } | null {
+  const needle = `</${name}`;
+  let pos = from;
+  while (true) {
+    const hit = lowerInput.indexOf(needle, pos);
+    if (hit === -1) return null;
+    let j = hit + needle.length;
+    while (j < input.length && /\s/.test(input[j])) j++;
+    if (j < input.length && input[j] === ">") return { start: hit, end: j + 1 };
+    pos = hit + 1;
+  }
+}
 
 function parseAttrsUntilClose(input: string, pos: number): [AttrDict, number, boolean] {
   const attrs: AttrDict = {};
@@ -257,10 +274,11 @@ function parseAttrsUntilClose(input: string, pos: number): [AttrDict, number, bo
       pos++;
       continue;
     }
-    const nameMatch = ATTR_NAME_RE.exec(input.slice(pos));
+    ATTR_NAME_RE.lastIndex = pos;
+    const nameMatch = ATTR_NAME_RE.exec(input);
     if (!nameMatch) return [attrs, -1, false];
     const name = nameMatch[0].toLowerCase();
-    pos += nameMatch[0].length;
+    pos = nameMatch.index + nameMatch[0].length;
     while (pos < input.length && /\s/.test(input[pos])) pos++;
     let value: string | null = null;
     if (pos < input.length && input[pos] === "=") {
@@ -285,64 +303,69 @@ function parseAttrsUntilClose(input: string, pos: number): [AttrDict, number, bo
 }
 
 function scanTag(
-  html: string,
+  input: string,
   i: number,
 ): { end: number; kind: "comment" | "decl" | "end" | "start" | "startend"; name?: string; attrs?: AttrDict } | null {
-  const rest = html.slice(i + 1);
-  if (rest.startsWith("!--")) {
-    const close = html.indexOf("-->", i + 4);
+  if (input.startsWith("!--", i + 1)) {
+    const close = input.indexOf("-->", i + 4);
     if (close === -1) return null;
     return { end: close + 3, kind: "decl" };
   }
-  if (rest.startsWith("!") || rest.startsWith("?")) {
+  const next = input[i + 1];
+  if (next === "!" || next === "?") {
     let j = i + 2;
-    while (j < html.length && html[j] !== ">") j++;
-    if (j >= html.length) return null;
+    while (j < input.length && input[j] !== ">") j++;
+    if (j >= input.length) return null;
     return { end: j + 1, kind: "decl" };
   }
-  if (rest.startsWith("/")) {
+  if (next === "/") {
     let j = i + 2;
-    while (j < html.length && /[\s>]/.test(html[j]) === false) j++;
-    const name = html.slice(i + 2, j).toLowerCase();
+    while (j < input.length && !/[\s>]/.test(input[j])) j++;
+    const name = input.slice(i + 2, j).toLowerCase();
     if (!name) return null;
-    while (j < html.length && html[j] !== ">") j++;
-    if (j >= html.length) return null;
+    while (j < input.length && input[j] !== ">") j++;
+    if (j >= input.length) return null;
     return { end: j + 1, kind: "end", name };
   }
-  const nameMatch = START_TAG_NAME_RE.exec(rest);
+  START_TAG_NAME_RE.lastIndex = i + 1;
+  const nameMatch = START_TAG_NAME_RE.exec(input);
   if (!nameMatch) return null;
   const name = nameMatch[0].toLowerCase();
-  const [attrs, next, selfClosing] = parseAttrsUntilClose(html, i + 1 + nameMatch[0].length);
-  if (next === -1) return null;
-  return { end: next, kind: selfClosing ? "startend" : "start", name, attrs };
+  const [attrs, nextPos, selfClosing] = parseAttrsUntilClose(input, i + 1 + nameMatch[0].length);
+  if (nextPos === -1) return null;
+  return { end: nextPos, kind: selfClosing ? "startend" : "start", name, attrs };
 }
 
 
 export function feedHtml(input: string, handlers: HtmlHandlers): void {
-  const emitText = (text: string) => {
-    if (!text) return;
-    let pos = 0;
-    while (pos < text.length) {
-      const amp = text.indexOf("&", pos);
-      if (amp === -1) {
-        handlers.handleData(text.slice(pos));
+  let lowerInput: string | null = null;
+  const emitTextRange = (start: number, end: number) => {
+    if (end <= start) return;
+    let pos = start;
+    while (pos < end) {
+      const amp = input.indexOf("&", pos);
+      if (amp === -1 || amp >= end) {
+        handlers.handleData(input.slice(pos, end));
         return;
       }
-      if (amp > pos) handlers.handleData(text.slice(pos, amp));
-      const named = /^&([A-Za-z][A-Za-z0-9.-]*);/.exec(text.slice(amp));
-      if (named) {
+      if (amp > pos) handlers.handleData(input.slice(pos, amp));
+      ENTITY_NAMED_RE.lastIndex = amp;
+      const named = ENTITY_NAMED_RE.exec(input);
+      if (named && named.index === amp && amp + named[0].length <= end) {
         handlers.handleEntityRef(named[1]);
         pos = amp + named[0].length;
         continue;
       }
-      const numeric = /^&#([xX][0-9a-fA-F]+|[0-9]+);?/.exec(text.slice(amp));
-      if (numeric) {
+      ENTITY_NUMERIC_RE.lastIndex = amp;
+      const numeric = ENTITY_NUMERIC_RE.exec(input);
+      if (numeric && numeric.index === amp && amp + numeric[0].length <= end) {
         handlers.handleCharRef(numeric[1]);
         pos = amp + numeric[0].length;
         continue;
       }
-      const legacy = /^&([A-Za-z][A-Za-z0-9.-]*)(?=[^A-Za-z0-9]|$)/.exec(text.slice(amp));
-      if (legacy) {
+      ENTITY_LEGACY_RE.lastIndex = amp;
+      const legacy = ENTITY_LEGACY_RE.exec(input);
+      if (legacy && legacy.index === amp && amp + legacy[0].length <= end) {
         handlers.handleEntityRef(legacy[1]);
         pos = amp + legacy[0].length;
         continue;
@@ -364,28 +387,28 @@ export function feedHtml(input: string, handlers: HtmlHandlers): void {
       i++;
       continue;
     }
-    emitText(input.slice(textStart, i));
+    emitTextRange(textStart, i);
     if (tag.kind === "start") {
-      const rawCloser = RAW_TEXT_CLOSERS[tag.name!];
-      if (rawCloser) {
-        const after = input.slice(tag.end);
-        const closeMatch = rawCloser.exec(after);
-        if (closeMatch) {
-          handlers.handleStartTag(tag.name!, tag.attrs!);
-          emitText(after.slice(0, closeMatch.index));
-          handlers.handleEndTag(tag.name!);
-          textStart = tag.end + closeMatch.index + closeMatch[0].length;
+      const rawName = tag.name!;
+      if (RAW_TEXT_TAGS.includes(rawName)) {
+        lowerInput ??= input.toLowerCase();
+        const close = findRawTextClose(input, lowerInput, tag.end, rawName);
+        if (close) {
+          handlers.handleStartTag(rawName, tag.attrs!);
+          emitTextRange(tag.end, close.start);
+          handlers.handleEndTag(rawName);
+          textStart = close.end;
           i = textStart;
           continue;
         }
       }
-      handlers.handleStartTag(tag.name!, tag.attrs!);
+      handlers.handleStartTag(rawName, tag.attrs!);
     } else if (tag.kind === "startend") handlers.handleStartEndTag(tag.name!, tag.attrs!);
     else if (tag.kind === "end") handlers.handleEndTag(tag.name!);
     textStart = tag.end;
     i = tag.end;
   }
-  emitText(input.slice(textStart));
+  emitTextRange(textStart, input.length);
 }
 
 function popMarksAbove(marks: number[], index: number): void {

package/index.ts

@@ -1,9 +1,9 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { webSearch } from "./web-search.ts";
-import { DEFAULT_FETCH_TIMEOUT_MS, fetchPageText } from "./web-fetch.ts";
+import { webSearch as defaultWebSearch } from "./web-search.ts";
+import { DEFAULT_FETCH_TIMEOUT_MS, fetchPageText as defaultFetchPageText } from "./web-fetch.ts";
 
-function positiveMaxChars(value: unknown): number | undefined {
+function positiveNumber(value: unknown): number | undefined {
   return typeof value === "number" && value > 0 ? value : undefined;
 }
 
@@ -23,6 +23,19 @@ const WebSearchParams = Type.Object({
         "Truncate the fetched page to this many characters (only used with the url parameter)",
     }),
   ),
+  maxResults: Type.Optional(
+    Type.Number({
+      minimum: 1,
+      maximum: 20,
+      description: "Maximum number of search results to return (default: 5)",
+    }),
+  ),
+  timeoutMs: Type.Optional(
+    Type.Number({
+      minimum: 1000,
+      description: "Overall timeout in milliseconds for the search or fetch",
+    }),
+  ),
 });
 
 const WebFetchParams = Type.Object({
@@ -32,65 +45,88 @@ const WebFetchParams = Type.Object({
       description: "Truncate the returned content to this many characters (default: no limit)",
     }),
   ),
+  timeoutMs: Type.Optional(
+    Type.Number({
+      minimum: 1000,
+      description: "Overall timeout in milliseconds (default: 60000)",
+    }),
+  ),
 });
 
-export default function (pi: ExtensionAPI) {
-  pi.registerTool({
-    name: "web_search",
-    label: "Web Search",
-    description:
-      "Search the web and fetch page content. Returns snippets for all results. " +
-      "Use the url parameter to fetch full page text from a specific URL.",
-    promptSnippet: "Search the web and fetch page content",
-    promptGuidelines: [
-      "Use web_search with the url parameter (e.g. {\"url\": \"<URL>\"}) to read the full text of a page found in search results.",
-    ],
-    parameters: WebSearchParams,
-    async execute(_toolCallId, params, signal, onUpdate, _ctx) {
-      if (params.url?.trim()) {
-        const url = params.url.trim();
-        onUpdate?.({ content: [{ type: "text", text: `Fetching ${url}...` }], details: {} });
-        return {
-          content: [
-            {
-              type: "text",
-              text: await fetchPageText(url, {
-                timeoutMs: DEFAULT_FETCH_TIMEOUT_MS,
-                signal: signal ?? undefined,
-                maxChars: positiveMaxChars(params.maxChars),
-              }),
-            },
-          ],
-          details: {},
-        };
-      }
-      onUpdate?.({ content: [{ type: "text", text: "Searching the web..." }], details: {} });
-      const text = await webSearch(params.query, { signal: signal ?? undefined });
-      return { content: [{ type: "text", text }], details: {} };
-    },
-  });
+export interface WebToolsDeps {
+  fetchPageText?: typeof defaultFetchPageText;
+  webSearch?: typeof defaultWebSearch;
+}
 
-  pi.registerTool({
-    name: "web_fetch",
-    label: "Web Fetch",
-    description:
-      "Fetch a URL and return its readable text. HTML pages are converted to Markdown using a " +
-      "main-content heuristic: article/main scoping plus hidden-element and boilerplate " +
-      "stripping. Non-HTML text is returned as-is. GitHub repo root pages are rewritten to the " +
-      "README API, so the README is returned instead of the repo page's UI chrome. " +
-      "Private/loopback/link-local targets are blocked (SSRF protection), and the download size " +
-      "is capped.",
-    promptSnippet: "Fetch a web page and return readable text content",
-    parameters: WebFetchParams,
-    async execute(_toolCallId, params, signal, onUpdate, _ctx) {
-      const maxChars = positiveMaxChars(params.maxChars);
-      onUpdate?.({ content: [{ type: "text", text: `Fetching ${params.url}...` }], details: {} });
-      const text = await fetchPageText(params.url, {
-        timeoutMs: DEFAULT_FETCH_TIMEOUT_MS,
-        signal: signal ?? undefined,
-        maxChars,
-      });
-      return { content: [{ type: "text", text }], details: {} };
-    },
-  });
+export function createWebTools(deps: WebToolsDeps = {}) {
+  const fetchPageText = deps.fetchPageText ?? defaultFetchPageText;
+  const webSearch = deps.webSearch ?? defaultWebSearch;
+  return {
+    webSearchTool: defineTool({
+      name: "web_search",
+      label: "Web Search",
+      description:
+        "Search the web and fetch page content. Returns snippets for all results. " +
+        "Use the url parameter to fetch full page text from a specific URL.",
+      promptSnippet: "Search the web and fetch page content",
+      promptGuidelines: [
+        'Use web_search with the url parameter (e.g. {"url": "<URL>"}) to read the full text of a page found in search results.',
+      ],
+      parameters: WebSearchParams,
+      async execute(_toolCallId, params, signal, onUpdate, _ctx) {
+        if (params.url?.trim()) {
+          const url = params.url.trim();
+          onUpdate?.({ content: [{ type: "text", text: `Fetching ${url}...` }], details: {} });
+          return {
+            content: [
+              {
+                type: "text",
+                text: await fetchPageText(url, {
+                  timeoutMs: positiveNumber(params.timeoutMs) ?? DEFAULT_FETCH_TIMEOUT_MS,
+                  signal: signal ?? undefined,
+                  maxChars: positiveNumber(params.maxChars),
+                }),
+              },
+            ],
+            details: {},
+          };
+        }
+        onUpdate?.({ content: [{ type: "text", text: "Searching the web..." }], details: {} });
+        const text = await webSearch(params.query, {
+          signal: signal ?? undefined,
+          timeoutMs: positiveNumber(params.timeoutMs),
+          maxResults: positiveNumber(params.maxResults),
+        });
+        return { content: [{ type: "text", text }], details: {} };
+      },
+    }),
+    webFetchTool: defineTool({
+      name: "web_fetch",
+      label: "Web Fetch",
+      description:
+        "Fetch a URL and return its readable text. HTML pages are converted to Markdown using a " +
+        "main-content heuristic: article/main scoping plus hidden-element and boilerplate " +
+        "stripping. Non-HTML text is returned as-is. GitHub repo root pages are rewritten to the " +
+        "README API, so the README is returned instead of the repo page's UI chrome. " +
+        "Private/loopback/link-local targets are blocked (SSRF protection), and the download size " +
+        "is capped.",
+      promptSnippet: "Fetch a web page and return readable text content",
+      parameters: WebFetchParams,
+      async execute(_toolCallId, params, signal, onUpdate, _ctx) {
+        onUpdate?.({ content: [{ type: "text", text: `Fetching ${params.url}...` }], details: {} });
+        const text = await fetchPageText(params.url, {
+          timeoutMs: positiveNumber(params.timeoutMs) ?? DEFAULT_FETCH_TIMEOUT_MS,
+          signal: signal ?? undefined,
+          maxChars: positiveNumber(params.maxChars),
+        });
+        return { content: [{ type: "text", text }], details: {} };
+      },
+    }),
+  };
+}
+
+export default function (pi: ExtensionAPI) {
+  const { webSearchTool, webFetchTool } = createWebTools();
+  pi.registerTool(webSearchTool);
+  pi.registerTool(webFetchTool);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-unsloth-webtools",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "Pi extension: web_search and web_fetch tools ported from the Unsloth Studio codebase (DuckDuckGo search, SSRF-safe direct fetching, HTML-to-Markdown extraction)",
   "main": "index.ts",

package/pdf.ts

@@ -697,6 +697,11 @@ function extractTextOps(bytes: Buffer): string {
         }
       }
     }
+    if (c === "'" || c === '"') {
+      if (inText) out.push("\n");
+      i++;
+      continue;
+    }
     const token = text.slice(i, i + 2);
     if (token === "BT") {
       inText = true;

package/web-access.ts

@@ -37,6 +37,11 @@ export function normalizeDomain(value: unknown): string {
     throw new Error("Website limits must contain domains without schemes or ports");
   }
   const numericParts = stripped.split(".");
+  const canonicalIpv4 =
+    numericParts.length === 4 &&
+    numericParts.every((part) => /^(?:0|[1-9][0-9]{0,2})$/.test(part)) &&
+    numericParts.every((part) => Number(part) <= 255);
+  if (canonicalIpv4) return stripped;
   if (
     numericParts.length <= 4 &&
     numericParts.every((part) => /^(?:0x[0-9a-f]+|[0-9]+)$/.test(part))

package/web-fetch.ts

@@ -1,4 +1,5 @@
 import { lookup as dnsLookup } from "node:dns/promises";
+import type { LookupAllOptions } from "node:dns";
 import http from "node:http";
 import https from "node:https";
 import { createBrotliDecompress, createGunzip, createInflate, createInflateRaw } from "node:zlib";
@@ -165,6 +166,7 @@ export interface ResolvedHost {
   reason: string;
   ip: string;
   family: number;
+  alternates?: { ip: string; family: number }[];
 }
 
 export interface FetchSeams {
@@ -204,14 +206,25 @@ export interface RawFetchResult {
 }
 
 function htmlProbe(body: string, re: RegExp): boolean {
-  let probe = body;
-  while (true) {
-    probe = probe.replace(/^[ \t\n\r\f\v]+/, "");
-    const stripped = probe.replace(/^(?:<!--[\s\S]*?-->|<\?[\s\S]*?\?>)/, "");
-    if (stripped === probe) break;
-    probe = stripped;
+  let i = 0;
+  const n = body.length;
+  while (i < n) {
+    while (i < n && /[ \t\n\r\f\v]/.test(body[i])) i++;
+    if (body.startsWith("<!--", i)) {
+      const close = body.indexOf("-->", i + 4);
+      if (close === -1) break;
+      i = close + 3;
+      continue;
+    }
+    if (body.startsWith("<?", i)) {
+      const close = body.indexOf("?>", i + 2);
+      if (close === -1) break;
+      i = close + 2;
+      continue;
+    }
+    break;
   }
-  return re.test(probe.slice(0, 256).toLowerCase());
+  return re.test(body.slice(i, i + 256).toLowerCase());
 }
 
 export function looksLikeHtml(body: string): boolean {
@@ -455,32 +468,15 @@ function decodeTis620(bytes: Buffer): string {
 }
 
 
-function withAbort<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
-  if (!signal) return promise;
-  return new Promise<T>((resolve, reject) => {
-    const onAbort = () => reject(new DOMException("aborted", "AbortError"));
-    if (signal.aborted) {
-      onAbort();
-      return;
-    }
-    signal.addEventListener("abort", onAbort, { once: true });
-    promise.then(
-      (value) => {
-        signal.removeEventListener("abort", onAbort);
-        resolve(value);
-      },
-      (err) => {
-        signal.removeEventListener("abort", onAbort);
-        reject(err);
-      },
-    );
-  });
-}
-
 async function resolveAndValidate(hostname: string, signal?: AbortSignal): Promise<ResolvedHost> {
   let addresses: { address: string; family: number }[];
   try {
-    addresses = await withAbort(dnsLookup(hostname, { all: true, verbatim: true }), signal);
+    const lookupOptions: LookupAllOptions & { signal?: AbortSignal } = {
+      all: true,
+      verbatim: true,
+      signal,
+    };
+    addresses = await dnsLookup(hostname, lookupOptions);
   } catch (err) {
     return { ok: false, reason: `Failed to resolve host: ${err}`, ip: "", family: 0 };
   }
@@ -492,8 +488,15 @@ async function resolveAndValidate(hostname: string, signal?: AbortSignal): Promi
       return { ok: false, reason: `Blocked: refusing to fetch the non-public address ${entry.address}.`, ip: "", family: 0 };
     }
   }
+  addresses.sort((a, b) => (a.family === 4 ? 0 : 1) - (b.family === 4 ? 0 : 1));
   const first = addresses[0];
-  return { ok: true, reason: "", ip: first.address, family: first.family };
+  return {
+    ok: true,
+    reason: "",
+    ip: first.address,
+    family: first.family,
+    alternates: addresses.slice(1).map((entry) => ({ ip: entry.address, family: entry.family })),
+  };
 }
 
 
@@ -603,7 +606,8 @@ export function requestHop(opts: HopOptions): Promise<HopResponse> {
         if (total >= limit) {
           truncated =
             codec !== null ||
-            !(Number.isFinite(declaredLength) && declaredLength === total);
+            take.length < chunk.length ||
+            (Number.isFinite(declaredLength) && declaredLength > total);
           decoder?.destroy();
           res.destroy();
           finish(null, Buffer.concat(chunks));
@@ -722,8 +726,9 @@ export async function fetchUrlRaw(
   let currentUrl = url;
   let pinnedIp = resolved.ip;
   let pinnedFamily = resolved.family;
+  let alternates: { ip: string; family: number }[] = resolved.alternates ?? [];
+  let alternateIndex = 0;
   const userAgent = randomUserAgent();
-
   for (let hop = 0; hop < MAX_REQUESTS; hop++) {
     const budgetResult = budgetExceededResult(deadline, signal, now);
     if (budgetResult !== null) return budgetResult;
@@ -752,6 +757,16 @@ export async function fetchUrlRaw(
         signal,
       });
     } catch (err) {
+      if (
+        !(err instanceof FetchCancelledError) &&
+        !(err instanceof FetchTimeoutError) &&
+        alternateIndex < alternates.length
+      ) {
+        const next = alternates[alternateIndex++];
+        pinnedIp = next.ip;
+        pinnedFamily = next.family;
+        continue;
+      }
       return { error: fetchErrorMessage(err), body: "", contentType: "" };
     }
 
@@ -782,6 +797,8 @@ export async function fetchUrlRaw(
       if (!redirected.ok) return { error: redirected.reason, body: "", contentType: "" };
       pinnedIp = redirected.ip;
       pinnedFamily = redirected.family;
+      alternates = redirected.alternates ?? [];
+      alternateIndex = 0;
       continue;
     }