opencode-cache-hit 0.1.0

package/src/tui-panel/layout.ts

@@ -0,0 +1,107 @@
+/** Terminal layout primitives (visual-width aware, opencode-visual-cache compatible). */
+
+export const MIN_PANEL_WIDTH = 20
+export const DEFAULT_PANEL_WIDTH = 28
+export const PANEL_GUTTER = 6
+export const UNIT_GAP = 1
+export const HEADER_PREFIX = 2
+
+export const HIT_LABEL_GAP = 1
+export const HIT_BAR_BRACKETS = 2
+export const HIT_BAR_GAP = 1
+export const HIT_PCT_FIXED_WIDTH = 5
+
+function charColumns(c: string): number {
+  const code = c.codePointAt(0) ?? 0
+  if (code < 0x20) return 0
+  if (code < 0x7f) return 1
+  if (code < 0xa0) return 0
+  if (
+    (code >= 0x1100 && code <= 0x115f) ||
+    (code >= 0x2e80 && code <= 0xa4cf) ||
+    (code >= 0xac00 && code <= 0xd7a3) ||
+    (code >= 0xf900 && code <= 0xfaff) ||
+    (code >= 0xfe10 && code <= 0xfe6f) ||
+    (code >= 0xff01 && code <= 0xff60) ||
+    (code >= 0xffe0 && code <= 0xffe6) ||
+    (code >= 0x1f300 && code <= 0x1f64f) ||
+    (code >= 0x20000 && code <= 0x3fffd)
+  )
+    return 2
+  return 1
+}
+
+export function visualWidth(s: string): number {
+  let w = 0
+  for (const c of s) w += charColumns(c)
+  return w
+}
+
+export function visualPadEnd(s: string, cols: number): string {
+  const pad = cols - visualWidth(s)
+  return pad > 0 ? s + " ".repeat(pad) : s
+}
+
+export function truncateVisual(s: string, maxCols: number): string {
+  if (visualWidth(s) <= maxCols) return s
+  let result = ""
+  let w = 0
+  for (const c of s) {
+    const cw = charColumns(c)
+    if (w + cw > maxCols - 1) {
+      result += "\u2026"
+      break
+    }
+    result += c
+    w += cw
+  }
+  return result
+}
+
+export function computeHitBarWidth(
+  hitLabel: string,
+  rowWidth: number,
+  trendText: string,
+  showTrend: boolean,
+): number {
+  const trendSpace = showTrend ? HIT_LABEL_GAP + visualWidth(trendText) : 0
+  const overhead =
+    visualWidth(hitLabel) +
+    HIT_LABEL_GAP +
+    HIT_BAR_BRACKETS +
+    HIT_BAR_GAP +
+    HIT_PCT_FIXED_WIDTH +
+    trendSpace
+  return Math.max(3, rowWidth - overhead)
+}
+
+export function justifyEnds(label: string, right: string, rowWidth: number): string {
+  const gap = Math.max(1, rowWidth - visualWidth(label) - visualWidth(right))
+  return label + " ".repeat(gap) + right
+}
+
+export function justifyRow(label: string, value: string, rowWidth: number, unit = ""): string {
+  const used =
+    visualWidth(label) + visualWidth(value) + (unit ? visualWidth(unit) + UNIT_GAP : 0)
+  const gap = Math.max(1, rowWidth - used)
+  return label + " ".repeat(gap) + value + (unit ? " " + unit : "")
+}
+
+export function sepAfterPrefix(prefix: string, rowWidth: number): string {
+  const rest = Math.max(1, rowWidth - visualWidth(prefix))
+  return "\u2500".repeat(rest)
+}
+
+export function separatorLine(width = 28): string {
+  return "\u2500".repeat(Math.max(8, width))
+}
+
+/** Spaces before right-aligned collapsed title summary. */
+export function padBeforeTitleSummary(
+  panelWidth: number,
+  gutter: number,
+  titleWidth: number,
+  summaryWidth: number,
+): number {
+  return Math.max(1, panelWidth - gutter - HEADER_PREFIX - titleWidth - summaryWidth)
+}

package/src/tui-panel/palette.ts

