@kenz1117/dsh-ui-usage-billing 1.6.7 → 1.7.0

package/lib/index.js

@@ -338,7 +338,8 @@ function isBeijingWeekend(timeMs) {
 *
 * 编码为空格分隔的 `YYYYMMDD` 列表（按年分组、同年日期连续排列，便于逐年追加）：
 * 每个键长度固定为 8，故 `includes` 不会跨键误匹配；相比「区间 + 运行时展开」
-* 省掉一段解析代码——client / index 两个 face 都要过 256 KiB 单文件上限。
+* 省掉一段解析代码——client / index 两个 face 都要过本仓自设的体积成本线
+* （sync.sh 的 256/320 KiB；DSH Store 对插件 JS bundle 本身无审查上限）。
 */
 const CHINA_HOLIDAYS = "20260925 20260926 20260927 20261001 20261002 20261003 20261004 20261005 20261006 20261007";
 /** 北京日期键 YYYYMMDD（与宿主时区无关）。 */
@@ -3558,6 +3559,7 @@ function createUsageAggregator(persistence, options = {}) {
 	let ledgerNeedsSave = false;
 	let lastLedgerSaveAt = 0;
 	const unreadable = /* @__PURE__ */ new Map();
+	const titleHints = /* @__PURE__ */ new Map();
 	let inflight;
 	let ledgerAppliedMigrations;
 	let lastDoc;
@@ -3590,6 +3592,7 @@ function createUsageAggregator(persistence, options = {}) {
 	const foldFingerprintOf = (registered, routes) => configFingerprint(subscriptionMatcher, officialProviderIds, routeAliases, searchEstimate, options.modelKeyAliases, registered, routeOriginsOf(routes));
 	let foldFingerprint = foldFingerprintOf(/* @__PURE__ */ new Set(), {});
 	const FOLD_CHUNK_EVENTS = 8e3;
+	const FOLD_YIELD_SESSIONS = 8;
 	/** 惰性失效（价目表时序）：账本/缓存行若以「当时不可计价」的模型落盘，
 	*  而价目表现在能计价了，该行必须重折——否则显示层按实时价算出的
 	*  「目录价预估」与服务端 cost=0 并存，出现「明细比总额高」的双口径
@@ -3692,7 +3695,10 @@ function createUsageAggregator(persistence, options = {}) {
 		let formatUnreadable = 0;
 		let noLedgerUnreadable = 0;
 		let staleLedgerSessions = 0;
-		for (const meta of metas) {
+		for (const [metaIndex, meta] of metas.entries()) {
+			if (metaIndex > 0 && metaIndex % FOLD_YIELD_SESSIONS === 0) await new Promise((resolve) => {
+				setImmediate(resolve);
+			});
 			const id = String(meta.id);
 			seen.add(id);
 			const stamp = await stampOf(meta);
@@ -3798,8 +3804,13 @@ function createUsageAggregator(persistence, options = {}) {
 					stamp,
 					format
 				});
+				if (options.resolveSessionTitle !== void 0) {
+					const hint = options.resolveSessionTitle(meta);
+					if (hint !== void 0) titleHints.set(id, hint);
+				}
 				console.warn("[usage-billing] skip unreadable session", id, error);
 			}
+			if (included.has(id)) titleHints.delete(id);
 		}
 		for (const key of [...cache.keys()]) if (!seen.has(key)) cache.delete(key);
 		for (const key of [...unreadable.keys()]) if (!seen.has(key)) unreadable.delete(key);
@@ -3813,12 +3824,17 @@ function createUsageAggregator(persistence, options = {}) {
 				if (included.has(entry.id)) continue;
 				try {
 					const stale = (entry.foldVersion ?? 1) < 23 || entry.fingerprint !== foldFingerprint;
+					const fold = deserializedFoldOf(entry.fold);
+					const hint = titleHints.get(entry.id);
 					folds.push({
 						id: entry.id,
 						...entry.cwd === void 0 ? {} : { cwd: entry.cwd },
 						...entry.subOf === void 0 ? {} : { subOf: entry.subOf },
 						...stale ? { staleLedger: true } : {},
-						fold: deserializedFoldOf(entry.fold)
+						fold: hint === void 0 ? fold : {
+							...fold,
+							title: hint
+						}
 					});
 					included.add(entry.id);
 					if (stale) staleLedgerSessions += 1;
@@ -4055,6 +4071,9 @@ function createUsageAggregator(persistence, options = {}) {
 		async flush() {
 			if (inflight !== void 0) await inflight.catch(() => {});
 			await saveLedger(true);
+		},
+		lastDocOf() {
+			return lastDoc;
 		}
 	};
 }
@@ -7296,8 +7315,9 @@ function registerPricingRoutes(ctx, deps) {
 * TokenHub 等）+ 用户自定义余额 + 声明端点 + 余额差对账。5 分钟缓存（避免
 * 每 30s 后台轮询打上游），in-flight 去重（并发请求共享同一次进行中的刷新）。
 *
-* 路由文件只关心 HTTP 缓存逻辑：5 分钟过期判定 + 失败时仍发旧缓存（不挂起
-* 已 writeHead 的响应）。上游查询（queryBalances / queryCustomBalances /
+* 路由文件只关心 HTTP 缓存逻辑：5 分钟过期判定 + 刷新预算（超预算回旧
+* 缓存并标 stale，不把响应挂在长查询上）+ 失败时仍发旧缓存（不挂起已
+* writeHead 的响应）。上游查询（queryBalances / queryCustomBalances /
 * queryDeclaredEndpoints / reconcileBalanceDelta）在装配器里跑，路由只通过
 * `cached()` 与 `refreshOnce()` 拿到结果。
 */
@@ -7312,12 +7332,21 @@ function registerBalanceRoute(ctx, deps) {
 				res.end(JSON.stringify(deps.cached().doc));
 				return;
 			}
-			try {
-				await deps.refreshOnce();
-			} catch (error) {
+			let timedOut = false;
+			const onFailure = (error) => {
 				console.warn("[usage-billing] refreshBalances failed; serving cached balances:", error);
-			}
-			res.end(JSON.stringify(deps.cached().doc));
+			};
+			await Promise.race([deps.refreshOnce().then(() => void 0, onFailure), new Promise((resolve) => {
+				setTimeout(() => {
+					timedOut = true;
+					resolve();
+				}, deps.responseBudgetMs).unref();
+			})]);
+			const doc = deps.cached().doc;
+			res.end(JSON.stringify(timedOut ? {
+				...doc,
+				stale: true
+			} : doc));
 		}
 	}), "usage-billing: balance route");
 }
