dsh-web-tavily 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project are documented in this file.
 
+## 0.4.2 (2026-09-16)
+
+### Fixed
+
+- **`ipaddr.js` is a declared dependency now.** `lib/index.js` imported it while `package.json` declared no `dependencies` at all, so the import resolved only because the dsh installation closure happens to hoist it (it is a dependency of `@deepseek-ai/dsh-web-fetch-http`). It is a module-scope import, so a closure without it would have failed the plugin tree. Declared as `^2.5.0`.
+- **`USER_AGENT` can no longer drift from the package version.** It was the literal `dsh-web-tavily/0.4.0` while the package shipped 0.4.1. It is now read from `package.json` at load time (through `createRequire(import.meta.url)`), with a graceful fallback to the bare plugin name when the manifest is unreadable — loading still never fails because of it.
+- **`diag()` creates the log directory.** `~/.dsh-tui/dsh-web-tavily.log` was appended to without creating `~/.dsh-tui/`, so on a fresh machine every line was swallowed by the outer catch. The write path now creates the parent directory first; the "never throws" contract is unchanged.
+- **Peer ranges widened to `^0.1.2-rc.1 || ^0.1.5-rc.1`.** `^0.1.2-rc.1` cannot match `0.1.5-rc.1`: semver lets a prerelease satisfy a range only when a comparator shares its `[major, minor, patch]` tuple, so every `0.1.x-rc.n` after `0.1.2` fell outside it. Today that is a warning rather than a failure (the profile template pins `autoInstallPeers: false`), but it would become an install error under strict peer enforcement. A future engine prerelease line needs its own clause.
+
+### Documentation
+
+- **The install steps now warn that saving `cordis.patch.yml` hot-reloads the running session.** A custom profile defaults to `patchReload: live`, so the edit takes effect immediately — not at the restart the README previously implied. If the `dsh-web-tavily` row has not been loaded yet, the `web` row points at a provider that is not registered and the session's web capability fails with `WEB_PROVIDER_CONFIGURED_MISSING` until the next restart. The safe order (install → `/restart` → edit the patch) is now spelled out.
+- **Getting a Tavily API key is step 1**, with where the key goes (`~/.dsh/.credentials.yaml` under `refs:`, or the launching environment's `TAVILY_API_KEY`) and an explicit note not to commit it.
+- The documented key-resolution order is corrected to match the code: literal `config.apiKey` first, then the credentials service, then the launching environment. The module header comment carried the same wrong order and is fixed too.
+
 ## 0.4.1 (2026-09-13)
 
 - Documentation only, no code change. Installation now goes through `dsh plugin --profile dsh-tui add dsh-web-tavily` (the package is published) instead of copying files into `node_modules`, both READMEs gain a CI badge, and the release section records the OIDC trusted-publishing path.

package/README.md

@@ -4,6 +4,8 @@
 
 **English** · [中文](README.zh.md)
 
+Built for [dsh-TUI](https://github.com/ccch1mneyyy/dsh-TUI).
+
 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`).
@@ -13,10 +15,10 @@ Search API** (`POST https://api.tavily.com/search`).
 - 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.
+- The key is resolved per operation in this order: a literal `apiKey` in the
+  configuration first, then the credentials service (`refs:` in
+  `~/.dsh/.credentials.yaml`), then the launch environment. The reference
+  defaults to `TAVILY_API_KEY`, and the provider never stores a key.
 
 ## How it works
 
@@ -46,7 +48,14 @@ Search API** (`POST https://api.tavily.com/search`).
 
 ## Install
 
-1. Install it into your profile — it is published on npm as `dsh-web-tavily`:
+1. **Get a Tavily account and an API key.** Register at <https://tavily.com/>,
+   create a key in the dashboard, and store it under `refs:` in
+   `~/.dsh/.credentials.yaml` — or export `TAVILY_API_KEY` in the environment
+   that launches dsh (see
+   [Where the key lives](#where-the-key-lives-local-only--never-in-a-repository)).
+   Never commit the key to a repository or paste it into a settings document.
+
+2. Install it into your profile — it is published on npm as `dsh-web-tavily`:
 
    ```sh
    dsh plugin --profile dsh-tui add dsh-web-tavily
@@ -54,7 +63,12 @@ Search API** (`POST https://api.tavily.com/search`).
    # dsh plugin --profile dsh-tui add file:<path to this package>
    ```
 
-2. **Make tavily the default search backend.** This has to be written in the
+3. **Restart dsh-tui before editing the patch** (`/restart`). Adding a plugin
+   only rewrites the profile's bundle list; it does **not** load the plugin into
+   the running session. Restarting here means the `tavily` provider is already
+   registered when the patch below is saved.
+
+4. **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:
@@ -67,12 +81,21 @@ Search API** (`POST https://api.tavily.com/search`).
        fetchProvider: http-trusted
    ```
 
+   ⚠️ **Saving this file hot-reloads the running session — it is not
+   "restart to apply".** The profile's patch layer is watched, so the session is
+   reconfigured the instant the file is written. If the plugin is not loaded yet
+   (step 3 skipped), the `web` row immediately points at a provider that is not
+   registered, and `web_search` / web fetch fail in that session with
+   `WEB_PROVIDER_CONFIGURED_MISSING`. **A `/restart` recovers it**, because at
+   boot the plugin is registered and the patched row is read together. Editing
+   the patch first and restarting later is also safe for the boot — it just
+   leaves this session's web capability unavailable until that restart.
+
    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.
-3. Restart dsh-tui (`/restart`).
 
 ## Configuration
 
@@ -106,6 +129,11 @@ refs:
   TAVILY_API_KEY: 'tvly-...'
 ```
 
+Exporting `TAVILY_API_KEY` in the environment that launches dsh works too — the
+credentials store is consulted first, the launch environment second. A literal
+key in `dsh-web-tavily.apiKey` is accepted as well and wins over both, but it
+puts the secret in a settings document, so treat it as a last resort.
+
 ## Switching back to DeepSeek's native search
 
 Set `web.searchProvider` to `deepseek-official` (or delete the key and let the
@@ -151,8 +179,10 @@ exchange for the complete safety preflight.
 - `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_search` answers `WEB_PROVIDER_CONFIGURED_MISSING` — the `web` row points
+  at a provider that is not registered: either the plugin did not load (check the
+  bundles list), or `cordis.patch.yml` was saved before the plugin was loaded,
+  which is a live reload (see [Install](#install)). `/restart` recovers it.
 - `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.

package/README.zh.md

@@ -4,11 +4,15 @@
 
 **中文** · [English](README.md)
 
+为 [dsh-TUI](https://github.com/ccch1mneyyy/dsh-TUI) 构建。
+
 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。
+- key 按以下顺序解析：配置里的字面 `apiKey` 最优先，其次凭证服务
+  （`~/.dsh/.credentials.yaml` 的 `refs:`，引用名默认 `TAVILY_API_KEY`），最后是启动
+  环境变量。provider 不保留 key。
 
 ## 工作原理
 
@@ -32,7 +36,12 @@ dsh host 平面 cordis 插件：为 dsh 的 web 能力 seam（`ctx.web`）注册
 
 ## 安装
 
-1. 装进 profile —— 它以 `dsh-web-tavily` 发布在 npm 上：
+1. **先注册 Tavily 账号并创建 API key。** 到 <https://tavily.com/> 注册，在控制台创建
+   key，然后放进 `~/.dsh/.credentials.yaml` 的 `refs:` 下，或在启动 dsh 的环境里导出
+   `TAVILY_API_KEY`（详见下文「key 存放」）。**不要把 key 提交进仓库，也不要写进设置
+   文档。**
+
+2. 装进 profile —— 它以 `dsh-web-tavily` 发布在 npm 上：
 
    ```sh
    dsh plugin --profile dsh-tui add dsh-web-tavily
@@ -40,7 +49,11 @@ dsh host 平面 cordis 插件：为 dsh 的 web 能力 seam（`ctx.web`）注册
    # dsh plugin --profile dsh-tui add file:<本包路径>
    ```
 
-2. **把 web 服务默认搜索改为 tavily**（必须写在 profile 用户补丁层，`settings.yaml` 的 `web:` 段对服务配置无效）——
+3. **先 `/restart` 重启一次**，让插件行载入。`dsh plugin add` 只改写 profile 的 bundles
+   清单，**不会**把插件加载进运行中的会话；先重启，下一步保存补丁时 `tavily` provider
+   才已经注册好。
+
+4. **把 web 服务默认搜索改为 tavily**（必须写在 profile 用户补丁层，`settings.yaml` 的 `web:` 段对服务配置无效）——
    编辑 `~/.dsh/profiles/dsh-tui/cordis.patch.yml` 追加：
 
    ```yaml
@@ -51,10 +64,15 @@ dsh host 平面 cordis 插件：为 dsh 的 web 能力 seam（`ctx.web`）注册
        fetchProvider: http-trusted
    ```
 
+   ⚠️ **保存该文件会立即热重载运行中的会话，不是「重启后才生效」。** profile 补丁层被
+   文件监听器盯着，落盘那一刻当前会话就会被重新配置。若插件此时尚未加载（跳过了第 3
+   步），`web` 行立刻指向一个还没注册的 provider，当前会话的 `web_search`/联网能力当场报
+   `WEB_PROVIDER_CONFIGURED_MISSING`。**重启即恢复**：启动时插件与补丁一起读入。先改
+   补丁、稍后再重启对启动同样安全，只是当前会话的联网能力要等到那次重启才可用。
+
    `web` 行由基座 dsh-base 提供，**不要用 `insert:` 新增同 id 行**——那会撞 id 直接崩
    `duplicate loader entry id: web`；这里要按 id 覆盖既有行，且覆盖是**整行重写，需写全
    `fetchProvider`**。
-3. 重启 dsh-tui（`/restart`）生效。
 
 ## 配置
 
@@ -82,6 +100,10 @@ refs:
   TAVILY_API_KEY: 'tvly-...'
 ```
 
+也可以在启动 dsh 的环境里导出 `TAVILY_API_KEY`：解析时先查凭证服务、再查启动环境。
+配置里的字面 `dsh-web-tavily.apiKey` 同样可用，且优先于以上两者，但它等于把密钥写进
+设置文档，只建议作为最后手段。
+
 ## 切回 DeepSeek 原生搜索
 
 把 `web.searchProvider` 改为 `deepseek-official`（或删除该键、让 seam 用唯一可用 provider）。注意 seam 不支持自动回退：Tavily 配置失效时搜索会明确报错，而**不会**悄悄走 DeepSeek。
@@ -106,7 +128,9 @@ config:
 ## 加载失败排查
 
 - 插件启动报 `duplicate loader entry id: web`：profile `cordis.patch.yml` 误用 `insert:` 新增同 id 行，按上文改写为直接行。
-- `web_search` 报 `WEB_PROVIDER_CONFIGURED_MISSING`：插件未加载（检查 bundles 列表与上述补丁）。
+- `web_search` 报 `WEB_PROVIDER_CONFIGURED_MISSING`：`web` 行指向的 provider 尚未注册
+  ——要么插件没加载（检查 bundles 清单），要么 `cordis.patch.yml` 在插件加载前就被保存
+  （保存即热重载，见「安装」）；`/restart` 即可恢复。
 - `web_fetch` 报 `WEB_BLOCKED_URL ... non-public IP`：代理假 IP 预检拒绝，改用 `http-trusted` 或关闭代理 fake-IP 模式。
 
 ## 限制说明

package/dsh-plugin.json

@@ -3,7 +3,7 @@
   "manifestVersion": "0.15",
   "id": "com.dsh-tui.dsh-web-tavily",
   "name": "dsh-web-tavily",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "facets": {
     "host": {
       "entry": "lib/index.js",

package/lib/diag.js

@@ -11,9 +11,9 @@
  * `~/.dsh-tui/` capped at 128 KiB, and no file writes under `node --test`.
  */
 
-import { appendFileSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 
 /** Plugin-owned log path. */
 export const DIAG_LOG = join(homedir(), '.dsh-tui', 'dsh-web-tavily.log');
@@ -31,6 +31,10 @@ function appendLogLine(path, line) {
     catch {
         // Missing or unreadable: the append below recreates it.
     }
+    // A fresh machine has no ~/.dsh-tui/ yet; create it first, or the append
+    // throws and the caller's catch swallows the line — losing exactly the
+    // evidence this log exists to keep.
+    mkdirSync(dirname(path), { recursive: true });
     appendFileSync(path, line);
 }
 

package/lib/index.js

@@ -3,9 +3,9 @@
  * 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.
+ * value: the key is resolved per operation from a literal `apiKey` config
+ * first, then the credentials service (ref, default TAVILY_API_KEY), then the
+ * launch environment, 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
@@ -26,6 +26,7 @@ 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 { createRequire } from "node:module";
 import { isIP } from "node:net";
 import { diag } from "./diag.js";
 import { applySettingsCard } from "./settings-card.js";
@@ -55,8 +56,24 @@ const DEFAULT_API_KEY_ENV = "TAVILY_API_KEY";
 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";
+/**
+ * Build the attribution header from the installed manifest (`../package.json`,
+ * beside `lib/`). The version is read at load time so a release can never leave
+ * it stale; a missing/unreadable manifest or version degrades to the bare
+ * plugin name — attribution is never a reason a module fails to load.
+ */
+function userAgent() {
+	try {
+		const version = createRequire(import.meta.url)("../package.json").version;
+		if (typeof version === "string" && version.length > 0) return `${name}/${version}`;
+	}
+	catch {
+		// Fall through to the name-only header.
+	}
+	return name;
+}
+/** Attribution header sent on every request. */
+const USER_AGENT = userAgent();
 /** Fallback result cap when the caller sends no maxResults. */
 const DEFAULT_MAX_RESULTS = 10;
 /** Tavily's documented per-request result cap. */

package/package.json

@@ -1,8 +1,18 @@
 {
   "name": "dsh-web-tavily",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "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",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "dsh-tui",
+    "deepseek-harness",
+    "plugin",
+    "search",
+    "tavily",
+    "web-search"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/VviLliAm-qwq/dsh-web-tavily.git"
@@ -29,10 +39,13 @@
   "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"
+    "@deepseek-ai/dsh-web": "^0.1.2-rc.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-web-fetch-http": "^0.1.2-rc.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-credentials": "^0.1.2-rc.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.2-rc.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.1.2-rc.1 || ^0.1.5-rc.1"
+  },
+  "dependencies": {
+    "ipaddr.js": "^2.5.0"
   }
 }