c0de-agent 0.0.0 → 1.0.0

package/dist/tools/types.d.ts

@@ -0,0 +1,101 @@
+import type { JSONSchema } from '../shared/types/base.js';
+import type { ChatTool } from '../shared/types/llm.js';
+import type { ToolContext, ToolDef, ToolExecutor, ToolMode, ToolPermission, ToolResult } from '../shared/types/tool.js';
+/** Mutable tool registry. Stores both eager tool definitions and lazy factories. */
+type ToolRegistry = {
+    tools: Map<string, ToolDef>;
+    factories: Map<string, ToolFactory>;
+};
+/** Context passed to tool factories for lazy tool construction. */
+type ToolFactoryContext = {
+    config: Record<string, unknown>;
+    cwd: string;
+};
+/** Factory function for lazy tool loading. Returns null if tool is unavailable. */
+type ToolFactory = (ctx: ToolFactoryContext) => ToolDef | null;
+/** Result of a permission check. */
+type PermissionResult = {
+    _tag: 'allow';
+} | {
+    _tag: 'deny';
+    reason: string;
+} | {
+    _tag: 'ask';
+    reason: string;
+    toolCallId: string;
+};
+/** Permission checker interface. The executor calls `check` before running a tool. */
+type PermissionChecker = {
+    check: (tool: ToolDef, input: unknown, ctx: ToolContext) => Promise<PermissionResult>;
+    confirm: (toolCallId: string, approved: boolean) => void;
+};
+/** Result of JSON Schema validation. */
+type ValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    error: string;
+};
+/** Options for output truncation. */
+type TruncateOptions = {
+    maxLines: number;
+    maxChars: number;
+    headLines: number;
+    tailLines: number;
+};
+/** Result of output truncation. */
+type TruncateResult = {
+    output: string;
+    truncated: boolean;
+    totalLines: number;
+    totalChars: number;
+};
+/** Input for the read tool. */
+type ReadInput = {
+    path: string;
+    offset?: number;
+    limit?: number;
+};
+/** Input for the write tool. */
+type WriteInput = {
+    path: string;
+    content: string;
+};
+/** Input for the edit tool. Two modes (spec §16.4):
+ * - diff: search/replace via oldText/newText
+ * - hashline: content-hash-anchored patch via `patch` */
+type EditInput = {
+    path: string;
+    oldText: string;
+    newText: string;
+} | {
+    path: string;
+    patch: string;
+};
+/** Input for the glob tool. */
+type GlobInput = {
+    pattern: string;
+    path?: string;
+};
+/** Input for the grep tool. */
+type GrepInput = {
+    pattern: string;
+    path?: string;
+    caseSensitive?: boolean;
+    maxResults?: number;
+};
+/** Input for the bash tool (sync mode). */
+type BashInput = {
+    command: string;
+    cwd?: string;
+    timeout?: number;
+    env?: Record<string, string>;
+};
+/** A single grep match. */
+type GrepMatch = {
+    file: string;
+    line: number;
+    text: string;
+    match: string;
+};
+export type { BashInput, ChatTool, EditInput, GlobInput, GrepInput, GrepMatch, JSONSchema, PermissionChecker, PermissionResult, ReadInput, ToolContext, ToolDef, ToolExecutor, ToolFactory, ToolFactoryContext, ToolMode, ToolPermission, ToolRegistry, ToolResult, TruncateOptions, TruncateResult, ValidationResult, WriteInput, };

package/dist/tools/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/validate.d.ts

@@ -0,0 +1,8 @@
+import type { JSONSchema } from '../shared/types/base.js';
+import type { ValidationResult } from './types.js';
+/**
+ * Validate a value against a JSON Schema (draft-07 subset).
+ * Supports: type, required, properties, items, enum, additionalProperties, anyOf, oneOf.
+ * No external dependency — lightweight custom implementation.
+ */
+export declare function validateInput(schema: JSONSchema, value: unknown): ValidationResult;

package/dist/tools/validate.js

