qlogicagent 2.13.3 → 2.13.5

package/dist/skills/tools/video-merge-tool.js

@@ -0,0 +1,95 @@
+// ============================================================
+// Video Merge Tool — merge multiple video clips with transitions.
+// Category: media
+// ============================================================
+export const VIDEO_MERGE_TOOL_NAME = "video_merge";
+export const VIDEO_MERGE_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        clips: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    video: { type: "string", description: "Video URL or file path. MUST be publicly accessible HTTP/HTTPS URL. Use file_upload tool first if local file." },
+                    audio: { type: "string", description: "Narration audio file path (from TTS)." },
+                    trimStart: { type: "number", description: "Trim start in seconds (default 0)." },
+                    trimEnd: { type: "number", description: "Trim end in seconds (default: full)." },
+                },
+                required: ["video"],
+            },
+            minItems: 2,
+            description: "Array of video clips to merge, in order.",
+        },
+        transition: {
+            type: "string",
+            description: "Transition effect: 'crossfade' (default), 'fade', 'wipeleft', 'cut', 'dissolve', etc.",
+        },
+        transitionDuration: {
+            type: "number",
+            description: "Transition duration in seconds (0.1-2.0, default 0.5).",
+        },
+        subtitles: {
+            type: "string",
+            description: "Path to SRT subtitle file to burn-in.",
+        },
+        bgm: {
+            type: "string",
+            description: "Background music file path.",
+        },
+        bgmVolume: {
+            type: "number",
+            description: "BGM volume (0.0-1.0, default 0.15).",
+        },
+        outputResolution: {
+            type: "string",
+            description: "Output resolution: '1920x1080', '1080x1920', etc. Default: auto.",
+        },
+        outputFps: {
+            type: "number",
+            description: "Output FPS (default 30).",
+        },
+    },
+    required: ["clips"],
+};
+export function createVideoMergeTool(deps) {
+    return {
+        name: VIDEO_MERGE_TOOL_NAME,
+        label: "Video Merge",
+        searchHint: "video merge concat join stitch transition 视频合并 拼接 合成视频 转场",
+        description: "Merge multiple video clips into a single video with transitions, subtitles, and background music. " +
+            "Requires at least 2 clips. Supports crossfade, fade, wipe, dissolve, and cut transitions. " +
+            "All video/audio URLs MUST be publicly accessible HTTP/HTTPS. " +
+            "Use file_upload tool first if the user provides local files. " +
+            "Audio per clip is preserved; BGM is mixed at adjustable volume.",
+        parameters: VIDEO_MERGE_TOOL_SCHEMA,
+        execute: async (_toolCallId, params) => {
+            if (!params.clips || params.clips.length < 2) {
+                return { content: [{ type: "text", text: "Error: at least 2 clips are required for merging." }] };
+            }
+            const result = await deps.mergeVideos({
+                clips: params.clips,
+                transition: params.transition,
+                transitionDuration: params.transitionDuration,
+                subtitles: params.subtitles,
+                bgm: params.bgm,
+                bgmVolume: params.bgmVolume,
+                outputResolution: params.outputResolution,
+                outputFps: params.outputFps,
+            });
+            const text = `Merged ${result.clipCount} clips → ${result.durationSec.toFixed(1)}s video` +
+                (params.transition ? ` (transition: ${params.transition})` : "");
+            return {
+                content: [{ type: "text", text }],
+                details: {
+                    type: "video_merge",
+                    localPath: result.localPath,
+                    servePath: result.servePath,
+                    durationSec: result.durationSec,
+                    clipCount: result.clipCount,
+                    mediaUrls: result.mediaUrls,
+                },
+            };
+        },
+    };
+}

package/dist/skills/tools/video-upscale-tool.d.ts

