@jhanink/opencode-context-compaction 0.1.1 → 0.1.2

package/README.md

@@ -59,8 +59,6 @@ Or as a package:
 opencode plugin add @jhanink/opencode-context-compaction
 ```
 
-The unscoped name `opencode-context-compaction` is deprecated and points here.
-
 ## Options
 
 Set options by loading the plugin from `opencode.json(c)` — and **do not** also
@@ -95,6 +93,7 @@ keys you set are overridden:
 | `idleMs` | `45000` | How long a session must be quiet before acting. |
 | `cooldownMs` | `600000` | Minimum gap between compactions of one session. |
 | `dryRun` | `false` | Log and notify instead of compacting. |
+| `history` | `false` | Record decisions and compactions in plugin storage. |
 
 To watch decisions for a day before letting it rewrite anything, add
 `"dryRun": true` — the toasts then tell you what it *would* have done.
@@ -105,13 +104,44 @@ Set it where a session stops being useful to you, not where the provider starts
 refusing it. Per-request cost is dominated by cache reads, which are cheap, so the
 real reasons to compact are transcript drift and the ceiling itself.
 
+## History
+
+Off by default. Records are written to plugin storage — which is OpenCode's
+database — so keeping them is a choice rather than a side effect. Set
+`"history": true` to record what the trigger decided, and every compaction that
+actually happened, including the ones OpenCode starts on its own.
+
+Both record types carry sizes and counts, never message content:
+
+| Record | Written when | Carries |
+| --- | --- | --- |
+| `decision` | the trigger evaluates a session | action, reason, estimated tokens, budget, dry run, gap since the last compaction |
+| `compaction` | a compaction begins | origin, estimated tokens, characters, message count, model |
+
+`origin` is the field worth having. OpenCode records *every* compaction in its
+own database as `reason: manual` — whether you asked for it, the built-in trigger
+did, or this plugin did — so without this the three are indistinguishable, and
+there is no way to tell whether a budget fires when it should.
+
+The records stay small because they do not duplicate what OpenCode already
+stores: the per-request token counts you would want alongside them are already in
+`opencode.db`. The newest 2,000 are kept, under the `history/` key prefix.
+
+To read them:
+
+```sh
+sqlite3 ~/.local/share/opencode/opencode.db \
+  "select key, value from kv where key like 'plugin:%history/%' order by key;"
+```
+
 ## How it works
 
 ```
