pi-web-access

Pi extension for web search and URL content extraction.

Tools

web_search

Search the web for information. Also available via /web-search <query>. Registered when a keyed search provider is available, or when the keyless parallel provider is explicitly selected.

web_fetch

Fetch a URL and return its content. Also available via /web-fetch <url> [extraction instructions]; instructions default to “Summarize this page.” when omitted. When fetch.summary is configured, the summary model processes the content using prompt; otherwise the fetched content is returned directly and prompt is retained for compatibility but ignored. Only registered when fetch.provider or fetch.summary is configured.

x_search

Search X (Twitter) for posts and social media content. Only registered when xai provider has an API key.

image_search

Search the web for images. Only registered when an image search provider (dashscope or unsplash) has an API key. Also invocable directly via the /image-search <query> command.

Structured tool results

On Pi runtimes with structured tool support, codemode receives objects from these tools instead of parsing their Markdown. web_search, x_search, and image_search return { provider, query, answer?, results, truncated }, where each source has title, url, content, and an optional score. web_fetch returns { url, title, content, truncated }; content is the summary when a summary model is configured. Readable tool results remain available.

Results are bounded and truncated indicates shortened text or omitted sources; retained source URLs are never shortened. Failed calls return { error } with isError: true, so scripts must check for error before reading result fields. Cancellation still aborts the call. Older Pi runtimes keep their text-result behavior.

Providers

DeepSeek Search and Fetch

DeepSeek uses the Search and Fetch APIs: POST /v1/tools/search returns ranked sources with long summaries, and POST /v1/tools/fetch returns Markdown. Set search.provider and/or fetch.provider to "deepseek" and supply DEEPSEEK_API_KEY or providers.deepseek.apiKey. Existing DeepSeek settings continue to work; model is ignored and search no longer returns a synthesized answer. Both root and /v1 base URLs are supported.

Search requests use count (default 5, API limit 50) and need_content: false; fetch a result URL for its full body. Domain filters become site: / -site: syntax, and timeRange becomes an after:YYYY-MM-DD filter (1/7/30/365 days, UTC). The complete query, including filters, must contain 1–128 Unicode characters. topic is ignored; use query terms to search for news. Raw DeepSeek search syntax can also be included directly in the query.

Cloudflare Web Search

Set search.provider to "cloudflare". The Cloudflare Web Search REST API requires an account ID, an API token with Workers AI: Read and AI Gateway: Read permissions, and an AI Gateway with credits or a stored provider key. The default gateway is default; the default search provider is ceramic.

{
  "pi-web-access": {
    "search": { "provider": "cloudflare" },
    "providers": {
      "cloudflare": {
        "apiKey": "${CLOUDFLARE_API_TOKEN}",
        "accountId": "${CLOUDFLARE_ACCOUNT_ID}",
        "gatewayId": "default",
        "searchProvider": "ceramic"
      }
    }
  }
}

apiKey and accountId fall back to CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. Cloudflare is also eligible for automatic selection when both are available, after the existing search providers. Configure interpolated values in user or agent settings; trusted project settings do not expand environment variables.

Cloudflare-only provider settings:

Requests use POST {baseUrl}/accounts/{accountId}/ai/websearch/. Queries must contain 1–1024 characters. maxResults defaults to 5 and is capped at 10; topic, timeRange, includeDomains, and excludeDomains are ignored because this API does not support them. Results contain titles, URLs, and description snippets, without a synthesized answer; large snippets are truncated. Cloudflare supports search only.