@@ -7422,12 +7451,19 @@ function registerSubscriptionsRoute(ctx, deps) {
 		handler: async (req, res) => {
 			if (!guardLoopback(req, res, deps.trustedHosts)) return;
 			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
-			if (Date.now() - deps.cached().at >= deps.cacheMs) try {
-				await deps.refreshOnce();
-			} catch (error) {
+			let timedOut = false;
+			if (Date.now() - deps.cached().at >= deps.cacheMs) await Promise.race([deps.refreshOnce().then(() => void 0, (error) => {
 				console.warn("[usage-billing] refreshQuotas failed; serving cached quotas:", error);
-			}
-			res.end(JSON.stringify({ quotas: deps.cached().quotas }));
+			}), new Promise((resolve) => {
+				setTimeout(() => {
+					timedOut = true;
+					resolve();
+				}, deps.responseBudgetMs).unref();
+			})]);
+			res.end(JSON.stringify({
+				quotas: deps.cached().quotas,
+				...timedOut ? { stale: true } : {}
+			}));
 		}
 	}), "usage-billing: subscriptions route");
 }
@@ -7450,11 +7486,15 @@ function registerRelayQuotasRoute(ctx, deps) {
 		handler: async (req, res) => {
 			if (!guardLoopback(req, res, deps.trustedHosts)) return;
 			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
-			if (Date.now() - deps.cached().at >= deps.cacheMs) try {
-				await deps.refreshOnce();
-			} catch (error) {
+			let timedOut = false;
+			if (Date.now() - deps.cached().at >= deps.cacheMs) await Promise.race([deps.refreshOnce().then(() => void 0, (error) => {
 				console.warn("[usage-billing] refreshRelay failed; serving cached relay quotas:", error);
-			}
+			}), new Promise((resolve) => {
+				setTimeout(() => {
+					timedOut = true;
+					resolve();
+				}, deps.responseBudgetMs).unref();
+			})]);
 			const diagnostics = deps.cached().quotas.map((row) => ({
 				route: row.route,
 				origin: row.origin,
@@ -7462,7 +7502,8 @@ function registerRelayQuotasRoute(ctx, deps) {
 			}));
 			res.end(JSON.stringify({
 				quotas: deps.cached().quotas,
-				diagnostics
+				diagnostics,
+				...timedOut ? { stale: true } : {}
 			}));
 		}
 	}), "usage-billing: relay-quotas route");
