pi-mega-compact 0.4.11 → 0.4.13

package/README.md

@@ -111,50 +111,45 @@ OpenAI-style contract and the `MEGACOMPACT_EMBEDDING_KEY` / `MEGACOMPACT_EMBEDDI
 ### Requirements
 
 - **Node >= 18**
-- `npm install` builds the **`better-sqlite3`** native module (one-time, local
+- install builds the **`better-sqlite3`** native module (one-time, local
   compile). No network call and no API key are needed at runtime.
-- A pi coding agent install that loads extensions from `~/.pi/agent/extensions/`.
+- A pi coding agent install with package support (`pi install` / `pi update
+  --extensions`). npm-installed packages are auto-discovered via the package's
+  `pi` manifest entry; local checkouts load from `~/.pi/agent/extensions/`.
 
 ### Install from npm (recommended)
 
-```bash
-npm install pi-mega-compact
-```
-
-This places the package in `node_modules` and exposes the extension entry at
-`node_modules/pi-mega-compact/extensions/mega-compact.ts`. Then point pi at it
-(see "Register with pi" below).
-
-### Register with pi
-
-Add the extension to your pi config's `pi.extensions` list, pointing at the
-installed entry (npm path or a symlink into pi's extensions dir — either works):
-
-```jsonc
-{
-  "pi": {
-    "extensions": ["pi-mega-compact/extensions/mega-compact.ts"]
-  }
-}
-```
-
-Or symlink the installed package into pi's extensions dir (the simplest path if
-you run pi from the same machine):
+pi installs extensions as **packages**. `pi install npm:<pkg>` writes an
+`npm:` source into your pi config's `packages` array; pi then auto-discovers the
+extension from the package's own `"pi": { "extensions": [...] }` manifest entry
+— **no manual `settings.json` edit is needed**.
 
 ```bash
-ln -s "$(npm root)/pi-mega-compact" ~/.pi/agent/extensions/pi-mega-compact
+pi install npm:pi-mega-compact        # first time: adds to packages + installs
+pi update --extensions                # thereafter: pulls the latest published version
 ```
 
-> **From a git checkout (development).** To hack on the extension, clone instead
-> and build locally:
+`pi update --extensions` refreshes every `npm:` entry in `packages` (including on
+other devices that share this config). The package ships both the TypeScript
+source (which pi loads directly) and the compiled `dist/`, so nothing else needs
+building.
+
+> **Tip — keep the spec unpinned.** Use `npm:pi-mega-compact`, not
+> `npm:pi-mega-compact@0.4.11`. Version-pinned specs are *skipped* by
+> `pi update --extensions`, so a pin would freeze you on that release.
+
+> **From a git checkout (development only).** To hack on the extension, clone and
+> build locally, then symlink it into pi's extensions dir — but this bypasses the
+> package manager, so it is NOT updated by `pi update --extensions`. Convert to the
+> npm package (above) before shipping. The bundled `./install.sh` helper does the
+> symlink + config edit (needs `jq`).
+>
 > ```bash
 > git clone https://github.com/TheArchitectit/pi-mega-compact.git \
 >   ~/.pi/agent/extensions/pi-mega-compact
 > cd ~/.pi/agent/extensions/pi-mega-compact
 > npm install && npm run build
 > ```
-> The bundled `./install.sh` helper (`copy`) / `./install.sh -s` (`symlink`) does
-> the same and also registers the path in pi's config (needs `jq`).
 
 ### Verify
 
@@ -166,17 +161,17 @@ npm run lint      # tsc --noEmit + guardrails scan clean
 ### Uninstall
 
 ```bash
