fix(agentic): show runtime metadata in point details (#609)

Expose KV offload, transfer, and router metadata through the point-detail API; render it in English and Simplified Chinese; and version the composite cache response.

中文：在 Agentic 数据点详情 API 中补充 KV 卸载、传输引擎和路由器元数据，并在英文与简体中文界面中展示；同时为组合响应增加版本化缓存命名空间。

Author: cquil11

packages/app/cypress/e2e/agentic-point-time-series.cy.ts

@@ -215,15 +215,19 @@ const pointMeta = {
   spec_method: 'none',
   disagg: true,
   conc: 128,
-  offload_mode: 'off',
+  offload_mode: 'on',
+  kv_offloading: 'dram',
+  kv_offload_backend: 'lmcache',
+  kv_offload_backend_version: '0.5.1',
+  kv_p2p_transfer: 'mooncake',
+  router_name: 'vllm-router',
+  router_version: '0.1.14',
   isl: null,
   osl: null,
   benchmark_type: 'agentic_traces',
   date: '2026-06-23',
   run_url: null,
   server_gpu_cache_hit_rate: 0.5,
-  // Reproduces historical rows that retained a CPU hit metric after offload
-  // was disabled. The agentic point summary must suppress this stale value.
   server_cpu_cache_hit_rate: 0.42,
 };
 
@@ -299,8 +303,17 @@ describe('Agentic point orchestrator metric sources', () => {
   });
 
   it('switches every server chart to an orchestrator-normalized worker', () => {
-    cy.contains('GPU cache hit').should('be.visible');
-    cy.contains('CPU cache hit').should('not.exist');
+    cy.get('[data-testid="point-summary"]')
+      .should('contain.text', 'Offload Type')
+      .and('contain.text', 'DRAM')
+      .and('contain.text', 'KV Offload Engine')
+      .and('contain.text', 'LMCache 0.5.1')
+      .and('contain.text', 'KV Transfer Engine')
+      .and('contain.text', 'Mooncake')
+      .and('contain.text', 'Router')
+      .and('contain.text', 'vLLM Router 0.1.14')
+      .and('contain.text', 'GPU cache hit')
+      .and('contain.text', 'CPU cache hit');
 
     cy.get('[data-testid="metric-source-toolbar"]')
       .should('have.css', 'position', 'sticky')

packages/app/src/app/api/v1/agentic-cache-keys.test.ts

@@ -25,8 +25,8 @@ vi.mock('@/lib/api-cache', () => ({
 }));
 
 import { STATS_VERSION } from '@semianalysisai/inferencex-db/queries/agentic-aggregates';
-import { CHART_SERIES_VERSION } from '@semianalysisai/inferencex-db/etl/compute-chart-series';
 import { REQUEST_TIMELINE_VERSION } from '@semianalysisai/inferencex-db/etl/compute-request-timeline';
+import { TRACE_SERVER_METRICS_VERSION } from '@semianalysisai/inferencex-db/queries/trace-server-metrics';
 
 import { CACHE_KEY_PREFIX as derivedAgenticMetricsKey } from './derived-agentic-metrics/route';
 import { CACHE_KEY_PREFIX as agenticAggregatesKey } from './agentic-aggregates/route';
@@ -47,8 +47,8 @@ describe('agentic blob-cache keys are version-derived', () => {
     expect(requestTimelineKey).toBe(`request-timeline-v${REQUEST_TIMELINE_VERSION}`);
   });
 
-  it('trace-server-metrics key embeds CHART_SERIES_VERSION', () => {
-    expect(traceServerMetricsKey).toBe(`trace-server-metrics-v${CHART_SERIES_VERSION}`);
+  it('trace-server-metrics key embeds its composite response version', () => {
+    expect(traceServerMetricsKey).toBe(`trace-server-metrics-v${TRACE_SERVER_METRICS_VERSION}`);
   });
 
   it('trace-histograms key embeds REQUEST_TIMELINE_VERSION (its payload is read from request_timeline)', () => {

packages/app/src/app/api/v1/trace-server-metrics/route.ts

@@ -1,8 +1,8 @@
-import { CHART_SERIES_VERSION } from '@semianalysisai/inferencex-db/etl/compute-chart-series';
 import { getDb } from '@semianalysisai/inferencex-db/connection';
 
 import {
   getTraceServerMetrics,
+  TRACE_SERVER_METRICS_VERSION,
   type TraceServerMetrics,
 } from '@semianalysisai/inferencex-db/queries/trace-server-metrics';
 
@@ -12,12 +12,13 @@ import { idQueryRoute } from '../id-routes';
 
 export const dynamic = 'force-dynamic';
 
-// Key derived from CHART_SERIES_VERSION (governs the `chart_series` payload).
+// Key derived from TRACE_SERVER_METRICS_VERSION (governs chart_series plus
+// the separately queried point-metadata payload).
 // The blob cache is write-once with no post-backfill purge, so the
 // version-derived key is what rolls the namespace on a bump — a hand-written
 // string would serve stale blob-cached series forever.
 /** Version-derived blob-cache key namespace (exported for the key-derivation test). */
-export const CACHE_KEY_PREFIX = `trace-server-metrics-v${CHART_SERIES_VERSION}`;
+export const CACHE_KEY_PREFIX = `trace-server-metrics-v${TRACE_SERVER_METRICS_VERSION}`;
 
 const getCachedTraceServerMetrics = cachedQuery(
   (id: number): Promise<TraceServerMetrics | null> => getTraceServerMetrics(getDb(), id),

packages/app/src/components/inference/agentic-point/point-summary.test.ts

@@ -1,6 +1,11 @@
 import { createElement } from 'react';
 import { renderToStaticMarkup } from 'react-dom/server';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
+
+const localeState = vi.hoisted(() => ({ pathname: '/inference/agentic/206885' }));
+vi.mock('next/navigation', () => ({
+  usePathname: () => localeState.pathname,
+}));
 
 import type { PointMeta } from '@/hooks/api/use-trace-server-metrics';
 
@@ -17,6 +22,12 @@ function meta(overrides: Partial<PointMeta> = {}): PointMeta {
     disagg: true,
     conc: 128,
     offload_mode: 'off',
+    kv_offloading: null,
+    kv_offload_backend: null,
+    kv_offload_backend_version: null,
+    kv_p2p_transfer: null,
+    router_name: null,
+    router_version: null,
     isl: null,
     osl: null,
     benchmark_type: 'agentic_traces',
@@ -44,4 +55,50 @@ describe('PointSummary', () => {
     expect(html).toContain('CPU cache hit');
     expect(html).toContain('42.00%');
   });
+
+  it('shows runtime component names and independently reported versions', () => {
+    const html = renderToStaticMarkup(
+      createElement(PointSummary, {
+        meta: meta({
+          offload_mode: 'on',
+          kv_offloading: 'dram',
+          kv_offload_backend: 'lmcache',
+          kv_offload_backend_version: '0.5.1',
+          kv_p2p_transfer: 'mooncake',
+          router_name: 'vllm-router',
+          router_version: '0.1.14',
+        }),
+      }),
+    );
+
+    expect(html).toContain('Offload Type');
+    expect(html).toContain('DRAM');
+    expect(html).toContain('KV Offload Engine');
+    expect(html).toContain('LMCache 0.5.1');
+    expect(html).toContain('KV Transfer Engine');
+    expect(html).toContain('Mooncake');
+    expect(html).toContain('Router');
+    expect(html).toContain('vLLM Router 0.1.14');
+  });
+
+  it('renders runtime metadata labels in Simplified Chinese on /zh', () => {
+    localeState.pathname = '/zh/inference/agentic/206885';
+    const html = renderToStaticMarkup(
+      createElement(PointSummary, {
+        meta: meta({
+          kv_offloading: 'dram',
+          kv_offload_backend: 'hicache',
+          router_name: 'sglang-router',
+          router_version: '0.3.2',
+        }),
+      }),
+    );
+    localeState.pathname = '/inference/agentic/206885';
+
+    expect(html).toContain('卸载类型');
+    expect(html).toContain('KV 卸载引擎');
+    expect(html).toContain('HiCache');
+    expect(html).toContain('路由器');
+    expect(html).toContain('SGLang Router 0.3.2');
+  });
 });

packages/app/src/components/inference/agentic-point/point-summary.tsx

@@ -3,7 +3,46 @@
 import type { ReactNode } from 'react';
 
 import type { PointMeta } from '@/hooks/api/use-trace-server-metrics';
+import type { Locale } from '@/lib/i18n';
 import { isKvOffloadEnabled } from '@/lib/kv-offload';
+import { useLocale } from '@/lib/use-locale';
+import {
+  offloadTypeLabel,
+  versionedComponentLabel,
+} from '@/components/inference/utils/runtime-metadata-labels';
+
+const STRINGS = {
+  en: {
+    selectedPoint: 'Selected point',
+    disagg: 'disagg',
+    githubRun: 'GitHub Actions run →',
+    offloadType: 'Offload Type',
+    offloadBackend: 'KV Offload Engine',
+    transferEngine: 'KV Transfer Engine',
+    router: 'Router',
+    concurrency: 'Concurrency',
+    gpuCacheHit: 'GPU cache hit',
+    cpuCacheHit: 'CPU cache hit',
+    enabledLegacy: 'Enabled (legacy data)',
+    disabledLegacy: 'Disabled (legacy data)',
+    none: 'None',
+  },
+  zh: {
+    selectedPoint: '已选数据点',
+    disagg: '解耦',
+    githubRun: 'GitHub Actions 运行 →',
+    offloadType: '卸载类型',
+    offloadBackend: 'KV 卸载引擎',
+    transferEngine: 'KV 传输引擎',
+    router: '路由器',
+    concurrency: '并发数',
+    gpuCacheHit: 'GPU Cache 命中率',
+    cpuCacheHit: 'CPU Cache 命中率',
+    enabledLegacy: '已启用（旧版数据）',
+    disabledLegacy: '已禁用（旧版数据）',
+    none: '无',
+  },
+} as const;
 
 const fmtPct = (v: number | null | undefined): string =>
   v === null || v === undefined || Number.isNaN(v) ? '—' : `${(v * 100).toFixed(2)}%`;
@@ -17,16 +56,32 @@ function MetaLine({ label, value }: { label: string; value: ReactNode }) {
   );
 }
 
-/** Selected-point header: config facts (offload, concurrency, cache hit rates, ISL/OSL). */
+function offloadDisplay(meta: PointMeta, locale: Locale): string {
+  const t = STRINGS[locale];
+  const type = meta.kv_offloading?.trim();
+  if (type) return type.toLowerCase() === 'none' ? t.none : offloadTypeLabel(type);
+  if (!meta.offload_mode) return t.none;
+  return meta.offload_mode.toLowerCase() === 'on' ? t.enabledLegacy : t.disabledLegacy;
+}
+
+/** Selected-point header: runtime components, concurrency, cache hit rates, and ISL/OSL. */
 export function PointSummary({ meta }: { meta: PointMeta }) {
+  const locale = useLocale();
+  const t = STRINGS[locale];
   const showCpuCacheHit = isKvOffloadEnabled(meta);
+  const offloadBackend = versionedComponentLabel(
+    meta.kv_offload_backend,
+    meta.kv_offload_backend_version,
+  );
+  const transferEngine = versionedComponentLabel(meta.kv_p2p_transfer, null);
+  const router = versionedComponentLabel(meta.router_name, meta.router_version);
 
   return (
-    <div className="mb-4">
+    <div className="mb-4" data-testid="point-summary">
       <div className="flex items-baseline justify-between gap-3 mb-2">
         <p className="text-sm text-muted-foreground">
-          Selected point
-          {meta.disagg ? ' · disagg' : ''}
+          {t.selectedPoint}
+          {meta.disagg ? ` · ${t.disagg}` : ''}
           {meta.spec_method && meta.spec_method !== 'none' ? ` · spec=${meta.spec_method}` : ''}
         </p>
         {meta.run_url && (
@@ -36,16 +91,19 @@ export function PointSummary({ meta }: { meta: PointMeta }) {
             rel="noopener noreferrer"
             className="text-xs text-muted-foreground hover:text-foreground underline"
           >
-            GitHub Actions run →
+            {t.githubRun}
           </a>
         )}
       </div>
       <div className="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-6 gap-3">
-        <MetaLine label="Offload" value={(meta.offload_mode ?? 'off').toUpperCase()} />
-        <MetaLine label="Concurrency" value={meta.conc} />
-        <MetaLine label="GPU cache hit" value={fmtPct(meta.server_gpu_cache_hit_rate)} />
+        <MetaLine label={t.offloadType} value={offloadDisplay(meta, locale)} />
+        {offloadBackend && <MetaLine label={t.offloadBackend} value={offloadBackend} />}
+        {transferEngine && <MetaLine label={t.transferEngine} value={transferEngine} />}
+        {router && <MetaLine label={t.router} value={router} />}
+        <MetaLine label={t.concurrency} value={meta.conc} />
+        <MetaLine label={t.gpuCacheHit} value={fmtPct(meta.server_gpu_cache_hit_rate)} />
         {showCpuCacheHit && (
-          <MetaLine label="CPU cache hit" value={fmtPct(meta.server_cpu_cache_hit_rate)} />
+          <MetaLine label={t.cpuCacheHit} value={fmtPct(meta.server_cpu_cache_hit_rate)} />
         )}
         {meta.isl !== null && <MetaLine label="ISL" value={meta.isl} />}
         {meta.osl !== null && <MetaLine label="OSL" value={meta.osl} />}

packages/app/src/components/inference/utils/runtime-metadata-labels.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  cacheImplementationLabel,
+  offloadTypeLabel,
+  versionedComponentLabel,
+} from './runtime-metadata-labels';
+
+describe('runtime metadata labels', () => {
+  it('normalizes known component names and preserves unknown names', () => {
+    expect(cacheImplementationLabel('vllm-simple')).toBe('vLLM Simple');
+    expect(cacheImplementationLabel('MOONCAKE')).toBe('Mooncake');
+    expect(cacheImplementationLabel('custom-engine')).toBe('custom-engine');
+  });
+
+  it('combines independently reported component versions', () => {
+    expect(versionedComponentLabel('lmcache', '0.5.1')).toBe('LMCache 0.5.1');
+    expect(versionedComponentLabel('hicache', null)).toBe('HiCache');
+    expect(versionedComponentLabel(null, 'ignored')).toBeNull();
+  });
+
+  it('formats DRAM and other offload types consistently', () => {
+    expect(offloadTypeLabel('dram')).toBe('DRAM');
+    expect(offloadTypeLabel('cpu')).toBe('CPU');
+  });
+});

packages/app/src/components/inference/utils/runtime-metadata-labels.ts

@@ -0,0 +1,31 @@
+const CACHE_IMPLEMENTATION_LABELS: Record<string, string> = {
+  hicache: 'HiCache',
+  lmcache: 'LMCache',
+  mooncake: 'Mooncake',
+  mori: 'MoRI',
+  moriio: 'MoRI-IO',
+  'mori-io': 'MoRI-IO',
+  nixl: 'NIXL',
+  atomesh: 'AtoMesh',
+  'vllm-native': 'vLLM Native',
+  'vllm-router': 'vLLM Router',
+  'vllm-simple': 'vLLM Simple',
+  'sglang-router': 'SGLang Router',
+};
+
+export const cacheImplementationLabel = (value: string): string =>
+  CACHE_IMPLEMENTATION_LABELS[value.toLowerCase()] ?? value;
+
+export const offloadTypeLabel = (value: string): string => {
+  if (value.toLowerCase() === 'dram') return 'DRAM';
+  return value.toUpperCase();
+};
+
+export const versionedComponentLabel = (
+  name: string | null | undefined,
+  version: string | null | undefined,
+): string | null => {
+  if (!name) return null;
+  const label = cacheImplementationLabel(name);
+  return version ? `${label} ${version}` : label;
+};