gsd-pi 2.33.1 → 2.34.0-dev.6769913

package/dist/resources/extensions/search-the-web/native-search.js

@@ -0,0 +1,166 @@
+/**
+ * Native Anthropic web search hook logic.
+ *
+ * Extracted from index.ts so it can be unit-tested without importing
+ * the heavy tool-registration modules.
+ */
+import { resolveSearchProviderFromPreferences } from "../gsd/preferences.js";
+/** Tool names for the Brave-backed custom search tools */
+export const BRAVE_TOOL_NAMES = ["search-the-web", "search_and_read"];
+/** All custom search tool names that should be disabled when native search is active */
+export const CUSTOM_SEARCH_TOOL_NAMES = ["search-the-web", "search_and_read", "google_search"];
+/** Thinking block types that require signature validation by the API */
+const THINKING_TYPES = new Set(["thinking", "redacted_thinking"]);
+/** When true, skip native web search injection and keep Brave/custom tools active on Anthropic. */
+export function preferBraveSearch() {
+    // preferences.md takes priority over env var
+    const prefsPref = resolveSearchProviderFromPreferences();
+    if (prefsPref === "brave" || prefsPref === "tavily" || prefsPref === "ollama")
+        return true;
+    if (prefsPref === "native")
+        return false;
+    // Fall back to env var
+    return process.env.PREFER_BRAVE_SEARCH === "1" || process.env.PREFER_BRAVE_SEARCH === "true";
+}
+/**
+ * Strip thinking/redacted_thinking blocks from assistant messages in the
+ * conversation history.
+ *
+ * Why: The Pi SDK's streaming parser drops `server_tool_use` and
+ * `web_search_tool_result` content blocks (unknown types). When the
+ * conversation is replayed, the assistant messages are incomplete — missing
+ * those blocks. The Anthropic API detects the modification and rejects the
+ * request with "thinking blocks cannot be modified."
+ *
+ * Fix: Remove thinking blocks from all assistant messages in the history.
+ * In Anthropic's Messages API, the messages array always ends with a user
+ * message, so every assistant message is from a previous turn that has been
+ * through a store/replay cycle. The model generates fresh thinking for the
+ * current turn regardless.
+ */
+export function stripThinkingFromHistory(messages) {
+    for (const msg of messages) {
+        if (msg.role !== "assistant")
+            continue;
+        const content = msg.content;
+        if (!Array.isArray(content))
+            continue;
+        msg.content = content.filter((block) => !THINKING_TYPES.has(block?.type));
+    }
+}
+/**
+ * Register model_select, before_provider_request, and session_start hooks
+ * for native Anthropic web search injection.
+ *
+ * Returns the isAnthropicProvider getter for testing.
+ */
+export function registerNativeSearchHooks(pi) {
+    let isAnthropicProvider = false;
+    let modelSelectFired = false;
+    // Track provider changes via model selection — also handles diagnostics
+    // since model_select fires AFTER session_start and knows the provider.
+    pi.on("model_select", async (event, ctx) => {
+        modelSelectFired = true;
+        const wasAnthropic = isAnthropicProvider;
+        isAnthropicProvider = event.model.provider === "anthropic";
+        const hasBrave = !!process.env.BRAVE_API_KEY;
+        // When Anthropic (and not preferring Brave): disable custom search tools —
+        // native web_search is server-side and more reliable.
+        if (isAnthropicProvider && !preferBraveSearch()) {
+            const active = pi.getActiveTools();
+            pi.setActiveTools(active.filter((t) => !CUSTOM_SEARCH_TOOL_NAMES.includes(t)));
+        }
+        else if (!isAnthropicProvider && wasAnthropic) {
+            // Switching away from Anthropic — re-enable custom search tools (they
+            // were disabled while native search was active). If keys are missing,
+            // user sees the error rather than tools silently vanishing.
+            const active = pi.getActiveTools();
+            const toAdd = CUSTOM_SEARCH_TOOL_NAMES.filter((t) => !active.includes(t));
+            if (toAdd.length > 0) {
+                pi.setActiveTools([...active, ...toAdd]);
+            }
+        }
+        // Show provider-aware diagnostics on first selection or provider change
+        if (isAnthropicProvider && !preferBraveSearch() && !wasAnthropic && event.source !== "restore") {
+            ctx.ui.notify("Native Anthropic web search active", "info");
+        }
+        else if (isAnthropicProvider && preferBraveSearch() && !wasAnthropic && event.source !== "restore") {
+            ctx.ui.notify("Brave search active (PREFER_BRAVE_SEARCH)", "info");
+        }
+        else if (!isAnthropicProvider && !hasBrave) {
+            ctx.ui.notify("Web search: Set BRAVE_API_KEY or use an Anthropic model for built-in search", "warning");
+        }
+    });
+    // Inject native web search into Anthropic API requests
+    pi.on("before_provider_request", (event) => {
+        const payload = event.payload;
+        if (!payload)
+            return;
+        // Detect Anthropic provider. Use the model object from the event (most
+        // reliable — comes directly from the resolved Model), then fall back to
+        // the model_select flag, then to the model name heuristic (last resort).
+        // The model name heuristic is needed for session restores where
+        // modelsAreEqual suppresses model_select AND the SDK doesn't pass model.
+        const eventModel = event.model;
+        let isAnthropic;
+        if (eventModel?.provider) {
+            isAnthropic = eventModel.provider === "anthropic";
+        }
+        else if (modelSelectFired) {
+            isAnthropic = isAnthropicProvider;
+        }
+        else {
+            const modelName = typeof payload.model === "string" ? payload.model : "";
+            isAnthropic = modelName.startsWith("claude-");
+        }
+        if (!isAnthropic)
+            return;
+        // Strip thinking blocks from history to avoid signature validation errors
+        // caused by the SDK dropping server_tool_use/web_search_tool_result blocks.
+        const messages = payload.messages;
+        if (Array.isArray(messages)) {
+            stripThinkingFromHistory(messages);
+        }
+        // When preferring Brave, skip native search injection entirely
+        if (preferBraveSearch())
+            return;
+        if (!Array.isArray(payload.tools))
+            payload.tools = [];
+        let tools = payload.tools;
+        // Don't double-inject if already present
+        if (tools.some((t) => t.type === "web_search_20250305"))
+            return;
+        // Remove custom search tool definitions from Anthropic requests.
+        // Native web_search is server-side and more reliable — keeping both confuses
+        // the model and causes it to pick custom tools which can fail with network errors.
+        tools = tools.filter((t) => !CUSTOM_SEARCH_TOOL_NAMES.includes(t.name));
+        payload.tools = tools;
+        tools.push({
+            type: "web_search_20250305",
+            name: "web_search",
+            // Cap server-side searches per response to prevent the model from
+            // looping on web_search without synthesizing results (#817).
+            // 5 searches is generous — most queries need 1-2.
+            max_uses: 5,
+        });
+        return payload;
+    });
+    // Basic startup diagnostics — provider-specific info comes from model_select
+    pi.on("session_start", async (_event, ctx) => {
+        const hasBrave = !!process.env.BRAVE_API_KEY;
+        const hasJina = !!process.env.JINA_API_KEY;
+        const hasAnswers = !!process.env.BRAVE_ANSWERS_KEY;
+        const hasTavily = !!process.env.TAVILY_API_KEY;
+        const parts = ["Web search v4 loaded"];
+        if (hasBrave)
+            parts.push("Brave ✓");
+        if (hasAnswers)
+            parts.push("Answers ✓");
+        if (hasJina)
+            parts.push("Jina ✓");
+        if (hasTavily)
+            parts.push("Tavily ✓");
+        ctx.ui.notify(parts.join(" · "), "info");
+    });
+    return { getIsAnthropic: () => isAnthropicProvider };
+}