@@ -0,0 +1,93 @@
+const FALLBACK = {
+  primary: "#8B9DAF",
+  text: "#C5C5BB",
+  muted: "#7A7A72",
+  success: "#9CAF8B",
+  warning: "#C5B88D",
+  error: "#B08A8A",
+  border: "#6B6B63",
+} as const
+
+function rgb(raw: unknown): { r: number; g: number; b: number } | null {
+  if (typeof raw === "string" && raw.startsWith("#")) {
+    const h = raw.slice(1)
+    return {
+      r: parseInt(h.slice(0, 2), 16),
+      g: parseInt(h.slice(2, 4), 16),
+      b: parseInt(h.slice(4, 6), 16),
+    }
+  }
+  if (raw && typeof raw === "object") {
+    const o = raw as Record<string, unknown>
+    if (typeof o.r === "number" && typeof o.g === "number" && typeof o.b === "number") {
+      const scale = o.r > 1 || o.g > 1 || o.b > 1 ? 1 : 255
+      return { r: Math.round(o.r * scale), g: Math.round(o.g * scale), b: Math.round(o.b * scale) }
+    }
+  }
+  return null
+}
+
+function saturation(r: number, g: number, b: number): number {
+  const max = Math.max(r, g, b) / 255
+  const min = Math.min(r, g, b) / 255
+  const delta = max - min
+  if (delta === 0) return 0
+  const L = (max + min) / 2
+  return L <= 0.5 ? delta / (max + min) : delta / (2 - max - min)
+}
+
+function desaturateTo(raw: unknown, maxSat: number, fallback: string): string {
+  const c = rgb(raw)
+  if (!c) return fallback
+  const sat = saturation(c.r, c.g, c.b)
+  if (sat <= maxSat) {
+    return "#" + [c.r, c.g, c.b].map((v) => v.toString(16).padStart(2, "0")).join("")
+  }
+  const luma = c.r * 0.299 + c.g * 0.587 + c.b * 0.114
+  let lo = 0,
+    hi = 1
+  for (let i = 0; i < 12; i++) {
+    const mid = (lo + hi) / 2
+    const nr = Math.round(c.r + (luma - c.r) * mid)
+    const ng = Math.round(c.g + (luma - c.g) * mid)
+    const nb = Math.round(c.b + (luma - c.b) * mid)
+    if (saturation(nr, ng, nb) > maxSat) lo = mid
+    else hi = mid
+  }
+  const nr = Math.round(c.r + (luma - c.r) * hi)
+  const ng = Math.round(c.g + (luma - c.g) * hi)
+  const nb = Math.round(c.b + (luma - c.b) * hi)
+  return "#" + [nr, ng, nb].map((v) => Math.max(0, Math.min(255, v)).toString(16).padStart(2, "0")).join("")
+}
+
+const MAX_SAT = 0.28
+
+export type PanelPalette = {
+  primary: string
+  text: string
+  muted: string
+  success: string
+  warning: string
+  error: string
+  border: string
+}
+
+/** Parse OpenCode theme color to #rrggbb (for tests and optional callers). */
+export function themeColorToHex(raw: unknown, fallback: string): string {
+  const c = rgb(raw)
+  if (!c) return fallback
+  return "#" + [c.r, c.g, c.b].map((v) => v.toString(16).padStart(2, "0")).join("")
+}
+
+export function buildPanelPalette(theme: Record<string, unknown>): PanelPalette {
+  const sat = (k: string, fb: string) => desaturateTo(theme[k], MAX_SAT, fb)
+  return {
+    primary: sat("primary", FALLBACK.primary),
+    text: sat("text", FALLBACK.text),
+    muted: sat("textMuted", FALLBACK.muted),
+    success: sat("success", FALLBACK.success),
+    warning: sat("warning", FALLBACK.warning),
+    error: sat("error", FALLBACK.error),
+    border: sat("border", FALLBACK.border),
+  }
+}

package/src/tui-panel/use-panel-layout.ts

