agent-cache-optimizer 0.5.4 → 0.6.0

package/CHANGELOG.md

@@ -1,41 +1,104 @@
 # Changelog
 
-## 0.4.0 — 2026-06-25
+## 0.6.0 — 2026-06-25
 
 ### Added
-- **Cache warming**: persist known-stable hashes to `warm-cache.json`; new sessions skip cold start
-- **Savings tracking**: cumulative estimated $ savings in `savings.json`, displayed in `aco status`
-- **Enhanced diag.log**: per-call stableKB + estimated $ saved + cumulative total
-- **Conversation log adapter**: append-only guidelines for maximizing cache across turns
+
+- **Model-scoped tracking**: databases and warm caches are now keyed by `provider__model__agent` instead of just agent name, enabling correct per-provider/model stability tracking across multi-model setups
+- **Block splitting v2**: robust brace-depth JSON parser handles arbitrary nesting, escaped strings, consecutive objects (not just arrays), and XML sibling elements. Markdown section splitting respects fenced code blocks. Long top-level lists (3+ items) are split into individual items.
+- **Volatile metadata detection**: cold-start heuristics now detect and cap blocks containing dynamic meta-info patterns (`currentDate`, `session ID`, `timestamp`, `last updated`, `ISO timestamp`) even when structural heuristics would otherwise boost them to stable
+- **Provider cache metrics**: real cache hit rate tracking from OpenCode provider events (`cacheReadTokens`, `cacheWriteTokens`, `cacheHitRate`) stored in `cache-metrics.json` with per-scope and total aggregation
+- **Structured event logging**: all significant events written to `events.jsonl` with content-hashed IDs for privacy-preserving observability
+- **Enhanced CLI**: `agent-cache-optimizer status` now displays cache hit rate, structured event counts, and properly handles scoped warm cache format
 
 ### Changed
-- `classify()` now accepts `warmHashes` for instant warm-state classification
-- `aco status --json` includes savings + warm cache data
-- `aco status` dashboard shows est. savings and warm cache count
+
+- **Two-tier classification**: simplified from 3 tiers (stable/unknown/dynamic) to 2 tiers (stable/dynamic) with 0.5 threshold, effectively eliminating the "unknown" bucket
+- **Warm cache v2**: upgraded format with `global` + per-scope hash sets; hashes stable across multiple scopes are promoted to global for cross-scope cache warming
+- **Warm cache durability**: hashes persist across sessions unless absent from ALL scopes (not just removed on first scope change)
+- **Content-addressable snapshot keys**: session and item IDs in cache metrics are content-hashed to avoid leaking sensitive identifiers
+- Cold-start classification now routes 0.5-score blocks to stable instead of unknown
+
+### Fixed
+
+- Cumulative savings no longer double-counted (was multiplying by observation count twice)
+- Metrics deduplication: zero-delta provider events are skipped after the first recording
+
+## 0.5.4 — 2026-06-25
+
+### Added
+
+- **Disk space management**: diag.log rotates at 50KB/1000 lines
+- **Stale hash pruning**: auto-removes hashes unseen for 7 days with count≤2
+- **VERSION const**: version logged in plugin startup message
+
+### Fixed
+
+- Migration detects missing `contentObservations` and resets cleanly
+
+## 0.5.3 — 2026-06-25
+
+### Changed
+
+- `VERSION` constant replaces hardcoded version strings
+- Migration logic simplified: full reset when `contentObservations` missing
+
+## 0.5.2 — 2026-06-25
+
+### Fixed
+
+- `contentObservations` field properly tracked (was missing after migration)
+
+## 0.5.1 — 2026-06-25
+
+### Fixed
+
+- Auto-migrate pre-0.5 DBs on load (rebuild contentIndex from positions)
+- `contentObservations` separate from `observations` for accurate content scoring
+
+## 0.5.0 — 2026-06-25
+
+### Added
+
+- **Content-addressed block matching** (Irminsul-lite): track blocks by hash regardless of position
+- `contentIndex` + `contentScores` in StabilityDB for position-independent tracking
+- `updateContentDB()` for per-call content fingerprinting
+- `lookupContentScore()` for position-independent score queries
+- Classification priority: warm cache → content score → position score → cold start
+
+### Changed
+
+- Stable block identification improved from ~1/25 to 25/25 in production
+
+## 0.4.0 — 2026-06-25
+
+### Added
+
+- **Cache warming**: persist known-stable hashes to `warm-cache.json`
+- **Savings tracking**: cumulative estimated $ savings in `savings.json`
+- **Enhanced diag.log**: per-call stableKB + estimated $ saved + cumulative total
+- **Conversation log adapter**: append-only cache optimization guidelines
 
 ## 0.2.1 — 2026-06-24
 
 ### Fixed
