oc-metricboard 0.1.4

package/src/tui-prefs-io.ts

@@ -0,0 +1,159 @@
+import { readFileSync, watch } from "node:fs"
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises"
+import { homedir } from "node:os"
+import { basename, dirname, join } from "node:path"
+import { parse, stringify } from "comment-json"
+
+// Generic preferences file I/O for OpenCode TUI plugins.
+// Plugin-specific types, defaults, and validation live in tui-preferences.ts.
+
+export const TUI_PREFS_FILE_ENV = "OPENCODE_TUI_PREFERENCES_FILE"
+const FILE_NAME = "tui-preferences.jsonc"
+
+export function getTuiPreferencesFile(): string {
+    const override = process.env[TUI_PREFS_FILE_ENV]
+    if (override) return override
+    const configDir =
+        process.env.OPENCODE_CONFIG_DIR ||
+        join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "opencode")
+    return join(configDir, FILE_NAME)
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+// Tolerant read: a missing file, parse error, or non-object root all resolve
+// to {} so the sidebar never crashes on hand-edited content. Never throws.
+export async function readTuiPreferencesFile(): Promise<Record<string, unknown>> {
+    try {
+        const raw = await readFile(getTuiPreferencesFile(), "utf8")
+        if (raw.trim() === "") return {}
+        const root: unknown = parse(raw)
+        return isRecord(root) ? (root as Record<string, unknown>) : {}
+    } catch {
+        return {}
+    }
+}
+
+// Synchronous tolerant read — used once at slot mount to seed the initial
+// collapse state and effective order WITHOUT a frame of async flicker.
+export function readTuiPreferencesFileSync(): Record<string, unknown> {
+    try {
+        const raw = readFileSync(getTuiPreferencesFile(), "utf8")
+        if (raw.trim() === "") return {}
+        const root: unknown = parse(raw)
+        return isRecord(root) ? (root as Record<string, unknown>) : {}
+    } catch {
+        return {}
+    }
+}
+
+const TEMPLATE = `// Shared preferences for OpenCode TUI plugins.
+// One top-level key per plugin (short name). See each plugin's README for its
+// supported settings. This file is safe to hand-edit; plugins update individual
+// keys and preserve the rest (values and comments).
+{}
+`
+
+type JsonValue = string | number | boolean | null
+
+function setDeep(root: Record<string, unknown>, path: string[], value: JsonValue): boolean {
+    let node: Record<string, unknown> = root
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const key = path[i]
+        const child = node[key]
+        if (child === undefined || child === null) {
+            node[key] = {}
+        } else if (!isRecord(child)) {
+            return false
+        }
+        node = node[key] as Record<string, unknown>
+    }
+    node[path[path.length - 1]] = value
+    return true
+}
+
+async function writePreference(pluginKey: string, path: string[], value: JsonValue): Promise<void> {
+    const file = getTuiPreferencesFile()
+    await mkdir(dirname(file), { recursive: true })
+    let text: string
+    try {
+        text = await readFile(file, "utf8")
+    } catch {
+        text = ""
+    }
+    if (text.trim() === "") text = TEMPLATE
+
+    let root: unknown
+    try {
+        root = parse(text)
+    } catch {
+        return
+    }
+    if (!isRecord(root)) root = {}
+    if (!setDeep(root as Record<string, unknown>, [pluginKey, ...path], value)) {
+        return
+    }
+
+    const next = `${stringify(root, null, 2)}\n`
+    const tmp = `${file}.${process.pid}.tmp`
+    await writeFile(tmp, next, "utf8")
+    await rename(tmp, file)
+}
+
+let writeChain: Promise<void> = Promise.resolve()
+
+// Writes are serialized on a promise chain: each update re-reads the file,
+// applies a comment-preserving edit to one property, and replaces the file
+// atomically (temp + rename in the same directory).
+export function queueTuiPreferenceUpdate(
+    pluginKey: string,
+    path: string[],
+    value: JsonValue,
+): Promise<void> {
+    writeChain = writeChain.then(() => writePreference(pluginKey, path, value)).catch(() => {})
+    return writeChain
+}
+
+const WATCH_DEBOUNCE_MS = 150
+
+// Watches the DIRECTORY, not the file: editors and our own atomic writes
+// replace the file via rename, which kills file-level watchers.
+export function watchTuiPreferences(onChange: () => void): () => void {
+    const file = getTuiPreferencesFile()
+    const name = basename(file)
+    let timer: ReturnType<typeof setTimeout> | null = null
+    let lastSeen: string | null = null
+    void readFile(file, "utf8")
+        .then((text) => {
+            if (lastSeen === null) lastSeen = text
+        })
+        .catch(() => {})
+    try {
+        const watcher = watch(dirname(file), (_event, filename) => {
+            const isOurs =
+                filename === name ||
+                (filename?.startsWith(`${name}.`) && filename.endsWith(".tmp"))
+            if (filename != null && !isOurs) return
+            if (timer) clearTimeout(timer)
+            timer = setTimeout(() => {
+                timer = null
+                void readFile(file, "utf8")
+                    .catch(() => null)
+                    .then((text) => {
+                        if (text === null) return
+                        if (text === lastSeen) return
+                        lastSeen = text
+                        onChange()
+                    })
+            }, WATCH_DEBOUNCE_MS)
+        })
+        return () => {
+            if (timer) clearTimeout(timer)
+            watcher.close()
+        }
+    } catch {
+        return () => {}
+    }
+}

