@brainpilot/web 0.0.5 → 0.0.7

package/src/contexts/messageGroups.ts

@@ -9,6 +9,60 @@ export type RenderItem =
   | { type: "single"; message: ChatMessage }
   | { type: "activity"; id: string; steps: ChatMessage[]; streaming: boolean };
 
+/**
+ * #134 — tool visibility model. Internal tools are part of the agent's plumbing
+ * (trace bookkeeping) rather than the user-facing conversation: the model still
+ * sees their calls and results, but the chat UI hides both so an implementation
+ * detail (`trace event dispatched`) never surfaces above the Principal's reply.
+ * Trace changes are surfaced quietly via the Trace tab badge instead.
+ *
+ * Hard-coded for the current internal toolset; promote to a richer
+ * `ToolVisibility = "user" | "debug" | "internal"` map if/when more land.
+ */
+const INTERNAL_TOOL_NAMES: ReadonlySet<string> = new Set([
+  "record_trace",
+  "create_trace_node",
+  "update_trace_node",
+  "add_trace_relation",
+  "get_trace_graph",
+]);
+
+/** A tool name is internal if it matches bare or mcp-namespaced (server__tool). */
+export function isInternalToolName(name: string | undefined): boolean {
+  if (!name) return false;
+  if (INTERNAL_TOOL_NAMES.has(name)) return true;
+  const bare = name.includes("__") ? name.slice(name.lastIndexOf("__") + 2) : name;
+  return INTERNAL_TOOL_NAMES.has(bare);
+}
+
+/**
+ * Drop internal-tool calls AND their matching results from the chat stream.
+ *
+ * A TOOL_CALL_START carries the tool name; the later TOOL_CALL_RESULT carries
+ * only a `toolCallId` linking back to it. So we first collect the call ids of
+ * every internal tool, then filter out both the call message and any tool
+ * message whose `toolCallId` (the result) points at one. Presentation-only:
+ * the underlying message list and the model's view are untouched.
+ */
+export function stripInternalToolMessages(messages: ChatMessage[]): ChatMessage[] {
+  const internalCallIds = new Set<string>();
+  for (const m of messages) {
+    if (m.kind === "tool" && isInternalToolName(m.toolName)) {
+      internalCallIds.add(m.id);
+      if (m.toolCallId) internalCallIds.add(m.toolCallId);
+    }
+  }
+  if (internalCallIds.size === 0) return messages;
+  return messages.filter((m) => {
+    if (m.kind !== "tool") return true;
+    // The call itself (internal tool name) → drop.
+    if (isInternalToolName(m.toolName)) return false;
+    // The result, linked by toolCallId to an internal call → drop.
+    if (m.toolCallId && internalCallIds.has(m.toolCallId)) return false;
+    return true;
+  });
+}
+
 /**
  * Standalone kinds render as their own visible card. All assistant text
  * messages — whether they come from the Principal or an Expert agent, and
@@ -49,6 +103,8 @@ export function buildRenderItems(
   runningAgents?: ReadonlySet<string>,
 ): RenderItem[] {
   const items: RenderItem[] = [];
+  // #134 — internal tools (trace bookkeeping) are hidden from the chat UI.
+  messages = stripInternalToolMessages(messages);
   let buffer: ChatMessage[] = [];
   // A step keeps its block "in progress" while its owning agent's run is active.
   // Steps default to the principal agent when unattributed, matching how the

package/src/contexts/messageReducer.ts

@@ -258,6 +258,10 @@ export function reduceMessagesForEvent(existing: ChatMessage[], event: WebSocket
           agent,
           kind: "tool",
           toolResult: content,
+          // #134 — keep the link back to the originating TOOL_CALL_START so the
+          // UI can suppress results of internal tools (record_trace) whose name
+          // only rode on the call event, not on this result.
+          toolCallId: event.toolCallId,
         },
       ];
     }

package/src/contexts/runningToast.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure helper for the "X 正在工作 / X is working" toast above the composer (#76).
+ *
+ * Selects which i18n key + vars the toast should render given the set of agents
+ * currently working. Kept pure (no React) so it's unit-testable without a DOM —
+ * the component just calls `t(key, vars)` with the result. The trace agent is
+ * excluded by the caller (it self-records continuously and isn't "the user's
+ * task"), matching the runtime's run-active aggregation.
+ */
+export interface ToastLabel {
+  key: "chat.agentWorking" | "chat.agentsWorking" | "chat.agentThinking";
+  /** Interpolation vars; shape matches i18n `TranslateVars` (string|number). */
+  vars?: Record<string, string>;
+}
+
+/**
+ * @param workingAgentNames names of non-trace agents with status "running"
+ * @param separator locale-appropriate join for multiple names (default "、")
+ */
+export function runningToastLabel(
+  workingAgentNames: readonly string[],
+  separator = "、",
+): ToastLabel {
+  if (workingAgentNames.length === 1) {
+    return { key: "chat.agentWorking", vars: { name: workingAgentNames[0]! } };
+  }
+  if (workingAgentNames.length > 1) {
+    return { key: "chat.agentsWorking", vars: { names: workingAgentNames.join(separator) } };
+  }
+  // Streaming but no named running agent yet (status not yet "running"): keep the
+  // generic label so the toast never renders blank.
+  return { key: "chat.agentThinking" };
+}