@@ -0,0 +1,130 @@
+/**
+ * Validate a value against a JSON Schema (draft-07 subset).
+ * Supports: type, required, properties, items, enum, additionalProperties, anyOf, oneOf.
+ * No external dependency — lightweight custom implementation.
+ */
+export function validateInput(schema, value) {
+    const error = validateNode(schema, value, '');
+    if (error)
+        return { valid: false, error };
+    return { valid: true };
+}
+function validateNode(schema, value, path) {
+    // Empty schema accepts anything
+    if (Object.keys(schema).length === 0)
+        return null;
+    // anyOf: at least one must pass
+    if (schema.anyOf) {
+        const passed = schema.anyOf.some((s) => validateNode(s, value, path) === null);
+        if (!passed)
+            return `${path || 'value'}: does not match anyOf schemas`;
+        return null;
+    }
+    // oneOf: exactly one must pass
+    if (schema.oneOf) {
+        const count = schema.oneOf.filter((s) => validateNode(s, value, path) === null).length;
+        if (count !== 1)
+            return `${path || 'value'}: must match exactly one oneOf schema (matched ${count})`;
+        return null;
+    }
+    // enum
+    if (schema.enum !== undefined) {
+        if (!schema.enum.includes(value)) {
+            return `${path || 'value'}: must be one of ${JSON.stringify(schema.enum)}`;
+        }
+    }
+    // type check
+    if (schema.type) {
+        const typeError = checkType(schema.type, value, path);
+        if (typeError)
+            return typeError;
+    }
+    // object validation
+    if (schema.type === 'object' &&
+        typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value)) {
+        const obj = value;
+        // required fields
+        if (schema.required) {
+            for (const field of schema.required) {
+                if (!(field in obj)) {
+                    return `${path ? `${path}.` : ''}${field}: missing required field`;
+                }
+            }
+        }
+        // properties
+        if (schema.properties) {
+            for (const [key, propSchema] of Object.entries(schema.properties)) {
+                if (key in obj) {
+                    const err = validateNode(propSchema, obj[key], path ? `${path}.${key}` : key);
+                    if (err)
+                        return err;
+                }
+            }
+        }
+        // additionalProperties
+        if (schema.additionalProperties === false && schema.properties) {
+            const knownKeys = new Set(Object.keys(schema.properties));
+            for (const key of Object.keys(obj)) {
+                if (!knownKeys.has(key)) {
+                    return `${path ? `${path}.` : ''}${key}: additional property not allowed`;
+                }
+            }
+        }
+    }
+    // array validation
+    if (schema.type === 'array' && Array.isArray(value)) {
+        if (schema.items) {
+            const itemSchema = Array.isArray(schema.items) ? schema.items : [schema.items];
+            for (let i = 0; i < value.length; i++) {
+                const s = itemSchema[i] ?? itemSchema[0];
+                if (s) {
+                    const err = validateNode(s, value[i], `${path}[${i}]`);
+                    if (err)
+                        return err;
+                }
+            }
+        }
+    }
+    return null;
+}
+function checkType(type, value, path) {
+    const label = path || 'value';
+    switch (type) {
+        case 'string':
+            if (typeof value !== 'string')
+                return `${label}: expected string, got ${typeof value}`;
+            break;
+        case 'number':
+            if (typeof value !== 'number' || Number.isNaN(value)) {
+                return `${label}: expected number, got ${typeof value}`;
+            }
+            break;
+        case 'integer':
+            if (typeof value !== 'number' || !Number.isInteger(value)) {
+                return `${label}: expected integer, got ${typeof value}`;
+            }
+            break;
+        case 'boolean':
+            if (typeof value !== 'boolean')
+                return `${label}: expected boolean, got ${typeof value}`;
+            break;
+        case 'object':
+            if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+                return `${label}: expected object`;
+            }
+            break;
+        case 'array':
+            if (!Array.isArray(value))
+                return `${label}: expected array, got ${typeof value}`;
+            break;
+        case 'null':
+            if (value !== null)
+                return `${label}: expected null, got ${typeof value}`;
+            break;
+        default:
+            break;
+    }
+    return null;
+}

package/dist/tools/websearch/fetch.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 读 HTTPS_PROXY/HTTP_PROXY 环境变量，有则返回带 dispatcher 的 fetch，
+ * 无则返回全局 fetch。仅影响本模块，不调用 setGlobalDispatcher（避免污染全局）。
+ *
+ * AGENTS.md 规定代理端口 7890；Node 内置 fetch 不自动走系统代理，故需包装。
+ *
+ * 注意：必须用 npm 包 undici 自带的 `fetch`（与 ProxyAgent 同版本）发起请求，
+ * 而非 Node 全局 fetch——Node 捆绑的 undici 与 npm 安装的 undici 版本不同，
+ * 跨版本传 Dispatcher 会被拒绝（UND_ERR_INVALID_ARG）。详见设计文档 §6。
+ */
+export declare function createFetch(): typeof fetch;

package/dist/tools/websearch/fetch.js