package/src/tui.tsx

@@ -0,0 +1,60 @@
+/** @jsxImportSource @opentui/solid */
+/** @jsxRuntime automatic */
+import type { TuiPlugin, TuiPluginApi, TuiPluginMeta } from "@opencode-ai/plugin/tui"
+import type { PluginOptions } from "@opencode-ai/plugin"
+import { createCollector } from "./collector"
+import { getConfig } from "./config"
+import { log } from "./logger"
+import { SidebarMetrics } from "./components/SidebarMetrics"
+import {
+    computeEffectiveOrder,
+    createMetricsSidebarController,
+    DEFAULT_SLOT_ORDER,
+    PLUGIN_KEY,
+    resolveMetricsPrefs,
+} from "./tui-preferences"
+import { readTuiPreferencesFileSync } from "./tui-prefs-io"
+
+const plugin: TuiPlugin = async (api: TuiPluginApi, _options: PluginOptions | undefined, _meta: TuiPluginMeta) => {
+    const config = getConfig()
+    const collector = createCollector(api, config, log)
+
+    // Sync-read preferences at slot mount so the sidebar renders at its final
+    // order and collapse state on the first paint (no async flicker).
+    const seedRoot = readTuiPreferencesFileSync()
+    const effectiveOrder = computeEffectiveOrder(seedRoot, PLUGIN_KEY, DEFAULT_SLOT_ORDER)
+    const prefs = resolveMetricsPrefs(seedRoot)
+    const controller = createMetricsSidebarController(prefs, () => api.renderer.requestRender())
+
+    api.slots.register({
+        order: effectiveOrder,
+        slots: {
+            sidebar_content(ctx, props) {
+                return (
+                    <SidebarMetrics
+                        sessionID={props.session_id}
+                        collector={collector}
+                        refreshIntervalMs={config.refreshIntervalMs}
+                        barConfig={config}
+                        theme={ctx.theme.current}
+                        controller={controller}
+                        requestRender={() => api.renderer.requestRender()}
+                    />
+                )
+            },
+        },
+    })
+
+    api.lifecycle.onDispose(() => {
+        collector.dispose()
+    })
+
+    log("opencode-metrics sidebar initialized")
+}
+
+const pluginModule: { id: string; tui: TuiPlugin } = {
+    id: "oc-metricboard",
+    tui: plugin,
+}
+
+export default pluginModule

package/src/turn-state.ts

@@ -0,0 +1,85 @@
+import { getDisplayInputTokens, getDisplayOutputTokens } from "./metrics"
+import type { RequestMetrics, TurnMetrics } from "./types"
+
+export function createTurnMetrics(sessionID: string, now: number): TurnMetrics {
+  return {
+    sessionID,
+    turnStartTime: now,
+    completeTime: null,
+    finalizedOutputTokens: 0,
+    finalizedSteps: new Map(),
+    stickyContextTokens: 0,
+    stickyContextUpdatedAt: Number.NEGATIVE_INFINITY,
+    hasStickyContextTokens: false,
+    stickyCacheReadTokens: 0,
+    hasStickyCacheReadTokens: false,
+    isComplete: false,
+  }
+}
+
+export function ensureTurn(
+  turns: Map<string, TurnMetrics>,
+  sessionID: string,
+  now: number,
+): TurnMetrics {
+  const existing = turns.get(sessionID)
+  if (existing) return existing
+  const turn = createTurnMetrics(sessionID, now)
+  turns.set(sessionID, turn)
+  return turn
+}
+
+export function startTurn(
+  turns: Map<string, TurnMetrics>,
+  sessionID: string,
+  now: number,
+): TurnMetrics {
+  const turn = createTurnMetrics(sessionID, now)
+  turns.set(sessionID, turn)
+  return turn
+}
+
+export function retireRequestIntoTurn(
+  turn: TurnMetrics,
+  request: RequestMetrics,
+  updateSticky = true,
+): boolean {
+  if (!request.messageID) return false
+  const outputTokens = getDisplayOutputTokens(request)
+  const exact = request.hasExactTokens
+  const previous = turn.finalizedSteps.get(request.messageID)
+
+  if (!previous) {
+    turn.finalizedSteps.set(request.messageID, { outputTokens, exact })
+    turn.finalizedOutputTokens += outputTokens
+  } else if (!previous.exact && exact) {
+    turn.finalizedOutputTokens += outputTokens - previous.outputTokens
+    turn.finalizedSteps.set(request.messageID, { outputTokens, exact: true })
+  } else {
+    return false
+  }
+
+  if (updateSticky && exact && request.requestStartTime >= turn.stickyContextUpdatedAt) {
+    turn.stickyContextTokens = getDisplayInputTokens(request)
+    turn.stickyContextUpdatedAt = request.requestStartTime
+    turn.hasStickyContextTokens = true
+    turn.stickyCacheReadTokens = Math.max(0, request.exactCacheReadTokens)
+    turn.hasStickyCacheReadTokens = request.hasExactCacheReadTokens
+  }
+  return true
+}
+
+export function liveRequestOutput(turn: TurnMetrics, request: RequestMetrics | undefined): number {
+  if (!request?.messageID || turn.finalizedSteps.has(request.messageID)) return 0
+  return getDisplayOutputTokens(request)
+}
+
+export function turnInputTokens(turn: TurnMetrics, request: RequestMetrics | undefined): number {
+  if (turn.hasStickyContextTokens) return turn.stickyContextTokens
+  return request ? getDisplayInputTokens(request) : 0
+}
+
+export function completeTurn(turn: TurnMetrics, now: number): void {
+  turn.isComplete = true
+  turn.completeTime = now
+}

