opencode-cache-hit 0.1.0

package/src/timeline/records.ts

@@ -0,0 +1,73 @@
+import { timingFromAssistantMessage } from "../message-timing.ts"
+import { perMessageHitPercent } from "../stats.ts"
+import type { AssistantMessage } from "../types.ts"
+import type { LlmCallRecord } from "./types.ts"
+
+export function messageKeyFor(msg: AssistantMessage, sessionId: string): string {
+  const id = msg.id ?? msg.messageID
+  if (typeof id === "string" && id.length > 0) return `${sessionId}:${id}`
+  const created = msg.time?.created ?? 0
+  return `${sessionId}:${created}:${msg.modelID ?? ""}`
+}
+
+export function sortKeyForRecord(r: LlmCallRecord): number {
+  return r.completedAt ?? r.created
+}
+
+export function assistantMessageToRecord(
+  msg: AssistantMessage,
+  sessionId: string,
+  rootSessionId: string,
+  scope: "main" | "child",
+  recordedAt: number,
+): LlmCallRecord | null {
+  if (msg.role !== "assistant") return null
+  const timing = timingFromAssistantMessage(msg)
+  if (!timing) return null
+  const t = msg.tokens ?? {}
+  const skippedForHit = msg.summary === true
+  return {
+    schema: 1,
+    recordedAt,
+    sessionId,
+    rootSessionId,
+    scope,
+    messageKey: messageKeyFor(msg, sessionId),
+    modelId: msg.modelID ?? "",
+    created: timing.created,
+    completedAt: timing.completedAt,
+    durationMs: timing.durationMs,
+    isComplete: timing.isComplete,
+    input: t.input ?? 0,
+    output: t.output ?? 0,
+    reasoning: t.reasoning ?? 0,
+    cacheRead: t.cache?.read ?? 0,
+    cacheWrite: t.cache?.write ?? 0,
+    cost: msg.cost ?? 0,
+    hitPercent: perMessageHitPercent(msg),
+    skippedForHit,
+  }
+}
+
+export function buildCallRecords(
+  sessionId: string,
+  rootSessionId: string,
+  scope: "main" | "child",
+  messages: readonly AssistantMessage[],
+  opts?: { logSummaryMessages?: boolean; recordedAt?: number },
+): LlmCallRecord[] {
+  const now = opts?.recordedAt ?? Date.now()
+  const logSummary = opts?.logSummaryMessages !== false
+  const out: LlmCallRecord[] = []
+  for (const msg of messages) {
+    if (!logSummary && msg.summary === true) continue
+    const rec = assistantMessageToRecord(msg, sessionId, rootSessionId, scope, now)
+    if (rec) out.push(rec)
+  }
+  return out
+}
+
+export function mergeAndSortRecords(chunks: readonly LlmCallRecord[][]): LlmCallRecord[] {
+  const all = chunks.flat()
+  return all.sort((a, b) => sortKeyForRecord(a) - sortKeyForRecord(b))
+}

package/src/timeline/rotation.ts

@@ -0,0 +1,47 @@
+import { readFile, rename, stat, unlink, writeFile } from "node:fs/promises"
+
+/** Keep only the last `maxLines` non-empty lines (in-place rewrite). */
+export async function trimFileToMaxLines(logPath: string, maxLines: number): Promise<void> {
+  if (maxLines <= 0) return
+  let text: string
+  try {
+    text = await readFile(logPath, "utf8")
+  } catch {
+    return
+  }
+  const lines = text.split("\n").filter((line) => line.length > 0)
+  if (lines.length <= maxLines) return
+  await writeFile(logPath, lines.slice(-maxLines).join("\n") + "\n", "utf8")
+}
+
+/**
+ * Size-based roll: `file` → `file.1` → `file.2` … keep at most `retainRotated` backups.
+ * Current active file is removed by rename; caller appends to a new empty `file`.
+ */
+export async function rotateFileBySize(
+  logPath: string,
+  maxBytes: number,
+  retainRotated: number,
+): Promise<void> {
+  if (maxBytes <= 0) return
+  let size = 0
+  try {
+    size = (await stat(logPath)).size
+  } catch {
+    return
+  }
+  if (size < maxBytes) return
+
+  const retain = Math.max(0, Math.floor(retainRotated))
+  if (retain === 0) {
+    await unlink(logPath).catch(() => {})
+    return
+  }
+
+  const oldest = `${logPath}.${retain}`
+  await unlink(oldest).catch(() => {})
+  for (let i = retain - 1; i >= 1; i--) {
+    await rename(`${logPath}.${i}`, `${logPath}.${i + 1}`).catch(() => {})
+  }
+  await rename(logPath, `${logPath}.1`)
+}

