oc-metricboard 0.1.4

package/README.md

@@ -0,0 +1,137 @@
+# oc-metricboard
+
+OpenCode TUI sidebar plugin for real-time LLM metrics (TPS / TTFT / token usage) with **sub-agent aggregation** and **per-model breakdown**.
+
+Based on [opencode-metrics](https://github.com/nxxxsooo/opencode-metrics) with a streamlined display, sub-agent × model grouping, and production-hardening fixes.
+
+## Features
+
+- **Real-time TPS** — live rolling-window rate while streaming, frozen average on completion (sanity-gated against absurd values)
+- **TTFT** — time to first token, anchored to the user message (not the lazy `step.started` event)
+- **Token usage** — exact input/output counts from provider (estimated fallback)
+- **Sub-agent aggregation** (`scope: "tree"`) — merges all descendant sub-agent sessions
+- **Per-model breakdown** — one row per distinct model with `×N` session count
+- **Collapsed quick-view** — keeps a compact TPS + Session summary while collapsed
+- **Compact layout** — no vertical gaps, no value truncation in narrow sidebars
+
+### Display
+
+```
+▼ MetricBoard
+  TPS             ⚡ 116.9 t/s
+  Elapsed         ▹ 1m5s
+  TTFT            ⏱ 57.8s
+  Tokens          ↓ 603.1K in  ↑ 3.9K out
+  Session         ◷ 1m49s
+
+  deepseek-v4-flash
+      ⚡116.9 ⏱7.8s ↓595.9K ↑902
+  mimo-v2.5-free ×4
+      ⚡67.3 ⏱2.1s ↓78.3K ↑5.0K
+```
+
+## Installation
+
+### From npm (after publishing)
+
+```bash
+opencode plugin oc-metricboard --global
+```
+
+or add to your config:
+
+```json
+{
+  "plugin": ["oc-metricboard"]
+}
+```
+
+### Local development (tarball)
+
+```json
+{
+  "plugin": ["file:///absolute/path/to/oc-metricboard-0.1.4.tgz"]
+}
+```
+
+Restart OpenCode TUI afterwards. Plugins load at TUI startup and are not hot-reloaded.
+
+## Configuration
+
+Preferences live in `~/.config/opencode/tui-preferences.jsonc` under the `oc-metricboard` key:
+
+```jsonc
+{
+  "oc-metricboard": {
+    "scope": "tree",              // "current" | "tree" — tree enables sub-agent aggregation
+    "section": {
+      "enabled": true,
+      "collapsed": false,
+      "rememberCollapsed": true,
+      "label": "MetricBoard"
+    },
+    "rows": {
+      "tps": true,                // TPS row (renamed from "speed")
+      "ttft": true,               // Time to first token
+      "input": true,              // Input tokens
+      "output": true,             // Output tokens
+      "cache": false,             // Cache read tokens (off by default)
+      "elapsed": true,            // Request elapsed time
+      "session": true,            // Session cumulative time
+      "modelBreakdown": true      // Per-model rows in tree scope
+    }
+  }
+}
+```
+
+Runtime behavior (`refreshIntervalMs`, `holdDurationMs`, `estimationRatio`, `enableLogging`) is read from `~/.config/opencode/opencode-bar.json`:
+
+```jsonc
+{
+  "refreshIntervalMs": 200,
+  "holdDurationMs": 0,
+  "estimationRatio": 4.0,
+  "enableLogging": false
+}
+```
+
+## How it works
+
+The plugin subscribes to OpenCode events:
+
+- `session.created/updated/status` — builds the session tree
+- `message.part.delta`, `session.next.text.delta` — live token estimation and TPS window
+- `session.next.step.started/ended` — exact token counts from provider
+- `message.updated` — model attribution and exact counts
+- `session.idle` — request completion
+
+For **tree scope** it additionally:
+
+1. Queries `session.children` (SDK client) to build the sub-agent hierarchy
+2. Hydrates descendant sessions via the async SDK client (`session.messages` / `session.status`)
+3. Groups requests by `(modelID, providerID)`, summing tokens and pooling sessions into a `×N` count
+4. Renders one compact two-line entry per model group
+
+### Design notes
+
+- **Aggregate cache** (150 ms TTL): multiple sidebar rows share one aggregation pass per render tick to avoid redundant O(tree) work and UI jank.
+- **TTFT anchor**: uses the preceding user message's created time — opencode 1.18.x stamps `step.started` lazily at the first token, which would otherwise collapse TTFT to ~0.
+- **Timing sanity**: negative timestamps (from hydrating messages older than the TUI process) and implausible spans are reported as `--`, not garbage numbers.
+- **Hydration bounds**: at most 5 attempts per session; a session with no token history is not retried forever.
+
+## Development
+
+```bash
+npm install
+npm run build        # tsup bundle check
+npm test             # bun test (requires bun)
+npm pack --dry-run   # verify publish contents
+```
+
+## Credits
+
+Forked from [opencode-metrics](https://github.com/nxxxsooo/opencode-metrics) by nxxxsooo, itself a rewrite of [Icicno/opencodeBar](https://github.com/Icicno/opencodeBar).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "oc-metricboard",
+  "version": "0.1.4",
+  "description": "OpenCode TUI sidebar plugin showing real-time LLM metrics (TPS, TTFT, tokens) with sub-agent × model breakdown",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "tui",
+    "metrics",
+    "tps",
+    "ttft",
+    "tokens",
+    "monitoring",
+    "sub-agent",
+    "llm"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JasonJason-oy/oc-metricboard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JasonJason-oy/oc-metricboard/issues"
+  },
+  "homepage": "https://github.com/JasonJason-oy/oc-metricboard#readme",
+  "engines": {
+    "opencode": ">=1.14.22",
+    "node": ">=20.11"
+  },
+  "type": "module",
+  "main": "./src/tui.tsx",
+  "exports": {
+    ".": {
+      "import": "./src/tui.tsx"
+    },
+    "./tui": {
+      "import": "./src/tui.tsx"
+    }
+  },
+  "oc-plugin": [
+    "tui"
+  ],
+  "files": [
+    "src/tui.tsx",
+    "src/tui-preferences.ts",
+    "src/tui-prefs-io.ts",
+    "src/badge-contrast.ts",
+    "src/assistant-progress.ts",
+    "src/collector.ts",
+    "src/collector-state.ts",
+    "src/config.ts",
+    "src/event-bus.ts",
+    "src/event-handlers.ts",
+    "src/logger.ts",
+    "src/metrics.ts",
+    "src/live-speed.ts",
+    "src/turn-state.ts",
+    "src/request-state.ts",
+    "src/request-updates.ts",
+    "src/session-hydration.ts",
+    "src/session-timing.ts",
+    "src/session-tree.ts",
+    "src/types.ts",
+    "src/event-shapes.ts",
+    "src/components/SidebarMetrics.tsx",
+    "src/components/StatRow.tsx",
+    "src/scripts/init-tui-preferences.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "init:prefs": "OPENCODE_TUI_PREFERENCES_FILE=${OPENCODE_TUI_PREFERENCES_FILE:-$HOME/.config/opencode/tui-preferences.jsonc} bun run src/scripts/init-tui-preferences.ts",
+    "prepublishOnly": "npm pack --dry-run"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.18.4",
+    "@opencode-ai/sdk": "1.18.4",
+    "@types/bun": "latest",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "@opentui/core": "0.4.5",
+    "@opentui/solid": "0.4.5",
+    "comment-json": "^5.0.0",
+    "solid-js": "^1.9.12"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*",
+    "@opencode-ai/sdk": "*"
+  }
+}

