agent-cache-optimizer 0.1.1 → 0.2.0

package/README.md

@@ -84,16 +84,9 @@ tail -f ~/.cache/opencode/agent-cache-optimizer/diag.log
 
 ### Status dashboard
 
-Inside OpenCode:
-
-```
-/cache-status
-```
-
-Or terminal:
-
 ```bash
-bash scripts/cache-status.sh
+aco status           # text dashboard
+aco status --json    # JSON for scripts
 ```
 
 ### Output
@@ -216,11 +209,11 @@ agent-cache-optimizer/
 │   └── types.ts          # TypeScript types
 ├── adapters/
 │   └── claude-code.md    # Claude Code optimization guide
+├── bin/
+│   └── aco               # CLI: aco status
 ├── scripts/
-│   ├── cache-status.sh   # Status dashboard
+│   ├── cache-status.sh   # Status dashboard (legacy)
 │   └── check-cache-friendly.sh  # Config audit tool
-├── skills/
-│   └── cache-status/     # /cache-status slash command
 ├── docs/
 │   ├── cross-cli.md      # Cross-CLI architecture
 │   └── upstream.md       # Upstream fix recommendations

package/README.zh-CN.md

@@ -87,13 +87,13 @@ tail -f ~/.cache/opencode/agent-cache-optimizer/diag.log
 OpenCode 内：
 
 ```
-/cache-status
+aco status
 ```
 
 终端：
 
 ```bash
-bash scripts/cache-status.sh
+bash scriptsaco status.sh
 ```
 
 ## 🏗 工作原理