+pi uninstall npm:pi-mega-compact   # removes from settings.packages + the npm tree
+# or, to keep the config entry but drop the package:
 npm uninstall pi-mega-compact
 ```
 
-If you symlinked it into pi's extensions dir, also remove that link:
+If you symlinked it into pi's extensions dir (dev only), also remove that link:
 
 ```bash
 rm -f ~/.pi/agent/extensions/pi-mega-compact
 ```
 
-Then remove the path from pi's `pi.extensions` array.
-
 ---
 
 ## How to use it

package/dist/extensions/mega-compact.js

@@ -255,25 +255,43 @@ export default function (pi) {
             const usedStr = `${C.cyan}${fmt(st.totalTokenEstimate)} sess${C.reset} / ${C.blue}${fmt(repo.totalTokenEstimate)} repo${C.reset}`;
             const agentStr = activeAgents > 0 ? ` │ 🤖 ${activeAgents} agent${activeAgents === 1 ? "" : "s"}` : "";
             const turnStr = currentTurn > 0 ? ` │ turn ${currentTurn}` : "";
+            // Phase 3 — pulsing status glyph while a compaction is in flight.
+            const pulse = pulsing ? `${C.cyan}${PULSE[Math.floor(Date.now() / 250) % PULSE.length]}${C.reset} ` : "";
             const lines = [
-                ` ${C.amber}⚡ ${config.tier}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} chkpt${st.checkpointCount === 1 ? "" : "s"}${agentStr}${turnStr}`,
+                ` ${C.amber}⚡ ${config.tier}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} chkpt${agentStr}${turnStr}`,
                 `   ${triggerLabel} │ ${C.magenta}dedup: ${dedupStr}${C.reset} │ ${C.gray}used:${C.reset} ${usedStr} │ ${C.gray}saved:${C.reset} ${savedStr}`,
             ];
+            // Phase 3 — compact progress bar: session tokens saved toward the rolling goal.
+            if (rt.tokensSaved > 0) {
+                const goal = Math.max(savedGoal, 1);
+                const pct = Math.min(100, Math.round((rt.tokensSaved / goal) * 100));
+                const filled = Math.round((pct / 100) * 10);
+                const bar = "▓".repeat(filled) + "░".repeat(10 - filled);
+                lines.push(`   ${C.green}saved ${fmt(rt.tokensSaved)} ${bar}${C.reset} ${pct}% of ${fmt(goal)}`);
+            }
             // Live "now processing" line — teal while fresh (≤4s), then the last-seen
             // action keeps the widget lively. Cleared on session reset.
-            if (tierTrace) {
-                // Per-tier dedup progress is more relevant than the last action while a
-                // compaction is mid-flight, so prefer it when fresh.
-                const fresh = Date.now() - lastActivityAt < 4000;
-                if (fresh)
-                    lines.push(`   ${tierTrace}`);
-                else if (currentActivity)
-                    lines.push(`   ${C.dim}${currentActivity}${C.reset}`);
+            const fresh = Date.now() - lastActivityAt < 4000;
+            if (tierTrace && fresh) {
+                lines.push(`   ${pulse}${tierTrace}`);
             }
             else if (currentActivity) {
-                const fresh = Date.now() - lastActivityAt < 4000;
                 lines.push(`   ${fresh ? C.teal : C.dim}${currentActivity}${C.reset}`);
             }
+            else if (pulsing) {
+                lines.push(`   ${pulse}${C.teal}compacting…${C.reset}`);
+            }
+            // Phase 3 — explain-why line (fresh only).
+            if (lastWhy && fresh)
+                lines.push(`   ${C.gray}${lastWhy}${C.reset}`);
+            // Phase 3 — recall/activity ticker (most-recent first), fresh only.
+            if (fresh) {
+                for (let i = ticker.length - 1; i >= 0; i--) {
+                    if (lines.length >= 10)
+                        break; // MAX_WIDGET_LINES guard
+                    lines.push(`   ${i === ticker.length - 1 ? "" : C.dim}${ticker[i].text}${C.reset}`);
+                }
+            }
             ctx.ui.setWidget(WIDGET_KEY, lines, { placement: "aboveEditor" });
         }
     }
@@ -305,6 +323,24 @@ export default function (pi) {
     // Built from the store's sync onTier callback during a compaction so the user
     // watches each tier evaluate in real time. Cleared once the outcome settles.
     let tierTrace;
+    const ticker = [];
+    const TICKER_MAX = 5;
+    function pushTicker(text) {
+        ticker.push({ text, at: Date.now() });
+        while (ticker.length > TICKER_MAX)
+            ticker.shift();
+        lastActivityAt = Date.now();
+    }
+    // Pulsing status: set true while a compaction is in flight, cleared on result.
+    let pulsing = false;
+    // Rolling "saved" goal for the progress bar — grows as we save more, so the
+    // bar always has a meaningful denominator (never sits at 100% forever).
+    let savedGoal = 50_000;
+    // Last explain-why line (dedup reason / anchor-kept / superseded), surfaced
+    // while fresh.
+    let lastWhy = undefined;
+    // Cycling glyph phases for the pulsing status.
+    const PULSE = ["◐", "◓", "◑", "◒"];
     // ANSI palette for the toolbar. The pi TUI's Text component preserves ANSI
     // escape codes (see wrapTextWithAnsi), so raw escapes render as colors. No
     // chalk dependency needed — these are just strings.
@@ -344,6 +380,10 @@ export default function (pi) {
         currentActivity = undefined;
         lastActivityAt = 0;
         tierTrace = undefined;
+        ticker.length = 0;
+        pulsing = false;
+        savedGoal = 50_000;
+        lastWhy = undefined;
     }
     /** Build the sync onTier callback that paints the live per-tier trace. */
     function makeTierCallback(ctx) {
@@ -382,6 +422,7 @@ export default function (pi) {
         const keepFrom = opts.keepFrom ?? Math.max(0, view.length - config.preserveRecent);
         if (keepFrom <= 0)
             return { skipped: true };
+        pulsing = true; // animate the status line while the (sync) pipeline runs
         const result = compactSession({
             sessionId: sid,
             messages: view,
@@ -390,6 +431,7 @@ export default function (pi) {
             timestamp: Date.now(),
             onTier: makeTierCallback(ctx),
         }, store);
+        pulsing = false;
         if (result.skipped)
             return { skipped: true };
         if (!result.deduped) {
@@ -410,6 +452,10 @@ export default function (pi) {
         rt.tokensSaved += saved;
         if (result.deduped)
             rt.dedupSkips++;
+        // Grow the rolling "saved" goal so the progress bar always has a fresh
+        // denominator (we don't want it pinned at 100% once we pass an old target).
+        if (rt.tokensSaved > savedGoal)
+            savedGoal = Math.ceil((rt.tokensSaved * 1.25) / 10_000) * 10_000;
         // Live toolbar "now processing" line: what file/region just got compacted or
         // deduped. Reset to the last-seen action after a few seconds (see snapshot).
         const files = result.filesModified ?? [];
@@ -420,6 +466,16 @@ export default function (pi) {
             ? `♻ deduped ${fileLabel}`
             : `🗜 compacted ${result.checkpointId} · ${fileLabel}`;
         lastActivityAt = Date.now();
+        // Explain-why line: surfaced while fresh. Pulls the dedup reason (which for
+        // L2 includes the cosine sim) so the user sees WHY a region was kept/dropped.
+        lastWhy = result.deduped
+            ? `why: deduped@${result.dedupReason ?? "tier"}`
+            : `why: compacted → ${result.checkpointId}`;
+        // Recall/activity ticker: record this event in the ring buffer.
+        const savedK = (saved / 1000).toFixed(1);
+        pushTicker(result.deduped
+            ? `${C.green}♻${C.reset} deduped ${fileLabel} · ${savedK}k saved`
+            : `${C.cyan}🗜${C.reset} ${result.checkpointId} · +${savedK}k · ${fileLabel}`);
         // The per-tier trace has settled into the final outcome — fold it back into
         // the activity line and stop showing the live trace.
         tierTrace = undefined;
@@ -472,6 +528,14 @@ export default function (pi) {
         const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
         const result = recallAndInline({ sessionId: sid, query, limit: config.autoInlineK, source, skipInjected: true }, store);
         dashboard.event("recall", { source, query: query.slice(0, 120), injected: result.toInject.length, empty: result.empty });
+        if (!result.empty && result.toInject.length > 0) {
+            const top = result.toInject[0];
+            const scorePct = Math.round((top.score ?? 0) * 100);
+            const files = top.checkpoint.filesModified ?? [];
+            const label = files.length ? files.map((f) => f.split("/").pop() ?? f).slice(0, 2).join(", ") : top.checkpoint.checkpointId;
+            pushTicker(`${C.amber}↩${C.reset} recalled ${top.checkpoint.checkpointId} · ${scorePct}% · ${label}`);
+            lastWhy = `why: recalled@${scorePct}% (${result.toInject.length} chkpt)`;
+        }
         return result;
     }
     // ---- Session lifecycle (state reset points) -------------------------------

package/extensions/mega-compact.ts

@@ -358,21 +358,38 @@ export default function (pi: ExtensionAPI) {
       const usedStr = `${C.cyan}${fmt(st.totalTokenEstimate)} sess${C.reset} / ${C.blue}${fmt(repo.totalTokenEstimate)} repo${C.reset}`;
       const agentStr = activeAgents > 0 ? ` │ 🤖 ${activeAgents} agent${activeAgents === 1 ? "" : "s"}` : "";
       const turnStr = currentTurn > 0 ? ` │ turn ${currentTurn}` : "";
+      // Phase 3 — pulsing status glyph while a compaction is in flight.
+      const pulse = pulsing ? `${C.cyan}${PULSE[Math.floor(Date.now() / 250) % PULSE.length]}${C.reset} ` : "";
       const lines = [
-        ` ${C.amber}⚡ ${config.tier}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} chkpt${st.checkpointCount === 1 ? "" : "s"}${agentStr}${turnStr}`,
+        ` ${C.amber}⚡ ${config.tier}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} chkpt${agentStr}${turnStr}`,
         `   ${triggerLabel} │ ${C.magenta}dedup: ${dedupStr}${C.reset} │ ${C.gray}used:${C.reset} ${usedStr} │ ${C.gray}saved:${C.reset} ${savedStr}`,
       ];
+      // Phase 3 — compact progress bar: session tokens saved toward the rolling goal.
+      if (rt.tokensSaved > 0) {
+        const goal = Math.max(savedGoal, 1);
+        const pct = Math.min(100, Math.round((rt.tokensSaved / goal) * 100));
+        const filled = Math.round((pct / 100) * 10);
+        const bar = "▓".repeat(filled) + "░".repeat(10 - filled);
+        lines.push(`   ${C.green}saved ${fmt(rt.tokensSaved)} ${bar}${C.reset} ${pct}% of ${fmt(goal)}`);
+      }
       // Live "now processing" line — teal while fresh (≤4s), then the last-seen
       // action keeps the widget lively. Cleared on session reset.
-      if (tierTrace) {
-        // Per-tier dedup progress is more relevant than the last action while a
-        // compaction is mid-flight, so prefer it when fresh.
-        const fresh = Date.now() - lastActivityAt < 4000;
-        if (fresh) lines.push(`   ${tierTrace}`);
-        else if (currentActivity) lines.push(`   ${C.dim}${currentActivity}${C.reset}`);
+      const fresh = Date.now() - lastActivityAt < 4000;
+      if (tierTrace && fresh) {
+        lines.push(`   ${pulse}${tierTrace}`);
       } else if (currentActivity) {
-        const fresh = Date.now() - lastActivityAt < 4000;
         lines.push(`   ${fresh ? C.teal : C.dim}${currentActivity}${C.reset}`);
+      } else if (pulsing) {
+        lines.push(`   ${pulse}${C.teal}compacting…${C.reset}`);
+      }
+      // Phase 3 — explain-why line (fresh only).
+      if (lastWhy && fresh) lines.push(`   ${C.gray}${lastWhy}${C.reset}`);
+      // Phase 3 — recall/activity ticker (most-recent first), fresh only.
+      if (fresh) {
+        for (let i = ticker.length - 1; i >= 0; i--) {
+          if (lines.length >= 10) break; // MAX_WIDGET_LINES guard
+          lines.push(`   ${i === ticker.length - 1 ? "" : C.dim}${ticker[i].text}${C.reset}`);
+        }
       }
       ctx.ui.setWidget(WIDGET_KEY, lines, { placement: "aboveEditor" });
     }
@@ -406,6 +423,27 @@ export default function (pi: ExtensionAPI) {
   // Built from the store's sync onTier callback during a compaction so the user
   // watches each tier evaluate in real time. Cleared once the outcome settles.
   let tierTrace: string | undefined;
+  // Phase 3 — standout toolbar state.
+  // Recall/activity ticker: a small ring buffer (≤5) of recent compact/recall
+  // events so the widget shows a live history instead of a single last action.
+  interface TickerEntry { text: string; at: number; }
+  const ticker: TickerEntry[] = [];
+  const TICKER_MAX = 5;
+  function pushTicker(text: string): void {
+    ticker.push({ text, at: Date.now() });
+    while (ticker.length > TICKER_MAX) ticker.shift();
+    lastActivityAt = Date.now();
+  }
+  // Pulsing status: set true while a compaction is in flight, cleared on result.
+  let pulsing = false;
+  // Rolling "saved" goal for the progress bar — grows as we save more, so the
+  // bar always has a meaningful denominator (never sits at 100% forever).
+  let savedGoal = 50_000;
+  // Last explain-why line (dedup reason / anchor-kept / superseded), surfaced
+  // while fresh.
+  let lastWhy: string | undefined = undefined;
+  // Cycling glyph phases for the pulsing status.
+  const PULSE = ["◐", "◓", "◑", "◒"];
   // ANSI palette for the toolbar. The pi TUI's Text component preserves ANSI
   // escape codes (see wrapTextWithAnsi), so raw escapes render as colors. No
   // chalk dependency needed — these are just strings.
@@ -446,6 +484,10 @@ export default function (pi: ExtensionAPI) {
     currentActivity = undefined;
     lastActivityAt = 0;
     tierTrace = undefined;
+    ticker.length = 0;
+    pulsing = false;
+    savedGoal = 50_000;
+    lastWhy = undefined;
   }
 
   /** Build the sync onTier callback that paints the live per-tier trace. */
@@ -488,6 +530,7 @@ export default function (pi: ExtensionAPI) {
     const keepFrom = opts.keepFrom ?? Math.max(0, view.length - config.preserveRecent);
     if (keepFrom <= 0) return { skipped: true as const };
 
+    pulsing = true; // animate the status line while the (sync) pipeline runs
     const result = compactSession(
       {
         sessionId: sid,
@@ -499,6 +542,7 @@ export default function (pi: ExtensionAPI) {
       },
       store,
     );
+    pulsing = false;
 
     if (result.skipped) return { skipped: true as const };
     if (!result.deduped) {
@@ -518,6 +562,9 @@ export default function (pi: ExtensionAPI) {
       : Math.max(0, result.originalTokenEstimate - result.tokenEstimate);
     rt.tokensSaved += saved;
     if (result.deduped) rt.dedupSkips++;
+    // Grow the rolling "saved" goal so the progress bar always has a fresh
+    // denominator (we don't want it pinned at 100% once we pass an old target).
+    if (rt.tokensSaved > savedGoal) savedGoal = Math.ceil((rt.tokensSaved * 1.25) / 10_000) * 10_000;
 
     // Live toolbar "now processing" line: what file/region just got compacted or
     // deduped. Reset to the last-seen action after a few seconds (see snapshot).
@@ -529,6 +576,18 @@ export default function (pi: ExtensionAPI) {
       ? `♻ deduped ${fileLabel}`
       : `🗜 compacted ${result.checkpointId} · ${fileLabel}`;
     lastActivityAt = Date.now();
+    // Explain-why line: surfaced while fresh. Pulls the dedup reason (which for
+    // L2 includes the cosine sim) so the user sees WHY a region was kept/dropped.
+    lastWhy = result.deduped
+      ? `why: deduped@${result.dedupReason ?? "tier"}`
+      : `why: compacted → ${result.checkpointId}`;
+    // Recall/activity ticker: record this event in the ring buffer.
+    const savedK = (saved / 1000).toFixed(1);
+    pushTicker(
+      result.deduped
+        ? `${C.green}♻${C.reset} deduped ${fileLabel} · ${savedK}k saved`
+        : `${C.cyan}🗜${C.reset} ${result.checkpointId} · +${savedK}k · ${fileLabel}`,
+    );
     // The per-tier trace has settled into the final outcome — fold it back into
     // the activity line and stop showing the live trace.
     tierTrace = undefined;
@@ -590,6 +649,14 @@ export default function (pi: ExtensionAPI) {
       store,
     );
     dashboard.event("recall", { source, query: query.slice(0, 120), injected: result.toInject.length, empty: result.empty });
+    if (!result.empty && result.toInject.length > 0) {
+      const top = result.toInject[0];
+      const scorePct = Math.round((top.score ?? 0) * 100);
+      const files = top.checkpoint.filesModified ?? [];
+      const label = files.length ? files.map((f) => f.split("/").pop() ?? f).slice(0, 2).join(", ") : top.checkpoint.checkpointId;
+      pushTicker(`${C.amber}↩${C.reset} recalled ${top.checkpoint.checkpointId} · ${scorePct}% · ${label}`);
+      lastWhy = `why: recalled@${scorePct}% (${result.toInject.length} chkpt)`;
+    }
     return result;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-2-Clause",