web_search tool: single-backend dependency fails silent (HTTP 401) with no typed degradation event

[AronSwan]

(Issues are disabled on this repo — posting here per the discussion channel. Happy to move it wherever the maintainers prefer.)

Environment

• dsh v0.2.0-rc.2 (official build), Windows
• Used as model runtime under an external orchestrator (multi-agent research tasks)

What happened (measured, not speculated)

During a fully-instrumented research run (2026-10-06, 17 fetch attempts by the agent), every web_search invocation returned HTTP 401 on the configured Messages API endpoint — the entire search channel went down at once. Root cause on our side: no ARK credential configured (ARK_API_KEY never set). Two observations that we believe are product gaps rather than our misconfiguration:

1. No typed degradation event. The failure was only observable because the model itself reported it in prose. The runtime emitted no structured "search unavailable" event that a host/orchestrator could consume — downstream tooling cannot distinguish "search down" from "agent chose not to search".

2. No key-presence check / actionable error. A missing credential surfaces as a bare 401 mid-run instead of a startup-time "web_search requires ARK_API_KEY" warning. Our agent silently degraded to direct URL fetching + marking claims as unverified (14 claims in that run) — correct agent behavior, but avoidable damage.

Impact

• Single-backend dependency: web_search works only via the ARK plugin; no fallback, no fail-fast.
• Across 5 production runs we cannot programmatically tell whether search was available in any of them.

Suggestions (directions, not prescriptions)

• Emit a typed search_backend_degraded event when the search tool errors N times.
• Preflight credential presence at session start; fail with a clear message.
• Document the credential requirement explicitly (we found it only via rc.1 release notes).

Happy to share run journals/CLI failure logs. The runtime itself is excellent — the turn journal + receipt/lineage model has given us five fully auditable runs.

[PerryLink]

那个 401 其实有机器可读的码——缺的不是"失败分类"，而是"降级事件"

1. 搜索失败是有码的

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

• :49：apiKeyEnv 默认 DEEPSEEK_API_KEY，"值缺失时调用以 WEB_PROVIDER_CREDENTIAL_MISSING 失败"；
• :68：失败会抛出带机器可路由码的 WebError——缺凭据是 WEB_PROVIDER_CREDENTIAL_MISSING、调用方取消是 WEB_ABORTED、provider/传输失败（含没有 web_search_tool_result 块）是 WEB_PROVIDER_ERROR；
• :157：可用性检查是同步的，查不到异步凭据库 ⇒ "已选中的无凭据 provider"会在调用时以该码失败。

⇒ 所以"静默失败、没有类型化降级事件"这个判断要分两半：码是有的（WEB_PROVIDER_CREDENTIAL_MISSING 等三种），缺的是把它作为"降级事件"上报/呈现。这个区分很重要——它把诉求从"请加错误码"改成"请把已有的码变成可观测的降级"，后者是维护者能直接做的。

2. 建议的诉求写法

搜索后端不可用时，应以类型化的降级事件（携带 WEB_PROVIDER_CREDENTIAL_MISSING / WEB_PROVIDER_ERROR 等码）上报，使外层编排器（如多智能体运行器）能区分"搜索能力缺失"与"这一轮没有结果"，而不是只看到一次 401。

你在外部编排器下使用这一点值得写进正文——这正是"码存在但不可观测"造成代价的场景。

3. 请补一样

那条 401 的原始文本与它出现的层（是 web_search 工具结果里的文本，还是编排器抓到的 HTTP 层？）。§1 里 :68 说明失败信息会指名解析到的搜索端点并给出配置路径——若你看到的只是裸 401，那说明该文本在某处被截断或未透出，那就是更具体的一条缺陷。

4. 版本提醒（本轮基线）

HEAD = origin/master = 5badb15009 = dsh-v0.2.1-alpha.1
npm: alpha = 0.2.1-alpha.1    next = 0.2.0-rc.2    latest = 0.2.0-rc.2

