opencode-context-indicator 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -4,6 +4,20 @@ Notable user-facing changes per release. Dates are commit days (UTC).
 The package also ships a dual V1/V2 plugin — see the README for the surface
 matrix; everything below concerns the V2 path unless stated otherwise.
 
+## 1.5.1 — 2026-10-19
+
+- **Compaction now handled by the real `compaction` hook.** opencode dispatches
+  a `compaction` hook at the start of a compaction request with the same
+  pre-compaction payload as the `context` hook. The plugin registers it and
+  persists the *true* pre-compaction breakdown at that moment — previously the
+  trailing `session.compacted` event re-persisted whatever the last model
+  request had left behind. The event is kept as a fallback (hosts/paths where
+  the hook does not fire), and a no-op compaction ("Nothing to compact yet")
+  writes no stale entry. Same `(stale — compacted)` UX, more accurate numbers.
+- Dev: pinned the `@opencode/plugin` devDependency to `2.0.32`.
+- Tests: T25 / T25a / T25b / T25c (compaction-hook snapshot, no-op guard,
+  event fallback, cold-cache clobber guard) — 62 unit checks total.
+
 ## 1.5.0 — 2026-10-16
 
 Highlights: two new context-health signals — the **provider-reported prompt

package/README.md

@@ -529,9 +529,10 @@ V2 path). It does not register configurable keys of its own.
 
 The package default export is a dual plugin:
 
