oc-metricboard 0.1.4

package/src/metrics.ts

@@ -0,0 +1,243 @@
+// src/metrics.ts
+import type { BarConfig, CacheReadCompleteness, MetricsAggregate, RequestMetrics } from "./types"
+
+/**
+ * Token estimation consistent with OpenCode internals:
+ * OpenCode uses CHARS_PER_TOKEN = 4
+ * See opencode/packages/opencode/src/util/token.ts
+ */
+export function estimateTokens(text: string, ratio: number): number {
+  if (!text) return 0
+  const safeRatio = Number.isFinite(ratio) && ratio > 0 ? ratio : 4
+  let tokens = 0
+  for (const char of text) {
+    const isCjk = /\p{Script=Han}|\p{Script=Hiragana}|\p{Script=Katakana}|\p{Script=Hangul}/u.test(char)
+    tokens += isCjk ? 0.6 : 1 / safeRatio
+  }
+  return Math.max(0, tokens)
+}
+
+/**
+ * Get display output token count (output + reasoning).
+ * Prefer exact value, fall back to estimation.
+ */
+export function getDisplayOutputTokens(m: RequestMetrics): number {
+  if (m.hasExactTokens) {
+    return Math.max(0, m.exactOutputTokens + m.exactReasoningTokens)
+  }
+  return Math.max(0, m.estimatedOutputTokens)
+}
+
+/**
+ * Get display input token count (including cache).
+ * Exact value = input + cache.read + cache.write (total actually sent to model).
+ * Fall back to estimation.
+ */
+export function getDisplayInputTokens(m: RequestMetrics): number {
+  if (m.hasExactTokens) {
+    return Math.max(0, m.exactInputTokens + m.exactCacheReadTokens + m.exactCacheWriteTokens)
+  }
+  return Math.max(0, m.estimatedInputTokens)
+}
+
+export function formatCacheRead(n: number, completeness: CacheReadCompleteness): string {
+  if (completeness === "unknown") return "—"
+  return `${formatTokens(n)}${completeness === "partial" ? "+" : ""}`
+}
+
+export function aggregateRequestMetrics(
+  metrics: readonly RequestMetrics[],
+  now: number,
+): MetricsAggregate | null {
+  if (metrics.length === 0) return null
+
+  let inputTokens = 0
+  let outputTokens = 0
+  let cacheReadTokens = 0
+  let exactCacheCount = 0
+  let requestStartTime = Number.POSITIVE_INFINITY
+  let firstTokenTime: number | null = null
+  let completeTime: number | null = null
+  let isStreaming = false
+  let isComplete = true
+
+  for (const m of metrics) {
+    inputTokens += getDisplayInputTokens(m)
+    outputTokens += getDisplayOutputTokens(m)
+    if (m.hasExactCacheReadTokens) {
+      cacheReadTokens += Math.max(0, m.exactCacheReadTokens)
+      exactCacheCount += 1
+    }
+    requestStartTime = Math.min(requestStartTime, m.requestStartTime)
+    if (m.firstTokenTime !== null) {
+      firstTokenTime = firstTokenTime === null ? m.firstTokenTime : Math.min(firstTokenTime, m.firstTokenTime)
+    }
+    if (m.completeTime !== null) {
+      completeTime = completeTime === null ? m.completeTime : Math.max(completeTime, m.completeTime)
+    }
+    isStreaming = isStreaming || m.isStreaming
+    isComplete = isComplete && m.isComplete
+  }
+
+  const cacheReadCompleteness: CacheReadCompleteness =
+    exactCacheCount === 0 ? "unknown" : exactCacheCount === metrics.length ? "exact" : "partial"
+  const ttft = firstTokenTime === null ? null : Math.round(firstTokenTime - requestStartTime)
+  const sessionIDs = [...new Set(metrics.map((m) => m.sessionID))]
+
+  return {
+    sessionIDs,
+    childSessionCount: Math.max(0, sessionIDs.length - 1),
+    inputTokens,
+    outputTokens,
+    cacheReadTokens,
+    cacheReadCompleteness,
+    requestStartTime,
+    firstTokenTime,
+    completeTime: completeTime ?? (isComplete ? now : null),
+    ttft,
+    liveTps: null,
+    isStreaming,
+    isComplete,
+  }
+}
+
+/**
+ * Calculate time to first token (milliseconds)
+ *
+ * Sanity gate: after session reopen, hydration anchors requestStartTime to the
+ * preceding user message's created time. If that message is hours old (long
+ * session) while the assistant message is recent, the raw difference would be
+ * minutes — not a meaningful TTFT. Values above the threshold are reported as
+ * null (rendered "--") rather than a misleading huge duration.
+ */
+export const MAX_TTFT_MS = 10 * 60 * 1000
+
+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)
+}
+
+/**
+ * Calculate average token speed (tokens/second).
+ * Based on cumulative streaming time (now - firstTokenTime).
+ */
+export function getTps(m: RequestMetrics, now: number): number {
+  const baseTime = m.firstTokenTime ?? m.requestStartTime
+  const elapsedMs = now - baseTime
+  if (elapsedMs <= 0) return 0
+  const tokens = getDisplayOutputTokens(m)
+  return Math.round((tokens / (elapsedMs / 1000)) * 10) / 10
+}
+
+/**
+ * Format token count: show raw below 1000, otherwise X.XK
+ */
+export function formatTokens(n: number): string {
+  if (n < 1000) return String(Math.round(n))
+  return (n / 1000).toFixed(1) + "K"
+}
+
+/**
+ * Format duration (general):
+ * - < 1000ms: "312ms"
+ * - < 60000ms: "1.5s" / "15.0s"
+ * - >= 60000ms: "2m5s"
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`
+  const minutes = Math.floor(ms / 60000)
+  const seconds = Math.round((ms % 60000) / 1000)
+  return `${minutes}m${seconds}s`
+}
+
+/**
+ * Format elapsed time (always in whole seconds to avoid UI jitter):
+ * - < 60000ms: "0s" / "15s"
+ * - >= 60000ms: "2m5s"
+ */
+export function formatElapsed(ms: number): string {
+  ms = Math.max(0, ms)
+  if (ms < 60000) return `${Math.floor(ms / 1000)}s`
+  const minutes = Math.floor(ms / 60000)
+  const seconds = Math.floor((ms % 60000) / 1000)
+  return `${minutes}m${seconds}s`
+}
+
+/**
+ * Format session-level elapsed time from a stable session start timestamp.
+ */
+export function formatSessionElapsed(now: number, sessionStartTime: number): string {
+  return formatElapsed(now - sessionStartTime)
+}
+
+/**
+ * Format the full status bar string.
+ * Format: ⚡ 42.5 t/s  ⏱ TTFT 312ms  ↓ 1.2K in  ↑ 639 out  ○ cr 200  ▹ 15.0s  [model]
+ * Control visibility of each metric via config.visible.
+ */
+export function formatBar(m: RequestMetrics, now: number, config?: BarConfig): string {
+  const tps = getTps(m, now)
+  const ttft = getTtft(m)
+  const inputTokens = getDisplayInputTokens(m)
+  const outputTokens = getDisplayOutputTokens(m)
+  const cacheRead = m.hasExactCacheReadTokens ? Math.max(0, m.exactCacheReadTokens) : 0
+  const elapsedMs = now - m.requestStartTime
+  const vis = config?.visible
+
+  const parts: string[] = []
+
+  if (!vis || vis.speed)   parts.push(`⚡ ${tps.toFixed(1)} t/s`)
+  if (!vis || vis.ttft)    parts.push(`⏱ ${ttft !== null ? formatDuration(ttft) : "--"}`)
+  if (!vis || vis.input)   parts.push(`↓ ${formatTokens(inputTokens)} in`)
+  if (!vis || vis.output)  parts.push(`↑ ${formatTokens(outputTokens)} out`)
+  if ((!vis || vis.cache) && (m.hasExactTokens || m.hasExactCacheReadTokens)) {
+    parts.push(`○ ${formatCacheRead(cacheRead, m.hasExactCacheReadTokens ? "exact" : "unknown")}`)
+  }
+  if (!vis || vis.elapsed) parts.push(`▹ ${formatElapsed(elapsedMs)}`)
+
+  if (!vis || vis.model) {
+    const modelLabel = m.providerID && m.modelID
+      ? `${m.providerID}/${m.modelID}`
+      : m.modelID || "unknown"
+    parts.push(`[${modelLabel}]`)
+  }
+
+  return parts.join("  ")
+}
+
+/**
+ * Create initial RequestMetrics.
+ */
+export function createFreshMetrics(
+  sessionID: string,
+  messageID: string,
+  modelID: string,
+  providerID: string,
+  now: number,
+): RequestMetrics {
+  return {
+    sessionID,
+    messageID,
+    modelID,
+    providerID,
+    requestStartTime: now,
+    firstTokenTime: null,
+    lastDeltaTime: null,
+    completeTime: null,
+    estimatedInputTokens: 0,
+    estimatedOutputTokens: 0,
+    exactInputTokens: 0,
+    exactOutputTokens: 0,
+    exactCacheReadTokens: 0,
+    exactCacheWriteTokens: 0,
+    exactReasoningTokens: 0,
+    hasExactTokens: false,
+    hasExactCacheReadTokens: false,
+    hasExactCacheWriteTokens: false,
+    isStreaming: false,
+    isComplete: false,
+  }
+}

