pi-web-lite 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smithyyang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# pi-web-lite
+
+Lightweight web access package for Pi. It registers only two tools:
+
+- `web_search` — search with Exa, Tavily, Brave Search, and Doubao Search
+- `fetch` — fetch URL content directly
+
+No curator UI, no browser cookie access, no Gemini/Perplexity, no video analysis, no background servers, no storage cache, and no package runtime dependencies.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    Agent[Pi agent] --> Search[web_search]
+    Agent --> Fetch[fetch]
+    Config[web-search.json] --> Router[Provider/key routing]
+    Search --> Router
+    Router --> Exa[Exa]
+    Router --> Tavily[Tavily]
+    Router --> Brave[Brave]
+    Router --> Doubao[Doubao]
+    Exa --> Normalize[Normalize and format results]
+    Tavily --> Normalize
+    Brave --> Normalize
+    Doubao --> Normalize
+    Normalize --> Agent
+    Fetch --> GitHub[GitHub API for GitHub URLs]
+    Fetch --> HTTP[Direct HTTP fetch]
+    GitHub --> Agent
+    HTTP --> Agent
+```
+
+`balanced` mode shuffles every provider/key pair in one pool. `auto` preserves provider priority while rotating keys inside each provider. Failed targets fall through to the next target in the generated plan.
+
+## Configuration
+
+`pi-web-lite` reads **only** the new format at `~/.pi/web-search.json`:
+
+```json
+{
+  "provider": "balanced",
+  "providers": ["exa", "tavily", "brave", "doubao"],
+  "apiKeys": {
+    "exa": ["exa-key-1"],
+    "tavily": ["tavily-key-1", "tavily-key-2"],
+    "brave": ["brave-key-1", "brave-key-2"],
+    "doubao": ["doubao-key-1"]
+  },
+  "search": {
+    "numResults": 5,
+    "timeoutMs": 20000
+  },
+  "fetch": {
+    "timeoutMs": 20000,
+    "maxChars": 30000
+  }
+}
+```
+
+Legacy fields are intentionally rejected:
+
+- `exaApiKey`, `exaApiKeys`
+- `tavilyApiKey`, `tavilyApiKeys`
+- `braveApiKey`, `braveApiKeys`
+- `doubaoApiKey`, `doubaoApiKeys`
+- `loadBalancing`, `workflow`, `geminiApiKey`, `perplexityApiKey`
+
+## Provider modes
+
+### `balanced`
+
+Flattens every provider+key pair into one pool and shuffles it per search.
+
+Example:
+
+```json
+{
+  "provider": "balanced",
+  "providers": ["exa", "tavily", "brave", "doubao"],
+  "apiKeys": {
+    "exa": ["exa1"],
+    "tavily": ["tvly1", "tvly2"],
+    "brave": ["brave1", "brave2"],
+    "doubao": ["doubao1"]
+  }
+}
+```
+
+Targets:
+
+```text
+exa:exa1
+tavily:tvly1
+tavily:tvly2
+brave:brave1
+brave:brave2
+doubao:doubao1
+```
+
+Each target has equal probability.
+
+### `auto`
+
+Uses `providers` as the priority order. Keys within the same provider are shuffled.
+
+```json
+{
+  "provider": "auto",
+  "providers": ["tavily", "exa", "brave", "doubao"]
+}
+```
+
+This tries all Tavily keys first, then Exa keys, then Brave keys.
+
+### Direct provider
+
+```json
+{ "provider": "brave" }
+```
+
+Only Brave keys are used. No fallback to other providers.
+
+## Tools
+
+### `web_search`
+
+```json
+{
+  "query": "React 19 compiler pitfalls"
+}
+```
+
+or:
+
+```json
+{
+  "queries": [
+    "React 19 compiler performance",
+    "React 19 compiler migration pitfalls"
+  ]
+}
+```
+
+Provider, key, and result count are chosen by config only. The result includes a hashed `keyId` such as `tavily#12ab34cd` so you can verify balancing without leaking API keys.
+
+### `fetch`
+
+```json
+{
+  "url": "https://github.com/GATE"
+}
+```
+
+or:
+
+```json
+{
+  "urls": ["https://example.com", "https://github.com/owner/repo"]
+}
+```
+
+`fetch` is plain fetch: no prompt, no AI analysis.
+
+GitHub URLs use the GitHub API for stable extraction:
+
+- `https://github.com/org` — organization/user repositories
+- `https://github.com/org/repo` — repo metadata + README
+- `https://github.com/org/repo/blob/ref/path` — raw file content
+
+## Install
+
+Install from npm:
+
+```bash
+pi install npm:pi-web-lite
+```
+
+Git and local development alternatives:
+
+```bash
+pi install git:github.com/smithyyang/pi-web-lite
+pi -e ./src/index.ts
+```
+
+Disable/remove the old `pi-web-access` package first if both register `web_search`.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "pi-web-lite",
+  "version": "0.1.1",
+  "description": "Lightweight web_search and fetch tools for Pi with Exa, Tavily, Brave, Doubao, auto priority, and balanced provider-key pools.",
+  "type": "module",
+  "scripts": {
+    "check": "node --input-type=module -e \"await import('./src/config.ts'); await import('./src/search.ts'); await import('./src/fetch.ts'); await import('./src/index.ts')\"",
+    "test": "node --test",
+    "prepublishOnly": "npm run check && npm test"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "extension",
+    "web-search",
+    "fetch",
+    "exa",
+    "tavily",
+    "brave",
+    "doubao"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smithyyang/pi-web-lite.git"
+  },
+  "files": [
+    "src/**/*.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/config.ts

@@ -0,0 +1,160 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const CONFIG_PATH = join(homedir(), ".pi", "web-search.json");
+
+export const PROVIDERS = ["exa", "tavily", "brave", "doubao"] as const;
+export type Provider = typeof PROVIDERS[number];
+export type ProviderMode = Provider | "auto" | "balanced";
+
+export interface SearchDefaults {
+	numResults: number;
+	timeoutMs: number;
+}
+
+export interface FetchDefaults {
+	timeoutMs: number;
+	maxChars: number;
+}
+
+export interface WebLiteConfig {
+	provider: ProviderMode;
+	providers: Provider[];
+	apiKeys: Record<Provider, string[]>;
+	search: SearchDefaults;
+	fetch: FetchDefaults;
+}
+
+const DEFAULT_PROVIDERS: Provider[] = ["exa", "tavily", "brave", "doubao"];
+const DEFAULT_SEARCH: SearchDefaults = { numResults: 5, timeoutMs: 20_000 };
+const DEFAULT_FETCH: FetchDefaults = { timeoutMs: 20_000, maxChars: 30_000 };
+
+const LEGACY_FIELDS = [
+	"exaApiKey",
+	"exaApiKeys",
+	"tavilyApiKey",
+	"tavilyApiKeys",
+	"braveApiKey",
+	"braveApiKeys",
+	"doubaoApiKey",
+	"doubaoApiKeys",
+	"loadBalancing",
+	"workflow",
+	"geminiApiKey",
+	"perplexityApiKey",
+];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function isProvider(value: unknown): value is Provider {
+	return typeof value === "string" && (PROVIDERS as readonly string[]).includes(value);
+}
+
+function normalizeProviderMode(value: unknown): ProviderMode {
+	if (value === undefined) return "auto";
+	if (value === "auto" || value === "balanced" || isProvider(value)) return value;
+	throw new Error(`Invalid provider in ${CONFIG_PATH}: expected auto, balanced, exa, tavily, brave, or doubao.`);
+}
+
+function normalizeProviderList(value: unknown): Provider[] {
+	if (value === undefined) return DEFAULT_PROVIDERS;
+	if (!Array.isArray(value)) {
+		throw new Error(`Invalid providers in ${CONFIG_PATH}: expected an array like ["exa", "tavily", "brave", "doubao"].`);
+	}
+	const providers: Provider[] = [];
+	for (const item of value) {
+		if (!isProvider(item)) {
+			throw new Error(`Invalid provider in providers: ${JSON.stringify(item)}. Expected exa, tavily, brave, or doubao.`);
+		}
+		if (!providers.includes(item)) providers.push(item);
+	}
+	return providers.length > 0 ? providers : DEFAULT_PROVIDERS;
+}
+
+function normalizeKeys(value: unknown, provider: Provider): string[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value)) {
+		throw new Error(`Invalid apiKeys.${provider} in ${CONFIG_PATH}: expected an array of strings.`);
+	}
+	const keys: string[] = [];
+	for (const item of value) {
+		if (typeof item !== "string") {
+			throw new Error(`Invalid apiKeys.${provider} entry in ${CONFIG_PATH}: expected strings only.`);
+		}
+		const key = item.trim();
+		if (key && !keys.includes(key)) keys.push(key);
+	}
+	return keys;
+}
+
+function normalizeNumber(value: unknown, fallback: number, name: string): number {
+	if (value === undefined) return fallback;
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+		throw new Error(`Invalid ${name} in ${CONFIG_PATH}: expected a positive number.`);
+	}
+	return Math.floor(value);
+}
+
+function assertNoLegacyFields(raw: Record<string, unknown>, sourcePath: string): void {
+	const found = LEGACY_FIELDS.filter((field) => field in raw);
+	if (found.length > 0) {
+		throw new Error(
+			`${sourcePath} uses legacy fields (${found.join(", ")}). ` +
+			"pi-web-lite only supports the new format: { provider, providers, apiKeys: { exa: [], tavily: [], brave: [], doubao: [] } }."
+		);
+	}
+}
+
+export function parseConfig(raw: unknown, sourcePath = CONFIG_PATH): WebLiteConfig {
+	if (!isRecord(raw)) {
+		throw new Error(`${sourcePath} must contain a JSON object.`);
+	}
+
+	assertNoLegacyFields(raw, sourcePath);
+
+	const apiKeysRaw = raw.apiKeys;
+	if (!isRecord(apiKeysRaw)) {
+		throw new Error(`Missing apiKeys in ${sourcePath}. Expected { "apiKeys": { "exa": [], "tavily": [], "brave": [], "doubao": [] } }.`);
+	}
+
+	const searchRaw = isRecord(raw.search) ? raw.search : {};
+	const fetchRaw = isRecord(raw.fetch) ? raw.fetch : {};
+
+	return {
+		provider: normalizeProviderMode(raw.provider),
+		providers: normalizeProviderList(raw.providers),
+		apiKeys: {
+			exa: normalizeKeys(apiKeysRaw.exa, "exa"),
+			tavily: normalizeKeys(apiKeysRaw.tavily, "tavily"),
+			brave: normalizeKeys(apiKeysRaw.brave, "brave"),
+			doubao: normalizeKeys(apiKeysRaw.doubao, "doubao"),
+		},
+		search: {
+			numResults: Math.min(normalizeNumber(searchRaw.numResults, DEFAULT_SEARCH.numResults, "search.numResults"), 20),
+			timeoutMs: normalizeNumber(searchRaw.timeoutMs, DEFAULT_SEARCH.timeoutMs, "search.timeoutMs"),
+		},
+		fetch: {
+			timeoutMs: normalizeNumber(fetchRaw.timeoutMs, DEFAULT_FETCH.timeoutMs, "fetch.timeoutMs"),
+			maxChars: normalizeNumber(fetchRaw.maxChars, DEFAULT_FETCH.maxChars, "fetch.maxChars"),
+		},
+	};
+}
+
+export function loadConfig(): WebLiteConfig {
+	if (!existsSync(CONFIG_PATH)) {
+		throw new Error(`Missing config file: ${CONFIG_PATH}`);
+	}
+
+	let raw: unknown;
+	try {
+		raw = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to parse ${CONFIG_PATH}: ${message}`);
+	}
+
+	return parseConfig(raw, CONFIG_PATH);
+}

package/src/fetch.ts

@@ -0,0 +1,191 @@
+import { requestSignal, truncateText } from "./utils.ts";
+
+export interface FetchOptions {
+	timeoutMs: number;
+	maxChars: number;
+	signal?: AbortSignal;
+}
+
+export interface FetchResult {
+	url: string;
+	title: string;
+	content: string;
+	truncated: boolean;
+	originalLength: number;
+}
+
+interface GitHubRepo {
+	name?: string;
+	full_name?: string;
+	description?: string | null;
+	html_url?: string;
+	language?: string | null;
+	stargazers_count?: number;
+	forks_count?: number;
+	updated_at?: string;
+}
+
+interface GitHubUser {
+	login?: string;
+	name?: string | null;
+	bio?: string | null;
+	html_url?: string;
+	public_repos?: number;
+}
+
+function headers(): HeadersInit {
+	const headers: Record<string, string> = {
+		"Accept": "application/vnd.github+json",
+		"User-Agent": "pi-web-lite",
+	};
+	if (process.env.GITHUB_TOKEN) headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+	return headers;
+}
+
+function decodeHtmlEntities(text: string): string {
+	return text
+		.replace(/&nbsp;/g, " ")
+		.replace(/&amp;/g, "&")
+		.replace(/&lt;/g, "<")
+		.replace(/&gt;/g, ">")
+		.replace(/&quot;/g, '"')
+		.replace(/&#39;/g, "'")
+		.replace(/&#x([0-9a-f]+);/gi, (_m, hex) => String.fromCodePoint(Number.parseInt(hex, 16)))
+		.replace(/&#(\d+);/g, (_m, num) => String.fromCodePoint(Number.parseInt(num, 10)));
+}
+
+function htmlToText(html: string): { title: string; text: string } {
+	const title = decodeHtmlEntities(html.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.replace(/\s+/g, " ").trim() || "Untitled");
+	const body = html
+		.replace(/<script\b[\s\S]*?<\/script>/gi, " ")
+		.replace(/<style\b[\s\S]*?<\/style>/gi, " ")
+		.replace(/<svg\b[\s\S]*?<\/svg>/gi, " ")
+		.replace(/<noscript\b[\s\S]*?<\/noscript>/gi, " ")
+		.replace(/<(h[1-6]|p|li|br|div|section|article|pre|blockquote)\b[^>]*>/gi, "\n")
+		.replace(/<[^>]+>/g, " ");
+	const text = decodeHtmlEntities(body)
+		.split("\n")
+		.map((line) => line.replace(/[ \t]+/g, " ").trim())
+		.filter(Boolean)
+		.join("\n");
+	return { title, text };
+}
+
+async function fetchText(url: string, options: FetchOptions, extraHeaders?: HeadersInit): Promise<{ text: string; contentType: string }> {
+	const response = await fetch(url, {
+		headers: extraHeaders,
+		signal: requestSignal(options.timeoutMs, options.signal),
+	});
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new Error(`Fetch error ${response.status} for ${url}: ${errorText.slice(0, 300)}`);
+	}
+	return { text: await response.text(), contentType: response.headers.get("content-type") || "" };
+}
+
+async function githubJson<T>(url: string, options: FetchOptions): Promise<T> {
+	const response = await fetch(url, {
+		headers: headers(),
+		signal: requestSignal(options.timeoutMs, options.signal),
+	});
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new Error(`GitHub API error ${response.status}: ${errorText.slice(0, 300)}`);
+	}
+	return await response.json() as T;
+}
+
+function formatRepo(repo: GitHubRepo): string {
+	const parts = [
+		`### ${repo.full_name || repo.name || "Unknown repo"}`,
+		repo.html_url || "",
+		repo.description || "No description.",
+		`Language: ${repo.language || "unknown"} | Stars: ${repo.stargazers_count ?? 0} | Forks: ${repo.forks_count ?? 0}`,
+	];
+	if (repo.updated_at) parts.push(`Updated: ${repo.updated_at}`);
+	return parts.filter(Boolean).join("\n");
+}
+
+async function fetchGitHubUser(owner: string, sourceUrl: string, options: FetchOptions): Promise<Omit<FetchResult, "truncated" | "originalLength">> {
+	const [user, repos] = await Promise.all([
+		githubJson<GitHubUser>(`https://api.github.com/users/${encodeURIComponent(owner)}`, options),
+		githubJson<GitHubRepo[]>(`https://api.github.com/users/${encodeURIComponent(owner)}/repos?sort=updated&per_page=100`, options),
+	]);
+	const title = user.name || user.login || owner;
+	let content = "";
+	if (user.bio) content += `${user.bio}\n\n`;
+	content += `Public repositories: ${user.public_repos ?? repos.length}\n\n`;
+	content += "## Repositories\n\n";
+	content += repos.map(formatRepo).join("\n\n");
+	return { url: sourceUrl, title, content };
+}
+
+async function fetchGitHubRepo(owner: string, repoName: string, sourceUrl: string, options: FetchOptions): Promise<Omit<FetchResult, "truncated" | "originalLength">> {
+	const repoUrl = `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repoName)}`;
+	const repo = await githubJson<GitHubRepo>(repoUrl, options);
+	let readme = "";
+	try {
+		readme = (await fetchText(
+			`https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repoName)}/readme`,
+			options,
+			{ ...headers(), Accept: "application/vnd.github.raw" },
+		)).text.trim();
+	} catch {
+		readme = "";
+	}
+	const title = repo.full_name || `${owner}/${repoName}`;
+	let content = `${repo.description || "No description."}\n\n`;
+	content += `Language: ${repo.language || "unknown"} | Stars: ${repo.stargazers_count ?? 0} | Forks: ${repo.forks_count ?? 0}\n`;
+	if (repo.updated_at) content += `Updated: ${repo.updated_at}\n`;
+	if (readme) content += `\n## README\n\n${readme}`;
+	return { url: sourceUrl, title, content };
+}
+
+async function fetchGitHubBlob(owner: string, repo: string, parts: string[], sourceUrl: string, options: FetchOptions): Promise<Omit<FetchResult, "truncated" | "originalLength">> {
+	const ref = parts[0];
+	const filePath = parts.slice(1).join("/");
+	if (!ref || !filePath) throw new Error(`Invalid GitHub blob URL: ${sourceUrl}`);
+	const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${filePath}`;
+	const { text } = await fetchText(rawUrl, options, { "User-Agent": "pi-web-lite" });
+	return { url: sourceUrl, title: `${owner}/${repo}/${filePath}`, content: text };
+}
+
+async function fetchGitHub(url: URL, options: FetchOptions): Promise<Omit<FetchResult, "truncated" | "originalLength"> | null> {
+	const host = url.hostname.toLowerCase();
+	if (host === "raw.githubusercontent.com") {
+		const parts = url.pathname.split("/").filter(Boolean);
+		if (parts.length >= 4) {
+			const [owner, repo, ref, ...rest] = parts;
+			return fetchGitHubBlob(owner, repo, [ref, ...rest], url.toString(), options);
+		}
+		return null;
+	}
+	if (host !== "github.com") return null;
+
+	const parts = url.pathname.split("/").filter(Boolean);
+	if (parts.length === 1) return fetchGitHubUser(parts[0], url.toString(), options);
+	if (parts.length >= 5 && parts[2] === "blob") return fetchGitHubBlob(parts[0], parts[1], parts.slice(3), url.toString(), options);
+	if (parts.length >= 2) return fetchGitHubRepo(parts[0], parts[1], url.toString(), options);
+	return null;
+}
+
+async function fetchGeneric(url: string, options: FetchOptions): Promise<Omit<FetchResult, "truncated" | "originalLength">> {
+	const { text, contentType } = await fetchText(url, options, { "User-Agent": "pi-web-lite" });
+	if (contentType.includes("text/html") || /^\s*</.test(text)) {
+		const converted = htmlToText(text);
+		return { url, title: converted.title, content: converted.text.trim() };
+	}
+	return { url, title: url, content: text };
+}
+
+export async function fetchOne(url: string, options: FetchOptions): Promise<FetchResult> {
+	const parsed = new URL(url);
+	const base = await fetchGitHub(parsed, options) ?? await fetchGeneric(url, options);
+	const truncated = truncateText(base.content, options.maxChars);
+	return {
+		...base,
+		content: truncated.text,
+		truncated: truncated.truncated,
+		originalLength: truncated.originalLength,
+	};
+}

package/src/index.ts

@@ -0,0 +1,187 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { loadConfig } from "./config.ts";
+import { fetchOne } from "./fetch.ts";
+import { searchOne, type FailedAttempt, type RoutedSearchResult } from "./search.ts";
+
+function normalizeList(single: unknown, many: unknown): string[] {
+	const raw = Array.isArray(many) ? many : (typeof single === "string" ? [single] : []);
+	const values: string[] = [];
+	for (const item of raw) {
+		if (typeof item !== "string") continue;
+		const value = item.trim();
+		if (value) values.push(value);
+	}
+	return values;
+}
+
+function formatSearchBatch(results: Array<(RoutedSearchResult & { attempts: FailedAttempt[] }) | { query: string; error: string }>): string {
+	return results.map((result) => {
+		if ("error" in result) {
+			return `## Search results for: "${result.query}"\n\nError: ${result.error}`;
+		}
+		return result.markdown;
+	}).join("\n\n---\n\n").trim();
+}
+
+function compactList(items: string[], max = 4): string {
+	if (items.length <= max) return items.join(", ");
+	return `${items.slice(0, max).join(", ")} +${items.length - max} more`;
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "web_search",
+		label: "Web Search Lite",
+		description: "Search the web and return concise results with source links. Use multiple varied queries for broader research coverage.",
+		promptSnippet: "Search the web. Prefer queries with 2-4 distinct angles for research tasks.",
+		parameters: Type.Object({
+			query: Type.Optional(Type.String({ description: "Single search query. Prefer queries for multi-angle research." })),
+			queries: Type.Optional(Type.Array(Type.String(), { description: "Multiple search queries, executed independently." })),
+		}),
+		renderCall(args, theme) {
+			const queries = normalizeList((args as { query?: unknown }).query, (args as { queries?: unknown }).queries);
+			const label = queries.length <= 1 ? (queries[0] || "no query") : `${queries.length} queries`;
+			return new Text(theme.fg("toolTitle", theme.bold("web_search ")) + theme.fg("accent", label), 0, 0);
+		},
+		renderResult(result, { isPartial }, theme) {
+			const details = result.details as {
+				queryCount?: number;
+				successful?: number;
+				providerMode?: string;
+				results?: Array<{ keyId?: string; sources?: unknown[]; error?: string }>;
+			};
+			if (isPartial) return new Text(theme.fg("accent", "searching..."), 0, 0);
+			const totalSources = details?.results?.reduce((sum, item) => sum + (Array.isArray(item.sources) ? item.sources.length : 0), 0) ?? 0;
+			const keys = [...new Set((details?.results ?? []).map((item) => item.keyId).filter((value): value is string => typeof value === "string"))];
+			const errors = (details?.results ?? []).filter((item) => item.error).length;
+			let line = theme.fg("success", `${details?.successful ?? 0}/${details?.queryCount ?? 0} queries, ${totalSources} sources`);
+			line += theme.fg("muted", ` | ${details?.providerMode ?? "auto"}`);
+			if (keys.length > 0) line += theme.fg("muted", ` | ${compactList(keys)}`);
+			if (errors > 0) line += theme.fg("warning", ` | ${errors} errors`);
+			return new Text(line, 0, 0);
+		},
+		async execute(_toolCallId, params, signal, onUpdate) {
+			const queries = normalizeList(params.query, params.queries);
+			if (queries.length === 0) {
+				throw new Error("No query provided. Use query or queries.");
+			}
+
+			const config = loadConfig();
+			const results: Array<(RoutedSearchResult & { attempts: FailedAttempt[] }) | { query: string; error: string }> = [];
+			const numResults = config.search.numResults;
+
+			for (let i = 0; i < queries.length; i++) {
+				const query = queries[i];
+				onUpdate?.({
+					content: [{ type: "text", text: `Searching ${i + 1}/${queries.length}: ${query}` }],
+					details: { phase: "search", current: i + 1, total: queries.length, query },
+				});
+				try {
+					results.push(await searchOne(query, config, { numResults, signal }));
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					results.push({ query, error: message });
+				}
+			}
+
+			const successful = results.filter((result) => !("error" in result)).length;
+			return {
+				content: [{ type: "text", text: formatSearchBatch(results) }],
+				details: {
+					queries,
+					queryCount: queries.length,
+					successful,
+					providerMode: config.provider,
+					providers: config.providers,
+					results: results.map((result) => "error" in result
+						? { query: result.query, error: result.error }
+						: {
+							query: result.query,
+							provider: result.provider,
+							keyId: result.keyId,
+							answer: result.answer,
+							sources: result.results,
+							failedAttempts: result.attempts,
+						}),
+				},
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "fetch",
+		label: "Fetch",
+		description: "Fetch URL content directly and return readable text. Use this when the user asks to inspect a specific link.",
+		promptSnippet: "Fetch the content of a specific URL.",
+		parameters: Type.Object({
+			url: Type.Optional(Type.String({ description: "Single URL to fetch" })),
+			urls: Type.Optional(Type.Array(Type.String(), { description: "Multiple URLs to fetch" })),
+		}),
+		renderCall(args, theme) {
+			const urls = normalizeList((args as { url?: unknown }).url, (args as { urls?: unknown }).urls);
+			const label = urls.length <= 1 ? (urls[0] || "no URL") : `${urls.length} URLs`;
+			return new Text(theme.fg("toolTitle", theme.bold("fetch ")) + theme.fg("accent", label), 0, 0);
+		},
+		renderResult(result, { isPartial }, theme) {
+			const details = result.details as {
+				urlCount?: number;
+				successful?: number;
+				results?: Array<{ title?: string; truncated?: boolean; error?: string }>;
+			};
+			if (isPartial) return new Text(theme.fg("accent", "fetching..."), 0, 0);
+			const titles = (details?.results ?? []).map((item) => item.title).filter((value): value is string => typeof value === "string" && value.length > 0);
+			const truncated = (details?.results ?? []).filter((item) => item.truncated).length;
+			const errors = (details?.results ?? []).filter((item) => item.error).length;
+			let line = theme.fg("success", `${details?.successful ?? 0}/${details?.urlCount ?? 0} URLs`);
+			if (titles.length > 0) line += theme.fg("muted", ` | ${compactList(titles, 2)}`);
+			if (truncated > 0) line += theme.fg("warning", ` | ${truncated} truncated`);
+			if (errors > 0) line += theme.fg("error", ` | ${errors} errors`);
+			return new Text(line, 0, 0);
+		},
+		async execute(_toolCallId, params, signal, onUpdate) {
+			const urls = normalizeList(params.url, params.urls);
+			if (urls.length === 0) {
+				throw new Error("No URL provided. Use url or urls.");
+			}
+
+			const config = loadConfig();
+			const fetched = [];
+			for (let i = 0; i < urls.length; i++) {
+				const url = urls[i];
+				onUpdate?.({
+					content: [{ type: "text", text: `Fetching ${i + 1}/${urls.length}: ${url}` }],
+					details: { phase: "fetch", current: i + 1, total: urls.length, url },
+				});
+				try {
+					fetched.push(await fetchOne(url, { ...config.fetch, signal }));
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					fetched.push({ url, title: url, content: `Error: ${message}`, truncated: false, originalLength: 0, error: message });
+				}
+			}
+
+			const output = fetched.map((result) => {
+				const header = `# ${result.title}\n${result.url}`;
+				return `${header}\n\n${result.content}`;
+			}).join("\n\n---\n\n");
+
+			return {
+				content: [{ type: "text", text: output.trim() }],
+				details: {
+					urls,
+					urlCount: urls.length,
+					successful: fetched.filter((result) => !("error" in result)).length,
+					results: fetched.map((result) => ({
+						url: result.url,
+						title: result.title,
+						truncated: result.truncated,
+						originalLength: result.originalLength,
+						error: "error" in result ? result.error : undefined,
+					})),
+				},
+			};
+		},
+	});
+}

