opencode-extended-sidebar 0.2.90

package/src/pware.oc.perf/pware.oc.perf.realtime.ts

@@ -0,0 +1,88 @@
+/**
+ * pware.oc.perf.realtime
+ *
+ * Real-time metric samples from the live stream. One `StatRealtimeSnapshot`
+ * carries the leaf series for every category the OES realtime chart renders
+ * (Tokens / Cache / CPU·RAM / Network); sums are derived via `sumSeries`.
+ * `StatRealtimeSnapshotHistory` is that sample retained in the rolling RAM
+ * history (see `pware.oc.perf.realtimeTimeline.ts`). Pure and host-free.
+ */
+import { REALTIME_WINDOW_MS } from "../pware.oc.core/pware.oc.core.timing.js"
+
+/** Token series — tok/s. `out` is visible output; `reasoning` is hidden thinking. */
+export type StatRealtimeTokensSeries = {
+  in: number | null
+  out: number | null
+  reasoning: number | null
+}
+
+/** Token-cache series — tok/s served from / written to cache. */
+export type StatRealtimeCacheSeries = {
+  read: number | null
+  write: number | null
+}
+
+/** CPU/RAM series — cpu as %, ram as MB. */
+export type StatRealtimeCpuRamSeries = {
+  cpu: number | null
+  ram: number | null
+}
+
+/**
+ * Network series — kbit/s, estimated from the token flow (≈ `NETWORK_BYTES_PER_TOKEN`
+ * per token), not a real socket meter (model traffic lives in the server process).
+ * Network convention: `in` is data the machine receives (model output + reasoning),
+ * `out` is data the machine sends (input + cache). Null when idle.
+ */
+export type StatRealtimeNetworkSeries = {
+  in: number | null
+  out: number | null
+}
+
+/** Rough bytes-per-token used to turn a token rate into a kbit/s estimate. */
+export const NETWORK_BYTES_PER_TOKEN = 4
+
+/** Token rate (tok/s) → kbit/s at `NETWORK_BYTES_PER_TOKEN`. Null stays null. */
+export function tokenRateToKbit(tokPerSec: number | null): number | null {
+  if (tokPerSec == null) return null
+  return (tokPerSec * NETWORK_BYTES_PER_TOKEN * 8) / 1000
+}
+
+/** One point-in-time realtime sample across all categories. Rates are null when idle. */
+export type StatRealtimeSnapshot = {
+  at: number
+  tokens: StatRealtimeTokensSeries
+  cache: StatRealtimeCacheSeries
+  cpuRam: StatRealtimeCpuRamSeries
+  network: StatRealtimeNetworkSeries
+}
+
+/** A realtime sample retained in the rolling history — the same shape as a snapshot. */
+export type StatRealtimeSnapshotHistory = StatRealtimeSnapshot
+
+/** Sum two nullable rates: null only when both are null. */
+export function sumSeries(a: number | null, b: number | null): number | null {
+  if (a == null && b == null) return null
+  return (a ?? 0) + (b ?? 0)
+}
+
+/** An idle sample at `at` — every series null. */
+export function emptyStatRealtimeSnapshot(at = Date.now()): StatRealtimeSnapshot {
+  return {
+    at,
+    tokens: { in: null, out: null, reasoning: null },
+    cache: { read: null, write: null },
+    cpuRam: { cpu: null, ram: null },
+    network: { in: null, out: null },
+  }
+}
+
+/** Append a sample and drop entries older than the window (immutable). */
+export function pushStatRealtimeHistory(
+  history: readonly StatRealtimeSnapshotHistory[],
+  snapshot: StatRealtimeSnapshotHistory,
+  windowMs = REALTIME_WINDOW_MS,
+): StatRealtimeSnapshotHistory[] {
+  const next = [...history, snapshot]
+  return next.filter((s) => snapshot.at - s.at <= windowMs)
+}

package/src/pware.oc.perf/pware.oc.perf.realtimeBlock.ts