package/src/contexts/traceReducer.ts

@@ -0,0 +1,62 @@
+import { CUSTOM_EVENT } from "@brainpilot/protocol";
+import type { TraceGraph, TraceNode, WebSocketEvent } from "../contracts/backend";
+import { normalizeTraceNode } from "../contracts/backend";
+
+/**
+ * #79: merge a single `CUSTOM:trace_node` event into the live Graph of Trace.
+ *
+ * The runtime emits `CUSTOM { name:"trace_node", value:{ op, node } }` on every
+ * trace mutation (LLM `record_trace`/`create_trace_*` and the deterministic
+ * post-turn hook). This keeps the Trace panel live without polling the whole
+ * graph every few seconds.
+ *
+ * Merge rules:
+ *  - a non-`trace_node` event returns the same graph reference (no-op);
+ *  - an unparseable / id-less payload is ignored (same reference);
+ *  - a node id already present is replaced in place (status/summary updates);
+ *  - a new node id is appended;
+ *  - `childIds` are recomputed from every node's `parentIds` so edges stay
+ *    consistent regardless of arrival order (a child can arrive before its
+ *    parent's childIds is known).
+ */
+export function reduceTraceForEvent(
+  graph: TraceGraph | null,
+  event: WebSocketEvent,
+  sessionId: string,
+): TraceGraph | null {
+  const e = event as Record<string, unknown>;
+  if (e.type !== "CUSTOM" || e.name !== CUSTOM_EVENT.TRACE_NODE) return graph;
+  const value = (e.value ?? {}) as Record<string, unknown>;
+  const rawNode = value.node;
+  if (!rawNode || typeof rawNode !== "object") return graph;
+  const node = normalizeTraceNode(rawNode);
+  if (!node.id) return graph;
+
+  const base: TraceGraph = graph ?? {
+    meta: { sessionId },
+    nodes: [],
+  };
+  const idx = base.nodes.findIndex((n) => n.id === node.id);
+  const nextNodes =
+    idx >= 0
+      ? base.nodes.map((n, i) => (i === idx ? node : n))
+      : [...base.nodes, node];
+
+  return { meta: base.meta, nodes: withChildIds(nextNodes) };
+}
+
+/** Recompute every node's `childIds` from the parent links across the set. */
+function withChildIds(nodes: TraceNode[]): TraceNode[] {
+  const childrenByParent = new Map<string, Set<string>>();
+  for (const n of nodes) {
+    for (const pid of n.parentIds) {
+      const set = childrenByParent.get(pid) ?? new Set<string>();
+      set.add(n.id);
+      childrenByParent.set(pid, set);
+    }
+  }
+  return nodes.map((n) => ({
+    ...n,
+    childIds: Array.from(childrenByParent.get(n.id) ?? []),
+  }));
+}