@@ -0,0 +1,45 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const VIDEO_UPSCALE_TOOL_NAME: "video_upscale";
+export interface VideoUpscaleToolParams {
+    video: string;
+    targetResolution?: string;
+    sharpness?: string;
+}
+export declare const VIDEO_UPSCALE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly video: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly targetResolution: {
+            readonly type: "string";
+            readonly description: "Target resolution: '1080p' (default, 1920x1080/1080x1920), '2k' (2560x1440/1440x2560).";
+        };
+        readonly sharpness: {
+            readonly type: "string";
+            readonly description: "Sharpening intensity: 'light' (default), 'medium', 'strong'.";
+        };
+    };
+    readonly required: readonly ["video"];
+};
+export interface VideoUpscaleResult {
+    localPath: string;
+    servePath: string;
+    resolution: string;
+    durationSec: number;
+    mediaUrls: string[];
+}
+/** Deps injected by the host runtime for video upscaling. */
+export interface VideoUpscaleToolDeps {
+    /**
+     * Upscale a video via the configured backend (ffmpeg Lanczos + unsharp mask, etc.).
+     * The host handles orientation detection, filter chain, and storage.
+     */
+    upscaleVideo(params: {
+        video: string;
+        targetResolution?: string;
+        sharpness?: string;
+    }): Promise<VideoUpscaleResult>;
+}
+export declare function createVideoUpscaleTool(deps: VideoUpscaleToolDeps): PortableTool<VideoUpscaleToolParams>;

package/dist/skills/tools/video-upscale-tool.js

@@ -0,0 +1,57 @@
+// ============================================================
+// Video Upscale Tool — upscale video resolution + sharpen.
+// Category: media
+// ============================================================
+export const VIDEO_UPSCALE_TOOL_NAME = "video_upscale";
+export const VIDEO_UPSCALE_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        video: {
+            type: "string",
+            description: "Video URL to upscale. MUST be publicly accessible HTTP/HTTPS URL. " +
+                "Use file_upload tool first if the user provides a local file.",
+        },
+        targetResolution: {
+            type: "string",
+            description: "Target resolution: '1080p' (default, 1920x1080/1080x1920), '2k' (2560x1440/1440x2560).",
+        },
+        sharpness: {
+            type: "string",
+            description: "Sharpening intensity: 'light' (default), 'medium', 'strong'.",
+        },
+    },
+    required: ["video"],
+};
+export function createVideoUpscaleTool(deps) {
+    return {
+        name: VIDEO_UPSCALE_TOOL_NAME,
+        label: "Video Upscale",
+        searchHint: "video upscale resolution enhance sharpen 视频超分 高清 提升分辨率 清晰度",
+        description: "Upscale a video to higher resolution with optional sharpening. " +
+            "Auto-detects orientation (landscape/portrait). Uses Lanczos interpolation + unsharp mask. " +
+            "Supports 1080p and 2K targets. " +
+            "Video URL MUST be publicly accessible HTTP/HTTPS. " +
+            "Use file_upload tool first if the user provides a local file. " +
+            "Best used as post-processing after video_merge.",
+        parameters: VIDEO_UPSCALE_TOOL_SCHEMA,
+        execute: async (_toolCallId, params) => {
+            const result = await deps.upscaleVideo({
+                video: params.video,
+                targetResolution: params.targetResolution,
+                sharpness: params.sharpness,
+            });
+            const text = `Upscaled to ${result.resolution}${params.sharpness ? ` (sharpness: ${params.sharpness})` : ""}`;
+            return {
+                content: [{ type: "text", text }],
+                details: {
+                    type: "video_upscale",
+                    localPath: result.localPath,
+                    servePath: result.servePath,
+                    resolution: result.resolution,
+                    durationSec: result.durationSec,
+                    mediaUrls: result.mediaUrls,
+                },
+            };
+        },
+    };
+}

package/dist/skills/tools/voice-clone-tool.d.ts

@@ -0,0 +1,40 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const VOICE_CLONE_TOOL_NAME: "voice_clone";
+export interface VoiceCloneToolParams {
+    text: string;
+    sample_audio_url: string;
+    speed?: number;
+}
+export declare const VOICE_CLONE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly text: {
+            readonly type: "string";
+            readonly description: "Text to synthesize in the cloned voice.";
+        };
+        readonly sample_audio_url: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly speed: {
+            readonly type: "number";
+            readonly description: "Speech speed multiplier (0.5-2.0). Default is 1.0.";
+        };
+    };
+    readonly required: readonly ["text", "sample_audio_url"];
+};
+export interface VoiceCloneResult {
+    mediaUrls: string[];
+    model?: string;
+    voiceId?: string;
+    durationMs?: number;
+}
+/** Deps injected by the host runtime for voice cloning. */
+export interface VoiceCloneToolDeps {
+    cloneVoice(params: {
+        text: string;
+        sampleAudioUrl: string;
+        speed?: number;
+    }): Promise<VoiceCloneResult>;
+}
+export declare function createVoiceCloneTool(deps: VoiceCloneToolDeps): PortableTool<VoiceCloneToolParams>;

