pi-unsloth-webtools 0.3.1 → 0.4.0

package/README.md

@@ -51,7 +51,8 @@ Port of Studio's `_fetch_page_text` / `_fetch_url_raw` pipeline:
   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.
+  blocked at the resolved-IP layer (non-canonical numeric encodings like `0x7f.0.0.1` /
+  `013.0.0.1` / `2130706433` are rejected by URL validation before DNS).
 - 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
@@ -64,7 +65,7 @@ Port of Studio's `_fetch_page_text` / `_fetch_url_raw` pipeline:
   (`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.
   returning error-page content.
-- Up to 4 redirect hops, each re-validated and re-resolved against the same rules.
+- Up to 5 total requests (initial fetch + up to 4 HTTP redirects or `<meta http-equiv="refresh">` refreshes), each re-validated and re-resolved against the same rules.
 - 512 KiB download cap (10 MiB for PDFs), overall deadline + per-hop socket timeouts, abort-aware
   (`signal` cancels mid-flight). Fetches cut off by a download cap are marked with a trailing
   truncation notice, so a partial page is not mistaken for a complete one.
@@ -131,6 +132,50 @@ Port of Studio's `_fetch_page_text` / `_fetch_url_raw` pipeline:
   deliberately pins the Studio snapshot — seven engines, bing disabled upstream, no vqd,
   no pagination — so engine behavior matches Studio rather than ddgs head.
 
+## When to use alternatives
+
+This package is intentionally a faithful, zero-dependency port of Studio's pipeline. Use it
+when you need deterministic, offline-friendly behavior with strong SSRF guarantees and test
+parity with `unsloth/studio`. For other tradeoffs, prefer:
+
+| Need | Use |
+|---|---|
+| Browser-like TLS/HTTP fingerprinting to unblock bot-defended pages | `pi-smart-fetch` (`wreq-js` `chrome_145`) |
+| Headless Chrome for JS-rendered SPAs/YouTube/Reddit threads | `georgebashi/pi-web-fetch` (puppeteer + trafilatura) |
+| Hosted search with semantic ranking and no scraping | `Brave Search API` / `Tavily` / `Exa` via `pi-ollama-web-search` |
+| Prompt-focused page distillation to save context | `pi-web-fetch` `prompt` -> sub-agent or Claude Code `WebFetch(url,prompt)` |
+| Batch fetching many URLs concurrently | `pi-smart-fetch` `batch_web_fetch` or call `web_fetch` in parallel |
+
+Mixing is supported: `pi install npm:pi-unsloth-webtools npm:pi-smart-fetch` lets the model
+choose the best tool per URL. No need to fork this package to add those features.
+
+## Configuration
+
+Optional settings in `~/.pi/agent/settings.json` or `.pi/settings.json` (project overrides global):
+
+```json
+{
+  "unslothWebTools": {
+    "maxResults": 5,
+    "maxChars": 50000,
+    "timeoutMs": 60000
+  },
+  "webFetch": {
+    "maxChars": 50000,
+    "timeoutMs": 15000
+  }
+}
+```
+
+| Key | Default | Description |
+|---|---|---|
+| `unslothWebTools.maxResults` | `5` | Default `maxResults` for `web_search` (clamped 1-20) |
+| `unslothWebTools.maxChars` / `webFetch.maxChars` / `smartFetchDefaultMaxChars` | tool param | Default `maxChars` for `web_fetch` and `web_search` url mode |
+| `unslothWebTools.timeoutMs` / `webFetch.timeoutMs` / `smartFetchDefaultTimeoutMs` | `60000` | Default `timeoutMs` (>=1000) |
+| `webSearch.maxResults` / `smartWebSearch.resultsPerQuery` | same as above | Legacy aliases for `maxResults` |
+
+Tool params always win over file defaults.
+
 ## Development
 
 ```sh
@@ -165,7 +210,8 @@ The suite ports Unsloth Studio's own tests for these tools:
 - `test/entities.test.ts`: `decodeHtmlEntities` parity with CPython `html.unescape`,
   legacy refs, longest-prefix rule, Windows-1252 numeric mappings, invalid codepoints
 - `test/smoke.test.ts`: live network checks against real hosts, including a per-engine
-  result-health sweep (at least three engines must return well-formed results)
+  result-health sweep (at least two engines must return well-formed results; engines
+  that block or reset connections from datacenter IPs count as unhealthy, not failures)
 
 The seams (`seams.resolve` / `seams.request` / `rawFetch`) replace the network stack
 with fakes, mirroring how the Studio suite monkeypatches `_validate_and_resolve_host`

package/agent-dir.ts

@@ -0,0 +1,19 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+function expandAgentDir(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed === "~") return homedir();
+  if (trimmed.startsWith("~/") || trimmed.startsWith("~\\")) return join(homedir(), trimmed.slice(2));
+  return trimmed;
+}
+
+export function agentDir(): string {
+  const env = (process.env.PI_CODING_AGENT_DIR ?? process.env.PI_AGENT_DIR)?.trim();
+  if (env) return expandAgentDir(env);
+  try {
+    const home = homedir();
+    if (home) return join(home, ".pi", "agent");
+  } catch {}
+  return "";
+}

