dsh-command-context-trim 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project are documented here. This project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-15
+
+### Added
+
+- **`/trim` — model-free context trimming.** Drops the oldest tool-pairing-balanced span of the model-visible surface so a
+  session built against a large-window cloud model can keep running on a smaller local model. It makes no model call at
+  all, which is the case `/compact` cannot rescue: compaction summarizes, so its summarizer must fit the very region it is
+  condensing in the now-smaller window.
+- Forms: `/trim` (fit the active or pending model window), `/trim check` (plan only, change nothing),
+  `/trim 32k` (explicit budget), `/trim provider:model` (fit another route's declared window).
+- Protected context: the leading task statement (`protectHeadNodes`), the most recent messages (`retainRatio` /
+  `minTailTokens`), and the final surface node. Within those bounds the policy is oldest-first and frees only what the
+  budget requires; retention is relaxed only when the fit is otherwise impossible, and the result says so.
+- Configuration: `targetRatio`, `reserveOutputTokens`, `retainRatio` / `retainTokens`, `minTailTokens`,
+  `protectHeadNodes`, `allowTailTrim`, `markerSlackTokens`.
+- Every refusal (fixed request overhead already over budget, no balanced cut point, not enough freeable) explains itself
+  and writes nothing to the session.
+
+### Notes
+
+- One trim appends exactly two events: a `compaction/prune` shadow-price claim for the meter's O(1) projections, then a
+  `user/message` positional replacement citing every shadowed node. `user/message` is the only surface-eligible event an
+  idle command may append — `assistant/message` needs an open step and a `tool/result` replacement needs an open turn.
+- Nothing is lost: replacements are model-only (the human transcript reads append-origin events) and the full original
+  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
+[0.1.0]: https://github.com/snailium/dsh-command-context-trim/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 snailium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# dsh-command-context-trim
+
+A **model-free `/trim` command** for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): drop the oldest,
+least valuable span of a conversation so a session can continue on a **smaller-context model** — without a single model call.
+
+[中文说明 →](README.zh.md)
+
+## Why
+
+Switching a long session from a large-window cloud model to a smaller local model makes the *next* request exceed the new
+model's window. The established workaround is `/compact` before switching — and that is exactly where it hurts:
+compaction **summarizes**, so its summarizer call must fit the (now smaller) window while holding the very region being
+condensed. It frequently fails for the same reason the original request failed.
+
+DSH's automatic context-overflow recovery has the same property: it retries by summarizing with the routed model, so on a
+too-small local window the recovery call overflows too, and the original error is preserved.
+
+`/trim` needs no model at all. It measures the current request under the target route, picks the oldest
+tool-pairing-balanced span that frees exactly enough tokens, and shadows that span with one short marker message. Two
+synchronous appends, zero LLM calls — it works precisely when every request is failing.
+
+## Install
+
+```bash
+# from npm, once published
+dsh plugin --profile web add dsh-command-context-trim
+
+# from a checkout
+dsh plugin --profile web add file:/path/to/dsh-command-context-trim
+```
+
+The package declares `dsh.bundle.patch`, so `dsh plugin add` also adds it to the profile's `dsh.profile.bundles` and its
+insert row (plugin id `context-trim`) is composed automatically. Then restart the profile's app (`/trim` appears in the
+slash-command menu with its argument hint).
+
+## Usage
+
+```
+/trim                       fit the active model window
+/trim check                 report the plan, change nothing
+/trim 32k                   fit an explicit 32768-token budget
+/trim lc:/models/qwen.gguf  fit that route's declared window
+```
+
+Typical use:
+
+1. Switch the session to the smaller local model.
+2. Run `/trim` (or run it *before* switching, while the large model is still active — the command targets the newest
+   `model/selection` intent, so a pending switch is honored).
+3. Continue the conversation.
+
+Success output:
+
+```
+Trimmed 47 messages (seqs 12-105, ~52310 tokens → 63-token marker) for lc:/models/Qwen3.8-27B-Q4_K_M.gguf (window 90000).
+Request size: ~118204 → ~66310 tokens (target 73612).
+```
+
+Every refusal explains itself and changes nothing — for example when the fixed request overhead (system prompt + tool
+schemas) alone exceeds the budget, or when the protected head/tail cannot be relaxed far enough.
+
+## How it works
+
+One trim is two synchronously adjacent appends:
+
+| # | Event | Why |
+|---|---|---|
+| 1 | `compaction/prune` | The token meter's **shadow-price claim**. The meter's persisted projections are O(1) and cannot re-price a replaced range, so a replacement must be preceded by an event stating the exact price of the range it shadows; without it the fold records a zero delta and reported occupancy drifts. |
+| 2 | `user/message` with `surfaceOp: {op: 'replace', start, end}` | The replacement itself. `sourceEventSeqs` cites every shadowed node, as the surface contract requires. |
+
+`user/message` is **the only surface-eligible event an idle command may append**: `assistant/message` requires an open
+step and a `tool/result` replacement requires an open turn, so a trim performed between turns — which is exactly when a
+user needs one — has no other legal node type.
+
+Design consequences:
+
+- **The human transcript is untouched.** Replacements are model-only; the transcript reads append-origin events. The full
+  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`.
+- **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.
+
+## 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. |
+
+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.
+
+## Configuration
+
+Override on the `context-trim` row of a profile patch (the bundle's own `cordis.patch.yml` lists the full default set):
+
+| Key | Default | Meaning |
+|---|---|---|
+| `targetRatio` | `0.9` | `budget = floor((contextWindow - reserveOutputTokens) * targetRatio)` |
+| `reserveOutputTokens` | `8192` | Output space kept for the model's own reply |
+| `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 |
+| `markerSlackTokens` | `64` | Slack added to the priced marker so the post-trim request stays under budget |
+
+## Limits
+
+- **It drops content; it does not summarize.** A trimmed detail is gone from the model's view (still in the log). When you
+  want a *summary* instead, use `/compact`; the two complement each other (`/trim` first makes a later `/compact` cheaper
+  and more likely to succeed).
+- **It cannot shrink the fixed envelope.** System prompt and tool schemas are outside the surface; if they alone exceed the
+  budget, `/trim` says so instead of pretending.
+- **Nothing is restored.** There is no `/untrim` in v1: re-inserting earlier content as surface nodes would need
+  `assistant`/`tool` events, which are only legal inside an open turn.
+- **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.
+
+## Development
+
+```bash
+npm install            # the harness contracts this plugin builds on, pinned as devDependencies
+npm test               # node --test
+npm run link:harness   # or resolve @deepseek-ai from a local dsh installation instead of npm
+```
+
+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;
+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 |
+| 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 |
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,92 @@
+# dsh-command-context-trim
+
+[English →](README.md)
+
+给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 增加一个**不调用任何模型**的 `/trim` 命令：
+把对话里最旧、最不重要的一段上下文裁掉，让会话能切到**窗口更小的模型**上继续跑。
+
+## 为什么需要它
+
+把长会话从云端大窗口模型切到本地小窗口模型后，下一次请求会超出新模型的窗口。常规做法是切换前先 `/compact`，
+但 compaction 的本质是**摘要**：它必须让摘要请求本身也塞进（已经变小的）窗口，而摘要的输入正是那段要压缩的历史——
+于是它常常因为和原请求同样的原因失败。DSH 内置的溢出自动恢复同理：它也是用 routed 模型去做摘要，本地窗口太小就一样失败。
+
+`/trim` 完全不依赖模型：它先按目标模型重新测算当前请求，选出**最旧的、工具调用/结果配对平衡的**一段，刚好释放到预算
+以内，再用一条极短的占位消息把这段遮蔽掉。两次同步 append，零次 LLM 调用——所以它在“所有请求都失败”的场景下照样能用。
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-command-context-trim          # 发布到 npm 后
+dsh plugin --profile web add file:/path/to/dsh-command-context-trim   # 从源码
+```
+
+包内声明了 `dsh.bundle.patch`，`dsh plugin add` 会自动把它加进 profile 的 `dsh.profile.bundles`，并组合其 insert 行
+（插件 id `context-trim`）。重启对应 profile 后，斜杠菜单里会出现 `/trim`。
+
+## 用法
+
+```
+/trim                       按当前/待切换模型的窗口裁到预算内
+/trim check                 只报告计划，不修改任何东西
+/trim 32k                   指定 32768 token 预算
+/trim lc:/models/qwen.gguf  按指定 route 声明的窗口裁
+```
+
+典型流程：切到本地小模型 → 执行 `/trim`（也可以在切换前执行：命令会读取最新的 `model/selection` 意图）→ 继续对话。
+
+## 实现要点
+
+一次裁剪 = 两次**紧邻**的 append：
+
+1. `compaction/prune` —— token meter 的 **shadow-price 记账**。meter 的持久化投影是 O(1) 的，无法为被替换的范围重新计价，
+   所以替换事件前必须有一条声明被遮蔽范围精确价格的计量事件，否则投影按 0 增量记账，上下文占用显示会漂移。
+2. `user/message` + `surfaceOp:{op:'replace',start,end}` —— 替换本体，`sourceEventSeqs` 覆盖全部被遮蔽节点。
+
+`user/message` 是**空闲态唯二合法的 surface 事件类型**：`assistant/message` 需要 open step，`tool/result` 替换需要 open turn，
+而“回合之间”正是用户需要裁剪的时刻。
+
+由此带来的性质：
+
+- **人类记录不受影响**：替换是 model-only，transcript 只读 append 来源事件；原始内容完整保留在持久化日志里，可审计、可人工恢复。
+- **绝不切断工具调用/结果配对**：切点由 `@deepseek-ai/dsh-compaction` 的 `toolPairingBalancedBefore/After` 决定。
+- **与其它机制互斥**：命令在 `agent.runMaintenance()` 内执行（非 idle 直接失败），不会与回合、`/compact`、自动压缩交错；
+  存在未闭合的 `compaction/start` 时也会拒绝执行。
+
+## 保护集与选段策略
+
+保护：开头 `protectHeadNodes`（默认 1，即任务声明）、末尾最近 `retainRatio` 窗口（下限 `minTailTokens`）、以及最后一条消息永不裁剪。
+在保护集之间采用**最旧优先、够用即止**：从最旧的平衡切点开始，只增长到刚好释放够 token。
+
+## 配置
+
+在 profile patch 的 `context-trim` 行上覆盖（`cordis.patch.yml` 里列出了全部默认值）：
+
+`targetRatio`(0.9)、`reserveOutputTokens`(8192)、`retainRatio`(0.16)/`retainTokens`、`minTailTokens`(2048)、
+`protectHeadNodes`(1)、`allowTailTrim`(true)、`markerSlackTokens`(64)。
+
+预算公式：`budget = floor((contextWindow - reserveOutputTokens) * targetRatio)`。
+
+## 局限
+
+- 它是**丢弃**而不是摘要。需要“浓缩保留”时用 `/compact`；两者互补（先 `/trim` 会让随后的 `/compact` 更省、更易成功）。
+- **无法缩减固定开销**（system prompt + 工具 schema 不在 surface 上）；如果固定开销本身超预算，命令会明确报错而不是假装成功。
+- v1 **没有 `/untrim`**：把旧内容重新变回 surface 需要 append `assistant`/`tool` 事件，而那只在 open turn 内合法。
+- 计价使用 token meter 的启发式估算（与 `/compact`、GUI 上下文条一致），与提供商真实 usage 略有偏差。
+
+## 开发与验证
+
+```bash
+npm install            # 本插件依赖的 harness 契约已固定为 devDependencies
+npm test               # node --test
+npm run link:harness   # 也可改为从本地 dsh 安装的依赖闭包解析 @deepseek-ai
+```
+
+已验证：30 个测试全部通过（选段算法、参数解析、真实 Session 上的 surface 改写与日志重放、插件命令注册与端到端裁剪）；
+隔离 `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 里的真实小窗口端到端验证。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,29 @@
+# dsh-command-context-trim bundle patch.
+#
+# Install into a profile:
+#   dsh plugin --profile <profile> add dsh-command-context-trim
+#
+# The insert activates the plugin; the config block below is the full default
+# set, shown so overrides are a copy/paste away. Remove `config` entirely to use
+# the built-in defaults (`lib/config.js`).
+- insert:
+    - id: context-trim
+      name: dsh-command-context-trim
+      config:
+        # Fraction of the usable window a trim aims for: budget =
+        # floor((contextWindow - reserveOutputTokens) * targetRatio).
+        targetRatio: 0.9
+        # Output tokens kept available for the model's own reply.
+        reserveOutputTokens: 8192
+        # Recent tail kept verbatim, as a fraction of the model's context window.
+        retainRatio: 0.16
+        # Absolute floor for that retained tail.
+        minTailTokens: 2048
+        # Leading surface nodes never trimmed (the task statement).
+        protectHeadNodes: 1
+        # Allow the elided span to reach into the retained tail when the oldest
+        # span alone cannot free enough tokens.
+        allowTailTrim: true
+        # 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