package/dist/resources/extensions/search-the-web/provider.js

@@ -0,0 +1,143 @@
+/**
+ * Search provider selection and preference management.
+ *
+ * Single source of truth for which search backend (Tavily vs Brave) to use.
+ * Reads API keys from process.env at call time (not module load time) so
+ * hot-reloaded keys work. Preference is stored in auth.json under the
+ * synthetic provider key `search_provider` as { type: "api_key", key: "tavily" | "brave" | "auto" }.
+ *
+ * @see S01-RESEARCH.md for the storage decision rationale (D002).
+ */
+import { AuthStorage } from '@gsd/pi-coding-agent';
+import { homedir } from 'os';
+import { join } from 'path';
+import { resolveSearchProviderFromPreferences } from '../gsd/preferences.js';
+// Compute authFilePath locally instead of importing from app-paths.ts,
+// because extensions are copied to ~/.gsd/agent/extensions/ at runtime
+// where the relative import '../../../app-paths.ts' doesn't resolve.
+const authFilePath = join(homedir(), '.gsd', 'agent', 'auth.json');
+const VALID_PREFERENCES = new Set(['tavily', 'brave', 'ollama', 'auto']);
+const PREFERENCE_KEY = 'search_provider';
+/** Returns the Tavily API key from the environment, or empty string if not set. */
+export function getTavilyApiKey() {
+    return process.env.TAVILY_API_KEY || '';
+}
+/** Returns the Brave API key from the environment, or empty string if not set. */
+export function getBraveApiKey() {
+    return process.env.BRAVE_API_KEY || '';
+}
+/** Standard headers for Brave Search API requests. */
+export function braveHeaders() {
+    return {
+        "Accept": "application/json",
+        "Accept-Encoding": "gzip",
+        "X-Subscription-Token": getBraveApiKey(),
+    };
+}
+/** Returns the Ollama API key from the environment, or empty string if not set. */
+export function getOllamaApiKey() {
+    return process.env.OLLAMA_API_KEY || '';
+}
+/**
+ * Read the user's search provider preference from auth.json.
+ * Returns 'auto' if no preference is stored or the stored value is invalid.
+ *
+ * @param authPath — Override auth.json path (for testing).
+ */
+export function getSearchProviderPreference(authPath) {
+    const auth = AuthStorage.create(authPath ?? authFilePath);
+    const cred = auth.get(PREFERENCE_KEY);
+    if (cred?.type === 'api_key' && typeof cred.key === 'string' && VALID_PREFERENCES.has(cred.key)) {
+        return cred.key;
+    }
+    return 'auto';
+}
+/**
+ * Write the user's search provider preference to auth.json.
+ * Uses AuthStorage to go through file locking.
+ *
+ * @param pref — The preference to store.
+ * @param authPath — Override auth.json path (for testing).
+ */
+export function setSearchProviderPreference(pref, authPath) {
+    const auth = AuthStorage.create(authPath ?? authFilePath);
+    auth.remove(PREFERENCE_KEY);
+    auth.set(PREFERENCE_KEY, { type: 'api_key', key: pref });
+}
+/**
+ * Resolve which search provider to use based on available API keys and user preference.
+ *
+ * Logic:
+ * 1. If an explicit override is given, use it — but only if that provider's key exists.
+ *    If the key doesn't exist, fall through to the other provider.
+ * 2. Otherwise, read the stored preference.
+ * 3. If preference is 'auto': prefer Tavily, then Brave.
+ * 4. If preference is a specific provider: use it if key exists, else fall back to the other.
+ * 5. Return null if neither key is available — explicit signal for "no provider".
+ *
+ * @param overridePreference — Optional override (e.g. from a tool parameter).
+ */
+export function resolveSearchProvider(overridePreference) {
+    const tavilyKey = getTavilyApiKey();
+    const braveKey = getBraveApiKey();
+    const ollamaKey = getOllamaApiKey();
+    const hasTavily = tavilyKey.length > 0;
+    const hasBrave = braveKey.length > 0;
+    const hasOllama = ollamaKey.length > 0;
+    // Determine effective preference
+    let pref;
+    if (overridePreference && VALID_PREFERENCES.has(overridePreference)) {
+        pref = overridePreference;
+    }
+    else {
+        // preferences.md takes priority over auth.json
+        const mdPref = resolveSearchProviderFromPreferences();
+        if (mdPref && mdPref !== 'auto' && mdPref !== 'native') {
+            pref = mdPref;
+        }
+        else if (overridePreference !== undefined && !VALID_PREFERENCES.has(overridePreference)) {
+            pref = 'auto';
+        }
+        else {
+            pref = getSearchProviderPreference();
+        }
+    }
+    // Resolve based on preference
+    if (pref === 'auto') {
+        if (hasTavily)
+            return 'tavily';
+        if (hasBrave)
+            return 'brave';
+        if (hasOllama)
+            return 'ollama';
+        return null;
+    }
+    if (pref === 'tavily') {
+        if (hasTavily)
+            return 'tavily';
+        if (hasBrave)
+            return 'brave';
+        if (hasOllama)
+            return 'ollama';
+        return null;
+    }
+    if (pref === 'brave') {
+        if (hasBrave)
+            return 'brave';
+        if (hasTavily)
+            return 'tavily';
+        if (hasOllama)
+            return 'ollama';
+        return null;
+    }
+    if (pref === 'ollama') {
+        if (hasOllama)
+            return 'ollama';
+        if (hasTavily)
+            return 'tavily';
+        if (hasBrave)
+            return 'brave';
+        return null;
+    }
+    return null;
+}

