pi-web-scout 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-web-scout contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# pi-web-scout
+
+No-key web search extension for [Pi](https://pi.dev). 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.
+
+## Try locally
+
+```bash
+pi -e ./pi-web-scout
+```
+
+## Commands
+
+```text
+/web-scout-status
+```
+
+Shows active config and provider status.
+
+## Tool
+
+`web_search`
+
+```json
+{
+  "query": "latest TypeScript release notes",
+  "max_results": 5,
+  "provider": "auto",
+  "mode": "first_success"
+}
+```
+
+`web_read`
+
+```json
+{
+  "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`
+
+```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.
+
+## 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:
+
+```bash
+export PI_WEB_SCOUT_BRAVE_API_KEY="..."
+```
+
+Then enable Brave in `.pi/pi-web-scout.json`:
+
+```json
+{
+  "fallbackChain": ["brave", "duckduckgo", "marginalia", "jina"],
+  "providers": {
+    "brave": { "enabled": true, "apiKeyEnv": "PI_WEB_SCOUT_BRAVE_API_KEY" }
+  }
+}
+```

package/SECURITY.md

@@ -0,0 +1,49 @@
+# Security Policy
+
+`pi-web-scout` is a Pi extension. Pi extensions run with the user's local permissions, so review changes before installing or publishing.
+
+## Design constraints
+
+This package intentionally avoids:
+
+- npm lifecycle install scripts (`preinstall`, `install`, `postinstall`, `prepare`)
+- shell execution (`child_process`, `exec`, `spawn`)
+- `eval` / `new Function`
+- native runtime dependencies
+- browser automation / JavaScript execution
+- credential commands such as `!pass show ...`
+- reading SSH keys, cookies, keychains, `~/.config`, `~/.codex`, or `~/.pi` secrets
+- writing config/cache/state files at runtime
+
+## Network behavior
+
+Tools send user-provided search/read requests to selected providers:
+
+- DuckDuckGo HTML search
+- Marginalia public search
+- Jina search
+- Brave Search API only when explicitly enabled and keyed via env var
+- `web_read` fetches public HTTP(S) URLs supplied by the user/model
+
+## Credentials
+
+Keyed providers use environment variables only. Literal keys in config and shell commands are unsupported by design.
+
+Current keyed env var:
+
+```bash
+PI_WEB_SCOUT_BRAVE_API_KEY
+```
+
+## SSRF notes
+
+`web_read` blocks common local/private/metadata targets and validates every redirect hop. It does not perform custom DNS resolution, so DNS rebinding protection is best-effort.
+
+## Reporting
+
+Before reporting a vulnerability, please include:
+
+- package version / commit
+- minimal reproduction
+- affected tool or provider
+- expected vs actual behavior

package/index.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerWebSearchTool } from "./src/tool.ts";
+
+export default function piWebScoutExtension(pi: ExtensionAPI): void {
+  registerWebSearchTool(pi);
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "pi-web-scout",
+  "version": "0.1.0",
+  "description": "No-key web search extension for Pi, with provider architecture ready for keyed search APIs.",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": {
+      "import": "./index.ts",
+      "types": "./index.ts"
+    }
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "package.json",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "web-search",
+    "search"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/alcovegan/pi-web-scout.git"
+  },
+  "bugs": {
+    "url": "https://github.com/alcovegan/pi-web-scout/issues"
+  },
+  "homepage": "https://github.com/alcovegan/pi-web-scout#readme",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "check:safety": "node tests/safety.test.mjs",
+    "test": "node --experimental-strip-types --test tests/*.test.mjs"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  }
+}

package/src/config.ts

@@ -0,0 +1,112 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { PiWebSearchConfig, ProviderId, ResolvedConfig } from "./types.ts";
+import { clampInt } from "./safety.ts";
+
+const CONFIG_FILE = "pi-web-scout.json";
+const PROVIDERS = ["duckduckgo", "marginalia", "jina", "brave"] as const;
+
+const DEFAULT_CONFIG: ResolvedConfig = {
+  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" },
+  },
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isProviderId(value: unknown): value is ProviderId {
+  return value === "auto" || PROVIDERS.includes(value as never);
+}
+
+function isConcreteProvider(value: unknown): value is (typeof PROVIDERS)[number] {
+  return PROVIDERS.includes(value as never);
+}
+
+export function getConfigPath(cwd: string): string {
+  return join(cwd, ".pi", CONFIG_FILE);
+}
+
+export function loadConfig(cwd: string): ResolvedConfig {
+  const path = getConfigPath(cwd);
+  if (!existsSync(path)) return structuredClone(DEFAULT_CONFIG);
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf-8"));
+  } catch (error) {
+    throw new Error(`Invalid ${path}: ${(error as Error).message}`);
+  }
+  if (!isRecord(parsed)) throw new Error(`Invalid ${path}: expected a JSON object`);
+
+  validateConfigShape(parsed, path);
+  const user = parsed as PiWebSearchConfig;
+
+  const resolved = structuredClone(DEFAULT_CONFIG);
+  if (user.enabled !== undefined) resolved.enabled = user.enabled;
+  if (user.defaultProvider !== undefined) resolved.defaultProvider = user.defaultProvider;
+  if (user.maxResults !== undefined) resolved.maxResults = clampInt(user.maxResults, 5, 1, 20);
+
+  if (user.fallbackChain !== undefined) {
+    const chain = user.fallbackChain.filter(isConcreteProvider);
+    resolved.fallbackChain = [...new Set(chain)];
+  }
+
+  if (user.providers) {
+    for (const provider of PROVIDERS) {
+      const providerConfig = user.providers[provider];
+      if (providerConfig?.enabled !== undefined) resolved.providers[provider].enabled = providerConfig.enabled;
+      if (providerConfig?.apiKeyEnv !== undefined) resolved.providers[provider].apiKeyEnv = providerConfig.apiKeyEnv;
+    }
+  }
+
+  resolved.fallbackChain = resolved.fallbackChain.filter((p) => resolved.providers[p].enabled);
+  if (resolved.fallbackChain.length === 0) resolved.fallbackChain = ["duckduckgo"];
+  if (resolved.defaultProvider !== "auto" && !resolved.providers[resolved.defaultProvider].enabled) {
+    resolved.defaultProvider = "auto";
+  }
+  return resolved;
+}
+
+function validateConfigShape(config: Record<string, unknown>, path: string): void {
+  if (config.enabled !== undefined && typeof config.enabled !== "boolean") {
+    throw new Error(`Invalid ${path}: enabled must be boolean`);
+  }
+  if (config.defaultProvider !== undefined && !isProviderId(config.defaultProvider)) {
+    throw new Error(`Invalid ${path}: defaultProvider must be one of auto, ${PROVIDERS.join(", ")}`);
+  }
+  if (config.maxResults !== undefined) {
+    const n = Number(config.maxResults);
+    if (!Number.isFinite(n) || n < 1 || n > 20) {
+      throw new Error(`Invalid ${path}: maxResults must be a number from 1 to 20`);
+    }
+  }
+  if (config.fallbackChain !== undefined) {
+    if (!Array.isArray(config.fallbackChain)) throw new Error(`Invalid ${path}: fallbackChain must be an array`);
+    const invalid = config.fallbackChain.find((value) => !isConcreteProvider(value));
+    if (invalid !== undefined) throw new Error(`Invalid ${path}: unknown provider in fallbackChain: ${String(invalid)}`);
+  }
+  if (config.providers !== undefined) {
+    if (!isRecord(config.providers)) throw new Error(`Invalid ${path}: providers must be an object`);
+    for (const [name, value] of Object.entries(config.providers)) {
+      if (!isConcreteProvider(name)) throw new Error(`Invalid ${path}: unknown provider: ${name}`);
+      if (!isRecord(value)) throw new Error(`Invalid ${path}: providers.${name} must be an object`);
+      if (value.enabled !== undefined && typeof value.enabled !== "boolean") {
+        throw new Error(`Invalid ${path}: providers.${name}.enabled must be boolean`);
+      }
+      if (value.apiKeyEnv !== undefined) {
+        if (typeof value.apiKeyEnv !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(value.apiKeyEnv)) {
+          throw new Error(`Invalid ${path}: providers.${name}.apiKeyEnv must be an ALL_CAPS environment variable name`);
+        }
+      }
+    }
+  }
+}

package/src/credentials.ts

@@ -0,0 +1,36 @@
+import type { ResolvedProviderConfig, SearchProvider } from "./types.ts";
+
+const ENV_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
+
+export interface ResolvedCredential {
+  value?: string;
+  source?: string;
+  error?: string;
+}
+
+export function validateEnvName(name: string): boolean {
+  return ENV_NAME_PATTERN.test(name);
+}
+
+/**
+ * Resolve provider credentials from environment variables only.
+ *
+ * Deliberately unsupported:
+ * - literal keys in config
+ * - shell commands like !pass show ...
+ * - keychain/cookie/SSH/config-file discovery
+ */
+export function resolveProviderCredential(
+  provider: SearchProvider,
+  config: ResolvedProviderConfig,
+): ResolvedCredential {
+  if (!provider.requiresKey) return {};
+
+  const envName = config.apiKeyEnv ?? provider.defaultKeyEnv;
+  if (!envName) return { error: `${provider.id} requires an API key env var` };
+  if (!validateEnvName(envName)) return { error: `${provider.id} apiKeyEnv is not a valid environment variable name: ${envName}` };
+
+  const value = process.env[envName]?.trim();
+  if (!value) return { error: `${provider.id} requires ${envName} to be set` };
+  return { value, source: `env:${envName}` };
+}

package/src/format.ts

@@ -0,0 +1,36 @@
+import type { ProviderRunResult, SearchResult } from "./types.ts";
+
+export function formatSearchResults(
+  query: string,
+  results: SearchResult[],
+  providerLabel: string,
+  runs: ProviderRunResult[] = [],
+): string {
+  const safeQuery = query.replace(/[\r\n]+/g, " ").trim();
+  const lines = [`## Web search: ${safeQuery}`, `Provider: ${providerLabel}`, `Results: ${results.length}`];
+
+  if (runs.length > 0) {
+    lines.push("", "Provider runs:");
+    for (const run of runs) {
+      const status = run.error ? `failed: ${run.error}` : `${run.results.length} result${run.results.length === 1 ? "" : "s"}`;
+      lines.push(`- ${run.provider}: ${status}`);
+    }
+  }
+  lines.push("");
+
+  for (const [index, result] of results.entries()) {
+    lines.push(`### ${index + 1}. ${result.title || "Untitled"}`);
+    lines.push(result.url);
+    if (result.providers && result.providers.length > 1) lines.push(`Sources: ${result.providers.join(", ")}`);
+    else lines.push(`Source: ${result.provider}`);
+    if (result.snippet) lines.push(result.snippet);
+    lines.push("");
+  }
+
+  return lines.join("\n").trimEnd();
+}
+
+export function formatProviderErrors(errors: ProviderRunResult[]): string {
+  if (errors.length === 0) return "";
+  return errors.map((e) => `${e.provider}: ${e.error ?? "unknown error"}`).join("; ");
+}

