dsh-web-tavily 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## 0.4.0 (2026-09-13)
+
+### Changed
+
+- **Renamed again, to `dsh-web-tavily`.** The 0.3.0 name `dsh-tavily-search`
+  turned out to be taken on npm as well (`ouones`, v0.1.2) — as are
+  `dsh-tavily-provider`, `dsh-search-tavily`, `dsh-tavily` and
+  `dsh-tavily-web-search`; `dsh-web-tavily` is the free one. The package name,
+  the manifest `id`, the bundle patch's row id and module name, the Cordis name,
+  the settings namespace and the log file all follow it. 0.3.0 was never
+  published, so nobody has to migrate twice.
+- **Settings section and log file are now `dsh-web-tavily`**: the section in
+  `~/.dsh/settings.yaml` is `dsh-web-tavily:` and the lifecycle log is
+  `~/.dsh-tui/dsh-web-tavily.log`.
+
+## 0.3.0 (2026-09-13)
+
+### Changed
+
+- **Renamed from `dsh-web-search-tavily` to `dsh-tavily-search`.** The npm name
+  `dsh-web-search-tavily` is taken by an unrelated package, so the package name,
+  the manifest `id`, the bundle patch's row id and module name, and the plugin's
+  Cordis name all moved to `dsh-tavily-search`. The provider id (`tavily`),
+  the registered fetch provider (`http-trusted`) and every seam contract are
+  unchanged, so a profile patch needs no edit.
+- **The settings namespace and the log file follow the package name**: the
+  section in `~/.dsh/settings.yaml` is now `dsh-tavily-search:` (rename the old
+  `web-search-tavily:` key to keep your values) and the lifecycle log is now
+  `~/.dsh-tui/dsh-tavily-search.log`.
+
+### Added
+
+- The `repository` field in `package.json` and `source.repository` in
+  `dsh-plugin.json`, both pointing at the public repository.
+
+## 0.2.0 (2026-09-13)
+
+### Added
+
+- **A localized settings card** (`lib/settings-card.js`). `settings.installSection`
+  registers the namespace and its schema, and the host can always render a generic
+  card from that — but a generic card shows raw field keys (`apiKeyEnv`,
+  `searchDepth`, …) with no translation. The card registered here is a
+  `tuiSettingsSections` section, the same shape every other plugin in this
+  ecosystem ships, with Chinese and English descriptions for the credential
+  reference, the API base URL, search depth, topic, the AI-answer switch and the
+  fallback result cap. `apiKey` is deliberately left out: a literal secret in a
+  settings document is the one thing this plugin tells users not to do.
+- The card registration tolerates the first tick: the seam refuses with
+  `requires a live Cordis activation context` while the activation is not live
+  yet, so the registration retries for ~12 s and logs the refusal once. Verified
+  against the headless probe: the card lands on the retry.
+
+## 0.1.1 (2026-09-13)
+
+### Added
+
+- **A lifecycle log** (`lib/diag.js` → `~/.dsh-tui/dsh-web-search-tavily.log`, the
+  host logger when there is one, 128 KiB cap, silent under `node --test`). The
+  plugin declares `inject = ["web"]`, so on a host without that seam `apply()`
+  stays parked — and with no logging at all it looked exactly like a plugin that
+  was never loaded. There is now an import-time breadcrumb, an `apply started`
+  line, the settings-namespace and provider-registration results, and an unload
+  line.
+- Both provider registrations are wrapped in a `try`/`catch` that logs, instead
+  of letting a refusing seam take the boot down.
+
+### Changed
+
+- Documentation: the README is split into an English `README.md` and a Chinese
+  `README.zh.md` with reciprocal links, the internal workspace path is gone from
+  the install steps, and the published `files` list now carries `README.zh.md`
+  and this changelog.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VviLliAm-qwq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# dsh-web-tavily
+
+**English** · [中文](README.zh.md)
+
+A host-plane Cordis plugin for dsh: it registers the **`tavily`** search provider
+on dsh's web seam (`ctx.web`), so the `web_search` tool goes to the **Tavily
+Search API** (`POST https://api.tavily.com/search`).
+
+- It does **not** replace the `web_search` tool itself: the tool, its system
+  prompt and its result card are untouched — only the search backend changes.
+- DeepSeek's native search (`web-search-deepseek`) stays available as a fallback
+  you can switch to; set `web.searchProvider` back to `deepseek-official` (or
+  delete the key) to do so.
+- The key is always resolved as a **reference** (default `TAVILY_API_KEY`): the
+  credentials service (`refs:` in `~/.dsh/.credentials.yaml`) first, then the
+  process environment, and only then a literal `apiKey` in the configuration. The
+  provider never stores a key.
+
+## How it works
+
+1. The provider (id `tavily`) registers on `ctx.web`; `web.searchProvider: tavily`
+   makes it the default choice.
+2. When `web_search` runs, the seam hands `{ query, maxResults }` to this provider.
+3. The provider resolves the key (a snapshot per operation, so one search never
+   mixes two configuration versions) and calls `{baseURL}/search`.
+4. The response is mapped: `results[] → sources[]` (`title` / `url` /
+   `content→snippet`, plus `published_date → publishedAt` when present), and a
+   top-level `answer` (Tavily's AI summary) becomes the tool's optional `content`.
+5. Cancellation (signal) → `WEB_ABORTED`; an HTTP failure or an unparsable body →
+   `WEB_PROVIDER_ERROR`; a missing key → `WEB_PROVIDER_CREDENTIAL_MISSING` (the
+   message names the configuration step).
+
+## Defaults
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `apiKeyEnv` | `TAVILY_API_KEY` | Credential reference (environment-variable name). |
+| `apiKey` | (none) | A literal key, only when you do not want a reference. |
+| `baseURL` | `https://api.tavily.com` | Overridable with `TAVILY_BASE_URL`. |
+| `searchDepth` | `basic` | `basic` / `advanced` (deeper, higher credit use). |
+| `topic` | `general` | `general` / `news`. |
+| `includeAnswer` | `true` | Ask for Tavily's AI summary (mapped to `content`). |
+| `maxResults` | `10` | Fallback cap; `web_search` passes 8 per call, Tavily's ceiling is 20. |
+
+## Install
+
+1. Copy the package into
+   `~/.dsh/profiles/dsh-tui/node_modules/dsh-web-tavily/`.
+2. Append `"dsh-web-tavily"` to `dsh.profile.bundles` in
+   `~/.dsh/profiles/dsh-tui/package.json`.
+3. **Make tavily the default search backend.** This has to be written in the
+   profile's user patch layer (the `web:` section of `settings.yaml` does not
+   affect service configuration) — edit
+   `~/.dsh/profiles/dsh-tui/cordis.patch.yml` and add:
+
+   ```yaml
+   - id: web
+     name: '@deepseek-ai/dsh-web'
+     config:
+       searchProvider: tavily
+       fetchProvider: http-trusted
+   ```
+
+   The `web` row belongs to the `dsh-base` layer, so **do not add a new row with
+   `insert:`** — the duplicate id crashes the boot with
+   `duplicate loader entry id: web`. Override the existing row by id instead, and
+   note that an override **replaces the whole config**, which is why
+   `fetchProvider` is restated above.
+4. Restart dsh-tui (`/restart`).
+
+## Configuration
+
+The plugin's own section lives in `~/.dsh/settings.yaml` (it also appears in the
+settings screen under “Web search Tavily”):
+
+```yaml
+dsh-web-tavily:
+  apiKeyEnv: TAVILY_API_KEY
+  searchDepth: basic
+  topic: general
+  includeAnswer: true
+  maxResults: 10
+```
+
+`TAVILY_BASE_URL` overrides the API origin; the credential reference defaults to
+`TAVILY_API_KEY`.
+
+The settings screen renders this namespace as a bilingual card (**Web search
+(Tavily)** / 联网搜索（Tavily）) with a description for every field, so the
+reference is the one control you normally touch. The key itself never enters the
+settings document.
+
+## Where the key lives (local only — never in a repository)
+
+Add it under `refs:` in `~/.dsh/.credentials.yaml` (that file holds machine-local
+credentials; do not commit or share it):
+
+```yaml
+refs:
+  TAVILY_API_KEY: 'tvly-...'
+```
+
+## Switching back to DeepSeek's native search
+
+Set `web.searchProvider` to `deepseek-official` (or delete the key and let the
+seam use the only provider available). The seam does **not** fall back
+automatically: a broken Tavily configuration fails loudly rather than quietly
+using DeepSeek.
+
+## Proxy-compatible fetch (`http-trusted`)
+
+The plugin also registers an `http-trusted` fetch provider, which works around
+`web_fetch` being refused by the official `http` provider's safety preflight in
+**fake-IP proxy environments** (Clash and friends resolving domains to
+`198.18.0.0/15`): `WEB_BLOCKED_URL: resolves to a non-public IP address`.
+
+- It **reuses the official `@deepseek-ai/dsh-web-fetch-http` transport** and
+  relaxes exactly one check — the “resolved address must be public” preflight
+  additionally allows `198.18.0.0/15`, the proxy fake-IP range. Everything else
+  is unchanged: private, loopback and reserved ranges are still refused
+  (`WEB_BLOCKED_URL`), IPv6 answers are still dropped, and address pinning,
+  same-origin redirects, the content-type allowlist, byte/character caps and the
+  no-credentials cookie rule all stay in place.
+- ⚠️ **Security boundary:** SSRF protection moves from “enforced inside the host”
+  to “trust the local proxy's DNS decision”, so the last word on reachability
+  belongs to the proxy's routing rules. **Intended for a single-user machine with
+  a trusted self-hosted proxy**; for shared or public deployments go back to the
+  official `http` provider (below).
+- Addresses that are special by construction (`http://192.168.x.x/` and friends)
+  are still refused.
+
+```yaml
+# the web row in ~/.dsh/profiles/dsh-tui/cordis.patch.yml
+config:
+  searchProvider: tavily
+  fetchProvider: http-trusted
+```
+
+**Rolling back to the official `http`:** set `fetchProvider` back to `http`. The
+cost is that `web_fetch` is refused again in a fake-IP proxy environment, in
+exchange for the complete safety preflight.
+
+## Troubleshooting
+
+- `duplicate loader entry id: web` on boot — the profile's `cordis.patch.yml`
+  used `insert:` for a row that already exists; rewrite it as the by-id override
+  shown above.
+- `web_search` answers `WEB_PROVIDER_CONFIGURED_MISSING` — the plugin did not
+  load: check the bundles list and the patch above.
+- `web_fetch` answers `WEB_BLOCKED_URL ... non-public IP` — the proxy fake-IP
+  preflight refused it: switch to `http-trusted`, or turn the proxy's fake-IP
+  mode off.
+
+## Limitations
+
+- A missing or invalid Tavily key makes `web_search` fail
+  (`WEB_PROVIDER_CREDENTIAL_MISSING` / `WEB_PROVIDER_ERROR`); the message names
+  what to configure.
+- `max_results` is clamped to Tavily's ceiling of 20.
+- An invalid `searchDepth` / `topic` is an error, never a silent fallback to the
+  default.
+
+## Publishing
+
+- **Repository**: <https://github.com/VviLliAm-qwq/dsh-web-tavily> (public)
+
+## Usage
+
+Once installed and configured, let the model call `web_search` as usual: the
+`sources` list it returns (and the optional summary) now comes from Tavily.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/README.zh.md

