omp-vcc 0.1.1 → 0.1.4

package/README.md

@@ -1,10 +1,10 @@
 # @zhulinchng/omp-vcc — Algorithmic VCC Compaction for oh-my-pi
 
-> Fast, deterministic, lossless compaction — no LLM calls. Port of [`sting8k/pi-vcc`](https://github.com/sting8k/pi-vcc) (`@0.7.0`) into [oh-my-pi](https://github.com/can1357/oh-my-pi), inspired by [`lllyasviel/VCC`](https://github.com/lllyasviel/VCC) and paper [`arxiv:2603.29678`](https://arxiv.org/pdf/2603.29678) *View-oriented Conversation Compiler for Agent Trace Analysis* (Zhang & Agrawala, 2026-03-31).
+> Fast, deterministic, lossless compaction with no LLM calls. Port of [`sting8k/pi-vcc`](https://github.com/sting8k/pi-vcc) (`@0.7.0`) into [oh-my-pi](https://github.com/can1357/oh-my-pi), inspired by [`lllyasviel/VCC`](https://github.com/lllyasviel/VCC) and paper [`arxiv:2603.29678`](https://arxiv.org/pdf/2603.29678) *View-oriented Conversation Compiler for Agent Trace Analysis* (Zhang & Agrawala, 2026-03-31).
 
 ## Quick start
 
-> **New here?** → [`docs/setup.md`](docs/setup.md) — 5-minute install with prerequisites, 4 install options (link / npm / git), verify, first `/omp-vcc`, recall, config, and troubleshooting. The commands below are the tldr.
+> **New here?** → [`docs/setup.md`](docs/setup.md)
 
 ```sh
 # from source (local)
@@ -23,27 +23,30 @@ omp plugin install github:zhulinchng/omp-vcc
 
 ## What you get
 
-- **Auto** threshold/overflow compaction via `session_before_compact` hook — no LLM summary, 30–470 ms, 35–99% reduction.
+- **Auto** threshold/overflow compaction via `session_before_compact` hook (no LLM summary), 30–470 ms, 35–99% reduction.
 - **Manual** `/omp-vcc [keep:N] [focus]` (and `/pi-vcc` alias) — e.g. `/omp-vcc keep:2 fix auth` keeps last 2 user turns.
 - **Recall** `vcc_recall({query:"redis cache", scope:"all", page:1})` or `/vcc-recall hook|inject scope:all page:2` — ranked regex → TF-IDF OR, 5/page, `mode:'touched'` and `#N:path` drill-down.
+- **Savings observability** — toast `90.0k→22.0k (76% saved, ~68.0k)`, divider `── compacted · 90K→22K ·`, `vcc_stats` tool + `/vcc-stats` table + `details.savings` + `/tmp/omp-vcc-debug.json` (authoritative `tokensAfter` from host).
 
 ## Commands
 
 | Command | Description |
 | --- | --- |
-| `/omp-vcc [keep:N] [focus]` | Algorithmic compaction, smart-keep may boost `keep:1` to keep more when tail small (5 k → 25 k). `keep:0` compacts all. |
+| `/omp-vcc [keep:N] [focus]` | Algorithmic compaction, smart-keep may boost `keep:1` to keep more when tail small (5 k → 25 k). `keep:0` compacts all. Add `--stats` / `stats` to show last savings without compacting. |
 | `/pi-vcc` | Alias for migration |
 | `/vcc-recall [query] [scope:all] [page:N]` | Search compacted history (V_adapt). Plain keywords best. |
 | `/pi-vcc-recall` | Alias |
+| `/vcc-stats [history\|all]` | Show last compaction `Before→After/Saved/Kept` + history table (from `CompactionStats` 50-capped). |
+| `/omp-vcc-stats` | Alias for `/vcc-stats` |
 
-Tool `vcc_recall` mirrors the command, plus `expand:[indices]` and `mode:'touched'` for file index.
-
+Tool `vcc_recall` mirrors the command, plus `expand:[indices]` and `mode:'touched'` for file index. Tool `vcc_stats({history:true})` mirrors `/vcc-stats` (approval `read`), same 50-capped table.
 ## Configuration
 
 File `~/.omp/omp-vcc/config.json` (XDG-aware: `$OMP_VCC_CONFIG_PATH` > `$PI_VCC_CONFIG_PATH` (legacy) > `$OMP_DIR`/`$PI_CODING_AGENT_DIR` > `~/.omp/omp-vcc/config.json`, migrates legacy `~/.pi/agent/pi-vcc-config.json`):
 
 ```json
 {
+  "vccEnabled": true,
   "overrideDefaultCompaction": true,
   "smartKeepTail": true,
   "continueAfterThresholdCompact": true,
@@ -55,19 +58,126 @@ File `~/.omp/omp-vcc/config.json` (XDG-aware: `$OMP_VCC_CONFIG_PATH` > `$PI_VCC_
 
 VCC compiles the raw JSONL trace via **lex → parse IR → monotonic line assignment → view lowering** into three views sharing one coordinate system:
 
-- `V_full` identity (defines coordinates)
-- `V_ui` one-line tool summaries with pointers (`* Read "src/pets.py" (file.txt:18-20)`)
+- `V_full` identity — every message verbatim, defines coordinates `L`
+- `V_ui` one-line tool summaries with stable pointers (`* Read "src/pets.py" (file.txt:18-20)`)
 - `V_adapt(b, ρ)` projection via predicate `ρ` preserving headers/role tags and `(f:s-e)` pointers, two transposed modalities (document vs index oriented)
 
-`omp-vcc` implements `V_ui` as the structured summary (5 sections + ranked brief transcript) and `V_adapt` as `vcc_recall`. Pointer invariant `V_ui → V_full[s:e]` holds structurally. Diagrams and pipeline in [`docs/architecture.md`](docs/architecture.md); paper mapping in [`docs/paper-notes.md`](docs/paper-notes.md); setup in [`docs/setup.md`](docs/setup.md).
+`omp-vcc` implements `V_ui` as the structured summary (5 sections + ranked brief transcript) and `V_adapt` as `vcc_recall`. Pointer invariant `V_ui → V_full[s:e]` holds structurally.
+
+### VCC algorithm (30–470 ms)
+
+Traditional compaction ships the whole history to a remote LLM and waits seconds. `omp-vcc` never calls a model: it reuses `branchEntries` already in memory, calibrates token size, cuts, normalizes, and ranks locally.
+
+```mermaid
+flowchart TB
+  subgraph VCC["omp-vcc — local, deterministic"]
+    A["branchEntries\nin memory"] --> B["calibrate\ncpt = chars / tokensBefore"]
+    B --> C["buildOwnCut + smartKeep\nkeep tailored to tail size"]
+    C --> D["normalize + filter\nstrip ANSI, 123 arrow, harness XML"]
+    D --> E["rank TF-IDF\n5 sections + brief transcript"]
+    E --> F["summary 1.1k tok\n+ kept tail\n30-470 ms, zero cost"]
+  end
+  subgraph LLM["native remote LLM compaction"]
+    L1["branchEntries"] --> L2["serialize history\nHTTP to LLM"]
+    L2 --> L3["wait seconds\n+ token cost\n+ nondeterministic"]
+  end
+  F -. "next turn sees only F" .-> A
+  classDef vcc fill:#e8f5e9,stroke:#2e7d32
+  class F vcc
+  classDef llm fill:#fce4ec,stroke:#c2185b
+  class L3 llm
+```
+
+What `omp-vcc` adds vs intercepts in the harness (hooks, tools, commands, settings) and why — see [`docs/harness.md`](docs/harness.md) §§2–3.
+
+**Example** — a 80-turn session at 90k tokens, `keep:1` tail is only 3k (wastes budget):
 
-## Related work
+- raw tail `3k` → `smartKeepTail` grows to `keep:4` with tail `21k` (still ≤ 25k cap)
+- older 76 turns are compiled into `V_ui`:
+
+```txt
+[Session Goal] Fix auth token refresh
+[Files And Changes] src/auth.ts, src/app.ts
+[Brief transcript] (ranked, TF-IDF, 78 lines)
+  (#12) Read src/auth.ts — missing refresh on expiry
+  (#18) Edit src/auth.ts:12-34 — add refreshToken()
+  (#33) Test auth flow — 2 failed, 1 passed
+---
+Recall is the same idea: `vcc_recall` runs local regex → TF-IDF `rank.ts` and preserves skeleton. `query: "hook|inject"` returns 5 hits with `(#N)` pointers like `(#33) hook registration`; `query: "#18:src/auth.ts"` drills to `V_full[18:e]` verbatim.
+
+Docs: [`architecture`](docs/architecture.md) · [`configuration`](docs/configuration.md) · [`verification`](docs/verification.md) · [`harness`](docs/harness.md) · [`paper-notes`](docs/paper-notes.md) · [`setup`](docs/setup.md) · [`PUBLISHING`](docs/PUBLISHING.md) · pinned [`omp-compaction`](docs/omp-compaction.md) / [`omp-snapcompact`](docs/omp-snapcompact.md).
 
 - **pi-vcc** — TypeScript algorithmic compactor, zero LLM, `RANKED_BRIEF_BUDGET_TOKENS=1100` ceil 2000, `charsPerBlock 15`
 - **VCC** — Python `VCC.py` adaptive/transposed views, `SEP`, `match_lines`, `_tokenize`, `_trunc`, projection model
 - **Paper** — AppWorld evaluation: +1.1–4.2 task_goal points, ½–⅔ token halving, smaller memory
 
-## Develop
+## Best practices
+
+> Goal: keep context small enough to stay fast and cheap, but large enough that the agent doesn't lose what you're working on.
+
+### 1) Let auto do its job
+
+- Keep `overrideDefaultCompaction:true` (default) — threshold/overflow compaction becomes deterministic and instant. Only set `false` if you explicitly want the remote LLM summarizer for `handoff` or you installed the optional native `vcc` dropdown patch and want to toggle per-session in `/settings`.
+- Keep `smartKeepTail:true` and `continueAfterThresholdCompact:true` — the plugin grows `keep:1` to `keep:2…4` when the tail is tiny (5 k → 25 k) and auto-continues after a threshold compact so the agent doesn't stall mid-task.
+- Don't spam `/omp-vcc` every few turns. Auto threshold (derived from your model's context window) already fires at the right moment. Manual compacts are for deliberate boundaries: finishing a sub-task, before a risky refactor, or when you feel the context getting noisy.
+
+### 2) Pick the right `keep:N`
+
+| Situation | Command | Why |
+| --- | --- | --- |
+| Default, happy path | `/omp-vcc` or `keep:1` | Smallest tail, max savings. `smartKeepTail` will still grow to `keep:3` if the last turn is only 3 k tok so you don't waste budget. |
+| Actively iterating on last edits/tests | `/omp-vcc keep:2` or `keep:3` | Preserves the last 2–3 user turns verbatim (e.g. failing test output + fix). Costs more tokens but avoids recall. |
+| Need maximal reduction (e.g. before context overflow) | `/omp-vcc keep:0` | Summarizes everything, no tail. Next turn starts from pure `V_ui`. Useful before pasting a huge spec. |
+| With a focus prompt | `/omp-vcc keep:2 focus on auth refresh only` | Preserved tail + an injected follow-up prompt so the agent continues with the narrowed scope. |
+
+Explicit `keep:N` always wins — smart-keep never overrides it.
+
+### 3) Use recall instead of keeping more
+
+Keeping a huge tail is the expensive alternative to recall. Prefer a small keep and search when you need history:
+
+- Plain keywords first: `/vcc-recall redis cache` or `vcc_recall({query:"redis cache"})` — multi-word is OR + TF-IDF ranked (rare terms rank higher).
+- Regex when you know the pattern: `/vcc-recall hook|inject`, `/vcc-recall fail.*build`.
+- Pagination: `page:2` (5 hits/page): `/vcc-recall auth scope:all page:2`.
+- Scope: default is active lineage (what the current branch actually saw). Add `scope:all` to search abandoned branches/edits/retries.
+- Drill-down: `/vcc-recall #18:src/auth.ts` expands that turn's file slice verbatim from `V_full` — fastest way to rehydrate an edit.
+- Index mode: `vcc_recall({query:"", mode:"touched"})` lists touched files across the session.
+
+```mermaid
+flowchart LR
+  KEEP["keep small\nkeep:1 + smartKeep"] --> RECALL["need history?\n/vcc-recall keywords"]
+  RECALL --> DRILL["#N:path drill\nrehydrate file"]
+  KEEP --> FORGET["keep huge tail\nwastes 10-20k tok"]
+  style FORGET stroke-dasharray: 3 3
+```
+
+### 4) Help the extractor help you
+
+The 5 sections (`[Session Goal]`, `[Files And Changes]`, `[Commits]`, `[Outstanding Context]`, `[User Preferences]`) are regex/heuristics, not an LLM. Make them work better:
+
+- State the goal once, plainly, in the first user message: `Goal: fix auth token refresh in src/auth.ts`. That seeds `[Session Goal]` reliably.
+- Declare preferences explicitly with cue words: `always run tests before committing`, `prefer concise diffs`, `never edit src/generated/`. Those go to `[User Preferences]`.
+- Commit frequently — commits populate `[Commits]` and survive compaction better than bare edits.
+- Mark outstanding items as questions/errors (`TODO:`, `failing:`, `why does …?`) so they land in `[Outstanding Context]` until resolved.
+
+### 5) Know the difference: compact vs clear
+
+- `/omp-vcc` (or `/compact`) **summarizes** — history becomes `V_ui` + searchable `V_full`. The divider `── compacted · 90k→22k · ctrl+o ──` stays in the transcript (expand with `ctrl+o`).
+- `/clear` **erases** — inserts a `reset_boundary` after which even `V_full` is no longer compacted. Previous history stays on disk for `/vcc-recall scope:all` but the live context starts empty. Use `/clear` when you truly want a fresh session; use `/omp-vcc` when you want to keep the story.
+
+### 6) Debug/verify habits
+
+- One-shot verification after install: `/omp-vcc keep:1 test` → expect toast `omp-vcc: kept …` and an inline `[Session Goal]` block. No toast = `overrideDefaultCompaction:false` or a competing compactor.
+- To tune: set `debug:true` in `~/.omp/omp-vcc/config.json`, run `/omp-vcc`, then `cat /tmp/omp-vcc-debug.json` — check `usedOwnCut`, `tokensBefore`, `tokenEstimate {charsPerToken, mode}`, `summaryLength`, `sections`. Remember to flip `debug:false` after — the file is overwritten every compact.
+- For overflow: if you hit `tokensBefore > 50k` and nothing happens, check `omp plugin doctor` and that `vccEnabled:true`.
+
+### 7) Team / long-session hygiene
+
+- One compaction covers 30–100 turns; repeated compactions merge bounded (transcript caps at ~120 lines, sections dedup). Long-running sessions (200+ turns) stay healthy — don't fear auto.
+- `snapcompact`/`shake`/`handoff` in `compaction.methodOrder` are orthogonal — `omp-vcc` only intercepts `context-full`. Leave them in the order if you use them; they run when `omp-vcc` explicitly defers (e.g. `vccEnabled:false`).
+- Pin the plugin version in CI or shared dots: `omp plugin install github:zhulinchng/omp-vcc#v0.1.x` so the team shares the same `RANKED_BRIEF_BUDGET_TOKENS=1100` behavior.
+
+## Development
 
 ```bash
 omp plugin link .
@@ -83,23 +193,28 @@ Capabilities: `extension`, `skill`, `command` — entry `extensions/main.ts`.
 
 ```sh
 bunx tsc --noEmit
-bun test          # 310 tests across 33 files, 768 expects
-bun run smoke     # ok: session_before_compact hooked, vcc_recall registered
+bun test          # 378 tests across 36 files, 1007 expects
+bun run smoke     # 9 checks: 3 hooks + 4 commands + 2 tools (vcc_recall, vcc_stats)
 omp plugin link /Users/zhu/code/projects/omp-vcc && omp plugin doctor
 ```
 
-In a live `omp` session: `/omp-vcc keep:1` shows `[Session Goal]` toast `omp-vcc: kept 1/5 turns, ~2.1k tok`; with `debug:true` check `/tmp/omp-vcc-debug.json`. Full proof matrix and mermaid flows in [`docs/verification.md`](docs/verification.md).
-## Publish
+In a live `omp` session: `/omp-vcc keep:1` shows `[Session Goal]` with toast `omp-vcc: 90.0k→22.0k (76% saved, ~68.0k) · kept 1/5 turns, ~2.1k tok` (fallback `omp-vcc: kept 1/5 turns…` when `tokensBefore` unavailable) + divider `── compacted · 90K→22K · ctrl+o ──`; with `debug:true` check `/tmp/omp-vcc-debug.json` (`savings` + `authoritativeSavings`). `/vcc-stats` / `/omp-vcc --stats` / `vcc_stats({history:true})` show the 50-capped `Before→After/Saved/Kept/Summarized/When` table. Full proof matrix and mermaid flows in [`docs/verification.md`](docs/verification.md); harness impact (adds vs intercepts) in [`docs/harness.md`](docs/harness.md). Smoke checks map to the re-runnable truth table in [`docs/harness.md` §9](docs/harness.md#9-verification-map-claim--evidence).
+
+Docs: [`architecture`](docs/architecture.md) · [`configuration`](docs/configuration.md) · [`verification`](docs/verification.md) · [`harness`](docs/harness.md) · [`paper-notes`](docs/paper-notes.md) · [`setup`](docs/setup.md) · [`PUBLISHING`](docs/PUBLISHING.md) · pinned [`omp-compaction`](docs/omp-compaction.md) / [`omp-snapcompact`](docs/omp-snapcompact.md).
 
-- npmjs (unscoped): `npm publish --registry https://registry.npmjs.org --access public` (package `omp-vcc`)
-- GitHub Packages (scoped): `npm publish --registry https://npm.pkg.github.com` (package `@zhulinchng/omp-vcc`, needs `GITHUB_TOKEN` with `read:packages, write:packages`)
+See [`docs/PUBLISHING.md`](docs/PUBLISHING.md) for the full checklist (package shape, gates, dual `omp-vcc` / `@zhulinchng/omp-vcc` flow, verification, deployment matrix, and troubleshooting). TL;DR:
+
+- npmjs (unscoped): `npm publish --access public` (package `omp-vcc`, 2FA `auth-and-writes` → browser or `--otp`)
+- GitHub Packages (scoped): `gh release create vX.Y.Z` triggers `.github/workflows/publish-gpr.yml` → `@zhulinchng/omp-vcc` via `GITHUB_TOKEN` (`read:packages, write:packages`); manual fallback `npm pkg set name=@zhulinchng/omp-vcc && GITHUB_TOKEN=$(gh auth token) npm publish --userconfig /tmp/gpr-npmrc --access public` (see guide for the scoped-registry `/tmp/gpr-npmrc` pitfall)
 - Consumer GPR auth: add to `~/.npmrc`:
+
   ```
   @zhulinchng:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT
   ```
+
 - Marketplace: add an entry to `.omp-plugin/marketplace.json` (see `plugin-skill/assets/templates/marketplace-entry.json.template`).
 
 ## License
 
-MIT — pi-vcc core files retain original MIT.
+MIT

package/extensions/main.ts

@@ -6,14 +6,19 @@
 
 import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
 import { scaffoldSettings } from "./vcc-core/core/settings";
+import { loadAllMessages } from "./vcc-core/core/load-messages";
 import {
   registerBeforeCompactHook,
   PI_VCC_COMPACT_INSTRUCTION,
   OMP_VCC_COMPACT_INSTRUCTION,
   getLastCompactionStats,
+  getCompactionHistory,
+  formatLastStatsDetail,
+  formatStatsTable,
   scheduleCompactionStatsNotify,
+  registerVccStatsTool as registerVccStatsToolHook,
+  registerVccStatsCommand as registerVccStatsCommandHook,
 } from "./vcc-core/hook";
-import { loadAllMessages } from "./vcc-core/core/load-messages";
 import { searchEntriesDetailed, getTouchedFiles } from "./vcc-core/core/search-entries";
 import { formatRecallOutput, formatTouchedOutput } from "./vcc-core/core/format-recall";
 import { getActiveLineageEntryIds } from "./vcc-core/core/lineage";
@@ -152,15 +157,37 @@ export default function (pi: ExtensionAPI): void {
       return { content: [{ type: "text", text: output }], details: undefined };
     },
   } as unknown as Parameters<ExtensionAPI["registerTool"]>[0]);