@@ -0,0 +1,69 @@
+import { createEffect, createMemo, createSignal, type Accessor } from "solid-js"
+import {
+  DEFAULT_PANEL_WIDTH,
+  justifyRow,
+  MIN_PANEL_WIDTH,
+  PANEL_GUTTER,
+  separatorLine,
+} from "./layout.ts"
+
+export type PanelLayoutOptions = {
+  border: Accessor<boolean>
+}
+
+/**
+ * Measured sidebar width + row helpers.
+ * Call once per panel instance (e.g. top of sidebar component), not per render branch.
+ */
+export function createPanelLayout(options: PanelLayoutOptions) {
+  const [panelWidth, setPanelWidth] = createSignal(DEFAULT_PANEL_WIDTH)
+  let boxEl: { width?: number } | undefined
+
+  const gutter = createMemo(() => (options.border() ? PANEL_GUTTER : 0))
+  const gauge = createMemo(() => Math.max(MIN_PANEL_WIDTH, panelWidth() - gutter()))
+  const sep = createMemo(() => separatorLine(gauge()))
+
+  const syncWidth = () => {
+    const w = boxEl?.width
+    if (typeof w === "number" && w > 0) {
+      const next = Math.max(MIN_PANEL_WIDTH, w)
+      setPanelWidth((prev) => (prev === next ? prev : next))
+    }
+  }
+
+  createEffect(() => {
+    options.border()
+    syncWidth()
+  })
+
+  const row = (label: string, value: string, unit = "") => justifyRow(label, value, gauge(), unit)
+
+  return {
+    panelWidth,
+    gutter,
+    gauge,
+    sep,
+    row,
+    syncWidth,
+    get boxRef() {
+      return boxEl
+    },
+    set boxRef(el: { width?: number } | undefined) {
+      boxEl = el
+    },
+  }
+}
+
+export type PanelLayout = ReturnType<typeof createPanelLayout>
+
+/** Independent fold state for a collapsible section. */
+export function createSectionFold(initial = true) {
+  const [open, setOpen] = createSignal(initial)
+  return {
+    open,
+    setOpen,
+    toggle: () => setOpen((o) => !o),
+  }
+}
+
+export type SectionFold = ReturnType<typeof createSectionFold>

package/src/types.ts

@@ -0,0 +1,71 @@
+export type SessionSnapshot = {
+  model: string
+  input: number
+  output: number
+  reasoning: number
+  cacheRead: number
+  cacheWrite: number
+  cost: number
+}
+
+export type SubAgentSummary = {
+  id: string
+  cost: number
+  input: number
+  output: number
+  reasoning: number
+  cacheRead: number
+  cacheWrite: number
+}
+
+export type AssistantMessage = {
+  role?: string
+  id?: string
+  messageID?: string
+  modelID?: string
+  cost?: number
+  /** OpenCode SDK: true = summary/compaction message, not a full LLM pricing turn */
+  summary?: boolean
+  time?: {
+    created: number
+    completed?: number
+  }
+  tokens?: {
+    input?: number
+    output?: number
+    reasoning?: number
+    cache?: { read?: number; write?: number }
+  }
+}
+
+export type OpenCodeTuiApi = {
+  state: {
+    path: { directory: string }
+    session: {
+      messages: (id: string) => unknown[] | undefined
+      get: (id: string) => { parentID?: string } | undefined
+    }
+  }
+  client: {
+    session: {
+      list: (opts: { query: { directory: string } }) => Promise<unknown>
+    }
+  }
+  event: {
+    on: (
+      name: string,
+      fn: (event: { properties?: { info?: { sessionID?: string } } }) => void,
+    ) => () => void
+  }
+  slots: {
+    register: (opts: {
+      order: number
+      slots: {
+        sidebar_content: (
+          ctx: { theme: { current: Record<string, unknown> } },
+          props: { session_id: string },
+        ) => unknown
+      }
+    }) => void
+  }
+}

package/src/use-cache-hit-metrics.ts