package/src/contexts/turnTimer.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from "vitest";
+import {
+  turnTimerReducer,
+  initialTurnTimerState,
+  type TurnTimerState,
+} from "./turnTimer";
+
+/** Apply a sequence of events from the initial state. */
+function run(events: Parameters<typeof turnTimerReducer>[1][]): TurnTimerState {
+  return events.reduce(turnTimerReducer, initialTurnTimerState);
+}
+
+describe("turnTimerReducer (#99 whole-turn timing)", () => {
+  it("times a simple turn: user input → active true → active false → settle", () => {
+    const s = run([
+      { type: "userInput", atMs: 1000 },
+      { type: "active", value: true, atMs: 1010 },
+      { type: "active", value: false, atMs: 4200 },
+      { type: "settle" },
+    ]);
+    expect(s.running).toBe(false);
+    // Duration spans user input (1000) → terminal active=false (4200) = 3.2s.
+    expect(s.lastDurationMs).toBe(3200);
+    expect(s.startedAt).toBeNull();
+    expect(s.candidateEndAt).toBeNull();
+  });
+
+  it("does NOT end the turn on a mid-flap false that is re-woken before settle", () => {
+    let s = run([
+      { type: "userInput", atMs: 1000 },
+      { type: "active", value: true, atMs: 1010 },
+      // Principal turn ends momentarily...
+      { type: "active", value: false, atMs: 2000 },
+    ]);
+    expect(s.running).toBe(true); // still running (candidate pending, not settled)
+    expect(s.candidateEndAt).toBe(2000);
+
+    // ...but a hook / mailbox delivery re-wakes an agent before settle fires.
+    s = turnTimerReducer(s, { type: "active", value: true, atMs: 2050 });
+    expect(s.candidateEndAt).toBeNull(); // candidate discarded
+    expect(s.running).toBe(true);
+    expect(s.startedAt).toBe(1000); // original start preserved
+
+    // Real end later.
+    s = turnTimerReducer(s, { type: "active", value: false, atMs: 5000 });
+    s = turnTimerReducer(s, { type: "settle" });
+    expect(s.lastDurationMs).toBe(4000); // 1000 → 5000, the re-wake didn't reset it
+  });
+
+  it("uses the candidate-end timestamp, not the settle time, for the duration", () => {
+    // settle is dispatched 'later' but the committed duration must reflect the
+    // authoritative active=false timestamp (the settle window is not counted).
+    const s = run([
+      { type: "userInput", atMs: 0 },
+      { type: "active", value: true, atMs: 5 },
+      { type: "active", value: false, atMs: 1000 },
+      { type: "settle" }, // wall-clock-wise this happens ~800ms later, irrelevant
+    ]);
+    expect(s.lastDurationMs).toBe(1000);
+  });
+
+  it("seeds startedAt from active=true if the user-input open was missed (reconnect)", () => {
+    const s = run([
+      { type: "active", value: true, atMs: 3000 },
+      { type: "active", value: false, atMs: 3500 },
+      { type: "settle" },
+    ]);
+    expect(s.lastDurationMs).toBe(500);
+  });
+
+  it("ignores active=false when no turn is running", () => {
+    const s = run([{ type: "active", value: false, atMs: 100 }]);
+    expect(s).toEqual(initialTurnTimerState);
+  });
+
+  it("preserves the original start when a second userInput arrives mid-turn", () => {
+    const s = run([
+      { type: "userInput", atMs: 1000 },
+      { type: "active", value: true, atMs: 1010 },
+      { type: "userInput", atMs: 1500 }, // steering / follow-up during the run
+    ]);
+    expect(s.startedAt).toBe(1000);
+    expect(s.running).toBe(true);
+  });
+
+  it("keeps lastDurationMs across a reset of the active turn but reset() clears all", () => {
+    let s = run([
+      { type: "userInput", atMs: 0 },
+      { type: "active", value: true, atMs: 1 },
+      { type: "active", value: false, atMs: 2000 },
+      { type: "settle" },
+    ]);
+    expect(s.lastDurationMs).toBe(2000);
+    s = turnTimerReducer(s, { type: "reset" });
+    expect(s).toEqual(initialTurnTimerState);
+  });
+});

