pi-unsloth-webtools 0.4.2 → 0.5.0

package/README.md

@@ -179,6 +179,28 @@ Optional settings in `~/.pi/agent/settings.json` or `.pi/settings.json` (project
 
 Tool params always win over file defaults.
 
+## Troubleshooting
+
+Match on the exact prefix. Do not retry blocked hosts with spelling tricks.
+
+| Symptom | Exact string | Action |
+|---|---|---|
+| Empty query | `No query provided.` | Pass `query` or `url`. |
+| Cancelled | `Search cancelled.` / `Failed to fetch URL: cancelled.` | Retry only if the abort was not intentional. |
+| Search timeout | `Search failed: the search engines (...) did not respond within N seconds.` | Retry, narrow the query, or raise `timeoutMs`. |
+| No results | `No results found.` | Rephrase the query. |
+| Policy filtered everything | `No results found within the website access limits.` | Widen `websitePolicy`, do not work around it. |
+| Blocked URL | `Blocked: ...` | Respect it. Includes non-http schemes, credentials, invalid hosts, non-public IPs, and policy denials. |
+| HTTP failure | `Failed to fetch URL: HTTP ...` | Fix the URL. A 404 automatically tries a Wayback snapshot. |
+| Non-text / binary | `(non-text content:` / `(binary content,` | Not readable as text by design. |
+| PDF without text | `(PDF contains no extractable text)` / `(PDF content could not be read as text...)` | Scanned or encrypted PDF. |
+| Download cap hit | `... (page truncated at the download limit)` | Raw fetch hit 512 KiB (10 MiB for PDFs). |
+| maxChars cut | `... (truncated, N chars total)` | Raise `maxChars` for the full text. |
+| Empty page | `(page returned no readable text)` | Page had no extractable text; JS-rendered pages need a browser tool. |
+| GitHub rewrite | `README of ... (fetched via the GitHub README API):` | Expected repo-root rewrite, not the HTML chrome. |
+| Cache fallback | `Served from cache` / `STALE cache from YYYY-MM-DD` | Network failed; output is the cached copy with its date. |
+| Wayback fallback | `Fetched from Wayback Machine snapshot (YYYY-MM-DD) for ...` | Original 404'd; output is the archived copy with its date. |
+
 ## Development
 
 ```sh

package/engines.ts

@@ -954,9 +954,9 @@ export async function autoTextSearch(
   const timedOutProviders = new Set<string>();
   let cancelled = false;
   const uniqueProviders = new Set(engines.map((e) => e.provider)).size;
-  const maxWorkers = Math.min(uniqueProviders, Math.ceil(maxResults / 10) + 1);
+  const maxWorkers = Math.min(uniqueProviders, Math.max(4, Math.ceil(maxResults / 5) + 1));
   let i = 0;
-  let pending: Promise<void>[] = [];
+  const pending = new Set<Promise<void>>();
   const run = async (engine: Engine) => {
     let results: SearchResult[] | null = null;
     for (let attempt = 0; attempt < 2 && results === null; attempt++) {
@@ -1000,18 +1000,35 @@ export async function autoTextSearch(
       if (aggregator.size >= maxResults) controller.abort();
     }
   };
-  while (i < engines.length) {
+  while (i < engines.length || pending.size > 0) {
     if (aggregator.size >= maxResults || cancelled) {
       controller.abort();
       break;
     }
-    const engine = engines[i++];
-    if (seenProviders.has(engine.provider)) continue;
-    pending.push(run(engine));
-    if (pending.length >= maxWorkers) {
-      await Promise.allSettled(pending);
-      pending = [];
+    while (i < engines.length && pending.size < maxWorkers) {
+      if (aggregator.size >= maxResults || cancelled) {
+        controller.abort();
+        break;
+      }
+      const engine = engines[i++];
+      if (seenProviders.has(engine.provider)) continue;
+      const task = run(engine);
+      pending.add(task);
+      void task.then(
+        () => {
+          pending.delete(task);
+        },
+        () => {
+          pending.delete(task);
+        },
+      );
+    }
+    if (pending.size === 0) break;
+    if (aggregator.size >= maxResults || cancelled) {
+      controller.abort();
+      break;
     }
+    await Promise.race(pending);
   }
   await Promise.allSettled(pending);
   if (onAbort && signal) signal.removeEventListener("abort", onAbort);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-unsloth-webtools",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "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",
@@ -55,16 +55,22 @@
     "test:smoke": "vitest run test/smoke.test.ts",
     "typecheck": "tsc --noEmit",
     "check:package": "node -e \"const fs=require('fs');const pkg=require('./package.json');const listed=new Set(pkg.files);const bad=[];for(const f of pkg.files){if(!fs.existsSync(f))bad.push('missing file: '+f)}for(const f of fs.readdirSync('.').filter(f=>f.endsWith('.ts'))){if(!listed.has(f))bad.push('unlisted source: '+f)}if(bad.length){console.error(bad.join('\\n'));process.exit(1)}\"",
-    "prepublishOnly": "npm run typecheck && npm run test:unit && npm run check:package"
+    "prepublishOnly": "npm run typecheck && npm run test:unit && npm run check:package && npm run check:publint",
+    "lint": "oxlint .",
+    "check:publint": "publint",
+    "check:attw": "attw --pack"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",
     "@types/node": "^24.0.0",
     "typebox": "^1.3.7",
     "typescript": "~5.9.3",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.9",
+    "@arethetypeswrong/cli": "^0.18.5",
+    "oxlint": "^1.81.0",
+    "publint": "^0.3.24"
   },
-  "dependencies": {
+  "optionalDependencies": {
     "mupdf": "^1.28.0"
   }
 }

package/web-access.ts

@@ -381,6 +381,8 @@ function ipv4Octets(ip: string): number[] | null {
 }
 
 export function isPublicIp(ip: string): boolean {
+  if (ip.includes("%")) return false;
+  if (ip.includes(".") && ip.includes(":")) return false;
   if (ip.includes(".")) {
     const o = ipv4Octets(ip);
     if (!o) return false;

package/web-fetch.ts

@@ -854,7 +854,13 @@ export async function fetchUrlRaw(
       Accept: "text/html,application/xhtml+xml,text/plain;q=0.9,*/*;q=0.5",
       "Accept-Encoding": "identity",
     };
-    if (options.extraHeaders) Object.assign(headers, options.extraHeaders);
+    if (options.extraHeaders) {
+      for (const [key, value] of Object.entries(options.extraHeaders)) {
+        if (key.toLowerCase() === "host") continue;
+        headers[key] = value;
+      }
+    }
+    headers["Host"] = hostHeader;
     const inactivity = remainingMs(deadline, now);
     let response: HopResponse;
     try {
@@ -1212,6 +1218,11 @@ async function fetchWaybackSnapshot(
     return null;
   }
   if (!snapshotUrl) return null;
+  const snapshotAccess = checkUrlAccess(snapshotUrl, options.websitePolicy ?? null);
+  if (!snapshotAccess[0]) return null;
+  const snapshotHost = snapshotAccess[2];
+  const snapshotIsIp = snapshotHost.includes(":") || /^\d+\.\d+\.\d+\.\d+$/.test(snapshotHost);
+  if (snapshotIsIp && !isPublicIp(snapshotHost)) return null;
   if (now() >= deadlineMs) return null;
   let snapResult: RawFetchResult | null = null;
   try {