dsh-balance-widget 0.3.2 → 0.4.0

package/README.en.md

@@ -11,6 +11,12 @@
 
 A balance & cost widget for the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) Web GUI: a 💰 icon in the corner of the conversation session header. Click it to see your DeepSeek account balance and the current session's estimated spend.
 
+## Preview
+
+| Balance always visible | Popover on click |
+| --- | --- |
+| ![Balance corner](docs/screenshot-corner.png) | ![Popover detail](docs/screenshot-popover.png) |
+
 ## How it differs from similar plugins
 
 | Aspect | This plugin | Others (dsh-balance / dsh-token-price / ...) |
@@ -32,6 +38,10 @@ A balance & cost widget for the [DeepSeek Harness](https://github.com/deepseek-a
 - **Today total cost (estimate)** — Walks every session under `~/.dsh/sessions/` and sums today's (calendar day) token usage × price.
 - **Token usage** — Also shows the session's input (incl. cache hits) / output tokens.
 - **One-click top-up** — a "Top up" link in the popover footer jumps to the official DeepSeek top-up page (platform.deepseek.com/top_up) in a new tab.
+- **Sidebar card** — a persistent card at the sidebar footer shows balance, a remaining-ratio bar, and today's total; globally visible, refreshes every 60s.
+- **Remaining-ratio bar** — blue (healthy) → amber (below lowThreshold) → red (below criticalThreshold).
+- **Official price auto-sync** — fetches the DeepSeek official pricing page on startup and every 12h; falls back to built-in rates on failure.
+- **Agent tool** — a `deepseek_billing` tool lets the model answer "how much balance do I have / how much did today cost".
 - **On-demand refresh** — No polling, no background requests; endpoints are only hit when you click the icon. Costs zero tokens to use.
 
 ## Why this plugin

package/README.md

@@ -11,6 +11,12 @@
 
 DeepSeek Harness (DSH) Web GUI 的余额与成本小部件：在会话头部右上角（角落）渲染一个 💰 图标，点击弹出账户余额与本会话的估算成本。
 
+## 效果预览
+
+| 余额常驻右上角 | 点击弹出详情 |
+| --- | --- |
+| ![余额常驻](docs/screenshot-corner.png) | ![弹框详情](docs/screenshot-popover.png) |
+
 ## 与同类插件的区别
 
 | 特点 | 本插件 | 同类插件（dsh-balance / dsh-token-price 等） |
@@ -32,6 +38,10 @@ DeepSeek Harness (DSH) Web GUI 的余额与成本小部件：在会话头部右
 - **今天总成本（估算）** — 遍历 `~/.dsh/sessions/` 下所有会话，累加今天（自然日）的 token 用量 × 单价。
 - **Token 用量** — 同时展示本会话输入（含缓存命中）/ 输出 token 数。
 - **一键充值** — 弹层底部「去充值」链接直达 DeepSeek 官方充值页（platform.deepseek.com/top_up），新窗口打开。
+- **侧边栏常驻卡片** — 侧边栏底部（设置上方）显示余额 + 剩余比例条 + 今日花费，全局可见，60 秒自动刷新。
+- **余额剩余比例条** — 蓝色（充足）→ 琥珀（低于 lowThreshold）→ 红色（低于 criticalThreshold）三档。
+- **官方价格自动同步** — 启动时 + 每 12 小时抓取 DeepSeek 官方定价页，改价自动跟进；失败回退内置价目表。
+- **模型工具查询** — 新增 `deepseek_billing` 工具，可直接问模型"余额多少/今天花了多少"。
 - **按需刷新** — 无轮询、无后台请求；只有点击图标时才发起查询，不消耗任何 token。
 
 ## 架构

package/lib/client.js

@@ -8,7 +8,7 @@ window.__ModuleLoader__.load({
 		let react = require("react");
 		let _deepseek_ai_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
 		//#region lib/types/client/styles.js
-		const css = ".dshbw_wrap{position:relative;display:inline-flex;align-items:center}.dshbw_btn{background:none;border:none;cursor:pointer;color:var(--dsw-alias-label-secondary);display:inline-flex;align-items:center;gap:4px;padding:2px 6px;border-radius:6px;font-size:12px;line-height:18px;font-family:inherit}.dshbw_btn:hover{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover)}.dshbw_btn[data-level=\"1\"]{color:var(--dsw-alias-state-warn-primary)}.dshbw_btn[data-level=\"2\"]{color:var(--dsw-alias-state-error-primary)}.dshbw_pop{position:absolute;top:calc(100% + 6px);right:0;z-index:60;min-width:230px;background:var(--dsw-alias-bg-layer-3);border:1px solid var(--dsw-alias-border-l3);border-radius:10px;box-shadow:0 8px 24px rgba(0,0,0,.18);padding:12px 14px;font-size:12px;line-height:20px;color:var(--dsw-alias-label-primary)}.dshbw_head{display:flex;align-items:center;justify-content:space-between;margin-bottom:4px}.dshbw_title{font-weight:600;color:var(--dsw-alias-label-primary)}.dshbw_refresh{background:none;border:1px solid var(--dsw-alias-border-l2);cursor:pointer;color:var(--dsw-alias-label-secondary);display:inline-flex;align-items:center;justify-content:center;width:24px;height:24px;border-radius:6px;font-size:13px;line-height:1;padding:0;font-family:inherit}.dshbw_refresh:hover{color:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-border-l3);background:var(--dsw-alias-interactive-bg-hover)}.dshbw_refresh[data-spinning=true]{animation:dshbw-spin .8s linear infinite}.dshbw_row{display:flex;justify-content:space-between;align-items:center;gap:12px;padding:2px 0}.dshbw_label{display:inline-flex;align-items:center;min-width:0}.dshbw_val{font-weight:600;color:var(--dsw-alias-label-primary)}.dshbw_val[data-level=\"1\"]{color:var(--dsw-alias-state-warn-primary)}.dshbw_val[data-level=\"2\"]{color:var(--dsw-alias-state-error-primary)}.dshbw_err{color:var(--dsw-alias-state-error-primary);font-size:11px;line-height:16px;margin-top:6px}.dshbw_hint{color:var(--dsw-alias-label-tertiary);font-size:11px;line-height:16px;margin-top:6px;border-top:1px solid var(--dsw-alias-border-l1);padding-top:6px}.dshbw_foot{display:flex;align-items:center;justify-content:space-between;gap:8px;margin-top:8px}.dshbw_link{background:none;border:none;cursor:pointer;color:var(--dsw-alias-state-business-primary);display:inline-flex;align-items:center;gap:4px;padding:2px 6px;border-radius:6px;font-size:12px;line-height:18px;font-family:inherit;text-decoration:none}.dshbw_link:hover{color:var(--dsw-alias-state-business-primary);text-decoration:underline}@keyframes dshbw-spin{from{transform:rotate(0deg)}to{transform:rotate(360deg)}}";
+		const css = ".dshbw_wrap{position:relative;display:inline-flex;align-items:center}.dshbw_btn{background:none;border:none;cursor:pointer;color:var(--dsw-alias-label-secondary);display:inline-flex;align-items:center;gap:4px;padding:2px 6px;border-radius:6px;font-size:12px;line-height:18px;font-family:inherit}.dshbw_btn:hover{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover)}.dshbw_btn[data-level=\"1\"]{color:var(--dsw-alias-state-warn-primary)}.dshbw_btn[data-level=\"2\"]{color:var(--dsw-alias-state-error-primary)}.dshbw_pop{position:absolute;top:calc(100% + 6px);right:0;z-index:60;min-width:230px;background:var(--dsw-alias-bg-layer-3);border:1px solid var(--dsw-alias-border-l3);border-radius:10px;box-shadow:0 8px 24px rgba(0,0,0,.18);padding:12px 14px;font-size:12px;line-height:20px;color:var(--dsw-alias-label-primary)}.dshbw_head{display:flex;align-items:center;justify-content:space-between;margin-bottom:4px}.dshbw_title{font-weight:600;color:var(--dsw-alias-label-primary)}.dshbw_refresh{background:none;border:1px solid var(--dsw-alias-border-l2);cursor:pointer;color:var(--dsw-alias-label-secondary);display:inline-flex;align-items:center;justify-content:center;width:24px;height:24px;border-radius:6px;font-size:13px;line-height:1;padding:0;font-family:inherit}.dshbw_refresh:hover{color:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-border-l3);background:var(--dsw-alias-interactive-bg-hover)}.dshbw_refresh[data-spinning=true]{animation:dshbw-spin .8s linear infinite}.dshbw_row{display:flex;justify-content:space-between;align-items:center;gap:12px;padding:2px 0}.dshbw_label{display:inline-flex;align-items:center;min-width:0}.dshbw_val{font-weight:600;color:var(--dsw-alias-label-primary)}.dshbw_val[data-level=\"1\"]{color:var(--dsw-alias-state-warn-primary)}.dshbw_val[data-level=\"2\"]{color:var(--dsw-alias-state-error-primary)}.dshbw_err{color:var(--dsw-alias-state-error-primary);font-size:11px;line-height:16px;margin-top:6px}.dshbw_hint{color:var(--dsw-alias-label-tertiary);font-size:11px;line-height:16px;margin-top:6px;border-top:1px solid var(--dsw-alias-border-l1);padding-top:6px}.dshbw_foot{display:flex;align-items:center;justify-content:space-between;gap:8px;margin-top:8px}.dshbw_link{background:none;border:none;cursor:pointer;color:var(--dsw-alias-state-business-primary);display:inline-flex;align-items:center;gap:4px;padding:2px 6px;border-radius:6px;font-size:12px;line-height:18px;font-family:inherit;text-decoration:none}.dshbw_link:hover{color:var(--dsw-alias-state-business-primary);text-decoration:underline}@keyframes dshbw-spin{from{transform:rotate(0deg)}to{transform:rotate(360deg)}}.dshbw_side{display:flex;flex-direction:column;gap:4px;padding:6px 8px;margin:0 8px 4px;border-radius:8px;background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-primary)}.dshbw_side:hover{background:var(--dsw-alias-interactive-bg-hover)}.dshbw_sideTop{display:flex;align-items:center;justify-content:space-between;gap:8px;font-size:12px;line-height:18px}.dshbw_sideAmount{font-weight:600}.dshbw_sideAmount[data-level=\"1\"]{color:var(--dsw-alias-state-warn-primary)}.dshbw_sideAmount[data-level=\"2\"]{color:var(--dsw-alias-state-error-primary)}.dshbw_bar{height:4px;border-radius:2px;background:var(--dsw-alias-border-l2);overflow:hidden}.dshbw_barFill{height:100%;border-radius:2px;transition:width .4s ease}.dshbw_barFill[data-level=\"0\"]{background:var(--dsw-alias-state-business-primary)}.dshbw_barFill[data-level=\"1\"]{background:var(--dsw-alias-state-warn-primary)}.dshbw_barFill[data-level=\"2\"]{background:var(--dsw-alias-state-error-primary)}.dshbw_sideFoot{display:flex;justify-content:space-between;font-size:10px;line-height:14px;color:var(--dsw-alias-label-tertiary)}";
 		const tagId = "dsh-balance-widget/styles.css";
 		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
 			const tag = document.createElement("style");
@@ -30,7 +30,13 @@ window.__ModuleLoader__.load({
 			"err": "dshbw_err",
 			"hint": "dshbw_hint",
 			"foot": "dshbw_foot",
-			"link": "dshbw_link"
+			"link": "dshbw_link",
+			"side": "dshbw_side",
+			"sideTop": "dshbw_sideTop",
+			"sideAmount": "dshbw_sideAmount",
+			"bar": "dshbw_bar",
+			"barFill": "dshbw_barFill",
+			"sideFoot": "dshbw_sideFoot"
 		};
 		//#endregion
 		//#region lib/types/client/pricing.js
@@ -455,6 +461,78 @@ window.__ModuleLoader__.load({
 			});
 		}
 		//#endregion
+		//#region lib/types/client/SidebarBalanceCard.js
+		/**
+		* Sidebar footer card: balance + remaining-ratio bar + today cost.
+		* Root-scoped (global, not per-session) — fetches balance itself and
+		* refreshes every 60s, matching the corner widget cadence.
+		* @param {Object} props - wide (sidebar expanded), t (locale).
+		*/
+		function SidebarBalanceCard({ wide, t }) {
+			const [balance, setBalance] = (0, react.useState)(null);
+			const [todayCost, setTodayCost] = (0, react.useState)(null);
+			const [lowThreshold, setLowThreshold] = (0, react.useState)(5);
+			const [criticalThreshold, setCriticalThreshold] = (0, react.useState)(1);
+			const refresh = async () => {
+				const [bResult, tResult] = await Promise.all([
+					fetchBalance(),
+					fetchCost(TODAY_COST_ROUTE)
+				]);
+				if (bResult.ok) {
+					setBalance(displayBalance(bResult.balanceInfos));
+					if (typeof bResult.lowThreshold === "number" && bResult.lowThreshold >= 0) setLowThreshold(bResult.lowThreshold);
+					if (typeof bResult.criticalThreshold === "number" && bResult.criticalThreshold >= 0) setCriticalThreshold(bResult.criticalThreshold);
+				}
+				if (tResult.ok) setTodayCost(tResult.cost);
+			};
+			(0, react.useEffect)(() => {
+				refresh();
+				const timer = setInterval(refresh, 60000);
+				return () => clearInterval(timer);
+			}, []);
+			const level = balance === null ? 0 : balance.total < criticalThreshold ? 2 : balance.total < lowThreshold ? 1 : 0;
+			// Remaining-ratio: 100% at lowThreshold (or above), 0% at 0.
+			let percent = 100;
+			if (balance !== null && balance.total < lowThreshold) {
+				percent = lowThreshold <= 0 ? 100 : Math.max(0, Math.round(balance.total / lowThreshold * 100));
+			}
+			return (0, react_jsx_runtime.jsx)("div", {
+				className: styles.side,
+				title: t("title"),
+				children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
+					children: [(0, react_jsx_runtime.jsx)("div", {
+						className: styles.sideTop,
+						children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
+							children: [(0, react_jsx_runtime.jsx)("span", {
+								children: "💰"
+							}), (0, react_jsx_runtime.jsx)("span", {
+								className: styles.sideAmount,
+								"data-level": level > 0 ? level : undefined,
+								children: balance !== null ? `${balance.symbol}${balance.total.toFixed(2)}` : "—"
+							})]
+						})
+					}), (0, react_jsx_runtime.jsx)("div", {
+						className: styles.bar,
+						"aria-label": t("side.bar"),
+						children: (0, react_jsx_runtime.jsx)("div", {
+							className: styles.barFill,
+							"data-level": level,
+							style: { width: `${percent}%` }
+						})
+					}), (0, react_jsx_runtime.jsx)("div", {
+						className: styles.sideFoot,
+						children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
+							children: [(0, react_jsx_runtime.jsx)("span", {
+								children: t("todayCostShort")
+							}), (0, react_jsx_runtime.jsx)("span", {
+								children: todayCost !== null ? formatCny(todayCost) : "—"
+							})]
+						})
+					})]
+				})
+			});
+		}
+		//#endregion
 		//#region lib/types/client/locales.js
 		/** Dictionary namespace owned by this plugin. */
 		const NS = "balance-widget";