@@ -7617,10 +7658,21 @@ function registerUsageStatsRoute(ctx, deps) {
 				res.end(statsBodyOf(fresh));
 				return;
 			}
+			const recent = deps.lastDoc?.();
+			if (recent !== void 0) {
+				res.end(JSON.stringify({
+					...decorate(recent),
+					staleSnapshot: true
+				}));
+				return;
+			}
 			for (const candidate of deps.candidates) {
 				const doc = await deps.readSnapshot(candidate);
 				if (doc === null) continue;
-				res.end(JSON.stringify(decorate(doc)));
+				res.end(JSON.stringify({
+					...decorate(doc),
+					staleSnapshot: true
+				}));
 				return;
 			}
 			res.end(JSON.stringify({ error: "usage stats unavailable" }));
@@ -7693,6 +7745,24 @@ const WARMUP_DELAY_MS = 3e3;
 /** 订阅套餐额度缓存时长（毫秒）：上游配额 API 低频变化，5 分钟足够。 */
 const SUBSCRIPTION_CACHE_MS = 3e5;
 const BALANCE_CACHE_MS = 3e5;
+/**
+* 余额路由的总等待预算（毫秒）：超预算立刻回上一次成功的余额（stale 标记），
+* 刷新在后台继续。取 8s——与上游单次查询超时（FETCH_TIMEOUT_MS）对齐：上游
+* 真的不可达时多等没有意义，先把响应还给浏览器，别占着同源连接（issue #104）。
+*/
+const BALANCE_RESPONSE_BUDGET_MS = 8e3;
+/**
+* 订阅 / 中转站额度路由的总等待预算（毫秒）：与余额路由同口径（issue #104）。
+* 上游额度接口不可达时（8s 超时 × 重试 ≈ 10~16s），响应被长期挂住会占满浏览器
+* 的同源连接池——多标签页各挂一条即让宿主自己的资源请求排队，界面整体卡死。
+*/
+const QUOTA_RESPONSE_BUDGET_MS = 8e3;
+/**
+* 对账基线的最大可用年龄（毫秒）：超过则「今日官方费用」偏小，用它对账会
+* 报假漂移——此时跳过本轮对账，等后台补算完成后再恢复（issue #104）。
+* 取 5 分钟：与 usage-stats 的 30s 轮询 + 5 分钟快照节流同一量级。
+*/
+const RECONCILE_BASIS_MAX_AGE_MS = 3e5;
 /** DeepSeek 余额查询的默认凭据引用（与 llm-deepseek 的默认引用一致）。 */
 const DEFAULT_BALANCE_API_KEY_ENV = "DEEPSEEK_API_KEY";
 /**
@@ -7932,6 +8002,48 @@ function buildWorkspaceTitleResolver(ctx) {
 	};
 }
 /**
+* 构造「会话头 → 宿主侧会话标题」解析器（issue #103，可选依赖）。
+*
+* 插件的会话标题取自日志里的 `session/title` 事件——**日志读不动**时（宿主拒绝
+* 该格式/代际，插件折叠失败），只能吃账本旧行，标题会永远停在重命名前的值。
+* 宿主自己的会话投影缓存仍可能记得这个标题（`cachedSnapshot` / 既有能力
+* `cachedPredecessorTitle`：格式代际边缘的标题仍能跨边缘存活），用它兜底可让
+* 账单明细的标题跟随工作区。
+*
+* 宿主没有该服务（0.1.x 代际）或读取失败都返回 undefined：绝不抛错，行为与
+* 现状一致（可选依赖，不影响主流程）。
+* @param ctx - host context carrying the optional session projection cache.
+* @returns 标题解析函数；服务不可用时 undefined。
+*/
+function buildSessionTitleResolver(ctx) {
+	let cache;
+	try {
+		cache = ctx.get("sessionProjectionCache");
+	} catch {
+		return;
+	}
+	if (cache === void 0) return void 0;
+	const titleOf = (values) => {
+		const title = values?.title;
+		return typeof title === "string" && title !== "" ? title : void 0;
+	};
+	const cachedSnapshot = cache.cachedSnapshot;
+	const cachedPredecessorTitle = cache.cachedPredecessorTitle;
+	if (typeof cachedSnapshot !== "function" && typeof cachedPredecessorTitle !== "function") return void 0;
+	return (header) => {
+		try {
+			if (typeof cachedSnapshot === "function") {
+				const title = titleOf(cachedSnapshot(header, ["title"])?.values);
+				if (title !== void 0) return title;
+			}
+			if (typeof cachedPredecessorTitle === "function") return titleOf(cachedPredecessorTitle(header)?.values);
+			return;
+		} catch {
+			return;
+		}
+	};
+}
+/**
 * 凭据 seam 的宽容解析：ref 名 → 非空值；失败/缺失返回 undefined（多 surface 共用，
 * 失败按结构化静默记录）。
 */