package/lib/apply.js

@@ -0,0 +1,97 @@
+/**
+ * Surface mutation for one trim.
+ *
+ * Two synchronously adjacent appends do the whole job:
+ *
+ * 1. `compaction/prune` — the token meter's shadow-price claim. The meter's
+ *    persisted projections are O(1) (they cannot re-price a replaced range), so
+ *    a replacement must be preceded by an event stating the exact price of the
+ *    range it shadows. Without it the fold records a zero delta and the reported
+ *    context occupancy drifts from reality.
+ * 2. `user/message` with a positional replace — the replacement itself. It is
+ *    model-only: the human transcript reads append-origin events, so nothing the
+ *    user already saw is rewritten, and the full original content stays in the
+ *    durable session log.
+ *
+ * A `user/message` is the only surface-eligible event an idle command may
+ * append: `assistant/message` requires an open step and a `tool/result`
+ * replacement requires an open turn, so a trim performed between turns — which
+ * is exactly when a user needs one — has no other legal node type.
+ *
+ * @module dsh-command-context-trim/apply
+ */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+
+/** Plugin name written into every replacement message's source marker. */
+export const TRIM_PLUGIN = 'dsh-command-context-trim';
+
+/** Provenance frozen into every replacement message. */
+const TRIM_SOURCE = Object.freeze({ kind: 'plugin', plugin: TRIM_PLUGIN });
+
+/** Framing used to price a marker before the plan's exact numbers are known. */
+const PROVISIONAL_MARKER =
+	'[context-trim] an earlier span of this conversation was removed from this request to fit the model context window. ' +
+	'The task statement and the most recent messages are unchanged: continue the current task directly.';
+
+/**
+ * Build the provisional marker, whose price seeds planning.
+ * @returns a frozen user message used only for measurement.
+ */
+export function provisionalMarker() {
+	return createUserMessage({
+		content: [{ type: 'text', text: PROVISIONAL_MARKER }],
+		source: TRIM_SOURCE
+	});
+}
+
+/**
+ * Build the replacement message describing one committed trim.
+ * @param plan - the committed span plan.
+ * @param label - human label of the target route.
+ * @param budget - target request size in tokens.
+ * @returns the frozen replacement user message.
+ */
+export function createMarkerMessage(plan, label, budget) {
+	return createUserMessage({
+		content: [
+			{
+				type: 'text',
+				text:
+					`[context-trim] ${plan.shadowedSeqs.length} earlier messages (~${plan.shadowedTokens} tokens) were removed ` +
+					`from this request to fit the ${label} context window (target ${budget} tokens). ` +
+					'The task statement and the most recent messages are unchanged: continue the current task directly, ' +
+					'and ask the user or re-read a file when a removed detail is needed.'
+			}
+		],
+		source: TRIM_SOURCE
+	});
+}
+
+/**
+ * Whether one message source identifies a context-trim replacement.
+ * @param source - message source restored from a surface node.
+ * @returns true when the source carries this plugin's marker.
+ */
+export function isTrimMarkerSource(source) {
+	return source?.kind === 'plugin' && source.plugin === TRIM_PLUGIN;
+}
+
+/**
+ * Apply one committed plan to a session surface.
+ * @param session - session whose surface is rewritten.
+ * @param plan - committed span plan naming the shadowed range.
+ * @param marker - replacement message built for that plan.
+ * @returns the appended replacement event.
+ * @throws when the session rejects the append (surface contract violation).
+ */
+export function applyTrim(session, plan, marker) {
+	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 },
+		sourceEventSeqs: [...plan.shadowedSeqs]
+	});
+}