package/dist/resources/extensions/search-the-web/tavily.js

@@ -0,0 +1,82 @@
+/**
+ * Tavily API types and helper functions for normalizing Tavily search results
+ * into the shared SearchResultFormatted shape.
+ *
+ * Consumed by: tool-search.ts (S02), search_and_read Tavily path (S03).
+ * All exports are pure functions with no side effects.
+ */
+// =============================================================================
+// Result Normalization
+// =============================================================================
+/**
+ * Map a single Tavily result to the shared SearchResultFormatted shape.
+ *
+ * - `content` → `description` (Tavily puts NLP summary or chunks inline)
+ * - `published_date` → `age` via publishedDateToAge()
+ * - No `extra_snippets` — Tavily's content already includes chunk data
+ */
+export function normalizeTavilyResult(r) {
+    return {
+        title: r.title || "(untitled)",
+        url: r.url,
+        description: r.content || "",
+        age: r.published_date ? publishedDateToAge(r.published_date) : undefined,
+    };
+}
+// =============================================================================
+// Date-to-Age Conversion
+// =============================================================================
+/**
+ * Convert an ISO 8601 date string to a human-readable relative age string.
+ *
+ * Examples: "3 days ago", "2 hours ago", "1 month ago", "just now"
+ * Returns undefined for unparseable dates or dates in the future.
+ */
+export function publishedDateToAge(isoDate) {
+    const date = new Date(isoDate);
+    if (isNaN(date.getTime()))
+        return undefined;
+    const now = Date.now();
+    const diffMs = now - date.getTime();
+    // Future dates — return undefined rather than negative ages
+    if (diffMs < 0)
+        return undefined;
+    const seconds = Math.floor(diffMs / 1000);
+    if (seconds < 60)
+        return "just now";
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes} ${minutes === 1 ? "minute" : "minutes"} ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours} ${hours === 1 ? "hour" : "hours"} ago`;
+    const days = Math.floor(hours / 24);
+    if (days < 30)
+        return `${days} ${days === 1 ? "day" : "days"} ago`;
+    const months = Math.floor(days / 30);
+    if (months < 12)
+        return `${months} ${months === 1 ? "month" : "months"} ago`;
+    const years = Math.floor(months / 12);
+    return `${years} ${years === 1 ? "year" : "years"} ago`;
+}
+// =============================================================================
+// Freshness Format Mapping
+// =============================================================================
+/** Brave freshness string → Tavily time_range value mapping. */
+const BRAVE_TO_TAVILY_FRESHNESS = {
+    pd: "day",
+    pw: "week",
+    pm: "month",
+    py: "year",
+};
+/**
+ * Convert a Brave-format freshness string (pd/pw/pm/py) to a Tavily
+ * `time_range` value (day/week/month/year).
+ *
+ * Returns null if input is null or not a recognized Brave freshness value.
+ */
+export function mapFreshnessToTavily(braveFreshness) {
+    if (braveFreshness === null)
+        return null;
+    return BRAVE_TO_TAVILY_FRESHNESS[braveFreshness] ?? null;
+}