dsh-budget 0.1.0

package/lib/index.js

@@ -0,0 +1,1225 @@
+import { n as BUDGET_SETTINGS_SCHEMA } from "./wire-DVO8yw7L.js";
+import z from "@deepseek-ai/schemastery";
+import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+//#region src/config.ts
+/**
+* Config schema and resolution for `dsh-budget`. Every tunable is a validated
+* {@link Config} field changeable from cordis.yml; `resolveConfig` re-judges
+* every default and bound so programmatic construction that bypasses
+* Schemastery normalization still fails loud (the explicit-resolve contract).
+*
+* @module dsh-budget/config
+*/
+/** Known electricity region keys (upstream carbon table). */
+const REGIONS = [
+	"global",
+	"us",
+	"eu",
+	"china",
+	"india",
+	"uk",
+	"france",
+	"iceland"
+];
+/** Schemastery schema: the loader validates and fills defaults before `apply`. */
+const Config = z.object({
+	prices: z.dict(z.object({
+		input: z.number().min(0).required(),
+		output: z.number().min(0).required(),
+		cacheRead: z.number().min(0),
+		cacheWrite: z.number().min(0)
+	})).default({}),
+	defaultPrice: z.object({
+		input: z.number().min(0).default(1),
+		output: z.number().min(0).default(3),
+		cacheRead: z.number().min(0).default(1),
+		cacheWrite: z.number().min(0).default(1)
+	}).default({
+		input: 1,
+		output: 3,
+		cacheRead: 1,
+		cacheWrite: 1
+	}),
+	budgets: z.object({
+		session: z.number().min(0),
+		daily: z.number().min(0),
+		monthly: z.number().min(0)
+	}).default({
+		session: 10,
+		daily: 50,
+		monthly: 500
+	}),
+	warnRatio: z.number().min(0).max(1).default(.8),
+	overLimit: z.union([
+		"alert",
+		"block",
+		"degrade"
+	]).default("alert"),
+	degradation: z.dict(z.string()).default({}),
+	webhookUrl: z.string().default(""),
+	webhookTimeoutMs: z.number().min(100).max(12e4).default(5e3),
+	alertsEnabled: z.boolean().default(true),
+	alertCooldownMs: z.number().min(0).default(36e5),
+	desktopNotifications: z.boolean().default(false),
+	refreshIntervalMs: z.number().min(1e3).max(3e5).default(5e3),
+	carbon: z.object({
+		enabled: z.boolean().default(true),
+		region: z.union([...REGIONS]).default("global"),
+		pue: z.number().min(1).max(3).default(1.58),
+		energyKwhPerToken: z.number().min(0).default(7e-6)
+	}).default({
+		enabled: true,
+		region: "global",
+		pue: 1.58,
+		energyKwhPerToken: 7e-6
+	}),
+	latency: z.object({
+		enabled: z.boolean().default(true),
+		windowSize: z.number().min(1).max(1e4).default(200)
+	}).default({
+		enabled: true,
+		windowSize: 200
+	}),
+	currency: z.object({
+		code: z.string().default("USD"),
+		rate: z.number().min(1e-6).default(1),
+		decimals: z.number().min(0).max(6).default(2)
+	}).default({
+		code: "USD",
+		rate: 1,
+		decimals: 2
+	}),
+	outputLanguage: z.union(["en", "zh"]).default("en"),
+	historyDays: z.number().min(1).max(365).default(30)
+});
+/** Throw the standard fail-loud config error for one invalid field. */
+function invalid(field, detail) {
+	throw new Error(`dsh-budget: config.${field} ${detail}`);
+}
+/**
+* Resolve raw config to the runtime policy, re-validating defaults and bounds.
+*
+* @param config - raw loader config; `undefined` for a bare row.
+* @returns the frozen resolved config.
+*/
+function resolveConfig(config) {
+	const prices = { ...config?.prices ?? {} };
+	for (const [model, entry] of Object.entries(prices)) {
+		if (!Number.isFinite(entry.input) || entry.input < 0) invalid(`prices.${model}.input`, "must be a non-negative number");
+		if (!Number.isFinite(entry.output) || entry.output < 0) invalid(`prices.${model}.output`, "must be a non-negative number");
+	}
+	const defaultPrice = config?.defaultPrice ?? {
+		input: 1,
+		output: 3
+	};
+	if (!Number.isFinite(defaultPrice.input) || defaultPrice.input < 0) invalid("defaultPrice.input", "must be a non-negative number");
+	if (!Number.isFinite(defaultPrice.output) || defaultPrice.output < 0) invalid("defaultPrice.output", "must be a non-negative number");
+	const budgets = { ...config?.budgets ?? {
+		session: 10,
+		daily: 50,
+		monthly: 500
+	} };
+	for (const [scope, cap] of Object.entries(budgets)) if (cap !== void 0 && (!Number.isFinite(cap) || cap < 0)) invalid(`budgets.${scope}`, "must be a non-negative number");
+	const warnRatio = config?.warnRatio ?? .8;
+	if (!Number.isFinite(warnRatio) || warnRatio < 0 || warnRatio > 1) invalid("warnRatio", "must be a number in [0, 1]");
+	const overLimit = config?.overLimit ?? "alert";
+	if (overLimit !== "alert" && overLimit !== "block" && overLimit !== "degrade") invalid("overLimit", "must be alert, block, or degrade");
+	const degradation = { ...config?.degradation ?? {} };
+	const rawWebhook = config?.webhookUrl ?? "";
+	let webhookUrl;
+	if (rawWebhook.trim() !== "") try {
+		const parsed = new URL(rawWebhook.trim());
+		if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new Error("scheme");
+		webhookUrl = parsed.href;
+	} catch {
+		invalid("webhookUrl", "must be a valid http(s) URL");
+	}
+	const webhookTimeoutMs = config?.webhookTimeoutMs ?? 5e3;
+	if (!Number.isFinite(webhookTimeoutMs) || webhookTimeoutMs < 100 || webhookTimeoutMs > 12e4) invalid("webhookTimeoutMs", "must be a finite number in [100, 120000]");
+	const alertsEnabled = config?.alertsEnabled ?? true;
+	if (typeof alertsEnabled !== "boolean") invalid("alertsEnabled", "must be a boolean");
+	const alertCooldownMs = config?.alertCooldownMs ?? 36e5;
+	if (!Number.isFinite(alertCooldownMs) || alertCooldownMs < 0) invalid("alertCooldownMs", "must be a non-negative number");
+	const desktopNotifications = config?.desktopNotifications ?? false;
+	const refreshIntervalMs = config?.refreshIntervalMs ?? 5e3;
+	if (!Number.isFinite(refreshIntervalMs) || refreshIntervalMs < 1e3 || refreshIntervalMs > 3e5) invalid("refreshIntervalMs", "must be a finite number in [1000, 300000]");
+	const carbonEnabled = config?.carbon?.enabled ?? true;
+	const carbonRegion = config?.carbon?.region ?? "global";
+	if (!REGIONS.includes(carbonRegion)) invalid("carbon.region", `must be one of ${REGIONS.join(", ")}`);
+	const carbonPue = config?.carbon?.pue ?? 1.58;
+	if (!Number.isFinite(carbonPue) || carbonPue < 1 || carbonPue > 3) invalid("carbon.pue", "must be a finite number in [1, 3]");
+	const energyKwhPerToken = config?.carbon?.energyKwhPerToken ?? 7e-6;
+	if (!Number.isFinite(energyKwhPerToken) || energyKwhPerToken < 0) invalid("carbon.energyKwhPerToken", "must be a non-negative number");
+	const latencyEnabled = config?.latency?.enabled ?? true;
+	const windowSize = config?.latency?.windowSize ?? 200;
+	if (!Number.isInteger(windowSize) || windowSize < 1 || windowSize > 1e4) invalid("latency.windowSize", "must be an integer in [1, 10000]");
+	const currencyCode = (config?.currency?.code ?? "USD").toUpperCase();
+	if (!/^[A-Z]{3}$/u.test(currencyCode)) invalid("currency.code", "must be a 3-letter code");
+	const currencyRate = config?.currency?.rate ?? 1;
+	if (!Number.isFinite(currencyRate) || currencyRate <= 0) invalid("currency.rate", "must be a positive number");
+	const currencyDecimals = config?.currency?.decimals ?? 2;
+	if (!Number.isInteger(currencyDecimals) || currencyDecimals < 0 || currencyDecimals > 6) invalid("currency.decimals", "must be an integer in [0, 6]");
+	const outputLanguage = config?.outputLanguage ?? "en";
+	if (outputLanguage !== "en" && outputLanguage !== "zh") invalid("outputLanguage", "must be en or zh");
+	const historyDays = config?.historyDays ?? 30;
+	if (!Number.isInteger(historyDays) || historyDays < 1 || historyDays > 365) invalid("historyDays", "must be an integer in [1, 365]");
+	return Object.freeze({
+		prices: Object.freeze(prices),
+		defaultPrice: Object.freeze(defaultPrice),
+		budgets: Object.freeze(budgets),
+		warnRatio,
+		overLimit,
+		degradation: Object.freeze(degradation),
+		webhookUrl,
+		webhookTimeoutMs,
+		alertsEnabled,
+		alertCooldownMs,
+		desktopNotifications,
+		refreshIntervalMs,
+		carbon: Object.freeze({
+			enabled: carbonEnabled,
+			region: carbonRegion,
+			pue: carbonPue,
+			energyKwhPerToken
+		}),
+		latency: Object.freeze({
+			enabled: latencyEnabled,
+			windowSize
+		}),
+		currency: Object.freeze({
+			code: currencyCode,
+			rate: currencyRate,
+			decimals: currencyDecimals
+		}),
+		outputLanguage,
+		historyDays
+	});
+}
+//#endregion
+//#region src/estimate/prices.ts
+/**
+* Fixed CNY→USD rate used when converting the upstream CNY-per-1k table into
+* USD-per-1M entries, captured at porting time. It is a conversion constant
+* of the shipped DATA, not a runtime exchange rate; override any converted
+* entry via `config.prices` when vendor USD pricing is available.
+*/
+const UPSTREAM_CNY_PER_USD = 7.2;
+/**
+* Convert an upstream CNY-per-1k price into USD per 1M tokens.
+*
+* @param cnyPer1k - price in CNY per 1000 tokens.
+* @returns the price in USD per 1,000,000 tokens.
+*/
+function cnyPer1kToUsdPer1m(cnyPer1k) {
+	return cnyPer1k * 1e3 / UPSTREAM_CNY_PER_USD;
+}
+/** The built-in price table (USD per 1M tokens). */
+const BUILTIN_PRICES = Object.freeze({
+	"deepseek-chat": {
+		input: .27,
+		cacheRead: .027,
+		cacheWrite: .27,
+		output: 1.1,
+		source: "vendor"
+	},
+	"deepseek-reasoner": {
+		input: .55,
+		cacheRead: .055,
+		cacheWrite: .55,
+		output: 2.19,
+		source: "vendor"
+	},
+	"gpt-4o": {
+		input: 2.5,
+		cacheRead: 1.25,
+		output: 10,
+		source: "vendor"
+	},
+	"gpt-4o-mini": {
+		input: .15,
+		cacheRead: .075,
+		output: .6,
+		source: "vendor"
+	},
+	"gpt-4.1": {
+		input: 2,
+		cacheRead: .5,
+		output: 8,
+		source: "vendor"
+	},
+	"gpt-4.1-mini": {
+		input: .4,
+		cacheRead: .1,
+		output: 1.6,
+		source: "vendor"
+	},
+	"claude-sonnet-4-5": {
+		input: 3,
+		output: 15,
+		source: "vendor"
+	},
+	"claude-haiku-4-5": {
+		input: 1,
+		output: 5,
+		source: "vendor"
+	},
+	"gemini-2.5-pro": {
+		input: 1.25,
+		output: 10,
+		source: "vendor"
+	},
+	"gemini-2.5-flash": {
+		input: .3,
+		output: 2.5,
+		source: "vendor"
+	},
+	"ernie-4.0": {
+		input: cnyPer1kToUsdPer1m(.12),
+		output: cnyPer1kToUsdPer1m(.12),
+		source: "upstream-cny"
+	},
+	"qwen-turbo": {
+		input: cnyPer1kToUsdPer1m(.008),
+		output: cnyPer1kToUsdPer1m(.008),
+		source: "upstream-cny"
+	},
+	"qwen-plus": {
+		input: cnyPer1kToUsdPer1m(.04),
+		output: cnyPer1kToUsdPer1m(.04),
+		source: "upstream-cny"
+	},
+	"glm-4": {
+		input: cnyPer1kToUsdPer1m(.1),
+		output: cnyPer1kToUsdPer1m(.1),
+		source: "upstream-cny"
+	},
+	"baichuan2-turbo": {
+		input: cnyPer1kToUsdPer1m(.008),
+		output: cnyPer1kToUsdPer1m(.008),
+		source: "upstream-cny"
+	},
+	"moonshot-v1-8k": {
+		input: cnyPer1kToUsdPer1m(.012),
+		output: cnyPer1kToUsdPer1m(.012),
+		source: "upstream-cny"
+	}
+});
+/**
+* Merge the user table over the built-in table (per-model override).
+*
+* @param custom - `config.prices` entries.
+* @returns the merged table; custom entries win per model id.
+*/
+function mergePrices(custom) {
+	return {
+		...BUILTIN_PRICES,
+		...custom
+	};
+}
+/**
+* Resolve the price for one exact route: `${provider}/${model}` first, then
+* the bare model id, then the fallback.
+*
+* @param table - merged price table.
+* @param fallback - price for models absent from the table.
+* @param provider - registered provider route.
+* @param model - model id.
+* @returns the effective price entry (never undefined).
+*/
+function priceFor(table, fallback, provider, model) {
+	return table[`${provider}/${model}`] ?? table[model] ?? fallback;
+}
+/**
+* Price one disjoint token usage record.
+*
+* @param price - effective price entry.
+* @param inputTokens - uncached input tokens.
+* @param outputTokens - output tokens.
+* @param cacheReadTokens - cache-hit tokens (0 when absent).
+* @param cacheWriteTokens - cache-miss tokens (0 when absent).
+* @returns the USD cost breakdown.
+*/
+function estimateUsageCost(price, inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens) {
+	const inputCost = inputTokens / 1e6 * price.input;
+	const outputCost = outputTokens / 1e6 * price.output;
+	const cacheReadCost = cacheReadTokens / 1e6 * (price.cacheRead ?? price.input);
+	const cacheWriteCost = cacheWriteTokens / 1e6 * (price.cacheWrite ?? price.input);
+	return {
+		inputCost,
+		outputCost,
+		cacheReadCost,
+		cacheWriteCost,
+		totalCost: inputCost + outputCost + cacheReadCost + cacheWriteCost
+	};
+}
+Object.freeze({
+	"A100": {
+		tdp: 400,
+		name: "NVIDIA A100",
+		category: "datacenter"
+	},
+	"A100-80GB": {
+		tdp: 400,
+		name: "NVIDIA A100 80GB",
+		category: "datacenter"
+	},
+	"H100": {
+		tdp: 700,
+		name: "NVIDIA H100",
+		category: "datacenter"
+	},
+	"H100-80GB": {
+		tdp: 700,
+		name: "NVIDIA H100 80GB",
+		category: "datacenter"
+	},
+	"V100": {
+		tdp: 300,
+		name: "NVIDIA V100",
+		category: "datacenter"
+	},
+	"A40": {
+		tdp: 300,
+		name: "NVIDIA A40",
+		category: "datacenter"
+	},
+	"A30": {
+		tdp: 165,
+		name: "NVIDIA A30",
+		category: "datacenter"
+	},
+	"A10": {
+		tdp: 150,
+		name: "NVIDIA A10",
+		category: "datacenter"
+	},
+	"RTX-4090": {
+		tdp: 450,
+		name: "NVIDIA RTX 4090",
+		category: "consumer"
+	},
+	"RTX-4080": {
+		tdp: 320,
+		name: "NVIDIA RTX 4080",
+		category: "consumer"
+	},
+	"RTX-3090": {
+		tdp: 350,
+		name: "NVIDIA RTX 3090",
+		category: "consumer"
+	},
+	"RTX-3080": {
+		tdp: 320,
+		name: "NVIDIA RTX 3080",
+		category: "consumer"
+	},
+	"MI250X": {
+		tdp: 560,
+		name: "AMD MI250X",
+		category: "datacenter"
+	},
+	"MI210": {
+		tdp: 300,
+		name: "AMD MI210",
+		category: "datacenter"
+	},
+	"MI100": {
+		tdp: 300,
+		name: "AMD MI100",
+		category: "datacenter"
+	},
+	"TPU-v4": {
+		tdp: 450,
+		name: "Google TPU v4",
+		category: "tpu"
+	},
+	"TPU-v3": {
+		tdp: 450,
+		name: "Google TPU v3",
+		category: "tpu"
+	}
+});
+/** Regional grid carbon intensity in kg CO2e per kWh, verbatim from upstream. */
+const CARBON_INTENSITY = Object.freeze({
+	global: .475,
+	us: .386,
+	eu: .276,
+	china: .555,
+	india: .708,
+	uk: .233,
+	france: .056,
+	iceland: .01
+});
+Object.freeze({
+	car_year: {
+		name: "燃油车行驶一年",
+		co2Kg: 4600,
+		emoji: "🚗"
+	},
+	flight_nyc_london: {
+		name: "纽约-伦敦往返航班",
+		co2Kg: 1100,
+		emoji: "✈️"
+	},
+	tree_year: {
+		name: "树木一年吸收的CO2",
+		co2Kg: 21,
+		emoji: "🌲"
+	},
+	smartphone_charge: {
+		name: "智能手机充电",
+		co2Kg: .008,
+		emoji: "📱"
+	},
+	home_electricity_month: {
+		name: "家庭一个月用电",
+		co2Kg: 400,
+		emoji: "🏠"
+	}
+});
+/**
+* Estimate the carbon footprint of a token volume (the plugin's token→carbon
+* bridge): energy = tokens × kWh/token, total = energy × PUE,
+* CO2 = total × regional intensity.
+*
+* @param tokens - total tokens processed (all buckets).
+* @param energyKwhPerToken - IT energy per token in kWh.
+* @param pue - power usage effectiveness.
+* @param region - electricity region key.
+* @returns the estimation result.
+* @throws on an unknown region.
+*/
+function tokenCarbon(tokens, energyKwhPerToken, pue, region) {
+	const carbonIntensity = CARBON_INTENSITY[region];
+	if (carbonIntensity === void 0) throw new Error(`Unknown region: ${region}`);
+	const energyKwh = tokens * energyKwhPerToken;
+	const totalEnergyKwh = energyKwh * pue;
+	return {
+		energyKwh,
+		totalEnergyKwh,
+		co2Kg: totalEnergyKwh * carbonIntensity,
+		carbonIntensity
+	};
+}
+//#endregion
+//#region src/aggregate/usage.ts
+/** Empty usage record. */
+function emptyUsage() {
+	return {
+		inputTokens: 0,
+		outputTokens: 0,
+		cacheReadTokens: 0,
+		cacheWriteTokens: 0,
+		costUsd: 0,
+		carbonKg: 0
+	};
+}
+/** UTC day key, e.g. `2026-08-16`. */
+function dayKey(timestamp) {
+	return new Date(timestamp).toISOString().slice(0, 10);
+}
+/** UTC month key, e.g. `2026-08`. */
+function monthKey(timestamp) {
+	return new Date(timestamp).toISOString().slice(0, 7);
+}
+/**
+* The runtime aggregator. All methods are synchronous; the caller invokes
+* them from the session-event listener (the event hot path).
+*/
+var BudgetAggregator = class {
+	config;
+	now;
+	state;
+	table;
+	/** @param config - resolved plugin config. @param now - clock (defaults to Date.now). */
+	constructor(config, now = Date.now) {
+		this.config = config;
+		this.now = now;
+		this.table = mergePrices(config.prices);
+		this.state = {
+			sessions: /* @__PURE__ */ new Map(),
+			days: /* @__PURE__ */ new Map(),
+			months: /* @__PURE__ */ new Map(),
+			latency: /* @__PURE__ */ new Map(),
+			blockedScopes: /* @__PURE__ */ new Set(),
+			alerts: [],
+			lastAlertAt: /* @__PURE__ */ new Map(),
+			provider: "",
+			model: ""
+		};
+	}
+	/** Update the current provider/model attribution from a request header. */
+	setAttribution(provider, model) {
+		this.state.provider = provider;
+		this.state.model = model;
+	}
+	/** The current provider/model attribution (latest request header). */
+	attribution() {
+		return {
+			provider: this.state.provider,
+			model: this.state.model
+		};
+	}
+	/**
+	* Record one usage payload against the current attribution. Unknown or
+	* zero usage is a no-op.
+	*
+	* @param sessionId - owning session id (string form).
+	* @param usage - the token usage payload.
+	*/
+	recordUsage(sessionId, usage) {
+		const input = usage.inputTokens;
+		const output = usage.outputTokens;
+		const cacheRead = usage.cacheReadTokens ?? 0;
+		const cacheWrite = usage.cacheWriteTokens ?? 0;
+		if (input + output + cacheRead + cacheWrite <= 0) return;
+		const cost = estimateUsageCost(priceFor(this.table, this.config.defaultPrice, this.state.provider, this.state.model), input, output, cacheRead, cacheWrite);
+		const tokens = input + output + cacheRead + cacheWrite;
+		const carbon = this.config.carbon.enabled ? tokenCarbon(tokens, this.config.carbon.energyKwhPerToken, this.config.carbon.pue, this.config.carbon.region).co2Kg : 0;
+		const add = (target) => {
+			target.inputTokens += input;
+			target.outputTokens += output;
+			target.cacheReadTokens += cacheRead;
+			target.cacheWriteTokens += cacheWrite;
+			target.costUsd += cost.totalCost;
+			target.carbonKg += carbon;
+		};
+		const session = this.state.sessions.get(sessionId) ?? emptyUsage();
+		add(session);
+		this.state.sessions.set(sessionId, session);
+		const at = this.now();
+		const day = this.state.days.get(dayKey(at)) ?? {
+			total: emptyUsage(),
+			models: /* @__PURE__ */ new Map()
+		};
+		add(day.total);
+		this.addModel(day.models, input, output, cacheRead, cacheWrite, cost.totalCost, carbon);
+		this.state.days.set(dayKey(at), day);
+		const month = this.state.months.get(monthKey(at)) ?? {
+			total: emptyUsage(),
+			models: /* @__PURE__ */ new Map()
+		};
+		add(month.total);
+		this.addModel(month.models, input, output, cacheRead, cacheWrite, cost.totalCost, carbon);
+		this.state.months.set(monthKey(at), month);
+	}
+	/** Record one measured call duration for one model. */
+	recordLatency(model, durationMs) {
+		if (!this.config.latency.enabled || !Number.isFinite(durationMs) || durationMs < 0) return;
+		const window = this.state.latency.get(model) ?? [];
+		window.push(durationMs);
+		if (window.length > this.config.latency.windowSize) window.shift();
+		this.state.latency.set(model, window);
+	}
+	/** Merge one usage record into a per-model map. */
+	addModel(models, input, output, cacheRead, cacheWrite, costUsd, carbonKg) {
+		const model = this.state.model || "unknown";
+		const entry = models.get(model) ?? {
+			provider: this.state.provider || "unknown",
+			model,
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheReadTokens: 0,
+			cacheWriteTokens: 0,
+			costUsd: 0,
+			carbonKg: 0,
+			latencyMs: []
+		};
+		entry.inputTokens += input;
+		entry.outputTokens += output;
+		entry.cacheReadTokens += cacheRead;
+		entry.cacheWriteTokens += cacheWrite;
+		entry.costUsd += costUsd;
+		entry.carbonKg += carbonKg;
+		models.set(model, entry);
+	}
+	/** Read one session's usage (empty when unknown). */
+	sessionUsage(sessionId) {
+		return this.state.sessions.get(sessionId) ?? emptyUsage();
+	}
+	/** Read today's usage. */
+	todayUsage() {
+		return this.state.days.get(dayKey(this.now()))?.total ?? emptyUsage();
+	}
+	/** Read this month's usage. */
+	monthUsage() {
+		return this.state.months.get(monthKey(this.now()))?.total ?? emptyUsage();
+	}
+	/** Per-model usage (today) with latency percentiles, sorted by cost. */
+	modelUsage() {
+		const list = [...this.state.days.get(dayKey(this.now()))?.models.values() ?? []];
+		for (const entry of list) entry.latencyMs = [...this.state.latency.get(entry.model) ?? []];
+		list.sort((a, b) => b.costUsd - a.costUsd);
+		return list;
+	}
+	/** Record one threshold alert (bounded to the most recent 50). */
+	recordAlert(alert) {
+		this.state.alerts.unshift(alert);
+		if (this.state.alerts.length > 50) this.state.alerts.length = 50;
+		this.state.lastAlertAt.set(`${alert.scope}:${alert.kind}`, alert.at);
+	}
+	/** Milliseconds since the last alert of the same scope+kind (Infinity when none). */
+	lastAlertAge(scope, kind, at) {
+		const last = this.state.lastAlertAt.get(`${scope}:${kind}`);
+		return last === void 0 ? Number.POSITIVE_INFINITY : at - last;
+	}
+	/** The current blocked scopes (budget crosses that the user has not lifted). */
+	get blockedScopes() {
+		return [...this.state.blockedScopes];
+	}
+	/** Mark one scope blocked (over-limit with block/degrade policy). */
+	blockScope(scope) {
+		this.state.blockedScopes.add(scope);
+	}
+	/** Lift a block (user confirmation through /budget unblock or the panel). */
+	unblockScope(scope) {
+		this.state.blockedScopes.delete(scope);
+	}
+	/**
+	* The per-scope snapshot for one session (the panel and the command
+	* attribute usage to the session that owns the view).
+	*
+	* @param sessionId - owning session id.
+	* @returns the session-attributed snapshot.
+	*/
+	snapshotFor(sessionId) {
+		return {
+			session: this.sessionUsage(sessionId),
+			today: this.todayUsage(),
+			thisMonth: this.monthUsage(),
+			models: this.modelUsage(),
+			alerts: [...this.state.alerts],
+			blockedScopes: this.blockedScopes
+		};
+	}
+};
+//#endregion
+//#region src/estimate/sanitize.ts
+/**
+* Sanitization and formatting pure functions. Every display/log surface of
+* dsh-budget goes through these: webhook URLs, alert text, token counts and
+* money amounts. Never log or render a raw config or wire value.
+*
+* @module dsh-budget/estimate/sanitize
+*/
+/** Control characters plus zero-width and bidi-override code points. */
+const CONTROL_OR_INVISIBLE = /[\u0000-\u001f\u007f\u200b-\u200f\u202a-\u202e\u2060-\u2064\ufeff]/gu;
+/**
+* Make arbitrary text safe for one-line display and logs: strip control and
+* invisible characters, collapse whitespace runs, truncate with an ellipsis.
+*
+* @param input - raw text (possibly hostile).
+* @param maxLength - output length cap (default 200).
+* @returns the sanitized text.
+*/
+function sanitizeText(input, maxLength = 200) {
+	const text = input.replace(CONTROL_OR_INVISIBLE, "").replace(/\s+/gu, " ").trim();
+	if (text.length <= maxLength) return text;
+	const cut = maxLength - 1;
+	return cut > 0 ? `${text.slice(0, cut)}…` : "";
+}
+//#endregion
+//#region src/governance.ts
+/**
+* Check every budget scope for one session after new usage landed.
+*
+* @param config - resolved plugin config.
+* @param aggregator - the runtime aggregator.
+* @param sessionId - owning session id.
+* @param hooks - alert/block sinks.
+* @param at - current timestamp (injected for tests).
+* @returns the per-scope decisions, in scope order.
+*/
+function checkBudgets(config, aggregator, sessionId, hooks, at) {
+	const scopes = [
+		{
+			scope: "session",
+			used: aggregator.sessionUsage(sessionId),
+			cap: config.budgets.session
+		},
+		{
+			scope: "daily",
+			used: aggregator.todayUsage(),
+			cap: config.budgets.daily
+		},
+		{
+			scope: "monthly",
+			used: aggregator.monthUsage(),
+			cap: config.budgets.monthly
+		}
+	];
+	const decisions = [];
+	for (const { scope, used, cap } of scopes) {
+		if (cap === void 0 || cap <= 0) {
+			decisions.push({
+				scope,
+				capUsd: void 0,
+				usedUsd: used.costUsd,
+				ratio: 0,
+				state: "ok"
+			});
+			continue;
+		}
+		const ratio = used.costUsd / cap;
+		const state = used.costUsd >= cap ? "over" : used.costUsd >= cap * config.warnRatio ? "warn" : "ok";
+		decisions.push({
+			scope,
+			capUsd: cap,
+			usedUsd: used.costUsd,
+			ratio,
+			state
+		});
+		if (state === "ok" || !config.alertsEnabled) continue;
+		if (aggregator.lastAlertAge(scope, state, at) < config.alertCooldownMs) continue;
+		aggregator.recordAlert({
+			scope,
+			kind: state,
+			at,
+			usedUsd: used.costUsd,
+			capUsd: cap
+		});
+		hooks.onAlert(decisions[decisions.length - 1]);
+		if (state === "over") {
+			if (config.overLimit === "block" || config.overLimit === "degrade") {
+				aggregator.blockScope(scope);
+				hooks.onBlock(scope, degradationFor(config, aggregator, scope));
+			}
+		}
+	}
+	return decisions;
+}
+/** The degradation pair for the current attribution, when configured. */
+function degradationFor(config, aggregator, _scope) {
+	const model = aggregator.attribution().model;
+	if (model === "") return void 0;
+	const to = config.degradation[model];
+	if (to === void 0 || to === "") return void 0;
+	return {
+		from: model,
+		to
+	};
+}
+/** Sanitize a webhook URL for logs: scheme + host only, credentials dropped. */
+function webhookDisplay(url) {
+	try {
+		const parsed = new URL(url);
+		return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+	} catch {
+		return sanitizeText(url, 80);
+	}
+}
+/**
+* Fire one threshold-alert webhook POST (JSON body). Failures are swallowed
+* and returned — alerts must never crash the hot path. The URL itself is
+* never logged with credentials attached.
+*
+* @param url - validated webhook URL.
+* @param payload - JSON-serializable payload.
+* @param timeoutMs - request timeout.
+* @param logger - warn sink for failures.
+* @returns the outcome (ok or the error message).
+*/
+async function sendWebhook(url, payload, timeoutMs, logger) {
+	try {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		try {
+			const response = await fetch(url, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify(payload),
+				signal: controller.signal
+			});
+			if (response.status < 200 || response.status >= 300) return {
+				ok: false,
+				error: `webhook answered HTTP ${response.status}`
+			};
+			return { ok: true };
+		} finally {
+			clearTimeout(timer);
+		}
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		logger.warn(`budget webhook alert failed (${webhookDisplay(url)}): ${message}`);
+		return {
+			ok: false,
+			error: message
+		};
+	}
+}
+//#endregion
+//#region src/events.ts
+/** The alert audit event type. */
+const ALERT_EVENT = "budget/alert";
+/** The block audit event type. */
+const BLOCK_EVENT = "budget/block";
+//#endregion
+//#region src/service.ts
+/** Effective cap lookup: runtime override first, then the config. */
+function effectiveCap(settings, config, scope) {
+	if (scope === "session") return settings.sessionCapUsd ?? config.budgets.session ?? null;
+	if (scope === "daily") return settings.dailyCapUsd ?? config.budgets.daily ?? null;
+	return settings.monthlyCapUsd ?? config.budgets.monthly ?? null;
+}
+/** One latency window's percentile summary. */
+function latencySummary(samples) {
+	if (samples.length === 0) return {
+		min: null,
+		p50: null,
+		p95: null,
+		max: null,
+		samples: 0
+	};
+	const sorted = [...samples].sort((a, b) => a - b);
+	const at = (p) => sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * p))] ?? 0;
+	return {
+		min: sorted[0] ?? null,
+		p50: at(.5),
+		p95: at(.95),
+		max: sorted[sorted.length - 1] ?? null,
+		samples: sorted.length
+	};
+}
+/**
+* The `budget` Typert Remote service. Constructed by `src/index.ts` with the
+* shared aggregator, the resolved config, and the runtime settings object;
+* mounted through `ctx.plugin`.
+*/
+var BudgetService = class extends TypertRemoteService {
+	bindings;
+	/** No service dependencies: pure status surface over injected bindings. */
+	static inject = [];
+	/**
+	* @param ctx - the mounting context.
+	* @param bindings - aggregator, resolved config, runtime settings, and the degraded-model probe.
+	*/
+	constructor(ctx, bindings) {
+		super(ctx, "budget");
+		this.bindings = bindings;
+	}
+	/** Assemble the wire snapshot for one session. */
+	status(sessionId) {
+		const { aggregator, config, settings } = this.bindings;
+		const id = sessionId ?? this.bindings.sessionId();
+		const snapshot = aggregator.snapshotFor(id === "" ? sessionId ?? "" : id);
+		const scopes = [
+			"session",
+			"daily",
+			"monthly"
+		].map((scope) => {
+			const used = scope === "session" ? snapshot.session : scope === "daily" ? snapshot.today : snapshot.thisMonth;
+			const cap = effectiveCap(settings, config, scope);
+			return {
+				scope,
+				capUsd: cap,
+				usedUsd: used.costUsd,
+				ratio: cap === null || cap <= 0 ? 0 : used.costUsd / cap,
+				tokens: used.inputTokens + used.outputTokens + used.cacheReadTokens + used.cacheWriteTokens,
+				carbonKg: used.carbonKg
+			};
+		});
+		const models = snapshot.models.map((entry) => ({
+			provider: entry.provider,
+			model: entry.model,
+			inputTokens: entry.inputTokens + entry.cacheReadTokens + entry.cacheWriteTokens,
+			outputTokens: entry.outputTokens,
+			costUsd: entry.costUsd,
+			carbonKg: entry.carbonKg,
+			latency: latencySummary(entry.latencyMs)
+		}));
+		const degraded = this.bindings.degradation();
+		return {
+			scopes,
+			models,
+			alerts: snapshot.alerts.map((alert) => ({ ...alert })),
+			blockedScopes: [...snapshot.blockedScopes],
+			currency: {
+				code: config.currency.code,
+				rate: config.currency.rate,
+				decimals: config.currency.decimals
+			},
+			alertsEnabled: settings.alertsEnabled,
+			desktopNotifications: settings.desktopNotifications,
+			degradedModel: degraded === void 0 ? null : degraded.to
+		};
+	}
+	/** Apply the panel's runtime settings and return the refreshed snapshot. */
+	setSettings(settingsJson) {
+		let parsed;
+		try {
+			parsed = JSON.parse(settingsJson);
+		} catch (error) {
+			throw new TypeError(`budget.setSettings requires a JSON payload: ${error instanceof Error ? error.message : "invalid JSON"}`);
+		}
+		const validated = BUDGET_SETTINGS_SCHEMA.parse(parsed);
+		const settings = this.bindings.settings;
+		settings.sessionCapUsd = validated.sessionCapUsd;
+		settings.dailyCapUsd = validated.dailyCapUsd;
+		settings.monthlyCapUsd = validated.monthlyCapUsd;
+		settings.alertsEnabled = validated.alertsEnabled;
+		settings.desktopNotifications = validated.desktopNotifications;
+		return this.status();
+	}
+	/** Lift one blocked scope and return the refreshed snapshot. */
+	unblock(scope) {
+		this.bindings.aggregator.unblockScope(scope);
+		this.bindings.onUnblock?.(scope);
+		return this.status();
+	}
+};
+//#endregion
+//#region src/command.ts
+const EN_MESSAGES = {
+	hint: "[unblock <scope> | models]",
+	unlimited: "unlimited",
+	blocked: "BLOCKED",
+	usage: "usage: /budget [unblock session|daily|monthly | models]",
+	unknownScope: (scope) => `unknown scope "${scope}" (session | daily | monthly)`,
+	unblocked: (scope) => `budget scope "${scope}" unblocked`,
+	noModels: "no model usage recorded yet"
+};
+const ZH_MESSAGES = {
+	hint: "[unblock <scope> | models]",
+	unlimited: "不限",
+	blocked: "已阻断",
+	usage: "用法：/budget [unblock session|daily|monthly | models]",
+	unknownScope: (scope) => `未知作用域 "${scope}"（session | daily | monthly）`,
+	unblocked: (scope) => `预算作用域 "${scope}" 已解除阻断`,
+	noModels: "尚未记录到任何模型用量"
+};
+/** Format one USD amount through the display currency. */
+function money(status, usd) {
+	return `${(usd * status.currency.rate).toFixed(status.currency.decimals)} ${status.currency.code}`;
+}
+/** Render the overview body for one snapshot. */
+function renderBudgetOverview(status, messages) {
+	const lines = [];
+	for (const scope of status.scopes) {
+		const capText = scope.capUsd === null ? messages.unlimited : money(status, scope.capUsd);
+		const blocked = status.blockedScopes.includes(scope.scope) ? ` ${messages.blocked}` : "";
+		lines.push(`${scope.scope}: ${money(status, scope.usedUsd)} / ${capText} (${Math.round(scope.ratio * 100)}% · ${scope.tokens} tokens · ${scope.carbonKg.toFixed(4)} kg CO2e)${blocked}`);
+	}
+	if (status.models.length === 0) lines.push(messages.noModels);
+	else for (const model of status.models.slice(0, 8)) {
+		const p50 = model.latency.p50 === null ? "-" : `${model.latency.p50}ms`;
+		lines.push(`${model.provider}/${model.model}: ${money(status, model.costUsd)} (${model.inputTokens} in / ${model.outputTokens} out · p50 ${p50} · ${model.carbonKg.toFixed(4)} kg CO2e)`);
+	}
+	if (status.degradedModel !== null) lines.push(`degraded model: ${status.degradedModel}`);
+	return lines.join("\n");
+}
+/** Parse the raw input after `/budget`. */
+function parseBudgetArgs(rawInput) {
+	const text = rawInput.trim();
+	if (text === "") return { kind: "overview" };
+	if (text === "models") return { kind: "models" };
+	const unblock = /^unblock\s+(session|daily|monthly)$/u.exec(text);
+	if (unblock !== null) return {
+		kind: "unblock",
+		scope: unblock[1]
+	};
+	return { kind: "usage" };
+}
+/** Render the per-model breakdown body. */
+function renderBudgetModels(status, _messages) {
+	if (status.models.length === 0) return _messages.noModels;
+	return status.models.map((model) => `${model.provider}/${model.model}: ${money(status, model.costUsd)} (${model.inputTokens} in / ${model.outputTokens} out · p50 ${model.latency.p50 === null ? "-" : `${model.latency.p50}ms`})`).join("\n");
+}
+/**
+* Build the `/budget` command definition.
+*
+* @param service - the budget service (snapshot + unblock).
+* @param language - output language.
+* @returns the command definition.
+*/
+function budgetCommand(service, language = "en") {
+	const messages = language === "zh" ? ZH_MESSAGES : EN_MESSAGES;
+	return {
+		name: "budget",
+		description: "Show per-scope budget usage (tokens, cost, carbon, latency) and lift a blocked scope with \"unblock session|daily|monthly\"",
+		input: { hint: messages.hint },
+		handler: ({ rawInput, agent }) => {
+			const parsed = parseBudgetArgs(rawInput);
+			if (parsed.kind === "usage") return {
+				kind: "error",
+				text: messages.usage
+			};
+			const sessionId = String(agent.session.id);
+			if (parsed.kind === "unblock") {
+				const scope = parsed.scope;
+				if (scope !== "session" && scope !== "daily" && scope !== "monthly") return {
+					kind: "error",
+					text: messages.unknownScope(scope)
+				};
+				const status = service.unblock(scope);
+				return {
+					kind: "success",
+					text: `${messages.unblocked(scope)}\n${renderBudgetOverview(status, messages)}`
+				};
+			}
+			const status = service.status(sessionId);
+			return {
+				kind: "success",
+				text: parsed.kind === "models" ? renderBudgetModels(status, messages) : renderBudgetOverview(status, messages)
+			};
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+const name = "dsh-budget";
+/** Hard services: the session store every aggregation keys off. */
+const inject = ["sessions"];
+/** The short-circuit stream the blocker yields when a scope is blocked. */
+function blockedStream(message, code) {
+	const finish = {
+		kind: "error",
+		failure: {
+			message,
+			code
+		}
+	};
+	return (async function* () {
+		yield {
+			type: "block-start",
+			index: 0,
+			blockType: "text"
+		};
+		yield {
+			type: "text-delta",
+			index: 0,
+			text: message
+		};
+		yield {
+			type: "block-end",
+			index: 0,
+			block: {
+				type: "text",
+				text: message
+			}
+		};
+		yield {
+			type: "finish",
+			reason: finish
+		};
+	})();
+}
+/**
+* Mount the plugin: resolve config, build the aggregator, wire the session
+* event feed, the budget checks, the `llm/stream` blocker, the webhook
+* alerts, the `budget` Remote service, and the `/budget` command.
+*
+* @param ctx - the plugin context (host).
+* @param config - raw plugin config.
+*/
+async function apply(ctx, config) {
+	const resolved = resolveConfig(config);
+	const logger = ctx.logger("budget");
+	const aggregator = new BudgetAggregator(resolved);
+	const settings = {
+		sessionCapUsd: resolved.budgets.session ?? null,
+		dailyCapUsd: resolved.budgets.daily ?? null,
+		monthlyCapUsd: resolved.budgets.monthly ?? null,
+		alertsEnabled: resolved.alertsEnabled,
+		desktopNotifications: resolved.desktopNotifications
+	};
+	let degradation;
+	const append = (session, type, event) => {
+		queueMicrotask(() => {
+			try {
+				session.append(type, event);
+			} catch (error) {
+				logger.warn(`audit append failed: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		});
+	};
+	const hooks = {
+		onAlert: (decision) => {
+			if (decision.capUsd === void 0 || decision.state === "ok") return;
+			logger.warn(`budget ${decision.scope} ${decision.state}: ${decision.usedUsd.toFixed(4)} USD of ${decision.capUsd} USD`);
+			const session = currentSession();
+			if (session !== void 0) append(session, ALERT_EVENT, {
+				scope: decision.scope,
+				kind: decision.state,
+				usedUsd: decision.usedUsd,
+				capUsd: decision.capUsd
+			});
+			if (resolved.webhookUrl !== void 0 && settings.alertsEnabled) sendWebhook(resolved.webhookUrl, {
+				plugin: "dsh-budget",
+				scope: decision.scope,
+				kind: decision.state,
+				usedUsd: decision.usedUsd,
+				capUsd: decision.capUsd
+			}, resolved.webhookTimeoutMs, logger);
+		},
+		onBlock: (scope, pair) => {
+			degradation = pair;
+			const session = currentSession();
+			if (session !== void 0) append(session, BLOCK_EVENT, {
+				scope,
+				blocked: true,
+				...pair === void 0 ? {} : { degradation: pair }
+			});
+		}
+	};
+	/** The session that the plugin attributes audits to (the latest observed). */
+	let lastSession;
+	const currentSession = () => lastSession;
+	ctx.on("session/event", (session, event) => {
+		try {
+			lastSession = session;
+			if (event.type === "request/header") {
+				aggregator.setAttribution(event.data.header.config.provider, event.data.header.config.model);
+				return;
+			}
+			if (event.type === "assistant/message") {
+				const usage = event.data.usage;
+				if (usage === void 0) return;
+				const sessionId = String(session.id);
+				aggregator.recordUsage(sessionId, usage);
+				checkBudgets(resolved, aggregator, sessionId, hooks, Date.now());
+			}
+		} catch (error) {
+			logger.warn(`session "${session.id}": budget event handling failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	});
+	if (ctx.get("llm") !== void 0) ctx.on("llm/stream", function(_options, next) {
+		const blocked = aggregator.blockedScopes;
+		if (blocked.length === 0) return next();
+		const capText = blocked.map((scope) => {
+			return {
+				scope,
+				cap: effectiveCap(settings, resolved, scope)
+			};
+		}).map((entry) => `${entry.scope} (${entry.cap === null ? "unlimited" : `${entry.cap} USD`})`).join(", ");
+		const guidance = degradation === void 0 ? `budget blocked for ${capText}. Ask the user to lift the block with "/budget unblock <scope>" before continuing.` : `budget blocked for ${capText}. Continue with the degraded model "${degradation.to}" (or ask the user to lift the block with "/budget unblock <scope>").`;
+		logger.warn(`blocking llm stream: ${guidance}`);
+		return blockedStream(guidance, "BUDGET_BLOCKED");
+	}, { prepend: true });
+	if (resolved.latency.enabled) ctx.on("llm/stream", async function* (options, next) {
+		const started = Date.now();
+		const model = String(options.model ?? "");
+		try {
+			yield* await next();
+		} finally {
+			if (model !== "") aggregator.recordLatency(model, Date.now() - started);
+		}
+	});
+	await ctx.plugin(BudgetService, {
+		aggregator,
+		config: resolved,
+		settings,
+		sessionId: () => lastSession === void 0 ? "" : String(lastSession.id),
+		degradation: () => degradation,
+		onUnblock: (scope) => {
+			const session = currentSession();
+			if (session !== void 0) append(session, BLOCK_EVENT, {
+				scope,
+				blocked: false
+			});
+		}
+	});
+	const commands = ctx.get("commands");
+	if (commands !== void 0) ctx.effect(() => commands.register(budgetCommand(ctx.get("budget"), resolved.outputLanguage)), "dsh-budget: /budget command");
+}
+//#endregion
+export { ALERT_EVENT, BLOCK_EVENT, BudgetAggregator, BudgetService, Config, apply, budgetCommand, checkBudgets, degradationFor, effectiveCap, inject, name, parseBudgetArgs, renderBudgetModels, renderBudgetOverview, resolveConfig };