package/src/contexts/turnTimer.ts

@@ -0,0 +1,108 @@
+/**
+ * turnTimer — derive a "whole-turn" wall-clock duration for the Chat footer
+ * ("本轮对话用时"), issue #99.
+ *
+ * A turn is NOT a single assistant message. It spans from the user's input
+ * until every agent (principal + delegated experts + delivery loops) has
+ * finished — i.e. the authoritative `runState.active` flag (derived by the
+ * runtime, trace agent excluded) goes false and STAYS false.
+ *
+ * The subtlety (#99): `runState.active` can briefly flip true→false→true when a
+ * turn ends and a hook / system message / queued mailbox delivery immediately
+ * re-wakes an agent. That mid-flap `false` is NOT the end of the turn. So we
+ * debounce the terminal transition with a settle window: a false only counts as
+ * the turn's end once it has held for `settleMs`. If `active` goes true again
+ * inside the window, the candidate end is discarded and the same turn continues.
+ *
+ * This reducer is pure and driven entirely by authoritative backend signals
+ * (`runState.active` + the event's ISO timestamp). The host attaches the settle
+ * timer and a live "ticking" clock for the running display.
+ */
+
+export interface TurnTimerState {
+  /** ms epoch when the current turn started (user input / first active=true). */
+  startedAt: number | null;
+  /** Whether a turn is currently in progress (active, or within settle window). */
+  running: boolean;
+  /** Pending terminal end: active went false, awaiting settle confirmation. */
+  candidateEndAt: number | null;
+  /** The last settled whole-turn duration in ms, or null if none yet. */
+  lastDurationMs: number | null;
+}
+
+export const initialTurnTimerState: TurnTimerState = {
+  startedAt: null,
+  running: false,
+  candidateEndAt: null,
+  lastDurationMs: null,
+};
+
+export type TurnTimerEvent =
+  /** Authoritative runState.active snapshot at time `atMs` (from session_state). */
+  | { type: "active"; value: boolean; atMs: number }
+  /** The settle window elapsed with active still false → commit the turn end. */
+  | { type: "settle" }
+  /** A fresh user submission opens a new turn at `atMs` (optimistic start). */
+  | { type: "userInput"; atMs: number }
+  /** Session switch / reset — clear all timing. */
+  | { type: "reset" };
+
+/**
+ * Advance the turn-timer state machine. Pure: returns the next state. The host
+ * is responsible for (re)arming the settle timer whenever `candidateEndAt`
+ * becomes non-null, and dispatching `{type:"settle"}` after `settleMs`.
+ */
+export function turnTimerReducer(state: TurnTimerState, event: TurnTimerEvent): TurnTimerState {
+  switch (event.type) {
+    case "reset":
+      return initialTurnTimerState;
+
+    case "userInput": {
+      // Opening (or continuing) a turn from the user side. If a turn is already
+      // running, keep its original start; otherwise begin a new one. Clears any
+      // stale candidate end.
+      if (state.running && state.startedAt !== null) {
+        return { ...state, candidateEndAt: null };
+      }
+      return {
+        startedAt: event.atMs,
+        running: true,
+        candidateEndAt: null,
+        lastDurationMs: state.lastDurationMs,
+      };
+    }
+
+    case "active": {
+      if (event.value) {
+        // active=true: turn is (still) running. Cancel any pending end. Seed a
+        // start if the user-input optimistic open was missed (e.g. reconnect).
+        return {
+          startedAt: state.startedAt ?? event.atMs,
+          running: true,
+          candidateEndAt: null,
+          lastDurationMs: state.lastDurationMs,
+        };
+      }
+      // active=false: candidate terminal transition. Only meaningful if a turn
+      // is in progress. Record the candidate end; the host arms the settle
+      // timer. A re-wake (active=true) before settle discards this.
+      if (!state.running || state.startedAt === null) return state;
+      return { ...state, candidateEndAt: event.atMs };
+    }
+
+    case "settle": {
+      // Settle window held with active false → commit the whole-turn duration.
+      if (state.candidateEndAt === null || state.startedAt === null) return state;
+      const duration = Math.max(0, state.candidateEndAt - state.startedAt);
+      return {
+        startedAt: null,
+        running: false,
+        candidateEndAt: null,
+        lastDurationMs: duration,
+      };
+    }
+
+    default:
+      return state;
+  }
+}