package/dist/skills/tools/voice-clone-tool.js

@@ -0,0 +1,58 @@
+// ============================================================
+// Voice Clone Tool — clone a voice from sample audio, then
+// synthesize speech in the cloned voice.
+// Category: media
+// ============================================================
+export const VOICE_CLONE_TOOL_NAME = "voice_clone";
+export const VOICE_CLONE_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        text: {
+            type: "string",
+            description: "Text to synthesize in the cloned voice.",
+        },
+        sample_audio_url: {
+            type: "string",
+            description: "URL of an audio sample (5-30 seconds recommended) of the voice to clone. " +
+                "The sample should be clear speech with minimal background noise. " +
+                "MUST be a publicly accessible HTTP/HTTPS URL. " +
+                "Use file_upload tool first if the user provides a local file.",
+        },
+        speed: {
+            type: "number",
+            description: "Speech speed multiplier (0.5-2.0). Default is 1.0.",
+        },
+    },
+    required: ["text", "sample_audio_url"],
+};
+export function createVoiceCloneTool(deps) {
+    return {
+        name: VOICE_CLONE_TOOL_NAME,
+        label: "Voice Clone",
+        searchHint: "voice clone timbre speaker 音色 克隆 声音克隆 模仿声音",
+        description: "Clone a voice from an audio sample and synthesize new speech in that voice. " +
+            "Requires a clear audio sample (5-30s recommended) of the target voice. " +
+            "Use for personalized narration, character voices, or voice preservation. " +
+            "DO NOT use for impersonation or deception. " +
+            "For standard TTS with preset voices, use the tts tool instead.",
+        parameters: VOICE_CLONE_TOOL_SCHEMA,
+        execute: async (_toolCallId, params) => {
+            const result = await deps.cloneVoice({
+                text: params.text,
+                sampleAudioUrl: params.sample_audio_url,
+                speed: params.speed,
+            });
+            const text = `Voice cloned and synthesized speech${result.model ? ` (model: ${result.model})` : ""}`;
+            return {
+                content: [{ type: "text", text }],
+                details: {
+                    type: "voice_clone",
+                    model: result.model,
+                    voiceId: result.voiceId,
+                    durationMs: result.durationMs,
+                    mediaUrls: result.mediaUrls,
+                },
+            };
+        },
+    };
+}

package/dist/skills/tools/web-answer-tool.d.ts

@@ -0,0 +1,27 @@
+import type { PortableTool } from "../portable-tool.js";
+import type { WebSearchBackend } from "../../runtime/ports/web-search-contracts.js";
+import type { WebFetchToolDeps } from "./web-fetch-tool.js";
+export declare const WEB_ANSWER_TOOL_NAME: "web_answer";
+export interface WebAnswerToolParams {
+    query: string;
+}
+export declare const WEB_ANSWER_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly query: {
+            readonly type: "string";
+            readonly description: "The question to answer using live web search. Be specific and concise.";
+        };
+    };
+    readonly required: readonly ["query"];
+};
+export interface WebAnswerToolDeps {
+    search: WebSearchBackend["search"];
+    fetchUrl: WebFetchToolDeps["fetchUrl"];
+    /**
+     * host 用指定档位 LLM 生成文本(内部 resolveClientForPurpose + transport.stream 累加)。
+     * 无可用模型时返回 null —— 工具据此 fail-loud 降级,不静默编造。
+     */
+    generate(purpose: "smallModel" | "textGeneration", prompt: string, signal: AbortSignal): Promise<string | null>;
+}
+export declare function createWebAnswerTool(deps: WebAnswerToolDeps): PortableTool<WebAnswerToolParams>;

package/dist/skills/tools/web-answer-tool.js