-* `setup(ctx)` — V2 entry (OpenCode ≥ 2.0.16). Registers a `session.hook("context", …)`
-  to capture the final messages / system prompt / tool schemas right before each
-  model request, subscribes to the event stream (`session.created`,
+* `setup(ctx)` — V2 entry (OpenCode ≥ 2.0.16). Registers `session.hook("context", …)`
+  and `session.hook("compaction", …)` to capture the final messages / system
+  prompt / tool schemas right before each model request (and each compaction
+  request), subscribes to the event stream (`session.created`,
   `session.step.ended`, `session.idle`, `session.compacted`, failure events),
   records limits from the model registry and registers the
   `/context` + `/context-breakdown` slash commands (via
@@ -549,12 +550,15 @@ duplicate final summaries are suppressed with an atomic claim marker
 (`lib/dedup.js`). Every file / estimate / subagent path is fault-tolerant: a
 failure is logged and never breaks the main event or toast path.
 
-**Compaction staleness.** OpenCode's compaction runs a separate flow that fires
-no `context` hook, so the numbers a `session.compacted` write re-persists are
-the *pre-compaction* ones. The plugin flags such an entry
-(`compactStale` in `state.json`) and every surface shows `(stale — compacted)`
-until the next model request refreshes the breakdown — i.e. the data is exactly
-as fresh as the last model request in the session.
+**Compaction staleness.** OpenCode dispatches a dedicated `compaction` hook at
+the start of a compaction request, carrying the same pre-compaction payload as
+the `context` hook. The plugin registers it and persists the *true*
+pre-compaction breakdown at that moment, flagging the entry stale
+(`compactStale` in `state.json`) so every surface shows `(stale — compacted)`
+until the next model request refreshes it. The trailing `session.compacted`
+event is kept as a fallback (for hosts or paths where the hook does not fire);
+a no-op compaction ("Nothing to compact yet") writes no stale entry. The data
+is always exactly as fresh as the last model request in the session.
 
 This plugin does not touch `opencode-token-monitor`
 (`token_stats` / `token_history` / `token_export` keep working unchanged).

package/index.js

@@ -150,7 +150,7 @@
  */
 
 import { makeV1 } from "./lib/v1.js";
-import { handleV2Event, onV2Context, estimateBreakdownFromContext, estimateBreakdownFromClientMessages } from "./lib/v2.js";
+import { handleV2Event, onV2Context, onV2Compaction, estimateBreakdownFromContext, estimateBreakdownFromClientMessages } from "./lib/v2.js";
 import { breakdownCategories, computeReclaim, contentFingerprint, estimateTokens, extractToolTarget, isSafeSessionKey, safeCell, safeReclaim, safeSaneOrNull, safeToolOutByTool, sumCategories, toolOutEntries } from "./lib/estimate.js";
 import {
   commandContextBreakdown,
@@ -170,7 +170,7 @@ import {
   modelLimits,
   reserveFor,
 } from "./lib/limits.js";
-import { lastKnownCacheRead, lastKnownCacheWrite, sessionAgentCache, sessionParentCache } from "./lib/cache.js";
+import { lastKnownCacheRead, lastKnownCacheWrite, lastKnownCtxCache, lastKnownInputCache, lastKnownReasoningCache, sessionAgentCache, sessionParentCache } from "./lib/cache.js";
 import {
   logErr,
   readStateSnapshot,
@@ -204,6 +204,7 @@ export {
   estimateBreakdownFromContext,
   estimateBreakdownFromClientMessages,
   onV2Context,
+  onV2Compaction,
   safeToolOutByTool,
   toolOutEntries,
   sumCategories,
@@ -218,6 +219,10 @@ export {
   safeSaneOrNull,
   lastKnownCacheRead,
   lastKnownCacheWrite,
+  lastKnownCtxCache,
+  lastKnownInputCache,
+  lastKnownReasoningCache,
+  handleV2Event,
 };
 
 // ---------------------------------------------------------------------------
@@ -238,6 +243,19 @@ export default {
       logErr("v2 context hook registration failed", err);
     }
 
+    // The compaction request carries the same pre-compaction context payload as
+    // the context hook. Registering it lets us persist the TRUE pre-compaction
+    // breakdown (see onV2Compaction); the `session.compacted` event then only
+    // acts as a fallback. A registration failure is non-fatal — the event path
+    // still marks the entry stale.
+    try {
+      registrations.push(
+        await ctx.session.hook("compaction", (context) => onV2Compaction(context)),
+      );
+    } catch (err) {
+      logErr("v2 compaction hook registration failed", err);
+    }
+
     // The model registry is captured asynchronously through ensureModelLimits
     // (ctx.model.list(), rank 3) — the authoritative source that carries the
     // user's merged config overrides. ctx.model.transform fires synchronously

package/lib/cache.js

@@ -69,6 +69,13 @@ const lastErrorToast = new Map();
 // sessionID -> timestamp — dedup for session.compacted toasts
 const lastCompactedToast = new Map();
 
+// sessionID -> timestamp — when the `compaction` HOOK last fired for a session.
+// The hook is dispatched at the START of a compaction request (before the model
+// summarises), carrying the exact pre-compaction context, so it lets us persist
+// the TRUE pre-compaction breakdown. It also tells the later `session.compacted`
+// EVENT that the hook already marked the entry (the event stays a fallback).
+const lastCompactionHookAt = new Map();
+
 // sessionID -> parentID (null = main session) — [main]/[sub] attribution cache
 const sessionParentCache = new Map();
 
@@ -144,6 +151,8 @@ function clearSessionTracking(sessionID, keepToastDedup = false) {
   v2ContextFetchTimes.delete(sessionID);
   // Per-session tool-schema TTL cache (see estimateBreakdownFromContext).
   toolSchemasBySession.delete(sessionID);
+  // Compaction-hook marker (re-armed by the next compaction on this session).
+  lastCompactionHookAt.delete(sessionID);
 }
 
 export {
@@ -168,6 +177,7 @@ export {
   lastBdWrite,
   lastErrorToast,
   lastCompactedToast,
+  lastCompactionHookAt,
   sessionParentCache,
   sessionTotals,
   sessionAgentCache,

package/lib/v2.js

@@ -29,6 +29,7 @@ import {
   lastBdWrite,
   lastKnownCtx,
   lastKnownCtxCache,
+  lastCompactionHookAt,
   lastKnownCacheRead,
   lastKnownCacheReadCache,
   lastKnownCacheWrite,
@@ -68,6 +69,11 @@ const V2_CONTEXT_FETCH_THROTTLE_MS = 5000; // min gap between fallback fetches
 // event handlers): cap each at 3s so a slow/hung client cannot pin resources.
 const V2_FALLBACK_TIMEOUT_MS = 3000;
 
+// Window within which a `session.compacted` EVENT is considered already handled
+// by the preceding `compaction` HOOK: if the hook marked the entry recently, the
+// event only logs + clears tracking instead of re-persisting the snapshot.
+const COMPACTION_HOOK_FALLBACK_MS = 60000;
+
 // Estimate the per-category breakdown directly from a V2 SessionContext.
 // `context.messages` are @opencode/ai Message objects:
 //   { role, content: [ {type:"text",text} | {type:"media"} |
@@ -329,6 +335,93 @@ function onV2Context(context) {
   }
 }
 
+// V2 compaction hook handler: opencode dispatches `compaction` at the START of a
+// compaction request with the SAME pre-compaction payload as the context hook
+// (system / messages / tools / model). We use it to persist the TRUE
+// pre-compaction breakdown instead of relying on the `session.compacted` event
+// to re-persist whatever a previous request left behind.
+//
+// The entry is marked stale BY CONSTRUCTION (the context is about to be
+// compacted, so the numbers change once the summary lands and the next context
+// hook fires). Guard: the hook also fires for a NO-OP compaction ("Nothing to
+// compact yet") on a session with no completed request — there is no measured
+// context to mark, so we only cache and skip the state write (no fake stale
+// badge).
+function onV2Compaction(context) {
+  try {
+    if (!context || typeof context !== "object") return;
+    const sid = context.sessionID;
+    if (!sid) return;
+
+    const parts = estimateBreakdownFromContext(context, sid);
+    breakdownCache.set(sid, {
+      ...parts,
+      capturedAt: Date.now(),
+      source: "compaction-hook",
+    });
+    pruneMap(breakdownCache, MAX_TRACKED_SESSIONS);
+
+    const model = context.model;
+    if (model && typeof model === "object") {
+      if (typeof model.id === "string") lastKnownModelCache.set(sid, model.id);
+      if (typeof model.providerID === "string") {
+        lastKnownProviderCache.set(sid, model.providerID);
+      }
+      pruneMap(lastKnownModelCache, MAX_TRACKED_SESSIONS);
+      pruneMap(lastKnownProviderCache, MAX_TRACKED_SESSIONS);
+    }
+
+    // Arm the fallback guard for the trailing `session.compacted` event.
+    lastCompactionHookAt.set(sid, Date.now());
+    pruneMap(lastCompactionHookAt, MAX_TRACKED_SESSIONS);
+
+    const ctxTokens = lastKnownCtx(sid);
+    if (ctxTokens > 0) {
+      const lines = buildLiveLinesV2(
+        sid,
+        lastKnownModel(sid),
+        lastKnownProvider(sid),
+        lastKnownInput(sid),
+        ctxTokens,
+        lastKnownReasoning(sid),
+      );
+      writeStateFile(
+        sid,
+        lastKnownModel(sid),
+        lastKnownProvider(sid),
+        lastKnownInput(sid),
+        ctxTokens,
+        lastKnownReasoning(sid),
+        {
+          compacted: true,
+          cacheRead: lastKnownCacheRead(sid),
+          cacheWrite: lastKnownCacheWrite(sid),
+        },
+      );
+      // Claim key derived from the PAYLOAD shape (message count + total
+      // estimated chars): identical across plugin instances for the SAME
+      // compaction (cross-instance dedup preserved) yet distinct per compaction
+      // — a session-only key would log just the first compaction on a session.
+      const messages = Array.isArray(context.messages) ? context.messages : [];
+      const sig =
+        `${messages.length}:` +
+        (parts.userChars +
+          parts.assistantChars +
+          parts.reasoningChars +
+          parts.toolArgsChars +
+          parts.toolOutChars +
+          (parts.systemChars || 0) +
+          (parts.toolSchemasChars || 0));
+      pushFinalSummary(`compaction-hook:${sid}:${sig}`, [
+        `[${new Date().toISOString()}] COMPACTION (hook) session=${sid} — pre-compaction snapshot captured`,
+        ...lines.slice(1),
+      ]);
+    }
+  } catch (err) {
+    logErr("v2 compaction hook failed", err);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // V2 fallback: derive the message-based categories from the session's persisted
 // message list when the context hook did NOT populate the cache for this
@@ -685,23 +778,30 @@ async function handleV2Event(ctx, event) {
         lastKnownCtx(sid),
         lastKnownReasoning(sid),
       );
-      writeStateFile(
-        sid,
-        lastKnownModel(sid),
-        lastKnownProvider(sid),
-        lastKnownInput(sid),
-        lastKnownCtx(sid),
-        lastKnownReasoning(sid),
-        // This write re-persists the PRE-compaction snapshot (the compaction
-        // flow fires no context hook — see README): mark the entry stale so the
-        // UI shows the numbers as pre-compaction until the next model request
-        // refreshes them.
-        {
-          compacted: true,
-          cacheRead: lastKnownCacheRead(sid),
-          cacheWrite: lastKnownCacheWrite(sid),
-        },
-      );
+      // The `compaction` HOOK already captured + persisted the exact
+      // pre-compaction snapshot and marked the entry stale. This event is now a
+      // FALLBACK: it re-persists only when the hook did NOT fire recently (host
+      // gap, mirror instance, or a compaction path that bypassed the hook).
+      // Either way the write re-persists the PRE-compaction numbers and marks
+      // the entry stale, so the UI shows them as pre-compaction until the next
+      // model request refreshes them.
+      const hookAt = lastCompactionHookAt.get(sid) || 0;
+      const handledByHook = Date.now() - hookAt < COMPACTION_HOOK_FALLBACK_MS;
+      if (!handledByHook) {
+        writeStateFile(
+          sid,
+          lastKnownModel(sid),
+          lastKnownProvider(sid),
+          lastKnownInput(sid),
+          lastKnownCtx(sid),
+          lastKnownReasoning(sid),
+          {
+            compacted: true,
+            cacheRead: lastKnownCacheRead(sid),
+            cacheWrite: lastKnownCacheWrite(sid),
+          },
+        );
+      }
       pushFinalSummary(
         `compacted:${event.id ?? sid}`,
         [
@@ -886,6 +986,7 @@ async function handleV2Event(ctx, event) {
 
 export {
   onV2Context,
+  onV2Compaction,
   handleV2Event,
   estimateBreakdownFromContext,
   estimateBreakdownFromClientMessages,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-context-indicator",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Real-time context-window usage for OpenCode: per-category token breakdown, a zero-LLM /cx panel with per-session cost and a searchable family-session picker, and a TUI sidebar. Dual V1 + V2 plugin entry.",
   "type": "module",
   "license": "MIT",
@@ -64,7 +64,7 @@
     "@opentui/solid": "0.5.17"
   },
   "devDependencies": {
-    "@opencode/plugin": "2.0.30",
+    "@opencode/plugin": "2.0.32",
     "@opentui/core": "0.5.17",
     "@types/node": "26.6.3",
     "esbuild": "^0.28.2",