smart-compaction 0.1.0 → 0.2.1

package/README.md

@@ -1,9 +1,10 @@
 # smart-compaction
 
 A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) plugin that gives the
-model a `compact_now` tool, so it can trigger compaction itself at a point *it* knows is safe —
-right after finishing a step, never mid-edit — instead of only ever being interrupted by dsh's
-automatic token-threshold trigger.
+model two tools: `compact_now`, so it can trigger compaction itself at a point *it* knows is safe
+— right after finishing a step, never mid-edit — instead of only ever being interrupted by dsh's
+automatic token-threshold trigger; and `context_status`, so it can check real, current token
+usage against its actual context window instead of guessing whether a conversation "feels long."
 
 ## Why
 
@@ -19,7 +20,9 @@ blind token counter.
 
 ## What it does
 
-One tool: **`compact_now`**. No arguments.
+Two tools, both no-argument.
+
+**`compact_now`**
 
 - Selects the largest currently-compactable span of conversation history — the same
   tool-call-pairing-safe boundary logic dsh's own compaction already guarantees, reimplemented
@@ -31,6 +34,21 @@ One tool: **`compact_now`**. No arguments.
 - No-ops harmlessly (`"Not enough compactable history yet."`) if there isn't enough history yet —
   safe for the model to call speculatively.
 
+**`context_status`**
+
+- Read-only — never modifies the session, safe to call anytime.
+- Reports current token usage and the model's actual context-window size for *this* session,
+  e.g. `"~42,300 / 77,824 tokens used (54.3%)."`
+- Reads dsh's own `contextPressure` session projection (registered by
+  `@deepseek-ai/dsh-token-meter`, mounted wherever `compaction-basic` is) via the public
+  `ctx.sessionProjections.stateOf()` API — the same numbers the web UI's own context meter
+  reads. Nothing is hardcoded: the context-window figure comes from whatever model this
+  session is actually routed to, so it's correct unchanged across different models, profiles,
+  and context-window sizes.
+- Exists because, without it, the model has zero visibility into its own context usage — the
+  only prior signal was a vague "if the conversation feels long" in `compact_now`'s own
+  description.
+
 ## How it works
 
 Two entry points exist on dsh's compaction service: `compactNow()` (what the human `/compact`
@@ -56,24 +74,41 @@ array yourself.)
 No build step, no config. Restart your dsh service after adding it — new bundles are only picked
 up on boot.
 
