Merge remote-tracking branch 'origin/master' into feat/web-search-card

.agents/notes/implemented/bug-fix/2026-07-30-tui-adapter-registration-race.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-30-tui-adapter-registration-race.md
+2026-07-30-tui-adapter-registration-race.md: fd08e7b6130bc8f7e3cd5287a9970f5fb47244a8
+2026-07-30-tui-adapter-registration-race.zh.md: 0c6bba4bbc8c3303d9c471c3164faa816438b333

.agents/notes/implemented/bug-fix/2026-07-30-tui-adapter-registration-race.md

@@ -0,0 +1,29 @@
+# Agent Note: TUI model-context resolution defers on the adapter-registration race
+
+Status: implemented
+
+English | [中文](2026-07-30-tui-adapter-registration-race.zh.md)
+
+## Problem
+
+Cordis activates plugins by service availability, not configuration order, so the TUI (whose `inject` requires only the `llm` service) can mount before a configured adapter plugin such as `dsh-llm-pi-ai` finishes registering its provider routes. The TUI's model controller resolves the selected model's context window immediately on mount; when the agent's route pointed at a not-yet-registered provider, `resolveModelInfo` rejected with `NO_ADAPTER` and every fresh session printed `Could not resolve model context: no adapter registered for provider "…"` — a spurious error for a fully working configuration (the adapter registered milliseconds later, and chatting worked).
+
+## Decision
+
+The TUI model controller treats a `NO_ADAPTER` rejection of its context-window resolution as a transient state rather than an error: it parks the resolution silently and re-resolves on the next `llm/adapters-updated` commit — the payload-free registry notification `LlmService` already fires at every route commit point. A commit that still lacks the route parks the wait again, so unrelated topology changes stay silent. Any target change re-enters the resolution and clears the pending wait, so the deferred state can never go stale against the current selection; every other resolution error still prints the notice.
+
+## Alternatives considered
+
+**Have the TUI wait for boot to settle before resolving.** The TUI has no Loader dependency (tests and embedders run without one) and "settled" is not observable from inside a plugin; adding a Loader coupling for one cosmetic resolution inverts the dependency direction.
+
+**Poll or retry with a timer.** A timer guesses at activation latency, still mis-prints on a slow adapter, and adds a tunable with no owner. The registry already announces every commit through `llm/adapters-updated`; subscribing is precise and free.
+
+**Order the config so adapters load first.** Row order carries no load semantics in the Loader (activation is service-driven by design), so this cannot be expressed in configuration.
+
+**Suppress NO_ADAPTER errors entirely.** A permanently missing adapter (typo in the provider name) would then never surface in the context-window path. Deferring keeps the signal: a wrong provider name still shows `model unset`-like behavior in the selector and fails loudly at dispatch, while the startup race resolves itself.
+
+**Resolve the context window per submitted message instead of at mount.** The send path already resolves per step (`prepareCall()`), and the indicator is displayed continuously, not only when sending; per-submit display resolution would leave the indicator blank until the first message and re-run adapter I/O for a value that only changes on route changes.
+
+## Consequences
+
+A genuinely misconfigured provider no longer prints the context-resolution error at startup — it surfaces at first dispatch instead, which is where the failure is actionable. The controller subscribes to every `llm/adapters-updated` commit but acts only while a wait is parked; the listener's disposer is released by the channel's `detachListeners()` through the controller's `detach()`, symmetric with the sibling channel listeners. Covered by three TUI tests: the deferred resolution stays silent through an unrelated commit and completes when the route's commit arrives, a target change drops the stale wait, and after channel detach a registry commit no longer re-enters resolution.

.agents/notes/implemented/bug-fix/2026-07-30-tui-adapter-registration-race.zh.md

@@ -0,0 +1,29 @@
+# Agent Note: TUI 模型上下文解析在适配器注册竞争时延后重试
+
+Status: implemented
+
+[English](2026-07-30-tui-adapter-registration-race.md) | 中文
+
+## Problem
+
+Cordis 按服务可用性而非配置顺序激活插件，因此 TUI（其 `inject` 只要求 `llm` 服务）可能在 `dsh-llm-pi-ai` 这类已配置的适配器插件完成提供方路由注册之前就挂载。TUI 的模型控制器在挂载时立即解析所选模型的上下文窗口；当 agent 的路由指向尚未注册的提供方时，`resolveModelInfo` 以 `NO_ADAPTER` 拒绝，于是每个新会话都会打印 `Could not resolve model context: no adapter registered for provider "…"` —— 对一份完全正常的配置报出的虚假错误（适配器几毫秒后就完成注册，对话也一切正常）。
+
+## Decision
+
+TUI 模型控制器把上下文窗口解析中的 `NO_ADAPTER` 拒绝视为瞬态状态而非错误：静默搁置这次解析，并在下一次 `llm/adapters-updated` 提交时重新解析——这是 `LlmService` 本就在每个路由提交点发出的无载荷注册表通知。若某次提交仍缺少该路由，等待会被再次搁置，因此无关的拓扑变化保持沉默。任何目标变更都会重新进入解析并清除挂起的等待，因此延后状态绝不会相对当前选择变陈旧；其他所有解析错误仍照常打印通知。
+
+## Alternatives considered
+
+**让 TUI 等启动结算后再解析。** TUI 不依赖 Loader（测试和嵌入方在没有 Loader 的环境下运行），而且"已结算"在插件内部不可观测；为一次外观性的解析引入 Loader 耦合会颠倒依赖方向。
+
+**用定时器轮询或重试。** 定时器只能猜测激活延迟，遇到慢适配器仍会误报，还会引入一个没有归属者的可调参数。注册表本就通过 `llm/adapters-updated` 公告每次提交；订阅它既精确又零成本。
+
+**调整配置顺序让适配器先加载。** Loader 中行顺序不承载加载语义（激活按设计由服务驱动），因此这无法用配置表达。
+
+**彻底压制 NO_ADAPTER 错误。** 那样的话，永久缺失的适配器（提供方名字拼错）在上下文窗口路径上就永远不会暴露。延后重试保留了信号：错误的提供方名字仍会在选择器中表现出类似 `model unset` 的行为，并在分派时大声失败，而启动竞争则自行化解。
+
+**改为在每次提交消息时解析上下文窗口，而不是在挂载时。** 发送路径本就按步解析（`prepareCall()`），且指示器是持续显示的，不只在发送时；按提交解析显示值会让指示器在首条消息之前一直空白，并为一个仅在路由变化时才变的值反复执行适配器 I/O。
+
+## Consequences
+
+真正配置错误的提供方不再在启动时打印上下文解析错误——它改在首次分派时暴露，那才是该失败可以被处理的地方。控制器订阅每次 `llm/adapters-updated` 提交，但只在有等待被搁置时才动作；监听器的 disposer 经由控制器的 `detach()` 在频道的 `detachListeners()` 中释放，与同级频道监听器保持对称。由三个 TUI 测试覆盖：延后的解析在无关提交中保持沉默、在该路由的提交到来时完成；目标变更丢弃陈旧等待；频道 detach 之后注册表提交不再重新进入解析。

.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.md
+2026-07-31-english-compaction-checkpoints.md: dc95ed187a6ba5b86800f06ebefb2776995f9421
+2026-07-31-english-compaction-checkpoints.zh.md: 7cd4179430ed775f3807af5a02e81838e495c81e

.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.md

@@ -0,0 +1,28 @@
+# Agent Note: Compaction checkpoints use an English engineering register
+
+Status: implemented
+
+English | [中文](2026-07-31-english-compaction-checkpoints.zh.md)
+
+## Problem
+
+A compaction checkpoint becomes part of the next model request's durable prefix. When a multilingual conversation leads the compactor to preserve its narrative material in the conversation language, the checkpoint can introduce a large amount of a language that is absent from the code, tool output, and existing reasoning prefix. That language then persists across later compaction cycles and can influence the conversation model's reasoning register.
+
+## Decision
+
+`COMPACTION_INSTRUCTION` requires an English-language internal engineering checkpoint. It asks the model to translate narrative source material as needed while preserving exact literals, including paths, commands, errors, identifiers, signatures, and quoted wording when exactness matters. The checkpoint's headings and terse engineering bullets remain the existing structured format.
+
+The requirement is integrated into the first sentence of the trailing compaction instruction. The replayed system prompt, tools, and conversation history remain byte-identical to the routed request, so the change retains the prefix-cache reuse owned by the [compaction summary prefix-cache note](2026-07-21-compaction-summary-prefix-cache-reuse.md).
+
+## Alternatives considered
+
+- **Leave checkpoint language to the replayed conversation** — rejected: the checkpoint is a durable prompt prefix, so preserving a transient conversational register can amplify it across later compactions.
+- **Constrain the conversation model's language** — rejected: the policy is for an internal checkpoint, not the user's visible conversation, and a conversation-wide rule would unnecessarily change normal interaction.
+- **Require ASCII-only output** — rejected: ASCII is a character-set constraint rather than an engineering-register constraint and would unnecessarily distort legitimate literals and technical material.
+- **Append a separate final English-only sentence** — rejected: stating the requirement in the instruction's opening output contract is shorter and ties it directly to the checkpoint being requested.
+
+## Consequences
+
+- New checkpoints normalize narrative context into English while retaining the exact strings that future tool use and code work depend on.
+- Existing checkpoint structure, compaction routing, and cache alignment are unchanged; only the final user instruction is different.
+- The direct summarization call remains outside transcript snapshots because it emits no `assistant/chunk` events. The real-loop regression instead asserts the exact final instruction received by the summarization request.

.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.zh.md

@@ -0,0 +1,28 @@
+# Agent Note: 压缩检查点使用英语工程文体
+
+Status: implemented
+
+[English](2026-07-31-english-compaction-checkpoints.md) | 中文
+
+## 问题
+
+压缩（compaction）检查点会成为下一次模型请求中持久存在的前缀。当多语言对话使压缩器以对话语言保留叙述性材料时，检查点可能引入大量代码、工具输出和既有推理（reasoning）前缀中均未出现的语言内容。该语言随后会在后续压缩周期中持续存在，并影响对话模型的推理文体。
+
+## 决策
+
+`COMPACTION_INSTRUCTION` 要求生成英语的内部工程检查点。它要求模型在必要时翻译叙述性源材料，同时保留精确的字面量；这包括路径、命令、错误、标识符、签名，以及精确性重要时的引用措辞。检查点的标题及简洁的工程项目符号仍沿用既有的结构化格式。
+
+这项要求被整合到尾部压缩指令的第一句话中。回放的系统提示词、工具和对话历史与已路由请求保持字节级一致，因此该变更保留 [compaction summary prefix-cache note](2026-07-21-compaction-summary-prefix-cache-reuse.md) 所确立的前缀缓存复用。
+
+## 考虑过的替代方案
+
+- **让回放的对话决定检查点语言**——不采纳：检查点是持久的提示词前缀，保留短暂的对话文体可能在后续压缩中放大这种影响。
+- **约束对话模型的语言**——不采纳：该策略针对内部检查点，而不是用户可见的对话；对整个对话施加规则会不必要地改变正常交互。
+- **要求仅输出 ASCII**——不采纳：ASCII 是字符集约束，而非工程文体约束，并会不必要地扭曲合法的字面量和技术材料。
+- **在末尾追加一句独立的仅限英语要求**——不采纳：在指令开头的输出契约中说明该要求更简洁，也直接将其与所请求的检查点绑定。
+
+## 后果
+
+- 新检查点会将叙述性上下文规范化为英语，同时保留未来工具使用和代码工作所依赖的精确字符串。
+- 既有检查点结构、压缩路由和缓存对齐保持不变；只有最后一条 user 指令不同。
+- 直接摘要调用仍不纳入 transcript（文本记录）快照，因为它不会发出 `assistant/chunk` 事件。真实循环回归改为断言摘要请求收到的精确最终指令。

.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-web-default-search.md
+2026-07-31-web-default-search.md: ddc047a963212cb228da67c6c33128877cacf92c
+2026-07-31-web-default-search.zh.md: 05c30b625953ccd54c127a97b646ad7db75f693b

.agents/notes/implemented/feature/2026-07-31-web-default-search.md

@@ -0,0 +1,35 @@
+# Agent Note: Default Web search in the Web/headless composition
+
+Status: implemented
+
+English | [中文](2026-07-31-web-default-search.zh.md)
+
+## Problem
+
+The harness had a complete Web capability family—provider registry, DeepSeek/Exa/Perplexity search providers, local fetch, stable model tools, and structured result presentation—but the shipped `dsh web` composition mounted none of it. The model could not discover current information unless a deployment supplied a custom overlay. Merely mounting the existing DeepSeek provider would not complete the WebUI path: the Models page stores `DEEPSEEK_API_KEY` through `ctx.credentials`, while the search provider froze only the process environment at plugin load, so a key entered or rotated in the running UI would not reach search.
+
+## Decision
+
+`apps/cli/config/web.cordis.yml` explicitly mounts `dsh-web` with `searchProvider: deepseek-official`, `dsh-web-search-deepseek`, and `dsh-tool-web` with `fetch: false`. It does not mount `dsh-web-fetch-local` or select a fetch provider. The shared overlay makes only `web_search` a default for browser and headless sessions; the TUI composition remains unchanged. The explicit search provider id keeps selection independent of registration order and leaves personal or `--config` overlays able to replace or disable the rows.
+
+DeepSeek search uses the same `DEEPSEEK_API_KEY` credential reference as the official conversation adapter. The provider resolves that reference inside every search through the optional `ctx.credentials` service; only a composition without the seam falls back to the launching process environment, and a non-empty literal `apiKey` remains the programmatic last resort. A stored or rotated Web Models key therefore reaches the next search without restarting or retaining the value on the provider. Because `WebSearchProvider.available()` is synchronous, it treats an installed resolver as locally usable and missing dynamic credentials fail the operation with the provider-specific `WEB_PROVIDER_CREDENTIAL_MISSING` code while the stable tool schema stays registered.
+
+Search keeps its endpoint distinct from chat completions: `DEEPSEEK_SEARCH_BASE_URL` overrides the Anthropic-compatible base, while `DEEPSEEK_BASE_URL` continues to configure conversation requests. Each `web_search` performs an auxiliary DeepSeek Messages call with the native search server tool. Immediately before dispatch, the provider appends a log-only `web/deepseek-search-llm-request` event to the initiating Agent session with the resolved endpoint, API version, and exact secret-free JSON body. Credential preflight remains provider-local and races caller cancellation; neither concern expands the generic Web or credentials seams.
+
+The default mount does not create a Web-specific permission policy. `web_search` executes outside the bash/filesystem sandbox and approval presets, following `dsh-tool-web`'s existing contract. It does not mount `web_fetch` or a local fetch provider, so the default does not grant model-selected arbitrary URL retrieval. The shipped deployment already defaults to `danger-full-access`; a future restricted-network product stance must add a `tools/pre-execute` policy or capability-specific network confinement rather than implying that filesystem access mode governs Web calls.
+
+## Alternatives considered
+
+**Mount only `dsh-tool-web`.** Rejected because stable schemas without registered providers would make every default call fail; enablement and backend availability are deliberately separate, but a shipped default must supply its intended implementations.
+
+**Read `$DSH_HOME/.env` from `cordis.yml` or hoist it into `process.env`.** Rejected because the credential provider owns that document, environment values are read-only overrides, and hoisting would make stored keys unrotatable while bypassing the audited secret boundary.
+
+**Freeze `process.env.DEEPSEEK_API_KEY` at provider load.** Rejected because the Web Models page writes through `ctx.credentials`; the product's documented first-run path must make the next operation work without a restart.
+
+**Mount Web tools in `base.cordis.yml`.** Rejected because that would also change the TUI deployment. The browser and headless entries already share `web.cordis.yml`; they gain the capability together while TUI remains an explicit later decision.
+
+**Enable search and fetch together.** Rejected because default `web_fetch` would allow model-selected anonymous outbound HTTP(S) retrieval to arbitrary URLs. Search covers discovery; deployments that accept broader retrieval can opt into `dsh-web-fetch-local` and set `dsh-tool-web`'s `fetch` option to `true` in their overlay.
+
+## Consequences
+
+Web/headless model requests carry only the `web_search` schema and search-only prompt guidance in native mode; Code Mode exposes the same search capability beneath `run_code`. The prompt tells the model to use returned snippets and never advertises the disabled `web_fetch` tool. Search adds a complete auxiliary model call and may use the native server tool multiple times; its exact secret-free request remains reconstructable from the initiating session log. The default offers search-result snippets and source metadata but no arbitrary page retrieval; deployments that need full-page fetch must opt in. The Web snapshot lane boots the shipped tree, drives a replayed `web_search` call through the real DeepSeek provider against a local Messages fixture, asserts the durable auxiliary request and structured result, and pins the settled browser presentation. The real-composition smoke test pins the absence of `web_fetch`; provider tests pin missing, stored, and rotated credential behavior plus literal and ambient compatibility.