package/src/request-state.ts

@@ -0,0 +1,100 @@
+import type { RequestMetrics } from "./types"
+import { createFreshMetrics } from "./metrics"
+import { applySessionModel } from "./request-updates"
+import { clearLiveSpeed, resetLiveSpeed } from "./live-speed"
+import { completeTurn, ensureTurn, retireRequestIntoTurn, startTurn } from "./turn-state"
+import type { LiveSpeedState, TurnMetrics } from "./types"
+
+export interface RequestState {
+  readonly requests: Map<string, RequestMetrics>
+  readonly turns: Map<string, TurnMetrics>
+  readonly liveSpeeds: Map<string, LiveSpeedState>
+  readonly sessionModels: Map<string, { readonly modelID: string; readonly providerID: string }>
+  lastRequestSessionID: string | null
+}
+
+export interface RequestActions {
+  readonly clearHoldTimer: (sessionID: string) => void
+  readonly startSessionTiming: (sessionID: string, now: number) => void
+  readonly stopSessionTiming: (sessionID: string, now: number) => void
+  readonly notify: () => void
+}
+
+export interface CurrentRequestInput {
+  readonly state: RequestState
+  readonly actions: RequestActions
+  readonly sessionID: string
+  readonly messageID: string
+  readonly now: number
+}
+
+export function currentRequest(input: CurrentRequestInput): RequestMetrics {
+  const existing = input.state.requests.get(input.sessionID)
+  const isDifferentMessage = existing?.messageID.length ? existing.messageID !== input.messageID : false
+  if (!existing || isDifferentMessage) {
+    const priorTurn = input.state.turns.get(input.sessionID)
+    const startsAfterCompletedTurn = Boolean(priorTurn?.isComplete && isDifferentMessage)
+    const turn = startsAfterCompletedTurn
+      ? 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)
+    const current = createFreshMetrics(
+      input.sessionID,
+      input.messageID,
+      existing?.modelID ?? "",
+      existing?.providerID ?? "",
+      requestStartTime,
+    )
+    applySessionModel(current, input.state.sessionModels.get(input.sessionID))
+    input.state.requests.set(input.sessionID, current)
+    resetLiveSpeed(input.state.liveSpeeds, input.sessionID, input.messageID)
+    input.state.lastRequestSessionID = input.sessionID
+    input.actions.clearHoldTimer(input.sessionID)
+    return current
+  }
+  if (existing.messageID.length === 0) {
+    existing.messageID = input.messageID
+  }
+  input.state.lastRequestSessionID = input.sessionID
+  return existing
+}
+
+export interface CompleteRequestInput {
+  readonly state: RequestState & { readonly holdTimers: Map<string, ReturnType<typeof setTimeout>> }
+  readonly actions: RequestActions
+  readonly sessionID: string
+  readonly now: number
+  readonly holdDurationMs: number
+  readonly log: (msg: string) => void
+}
+
+export function completeRequest(input: CompleteRequestInput): void {
+  const current = input.state.requests.get(input.sessionID)
+  input.actions.stopSessionTiming(input.sessionID, input.now)
+  const turn = input.state.turns.get(input.sessionID)
+  if (current && turn) retireRequestIntoTurn(turn, current)
+  if (turn) completeTurn(turn, input.now)
+  clearLiveSpeed(input.state.liveSpeeds, input.sessionID)
+  if (!current) return
+  current.isStreaming = false
+  current.isComplete = true
+  current.completeTime = input.now
+  input.log(`request complete: session=${input.sessionID}`)
+  input.actions.notify()
+  if (input.holdDurationMs <= 0) return
+  input.actions.clearHoldTimer(input.sessionID)
+  input.state.holdTimers.set(input.sessionID, setTimeout(() => {
+    input.state.holdTimers.delete(input.sessionID)
+    if (input.state.requests.get(input.sessionID)?.sessionID === input.sessionID) {
+      input.state.requests.delete(input.sessionID)
+      input.actions.notify()
+    }
+  }, input.holdDurationMs))
+}