@@ -0,0 +1,21 @@
+import { ProxyAgent, fetch as undiciFetch } from 'undici';
+/**
+ * 读 HTTPS_PROXY/HTTP_PROXY 环境变量，有则返回带 dispatcher 的 fetch，
+ * 无则返回全局 fetch。仅影响本模块，不调用 setGlobalDispatcher（避免污染全局）。
+ *
+ * AGENTS.md 规定代理端口 7890；Node 内置 fetch 不自动走系统代理，故需包装。
+ *
+ * 注意：必须用 npm 包 undici 自带的 `fetch`（与 ProxyAgent 同版本）发起请求，
+ * 而非 Node 全局 fetch——Node 捆绑的 undici 与 npm 安装的 undici 版本不同，
+ * 跨版本传 Dispatcher 会被拒绝（UND_ERR_INVALID_ARG）。详见设计文档 §6。
+ */
+export function createFetch() {
+    const proxy = process.env.HTTPS_PROXY ||
+        process.env.https_proxy ||
+        process.env.HTTP_PROXY ||
+        process.env.http_proxy;
+    if (!proxy)
+        return fetch;
+    const dispatcher = new ProxyAgent(proxy);
+    return ((url, init) => undiciFetch(url, { ...init, dispatcher }));
+}

package/dist/tools/websearch/index.d.ts

@@ -0,0 +1,19 @@
+import type { WebSearchConfig } from '../../shared/types/config.js';
+import type { Recency, WebSearchProvider, WebSearchProviderId, WebSearchResponse } from './types.js';
+import { clampNumResults, DEFAULT_NUM_RESULTS } from './types.js';
+/** 按 preference + key 可用性解析目标 provider。auto 优先级：tavily > brave > duckduckgo。 */
+export declare function resolveProvider(preference: 'auto' | WebSearchProviderId, keys: {
+    tavily?: string;
+    brave?: string;
+}): WebSearchProvider;
+/** 将统一响应格式化为 LLM 友好的纯文本。 */
+export declare function formatForLLM(response: WebSearchResponse): string;
+/** 测试钩子：覆盖默认 fetch（undici ProxyAgent 包装版）。 */
+export declare function setFetchOverride(f: typeof fetch | undefined): void;
+/** 工具入口：解析 provider → search → 返回 WebSearchResponse。 */
+export declare function runWebSearch(input: {
+    query: string;
+    numResults?: number;
+    recency?: Recency;
+}, config: WebSearchConfig, abort: AbortSignal): Promise<WebSearchResponse>;
+export { clampNumResults, DEFAULT_NUM_RESULTS };

package/dist/tools/websearch/index.js

@@ -0,0 +1,78 @@
+import { createFetch } from './fetch.js';
+import { braveProvider } from './providers/brave.js';
+import { duckduckgoProvider } from './providers/duckduckgo.js';
+import { tavilyProvider } from './providers/tavily.js';
+import { clampNumResults, DEFAULT_NUM_RESULTS } from './types.js';
+const PROVIDERS = {
+    duckduckgo: duckduckgoProvider,
+    tavily: tavilyProvider,
+    brave: braveProvider,
+};
+/** 环境变量名 → config key 字段映射。环境变量优先于 config。 */
+function resolveKeys(config) {
+    return {
+        tavily: process.env.TAVILY_API_KEY ?? config.tavilyApiKey,
+        brave: process.env.BRAVE_API_KEY ?? config.braveApiKey,
+    };
+}
+/** 按 preference + key 可用性解析目标 provider。auto 优先级：tavily > brave > duckduckgo。 */
+export function resolveProvider(preference, keys) {
+    if (preference === 'auto') {
+        if (tavilyProvider.isAvailable(keys.tavily))
+            return tavilyProvider;
+        if (braveProvider.isAvailable(keys.brave))
+            return braveProvider;
+        return duckduckgoProvider;
+    }
+    const provider = PROVIDERS[preference];
+    if (!provider)
+        throw new Error(`Unknown websearch provider: ${preference}`);
+    if (!provider.isAvailable(preference === 'tavily' ? keys.tavily : keys.brave)) {
+        throw new Error(`${preference} provider requires an API key (set ${preference === 'tavily' ? 'TAVILY_API_KEY' : 'BRAVE_API_KEY'} or config).`);
+    }
+    return provider;
+}
+const SNIPPET_MAX = 240;
+function truncate(text, max) {
+    return text.length <= max ? text : `${text.slice(0, Math.max(0, max - 1))}…`;
+}
+/** 将统一响应格式化为 LLM 友好的纯文本。 */
+export function formatForLLM(response) {
+    const parts = [];
+    if (response.answer?.trim()) {
+        parts.push(response.answer.trim());
+    }
+    if (response.sources.length > 0) {
+        parts.push(`## Sources (${response.sources.length})`);
+        for (const [i, src] of response.sources.entries()) {
+            parts.push(`[${i + 1}] ${src.title}`);
+            parts.push(`    ${src.url}`);
+            if (src.snippet)
+                parts.push(`    ${truncate(src.snippet, SNIPPET_MAX)}`);
+        }
+    }
+    return parts.join('\n');
+}
+/** 模块级 fetch 覆盖（测试注入）。undefined 时用 createFetch()。 */
+let fetchOverride;
+/** 测试钩子：覆盖默认 fetch（undici ProxyAgent 包装版）。 */
+export function setFetchOverride(f) {
+    fetchOverride = f;
+}
+function currentFetch() {
+    return fetchOverride ?? createFetch();
+}
+/** 工具入口：解析 provider → search → 返回 WebSearchResponse。 */
+export async function runWebSearch(input, config, abort) {
+    const keys = resolveKeys(config);
+    const provider = resolveProvider(config.provider, keys);
+    return provider.search({
+        query: input.query,
+        limit: clampNumResults(input.numResults),
+        recency: input.recency,
+        signal: abort,
+        apiKey: provider.id === 'tavily' ? keys.tavily : provider.id === 'brave' ? keys.brave : undefined,
+        fetchImpl: currentFetch(),
+    });
+}
+export { clampNumResults, DEFAULT_NUM_RESULTS };

