dsh-token-total 1.0.7 → 1.0.9

package/lib/index.js

@@ -772,8 +772,16 @@ var UsageStore = class {
 	/** Fold ONLY the failure count of a sample into the day and hour rows. The
 	*  failure upgrade pass uses this: its replay walks logs the token passes
 	*  already consumed, so the tokens and the request marker must not be added
-	*  a second time — only the failed-call counter may move. */
+	*  a second time — only the failed-call counter may move.
+	*
+	*  A sample WITHOUT the `failed` marker counts NOTHING here. The pass folds
+	*  whole session logs, which are mostly successful calls: passing every
+	*  folded sample through a write that hardcodes `failed: true` would count
+	*  each call's request marker AND token sample as two extra "failures" —
+	*  exactly how stores upgrading through v1.0.2–v1.0.8 ended up with
+	*  failures ≈ 2 × requests on every pre-upgrade day ("失败的比总的都多"). */
 	async recordFailure(sample) {
+		if (!sample.failed) return;
 		await this.record({
 			day: sample.day,
 			hour: sample.hour,
@@ -1316,7 +1324,7 @@ var UsageCollector = class UsageCollector {
 			const concurrency = this.options.backfillConcurrency ?? 4;
 			let next = 0;
 			const completed = [];
-			const writeSample = target === "hours" ? (sample) => this.store.recordHours(sample) : target === "failures" ? (sample) => this.store.recordFailure(sample) : (sample) => this.store.record(sample);
+			const writeSample = target === "hours" ? (sample) => this.store.recordHours(sample) : target === "failures" ? (sample) => sample.failed ? this.store.recordFailure(sample) : Promise.resolve() : (sample) => this.store.record(sample);
 			const flushCompleted = async () => {
 				if (completed.length === 0) return;
 				const batch = completed.splice(0, completed.length);
@@ -1518,6 +1526,273 @@ async function resolveModelNames(modelRefs, llm) {
 	return names;
 }
 //#endregion
+//#region src/context-window.ts
+/** ASCII-ish characters per token (the host estimator's ratio). */
+const ASCII_CHARS_PER_TOKEN = 4;
+/** Wide (CJK, kana, hangul) characters per token: these bill ~1 token/char. */
+const WIDE_CHARS_PER_TOKEN = 1.5;
+/** A supplementary-plane emoji is worth a few wide characters. */
+const EMOJI_TOKEN_EQUIVALENT = 3;
+/** Serialized JSON punctuation/keys cost a token or two per schema node. */
+const TOOL_SCHEMA_OVERHEAD_TOKENS = 8;
+/** Per-message framing the provider bills on top of the content. */
+const MESSAGE_OVERHEAD_TOKENS = 4;
+/** A rendered image is billed in tiles, not characters. */
+const IMAGE_TOKENS = 1100;
+/** A category keeps its biggest rows until this share of its tokens is covered. */
+const KEEP_SHARE = .85;
+/** Hard cap on rows kept per category before the rest folds into one block. */
+const MAX_ROWS_PER_CATEGORY = 10;
+/** Tool names whose results are file payloads (they group by path). */
+const FILE_TOOLS = /* @__PURE__ */ new Set([
+	"read",
+	"write",
+	"edit",
+	"multiedit",
+	"notebook_read",
+	"notebook_edit"
+]);
+/** Legend/treemap order; also the tie-break for equal-sized rows. */
+const CATEGORY_ORDER = [
+	"system",
+	"tools",
+	"memory",
+	"files",
+	"results",
+	"conversation"
+];
+/** Approximate token count of one string (see the header comment). */
+function estimateTokens(text) {
+	if (text === "") return 0;
+	let ascii = 0;
+	let wide = 0;
+	for (const ch of text) {
+		const code = ch.codePointAt(0) ?? 0;
+		if (code >= 126976 && code <= 129791) wide += EMOJI_TOKEN_EQUIVALENT;
+		else if (code < 11904) ascii++;
+		else wide++;
+	}
+	return Math.ceil(ascii / ASCII_CHARS_PER_TOKEN + wide / WIDE_CHARS_PER_TOKEN);
+}
+/** Approximate tokens of any JSON-ish value, counting its strings only. */
+function valueTokens(value) {
+	if (typeof value === "string") return estimateTokens(value);
+	if (typeof value === "number" || typeof value === "boolean") return 1;
+	if (Array.isArray(value)) return value.reduce((sum, item) => sum + valueTokens(item), 0);
+	if (value !== null && typeof value === "object") {
+		let sum = 0;
+		for (const [key, item] of Object.entries(value)) {
+			if (key === "replayState" || key === "thinkingSignature" || key === "textSignature") continue;
+			sum += valueTokens(item);
+		}
+		return sum;
+	}
+	return 0;
+}
+/** Approximate tokens of one replayed message (content + framing). */
+function messageTokens(message) {
+	const content = message?.content;
+	const blocks = Array.isArray(content) ? content : content === void 0 ? [] : [content];
+	let sum = MESSAGE_OVERHEAD_TOKENS;
+	for (const block of blocks) {
+		const kind = block?.type;
+		if (kind === "image" || kind === "image-url") {
+			sum += IMAGE_TOKENS;
+			continue;
+		}
+		if (kind === "text" && typeof block.text === "string") {
+			sum += valueTokens(block.text);
+			continue;
+		}
+		sum += valueTokens(block);
+	}
+	return sum;
+}
+/** Prompt tokens one answer actually sent, as the provider billed it: its total
+*  minus the output it generated, or the uncached plus cached input when the
+*  provider reported no total. Null when there is no usage at all. */
+function promptTokensOf(usage) {
+	const record = usage;
+	const total = Number(record?.totalTokens) || 0;
+	const output = Number(record?.outputTokens) || 0;
+	if (total > output) return total - output;
+	const input = Number(record?.inputTokens) || 0;
+	const cached = Number(record?.cacheReadTokens) || 0;
+	return input + cached > 0 ? input + cached : null;
+}
+/** Fold one category's rows: keep the biggest until KEEP_SHARE is covered (and
+*  never more than MAX_ROWS_PER_CATEGORY), then merge the tail into one row so
+*  a session with 200 tool calls still yields a readable treemap. */
+function foldDrafts(drafts) {
+	const items = [];
+	for (const category of CATEGORY_ORDER) {
+		const rows = drafts.filter((row) => row.category === category).sort((a, b) => b.tokens - a.tokens);
+		if (rows.length === 0) continue;
+		const total = rows.reduce((sum, row) => sum + row.tokens, 0);
+		const kept = [];
+		let covered = 0;
+		for (const row of rows) {
+			if (kept.length >= MAX_ROWS_PER_CATEGORY) break;
+			if (kept.length > 0 && covered >= total * KEEP_SHARE) break;
+			kept.push(row);
+			covered += row.tokens;
+		}
+		const folded = rows.slice(kept.length);
+		for (const row of kept) items.push({
+			key: `${category}:${row.kind ?? row.label}`,
+			category,
+			...row.kind === void 0 ? {} : { kind: row.kind },
+			label: row.label,
+			count: row.count,
+			tokens: row.tokens
+		});
+		if (folded.length > 0) items.push({
+			key: `${category}:rest`,
+			category,
+			kind: "rest",
+			label: "",
+			count: folded.length,
+			tokens: folded.reduce((sum, row) => sum + row.tokens, 0)
+		});
+	}
+	return items.sort((a, b) => b.tokens - a.tokens || CATEGORY_ORDER.indexOf(a.category) - CATEGORY_ORDER.indexOf(b.category));
+}
+/** Build the context-window snapshot from one session's own events. Returns
+*  null for an empty log so the panel can hide itself. */
+function buildSessionContextWindow(events) {
+	if (events.length === 0) return null;
+	const ordered = [...events].sort((a, b) => a.seq - b.seq);
+	const shadowed = /* @__PURE__ */ new Set();
+	const summaries = [];
+	const callNames = /* @__PURE__ */ new Map();
+	let tools = [];
+	let headerRoute = null;
+	let route = null;
+	let cache = null;
+	/** What the newest answer actually sent, which is what the window holds now. */
+	let billed = null;
+	for (const event of ordered) {
+		const data = event.data ?? {};
+		if (event.type === "compaction/prune" || event.type === "compaction/summary") {
+			for (const seq of Array.isArray(data.shadowedSeqs) ? data.shadowedSeqs : []) shadowed.add(Number(seq));
+			const range = data.shadowedRange;
+			if (typeof range?.start === "number" && typeof range?.end === "number") for (let seq = range.start; seq <= range.end; seq++) shadowed.add(seq);
+			if (event.type === "compaction/summary") {
+				summaries.push({
+					seq: event.seq,
+					tokens: messageTokens({ content: data.summary })
+				});
+				const usage = data.usage;
+				if (usage) {
+					cache = {
+						hit: Number(usage.cacheReadTokens) || 0,
+						miss: (Number(usage.inputTokens) || 0) + (Number(usage.cacheWriteTokens) || 0)
+					};
+					const summaryBilled = promptTokensOf(usage);
+					if (summaryBilled !== null) billed = summaryBilled;
+				}
+			}
+			continue;
+		}
+		if (event.type === "tool/call" && typeof data.callId === "string") {
+			callNames.set(data.callId, String(data.name ?? ""));
+			continue;
+		}
+		if (event.type === "request/header") {
+			const header = data.header ?? {};
+			if (Array.isArray(header.tools)) tools = header.tools;
+			const config = header.config ?? {};
+			if (typeof config.provider === "string" || typeof config.model === "string") headerRoute = {
+				provider: String(config.provider ?? ""),
+				model: String(config.model ?? "")
+			};
+			continue;
+		}
+		if (event.type === "request/context") {
+			route = {
+				provider: String(data.provider ?? ""),
+				model: String(data.model ?? ""),
+				contextWindow: typeof data.contextWindow === "number" && data.contextWindow > 0 ? data.contextWindow : null
+			};
+			continue;
+		}
+		if (event.type === "assistant/message" && data.usage) {
+			const usage = data.usage;
+			cache = {
+				hit: Number(usage.cacheReadTokens) || 0,
+				miss: (Number(usage.inputTokens) || 0) + (Number(usage.cacheWriteTokens) || 0)
+			};
+			billed = promptTokensOf(usage);
+		}
+	}
+	const drafts = /* @__PURE__ */ new Map();
+	const add = (category, label, tokens, kind) => {
+		const key = `${category}\u0000${kind ?? ""}\u0000${label}`;
+		const draft = drafts.get(key);
+		if (draft === void 0) drafts.set(key, {
+			category,
+			...kind === void 0 ? {} : { kind },
+			label,
+			count: 1,
+			tokens
+		});
+		else {
+			draft.count++;
+			draft.tokens += tokens;
+		}
+	};
+	for (const event of ordered) {
+		if (shadowed.has(event.seq)) continue;
+		const data = event.data ?? {};
+		switch (event.type) {
+			case "system/message": {
+				const kind = String(data.message?.source?.kind ?? data.source?.kind ?? "system-prompt");
+				add(kind === "system-prompt" ? "system" : "memory", "", messageTokens(data.message ?? { content: data.content }), kind);
+				break;
+			}
+			case "user/message": {
+				const kind = String(data.source?.kind ?? data.message?.source?.kind ?? "user");
+				const message = data.message ?? { content: data.content };
+				if (kind === "user") add("conversation", "", messageTokens(message), "user");
+				else add("memory", "", messageTokens(message), kind);
+				break;
+			}
+			case "assistant/message":
+				add("conversation", "", messageTokens(data.message ?? { content: data.content }), "assistant");
+				break;
+			case "tool/result": {
+				const message = data.message ?? {};
+				const callId = String(message.toolCallId ?? message.source?.callId ?? "");
+				const name = callNames.get(callId) ?? "";
+				const path = typeof data.meta?.path === "string" ? data.meta.path : "";
+				const tokens = messageTokens(message);
+				if (path !== "" && (FILE_TOOLS.has(name) || name === "")) add("files", path, tokens);
+				else add("results", name === "" ? "tool" : name, tokens);
+				break;
+			}
+		}
+	}
+	for (const summary of summaries) if (summary.tokens > 0) add("memory", "", summary.tokens, "compaction-summary");
+	for (const tool of tools) {
+		const record = tool;
+		const name = String(record?.name ?? "");
+		if (name === "") continue;
+		add("tools", name, estimateTokens(name) + valueTokens(record?.description) + estimateTokens(JSON.stringify(record?.parameters ?? {})) + TOOL_SCHEMA_OVERHEAD_TOKENS);
+	}
+	const items = foldDrafts([...drafts.values()]);
+	return {
+		totalTokens: items.reduce((sum, item) => sum + item.tokens, 0),
+		contextWindow: route?.contextWindow ?? null,
+		provider: route?.provider || headerRoute?.provider || "",
+		model: route?.model || headerRoute?.model || "",
+		cacheHitTokens: cache?.hit ?? 0,
+		cacheMissTokens: cache?.miss ?? 0,
+		cacheKnown: cache !== null,
+		promptTokens: billed,
+		items
+	};
+}
+//#endregion
 //#region src/session-detail.ts
 const zero = () => ({
 	uncachedInputTokens: 0,
@@ -1844,7 +2119,8 @@ async function one(p, id, header, live) {
 		records,
 		requests,
 		averageFirstTokenMs: firsts.length ? firsts.reduce((a, b) => a + b, 0) / firsts.length : null,
-		tokensPerSecond: decodeRateOf(records)
+		tokensPerSecond: decodeRateOf(records),
+		context: buildSessionContextWindow(own)
 	};
 }
 async function buildSessionUsageDetail(persistence, sessions, rootId, ctx) {
@@ -1943,7 +2219,8 @@ async function buildSessionUsageDetail(persistence, sessions, rootId, ctx) {
 			};
 		}),
 		records,
-		routes: [...routeMap.values()]
+		routes: [...routeMap.values()],
+		context: parts[0]?.context ?? null
 	};
 }
 //#endregion

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

@@ -0,0 +1,18 @@
+import type { SessionContextCategory, SessionContextWindow } from '../wire.ts';
+import type { SessionUsageKey } from './session-usage-locales.ts';
+type T = (key: SessionUsageKey, params?: Record<string, string>) => string;
+/** The context-window panel above the Usage cards, in magpie's shape: the used
+ *  total and the model's window on the left, the newest answer's prompt-cache
+ *  split on the right, a treemap of what occupies the window below (with a
+ *  hover card per tile), and one legend row naming the six buckets with their
+ *  sizes. Every figure is an estimate, so the panel never claims an exact
+ *  count — and the live pill stamps when the estimate was last refreshed. */
+export declare function ContextWindowPanel({ context, t, updatedAt }: {
+    context: SessionContextWindow;
+    t: T;
+    /** Wall-clock ms of the last successful read, when the host reports one. */
+    updatedAt?: number | null;
+}): JSX.Element;
+/** Legend order shared with the CSS tone classes (kept exported for tests). */
+export declare const CONTEXT_LEGEND_ORDER: readonly SessionContextCategory[];
+export {};

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

@@ -1,14 +1,15 @@
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
 import type { SessionUsageDetail } from '../wire.ts';
 import { SESSION_USAGE_NS, type SessionUsageKey } from './session-usage-locales.ts';
-type T = (key: SessionUsageKey) => string;
+type T = (key: SessionUsageKey, params?: Record<string, string>) => string;
 export type SessionUsageViewProps = PropsLocale<typeof SESSION_USAGE_NS> & {
     sessionId: string;
 };
 /** Pure presentation export also used by offline visual regression fixtures. */
-export declare function SessionUsageContent({ detail, t }: {
+export declare function SessionUsageContent({ detail, t, updatedAt }: {
     detail: SessionUsageDetail;
     t: T;
+    updatedAt?: number | null;
 }): JSX.Element;
 export declare function SessionUsageView({ sessionId, t }: SessionUsageViewProps): JSX.Element;
 export {};

package/lib/types/client/context-window-core.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Pure helpers behind the context-window panel: the treemap squarifier, the
+ * per-category roll-up the legend prints, and the occupancy reading. Kept
+ * separate from the component so both are testable without a DOM.
+ */
+import type { SessionContextCategory, SessionContextItem, SessionContextWindow } from '../wire.ts';
+/** Legend order, also the color assignment order (see the CSS module). */
+export declare const CONTEXT_CATEGORY_ORDER: readonly SessionContextCategory[];
+/** One positioned treemap block in container pixels. */
+export interface TreemapBox {
+    key: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Per-category token totals in legend order, empty categories dropped. */
+export declare function contextCategoryTotals(items: readonly SessionContextItem[]): Array<{
+    key: SessionContextCategory;
+    tokens: number;
+}>;
+/** Window occupancy in whole percent, or null when the host never reported the
+ *  model's window (the panel then says "unknown" instead of guessing one). */
+export declare function contextWindowPercent(usedTokens: number, contextWindow: number | null): number | null;
+/** How much the replay estimate may drift from the billed prompt before the
+ *  panel stops treating them as the same number (rounding, framing tokens). */
+export declare const CONTEXT_ESTIMATE_TOLERANCE = 0.15;
+/** One reading of the snapshot for the headline: the billed prompt when the log
+ *  has one (exact), else the replay estimate. `estimateDiffers` marks the case
+ *  where the log carries text the model was never billed for — an upstream
+ *  compression plugin, say — so the panel can explain a treemap that sums
+ *  higher than the total. */
+export interface ContextReading {
+    usedTokens: number;
+    percent: number | null;
+    estimateTokens: number;
+    estimateDiffers: boolean;
+}
+export declare function contextReading(context: SessionContextWindow): ContextReading;
+/**
+ * Squarified treemap (Bruls, Huizing & van Wijk): tile `width`×`height` with
+ * one block per positive weight, proportional to its tokens and as close to
+ * square as the greedy row packing allows. Blocks come back in the input's
+ * descending-weight order, covering the whole area.
+ */
+export declare function treemapLayout(rows: ReadonlyArray<{
+    key: string;
+    tokens: number;
+}>, width: number, height: number): TreemapBox[];

package/lib/types/client/session-usage-locales.d.ts

@@ -59,6 +59,34 @@ export declare const usageZh: {
     live: string;
     asOf: string;
     refresh: string;
+    contextTitle: string;
+    contextUsed: string;
+    contextLive: string;
+    contextWindowKnown: string;
+    contextWindowUnknown: string;
+    contextCache: string;
+    contextCacheHit: string;
+    contextCacheMiss: string;
+    contextCachePending: string;
+    contextSystem: string;
+    contextTools: string;
+    contextMemory: string;
+    contextFiles: string;
+    contextResults: string;
+    contextConversation: string;
+    contextKindSystemPrompt: string;
+    contextKindRuntimeContext: string;
+    contextKindSkillCatalog: string;
+    contextKindTimeContext: string;
+    contextKindCompaction: string;
+    contextKindUser: string;
+    contextKindAssistant: string;
+    contextKindRest: string;
+    contextTimes: string;
+    contextEmpty: string;
+    contextTipShare: string;
+    contextTipWindow: string;
+    contextEstimateNote: string;
 };
 export type SessionUsageKey = keyof typeof usageZh;
 export declare const usageEn: Record<SessionUsageKey, string>;

package/lib/types/context-window.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Context-window composition: what the session's NEXT provider call carries.
+ *
+ * The panel above the Usage cards answers "what is inside the window right
+ * now", which is not what the log accumulated. So this walks one session's own
+ * events (fork-inherited ones never reach here) and rebuilds the message list a
+ * live request would replay:
+ * - `compaction/prune` / `compaction/summary` shadowed sequences drop out — the
+ *   compacted turn is gone from the request, not merely folded in the store;
+ * - a compaction summary stands in for the range it replaced, as injected
+ *   memory rather than conversation (the model never wrote it);
+ * - the tool catalogue is the NEWEST `request/header`'s list, since that is the
+ *   set the next call will send;
+ * - file reads group by path and the remaining tool results by tool name, so a
+ *   session that ran `pwsh` sixty times shows one block with its call count.
+ *
+ * Token counts are ESTIMATES from character counts: the host's own estimator
+ * bills ASCII at four characters per token, while CJK text bills closer to one
+ * token per character, so both rates are applied per character class and every
+ * figure is presented as approximate. Exact counts are unavailable here — the
+ * provider only reports a whole-prompt number after the call — but that billed
+ * number IS exact for the request it answered, so it ships alongside the
+ * estimate (`promptTokens`) and the panel prints it as the used total whenever
+ * the log has one. The two disagree when something upstream rewrites the prompt
+ * (a compression plugin, a gateway that trims history), because the stored log
+ * then holds more text than the model was ever billed for.
+ */
+import type { UsageSessionEvent } from './context-types.ts';
+import type { SessionContextWindow } from './wire.ts';
+/** Approximate token count of one string (see the header comment). */
+export declare function estimateTokens(text: string): number;
+/** Approximate tokens of one replayed message (content + framing). */
+export declare function messageTokens(message: unknown): number;
+/** Build the context-window snapshot from one session's own events. Returns
+ *  null for an empty log so the panel can hide itself. */
+export declare function buildSessionContextWindow(events: readonly UsageSessionEvent[]): SessionContextWindow | null;

package/lib/types/store.d.ts

@@ -228,7 +228,14 @@ export declare class UsageStore {
     /** Fold ONLY the failure count of a sample into the day and hour rows. The
      *  failure upgrade pass uses this: its replay walks logs the token passes
      *  already consumed, so the tokens and the request marker must not be added
-     *  a second time — only the failed-call counter may move. */
+     *  a second time — only the failed-call counter may move.
+     *
+     *  A sample WITHOUT the `failed` marker counts NOTHING here. The pass folds
+     *  whole session logs, which are mostly successful calls: passing every
+     *  folded sample through a write that hardcodes `failed: true` would count
+     *  each call's request marker AND token sample as two extra "failures" —
+     *  exactly how stores upgrading through v1.0.2–v1.0.8 ended up with
+     *  failures ≈ 2 × requests on every pre-upgrade day ("失败的比总的都多"). */
     recordFailure(sample: UsageSample): Promise<void>;
     /** The row identity a sample lands on: turn markers use the synthetic
      *  (turns) model, unlabelled calls the (unknown) one. */

package/lib/types/wire.d.ts

@@ -188,6 +188,56 @@ export interface SessionUsageDetail {
         model: string;
         status: 'idle' | 'running' | 'completed' | 'failed';
     }>;
+    /** The root session's live context composition, rendered above the cards.
+     *  Null when the log has no readable events (or on an older host). */
+    context?: SessionContextWindow | null;
+}
+/** The six buckets the context-window panel paints, in legend order. They are
+ *  the buckets a reader thinks in: the harness prompt, the tool catalogue, the
+ *  injected memory (runtime context, skill catalog, compaction summaries), the
+ *  files the agent read, the remaining tool results, and the conversation. */
+export type SessionContextCategory = 'system' | 'tools' | 'memory' | 'files' | 'results' | 'conversation';
+/** One block of the context-window treemap: a tool, one file path, one folded
+ *  group of the same tool, or one message bucket. `tokens` is an ESTIMATE from
+ *  character counts (see context-window.ts), so the panel renders it as ~N. */
+export interface SessionContextItem {
+    /** Row key, unique inside one snapshot. */
+    key: string;
+    category: SessionContextCategory;
+    /** What to print: a tool name, a file path, or (for `kind`-bearing rows) the
+     *  localized kind label the panel substitutes. */
+    label: string;
+    /** Machine kind the panel localizes ("system-prompt", "user", "rest", …).
+     *  Absent for rows whose label is itself the data (tool names, paths). */
+    kind?: string;
+    /** How many log entries folded into this row (messages, tool calls). */
+    count: number;
+    tokens: number;
+}
+/** The context-window snapshot: what the session's next provider call would
+ *  carry, reconstructed from its own log (pruned events dropped, a compaction
+ *  summary standing in for the range it replaced, the newest request's tool
+ *  catalogue). Null when the session has no readable events yet. */
+export interface SessionContextWindow {
+    /** Sum of every item's estimated tokens. */
+    totalTokens: number;
+    /** The model's window from the newest `request/context`, or null when the
+     *  host route never reported one (the panel then says "unknown"). */
+    contextWindow: number | null;
+    provider: string;
+    model: string;
+    /** Prompt-cache split of the newest answer: cache reads vs new prompt tokens. */
+    cacheHitTokens: number;
+    cacheMissTokens: number;
+    /** Whether any answer reported usage (the cache bar needs one to draw). */
+    cacheKnown: boolean;
+    /** Prompt tokens the provider billed on the newest answer
+     *  (`totalTokens − outputTokens`, or uncached + cached input): the real
+     *  occupancy. Upstream prompt compression can make it smaller than
+     *  `totalTokens`, which merely replays the stored log. */
+    promptTokens: number | null;
+    /** Treemap blocks, largest first. */
+    items: SessionContextItem[];
 }
 /** The backfill (historical session scan) progress state. */
 export interface BackfillStatus {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-token-total",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "DSH web plugin: token 用量统计看板 + 单会话（主智能体 + 子智能体）用量统计。提供今日/近3天/近7天/近1月/近3月/自定义筛选、六个汇总卡片、活跃热力图、缓存命中率折线与分模型柱状图、按模型/按供应商 Top5 列表。",
   "icon": "./icon.svg",
   "type": "module",

package/src/client/ContextWindowPanel.module.css

@@ -0,0 +1,77 @@
+/* The context-window panel: magpie's shape on this page's surfaces — a header
+ * with the model and a live pill, the used total beside the newest answer's
+ * prompt-cache split, a treemap of what occupies the window, and one legend row
+ * naming the six buckets. Category colors live as custom properties on the tone
+ * classes so the tile and the legend dot share one palette. */
+.panel { background:#fff; border:1px solid #e4e7ee; border-radius:12px; margin:0 0 16px; overflow:hidden; }
+.head { display:flex; align-items:center; justify-content:space-between; gap:10px; padding:12px 16px 0; }
+.headCollapsed { padding-bottom:12px; }
+.toggle { display:flex; align-items:center; gap:6px; min-width:0; background:none; border:0; padding:0; font:inherit; color:#394354; cursor:pointer; }
+.toggle h2 { font-size:13px; font-weight:600; margin:0; white-space:nowrap; }
+.chevron { flex:none; color:#99a1af; transition:transform .2s; }
+.chevronOpen { transform:rotate(90deg); }
+.headRight { display:flex; align-items:center; gap:8px; min-width:0; }
+.model { min-width:0; max-width:220px; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; font-size:11px; color:#8b93a4; }
+.livePill { display:inline-flex; align-items:center; gap:4px; flex:none; padding:1px 8px 1px 6px; border-radius:999px; background:#e9f8f1; color:#128a63; font-size:10px; font-weight:500; }
+.liveDot { width:5px; height:5px; border-radius:50%; background:#18a97b; box-shadow:0 0 0 2px #d6f2e5; }
+.liveTime { font-variant-numeric:tabular-nums; opacity:.85; }
+.toggle:focus-visible { outline:2px solid #2ab1c6; outline-offset:2px; }
+.body { padding:10px 16px 14px; }
+.body[hidden] { display:none; }
+.summary { display:grid; grid-template-columns:minmax(0,1fr) minmax(180px,260px); align-items:end; gap:18px; padding-bottom:12px; }
+.used { display:flex; flex-direction:column; gap:1px; min-width:0; }
+.label { font-size:11px; color:#8790a3; }
+.total { font-size:28px; font-weight:650; line-height:1.15; letter-spacing:-.6px; color:#1b2130; font-variant-numeric:tabular-nums; white-space:nowrap; }
+.total small { margin-left:4px; font-size:11px; font-weight:500; letter-spacing:0; color:#98a0ae; }
+.window { font-size:11px; color:#939aab; white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }
+.cache { display:flex; flex-direction:column; gap:6px; min-width:0; }
+.cacheBar { display:flex; width:100%; height:5px; border-radius:999px; overflow:hidden; background:#eef0f4; }
+.cacheHit { height:100%; background:#2ec4a0; }
+.cacheMiss { height:100%; background:#dfe3ea; }
+.cacheEmpty { display:block; width:100%; height:100%; background:repeating-linear-gradient(90deg,#e6e9ef 0 3px,transparent 3px 7px); }
+.cacheLegend { display:flex; flex-wrap:wrap; gap:2px 10px; font-size:10px; color:#8b93a4; font-variant-numeric:tabular-nums; }
+.cacheLegend i { display:inline-block; width:6px; height:6px; margin-right:4px; border-radius:50%; }
+.cacheHitDot { background:#2ec4a0; }
+.cacheMissDot { background:#dfe3ea; }
+.cachePending { color:#9aa3b3; }
+.note { margin:0 0 10px; padding:5px 8px; border:1px solid #f2e4c6; border-radius:6px; background:#fdf7ea; font-size:10.5px; line-height:1.5; color:#8a6a2a; font-variant-numeric:tabular-nums; }
+.map { position:relative; height:268px; border-radius:9px; overflow:hidden; }
+/* Slots glide into their new geometry when a refresh re-writes the estimate,
+ * so a change in the data reads as motion instead of a silent repaint. */
+.slot { position:absolute; box-sizing:border-box; padding:1.5px; transition:left .35s, top .35s, width .35s, height .35s; }
+.tile { display:flex; flex-direction:column; gap:1px; box-sizing:border-box; width:100%; height:100%; padding:5px 6px; border:1px solid var(--ctx-line); border-radius:7px; background:var(--ctx-soft); color:var(--ctx-ink); overflow:hidden; }
+.tileLabel { font-size:11px; font-weight:600; line-height:1.25; overflow:hidden; white-space:nowrap; text-overflow:ellipsis; }
+.tileSize { font-size:10px; opacity:.72; white-space:nowrap; overflow:hidden; text-overflow:ellipsis; font-variant-numeric:tabular-nums; }
+/* The hover card: exact figures a tile has no room to print. */
+.tip { position:absolute; z-index:2; box-sizing:border-box; width:220px; padding:8px 10px; border:1px solid #e0e4ec; border-radius:8px; background:#fff; box-shadow:0 8px 20px rgba(23,32,54,.12); font-size:11px; line-height:1.55; pointer-events:none; }
+.tipName { font-weight:600; color:#1b2130; overflow-wrap:anywhere; }
+.tipMeta { color:#6f7889; font-variant-numeric:tabular-nums; }
+.tipShare { color:#4a5567; font-variant-numeric:tabular-nums; }
+.legend { display:flex; flex-wrap:wrap; gap:5px 14px; list-style:none; margin:0; padding:10px 0 0; border-top:1px solid #f2f4f8; margin-top:10px; font-size:11px; color:#6f7889; }
+.legend li { display:flex; align-items:center; gap:5px; }
+.legendName { white-space:nowrap; }
+.legendValue { color:#98a0ae; font-variant-numeric:tabular-nums; }
+.swatch { display:inline-block; flex:none; box-sizing:border-box; width:9px; height:9px; border-radius:3px; background:var(--ctx-soft); background:color-mix(in srgb, var(--ctx) 50%, var(--ctx-soft)); border:1px solid var(--ctx-line); }
+.empty { margin:0; padding:24px 0; text-align:center; font-size:12px; color:#9aa2b1; }
+/* Category palette: `--ctx` is the accent tint, `--ctx-soft` the tile fill (and
+ * the legend swatch, so the dots match the tiles exactly), `--ctx-ink` the tile
+ * text, `--ctx-line` its hairline border. */
+.toneSystem { --ctx:#a346e6; --ctx-soft:#f6ecfd; --ctx-ink:#6c2e9e; --ctx-line:#ecdafa; }
+.toneTools { --ctx:#4f79f6; --ctx-soft:#eaf0fe; --ctx-ink:#3a5aa8; --ctx-line:#d9e3fb; }
+.toneMemory { --ctx:#8fb21e; --ctx-soft:#f1f5d8; --ctx-ink:#5a7012; --ctx-line:#dfe8bd; }
+.toneFiles { --ctx:#18a97b; --ctx-soft:#e6f6ee; --ctx-ink:#1c7a56; --ctx-line:#d2ecdf; }
+.toneResults { --ctx:#e8853f; --ctx-soft:#fdeee3; --ctx-ink:#a35d24; --ctx-line:#f7ddc8; }
+.toneConversation { --ctx:#c2327f; --ctx-soft:#fbe9f3; --ctx-ink:#8c2259; --ctx-line:#f2d3e4; }
+@media (max-width:700px) {
+  .head { padding:11px 12px 0; }
+  .headCollapsed { padding-bottom:11px; }
+  .body { padding:9px 12px 12px; }
+  .summary { grid-template-columns:minmax(0,1fr); gap:10px; }
+  .total { font-size:24px; }
+  .map { height:220px; }
+  .model { display:none; }
+}
+@media (prefers-reduced-motion:reduce) {
+  .chevron { transition:none; }
+  .slot { transition:none; }
+}