dsh-command-context-trim 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -5,6 +5,62 @@ All notable changes to this project are documented here. This project adheres to
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-09-22
+
+### Added
+
+- **Cheap reduction first: oversized tool results are slimmed in place before any span is elided.** On the wall the
+  plugin now performs the same head/marker/tail transform DSH's own pruner performs — keeping the node, its tool call and
+  the prefix up to it — and only elides a whole span when that is not enough. It delegates to the official
+  `toolResultPruner` service when that service is reachable from the plugin's context (0.1.2; a 0.1.5 headless profile
+  where compaction stays on the host plane) and performs the identical transform itself when it is not (a 0.1.5 web
+  profile hides the pruner inside an agent-preset isolate realm). New configuration: `preferInPlacePrune` (default true)
+  and `pruneThresholdChars` / `pruneHeadChars` / `pruneTailChars` (8192 / 4096 / 1024, mirroring DSH's defaults).
+- The in-place marker is `[... tool result middle trimmed to fit the context window ...]`, deliberately distinct from
+  DSH's `[... tool result middle pruned ...]`, so a session log shows which producer slimmed a node.
+
+### Notes
+
+- Verified end to end in the real `dsh-container` image (0.1.5-rc.2, isolated home, mock backend): a request of 23,429
+  tokens was refused, the plugin delegated to the official pruner, the retry came back at 19,995 tokens, the turn
+  completed, and the session log shows **no `compaction/start`** and **no span elided** — the pruner's `tool/result`
+  replacement kept `callId` and the step. The earlier span path was verified the same way (33,373 → 18,431 tokens).
+  The inline fallback (used only where the service is unreachable, i.e. a 0.1.5 web profile) is unit-tested against the
+  same semantics but not yet exercised end to end.
+- `scripts/mock-overflow-server.mjs` gained `TOOL_COMMAND` / `TOOL_DESCRIPTION`: a bash tool call without a `description`
+  fails argument validation, which silently produced tiny error results instead of real tool output during testing.
+
+
+## [0.2.1] - 2026-09-22
+
+### Fixed
+
+- **A wall hit is no longer a one-shot.** Reported from a 32k backend while `settings.yaml` declared `contextWindow:
+  90000`: the first automatic trim targeted `(90000 - 8192) * 0.9 ~= 73.6k`, the retry was rejected again, and with
+  `maxAutoTrimRetries: 1` spent the recovery fell through to compaction — whose summarisation request is itself over the
+  real limit, so the turn died. The plugin now adapts instead of trusting a declaration it has just seen contradicted:
+  - the **first** attempt still trusts the declared window (cheap, and correct when the window is honest);
+  - every **later** attempt inside the same episode retargets to `failingRequestTokens * (1 - autoTrimShrink)`, i.e. it
+    halves the request that was just rejected — a geometric descent that converges however wrong the declared window is;
+  - a repeat attempt also logs an actionable warning: the routed model's `contextWindow` is larger than the backend
+    actually serves, fix it in `settings.yaml` (and the server's own context flag).
+- Defaults changed accordingly: `maxAutoTrimRetries` **1 → 3**, and a new `autoTrimShrink` (**0.5**).
+
+- **Automatic-trim decisions now log at `warn`.** An unattended rewrite of the user's context has to be visible in the
+  host log: a test run recorded the trim in the session log while the app log showed nothing, because `info` is filtered
+  at the default level.
+- The README now explains how to tell this plugin's `compaction/prune` from DSH's tool-result pruner in a session log
+  (producer of the following event, and pre-step vs in-step position) and the two `usage` accounting traps.
+
+### Notes
+
+- The honest fix for a mismatched backend is still the setting itself: with `contextWindow: 32768` the very first trim
+  targets ~22k and succeeds without the adaptive path. The adaptive path exists so a wrong declaration degrades into
+  "more trimming than necessary" rather than a dead turn.
+- Nothing else changed: the event, its gating (`CONTEXT_WINDOW_EXCEEDED` only), the elision preference tiers and the
+  newest-user-message barrier are untouched.
+
+
 ## [0.2.0] - 2026-09-16
 
 ### Added
@@ -101,7 +157,9 @@ All notable changes to this project are documented here. This project adheres to
   content stays in the durable session log. v1 has no `/untrim`.
 - Requires a harness that exposes `ctx.commands`, `ctx.tokenMeter`, and `ctx.llm` (DeepSeek Harness 0.1.2-rc.1 or later).
 
-[Unreleased]: https://github.com/snailium/dsh-command-context-trim/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/snailium/dsh-command-context-trim/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/snailium/dsh-command-context-trim/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/snailium/dsh-command-context-trim/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/snailium/dsh-command-context-trim/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/snailium/dsh-command-context-trim/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/snailium/dsh-command-context-trim/releases/tag/v0.1.0

package/README.md

@@ -110,9 +110,30 @@ Scope, deliberately narrow:
 | ordinary threshold compaction (`agent/pre-step` pressure) | **never touched** |
 | `/compact`, the tool-result pruner | **never touched** |
 
-The per-episode retry budget (`maxAutoTrimRetries`, default 1) resets when a completed assistant message lands or the
+The per-episode retry budget (`maxAutoTrimRetries`, default 3) resets when a completed assistant message lands or the
 agent goes idle, mirroring compaction's own overflow accounting. Set `autoTrim: false` to keep trimming manual.
 
+**The cheap reduction runs first.** On the wall the plugin slims oversized tool results **in place** (head + marker + tail,
+the same transform DSH's own pruner performs) and only elides a whole span when that is not enough:
+
+```
+request refused → in-place tool-result slim  →  elide one span  →  compaction (prune + summarize)
+```
+
+It calls the official `toolResultPruner` service when that service is reachable from the plugin's context (0.1.2, and a
+0.1.5 headless profile where compaction stays on the host plane) and performs the same transform itself when it is not (a
+0.1.5 web profile hides the pruner inside an agent-preset isolate realm). A slim keeps the node, its tool call and the
+prefix up to it — the marker written in place says `[... tool result middle trimmed to fit the context window ...]`, which
+is how a log shows that *this* plugin slimmed a node rather than DSH's pruner (`[... tool result middle pruned ...]`).
+Set `preferInPlacePrune: false` to go straight to span elision.
+
+**A wrong `contextWindow` degrades into extra trimming, not a dead turn.** The first attempt trusts the declared window.
+If the retry is rejected again, the declaration has just been contradicted, so every later attempt in that episode
+retargets to `failingRequestTokens * (1 - autoTrimShrink)` — by default *halving* the request that was rejected — which
+converges however far the backend is below its declaration, and logs a warning naming the setting to fix. With an honest
+window the first attempt succeeds and the adaptive path never runs. The real fix for a mismatched backend is the setting:
+`contextWindow: 32768` makes the first trim target ~22k and fit.
+
 Trade-off, stated plainly: an automatic trim **drops** the oldest span instead of summarizing it. On a small local
 window that is the point — the summarizer must fit the region it is condensing and frequently cannot — but the dropped
 text is replaced by a marker rather than a summary. `/compact` stays available, and the full text remains in the
@@ -171,14 +192,17 @@ Override on the `context-trim` row of a profile patch (the bundle's own `cordis.
 | Key | Default | Meaning |
 |---|---|---|
 | `targetRatio` | `0.9` | `budget = floor((contextWindow - reserveOutputTokens) * targetRatio)` |
-| `reserveOutputTokens` | `8192` | Output space kept for the model's own reply |
+| `reserveOutputTokens` | `8192` | Output space kept for the model's own reply. Keep it plus the provider's own `maxTokens` inside the real window: a 32k server with `maxTokens: 16384` exhausts the window with prompt + output even when every prompt fits |
 | `retainRatio` / `retainTokens` | `0.16` / — | Recent tail kept verbatim (mutually exclusive forms) |
 | `minTailTokens` | `2048` | Absolute floor for that tail |
 | `protectHeadNodes` | `1` | Leading nodes that are never trimmed |
 | `allowTailTrim` | `true` | Enable tiers 2–3 (reach into the retained tail; as a last resort include the final message). `false` ends the search after tier 1, making the retained tail a hard boundary |
 | `markerSlackTokens` | `64` | Slack added to the priced marker so the post-trim request stays under budget |
 | `autoTrim` | `true` | Trim automatically on `CONTEXT_WINDOW_EXCEEDED`; never fires on ordinary compaction |
-| `maxAutoTrimRetries` | `1` | Automatic trims allowed per overflow episode before compaction takes over |
+| `maxAutoTrimRetries` | `3` | Automatic trims allowed per overflow episode before compaction takes over |
+| `autoTrimShrink` | `0.5` | After a repeat overflow, retarget to this fraction of the rejected request (geometric descent when the declared window is wrong) |
+| `preferInPlacePrune` | `true` | Slim oversized tool results in place before planning any span; uses the official pruner when reachable |
+| `pruneThresholdChars` / `pruneHeadChars` / `pruneTailChars` | `8192` / `4096` / `1024` | In-place slim budgets, mirroring DSH's own pruner defaults |
 
 ## Limits
 
@@ -192,6 +216,28 @@ Override on the `context-trim` row of a profile patch (the bundle's own `cordis.
 - **Heuristic pricing.** Budgets use the token meter's own estimate — the same numbers `/compact` and the GUI context bar
   use. Provider-reported usage drifts slightly from it.
 
+## Reading the session log
+
+`compaction/prune` has **two producers**, and only one of them is this plugin:
+
+| Producer | Where | Followed by | Shape |
+|---|---|---|---|
+| **this plugin**, span elision | inside a step, right after a failed attempt | `user/message` whose `source.plugin` is `dsh-command-context-trim` | a whole span, both cut edges tool-pairing balanced |
+| **this plugin**, in-place slim | same place, before any span is planned | `tool/result` replacing exactly one node | one `tool/result`, marker `[... tool result middle trimmed to fit the context window ...]`, `callId` kept |
+| **DSH's tool-result pruner** | in compaction's own path | `tool/result` replacing exactly one node | a single `tool/result`, its `tool/call` kept |
+
+Position is the other tell: a prune **between `step/end` and `step/start`** belongs to compaction's *pressure*
+path (and this plugin, being overflow-only, is deliberately not involved); a prune **inside a step, after an
+`assistant/attempt`** is an overflow recovery. A session with no `assistant/attempt` events never hit
+`CONTEXT_WINDOW_EXCEEDED` at all, so this plugin never ran in it.
+
+Two accounting traps when checking whether a trim helped: `assistant/message` `usage` is **per request**
+(`input + cacheRead + output` for that call), not a session total — and a tool result is appended *after* the
+request that produced its tool call, so comparing consecutive `usage.total` values measures "content was added",
+not "the trim freed nothing". Compare the rejected attempt with the retry instead. Also, an in-place replacement of
+the *last* node keeps the cached prefix (so `cacheRead` stays high); only a mid-conversation cut — this plugin, or
+compaction rewriting the head — breaks it, which shows up as `cacheRead` dropping and `input` jumping on the next call.
+
 ## Development
 
 ### End-to-end overflow check (no model needed)
@@ -227,14 +273,15 @@ releases go out through `.github/workflows/publish.yml`, which is manual-only (`
 
 | Check | State |
 |---|---|
-| `npm test` (51 tests: planner, args, surface apply + log replay, plugin handler, automatic overflow path) | ✅ passing |
+| `npm test` (72 tests: planner, args, surface apply + log replay, plugin handler, automatic overflow path, in-place slim, config) | ✅ passing |
 | Isolated `DSH_HOME` install (`dsh plugin add file:…`) reconciling dependency **and** bundle layer | ✅ verified |
 | Composed profile tree contains the `context-trim` insert row (`dsh --dump-config`) | ✅ verified |
 | Profile boot with the plugin mounted (no load error) | ✅ reaches the credential check cleanly |
-| Same suite against the pinned **published** harness packages (`npm ci`) | ✅ 51 passing |
+| Same suite against the pinned **published** harness packages (`npm ci`) | ✅ 72 passing |
 | Integration against the **real** `ctx.tokenMeter`: measured drop equals the claimed shadow price, and a fresh meter replaying the trimmed log reaches the identical total | ✅ 4 tests |
 | Real-`cordis` proof that a `prepend`ed waterfall listener runs first and vetoes the chain (the mechanism the automatic path depends on) | ✅ 3 tests |
-| Same suite on harness 0.1.5-rc.2 (renamed marker + surface system prompt) | ✅ 51 passing |
+| Same suite on the newer harness line (renamed replacement marker + surface system prompt); CI resolves it via the `next` tag, currently 0.1.5-rc.3 | ✅ 72 passing |
+| **End-to-end in the real `dsh-container` image (0.1.5-rc.2, isolated home, mock backend)**: span path (33,373 → 18,431 tokens, `compaction/start` = 0) and in-place slim path (23,429 → 19,995 tokens, no span elided, pruner delegated to the official service) | ✅ both verified |
 | CI workflow (Node 22 / 24) | ✅ green |
 | npm release via GitHub Actions | ✅ 0.1.0 published with provenance (`+ dsh-command-context-trim@0.1.0`) |
 | Isolated profile install **from the npm registry** (dependency + bundle layer + composed insert row) | ✅ 0.1.0 |

package/README.zh.md

@@ -72,7 +72,17 @@ agent-preset 的 isolate realm 里挂载的（web profile 里就是这样），
 **范围刻意收窄**：只有 `CONTEXT_WINDOW_EXCEEDED` 才触发；其它请求错误、普通阈值 compaction（`agent/pre-step` 压力路径）、
 `/compact`、工具结果 pruner **一律不碰**（有测试锁定注册的监听器集合）。
 
-每轮溢出 epis 的额度由 `maxAutoTrimRetries`（默认 1）限制，收到完成的 assistant 消息或 agent 空闲即重置。
+每轮溢出 episode 的额度由 `maxAutoTrimRetries`（默认 3）限制，收到完成的 assistant 消息或 agent 空闲即重置。
+
+**便宜的那一步先做**：撞墙时先把超长 tool result **原地瘦身**（head + 标记 + tail，与 DSH 自带 pruner 同一变换），不够才整段裁剪：
+
+```
+请求被拒 → tool result 原地瘦身 → 整段裁剪一段 → compaction（prune + summarize）
+```
+
+官方 `toolResultPruner` 服务在插件上下文里可见时（0.1.2、以及 compaction 仍在宿主层的 0.1.5 headless）直接委托它；不可见时（0.1.5 web profile 把 pruner 藏在 agent-preset isolate realm 里）自己做同样的变换。瘦身保留节点、tool call 与其之前的前缀；写入的标记是 `[... tool result middle trimmed to fit the context window ...]`，与 DSH 自己的 `[... tool result middle pruned ...]` 可区分。`preferInPlacePrune: false` 可跳过这一步。
+
+**声明窗口与实际不符时，退化成"多裁一点"而不是"回合死掉"**：第一次仍按声明的 `contextWindow` 定目标；若重试又被拒（说明声明已被事实推翻），此后同一 episode 内改为按 `failingRequestTokens × (1 − autoTrimShrink)` 重定目标——默认**减半**刚被拒的那次请求，几何收敛，并打印告警指出该去改 `settings.yaml` 的哪个设置。窗口声明正确时第一次就成功，自适应路径根本不会触发。根治办法仍是配置本身：`contextWindow: 32768` 时首次裁剪目标约 22k，直接命中。
 代价如实说：自动 trim 是**丢弃**最旧一段而不是摘要它——在小窗口下这正是要点，但被丢的内容只会变成一条占位标记。
 `/compact` 仍在，原文也仍在会话日志里。
 
@@ -127,8 +137,8 @@ npm run link:harness   # 也可改为从本地 dsh 安装的依赖闭包解析 @
 
 已验证：34 个测试全部通过（选段算法、参数解析、真实 Session 上的 surface 改写与日志重放、插件命令注册与端到端裁剪，以及用**真实 `ctx.tokenMeter`** 验证「实测降幅 == 声明的 shadow price」和「新进程重放裁剪后日志得到完全一致的总量」）；
 隔离 `DSH_HOME` 安装后 dependency 与 bundle 层均正确 reconcile；`dsh --dump-config` 中出现 `context-trim` 行；profile 启动无加载错误。
-CI 在 Node 22/24 上跑同一套测试；发布通过 `.github/workflows/publish.yml`（手动 `workflow_dispatch`）。
-npm 0.2.0（新增撞墙自动 trim），并已在隔离 profile 里从 registry 安装验证；尚未执行：Web GUI 里的真实小窗口端到端验证（mock provider 与隔离实例已就绪）。
+CI 在 Node 22/24 × harness 0.1.2-rc.1/`next`（当前解析到 0.1.5-rc.3）四腿矩阵上跑同一套 61 项测试；发布通过 `.github/workflows/publish.yml`（手动 `workflow_dispatch`）。
+npm 0.2.2（撞墙自动 trim：先原地瘦身、再整段裁剪、最后才摘要），并已在隔离 profile 里从 registry 安装验证；尚未执行：Web GUI 里的真实小窗口端到端验证（mock provider 与隔离实例已就绪）。
 
 ## License
 

package/cordis.patch.yml

@@ -32,4 +32,20 @@
         # Ordinary threshold compaction is never touched.
         autoTrim: true
         # Automatic trims allowed per overflow episode before compaction takes over.
-        maxAutoTrimRetries: 1
+        # More than one is needed when the declared contextWindow is larger than the
+        # backend really serves: see autoTrimShrink below.
+        maxAutoTrimRetries: 3
+        # After a repeat overflow the target becomes this fraction of the request that
+        # was just rejected (0.5 = halve it), which converges even when the declared
+        # window is wrong. The first attempt still trusts the declared window.
+        autoTrimShrink: 0.5
+        # Before eliding any span, slim oversized tool results IN PLACE (head +
+        # marker + tail), the same cheap reduction DSH's own pruner performs. Uses
+        # the official `toolResultPruner` service when it is reachable and performs
+        # the same transform itself when it is not (a 0.1.5 web profile hides it in
+        # an agent-preset isolate realm). A span is elided only when that is not
+        # enough.
+        preferInPlacePrune: true
+        pruneThresholdChars: 8192
+        pruneHeadChars: 4096
+        pruneTailChars: 1024

package/lib/auto-trim.js

@@ -20,10 +20,18 @@
  * `{ kind: 'retry' }` without calling `next()` vetoes the rest of the chain for
  * that attempt; calling `next()` hands the problem to compaction.
  *
+ * Before any span is elided, oversized tool results are slimmed **in place** (the
+ * cheap, information-preserving reduction DSH itself uses); a span is only elided
+ * when that is not enough. See `./prune-first.js`.
+ *
+ * Every decision here logs at `warn`: an unattended rewrite of the user's context
+ * must be visible in the host log, not filtered behind an info level (an earlier
+ * run recorded a trim in the session log while the app log showed nothing).
+ *
  * @module dsh-command-context-trim/auto-trim
  */
 import { CONTEXT_WINDOW_EXCEEDED_CODE } from '@deepseek-ai/dsh-llm';
-import { logLine, describeError } from './render.js';
+import { logLineFor, describeError } from './render.js';
 import { executeTrim } from './trim-session.js';
 
 /**
@@ -44,25 +52,42 @@ export function registerAutoTrim(ctx, config) {
 			if (failure?.code !== CONTEXT_WINDOW_EXCEEDED_CODE || signal.aborted) return next();
 			const used = spent.get(agent) ?? 0;
 			if (used >= config.maxAutoTrimRetries) {
-				log(ctx, 'info', `context-overflow auto-trim: retry budget spent (${used}); leaving recovery to compaction`);
+				log(ctx, 'warn', `context-overflow auto-trim: retry budget spent (${used}); leaving recovery to compaction`);
 				return next();
 			}
+			// First attempt trusts the routed model's declared window. Every later
+			// attempt has proof that the declared window is wrong — this exact request
+			// was rejected — so the target becomes a fraction of the size that just
+			// failed, which converges even when the backend is far smaller than
+			// settings.yaml claims.
+			const failingTotal = ctx.tokenMeter.measure(agent.session).totalTokens;
+			const budgetCeiling =
+				used === 0 ? undefined : Math.max(1, Math.floor(failingTotal * (1 - config.autoTrimShrink)));
+			if (budgetCeiling !== undefined) {
+				log(
+					ctx,
+					'warn',
+					`context-overflow auto-trim: attempt ${used + 1} — a request of ~${failingTotal} tokens was still rejected; ` +
+						`retargeting to ~${budgetCeiling} tokens. If this repeats, the routed model's contextWindow is larger than the ` +
+						`backend actually serves — fix it in settings.yaml (and in the server's own context flag).`
+				);
+			}
 			const generation = agent.session.surface.replaceGeneration;
 			let outcome;
 			try {
-				outcome = await executeTrim(ctx, config, { agent, signal, routedOnly: true });
+				outcome = await executeTrim(ctx, config, { agent, signal, routedOnly: true, budgetCeiling, inPlaceFirst: true });
 			} catch (error) {
 				log(ctx, 'warn', `context-overflow auto-trim failed (${describeError(error)}); leaving recovery to compaction`);
 				return next();
 			}
 			if (signal.aborted) return next();
 			if (agent.session.surface.replaceGeneration <= generation) {
-				log(ctx, 'info', `context-overflow auto-trim: nothing safely trimmable; leaving recovery to compaction`);
+				log(ctx, 'warn', `context-overflow auto-trim: nothing safely trimmable; leaving recovery to compaction`);
 				return next();
 			}
 			spent.set(agent, used + 1);
 			actors.set(agent.session, agent);
-			log(ctx, 'info', `context-overflow auto-trim: ${logLine(outcome.plan, outcome.after, outcome.label)}`);
+			log(ctx, 'warn', `context-overflow auto-trim: ${logLineFor(outcome)}`);
 			return { kind: 'retry' };
 		},
 		{ prepend: true }

package/lib/config.js

@@ -7,6 +7,8 @@
  * @module dsh-command-context-trim/config
  */
 
+import { TRIM_MARKER } from './prune-first.js';
+
 /** Built-in defaults, mirrored by the bundle patch's commented config block. */
 export const DEFAULTS = Object.freeze({
 	targetRatio: 0.9,
@@ -17,7 +19,12 @@ export const DEFAULTS = Object.freeze({
 	allowTailTrim: true,
 	markerSlackTokens: 64,
 	autoTrim: true,
-	maxAutoTrimRetries: 1
+	maxAutoTrimRetries: 3,
+	autoTrimShrink: 0.5,
+	preferInPlacePrune: true,
+	pruneThresholdChars: 8192,
+	pruneHeadChars: 4096,
+	pruneTailChars: 1024
 });
 
 /** Every key this plugin accepts. */
@@ -31,7 +38,12 @@ const CONFIG_KEYS = new Set([
 	'allowTailTrim',
 	'markerSlackTokens',
 	'autoTrim',
-	'maxAutoTrimRetries'
+	'maxAutoTrimRetries',
+	'autoTrimShrink',
+	'preferInPlacePrune',
+	'pruneThresholdChars',
+	'pruneHeadChars',
+	'pruneTailChars'
 ]);
 
 /**
@@ -54,13 +66,29 @@ export function resolveConfig(config = {}) {
 	const markerSlackTokens = config.markerSlackTokens ?? DEFAULTS.markerSlackTokens;
 	const autoTrim = config.autoTrim ?? DEFAULTS.autoTrim;
 	const maxAutoTrimRetries = config.maxAutoTrimRetries ?? DEFAULTS.maxAutoTrimRetries;
+	const autoTrimShrink = config.autoTrimShrink ?? DEFAULTS.autoTrimShrink;
+	const preferInPlacePrune = config.preferInPlacePrune ?? DEFAULTS.preferInPlacePrune;
+	const pruneThresholdChars = config.pruneThresholdChars ?? DEFAULTS.pruneThresholdChars;
+	const pruneHeadChars = config.pruneHeadChars ?? DEFAULTS.pruneHeadChars;
+	const pruneTailChars = config.pruneTailChars ?? DEFAULTS.pruneTailChars;
 	assertRatio('targetRatio', targetRatio);
 	assertNonNegativeInteger('reserveOutputTokens', reserveOutputTokens);
 	assertNonNegativeInteger('minTailTokens', minTailTokens);
 	assertNonNegativeInteger('protectHeadNodes', protectHeadNodes);
 	assertNonNegativeInteger('markerSlackTokens', markerSlackTokens);
 	assertNonNegativeInteger('maxAutoTrimRetries', maxAutoTrimRetries);
+	assertRatio('autoTrimShrink', autoTrimShrink);
 	if (typeof autoTrim !== 'boolean') throw new Error('ContextTrimConfig: autoTrim must be a boolean');
+	if (typeof preferInPlacePrune !== 'boolean') throw new Error('ContextTrimConfig: preferInPlacePrune must be a boolean');
+	assertNonNegativeInteger('pruneHeadChars', pruneHeadChars);
+	assertNonNegativeInteger('pruneTailChars', pruneTailChars);
+	assertPositiveInteger('pruneThresholdChars', pruneThresholdChars);
+	// Mirror the official pruner's load-time guard: the emitted head + marker + tail
+	// must fit inside the threshold, or a rewrite could not both shrink and comply.
+	const emitted = pruneHeadChars + TRIM_MARKER.length + pruneTailChars;
+	if (emitted > pruneThresholdChars) {
+		throw new Error(`ContextTrimConfig: pruneHeadChars + marker + pruneTailChars (${emitted}) must be at most pruneThresholdChars (${pruneThresholdChars})`);
+	}
 	if (typeof allowTailTrim !== 'boolean') throw new Error('ContextTrimConfig: allowTailTrim must be a boolean');
 	const retention = resolveRetention(config);
 	if (retention.retainRatio !== undefined && retention.retainRatio >= targetRatio) {
@@ -75,7 +103,12 @@ export function resolveConfig(config = {}) {
 		allowTailTrim,
 		markerSlackTokens,
 		autoTrim,
-		maxAutoTrimRetries
+		maxAutoTrimRetries,
+		autoTrimShrink,
+		preferInPlacePrune,
+		pruneThresholdChars,
+		pruneHeadChars,
+		pruneTailChars
 	});
 }
 
@@ -130,6 +163,12 @@ function assertRatio(name, value) {
 	}
 }
 
+function assertPositiveInteger(name, value) {
+	if (!Number.isInteger(value) || value <= 0) {
+		throw new Error(`ContextTrimConfig: ${name} (${String(value)}) must be a positive integer`);
+	}
+}
+
 function assertNonNegativeInteger(name, value) {
 	if (!Number.isInteger(value) || value < 0) {
 		throw new Error(`ContextTrimConfig: ${name} (${String(value)}) must be a non-negative integer`);

package/lib/prune-first.js

@@ -0,0 +1,131 @@
+/**
+ * In-place tool-result slimming, run **before** any span elision.
+ *
+ * DSH already owns this idea (`@deepseek-ai/dsh-compaction-tool-result-pruner`),
+ * but a host-plane plugin can only reach that service where compaction itself is
+ * mounted on the host plane. In a 0.1.5 web profile the host row is disabled and
+ * the pruner is re-mounted inside an agent-preset isolate realm, where
+ * `ctx.get('toolResultPruner')` resolves nothing. So this module prefers the
+ * official service when it is visible and otherwise performs the same transform
+ * itself, which keeps the cheap reduction ahead of the expensive one:
+ *
+ *   slim oversized tool results in place  →  elide a whole span  →  compaction
+ *
+ * The transform mirrors the official one: text is measured and sliced in Unicode
+ * code points (never splitting a surrogate pair), the head and tail are kept, one
+ * marker replaces the removed middle, non-text blocks keep their order, and the
+ * replacement carries the complete original event data except `content` — so the
+ * tool call keeps its result and the step stays intact.
+ *
+ * A `tool/result` replacement is only legal inside an open turn, which is exactly
+ * the state the automatic overflow path runs in; the idle `/trim` command never
+ * uses this module.
+ *
+ * @module dsh-command-context-trim/prune-first
+ */
+import { freezeMessage } from '@deepseek-ai/dsh-llm';
+import { replaceKeys, replacementOp } from './session-compat.js';
+
+/**
+ * Marker replacing the removed middle. Deliberately worded for the model and
+ * distinct from DSH's own `[... tool result middle pruned ...]`, so a session log
+ * shows which producer slimmed a node.
+ */
+export const TRIM_MARKER = '\n\n[... tool result middle trimmed to fit the context window ...]\n\n';
+
+/**
+ * Slim every over-budget tool result on the current surface.
+ * @param ctx - plugin context; `ctx.get('toolResultPruner')` is used when present.
+ * @param session - session whose surface is rewritten.
+ * @param config - resolved configuration.
+ * @returns `{ pruned, via, replacementSeq }`; `pruned` is the number of nodes rewritten.
+ */
+export function shrinkOversizedToolResults(ctx, session, config) {
+	if (config.preferInPlacePrune !== true) return { pruned: 0, via: 'disabled' };
+	const official = ctx.get?.('toolResultPruner');
+	if (official !== undefined && typeof official.pruneSession === 'function') {
+		const outcome = official.pruneSession(session);
+		const pruned = Array.isArray(outcome?.pruned) ? outcome.pruned.length : 0;
+		return { pruned, via: 'service', replacementSeq: outcome?.pruned?.at(-1)?.replacementSeq };
+	}
+	const keys = replaceKeys();
+	let pruned = 0;
+	let replacementSeq;
+	// Snapshot first: replacements are appended while iterating.
+	for (const seq of [...session.surface.nodes]) {
+		const event = session.eventAt(seq);
+		if (event?.type !== 'tool/result') continue;
+		const result = event.data.message.content[0];
+		const content = pruneContent(result.content, config);
+		if (content === null) continue;
+		const message = freezeMessage({
+			...event.data.message,
+			content: [{ ...result, content }]
+		});
+		session.append('compaction/prune', {
+			shadowedRange: { start: seq, end: seq },
+			shadowedSeqs: [seq],
+			shadowedTokenCount: ctx.tokenMeter.estimateMessage(event.data.message)
+		});
+		const replacement = session.append('tool/result', { ...event.data, message }, {
+			surfaceOp: replacementOp(keys, seq, seq),
+			sourceEventSeqs: [seq]
+		});
+		pruned += 1;
+		replacementSeq = replacement.seq;
+	}
+	return { pruned, via: 'inline', ...(replacementSeq === undefined ? {} : { replacementSeq }) };
+}
+
+/**
+ * Measure tool-result text in Unicode code points; non-text blocks cost zero.
+ * @param blocks - tool-result content blocks.
+ * @returns total code points across text blocks.
+ */
+export function measureContent(blocks) {
+	let chars = 0;
+	for (const block of blocks) if (block.type === 'text') chars += codePointLength(block.text);
+	return chars;
+}
+
+/**
+ * Replace an over-budget text middle while retaining rich-block order.
+ * @param blocks - original tool-result content.
+ * @param config - resolved configuration with the character budgets.
+ * @returns rewritten content, or `null` when the text is already within budget.
+ */
+export function pruneContent(blocks, config) {
+	const totalChars = measureContent(blocks);
+	if (totalChars <= config.pruneThresholdChars) return null;
+	const removedStart = config.pruneHeadChars;
+	const removedEnd = totalChars - config.pruneTailChars;
+	const pruned = [];
+	let consumed = 0;
+	let markerInserted = false;
+	for (const block of blocks) {
+		if (block.type !== 'text') {
+			pruned.push(block);
+			continue;
+		}
+		const points = Array.from(block.text);
+		const blockStart = consumed;
+		const blockEnd = blockStart + points.length;
+		const headEnd = Math.min(points.length, Math.max(0, removedStart - blockStart));
+		const tailStart = Math.min(points.length, Math.max(0, removedEnd - blockStart));
+		const marker = blockStart < removedEnd && blockEnd > removedStart && !markerInserted ? TRIM_MARKER : '';
+		if (marker.length > 0) markerInserted = true;
+		const text = points.slice(0, headEnd).join('') + marker + points.slice(tailStart).join('');
+		if (text.length > 0) pruned.push({ ...block, text });
+		consumed = blockEnd;
+	}
+	if (!markerInserted) return null;
+	const charsAfter = measureContent(pruned);
+	// Refuse a rewrite that would not actually be smaller and within budget.
+	if (charsAfter > config.pruneThresholdChars || charsAfter >= totalChars) return null;
+	return pruned;
+}
+
+/** Count Unicode code points without splitting surrogate pairs. */
+function codePointLength(text) {
+	return Array.from(text).length;
+}

package/lib/render.js

@@ -113,3 +113,21 @@ export function describeError(error) {
 		return '<unrenderable thrown value>';
 	}
 }
+
+/**
+ * Render one automatic-path outcome, which may be an in-place slim with no span
+ * elision, a span elision, or a slim followed by a span elision.
+ * @param outcome - the object returned by `executeTrim`.
+ * @returns a single-line account.
+ */
+export function logLineFor(outcome) {
+	if (outcome.plan === undefined) {
+		return (
+			`slimmed ${outcome.pruned.pruned} oversized tool result(s) in place for ${outcome.label}; ` +
+			`request ~${outcome.before.totalTokens} → ~${outcome.after.totalTokens} tokens`
+		);
+	}
+	const base = logLine(outcome.plan, outcome.after, outcome.label);
+	if (outcome.pruned === undefined || outcome.pruned.pruned === 0) return base;
+	return `${outcome.pruned.pruned} tool result(s) slimmed in place, then ${base}`;
+}

package/lib/trim-session.js

@@ -14,6 +14,7 @@ import { toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-a
 import { applyTrim, createMarkerMessage, provisionalMarker } from './apply.js';
 import { budgetFor, retentionFor } from './config.js';
 import { planTrim } from './plan.js';
+import { shrinkOversizedToolResults } from './prune-first.js';
 import { describeNonSpan, preview, report } from './render.js';
 import { replaceKeys } from './session-compat.js';
 import { resolveTarget, targetHeader } from './target.js';
@@ -26,6 +27,10 @@ import { resolveTarget, targetHeader } from './target.js';
  * @property {number} [explicitBudget] - explicit token budget instead of a resolved window.
  * @property {boolean} [check] - plan only, mutate nothing.
  * @property {boolean} [routedOnly] - target the route the last durable request used.
+ * @property {number} [budgetCeiling] - hard upper bound on the target budget, used when a
+ *   request of a known size has just been rejected and the declared window cannot be trusted.
+ * @property {boolean} [inPlaceFirst] - slim oversized tool results in place before planning a
+ *   span. Only legal inside an open turn, so the automatic path sets it and `/trim` never does.
  */
 
 /**
@@ -38,16 +43,43 @@ import { resolveTarget, targetHeader } from './target.js';
  *   surface was actually rewritten.
  */
 export async function executeTrim(ctx, config, request) {
-	const { agent, signal, requestedRoute, explicitBudget, check = false, routedOnly = false } = request;
+	const { agent, signal, requestedRoute, explicitBudget, check = false, routedOnly = false, budgetCeiling, inPlaceFirst = false } = request;
 	signal?.throwIfAborted?.();
 	const session = agent.session;
 	assertNoOpenCompaction(session);
 	const target =
 		explicitBudget === undefined ? await resolveTarget(ctx, agent, requestedRoute, signal, { routedOnly }) : undefined;
-	const budget = explicitBudget ?? budgetFor(target.contextWindow, config);
-	const label = target === undefined ? `an explicit ${budget}-token budget` : `${target.label} (window ${target.contextWindow})`;
+	const windowBudget = explicitBudget ?? budgetFor(target.contextWindow, config);
+	const budget = budgetCeiling === undefined ? windowBudget : Math.min(windowBudget, budgetCeiling);
+	const baseLabel = target === undefined ? `an explicit ${budget}-token budget` : `${target.label} (window ${target.contextWindow})`;
+	const label = budget === windowBudget ? baseLabel : `${baseLabel}, capped at ${budget}`;
 	const header = target === undefined ? undefined : targetHeader(session, target);
-	const measurement = ctx.tokenMeter.measure(session, header);
+	let measurement = ctx.tokenMeter.measure(session, header);
+	// Cheap reduction first: a single oversized tool result is slimmed in place
+	// (keeping the node, its tool call and the prefix up to it) and a span is only
+	// elided when that is not enough.
+	let pruned;
+	if (inPlaceFirst) {
+		const shrunk = shrinkOversizedToolResults(ctx, session, config);
+		if (shrunk.pruned > 0) {
+			const afterPrune = ctx.tokenMeter.measure(session, header);
+			pruned = shrunk;
+			if (afterPrune.totalTokens <= budget) {
+				return {
+					result: {
+						kind: 'success',
+						text: `Slimmed ${shrunk.pruned} oversized tool result(s) in place for ${label}: ~${measurement.totalTokens} → ~${afterPrune.totalTokens} tokens (target ${budget}).`,
+						...(shrunk.replacementSeq === undefined ? {} : { sourceEventSeq: shrunk.replacementSeq })
+					},
+					label,
+					before: measurement,
+					after: afterPrune,
+					pruned: shrunk
+				};
+			}
+			measurement = afterPrune;
+		}
+	}
 	const nodes = measurement.nodes.map((node) => {
 		const type = session.eventAt(node.seq)?.type;
 		return {
@@ -65,6 +97,10 @@ export async function executeTrim(ctx, config, request) {
 	if (nodes.length === 0) {
 		return { result: { kind: 'success', text: `Nothing to trim: ${session.id} has no model-visible messages yet.` } };
 	}
+	const notePrune = (result) =>
+		pruned === undefined
+			? result
+			: { ...result, text: `${result.text}\n(Note: ${pruned.pruned} oversized tool result(s) were already slimmed in place.)` };
 	// The retained tail scales with the capacity being fitted: the target window
 	// when one is known, otherwise the explicit budget itself.
 	const retainTokens = retentionFor(target?.contextWindow ?? budget, config);
@@ -84,18 +120,18 @@ export async function executeTrim(ctx, config, request) {
 		});
 	let markerTokens = ctx.tokenMeter.estimateMessage(provisionalMarker());
 	let plan = planFor(markerTokens);
-	if (plan.kind !== 'span') return { result: describeNonSpan(plan, label), plan, label, before: measurement };
+	if (plan.kind !== 'span') return { result: notePrune(describeNonSpan(plan, label)), plan, label, before: measurement, ...(pruned === undefined ? {} : { pruned }) };
 	let marker = createMarkerMessage(plan, target?.label ?? `budget ${budget}`, budget);
 	const finalMarkerTokens = ctx.tokenMeter.estimateMessage(marker);
 	if (finalMarkerTokens > markerTokens) {
 		// The marker now carries real numbers; re-plan once so its own price is exact.
 		plan = planFor(finalMarkerTokens);
-		if (plan.kind !== 'span') return { result: describeNonSpan(plan, label), plan, label, before: measurement };
+		if (plan.kind !== 'span') return { result: notePrune(describeNonSpan(plan, label)), plan, label, before: measurement, ...(pruned === undefined ? {} : { pruned }) };
 		marker = createMarkerMessage(plan, target?.label ?? `budget ${budget}`, budget);
 		markerTokens = finalMarkerTokens;
 	}
 	if (check) {
-		return { result: { kind: 'success', text: preview(plan, label, markerTokens) }, plan, label, before: measurement };
+		return { result: { kind: 'success', text: preview(plan, label, markerTokens) }, plan, label, before: measurement, ...(pruned === undefined ? {} : { pruned }) };
 	}
 	const replacement = applyTrim(session, plan, marker, replaceKeys());
 	const after = ctx.tokenMeter.measure(session, header);
@@ -106,7 +142,8 @@ export async function executeTrim(ctx, config, request) {
 		before: measurement,
 		after,
 		markerTokens,
-		replacement
+		replacement,
+		...(pruned === undefined ? {} : { pruned })
 	};
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-command-context-trim",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Model-free /trim for DeepSeek Harness — drop the oldest, least valuable span of context on demand (the `/trim` command) or automatically when a request hits the model's context wall, without any model call.",
   "license": "MIT",
   "author": "snailium",