dsh-connect-agnes-token-plan 0.13.2 → 0.13.3

package/CHANGELOG.md

@@ -23,6 +23,15 @@
 
 ## [Unreleased]
 
+## [0.13.3] — 2026-10-26
+
+本版改一件事：**出图 / 视频工具开关即时生效**——工具本体就地注册 / 撤下，不再等下一次 Host 启动。
+
+### 变更：出图 / 视频工具随开关即时注册 / 撤下
+
+- **改（接入 API tab）**：出图与视频工具的开关、勾选与模型偏好，此前对工具本体的生效要等**下一次 Host 启动**（或重装插件）。现在翻一次开关就地把 `agnes_draw_image` / `agnes_video_generate` 注册或撤下，改模型偏好即时换模型；无需重启 `dsh web`、无需重装插件。
+- **说明**：宿主不提供卸载句柄时与旧版行为一致（工具对本进程粘性，保持首次注册值）；面板上开关状态的读写始终即时。机制与边界见 `docs/TOOL-HOT-RELOAD.md`。
+
 ## [0.13.2] — 2026-10-23
 
 本版两件事：**网关新上的模型默认就能发图**，以及**余额胶囊上会多一段「· N 新模型」**。两处都只影响 AgnesCode（桌面端）这条线。

package/README.md

@@ -46,7 +46,7 @@
 - **语言模型**：显示当前 Key 实际能调哪些模型，其中哪些能看图（按平台 `input_modalities` 判定，不靠名字猜）。
 - **出图工具**：Host 给 agent 注册 `agnes_draw_image` ，出图模型按 catalog 的 `output_modalities` 结构化判定。
 - **视频工具**：Host 给 agent 注册 `agnes_video_generate`，按选中模型分派 V2.0 / 2.5 两套互斥参数。
-- 开关与勾选都在面板热生效，无需重启。但工具的实际挂载 / 缺席发生在**下一次 Host 启动**（agent tools 没有 unregister 语义）。细节见 [docs/SETUP.md](docs/SETUP.md) §3、[docs/PROVIDER-HOT-RELOAD.md](docs/PROVIDER-HOT-RELOAD.md) 与 [docs/AGNES-API.md](docs/AGNES-API.md) §7.5。
+- 开关、勾选与工具挂载都热生效，无需重启：翻一次开关，出图 / 视频工具就地注册或撤下（0.13.x 起；宿主不给卸载句柄时工具对本进程粘性，见 [docs/TOOL-HOT-RELOAD.md](docs/TOOL-HOT-RELOAD.md)）。细节见 [docs/SETUP.md](docs/SETUP.md) §3、[docs/PROVIDER-HOT-RELOAD.md](docs/PROVIDER-HOT-RELOAD.md) 与 [docs/AGNES-API.md](docs/AGNES-API.md) §7.5。
 
 ![「接入 API」tab](assets/panel-API-provider.png)
 

package/client.js

