@wolido/pi-anysearch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 liuyu
+
+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,65 @@
+# @wolido/pi-anysearch
+
+AnySearch AI search extension for [pi](https://github.com/earendil-works/pi-coding-agent). It wraps the [AnySearch](https://anysearch.ai) vertical search API — 40 curated capability domains (finance, academic, legal, security, health, travel, ...) — as four LLM tools, with authentication, MCP session handling and output truncation taken care of.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `anysearch_search` | Vertical web search. Optional capability `tag` (e.g. `finance.quote`, `academic.search`, `code.doc`, `security.vuln`), `zone` (`cn`/`intl`), `language`, tag-specific `params`, `format` and `max_results` (1–20). |
+| `anysearch_batch_search` | Run several queries in parallel with shared options; returns one aggregated result set. |
+| `anysearch_extract` | Fetch a URL and return its readable content as markdown (via AnySearch's MCP `extract` tool). |
+| `anysearch_domains` | List the curated sub-domains under a top-level capability domain (via MCP `get_sub_domains`); useful for discovering valid tags. |
+
+Search and batch results include titles, URLs, snippets, extracted content and `total_results` / `search_time_ms` metadata. Oversized outputs are truncated to pi's tool output limits, byte-safely for multi-byte text.
+
+## Installation
+
+```bash
+pi install npm:@wolido/pi-anysearch
+```
+
+For local development, load the extension directly from the repo:
+
+```bash
+pi -e /path/to/pi-anysearch/src/index.ts
+```
+
+## Configuration
+
+The API key is resolved on first tool execution, with the following precedence (first hit wins):
+
+1. **Environment variable** — `ANYSEARCH_API_KEY`
+   ```bash
+   export ANYSEARCH_API_KEY="sk-..."
+   ```
+2. **Project config** — `<project>/.pi/pi-anysearch/config.json`
+   ```json
+   { "apiKey": "sk-..." }
+   ```
+   Read **only when the project is trusted** by pi; config files from untrusted projects are ignored so a malicious repository cannot inject an API key.
+   
+   > ⚠️ This file contains a plaintext key — add `.pi/pi-anysearch/config.json` to your project's `.gitignore`.
+3. **Global config** — `~/.pi/agent/pi-anysearch/config.json` (same JSON format)
+4. **Anonymous mode** — no key found: requests are sent without an `Authorization` header and are rate-limited by the AnySearch service.
+
+Get a key at [anysearch.ai](https://anysearch.ai).
+
+## Development
+
+```bash
+npm install
+npm test           # vitest, 36 tests
+npm run typecheck  # tsc --noEmit
+```
+
+Layout:
+
+- `src/anysearch.ts` — AnySearch client: `POST /v1/search` envelope API plus a stateful MCP Streamable HTTP session (`initialize` → `notifications/initialized` → `tools/call`) for extract/domains.
+- `src/config.ts` — API key resolution (env → trusted project config → global config → anonymous).
+- `src/index.ts` — pi extension factory registering the four tools (TypeBox schemas via `StringEnum` for provider compatibility); clients are created lazily and cached per cwd + trust state.
+- `tests/` — vitest suite with a mock fetch/MCP harness (`tests/helpers/`).
+
+## License
+
+MIT © 2026 liuyu

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@wolido/pi-anysearch",
+  "version": "0.1.0",
+  "description": "AnySearch AI search API extension for pi",
+  "type": "module",
+  "main": "./src/index.ts",
+  "license": "MIT",
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wolido/pi-anysearch"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "anysearch",
+    "search"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "file:/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-ai",
+    "@earendil-works/pi-coding-agent": "file:/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent",
+    "@types/node": "^20.0.0",
+    "typebox": "file:/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/node_modules/typebox",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/anysearch.ts

@@ -0,0 +1,251 @@
+/**
+ * AnySearch API client.
+ *
+ * Two transports:
+ * - POST {baseUrl}/v1/search  — HTTP search API with a {code, message, data} envelope
+ * - POST {baseUrl}/mcp        — MCP Streamable HTTP endpoint (JSON-RPC 2.0 tools/call)
+ *   used for the `extract` and `get_sub_domains` tools
+ */
+
+export interface SearchParams {
+	query: string;
+	max_results?: number;
+	tag?: string;
+	zone?: "cn" | "intl";
+	language?: string;
+	params?: Record<string, unknown>;
+	format?: "json" | "markdown";
+}
+
+export interface BatchSearchParams extends Omit<SearchParams, "query"> {
+	queries: string[];
+}
+
+export interface SearchResultItem {
+	title: string;
+	url: string;
+	snippet: string;
+	content: string;
+}
+
+export interface SearchMetadata {
+	total_results: number;
+	search_time_ms: number;
+}
+
+export interface SearchResult {
+	results: SearchResultItem[];
+	metadata: SearchMetadata;
+	request_id?: string;
+}
+
+export interface AnySearchClientOptions {
+	/** API key for authenticated access; omitted for anonymous (rate-limited) mode. */
+	apiKey?: string;
+	baseUrl?: string;
+	fetch?: typeof fetch;
+}
+
+export interface AnySearchClient {
+	search(params: SearchParams): Promise<SearchResult>;
+	batchSearch(params: BatchSearchParams): Promise<SearchResult[]>;
+	extract(url: string): Promise<string>;
+	getDomains(domain: string): Promise<string>;
+}
+
+const DEFAULT_BASE_URL = "https://api.anysearch.com";
+
+interface SearchEnvelope {
+	code: number;
+	message?: string;
+	request_id?: string;
+	data?: { results?: SearchResultItem[]; metadata?: SearchMetadata };
+}
+
+interface JsonRpcResponse {
+	jsonrpc: "2.0";
+	id: number | string | null;
+	result?: { content?: Array<{ type: string; text?: string }>; isError?: boolean };
+	error?: { code: number; message: string };
+}
+
+export function createAnySearchClient(options: AnySearchClientOptions = {}): AnySearchClient {
+	const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+	// Resolve global fetch lazily so tests embedding a stubbed global still work.
+	const fetchImpl: typeof fetch = options.fetch ?? ((input, init) => fetch(input, init));
+	let rpcId = 0;
+
+	function buildHeaders(extra?: Record<string, string>): Record<string, string> {
+		const headers: Record<string, string> = { "content-type": "application/json", ...extra };
+		if (options.apiKey) {
+			headers.authorization = `Bearer ${options.apiKey}`;
+		}
+		return headers;
+	}
+
+	async function readErrorMessage(res: Response): Promise<string> {
+		try {
+			const body = (await res.json()) as { message?: string; error?: string };
+			if (body && typeof body.message === "string" && body.message) {
+				return body.message;
+			}
+			if (body && typeof body.error === "string" && body.error) {
+				return body.error;
+			}
+		} catch {
+			// Non-JSON error body; fall through to status text.
+		}
+		return `HTTP ${res.status}`;
+	}
+
+	/** Build an actionable message for HTTP error responses (429 gets special treatment). */
+	async function httpErrorMessage(res: Response): Promise<string> {
+		if (res.status !== 429) {
+			return readErrorMessage(res);
+		}
+		const detail = await readErrorMessage(res);
+		const base = detail.startsWith("HTTP ") ? "rate limit exceeded, slow down or retry later" : detail;
+		const retryAfter = res.headers.get("retry-after");
+		return retryAfter ? `${base}; retry after ${retryAfter}s` : base;
+	}
+
+	async function search(params: SearchParams): Promise<SearchResult> {
+		const res = await fetchImpl(`${baseUrl}/v1/search`, {
+			method: "POST",
+			headers: buildHeaders(),
+			body: JSON.stringify(params),
+		});
+		if (!res.ok) {
+			throw new Error(`AnySearch search failed: ${await httpErrorMessage(res)}`);
+		}
+		const envelope = (await res.json()) as SearchEnvelope;
+		if (envelope.code !== 0) {
+			throw new Error(`AnySearch search failed: ${envelope.message ?? `error code ${envelope.code}`}`);
+		}
+		return {
+			results: envelope.data?.results ?? [],
+			metadata: envelope.data?.metadata ?? { total_results: 0, search_time_ms: 0 },
+			request_id: envelope.request_id,
+		};
+	}
+
+	/** Parse a JSON-RPC response that may be plain JSON or SSE-framed (`data:` lines). */
+	async function readJsonRpc(res: Response): Promise<JsonRpcResponse> {
+		const text = await res.text();
+		try {
+			return JSON.parse(text) as JsonRpcResponse;
+		} catch {
+			const dataLines = text
+				.split("\n")
+				.filter((line) => line.startsWith("data:"))
+				.map((line) => line.slice(5).trim());
+			const last = dataLines[dataLines.length - 1];
+			if (!last) {
+				throw new Error("AnySearch MCP returned an unparseable response");
+			}
+			return JSON.parse(last) as JsonRpcResponse;
+		}
+	}
+
+	function mcpHeaders(sessionId?: string): Record<string, string> {
+		// Streamable HTTP requires both media types in Accept.
+		const headers = buildHeaders({ accept: "application/json, text/event-stream" });
+		if (sessionId) {
+			headers["Mcp-Session-Id"] = sessionId;
+		}
+		return headers;
+	}
+
+	/** Perform the MCP handshake: initialize -> notifications/initialized. Returns the session id, if any. */
+	async function performHandshake(): Promise<string | undefined> {
+		const initRes = await fetchImpl(`${baseUrl}/mcp`, {
+			method: "POST",
+			headers: mcpHeaders(),
+			body: JSON.stringify({
+				jsonrpc: "2.0",
+				id: ++rpcId,
+				method: "initialize",
+				params: {
+					protocolVersion: "2025-03-26",
+					capabilities: {},
+					clientInfo: { name: "pi-anysearch", version: "0.1.0" },
+				},
+			}),
+		});
+		if (!initRes.ok) {
+			throw new Error(`AnySearch MCP initialize failed: ${await httpErrorMessage(initRes)}`);
+		}
+		const sessionId = initRes.headers.get("Mcp-Session-Id") ?? undefined;
+		const initMessage = await readJsonRpc(initRes);
+		if (initMessage.error) {
+			throw new Error(`AnySearch MCP initialize failed: ${initMessage.error.message}`);
+		}
+		// Notify the server that initialization is complete (JSON-RPC notification: no id, response ignored).
+		await fetchImpl(`${baseUrl}/mcp`, {
+			method: "POST",
+			headers: mcpHeaders(sessionId),
+			body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
+		});
+		return sessionId;
+	}
+
+	// Session state is cached per client instance (and thus per baseUrl). The
+	// in-flight promise doubles as a mutex so concurrent MCP calls trigger only
+	// one handshake; a failed handshake is cleared so the next call retries.
+	let mcpSessionPromise: Promise<string | undefined> | null = null;
+
+	function ensureMcpSession(): Promise<string | undefined> {
+		if (!mcpSessionPromise) {
+			mcpSessionPromise = performHandshake();
+			mcpSessionPromise.catch(() => {
+				mcpSessionPromise = null;
+			});
+		}
+		return mcpSessionPromise;
+	}
+
+	async function mcpCall(tool: string, args: Record<string, unknown>): Promise<string> {
+		const sessionId = await ensureMcpSession();
+		const res = await fetchImpl(`${baseUrl}/mcp`, {
+			method: "POST",
+			headers: mcpHeaders(sessionId),
+			body: JSON.stringify({
+				jsonrpc: "2.0",
+				id: ++rpcId,
+				method: "tools/call",
+				params: { name: tool, arguments: args },
+			}),
+		});
+		if (!res.ok) {
+			throw new Error(`AnySearch MCP tool "${tool}" failed: ${await httpErrorMessage(res)}`);
+		}
+		const message = await readJsonRpc(res);
+		if (message.error) {
+			throw new Error(`AnySearch MCP tool "${tool}" failed: ${message.error.message}`);
+		}
+		const texts = (message.result?.content ?? [])
+			.filter((item) => item.type === "text" && typeof item.text === "string")
+			.map((item) => item.text as string);
+		if (message.result?.isError) {
+			throw new Error(`AnySearch MCP tool "${tool}" failed: ${texts.join("\n") || "unknown error"}`);
+		}
+		return texts.join("\n");
+	}
+
+	return {
+		search,
+
+		batchSearch(params: BatchSearchParams): Promise<SearchResult[]> {
+			const { queries, ...shared } = params;
+			return Promise.all(queries.map((query) => search({ ...shared, query })));
+		},
+
+		extract(url: string): Promise<string> {
+			return mcpCall("extract", { url });
+		},
+
+		getDomains(domain: string): Promise<string> {
+			return mcpCall("get_sub_domains", { domain });
+		},
+	};
+}

package/src/config.ts

@@ -0,0 +1,77 @@
+/**
+ * API key resolution for pi-anysearch.
+ *
+ * Precedence (first hit wins):
+ *   1. ANYSEARCH_API_KEY environment variable
+ *   2. Project config  <cwd>/<CONFIG_DIR_NAME>/pi-anysearch/config.json
+ *      (read only when the project is trusted — an untrusted project must not
+ *      be able to inject an API key)
+ *   3. Global config   <homeDir>/<CONFIG_DIR_NAME>/agent/pi-anysearch/config.json
+ *   4. undefined (anonymous, rate-limited mode)
+ *
+ * Config files are JSON: { "apiKey": "sk-..." }. Missing files fall back
+ * silently; malformed JSON falls back with a console warning.
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+
+export interface ResolveApiKeyOptions {
+	env?: Record<string, string | undefined>;
+	homeDir?: string;
+	cwd?: string;
+	isProjectTrusted?: boolean;
+}
+
+const CONFIG_FILE_NAME = "config.json";
+
+async function readConfigKey(path: string): Promise<string | undefined> {
+	let raw: string;
+	try {
+		raw = await readFile(path, "utf-8");
+	} catch {
+		// File missing or unreadable: silent fallback to the next source.
+		return undefined;
+	}
+	try {
+		const parsed = JSON.parse(raw) as { apiKey?: unknown };
+		if (parsed && typeof parsed.apiKey === "string" && parsed.apiKey) {
+			return parsed.apiKey;
+		}
+		return undefined;
+	} catch (error) {
+		console.warn(
+			`pi-anysearch: ignoring malformed config file ${path}:`,
+			error instanceof Error ? error.message : error,
+		);
+		return undefined;
+	}
+}
+
+export async function resolveApiKey(options: ResolveApiKeyOptions = {}): Promise<string | undefined> {
+	const envKey = options.env?.ANYSEARCH_API_KEY;
+	if (envKey) {
+		return envKey;
+	}
+
+	if (options.isProjectTrusted === true && options.cwd) {
+		const projectKey = await readConfigKey(
+			join(options.cwd, CONFIG_DIR_NAME, "pi-anysearch", CONFIG_FILE_NAME),
+		);
+		if (projectKey) {
+			return projectKey;
+		}
+	}
+
+	if (options.homeDir) {
+		const globalKey = await readConfigKey(
+			join(options.homeDir, CONFIG_DIR_NAME, "agent", "pi-anysearch", CONFIG_FILE_NAME),
+		);
+		if (globalKey) {
+			return globalKey;
+		}
+	}
+
+	return undefined;
+}

package/src/index.ts

@@ -0,0 +1,323 @@
+/**
+ * pi-anysearch — AnySearch AI search extension for pi.
+ *
+ * Registers four LLM tools backed by the AnySearch API:
+ * - anysearch_search        (POST /v1/search)
+ * - anysearch_batch_search  (parallel /v1/search calls)
+ * - anysearch_extract       (MCP tools/call "extract")
+ * - anysearch_domains       (MCP tools/call "get_sub_domains")
+ *
+ * Set ANYSEARCH_API_KEY for authenticated access; without it the client runs
+ * in anonymous (rate-limited) mode.
+ */
+
+import {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	truncateHead,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { homedir } from "node:os";
+import { Type } from "typebox";
+import { createAnySearchClient, type AnySearchClient, type SearchResult } from "./anysearch.js";
+import { resolveApiKey } from "./config.js";
+
+// The 40 capability tags documented by AnySearch. Use StringEnum (not
+// Type.Union/Type.Literal) so the schema stays compatible with Google's API.
+const CAPABILITY_TAGS = [
+	"academic.biomedical",
+	"academic.citation",
+	"academic.dataset",
+	"academic.preprint",
+	"academic.search",
+	"agriculture.fao",
+	"business.company",
+	"business.jobs",
+	"business.people",
+	"business.trade",
+	"code.doc",
+	"code.snippet",
+	"energy.electricity",
+	"energy.production",
+	"environment.aqi",
+	"film.torrent",
+	"finance.calendar",
+	"finance.fundamental",
+	"finance.macro",
+	"finance.news",
+	"finance.quote",
+	"finance.screen",
+	"gaming.esports",
+	"gaming.store",
+	"general.general",
+	"health.drug",
+	"health.stats",
+	"health.trial",
+	"ip.global",
+	"legal.case",
+	"legal.legislation",
+	"legal.statute",
+	"resource.image",
+	"security.intel",
+	"security.noise",
+	"security.scan",
+	"security.vuln",
+	"social_media.social_media",
+	"travel.flight",
+	"travel.flight_status",
+] as const;
+
+// Optional parameters shared by the search and batch_search schemas.
+const sharedSearchParams = {
+	max_results: Type.Optional(
+		Type.Integer({ minimum: 1, maximum: 20, description: "Maximum number of results to return (1-20)" }),
+	),
+	tag: Type.Optional(
+		StringEnum(CAPABILITY_TAGS, {
+			description:
+				'Capability tag routing the query to a vertical index, e.g. "finance.quote", "academic.search", "code.doc". Omit for general web search.',
+		}),
+	),
+	zone: Type.Optional(
+		StringEnum(["cn", "intl"] as const, { description: 'Search zone: "cn" for China-focused results, "intl" for global' }),
+	),
+	language: Type.Optional(Type.String({ description: 'Response language code, e.g. "en", "zh"' })),
+	params: Type.Optional(
+		Type.Record(Type.String(), Type.Unknown(), {
+			description: "Tag-specific extra parameters as key/value pairs (e.g. { symbol: \"AAPL\" } for finance.quote)",
+		}),
+	),
+	format: Type.Optional(
+		StringEnum(["json", "markdown"] as const, { description: 'Result content format: "json" or "markdown"' }),
+	),
+};
+
+const searchSchema = Type.Object({
+	query: Type.String({ description: "The search query" }),
+	...sharedSearchParams,
+});
+
+const batchSearchSchema = Type.Object({
+	queries: Type.Array(Type.String({ description: "A search query" }), {
+		minItems: 1,
+		description: "Queries to execute in parallel",
+	}),
+	...sharedSearchParams,
+});
+
+const extractSchema = Type.Object({
+	url: Type.String({ description: "URL of the page to extract readable content from" }),
+});
+
+const domainsSchema = Type.Object({
+	domain: Type.String({ description: 'Top-level capability domain to inspect, e.g. "finance", "academic"' }),
+});
+
+/** Byte-level truncation of a single field value (e.g. one result's content). */
+function truncateContentBytes(
+	text: string,
+	maxBytes: number,
+): { text: string; keptBytes: number; totalBytes: number; truncated: boolean } {
+	const bytes = new TextEncoder().encode(text);
+	if (bytes.length <= maxBytes) {
+		return { text, keptBytes: bytes.length, totalBytes: bytes.length, truncated: false };
+	}
+	// Cut by raw bytes; the decoder replaces a trailing incomplete multi-byte
+	// sequence with U+FFFD instead of producing mojibake.
+	const cut = bytes.subarray(0, maxBytes);
+	return { text: new TextDecoder().decode(cut), keptBytes: cut.length, totalBytes: bytes.length, truncated: true };
+}
+
+/** Keep tool output within pi's default limits, noting truncation in the text. */
+function truncateForOutput(text: string): string {
+	const result = truncateHead(text, { maxBytes: DEFAULT_MAX_BYTES, maxLines: DEFAULT_MAX_LINES });
+	if (!result.truncated) {
+		return text;
+	}
+	let content = result.content;
+	let keptBytes = result.outputBytes;
+	if (result.firstLineExceedsLimit) {
+		// A single line exceeds the byte limit and truncateHead yields nothing; cut
+		// by raw bytes so the model still sees the beginning. The decoder replaces
+		// any trailing incomplete multi-byte sequence with U+FFFD (no mojibake).
+		const cut = new TextEncoder().encode(text).subarray(0, DEFAULT_MAX_BYTES);
+		content = new TextDecoder().decode(cut);
+		keptBytes = cut.length;
+	}
+	return (
+		`${content}\n\n[Output truncated: kept ${keptBytes} of ${result.totalBytes} bytes ` +
+		`(${result.truncatedBy} limit). Narrow the query or reduce max_results.]`
+	);
+}
+
+// Headroom reserved for the header lines, URL and the truncation notice so
+// that a field-truncated result set stays under the whole-output byte limit.
+const CONTENT_TRUNCATE_HEADROOM = 1200;
+
+function formatSearchResults(query: string, result: SearchResult): string {
+	const lines = [
+		`Found ${result.results.length} result(s) for "${query}" ` +
+			`(total_results: ${result.metadata.total_results}, search_time_ms: ${result.metadata.search_time_ms})`,
+	];
+	result.results.forEach((item, index) => {
+		lines.push("", `[${index + 1}] ${item.title}`, `URL: ${item.url}`);
+		if (item.snippet) lines.push(`Snippet: ${item.snippet}`);
+		if (item.content) {
+			const content = truncateContentBytes(item.content, DEFAULT_MAX_BYTES - CONTENT_TRUNCATE_HEADROOM);
+			lines.push(`Content: ${content.text}`);
+			if (content.truncated) {
+				lines.push(
+					`[Content truncated: kept ${content.keptBytes} of ${content.totalBytes} bytes. ` +
+						`Use anysearch_extract on the URL for the full page.]`,
+				);
+			}
+		}
+	});
+	return lines.join("\n");
+}
+
+export default function anysearchExtension(pi: ExtensionAPI) {
+	// Clients are created lazily on first tool execution: the API key is
+	// resolved per context (env > trusted project config > global config) and
+	// cached by cwd + trust state so keys never leak across contexts. A failed
+	// resolution is evicted so the next execution retries.
+	const clients = new Map<string, Promise<AnySearchClient>>();
+
+	function getClient(ctx: ExtensionContext | undefined): Promise<AnySearchClient> {
+		const cwd = typeof ctx?.cwd === "string" ? ctx.cwd : process.cwd();
+		// Untrusted (or unknown) contexts must not read project-level config.
+		const trusted = typeof ctx?.isProjectTrusted === "function" ? ctx.isProjectTrusted() : false;
+		const cacheKey = `${trusted ? "trusted" : "untrusted"}:${cwd}`;
+		let client = clients.get(cacheKey);
+		if (!client) {
+			// Prefer $HOME over os.homedir(): it is the conventional override point
+			// for the home directory (and os.homedir() ignores later $HOME changes
+			// in some runtimes).
+			const homeDir = process.env.HOME ?? homedir();
+			client = resolveApiKey({
+				env: process.env,
+				homeDir,
+				cwd,
+				isProjectTrusted: trusted,
+			}).then((apiKey) => createAnySearchClient({ apiKey }));
+			clients.set(cacheKey, client);
+			client.catch(() => clients.delete(cacheKey));
+		}
+		return client;
+	}
+
+	pi.registerTool({
+		name: "anysearch_search",
+		label: "AnySearch Search",
+		description:
+			"Search the web with AnySearch, a vertical search API with 40 curated capability domains " +
+			"(finance, academic, legal, security, health, travel, ...). Returns titles, URLs, snippets and " +
+			"extracted page content. When the query clearly belongs to a vertical, pass its capability tag " +
+			"(e.g. finance.quote for stock quotes, academic.search for papers, security.vuln for CVEs, " +
+			"code.doc for API documentation) for higher-precision results; omit tag for general web search.",
+		promptSnippet: "Vertical web search via AnySearch (40 capability tags, cn/intl zones)",
+		promptGuidelines: [
+			"Use anysearch_search for web lookups; set its tag parameter when the request matches a vertical such as finance.quote, academic.search, code.doc or security.vuln.",
+			'Use anysearch_search with zone "cn" for China-focused queries and zone "intl" for global ones.',
+		],
+		parameters: searchSchema,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const client = await getClient(ctx);
+			const result = await client.search(params);
+			return {
+				content: [{ type: "text", text: truncateForOutput(formatSearchResults(params.query, result)) }],
+				details: {
+					request_id: result.request_id,
+					query: params.query,
+					total_results: result.metadata.total_results,
+					search_time_ms: result.metadata.search_time_ms,
+					result_count: result.results.length,
+				},
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "anysearch_batch_search",
+		label: "AnySearch Batch Search",
+		description:
+			"Run several AnySearch vertical-search queries in parallel and return all result sets in one call. " +
+			"Accepts the same optional parameters as anysearch_search (tag, zone, language, params, format, " +
+			"max_results), applied to every query. Prefer this over multiple sequential searches when comparing " +
+			"or gathering several independent queries.",
+		promptSnippet: "Parallel AnySearch queries aggregated into one result",
+		promptGuidelines: [
+			"Use anysearch_batch_search instead of repeated anysearch_search calls when the user asks several independent questions at once.",
+		],
+		parameters: batchSearchSchema,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const client = await getClient(ctx);
+			const { queries, ...shared } = params;
+			const results = await client.batchSearch({ ...shared, queries });
+			const sections = results.map(
+				(result, index) => `=== Query ${index + 1}: ${formatSearchResults(queries[index], result)}`,
+			);
+			return {
+				content: [
+					{
+						type: "text",
+						text: truncateForOutput(
+							`Batch search: ${queries.length} queries executed in parallel\n\n${sections.join("\n\n")}`,
+						),
+					},
+				],
+				details: {
+					request_count: results.length,
+					queries,
+					total_results: results.reduce((sum, r) => sum + r.metadata.total_results, 0),
+				},
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "anysearch_extract",
+		label: "AnySearch Extract",
+		description:
+			"Fetch a web page through AnySearch's extraction service and return its readable content as " +
+			"markdown (main text, stripped of navigation/ads). Use after anysearch_search to read the full " +
+			"content of a promising URL.",
+		promptSnippet: "Extract readable markdown content from a URL via AnySearch",
+		promptGuidelines: [
+			"Use anysearch_extract to read the full content of a URL returned by anysearch_search before summarizing or quoting it.",
+		],
+		parameters: extractSchema,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const client = await getClient(ctx);
+			const text = await client.extract(params.url);
+			return {
+				content: [{ type: "text", text: truncateForOutput(text) }],
+				details: { url: params.url },
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "anysearch_domains",
+		label: "AnySearch Domains",
+		description:
+			"List the curated sub-domains AnySearch covers under a top-level capability domain " +
+			'(e.g. "finance", "academic", "legal"). Use this to discover which capability tags exist ' +
+			"before choosing a tag for anysearch_search.",
+		promptSnippet: "Discover AnySearch capability sub-domains and tags",
+		promptGuidelines: [
+			"Use anysearch_domains when unsure which capability tag to pass to anysearch_search for a specialized query.",
+		],
+		parameters: domainsSchema,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const client = await getClient(ctx);
+			const text = await client.getDomains(params.domain);
+			return {
+				content: [{ type: "text", text: truncateForOutput(text) }],
+				details: { domain: params.domain },
+			};
+		},
+	});
+}