dsh-token-total 1.0.4 → 1.0.6

package/lib/index.js

@@ -1400,6 +1400,8 @@ var UsageCollector = class UsageCollector {
 			const clean = !signal?.aborted && this.status.error === void 0;
 			if ((target === "hours" || dayCursorWasEmpty) && clean) await this.store.markHoursReady();
 			if ((target === "failures" || dayCursorWasEmpty) && clean) await this.store.markFailuresReady();
+		} catch (err) {
+			this.status.error = err instanceof Error ? err.message : String(err);
 		} finally {
 			this.status.running = false;
 		}
@@ -1495,6 +1497,383 @@ async function resolveModelNames(modelRefs, llm) {
 	return names;
 }
 //#endregion
+//#region src/session-detail.ts
+const zero = () => ({
+	uncachedInputTokens: 0,
+	outputTokens: 0,
+	cacheReadTokens: 0,
+	cacheWriteTokens: 0
+});
+function add$1(a, b) {
+	a.uncachedInputTokens += b.uncachedInputTokens;
+	a.outputTokens += b.outputTokens;
+	a.cacheReadTokens += b.cacheReadTokens;
+	a.cacheWriteTokens += b.cacheWriteTokens;
+}
+function usageOf(x) {
+	const u = x?.usage ?? x;
+	return {
+		uncachedInputTokens: Number(u?.inputTokens) || 0,
+		outputTokens: Number(u?.outputTokens) || 0,
+		cacheReadTokens: Number(u?.cacheReadTokens) || 0,
+		cacheWriteTokens: Number(u?.cacheWriteTokens) || 0
+	};
+}
+function positive(u) {
+	return u.uncachedInputTokens + u.outputTokens + u.cacheReadTokens + u.cacheWriteTokens > 0;
+}
+function routeOf(x) {
+	const source = x?.message?.source ?? x?.source ?? x?.request ?? x?.context ?? x;
+	return {
+		provider: typeof source?.provider === "string" ? source.provider : "",
+		model: typeof source?.model === "string" ? source.model : ""
+	};
+}
+function streamUsage(data) {
+	let firstTime;
+	let usage;
+	for (const r of Array.isArray(data?.stream) ? data.stream : []) {
+		const t = typeof r?.time === "number" ? r.time : void 0;
+		if (firstTime === void 0 && t !== void 0 && (r?.type === "chunk" || r?.chunk?.type === "text" || r?.chunk?.type === "content")) firstTime = t;
+		if (r?.type === "chunk" && r?.chunk?.type === "usage") usage = usageOf(r.chunk);
+	}
+	return {
+		usage,
+		firstTime
+	};
+}
+function headerOf$1(item) {
+	const x = item;
+	if (x?.header?.id && typeof x.header.id === "string") return x.header;
+	return typeof x?.id === "string" && x.id ? x : null;
+}
+async function read(p, id, live) {
+	if (live?.snapshotEvents && typeof live.inheritedEventCount === "number") return {
+		events: live.snapshotEvents(),
+		cut: Math.max(0, live.inheritedEventCount)
+	};
+	if (p.open) {
+		const h = await p.open(id, "read");
+		const out = [];
+		try {
+			for (let off = 0;;) {
+				const page = await h.read(off, 500);
+				if (!page.events.length) break;
+				out.push(...page.events);
+				off += page.events.length;
+			}
+		} finally {
+			await h.close().catch(() => {});
+		}
+		return {
+			events: out,
+			cut: Math.max(0, Number(h.inheritedEventCount) || 0)
+		};
+	}
+	if (p.inspect) {
+		const x = await p.inspect(id);
+		return {
+			events: x.events,
+			cut: Math.max(0, Number(x.inheritedEventCount) || 0)
+		};
+	}
+	throw new Error("no readable persistence seam (need open or inspect)");
+}
+function nameOf(h, id) {
+	const x = h;
+	if (typeof x?.name === "string" && x.name) return x.name;
+	if (typeof x?.title === "string" && x.title) return x.title;
+	if (typeof x?.cwd === "string" && x.cwd) return x.cwd.split(/[\\/]/).filter(Boolean).pop() || id;
+	return id;
+}
+async function one(p, id, header, live) {
+	const { events, cut } = await read(p, id, live);
+	const fold = new UsageFold();
+	const totals = zero();
+	const records = [];
+	const byKey = /* @__PURE__ */ new Map();
+	let route = live?.requestContext?.() ?? {};
+	let ordinal = 0;
+	let currentTurn = 0;
+	let effort = "";
+	let pendingTopic = "";
+	const turnTopics = /* @__PURE__ */ new Map();
+	const own = events.filter((e) => !(cut > 0 && typeof e.seq === "number" && e.seq < cut));
+	let label = "", title = "";
+	for (const ev of own) {
+		const d = ev.data ?? {};
+		if (!label && ev.type === "subagent/descriptor" && typeof d.label === "string" && d.label.trim()) label = d.label.trim();
+		if (!title && ev.type === "session/title" && typeof d.title === "string" && d.title.trim()) title = d.title.trim();
+		if (label && title) break;
+	}
+	const name = label || title || nameOf(header, id);
+	for (const ev of own) {
+		const d = ev.data ?? {};
+		const turn = Number.isFinite(d.turn) ? d.turn : 0;
+		const step = Number.isFinite(d.step) ? d.step : 0;
+		if (ev.type === "request/context") {
+			route = {
+				...route,
+				...routeOf(d)
+			};
+			continue;
+		}
+		const r = routeOf(d);
+		if (r.provider || r.model) route = {
+			...route,
+			...r
+		};
+		if (ev.type === "turn/start") {
+			currentTurn = turn;
+			if (pendingTopic && !turnTopics.has(currentTurn)) {
+				turnTopics.set(currentTurn, pendingTopic);
+				pendingTopic = "";
+			}
+		} else if (ev.type === "user/message" && d.source?.kind === "user") {
+			const block = (Array.isArray(d.content) ? d.content : []).find((b) => b?.type === "text" && typeof b.text === "string");
+			const text = String(block?.text ?? "").replace(/\s+/g, " ").trim();
+			if (text) {
+				if (currentTurn > 0 && !turnTopics.has(currentTurn)) turnTopics.set(currentTurn, text);
+				else pendingTopic = text;
+			}
+		} else if (ev.type === "request/header") {
+			const e = d.header?.config?.reasoningEffort;
+			if (typeof e === "string" && e) {
+				effort = e;
+				for (const x of records) if (x.status === "running") x.effort = e;
+			}
+		}
+		let rec;
+		if (ev.type === "step/start" || ev.type === "llm/retry-started") {
+			const key = `${turn}:${step}`;
+			if (ev.type === "llm/retry-started" || !byKey.has(key)) {
+				const previous = byKey.get(key);
+				if (previous && ev.type === "llm/retry-started" && previous.status === "running") {
+					previous.status = "failed";
+					previous.finishedAt = ev.time;
+				}
+				rec = {
+					id: `${id}:${turn}:${step}:${ordinal++}`,
+					sessionId: id,
+					sessionName: name,
+					turn,
+					step,
+					startedAt: ev.time,
+					finishedAt: null,
+					provider: r.provider || route.provider || "",
+					model: r.model || route.model || "",
+					status: "running",
+					totals: zero(),
+					firstTokenMs: null,
+					tokensPerSecond: null,
+					turnName: "",
+					effort,
+					_attempt: ev.type === "llm/retry-started" ? 1 : 0,
+					_lastUsage: zero()
+				};
+				records.push(rec);
+				byKey.set(key, rec);
+			}
+		} else if (ev.type === "assistant/chunk" || ev.type === "assistant/message" || ev.type === "assistant/attempt") {
+			rec = byKey.get(`${turn}:${step}`);
+			if (!rec) {
+				rec = {
+					id: `${id}:${turn}:${step}:${ordinal++}`,
+					sessionId: id,
+					sessionName: name,
+					turn,
+					step,
+					startedAt: ev.time,
+					finishedAt: null,
+					provider: r.provider || route.provider || "",
+					model: r.model || route.model || "",
+					status: "running",
+					totals: zero(),
+					firstTokenMs: null,
+					tokensPerSecond: null,
+					turnName: "",
+					effort,
+					_attempt: 0,
+					_lastUsage: zero()
+				};
+				records.push(rec);
+				byKey.set(`${turn}:${step}`, rec);
+			}
+			if (r.provider) rec.provider = r.provider;
+			if (r.model) rec.model = r.model;
+			const su = streamUsage(d);
+			const u = ev.type === "assistant/message" ? d.usage ? usageOf(d) : su.usage : ev.type === "assistant/chunk" ? d.chunk?.type === "usage" ? usageOf(d.chunk) : void 0 : d.usage ? usageOf(d) : su.usage;
+			if (u) {
+				rec._lastUsage = u;
+				rec.totals = u;
+				if (positive(u) && rec.firstTokenMs === null) {
+					const rawFirst = su.firstTime ?? (typeof d.chunk?.time === "number" ? d.chunk.time : ev.time);
+					rec.firstTokenMs = Math.max(0, rawFirst - rec.startedAt);
+				}
+			}
+			if (ev.type !== "assistant/chunk") {
+				rec.finishedAt = ev.time;
+				rec.status = ev.type === "assistant/attempt" ? "failed" : "completed";
+			}
+			const elapsedMs = rec.finishedAt === null ? null : Math.max(0, rec.finishedAt - rec.startedAt);
+			if (elapsedMs !== null && elapsedMs > 0 && rec.totals.outputTokens > 0) rec.tokensPerSecond = rec.totals.outputTokens / (elapsedMs / 1e3);
+		} else if (ev.type === "turn/end") {
+			const recs = records.filter((x) => x.turn === turn && x.status === "running");
+			for (const x of recs) {
+				x.status = "interrupted";
+				x.finishedAt = ev.time;
+			}
+		} else if (ev.type === "compaction/summary") {
+			const u = usageOf(d);
+			rec = {
+				id: `${id}:compaction:${ordinal++}`,
+				sessionId: id,
+				sessionName: name,
+				turn: 0,
+				step: 0,
+				startedAt: ev.time,
+				finishedAt: ev.time,
+				provider: typeof d.provider === "string" ? d.provider : "",
+				model: typeof d.model === "string" ? d.model : "",
+				status: "completed",
+				totals: u,
+				firstTokenMs: null,
+				tokensPerSecond: null,
+				turnName: "",
+				effort: "",
+				_attempt: 0,
+				_lastUsage: u
+			};
+			records.push(rec);
+		}
+		const sample = fold.fold(ev);
+		if (sample && !sample.turn) add$1(totals, {
+			uncachedInputTokens: sample.inputTokens,
+			outputTokens: sample.outputTokens,
+			cacheReadTokens: sample.cacheReadTokens,
+			cacheWriteTokens: sample.cacheWriteTokens
+		});
+	}
+	const requests = records.length;
+	const firsts = records.map((x) => x.firstTokenMs).filter((x) => x !== null);
+	const outputSeconds = records.reduce((n, x) => n + x.totals.outputTokens, 0);
+	const elapsed = records.reduce((n, x) => n + (x.firstTokenMs ?? 0), 0);
+	for (const x of records) {
+		x.turnName = turnTopics.get(x.turn) ?? "";
+		delete x._attempt;
+		delete x._lastUsage;
+	}
+	return {
+		id,
+		name,
+		header,
+		totals,
+		records,
+		requests,
+		averageFirstTokenMs: firsts.length ? firsts.reduce((a, b) => a + b, 0) / firsts.length : null,
+		tokensPerSecond: elapsed > 0 ? outputSeconds / (elapsed / 1e3) : null
+	};
+}
+async function buildSessionUsageDetail(persistence, sessions, rootId, ctx) {
+	const headers = (await persistence.list(typeof persistence.open === "function" ? void 0 : void 0)).map(headerOf$1).filter((x) => x !== null);
+	const live = new Map((sessions?.list() ?? []).map((x) => [x.id, x]));
+	const children = /* @__PURE__ */ new Map();
+	for (const h of headers) if (h.parentSession) children.set(h.parentSession, [...children.get(h.parentSession) ?? [], h.id]);
+	for (const h of live.values()) {
+		const p = h.header?.parentSession ?? h.parentSession;
+		if (p) children.set(p, [...(children.get(p) ?? []).filter((x) => x !== h.id), h.id]);
+	}
+	const ids = [];
+	const seen = /* @__PURE__ */ new Set([rootId]);
+	const q = [rootId];
+	while (q.length) for (const c of children.get(q.shift()) ?? []) if (!seen.has(c)) {
+		seen.add(c);
+		ids.push(c);
+		q.push(c);
+	}
+	const all = [rootId, ...ids];
+	const parts = await Promise.all(all.map((id) => one(persistence, id, headers.find((h) => h.id === id), live.get(id))));
+	const root = parts[0];
+	const totals = zero();
+	const models = /* @__PURE__ */ new Map();
+	const records = parts.flatMap((x) => x.records);
+	for (const p of parts) add$1(totals, p.totals);
+	for (const r of records) {
+		const key = r.model || "(unknown)";
+		const m = models.get(key) ?? {
+			totals: zero(),
+			requests: 0,
+			providers: /* @__PURE__ */ new Set()
+		};
+		add$1(m.totals, r.totals);
+		m.requests++;
+		if (r.provider) m.providers.add(r.provider);
+		models.set(key, m);
+	}
+	const subagents = parts.slice(1).map((p) => ({
+		sessionId: p.id,
+		name: p.name,
+		totals: p.totals,
+		requests: p.requests,
+		averageFirstTokenMs: p.averageFirstTokenMs,
+		tokensPerSecond: p.tokensPerSecond
+	}));
+	const routeMap = /* @__PURE__ */ new Map();
+	for (const r of records) if (r.provider || r.model) {
+		const id = `${r.provider}/${r.model}`;
+		routeMap.set(id, {
+			id,
+			provider: r.provider,
+			name: r.provider,
+			model: r.model,
+			status: r.status === "running" ? "running" : r.status === "failed" ? "failed" : "completed"
+		});
+	}
+	const llm = ctx?.get?.("llm");
+	for (const x of llm?.listProviders?.() ?? []) if (x?.id && !routeMap.has(x.id)) routeMap.set(x.id, {
+		id: x.id,
+		provider: x.id,
+		name: x.name || x.id,
+		model: "",
+		status: "idle"
+	});
+	const providerNames = resolveProviderNames(llm);
+	const refOf = (provider, model) => provider ? `${provider}/${model}` : model;
+	const refs = [];
+	for (const [model, m] of models) if (model !== "(unknown)") {
+		if (m.providers.size) for (const provider of m.providers) refs.push(refOf(provider, model));
+		else refs.push(refOf("", model));
+	}
+	const names = await resolveModelNames(refs, llm);
+	const displayNameOf = (model, providers) => {
+		const keys = providers.size ? [...providers].map((provider) => refOf(provider, model)) : [refOf("", model)];
+		for (const key of keys) {
+			const resolved = names.get(key)?.trim();
+			if (resolved) return resolved;
+		}
+	};
+	return {
+		sessionId: rootId,
+		totals,
+		requests: parts.reduce((n, p) => n + p.requests, 0),
+		averageFirstTokenMs: root.averageFirstTokenMs,
+		tokensPerSecond: root.tokensPerSecond,
+		subagents,
+		models: [...models.entries()].map(([model, x]) => {
+			const name = displayNameOf(model, x.providers);
+			return {
+				model,
+				...name ? { name } : {},
+				providers: [...x.providers].map((provider) => providerNames[provider] || provider),
+				totals: x.totals,
+				requests: x.requests
+			};
+		}),
+		records,
+		routes: [...routeMap.values()]
+	};
+}
+//#endregion
 //#region src/wire.ts
 /** Default cap for a JSON request body. The panel posts tiny objects
 *  ({ range, from?, to? }); the cap only bounds a misbehaving trusted
@@ -1832,6 +2211,16 @@ function buildUsageRoute(ctx, deps) {
 				});
 				return;
 			}
+			if (method === "POST" && path === "/token-total/api/session-detail") {
+				const body = await readJsonBody(req);
+				const sessionId = typeof body.sessionId === "string" ? body.sessionId.trim() : "";
+				if (sessionId === "" || sessionId.length > 200) throw new UsageError(400, "token total: session needs a valid sessionId");
+				writeJson(res, {
+					ok: true,
+					value: await buildSessionUsageDetail(deps.persistence(), deps.sessions(), sessionId, ctx)
+				});
+				return;
+			}
 			if (method === "POST" && path === "/token-total/api/status") {
 				writeJson(res, {
 					ok: true,
@@ -2191,7 +2580,9 @@ function apply(ctx, config = {}) {
 			await rescan();
 			await ensureHourHistory();
 			await ensureFailureHistory();
-		})();
+		})().catch((err) => {
+			ctx.logger?.warn(`[dsh-token-total] boot scan failed: ${err instanceof Error ? err.message : String(err)}`);
+		});
 		return () => {
 			scanController?.abort();
 		};

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

@@ -0,0 +1,18 @@
+export interface ModelLogoProps {
+    /** Raw model id; may itself be a "provider/model" ref. */
+    model: string;
+    /** Resolved model display name (the by-model row's label) — matched with
+     *  the raw id, so an opaque route id beside a brandful name still brands. */
+    name?: string;
+    /** Provider route id — a secondary match signal for opaque model ids. */
+    provider?: string;
+    /** Resolved provider display names (the by-model row's split), matched last. */
+    providers?: ReadonlyArray<string>;
+    /** Rendered square size; the record rows read at 13px. */
+    size?: number;
+    className?: string;
+}
+/** One model's brand logo inline. The markup is a bundled constant (never
+ *  request data) rendered as-is so each brand keeps its own gradients,
+ *  circles and multi-path fills; ids inside stay unique across brands. */
+export declare function ModelLogo({ model, name, provider, providers, size, className }: ModelLogoProps): JSX.Element;

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

