@sayknow-cli/coding-agent 0.4.2 → 0.4.4

package/dist/types/web/search/index.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Unified Web Search Tool
+ *
+ * Single tool supporting Anthropic, Perplexity, Exa, Brave, Jina, Kimi, Gemini, OpenAI code backend, xAI, Tavily, Kagi, Z.AI, SearXNG, and Synthetic
+ * providers with provider-specific parameters exposed conditionally.
+ */
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@sayknow-cli/agent-core";
+import type { AuthStorage } from "@sayknow-cli/ai";
+import * as z from "zod/v4";
+import type { CustomTool } from "../../extensibility/custom-tools/types";
+import type { ToolSession } from "../../tools";
+import { type SearchRenderDetails } from "./render";
+import type { ActiveSearchModelContext, SearchProviderId, SearchResponse } from "./types";
+/** Web search tool parameters schema */
+export declare const webSearchSchema: z.ZodObject<{
+    query: z.ZodString;
+    recency: z.ZodOptional<z.ZodEnum<{
+        day: "day";
+        week: "week";
+        month: "month";
+        year: "year";
+    }>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    max_tokens: z.ZodOptional<z.ZodNumber>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    num_search_results: z.ZodOptional<z.ZodNumber>;
+    xai_search_mode: z.ZodOptional<z.ZodEnum<{
+        x: "x";
+        web: "web";
+        web_and_x: "web_and_x";
+    }>>;
+    allowed_domains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    excluded_domains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allowed_x_handles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    excluded_x_handles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    from_date: z.ZodOptional<z.ZodString>;
+    to_date: z.ZodOptional<z.ZodString>;
+    enable_image_understanding: z.ZodOptional<z.ZodBoolean>;
+    enable_image_search: z.ZodOptional<z.ZodBoolean>;
+    enable_video_understanding: z.ZodOptional<z.ZodBoolean>;
+    no_inline_citations: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SearchToolParams = z.infer<typeof webSearchSchema>;
+export interface SearchQueryParams extends SearchToolParams {
+    provider?: SearchProviderId | "auto";
+}
+/** Format response for LLM consumption */
+export declare function formatSearchResponseForLlm(response: SearchResponse): string;
+/** Override the hedge delay (tests). Non-finite/non-positive resets to default. */
+export declare function setDdgHedgeDelayMs(ms: number | undefined): void;
+/**
+ * Execute a web search query for CLI/testing workflows.
+ *
+ * `authStorage` may be omitted; in that case we discover one via the standard
+ * factory (`discoverAuthStorage`), which honours `SKC_AUTH_BROKER_URL` and
+ * otherwise opens the local SQLite credential store.
+ */
+export declare function runSearchQuery(params: SearchQueryParams, options?: {
+    authStorage?: AuthStorage;
+    sessionId?: string;
+    signal?: AbortSignal;
+    activeModelContext?: ActiveSearchModelContext;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details: SearchRenderDetails;
+}>;
+/**
+ * Web search tool implementation.
+ *
+ * Supports Anthropic, Perplexity, Exa, Brave, Jina, Kimi, Gemini, OpenAI code backend, xAI, Z.AI, SearXNG, and Synthetic providers with automatic fallback.
+ */
+export declare class WebSearchTool implements AgentTool<typeof webSearchSchema, SearchRenderDetails> {
+    #private;
+    readonly name = "web_search";
+    readonly label = "Web Search";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        query: z.ZodString;
+        recency: z.ZodOptional<z.ZodEnum<{
+            day: "day";
+            week: "week";
+            month: "month";
+            year: "year";
+        }>>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        max_tokens: z.ZodOptional<z.ZodNumber>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+        num_search_results: z.ZodOptional<z.ZodNumber>;
+        xai_search_mode: z.ZodOptional<z.ZodEnum<{
+            x: "x";
+            web: "web";
+            web_and_x: "web_and_x";
+        }>>;
+        allowed_domains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        excluded_domains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allowed_x_handles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        excluded_x_handles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        from_date: z.ZodOptional<z.ZodString>;
+        to_date: z.ZodOptional<z.ZodString>;
+        enable_image_understanding: z.ZodOptional<z.ZodBoolean>;
+        enable_image_search: z.ZodOptional<z.ZodBoolean>;
+        enable_video_understanding: z.ZodOptional<z.ZodBoolean>;
+        no_inline_citations: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    readonly strict = true;
+    readonly loadMode = "discoverable";
+    readonly summary = "Search the web for up-to-date information";
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: SearchToolParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<SearchRenderDetails>, _context?: AgentToolContext): Promise<AgentToolResult<SearchRenderDetails>>;
+}
+/** Web search tool as CustomTool (for TUI rendering support) */
+export declare const webSearchCustomTool: CustomTool<typeof webSearchSchema, SearchRenderDetails>;
+export declare function getSearchTools(): CustomTool<any, any>[];
+export { getConfiguredSearchProviderPreference, getSearchProvider, setPreferredSearchProvider, setSearchFallbackProviders, } from "./provider";
+export { applyConfiguredSearchTimeout, setSearchHardTimeoutMs } from "./providers/utils";
+export type { SearchProviderId as SearchProvider, SearchResponse } from "./types";
+export { isConfigurableSearchProviderId, isSearchProviderPreference } from "./types";

package/dist/types/web/search/provider.d.ts

@@ -0,0 +1,55 @@
+import type { AuthStorage } from "@sayknow-cli/ai";
+import type { SearchProvider } from "./providers/base";
+import type { ActiveSearchModelContext, SearchProviderId } from "./types";
+export type { SearchParams } from "./providers/base";
+export { SearchProvider } from "./providers/base";
+export declare function getSearchProviderLabel(id: SearchProviderId): string;
+export declare function getSearchProvider(id: SearchProviderId): Promise<SearchProvider>;
+export declare const SEARCH_PROVIDER_ORDER: SearchProviderId[];
+/** Drop every cached resolved chain (settings changed, tests). */
+export declare function clearResolvedChainCache(): void;
+export declare function setPreferredSearchProvider(provider: SearchProviderId | "auto"): void;
+export declare function setSearchFallbackProviders(ids: readonly string[]): void;
+/**
+ * Fire-and-forget warm-up: resolve the provider chain once so the provider
+ * modules are imported and the chain cache is primed before the first
+ * user-visible search. Errors are intentionally swallowed — prewarming must
+ * never surface a failure the real search path would handle itself.
+ */
+export declare function prewarmSearchProviders(options: ResolveProviderChainOptions): void;
+export interface SearchProviderPreferenceSource {
+    get(path: "providers.webSearch" | "web_search.provider"): SearchProviderId | "auto";
+    has(path: "providers.webSearch" | "web_search.provider"): boolean;
+}
+export declare function getConfiguredSearchProviderPreference(settings: SearchProviderPreferenceSource): SearchProviderId | "auto";
+export interface ResolveProviderChainOptions {
+    authStorage: AuthStorage;
+    sessionId?: string;
+    signal?: AbortSignal;
+    preferredProvider?: SearchProviderId | "auto";
+    activeModelContext?: ActiveSearchModelContext;
+    fallbackProviders?: readonly SearchProviderId[];
+}
+export declare function looksHostedModelId(modelId: string | undefined): boolean;
+export declare function isLocalBaseUrl(baseUrl: string | undefined): boolean;
+export declare function inferNativeProviderFromModel(ctx: ActiveSearchModelContext | undefined): SearchProviderId | undefined;
+export declare function canUseGenericCredentials(authStorage: AuthStorage, ctx: ActiveSearchModelContext | undefined, sessionId?: string, signal?: AbortSignal): Promise<boolean>;
+/**
+ * Native web-search provider to attempt by reusing the ACTIVE model's own
+ * credentials + baseUrl, dispatched by the model's wire protocol.
+ *
+ * This is the "native search over a proxy" path: when a model is served through
+ * a proxy/custom endpoint, its canonical search credentials (e.g. a dedicated
+ * `anthropic` key, or ChatGPT OAuth for `codex`) are usually absent, but the
+ * credential that authenticates the model itself — stored under the active
+ * provider id and aimed at `ctx.baseUrl` — can drive native web search just as
+ * well. Each provider's `search()` falls back to those active credentials when
+ * its canonical ones are missing.
+ *
+ * Returned ids are matched purely from the wire `api` (+ model-id family where a
+ * native tool only makes sense for that family); the providers themselves fail
+ * closed (and the chain falls through to DuckDuckGo) if the endpoint does not
+ * actually support web search.
+ */
+export declare function activeContextNativeId(ctx: ActiveSearchModelContext | undefined): SearchProviderId | undefined;
+export declare function resolveProviderChain(options: ResolveProviderChainOptions): Promise<SearchProvider[]>;

package/dist/types/web/search/providers/anthropic.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Anthropic Web Search Provider
+ *
+ * Uses Anthropic's built-in web_search_20250305 tool to search the web.
+ * Returns synthesized answers with citations and source metadata.
+ */
+import { type AuthStorage } from "@sayknow-cli/ai";
+import type { SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+export interface AnthropicSearchParams {
+    query: string;
+    system_prompt?: string;
+    num_results?: number;
+    max_tokens?: number;
+    temperature?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Executes a web search using Anthropic's Anthropic model with built-in web search tool.
+ * @param params - Search parameters including query and optional settings
+ * @returns Search response with synthesized answer, sources, and citations
+ * @throws {Error} If no Anthropic credentials are configured
+ */
+export declare function searchAnthropic(params: SearchParams | AnthropicSearchParams, _legacyStorage?: unknown): Promise<SearchResponse>;
+/** Search provider for Anthropic Anthropic model web search. */
+export declare class AnthropicProvider extends SearchProvider {
+    readonly id = "anthropic";
+    readonly label = "Anthropic";
+    isAvailable(authStorage: AuthStorage): Promise<boolean> | boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/types/web/search/providers/base.d.ts

@@ -0,0 +1,90 @@
+import type { AuthStorage } from "@sayknow-cli/ai";
+import type { ActiveSearchModelContext, SearchProviderId, SearchResponse } from "../types";
+/**
+ * Shared web search parameters passed to providers.
+ *
+ * `authStorage` is the **only** credential source providers may consult.
+ * Opening a sibling SQLite handle or calling provider-direct refresh helpers
+ * (e.g. `refreshOpenAIOpenAI code backendToken`, `refreshGoogleCloudToken`) is prohibited:
+ * it races the broker's per-credential refresh and POSTs the broker sentinel
+ * (`REMOTE_REFRESH_SENTINEL`) to the upstream token endpoint, which classifies
+ * as `invalid_grant` and disables the row.
+ */
+export interface SearchParams {
+    query: string;
+    limit?: number;
+    /**
+     * Temporal filter narrowing results to the specified time window.
+     *
+     * Providers MUST interpret this as a pure time filter. Providers MUST NOT
+     * use recency as an implicit signal to change topic scope, content domain,
+     * or ranking strategy. If a provider API couples temporal filtering with
+     * other dimensions (e.g. Tavily's `topic=news`), the provider implementation
+     * is responsible for decoupling them before calling the upstream API.
+     *
+     * Providers that do not support temporal filtering MUST ignore this field
+     * silently; they MUST NOT approximate it by rewriting the query or altering
+     * any other request parameter.
+     */
+    recency?: "day" | "week" | "month" | "year";
+    systemPrompt: string;
+    signal?: AbortSignal;
+    maxOutputTokens?: number;
+    numSearchResults?: number;
+    temperature?: number;
+    /** xAI-specific search surface. Defaults to web_search when omitted. */
+    xaiSearchMode?: "web" | "x" | "web_and_x";
+    /** xAI web_search domain allow-list (max 5). */
+    allowedDomains?: string[];
+    /** xAI web_search domain deny-list (max 5). */
+    excludedDomains?: string[];
+    /** xAI x_search handle allow-list (max 20). */
+    allowedXHandles?: string[];
+    /** xAI x_search handle deny-list (max 20). */
+    excludedXHandles?: string[];
+    /** xAI x_search lower date bound, ISO8601 date such as YYYY-MM-DD. */
+    fromDate?: string;
+    /** xAI x_search upper date bound, ISO8601 date such as YYYY-MM-DD. */
+    toDate?: string;
+    /** xAI web_search/x_search image understanding. */
+    enableImageUnderstanding?: boolean;
+    /** xAI web_search image search result embedding. */
+    enableImageSearch?: boolean;
+    /** xAI x_search video understanding. */
+    enableVideoUnderstanding?: boolean;
+    /** xAI Responses include=["no_inline_citations"]. */
+    noInlineCitations?: boolean;
+    googleSearch?: Record<string, unknown>;
+    codeExecution?: Record<string, unknown>;
+    urlContext?: Record<string, unknown>;
+    /**
+     * The single source of truth for credentials. Providers MUST consult this
+     * handle exclusively (`getApiKey` for bearer-style auth, `getOAuthAccess`
+     * when identity metadata is required). Do not open `AgentStorage` or any
+     * `AuthCredentialStore` directly — that bypasses the broker pipeline and
+     * the per-credential single-flight refresh.
+     */
+    authStorage: AuthStorage;
+    /**
+     * Optional session id used as the round-robin / sticky key when selecting
+     * among multiple credentials for the same provider. Pass through from the
+     * caller's agent session when available; otherwise omit.
+     */
+    sessionId?: string;
+    activeModelContext?: ActiveSearchModelContext;
+}
+/** Base class for web search providers. */
+export declare abstract class SearchProvider {
+    abstract readonly id: SearchProviderId;
+    abstract readonly label: string;
+    /**
+     * Indicates whether this provider has the credentials/config it needs to
+     * service a request right now. Implementations consult the passed
+     * {@link AuthStorage} — never a sibling store.
+     */
+    abstract isAvailable(authStorage: AuthStorage): Promise<boolean> | boolean;
+    /**
+     * Execute a search. Credentials MUST be resolved through `params.authStorage`.
+     */
+    abstract search(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/types/web/search/providers/brave.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Brave Web Search Provider
+ *
+ * Calls Brave's web search REST API and maps results into the unified
+ * SearchResponse shape used by the web search tool.
+ */
+import { type AuthStorage } from "@sayknow-cli/ai";
+import type { SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+export interface BraveSearchParams {
+    query: string;
+    num_results?: number;
+    recency?: "day" | "week" | "month" | "year";
+    signal?: AbortSignal;
+}
+/** Find BRAVE_API_KEY from environment or .env files. */
+export declare function findApiKey(): string | null;
+/** Execute Brave web search. */
+export declare function searchBrave(params: BraveSearchParams): Promise<SearchResponse>;
+/** Search provider for Brave web search. */
+export declare class BraveProvider extends SearchProvider {
+    readonly id = "brave";
+    readonly label = "Brave";
+    isAvailable(_authStorage: AuthStorage): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/types/web/search/providers/codex.d.ts

@@ -0,0 +1,35 @@
+import { type AuthStorage } from "@sayknow-cli/ai";
+import type { SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+export interface CodexSearchParams {
+    signal?: AbortSignal;
+    query: string;
+    system_prompt?: string;
+    num_results?: number;
+    /** Search context size: controls how much web content to include */
+    search_context_size?: "low" | "medium" | "high";
+}
+/**
+ * Executes a web search using OpenAI code provider's built-in web search tool.
+ *
+ * Default-model behavior:
+ * - If `PI_CODEX_WEB_SEARCH_MODEL` is set, use it exactly once and surface any
+ *   upstream error verbatim.
+ * - Otherwise prefer ChatGPT-account-safe bundled defaults (GPT-5.5, GPT-5.4,
+ *   GPT-5 code backend, …) and retry the next candidate only when OpenAI code backend returns the
+ *   known 400 "model is not supported" family. This avoids selecting
+ *   `gpt-5-codex-mini` first on ChatGPT accounts, which OpenAI rejects.
+ */
+export declare function searchCodex(params: SearchParams): Promise<SearchResponse>;
+/**
+ * Checks if OpenAI code backend web search is available.
+ */
+export declare function hasCodexSearch(authStorage: AuthStorage): Promise<boolean>;
+/** Search provider for OpenAI code provider web search. */
+export declare class CodexProvider extends SearchProvider {
+    readonly id = "codex";
+    readonly label = "OpenAI";
+    isAvailable(authStorage: AuthStorage): Promise<boolean> | boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/types/web/search/providers/duckduckgo.d.ts

@@ -0,0 +1,57 @@
+/**
+ * DuckDuckGo Web Search Provider
+ *
+ * Keyless, permissionless web search. Scrapes DuckDuckGo's no-JavaScript HTML
+ * endpoints and maps anchors/snippets into the unified SearchResponse shape
+ * (sources only — DuckDuckGo does not synthesize an answer).
+ *
+ * This is the zero-config default/fallback backend: it requires no API key and
+ * no OAuth, so `isAvailable()` is always true. Because DuckDuckGo applies
+ * anti-bot rate limiting (HTTP 202 / 403 / empty responses) from datacenter and
+ * VPN IPs, the provider is best-effort: it retries with backoff, rotates the
+ * user-agent, and alternates between the `html` and `lite` endpoints. When every
+ * attempt fails it throws a {@link SearchProviderError} rather than returning an
+ * empty success — it never falls through to keyed providers.
+ *
+ * Endpoints:
+ *   https://html.duckduckgo.com/html/  (primary)
+ *   https://lite.duckduckgo.com/lite/  (fallback markup)
+ *
+ * The HTML markup is liable to drift; the parser is deliberately small and is
+ * pinned by fixture-driven tests (see test/tools/web-search-duckduckgo.test.ts).
+ */
+import type { AuthStorage } from "@sayknow-cli/ai";
+import type { SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+interface ParsedResult {
+    title: string;
+    url: string;
+    snippet?: string;
+}
+/**
+ * Resolve a DuckDuckGo result href to the real destination URL. DuckDuckGo wraps
+ * external links in a `/l/?uddg=<encoded>` redirect; `lite` sometimes links
+ * directly. Returns null for unusable or internal links (so ads/redirect shells
+ * are dropped).
+ */
+export declare function decodeResultUrl(href: string): string | null;
+/** Parse results from the `html.duckduckgo.com/html/` markup. */
+export declare function parseHtmlResults(html: string): ParsedResult[];
+/** Parse results from the `lite.duckduckgo.com/lite/` markup. */
+export declare function parseLiteResults(html: string): ParsedResult[];
+/** Execute a keyless DuckDuckGo web search with light resilience. */
+export declare function searchDuckDuckGo(params: {
+    query: string;
+    num_results?: number;
+    recency?: "day" | "week" | "month" | "year";
+    signal?: AbortSignal;
+}): Promise<SearchResponse>;
+/** Keyless, permissionless web search provider backed by DuckDuckGo. */
+export declare class DuckDuckGoProvider extends SearchProvider {
+    readonly id = "duckduckgo";
+    readonly label = "DuckDuckGo";
+    isAvailable(_authStorage: AuthStorage): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}
+export {};

package/dist/types/web/search/providers/exa.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Exa Web Search Provider
+ *
+ * High-quality neural search via Exa Search API.
+ * Returns structured search results with optional content extraction.
+ * Requests per-result summaries via `contents.summary` and synthesizes
+ * them into a combined `answer` string on the SearchResponse.
+ */
+import { type AuthStorage } from "@sayknow-cli/ai";
+import type { SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+type ExaSearchType = "neural" | "fast" | "auto" | "deep";
+type ExaSearchParamType = ExaSearchType | "keyword";
+export interface ExaSearchParams {
+    query: string;
+    num_results?: number;
+    type?: ExaSearchParamType;
+    include_domains?: string[];
+    exclude_domains?: string[];
+    start_published_date?: string;
+    end_published_date?: string;
+    signal?: AbortSignal;
+}
+interface ExaSearchResult {
+    title?: string | null;
+    url?: string | null;
+    author?: string | null;
+    publishedDate?: string | null;
+    text?: string | null;
+    highlights?: string[] | null;
+    summary?: string | null;
+}
+export declare function normalizeSearchType(type: ExaSearchParamType | undefined): ExaSearchType;
+/**
+ * Synthesize an answer string from per-result summaries returned by Exa.
+ * Returns `undefined` when no non-empty summaries are available so callers
+ * can leave `SearchResponse.answer` unset (matching other providers).
+ */
+export declare function synthesizeAnswer(results: ExaSearchResult[]): string | undefined;
+/** Build the request body for `callExaSearch`. Exported for testing. */
+export declare function buildExaRequestBody(params: ExaSearchParams): Record<string, unknown>;
+/** Execute Exa web search */
+export declare function searchExa(params: ExaSearchParams): Promise<SearchResponse>;
+/** Search provider for Exa. */
+export declare class ExaProvider extends SearchProvider {
+    readonly id = "exa";
+    readonly label = "Exa";
+    isAvailable(_authStorage: AuthStorage): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}
+export {};

package/dist/types/web/search/providers/gemini.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Google Gemini Web Search Provider
+ *
+ * Uses Gemini's Google Search grounding via Cloud Code Assist API.
+ * Auth is resolved through `AuthStorage.getOAuthAccess(...)` for both
+ * `google-gemini-cli` (stable prod) and `google-antigravity` (daily sandbox)
+ * — the broker is the sole refresh authority, so this module never opens a
+ * sibling SQLite store and never POSTs the broker sentinel to a Google token
+ * endpoint.
+ */
+import { type AuthStorage } from "@sayknow-cli/ai";
+import type { SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+interface GeminiToolParams {
+    google_search?: Record<string, unknown>;
+    code_execution?: Record<string, unknown>;
+    url_context?: Record<string, unknown>;
+}
+export interface GeminiSearchParams extends GeminiToolParams {
+    query: string;
+    system_prompt?: string;
+    num_results?: number;
+    /** Maximum output tokens. */
+    max_output_tokens?: number;
+    /** Sampling temperature (0–1). Lower = more focused/factual. */
+    temperature?: number;
+    signal?: AbortSignal;
+    authStorage: AuthStorage;
+    sessionId?: string;
+}
+export declare function buildGeminiRequestTools(params: GeminiToolParams): Array<Record<string, Record<string, unknown>>>;
+/** Resolved auth for a Gemini API request. */
+interface GeminiAuth {
+    accessToken: string;
+    projectId: string;
+    isAntigravity: boolean;
+}
+/**
+ * Walks the configured Gemini OAuth providers in deterministic order and
+ * returns the first one that yields a usable access token + projectId via
+ * {@link AuthStorage.getOAuthAccess}. AuthStorage handles refresh + broker
+ * routing internally; this helper never touches refresh tokens directly.
+ */
+export declare function findGeminiAuth(authStorage: AuthStorage, sessionId: string | undefined, signal: AbortSignal | undefined): Promise<GeminiAuth | null>;
+/**
+ * Executes a web search using Google Gemini with Google Search grounding.
+ */
+export declare function searchGemini(params: GeminiSearchParams): Promise<SearchResponse>;
+/** Search provider for Google Gemini web search. */
+export declare class GeminiProvider extends SearchProvider {
+    readonly id = "gemini";
+    readonly label = "Gemini";
+    isAvailable(authStorage: AuthStorage): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}
+export {};

package/dist/types/web/search/providers/insane.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Insane Search Provider
+ *
+ * Native TypeScript, fail-closed adaptation of the MIT-licensed upstream
+ * fivetaku/insane-search public-route strategy. This ports only safe Phase 0
+ * concepts: deterministic no-auth public endpoints plus route-attempt tracing.
+ *
+ * Deliberately excluded from upstream: TLS impersonation, browser/cookie warming,
+ * CAPTCHA/paywall/login bypasses, credential storage, Playwright automation, and
+ * auto dependency installation. Unsupported or terminal auth/paywall/block states
+ * throw instead of pretending a shallow fetch succeeded.
+ */
+import type { AuthStorage } from "@sayknow-cli/ai";
+import type { SearchResponse, SearchSource } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+export interface InsaneRouteAttempt {
+    platform: InsanePlatform;
+    route: string;
+    ok: boolean;
+    status: number;
+    bytes: number;
+    note?: string;
+}
+type InsanePlatform = "reddit" | "x" | "youtube" | "hackernews";
+interface RouteSuccess {
+    platform: InsanePlatform;
+    route: string;
+    finalUrl: string;
+    sources: SearchSource[];
+    attempts: InsaneRouteAttempt[];
+}
+interface RouteFailure {
+    platform: InsanePlatform;
+    attempts: InsaneRouteAttempt[];
+}
+type RouteResult = RouteSuccess | RouteFailure | null;
+export declare function routeInsanePublicUrl(rawUrl: string, signal?: AbortSignal): Promise<RouteResult>;
+/** Execute safe Insane Search public-route discovery. */
+export declare function searchInsane(params: {
+    query: string;
+    num_results?: number;
+    recency?: "day" | "week" | "month" | "year";
+    signal?: AbortSignal;
+}): Promise<SearchResponse>;
+/** Keyless provider that ports safe upstream public-route fallbacks only. */
+export declare class InsaneProvider extends SearchProvider {
+    readonly id = "insane";
+    readonly label = "Insane";
+    isAvailable(_authStorage: AuthStorage): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}
+export {};

package/dist/types/web/search/providers/jina.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Jina Reader Web Search Provider
+ *
+ * Uses the Jina Reader `s.jina.ai` endpoint to fetch search results with
+ * cleaned content.
+ */
+import { type AuthStorage } from "@sayknow-cli/ai";
+import type { SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+export interface JinaSearchParams {
+    query: string;
+    num_results?: number;
+    signal?: AbortSignal;
+}
+/** Find JINA_API_KEY from environment or .env files. */
+export declare function findApiKey(): string | null;
+/** Execute Jina web search. */
+export declare function searchJina(params: JinaSearchParams): Promise<SearchResponse>;
+/** Search provider for Jina Reader. */
+export declare class JinaProvider extends SearchProvider {
+    readonly id = "jina";
+    readonly label = "Jina";
+    isAvailable(_authStorage: AuthStorage): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/types/web/search/providers/kagi.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Kagi Web Search Provider
+ *
+ * Thin wrapper that adapts shared Kagi API utilities to SearchResponse shape.
+ */
+import type { AuthStorage } from "@sayknow-cli/ai";
+import type { SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+/** Execute Kagi web search. */
+export declare function searchKagi(params: {
+    query: string;
+    num_results?: number;
+    signal?: AbortSignal;
+    authStorage: AuthStorage;
+    sessionId?: string;
+}): Promise<SearchResponse>;
+/** Search provider for Kagi web search. */
+export declare class KagiProvider extends SearchProvider {
+    readonly id = "kagi";
+    readonly label = "Kagi";
+    isAvailable(authStorage: AuthStorage): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/types/web/search/providers/kimi.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Kimi Web Search Provider
+ *
+ * Uses Moonshot Kimi Code search API to retrieve web results.
+ * Endpoint: POST https://api.kimi.com/coding/v1/search
+ */
+import type { AuthStorage } from "@sayknow-cli/ai";
+import type { SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+export interface KimiSearchParams {
+    query: string;
+    num_results?: number;
+    include_content?: boolean;
+    signal?: AbortSignal;
+    authStorage: AuthStorage;
+    sessionId?: string;
+}
+/** Execute Kimi web search. */
+export declare function searchKimi(params: KimiSearchParams): Promise<SearchResponse>;
+/** Search provider for Kimi web search. */
+export declare class KimiProvider extends SearchProvider {
+    readonly id = "kimi";
+    readonly label = "Kimi";
+    isAvailable(authStorage: AuthStorage): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}