package/src/request-updates.ts

@@ -0,0 +1,40 @@
+import type { AssistantMessageEvent, AssistantTokenUpdate } from "./event-shapes"
+import type { RequestMetrics } from "./types"
+
+export interface SessionModel {
+  readonly modelID: string
+  readonly providerID: string
+}
+
+export function mergeAssistantModel(
+  existing: SessionModel | undefined,
+  message: AssistantMessageEvent,
+): SessionModel | null {
+  const modelID = message.modelID || existing?.modelID || ""
+  const providerID = message.providerID || existing?.providerID || ""
+  return modelID || providerID ? { modelID, providerID } : null
+}
+
+export function applySessionModel(metrics: RequestMetrics, model: SessionModel | undefined): void {
+  if (!model) return
+  metrics.modelID = model.modelID
+  metrics.providerID = model.providerID
+}
+
+export function hasPositiveAssistantTokens(tokens: AssistantTokenUpdate | null | undefined): tokens is AssistantTokenUpdate {
+  if (!tokens?.hasAny) return false
+  return tokens.input + tokens.output + tokens.reasoning + tokens.cacheRead + tokens.cacheWrite > 0
+}
+
+export function applyAssistantTokens(metrics: RequestMetrics, tokens: AssistantTokenUpdate): boolean {
+  if (!hasPositiveAssistantTokens(tokens)) return false
+  metrics.exactInputTokens = tokens.input
+  metrics.exactOutputTokens = tokens.output
+  metrics.exactReasoningTokens = tokens.reasoning
+  metrics.exactCacheReadTokens = tokens.cacheRead
+  metrics.exactCacheWriteTokens = tokens.cacheWrite
+  metrics.hasExactTokens = true
+  metrics.hasExactCacheReadTokens = tokens.hasCacheRead
+  metrics.hasExactCacheWriteTokens = tokens.hasCacheWrite
+  return true
+}