@@ -0,0 +1,121 @@
+# dsh-web-tavily
+
+**中文** · [English](README.md)
+
+dsh host 平面 cordis 插件：为 dsh 的 web 能力 seam（`ctx.web`）注册搜索提供商 **`tavily`**，让 `web_search` 工具默认走 **Tavily Search API**（`POST https://api.tavily.com/search`）。
+
+- 不替换 `web_search` 工具本身：工具、系统提示、展示卡片均保持原样，只有搜索后端换成 Tavily。
+- 保留 DeepSeek 原生搜索（`web-search-deepseek`）为可切换备选；想切回只需把 `web.searchProvider` 改为 `deepseek-official` 或删掉该键。
+- key 一律按**引用**解析（默认 `TAVILY_API_KEY`）：优先凭证服务（`~/.dsh/.credentials.yaml` 的 `refs:`），其次启动环境变量，最后才是配置里的字面 `apiKey`。provider 不保留 key。
+
+## 工作原理
+
+1. 注册 provider（id = `tavily`）到 `ctx.web`；`web.searchProvider: tavily` 使其成为默认选择。
+2. `web_search` 被调用时，seam 把 `{ query, maxResults }` 交给本 provider。
+3. provider 解析 key（每次操作时快照，一次搜索不会混用两个配置版本）→ 请求 `{baseURL}/search`。
+4. 响应映射：`results[] → sources[]`（`title` / `url` / `content→snippet`，若有 `published_date → publishedAt`），顶层 `answer`（Tavily 的 AI 总结）→ 工具的可选 `content` 摘要。
+5. 取消（信号）→ `WEB_ABORTED`；HTTP 失败 / 不可解析 → `WEB_PROVIDER_ERROR`；缺 key → `WEB_PROVIDER_CREDENTIAL_MISSING`（错误信息带配置指引）。
+
+## 默认配置
+
+| 字段 | 默认值 | 说明 |
+| --- | --- | --- |
+| `apiKeyEnv` | `TAVILY_API_KEY` | 凭证引用（环境变量名） |
+| `apiKey` | （无） | 字面 key，仅当不想走引用时使用 |
+| `baseURL` | `https://api.tavily.com` | 可用环境变量 `TAVILY_BASE_URL` 覆盖 |
+| `searchDepth` | `basic` | `basic` / `advanced`（advanced 更深度、额度消耗更高） |
+| `topic` | `general` | `general` / `news` |
+| `includeAnswer` | `true` | 是否请求 Tavily 的 AI 总结（映射为 `content`） |
+| `maxResults` | `10` | 兜底结果数上限（`web_search` 每次实际传 8，Tavily 上限 20） |
+
+## 安装
+
+1. 把整个包复制到
+   `~/.dsh/profiles/dsh-tui/node_modules/dsh-web-tavily/`。
+2. 在 `~/.dsh/profiles/dsh-tui/package.json` 的 `dsh.profile.bundles` 追加 `"dsh-web-tavily"`。
+3. **把 web 服务默认搜索改为 tavily**（必须写在 profile 用户补丁层，`settings.yaml` 的 `web:` 段对服务配置无效）——
+   编辑 `~/.dsh/profiles/dsh-tui/cordis.patch.yml` 追加：
+
+   ```yaml
+   - id: web
+     name: '@deepseek-ai/dsh-web'
+     config:
+       searchProvider: tavily
+       fetchProvider: http-trusted
+   ```
+
+   `web` 行由基座 dsh-base 提供，**不要用 `insert:` 新增同 id 行**——那会撞 id 直接崩
+   `duplicate loader entry id: web`；这里要按 id 覆盖既有行，且覆盖是**整行重写，需写全
+   `fetchProvider`**。
+4. 重启 dsh-tui（`/restart`）生效。
+
+## 配置
+
+插件自身的设置段放 `~/.dsh/settings.yaml`（设置页「Plugin configuration」里也会出现「Web search Tavily」类）：
+
+```yaml
+dsh-web-tavily:
+  apiKeyEnv: TAVILY_API_KEY
+  searchDepth: basic
+  topic: general
+  includeAnswer: true
+  maxResults: 10
+```
+
+可用环境变量覆盖：`TAVILY_BASE_URL`（API 源），凭证引用键默认 `TAVILY_API_KEY`。
+
+设置页把这个命名空间渲染成一张**中英双语卡片**（「联网搜索（Tavily）」/ Web search (Tavily)），每个字段都有说明；日常只需要改「凭证引用」那一项。密钥本身永远不进设置文档。
+
+## key 存放（本机，不进代码库）
+
+在 `~/.dsh/.credentials.yaml` 的 `refs:` 下添加（该文件属于本机凭证，不要提交/外发）：
+
+```yaml
+refs:
+  TAVILY_API_KEY: 'tvly-...'
+```
+
+## 切回 DeepSeek 原生搜索
+
+把 `web.searchProvider` 改为 `deepseek-official`（或删除该键、让 seam 用唯一可用 provider）。注意 seam 不支持自动回退：Tavily 配置失效时搜索会明确报错，而**不会**悄悄走 DeepSeek。
+
+## 代理兼容 fetch（`http-trusted`）
+
+本插件同时注册 `http-trusted` fetch provider，解决 **fake-IP 代理环境**（Clash 等把域名解析为 `198.18.0.0/15` 假地址）下 `web_fetch` 被官方 `http` provider 的安全预检拒绝的问题（`WEB_BLOCKED_URL: resolves to a non-public IP address`）。
+
+- **复用官方 `@deepseek-ai/dsh-web-fetch-http` 传输层**：仅放宽「解析结果必须是公网 IP」这一预检——额外放行 `198.18.0.0/15`（代理 fake-IP 段），**其余全部照旧**：内网/环回/保留段照常拒绝（`WEB_BLOCKED_URL`）、IPv6 答案一律丢弃、地址 pinning、同源重定向、内容类型白名单、字节/字符上限、无凭证 cookie 等防护原封未动。
+- ⚠️ **安全边界**：SSRF 防护从「宿主内强校验」退化为「信任本机代理的 DNS 决策」，网络的最终裁决权移交代理分流规则。**仅适用于单用户本机 + 自制可信代理**；多人共用/公网服务请回退官方 `http`（见下）。
+- IP 来源特殊（`http://192.168.x.x/` 之类）仍会被拒绝。
+
+```yaml
+# ~/.dsh/profiles/dsh-tui/cordis.patch.yml 的 web 行
+config:
+  searchProvider: tavily
+  fetchProvider: http-trusted
+```
+
+**回退官方 http**：把 `fetchProvider` 改回 `http`（代价：fake-IP 代理环境下 `web_fetch` 将再次被拒，但安全预检完整）。
+
+## 加载失败排查
+
+- 插件启动报 `duplicate loader entry id: web`：profile `cordis.patch.yml` 误用 `insert:` 新增同 id 行，按上文改写为直接行。
+- `web_search` 报 `WEB_PROVIDER_CONFIGURED_MISSING`：插件未加载（检查 bundles 列表与上述补丁）。
+- `web_fetch` 报 `WEB_BLOCKED_URL ... non-public IP`：代理假 IP 预检拒绝，改用 `http-trusted` 或关闭代理 fake-IP 模式。
+
+## 限制说明
+
+- Tavily key 缺失或失效 → `web_search` 报错（`WEB_PROVIDER_CREDENTIAL_MISSING` / `WEB_PROVIDER_ERROR`），按错误信息指引配置即可。
+- `max_results` 会被钳制到 Tavily 上限 20。
+- `searchDepth` / `topic` 非法值会直接报错，不会悄悄回退默认。
+
+## 发布
+
+- **仓库**：<https://github.com/VviLliAm-qwq/dsh-web-tavily>（公开）
+
+## 使用
+
+装好并配置 key 后，照常让模型调用 `web_search` 即可；工具返回的 `Sources:` 列表与可选总结即来自 Tavily。
+
+## 许可
+
+MIT — 见 [LICENSE](LICENSE)。

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# dsh-web-tavily bundle patch: mounts the Tavily search provider plugin.
+- insert:
+    - id: dsh-web-tavily
+      name: 'dsh-web-tavily'