@@ -0,0 +1,118 @@
+/**
+ * pware.oc.perf.realtimeBlock
+ *
+ * The static definition of the OES realtime widget: which category tabs exist,
+ * which selector rows each tab offers, and how each row reads its series from a
+ * `StatRealtimeSnapshot`. This is a pure, host-free model — the TUI layer
+ * renders it and owns the runtime state (active tab, fullscreen).
+ */
+import { sumSeries, type StatRealtimeSnapshot, type StatRealtimeSnapshotHistory } from "./pware.oc.perf.realtime.js"
+
+/** A selector row's series key — unique within its tab. */
+export type StatRealtimeSeriesKey =
+  | "avg"
+  | "sum"
+  | "in"
+  | "out"
+  | "reasoning"
+  | "read"
+  | "write"
+  | "cpu"
+  | "ram"
+  | "tok/s"
+
+/** One selector row: its key, label, unit, and how to read the series from a sample. */
+export type StatRealtimeRowTab = {
+  key: StatRealtimeSeriesKey
+  label: string
+  unit: string
+  read: (snap: StatRealtimeSnapshot) => number | null
+}
+
+/** A category tab id. */
+export type StatRealtimeTabId = "tokens" | "cache" | "cpu-ram" | "network"
+/** One category tab: its id, label, unit, and selector rows. */
+export type StatRealtimeTab = {
+  id: StatRealtimeTabId
+  label: string
+  unit: string
+  rows: readonly StatRealtimeRowTab[]
+}
+
+/** The whole realtime widget definition: the tabs the selector offers. */
+export type StatRealtimeBlock = {
+  tabs: readonly StatRealtimeTab[]
+}
+
+/** Extract one selector row's series across history as a chartable `number[]` (null → 0). */
+export function seriesValues(
+  history: readonly StatRealtimeSnapshotHistory[],
+  read: (snap: StatRealtimeSnapshot) => number | null,
+): number[] {
+  return history.map((s) => read(s) ?? 0)
+}
+
+/** The tab for `id`, or the first tab if `id` is unknown. */
+export function realtimeTab(
+  tabs: readonly StatRealtimeTab[],
+  id: StatRealtimeTabId,
+): StatRealtimeTab {
+  return tabs.find((t) => t.id === id) ?? tabs[0]!
+}
+
+/** The selector row for `key` on `tab`, or the tab's first row if `key` is missing. */
+export function realtimeRow(
+  tab: StatRealtimeTab,
+  key: StatRealtimeSeriesKey,
+): StatRealtimeRowTab {
+  return tab.rows.find((r) => r.key === key) ?? tab.rows[0]!
+}
+
+/** The default OES realtime block. Network is estimated from the token flow (kbit/s). */
+export const STAT_REALTIME_BLOCK: StatRealtimeBlock = {
+  tabs: [
+    {
+      id: "tokens",
+      label: "Tok",
+      unit: "tok/s",
+      rows: [
+        // avg is the OES bar's old live reading — the chart smooths this series.
+        { key: "avg", label: "avg", unit: "tok/s", read: (s) => sumSeries(s.tokens.in, s.tokens.out) },
+        { key: "sum", label: "sum", unit: "tok/s", read: (s) => sumSeries(s.tokens.in, s.tokens.out) },
+        { key: "in", label: "in", unit: "tok/s", read: (s) => s.tokens.in },
+        { key: "out", label: "out", unit: "tok/s", read: (s) => s.tokens.out },
+        // tok/s duplicates sum (in+out) — kept as the bar's old label per UX.
+        { key: "tok/s", label: "tok/s", unit: "tok/s", read: (s) => sumSeries(s.tokens.in, s.tokens.out) },
+      ],
+    },
+    {
+      id: "cache",
+      label: "Cache",
+      unit: "tok/s",
+      rows: [
+        { key: "sum", label: "sum", unit: "tok/s", read: (s) => sumSeries(s.cache.read, s.cache.write) },
+        { key: "read", label: "read", unit: "tok/s", read: (s) => s.cache.read },
+        { key: "write", label: "write", unit: "tok/s", read: (s) => s.cache.write },
+      ],
+    },
+    {
+      id: "cpu-ram",
+      label: "Proc",
+      unit: "%/MB",
+      rows: [
+        { key: "cpu", label: "cpu", unit: "%", read: (s) => s.cpuRam.cpu },
+        { key: "ram", label: "ram", unit: "MB", read: (s) => s.cpuRam.ram },
+      ],
+    },
+    {
+      id: "network",
+      label: "Net",
+      unit: "kbit/s",
+      rows: [
+        { key: "in", label: "in", unit: "kbit/s", read: (s) => s.network.in },
+        { key: "out", label: "out", unit: "kbit/s", read: (s) => s.network.out },
+        { key: "sum", label: "sum", unit: "kbit/s", read: (s) => sumSeries(s.network.in, s.network.out) },
+      ],
+    },
+  ],
+}