package/src/scripts/init-tui-preferences.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * Init/default writer for opencode-metrics TUI preferences.
+ *
+ * Inserts missing `opencode-metrics` defaults into the target prefs file
+ * (default: ~/.config/opencode/tui-preferences.jsonc). If `opencode-metrics`
+ * already exists, fills only missing nested defaults and preserves user values.
+ *
+ * If the file is malformed or `opencode-metrics` is a non-object, fails safely
+ * without overwriting. Uses same-directory temp file + rename for atomic write.
+ *
+ * Override the target with OPENCODE_TUI_PREFERENCES_FILE env var.
+ */
+import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync } from "node:fs"
+import { dirname } from "node:path"
+import { parse, stringify } from "comment-json"
+import {
+    DEFAULT_PREFS,
+    PLUGIN_KEY,
+} from "../tui-preferences"
+import { getTuiPreferencesFile } from "../tui-prefs-io"
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function deepFillDefaults(target: Record<string, unknown>, defaults: Record<string, unknown>): void {
+    for (const key of Object.keys(defaults)) {
+        if (!(key in target)) {
+            target[key] = structuredClone(defaults[key])
+        } else if (isRecord(defaults[key]) && isRecord(target[key])) {
+            deepFillDefaults(target[key] as Record<string, unknown>, defaults[key] as Record<string, unknown>)
+        }
+    }
+}
+
+export interface InitResult {
+    ok: boolean
+    file: string
+    reason?: string
+}
+
+export function initPreferences(fileOverride?: string): InitResult {
+    const file = fileOverride ?? getTuiPreferencesFile()
+
+    let text = ""
+    if (existsSync(file)) {
+        try {
+            text = readFileSync(file, "utf8")
+        } catch {
+            return { ok: false, file, reason: "cannot read file" }
+        }
+    }
+
+    let root: unknown = {}
+    if (text.trim() !== "") {
+        try {
+            root = parse(text)
+        } catch {
+            return { ok: false, file, reason: "malformed JSON/JSONC — not overwriting" }
+        }
+    }
+    if (!isRecord(root)) {
+        return { ok: false, file, reason: "root is not an object — not overwriting" }
+    }
+
+    const existing = root[PLUGIN_KEY]
+    if (existing !== undefined && !isRecord(existing)) {
+        return { ok: false, file, reason: `${PLUGIN_KEY} is not an object — not overwriting` }
+    }
+
+    if (!isRecord(root[PLUGIN_KEY])) {
+        root[PLUGIN_KEY] = structuredClone(DEFAULT_PREFS)
+    } else {
+        deepFillDefaults(root[PLUGIN_KEY] as Record<string, unknown>, DEFAULT_PREFS as unknown as Record<string, unknown>)
+    }
+
+    const output = `${stringify(root, null, 2)}\n`
+    const tmp = `${file}.init.${process.pid}.tmp`
+
+    try {
+        mkdirSync(dirname(file), { recursive: true })
+        writeFileSync(tmp, output, "utf8")
+        renameSync(tmp, file)
+    } catch (err) {
+        return { ok: false, file, reason: String(err) }
+    }
+
+    return { ok: true, file }
+}
+
+// CLI entry — runs only when executed directly, not when imported for tests.
+const isDirectRun =
+    typeof process !== "undefined" &&
+    process.argv[1] != null &&
+    (process.argv[1].endsWith("init-tui-preferences.ts") ||
+        process.argv[1].endsWith("init-tui-preferences.js"))
+
+if (isDirectRun) {
+    const result = initPreferences()
+    if (result.ok) {
+        console.log(`opencode-metrics: defaults written to ${result.file}`)
+    } else {
+        console.error(`opencode-metrics: ${result.reason} (${result.file})`)
+        process.exit(1)
+    }
+}