你在 0.2.0-rc.2 上 ⇒ 属当前发布线。⚠️ 注意 latest 不再是旧的 0.1.5-rc.3。

一条边界

我确认的是该包文档里三种码的存在与"同步可用性检查查不到异步凭据库"这一机制（它解释了为何是调用时失败）。你那次 401 的实际来源以你补的原文为准——我没有跑你的编排器。

[AronSwan]

补上你要的原文与层位——先认两处修正，再说收窄后的诉求。

层位

不在编排器 HTTP 层（编排器从不发起搜索调用）。401 出现在 web_search 工具结果里，同一记录带结构化错误字段。来源：session journal（逐 turn，session.v4.jsonl.zstd）原始记录。

工具结果文本（逐字）：

Error: DeepSeek API error (HTTP 401): Authentication Fails, Your api key: ****kGs6 is invalid (request_id: c2188eb6-32a4-49ac-a0fa-0b748bb40677)

The web search request used endpoint "https://api.deepseek.com/anthropic/v1/messages". Search endpoint configuration is separate from chat. If that endpoint is not intended, guide the user to Settings > Plugins > Plugin configuration > Web search, where they can change and save Endpoint. If that settings page is unavailable, the user can set DEEPSEEK_SEARCH_BASE_URL or configure web-search-deepseek.baseURL to a trusted Anthropic-compatible Messages API base. Only the user should choose or change the endpoint.

同记录的结构化面：

"isError":true, "error":{"name":"WebError","code":"WEB_PROVIDER_ERROR"}

两处修正（对原帖）

1. "bare 401" 不成立。错误文本带端点名+配置指引，结构化 WebError.code 也在 journal 里——比 README :68 的文档承诺还多走了一步。你的分半判断（码有、缺的是降级事件呈现）成立。
2. 归因不准：失败的是 web-search-deepseek 插件（endpoint=api.deepseek.com/anthropic/v1/messages，key ****kGs6 无效），不是原帖写的 ARK 插件。根因仍在我方（搜索凭据无效），但插件归因以此帖为准。

计数

按 HTTP 401 签名数 tool/result 记录（五场生产运行，2026-10-06..10-07，dsh 0.2.0-rc.2）：11 / 6 / 25 / 2 / 3，共 47 次——五场全中。

存活下来的诉求（收窄为"把已有的码变成可观测的降级"）

1. host 侧实时信号缺位：这些结构化错误只住在逐 session 的 zstd journal 里，host 进程没有任何实时事件。我们是在事后解压 journal 才数出 47 次的。Ask：同 session 内 web_search 连续 N 次错误时，向 host 可见面（drain/CLI）发一条聚合的类型化降级事件——让外层编排器能区分"搜索能力不可用"与"本轮没有结果"。
2. 细分：无效 key 与 provider 故障同码（WEB_PROVIDER_ERROR；CREDENTIAL_MISSING 只覆盖"值缺失"，实测 0 次）。若结构化面能带上 HTTP 状态或分出 auth 类，host 侧可区分"该改配置"与"该等恢复"。

版本确认 0.2.0-rc.2（同你的基线注）。编排器场景=外部多智能体运行器（loopx 族），这条正是"码存在但 host 不可观测"造成代价的场景，已按你的建议写明。

[AronSwan]

跟进:根因在我方侧已定位——DeepSeek 账户欠费(我们今日内部确认;账面状态不在编排器可见面内,此前只能从 401 反推)。

值得记录的是:欠费在该端点呈现为与 key 写错完全相同的 Authentication Fails ... api key is invalid 401 签名。这正好补强上面的细分诉求——host 侧若能拿到 auth 类与 HTTP 状态的区分,就能把"改配置"(换 key/换端点)与"去充值/等服务恢复"两类处置分开。我们的 47 次计数里,若当时有该区分,第一次失败即可定性。