pi-web-search 1.2.0 → 1.3.0

package/README.md

@@ -1,95 +1,59 @@
 # pi-web-search
 
-A pi extension that provides provider-native web search across Google Gemini, OpenAI, and Anthropic, plus Gemini-native URL Context analysis.
+Provider-native web search for [pi](https://github.com/earendil-works/pi-coding-agent), across Google Gemini, OpenAI, and Anthropic, plus Gemini-only URL Context analysis.
 
-## Features
+## Tools
 
-- **🔍 Web Search** - Provider-native web search across Google Gemini, OpenAI Responses, and Anthropic Messages
-- **📄 URL Context** - Gemini-native analysis of up to 20 public URLs, including web pages, documents, images, and YouTube videos
-- **🧾 Search telemetry** - Tool results include provider, search queries, result URLs, citations, and whether native search metadata was actually observed
-- **🔗 Canonicalized Google grounding links** - Gemini grounding redirect URLs are resolved to their underlying destination URLs when possible
+### `web_search`
 
-## Installation
+Search the web using your currently selected model. Automatically picks the right provider API:
 
-```bash
-pi install npm:pi-web-search
-```
-
-## Release highlights for v1.2.0
-
-- `web_search` now follows the current model across Google Gemini, OpenAI Responses, and Anthropic Messages
-- `url_context` is explicitly Gemini-only and is removed from the active tool set for non-Gemini models
-- Provider-native search telemetry now exposes queries, URLs, citations, and verification metadata in tool `details`
-- Gemini grounding redirect URLs are resolved to canonical destination URLs when possible
-- Real test scripts now read configuration from `.env` / `.env.example`
-- The package now ships source-only TypeScript entrypoints for pi; no `dist/` build output is required in the project or published package
-
-## Behavior notes
-
-- `web_search` follows the **currently selected model** when that model exposes a supported native search API.
-- `web_search` supports Google Gemini, OpenAI Responses, Anthropic Messages, and compatible proxy providers exposing those APIs.
-- `url_context` is intentionally **Gemini-only**. When the current model is not Gemini-compatible, the extension removes `url_context` from the active tool set and the executor also fast-fails with a clear unsupported-provider message as a second safety net.
-- If `web_search` returns only plain text and does **not** return native search metadata, the tool output includes a warning and marks the result as ungrounded in `details`.
-- If `url_context` does not return verified URL-context metadata, the tool output includes an explicit warning so the caller can distinguish a best-effort summary from a verified retrieval.
-- For Gemini grounding results, the extension attempts to resolve Google redirect URLs to the final destination URL before returning `sources` / `searchResults`.
-
-## Tool matrix
+| Provider | API |
+|---|---|
+| Google Gemini | Grounding with Google Search |
+| OpenAI | Responses API web search |
+| Anthropic | Messages API web search |
 
-| Tool | Google Gemini | OpenAI Responses | Anthropic Messages | Proxy providers exposing those APIs |
-|---|---|---|---|---|
-| `web_search` | ✅ | ✅ | ✅ | ✅ |
-| `url_context` | ✅ | ❌ | ❌ | ✅, but only when the selected model is Gemini-compatible |
+Supports passing up to 20 additional URLs to analyze alongside the query.
 
-## Configuration
+### `url_context`
 
-No special configuration required. Configure or login to any of the following model providers in pi, and it will be automatically detected and used:
+Gemini-only. Analyze up to 20 public URLs — web pages, documents, images, and YouTube videos. Uses Gemini's native URL Context retrieval with verified metadata.
 
-### For `web_search`
+When using `google-generative-ai`, YouTube URLs are passed as `file_data` for native video understanding.
 
-- google
-- google-generative-ai
-- openai
-- anthropic
-- compatible proxy providers whose selected model API is OpenAI Responses, Anthropic Messages, or Google Generative AI
+## Install
 
-### For `url_context`
+```bash
+pi install npm:pi-web-search
+```
 
-- google
-- google-generative-ai
-- compatible proxy providers whose selected model API is Google Generative AI
+## Usage
 
-## Verification scripts
+No extra config needed. Select a supported current model in pi and the tools auto-detect the matching provider API.
 
-Create a local `.env` first, ideally by copying `.env.example`. Real-test scripts read all configuration from environment variables instead of hardcoding any provider or extension.
+`web_search` will not scan configured models and pick one automatically when the current model does not support native search. To use a dedicated search model, opt in explicitly with `~/.pi/agent/web-search.json`:
 
-```bash
-# Mock/unit parsing tests
-npm test
+```json
+{
+  "provider": "openai",
+  "model": "gpt-5.1"
+}
+```
 
-# Real multi-provider web_search verification using models from .env
-node tests/real-web-search.mjs
+When this file exists, `web_search` uses the configured provider/model first. If it is missing, `web_search` uses the current conversation model. If the selected model does not support native search, the tool returns an error instead of falling back.
 
-# Real Gemini url_context verification using model from .env
-# Passes when url_context either returns verified metadata/URLs
-# or emits the explicit unverified-warning path.
-node tests/real-url-context.mjs
-```
+`url_context` is automatically removed from active tools when using a non-Gemini model.
 
-Example `.env` keys:
+## Test
 
 ```bash
-PI_BIN=pi
-PI_WEB_SEARCH_EXTENSION=./src/index.ts
-PI_PROVIDER_EXTENSIONS=/path/to/provider-extension.ts
-PI_WEB_SEARCH_MODEL_OPENAI=provider/model-openai
-PI_WEB_SEARCH_MODEL_ANTHROPIC=provider/model-anthropic
-PI_WEB_SEARCH_MODEL_GOOGLE=provider/model-google
-PI_URL_CONTEXT_MODEL=provider/model-google
+cp .env.example .env   # edit with your models
+npm test               # unit tests
+npm run test:real:web-search
+npm run test:real:url-context
 ```
 
-Recommended setup:
+## License
 
-```bash
-cp .env.example .env
-# then edit .env with models/extensions available in your local pi setup
-```
+MIT

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "pi-web-search",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Provider-native web search for pi across Google Gemini, OpenAI, and Anthropic, plus Gemini URL Context",
   "type": "module",
   "main": "src/index.ts",
   "keywords": [
     "pi",
     "pi-extension",
+    "pi-package",
     "web-search",
     "gemini",
     "google",
@@ -38,13 +39,18 @@
   "devDependencies": {
     "@earendil-works/pi-ai": "^0.75.4",
     "@earendil-works/pi-coding-agent": "^0.75.4",
-    "@sinclair/typebox": "^0.34.49",
     "@types/node": "^25.9.1",
+    "typebox": "^1.1.38",
     "typescript": "^6.0.3"
   },
   "pi": {
     "extensions": [
       "./src/index.ts"
     ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
   }
 }

package/src/index.ts

@@ -77,7 +77,6 @@ export default function (pi: ExtensionAPI) {
 
     const toolManager = createModelScopedToolManager(pi);
     pi.on("session_start", (_event, ctx) => toolManager.sync(ctx.model));
-    pi.on("session_switch", (_event, ctx) => toolManager.sync(ctx.model));
     pi.on("session_tree", (_event, ctx) => toolManager.sync(ctx.model));
     pi.on("model_select", (event) => toolManager.sync(event.model));
 }

package/src/url_context.ts

@@ -1,5 +1,5 @@
 import type { ExtensionContext, AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
-import { Type, type Static } from "@sinclair/typebox";
+import { Type, type Static } from "typebox";
 import { callApiStream, getConfig, applyCitations } from "./api.ts";
 import { getModel, missingConfigResult, errorResult, formatResult } from "./utils.ts";
 

package/src/utils.ts

@@ -1,6 +1,9 @@
 import type { ExtensionContext, AgentToolResult } from "@earendil-works/pi-coding-agent";
 import { type Model } from "@earendil-works/pi-ai";
 import { truncateHead, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { getProviderKind } from "./api.ts";
 
 // --- Formatting ---
@@ -15,63 +18,170 @@ export function formatResult(text: string, details: any): AgentToolResult<any> {
 
 // --- Model Selection ---
 
+const SUPPORTED_PROVIDERS = ["google-generative-ai", "openai-responses", "anthropic-messages"];
+const WEB_SEARCH_CONFIG_PATH = join(homedir(), ".pi", "agent", "web-search.json");
+
+type WebSearchModelConfig =
+    | { status: "missing"; path: string; }
+    | { status: "configured"; path: string; provider: string; modelId: string; }
+    | { status: "invalid"; path: string; error: string; };
+
 function isSupportedSearchModel(model: Model<any> | undefined): model is Model<any> {
     if (!model) return false;
     return getProviderKind(model) !== "unsupported";
 }
 
-function providerPriority(model: Model<any>): number {
-    const priorities = [
-        "google",
-        "google-generative-ai",
-        "openai",
-        "anthropic",
-    ];
-    const providerIndex = priorities.indexOf(model.provider);
-    if (providerIndex >= 0) return providerIndex;
-    return priorities.length;
+function describeModel(model: Model<any>): string {
+    return `${model.id} (${model.provider}/${model.api})`;
 }
 
-function modelPriority(model: Model<any>): number {
-    const id = model.id;
-    const patterns = [
-        /gemini-3.*flash/i,
-        /gemini-2\.5.*flash/i,
-        /gemini-2\.0.*flash/i,
-        /gemini.*flash/i,
-        /gpt-5\..*mini/i,
-        /gpt-4\.1.*mini/i,
-        /gpt-4o-mini/i,
-        /claude.*haiku/i,
-        /claude.*sonnet/i,
-    ];
-    const patternIndex = patterns.findIndex((pattern) => pattern.test(id));
-    return patternIndex >= 0 ? patternIndex : patterns.length;
+function getWebSearchConfigPath(): string {
+    return process.env.PI_WEB_SEARCH_CONFIG || WEB_SEARCH_CONFIG_PATH;
 }
 
-export async function getModel(ctx: ExtensionContext): Promise<Model<any> | undefined> {
-    // Use the current model first so the tool follows the user's selected provider.
-    // This lets pi --provider openai/anthropic/google automatically pick the matching API.
-    if (isSupportedSearchModel(ctx.model)) {
-        return ctx.model;
+function readWebSearchModelConfig(): WebSearchModelConfig {
+    const path = getWebSearchConfigPath();
+    let raw: string;
+    try {
+        raw = readFileSync(path, "utf8");
+    } catch (error: any) {
+        if (error?.code === "ENOENT") return { status: "missing", path };
+        return { status: "invalid", path, error: error?.message || String(error) };
+    }
+
+    let parsed: any;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (error: any) {
+        return { status: "invalid", path, error: `Invalid JSON: ${error?.message || String(error)}` };
+    }
+
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { status: "invalid", path, error: "Expected a JSON object with provider and model fields" };
+    }
+
+    const provider = parsed.provider;
+    const modelId = parsed.model ?? parsed.modelId;
+    if (typeof provider !== "string" || provider.trim() === "") {
+        return { status: "invalid", path, error: "Missing required string field: provider" };
+    }
+    if (typeof modelId !== "string" || modelId.trim() === "") {
+        return { status: "invalid", path, error: "Missing required string field: model" };
+    }
+
+    return { status: "configured", path, provider: provider.trim(), modelId: modelId.trim() };
+}
+
+function getAvailableSupportedModels(ctx: ExtensionContext): string[] {
+    try {
+        return ctx.modelRegistry.getAvailable()
+            .filter(isSupportedSearchModel)
+            .map(describeModel);
+    } catch {
+        return [];
     }
+}
+
+export async function getModel(ctx: ExtensionContext): Promise<Model<any> | undefined> {
+    // Only use the currently selected model. Do not silently fall back to another
+    // configured model, because that can surprise users with unexpected API costs.
+    return isSupportedSearchModel(ctx.model) ? ctx.model : undefined;
+}
 
-    const models = ctx.modelRegistry.getAvailable().filter(isSupportedSearchModel);
-    if (models.length === 0) return undefined;
+export async function getWebSearchModel(ctx: ExtensionContext): Promise<Model<any> | undefined> {
+    const config = readWebSearchModelConfig();
+    if (config.status === "invalid") return undefined;
+
+    if (config.status === "configured") {
+        const model = ctx.modelRegistry.find(config.provider, config.modelId);
+        return isSupportedSearchModel(model) ? model : undefined;
+    }
 
-    return models.sort((a, b) => {
-        const byProvider = providerPriority(a) - providerPriority(b);
-        if (byProvider !== 0) return byProvider;
-        return modelPriority(a) - modelPriority(b);
-    })[0];
+    return getModel(ctx);
 }
 
 // --- Error Results ---
 
 export function missingConfigResult(ctx: ExtensionContext): AgentToolResult<any> {
-    const current = ctx.model ? `${ctx.model.provider} (${ctx.model.api})` : "none";
-    const msg = `No supported web-search model configuration found. Current model: ${current}. Configure or select a supported provider: google-generative-ai, openai, or anthropic.`;
-    return { content: [{ type: "text", text: `Failed: ${msg}` }], details: { error: "missing_config" } };
+    const availableSupportedModels = getAvailableSupportedModels(ctx);
+    const supportedList = SUPPORTED_PROVIDERS.join(", ");
+
+    if (ctx.model) {
+        const availableHint = availableSupportedModels.length > 0
+            ? ` Select one of these configured supported models manually: ${availableSupportedModels.join(", ")}.`
+            : ` Configure and select a supported provider: ${supportedList}.`;
+        const msg = `The current model ${describeModel(ctx.model)} does not support native web search. pi-web-search will not switch to another configured model automatically to avoid unexpected API costs.${availableHint}`;
+        return {
+            content: [{ type: "text", text: `Failed: ${msg}` }],
+            details: {
+                error: "unsupported_model",
+                currentModel: describeModel(ctx.model),
+                availableSupportedModels,
+                supportedProviders: SUPPORTED_PROVIDERS,
+            }
+        };
+    }
+
+    const availableHint = availableSupportedModels.length > 0
+        ? ` Select one of these configured supported models manually: ${availableSupportedModels.join(", ")}.`
+        : ` Configure and select a supported provider: ${supportedList}.`;
+    const msg = `No current model selected for web search.${availableHint}`;
+    return {
+        content: [{ type: "text", text: `Failed: ${msg}` }],
+        details: {
+            error: "missing_config",
+            availableSupportedModels,
+            supportedProviders: SUPPORTED_PROVIDERS,
+        }
+    };
+}
+
+export function missingWebSearchConfigResult(ctx: ExtensionContext): AgentToolResult<any> {
+    const config = readWebSearchModelConfig();
+    const availableSupportedModels = getAvailableSupportedModels(ctx);
+    const supportedList = SUPPORTED_PROVIDERS.join(", ");
+
+    if (config.status === "invalid") {
+        return {
+            content: [{ type: "text", text: `Failed: Invalid web search model config at ${config.path}: ${config.error}. Fix the file or remove it to use the current conversation model.` }],
+            details: {
+                error: "invalid_config",
+                configPath: config.path,
+                configError: config.error,
+                supportedProviders: SUPPORTED_PROVIDERS,
+            }
+        };
+    }
+
+    if (config.status === "configured") {
+        const model = ctx.modelRegistry.find(config.provider, config.modelId);
+        if (!model) {
+            return {
+                content: [{ type: "text", text: `Failed: Configured web search model ${config.provider}/${config.modelId} from ${config.path} was not found. Fix the file or remove it to use the current conversation model.` }],
+                details: {
+                    error: "configured_model_not_found",
+                    configPath: config.path,
+                    configuredProvider: config.provider,
+                    configuredModel: config.modelId,
+                    availableSupportedModels,
+                    supportedProviders: SUPPORTED_PROVIDERS,
+                }
+            };
+        }
+        return {
+            content: [{ type: "text", text: `Failed: Configured web search model ${describeModel(model)} from ${config.path} does not support native web search. Configure a model backed by ${supportedList}, or remove the file to use the current conversation model.` }],
+            details: {
+                error: "unsupported_model",
+                configPath: config.path,
+                configuredModel: describeModel(model),
+                configuredProvider: config.provider,
+                availableSupportedModels,
+                supportedProviders: SUPPORTED_PROVIDERS,
+            }
+        };
+    }
+
+    return missingConfigResult(ctx);
 }
 
 export function errorResult(e: Error): AgentToolResult<any> {

package/src/web_search.ts

@@ -1,7 +1,7 @@
 import type { ExtensionContext, AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
-import { Type, type Static } from "@sinclair/typebox";
+import { Type, type Static } from "typebox";
 import { callApiStream, getConfig, applyCitations } from "./api.ts";
-import { getModel, missingConfigResult, errorResult, formatResult } from "./utils.ts";
+import { getWebSearchModel, missingWebSearchConfigResult, errorResult, formatResult } from "./utils.ts";
 
 export const WebSearchSchema = Type.Object({
     query: Type.String({ description: "The search query or question to answer" }),
@@ -19,8 +19,8 @@ export async function webSearch(
     onUpdate: AgentToolUpdateCallback | undefined, 
     ctx: ExtensionContext
 ) {
-    const model = await getModel(ctx);
-    if (!model) return missingConfigResult(ctx);
+    const model = await getWebSearchModel(ctx);
+    if (!model) return missingWebSearchConfigResult(ctx);
 
     const hasUrls = params.urls && params.urls.length > 0;
     const urlCount = hasUrls ? params.urls!.length : 0;
@@ -84,10 +84,6 @@ export async function webSearch(
             failed.forEach((f: any) => { summary += `\n- ${f.url}: ${f.status}`; });
         }
 
-        if (result.nativeSearchUsed === false) {
-            summary += `\n\n## Search Verification\n⚠️ No verified native search metadata was returned by provider ${result.providerKind || "unknown"}. Treat the answer as ungrounded unless sources/searchResults are present in tool details.`;
-        }
-
         // Add sources
         if (sources.length > 0) {
             summary += `\n\n## Sources\n${sources.map((s, i) => `${i + 1}. [${s.title}](${s.url})`).join("\n")}`;