smart-compaction 0.2.0 → 0.2.2

package/README.md

@@ -87,19 +87,33 @@ installs cleanly and just reports `available: false` instead of erroring.
 
 ### Tell the model when to use it
 
-Neither tool calls itself — nothing uses them unless instructed to. Add something like this to
-your `AGENTS.md` (or whatever your profile injects as standing instructions):
-
-> After marking a todo item `completed` (never while one is `in_progress`), call `context_status`.
-> If usage is climbing past roughly 70-80% of the context window, call `compact_now` too. Both are
-> safe to call speculatively — `context_status` is read-only, and `compact_now` no-ops if there
-> isn't enough history to compact yet.
+This is baked into both tools' own descriptions, so it works out of the box with no setup: each
+tool's description tells the model to check `context_status` right after finishing a
+self-contained step (e.g. right after `todo_write` marks an item `completed`) and to follow up
+with `compact_now` once usage climbs past roughly 70-90%. Since both descriptions are sent to the
+model on every request automatically, no `AGENTS.md` edit is required for this behavior — unlike
+an early version of this plugin, which relied entirely on a hand-written `AGENTS.md` rule and
+(measured directly against real session logs) got essentially no organic use as a result: the
+description alone wasn't a strong enough signal.
+
+That said, standing instructions carry more weight than a tool description competing against
+everything else in a long tool catalog. If you want to reinforce it further, copy
+[`agents-snippet.md`](./agents-snippet.md) into your `AGENTS.md` (or whatever your profile injects
+as standing instructions).
 
 Tying this to todo-completion matters: it's a real, already-tracked signal for "I just finished a
 self-contained unit of work," instead of asking the model to estimate its own remaining work or
 guess whether a conversation "feels long," both of which it's generally bad at. `context_status`
 replaces that guess with the real number.
 
+The snippet deliberately does *not* say "compact once usage crosses 70-80%" as the primary rule —
+a threshold check alone is still reactive: a step that turns out bigger than expected (a large
+file, a long diff, a subagent dispatch) can blow straight past a comfortable-looking percentage
+*during* that step, which is exactly the mid-step interruption this plugin exists to avoid. The
+percentage is kept only as a hard backstop; the primary check is comparing remaining headroom
+against the size of the step about to start, and compacting early — before that step, not during
+or after it — whenever the fit looks tight.
+
 ## Building from source
 
 Requires Node 22+. Plain JS, no build step — `git clone`, `pnpm install`, done.

package/index.js

@@ -33,8 +33,15 @@ const DESCRIPTION =
   'Voluntarily compact older conversation history now, at a point you know is safe: '
   + 'right after finishing a concrete step (e.g. just marked a todo item completed), '
   + 'never mid-edit or with unfinished work pending. Use this instead of waiting to be '
-  + 'interrupted by automatic compaction, if the conversation feels like it has gotten '
-  + 'long. Harmless to call speculatively — it no-ops if there is not enough history to '
+  + 'interrupted by automatic compaction. Do not decide this only by checking whether usage '
+  + 'is already past a fixed percentage — that is still reactive, and a step that turns out '
+  + 'bigger than expected can blow past a comfortable-looking number mid-step. Before '
+  + 'starting the next step, weigh how much room is left against what that step will '
+  + 'actually cost (a big file read, a long diff, a subagent dispatch); if it is not clearly '
+  + 'going to fit with room to spare, call this now even while usage still looks moderate. '
+  + 'Compacting a little early costs nothing; running out mid-step loses exactly the context '
+  + 'that step needed. Call context_status first if unsure how much room is actually left. '
+  + 'Harmless to call speculatively either way — it no-ops if there is not enough history to '
   + 'compact yet.'
 
 /**
@@ -125,11 +132,17 @@ export function apply(ctx) {
 const CONTEXT_STATUS_DESCRIPTION =
   'Check real, current context-window usage for this session: tokens used so far and the '
   + 'model\'s actual context-window size, whatever model this session happens to be running. '
-  + 'Use this instead of guessing whether the conversation "feels long" before deciding to call '
-  + 'compact_now — automatic compaction generally triggers well before the window fills, '
-  + 'typically somewhere around 70-90% depending on profile config, so usage climbing past that '
-  + 'range is a good signal to call compact_now proactively rather than wait to be interrupted. '
-  + 'Harmless to call anytime; read-only, never modifies the session.'
+  + 'Call this right after finishing any self-contained step — e.g. right after todo_write '
+  + 'marks an item completed, never mid-edit or with unfinished work pending — instead of '
+  + 'guessing whether the conversation "feels long." Use the result to judge whether what is '
+  + 'left is enough for the next step specifically (a big file read, a long diff, a subagent '
+  + 'dispatch), not just whether percentUsed has crossed some fixed number — a step that '
+  + 'turns out larger than expected can still blow past a comfortable-looking percentage. '
+  + 'When in doubt, call compact_now before starting that next step rather than after it runs '
+  + 'into trouble: as a hard backstop, treat anything past roughly 70-90% (depending on '
+  + 'profile config) as reason enough on its own, but do not wait for that number if the next '
+  + 'step alone looks likely to use it up. Harmless to call anytime — read-only, never '
+  + 'modifies the session.'
 
 function renderContextStatus(value) {
   if (!value.available) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-compaction",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "dsh plugin: a compact_now tool letting the model trigger compaction itself at a safe point, plus a context_status tool so it can check real token usage against its context window, instead of only the automatic token-threshold trigger.",
   "type": "module",
   "main": "./index.js",