pi-web-scout

No-key web search extension for Pi. It registers a web_search tool and starts with providers that do not require API keys.

Goals

• No install lifecycle scripts.
• No native dependencies.
• No shell execution.
• No credential command execution.
• Provider architecture ready for future keyed APIs such as Brave, Serper, Tavily, Exa, etc.

Install

pi install npm:pi-web-scout

Try locally

pi -e ./pi-web-scout

Commands

/web-scout-status

Shows active config and provider status.

Tool

web_search

{
  "query": "latest TypeScript release notes",
  "max_results": 5,
  "provider": "auto",
  "mode": "first_success"
}

web_read

{
  "url": "https://example.com/docs",
  "max_chars": 12000
}

web_read fetches public HTTP(S) pages, follows validated redirects, blocks localhost/private/metadata IPs, strips noisy HTML, and returns readable text. It does not run JavaScript or launch a browser.

Recommended model flow: call web_search first, choose relevant result URLs, then call web_read on the best sources instead of relying on snippets alone.

Current no-key providers:

• duckduckgo — DuckDuckGo HTML endpoint.
• marginalia — Marginalia Search public endpoint.
• jina — Jina Search endpoint without an API key.

Current keyed providers, disabled by default:

• brave — Brave Search API, env-only key resolution.

Planned keyed providers:

• Serper, Tavily, Exa, etc.

Config

Optional project config:

.pi/pi-web-scout.json

{
  "enabled": true,
  "defaultProvider": "auto",
  "fallbackChain": ["duckduckgo", "marginalia", "jina"],
  "maxResults": 5,
  "providers": {
    "duckduckgo": { "enabled": true },
    "marginalia": { "enabled": true },
    "jina": { "enabled": true },
    "brave": { "enabled": false, "apiKeyEnv": "PI_WEB_SCOUT_BRAVE_API_KEY" }
  }
}

The extension currently reads project config only and does not write config files. Invalid config fails fast with a clear error.

mode: "combine" queries all enabled providers in the fallback chain, deduplicates URLs, and ranks repeated results higher with a simple reciprocal-rank score.

Compatibility aliases

web_search accepts these argument aliases:

• maxResults → max_results
• provider: "ddg" → "duckduckgo"
• mode: "first-success" → "first_success"

web_read accepts:

• maxChars → max_chars

Security notes

This package intentionally avoids:

• postinstall, preinstall, prepare
• child_process
• eval / new Function
• shell-based credential resolution
• writes outside the project
• browser automation / JavaScript execution

Search queries are sent to the selected provider.

Brave API key

Brave keys are available from the Brave Search API dashboard:

https://api.search.brave.com/app/keys

After creating a key, export it before starting Pi:

export PI_WEB_SCOUT_BRAVE_API_KEY="..."

Then enable Brave in .pi/pi-web-scout.json:

{
  "fallbackChain": ["brave", "duckduckgo", "marginalia", "jina"],
  "providers": {
    "brave": { "enabled": true, "apiKeyEnv": "PI_WEB_SCOUT_BRAVE_API_KEY" }
  }
}