@@ -0,0 +1,14 @@
+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;
+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 }: {
+    detail: SessionUsageDetail;
+    t: T;
+}): JSX.Element;
+export declare function SessionUsageView({ sessionId, t }: SessionUsageViewProps): JSX.Element;
+export {};

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

@@ -11,7 +11,7 @@
  * prefix-stripping proxy; the host's own route key stays absolute
  * (`/token-total/api` in src/routes.ts), because only the browser half is relative.
  */
-import type { BackfillStatus, SessionUsageTree, TokenTotalRange, TokenTotalRequest } from '../wire.ts';
+import type { BackfillStatus, SessionUsageDetail, SessionUsageTree, TokenTotalRange, TokenTotalRequest } from '../wire.ts';
 /** One wire failure. */
 export declare class UsageApiError extends Error {
     readonly code: string;
@@ -29,3 +29,5 @@ export declare function rebuildStats(): Promise<BackfillStatus>;
  *  covers only the main agent, so this is what makes a delegating session's
  *  cost visible. */
 export declare function fetchSessionUsage(sessionId: string): Promise<SessionUsageTree>;
+/** Log-owned requests and live route states for the per-session Usage view. */
+export declare function fetchSessionDetail(sessionId: string, signal?: AbortSignal): Promise<SessionUsageDetail>;

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

@@ -7,7 +7,7 @@
  * from the shared zero-dependency module so the host and client halves share
  * one implementation.
  */
-export { providerOf, modelNameOf, daysInRange as daysBetween } from '../shared.ts';
+export { providerOf, modelNameOf, normalizeModelName, daysInRange as daysBetween } from '../shared.ts';
 /** Exact token counts with thousands separators — no 万/亿/k/M units, the
  *  user reads the precise number (long values shrink to fit via FitText).
  *  Compact units stay on the axis labels and card sub-values only. */

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

@@ -21,6 +21,7 @@
 import type { Context, UsagePluginConfigOwnerProps } from '../context-types.ts';
 import type { PropsLocale, PropsRuntime, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
 import { LOCALE_NS, type TokenTotalKey } from './locales.ts';
+import { type SessionUsageKey } from './session-usage-locales.ts';
 /** This bundle's npm package name — the key the Plugins page matches on. */
 export declare const BUNDLE_NAME = "dsh-token-total";
 /** The id shared by the sidebar row and the main panel it selects. */
@@ -36,6 +37,7 @@ export type TokenTotalPanelPageProps = PropsLocale<typeof LOCALE_NS> & {
 declare module '@deepseek-ai/dsh-client-ui-slots' {
     interface LocaleNamespaceMap {
         'tokenTotal': TokenTotalKey;
+        'sessionUsage': SessionUsageKey;
     }
 }
 export declare const inject: string[];

package/lib/types/client/model-logos-core.d.ts

@@ -0,0 +1,11 @@
+/** Brand ids in match order — every id here must ship markup. */
+export declare const MODEL_LOGO_BRANDS: ReadonlyArray<string>;
+/** Resolve the brand id for one usage record. The model's own naming (raw
+ *  model id plus its resolved display name) decides the brand when it can;
+ *  the provider fields (route id and provider display names) are the fallback
+ *  for opaque model ids, so a Llama served through a vertex/google route keeps
+ *  the Llama mark. Empty/undefined parts are ignored; null when no bundled
+ *  brand matches. */
+export declare function resolveModelLogo(provider: string | null | undefined, model: string | null | undefined, name?: string | null, providers?: ReadonlyArray<string>): string | null;
+/** Inner SVG markup of a brand's logo, or undefined for an unknown id. */
+export declare function modelLogoMarkup(id: string | null): string | undefined;

package/lib/types/client/model-logos-data.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Official per-brand logos for the usage panel: the inner markup of each
+ * brand's 24x24 SVG, extracted verbatim from @lobehub/icons-static-svg
+ * (MIT). Regenerate from .tmp/gen-logos.mjs after refreshing .tmp/logos/;
+ * brand colors are baked in, so no fill follows currentColor. Brand
+ * matching lives in model-logos-core.ts.
+ */
+export declare const MODEL_LOGOS: Readonly<Record<string, string>>;

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

@@ -0,0 +1,62 @@
+/** Session Usage view translations, independent of the global dashboard. */
+export declare const SESSION_USAGE_NS = "sessionUsage";
+export declare const usageZh: {
+    tab: string;
+    requests: string;
+    tokens: string;
+    hit: string;
+    first: string;
+    speed: string;
+    input: string;
+    output: string;
+    read: string;
+    write: string;
+    requestsCount: string;
+    inputFull: string;
+    outputFull: string;
+    readFull: string;
+    writeFull: string;
+    cacheHit: string;
+    compaction: string;
+    reqTimes: string;
+    children: string;
+    session: string;
+    models: string;
+    model: string;
+    records: string;
+    expand: string;
+    collapse: string;
+    loading: string;
+    empty: string;
+    noChildren: string;
+    noModels: string;
+    scope: string;
+    note: string;
+    failedLoad: string;
+    retry: string;
+    completed: string;
+    running: string;
+    failed: string;
+    interrupted: string;
+    main: string;
+    turn: string;
+    step: string;
+    started: string;
+    duration: string;
+    firstDetail: string;
+    provider: string;
+    status: string;
+    exact: string;
+    answering: string;
+    firstWait: string;
+    sec: string;
+    tokenWord: string;
+    perSec: string;
+    cacheShort: string;
+    avgCache: string;
+    avgRate: string;
+    inProgress: string;
+};
+export type SessionUsageKey = keyof typeof usageZh;
+export declare const usageEn: Record<SessionUsageKey, string>;
+export declare const usageZhTW: Record<SessionUsageKey, string>;

package/lib/types/client/use-session-detail.d.ts

@@ -0,0 +1,8 @@
+import type { SessionUsageDetail } from '../wire.ts';
+export declare const DETAIL_POLL_MS = 1500;
+export declare function useSessionDetail(sessionId: string): {
+    detail: SessionUsageDetail | null;
+    loading: boolean;
+    error: boolean;
+    retry: () => void;
+};

package/lib/types/routes.d.ts

@@ -15,7 +15,7 @@ import type { UsageWebRoute } from './context-types.ts';
 import type { UsageStore } from './store.ts';
 import type { UsageCollector } from './collector.ts';
 import type { Granularity } from './query.ts';
-import type { BackfillStatus, SessionUsageRequest, TokenTotalRange, TokenTotalRequest } from './wire.ts';
+import type { BackfillStatus, SessionUsageDetail, SessionUsageRequest, TokenTotalRange, TokenTotalRequest } from './wire.ts';
 import type { SessionUsageService } from './session-usage.ts';
 import { type TrustInputs } from './trust-fence.ts';
 export interface RoutesDeps {
@@ -55,4 +55,4 @@ export declare function aggregateRange(store: UsageStore, from: string, to: stri
  *  The host mounts it via `ctx.webServer.register` (which takes ONE WebRoute,
  *  not an array 鈥?matching the real dsh-host-webserver contract). */
 export declare function buildUsageRoute(ctx: Context, deps: RoutesDeps): UsageWebRoute;
-export type { BackfillStatus, TokenTotalRange, TokenTotalRequest, SessionUsageRequest };
+export type { BackfillStatus, TokenTotalRange, TokenTotalRequest, SessionUsageRequest, SessionUsageDetail };

package/lib/types/session-detail.d.ts

@@ -0,0 +1,3 @@
+import type { Context, UsageSessionPersistence, UsageSessionStore } from './context-types.ts';
+import type { SessionUsageDetail } from './wire.ts';
+export declare function buildSessionUsageDetail(persistence: UsageSessionPersistence, sessions: UsageSessionStore | undefined, rootId: string, ctx?: Context): Promise<SessionUsageDetail>;

package/lib/types/wire.d.ts

@@ -129,6 +129,61 @@ export interface SessionUsageTree {
 export interface SessionUsageRequest {
     sessionId: string;
 }
+/** Detailed per-session usage view used by the Usage tab. */
+export interface SessionUsageDetail {
+    sessionId: string;
+    totals: SessionUsageTotals;
+    requests: number;
+    averageFirstTokenMs: number | null;
+    tokensPerSecond: number | null;
+    subagents: Array<{
+        sessionId: string;
+        name: string;
+        totals: SessionUsageTotals;
+        requests: number;
+        averageFirstTokenMs: number | null;
+        tokensPerSecond: number | null;
+    }>;
+    models: Array<{
+        /** Raw model id from the historical route. Stays the row key and the
+         *  fallback label (also the tooltip) when no display name is resolved. */
+        model: string;
+        /** The model selector's display name for this model, resolved host-side
+         *  from the llm service metadata. Optional so an older host (or an
+         *  unresolvable route) still serves a valid payload. */
+        name?: string;
+        /** Display names (raw ids when unknown) of every provider that served this
+         *  model in the session, first-seen order. The by-model card shows these in
+         *  gray when two rows end up sharing one display name. */
+        providers?: string[];
+        totals: SessionUsageTotals;
+        requests: number;
+    }>;
+    records: Array<{
+        id: string;
+        sessionId: string;
+        sessionName: string;
+        turn: number;
+        step: number;
+        startedAt: number;
+        finishedAt: number | null;
+        provider: string;
+        model: string;
+        status: 'running' | 'completed' | 'failed' | 'interrupted';
+        totals: SessionUsageTotals;
+        firstTokenMs: number | null;
+        tokensPerSecond: number | null;
+        turnName: string;
+        effort: string;
+    }>;
+    routes: Array<{
+        id: string;
+        provider: string;
+        name: string;
+        model: string;
+        status: 'idle' | 'running' | 'completed' | 'failed';
+    }>;
+}
 /** The backfill (historical session scan) progress state. */
 export interface BackfillStatus {
     running: boolean;

package/package.json

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