@bacnh85/pi-web 0.4.1 → 0.4.4

package/extensions/test/unit/format.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Unit tests for pi-web format module.
+ */
+
+import { expect } from "chai";
+import {
+	sanitizeSnippet,
+	truncateText,
+	formatFirecrawlScrape,
+	formatCrawl4aiResult,
+	type SearchResultItem,
+} from "../../lib/format";
+
+const OUTPUT_MAX_BYTES = 50 * 1024;
+const OUTPUT_MAX_LINES = 2_000;
+
+describe("sanitizeSnippet", () => {
+	it("returns empty string for empty input", () => {
+		expect(sanitizeSnippet()).to.equal("");
+		expect(sanitizeSnippet("")).to.equal("");
+	});
+
+	it("strips HTML tags", () => {
+		expect(sanitizeSnippet("<b>hello</b> world")).to.equal("hello world");
+	});
+
+	it("decodes HTML entities", () => {
+		expect(sanitizeSnippet("foo &amp; bar")).to.equal("foo & bar");
+		expect(sanitizeSnippet("&lt;tag&gt;")).to.equal("<tag>");
+		expect(sanitizeSnippet("&quot;quoted&quot;")).to.equal('"quoted"');
+		expect(sanitizeSnippet("hello&nbsp;world")).to.equal("hello world");
+	});
+
+	it("decodes numeric HTML entities", () => {
+		expect(sanitizeSnippet("&#65;")).to.equal("A");
+		expect(sanitizeSnippet("&#x41;")).to.equal("A");
+	});
+
+	it("collapses whitespace", () => {
+		expect(sanitizeSnippet("hello   world")).to.equal("hello world");
+		expect(sanitizeSnippet("  hello  ")).to.equal("hello");
+	});
+});
+
+describe("truncateText", () => {
+	it("returns short text as-is", () => {
+		const text = "hello world";
+		expect(truncateText(text)).to.equal(text);
+	});
+
+	it("truncates by line count when exceeding OUTPUT_MAX_LINES", () => {
+		const lines = Array.from({ length: OUTPUT_MAX_LINES + 10 }, (_, i) => `line ${i}`);
+		const text = lines.join("\n");
+		const result = truncateText(text);
+		expect(result).to.include("[Web output truncated to");
+		expect(result.split("\n").length).to.be.lessThan(OUTPUT_MAX_LINES + 15);
+	});
+
+	it("truncates by byte count when exceeding OUTPUT_MAX_BYTES", () => {
+		const text = "x".repeat(OUTPUT_MAX_BYTES + 50000);
+		const result = truncateText(text);
+		expect(result).to.include("[Web output truncated to");
+	});
+
+	it("handles empty string", () => {
+		expect(truncateText("")).to.equal("");
+	});
+});
+
+describe("formatFirecrawlScrape", () => {
+	it("formats scrape data with metadata", () => {
+		const data = {
+			data: {
+				metadata: {
+					title: "Test Page",
+					sourceURL: "https://example.com",
+					statusCode: 200,
+				},
+				markdown: "# Hello\n\nThis is content.",
+			},
+		};
+		const output = formatFirecrawlScrape(data);
+		expect(output).to.include("# Test Page");
+		expect(output).to.include("Source: https://example.com");
+		expect(output).to.include("Status: 200");
+		expect(output).to.include("# Hello");
+		expect(output).to.include("This is content.");
+	});
+
+	it("resolves data at top level when no nested data", () => {
+		const data = {
+			metadata: { title: "Direct" },
+			markdown: "Content",
+		};
+		const output = formatFirecrawlScrape(data);
+		expect(output).to.include("# Direct");
+		expect(output).to.include("Content");
+	});
+
+	it("includes warning when present", () => {
+		const data = { data: { markdown: "x" }, warning: "Rate limited" };
+		const output = formatFirecrawlScrape(data);
+		expect(output).to.include("Warning: Rate limited");
+	});
+
+	it("includes links when present", () => {
+		const data = {
+			data: {
+				markdown: "body",
+				links: ["https://a.com", "https://b.com"],
+			},
+		};
+		const output = formatFirecrawlScrape(data);
+		expect(output).to.include("## Links");
+		expect(output).to.include("- https://a.com");
+	});
+
+	it("returns JSON stringify fallback for empty data", () => {
+		const data = { foo: "bar" };
+		const output = formatFirecrawlScrape(data);
+		expect(output).to.include("foo");
+	});
+});
+
+describe("formatCrawl4aiResult", () => {
+	it("formats a single successful crawl result with markdown", () => {
+		const data = {
+			url: "https://example.com",
+			success: true,
+			status_code: 200,
+			markdown: { fit_markdown: "# Hello\n\nWorld content." },
+		};
+		const output = formatCrawl4aiResult(data);
+		expect(output).to.include("URL: https://example.com");
+		expect(output).to.include("Status: 200");
+		expect(output).to.include("# Hello");
+	});
+
+	it("shows error for failed crawl", () => {
+		const data = {
+			url: "https://example.com/404",
+			success: false,
+			error_message: "Not Found",
+		};
+		const output = formatCrawl4aiResult(data);
+		expect(output).to.include("Error: Not Found");
+		expect(output).to.include("URL: https://example.com/404");
+	});
+
+	it("formats multiple results from wrapped response", () => {
+		const data = {
+			results: [
+				{ url: "https://a.com", success: true, markdown: { raw_markdown: "Page A" } },
+				{ url: "https://b.com", success: true, markdown: { raw_markdown: "Page B" } },
+			],
+		};
+		const output = formatCrawl4aiResult(data);
+		expect(output).to.include("=== Result 1 ===");
+		expect(output).to.include("=== Result 2 ===");
+		expect(output).to.include("Page A");
+		expect(output).to.include("Page B");
+	});
+
+	it("falls back to raw_markdown when fit_markdown is absent", () => {
+		const data = {
+			url: "https://example.com",
+			success: true,
+			markdown: { raw_markdown: "Raw content only" },
+		};
+		const output = formatCrawl4aiResult(data);
+		expect(output).to.include("Raw content only");
+	});
+
+	it("includes links when present", () => {
+		const data = {
+			url: "https://example.com",
+			success: true,
+			markdown: { fit_markdown: "body" },
+			links: {
+				internal: [{ href: "https://example.com/about" }],
+				external: [{ href: "https://other.com" }],
+			},
+		};
+		const output = formatCrawl4aiResult(data);
+		expect(output).to.include("Links");
+		expect(output).to.include("https://example.com/about");
+	});
+
+	it("returns fallback for empty data", () => {
+		expect(formatCrawl4aiResult({})).to.equal("(No data)");
+	});
+});
+
+