package/src/contexts/useTurnTimer.ts

@@ -0,0 +1,104 @@
+/**
+ * useTurnTimer — React host for the whole-turn timer reducer (#99).
+ *
+ * Consumes the authoritative `runActive` signal from SessionContext
+ * (session_state.runState.active + backend timestamp) and produces:
+ *   - `running`: a turn is in progress (active, or within the settle window);
+ *   - `elapsedMs`: live elapsed while running (ticks ~every second), or the
+ *     last settled whole-turn duration once finished;
+ *   - `lastDurationMs`: the last settled whole-turn duration.
+ *
+ * The settle window debounces the true→false→true flap that happens when a hook
+ * / system message / queued mailbox delivery re-wakes an agent right after a
+ * turn momentarily ends — that mid-flap false must NOT end the turn.
+ */
+import { useEffect, useReducer, useRef, useState } from "react";
+import {
+  turnTimerReducer,
+  initialTurnTimerState,
+  type TurnTimerState,
+} from "./turnTimer";
+
+/** Default debounce for the terminal active=false transition. */
+export const DEFAULT_SETTLE_MS = 900;
+
+export interface TurnTiming {
+  running: boolean;
+  /** Live elapsed while running; the settled duration once finished; null if none. */
+  elapsedMs: number | null;
+  lastDurationMs: number | null;
+}
+
+interface UseTurnTimerOptions {
+  /** Backend run-active snapshot; null until the first session_state arrives. */
+  runActive: { active: boolean; atMs: number } | null;
+  /** Key that resets the timer when it changes (e.g. session id). */
+  resetKey?: string | null;
+  settleMs?: number;
+  /** Test seam: clock source (defaults to Date.now). */
+  now?: () => number;
+}
+
+export function useTurnTimer(options: UseTurnTimerOptions): TurnTiming {
+  const { runActive, resetKey, settleMs = DEFAULT_SETTLE_MS, now = Date.now } = options;
+  const [state, dispatch] = useReducer(turnTimerReducer, initialTurnTimerState);
+  const settleRef = useRef<number | undefined>(undefined);
+  const [, forceTick] = useState(0);
+
+  // Reset when the session changes.
+  useEffect(() => {
+    dispatch({ type: "reset" });
+  }, [resetKey]);
+
+  // Feed authoritative active transitions into the reducer.
+  useEffect(() => {
+    if (!runActive) return;
+    dispatch({ type: "active", value: runActive.active, atMs: runActive.atMs });
+  }, [runActive]);
+
+  // Arm/disarm the settle timer based on a pending candidate end.
+  const hasCandidate = state.candidateEndAt !== null;
+  useEffect(() => {
+    if (!hasCandidate) {
+      if (settleRef.current !== undefined) {
+        window.clearTimeout(settleRef.current);
+        settleRef.current = undefined;
+      }
+      return;
+    }
+    settleRef.current = window.setTimeout(() => {
+      settleRef.current = undefined;
+      dispatch({ type: "settle" });
+    }, settleMs);
+    return () => {
+      if (settleRef.current !== undefined) {
+        window.clearTimeout(settleRef.current);
+        settleRef.current = undefined;
+      }
+    };
+  }, [hasCandidate, settleMs]);
+
+  // Tick once per second while running so the live elapsed advances.
+  useEffect(() => {
+    if (!state.running) return;
+    const id = window.setInterval(() => forceTick((n) => n + 1), 1000);
+    return () => window.clearInterval(id);
+  }, [state.running]);
+
+  return deriveTiming(state, now);
+}
+
+function deriveTiming(state: TurnTimerState, now: () => number): TurnTiming {
+  if (state.running && state.startedAt !== null) {
+    return {
+      running: true,
+      elapsedMs: Math.max(0, now() - state.startedAt),
+      lastDurationMs: state.lastDurationMs,
+    };
+  }
+  return {
+    running: false,
+    elapsedMs: state.lastDurationMs,
+    lastDurationMs: state.lastDurationMs,
+  };
+}

