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

package/CHANGELOG.md

@@ -23,6 +23,25 @@
 
 ## [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（桌面端）这条线。
+
+### 变更：新模型默认能发图，胶囊会告诉你网关多了哪个模型
+
+- **改（识图）**：网关新上的模型不再默认被当成纯文本。旧版只认「官方文档表里写过的」那几个，表里没有的模型就不给图片入口——看不到任何提示，只能自己发现。现在没证据的模型**默认放开图片输入**，面板把它标成「可看图·未实测」；确认看不见图的模型才被收回去（记在一份否决清单里，带实测日期）。
+- **新（胶囊）**：小浣熊/AgnesCode 的余额胶囊上会多一段「· N 新模型」。它比的是插件自己记的「这台机器见过哪些模型」，所以只在网关真的新上了模型时出现。新模型名字在 tooltip 和展开卡片里，最多列三个。标记保持 7 天，不弹窗、不需要点确认；装上新版后的第一次运行会把当时的目录当作「早就见过」，不会把整张表报成新的。
+- **说明**：两处都只影响 AgnesCode 这条线，商汤 Token Plan 侧的面板与胶囊不变。
+
 ## [0.13.1] — 2026-10-22
 
 本版只改一件事：**插件卡的标题**。中文叫「Agnes 模型接入」，英文叫「Agnes Model Access」，与「商汤模型接入」「魔搭模型接入」同构。

package/README.md

@@ -2,20 +2,11 @@
 
 <p align="center"><b>把 Agnes（爱思）接进 DSH 的 Plugins 页插件卡，并在会话输入框常驻一枚用量胶囊。</b></p>
 
-<p align="center">
-  <a href="#安装">安装</a> ·
-  <a href="#它是怎么工作的">工作原理</a> ·
-  <a href="CHANGELOG.md">更新日志</a> ·
-  <a href="https://github.com/eghrhegpe/dsh-connect-agnes-token-plan/issues">问题反馈</a>
-</p>
+<p align="center"><a href="#安装">安装</a> · <a href="#它是怎么工作的">工作原理</a> · <a href="CHANGELOG.md">更新日志</a> · <a href="https://github.com/eghrhegpe/dsh-connect-agnes-token-plan/issues">问题反馈</a></p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/dsh-connect-agnes-token-plan"><img src="https://img.shields.io/npm/v/dsh-connect-agnes-token-plan?style=flat-square&label=npm&color=cb3837" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/dsh-connect-agnes-token-plan"><img src="https://img.shields.io/npm/d18m/dsh-connect-agnes-token-plan?style=flat-square&label=downloads&color=cb3837" alt="npm downloads"></a>
-  <a href="https://github.com/eghrhegpe/dsh-connect-agnes-token-plan/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/eghrhegpe/dsh-connect-agnes-token-plan/ci.yml?branch=main&style=flat-square&label=tests" alt="test status"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/github/license/eghrhegpe/dsh-connect-agnes-token-plan?style=flat-square" alt="MIT license"></a>
-  <a href="https://github.com/eghrhegpe/dsh-connect-agnes-token-plan/stargazers"><img src="https://img.shields.io/github/stars/eghrhegpe/dsh-connect-agnes-token-plan?style=flat-square" alt="GitHub stars"></a>
-  <a href="https://dshfind.com/plugins/eghrhegpe/dsh-connect-agnes-token-plan"><img src="https://dshfind.com/api/badge/eghrhegpe/dsh-connect-agnes-token-plan" alt="dshfind plugin"></a>
+  <a href="https://www.npmjs.com/package/dsh-connect-agnes-token-plan"><img src="https://img.shields.io/npm/v/dsh-connect-agnes-token-plan?style=flat-square&label=npm&color=cb3837" alt="npm version"></a> <a href="https://www.npmjs.com/package/dsh-connect-agnes-token-plan"><img src="https://img.shields.io/npm/d18m/dsh-connect-agnes-token-plan?style=flat-square&label=downloads&color=cb3837" alt="npm downloads"></a> <a href="https://github.com/eghrhegpe/dsh-connect-agnes-token-plan/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/eghrhegpe/dsh-connect-agnes-token-plan/ci.yml?branch=main&style=flat-square&label=tests" alt="test status"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/eghrhegpe/dsh-connect-agnes-token-plan?style=flat-square" alt="MIT license"></a> <a href="https://github.com/eghrhegpe/dsh-connect-agnes-token-plan/stargazers"><img src="https://img.shields.io/github/stars/eghrhegpe/dsh-connect-agnes-token-plan?style=flat-square" alt="GitHub stars"></a> <a href="https://dshfind.com/plugins/eghrhegpe/dsh-connect-agnes-token-plan"><img src="https://dshfind.com/api/badge/eghrhegpe/dsh-connect-agnes-token-plan" alt="dshfind plugin"></a>
 </p>
 
 把 Agnes 接进 DSH：**Plugins 页**的插件卡（三个 tab），外加**会话输入框右侧的一枚用量胶囊**。**DSH** 即 **DeepSeek Harness**；**Agnes**（爱思）是全模态大模型平台，本插件对接其**控制台 API** 与**推理 API**。