-- Binary renamed from `aco` to `agent-cache-optimizer` (aco was taken on npm)
+
+- Binary renamed from `aco` to `agent-cache-optimizer` (`aco` was taken on npm)
 
 ## 0.2.0 — 2026-06-24
 
 ### Added
-- `agent-cache-optimizer` CLI binary (replaces skill-based slash command)
-- `aco status` / `aco status --json` commands
+
+- `agent-cache-optimizer` CLI (replaces skill-based slash command)
+- `agent-cache-optimizer status` and `--json` commands
 
 ## 0.1.0 — 2026-06-24
 
 ### Added
 
-- **Core engine**: content-agnostic hash-based stability tracking (`core.ts`)
-- **Cold-start heuristics**: universal position/size/structure signals (`heuristics.ts`)
-- **Block splitting**: automatic splitting of >4KB blocks at JSON/Markdown/XML boundaries (`splitting.ts`)
-- **OpenCode plugin**: `experimental.chat.system.transform` hook for runtime prompt reordering
-- **Per-agent tracking**: isolated stability databases for orchestrator/oracle/fixer/etc.
-- **Diagnostics**: `chat.params` fallback logging, `diag.log` audit trail
-- **Provider headers**: automatic Anthropic `prompt-caching-2024-07-31` header via `chat.headers`
-- **Status dashboard**: `/cache-status` slash command + `cache-status.sh` CLI script
-- **Cache audit tool**: `check-cache-friendly.sh` for scanning config files
-- **Claude Code adapter**: optimization guidelines document
-- **Documentation**: bilingual README (EN + zh-CN), cross-CLI architecture docs
+- Core engine: content-agnostic hash-based stability tracking
+- Cold-start heuristics: universal position/size/structure signals
+- Block splitting for >4KB blocks at JSON/Markdown/XML boundaries
+- OpenCode plugin: `experimental.chat.system.transform` hook
+- Per-agent tracking, diagnostics, Anthropic prompt-caching header
+- Bilingual README (EN + zh-CN)

package/README.md

@@ -96,20 +96,24 @@ agent-cache-optimizer status --json    # JSON for scripts
 ║              KV Cache Optimizer Status                       ║
 ╠══════════════════════════════════════════════════════════════╣
 ║ Status:  ACTIVE                                              ║
-║ Mode:    orchestrator=WARM oracle=COLD                        ║
-║ Uptime:  2026-06-24T15:30 → 2026-06-24T16:45                ║
+║ Mode:    WARM (12 scopes, 150 observations)                  ║
+║ Uptime:  2026-06-24T15:30 → 2026-06-25T16:45                ║
+║ Structured events: 1267 jsonl records                        ║
 ╠══════════════════════════════════════════════════════════════╣
-║ Agent              Obs  Positions     Stable                 ║
-║ orchestrator        12         11      8/11                  ║
-║ oracle               3          5      3/5                   ║
+║ Scope                              Obs  Positions  Stable    ║
+║ deepseek__deepseek-chat__orch       12         25   25/25    ║
+║ deepseek__deepseek-chat__oracle      3          5    5/5     ║
 ╠══════════════════════════════════════════════════════════════╣