+  // ── vcc_stats tool — stats surface for savings (paper § verification) ──
+  registerVccStatsToolHook(pi);
+
 
-  // ── /omp-vcc command — manual algorithmic compaction (V_ui) ──
   pi.registerCommand("omp-vcc", {
-    description: "Compact conversation with omp-vcc structured summary (keep:N + optional focus)",
+    description: "Compact conversation with omp-vcc structured summary (keep:N + optional focus) — add --stats to show savings",
     handler: async (args: string, ctx: unknown) => {
       const c = ctx as {
         compact: (instructions?: string) => Promise<void>;
         ui: { notify: (msg: string, level?: string) => void };
+        sessionManager?: { getSessionFile?: () => string | undefined };
       };
+      const trimmed = (args || "").trim();
+      const lower = trimmed.toLowerCase();
+      if (lower === "--stats" || lower === "stats" || lower.startsWith("--stats ") || lower.startsWith("stats ")) {
+        const wantHistory = lower.includes("history") || lower.includes("all");
+        const history = getCompactionHistory(pi);
+        const last = getLastCompactionStats(pi);
+        const piAny = pi as unknown as { sendMessage?: (msg: unknown, opts?: unknown) => void };
+        if (!last && history.length === 0) {
+          try { piAny.sendMessage?.({ customType: "vcc-stats", content: "No compactions yet. Run /omp-vcc to compact first.", display: true }, { triggerTurn: false }); } catch {}
+          try { c.ui.notify("No compactions yet.", "info"); } catch {}
+          return;
+        }
+        const output = wantHistory
+          ? `${formatStatsTable(history)}\n\n${last ? formatLastStatsDetail(last) : ""}`
+          : `${last ? formatLastStatsDetail(last) : "No last stats"}${history.length > 1 ? `\n\nHistory:\n${formatStatsTable(history)}` : ""}`;
+        try { piAny.sendMessage?.({ customType: "vcc-stats", content: output, display: true }, { triggerTurn: false }); } catch {}
+        try { c.ui.notify(`vcc_stats: ${history.length} compaction(s)`, "info"); } catch {}
+        return;
+      }
       const parsed = parseKeepAndPrompt(args);
       const keep = parsed.keepUserTurns;
       const followUpPrompt = parsed.followUpPrompt;
@@ -172,7 +199,7 @@ export default function (pi: ExtensionAPI): void {
       } catch {}
       try {
         await c.compact(customInstructions);
-        const stats = getLastCompactionStats();
+        const stats = getLastCompactionStats(pi);
         if (stats) {
           scheduleCompactionStatsNotify(c as unknown as { ui: { notify: (msg: string, level?: string) => void } }, stats);
         } else {
@@ -209,7 +236,7 @@ export default function (pi: ExtensionAPI): void {
       const customInstructions = buildPiVccCustomInstructions(keep);
       try {
         await c.compact(customInstructions);
-        const stats = getLastCompactionStats();
+        const stats = getLastCompactionStats(pi);
         if (stats) scheduleCompactionStatsNotify(c as unknown as { ui: { notify: (msg: string, level?: string) => void } }, stats);
         else try { c.ui.notify("Compacted with pi-vcc (via omp-vcc)", "info"); } catch {}
         if (followUpPrompt) {
@@ -309,11 +336,15 @@ export default function (pi: ExtensionAPI): void {
       const header = totalPages > 1 ? `Page ${page}/${totalPages} (${hits.length} total matches${scopeSuffix}${truncationNote})` : `${hits.length} matches${scopeSuffix}${truncationNote}`;
       const footer = page < totalPages ? `\n--- /pi-vcc-recall ${query}${scopeArg} page:${page + 1} ---` : "";
       const output = formatRecallOutput(pageResults, query, header) + footer;
+
       try { piAny.sendMessage?.({ customType: "vcc-recall", content: output, display: true }, { triggerTurn: false }); } catch {}
     },
   });
+  // ── /vcc-stats commands — show savings table (PR3) ──
+  registerVccStatsCommandHook(pi);
+
 }
 // ── Re-exports for pi-vcc test compatibility (not dead: tests import via hook directly,
 // but external consumers and the `vcc-recall` shim may import via main) ──
-export { registerBeforeCompactHook, PI_VCC_COMPACT_INSTRUCTION, OMP_VCC_COMPACT_INSTRUCTION, getLastCompactionStats, scheduleCompactionStatsNotify, formatCompactionStats, AUTO_CONTINUE_CUSTOM_TYPE, LEGACY_AUTO_CONTINUE_CUSTOM_TYPE, invalidExpandIndices, registerRecallTool, registerVccRecallCommand, registerPiVccCommand } from "./vcc-core/hook";
+export { registerBeforeCompactHook, PI_VCC_COMPACT_INSTRUCTION, OMP_VCC_COMPACT_INSTRUCTION, getLastCompactionStats, getCompactionHistory, formatCompactionStats, formatStatsTable, formatLastStatsDetail, scheduleCompactionStatsNotify, AUTO_CONTINUE_CUSTOM_TYPE, LEGACY_AUTO_CONTINUE_CUSTOM_TYPE, invalidExpandIndices, registerRecallTool, registerVccRecallCommand, registerPiVccCommand, registerVccStatsTool, registerVccStatsCommand, clearCompactionHistoryForTests } from "./vcc-core/hook";
 export { buildPiVccCustomInstructions, parseKeepAndPrompt } from "./vcc-core/core/compact-args";

package/extensions/vcc-core/details.ts

@@ -2,11 +2,20 @@
 import type { CompactionReason } from "./types";
 
 export interface PiVccCompactionDetails {
-  compactor: "pi-vcc";
+  compactor: "pi-vcc" | "omp-vcc";
   version: number;
   sections: string[];
   sourceMessageCount: number;
   previousSummaryUsed: boolean;
   reason?: CompactionReason;
   willRetry?: boolean;
+  savings?: {
+    tokensBefore: number;
+    summaryChars: number;
+    summaryTokensEst: number;
+    keptTokensEst: number;
+    tokensAfterEst: number;
+    tokensSavedEst: number;
+    savedPercentEst: number;
+  };
 }

package/extensions/vcc-core/hook.ts

@@ -52,6 +52,26 @@ export interface CompactionStats {
   smartFromKeep?: number;
   reason?: CompactionReason;
   willRetry?: boolean;
+  /** Tokens before compaction (from preparation). */
+  tokensBefore?: number;
+  /** Summary char length */
+  summaryChars?: number;
+  /** Summary tokens estimate via calibrated cpt */
+  summaryTokensEst?: number;
+  /** Estimated tokens after = summaryTokensEst + keptTokensEst */
+  tokensAfterEst?: number;
+  /** Authoritative tokensAfter from host (compactionEntry) */
+  tokensAfter?: number;
+  /** Estimated saved = tokensBefore - tokensAfterEst */
+  tokensSavedEst?: number;
+  /** Authoritative saved */
+  tokensSaved?: number;
+  /** Estimated percent 0-100 */
+  savedPercentEst?: number;
+  /** Authoritative percent */
+  savedPercent?: number;
+  /** When compaction occurred */
+  timestamp?: number;
 }
 
 export type BudgetCutKind = "no_anchor" | "oversized_tail";
@@ -61,17 +81,37 @@ let lastStats: CompactionStats | null = null;
 let lastCompactWasPiVcc = false;
 let pendingFollowUpPrompt: string | null = null;
 let pendingAutoContinueTimer: any = null;
+let globalHistory: CompactionStats[] = [];
 // Per-pi state to avoid cross-session pollution when multiple sessions share the
 // same ESM module singleton (e.g. main + subagents). Module globals remain as
 // fallback for host-free tests that call getLastCompactionStats() without a pi.
-const perPi = new WeakMap<any, { lastStats: CompactionStats | null; lastCompactWasPiVcc: boolean; pendingFollowUpPrompt: string | null; pendingAutoContinueTimer: any }>();
+const perPi = new WeakMap<any, { lastStats: CompactionStats | null; lastCompactWasPiVcc: boolean; pendingFollowUpPrompt: string | null; pendingAutoContinueTimer: any; statsHistory: CompactionStats[] }>();
+// Track strong refs for test helper clearCompactionHistoryForTests: WeakMap keys
+// cannot be enumerated, so keep a Set for test-only cleanup.
+const perPiKeys = new Set<any>();
 const getPerPi = (pi: any) => {
   if (!pi || typeof pi !== "object") return null;
   let s = perPi.get(pi);
-  if (!s) { s = { lastStats: null, lastCompactWasPiVcc: false, pendingFollowUpPrompt: null, pendingAutoContinueTimer: null }; perPi.set(pi, s); }
+  if (!s) { s = { lastStats: null, lastCompactWasPiVcc: false, pendingFollowUpPrompt: null, pendingAutoContinueTimer: null, statsHistory: [] }; perPi.set(pi, s); perPiKeys.add(pi); }
+  if (!s.statsHistory) s.statsHistory = [];
   return s;
 };
-const setLastStats = (pi: any, v: CompactionStats | null) => { lastStats = v; const s = getPerPi(pi); if (s) s.lastStats = v; };
+const setLastStats = (pi: any, v: CompactionStats | null) => {
+  if (v && v.timestamp == null) v.timestamp = Date.now();
+  lastStats = v;
+  const s = getPerPi(pi);
+  if (s) {
+    s.lastStats = v;
+    if (v) {
+      s.statsHistory.push(v);
+      if (s.statsHistory.length > 50) s.statsHistory.shift();
+    }
+  }
+  if (v) {
+    globalHistory.push(v);
+    if (globalHistory.length > 50) globalHistory.shift();
+  }
+};
 const setLastCompactWasPiVcc = (pi: any, v: boolean) => { lastCompactWasPiVcc = v; const s = getPerPi(pi); if (s) s.lastCompactWasPiVcc = v; };
 const setPendingFollowUpPrompt = (pi: any, v: string | null) => { pendingFollowUpPrompt = v; const s = getPerPi(pi); if (s) s.pendingFollowUpPrompt = v; };
 const getPendingFollowUpPrompt = (pi: any) => { const s = getPerPi(pi); return s ? s.pendingFollowUpPrompt : pendingFollowUpPrompt; };
@@ -135,25 +175,131 @@ const scheduleAutoContinue = (pi: any) => {
   }, 0);
 };
 
-export const getLastCompactionStats = () => lastStats;
-
+export const getLastCompactionStats = (pi?: any) => {
+  if (pi) {
+    const s = getPerPi(pi);
+    return s?.lastStats ?? null;
+  }
+  return lastStats;
+};
 const formatTokens = (n: number): string => {
   if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
   return String(n);
 };
 
 export const formatCompactionStats = (stats: CompactionStats): string => {
+  const before = stats.tokensBefore ?? 0;
+  const after = stats.tokensAfter ?? stats.tokensAfterEst ?? 0;
+  const savedRaw = stats.tokensSaved ?? stats.tokensSavedEst;
+  const saved = typeof savedRaw === "number" ? savedRaw : (before > 0 && after > 0 ? Math.max(0, before - after) : 0);
+  const percentRaw = stats.savedPercent ?? stats.savedPercentEst;
+  const percent = typeof percentRaw === "number" ? percentRaw : (before > 0 && saved > 0 ? Math.round((saved / before) * 100) : 0);
+  const hasSavings = before > 0 && after > 0 && before > after && saved > 0 && percent > 0;
+  const savingsPrefix = hasSavings ? `${formatTokens(before)}→${formatTokens(after)} (${percent}% saved, ~${formatTokens(saved)}) · ` : "";
+  const keptTokens = stats.keptTokensEst ?? 0;
+  const summarized = stats.summarized ?? 0;
+  const keptTurns = stats.keptUserTurns ?? 0;
+  const totalTurns = stats.totalUserTurns ?? 0;
   if (stats.budgetCut) {
     const reason = stats.budgetCut === "no_anchor" ? "no user anchor" : "oversized tail";
-    return `omp-vcc: kept ~${formatTokens(stats.keptTokensEst)} tok tail (mid-turn cut, ${reason}), summarized ${stats.summarized}.`;
+    if (savingsPrefix) {
+      return `omp-vcc: ${savingsPrefix}kept ~${formatTokens(keptTokens)} tok tail (mid-turn cut, ${reason}), summarized ${summarized}.`;
+    }
+    return `omp-vcc: kept ~${formatTokens(keptTokens)} tok tail (mid-turn cut, ${reason}), summarized ${summarized}.`;
   }
-  const notes: string[] = [`summarized ${stats.summarized}`];
+  const notes: string[] = [`summarized ${summarized}`];
   if (stats.smartKeepAdjusted) {
     notes.push("smart-keep");
   }
-  return `omp-vcc: kept ${stats.keptUserTurns}/${stats.totalUserTurns} turns, ~${formatTokens(stats.keptTokensEst)} tok (${notes.join(", ")}).`;
+  if (savingsPrefix) {
+    return `omp-vcc: ${savingsPrefix}kept ${keptTurns}/${totalTurns} turns, ~${formatTokens(keptTokens)} tok (${notes.join(", ")}).`;
+  }
+  return `omp-vcc: kept ${keptTurns}/${totalTurns} turns, ~${formatTokens(keptTokens)} tok (${notes.join(", ")}).`;
+};
+
+export const getCompactionHistory = (pi?: any): CompactionStats[] => {
+  if (pi) {
+    const s = getPerPi(pi);
+    if (s?.statsHistory) return [...s.statsHistory];
+  }
+  return [...globalHistory];
+};
+
+export const clearCompactionHistoryForTests = () => {
+  globalHistory = [];
+  lastStats = null;
+  lastCompactWasPiVcc = false;
+  pendingFollowUpPrompt = null;
+  clearTimeout(pendingAutoContinueTimer as any);
+  pendingAutoContinueTimer = null;
+  for (const pi of perPiKeys) {
+    const s = perPi.get(pi);
+    if (s) {
+      s.statsHistory = [];
+      s.lastStats = null;
+      s.lastCompactWasPiVcc = false;
+      s.pendingFollowUpPrompt = null;
+      clearTimeout(s.pendingAutoContinueTimer as any);
+      s.pendingAutoContinueTimer = null;
+    }
+    // Remove strong ref so pi can be GC'd and WeakMap entry cleared; fresh
+    // getPerPi(pi) will recreate if this pi is reused, but tests create fresh
+    // pi objects each time, so clearing prevents unbounded Set growth across
+    // the 377-test suite.
+    perPi.delete(pi);
+  }
+  perPiKeys.clear();
+};
+
+export const formatStatsTable = (history: CompactionStats[]): string => {
+  if (!history || history.length === 0) return "No compactions yet.";
+  const header = "| # | Before → After | Saved | Kept | Summarized | When |";
+  const sep = "|---|---|---|---|---|---|---|";
+  const rows = history.map((s, idx) => {
+    const before = s.tokensBefore ?? 0;
+    const after = s.tokensAfter ?? s.tokensAfterEst ?? 0;
+    const saved = s.tokensSaved ?? s.tokensSavedEst ?? (before > 0 && after > 0 ? Math.max(0, before - after) : 0);
+    const percent = s.savedPercent ?? s.savedPercentEst ?? (before > 0 && saved > 0 ? Math.round((saved / before) * 100) : 0);
+    const beforeAfter = before > 0 && after > 0 ? `${formatTokens(before)}→${formatTokens(after)}` : `${formatTokens(before)}→${formatTokens(after)}`;
+    const savedStr = saved > 0 ? `${formatTokens(saved)} (${percent}%)` : "—";
+    const keptTurns = s.keptUserTurns ?? 0;
+    const totalTurns = s.totalUserTurns ?? 0;
+    const keptTok = s.keptTokensEst ?? 0;
+    const summarized = s.summarized ?? 0;
+    const keptStr = `${keptTurns}/${totalTurns} turns, ~${formatTokens(keptTok)} tok${s.budgetCut ? ` (${s.budgetCut})` : ""}`;
+    const when = s.timestamp ? new Date(s.timestamp).toISOString().slice(0, 19).replace("T", " ") : "—";
+    return `| ${idx + 1} | ${beforeAfter} | ${savedStr} | ${keptStr} | ${summarized} | ${when} |`;
+  });
+  return [header, sep, ...rows].join("\n");
+};
+
+export const formatLastStatsDetail = (stats: CompactionStats | null): string => {
+  if (!stats) return "No compaction has run yet.";
+  const before = stats.tokensBefore ?? 0;
+  const after = stats.tokensAfter ?? stats.tokensAfterEst ?? 0;
+  const saved = stats.tokensSaved ?? stats.tokensSavedEst ?? (before > 0 && after > 0 ? Math.max(0, before - after) : 0);
+  const percent = stats.savedPercent ?? stats.savedPercentEst ?? (before > 0 && saved > 0 ? Math.round((saved / before) * 100) : 0);
+  const kept = stats.kept ?? 0;
+  const keptTurns = stats.keptUserTurns ?? 0;
+  const totalTurns = stats.totalUserTurns ?? 0;
+  const keptTok = stats.keptTokensEst ?? 0;
+  const summaryTok = stats.summaryTokensEst ?? 0;
+  const summaryChars = stats.summaryChars ?? 0;
+  const summarized = stats.summarized ?? 0;
+  const lines = [
+    `**Last compaction** ${stats.timestamp ? new Date(stats.timestamp).toISOString() : ""}`,
+    `- Before → After: **${formatTokens(before)} → ${formatTokens(after)}** (${percent}% saved, ~${formatTokens(saved)})`,
+    `- Summary: ~${formatTokens(summaryTok)} tok (${summaryChars} chars), kept tail ~${formatTokens(keptTok)} tok (${kept} msgs, ${keptTurns}/${totalTurns} turns)`,
+    `- Summarized: ${summarized} messages${stats.smartKeepAdjusted ? ` (smart-keep ${stats.smartFromKeep}→${keptTurns})` : ""}${stats.budgetCut ? ` · budgetCut:${stats.budgetCut}` : ""}`,
+    `- Details: ${stats.reason ? `reason=${stats.reason}` : "reason=auto"}${stats.willRetry ? " willRetry=true" : ""}`,
+  ];
+  if (stats.tokensAfter != null && stats.tokensAfterEst != null && stats.tokensAfter !== stats.tokensAfterEst) {
+    lines.push(`- Note: est after ${formatTokens(stats.tokensAfterEst)} vs authoritative ${formatTokens(stats.tokensAfter)}`);
+  }
+  return lines.join("\n");
 };
 
+
 const readCompactionEventContext = (event: unknown): { reason?: CompactionReason; willRetry: boolean } => {
   const raw = event as { reason?: unknown; willRetry?: unknown };
   const reason = raw.reason === "manual" || raw.reason === "threshold" || raw.reason === "overflow"
@@ -726,21 +872,7 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
       (sum: number, e: any) => sum + estimateMessageContentChars(e.message?.content),
       0,
     );
-    setLastStats(pi, {
-      summarized: agentMessages.length,
-      kept: keptEntries.length,
-      keptUserTurns: ownCut.keptUserTurns,
-      totalUserTurns: ownCut.totalUserTurns,
-      requestedKeepUserTurns: ownCut.requestedKeepUserTurns,
-      keepUserTurnsExplicit,
-      keepFallbackToCompactAll: ownCut.keepFallbackToCompactAll,
-      keptTokensEst: estimateTokensFromChars(keptChars, tokenEstimate.charsPerToken),
-      smartKeepAdjusted: smartKeep.smartAdjusted,
-      smartFromKeep: smartKeep.fromKeep,
-      budgetCut: ownCut.ok ? ownCut.budgetCut : undefined,
-      reason,
-      willRetry,
-    });
+    const keptTokensEst = estimateTokensFromChars(keptChars, tokenEstimate.charsPerToken);
     const config = settings;
 
     // Ranked compaction: keep the highest-signal blocks under a token budget
@@ -776,6 +908,35 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
       },
     });
 
