opencode-tui-stats 0.4.0 → 0.4.2

package/README.en.md

@@ -1,6 +1,6 @@
 # opencode-tui-stats
 
-A TUI plugin for OpenCode 1.x (v1) that shows a single line — `TPS | AVG | TTFT` — on the right side of the session prompt.
+A TUI plugin for OpenCode 1.x (v1), mounted at the bottom of the right sidebar (slot `sidebar_footer`), with the panel title `Model-Performance · observed`. Each model occupies one row that can be collapsed/expanded by mouse click.
 
 ## Demo
 
@@ -18,11 +18,25 @@ This command writes the plugin into opencode's TUI config. You can also install
 
 - opencode ≥ 1.3.14
 
+## Collapsing & subagents
+
+- Each model occupies one row that can be collapsed/expanded by mouse click (`▼`/`▶`); rows are collapsed by default, and the most recently used model starts expanded.
+- Collapsed: `▶ [↳ ]provider/model` (redundant same-provider prefix omitted; provider dimmed, model name bright).
+- Expanded:
+  - `AVG …t/s · TPS …t/s` (TPS shown only when a value exists; the final value is kept and dimmed after generation ends)
+  - `TTFT …s · CACHE …%`
+  - `$…` (cost on its own line)
+- Models from subagents (sub-sessions) are merged into the same panel; rows originating from a subagent are prefixed with `↳`, and the same model (parent/child) is merged and summed.
+- Panel footer: `Session CACHE …%` (aggregated across the whole session + subagent tree, 1 decimal place); `retries` is shown only when >0.
+
 ## Metrics
 
-- `TPS`: live generation rate within the most recent ~5-second streaming window (tokens/sec); shows `-` when the session is idle or data is stale.
+- `TPS`: generation rate within the most recent ~5-second streaming window (tokens/sec); the final value is frozen and dimmed after the stream stops.
 - `AVG`: average generation rate of completed messages in this session (tokens/sec).
-- `TTFT`: average time to first token of completed messages in this session (seconds).
+- `TTFT`: average time to first token (seconds, approximate, includes queue/retry wait).
+- `CACHE`: prompt cache hit rate = `cache.read / (input + cache.read + cache.write)`, 1 decimal place.
+- `COST`: cumulative session cost (aggregated per model/session).
+- `RETRY`: retry count, derived from the attempt reported by the provider.
 
 ## License
 

package/README.md

@@ -1,6 +1,6 @@
 # opencode-tui-stats
 
-OpenCode 1.x（v1）的 TUI 插件，在会话提示区右侧显示一行 `TPS | AVG | TTFT`。
+OpenCode 1.x（v1）的 TUI 插件，安装在右侧栏底部（slot `sidebar_footer`），面板标题为 `Model-Performance · observed`。每个模型占一行，鼠标点击可折叠/展开。
 
 ## 演示
 
@@ -18,11 +18,25 @@ opencode plugin opencode-tui-stats --global
 
 - opencode ≥ 1.3.14
 
+## 折叠与子会话
+
+- 每个模型占一行，鼠标点击可折叠/展开（`▼`/`▶`）；默认折叠，最近使用的模型默认展开。
+- 折叠态：`▶ [↳ ]provider/model`（同 provider 前缀省略；provider 暗色、模型名亮色）。
+- 展开态：
+  - `AVG …t/s · TPS …t/s`（TPS 仅在有值时显示；生成结束后保留最后值并变暗）
+  - `TTFT …s · CACHE …%`
+  - `$…`（成本单独一行）
+- 子会话（子 agent）的模型会并入同一面板，来自子会话的行前缀 `↳`；同一模型（父/子）合并求和。
+- 面板底部：`Session CACHE …%`（整个会话 + 子会话树聚合，1 位小数）；`retries` 仅在 >0 时显示。
+
 ## 指标说明
 
-- `TPS`：最近约 5 秒流式窗口内的实时生成速度（token/秒）；会话空闲或数据过期时显示 `-`。
+- `TPS`：最近约 5 秒流式窗口内的生成速度（token/秒）；停止后冻结最后值并变暗。
 - `AVG`：本会话已完成消息的平均生成速度（token/秒）。