-║ Estimated cache reuse: ~73% of system prompt                 ║
+║ Est. savings: $1.2345 over 50 calls                         ║
+║ Warm cache: 52 stable hashes pinned (18 global + 34 scoped) ║
+║ Cache hit: 96.4% (29952/31061 input tokens)                 ║
+║ Last reorder: S:25 U:0 D:0 T:25 obs:150                     ║
 ╚══════════════════════════════════════════════════════════════╝
 ```
 
 ## 🏗 How It Works
 
-### 1. Observe (content-agnostic)
+### 1. Observe (content-addressed, position-independent)
 
 The plugin **never reads the content** of your prompts. It only hashes
 each system block and tracks which hashes stay the same vs change across calls.
@@ -126,7 +130,15 @@ After 3 observations:
   ...
 ```
 
-### 2. Classify & Reorder
+### 2. Split & Classify
+
+Large blocks (>4KB) are split at structural boundaries — JSON arrays,
+Markdown headings, XML elements, and long lists — using a robust
+brace-depth parser that handles arbitrary nesting and fenced code blocks.
+
+Cold-start heuristics detect volatile metadata patterns (`currentDate`,
+`session ID`, `timestamp`) and cap their scores to prevent structural
+boosts from misclassifying them as stable.
 
 ```
                                                                   ┌──────────┐
@@ -144,30 +156,36 @@ After 3 observations:
 
 | Phase          | Trigger                 | Method                                       |
 | -------------- | ----------------------- | -------------------------------------------- |
-| **Cold start** | First 2 calls per agent | Universal position/size/structure heuristics |
+| **Cold start** | First 2 calls per scope | Universal position/size/structure heuristics |
 | **Warm**       | 3+ calls                | Hash-based stability scores                  |
 
 The cold-start heuristics use **only** structural signals (position, size,
 delimiters, line density) — no keyword matching, no config awareness.
 This means the plugin works immediately with **any** agent setup.
 
+### 4. Provider Cache Metrics
+
+Real cache hit rates are tracked from OpenCode provider events — no
+estimation needed. `cache-metrics.json` records per-scope and
+total `cacheReadTokens`, `cacheWriteTokens`, and `cacheHitRate`.
+All session and message IDs are content-hashed for privacy.
+
 ## 📊 Benchmarks
 
 Tested on a realistic OpenCode orchestrator prompt (~25KB system prompt):
 
-| Scenario                       | Cacheable prefix | Improvement |
-| ------------------------------ | ---------------- | ----------- |
-| Original (no reorder)          | 0 KB (0%)        | —           |
-| Cold start (heuristics)        | 21.8 KB (88%)    | +88%        |
-| Warm (hash-based, 3+ sessions) | 21.8 KB (88%)    | +88%        |
+| Scenario                     | Cacheable prefix   | Improvement |
+| ---------------------------- | ------------------ | ----------- |
+| Original (no reorder)        | 0 KB (0%)          | —           |
+| Cold start (heuristics)      | 21.8 KB (88%)      | +88%        |
+| **Content-addressed (v0.5)** | **52.9 KB (100%)** | **+100%**   |
 
-**Per-agent results** (3 different agent configurations):
+**Production results** (155 observations, deepseek-v4-pro):
 
-| Agent        | Blocks | Stable | Dynamic | Cacheable |
-| ------------ | ------ | ------ | ------- | --------- |
-| orchestrator | 11     | 8      | 3       | 88%       |
-| oracle       | 6      | 3      | 3       | 88%       |
-| fixer        | 6      | 3      | 3       | 90%       |
+| Phase                        | S      | U     | D     | Stable KB   |
+| ---------------------------- | ------ | ----- | ----- | ----------- |
+| Pre-v0.5 (position-based)    | 1      | 0     | 24    | ~2 KB       |
+| **v0.5 (content-addressed)** | **25** | **0** | **0** | **52.9 KB** |
 
 ## 🔌 Supported Platforms
 
@@ -202,25 +220,29 @@ db = updateDB(db, optimized)
 ```
 agent-cache-optimizer/
 ├── src/
