opencode-cache-hit 0.1.0

package/docs/en/design.md

@@ -0,0 +1,228 @@
+# Design
+
+For **maintainers** of this plugin: data flow, refresh rules, and boundaries vs [opencode-visual-cache](https://www.npmjs.com/package/opencode-visual-cache). User setup: [README.md](../../README.md).
+
+## Relationship to opencode-visual-cache
+
+This is a **separate project**, not maintained by the visual-cache authors. It **borrows heavily** from [opencode-visual-cache](https://www.npmjs.com/package/opencode-visual-cache):
+
+- **Sidebar panel layout** (`src/tui-panel/`): borders, hit bar, foldable sections, theme palette mapping
+- **Layout**: main session block always visible; collapsible **Agents** section when sub-agents exist
+- **Hit rate convention**: session totals align with visual-cache’s `cache.read / (cache.read + input)` rule
+
+**Division of labor**: visual-cache focuses on **main-session context / token distribution estimates**; cache-hit focuses on **per-turn metrics, cost, and sub-agent aggregation**. Install both for a complete picture.
+
+See the [documentation index](../README.md).
+
+## Product boundary
+
+```mermaid
+flowchart TB
+  subgraph ours [opencode-cache-hit]
+    DISC[Child session discovery]
+    AGG[Per-message token/cost aggregation]
+    UI[Cache Hit sidebar]
+  end
+  subgraph ref [opencode-visual-cache reference]
+    EST[Context token estimate]
+    VCUI[Token Cache sidebar]
+  end
+  OC[OpenCode session / messages API] --> DISC
+  OC --> AGG
+  AGG --> UI
+  OC -.->|UI patterns only| EST
+  EST -.-> VCUI
+```
+
+| Role | Responsibility |
+|------|----------------|
+| **cache-hit** | Sub-agent discovery and rollup; cache, tokens, cost for main/child sessions |
+| **visual-cache** | Main-session context and estimates; not maintained in this repo |
+| **Default** | Main block + foldable **Agents** (child-session totals) |
+
+## Cost model
+
+- OpenCode: `msg.cost` accumulates assistant messages using **USD** list prices from `opencode.json`.
+- Plugin: `createCostFormatter(loadPluginConfig().cost)`; default `costUnit: USD` → `currency: CNY`, `rate: 7.2`.
+- Config file: `cache-hit.config.json` at plugin root (`load-config.ts`); defaults in `plugin-config.ts`.
+
+## Runtime architecture
+
+```mermaid
+sequenceDiagram
+  participant Slot as sidebar_content slot
+  participant Host as sidebar-host
+  participant API as OpenCode API
+  participant W as widget + metrics
+
+  Slot->>Host: sessionId, display, api
+  Host->>API: session.list → childIds
+  API-->>Host: message.updated
+  Host->>Host: refreshTick++
+  Host->>API: session.messages(sid / cid)
+  Host->>W: main, messages, subAgents
+  W->>W: aggregate / format / TuiPanel
+```
+
+### Module map
+
+| File | Role |
+|------|------|
+| `plugin.tsx` | `api.slots.register` (`order: 56`, next to visual-cache); load config |
+| `sidebar-host.tsx` | Bind `sessionId`; `mainSnap` / `mainMessages` / `subAgentList`; `refreshTick` + `message.updated` |
+| `widget.tsx` | Render panel when `sessionId` set; `noData` when empty |
+| `use-cache-hit-metrics.ts` | Hit row, trend, main block visibility |
+| `main-session-view.tsx` / `agents-view.tsx` | Business sections |
+| `cache-hit-rows.tsx` | Shared token rows in Detail |
+| `stats.ts` | Pure aggregation (no UI) |
+| `session-list.ts` | Parse `session.list`, `childSessionIdsForParent` |
+| `format-cost.ts` / `format-tokens.ts` / `format-cache-ui.ts` | Display formatting (`computeHitBarWidth` lives in `tui-panel/layout.ts`) |
+| `message-timing.ts` | SDK time fields |
+| `timeline/` | Per-call JSONL (`records` / `writer` / `collector`) |
+| `plugin-config.ts` / `load-config.ts` | Config normalization |
+
+### TUI panel framework (`src/tui-panel/`)
+
+Reusable **page** skeleton aligned with visual-cache (layout, colors, foldable sections)—no skills estimate, slash, or kv business logic.
+
+| Module | Role |
+|--------|------|
+| `layout.ts` | Column widths, `justifyRow`, `computeHitBarWidth`, separators |
+| `palette.ts` | Theme → panel palette |
+| `use-panel-layout.ts` | `createPanelLayout`, `createSectionFold` |
+| `components.tsx` | `TuiPanel`, `TuiHitRow`, `TuiMetricRow`, … (`@opentui/solid`) |
+| `index.ts` | Barrel export |
+
+Import `layout.ts` / `palette.ts` directly from non-JSX code (e.g. `use-cache-hit-metrics`) so `bun test` smoke tests do not pull JSX.
+
+See [src/tui-panel/README.md](../../src/tui-panel/README.md) · [中文](../../src/tui-panel/README.zh-CN.md).
+
+## Sub-agent discovery
+
+Implementation: `src/child-session-sync.ts` (used by `sidebar-host`).
+
+```mermaid
+flowchart TD
+  A[sessionId changes] --> B[resetForParentChange]
+  B --> C[loadChildren: session.list]
+  E[message.updated any session] --> R[refreshTick++]
+  E --> F{sessionID !== parent?}
+  F -->|yes| G[debounce 200ms]
+  G --> C2[loadChildren overwrites childIds]
+  F -->|no| R
+  C --> H[childSessionIdsForParent]
+  C2 --> H
+  H --> I[re-read messages + aggregate]
+```
+
+- **Single source of truth**: `childIds` always **replaced** from `session.list` (no `session.get` append).
+- **Races**: `listGen` increments on parent change; callbacks check generation and `parentId`.
+- **Streaming**: foreign-session `message.updated` is debounced (`CHILD_LIST_DEBOUNCE_MS` = 200ms).
+- **Depth**: direct children only (`parentID === sid`); nested sub-agents are future work.
+- **Data**: `messages(cid)` → `aggregateSessionFromMessages`; entries without stats are filtered out.
+
+### Agents block semantics
+
+| Scope | Included in Agents total? |
+|-------|-------------------------|
+| Each child session’s assistant messages | Yes (`aggregateSubAgents`) |
+| Main session assistant messages | **No** (still in `mainSnap` when hidden in UI) |
+
+The UI shows `agentsScopeHint` (“sub-sessions only”). This complements visual-cache’s main-session view—it is not a missing-aggregation bug.
+
+## Aggregation and refresh
+
+### When values recompute
+
+| Data | Trigger |
+|------|---------|
+| Main snapshot | `createMemo` reads `refreshTick` + `messages(sid)` |
+| Main messages (Hit trend) | Same |
+| Sub-agent content | `childIds` or `refreshTick` → re-read each `messages(cid)` |
+| Sub-agent ids | `session.list` callback / debounced refresh on foreign activity |
+
+`sidebar-host` subscribes to `message.updated` and bumps `refreshTick` so streaming token updates always recompute.
+
+### Accumulation rules
+
+- Every `role === assistant` message in the session is included—not only the last turn.
+- Streaming updates the same message’s `tokens` repeatedly.
+- `reasoning` tokens are **excluded** from hit-rate denominator.
+- `summary: true`: skipped in `computePerCallHitTrend`; **not** yet excluded in `aggregateSessionFromMessages`.
+
+### Sidebar visibility
+
+```mermaid
+flowchart TD
+  S{sessionId set?}
+  S -->|no| H[no panel]
+  S -->|yes| P[TuiPanel]
+  P --> D{hasData?}
+  D -->|no| ND[noData]
+  D -->|yes| MAIN[Main / Detail / Model]
+  D -->|has subs| AG[Agents (foldable)]
+```
+
+| Concept | Implementation |
+|---------|----------------|
+| Whole panel | `widget.tsx`: `Show when={sessionId().length > 0}` |
+| Has data | `mainSessionHasStats(main) \|\| subs.length > 0` |
+| Main **block** | Always rendered |
+| **Agents** | Shown when `subs.length > 0`; foldable |
+
+## Hit rate (current)
+
+**Session total (Total Hit, aligned with visual-cache)**
+
+```
+Sum input and cache.read over assistant messages
+→ cacheRead / (cacheRead + input)
+```
+
+**Header Hit (per-turn + trend)**
+
+- `computePerCallHitTrend`: one rate per assistant turn; skip `summary: true`.
+- Display the **last** non-summary turn; compare to previous for ↑ / ↓ / `-`.
+
+**Combined Hit**
+
+- Shown only when main block is visible, sub-agents exist, and combined vs session total differs by ≥ 0.05%.
+
+## Time fields (OpenCode SDK v2)
+
+| Source | Field | Notes |
+|--------|-------|-------|
+| `AssistantMessage` | `time.created` | ms epoch |
+| `AssistantMessage` | `time.completed?` | end of LLM turn; often missing while streaming |
+| `ReasoningPart` | `time.start` / `time.end?` | thought segments |
+| `ToolStateCompleted` | `time.start` / `time.end` | tool run |
+| `StepFinishPart` | (no time) | tokens/cost; time falls back to message |
+
+**Per-call JSONL (Phase 1, default off)**: one row per assistant turn; daily file under `logs/`. See **[timeline.md](./timeline.md)** § Storage, § Rotation and retention.
+
+## Testing
+
+| Layer | Files | Purpose |
+|-------|-------|---------|
+| Unit | `tests/*.test.ts` | `stats`, `format-*`, layout, timeline |
+| Smoke | `tests/module-load.test.ts` | Real import graph |
+| Runtime | OpenCode logs | JSX / peer load errors |
+
+After moving exports: `rg` + `bun test`.
+
+## Roadmap (not implemented)
+
+| Item | Notes | Doc |
+|------|-------|-----|
+| Per-call JSONL | **Phase 1 done** (`src/timeline/`, default off) | [timeline.md](./timeline.md) |
+| Metric modes | Session / last N / sliding window | timeline.md § Phase 3 |
+| Sub-agents | Recursive children, filter by agent type | timeline.md § Risks |
+
+Timeline writes must stay async and non-blocking (see timeline.md).
+
+## Plugin cache
+
+| Install | After code change |
+|---------|-------------------|
+| Local path | Restart OpenCode |
+| npm package | Restart; clear `~/.cache/opencode/packages/opencode-cache-hit@latest` if needed |

package/docs/en/timeline.md

@@ -0,0 +1,253 @@
+# Timeline / per-call JSONL
+
+For developers. Sidebar aggregation: [design.md](./design.md). User guide: [README.md](../../README.md).
+
+**Phase 1 (JSONL on disk) is implemented**; default `timeline.enabled: false`. Phase 2 sidebar Timeline section and Phase 3 metric modes are not done.
+
+## Goals and non-goals
+
+| Goals | Non-goals |
+|-------|-----------|
+| Inspect each assistant call’s tokens / cache / cost / hit % over time | Replace OpenCode platform logs (`~/.local/share/opencode/log`) |
+| Distinguish main vs child sessions | Spam the TUI with `console.log` |
+| Local JSONL for `jq` / scripts | Cloud upload or team sharing |
+| Same rules as `stats.ts` (including `summary` skip) | SQLite, charts, or recursive sub-agents in v1 |
+
+## Core concept
+
+**One timeline event = one billable assistant turn**, same source as the sidebar **Hit** row—not tool parts or user messages.
+
+```mermaid
+flowchart LR
+  MSG[AssistantMessage] --> REC[LlmCallRecord]
+  REC --> MEM[in-memory ring last N]
+  REC --> JSONL[JSONL append]
+  MEM --> UI[sidebar Timeline section optional]
+```
+
+| Field | Source |
+|-------|--------|
+| Sort key | `time.completed ?? time.created` (`timingFromAssistantMessage`) |
+| Hit trend eligibility | `summary !== true` and `input + cache.read > 0` |
+| Session totals | `aggregateSessionFromMessages` (may later skip `summary` too) |
+
+## Data model
+
+```typescript
+export type LlmCallRecord = {
+  schema: 1
+  recordedAt: number       // local write time (ms)
+  sessionId: string
+  rootSessionId: string    // main session; differs for child scope
+  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   // compaction / summary
+}
+```
+
+**`messageKey` (dedupe)**
+
+1. Prefer `message.id` / `messageID`.
+2. Fallback: `${sessionId}:${created}:${modelID ?? ""}`.
+
+**Streaming**
+
+- In-memory map keyed by `messageKey` is overwritten on each build.
+- **Disk**: append when `isComplete === true` unless `flushIncomplete: true`.
+
+## Building records
+
+Module: `src/timeline/records.ts` — `buildCallRecords(sessionId, rootSessionId, scope, messages)`.
+
+- Only `role === assistant`.
+- `skippedForHit = msg.summary === true`.
+- `hitPercent` matches `computePerCallHitTrend` per message.
+- Children: `buildCallRecords(cid, rootSid, "child", …)` merged and sorted by `completedAt ?? created`.
+
+## Storage
+
+**Default layout**
+
+```
+~/.config/opencode/plugins/opencode-cache-hit/logs/
+  timeline-2026-05-31.jsonl       # one active file per local calendar day
+  timeline-2026-05-31.jsonl.1     # size rotation backup for that day
+```
+
+All main and child sessions for a day share one file; filter by `rootSessionId` / `sessionId` / `scope`. A new date gets a new filename at midnight.
+
+Optional `dir` (e.g. `~/.local/share/opencode/cache-hit/logs/`).
+
+**Legacy**: older builds used `<rootSessionId>.jsonl` per main session; not migrated automatically.
+
+**Config** (`cache-hit.config.json` → `timeline`):
+
+```json
+{
+  "timeline": {
+    "enabled": false,
+    "dir": "",
+    "flushIncomplete": false,
+    "logSummaryMessages": true,
+    "maxMemoryRows": 50,
+    "maxLinesPerFile": 100000,
+    "rotateMaxBytes": 16777216,
+    "retainRotated": 5,
+    "maxAgeDays": 30,
+    "maxLogFiles": 20
+  }
+}
+```
+
+Example values above; code defaults below (`enabled: false`, rotation `0` except `retainRotated: 5`).
+
+| Field | Code default | Description |
+|-------|--------------|-------------|
+| `enabled` | `false` | No IO when off |
+| `dir` | `""` | Empty → plugin `logs/` |
+| `flushIncomplete` | `false` | Write only completed turns |
+| `logSummaryMessages` | `true` | Include summary rows (flagged) |
+| `maxMemoryRows` | `50` | In-memory rows for future UI |
+| `maxLinesPerFile` | `0` | Trim active file to last N lines (`0` = off) |
+| `rotateMaxBytes` | `0` | Size roll to `.jsonl.1` (`0` = off) |
+| `retainRotated` | `5` | Same-day backup files to keep (not counting active) |
+| `maxAgeDays` | `0` | On collector start: delete files older than N days (mtime) |
+| `maxLogFiles` | `0` | Cap total `timeline-*.jsonl*` files (each `.1` counts) |
+
+**Write pipeline** (`writer.ts` + `rotation.ts`)
+
+1. Optional size roll **before** append.
+2. `appendFile` one JSON line.
+3. Optional line trim **after** append.
+4. Async flush in `queueMicrotask`; `flushedKeys` dedupe by `messageKey` (not cleared on session switch; cleared on date change).
+
+## Rotation and retention
+
+### Same-day size rotation (`rotateMaxBytes` + `retainRotated`)
+
+Before each append, if the active file ≥ threshold:
+
+```
+active (full)  →  rename  →  .1
+old .1         →  rename  →  .2
+old .N         →  delete when at retainRotated and rolling again
+new empty active file, then append
+```
+
+| `retainRotated` | Approx. max per day |
+|-----------------|---------------------|
+| `5` (default / example) | active + `.1`…`.5` ≈ 6× `rotateMaxBytes` |
+| `1` | active + `.1` ≈ 2× |
+| `0` | delete active file on roll, no backup |
+
+Oldest backup is **deleted** on further rolls; data is gone permanently.
+
+### Line cap (`maxLinesPerFile`)
+
+Rewrites the **active** file in place; dropped lines are **not** moved to `.1`. With ~500 B/line records, **16MB size roll usually happens before 100k lines**.
+
+### Directory cleanup (once per collector start)
+
+1. `maxAgeDays`: delete `timeline-*.jsonl*` with mtime older than N days.
+2. `maxLogFiles`: if still over cap, delete **earliest logs first**: oldest **date in filename**, then highest backup index (`.5` before `.1` before active); mtime only as tie-breaker.
+
+Does **not** match legacy `ses_*.jsonl` names.
+
+### Cross-day
+
+New filename after midnight; previous days remain until cleanup runs.
+
+### Dedup and session switch
+
+- One append per `messageKey` per process (`flushedKeys`).
+- Switching main session: same day file; filter by `rootSessionId`.
+- **Restart** clears `flushedKeys`; completed messages may be written again (no persistent dedupe yet).
+
+## Runtime wiring
+
+```mermaid
+sequenceDiagram
+  participant E as message.updated
+  participant H as sidebar-host
+  participant B as timeline/build
+  participant W as timeline/writer
+
+  E->>H: refreshTick++
+  H->>B: debounce 500ms buildCallRecords
+  alt enabled and complete and not flushed
+    B->>W: append JSONL
+  end
+```
+
+- Child ids from `child-session-sync` / `session.list`; timeline only reads `messages()`.
+- Debounce 500ms when enabled.
+- Scope: current TUI root session + its children.
+
+## UI phases
+
+### Phase 1 — disk only (current)
+
+```bash
+LOG=~/.config/opencode/plugins/opencode-cache-hit/logs/timeline-$(date +%Y-%m-%d).jsonl
+tail -f "$LOG"
+jq -r 'select(.rootSessionId=="YOUR_ROOT") | [.created,.scope,.hitPercent,.cost]|@tsv' "$LOG"
+```
+
+**Charts (optional scripts)** — see [scripts/README.md](../../scripts/README.md):
+
+```bash
+# one-liner: call count + average hit %
+python3 -c "import json,sys; r=[json.loads(x) for x in open(sys.argv[1]) if x.strip()]; h=[x['hitPercent'] for x in r if x.get('hitPercent') is not None]; print(f\"{len(r)} calls, avg hit {sum(h)/len(h):.1f}%\")" "$LOG"
+
+bun scripts/plot-hit-rate.ts "$LOG" -o /tmp/hit.svg
+bun scripts/plot-hit-rate.ts "$LOG" --by-root -o /tmp/hit-multi.svg
+```
+
+### Phase 2 — sidebar Timeline section (planned)
+
+### Phase 3 — metric window linkage (planned)
+
+## Module map
+
+| Module | Role |
+|--------|------|
+| `message-timing.ts` | `created` / `completed` |
+| `stats.ts` | shared per-message hit % |
+| `sidebar-host.tsx` | `createTimelineCollector` |
+| `plugin.tsx` | reads config |
+
+## Tests
+
+| Case | File |
+|------|------|
+| `buildCallRecords` | `tests/timeline-records.test.ts` |
+| writer / rotation / purge | `tests/timeline-writer.test.ts`, `timeline-rotation.test.ts` |
+| collector | `tests/timeline-collector.test.ts` |
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Too many writes while streaming | `isComplete` only; debounce |
+| No stable message id | synthetic `messageKey` |
+| Nested sub-agents | flat `child` scope only in v1 |
+| Disk growth | rotation + age + file count caps |
+| SDK changes | `schema: 1` |
+
+## Example line
+
+```json
+{"schema":1,"recordedAt":1717000000000,"sessionId":"sess_main","rootSessionId":"sess_main","scope":"main","messageKey":"sess_main:1716999990000:deepseek/v4","modelId":"deepseek/v4","created":1716999990000,"completedAt":1717000000000,"durationMs":10000,"isComplete":true,"input":1200,"output":80,"reasoning":0,"cacheRead":38000,"cacheWrite":0,"cost":0.012,"hitPercent":96.9,"skippedForHit":false}
+```