package/src/providers/brave.ts

@@ -0,0 +1,53 @@
+import type { SearchProvider, SearchRequest, SearchResult } from "../types.ts";
+
+const ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
+const USER_AGENT = "pi-web-scout/0.1 (+https://pi.dev)";
+
+interface BraveItem {
+  title?: unknown;
+  url?: unknown;
+  description?: unknown;
+  age?: unknown;
+}
+
+export const braveProvider: SearchProvider = {
+  id: "brave",
+  label: "Brave Search API",
+  requiresKey: true,
+  defaultKeyEnv: "PI_WEB_SCOUT_BRAVE_API_KEY",
+  async search(request: SearchRequest): Promise<SearchResult[]> {
+    if (!request.apiKey) throw new Error("Brave API key is missing");
+
+    const url = new URL(ENDPOINT);
+    url.searchParams.set("q", request.query);
+    url.searchParams.set("count", String(Math.min(request.maxResults, 20)));
+
+    const response = await fetch(url.toString(), {
+      headers: {
+        "Accept": "application/json",
+        "Accept-Encoding": "gzip",
+        "User-Agent": USER_AGENT,
+        "X-Subscription-Token": request.apiKey,
+      },
+      signal: request.signal,
+    });
+
+    if (!response.ok) throw new Error(`Brave returned HTTP ${response.status}`);
+
+    const data = await response.json() as { web?: { results?: BraveItem[] } };
+    return (Array.isArray(data.web?.results) ? data.web.results : [])
+      .slice(0, request.maxResults)
+      .map((item, index) => ({
+        title: stringValue(item.title),
+        url: stringValue(item.url),
+        snippet: stringValue(item.description),
+        provider: "brave",
+        rank: index + 1,
+      }))
+      .filter((result) => result.title.length > 0 && result.url.length > 0);
+  },
+};
+
+function stringValue(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}