-│   ├── index.ts          # OpenCode plugin entry point
-│   ├── core.ts           # Hash-tracking engine (CLI-agnostic)
-│   ├── heuristics.ts     # Cold-start position/size classifiers
-│   ├── splitting.ts      # Large block splitter (>4KB)
-│   └── types.ts          # TypeScript types
+│   ├── index.ts          # OpenCode plugin entry
+│   ├── core.ts           # Content-addressed hash engine
+│   ├── heuristics.ts     # Cold-start + content classifiers
+│   ├── splitting.ts      # Large block splitter (brace-depth parser)
+│   ├── types.ts          # TypeScript types
+│   └── __tests__/        # Unit tests (vitest)
+│       ├── plugin.test.ts
+│       └── heuristics-splitting.test.ts
 ├── adapters/
-│   └── claude-code.md    # Claude Code optimization guide
+│   ├── claude-code.md    # Claude Code optimization guide
+│   └── conversation-log.md # Append-only log guidelines
 ├── bin/
 │   └── aco               # CLI: agent-cache-optimizer status
 ├── scripts/
-│   ├── cache-status.sh   # Status dashboard (legacy)
+│   ├── cache-status.sh   # Legacy status script
 │   └── check-cache-friendly.sh  # Config audit tool
 ├── docs/
