oc-metricboard 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oc-metricboard",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "OpenCode TUI sidebar plugin showing real-time LLM metrics (TPS, TTFT, tokens) with sub-agent × model breakdown",
   "keywords": [
     "opencode",

package/src/assistant-progress.ts

@@ -4,6 +4,7 @@ import { currentRequest } from "./request-state"
 import { eventAggregateID, eventID, eventProperties, stringEventProperty } from "./event-bus"
 import type { EventHandlerContext } from "./collector-state"
 import { recordLiveTokens } from "./live-speed"
+import { ensureTurn, recordTurnFirstToken } from "./turn-state"
 
 export interface AssistantProgressPart {
   readonly partID: string
@@ -26,6 +27,7 @@ function applyTokenDelta(
   if (state.turns.get(sessionID)?.finalizedSteps.has(messageID)) return
   const current = currentRequest({ state, actions, sessionID, messageID, now })
   if (current.firstTokenTime === null) current.firstTokenTime = now
+  recordTurnFirstToken(ensureTurn(state.turns, sessionID, now), now)
   if (deltaTokens > 0) {
     current.estimatedOutputTokens += deltaTokens
     current.lastDeltaTime = now

package/src/collector.ts

@@ -1,6 +1,6 @@
 import type { TuiPluginApi } from "@opencode-ai/plugin/tui"
 import type { BarConfig, CacheReadCompleteness, MetricsAggregate, MetricsScope, ModelMetrics, RequestMetrics } from "./types"
-import { getDisplayInputTokens, getDisplayOutputTokens, getTtft } from "./metrics"
+import { getDisplayInputTokens, getDisplayOutputTokens, gateTtft, getTtft } from "./metrics"
 import { registerEventHandlers } from "./event-handlers"
 import type { CollectorState } from "./collector-state"
 import type { MetricsEventApi } from "./event-bus"
@@ -352,7 +352,7 @@ export function createCollector(
 
       const cacheReadCompleteness: CacheReadCompleteness =
         exactCacheCount === 0 ? "unknown" : exactCacheCount === metrics.length ? "exact" : "partial"
-      const ttft = firstTokenTime === null ? null : Math.round(firstTokenTime - requestStartTime)
+      const ttft = firstTokenTime === null ? null : gateTtft(firstTokenTime - requestStartTime)
 
       // Live TPS for this model group
       let liveTps = 0
@@ -546,7 +546,15 @@ export function createCollector(
 
       // NEW: Build per-model breakdown for tree scope
       const modelBreakdown = scope === "tree" ? aggregateByModel(ids, now, scope) : []
-      const ttft = foregroundRequest ? getTtft(foregroundRequest) : null
+      // Turn-level TTFT: opencode stamps step.started at the first token, so
+      // intra-turn steps cannot measure their own request start (they would
+      // collapse to ~0). Anchor TTFT to the turn's user message instead —
+      // stable across all steps within a turn, refreshed on each new turn.
+      // Falls back to the per-request measurement when no turn timing exists.
+      const turnTtft = foregroundTurn?.firstTokenTime != null
+        ? gateTtft(foregroundTurn.firstTokenTime - foregroundTurn.turnStartTime)
+        : null
+      const ttft = turnTtft ?? (foregroundRequest ? getTtft(foregroundRequest) : null)
 
       const result: MetricsAggregate = {
         sessionIDs: contributingSessionIDs.length > 0 ? contributingSessionIDs : [rootID],

package/src/metrics.ts

@@ -81,7 +81,7 @@ export function aggregateRequestMetrics(
 
   const cacheReadCompleteness: CacheReadCompleteness =
     exactCacheCount === 0 ? "unknown" : exactCacheCount === metrics.length ? "exact" : "partial"
-  const ttft = firstTokenTime === null ? null : Math.round(firstTokenTime - requestStartTime)
+  const ttft = firstTokenTime === null ? null : gateTtft(firstTokenTime - requestStartTime)
   const sessionIDs = [...new Set(metrics.map((m) => m.sessionID))]
 
   return {
@@ -98,6 +98,7 @@ export function aggregateRequestMetrics(
     liveTps: null,
     isStreaming,
     isComplete,
+    modelBreakdown: [],
   }
 }
 
@@ -112,11 +113,18 @@ export function aggregateRequestMetrics(
  */
 export const MAX_TTFT_MS = 10 * 60 * 1000
 
+/**
+ * Gate a raw TTFT value: non-finite, negative, or beyond MAX_TTFT_MS is not a
+ * meaningful TTFT and is reported as null (rendered "--").
+ */
+export function gateTtft(rawMs: number): number | null {
+  if (!Number.isFinite(rawMs) || rawMs < 0 || rawMs > MAX_TTFT_MS) return null
+  return Math.round(rawMs)
+}
+
 export function getTtft(m: RequestMetrics): number | null {
   if (m.firstTokenTime === null) return null
-  const ttft = m.firstTokenTime - m.requestStartTime
-  if (!Number.isFinite(ttft) || ttft < 0 || ttft > MAX_TTFT_MS) return null
-  return Math.round(ttft)
+  return gateTtft(m.firstTokenTime - m.requestStartTime)
 }
 
 /**

package/src/request-state.ts

@@ -38,13 +38,18 @@ export function currentRequest(input: CurrentRequestInput): RequestMetrics {
       ? startTurn(input.state.turns, input.sessionID, input.now)
       : ensureTurn(input.state.turns, input.sessionID, existing?.requestStartTime ?? input.now)
     if (existing && isDifferentMessage && !startsAfterCompletedTurn) retireRequestIntoTurn(turn, existing)
-    // Keep the existing request's start time when continuing the same turn:
-    // opencode 1.18.x stamps step.started lazily at the first token, so a fresh
-    // `now` here would collapse TTFT to ~0. The user message's created time is
-    // the correct "request submitted" anchor.
-    const requestStartTime = startsAfterCompletedTurn
-      ? input.now
-      : (existing?.requestStartTime ?? input.now)
+    // Keep the existing request's start time ONLY while the existing request
+    // is still an un-streamed placeholder (opencode 1.18.x stamps
+    // step.started lazily at the first token, so the user message's created
+    // time is the correct "request submitted" anchor). Once the previous
+    // request has produced a first token it was a real generation, and a new
+    // messageID is a NEW step: it must NOT inherit the turn's original start
+    // time, otherwise TTFT absorbs every tool execution since the turn began
+    // (huge TTFT in long agentic sessions).
+    const inheritAnchor = !startsAfterCompletedTurn && (existing?.firstTokenTime ?? null) === null
+    const requestStartTime = inheritAnchor
+      ? (existing?.requestStartTime ?? input.now)
+      : input.now
     const current = createFreshMetrics(
       input.sessionID,
       input.messageID,

package/src/session-hydration.ts

@@ -233,6 +233,11 @@ export async function hydrateSession(input: HydrateSessionInput): Promise<boolea
     input.now,
   ) ?? requestStartTime
   const turn = createTurnMetrics(input.sessionID, turnStartTime)
+  // Turn-level TTFT anchor: the first trailing assistant's createdTime is
+  // stamped at its first token, so turnStart → that instant is the hydrated
+  // turn's time-to-first-token. Fall back to the live request's first token.
+  turn.firstTokenTime = toPerformanceTime(trailingAssistants[0]?.createdTime, input.now)
+    ?? current.firstTokenTime
   for (const step of trailingAssistants) {
     if (!step.tokens || !hasPositiveAssistantTokens(step.tokens)) continue
     const stepStart = toPerformanceTime(step.createdTime, input.now) ?? turnStartTime

package/src/turn-state.ts

@@ -5,6 +5,7 @@ export function createTurnMetrics(sessionID: string, now: number): TurnMetrics {
   return {
     sessionID,
     turnStartTime: now,
+    firstTokenTime: null,
     completeTime: null,
     finalizedOutputTokens: 0,
     finalizedSteps: new Map(),
@@ -83,3 +84,13 @@ export function completeTurn(turn: TurnMetrics, now: number): void {
   turn.isComplete = true
   turn.completeTime = now
 }
+
+/**
+ * Record the turn's first token instant (once). opencode stamps step.started
+ * at the first token, so intra-turn steps cannot measure their own request
+ * start; the turn-level anchor (user message → first delta) is the only
+ * meaningful TTFT observable from the event stream.
+ */
+export function recordTurnFirstToken(turn: TurnMetrics, now: number): void {
+  if (turn.firstTokenTime === null) turn.firstTokenTime = now
+}

package/src/types.ts

@@ -37,6 +37,7 @@ export interface FinalizedStepUsage {
 export interface TurnMetrics {
   sessionID: string
   turnStartTime: number
+  firstTokenTime: number | null        // First token of the turn (user message → first delta)
   completeTime: number | null
   finalizedOutputTokens: number
   finalizedSteps: Map<string, FinalizedStepUsage>