@@ -55,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)
 
@@ -84,7 +75,8 @@
 
 - 读数与面板**同源**：控制台百分比优先用平台自己报的 `usage_pct`、缺失才回落 `已用 / 上限`，**不做钳制**（超额窗口就显示 >100%，那是事实）；桌面端画的是**存量**，所以**不造百分比**——网关只公布积分，没有「上限」可以当分母；
 - 两条上游**互不借用**：`agnescode` 的会话只读它自己的路由、绝不画控制台窗口，反之亦然；切到**别的 provider**（其它插件）的模型时胶囊直接消失，也不再发任何请求；
-- 读不到时**保留上一次数字并标「上次数据」**，不会清零或伪装成 0%；余额里的 `0` 是「烧完了」的读数（红色告警），`—` 才是「这次没读到」——这个区别是刻意的。
+- 读不到时**保留上一次数字并标「上次数据」**，不会清零或伪装成 0%；余额里的 `0` 是「烧完了」的读数（红色告警），`—` 才是「这次没读到」——这个区别是刻意的；
+- 网关新上了模型时，余额胶囊会多一段**「· N 新模型」**（名字在 tooltip 与展开卡里，最多三个，保留 7 天）。这里的「新」指**这台机器第一次见到它**，不是上游的上架时间——网关目录没有这个字段。装上新版后的第一次运行只把当时的目录记下来当基线，不会把整张表报成新的。
 
 ![AgnesCode 积分余额胶囊（点开读数卡）](assets/agnescode-usage-capsule.png)
 
@@ -118,12 +110,7 @@
 
 ## 运维诊断：这台机器现在挂没挂 provider？
 
-provider / 出图开关的生效值存在插件私有状态文件里（`$DSH_HOME/state/<name>/`），不在任何配置或路由上——查"到底开没开"用 doctor，它只读状态文件、不碰凭据，Host 没起也能跑：
-
-```powershell
-npm run doctor          # 人读：每个 profile 的 provider / draw / video / agnescode 开关与模型清单
-npm run doctor:json     # 机器读：JSON（可进你的巡检 / 工单脚本）
-```
+provider / 出图 / 视频 / AgnesCode 开关的生效值存在插件私有状态文件里（`$DSH_HOME/state/<name>/`），不在任何配置或路由上；`npm run doctor` 只读状态文件、不碰凭据，Host 没起也能跑（人读 / 机器读两个口径见 [docs/SETUP.md](docs/SETUP.md) §6.1）。
 
 ## 文档
 

package/client.js