+    const tokensBefore = typeof preparation.tokensBefore === "number" ? preparation.tokensBefore : 0;
+    const summaryChars = summary.length;
+    const summaryTokensEst = estimateTokensFromChars(summaryChars, tokenEstimate.charsPerToken);
+    const tokensAfterEst = summaryTokensEst + keptTokensEst;
+    const tokensSavedEst = tokensBefore > 0 ? Math.max(0, tokensBefore - tokensAfterEst) : 0;
+    const savedPercentEst = tokensBefore > 0 && tokensSavedEst > 0 ? Math.round((tokensSavedEst / tokensBefore) * 100) : 0;
+
+    setLastStats(pi, {
+      summarized: agentMessages.length,
+      kept: keptEntries.length,
+      keptUserTurns: ownCut.keptUserTurns,
+      totalUserTurns: ownCut.totalUserTurns,
+      requestedKeepUserTurns: ownCut.requestedKeepUserTurns,
+      keepUserTurnsExplicit,
+      keepFallbackToCompactAll: ownCut.keepFallbackToCompactAll,
+      keptTokensEst,
+      smartKeepAdjusted: smartKeep.smartAdjusted,
+      smartFromKeep: smartKeep.fromKeep,
+      budgetCut: ownCut.ok ? ownCut.budgetCut : undefined,
+      reason,
+      willRetry,
+      tokensBefore,
+      summaryChars,
+      summaryTokensEst,
+      tokensAfterEst,
+      tokensSavedEst,
+      savedPercentEst,
+    });
+
     const branchIds = branchEntries.map((e: any) => e.id);
     const cutIdx = branchIds.indexOf(firstKeptEntryId);
     const cutWindow = cutIdx >= 0
