c0de-agent 0.0.0 → 1.1.0

package/dist/tools/registry.d.ts

@@ -0,0 +1,15 @@
+import type { ChatTool } from '../shared/types/llm.js';
+import type { ToolDef } from '../shared/types/tool.js';
+import type { ToolFactory, ToolFactoryContext, ToolRegistry } from './types.js';
+/** Create an empty tool registry. */
+export declare function createToolRegistry(): ToolRegistry;
+/** Register a fully-constructed tool definition (eager). */
+export declare function registerTool(registry: ToolRegistry, tool: ToolDef): void;
+/** Register a lazy factory that constructs the tool on first access. */
+export declare function registerToolFactory(registry: ToolRegistry, name: string, factory: ToolFactory): void;
+/** Get a tool by name. Triggers and caches lazy factories. Returns undefined if not found. */
+export declare function getTool(registry: ToolRegistry, name: string, ctx?: ToolFactoryContext): ToolDef | undefined;
+/** List all tools. Triggers and caches all lazy factories. */
+export declare function listTools(registry: ToolRegistry, ctx?: ToolFactoryContext): ToolDef[];
+/** Convert registered tools to ChatTool[] for sending to the LLM. */
+export declare function getToolSchemas(registry: ToolRegistry, ctx?: ToolFactoryContext): ChatTool[];

package/dist/tools/registry.js

@@ -0,0 +1,54 @@
+/** Create an empty tool registry. */
+export function createToolRegistry() {
+    return { tools: new Map(), factories: new Map() };
+}
+/** Register a fully-constructed tool definition (eager). */
+export function registerTool(registry, tool) {
+    registry.tools.set(tool.name, tool);
+}
+/** Register a lazy factory that constructs the tool on first access. */
+export function registerToolFactory(registry, name, factory) {
+    registry.factories.set(name, factory);
+}
+/** Get a tool by name. Triggers and caches lazy factories. Returns undefined if not found. */
+export function getTool(registry, name, ctx) {
+    // Check eager tools first
+    const eager = registry.tools.get(name);
+    if (eager)
+        return eager;
+    // Check lazy factories
+    const factory = registry.factories.get(name);
+    if (factory && ctx) {
+        const tool = factory(ctx);
+        if (tool) {
+            registry.tools.set(name, tool); // cache
+            registry.factories.delete(name);
+            return tool;
+        }
+        // Factory returned null → remove
+        registry.factories.delete(name);
+    }
+    return undefined;
+}
+/** List all tools. Triggers and caches all lazy factories. */
+export function listTools(registry, ctx) {
+    // Materialize factories if context is provided
+    if (ctx) {
+        for (const [name, factory] of registry.factories) {
+            const tool = factory(ctx);
+            if (tool) {
+                registry.tools.set(name, tool);
+            }
+            registry.factories.delete(name);
+        }
+    }
+    return Array.from(registry.tools.values());
+}
+/** Convert registered tools to ChatTool[] for sending to the LLM. */
+export function getToolSchemas(registry, ctx) {
+    return listTools(registry, ctx).map((t) => ({
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters,
+    }));
+}

package/dist/tools/resolver.d.ts

@@ -0,0 +1,15 @@
+import type { ResolveResult, URLRegistry, URLResolveContext, URLResolver } from '../shared/types/tool.js';
+/** Create an empty URL resolver registry. */
+declare function createURLRegistry(): URLRegistry;
+/** Register a resolver for its scheme. First registration for a scheme wins;
+ *  later registrations are ignored (stable dispatch, no accidental overrides). */
+declare function registerURLResolver(registry: URLRegistry, resolver: URLResolver): void;
+/** Does `path` carry a `scheme://` prefix? Plain file paths return false. */
+declare function isURLPath(path: string): boolean;
+/** Extract the scheme from a `scheme://…` path, or null for plain file paths.
+ *  Scheme is the run of [a-z0-9+.-] before the first `://`. */
+declare function parseScheme(path: string): string | null;
+/** Resolve a `scheme://…` URL via the registry.
+ *  Returns { _tag: 'error' } for unregistered schemes. */
+declare function resolveURL(registry: URLRegistry, url: string, ctx: URLResolveContext): Promise<ResolveResult>;
+export { createURLRegistry, isURLPath, parseScheme, registerURLResolver, resolveURL };

package/dist/tools/resolver.js

