@yandy0725/pi-web-tools 0.1.0

package/README.md

@@ -0,0 +1,144 @@
+# pi-web-tools
+
+A [pi](https://pi.dev/docs/latest/packages) package providing web and image search tools for coding agents.
+
+## Tools
+
+| Tool | Description | Source |
+|------|-------------|--------|
+| `web_search` | Pure web search, returns raw results (titles, URLs, snippets) | Exa (REST + MCP free tier) |
+| `deep_search` | Deep research with LLM-synthesized answers | Aliyun (Bailian) Chat Completions API |
+| `image_search` | Search images by text or find similar images by URL | Aliyun (Bailian) Responses API |
+| `web_fetch` | Fetch and convert web pages to text, markdown, or raw HTML | — |
+
+## Quick Start
+
+```bash
+# Install from a local checkout
+pi install ./path/to/pi-web-tools
+
+# Or test with -e flag
+pi -e ./index.ts
+```
+
+### Prerequisites
+
+- `web_search`: No config needed — Exa MCP free tier (150 calls/day). Set `EXA_API_KEY` for higher limits.
+- `deep_search` / `image_search`: Set `ALIYUN_API_KEY` or use `/login` in pi to authenticate with Aliyun.
+
+## Configuration
+
+Configuration uses two layers: environment variables for API keys, and a project config file for other settings.
+
+### API Keys (environment variables only)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `EXA_API_KEY` | Exa API key. If not set, uses MCP free tier (150 calls/day) | — |
+| `ALIYUN_API_KEY` | Aliyun (Bailian) API key | — |
+| `ALIYUN_BASE_URL` | Aliyun API base URL | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+| `ALIYUN_DEEP_SEARCH_MODEL` | Model for deep_search | `deepseek-v4-flash` |
+| `ALIYUN_IMAGE_SEARCH_MODEL` | Model for image_search | `qwen3.7-plus` |
+
+Aliyun also supports key resolution via pi's `/login` — if you've logged into Aliyun through pi, no env var needed.
+
+### Project Config (`.pi/agent/web-tools.json`)
+
+Create `.pi/agent/web-tools.json` in your project root for per-project settings:
+
+```json
+{
+  "aliyun": {
+    "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+    "aliyunProviderKey": "aliyun",
+    "deepSearchModel": "deepseek-v4-flash",
+    "imageSearchModel": "qwen3.7-plus"
+  }
+}
+```
+
+Environment variables take precedence over the config file.
+
+| Config Key | Env Variable (overrides) | Default | Description |
+|------------|--------------------------|---------|-------------|
+| `aliyun.baseUrl` | `ALIYUN_BASE_URL` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | Aliyun API base URL |
+| `aliyun.aliyunProviderKey` | — | `aliyun` | Pi provider name to extract apiKey/baseUrl from |
+| `aliyun.deepSearchModel` | `ALIYUN_DEEP_SEARCH_MODEL` | `deepseek-v4-flash` | Model for deep_search |
+| `aliyun.imageSearchModel` | `ALIYUN_IMAGE_SEARCH_MODEL` | `qwen3.7-plus` | Model for image_search |
+
+**aliyunProviderKey:** deep_search and image_search will extract apiKey and baseUrl from the corresponding pi provider (via `modelRegistry`). Defaults to `"aliyun"`. Environment variables take precedence over provider values. If the provider is not found, falls back to `aliyun.baseUrl` config or default.
+
+> **Note:** deep_search uses Chat Completions API and does not return structured sources. image_search uses Responses API.
+
+> **Security:** API keys are NEVER read from config files — only from environment variables or pi's built-in credential store (`/login`).
+
+## Tools Reference
+
+### web_search
+
+Search the web with automatic source fallback.
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `query` | string | yes | — | Search query |
+| `numResults` | number | no | 10 | Number of results (1-20) |
+| `source` | `"exa"` | no | — | Search source |
+
+**Source:** **Exa** — AI-native search API. With `EXA_API_KEY`: full REST API. Without: MCP free tier (150 calls/day, 3 QPS). Always available, no key needed for basic usage.
+
+### deep_search
+
+Deep research using Aliyun's LLM-powered search with web content extraction. The model searches the web, extracts page content, and synthesizes a comprehensive answer.
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `query` | string | yes | — | Research question |
+| `enableSearchExtension` | boolean | no | false | Enable vertical domain search |
+| `freshness` | number | no | — | Time range: 7/30/180/365 days |
+| `assignedSiteList` | string[] | no | — | Restrict search to specific sites |
+| `enableImageOutput` | boolean | no | false | Enable mixed text-image output |
+
+> Requires `ALIYUN_API_KEY` or `aliyunProviderKey` config. Uses Chat Completions API with forced search (turbo strategy). Sources are not returned.
+
+### image_search
+
+Search images by text description or find visually similar images by URL.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | no | Text description for text-to-image search |
+| `imageUrl` | string | no | Public image URL for image-to-image search |
+
+> At least one of `query` or `imageUrl` must be provided. Both can be combined.
+> The image URL must be publicly accessible. Requires `ALIYUN_API_KEY`.
+
+### web_fetch
+
+Fetch content from a URL and return as text, markdown, or raw HTML.
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `url` | string | yes | — | URL to fetch |
+| `format` | `"text"` \| `"markdown"` \| `"html"` | no | `"markdown"` | Output format |
+| `timeout` | number | no | 30 | Timeout in seconds (1-120) |
+
+## Development
+
+```bash
+npm install              # Install dependencies
+npm run typecheck        # tsc --noEmit
+npm run lint             # biome lint
+npm test                 # vitest run
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,308 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { loadConfig } from "./src/config";
+import { deepSearch } from "./src/deep_search/index";
+import { imageSearch } from "./src/image_search/index";
+import { webFetch } from "./src/web_fetch";
+import { search } from "./src/web_search/index";
+
+export default function (pi: ExtensionAPI) {
+	// -------------------------------------------------------------------
+	// web_search
+	// -------------------------------------------------------------------
+	pi.registerTool({
+		name: "web_search",
+		label: "Web Search",
+		description:
+			`Search the web via Exa and return raw results (titles, URLs, snippets). With EXA_API_KEY: full REST API. Without: MCP free tier (150 calls/day). ` +
+			`The current year is ${new Date().getFullYear()}.`,
+		promptSnippet:
+			"web_search: search the web via Exa. Returns raw results with titles, URLs, snippets. LLM synthesizes the answer.",
+		promptGuidelines: [
+			"Use web_search when you need current information outside your training data.",
+			"Synthesize a clear answer from the search results and cite sources with markdown hyperlinks.",
+		],
+		parameters: Type.Object({
+			query: Type.String({ minLength: 2, description: "The search query." }),
+			numResults: Type.Optional(
+				Type.Number({ minimum: 1, maximum: 20, default: 10, description: "Number of results (1-20)." }),
+			),
+			source: Type.Optional(Type.String({ enum: ["exa"], description: "Search source. Default: exa." })),
+		}),
+		renderCall(args, theme) {
+			const p = args as { query: string };
+			return new Text(
+				theme.fg("toolTitle", theme.bold("web_search ")) + theme.fg("accent", `"${p.query || "..."}"`),
+				0,
+				0,
+			);
+		},
+		renderResult(result, { expanded }, theme) {
+			const text = result.content?.[0];
+			const body = text?.type === "text" ? text.text : "";
+			const lines = body.split("\n");
+			if (!expanded) {
+				const preview = lines.slice(0, 6);
+				if (lines.length > 6) preview.push(theme.fg("dim", `... ${lines.length - 6} more lines · ctrl+o to expand`));
+				return new Text(preview.join("\n"), 0, 0);
+			}
+			return new Text(body, 0, 0);
+		},
+		async execute(_toolCallId, params, signal, onUpdate, _ctx) {
+			const p = params as { query: string; numResults?: number; source?: string };
+			const query = p.query?.trim();
+			if (!query) {
+				return { content: [{ type: "text", text: "Error: query is required." }], details: {}, isError: true };
+			}
+
+			onUpdate?.({ content: [{ type: "text", text: "Searching..." }], details: {} });
+
+			let firstProgress = true;
+			const onProgress = (msg: string) => {
+				if (firstProgress) {
+					onUpdate?.({ content: [{ type: "text", text: msg }], details: {} });
+					firstProgress = false;
+				}
+			};
+
+			try {
+				const result = await search(query, p.numResults ?? 10, signal, onProgress, p.source);
+				const sourceLabel = `\n\n*Source: ${result.sourceLabel}*`;
+				return {
+					content: [{ type: "text", text: result.answer + sourceLabel }],
+					details: { source: result.sourceLabel, sources: result.sources },
+				};
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return { content: [{ type: "text", text: `Search failed: ${message}` }], details: {}, isError: true };
+			}
+		},
+	});
+
+	// -------------------------------------------------------------------
+	// deep_search
+	// -------------------------------------------------------------------
+	pi.registerTool({
+		name: "deep_search",
+		label: "Deep Search",
+		description:
+			"Deep search powered by Aliyun (Bailian) using Chat Completions API with web search. The model searches the web and synthesizes a comprehensive answer. Supports vertical domain search, time range filtering, site restriction, and mixed image output.",
+		promptSnippet:
+			"deep_search: Aliyun-powered deep search that synthesizes web results into a comprehensive answer. Supports vertical domain search, time range filtering, site restriction, and mixed image output.",
+		promptGuidelines: [
+			"Use deep_search for complex research questions that benefit from web search synthesis.",
+			"deep_search is powered by Aliyun Chat Completions API. Configure ALIYUN_API_KEY or use aliyunProviderKey in config.",
+		],
+		parameters: Type.Object({
+			query: Type.String({ minLength: 2, description: "The search query." }),
+			enableSearchExtension: Type.Optional(
+				Type.Boolean({ description: "Enable vertical domain search for more precise results." }),
+			),
+			freshness: Type.Optional(
+				Type.Number({
+					enum: [7, 30, 180, 365],
+					description: "Time range filter: 7/30/180/365 days. Only effective with turbo strategy.",
+				}),
+			),
+			assignedSiteList: Type.Optional(
+				Type.Array(Type.String(), {
+					description: 'Restrict search to specific sites (e.g. ["baidu.com", "sina.cn"]).',
+				}),
+			),
+			enableImageOutput: Type.Optional(Type.Boolean({ description: "Enable mixed text-image output in the response." })),
+		}),
+		renderCall(args, theme) {
+			const p = args as { query: string };
+			return new Text(
+				theme.fg("toolTitle", theme.bold("deep_search ")) + theme.fg("accent", `"${p.query || "..."}"`),
+				0,
+				0,
+			);
+		},
+		renderResult(result, { expanded }, theme) {
+			const text = result.content?.[0];
+			const body = text?.type === "text" ? text.text : "";
+			const lines = body.split("\n");
+			if (!expanded) {
+				const preview = lines.slice(0, 6);
+				if (lines.length > 6) preview.push(theme.fg("dim", `... ${lines.length - 6} more lines · ctrl+o to expand`));
+				return new Text(preview.join("\n"), 0, 0);
+			}
+			return new Text(body, 0, 0);
+		},
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			const p = params as {
+				query: string;
+				enableSearchExtension?: boolean;
+				freshness?: number;
+				assignedSiteList?: string[];
+				enableImageOutput?: boolean;
+			};
+			const query = p.query?.trim();
+			if (!query) {
+				return { content: [{ type: "text", text: "Error: query is required." }], details: {}, isError: true };
+			}
+
+			onUpdate?.({ content: [{ type: "text", text: "Deep searching..." }], details: {} });
+
+			try {
+				const cfg = loadConfig(ctx.cwd);
+				const result = await deepSearch(query, signal, cfg.aliyun, ctx, {
+					enableSearchExtension: p.enableSearchExtension,
+					freshness: p.freshness,
+					assignedSiteList: p.assignedSiteList,
+					enableImageOutput: p.enableImageOutput,
+				});
+				const sourcesText = result.sources.length
+					? `\n\nSources:\n${result.sources.map((s, i) => `${i + 1}. [${s.title}](${s.url})`).join("\n")}`
+					: "";
+				return {
+					content: [{ type: "text", text: result.answer + sourcesText }],
+					details: { sources: result.sources },
+				};
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return { content: [{ type: "text", text: `Deep search failed: ${message}` }], details: {}, isError: true };
+			}
+		},
+	});
+
+	// -------------------------------------------------------------------
+	// image_search
+	// -------------------------------------------------------------------
+	pi.registerTool({
+		name: "image_search",
+		label: "Image Search",
+		description:
+			"Search for images by text description or find similar images by URL. Powered by Aliyun (Bailian). Returns image results and model analysis.",
+		promptSnippet: "image_search: search images by text or find similar images by URL. Powered by Aliyun (Bailian).",
+		promptGuidelines: [
+			"Use image_search to find images matching a text description (provide query).",
+			"Use image_search to find visually similar images (provide imageUrl, the image must be a publicly accessible URL).",
+			"Both query and imageUrl can be provided together for combined search.",
+		],
+		parameters: Type.Object({
+			query: Type.Optional(Type.String({ minLength: 2, description: "Text description of the image to search for." })),
+			imageUrl: Type.Optional(Type.String({ description: "Public URL of the image to find similar images." })),
+		}),
+		renderCall(args, theme) {
+			const p = args as { query?: string; imageUrl?: string };
+			const label = theme.fg("toolTitle", theme.bold("image_search "));
+			if (p.imageUrl) return new Text(label + theme.fg("accent", `[image: ${p.imageUrl}]`), 0, 0);
+			return new Text(label + theme.fg("accent", `"${p.query || "..."}"`), 0, 0);
+		},
+		renderResult(result, { expanded }, theme) {
+			const text = result.content?.[0];
+			const body = text?.type === "text" ? text.text : "";
+			const lines = body.split("\n");
+			if (!expanded) {
+				const preview = lines.slice(0, 6);
+				if (lines.length > 6) preview.push(theme.fg("dim", `... ${lines.length - 6} more lines · ctrl+o to expand`));
+				return new Text(preview.join("\n"), 0, 0);
+			}
+			return new Text(body, 0, 0);
+		},
+		async execute(_toolCallId, params, signal, onUpdate, ctx: ExtensionContext) {
+			const p = params as { query?: string; imageUrl?: string };
+			if (!p.query && !p.imageUrl) {
+				return {
+					content: [{ type: "text", text: "Error: at least one of query or imageUrl is required." }],
+					details: {},
+					isError: true,
+				};
+			}
+
+			onUpdate?.({ content: [{ type: "text", text: "Searching images..." }], details: {} });
+
+			try {
+				const cfg = loadConfig(ctx.cwd);
+				const result = await imageSearch({ query: p.query, imageUrl: p.imageUrl }, signal, cfg.aliyun, ctx);
+				const imagesText = result.images.length
+					? "\n\nImages:\n" + result.images.map((img) => `${img.index}. [${img.title}](${img.url})`).join("\n")
+					: "";
+				return {
+					content: [{ type: "text", text: result.answer + imagesText }],
+					details: { images: result.images },
+				};
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text", text: `Image search failed: ${message}` }],
+					details: {},
+					isError: true,
+				};
+			}
+		},
+	});
+
+	// -------------------------------------------------------------------
+	// web_fetch
+	// -------------------------------------------------------------------
+	pi.registerTool({
+		name: "web_fetch",
+		label: "Web Fetch",
+		description: "Fetch content from a URL and return as text, markdown, or raw HTML.",
+		promptSnippet: "web_fetch: fetch content from a URL as text, markdown, or raw HTML.",
+		promptGuidelines: [
+			"Use web_fetch to retrieve full page content from a URL.",
+			"Prefer fetching specific pages rather than homepages for more targeted information.",
+		],
+		parameters: Type.Object({
+			url: Type.String({ minLength: 5, description: "The URL to fetch content from." }),
+			format: Type.Optional(
+				Type.String({
+					enum: ["text", "markdown", "html"],
+					default: "markdown",
+					description: "Output format. Default: markdown.",
+				}),
+			),
+			timeout: Type.Optional(
+				Type.Number({
+					minimum: 1,
+					maximum: 120,
+					default: 30,
+					description: "Timeout in seconds (1-120). Default: 30.",
+				}),
+			),
+		}),
+		renderCall(args, theme) {
+			const p = args as { url: string };
+			return new Text(theme.fg("toolTitle", theme.bold("web_fetch ")) + theme.fg("accent", p.url || "..."), 0, 0);
+		},
+		renderResult(result, { expanded }, theme) {
+			const text = result.content?.[0];
+			const body = text?.type === "text" ? text.text : "";
+			const lines = body.split("\n");
+			if (!expanded) {
+				const preview = lines.slice(0, 6);
+				if (lines.length > 6) preview.push(theme.fg("dim", `... ${lines.length - 6} more lines · ctrl+o to expand`));
+				return new Text(preview.join("\n"), 0, 0);
+			}
+			return new Text(body, 0, 0);
+		},
+		async execute(_toolCallId, params, signal, onUpdate, _ctx) {
+			const p = params as { url: string; format?: "text" | "markdown" | "html"; timeout?: number };
+			const url = p.url?.trim();
+			if (!url) {
+				return { content: [{ type: "text", text: "Error: url is required." }], details: {}, isError: true };
+			}
+			const format = p.format || "markdown";
+			const timeout = p.timeout ?? 30;
+
+			onUpdate?.({ content: [{ type: "text", text: `Fetching ${url}...` }], details: {} });
+
+			try {
+				const result = await webFetch(url, format, timeout, signal);
+				const header = `URL: ${result.url}\nContent-Type: ${result.contentType}\n\n`;
+				return {
+					content: [{ type: "text", text: header + result.content }],
+					details: { url: result.url, contentType: result.contentType, status: result.status },
+				};
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return { content: [{ type: "text", text: `Fetch failed: ${message}` }], details: {}, isError: true };
+			}
+		},
+	});
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "@yandy0725/pi-web-tools",
+	"publishConfig": {
+		"access": "public"
+	},
+	"version": "0.1.0",
+	"description": "pi package providing web_search, deep_search, image_search and web_fetch tools",
+	"license": "MIT",
+	"type": "module",
+	"keywords": [
+		"pi-package"
+	],
+	"files": [
+		"index.ts",
+		"src/"
+	],
+	"scripts": {
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome lint .",
+		"format": "biome format --write .",
+		"check": "biome check ."
+	},
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"dependencies": {
+		"openai": "^6.26.0"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": ">=0.74.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.0",
+		"@earendil-works/pi-coding-agent": "^0.74.0",
+		"@types/node": "^22.0.0",
+		"typescript": "~5.7.0",
+		"vitest": "^3.0.0"
+	}
+}

package/src/config.ts

@@ -0,0 +1,39 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+interface WebToolsConfig {
+	aliyun?: {
+		baseUrl?: string;
+		aliyunProviderKey?: string;
+		deepSearchModel?: string;
+		imageSearchModel?: string;
+	};
+}
+
+let cachedConfig: WebToolsConfig | null = null;
+let cachedCwd: string | null = null;
+
+export function loadConfig(cwd?: string): WebToolsConfig {
+	const dir = cwd || process.cwd();
+	if (cachedConfig && cachedCwd === dir) return cachedConfig;
+
+	try {
+		const path = resolve(dir, ".pi/agent/web-tools.json");
+		const raw = readFileSync(path, "utf-8");
+		cachedConfig = JSON.parse(raw) as WebToolsConfig;
+		cachedCwd = dir;
+		return cachedConfig;
+	} catch {
+		cachedConfig = {};
+		cachedCwd = dir;
+		return cachedConfig;
+	}
+}
+
+export function resolveSetting(
+	value: string | undefined,
+	configValue: string | undefined,
+	defaultValue: string,
+): string {
+	return value || configValue || defaultValue;
+}

package/src/deep_search/aliyun.ts

@@ -0,0 +1,48 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type OpenAI from "openai";
+import { resolveSetting } from "../config";
+import { createAliyunClient } from "../openai_client";
+import { resolveAliyunProvider } from "../provider";
+import type { DeepSearchOptions, DeepSearchResponse } from "./types";
+
+const DEFAULT_DEEP_SEARCH_MODEL = "deepseek-v4-flash";
+const TIMEOUT_MS = 120_000;
+
+export async function aliyunDeepSearch(
+	query: string,
+	signal?: AbortSignal,
+	config?: { baseUrl?: string; aliyunProviderKey?: string; deepSearchModel?: string },
+	ctx?: ExtensionContext,
+	searchOpts?: DeepSearchOptions,
+): Promise<DeepSearchResponse> {
+	const { apiKey, baseUrl } = await resolveAliyunProvider({ ctx, config });
+	const model = resolveSetting(process.env.ALIYUN_DEEP_SEARCH_MODEL, config?.deepSearchModel, DEFAULT_DEEP_SEARCH_MODEL);
+	const client = createAliyunClient({ apiKey, baseUrl });
+
+	const s = signal ? AbortSignal.any([signal, AbortSignal.timeout(TIMEOUT_MS)]) : AbortSignal.timeout(TIMEOUT_MS);
+
+	const { enableSearchExtension, freshness, assignedSiteList, enableImageOutput } = searchOpts ?? {};
+
+	const searchOptions: Record<string, unknown> = {
+		search_strategy: "turbo",
+		forced_search: true,
+		...(enableSearchExtension && { enable_search_extension: true }),
+		...(freshness && { freshness }),
+		...(assignedSiteList?.length && { assigned_site_list: assignedSiteList }),
+	};
+
+	const completion = await client.chat.completions.create(
+		{
+			model,
+			messages: [{ role: "user", content: query }],
+			stream: false,
+			enable_search: true,
+			search_options: searchOptions,
+			...(enableImageOutput && { enable_text_image_mixed: true }),
+		} as unknown as OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming,
+		{ signal: s },
+	);
+
+	const answer = completion.choices[0]?.message?.content || "No results";
+	return { answer, sources: [] };
+}

package/src/deep_search/index.ts

@@ -0,0 +1 @@
+export { aliyunDeepSearch as deepSearch } from "./aliyun";

package/src/deep_search/types.ts

@@ -0,0 +1,16 @@
+export interface DeepSearchSource {
+	title: string;
+	url: string;
+}
+
+export interface DeepSearchResponse {
+	answer: string;
+	sources: DeepSearchSource[];
+}
+
+export interface DeepSearchOptions {
+	enableSearchExtension?: boolean;
+	freshness?: number;
+	assignedSiteList?: string[];
+	enableImageOutput?: boolean;
+}

package/src/image_search/aliyun.ts

@@ -0,0 +1,87 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type OpenAI from "openai";
+import { resolveSetting } from "../config";
+import { createAliyunClient } from "../openai_client";
+import { resolveAliyunProvider } from "../provider";
+import type { ImageResult, ImageSearchParams, ImageSearchResponse } from "./types";
+
+const DEFAULT_IMAGE_SEARCH_MODEL = "qwen3.7-plus";
+const TIMEOUT_MS = 120_000;
+
+export async function aliyunImageSearch(
+	params: ImageSearchParams,
+	signal?: AbortSignal,
+	config?: { baseUrl?: string; aliyunProviderKey?: string; imageSearchModel?: string },
+	ctx?: ExtensionContext,
+): Promise<ImageSearchResponse> {
+	const { query, imageUrl } = params;
+
+	if (!query && !imageUrl) {
+		throw new Error("At least one of query or imageUrl must be provided");
+	}
+
+	const { apiKey, baseUrl } = await resolveAliyunProvider({ ctx, config });
+	const model = resolveSetting(
+		process.env.ALIYUN_IMAGE_SEARCH_MODEL,
+		config?.imageSearchModel,
+		DEFAULT_IMAGE_SEARCH_MODEL,
+	);
+	const client = createAliyunClient({ apiKey, baseUrl });
+
+	const s = signal ? AbortSignal.any([signal, AbortSignal.timeout(TIMEOUT_MS)]) : AbortSignal.timeout(TIMEOUT_MS);
+
+	let input: unknown;
+	let tools: Array<{ type: string }>;
+
+	if (imageUrl) {
+		tools = [{ type: "image_search" }];
+		const content: Array<{ type: string; [key: string]: unknown }> = [];
+		if (query) {
+			content.push({ type: "input_text", text: query });
+		}
+		content.push({ type: "input_image", image_url: imageUrl });
+		input = [{ role: "user", content }];
+	} else {
+		tools = [{ type: "web_search_image" }];
+		input = query;
+	}
+
+	const response = (await client.responses.create(
+		{ model, input, tools } as unknown as OpenAI.Responses.ResponseCreateParams,
+		{ signal: s },
+	)) as unknown as AliyunImageResponse;
+
+	const images = parseImages(response.output);
+	const answer = parseAnswer(response.output);
+
+	return { answer, images };
+}
+
+interface AliyunImageResponse {
+	output?: Array<{
+		type: string;
+		output?: string;
+		content?: Array<{ type?: string; text?: string }>;
+	}>;
+}
+
+function parseImages(output: AliyunImageResponse["output"] = []): ImageResult[] {
+	for (const item of output) {
+		if (item.type === "web_search_image_call" || item.type === "image_search_call") {
+			try {
+				return JSON.parse(item.output || "[]") as ImageResult[];
+			} catch {
+				return [];
+			}
+		}
+	}
+	return [];
+}
+
+function parseAnswer(output: AliyunImageResponse["output"] = []): string {
+	const messages = output.filter((item) => item.type === "message");
+	const texts = messages.flatMap((m) =>
+		(m.content || []).filter((c) => c.type === "output_text").map((c) => c.text || ""),
+	);
+	return texts.join("\n") || "No results";
+}

package/src/image_search/index.ts

@@ -0,0 +1 @@
+export { aliyunImageSearch as imageSearch } from "./aliyun";

package/src/image_search/types.ts

@@ -0,0 +1,15 @@
+export interface ImageResult {
+	index: number;
+	title: string;
+	url: string;
+}
+
+export interface ImageSearchResponse {
+	answer: string;
+	images: ImageResult[];
+}
+
+export interface ImageSearchParams {
+	query?: string;
+	imageUrl?: string;
+}

package/src/openai_client.ts

@@ -0,0 +1,9 @@
+import OpenAI from "openai";
+
+export function createAliyunClient(opts: { apiKey: string; baseUrl: string }): OpenAI {
+	return new OpenAI({
+		apiKey: opts.apiKey,
+		baseURL: opts.baseUrl,
+		maxRetries: 0,
+	});
+}

package/src/provider.ts

@@ -0,0 +1,69 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const DEFAULT_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1";
+const DEFAULT_PROVIDER_KEY = "aliyun";
+
+interface ProviderConfig {
+	baseUrl?: string;
+	aliyunProviderKey?: string;
+}
+
+interface ResolvedProvider {
+	apiKey: string;
+	baseUrl: string;
+}
+
+export async function resolveAliyunProvider(opts: {
+	ctx?: ExtensionContext;
+	config?: ProviderConfig;
+}): Promise<ResolvedProvider> {
+	const { ctx, config } = opts;
+	const providerKey = config?.aliyunProviderKey ?? DEFAULT_PROVIDER_KEY;
+
+	// --- apiKey ---
+	let apiKey: string | undefined;
+
+	const envApiKey = process.env.ALIYUN_API_KEY;
+	if (envApiKey) {
+		apiKey = envApiKey;
+	}
+
+	if (!apiKey && providerKey && ctx) {
+		const providerKeyResult = await ctx.modelRegistry.getApiKeyForProvider(providerKey);
+		if (providerKeyResult) {
+			apiKey = providerKeyResult;
+		}
+	}
+
+	if (!apiKey) {
+		throw new Error(
+			"ALIYUN_API_KEY not configured. Set ALIYUN_API_KEY or configure aliyunProviderKey with a valid pi provider.",
+		);
+	}
+
+	// --- baseUrl ---
+	let baseUrl: string | undefined;
+
+	const envBaseUrl = process.env.ALIYUN_BASE_URL;
+	if (envBaseUrl) {
+		baseUrl = envBaseUrl;
+	}
+
+	if (!baseUrl && providerKey && ctx) {
+		const allModels = ctx.modelRegistry.getAll();
+		const matchingModel = allModels.find((m) => m.provider === providerKey);
+		if (matchingModel?.baseUrl) {
+			baseUrl = matchingModel.baseUrl;
+		}
+	}
+
+	if (!baseUrl && config?.baseUrl) {
+		baseUrl = config.baseUrl;
+	}
+
+	if (!baseUrl) {
+		baseUrl = DEFAULT_BASE_URL;
+	}
+
+	return { apiKey, baseUrl };
+}

package/src/web_fetch.ts

@@ -0,0 +1,110 @@
+const MAX_CONTENT_CHARS = 100_000;
+
+export interface FetchResult {
+	content: string;
+	contentType: string;
+	url: string;
+	status: number;
+}
+
+export async function webFetch(
+	url: string,
+	format: "text" | "markdown" | "html",
+	timeout: number,
+	signal?: AbortSignal,
+): Promise<FetchResult> {
+	let parsedUrl: URL;
+	try {
+		parsedUrl = new URL(url);
+	} catch {
+		throw new Error(`Invalid URL: ${url}`);
+	}
+
+	if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+		throw new Error(`Unsupported protocol: ${parsedUrl.protocol}`);
+	}
+
+	const timeoutMs = Math.min(timeout * 1000, 120_000);
+	const timeoutSignal = AbortSignal.timeout(timeoutMs);
+	const s = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+
+	const response = await fetch(url, {
+		method: "GET",
+		headers: {
+			"User-Agent": "pi-web-tools/1.0",
+			Accept: format === "html" ? "text/html" : "text/html, text/plain, application/json",
+		},
+		redirect: "follow",
+		signal: s,
+	});
+
+	const contentType = response.headers.get("content-type") || "text/plain";
+	const body = await response.text();
+
+	if (!response.ok) {
+		const truncated = body.slice(0, 500);
+		throw new Error(`HTTP ${response.status} from ${url}${truncated ? `: ${truncated}` : ""}`);
+	}
+
+	let content: string;
+
+	if (contentType.includes("application/json")) {
+		try {
+			content = JSON.stringify(JSON.parse(body), null, 2);
+		} catch {
+			content = body;
+		}
+	} else if (format === "html") {
+		content = body;
+	} else {
+		content = htmlToText(body, format);
+	}
+
+	if (content.length > MAX_CONTENT_CHARS) {
+		const truncated = content.slice(0, MAX_CONTENT_CHARS);
+		content = `${truncated}\n\n... [truncated ${content.length - MAX_CONTENT_CHARS} characters]`;
+	}
+
+	return { content, contentType, url: response.url, status: response.status };
+}
+
+function htmlToText(html: string, format: "text" | "markdown"): string {
+	let text = html;
+
+	text = text.replace(/<head[\s\S]*?<\/head>/gi, "");
+	text = text.replace(/<style[\s\S]*?<\/style>/gi, "");
+	text = text.replace(/<script[\s\S]*?<\/script>/gi, "");
+	text = text.replace(/<noscript[\s\S]*?<\/noscript>/gi, "");
+
+	if (format === "markdown") {
+		text = text.replace(/<h1[^>]*>([\s\S]*?)<\/h1>/gi, "\n\n# $1\n\n");
+		text = text.replace(/<h2[^>]*>([\s\S]*?)<\/h2>/gi, "\n\n## $1\n\n");
+		text = text.replace(/<h3[^>]*>([\s\S]*?)<\/h3>/gi, "\n\n### $1\n\n");
+		text = text.replace(/<h4[^>]*>([\s\S]*?)<\/h4>/gi, "\n\n#### $1\n\n");
+		text = text.replace(/<h5[^>]*>([\s\S]*?)<\/h5>/gi, "\n\n##### $1\n\n");
+		text = text.replace(/<h6[^>]*>([\s\S]*?)<\/h6>/gi, "\n\n###### $1\n\n");
+		text = text.replace(/<strong[^>]*>([\s\S]*?)<\/strong>/gi, "**$1**");
+		text = text.replace(/<b[^>]*>([\s\S]*?)<\/b>/gi, "**$1**");
+		text = text.replace(/<em[^>]*>([\s\S]*?)<\/em>/gi, "*$1*");
+		text = text.replace(/<i[^>]*>([\s\S]*?)<\/i>/gi, "*$1*");
+		text = text.replace(/<code[^>]*>([\s\S]*?)<\/code>/gi, "`$1`");
+		text = text.replace(/<pre[^>]*>([\s\S]*?)<\/pre>/gi, "\n\n```\n$1\n```\n\n");
+		text = text.replace(/<a[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi, "[$2]($1)");
+		text = text.replace(/<li[^>]*>([\s\S]*?)<\/li>/gi, "- $1\n");
+		text = text.replace(/<p[^>]*>/gi, "\n\n");
+	}
+
+	text = text.replace(/<br\s*\/?>/gi, "\n");
+	text = text.replace(/<[^>]+>/g, "");
+	text = text.replace(/&amp;/g, "&");
+	text = text.replace(/&lt;/g, "<");
+	text = text.replace(/&gt;/g, ">");
+	text = text.replace(/&quot;/g, '"');
+	text = text.replace(/&#39;/g, "'");
+	text = text.replace(/&nbsp;/g, " ");
+	text = text.replace(/\n{3,}/g, "\n\n");
+	text = text.replace(/[ \t]+/g, " ");
+	text = text.trim();
+
+	return text;
+}

package/src/web_search/exa.ts

@@ -0,0 +1,163 @@
+import type { SearchResponse } from "./types";
+
+const EXA_REST_URL = "https://api.exa.ai/search";
+const EXA_MCP_URL = "https://mcp.exa.ai/mcp";
+const MCP_TOOL_NAME = "web_search_exa";
+const TIMEOUT_MS = 60_000;
+
+export async function exaSearch(query: string, numResults: number, signal?: AbortSignal): Promise<SearchResponse> {
+	const apiKey = process.env.EXA_API_KEY;
+
+	const timeoutSignal = AbortSignal.timeout(TIMEOUT_MS);
+	const s = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+
+	if (!apiKey) {
+		return exaMcpSearch(query, numResults, s);
+	}
+	return exaRestSearch(query, numResults, apiKey, s);
+}
+
+async function exaRestSearch(
+	query: string,
+	numResults: number,
+	apiKey: string,
+	signal: AbortSignal,
+): Promise<SearchResponse> {
+	const resp = await fetch(EXA_REST_URL, {
+		method: "POST",
+		headers: { "x-api-key": apiKey, "Content-Type": "application/json" },
+		body: JSON.stringify({
+			query,
+			numResults,
+			type: "auto",
+			contents: { text: { maxCharacters: 3000 } },
+		}),
+		signal,
+	});
+
+	if (!resp.ok) {
+		const detail = await resp.text().catch(() => resp.statusText);
+		throw new Error(`Exa API ${resp.status}: ${detail}`);
+	}
+
+	const data = (await resp.json()) as {
+		results?: Array<{ title?: string; url?: string; text?: string }>;
+	};
+	const results = data.results || [];
+
+	const sources = results.map((r) => ({
+		title: r.title || "Untitled",
+		url: r.url || "",
+		snippet: (r.text || "").slice(0, 500),
+	}));
+
+	const answer = formatAnswer(sources, query);
+	return { answer, sources, sourceLabel: "exa" };
+}
+
+async function exaMcpSearch(query: string, numResults: number, signal: AbortSignal): Promise<SearchResponse> {
+	// 1. initialize
+	const initResult = await mcpCall(
+		"initialize",
+		{
+			protocolVersion: "2024-11-05",
+			capabilities: {},
+			clientInfo: { name: "pi-web-tools", version: "1.0" },
+		},
+		signal,
+	);
+
+	if (!initResult) {
+		throw new Error("Exa MCP initialize failed: no result");
+	}
+
+	// 2. search
+	const searchResult = (await mcpCall(
+		MCP_TOOL_NAME,
+		{
+			query,
+			numResults,
+			type: "auto",
+			contents: { text: { maxCharacters: 3000 } },
+		},
+		signal,
+	)) as { content?: Array<{ text?: string }> } | null;
+
+	const text = searchResult?.content?.map((c) => c.text || "").join("\n\n") || "";
+	const sources = parseMcpResults(text);
+	const answer = formatAnswer(sources, query);
+
+	return { answer, sources, sourceLabel: "exa" };
+}
+
+async function mcpCall(method: string, params: unknown, signal: AbortSignal): Promise<Record<string, unknown> | null> {
+	const resp = await fetch(EXA_MCP_URL, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Accept: "application/json, text/event-stream",
+		},
+		body: JSON.stringify({
+			jsonrpc: "2.0",
+			method: method === "initialize" ? "initialize" : "tools/call",
+			params: method === "initialize" ? params : { name: method, arguments: params },
+			id: 1,
+		}),
+		signal,
+	});
+
+	if (!resp.ok) {
+		throw new Error(`Exa MCP ${method} failed: ${resp.status}`);
+	}
+
+	const contentType = resp.headers?.get("content-type") || "";
+
+	if (contentType.includes("text/event-stream")) {
+		const text = await resp.text();
+		for (const line of text.split("\n")) {
+			if (line.startsWith("data: ")) {
+				try {
+					const parsed = JSON.parse(line.slice(6));
+					if (parsed.result) return parsed.result as Record<string, unknown>;
+					if (parsed.error) throw new Error(`Exa MCP error: ${parsed.error.message || JSON.stringify(parsed.error)}`);
+				} catch (e) {
+					if (e instanceof SyntaxError) continue;
+					throw e;
+				}
+			}
+		}
+		return null;
+	}
+
+	const data = (await resp.json()) as { result?: Record<string, unknown>; error?: unknown };
+	if (data.error) throw new Error(`Exa MCP error: ${JSON.stringify(data.error)}`);
+	return data.result ?? null;
+}
+
+function formatAnswer(sources: Array<{ title: string; url: string; snippet: string }>, query: string): string {
+	return (
+		sources.map((s, i) => `${i + 1}. [${s.title}](${s.url})\n   ${s.snippet}`).join("\n\n") ||
+		`No results found for: ${query}`
+	);
+}
+
+function parseMcpResults(text: string): Array<{ title: string; url: string; snippet: string }> {
+	const results: Array<{ title: string; url: string; snippet: string }> = [];
+	const blocks = text.split(/\n\n---\n\n/);
+
+	for (const block of blocks) {
+		const titleMatch = block.match(/^Title:\s*(.+)$/m);
+		const urlMatch = block.match(/^URL:\s*(.+)$/m);
+		const highlightsMatch = block.match(/^Highlights:\s*\n([\s\S]*?)$/m);
+
+		if (urlMatch) {
+			results.push({
+				title: titleMatch?.[1]?.trim() || "Untitled",
+				url: urlMatch[1].trim(),
+				snippet: highlightsMatch?.[1]?.trim().slice(0, 500) || "",
+			});
+		}
+	}
+
+	return results;
+}

package/src/web_search/index.ts

@@ -0,0 +1,45 @@
+import { exaSearch } from "./exa";
+import type { SearchResponse } from "./types";
+
+type SearchFn = (query: string, numResults: number, signal?: AbortSignal) => Promise<SearchResponse>;
+
+interface SourceEntry {
+	name: string;
+	fn: SearchFn;
+}
+
+const SOURCES: SourceEntry[] = [
+	{
+		name: "exa",
+		fn: exaSearch,
+	},
+];
+
+export async function search(
+	query: string,
+	numResults: number,
+	signal?: AbortSignal,
+	onProgress?: (msg: string) => void,
+	specifiedSource?: string,
+): Promise<SearchResponse> {
+	const errors: string[] = [];
+
+	const sources = specifiedSource ? SOURCES.filter((s) => s.name === specifiedSource) : SOURCES;
+
+	if (specifiedSource && sources.length === 0) {
+		throw new Error(`Unknown source: ${specifiedSource}. Available: ${SOURCES.map((s) => s.name).join(", ")}`);
+	}
+
+	for (const source of sources) {
+		try {
+			onProgress?.(`Trying ${source.name}...`);
+			const resp = await source.fn(query, numResults, signal);
+			return resp;
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			errors.push(`${source.name}: ${msg}`);
+		}
+	}
+
+	throw new Error(`All search sources failed:\n${errors.map((e) => `  - ${e}`).join("\n")}`);
+}

package/src/web_search/types.ts

@@ -0,0 +1,11 @@
+export interface SearchSource {
+	title: string;
+	url: string;
+	snippet: string;
+}
+
+export interface SearchResponse {
+	answer: string;
+	sources: SearchSource[];
+	sourceLabel: string;
+}