@@ -787,6 +948,9 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
         }))
       : [];
 
+    const KNOWN_SECTIONS = new Set(["Session Goal", "Files And Changes", "Commits", "Outstanding Context", "User Preferences"]);
+    const extractKnownSections = (text: string) =>
+      [...text.matchAll(/^\[(.+?)\]/gm)].map((m) => m[1]).filter((h) => KNOWN_SECTIONS.has(h));
     dbg(config, {
       usedOwnCut: true,
       budgetCut: ownCut.budgetCut,
@@ -797,21 +961,39 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
       convertedMessages: messages.length,
       firstKeptEntryId,
       cutWindow,
-      tokensBefore: preparation.tokensBefore,
+      tokensBefore,
       tokenEstimate,
       summaryLength: summary.length,
       summaryPreview: summary.slice(0, 500),
-      sections: [...summary.matchAll(/^\[(.+?)\]/gm)].map((m) => m[1]),
+      sections: extractKnownSections(summary),
+      savings: {
+        tokensBefore,
+        summaryChars,
+        summaryTokensEst,
+        keptTokensEst,
+        tokensAfterEst,
+        tokensSavedEst,
+        savedPercentEst,
+      },
     });
 
     const details: PiVccCompactionDetails = {
       compactor: "omp-vcc",
-      version: 1,
-      sections: [...summary.matchAll(/^\[(.+?)\]/gm)].map((m) => m[1]),
+      version: 2,
+      sections: extractKnownSections(summary),
       sourceMessageCount: agentMessages.length,
       previousSummaryUsed: Boolean(preparation.previousSummary),
       reason,
       willRetry,
+      savings: {
+        tokensBefore,
+        summaryChars,
+        summaryTokensEst,
+        keptTokensEst,
+        tokensAfterEst,
+        tokensSavedEst,
+        savedPercentEst,
+      },
     };
 
     setLastCompactWasPiVcc(pi, isPiVcc);