package/src/timeline/types.ts

@@ -0,0 +1,22 @@
+/** Single LLM call row (one JSONL line). */
+export type LlmCallRecord = {
+  schema: 1
+  recordedAt: number
+  sessionId: string
+  rootSessionId: string
+  scope: "main" | "child"
+  messageKey: string
+  modelId: string
+  created: number
+  completedAt?: number
+  durationMs?: number
+  isComplete: boolean
+  input: number
+  output: number
+  reasoning: number
+  cacheRead: number
+  cacheWrite: number
+  cost: number
+  hitPercent: number | null
+  skippedForHit: boolean
+}

package/src/timeline/writer.ts

@@ -0,0 +1,134 @@
+import { appendFile, mkdir, readdir, stat, unlink } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import type { TimelineConfig } from "../plugin-config.ts"
+import { PLUGIN_ROOT } from "../load-config.ts"
+import type { LlmCallRecord } from "./types.ts"
+import { rotateFileBySize, trimFileToMaxLines } from "./rotation.ts"
+
+export const DEFAULT_TIMELINE_DIR = join(PLUGIN_ROOT, "logs")
+export const TIMELINE_FILE_PREFIX = "timeline"
+
+export type TimelineWriteOptions = Pick<
+  TimelineConfig,
+  "maxLinesPerFile" | "rotateMaxBytes" | "retainRotated"
+>
+
+export function resolveTimelineDir(config: TimelineConfig): string {
+  const raw = config.dir?.trim()
+  return raw.length > 0 ? raw : DEFAULT_TIMELINE_DIR
+}
+
+/** Local calendar day `YYYY-MM-DD` for daily log files. */
+export function localDateKey(ms = Date.now()): string {
+  const d = new Date(ms)
+  const y = d.getFullYear()
+  const m = String(d.getMonth() + 1).padStart(2, "0")
+  const day = String(d.getDate()).padStart(2, "0")
+  return `${y}-${m}-${day}`
+}
+
+/** Active daily log: `logs/timeline-2026-05-31.jsonl`; rolls to `.jsonl.1` when over size. */
+export function timelineDailyLogPath(logsDir: string, dateKey: string): string {
+  return join(logsDir, `${TIMELINE_FILE_PREFIX}-${dateKey}.jsonl`)
+}
+
+export function serializeRecord(record: LlmCallRecord): string {
+  return JSON.stringify(record) + "\n"
+}
+
+const TIMELINE_FILE_RE = /^timeline-\d{4}-\d{2}-\d{2}\.jsonl(\.\d+)?$/
+
+/** Parsed daily log name: `roll` 0 = active file, `.1`…`.N` = older backups. */
+export function parseTimelineLogBasename(name: string): { dateKey: string; roll: number } | null {
+  const m = /^timeline-(\d{4}-\d{2}-\d{2})\.jsonl(?:\.(\d+))?$/.exec(name)
+  if (!m) return null
+  return { dateKey: m[1], roll: m[2] ? Number.parseInt(m[2], 10) : 0 }
+}
+
+/** Sort key for purge: oldest calendar day first, then highest backup index. */
+export function compareTimelineLogsForPurge(aPath: string, bPath: string): number {
+  const a = parseTimelineLogBasename(aPath.split(/[/\\]/).pop() ?? "")
+  const b = parseTimelineLogBasename(bPath.split(/[/\\]/).pop() ?? "")
+  if (!a || !b) return 0
+  if (a.dateKey !== b.dateKey) return a.dateKey.localeCompare(b.dateKey)
+  return b.roll - a.roll
+}
+
+async function listTimelineLogFiles(logsDir: string): Promise<{ path: string; mtimeMs: number }[]> {
+  let names: string[]
+  try {
+    names = await readdir(logsDir)
+  } catch {
+    return []
+  }
+  const entries: { path: string; mtimeMs: number }[] = []
+  for (const name of names) {
+    if (!TIMELINE_FILE_RE.test(name)) continue
+    const path = join(logsDir, name)
+    try {
+      entries.push({ path, mtimeMs: (await stat(path)).mtimeMs })
+    } catch {
+      /* ignore */
+    }
+  }
+  return entries
+}
+
+/** Delete `timeline-*.jsonl*` older than `maxAgeDays` (by mtime). */
+export async function purgeTimelineLogsOlderThan(
+  logsDir: string,
+  maxAgeDays: number,
+): Promise<void> {
+  if (maxAgeDays <= 0) return
+  const cutoff = Date.now() - maxAgeDays * 86_400_000
+  for (const { path, mtimeMs } of await listTimelineLogFiles(logsDir)) {
+    if (mtimeMs < cutoff) await unlink(path).catch(() => {})
+  }
+}
+
+/** Keep at most `maxLogFiles` timeline files; delete earliest logs (date, then backup roll). */
+export async function purgeTimelineLogsOverCount(
+  logsDir: string,
+  maxLogFiles: number,
+): Promise<void> {
+  if (maxLogFiles <= 0) return
+  const entries = await listTimelineLogFiles(logsDir)
+  if (entries.length <= maxLogFiles) return
+  entries.sort((a, b) => {
+    const byLog = compareTimelineLogsForPurge(a.path, b.path)
+    if (byLog !== 0) return byLog
+    return a.mtimeMs - b.mtimeMs
+  })
+  const remove = entries.length - maxLogFiles
+  for (let i = 0; i < remove; i++) {
+    await unlink(entries[i].path).catch(() => {})
+  }
+}
+
+/** Age purge first, then enforce total file cap. */
+export async function purgeTimelineLogDir(
+  logsDir: string,
+  opts: { maxAgeDays: number; maxLogFiles: number },
+): Promise<void> {
+  await purgeTimelineLogsOlderThan(logsDir, opts.maxAgeDays)
+  await purgeTimelineLogsOverCount(logsDir, opts.maxLogFiles)
+}
+
+export async function appendTimelineRecord(
+  logPath: string,
+  record: LlmCallRecord,
+  rotation?: TimelineWriteOptions,
+): Promise<void> {
+  await mkdir(dirname(logPath), { recursive: true })
+  const maxLines = rotation?.maxLinesPerFile ?? 0
+  const maxBytes = rotation?.rotateMaxBytes ?? 0
+  const retain = rotation?.retainRotated ?? 5
+
+  if (maxBytes > 0) {
+    await rotateFileBySize(logPath, maxBytes, retain)
+  }
+  await appendFile(logPath, serializeRecord(record), "utf8")
+  if (maxLines > 0) {
+    await trimFileToMaxLines(logPath, maxLines)
+  }
+}