package/lib/args.js

@@ -0,0 +1,53 @@
+/**
+ * `/trim` argument parsing: `[check] [<tokens>|k|m] [<provider>:<model>]`.
+ *
+ * Deliberately tiny and total: every rejection carries a human sentence, and
+ * no argument form reaches the session mutator without being understood.
+ *
+ * @module dsh-command-context-trim/args
+ */
+
+/** Multipliers accepted after a numeric budget. */
+const UNITS = Object.freeze({ k: 1_000, K: 1_000, m: 1_000_000, M: 1_000_000 });
+
+/** Help text returned with every argument failure. */
+export const USAGE = [
+	'Usage: /trim [check] [<tokens>|k] [<provider>:<model>]',
+	'  /trim                       fit the active model window',
+	'  /trim check                 report the plan, change nothing',
+	'  /trim 32k                   fit an explicit 32768-token budget',
+	'  /trim lc:/models/qwen.gguf  fit that route\'s declared window'
+].join('\n');
+
+/**
+ * Parse one `/trim` invocation.
+ * @param rawInput - text after the command name, verbatim.
+ * @returns `{ check, budget?, route? }`, or `{ error }` for an unrecognized form.
+ */
+export function parseTrimArguments(rawInput) {
+	const result = { check: false };
+	const fields = rawInput.trim().split(/\s+/u).filter((field) => field.length > 0);
+	for (const field of fields) {
+		if (field === 'check' || field === '--check' || field === '--dry-run') {
+			if (result.check) return { error: 'duplicate "check"' };
+			result.check = true;
+			continue;
+		}
+		const numeric = /^(\d+(?:\.\d+)?)([kKmM])?$/u.exec(field);
+		if (numeric !== null) {
+			if (result.budget !== undefined) return { error: `duplicate token budget "${field}"` };
+			const value = Math.floor(Number(numeric[1]) * (UNITS[numeric[2]] ?? 1));
+			if (!Number.isSafeInteger(value) || value <= 0) return { error: `invalid token budget "${field}"` };
+			result.budget = value;
+			continue;
+		}
+		const route = /^([A-Za-z0-9._-]+):(.+)$/u.exec(field);
+		if (route !== null) {
+			if (result.route !== undefined) return { error: `duplicate target route "${field}"` };
+			result.route = { provider: route[1], model: route[2] };
+			continue;
+		}
+		return { error: `unrecognized argument "${field}"` };
+	}
+	return result;
+}

