dsh-command-context-trim 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,75 @@ All notable changes to this project are documented here. This project adheres to
 
 ## [Unreleased]
 
+## [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
+
+- **DeepSeek Harness 0.1.5 compatibility.** 0.1.5 renamed the positional replacement marker
+  (`{op: 'replace', start, end}` → `{op: 'replace', startSeq, endSeq}`), so every trim failed with
+  `session event "user/message" carries an invalid replace surfaceOp`. The plugin now probes the accepted shape
+  once against the harness actually installed and writes that one, so the same build works on the 0.1.2 and
+  0.1.5 lines without a version check.
+- **The system prompt is never trimmed — and no longer eats head protection.** 0.1.5 moved the system prompt
+  from the request header onto the surface as node 0 (`system/message`). A position-only "protect the first
+  node" rule would have protected the *system prompt* and exposed the **user's original request** as the first
+  elidable message. System nodes are now barriers: never elided and never crossed, and `protectHeadNodes` counts
+  only non-barrier nodes, so it keeps protecting the task statement.
+
+### Notes
+
+- No configuration changes. The only user-visible difference is the "fixed request overhead" refusal, which now
+  says "tool schemas and other non-surface request data": on 0.1.5 the system prompt is surface content rather
+  than header content.
+- Verified on harness 0.1.2-rc.1 and 0.1.5-rc.2 (40 tests each, same build).
+
+
+### Added
+
+- Integration tests against the **real** `ctx.tokenMeter` (bare cordis context + stub projection registry): a trim's
+  measured saving equals the `compaction/prune` shadow price it claims minus the replacement marker, and a *fresh* meter
+  folding the replayed log reaches the identical total — the replay property the claim exists for.
+
 ## [0.1.0] - 2026-09-15
 
 ### Added
