@sayknow-cli/coding-agent 0.4.2 → 0.4.4

package/dist/types/web/search/providers/openai-compatible.d.ts

@@ -0,0 +1,9 @@
+import type { SearchResponse } from "../types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+export declare class OpenAICompatibleSearchProvider extends SearchProvider {
+    readonly id: "openai-compatible";
+    readonly label = "OpenAI-compatible";
+    isAvailable(): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

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

@@ -0,0 +1,15 @@
+import { type AuthStorage } from "@sayknow-cli/ai";
+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;
+}, authStorage: AuthStorage, sessionId?: string): Promise<SearchResponse>;
+export declare class ParallelProvider extends SearchProvider {
+    readonly id = "parallel";
+    readonly label = "Parallel";
+    isAvailable(authStorage: AuthStorage): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Perplexity Web Search Provider
+ *
+ * Supports three auth modes:
+ * - Cookies (`PERPLEXITY_COOKIES`) via `www.perplexity.ai/rest/sse/perplexity_ask`
+ * - OAuth/session bearer via `AuthStorage` and `www.perplexity.ai/rest/sse/perplexity_ask`
+ * - API key (`PERPLEXITY_API_KEY`) via `api.perplexity.ai/chat/completions`
+ */
+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 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;
+    authStorage: AuthStorage;
+    sessionId?: string;
+}
+/** 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(authStorage: AuthStorage): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

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

@@ -0,0 +1,44 @@
+/**
+ * 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 { AuthStorage } from "@sayknow-cli/ai";
+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(_authStorage: AuthStorage): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * 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 AuthStorage } from "@sayknow-cli/ai";
+import type { SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+/** Resolve Synthetic API key through the shared auth storage pipeline. */
+export declare function findApiKey(authStorage: AuthStorage, sessionId?: string, signal?: AbortSignal): Promise<string | undefined>;
+/** Execute Synthetic web search. */
+export declare function searchSynthetic(params: SearchParams): Promise<SearchResponse>;
+/** Search provider for Synthetic. */
+export declare class SyntheticProvider extends SearchProvider {
+    readonly id = "synthetic";
+    readonly label = "Synthetic";
+    isAvailable(authStorage: AuthStorage): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Tavily Web Search Provider
+ *
+ * Uses Tavily's agent-focused search API to return structured results with an
+ * optional synthesized answer.
+ */
+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 TavilySearchParams {
+    query: string;
+    num_results?: number;
+    recency?: "day" | "week" | "month" | "year";
+    signal?: AbortSignal;
+}
+/** Find Tavily API key through AuthStorage's unified refresh pipeline. */
+export declare function findApiKey(authStorage: AuthStorage, sessionId: string | undefined, signal: AbortSignal | undefined): 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: SearchParams): Promise<SearchResponse>;
+/** Search provider for Tavily web search. */
+export declare class TavilyProvider extends SearchProvider {
+    readonly id = "tavily";
+    readonly label = "Tavily";
+    isAvailable(authStorage: AuthStorage): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/types/web/search/providers/text-citations.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Inline citation extraction shared by native web-search providers.
+ *
+ * Web-search-capable models sometimes return a genuinely grounded answer whose
+ * sources are written inline (markdown links or bare URLs) instead of as
+ * structured citation annotations. When a provider has independent proof that a
+ * web search actually ran, these helpers recover sources from the answer text so
+ * the result is not discarded.
+ */
+import type { SearchSource } from "../types";
+/** Append a source, de-duplicating by URL. */
+export declare function addSource(sources: SearchSource[], source: SearchSource): void;
+/**
+ * Strips prose punctuation and unmatched closing delimiters from extracted URLs.
+ * Models often return links embedded in markdown or sentence text.
+ */
+export declare function normalizeExtractedUrl(candidate: string): string | null;
+/**
+ * Extracts citation sources from markdown links and bare URLs in answer text.
+ * Used only as a fallback when a provider confirms a search ran but omits
+ * structured citation annotations.
+ */
+export declare function extractTextSources(text: string): SearchSource[];

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

@@ -0,0 +1,88 @@
+import type { AgentStorage } from "../../../session/agent-storage";
+import { SearchProviderError, type SearchProviderId, 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.
+ *
+ * The caller MUST supply an open {@link AgentStorage} handle so the helper
+ * never reaches out to global filesystem state; both the unified web_search
+ * chain and one-shot CLI calls open storage exactly once and thread it
+ * through every provider.
+ *
+ * @param storage - Open agent storage handle
+ * @param envKey - Pre-resolved environment variable value (or null)
+ * @param storageProviders - Provider names to look up in AgentStorage
+ */
+export declare function findCredential(storage: AgentStorage | null | undefined, envKey: string | null | undefined, ...storageProviders: string[]): string | null;
+/**
+ * Legacy hard ceiling for a single web-search round-trip, retained as the
+ * fallback for call sites that do not declare a timeout class. 300s tolerates
+ * pathological cases while still guaranteeing the session unfreezes if Bun's
+ * `AbortSignal` fails to propagate on Windows.
+ */
+export declare const SEARCH_HARD_TIMEOUT_MS = 300000;
+/**
+ * Hard ceiling for pure search APIs (brave, exa, jina, tavily, kagi,
+ * parallel, searxng, synthetic, zai, duckduckgo). These settle in ~1-3s in
+ * practice; a hung TCP/TLS connection should fall through to the next
+ * provider in seconds, not minutes. Kimi is the exception: it declares an
+ * explicit ceiling aligned with its upstream 30s request budget.
+ */
+export declare const SEARCH_API_TIMEOUT_MS = 15000;
+/**
+ * Hard ceiling for LLM-mediated search providers (anthropic, codex, gemini,
+ * perplexity, xai, openai-compatible). These legitimately take tens of
+ * seconds because a model performs the search and synthesizes an answer.
+ */
+export declare const SEARCH_LLM_TIMEOUT_MS = 120000;
+/** Timeout class a provider declares for its outbound round-trips. */
+export type SearchTimeoutClass = "api" | "llm";
+/**
+ * Override the hard timeout applied to every web-search round-trip.
+ *
+ * @param ms - Hard timeout in milliseconds. Non-finite or non-positive
+ *   values clear the override so per-class defaults apply.
+ */
+export declare function setSearchHardTimeoutMs(ms: number | undefined): void;
+/** Structural settings source for {@link applyConfiguredSearchTimeout}. */
+export interface SearchTimeoutSettingSource {
+    get(path: "web_search.timeout"): unknown;
+    has(path: "web_search.timeout"): boolean;
+}
+/**
+ * Install the `web_search.timeout` override from settings — but only when the
+ * user explicitly configured it. The settings schema ships a default value
+ * (300), and consuming that default via `get()` alone would reinstall a
+ * uniform 300s ceiling on every session, silently disabling the per-class
+ * timeout defaults. `has()` distinguishes loaded/overridden settings from
+ * schema defaults; unset clears any previous override so class defaults apply.
+ */
+export declare function applyConfiguredSearchTimeout(settings: SearchTimeoutSettingSource): void;
+/**
+ * Compose a caller-supplied {@link AbortSignal} with a hard timeout so an
+ * outbound `fetch()` is guaranteed to settle even when the runtime fails to
+ * propagate cancellation to the underlying transport.
+ *
+ * Bun's WinHTTP backend on Windows is known to ignore `AbortSignal` once a
+ * TCP/TLS connection stalls (oven-sh/bun#15275, oven-sh/bun#18536); without
+ * this safety net a stalled web-search request freezes the entire session
+ * because the user's Esc is never delivered to the native layer.
+ *
+ * @param signal - Caller cancellation signal, if any.
+ * @param msOrClass - Explicit timeout in milliseconds, or a
+ *   {@link SearchTimeoutClass} resolved to its class default. Omitted falls
+ *   back to the legacy {@link SEARCH_HARD_TIMEOUT_MS} ceiling. A user-set
+ *   `web_search.timeout` overrides class defaults (but not explicit ms).
+ */
+export declare function withHardTimeout(signal: AbortSignal | undefined, msOrClass?: number | SearchTimeoutClass): AbortSignal;
+/**
+ * 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[];
+export declare function classifyProviderHttpError(provider: SearchProviderId, status: number, body: string): SearchProviderError | null;

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

@@ -0,0 +1,64 @@
+/**
+ * xAI Web/X Search Provider
+ *
+ * Uses xAI's Responses API with the built-in web_search and x_search tools.
+ * Endpoint: POST https://api.x.ai/v1/responses
+ */
+import type { AuthStorage } from "@sayknow-cli/ai";
+import type { SearchCitation, SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+declare const XAI_SEARCH_MODES: readonly ["web", "x", "web_and_x"];
+export type XaiSearchMode = (typeof XAI_SEARCH_MODES)[number];
+export interface XaiSearchParams {
+    query: string;
+    system_prompt?: string;
+    num_results?: number;
+    max_output_tokens?: number;
+    temperature?: number;
+    recency?: "day" | "week" | "month" | "year";
+    xai_search_mode?: XaiSearchMode;
+    allowed_domains?: string[];
+    excluded_domains?: string[];
+    allowed_x_handles?: string[];
+    excluded_x_handles?: string[];
+    from_date?: string;
+    to_date?: string;
+    enable_image_understanding?: boolean;
+    enable_image_search?: boolean;
+    enable_video_understanding?: boolean;
+    no_inline_citations?: boolean;
+    signal?: AbortSignal;
+    authStorage: AuthStorage;
+    sessionId?: string;
+}
+export declare function buildXaiRequestBody(params: {
+    query: string;
+    systemPrompt: string;
+    model: string;
+    maxOutputTokens?: number;
+    temperature?: number;
+    recency?: XaiSearchParams["recency"];
+    xaiSearchMode?: XaiSearchMode;
+    allowedDomains?: string[];
+    excludedDomains?: string[];
+    allowedXHandles?: string[];
+    excludedXHandles?: string[];
+    fromDate?: string;
+    toDate?: string;
+    enableImageUnderstanding?: boolean;
+    enableImageSearch?: boolean;
+    enableVideoUnderstanding?: boolean;
+    noInlineCitations?: boolean;
+}): Record<string, unknown>;
+export declare function parseXaiCitations(json: any): SearchCitation[];
+/** Execute xAI web/X search through the Responses API search tools. */
+export declare function searchXai(params: XaiSearchParams): Promise<SearchResponse>;
+/** Search provider for xAI web and X search. */
+export declare class XaiProvider extends SearchProvider {
+    readonly id = "xai";
+    readonly label = "xAI";
+    isAvailable(authStorage: AuthStorage): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}
+export {};

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

@@ -0,0 +1,28 @@
+/**
+ * Z.AI Web Search Provider
+ *
+ * Calls Z.AI's remote MCP server (`webSearchPrime`) and adapts 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 ZaiSearchParams {
+    query: string;
+    num_results?: number;
+    signal?: AbortSignal;
+    authStorage: AuthStorage;
+    sessionId?: string;
+}
+/** Resolve Z.AI API credentials through the unified auth storage pipeline. */
+export declare function findApiKey(authStorage: AuthStorage, sessionId?: string, signal?: AbortSignal): 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(authStorage: AuthStorage): Promise<boolean> | boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Web Search TUI Rendering
+ *
+ * Tree-based rendering with collapsed/expanded states for web search results.
+ */
+import type { Component } from "@sayknow-cli/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;
+    warning?: 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;
+};