package/dist/tools/websearch/providers/brave.d.ts

@@ -0,0 +1,5 @@
+import type { Recency, WebSearchProvider } from '../types.js';
+/** 导出供测试：recency → Brave freshness 代码映射。 */
+export declare function recencyToFreshness(recency: Recency | undefined): string | undefined;
+/** Brave 后端（独立索引，需 key）。 */
+export declare const braveProvider: WebSearchProvider;

package/dist/tools/websearch/providers/brave.js

@@ -0,0 +1,53 @@
+import { DEFAULT_NUM_RESULTS } from '../types.js';
+const BRAVE_SEARCH_URL = 'https://api.search.brave.com/res/v1/web/search';
+/** 导出供测试：recency → Brave freshness 代码映射。 */
+export function recencyToFreshness(recency) {
+    switch (recency) {
+        case 'day':
+            return 'pd';
+        case 'week':
+            return 'pw';
+        case 'month':
+            return 'pm';
+        case 'year':
+            return 'py';
+        default:
+            return undefined;
+    }
+}
+/** Brave 后端（独立索引，需 key）。 */
+export const braveProvider = {
+    id: 'brave',
+    isAvailable: (apiKey) => Boolean(apiKey && apiKey.length > 0),
+    search: async (params) => {
+        if (!params.apiKey)
+            throw new Error('Brave requires an API key (BRAVE_API_KEY or config).');
+        const fetchImpl = params.fetchImpl ?? fetch;
+        const count = params.limit ?? DEFAULT_NUM_RESULTS;
+        const query = new URLSearchParams({ q: params.query, count: String(count) });
+        const freshness = recencyToFreshness(params.recency);
+        if (freshness)
+            query.set('freshness', freshness);
+        const response = await fetchImpl(`${BRAVE_SEARCH_URL}?${query.toString()}`, {
+            method: 'GET',
+            headers: {
+                'X-Subscription-Token': params.apiKey,
+                Accept: 'application/json',
+                'Accept-Encoding': 'gzip',
+            },
+            signal: params.signal,
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => response.statusText);
+            throw new Error(`Brave API error (${response.status}): ${text}`);
+        }
+        const data = (await response.json());
+        const sources = [];
+        for (const r of data.web?.results ?? []) {
+            if (!r.url)
+                continue;
+            sources.push({ title: r.title ?? r.url, url: r.url, snippet: r.description ?? undefined });
+        }
+        return { provider: 'brave', sources };
+    },
+};

package/dist/tools/websearch/providers/duckduckgo.d.ts

@@ -0,0 +1,3 @@
+import type { WebSearchProvider } from '../types.js';
+/** DuckDuckGo Instant Answer 后端（零 key，恒可用）。recency 不支持，忽略。 */
+export declare const duckduckgoProvider: WebSearchProvider;

package/dist/tools/websearch/providers/duckduckgo.js