@@ -264,6 +264,12 @@ var dsh_connect_agnes_token_plan_client = (function() {
 			"agnescode.models": "模型（{count}）",
 			"agnescode.fallbackRoster": "未取到实时目录，以下为内置清单，倍率截至 {asOf}。",
 			"agnescode.memberOnly": "会员",
+			"agnescode.visionAssumed": "可看图·未实测",
+			"agnescode.visionAssumedTitle": "网关没声明这个模型能否看图，插件默认放开图片入口（未实测）。真发过去模型说看不到，就把它的 id 记进否决清单。",
+			"agnescd.newModels": "新模型",
+			"agnescd.newModelsRow": "本机新见",
+			"agnescd.newModelsTitle": "本机首次见到的模型：",
+			"agnescd.newModelsSep": "、",
 			"agnescode.rateTitle": "平台公布的积分消耗倍率（0 为免费）",
 			"agnescode.registeredPill": "已注册",
 			"agnescode.rosterHint": "勾选决定哪些模型推送进 DSH 模型列表，改动即时生效。",
@@ -524,6 +530,12 @@ var dsh_connect_agnes_token_plan_client = (function() {
 			"agnescode.models": "Models ({count})",
 			"agnescode.fallbackRoster": "Live catalogue unavailable — showing the built-in list, rates as of {asOf}.",
 			"agnescode.memberOnly": "member",
+			"agnescode.visionAssumed": "vision (unverified)",
+			"agnescode.visionAssumedTitle": "The gateway did not declare whether this model sees images, so picture input is allowed by default and this is unverified. If the model answers it cannot see the image, add its id to the vision denylist.",
+			"agnescd.newModels": "new",
+			"agnescd.newModelsRow": "New here",
+			"agnescd.newModelsTitle": "First seen on this machine: ",
+			"agnescd.newModelsSep": ", ",
 			"agnescode.rateTitle": "Credit multiplier as published by the platform (0 = free)",
 			"agnescode.registeredPill": "Registered",
 			"agnescode.rosterHint": "Ticking decides which models are pushed into DSH's model list; the change takes effect immediately.",
@@ -1562,6 +1574,10 @@ var dsh_connect_agnes_token_plan_client = (function() {
 			},
 			pillReading: { fontVariantNumeric: "tabular-nums" },
 			pillStale: { color: "var(--dsw-alias-label-secondary)" },
+			pillNewTag: {
+				color: "var(--dsw-alias-label-secondary)",
+				flexShrink: 0
+			},
 			pillErrorText: { color: "var(--dsw-alias-state-error-primary)" },
 			pillTierOk: { background: "var(--dsw-alias-state-success-primary, #22c55e)" },
 			pillTierWarn: { background: "var(--dsw-alias-state-warn-primary, #f59e0b)" },
@@ -2542,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
@@ -4050,7 +4067,10 @@ var dsh_connect_agnes_token_plan_client = (function() {
 			}), h("span", { style: S.spacer }), promo === null ? null : h("span", { style: S.modelPromo }, promo), rate === null ? null : h("span", {
 				style: S.modelRate,
 				title: tt("agnescode.rateTitle")
-			}, `×${rate}`), row.memberOnly === true ? h("span", { style: S.modelBadge }, tt("agnescode.memberOnly")) : null), meta === "" ? null : h("div", { style: S.modelMeta }, meta));
+			}, `×${rate}`), row?.vision === true ? h("span", {
+				style: S.modelBadge,
+				title: row?.visionSource === "assumed" ? tt("agnescode.visionAssumedTitle") : void 0
+			}, row?.visionSource === "assumed" ? tt("agnescode.visionAssumed") : tt("llm.rosterVision")) : null, row.memberOnly === true ? h("span", { style: S.modelBadge }, tt("agnescode.memberOnly")) : null), meta === "" ? null : h("div", { style: S.modelMeta }, meta));
 		})));
 	}
 	/**
@@ -4665,10 +4685,17 @@ var dsh_connect_agnes_token_plan_client = (function() {
 		const permanent = partOf(state, "permanentBalance");
 		const split = timeLimited === null || permanent === null ? null : `${tt("agnescode.balanceTimeLabel")} ${count(timeLimited)} · ${tt("agnescode.balancePermanentLabel")} ${count(permanent)}`;
 		const usageText = agnescodeUsageText(state?.usage ?? null, tt);
+		const newIds = (Array.isArray(state?.newModelIds) ? state.newModelIds : []).filter((id) => typeof id === "string" && id !== "");
+		const shownNames = newIds.map((id) => {
+			const row = state?.models?.find((model) => model.id === id);
+			return row?.name ?? row?.id ?? id;
+		}).slice(0, 3);
+		const newModelTitle = newIds.length === 0 ? null : `${tt("agnescd.newModelsTitle")}${shownNames.join(tt("agnescd.newModelsSep"))}${newIds.length > shownNames.length ? "…" : ""}`;
 		const title = [
 			tt("composer.balanceTitle"),
 			split,
 			why,
+			newModelTitle,
 			stale ? tt("composer.stale") : null
 		].filter(Boolean).join(" · ");
 		const { popoverId, open, setOpen, rootRef, cardRef, triggerRef } = usePillPopover();
@@ -4693,6 +4720,10 @@ var dsh_connect_agnes_token_plan_client = (function() {
 				key: "why",
 				style: S.pillPopMuted
 			}, why) : null,
+			newIds.length > 0 ? h("div", {
+				key: "new-models",
+				style: S.pillPopMuted
+			}, `${tt("agnescd.newModelsRow")} ${shownNames.join(tt("agnescd.newModelsSep"))}${newIds.length > shownNames.length ? "…" : ""}`) : null,
 			stale ? h("div", {
 				key: "stale",
 				style: S.pillPopMuted
@@ -4716,7 +4747,13 @@ var dsh_connect_agnes_token_plan_client = (function() {
 			popoverOpen: open,
 			popoverId,
 			buttonRef: triggerRef,
-			children: h("span", { style: S.pillReading }, pending ? "…" : balance === null ? "—" : `${count(balance)} ${tt("composer.balanceUnit")}`)
+			children: [h("span", {
+				key: "reading",
+				style: S.pillReading
+			}, pending ? "…" : balance === null ? "—" : `${count(balance)} ${tt("composer.balanceUnit")}`), newIds.length === 0 ? null : h("span", {
+				key: "new-models",
+				style: S.pillNewTag
+			}, ` · ${newIds.length} ${tt("agnescd.newModels")}`)]
 		}), open ? h("div", {
 			ref: cardRef,
 			id: popoverId,

package/docs/ADR.md

@@ -206,3 +206,24 @@
 - **受影响的文档**：`src/host/agnescode-models.ts`（`agnescodeThinkingLevelMap(id)` per-model + 模块头决策 1）、`test/agnescode.test.mjs`（新增 agnes-2.5-pro 断言块）、`docs/ROADMAP.md` §6.3.1（新增 2026-10-18 探针行）、`CHANGELOG.md`（[Unreleased]）。ADR-009 原文按考古纪律保留不改写。
 - **与既有条目的关系**：细化 ADR-009 的档位映射（该裁定以 3.0-flash 探针为基础，未覆盖 2.5-pro 的阶梯差异）；不改变 `docs/DSH-LLM-DEVELOP.md` §4 的通用裁法（Token Plan 侧 `thinkingLevelMapFor` 未动）。
 
+## ADR-018 agnescode 识图默认放行：没证据的行也收图，但面板必须说「未实测」
+
+- **日期**：2026-10-22
+- **状态**：现行（实现见 `src/host/agnescode-models.ts` 的 `AGNESCODE_VISION_DENYLIST` / `agnescodeVisionVerdict` / `agnescodeVisionSource`，`agnescodeRoster` 把 `vision` 与 `visionSource` 一起透出；面板 chip 见 `src/client/agnescode-tab.ts`；门禁见 `test/agnescode.test.mjs` 的判定阶梯段与 `test/dom-render.test.mjs` 的 chip 段）
+- **裁定**：判定阶梯四级——**实测否决集 → 行内声明 → `PROBED_VISION` 实测表 → 默认放行（`assumed`）**。前三级给面板一个朴素 chip；`assumed` 必须画成「可看图·未实测」并带 tooltip；否决项画 `vision:false`、无 chip。换言之：**默认值是「给它图片」，唯一能否掉它的是带日期实测的否决条目**。
+- **理由**：网关 `/models` 的每一行都只写 `model_type: "text"`，从不说自己能不能看图（`fetchAgnescodeCatalog` 因此钉死 `vision:false`——那是 wire 事实，不是判决）。旧逻辑把「文档表里没有」读成「不支持」，于是网关每上一次新模型，图片入口就静默消失一次：用户看不到任何提示，只能自己发现并来报。这条失效方向是不可见的（能力缺失不像错报那样会在会话里露头），而错报在当前网关是可观测的：模型收到图片后自述看不见，HTTP 仍是 200。
+- **代价与护栏**：默认放行把失效方向翻成「错报」，但没有翻成「谎报」——`visionSource` 让面板把未实测的行标出来，读者因此知道这是插件的默认，不是平台的声明。否决集是唯一维护面：发现某模型自述看不见，就把它带日期加进 `AGNESCODE_VISION_DENYLIST`。
+- **边界**：只动 agnescode 这条上游；Token Plan 侧 `identifyVisionModel`（按 `/v1/models` 的 `input_modalities` 判定）不受影响，两侧判定函数不合并。`AGNESCODE_FALLBACK_MODELS` 的 `vision` 列是手写快照，不经过本判定函数；`visionSource` 只影响面板显示，不改变 descriptor 的 `input` 数组长度约定（`vision:true` → `["text","image"]`）。
+- **复核条件**：若网关开始在 `/models` 里声明模态（`input_modalities` 或视觉标签），第二级（`declared`）就会接管绝大多数行，`assumed` 退化为稀有位——那时本条仍然成立，只是很少被用到。若哪天实测发现「未实测默认可看图」在本网关的错报代价高到不可接受（例如图片被静默吞掉且模型照常编造），把默认改回 `false` 并把本条的 `assumed` 换成一个显式的 `unknown` chip。
+
+## ADR-019 网关新增模型走胶囊的「· N 新模型」，不弹窗、不留确认态
+
+- **日期**：2026-10-22
+- **状态**：现行（实现见 `src/host/agnescode-roster-seen-store.ts` 的首次见到历史、`src/host/routes/agnescode.ts` 的 `newModelIds` 差分、`src/client/composer-usage-pill.ts` 的 AgnesCode 胶囊段；门禁见 `test/agnescode.test.mjs` 的两个新段与 `test/dom-render.test.mjs` 的胶囊三帧）
+- **裁定**：网关目录里出现本机没见过的 model id 时，**只在胶囊上多一段「· N 新模型」**（tooltip 与 popover 给名字，最多列三个），不弹窗、不阻塞、不留「已读」按钮。判定基准是插件自己写的首次见到文件 `agnescode-roster-seen.json`：**首次写入是播种（整表记为已见、一条都不报）**，之后新增的 id 记为「现在」并保持 7 天，离开目录的 id 从表里删除（重新上架算新）。
+- **理由**：DSH 的 Host 面没有通知/弹窗服务，插件的可见面只有插件卡与胶囊；而胶囊本来就是读者扫余额的地方，把「网关多了个模型」放在余额旁边是同一类信息（都关于「现在能用什么」）。播种是必须的：升级后的第一次运行会把当时整张目录写成历史，否则每个老用户都会被告知全部七个模型都是新的——那是噪音，不是提醒。
+- **为什么不是弹窗 / 已读态**：弹窗需要用户处理，而「多了个模型」不需要处理；已读态需要一个点击，等于把一个纯信息变成一次任务。7 天窗口是提醒的寿命：够长到用户会看见，够短到不会永远挂着。重上架的 id 再报一次，因为那说明这一行背后的东西换过手，值得知道。
+- **边界**：只在 `modelsSource === "live"` 时差分——回退快照表是插件自己的六行文本，拿它差分会在登录/离线那几帧凭空造出「新模型」。差分对象是**整张 live 目录**，不是用户勾选的子集：某个模型是不是网关的新闻，与这台机器勾了哪些框无关；拿子集差分还会让一个上架很久的模型在「被勾上」的那天冒充新模型。`newModelIds` 缺席（旧生产者、离线、首次播种）时胶囊什么都不画，不画空段、不留悬空分隔符。该标记只出现在 agnescode provider 被选中的胶囊上；Token Plan 侧名册没有这个字段。
+- **复核条件**：若网关开始提供「上架时间」字段，差分就应改成读那个字段，本文件降级为离线兜底；若 DSH 之后提供通知服务，这段可以迁过去，胶囊只留计数。
+
+

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.1",
+  "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/SETUP.md

@@ -120,3 +120,14 @@ AgnesCode tab 读的是**另一个应用**（AgnesCode 桌面端）已经登录
 信号与处置的整张表已迁到 **[TROUBLESHOOTING.md](./TROUBLESHOOTING.md)**（按面板上的**界面原文**索引：面板读不出来、登录被拒、模型目录为空、以及「看着像坏了其实是设计」的清单）。
 
 本文件只管装、配、重启；排障从那份进。`shapeWarnings`、`quota.error` 按源降级、「可看图」为空是「读不到」等接口侧含义，那份表指到 [AGNES-API.md](./AGNES-API.md) 与 [ADR.md](./ADR.md)，不在此重复。
+
+### 6.1 查这台机器的开关生效值（doctor）
+
+provider / 出图 / 视频 / AgnesCode 四个开关的生效值存在插件私有状态文件里（`$DSH_HOME/state/<name>/`），不在任何配置或路由上；`npm run doctor` 只读状态文件、不碰凭据，Host 没起也能跑：
+
+```powershell
+npm run doctor          # 人读：每个 profile 的 provider / draw / video / agnescode 开关与模型清单
+npm run doctor:json     # 机器读：JSON（可进你的巡检 / 工单脚本）
+```
+
+doctor 的只读范围与实现见 [PITFALLS.md](./PITFALLS.md) §22 与 [ROADMAP.md](./ROADMAP.md) 的落地坐标。

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/agnescode-stats-store.js

@@ -2087,28 +2087,73 @@ function agnescodeRequestHeaders() {
 	return { ...AGNESCODE_BASE_HEADERS };
 }
 /**
-* Whether an AgnesCode roster row accepts image input.
-*
-* AgnesCode's own BFF `/models` rows declare no modality field — only
-* `model_type: "text"` and `supported_endpoint_types` — so the catalogue alone
-* would answer "no vision" for EVERY row (that is why `fetchAgnescodeCatalog`
-* pins `vision: false`). But AgnesCode serves the SAME Agnes model family the
-* Token Plan gateway does (`agnes-3.0-flash` / `agnes-2.5-flash` /
-* `agnes-2.5-pro` all appear in both rosters), whose official docs declare
-* image input — `PROBED_VISION` (llm-models.ts) is that evidence, and the
-* Token Plan side already probed `agnes-3.0-flash` accepting the standard
-* OpenAI `image_url` block live. Non-agnes ids (`deepseek-*` / `glm-*` /
-* `kimi-*`) have no such claim and stay text-only.
-*
-* Resolution order: the row's own `vision` (if the catalogue ever declares
-* one) wins, then `PROBED_VISION` for the Agnes family, then false.
+* Models confirmed on this gateway to CANNOT read an image, in a LIVE probe
+* with the same picture + question the allow side was measured with (a live
+* re-probe runs against this set, so the day a gateway routing change makes a
+* denied model able to see, the baseline turns and the entry comes out).
+* Membership is a dated measurement, never a design call about the model.
+*
+* STARTS EMPTY: nothing about this gateway is known to be blind. An entry is
+* added only when a user reports a model that cannot see the image (with a
+* probe that proves it), and it leaves the same way. Until a report lands
+* here, every untagged row is OFFERED image input by default and labelled
+* unverified — see the companion verdict below.
+* @type {ReadonlySet<string>}
+*/
+const AGNESCODE_VISION_DENYLIST = Object.freeze(/* @__PURE__ */ new Set([]));
+/**
+* Whether an AgnesCode roster row accepts image input, together with how the
+* verdict was reached.
+*
+* The BFF's own `/models` rows declare no modality field (only `model_type:
+* "text"`), so `fetchAgnescodeCatalog` pins `vision: false` — a raw fact about
+* what the wire said, NOT a verdict. The verdict is made here. The ladder is
+* asymmetric on purpose: a false "it can see" (an image sent to a model that
+* ignores it, HTTP 200, no error anywhere upstream) is worse than a hidden
+* capability, so the DEFAULT is to offer the entry but SAY it is unverified,
+* and only a dated live probe may deny it:
+*
+* 1. `AGNESCODE_VISION_DENYLIST` wins: a row confirmed blind in a live probe is
+*    not offered image input; `source: "denied"` tells the panel to draw no chip.
+* 2. A row carrying `vision: true` (a future BFF that starts declaring its own
+*    modality) is `declared`.
+* 3. The `PROBED_VISION` official-docs table (llm-models.ts) — the Agnes family
+*    the platform already proved — is `measured`.
+* 4. Otherwise: `assumed` (true). A model the docs table never mentioned is
+*    still offered image input — it does not vanish from the image picker —
+*    and the panel marks it unverified. Reading "absent from `PROBED_VISION`"
+*    as "text-only" is what made every newly-listed gateway model silently
+*    lose the attachment entry.
 * @param {object} row - one AgnesCode roster row (must carry `id`).
+* @returns {object} the verdict and how it was reached.
+*/
+function agnescodeVisionVerdict(row) {
+	const id = str(row?.id, "");
+	if (id !== "" && AGNESCODE_VISION_DENYLIST.has(id)) return {
+		vision: false,
+		source: "denied"
+	};
+	if (row?.vision === true) return {
+		vision: true,
+		source: "declared"
+	};
+	if (id !== "" && PROBED_VISION[id] === true) return {
+		vision: true,
+		source: "measured"
+	};
+	return {
+		vision: true,
+		source: "assumed"
+	};
+}
+/**
+* The boolean-only view of {@link agnescodeVisionVerdict}, kept for call sites
+* and tests that want the capability bit without the provenance.
+* @param {object} row - one AgnesCode roster row.
 * @returns {boolean} whether the row accepts image input.
 */
 function agnescodeVisionOf(row) {
-	if (row?.vision === true) return true;
-	const id = str(row?.id, "");
-	return PROBED_VISION[id] === true;
+	return agnescodeVisionVerdict(row).vision;
 }
 /**
 * The AgnesCode model rows the panel shows and the adapter offers.
@@ -2128,10 +2173,12 @@ function agnescodeRoster(catalog, maxTokensOverrides) {
 		const multiplier = numZeroOk(row?.multiplier);
 		const maxOutputLength = agnescodeMaxTokensFor(id, row?.maxOutputLength, maxTokensOverrides);
 		const displayLabel = str(row?.displayLabel, "");
+		const verdict = agnescodeVisionVerdict(row);
 		out.push({
 			id,
 			name: str(row?.name, id),
-			vision: agnescodeVisionOf(row),
+			vision: verdict.vision,
+			visionSource: verdict.source,
 			memberOnly: row?.memberOnly === true,
 			...multiplier === void 0 ? {} : { multiplier },
 			...displayLabel === "" ? {} : { displayLabel },

package/lib/index.js

@@ -106,7 +106,7 @@ function throttleDir() {
 * @param {() => number} now - clock source.
 * @returns {{code: string, parked: boolean, until: number|null, attempt: number}|null}
 */