package/extensions/test/unit/search.test.ts

@@ -0,0 +1,147 @@
+import { expect } from "chai";
+
+import {
+	searchWithDiagnostics,
+	selectSearchBackendOrder,
+	type SearchParams,
+	type SearchResult,
+} from "../../lib/search";
+
+const ORIGINAL_ENV = { ...process.env };
+const ORIGINAL_FETCH = globalThis.fetch;
+
+function jsonResponse(body: unknown, status = 200): Response {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "content-type": "application/json" },
+	});
+}
+
+function htmlResponse(body: string, status = 200): Response {
+	return new Response(body, {
+		status,
+		headers: { "content-type": "text/html" },
+	});
+}
+
+function installMockFetch(handler: (url: string, init?: RequestInit) => Response | Promise<Response>): string[] {
+	const calls: string[] = [];
+	globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+		const url = String(input);
+		calls.push(url);
+		return handler(url, init);
+	}) as typeof fetch;
+	return calls;
+}
+
+function restoreEnv(): void {
+	process.env = { ...ORIGINAL_ENV };
+}
+
+describe("SearchParams and SearchResult types", () => {
+	it("accept expected fields", () => {
+		const params: SearchParams = { query: "test", backend: "auto", signal: new AbortController().signal };
+		const result: SearchResult = { title: "T", url: "https://example.com", snippet: "S", age: "", content: "", backend: "brave" };
+		expect(params.backend).to.equal("auto");
+		expect(result.backend).to.equal("brave");
+	});
+});
+
+describe("selectSearchBackendOrder", () => {
+	it("selects Brave first for include_content", () => {
+		expect(selectSearchBackendOrder({ query: "homelab ansible", include_content: true })).to.deep.equal(["brave", "searxng", "firecrawl"]);
+	});
+
+	it("selects Brave first for site: and precision queries", () => {
+		expect(selectSearchBackendOrder({ query: "site:docs.ansible.com podman quadlet" })).to.deep.equal(["brave", "searxng", "firecrawl"]);
+		expect(selectSearchBackendOrder({ query: '"exact phrase" release notes' })).to.deep.equal(["brave", "searxng", "firecrawl"]);
+	});
+
+	it("keeps SearXNG first for broad discovery and explicit engines", () => {
+		expect(selectSearchBackendOrder({ query: "homelab ansible ideas" })).to.deep.equal(["searxng", "brave", "firecrawl"]);
+		expect(selectSearchBackendOrder({ query: "docs api", engines: "google,github" })).to.deep.equal(["searxng", "brave", "firecrawl"]);
+	});
+
+	it("honors explicit backend", () => {
+		expect(selectSearchBackendOrder({ query: "test", backend: "firecrawl" })).to.deep.equal(["firecrawl"]);
+	});
+});
+
+describe("searchWithDiagnostics", () => {
+	beforeEach(() => {
+		restoreEnv();
+		process.env.BRAVE_API_KEY = "test-brave-key";
+		process.env.SEARXNG_BASE_URL = "http://searxng.test";
+		process.env.FIRECRAWL_API_URL = "http://firecrawl.test/v2";
+	});
+
+	afterEach(() => {
+		globalThis.fetch = ORIGINAL_FETCH;
+		restoreEnv();
+	});
+
+	it("uses Brave first for include_content and fetches inline content", async () => {
+		const calls = installMockFetch((url) => {
+			if (url.startsWith("https://api.search.brave.com/")) {
+				return jsonResponse({ web: { results: [{ title: "Brave", url: "https://example.com/page", description: "Snippet" }] } });
+			}
+			if (url === "https://example.com/page") {
+				return htmlResponse("<html><head><title>Page</title></head><body><main><h1>Page</h1><p>This is long enough readable content for the inline content fetch test.</p></main></body></html>");
+			}
+			throw new Error(`unexpected fetch ${url}`);
+		});
+
+		const result = await searchWithDiagnostics({ query: "homelab ansible", include_content: true });
+		expect(result.selectedBackend).to.equal("brave");
+		expect(result.backendOrder[0]).to.equal("brave");
+		expect(result.results[0].content).to.include("readable content");
+		expect(calls[0]).to.include("api.search.brave.com");
+	});
+
+	it("uses SearXNG first for broad discovery", async () => {
+		const calls = installMockFetch((url) => {
+			if (url.startsWith("http://searxng.test/search")) {
+				return jsonResponse({ results: [{ title: "SearXNG", url: "https://example.com", content: "Snippet" }] });
+			}
+			throw new Error(`unexpected fetch ${url}`);
+		});
+
+		const result = await searchWithDiagnostics({ query: "homelab ansible ideas" });
+		expect(result.selectedBackend).to.equal("searxng");
+		expect(result.attempts).to.deep.include({ backend: "searxng", status: "success", message: "Selected searxng", resultCount: 1 });
+		expect(calls[0]).to.include("searxng.test");
+	});
+
+	it("captures backend errors and falls through to Firecrawl last", async () => {
+		installMockFetch((url) => {
+			if (url.startsWith("http://searxng.test/search")) return jsonResponse({ results: [] });
+			if (url.startsWith("https://api.search.brave.com/")) return jsonResponse({ error: "rate limited" }, 429);
+			if (url.startsWith("http://firecrawl.test/v2/search")) {
+				return jsonResponse({ data: { web: [{ title: "Fire", url: "https://fire.example", description: "Fallback" }] } });
+			}
+			throw new Error(`unexpected fetch ${url}`);
+		});
+
+		const result = await searchWithDiagnostics({ query: "homelab ansible ideas" });
+		expect(result.selectedBackend).to.equal("firecrawl");
+		expect(result.attempts.map((a) => a.backend)).to.deep.equal(["searxng", "brave", "firecrawl"]);
+		expect(result.attempts[1].status).to.equal("error");
+		expect(result.attempts[1].message).not.to.include("test-brave-key");
+	});
+
+	it("explicit backend tries only that backend", async () => {
+		const calls = installMockFetch((url) => {
+			if (url.startsWith("http://searxng.test/search")) return jsonResponse({ results: [] });
+			throw new Error(`unexpected fetch ${url}`);
+		});
+
+		try {
+			await searchWithDiagnostics({ query: "nothing", backend: "searxng" });
+			expect.fail("expected search to fail");
+		} catch (e: any) {
+			expect(e.message).to.include("searxng: empty");
+			expect(calls).to.have.length(1);
+		}
+	});
+
+});

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@bacnh85/pi-web",
-  "version": "0.4.1",
+  "version": "0.4.4",
   "description": "Pi extension for web search, page extraction, Firecrawl scraping/crawling, and Crawl4AI headless browser crawling.",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