@@ -8086,6 +8198,7 @@ function apply(ctx, config = {}) {
 		}).catch(() => {});
 	};
 	const workspaceTitleResolver = buildWorkspaceTitleResolver(ctx);
+	const sessionTitleResolver = buildSessionTitleResolver(ctx);
 	applyBuiltinCatalog(BUILTIN_MODEL_CATALOG, BUILTIN_MODEL_KEY_ALIASES);
 	applyUserModelAliases(config.modelKeyAliases);
 	let llmRegistryWarned = false;
@@ -8119,6 +8232,7 @@ function apply(ctx, config = {}) {
 		resolveRegisteredProviders: registeredProvidersOf,
 		...config.modelKeyAliases === void 0 ? {} : { modelKeyAliases: config.modelKeyAliases },
 		...workspaceTitleResolver === void 0 ? {} : { resolveWorkspaceTitle: workspaceTitleResolver },
+		...sessionTitleResolver === void 0 ? {} : { resolveSessionTitle: sessionTitleResolver },
 		...config.searchCallEstimateCny === void 0 ? {} : { searchCallEstimateCny: config.searchCallEstimateCny },
 		ledger: ledgerStore
 	});
@@ -8414,21 +8528,22 @@ function apply(ctx, config = {}) {
 		if (official !== void 0 && reconcilable) {
 			const now = Date.now();
 			const today = dayStamp(now);
-			let todayOfficialCost = 0;
-			try {
-				todayOfficialCost = (await aggregator.aggregate()).byDay[today]?.officialCost ?? 0;
-			} catch {
-				swallowed("reconcile-aggregate-skipped");
+			const recent = aggregator.lastDocOf();
+			if (recent !== void 0 && now - recent.updatedAt <= RECONCILE_BASIS_MAX_AGE_MS) {
+				const todayOfficialCost = recent?.byDay[today]?.officialCost ?? 0;
+				const result = reconcileBalanceDelta(reconcileRef, official, todayOfficialCost, today, now);
+				const refChanged = result.ref !== null && result.ref !== reconcileRef;
+				reconcileRef = result.ref;
+				if (result.event !== null && result.event.kind !== "flat") reconcile = {
+					...result.event,
+					provider: official.displayName,
+					...official.currency === void 0 ? {} : { currency: official.currency }
+				};
+				if (refChanged) persistReconcileRef();
+			} else {
+				aggregator.aggregate().catch(() => {});
+				swallowed("reconcile-basis-stale");
 			}
-			const result = reconcileBalanceDelta(reconcileRef, official, todayOfficialCost, today, now);
-			const refChanged = result.ref !== null && result.ref !== reconcileRef;
-			reconcileRef = result.ref;
-			if (result.event !== null && result.event.kind !== "flat") reconcile = {
-				...result.event,
-				provider: official.displayName,
-				...official.currency === void 0 ? {} : { currency: official.currency }
-			};
-			if (refChanged) persistReconcileRef();
 		}
 		const doc = {
 			balances: [
@@ -8453,7 +8568,8 @@ function apply(ctx, config = {}) {
 		trustedHosts,
 		cached: () => balanceCache,
 		refreshOnce: refreshBalanceOnce,
-		cacheMs: BALANCE_CACHE_MS
+		cacheMs: BALANCE_CACHE_MS,
+		responseBudgetMs: BALANCE_RESPONSE_BUDGET_MS
 	});
 	registerUsageToolRoute(ctx, {
 		trustedHosts,
@@ -8513,7 +8629,8 @@ function apply(ctx, config = {}) {
 		trustedHosts,
 		cached: () => quotaCache,
 		refreshOnce: refreshQuotasOnce,
-		cacheMs: SUBSCRIPTION_CACHE_MS
+		cacheMs: SUBSCRIPTION_CACHE_MS,
+		responseBudgetMs: QUOTA_RESPONSE_BUDGET_MS
 	});
 	let relayCache = {
 		at: 0,
@@ -8552,7 +8669,8 @@ function apply(ctx, config = {}) {
 		trustedHosts,
 		cached: () => relayCache,
 		refreshOnce: refreshRelayOnce,
-		cacheMs: SUBSCRIPTION_CACHE_MS
+		cacheMs: SUBSCRIPTION_CACHE_MS,
+		responseBudgetMs: QUOTA_RESPONSE_BUDGET_MS
 	});
 	registerUsageStatsRoute(ctx, {
 		trustedHosts,
@@ -8562,7 +8680,8 @@ function apply(ctx, config = {}) {
 		persistSnapshot,
 		readSnapshot,
 		packageVersion: PACKAGE_VERSION,
-		responseBudgetMs: RESPONSE_BUDGET_MS
+		responseBudgetMs: RESPONSE_BUDGET_MS,
+		lastDoc: () => aggregator.lastDocOf()
 	});
 }
 //#endregion

package/lib/types/aggregate.d.ts

@@ -164,6 +164,15 @@ export interface AggregateOptions {
     /** 工作区标题解析：给定会话 cwd 返回项目显示标题；undefined = 回退到 cwd 末级目录名
      *  （host 的 workspaceRegistry 为可选依赖，缺失时不注入，行为保持不变）。 */
     resolveWorkspaceTitle?: (cwd: string) => string | undefined;
+    /**
+     * 会话标题兜底解析：给定会话头（宿主持久层列表元数据）返回宿主侧的会话标题。
+     *
+     * 只在**日志读不动**的会话上用（宿主拒绝该格式/代际，插件折叠失败）：此时插件
+     * 只能吃账本里的旧行，标题会永远停在重命名前的值——宿主自己的投影缓存仍可能
+     * 记得这个标题（格式代际边缘的既定能力），用它兜底可让标题跟随工作区
+     * （issue #103）。读得动的会话一律以日志为准，本回调不参与。
+     */
+    resolveSessionTitle?: (header: SessionHeader) => string | undefined;
     /** 独立的持久用量账本。启用后，已经成功折叠过的会话即使随后从
      *  sessionPersistence 中永久删除，也会继续计入累计用量。 */
     ledger?: UsageLedgerStore;
@@ -735,6 +744,16 @@ export interface UsageAggregator {
      * @returns 会话累计；日志与账本均无该会话时 undefined（调用方自行兜底）。
      */
     sessionUsageOf(sessionId: string): Promise<SessionUsageSummary | undefined>;
+    /**
+     * 最近一次**已完成**的聚合文档（不触发新的折叠）。
+     *
+     * 供路由的 stale-while-revalidate 兜底用：当本轮折叠超过响应预算（宿主单进程
+     * 事件循环被重活折叠占住）时，落盘快照最多落后一个节流窗口（分钟级），而这里
+     * 的内存文档只落后一个聚合周期——两者都是「上次算好的」，但内存那份更新。
+     * 从未完成过一次聚合时返回 undefined（调用方回落到磁盘快照）。
+     * @returns 最近一次完成的聚合文档；尚无完成聚合时 undefined。
+     */
+    lastDocOf(): UsageStatsDocument | undefined;
     /** 立刻落盘未保存的账本改动（无视节流），供插件卸载时调用；
      *  进行中的聚合先等完再存，折叠失败仍保存已成功部分。 */
     flush(): Promise<void>;

package/lib/types/client/api/balance.d.ts

@@ -5,16 +5,20 @@
 import type { ProviderBalance, ReconcileNotice } from '../../pricing-shared.ts';
 /** Path to the account-balance endpoint served by this plugin's node half. */
 export declare const BALANCE_PATH = "/api/billing/balance";
+/** 余额文档（服务端响应体的白名单切片）。 */
+export interface BalanceDocSlice {
+    balances: readonly ProviderBalance[];
+    reconcile?: ReconcileNotice;
+    /** 服务端刷新超预算：本次余额来自上一次成功的查询（issue #104）。 */
+    stale?: boolean;
+}
 /**
  * 一次拉取 `/api/billing/balance` 的完整响应（余额行 + 对账提示）。余额与对账
  * 提示来自同一响应体，拆成两个函数会导致每 30 秒对同一端点发两次请求，故合并
  * 为单次 fetch；失败返回空值（余额 []、对账 undefined），由调用方降级。
  * @returns the balances and reconcile notice (both degraded on any failure).
  */
-export declare function fetchBalanceDoc(): Promise<{
-    balances: readonly ProviderBalance[];
-    reconcile?: ReconcileNotice;
-}>;
+export declare function fetchBalanceDoc(): Promise<BalanceDocSlice>;
 /**
  * 拉取官方余额差对账提示（drift 时非空），供余额面板展示；失败返回 undefined。
  * 复用 {@link fetchBalanceDoc} 的同一响应，导出供对账提示渲染测试单独解析。

package/lib/types/client/api/http.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 插件自有端点（/api/billing/*）的统一取数封装：超时底座。
+ *
+ * 背景（issue #104）：浏览器对同源最多 6 条并发连接，而旧实现里所有 fetch
+ * 都没有超时——服务端某次响应被上游查询拖住（报告者实测 45~60s）时，这条
+ * 连接会被长期占住；多标签页各挂一条即占满连接池，宿主自己的资源请求排队，
+ * 用户看到的是「整个 DSH 界面卡死」。
+ *
+ * 超时上限必须小于轮询间隔（30s），否则「超时中的请求」会与下一轮轮询重叠，
+ * 在途请求越堆越多。
+ */
+/**
+ * 客户端取插件端点的默认超时（毫秒）：小于 30s 轮询间隔，保证不与下一轮重叠。
+ *
+ * 取 12s：服务端三条轮询路由的总预算都是 8s（余额 / 订阅额度 / 中转站额度），
+ * usage-stats 是 1.5s——12s 给服务端留了 4s 余量，又远小于 30s 的轮询间隔，
+ * 超时的请求不会与下一轮重叠（issue #104 报告者建议值同为 12s）。
+ */
+export declare const BILLING_FETCH_TIMEOUT_MS = 12000;
+/** 取数选项：在标准 RequestInit 之上加一个超时覆盖。 */
+export interface BillingFetchInit extends RequestInit {
+    /** 超时（毫秒）；缺省 {@link BILLING_FETCH_TIMEOUT_MS}。 */
+    timeoutMs?: number;
+}
+/**
+ * 带超时的 fetch（插件端点专用）。
+ *
+ * 超时以 AbortController 实现（不用 AbortSignal.timeout）：宿主 UI 跑在
+ * 浏览器里，但插件的客户端代码也会被测试与宿主内嵌环境加载，显式
+ * AbortController 在任何实现上都可用。
+ * @param path - 端点路径（相对当前源）。
+ * @param init - 请求选项；`timeoutMs` 覆盖默认超时，`signal` 透传外部取消。
+ * @returns the response; rejects when the request times out or fails.
+ */
+export declare function fetchBilling(path: string, init?: BillingFetchInit): Promise<Response>;
+//# sourceMappingURL=http.d.ts.map

package/lib/types/client/api/subscriptions.d.ts

@@ -5,9 +5,15 @@
 import type { SubscriptionQuota } from '../../pricing-shared.ts';
 /** Path to the subscription-plan quota endpoint served by this plugin's node half. */
 export declare const SUBSCRIPTIONS_PATH = "/api/billing/subscriptions";
+/** 订阅额度响应（白名单切片）。 */
+export interface SubscriptionsDoc {
+    quotas: readonly SubscriptionQuota[];
+    /** 服务端刷新超预算：额度来自上一次成功的查询（issue #104）。 */
+    stale?: boolean;
+}
 /**
  * 拉取订阅套餐剩余额度（供订阅面板）；失败返回空列表。
  * @returns the quota rows, or an empty list on any failure.
  */
-export declare function fetchSubscriptions(): Promise<readonly SubscriptionQuota[]>;
+export declare function fetchSubscriptions(): Promise<SubscriptionsDoc>;
 //# sourceMappingURL=subscriptions.d.ts.map

package/lib/types/client/context-store.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 上下文占用快照 store：把宿主的 token-meter 投影从**会话作用域**搬到全局弹窗。
+ *
+ * 宿主能力（@deepseek-ai/dsh-token-meter，经会话作用域标准 props 的 useProjection 读）：
+ * - `contextPressure`：{ pressureTokens?, projectedTokens?, contextWindow? }
+ *   —— provider 上报的最近一次提示词占用、下一次请求的占用外推、路由容量上限。
+ * - `contextBreakdown`：{ systemTokens, toolsTokens, messageTokens }
+ *   —— 下一次请求上下文的构成拆解（**启发式 token 估算**，三项之和不等于
+ *   provider 锚定的 projectedTokens：估算器系统性低估 CJK 与 JSON schema）。
+ *
+ * 为什么需要这个 store：`contextPressure` / `contextBreakdown` 只在**会话作用域**
+ * 的槽位里可读（投影按会话分发），而仪表盘弹窗是全局的——侧边栏触发的弹窗不在
+ * 任何会话作用域内。解法：会话作用域里已有的即时代费用条（conversation.composer.dock
+ * 座位）顺手读一次投影并发布到本 store，弹窗订阅它。
+ *
+ * 降级：没有会话 / 宿主不提供该投影 / 老宿主没有 token-meter → store 保持空，
+ * 界面整块隐藏（**不显示 0、不显示占位假数据**）。
+ */
+/** 上下文占用快照（两个投影的合并视图）。 */
+export interface ContextOccupancy {
+    /** 下一次请求的提示词占用（provider 锚定 + 增量外推）——面板主指标。 */
+    projectedTokens?: number;
+    /** 最近一次请求的提示词占用（provider 上报值）。 */
+    pressureTokens?: number;
+    /** 路由容量（上下文窗口上限）；适配器未上报时缺席。 */
+    contextWindow?: number;
+    /** 系统提示词占用（启发式估算）。 */
+    systemTokens?: number;
+    /** 工具 schema 占用（启发式估算）。 */
+    toolsTokens?: number;
+    /** 消息占用（启发式估算）。 */
+    messageTokens?: number;
+}
+/** 空快照：无数据（界面据此整块隐藏）。 */
+export declare const EMPTY_CONTEXT: ContextOccupancy;
+/** 上下文 store：写入方 = 会话作用域的费用条；读取方 = 全局仪表盘弹窗。 */
+export interface ContextStore {
+    /** 发布新快照（内容未变时保持同一对象引用，避免无谓重渲染）。 */
+    publish(next: ContextOccupancy): void;
+    /** 订阅变更；立即收到当前值一次（若为空则收到 undefined）。 */
+    subscribe(listener: (value: ContextOccupancy | undefined) => void): () => void;
+    /** 读取当前快照（无数据返回 undefined）。 */
+    read(): ContextOccupancy | undefined;
+}
+/**
+ * 创建上下文 store。
+ * @returns store 实例。
+ */
+export declare function createContextStore(): ContextStore;
+/**
+ * 占用率（0..1）：以外推占用除以窗口容量。
+ * 缺任一要素 → undefined（界面不画进度，不以 0 冒充）。
+ * @param occupancy - 占用快照。
+ * @returns 占用率或 undefined。
+ */
+export declare function occupancyRatio(occupancy: ContextOccupancy | undefined): number | undefined;
+/**
+ * 构成拆解的三项（顺序固定，便于渲染与比较）。
+ * @param occupancy - 占用快照。
+ * @returns 构成项数组（无任何构成数据时返回空数组）。
+ */
+export declare function occupancyBreakdown(occupancy: ContextOccupancy | undefined): readonly {
+    key: 'system' | 'tools' | 'message';
+    tokens: number;
+}[];
+/** 页面级单例：同一页面只有一个计费插件实例，与其它模块级单例同口径。 */
+export declare const contextStore: ContextStore;
+//# sourceMappingURL=context-store.d.ts.map

package/lib/types/client/domain/agent-tree.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 智能体网络树：从会话行的 `parentId` 还原委派关系，并逐级算出「链合计」。
+ *
+ * 背景：宿主把子智能体落成**独立会话**，靠 `parentId` 指向委派它的对话。本仓的
+ * 账单页（明细 Tab）已经能把子智能体归并到父会话，但那是「账单视角」；本模块给出
+ * 「网络视角」——谁委派了谁、每条链总共花了多少，用来回答**「哪次委派最贵」**。
+ *
+ * 与展示层的 `buildSessionDisplay` 的分工：那一支做的是**同标题会话合并 + 展示树
+ * 挂靠**（账单表要按人可读的方式分组）；本模块只做**委派关系 + 链合计**，不合并
+ * 同标题会话——网络视角里两个同名会话是两个独立智能体。
+ *
+ * 环防护：异常数据可能出现 `a.parentId=b && b.parentId=a`（互指父子），直接递归
+ * 会造出渲染死循环。建树时按「父链回溯」判环：命中环的节点按根处理（不挂到任何
+ * 父节点下），其余结构照常。
+ */
+import type { SessionBillingRow } from './types.ts';
+/** 网络树的一个节点（一个智能体 / 一个会话）。 */
+export interface AgentNode {
+    id: string;
+    title?: string;
+    cwd?: string;
+    /** 自身调用数（不含后代）。 */
+    calls: number;
+    /** 自身费用（不含后代）。 */
+    cost: number;
+    /** 最后活跃时刻（毫秒）。 */
+    lastActive: number;
+    /** 自身 + 全部后代的费用合计。 */
+    chainCost: number;
+    /** 自身 + 全部后代的调用合计。 */
+    chainCalls: number;
+    /** 直接子智能体（按链合计倒序）。 */
+    children: AgentNode[];
+    /** 深度（根 = 0）。 */
+    depth: number;
+}
+/** 网络树汇总。 */
+export interface AgentTreeStats {
+    /** 参与网络的智能体总数（含根）。 */
+    agents: number;
+    /** 委派边数（父 → 子 的条数）。 */
+    delegations: number;
+    /** 根（对话）数量。 */
+    roots: number;
+    /** 链合计最高的一支（根或子节点皆可）。 */
+    costliest?: AgentNode;
+}
+/**
+ * 建树：还原委派关系并算链合计。
+ * @param rows - 会话行（含 parentId 的原始行，不是展示层合并后的行）。
+ * @returns 根节点数组（按链合计倒序）。
+ */
+export declare function buildAgentTree(rows: readonly SessionBillingRow[]): AgentNode[];
+/**
+ * 网络树汇总统计。
+ * @param roots - 根节点数组。
+ * @returns 汇总（智能体数 / 委派数 / 对话数 / 最贵的一支）。
+ */
+export declare function agentTreeStats(roots: readonly AgentNode[]): AgentTreeStats;
+//# sourceMappingURL=agent-tree.d.ts.map

package/lib/types/client/domain/types.d.ts

@@ -27,7 +27,7 @@ export interface ModelHealth {
 /** Idle health state before the probe settles. */
 export declare const IDLE_HEALTH: ModelHealth;
 /** 仪表盘分区 Tab id。 */
-export type DashboardTab = 'overview' | 'token' | 'trends' | 'providers' | 'pricing' | 'settings';
+export type DashboardTab = 'overview' | 'context' | 'agents' | 'token' | 'trends' | 'providers' | 'pricing' | 'settings';
 import type { UsageBillingKey } from '../locales.ts';
 /**
  * Tab 定义（顺序即渲染顺序）：概览=主数字/KPI/热力图，账单=厂商计费与订阅，
@@ -65,19 +65,7 @@ export interface KpiAgg {
     peakTokens: number;
 }
 /** v1.5 Tab 徽章数据信号：空字符串 / 数字 / 状态字。`kind` 决定色调。 */
-export type TabBadgeKind = 'warn' | 'hot' | 'violet' | 'neutral';
 /** v1.5 Tab 徽章。 */
-export interface TabBadge {
-    label: string;
-    kind: TabBadgeKind;
-}
-/** 各 Tab 数据信号聚合：调用方传 dashboardBadgeState（避免每个 Tab 重复声明） */
-export interface DashboardBadgeState {
-    providersCount: number;
-    tokenTotal: number;
-    rateAgeMinutes: number | null;
-    settingsDirty: number;
-}
 /** 会话明细行（与服务端 SessionUsageRow 同形；旧快照可能缺失整个 bySession）。 */
 export interface SessionBillingRow {
     id: string;
@@ -161,11 +149,22 @@ export interface UsageBillingInjected {
         monthCost: number;
     }) => void;
     registerOpen: (handler: () => void) => () => void;
+    /**
+     * 跳转到宿主会话（跨插件导航）：面板点会话行时调用。
+     * 返回 'opened' 已跳转 / 'unavailable' 宿主无通道（老到没有）/ 'failed' 通道报错。
+     */
+    navigateToSession: (sessionId: string) => 'opened' | 'unavailable' | 'failed';
 }
 /** Usage stats structure from `.dsh-usage-stats.json`. */
 export interface UsageStats {
     /** 服务端聚合时间戳（毫秒）；旧快照可能缺失。 */
     updatedAt?: number;
+    /**
+     * 本次下发的是「上次算好的」文档（聚合超响应预算或失败时的回落）：
+     * 内存里最近一次完成的聚合，或落盘快照。面板据此提示数据滞后，
+     * 避免把旧值（如重命名前的会话标题）当成最新值读。
+     */
+    staleSnapshot?: boolean;
     /** 宿主进程时区（IANA 名 + UTC 偏移）：天按此切分，副标题据此标注；旧快照可能缺失。 */
     timezone?: {
         name: string;