-function parse(raw, now) {
+function parse$1(raw, now) {
 	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
 	const body = raw;
 	const version = num(body.version, 0);
@@ -119,7 +119,7 @@ function parse(raw, now) {
 		};
 		const migrated = migrateToCurrent(body);
 		if (migrated === null) return null;
-		return parse({
+		return parse$1({
 			...migrated,
 			version: THROTTLE_VERSION
 		}, now);
@@ -158,7 +158,7 @@ function createFileThrottleStore({ dir = throttleDir(), now = Date.now } = {}) {
 	const file = join(dir, "throttle.json");
 	return {
 		async read() {
-			return parse(await readStateJson(file), now);
+			return parse$1(await readStateJson(file), now);
 		},
 		async write(state) {
 			const temporary = temporaryOf(dir, "throttle.json");
@@ -201,7 +201,7 @@ function createMemoryThrottleStore(now = Date.now) {
 	let held = null;
 	return {
 		async read() {
-			return parse(held, now);
+			return parse$1(held, now);
 		},
 		async write(state) {
 			held = {
@@ -2260,6 +2260,171 @@ function createFileAgnescodeModelsStore(options = {}) {
 	};
 }
 
+//#endregion
+//#region src/host/agnescode-roster-seen-store.ts
+/**
+* dsh-connect-agnes-token-plan — when each AgnesCode roster id was FIRST seen.
+*
+* WHY this exists (and why it is a separate file, not `agnescode-store.ts`): the
+* gateway's catalogue rows carry no "listed since" fact — the model list is the
+* only signal that "a model is new to this user", and it is knowable only by
+* diffing today's roster against a roster THIS plugin wrote down. In memory
+* would do for one process, but the composer pill has to survive a restart to
+* be worth rendering, so the history lives in a state file of its own (the same
+* discipline as `agnescode-stats-store.ts`: one concern, one file, one reader).
+*
+* Semantics, stated once because two consumers read them:
+*  - the FIRST ever write SEEDS: it stamps the whole roster one window back and
+*    announces nothing new — an upgrade must not tell every existing user the
+*    entire roster is brand new;
+*  - an id that LEAVES the roster is dropped, so a model the gateway re-lists
+*    later counts as new again (a re-listing IS a change the reader may want);
+*  - "new" is a WINDOW, not a tick: an id first seen less than
+*    {@link AGNESCODE_ROSTER_NEW_WINDOW_MS} ago stays new across polls, so the
+*    marker does not vanish between two catalogue reads;
+*  - a roster larger than {@link AGNESCODE_ROSTER_SEEN_MAX_IDS} is a shape
+*    drift: nothing is written or announced for its duration (evicting a live
+*    id would re-announce it next poll and the count would oscillate);
+*  - an unrecognised or foreign-version file reads as "no history" (PITFALLS
+*    §23), but the FIRST write over it is REFUSED, not stomped — the ADR-006
+*    discipline. A caller that cannot write degrades to "no marker", never to a
+*    wrong one.
+*
+* The marker is only fed from a LIVE roster: the static fallback table is this
+* plugin's own text, and diffing it would announce our rows as gateway news.
+*
+* @module dsh-connect-agnes-token-plan/agnescode-roster-seen-store
+*/
+/** Shape version, bumped when the persisted form changes incompatibly. */
+const AGNESCODE_ROSTER_SEEN_VERSION = 1;
+/**
+* How long a first sighting keeps reading as "new". Seven days: long enough that
+* a user who opens the panel twice a week still catches it, short enough that a
+* stale marker cannot outlive the model it announces.
+*/
+const AGNESCODE_ROSTER_NEW_WINDOW_MS = 6048e5;
+/**
+* The largest roster one file will track — a SHAPE-DRIFT guard, not a queue.
+* A roster past the cap is read as a broken/looping producer: NOTHING is
+* written or announced for its duration, and the previous map is kept as-is.
+*/
+const AGNESCODE_ROSTER_SEEN_MAX_IDS = 200;
+/** Where the record lives: the SHARED directory, `$DSH_HOME/state/<plugin>`. */
+function agnescodeRosterSeenDir() {
+	return stateDir(name);
+}
+/**
+* Read one persisted map, keeping only well-formed entries. A non-numeric stamp
+* is dropped rather than coerced (a coerced `0` would read as "seen since 1970"
+* and mark nothing new forever). Never throws.
+* @param {unknown} raw - the persisted or posted value.
+* @returns {Record<string, number>} the usable entries (possibly empty).
+*/
+function normalizeRosterSeen(raw) {
+	const source = raw !== null && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+	const seen = {};
+	for (const [id, stamp] of Object.entries(source)) {
+		if (id === "" || typeof stamp !== "number" || !Number.isFinite(stamp) || stamp <= 0) continue;
+		seen[id] = stamp;
+	}
+	return seen;
+}
+/**
+* Keep the map ONLY while the roster is a sane size: a roster past the cap is a
+* shape drift, so NOTHING is written or announced and the previous map survives.
+* @param {Record<string, number>} next - this round's map.
+* @returns {Record<string, number>|null} the map to persist, or `null` to skip.
+*/
+function bounded(next) {
+	return Object.keys(next).length <= 200 ? next : null;
+}
+/** Is the parsed payload a shape THIS build recognises (a known version)? */
+function parse(raw) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+	const body = raw;
+	if (body.version !== 1) return null;
+	return { seen: normalizeRosterSeen(body.seen) };
+}
+/**
+* The file-backed first-sighting history.
+* @param {object} [options] - `{ dir, now }` (a clock source for the tests).
+* @returns {object} the store.
+*/
+function createFileAgnescodeRosterSeenStore({ dir = agnescodeRosterSeenDir(), now = Date.now } = {}) {
+	const file = join(dir, "agnescode-roster-seen.json");
+	const readThrough = async () => {
+		const raw = await readStateJson(file);
+		return {
+			raw: raw === null ? null : raw,
+			parsed: parse(raw)
+		};
+	};
+	/** Persist one map (atomic). Refuses to stomp a foreign-version file (ADR-006). */
+	const persist = async (seen) => {
+		const { raw } = await readThrough();
+		if (raw !== null && parse(raw) === null) return;
+		const body = JSON.stringify({
+			version: 1,
+			seen,
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		const temporary = temporaryOf(dir, "agnescode-roster-seen.json");
+		await ensureStateDir(dir);
+		await writeStateFile(file, body, { temporary });
+	};
+	return {
+		/** The whole first-sighting map. */
+		async seen() {
+			const { parsed } = await readThrough();
+			return parsed?.seen ?? {};
+		},
+		/** Whether this store has ever written a recognisable history. */
+		async isSet() {
+			const { parsed } = await readThrough();
+			return parsed !== null;
+		},
+		/**
+		* Record today's roster and answer which ids still read as new.
+		* @param {string[]} ids - the FULL live roster as the gateway just listed it.
+		* @param {number} [nowMs] - the clock (tests inject it).
+		* @returns {Promise<{newIds: string[]}>} ids first seen inside the window,
+		*   oldest first; empty on the seeding write and on a roster with nothing fresh.
+		*/
+		async note(ids, nowMs = now()) {
+			const list = Array.isArray(ids) ? ids.filter((id) => typeof id === "string" && id !== "") : [];
+			const unique = [...new Set(list)];
+			if (unique.length === 0) return { newIds: [] };
+			const nowT = Number.isFinite(nowMs) ? nowMs : now();
+			const { raw, parsed } = await readThrough();
+			if (raw !== null && parsed === null) return { newIds: [] };
+			const previous = parsed?.seen ?? {};
+			const next = {};
+			const seeded = parsed === null && raw === null;
+			for (const id of unique) {
+				const first = previous[id];
+				next[id] = typeof first === "number" && first > 0 ? Math.min(first, nowT) : seeded ? nowT - AGNESCODE_ROSTER_NEW_WINDOW_MS : nowT;
+			}
+			const trimmed = bounded(next);
+			if (trimmed === null) return { newIds: [] };
+			if (seeded || Object.keys(previous).length !== Object.keys(trimmed).length || Object.keys(trimmed).some((id) => previous[id] !== trimmed[id])) await persist(trimmed);
+			return { newIds: seeded ? [] : Object.entries(trimmed).filter(([, first]) => nowT - first < AGNESCODE_ROSTER_NEW_WINDOW_MS).sort((left, right) => left[1] - right[1]).map(([id]) => id) };
+		},
+		/** Forget the history (the next `note` reseeds). */
+		async forget() {
+			const { raw } = await readThrough();
+			if (raw !== null && parse(raw) === null) return;
+			const body = JSON.stringify({
+				version: 1,
+				seen: {},
+				updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			const temporary = temporaryOf(dir, "agnescode-roster-seen.json");
+			await ensureStateDir(dir);
+			await writeStateFile(file, body, { temporary });
+		}
+	};
+}
+
 //#endregion
 //#region src/host/switch-precedence.ts
 /**
@@ -5325,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,
@@ -5351,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;
@@ -5378,6 +5549,7 @@ function registerToolSwitchRoute(ctx, { path, label, store, enabledKey, enabledS
 					});
 					return;
 				}
+				commit();
 				await answer();
 				return;
 			}
@@ -5406,6 +5578,7 @@ function registerToolSwitchRoute(ctx, { path, label, store, enabledKey, enabledS
 					});
 					return;
 				}
+				commit();
 				await answer();
 				return;
 			}
@@ -5432,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.
@@ -5454,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.
@@ -5475,7 +5652,8 @@ function registerVideoRoute(ctx, wiring) {
 		modelKey: "videoModelId",
 		modelSourceKey: "videoModelSource",
 		configModelId: settings.videoModelId,
-		allowedHosts: settings.allowedHosts
+		allowedHosts: settings.allowedHosts,
+		mount: wiring.videoToolMount ?? null
 	});
 }
 
@@ -5994,7 +6172,7 @@ function readThroughAgnescode(key, cache, inflight, produce) {
 * @returns {Function} the `off()` unregister callback.
 */
 function registerAgnescodeRoute(ctx, wiring) {
-	const { settings, agnescodeStore, agnescodeSwitch, agnescodePublisher, agnescodeModels, cache, inflight, agnescodeFetch } = wiring;
+	const { settings, agnescodeStore, agnescodeSwitch, agnescodePublisher, agnescodeModels, agnescodeRosterSeen, cache, inflight, agnescodeFetch } = wiring;
 	let lastHarvest = null;
 	let agnescodeHarvestInFlight = null;
 	let agnescodeLoginInFlight = null;
@@ -6067,6 +6245,12 @@ function registerAgnescodeRoute(ctx, wiring) {
 				const publisherState = agnescodePublisher?.state ?? null;
 				const enabledModelIds = agnescodeModels !== null && agnescodeModels !== void 0 ? await agnescodeModels.listEnabledIds().catch(() => []) : [];
 				const { usage, ...rateLimit } = await agnescodeStats.read();
+				let newModelIds;
+				if (liveRoster && agnescodeRosterSeen !== null && agnescodeRosterSeen !== void 0) {
+					const offered = roster.map((r) => r.id).filter((id) => typeof id === "string" && id !== "");
+					const noted = await agnescodeRosterSeen.note(offered);
+					if (noted.newIds.length > 0) newModelIds = noted.newIds;
+				}
 				return {
 					ok: true,
 					enabled: effectiveEnabled,
@@ -6083,6 +6267,7 @@ function registerAgnescodeRoute(ctx, wiring) {
 					models: roster,
 					modelsSource: liveRoster ? "live" : "fallback",
 					...liveRoster ? {} : { modelsAsOf: AGNESCODE_FALLBACK_ASOF },
+					...newModelIds !== void 0 ? { newModelIds } : {},
 					enabledModelIds,
 					providerRegistered: publisherState?.registered === true,
 					...publisherState?.error !== null && publisherState?.error !== void 0 ? { providerError: publisherState.error } : {},
@@ -7384,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`.
@@ -7402,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
@@ -7444,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
@@ -7454,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 () => {
@@ -7499,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,
@@ -7523,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,
@@ -7547,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
@@ -7620,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.
@@ -7640,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 {}
@@ -7760,6 +8030,7 @@ function apply(ctx, config = {}, deps = {}) {
 	const agnescodeStore = createAgnescodeStore({ credentials: () => ctx.get("credentials") ?? null });
 	const agnescodeSwitch = createFileAgnescodeStore({ profile });
 	const agnescodeModels = createFileAgnescodeModelsStore({ profile });
+	const agnescodeRosterSeen = createFileAgnescodeRosterSeenStore();
 	const { publisher: agnescodePublisher, seed: agnescodeSeed } = wireAgnescodePublisher({
 		store: agnescodeStore,
 		panelSwitch: () => agnescodeSwitch.enabled().catch(() => null),
@@ -7806,6 +8077,7 @@ function apply(ctx, config = {}, deps = {}) {
 		agnescodeStore,
 		agnescodeSwitch,
 		agnescodeModels,
+		agnescodeRosterSeen,
 		agnescodePublisher,
 		agnescodeFetch: deps.agnescodeFetch ?? ((url, options) => fetch(url, options))
 	};

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.1",
+  "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",