@bacnh85/pi-web 0.3.0 → 0.4.3

package/index.ts

@@ -1,638 +0,0 @@
-/// <reference path="./types.d.ts" />
-
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-
-import {
-	findEnvValue,
-	cwdFromContext,
-	includeProjectEnv,
-	normalizeSearxngBaseUrl,
-	normalizeFirecrawlBaseUrl,
-	normalizeCrawl4aiBaseUrl,
-	loadSearxngConfig,
-	loadFirecrawlConfig,
-	loadCrawl4aiConfig,
-	HOSTED_FIRECRAWL_BASE_URL,
-	DEFAULT_CRAWL4AI_BASE_URL,
-} from "./lib/config";
-import {
-	truncateText,
-	formatSearchResults,
-	formatFirecrawlScrape,
-	formatFirecrawlSearch,
-	formatCrawl4aiResult,
-	formatCrawl4aiStream,
-} from "./lib/format";
-import { fetchReadableContent } from "./lib/content";
-import { fetchBraveResults } from "./lib/brave";
-import { fetchSearxngResults } from "./lib/searxng";
-import { firecrawlRequest, type FirecrawlResult } from "./lib/firecrawl";
-import {
-	fetchCrawl4aiMarkdown,
-	fetchCrawl4aiCrawl,
-	fetchCrawl4aiStream,
-	fetchCrawl4aiScreenshot,
-	fetchCrawl4aiPdf,
-	fetchCrawl4aiHealth,
-} from "./lib/crawl4ai";
-
-// ---------------------------------------------------------------------------
-// Schema fragments shared across tool registrations
-// ---------------------------------------------------------------------------
-
-const controlSchema = {
-	api_key: Type.Optional(Type.String({ description: "Provider API key override. Prefer env vars." })),
-	timeout_ms: Type.Optional(Type.Number({ description: "Request timeout in milliseconds." })),
-};
-
-const firecrawlControlSchema = {
-	firecrawl_api_key: Type.Optional(Type.String({ description: "Firecrawl API key override. Prefer FIRECRAWL_API_KEY." })),
-	firecrawl_api_url: Type.Optional(Type.String({ description: "Firecrawl API URL override. Defaults to FIRECRAWL_API_URL or hosted." })),
-	timeout_ms: Type.Optional(Type.Number({ description: "Request timeout in milliseconds." })),
-};
-
-const searxngControlSchema = {
-	searxng_base_url: Type.Optional(Type.String({ description: "SearXNG base URL override. Defaults to SEARXNG_BASE_URL or http://172.30.55.22:8888." })),
-	timeout_ms: Type.Optional(Type.Number({ description: "Request timeout in milliseconds." })),
-};
-
-const crawl4aiControlSchema = {
-	crawl4ai_base_url: Type.Optional(Type.String({ description: "Crawl4AI base URL override. Defaults to CRAWL4AI_BASE_URL or http://172.30.55.22:11235." })),
-	crawl4ai_api_token: Type.Optional(Type.String({ description: "Crawl4AI API token override. Prefer CRAWL4AI_API_TOKEN." })),
-	timeout_ms: Type.Optional(Type.Number({ description: "Request timeout in milliseconds." })),
-};
-
-// ---------------------------------------------------------------------------
-// Extension entry point
-// ---------------------------------------------------------------------------
-
-export default function piWebExtension(pi: ExtensionAPI) {
-	// ── Brave Search ──────────────────────────────────────────────────────
-	pi.registerTool({
-		name: "brave_search",
-		label: "Brave Search",
-		description:
-			"Search the web with Brave Search API, optionally fetching readable page content. Best as a fast hosted fallback or independent index for source discovery, current facts, docs lookup, and general web search.",
-		promptSnippet: "Search current web results with Brave",
-		promptGuidelines: [
-			"Use SearXNG first for general web search when the self-hosted instance is available; use Brave as a fast hosted fallback or independent second source.",
-			"Use include_content only for a small number of results to avoid rate limits and extra page fetches.",
-			"Cite result URLs when web results materially support the answer; if Brave is rate-limited, try SearXNG or Firecrawl search.",
-		],
-		parameters: Type.Object({
-			...controlSchema,
-			query: Type.String(),
-			count: Type.Optional(Type.Number({ default: 5 })),
-			country: Type.Optional(Type.String({ default: "US" })),
-			freshness: Type.Optional(Type.String()),
-			include_content: Type.Optional(Type.Boolean({ default: false })),
-			content_chars: Type.Optional(Type.Number({ default: 5000 })),
-		}),
-		async execute(_id: string, params: Record<string, unknown>, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
-			const cwd = cwdFromContext(ctx);
-			const apiKey = (params.api_key as string) || findEnvValue("BRAVE_API_KEY", cwd, includeProjectEnv(ctx)).value;
-			if (!apiKey) throw new Error("BRAVE_API_KEY is required.");
-			const count = Math.min(20, Math.max(1, (params.count as number) ?? 5));
-			const results = await fetchBraveResults(
-				params.query as string,
-				count,
-				((params.country as string) || "US").toUpperCase(),
-				(params.freshness as string) || "",
-				apiKey,
-				signal,
-			);
-			if (params.include_content) {
-				await Promise.all(
-					results.map(async (r) => {
-						try {
-							const content = await fetchReadableContent(r.url, (params.timeout_ms as number) || 10000, signal);
-							r.content = content.markdown.slice(0, (params.content_chars as number) ?? 5000);
-						} catch (e: any) {
-							r.content = `(Fetch error for ${r.url}: ${e?.message || String(e)})`;
-						}
-					}),
-				);
-			}
-			return { content: [{ type: "text" as const, text: truncateText(formatSearchResults(results)) }], details: results };
-		},
-	});
-
-	// ── Web Content (readable extraction) ─────────────────────────────────
-	pi.registerTool({
-		name: "web_content",
-		label: "Web Content",
-		description:
-			"Fetch a URL and extract readable markdown content using JSDOM + Readability + Turndown (does not use the Brave API). Best for fast known-URL article/docs extraction.",
-		promptSnippet: "Extract readable webpage content as markdown",
-		promptGuidelines: [
-			"Use for known URLs when simple readable markdown extraction is enough.",
-			"Prefer Firecrawl scrape for dynamic pages, pages that block direct fetching, or when links/structured extraction are needed.",
-			"Cite the source URL when using extracted content in an answer.",
-		],
-		parameters: Type.Object({
-			url: Type.String(),
-			timeout_ms: Type.Optional(Type.Number({ default: 15000 })),
-			content_chars: Type.Optional(Type.Number({ default: 20000 })),
-		}),
-		async execute(_id: string, params: Record<string, unknown>, signal: AbortSignal) {
-			const parsed = new URL(params.url as string);
-			if (!["http:", "https:"].includes(parsed.protocol)) throw new Error("URL must use http or https.");
-			const article = await fetchReadableContent(parsed.href, (params.timeout_ms as number) || 15000, signal);
-			const text = `${article.title ? `# ${article.title}\n\n` : ""}${article.markdown.slice(0, (params.content_chars as number) ?? 20000)}`;
-			return { content: [{ type: "text" as const, text: truncateText(text) }], details: { url: parsed.href, ...article } };
-		},
-	});
-
-	// ── SearXNG Search ───────────────────────────────────────────────────
-	pi.registerTool({
-		name: "searxng_search",
-		label: "SearXNG Search",
-		description:
-			"Search the web through the configured self-hosted SearXNG metasearch instance. Best for free, self-hosted source discovery without hosted API keys.",
-		promptSnippet: "Search web results with self-hosted SearXNG",
-		promptGuidelines: [
-			"Use SearXNG for self-hosted metasearch and source discovery, especially when Brave is unavailable or avoiding hosted search APIs.",
-			"Use SearXNG before browser/scrape tools when the task starts with finding URLs or sources.",
-			"Cite result URLs when SearXNG results materially support the answer.",
-		],
-		parameters: Type.Object({
-			...searxngControlSchema,
-			query: Type.String(),
-			count: Type.Optional(Type.Number({ default: 5 })),
-			pageno: Type.Optional(Type.Number({ default: 1 })),
-			categories: Type.Optional(Type.String({ description: "Comma-separated SearXNG categories, e.g. general,science." })),
-			engines: Type.Optional(Type.String({ description: "Comma-separated SearXNG engines, e.g. brave,wikipedia." })),
-			language: Type.Optional(Type.String()),
-			time_range: Type.Optional(Type.Union([Type.Literal("day"), Type.Literal("month"), Type.Literal("year")])),
-			safesearch: Type.Optional(Type.Number({ description: "SearXNG safesearch level: 0, 1, or 2." })),
-		}),
-		async execute(_id: string, params: Record<string, unknown>, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
-			const config = loadSearxngConfig(params, cwdFromContext(ctx), includeProjectEnv(ctx));
-			const result = await fetchSearxngResults(params, config.baseUrl, signal);
-			return { content: [{ type: "text" as const, text: truncateText(formatSearchResults(result.results || [])) }], details: { ...result, baseUrl: config.baseUrl } };
-		},
-	});
-
-	// ── Firecrawl Search ─────────────────────────────────────────────────
-	pi.registerTool({
-		name: "firecrawl_search",
-		label: "Firecrawl Search",
-		description:
-			"Search web/news/images through Firecrawl, optionally scraping result markdown. Best when SearXNG/Brave are unavailable or when Firecrawl-backed search/scrape is preferred.",
-		promptSnippet: "Search with Firecrawl",
-		promptGuidelines: [
-			"Use when SearXNG and Brave are missing/rate-limited/insufficient, when Firecrawl search is preferred, or when you need scraped markdown from results.",
-			"Keep limits conservative; scraped search is slower and heavier than plain search.",
-			"Cite result URLs and verify scraped content before relying on it.",
-		],
-		parameters: Type.Object({
-			...firecrawlControlSchema,
-			query: Type.String(),
-			limit: Type.Optional(Type.Number({ default: 5 })),
-			sources: Type.Optional(Type.String({ description: "Comma-separated sources: web,news,images", default: "web" })),
-			country: Type.Optional(Type.String()),
-			location: Type.Optional(Type.String()),
-			tbs: Type.Optional(Type.String()),
-			scrape: Type.Optional(Type.Boolean({ default: false })),
-			content_chars: Type.Optional(Type.Number({ default: 5000 })),
-		}),
-		async execute(_id: string, params: Record<string, unknown>, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
-			const config = loadFirecrawlConfig(params, cwdFromContext(ctx), includeProjectEnv(ctx));
-			const sources = String(params.sources || "web")
-				.split(",")
-				.map((type: string) => ({ type: type.trim() }))
-				.filter((s: { type: string }) => s.type);
-			const body: Record<string, unknown> = {
-				query: params.query,
-				limit: Math.min(100, Math.max(1, (params.limit as number) ?? 5)),
-				sources,
-				...(params.country ? { country: String(params.country).toUpperCase() } : {}),
-				...(params.location ? { location: params.location } : {}),
-				...(params.tbs ? { tbs: params.tbs } : {}),
-				...(params.scrape ? { scrapeOptions: { formats: ["markdown"], onlyMainContent: true } } : {}),
-			};
-			const result = await firecrawlRequest(config, "POST", "/search", body, true, signal);
-			return { content: [{ type: "text" as const, text: truncateText(formatFirecrawlSearch((result as FirecrawlResult) as Record<string, unknown>, (params.content_chars as number) ?? 5000)) }], details: result };
-		},
-	});
-
-	// ── Firecrawl Scrape ─────────────────────────────────────────────────
-	pi.registerTool({
-		name: "firecrawl_scrape",
-		label: "Firecrawl Scrape",
-		description:
-			"Scrape a URL through Firecrawl as markdown/html/links/summary/json. Best for dynamic pages, higher-quality extraction, links, or structured JSON extraction.",
-		promptSnippet: "Scrape a URL with Firecrawl",
-		promptGuidelines: [
-			"Use for known URLs when extraction quality matters, pages are dynamic, or markdown/links/JSON extraction is needed.",
-			"Use prompt/schema only for explicit structured extraction tasks.",
-			"Prefer web_content for simple fast known-URL extraction when Firecrawl is unnecessary.",
-		],
-		parameters: Type.Object({
-			...firecrawlControlSchema,
-			url: Type.String(),
-			formats: Type.Optional(Type.String({ default: "markdown" })),
-			prompt: Type.Optional(Type.String()),
-			schema: Type.Optional(Type.Any()),
-			wait_for: Type.Optional(Type.Number()),
-			timeout: Type.Optional(Type.Number()),
-			mobile: Type.Optional(Type.Boolean()),
-			country: Type.Optional(Type.String()),
-			actions: Type.Optional(Type.Any()),
-			only_main_content: Type.Optional(Type.Boolean({ default: true })),
-			content_chars: Type.Optional(Type.Number({ default: 20000 })),
-		}),
-		async execute(_id: string, params: Record<string, unknown>, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
-			const formats = String(params.formats || "markdown")
-				.split(",")
-				.map((f: string) => f.trim())
-				.filter(Boolean)
-				.map((f: string) =>
-					f === "json" && (params.prompt || params.schema)
-						? { type: "json", ...(params.prompt ? { prompt: params.prompt } : {}), ...(params.schema ? { schema: params.schema } : {}) }
-						: f,
-				);
-			const body: Record<string, unknown> = {
-				url: params.url,
-				formats,
-				onlyMainContent: params.only_main_content !== false,
-				...(params.wait_for ? { waitFor: params.wait_for } : {}),
-				...(params.timeout ? { timeout: params.timeout } : {}),
-				...(params.mobile ? { mobile: true } : {}),
-				...(params.country ? { location: { country: String(params.country).toUpperCase() } } : {}),
-				...(params.actions ? { actions: params.actions } : {}),
-			};
-			const result = await firecrawlRequest(loadFirecrawlConfig(params, cwdFromContext(ctx), includeProjectEnv(ctx)), "POST", "/scrape", body, true, signal);
-			return { content: [{ type: "text" as const, text: truncateText(formatFirecrawlScrape((result as FirecrawlResult) as Record<string, unknown>, (params.content_chars as number) ?? 20000)) }], details: result };
-		},
-	});
-
-	// ── Firecrawl Map ────────────────────────────────────────────────────
-	pi.registerTool({
-		name: "firecrawl_map",
-		label: "Firecrawl Map",
-		description:
-			"Discover URLs from a site with Firecrawl map. Best before crawling or when you need candidate pages from a site/docs section.",
-		promptSnippet: "Map site URLs",
-		promptGuidelines: [
-			"Use before crawling to identify relevant URLs and avoid unnecessary broad crawls.",
-			"Keep limits small unless the user explicitly asks for broad site discovery.",
-			"Use mapped URLs with firecrawl_scrape for targeted extraction.",
-		],
-		parameters: Type.Object({
-			...firecrawlControlSchema,
-			url: Type.String(),
-			limit: Type.Optional(Type.Number({ default: 100 })),
-			include_subdomains: Type.Optional(Type.Boolean({ default: false })),
-			search: Type.Optional(Type.String({ description: "Optional search query to guide URL discovery (semantic map)." })),
-			sitemap: Type.Optional(Type.Union([Type.Literal("only"), Type.Literal("include"), Type.Literal("skip")], { description: "Sitemap mode: include (default), only (sitemap-only), or skip." })),
-			use_index: Type.Optional(Type.Boolean({ default: true, description: "Whether to use the Firecrawl search index for URL discovery." })),
-			ignore_cache: Type.Optional(Type.Boolean({ default: false, description: "Ignore cached map results." })),
-		}),
-		async execute(_id: string, params: Record<string, unknown>, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
-			const body: Record<string, unknown> = {
-				url: params.url,
-				limit: (params.limit as number) ?? 100,
-				includeSubdomains: Boolean(params.include_subdomains),
-			};
-			if (params.search !== undefined) body.search = params.search;
-			if (params.sitemap !== undefined) body.sitemap = params.sitemap;
-			if (params.use_index !== undefined) body.useIndex = params.use_index;
-			if (params.ignore_cache !== undefined) body.ignoreCache = params.ignore_cache;
-			const result = await firecrawlRequest(
-				loadFirecrawlConfig(params, cwdFromContext(ctx), includeProjectEnv(ctx)),
-				"POST",
-				"/map",
-				body,
-				true,
-				signal,
-			);
-			const urls = result.data || result.links || result.urls || [];
-			const text = Array.isArray(urls) && urls.length > 0
-				? (urls as Array<Record<string, unknown> | string>).map((u: any) => u.url || u).join("\n")
-				: JSON.stringify(result, null, 2);
-			return { content: [{ type: "text" as const, text: truncateText(text) }], details: result };
-		},
-	});
-
-	// ── Firecrawl Crawl ──────────────────────────────────────────────────
-	pi.registerTool({
-		name: "firecrawl_crawl",
-		label: "Firecrawl Crawl",
-		description:
-			"Start a conservative Firecrawl site crawl and optionally poll for results. Best for small docs/site sections after mapping or when multiple pages are required.",
-		promptSnippet: "Crawl a small site section",
-		promptGuidelines: [
-			"Use only when multiple pages from a site are needed; prefer firecrawl_map plus targeted scrape when possible.",
-			"Keep limits conservative and use include/exclude paths to narrow scope.",
-			"Avoid large crawls unless the user explicitly requests them and accepts runtime/load.",
-		],
-		parameters: Type.Object({
-			...firecrawlControlSchema,
-			url: Type.String(),
-			limit: Type.Optional(Type.Number({ default: 10 })),
-			include_paths: Type.Optional(Type.String()),
-			exclude_paths: Type.Optional(Type.String()),
-			poll: Type.Optional(Type.Boolean({ default: false })),
-		}),
-		async execute(_id: string, params: Record<string, unknown>, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
-			const config = loadFirecrawlConfig(params, cwdFromContext(ctx), includeProjectEnv(ctx));
-			let result = await firecrawlRequest(
-				config,
-				"POST",
-				"/crawl",
-				{
-					url: params.url,
-					limit: Math.min(10000, Math.max(1, (params.limit as number) ?? 10)),
-					includePaths: params.include_paths
-						? String(params.include_paths)
-								.split(",")
-								.map((s: string) => s.trim())
-								.filter(Boolean)
-						: [],
-					excludePaths: params.exclude_paths
-						? String(params.exclude_paths)
-								.split(",")
-								.map((s: string) => s.trim())
-								.filter(Boolean)
-						: [],
-					scrapeOptions: { formats: ["markdown"], onlyMainContent: true },
-				},
-				true,
-				signal,
-			);
-			const id = result.id || (result.data as Record<string, unknown> | undefined)?.id;
-			if (params.poll && id && !Array.isArray(result.data)) {
-				const { abortableSleep } = await import("./lib/retry");
-				for (let i = 0; i < 60; i++) {
-					result = await firecrawlRequest(config, "GET", `/crawl/${id}`, undefined, true, signal);
-					if (["completed", "failed", "cancelled"].includes(String(result.status || (result.data as Record<string, unknown> | undefined)?.status || ""))) break;
-					await abortableSleep(2000, signal);
-				}
-			}
-			const pages = Array.isArray(result.data)
-				? (result.data as Record<string, unknown>[])
-				: ((result.data as Record<string, unknown>)?.data as Record<string, unknown>[]) || [];
-			const text = pages.length
-				? pages
-						.map((p: Record<string, unknown>) => formatFirecrawlScrape({ data: p } as Record<string, unknown>, 12000))
-						.join("\n\n---\n\n")
-				: id
-					? `Crawl started: ${id}\nUse poll=true or check Firecrawl status/dashboard.`
-					: JSON.stringify(result, null, 2);
-			return { content: [{ type: "text" as const, text: truncateText(text) }], details: result };
-		},
-	});
-
-	// ── Crawl4AI Scrape ──────────────────────────────────────────────────
-	pi.registerTool({
-		name: "crawl4ai_scrape",
-		label: "Crawl4AI Scrape",
-		description:
-			"Extract clean LLM-ready markdown from a URL using Crawl4AI's headless browser engine, with optional content filtering (fit, raw, bm25, llm). Best for JavaScript-rendered pages and when you need high-quality markdown for AI consumption.",
-		promptSnippet: "Scrape with Crawl4AI",
-		promptGuidelines: [
-			"Prefer crawl4ai_scrape over web_content for dynamic/JS-rendered pages.",
-			"Use filter=raw for full DOM-to-markdown, filter=fit (default) for Readability-based clean content.",
-			"Use filter=bm25 with a query for relevance-ranked content extraction.",
-		],
-		parameters: Type.Object({
-			...crawl4aiControlSchema,
-			url: Type.String(),
-			filter: Type.Optional(Type.Union([Type.Literal("fit"), Type.Literal("raw"), Type.Literal("bm25"), Type.Literal("llm")], { default: "fit", description: "Content-filter strategy: fit (default), raw, bm25, or llm." })),
-			query: Type.Optional(Type.String({ description: "Query string used by BM25 or LLM filters." })),
-			content_chars: Type.Optional(Type.Number({ default: 20000 })),
-		}),
-		async execute(_id: string, params: Record<string, unknown>, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
-			const config = loadCrawl4aiConfig(params, cwdFromContext(ctx), includeProjectEnv(ctx));
-			const filter = (params.filter as string) || "fit";
-			const query = params.query as string | undefined;
-			const result = await fetchCrawl4aiMarkdown(config, params.url as string, filter, query, signal);
-			const text = `# Crawl4AI Markdown (filter: ${filter})\nURL: ${params.url}\n\n${result.markdown.slice(0, (params.content_chars as number) ?? 20000)}`;
-			return { content: [{ type: "text" as const, text: truncateText(text) }], details: result };
-		},
-	});
-
-	// ── Crawl4AI Crawl ──────────────────────────────────────────────────
-	pi.registerTool({
-		name: "crawl4ai_crawl",
-		label: "Crawl4AI Crawl",
-		description:
-			"Crawl one or more URLs with Crawl4AI's headless browser, returning full crawl data including markdown, HTML, links, and media. Supports up to 100 URLs per request.",
-		promptSnippet: "Crawl with Crawl4AI",
-		promptGuidelines: [
-			"Use crawl4ai_crawl when you need full crawl data (HTML, links, media) from multiple URLs.",
-			"For single-URL markdown-only extraction, prefer crawl4ai_scrape.",
-			"Keep to 10 or fewer URLs per request for reasonable response times.",
-		],
-		parameters: Type.Object({
-			...crawl4aiControlSchema,
-			urls: Type.Array(Type.String(), { minItems: 1, maxItems: 100, description: "URLs to crawl (1-100)." }),
-			browser_config: Type.Optional(Type.Any({ description: "Optional BrowserConfig JSON object." })),
-			crawler_config: Type.Optional(Type.Any({ description: "Optional CrawlerRunConfig JSON object." })),
-			content_chars: Type.Optional(Type.Number({ default: 20000 })),
-		}),
-		async execute(_id: string, params: Record<string, unknown>, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
-			const config = loadCrawl4aiConfig(params, cwdFromContext(ctx), includeProjectEnv(ctx));
-			const urls = params.urls as string[];
-			const browserConfig = params.browser_config as Record<string, unknown> | undefined;
-			const crawlerConfig = params.crawler_config as Record<string, unknown> | undefined;
-			const result = await fetchCrawl4aiCrawl(config, urls, browserConfig, crawlerConfig, signal);
-			const text = formatCrawl4aiResult(result as unknown as Record<string, unknown>, (params.content_chars as number) ?? 20000);
-			return { content: [{ type: "text" as const, text: truncateText(text) }], details: result };
-		},
-	});
-
-	// ── Crawl4AI Stream ─────────────────────────────────────────────────
-	pi.registerTool({
-		name: "crawl4ai_stream",
-		label: "Crawl4AI Stream",
-		description:
-			"Crawl one or more URLs with Crawl4AI using streaming response (SSE-style JSON lines). Results arrive as each URL is processed, useful for long-running multi-URL crawls.",
-		promptSnippet: "Stream crawl with Crawl4AI",
-		promptGuidelines: [
-			"Use crawl4ai_stream for large batch crawls where you want results incrementally.",
-			"The response is newline-delimited JSON; each line is a complete CrawlResult.",
-			"The stream ends with a line containing {\"status\": \"completed\"}.",
-		],
-		parameters: Type.Object({
-			...crawl4aiControlSchema,
-			urls: Type.Array(Type.String(), { minItems: 1, maxItems: 100, description: "URLs to crawl (1-100)." }),
-			browser_config: Type.Optional(Type.Any({ description: "Optional BrowserConfig JSON object." })),
-			crawler_config: Type.Optional(Type.Any({ description: "Optional CrawlerRunConfig JSON object." })),
-		}),
-		async execute(_id: string, params: Record<string, unknown>, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
-			const config = loadCrawl4aiConfig(params, cwdFromContext(ctx), includeProjectEnv(ctx));
-			const urls = params.urls as string[];
-			const browserConfig = params.browser_config as Record<string, unknown> | undefined;
-			const crawlerConfig = params.crawler_config as Record<string, unknown> | undefined;
-			const raw = await fetchCrawl4aiStream(config, urls, browserConfig, crawlerConfig, signal);
-			const text = formatCrawl4aiStream(raw);
-			return { content: [{ type: "text" as const, text: truncateText(text) }], details: { raw_length: raw.length } };
-		},
-	});
-
-	// ── Crawl4AI Screenshot ─────────────────────────────────────────────
-	pi.registerTool({
-		name: "crawl4ai_screenshot",
-		label: "Crawl4AI Screenshot",
-		description:
-			"Capture a full-page PNG screenshot of a URL using Crawl4AI's headless browser. Returns a base64-encoded screenshot image.",
-		promptSnippet: "Screenshot with Crawl4AI",
-		promptGuidelines: [
-			"Use crawl4ai_screenshot when you need a visual snapshot of a rendered page.",
-			"The screenshot is returned as a base64-encoded PNG string.",
-			"Use the wait_for parameter to delay capture for dynamic content to render.",
-		],
-		parameters: Type.Object({
-			...crawl4aiControlSchema,
-			url: Type.String(),
-			wait_for: Type.Optional(Type.Number({ default: 2, description: "Seconds to wait before capturing screenshot." })),
-			wait_for_images: Type.Optional(Type.Boolean({ default: false, description: "Wait for images to load before capture." })),
-		}),
-		async execute(_id: string, params: Record<string, unknown>, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
-			const config = loadCrawl4aiConfig(params, cwdFromContext(ctx), includeProjectEnv(ctx));
-			const result = await fetchCrawl4aiScreenshot(config, params.url as string, params.wait_for as number | undefined, params.wait_for_images as boolean | undefined, signal);
-			const screenshot = result.screenshot as string | undefined;
-			const artifactUrl = result.url as string | undefined;
-			const mime = result.mime as string | undefined;
-			const size = result.size as number | undefined;
-			let text = `Screenshot: ${params.url}\n`;
-			if (screenshot) text += `Data: base64 PNG (${screenshot.length} chars)\n`;
-			if (artifactUrl) text += `Artifact: ${artifactUrl}\n`;
-			if (mime) text += `MIME: ${mime}\n`;
-			if (size) text += `Size: ${size} bytes\n`;
-			return { content: [{ type: "text" as const, text: truncateText(text) }], details: { ...result, url: params.url } };
-		},
-	});
-
-	// ── Crawl4AI PDF ────────────────────────────────────────────────────
-	pi.registerTool({
-		name: "crawl4ai_pdf",
-		label: "Crawl4AI PDF",
-		description:
-			"Generate a PDF document of a URL using Crawl4AI's headless browser. Returns a base64-encoded PDF suitable for saving or further processing.",
-		promptSnippet: "PDF with Crawl4AI",
-		promptGuidelines: [
-			"Use crawl4ai_pdf when you need a printable or archivable snapshot of a page.",
-			"The PDF is returned as a base64-encoded string.",
-		],
-		parameters: Type.Object({
-			...crawl4aiControlSchema,
-			url: Type.String(),
-		}),
-		async execute(_id: string, params: Record<string, unknown>, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
-			const config = loadCrawl4aiConfig(params, cwdFromContext(ctx), includeProjectEnv(ctx));
-			const result = await fetchCrawl4aiPdf(config, params.url as string, signal);
-			const pdf = result.pdf as string | undefined;
-			const artifactUrl = result.url as string | undefined;
-			const size = result.size as number | undefined;
-			let text = `PDF: ${params.url}\n`;
-			if (pdf) text += `Data: base64 PDF (${pdf.length} chars)\n`;
-			if (artifactUrl) text += `Artifact: ${artifactUrl}\n`;
-			if (size) text += `Size: ${size} bytes\n`;
-			return { content: [{ type: "text" as const, text: truncateText(text) }], details: { ...result, url: params.url } };
-		},
-	});
-
-	// ── Web Status ───────────────────────────────────────────────────────
-	pi.registerTool({
-		name: "web_status",
-		label: "Web Provider Status",
-		description:
-			"Show Brave, SearXNG, Firecrawl, and Crawl4AI configuration status without printing secrets.",
-		promptSnippet: "Check web provider configuration",
-		promptGuidelines: [
-			"Use when web tools fail due to missing credentials/config or before comparing Brave, SearXNG, Firecrawl, and Crawl4AI availability.",
-			"Never print API key values; this tool reports only presence and source.",
-		],
-		parameters: Type.Object({}),
-		async execute(_id: string, _params: Record<string, unknown>, _signal: AbortSignal, _onUpdate: unknown, ctx: any) {
-			const cwd = cwdFromContext(ctx);
-			const trusted = includeProjectEnv(ctx);
-			const braveKey = findEnvValue("BRAVE_API_KEY", cwd, trusted);
-			const searxngUrl = findEnvValue("SEARXNG_BASE_URL", cwd, trusted);
-			const fireKey = findEnvValue("FIRECRAWL_API_KEY", cwd, trusted);
-			const fireUrl = findEnvValue("FIRECRAWL_API_URL", cwd, trusted);
-			const c4aiUrl = findEnvValue("CRAWL4AI_BASE_URL", cwd, trusted);
-			const c4aiToken = findEnvValue("CRAWL4AI_API_TOKEN", cwd, trusted);
-			const status = {
-				brave: { apiKeyFound: Boolean(braveKey.value), apiKeySource: braveKey.value ? braveKey.source : "not set" },
-				searxng: {
-					baseUrl: normalizeSearxngBaseUrl(searxngUrl.value),
-					baseUrlSource: searxngUrl.source || "default local",
-				},
-				firecrawl: {
-					baseUrl: normalizeFirecrawlBaseUrl(fireUrl.value),
-					apiUrlSource: fireUrl.source || "default hosted",
-					apiKeyFound: Boolean(fireKey.value),
-					apiKeySource: fireKey.value ? fireKey.source : "not set",
-					hostedMode: !fireUrl.value || normalizeFirecrawlBaseUrl(fireUrl.value).startsWith(HOSTED_FIRECRAWL_BASE_URL),
-				},
-				crawl4ai: {
-					baseUrl: normalizeCrawl4aiBaseUrl(c4aiUrl.value),
-					baseUrlSource: c4aiUrl.source || "default",
-					apiTokenFound: Boolean(c4aiToken.value),
-					apiTokenSource: c4aiToken.value ? c4aiToken.source : "not set",
-				},
-			};
-			return { content: [{ type: "text" as const, text: JSON.stringify(status, null, 2) }], details: status };
-		},
-	});
-
-	// ── Crawl4AI Status ─────────────────────────────────────────────────
-	pi.registerTool({
-		name: "crawl4ai_status",
-		label: "Crawl4AI Server Status",
-		description:
-			"Check Crawl4AI server health and version. Connects to the configured Crawl4AI endpoint to verify availability.",
-		promptSnippet: "Check Crawl4AI server status",
-		promptGuidelines: [
-			"Use crawl4ai_status when Crawl4AI tools return connection errors.",
-			"Shows server version, response timestamp, and whether auth is configured.",
-		],
-		parameters: Type.Object({
-			...crawl4aiControlSchema,
-		}),
-		async execute(_id: string, params: Record<string, unknown>, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
-			const config = loadCrawl4aiConfig(params, cwdFromContext(ctx), includeProjectEnv(ctx));
-			const health = await fetchCrawl4aiHealth(config, signal);
-			const text = [
-				`Crawl4AI Server Status`,
-				`Endpoint: ${config.baseUrl}`,
-				`Status: ${health.status || "unknown"}`,
-				`Version: ${health.version || "unknown"}`,
-				`Timestamp: ${health.timestamp ? new Date(health.timestamp * 1000).toISOString() : "unknown"}`,
-				`Auth token: ${config.apiToken ? "configured" : "not set (loopback only)"}`,
-			].join("\n");
-			return { content: [{ type: "text" as const, text: text }], details: { config: { baseUrl: config.baseUrl, apiTokenConfigured: Boolean(config.apiToken) }, health } };
-		},
-	});
-
-	// ── /web-status command ──────────────────────────────────────────────
-	pi.registerCommand("web-status", {
-		description: "Show web provider configuration status",
-		handler: async (_args: string, ctx: any) => {
-			const cwd = cwdFromContext(ctx);
-			const trusted = includeProjectEnv(ctx);
-			const braveKey = findEnvValue("BRAVE_API_KEY", cwd, trusted);
-			const searxngUrl = findEnvValue("SEARXNG_BASE_URL", cwd, trusted);
-			const fireKey = findEnvValue("FIRECRAWL_API_KEY", cwd, trusted);
-			const fireUrl = findEnvValue("FIRECRAWL_API_URL", cwd, trusted);
-			const c4aiUrl = findEnvValue("CRAWL4AI_BASE_URL", cwd, trusted);
-			const c4aiToken = findEnvValue("CRAWL4AI_API_TOKEN", cwd, trusted);
-			ctx.ui.notify(
-				[
-					`Brave API key: ${braveKey.value ? `found (${braveKey.source})` : "not set"}`,
-					`SearXNG base URL: ${normalizeSearxngBaseUrl(searxngUrl.value)} (${searxngUrl.source || "default local"})`,
-					`Firecrawl base URL: ${normalizeFirecrawlBaseUrl(fireUrl.value)}`,
-					`Firecrawl API key: ${fireKey.value ? `found (${fireKey.source})` : "not set"}`,
-					`Crawl4AI base URL: ${normalizeCrawl4aiBaseUrl(c4aiUrl.value)} (${c4aiUrl.source || "default"})`,
-					`Crawl4AI API token: ${c4aiToken.value ? `found (${c4aiToken.source})` : "not set"}`,
-				].join("\n"),
-				"info",
-			);
-		},
-	});
-}