@@ -831,11 +1013,44 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
     const followUpPrompt = getPendingFollowUpPrompt(pi);
     setPendingFollowUpPrompt(pi, null);
     const per = getPerPi(pi);
+    const stats = per ? per.lastStats : lastStats;
+    if (!stats) return;
+    // Enrich with authoritative tokensAfter from host if available (even for pi-vcc manual, before early return)
+    const entry: any = (event as any).compactionEntry;
+    if (entry && typeof entry.tokensAfter === "number" && typeof entry.tokensBefore === "number") {
+      const before = entry.tokensBefore;
+      const after = entry.tokensAfter;
+      const saved = Math.max(0, before - after);
+      const percent = before > 0 && saved > 0 ? Math.round((saved / before) * 100) : 0;
+      if (per && per.lastStats) {
+        per.lastStats.tokensAfter = after;
+        per.lastStats.tokensSaved = saved;
+        per.lastStats.savedPercent = percent;
+        per.lastStats.tokensBefore = before;
+      }
+      if (lastStats) {
+        lastStats.tokensAfter = after;
+        lastStats.tokensSaved = saved;
+        lastStats.savedPercent = percent;
+        lastStats.tokensBefore = before;
+      }
+      (stats as any).tokensAfter = after;
+      (stats as any).tokensSaved = saved;
+      (stats as any).savedPercent = percent;
+      (stats as any).tokensBefore = before;
+      try {
+        const cfg = loadSettings(ctx);
+        if (cfg.debug) {
+          dbg(cfg, {
+            authoritativeSavings: { tokensBefore: before, tokensAfter: after, tokensSaved: saved, savedPercent: percent },
+            eventEntry: { id: entry.id, tokensBefore: entry.tokensBefore, tokensAfter: entry.tokensAfter },
+          });
+        }
+      } catch {}
+    }
     const isPiVccLast = per ? per.lastCompactWasPiVcc : lastCompactWasPiVcc;
     if (isPiVccLast) return; // /pi-vcc handles its own toast via onComplete
     if (willRetry) return;