package/bin/aco

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# aco — agent-cache-optimizer CLI
+# Usage: aco status [--json]
+set -euo pipefail
+
+CACHE_DIR="${HOME}/.cache/opencode/agent-cache-optimizer"
+CMD="${1:-help}"
+
+# ── Colors ────────────────────────────────────────────────────────
+BOLD='\033[1m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; RED='\033[0;31m'; CYAN='\033[0;36m'; NC='\033[0m'
+
+# ── status ────────────────────────────────────────────────────────
+status_json() {
+  local agents_json="{}"
+  for db in "$CACHE_DIR"/stability-*.json; do
+    [[ -f "$db" ]] || continue
+    local agent
+    agent=$(basename "$db" .json | sed 's/^stability-//')
+    local obs
+    obs=$(python3 -c "import json; d=json.load(open('$db')); print(d.get('observations', 0))" 2>/dev/null || echo 0)
+    local pos_count
+    pos_count=$(python3 -c "import json; d=json.load(open('$db')); print(len(d.get('positions', {})))" 2>/dev/null || echo 0)
+    local avg_score
+    avg_score=$(python3 -c "
+import json
+d=json.load(open('$db'))
+scores=list(d.get('scores',{}).values())
+stable=sum(1 for s in scores if s>=0.7)
+total=len(scores)
+print(f'{stable}/{total}')" 2>/dev/null || echo "0/0")
+    agents_json=$(echo "$agents_json" | python3 -c "
+import json,sys
+agents=json.load(sys.stdin)
+agents['$agent']={'observations':$obs,'positions':$pos_count,'stable':'$avg_score'}
+print(json.dumps(agents))" 2>/dev/null || echo "$agents_json")
+  done
+
+  local diag_entries=0
+  [[ -f "$CACHE_DIR/diag.log" ]] && diag_entries=$(wc -l < "$CACHE_DIR/diag.log" | tr -d ' ')
+
+  local total_obs=0
+  for db in "$CACHE_DIR"/stability-*.json; do
+    [[ -f "$db" ]] || continue
+    local o
+    o=$(python3 -c "import json; d=json.load(open('$db')); print(d.get('observations', 0))" 2>/dev/null || echo 0)
+    total_obs=$((total_obs + o))
+  done
+
+  local status="no_data"
+  [[ $diag_entries -gt 0 ]] && status="active"
+
+  python3 -c "
+import json
+print(json.dumps({
+  'status': '$status',
+  'diag_entries': $diag_entries,
+  'total_observations': $total_obs,
+  'agents': $agents_json
+}, indent=2))"
+}
+
+status_text() {
+  # Check if any data exists
+  if [[ ! -d "$CACHE_DIR" ]] || [[ -z "$(ls "$CACHE_DIR"/stability-*.json 2>/dev/null)" ]]; then
+    echo ""
+    echo -e "${BOLD}╔══════════════════════════════════════════════════════╗${NC}"
+    echo -e "${BOLD}║           agent-cache-optimizer Status               ║${NC}"
+    echo -e "${BOLD}╠══════════════════════════════════════════════════════╣${NC}"
+    echo -e "║ ${YELLOW}Status: NO DATA${NC}                                          ║"
+    echo -e "║                                                       ║"
+    echo -e "║ Plugin has not been invoked yet. Make a request first. ║"
+    echo -e "${BOLD}╚══════════════════════════════════════════════════════╝${NC}"
+    echo ""
+    return
+  fi
+
+  # Count agents
+  local agent_count=0
+  for db in "$CACHE_DIR"/stability-*.json; do [[ -f "$db" ]] && agent_count=$((agent_count + 1)); done
+
+  # Diag entries
+  local diag_entries=0 first_ts="" last_ts=""
+  if [[ -f "$CACHE_DIR/diag.log" ]]; then
+    diag_entries=$(wc -l < "$CACHE_DIR/diag.log" | tr -d ' ')
+    first_ts=$(head -1 "$CACHE_DIR/diag.log" | grep -oP '^\[[^\]]+\]' | tr -d '[]' 2>/dev/null || echo "?")
+    last_ts=$(tail -1 "$CACHE_DIR/diag.log" | grep -oP '^\[[^\]]+\]' | tr -d '[]' 2>/dev/null || echo "?")
+  fi
+
+  echo ""
+  echo -e "${BOLD}╔══════════════════════════════════════════════════════╗${NC}"
+  echo -e "${BOLD}║           agent-cache-optimizer Status               ║${NC}"
+  echo -e "${BOLD}╠══════════════════════════════════════════════════════╣${NC}"
+
+  if [[ $diag_entries -gt 0 ]]; then
+    echo -e "║ ${GREEN}Status: ACTIVE${NC}                                           ║"
+    printf "║ Uptime: %-46s ║\n" "$first_ts → $last_ts"
+  else
+    echo -e "║ ${YELLOW}Status: LOADED (no activity yet)${NC}                        ║"
+  fi
+
+  echo -e "${BOLD}╠══════════════════════════════════════════════════════╣${NC}"
+
+  if [[ $agent_count -eq 0 ]]; then
+    echo -e "║ ${YELLOW}No per-agent data yet${NC}                                    ║"
+  else
+    printf "║ ${CYAN}%-22s %5s %8s %9s${NC} ║\n" "Agent" "Obs" "Pos" "Stable"
+    for db in "$CACHE_DIR"/stability-*.json; do
+      [[ -f "$db" ]] || continue
+      local agent obs pos stable
+      agent=$(basename "$db" .json | sed 's/^stability-//')
+      obs=$(python3 -c "import json; d=json.load(open('$db')); print(d.get('observations', 0))" 2>/dev/null || echo 0)
+      pos=$(python3 -c "import json; d=json.load(open('$db')); print(len(d.get('positions', {})))" 2>/dev/null || echo 0)
+      stable=$(python3 -c "
+import json
+d=json.load(open('$db'))
+scores=list(d.get('scores',{}).values())
+if scores:
+    s=sum(1 for v in scores if v>=0.7)
+    print(f'{s}/{len(scores)}')
+else:
+    print('0/0')" 2>/dev/null || echo "0/0")
+      printf "║ %-22s %5s %8s %9s ║\n" "$agent" "$obs" "$pos" "$stable"
+    done
+  fi
+
+  echo -e "${BOLD}╠══════════════════════════════════════════════════════╣${NC}"
+
+  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
+      printf "║   %-52s ║\n" "${line:0:52}"
+    done
+  fi
+
+  echo -e "${BOLD}╚══════════════════════════════════════════════════════╝${NC}"
+  echo ""
+}
+
+# ── help ───────────────────────────────────────────────────────────
+help_text() {
+  echo "agent-cache-optimizer (aco) — KV cache optimizer for LLM CLI agents"
+  echo ""
+  echo "Usage: aco <command>"
+  echo ""
+  echo "Commands:"
+  echo "  status          Show cache optimizer status"
+  echo "  status --json   Show status in JSON format"
+  echo "  help            Show this help"
+}
+
+# ── Main ───────────────────────────────────────────────────────────
+case "$CMD" in
+  status)
+    if [[ "${2:-}" == "--json" ]]; then
+      status_json
+    else
+      status_text
+    fi
+    ;;
+  help|--help|-h)
+    help_text
+    ;;
+  *)
+    echo "Unknown command: $CMD"
+    help_text
+    exit 1
+    ;;
+esac

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-cache-optimizer",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Content-agnostic KV cache optimizer for LLM CLI agents — boosts prompt cache hit rate by 40-88% through automatic stability tracking and block reordering",
   "keywords": [
     "kv-cache",
@@ -25,6 +25,9 @@
   },
   "type": "module",
   "main": "./src/index.ts",
+  "bin": {
+    "aco": "./bin/aco"
+  },
   "exports": {
     ".": "./src/index.ts",
     "./core": "./src/core.ts",
@@ -32,10 +35,10 @@
     "./splitting": "./src/splitting.ts"
   },
   "files": [
+    "bin/",
     "src/",
     "adapters/",
     "scripts/",
-    "skills/",
     "docs/",
     "README.md",
     "README.zh-CN.md",

package/skills/cache-status/SKILL.md

@@ -1,81 +0,0 @@
----
-name: cache-status
-description: Show KV cache optimizer status — stability DBs, reordering stats, diagnostics. Trigger: /cache-status
----
-
-# KV Cache Optimizer Status
-
-Show the current state of the KV cache optimizer plugin (agent-cache-optimizer.ts).
-
-## Data Locations
-
-- Stability DBs: `~/.cache/opencode/agent-cache-optimizer/stability-*.json`
-- Diagnostic log: `~/.cache/opencode/agent-cache-optimizer/diag.log`
-
-## Display Format
-
-Read all `stability-*.json` files and `diag.log`, then present:
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║              KV Cache Optimizer Status                       ║
-╠══════════════════════════════════════════════════════════════╣
-║ Status:  ACTIVE / NO DATA / ERROR                            ║
-║ Mode:    COLD START (heuristics) / WARM (hash-based)         ║
-║ Uptime:  first_seen → last_seen                             ║
-╠══════════════════════════════════════════════════════════════╣
-║ Per-Agent Breakdown:                                         ║
-║   orchestrator:  12 obs, 88% cacheable                       ║
-║   oracle:         5 obs, 75% cacheable                       ║
-║   fixer:          3 obs, 90% cacheable                       ║
-║   ...                                                        ║
-╠══════════════════════════════════════════════════════════════╣
-║ Last 5 reorders (from diag.log):                             ║
-║   [time] [agent] S:X U:Y D:Z T:N obs:M                       ║
-║   ...                                                        ║
-╠══════════════════════════════════════════════════════════════╣
-║ Estimated savings: XX KB / session                           ║
-╚══════════════════════════════════════════════════════════════╝
-```
-
-## Key Metrics
-
-From each `stability-{agent}.json`:
-- `observations`: number of calls tracked
-- `positions`: number of distinct block positions
-- Average `scores` per block → classification quality
-- Ratio of stable vs dynamic blocks
-
-From `diag.log`:
-- Last N reorder operations
-- Confirm plugin is being invoked
-
-## Interpretation
-
-- **NO DATA**: Plugin hasn't been invoked yet. Restart OpenCode after adding the plugin to `opencode.json`.
-- **COLD START**: First 2 sessions per agent — using position/size heuristics.
-- **WARM**: 3+ sessions — using hash-based stability tracking. More accurate.
-- **High stable %**: Good cache reuse across sessions.
-- **High unknown %**: Heuristics can't classify some blocks → will improve with more observations.
-
-## If Plugin Not Working
-
-1. Check `opencode.json` has `"file:///home/chris/.config/opencode/plugins/agent-cache-optimizer.ts"` in `plugin` array
-2. Check `diag.log` exists and has entries
-3. If no diag.log: the `experimental.chat.system.transform` hook may not be firing → fall back to `chat.params` diagnostic
-4. Run `opencode debug agent orchestrator` to verify plugin config
-
-## Quick Health Check
-
-```bash
-# Check if plugin is loaded
-ls ~/.cache/opencode/agent-cache-optimizer/
-
-# View last reorder
-tail -5 ~/.cache/opencode/agent-cache-optimizer/diag.log
-
-# Count observations per agent
-for f in ~/.cache/opencode/agent-cache-optimizer/stability-*.json; do
-  echo "$(basename $f .json): $(python3 -c "import json; d=json.load(open('$f')); print(d['observations'])") obs"
-done
-```