@jhanink/opencode-context-compaction 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jhanink
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,179 @@
-# Temporary Holding Version
+# opencode-context-compaction
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Compact an OpenCode session on a **token budget**, at an idle moment, instead of
+waiting for the model's context ceiling.
+
+## Why
+
+OpenCode compacts automatically near the window limit (`limit − compaction.buffer`).
+On a 1M-token model that is roughly 900k, so a session can sit at 150–250k all
+afternoon and never compact: every request keeps re-reading a large transcript,
+and the conversation keeps drifting away from what it actually needed.
+
+The obvious fix — "compact at 40% of the window" — does not work for the same
+reason: 40% of 1M is 400k, which real sessions never reach. A budget in absolute
+tokens is the rule that actually bounds context, so that is what this uses.
+
+## What it does
+
+- Watches the context assembled for every model call and estimates its size.
+- When a session goes quiet for `idleMs` **and** its context is over `maxTokens`,
+  it requests a normal OpenCode compaction (`delivery: "queue"`, so a prompt you
+  send in the meantime is not stuck behind the summary).
+- Adds no model calls of its own. The compaction it requests costs one summary
+  call plus a prompt-cache miss on the next request, because the conversation is
+  rewritten — the same cost the built-in trigger pays, just at a moment you chose.
+- Leaves subagent sessions alone, and will not compact the same session twice
+  inside `cooldownMs` (the latch is durable, so a reload does not double-fire).
+
+## Terminal integration
+
+The server plugin and the terminal plugin are separate halves that talk over
+[RPC](https://opencode.ai/v2/docs/build/plugins/rpc), so the numbers on screen are
+the numbers the trigger uses.
+
+- **Status line** under the composer: `ctx 44k/150k 29%`, muted while comfortable,
+  attention-coloured once the session is past budget (`ctx 160k/150k 100% · compacts at idle`).
+- **Toasts** when a compaction is requested, and again when the session's history
+  actually shrinks.
+- **`/compact-status`** (also in the command palette) for budget, current usage,
+  idle delay, cooldown, and whether a dry run is on.
+- **`/compact-now`** to compact immediately.
+
+## Install
+
+Local plugin directories are picked up automatically, and a directory plugin's
+`tui.ts` is loaded by the terminal client:
+
+```sh
+git clone https://github.com/jhanink/opencode-context-compaction
+cp -R opencode-context-compaction/src ~/.config/opencode/plugins/context-compaction
+```
+
+Restart the terminal UI if the status line does not appear; the server half
+reloads on its own.
+
+Or as a package:
+
+```sh
+opencode plugin add @jhanink/opencode-context-compaction
+```
+
+## Options
+
+Set options by loading the plugin from `opencode.json(c)` — and **do not** also
+leave a copy in the auto-discovered plugins directory, or two instances will each
+request compaction:
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "@jhanink/opencode-context-compaction",
+      "options": {
+        "maxTokens": 200000,
+        "idleMs": 60000
+      }
+    }
+  ]
+}
+```
+
+Those two are a better starting point than the defaults on a model with a
+1M-token window such as DeepSeek V4. Its built-in trigger sits out around 900k and
+cache reads are cheap, so there is little reason to compact early; the longer idle
+delay also keeps a short pause mid-task from reading as the end of one. Only the
+keys you set are overridden:
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | Turn the trigger off without removing the plugin. |
+| `maxTokens` | `150000` | Compact at or above this estimated context size. |
+| `charsPerToken` | `4` | Estimator for a text-heavy transcript; higher means later compaction. |
+| `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.
+
+### Sizing `maxTokens`
+
+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("compaction")  →  attribute (rule | command | external)  →  history
+```
+
+Estimated size is the serialized system parts and messages divided by
+`charsPerToken`. JSON overhead makes it skew slightly high, which is the safe
+direction for a budget: compact a little early rather than too late. Exact
+tokenization would cost more than the decision is worth.
+
+## Development
+
+```sh
+node --test test/*.test.ts   # pure decision logic, no OpenCode needed
+```
+
+`src/lib.ts` holds the rules and is free of OpenCode and Solid imports so it can
+be tested on its own; `src/index.ts` and `src/tui.ts` are thin adapters.
+
+OpenCode supplies `@opencode/plugin`, `@opentui/*` and `solid-js` at runtime, so
+they are declared as **optional** peer dependencies and installing this package
+fetches nothing else. (0.1.0 listed `@opencode/plugin` as a normal dependency,
+which pulled 424 packages into every install, including a deprecated `glob`
+with known advisories.)
+
+## Prior art
+
+Closest neighbours, both worth reading before adopting this:
+
+- [`@cortexkit/opencode-magic-context`](https://www.npmjs.com/package/@cortexkit/opencode-magic-context) (MIT) — background compression of old conversation, cross-session memory, cache-aware deferred operations. Solves the same problem with a parallel summarizer.
+- [`@tarquinen/opencode-dcp`](https://www.npmjs.com/package/@tarquinen/opencode-dcp) (AGPL-3.0) — prunes stale tool output from context instead of compacting.
+
+This plugin deliberately does neither: it drives OpenCode's *native* compaction,
+adds no dependencies, and makes no model calls of its own.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@jhanink/opencode-context-compaction",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "exports": {
+    ".": "./src/index.ts",
+    "./tui": "./src/tui.ts",
+    "./rpc": "./src/rpc.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "compaction",
+    "context",
+    "tokens"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.ts"
+  },
+  "peerDependencies": {
+    "@opencode/plugin": ">=2",
+    "@opentui/core": "*",
+    "@opentui/solid": "*",
+    "solid-js": ">=1.9"
+  },
+  "peerDependenciesMeta": {
+    "@opencode/plugin": {
+      "optional": true
+    },
+    "@opentui/core": {
+      "optional": true
+    },
+    "@opentui/solid": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jhanink/opencode-context-compaction.git"
+  },
+  "author": "jhanink"
+}

package/src/index.ts

@@ -0,0 +1,308 @@
+/**
+ * context-compaction — server side.
+ *
+ * OpenCode's built-in trigger fires near the window ceiling (limit minus
+ * `compaction.buffer`), which on a 1M-token model means roughly 900k. A long
+ * session can sit at 150-250k all afternoon and never compact. This plugin
+ * watches the context assembled for each model call and, once a session has
+ * gone quiet and its context passes a budget, asks OpenCode to compact — the
+ * same compaction the built-in trigger uses, requested at an idle moment
+ * instead of mid-task at the ceiling.
+ *
+ * Cost shape: no model calls of its own. The compaction it requests costs one
+ * summary call plus a prompt-cache miss on the next request, because the
+ * conversation is rewritten. That cost exists because a compaction happened;
+ * the plugin decides when, not whether.
+ *
+ * The terminal side lives in ./tui.ts and reads its numbers over RPC, so what
+ * the TUI shows is what the trigger uses.
+ */
+import { Plugin } from "@opencode/plugin"
+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 }
+
+export default Plugin.define({
+  id: "context-compaction",
+
+  async setup(ctx: any) {
+    const opts = resolveOptions(ctx.options)
+    const log = (...args: unknown[]) => console.log("[context-compaction]", ...args)
+
+    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 () => {
+          // 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(
+          registration.events.emit("decision", {
+            sessionID,
+            phase,
+            estimated,
+            maxTokens: opts.maxTokens,
+          }),
+        ).catch(() => {})
+      }
+    } catch (error) {
+      log("RPC unavailable — the trigger still runs, the TUI just cannot show it:", error)
+    }
+
+    // The cooldown latch lives in plugin storage so a reload mid-session still
+    // respects it rather than compacting twice in a row.
+    const lastCompactedAt = async (sessionID: string): Promise<number> => {
+      try {
+        const value = await ctx.storage.get(`last:${sessionID}`)
+        if (typeof value === "number") return value
+      } catch {
+        // fall through to the in-memory record
+      }
+      return seen.get(sessionID)?.compactedAt ?? 0
+    }
+
+    const markCompacted = async (sessionID: string, now: number) => {
+      const record = seen.get(sessionID) ?? { estimated: 0 }
+      record.compactedAt = now
+      seen.set(sessionID, record)
+      try {
+        await ctx.storage.set(`last:${sessionID}`, now)
+      } catch {
+        // in-memory record above still guards the cooldown
+      }
+    }
+
+    const act = async (sessionID: string) => {
+      pending.delete(sessionID)
+      const record = seen.get(sessionID)
+      if (!record) return
+
+      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,
+        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)
+        return
+      }
+
+      const size = `~${formatTokens(record.estimated)} tokens over a ${formatTokens(opts.maxTokens)} budget`
+      if (opts.dryRun) {
+        log(`would compact ${sessionID}: ${size}`)
+        emit?.("dry-run", sessionID, record.estimated)
+        return
+      }
+
+      log(`compacting ${sessionID}: ${size}`)
+      await markCompacted(sessionID, now)
+      emit?.("requested", sessionID, record.estimated)
+      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) {
+      await ctx.session.hook("context", (event: any) => {
+        const record = seen.get(event.sessionID) ?? { estimated: 0 }
+        record.estimated = estimateTokens(event, opts.charsPerToken)
+        seen.set(event.sessionID, record)
+
+        // Debounce: act once the session stops issuing model calls, not between
+        // the calls of a single turn.
+        const timer = pending.get(event.sessionID)
+        if (timer) clearTimeout(timer)
+        pending.set(
+          event.sessionID,
+          setTimeout(() => {
+            act(event.sessionID).catch((error) => log("compaction request failed:", error))
+          }, opts.idleMs),
+        )
+      })
+    }
+
+    // The on-demand counterpart, since the built-in trigger is window-based.
+    await ctx.command.transform((editor: any) => {
+      editor.add({
+        name: "compact-now",
+        description: "Compact this session now",
+        execute: async ({ sessionID }: any) => {
+          // 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.history ? " (history on)" : ""}`,
+    )
+
+    return () => {
+      for (const timer of pending.values()) clearTimeout(timer)
+      pending.clear()
+      seen.clear()
+      requested.clear()
+    }
+  },
+})

package/src/lib.ts

@@ -0,0 +1,239 @@
+/**
+ * Pure decision logic for context-compaction.
+ *
+ * Nothing here imports OpenCode or Solid, so the rules can be unit-tested on
+ * their own (see test/lib.test.ts) with a plain TypeScript runtime.
+ */
+
+export interface Options {
+  /** Hold the trigger off entirely without removing the plugin. */
+  enabled: boolean
+  /** Compact when the estimated context is at or above this many tokens. */
+  maxTokens: number
+  /** Estimate for a text-heavy transcript; high estimates compact earlier. */
+  charsPerToken: number
+  /** How long a session must be quiet before a compaction is requested. */
+  idleMs: number
+  /** Minimum gap between compactions of the same session. */
+  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 = {
+  enabled: true,
+  // A budget, not a share of the window: 40% of a 1M-token window is 400k,
+  // which real sessions never reach, so a percentage rule never fires.
+  maxTokens: 150_000,
+  charsPerToken: 4,
+  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 {
+  return { ...DEFAULTS, ...(options ?? {}) }
+}
+
+function lengthOf(value: unknown): number {
+  const text = (value as { text?: unknown } | undefined)?.text
+  if (typeof text === "string") return text.length
+  try {
+    return JSON.stringify(value)?.length ?? 0
+  } catch {
+    return 0
+  }
+}
+
+/**
+ * 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
+ * makes the result skew slightly high, which is the safe direction for a
+ * budget — compact a little early rather than too late.
+ */
+export function estimateTokens(
+  event: { system?: readonly unknown[]; messages?: readonly unknown[] } | undefined,
+  charsPerToken: number,
+): number {
+  return Math.round(countChars(event) / charsPerToken)
+}
+
+export type Decision =
+  | { action: "request"; reason: "over-budget" }
+  | { action: "skip"; reason: "disabled" | "subagent" | "under-budget" | "cooldown" }
+
+export interface DecisionInput {
+  estimated: number
+  maxTokens: number
+  enabled: boolean
+  /** Subagent sessions are short-lived; compacting them buys nothing. */
+  isSubagent?: boolean
+  /** When this session was last compacted, 0 if never. */
+  compactedAt?: number
+  now: number
+  cooldownMs: number
+}
+
+export function decide(input: DecisionInput): Decision {
+  if (!input.enabled) return { action: "skip", reason: "disabled" }
+  if (input.isSubagent) return { action: "skip", reason: "subagent" }
+  if (input.estimated < input.maxTokens) return { action: "skip", reason: "under-budget" }
+  if (input.compactedAt && input.now - input.compactedAt < input.cooldownMs) {
+    return { action: "skip", reason: "cooldown" }
+  }
+  return { action: "request", reason: "over-budget" }
+}
+
+/** 15234 -> "15k", 1500000 -> "1.5M" */
+export function formatTokens(tokens: number): string {
+  if (!Number.isFinite(tokens) || tokens <= 0) return "0"
+  if (tokens >= 1_000_000) return `${(tokens / 1_000_000).toFixed(1)}M`
+  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

@@ -0,0 +1,67 @@
+/**
+ * The contract between the server plugin and the terminal plugin.
+ *
+ * The server side owns the budget and knows when a compaction is requested; the
+ * terminal side renders it. Sharing the contract keeps the budget in one place
+ * instead of duplicating a constant that can drift.
+ */
+import { Rpc } from "@opencode/plugin/rpc"
+
+export const ContextCompaction = Rpc.define({
+  id: "context-compaction",
+  methods: {
+    /** Current settings, so the terminal shows the numbers actually in use. */
+    status: {
+      // Deliberately an empty object schema rather than an omitted `input`:
+      // this server version dereferences the input schema even for
+      // argument-less methods, and a missing one throws internally.
+      input: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+      },
+      output: {
+        type: "object",
+        properties: {
+          enabled: { type: "boolean" },
+          dryRun: { type: "boolean" },
+          maxTokens: { type: "number" },
+          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",
+          "history",
+          "historyRecords",
+          "historyLastAt",
+        ],
+        additionalProperties: false,
+      },
+    },
+  },
+  events: {
+    /** A decision worth telling the user about, per session. */
+    decision: {
+      schema: {
+        type: "object",
+        properties: {
+          sessionID: { type: "string" },
+          phase: { type: "string", enum: ["requested", "dry-run", "cooldown"] },
+          estimated: { type: "number" },
+          maxTokens: { type: "number" },
+        },
+        required: ["sessionID", "phase", "estimated", "maxTokens"],
+        additionalProperties: false,
+      },
+    },
+  },
+})

package/src/tui.ts

@@ -0,0 +1,274 @@
+/**
+ * context-compaction — terminal side.
+ *
+ * Shows what the server-side trigger is doing, in the terminal:
+ *
+ *   - a status line under the composer: `ctx 44k/150k 29%`, turning
+ *     attention-coloured once the session is past the budget;
+ *   - a toast when a compaction is requested, and another when the session's
+ *     history actually shrinks;
+ *   - `/compact-status` (and a palette command) for the full numbers.
+ *
+ * It never decides anything: the budget and the decisions come from the server
+ * plugin over RPC, so the TUI cannot disagree with the trigger.
+ *
+ * Built without JSX, matching the element tree a Solid transform would emit, so
+ * the file loads under the plugin runtime as-is.
+ */
+import { createEffect, createSignal, onCleanup, onMount } from "solid-js"
+import { createComponent, createElement, effect, insert, setProp } from "@opentui/solid"
+import { Plugin } from "@opencode/plugin/tui"
+import { formatTokens } from "./lib.ts"
+import { ContextCompaction } from "./rpc.ts"
+
+// Events drive updates; this interval is only a low-frequency backstop.
+const REFRESH_MS = 10_000
+
+// What the status line last saw, so the command can report the same numbers.
+const observed: { sessionID?: string; used: number } = { used: 0 }
+
+function info(message: any) {
+  return message?.info ?? message ?? {}
+}
+
+/** Tokens the session is carrying: the newest request's input and cache reads. */
+function contextTokens(messages: any[]): number {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const tokens = info(messages[index]).tokens
+    if (!tokens) continue
+    const cache = tokens.cache ?? {}
+    const total = (tokens.input ?? 0) + (cache.read ?? 0) + (cache.write ?? 0)
+    if (total > 0) return total
+  }
+  return 0
+}
+
+function latestCompaction(messages: any[]): any {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = info(messages[index])
+    if (message.type === "compaction") return message
+  }
+  return undefined
+}
+
+function StatusLine(props: any) {
+  const ctx = props.ctx
+  const [usage, setUsage] = createSignal(0)
+  const adopted = new Set<string>()
+  let lastCompaction: string | undefined
+
+  // Read defensively: the cache can throw if the session is torn down mid-read,
+  // and this runs inside event callbacks where an exception would be unhandled.
+  const read = () => {
+    const sessionID = props.sessionID
+    if (!sessionID) return undefined
+    try {
+      const messages = ctx.data.session.message.list(sessionID) ?? []
+      return { used: contextTokens(messages), compaction: latestCompaction(messages) }
+    } catch {
+      return undefined
+    }
+  }
+
+  const refresh = () => {
+    const current = read()
+    if (!current) return
+    observed.sessionID = props.sessionID
+    observed.used = current.used
+    setUsage(current.used)
+
+    const compaction = current.compaction
+    if (!compaction) return
+    // A compaction already in history when we start watching is adopted, not
+    // announced; only one that lands while watching is worth a toast.
+    if (!adopted.has(props.sessionID)) {
+      adopted.add(props.sessionID)
+      lastCompaction = compaction.id
+      return
+    }
+    if (compaction.id === lastCompaction) return
+    lastCompaction = compaction.id
+    ctx.ui.toast.show({
+      title: "Context compacted",
+      message: `session context is now ~${formatTokens(current.used)} tokens`,
+      duration: 6000,
+    })
+  }
+
+  const resync = () => {
+    refresh()
+    const sessionID = props.sessionID
+    if (!sessionID) return
+    try {
+      void Promise.resolve(ctx.data.session.message.sync(sessionID)).then(refresh, refresh)
+    } catch {
+      // best effort: the interval backstop covers failures
+    }
+  }
+
+  // The slot may stay mounted while the session changes underneath it.
+  createEffect(() => {
+    void props.sessionID
+    refresh()
+    const recovery = [setTimeout(refresh, 400), setTimeout(refresh, 1500), setTimeout(refresh, 4000)]
+    onCleanup(() => {
+      for (const timer of recovery) clearTimeout(timer)
+    })
+  })
+
+  onMount(() => {
+    resync()
+    const stops = [
+      ctx.data.on("message.updated", resync),
+      ctx.data.on("message.removed", resync),
+      ctx.data.on("session.updated", resync),
+      ctx.data.on("session.idle", resync),
+    ]
+    const interval = setInterval(resync, REFRESH_MS)
+    onCleanup(() => {
+      for (const stop of stops) {
+        try {
+          stop()
+        } catch {
+          // ignore
+        }
+      }
+      clearInterval(interval)
+    })
+  })
+
+  const budget = () => props.budget
+
+  const label = () => {
+    const used = usage()
+    if (!used) return ""
+    const limit = budget()
+    if (!limit) return `ctx ~${formatTokens(used)}`
+    const share = Math.round((used / limit) * 100)
+    const over = used >= limit ? " · compacts at idle" : ""
+    return `ctx ${formatTokens(used)}/${formatTokens(limit)} ${share}%${over}`
+  }
+
+  const color = () => {
+    const limit = budget()
+    const theme = ctx.theme ?? {}
+    if (limit && usage() >= limit) return theme.text?.warn ?? theme.text?.base
+    return theme.text?.muted ?? theme.text?.base
+  }
+
+  const text = createElement("text")
+  setProp(text, "wrapMode", "none")
+  insert(text, () => label())
+  effect((previous: any) => setProp(text, "fg", color(), previous))
+  return text
+}
+
+export default Plugin.define({
+  id: "opencode-context-compaction",
+
+  async setup(context: any) {
+    const [status, setStatus] = createSignal<any>(undefined)
+    const compaction = context.client.rpc(ContextCompaction)
+
+    // Ask the server plugin for the settings in use, rather than duplicating
+    // them here where they would drift.
+    const loadStatus = async () => {
+      try {
+        setStatus(await compaction.status({}))
+      } catch {
+        // Server plugin absent or still starting: show usage without a budget.
+      }
+    }
+    await loadStatus()
+
+    const stopDecisions = compaction.events.on("decision", (event: any) => {
+      const data = event?.data ?? {}
+      const estimated = formatTokens(data.estimated ?? 0)
+      const limit = formatTokens(data.maxTokens ?? 0)
+      if (data.phase === "requested") {
+        context.ui.toast.show({
+          title: "Context compaction",
+          message: `~${estimated} tokens over a ${limit} budget — compacting now`,
+          duration: 6000,
+        })
+      } else if (data.phase === "dry-run") {
+        context.ui.toast.show({
+          title: "Context compaction (dry run)",
+          message: `would compact ~${estimated} tokens against a ${limit} budget`,
+          duration: 6000,
+        })
+      } else if (data.phase === "cooldown") {
+        context.ui.toast.show({
+          title: "Context compaction",
+          message: `~${estimated} tokens over budget, but inside the cooldown window`,
+          duration: 5000,
+        })
+      }
+    })
+
+    const showStatus = async () => {
+      const current = status()
+      const used = observed.used
+      const limit = current?.maxTokens
+      const lines = [
+        current?.enabled === false ? "trigger: disabled" : "trigger: armed",
+        limit ? `budget: ~${formatTokens(limit)} tokens` : "budget: unknown (server plugin not answering)",
+        used ? `this session: ~${formatTokens(used)} tokens${limit ? ` (${Math.round((used / limit) * 100)}%)` : ""}` : "this session: no request seen yet",
+        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)
+      await context.ui.dialog.alert({ title: "Context compaction", message: lines.join("\n") })
+    }
+
+    context.keymap.layer(() => ({
+      mode: "global",
+      priority: 10,
+      commands: [
+        {
+          id: "context-compaction.status",
+          title: "Context budget: show status",
+          group: "Context",
+          palette: true,
+          slash: { name: "compact-status" },
+          run: () => showStatus(),
+        },
+      ],
+      bindings: ["context-compaction.status"],
+    }))
+
+    const unregisterSlot = context.ui.slot({
+      append: "prompt.footer.status",
+      render: (props: any) =>
+        createComponent(StatusLine, {
+          ctx: context,
+          get sessionID() {
+            return props.sessionID
+          },
+          get budget() {
+            return status()?.maxTokens
+          },
+        }),
+    })
+
+    return () => {
+      try {
+        stopDecisions?.()
+      } catch {
+        // ignore
+      }
+      try {
+        unregisterSlot?.()
+      } catch {
+        // ignore
+      }
+    }
+  },
+})