package/dsh-plugin.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://dsh.community/schemas/dsh-plugin-0.15.json",
+  "manifestVersion": "0.15",
+  "id": "com.dsh-tui.dsh-web-tavily",
+  "name": "dsh-web-tavily",
+  "version": "0.4.0",
+  "facets": {
+    "host": {
+      "entry": "lib/index.js",
+      "apiVersion": "v1alpha1"
+    }
+  },
+  "requires": {
+    "contracts": [],
+    "services": []
+  },
+  "permissions": [],
+  "contributes": {
+    "commands": []
+  },
+  "subscriptions": [],
+  "license": "MIT",
+  "source": {
+    "repository": "https://github.com/VviLliAm-qwq/dsh-web-tavily"
+  }
+}

package/lib/diag.js

@@ -0,0 +1,60 @@
+/**
+ * Bounded lifecycle log for dsh-web-tavily.
+ *
+ * The plugin declares `inject = ["web"]`, so on a host that never mounts the web
+ * seam `apply()` stays parked — and a parked plugin is indistinguishable from
+ * one that was never loaded unless the module says something at import time.
+ * That is the whole reason this file exists.
+ *
+ * Same conventions as the other plugins in this ecosystem: one line per
+ * lifecycle event, the host logger when there is one, a plugin-owned file under
+ * `~/.dsh-tui/` capped at 128 KiB, and no file writes under `node --test`.
+ */
+
+import { appendFileSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** Plugin-owned log path. */
+export const DIAG_LOG = join(homedir(), '.dsh-tui', 'dsh-web-tavily.log');
+
+/** Above this size the file is trimmed to its newest half. */
+export const MAX_LOG_BYTES = 128 * 1024;
+
+/** Append one line, trimming the file when it has grown past the cap. */
+function appendLogLine(path, line) {
+    try {
+        if (statSync(path).size > MAX_LOG_BYTES) {
+            writeFileSync(path, readFileSync(path, 'utf8').slice(-Math.floor(MAX_LOG_BYTES / 2)));
+        }
+    }
+    catch {
+        // Missing or unreadable: the append below recreates it.
+    }
+    appendFileSync(path, line);
+}
+
+/**
+ * Write one lifecycle line.
+ *
+ * @param ctx - Cordis context when there is one (`ctx.logger` is used if the
+ *   host offers it); `undefined` at import time.
+ * @param message - the line, without timestamp or level.
+ * @param options.env - environment override (tests).
+ */
+export function diag(ctx, message, options = {}) {
+    try {
+        ctx?.logger?.info?.(`dsh-web-tavily: ${message}`);
+    }
+    catch {
+        // Observability only; never let logging break the plugin.
+    }
+    const env = options.env ?? process.env;
+    if (typeof env?.NODE_TEST_CONTEXT === 'string') return;
+    try {
+        appendLogLine(DIAG_LOG, `${new Date().toISOString()} info ${message}\n`);
+    }
+    catch {
+        // An unwritable log path is not worth surfacing.
+    }
+}

package/lib/index.js

@@ -0,0 +1,392 @@
+/**
+ * dsh-web-tavily: a Tavily-backed search provider for the dsh web
+ * capability seam (ctx.web). Registers the `tavily` provider so the
+ * model-facing web_search tool runs against the Tavily Search API
+ * (POST https://api.tavily.com/search). The provider holds no credential
+ * value: the key is resolved per operation through the credentials service
+ * (ref, default TAVILY_API_KEY), the launch environment, or a literal
+ * `apiKey` config, in that order.
+ *
+ * The bundle additionally registers `http-trusted`, a proxy-friendly HTTP(S)
+ * fetch provider: it reuses the official @deepseek-ai/dsh-web-fetch-http
+ * transport (same-origin redirects, content-type allowlist, byte caps,
+ * timeout, no credentials, address pinning) but relaxes the public-IP precheck
+ * to also admit the proxy fake-IP range 198.18.0.0/15 (Clash-style DNS), which
+ * the stock provider rejects as non-public and which breaks web_fetch under a
+ * fake-IP DNS proxy. IPv6 answers are dropped entirely (never trust a
+ * link-local/ULA answer for routing), and every other non-public IPv4
+ * destination — loopback, RFC1918, link-local, CGNAT, multicast, reserved —
+ * is still rejected with WEB_BLOCKED_URL.
+ *
+ * @module dsh-web-tavily
+ */
+import z from "@deepseek-ai/schemastery";
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
+import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
+import { WebError } from "@deepseek-ai/dsh-web";
+import { HttpFetchProvider } from "@deepseek-ai/dsh-web-fetch-http";
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { diag } from "./diag.js";
+import { applySettingsCard } from "./settings-card.js";
+import ipaddr from "ipaddr.js";
+
+// Import-time breadcrumb: the only evidence a host that never mounts `ctx.web`
+// can give that this file was read at all (see ./diag.js).
+try {
+    diag(undefined, `module imported pid=${process.pid} node=${process.version}`);
+}
+catch {
+    // Diagnostics must never be the reason a module fails to load.
+}
+
+//#region identity & defaults
+/** Cordis plugin name used by loader diagnostics. */
+const name = "dsh-web-tavily";
+/** The web seam this provider registers into. */
+const inject = ["web"];
+/** Stable id this provider registers under. */
+const TAVILY_PROVIDER_ID = "tavily";
+/** Default Tavily API origin; the `/search` path is appended per call. */
+const TAVILY_DEFAULT_BASE_URL = "https://api.tavily.com";
+/** Default environment variable naming the credential reference. */
+const DEFAULT_API_KEY_ENV = "TAVILY_API_KEY";
+/** Environment variable that overrides the API origin. */
+const BASE_URL_ENV = "TAVILY_BASE_URL";
+/** Settings namespace carrying this provider's endpoint and behavior options. */
+const SETTINGS_NAMESPACE = "dsh-web-tavily";
+/** Attribution header sent on every request. Bump with the package version. */
+const USER_AGENT = "dsh-web-tavily/0.4.0";
+/** Fallback result cap when the caller sends no maxResults. */
+const DEFAULT_MAX_RESULTS = 10;
+/** Tavily's documented per-request result cap. */
+const TAVILY_MAX_RESULTS_CAP = 20;
+/** Accepted search_depth values. */
+const SEARCH_DEPTHS = ["basic", "advanced"];
+/** Accepted topic values. */
+const TOPICS = ["general", "news"];
+/** Stable id this bundle's proxy-friendly fetch provider registers under. */
+const TRUSTED_FETCH_PROVIDER_ID = "http-trusted";
+/** Resource limits for the trusted fetch provider (mirror dsh-web-fetch-http defaults). */
+const TRUSTED_FETCH_LIMITS = {
+	maxResponseBytes: 5e6,
+	maxBodyChars: 1e5,
+	timeoutMs: 3e4,
+	maxRedirects: 5,
+	userAgent: USER_AGENT
+};
+//#endregion
+
+//#region config
+const Config = z.object({
+	apiKey: z.string().role("secret"),
+	apiKeyEnv: z.string().role("credential-ref").default(DEFAULT_API_KEY_ENV),
+	baseURL: z.string(),
+	searchDepth: z.string().default("basic"),
+	topic: z.string().default("general"),
+	includeAnswer: z.boolean().default(true),
+	maxResults: z.number().step(1).min(1).default(DEFAULT_MAX_RESULTS)
+});
+//#endregion
+
+//#region abort & error helpers
+/** True for a fetch/`AbortSignal` abort, surfaced as `WEB_ABORTED`. */
+function isAbortError(error) {
+	return error instanceof DOMException && error.name === "AbortError";
+}
+/** Build the provider's stable cancellation error while retaining the caller's reason. */
+function searchAborted(signal, fallback) {
+	return new WebError("Tavily search aborted", "WEB_ABORTED", { cause: signal?.aborted === true ? signal.reason : fallback });
+}
+/** Throw the provider's stable cancellation error when the caller already aborted. */
+function throwIfAborted(signal) {
+	if (signal?.aborted === true) throw searchAborted(signal);
+}
+/**
+ * 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(operation, signal) {
+	if (signal === undefined) return operation;
+	if (signal.aborted) return Promise.reject(searchAborted(signal));
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			reject(searchAborted(signal));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		operation.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(new Error(String(error).replace(/^Error: /u, ""), { cause: error }));
+		});
+	});
+}
+/** Race a non-cancellable OS lookup without letting it delay tool cancellation. */
+function raceWithSignal(promise, signal) {
+	const abortError = () => new Error("web fetch aborted during hostname resolution", { cause: signal.reason });
+	if (signal.aborted) return Promise.reject(abortError());
+	return new Promise((resolve, reject) => {
+		const abort = () => {
+			reject(abortError());
+		};
+		signal.addEventListener("abort", abort, { once: true });
+		promise.then(resolve, reject).finally(() => {
+			signal.removeEventListener("abort", abort);
+		});
+	});
+}
+/** Collapse newlines in a text field so a snippet never breaks the markdown list. */
+function flattenInline(text) {
+	return text.replace(/\s*\n+\s*/g, " ");
+}
+/** Extract a human message from a Tavily error body (several documented shapes). */
+function parseErrorDetail(parsed) {
+	if (typeof parsed === "string" && parsed.length > 0) return parsed;
+	if (parsed == null || typeof parsed !== "object") return undefined;
+	if (typeof parsed.error === "string" && parsed.error.length > 0) return parsed.error;
+	if (typeof parsed.error?.message === "string" && parsed.error.message.length > 0) return parsed.error.message;
+	if (typeof parsed.detail === "string" && parsed.detail.length > 0) return parsed.detail;
+	if (parsed.detail != null && typeof parsed.detail === "object" && typeof parsed.detail.error === "string" && parsed.detail.error.length > 0) return parsed.detail.error;
+	if (typeof parsed.message === "string" && parsed.message.length > 0) return parsed.message;
+	return undefined;
+}
+//#endregion
+
+//#region trusted fetch resolver
+/**
+ * Whether an IPv4 address is inside the proxy fake-IP range 198.18.0.0/15
+ * (RFC 2544 benchmarking block commonly used by Clash-style DNS proxies as
+ * fake answers). This is the ONLY non-public range the trusted fetcher admits.
+ */
+function isFakeIpRange(address) {
+	try {
+		const parsed = ipaddr.parse(address);
+		if (!(parsed instanceof ipaddr.IPv4)) return false;
+		const [a, b] = parsed.toByteArray();
+		return a === 198 && (b === 18 || b === 19);
+	} catch {
+		return false;
+	}
+}
+/** Whether an address is a globally reachable public unicast (mirrors dsh-web-fetch-http). */
+function isPublicUnicast(address) {
+	try {
+		const parsed = ipaddr.parse(address);
+		if (parsed instanceof ipaddr.IPv4) return parsed.range() === "unicast";
+		if (parsed.isIPv4MappedAddress()) return parsed.toIPv4Address().range() === "unicast";
+		return parsed.range() === "unicast";
+	} catch {
+		return false;
+	}
+}
+/** WHATWG URL retains brackets around IPv6 hostnames; IP parsers do not. */
+function stripIpv6Brackets(hostname) {
+	return hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+}
+/**
+ * Proxy-friendly destination resolution: accepts public IPv4 unicasts plus the
+ * fake-IP range 198.18.0.0/15, drops every IPv6 answer (a ULA/link-local answer
+ * is never trusted for routing), and rejects any other IPv4 answer set with
+ * `WEB_BLOCKED_URL`. The returned addresses are the only ones the transport may
+ * use (pinned connection, same as the official provider).
+ *
+ * @param hostname - URL hostname, including brackets when it is an IPv6 literal.
+ * @param signal - aborts the wait for system resolution.
+ * @returns the validated, non-empty address set.
+ */
+async function resolveProxyFriendly(hostname, signal) {
+	const unbracketed = stripIpv6Brackets(hostname);
+	const literalFamily = isIP(unbracketed);
+	const resolved = literalFamily === 0
+		? await raceWithSignal(lookup(unbracketed, { all: true, order: "verbatim" }), signal)
+		: [{ address: unbracketed, family: literalFamily }];
+	if (resolved.length === 0) throw new WebError(`hostname "${hostname}" resolved to no addresses`, "WEB_PROVIDER_ERROR");
+	const addresses = [];
+	for (const entry of resolved) {
+		if (entry.family !== 4 && entry.family !== 6 || isIP(entry.address) !== entry.family) continue;
+		if (entry.family === 6) continue;
+		if (!isPublicUnicast(entry.address) && !isFakeIpRange(entry.address)) {
+			throw new WebError(`URL hostname "${hostname}" resolves to a non-public IP address`, "WEB_BLOCKED_URL");
+		}
+		addresses.push({ address: entry.address, family: 4 });
+	}
+	if (addresses.length === 0) throw new WebError(`hostname "${hostname}" resolved to no usable addresses`, "WEB_PROVIDER_ERROR");
+	return addresses;
+}
+/**
+ * The proxy-friendly fetch provider: identical transport to
+ * @deepseek-ai/dsh-web-fetch-http with permissive destination resolution.
+ */
+class TrustedHttpFetchProvider extends HttpFetchProvider {
+	id = TRUSTED_FETCH_PROVIDER_ID;
+}
+//#endregion
+
+//#region provider
+/**
+ * The Tavily-backed search provider. HTTP redirects fail as `WEB_PROVIDER_ERROR`;
+ * failures after dispatch name the endpoint so the user can fix configuration.
+ */
+class TavilySearchProvider {
+	constructor(resolveOptions) {
+		this.resolveOptions = resolveOptions;
+	}
+	id = TAVILY_PROVIDER_ID;
+	/** True when a key can be resolved and the endpoint parses. */
+	available() {
+		const options = this.resolveOptions();
+		return ((options.apiKey?.length ?? 0) > 0 || options.resolveApiKey !== undefined) && URL.canParse(options.baseURL);
+	}
+	async search(request, signal) {
+		const options = this.resolveOptions();
+		const apiKey = await this.apiKey(options, signal);
+		throwIfAborted(signal);
+		assertEnum("searchDepth", options.searchDepth, SEARCH_DEPTHS);
+		assertEnum("topic", options.topic, TOPICS);
+		const endpoint = `${options.baseURL}/search`;
+		const requested = request.maxResults ?? options.maxResults;
+		const maxResults = Math.min(Number.isInteger(requested) && requested > 0 ? requested : options.maxResults, TAVILY_MAX_RESULTS_CAP);
+		const body = {
+			query: request.query,
+			max_results: maxResults,
+			search_depth: options.searchDepth,
+			topic: options.topic,
+			include_answer: options.includeAnswer
+		};
+		let response;
+		try {
+			response = await fetch(endpoint, {
+				method: "POST",
+				redirect: "error",
+				headers: {
+					authorization: `Bearer ${apiKey}`,
+					"content-type": "application/json",
+					accept: "application/json",
+					"user-agent": USER_AGENT
+				},
+				body: JSON.stringify(body),
+				...(signal !== undefined ? { signal } : {})
+			});
+		} catch (error) {
+			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+			throw new WebError(`Tavily search request failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+		if (!response.ok) {
+			let message = `Tavily API error (HTTP ${response.status})`;
+			try {
+				const detail = parseErrorDetail(await response.json());
+				if (detail !== undefined && detail.length > 0) message += `: ${detail}`;
+			} catch (error) {
+				if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+			}
+			throw new WebError(`${message}\n\nThe web search request used endpoint ${JSON.stringify(endpoint)}. Only the user should choose or change the endpoint (Settings > Plugins > Plugin configuration > Web search Tavily, or the ${BASE_URL_ENV} environment variable).`, "WEB_PROVIDER_ERROR");
+		}
+		try {
+			const data = await response.json();
+			const sources = (Array.isArray(data.results) ? data.results : [])
+				.filter((item) => item?.url != null && item.url.length > 0)
+				.map((item) => ({
+					url: item.url,
+					...(item.title != null && item.title.length > 0 ? { title: flattenInline(item.title) } : {}),
+					...(item.content != null && item.content.length > 0 ? { snippet: flattenInline(item.content) } : {}),
+					...(item.published_date != null && item.published_date.length > 0 ? { publishedAt: item.published_date } : {})
+				}));
+			return {
+				...(typeof data.answer === "string" && data.answer.length > 0 ? { content: data.answer } : {}),
+				sources,
+				truncated: false
+			};
+		} catch (error) {
+			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+			throw new WebError(error instanceof WebError ? error.message : `Tavily returned an unprocessable response body: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+	}
+	/**
+	 * Resolve one operation's credential without retaining it on the provider.
+	 * @param options - the caller's snapshot, so the key and the endpoint it is sent to come from one section.
+	 * @param signal - abort signal for the surrounding search.
+	 * @returns the resolved key.
+	 */
+	async apiKey(options, signal) {
+		throwIfAborted(signal);
+		if (options.apiKey !== undefined && options.apiKey.length > 0) return options.apiKey;
+		let resolved;
+		try {
+			resolved = await abortable(options.resolveApiKey?.() ?? Promise.resolve(undefined), signal);
+		} catch (error) {
+			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+			throw new WebError(`Tavily search credential resolution failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+		if (resolved !== undefined && resolved.length > 0) return resolved;
+		throw new WebError(`Tavily search has no API key for "${options.apiKeyEnv ?? DEFAULT_API_KEY_ENV}"; store it through the credentials service (refs: TAVILY_API_KEY in ~/.dsh/.credentials.yaml), export it in the launching environment, or set a literal "apiKey" in the dsh-web-tavily config`, "WEB_PROVIDER_CREDENTIAL_MISSING");
+	}
+}
+/** Reject a config value outside the provider's accepted set with a friendly message. */
+function assertEnum(field, value, accepted) {
+	if (!accepted.includes(value)) throw new WebError(`Tavily search config "${field}" must be one of ${accepted.map((item) => JSON.stringify(item)).join(", ")} (got ${JSON.stringify(value)})`, "WEB_PROVIDER_ERROR");
+}
+//#endregion
+
+//#region registration
+/**
+ * Project one resolved section into the options the provider serves its next
+ * search with. Environment fallbacks stay here rather than in the provider:
+ * every value it reads is already fully defaulted.
+ */
+function resolveOptions(ctx, config) {
+	const apiKeyEnv = credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV);
+	const literalApiKey = config.apiKey !== undefined && config.apiKey.length > 0 ? config.apiKey : undefined;
+	return {
+		...(literalApiKey === undefined ? {} : { apiKey: literalApiKey }),
+		resolveApiKey: async () => {
+			const credentials = ctx.get("credentials");
+			if (credentials !== undefined) return (await credentials.resolve(apiKeyEnv))?.value;
+			const ambient = launchEnvironmentOf(ctx).get(apiKeyEnv);
+			return ambient !== undefined && ambient.value.length > 0 ? ambient.value : undefined;
+		},
+		apiKeyEnv,
+		baseURL: config.baseURL ?? launchEnvironmentOf(ctx).get(BASE_URL_ENV)?.value ?? TAVILY_DEFAULT_BASE_URL,
+		searchDepth: config.searchDepth ?? "basic",
+		topic: config.topic ?? "general",
+		includeAnswer: config.includeAnswer ?? true,
+		maxResults: config.maxResults ?? DEFAULT_MAX_RESULTS
+	};
+}
+/** Register the Tavily search provider and the proxy-friendly fetch provider. */
+function apply(ctx, config) {
+	diag(ctx, `apply started pid=${process.pid} file=${import.meta.url}`);
+	// The localized card lives on the optional TUI seam (see ./settings-card.js);
+	// the namespace/schema registration above stays authoritative for storage.
+	applySettingsCard(ctx, diag);
+	let current = () => config;
+	ctx.inject(["settings"], (settingsCtx) => {
+		settingsCtx.settings.installSection(ctx, SETTINGS_NAMESPACE, Config, config, {
+			setSource: (source) => {
+				current = source;
+			},
+			onChange: () => {}
+		});
+		diag(ctx, "settings namespace registered");
+	});
+	// The web seam is the one thing this plugin cannot work without. It is
+	// injected (see `inject`), but a host that answers with a shadow instance or
+	// refuses the registration must degrade to a logged warning instead of taking
+	// the boot down.
+	try {
+		ctx.web.registerSearchProvider(new TavilySearchProvider(() => resolveOptions(ctx, current())));
+		ctx.web.registerFetchProvider(new TrustedHttpFetchProvider(TRUSTED_FETCH_LIMITS, resolveProxyFriendly));
+		diag(ctx, `providers registered search=${TAVILY_PROVIDER_ID} fetch=${TRUSTED_FETCH_PROVIDER_ID}`);
+	}
+	catch (error) {
+		diag(ctx, `provider registration failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	ctx.effect(() => () => {
+		diag(ctx, "unloaded");
+	});
+}
+//#endregion
+
+export { Config, DEFAULT_API_KEY_ENV, SETTINGS_NAMESPACE, TAVILY_DEFAULT_BASE_URL, TAVILY_PROVIDER_ID, TRUSTED_FETCH_LIMITS, TRUSTED_FETCH_PROVIDER_ID, TavilySearchProvider, TrustedHttpFetchProvider, apply, inject, isFakeIpRange, name, resolveProxyFriendly };

package/lib/settings-card.js

@@ -0,0 +1,175 @@
+/**
+ * The localized settings card for dsh-web-tavily.
+ *
+ * The harness-side `settings.installSection` registers the namespace and its
+ * schema, and the host can always render a generic card from that schema — but a
+ * generic card shows raw field keys (`apiKeyEnv`, `searchDepth`, …) with no
+ * translation. A localized card is a `tuiSettingsSections` registration, the
+ * same shape every other plugin in this ecosystem ships, and a plugin may
+ * (and normally does) register both.
+ *
+ * The seam is optional and may still be activating on the first tick, so the
+ * registration is probed and retried instead of being attempted once.
+ */
+
+/** Section namespace; the same one `installSection` registers. */
+const NS = 'dsh-web-tavily';
+
+/** How often the optional seam is re-probed while it has not appeared yet. */
+const RETRY_MS = 400;
+
+/** Give up after this many attempts (~12 s) and stay silent. */
+const RETRY_LIMIT = 30;
+
+/**
+ * The card.
+ *
+ * `apiKey` is deliberately absent: a literal secret in a settings document is
+ * the one thing this plugin tells users not to do — the key belongs in the
+ * credentials store under the reference named below.
+ */
+export const SETTINGS_SECTION = Object.freeze({
+    ns: NS,
+    title: 'Web search (Tavily)',
+    descriptions: { zh: '联网搜索（Tavily）', en: 'Web search (Tavily)' },
+    fields: [
+        {
+            path: ['apiKeyEnv'],
+            label: 'Credential reference',
+            descriptions: { zh: '凭证引用', en: 'Credential reference' },
+            hint: 'Environment-variable-style reference for the Tavily key: the credentials service first, then the launch environment.',
+            hintDescriptions: {
+                zh: 'Tavily 密钥的引用名（环境变量形式）：先查凭证服务，再查启动环境。',
+                en: 'Environment-variable-style reference for the Tavily key: the credentials service first, then the launch environment.',
+            },
+            kind: 'text',
+        },
+        {
+            path: ['baseURL'],
+            label: 'API base URL',
+            descriptions: { zh: 'API 地址', en: 'API base URL' },
+            hint: 'Tavily API origin; the TAVILY_BASE_URL environment variable overrides it.',
+            hintDescriptions: {
+                zh: 'Tavily API 源地址；环境变量 TAVILY_BASE_URL 可覆盖。',
+                en: 'Tavily API origin; the TAVILY_BASE_URL environment variable overrides it.',
+            },
+            kind: 'text',
+        },
+        {
+            path: ['searchDepth'],
+            label: 'Search depth',
+            descriptions: { zh: '检索深度', en: 'Search depth' },
+            hint: '“advanced” searches further and consumes more credits.',
+            hintDescriptions: {
+                zh: '「advanced」检索更深入，也消耗更多额度。',
+                en: '“advanced” searches further and consumes more credits.',
+            },
+            kind: 'select',
+            options: [
+                { value: 'basic', label: 'basic', descriptions: { zh: '基础', en: 'basic' } },
+                { value: 'advanced', label: 'advanced', descriptions: { zh: '深入', en: 'advanced' } },
+            ],
+        },
+        {
+            path: ['topic'],
+            label: 'Topic',
+            descriptions: { zh: '检索主题', en: 'Topic' },
+            hint: '“news” biases the index towards recent coverage.',
+            hintDescriptions: {
+                zh: '「news」偏向最近的新闻报道。',
+                en: '“news” biases the index towards recent coverage.',
+            },
+            kind: 'select',
+            options: [
+                { value: 'general', label: 'general', descriptions: { zh: '通用', en: 'general' } },
+                { value: 'news', label: 'news', descriptions: { zh: '新闻', en: 'news' } },
+            ],
+        },
+        {
+            path: ['includeAnswer'],
+            label: 'Include AI answer',
+            descriptions: { zh: '附带 AI 总结', en: 'Include AI answer' },
+            hint: 'Ask Tavily for its short AI summary and pass it to the tool as optional content.',
+            hintDescriptions: {
+                zh: '请求 Tavily 的简短 AI 总结，作为工具的可选内容返回。',
+                en: 'Ask Tavily for its short AI summary and pass it to the tool as optional content.',
+            },
+            kind: 'boolean',
+        },
+        {
+            path: ['maxResults'],
+            label: 'Fallback result cap',
+            descriptions: { zh: '兜底结果上限', en: 'Fallback result cap' },
+            hint: 'Used when a call passes no limit; Tavily itself caps at 20.',
+            hintDescriptions: {
+                zh: '调用未指定数量时使用；Tavily 自身上限为 20。',
+                en: 'Used when a call passes no limit; Tavily itself caps at 20.',
+            },
+            kind: 'number',
+        },
+    ],
+});
+
+/**
+ * Register the card through the optional TUI seam.
+ *
+ * @param ctx - Cordis context.
+ * @param diag - lifecycle logger from `./diag.js`.
+ */
+export function applySettingsCard(ctx, diag) {
+    let attempts = 0;
+    let refusalLogged = false;
+    /** Consecutive refusals before the card is considered unavailable. */
+    let refusals = 0;
+    const tryOnce = () => {
+        let sections;
+        try {
+            sections = ctx.get('tuiSettingsSections', false);
+        }
+        catch {
+            sections = undefined;
+        }
+        if (sections !== undefined && sections !== null && typeof sections.register === 'function') {
+            try {
+                const dispose = sections.register(SETTINGS_SECTION);
+                diag(ctx, 'settings section registered');
+                ctx.effect(() => () => {
+                    try {
+                        if (typeof dispose === 'function') dispose();
+                    }
+                    catch {
+                        // Best-effort teardown.
+                    }
+                });
+                return;
+            }
+            catch (error) {
+                // THE FIRST REFUSAL IS NOT A VERDICT. The activation context is
+                // not live during the first tick, so `register` answers with
+                // "requires a live Cordis activation context" and starts working
+                // a few ticks later — the same behaviour every plugin in this
+                // ecosystem has to tolerate. Log once, keep trying, and only give
+                // up after a long run of refusals.
+                refusals += 1;
+                if (!refusalLogged) {
+                    refusalLogged = true;
+                    diag(ctx, `settings section refused (will retry): ${error instanceof Error ? error.message : String(error)}`);
+                }
+                if (refusals > RETRY_LIMIT) {
+                    diag(ctx, `settings section unavailable after ${refusals} refusals; the namespace card stays generic`);
+                    return;
+                }
+            }
+        }
+        attempts += 1;
+        if (attempts > RETRY_LIMIT) return;
+        const timer = setTimeout(tryOnce, RETRY_MS);
+        if (typeof timer.unref === 'function') timer.unref();
+    };
+    try {
+        tryOnce();
+    }
+    catch (error) {
+        diag(ctx, `settings card setup failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "dsh-web-tavily",
+  "version": "0.4.0",
+  "description": "Tavily-backed search provider for dsh: registers the `tavily` provider on ctx.web so the web_search tool runs against the Tavily Search API",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VviLliAm-qwq/dsh-web-tavily.git"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "files": [
+    "lib",
+    "dsh-plugin.json",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": "^22.19 || >=24"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/schemastery": "^3.18.2",
+    "@deepseek-ai/dsh-web": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-web-fetch-http": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-credentials": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.1.2-rc.1"
+  }
+}