package/lib/config.js

@@ -0,0 +1,127 @@
+/**
+ * Configuration resolution for the model-free `/trim` command.
+ *
+ * Every field is validated and detached at plugin load, so a bad profile patch
+ * fails loudly once at boot instead of silently distorting a trim later.
+ *
+ * @module dsh-command-context-trim/config
+ */
+
+/** Built-in defaults, mirrored by the bundle patch's commented config block. */
+export const DEFAULTS = Object.freeze({
+	targetRatio: 0.9,
+	reserveOutputTokens: 8192,
+	retainRatio: 0.16,
+	minTailTokens: 2048,
+	protectHeadNodes: 1,
+	allowTailTrim: true,
+	markerSlackTokens: 64
+});
+
+/** Every key this plugin accepts. */
+const CONFIG_KEYS = new Set([
+	'targetRatio',
+	'reserveOutputTokens',
+	'retainRatio',
+	'retainTokens',
+	'minTailTokens',
+	'protectHeadNodes',
+	'allowTailTrim',
+	'markerSlackTokens'
+]);
+
+/**
+ * Validate one untrusted configuration object and fill in defaults.
+ * @param config - raw plugin configuration from the loader.
+ * @returns a detached frozen configuration.
+ * @throws when a key is unknown or a value is out of range.
+ */
+export function resolveConfig(config = {}) {
+	for (const key of Object.keys(config)) {
+		if (!CONFIG_KEYS.has(key)) {
+			throw new Error(`ContextTrimConfig: unknown key "${key}" (allowed: ${[...CONFIG_KEYS].join(', ')})`);
+		}
+	}
+	const targetRatio = config.targetRatio ?? DEFAULTS.targetRatio;
+	const reserveOutputTokens = config.reserveOutputTokens ?? DEFAULTS.reserveOutputTokens;
+	const minTailTokens = config.minTailTokens ?? DEFAULTS.minTailTokens;
+	const protectHeadNodes = config.protectHeadNodes ?? DEFAULTS.protectHeadNodes;
+	const allowTailTrim = config.allowTailTrim ?? DEFAULTS.allowTailTrim;
+	const markerSlackTokens = config.markerSlackTokens ?? DEFAULTS.markerSlackTokens;
+	assertRatio('targetRatio', targetRatio);
+	assertNonNegativeInteger('reserveOutputTokens', reserveOutputTokens);
+	assertNonNegativeInteger('minTailTokens', minTailTokens);
+	assertNonNegativeInteger('protectHeadNodes', protectHeadNodes);
+	assertNonNegativeInteger('markerSlackTokens', markerSlackTokens);
+	if (typeof allowTailTrim !== 'boolean') throw new Error('ContextTrimConfig: allowTailTrim must be a boolean');
+	const retention = resolveRetention(config);
+	if (retention.retainRatio !== undefined && retention.retainRatio >= targetRatio) {
+		throw new Error(`ContextTrimConfig: retainRatio (${retention.retainRatio}) must be less than targetRatio (${targetRatio})`);
+	}
+	return Object.freeze({
+		targetRatio,
+		reserveOutputTokens,
+		...retention,
+		minTailTokens,
+		protectHeadNodes,
+		allowTailTrim,
+		markerSlackTokens
+	});
+}
+
+/** Choose one explicit retention form, rejecting the ambiguous pair. */
+function resolveRetention(config) {
+	const retainRatio = config.retainRatio;
+	const retainTokens = config.retainTokens;
+	if (retainRatio !== undefined && retainTokens !== undefined) {
+		throw new Error('ContextTrimConfig: retainRatio and retainTokens are mutually exclusive');
+	}
+	if (retainTokens !== undefined) {
+		assertNonNegativeInteger('retainTokens', retainTokens);
+		return { retainTokens };
+	}
+	const resolved = retainRatio ?? DEFAULTS.retainRatio;
+	assertRatio('retainRatio', resolved);
+	return { retainRatio: resolved };
+}
+
+/**
+ * Request-token budget a trim aims for on one model capacity.
+ * @param contextWindow - positive adapter-owned capacity of the target model.
+ * @param config - resolved configuration.
+ * @returns the target total request size in tokens.
+ * @throws when the reserved output budget leaves no usable window.
+ */
+export function budgetFor(contextWindow, config) {
+	if (!Number.isInteger(contextWindow) || contextWindow <= 0) {
+		throw new Error(`context trim: contextWindow (${String(contextWindow)}) must be a positive integer`);
+	}
+	const usable = contextWindow - config.reserveOutputTokens;
+	if (usable <= 0) {
+		throw new Error(`context trim: reserveOutputTokens (${config.reserveOutputTokens}) leaves no room inside the ${contextWindow}-token window`);
+	}
+	return Math.max(1, Math.floor(usable * config.targetRatio));
+}
+
+/**
+ * Verbatim recent-tail budget resolved for one model capacity.
+ * @param contextWindow - positive adapter-owned capacity of the target model.
+ * @param config - resolved configuration.
+ * @returns tokens kept verbatim at the end of the conversation.
+ */
+export function retentionFor(contextWindow, config) {
+	const configured = config.retainTokens ?? Math.floor(contextWindow * config.retainRatio);
+	return Math.max(config.minTailTokens, configured);
+}
+
+function assertRatio(name, value) {
+	if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > 1) {
+		throw new Error(`ContextTrimConfig: ${name} (${String(value)}) must be a number in (0, 1]`);
+	}
+}
+
+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/index.js