-session.hook("context")  →  estimate tokens  →  debounce (idleMs)
-                                              →  decide (budget, cooldown, subagent)
-                                              →  ctx.session.compact({ delivery: "queue" })
-                                              →  RPC event  →  toast
+session.hook("context")     →  estimate tokens  →  debounce (idleMs)
+                                                 →  decide (budget, cooldown, subagent)
+                                                 →  ctx.session.compact({ delivery: "queue" })
+                                                 →  RPC event  →  toast
+session.hook("compaction")  →  attribute (rule | command | external)  →  history
 ```
 
 Estimated size is the serialized system parts and messages divided by

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhanink/opencode-context-compaction",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "Compact an OpenCode session on a token budget at idle, with a TUI status line and toasts.",
   "license": "MIT",

package/src/index.ts

@@ -18,7 +18,19 @@
  * the TUI shows is what the trigger uses.
  */
 import { Plugin } from "@opencode/plugin"
-import { decide, estimateTokens, formatTokens, resolveOptions } from "./lib.ts"
+import {
+  HISTORY_LIMIT,
+  HISTORY_PREFIX,
+  compactionEntry,
+  decide,
+  decisionEntry,
+  estimateTokens,
+  formatTokens,
+  historyKey,
+  resolveOptions,
+  takeOrigin,
+  type HistoryEntry,
+} from "./lib.ts"
 import { ContextCompaction } from "./rpc.ts"
 
 type Seen = { estimated: number; compactedAt?: number }
@@ -33,19 +45,121 @@ export default Plugin.define({
     const pending = new Map<string, any>() // sessionID -> debounce timer
     const seen = new Map<string, Seen>() // sessionID -> last observation
 
+    // Compactions this plugin has asked for that have not landed yet. OpenCode
+    // admits the request and compacts at the next step boundary, so the request
+    // and the compaction are separated in time; this marker is what lets the
+    // history say whether a compaction was ours or OpenCode's own.
+    const requested = new Map<string, { at: number; origin: "rule" | "command" }>()
+
+    // Optional history. Deliberately low volume — one record per decision, one
+    // per compaction — because the per-request token counts an analysis of the
+    // budget actually needs are already in OpenCode's own database, and are not
+    // worth duplicating. See the "History" section of the README.
+    let seq = 0
+    let writes = 0
+    const PRUNE_EVERY = 100
+
+    const prune = async (): Promise<void> => {
+      // Keys come back oldest-first, so anything over the cap is at the front.
+      const keys: string[] = []
+      let after: string | undefined
+      do {
+        const page: any = await ctx.storage.scan({ prefix: HISTORY_PREFIX, after, limit: 500 })
+        for (const found of page?.entries ?? []) keys.push(found.key)
+        after = page?.next
+      } while (after)
+      for (let index = 0; index < keys.length - HISTORY_LIMIT; index += 1) {
+        await ctx.storage.remove(keys[index])
+      }
+    }
+
+    // Fire and forget: a compaction must never wait on our bookkeeping.
+    const write = (entry: HistoryEntry): void => {
+      if (!opts.history) return
+      const key = historyKey(entry.at, seq)
+      seq += 1
+      void (async () => {
+        try {
+          await ctx.storage.set(key, entry)
+          if (writes++ % PRUNE_EVERY === 0) await prune()
+        } catch (error) {
+          log("history write failed:", error)
+        }
+      })()
+    }
+
+    // Observe every compaction, including the ones OpenCode starts on its own —
+    // which is the comparison worth having. Strictly an observer: setting
+    // `result` on this event would replace the summary OpenCode was going to
+    // generate, so this hook never touches anything but its own record.
+    if (opts.history) {
+      try {
+        await ctx.session.hook("compaction", (event: any) => {
+          const at = Date.now()
+          write(
+            compactionEntry({
+              at,
+              sessionID: event.sessionID,
+              origin: takeOrigin(requested, event.sessionID, at),
+              event,
+              charsPerToken: opts.charsPerToken,
+              agent: event.agent,
+              model: event.model?.id,
+              providerID: event.model?.providerID,
+            }),
+          )
+        })
+      } catch (error) {
+        log("history hook unavailable — compactions will not be attributed:", error)
+      }
+    }
+
     // Tell the terminal plugin what is happening. Registration can fail (an
     // older server, a conflicting id); the trigger must keep working either way.
     let emit: ((phase: string, sessionID: string, estimated: number) => void) | undefined
     try {
       const registration: any = await ctx.rpc.register(ContextCompaction, {
-        status: async () => ({
-          enabled: opts.enabled,
-          dryRun: opts.dryRun,
-          maxTokens: opts.maxTokens,
-          charsPerToken: opts.charsPerToken,
-          idleMs: opts.idleMs,
-          cooldownMs: opts.cooldownMs,
-        }),
+        status: async () => {
+          // Counted from storage, not from memory. The plugin is instantiated
+          // per location, so the instance answering this call is frequently
+          // not the one whose hook wrote the records — an in-memory counter
+          // reports zero there while records plainly exist. Storage is shared.
+          let records = 0
+          let lastWriteAt = 0
+          if (opts.history) {
+            try {
+              let after: string | undefined
+              do {
+                const page: any = await ctx.storage.scan({ prefix: HISTORY_PREFIX, after, limit: 500 })
+                for (const found of page?.entries ?? []) {
+                  records += 1
+                  // Keys lead with a zero-padded millisecond stamp.
+                  const stamped = Number(
+                    String(found.key).slice(HISTORY_PREFIX.length, HISTORY_PREFIX.length + 16),
+                  )
+                  if (Number.isFinite(stamped)) lastWriteAt = Math.max(lastWriteAt, stamped)
+                }
+                after = page?.next
+              } while (after)
+            } catch {
+              // -1 rather than 0: an unreadable history must not be
+              // indistinguishable from an empty one, which is the exact
+              // failure this field exists to catch.
+              records = -1
+            }
+          }
+          return {
+            enabled: opts.enabled,
+            dryRun: opts.dryRun,
+            maxTokens: opts.maxTokens,
+            charsPerToken: opts.charsPerToken,
+            idleMs: opts.idleMs,
+            cooldownMs: opts.cooldownMs,
+            history: opts.history,
+            historyRecords: records,
+            historyLastAt: lastWriteAt,
+          }
+        },
       })
       emit = (phase, sessionID, estimated) => {
         void Promise.resolve(
@@ -91,15 +205,27 @@ export default Plugin.define({
 
       const now = Date.now()
       const info = await ctx.session.get({ sessionID })
+      const compactedAt = await lastCompactedAt(sessionID)
       const decision = decide({
         estimated: record.estimated,
         maxTokens: opts.maxTokens,
         enabled: opts.enabled,
         isSubagent: Boolean(info.parentID),
-        compactedAt: await lastCompactedAt(sessionID),
+        compactedAt,
         now,
         cooldownMs: opts.cooldownMs,
       })
+      write(
+        decisionEntry({
+          at: now,
+          sessionID,
+          decision,
+          estimated: record.estimated,
+          maxTokens: opts.maxTokens,
+          dryRun: opts.dryRun,
+          compactedAt,
+        }),
+      )
 
       if (decision.action === "skip") {
         if (decision.reason === "cooldown") emit?.("cooldown", sessionID, record.estimated)
@@ -116,9 +242,16 @@ export default Plugin.define({
       log(`compacting ${sessionID}: ${size}`)
       await markCompacted(sessionID, now)
       emit?.("requested", sessionID, record.estimated)
-      // "queue" keeps the request behind anything already waiting, so a prompt
-      // sent in the meantime is not held up behind the summary.
-      await ctx.session.compact({ sessionID, delivery: "queue" })
+      requested.set(sessionID, { at: now, origin: "rule" })
+      try {
+        // "queue" keeps the request behind anything already waiting, so a prompt
+        // sent in the meantime is not held up behind the summary.
+        await ctx.session.compact({ sessionID, delivery: "queue" })
+      } catch (error) {
+        // The request never landed, so it must not claim a later compaction.
+        requested.delete(sessionID)
+        throw error
+      }
     }
 
     if (opts.enabled) {
@@ -146,20 +279,30 @@ export default Plugin.define({
         name: "compact-now",
         description: "Compact this session now",
         execute: async ({ sessionID }: any) => {
-          await ctx.session.compact({ sessionID, delivery: "queue" })
+          // Marked for the same reason the trigger marks its own request: the
+          // history should record that a compaction was asked for, not infer it.
+          requested.set(sessionID, { at: Date.now(), origin: "command" })
+          try {
+            await ctx.session.compact({ sessionID, delivery: "queue" })
+          } catch (error) {
+            requested.delete(sessionID)
+            throw error
+          }
         },
       })
     })
 
     log(
       `loaded — ${opts.enabled ? `compact above ~${formatTokens(opts.maxTokens)} tokens after ${opts.idleMs}ms quiet` : "trigger disabled"}` +
-        `${opts.dryRun ? " (dry run)" : ""}`,
+        `${opts.dryRun ? " (dry run)" : ""}` +
+        `${opts.history ? " (history on)" : ""}`,
     )
 
     return () => {
       for (const timer of pending.values()) clearTimeout(timer)
       pending.clear()
       seen.clear()
+      requested.clear()
     }
   },
 })

package/src/lib.ts

@@ -18,6 +18,8 @@ export interface Options {
   cooldownMs: number
   /** Log and notify instead of requesting compaction. */
   dryRun: boolean
+  /** Keep a durable record of decisions and compactions, for later analysis. */
+  history: boolean
 }
 
 export const DEFAULTS: Options = {
@@ -29,6 +31,9 @@ export const DEFAULTS: Options = {
   idleMs: 45_000,
   cooldownMs: 10 * 60_000,
   dryRun: false,
+  // Off by default: records land in OpenCode's own database, which is the
+  // user's, so writing there is something they opt into rather than inherit.
+  history: false,
 }
 
 export function resolveOptions(options: Partial<Options> | undefined): Options {
@@ -45,6 +50,20 @@ function lengthOf(value: unknown): number {
   }
 }
 
+/**
+ * Characters in the request about to be assembled: system parts plus messages.
+ * Every size estimate is this number over a per-token constant, so the raw
+ * count is worth keeping for the history — it can be re-divided later.
+ */
+export function countChars(
+  event: { system?: readonly unknown[]; messages?: readonly unknown[] } | undefined,
+): number {
+  let chars = 0
+  for (const part of event?.system ?? []) chars += lengthOf(part)
+  for (const message of event?.messages ?? []) chars += lengthOf(message)
+  return chars
+}
+
 /**
  * Rough size of the request about to be assembled: system parts plus messages,
  * serialized and divided by a characters-per-token constant. JSON overhead
@@ -55,10 +74,7 @@ export function estimateTokens(
   event: { system?: readonly unknown[]; messages?: readonly unknown[] } | undefined,
   charsPerToken: number,
 ): number {
-  let chars = 0
-  for (const part of event?.system ?? []) chars += lengthOf(part)
-  for (const message of event?.messages ?? []) chars += lengthOf(message)
-  return Math.round(chars / charsPerToken)
+  return Math.round(countChars(event) / charsPerToken)
 }
 
 export type Decision =
@@ -94,3 +110,130 @@ export function formatTokens(tokens: number): string {
   if (tokens >= 1_000) return `${Math.round(tokens / 1_000)}k`
   return String(Math.round(tokens))
 }
+
+/**
+ * Optional history.
+ *
+ * Off unless asked for. It exists to answer what the trigger cannot answer
+ * about itself: whether a given compaction was ours or OpenCode's, and how far
+ * the `charsPerToken` estimate sits from the token count the provider actually
+ * reported. Records hold sizes and counts only — never message content — and
+ * they live in plugin storage, which is the user's database, so the list is
+ * capped rather than left to grow.
+ */
+export type Origin = "rule" | "command" | "external"
+
+export interface DecisionRecord {
+  kind: "decision"
+  at: number
+  sessionID: string
+  action: Decision["action"]
+  reason: Decision["reason"]
+  estimated: number
+  maxTokens: number
+  dryRun: boolean
+  /** Milliseconds since this session last compacted; 0 if it never has. */
+  sinceCompactionMs: number
+}
+
+export interface CompactionRecord {
+  kind: "compaction"
+  at: number
+  sessionID: string
+  origin: Origin
+  /** The same estimator the trigger uses, over the transcript being summarized. */
+  estimated: number
+  chars: number
+  messages: number
+  agent?: string
+  model?: string
+  providerID?: string
+}
+
+export type HistoryEntry = DecisionRecord | CompactionRecord
+
+/** Newest records kept; the oldest are pruned as new ones arrive. */
+export const HISTORY_LIMIT = 2_000
+
+/** Storage key prefix, so this never collides with a plugin's other keys. */
+export const HISTORY_PREFIX = "history/"
+
+/**
+ * How long a requested compaction stays attributable to the plugin. OpenCode
+ * admits the request and compacts at the next step boundary, so the gap is
+ * normally seconds; a request that never lands must not go on to claim a
+ * compaction OpenCode started on its own.
+ */
+export const PENDING_TTL_MS = 30 * 60_000
+
+/**
+ * Keys carry a zero-padded timestamp, so a prefix scan returns records in the
+ * order they were written and pruning can drop from the front. The sequence
+ * only breaks ties within the same millisecond.
+ */
+export function historyKey(at: number, seq: number): string {
+  return `${HISTORY_PREFIX}${String(at).padStart(16, "0")}-${String(seq).padStart(6, "0")}`
+}
+
+export function decisionEntry(input: {
+  at: number
+  sessionID: string
+  decision: Decision
+  estimated: number
+  maxTokens: number
+  dryRun: boolean
+  compactedAt?: number
+}): DecisionRecord {
+  return {
+    kind: "decision",
+    at: input.at,
+    sessionID: input.sessionID,
+    action: input.decision.action,
+    reason: input.decision.reason,
+    estimated: input.estimated,
+    maxTokens: input.maxTokens,
+    dryRun: input.dryRun,
+    sinceCompactionMs: input.compactedAt ? Math.max(0, input.at - input.compactedAt) : 0,
+  }
+}
+
+export function compactionEntry(input: {
+  at: number
+  sessionID: string
+  origin: Origin
+  event?: { system?: readonly unknown[]; messages?: readonly unknown[] }
+  charsPerToken: number
+  agent?: string
+  model?: string
+  providerID?: string
+}): CompactionRecord {
+  return {
+    kind: "compaction",
+    at: input.at,
+    sessionID: input.sessionID,
+    origin: input.origin,
+    estimated: estimateTokens(input.event, input.charsPerToken),
+    chars: countChars(input.event),
+    messages: input.event?.messages?.length ?? 0,
+    agent: input.agent,
+    model: input.model,
+    providerID: input.providerID,
+  }
+}
+
+/**
+ * Who a compaction that is starting now belongs to. Consumes the session's
+ * pending marker, because one request can only explain one compaction.
+ * Mutates `pending`.
+ */
+export function takeOrigin(
+  pending: Map<string, { at: number; origin: "rule" | "command" }>,
+  sessionID: string,
+  now: number,
+  ttlMs: number = PENDING_TTL_MS,
+): Origin {
+  const held = pending.get(sessionID)
+  if (!held) return "external"
+  pending.delete(sessionID)
+  return now - held.at > ttlMs ? "external" : held.origin
+}

package/src/rpc.ts

@@ -29,8 +29,21 @@ export const ContextCompaction = Rpc.define({
           charsPerToken: { type: "number" },
           idleMs: { type: "number" },
           cooldownMs: { type: "number" },
+          history: { type: "boolean" },
+          historyRecords: { type: "number" },
+          historyLastAt: { type: "number" },
         },
-        required: ["enabled", "dryRun", "maxTokens", "charsPerToken", "idleMs", "cooldownMs"],
+        required: [
+          "enabled",
+          "dryRun",
+          "maxTokens",
+          "charsPerToken",
+          "idleMs",
+          "cooldownMs",
+          "history",
+          "historyRecords",
+          "historyLastAt",
+        ],
         additionalProperties: false,
       },
     },

package/src/tui.ts

@@ -217,6 +217,11 @@ export default Plugin.define({
         current ? `idle before acting: ${Math.round(current.idleMs / 1000)}s` : "",
         current ? `cooldown: ${Math.round(current.cooldownMs / 60_000)} min` : "",
         current?.dryRun ? "dry run: on (nothing is compacted)" : "",
+        current?.history
+          ? current.historyRecords === -1
+            ? "history: on (unreadable)"
+            : `history: on (${current.historyRecords ?? 0} recorded this run)`
+          : "",
         "",
         "/compact-now compacts immediately.",
       ].filter(Boolean)