smart-compaction 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JoblessJoe
+
+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

@@ -0,0 +1,121 @@
+# 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.
+
+## Why
+
+dsh's built-in compaction is purely reactive: an automatic trigger fires between agent steps
+whenever token pressure crosses a fixed threshold, with no idea whether that moment is a good one
+to interrupt. It can land between two dependent steps — e.g. right after reading a file and right
+before editing it based on what was just read — and the resulting summary loses exactly the
+context the very next step needed.
+
+This plugin doesn't change *how* compaction works, only *who decides when*. It hands the model a
+tool it can call proactively, on its own judgment, instead of leaving that decision entirely to a
+blind token counter.
+
+## What it does
+
+One tool: **`compact_now`**. No arguments.
+
+- Selects the largest currently-compactable span of conversation history — the same
+  tool-call-pairing-safe boundary logic dsh's own compaction already guarantees, reimplemented
+  here against dsh's *public* APIs only (no dsh core changes, no dependency on
+  `compaction-basic`'s internals).
+- Calls dsh's own `ctx.compaction.compactRegion()` to actually do the compaction — the same
+  summarizer, the same durable `compaction/start`/`compaction/end` log events, the same guarantees
+  as any other compaction in the session.
+- No-ops harmlessly (`"Not enough compactable history yet."`) if there isn't enough history yet —
+  safe for the model to call speculatively.
+
+## How it works
+
+Two entry points exist on dsh's compaction service: `compactNow()` (what the human `/compact`
+command uses — requires an **idle** agent, throws `busy` otherwise) and `compactRegion()` (what
+dsh's own *automatic* between-step trigger uses — works fine **mid-turn**). A tool's `execute()`
+always runs mid-turn — that's what calling a tool means — so `compact_now` is built on
+`compactRegion()`, not `compactNow()`.
+
+## Install
+
+From your dsh **web profile** (`web` below is the profile name; use whichever profile backs your
+session):
+
+```bash
+dsh plugin --profile web add smart-compaction
+```
+
+This installs the package and adds it to `dsh.profile.bundles` for you. (No local `dsh` binary?
+Run the equivalent by hand from the profile directory, e.g. `~/.dsh/profiles/web/`: `pnpm add
+smart-compaction`, then add `"smart-compaction"` to that `package.json`'s `dsh.profile.bundles`
+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.
+
+### Tell the model when to use it
+
+`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.
+
+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.
+
+## Building from source
+
+Requires Node 22+. Plain JS, no build step — `git clone`, `pnpm install`, done.
+
+```bash
+git clone https://github.com/JoblessJoe/smart-compaction.git
+cd smart-compaction
+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.
+
+## Configuration
+
+None. The tool takes no arguments and needs no setup beyond installing it.
+
+## Status
+
+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
+  avoid.
+- A real tool-call/tool-result pair (`todo_write`, marked `in_progress` then `completed`) sitting
+  in the compacted range — stays correctly paired, nothing split.
+- Three `compact_now` calls in a row in one session (one accidental, caught by dsh's own
+  duplicate-call guard mid-task) — each completed cleanly, no crash, no `busy`, no corrupted state
+  from operating on a surface that already contains an earlier compaction's checkpoint message.
+
+**Troubleshooting:** if the tool returns an error like `summarization produced no text summary
+content`, that's not this plugin — `compact_now` selected a valid range and handed it to dsh's own
+summarizer, which returned nothing. Observed specifically when the compacted range contains only
+injected boilerplate (e.g. standing instructions) with no real assistant-generated text yet —
+succeeded reliably once genuine conversation content was in the range. If it happens on ranges with
+real content too, check whether your model's "thinking" level is an actually-enforced token budget
+or just an instruction (e.g. Ollama's `think: low` is unenforced — a model can still spend its
+entire output budget on hidden reasoning and return no visible summary text). Either way, this is a
+model/summarizer-side issue, not something `compact_now` itself controls.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# This bundle's own default layer: mounts the plugin under id
+# `tool-compact-now`. Nothing to configure — the tool takes no config.
+- insert:
+    - id: tool-compact-now
+      name: 'smart-compaction'

package/index.js

@@ -0,0 +1,90 @@
+/**
+ * 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.
+ *
+ * Calls `ctx.compaction.compactRegion()` directly — NOT `compactNow()` (what
+ * the human `/compact` command uses). `compactRegion` doesn't require an
+ * idle agent, which matters because a tool's `execute()` always runs during
+ * an open turn; `compactNow()` would throw `busy` on every real call here.
+ * See HANDOFF.md for the full research trail.
+ *
+ * @module dsh-compact-now
+ */
+
+import { toolPairingBalancedBefore } from '@deepseek-ai/dsh-compaction'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { selectCompactableRange } from './select-range.js'
+
+export const name = 'tool-compact-now'
+// `compaction` deliberately NOT in `inject`: that would make this plugin's
+// boot depend on the service existing, and not every profile bundle ships a
+// compaction backend (e.g. dsh-web-app doesn't) — a hard inject broke boot
+// on any profile that lacks one. Looked up via `ctx.get()` at call time
+// instead, same as core's own optional-sibling-service pattern
+// (compaction-basic's own `toolResultPruner` lookup).
+export const inject = ['tools']
+
+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.'
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ */
+export function apply(ctx) {
+  ctx.tools.register(defineTool({
+    name: 'compact_now',
+    description: DESCRIPTION,
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          compacted: { type: 'boolean', required: true },
+          shadowedCount: { type: 'integer' },
+          shadowedTokenCount: { type: 'integer' },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: value.compacted
+          ? `Compacted ${value.shadowedCount} history items (~${value.shadowedTokenCount} tokens).`
+          : 'Not enough compactable history yet.',
+      }],
+    },
+    async execute(_args, exec) {
+      const compaction = ctx.get('compaction')
+      if (!compaction) {
+        throw new Error('compact_now: no compaction service is configured on this profile')
+      }
+      if (!exec.agent) {
+        throw new Error('compact_now requires an owning agent session')
+      }
+      const session = exec.agent.session
+      const range = selectCompactableRange(session, toolPairingBalancedBefore)
+      if (range === null) {
+        return { compacted: false }
+      }
+      let result
+      try {
+        result = await compaction.compactRegion(range.start, range.end, exec.agent, exec.signal)
+      } catch (error) {
+        // The four errors compactRegion's own range validation can throw all
+        // indicate this file's range-selection logic disagrees with core's —
+        // a bug here, not an expected runtime outcome. Surface it plainly.
+        throw new Error(`compact_now: compaction failed: ${error instanceof Error ? error.message : String(error)}`)
+      }
+      return {
+        compacted: true,
+        shadowedCount: result.shadowedSeqs.length,
+        shadowedTokenCount: result.shadowedTokenCount,
+      }
+    },
+  }))
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "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.",
+  "type": "module",
+  "main": "./index.js",
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "author": "joblessjoe",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JoblessJoe/smart-compaction.git"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "compaction",
+    "context-management"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "compatibility": {
+      "dsh": ">=0.1.5-rc.3"
+    }
+  },
+  "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.",
+    "categories": [
+      "Sessions & Messages",
+      "Tools & Capabilities"
+    ],
+    "surfaces": [
+      "cli",
+      "web"
+    ],
+    "capabilities": {
+      "provides": [
+        "tool:compact_now"
+      ]
+    },
+    "compatibility": {
+      "dsh": ">=0.1.5-rc.3",
+      "node": ">=22"
+    },
+    "permissions": {}
+  },
+  "files": [
+    "index.js",
+    "select-range.js",
+    "cordis.patch.yml"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-compaction": "*",
+    "@deepseek-ai/dsh-tools": "*"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-compaction": "0.0.1-rc.5",
+    "@deepseek-ai/dsh-tools": "0.0.1-rc.1"
+  }
+}