-    const stats = per ? per.lastStats : lastStats;
-    if (!stats) return;
     // omp's SessionCompactEvent is {compactionEntry, fromExtension} only
     // (shared-events.ts:84-89); reason/willRetry are always undefined/false
     // under real omp runs. Treat undefined as auto (threshold/overflow) when
@@ -992,7 +1207,7 @@ export const registerPiVccCommand = (pi: any) => {
       ctx.compact({
         customInstructions: buildPiVccCustomInstructions(keepUserTurns),
         onComplete: () => {
-          const stats = getLastCompactionStats();
+          const stats = getLastCompactionStats(pi);
           if (stats) {
             scheduleCompactionStatsNotify(ctx, stats);
           } else {
@@ -1014,4 +1229,64 @@ export const registerPiVccCommand = (pi: any) => {
       });
     },
   });
+};
+export const registerVccStatsTool = (pi: any) => {
+  const hasBoolean = typeof pi?.zod?.boolean === "function";
+  const schema = pi?.zod?.object && hasBoolean
+    ? pi.zod.object({
+        history: pi.zod.boolean().optional().describe("Include full history table of all compactions in this session"),
+      })
+    : {};
+  pi.registerTool({
+    name: "vcc_stats",
+    label: "VCC Stats",
+    description: "Show omp-vcc compaction savings — last compaction before→after, tokens saved, percent, and optional history of all compactions in this session. Divider in transcript already shows 256K→20K; this tool surfaces the same numbers with kept/summarized details.",
+    approval: "read",
+    parameters: schema,
+    async execute(_toolCallId: string, params: any, _signal: unknown, _onUpdate: unknown, _ctx: any) {
+      const history = getCompactionHistory(pi);
+      const last = getLastCompactionStats(pi);
+      const wantHistory = params?.history === true;
+      if (!last && history.length === 0) {
+        return { content: [{ type: "text", text: "No compactions yet in this session." }], details: undefined };
+      }
+      if (wantHistory) {
+        const table = formatStatsTable(history);
+        const detail = last ? `\n\n${formatLastStatsDetail(last)}` : "";
+        return { content: [{ type: "text", text: `${table}${detail}` }], details: undefined };
+      }
+      const detail = formatLastStatsDetail(last);
+      const table = history.length > 1 ? `\n\nHistory:\n${formatStatsTable(history)}` : "";
+      return { content: [{ type: "text", text: `${detail}${table}` }], details: undefined };
+    },
+  } as unknown as Parameters<(typeof pi)["registerTool"]>[0]);
+};
+
+export const registerVccStatsCommand = (pi: any) => {
+  const handler = async (args: string, ctx: any) => {
+    const raw = (args || "").trim().toLowerCase();
+    const wantHistory = raw.includes("history") || raw.includes("--history") || raw.includes("all");
+    const history = getCompactionHistory(pi);
+    const last = getLastCompactionStats(pi);
+    const piAny = pi as unknown as { sendMessage?: (msg: unknown, opts?: unknown) => void };
+    if (!last && history.length === 0) {
+      try { piAny.sendMessage?.({ customType: "vcc-stats", content: "No compactions yet in this session.", display: true }, { triggerTurn: false }); } catch {}
+      try { ctx?.ui?.notify?.("No compactions yet.", "info"); } catch {}
+      return;
+    }
+    let output: string;
+    if (wantHistory) {
+      const table = formatStatsTable(history);
+      const detail = last ? `\n\n${formatLastStatsDetail(last)}` : "";
+      output = `${table}${detail}`;
+    } else {
+      const detail = formatLastStatsDetail(last);
+      const table = history.length > 1 ? `\n\nHistory (${history.length} compactions):\n${formatStatsTable(history)}` : "";
+      output = `${detail}${table}`;
+    }
+    try { piAny.sendMessage?.({ customType: "vcc-stats", content: output, display: true }, { triggerTurn: false }); } catch {}
+    try { ctx?.ui?.notify?.(`vcc_stats: ${history.length} compaction(s)`, "info"); } catch {}
+  };
+  pi.registerCommand("vcc-stats", { description: "Show omp-vcc compaction savings (last + history)", handler });
+  pi.registerCommand("omp-vcc-stats", { description: "Alias for /vcc-stats", handler });
 };

