@oh-my-pi/pi-coding-agent 15.1.1 → 15.1.3

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

@@ -0,0 +1,35 @@
+import type { SearchProviderId, SearchResponse } from "../types";
+/** Shared web search parameters passed to providers. */
+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;
+    googleSearch?: Record<string, unknown>;
+    codeExecution?: Record<string, unknown>;
+    urlContext?: Record<string, unknown>;
+}
+/** Base class for web search providers. */
+export declare abstract class SearchProvider {
+    abstract readonly id: SearchProviderId;
+    abstract readonly label: string;
+    abstract isAvailable(): Promise<boolean> | boolean;
+    abstract search(params: SearchParams): Promise<SearchResponse>;
+}

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

@@ -0,0 +1,20 @@
+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(): Promise<boolean>;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

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

@@ -0,0 +1,31 @@
+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 Codex's built-in web search tool.
+ * Requires OAuth credentials stored in agent.db for provider "openai-codex".
+ * @param params - Search parameters including query and optional settings
+ * @returns Search response with synthesized answer, sources, and usage
+ * @throws {Error} If no Codex OAuth credentials are configured
+ */
+export declare function searchCodex(params: CodexSearchParams): Promise<SearchResponse>;
+/**
+ * Checks if Codex web search is available.
+ * @returns True if valid OAuth credentials exist for openai-codex
+ */
+export declare function hasCodexSearch(): Promise<boolean>;
+/** Search provider for OpenAI Codex web search. */
+export declare class CodexProvider extends SearchProvider {
+    readonly id = "codex";
+    readonly label = "Codex";
+    isAvailable(): Promise<boolean>;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

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

@@ -0,0 +1,43 @@
+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(): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}
+export {};

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

@@ -0,0 +1,60 @@
+import { AgentStorage } from "../../../session/agent-storage";
+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;
+}
+export declare function buildGeminiRequestTools(params: GeminiToolParams): Array<Record<string, Record<string, unknown>>>;
+/** OAuth credential stored in agent.db */
+interface GeminiOAuthCredential {
+    type: "oauth";
+    access: string;
+    refresh?: string;
+    expires: number;
+    projectId?: string;
+}
+/** Auth info for Gemini API requests */
+interface GeminiAuth {
+    accessToken: string;
+    refreshToken?: string;
+    projectId: string;
+    isAntigravity: boolean;
+    storage: AgentStorage;
+    credentialId: number;
+    credential: GeminiOAuthCredential;
+}
+/**
+ * Finds valid Gemini OAuth credentials from agent.db.
+ * Checks google-gemini-cli first (stable prod), then google-antigravity (daily sandbox).
+ * @returns OAuth credential with access token and project ID, or null if none found
+ */
+export declare function findGeminiAuth(): Promise<GeminiAuth | null>;
+/**
+ * Executes a web search using Google Gemini with Google Search grounding.
+ * Requires OAuth credentials stored in agent.db for provider "google-gemini-cli" or "google-antigravity".
+ * @param params - Search parameters including query and optional settings
+ * @returns Search response with synthesized answer, sources, and citations
+ * @throws {Error} If no Gemini OAuth credentials are configured
+ */
+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(): Promise<boolean>;
+    search(params: SearchParams): Promise<SearchResponse>;
+}
+export {};

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