package/src/types.ts

@@ -0,0 +1,138 @@
+// src/types.ts
+
+export interface RequestMetrics {
+  sessionID: string
+  messageID: string
+  modelID: string
+  providerID: string
+
+  // Timing
+  requestStartTime: number              // performance.now()
+  firstTokenTime: number | null         // Timestamp when first text delta arrives
+  lastDeltaTime: number | null          // Last delta arrival time
+  completeTime: number | null           // Idle timestamp
+
+  // Token counts
+  estimatedInputTokens: number          // Estimated from user message content length / ratio
+  estimatedOutputTokens: number         // Accumulated from delta.length / ratio
+  exactInputTokens: number              // From AssistantMessage.tokens
+  exactOutputTokens: number
+  exactCacheReadTokens: number
+  exactCacheWriteTokens: number
+  exactReasoningTokens: number
+  hasExactTokens: boolean               // Whether exact values have been received
+  hasExactCacheReadTokens: boolean
+  hasExactCacheWriteTokens: boolean
+
+  // State
+  isStreaming: boolean                  // Whether still streaming
+  isComplete: boolean                   // Whether request is complete (idle)
+}
+
+export interface FinalizedStepUsage {
+  outputTokens: number
+  exact: boolean
+}
+
+export interface TurnMetrics {
+  sessionID: string
+  turnStartTime: number
+  completeTime: number | null
+  finalizedOutputTokens: number
+  finalizedSteps: Map<string, FinalizedStepUsage>
+  stickyContextTokens: number
+  stickyContextUpdatedAt: number
+  hasStickyContextTokens: boolean
+  stickyCacheReadTokens: number
+  hasStickyCacheReadTokens: boolean
+  isComplete: boolean
+}
+
+export interface LiveSpeedSample {
+  at: number
+  cumulativeTokens: number
+}
+
+export interface LiveSpeedState {
+  messageID: string
+  cumulativeTokens: number
+  samples: LiveSpeedSample[]
+}
+
+export type MetricsScope = "current" | "tree"
+
+export type CacheReadCompleteness = "exact" | "partial" | "unknown"
+
+export interface ModelMetrics {
+  modelID: string
+  providerID: string
+  sessionID: string
+  // Number of sub-agent sessions sharing this (provider, model) — used for the
+  // "×N" count in the model-grouped breakdown.
+  sessionCount: number
+  inputTokens: number
+  outputTokens: number
+  cacheReadTokens: number
+  cacheReadCompleteness: CacheReadCompleteness
+  requestStartTime: number
+  firstTokenTime: number | null
+  completeTime: number | null
+  ttft: number | null
+  liveTps: number | null
+  isStreaming: boolean
+  isComplete: boolean
+}
+
+export interface MetricsAggregate {
+  sessionIDs: string[]
+  childSessionCount: number
+  inputTokens: number
+  outputTokens: number
+  cacheReadTokens: number
+  cacheReadCompleteness: CacheReadCompleteness
+  requestStartTime: number
+  firstTokenTime: number | null
+  completeTime: number | null
+  ttft: number | null
+  liveTps: number | null
+  isStreaming: boolean
+  isComplete: boolean
+  // NEW: per-model breakdown for tree scope
+  modelBreakdown: ModelMetrics[]
+}
+
+export interface BarConfig {
+  refreshIntervalMs: number
+  holdDurationMs: number
+  estimationRatio: number
+  enableLogging: boolean
+  visible: {
+    speed: boolean
+    ttft: boolean
+    input: boolean
+    output: boolean
+    cache: boolean
+    elapsed: boolean
+    session: boolean
+    model: boolean
+    modelBreakdown: boolean
+  }
+}
+
+export const DEFAULT_CONFIG: BarConfig = {
+  refreshIntervalMs: 200,
+  holdDurationMs: 0,
+  estimationRatio: 4.0,
+  enableLogging: false,
+  visible: {
+    speed: true,
+    ttft: true,
+    input: true,
+    output: true,
+    cache: false,
+    elapsed: true,
+    session: true,
+    model: true,
+    modelBreakdown: true,
+  },
+}