feat(api): expose cache metrics in REPL + normalize across providers (#813)

* feat(api): expose cache metrics in REPL + /cache-stats command

* fix(api): normalize Kimi/DeepSeek/Gemini cache fields through shim layer

* test(api): cover /cache-stats rendering + fix CacheMetrics docstring drift

* fix(api): always reset cache turn counter + include date in /cache-stats rows

* refactor(api): unify shim usage builder + add cost-tracker wiring test

* fix(api): classify private-IP/self-hosted OpenAI endpoints as N/A instead of cold

* fix(api): require colon guard on IPv6 ULA prefix to avoid public-host over-match

* perf(api): ring buffer for cache history + hit rate clamp + .localhost TLD

* fix(api): null guards on formatters + document Codex Responses API shape

* fix(api): defensive start-of-turn reset + config gate fallback + env var docs

* fix(api): trust forwarded cache data on self-hosted URLs (data-driven)

* refactor(api): delegate streaming Responses usage to shared makeUsage helper

src/commands/cacheStats/index.ts

@@ -0,0 +1,24 @@
+/**
+ * /cache-stats — per-session cache diagnostics.
+ *
+ * Always-on diagnostic command (no toggle) that surfaces the metrics
+ * tracked in `cacheStatsTracker.ts`. Breaks cache usage down by request
+ * and also reports the session-wide aggregate — useful when the user
+ * suspects a cache bust (e.g. after /reload-plugins) and wants to see
+ * whether recent turns still hit the cache.
+ *
+ * Lazy-loaded (implementation in cacheStats.ts) to keep startup time
+ * minimal — same pattern used by /cost and /cache-probe.
+ */
+import type { Command } from '../../commands.js'
+
+const cacheStats = {
+  type: 'local',
+  name: 'cache-stats',
+  description:
+    'Show per-turn and session cache hit/miss stats (works across all providers)',
+  supportsNonInteractive: true,
+  load: () => import('./cacheStats.js'),
+} satisfies Command
+
+export default cacheStats