dsh-command-context-trim 0.1.1 → 0.2.2

package/CHANGELOG.md

@@ -5,6 +5,102 @@ 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
+
+- **Automatic trimming on the context wall.** A `prepend`ed `agent/request-error` listener reacts to
+  `CONTEXT_WINDOW_EXCEEDED`, frees space with no model call, and asks the loop to retry. Only when it cannot free
+  anything does the waterfall continue into DSH's own recovery (prune + summarize) — so a session that hits the wall
+  is repaired by *dropping* the oldest span first and only pays for summarization when dropping cannot help.
+  This is the unattended form of `/trim`; it is the same execution, invoked by the harness instead of a human.
+- Configuration `autoTrim` (default `true`) and `maxAutoTrimRetries` (default `1`, per overflow episode).
+- **The elided span is chosen by explicit preference tiers.** Elision always starts at the oldest balanced cut, and the
+  search is graded: (1) stay outside the retained tail and keep the final message, with the configured retention relaxed
+  step by step only if the fit otherwise fails; (2) reach into the retained tail, still keeping the final message;
+  (3) last resort — include the final message, typically the current step's assistant tool-call plus its tool result,
+  which can only be removed as a pair. `allowTailTrim: false` ends the list after tier 1. The plan and every rendered
+  result state when the last-resort tier was used.
+- **Planner anchor changed: the newest `user/message` is protected, the final node is not.** The previous rule
+  ("never elide the final surface node") deadlocked the most common overflow shape — one large assistant tool-call whose
+  tool result is the last node could not be removed as a pair, so only a handful of tokens were freeable while the
+  request stayed over the wall (observed live: "largest balanced span frees ~4 of the ~4631 tokens needed"). The newest
+  human instruction is now a **barrier** (never elided, never crossed) and everything after it stays eligible, tool
+  pairing still enforced on both cut edges.
+
+### Notes
+
+- **Scope: the context wall only.** The listener fires exclusively for `CONTEXT_WINDOW_EXCEEDED`. Ordinary
+  threshold compaction (`agent/pre-step` pressure), `/compact`, and the tool-result pruner are untouched — this is
+  asserted by a test that pins the registered listener set.
+- Why `prepend` is required: `agent/request-error` is a Cordis waterfall and compaction registers its summarization
+  recovery on the same event. Cordis stores listeners in registration order and `{ prepend: true }` unshifts, so this
+  listener runs first even when compaction is mounted later inside an agent-preset isolate realm (as it is in a web
+  profile). Returning `{ kind: 'retry' }` without calling `next()` vetoes summarization for that attempt.
+- The per-episode budget resets when a completed assistant message lands or the agent goes idle, mirroring
+  compaction's own overflow accounting.
+- Trade-off, stated plainly: an automatic trim **drops** the oldest span rather than summarizing it. That is the
+  point on a small local window — the summarizer must fit the region it is condensing and frequently cannot — but it
+  does mean the dropped text is replaced by a marker instead of a summary. `/compact` remains available, and the full
+  text stays in the durable session log.
+
+
 ## [0.1.1] - 2026-09-15
 
 ### Fixed
@@ -61,6 +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.1.1...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

@@ -84,17 +84,87 @@ Design consequences:
   is idle, so it cannot interleave with a turn, `/compact`, or automatic compaction; it also refuses while an unmatched
   `compaction/start` is open.
 