@@ -0,0 +1,103 @@
+import { createMemo, type Accessor } from "solid-js"
+import type { DisplayConfig } from "./plugin-config.ts"
+import { getUiStrings, resolveLang } from "./i18n.ts"
+import {
+  formatHitBar,
+  formatPercentOneDecimal,
+  formatRatioAsPercent,
+  formatTrendLabel,
+} from "./format-cache-ui.ts"
+import { computeHitBarWidth, visualWidth } from "./tui-panel/layout.ts"
+import { buildPanelPalette, type PanelPalette } from "./tui-panel/palette.ts"
+import type { PanelLayout } from "./tui-panel/use-panel-layout.ts"
+import type { AssistantMessage, SessionSnapshot, SubAgentSummary } from "./types.ts"
+import {
+  cacheHitRatio,
+  combinedCacheHitRatio,
+  computePerCallHitTrend,
+  mainSessionHasStats,
+  shortModelName,
+} from "./stats.ts"
+
+function activeLang(display: DisplayConfig) {
+  return display.lang === "auto" ? resolveLang("auto") : display.lang
+}
+
+function hitRateColor(pct: number, pal: PanelPalette): string {
+  if (pct >= 85) return pal.success
+  if (pct >= 70) return pal.warning
+  return pal.muted
+}
+
+export function useCacheHitMetrics(props: {
+  theme: Accessor<Record<string, unknown>>
+  display: DisplayConfig
+  messages: Accessor<AssistantMessage[]>
+  main: Accessor<SessionSnapshot>
+  subAgents: Accessor<SubAgentSummary[]>
+  layout: PanelLayout
+}) {
+  const pal = createMemo(() => buildPanelPalette(props.theme()))
+  const t = createMemo(() => getUiStrings(activeLang(props.display)))
+  const hitLabel = createMemo(() => props.display.mainHitLabel ?? t().hit)
+  const subs = createMemo(() => props.subAgents())
+  const main = createMemo(() => props.main())
+  const perCall = createMemo(() => computePerCallHitTrend(props.messages()))
+  const sessionRatio = createMemo(() => cacheHitRatio(main().cacheRead, main().input))
+  const combinedRatio = createMemo(() => combinedCacheHitRatio(main(), subs()))
+
+  const showCombinedHit = createMemo(() => {
+    if (subs().length === 0) return false
+    return Math.abs(combinedRatio() - sessionRatio()) >= 0.0005
+  })
+
+  const mainHasStats = createMemo(() => mainSessionHasStats(main()))
+  const hasData = createMemo(() => mainHasStats() || subs().length > 0)
+
+  const trendLabel = createMemo(() =>
+    perCall().hasTrend ? formatTrendLabel(perCall().trendPercent) : "",
+  )
+  const bar = createMemo(() =>
+    formatHitBar(
+      perCall().hitPercent / 100,
+      computeHitBarWidth(hitLabel(), props.layout.gauge(), trendLabel(), perCall().hasTrend),
+    ),
+  )
+  const hitColor = createMemo(() => hitRateColor(perCall().hitPercent, pal()))
+  const trendFg = createMemo(() => {
+    const tr = perCall().trendPercent
+    if (Math.abs(tr) < 0.05) return pal().text
+    return tr > 0 ? pal().success : pal().error
+  })
+
+  const collapsedHitSummary = createMemo(() => {
+    const right = perCall().hasTrend
+      ? `${formatPercentOneDecimal(perCall().hitPercent)} ${t().hitFolded} ${trendLabel()}`
+      : `${formatPercentOneDecimal(perCall().hitPercent)} ${t().hitFolded}`
+    return { text: right, width: visualWidth(right) }
+  })
+
+  return {
+    pal,
+    t,
+    hitLabel,
+    subs,
+    main,
+    mainHasStats,
+    perCall,
+    sessionPct: createMemo(() => formatRatioAsPercent(sessionRatio())),
+    combinedPct: createMemo(() => formatRatioAsPercent(combinedRatio())),
+    showCombinedHit,
+    hasData,
+    trendLabel,
+    bar,
+    hitColor,
+    trendFg,
+    pctLabel: createMemo(() => formatPercentOneDecimal(perCall().hitPercent)),
+    modelShort: createMemo(() => shortModelName(main().model)),
+    totalSubCost: createMemo(() => subs().reduce((s, a) => s + a.cost, 0)),
+    collapsedHitSummary,
+  }
+}
+
+export type CacheHitMetrics = ReturnType<typeof useCacheHitMetrics>

package/src/version.ts

@@ -0,0 +1 @@
+export const PLUGIN_VERSION = "0.1.0"

package/src/widget.tsx

