feat: surface sidecar timing summaries

Author: linhay

.agents/skills/gettokens-domain-engineering/SKILL.md

@@ -169,6 +169,8 @@ This skill unifies the technical rules for building, styling, and debugging GetT
   - Trend chart data window is a fixed count cap, not a fixed time window. Keep only the latest capped request points for the chart model, so new requests push the sequence labels forward (`#50` -> `#51` -> `#52`) while the visible data volume remains bounded.
   - Trend chart viewport should be a fixed, non-scrollable audio waveform chart. The visible request count is width-driven: wider surfaces show more recent request bars, narrower surfaces show fewer, and the latest request stays anchored near the right edge. Do not reintroduce horizontal panning or auto-scroll follow logic.
   - The timing metric picker below the chart summarizes the same trend window. Show average values for `total / TTFT / first token / stream / queue / auth select / connect / gaps / rates` rather than echoing the latest single request; keep latest-request values in the timeline rows and chart footer.
+  - The timing metric picker should prefer the sidecar session-level `timingSummary` when present. Treat `timingSummary.window=retained_requests` as the authoritative average window, show `sampleCount` plus `sequenceFrom / sequenceTo`, and mark the UI as `Sidecar summary`. Only use frontend request-window averaging as a fallback for old sidecars or preview data without summary, and label that path as a local estimate.
+  - Sidecar `timingSummary` must not let stale historical streaming/reconnecting requests grow on every snapshot. Only the current active request may project `totalDurationMs` from the sidecar summary generation time; first-event and first-token fields must remain absent until observed.
   - Keep the live-session chart visually inside the page section, not as a nested card. Use the existing Swiss-industrial chart tokens, footer summaries below the graph, and live markers such as dashed strokes/rings for in-flight samples.
   - Request timing trend visuals should read like a forward-moving audio waveform, not a finance line, ECG trace, or candlestick chart. Render exactly one centered vertical amplitude bar per request for the selected timing metric; longer durations produce taller bars, and live rings distinguish in-flight samples.
   - Timing trend motion should not redraw the full waveform on every live refresh. Keep bars steady; use a short opacity settle only when switching metrics and a subtle breathing ring on the live sample to indicate activity.

app_codex_live_sessions.go

@@ -57,6 +57,7 @@ type CodexLiveSession struct {
 	FallbackInferred    bool                     `json:"fallbackInferred,omitempty"`
 	FallbackConfidence  string                   `json:"fallbackConfidence,omitempty"`
 	FallbackReason      string                   `json:"fallbackReason,omitempty"`
+	TimingSummary       *CodexLiveTimingSummary  `json:"timingSummary,omitempty"`
 	RecentEvents        []CodexLiveTimelineEvent `json:"recentEvents"`
 	Requests            []CodexLiveRequest       `json:"requests"`
 }
@@ -106,6 +107,31 @@ type CodexLiveTimingMetrics struct {
 	TotalTokensPerSecond  float64 `json:"totalTokensPerSecond,omitempty"`
 }
 