+## Automatic trimming on the context wall
+
+`autoTrim` (default on) makes the same model-free reduction happen without anyone typing a command: a **prepended**
+`agent/request-error` listener reacts to `CONTEXT_WINDOW_EXCEEDED`, trims, and asks the loop to retry.
+
+```
+request fails (context wall)
+  ├─ prepended: context-trim   → trim a span, no model call → retry      ← wins when it can free space
+  └─ next(): compaction-basic  → prune tool results → summarize (LLM)    ← only when trimming cannot help
+```
+
+Why `prepend` is the whole trick: `agent/request-error` is a Cordis **waterfall**, and compaction registers its own
+summarization recovery on the same event. Cordis keeps listeners in registration order and `{ prepend: true }`
+unshifts to the front, so this plugin runs first even though compaction is mounted later — in a web profile it lives
+inside an agent-preset isolate realm, which no host-plane plugin can out-order by mount position. Returning
+`{ kind: 'retry' }` without calling `next()` vetoes summarization for that attempt.
+
+Scope, deliberately narrow:
+
+| Event | Behaviour |
+|---|---|
+| `CONTEXT_WINDOW_EXCEEDED` on `agent/request-error` | trim, then retry |
+| any other request failure | untouched (`next()`) |
+| ordinary threshold compaction (`agent/pre-step` pressure) | **never touched** |
+| `/compact`, the tool-result pruner | **never touched** |
+
+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
+durable session log.
+
 ## What is protected
 
 | Protected | Why |
 |---|---|
 | Leading `protectHeadNodes` nodes (default 1) | The task statement — dropping it destroys the point of the conversation. |
 | Recent tail (`retainRatio` of the window, floor `minTailTokens`) | Recency is what a coding agent needs; retention is relaxed only when the fit is otherwise impossible, and the result says so. |
-| The final surface node | Never elided, even when trimming into the tail. |
+| The **newest** `user/message` | The live human instruction. It is never elided and no span may cross it, so an ongoing request cannot be dropped. Older user messages are ordinary nodes. |
+| The final surface message | **A preference, not a prohibition.** Kept whenever any older span can free enough; dropped only as a last resort, and typically only together with its tool call (they can only be removed as a pair). |
 
 Within those bounds the policy is **oldest-first, least-long-possible**: the elided span starts at the oldest balanced cut
 and grows only until it frees exactly enough tokens.
 
+Elision always starts at the **oldest** balanced cut, and the search is graded so that the cheapest loss is tried first:
+
+1. a span that stays **outside the retained tail** and keeps the **final message** (the configured retention, relaxed step
+   by step only if the fit otherwise fails);
+2. a span that may reach **into the retained tail**, still keeping the final message;
+3. **last resort** — a span that includes the final message, typically the current step's assistant tool-call plus its tool
+   result, which can only be removed as a pair.
+
+Protecting the final message outright deadlocks the most common overflow shape: one large assistant tool-call whose tool
+result is the last node cannot be removed as a pair, which left a handful of freeable tokens while the request stayed over
+the wall (observed live: "largest balanced span frees ~4 of the ~4631 tokens needed"). The newest user message is the real
+anchor and stays a hard barrier in every tier. With `allowTailTrim: false` the search ends after tier 1, so the retained
+tail is a hard boundary and the final message is never dropped.
+
 ## Compatibility
 
 | Harness | State |
@@ -122,12 +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` | Let the elided span reach into the retained tail when necessary |
+| `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` | `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
 
@@ -141,8 +216,47 @@ 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)
+
+`scripts/mock-overflow-server.mjs` is a stateful OpenAI-compatible endpoint that enforces a **real** limit lower than the
+`contextWindow` the harness is told, and answers the first `TOOL_STEPS` requests with a tool call so one turn keeps
+looping and grows past the real limit — the context wall, without a model switch:
+
+```bash
+node scripts/mock-overflow-server.mjs &            # PORT=4185 TOKEN_LIMIT=12000 TOOL_STEPS=4
+# point an ISOLATED profile at it (provider with contextWindow 20000, baseURL .../v1), then:
+DSH_HOME=$(mktemp -d) dsh --profile headless "..."   # see the isolated-home procedure in dsh-plugin-packaging
+```
+
+A passing run leaves this in the session log: `assistant/attempt` (the wall), then exactly one `compaction/prune` + one
+`user/message` replacement, then a **succeeding** retry — and **zero** `compaction/start`, proving the request was
+repaired by trimming and that summarisation never ran.
+
+
 ```bash
 npm install            # the harness contracts this plugin builds on, pinned as devDependencies
 npm test               # node --test
@@ -159,13 +273,15 @@ releases go out through `.github/workflows/publish.yml`, which is manual-only (`
 
 | Check | State |
 |---|---|