@@ -0,0 +1,232 @@
+/**
+ * `/trim` — model-free context trimming for DeepSeek Harness.
+ *
+ * A session built against a large-window cloud model can exceed a smaller local
+ * model's window the moment the model is switched. `/compact` cannot rescue that
+ * situation reliably, because compaction *summarizes*: its summarizer call must
+ * itself fit the (now smaller) window while holding the very region being
+ * condensed, so it fails for the same reason the original request failed.
+ *
+ * `/trim` needs no model at all. It measures the current request under the
+ * target route, picks the oldest tool-pairing-balanced span that frees exactly
+ * enough tokens, and shadows that span with one short marker message — two
+ * synchronous appends, zero LLM calls, so it works precisely when every request
+ * is failing.
+ *
+ * @module dsh-command-context-trim
+ */
+import { toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compaction';
+import z from '@deepseek-ai/schemastery';
+import { parseTrimArguments, USAGE } from './args.js';
+import { applyTrim, createMarkerMessage, provisionalMarker } from './apply.js';
+import { budgetFor, resolveConfig, retentionFor } from './config.js';
+import { planTrim } from './plan.js';
+import { resolveTarget, targetHeader } from './target.js';
+
+/** Cordis plugin name. */
+export const name = 'context-trim';
+
+/** Services required before the command can be registered. */
+export const inject = ['commands', 'tokenMeter', 'llm'];
+
+/** Loader-facing configuration shape; ranges are enforced by {@link resolveConfig}. */
+export const Config = z.object({
+	targetRatio: z.number(),
+	reserveOutputTokens: z.number(),
+	retainRatio: z.number(),
+	retainTokens: z.number(),
+	minTailTokens: z.number(),
+	protectHeadNodes: z.number(),
+	allowTailTrim: z.boolean(),
+	markerSlackTokens: z.number()
+});
+
+/**
+ * Register `/trim` for every composed human-command adapter.
+ * @param ctx - context carrying the command registry, token meter, and LLM service.
+ * @param config - untrusted plugin configuration.
+ */
+export function apply(ctx, config) {
+	const resolved = resolveConfig(config ?? {});
+	const active = new Set();
+	const handler = (invocation) => {
+		const operation = execute(ctx, resolved, invocation);
+		active.add(operation);
+		const retire = () => {
+			active.delete(operation);
+		};
+		operation.then(retire, retire);
+		return operation;
+	};
+	ctx.effect(function* () {
+		yield async () => {
+			await Promise.allSettled(active);
+		};
+		yield ctx.commands.register({
+			name: 'trim',
+			description: 'Drop the least valuable span of context to fit the active model window (no model call)',
+			input: { hint: '[check] [tokens|k] [provider:model]' },
+			handler
+		});
+	}, 'context-trim lifecycle');
+}
+
+/**
+ * Execute one `/trim` invocation inside an idle-agent reservation.
+ * @param ctx - plugin context.
+ * @param config - resolved configuration.
+ * @param invocation - command invocation from the UI adapter.
+ * @returns a command result.
+ */
+async function execute(ctx, config, invocation) {
+	const parsed = parseTrimArguments(invocation.rawInput);
+	if (parsed.error !== undefined) return { kind: 'error', text: `${parsed.error}\n${USAGE}` };
+	let running;
+	try {
+		running = invocation.agent.runMaintenance((agentSignal) => trimOnce(ctx, config, invocation, parsed, agentSignal));
+	} catch (error) {
+		return { kind: 'error', text: `Trim needs an idle agent: ${describeError(error)}` };
+	}
+	try {
+		return await running;
+	} catch (error) {
+		if (invocation.signal.aborted) return { kind: 'error', text: 'Trim cancelled.' };
+		return { kind: 'error', text: `Trim failed: ${describeError(error)}` };
+	}
+}
+
+/**
+ * Plan and apply one trim; the whole session-visible mutation happens here.
+ * @param ctx - plugin context.
+ * @param config - resolved configuration.
+ * @param invocation - command invocation (agent, signal).
+ * @param parsed - parsed command arguments.
+ * @param agentSignal - cancellation owned by the maintenance reservation.
+ * @returns a command result.
+ */
+async function trimOnce(ctx, config, invocation, parsed, agentSignal) {
+	const signal = AbortSignal.any([invocation.signal, agentSignal]);
+	signal.throwIfAborted();
+	const session = invocation.agent.session;
+	assertNoOpenCompaction(session);
+	const target = parsed.budget === undefined ? await resolveTarget(ctx, invocation.agent, parsed.route, signal) : undefined;
+	const budget = parsed.budget ?? budgetFor(target.contextWindow, config);
+	const label = target === undefined ? `an explicit ${budget}-token budget` : `${target.label} (window ${target.contextWindow})`;
+	const header = target === undefined ? undefined : targetHeader(session, target);
+	const measurement = ctx.tokenMeter.measure(session, header);
+	const nodes = measurement.nodes.map((node) => ({ seq: node.seq, heuristicTokens: node.heuristicTokens }));
+	if (nodes.length === 0) {
+		return { kind: 'success', text: `Nothing to trim: ${session.id} has no model-visible messages yet.` };
+	}
+	// 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);
+	const envelopeTokens = Math.max(0, measurement.totalTokens - measurement.surfaceTokens);
+	const planFor = (markerTokens) =>
+		planTrim({
+			nodes,
+			envelopeTokens,
+			budget,
+			markerCost: markerTokens + config.markerSlackTokens,
+			retainTokens,
+			minTailTokens: config.minTailTokens,
+			protectHeadNodes: config.protectHeadNodes,
+			allowTailTrim: config.allowTailTrim,
+			isBalancedBefore: (seq) => toolPairingBalancedBefore(session, seq),
+			isBalancedAfter: (seq) => toolPairingBalancedAfter(session, seq)
+		});
+	let markerTokens = ctx.tokenMeter.estimateMessage(provisionalMarker());
+	let plan = planFor(markerTokens);
+	if (plan.kind !== 'span') return describeNonSpan(plan, label);
+	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 describeNonSpan(plan, label);
+		marker = createMarkerMessage(plan, target?.label ?? `budget ${budget}`, budget);
+		markerTokens = finalMarkerTokens;
+	}
+	if (parsed.check) return { kind: 'success', text: preview(plan, label, markerTokens) };
+	const replacement = applyTrim(session, plan, marker);
+	const after = ctx.tokenMeter.measure(session, header);
+	return { kind: 'success', text: report(plan, after, label, markerTokens), sourceEventSeq: replacement.seq };
+}
+
+/** Refuse to rewrite a surface while a compaction bracket is open. */
+function assertNoOpenCompaction(session) {
+	for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
+		const event = session.eventAt(seq);
+		if (event === undefined) continue;
+		if (event.type === 'compaction/end') return;
+		// A seed boundary proves any earlier unmatched start belongs to a previous lifecycle.
+		if (event.type === 'session/end-seed') return;
+		if (event.type === 'compaction/start') {
+			throw new Error('a compaction is already in progress in this session; wait for it to finish, then retry');
+		}
+	}
+}
+
+/** Render every non-span outcome as a final command result. */
+function describeNonSpan(plan, label) {
+	switch (plan.kind) {
+		case 'fits':
+			return {
+				kind: 'success',
+				text: `Already within budget: ~${plan.totalTokens} / ${plan.budget} tokens for ${label}. Nothing to trim.`
+			};
+		case 'envelope':
+			return {
+				kind: 'error',
+				text: [
+					`Fixed request overhead alone (~${plan.envelopeTokens} tokens of system prompt and tool schemas) exceeds the ${plan.budget}-token budget for ${label}.`,
+					'Trimming conversation history cannot help: raise the backend context size (the model\'s contextWindow in settings.yaml, or the server\'s context flag) or reduce mounted tools and skills, then retry.'
+				].join('\n')
+			};
+		case 'no-span':
+			return {
+				kind: 'error',
+				text: `Nothing safely trimmable for ${label}: ${plan.reason}, or no tool-pairing balanced cut exists.`
+			};
+		case 'insufficient':
+			return {
+				kind: 'error',
+				text: [
+					`Cannot free enough for ${label}: the largest balanced span frees ~${plan.maxFreeable} of the ~${plan.need} tokens needed.`,
+					`Protected content: task statement ~${plan.protectedHeadTokens} tokens, recent tail ~${plan.protectedTailTokens} tokens (retain target ~${plan.retainTokens}).`,
+					'Try /compact (it summarizes instead of dropping), a larger window, or /trim with an explicit budget after another reduction.'
+				].join('\n')
+			};
+		default:
+			return { kind: 'error', text: `Trim could not plan a reduction (${String(plan.kind)}).` };
+	}
+}
+
+/** Render a dry run. */
+function preview(plan, label, markerTokens) {
+	return [
+		`Would trim ${plan.shadowedSeqs.length} messages (seqs ${plan.startSeq}-${plan.endSeq}, ~${plan.shadowedTokens} tokens → ${markerTokens}-token marker) for ${label}.`,
+		`Request size: ~${plan.totalTokens} → ~${plan.projectedTotal} tokens (target ${plan.budget}). Nothing was changed.`
+	].join('\n');
+}
+
+/** Render a committed trim against the re-measured request. */
+function report(plan, after, label, markerTokens) {
+	const lines = [
+		`Trimmed ${plan.shadowedSeqs.length} messages (seqs ${plan.startSeq}-${plan.endSeq}, ~${plan.shadowedTokens} tokens → ${markerTokens}-token marker) for ${label}.`,
+		`Request size: ~${plan.totalTokens} → ~${after.totalTokens} tokens (target ${plan.budget}).`
+	];
+	if (plan.relaxedRetention) {
+		lines.push(`Retention relaxed to ~${plan.retainTokens} tokens to reach the budget.`);
+	}
+	return lines.join('\n');
+}
+
+/** Render a thrown value without trusting its string coercion. */
+function describeError(error) {
+	try {
+		return error instanceof Error ? error.message : String(error);
+	} catch {
+		return '<unrenderable thrown value>';
+	}
+}

