WeKnora/internal/agent/tools
Jundong Zhang 40eb34bc84
fix(agent): align web_search count limit with the configured maximum (#4011)
* fix(agent): align web_search count limit with the configured maximum

count 的参数描述写死了 "at most 20",而实际生效的上限来自 agent 配置
(web_search_max_results,常见值 7)。模型按描述填 8/20 就会被 Execute 里的
"count must be between 1 and N" 硬拒——那一轮连 provider 都没被调用,而且在
trace 里与真正的故障同为 span error,无法区分。

- count 的静态描述去掉写死的 20;NewWebSearchTool 再按实际生效的 maxResults
  动态改写 schema 描述(解析失败原样返回,不影响工具可用性)
- count 超范围由"整轮失败"改为"截断到上限",输出里附一句纠正提示,日志降为 Warn。
  同类标量 search_knowledge.limit / search_memory.limit 走的也是截断;且工具本来
  就会静默返回少于 count 条(结果被 URL 校验过滤时 break),同一字段不该两套策略

行为变更:count 传 0/负数/超过上限不再返回 Success=false,而是按上限执行。
TestSearchOptionsAndExplicitPageContent 原先把 count 与非法过滤值并列断言
"必须失败且不得调用 provider",该断言已相应调整,新行为由
TestAgentWebSearchClampsCountToConfiguredMaximum 覆盖。

测试:go test ./internal/agent/tools/... -count=1

* fix(agent): clamp only an over-maximum web_search count

count is documented as 1..maximum, so a value below 1 is a malformed
argument rather than a near miss: reject it before the provider runs and
restore the previous message ("count must be between 1 and N"). Only a
count above the configured maximum is clamped, which keeps the change
scoped to the near-miss case it was meant to fix.

The correction now travels in Data as well as Output. web_search enables
sourceOutput, so once there is at least one row the model reads the
rendered retrieval block, which is rebuilt from Data["results"]; the note
written to Output never reached it. annotateWebSearchNotes restates the
clamp as <count_clamped> inside that block, the same way
annotateSearchNotes surfaces <omitted> and <subset>. The zero-result early
return carries the note too, instead of returning before it is built.

Also documents the clamping in website-docs and moves the added comments
back to English, keeping only the ones that describe what the code does.
2026-10-10 10:27:52 +08:00
..
browserskill.go fix(browser): let shared-space agents drive the caller's local browser 2026-09-24 18:19:17 +08:00
browserskill_image.go fix(browser): complete task cancellation, screenshots, and result display (#3206) 2026-09-12 09:32:26 +08:00
browserskill_image_test.go fix(browser): complete task cancellation, screenshots, and result display (#3206) 2026-09-12 09:32:26 +08:00
browserskill_prompt.go chore: update BrowserSkill extension version to 0.3.1 and enhance localization support 2026-09-23 17:12:19 +08:00
browserskill_result.go fix(browser): use unmodified BrowserSkill upstream and remove downstream patches (#3563) 2026-09-23 00:22:34 +08:00
browserskill_result_test.go fix(agent): give local_browser one text cap and per-method signatures 2026-09-23 11:49:39 +08:00
browserskill_schema.go fix(agent): give local_browser one text cap and per-method signatures 2026-09-23 11:49:39 +08:00
browserskill_schema_test.go fix(agent): give local_browser one text cap and per-method signatures 2026-09-23 11:49:39 +08:00
browserskill_test.go fix(browser): let shared-space agents drive the caller's local browser 2026-09-24 18:19:17 +08:00
capabilities.go revert: take the plugin system back out of main 2026-09-26 14:58:18 +08:00
chunk_snippet.go refactor(agent): consolidate knowledge retrieval tools into search_knowledge, read_document, list_documents (#3381) 2026-09-18 14:12:22 +08:00
chunk_snippet_test.go fix(retrieval): fix recall correctness, score scales, cost and agent tools (#3687) 2026-09-25 10:48:18 +08:00
data_analysis.go fix(data-analysis): skip style-only worksheets before DuckDB loading (#3660) 2026-10-08 13:04:29 +08:00
data_analysis_duckdb_test.go test(agent): add end-to-end DuckDB excel tests and fix sheet enumeration (#1007) 2026-04-24 19:57:56 +08:00
data_analysis_empty_sheet_test.go fix(data-analysis): skip style-only worksheets before DuckDB loading (#3660) 2026-10-08 13:04:29 +08:00
data_analysis_materialize_test.go fix: deep-copy stored files and images when cloning a knowledge base 2026-06-03 14:45:59 +08:00
data_analysis_query_test.go refactor(modelcontext): consolidate source_refs parsing, fixed data_analysis table, and identifier leak report (#3372) 2026-09-17 22:08:16 +08:00
data_analysis_reconcile_test.go fix(agent): 保留数据分析 SQL 字符串字面量 (#3812) 2026-10-08 01:22:11 +08:00
data_analysis_recovery_test.go fix: keep failed data-analysis table loads retryable (#3745) 2026-10-08 01:20:48 +08:00
data_analysis_test.go feat(memory): add cross-session long-term memory 2026-08-13 18:00:02 +08:00
data_schema.go refactor(modelcontext): consolidate source_refs parsing, fixed data_analysis table, and identifier leak report (#3372) 2026-09-17 22:08:16 +08:00
database_query.go fix(agent): exclude disabled FAQ entries 2026-07-29 14:40:54 +08:00
database_query_test.go fix(agent): exclude disabled FAQ entries 2026-07-29 14:40:54 +08:00
definitions.go refactor(agent): consolidate knowledge retrieval tools into search_knowledge, read_document, list_documents (#3381) 2026-09-18 14:12:22 +08:00
definitions_test.go refactor(agent): consolidate knowledge retrieval tools into search_knowledge, read_document, list_documents (#3381) 2026-09-18 14:12:22 +08:00
excel_sheets.go fix(data-analysis): skip style-only worksheets before DuckDB loading (#3660) 2026-10-08 13:04:29 +08:00
exec_context.go feat: scope API MCP OAuth by principal 2026-06-30 20:01:05 +08:00
execution_policy.go refactor(agent): consolidate knowledge retrieval tools into search_knowledge, read_document, list_documents (#3381) 2026-09-18 14:12:22 +08:00
faq_snippet.go fix(retrieval): fix recall correctness, score scales, cost and agent tools (#3687) 2026-09-25 10:48:18 +08:00
faq_snippet_test.go feat(faq): enhance FAQ handling and localization support 2026-06-04 21:43:16 +08:00
file_mutation_queue.go feat(agent): unify sandbox tools and drop host preloaded skills (#3033) 2026-09-05 16:45:59 +08:00
file_mutation_queue_test.go feat(agent): keep long sandbox turns from truncating, overflowing, or rewriting files 2026-09-02 22:09:09 +08:00
goroutine.go fix(agent): 工具自起 goroutine 的 panic 自行兜底,MCP 预热不再带走进程 (#3846) 2026-10-08 01:24:36 +08:00
goroutine_test.go fix(agent): 工具自起 goroutine 的 panic 自行兜底,MCP 预热不再带走进程 (#3846) 2026-10-08 01:24:36 +08:00
image_markdown_output_test.go refactor(agent): consolidate knowledge retrieval tools into search_knowledge, read_document, list_documents (#3381) 2026-09-18 14:12:22 +08:00
json_repair.go feat(agent): keep long sandbox turns from truncating, overflowing, or rewriting files 2026-09-02 22:09:09 +08:00
json_repair_test.go fix(agent): recover tool arguments with a stray trailing fragment 2026-09-02 10:12:55 +08:00
list_documents.go refactor(agent): consolidate knowledge retrieval tools into search_knowledge, read_document, list_documents (#3381) 2026-09-18 14:12:22 +08:00
list_documents_test.go refactor(agent): consolidate knowledge retrieval tools into search_knowledge, read_document, list_documents (#3381) 2026-09-18 14:12:22 +08:00
mcp_catalog.go fix(chat): preserve steering continuity and composer focus 2026-09-09 20:15:23 +08:00
mcp_catalog_integration_test.go feat(mcp)!: persist tool catalogs and add guided configuration (#3118) 2026-09-09 13:34:56 +08:00
mcp_catalog_regression_test.go feat(mcp)!: persist tool catalogs and add guided configuration (#3118) 2026-09-09 13:34:56 +08:00
mcp_catalog_test.go fix(mcp): normalize JSON-encoded argument envelopes 2026-09-09 16:11:52 +08:00
mcp_directory_test.go feat(mcp)!: persist tool catalogs and add guided configuration (#3118) 2026-09-09 13:34:56 +08:00
mcp_exposure.go fix(agent): 工具自起 goroutine 的 panic 自行兜底,MCP 预热不再带走进程 (#3846) 2026-10-08 01:24:36 +08:00
mcp_exposure_panic_test.go fix(agent): 工具自起 goroutine 的 panic 自行兜底,MCP 预热不再带走进程 (#3846) 2026-10-08 01:24:36 +08:00
mcp_exposure_test.go feat(mcp)!: streamline setup and use short routing handles 2026-09-09 16:11:52 +08:00
mcp_oauth.go refactor(agent): discover and invoke MCP tools on demand 2026-09-08 12:01:36 +08:00
mcp_schema.go refactor(agent): discover and invoke MCP tools on demand 2026-09-08 12:01:36 +08:00
mcp_schema_test.go refactor(agent): discover and invoke MCP tools on demand 2026-09-08 12:01:36 +08:00
mcp_tool.go fix(mcp): pass embedded resources in tool results to the agent (#3766) 2026-10-08 01:25:04 +08:00
mcp_tool_enabled_test.go feat(mcp): add per-tool enable toggle (#2989) 2026-09-05 17:19:20 +08:00
mcp_tool_image_test.go feat: auto-describe MCP tool result images via VLM 2026-03-25 21:38:15 +08:00
mcp_tool_resource_test.go fix(mcp): pass embedded resources in tool results to the agent (#3766) 2026-10-08 01:25:04 +08:00
mcp_tool_test.go feat(tests): add comprehensive tests for MCPTool functionality 2026-03-25 22:08:29 +08:00
mcp_tool_timeout_test.go fix(agent): honor MCP service advanced_config.timeout for CallTool window 2026-09-11 17:47:04 +08:00
normalize_id.go feat(agent): enhance tool execution and message sanitization 2026-03-25 22:08:29 +08:00
normalize_id_test.go feat(agent): enhance tool execution and message sanitization 2026-03-25 22:08:29 +08:00
output_budget.go fix(agent): keep batched wiki_read_page results within output budget 2026-07-27 13:22:16 +08:00
output_budget_test.go fix(agent): keep batched wiki_read_page results within output budget 2026-07-27 13:22:16 +08:00
output_links.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
output_links_test.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
param_cast.go fix(agent): preserve untouched numeric tool arguments during casting (#3936) 2026-10-08 13:14:18 +08:00
param_cast_preserve_test.go fix(agent): preserve untouched numeric tool arguments during casting (#3936) 2026-10-08 13:14:18 +08:00
param_cast_test.go refactor(prompt): streamline context handling in templates 2026-03-25 22:08:29 +08:00
param_validate.go fix(agent): compare tool enum values without string coercion 2026-10-08 21:07:11 +08:00
param_validate_enum_test.go fix(agent): compare tool enum values without string coercion 2026-10-08 21:07:11 +08:00
param_validate_test.go feat(agent): implement memory consolidation and context management 2026-03-25 22:08:29 +08:00
param_validate_unicode_test.go fix(agent): validate tool string lengths by Unicode code points (#3937) 2026-10-08 01:22:18 +08:00
persist.go feat: judge image hits by their image in rerank and show them to vision models (#4013) 2026-10-09 13:01:48 +08:00
persist_test.go refactor(agent): consolidate knowledge retrieval tools into search_knowledge, read_document, list_documents (#3381) 2026-09-18 14:12:22 +08:00
python_syntax.go feat(agent): unify sandbox tools and drop host preloaded skills (#3033) 2026-09-05 16:45:59 +08:00
python_syntax_test.go refactor(skills): introduce write_skill_file and edit_skill_file tools for skill directory management 2026-09-02 15:08:05 +08:00
query_knowledge_graph.go fix(graph): preserve relationship direction and document provenance (#3950) 2026-10-08 00:48:51 +08:00
query_knowledge_graph_graph_test.go fix(graph): preserve relationship direction and document provenance (#3950) 2026-10-08 00:48:51 +08:00
query_knowledge_graph_test.go feat: judge image hits by their image in rerank and show them to vision models (#4013) 2026-10-09 13:01:48 +08:00
query_knowledge_graph_truncation_test.go fix(agent): 图谱查询的三处截断必须可见,模型不再把子图当全集 (#3885) 2026-10-07 23:59:50 +08:00
read_document.go fix(chat): restore citation source navigation and soften highlights 2026-10-08 16:59:50 +08:00
read_document_test.go fix(chat): restore citation source navigation and soften highlights 2026-10-08 16:59:50 +08:00
read_file.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
read_file_test.go fix(sandbox): separate file access from artifact publishing (#3356) 2026-09-17 16:18:01 +08:00
read_web_page.go fix(agent): improve web search and persistent page reading (#3086) 2026-09-07 23:09:27 +08:00
registry.go fix(agent): 工具自起 goroutine 的 panic 自行兜底,MCP 预热不再带走进程 (#3846) 2026-10-08 01:24:36 +08:00
registry_outcome_test.go fix(agent): recover tool panics instead of crashing the server 2026-09-25 18:22:14 +08:00
registry_test.go fix(agent/tools): sort function definitions for deterministic ordering 2026-05-25 16:47:14 +08:00
sandbox_diff.go feat(agent): stream live +/- progress for sandbox write and edit 2026-09-02 23:36:58 +08:00
sandbox_diff_test.go feat(agent): stream live +/- progress for sandbox write and edit 2026-09-02 23:36:58 +08:00
sandbox_edit.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
sandbox_edit_test.go feat(agent): stream live +/- progress for sandbox write and edit 2026-09-02 23:36:58 +08:00
sandbox_ls.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
sandbox_write.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
sandbox_write_test.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
sanitize_messages.go fix(agent): 合并相邻 assistant 消息时保留 tool_calls,避免孤儿 tool 消息导致整轮 400 (#3574) 2026-09-25 18:47:55 +08:00
sanitize_messages_test.go fix(agent): 合并相邻 assistant 消息时保留 tool_calls,避免孤儿 tool 消息导致整轮 400 (#3574) 2026-09-25 18:47:55 +08:00
schema_validity_test.go refactor(agent): consolidate knowledge retrieval tools into search_knowledge, read_document, list_documents (#3381) 2026-09-18 14:12:22 +08:00
scope_authorization.go refactor(agent): consolidate knowledge retrieval tools into search_knowledge, read_document, list_documents (#3381) 2026-09-18 14:12:22 +08:00
scope_authorization_test.go fix(agent): exclude disabled FAQ entries 2026-07-29 14:40:54 +08:00
search_conversations.go refactor(agent): consolidate knowledge retrieval tools into search_knowledge, read_document, list_documents (#3381) 2026-09-18 14:12:22 +08:00
search_knowledge.go feat: judge image hits by their image in rerank and show them to vision models (#4013) 2026-10-09 13:01:48 +08:00
search_knowledge_images_test.go feat: judge image hits by their image in rerank and show them to vision models (#4013) 2026-10-09 13:01:48 +08:00
search_knowledge_metadata_test.go refactor(agent): consolidate knowledge retrieval tools into search_knowledge, read_document, list_documents (#3381) 2026-09-18 14:12:22 +08:00
search_knowledge_rerank_test.go fix(retrieval): fix recall correctness, score scales, cost and agent tools (#3687) 2026-09-25 10:48:18 +08:00
search_knowledge_test.go fix(retrieval): fix recall correctness, score scales, cost and agent tools (#3687) 2026-09-25 10:48:18 +08:00
search_memory.go feat(memory): introduce long-term memory feature with i18n updates 2026-08-13 18:00:02 +08:00
search_memory_test.go feat(memory): introduce long-term memory feature with i18n updates 2026-08-13 18:00:02 +08:00
sequentialthinking.go refactor(agent): consolidate knowledge retrieval tools into search_knowledge, read_document, list_documents (#3381) 2026-09-18 14:12:22 +08:00
shell_command_output.go feat(sandbox): stream live shell and install command output 2026-09-12 10:16:39 +08:00
shell_command_output_test.go feat(sandbox): stream live shell and install command output 2026-09-12 10:16:39 +08:00
shell_env_extract.go feat(localsandbox): add host OS sandbox core and macOS Seatbelt backend (#3472) 2026-09-21 13:24:05 +08:00
shell_env_extract_test.go fix(sandbox): make skill env capture fill blanks only 2026-08-27 14:32:00 +08:00
shell_exec.go feat(lite): install and run skills on the host (#3661) 2026-09-24 21:30:34 +08:00
shell_exec_test.go feat(lite): install and run skills on the host (#3661) 2026-09-24 21:30:34 +08:00
shell_runtime_integration_test.go feat(sandbox): run sandboxed execs as root by default (#3067) 2026-09-07 13:03:35 +08:00
shell_stdin_test.go feat(agent): unify sandbox tools and drop host preloaded skills (#3033) 2026-09-05 16:45:59 +08:00
skill_file.go feat(agent): keep long sandbox turns from truncating, overflowing, or rewriting files 2026-09-02 22:09:09 +08:00
skill_file_test.go refactor(skills): introduce write_skill_file and edit_skill_file tools for skill directory management 2026-09-02 15:08:05 +08:00
skill_file_tree_test.go feat(agent): keep long sandbox turns from truncating, overflowing, or rewriting files 2026-09-02 22:09:09 +08:00
skill_resources.go feat(agent): unify sandbox tools and drop host preloaded skills (#3033) 2026-09-05 16:45:59 +08:00
skill_runtime_guard.go feat(sandbox): run sandboxed execs as root by default (#3067) 2026-09-07 13:03:35 +08:00
skill_runtime_guard_test.go feat(sandbox): run sandboxed execs as root by default (#3067) 2026-09-07 13:03:35 +08:00
strip_think.go fix(agent): end the turn when the completion cap truncates an answer (#3449) 2026-09-20 13:17:50 +08:00
strip_think_test.go refactor(agent): remove query display from DatabaseQuery component and update tool result structure 2026-03-25 22:08:29 +08:00
think_stream.go feat(agent): enhance event routing for reasoning and answers in streaming 2026-06-04 15:48:04 +08:00
think_stream_test.go feat(agent): enhance event routing for reasoning and answers in streaming 2026-06-04 15:48:04 +08:00
todo_write.go refactor(agent): consolidate knowledge retrieval tools into search_knowledge, read_document, list_documents (#3381) 2026-09-18 14:12:22 +08:00
tool.go feat: use language-neutral English prompts for multilingual LLM responses 2026-03-06 21:08:12 +08:00
tool_policy_coverage_test.go refactor(agent): consolidate knowledge retrieval tools into search_knowledge, read_document, list_documents (#3381) 2026-09-18 14:12:22 +08:00
truncate.go fix(agent): keep batched wiki_read_page results within output budget 2026-07-27 13:22:16 +08:00
truncate_test.go feat(agent): implement memory consolidation and context management 2026-03-25 22:08:29 +08:00
web_fetch.go fix(agent): improve web search and persistent page reading (#3086) 2026-09-07 23:09:27 +08:00
web_fetch_test.go fix(agent): improve web search and persistent page reading (#3086) 2026-09-07 23:09:27 +08:00
web_pages_test.go fix(agent): align web_search count limit with the configured maximum (#4011) 2026-10-10 10:27:52 +08:00
web_search.go fix(agent): align web_search count limit with the configured maximum (#4011) 2026-10-10 10:27:52 +08:00
web_search_test.go fix(agent): align web_search count limit with the configured maximum (#4011) 2026-10-10 10:27:52 +08:00
wiki_delete_page.go feat(wiki): add page revision history with diff, revert, and manual editing 2026-07-27 15:03:24 +08:00
wiki_flag_issue.go refactor(modelcontext): consolidate source_refs parsing, fixed data_analysis table, and identifier leak report (#3372) 2026-09-17 22:08:16 +08:00
wiki_index_overview_test.go perf(wiki): move ingest log to event table and index to on-demand API 2026-05-08 21:48:52 +08:00
wiki_link_mutation.go refactor(agent): introduce modelcontext registry and fix handle-codec bugs 2026-07-27 11:05:43 +08:00
wiki_link_mutation_test.go refactor(agent): introduce modelcontext registry and fix handle-codec bugs 2026-07-27 11:05:43 +08:00
wiki_read_issue.go refactor(agent): introduce modelcontext registry and fix handle-codec bugs 2026-07-27 11:05:43 +08:00
wiki_read_page_budget_test.go fix(agent): keep batched wiki_read_page results within output budget 2026-07-27 13:22:16 +08:00
wiki_rename_page.go feat(wiki): add page revision history with diff, revert, and manual editing 2026-07-27 15:03:24 +08:00
wiki_replace_text.go fix(wiki): 唯一写出口 UpdatePage 拦住丢表格行的机器重写(agent 整页写入不再静默改短页面) (#3793) 2026-10-09 10:55:28 +08:00
wiki_replace_text_test.go fix: replace all exact wiki text matches 2026-08-05 19:30:40 +08:00
wiki_route_resolver.go refactor(modelcontext): consolidate source_refs parsing, fixed data_analysis table, and identifier leak report (#3372) 2026-09-17 22:08:16 +08:00
wiki_search_scope_test.go fix(retrieval): fix recall correctness, score scales, cost and agent tools (#3687) 2026-09-25 10:48:18 +08:00
wiki_source_refs.go refactor(modelcontext): consolidate source_refs parsing, fixed data_analysis table, and identifier leak report (#3372) 2026-09-17 22:08:16 +08:00
wiki_source_refs_test.go refactor(modelcontext): consolidate source_refs parsing, fixed data_analysis table, and identifier leak report (#3372) 2026-09-17 22:08:16 +08:00
wiki_tools.go feat(wiki): 增加跨知识库 Wiki 搜索 POST /wiki-search (#3535) 2026-09-25 22:22:58 +08:00
wiki_tools_test.go refactor(agent): consolidate knowledge retrieval tools into search_knowledge, read_document, list_documents (#3381) 2026-09-18 14:12:22 +08:00
wiki_update_issue.go fix(security): close the low-severity shared-space findings (#3416) 2026-09-18 22:58:46 +08:00
wiki_write_page.go refactor(modelcontext): consolidate source_refs parsing, fixed data_analysis table, and identifier leak report (#3372) 2026-09-17 22:08:16 +08:00
wiki_write_page_test.go refactor(agent): introduce modelcontext registry and fix handle-codec bugs 2026-07-27 11:05:43 +08:00
workspace_layout.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
workspace_layout_test.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
workspace_reader.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00
workspace_reader_test.go feat(sandbox): run unpinned Lite sessions on the host OS sandbox (#3549) 2026-09-22 19:35:03 +08:00