oc-metricboard 0.1.4

package/src/event-handlers.ts

@@ -0,0 +1,345 @@
+import { applyAssistantDelta, applyAssistantPartDelta, applyAssistantProgress } from "./assistant-progress"
+import { createFreshMetrics, estimateTokens } from "./metrics"
+import {
+  parseAssistantMessage,
+  parseAssistantProgressPart,
+  parseAssistantStepEnded,
+  parseAssistantStepStarted,
+  parseSessionInfo,
+  parseTextPart,
+  parseUserMessage,
+} from "./event-shapes"
+import { applyAssistantTokens, applySessionModel, hasPositiveAssistantTokens, mergeAssistantModel } from "./request-updates"
+import { completeRequest, currentRequest } from "./request-state"
+import { eventAggregateID, eventID, eventProperties, eventProperty, statusType, stringEventProperty } from "./event-bus"
+import type { EventHandlerContext } from "./collector-state"
+import { clearLiveSpeed, resetLiveSpeed } from "./live-speed"
+import { ensureTurn, retireRequestIntoTurn, startTurn } from "./turn-state"
+
+export function registerEventHandlers(ctx: EventHandlerContext): Array<() => void> {
+  const { api, config, log, state, actions } = ctx
+  const disposers: Array<() => void> = []
+
+  function recordSession(value: unknown, defaultParentWhenMissing: boolean): void {
+    const info = parseSessionInfo(value)
+    if (!info) return
+    if (info.hasParentID) {
+      state.sessionTree.setParent(info.id, info.parentID)
+    } else if (defaultParentWhenMissing) {
+      state.sessionTree.setParent(info.id, null)
+    }
+  }
+
+  function on(type: string, handler: (event: unknown) => void): void {
+    for (const eventType of [type, `${type}.1`, `${type}.2`]) {
+      disposers.push(api.event.on(eventType, (event) => {
+        const id = eventID(event)
+        const properties = eventProperties(event)
+        let serialized = ""
+        try {
+          serialized = JSON.stringify(properties)
+        } catch {
+          serialized = ""
+        }
+        const key = id && eventAggregateID(event) ? `${type}:${id}:${serialized}` : ""
+        if (key && state.seenEventKeys.has(key)) return
+        if (key) {
+          state.seenEventKeys.add(key)
+          state.seenEventOrder.push(key)
+          if (state.seenEventOrder.length > 4096) {
+            const oldest = state.seenEventOrder.shift()
+            if (oldest) state.seenEventKeys.delete(oldest)
+          }
+        }
+        handler(event)
+      }))
+    }
+  }
+
+  function addAlias(left: string, right: string): void {
+    if (left.length === 0 || right.length === 0 || left === right) return
+    const leftAliases = state.sessionAliases.get(left) ?? new Set<string>()
+    leftAliases.add(right)
+    state.sessionAliases.set(left, leftAliases)
+    const rightAliases = state.sessionAliases.get(right) ?? new Set<string>()
+    rightAliases.add(left)
+    state.sessionAliases.set(right, rightAliases)
+  }
+
+  function recordEventAlias(event: unknown, sessionID: string): void {
+    addAlias(eventAggregateID(event), sessionID)
+  }
+
+  function clearPartEstimates(sessionID: string): void {
+    for (const key of state.partTokenEstimates.keys()) {
+      if (key.startsWith(`${sessionID}:`)) state.partTokenEstimates.delete(key)
+    }
+  }
+
+  // ── session.created ──
+  on("session.created", (event) => {
+    recordSession(eventProperty(event, "info"), true)
+    actions.notify()
+  })
+
+  // ── session.updated ──
+  on("session.updated", (event) => {
+    recordSession(eventProperty(event, "info"), false)
+    actions.notify()
+  })
+
+  // ── session.status ──
+  on("session.status", (event) => {
+    const sessionID = stringEventProperty(event, "sessionID")
+    if (sessionID.length === 0) return
+    recordEventAlias(event, sessionID)
+    const type = statusType(event)
+    log(`session.status: ${sessionID} -> ${type}`)
+
+    if (type === "busy") {
+      const now = performance.now()
+      actions.startSessionTiming(sessionID, now)
+      actions.clearHoldTimer(sessionID)
+      const existingTurn = state.turns.get(sessionID)
+      if (!existingTurn || existingTurn.isComplete) startTurn(state.turns, sessionID, now)
+      const existing = state.requests.get(sessionID)
+      if (existing && existing.isComplete) {
+        const prev = existing
+        state.requests.set(sessionID, createFreshMetrics(sessionID, "", prev.modelID, prev.providerID, now))
+        clearLiveSpeed(state.liveSpeeds, sessionID)
+        state.lastRequestSessionID = sessionID
+        log(`new turn after idle: session=${sessionID}`)
+        actions.notify()
+      } else if (!existing) {
+        state.requests.set(sessionID, createFreshMetrics(sessionID, "", "", "", now))
+        state.lastRequestSessionID = sessionID
+        actions.notify()
+      }
+    }
+
+    if (type === "idle") {
+      completeRequest({ state, actions, sessionID, now: performance.now(), holdDurationMs: config.holdDurationMs, log })
+    }
+  })
+
+  on("session.idle", (event) => {
+    const sessionID = stringEventProperty(event, "sessionID")
+    if (sessionID.length === 0) return
+    recordEventAlias(event, sessionID)
+    completeRequest({ state, actions, sessionID, now: performance.now(), holdDurationMs: config.holdDurationMs, log })
+  })
+
+  // ── message.part.delta ──
+  on("message.part.delta", (event) => {
+    const sessionID = stringEventProperty(event, "sessionID")
+    const messageID = stringEventProperty(event, "messageID")
+    const delta = stringEventProperty(event, "delta")
+    const field = stringEventProperty(event, "field")
+    const partID = stringEventProperty(event, "partID") || `${messageID}:stream`
+    if (sessionID.length === 0 || messageID.length === 0) return
+    recordEventAlias(event, sessionID)
+    if (field !== "text") return
+    actions.startSessionTiming(sessionID, performance.now())
+
+    const now = performance.now()
+    ensureTurn(state.turns, sessionID, now)
+    applyAssistantPartDelta(ctx, sessionID, messageID, partID, delta, now)
+  })
+
+  on("session.next.step.started", (event) => {
+    const step = parseAssistantStepStarted(eventProperties(event), eventID(event))
+    if (!step) return
+    recordEventAlias(event, step.sessionID)
+    const now = performance.now()
+    actions.startSessionTiming(step.sessionID, now)
+    const existingTurn = state.turns.get(step.sessionID)
+    if (!existingTurn || existingTurn.isComplete) startTurn(state.turns, step.sessionID, now)
+    state.assistantMessageIds.set(step.sessionID, step.messageID)
+    clearPartEstimates(step.sessionID)
+    if (step.modelID || step.providerID) {
+      state.sessionModels.set(step.sessionID, { modelID: step.modelID, providerID: step.providerID })
+    }
+    const current = currentRequest({ state, actions, sessionID: step.sessionID, messageID: step.messageID, now })
+    resetLiveSpeed(state.liveSpeeds, step.sessionID, step.messageID)
+    applySessionModel(current, state.sessionModels.get(step.sessionID))
+    actions.notify()
+  })
+
+  on("session.next.text.delta", (event) => applyAssistantDelta(ctx, event))
+
+  on("session.next.reasoning.delta", (event) => applyAssistantDelta(ctx, event))
+
+  on("session.next.step.ended", (event) => {
+    const sessionID = stringEventProperty(event, "sessionID")
+    const fallbackMessageID = sessionID ? state.assistantMessageIds.get(sessionID) ?? eventID(event) : eventID(event)
+    const step = parseAssistantStepEnded(eventProperties(event), fallbackMessageID)
+    if (!step) return
+    recordEventAlias(event, step.sessionID)
+    const now = performance.now()
+    actions.startSessionTiming(step.sessionID, now)
+    const turn = ensureTurn(state.turns, step.sessionID, now)
+    const existing = state.requests.get(step.sessionID)
+    const isCurrent = existing?.messageID === step.messageID
+    if (turn.finalizedSteps.get(step.messageID)?.exact) {
+      log(`duplicate finalized step ignored: session=${step.sessionID} message=${step.messageID}`)
+      return
+    }
+    const shouldStore = !existing
+      || existing.messageID.length === 0
+      || Boolean(state.userMessageIds.get(step.sessionID)?.has(existing.messageID))
+    const current = isCurrent
+      ? existing
+      : createFreshMetrics(step.sessionID, step.messageID, existing?.modelID ?? "", existing?.providerID ?? "", now)
+    if (shouldStore) {
+      state.requests.set(step.sessionID, current)
+      state.lastRequestSessionID = step.sessionID
+    }
+    if (applyAssistantTokens(current, step.tokens)) {
+      log(`exact: in=${step.tokens.input} out=${step.tokens.output} cr=${step.tokens.cacheRead} cw=${step.tokens.cacheWrite}`)
+    } else {
+      log("assistant tokens all zero, skipping overwrite")
+    }
+    current.lastDeltaTime = now
+    current.isStreaming = false
+    retireRequestIntoTurn(turn, current, isCurrent || shouldStore)
+    if (state.liveSpeeds.get(step.sessionID)?.messageID === step.messageID) {
+      clearLiveSpeed(state.liveSpeeds, step.sessionID)
+    }
+    actions.notify()
+  })
+
+  // ── message.part.updated ──
+  on("message.part.updated", (event) => {
+    const sessionID = stringEventProperty(event, "sessionID")
+    if (sessionID.length === 0) return
+    recordEventAlias(event, sessionID)
+    const rawPart = eventProperty(event, "part")
+    const part = parseTextPart(rawPart)
+    const now = performance.now()
+    const msgIds = state.userMessageIds.get(sessionID)
+    if (part && msgIds?.has(part.messageID)) {
+      const current = state.requests.get(sessionID)
+      if (current) {
+        if (!current.isComplete) actions.startSessionTiming(sessionID, now)
+        current.estimatedInputTokens = estimateTokens(part.text, config.estimationRatio)
+        log(`estimated input tokens: ${current.estimatedInputTokens} (textLen=${part.text.length})`)
+        actions.notify()
+      }
+      return
+    }
+
+    const assistantPart = parseAssistantProgressPart(rawPart)
+    if (assistantPart) {
+      applyAssistantProgress(ctx, sessionID, assistantPart, now)
+    }
+  })
+
+  // ── message.updated ──
+  on("message.updated", (event) => {
+    const sessionID = stringEventProperty(event, "sessionID")
+    if (sessionID.length === 0) return
+    recordEventAlias(event, sessionID)
+    const info = eventProperty(event, "info")
+
+    const assistant = parseAssistantMessage(info)
+    if (assistant) {
+      const nextModel = mergeAssistantModel(state.sessionModels.get(sessionID), assistant)
+      if (nextModel) state.sessionModels.set(sessionID, nextModel)
+
+      const now = performance.now()
+      const tokens = assistant.tokens
+      const existing = state.requests.get(sessionID)
+      const turn = ensureTurn(state.turns, sessionID, now)
+      const hasPositive = hasPositiveAssistantTokens(tokens)
+      const isCurrent = existing?.messageID === assistant.messageID
+      const shouldUseAssistantMessage = assistant.messageID.length > 0 && (hasPositive || isCurrent)
+      const current = shouldUseAssistantMessage
+        ? isCurrent
+          ? existing
+          : turn.finalizedSteps.has(assistant.messageID)
+            ? createFreshMetrics(sessionID, assistant.messageID, assistant.modelID, assistant.providerID, now)
+            : currentRequest({ state, actions, sessionID, messageID: assistant.messageID, now })
+        : existing
+      if (current) {
+        if (!current.isComplete) actions.startSessionTiming(sessionID, now)
+        if (tokens) {
+          if (applyAssistantTokens(current, tokens)) {
+            log(`exact: in=${tokens.input} out=${tokens.output} cr=${tokens.cacheRead} cw=${tokens.cacheWrite}`)
+            retireRequestIntoTurn(turn, current, isCurrent || state.requests.get(sessionID) === current)
+          } else {
+            log(`assistant tokens all zero, skipping overwrite`)
+          }
+        }
+        applySessionModel(current, state.sessionModels.get(sessionID))
+        if (assistant.completed && state.liveSpeeds.get(sessionID)?.messageID === assistant.messageID) {
+          clearLiveSpeed(state.liveSpeeds, sessionID)
+        }
+        actions.notify()
+      }
+    }
+
+    const user = parseUserMessage(info)
+    if (user) {
+      const userMsgID = user.messageID
+      const current = state.requests.get(sessionID)
+      if (current && current.messageID === userMsgID) {
+        return
+      }
+      if (userMsgID && state.userMessageIds.get(sessionID)?.has(userMsgID)) {
+        return
+      }
+      const now = performance.now()
+      const previous = state.requests.get(sessionID)
+      const previousTurn = state.turns.get(sessionID)
+      if (previous && previousTurn) retireRequestIntoTurn(previousTurn, previous)
+      startTurn(state.turns, sessionID, now)
+      clearLiveSpeed(state.liveSpeeds, sessionID)
+      clearPartEstimates(sessionID)
+      const fresh = createFreshMetrics(sessionID, userMsgID, "", "", now)
+      actions.startSessionTiming(sessionID, fresh.requestStartTime)
+      if (userMsgID) {
+        let msgIds = state.userMessageIds.get(sessionID)
+        if (!msgIds) {
+          msgIds = new Set()
+          state.userMessageIds.set(sessionID, msgIds)
+        }
+        msgIds.add(userMsgID)
+      }
+      log(`user msg: id=${userMsgID}`)
+      applySessionModel(fresh, state.sessionModels.get(sessionID))
+      state.requests.set(sessionID, fresh)
+      state.lastRequestSessionID = sessionID
+      actions.notify()
+    }
+  })
+
+  // ── session.deleted ──
+  on("session.deleted", (event) => {
+    const sessionID = stringEventProperty(event, "sessionID")
+    if (sessionID.length === 0) return
+    state.sessionTree.deleteSession(sessionID)
+    state.sessionModels.delete(sessionID)
+    state.sessionTimings.delete(sessionID)
+    state.turns.delete(sessionID)
+    state.liveSpeeds.delete(sessionID)
+    state.userMessageIds.delete(sessionID)
+    state.assistantMessageIds.delete(sessionID)
+    state.sessionAliases.delete(sessionID)
+    for (const aliases of state.sessionAliases.values()) {
+      aliases.delete(sessionID)
+    }
+    for (const key of state.partTokenEstimates.keys()) {
+      if (key.startsWith(`${sessionID}:`)) state.partTokenEstimates.delete(key)
+    }
+    actions.clearHoldTimer(sessionID)
+    if (state.requests.has(sessionID)) {
+      state.requests.delete(sessionID)
+      if (state.lastRequestSessionID === sessionID) {
+        state.lastRequestSessionID = [...state.requests.keys()].at(-1) ?? null
+      }
+      actions.notify()
+    }
+  })
+
+  return disposers
+}