package/src/pware.oc.perf/pware.oc.perf.realtimeCpuRam.ts

@@ -0,0 +1,79 @@
+/**
+ * pware.oc.perf.realtimeCpuRam
+ *
+ * Process-level CPU/RAM reading for the OES realtime block. CPU% is the
+ * OpenCode process's load across all cores; RAM is its resident set. Both come
+ * from Node/Bun built-ins (`process.cpuUsage`, `process.memoryUsage`,
+ * `os.cpus`), so they work identically on Linux, macOS and Windows with no
+ * dependencies. The sampling math is pure and exported for tests; the host
+ * read helpers (`readCpuRam`, `cpuCores`) are thin edges the UI tick calls.
+ */
+import os from "node:os"
+
+/** A raw CPU/RAM reading: cumulative CPU µs (user/system) + resident bytes. */
+export type CpuRamReading = {
+  user: number
+  system: number
+  rss: number
+}
+
+/** One raw reading from the host: process CPU µs since start + resident bytes. Never throws. */
+export function readCpuRam(): CpuRamReading {
+  try {
+    const cpu = process.cpuUsage()
+    return { user: cpu.user, system: cpu.system, rss: process.memoryUsage().rss }
+  } catch {
+    return { user: 0, system: 0, rss: 0 }
+  }
+}
+
+/** Logical CPU count — divides CPU% so a full core is never above 100. */
+export function cpuCores(): number {
+  return os.cpus().length
+}
+
+/** A reading stamped with when it was taken. */
+export type CpuRamStampedReading = CpuRamReading & { at: number }
+
+/** Process CPU% over an interval, relative to `cores` cores. Null when unmeasurable. */
+export function cpuPercent(
+  prev: CpuRamReading,
+  next: CpuRamReading,
+  wallMs: number,
+  cores: number,
+): number | null {
+  if (wallMs <= 0 || cores <= 0) return null
+  const usedMs = (next.user - prev.user + next.system - prev.system) / 1000
+  return (usedMs / wallMs / cores) * 100
+}
+
+/**
+ * CPU% across a rolling window of stamped readings (oldest first): the delta
+ * between the newest and the first reading still inside the window, over their
+ * wall span. Null while fewer than two readings fit. This is what damps the
+ * fine sampling cadence into a stable utilisation number.
+ */
+export function cpuPercentOverWindow(
+  readings: readonly CpuRamStampedReading[],
+  cores: number,
+  windowMs: number,
+): number | null {
+  if (cores <= 0 || windowMs <= 0 || readings.length < 2) return null
+  const last = readings[readings.length - 1]!
+  const minAt = last.at - windowMs
+  let first = readings[0]!
+  for (let i = 0; i < readings.length; i += 1) {
+    if (readings[i]!.at >= minAt) {
+      first = readings[i]!
+      break
+    }
+  }
+  const wall = last.at - first.at
+  if (wall <= 0) return null
+  return cpuPercent(first, last, wall, cores)
+}
+
+/** Resident bytes → MB. */
+export function ramMb(rssBytes: number): number {
+  return rssBytes / (1024 * 1024)
+}

package/src/pware.oc.perf/pware.oc.perf.realtimeSampler.ts