@@ -32,5 +101,7 @@ 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.0...HEAD
+[Unreleased]: https://github.com/snailium/dsh-command-context-trim/compare/v0.2.0...HEAD
+[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

@@ -22,7 +22,7 @@ synchronous appends, zero LLM calls — it works precisely when every request is
 ## Install
 
 ```bash
-# from npm, once published
+# from npm
 dsh plugin --profile web add dsh-command-context-trim
 
 # from a checkout
@@ -78,21 +78,92 @@ Design consequences:
   original content stays in the durable session log, so a trim is auditable and recoverable by hand.
 - **No tool-call/result pair is ever split.** Cut edges are chosen with
   `toolPairingBalancedBefore`/`After` from `@deepseek-ai/dsh-compaction`.
+- **The system prompt is never trimmed** (harness 0.1.5+ carries it as a surface node): it is a barrier that no
+  elided span may touch or cross.
 - **Mutual exclusion with everything else.** The handler runs inside `agent.runMaintenance()`, which fails unless the agent
   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 1) 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.
+
+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 |
+|---|---|
+| 0.1.2-rc.1 (`latest`) | ✅ full suite green |
+| 0.1.5-rc.2 (`next`) | ✅ full suite green |
+
+Two harness changes between those lines are handled without a version check:
+
+- **The replacement marker was renamed** — `{op: 'replace', start, end}` became `{op: 'replace', startSeq, endSeq}`.
+  The plugin probes a throwaway detached session with each known shape at first use and writes the accepted one.
+- **The system prompt moved onto the surface** — 0.1.5 carries it as `system/message` node 0 instead of
+  `header.system`. System nodes are treated as **barriers**: they are never elided, no elided span crosses one,
+  and `protectHeadNodes` counts only non-barrier nodes, so head protection keeps covering the task statement
+  rather than the system prompt.
+
+Because of the second change, the fixed request overhead is now the tool schemas plus any other non-surface
+request data; on 0.1.2 it also included the system prompt. A trim's budget itself is unaffected — it comes from
+the token meter's total, whichever way the harness splits that total.
+
 ## Configuration
 
 Override on the `context-trim` row of a profile patch (the bundle's own `cordis.patch.yml` lists the full default set):
@@ -104,8 +175,10 @@ Override on the `context-trim` row of a profile patch (the bundle's own `cordis.
 | `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` | `1` | Automatic trims allowed per overflow episode before compaction takes over |
 
 ## Limits
 
@@ -121,6 +194,23 @@ Override on the `context-trim` row of a profile patch (the bundle's own `cordis.
 
 ## 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
@@ -128,21 +218,27 @@ npm run link:harness   # or resolve @deepseek-ai from a local dsh installation i
 ```
 
 Tests cover the pure planner and argument parser, the surface mutation against a real `Session` (including log replay),
-and the plugin's command registration and end-to-end trim over a stub context. CI runs the suite on Node 22 and 24;
+the plugin's command registration and end-to-end trim over a stub context, and — against the real `ctx.tokenMeter` — that a
+trim's measured saving equals the shadow price it claims and that a fresh meter replaying the trimmed log lands on the very
+same total. CI runs the suite on Node 22 and 24;
 releases go out through `.github/workflows/publish.yml`, which is manual-only (`workflow_dispatch`).
 
 ### Verification status
 
 | Check | State |
 |---|---|
-| `npm test` (30 tests: planner, args, surface apply + replay, plugin handler) | ✅ passing |
+| `npm test` (51 tests: planner, args, surface apply + log replay, plugin handler, automatic overflow path) | ✅ 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`) | ✅ 30 passing |
-| CI workflow (Node 22 / 24) | ⏳ first run pending |
-| npm release via GitHub Actions | ⏳ first publish pending (Trusted Publishing cannot create a brand-new package; see the `npm-publish` procedure) |
-| End-to-end in the web GUI against a small-window model | ⏳ not yet run |
+| Same suite against the pinned **published** harness packages (`npm ci`) | ✅ 51 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 |
+| 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 |
+| End-to-end in the web GUI against a small-window model | ⏳ harness ready, not yet run |
 
 ## License
 

package/README.zh.md

@@ -17,7 +17,7 @@
 ## 安装
 
 ```bash
-dsh plugin --profile web add dsh-command-context-trim          # 发布到 npm 后
+dsh plugin --profile web add dsh-command-context-trim          # 从 npm 安装
 dsh plugin --profile web add file:/path/to/dsh-command-context-trim   # 从源码
 ```
 
@@ -53,11 +53,54 @@ 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 **一律不碰**（有测试锁定注册的监听器集合）。
+
+每轮溢出 epis 的额度由 `maxAutoTrimRetries`（默认 1）限制，收到完成的 assistant 消息或 agent 空闲即重置。
+代价如实说：自动 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。
 
+## 兼容性
+
+| Harness | 状态 |
+|---|---|
+| 0.1.2-rc.1（`latest`） | ✅ 全套测试通过 |
+| 0.1.5-rc.2（`next`） | ✅ 全套测试通过 |
+
+两处 0.1.5 变更已在不做版本号判断的前提下兼容：
+
+- **替换标记改名**：`{op:'replace', start, end}` → `{op:'replace', startSeq, endSeq}`。插件首次使用时用一个一次性游离 session 探测本机 harness 接受哪种形状，再按该形状写入。
+- **system prompt 从 header 搬到了 surface**（0.1.5 作为 `system/message` 节点 0）。system 节点被当作**屏障**：永不裁剪、任何被裁区间都不得跨越它；同时 `protectHeadNodes` 只统计非屏障节点，因此"保护头部"保护的仍是**用户的任务声明**，而不是 system prompt。
+
+因此"固定请求开销"的含义变为工具 schema + 其它非 surface 请求数据（0.1.2 上还包含 system prompt）；裁剪预算本身不受影响，因为它来自 token meter 的总量。
+
 ## 配置
 
 在 profile patch 的 `context-trim` 行上覆盖（`cordis.patch.yml` 里列出了全部默认值）：
@@ -82,10 +125,10 @@ npm test               # node --test
 npm run link:harness   # 也可改为从本地 dsh 安装的依赖闭包解析 @deepseek-ai
 ```
 
-已验证：30 个测试全部通过（选段算法、参数解析、真实 Session 上的 surface 改写与日志重放、插件命令注册与端到端裁剪）；
+已验证：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 首发（Trusted Publishing 无法创建全新包名，需要一次首发布引导）、以及 Web GUI 里的真实小窗口端到端验证。
+npm 0.2.0（新增撞墙自动 trim），并已在隔离 profile 里从 registry 安装验证；尚未执行：Web GUI 里的真实小窗口端到端验证（mock provider 与隔离实例已就绪）。
 
 ## License
 

package/cordis.patch.yml

@@ -27,3 +27,9 @@
         # 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.
+        maxAutoTrimRetries: 1

package/lib/apply.js

@@ -21,6 +21,7 @@
  * @module dsh-command-context-trim/apply
  */
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { replacementOp } from './session-compat.js';
 
 /** Plugin name written into every replacement message's source marker. */
 export const TRIM_PLUGIN = 'dsh-command-context-trim';
@@ -81,17 +82,18 @@ export function isTrimMarkerSource(source) {
  * @param session - session whose surface is rewritten.
  * @param plan - committed span plan naming the shadowed range.
  * @param marker - replacement message built for that plan.
+ * @param keys - replacement-marker keys this harness accepts ({@link replaceKeys}).
  * @returns the appended replacement event.
  * @throws when the session rejects the append (surface contract violation).
  */
-export function applyTrim(session, plan, marker) {
+export function applyTrim(session, plan, marker, keys) {
 	session.append('compaction/prune', {
 		shadowedRange: { start: plan.startSeq, end: plan.endSeq },
 		shadowedSeqs: [...plan.shadowedSeqs],
 		shadowedTokenCount: plan.shadowedTokens
 	});
 	return session.append('user/message', marker, {
-		surfaceOp: { op: 'replace', start: plan.startSeq, end: plan.endSeq },
+		surfaceOp: replacementOp(keys, plan.startSeq, plan.endSeq),
 		sourceEventSeqs: [...plan.shadowedSeqs]
 	});
 }

package/lib/auto-trim.js

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ *
+ * @module dsh-command-context-trim/auto-trim
+ */
+import { CONTEXT_WINDOW_EXCEEDED_CODE } from '@deepseek-ai/dsh-llm';
+import { logLine, 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, 'info', `context-overflow auto-trim: retry budget spent (${used}); leaving recovery to compaction`);
+				return next();
+			}
+			const generation = agent.session.surface.replaceGeneration;
+			let outcome;
+			try {
+				outcome = await executeTrim(ctx, config, { agent, signal, routedOnly: 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`);
+				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)}`);
+			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

@@ -15,7 +15,9 @@ export const DEFAULTS = Object.freeze({
 	minTailTokens: 2048,
 	protectHeadNodes: 1,
 	allowTailTrim: true,
-	markerSlackTokens: 64
+	markerSlackTokens: 64,
+	autoTrim: true,
+	maxAutoTrimRetries: 1
 });
 
 /** Every key this plugin accepts. */
@@ -27,7 +29,9 @@ const CONFIG_KEYS = new Set([
 	'minTailTokens',
 	'protectHeadNodes',
 	'allowTailTrim',
-	'markerSlackTokens'
+	'markerSlackTokens',
+	'autoTrim',
+	'maxAutoTrimRetries'
 ]);
 
 /**
@@ -48,11 +52,15 @@ 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;
 	assertRatio('targetRatio', targetRatio);
 	assertNonNegativeInteger('reserveOutputTokens', reserveOutputTokens);
 	assertNonNegativeInteger('minTailTokens', minTailTokens);
 	assertNonNegativeInteger('protectHeadNodes', protectHeadNodes);
 	assertNonNegativeInteger('markerSlackTokens', markerSlackTokens);
+	assertNonNegativeInteger('maxAutoTrimRetries', maxAutoTrimRetries);
+	if (typeof autoTrim !== 'boolean') throw new Error('ContextTrimConfig: autoTrim must be a boolean');
 	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 +73,9 @@ export function resolveConfig(config = {}) {
 		minTailTokens,
 		protectHeadNodes,
 		allowTailTrim,
-		markerSlackTokens
+		markerSlackTokens,
+		autoTrim,
+		maxAutoTrimRetries
 	});
 }