+type CodexLiveTimingSummary struct {
+	Window         string                         `json:"window"`
+	SampleCount    int                            `json:"sampleCount"`
+	SequenceFrom   int                            `json:"sequenceFrom,omitempty"`
+	SequenceTo     int                            `json:"sequenceTo,omitempty"`
+	ActiveIncluded bool                           `json:"activeIncluded,omitempty"`
+	GeneratedAt    string                         `json:"generatedAt"`
+	Averages       CodexLiveTimingSummaryAverages `json:"averages"`
+}
+
+type CodexLiveTimingSummaryAverages struct {
+	QueueWaitMs           *int64   `json:"queueWaitMs,omitempty"`
+	AuthSelectMs          *int64   `json:"authSelectMs,omitempty"`
+	UpstreamConnectMs     *int64   `json:"upstreamConnectMs,omitempty"`
+	FirstEventMs          *int64   `json:"firstEventMs,omitempty"`
+	FirstTokenMs          *int64   `json:"firstTokenMs,omitempty"`
+	AverageEventGapMs     *int64   `json:"averageEventGapMs,omitempty"`
+	LongestEventGapMs     *int64   `json:"longestEventGapMs,omitempty"`
+	StreamDurationMs      *int64   `json:"streamDurationMs,omitempty"`
+	TotalDurationMs       *int64   `json:"totalDurationMs,omitempty"`
+	ReconnectCount        *int     `json:"reconnectCount,omitempty"`
+	OutputTokensPerSecond *float64 `json:"outputTokensPerSecond,omitempty"`
+	TotalTokensPerSecond  *float64 `json:"totalTokensPerSecond,omitempty"`
+}
+
 type CodexLiveErrorSummary struct {
 	StatusCode int    `json:"statusCode,omitempty"`
 	Code       string `json:"code,omitempty"`
@@ -193,6 +219,7 @@ func mapCodexLiveSessions(items []wailsapp.CodexLiveSession) []CodexLiveSession
 			FallbackInferred:    item.FallbackInferred,
 			FallbackConfidence:  item.FallbackConfidence,
 			FallbackReason:      item.FallbackReason,
+			TimingSummary:       mapCodexLiveTimingSummary(item.TimingSummary),
 			RecentEvents:        mapCodexLiveTimelineEvents(item.RecentEvents),
 			Requests:            mapCodexLiveRequests(item.Requests),
 		})
@@ -274,6 +301,34 @@ func mapCodexLiveTiming(item wailsapp.CodexLiveTimingMetrics) CodexLiveTimingMet
 	}
 }
 