package/src/providers/brave.ts

@@ -0,0 +1,68 @@
+import type { SearchOptions, SearchResponse, SearchResult } from "../utils.ts";
+import { requestSignal } from "../utils.ts";
+
+const BRAVE_LLM_CONTEXT_URL = "https://api.search.brave.com/res/v1/llm/context";
+
+interface BraveContextResponse {
+	grounding?: {
+		generic?: Array<{
+			title?: string;
+			url?: string;
+			snippets?: string[];
+		}>;
+	};
+	sources?: Record<string, {
+		title?: string;
+		hostname?: string;
+		age?: string | string[];
+	}>;
+}
+
+function normalizeSnippet(value: unknown): string | null {
+	if (typeof value !== "string") return null;
+	const snippet = value.trim();
+	return snippet.length > 0 ? snippet : null;
+}
+
+export async function searchBrave(query: string, apiKey: string, options: SearchOptions): Promise<SearchResponse> {
+	const url = new URL(BRAVE_LLM_CONTEXT_URL);
+	url.searchParams.set("q", query);
+	url.searchParams.set("count", String(options.numResults));
+
+	const response = await fetch(url, {
+		headers: {
+			"Accept": "application/json",
+			"Accept-Encoding": "gzip",
+			"X-Subscription-Token": apiKey,
+		},
+		signal: requestSignal(options.timeoutMs, options.signal),
+	});
+
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new Error(`Brave LLM Context API error ${response.status}: ${errorText.slice(0, 500)}`);
+	}
+
+	const data = await response.json() as BraveContextResponse;
+	const results: SearchResult[] = [];
+	const seen = new Set<string>();
+
+	for (const item of data.grounding?.generic ?? []) {
+		if (!item?.url || seen.has(item.url)) continue;
+		const snippets = (item.snippets ?? [])
+			.map(normalizeSnippet)
+			.filter((snippet): snippet is string => !!snippet);
+		if (snippets.length === 0) continue;
+
+		const source = data.sources?.[item.url];
+		results.push({
+			title: item.title || source?.title || source?.hostname || item.url,
+			url: item.url,
+			snippet: snippets.join("\n\n"),
+		});
+		seen.add(item.url);
+		if (results.length >= options.numResults) break;
+	}
+
+	return { answer: "", results };
+}