@@ -0,0 +1,117 @@
+/** @jsxImportSource @opentui/solid */
+import { createMemo, createSignal, Show, type Accessor } from "solid-js"
+import type { DisplayConfig } from "./plugin-config.ts"
+import type { AssistantMessage, SessionSnapshot, SubAgentSummary } from "./types.ts"
+import { PLUGIN_VERSION } from "./version.ts"
+import { AgentsView } from "./agents-view.tsx"
+import { MainSessionView } from "./main-session-view.tsx"
+import { useCacheHitMetrics } from "./use-cache-hit-metrics.ts"
+import {
+  createPanelLayout,
+  createSectionFold,
+  TuiPanel,
+  TuiPanelNoData,
+  TuiPanelSep,
+  TuiPanelTitle,
+  TuiSection,
+  TuiTitleSummaryPad,
+  visualWidth,
+} from "./tui-panel/index.ts"
+
+export function CacheHitSidebar(props: {
+  sessionId: Accessor<string>
+  theme: Record<string, unknown>
+  display: DisplayConfig
+  messages: Accessor<AssistantMessage[]>
+  main: Accessor<SessionSnapshot>
+  subAgents: Accessor<SubAgentSummary[]>
+  formatCost: (amount: number) => string
+}) {
+  const [panelOpen, setPanelOpen] = createSignal(true)
+  const detail = createSectionFold(true)
+  const model = createSectionFold(true)
+  const agents = createSectionFold(true)
+
+  const borderOn = () => props.display.panelBorder
+  const layout = createPanelLayout({ border: borderOn })
+
+  const m = useCacheHitMetrics({
+    theme: () => props.theme,
+    display: props.display,
+    messages: props.messages,
+    main: props.main,
+    subAgents: props.subAgents,
+    layout,
+  })
+
+  const agentsSuffix = createMemo(() => {
+    const n = m.subs().length
+    if (n === 0) return ""
+    return ` (${n})${m.t().agentsScopeHint}`
+  })
+
+  return (
+    <Show when={props.sessionId().length > 0}>
+      <TuiPanel pal={m.pal()} border={borderOn()} layout={layout}>
+        <TuiPanelTitle
+          pal={m.pal()}
+          layout={layout}
+          open={panelOpen()}
+          onToggle={() => setPanelOpen((o) => !o)}
+          title={m.t().title}
+          version={PLUGIN_VERSION}
+          collapsed={
+            <>
+              <Show when={m.hasData() && m.mainHasStats()}>
+                <TuiTitleSummaryPad
+                  layout={layout}
+                  titleWidth={visualWidth(m.t().title)}
+                  summaryWidth={m.collapsedHitSummary().width}
+                >
+                  <span style={{ fg: m.hitColor() }}>{m.collapsedHitSummary().text}</span>
+                </TuiTitleSummaryPad>
+              </Show>
+              <Show when={m.hasData() && !m.mainHasStats() && m.subs().length > 0}>
+                <TuiTitleSummaryPad
+                  layout={layout}
+                  titleWidth={visualWidth(m.t().title)}
+                  summaryWidth={visualWidth(props.formatCost(m.totalSubCost()))}
+                >
+                  <span style={{ fg: m.pal().success }}>{props.formatCost(m.totalSubCost())}</span>
+                </TuiTitleSummaryPad>
+              </Show>
+            </>
+          }
+        />
+
+        <Show when={panelOpen()}>
+          <Show
+            when={m.hasData()}
+            fallback={<TuiPanelNoData pal={m.pal()} layout={layout} message={m.t().noData} />}
+          >
+            <TuiPanelSep pal={m.pal()} layout={layout} />
+            <MainSessionView
+              m={m}
+              layout={layout}
+              detail={detail}
+              model={model}
+              formatCost={props.formatCost}
+            />
+            <Show when={m.subs().length > 0}>
+              <TuiSection
+                pal={m.pal()}
+                layout={layout}
+                open={agents.open()}
+                title={m.t().secAgents}
+                suffix={agentsSuffix()}
+                onToggle={agents.toggle}
+              >
+                <AgentsView m={m} layout={layout} formatCost={props.formatCost} />
+              </TuiSection>
+            </Show>
+          </Show>
+        </Show>
+      </TuiPanel>
+    </Show>
+  )
+}