@@ -0,0 +1,71 @@
+/**
+ * pware.oc.perf.realtimeSampler
+ *
+ * Event-driven sampler: subscribes to `session.updated` events, extracts the
+ * per-session cumulative token totals, and feeds them to a
+ * `StatRealtimeTimeline`. The subscription is injected so the class stays
+ * host-free; the event parsing is a pure exported function.
+ */
+import type { StatRealtimeEventTokens, StatRealtimeTimeline } from "./pware.oc.perf.realtimeTimeline.js"
+
+/** Subscribe to realtime events: returns a dispose function. */
+export type RealtimeEventSubscribe = (handler: (evt: unknown) => void) => () => void
+
+/** Pull `sessionID` + cumulative `tokens` out of a `session.updated` event; null otherwise. */
+export function extractSessionTokens(evt: unknown): { sessionId: string; tokens: StatRealtimeEventTokens } | null {
+  if (!evt || typeof evt !== "object") return null
+  const o = evt as Record<string, unknown>
+  const props = (
+    o.properties && typeof o.properties === "object" ? o.properties : o
+  ) as Record<string, unknown>
+  const sessionId = props.sessionID ?? props.sessionId ?? props.session_id
+  const info = props.info as Record<string, unknown> | undefined
+  const tokens = info && typeof info === "object" ? (info.tokens as Record<string, unknown> | undefined) : undefined
+  if (typeof sessionId !== "string" || !sessionId || !tokens || typeof tokens !== "object") return null
+  const num = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) ? v : 0)
+  const cache = (
+    tokens.cache && typeof tokens.cache === "object" ? tokens.cache : {}
+  ) as Record<string, unknown>
+  return {
+    sessionId,
+    tokens: {
+      input: num(tokens.input),
+      output: num(tokens.output),
+      reasoning: num(tokens.reasoning),
+      cacheRead: num(cache.read),
+      cacheWrite: num(cache.write),
+    },
+  }
+}
+
+export class EventDriverSampler {
+  static create(
+    timeline: StatRealtimeTimeline,
+    subscribe: RealtimeEventSubscribe,
+    now: () => number = Date.now,
+  ): EventDriverSampler {
+    return new EventDriverSampler(timeline, subscribe, now)
+  }
+
+  private off: (() => void) | null = null
+
+  private constructor(
+    private readonly timeline: StatRealtimeTimeline,
+    private readonly subscribe: RealtimeEventSubscribe,
+    private readonly now: () => number,
+  ) {}
+
+  start(): void {
+    if (this.off) return
+    this.off = this.subscribe((evt) => {
+      const hit = extractSessionTokens(evt)
+      if (!hit) return
+      this.timeline.ingest(hit.sessionId, hit.tokens, this.now())
+    })
+  }
+
+  stop(): void {
+    this.off?.()
+    this.off = null
+  }
+}

package/src/pware.oc.perf/pware.oc.perf.realtimeTimeline.ts