package/src/assistant-progress.ts

@@ -0,0 +1,99 @@
+import { estimateTokens } from "./metrics"
+import { parseAssistantTextDelta } from "./event-shapes"
+import { currentRequest } from "./request-state"
+import { eventAggregateID, eventID, eventProperties, stringEventProperty } from "./event-bus"
+import type { EventHandlerContext } from "./collector-state"
+import { recordLiveTokens } from "./live-speed"
+
+export interface AssistantProgressPart {
+  readonly partID: string
+  readonly messageID: string
+  readonly text: string
+}
+
+function partEstimateKey(sessionID: string, messageID: string, partID: string): string {
+  return `${sessionID}:${messageID}:${partID}`
+}
+
+function applyTokenDelta(
+  ctx: EventHandlerContext,
+  sessionID: string,
+  messageID: string,
+  deltaTokens: number,
+  now: number,
+): void {
+  const { actions, state } = ctx
+  if (state.turns.get(sessionID)?.finalizedSteps.has(messageID)) return
+  const current = currentRequest({ state, actions, sessionID, messageID, now })
+  if (current.firstTokenTime === null) current.firstTokenTime = now
+  if (deltaTokens > 0) {
+    current.estimatedOutputTokens += deltaTokens
+    current.lastDeltaTime = now
+    recordLiveTokens(state.liveSpeeds, sessionID, messageID, deltaTokens, now)
+  }
+  current.isStreaming = true
+  actions.notify()
+}
+
+function applyAssistantText(
+  ctx: EventHandlerContext,
+  sessionID: string,
+  messageID: string,
+  partID: string,
+  text: string,
+  now: number,
+): void {
+  const { actions, config, state } = ctx
+  const key = partEstimateKey(sessionID, messageID, partID)
+  const nextTokens = estimateTokens(text, config.estimationRatio)
+  const previousTokens = state.partTokenEstimates.get(key) ?? 0
+  const deltaTokens = Math.max(0, nextTokens - previousTokens)
+  state.partTokenEstimates.set(key, Math.max(previousTokens, nextTokens))
+  applyTokenDelta(ctx, sessionID, messageID, deltaTokens, now)
+}
+
+export function applyAssistantProgress(
+  ctx: EventHandlerContext,
+  sessionID: string,
+  part: AssistantProgressPart,
+  now: number,
+): void {
+  applyAssistantText(ctx, sessionID, part.messageID, part.partID, part.text, now)
+}
+
+export function applyAssistantDelta(ctx: EventHandlerContext, event: unknown): void {
+  const { actions, state } = ctx
+  const sessionID = stringEventProperty(event, "sessionID")
+  const fallbackMessageID = sessionID.length > 0 ? state.assistantMessageIds.get(sessionID) ?? eventID(event) : eventID(event)
+  const text = parseAssistantTextDelta(eventProperties(event), fallbackMessageID)
+  if (!text) return
+  const aggregateID = eventAggregateID(event)
+  if (aggregateID.length > 0 && aggregateID !== text.sessionID) {
+    const aggregateAliases = state.sessionAliases.get(aggregateID) ?? new Set<string>()
+    aggregateAliases.add(text.sessionID)
+    state.sessionAliases.set(aggregateID, aggregateAliases)
+    const sessionAliases = state.sessionAliases.get(text.sessionID) ?? new Set<string>()
+    sessionAliases.add(aggregateID)
+    state.sessionAliases.set(text.sessionID, sessionAliases)
+  }
+  const now = performance.now()
+  actions.startSessionTiming(text.sessionID, now)
+  const key = partEstimateKey(text.sessionID, text.messageID, text.partID)
+  const deltaTokens = estimateTokens(text.delta, ctx.config.estimationRatio)
+  state.partTokenEstimates.set(key, (state.partTokenEstimates.get(key) ?? 0) + deltaTokens)
+  applyTokenDelta(ctx, text.sessionID, text.messageID, deltaTokens, now)
+}
+
+export function applyAssistantPartDelta(
+  ctx: EventHandlerContext,
+  sessionID: string,
+  messageID: string,
+  partID: string,
+  delta: string,
+  now: number,
+): void {
+  const key = partEstimateKey(sessionID, messageID, partID)
+  const deltaTokens = estimateTokens(delta, ctx.config.estimationRatio)
+  ctx.state.partTokenEstimates.set(key, (ctx.state.partTokenEstimates.get(key) ?? 0) + deltaTokens)
+  applyTokenDelta(ctx, sessionID, messageID, deltaTokens, now)
+}