package/src/tui-panel/README.md

@@ -0,0 +1,78 @@
+# TUI panel framework
+
+Reusable OpenCode **sidebar panel** layout (borders, foldable sections, hit bar, theme palette). Inspired by [opencode-visual-cache](https://www.npmjs.com/package/opencode-visual-cache) page structure—no skills, slash commands, or `api.kv` logic.
+
+[中文](README.zh-CN.md) · Design context: [docs/en/design.md](../../docs/en/design.md) § TUI panel framework.
+
+## Quick example
+
+```tsx
+/** @jsxImportSource @opentui/solid */
+import { createMemo, createSignal, Show } from "solid-js"
+import {
+  buildPanelPalette,
+  createPanelLayout,
+  createSectionFold,
+  TuiMetricRow,
+  TuiPanel,
+  TuiPanelNoData,
+  TuiPanelSep,
+  TuiPanelTitle,
+  TuiSection,
+} from "./tui-panel/index.ts"
+
+export function MySidebar(props: { theme: Record<string, unknown> }) {
+  const pal = createMemo(() => buildPanelPalette(props.theme))
+  const [open, setOpen] = createSignal(true)
+  const detail = createSectionFold(true)
+  const layout = createPanelLayout({ border: () => true })
+  const hasData = () => true
+
+  return (
+    <TuiPanel pal={pal()} border layout={layout}>
+      <TuiPanelTitle
+        pal={pal()}
+        layout={layout}
+        open={open()}
+        onToggle={() => setOpen((o) => !o)}
+        title="My Panel"
+        version="0.1.0"
+      />
+      <Show when={open()}>
+        <Show
+          when={hasData()}
+          fallback={<TuiPanelNoData pal={pal()} layout={layout} message="No data..." />}
+        >
+          <TuiPanelSep pal={pal()} layout={layout} />
+          <TuiSection
+            pal={pal()}
+            layout={layout}
+            open={detail.open()}
+            title="Detail"
+            onToggle={detail.toggle}
+          >
+            <TuiMetricRow pal={pal()} layout={layout} label="Count:" value="42" />
+          </TuiSection>
+        </Show>
+      </Show>
+    </TuiPanel>
+  )
+}
+```
+
+## API
+
+| Export | Role |
+|--------|------|
+| `createPanelLayout` | Width from `onSizeChange`; `gauge`, `row()`, `sep` |
+| `createSectionFold` | Section open/closed state |
+| `TuiPanel` | Outer border + padding |
+| `TuiPanelTitle` | Foldable title; optional `collapsed` summary |
+| `TuiSection` | `▼` section header + separator fill |
+| `TuiMetricRow` | Label left, value (+ unit) right |
+| `TuiHitRow` | Hit bar + % + trend |
+| `computeHitBarWidth` | Dynamic bar width |
+
+Keep business data, i18n, and stats in your plugin modules; use this package for layout only.
+
+Import `layout.ts` / `palette.ts` directly in tests to avoid pulling JSX through `index.ts`.

package/src/tui-panel/README.zh-CN.md

@@ -0,0 +1,76 @@
+# TUI 面板框架
+
+OpenCode **侧边栏面板**可复用布局（边框、折叠段、命中率条、主题调色板）。页面结构对齐 [opencode-visual-cache](https://www.npmjs.com/package/opencode-visual-cache)，**不含** skills、斜杠命令、`api.kv` 等业务。
+
+[English](README.md) · 设计背景：[docs/zh-CN/design.md](../../docs/zh-CN/design.md) § TUI 面板框架。
+
+## 快速用法
+
+```tsx
+/** @jsxImportSource @opentui/solid */
+import { createMemo, createSignal, Show } from "solid-js"
+import {
+  buildPanelPalette,
+  createPanelLayout,
+  createSectionFold,
+  TuiMetricRow,
+  TuiPanel,
+  TuiPanelNoData,
+  TuiPanelSep,
+  TuiPanelTitle,
+  TuiSection,
+} from "./tui-panel/index.ts"
+
+export function MySidebar(props: { theme: Record<string, unknown> }) {
+  const pal = createMemo(() => buildPanelPalette(props.theme))
+  const [open, setOpen] = createSignal(true)
+  const detail = createSectionFold(true)
+  const layout = createPanelLayout({ border: () => true })
+  const hasData = () => true
+
+  return (
+    <TuiPanel pal={pal()} border layout={layout}>
+      <TuiPanelTitle
+        pal={pal()}
+        layout={layout}
+        open={open()}
+        onToggle={() => setOpen((o) => !o)}
+        title="My Panel"
+        version="0.1.0"
+      />
+      <Show when={open()}>
+        <Show
+          when={hasData()}
+          fallback={<TuiPanelNoData pal={pal()} layout={layout} message="No data..." />}
+        >
+          <TuiPanelSep pal={pal()} layout={layout} />
+          <TuiSection
+            pal={pal()}
+            layout={layout}
+            open={detail.open()}
+            title="Detail"
+            onToggle={detail.toggle}
+          >
+            <TuiMetricRow pal={pal()} layout={layout} label="Count:" value="42" />
+          </TuiSection>
+        </Show>
+      </Show>
+    </TuiPanel>
+  )
+}
+```
+
+## API
+
+| 导出 | 说明 |
+|------|------|
+| `createPanelLayout` | `onSizeChange` 测宽；`gauge`、`row()`、`sep` |
+| `createSectionFold` | 区块折叠状态 |
+| `TuiPanel` | 外框 + padding |
+| `TuiPanelTitle` | 可折叠标题；可选 `collapsed` 摘要 |
+| `TuiSection` | `▼` 区块标题 + 分隔线填充 |
+| `TuiMetricRow` | 左标签右数值（可选 unit） |
+| `TuiHitRow` | Hit 条 + % + 趋势 |
+| `computeHitBarWidth` | 动态进度条宽度 |
+
+业务数据、i18n、统计逻辑放在插件自己的模块；本目录只负责页面骨架。测试里请直接 import `layout.ts` / `palette.ts`，避免经 `index.ts` 拉入 JSX。

package/src/tui-panel/components.tsx

@@ -0,0 +1,163 @@
+/** @jsxImportSource @opentui/solid */
+import { Show, type JSX } from "solid-js"
+import { padBeforeTitleSummary, sepAfterPrefix, visualWidth } from "./layout.ts"
+import type { PanelLayout } from "./use-panel-layout.ts"
+import type { PanelPalette } from "./palette.ts"
+
+export function TuiPanel(props: {
+  pal: PanelPalette
+  border: boolean
+  layout: PanelLayout
+  children: JSX.Element
+}) {
+  const bindRef = (el: { width?: number } | undefined) => {
+    props.layout.boxRef = el
+  }
+  return (
+    <box
+      ref={bindRef}
+      onSizeChange={props.layout.syncWidth}
+      border={props.border}
+      {...(props.border ? { borderColor: props.pal.border } : {})}
+      paddingTop={0}
+      paddingBottom={0}
+      paddingLeft={props.border ? 2 : 0}
+      paddingRight={props.border ? 2 : 0}
+      flexDirection="column"
+      gap={0}
+      width="100%"
+    >
+      {props.children}
+    </box>
+  )
+}
+
+export function TuiPanelTitle(props: {
+  pal: PanelPalette
+  layout: PanelLayout
+  open: boolean
+  onToggle: () => void
+  title: string
+  version?: string
+  collapsed?: JSX.Element
+}) {
+  return (
+    <text onMouseUp={props.onToggle}>
+      <span style={{ fg: props.pal.muted }}>{props.open ? "\u25bc " : "\u25b6 "}</span>
+      <span style={{ fg: props.pal.primary }}>
+        <b>{props.title}</b>
+        <Show when={props.open && props.version}>
+          <span style={{ fg: props.pal.muted }}> (v{props.version})</span>
+        </Show>
+      </span>
+      <Show when={!props.open && props.collapsed}>{props.collapsed}</Show>
+    </text>
+  )
+}
+
+export function TuiTitleSummaryPad(props: {
+  layout: PanelLayout
+  titleWidth: number
+  summaryWidth: number
+  children: JSX.Element
+}) {
+  const spaces = () =>
+    padBeforeTitleSummary(
+      props.layout.panelWidth(),
+      props.layout.gutter(),
+      props.titleWidth,
+      props.summaryWidth,
+    )
+  return (
+    <span>
+      {" ".repeat(spaces())}
+      {props.children}
+    </span>
+  )
+}
+
+export function TuiPanelSep(props: { pal: PanelPalette; layout: PanelLayout }) {
+  return <text fg={props.pal.muted}>{props.layout.sep()}</text>
+}
+
+export function TuiPanelNoData(props: {
+  pal: PanelPalette
+  layout: PanelLayout
+  message: string
+}) {
+  return (
+    <>
+      <TuiPanelSep pal={props.pal} layout={props.layout} />
+      <text>
+        <span style={{ fg: props.pal.muted }}>{"> "}</span>
+        <span style={{ fg: props.pal.muted }}>{props.message}</span>
+      </text>
+    </>
+  )
+}
+
+export function TuiSection(props: {
+  pal: PanelPalette
+  layout: PanelLayout
+  open: boolean
+  title: string
+  suffix?: string
+  onToggle: () => void
+  children: JSX.Element
+}) {
+  const prefix = () =>
+    `${props.open ? "\u25bc " : "\u25b6 "}${props.title}${props.suffix ?? ""}`
+  return (
+    <>
+      <text onMouseUp={props.onToggle}>
+        <span style={{ fg: props.pal.muted }}>{props.open ? "\u25bc " : "\u25b6 "}</span>
+        <span style={{ fg: props.pal.primary }}>
+          <b>{props.title}</b>
+        </span>
+        <Show when={props.suffix}>
+          <span style={{ fg: props.pal.muted }}>{props.suffix}</span>
+        </Show>
+        <span style={{ fg: props.pal.muted }}>
+          {sepAfterPrefix(prefix(), props.layout.gauge())}
+        </span>
+      </text>
+      <Show when={props.open}>{props.children}</Show>
+    </>
+  )
+}
+
+export function TuiMetricRow(props: {
+  pal: PanelPalette
+  layout: PanelLayout
+  label: string
+  value: string
+  unit?: string
+  fg?: string
+}) {
+  const fg = props.fg ?? props.pal.muted
+  return (
+    <text fg={fg}>
+      {props.layout.row(props.label, props.value, props.unit ?? "")}
+    </text>
+  )
+}
+
+export function TuiHitRow(props: {
+  label: string
+  bar: string
+  pct: string
+  barColor: string
+  textColor: string
+  trend?: { text: string; color: string }
+}) {
+  return (
+    <text>
+      <span style={{ fg: props.textColor }}>{props.label} </span>
+      <span style={{ fg: props.barColor }}>[{props.bar}] </span>
+      <span style={{ fg: props.textColor }}>{props.pct}</span>
+      <Show when={props.trend}>
+        <span style={{ fg: props.trend!.color }}> {props.trend!.text}</span>
+      </Show>
+    </text>
+  )
+}

package/src/tui-panel/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Reusable OpenCode TUI sidebar panel framework (visual-cache layout language).
+ * Domain plugins compose: TuiPanel + sections + metric rows + optional Hit row.
+ */
+
+export {
+  MIN_PANEL_WIDTH,
+  DEFAULT_PANEL_WIDTH,
+  PANEL_GUTTER,
+  HEADER_PREFIX,
+  visualWidth,
+  visualPadEnd,
+  truncateVisual,
+  justifyRow,
+  justifyEnds,
+  computeHitBarWidth,
+  separatorLine,
+  sepAfterPrefix,
+  padBeforeTitleSummary,
+} from "./layout.ts"
+
+export { buildPanelPalette, themeColorToHex, type PanelPalette } from "./palette.ts"
+
+export {
+  createPanelLayout,
+  createSectionFold,
+  type PanelLayout,
+  type PanelLayoutOptions,
+  type SectionFold,
+} from "./use-panel-layout.ts"
+
+export {
+  TuiPanel,
+  TuiPanelTitle,
+  TuiTitleSummaryPad,
+  TuiPanelSep,
+  TuiPanelNoData,
+  TuiSection,
+  TuiMetricRow,
+  TuiHitRow,
+} from "./components.tsx"