@@ -0,0 +1,47 @@
+/** Create an empty URL resolver registry. */
+function createURLRegistry() {
+    return { resolvers: new Map() };
+}
+/** Register a resolver for its scheme. First registration for a scheme wins;
+ *  later registrations are ignored (stable dispatch, no accidental overrides). */
+function registerURLResolver(registry, resolver) {
+    if (!registry.resolvers.has(resolver.scheme)) {
+        registry.resolvers.set(resolver.scheme, resolver);
+    }
+}
+/** Does `path` carry a `scheme://` prefix? Plain file paths return false. */
+function isURLPath(path) {
+    return parseScheme(path) !== null;
+}
+/** Extract the scheme from a `scheme://…` path, or null for plain file paths.
+ *  Scheme is the run of [a-z0-9+.-] before the first `://`. */
+function parseScheme(path) {
+    const idx = path.indexOf('://');
+    if (idx <= 0)
+        return null;
+    const scheme = path.slice(0, idx);
+    // Schemes are ASCII alphanumeric plus +, -, . (RFC 3986).
+    if (!/^[a-z0-9+.-]+$/i.test(scheme))
+        return null;
+    return scheme.toLowerCase();
+}
+/** Resolve a `scheme://…` URL via the registry.
+ *  Returns { _tag: 'error' } for unregistered schemes. */
+async function resolveURL(registry, url, ctx) {
+    const scheme = parseScheme(url);
+    if (scheme === null) {
+        return { _tag: 'error', error: `Not a URL path: ${url}` };
+    }
+    const resolver = registry.resolvers.get(scheme);
+    if (!resolver) {
+        return { _tag: 'error', error: `No resolver registered for scheme "${scheme}://"` };
+    }
+    try {
+        const content = await resolver.resolve(url, ctx);
+        return { _tag: 'ok', content };
+    }
+    catch (e) {
+        return { _tag: 'error', error: e instanceof Error ? e.message : String(e) };
+    }
+}
+export { createURLRegistry, isURLPath, parseScheme, registerURLResolver, resolveURL };

package/dist/tools/truncate.d.ts

@@ -0,0 +1,8 @@
+import type { TruncateOptions, TruncateResult } from './types.js';
+/** Default truncation thresholds — tuned for LLM context windows. */
+export declare const DEFAULT_TRUNCATE_OPTIONS: TruncateOptions;
+/**
+ * Truncate output to fit within line and character limits.
+ * Preserves head and tail, inserting a marker for omitted content.
+ */
+export declare function truncateOutput(output: string, opts?: TruncateOptions): TruncateResult;

package/dist/tools/truncate.js

@@ -0,0 +1,50 @@
+/** Default truncation thresholds — tuned for LLM context windows. */
+export const DEFAULT_TRUNCATE_OPTIONS = {
+    maxLines: 2000,
+    maxChars: 100_000,
+    headLines: 50,
+    tailLines: 50,
+};
+/**
+ * Truncate output to fit within line and character limits.
+ * Preserves head and tail, inserting a marker for omitted content.
+ */
+export function truncateOutput(output, opts = DEFAULT_TRUNCATE_OPTIONS) {
+    if (output === '') {
+        return { output: '', truncated: false, totalLines: 0, totalChars: 0 };
+    }
+    const lines = output.split('\n');
+    const totalLines = lines.length;
+    const totalChars = output.length;
+    // Check if truncation is needed
+    const needsLineTrunc = totalLines > opts.maxLines;
+    const needsCharTrunc = totalChars > opts.maxChars;
+    if (!needsLineTrunc && !needsCharTrunc) {
+        return { output, truncated: false, totalLines, totalChars };
+    }
+    // Line-based truncation takes priority
+    if (needsLineTrunc) {
+        const head = lines.slice(0, opts.headLines);
+        const tailStart = totalLines - opts.tailLines;
+        // If tail would overlap head, show only head + marker
+        if (tailStart <= opts.headLines) {
+            const omitted = totalLines - head.length;
+            const marker = `[... ${omitted} lines truncated ...]`;
+            return { output: [...head, marker].join('\n'), truncated: true, totalLines, totalChars };
+        }
+        const tail = lines.slice(tailStart);
+        const omitted = totalLines - head.length - tail.length;
+        const marker = `[... ${omitted} lines truncated ...]`;
+        const result = [...head, marker, ...tail].join('\n');
+        return { output: result, truncated: true, totalLines, totalChars };
+    }
+    // Char-based truncation (keep proportional head/tail of chars)
+    const keepChars = opts.maxChars;
+    const headChars = Math.floor(keepChars * 0.5);
+    const tailChars = keepChars - headChars;
+    const head = output.slice(0, headChars);
+    const tail = output.slice(totalChars - tailChars);
+    const omitted = totalChars - keepChars;
+    const marker = `\n[... ${omitted} chars truncated ...]\n`;
+    return { output: head + marker + tail, truncated: true, totalLines, totalChars };
+}

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;