package/cache.ts

@@ -0,0 +1,154 @@
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, readdir, readFile, rename, stat, unlink, writeFile, chmod } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { agentDir } from "./agent-dir.ts";
+import { canonicalizeHref } from "./engines.ts";
+
+const CACHE_TTL_MS = 60 * 60 * 1000;
+const MAX_ENTRIES = 128;
+const MAX_BYTES = 128 * 1024 * 1024;
+const STALE_MAX_AGE_MS = 24 * CACHE_TTL_MS;
+
+function cacheDir(): string {
+  const env = process.env.PI_UNSLOTH_CACHE_DIR?.trim();
+  if (env) return env;
+  const base = agentDir();
+  if (base) return join(base, "pi-unsloth-cache");
+  return join(tmpdir(), "pi-unsloth-cache");
+}
+
+function cacheKey(url: string): string {
+  const canon = canonicalizeHref(url) || url;
+  return createHash("sha256").update(canon).digest("hex");
+}
+
+function cachePath(key: string): string {
+  return join(cacheDir(), `${key}.json`);
+}
+
+async function secureChmod(path: string, mode: number): Promise<void> {
+  if (process.platform === "win32") return;
+  try {
+    await chmod(path, mode);
+  } catch {}
+}
+
+async function unlinkSafe(path: string): Promise<boolean> {
+  try {
+    await unlink(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureDir(): Promise<void> {
+  const dir = cacheDir();
+  try {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await secureChmod(dir, 0o700);
+  } catch {}
+}
+
+export interface CacheEntry {
+  url: string;
+  body: string;
+  contentType: string;
+  timestamp: number;
+}
+
+export async function getCached(url: string): Promise<CacheEntry | null> {
+  const key = cacheKey(url);
+  const path = cachePath(key);
+  try {
+    const raw = await readFile(path, "utf8");
+    const entry = JSON.parse(raw) as CacheEntry;
+    if (!entry || typeof entry.body !== "string" || typeof entry.contentType !== "string" || typeof entry.timestamp !== "number") return null;
+    if (!Number.isFinite(entry.timestamp)) return null;
+    return entry;
+  } catch {
+    return null;
+  }
+}
+
+export async function setCached(url: string, body: string, contentType: string): Promise<void> {
+  await ensureDir();
+  const key = cacheKey(url);
+  const path = cachePath(key);
+  const entry: CacheEntry = { url: canonicalizeHref(url) || url, body, contentType, timestamp: Date.now() };
+  const tmpPath = `${path}.tmp.${process.pid}.${Date.now()}.${randomBytes(4).toString("hex")}`;
+  try {
+    await writeFile(tmpPath, JSON.stringify(entry), { mode: 0o600 });
+    await secureChmod(tmpPath, 0o600);
+    await rename(tmpPath, path);
+    await secureChmod(path, 0o600);
+  } catch {
+    await unlinkSafe(tmpPath);
+    return;
+  }
+  await prune();
+}
+
+async function prune(): Promise<void> {
+  const dir = cacheDir();
+  let files: string[];
+  try {
+    files = await readdir(dir);
+  } catch {
+    return;
+  }
+  const jsonFiles = files.filter((f) => f.endsWith(".json"));
+  if (!jsonFiles.length) return;
+  const now = Date.now();
+  const entries: { file: string; size: number; timestamp: number }[] = [];
+  let total = 0;
+  for (const file of jsonFiles) {
+    const full = join(dir, file);
+    try {
+      const s = await stat(full);
+      let timestamp = s.mtimeMs;
+      try {
+        const raw = await readFile(full, "utf8");
+        const entry = JSON.parse(raw) as CacheEntry;
+        if (entry && typeof entry.timestamp === "number" && Number.isFinite(entry.timestamp)) timestamp = entry.timestamp;
+      } catch {}
+      if (now - timestamp >= STALE_MAX_AGE_MS) {
+        await unlinkSafe(full);
+        continue;
+      }
+      entries.push({ file: full, size: s.size, timestamp });
+      total += s.size;
+    } catch {}
+  }
+  const expired = entries.filter((e) => now - e.timestamp >= CACHE_TTL_MS).sort((a, b) => a.timestamp - b.timestamp);
+  for (const e of expired) {
+    if (entries.length <= MAX_ENTRIES && total <= MAX_BYTES) break;
+    if (await unlinkSafe(e.file)) {
+      total -= e.size;
+      const idx = entries.indexOf(e);
+      if (idx !== -1) entries.splice(idx, 1);
+    }
+  }
+  if (entries.length <= MAX_ENTRIES && total <= MAX_BYTES) return;
+  entries.sort((a, b) => a.timestamp - b.timestamp);
+  let idx = 0;
+  while (idx < entries.length && (entries.length > MAX_ENTRIES || total > MAX_BYTES)) {
+    const e = entries[idx];
+    if (await unlinkSafe(e.file)) {
+      total -= e.size;
+      entries.splice(idx, 1);
+    } else {
+      idx++;
+    }
+  }
+}
+
+export function isFresh(entry: CacheEntry, now = Date.now()): boolean {
+  return now - entry.timestamp < CACHE_TTL_MS;
+}
+
+export function staleNotice(entry: CacheEntry): string {
+  const date = new Date(entry.timestamp).toISOString().slice(0, 10);
+  return `\n\n*STALE cache from ${date} — network fetch failed, serving cached copy*`;
+}

package/engines.ts

@@ -1,7 +1,11 @@
 import { randomBytes } from "node:crypto";
+import { appendFile, chmod, mkdir } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
 import { collapseWhitespace, decodeHtmlEntities, feedHtml } from "./html-to-md.ts";
 import type { AttrDict } from "./html-to-md.ts";
 import { randomUserAgent } from "./user-agents.ts";
+import { agentDir } from "./agent-dir.ts";
+import { MAX_SIGNAL_TIMEOUT_MS } from "./web-access.ts";
 export class EmptySweepError extends Error {
   constructor() {
     super("No results found");
@@ -9,8 +13,10 @@ export class EmptySweepError extends Error {
 }
 
 export class SearchTimeoutError extends Error {
-  constructor() {
+  providers: string[];
+  constructor(providers: string[] = []) {
     super("timed out");
+    this.providers = providers;
   }
 }
 
@@ -556,7 +562,8 @@ async function httpFetch(
         .join("; ")
     : null;
   if (cookie) headers["Cookie"] = cookie;
-  const signals: AbortSignal[] = [AbortSignal.timeout(options.timeoutMs)];
+  const timeoutMs = Math.min(MAX_SIGNAL_TIMEOUT_MS, Math.max(1, options.timeoutMs));
+  const signals: AbortSignal[] = [AbortSignal.timeout(timeoutMs)];
   if (options.signal) signals.push(options.signal);
   let response: Response;
   try {
@@ -840,6 +847,40 @@ export function rankResults(docs: SearchResult[], query: string): SearchResult[]
   }
   return [...wiki, ...both, ...titleOnly, ...bodyOnly, ...neither];
 }
+async function recordSweepStats(query: string, maxResults: number, started: number, timedOutProviders: string[], resultCount: number): Promise<void> {
+  const flag = process.env.PI_UNSLOTH_WEBTOOLS_STATS?.trim();
+  if (!flag) return;
+  const lower = flag.toLowerCase();
+  if (lower === "0" || lower === "false" || lower === "no" || lower === "off") return;
+  const base = agentDir();
+  if (!base) return;
+  const isDefaultFlag = lower === "1" || lower === "true" || lower === "yes" || lower === "on";
+  const statsPath = isDefaultFlag ? join(base, "pi-unsloth-webtools-stats.jsonl") : isAbsolute(flag) ? flag : join(base, flag);
+  try {
+    const dir = dirname(statsPath);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32") {
+      try {
+        await chmod(dir, 0o700);
+      } catch {}
+    }
+    const sortedProviders = [...timedOutProviders].sort();
+    const entry = JSON.stringify({
+      ts: new Date().toISOString(),
+      query,
+      maxResults,
+      durationMs: Date.now() - started,
+      timedOutProviders: sortedProviders,
+      resultCount,
+    });
+    await appendFile(statsPath, entry + "\n", { mode: 0o600 });
+    if (process.platform !== "win32") {
+      try {
+        await chmod(statsPath, 0o600);
+      } catch {}
+    }
+  } catch {}
+}
 
 function shuffledEngines(): Engine[] {
   const shuffled = [...TEXT_ENGINES];
@@ -858,13 +899,22 @@ export async function autoTextSearch(
   timeoutMs: number,
   signal?: AbortSignal,
 ): Promise<SearchResult[]> {
+  const started = Date.now();
   const engines = shuffledEngines();
-  const deadline = Date.now() + timeoutMs;
+  const deadline = started + timeoutMs;
   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 onAbort: (() => void) | undefined;
+  if (signal) {
+    if (signal.aborted) controller.abort();
+    else {
+      onAbort = () => controller.abort();
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  }
+  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);
@@ -873,7 +923,10 @@ 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;
+      if (controller.signal.aborted) {
+        if (signal?.aborted) cancelled = true;
+        return;
+      }
       const budgetLeft = deadline - Date.now();
       if (budgetLeft <= 0) return;
       if (attempt > 0 && budgetLeft < ENGINE_RETRY_BACKOFF_MS) return;
@@ -890,7 +943,7 @@ export async function autoTextSearch(
           return;
         }
         if (e instanceof SearchTimeoutError) {
-          timedOut = true;
+          timedOutProviders.add(engine.name);
           return;
         }
       }
@@ -924,9 +977,18 @@ export async function autoTextSearch(
     }
   }
   await Promise.allSettled(pending);
+  if (onAbort && signal) signal.removeEventListener("abort", onAbort);
   if (cancelled) throw new SearchCancelled();
   const results = rankResults(aggregator.extractDicts(), query);
-  if (results.length) return results.slice(0, maxResults);
-  if (timedOut) throw new SearchTimeoutError();
+  if (results.length) {
+    void recordSweepStats(query, maxResults, started, [...timedOutProviders], results.length);
+    return results.slice(0, maxResults);
+  }
+  if (timedOutProviders.size) {
+    const sorted = [...timedOutProviders].sort();
+    void recordSweepStats(query, maxResults, started, sorted, 0);
+    throw new SearchTimeoutError(sorted);
+  }
+  void recordSweepStats(query, maxResults, started, [], 0);
   throw new EmptySweepError();
 }

package/html-to-md.ts

@@ -1086,8 +1086,13 @@ function visibleLineChars(line: string): number {
   let openBracket = false;
   while (i < n) {
     if (line[i] === "\\") {
-      total += 2;
-      i += 2;
+      if (i + 1 < n) {
+        total += 2;
+        i += 2;
+      } else {
+        total += 1;
+        i += 1;
+      }
       continue;
     }
     if (line[i] === "[") openBracket = true;
@@ -1097,7 +1102,11 @@ function visibleLineChars(line: string): number {
       while (j < n && depth) {
         const char = line[j];
         if (char === "\\") {
-          j += 2;
+          if (j + 1 < n) {
+            j += 2;
+          } else {
+            j += 1;
+          }
           continue;
         }
         depth += (char === "(" ? 1 : 0) - (char === ")" ? 1 : 0);

package/index.ts

@@ -1,10 +1,23 @@
-import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { webSearch as defaultWebSearch } from "./web-search.ts";
 import { DEFAULT_FETCH_TIMEOUT_MS, fetchPageText as defaultFetchPageText } from "./web-fetch.ts";
+import { loadDefaultFetchSettings } from "./settings.ts";
 
 function positiveNumber(value: unknown): number | undefined {
-  return typeof value === "number" && value > 0 ? value : undefined;
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  const n = Math.floor(value);
+  return n > 0 ? n : undefined;
+}
+async function fetchDefaults(cwd: string | undefined, params: { timeoutMs?: unknown; maxChars?: unknown }) {
+  const timeoutParam = positiveNumber(params.timeoutMs);
+  const maxCharsParam = positiveNumber(params.maxChars);
+  if (timeoutParam !== undefined && maxCharsParam !== undefined) return { timeoutMs: timeoutParam, maxChars: maxCharsParam };
+  const defaults = await loadDefaultFetchSettings(cwd);
+  return {
+    timeoutMs: timeoutParam ?? defaults.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS,
+    maxChars: maxCharsParam ?? defaults.maxChars,
+  };
 }
 
 const WebSearchParams = Type.Object({
@@ -77,14 +90,16 @@ export function createWebTools(deps: WebToolsDeps = {}) {
         if (params.url?.trim()) {
           const url = params.url.trim();
           onUpdate?.({ content: [{ type: "text", text: `Fetching ${url}...` }], details: {} });
+          const cwd = (_ctx as ExtensionContext | undefined)?.cwd;
+          const { timeoutMs, maxChars } = await fetchDefaults(cwd, params);
           return {
             content: [
               {
                 type: "text",
                 text: await fetchPageText(url, {
-                  timeoutMs: positiveNumber(params.timeoutMs) ?? DEFAULT_FETCH_TIMEOUT_MS,
+                  timeoutMs,
                   signal: signal ?? undefined,
-                  maxChars: positiveNumber(params.maxChars),
+                  maxChars,
                 }),
               },
             ],
@@ -96,6 +111,7 @@ export function createWebTools(deps: WebToolsDeps = {}) {
           signal: signal ?? undefined,
           timeoutMs: positiveNumber(params.timeoutMs),
           maxResults: positiveNumber(params.maxResults),
+          cwd: (_ctx as ExtensionContext | undefined)?.cwd,
         });
         return { content: [{ type: "text", text }], details: {} };
       },
@@ -114,10 +130,12 @@ export function createWebTools(deps: WebToolsDeps = {}) {
       parameters: WebFetchParams,
       async execute(_toolCallId, params, signal, onUpdate, _ctx) {
         onUpdate?.({ content: [{ type: "text", text: `Fetching ${params.url}...` }], details: {} });
+        const cwd = (_ctx as ExtensionContext | undefined)?.cwd;
+        const { timeoutMs, maxChars } = await fetchDefaults(cwd, params);
         const text = await fetchPageText(params.url, {
-          timeoutMs: positiveNumber(params.timeoutMs) ?? DEFAULT_FETCH_TIMEOUT_MS,
+          timeoutMs,
           signal: signal ?? undefined,
-          maxChars: positiveNumber(params.maxChars),
+          maxChars,
         });
         return { content: [{ type: "text", text }], details: {} };
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-unsloth-webtools",
-  "version": "0.3.1",
+  "version": "0.4.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",
@@ -31,6 +31,9 @@
     "entities.ts",
     "pdf.ts",
     "user-agents.ts",
+    "cache.ts",
+    "settings.ts",
+    "agent-dir.ts",
     "README.md",
     "LICENSE"
   ],

package/pdf.ts

@@ -594,7 +594,7 @@ function assemblePages(
   pageLimitOverride?: boolean,
 ): string {
   const parts: string[] = [];
-  const pageLimitReached = pageLimitOverride ?? pages.length >= MAX_WEB_PDF_PAGES;
+  const pageLimitReached = pageLimitOverride ?? pages.length > MAX_WEB_PDF_PAGES;
   for (const page of pages) {
     const pageText = page.text.trim();
     if (!pageText) continue;

package/settings.ts

@@ -0,0 +1,114 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { agentDir } from "./agent-dir.ts";
+
+async function readJson(file: string): Promise<Record<string, unknown> | undefined> {
+  try {
+    const raw = await readFile(file, "utf-8");
+    const data = JSON.parse(raw);
+    if (data && typeof data === "object" && !Array.isArray(data)) return data as Record<string, unknown>;
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function toNumber(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  return Math.floor(value);
+}
+
+function pickNumber(data: Record<string, unknown>, paths: string[][]): number | undefined {
+  for (const path of paths) {
+    let cur: unknown = data;
+    for (const key of path) {
+      if (cur && typeof cur === "object" && !Array.isArray(cur)) cur = (cur as Record<string, unknown>)[key];
+      else {
+        cur = undefined;
+        break;
+      }
+    }
+    const n = toNumber(cur);
+    if (n !== undefined) return n;
+  }
+  return undefined;
+}
+
+const MAX_RESULTS = 5;
+
+const MAX_RESULTS_PATHS: string[][] = [
+  ["unslothWebTools", "maxResults"],
+  ["webSearch", "maxResults"],
+  ["smartWebSearch", "resultsPerQuery"],
+];
+
+const FETCH_MAX_CHARS_PATHS: string[][] = [
+  ["unslothWebTools", "maxChars"],
+  ["webFetch", "maxChars"],
+  ["smartFetchDefaultMaxChars"],
+];
+
+const FETCH_TIMEOUT_PATHS: string[][] = [
+  ["unslothWebTools", "timeoutMs"],
+  ["webFetch", "timeoutMs"],
+  ["smartFetchDefaultTimeoutMs"],
+];
+
+function clampMaxResults(value: number): number {
+  return Math.min(20, Math.max(1, value));
+}
+
+function settingsFiles(cwd?: string): string[] {
+  const base = agentDir();
+  const globalFile = base ? join(base, "settings.json") : "";
+  const files = globalFile ? [globalFile] : [];
+  if (cwd) files.push(join(cwd, ".pi", "settings.json"));
+  return files;
+}
+
+async function settingsEntries(cwd?: string): Promise<Record<string, unknown>[]> {
+  const entries: Record<string, unknown>[] = [];
+  for (const file of settingsFiles(cwd)) {
+    const data = await readJson(file);
+    if (data) entries.push(data);
+  }
+  return entries;
+}
+
+export async function loadDefaultMaxResults(cwd?: string): Promise<number> {
+  let result = MAX_RESULTS;
+  for (const data of await settingsEntries(cwd)) {
+    const candidate = pickNumber(data, MAX_RESULTS_PATHS);
+    if (candidate !== undefined) result = clampMaxResults(candidate);
+  }
+  return result;
+}
+
+async function loadFetchSetting(cwd: string | undefined, paths: string[][], valid: (n: number) => boolean): Promise<number | undefined> {
+  let result: number | undefined;
+  for (const data of await settingsEntries(cwd)) {
+    const candidate = pickNumber(data, paths);
+    if (candidate !== undefined && valid(candidate)) result = candidate;
+  }
+  return result;
+}
+
+export async function loadDefaultFetchMaxChars(cwd?: string): Promise<number | undefined> {
+  return loadFetchSetting(cwd, FETCH_MAX_CHARS_PATHS, (n) => n > 0);
+}
+
+export async function loadDefaultFetchTimeoutMs(cwd?: string): Promise<number | undefined> {
+  return loadFetchSetting(cwd, FETCH_TIMEOUT_PATHS, (n) => n >= 1000);
+}
+
+export async function loadDefaultFetchSettings(cwd?: string): Promise<{ maxChars?: number; timeoutMs?: number }> {
+  let maxChars: number | undefined;
+  let timeoutMs: number | undefined;
+  for (const data of await settingsEntries(cwd)) {
+    const c = pickNumber(data, FETCH_MAX_CHARS_PATHS);
+    if (c !== undefined && c > 0) maxChars = c;
+    const t = pickNumber(data, FETCH_TIMEOUT_PATHS);
+    if (t !== undefined && t >= 1000) timeoutMs = t;
+  }
+  return { maxChars, timeoutMs };
+}