@zeldrisho/pi-web-fetch 0.5.3 → 0.5.4

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.5.4](https://github.com/zeldrisho/pi-packages/compare/pi-web-fetch-v0.5.3...pi-web-fetch-v0.5.4) (2026-08-12)
+
+### Bug fixes
+
+- **web-fetch:** Abort stalled response bodies instead of hanging ([0b0a080](https://github.com/zeldrisho/pi-packages/commit/0b0a080b6231944c3d7788af1a4710c3ca0cee78))
+- Apply CodeRabbit auto-fixes ([ddaa177](https://github.com/zeldrisho/pi-packages/commit/ddaa17764aedf0127c4057d3abb6900acfab2b78))
+
 ## [0.5.3](https://github.com/zeldrisho/pi-packages/compare/pi-web-fetch-v0.5.2...pi-web-fetch-v0.5.3) (2026-08-12)
 
 ### Bug fixes

package/README.md

@@ -20,7 +20,7 @@ The `web_fetch` tool accepts public HTTP and HTTPS URLs. It supports textual con
 
 For safety, the tool blocks URLs containing credentials, local hostnames, private or reserved network targets, unsafe redirects, raw responses larger than 5 MiB, and unsupported content types. The `maxCharacters` parameter controls returned Markdown length; it does not change the raw download limit.
 
-In Pi's interactive UI, fetched content uses Pi's standard collapsed preview; use the configured tool-expansion shortcut (`Ctrl+O` by default) to show all visible tool output. Output sent to the agent remains bounded. The `offset` parameter is a character offset into extracted content, not a byte range into the remote response. When a result is truncated, call the tool again with the returned `nextOffset` as `offset` to continue reading. Fetched and extracted pages are cached in byte-bounded memory for a limited time so continuation requests can reuse the same content. Concurrent requests for the same URL share one fetch; cancelling one caller does not cancel work still needed by another.
+In Pi's interactive UI, fetched content uses Pi's standard collapsed preview; use the configured tool-expansion shortcut (`Ctrl+O` by default) to show all visible tool output. Output sent to the agent remains bounded: each call returns at most `maxCharacters` characters of extracted Markdown (default 6,000) and is additionally capped by Pi's 2,000-line / 50 KiB tool-output limit, so fetching cannot bloat the conversation context. The `offset` parameter is a character offset into extracted content, not a byte range into the remote response. When a result is truncated, call the tool again with the returned `nextOffset` as `offset` to continue reading. Fetched and extracted pages are cached in byte-bounded memory for a limited time so continuation requests can reuse the same content. Concurrent requests for the same URL share one fetch; cancelling one caller does not cancel work still needed by another.
 
 Every result includes `details.truncation`. Complete output reports `{ truncated: false, strategy: "none" }`. Truncated output reports `strategy: "continuation"` and a valid `nextOffset`. The existing top-level `details.truncated` and `details.nextOffset` fields remain available.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeldrisho/pi-web-fetch",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Pi extension for secure, bounded public web page fetching and Markdown extraction",
   "keywords": [
     "pi",

package/src/fetch.ts

@@ -60,7 +60,10 @@ async function documentFromResponse(
     throw new Error(`web_fetch does not support ${contentType || "this content type"}.`);
   }
 
-  const raw = decodeResponse(await readResponseBytes(response, FETCH_MAX_BYTES), contentTypeHeader);
+  const raw = decodeResponse(
+    await readResponseBytes(response, FETCH_MAX_BYTES, signal),
+    contentTypeHeader,
+  );
   let markdown: string;
   let title: string | undefined;
   let extractor: CompleteDocument["extractor"] = "raw";

package/src/network-transport.ts

@@ -15,6 +15,13 @@ export const CONNECT_ATTEMPT_TIMEOUT_MS = 4_000;
 
 const encoder = new TextEncoder();
 
+/** Builds an AbortError matching the DOMException name used by the abort signal. */
+function abortedError(): Error {
+  const error = new Error("Operation aborted.");
+  error.name = "AbortError";
+  return error;
+}
+
 /**
  * Formats an error message for a response that exceeds the raw download limit.
  *
@@ -62,7 +69,11 @@ async function requestOnce(
   const request = target.url.protocol === "https:" ? httpsRequest : httpRequest;
   return await new Promise((resolve, reject) => {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), attemptTimeoutMs);
+    let attemptExpired = false;
+    const timer = setTimeout(() => {
+      attemptExpired = true;
+      controller.abort();
+    }, attemptTimeoutMs);
     const forwardAbort = () => controller.abort();
     if (signal.aborted) controller.abort();
     else signal.addEventListener("abort", forwardAbort, { once: true });
@@ -74,6 +85,8 @@ async function requestOnce(
       signal.removeEventListener("abort", forwardAbort);
       callback();
     };
+    const unreachableError = () =>
+      new Error(`web_fetch could not reach ${address} within ${attemptTimeoutMs} ms.`);
     const outgoing = request(
       target.url,
       {
@@ -86,18 +99,20 @@ async function requestOnce(
       },
       (response) => {
         if (controller.signal.aborted) {
-          // The attempt deadline fired before response headers: drop the socket
-          // and treat the address as unreachable so the next one is tried.
+          // The attempt deadline or caller cancellation fired before response
+          // headers: drop the socket and report the reason.
           response.destroy();
-          finish(() =>
-            reject(
-              new Error(`web_fetch could not reach ${address} within ${attemptTimeoutMs} ms.`),
-            ),
-          );
+          finish(() => reject(attemptExpired ? unreachableError() : abortedError()));
         } else finish(() => resolve(response));
       },
     );
-    outgoing.once("error", (error) => finish(() => reject(error)));
+    outgoing.once("error", (error) => {
+      // The per-attempt deadline surfaces as a raw AbortError from the HTTP
+      // client; report it as an unreachable address instead so the next
+      // validated address is tried and the final error explains itself.
+      if (attemptExpired) finish(() => reject(unreachableError()));
+      else finish(() => reject(error));
+    });
     outgoing.end();
   });
 }
@@ -149,23 +164,41 @@ export function responseHeader(response: IncomingMessage, name: string): string
 export async function readResponseBytes(
   response: IncomingMessage,
   maxBytes: number,
+  signal?: AbortSignal,
 ): Promise<Uint8Array> {
   const declared = Number(responseHeader(response, "content-length"));
   if (Number.isFinite(declared) && declared > maxBytes) {
     response.destroy();
     throw new Error(responseTooLargeMessage(declared, maxBytes, true));
   }
+  // Once response headers arrive the connect deadline and caller signal are no
+  // longer wired to the socket, so a stalled body would otherwise hang the
+  // fetch forever. Keep the caller signal attached for the whole body read and
+  // drop the socket when it fires.
+  const forwardAbort = () => response.destroy();
+  if (signal?.aborted) response.destroy();
+  else signal?.addEventListener("abort", forwardAbort, { once: true });
   const chunks: Uint8Array[] = [];
   let total = 0;
-  for await (const value of response) {
-    const chunk = typeof value === "string" ? encoder.encode(value) : new Uint8Array(value);
-    total += chunk.byteLength;
-    if (total > maxBytes) {
-      response.destroy();
-      throw new Error(responseTooLargeMessage(total, maxBytes, false));
+  try {
+    for await (const value of response) {
+      const chunk = typeof value === "string" ? encoder.encode(value) : new Uint8Array(value);
+      total += chunk.byteLength;
+      if (total > maxBytes) {
+        response.destroy();
+        throw new Error(responseTooLargeMessage(total, maxBytes, false));
+      }
+      chunks.push(chunk);
     }
-    chunks.push(chunk);
+  } catch (error) {
+    if (signal?.aborted) throw abortedError();
+    throw error;
+  } finally {
+    signal?.removeEventListener("abort", forwardAbort);
   }
+  // Destroying the socket can end the stream without an error; detect a
+  // mid-read abort here as well so truncated bodies never look complete.
+  if (signal?.aborted) throw abortedError();
   const output = new Uint8Array(total);
   let offset = 0;
   for (const chunk of chunks) {