oc-metricboard 0.1.4

package/src/session-hydration.ts

@@ -0,0 +1,278 @@
+import { createFreshMetrics } from "./metrics"
+import { parseAssistantMessage, parseUserMessage } from "./event-shapes"
+import { applyAssistantTokens, hasPositiveAssistantTokens } from "./request-updates"
+import type { RequestMetrics, TurnMetrics } from "./types"
+import type { SessionTiming } from "./session-timing"
+import { completeTurn, createTurnMetrics, retireRequestIntoTurn } from "./turn-state"
+
+export interface HydrationApi {
+  readonly client: {
+    readonly session: {
+      messages(options: { readonly id: string }): Promise<unknown>
+      status(options: { readonly id: string }): Promise<unknown>
+    }
+    readonly message?: {
+      readonly parts?(options: { readonly id: string }): Promise<unknown>
+    }
+  }
+}
+
+export interface HydrationState {
+  readonly requests: Map<string, RequestMetrics>
+  readonly turns: Map<string, TurnMetrics>
+  readonly sessionModels: Map<string, { readonly modelID: string; readonly providerID: string }>
+  readonly sessionTimings: Map<string, SessionTiming>
+  lastRequestSessionID: string | null
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function timestampOrNull(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null
+}
+
+export function isHydrationApi(value: unknown): value is HydrationApi {
+  if (!isRecord(value)) return false
+  const client = value.client
+  if (!isRecord(client)) return false
+  const session = client.session
+  return isRecord(session) && typeof session.messages === "function" && typeof session.status === "function"
+}
+
+// SDK responses (hey-api with throwOnError=false) resolve to a fields-style
+// result `{ data, error, response }`; some callers may hand us the bare array
+// or object instead. Strip a single `{ data: ... }` wrapper when present.
+function unwrapData(value: unknown): unknown {
+  if (isRecord(value) && "data" in value) return value.data
+  return value
+}
+
+function unwrapMessageList(response: unknown): readonly unknown[] {
+  const value = unwrapData(response)
+  return Array.isArray(value) ? value : []
+}
+
+// session.status() may resolve to a single status object or to a map keyed by
+// sessionID; prefer the entry for the requested session when present.
+function unwrapSessionStatus(response: unknown, sessionID: string): unknown {
+  const value = unwrapData(response)
+  if (isRecord(value)) {
+    const bySessionID = value[sessionID]
+    if (typeof bySessionID === "string" || isRecord(bySessionID)) return bySessionID
+  }
+  return value
+}
+
+function statusKind(value: unknown): string {
+  if (typeof value === "string") return value
+  if (!isRecord(value)) return ""
+  return typeof value.type === "string" ? value.type : ""
+}
+
+function messageInfo(value: unknown): unknown {
+  if (!isRecord(value)) return value
+  return isRecord(value.info) ? value.info : value
+}
+
+function toPerformanceTime(wallTime: number | null, now: number): number | null {
+  if (wallTime === null) return null
+  return now - Math.max(0, Date.now() - wallTime)
+}
+
+async function observablePartTimes(api: HydrationApi, messageID: string, now: number): Promise<{
+  readonly first: number | null
+  readonly last: number | null
+}> {
+  const parts = api.client.message?.parts
+  if (typeof parts !== "function") return { first: null, last: null }
+  let values: readonly unknown[]
+  try {
+    values = unwrapMessageList(await parts({ id: messageID }))
+  } catch {
+    // Part timing is best-effort; unavailable/failed lookups yield null times.
+    return { first: null, last: null }
+  }
+  let firstWall: number | null = null
+  let lastWall: number | null = null
+  for (const value of values) {
+    if (!isRecord(value) || (value.type !== "text" && value.type !== "reasoning")) continue
+    const time = isRecord(value.time) ? value.time : null
+    const start = timestampOrNull(time?.start)
+    const end = timestampOrNull(time?.end)
+    if (start !== null) firstWall = firstWall === null ? start : Math.min(firstWall, start)
+    if (end !== null) lastWall = lastWall === null ? end : Math.max(lastWall, end)
+  }
+  return { first: toPerformanceTime(firstWall, now), last: toPerformanceTime(lastWall, now) }
+}
+
+function hydrateSessionTiming(
+  rawMessages: readonly unknown[],
+  status: string,
+  now: number,
+): SessionTiming {
+  const intervals: Array<{ start: number; end: number }> = []
+  const hasUserBoundary = rawMessages.some((raw) => parseUserMessage(messageInfo(raw)) !== null)
+  if (!hasUserBoundary) {
+    for (const raw of rawMessages) {
+      const assistant = parseAssistantMessage(messageInfo(raw))
+      const start = toPerformanceTime(assistant?.createdTime ?? null, now)
+      const end = toPerformanceTime(assistant?.completedTime ?? null, now)
+      if (start !== null && end !== null && end >= start) intervals.push({ start, end })
+    }
+    const elapsedMs = Math.round(intervals.reduce((total, interval) => total + Math.max(0, interval.end - interval.start), 0))
+    return { elapsedMs, activeSince: null, intervals }
+  }
+  let groupStartWall: number | null = null
+  let groupEndWall: number | null = null
+
+  function closeGroup(): void {
+    const start = toPerformanceTime(groupStartWall, now)
+    const end = toPerformanceTime(groupEndWall, now)
+    if (start !== null && end !== null && end >= start) intervals.push({ start, end })
+  }
+
+  for (const raw of rawMessages) {
+    const info = messageInfo(raw)
+    const user = parseUserMessage(info)
+    if (user) {
+      if (groupStartWall !== null) closeGroup()
+      groupStartWall = user.createdTime
+      groupEndWall = null
+      continue
+    }
+    const assistant = parseAssistantMessage(info)
+    if (!assistant) continue
+    groupStartWall ??= assistant.createdTime
+    if (assistant.completedTime !== null) {
+      groupEndWall = groupEndWall === null
+        ? assistant.completedTime
+        : Math.max(groupEndWall, assistant.completedTime)
+    }
+  }
+
+  const activeSince = status === "idle" ? null : toPerformanceTime(groupStartWall, now)
+  if (activeSince === null && groupStartWall !== null) closeGroup()
+  const elapsedMs = Math.round(intervals.reduce((total, interval) => total + Math.max(0, interval.end - interval.start), 0))
+  return { elapsedMs, activeSince, intervals }
+}
+
+export interface HydrateSessionInput {
+  readonly api: HydrationApi
+  readonly state: HydrationState
+  readonly sessionID: string
+  readonly now: number
+}
+
+export async function hydrateSession(input: HydrateSessionInput): Promise<boolean> {
+  const rawMessages = unwrapMessageList(await input.api.client.session.messages({ id: input.sessionID }))
+  const infos = rawMessages.map(messageInfo)
+  const assistants = infos
+    .map(parseAssistantMessage)
+    .filter((message): message is NonNullable<typeof message> => message !== null && hasPositiveAssistantTokens(message.tokens))
+  const assistant = assistants.at(-1)
+  if (!assistant || !hasPositiveAssistantTokens(assistant.tokens)) return false
+
+  let lastUserIndex = -1
+  for (let index = infos.length - 1; index >= 0; index -= 1) {
+    if (parseUserMessage(infos[index])) {
+      lastUserIndex = index
+      break
+    }
+  }
+  const trailingAssistants = infos
+    .slice(lastUserIndex + 1)
+    .map(parseAssistantMessage)
+    .filter((message): message is NonNullable<typeof message> => message !== null && hasPositiveAssistantTokens(message.tokens))
+  const lastUser = lastUserIndex >= 0 ? parseUserMessage(infos[lastUserIndex]) : null
+
+  const existing = input.state.requests.get(input.sessionID)
+  if (existing && !existing.isComplete && existing.messageID !== assistant.messageID) return false
+  // TTFT anchor: the preceding user message's created time is the true
+  // "request submitted" instant. In opencode 1.18.x, assistant.createdTime and
+  // part.time.start are stamped in the same tick as the first text-start event,
+  // so using assistant.createdTime here yields TTFT ≈ 0.
+  const requestStartTime = toPerformanceTime(lastUser?.createdTime ?? assistant.createdTime, input.now) ?? input.now
+  const completedTime = toPerformanceTime(assistant.completedTime, input.now)
+  const sessionStatus = statusKind(unwrapSessionStatus(
+    await input.api.client.session.status({ id: input.sessionID }),
+    input.sessionID,
+  ))
+  const shouldReuseExisting = existing?.messageID === assistant.messageID
+
+  const current = shouldReuseExisting ? existing : createFreshMetrics(
+    input.sessionID,
+    assistant.messageID,
+    assistant.modelID,
+    assistant.providerID,
+    requestStartTime,
+  )
+  if (!shouldReuseExisting || !current.isComplete) {
+    current.requestStartTime = requestStartTime
+  }
+  current.messageID = assistant.messageID
+  current.modelID = assistant.modelID
+  current.providerID = assistant.providerID
+  const partTimes = await observablePartTimes(input.api, assistant.messageID, input.now)
+  current.firstTokenTime = current.firstTokenTime ?? partTimes.first
+  current.lastDeltaTime = current.lastDeltaTime ?? partTimes.last ?? completedTime ?? input.now
+  current.isStreaming = !assistant.completed && sessionStatus !== "idle"
+  current.isComplete = assistant.completed || !current.isStreaming
+  if (current.isComplete && current.completeTime === null) {
+    current.completeTime = completedTime ?? input.now
+  }
+  if (!current.isComplete) {
+    current.completeTime = null
+    current.lastDeltaTime = input.now
+  }
+  applyAssistantTokens(current, assistant.tokens)
+
+  const turnStartTime = toPerformanceTime(
+    lastUser?.createdTime ?? trailingAssistants[0]?.createdTime ?? assistant.createdTime,
+    input.now,
+  ) ?? requestStartTime
+  const turn = createTurnMetrics(input.sessionID, turnStartTime)
+  for (const step of trailingAssistants) {
+    if (!step.tokens || !hasPositiveAssistantTokens(step.tokens)) continue
+    const stepStart = toPerformanceTime(step.createdTime, input.now) ?? turnStartTime
+    const stepMetrics = createFreshMetrics(
+      input.sessionID,
+      step.messageID,
+      step.modelID,
+      step.providerID,
+      stepStart,
+    )
+    applyAssistantTokens(stepMetrics, step.tokens)
+    retireRequestIntoTurn(turn, stepMetrics)
+  }
+  if (sessionStatus === "idle") completeTurn(turn, completedTime ?? input.now)
+  input.state.turns.set(input.sessionID, turn)
+
+  // Write-point race guard: the checks above ran before several awaits. By
+  // now a live event handler (e.g. session.next.step.started -> currentRequest)
+  // may have replaced the requests entry with a newer in-flight request.
+  // Overwriting it with this (stale) snapshot would orphan the live request
+  // and misroute subsequent deltas. Re-check immediately before writing.
+  const liveEntry = input.state.requests.get(input.sessionID)
+  if (
+    liveEntry !== undefined &&
+    liveEntry !== current &&
+    !liveEntry.isComplete &&
+    liveEntry.messageID !== current.messageID
+  ) {
+    return false
+  }
+  input.state.requests.set(input.sessionID, current)
+  input.state.lastRequestSessionID = input.sessionID
+  if (assistant.modelID || assistant.providerID) {
+    input.state.sessionModels.set(input.sessionID, { modelID: assistant.modelID, providerID: assistant.providerID })
+  }
+  if (!input.state.sessionTimings.has(input.sessionID)) {
+    input.state.sessionTimings.set(
+      input.sessionID,
+      hydrateSessionTiming(rawMessages, sessionStatus, input.now),
+    )
+  }
+  return true
+}

package/src/session-timing.ts

@@ -0,0 +1,78 @@
+export interface SessionTiming {
+  elapsedMs: number
+  activeSince: number | null
+  intervals?: Array<{ start: number; end: number }>
+}
+
+export function startSessionTiming(
+  timings: Map<string, SessionTiming>,
+  sessionID: string,
+  now: number,
+): void {
+  const timing = timings.get(sessionID)
+  if (!timing) {
+    timings.set(sessionID, { elapsedMs: 0, activeSince: now, intervals: [] })
+    return
+  }
+  if (timing.activeSince === null) timing.activeSince = now
+}
+
+export function stopSessionTiming(
+  timings: Map<string, SessionTiming>,
+  sessionID: string,
+  now: number,
+): void {
+  const timing = timings.get(sessionID)
+  if (!timing || timing.activeSince === null) return
+  timing.elapsedMs += Math.max(0, now - timing.activeSince)
+  timing.intervals ??= []
+  timing.intervals.push({ start: timing.activeSince, end: now })
+  timing.activeSince = null
+}
+
+export function getScopeElapsedMs(
+  timings: Map<string, SessionTiming>,
+  sessionIDs: readonly string[],
+  now: number,
+): number {
+  const intervals: Array<{ start: number; end: number }> = []
+  let unpositionedElapsedMs = 0
+
+  for (const sessionID of sessionIDs) {
+    const timing = timings.get(sessionID)
+    if (!timing) continue
+    const positionedMs = (timing.intervals ?? []).reduce(
+      (total, interval) => total + Math.max(0, interval.end - interval.start),
+      0,
+    )
+    for (const interval of timing.intervals ?? []) intervals.push(interval)
+    if (timing.activeSince !== null) intervals.push({ start: timing.activeSince, end: now })
+    unpositionedElapsedMs += Math.max(0, timing.elapsedMs - positionedMs)
+  }
+
+  intervals.sort((left, right) => left.start - right.start || left.end - right.end)
+  let unionMs = 0
+  let start: number | null = null
+  let end: number | null = null
+  for (const interval of intervals) {
+    if (start === null || end === null) {
+      start = interval.start
+      end = interval.end
+      continue
+    }
+    if (interval.start <= end) {
+      end = Math.max(end, interval.end)
+      continue
+    }
+    unionMs += Math.max(0, end - start)
+    start = interval.start
+    end = interval.end
+  }
+  if (start !== null && end !== null) unionMs += Math.max(0, end - start)
+  return unionMs + unpositionedElapsedMs
+}
+
+export function getSessionElapsedMs(timing: SessionTiming | undefined, now: number): number {
+  if (!timing) return 0
+  return timing.elapsedMs + (timing.activeSince === null ? 0 : Math.max(0, now - timing.activeSince))
+}

package/src/session-tree.ts

@@ -0,0 +1,43 @@
+import type { MetricsScope } from "./types"
+
+export interface SessionTree {
+  setParent(sessionID: string, parentID: string | null): void
+  deleteSession(sessionID: string): void
+  clear(): void
+  getScopeSessionIDs(sessionID: string, scope: MetricsScope): readonly string[]
+  getChildSessionCount(sessionID: string): number
+}
+
+export function createSessionTree(): SessionTree {
+  const parentBySession = new Map<string, string | null>()
+
+  function collectDescendants(sessionID: string, seen: Set<string>): string[] {
+    const descendants: string[] = []
+    for (const [candidateID, parentID] of parentBySession) {
+      if (parentID !== sessionID || seen.has(candidateID)) continue
+      seen.add(candidateID)
+      descendants.push(candidateID, ...collectDescendants(candidateID, seen))
+    }
+    return descendants
+  }
+
+  return {
+    setParent(sessionID: string, parentID: string | null): void {
+      parentBySession.set(sessionID, parentID)
+    },
+    deleteSession(sessionID: string): void {
+      parentBySession.delete(sessionID)
+    },
+    clear(): void {
+      parentBySession.clear()
+    },
+    getScopeSessionIDs(sessionID: string, scope: MetricsScope): readonly string[] {
+      if (scope === "current") return [sessionID]
+      const seen = new Set<string>([sessionID])
+      return [sessionID, ...collectDescendants(sessionID, seen)]
+    },
+    getChildSessionCount(sessionID: string): number {
+      return collectDescendants(sessionID, new Set<string>([sessionID])).length
+    },
+  }
+}

package/src/tui-preferences.ts

@@ -0,0 +1,203 @@
+import { createSignal } from "solid-js"
+import type { MetricsScope } from "./types"
+import {
+    isRecord,
+    readTuiPreferencesFile,
+    queueTuiPreferenceUpdate,
+    watchTuiPreferences,
+} from "./tui-prefs-io"
+
+// Plugin-specific types, defaults, validation, resolution, order computation,
+// and controller. Generic preferences file I/O lives in tui-prefs-io.ts.
+
+export const PLUGIN_KEY = "oc-metricboard"
+export const DEFAULT_SLOT_ORDER = 160
+
+export interface MetricsTuiPrefs {
+    forceToTop: boolean
+    order: number
+    scope: MetricsScope
+    section: {
+        enabled: boolean
+        collapsed: boolean | null
+        rememberCollapsed: boolean
+        label: string
+    }
+    rows: {
+        speed: boolean
+        ttft: boolean
+        input: boolean
+        output: boolean
+        cache: boolean
+        elapsed: boolean
+        session: boolean
+        model: boolean
+        modelBreakdown: boolean
+    }
+}
+
+export const DEFAULT_PREFS: MetricsTuiPrefs = {
+    forceToTop: false,
+    order: DEFAULT_SLOT_ORDER,
+    scope: "current",
+    section: {
+        enabled: true,
+        collapsed: null,
+        rememberCollapsed: true,
+        label: "MetricBoard",
+    },
+    rows: {
+        speed: true,
+        ttft: true,
+        input: true,
+        output: true,
+        cache: true,
+        elapsed: true,
+        session: true,
+        model: true,
+        modelBreakdown: true,
+    },
+}
+
+function bool(value: unknown, fallback: boolean): boolean {
+    return typeof value === "boolean" ? value : fallback
+}
+
+function int(value: unknown, fallback: number, min: number, max: number): number {
+    if (typeof value !== "number" || !Number.isFinite(value)) return fallback
+    return Math.min(Math.max(Math.round(value), min), max)
+}
+
+function label(value: unknown, fallback: string, maxLength: number): string {
+    if (typeof value !== "string" || value.length === 0) return fallback
+    return value.slice(0, maxLength)
+}
+
+function metricsScope(value: unknown, fallback: MetricsScope): MetricsScope {
+    return value === "current" || value === "tree" ? value : fallback
+}
+
+// Per-key validation: every value is independently clamped/defaulted so one
+// bad entry never poisons the rest. Never throws. A missing/non-object
+// opencode-metrics key → full defaults clone.
+export function resolveMetricsPrefs(root: Record<string, unknown>): MetricsTuiPrefs {
+    const entry = root[PLUGIN_KEY]
+    if (!isRecord(entry)) return structuredClone(DEFAULT_PREFS)
+
+    const d = DEFAULT_PREFS
+    const section = isRecord(entry.section) ? entry.section : {}
+    const rows = isRecord(entry.rows) ? entry.rows : {}
+
+    return {
+        forceToTop: bool(entry.forceToTop, d.forceToTop),
+        order: int(entry.order, d.order, -10000, 10000),
+        scope: metricsScope(entry.scope, d.scope),
+        section: {
+            enabled: bool(section.enabled, d.section.enabled),
+            collapsed: typeof section.collapsed === "boolean" ? section.collapsed : null,
+            rememberCollapsed: bool(section.rememberCollapsed, d.section.rememberCollapsed),
+            label: label(section.label, d.section.label, 24),
+        },
+        rows: {
+            speed: bool(rows.speed, d.rows.speed),
+            ttft: bool(rows.ttft, d.rows.ttft),
+            input: bool(rows.input, d.rows.input),
+            output: bool(rows.output, d.rows.output),
+            cache: bool(rows.cache, d.rows.cache),
+            elapsed: bool(rows.elapsed, d.rows.elapsed),
+            session: bool(rows.session, d.rows.session),
+            model: bool(rows.model, d.rows.model),
+            modelBreakdown: bool(rows.modelBreakdown, d.rows.modelBreakdown),
+        },
+    }
+}
+
+const FORCE_TOP_BASE = -100000
+
+// Shared forceToTop convention — MUST stay byte-identical across plugins or
+// they sort inconsistently against each other. Forced plugins sort below
+// FORCE_TOP_BASE, ordered among themselves by their top-level key's position
+// in the file. The user-facing `order` knob clamps to -10000..10000, strictly
+// above the forced band.
+export function computeEffectiveOrder(
+    root: Record<string, unknown>,
+    pluginKey: string,
+    defaultOrder: number,
+): number {
+    const entry = root[pluginKey]
+    if (!isRecord(entry)) return defaultOrder
+    if (entry.forceToTop === true) {
+        return FORCE_TOP_BASE + Object.keys(root).indexOf(pluginKey)
+    }
+    return int(entry.order, defaultOrder, -10000, 10000)
+}
+
+// ── Controller ──
+
+export interface MetricsSidebarController {
+    prefs: () => MetricsTuiPrefs
+    collapsed: () => boolean
+    toggleCollapsed: () => void
+    subscribe: (cb: () => void) => () => void
+}
+
+export function createMetricsSidebarController(
+    initialPrefs: MetricsTuiPrefs,
+    requestRender?: () => void,
+): MetricsSidebarController {
+    const [prefs, setPrefs] = createSignal<MetricsTuiPrefs>(initialPrefs)
+    const seedCollapsed =
+        initialPrefs.section.rememberCollapsed && initialPrefs.section.collapsed != null
+            ? initialPrefs.section.collapsed
+            : false
+    const [collapsed, setCollapsed] = createSignal(seedCollapsed)
+    let lastPersistedCollapsed: boolean | null = initialPrefs.section.collapsed
+    let lastApplied = JSON.stringify(initialPrefs)
+
+    const listeners = new Set<() => void>()
+    const notify = (): void => {
+        requestRender?.()
+        for (const cb of listeners) cb()
+    }
+
+    const disposeWatcher = watchTuiPreferences(() => {
+        void (async () => {
+            const next = resolveMetricsPrefs(await readTuiPreferencesFile())
+            const serialized = JSON.stringify(next)
+            if (serialized === lastApplied) return
+            lastApplied = serialized
+            setPrefs(next)
+            if (
+                next.section.rememberCollapsed &&
+                next.section.collapsed != null &&
+                next.section.collapsed !== lastPersistedCollapsed
+            ) {
+                lastPersistedCollapsed = next.section.collapsed
+                setCollapsed(next.section.collapsed)
+            }
+            notify()
+        })()
+    })
+
+    // Intentionally not calling disposeWatcher here — the watcher lives for
+    // the plugin/process lifetime, matching Magic Context's convention.
+    void disposeWatcher
+
+    function toggleCollapsed() {
+        const next = !collapsed()
+        setCollapsed(next)
+        notify()
+        if (prefs().section.rememberCollapsed) {
+            void queueTuiPreferenceUpdate(PLUGIN_KEY, ["section", "collapsed"], next).then(() => {
+                lastPersistedCollapsed = next
+            })
+        }
+    }
+
+    function subscribe(cb: () => void): () => void {
+        listeners.add(cb)
+        return () => listeners.delete(cb)
+    }
+
+    return { prefs, collapsed, toggleCollapsed, subscribe }
+}