-- `TTFT`：本会话已完成消息的平均首字延迟（秒）。
+- `TTFT`：平均首字延迟（秒，近似值，包含排队/重试等待）。
+- `CACHE`：提示词缓存命中率 = `cache.read / (input + cache.read + cache.write)`，1 位小数。
+- `COST`：会话累计成本（按模型/会话聚合）。
+- `RETRY`：按 provider 上报的 attempt 统计的重试次数。
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-tui-stats",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "OpenCode 1 TUI plugin that shows live TPS, average TPS, and average time to first token in the session prompt.",
   "type": "module",
   "exports": {

package/tracker.ts

@@ -53,6 +53,9 @@ export type SessionModels = {
   aggregates: Record<string, ModelAggregate>
   /** `messageID -> providerID/modelID`, used to attribute live samples to a model. */
   messageModels: Map<string, string>
+  /** Last measured live rate per model key, kept after the stream goes idle/stale so the
+   * final reading stays visible instead of disappearing. */
+  lastRate: Record<string, string>
 }
 
 export type Tracker = {
@@ -147,7 +150,7 @@ export function averageTtft(average: SessionAverage | undefined) {
 /** Cache hit percentage (e.g. `31%`) or `undefined` when nothing promptable has been seen. */
 export function cacheText(stats: { cacheRead: number; cachePrompt: number } | undefined) {
   if (!stats || stats.cachePrompt <= 0) return undefined
-  return `${Math.round((stats.cacheRead / stats.cachePrompt) * 100)}%`
+  return `${((stats.cacheRead / stats.cachePrompt) * 100).toFixed(1)}%`
 }
 
 export function costText(stats: { cost: number; steps: number } | undefined) {
@@ -182,7 +185,10 @@ export type ModelRow = {
   active: boolean
   /** True when any descendant (subagent) session contributed data to this row. */
   subagent?: boolean
+  /** Last measured live rate, or `undefined` when this model has never streamed. */
   tps?: string
+  /** True while `tps` is backed by an active stream; false for a frozen final value. */
+  tpsLive: boolean
   avg?: string
   ttft?: string
   cache?: string
@@ -323,10 +329,13 @@ export function createTracker(api: TuiPluginApi, onChange: () => void): TrackerH
     bump()
   }
 
-  /** Live rate restricted to samples attributed to `key` via the `messageID -> model` mapping. */
-  const sessionLiveRate = (sessionID: string, key: string) => {
+  /** Live rate restricted to samples attributed to `key` via the `messageID -> model` mapping.
+   * When the session is idle or the samples are stale, the last measured value is frozen and
+   * returned with `live: false` instead of disappearing. */
+  const sessionLiveRate = (sessionID: string, key: string): { value?: string; live: boolean } => {
+    const frozen = { value: tracker.models[sessionID]?.lastRate[key], live: false }
     const status = api.state.session.status(sessionID)
-    if (!status || status.type === "idle") return undefined
+    if (!status || status.type === "idle") return frozen
 
     const now = Date.now()
     const mapping = tracker.models[sessionID]?.messageModels
@@ -334,10 +343,14 @@ export function createTracker(api: TuiPluginApi, onChange: () => void): TrackerH
       (sample) => now - sample.at <= STREAM_WINDOW_MS && mapping?.get(sample.messageID) === key,
     )
     const last = samples[samples.length - 1]
-    if (!last || now - last.at > LIVE_STALE_MS) return undefined
+    if (!last || now - last.at > LIVE_STALE_MS) return frozen
 
     const tokens = samples.reduce((sum, sample) => sum + sample.tokens, 0)
-    return formatRate(tokens / (activeDuration(samples, now) / 1_000))
+    const value = formatRate(tokens / (activeDuration(samples, now) / 1_000))
+    if (value === undefined) return frozen
+    const models = tracker.models[sessionID]
+    if (models) models.lastRate[key] = value
+    return { value, live: true }
   }
 
   /** Fold a session's parent from `session.created`/`session.updated`, or lazily from state.
@@ -414,14 +427,14 @@ export function createTracker(api: TuiPluginApi, onChange: () => void): TrackerH
   /** Live rate for a merged row: the parent and its subagents share one row, so only the
    * session/model pair that most recently saw activity contributes. Concurrent streams in a
    * parent and a child are therefore approximated by the newer one instead of being summed. */
-  const liveRateFor = (sessions: string[], key: string) => {
+  const liveRateFor = (sessions: string[], key: string): { value?: string; live: boolean } => {
     let latest: { sessionID: string; at: number } | undefined
     for (const sessionID of sessions) {
       const aggregate = tracker.models[sessionID]?.aggregates[key]
       if (!aggregate) continue
       if (!latest || aggregate.lastAt >= latest.at) latest = { sessionID, at: aggregate.lastAt }
     }
-    if (!latest) return undefined
+    if (!latest) return { live: false }
     return sessionLiveRate(latest.sessionID, key)
   }
 
@@ -482,12 +495,14 @@ export function createTracker(api: TuiPluginApi, onChange: () => void): TrackerH
     const rows = visible.map<ModelRow>((key) => {
       const aggregate = aggregates[key]
       const isActive = key === active
+      const tps = isActive ? liveRateFor(subtree, key) : { value: undefined, live: false }
       return {
         key,
         label: key,
         active: isActive,
         subagent: subagentModels.has(key),
-        tps: isActive ? liveRateFor(subtree, key) : undefined,
+        tps: tps.value,
+        tpsLive: tps.live,
         avg: averageRate(aggregate),
         ttft: averageTtft(aggregate),
         cache: cacheText(aggregate),
@@ -533,7 +548,8 @@ export function createTracker(api: TuiPluginApi, onChange: () => void): TrackerH
       // Observe the model as soon as a message appears so the sidebar can attribute live samples
       // and mark the most recently used model as active.
       const models =
-        tracker.models[sessionID] ?? (tracker.models[sessionID] = { order: [], aggregates: {}, messageModels: new Map() })
+        tracker.models[sessionID] ??
+        (tracker.models[sessionID] = { order: [], aggregates: {}, messageModels: new Map(), lastRate: {} })
       touchModel(models, key)
       models.active = key
       models.aggregates[key] = { ...models.aggregates[key], lastAt: Date.now() }

package/tui.tsx

@@ -14,10 +14,10 @@ const DETAIL_INDENT = "   "
 /** Fixed cells keep every label on the same column across rows without measuring the panel. */
 const RATE_CELL = 4
 const TTFT_CELL = 6
-const CACHE_CELL = 4
+const CACHE_CELL = 6
 
-/** Split `provider/model` so the provider can be muted. Model ids may contain slashes, so only the
- * first slash separates the provider. When the model already starts with the provider name
+/** Split `provider/model` so the provider can be de-emphasised. Model ids may contain slashes, so
+ * only the first slash separates the provider. When the model already starts with the provider name
  * (`deepseek/deepseek-flash`) the redundant prefix is dropped. */
 function splitLabel(label: string) {
   const slash = label.indexOf("/")
@@ -39,7 +39,7 @@ function ttftCell(value: string | undefined) {
 function cacheCell(value: string | undefined) {
   if (value === undefined) return "—".padStart(CACHE_CELL)
   const percent = value.endsWith("%") ? value.slice(0, -1) : value
-  return `${percent.padStart(3)}%`
+  return `${percent.padStart(5)}%`
 }
 
 /** A single model row: fold marker + summary line, plus its detail lines when expanded. */
@@ -65,25 +65,39 @@ function ModelRowView(props: { api: TuiPluginApi; row: ModelRow; expanded: boole
   return (
     <box flexDirection="column" onMouseDown={handleMouseDown} onMouseUp={handleMouseUp}>
       <text wrapMode="none" truncate>
+        {/* The most recently used model gets a green dot; other rows keep a blank slot so
+         * names stay aligned without spending extra width on a second marker. */}
+        <span style={{ fg: theme().success } as Record<string, unknown>}>{props.row.active ? "● " : "  "}</span>
         <span style={{ fg: theme().textMuted } as Record<string, unknown>}>{`${props.expanded ? "▼" : "▶"} `}</span>
         <Show when={props.row.subagent}>
           <span style={{ fg: theme().textMuted } as Record<string, unknown>}>{"↳ "}</span>
         </Show>
         <Show when={parts().provider}>
-          <span style={{ fg: theme().textMuted } as Record<string, unknown>}>{parts().provider}</span>
+          {/* Dimmed foreground sits between the model name and muted metadata without borrowing
+           * a status colour, so the provider reads as its own tier even as themes change. */}
+          <span style={{ fg: theme().text, dim: true } as Record<string, unknown>}>{parts().provider}</span>
         </Show>
         <span style={{ fg: theme().text } as Record<string, unknown>}>{parts().model}</span>
       </text>
       <Show when={props.expanded}>
         <text fg={theme().textMuted} wrapMode="none" truncate>
-          {`${DETAIL_INDENT}AVG ${rateCell(props.row.avg)}${
-            props.row.tps === undefined ? "" : ` · TPS ${rateCell(props.row.tps)}`
-          }`}
+          <span style={{ fg: theme().textMuted } as Record<string, unknown>}>
+            {`${DETAIL_INDENT}AVG ${rateCell(props.row.avg)}`}
+          </span>
+          <Show when={props.row.tps !== undefined}>
+            <span style={{ fg: theme().textMuted } as Record<string, unknown>}>{" · TPS "}</span>
+            {/* A frozen final reading stays visible but is dimmed to distinguish it from a
+             * value backed by an active stream. */}
+            <span style={{ fg: theme().textMuted, dim: !props.row.tpsLive } as Record<string, unknown>}>
+              {rateCell(props.row.tps)}
+            </span>
+          </Show>
         </text>
         <text fg={theme().textMuted} wrapMode="none" truncate>
-          {`${DETAIL_INDENT}TTFT ${ttftCell(props.row.ttft)} · CACHE ${cacheCell(props.row.cache)} · ${
-            props.row.cost ?? "—"
-          }`}
+          {`${DETAIL_INDENT}TTFT ${ttftCell(props.row.ttft)} · CACHE ${cacheCell(props.row.cache)}`}
+        </text>
+        <text fg={theme().textMuted} wrapMode="none" truncate>
+          {`${DETAIL_INDENT}${props.row.cost ?? "—"}`}
         </text>
       </Show>
     </box>
@@ -154,7 +168,7 @@ function ModelPanelView(props: {
   return (
     <box flexDirection="column">
       <text fg={props.api.theme.current.text} wrapMode="none" truncate>
-        <b>Performance · observed</b>
+        <b>Model-Performance · observed</b>
       </text>
       <Show when={panel().rows.length === 0}>
         <text fg={props.api.theme.current.textMuted} wrapMode="none" truncate>