package/package.json

@@ -1,18 +1,27 @@
 {
   "name": "omp-vcc",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Algorithmic VCC compaction for omp - fast lossless no-LLM",
-  "type": "module",
+  "author": "Zhu Lin <zhulin@czl.my>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhulinchng/omp-vcc.git"
+  },
+  "homepage": "https://github.com/zhulinchng/omp-vcc#readme",
+  "bugs": {
+    "url": "https://github.com/zhulinchng/omp-vcc/issues"
+  },
   "keywords": [
     "oh-my-pi",
     "omp",
-    "plugin"
+    "pi",
+    "oh-my-pi",
+    "plugin",
+    "vcc",
+    "compaction",
+    "pi-package"
   ],
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/zhulinchng/omp-vcc.git"
-  },
   "files": [
     "extensions",
     "skills",
@@ -99,6 +108,6 @@
     "test": "bun test",
     "smoke": "bun run scripts/smoke.ts",
     "postuninstall": "node scripts/uninstall-reset.js || true",
-    "prepublishOnly": "npm run typecheck"
+    "prepublishOnly": "npm run typecheck && npm test && npm run smoke"
   }
 }

package/scripts/smoke.ts

@@ -55,6 +55,10 @@ try {
     "vcc_recall registered",
     tools.some((t) => t.name === "vcc_recall"),
   );
+  check(
+    "vcc_stats registered",
+    tools.some((t) => t.name === "vcc_stats"),
+  );
   check(
     "omp-vcc command registered",
     commands.some((c) => c.name === "omp-vcc"),
@@ -67,7 +71,15 @@ try {
     "pi-vcc alias registered",
     commands.some((c) => c.name === "pi-vcc"),
   );
-} catch (e) {
+  check(
+    "vcc-stats command registered",
+    commands.some((c) => c.name === "vcc-stats"),
+  );
+  check(
+    "omp-vcc-stats alias registered",
+    commands.some((c) => c.name === "omp-vcc-stats"),
+  );
+  } catch (e) {
   check("extension loads", false, String(e));
 }
 

package/skills/omp-vcc/SKILL.md

@@ -1,35 +1,117 @@
+---
+name: omp-vcc
+description: VCC-inspired algorithmic compaction for oh-my-pi — lossless V_ui summary + ranked brief + V_adapt recall via vcc_recall. Use after auto-compaction (toast 90k→22k), when context grows 50+ turns, or before /omp-vcc keep:N boundaries.
+---
+
 # omp-vcc Skill — VCC-Inspired Algorithmic Compaction
 
-> Lossless, transcript-preserving structured summaries — no LLM calls. Based on `sting8k/pi-vcc` (TypeScript) and `lllyasviel/VCC` (View-oriented Conversation Compiler, arXiv 2603.29678).
+> Lossless, deterministic summarization — no LLM. `V_full` = full transcript, `V_ui` = structured summary + ranked brief, `V_adapt(b, ρ)` = structure-preserving recall. Use `V_ui → V_adapt(query) → V_full[s:e]`: scan summary, query, drill to verbatim lines.
+
+## When to Use
+
+- **After auto compaction** — read `V_ui` first, then `vcc_recall` for anything missing before asking the user to repeat. Toast `omp-vcc: 90.0k→22.0k (76% saved) · kept 1/5 turns` + divider `── 📷 compacted ──` means you just got a `V_ui`.
+- **Context is growing** (50+ turns, heavy tool output) — prefer small keep + recall over a huge tail. Recall is cheap and preserves turn/header/block.
+- **Before risky work** — create a clean boundary: `/omp-vcc keep:2 <focus>` (e.g. `/omp-vcc keep:2 fix auth`). The focus text is sent as the next user message after compaction.
+
+## What You Get (V_ui)
+
+Compacted summary replaces the old transcript; `V_ui` + kept tail is what you see next:
+
+```sh
+[Session Goal]
+- …
+
+[Files And Changes]
+- …
+
+[Commits]
+- …
+
+[Outstanding Context]
+- …
+
+[User Preferences]
+- …
+
+---
+* Read "src/pets.py" (file.txt:18-20)          ← ranked brief, one line per block
+* Edit src/auth.ts { old: "…" (#12:auth.ts:10-40) }
+
+Use `vcc_recall` to search for prior work … Do not redo work already completed.
+```
+
+- **5 sections** are extraction-only (no hallucination): Session Goal, Files And Changes, Commits, Outstanding Context, User Preferences.
+- **Ranked brief**: TF-IDF-ranked tool summaries, capped at **120 lines** (`BRIEF_MAX_LINES=120`), token-budgeted **1100 → 2000 tokens** (`RANKED_BRIEF_BUDGET_TOKENS` floor, `CEILING` 2000, ~15 tok/block). `---` separates sections from brief; earlier lines beyond 120 are dropped tail-first.
+- **Every line keeps a pointer** `(#N)` or `(path:s-e)` so `V_ui → V_full[s:e]` is structural. Trust the summary's pointers; drill for verbatim.
+
+## Commands & Tools
+
+| Task | How | Notes |
+|---|---|---|
+| **Force compaction** | `/omp-vcc` or `/omp-vcc keep:2 fix auth` · alias `/pi-vcc` | `keep:1` is default. Explicit `keep:N` always wins. Default `keep:1` may keep 2–4 turns if tail is tiny (smart-keep ≤5k→≤25k). `keep:0` = compact all, next turn from pure `V_ui`. Focus text after `keep:N` becomes the next user message. |
+| **Check savings** | `/omp-vcc --stats` · `/vcc-stats` · `/omp-vcc-stats`  · `vcc_stats({history:true})` | Last + history table (50-capped). Use to confirm headroom before long edits. |
+| **Recall search** | `/vcc-recall <query> [scope:all] [page:2]` · alias `/pi-vcc-recall` · tool `vcc_recall({query, scope, mode, page, expand})` | 5 hits/page, up to 50 total. See cookbook below. |
+| **Stats tool** | `vcc_stats({history?: boolean})` | Same as `/vcc-stats`. `history:true` = full 50-row table. |
+
+`vcc_recall` params (all optional): `query?: string`, `page?: number` (1-indexed), `scope?: "lineage" | "all"` (default `lineage` = active branch), `mode?: "hybrid" | "touched"` (default `hybrid`), `expand?: number[]` (valid indices only).
+
+No config needed for normal use. Auto `threshold`/`overflow` compaction is already `V_ui` (deterministic, no model call, ~30–470 ms benchmark) when `overrideDefaultCompaction:true` (default). Don't fight it — just use the summary.
+
+## Recall Cookbook — V_adapt
+
+**How search works**: regex first; if invalid or no hits → TF-IDF keyword OR (rare terms weighted, stopwords removed). Each hit preserves turn/header/block, role tags, and `(#N)`. ±2 lines around the match are shown.
 
