About 📖

pi-web-engine gives Pi two focused tools: native web search through the active OpenAI Codex model and hardened fetching of public web pages.

Search reuses Pi's existing Codex OAuth session, so there is no second API key to configure. Fetching converts pages into model-friendly Markdown while applying strict network, redirect, content-type, and response-size protections.

This focused release does not include Exa, Firecrawl, or Tavily. See the roadmap.

Features 🌟

• 🔎 Native Codex Search — follows the official Codex CLI's standalone web-search contract
• 🔑 No Additional Search Key — securely reuses the Codex OAuth session managed by Pi
• 🧠 Model-Agnostic Integration — supports models from Pi's official openai-codex provider without a brittle model-name allowlist
• 🛡️ Hardened Web Fetching — blocks private networks, DNS rebinding, unsafe redirects, URL credentials, and non-HTTP schemes
• 📄 Readable Output — extracts article content and returns Markdown, plain text, or HTML
• 🪪 Configurable Request Identity — supports a complete operator-controlled User-Agent value through Pi settings
• 📏 Bounded Responses — enforces download, provider-response, line, and tool-output limits
• 🧰 Type-Safe & Tested — built with TypeScript and TypeBox, with contract and security tests

Installation 📦

Requirements ✅

• Node.js 24.11 or newer
• Pi 0.84.4 or newer
• An OpenAI Codex login for web_search

Install from npm 🔥

pi install npm:pi-web-engine

Or directly from GitHub:

pi install git:github.com/WolfieLeader/pi-web-engine

Quick Start 🚀

1. Start Pi.
2. Use /login to create an OpenAI Codex session.
3. Use /model to select a model from the official openai-codex provider.
4. Ask Pi to search or fetch the web:

Search the web for the latest OpenAI Codex release and summarize the changes.

Fetch https://example.com and return the page as Markdown.

No additional configuration is required.

Configuration ⚙️

web_fetch identifies itself with this default request header:

pi-web-engine/0.1.2 (+https://github.com/WolfieLeader/pi-web-engine)

To replace the complete User-Agent value, add a namespaced setting to Pi's global ~/.pi/agent/settings.json:

{
  "pi-web-engine": {
    "userAgent": "OpenCode/1.0"
  }
}

A trusted project's .pi/settings.json may use the same shape and overrides the global value. Pi ignores project settings until the project is trusted; pi-web-engine preserves that boundary. The value must be 1–512 printable ASCII characters with no surrounding whitespace or control characters.

The setting is operator-controlled and is intentionally not exposed as a web_fetch tool argument.

Tools 🧰

web_search 🔎

Searches the web through Codex's native standalone search endpoint with external web access and returns evidence with normalized source URLs.

| Parameter | Type | Required | Description | | ----------------- | ---------- | -------- | ------------------------------------------------ | | query | string | Yes | Search query or question | | allowed_domains | string[] | No | Restrict results to up to 100 normalized domains |

• Credentials are resolved through Pi and sent only to the official https://chatgpt.com/backend-api endpoint.
• The active model must use Pi's official openai-codex provider and openai-codex-responses API.
• Search output is limited to 50 KB or 2,000 lines and includes an explicit truncation notice when needed.
• Time-sensitive claims should be verified against an authoritative first-party URL because external web access does not guarantee that every result snippet was retrieved at query time.

web_fetch 📄

Fetches a public HTTP(S) URL and returns readable content.

| Parameter | Type | Required | Description | | --------- | -------------------------------- | -------- | --------------------------------------------- | | url | string | Yes | Public HTTP or HTTPS URL | | format | "markdown" \| "text" \| "html" | No | Output format; defaults to "markdown" | | timeout | integer | No | Timeout in seconds, from 1 to 120; default 30 |

• HTML pages are parsed with Mozilla Readability before Markdown or text conversion.
• JSON, XML, and supported JavaScript text responses are accepted as structured-text fallbacks without overriding the requested format preference.
• Redirected fetches include a sanitized final URL in model-visible output.
• Non-text content and responses larger than 2 MB are rejected.
• Tool output is limited to 50 KB or 2,000 lines.

Security 🛡️

• 🌐 Network Boundaries — rejects localhost, private and reserved addresses, IPv4 transition addresses, URL credentials, and unsupported schemes
• 🔁 Safe Redirects — validates every redirect target and removes sensitive headers from cross-origin redirects
• 🧱 DNS Rebinding Protection — validates hostnames whenever the connector opens a socket, including after redirects
• 🔒 Credential Redaction — removes OAuth credentials from bounded provider errors before they reach tool output

[!IMPORTANT] These controls are defense in depth, not a sandbox boundary. Pi extensions execute with the user's permissions, so install only code you trust. Retrieved web content is untrusted and may contain prompt-injection attempts.

Codex Compatibility 🔌

• 🥇 Primary Source of Truth — the official Codex app and CLI
• 🔎 Search Contract — the Codex CLI's standalone web-search extension and codex/alpha/search endpoint
• 📚 Supporting Documentation — OpenAI's public web-search guide, which describes the related Responses API behavior
• 🧪 Release Policy — because the standalone endpoint is explicitly alpha, every release should retain request-contract tests and receive live Codex verification

Development 🛠️

pnpm install
pnpm check
pnpm build

For local Pi development:

pi -e ./src/index.ts

• 🧰 Tooling — TypeScript, pnpm, OXC, Knip, Vitest, TypeBox, and tsdown
• 📐 Validation — reuses Pi's TypeBox peer dependency for tool schemas and untrusted provider responses
• 🧹 Linting — the development-only anti-slop Oxlint plugin is vendored as required by upstream, retains its MIT license and provenance, and is excluded from the npm package

Roadmap 🗺️

See the Pi web-tool ecosystem survey for a living comparison of features, optimizations, architecture, specialized media support, and security tradeoffs.

Possible follow-up releases:

1. Exa provider support
2. Firecrawl search and extraction
3. Tavily provider support
4. Provider routing and configuration
5. Opt-in, credential-gated integration tests against live providers

Version history is available in the changelog.

Contributions 🤝

• Open an issue or feature request
• Submit a PR to improve the extension
• Star the repository if you find it useful

Crafted carefully by WolfieLeader

This project is licensed under the MIT License.