package/lib/plan.js

@@ -0,0 +1,170 @@
+/**
+ * Pure trim planning.
+ *
+ * The policy is *oldest-first, least-long-possible*: the elided span starts at
+ * the oldest cut that keeps every tool-call/result pair intact, and grows only
+ * until it frees exactly enough tokens. The task statement (leading nodes) and
+ * the most recent messages are protected, because for a coding agent recency
+ * and the original request are the two pieces of high-value context; everything
+ * between them is what a smaller window can afford to lose.
+ *
+ * Nothing here touches a session: the planner receives measured node prices and
+ * two balance predicates, so every branch is directly testable.
+ *
+ * @module dsh-command-context-trim/plan
+ */
+
+/**
+ * @typedef {object} TrimNode
+ * @property {number} seq - surface event sequence of the node.
+ * @property {number} heuristicTokens - the token meter's heuristic price for it.
+ */
+
+/**
+ * @typedef {object} TrimPlanInput
+ * @property {readonly TrimNode[]} nodes - current surface nodes in model-visible order.
+ * @property {number} envelopeTokens - non-surface request price (system prompt + tool schemas).
+ * @property {number} budget - target total request size in tokens.
+ * @property {number} markerCost - priced replacement marker, including configured slack.
+ * @property {number} retainTokens - preferred verbatim recent-tail budget.
+ * @property {number} minTailTokens - absolute floor for that retained tail.
+ * @property {number} protectHeadNodes - leading nodes that must never be elided.
+ * @property {boolean} allowTailTrim - whether the elided span may reach into the retained tail.
+ * @property {(seq: number) => boolean} isBalancedBefore - tool-pairing balance before a node.
+ * @property {(seq: number) => boolean} isBalancedAfter - tool-pairing balance after a node.
+ */
+
+/**
+ * Plan one model-free trim.
+ * @param input - measured surface, budgets, and balance predicates.
+ * @returns a plan: `fits`, `envelope`, `no-span`, `insufficient`, or `span`.
+ */
+export function planTrim(input) {
+	const surfaceTokens = input.nodes.reduce((total, node) => total + node.heuristicTokens, 0);
+	const common = {
+		totalTokens: input.envelopeTokens + surfaceTokens,
+		surfaceTokens,
+		envelopeTokens: input.envelopeTokens,
+		budget: input.budget
+	};
+	if (common.totalTokens <= input.budget) return { kind: 'fits', ...common };
+	if (input.envelopeTokens >= input.budget) return { kind: 'envelope', ...common };
+	if (input.nodes.length < 2) {
+		return { kind: 'no-span', ...common, reason: 'the conversation surface holds fewer than two messages' };
+	}
+	const need = common.totalTokens - input.budget;
+	const configuredRetention = input.retainTokens;
+	let weakest = null;
+	for (const retainTokens of retentionLadder(configuredRetention, input.minTailTokens)) {
+		const attempt = attemptSpan({ ...input, retainTokens, need });
+		if (attempt.kind === 'span') {
+			return {
+				kind: 'span',
+				...common,
+				...attempt,
+				need,
+				retainTokens,
+				relaxedRetention: retainTokens < configuredRetention,
+				projectedTotal: common.totalTokens - attempt.freedTokens
+			};
+		}
+		if (weakest === null || attempt.maxFreeable > weakest.maxFreeable) weakest = { ...attempt, retainTokens };
+	}
+	return {
+		kind: 'insufficient',
+		...common,
+		need,
+		maxFreeable: weakest?.maxFreeable ?? 0,
+		protectedHeadTokens: headTokens(input.nodes, input.protectHeadNodes),
+		protectedTailTokens: weakest?.protectedTailTokens ?? 0,
+		retainTokens: configuredRetention
+	};
+}
+
+/**
+ * Try one retention budget, returning the smallest oldest-anchored balanced span
+ * that frees at least `need` tokens.
+ * @param input - planning input plus the retention budget under test.
+ * @returns a `span` plan, or the `shortfall` diagnostics for this retention.
+ */
+function attemptSpan(input) {
+	const nodes = input.nodes;
+	const tailStart = tailStartIndex(nodes, input.retainTokens);
+	const lastElidable = input.allowTailTrim ? nodes.length - 2 : Math.min(nodes.length - 2, tailStart - 1);
+	const shortfall = (maxFreeable) => ({
+		kind: 'shortfall',
+		maxFreeable,
+		protectedTailTokens: tailTokens(nodes, tailStart),
+		protectedHeadTokens: headTokens(nodes, input.protectHeadNodes)
+	});
+	const from = Math.min(input.protectHeadNodes, nodes.length - 1);
+	if (lastElidable < from) return shortfall(0);
+	let start = -1;
+	for (let index = from; index <= lastElidable; index += 1) {
+		if (input.isBalancedBefore(nodes[index].seq)) {
+			start = index;
+			break;
+		}
+	}
+	if (start === -1) return shortfall(0);
+	let accumulated = 0;
+	let best = null;
+	for (let index = start; index <= lastElidable; index += 1) {
+		accumulated += nodes[index].heuristicTokens;
+		if (!input.isBalancedAfter(nodes[index].seq)) continue;
+		const freedTokens = accumulated - input.markerCost;
+		if (best === null || freedTokens > best.freedTokens) {
+			best = {
+				startIndex: start,
+				endIndex: index,
+				startSeq: nodes[start].seq,
+				endSeq: nodes[index].seq,
+				shadowedSeqs: nodes.slice(start, index + 1).map((node) => node.seq),
+				shadowedTokens: accumulated,
+				freedTokens
+			};
+		}
+		if (freedTokens >= input.need) break;
+	}
+	return best === null ? shortfall(0) : best.freedTokens >= input.need
+		? { kind: 'span', ...best }
+		: shortfall(best.freedTokens);
+}
+
+/**
+ * Descending retention budgets to try: the configured one first, then half of
+ * it, then the configured floor. A trim exists to keep the session usable, so a
+ * configured tail that makes the fit impossible is relaxed rather than obeyed —
+ * and the result reports that it happened.
+ * @param configured - preferred verbatim recent-tail budget.
+ * @param floor - absolute minimum retained tail.
+ * @returns distinct retention budgets, strongest first.
+ */
+function retentionLadder(configured, floor) {
+	const candidates = [configured, Math.max(floor, Math.floor(configured / 2)), floor];
+	return [...new Set(candidates.filter((value) => value >= 0 && value <= configured))];
+}
+
+/** Index of the first node retained verbatim for one tail budget. */
+function tailStartIndex(nodes, retainTokens) {
+	let accumulated = 0;
+	for (let index = nodes.length - 1; index >= 0; index -= 1) {
+		accumulated += nodes[index].heuristicTokens;
+		if (accumulated >= retainTokens) return index;
+	}
+	return 0;
+}
+
+/** Tokens held by the nodes from `tailStart` to the end. */
+function tailTokens(nodes, tailStart) {
+	let total = 0;
+	for (let index = tailStart; index < nodes.length; index += 1) total += nodes[index].heuristicTokens;
+	return total;
+}
+
+/** Tokens held by the protected leading nodes. */
+function headTokens(nodes, protectHeadNodes) {
+	let total = 0;
+	for (let index = 0; index < Math.min(protectHeadNodes, nodes.length); index += 1) total += nodes[index].heuristicTokens;
+	return total;
+}