@@ -2558,8 +2558,9 @@ var dsh_connect_agnes_token_plan_client = (function() {
 	/**
 	* The shared body of an agent-tool card (`DrawSwitch`, `VideoSwitch`).
 	*
-	* Both tools are mounted by the SAME Host ladder (`mountAgentTool` in
-	* `lifecycle.ts`) and both routes are served by the SAME handler shape
+	* Both tools are mounted by the SAME Host ladder (`createToolMount` in
+	* `lifecycle.ts`, each a live handle the switch route re-syncs on every
+	* successful write) and both routes are served by the SAME handler shape
 	* (`registerToolSwitchRoute` in `routes.ts`), so their cards differ only in
 	* which route they post to, which `llm.*` fields they read, and which
 	* dictionary prefix labels them. Writing the card once is what keeps the two

package/docs/API.md

@@ -115,7 +115,7 @@
     // quotaBlockedModelIds 是交给选择器剔除的 id 集。Agnes 下**恒为空**——
     // 平台不按模型分配额，账号级用尽由面板明说，而不是静默摘模型。
     "quotaBlockedModelIds": [],
-    // 出图工具开关生效值与来源（0.4.2）；工具实际挂载在下一个 Host 启动时发生
+    // 出图工具开关生效值与来源（0.4.2）；工具实际挂载随之即时收敛（0.13.x 起，见 TOOL-HOT-RELOAD.md）
     "drawEnabled": false, "drawSource": "config",
     // 一次出图调用实际会寻址的模型 id：用与工具本身相同的 pickDrawModel
     // 优先级（调用参数 > 配置的 drawModelId > 目录首个出图模型）从同一份
@@ -224,9 +224,9 @@
 
 ### `POST /api/dsh-connect-agnes-token-plan/draw`
 
-`{ "enabled": true|false }` —— 把出图开关写入插件私有状态文件（`$DSH_HOME/state/<profile>/<plugin>/draw.json`，按 profile 分段、见 [PITFALLS.md](./PITFALLS.md) §23），与 `/provider` 走的是同一套「存私有状态」机制，但**不触发任何即时发布**——agent 工具的实际注册/缺席发生在下一个 Host 启动（或重新安装）时，由 `lifecycle.js` 的 `startSideEffects` 重读生效值。优先级：面板保存的值 > `cordis.patch.yml` 的 `drawEnabled`。非布尔 `enabled` 返回 400；跨域返回 403。
+`{ "enabled": true|false }` —— 把出图开关写入插件私有状态文件（`$DSH_HOME/state/<profile>/<plugin>/draw.json`，按 profile 分段、见 [PITFALLS.md](./PITFALLS.md) §23），与 `/provider` 走的是同一套「存私有状态」机制，但**不发布 provider**——写成功后立即收敛**工具挂载**：协调器 `sync()` 就地注册 / 撤下 / 换模型（0.13.x 起，机制见 [TOOL-HOT-RELOAD.md](./TOOL-HOT-RELOAD.md)；宿主不给卸载句柄时工具粘性，保持首次注册值）。优先级：面板保存的值 > `cordis.patch.yml` 的 `drawEnabled`。非布尔 `enabled` 返回 400；跨域返回 403。
 
-`{ "drawModelId": "agnes-image-2.5-flash" }`（或 `null` = 自动选择）—— 把出图模型偏好写入同一个 `draw.json`。生效时机与开关相同：`startSideEffects` 在下一次挂载时用它覆盖 `cordis.patch.yml` 的 `drawModelId`（优先级：面板 > 配置；面板清除后回落配置，配置也为空则自动取目录第一个出图模型）。非空字符串之外的非 null 值返回 400；跨域返回 403。`{ "forget": true }` 同时清除开关与模型偏好的面板保存值。
+`{ "drawModelId": "agnes-image-2.5-flash" }`（或 `null` = 自动选择）—— 把出图模型偏好写入同一个 `draw.json`。生效时机与开关相同：写成功后协调器就地收敛（已挂载则先撤旧再注新，见 [TOOL-HOT-RELOAD.md](./TOOL-HOT-RELOAD.md)）；优先级：面板 > 配置，面板清除后回落 `cordis.patch.yml` 的 `drawModelId`，配置也为空则自动取目录第一个出图模型。非空字符串之外的非 null 值返回 400；跨域返回 403。`{ "forget": true }` 同时清除开关与模型偏好的面板保存值。
 
 ### `GET /api/dsh-connect-agnes-token-plan/video`
 

package/docs/DSH-PLUGIN.md

@@ -25,7 +25,7 @@ DSH 插件是一段在 **Host**（桌面版或 `dsh web`）进程内运行的代
 {
   "name": "dsh-connect-agnes-token-plan",
   "icon": "./icon.svg",                  // Plugins 页插件卡图标：Host 读此字段按 SVG/PNG/JPEG/WebP 渲染（相对路径、落在 files 内、≤256 KiB，任一不满足会让整条元数据报错）
-  "version": "0.13.2",
+  "version": "0.13.3",
   "main": "./lib/index.js",              // Host 半边入口：src/host/*.ts 经 tsdown 打成的单条 bundle
   "exports": {
     ".": "./lib/index.js",               // 源码在 src/host/，lib/ 为纯构建产物（随库提交，git/市场直装零构建）

package/docs/PROVIDER-HOT-RELOAD.md

@@ -77,9 +77,9 @@ trae/workbuddy 的 volatile 路线（把 `registerProvider` 标成 Config schema
 | `snapshot-aggregate.ts` | 快照 `llm.drawEnabled` / `llm.drawSource` 回显生效值与来源 |
 | `panel-page.ts` | 独立 SectionCard 承载「出图工具」卡片，含 `DrawSwitch` 控件（`ProviderForm` 已移到 `provider-controls.ts`，见其脚注） |
 
-与 provider 开关的一个**语义差异**需要说明：provider 开关改的是「当前请求立刻重新发布注册对」，改完立即生效；draw 开关改的是「挂载时是否注册 agent 工具」，**当前 Host 进程里已经注册的工具不会因为改开关而消失或出现**——要真正生效需要在**下一个 Host (re)mount**（即重启 `dsh web` 或重新安装插件）时，`lifecycle.ts` 的 `startSideEffects` 重新读生效值。面板开关本身是「立即生效、无需重启」的**状态读写**；工具的实际挂载/卸载要等到下次 Host 启动。面板文案里「立即生效」指的是**开关值**本身，不是 agent 工具的实时性。
+与 provider 开关在 0.4.2 时期存在一个**语义差异**（该差异现已解除，见 §9）：provider 开关改的是「当前请求立刻重新发布注册对」，改完立即生效；而当时 draw 开关改的是「挂载时是否注册 agent 工具」，`mountAgentTool` 丢弃了宿主返回的卸载句柄，**已注册的工具不会随开关在进程内消失或出现**——要真正生效需等**下一个 Host (re)mount**（重启 `dsh web` 或重装插件）时 `startSideEffects` 重新读生效值。面板文案里「立即生效」当时仅指**开关值**本身的读写。0.13.x 起补齐了热挂载/卸载协调层，draw 与 video 开关也随之**无需重启即时生效**（机制与边界见 §9）。
 
-**已知边界**：两个 Host 进程共享同一状态目录时，后写者胜（与 provider / throttle / catalog 文件语义一致）。`POST /draw` 只改开关值，不直接操作 tools registry——这是有意的：tools registry 没有 `unregister` 语义（见 `lifecycle.ts` 注释），强行卸载要等 Host 生命周期自然结束。
+**已知边界**：两个 Host 进程共享同一状态目录时，后写者胜（与 provider / throttle / catalog 文件语义一致）。`POST /draw` 在 0.4.x 时期只改开关值、不直接操作 tools registry——因为当时宿主未提供可捕获的卸载句柄，工具卸载要等 Host 生命周期自然结束。这一限制**已在 0.13.x 解除**：`POST /draw`（与 `/video`）现会触发即时再同步（`createToolMount.sync()`），机制与「宿主不给卸载路径则工具粘性挂载」的边界见 §9。
 
 ## 8. 0.4.3 增量：视频工具开关（videoEnabled）
 
@@ -101,9 +101,23 @@ trae/workbuddy 的 volatile 路线（把 `registerProvider` 标成 Config schema
 
 ---
 
-> **结构沿革注记**：本节两张改动表是 0.4.x 各增量落地时的定格记录，表中「新增」文件此后又经历过收敛与拆分。查现行结构以 [ARCHITECTURE.md](./ARCHITECTURE.md) §2 为准；与上表直接相关的三处：
+## 9. 0.13.x 增量：出图 / 视频工具的「真热开关」（disposer 保留的即时挂载/卸载）
+
+§7 里那句「工具的实际挂载/卸载要等到下次 Host 启动」在 0.4.x 时期是对的——当时 `mountAgentTool` 把宿主 `tools.register()` 返回的卸载句柄直接丢弃，所以 agent 工具只能「挂载一次」。现在改掉了：
+
+1. **宿主本就支持卸载**。`tools.register(definition)` 返回一个 `() => void` 的 disposer（同族插件 workbuddy 的 image/video 工具已长期以「常驻注册 + 保留句柄 + 开关切换时 live 卸载/换模型」的形态跑在生产），`types.ts` 把 `HostCtx.tools.register` 的类型从 `unknown` 收紧成 `(() => void) | undefined`。不给卸载路径的宿主返回 `undefined`，工具退化为粘性「挂载一次」——这是宿主能力边界，不是缺陷。
+2. **每工具一个「热挂载协调器」** `createToolMount`（`lifecycle.ts`，替代旧的一次性 `mountAgentTool`）。它持有闭包状态（缓存的宿主 `tools` 服务引用、`registered` / `disposer` / `regModel`）并把**所有**协调串在**同一条 promise 链**上，使「开关 POST / 模型 POST / forget / 挂载种子」的并发触发不会重复注册同一工具：链上每跑一次都**重读当前生效值**再收敛，所以排队的旧协调照样落到最新态。收敛规则：关 → 有 disposer 就卸载（没有则保持粘性，不动）；开且与已注册模型一致 → 幂等不动；开但模型变了 → 有 disposer 先卸旧再注新（模型偏好也即时生效）。
+3. **句柄落在接线袋**（`wiring.drawToolMount` / `wiring.videoToolMount`），开关路由（`routes/tool-switch.ts` 的 `registerToolSwitchRoute`，draw 与 video 共用）在**每次成功的写入后**（`enabled` / `forget` / 模型偏好）调用协调器 `sync()`。协调是 fire-and-forget、不阻塞 HTTP 响应；GET 只读路径**绝不**协调——读不应改写宿主注册表。
+4. **teardown 顺序**（PITFALLS §18）在路由 `off()` 之前释放两个工具协调器：`stop → dispose → release → tools → off`，让在途的开关 POST 无法再往一个正在离场的宿主里同步工具。
+
+**已知边界**：宿主不提供卸载路径时（`register` 返回 `undefined`），工具对本进程粘性——开关/模型改动能被协调器读到，但没有句柄可卸，注册保持首次值；此时行为与 0.4.x 完全一致。面板开关的状态读写永远即时生效，工具注册跟不跟上取决于宿主能力。
+
+---
+
+> **结构沿革注记**：本节两张改动表是 0.4.x 各增量落地时的定格记录，表中「新增」文件此后又经历过收敛与拆分。查现行结构以 [ARCHITECTURE.md](./ARCHITECTURE.md) §2 为准；与上表直接相关的四处：
 >
 > - **video 逻辑层已拆分**：表中的单文件 `video.ts` 现在只保留 `agnes_video_generate` 工具定义与兼容 barrel；建任务/轮询状态机在 `video-client.ts`，V2.0 与 2.5 两套请求体分别在 `video-protocol.ts` / `video-protocol-25.ts`，目录花名册在 `video-models.ts`。
 > - **两个开关 store 不再逐字镜像**：重复体已收敛到 `switch-store.ts`（provider / draw / video / AgnesCode 共用一层），`draw-store.ts` 与 `video-store.ts` 只剩各自的文件名、形状版本、model wire key 与报错措辞。事故与收敛过程见 [PITFALLS.md](./PITFALLS.md) §34。
 > - **draw / video 共用的路由处理器**现在落在 `routes/tool-switch.ts`，由 `routes.ts` 门面统一注册。
+> - **§7/§8 表格里指名的共享私有函数 `mountAgentTool` 已于 0.13.x 换成 `createToolMount`**（热挂载协调器，§9）：工具从「挂载一次、卸载等 Host 重启」变成「开关/模型写入后即时挂载、卸载、换模型」。表格里 `lifecycle.ts` 一行的 `registerDrawTool` / `registerVideoTool` 名字不变，现在它们返回并保留热句柄而不是 fire-and-forget 地丢弃。
 

package/docs/README.md

@@ -17,6 +17,7 @@ AI 协作会话从根目录 [AGENTS.md](../AGENTS.md) 进入：验证怎么跑
 | [AUTH.md](./AUTH.md) | 一跳账号密码登录、无 refresh token（重登即续期）、密码明文过 TLS 与不落盘纪律、登录 trace、防锁号节流 | 改登录/重登、排查登录失败 |
 | [API.md](./API.md) | 本地路由（`snapshot` / `account` / `api-key` / `provider` / `models` / `draw` / `video` / `agnescode` 共 8 组）、控制台端点、配置端点清单 | 对接路由、看返回结构、调端点 |
 | [PROVIDER-HOT-RELOAD.md](./PROVIDER-HOT-RELOAD.md) | 提供方注册开关：从「配置字段 + 重启」到「面板开关 + 立即生效」的设计决策与同类插件调研 | 改 provider 注册、理解开关语义 |
+| [TOOL-HOT-RELOAD.md](./TOOL-HOT-RELOAD.md) | 出图 / 视频 agent 工具热挂载机制（0.13.x）：disposer 保留、每工具协调器、开关写入触发 `sync()`、teardown 顺序、宿主不给卸载句柄的粘性边界 | 改工具挂载 / 开关语义、排「翻了开关工具没变」 |
 | [TESTING.md](./TESTING.md) | 离线测试体系、`panel-decision.js` 机制、已知缺口 | 跑测试、理解测试为什么这样写 |
 | [AGNES-API.md](./AGNES-API.md) | **现行接口事实源**：控制台额度侧（端点表、响应信封、四窗口额度模型、套餐目录与 uuid 匹配）＋推理侧（provider `agnes-token-plan`、key `AGNES_TOKEN_PLAN_API_KEY`、思考档位 safe-set、live-contract 护栏） | 改额度/推理接口、排「打到错网关」、对 live-contract 基线 |
 | [PITFALLS.md](./PITFALLS.md) | 真实踩坑（现象→根因→修法）；**条数以文件内 `## N.` 编号为准，别在此写死** | 改代码前避坑、理解防御性代码的来由 |

package/docs/TOOL-HOT-RELOAD.md

@@ -0,0 +1,67 @@
+# 出图 / 视频工具热挂载（Tool Hot-Mount）
+
+本文记录 0.13.x 起出图 / 视频 agent 工具（`agnes_draw_image` / `agnes_video_generate`）的**热挂载机制**：面板开关、模型偏好的每次写入都**就地**收敛工具的注册 / 撤下 / 换模型，无需重启 Host。**路由与开关的现行契约以 [API.md](./API.md) §1（`/draw` / `/video` 路由段）为准，provider 注册开关的决策记录见 [PROVIDER-HOT-RELOAD.md](./PROVIDER-HOT-RELOAD.md)，本篇侧重机制与边界。**
+
+---
+
+## 1. 为什么 0.4.x 时期不热
+
+出图（0.4.2）与视频（0.4.3）工具开关落地时，「面板开关 + 立即生效」的语义只兑现了一半——**开关值本身**即时读写，工具的实际挂载 / 缺席要等**下一个 Host 启动**时 `startSideEffects` 重读生效值。三个成因，全部是本插件自己的接线选择，不是宿主能力边界：
+
+1. 开关状态存插件私有状态文件（`draw-store.ts` / `video-store.ts`），由自有路由 `POST /api/<name>/draw|video` 写入——路由只做**持久化 + 回显**，从不同步宿主注册表。
+2. 旧的一次性 `mountAgentTool` 把宿主 `tools.register()` 返回的卸载句柄直接丢弃（fire-and-forget），工具「挂载一次」后进程内无法撤下。
+3. 一条过时的注释（「the tools registry has no unregister call」）让「宿主没有卸载能力」当成了已知事实——**这是错的**。宿主 `tools.register(definition)` 本就返回一个 `() => void` 的 disposer；同族插件 workbuddy 的 image / video 工具长期以「常驻注册 + 保留句柄 + 开关切换时 live 卸载 / 换模型」的形态跑在生产。
+
+## 2. 机制
+
+### 2.1 宿主能力
+
+`HostCtx.tools.register(definition)` 返回 `(() => void) | undefined`（`types.ts` 把返回类型从 `unknown` 收紧为 `(() => void) | undefined`）。返回 `undefined` 的宿主（不提供卸载路径）下工具退化为**粘性挂载一次**——那是宿主能力边界，行为与 0.4.x 一致，不是缺陷。
+
+### 2.2 每工具一个热挂载协调器
+
+`createToolMount`（`src/host/lifecycle.ts`，替代旧的一次性 `mountAgentTool`；`registerDrawTool` / `registerVideoTool` 是它的两个薄包装，差异只有开关键、模型键、fetch 与工厂，降级阶梯写一份，两个工具**不可能降级不同**）。每个协调器持有自己的闭包状态：
+
+| 状态 | 含义 |
+|---|---|
+| `tools` | 缓存的宿主 tools 服务（`resolveServiceWithRetry` 找到一次后复用；没找到时每次 `sync()` 重新探测，晚到的服务能被后续协调接住） |
+| `registered` | 宿主是否真的持有该工具的一份副本 |
+| `disposer` | 撤下句柄；宿主不给卸载路径时为 `null`（粘性） |
+| `regModel` | 当前注册所用模型偏好（面板保存值 > 配置默认） |
+| `chain` | **同一条 promise 链**：所有协调（挂载种子、开关 POST、模型 POST、forget、teardown 前在途调用）串在这条链上，并发触发不会重复注册同一工具；链上每跑一次都**重读当前生效值**再收敛，排队的旧协调照样落到最新态 |
+
+收敛规则（`sync()` 每跑一次）：
+
+- **关** → 有 disposer 就撤下（清状态后 `safeCall(disposer)`）；没有则保持粘性，不动。
+- **开且与已注册模型一致** → 幂等，不动。
+- **开但模型变了** → 有 disposer 先撤旧再注新（模型偏好也即时生效）；无 disposer 保持首次注册值。
+- 挂载路径：读 tools 服务 → 懒加载 tools peer（`defineTool`）→ 工厂构造工具定义（目录**调用时**读取：活目录缺席回落 `catalogStore.list()`，目录刷新落地不需要重注册）→ `tools.register(definition)`（catch：拒绝的注册表降级为工具缺席）→ 捕获 disposer。
+
+**双降级纪律不变**：无 tools 服务 / peer 装载失败 / 注册表拒绝——每一档都是**静默**降级：面板与 provider 照常，工具只是缺席，没有任何一行日志把失败打成配置错误。
+
+### 2.3 句柄与触发点
+
+句柄落在接线袋（`wiring.drawToolMount` / `wiring.videoToolMount`，`startSideEffects` 填充）。开关路由（`src/host/routes/tool-switch.ts` 的 `registerToolSwitchRoute`，draw 与 video 共用一份处理器）在**每次成功的 POST 写入后**（`enabled` / `forget` / 模型偏好三处）调用协调器 `sync()`：
+
+- 协调是 **fire-and-forget**，不阻塞 HTTP 响应；失败自吞（面板状态永远是对的，工具注册跟不跟上取决于宿主能力）。
+- **GET 只读路径绝不协调**——读不应改写宿主注册表。
+
+## 3. teardown 顺序
+
+卸载顺序按 [PITFALLS.md](./PITFALLS.md) §18 钉死：`stop → dispose → release → tools → off`。两个工具协调器的 `dispose()` 在路由 `off()` **之前**执行（撤下活工具 + 关闭句柄），让在途的开关 POST 无法再往一个正在离场的宿主里同步工具；句柄关闭后，队列里未跑的 `sync()` 变成 no-op 而不是迟到的注册。
+
+## 4. 边界与失败形状
+
+- **宿主不给卸载句柄**（`register` 返回 `undefined`）：工具对本进程**粘性**——开关 / 模型改动能被协调器读到，但没有句柄可撤，注册保持首次值；行为与 0.4.x 完全一致。面板开关的状态读写永远即时生效。
+- **两个 Host 进程共享同一状态目录**：后写者胜（与 provider / throttle / catalog 状态文件语义一致）。
+- **协调失败自静默**：tools 服务缺席、peer 装载失败、注册表拒绝——面板与 provider 零影响，工具缺席即可；没有任何一行日志为它点名。
+
+## 5. 测试锚点
+
+- `test/routes.test.mjs`：开关路由的无 tools 服务降级路径（假宿主 ctx 无 `tools` 服务）与键名隔离（组 S 交叉投递 / 各自回读，[API.md](./API.md) §1 `/draw` / `/video` 段引注）。
+- **已知缺口**：disposer 路径（挂载 / 撤下 / 换模型）尚无离线套件——需要向挂载缝注入一个返回 disposer 的假 `tools` 服务；补套件前先冻结现状。
+- 工具纯逻辑（失败分诊 / 冷却 / hints）由 `test/draw.test.mjs` 等覆盖，与挂载无关。
+
+---
+
+> 跨链：决策记录（为何不走 volatile、开关语义沿革）见 [PROVIDER-HOT-RELOAD.md](./PROVIDER-HOT-RELOAD.md) §7–§9；出图对接点（ARCHITECTURE §5.4 接法 B）见 [ARCHITECTURE.md](./ARCHITECTURE.md) §5.4；「为何自己造工具」的 runtime 取证见 [DSH-UNIFIED-INTERFACE-AUDIT.md](./DSH-UNIFIED-INTERFACE-AUDIT.md)。

package/docs/TROUBLESHOOTING.md

@@ -76,7 +76,7 @@
 - **没有「登出」按钮**：能停的是 provider 开关，不是令牌。「删除已存 JWT」是隐私动作，被刻意移出日常操作；真正吊销只能在桌面 App 里登出 / 改密码。见 [SETUP.md](./SETUP.md) §3。
 - **「可看图」清单为空**：Agnes 目录条目**不带** `input_modalities`（实测只有 `id`/`object`/`created`/`owned_by`/`supported_endpoint_types` 五个字段），`identifyVisionModel` 只能读目录 → 恒 false。这是**「读不到」而不是「没有」**——官方文档（`AGNES-API-docs/`）明说 `agnes-3.0-flash` / `agnes-2.5-pro` / `agnes-2.5-flash` 支持「文本 + 图像 URL 输入」，所以空清单不能当作「真没有可看图模型」的证据。见 [AGNES-API.md](./AGNES-API.md) §7.1。
 - **「可看图」整行消失**：不是被裁掉，是没有 API Key → 目录没拉 → 视觉清单无从生成。见 §1.3 第一行。
-- **改了设置不重启也生效，但工具挂载要等下次启动**：开关与勾选走热生效；agent 工具没有 unregister 语义，挂载 / 缺席只发生在 Host 启动时。见 [PROVIDER-HOT-RELOAD.md](./PROVIDER-HOT-RELOAD.md)。
+- **翻了开关出图 / 视频工具却没变**：开关值读写永远即时；工具挂载跟不跟得上取决于宿主能力——宿主不给卸载句柄时工具对本进程**粘性**（保持首次注册值，0.13.x 起的行为边界），机制与失败形状见 [TOOL-HOT-RELOAD.md](./TOOL-HOT-RELOAD.md) §4。
 - **拼错的配置键只记日志、不报错**：老 patch 里的历史键不该把面板打成配置错误。见 [SETUP.md](./SETUP.md) §3。
 - **429 与额度耗尽不是一件事**：402 是额度不足，429 多为速率上限（订阅用尽也可能回 429）。见 [AGNES-API.md](./AGNES-API.md)。
 

package/lib/index.js

@@ -5490,9 +5490,12 @@ const VIDEO_PATH = `/api/${name}/video`;
 * @param {string} options.modelSourceKey - the response key carrying its source.
 * @param {string} options.configModelId - the config default for the model id.
 * @param {Set<string>} options.allowedHosts - the trust fence.
+* @param {ToolMount} [options.mount] - the live tool mount handle; each
+*   successful POST write converges it (hot reload). Absent = the route only
+*   persists state, the mount is reconciled elsewhere (mount seed / teardown).
 * @returns {Function} the `off()` unregister callback.
 */
-function registerToolSwitchRoute(ctx, { path, label, store, enabledKey, enabledSourceKey, configEnabled, modelKey, modelSourceKey, configModelId, allowedHosts }) {
+function registerToolSwitchRoute(ctx, { path, label, store, enabledKey, enabledSourceKey, configEnabled, modelKey, modelSourceKey, configModelId, allowedHosts, mount }) {
 	return ctx.webServer.register({
 		kind: "exact",
 		path,
@@ -5516,6 +5519,9 @@ function registerToolSwitchRoute(ctx, { path, label, store, enabledKey, enabledS
 					...extra
 				}, { "cache-control": "no-store" });
 			};
+			const commit = () => {
+				if (mount !== null && mount !== void 0) mount.sync().catch(() => {});
+			};
 			if (method === "GET") {
 				await answer();
 				return;
@@ -5543,6 +5549,7 @@ function registerToolSwitchRoute(ctx, { path, label, store, enabledKey, enabledS
 					});
 					return;
 				}
+				commit();
 				await answer();
 				return;
 			}
@@ -5571,6 +5578,7 @@ function registerToolSwitchRoute(ctx, { path, label, store, enabledKey, enabledS
 					});
 					return;
 				}
+				commit();
 				await answer();
 				return;
 			}
@@ -5597,12 +5605,14 @@ function registerToolSwitchRoute(ctx, { path, label, store, enabledKey, enabledS
 				});
 				return;
 			}
+			commit();
 			await answer();
 		}
 	});
 }
 /**
-* Register the draw switch route. Wiring subset: `settings`, `drawStore`.
+* Register the draw switch route. Wiring subset: `settings`, `drawStore`,
+* `drawToolMount` (the live handle the successful writes converge).
 * @param ctx - the host root context.
 * @param {object} wiring - as assembled by `apply()` in `index.ts`.
 * @returns {Function} the `off()` unregister callback.
@@ -5619,11 +5629,13 @@ function registerDrawRoute(ctx, wiring) {
 		modelKey: "drawModelId",
 		modelSourceKey: "drawModelSource",
 		configModelId: settings.drawModelId,
-		allowedHosts: settings.allowedHosts
+		allowedHosts: settings.allowedHosts,
+		mount: wiring.drawToolMount ?? null
 	});
 }
 /**
-* Register the video switch route. Wiring subset: `settings`, `videoStore`.
+* Register the video switch route. Wiring subset: `settings`, `videoStore`,
+* `videoToolMount` (the live handle the successful writes converge).
 * @param ctx - the host root context.
 * @param {object} wiring - as assembled by `apply()` in `index.ts`.
 * @returns {Function} the `off()` unregister callback.
@@ -5640,7 +5652,8 @@ function registerVideoRoute(ctx, wiring) {
 		modelKey: "videoModelId",
 		modelSourceKey: "videoModelSource",
 		configModelId: settings.videoModelId,
-		allowedHosts: settings.allowedHosts
+		allowedHosts: settings.allowedHosts,
+		mount: wiring.videoToolMount ?? null
 	});
 }
 
@@ -7556,11 +7569,13 @@ function defineVideoTool({ defineTool, resolveApiKey, getEntries, settings, fetc
 *   - the mount seed (`seedPublisherFromCatalog`): offer models before the
 *     first poll, fire-and-forget;
 *   - the two generation tools (opt-in `drawEnabled` / `videoEnabled`,
-*     doubly degraded through the shared {@link mountAgentTool} ladder);
+*     doubly degraded through the shared {@link createToolMount} ladder —
+*     each handle is stored on the wiring bag, so the switch route re-syncs it
+*     live and teardown disposes it);
 *   - vision step two: the settings-row writer filled for the snapshot route.
 *
 * and {@link teardown} for the unmount order that PITFALLS §18 pins
-* (`dispose → release → off×5` — it must NOT be simplified).
+* (`stop → dispose → release → tools → off` — it must NOT be simplified).
 *
 * Peer-free discipline: no Host peer is imported here. The only lazy peer
 * loads (the adapter / tools modules) are injected from `apply` via `deps`.
@@ -7574,12 +7589,14 @@ const SERVICE_RETRY_DELAY_MS = 300;
 /**
 * Read an optional Host service with a bounded retry.
 *
-* A service may register AFTER this plugin mounts, and a mount-time read is
-* the only window for a capability the Host cannot later remove: the tools
-* registry has no unregister call. A one-shot read therefore misses a service
-* that arrives a moment late for the WHOLE session, silently — the draw tool
-* would be absent with the switch visibly on, and no line on any panel naming
-* the reason. The AgnesCode mount seed uses the same retry for its publish.
+* A service may register AFTER this plugin mounts: a one-shot read misses a
+* service that arrives a moment late, silently — the draw tool would be
+* absent with the switch visibly on, and no line on any panel naming the
+* reason. A late service is catchable LATER too, not only here: the tool
+* coordinator caches the service once found, but a `sync()` that has not
+* found one yet re-probes on every run (so a switch flip picks up a tools
+* service that registered late). The AgnesCode mount seed uses the same
+* retry for its publish.
 *
 * This retries the READ ONLY. Whatever it returns is used exactly once by the
 * caller: retrying a call that mutates (a tool registration) would register the
@@ -7616,7 +7633,8 @@ async function resolveServiceWithRetry(ctx, service, options = {}) {
 	return found;
 }
 /**
-* Mount one opt-in agent tool, through the shared degradation ladder.
+* The live mount handle for ONE opt-in agent tool, through the shared
+* degradation ladder.
 *
 * `registerDrawTool` and `registerVideoTool` differ only in which switch, which
 * model preference, which fetch and which factory they name — everything else
@@ -7626,42 +7644,84 @@ async function resolveServiceWithRetry(ctx, service, options = {}) {
 * degrade differently: a tool that vanished on a Host where the other survived
 * would be a bug with no visible cause.
 *
-* Every rung returns silently rather than throwing. A Host without a tools
-* service, or a peer that fails to load, must leave the panel and the provider
-* untouched — the tool is simply absent.
+* The returned {@link ToolMount} is what makes the tool HOT: the panel switch
+* route re-runs `sync()` after it writes the state file, and `sync()` mounts
+* or unmounts the tool in place using the disposer the host's
+* `tools.register` returns. Every rung still returns silently rather than
+* throwing: a Host without a tools service, or a peer that fails to load,
+* leaves the panel and the provider untouched — the tool is simply absent.
+*
+* State is per-handle (a closure), shared by the mount-time seed, every switch
+* POST and teardown, so the two callers cannot drift into registering the same
+* tool twice: all reconciliations are serialized behind one promise chain,
+* each re-reading the CURRENT effective value before it acts.
 * @param {object} options - wiring.
-* @param {object} options.ctx - the host root context.
-* @param {object} options.wiring - see {@link startSideEffects}.
-* @param {object} options.side - the test seams from `apply`'s `deps`.
-* @param {object} [options.store] - the panel switch store (`draw-store` / `video-store`).
-* @param {string} options.enabledKey - the settings key holding the config default.
-* @param {string} options.modelKey - the settings key holding the configured model id.
+* @param {HostCtx} options.ctx - the host root context.
+* @param {HostWiring} options.wiring - see {@link startSideEffects}.
+* @param {ToolSide} options.side - the test seams from `apply`'s `deps`.
+* @param {SwitchStore|null|undefined} [options.store] - the panel switch store.
+* @param {"drawEnabled"|"videoEnabled"} options.enabledKey - the config-default switch key.
+* @param {"drawModelId"|"videoModelId"} options.modelKey - the config-default model key.
 * @param {Function} options.fetchImpl - the request fetch (stubbed in tests).
 * @param {Function} options.factory - `defineDrawTool` / `defineVideoTool`.
-* @returns {Promise<void>}
+* @returns {ToolMount} the live handle; call `sync()` to reconcile.
 */