-**Requires a `compaction` service on your profile.** Most profile templates ship one, but not all
-do (e.g. `@deepseek-ai/dsh-web-app`-based profiles don't by default). If yours doesn't, `compact_now`
-still installs cleanly (it won't break your profile's boot) but returns an error every time it's
-called: `"no compaction service is configured on this profile"`. Add a `compaction-basic` bundle to
-get one.
+**`compact_now` requires a `compaction` service on your profile.** Most profile templates ship
+one, but not all do (e.g. `@deepseek-ai/dsh-web-app`-based profiles don't by default). If yours
+doesn't, `compact_now` still installs cleanly (it won't break your profile's boot) but returns an
+error every time it's called: `"no compaction service is configured on this profile"`. Add a
+`compaction-basic` bundle to get one.
 
-### Tell the model when to use it
+**`context_status` requires `@deepseek-ai/dsh-token-meter` mounted** (it registers the
+`contextPressure` projection this tool reads). It's normally pulled in wherever `compaction-basic`
+is, so if `compact_now` works, `context_status` should too. If it isn't mounted, the tool still
+installs cleanly and just reports `available: false` instead of erroring.
 
-`compact_now` only *offers* the capability — nothing calls it 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`), if the conversation
-> has gotten long, call `compact_now`. It's safe to call speculatively — it no-ops if there isn't
-> enough history to compact yet.
+### Tell the model when to use it
 
-Tying it 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,
-which it's generally bad at.
+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, 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.
+
+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.
 
 ## Building from source
 
@@ -86,8 +121,8 @@ pnpm install
 node test.js
 ```
 
-`test.js` is a pure unit-test check of the range-selection logic (`select-range.js`) — no live
-dsh/Ollama session required.
+`test.js` is a pure unit-test check of the range-selection logic (`select-range.js`) and the
+context-usage summary logic (`context-status.js`) — no live dsh/Ollama session required.
 
 ## Configuration
 
@@ -95,7 +130,7 @@ None. The tool takes no arguments and needs no setup beyond installing it.
 
 ## Status
 
-Verified end-to-end against a real dsh session, including:
+`compact_now` verified end-to-end against a real dsh session, including:
 
 - Basic call: the tool loads, the model calls it, it selects a valid boundary-safe range, and it
   drives `compactRegion()` mid-turn without ever hitting the `busy` failure this design exists to

package/context-status.js

@@ -0,0 +1,54 @@
+/**
+ * Pure summary of dsh's own `contextPressure` session-projection state.
+ *
+ * That projection is registered by `@deepseek-ai/dsh-token-meter` (mounted
+ * on any profile that runs `compaction-basic`) and read here through the
+ * public `ctx.sessionProjections.stateOf(session, 'contextPressure')` API —
+ * the exact same numbers the web UI's own context meter reads. Nothing about
+ * a model or its context-window size is hardcoded: `contextWindow` is
+ * whatever the last `request/context` event actually logged for whichever
+ * model this session is really routed to, so this works unchanged across
+ * profiles, models, and context-window sizes.
+ *
+ * The `usedTokens` formula mirrors token-meter's own private
+ * `contextPressureProjectionDefinition.wire.view` (not part of that
+ * package's public exports — see the doc comment above it in
+ * `usage-projection.ts` for the reasoning): prompt-side pressure from the
+ * last real provider usage sample, adjusted by how much the tracked surface
+ * has grown or shrunk (e.g. via compaction) since that sample was taken.
+ * Before any request has completed this session, no usage sample exists yet
+ * — `surfaceTokens` alone is the best available estimate, flagged
+ * `estimated: true`.
+ *
+ * @see HANDOFF.md for the full research trail behind this file.
+ */
+
+/**
+ * @param {import('@deepseek-ai/dsh-token-meter').ContextPressureState | undefined} state
+ * @returns {{
+ *   available: boolean,
+ *   contextWindow?: number,
+ *   usedTokens?: number,
+ *   percentUsed?: number,
+ *   estimated?: boolean,
+ * }}
+ */
+export function summarizeContextUsage(state) {
+  if (state === undefined) return { available: false }
+  if (state.contextWindow === undefined) {
+    return { available: true, usedTokens: state.surfaceTokens, estimated: true }
+  }
+
+  const hasSample = state.pressureTokens !== undefined && state.sampledSurfaceTokens !== undefined
+  const usedTokens = hasSample
+    ? Math.max(0, state.pressureTokens + state.surfaceTokens - state.sampledSurfaceTokens)
+    : state.surfaceTokens
+
+  return {
+    available: true,
+    contextWindow: state.contextWindow,
+    usedTokens,
+    percentUsed: Math.round((usedTokens / state.contextWindow) * 1000) / 10,
+    estimated: !hasSample,
+  }
+}

package/cordis.patch.yml

@@ -1,5 +1,6 @@
 # This bundle's own default layer: mounts the plugin under id
-# `tool-compact-now`. Nothing to configure — the tool takes no config.
+# `tool-compact-now`. One module registers both the `compact_now` and
+# `context_status` tools — nothing to configure, the tool takes no config.
 - insert:
     - id: tool-compact-now
       name: 'smart-compaction'

package/index.js

@@ -1,7 +1,10 @@
 /**
  * dsh plugin: registers a `compact_now` tool on `ctx.tools` so the model can
  * voluntarily trigger compaction at a point it judges safe, instead of only
- * ever being interrupted by dsh's automatic token-threshold trigger.
+ * ever being interrupted by dsh's automatic token-threshold trigger. Also
+ * registers `context_status`, so the model can check real, current token
+ * usage against its actual context window on demand instead of guessing
+ * whether "the conversation feels long" — see context-status.js.
  *
  * Calls `ctx.compaction.compactRegion()` directly — NOT `compactNow()` (what
  * the human `/compact` command uses). `compactRegion` doesn't require an
@@ -14,6 +17,7 @@
 
 import { toolPairingBalancedBefore } from '@deepseek-ai/dsh-compaction'
 import { defineTool } from '@deepseek-ai/dsh-tools'
+import { summarizeContextUsage } from './context-status.js'
 import { selectCompactableRange } from './select-range.js'
 
 export const name = 'tool-compact-now'
@@ -29,9 +33,12 @@ 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 '
-  + 'compact yet.'
+  + 'interrupted by automatic compaction. Call context_status first if unsure whether now '
+  + 'is a good time — usage past roughly 70-90% of the context window is a concrete signal '
+  + 'to call this proactively, not just a vague feeling that the conversation has gotten '
+  + 'long. As a habit: check context_status after every completed step, and call this '
+  + 'whenever that check comes back high. Harmless to call speculatively either way — it '
+  + 'no-ops if there is not enough history to compact yet.'
 
 /**
  * @param {import('@deepseek-ai/cordis').Context} ctx
@@ -87,4 +94,57 @@ export function apply(ctx) {
       }
     },
   }))
+
+  ctx.tools.register(defineTool({
+    name: 'context_status',
+    description: CONTEXT_STATUS_DESCRIPTION,
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          available: { type: 'boolean', required: true },
+          contextWindow: { type: 'integer' },
+          usedTokens: { type: 'integer' },
+          percentUsed: { type: 'number' },
+          estimated: { type: 'boolean' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: renderContextStatus(value) }],
+    },
+    async execute(_args, exec) {
+      if (!exec.agent) {
+        throw new Error('context_status requires an owning agent session')
+      }
+      const projections = ctx.get('sessionProjections')
+      if (!projections) return { available: false }
+      const state = projections.stateOf(exec.agent.session, 'contextPressure')
+      return summarizeContextUsage(state)
+    },
+  }))
+}
+
+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. '
+  + '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." Automatic compaction generally triggers '
+  + 'well before the window fills, typically somewhere around 70-90% depending on profile '
+  + 'config, so if percentUsed comes back past that range, follow up by calling compact_now '
+  + 'proactively rather than wait to be interrupted. Harmless to call anytime — read-only, '
+  + 'never modifies the session.'
+
+function renderContextStatus(value) {
+  if (!value.available) {
+    return 'Context usage isn\'t available on this profile (no token-meter service mounted).'
+  }
+  if (value.contextWindow === undefined) {
+    return `~${value.usedTokens} tokens used so far this session; context-window size isn't `
+      + 'known yet (no model request has completed yet).'
+  }
+  const note = value.estimated ? ' (estimated — no confirmed usage sample yet)' : ''
+  return `~${value.usedTokens.toLocaleString()} / ${value.contextWindow.toLocaleString()} tokens `
+    + `used (${value.percentUsed}%)${note}.`
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "smart-compaction",
-  "version": "0.1.0",
-  "description": "dsh plugin: a compact_now tool letting the model trigger compaction itself at a safe point, instead of only the automatic token-threshold trigger.",
+  "version": "0.2.1",
+  "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",
   "engines": {
@@ -30,7 +30,7 @@
   "dshhub": {
     "schemaVersion": 1,
     "displayName": "Smart Compaction",
-    "summary": "Gives the model a compact_now tool so it can trigger compaction itself at a safe point, instead of only being interrupted by the automatic token-threshold trigger.",
+    "summary": "Gives the model a compact_now tool so it can trigger compaction itself at a safe point, plus a context_status tool to check real token usage against its context window, instead of only being interrupted by the automatic token-threshold trigger.",
     "categories": [
       "Sessions & Messages",
       "Tools & Capabilities"
@@ -41,7 +41,8 @@
     ],
     "capabilities": {
       "provides": [
-        "tool:compact_now"
+        "tool:compact_now",
+        "tool:context_status"
       ]
     },
     "compatibility": {
@@ -53,6 +54,7 @@
   "files": [
     "index.js",
     "select-range.js",
+    "context-status.js",
     "cordis.patch.yml"
   ],
   "peerDependencies": {