qwen-code/docs/developers/tools
tanzhenxin 443b81e180
feat(core): add opt-in built-in web_search backed by the DashScope Responses API (#7215)
* feat(core): add opt-in built-in web_search backed by the DashScope Responses API

Claude-Session: https://claude.ai/code/session_01KwsYFzWZ6VLCxVN8MbeFXb

* fix(core): require HTTPS for the web_search backend; fail closed on unresolved agent allow-lists

Review follow-ups on #7215: the endpoint gate now rejects plaintext
endpoints (the side request carries a bearer key), and an agent allow-list
whose names resolve to no registered tool keeps its dead entries instead of
widening to the inherited toolset — an agent restricted to the unavailable
WebSearch now runs tool-less rather than gaining shell/write.

Claude-Session: https://claude.ai/code/session_01KwsYFzWZ6VLCxVN8MbeFXb

* chore(cli): remove test-leaked debug artifacts; gitignore the leaked dirs

The CLI unit-test suites write debug logs relative to the package dir
(custom/, first/, from-env/, workspace/); a merge-commit git add swept
them in. Remove them and ignore the directories until the tests are
pointed at temp dirs.

Claude-Session: https://claude.ai/code/session_01KwsYFzWZ6VLCxVN8MbeFXb

* fix(core): honor web_search's own result budget and salvage in-stream-error partials

- Override maxOutputChars (result limit + envelope headroom) so the
  scheduler's global 25k threshold no longer slices results before the
  tool's section-aware truncation can protect URL evidence sections.
- Route in-stream backend errors through the shared terminal-failure
  tail so results streamed (and billed) before the error surface as a
  partial result, matching the transport-error path.
- Strengthen gate tests: assert gate.ok before webExtractor, exercise
  the https-only endpoint guard, and make the config mock disambiguate
  same-id entries by baseUrl like the real Config.

* fix(cli): treat whitespace-only WEB_SEARCH_API_KEY as unset

Apply the function's set-but-empty-is-unset rule to the API key env
var like every sibling env read, and add loadCliConfig coverage for
the web search settings resolution (env precedence, empty-env
fallthrough, base-URL key selection).

* fix(core): salvage failed-terminal web_search results and name the exact endpoint disqualifier

- Route the failed/cancelled terminal paths through the shared
  terminal-failure tail so search evidence streamed (and billed) before
  the backend gave up is salvaged, consistent with the in-stream-error
  and transport-error paths; regression test included.
- Classify base-URL gate rejections so the startup notice blames the
  actual disqualifier: a plaintext-HTTP endpoint now gets an "use
  https://" notice at both the env-declared and modelProviders sites
  instead of the misleading "non-DashScope endpoint" text.
- Cover WEB_SEARCH in the speculation boundary-tools test and the US
  regional host in the DashScope provider test — both behavioral
  changes this PR introduced without direct test coverage.

* test(cli): cover web search suppression in safe and bare modes

The bareMode/safeMode guard is the escape hatch that keeps web search
(external, billed API calls) off in troubleshooting modes; assert that
an enabled settings config resolves to no web search settings under
--safe-mode and --bare.

* fix(core): parse the search model selector once for both gate paths

A selector written for the modelProviders path ("openai:<model-id>", as
the gate's own OAuth notice suggests) was sent verbatim to DashScope
when WEB_SEARCH_BASE_URL overrode the backend, failing with
InvalidParameter. Hoist the resolveModelId parse above the env branch
so both paths share one interpretation of the selector.

Also cover two review gaps: the Claude extension WebSearch tool mapping
and the ACP startup-warning emission that surfaces WebSearch
misconfiguration notices in the client log.

* fix(core): handle response.cancelled in the web_search terminal-event switch and trim gate env keys

- Add response.cancelled to the terminal-event switch so the
  status === 'cancelled' handler is reachable instead of dead code
- Trim API key env vars in the gate (all three check sites), matching
  the CLI-side whitespace rule from 302cf3bb7
- Add tests: cancelled with/without prior search, whitespace-only env
  key rejection, schema getter month/year embedding

* fix(core): cap opened URLs, suppress failed-item progress, note retry budget (#7215)

* fix(core): reject unresolved selector on env-declared web_search path (#7215)

---------

Co-authored-by: Qwen Code Bot <qwen-code-bot@users.noreply.github.com>
2026-07-21 10:59:36 +00:00
..
_meta.ts docs(tools): document monitor tool (#4356) 2026-05-25 15:25:07 +08:00
exit-plan-mode.md fix(core): Require explicit approval to exit Plan mode (#6967) 2026-07-17 02:51:11 +00:00
file-system.md feat(core): add PDF vision bridge fallback (#6846) 2026-07-15 03:42:14 +00:00
introduction.md fix(core): Align MCP OAuth guidance and docs (#5589) 2026-06-24 07:09:53 +08:00
mcp-server.md fix(core): Align MCP OAuth guidance and docs (#5589) 2026-06-24 07:09:53 +08:00
monitor.md docs(tools): document monitor tool (#4356) 2026-05-25 15:25:07 +08:00
multi-file.md docs: fix stale defaults, CLI syntax, and tool naming drift (#5158) 2026-06-15 20:06:34 +08:00
sandbox.md Merge branch 'main' into feat/sandbox-config-improvements 2026-03-06 14:38:39 +08:00
shell.md fix(shell): avoid Unix pager default on Windows (#6390) 2026-07-07 06:16:18 +00:00
task.md feat(core): add fork_turns to fork subagents (#7346) 2026-07-21 07:08:12 +00:00
todo-write.md docs: fix stale defaults, CLI syntax, and tool naming drift (#5158) 2026-06-15 20:06:34 +08:00
web-fetch.md fix(core): allow web_fetch JSON fallback (#5660) 2026-06-24 14:18:33 +00:00
web-search.md feat(core): add opt-in built-in web_search backed by the DashScope Responses API (#7215) 2026-07-21 10:59:36 +00:00