package/src/event-shapes.ts

@@ -0,0 +1,198 @@
+export interface SessionInfoEvent {
+  readonly id: string
+  readonly parentID: string | null
+  readonly hasParentID: boolean
+}
+
+export interface TextPartEvent {
+  readonly partID: string
+  readonly messageID: string
+  readonly text: string
+}
+
+export interface AssistantTokenUpdate {
+  readonly hasAny: boolean
+  readonly hasCacheRead: boolean
+  readonly hasCacheWrite: boolean
+  readonly input: number
+  readonly output: number
+  readonly reasoning: number
+  readonly cacheRead: number
+  readonly cacheWrite: number
+}
+
+export interface AssistantMessageEvent {
+  readonly messageID: string
+  readonly modelID: string
+  readonly providerID: string
+  readonly tokens: AssistantTokenUpdate | null
+  readonly completed: boolean
+  readonly createdTime: number | null
+  readonly completedTime: number | null
+}
+
+export interface UserMessageEvent {
+  readonly messageID: string
+  readonly createdTime: number | null
+}
+
+export interface AssistantStepStartedEvent {
+  readonly sessionID: string
+  readonly messageID: string
+  readonly modelID: string
+  readonly providerID: string
+}
+
+export interface AssistantTextDeltaEvent {
+  readonly sessionID: string
+  readonly messageID: string
+  readonly partID: string
+  readonly delta: string
+}
+
+export interface AssistantStepEndedEvent {
+  readonly sessionID: string
+  readonly messageID: string
+  readonly tokens: AssistantTokenUpdate
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function hasOwn(record: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(record, key)
+}
+
+function stringOrEmpty(value: unknown): string {
+  return typeof value === "string" ? value : ""
+}
+
+function nonNegativeNumber(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? Math.max(0, value) : 0
+}
+
+function timestampOrNull(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null
+}
+
+export function parseSessionInfo(value: unknown): SessionInfoEvent | null {
+  if (!isRecord(value)) return null
+  const id = stringOrEmpty(value.id)
+  if (id.length === 0) return null
+  const hasParentID = hasOwn(value, "parentID")
+  return {
+    id,
+    parentID: typeof value.parentID === "string" ? value.parentID : null,
+    hasParentID,
+  }
+}
+
+export function parseTextPart(value: unknown): TextPartEvent | null {
+  if (!isRecord(value)) return null
+  if (value.type !== "text") return null
+  const partID = stringOrEmpty(value.id)
+  const messageID = stringOrEmpty(value.messageID)
+  const text = stringOrEmpty(value.text)
+  if (partID.length === 0 || messageID.length === 0 || text.length === 0) return null
+  return { partID, messageID, text }
+}
+
+export function parseAssistantProgressPart(value: unknown): TextPartEvent | null {
+  if (!isRecord(value)) return null
+  if (value.type !== "text" && value.type !== "reasoning") return null
+  const partID = stringOrEmpty(value.id)
+  const messageID = stringOrEmpty(value.messageID)
+  const text = stringOrEmpty(value.text)
+  if (partID.length === 0 || messageID.length === 0 || text.length === 0) return null
+  return { partID, messageID, text }
+}
+
+function parseAssistantTokens(value: unknown): AssistantTokenUpdate | null {
+  if (!isRecord(value)) return null
+  const cache = isRecord(value.cache) ? value.cache : null
+  const hasInput = hasOwn(value, "input")
+  const hasOutput = hasOwn(value, "output")
+  const hasReasoning = hasOwn(value, "reasoning")
+  const hasCacheRead = cache !== null && hasOwn(cache, "read")
+  const hasCacheWrite = cache !== null && hasOwn(cache, "write")
+
+  return {
+    hasAny: hasInput || hasOutput || hasReasoning || hasCacheRead || hasCacheWrite,
+    hasCacheRead,
+    hasCacheWrite,
+    input: nonNegativeNumber(value.input),
+    output: nonNegativeNumber(value.output),
+    reasoning: nonNegativeNumber(value.reasoning),
+    cacheRead: nonNegativeNumber(cache?.read),
+    cacheWrite: nonNegativeNumber(cache?.write),
+  }
+}
+
+export function parseAssistantMessage(value: unknown): AssistantMessageEvent | null {
+  if (!isRecord(value)) return null
+  const time = isRecord(value.time) ? value.time : null
+  const createdTime = timestampOrNull(time?.created)
+  const completedTime = timestampOrNull(time?.completed)
+  if (value.role === "assistant") {
+    return {
+      messageID: stringOrEmpty(value.id),
+      modelID: stringOrEmpty(value.modelID),
+      providerID: stringOrEmpty(value.providerID),
+      tokens: parseAssistantTokens(value.tokens),
+      completed: completedTime !== null,
+      createdTime,
+      completedTime,
+    }
+  }
+  if (value.type !== "assistant") return null
+  const model = isRecord(value.model) ? value.model : null
+  return {
+    messageID: stringOrEmpty(value.id),
+    modelID: stringOrEmpty(model?.id),
+    providerID: stringOrEmpty(model?.providerID),
+    tokens: parseAssistantTokens(value.tokens),
+    completed: completedTime !== null,
+    createdTime,
+    completedTime,
+  }
+}
+
+export function parseUserMessage(value: unknown): UserMessageEvent | null {
+  if (!isRecord(value) || value.role !== "user") return null
+  const time = isRecord(value.time) ? value.time : null
+  return { messageID: stringOrEmpty(value.id), createdTime: timestampOrNull(time?.created) }
+}
+
+export function parseAssistantStepStarted(value: unknown, fallbackMessageID = ""): AssistantStepStartedEvent | null {
+  if (!isRecord(value)) return null
+  const sessionID = stringOrEmpty(value.sessionID)
+  const messageID = stringOrEmpty(value.assistantMessageID) || fallbackMessageID
+  const model = isRecord(value.model) ? value.model : null
+  if (sessionID.length === 0 || messageID.length === 0) return null
+  return {
+    sessionID,
+    messageID,
+    modelID: stringOrEmpty(model?.id),
+    providerID: stringOrEmpty(model?.providerID),
+  }
+}
+
+export function parseAssistantTextDelta(value: unknown, fallbackMessageID = ""): AssistantTextDeltaEvent | null {
+  if (!isRecord(value)) return null
+  const sessionID = stringOrEmpty(value.sessionID)
+  const messageID = stringOrEmpty(value.assistantMessageID) || fallbackMessageID
+  const partID = stringOrEmpty(value.textID) || stringOrEmpty(value.reasoningID) || `${messageID}:stream`
+  const delta = stringOrEmpty(value.delta)
+  if (sessionID.length === 0 || messageID.length === 0 || partID.length === 0 || delta.length === 0) return null
+  return { sessionID, messageID, partID, delta }
+}
+
+export function parseAssistantStepEnded(value: unknown, fallbackMessageID = ""): AssistantStepEndedEvent | null {
+  if (!isRecord(value)) return null
+  const sessionID = stringOrEmpty(value.sessionID)
+  const messageID = stringOrEmpty(value.assistantMessageID) || fallbackMessageID
+  const tokens = parseAssistantTokens(value.tokens)
+  if (sessionID.length === 0 || messageID.length === 0 || tokens === null) return null
+  return { sessionID, messageID, tokens }
+}

package/src/live-speed.ts

@@ -0,0 +1,79 @@
+import type { LiveSpeedState } from "./types"
+
+export const LIVE_SPEED_WINDOW_MS = 3000
+export const LIVE_SPEED_STALE_MS = 2000
+export const LIVE_SPEED_MAX_SAMPLES = 256
+// Minimum interval between distinct samples. History replay during session
+// reopen delivers many deltas in a few milliseconds; merging those into one
+// sample prevents the rolling window from reporting absurd TPS values.
+export const LIVE_SPEED_MIN_SAMPLE_INTERVAL_MS = 20
+
+export function resetLiveSpeed(
+  states: Map<string, LiveSpeedState>,
+  sessionID: string,
+  messageID: string,
+): void {
+  states.set(sessionID, {
+    messageID,
+    cumulativeTokens: 0,
+    samples: [],
+  })
+}
+
+export function clearLiveSpeed(states: Map<string, LiveSpeedState>, sessionID: string): void {
+  states.delete(sessionID)
+}
+
+export function recordLiveTokens(
+  states: Map<string, LiveSpeedState>,
+  sessionID: string,
+  messageID: string,
+  deltaTokens: number,
+  now: number,
+): void {
+  if (!Number.isFinite(deltaTokens) || deltaTokens <= 0) return
+
+  let state = states.get(sessionID)
+  if (!state || state.messageID !== messageID) {
+    state = { messageID, cumulativeTokens: 0, samples: [] }
+    states.set(sessionID, state)
+  }
+
+  state.cumulativeTokens += deltaTokens
+
+  // Merge into the most recent sample when deltas arrive faster than the
+  // minimum interval (e.g. history replay bursts). This keeps the windowed
+  // TPS honest without discarding the token counts themselves.
+  const latest = state.samples.at(-1)
+  if (latest !== undefined && now - latest.at < LIVE_SPEED_MIN_SAMPLE_INTERVAL_MS) {
+    latest.cumulativeTokens = state.cumulativeTokens
+  } else {
+    state.samples.push({ at: now, cumulativeTokens: state.cumulativeTokens })
+  }
+
+  const cutoff = now - LIVE_SPEED_WINDOW_MS
+  while (state.samples.length > 2 && state.samples[1]!.at < cutoff) {
+    state.samples.shift()
+  }
+  while (state.samples.length > LIVE_SPEED_MAX_SAMPLES) state.samples.shift()
+}
+
+export function getLiveTps(state: LiveSpeedState | undefined, now: number): number | null {
+  if (!state || state.samples.length < 2) return null
+  const latest = state.samples.at(-1)!
+  if (now - latest.at >= LIVE_SPEED_STALE_MS) return null
+
+  const cutoff = latest.at - LIVE_SPEED_WINDOW_MS
+  let baseline = state.samples[0]!
+  for (const sample of state.samples) {
+    if (sample.at >= cutoff) {
+      baseline = sample
+      break
+    }
+  }
+
+  const elapsedMs = latest.at - baseline.at
+  const tokens = latest.cumulativeTokens - baseline.cumulativeTokens
+  if (elapsedMs <= 0 || tokens <= 0) return null
+  return Math.round((tokens / (elapsedMs / 1000)) * 10) / 10
+}

package/src/logger.ts

@@ -0,0 +1,36 @@
+// src/logger.ts
+import { appendFileSync, existsSync, mkdirSync } from "node:fs"
+import { join } from "node:path"
+import { homedir } from "node:os"
+import { getConfig } from "./config"
+
+let logFile: string | null = null
+
+function getLogDir(): string {
+  if (process.platform === "win32") {
+      return join(process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local"), "opentui", "opencode-metrics", "logs")
+  }
+  // macOS & Linux: XDG_DATA_HOME or ~/.local/share
+  const dataHome = process.env.XDG_DATA_HOME || join(homedir(), ".local", "share")
+    return join(dataHome, "opentui", "opencode-metrics", "logs")
+}
+
+function getLogFile(): string {
+  if (logFile) return logFile
+  const dir = getLogDir()
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  logFile = join(dir, "opencode-metrics.log")
+  return logFile
+}
+
+export function log(msg: string): void {
+  const config = getConfig()
+  if (!config.enableLogging) return
+  try {
+    appendFileSync(getLogFile(), `[${new Date().toISOString()}] ${msg}\n`)
+  } catch (error) {
+    if (process.env.OPENCODE_METRICS_DEBUG === "1") {
+      console.warn("opencode-metrics: failed to write log", error)
+    }
+  }
+}