pi-unsloth-webtools 0.4.1 → 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

@@ -216,6 +216,10 @@ function parsePredExpr(input: string): Pred {
       pos += "position()=last()".length;
       return { op: "last" };
     }
+    if (input.startsWith("last()", pos)) {
+      pos += "last()".length;
+      return { op: "last" };
+    }
     if (input.startsWith("contains(@class,", pos)) {
       pos += "contains(@class,".length;
       const value = quoted();
@@ -359,7 +363,38 @@ function matchesPred(pred: Pred, el: DomNode, index: number, total: number): boo
   }
 }
 
+function predContainsLast(pred: Pred): boolean {
+  switch (pred.op) {
+    case "last":
+      return true;
+    case "or":
+    case "and":
+      return predContainsLast(pred.a) || predContainsLast(pred.b);
+    case "child":
+      return pred.preds.some(predContainsLast);
+    default:
+      return false;
+  }
+}
+
 function applyStep(step: XStep, nodes: DomNode[]): DomNode[] {
+  if (step.preds.some(predContainsLast)) {
+    const out: DomNode[] = [];
+    const seen = new Set<DomNode>();
+    for (const node of nodes) {
+      const source = step.axis === "child" ? node.children : descendantsOf(node);
+      const list = source.filter((c) => !step.name || c.tag === step.name);
+      const total = list.length;
+      list.forEach((el, index) => {
+        if (seen.has(el)) return;
+        if (step.preds.every((p) => matchesPred(p, el, index, total))) {
+          seen.add(el);
+          out.push(el);
+        }
+      });
+    }
+    return out;
+  }
   const candidates: DomNode[] = [];
   for (const node of nodes) {
     const list = step.axis === "child" ? node.children : descendantsOf(node);
@@ -427,6 +462,7 @@ export function extractResults(
       if (!data) continue;
       result[key] = key === "href" ? normalizeUrl(data) : normalizeText(data);
     }
+    if (!result.title && !result.href && !result.body) continue;
     results.push(result);
   }
   return results;
@@ -445,8 +481,7 @@ function googleUserAgent(): string {
   return (
     `Mozilla/5.0 (Linux; Android ${androidVer}; ${device}) ` +
     `AppleWebKit/537.36 (KHTML, like Gecko) ` +
-    `Chrome/${chromeMajor}.0.${chromeBuild}.${chromePatch} Mobile Safari/537.36` +
-    "NSTNWV"
+    `Chrome/${chromeMajor}.0.${chromeBuild}.${chromePatch} Mobile Safari/537.36`
   );
 }
 
@@ -794,7 +829,9 @@ export class ResultsAggregator {
   }
 
   append(item: SearchResult): void {
+    if (typeof item.href !== "string" || !item.href.trim()) return;
     const key = canonicalizeHref(item.href);
+    if (!key) return;
     const existing = this.cache.get(key);
     if (!existing || item.body.length > existing.body.length) {
       this.cache.set(key, { ...item, href: key });
@@ -917,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++) {
@@ -963,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.1",
+  "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/pdf.ts

@@ -344,7 +344,7 @@ function findLink(links: LinkInfo[], span: SpanData): string | null {
     if (midX < link.x0 || midX > link.x1 || midY < link.y0 || midY > link.y1) continue;
     let uri = link.uri;
     for (const c of "()\n") {
-      uri = uri.replaceAll(c, "%0x" + c.charCodeAt(0).toString(16));
+      uri = uri.replaceAll(c, "%" + c.charCodeAt(0).toString(16).padStart(2, "0"));
     }
     return `[${span.text.trim()}](${uri})`;
   }

package/web-access.ts

@@ -137,7 +137,7 @@ export function normalizeWebsitePolicy(value: unknown): WebsitePolicy {
   }
   const normalized: WebsitePolicy = { allowedDomains: [], blockedDomains: [] };
   for (const key of ["allowedDomains", "blockedDomains"] as const) {
-    const rawDomains = raw[key];
+    const rawDomains = raw[key] ?? [];
     if (!Array.isArray(rawDomains)) throw new Error(`${key} must be a list`);
     if (rawDomains.length > MAX_DOMAINS_PER_LIST) {
       throw new Error(`${key} supports at most ${MAX_DOMAINS_PER_LIST} domains`);
@@ -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;
@@ -408,7 +410,7 @@ export function isPublicIp(ip: string): boolean {
   }
   if (canonical === "::1" || canonical.startsWith("::")) return false;
   if (canonical.startsWith("fc") || canonical.startsWith("fd")) return false;
-  if (/^fe[89ab][0-9a-f]:/.test(canonical)) return false;
+  if (/^fe[89a-f][0-9a-f]:/.test(canonical)) return false;
   if (canonical.startsWith("ff")) return false;
   if (canonical.startsWith("2001:db8")) return false;
   if (canonical.startsWith("64:ff9b:")) return false;

package/web-fetch.ts

@@ -810,16 +810,22 @@ export async function fetchUrlRaw(
   const performRequest = seams.request ?? requestHop;
   const resolveWithBudget = async (hostname: string): Promise<ResolvedHost> => {
     const abortController = new AbortController();
-    const timeoutId = setTimeout(() => abortController.abort(), clampedRemainingMs(deadline, now));
+    const waitMs = clampedRemainingMs(deadline, now);
+    const timeoutId = setTimeout(() => abortController.abort(), waitMs);
     const resolveSignal = signal ? AbortSignal.any([signal, abortController.signal]) : abortController.signal;
+    let deadlineId: ReturnType<typeof setTimeout> | undefined;
+    const deadlinePromise = new Promise<ResolvedHost>((resolve) => {
+      deadlineId = setTimeout(() => resolve({ ok: false, reason: FETCH_TIMEOUT_MESSAGE, ip: "", family: 0 }), waitMs);
+    });
     try {
-      const resolved = await resolveHost(hostname, resolveSignal);
+      const resolved = await Promise.race([resolveHost(hostname, resolveSignal), deadlinePromise]);
       if (resolved.ok) return resolved;
       if (signal?.aborted) return { ...resolved, reason: FETCH_CANCELLED_MESSAGE };
       if (resolveSignal.aborted) return { ...resolved, reason: FETCH_TIMEOUT_MESSAGE };
       return resolved;
     } finally {
       clearTimeout(timeoutId);
+      if (deadlineId !== undefined) clearTimeout(deadlineId);
     }
   };
   const checkBudget = (contentType = ""): RawFetchResult | null => budgetExceededResult(deadline, signal, now, contentType);
@@ -848,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 {
@@ -1206,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 {

package/web-search.ts

@@ -23,15 +23,16 @@ export type SearchClient = (
   query: string,
   maxResults: number,
   signal?: AbortSignal,
+  timeoutMs?: number,
 ) => Promise<SearchResult[]>;
-
 export async function ddgSearch(
   query: string,
   maxResults = MAX_RESULTS,
   signal?: AbortSignal,
+  timeoutMs = SEARCH_TIMEOUT_MS,
 ): Promise<SearchResult[]> {
   if (signal?.aborted) throw new SearchCancelled();
-  return autoTextSearch(query, maxResults, SEARCH_TIMEOUT_MS, signal);
+  return autoTextSearch(query, maxResults, timeoutMs, signal);
 }
 
 const POLICY_OVERFETCH = 4;
@@ -51,8 +52,11 @@ export async function webSearch(
   query: string | undefined,
   options: WebSearchOptions = {},
 ): Promise<string> {
-  const maxResults = options.maxResults ?? (await loadDefaultMaxResults(options.cwd));
-  const timeoutMs = options.timeoutMs ?? SEARCH_TIMEOUT_MS;
+  const rawMaxResults = options.maxResults ?? (await loadDefaultMaxResults(options.cwd));
+  const saneMax = Number.isFinite(rawMaxResults) ? Math.floor(rawMaxResults as number) : MAX_RESULTS;
+  const maxResults = Math.min(20, Math.max(1, saneMax));
+  const rawTimeout = options.timeoutMs ?? SEARCH_TIMEOUT_MS;
+  const timeoutMs = Number.isFinite(rawTimeout) ? (rawTimeout as number) : SEARCH_TIMEOUT_MS;
   const signal = options.signal;
   const policy = options.websitePolicy ?? null;
   const client = options.client ?? ddgSearch;
@@ -66,14 +70,15 @@ export async function webSearch(
         (policy?.blockedDomains?.length ?? 0) > 0,
     );
     const wanted = restricted ? maxResults * POLICY_OVERFETCH : maxResults;
-    const results = await client(effectiveQuery, wanted, signal);
+    const results = await client(effectiveQuery, wanted, signal, timeoutMs);
     if (signal?.aborted) return "Search cancelled.";
     if (!results.length) return EMPTY_SEARCH_RESULTS[0];
     const allowed: SearchResult[] = [];
     for (const result of results) {
       if (allowed.length >= maxResults) break;
       const href = String(result.href ?? "").trim();
-      if (href && !checkUrlAccess(href, policy)[0]) continue;
+      if (!href) continue;
+      if (!checkUrlAccess(href, policy)[0]) continue;
       allowed.push(result);
     }
     if (!allowed.length) return EMPTY_SEARCH_RESULTS[1];