-  "homepage": "https://github.com/bacnh85/skills#readme",
+  "homepage": "https://github.com/bacnh85/pi-extensions#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/bacnh85/skills.git",
-    "directory": "extensions/pi-web"
+    "url": "git+https://github.com/bacnh85/pi-extensions.git",
+    "directory": "pi-web"
   },
   "keywords": [
     "pi-package",
@@ -24,18 +24,19 @@
     "crawling"
   ],
   "scripts": {
-    "test": "npx mocha",
-    "test:unit": "npx mocha --spec 'test/unit/**/*.test.ts'"
+    "test": "cd extensions && mocha"
   },
   "files": [
     "README.md",
-    "index.ts",
-    "types.d.ts",
-    "lib/"
+    "extensions/",
+    "skills/"
   ],
   "pi": {
     "extensions": [
-      "./index.ts"
+      "./extensions/index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "dependencies": {

package/skills/pi-web/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: pi-web
+description: Web search, content extraction, site crawling, and page capture via the pi-web extension. Use when the user needs current web search results, documentation lookup, factual research, source discovery, URL-to-markdown extraction, JSON extraction from websites, site URL discovery, site crawling, or page screenshots/PDFs. Use when the user mentions searching the web, finding docs, looking something up, researching, scraping/extracting content from a URL, or capturing a page.
+---
+
+# pi-web — Unified Web Tools
+
+Use the **7 unified tools** from the `pi-web` extension for all web-related tasks. These tools automatically select the best backend from SearXNG, Brave Search, Firecrawl, and Crawl4AI — you don't need to know which backend to use. Search selection is adaptive: broad discovery prefers self-hosted SearXNG, while precision-sensitive queries and inline content prefer Brave.
+
+## Quick Reference
+
+| Tool | Purpose | Auto-selection |
+|---|---|---|
+| `web_search` | Search the web for sources, docs, facts | SearXNG → Brave → Firecrawl |
+| `web_extract` | Extract readable content from a URL | Static (JSDOM) → Dynamic (Firecrawl) → Full (Crawl4AI) |
+| `web_map` | Discover URLs from a site | Firecrawl Map (only option) |
+| `web_crawl` | Crawl multiple pages from a site | Light (Firecrawl) or Full (Crawl4AI) |
+| `web_screenshot` | Capture page screenshot as PNG | Crawl4AI (only option) |
+| `web_pdf` | Generate page PDF | Crawl4AI (only option) |
+| `web_status` | Check provider configuration and health | — |
+
+## Decision Tree
+
+```
+What do you need?
+│
+├── Search results (URLs, snippets, docs lookup)
+│   → web_search
+│     ├─ default: adaptive auto-selects SearXNG or Brave, then Firecrawl
+│     ├─ precision/inline content: auto prefers Brave, or explicit backend=brave
+│     └─ SearXNG engine tuning: engines=google,github
+│
+├── Content from a known URL (markdown, structured data)
+│   → web_extract
+│     ├─ static page (blog, docs): mode=static (fastest, no API key)
+│     ├─ dynamic page (JS-rendered): mode=dynamic
+│     ├─ JS-heavy SPA: mode=full
+│     └─ auto (default): tries static > dynamic > full
+│
+├── Site URL discovery (find pages on a site)
+│   → web_map
+│     └─ sitemap=only for sitemap-only discovery
+│
+├── Crawl multiple pages from a site
+│   → web_crawl
+│     ├─ docs/docs section: mode=light (default, Firecrawl)
+│     └─ rendered data with media/links: mode=full (Crawl4AI)
+│
+├── Visual snapshot of a page
+│   → web_screenshot
+│
+├── Printable/archivable PDF of a page
+│   → web_pdf
+│
+└── Check what web tools are configured
+    → web_status
+```
+
+## Auto-selection Details
+
+### `web_search` adaptive backend order
+
+1. **SearXNG** (self-hosted, free) — first for broad/general discovery.
+   - Use `engines` parameter to tune: `engines: "google,github"` for technical queries.
+   - If auto-selection returns poor results, try `backend: "brave"` for a different search index.
+2. **Brave Search** (hosted, requires API key) — first for precision-sensitive queries and inline content.
+   - Auto mode prefers Brave for `include_content`, `site:` searches, quoted phrases, docs/API/source lookups, short proper-name queries, and domain-specific/ambiguous queries.
+   - Supports `include_content` for inline page content.
+   - Handles page-content fetch failures gracefully by keeping search results and adding per-result notes.
+3. **Firecrawl Search** — last resort.
+   - ⚠️ **Poor semantic accuracy** on domain-specific/ambiguous queries. E.g., "Riven" returns League of Legends champion build guide instead of the media-automation tool. Prefer SearXNG or Brave for precision.
+   - Acceptable for general technical queries.
+
+### `web_extract` mode order
+
+1. **static** (JSDOM+Readability) — no API key needed, works on simple static sites, blogs, and doc pages. Fastest option.
+2. **dynamic** (Firecrawl Scrape) — handles JS-rendered pages and dynamic content.
+   - ❌ Fails on bot-protected sites (Ansible docs, many CDN-backed doc sites). Falls through Crawl4AI in `auto` mode.
+   - ✅ Supported: prompt-based JSON extraction, schema-based structured extraction.
+3. **full** (Crawl4AI headless browser) — handles all content types. **Resource-intensive** (launches a full headless browser). Use only when static and dynamic modes fail, or when explicitly needed.
+
+## Fallback Strategy
+
+If one tool fails, try the next option in the chain:
+
+- **Search issues**: `web_search` auto-fallbacks and reports backend diagnostics. If all backends fail, configure at least one via env vars (check `web_status`).
+- **Extraction issues**: `web_extract` auto-fallbacks in `auto` mode. If all modes fail:
+  1. Try `web_screenshot` for a visual snapshot — may work when extraction is blocked.
+  2. The page may require interactive login, CAPTCHA, or be a non-HTML resource.
+- **Tool not found**: Ensure `pi-web` extension is installed (`pi install ./extensions/pi-web`).
+
+## Cross-tool Decision Guide
+
+| If you need... | Use this | Instead of... |
+|---|---|---|
+| A few specific pages from a site | `web_map` + `web_extract` on each URL | `web_crawl` (heavier than needed) |
+| Content from a JS-heavy page that fails in `auto` mode | `web_extract` with `mode: "full"` | Retrying `auto` mode repeatedly |
+| A visual of a bot-protected page | `web_screenshot` | Retrying `web_extract` with all modes |
+| Content alongside search results | `web_search` with `include_content: true` (auto prefers Brave) or `backend: "brave"` | Search snippets alone |
+| Printable/archivable page | `web_pdf` | Taking a screenshot and converting |
+| All URLs on a docs site | `web_map` with `sitemap: "only"` | Crawling the entire site |
+
+## Important Notes
+
+- **Always cite source URLs** when using web content in answers.
+- `web_status` shows which backends are configured without printing secrets. For Firecrawl, `apiKeyFound: false` is normal for self-hosted instances without auth — check the `ready` field to see if Firecrawl is actually usable.
+- The `backend` and `mode` parameters give explicit control when auto-selection is not desired.
+- Backend-specific config (API keys, URLs) comes from environment variables, not tool parameters. Use `web_status` to verify configuration.

package/lib/brave.ts

@@ -1,40 +0,0 @@
-// Brave Search API client.
-
-import { sanitizeSnippet, type SearchResultItem } from "./format";
-import { withRetry } from "./retry";
-
-export interface BraveResult extends SearchResultItem {
-	age: string;
-}
-
-export async function fetchBraveResults(
-	query: string,
-	count: number,
-	country: string,
-	freshness: string,
-	apiKey: string,
-	signal?: AbortSignal,
-): Promise<BraveResult[]> {
-	return withRetry(async () => {
-		const params = new URLSearchParams({ q: query, count: String(count), country });
-		if (freshness) params.append("freshness", freshness);
-		const response = await fetch(`https://api.search.brave.com/res/v1/web/search?${params}`, {
-			headers: {
-				Accept: "application/json",
-				"Accept-Encoding": "gzip",
-				"X-Subscription-Token": apiKey,
-			},
-			signal,
-		});
-		if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}\n${await response.text()}`);
-		const data: any = await response.json();
-		return (data.web?.results || [])
-			.slice(0, count)
-			.map((r: any) => ({
-				title: sanitizeSnippet(r.title || ""),
-				url: r.url || "",
-				snippet: sanitizeSnippet(r.description || ""),
-				age: sanitizeSnippet(r.age || r.page_age || ""),
-			}));
-	}, { maxRetries: 2, retryableErrors: ["timeout", "econn", "etimedout", "network", "socket"] });
-}

package/lib/retry.ts

@@ -1,142 +0,0 @@
-// Retry logic with exponential backoff for transient network failures.
-// Ported from pi-munin/lib/retry.ts.
-
-export interface RetryOptions {
-	maxRetries?: number;
-	initialDelay?: number;
-	maxDelay?: number;
-	multiplier?: number;
-	retryableErrors?: string[];
-	onRetry?: (attempt: number, max: number, delay: number, error: Error) => void;
-}
-
-function isRetryableError(error: Error): boolean {
-	const errorMessage = (error.message || "").toLowerCase();
-	const retryablePatterns = [
-		"econnrefused",
-		"enotfound",
-		"etimedout",
-		"econnreset",
-		"econnaborted",
-		"enetunreach",
-		"etimeout",
-		"timeout",
-		"network",
-		"socket hang up",
-		"socket",
-		"connection",
-		"fetch",
-		"request timeout",
-	];
-	return retryablePatterns.some((pattern) => errorMessage.includes(pattern));
-}
-
-function sleep(ms: number): Promise<void> {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function calculateDelay(
-	attempt: number,
-	initialDelay: number,
-	maxDelay: number,
-	multiplier: number,
-): number {
-	const exponentialDelay = initialDelay * Math.pow(multiplier, attempt);
-	const jitter = Math.random() * 0.1 * exponentialDelay;
-	return Math.min(exponentialDelay + jitter, maxDelay);
-}
-
-/**
- * Retry a function with exponential backoff.
- * Never retries auth, not_found, or validation errors.
- */
-export async function withRetry<T>(
-	fn: () => Promise<T>,
-	options: RetryOptions = {},
-): Promise<T> {
-	const {
-		maxRetries = 3,
-		initialDelay = 1000,
-		maxDelay = 10000,
-		multiplier = 2,
-		retryableErrors = [],
-		onRetry,
-	} = options;
-
-	// Errors we never retry (non-transient)
-	const nonRetryablePatterns = [
-		"unauthorized",
-		"invalid api key",
-		"not found",
-		"validation",
-		"required",
-		"refusing to send",
-		"refusing to send a configured",
-		"must use http or https",
-		"could not extract readable content",
-		"brave_api_key is required",
-		"firecrawl_api_key is required",
-	];
-
-	let lastError: Error;
-
-	for (let attempt = 0; attempt <= maxRetries; attempt++) {
-		try {
-			return await fn();
-		} catch (error) {
-			lastError = error as Error;
-
-			if (attempt === maxRetries) throw error;
-
-			// Never retry non-transient errors
-			const msg = lastError.message.toLowerCase();
-			if (nonRetryablePatterns.some((p) => msg.includes(p))) throw error;
-
-			// Check if error is retryable
-			const shouldRetry =
-				retryableErrors.length > 0
-					? retryableErrors.some((pattern) => msg.includes(pattern.toLowerCase()))
-					: isRetryableError(lastError);
-
-			if (!shouldRetry) throw error;
-
-			const delay = calculateDelay(attempt, initialDelay, maxDelay, multiplier);
-
-			if (onRetry) {
-				onRetry(attempt + 1, maxRetries + 1, delay, lastError);
-			}
-
-			await sleep(delay);
-		}
-	}
-
-	throw lastError!;
-}
-
-/**
- * Combine a timeout signal with an optional external signal.
- */
-export function signalWithTimeout(timeoutMs: number, signal?: AbortSignal): AbortSignal {
-	const timeoutSignal = AbortSignal.timeout(timeoutMs);
-	if (!signal) return timeoutSignal;
-	return AbortSignal.any([signal, timeoutSignal]);
-}
-
-/**
- * Sleep that is abortable via an AbortSignal.
- */
-export function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
-	if (signal?.aborted) return Promise.reject(signal.reason ?? new Error("Operation aborted."));
-	return new Promise((resolve, reject) => {
-		const timer = setTimeout(cleanupResolve, ms);
-		function cleanupResolve() {
-			signal?.removeEventListener("abort", cleanupReject);
-			resolve();
-		}
-		function cleanupReject() {
-			clearTimeout(timer);
-			reject(signal?.reason ?? new Error("Operation aborted."));
-		}
-		signal?.addEventListener("abort", cleanupReject, { once: true });
-	});
-}