.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md

@@ -0,0 +1,35 @@
+# Agent Note: Web／无头组合中的默认 Web 搜索
+
+Status: implemented
+
+[English](2026-07-31-web-default-search.md) | 中文
+
+## 问题
+
+该 harness 已具备完整的 Web 能力体系：提供方注册表、DeepSeek、Exa 和 Perplexity 搜索提供方、本地抓取、稳定的面向模型工具，以及结构化结果呈现，但已交付的 `dsh web` 组合没有挂载其中任何一项。除非部署提供自定义覆盖层，否则模型无法发现最新信息。仅挂载现有 DeepSeek 提供方仍无法打通 WebUI 链路：Models 页面通过 `ctx.credentials` 存储 `DEEPSEEK_API_KEY`，而搜索提供方只会在插件加载时固定读取进程环境，因此在运行中的 UI 输入或轮换的密钥无法用于搜索。
+
+## 决策
+
+`apps/cli/config/web.cordis.yml` 明确挂载 `dsh-web`，配置 `searchProvider: deepseek-official`，同时挂载 `dsh-web-search-deepseek`，并以 `fetch: false` 挂载 `dsh-tool-web`。它不挂载 `dsh-web-fetch-local`，也不选择抓取提供方。共享覆盖层只将 `web_search` 设为浏览器与无头会话的默认工具；TUI 组合保持不变。显式搜索提供方 id 使选择不受注册顺序影响，同时个人覆盖层或 `--config` 覆盖层仍可替换或禁用这些配置项。
+
+DeepSeek 搜索使用与官方会话适配器相同的 `DEEPSEEK_API_KEY` 凭据引用。提供方在每次搜索内部通过可选的 `ctx.credentials` 服务解析该引用；只有未挂载该 seam 的组合才会回退到启动进程的环境变量，非空的 `apiKey` 字面值仍作为程序化配置的最后兜底。因此，由 Web 的 Models 页存储或轮换的密钥无需重启即可用于下一次搜索，提供方也无需保留该值。由于 `WebSearchProvider.available()` 是同步方法，它会将已安装解析器视为本地可用；若动态凭据缺失，操作会以提供方专属错误码 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败，而稳定的工具 schema 仍保持注册。
+
+搜索端点与 chat completions 保持独立：`DEEPSEEK_SEARCH_BASE_URL` 覆盖 Anthropic 兼容基址，`DEEPSEEK_BASE_URL` 则继续配置会话请求。每次 `web_search` 都会发起一次辅助 DeepSeek Messages 调用，并携带原生搜索服务器工具。发出请求前一刻，提供方会向发起请求的 agent（智能体）会话追加仅用于日志的 LLM（大语言模型）请求事件 `web/deepseek-search-llm-request`，其中包含已解析端点、API 版本，以及不含密钥的精确 JSON 请求体。凭据预检仍留在提供方内部，并与调用方取消存在竞态；这两项关注点都不会扩展通用 Web seam 或凭据 seam。
+
+默认挂载不会创建 Web 专用权限策略。`web_search` 在 bash／文件系统沙箱及审批预设之外执行，并遵循 `dsh-tool-web` 的现有契约。组合不挂载 `web_fetch` 或本地抓取提供方，因此默认配置不会允许模型自行选择任意 URL 进行抓取。已交付部署的默认值本就是 `danger-full-access`；未来如果产品采取受限网络策略，必须添加 `tools/pre-execute` 策略或按能力限制网络访问，而不能暗示文件系统访问模式会管辖 Web 调用。
+
+## 考虑过的替代方案
+
+**仅挂载 `dsh-tool-web`。** 不予采纳：稳定的 schema 如果没有已注册提供方，每次默认调用都会失败。启用状态与后端可用性刻意分离，但已交付的默认配置必须提供其预期实现。
+
+**从 `cordis.yml` 读取 `$DSH_HOME/.env`，或将其提升到 `process.env`。** 不予采纳：凭据提供方拥有该文件，环境变量值是只读覆盖；提升后存储的密钥将无法轮换，还会绕过经审计的密钥边界。
+
+**在提供方加载时固定读取 `process.env.DEEPSEEK_API_KEY`。** 不予采纳：Web Models 页面通过 `ctx.credentials` 写入密钥；产品文档规定的首次运行路径必须保证下一次操作无需重启即可生效。
+
+**在 `base.cordis.yml` 中挂载 Web 工具。** 不予采纳：这也会改变 TUI 部署。浏览器与无头入口已经共享 `web.cordis.yml`；两者会一同获得该能力，是否为 TUI 启用则仍留作后续显式决策。
+
+**同时启用搜索和抓取。** 不予采纳：默认启用 `web_fetch` 会允许模型自行选择任意 URL，执行匿名出站 HTTP(S) 抓取。搜索负责发现信息；接受更广泛抓取范围的部署可以在覆盖层中选择启用 `dsh-web-fetch-local`，并将 `dsh-tool-web` 的 `fetch` 选项设为 `true`。
+
+## 后果
+
+Web／无头模型请求在原生模式下只会携带 `web_search` schema，以及仅用于搜索的提示词指引；Code Mode 通过 `run_code` 公开相同的搜索能力。该提示词要求模型使用返回的 snippet，且绝不会向模型提及已禁用的 `web_fetch` 工具。搜索会增加一次完整的辅助模型调用，并可能多次使用原生服务器工具；发起会话的日志仍可精确重建其不含密钥的请求。默认配置会提供搜索结果 snippet 与来源元数据，但不支持任意页面抓取；需要抓取完整页面的部署必须自行选择启用抓取。Web 快照通道会启动已交付配置树，使用本地 Messages fixture（测试前置数据），经由真实 DeepSeek 提供方驱动一次回放的 `web_search` 调用，断言持久化的辅助请求与结构化结果，并固定最终浏览器呈现。真实组合冒烟测试固定了不提供 `web_fetch` 这一事实；提供方测试固定缺失、已存储及已轮换凭据的行为，以及字面值与环境变量的兼容性。

.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
-2026-07-28-storage-root-and-derived-medium-recovery.md: 3937b17502d0bf640625e73822b758b1862b5391
-2026-07-28-storage-root-and-derived-medium-recovery.zh.md: ff2f196a911986d23b7a102e6336f353c6aef278
+2026-07-28-storage-root-and-derived-medium-recovery.md: 7759d0b6a8d522d6f853be0cd31a0b3909292446
+2026-07-28-storage-root-and-derived-medium-recovery.zh.md: 893b91c2ad3943cce9f64702e52afbb8075b907c

.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md

@@ -8,7 +8,7 @@ English | [中文](2026-07-28-storage-root-and-derived-medium-recovery.zh.md)
 
 The persisted projection cache ([RFC](2026-07-27-session-projection-and-command-log.md), shipped as `dsh-session-projection-cache`) surfaced two gaps in the storage substrate it landed on. Both are properties of the domain-KV stack ([design](2026-07-24-domain-kv-storage-and-workspace.md)), not of the cache itself, and both bite the cache first because it is the first *derived* medium on that stack.
 
-**Where the files actually live.** The shipped Web overlay gives the json backend a relative root — `root: './.storages'` (`apps/cli/config/web.cordis.yml`) — while the shared base defaults the session store to the global harness home (`$DSH_HOME/sessions`, default `~/.dsh/sessions`); no equivalent global root exists for `storage-json`. `JsonStorageBackend` never resolves its root either — each unit open joins the still-relative path against whatever `process.cwd()` is at that moment (packages/storage/storage-json/src/index.ts) — the exact hazard the JSONL session backend resolves-once to prevent ("later process.cwd() changes cannot split one backend across roots", packages/session-persistence/session-persistence-jsonl/src/index.ts). Net effect: session logs are global across launch directories, but `workspace.json` and `session_projcache.json` land under `<launch dir>/.storages/`. Two launches from different directories share their sessions yet see different workspace registries and different projection caches — and the cache exists precisely to serve the cross-session cold listing, which now misses for every session last cached under another launch directory.
+**Where the files actually live (root mismatch closed; resolve-once residual still open).** The shared base defaults the session store to the global harness home (`$DSH_HOME/sessions`, default `~/.dsh/sessions`), while the shipped Web overlay used to give the json backend the relative root `./.storages`: `workspace.json` and `session_projcache.json` landed under `<launch dir>/.storages/` — two launches from different directories shared their sessions yet saw different workspace registries and different projection caches, and the cache exists precisely to serve the cross-session cold listing, which missed for every session last cached under another launch directory. That mismatch is now closed: the overlay anchors `storage-json.root` to `$DSH_HOME/storages` with the same `!!js` expression the session root uses (`apps/cli/config/web.cordis.yml`). The residual hazard: `JsonStorageBackend` still never resolves its root — each unit open joins the path against whatever `process.cwd()` is at that moment (packages/storage/storage-json/src/index.ts); the shipped overlay root is already absolute and unaffected, but any relative root (bare Loader boots, tests) still splits on a later cwd change — the exact hazard the JSONL session backend resolves-once to prevent ("later process.cwd() changes cannot split one backend across roots", packages/session-persistence/session-persistence-jsonl/src/index.ts).
 
 **How recovery works today.** Inside a healthy medium the cache is fully self-healing by design: a `stateVersion`-mismatched row is discarded and refolded, a log shrunk below a row's watermark is detected by the anchored restore floor and answered with one full re-read, and every background write is fail-soft. But at the *medium* level there is no recovery at all: a truncated, hand-edited, or version-bumped `session_projcache.json` fails `openJsonUnit` with `malformed-medium`/`version-mismatch` (packages/storage/storage-json/src/format.ts), a schema-drifted record fails domain open with `invalid-record` (packages/storage/storage-domain/src/index.ts), the rejection propagates through `SessionProjectionCache[Service.init]`, and under the CLI's fail-loud boot the assembly refuses to start. A file whose entire content is rebuildable from session logs can brick boot. This contradicts the cache package's own stated stance ("a stale or unreadable cache costs a longer tail replay, never a wrong value") and the cache domain spec's JSDoc ("version bumps discard the whole medium"), which today describes an aspiration, not the implementation. The same fail-loud path is *correct* for `workspace.json` — workspace records are authoritative, not derivable — so the missing concept is a per-domain declaration of authority, not a global behavior change.
 
