@ian-pascoe/pi-web-tools

Bounded Web Search and Web Fetch model tools for Pi. Web Search discovers current public information through Exa or Parallel. Web Fetch retrieves one HTTP or HTTPS URL as text, Markdown, or HTML.

Install

Pi loads the source extension from this repository:

pi install git:github.com/ian-pascoe/pi-extensions

Select packages/pi-web-tools/src/index.ts for a filtered Git installation. After publishing, install the package directly:

pi install npm:@ian-pascoe/pi-web-tools

Requires Node.js 22.19 or newer and Pi >=0.99.0.

Tools

web_search

Searches current public web information. Pi deterministically chooses Exa or Parallel once per session with FNV-1a checksum parity; API-key presence never changes that choice. Both providers support anonymous requests. Set optional process environment keys before starting Pi:

export EXA_API_KEY=...
export PARALLEL_API_KEY=...

Exa receives all controls and an optional EXA_API_KEY endpoint credential. Parallel receives the query and Pi session ID; its protocol has no matching tuning fields. Search results are provider text without citation rewriting. A provider failure has no retry and never falls back to the other provider.

web_fetch

Fetches exactly one absolute HTTP or HTTPS URL. HTTP is preserved, native fetch redirects are followed, and loopback, link-local, and private-network URLs are permitted in Pi's local trust model.

Only textual MIME types are returned: an absent type, text/*, JSON, XML, JavaScript, and structured +json/+xml types. SVG is accepted as XML. Other images and files are rejected. HTML converts to Markdown or plain text when requested; scripts and other active embedded content are not executed. A Cloudflare 403 challenge gets one retry with the pi-web-tools user agent inside the original timeout budget.

Both tools declare MCP-style annotations: read-only, non-destructive, idempotent, and open-world. Pi reports them through pi.getAllTools() so permission extensions can decide which calls to confirm; Pi does not send them to model providers.

Script results

Both tools declare an outputSchema and return matching structuredContent, so a Pi codemode script receives an object instead of the model-facing text. Field names are snake_case, like Pi's bash and pi-termctrl; the session details keep their existing shape. The model still reads the same text, and a failed call still throws.

Scripts cannot read the private spill file, so content carries more than the model sees. Web Search content is the Search Provider's complete text answer (at most 256 KiB). Web Fetch content is the complete converted text up to 1 MiB of UTF-8, cut on a character boundary; truncated is true only for a longer page. full_output_path appears whenever the model-visible text was truncated, and then names the file with the complete text.

Search results stay provider free text: Exa and Parallel return prose-and-snippet blobs rather than records, so the schema does not invent result fields. It adds the selected provider and the complete text.

Limits and security

Web Search response bodies stop at 256 KiB. Web Fetch response bodies stop at 5 MiB. Both tools apply Pi's 50 KiB or 2,000-line model-output limit after parsing or conversion. When output is truncated, the complete text is written to a unique private temporary directory and the returned result includes its path and exact counts. Script results are bounded separately, as described above. The operating system owns later temporary-file cleanup.

Queries and URLs leave the machine for their Search Provider or requested host. Web Fetch intentionally permits private-network destinations, so use it only where the model and extension are trusted. The package provides no browser automation, JavaScript execution, extension-owned crawling, cookie storage, cache, settings, commands, or citation rewriting.

API keys are read once when the extension loads, used only to construct the final provider request, and never intentionally included in model content, result details, errors, or temporary files.

License

MIT