package/src/badge-contrast.ts

@@ -0,0 +1,62 @@
+/**
+ * Pick the text color for the sidebar header badge (a bold label drawn on a
+ * `theme.accent` background).
+ *
+ * Primary rule: paint the theme's own `background` color as the label, giving
+ * the inverse-of-panel look consistent with other sidebar plugins.
+ *
+ * Fallback rule: `theme.background` can be unusable as a label color when:
+ *   1. Transparent background (alpha < 0.5). Drawing transparent text on the
+ *      accent renders the label invisible.
+ *   2. Background ~= accent (per-channel distance < 0.06). No contrast.
+ * In either case we fall back to a black/white pick by accent luminance.
+ *
+ * Accepts the minimal `{ r, g, b, a? }` shape so this stays a pure, trivially
+ * testable function independent of the native color class.
+ */
+
+export type Color = { r: number; g: number; b: number; a?: number }
+
+const MIN_OPAQUE_ALPHA = 0.5
+const MIN_CHANNEL_DISTANCE = 0.06
+const LIGHT_ACCENT_LUMINANCE = 0.5
+
+function srgbChannelToLinear(c: number): number {
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
+}
+
+function relativeLuminance(bg: Color): number {
+    return (
+        0.2126 * srgbChannelToLinear(bg.r) +
+        0.7152 * srgbChannelToLinear(bg.g) +
+        0.0722 * srgbChannelToLinear(bg.b)
+    )
+}
+
+function nearlyEqual(a: Color, b: Color): boolean {
+    return (
+        Math.abs(a.r - b.r) < MIN_CHANNEL_DISTANCE &&
+        Math.abs(a.g - b.g) < MIN_CHANNEL_DISTANCE &&
+        Math.abs(a.b - b.b) < MIN_CHANNEL_DISTANCE
+    )
+}
+
+/**
+ * Pure black/white pick by accent luminance. Used as the badge fallback.
+ */
+export function readableTextColorOn(bg: Color): string {
+    return relativeLuminance(bg) < LIGHT_ACCENT_LUMINANCE ? "#ffffff" : "#000000"
+}
+
+/**
+ * Badge label color on the accent: the theme background when it is usable,
+ * else a guaranteed-visible black/white fallback. Returns the passed-in
+ * `background` reference unchanged on the primary path.
+ */
+export function badgeTextColor<T extends Color>(accent: T, background: T): T | string {
+    const alpha = background.a ?? 1
+    if (alpha >= MIN_OPAQUE_ALPHA && !nearlyEqual(accent, background)) {
+        return background
+    }
+    return readableTextColorOn(accent)
+}