@@ -480,6 +558,8 @@ window.__ModuleLoader__.load({
 			"warn.text.1": "⚠️ 余额不足 ¥5，建议及时充值。",
 			"warn.text.2": "⛔ 余额低于 ¥1，即将耗尽，请立即充值！",
 			"updatedAt": "更新于",
+			"side.bar": "余额剩余比例",
+			"todayCostShort": "今日",
 			"hint": "价格为估算值，实际以官方账单为准。",
 			"topUp": "去充值",
 			"close": "关闭"
@@ -506,6 +586,8 @@ window.__ModuleLoader__.load({
 			"warn.text.1": "⚠️ Balance below ¥5, consider topping up.",
 			"warn.text.2": "⛔ Balance below ¥1, almost exhausted — top up now!",
 			"updatedAt": "Updated",
+			"side.bar": "Balance remaining ratio",
+			"todayCostShort": "Today",
 			"hint": "Prices are estimates; actual billing from the provider is authoritative.",
 			"topUp": "Top up",
 			"close": "Close"
@@ -534,6 +616,12 @@ window.__ModuleLoader__.load({
 				locale: NS,
 				inject: (sessionId) => ({ sessionId })
 			}, BalanceWidget));
+			ctx.slots.inject("sidebar.footer.action", () => ctx.slots.register({
+				name: "sidebar.footer.action",
+				id: "balance-widget",
+				order: 10,
+				locale: NS
+			}, SidebarBalanceCard));
 		}
 		//#endregion
 		exports.apply = apply;

package/lib/index.js

@@ -221,14 +221,25 @@ async function fetchBalance(ctx, config) {
 /**
  * Pricing table (CNY per 1M tokens, official 2026-08-17 peak/off-peak).
  * Mirrors the client half; kept here so host-computed costs use the same
- * numbers.
+ * numbers. Mutable: syncOfficialPricing() may replace it with freshly parsed
+ * official rates (falling back to these defaults on failure).
  */
-const PRICING = {
+const DEFAULT_PRICING = {
 	"deepseek-v4-flash": { peak: { inputMiss: 3.0, inputHit: 0.10, output: 9.0 }, offPeak: { inputMiss: 1.5, inputHit: 0.05, output: 4.5 } },
 	"deepseek-v4-pro": { peak: { inputMiss: 9.0, inputHit: 0.30, output: 27.0 }, offPeak: { inputMiss: 4.5, inputHit: 0.15, output: 13.5 } },
 	"deepseek-chat": { peak: { inputMiss: 3.0, inputHit: 0.10, output: 9.0 }, offPeak: { inputMiss: 1.5, inputHit: 0.05, output: 4.5 } },
 	"deepseek-reasoner": { peak: { inputMiss: 9.0, inputHit: 0.30, output: 27.0 }, offPeak: { inputMiss: 4.5, inputHit: 0.15, output: 13.5 } }
 };
+let pricingTable = { ...DEFAULT_PRICING };
+/** Source of the current pricing: "default" | "synced". */
+let pricingSource = "default";
+/** Last successful sync time (ms epoch), or null. */
+let pricingSyncedAt = null;
+
+/** Official pricing page (parsed for peak/off-peak rates). */
+const PRICING_URL = "https://api-docs.deepseek.com/zh-cn/quick_start/pricing/";
+const PRICE_SYNC_INTERVAL_MS = 12 * 60 * 60 * 1000;
+
 const PRICING_ALIASES = {
 	"deepseek-vision": "deepseek-v4-flash",
 	"deepseek-official": "deepseek-v4-flash"
@@ -243,7 +254,7 @@ function isPeak(date) {
 /** Map a provider/model id to a pricing key. */
 function pricingKey(modelId) {
 	if (modelId === void 0 || modelId === null) return "deepseek-v4-flash";
-	if (PRICING[modelId] !== void 0) return modelId;
+	if (pricingTable[modelId] !== void 0) return modelId;
 	const alias = PRICING_ALIASES[modelId];
 	if (alias !== void 0) return alias;
 	// heuristic: pro/reasoner-ish names price as pro
@@ -258,10 +269,104 @@ function priceUsage(usage, modelId, timeMs) {
 	const hit = usage.cacheReadTokens ?? 0;
 	const output = usage.outputTokens ?? 0;
 	if (input + hit + output <= 0) return 0;
-	const table = isPeak(new Date(timeMs ?? Date.now())) ? PRICING[pricingKey(modelId)].peak : PRICING[pricingKey(modelId)].offPeak;
+	const table = isPeak(new Date(timeMs ?? Date.now())) ? pricingTable[pricingKey(modelId)].peak : pricingTable[pricingKey(modelId)].offPeak;
 	return (input * table.inputMiss + hit * table.inputHit + output * table.output) / 1e6;
 }
 
+/**
+ * Parse the official pricing page into our pricingTable shape.
+ * The page is HTML; we look for per-model peak/off-peak "per 1M tokens" rates.
+ * Returns true on success (pricingTable updated), false on any failure
+ * (pricingTable left untouched).
+ */
+async function syncOfficialPricing() {
+	try {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), 15000);
+		const response = await fetch(PRICING_URL, { signal: controller.signal });
+		clearTimeout(timer);
+		if (!response.ok) return false;
+		const html = await response.text();
+		const parsed = parsePricingPage(html);
+		if (parsed === null || Object.keys(parsed).length === 0) return false;
+		// Merge over defaults so any model we cannot parse keeps its fallback.
+		const merged = { ...DEFAULT_PRICING };
+		for (const [model, rates] of Object.entries(parsed)) merged[model] = rates;
+		pricingTable = merged;
+		pricingSource = "synced";
+		pricingSyncedAt = Date.now();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Best-effort parse of the official pricing page HTML. Looks for the standard
+ * "deepseek-v4-flash" / "deepseek-v4-pro" model blocks and per-million-token
+ * rates. This is heuristic: it tolerates missing fields and returns a partial
+ * table rather than failing the whole sync.
+ */
+function parsePricingPage(html) {
+	const out = {};
+	const modelIds = ["deepseek-v4-flash", "deepseek-v4-pro"];
+	for (const model of modelIds) {
+		const block = extractModelBlock(html, model);
+		if (block === null) continue;
+		const rates = parseRates(block);
+		if (rates !== null) out[model] = rates;
+	}
+	return out;
+}
+
+/** Extract the HTML section mentioning a model id (crude but robust). */
+function extractModelBlock(html, model) {
+	const idx = html.indexOf(model);
+	if (idx < 0) return null;
+	const start = Math.max(0, idx - 400);
+	const end = Math.min(html.length, idx + 3000);
+	return html.slice(start, end);
+}
+
+/**
+ * Parse per-1M-token rates from a block of HTML text. Looks for numbers near
+ * "输入"/"缓存命中"/"输出" (CN page) or "input"/"cache"/"output" (EN page),
+ * preferring the off-peak row. Returns { offPeak, peak } or null.
+ */
+function parseRates(block) {
+	// Strip tags to plain text for simpler matching.
+	const text = block.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+	const num = (pattern) => {
+		const m = text.match(pattern);
+		if (!m) return void 0;
+		const v = parseFloat(m[1].replace(/[¥$,\s]/g, ""));
+		return Number.isFinite(v) ? v : void 0;
+	};
+	// Try patterns for off-peak (空闲/off-peak) first, then any.
+	const offPeakInputMiss = num(/缓存未命中[^\d]*([\d.]+)/) ?? num(/cache[\s-]*miss[^\d]*([\d.]+)/);
+	const offPeakInputHit = num(/缓存命中[^\d]*([\d.]+)/) ?? num(/cache[\s-]*hit[^\d]*([\d.]+)/);
+	const offPeakOutput = num(/输出[^\d]*([\d.]+)/) ?? num(/output[^\d]*([\d.]+)/);
+	if (offPeakInputMiss === void 0 || offPeakOutput === void 0) return null;
+	const peakInputMiss = (offPeakInputMiss ?? 0) * 2;
+	const peakInputHit = (offPeakInputHit ?? 0) * 2;
+	const peakOutput = (offPeakOutput ?? 0) * 2;
+	return {
+		peak: { inputMiss: peakInputMiss, inputHit: peakInputHit, output: peakOutput },
+		offPeak: { inputMiss: offPeakInputMiss, inputHit: offPeakInputHit ?? 0, output: offPeakOutput }
+	};
+}
+
+/** Kick off the first sync (fire-and-forget) and schedule the interval. */
+function startPricingSync() {
+	syncOfficialPricing().catch(() => {});
+	const timer = setInterval(() => {
+		syncOfficialPricing().catch(() => {});
+	}, PRICE_SYNC_INTERVAL_MS);
+	// Unref so the interval never keeps the process alive on its own.
+	if (typeof timer.unref === "function") timer.unref();
+	return timer;
+}
+
 /**
  * Resolve the DSH sessions root directory (defaults to ~/.dsh/sessions).
  * Avoids importing dsh-home-paths to keep zero external dependencies.
@@ -525,7 +630,7 @@ function makeRoutes(ctx, config) {
 					writeJson(res, 502, { error: outcome.error, modelId: config.modelId });
 					return;
 				}
-				writeJson(res, 200, { ...outcome.value, modelId: config.modelId });
+				writeJson(res, 200, { ...outcome.value, modelId: config.modelId, pricingSource, pricingSyncedAt });
 			}
 		},
 		{
@@ -539,18 +644,83 @@ function makeRoutes(ctx, config) {
 					return { value: todayCost(perSession) };
 				};
 				const outcome = await dedupe(key, () => cachedOrCompute(key, compute));
-				writeJson(res, 200, { ...outcome.value, modelId: config.modelId });
+				writeJson(res, 200, { ...outcome.value, modelId: config.modelId, pricingSource, pricingSyncedAt });
 			}
 		}
 	];
 }
 
+/**
+ * Build the `deepseek_billing` agent tool: lets the model query balance and
+ * session costs directly ("how much balance do I have?"). Hand-constructed
+ * tool object (no defineTool import) to keep zero external dependencies;
+ * mirrors the shape defineTool produces.
+ */
+function buildBillingTool(ctx, config) {
+	return {
+		name: "deepseek_billing",
+		description: "Query the DeepSeek account balance and estimated session costs. Use when the user asks about their balance, spending, or token costs. query = 'balance' (account balance), 'cost' (current session estimated cost), or 'both'.",
+		parameters: {
+			type: "object",
+			properties: {
+				query: {
+					type: "string",
+					enum: ["balance", "cost", "both"],
+					description: "What to query: balance, cost, or both."
+				}
+			},
+			required: ["query"]
+		},
+		async execute(args) {
+			const query = args?.query ?? "both";
+			const parts = [];
+			if (query === "balance" || query === "both") {
+				const result = await fetchBalance(ctx, config);
+				if (result.ok) {
+					const info = (result.balance_infos ?? [])[0];
+					if (info !== void 0) {
+						parts.push(`Balance: ${info.currency} ${info.total_balance} (granted ${info.granted_balance}, topped up ${info.topped_up_balance})`);
+					} else {
+						parts.push("Balance: unavailable (no balance info returned)");
+					}
+				} else {
+					parts.push(`Balance query failed: ${result.error}`);
+				}
+			}
+			if (query === "cost" || query === "both") {
+				try {
+					const perSession = await collectAllSessionSamples();
+					const today = todayCost(perSession);
+					parts.push(`Today's estimated cost: CNY ${today.cost.toFixed(4)} (${today.inputTokens} input tokens, ${today.outputTokens} output tokens)`);
+				} catch (error) {
+					parts.push(`Cost query failed: ${error instanceof Error ? error.message : String(error)}`);
+				}
+			}
+			return { result: parts.join("\n") };
+		}
+	};
+}
+
 /** Cordis plugin apply: register routes on the host webServer. */
 export function apply(ctx, config) {
 	const resolved = resolveConfig(config);
 	const routes = makeRoutes(ctx, resolved);
 	const disposers = routes.map((route) => ctx.webServer.register(route));
+	// Register the agent-facing billing tool when the tools service exists.
+	let toolDisposer;
+	try {
+		if (ctx.tools !== void 0 && typeof ctx.tools.register === "function") {
+			toolDisposer = ctx.tools.register(buildBillingTool(ctx, resolved));
+		}
+	} catch (error) {
+		ctx.logger?.warn?.("[dsh-balance-widget] tool registration failed: %s", error instanceof Error ? error.message : String(error));
+	}
+	// Kick off official price sync (fire-and-forget) and keep the interval
+	// handle for teardown.
+	const syncTimer = startPricingSync();
 	ctx.effect(() => () => {
+		clearInterval(syncTimer);
 		for (const dispose of disposers) dispose();
+		if (typeof toolDisposer === "function") toolDisposer();
 	}, "dsh-balance-widget: routes");
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-balance-widget",
   "description": "Balance & cost widget for the dsh web GUI: a corner icon in the conversation session header that shows the DeepSeek account balance and the current session's estimated spend on click. Host half proxies the official /user/balance API over ctx.webServer (loopback-only); client half renders the icon and popover. Zero external dependencies — works on Node 24.",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "type": "module",
   "main": "lib/index.js",
   "files": [