-| `npm test` (34 tests: planner, args, surface apply + log replay, plugin handler) | ✅ 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`) | ✅ 34 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 |
-| Same suite on harness 0.1.5-rc.2 (renamed marker + surface system prompt) | ✅ 40 passing |
+| 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 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

@@ -53,9 +53,48 @@ dsh plugin --profile web add file:/path/to/dsh-command-context-trim   # 从源
 - **与其它机制互斥**：命令在 `agent.runMaintenance()` 内执行（非 idle 直接失败），不会与回合、`/compact`、自动压缩交错；
   存在未闭合的 `compaction/start` 时也会拒绝执行。
 
+## 撞墙自动 trim
+
+`autoTrim`（默认开）让同一套"无模型调用"的裁剪在无人值守时发生：用 **`prepend`** 注册的 `agent/request-error`
+监听器在 `CONTEXT_WINDOW_EXCEEDED` 时裁剪并请求重试。
+
+```
+请求撞墙
+  ├─ prepend: context-trim   → 裁剪一段，零模型调用 → retry       ← 能腾出空间时由它解决
+  └─ next(): compaction-basic → 先 prune 工具结果再摘要（LLM）     ← 只在 trim 无能为力时
+```
+
+为什么 `prepend` 是关键：`agent/request-error` 是 Cordis 的 **waterfall**，compaction 也在同一事件上注册了自己的
+摘要恢复；Cordis 按注册顺序存放监听器，`{ prepend: true }` 会 `unshift` 到最前，所以即使 compaction 是稍后在
+agent-preset 的 isolate realm 里挂载的（web profile 里就是这样），本插件依然先执行。不调用 `next()` 即否决该次
+摘要。
+
+**范围刻意收窄**：只有 `CONTEXT_WINDOW_EXCEEDED` 才触发；其它请求错误、普通阈值 compaction（`agent/pre-step` 压力路径）、
+`/compact`、工具结果 pruner **一律不碰**（有测试锁定注册的监听器集合）。
+
+每轮溢出 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` 仍在，原文也仍在会话日志里。
+
 ## 保护集与选段策略
 
-保护：开头 `protectHeadNodes`（默认 1，即任务声明）、末尾最近 `retainRatio` 窗口（下限 `minTailTokens`）、以及最后一条消息永不裁剪。
+保护与**优先级**（永远从最旧处开始裁，按"损失最小"逐档尝试）：
+
+1. 留在保留尾部之外，且**保留最后一条**（先按配置的保留量；实在放不下才逐级放宽保留量）；
+2. 可以进入保留尾部，但仍**保留最后一条**；
+3. **最后一档**才允许把最后一条纳入——通常就是当前这步的 assistant tool-call 与它的 tool-result（两者只能成对移除）。
+
+另外：开头 `protectHeadNodes`（默认 1，即任务声明）与**最新的那条 `user/message`（你当前的指令）是硬屏障**——永不裁剪、也不被跨越。把最后一条按位置硬保护会卡死最常见的溢出形态（实测探针：`largest balanced span frees ~4 of the ~4631 tokens needed`）。`allowTailTrim: false` 时搜索在第 1 档后结束：保留尾部成为硬边界，最后一条永不丢弃。
 在保护集之间采用**最旧优先、够用即止**：从最旧的平衡切点开始，只增长到刚好释放够 token。
 
 ## 兼容性
@@ -98,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.1.1 已发布（带 provenance），并已在隔离 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

@@ -27,3 +27,25 @@
         # Slack added to the priced replacement marker, so the post-trim request
         # stays under budget even though the marker text carries real numbers.
         markerSlackTokens: 64
+        # Trim automatically when a request hits the model's context wall
+        # (CONTEXT_WINDOW_EXCEEDED) instead of going straight to compaction.
+        # Ordinary threshold compaction is never touched.
+        autoTrim: true
+        # Automatic trims allowed per overflow episode before compaction takes over.
+        # 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