@@ -0,0 +1,75 @@
+const DUCKDUCKGO_SEARCH_URL = 'https://api.duckduckgo.com/';
+const AGENT_TOKEN = 'c0de-agent';
+function cleanText(value) {
+    const cleaned = value
+        ?.replace(/<[^>]*>/g, ' ')
+        .replace(/&nbsp;/gi, ' ')
+        .replace(/&amp;/gi, '&')
+        .replace(/&lt;/gi, '<')
+        .replace(/&gt;/gi, '>')
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;/gi, "'")
+        .replace(/\s+/g, ' ')
+        .trim();
+    return cleaned ? cleaned : undefined;
+}
+function addSource(sources, source) {
+    if (!source.url || sources.some((s) => s.url === source.url))
+        return;
+    sources.push(source);
+}
+function addTopicSource(sources, topic) {
+    const url = topic.FirstURL?.trim();
+    if (!url)
+        return;
+    const text = cleanText(topic.Text);
+    addSource(sources, { title: text ?? url, url, snippet: text });
+}
+function collectTopicSources(sources, topics) {
+    if (!topics)
+        return;
+    for (const topic of topics) {
+        addTopicSource(sources, topic);
+        collectTopicSources(sources, topic.Topics);
+    }
+}
+async function callDuckDuckGoSearch(params) {
+    const fetchImpl = params.fetchImpl ?? fetch;
+    const query = new URLSearchParams({
+        q: params.query,
+        format: 'json',
+        no_redirect: '1',
+        no_html: '1',
+        skip_disambig: '1',
+        t: AGENT_TOKEN,
+    });
+    const response = await fetchImpl(`${DUCKDUCKGO_SEARCH_URL}?${query.toString()}`, {
+        method: 'GET',
+        signal: params.signal,
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => response.statusText);
+        throw new Error(`DuckDuckGo API error (${response.status}): ${text}`);
+    }
+    return (await response.json());
+}
+/** DuckDuckGo Instant Answer 后端（零 key，恒可用）。recency 不支持，忽略。 */
+export const duckduckgoProvider = {
+    id: 'duckduckgo',
+    isAvailable: () => true,
+    search: async (params) => {
+        const data = await callDuckDuckGoSearch(params);
+        const answer = cleanText(data.AbstractText) ?? cleanText(data.Answer) ?? cleanText(data.Definition);
+        const sources = [];
+        // AbstractURL 作为首个来源（若无 RelatedTopics 填充）
+        if (data.AbstractURL) {
+            addSource(sources, {
+                title: cleanText(data.Heading) ?? data.AbstractURL,
+                url: data.AbstractURL,
+            });
+        }
+        collectTopicSources(sources, data.Results);
+        collectTopicSources(sources, data.RelatedTopics);
+        return { provider: 'duckduckgo', answer, sources };
+    },
+};

package/dist/tools/websearch/providers/tavily.d.ts

@@ -0,0 +1,11 @@
+import type { Recency, WebSearchProvider } from '../types.js';
+interface TavilySearchParams {
+    query: string;
+    numResults?: number;
+    recency?: Recency;
+}
+/** 导出供测试：构造 Tavily 请求 body。始终用 general topic（避免技术查询窄化为新闻）。 */
+export declare function buildRequestBody(params: TavilySearchParams): Record<string, unknown>;
+/** Tavily 后端（AI 优化搜索，需 key，返回合成 answer）。 */
+export declare const tavilyProvider: WebSearchProvider;
+export {};

package/dist/tools/websearch/providers/tavily.js