@@ -0,0 +1,214 @@
+/**
+ * pware.oc.perf.realtimeTimeline
+ *
+ * One shared realtime history for every category the OES realtime chart
+ * renders (Tokens / Cache / CPU·RAM / Network). A single wall-clock loop calls
+ * `tick(at)` on the UI heartbeat cadence (`TICK_MS`); every tick folds the
+ * current per-session cumulative token state and the raw CPU ring into one grid
+ * sample, so the chart's right edge always reaches "now" instead of waiting for
+ * a host event. Pure state + injectable timestamps — no host, no database.
+ *
+ * Token/cache rates are a windowed derivative over the trailing
+ * `REALTIME_RATE_WINDOW_MS`: `ingest` (exact `session.updated` totals) and
+ * `ingestEstimate` (estimated stream deltas for out/reasoning) record level
+ * changes, and `tick` reports the average over the window — it falls back to
+ * zero when nothing new arrives instead of holding a stale rate. Estimated
+ * out/reasoning deltas are reconciled against the exact totals on every
+ * `session.updated`, so a streamed token is never counted twice: the exact
+ * delta only adds what the estimate has not covered yet.
+ */
+import { cpuCores, cpuPercentOverWindow, ramMb, type CpuRamReading } from "./pware.oc.perf.realtimeCpuRam.js"
+import {
+  REALTIME_RATE_WINDOW_MS,
+  REALTIME_WINDOW_MS,
+} from "../pware.oc.core/pware.oc.core.timing.js"
+import {
+  emptyStatRealtimeSnapshot,
+  pushStatRealtimeHistory,
+  sumSeries,
+  tokenRateToKbit,
+  type StatRealtimeSnapshot,
+  type StatRealtimeSnapshotHistory,
+} from "./pware.oc.perf.realtime.js"
+
+/** Cumulative token totals as reported by one `session.updated` event. */
+export type StatRealtimeEventTokens = {
+  input: number
+  output: number
+  reasoning: number
+  cacheRead: number
+  cacheWrite: number
+}
+
+/** Which token channel an estimated stream delta feeds. */
+export type StatRealtimeEstKind = "out" | "reasoning"
+
+/** A single cumulative-token or streamed-token level change at `at`. */
+type Step = { at: number; n: number }
+
+/** Per-session state: last exact totals + stream estimates not yet confirmed. */
+type SessionState = {
+  exact: StatRealtimeEventTokens | null
+  estOut: number
+  estReasoning: number
+  lastAt: number
+}
+
+/** Channel names that map 1:1 onto a `StatRealtimeSnapshot` leaf. */
+type TokenChannel = "in" | "out" | "reasoning" | "cacheRead" | "cacheWrite"
+
+const TOKEN_CHANNELS: readonly TokenChannel[] = ["in", "out", "reasoning", "cacheRead", "cacheWrite"]
+
+function pos(n: number): number {
+  return Number.isFinite(n) && n > 0 ? n : 0
+}
+
+export class StatRealtimeTimeline {
+  static build(scope: string | null = null, cores: number = cpuCores()): StatRealtimeTimeline {
+    return new StatRealtimeTimeline(scope, cores)
+  }
+
+  private readonly scope: string | null
+  private readonly cores: number
+  private readonly bySession = new Map<string, SessionState>()
+  private readonly steps = new Map<TokenChannel, Step[]>()
+  private cpuReadings: Array<CpuRamReading & { at: number }> = []
+  private history: StatRealtimeSnapshotHistory[] = []
+
+  private constructor(scope: string | null, cores: number) {
+    this.scope = scope
+    this.cores = cores
+    for (const c of TOKEN_CHANNELS) this.steps.set(c, [])
+  }
+
+  /** Exact cumulative totals from one `session.updated` event. */
+  ingest(sessionId: string, totals: StatRealtimeEventTokens, at: number): void {
+    if (this.scope !== null && sessionId !== this.scope) return
+    const st = this.bySession.get(sessionId) ?? {
+      exact: null,
+      estOut: 0,
+      estReasoning: 0,
+      lastAt: 0,
+    }
+    st.lastAt = at
+    this.bySession.set(sessionId, st)
+
+    const prev = st.exact
+    if (!prev) {
+      // First report is the baseline: estimates seen before it are already
+      // inside the reported cumulative, so they must not suppress the first
+      // post-baseline delta.
+      st.exact = totals
+      st.estOut = 0
+      st.estReasoning = 0
+      return
+    }
+    this.push("in", totals.input - prev.input, at)
+    this.push("cacheRead", totals.cacheRead - prev.cacheRead, at)
+    this.push("cacheWrite", totals.cacheWrite - prev.cacheWrite, at)
+    this.rebase("out", "estOut", prev.output, totals.output, st, at)
+    this.rebase("reasoning", "estReasoning", prev.reasoning, totals.reasoning, st, at)
+    st.exact = totals
+  }
+
+  /** Estimated streamed delta (text → out, thinking → reasoning). */
+  ingestEstimate(sessionId: string, kind: StatRealtimeEstKind, n: number, at: number): void {
+    if (this.scope !== null && sessionId !== this.scope) return
+    const amount = pos(n)
+    if (amount === 0) return
+    this.push(kind, amount, at)
+    const st = this.bySession.get(sessionId) ?? {
+      exact: null,
+      estOut: 0,
+      estReasoning: 0,
+      lastAt: 0,
+    }
+    st.lastAt = at
+    if (kind === "out") st.estOut += amount
+    else st.estReasoning += amount
+    this.bySession.set(sessionId, st)
+  }
+
+  /** A raw process CPU/RAM reading, taken on the same cadence as `tick`. */
+  ingestCpuRam(raw: CpuRamReading, at: number): void {
+    this.cpuReadings.push({ ...raw, at })
+  }
+
+  /** Advance the grid: fold all state into one sample at `at`, prune stale state. */
+  tick(at: number): void {
+    const cut = at - REALTIME_RATE_WINDOW_MS
+    const snap = emptyStatRealtimeSnapshot(at)
+
+    for (const c of TOKEN_CHANNELS) {
+      const kept: Step[] = []
+      let sum = 0
+      for (const s of this.steps.get(c)!) {
+        if (s.at <= cut) continue
+        kept.push(s)
+        sum += s.n
+      }
+      this.steps.set(c, kept)
+      this.setChannel(snap, c, sum === 0 ? null : (sum / REALTIME_RATE_WINDOW_MS) * 1000)
+    }
+
+    // Network is estimated from the same token flow: what the session sends to
+    // the model (input + cache) is `out`, what streams back (output + reasoning)
+    // is `in`. Real socket bytes never reach this plugin (model traffic lives in
+    // the server process), so kbit/s here means "≈ tokens × 4 bytes", not a meter.
+    snap.network.out = tokenRateToKbit(sumSeries(snap.tokens.in, sumSeries(snap.cache.read, snap.cache.write)))
+    snap.network.in = tokenRateToKbit(sumSeries(snap.tokens.out, snap.tokens.reasoning))
+
+    this.cpuReadings = this.cpuReadings.filter((r) => r.at > cut)
+    snap.cpuRam.cpu = cpuPercentOverWindow(this.cpuReadings, this.cores, REALTIME_RATE_WINDOW_MS)
+    const last = this.cpuReadings[this.cpuReadings.length - 1]
+    snap.cpuRam.ram = last ? ramMb(last.rss) : null
+
+    this.history = pushStatRealtimeHistory(this.history, snap, REALTIME_WINDOW_MS)
+    // Drop est-only transient states once idle — a session with an exact
+    // baseline stays, so its first post-idle burst still diffs correctly.
+    const stale = at - REALTIME_WINDOW_MS
+    for (const [sid, st] of this.bySession) {
+      if (st.exact === null && st.lastAt < stale) this.bySession.delete(sid)
+    }
+  }
+
+  /** The rolling grid samples in time order — already on the fixed grid. */
+  getTimeline(): StatRealtimeSnapshotHistory[] {
+    return this.history
+  }
+
+  reset(): void {
+    this.bySession.clear()
+    for (const c of TOKEN_CHANNELS) this.steps.set(c, [])
+    this.cpuReadings = []
+    this.history = []
+  }
+
+  private push(channel: TokenChannel, n: number, at: number): void {
+    const amount = pos(n)
+    if (amount === 0) return
+    this.steps.get(channel)!.push({ at, n: amount })
+  }
+
+  private rebase(
+    channel: "out" | "reasoning",
+    estKey: "estOut" | "estReasoning",
+    prevVal: number,
+    nextVal: number,
+    st: SessionState,
+    at: number,
+  ): void {
+    const delta = pos(nextVal - prevVal)
+    const uncovered = Math.max(0, delta - st[estKey])
+    st[estKey] = 0
+    this.push(channel, uncovered, at)
+  }
+
+  private setChannel(snap: StatRealtimeSnapshot, c: TokenChannel, rate: number | null): void {
+    if (c === "in") snap.tokens.in = rate
+    else if (c === "out") snap.tokens.out = rate
+    else if (c === "reasoning") snap.tokens.reasoning = rate
+    else if (c === "cacheRead") snap.cache.read = rate
+    else snap.cache.write = rate
+  }
+}