@@ -0,0 +1,112 @@
+/**
+ * Automatic trimming when a request hits the model's context wall.
+ *
+ * This is the unattended neighbour of `/trim`: a **prepended**
+ * `agent/request-error` listener reacts to `CONTEXT_WINDOW_EXCEEDED`, frees space
+ * with no model call, and asks the loop to retry. Only when it cannot help does
+ * the waterfall continue into DSH's own recovery — which prunes oversized tool
+ * results and then *summarizes*. That ordering is the whole point: dropping the
+ * oldest span is cheap and works when every request is failing, whereas the
+ * summarizer must itself fit the window while holding the region it is condensing,
+ * so on a small local window it frequently fails for the same reason the original
+ * request did.
+ *
+ * Why `prepend` matters: `agent/request-error` is a Cordis **waterfall**, and
+ * `@deepseek-ai/dsh-compaction-basic` registers its summarization recovery on the
+ * same event. Listeners are stored in registration order and `{ prepend: true }`
+ * unshifts to the front, so this listener runs first regardless of which bundle
+ * mounted compaction (in a web profile compaction lives inside an agent-preset
+ * isolate realm, mounted later than any host-plane plugin). Returning
+ * `{ 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 { logLineFor, describeError } from './render.js';
+import { executeTrim } from './trim-session.js';
+
+/**
+ * Register automatic context-overflow trimming.
+ * @param ctx - plugin context (token meter, LLM service, events, logger).
+ * @param config - resolved configuration.
+ * @returns nothing; listeners are owned by the plugin's fiber and disposed with it.
+ */
+export function registerAutoTrim(ctx, config) {
+	if (config.autoTrim !== true) return;
+	/** agent -> automatic trims already spent in the current overflow episode. */
+	const spent = new WeakMap();
+	/** session -> agent, so a successful assistant message can reset the budget. */
+	const actors = new WeakMap();
+	ctx.on(
+		'agent/request-error',
+		async ({ agent, failure, signal }, next) => {
+			if (failure?.code !== CONTEXT_WINDOW_EXCEEDED_CODE || signal.aborted) return next();
+			const used = spent.get(agent) ?? 0;
+			if (used >= config.maxAutoTrimRetries) {
+				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, 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, '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, 'warn', `context-overflow auto-trim: ${logLineFor(outcome)}`);
+			return { kind: 'retry' };
+		},
+		{ prepend: true }
+	);
+	// Mirror compaction-basic's accounting: one overflow episode's budget resets
+	// once the conversation advances or the agent goes idle.
+	ctx.on('agent/status', ({ agent, status }) => {
+		if (status === 'idle') spent.delete(agent);
+	});
+	ctx.on('session/event', (session, event) => {
+		if (event.type !== 'assistant/message') return;
+		const agent = actors.get(session);
+		if (agent !== undefined) spent.delete(agent);
+	});
+}
+
+/** Log through the context logger when it is available. */
+function log(ctx, level, message) {
+	const logger = ctx.logger;
+	if (logger?.[level] === undefined) return;
+	logger[level](`context-trim: ${message}`);
+}

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,
@@ -15,7 +17,14 @@ export const DEFAULTS = Object.freeze({
 	minTailTokens: 2048,
 	protectHeadNodes: 1,
 	allowTailTrim: true,
-	markerSlackTokens: 64
+	markerSlackTokens: 64,
+	autoTrim: true,
+	maxAutoTrimRetries: 3,
+	autoTrimShrink: 0.5,
+	preferInPlacePrune: true,
+	pruneThresholdChars: 8192,
+	pruneHeadChars: 4096,
+	pruneTailChars: 1024
 });
 
 /** Every key this plugin accepts. */
@@ -27,7 +36,14 @@ const CONFIG_KEYS = new Set([
 	'minTailTokens',
 	'protectHeadNodes',
 	'allowTailTrim',
-	'markerSlackTokens'
+	'markerSlackTokens',
+	'autoTrim',
+	'maxAutoTrimRetries',
+	'autoTrimShrink',
+	'preferInPlacePrune',
+	'pruneThresholdChars',
+	'pruneHeadChars',
+	'pruneTailChars'
 ]);
 
 /**
@@ -48,11 +64,31 @@ export function resolveConfig(config = {}) {
 	const protectHeadNodes = config.protectHeadNodes ?? DEFAULTS.protectHeadNodes;
 	const allowTailTrim = config.allowTailTrim ?? DEFAULTS.allowTailTrim;
 	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) {
@@ -65,7 +101,14 @@ export function resolveConfig(config = {}) {
 		minTailTokens,
 		protectHeadNodes,
 		allowTailTrim,
-		markerSlackTokens
+		markerSlackTokens,
+		autoTrim,
+		maxAutoTrimRetries,
+		autoTrimShrink,
+		preferInPlacePrune,
+		pruneThresholdChars,
+		pruneHeadChars,
+		pruneTailChars
 	});
 }
 
@@ -120,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`);