@@ -16,11 +16,11 @@ The persisted projection cache ([RFC](2026-07-27-session-projection-and-command-
 
 Two independent changes, one per gap.
 
-### One global storage root, resolved once
+### One global storage root (shipped, amended form); resolved once at construction (still open)
 
-- `AppCLIEntry.composePatches` Source 0 additionally patches `storage-json.root` to `join(resolveDshHome(), 'storages')` — `~/.dsh/storages` by default, beside `~/.dsh/sessions` — and `PROFILE_MAPPINGS` gains `storageRoot` → (`storage-json`, `root`), mirroring `persistenceRoot` exactly. The yml keeps `./.storages` as the raw-composition engineering default (tests and bare Loader boots are unaffected), same layering as the session root today.
-- `JsonStorageBackend` resolves its configured root once at construction (`resolve(config.root)`), adopting the JSONL backend's recorded rationale verbatim: a later `process.cwd()` change must not split one backend across roots. The SQLite storage backend already resolves its path.
-- Pre-release stance applies: no migration shim. A deployment that cached under `<cwd>/.storages` re-derives everything (workspace re-bootstraps from the header index; the projection cache refolds lazily) or moves the two json files by hand once.
+- **Shipped**: the Web overlay anchors `storage-json.root` to `$DSH_HOME/storages` directly in the row, with the same `!!js` IIFE the session root uses (`~/.dsh/storages` by default, beside `~/.dsh/sessions`; no leading dot — the home is already a hidden tree). The user ruled this form in over this section's original launcher-patch + `storageRoot` profile key (see Alternatives); per-row overrides ride the personal `~/.dsh/config.yaml` patch layer. The verbatim duplication of the expression against the session root (`base.cordis.yml`) is a known cost — acceptable at two consumers; a third `$DSH_HOME`-derived root triggers extracting a single source (a launcher variable or a shared expression). The web e2e scaffold already patches the row to an absolute temp root, so tests never touch the user's home.
+- **Still open**: `JsonStorageBackend` resolves its configured root once at construction (`resolve(config.root)`), adopting the JSONL backend's recorded rationale verbatim: a later `process.cwd()` change must not split one backend across roots. The SQLite storage backend already resolves its path.
+- Pre-release stance applies (and was executed): no migration shim. A deployment that cached under `<cwd>/.storages` re-derives everything (workspace re-bootstraps from the header index; the projection cache refolds lazily) or moves the two json files by hand once.
 
 ### Declared derived media: reset instead of reject
 
@@ -31,7 +31,9 @@ Two independent changes, one per gap.
 
 ## Alternatives considered
 
-**Keep per-launch-directory `.storages` (status quo)** — rejected: sessions are global, so every derived-from-sessions medium splits against its own source of truth; the cache's motivating scenario (one listing over all sessions) structurally misses rows, and the workspace registry indexes sessions it cannot see from another launch directory.
+**Keep per-launch-directory `.storages` (the pre-change status quo)** — rejected: sessions are global, so every derived-from-sessions medium splits against its own source of truth; the cache's motivating scenario (one listing over all sessions) structurally misses rows, and the workspace registry indexes sessions it cannot see from another launch directory.
+
+**Launcher patch + a `storageRoot` profile key (this section's original form)** — not taken: one `!!js` yml expression reaches the global root with the same layering the session root already has; a launcher patch adds a second rewrite point, and the profile key is an empty seat until a real consumer exists (per-row overrides already have the personal config.yaml patch layer).
 
 **Patch only the projection cache's route to a global root, leave `workspace.json` per-cwd** — rejected: the workspace registry has the identical global-vs-cwd mismatch, and the user decision that shaped the cache placed it deliberately beside `workspace.json` — one hub root keeps the media co-located and the mental model single.
 
@@ -45,7 +47,7 @@ Two independent changes, one per gap.
 
 ## Acceptance criteria
 
-- `dsh` launched from any directory reads and writes the same `$DSH_HOME/storages/*.json` (default `~/.dsh/storages`); the profile key `storageRoot` overrides it; a raw Loader boot of the yml still lands in `./.storages` relative to the boot cwd, resolved once at backend construction.
+- `dsh` launched from any directory reads and writes the same `$DSH_HOME/storages/*.json` (default `~/.dsh/storages`) — already satisfied by the overlay expression; per-row overrides ride the personal config.yaml patch layer; the backend resolves a relative root once at construction (still to do).
 - With a truncated, version-bumped, or schema-drifted `session_projcache.json`, the assembly boots clean: one warning names the discarded medium, the file is gone, the cache rebuilds through normal operation, and the cold listing column reappears as sessions are re-checkpointed.
 - The same damage to `workspace.json` still fails boot loudly.
 - Facility tests cover: each damage class resets a `'reset'` domain exactly once; non-damage failures stay loud on a `'reset'` domain; a `'reject'` domain propagates every failure; `destroy` removes the medium on both shipped backends.

.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md

@@ -8,7 +8,7 @@ Status: proposed
 
 持久投影缓存（[RFC](2026-07-27-session-projection-and-command-log.md)，已作为 `dsh-session-projection-cache` 落地）暴露了它所依托的存储基座的两个缺口。二者都是 domain-KV 栈（[设计](2026-07-24-domain-kv-storage-and-workspace.md)）的属性而非缓存自身的问题，且都首先咬到缓存——因为它是这条栈上第一个*派生*介质。
 
-**文件到底存在哪。** 出厂 Web overlay 给 json 后端的是相对根目录——`root: './.storages'`（`apps/cli/config/web.cordis.yml`）——而共享 base 将会话存储默认为全局 harness home（`$DSH_HOME/sessions`，默认 `~/.dsh/sessions`）；`storage-json` 没有对应的全局根目录。`JsonStorageBackend` 自己也从不 resolve 根——每次打开 unit 都把仍然相对的路径 join 到当时的 `process.cwd()` 上（packages/storage/storage-json/src/index.ts）——这正是 JSONL 会话后端用「构造时 resolve 一次」防住的那个隐患（"later process.cwd() changes cannot split one backend across roots"，packages/session-persistence/session-persistence-jsonl/src/index.ts）。净效果：会话日志跨启动目录全局共享，但 `workspace.json` 和 `session_projcache.json` 落在 `<启动目录>/.storages/` 下。从两个不同目录启动，会话相同，工作区注册表和投影缓存却各是一份——而缓存存在的意义恰恰是跨会话冷列表，如今凡是上次在别的启动目录下缓存过的会话全部 miss。
+**文件到底存在哪（根错位已收口，resolve-once 残余仍开放）。** 共享 base 将会话存储默认为全局 harness home（`$DSH_HOME/sessions`，默认 `~/.dsh/sessions`），而出厂 Web overlay 曾给 json 后端相对根 `./.storages`：`workspace.json` 和 `session_projcache.json` 落在 `<启动目录>/.storages/` 下——从两个不同目录启动，会话相同，工作区注册表和投影缓存却各是一份，而缓存存在的意义恰恰是跨会话冷列表，凡上次在别的启动目录下缓存过的会话全部 miss。这一错位已消除：overlay 现以与会话根同一段 `!!js` 表达式把 `storage-json.root` 锚定到 `$DSH_HOME/storages`（`apps/cli/config/web.cordis.yml`）。残余隐患：`JsonStorageBackend` 仍从不 resolve 根——每次打开 unit 都把路径 join 到当时的 `process.cwd()` 上（packages/storage/storage-json/src/index.ts）；出厂 overlay 的根已是绝对路径不受影响，但任何相对根（裸 Loader 启动、测试）仍会被后续 cwd 变化劈开，JSONL 会话后端用「构造时 resolve 一次」防住的正是它（"later process.cwd() changes cannot split one backend across roots"，packages/session-persistence/session-persistence-jsonl/src/index.ts）。
 
 **现在是怎么恢复的。** 在健康介质内部，缓存按设计完全自愈：`stateVersion` 不匹配的行被丢弃重折，日志缩短到行水位以下由带锚的 restore floor 检出并以一次全量重读回答，每次后台写都是 fail-soft。但在*介质*层面完全没有恢复：被截断、被手改或版本被 bump 的 `session_projcache.json` 会让 `openJsonUnit` 以 `malformed-medium`/`version-mismatch` 失败（packages/storage/storage-json/src/format.ts），schema 漂移的记录让域 open 以 `invalid-record` 失败（packages/storage/storage-domain/src/index.ts），拒绝一路穿过 `SessionProjectionCache[Service.init]`，在 CLI 的 fail-loud 启动下整个组装拒绝启动。一个内容完全可从会话日志重建的文件能把启动搞死。这与缓存包自己声明的立场（"a stale or unreadable cache costs a longer tail replay, never a wrong value"）和缓存域 spec 的 JSDoc（"version bumps discard the whole medium"）相矛盾——后者今天描述的是愿望而非实现。同一条 fail-loud 路径对 `workspace.json` 却是*正确*的——工作区记录是权威数据，不可派生——所以缺的概念是按域声明权威性，而不是全局改行为。
 
@@ -16,11 +16,11 @@ Status: proposed
 
 两个独立改动，一个缺口一个。
 
-### 全局唯一存储根，构造时 resolve 一次
+### 全局唯一存储根（已落地，形态修正）；构造时 resolve 一次（仍开放）
 
-- `AppCLIEntry.composePatches` 的 Source 0 追加把 `storage-json.root` patch 到 `join(resolveDshHome(), 'storages')`——默认 `~/.dsh/storages`，与 `~/.dsh/sessions` 并肩——并且 `PROFILE_MAPPINGS` 增加 `storageRoot` →（`storage-json`，`root`），与 `persistenceRoot` 完全镜像。yml 保留 `./.storages` 作为裸组合的工程默认（测试和裸 Loader 启动不受影响），分层方式与今天的会话根相同。
-- `JsonStorageBackend` 在构造时对配置根 `resolve` 一次，原样采纳 JSONL 后端已记录的理由：后续 `process.cwd()` 变化不得把一个后端劈到多个根下。SQLite 存储后端已经 resolve 其路径。
-- 适用 pre-release 立场：不做迁移垫片。曾在 `<cwd>/.storages` 下缓存过的部署要么全部重新派生（工作区从 header 索引重新 bootstrap；投影缓存惰性重折），要么手动把两个 json 文件挪一次。
+- **已落地**：出厂 Web overlay 直接在 `storage-json` 行内用与会话根同一段 `!!js` IIFE 把 `root` 锚定到 `$DSH_HOME/storages`（默认 `~/.dsh/storages`，与 `~/.dsh/sessions` 并肩；目录名不带点——home 本身已是隐藏树）。用户拍板采用此形态取代本节初版的「launcher patch + `storageRoot` profile 键」（见 Alternatives）；按行覆盖仍走个人 `~/.dsh/config.yaml` patch 层。该表达式与 sessions 根（`base.cordis.yml`）逐字重复是已知代价——两个消费者尚可接受；出现第三个 `$DSH_HOME` 派生根时提取单一来源（launcher 变量或共享表达式）。web e2e scaffold 本就把该行 patch 到临时绝对根，测试不触用户 home。
+- **仍开放**：`JsonStorageBackend` 在构造时对配置根 `resolve` 一次，原样采纳 JSONL 后端已记录的理由：后续 `process.cwd()` 变化不得把一个后端劈到多个根下。SQLite 存储后端已经 resolve 其路径。
+- 适用 pre-release 立场（已按此执行）：不做迁移垫片。曾在 `<cwd>/.storages` 下缓存过的部署要么全部重新派生（工作区从 header 索引重新 bootstrap；投影缓存惰性重折），要么手动把两个 json 文件挪一次。
 
 ### 声明派生介质：损坏时重置而非拒绝
 
@@ -31,7 +31,9 @@ Status: proposed
 
 ## Alternatives considered
 
-**保持按启动目录的 `.storages`（现状）**——拒绝：会话是全局的，所以每个从会话派生的介质都与自己的真源劈叉；缓存的动机场景（一次列出全部会话）结构性丢行，工作区注册表索引着从另一个启动目录看不见的会话。
+**保持按启动目录的 `.storages`（改动前现状）**——拒绝：会话是全局的，所以每个从会话派生的介质都与自己的真源劈叉；缓存的动机场景（一次列出全部会话）结构性丢行，工作区注册表索引着从另一个启动目录看不见的会话。
+
+**launcher patch + `storageRoot` profile 键（本节初版提案形态）**——未采：一行 yml `!!js` 表达式即达全局根，与会话根的既有分层完全一致；launcher patch 多引入一个改写点，profile 键在有真实消费者前是空席（按行覆盖已有个人 config.yaml patch 层可用）。
 
 **只把投影缓存的 route 指到全局根，`workspace.json` 留在 per-cwd**——拒绝：工作区注册表有一模一样的全局 vs per-cwd 错位，而且塑造缓存的用户决策就是刻意把它放在 `workspace.json` 旁边——一个 hub 根让介质同址、心智模型单一。
 
@@ -45,7 +47,7 @@ Status: proposed
 
 ## Acceptance criteria
 
-- 从任意目录启动 `dsh` 都读写同一份 `$DSH_HOME/storages/*.json`（默认 `~/.dsh/storages`）；profile 键 `storageRoot` 可覆盖；裸 Loader 启动 yml 仍落在相对启动 cwd 的 `./.storages`,并在后端构造时 resolve 一次。
+- 从任意目录启动 `dsh` 都读写同一份 `$DSH_HOME/storages/*.json`（默认 `~/.dsh/storages`）——已由 overlay 表达式满足，按行覆盖走个人 config.yaml patch 层；后端对相对根在构造时 resolve 一次（待做）。
 - `session_projcache.json` 被截断、版本 bump 或 schema 漂移时，组装干净启动：一条警告命名被丢弃的介质，文件消失，缓存经正常运转重建，冷列表列随会话重新 checkpoint 逐步回归。
 - 同样的损坏发生在 `workspace.json` 上仍大声拒绝启动。
 - facility 测试覆盖：每个损坏类恰好重置一次 `'reset'` 域；非损坏失败在 `'reset'` 域上保持大声；`'reject'` 域传播一切失败；`destroy` 在两个出厂后端上都移除介质。

.gitattributes

@@ -5,3 +5,5 @@
 # for cmd.exe), add a `*.bat text eol=crlf` override AFTER this line — the
 # in-repo form stays LF; CRLF becomes checkout-time presentation only.
 * text=auto eol=lf
+
+*.pdf -text

apps/cli/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write apps/cli/README.md
-README.md: c36a75fc61fd7118f48c9b68be3144177df19534
-README.zh.md: e926fa99c4e483351f52ca4e76b668e26b34d02f
+README.md: fc5bce195fb10872c605cada1bcb3ed79380265c
+README.zh.md: 2fb1272231abb02e145e5c9925362de27307ca86

apps/cli/README.md

@@ -21,6 +21,8 @@ The Web and headless surfaces boot `base.cordis.yml` plus `web.cordis.yml`, then
 
 The shipped TUI and Web compositions register the native DeepSeek adapter plus pi-ai OpenAI and Anthropic profiles. Credentials and endpoint overrides come from the provider-standard `DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`, `OPENAI_API_KEY` / `OPENAI_BASE_URL`, and `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL` pairs in the boot's layered environment.
 
+The Web/headless composition also registers only `web_search`. Search uses DeepSeek's Anthropic-compatible Messages endpoint, resolves the same `DEEPSEEK_API_KEY` reference for every call, and accepts the separate `DEEPSEEK_SEARCH_BASE_URL` endpoint override; each search is an auxiliary model request with its own latency and token cost. `web_fetch` remains disabled and the composition mounts no default fetch provider, so deployments that need arbitrary page retrieval must opt in through an overlay. The TUI composition does not mount Web tools by default. The deployment decision and its security boundary live in the [default Web search Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-default-search.md).
+
 `DSH_TOOLS_MODE` selects the tool presentation mode for the whole Web/headless process: `native` (the schema default when unset), `code` (the `run_code`-only Code Mode wire), or `both`; any other value fails loud at boot through the `dsh-tools` config schema. It is a TEMPORARY seam — process-wide because Loader composition is static — and is removed once the web UI owns per-session tool-mode selection; the TUI surface ignores it (its config tree pins its own mode).
 
 Every `dsh` surface — TUI, Web, and headless — reports session telemetry by default (the row lives in the shared `base.cordis.yml`): every session-log event streams as OTLP/HTTP log records to `https://harness-telemetry.deepseeksvc.com/v1/logs` on a 10-second batch cadence. `DSH_TELEMETRY_OTLP_URL` points the exporter at a different collector; setting `DSH_TELEMETRY_DISABLED` to ANY non-empty value — including `0` or `false` — disables the row before it loads (a privacy switch prefers off-by-mistake over on-by-mistake). No redaction rule is mounted in this composition yet: exported records are the raw captured copy, including message text, tool arguments and results, and the session's working-directory path. The deployment rulings live in the [web-telemetry-default-mount Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md).

apps/cli/README.zh.md

@@ -21,6 +21,8 @@ Web 和无头界面启动 `base.cordis.yml` 与 `web.cordis.yml`，随后应用
 
 已交付的 TUI 和 Web 组合会注册原生 DeepSeek 适配器，以及 pi-ai 的 OpenAI 和 Anthropic 提供方配置。凭据和端点覆盖来自启动分层环境中的提供方标准变量对：`DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`、`OPENAI_API_KEY` / `OPENAI_BASE_URL` 和 `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`。
 
+Web／无头组合还只会注册 `web_search`。搜索使用 DeepSeek 的 Anthropic 兼容 Messages 端点，每次调用都会解析同一个 `DEEPSEEK_API_KEY` 凭据引用，并接受独立的 `DEEPSEEK_SEARCH_BASE_URL` 端点覆盖；每次搜索都是一次辅助模型请求，会产生独立的延迟与 token 成本。`web_fetch` 仍处于禁用状态，组合也未挂载默认抓取提供方；需要任意页面抓取能力的部署必须通过覆盖层选择启用。TUI 组合默认不挂载 Web 工具。部署决策及其安全边界见[默认 Web 搜索 Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-default-search.md)。
+
 `DSH_TOOLS_MODE` 为整个 Web／无头进程选择工具呈现模式：可选值为 `native`（未设置时的 schema 默认值）、`code`（仅含 `run_code` 的 Code Mode 协议接口）或 `both`；任何其他值都会经由 `dsh-tools` 配置 schema 在启动时明确报错。它是一个临时 seam：Loader 组合是静态的，因此该设置作用于整个进程；待 Web UI 负责逐会话工具模式选择后便会移除。TUI 界面会忽略该变量（其配置树固定了自身模式）。
 
 每个 `dsh` 界面——TUI、Web 与无头——都默认上报会话遥测（该行位于共享的 `base.cordis.yml`）：每条会话日志事件以 OTLP/HTTP 日志记录的形式、按 10 秒批处理节奏流向 `https://harness-telemetry.deepseeksvc.com/v1/logs`。`DSH_TELEMETRY_OTLP_URL` 可将 exporter 指向其他 collector；将 `DSH_TELEMETRY_DISABLED` 设为**任意非空值**——包括 `0` 或 `false`——都会在该行加载前将其关停（隐私开关取「宁可误关、不可误开」）。该组合当前未挂载任何脱敏规则：导出记录即原始捕获副本，包含消息正文、工具参数与结果、以及会话工作目录路径。部署口径见 [web-telemetry-default-mount Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md)。

apps/cli/config/web.cordis.yml

@@ -80,6 +80,28 @@
 - id: fs-local
   disabled: true
 
+# The Web/headless product enables only the stable web_search model surface.
+# DeepSeek search resolves the same DEEPSEEK_API_KEY credential the Models page
+# manages for chat, at each search; its Messages endpoint is separate from the
+# chat-completions endpoint. Fetch remains disabled and no default fetch
+# provider is mounted.
+- insert:
+    - id: web
+      name: '@deepseek-ai/dsh-web'
+      config:
+        searchProvider: deepseek-official
+
+    - id: web-search-deepseek
+      name: '@deepseek-ai/dsh-web-search-deepseek'
+      config:
+        apiKeyEnv: DEEPSEEK_API_KEY
+        baseURL: !!js process.env.DEEPSEEK_SEARCH_BASE_URL
+
+    - id: tool-web
+      name: '@deepseek-ai/dsh-tool-web'
+      config:
+        fetch: false
+
 # ── web-only host rows, the transport layer, and the browser roster ─────────
 
 # `dshClient` rows are the browser roster the modules node half scans into
@@ -97,7 +119,8 @@
     - id: storage-json
       name: '@deepseek-ai/dsh-storage-json'
       config:
-        root: './.storages'
+        root: !!js >-
+          (() => { const path = process.getBuiltinModule('node:path'); const home = process.getBuiltinModule('node:os').homedir(); const configured = process.env.DSH_HOME; const selected = configured !== undefined && configured.trim().length > 0 ? configured : path.join(home, '.dsh'); const expanded = selected === '~' ? home : selected.startsWith('~/') || selected.startsWith('~\\') ? path.join(home, selected.slice(2)) : selected; return path.join(path.resolve(expanded), 'storages') })()
 
     - id: storage-domain
       name: '@deepseek-ai/dsh-storage-domain'

apps/cli/package.json

@@ -112,11 +112,14 @@
     "@deepseek-ai/dsh-tool-subagent": "workspace:^",
     "@deepseek-ai/dsh-tool-tasks": "workspace:^",
     "@deepseek-ai/dsh-tool-todo": "workspace:^",
+    "@deepseek-ai/dsh-tool-web": "workspace:^",
     "@deepseek-ai/dsh-tool-workflow": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/dsh-tui": "workspace:^",
     "@deepseek-ai/dsh-user-approval": "workspace:^",
     "@deepseek-ai/dsh-user-interaction": "workspace:^",
+    "@deepseek-ai/dsh-web": "workspace:^",
+    "@deepseek-ai/dsh-web-search-deepseek": "workspace:^",
     "@deepseek-ai/dsh-workflow-workerthread": "workspace:^",
     "@deepseek-ai/dsh-workspace": "workspace:^",
     "@deepseek-ai/dsh-workspace-context": "workspace:^",

apps/web/tests/scaffold.ts

@@ -139,6 +139,17 @@ export interface LaunchOptions {
    * keyless first-run configuration lane; the default disables the adapter.
    */
   deepSeekMissingCredential?: boolean
+  /**
+   * Patch the shipped DeepSeek search row to a deterministic endpoint and
+   * credential reference. Browser search scenarios keep the real provider and
+   * credentials seam while avoiding external search traffic and ambient keys.
+   */
+  deepSeekSearch?: {
+    /** Anthropic-compatible base URL; the provider appends `/messages`. */
+    baseURL: string
+    /** Credential reference resolved by the shipped search provider. */
+    apiKeyEnv: string
+  }
   /** Leave the current welcome notice unacknowledged; ordinary scenarios publish it as complete before browser boot. */
   welcomeNoticePending?: boolean
 }
@@ -206,9 +217,9 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     ...surfacePatches,
     { id: 'session-persistence-jsonl', config: { root: persistenceRoot } },
     { id: 'session-query-sqlite', config: { path: ':memory:', openAt: 'first-search' } },
-    // storage-json's './.storages' yml default is cwd-relative and resolves
-    // per write; the scaffold restores the original cwd after boot, so the
-    // row gets an absolute temp root (removed with the workspace at close).
+    // storage-json's yml root is anchored to the real $DSH_HOME; pin the row
+    // to an absolute temp root (removed with the workspace at close) so tests
+    // never write the user's harness home.
     { id: 'storage-json', config: { root: join(workspaceCwd, '.dsh-storages') } },
     // Skill discovery is model-visible input. Pin every host-level root inside
     // the owned temp world so ~/.dsh, ~/.agents, and a bundled-root env setting
@@ -247,6 +258,15 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     ...options.cordisTools === true
       ? [{ insert: [{ id: 'tool-cordis', name: 'cordis:tool-cordis' }] }]
       : [],
+    ...options.deepSeekSearch === undefined
+      ? []
+      : [{
+        id: 'web-search-deepseek',
+        config: {
+          apiKeyEnv: options.deepSeekSearch.apiKeyEnv,
+          baseURL: options.deepSeekSearch.baseURL,
+        },
+      }],
     ...mode === 'record' || options.deepSeekMissingCredential === true
       ? []
       : [{ id: 'llm-deepseek', disabled: true }],

apps/web/tests/smoke-real.e2e.ts

@@ -188,8 +188,12 @@ describe('dsh web keyless CLI smoke', () => {
     mkdirSync(join(workspace, '.git'))
     writeFileSync(join(workspace, 'AGENTS.md'), 'web-workspace-context-probe\n')
 
-    let resolveProviderRequest!: (request: { messages?: { role?: string; content?: string }[] }) => void
-    const providerRequest = new Promise<{ messages?: { role?: string; content?: string }[] }>((resolve) => {
+    interface NativeProviderRequest {
+      messages?: { role?: string; content?: string }[]
+      tools?: { function?: { name?: string } }[]
+    }
+    let resolveProviderRequest!: (request: NativeProviderRequest) => void
+    const providerRequest = new Promise<NativeProviderRequest>((resolve) => {
       resolveProviderRequest = resolve
     })
     const provider = createServer((request, response) => {
@@ -197,7 +201,7 @@ describe('dsh web keyless CLI smoke', () => {
       request.setEncoding('utf8')
       request.on('data', (chunk: string) => { body += chunk })
       request.on('end', () => {
-        resolveProviderRequest(JSON.parse(body) as { messages?: { role?: string; content?: string }[] })
+        resolveProviderRequest(JSON.parse(body) as NativeProviderRequest)
         response.writeHead(200, { 'content-type': 'text/event-stream' })
         response.end([
           'data: {"choices":[{"delta":{"role":"assistant","content":null,"reasoning_content":""}}]}',
@@ -256,6 +260,13 @@ describe('dsh web keyless CLI smoke', () => {
           "role": "user",
         }
       `)
+      expect(captured.tools?.map(tool => tool.function?.name)
+        .filter(name => name === 'web_search' || name === 'web_fetch'))
+        .toMatchInlineSnapshot(`
+          [
+            "web_search",
+          ]
+        `)
     } finally {
       const closed = child.exitCode === null
         ? new Promise<void>((resolveClose) => { child.once('close', () => { resolveClose() }) })

apps/web/tests/snapshots/web-search-round/session.jsonl

@@ -0,0 +1,12 @@
+{"type":"session","version":0,"id":"{{sessionId}}","createdAt":1785456000000,"cwd":"{{cwd}}"}
+{"type":"user/message","seq":0,"time":1785456000001,"data":{"content":[{"type":"text","text":"Use web_search to search exactly \"DeepSeek Harness snapshot search\". Then reply exactly SEARCH_DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpcId}}"}},"surfaceOp":"append"}
+{"type":"assistant/chunk","seq":1,"time":1785456000002,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":2,"time":1785456000003,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"call_web_search","name":"web_search","argumentsDelta":"{\"query\":\"DeepSeek Harness snapshot search\"}"}}}
+{"type":"assistant/chunk","seq":3,"time":1785456000004,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_web_search","name":"web_search","arguments":"{\"query\":\"DeepSeek Harness snapshot search\"}"}}}}
+{"type":"assistant/chunk","seq":4,"time":1785456000005,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":5,"time":1785456000006,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/chunk","seq":6,"time":1785456000007,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":7,"time":1785456000008,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":0,"text":"SEARCH_DONE"}}}
+{"type":"assistant/chunk","seq":8,"time":1785456000009,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"SEARCH_DONE"}}}}
+{"type":"assistant/chunk","seq":9,"time":1785456000010,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":12,"outputTokens":2}}}}
+{"type":"assistant/chunk","seq":10,"time":1785456000011,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}

apps/web/tests/snapshots/web-search-round/ui.expected.md

@@ -0,0 +1,35 @@
+- banner:
+  - navigation "Session hierarchy":
+    - button "Use web_search to search exactly" [disabled]
+  - tablist:
+    - tab "Chat" [selected]
+    - tab "Trajectory"
+- text: Use web_search to search exactly "DeepSeek Harness snapshot search". Then reply exactly SEARCH_DONE and stop. {{clock}}
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- button "Edit":
+  - img
+- img
+- text: Search DeepSeek Harness snapshot search
+- list:
+  - listitem:
+    - link "Snapshot Search Result":
+      - /url: https://docs.example.test/search
+    - text: Snapshot search excerpt. 2026-07-31
+- paragraph: SEARCH_DONE
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: {{clock}}
+- textbox "Message the agent"
+- button "Commands":
+  - img
+- 'button "Access mode, current: Full access"': Full access
+- button "Select model, current DeepSeek-V4-Flash":
+  - text: DeepSeek-V4-Flash
+  - img
+- button "Send message" [disabled]
+- text: 1 turns · 2 steps Tool call {{duration}} Cache hit 0% Input 22 tok · Output 7 tok

apps/web/tests/web-search-round.e2e.ts

@@ -0,0 +1,207 @@
+// Web e2e scenario for the shipped default search composition. A real browser
+// drives `web_search`; the model stream is replayed while the real DeepSeek
+// provider calls a deterministic local Anthropic-compatible endpoint through
+// the real credentials service.
+import { readFile } from 'node:fs/promises'
+import { createServer, type Server } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { fileURLToPath } from 'node:url'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import {
+  assertFixtureInventory, captureStableAria, compareOrRefreshGolden, fixtureUserPrompts,
+  launchWebScaffold, recordFixture, watchConsole, webSnapshotMode, type WebScaffold,
+} from './scaffold.ts'
+import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './support.ts'
+
+const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/web-search-round', import.meta.url))
+const FIXTURE = fileURLToPath(new URL('./snapshots/web-search-round/session.jsonl', import.meta.url))
+const UI_EXPECTED = fileURLToPath(new URL('./snapshots/web-search-round/ui.expected.md', import.meta.url))
+const MODE = webSnapshotMode()
+const QUERY = 'DeepSeek Harness snapshot search'
+const PROMPT = `Use web_search to search exactly "${QUERY}". Then reply exactly SEARCH_DONE and stop.`
+const SEARCH_CREDENTIAL_REF = credentialRef('DSH_WEB_SEARCH_E2E_KEY')
+const SEARCH_CREDENTIAL = 'snapshot-search-key'
+const RESULT_URL = 'https://docs.example.test/search'
+
+interface CapturedSearchRequest {
+  path: string
+  apiKey: string | undefined
+  body: unknown
+}
+
+/** Start the deterministic DeepSeek Messages double used by the real provider. */
+async function startSearchServer(captured: CapturedSearchRequest[]): Promise<{ server: Server; baseURL: string }> {
+  const server = createServer((request, response) => {
+    let body = ''
+    request.setEncoding('utf8')
+    request.on('data', (chunk: string) => { body += chunk })
+    request.on('end', () => {
+      captured.push({
+        path: request.url ?? '',
+        apiKey: typeof request.headers['x-api-key'] === 'string' ? request.headers['x-api-key'] : undefined,
+        body: JSON.parse(body) as unknown,
+      })
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(JSON.stringify({
+        content: [
+          {
+            type: 'text',
+            text: 'Found one source.',
+            citations: [{
+              type: 'web_search_result_location',
+              url: RESULT_URL,
+              cited_text: 'Snapshot search excerpt.',
+            }],
+          },
+          {
+            type: 'web_search_tool_result',
+            content: [{
+              type: 'web_search_result',
+              url: RESULT_URL,
+              title: 'Snapshot Search Result',
+              page_age: '2026-07-31',
+            }],
+          },
+        ],
+      }))
+    })
+  })
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => {
+      server.off('error', reject)
+      resolve()
+    })
+  })
+  const address = server.address() as AddressInfo
+  return { server, baseURL: `http://127.0.0.1:${address.port}` }
+}
+
+describe('web e2e: shipped default web search', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let searchServer: Server | undefined
+  let searchBaseURL: string
+  let tripwire: ReturnType<typeof watchConsole>
+  const searchRequests: CapturedSearchRequest[] = []
+  const sessionEvents: SessionEvent[] = []
+
+  beforeAll(async () => {
+    const search = await startSearchServer(searchRequests)
+    searchServer = search.server
+    searchBaseURL = search.baseURL
+    scaffold = await launchWebScaffold({
+      deepSeekSearch: {
+        baseURL: search.baseURL,
+        apiKeyEnv: SEARCH_CREDENTIAL_REF,
+      },
+      ...(MODE === 'record' ? {} : { replayFixture: FIXTURE, paceMs: 15 }),
+    })
+    await scaffold.ctx.credentials.set(SEARCH_CREDENTIAL_REF, SEARCH_CREDENTIAL)
+    scaffold.ctx.on('session/event', (_session, event: SessionEvent) => { sessionEvents.push(event) })
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+    await connectFreshWorkspace(page)
+  }, 120_000)
+
+  afterAll(async () => {
+    await browser?.close()
+    await scaffold?.close()
+    await new Promise<void>((resolve, reject) => {
+      if (searchServer === undefined) {
+        resolve()
+        return
+      }
+      searchServer.close((error) => {
+        if (error === undefined) resolve()
+        else reject(error)
+      })
+    })
+  })
+
+  it('drives the recorded search to a settled turn (all modes)', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-search-drive'))
+    if (MODE !== 'record') {
+      expect(fixtureUserPrompts(await readFile(FIXTURE, 'utf8'))).toEqual([PROMPT])
+    }
+    const input = page.locator('textarea').first()
+    await input.waitFor({ timeout: 10_000 })
+    const settled = scaffold.whenTurnSettled()
+    await input.fill(PROMPT)
+    await input.press('Enter')
+    const sessionId = await settled
+    if (MODE === 'record') await recordFixture(scaffold, sessionId, FIXTURE)
+  }, 200_000)
+
+  it.skipIf(MODE === 'record')('uses the real provider and persists the structured result', () => {
+    expect(searchRequests).toHaveLength(1)
+    expect(searchRequests[0]).toMatchObject({
+      path: '/messages',
+      apiKey: SEARCH_CREDENTIAL,
+      body: {
+        messages: [{
+          role: 'user',
+          content: [{ type: 'text', text: `Perform a web search for the query: ${QUERY}` }],
+        }],
+        tools: [{ type: 'web_search_20250305', name: 'web_search' }],
+      },
+    })
+
+    const auxiliaryRequest = sessionEvents.find(
+      (event): event is Extract<SessionEvent, { type: 'web/deepseek-search-llm-request' }> =>
+        event.type === 'web/deepseek-search-llm-request',
+    )
+    expect(auxiliaryRequest?.data).toEqual({
+      endpoint: `${searchBaseURL}/messages`,
+      apiVersion: '2023-06-01',
+      body: searchRequests[0]?.body,
+    })
+
+    const searchCall = sessionEvents.find(
+      (event): event is Extract<SessionEvent, { type: 'tool/call' }> =>
+        event.type === 'tool/call' && event.data.name === 'web_search',
+    )
+    if (searchCall === undefined) throw new Error('the replayed turn did not call web_search')
+    const searchResult = sessionEvents.find(
+      (event): event is Extract<SessionEvent, { type: 'tool/result' }> =>
+        event.type === 'tool/result' && event.data.message.source.callId === searchCall.data.callId,
+    )
+    if (searchResult === undefined) throw new Error('web_search produced no durable result')
+    const content = searchResult.data.message.content[0]
+    expect(content.isError).toBe(false)
+    expect(content.content.filter(block => block.type === 'text').map(block => block.text).join(''))
+      .toContain(`[Snapshot Search Result](${RESULT_URL})`)
+    expect(searchResult.data.meta).toMatchObject({
+      sources: [{
+        url: RESULT_URL,
+        title: 'Snapshot Search Result',
+        snippet: 'Snapshot search excerpt.',
+        publishedAt: '2026-07-31',
+      }],
+      truncated: false,
+    })
+  })
+
+  it.skipIf(MODE === 'record')('matches the settled search card aria golden', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-search-aria'))
+    await expect.poll(() => page.getByText('SEARCH_DONE', { exact: true }).count(), { timeout: 15_000 })
+      .toBeGreaterThanOrEqual(1)
+    await page.locator('[data-tool="web_search"]').waitFor({ timeout: 10_000 })
+    const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
+    await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
+  })
+
+  it.skipIf(MODE === 'record')('stayed clean and kept the exact fixture inventory', async () => {
+    expect(tripwire.pageErrors).toEqual([])
+    expect(tripwire.warnings).toEqual([])
+    await assertFixtureInventory(SNAPSHOT_DIR, ['session.jsonl', 'ui.expected.md'])
+  })
+})

apps/web/tsconfig.json

@@ -42,6 +42,7 @@
     "tests/code-mode-round.e2e.ts",
     "tests/composer-draft-scroll.e2e.ts",
     "tests/cordis-tool-round.e2e.ts",
+    "tests/web-search-round.e2e.ts",
     "tests/message-actions.e2e.ts",
     "tests/queue-actions.e2e.ts",
     "tests/skill-invocation-policy.e2e.ts",

docs/config-catalog.md

@@ -2164,8 +2164,10 @@ Requires: `web`
 ```ts config-catalog
 /** Plugin config (all optional — `apply` fills env-var and constant defaults). */
 export interface Config {
-  /** DeepSeek API key. Falls back to `$DEEPSEEK_API_KEY`. Empty → unavailable. */
+  /** Literal DeepSeek API key; prefer {@link apiKeyEnv} so no secret enters configuration files. */
   apiKey?: string
+  /** Credential reference resolved for each search; defaults to `DEEPSEEK_API_KEY`. */
+  apiKeyEnv?: string
   /** Anthropic-compatible endpoint base; `/messages` is appended. */
   baseURL?: string
   /** Anthropic-format model name. Defaults to `deepseek-v4-flash`. */
@@ -2179,7 +2181,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/web/web-search-deepseek/src/index.ts:38`](../packages/web/web-search-deepseek/src/index.ts)
+Source: [`packages/web/web-search-deepseek/src/index.ts:43`](../packages/web/web-search-deepseek/src/index.ts)
 
 ## `@deepseek-ai/dsh-web-search-exa`
 

docs/event-producer-consumer.md

@@ -32,7 +32,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:71`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) |
 | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:54`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:135`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
-| `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:70`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm) |
+| `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:70`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm), [`tui`](../packages/ui/tui) |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:59`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) |
 | `session/created` | `emit` | [`packages/core/session/src/index.ts:71`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
 | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:81`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) |

docs/module-graph.md

@@ -431,8 +431,6 @@ flowchart TD
   pkg_web_fetch_local --> pkg_invariants
   pkg_web_fetch_local --> pkg_timeout
   pkg_web_fetch_local --> pkg_web
-  pkg_web_search_deepseek --> pkg_invariants
-  pkg_web_search_deepseek --> pkg_web
   pkg_web_search_exa --> pkg_invariants
   pkg_web_search_exa --> pkg_web
   pkg_web_search_perplexity --> pkg_invariants
@@ -528,6 +526,11 @@ flowchart TD
   pkg_compact_basic --> pkg_llm
   pkg_compact_basic --> pkg_session
   pkg_compact_basic --> pkg_token_meter
+  pkg_web_search_deepseek --> pkg_agent
+  pkg_web_search_deepseek --> pkg_credentials
+  pkg_web_search_deepseek --> pkg_invariants
+  pkg_web_search_deepseek --> pkg_session
+  pkg_web_search_deepseek --> pkg_web
   pkg_spill_local --> pkg_invariants
   pkg_spill_local --> pkg_spill
   pkg_hook_protocol --> pkg_bash
@@ -1104,7 +1107,6 @@ flowchart TD
 | [`compact`](../packages/compact/compact) | `compact` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`web-fetch-local`](../packages/web/web-fetch-local) | `web` | [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) |
-| [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
@@ -1129,6 +1131,7 @@ flowchart TD
 | [`fs-policy`](../packages/fs/fs-policy) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
 | [`skill-local`](../packages/skill/skill-local) | `skill` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`skill`](../packages/skill/skill) |
 | [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
+| [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`web`](../packages/web/web) |
 | [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/support/invariants), [`spill`](../packages/spill/spill) |
 | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) | `session-persistence` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |

docs/persistence-catalog.md

@@ -643,3 +643,14 @@ Source: [`packages/core/session/src/types.ts:193`](../packages/core/session/src/
 ```
 
 Source: [`packages/core/session/src/types.ts:213`](../packages/core/session/src/types.ts)
+
+### `web/*`
+
+#### `web/deepseek-search-llm-request` — log-only
+
+```ts persistence-catalog
+/** Secret-free auxiliary DeepSeek search request recorded before dispatch. */
+'web/deepseek-search-llm-request': DeepSeekSearchLlmRequest
+```
+
+Source: [`packages/web/web-search-deepseek/src/provider.ts:83`](../packages/web/web-search-deepseek/src/provider.ts)

packages/compact/compact-basic/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/compact/compact-basic/README.md
-README.md: 775355f1ac1a7c79c16f66a5b2489d73df7b960d
-README.zh.md: bfa139596b5ef61c23d29575bdea5534fa82b158
+README.md: b35e5dc110e908047338054337b309a77b7e0f68
+README.zh.md: 9c5f83d987b584d58ffacadce4e469bb6ba81aa2

packages/compact/compact-basic/README.md

@@ -136,7 +136,7 @@ Output EXACTLY the Markdown structure below: keep every section, in order. Use t
 - [decisions and their rationale, constraints, user preferences, open questions, data needed to continue]
 
 Rules:
-- Preserve exact file paths, commands, error strings, identifiers, and function signatures.
+- Write concise English engineering prose. Preserve exact file paths, commands, error strings, identifiers, numeric values, function signatures, and syntax fragments.
 - Capture user feedback and explicit instructions faithfully, especially corrections.
 - Do NOT mention this summarization request or that the context was compacted.
 - Output only the checkpoint text: do not call any tool or take any other action.

packages/compact/compact-basic/README.zh.md

@@ -136,7 +136,7 @@ Output EXACTLY the Markdown structure below: keep every section, in order. Use t
 - [decisions and their rationale, constraints, user preferences, open questions, data needed to continue]
 
 Rules:
-- Preserve exact file paths, commands, error strings, identifiers, and function signatures.
+- Write concise English engineering prose. Preserve exact file paths, commands, error strings, identifiers, numeric values, function signatures, and syntax fragments.
 - Capture user feedback and explicit instructions faithfully, especially corrections.
 - Do NOT mention this summarization request or that the context was compacted.
 - Output only the checkpoint text: do not call any tool or take any other action.

packages/compact/compact-basic/src/summarizer.ts

@@ -58,7 +58,7 @@ const COMPACTION_INSTRUCTION = [
   '- [decisions and their rationale, constraints, user preferences, open questions, data needed to continue]',
   '',
   'Rules:',
-  '- Preserve exact file paths, commands, error strings, identifiers, and function signatures.',
+  '- Write concise English engineering prose. Preserve exact file paths, commands, error strings, identifiers, numeric values, function signatures, and syntax fragments.',
   '- Capture user feedback and explicit instructions faithfully, especially corrections.',
   '- Do NOT mention this summarization request or that the context was compacted.',
   '- Output only the checkpoint text: do not call any tool or take any other action.',

packages/compact/compact-basic/tests/compact-basic.spec.ts

@@ -1224,7 +1224,8 @@ describe('default one-shot summarizer', () => {
     expect(messages[0]).toEqual(prefix)
     const last = messages.at(-1)?.content[0]
     const lastText = last?.type === 'text' ? last.text : ''
-    expect(lastText).toContain('Condense the conversation ABOVE')
+    expect(lastText).toContain('Write concise English engineering prose.')
+    expect(lastText).toContain('numeric values, function signatures, and syntax fragments.')
     expect(lastText).toContain('## Primary Request and Intent')
   })
 

packages/compact/compact-basic/tests/compact-loop-repro.spec.ts

@@ -342,6 +342,11 @@ describe('context-overflow recovery across the real loop and compact-basic', ()
 
         expect(adapter.conversationRequests).toHaveLength(2)
         expect(adapter.summaryRequests).toHaveLength(1)
+        const instruction = adapter.summaryRequests[0]!.messages.at(-1)?.content
+          .map(block => (block.type === 'text' ? block.text : ''))
+          .join('') ?? ''
+        expect(instruction).toContain('Write concise English engineering prose.')
+        expect(instruction).toContain('numeric values, function signatures, and syntax fragments.')
         expect(JSON.stringify(adapter.conversationRequests[0]!.messages)).toContain('OLD HISTORY SENTINEL')
         const retry = JSON.stringify(adapter.conversationRequests[1]!.messages)
         expect(retry).toContain('RECOVERY CHECKPOINT')

packages/ui/tui/src/chat/model-command.ts

@@ -8,7 +8,7 @@
  */
 
 import type { AgentLlmTarget, AgentLlmTargetRef } from '@deepseek-ai/dsh-agent'
-import { errorChain, type ReasoningEffortId } from '@deepseek-ai/dsh-llm'
+import { errorChain, LlmError, type ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 import type { TuiOverlaySession } from '../extension/types.ts'
 import { displayText } from '../components/text.ts'
 import {
@@ -37,6 +37,8 @@ export interface ModelController {
   resetContextResolution(): void
   /** Forget the tracked selector overlay (shutdown). */
   clearOverlay(): void
+  /** Remove the adapter-registration listener (channel detach). */
+  detach(): void
 }
 
 type ContextResolution =
@@ -55,8 +57,15 @@ export function createModelController(deps: ModelControllerDeps): ModelControlle
   let modelOverlay: TuiOverlaySession | undefined
   let modelCommands = Promise.resolve()
 
+  // A route whose adapter has not registered yet. Loader activation order is
+  // service-driven, so the TUI can mount before a configured adapter plugin
+  // activates; that transient NO_ADAPTER is not an error — the resolution
+  // waits for the next `llm/adapters-updated` commit instead of surfacing it.
+  let awaitingAdapter = false
+
   const resolveContextWindow = (selected: AgentLlmTarget | undefined): void => {
     contextWindow = undefined
+    awaitingAdapter = false
     const resolution: Promise<ContextResolution> = selected === undefined
       ? Promise.resolve({ kind: 'resolved', contextWindow: undefined } as const)
       : ctx.llm.resolveModelInfo(selected.provider, selected.model).then(
@@ -67,6 +76,10 @@ export function createModelController(deps: ModelControllerDeps): ModelControlle
     void resolution.then((result) => {
       if (contextResolution !== resolution) return
       if (result.kind === 'error') {
+        if (selected !== undefined && result.error instanceof LlmError && result.error.code === 'NO_ADAPTER') {
+          awaitingAdapter = true
+          return
+        }
         deps.appendNotice(`Could not resolve model context: ${errorChain(result.error)}`, 'error')
         return
       }
@@ -74,6 +87,15 @@ export function createModelController(deps: ModelControllerDeps): ModelControlle
       deps.requestRender()
     })
   }
+  // The wait cannot go stale against `target.current`: every target change
+  // re-enters resolveContextWindow, which clears it. A commit that still
+  // lacks the route parks the resolution again rather than erroring, so
+  // unrelated topology changes stay silent. The disposer rides the channel's
+  // detachListeners() through detach(), matching the sibling listeners.
+  const disposeAdapterListener = ctx.on('llm/adapters-updated', () => {
+    if (deps.isDisposed() || !awaitingAdapter) return
+    resolveContextWindow(target.current)
+  })
   resolveContextWindow(target.current)
 
   const selectModel = (
@@ -187,5 +209,8 @@ export function createModelController(deps: ModelControllerDeps): ModelControlle
     clearOverlay(): void {
       modelOverlay = undefined
     },
+    detach(): void {
+      disposeAdapterListener()
+    },
   }
 }

packages/ui/tui/src/index.ts

@@ -1563,6 +1563,7 @@ export function createTuiChat(
     disposeAgent()
     disposeSchemeListener()
     disposeTargetListeners()
+    modelController.detach()
   }
 
   // Sweep reveal of the whole banner: the header wipes in left-to-right over

packages/ui/tui/tests/tui.spec.ts

@@ -10,6 +10,7 @@ import AgentRegistry, {
 } from '@deepseek-ai/dsh-agent'
 import { createUserMessage,
   createToolResultMessage,
+  LlmError,
   ReasoningEffortId,
   type LlmCallConfig,
   type LlmModelReasoningInfo,
@@ -3630,6 +3631,96 @@ describe('pi-tui chat lifecycle and transcript', () => {
     await dispose(reasoningFailed)
   })
 
+  it('defers a NO_ADAPTER context resolution until the provider registers instead of surfacing an error', async () => {
+    // Loader activation order is service-driven: the TUI can mount before a
+    // configured adapter plugin activates, so the initial resolveModelInfo
+    // fails with NO_ADAPTER. That transient state must not print an error;
+    // the resolution retries on llm/adapters-updated.
+    const adapters = new Set<string>()
+    const result = await setup({
+      agentOptions: { provider: 'openai-codex', model: 'gpt-x' },
+      contextTokens: 50_000,
+      catalog: {
+        providers: [],
+        models: [],
+        resolveModelInfo: () => adapters.has('openai-codex')
+          ? Promise.resolve({ context: { contextWindow: 100_000 } })
+          : Promise.reject(new LlmError('no adapter registered for provider "openai-codex"', 'NO_ADAPTER')),
+      },
+    })
+    await tick()
+    expect(result.terminal.output).not.toContain('Could not resolve model context')
+
+    // A topology commit that still lacks the route parks the wait again.
+    result.ctx.emit('llm/adapters-updated')
+    await tick()
+    expect(result.terminal.output).not.toContain('% context')
+    expect(result.terminal.output).not.toContain('Could not resolve model context')
+
+    adapters.add('openai-codex')
+    result.ctx.emit('llm/adapters-updated')
+    await vi.waitFor(() => {
+      expect(result.terminal.output).toContain('% context')
+    })
+    expect(result.terminal.output).not.toContain('Could not resolve model context')
+
+    // A commit after satisfaction is a no-op for the resolved value.
+    result.ctx.emit('llm/adapters-updated')
+    await tick()
+    expect(result.terminal.output).not.toContain('Could not resolve model context')
+    await dispose(result)
+  })
+
+  it('stops listening for adapter registrations after channel detach', async () => {
+    // The listener disposer rides detachListeners() through the controller's
+    // detach(): after dispose, a registry commit must not re-enter resolution
+    // at all (the isDisposed() guard is a fallback, not the removal).
+    const calls: string[] = []
+    const result = await setup({
+      agentOptions: { provider: 'openai-codex', model: 'gpt-x' },
+      catalog: {
+        providers: [],
+        models: [],
+        resolveModelInfo: (provider) => {
+          calls.push(provider)
+          return Promise.reject(new LlmError('no adapter registered for provider "openai-codex"', 'NO_ADAPTER'))
+        },
+      },
+    })
+    await tick()
+    const callsAtDetach = calls.length
+    await result.controller.dispose()
+    result.ctx.emit('llm/adapters-updated')
+    await tick()
+    expect(calls.length).toBe(callsAtDetach)
+    await result.ctx.fiber.dispose()
+  })
+
+  it('drops a deferred NO_ADAPTER resolution when the target moved before the adapter registered', async () => {
+    const result = await setup({
+      agentOptions: { provider: 'openai-codex', model: 'gpt-x' },
+      catalog: {
+        providers: [{ id: 'alpha', name: 'Alpha' }],
+        models: [{ provider: 'alpha', id: 'a1', name: 'Alpha One' }],
+        resolveModelInfo: provider => provider === 'alpha'
+          ? Promise.resolve({ context: { contextWindow: 64_000 } })
+          : Promise.reject(new LlmError('no adapter registered for provider "openai-codex"', 'NO_ADAPTER')),
+      },
+    })
+    await tick()
+    // Switching the model re-resolves and clears the deferred wait, so the
+    // stale route's adapter arriving afterwards must be a no-op.
+    result.terminal.send('/model alpha/a1')
+    result.terminal.send('\r')
+    await vi.waitFor(() => {
+      expect(result.terminal.output).toContain('Model selected: alpha/a1')
+    })
+    result.ctx.emit('llm/adapters-updated')
+    await tick()
+    expect(result.terminal.output).not.toContain('Could not resolve model context')
+    await dispose(result)
+  })
+
   it('does not render a model catalog that resolves after TUI disposal', async () => {
     const deferred = Promise.withResolvers<never[]>()
     const result = await setup({

packages/web/tool-web/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/web/tool-web/README.md
-README.md: 7bee0d2d30fbbcf582fd7b60eb5d9130b6bdf888
-README.zh.md: 3d708839c9ffbdd89df08678fd6997fc6c45ee07
+README.md: 12f5c806db66b2109888c1ec642d117f3432d0df
+README.zh.md: cfbf47219f160af706912ca53f85cff535c381ec

packages/web/tool-web/README.md

@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 The model-facing web tool suite — `web_search` and `web_fetch` — over the [web capability seam](../web/README.md) (`ctx.web`). It owns model-facing concerns only: tool names, JSON schemas, snake_case argument names, prompt sections, the result-count bound, result formatting, HTML→markdown presentation, and the UI presentation projection — `presentCall`, `presentResult` (a `card: 'web'` result card discriminated by `kind: 'search' | 'fetch'`), and the `output.presentationMeta` that carries the structured search sources or the fetch summary the lossy render text cannot (see the [web-result-card Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card.md)). All web access goes through `ctx.web`; this package never imports a concrete provider. Neither tool exposes a model-facing timeout — each tool's cooperative tool-call budget is declared here via config (`fetchTimeoutMs`/`searchTimeoutMs`, attached as `ToolDefinition.timeoutMs`) and enforced by [`@deepseek-ai/dsh-timeout-policy`](../../timeout/timeout-policy/README.md) (a `tools/execute` wrapper); each tool just forwards `exec.signal` to the seam.
 
-Each tool is registered independently; a product that wants only one disables the other via config (`{ search: false }` / `{ fetch: false }`).
+Each tool is registered independently; a product that wants only one disables the other via config (`{ search: false }` / `{ fetch: false }`). Search guidance mentions `web_fetch` only when fetch is also config-enabled; a search-only composition instead tells the model to use returned snippets and cite their URLs.
 
 ## Tools
 
@@ -47,14 +47,20 @@ The tool never calls a provider's `available()` and never enumerates providers
 
 #### What the model sees
 
-Search and fetch contribute the web-search and web-fetch guidance below. A scoped tool restriction does not remove these independently registered sections.
+Search and fetch contribute the web-search and web-fetch guidance below. Search chooses its fetch-enabled or search-only text from config at registration time. A scoped tool restriction does not remove these independently registered sections.
 
-##### Web search guidance
+##### Web search guidance with fetch enabled
 
 ```markdown
 Use the web_search tool to discover current information on the web. It returns an optional answer plus a list of source URLs. Follow up with web_fetch when you need the full content of a specific result, and cite the relevant URLs as markdown links.
 ```
 
+##### Web search-only guidance
+
+```markdown
+Use the web_search tool to discover current information on the web. It returns an optional answer plus a list of source URLs. Use the returned source snippets when available, and cite the relevant URLs as markdown links.
+```
+
 ##### Web fetch guidance
 
 ```markdown
@@ -63,11 +69,11 @@ Use the web_fetch tool to retrieve the content of a specific HTTP(S) URL (for ex
 
 #### Token effect
 
-Fixed guidance cost per request for each config-enabled tool, even when a restriction hides its schema.
+Fixed guidance cost per request for each config-enabled tool, even when a restriction hides its schema. Toggling fetch changes the search guidance as well as registering or removing the fetch section.
 
 #### KV Cache effect
 
-Prefix-stable while enabled tools, scope, and guidance text are unchanged. Config enablement or plugin lifecycle may invalidate reuse from the first changed prompt section; scoped schema restrictions do not remove it.
+Prefix-stable while enabled tools, scope, and guidance text are unchanged. Config enablement—including toggling fetch's search-guidance branch—or plugin lifecycle may invalidate reuse from the first changed prompt section; scoped schema restrictions do not remove it.
 
 ### Tool schemas
 

packages/web/tool-web/README.zh.md

@@ -4,7 +4,7 @@
 
 面向模型的 web 工具套件 `web_search` 与 `web_fetch`，构建于 [web 能力 seam](../web/README.md)（`ctx.web`）之上。它只负责面向模型的事项：工具名称、JSON Schema、snake_case 参数名称、提示词区段、结果数量上限、结果格式、HTML→markdown 呈现，以及 UI 呈现投影——`presentCall`、`presentResult`（以 `kind: 'search' | 'fetch'` 区分的 `card: 'web'` 结果卡片），以及承载有损渲染文本无法携带的结构化搜索来源或抓取摘要的 `output.presentationMeta`（见 [web-result-card Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card.md)）。所有 web 访问都通过 `ctx.web`；该包（package）绝不导入具体提供方。两个工具都不公开面向模型的超时：每个工具的协作式工具调用超时预算通过配置在此声明（`fetchTimeoutMs`／`searchTimeoutMs`，附加为 `ToolDefinition.timeoutMs`），由 [`@deepseek-ai/dsh-timeout-policy`](../../timeout/timeout-policy/README.md)（`tools/execute` 包装层）强制执行；每个工具只把 `exec.signal` 转发给 seam。
 
-每个工具独立注册；只需要其中一个工具的产品可以通过配置禁用另一个（`{ search: false }`／`{ fetch: false }`）。
+每个工具独立注册；只需要其中一个工具的产品可以通过配置禁用另一个（`{ search: false }`／`{ fetch: false }`）。仅当抓取也通过配置启用时，搜索指引才会提及 `web_fetch`；仅启用搜索的组合则会要求模型使用返回的 snippet 并引用其 URL。
 
 ## 工具
 
@@ -47,14 +47,20 @@
 
 #### 模型看到的内容
 
-搜索与抓取分别贡献以下 web-search 和 web-fetch 指引。scope 工具限制不会移除这些独立注册的区段。
+搜索与抓取分别贡献以下 web-search 和 web-fetch 指引。搜索会在注册时根据配置选用启用抓取或仅搜索的文本。scope 工具限制不会移除这些独立注册的区段。
 
-##### Web 搜索指引
+##### 启用抓取时的 Web 搜索指引
 
 ```markdown
 Use the web_search tool to discover current information on the web. It returns an optional answer plus a list of source URLs. Follow up with web_fetch when you need the full content of a specific result, and cite the relevant URLs as markdown links.
 ```
 
+##### 仅搜索时的 Web 搜索指引
+
+```markdown
+Use the web_search tool to discover current information on the web. It returns an optional answer plus a list of source URLs. Use the returned source snippets when available, and cite the relevant URLs as markdown links.
+```
+
 ##### Web 抓取指引
 
 ```markdown
@@ -63,11 +69,11 @@ Use the web_fetch tool to retrieve the content of a specific HTTP(S) URL (for ex
 
 #### Token 影响
 
-每个通过配置启用的工具都会为每次请求增加固定的指引 token 开销，即使限制隐藏了其 schema。
+每个通过配置启用的工具都会为每次请求增加固定的指引 token 开销，即使限制隐藏了其 schema。切换抓取状态不仅会注册或移除抓取区段，也会更改搜索指引。
 
 #### KV Cache 影响
 
-只要启用工具、scope 与指引文本不变，前缀就保持稳定。配置启用状态或插件生命周期可能使从第一个变化的提示词区段起的复用失效；scope schema 限制不会移除该区段。
+只要启用工具、scope 与指引文本不变，前缀就保持稳定。配置启用状态（包括因切换抓取状态而改变搜索指引分支）或插件生命周期可能使从第一个变化的提示词区段起的复用失效；scope schema 限制不会移除该区段。
 
 ### 工具 schema
 

packages/web/tool-web/src/index.ts

@@ -84,6 +84,8 @@ export function apply(ctx: Context, config: Config): void {
   assertPositiveInteger('fetchTimeoutMs', resolved.fetchTimeoutMs)
   assertPositiveInteger('searchTimeoutMs', resolved.searchTimeoutMs)
   assertPositiveInteger('fetchMaxOutputChars', resolved.fetchMaxOutputChars)
-  if (resolved.search) applyWebSearchTool(ctx, resolved.searchMaxResults, resolved.searchTimeoutMs)
+  if (resolved.search) {
+    applyWebSearchTool(ctx, resolved.searchMaxResults, resolved.searchTimeoutMs, resolved.fetch)
+  }
   if (resolved.fetch) applyWebFetchTool(ctx, resolved.fetchTimeoutMs, resolved.fetchMaxOutputChars)
 }

packages/web/tool-web/src/search.ts

@@ -204,12 +204,21 @@ export function presentSearchResult(args: { query: string }, result: ToolResult)
  *   request's `maxResults`.
  * @param timeoutMs - the cooperative tool-call budget (ms) attached as the tool's
  *   `ToolDefinition.timeoutMs` for `@deepseek-ai/dsh-timeout-policy` to enforce.
+ * @param fetchEnabled - whether the same composition exposes `web_fetch`, which
+ *   controls whether search guidance may recommend that follow-up tool.
  */
-export function applyWebSearchTool(ctx: Context, maxResults: number, timeoutMs: number): void {
+export function applyWebSearchTool(
+  ctx: Context,
+  maxResults: number,
+  timeoutMs: number,
+  fetchEnabled: boolean,
+): void {
   ctx.systemPrompt.section({
     name: 'tool:web_search',
     order: 110,
-    text: 'Use the web_search tool to discover current information on the web. It returns an optional answer plus a list of source URLs. Follow up with web_fetch when you need the full content of a specific result, and cite the relevant URLs as markdown links.',
+    text: fetchEnabled
+      ? 'Use the web_search tool to discover current information on the web. It returns an optional answer plus a list of source URLs. Follow up with web_fetch when you need the full content of a specific result, and cite the relevant URLs as markdown links.'
+      : 'Use the web_search tool to discover current information on the web. It returns an optional answer plus a list of source URLs. Use the returned source snippets when available, and cite the relevant URLs as markdown links.',
   })
 
   ctx.tools.register(defineTool({

packages/web/tool-web/tests/tool-web.spec.ts

@@ -483,8 +483,17 @@ describe('tool-web registration', () => {
     const { fiber, ctx } = await mountTools()
     const prompt = await ctx.systemPrompt.assemble()
     const text = prompt.sections.map(s => s.text).join('\n')
-    expect(text).toContain('web_search')
-    expect(text).toContain('web_fetch')
+    expect(text).toContain('Use the web_search tool to discover current information on the web. It returns an optional answer plus a list of source URLs. Follow up with web_fetch when you need the full content of a specific result, and cite the relevant URLs as markdown links.')
+    expect(text).toContain('Use the web_fetch tool to retrieve the content of a specific HTTP(S) URL')
+    await fiber.dispose()
+  })
+
+  it('does not advertise web_fetch in search-only prompt guidance', async () => {
+    const { fiber, ctx } = await mountTools({ config: { search: true, fetch: false } })
+    const prompt = await ctx.systemPrompt.assemble()
+    const text = prompt.sections.map(s => s.text).join('\n')
+    expect(text).toContain('Use the returned source snippets when available')
+    expect(text).not.toContain('web_fetch')
     await fiber.dispose()
   })
 })

packages/web/web-search-deepseek/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/web/web-search-deepseek/README.md
-README.md: 54eb7561b9d81a9e2da565e3870abe094dbe984d
-README.zh.md: 8862b8a9c1ba69d247942bb6e41289214826c682
+README.md: 9046934de209ed0787efa50332e5be16bfdf55c6
+README.zh.md: 94e01daba69cecd2f5c3c6680979ee5fd66d7cdd

packages/web/web-search-deepseek/README.md

@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 A [DeepSeek](https://deepseek.com)-backed `WebSearchProvider` for the harness [web capability seam](../web/README.md) (`ctx.web`). It calls DeepSeek's **Anthropic-compatible Messages API** (`POST {baseURL}/messages`) with the native `web_search_20250305` server tool enabled, and maps the structured `web_search_tool_result` blocks DeepSeek returns into the seam's normalized `WebSearchResult`.
 
-This is an **implementation** package: it registers a provider into `ctx.web`, it does not own the key and it does not register a model-facing tool. Like `@deepseek-ai/dsh-llm-deepseek`, it is a function/namespace plugin (`inject: ['web']`). The Anthropic wire shape is a provider-private detail — it does **not** make this provider depend on `ctx.llm`.
+This is an **implementation** package: it registers a provider into `ctx.web`, resolves its credential for each search through the optional `ctx.credentials` seam, records the auxiliary request in the initiating Agent session when one exists, and does not register a model-facing tool. Like `@deepseek-ai/dsh-llm-deepseek`, it is a function/namespace plugin (`inject: ['web']`). The Anthropic wire shape is a provider-private detail — it does **not** make this provider depend on `ctx.llm`.
 
 ## How it differs from a dedicated search endpoint
 
@@ -12,13 +12,14 @@ Exa and Perplexity expose dedicated search endpoints; DeepSeek does not. Instead
 
 **Strict mode**: if the response carries no `web_search_tool_result` block (native search did not trigger), the provider throws `WebError` `WEB_PROVIDER_ERROR` rather than degrading to prose-scraping — honest and debuggable.
 
-It reuses `$DEEPSEEK_API_KEY` (no new secret) but **not** `$DEEPSEEK_BASE_URL`: the search endpoint is the Anthropic-compatible base (`https://api.deepseek.com/anthropic/v1`), distinct from the chat-completions base (`https://api.deepseek.com`) the LLM adapter uses.
+It reuses the `DEEPSEEK_API_KEY` credential reference (no new secret) but **not** `$DEEPSEEK_BASE_URL`: the search endpoint is the Anthropic-compatible base (`https://api.deepseek.com/anthropic/v1`), distinct from the chat-completions base (`https://api.deepseek.com`) the LLM adapter uses. A mounted credentials service is authoritative; without one, the provider falls back to the launching process environment. The reference is resolved for each search, so a key stored or rotated by the Web Models page reaches the next call without a restart.
 
 ## Config
 
 | Key | Default | Meaning |
 |---|---|---|
-| `apiKey` | `$DEEPSEEK_API_KEY` | DeepSeek API key. Empty/absent makes the provider unavailable. Sent as both `x-api-key` and `Authorization: Bearer` (official vs Anthropic-compatible proxy). |
+| `apiKey` | omitted | Literal DeepSeek API key. Prefer `apiKeyEnv` so no secret enters configuration; a non-empty literal wins. |
+| `apiKeyEnv` | `DEEPSEEK_API_KEY` | Credential reference resolved for each search through `ctx.credentials`, or from the process environment when that seam is absent. A missing value fails the call as `WEB_PROVIDER_CREDENTIAL_MISSING`. |
 | `baseURL` | `https://api.deepseek.com/anthropic/v1` | Anthropic-compatible endpoint base; `/messages` is appended. Use a separate env var such as `$DEEPSEEK_SEARCH_BASE_URL` when overriding it; do not reuse `$DEEPSEEK_BASE_URL`, which belongs to the chat-completions LLM adapter. An unparseable value makes the provider unavailable. |
 | `model` | `deepseek-v4-flash` | Anthropic-format model name. |
 | `apiVersion` | `2023-06-01` | `anthropic-version` header value. |
@@ -29,7 +30,7 @@ It reuses `$DEEPSEEK_API_KEY` (no new secret) but **not** `$DEEPSEEK_BASE_URL`:
 - id: web-search-deepseek
   name: '@deepseek-ai/dsh-web-search-deepseek'
   config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    apiKeyEnv: DEEPSEEK_API_KEY
     baseURL: !!js process.env.DEEPSEEK_SEARCH_BASE_URL
 ```
 
@@ -41,6 +42,10 @@ Results are deduplicated by URL because one request may surface the same page ac
 
 Provider failures become `WEB_PROVIDER_ERROR`; caller cancellation becomes `WEB_ABORTED`. HTTP redirects are rejected before the `Location` target is contacted and surface as `WEB_PROVIDER_ERROR`.
 
+## Request logging
+
+Immediately before dispatch, a search running under an initiating Agent appends the log-only `web/deepseek-search-llm-request` session event. It contains the resolved endpoint, API version, and exact secret-free JSON body sent to DeepSeek; headers and credentials are excluded. Credential failures and cancellations before dispatch create no event, while later HTTP or response failures leave the attempted request durable. Direct programmatic provider calls outside an Agent have no initiating session to log.
+
 ## Model Experience
 
 ### Auxiliary DeepSeek search request
@@ -61,7 +66,7 @@ Independent of the conversation request cache. The auxiliary instruction and nat
 
 #### What the model sees
 
-Through [`dsh-tool-web`](../tool-web/README.md), the conversation model sees deduplicated URLs, titles, dates, and citation snippets from structured search blocks; provider prose is not trusted as an answer. This provider's exact failures are `DeepSeek search aborted`, `DeepSeek search request failed: <error>`, `DeepSeek returned no web_search_tool_result blocks; the request may not have triggered native web search`, and `DeepSeek returned an unprocessable response body: <error>`; HTTP failures preserve the provider message. The consumer owns the error wrapper.
+Through [`dsh-tool-web`](../tool-web/README.md), the conversation model sees deduplicated URLs, titles, dates, and citation snippets from structured search blocks; provider prose is not trusted as an answer. This provider's exact failures include the actionable missing-credential message, `DeepSeek search credential resolution failed: <error>`, `DeepSeek search aborted`, `DeepSeek search request failed: <error>`, `DeepSeek returned no web_search_tool_result blocks; the request may not have triggered native web search`, and `DeepSeek returned an unprocessable response body: <error>`; HTTP failures preserve the provider message. The consumer owns the error wrapper.
 
 #### Token effect
 
@@ -74,6 +79,6 @@ Append-only; newly visible content follows the reusable request prefix and does
 ## Known Limitations and Deferred Work
 
 - **One search costs a full Messages model turn** — latency plus generated tokens, with up to `maxUses` server-side searches; DeepSeek exposes no dedicated retrieval endpoint.
+- **Dynamic credential availability resolves inside the operation** — the synchronous `available()` contract can establish that a resolver exists but cannot query an asynchronous credential store. A selected keyless provider therefore fails the search with `WEB_PROVIDER_CREDENTIAL_MISSING`; the stable `web_search` schema remains registered. Caller cancellation races this preflight locally, but cannot force an arbitrary credential backend itself to stop work.
 - **Over-returned sources still cost tokens** — with no result-count knob on the wire, `maxResults` is enforced only post-hoc by seam truncation.
 - **Uncited results carry no `snippet`** — a source gains one only when a `text` block citation (`cited_text`) matches its URL.
-- **Abort classification is error-shape-based** — only a `DOMException` named `AbortError` maps to `WEB_ABORTED`; an abort carrying a custom reason (e.g. `dsh-timeout`'s `TimeoutReason`) surfaces as `WEB_PROVIDER_ERROR`.

packages/web/web-search-deepseek/README.zh.md

@@ -4,7 +4,7 @@
 
 由 [DeepSeek](https://deepseek.com) 支持的 `WebSearchProvider`，用于 harness [web 能力 seam](../web/README.md)（`ctx.web`）。它调用 DeepSeek 的 **Anthropic 兼容 Messages API**（`POST {baseURL}/messages`），启用原生 `web_search_20250305` 服务器工具，并把 DeepSeek 返回的结构化 `web_search_tool_result` 块映射为 seam 规范化的 `WebSearchResult`。
 
-这是一个**实现**包（package）：它向 `ctx.web` 注册提供方，不拥有该键，也不注册面向模型的工具。与 `@deepseek-ai/dsh-llm-deepseek` 一样，它是函数／命名空间插件（`inject: ['web']`）。Anthropic 协议格式（wire format）是提供方私有细节，并**不**使该提供方依赖 `ctx.llm`。
+这是一个**实现**包（package）：它向 `ctx.web` 注册提供方，通过可选的 `ctx.credentials` seam 为每次搜索解析凭据，若存在发起请求的 agent（智能体）会话，还会在其中记录该辅助请求，且不注册面向模型的工具。与 `@deepseek-ai/dsh-llm-deepseek` 一样，它是函数／命名空间插件（`inject: ['web']`）。Anthropic 协议格式（wire format）是提供方私有细节，并**不**使该提供方依赖 `ctx.llm`。
 
 ## 与专用搜索端点的区别
 
@@ -12,13 +12,14 @@ Exa 和 Perplexity 提供专用搜索端点，DeepSeek 则没有。该提供方
 
 **严格模式**：如果响应不含 `web_search_tool_result` 块（未触发原生搜索），提供方会抛出 `WebError` `WEB_PROVIDER_ERROR`，而非降级为文本抓取；这种行为诚实且可诊断。
 
-它复用 `$DEEPSEEK_API_KEY`（不增加密钥），但**不会**复用 `$DEEPSEEK_BASE_URL`：搜索端点使用 Anthropic 兼容基址（`https://api.deepseek.com/anthropic/v1`），不同于大语言模型（LLM）适配器使用的 chat-completions 基址（`https://api.deepseek.com`）。
+它复用 `DEEPSEEK_API_KEY` 凭据引用（不增加密钥），但**不会**复用 `$DEEPSEEK_BASE_URL`：搜索端点使用 Anthropic 兼容基址（`https://api.deepseek.com/anthropic/v1`），不同于大语言模型（LLM）适配器使用的 chat-completions 基址（`https://api.deepseek.com`）。已挂载的凭据服务具有权威性；没有该服务时，提供方会回退到启动进程的环境变量。每次搜索都会解析该引用，因此在 Web 的 Models 页中存储或轮换的密钥无需重启，即可用于下一次调用。
 
 ## 配置
 
 | 配置键 | 默认值 | 含义 |
 |---|---|---|
-| `apiKey` | `$DEEPSEEK_API_KEY` | DeepSeek API 密钥。为空或缺失时提供方不可用。同时通过 `x-api-key` 和 `Authorization: Bearer` 发送（分别用于官方接口与 Anthropic 兼容代理）。 |
+| `apiKey` | 未设置 | DeepSeek API 密钥字面值。优先使用 `apiKeyEnv`，避免密钥进入配置；非空字面值优先。 |
+| `apiKeyEnv` | `DEEPSEEK_API_KEY` | 每次搜索都会通过 `ctx.credentials` 解析该凭据引用；没有该 seam 时则从进程环境解析。值缺失时，调用以 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败。 |
 | `baseURL` | `https://api.deepseek.com/anthropic/v1` | Anthropic 兼容端点基址；追加 `/messages`。覆盖时使用 `$DEEPSEEK_SEARCH_BASE_URL` 等独立环境变量；禁止复用属于 chat-completions LLM 适配器的 `$DEEPSEEK_BASE_URL`。无法解析时提供方不可用。 |
 | `model` | `deepseek-v4-flash` | Anthropic 格式模型名称。 |
 | `apiVersion` | `2023-06-01` | `anthropic-version` 标头值。 |
@@ -29,7 +30,7 @@ Exa 和 Perplexity 提供专用搜索端点，DeepSeek 则没有。该提供方
 - id: web-search-deepseek
   name: '@deepseek-ai/dsh-web-search-deepseek'
   config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    apiKeyEnv: DEEPSEEK_API_KEY
     baseURL: !!js process.env.DEEPSEEK_SEARCH_BASE_URL
 ```
 
@@ -41,6 +42,10 @@ DeepSeek 不返回该提供方可作为 `content` 信任的提供方生成答案
 
 提供方失败变为 `WEB_PROVIDER_ERROR`；调用方取消变为 `WEB_ABORTED`。HTTP 重定向会在接触 `Location` 目标前被拒绝，并以 `WEB_PROVIDER_ERROR` 呈现。
 
+## 请求日志
+
+由 agent 发起的搜索会在发出请求前一刻，向相应会话追加仅用于日志的 `web/deepseek-search-llm-request` 会话事件。其中包含已解析端点、API 版本，以及发送给 DeepSeek 且不含密钥的精确 JSON 请求体；不包含标头和凭据。发出请求前发生凭据处理失败或取消时不会创建事件；发出请求后才发生 HTTP 或响应失败时，本次请求尝试仍保留持久记录。在 agent 之外通过程序直接调用提供方时，没有发起会话可供记录。
+
 ## 模型体验
 
 ### 辅助 DeepSeek 搜索请求
@@ -61,7 +66,7 @@ DeepSeek 不返回该提供方可作为 `content` 信任的提供方生成答案
 
 #### 模型看到的内容
 
-通过 [`dsh-tool-web`](../tool-web/README.md)，会话模型会看到结构化搜索块中去重后的 URL、标题、日期与引用 snippet；提供方文本不会作为答案受到信任。该提供方的具体错误消息为 `DeepSeek search aborted`、`DeepSeek search request failed: <error>`、`DeepSeek returned no web_search_tool_result blocks; the request may not have triggered native web search` 和 `DeepSeek returned an unprocessable response body: <error>`；HTTP 失败保留提供方消息。错误包装属于消费方。
+通过 [`dsh-tool-web`](../tool-web/README.md)，会话模型会看到结构化搜索块中去重后的 URL、标题、日期与引用 snippet；提供方文本不会作为答案受到信任。该提供方的具体错误消息包括带有处理指引的凭据缺失消息、`DeepSeek search credential resolution failed: <error>`、`DeepSeek search aborted`、`DeepSeek search request failed: <error>`、`DeepSeek returned no web_search_tool_result blocks; the request may not have triggered native web search` 和 `DeepSeek returned an unprocessable response body: <error>`；HTTP 失败保留提供方消息。错误包装属于消费方。
 
 #### Token 影响
 
@@ -74,6 +79,6 @@ DeepSeek 不返回该提供方可作为 `content` 信任的提供方生成答案
 ## 已知限制与暂缓事项
 
 - **一次搜索需要完整的 Messages 模型轮次**：会产生延迟与生成 token，并且最多执行 `maxUses` 次服务器侧搜索；DeepSeek 不公开专用检索端点。
+- **动态凭据的可用性在操作内部解析**：同步的 `available()` 契约可以确认解析器存在，但无法查询异步凭据存储。因此，选中的无密钥提供方会使搜索以 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败；稳定的 `web_search` schema 仍保持注册。调用方取消在本地与该预检存在竞态，但无法强制任意凭据后端自行停止工作。
 - **超量返回的源仍消耗 token**：协议没有结果数量旋钮，`maxResults` 只能由 seam 在事后截断。
 - **未引用的结果没有 `snippet`**：只有 `text` 块中的引用（`cited_text`）匹配其 URL 时，源才会获得 snippet。
-- **中止分类基于错误结构**：只有 `DOMException` 且名为 `AbortError` 时才映射为 `WEB_ABORTED`；携带自定义原因的中止（例如 `dsh-timeout` 的 `TimeoutReason`）会呈现为 `WEB_PROVIDER_ERROR`。

packages/web/web-search-deepseek/package.json

@@ -27,7 +27,10 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-credentials": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
     "@deepseek-ai/dsh-web": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
@@ -35,7 +38,11 @@
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-credentials": "workspace:^",
+    "@deepseek-ai/dsh-credentials-local": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-web": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }

packages/web/web-search-deepseek/src/index.ts

@@ -7,6 +7,9 @@
 
 import type { Context } from 'cordis'
 import z from 'schemastery'
+import type {} from '@deepseek-ai/dsh-agent'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import type {} from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-web'
 import {
   DeepSeekSearchProvider,
@@ -26,7 +29,7 @@ export {
   DEEPSEEK_DEFAULT_MODEL,
   DEEPSEEK_PROVIDER_ID,
 } from './provider.ts'
-export type { DeepSeekSearchProviderOptions } from './provider.ts'
+export type { DeepSeekSearchLlmRequest, DeepSeekSearchProviderOptions } from './provider.ts'
 
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'web-search-deepseek'
@@ -34,10 +37,14 @@ export const name = 'web-search-deepseek'
 /** The web seam this provider registers into. */
 export const inject = ['web']
 
+const DEFAULT_API_KEY_ENV = 'DEEPSEEK_API_KEY'
+
 /** Plugin config (all optional — `apply` fills env-var and constant defaults). */
 export interface Config {
-  /** DeepSeek API key. Falls back to `$DEEPSEEK_API_KEY`. Empty → unavailable. */
+  /** Literal DeepSeek API key; prefer {@link apiKeyEnv} so no secret enters configuration files. */
   apiKey?: string
+  /** Credential reference resolved for each search; defaults to `DEEPSEEK_API_KEY`. */
+  apiKeyEnv?: string
   /** Anthropic-compatible endpoint base; `/messages` is appended. */
   baseURL?: string
   /** Anthropic-format model name. Defaults to `deepseek-v4-flash`. */
@@ -51,7 +58,8 @@ export interface Config {
 }
 
 export const Config: z<Config> = z.object({
-  apiKey: z.string(),
+  apiKey: z.string().role('secret'),
+  apiKeyEnv: z.string().role('credential-ref').default(DEFAULT_API_KEY_ENV),
   baseURL: z.string(),
   model: z.string(),
   apiVersion: z.string(),
@@ -63,12 +71,29 @@ export const Config: z<Config> = z.object({
 export function apply(ctx: Context, config: Config): void {
   const maxTokens = config.maxTokens ?? DEEPSEEK_DEFAULT_MAX_TOKENS
   const maxUses = config.maxUses ?? DEEPSEEK_DEFAULT_MAX_USES
+  const apiKeyEnv = credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV)
+  const literalApiKey = config.apiKey !== undefined && config.apiKey.length > 0
+    ? config.apiKey
+    : undefined
   ctx.web.registerSearchProvider(new DeepSeekSearchProvider({
-    apiKey: config.apiKey ?? process.env.DEEPSEEK_API_KEY ?? '',
+    ...literalApiKey === undefined ? {} : { apiKey: literalApiKey },
+    resolveApiKey: async () => {
+      const credentials = ctx.get('credentials')
+      if (credentials !== undefined) return (await credentials.resolve(apiKeyEnv))?.value
+      const ambient = process.env[apiKeyEnv]
+      return ambient !== undefined && ambient.length > 0 ? ambient : undefined
+    },
+    apiKeyEnv,
     baseURL: config.baseURL ?? DEEPSEEK_DEFAULT_BASE_URL,
     model: config.model ?? DEEPSEEK_DEFAULT_MODEL,
     apiVersion: config.apiVersion ?? DEEPSEEK_DEFAULT_API_VERSION,
     maxTokens,
     maxUses,
+    recordRequest: (request) => {
+      ctx.get('agents')?.currentInitiator()?.session.append(
+        'web/deepseek-search-llm-request',
+        request,
+      )
+    },
   }))
 }

packages/web/web-search-deepseek/src/invariant.ts

@@ -15,8 +15,9 @@ export const name = 'web-search-deepseek-invariant'
 export const inject = ['invariants']
 
 /**
- * No runtime invariant: this package exposes no independent event sequence or mutable data relation
- * beyond contracts enforced at its owning seam.
+ * No runtime invariant: the package emits a pre-dispatch log event but owns no
+ * later authoritative dispatch event to relate it to. Exact envelope equality
+ * is pinned at the provider boundary instead.
  */
 const install: InvariantInstaller = () => {}
 

packages/web/web-search-deepseek/src/provider.ts

@@ -13,6 +13,8 @@ import type {
   WebSearchResult,
   WebSearchSource,
 } from '@deepseek-ai/dsh-web'
+import type { CredentialRef } from '@deepseek-ai/dsh-credentials'
+import type {} from '@deepseek-ai/dsh-session'
 import type {
   AnthropicError,
   AnthropicResponse,
@@ -47,10 +49,49 @@ export const DEEPSEEK_DEFAULT_MAX_USES = 5
 /** Attribution header sent on every request. Bump with the package version. */
 const USER_AGENT = 'deepseek-harness/0.0.1'
 
-/** Resolved provider options (the plugin's `apply` supplies env-var and constant defaults). */
+/**
+ * Exact secret-free DeepSeek Messages request recorded immediately before one
+ * auxiliary search dispatch.
+ */
+export interface DeepSeekSearchLlmRequest {
+  /** Fully resolved Messages endpoint. */
+  readonly endpoint: string
+  /** `anthropic-version` header value. */
+  readonly apiVersion: string
+  /** Exact JSON body sent to the provider. */
+  readonly body: {
+    readonly model: string
+    readonly max_tokens: number
+    readonly messages: readonly [{
+      readonly role: 'user'
+      readonly content: readonly [{
+        readonly type: 'text'
+        readonly text: string
+      }]
+    }]
+    readonly tools: readonly [{
+      readonly type: 'web_search_20250305'
+      readonly name: 'web_search'
+      readonly max_uses: number
+    }]
+  }
+}
+
+declare module '@deepseek-ai/dsh-session' {
+  interface SessionEventMap {
+    /** Secret-free auxiliary DeepSeek search request recorded before dispatch. */
+    'web/deepseek-search-llm-request': DeepSeekSearchLlmRequest
+  }
+}
+
+/** Resolved provider options (the plugin's `apply` supplies credential and constant defaults). */
 export interface DeepSeekSearchProviderOptions {
-  /** DeepSeek API key. Empty/absent makes the provider unavailable. */
-  apiKey: string
+  /** Literal DeepSeek API key; when present it wins over {@link resolveApiKey}. */
+  apiKey?: string
+  /** Resolve the current DeepSeek API key for one search operation. */
+  resolveApiKey?: () => Promise<string | undefined>
+  /** Credential reference named by missing-credential diagnostics. */
+  apiKeyEnv?: CredentialRef
   /** Endpoint base; `/messages` is appended. */
   baseURL: string
   /** Anthropic-format model name. */
@@ -61,6 +102,11 @@ export interface DeepSeekSearchProviderOptions {
   maxTokens: number
   /** Maximum `web_search` server-tool uses per request. */
   maxUses: number
+  /**
+   * Record the exact secret-free request immediately before dispatch. A throw
+   * prevents dispatch so model-visible auxiliary input cannot escape logging.
+   */
+  recordRequest?: (request: DeepSeekSearchLlmRequest) => void
 }
 
 /**
@@ -134,41 +180,51 @@ export class DeepSeekSearchProvider implements WebSearchProvider {
   constructor(private readonly options: DeepSeekSearchProviderOptions) {}
 
   available(): boolean {
-    return this.options.apiKey.length > 0
+    return ((this.options.apiKey?.length ?? 0) > 0 || this.options.resolveApiKey !== undefined)
       && URL.canParse(this.options.baseURL)
       && isPositiveInteger(this.options.maxTokens)
       && isPositiveInteger(this.options.maxUses)
   }
 
   async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult> {
+    const apiKey = await this.apiKey(signal)
+    throwIfSearchAborted(signal)
+    const endpoint = `${this.options.baseURL}/messages`
+    const body: DeepSeekSearchLlmRequest['body'] = {
+      model: this.options.model,
+      max_tokens: this.options.maxTokens,
+      messages: [{
+        role: 'user',
+        content: [{ type: 'text', text: `Perform a web search for the query: ${request.query}` }],
+      }],
+      tools: [{ type: 'web_search_20250305', name: 'web_search', max_uses: this.options.maxUses }],
+    }
+    this.options.recordRequest?.({
+      endpoint,
+      apiVersion: this.options.apiVersion,
+      body,
+    })
+    throwIfSearchAborted(signal)
     let response: Response
     try {
-      response = await fetch(`${this.options.baseURL}/messages`, {
+      response = await fetch(endpoint, {
         method: 'POST',
         redirect: 'error',
         headers: {
           // Official DeepSeek expects `x-api-key`; an Anthropic-compatible proxy
           // may expect `Authorization: Bearer` — send both so either resolves.
-          'x-api-key': this.options.apiKey,
-          'authorization': `Bearer ${this.options.apiKey}`,
+          'x-api-key': apiKey,
+          'authorization': `Bearer ${apiKey}`,
           'anthropic-version': this.options.apiVersion,
           'content-type': 'application/json',
           'accept': 'application/json',
           'user-agent': USER_AGENT,
         },
-        body: JSON.stringify({
-          model: this.options.model,
-          max_tokens: this.options.maxTokens,
-          messages: [{
-            role: 'user',
-            content: [{ type: 'text', text: `Perform a web search for the query: ${request.query}` }],
-          }],
-          tools: [{ type: 'web_search_20250305', name: 'web_search', max_uses: this.options.maxUses }],
-        }),
+        body: JSON.stringify(body),
         ...signal !== undefined ? { signal } : {},
       })
     } catch (error: unknown) {
-      if (isAbortError(error)) throw new WebError('DeepSeek search aborted', 'WEB_ABORTED', { cause: error })
+      if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error)
       throw new WebError(`DeepSeek search request failed: ${String(error)}`, 'WEB_PROVIDER_ERROR', { cause: error })
     }
 
@@ -183,7 +239,7 @@ export class DeepSeekSearchProvider implements WebSearchProvider {
         // An abort fired mid-body must surface as WEB_ABORTED, not be swallowed
         // into a generic HTTP-error message — cancellation is not a provider
         // error (the seam's cancellation contract).
-        if (isAbortError(error)) throw new WebError('DeepSeek search aborted', 'WEB_ABORTED', { cause: error })
+        if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error)
         // Otherwise: the HTTP status is already captured in `message` above; a
         // malformed/non-JSON error body (normal for gateway 5xx/429s) can only
         // cost a richer provider message, never the real error.
@@ -195,11 +251,72 @@ export class DeepSeekSearchProvider implements WebSearchProvider {
       const payload = await response.json() as AnthropicResponse
       return mapAnthropicResponse(payload)
     } catch (error: unknown) {
-      if (isAbortError(error)) throw new WebError('DeepSeek search aborted', 'WEB_ABORTED', { cause: error })
+      if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error)
       if (error instanceof WebError) throw error
       throw new WebError(`DeepSeek returned an unprocessable response body: ${String(error)}`, 'WEB_PROVIDER_ERROR', { cause: error })
     }
   }
+
+  /** Resolve one operation's credential without retaining it on the provider. */
+  private async apiKey(signal?: AbortSignal): Promise<string> {
+    throwIfSearchAborted(signal)
+    if (this.options.apiKey !== undefined && this.options.apiKey.length > 0) return this.options.apiKey
+    let resolved: string | undefined
+    try {
+      resolved = await abortable(this.options.resolveApiKey?.() ?? Promise.resolve(undefined), signal)
+    } catch (error: unknown) {
+      if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error)
+      throw new WebError(
+        `DeepSeek search credential resolution failed: ${String(error)}`,
+        'WEB_PROVIDER_ERROR',
+        { cause: error },
+      )
+    }
+    if (resolved !== undefined && resolved.length > 0) return resolved
+    const ref = this.options.apiKeyEnv ?? 'DEEPSEEK_API_KEY'
+    throw new WebError(
+      `DeepSeek search has no API key for "${ref}"; store it through the credentials service`
+      + ' (the web Models page writes it), export it in the launching environment, or set a literal'
+      + ' "apiKey" in the web-search-deepseek config',
+      'WEB_PROVIDER_CREDENTIAL_MISSING',
+    )
+  }
+}
+
+/**
+ * Race a same-process asynchronous preflight against caller cancellation. The
+ * attached settlement handlers keep observing an uncooperative operation after
+ * abort so a later rejection cannot become unhandled.
+ */
+function abortable<T>(operation: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (signal === undefined) return operation
+  if (signal.aborted) return Promise.reject(searchAborted(signal))
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => { reject(searchAborted(signal)) }
+    signal.addEventListener('abort', onAbort, { once: true })
+    void operation.then(
+      (value) => {
+        signal.removeEventListener('abort', onAbort)
+        resolve(value)
+      },
+      (error: unknown) => {
+        signal.removeEventListener('abort', onAbort)
+        reject(new Error(String(error).replace(/^Error: /u, ''), { cause: error }))
+      },
+    )
+  })
+}
+
+/** Throw the provider's stable cancellation error when the caller already aborted. */
+function throwIfSearchAborted(signal?: AbortSignal): void {
+  if (signal?.aborted === true) throw searchAborted(signal)
+}
+
+/** Build the provider's stable cancellation error while retaining the caller's reason. */
+function searchAborted(signal?: AbortSignal, fallback?: unknown): WebError {
+  return new WebError('DeepSeek search aborted', 'WEB_ABORTED', {
+    cause: signal?.aborted === true ? signal.reason : fallback,
+  })
 }
 
 /** True for a fetch/`AbortSignal` abort, surfaced as `WEB_ABORTED`. */

packages/web/web-search-deepseek/tests/deepseek.spec.ts

@@ -1,6 +1,11 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import CredentialsLocal from '@deepseek-ai/dsh-credentials-local'
 import WebService from '@deepseek-ai/dsh-web'
 import {
   DeepSeekSearchProvider,
@@ -156,10 +161,11 @@ describe('DeepSeekSearchProvider availability', () => {
 })
 
 describe('DeepSeekSearchProvider request mapping', () => {
-  it('posts an Anthropic Messages request enabling the web_search server tool', async () => {
+  it('records and posts the same Anthropic Messages request with the web_search server tool', async () => {
     const fetchMock = vi.fn(async () => jsonResponse(searchResponse()))
+    const recordRequest = vi.fn()
     vi.stubGlobal('fetch', fetchMock)
-    await new DeepSeekSearchProvider(options).search({ query: 'hello' })
+    await new DeepSeekSearchProvider({ ...options, recordRequest }).search({ query: 'hello' })
     const [url, init] = fetchMock.mock.calls[0] as unknown as [string, RequestInit]
     expect(url).toBe('https://api.deepseek.test/anthropic/v1/messages')
     expect(init).toMatchObject({ method: 'POST', redirect: 'error' })
@@ -167,12 +173,20 @@ describe('DeepSeekSearchProvider request mapping', () => {
     expect(headers['x-api-key']).toBe('ds-key')
     expect(headers['authorization']).toBe('Bearer ds-key')
     expect(headers['anthropic-version']).toBe('2023-06-01')
-    expect(JSON.parse(init.body as string)).toEqual({
+    const body = {
       model: 'deepseek-chat',
       max_tokens: 4096,
       messages: [{ role: 'user', content: [{ type: 'text', text: 'Perform a web search for the query: hello' }] }],
       tools: [{ type: 'web_search_20250305', name: 'web_search', max_uses: 5 }],
+    }
+    expect(JSON.parse(init.body as string)).toEqual(body)
+    expect(recordRequest).toHaveBeenCalledOnce()
+    expect(recordRequest).toHaveBeenCalledWith({
+      endpoint: url,
+      apiVersion: '2023-06-01',
+      body,
     })
+    expect(recordRequest.mock.invocationCallOrder[0]).toBeLessThan(fetchMock.mock.invocationCallOrder[0] ?? 0)
   })
 
   it('forwards the abort signal', async () => {
@@ -186,6 +200,91 @@ describe('DeepSeekSearchProvider request mapping', () => {
 })
 
 describe('DeepSeekSearchProvider error handling', () => {
+  it('does not start credential resolution or dispatch for a pre-aborted call', async () => {
+    const resolveApiKey = vi.fn(async () => 'late-key')
+    const recordRequest = vi.fn()
+    const fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+    const controller = new AbortController()
+    controller.abort(new Error('caller stopped'))
+    await expect(new DeepSeekSearchProvider({
+      ...options,
+      apiKey: '',
+      resolveApiKey,
+      recordRequest,
+    }).search({ query: 'q' }, controller.signal))
+      .rejects.toThrow(expect.objectContaining({ code: 'WEB_ABORTED' }))
+    expect(resolveApiKey).not.toHaveBeenCalled()
+    expect(recordRequest).not.toHaveBeenCalled()
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('aborts while an uncooperative credential resolver remains pending', async () => {
+    const resolveApiKey = vi.fn(() => new Promise<string>(() => {}))
+    const recordRequest = vi.fn()
+    const fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+    const controller = new AbortController()
+    const search = new DeepSeekSearchProvider({
+      ...options,
+      apiKey: '',
+      resolveApiKey,
+      recordRequest,
+    }).search({ query: 'q' }, controller.signal)
+    controller.abort(new Error('deadline'))
+    await expect(search).rejects.toThrow(expect.objectContaining({ code: 'WEB_ABORTED' }))
+    expect(resolveApiKey).toHaveBeenCalledOnce()
+    expect(recordRequest).not.toHaveBeenCalled()
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('resolves credentials under an active cancellation signal', async () => {
+    const fetchMock = vi.fn(async () => jsonResponse(searchResponse()))
+    vi.stubGlobal('fetch', fetchMock)
+    const controller = new AbortController()
+    await expect(new DeepSeekSearchProvider({
+      ...options,
+      apiKey: '',
+      resolveApiKey: async () => 'resolved-key',
+    }).search({ query: 'q' }, controller.signal)).resolves.toMatchObject({ truncated: false })
+    const [, init] = fetchMock.mock.calls[0] as unknown as [string, RequestInit]
+    expect((init.headers as Record<string, string>)['x-api-key']).toBe('resolved-key')
+  })
+
+  it('maps a credential resolver rejection under an active signal to WEB_PROVIDER_ERROR', async () => {
+    const controller = new AbortController()
+    await expect(new DeepSeekSearchProvider({
+      ...options,
+      apiKey: '',
+      resolveApiKey: () => Promise.reject(new Error('credential backend failed')),
+    }).search({ query: 'q' }, controller.signal))
+      .rejects.toThrow(expect.objectContaining({
+        code: 'WEB_PROVIDER_ERROR',
+        message: 'DeepSeek search credential resolution failed: Error: credential backend failed',
+      }))
+  })
+
+  it('uses the default credential reference when no resolver is configured', async () => {
+    await expect(new DeepSeekSearchProvider({ ...options, apiKey: '' }).search({ query: 'q' }))
+      .rejects.toThrow('DeepSeek search has no API key for "DEEPSEEK_API_KEY"')
+  })
+
+  it('observes cancellation triggered synchronously by credential resolution', async () => {
+    const controller = new AbortController()
+    const fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+    await expect(new DeepSeekSearchProvider({
+      ...options,
+      apiKey: '',
+      resolveApiKey: () => {
+        controller.abort(new Error('resolver cancelled caller'))
+        return Promise.resolve('unused-key')
+      },
+    }).search({ query: 'q' }, controller.signal))
+      .rejects.toThrow(expect.objectContaining({ code: 'WEB_ABORTED' }))
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
   it('maps an HTTP error to WEB_PROVIDER_ERROR with the provider message', async () => {
     vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({ error: { message: 'rate limited' } }, { status: 429 })))
     await expect(new DeepSeekSearchProvider(options).search({ query: 'q' }))
@@ -216,6 +315,17 @@ describe('DeepSeekSearchProvider error handling', () => {
       .rejects.toThrow(expect.objectContaining({ code: 'WEB_ABORTED' }))
   })
 
+  it('maps a custom abort reason to WEB_ABORTED', async () => {
+    const controller = new AbortController()
+    vi.stubGlobal('fetch', vi.fn(async (_input: RequestInfo | URL, init?: RequestInit) =>
+      await new Promise<Response>((_resolve, reject) => {
+        init?.signal?.addEventListener('abort', () => { reject(new Error('custom abort reason')) }, { once: true })
+      })))
+    const search = new DeepSeekSearchProvider(options).search({ query: 'q' }, controller.signal)
+    controller.abort(new Error('timeout reason'))
+    await expect(search).rejects.toThrow(expect.objectContaining({ code: 'WEB_ABORTED' }))
+  })
+
   it('maps an unparseable success body to WEB_PROVIDER_ERROR', async () => {
     vi.stubGlobal('fetch', vi.fn(async () => new Response('not json', { status: 200 })))
     await expect(new DeepSeekSearchProvider(options).search({ query: 'q' }))
@@ -323,28 +433,66 @@ describe('web-search-deepseek plugin registration', () => {
       vi.stubGlobal('fetch', fetchMock)
       const ctx = new Context()
       await ctx.plugin(WebService, { searchProvider: DEEPSEEK_PROVIDER_ID })
-      const fiber = await ctx.plugin(deepseekPlugin, {})
+      deepseekPlugin.apply(ctx, {})
       await ctx.web.search({ query: 'q' })
       const [url, init] = fetchMock.mock.calls[0] as unknown as [string, RequestInit]
       expect(url).toBe('https://api.deepseek.com/anthropic/v1/messages')
       expect((init.headers as Record<string, string>)['x-api-key']).toBe('env-key')
       expect(JSON.parse(init.body as string)).toMatchObject({ model: 'deepseek-v4-flash' })
-      await fiber.dispose()
+      await ctx.fiber.dispose()
     } finally {
       if (prev === undefined) delete process.env.DEEPSEEK_API_KEY
       else process.env.DEEPSEEK_API_KEY = prev
     }
   })
 
-  it('is unavailable when neither config nor env supplies a key', async () => {
+  it('resolves the credential for each search so a stored or rotated key needs no restart', async () => {
+    const previous = process.env.DEEPSEEK_API_KEY
+    delete process.env.DEEPSEEK_API_KEY
+    const dir = await mkdtemp(join(tmpdir(), 'dsh-web-search-credentials-'))
+    const fetchMock = vi.fn(async (_input: RequestInfo | URL, _init?: RequestInit) => jsonResponse(searchResponse()))
+    vi.stubGlobal('fetch', fetchMock)
+    const ctx = new Context()
+    try {
+      await ctx.plugin(WebService, { searchProvider: DEEPSEEK_PROVIDER_ID })
+      await ctx.plugin(CredentialsLocal, { path: join(dir, '.env'), watch: false })
+      await ctx.plugin(deepseekPlugin, { baseURL: 'https://api.deepseek.test/anthropic/v1' })
+
+      await expect(ctx.web.search({ query: 'missing' }))
+        .rejects.toThrow(expect.objectContaining({ code: 'WEB_PROVIDER_CREDENTIAL_MISSING' }))
+
+      const ref = credentialRef('DEEPSEEK_API_KEY')
+      await ctx.credentials.set(ref, 'stored-key')
+      await ctx.web.search({ query: 'stored' })
+      await ctx.credentials.set(ref, 'rotated-key')
+      await ctx.web.search({ query: 'rotated' })
+
+      const headers = fetchMock.mock.calls.map(([, init]) => (init as RequestInit).headers as Record<string, string>)
+      expect(headers.map(value => value['x-api-key'])).toEqual(['stored-key', 'rotated-key'])
+    } finally {
+      await ctx.fiber.dispose()
+      await rm(dir, { recursive: true, force: true })
+      if (previous === undefined) delete process.env.DEEPSEEK_API_KEY
+      else process.env.DEEPSEEK_API_KEY = previous
+    }
+  })
+
+  it('reports an actionable credential error when neither config nor env supplies a key', async () => {
     const prev = process.env.DEEPSEEK_API_KEY
     delete process.env.DEEPSEEK_API_KEY
     try {
       const ctx = new Context()
       await ctx.plugin(WebService, { searchProvider: DEEPSEEK_PROVIDER_ID })
       await ctx.plugin(deepseekPlugin, {})
-      await expect(ctx.web.search({ query: 'q' }))
-        .rejects.toThrow(expect.objectContaining({ code: 'WEB_PROVIDER_CONFIGURED_UNAVAILABLE' }))
+      let caught: unknown
+      try {
+        await ctx.web.search({ query: 'q' })
+      } catch (error: unknown) {
+        caught = error
+      }
+      expect(caught).toMatchObject({ code: 'WEB_PROVIDER_CREDENTIAL_MISSING' })
+      if (!(caught instanceof Error)) throw new Error('search did not throw an Error')
+      expect(caught.message).toMatch(/store it through the credentials service.*Models page/s)
     } finally {
       if (prev !== undefined) process.env.DEEPSEEK_API_KEY = prev
     }

packages/web/web-search-deepseek/tsconfig.json

@@ -20,6 +20,15 @@
     {
       "path": "../web"
     },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../credentials/credentials"
+    },
     {
       "path": "../../support/invariants"
     }

pnpm-lock.yaml

@@ -411,6 +411,9 @@ importers:
       '@deepseek-ai/dsh-tool-todo':
         specifier: workspace:^
         version: link:../../packages/todo/tool-todo
+      '@deepseek-ai/dsh-tool-web':
+        specifier: workspace:^
+        version: link:../../packages/web/tool-web
       '@deepseek-ai/dsh-tool-workflow':
         specifier: workspace:^
         version: link:../../packages/workflow/tool-workflow
@@ -426,6 +429,12 @@ importers:
       '@deepseek-ai/dsh-user-interaction':
         specifier: workspace:^
         version: link:../../packages/ui/user-interaction
+      '@deepseek-ai/dsh-web':
+        specifier: workspace:^
+        version: link:../../packages/web/web
+      '@deepseek-ai/dsh-web-search-deepseek':
+        specifier: workspace:^
+        version: link:../../packages/web/web-search-deepseek
       '@deepseek-ai/dsh-workflow-workerthread':
         specifier: workspace:^
         version: link:../../packages/workflow/workflow-workerthread
@@ -5798,9 +5807,21 @@ importers:
         specifier: ^3.18.0
         version: 3.18.0
     devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-credentials':
+        specifier: workspace:^
+        version: link:../../credentials/credentials
+      '@deepseek-ai/dsh-credentials-local':
+        specifier: workspace:^
+        version: link:../../credentials/credentials-local
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
       '@deepseek-ai/dsh-web':
         specifier: workspace:^
         version: link:../web

tsconfig.host.json

@@ -29,6 +29,7 @@
     "apps/web/tests/code-mode-round.e2e.ts",
     "apps/web/tests/composer-draft-scroll.e2e.ts",
     "apps/web/tests/cordis-tool-round.e2e.ts",
+    "apps/web/tests/web-search-round.e2e.ts",
     "apps/web/tests/message-actions.e2e.ts",
     "apps/web/tests/queue-actions.e2e.ts",
     "apps/web/tests/skill-invocation-policy.e2e.ts",