-## Philosophy
+```sh
+# basic keyword (TF-IDF OR)
+vcc_recall({query:"redis cache"})
+/vcc-recall redis cache
 
-- **Agent trace as structured document** (`user`, `assistant`, `thinking`, `tool_call/result`, `subagent`, compaction boundaries, harness directives). Like VCC's `V_full` identity view defines a line-number coordinate system; `V_ui` gives a one-line tool summary (`* Read "src/pets.py" (file.txt:18-20)`); `V_adapt(b, ρ)` projects via relevance predicate `ρ` (regex / BM25 / embedding / LLM) preserving turn headers, role tags, and `(f:s-e)` pointers.
-- **Fast, deterministic, lossless** — pure extraction, not LLM summarization. 30–470 ms, 35–99% context reduction, pointer invariant `V_ui → V_full[s:e]` holds structurally (SSA-like).
-- **Progressive disclosure** — brief transcript → ranked recall via `vcc_recall` (`ρ = regex→OR`) → drill-down `#N:path` resolves `(session.jsonl:s-e)` into the full view.
+# regex (contains | * + ? {} () [] \ ^ $ .)
+vcc_recall({query:"hook|inject"})
+/vcc-recall hook|inject
 
-## Pipeline
+# scope: include abandoned branches (default is active branch only)
+vcc_recall({query:"auth", scope:"all"})
+/vcc-recall auth scope:all
 
-Calibrated `charsPerToken` from `preparation.tokensBefore` (heuristic fallback 4) → Smart keep-tail (5 k → 25 k) → Build own cut (`firstKeptEntryId`, orphan recovery) → Token-budget tail rescue (`no_anchor` / `oversized_tail` ×2.5) → Normalize (IR lex: escaped JSON→`|` block, `digits→` strip, `<system-reminder>` filter, `TodoWrite`/`ToolSearch`/ANSI strip, `same message.id` merge, `queue-operation` discard, base64 image extract) → Filter noise → Build 5 sections (Session Goal, Files And Changes, Commits, Outstanding Context, User Preferences) → Ranked brief transcript (TF-IDF, `RANKED_BRIEF_BUDGET_TOKENS=1100` ceiling 2000, ~15 tok/block) → Format bracketed sections + separator `---` → Bounded merge (sticky dedup, volatile replace, transcript roll, 120-line cap).
+# pagination (5/page, up to 50)
+vcc_recall({query:"auth", page:2})
+/vcc-recall auth page:2 scope:all
 
-## Usage
+# file index — what was touched, not text search
+vcc_recall({query:"", mode:"touched"})
+/vcc-recall touched mode:touched
 
-- **Auto**: threshold/overflow compaction intercepts `session_before_compact` when `overrideDefaultCompaction=true` (default). No LLM summary; token-budgeted.
-- **Manual**: `/omp-vcc [keep:N] [focus]` — e.g. `/omp-vcc keep:2 fix auth` keeps last 2 user turns. Also `/pi-vcc` alias.
-- **Recall**: `vcc_recall({query:"redis cache", scope:"all", page:1})` or `/vcc-recall hook|inject scope:all page:2`. Regex first, then TF-IDF OR fallback. `mode:'touched'` lists files, `#12:src/auth.ts` drills. 5 per page.
+# drill to verbatim lines — resolves (#N) or (path:s-e)
+vcc_recall({query:"#12:src/auth.ts"})
+/vcc-recall #12:src/auth.ts
+vcc_recall({query:"#18"})                 # whole turn 18
+vcc_recall({query:"#18:src/auth.ts:40-80"}) # slice (offset/limit via drill-down)
 
-## Configuration
+# expand multiple turns by index (from a prior recall's #N)
+vcc_recall({query:"", expand:[12,18,25]})
+```
 
-File `~/.omp/omp-vcc/config.json` (XDG-aware via `$OMP_DIR`/`$PI_CODING_AGENT_DIR`/`$OMP_VCC_CONFIG_PATH`, migrates legacy `~/.pi/agent/pi-vcc-config.json`). Manifest `omp.settings` also exposed: `vccEnabled`, `overrideDefaultCompaction`, `smartKeepTail`, `continueAfterThresholdCompact`, `debug` (`/tmp/omp-vcc-debug.json`).
+**Pick the right query:**
 
-Optional native strategy: add `vcc` to `COMPACTION_METHOD_CHOICES` in `oh-my-pi` (see `docs/configuration.md#native-strategy`).
+- Find an edit/file: `mode:touched` then drill, or `query:"src/auth.ts"` then `#N:path`.
+- Find a decision: `query:"why did we choose|decision|ADR"` (regex).
+- Find an error/tool output: keyword of the error message — full tool output is searchable.
+- Nothing found in `lineage` but you know it existed: retry `scope:all` (abandoned `/clear` branches are excluded by default).
 
-## Verification
+**If you get:**
 
-`bunx tsc --noEmit` → `bun test` → `bun run smoke` → `omp plugin link` → `/omp-vcc keep:1` shows `[Session Goal]` toast `omp-vcc: kept 1/5 turns, ~2.1k tok`.
+- `0 matches` — try keywords (no regex chars) or `scope:all`; check spelling of path.
+- `truncated — showing 50 of 120 matches, refine…` — narrow regex/keywords.
+- `Page 3 is outside 1-2 (7 matches)…` — use `page` in range or refine.
+- `Cannot expand indices outside active lineage: 42. Use scope:'all'` — add `scope:"all"` or pick index from the same lineage.
+- `#N` outside active lineage → same: retry with `scope:"all"` or use a `lineage` hit.
 
-## Related
+## Agent Playbook
 
-- VCC paper `arxiv:2603.29678` — three views, AppWorld evaluation (+1.1–4.2 pts, ½–⅔ tokens)
-- `sting8k/pi-vcc` `@0.7.0` — ported core `extensions/vcc-core/*` verbatim, imports adapted to `@oh-my-pi/*`
-- `lllyasviel/VCC` `VCC.py` — adaptive `SEP`, `match_lines`, transposed modalities
+1. **After any compaction, re-orient from V_ui.** Read Session Goal → Files → Outstanding → brief. Don't re-ask the user for what's already in the summary.
+2. **Small keep + recall beats large keep.** `/omp-vcc keep:1` + `vcc_recall({query:"auth"})` keeps the focused tail small and lets you pull exact history on demand. Only `keep:3+` when you need verbatim recent context immediately after compaction.
+3. **Recall before synthesis.** For any question about prior work (file changed, test added, decision made), call `vcc_recall` proportionally to context size: small session → 1 recall with broad keywords; long/complex session → 2–3 targeted recalls (keywords then drill).
+4. **Create boundaries intentionally.** Before a multi-file refactor or hand-off doc: `/omp-vcc keep:2 continue auth refactor` — next turn starts from a fresh, citable `V_ui`. Verify with `/vcc-stats` (`kept 2/18 turns, 76% saved`) before continuing.
+5. **Don't stall after threshold.** Auto threshold/overflow compaction auto-continues via invisible follow-up (you'll just see the summary and your next turn proceeds). If you issued `/omp-vcc keep:2 <focus>`, that focus text arrives as the next user message — treat it as the goal.
+6. **Use pointers, don't re-derive.** When you quote prior work, cite `(#N)` or `(file:s-e)` from the brief; drill `#N:path` for verbatim to paste, not guessed content.