Custom Kimi base URLs must support both /chat/completions and /formulas/*.

You.com search returns web and news results in one call; topic: "news" prefers news results and applies a one-week freshness window. The Contents API (/v1/contents) returns clean Markdown for web_fetch. Get a key at you.com/platform/api-keys.

Custom DashScope base URLs must point to an OpenAI-compatible Responses API root — ${baseUrl}/responses is called for all capabilities. For the international site or a dedicated workspace endpoint, use e.g. https://dashscope-intl.aliyuncs.com/compatible-mode/v1. DashScope fetch uses the web_extractor tool and image search uses web_search_image; both are agent-style tools and can take minutes per call (default timeout 5 min, tune via timeoutMs). DashScope search supports only basic web search — includeDomains/excludeDomains filters are ignored.

Fetch fallback (when fetch.provider is not set): Jina Reader (r.jina.ai, free, JS-rendered) → local HTTP GET + turndown. Both stages, including destination and redirect DNS validation, share one timeoutMs deadline (30 seconds by default); Jina receives at most half that budget so a slow reader still leaves time for local fallback. Jina and local response bodies are capped at 2 MiB before text/HTML conversion, and oversized responses return a marked partial prefix. The partial flag survives summarization; use a focused search or browser inspection to recover missing evidence rather than repeat the same full fetch. Configured provider adapters retain their own response and timeout policies.

Configuration

Settings key: pi-web-access

Project .pi/settings.json values are loaded only after project trust is accepted and are not environment-interpolated. User and agent settings retain environment interpolation.

{
  "pi-web-access": {
    "search": {
      "provider": "kimi"
    },
    "fetch": {
      "provider": "zai",
      "summary": {
        "provider": "amaster",
        "model": "deepseek-v4-flash"
      }
    },
    "providers": {
      "kimi": {
        "apiKey": "AMASTER_API_KEY",
        "baseUrl": "https://credits.amaster.ai/v1"
      },
      "zai": {
        "apiKey": "${ZAI_API_KEY}"
      },
      "xai": {
        "apiKey": "${XAI_API_KEY}"
      }
    }
  }
}

search

fetch

If neither fetch.provider nor fetch.summary is configured, web_fetch is not registered.

imageSearch

providers

Per-provider configuration. Each provider supports:

Environment variables serve as fallbacks when apiKey is not set in config.

Parallel is opt-in and supports search only: it never enables image search or web_fetch, and it does not perform URL fetching or extraction. When selected, search objectives and queries leave the machine for https://search.parallel.ai/mcp; this can include agent-generated repository context and user-supplied URLs contained in those objectives or queries. Existing automatic provider selection, provider order, and keyed provider behavior are unchanged.

Architecture

Each provider implements the WebProvider interface via BaseProvider:

// providers/base.ts
export interface WebProvider {
  readonly id: BuiltInProviderId;
  search(params: SearchParams, provider: ResolvedProvider): Promise<SearchResponse>;
  fetch(url: string, provider: ResolvedProvider): Promise<FetchResponse>;
  imageSearch(params: ImageSearchParams, provider: ResolvedProvider): Promise<SearchResponse>;
}

export abstract class BaseProvider implements WebProvider {
  abstract readonly id: BuiltInProviderId;
  // Default implementations throw "not supported"
  async search(...) { throw new Error(`${this.id} does not support web_search.`); }
  async fetch(...) { throw new Error(`${this.id} does not support web_fetch.`); }
  async imageSearch(...) { throw new Error(`${this.id} does not support image_search.`); }
}

Providers only override methods they support. Provider-specific capabilities (like XaiProvider.xsearch) are exposed as additional methods on the class.

Tool Registration Rules

• web_search and /web-search <query> — registered when a search provider has an API key, or when keyless parallel is explicitly selected.
• web_fetch and /web-fetch <url> [extraction instructions] — registered when fetch.provider or fetch.summary is configured.
• x_search — registered when xai provider has an API key.
• image_search — registered when an image search provider (dashscope, unsplash) has an API key; /image-search command is registered alongside it. An imageSearch.provider that doesn't support image search (e.g. "openai") is treated as unconfigured.
• If none are configured, the extension loads silently with no tools registered.

Install

pi install npm:@amaster.ai/pi-web-access

Development

pnpm build      # tsc -b
pnpm typecheck  # tsc -b --pretty false
pnpm test       # vitest run src

Tool failures

web_search, web_fetch, x_search, and image_search return isError: true with a safe error message and errorCategory: timeout for request deadlines, http_error for recognized HTTP failures (with numeric httpStatus), network_error for recognized transport failures, cancelled for an upstream cancellation, configuration_error / invalid_request / invalid_response for vetted local validation failures, or request_failed for unclassified failures. Raw provider errors, response bodies, URLs, and credentials are excluded from these failure results and diagnostic logs. Caller cancellation propagates to the runtime. The /web-search, /web-fetch, and /image-search commands use the same safe messages and log categories. A timeout does not imply invalid provider configuration.