-│   ├── cross-cli.md      # Cross-CLI architecture
-│   └── upstream.md       # Upstream fix recommendations
-├── README.md
-├── README.zh-CN.md       # 中文文档
-├── LICENSE               # MIT
-└── CHANGELOG.md
+│   ├── deep-research-kv-cache.md  # DeepSeek KV cache research
+│   ├── cross-cli.md               # Cross-CLI architecture
+│   └── upstream.md                # Upstream fix recommendations
+├── README.md + README.zh-CN.md
+├── CHANGELOG.md
+└── LICENSE (MIT)
 ```
 
 ## 🛠 Cache-Friendliness Audit

package/bin/aco

@@ -38,6 +38,9 @@ print(json.dumps(agents))" 2>/dev/null || echo "$agents_json")
   local diag_entries=0
   [[ -f "$CACHE_DIR/diag.log" ]] && diag_entries=$(wc -l < "$CACHE_DIR/diag.log" | tr -d ' ')
 
+  local event_entries=0
+  [[ -f "$CACHE_DIR/events.jsonl" ]] && event_entries=$(wc -l < "$CACHE_DIR/events.jsonl" | tr -d ' ')
+
   local total_obs=0
   for db in "$CACHE_DIR"/stability-*.json; do
     [[ -f "$db" ]] || continue
@@ -46,9 +49,6 @@ print(json.dumps(agents))" 2>/dev/null || echo "$agents_json")
     total_obs=$((total_obs + o))
   done
 
-  local status="no_data"
-  [[ $diag_entries -gt 0 ]] && status="active"
-
   local savings_json="{}"
   if [[ -f "$CACHE_DIR/savings.json" ]]; then
     savings_json=$(python3 -c "import json; print(json.dumps(json.load(open('$CACHE_DIR/savings.json'))))" 2>/dev/null || echo "{}")
@@ -56,7 +56,29 @@ print(json.dumps(agents))" 2>/dev/null || echo "$agents_json")
 
   local warm_count=0
   if [[ -f "$CACHE_DIR/warm-cache.json" ]]; then
-    warm_count=$(python3 -c "import json; print(len(json.load(open('$CACHE_DIR/warm-cache.json'))))" 2>/dev/null || echo 0)
+    warm_count=$(python3 -c "
+import json
+d=json.load(open('$CACHE_DIR/warm-cache.json'))
+hashes=set(d if isinstance(d, list) else d.get('global', []))
+if isinstance(d, dict):
+    for values in d.get('scopes', {}).values():
+        hashes.update(values)
+print(len(hashes))" 2>/dev/null || echo 0)
+  fi
+
+  local cache_metrics_json="{}"
+  if [[ -f "$CACHE_DIR/cache-metrics.json" ]]; then
+    cache_metrics_json=$(python3 -c "import json; print(json.dumps(json.load(open('$CACHE_DIR/cache-metrics.json'))))" 2>/dev/null || echo "{}")
+  fi
+
+  local metric_events=0
+  if [[ -f "$CACHE_DIR/cache-metrics.json" ]]; then
+    metric_events=$(python3 -c "import json; print(json.load(open('$CACHE_DIR/cache-metrics.json')).get('total', {}).get('events', 0))" 2>/dev/null || echo 0)
+  fi
+
+  local status="no_data"
+  if [[ $diag_entries -gt 0 || $total_obs -gt 0 || $metric_events -gt 0 ]]; then
+    status="active"
   fi
 
   python3 -c "
@@ -64,10 +86,12 @@ import json
 print(json.dumps({
   'status': '$status',
   'diag_entries': $diag_entries,
+  'event_entries': $event_entries,
   'total_observations': $total_obs,
   'agents': $agents_json,
   'savings': $savings_json,
-  'warm_cache_hashes': $warm_count
+  'warm_cache_hashes': $warm_count,
+  'cache_metrics': $cache_metrics_json
 }, indent=2))"
 }
 
@@ -98,6 +122,9 @@ status_text() {
     last_ts=$(tail -1 "$CACHE_DIR/diag.log" | grep -oP '^\[[^\]]+\]' | tr -d '[]' 2>/dev/null || echo "?")
   fi
 
+  local event_entries=0
+  [[ -f "$CACHE_DIR/events.jsonl" ]] && event_entries=$(wc -l < "$CACHE_DIR/events.jsonl" | tr -d ' ')
+
   echo ""
   echo -e "${BOLD}╔══════════════════════════════════════════════════════╗${NC}"
   echo -e "${BOLD}║           agent-cache-optimizer Status               ║${NC}"
@@ -112,6 +139,10 @@ status_text() {
 
   echo -e "${BOLD}╠══════════════════════════════════════════════════════╣${NC}"
 
+  if [[ $event_entries -gt 0 ]]; then
+    printf "║ ${CYAN}Structured events: ${event_entries} jsonl records${NC}                  ║\n"
+  fi
+
   if [[ $agent_count -eq 0 ]]; then
     echo -e "║ ${YELLOW}No per-agent data yet${NC}                                    ║"
   else
@@ -155,10 +186,34 @@ print(d.get('totalObservations', 0))" 2>/dev/null || echo "0")
   # Warm cache
   if [[ -f "$CACHE_DIR/warm-cache.json" ]]; then
     local warm_count
-    warm_count=$(python3 -c "import json; print(len(json.load(open('$CACHE_DIR/warm-cache.json'))))" 2>/dev/null || echo "0")
+    warm_count=$(python3 -c "
+import json
+d=json.load(open('$CACHE_DIR/warm-cache.json'))
+hashes=set(d if isinstance(d, list) else d.get('global', []))
+if isinstance(d, dict):
+    for values in d.get('scopes', {}).values():
+        hashes.update(values)
+print(len(hashes))" 2>/dev/null || echo "0")
     printf "║ ${CYAN}Warm cache: ${warm_count} stable hashes pinned${NC}                      ║\n"
   fi
 
+  # Real provider cache metrics from OpenCode events
+  if [[ -f "$CACHE_DIR/cache-metrics.json" ]]; then
+    local metrics_line
+    metrics_line=$(python3 -c "
+import json
+d=json.load(open('$CACHE_DIR/cache-metrics.json')).get('total', {})
+read=int(d.get('cacheReadTokens', 0))
+write=int(d.get('cacheWriteTokens', 0))
+inp=int(d.get('inputTokens', 0))
+rate=float(d.get('cacheHitRate', 0)) * 100
+events=int(d.get('events', 0))
+print(f'Cache hit: {rate:.1f}% ({read}/{inp} input tokens, write {write}, events {events})')" 2>/dev/null || echo "")
+    if [[ -n "$metrics_line" ]]; then
+      printf "║ ${CYAN}%-53s${NC} ║\n" "$metrics_line"
+    fi
+  fi
+
   if [[ $diag_entries -gt 0 ]]; then
     echo -e "║ ${CYAN}Last reorder:${NC}                                           ║"
     tail -1 "$CACHE_DIR/diag.log" 2>/dev/null | while IFS= read -r line; do