package/lib/target.js

@@ -0,0 +1,100 @@
+/**
+ * Resolve which model a trim is fitting, and price the request envelope under
+ * that model's route.
+ *
+ * @module dsh-command-context-trim/target
+ */
+import { canonicalHeader } from '@deepseek-ai/dsh-session';
+
+/**
+ * Latest durable model intent for a session: the newest `model/selection` (a
+ * pending switch) or the newest `request/header` (the route actually used),
+ * whichever the log records last. Scanning backwards and taking the first hit
+ * is exactly the rule the harness's own model-selection projection applies:
+ * a selection later consumed by a matching request is superseded by that
+ * request's header, and a newer selection supersedes both.
+ * @param session - session whose log is read.
+ * @returns `{ provider, model, source }`, or undefined when nothing was routed yet.
+ */
+export function latestRoute(session) {
+	for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
+		const event = session.eventAt(seq);
+		if (event === undefined) continue;
+		if (event.type === 'model/selection') {
+			return { provider: event.data.provider, model: event.data.model, source: 'selection' };
+		}
+		if (event.type === 'request/header') {
+			const config = event.data.header.config;
+			return { provider: config.provider, model: config.model, source: 'request' };
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Resolve the target route and its declared context capacity.
+ * @param ctx - context carrying the LLM service.
+ * @param agent - agent whose session supplies the durable model intent.
+ * @param requested - explicit `{ provider, model }` from the command line, if any.
+ * @param signal - cancellation signal for model resolution.
+ * @returns `{ provider, model, contextWindow, label }`.
+ * @throws when no route can be determined, the route is unknown, or its adapter declares no window.
+ */
+export async function resolveTarget(ctx, agent, requested, signal) {
+	const route = requested ?? latestRoute(agent.session) ?? agentRoute(agent);
+	if (route === undefined) {
+		throw new Error('cannot determine the target model: select a model in this session first, or pass an explicit budget (e.g. /trim 32k)');
+	}
+	let info;
+	try {
+		info = await ctx.llm.resolveModelInfo(route.provider, route.model, signal);
+	} catch (error) {
+		throw new Error(
+			`unknown model route ${route.provider}:${route.model} (${describeError(error)}); ` +
+				'pass an explicit budget instead (e.g. /trim 32k)'
+		);
+	}
+	const contextWindow = info?.context?.contextWindow;
+	if (!Number.isInteger(contextWindow) || contextWindow <= 0) {
+		throw new Error(
+			`the adapter for ${route.provider}:${route.model} declares no usable contextWindow ` +
+				'(set it on that model entry in settings.yaml, or pass an explicit budget such as /trim 32k)'
+		);
+	}
+	return { provider: route.provider, model: route.model, contextWindow, label: `${route.provider}:${route.model}` };
+}
+
+/**
+ * Re-price the session's current request envelope under another route by
+ * overriding the logged header's model config. The token meter reuses provider
+ * usage only when the header matches its anchor exactly, so overriding the
+ * config forces a fresh heuristic estimate sized for the target model's route.
+ * @param session - session whose envelope is repriced.
+ * @param target - resolved target route.
+ * @returns a canonical header for the target route, or undefined before any request.
+ */
+export function targetHeader(session, target) {
+	const current = session.requestHeader();
+	if (current === undefined) return undefined;
+	return canonicalHeader({
+		...current,
+		config: { ...current.config, provider: target.provider, model: target.model }
+	});
+}
+
+/** Per-agent configured route, used only before any request was routed. */
+function agentRoute(agent) {
+	const provider = agent.options?.provider;
+	const model = agent.options?.model;
+	if (typeof provider !== 'string' || provider.length === 0 || typeof model !== 'string' || model.length === 0) return undefined;
+	return { provider, model, source: 'agent-options' };
+}
+
+/** Render a thrown value without trusting its string coercion. */
+function describeError(error) {
+	try {
+		return error instanceof Error ? error.message : String(error);
+	} catch {
+		return '<unrenderable thrown value>';
+	}
+}

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "dsh-command-context-trim",
+  "version": "0.1.0",
+  "description": "Model-free /trim command for DeepSeek Harness — drop the oldest, least valuable span of conversation context so a session can continue on a smaller-window model, without any model call.",
+  "license": "MIT",
+  "author": "snailium",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^22.19 || >=24"
+  },
+  "scripts": {
+    "test": "node --test",
+    "link:harness": "bash scripts/dev-link-harness.sh",
+    "prepublishOnly": "npm test"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-commands": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-compaction": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-token-meter": "^0.1.2-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-commands": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-compaction": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-invariants": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-token-meter": {
+      "optional": true
+    },
+    "@deepseek-ai/schemastery": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-compaction": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-session": "0.1.2-rc.1",
+    "@deepseek-ai/schemastery": "3.18.2"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "context",
+    "context-window",
+    "trim",
+    "compaction",
+    "local-model"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/snailium/dsh-command-context-trim.git"
+  },
+  "homepage": "https://github.com/snailium/dsh-command-context-trim#readme",
+  "bugs": {
+    "url": "https://github.com/snailium/dsh-command-context-trim/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}