package/src/collector-state.ts

@@ -0,0 +1,36 @@
+import type { BarConfig, LiveSpeedState, RequestMetrics, TurnMetrics } from "./types"
+import type { SessionTree } from "./session-tree"
+import type { MetricsEventApi } from "./event-bus"
+import type { SessionTiming } from "./session-timing"
+
+export interface CollectorState {
+  requests: Map<string, RequestMetrics>
+  turns: Map<string, TurnMetrics>
+  liveSpeeds: Map<string, LiveSpeedState>
+  holdTimers: Map<string, ReturnType<typeof setTimeout>>
+  sessionTree: SessionTree
+  sessionModels: Map<string, { readonly modelID: string; readonly providerID: string }>
+  sessionTimings: Map<string, SessionTiming>
+  userMessageIds: Map<string, Set<string>>
+  assistantMessageIds: Map<string, string>
+  partTokenEstimates: Map<string, number>
+  sessionAliases: Map<string, Set<string>>
+  seenEventKeys: Set<string>
+  seenEventOrder: string[]
+  lastRequestSessionID: string | null
+}
+
+export interface CollectorActions {
+  notify: () => void
+  startSessionTiming: (sessionID: string, now: number) => void
+  stopSessionTiming: (sessionID: string, now: number) => void
+  clearHoldTimer: (sessionID: string) => void
+}
+
+export interface EventHandlerContext {
+  readonly api: MetricsEventApi
+  readonly config: BarConfig
+  readonly log: (msg: string) => void
+  readonly state: CollectorState
+  readonly actions: CollectorActions
+}