-async function mountAgentTool({ ctx, wiring, side, store, enabledKey, modelKey, fetchImpl, factory }) {
+function createToolMount({ ctx, wiring, side, store, enabledKey, modelKey, fetchImpl, factory }) {
 	const { settings, configError, providerState, catalogStore, resolveApiKey, publisher } = wiring;
-	if (configError !== null) return;
-	const { enabled: toolEnabled } = resolveSwitchEnabled(await readPanelValue(async () => await store?.enabled() ?? null), settings[enabledKey]);
-	if (toolEnabled !== true) return;
-	const panelModelId = await readPanelValue(async () => await store?.modelId() ?? null);
-	const effectiveSettings = panelModelId !== null ? {
-		...settings,
-		[modelKey]: panelModelId
-	} : settings;
-	const tools = await resolveServiceWithRetry(ctx, "tools", { isDisposed: () => publisher.isDisposed() });
-	if (tools === null || typeof tools.register !== "function") return;
-	let defineTool;
-	try {
-		const mod = await Promise.resolve(side.loadToolsModule?.());
-		defineTool = mod?.defineTool ?? mod?.default?.defineTool ?? null;
-	} catch {
-		return;
-	}
-	if (typeof defineTool !== "function") return;
-	try {
-		tools.register(factory({
+	let tools = null;
+	let registered = false;
+	let disposer = null;
+	let regModel = null;
+	let closed = false;
+	let chain = Promise.resolve();
+	const safeCall = (fn) => {
+		if (fn === null) return;
+		try {
+			fn();
+		} catch {}
+	};
+	async function syncImpl() {
+		if (closed) return;
+		if (configError !== null) return;
+		const panelEnabled = await readPanelValue(async () => await store?.enabled() ?? null);
+		const panelModel = await readPanelValue(async () => await store?.modelId() ?? null);
+		const { enabled } = resolveSwitchEnabled(panelEnabled, settings[enabledKey]);
+		const { value: targetModel } = resolveSwitchValue(panelModel, settings[modelKey]);
+		if (enabled !== true) {
+			if (registered) {
+				const d = disposer;
+				registered = false;
+				disposer = null;
+				regModel = null;
+				safeCall(d);
+			}
+			return;
+		}
+		if (registered && regModel === targetModel) return;
+		if (registered && disposer === null) return;
+		if (registered && disposer !== null) {
+			const d = disposer;
+			registered = false;
+			disposer = null;
+			regModel = null;
+			safeCall(d);
+		}
+		const service = tools ?? await resolveServiceWithRetry(ctx, "tools", { isDisposed: () => publisher.isDisposed() });
+		if (service === null || typeof service.register !== "function") return;
+		tools = service;
+		let defineTool;
+		try {
+			const mod = await Promise.resolve(side.loadToolsModule?.());
+			defineTool = mod?.defineTool ?? mod?.default?.defineTool ?? null;
+		} catch {
+			return;
+		}
+		if (typeof defineTool !== "function") return;
+		const effectiveSettings = targetModel !== settings[modelKey] ? {
+			...settings,
+			[modelKey]: targetModel
+		} : settings;
+		const definition = factory({
 			defineTool,
 			resolveApiKey,
 			getEntries: async () => {
@@ -7671,21 +7731,48 @@ async function mountAgentTool({ ctx, wiring, side, store, enabledKey, modelKey,
 			settings: effectiveSettings,
 			fetchImpl,
 			isDisposed: () => publisher.isDisposed()
-		}));
-	} catch {}
+		});
+		let newDisposer;
+		try {
+			newDisposer = service.register(definition);
+		} catch {
+			return;
+		}
+		registered = true;
+		regModel = targetModel;
+		disposer = typeof newDisposer === "function" ? newDisposer : null;
+	}
+	return {
+		sync: () => {
+			const run = chain.then(() => syncImpl());
+			chain = run.then(() => void 0, () => void 0);
+			return run;
+		},
+		dispose: () => {
+			closed = true;
+			const d = disposer;
+			registered = false;
+			disposer = null;
+			regModel = null;
+			safeCall(d);
+		},
+		isMounted: () => registered
+	};
 }
 /**
-* Register the `agnes_draw_image` agent tool (ARCHITECTURE.md §5.4, route B).
-* Opt-in (`drawEnabled`, default off) and doubly degraded. Named as a separate
-* export so a test can inject its own `ctx`/`wiring`; `startSideEffects` calls
-* it when enabled.
+* Create the live mount handle for the `agnes_draw_image` agent tool
+* (ARCHITECTURE.md §5.4, route B). Opt-in (`drawEnabled`, default off) and
+* doubly degraded. The handle is stored on the wiring bag (`wiring.drawToolMount`)
+* so the switch route can re-sync it live and teardown can dispose it; the
+* initial `sync()` seeds the mount-time behavior (register now when the
+* effective value is on).
 * @param ctx - the host root context (reads `ctx.get("tools")` / `ctx.tools`).
 * @param {object} wiring - see {@link startSideEffects}.
 * @param {object} side - test seams from `apply`'s `deps`.
-* @returns {Promise<void>}
+* @returns {ToolMount} the live handle, also stored at `wiring.drawToolMount`.
 */
-async function registerDrawTool(ctx, wiring, side) {
-	await mountAgentTool({
+function registerDrawTool(ctx, wiring, side) {
+	const mount = createToolMount({
 		ctx,
 		wiring,
 		side,
@@ -7695,21 +7782,25 @@ async function registerDrawTool(ctx, wiring, side) {
 		fetchImpl: side.drawFetch,
 		factory: defineDrawTool
 	});
+	wiring.drawToolMount = mount;
+	mount.sync();
+	return mount;
 }
 /**
-* Register the `agnes_video_generate` agent tool (`video.ts`).
+* Create the live mount handle for the `agnes_video_generate` agent tool
+* (`video.ts`).
 *
 * A SEPARATE opt-in from the draw tool (`videoEnabled`), sharing only the
-* mounting ladder — see {@link mountAgentTool}. The protocol is the reason the
+* mounting ladder — see {@link createToolMount}. The protocol is the reason the
 * two are not one module: video is an asynchronous task, so this tool creates a
 * task and then polls it for minutes rather than issuing one request.
 * @param ctx - the host root context.
 * @param {object} wiring - see {@link startSideEffects}.
 * @param {object} side - test seams from `apply`'s `deps`.
-* @returns {Promise<void>}
+* @returns {ToolMount} the live handle, also stored at `wiring.videoToolMount`.
 */
-async function registerVideoTool(ctx, wiring, side) {
-	await mountAgentTool({
+function registerVideoTool(ctx, wiring, side) {
+	const mount = createToolMount({
 		ctx,
 		wiring,
 		side,
@@ -7719,6 +7810,9 @@ async function registerVideoTool(ctx, wiring, side) {
 		fetchImpl: side.videoFetch,
 		factory: defineVideoTool
 	});
+	wiring.videoToolMount = mount;
+	mount.sync();
+	return mount;
 }
 /**
 * Run the mount-time side effects: the persisted-catalog seed, the draw tool
@@ -7792,7 +7886,9 @@ function startSideEffects(ctx, wiring, side) {
 *      must not register into a Host that is letting this plugin go;
 *   2. `release` — stop offering the provider first, so a request cannot be
 *      routed to an adapter whose Host services are already half gone;
-*   3. the route `off()` callbacks, each guarded (the web server may already
+*   3. the live agent tools (draw / video) are unmounted, so an in-flight
+*      switch handler cannot re-sync a tool into a Host that is going away;
+*   4. the route `off()` callbacks, each guarded (the web server may already
 *      be gone during shutdown).
 *
 * This order is a concurrency fix and must NOT be simplified.
@@ -7812,6 +7908,8 @@ function teardown(wiring, offs, stopTick) {
 	agnescodePublisher?.dispose();
 	agnescodePublisher?.release?.();
 	releaseProvider();
+	wiring.drawToolMount?.dispose();
+	wiring.videoToolMount?.dispose();
 	for (const off of offs) try {
 		off();
 	} catch {}

package/package.json

@@ -2,7 +2,7 @@
   "name": "dsh-connect-agnes-token-plan",
   "displayName": "DSH Connect Agnes Token Plan",
   "icon": "./icon.svg",
-  "version": "0.13.2",
+  "version": "0.13.3",
   "description": "One-tap connect Agnes language, image and video models into DSH (off by default), with image recognition and thinking level filled in automatically. After signing in to the Agnes console (re-login uses AGNES_PASSWORD), you can see the quota windows (5-hour requests, weekly requests, daily images, video), account-wide cumulative usage, and a usage pill beside the input box. AgnesCode desktop models can be connected too (Windows only), re-reading the desktop app login when the token expires, with rate-limit hits backing off on their own.",
   "keywords": [
     "dsh-plugin",