@kenz1117/dsh-ui-usage-billing 1.7.4 → 1.8.0-alpha.2

package/lib/index.js

@@ -1,14 +1,14 @@
 import { createRequire } from "node:module";
 import { lstat, mkdir, readFile, rm, stat } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { withFileLock, writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 import z from "@deepseek-ai/schemastery";
 import * as sessionTypes from "@deepseek-ai/dsh-session/types";
-import { createHash, createHmac } from "node:crypto";
+import { createHash, createHmac, randomUUID } from "node:crypto";
 //#region lib/types/client/plan-knowledge.js
 /**
 * Plan-knowledge reference (adapted from dsh-spend's `knowledge.js`, MIT):
@@ -339,7 +339,7 @@ function isBeijingWeekend(timeMs) {
 * 编码为空格分隔的 `YYYYMMDD` 列表（按年分组、同年日期连续排列，便于逐年追加）：
 * 每个键长度固定为 8，故 `includes` 不会跨键误匹配；相比「区间 + 运行时展开」
 * 省掉一段解析代码——client / index 两个 face 都要过本仓自设的体积成本线
-* （sync.sh 的 256/320 KiB；DSH Store 对插件 JS bundle 本身无审查上限）。
+* （sync.sh 的 256/500 KiB；DSH Store 对插件 JS bundle 本身无审查上限）。
 */
 const CHINA_HOLIDAYS = "20260925 20260926 20260927 20261001 20261002 20261003 20261004 20261005 20261006 20261007";
 /** 北京日期键 YYYYMMDD（与宿主时区无关）。 */
@@ -357,11 +357,65 @@ const TIER_BOUNDARY_MINUTES = [
 	840,
 	1080
 ];
+/**
+* 智谱 Coding Plan 的高峰边界（北京时间当日分钟）：工作日 14:00–18:00 为高峰，
+* 额度按基础积分全额抵扣；其余时段（含周末全天）按基础积分 5 折抵扣。
+*/
+const ZHIPU_CODING_PLAN_BOUNDARY_MINUTES = [840, 1080];
 /** 北京时间的当日毫秒数（0–86,400,000）。 */
 function beijingMillisOfDay(timeMs) {
 	return ((timeMs + 288e5) % 864e5 + 864e5) % 864e5;
 }
 /**
+* 按给定峰段边界计算当前档位与距下一切换的时长（扫描结构与 tierCountdown 相同）。
+* @param holidays - 是否把法定节假日并入低谷日（见 {@link tierAtWithBounds}）。
+*/
+function tierCountdownWithBounds(nowMs, bounds, holidays = false) {
+	const tier = tierAtWithBounds(nowMs, bounds, holidays);
+	const dayMs = beijingMillisOfDay(nowMs);
+	for (let dayOffset = 0; dayOffset < 10; dayOffset++) {
+		const dayStart = dayOffset * 864e5 - dayMs;
+		for (const boundary of bounds) {
+			const inMs = dayStart + boundary * 6e4;
+			if (inMs <= 0) continue;
+			if (tierAtWithBounds(nowMs + inMs, bounds, holidays) !== tier) return {
+				tier,
+				nextSwitchInMs: inMs
+			};
+		}
+	}
+	const firstBoundary = bounds[0] ?? 0;
+	return {
+		tier,
+		nextSwitchInMs: 864e5 - dayMs + firstBoundary * 6e4
+	};
+}
+/**
+* 由会话当前模型与订阅状态推断峰谷窗口。DeepSeek 目录模型恒为按量分时；
+* 智谱模型仅在持有 Z.ai Coding Plan（status ok）时适用积分分时——智谱按量价
+* 全天统一，不涉及峰谷。其余模型（含未收录）返回 none：不显示档位、不提醒，
+* 峰谷提示严格跟随当前对话实际使用的模型而非全局规则。
+* @param modelKey - 当前会话最近一轮的计费目录键（归因模型 key）；无轮次时 undefined。
+* @param hasZhipuPlan - 是否存在状态正常的 Z.ai Coding Plan 订阅。
+* @returns 命中的峰谷窗口种类。
+*/
+function rateChannelOf(modelKey, hasZhipuPlan) {
+	if (modelKey === void 0 || modelKey === "") return "none";
+	const resolved = resolveCatalogKey(modelKey);
+	const provider = modelCatalog().find((entry) => entry.key === resolved)?.provider;
+	if (provider === "DeepSeek") return "deepseek-metered";
+	if (hasZhipuPlan && provider === "智谱 AI") return "zhipu-coding-plan";
+	return "none";
+}
+/** 按计费通道的峰谷倒计时：none 返回 null（调用方据此隐藏档位 UI 与切换预告）。 */
+function channelCountdown(nowMs, channel) {
+	switch (channel) {
+		case "deepseek-metered": return tierCountdownWithBounds(nowMs, TIER_BOUNDARY_MINUTES, true);
+		case "zhipu-coding-plan": return tierCountdownWithBounds(nowMs, ZHIPU_CODING_PLAN_BOUNDARY_MINUTES);
+		case "none": return null;
+	}
+}
+/**
 * 内置目录与别名表的运行时注入态：数据本体在 src/builtin-catalog.ts（仅随 node
 * 半构建发布）。宿主半区在插件 activate 时同步注入；客户端在 /api/billing/pricing
 * 首次响应时注入。未注入时目录为空——计价消费方走 UNSEEDED_OTHER 兜底（不产生
@@ -9335,6 +9389,551 @@ function registerUsageStatsRoute(ctx, deps) {
 	}), "usage-billing: usage-stats route");
 }
 //#endregion
+//#region lib/types/task-queue.js
+/**
+* Durable off-peak FIFO task queue (issue #106, new-host capability preview).
+*
+* Safety contract: tasks START only in the DeepSeek off-peak window; an admitted
+* turn is never cancelled at the next peak. Failed/unknown outcomes never auto-
+* retry. A file lock + owner lease prevents two DSH instances sharing DSH_HOME
+* from submitting the same task. Prompts are persisted with mode 0600.
+*/
+const QUEUE_VERSION = 1;
+const MAX_TASKS = 100;
+const MAX_QUEUED = 50;
+const MAX_PROMPT_LENGTH = 32e3;
+const LOCK_WAIT_MS = 5e3;
+const LEASE_MS = 45e3;
+const HEARTBEAT_MS = 15e3;
+const OPTIONS_CACHE_MS = 6e4;
+var TaskQueueError = class extends Error {
+	status;
+	constructor(message, status = 400) {
+		super(message);
+		this.status = status;
+		this.name = "TaskQueueError";
+	}
+};
+function messageOf(error) {
+	return (error instanceof Error ? error.message : String(error)).slice(0, 300);
+}
+function isTerminal(status) {
+	return status === "completed" || status === "failed";
+}
+function validStoredTask(value) {
+	if (value === null || typeof value !== "object") return false;
+	const task = value;
+	return typeof task.id === "string" && task.id !== "" && typeof task.prompt === "string" && task.prompt.trim() !== "" && task.prompt.length <= MAX_PROMPT_LENGTH && typeof task.cwd === "string" && isAbsolute(task.cwd) && typeof task.provider === "string" && task.provider !== "" && typeof task.model === "string" && task.model !== "" && typeof task.createdAt === "number" && Number.isFinite(task.createdAt) && [
+		"queued",
+		"starting",
+		"running",
+		"completed",
+		"failed"
+	].includes(task.status ?? "") && (task.sessionId === void 0 || typeof task.sessionId === "string") && (task.owner === void 0 || typeof task.owner === "string") && (task.leaseUntil === void 0 || typeof task.leaseUntil === "number");
+}
+function publicTask(task) {
+	const { owner: _owner, leaseUntil: _leaseUntil, ...pub } = task;
+	return pub;
+}
+/** The host API is an optional capability; absence never blocks plugin startup. */
+function usableController(value) {
+	if (value === void 0) return void 0;
+	return [
+		"create",
+		"selectModel",
+		"prompt",
+		"follow",
+		"modelCatalog"
+	].every((key) => typeof value[key] === "function") ? value : void 0;
+}
+var TaskQueueEngine = class {
+	options;
+	now;
+	createId;
+	ownerId;
+	pollMs;
+	timer;
+	heartbeat;
+	taskAbort;
+	stopped = true;
+	pumping = false;
+	modelCache;
+	constructor(options) {
+		this.options = options;
+		this.now = options.now ?? Date.now;
+		this.createId = options.createId ?? randomUUID;
+		this.ownerId = options.ownerId ?? randomUUID();
+		this.pollMs = options.pollMs ?? 15e3;
+	}
+	start() {
+		if (!this.stopped) return;
+		this.stopped = false;
+		this.timer = setInterval(() => {
+			this.pump();
+		}, this.pollMs);
+		this.timer.unref();
+		this.pump();
+	}
+	stop() {
+		this.stopped = true;
+		if (this.timer !== void 0) clearInterval(this.timer);
+		if (this.heartbeat !== void 0) clearInterval(this.heartbeat);
+		this.timer = void 0;
+		this.heartbeat = void 0;
+		this.taskAbort?.abort();
+	}
+	async snapshot() {
+		const countdown = channelCountdown(this.now(), "deepseek-metered");
+		const controller = usableController(this.options.getController());
+		const base = {
+			supported: controller !== void 0,
+			tier: tierAt(this.now()),
+			nextSwitchInMs: countdown?.nextSwitchInMs ?? 0,
+			tasks: (await this.readDocument()).tasks.map(publicTask),
+			workspaces: this.options.getWorkspaces()
+		};
+		if (controller === void 0) return {
+			...base,
+			models: []
+		};
+		try {
+			return {
+				...base,
+				models: await this.modelOptions(controller)
+			};
+		} catch (error) {
+			return {
+				...base,
+				models: [],
+				optionsError: messageOf(error)
+			};
+		}
+	}
+	async summary() {
+		const countdown = channelCountdown(this.now(), "deepseek-metered");
+		const document = await this.readDocument();
+		return {
+			supported: usableController(this.options.getController()) !== void 0,
+			tier: tierAt(this.now()),
+			nextSwitchInMs: countdown?.nextSwitchInMs ?? 0,
+			queuedCount: document.tasks.filter((task) => task.status === "queued").length
+		};
+	}
+	async enqueue(input) {
+		await this.enqueueMany([input]);
+	}
+	/** Validate the whole batch before one locked append: no partially admitted import. */
+	async enqueueMany(inputs) {
+		const controller = usableController(this.options.getController());
+		if (controller === void 0) throw new TaskQueueError("this host does not provide Session task control", 409);
+		if (!Array.isArray(inputs) || inputs.length === 0) throw new TaskQueueError("at least one task is required");
+		if (inputs.length > MAX_QUEUED) throw new TaskQueueError("too many active queue items", 409);
+		const workspaces = this.options.getWorkspaces();
+		const models = await this.modelOptions(controller, true);
+		const validated = inputs.map((input, index) => {
+			try {
+				if (input === null || typeof input !== "object" || Array.isArray(input)) throw new TaskQueueError("task must be a JSON object");
+				const { prompt, cwd, provider, model } = input;
+				if (typeof prompt !== "string" || prompt.trim() === "") throw new TaskQueueError("prompt is required");
+				if (prompt.length > MAX_PROMPT_LENGTH) throw new TaskQueueError("prompt is too long");
+				if (typeof cwd !== "string" || !isAbsolute(cwd)) throw new TaskQueueError("a valid workspace is required");
+				if (!workspaces.some((workspace) => workspace.path === cwd)) throw new TaskQueueError("workspace is no longer available", 409);
+				if (typeof provider !== "string" || typeof model !== "string") throw new TaskQueueError("model is required");
+				if (!models.some((candidate) => candidate.provider === provider && candidate.id === model)) throw new TaskQueueError("select an available DeepSeek time-of-day model", 409);
+				return {
+					prompt,
+					cwd,
+					provider,
+					model
+				};
+			} catch (error) {
+				if (inputs.length > 1 && error instanceof TaskQueueError) throw new TaskQueueError(`task ${String(index + 1)}: ${error.message}`, error.status);
+				throw error;
+			}
+		});
+		await this.update((tasks) => {
+			if (tasks.filter((task) => !isTerminal(task.status)).length + validated.length > MAX_QUEUED) throw new TaskQueueError("too many active queue items", 409);
+			const createdAt = this.now();
+			for (const input of validated) tasks.push({
+				id: this.createId(),
+				...input,
+				status: "queued",
+				createdAt
+			});
+		});
+		this.pump();
+	}
+	async remove(id) {
+		await this.update((tasks) => {
+			const index = tasks.findIndex((task) => task.id === id);
+			if (index < 0) throw new TaskQueueError("queue item not found", 404);
+			const task = tasks[index];
+			if (!isTerminal(task.status) && task.status !== "queued") throw new TaskQueueError("an admitted task cannot be removed; open its Session to review it", 409);
+			tasks.splice(index, 1);
+		});
+	}
+	async clearFinished() {
+		await this.update((tasks) => {
+			for (let i = tasks.length - 1; i >= 0; i -= 1) if (isTerminal(tasks[i].status)) tasks.splice(i, 1);
+		});
+	}
+	async modelOptions(controller, refresh = false) {
+		if (!refresh && this.modelCache !== void 0 && this.now() - this.modelCache.at < OPTIONS_CACHE_MS) return this.modelCache.models;
+		const catalog = await controller.modelCatalog();
+		const models = [];
+		for (const group of catalog.groups) {
+			if (group.id !== "deepseek-official") continue;
+			for (const model of group.models) {
+				if (rateChannelOf(model.id, false) !== "deepseek-metered") continue;
+				models.push({
+					provider: group.id,
+					providerName: group.name,
+					id: model.id,
+					name: model.name
+				});
+			}
+		}
+		this.modelCache = {
+			at: this.now(),
+			models
+		};
+		return models;
+	}
+	async pump() {
+		if (this.stopped || this.pumping) return;
+		this.pumping = true;
+		try {
+			await this.recoverExpired();
+			if (this.stopped || tierAt(this.now()) !== "offPeak") return;
+			if (usableController(this.options.getController()) === void 0) return;
+			const task = await this.claimNext();
+			if (task !== void 0) await this.execute(task);
+		} catch (error) {
+			if (!this.stopped) console.warn("[usage-billing] task queue pump failed:", error);
+		} finally {
+			this.pumping = false;
+		}
+	}
+	async claimNext() {
+		let claimed;
+		await this.update((tasks) => {
+			const task = tasks.find((candidate) => candidate.status === "queued");
+			if (task === void 0) return;
+			const next = {
+				...task,
+				status: "starting",
+				owner: this.ownerId,
+				leaseUntil: this.now() + LEASE_MS,
+				startedAt: this.now(),
+				error: void 0
+			};
+			claimed = next;
+			tasks[tasks.indexOf(task)] = next;
+		});
+		return claimed;
+	}
+	async recoverExpired() {
+		await this.update((tasks) => {
+			for (let i = 0; i < tasks.length; i += 1) {
+				const task = tasks[i];
+				if (task.status !== "starting" && task.status !== "running" || (task.leaseUntil ?? 0) > this.now()) continue;
+				tasks[i] = {
+					...task,
+					status: "failed",
+					finishedAt: this.now(),
+					owner: void 0,
+					leaseUntil: void 0,
+					error: "execution result is unconfirmed after the queue owner stopped; review the Session before retrying"
+				};
+			}
+		});
+	}
+	async execute(claimed) {
+		if (this.stopped) {
+			await this.requeue(claimed.id);
+			return;
+		}
+		const controller = usableController(this.options.getController());
+		if (controller === void 0) {
+			await this.finish(claimed.id, "failed", "host Session task control disappeared before start");
+			return;
+		}
+		this.taskAbort = new AbortController();
+		const heartbeat = setInterval(() => {
+			this.renewLease(claimed.id);
+		}, HEARTBEAT_MS);
+		heartbeat.unref();
+		this.heartbeat = heartbeat;
+		try {
+			if (!this.options.getWorkspaces().some((workspace) => workspace.path === claimed.cwd)) throw new TaskQueueError("workspace is no longer available", 409);
+			if (tierAt(this.now()) !== "offPeak") {
+				await this.requeue(claimed.id);
+				return;
+			}
+			if (!(await this.modelOptions(controller, true)).some((model) => model.provider === claimed.provider && model.id === claimed.model)) throw new TaskQueueError("the selected official DeepSeek model is no longer available", 409);
+			const { sessionId } = await controller.create({ cwd: claimed.cwd });
+			if (!await this.patch(claimed.id, { sessionId })) return;
+			await controller.selectModel({
+				sessionId,
+				provider: claimed.provider,
+				model: claimed.model
+			});
+			if (tierAt(this.now()) !== "offPeak") {
+				await this.requeue(claimed.id);
+				return;
+			}
+			if (!await this.patch(claimed.id, { leaseUntil: this.now() + LEASE_MS })) return;
+			const frames = controller.follow({ address: {
+				kind: "session",
+				sessionId
+			} }, this.taskAbort.signal);
+			const requestId = this.createId();
+			await controller.prompt({
+				requestId,
+				sessionId,
+				mode: "queue",
+				content: [{
+					type: "text",
+					text: claimed.prompt
+				}]
+			}, new AbortController().signal);
+			await this.patch(claimed.id, {
+				status: "running",
+				leaseUntil: this.now() + LEASE_MS
+			});
+			const outcome = await this.watch(frames, String(requestId));
+			if (outcome !== void 0) await this.finish(claimed.id, outcome.status, outcome.error);
+		} catch (error) {
+			if (!this.stopped) await this.finish(claimed.id, "failed", messageOf(error));
+		} finally {
+			clearInterval(heartbeat);
+			if (this.heartbeat === heartbeat) this.heartbeat = void 0;
+			this.taskAbort?.abort();
+			this.taskAbort = void 0;
+		}
+	}
+	async watch(frames, requestId) {
+		let admitted = false;
+		for await (const raw of frames) {
+			const frame = raw;
+			if (frame.type !== "event" || frame.event === void 0) continue;
+			if (frame.event.type === "user/message") {
+				const data = frame.event.data;
+				if (data.source?.kind === "user" && data.source.rpcId === requestId) admitted = true;
+				continue;
+			}
+			if (!admitted || frame.event.type !== "turn/end") continue;
+			const data = frame.event.data;
+			const kind = data.reason?.kind;
+			if (kind === "completed") return { status: "completed" };
+			return {
+				status: "failed",
+				error: data.reason?.error?.message ?? `task turn ended: ${kind ?? "unknown"}`
+			};
+		}
+		return this.stopped ? void 0 : {
+			status: "failed",
+			error: "execution result is unconfirmed; review the Session"
+		};
+	}
+	async renewLease(id) {
+		try {
+			await this.patch(id, { leaseUntil: this.now() + LEASE_MS });
+		} catch (error) {
+			console.warn("[usage-billing] task queue lease renewal failed:", error);
+		}
+	}
+	async requeue(id) {
+		await this.patch(id, {
+			status: "queued",
+			owner: void 0,
+			leaseUntil: void 0,
+			startedAt: void 0,
+			sessionId: void 0
+		});
+	}
+	async finish(id, status, error) {
+		await this.patch(id, {
+			status,
+			error,
+			finishedAt: this.now(),
+			owner: void 0,
+			leaseUntil: void 0
+		});
+	}
+	async patch(id, patch) {
+		let applied = false;
+		await this.update((tasks) => {
+			const index = tasks.findIndex((task) => task.id === id);
+			if (index < 0) return;
+			const task = tasks[index];
+			if (task.owner !== this.ownerId) return;
+			tasks[index] = {
+				...task,
+				...patch
+			};
+			applied = true;
+		});
+		return applied;
+	}
+	async update(mutate) {
+		await mkdir(dirname(this.options.filePath), {
+			recursive: true,
+			mode: 448
+		});
+		await withFileLock(this.options.filePath, async () => {
+			const { document, rawMain } = await this.readDocumentWithRaw();
+			const tasks = [...document.tasks];
+			mutate(tasks);
+			while (tasks.length > MAX_TASKS) {
+				const index = tasks.findIndex((task) => isTerminal(task.status));
+				if (index < 0) break;
+				tasks.splice(index, 1);
+			}
+			if (JSON.stringify(tasks) === JSON.stringify(document.tasks)) return;
+			if (rawMain !== void 0) await writeFileAtomic(`${this.options.filePath}.bak`, rawMain, {
+				mode: 384,
+				dirMode: 448
+			});
+			const next = {
+				version: QUEUE_VERSION,
+				tasks
+			};
+			await writeFileAtomic(this.options.filePath, JSON.stringify(next), {
+				mode: 384,
+				dirMode: 448
+			});
+		}, { waitMs: LOCK_WAIT_MS });
+	}
+	async readDocument() {
+		return (await this.readDocumentWithRaw()).document;
+	}
+	async readDocumentWithRaw() {
+		let sawFile = false;
+		for (const path of [this.options.filePath, `${this.options.filePath}.bak`]) try {
+			const raw = await readFile(path, "utf8");
+			sawFile = true;
+			const parsed = JSON.parse(raw);
+			if (parsed.version !== QUEUE_VERSION || !Array.isArray(parsed.tasks) || !parsed.tasks.every(validStoredTask)) continue;
+			return {
+				document: {
+					version: QUEUE_VERSION,
+					tasks: parsed.tasks
+				},
+				...path === this.options.filePath ? { rawMain: raw } : {}
+			};
+		} catch (error) {
+			if (error.code !== "ENOENT") sawFile = true;
+		}
+		if (sawFile) throw new Error("task queue persistence is unreadable");
+		return { document: {
+			version: QUEUE_VERSION,
+			tasks: []
+		} };
+	}
+};
+//#endregion
+//#region lib/types/routes/task-queue.js
+/** Loopback-only GET/POST /api/billing/task-queue (issue #106). */
+const BODY_LIMIT = 10485760;
+const JSON_HEADERS = {
+	"content-type": "application/json; charset=utf-8",
+	"cache-control": "no-store"
+};
+function send(res, status, body) {
+	res.writeHead(status, JSON_HEADERS);
+	res.end(JSON.stringify(body));
+}
+function registerTaskQueueRoute(ctx, deps) {
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: "/api/billing/task-queue",
+		handler: async (req, res) => {
+			if (!guardLoopback(req, res, deps.trustedHosts)) return;
+			if (req.method !== "GET" && req.method !== "POST") {
+				send(res, 405, { error: "method not allowed" });
+				return;
+			}
+			if (req.method === "POST") {
+				if (!isLoopbackOrigin(req.headers.origin)) {
+					send(res, 403, { error: "forbidden: loopback only" });
+					return;
+				}
+				if (!(req.headers["content-type"] ?? "").toLowerCase().includes("application/json")) {
+					send(res, 415, { error: "unsupported content-type" });
+					return;
+				}
+			}
+			try {
+				if (req.method === "GET") {
+					send(res, 200, await deps.engine.snapshot());
+					return;
+				}
+				const chunks = [];
+				let bytes = 0;
+				for await (const chunk of req) {
+					const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+					bytes += buffer.byteLength;
+					if (bytes > BODY_LIMIT) {
+						send(res, 413, { error: "body too large" });
+						return;
+					}
+					chunks.push(buffer);
+				}
+				let input;
+				try {
+					const body = Buffer.concat(chunks).toString("utf8");
+					const parsed = JSON.parse(body === "" ? "{}" : body);
+					if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new TaskQueueError("request body must be a JSON object");
+					input = parsed;
+				} catch (error) {
+					if (error instanceof TaskQueueError) throw error;
+					throw new TaskQueueError("malformed JSON body");
+				}
+				switch (input.action) {
+					case "enqueue":
+						await deps.engine.enqueue(input);
+						break;
+					case "enqueueMany":
+						if (!Array.isArray(input.tasks)) throw new TaskQueueError("tasks must be an array");
+						await deps.engine.enqueueMany(input.tasks);
+						break;
+					case "remove":
+						if (typeof input.id !== "string" || input.id === "") throw new TaskQueueError("queue item id is required");
+						await deps.engine.remove(input.id);
+						break;
+					case "clearFinished":
+						await deps.engine.clearFinished();
+						break;
+					default: throw new TaskQueueError("unknown queue action");
+				}
+				send(res, 200, {
+					ok: true,
+					snapshot: await deps.engine.snapshot()
+				});
+			} catch (error) {
+				send(res, error instanceof TaskQueueError ? error.status : 503, { error: error instanceof Error ? error.message.slice(0, 300) : "queue operation failed" });
+			}
+		}
+	}), "usage-billing: task queue route");
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: "/api/billing/task-queue-summary",
+		handler: async (req, res) => {
+			if (!guardLoopback(req, res, deps.trustedHosts)) return;
+			if (req.method !== "GET") {
+				send(res, 405, { error: "method not allowed" });
+				return;
+			}
+			try {
+				send(res, 200, await deps.engine.summary());
+			} catch {
+				send(res, 503, { error: "queue summary unavailable" });
+			}
+		}
+	}), "usage-billing: task queue summary route");
+}
+//#endregion
 //#region lib/types/client/usage-billing-settings.js
 /** 设置命名空间 id（小写 kebab-case）。 */
 const BILLING_SETTINGS_NAMESPACE = "ui-usage-billing";