@@ -0,0 +1,124 @@
+// ============================================================
+// Web Answer Tool — 搜索 + 抓正文 + LLM 合成带引用的答案(V1)。
+// Category: web
+// host 注入 search / fetchUrl / generate;generate 由 host 用
+// resolveClientForPurpose + transport.stream 累加实现(隔离 LLM transport 类型)。
+// ============================================================
+export const WEB_ANSWER_TOOL_NAME = "web_answer";
+export const WEB_ANSWER_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        query: {
+            type: "string",
+            description: "The question to answer using live web search. Be specific and concise.",
+        },
+    },
+    required: ["query"],
+};
+const TOP_K_FETCH = 4;
+const PER_PAGE_MAX_CHARS = 4000;
+export function createWebAnswerTool(deps) {
+    return {
+        name: WEB_ANSWER_TOOL_NAME,
+        label: "Web Answer",
+        description: "Answer a question using live web search: searches, reads the top pages, and synthesizes a cited answer " +
+            "with markdown source links. Use when you need a synthesized, well-sourced answer rather than a raw link list.",
+        parameters: WEB_ANSWER_TOOL_SCHEMA,
+        isReadOnly: true,
+        isEgress: true,
+        egressCarriesData: false,
+        execute: async (_toolCallId, params, signal) => {
+            const query = params.query?.trim();
+            if (!query || query.length < 2) {
+                return {
+                    content: [{ type: "text", text: "Error: query must be at least 2 characters." }],
+                    details: { type: "web_answer", error: "invalid_query" },
+                };
+            }
+            // L1:query 改写(口语→检索词,smallModel,§11.1-B 实锤口语 query 召回崩)。
+            // fail-soft:无模型/失败/输出异常 → 用原 query,绝不阻断检索。
+            let searchQuery = query;
+            try {
+                const rewritten = await deps.generate("smallModel", buildRewritePrompt(query), signal);
+                const cleaned = rewritten?.split("\n")[0]?.trim().replace(/^["'`]+|["'`]+$/g, "");
+                if (cleaned && cleaned.length >= 2 && cleaned.length <= 120)
+                    searchQuery = cleaned;
+            }
+            catch {
+                // 改写失败 → 原 query
+            }
+            // L0/L3:检索(多源后端,自带缓存/熔断/硬超时)
+            const searchOut = await deps.search(searchQuery, { maxResults: 6 });
+            if (searchOut.results.length === 0) {
+                return {
+                    content: [{ type: "text", text: `No web results found for: "${query}"` }],
+                    details: { type: "web_answer", query, rewrittenQuery: searchQuery !== query ? searchQuery : undefined, resultCount: 0 },
+                };
+            }
+            // L2:并发抓 top-K 正文(fetchUrl 自管超时)
+            const topK = searchOut.results.slice(0, TOP_K_FETCH);
+            const fetched = await Promise.allSettled(topK.map((r) => deps.fetchUrl({ url: r.url, query: searchQuery, maxChars: PER_PAGE_MAX_CHARS, signal })));
+            const sources = topK.map((r, i) => {
+                const f = fetched[i];
+                const body = f && f.status === "fulfilled" ? f.value.content : r.snippet;
+                return { title: r.title, url: r.url, body };
+            });
+            // L4:合成带引用答案
+            const prompt = buildAnswerPrompt(query, sources);
+            let answer;
+            try {
+                answer = await deps.generate("textGeneration", prompt, signal);
+            }
+            catch (err) {
+                return {
+                    content: [{ type: "text", text: `web_answer synthesis failed: ${err.message}` }],
+                    details: { type: "web_answer", error: "generate_failed" },
+                };
+            }
+            if (!answer) {
+                // fail-loud:无可用文本模型 → 显式降级为来源列表(不静默编造)
+                const list = sources.map((s, i) => `${i + 1}. [${s.title}](${s.url})`).join("\n");
+                return {
+                    content: [{ type: "text", text: `(no text model configured — degraded to source list)\n\n${list}` }],
+                    details: { type: "web_answer", query, degraded: true, resultCount: sources.length },
+                };
+            }
+            return {
+                content: [{ type: "text", text: answer }],
+                details: {
+                    type: "web_answer",
+                    query,
+                    rewrittenQuery: searchQuery !== query ? searchQuery : undefined,
+                    sources: sources.map((s) => ({ title: s.title, url: s.url })),
+                },
+            };
+        },
+    };
+}
+function buildRewritePrompt(query) {
+    return [
+        "Rewrite the user's question into ONE concise web search query (keywords, not a sentence).",
+        "Keep the original language. Preserve technical terms. Output ONLY the query, no quotes, one line.",
+        "",
+        `Question: ${query}`,
+    ].join("\n");
+}
+function buildAnswerPrompt(query, sources) {
+    // 来源用 "Source N:" 呈现(不带方括号),避免诱导模型用 [Source N] 裸标记引用。
+    const blocks = sources
+        .map((s, i) => `Source ${i + 1}: ${s.title}\nURL: ${s.url}\n${s.body.slice(0, PER_PAGE_MAX_CHARS)}`)
+        .join("\n\n---\n\n");
+    return [
+        "You answer the user's question using ONLY the web sources below.",
+        "Write a concise, accurate answer.",
+        "Cite every claim inline as a CLICKABLE markdown link built from the source's title and URL,",
+        "e.g. [Pinecone HNSW guide](https://www.pinecone.io/learn/series/faiss/hnsw/).",
+        "NEVER cite as a bare tag like [Source 1] — always use the [title](url) markdown link form, so citations are clickable.",
+        "If the sources do not contain the answer, say so explicitly. Do not invent facts.",
+        "",
+        `Question: ${query}`,
+        "",
+        "Sources:",
+        blocks,
+    ].join("\n");
+}

package/dist/skills/tools/web-fetch-tool.d.ts

@@ -0,0 +1,80 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const WEB_FETCH_TOOL_NAME: "web_fetch";
+export interface WebFetchToolParams {
+    url: string;
+    extractMode?: "markdown" | "text" | "json";
+    maxChars?: number;
+    query?: string;
+    extract?: boolean;
+    summarize?: boolean;
+}
+export declare const WEB_FETCH_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly url: {
+            readonly type: "string";
+            readonly description: "HTTP or HTTPS URL to fetch.";
+        };
+        readonly extractMode: {
+            readonly type: "string";
+            readonly enum: readonly ["markdown", "text", "json"];
+            readonly description: "Extraction mode: \"markdown\" (default), \"text\", or \"json\" (LLM-driven structured extraction).";
+        };
+        readonly maxChars: {
+            readonly type: "number";
+            readonly description: "Maximum characters to return (truncates when exceeded).";
+            readonly minimum: 100;
+        };
+        readonly query: {
+            readonly type: "string";
+            readonly description: "Original search query. When provided, returns the most query-relevant sections.";
+        };
+        readonly extract: {
+            readonly type: "boolean";
+            readonly description: "When true, returns structured extraction (title, summary, key facts, entities, topics, sentiment).";
+        };
+        readonly summarize: {
+            readonly type: "boolean";
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["url"];
+};
+export interface WebFetchResult {
+    content: string;
+    title?: string;
+    relevantExcerpts?: string[];
+    summary?: string;
+    extraction?: {
+        title?: string;
+        summary?: string;
+        keyFacts?: string[];
+        entities?: string[];
+        topics?: string[];
+        sentiment?: string;
+    };
+}
+/** Deps injected by the host runtime for web fetching. */
+export interface WebFetchToolDeps {
+    /**
+     * Fetch a URL and extract content.
+     * The host handles user-agent rotation, anti-block,
+     * JS rendering, caching, and content extraction.
+     */
+    fetchUrl(params: {
+        url: string;
+        extractMode?: "markdown" | "text" | "json";
+        maxChars?: number;
+        query?: string;
+        extract?: boolean;
+        /** 调用方取消信号(§15-1):用户中断后抓取必须随之中止,不再烧带宽/时间 */
+        signal?: AbortSignal;
+    }): Promise<WebFetchResult>;
+    /**
+     * Optional: summarize long content using a small/cheap model.
+     * When provided and summarize=true is requested, called after fetchUrl.
+     * Should return a concise summary (< 500 chars) preserving key information.
+     */
+    summarizeContent?(content: string, query?: string): Promise<string>;
+}
+export declare function createWebFetchTool(deps: WebFetchToolDeps): PortableTool<WebFetchToolParams>;

package/dist/skills/tools/web-fetch-tool.js

@@ -0,0 +1,95 @@
+// ============================================================
+// Web Fetch Tool — fetch and extract web page content.
+// Category: web
+// ============================================================
+export const WEB_FETCH_TOOL_NAME = "web_fetch";
+export const WEB_FETCH_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        url: {
+            type: "string",
+            description: "HTTP or HTTPS URL to fetch.",
+        },
+        extractMode: {
+            type: "string",
+            enum: ["markdown", "text", "json"],
+            description: 'Extraction mode: "markdown" (default), "text", or "json" (LLM-driven structured extraction).',
+        },
+        maxChars: {
+            type: "number",
+            description: "Maximum characters to return (truncates when exceeded).",
+            minimum: 100,
+        },
+        query: {
+            type: "string",
+            description: "Original search query. When provided, returns the most query-relevant sections.",
+        },
+        extract: {
+            type: "boolean",
+            description: "When true, returns structured extraction (title, summary, key facts, entities, topics, sentiment).",
+        },
+        summarize: {
+            type: "boolean",
+            description: "When true, returns a concise summary (< 500 chars) of the page content. " +
+                "Useful for long pages to reduce context usage while preserving key information.",
+        },
+    },
+    required: ["url"],
+};
+const DEFAULT_MAX_CHARS = 50000;
+export function createWebFetchTool(deps) {
+    return {
+        name: WEB_FETCH_TOOL_NAME,
+        label: "Web Fetch",
+        description: "Fetch content from a URL and extract it as markdown, text, or structured JSON. " +
+            "Supports query-based relevance filtering and structured extraction " +
+            "(title, summary, key facts, entities, topics, sentiment).",
+        parameters: WEB_FETCH_TOOL_SCHEMA,
+        isReadOnly: true,
+        isEgress: true,
+        execute: async (_toolCallId, params, signal) => {
+            const result = await deps.fetchUrl({
+                url: params.url,
+                extractMode: params.extractMode,
+                maxChars: params.maxChars ?? DEFAULT_MAX_CHARS,
+                query: params.query,
+                extract: params.extract,
+                signal,
+            });
+            // Summarization: if requested and content is long enough to warrant it
+            if (params.summarize && deps.summarizeContent && result.content.length > 1000) {
+                const summary = await deps.summarizeContent(result.content, params.query);
+                return {
+                    content: [{ type: "text", text: result.title ? `# ${result.title}\n\n${summary}` : summary }],
+                    details: {
+                        type: "web_fetch",
+                        url: params.url,
+                        summarized: true,
+                        originalLength: result.content.length,
+                        summaryLength: summary.length,
+                    },
+                };
+            }
+            const parts = [];
+            if (result.title)
+                parts.push(`# ${result.title}\n`);
+            parts.push(result.content);
+            if (result.relevantExcerpts?.length) {
+                parts.push("\n---\n## Relevant Excerpts\n");
+                for (const excerpt of result.relevantExcerpts) {
+                    parts.push(`- ${excerpt}`);
+                }
+            }
+            return {
+                content: [{ type: "text", text: parts.join("\n") }],
+                details: {
+                    type: "web_fetch",
+                    url: params.url,
+                    extractMode: params.extractMode ?? "markdown",
+                    hasExtraction: !!result.extraction,
+                    extraction: result.extraction,
+                },
+            };
+        },
+    };
+}