package/src/providers/duckduckgo.ts

@@ -0,0 +1,68 @@
+import type { SearchProvider, SearchRequest, SearchResult } from "../types.ts";
+import { stripTags } from "../safety.ts";
+
+const ENDPOINT = "https://html.duckduckgo.com/html/";
+const USER_AGENT = "pi-web-scout/0.1 (+https://pi.dev)";
+
+export const duckDuckGoProvider: SearchProvider = {
+  id: "duckduckgo",
+  label: "DuckDuckGo HTML",
+  requiresKey: false,
+  async search(request: SearchRequest): Promise<SearchResult[]> {
+    const params = new URLSearchParams({ q: request.query, no_redirect: "1" });
+    const response = await fetch(`${ENDPOINT}?${params.toString()}`, {
+      headers: {
+        "Accept": "text/html,application/xhtml+xml",
+        "User-Agent": USER_AGENT,
+      },
+      signal: request.signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(`DuckDuckGo returned HTTP ${response.status}`);
+    }
+
+    return parseDuckDuckGoHtml(await response.text(), request.maxResults);
+  },
+};
+
+export function parseDuckDuckGoHtml(html: string, maxResults: number): SearchResult[] {
+  const results: SearchResult[] = [];
+  const resultBlockRegex = /<div[^>]+class="[^"]*result[^"]*"[\s\S]*?(?=<div[^>]+class="[^"]*result[^"]*"|<\/body>|$)/gi;
+  let blockMatch: RegExpExecArray | null;
+
+  while ((blockMatch = resultBlockRegex.exec(html)) !== null && results.length < maxResults) {
+    const block = blockMatch[0];
+    const link = block.match(/<a[^>]+class="[^"]*result__a[^"]*"[^>]+href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/i);
+    if (!link) continue;
+
+    const rawUrl = decodeDuckDuckGoUrl(link[1] ?? "");
+    const title = stripTags(link[2] ?? "");
+    if (!rawUrl || !title) continue;
+
+    const snippetMatch = block.match(/<a[^>]+class="[^"]*result__snippet[^"]*"[^>]*>([\s\S]*?)<\/a>/i)
+      ?? block.match(/<td[^>]+class="[^"]*result__snippet[^"]*"[^>]*>([\s\S]*?)<\/td>/i);
+    const snippet = snippetMatch ? stripTags(snippetMatch[1] ?? "") : undefined;
+
+    results.push({
+      title,
+      url: rawUrl,
+      snippet,
+      provider: "duckduckgo",
+      rank: results.length + 1,
+    });
+  }
+
+  return results;
+}
+
+function decodeDuckDuckGoUrl(url: string): string {
+  const decoded = stripTags(url);
+  try {
+    const parsed = new URL(decoded, "https://duckduckgo.com");
+    const uddg = parsed.searchParams.get("uddg");
+    return uddg ? decodeURIComponent(uddg) : parsed.toString();
+  } catch {
+    return decoded;
+  }
+}

package/src/providers/jina.ts

@@ -0,0 +1,54 @@
+import type { SearchProvider, SearchRequest, SearchResult } from "../types.ts";
+
+const ENDPOINT = "https://s.jina.ai/";
+const USER_AGENT = "pi-web-scout/0.1 (+https://pi.dev)";
+
+interface JinaItem {
+  title?: unknown;
+  url?: unknown;
+  content?: unknown;
+  description?: unknown;
+}
+
+export const jinaProvider: SearchProvider = {
+  id: "jina",
+  label: "Jina Search",
+  requiresKey: false,
+  async search(request: SearchRequest): Promise<SearchResult[]> {
+    const url = new URL(ENDPOINT);
+    url.searchParams.set("q", request.query);
+    url.searchParams.set("format", "json");
+
+    const response = await fetch(url.toString(), {
+      headers: {
+        "Accept": "application/json",
+        "User-Agent": USER_AGENT,
+      },
+      signal: request.signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(`Jina returned HTTP ${response.status}`);
+    }
+
+    return parseJinaResponse(await response.json(), request.maxResults);
+  },
+};
+
+export function parseJinaResponse(data: unknown, maxResults: number): SearchResult[] {
+  const payload = data as { data?: JinaItem[] };
+  return (Array.isArray(payload.data) ? payload.data : [])
+    .slice(0, maxResults)
+    .map((item, index) => ({
+      title: stringValue(item.title) || stringValue(item.url),
+      url: stringValue(item.url),
+      snippet: (stringValue(item.content) || stringValue(item.description)).slice(0, 700),
+      provider: "jina",
+      rank: index + 1,
+    }))
+    .filter((result) => result.title.length > 0 && result.url.length > 0);
+}
+
+function stringValue(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}

package/src/providers/marginalia.ts

@@ -0,0 +1,51 @@
+import type { SearchProvider, SearchRequest, SearchResult } from "../types.ts";
+
+const BASE_URL = "https://api.marginalia.nu/public/search";
+const USER_AGENT = "pi-web-scout/0.1 (+https://pi.dev)";
+
+interface MarginaliaItem {
+  title?: unknown;
+  url?: unknown;
+  description?: unknown;
+}
+
+export const marginaliaProvider: SearchProvider = {
+  id: "marginalia",
+  label: "Marginalia Search",
+  requiresKey: false,
+  async search(request: SearchRequest): Promise<SearchResult[]> {
+    const count = Math.min(request.maxResults, 20);
+    const endpoint = `${BASE_URL}/${encodeURIComponent(request.query)}?index=0&count=${count}`;
+    const response = await fetch(endpoint, {
+      headers: {
+        "Accept": "application/json",
+        "User-Agent": USER_AGENT,
+      },
+      signal: request.signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(`Marginalia returned HTTP ${response.status}`);
+    }
+
+    return parseMarginaliaResponse(await response.json(), request.maxResults);
+  },
+};
+
+export function parseMarginaliaResponse(data: unknown, maxResults: number): SearchResult[] {
+  const payload = data as { results?: MarginaliaItem[] };
+  return (Array.isArray(payload.results) ? payload.results : [])
+    .slice(0, maxResults)
+    .map((item, index) => ({
+      title: stringValue(item.title),
+      url: stringValue(item.url),
+      snippet: stringValue(item.description),
+      provider: "marginalia",
+      rank: index + 1,
+    }))
+    .filter((result) => result.title.length > 0 && result.url.length > 0);
+}
+
+function stringValue(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}

package/src/providers/registry.ts

@@ -0,0 +1,20 @@
+import type { ProviderId, SearchProvider } from "../types.ts";
+import { braveProvider } from "./brave.ts";
+import { duckDuckGoProvider } from "./duckduckgo.ts";
+import { jinaProvider } from "./jina.ts";
+import { marginaliaProvider } from "./marginalia.ts";
+
+const providers = new Map<string, SearchProvider>([
+  [duckDuckGoProvider.id, duckDuckGoProvider],
+  [marginaliaProvider.id, marginaliaProvider],
+  [jinaProvider.id, jinaProvider],
+  [braveProvider.id, braveProvider],
+]);
+
+export function getProvider(id: Exclude<ProviderId, "auto">): SearchProvider | undefined {
+  return providers.get(id);
+}
+
+export function listProviders(): SearchProvider[] {
+  return [...providers.values()];
+}

package/src/read.ts

@@ -0,0 +1,102 @@
+import { clampInt, sanitizeError } from "./safety.ts";
+import { validatePublicHttpUrl } from "./url-safety.ts";
+import { extractReadableText } from "./readability.ts";
+
+const MAX_REDIRECTS = 8;
+const MAX_BYTES = 1_000_000;
+const DEFAULT_TIMEOUT_MS = 15_000;
+const USER_AGENT = "pi-web-scout/0.1 (+https://pi.dev)";
+
+export interface WebReadOptions {
+  url: string;
+  maxChars?: number;
+  signal?: AbortSignal;
+}
+
+export interface WebReadResult {
+  requestedUrl: string;
+  finalUrl: string;
+  title?: string;
+  contentType: string;
+  status: number;
+  text: string;
+  truncated: boolean;
+  bytesRead: number;
+}
+
+export async function readWebPage(options: WebReadOptions): Promise<WebReadResult> {
+  const maxChars = clampInt(options.maxChars, 12_000, 1_000, 50_000);
+  return await fetchWithRedirects(options.url, maxChars, options.signal, 0, new Set());
+}
+
+async function fetchWithRedirects(
+  url: string,
+  maxChars: number,
+  signal: AbortSignal | undefined,
+  depth: number,
+  seen: Set<string>,
+): Promise<WebReadResult> {
+  const validation = validatePublicHttpUrl(url);
+  if (!validation.valid || !validation.url) throw new Error(`URL blocked: ${validation.reason ?? "invalid URL"}`);
+  const normalized = validation.url.toString();
+  if (seen.has(normalized)) throw new Error("redirect loop detected");
+  if (depth > MAX_REDIRECTS) throw new Error(`too many redirects (>${MAX_REDIRECTS})`);
+  seen.add(normalized);
+
+  const timeout = AbortSignal.timeout(DEFAULT_TIMEOUT_MS);
+  const combinedSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
+
+  const response = await fetch(normalized, {
+    redirect: "manual",
+    signal: combinedSignal,
+    headers: {
+      "Accept": "text/html,application/xhtml+xml,text/plain,application/json;q=0.8,*/*;q=0.1",
+      "Accept-Encoding": "gzip, deflate",
+      "User-Agent": USER_AGENT,
+    },
+  });
+
+  if (response.status >= 300 && response.status < 400) {
+    const location = response.headers.get("location");
+    if (!location) throw new Error(`redirect without location: HTTP ${response.status}`);
+    return await fetchWithRedirects(new URL(location, normalized).toString(), maxChars, signal, depth + 1, seen);
+  }
+
+  if (!response.ok) throw new Error(`fetch failed: HTTP ${response.status}`);
+
+  const contentType = response.headers.get("content-type") ?? "text/plain";
+  const { text: raw, bytesRead } = await readLimitedBody(response);
+  const extracted = extractReadableText(raw, contentType);
+  const truncated = extracted.text.length > maxChars;
+  const text = truncated ? `${extracted.text.slice(0, maxChars)}\n\n[... truncated at ${maxChars} chars ...]` : extracted.text;
+
+  return {
+    requestedUrl: url,
+    finalUrl: response.url || normalized,
+    title: extracted.title,
+    contentType,
+    status: response.status,
+    text,
+    truncated,
+    bytesRead,
+  };
+}
+
+async function readLimitedBody(response: Response): Promise<{ text: string; bytesRead: number }> {
+  const reader = response.body?.getReader();
+  if (!reader) return { text: await response.text().catch((error) => sanitizeError(error)), bytesRead: 0 };
+
+  const decoder = new TextDecoder();
+  let text = "";
+  let bytesRead = 0;
+  while (bytesRead < MAX_BYTES) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    bytesRead += value.byteLength;
+    text += decoder.decode(value, { stream: true });
+  }
+  await reader.cancel().catch(() => undefined);
+  text += decoder.decode();
+  if (bytesRead >= MAX_BYTES) text += "\n[... response body truncated at 1MB ...]";
+  return { text, bytesRead };
+}

package/src/readability.ts

@@ -0,0 +1,58 @@
+import { decodeHtml, stripTags } from "./safety.ts";
+
+export interface ExtractedPage {
+  title?: string;
+  text: string;
+}
+
+export function extractReadableText(content: string, contentType: string): ExtractedPage {
+  if (!/html|xml/i.test(contentType)) {
+    return { text: normalizeWhitespace(content) };
+  }
+
+  const title = extractTitle(content);
+  let html = content
+    .replace(/<script\b[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style\b[\s\S]*?<\/style>/gi, " ")
+    .replace(/<noscript\b[\s\S]*?<\/noscript>/gi, " ")
+    .replace(/<svg\b[\s\S]*?<\/svg>/gi, " ")
+    .replace(/<nav\b[\s\S]*?<\/nav>/gi, " ")
+    .replace(/<footer\b[\s\S]*?<\/footer>/gi, " ")
+    .replace(/<header\b[\s\S]*?<\/header>/gi, " ")
+    .replace(/<(br|p|div|section|article|li|tr|h[1-6])\b[^>]*>/gi, "\n")
+    .replace(/<\/((p|div|section|article|li|tr|h[1-6]))>/gi, "\n");
+
+  const main = pickMainContent(html);
+  return { title, text: normalizeWhitespace(stripTags(main)) };
+}
+
+function extractTitle(html: string): string | undefined {
+  const match = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+  const title = match ? normalizeWhitespace(decodeHtml(stripTags(match[1] ?? ""))) : "";
+  return title || undefined;
+}
+
+function pickMainContent(html: string): string {
+  const candidates = [
+    /<main\b[^>]*>([\s\S]*?)<\/main>/i,
+    /<article\b[^>]*>([\s\S]*?)<\/article>/i,
+    /<body\b[^>]*>([\s\S]*?)<\/body>/i,
+  ];
+  for (const pattern of candidates) {
+    const match = html.match(pattern);
+    if (match?.[1] && stripTags(match[1]).length > 200) return match[1];
+  }
+  return html;
+}
+
+function normalizeWhitespace(text: string): string {
+  return text
+    .replace(/\r/g, "")
+    .replace(/[ \t]+/g, " ")
+    .replace(/\n{3,}/g, "\n\n")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line, index, lines) => line || lines[index - 1])
+    .join("\n")
+    .trim();
+}

package/src/safety.ts

@@ -0,0 +1,47 @@
+const SECRET_PATTERNS: RegExp[] = [
+  /(authorization|x-api-key|api[-_]?key|token|secret|password)["']?\s*[:=]\s*["']?[^\s"']{8,}/gi,
+  /(bearer|token)\s+[a-z0-9._\/-]{8,}/gi,
+];
+
+export function sanitizeError(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  let safe = message.slice(0, 500);
+  for (const pattern of SECRET_PATTERNS) safe = safe.replace(pattern, "$1 [redacted]");
+  return safe;
+}
+
+export function clampInt(value: unknown, fallback: number, min: number, max: number): number {
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(n)));
+}
+
+export function normalizeUrlForDedupe(url: string): string {
+  try {
+    const parsed = new URL(url);
+    parsed.hash = "";
+    if (parsed.pathname.endsWith("/") && parsed.pathname.length > 1) {
+      parsed.pathname = parsed.pathname.replace(/\/+$/, "");
+    }
+    return parsed.toString().toLowerCase();
+  } catch {
+    return url.trim().toLowerCase();
+  }
+}
+
+export function decodeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&#x27;/g, "'")
+    .replace(/&#x2F;/g, "/")
+    .replace(/&#(\d+);/g, (_m, code) => String.fromCharCode(Number(code)))
+    .replace(/&#x([0-9a-f]+);/gi, (_m, code) => String.fromCharCode(parseInt(code, 16)));
+}
+
+export function stripTags(html: string): string {
+  return decodeHtml(html.replace(/<[^>]*>/g, " ")).replace(/\s+/g, " ").trim();
+}

package/src/tool.ts

@@ -0,0 +1,249 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import { getConfigPath, loadConfig } from "./config.ts";
+import { resolveProviderCredential } from "./credentials.ts";
+import { formatProviderErrors, formatSearchResults } from "./format.ts";
+import { getProvider, listProviders } from "./providers/registry.ts";
+import { readWebPage } from "./read.ts";
+import { clampInt, normalizeUrlForDedupe, sanitizeError } from "./safety.ts";
+import type { ProviderId, ProviderRunResult, ResolvedConfig, SearchMode, SearchResult } from "./types.ts";
+
+const PROVIDERS = ["auto", "duckduckgo", "marginalia", "jina", "brave"] as const;
+const MODES = ["first_success", "combine"] as const;
+
+export function registerWebSearchTool(pi: ExtensionAPI): void {
+  registerStatusCommand(pi);
+
+  pi.registerTool({
+    name: "web_search",
+    label: "Web Scout Search",
+    description:
+      "Search the web using no-key search providers. Defaults to DuckDuckGo HTML and is architected for future keyed providers.",
+    promptSnippet: "web_search: search the public web without requiring API keys.",
+    promptGuidelines: [
+      "Use web_search when current or source-backed information is needed.",
+      "Prefer web_search over guessing facts that may have changed recently.",
+      "Use web_search with mode=combine when broad coverage matters more than speed.",
+    ],
+    parameters: Type.Object({
+      query: Type.String({ description: "Search query" }),
+      max_results: Type.Optional(Type.Number({ description: "Number of results, 1-20. Default comes from config or 5." })),
+      provider: Type.Optional(StringEnum(PROVIDERS, { description: "Search provider. Use auto unless a provider is requested." })),
+      mode: Type.Optional(StringEnum(MODES, { description: "first_success uses fallback order; combine merges enabled providers." })),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const config = loadConfig(ctx.cwd);
+      if (!config.enabled) throw new Error("pi-web-scout is disabled in .pi/pi-web-scout.json");
+
+      const query = String(params.query ?? "").trim();
+      if (!query) throw new Error("query must be non-empty");
+
+      const maxResults = clampInt(params.max_results, config.maxResults, 1, 20);
+      const provider = (params.provider ?? config.defaultProvider) as ProviderId;
+      const mode = (params.mode ?? "first_success") as SearchMode;
+      if (provider !== "auto" && !config.providers[provider].enabled) {
+        throw new Error(`Provider ${provider} is disabled in .pi/pi-web-scout.json`);
+      }
+
+      const providerIds = provider === "auto" ? config.fallbackChain : [provider];
+      const runResult = mode === "combine" && provider === "auto"
+        ? await runCombined(providerIds, query, maxResults, signal, config)
+        : await runFirstSuccess(providerIds, query, maxResults, signal, config);
+
+      if (runResult.results.length === 0) {
+        const errors = formatProviderErrors(runResult.runs.filter((r) => r.error));
+        throw new Error(errors ? `No web search results. Provider errors: ${errors}` : "No web search results.");
+      }
+
+      return {
+        content: [{ type: "text", text: formatSearchResults(query, runResult.results, runResult.providerLabel, runResult.runs) }],
+        details: {
+          query,
+          provider: runResult.provider,
+          providerLabel: runResult.providerLabel,
+          mode,
+          resultCount: runResult.results.length,
+          runs: runResult.runs.map((run) => ({
+            provider: run.provider,
+            resultCount: run.results.length,
+            error: run.error,
+          })),
+          results: runResult.results,
+        },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "web_read",
+    label: "Web Read",
+    description: "Fetch a public HTTP(S) URL and extract readable text with SSRF protection. No browser or JavaScript execution.",
+    promptSnippet: "web_read: read and extract text from a specific public URL.",
+    promptGuidelines: [
+      "Use web_read after web_search when snippets are insufficient and a source needs to be read.",
+      "Do not use web_read for localhost, private network, or metadata URLs; those are blocked.",
+    ],
+    parameters: Type.Object({
+      url: Type.String({ description: "Public HTTP(S) URL to read" }),
+      max_chars: Type.Optional(Type.Number({ description: "Maximum extracted characters, 1000-50000. Default 12000." })),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const url = String(params.url ?? "").trim();
+      if (!url) throw new Error("url must be non-empty");
+      const result = await readWebPage({ url, maxChars: params.max_chars, signal });
+      const header = [
+        `# ${result.title || "Web page"}`,
+        `URL: ${result.finalUrl}`,
+        `Status: HTTP ${result.status}`,
+        `Content-Type: ${result.contentType}`,
+        result.truncated ? "Truncated: yes" : "Truncated: no",
+        "",
+      ].join("\n");
+      return {
+        content: [{ type: "text", text: header + result.text }],
+        details: result,
+      };
+    },
+  });
+}
+
+function registerStatusCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("web-scout-status", {
+    description: "Show pi-web-scout configuration and provider status.",
+    handler: async (_args, ctx) => {
+      try {
+        const config = loadConfig(ctx.cwd);
+        const lines = [
+          "pi-web-scout status",
+          `config: ${getConfigPath(ctx.cwd)}`,
+          `enabled: ${config.enabled}`,
+          `defaultProvider: ${config.defaultProvider}`,
+          `fallbackChain: ${config.fallbackChain.join(", ")}`,
+          `maxResults: ${config.maxResults}`,
+          "",
+          "providers:",
+        ];
+        for (const provider of listProviders()) {
+          const enabled = config.providers[provider.id].enabled;
+          const providerConfig = config.providers[provider.id];
+          const credential = resolveProviderCredential(provider, providerConfig);
+          const key = provider.requiresKey
+            ? credential.value
+              ? `key ${credential.source}`
+              : `key missing (${credential.error ?? "not configured"})`
+            : "no key";
+          lines.push(`- ${provider.id}: ${enabled ? "enabled" : "disabled"}, ${key}, ${provider.label}`);
+        }
+        ctx.ui.notify(lines.join("\n"), "info");
+      } catch (error) {
+        ctx.ui.notify(sanitizeError(error), "error");
+      }
+    },
+  });
+}
+
+async function runFirstSuccess(
+  providerIds: string[],
+  query: string,
+  maxResults: number,
+  signal: AbortSignal | undefined,
+  config: ResolvedConfig,
+): Promise<{ provider: string; providerLabel: string; results: SearchResult[]; runs: ProviderRunResult[] }> {
+  const runs: ProviderRunResult[] = [];
+
+  for (const providerId of providerIds) {
+    const provider = getProvider(providerId as never);
+    if (!provider) {
+      runs.push({ provider: providerId, results: [], error: "unknown provider" });
+      continue;
+    }
+
+    try {
+      const providerConfig = config.providers[provider.id];
+      const credential = resolveProviderCredential(provider, providerConfig);
+      if (provider.requiresKey && !credential.value) {
+        runs.push({ provider: provider.id, results: [], error: credential.error ?? "missing API key" });
+        continue;
+      }
+      const results = await withTimeoutSignal(signal, 15_000, (combinedSignal) =>
+        provider.search({ query, maxResults, signal: combinedSignal, apiKey: credential.value })
+      );
+      runs.push({ provider: provider.id, results, keySource: credential.source });
+      if (results.length > 0) return { provider: provider.id, providerLabel: provider.label, results, runs };
+    } catch (error) {
+      runs.push({ provider: provider.id, results: [], error: sanitizeError(error) });
+    }
+  }
+
+  return { provider: "none", providerLabel: "none", results: [], runs };
+}
+
+async function runCombined(
+  providerIds: string[],
+  query: string,
+  maxResults: number,
+  signal: AbortSignal | undefined,
+  config: ResolvedConfig,
+): Promise<{ provider: string; providerLabel: string; results: SearchResult[]; runs: ProviderRunResult[] }> {
+  const runs = await Promise.all(providerIds.map(async (providerId): Promise<ProviderRunResult> => {
+    const provider = getProvider(providerId as never);
+    if (!provider) return { provider: providerId, results: [], error: "unknown provider" };
+    try {
+      const providerConfig = config.providers[provider.id];
+      const credential = resolveProviderCredential(provider, providerConfig);
+      if (provider.requiresKey && !credential.value) return { provider: provider.id, results: [], error: credential.error ?? "missing API key" };
+      const results = await withTimeoutSignal(signal, 15_000, (combinedSignal) =>
+        provider.search({ query, maxResults, signal: combinedSignal, apiKey: credential.value })
+      );
+      return { provider: provider.id, results, keySource: credential.source };
+    } catch (error) {
+      return { provider: provider.id, results: [], error: sanitizeError(error) };
+    }
+  }));
+
+  return {
+    provider: "combined",
+    providerLabel: "combined",
+    results: combineResults(runs).slice(0, maxResults),
+    runs,
+  };
+}
+
+function combineResults(runs: ProviderRunResult[]): SearchResult[] {
+  const byUrl = new Map<string, { result: SearchResult; providers: Set<string>; score: number }>();
+  for (const run of runs) {
+    for (const result of run.results) {
+      const key = normalizeUrlForDedupe(result.url);
+      const contribution = 1 / (60 + Math.max(1, result.rank));
+      const existing = byUrl.get(key);
+      if (!existing) {
+        byUrl.set(key, { result, providers: new Set([run.provider]), score: contribution });
+        continue;
+      }
+      existing.providers.add(run.provider);
+      existing.score += contribution;
+      if ((result.snippet?.length ?? 0) > (existing.result.snippet?.length ?? 0)) existing.result = result;
+    }
+  }
+
+  return [...byUrl.values()]
+    .sort((a, b) => (b.score - a.score) || (b.providers.size - a.providers.size))
+    .map((entry, index) => ({
+      ...entry.result,
+      rank: index + 1,
+      provider: [...entry.providers][0] ?? entry.result.provider,
+      providers: [...entry.providers].sort(),
+      score: Number(entry.score.toFixed(6)),
+    }));
+}
+
+async function withTimeoutSignal<T>(
+  signal: AbortSignal | undefined,
+  timeoutMs: number,
+  fn: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  const combined = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+  return await fn(combined);
+}

package/src/types.ts

@@ -0,0 +1,65 @@
+export type ProviderId = "auto" | "duckduckgo" | "marginalia" | "jina" | "brave";
+
+export type SearchMode = "first_success" | "combine";
+
+export interface SearchResult {
+  title: string;
+  url: string;
+  snippet?: string;
+  provider: string;
+  rank: number;
+  /** Providers that returned this URL in combine mode. */
+  providers?: string[];
+  /** Internal combine score, exposed in details for diagnostics. */
+  score?: number;
+}
+
+export interface SearchRequest {
+  query: string;
+  maxResults: number;
+  signal?: AbortSignal;
+  /** Resolved provider API key. Present only for keyed providers. */
+  apiKey?: string;
+}
+
+export interface ProviderRunResult {
+  provider: string;
+  results: SearchResult[];
+  error?: string;
+  keySource?: string;
+}
+
+export interface SearchProvider {
+  id: Exclude<ProviderId, "auto">;
+  label: string;
+  requiresKey: boolean;
+  defaultKeyEnv?: string;
+  search(request: SearchRequest): Promise<SearchResult[]>;
+}
+
+export interface ProviderConfig {
+  enabled?: boolean;
+  /** Environment variable name only. Literal keys and shell commands are intentionally unsupported. */
+  apiKeyEnv?: string;
+}
+
+export interface ResolvedProviderConfig {
+  enabled: boolean;
+  apiKeyEnv?: string;
+}
+
+export interface PiWebSearchConfig {
+  enabled?: boolean;
+  defaultProvider?: ProviderId;
+  fallbackChain?: Array<Exclude<ProviderId, "auto">>;
+  maxResults?: number;
+  providers?: Partial<Record<Exclude<ProviderId, "auto">, ProviderConfig>>;
+}
+
+export interface ResolvedConfig {
+  enabled: boolean;
+  defaultProvider: ProviderId;
+  fallbackChain: Array<Exclude<ProviderId, "auto">>;
+  maxResults: number;
+  providers: Record<Exclude<ProviderId, "auto">, ResolvedProviderConfig>;
+}

package/src/url-safety.ts

@@ -0,0 +1,60 @@
+const BLOCKED_HOSTNAMES = new Set([
+  "localhost",
+  "127.0.0.1",
+  "0.0.0.0",
+  "::1",
+  "[::1]",
+  "metadata.google.internal",
+  "metadata.azure.com",
+  "169.254.169.254",
+  "100.100.100.200",
+]);
+
+export interface UrlValidationResult {
+  valid: boolean;
+  url?: URL;
+  reason?: string;
+}
+
+export function validatePublicHttpUrl(input: string): UrlValidationResult {
+  let parsed: URL;
+  try {
+    parsed = new URL(input);
+  } catch {
+    return { valid: false, reason: "invalid URL" };
+  }
+
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return { valid: false, reason: `disallowed URL scheme: ${parsed.protocol}` };
+  }
+
+  const hostname = parsed.hostname.toLowerCase();
+  if (BLOCKED_HOSTNAMES.has(hostname)) return { valid: false, reason: `blocked hostname: ${hostname}` };
+  if (isBlockedIpv4(hostname)) return { valid: false, reason: `blocked IP address: ${hostname}` };
+  if (isBlockedIpv6(hostname)) return { valid: false, reason: `blocked IPv6 address: ${hostname}` };
+  if (/^\d+$/.test(hostname)) return { valid: false, reason: "numeric hostnames are not allowed" };
+
+  return { valid: true, url: parsed };
+}
+
+function isBlockedIpv4(hostname: string): boolean {
+  if (!/^(\d{1,3}\.){3}\d{1,3}$/.test(hostname)) return false;
+  const octets = hostname.split(".").map(Number);
+  if (octets.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return true;
+  const [a, b] = octets as [number, number, number, number];
+  return (
+    a === 0 ||
+    a === 10 ||
+    a === 127 ||
+    (a === 169 && b === 254) ||
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 168) ||
+    (a === 100 && b >= 64 && b <= 127) ||
+    a >= 224
+  );
+}
+
+function isBlockedIpv6(hostname: string): boolean {
+  const host = hostname.replace(/^\[/, "").replace(/\]$/, "");
+  return host === "::1" || host.startsWith("fe80:") || host.startsWith("fc") || host.startsWith("fd");
+}