package/src/providers/doubao.ts

@@ -0,0 +1,95 @@
+import type { SearchOptions, SearchResponse, SearchResult } from "../utils.ts";
+import { cleanText, requestSignal } from "../utils.ts";
+
+const DOUBAO_SEARCH_URL = "https://open.feedcoopapi.com/search_api/web_search";
+
+interface DoubaoResponse {
+	ResponseMetadata?: {
+		RequestId?: string;
+		Error?: {
+			CodeN?: number;
+			Code?: string;
+			Message?: string;
+		};
+	};
+	Result?: {
+		ResultCount?: number;
+		ErrorCode?: number;
+		ErrorMsg?: string;
+		WebResults?: Array<{
+			Title?: string;
+			SiteName?: string;
+			Url?: string;
+			Snippet?: string;
+			Summary?: string;
+			Content?: string;
+			PublishTime?: string;
+		}>;
+	};
+}
+
+function responseError(data: DoubaoResponse): string | null {
+	const metaError = data.ResponseMetadata?.Error;
+	if (metaError) {
+		const code = metaError.Code || String(metaError.CodeN ?? "unknown");
+		return `${code}: ${metaError.Message || "unknown error"}`;
+	}
+	const result = data.Result;
+	if (result && typeof result.ErrorCode === "number" && result.ErrorCode !== 0) {
+		return `${result.ErrorCode}: ${result.ErrorMsg || "unknown error"}`;
+	}
+	return null;
+}
+
+export async function searchDoubao(query: string, apiKey: string, options: SearchOptions): Promise<SearchResponse> {
+	const response = await fetch(DOUBAO_SEARCH_URL, {
+		method: "POST",
+		headers: {
+			"Accept": "application/json",
+			"Authorization": `Bearer ${apiKey}`,
+			"Content-Type": "application/json",
+		},
+		body: JSON.stringify({
+			Query: query,
+			SearchType: "web",
+			Count: options.numResults,
+			Filter: {
+				NeedContent: false,
+				NeedUrl: true,
+			},
+			NeedSummary: false,
+		}),
+		signal: requestSignal(options.timeoutMs, options.signal),
+	});
+
+	const responseText = await response.text();
+	if (!response.ok) {
+		throw new Error(`Doubao Search API error ${response.status}: ${responseText.slice(0, 500)}`);
+	}
+
+	let data: DoubaoResponse;
+	try {
+		data = JSON.parse(responseText) as DoubaoResponse;
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Doubao Search API returned invalid JSON: ${message}`);
+	}
+
+	const error = responseError(data);
+	if (error) throw new Error(`Doubao Search API error ${error}`);
+
+	const results: SearchResult[] = [];
+	const seen = new Set<string>();
+	for (const item of data.Result?.WebResults ?? []) {
+		if (!item?.Url || seen.has(item.Url)) continue;
+		results.push({
+			title: item.Title || item.SiteName || item.Url,
+			url: item.Url,
+			snippet: cleanText(item.Summary || item.Snippet || item.Content, 1200),
+		});
+		seen.add(item.Url);
+		if (results.length >= options.numResults) break;
+	}
+
+	return { answer: "", results };
+}

package/src/providers/exa.ts

@@ -0,0 +1,81 @@
+import type { SearchOptions, SearchResponse, SearchResult } from "../utils.ts";
+import { cleanText, requestSignal } from "../utils.ts";
+
+const EXA_SEARCH_URL = "https://api.exa.ai/search";
+
+interface ExaSearchResponse {
+	results?: Array<{
+		title?: string;
+		url?: string;
+		text?: string;
+		highlights?: unknown;
+	}>;
+}
+
+function normalizeHighlights(value: unknown): string[] {
+	return Array.isArray(value)
+		? value.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
+		: [];
+}
+
+function buildAnswer(results: ExaSearchResponse["results"]): string {
+	if (!Array.isArray(results)) return "";
+	const parts: string[] = [];
+	for (let i = 0; i < results.length; i++) {
+		const item = results[i];
+		if (!item?.url) continue;
+		const highlights = normalizeHighlights(item.highlights);
+		const snippet = highlights.length > 0 ? highlights.join(" ") : cleanText(item.text, 1000);
+		if (!snippet) continue;
+		parts.push(`${snippet}\nSource: ${item.title || `Source ${i + 1}`} (${item.url})`);
+	}
+	return parts.join("\n\n");
+}
+
+function mapResults(results: ExaSearchResponse["results"], numResults: number): SearchResult[] {
+	if (!Array.isArray(results)) return [];
+	const mapped: SearchResult[] = [];
+	for (let i = 0; i < results.length; i++) {
+		const item = results[i];
+		if (!item?.url) continue;
+		const highlights = normalizeHighlights(item.highlights);
+		mapped.push({
+			title: item.title || `Source ${i + 1}`,
+			url: item.url,
+			snippet: highlights.length > 0 ? cleanText(highlights.join(" ")) : cleanText(item.text),
+		});
+		if (mapped.length >= numResults) break;
+	}
+	return mapped;
+}
+
+export async function searchExa(query: string, apiKey: string, options: SearchOptions): Promise<SearchResponse> {
+	const response = await fetch(EXA_SEARCH_URL, {
+		method: "POST",
+		headers: {
+			"x-api-key": apiKey,
+			"Content-Type": "application/json",
+		},
+		body: JSON.stringify({
+			query,
+			type: "auto",
+			numResults: options.numResults,
+			contents: {
+				text: { maxCharacters: 1000 },
+				highlights: true,
+			},
+		}),
+		signal: requestSignal(options.timeoutMs, options.signal),
+	});
+
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new Error(`Exa API error ${response.status}: ${errorText.slice(0, 500)}`);
+	}
+
+	const data = await response.json() as ExaSearchResponse;
+	return {
+		answer: buildAnswer(data.results),
+		results: mapResults(data.results, options.numResults),
+	};
+}

package/src/providers/tavily.ts

@@ -0,0 +1,50 @@
+import type { SearchOptions, SearchResponse, SearchResult } from "../utils.ts";
+import { cleanText, requestSignal } from "../utils.ts";
+
+const TAVILY_API_URL = "https://api.tavily.com/search";
+
+interface TavilyResponse {
+	answer?: string;
+	results?: Array<{
+		title?: string;
+		url?: string;
+		content?: string;
+	}>;
+}
+
+export async function searchTavily(query: string, apiKey: string, options: SearchOptions): Promise<SearchResponse> {
+	const response = await fetch(TAVILY_API_URL, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({
+			api_key: apiKey,
+			query,
+			max_results: options.numResults,
+			search_depth: "basic",
+			include_answer: true,
+		}),
+		signal: requestSignal(options.timeoutMs, options.signal),
+	});
+
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new Error(`Tavily API error ${response.status}: ${errorText.slice(0, 500)}`);
+	}
+
+	const data = await response.json() as TavilyResponse;
+	const results: SearchResult[] = [];
+	for (const item of data.results ?? []) {
+		if (!item?.title || !item?.url) continue;
+		results.push({
+			title: item.title,
+			url: item.url,
+			snippet: cleanText(item.content),
+		});
+		if (results.length >= options.numResults) break;
+	}
+
+	return {
+		answer: typeof data.answer === "string" ? data.answer.trim() : "",
+		results,
+	};
+}

package/src/search.ts

@@ -0,0 +1,102 @@
+import type { Provider, ProviderMode, WebLiteConfig } from "./config.ts";
+import { formatSearchMarkdown, isAbortError, keyId, shuffle, type SearchOptions, type SearchResponse } from "./utils.ts";
+import { searchBrave } from "./providers/brave.ts";
+import { searchDoubao } from "./providers/doubao.ts";
+import { searchExa } from "./providers/exa.ts";
+import { searchTavily } from "./providers/tavily.ts";
+
+export interface SearchTarget {
+	provider: Provider;
+	apiKey: string;
+	keyId: string;
+}
+
+export interface RoutedSearchResult {
+	query: string;
+	provider: Provider;
+	keyId: string;
+	answer: string;
+	results: SearchResponse["results"];
+	markdown: string;
+}
+
+export interface FailedAttempt {
+	provider: Provider;
+	keyId: string;
+	error: string;
+}
+
+function providerTargets(config: WebLiteConfig, provider: Provider): SearchTarget[] {
+	return config.apiKeys[provider].map((apiKey) => ({
+		provider,
+		apiKey,
+		keyId: keyId(provider, apiKey),
+	}));
+}
+
+export function buildSearchPlan(config: WebLiteConfig, mode: ProviderMode = config.provider): SearchTarget[] {
+	if (mode === "balanced") {
+		return shuffle(config.providers.flatMap((provider) => providerTargets(config, provider)));
+	}
+
+	if (mode === "auto") {
+		return config.providers.flatMap((provider) => shuffle(providerTargets(config, provider)));
+	}
+
+	return shuffle(providerTargets(config, mode));
+}
+
+async function searchWithTarget(target: SearchTarget, query: string, options: SearchOptions): Promise<SearchResponse> {
+	if (target.provider === "exa") return searchExa(query, target.apiKey, options);
+	if (target.provider === "tavily") return searchTavily(query, target.apiKey, options);
+	if (target.provider === "brave") return searchBrave(query, target.apiKey, options);
+	return searchDoubao(query, target.apiKey, options);
+}
+
+function errorMessage(err: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}
+
+export async function searchOne(
+	query: string,
+	config: WebLiteConfig,
+	options: Partial<SearchOptions> = {},
+): Promise<RoutedSearchResult & { attempts: FailedAttempt[] }> {
+	const plan = buildSearchPlan(config);
+	if (plan.length === 0) {
+		throw new Error(
+			`No API keys available for provider mode "${config.provider}". ` +
+			`Check ${config.providers.map((p) => `apiKeys.${p}`).join(", ")} in ~/.pi/web-search.json.`
+		);
+	}
+
+	const attempts: FailedAttempt[] = [];
+	const searchOptions: SearchOptions = {
+		numResults: options.numResults ?? config.search.numResults,
+		timeoutMs: options.timeoutMs ?? config.search.timeoutMs,
+		signal: options.signal,
+	};
+
+	for (const target of plan) {
+		try {
+			const response = await searchWithTarget(target, query, searchOptions);
+			return {
+				query,
+				provider: target.provider,
+				keyId: target.keyId,
+				answer: response.answer,
+				results: response.results,
+				markdown: formatSearchMarkdown(query, target.provider, target.keyId, response),
+				attempts,
+			};
+		} catch (err) {
+			if (isAbortError(err)) throw err;
+			attempts.push({ provider: target.provider, keyId: target.keyId, error: errorMessage(err) });
+		}
+	}
+
+	throw new Error(
+		`Search failed for all configured targets:\n` +
+		attempts.map((attempt) => `- ${attempt.provider} ${attempt.keyId}: ${attempt.error}`).join("\n")
+	);
+}

package/src/utils.ts

@@ -0,0 +1,76 @@
+import { createHash } from "node:crypto";
+
+export interface SearchResult {
+	title: string;
+	url: string;
+	snippet: string;
+}
+
+export interface SearchResponse {
+	answer: string;
+	results: SearchResult[];
+}
+
+export interface SearchOptions {
+	numResults: number;
+	timeoutMs: number;
+	signal?: AbortSignal;
+}
+
+export function keyId(provider: string, apiKey: string): string {
+	return `${provider}#${createHash("sha256").update(apiKey).digest("hex").slice(0, 8)}`;
+}
+
+export function shuffle<T>(items: readonly T[]): T[] {
+	const out = items.slice();
+	for (let i = out.length - 1; i > 0; i--) {
+		const j = Math.floor(Math.random() * (i + 1));
+		[out[i], out[j]] = [out[j], out[i]];
+	}
+	return out;
+}
+
+export function requestSignal(timeoutMs: number, signal?: AbortSignal): AbortSignal {
+	const timeout = AbortSignal.timeout(timeoutMs);
+	return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+
+export function cleanText(value: unknown, max = 1000): string {
+	if (typeof value !== "string") return "";
+	return value.replace(/\s+/g, " ").trim().slice(0, max);
+}
+
+export function truncateText(text: string, maxChars: number): { text: string; truncated: boolean; originalLength: number } {
+	if (text.length <= maxChars) return { text, truncated: false, originalLength: text.length };
+	return {
+		text: text.slice(0, maxChars) + `\n\n[Content truncated: showing ${maxChars} of ${text.length} characters.]`,
+		truncated: true,
+		originalLength: text.length,
+	};
+}
+
+export function isAbortError(err: unknown): boolean {
+	const message = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+	return message.toLowerCase().includes("abort");
+}
+
+export function formatSearchMarkdown(query: string, provider: string, id: string, response: SearchResponse): string {
+	let output = `## Search results for: "${query}"\n\n`;
+	output += `Provider: ${provider}\n`;
+	output += `Key: ${id}\n\n`;
+	if (response.answer.trim()) {
+		output += `### Answer\n\n${response.answer.trim()}\n\n`;
+	}
+	output += "### Sources\n\n";
+	if (response.results.length === 0) {
+		output += "No sources returned.\n";
+	} else {
+		for (let i = 0; i < response.results.length; i++) {
+			const result = response.results[i];
+			output += `${i + 1}. ${result.title}\n   ${result.url}`;
+			if (result.snippet) output += `\n   ${result.snippet}`;
+			output += "\n\n";
+		}
+	}
+	return output.trim();
+}