package/dist/skills/tools/web-research-tool.d.ts

@@ -0,0 +1,48 @@
+import type { PortableTool } from "../portable-tool.js";
+import type { WebAnswerToolDeps } from "./web-answer-tool.js";
+export declare const WEB_RESEARCH_TOOL_NAME: "web_research";
+export interface WebResearchToolParams {
+    task: string;
+    budget?: {
+        /** 搜-读-反思轮数上限(默认 2:首轮 + 1 轮 reflect 补搜) */
+        maxRounds?: number;
+        /** 墙钟时间上限 ms(默认 120000) */
+        maxWallClockMs?: number;
+    };
+}
+export declare const WEB_RESEARCH_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly task: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly budget: {
+            readonly type: "object";
+            readonly properties: {
+                readonly maxRounds: {
+                    readonly type: "number";
+                    readonly description: "Max search-read-reflect rounds (default 2).";
+                };
+                readonly maxWallClockMs: {
+                    readonly type: "number";
+                    readonly description: "Max wall-clock time in ms (default 120000).";
+                };
+            };
+            readonly description: "Hard budget caps to prevent runaway research.";
+        };
+    };
+    readonly required: readonly ["task"];
+};
+/** 与 web_answer 同 deps + 可选写记忆(host 注入;无则跳过,details 如实标注)。 */
+export interface WebResearchToolDeps extends WebAnswerToolDeps {
+    /**
+     * 可选:把研究结论写入长期记忆(§14)。内部经 consolidator 去重/重要度过滤(§15-7),
+     * 返回是否成功提交(不保证最终入库条数)。
+     */
+    saveMemory?(text: string, meta: {
+        source: string;
+        category: string;
+    }): Promise<boolean>;
+}
+export declare function createWebResearchTool(deps: WebResearchToolDeps): PortableTool<WebResearchToolParams>;