@@ -9963,6 +10562,34 @@ function apply(ctx, config = {}) {
 		trustedHosts,
 		claimsPath: `${snapshotPath}.notify-claims.json`
 	});
+	const taskQueue = new TaskQueueEngine({
+		filePath: config.taskQueuePath ?? join(dshHome, ".dsh-usage-task-queue.json"),
+		getController: () => {
+			try {
+				return ctx.get("sessionController");
+			} catch {
+				return;
+			}
+		},
+		getWorkspaces: () => {
+			try {
+				return (ctx.get("workspaceRegistry")?.list?.() ?? []).filter((workspace) => typeof workspace.path === "string" && workspace.path !== "").map((workspace) => ({
+					path: workspace.path,
+					title: workspace.title || workspace.path
+				}));
+			} catch {
+				return [];
+			}
+		}
+	});
+	registerTaskQueueRoute(ctx, {
+		trustedHosts,
+		engine: taskQueue
+	});
+	taskQueue.start();
+	ctx.effect(() => () => {
+		taskQueue.stop();
+	}, "usage-billing: task queue scheduler");
 	let usageToolDisposer;
 	let usageToolRegister;
 	const syncUsageTool = () => {

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

@@ -10,7 +10,7 @@ import type { UsageBillingKey } from './locales.ts';
 export interface PeakAlertBannerProps {
     hit: PeakAlertHit;
     config: PeakAlertConfig;
-    t: (key: UsageBillingKey) => string;
+    t: (key: UsageBillingKey, params?: Record<string, unknown>) => string;
     onDismiss: () => void;
 }
 /** 渲染一个切档前提醒状态条。 */