package/select-range.js

@@ -0,0 +1,41 @@
+/**
+ * Reimplementation of dsh core's `selectCompactableRange`
+ * (`@deepseek-ai/dsh-compaction-basic`'s internal `region.ts` — not part of
+ * that package's public exports) using only APIs public to any dsh plugin:
+ * `toolPairingBalancedBefore` from `@deepseek-ai/dsh-compaction`, and
+ * `session.surface`/`session.eventAt` from `@deepseek-ai/dsh-session`.
+ *
+ * Fixed at the equivalent of `retainTokens = 0` — the largest currently
+ * compactable span, same as what dsh core's own `compactNow()` (the manual
+ * `/compact` command's backend) passes internally. Note this still always
+ * keeps the final surface node out of the compactable range: core's own
+ * retain-budget loop runs at least once even at `retainTokens = 0`, so it
+ * never offers the single most recent node for compaction either. This
+ * mirrors that behavior on purpose, not an oversight.
+ *
+ * @see HANDOFF.md for the full research trail behind this file.
+ */
+
+/**
+ * @param {import('@deepseek-ai/dsh-session').Session} session
+ * @returns {{ start: import('@deepseek-ai/dsh-session').SessionSeq, end: import('@deepseek-ai/dsh-session').SessionSeq } | null}
+ */
+export function selectCompactableRange(session, toolPairingBalancedBefore) {
+  const nodes = session.surface.nodes
+  if (nodes.length === 0) return null
+
+  const head = session.eventAt(nodes[0])
+  const firstIdx = head !== undefined && head.type === 'system/message' ? 1 : 0
+
+  // Always retain at least the final surface node verbatim.
+  let keepFromIdx = nodes.length - 1
+  if (keepFromIdx <= firstIdx) return null
+
+  while (keepFromIdx > firstIdx) {
+    if (toolPairingBalancedBefore(session, nodes[keepFromIdx])) break
+    keepFromIdx -= 1
+  }
+  if (keepFromIdx <= firstIdx) return null
+
+  return { start: nodes[firstIdx], end: nodes[keepFromIdx - 1] }
+}