package/src/contracts/backend.ts

@@ -14,10 +14,14 @@ import type {
   Session,
   AgentStatus,
   SessionStateSnapshot,
+  SessionTokenUsage,
+  TokenUsage,
   SettingsData,
   McpServerEntry,
   ModelHealth,
   ProviderProfile,
+  ProviderApi,
+  ProviderAdapter,
   FileEntry,
   FileContent,
   TraceNode,
@@ -34,10 +38,14 @@ export type {
   Session,
   AgentStatus,
   SessionStateSnapshot,
+  SessionTokenUsage,
+  TokenUsage,
   SettingsData,
   McpServerEntry,
   ModelHealth,
   ProviderProfile,
+  ProviderApi,
+  ProviderAdapter,
   FileEntry,
   FileContent,
   TraceNode,
@@ -195,6 +203,8 @@ export interface MessageFilterConfig {
 export interface ProviderCreate {
   name: string;
   baseUrl: string;
+  api?: ProviderApi;
+  adapter?: ProviderAdapter;
   apiKey: string;
   models?: string[];
   icon?: string;
@@ -205,6 +215,8 @@ export interface ProviderCreate {
 export interface ProviderUpdate {
   name?: string;
   baseUrl?: string;
+  api?: ProviderApi;
+  adapter?: ProviderAdapter;
   apiKey?: string;
   models?: string[];
   icon?: string;
@@ -400,6 +412,8 @@ interface RawProviderProfile {
   name?: string;
   base_url?: string;
   baseUrl?: string;
+  api?: string;
+  adapter?: string;
   models?: string[];
   icon?: string;
   icon_color?: string;
@@ -407,6 +421,8 @@ interface RawProviderProfile {
   notes?: string;
   is_active?: boolean;
   isActive?: boolean;
+  is_shared?: boolean;
+  isShared?: boolean;
   api_key_masked?: string;
   apiKeyMasked?: string;
   created_at?: number;
@@ -639,6 +655,9 @@ export function normalizeProviderProfile(raw: RawProviderProfile): ProviderProfi
     id: stringValue(raw.id),
     name: stringValue(raw.name),
     baseUrl: stringValue(raw.baseUrl ?? raw.base_url),
+    api: (raw.api ?? "anthropic-messages") as ProviderApi,
+    adapter: (raw.adapter ?? "auto") as ProviderAdapter,
+    isShared: Boolean(raw.isShared ?? raw.is_shared),
     models: Array.isArray(raw.models) ? raw.models : [],
     icon: stringValue(raw.icon, "circle"),
     iconColor: stringValue(raw.iconColor ?? raw.icon_color, "#111111"),
@@ -657,6 +676,8 @@ export function serializeProviderCreate(data: ProviderCreate): Record<string, un
   return {
     name: data.name,
     base_url: data.baseUrl,
+    api: data.api,
+    adapter: data.adapter,
     api_key: data.apiKey,
     models: data.models,
     icon: data.icon,
@@ -669,6 +690,8 @@ export function serializeProviderUpdate(data: ProviderUpdate): Record<string, un
   return {
     ...(data.name !== undefined ? { name: data.name } : {}),
     ...(data.baseUrl !== undefined ? { base_url: data.baseUrl } : {}),
+    ...(data.api !== undefined ? { api: data.api } : {}),
+    ...(data.adapter !== undefined ? { adapter: data.adapter } : {}),
     ...(data.apiKey !== undefined ? { api_key: data.apiKey } : {}),
     ...(data.models !== undefined ? { models: data.models } : {}),
     ...(data.icon !== undefined ? { icon: data.icon } : {}),
@@ -677,7 +700,7 @@ export function serializeProviderUpdate(data: ProviderUpdate): Record<string, un
   };
 }
 
-function normalizeTraceNode(rawValue: unknown): TraceNode {
+export function normalizeTraceNode(rawValue: unknown): TraceNode {
   const raw = asDict(rawValue);
   const parents = Array.isArray(raw.parents)
     ? raw.parents.map((parent) => {
@@ -752,7 +775,7 @@ export function normalizeSessionState(rawValue: unknown): SessionStateSnapshot {
       alive: typeof a.alive === "boolean" ? a.alive : undefined,
     };
   });
-  return {
+  const out: SessionStateSnapshot = {
     runState: {
       active: rs.active === true,
       runId: optionalString(rs.runId) ?? null,
@@ -760,6 +783,34 @@ export function normalizeSessionState(rawValue: unknown): SessionStateSnapshot {
     agents,
     lastActivityTs: stringValue(camelized.lastActivityTs, ""),
   };
+  const tokenUsage = normalizeSessionTokenUsage(camelized.tokenUsage);
+  if (tokenUsage) out.tokenUsage = tokenUsage;
+  return out;
+}
+
+/** Coerce one wire token-usage record into the numeric TokenUsage shape. */
+function normalizeTokenUsage(rawValue: unknown): TokenUsage {
+  const u = asDict(rawValue);
+  const num = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+  return {
+    input: num(u.input),
+    output: num(u.output),
+    cacheRead: num(u.cacheRead),
+    cacheWrite: num(u.cacheWrite),
+    total: num(u.total),
+  };
+}
+
+/** Parse the optional per-session token usage (total + per-agent breakdown). */
+function normalizeSessionTokenUsage(rawValue: unknown): SessionTokenUsage | undefined {
+  if (rawValue == null) return undefined;
+  const raw = asDict(rawValue);
+  const byAgentRaw = asDict(raw.byAgent);
+  const byAgent: Record<string, TokenUsage> = {};
+  for (const [name, value] of Object.entries(byAgentRaw)) {
+    byAgent[name] = normalizeTokenUsage(value);
+  }
+  return { total: normalizeTokenUsage(raw.total), byAgent };
 }
 
 

package/src/i18n/messages/analytics.ts

@@ -16,9 +16,14 @@ export default defineMessages(
     "analytics.chart.volume": "消息量（最近一小时）",
     "analytics.chart.load": "Agent 负载",
     "analytics.chart.types": "消息类型",
-    "analytics.chart.latency": "响应延迟",
-    "analytics.chart.tokens": "Token 估算（已发送）",
-    "analytics.chart.heatmap": "活动热力图",
+      "analytics.chart.latency": "响应延迟",
+      "analytics.chart.tokens": "Token 用量",
+      "analytics.chart.avgLength": "平均消息长度",
+      "analytics.chart.heatmap": "活动热力图",
+    "analytics.tokens.total": "总计",
+    "analytics.tokens.input": "输入",
+    "analytics.tokens.output": "输出",
+    "analytics.tokens.cache": "缓存",
     "analytics.table.agent": "Agent",
     "analytics.table.msgs": "消息数",
     "analytics.table.avgLen": "平均长度",
@@ -62,9 +67,14 @@ export default defineMessages(
     "analytics.chart.volume": "Message volume (last hour)",
     "analytics.chart.load": "Agent load",
     "analytics.chart.types": "Message types",
-    "analytics.chart.latency": "Response latency",
-    "analytics.chart.tokens": "Token estimate (sent)",
-    "analytics.chart.heatmap": "Activity heatmap",
+      "analytics.chart.latency": "Response latency",
+      "analytics.chart.tokens": "Token usage",
+      "analytics.chart.avgLength": "Average message length",
+      "analytics.chart.heatmap": "Activity heatmap",
+    "analytics.tokens.total": "Total",
+    "analytics.tokens.input": "Input",
+    "analytics.tokens.output": "Output",
+    "analytics.tokens.cache": "Cache",
     "analytics.table.agent": "Agent",
     "analytics.table.msgs": "Msgs",
     "analytics.table.avgLen": "Avg len",