@@ -0,0 +1,25 @@
+/**
+ * Jina Reader Web Search Provider
+ *
+ * Uses the Jina Reader `s.jina.ai` endpoint to fetch search results with
+ * cleaned content.
+ */
+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(): Promise<boolean>;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Kagi Web Search Provider
+ *
+ * Thin wrapper that adapts shared Kagi API utilities to SearchResponse shape.
+ */
+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;
+}): Promise<SearchResponse>;
+/** Search provider for Kagi web search. */
+export declare class KagiProvider extends SearchProvider {
+    readonly id = "kagi";
+    readonly label = "Kagi";
+    isAvailable(): Promise<boolean>;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

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

@@ -0,0 +1,18 @@
+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;
+}
+/** 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(): Promise<boolean>;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

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

@@ -0,0 +1,14 @@
+import type { SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+export declare function searchParallel(params: {
+    query: string;
+    num_results?: number;
+    signal?: AbortSignal;
+}): Promise<SearchResponse>;
+export declare class ParallelProvider extends SearchProvider {
+    readonly id = "parallel";
+    readonly label = "Parallel";
+    isAvailable(): Promise<boolean>;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Perplexity Web Search Provider
+ *
+ * Supports three auth modes:
+ * - Cookies (`PERPLEXITY_COOKIES`) via `www.perplexity.ai/rest/sse/perplexity_ask`
+ * - OAuth JWT (stored in `agent.db`) via `www.perplexity.ai/rest/sse/perplexity_ask`
+ * - API key (`PERPLEXITY_API_KEY`) via `api.perplexity.ai/chat/completions`
+ */
+import type { SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+export interface PerplexitySearchParams {
+    signal?: AbortSignal;
+    query: string;
+    system_prompt?: string;
+    search_recency_filter?: "hour" | "day" | "week" | "month" | "year";
+    num_results?: number;
+    /** Maximum output tokens. Defaults to 4096. */
+    max_tokens?: number;
+    /** Sampling temperature (0–1). Lower = more focused/factual. Defaults to 0.2. */
+    temperature?: number;
+    /** Number of search results to retrieve. Defaults to 10. */
+    num_search_results?: number;
+}
+/** Find PERPLEXITY_API_KEY from environment or .env files (also checks PPLX_API_KEY) */
+export declare function findApiKey(): string | null;
+/** Execute Perplexity web search */
+export declare function searchPerplexity(params: PerplexitySearchParams): Promise<SearchResponse>;
+/** Search provider for Perplexity. */
+export declare class PerplexityProvider extends SearchProvider {
+    readonly id = "perplexity";
+    readonly label = "Perplexity";
+    isAvailable(): Promise<boolean>;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * SearXNG Web Search Provider
+ *
+ * Calls a SearXNG instance's JSON search API and maps results into the unified
+ * SearchResponse shape used by the web search tool.
+ *
+ * SearXNG is a free, open-source metasearch engine that aggregates results from
+ * multiple sources without tracking users. It supports self-hosted instances
+ * and various authentication methods (bearer token, basic auth, or none).
+ *
+ * Configuration via settings:
+ *   searxng.endpoint      - Base URL of the SearXNG instance (e.g. https://searx.example.org)
+ *   searxng.token         - Optional bearer token for authentication
+ *   searxng.basicUsername - Optional RFC 7617 Basic auth username
+ *   searxng.basicPassword - Optional RFC 7617 Basic auth password
+ *   searxng.categories    - Optional comma-separated categories filter
+ *   searxng.language      - Optional language code (e.g. en, zh-CN)
+ *
+ * Environment variable fallbacks:
+ *   SEARXNG_ENDPOINT       - Base URL of the SearXNG instance
+ *   SEARXNG_TOKEN          - Optional bearer token
+ *   SEARXNG_BASIC_USERNAME - Optional RFC 7617 Basic auth username
+ *   SEARXNG_BASIC_PASSWORD - Optional RFC 7617 Basic auth password
+ *
+ * Reference: https://docs.searxng.org/dev/search_api.html
+ */
+import type { SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+/** Execute SearXNG web search. */
+export declare function searchSearXNG(params: {
+    query: string;
+    num_results?: number;
+    recency?: "day" | "week" | "month" | "year";
+    signal?: AbortSignal;
+}): Promise<SearchResponse>;
+/** Search provider for SearXNG web search. */
+export declare class SearXNGProvider extends SearchProvider {
+    readonly id = "searxng";
+    readonly label = "SearXNG";
+    isAvailable(): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Synthetic Web Search Provider
+ *
+ * Uses Synthetic's zero-data-retention web search API for coding agents.
+ * Endpoint: POST https://api.synthetic.new/v2/search
+ */
+import type { SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+/** Find Synthetic API key from environment or agent.db credentials. */
+export declare function findApiKey(): Promise<string | null>;
+/** Execute Synthetic web search. */
+export declare function searchSynthetic(params: {
+    query: string;
+    num_results?: number;
+    signal?: AbortSignal;
+}): Promise<SearchResponse>;
+/** Search provider for Synthetic. */
+export declare class SyntheticProvider extends SearchProvider {
+    readonly id = "synthetic";
+    readonly label = "Synthetic";
+    isAvailable(): Promise<boolean>;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

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

@@ -0,0 +1,22 @@
+import type { SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+export interface TavilySearchParams {
+    query: string;
+    num_results?: number;
+    recency?: "day" | "week" | "month" | "year";
+    signal?: AbortSignal;
+}
+/** Find Tavily API key from environment or agent.db credentials. */
+export declare function findApiKey(): Promise<string | null>;
+/** Exported for testing. Builds the Tavily request body from unified params. */
+export declare function buildRequestBody(params: TavilySearchParams): Record<string, unknown>;
+/** Execute Tavily web search. */
+export declare function searchTavily(params: TavilySearchParams): Promise<SearchResponse>;
+/** Search provider for Tavily web search. */
+export declare class TavilyProvider extends SearchProvider {
+    readonly id = "tavily";
+    readonly label = "Tavily";
+    isAvailable(): Promise<boolean>;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

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

@@ -0,0 +1,24 @@
+import type { SearchSource } from "../../../web/search/types";
+/**
+ * Search for an API credential by checking an env-derived key first,
+ * then falling back to agent.db stored credentials for the given providers.
+ *
+ * @param envKey - Pre-resolved environment variable value (or null)
+ * @param storageProviders - Provider names to look up in AgentStorage
+ */
+export declare function findCredential(envKey: string | null | undefined, ...storageProviders: string[]): Promise<string | null>;
+/**
+ * Probe whether a provider's API key lookup resolves to a truthy value.
+ * Swallows lookup errors and reports unavailability.
+ */
+export declare function isApiKeyAvailable(findApiKey: () => string | null | Promise<string | null>): Promise<boolean>;
+/**
+ * Map a provider's raw source list to the unified SearchSource shape,
+ * clamped to the requested result count and annotated with ageSeconds.
+ */
+export declare function toSearchSources(sources: ReadonlyArray<{
+    title: string;
+    url: string;
+    snippet?: string;
+    publishedDate?: string;
+}>, numResults: number): SearchSource[];

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

@@ -0,0 +1,19 @@
+import type { SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+export interface ZaiSearchParams {
+    query: string;
+    num_results?: number;
+    signal?: AbortSignal;
+}
+/** Find Z.AI API credentials from environment or saved auth storage. */
+export declare function findApiKey(): Promise<string | null>;
+/** Execute Z.AI web search via remote MCP endpoint. */
+export declare function searchZai(params: ZaiSearchParams): Promise<SearchResponse>;
+/** Search provider for Z.AI web search MCP. */
+export declare class ZaiProvider extends SearchProvider {
+    readonly id = "zai";
+    readonly label = "Z.AI";
+    isAvailable(): Promise<boolean>;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Web Search TUI Rendering
+ *
+ * Tree-based rendering with collapsed/expanded states for web search results.
+ */
+import type { Component } from "@oh-my-pi/pi-tui";
+import type { RenderResultOptions } from "../../extensibility/custom-tools/types";
+import type { Theme } from "../../modes/theme/theme";
+import type { SearchResponse } from "./types";
+export interface SearchRenderDetails {
+    response: SearchResponse;
+    error?: string;
+}
+/** Render web search result with tree-based layout */
+export declare function renderSearchResult(result: {
+    content: Array<{
+        type: string;
+        text?: string;
+    }>;
+    details?: SearchRenderDetails;
+}, options: RenderResultOptions, theme: Theme, args?: {
+    query?: string;
+    allowLongAnswer?: boolean;
+    maxAnswerLines?: number;
+}): Component;
+/** Render web search call (query preview) */
+export declare function renderSearchCall(args: {
+    query?: string;
+    [key: string]: unknown;
+}, _options: RenderResultOptions, theme: Theme): Component;
+export declare const webSearchToolRenderer: {
+    renderCall: typeof renderSearchCall;
+    renderResult: typeof renderSearchResult;
+    mergeCallAndResult: boolean;
+};