@@ -0,0 +1,89 @@
+import { DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS, MIN_NUM_RESULTS } from '../types.js';
+const TAVILY_SEARCH_URL = 'https://api.tavily.com/search';
+function clamp(n) {
+    if (n === undefined || Number.isNaN(n))
+        return DEFAULT_NUM_RESULTS;
+    return Math.min(MAX_NUM_RESULTS, Math.max(MIN_NUM_RESULTS, Math.trunc(n)));
+}
+/** 导出供测试：构造 Tavily 请求 body。始终用 general topic（避免技术查询窄化为新闻）。 */
+export function buildRequestBody(params) {
+    const body = {
+        query: params.query,
+        search_depth: 'basic',
+        max_results: clamp(params.numResults),
+        include_answer: 'advanced',
+        include_raw_content: false,
+    };
+    if (params.recency)
+        body.time_range = params.recency;
+    return body;
+}
+function safeParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : null;
+}
+function getErrorMessage(value) {
+    if (typeof value === 'string') {
+        const t = value.trim();
+        return t.length > 0 ? t : null;
+    }
+    const rec = asRecord(value);
+    if (!rec)
+        return null;
+    for (const key of ['detail', 'error', 'message']) {
+        const m = getErrorMessage(rec[key]);
+        if (m)
+            return m;
+    }
+    return null;
+}
+async function callTavilySearch(apiKey, params) {
+    const fetchImpl = params.fetchImpl ?? fetch;
+    const response = await fetchImpl(TAVILY_SEARCH_URL, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify(buildRequestBody({
+            query: params.query,
+            numResults: params.limit,
+            recency: params.recency,
+        })),
+        signal: params.signal,
+    });
+    if (!response.ok) {
+        const raw = await response.text().catch(() => response.statusText);
+        const msg = getErrorMessage(safeParse(raw)) ?? (raw.trim() || response.statusText);
+        throw new Error(`Tavily API error (${response.status}): ${msg}`);
+    }
+    return (await response.json());
+}
+/** Tavily 后端（AI 优化搜索，需 key，返回合成 answer）。 */
+export const tavilyProvider = {
+    id: 'tavily',
+    isAvailable: (apiKey) => Boolean(apiKey && apiKey.length > 0),
+    search: async (params) => {
+        if (!params.apiKey)
+            throw new Error('Tavily requires an API key (TAVILY_API_KEY or config).');
+        const data = await callTavilySearch(params.apiKey, params);
+        const sources = [];
+        for (const r of data.results ?? []) {
+            if (!r.url)
+                continue;
+            sources.push({ title: r.title ?? r.url, url: r.url, snippet: r.content ?? undefined });
+        }
+        return {
+            provider: 'tavily',
+            answer: data.answer?.trim() || undefined,
+            sources: sources.slice(0, clamp(params.limit)),
+        };
+    },
+};

package/dist/tools/websearch/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * websearch 工具的统一类型、常量与工具函数。
+ *
+ * 来源：oh-my-pi（packages/coding-agent/src/web/search/）多后端 strategy 架构，
+ * 裁剪适配 c0de-agent 的 data+functions 范式（无 class）。
+ * 详见 docs/superpowers/specs/2026-06-30-websearch-tool-design.md §2-3。
+ */
+/** 后端标识。strategy 接口预留，未来可加 'exa' | 'searxng' | … */
+type WebSearchProviderId = 'duckduckgo' | 'tavily' | 'brave';
+/** 时效过滤窗口。各后端映射为各自 API 参数。 */
+type Recency = 'day' | 'week' | 'month' | 'year';
+/** 单条搜索来源（所有后端统一）。 */
+type WebSearchSource = {
+    title: string;
+    url: string;
+    snippet?: string;
+};
+/** 统一搜索参数。 */
+type WebSearchParams = {
+    query: string;
+    limit?: number;
+    recency?: Recency;
+    signal?: AbortSignal;
+    /** Tavily/Brave 的 key（DuckDuckGo 不用）。 */
+    apiKey?: string;
+    /** 测试注入；默认用 createFetch()。 */
+    fetchImpl?: typeof fetch;
+};
+/** 统一响应（所有后端统一）。 */
+type WebSearchResponse = {
+    provider: WebSearchProviderId;
+    /** Tavily 返回合成答案；DuckDuckGo/Brave 通常无。 */
+    answer?: string;
+    sources: WebSearchSource[];
+};
+/** 后端 strategy 接口（data + functions，非 class）。 */
+type WebSearchProvider = {
+    id: WebSearchProviderId;
+    /** 是否当前可用（DuckDuckGo 恒真；Tavily/Brave 需 key）。驱动 'auto' 选择。 */
+    isAvailable: (apiKey?: string) => boolean;
+    /** 执行搜索。 */
+    search: (params: WebSearchParams) => Promise<WebSearchResponse>;
+};
+/** 工具参数校验常量。 */
+declare const DEFAULT_NUM_RESULTS = 8;
+declare const MAX_NUM_RESULTS = 20;
+declare const MIN_NUM_RESULTS = 1;
+/** clamp 结果数到 [MIN, MAX]；undefined/NaN 回退到 fallback。 */
+declare function clampNumResults(n: number | undefined, fallback?: number): number;
+export type { Recency, WebSearchParams, WebSearchProvider, WebSearchProviderId, WebSearchResponse, WebSearchSource, };
+export { clampNumResults, DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS, MIN_NUM_RESULTS };