+func mapCodexLiveTimingSummary(item *wailsapp.CodexLiveTimingSummary) *CodexLiveTimingSummary {
+	if item == nil {
+		return nil
+	}
+	return &CodexLiveTimingSummary{
+		Window:         item.Window,
+		SampleCount:    item.SampleCount,
+		SequenceFrom:   item.SequenceFrom,
+		SequenceTo:     item.SequenceTo,
+		ActiveIncluded: item.ActiveIncluded,
+		GeneratedAt:    item.GeneratedAt,
+		Averages: CodexLiveTimingSummaryAverages{
+			QueueWaitMs:           item.Averages.QueueWaitMs,
+			AuthSelectMs:          item.Averages.AuthSelectMs,
+			UpstreamConnectMs:     item.Averages.UpstreamConnectMs,
+			FirstEventMs:          item.Averages.FirstEventMs,
+			FirstTokenMs:          item.Averages.FirstTokenMs,
+			AverageEventGapMs:     item.Averages.AverageEventGapMs,
+			LongestEventGapMs:     item.Averages.LongestEventGapMs,
+			StreamDurationMs:      item.Averages.StreamDurationMs,
+			TotalDurationMs:       item.Averages.TotalDurationMs,
+			ReconnectCount:        item.Averages.ReconnectCount,
+			OutputTokensPerSecond: item.Averages.OutputTokensPerSecond,
+			TotalTokensPerSecond:  item.Averages.TotalTokensPerSecond,
+		},
+	}
+}
+
 func mapCodexLiveError(item *wailsapp.CodexLiveErrorSummary) *CodexLiveErrorSummary {
 	if item == nil {
 		return nil

docs-linhay/dev/20260523-session-distillation-codex-live-sessions-ui.md

@@ -117,6 +117,21 @@ Live sessions 的 detail 面板和筛选区本质上是工作台容器，不是
 
 本轮 browser cache 验证中，最新请求时间线仍显示 `#50 总 8.0s / TTFT 562ms / 首 810ms`，而耗时指标块显示 `总耗时 7.1s / TTFT 740ms / 首 token 1.2s`，口径已区分。
 
+### 10.1 耗时均值摘要由 sidecar 声明
+
+趋势窗口平均值的权威口径应由 CLIProxyAPI live-session tracker 返回，而不是只在前端页面进入后临时解释。
+
+稳定边界：
+
+1. session 级 `timingSummary` 是耗时均值的优先数据源，窗口固定描述为 `retained_requests`。
+2. summary 必须包含 `sampleCount`、`sequenceFrom / sequenceTo`、`activeIncluded`、`generatedAt` 和 `averages`，让 UI 可以解释样本范围与 active request 投影。
+3. active request 只允许用 sidecar 的生成时刻投影 `totalDurationMs`；不要凭空生成 first event / first token 等未出现的字段。
+4. 历史 stale streaming / reconnecting request 只能使用已记录 timing 或 `completedAt - startedAt`，不能因为 snapshot 刷新继续增长。
+5. 前端 `resolveCodexLiveTimingMetricSummary` 优先使用 sidecar summary；缺失时才回退本地 retained request window 聚合，并在 UI 标记 `本地估算`。
+6. summary 只能包含计数、序号、时间与速率字段，不能包含 payload、headers、token、cookie 或未脱敏错误体。
+
+浏览器预览数据也应带 `timingSummary`，避免 preview 永远只覆盖 fallback 分支。结构差分合并时要把 `timingSummary.generatedAt` 和 active 投影导致的 summary 总耗时/流式耗时变化视为 clock-only refresh，避免高频轮询闪烁。
+
 ### 11. 右侧详情列要自包含滚动
 
 长运行会话的详情内容会明显高于视口。宽屏双栏布局下，右侧详情列不能只靠外层 workbench 滚动访问底部，否则用户在请求耗时趋势或请求时间线附近滚动时，会把页头、搜索栏和左侧列表一起卷走。

docs-linhay/memory/2026-05-27.md

@@ -307,3 +307,13 @@
 - 会话整理：本轮把状态页 Provider/Model 下拉的语义边界沉淀为项目级规则：显示和保存必须贴近 `config.toml` 的真实 key/value，UI 不再制造显示名/ID 双轨，也不再把历史 `GT` 兜底当作有效默认模型。
 - 写回：已更新 `.agents/skills/gettokens-domain-engineering/SKILL.md` 的 `Status Local CLI Config`，并补充 `docs-linhay/dev/20260426-relay-service-config-boundary.md` 第 8 节。
 - 不升级：该模式属于 Status 本地 CLI 配置域内规则，暂不升级 `AGENTS.md`。
+
+## Codex live-session sidecar timing summary implementation
+
+- 实施：CLIProxyAPI fork 的 live-session tracker 新增 session 级 `timingSummary`，基于 retained requests 返回样本数、sequence 范围、active 是否纳入、生成时间和 timing 均值；active request 只投影 `totalDurationMs`，历史 stale streaming/reconnecting request 不随刷新增长。
+- GetTokens 透传：`internal/wailsapp`、root `main.App`、`frontend/wailsjs/go/models.ts`、前端 adapter 和类型已端到端支持 `timingSummary`；前端 `resolveCodexLiveTimingMetricSummary` 优先用 sidecar summary，缺失时回退本地估算。
+- UI：live sessions 详情耗时区域改为 `耗时均值`，展示 `最近请求 <n> · #from-#to · Sidecar 汇总/本地估算`，timeline 和 chart footer 继续保留最新单请求值。
+- 验证：`go test ./internal/gettokenshooks -run 'LiveSessions.*TimingSummary|TimingSummary' -count=1`、`go test ./internal/gettokenshooks -run 'LiveSessions' -count=1`、`go test ./internal/wailsapp -run 'CodexLiveSessions' -count=1`、`node --test frontend/src/features/codex-live-sessions/model.test.mjs`、`npm --prefix frontend run typecheck`、`npm --prefix frontend run build` 均通过。
+- 浏览器验收：Playwright 打开 `http://localhost:5173/#frame=codex&workspace=live-sessions`，详情区显示 `耗时均值` 与 `最近请求 50 · #36-#85 · SIDECAR 汇总`；截图为 `docs-linhay/spaces/20260527-codex-live-session-timing-summary/screenshots/20260527/codex-live-sessions/20260527-codex-live-sessions-timing-summary-after-v01.png`。唯一 console error 是 favicon 404，与本功能无关。
+- 未覆盖：未重启真实桌面 app 并发起真实 Codex 请求做 runtime 验收；当前完成 sidecar fork、Wails DTO、前端模型/构建和浏览器预览验收。
+- 沉淀：已更新 `.agents/skills/gettokens-domain-engineering/SKILL.md` 和 `docs-linhay/dev/20260523-session-distillation-codex-live-sessions-ui.md`；不升级 `AGENTS.md`。

docs-linhay/references/CLIProxyAPI

@@ -1 +1 @@
-Subproject commit 952cf213eb49965f8e4c055affc71f932e897058
+Subproject commit b0cbe42cafa232b30cdedb1271b1bfe4ae6f14ad

docs-linhay/spaces/20260527-codex-live-session-timing-summary/README.md

@@ -128,5 +128,25 @@
 - 相关 workspace：`#frame=codex&workspace=live-sessions`
 
 ## 当前状态
-- 状态：requirements-ready
+- 状态：implemented-tested
 - 最近更新：2026-05-27
+
+## 实施记录
+
+- CLIProxyAPI fork 已在 session 级返回 `timingSummary`，窗口为 `retained_requests`，包含样本数、sequence 范围、active 是否纳入、生成时间和各 timing 字段均值。
+- active request 只投影 `totalDurationMs`；历史 stale streaming / reconnecting request 不随 snapshot 刷新继续增长。
+- GetTokens `internal/wailsapp`、root `main.App`、`frontend/wailsjs/go/models.ts` 和前端 adapter 已端到端透传 `timingSummary`。
+- 前端 `TimingMetrics` 优先使用 sidecar summary；缺失时回退本地 retained request window 聚合，并在 UI 标注 `Sidecar 汇总` 或 `本地估算`。
+- 浏览器验收截图：`screenshots/20260527/codex-live-sessions/20260527-codex-live-sessions-timing-summary-after-v01.png`。
+
+## 验证记录
+
+- `go test ./internal/gettokenshooks -run 'LiveSessions.*TimingSummary|TimingSummary' -count=1`
+- `go test ./internal/gettokenshooks -run 'LiveSessions' -count=1`
+- `go test ./internal/wailsapp -run 'CodexLiveSessions' -count=1`
+- `node --test frontend/src/features/codex-live-sessions/model.test.mjs`
+- `npm --prefix frontend run typecheck`
+- `npm --prefix frontend run build`
+- Playwright 验收 `http://localhost:5173/#frame=codex&workspace=live-sessions`：详情区显示 `耗时均值` 与 `最近请求 50 · #36-#85 · SIDECAR 汇总`，timeline 仍显示最新单请求耗时。
+
+未执行真实桌面 app 重启与真实 Codex 请求验收；当前完成的是 sidecar fork 单元测试、Wails DTO 测试、前端构建和浏览器预览验收。

docs-linhay/spaces/20260527-codex-live-session-timing-summary/plans/implementation-plan-v01.md

@@ -245,6 +245,36 @@ qmd update && qmd embed
 3. `M3 frontend display`：UI 优先 sidecar summary，fallback 兼容，前端测试通过。
 4. `M4 acceptance`：浏览器截图与真实 sidecar 验收完成，文档记忆同步。
 
+## 执行结果
+
+### 已完成
+
+- `M1 sidecar summary contract`：已在 CLIProxyAPI fork 增加 `LiveTimingSummary` 与 retained requests 聚合构建器，focused live-session 测试通过。
+- `M2 GetTokens DTO bridge`：已在 `internal/wailsapp`、root `main.App`、`frontend/wailsjs/go/models.ts` 增加 timing summary DTO 与 mapper，Wails focused 测试通过。
+- `M3 frontend display`：前端类型、adapter、preview mock、summary resolver 和详情 UI 已接入；`耗时均值` 优先展示 sidecar summary，缺失时 fallback 本地估算。
+- `M4 acceptance`：已完成浏览器预览验收与截图归档；文档、memory、领域 skill 已写回。
+
+### 最终验证
+
+```bash
+go test ./internal/gettokenshooks -run 'LiveSessions.*TimingSummary|TimingSummary' -count=1
+go test ./internal/gettokenshooks -run 'LiveSessions' -count=1
+go test ./internal/wailsapp -run 'CodexLiveSessions' -count=1
+node --test frontend/src/features/codex-live-sessions/model.test.mjs
+npm --prefix frontend run typecheck
+npm --prefix frontend run build
+```
+
+浏览器预览验收：
+
+- URL：`http://localhost:5173/#frame=codex&workspace=live-sessions`
+- 截图：`../screenshots/20260527/codex-live-sessions/20260527-codex-live-sessions-timing-summary-after-v01.png`
+- DOM 结果：详情区显示 `耗时均值` 与 `最近请求 50 · #36-#85 · SIDECAR 汇总`，timeline 仍显示最新单请求耗时。
+
+### 未覆盖项
+
+- 未重启真实桌面 app 并发起真实 Codex 请求做端到端 runtime 验收。本期验证覆盖 sidecar fork 单元测试、Wails DTO、前端模型/构建和浏览器预览。
+
 ## 开放问题
 
 1. `timingSummary` 放在 session 级即可，还是 request detail/history response 也要独立返回同一 summary？

frontend/src/features/codex-live-sessions/components/CodexLiveSessionDetail.tsx

@@ -30,8 +30,8 @@ import {
 } from './requestTimelineSummary';
 import type { Translate } from './types';
 import {
-  buildCodexLiveRequestTimingMetricAverages,
   buildCodexLiveRequestTimingTrend,
+  resolveCodexLiveTimingMetricSummary,
   type CodexLiveTimingMetricAverages,
   type CodexLiveRequestTimingTrendPoint,
   type CodexLiveTimingTrendMetric,
@@ -652,13 +652,21 @@ function TimingMetrics({
     return () => window.clearInterval(refreshID);
   }, []);
 
-  const averages = buildCodexLiveRequestTimingMetricAverages(session.requests, request, { nowMs });
+  const averages = resolveCodexLiveTimingMetricSummary(session, request, { nowMs });
   const metrics = buildTimingMetricRows(averages, t);
+  const summaryMeta = buildTimingSummaryMeta(averages, t);
 
   return (
     <div className="border-2 border-[var(--border-color)] bg-[var(--bg-surface)] p-3">
-      <div className="font-mono text-[length:var(--font-size-ui-sm)] font-black uppercase tracking-[0.16em] text-[var(--text-muted)]">
-        {t('codex_live_sessions.timing')}
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <div className="font-mono text-[length:var(--font-size-ui-sm)] font-black uppercase tracking-[0.16em] text-[var(--text-muted)]">
+          {t('codex_live_sessions.timing_average')}
+        </div>
+        {summaryMeta ? (
+          <div className="truncate font-mono text-[length:var(--font-size-ui-xs)] font-black uppercase text-[var(--text-muted)]">
+            {summaryMeta}
+          </div>
+        ) : null}
       </div>
       <div className="mt-3 grid gap-x-5 gap-y-2 md:grid-cols-3 xl:grid-cols-4">
         {metrics.map((metric) => {
@@ -697,6 +705,18 @@ function TimingMetrics({
   );
 }
 
+function buildTimingSummaryMeta(summary: CodexLiveTimingMetricAverages, t: Translate): string {
+  if (summary.sampleCount <= 0) {
+    return '';
+  }
+  const parts = [`${t('codex_live_sessions.timing_summary_recent')} ${summary.sampleCount}`];
+  if (typeof summary.sequenceFrom === 'number' && typeof summary.sequenceTo === 'number') {
+    parts.push(`#${summary.sequenceFrom}-#${summary.sequenceTo}`);
+  }
+  parts.push(t(summary.source === 'sidecar' ? 'codex_live_sessions.timing_summary_sidecar' : 'codex_live_sessions.timing_summary_fallback'));
+  return parts.join(' · ');
+}
+
 interface TimingMetricRow {
   key: string;
   label: string;