dsh-context-compression-improved 0.1.1 → 0.2.1

package/package.json

@@ -1,41 +1,37 @@
 {
   "name": "dsh-context-compression-improved",
-  "version": "0.1.1",
-  "description": "One-install context-compression selector bundle for DeepSeek Harness",
+  "version": "0.2.1",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "tag": "dsh-0.1.2"
+  },
   "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
+  "main": "packages/selector/lib/index.js",
+  "types": "packages/selector/lib/index.d.ts",
   "exports": {
     ".": {
-      "types": "./lib/index.d.ts",
-      "default": "./lib/index.js"
+      "types": "./packages/selector/lib/index.d.ts",
+      "default": "./packages/selector/lib/index.js"
     },
     "./invariant": {
-      "types": "./lib/invariant.d.ts",
-      "default": "./lib/invariant.js"
+      "types": "./packages/selector/lib/invariant.d.ts",
+      "default": "./packages/selector/lib/invariant.js"
     },
     "./pruner": {
-      "types": "./lib/pruner.d.ts",
-      "default": "./lib/pruner.js"
+      "types": "./packages/selector/lib/pruner.d.ts",
+      "default": "./packages/selector/lib/pruner.js"
     },
     "./client": {
-      "types": "./lib/client.d.ts",
-      "default": "./lib/client.js"
+      "types": "./packages/selector/lib/client.d.ts",
+      "default": "./packages/selector/lib/client.js"
     },
     "./package.json": "./package.json"
   },
-  "files": [
-    "lib/**/*.js",
-    "lib/**/*.d.ts",
-    "cordis.patch.yml",
-    "dsh.plugin.json",
-    "screenshots.json",
-    "assets",
-    "README.md",
-    "README.zh.md",
-    "LICENSE",
-    "THIRD_PARTY_NOTICES.md"
-  ],
+  "dependencies": {
+    "@huggingface/tokenizers": "0.1.3",
+    "js-yaml": "^4.3.2"
+  },
   "dsh": {
     "client": {
       "inject": [
@@ -47,69 +43,76 @@
       "platform": "web"
     },
     "bundle": {
-      "patch": "./cordis.patch.yml"
+      "patch": "./packages/selector/cordis.patch.yml"
     }
   },
-  "scripts": {
-    "bundle": "tsdown --config tsdown.config.ts && tsdown --config tsdown.client.config.ts",
-    "prepack": "pnpm run bundle",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "vitest run --root ../.. --config vitest.config.ts --project runtime --project selector-host --project selector-client",
-    "pack:dry-run": "npm pack --dry-run"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/drscrewdriver/dsh-context-compression-improved.git",
-    "directory": "packages/selector"
-  },
-  "homepage": "https://github.com/drscrewdriver/dsh-context-compression-improved#readme",
-  "bugs": {
-    "url": "https://github.com/drscrewdriver/dsh-context-compression-improved/issues"
-  },
-  "author": "WilliamShi666",
+  "license": "MIT",
+  "packageManager": "pnpm@11.7.0",
   "engines": {
     "node": "^22.19.0 || >=24.0.0",
-    "dsh": ">=0.1.1-rc.2 <0.2.0-0"
-  },
-  "keywords": [
-    "deepseek",
-    "harness",
-    "context",
-    "compression",
-    "plugin"
-  ],
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public",
-    "tag": "latest"
+    "dsh": ">=0.1.2-rc.1 <0.2.0-0"
   },
-  "dependencies": {
-    "@huggingface/tokenizers": "0.1.3",
-    "js-yaml": "^4.3.2"
+  "scripts": {
+    "build": "pnpm -r --if-present run bundle",
+    "build:scripts": "tsc -p tsconfig.scripts.json",
+    "typecheck": "pnpm --filter dsh-context-compression-improved run bundle && pnpm --filter dsh-context-compression-improved run typecheck && pnpm run typecheck:tests",
+    "typecheck:tests": "tsc --noEmit -p tsconfig.tests.json",
+    "lint": "eslint packages scripts eslint.config.js",
+    "lint:fix": "eslint packages scripts eslint.config.js --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:built": "vitest run --config vitest.built.config.ts",
+    "test:e2e:packed": "node scripts-dist/packed-install-e2e.js",
+    "test:unit": "vitest run",
+    "verify:release": "node scripts-dist/verify-release.js",
+    "pack:dry-run": "pnpm -r --if-present run pack:dry-run"
   },
-  "peerDependencies": {
-    "@deepseek-ai/cordis": ">=4.0.1 <5",
-    "@deepseek-ai/cordis-plugin-include": ">=1.0.6 <2",
-    "@deepseek-ai/cordis-plugin-loader": ">=1.0.2 <2",
-    "@deepseek-ai/dsh-agent": ">=0.1.1-rc.2 <0.2.0",
-    "@deepseek-ai/dsh-agent-presets": ">=0.1.1-rc.2 <0.2.0",
-    "@deepseek-ai/dsh-command-compact": ">=0.1.1-rc.2 <0.2.0",
-    "@deepseek-ai/dsh-compaction": ">=0.1.1-rc.2 <0.2.0",
-    "@deepseek-ai/dsh-compaction-basic": ">=0.1.1-rc.2 <0.2.0",
-    "@deepseek-ai/dsh-client-locale": ">=0.1.1-rc.2 <0.2.0",
-    "@deepseek-ai/dsh-client-runtime": ">=0.1.1-rc.2 <0.2.0",
-    "@deepseek-ai/dsh-client-ui-primitives": ">=0.1.1-rc.2 <0.2.0",
-    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.1-rc.2 <0.2.0",
-    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.1-rc.2 <0.2.0",
-    "@deepseek-ai/dsh-client-ui-workspace": ">=0.1.1-rc.2 <0.2.0",
-    "@deepseek-ai/dsh-invariants": ">=0.1.1-rc.2 <0.2.0",
-    "@deepseek-ai/dsh-llm": ">=0.1.1-rc.2 <0.2.0",
-    "@deepseek-ai/dsh-session": ">=0.1.1-rc.2 <0.2.0",
-    "@deepseek-ai/dsh-settings": ">=0.1.1-rc.2 <0.2.0",
-    "@deepseek-ai/dsh-system-prompt": ">=0.1.1-rc.2 <0.2.0",
-    "@deepseek-ai/dsh-token-meter": ">=0.1.1-rc.2 <0.2.0",
-    "@deepseek-ai/dsh-tools": ">=0.1.1-rc.2 <0.2.0",
-    "@deepseek-ai/schemastery": ">=3.18.1 <4",
-    "react": ">=18 <19"
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/cordis-plugin-group": "1.0.1",
+    "@deepseek-ai/cordis-plugin-include": "1.0.6",
+    "@deepseek-ai/cordis-plugin-loader": "1.0.2",
+    "@deepseek-ai/dsh-agent": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-agent-loop": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-agent-loop-testkit": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-agent-presets": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-locale": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-workspace": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-command-compact": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-commands": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-compaction": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-compaction-basic": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm-deepseek": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-scope": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-subagent": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-subagent-fork-in-process": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-subagent-spawn-in-process": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-token-meter": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "3.18.1",
+    "@eslint/js": "^10.0.1",
+    "@testing-library/react": "^16.3.2",
+    "@tsdown/css": "^0.22.14",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.20.0",
+    "@types/react": "~18.3.1",
+    "eslint": "^10.10.0",
+    "globals": "^17.12.0",
+    "jsdom": "29.1.1",
+    "lightningcss": "^1.33.0",
+    "react": "^18.2.0",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.69.0",
+    "vitest": "^4.1.8"
   }
 }

package/packages/selector/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WilliamShi666
+
+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/packages/selector/README.md

@@ -0,0 +1,26 @@
+# dsh-context-compression-improved
+
+The installable Product Bundle for the unofficial community DeepSeek Harness context-compression selector.
+
+**0.1.0 highlights:** DeepSeek V4 Flash Vision's official tokenizer is included; users can choose the model-driven Auto Compact threshold; standard profile watermarks and compression parameters follow that choice.
+
+```sh
+dsh plugin --profile web add dsh-context-compression-improved@latest
+dsh --profile web --dump-config
+```
+
+This one command installs the Bundle and its pinned `@huggingface/tokenizers` dependency; there is no separate runtime package. The Bundle contributes Host settings, the Web UI, and a reversible preset overlay. All presets except the exact built-in `minimal` id receive the compression stack; switching non-Minimal presets preserves the saved selector settings. Minimal pauses plugin compression without deleting the setting.
+
+## What it provides
+
+It provides deterministic Fresh, Aggregate, History, Native tool-result, and Custom TailTrim compression; a plugin-owned `context_compression_retrieve` recovery tool; structured audit records; and a pinned offline DeepSeek V4 tokenizer. It uses only public DeepSeek Harness APIs and supports both `0.1.1-rc.2` and `0.1.2-alpha.5`; it does not patch Harness core.
+
+Lossy rewrites require exact same-revision counts before and after replacement. Verified model ids are `deepseek-v4-flash`, `deepseek-v4-pro`, and `deepseek-v4-flash-vision-exp`. Vision text counting uses the separately pinned `deepseek-ai/DeepSeek-V4-Flash-Vision-Exp` tokenizer. Vision images use the official image-processor arithmetic validated against official golden fixtures and are reported as `tokenizer-estimate`: the four alignment residues over valid intrinsic dimensions are collapsed to their midpoint, with 384 tokens retained as the per-image upper bound; malformed or unevaluable dimensions use a fixed 256-token fallback. The estimate is not exact because the absolute prompt position and the adapter's final image projection are not publicly observable. Image-bearing tool-result candidates remain exact-ineligible and intact; unknown models, unavailable tokenizer assets, unsafe tool groups, and incomplete text measurements still fail open.
+
+Audit log records use the prefix `context-compression audit ` and distinguish policy snapshots, skipped/disabled components, committed rewrites, fail-open errors, and observed core `compaction/summary` events. No audit record contains prompt or tool-result content.
+
+The first `policy-frozen` record carries the complete settings/deployment snapshot. It is emitted through the Harness logger, so its retention follows the configured log sink; standard prune/replacement Session events remain the durable proof of committed rewrites. This package does not hard-code a private path below `~/.dsh`.
+
+Verified compatibility: DeepSeek Harness `dsh-v0.1.1-rc.2` and `dsh-v0.1.2-alpha.5`, Node `^22.19.0 || >=24`. No Harness core patch is required.
+
+See the [full README](https://github.com/WilliamShi666/dsh-context-compression-improved#readme) for profiles, defaults, audit evidence, Adaptive/cache limitations, upgrade/removal, and security guidance. Tokenizer provenance and checksums are in `assets/deepseek-v4/manifest.json` and `assets/deepseek-v4-vision-exp/manifest.json`, summarized in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). This package is not affiliated with or endorsed by DeepSeek.

package/packages/selector/README.zh.md

@@ -0,0 +1,26 @@
+# dsh-context-compression-improved
+
+这是可直接安装的非官方社区 DeepSeek Harness 上下文压缩选择器 Product Bundle。
+
+**0.1.0 更新：**已加入 DeepSeek V4 Flash 视觉模型的官方 tokenizer；用户可选择模型驱动 Auto Compact 的触发阈值；标准 Profile 的水位与压缩参数会随该选择联动。
+
+```sh
+dsh plugin --profile web add dsh-context-compression-improved@latest
+dsh --profile web --dump-config
+```
+
+这一条命令会安装 Bundle 及其固定版本的 `@huggingface/tokenizers` 依赖，不再需要单独的 runtime 包。Bundle 提供 Host 设置、Web UI 和可逆的 preset overlay。除 id 精确等于内置 `minimal` 的 preset 外，其他 preset 都会获得压缩能力；非 Minimal preset 之间切换时已保存设置保持不变。Minimal 只暂停插件压缩，不删除设置。
+
+## 本包能力
+
+本包提供确定性的 Fresh、Aggregate、History、Native 工具结果与 Custom TailTrim 压缩，插件自有的 `context_compression_retrieve` 恢复工具，结构化审计记录，以及固定版本的离线 DeepSeek V4 tokenizer。它只使用 DeepSeek Harness 的公开 API，兼容 `0.1.1-rc.2` 与 `0.1.2-alpha.5`，不修改 Harness 核心。
+
+有损改写要求 replacement 前后取得同 revision 的 exact count。明确验证过的模型 id 为 `deepseek-v4-flash`、`deepseek-v4-pro` 与 `deepseek-v4-flash-vision-exp`。视觉模型的文本计数使用独立固定的 `deepseek-ai/DeepSeek-V4-Flash-Vision-Exp` tokenizer。图像 token 使用由官方 golden fixtures 逐项验证的官方图像处理算术，并以 `tokenizer-estimate` 上报：有效 intrinsic 尺寸的四种对齐位置取中值，每张图片保留 384 token 上限；尺寸畸形或无法计算时固定计为 256 token。由于绝对 prompt 位置与 adapter 最终图片投影不可公开观测，该数值不标记为 exact。含图片的工具结果候选仍不具备 exact 资格并保持原样；未知模型、tokenizer 资产不可用、不安全工具组或文本计量不完整时继续 fail-open。
+
+审计日志以 `context-compression audit ` 开头，区分策略快照、组件关闭/跳过、已提交 rewrite、fail-open 错误和已观察到的核心 `compaction/summary`。审计记录不包含 prompt 或工具结果正文。
+
+首次 `policy-frozen` 会携带完整 settings/deployment 快照。它通过 Harness logger 输出，因此保留期限由部署的日志 sink 决定；标准 prune/replacement Session event 仍是已提交 rewrite 的持久证据。本包不会在 `~/.dsh` 下硬编码私有路径。
+
+已验证兼容：DeepSeek Harness `dsh-v0.1.1-rc.2` 与 `dsh-v0.1.2-alpha.5`，Node `^22.19.0 || >=24`。不需要修改 Harness 核心。
+
+Profile、默认值、审计证据、Adaptive/cache 限制、升级/卸载与安全说明见[完整 README](https://github.com/WilliamShi666/dsh-context-compression-improved#readme)。Tokenizer 来源与校验和在 `assets/deepseek-v4/manifest.json`、`assets/deepseek-v4-vision-exp/manifest.json`，并汇总于 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。本包与 DeepSeek 无隶属或背书关系。

package/packages/selector/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,38 @@
+# Third-party notices
+
+Portions of this package are adapted from the MIT-licensed DeepSeek Harness, verified against `dsh-v0.1.1-rc.2` (`b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`).
+
+## DeepSeek Harness MIT notice
+
+Copyright (c) 2026 DeepSeek
+
+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.
+
+This package also distributes `tokenizer.json` and `tokenizer_config.json` from these pinned official repositories, both under the MIT license:
+
+- `deepseek-ai/DeepSeek-V4-Pro` revision `0e1a0e5e52aea73055f50fef6f2423db370265b6` (serves `deepseek-v4-flash` and `deepseek-v4-pro`), in `assets/deepseek-v4/`.
+- `deepseek-ai/DeepSeek-V4-Flash-Vision-Exp` revision `6821d6ad3681a4b137b066b76094fa82ebd0a380` (serves `deepseek-v4-flash-vision-exp`), in `assets/deepseek-v4-vision-exp/`. This tokenizer is a distinct artifact, not an alias of the V4 Pro tokenizer.
+
+The exact provenance and SHA-256 values are in each directory's `manifest.json`; the upstream license text ships beside the assets. The vision image-token arithmetic is a port of the repository's `inference/image_processor.py` at the same pinned revision.
+
+This package depends on `@huggingface/tokenizers` 0.1.3 under Apache-2.0. Its NPM package carries the dependency license text.
+
+This package depends on `js-yaml` under MIT; its production dependency `argparse` is licensed under Python-2.0. Their NPM packages carry the dependency license texts.
+
+This is an unofficial community package and is not endorsed by DeepSeek.

package/packages/selector/docs/history-tool-call-working-set-spec.md

@@ -0,0 +1,112 @@
+# History / microcompact：按 agent 工具调用保护近期工作集
+
+状态：提案，尚未实现
+
+## 目标与边界
+
+将插件的 History / microcompact 从“保护最近若干个 Harness turn 加一个 token 尾窗”改为“超过该 Profile 的 History 触发阈值后，保护最近 10 次已完成的 agent 工具调用”。这是一项面向所有插件 Profile 的策略变更，不是只为 Balanced 调整。
+
+所有实现只修改本仓库的 runtime、selector UI、配置、审计、测试和 npm Bundle。不得修改 DeepSeek Harness 核心、会话事件格式、内置压缩器、provider 或 DSH UI。插件继续只消费现有公开的 `tool/call`、`tool/result` 和 Session surface API。
+
+此前发现的 `deepseek-official` tokenizer route alias 是独立的插件内兼容性修复：需回填到本仓库的 `measurement.ts` 并测试，但不属于本 History 策略改动。
+
+## 现有问题
+
+当前 History 用外层 `turn` 保护近期内容。一个 turn 通常是一次用户消息驱动的 agent 处理周期，不是一次工具调用：一次“探索代码库”的用户请求可以在同一 turn 内产生几十个 Bash、Read、Grep 或 Web 调用。这样它们会被整体保护，即使其中大部分已经很旧；反过来，连续输入几条没有工具输出的用户消息也会推进保护窗口。
+
+用户消息不是 History 的可替换对象，保护它们的外层 turn 对 History 没有实际约束意义。现有的 `historyKeepRecentTokens` 也会让“近期保护”取决于个别结果的大小，而不是 agent 最近实际使用过的工具交互数量。
+
+## 统一语义
+
+### 触发条件不变
+
+每个 Profile 仍使用自己的 History gate、`historyTriggerTokens` 和 `historyMinReclaimTokens`。当且仅当：
+
+1. 运行到了插件的 `pressure` 阶段；
+2. Profile 的 History gate 允许执行；
+3. 所有活动工具结果的精确 token 总数严格大于该 Profile 的 `historyTriggerTokens`；
+
+History 才会规划 microcompact。Fresh、Aggregate、Native 和 TailTrim 的各自 trigger/reducer 不因这条规则而变。
+
+### 两部分近期工作集
+
+一条可计数记录是一个仍在活动 surface 中、能按 `callId` 与 agent 发出的 `tool/call` 配对的 `tool/result`。计数顺序使用该调用在活动会话 surface 中的原始发生顺序，不能使用外层 turn，也不能使用之后压缩替换事件的 seq。
+
+- 精确保护最新 10 条已完成调用；不足 10 条时全部保护。
+- 用户消息、assistant 文本、`turn/start`、`turn/end`、`step/start`、`step/end` 都不计数，也不因它们的数量改变选择结果。
+- 尚未产生 `tool/result` 的未完成调用不占槽位，也不是压缩候选。
+- `context_compression_retrieve` 也算一次 agent 工具调用并占一个槽位，以保证“最后十次调用完全不动”的字面语义；但它本身继续永远不可被 History 重写。
+- 已经是 History 占位符的结果继续占槽位，但不能再次被 History 重写。
+
+在调用数量保护之外，保留一个 `64000` token 的工具结果尾窗。从最新活动 `tool/result` 向较早结果逐条累计精确 token；每一条先加入保护集、再判断累计值是否已达到或超过 `64000`。因此，刚好使累计值跨过 `64000` 的那一条也受保护。这个尾窗同样不包含用户消息或 assistant 文本。
+
+最终保护集是“最近 10 次调用保护集”和“最近 `64000` token 工具结果尾窗”的并集。排除它后，History 由旧到新选择安全结果，沿用现有可恢复占位符/富结果 reducer。达到 `max(historyMinReclaimTokens, totalTokens - historyTriggerTokens)` 后停止；若最终无法达到最小回收量，则整个 History 批次不提交。精确 tokenizer 不可用、结果形态不安全或 recovery tool 缺失时继续 fail-open。
+
+删除 `historyKeepRecentTurns`，保留并将标准 Profile 的 `historyKeepRecentTokens` 统一为 `64000`。近期工作集因此同时保证最近工具交互数量和最近工具结果的内容规模。
+
+## 各 Profile 的计划与初始参数
+
+首版只替换“保护集的计算方法”，保留现有各 Profile 的触发和回收数值。这样可以先验证工作集语义，而不把“何时触发”“保留什么”“一次回收多少”三个变量同时改变。下表中的“建议首版”是待实现值；“后续调参”只有在带真实工具输出的可重复测试证明需要时才进行。
+
+| Profile | 当前/建议 History gate | 首版 trigger / 最小回收 | 近期保护 | 后续调参方向 |
+| --- | --- | --- | --- | --- |
+| `off` | disabled | 不触发 | 10 次调用 + `64000` token；无运行效果 | 无；保持关闭。 |
+| `native` | disabled | 不触发；Native 头-中-尾裁剪仍独立 | 10 次调用 + `64000` token；无运行效果 | 无；不得把 History 偷偷加入 Native。 |
+| `balanced` | `routine` | `500000 / 96000` tokens，保持不变 | 最近 10 次调用 + `64000` token 尾窗 | 作为基线。若保护集导致频繁无法达到 96k 回收，再只评估提高 trigger 或降低 min-reclaim 之一。 |
+| `cache-strict` | `capacity-pressure` | `600000 / 128000` tokens，保持不变；路由上下文利用率至少 `70%` | 最近 10 次调用 + `64000` token 尾窗 | 不降低 trigger；它以稳定已发送前缀为优先。只在已确认容量压力时改写。 |
+| `savings` | `routine` | `400000 / 128000` tokens | 最近 10 次调用 + `64000` token 尾窗 | 将 trigger 从 `450000` 提前到 `400000`，以更早回收旧工具结果；首版保留 `128000` 最小回收量，避免用一次很小的前缀改写交换缓存损失。 |
+| `adaptive` | `adaptive`，容量压力可覆盖 | `500000 / 96000` tokens，保持不变 | 最近 10 次调用 + `64000` token 尾窗 | 先让现有成本判断评估新的候选批次；没有连续官方 usage/价格证据时不调低门槛。 |
+| `custom` | `enabled + prefixPolicy` 决定 routine 或 capacity-pressure | 保留用户的 trigger/min-reclaim | 默认 10 次调用 + `64000` token 尾窗 | Custom v3 允许用户显式改两个保护值；默认/重置值为 10 与 `64000`。 |
+
+TailTrim 不属于 History / microcompact，但它目前复用 History 的近期保护 helper。为避免同一 helper 同时拥有两套语义，TailTrim 也使用同一个“最近 N 次工具调用 + token 尾窗”保护集；它的独立 trigger、完整工具组条件和 reducer 不变。
+
+## 参数与配置改动
+
+近期保护参数为：
+
+```ts
+historyKeepRecentToolCalls: number
+historyKeepRecentTokens: number
+```
+
+前者是非负安全整数；标准 Profile 都解析为 `10`，它不是 token 数，不受 `tokens` / `context-percent` 单位切换影响。后者保留现有 token 尾窗语义，标准 Profile 都解析为 `64000`。即使 `off`、`native` 的 History 被禁用，解析后的策略结构仍完整一致。
+
+Custom 升为版本 3：
+
+```ts
+history: {
+  enabled: boolean
+  trigger: number
+  keepRecentToolCalls: number
+  keepRecentTokens: number
+  minReclaim: number
+}
+```
+
+Custom 编辑器显示“保护近期工具调用数”和“保护近期工具结果尾窗”，默认值分别为 10 与 `64000`。保留 Custom 的可编辑性：标准 Profile 固定这些默认值，只有明确选择 Custom 的用户可以改变它们。若产品决定“Custom 也必须固定为这些值”，可在实现前删去两个输入框；其余算法不受影响。
+
+已有 Custom v1/v2 设置继续可读：插件将它们规范化为 v3，将 `keepRecentToolCalls` 设为 10，并将用户原有的 `keepRecent` 原样迁移为 `keepRecentTokens`。下一次用户保存 Custom 时写回 v3。部署配置中使用已删除的 `historyKeepRecentTurns` 则在插件加载时明确报错，提示改用 `historyKeepRecentToolCalls`；`historyKeepRecentTokens` 继续受支持。
+
+## 审计与可观测性
+
+`policy-frozen` 和 `policy-resolved` 记录新字段。History rewrite 仍记录 `component: "history"`、`stage: "pressure"`、History mode、reducer、精确 token 前后值和回收量。
+
+为解释选择器结果，History 审计增加有限元数据：配置的保护调用数、尾窗 token 预算、活动已完成调用总数、实际受保护结果数。不得记录工具文本、工具参数、用户消息、call id 或 prompt。无需新增 DSH Session event 或修改 DSH 核心审计 schema。
+
+## 验证计划
+
+每个 History-enabled Profile 至少覆盖一次独立测试；不得只用 Balanced 证明实现。
+
+1. 一个用户 turn 内连续完成至少 16 次调用并越过 trigger：最近 10 次总计约 `30000` token，继续向前累计到 `64000` token 的第 11 至第 15 次也不变；第 16 次（从最新向旧数）成为可选候选。
+2. 将同一批调用切分到任意多个用户 turn：受保护和可压缩集合完全相同；只添加用户消息的 turn 不改变结果。
+3. 包含并行调用、错误结果、富结果、已替换占位符和 `context_compression_retrieve`，验证计数顺序与不可重写规则。
+4. `off` 和 `native` 即使工具输出很大也不执行 History；Native 仍按自己的逻辑运行。
+5. Balanced、Savings 的 routine gate 在各自 trigger 之上执行；Cache Strict 只有确认容量压力时执行；Adaptive 在成本证据不足时跳过、容量压力时仍可执行；Custom 同时覆盖 routine 与 capacity-pressure。
+6. 十条或更少调用、未达到 `64000` token 尾窗但所有调用都仍在尾窗内、精确 tokenizer 不可用、无安全候选或达不到最小回收量时，History 只留下可解释的跳过审计，不产生部分重写。
+7. Custom v1/v2 规范化、v3 校验、浏览器输入、中文/英文文案、运行时公共测试、packed smoke、构建和 clean-install 发布验证均使用新字段。
+
+## 风险与取舍
+
+最近十条结果或 `64000` token 尾窗可能很大，导致旧结果不足以回收最小 token 数；此时跳过是对工作集保证的正确结果，而不是压缩器失效。Savings 的更激进候选参数必须先用同一任务的 token、缓存和结果可用性数据验证。
+
+这会改变旧 Custom 文档的实际保留行为。将其统一为 10 次调用是可预测的迁移，但不等价于任何旧 turn/token 数。发布说明必须明确指出 Custom v3 和该语义变化。

package/packages/selector/docs/native-tool-result-selector-spec.md

@@ -0,0 +1,34 @@
+# 原生工具结果压缩接管规格
+
+## 范围
+
+本规格只约束选择器 Bundle 的工具结果压缩。不得修改 DeepSeek Harness 核心、内置 pruner、会话事件格式或 DSH UI。
+
+## 机制
+
+适用的 Harness preset 在插件的可逆 overlay 中移除 `@deepseek-ai/dsh-compaction-tool-result-pruner`，并以选择器 runtime 的同名 `toolResultPruner` 服务替换它。Harness 的 compaction-basic 继续调用这个公开服务；选择器据冻结的 Profile 决定允许哪一种 reducer。因此同一 Session 不会同时运行核心头尾裁剪和选择器 reducer。
+
+## Profile 规则
+
+| Profile | 选择器原生风格头—中间—尾 reducer | 其他选择器路径 |
+| --- | --- | --- |
+| `native` | 允许 | Fresh、Aggregate、History、TailTrim 均关闭 |
+| `balanced` | 禁止 | 按 Balanced policy 运行 |
+| `cache-strict` | 禁止 | 按 Cache Strict policy 运行 |
+| `savings` | 禁止 | 按 Savings policy 运行 |
+| `adaptive` | 禁止 | 按 Adaptive policy 运行 |
+| `custom` | 禁止 | 只运行 Custom 明确启用的路径 |
+| `off` | 禁止 | 不运行选择器工具结果压缩 |
+
+这里的“禁止”同时排除两条路径：overlay 已移除核心 `@deepseek-ai/dsh-compaction-tool-result-pruner`，解析后的 `nativeToolResultEnabled` 也为 `false`。因此不会生成 `component: "native-tool-result"` 的选择器 rewrite。`native-auto-compact` 是 Harness/模型独立机制，不受本规格控制。
+
+## 会话冻结
+
+选择器首次观察 Session 时冻结 Profile 与 Custom 文档。之后修改全局设置只能影响新 Session，不能让已经采用 Balanced、Savings、Cache Strict、Adaptive 或 Custom 的 Session 在中途重新启用头—中间—尾裁剪。
+
+## 验收
+
+1. `resolvePolicy()` 对 `balanced`、`cache-strict`、`savings`、`adaptive`、`custom` 返回 `nativeToolResultEnabled: false`，对 `native` 返回 `true`。
+2. 插件 runtime 的 pressure pass 仅在 `nativeToolResultEnabled` 为 `true` 时计划 `native-tool-result` rewrite。
+3. preset overlay 测试证明生成 composition 中没有核心 pruner，只有选择器 runtime 的同名服务。
+4. 所有源代码改动限定在本仓库；不修改 Harness worktree。

package/packages/selector/docs/subagent-cache-reuse-spec.md

@@ -0,0 +1,46 @@
+# Parent and child agent cache-prefix audit
+
+## Scope
+
+This reference characterizes when DeepSeek Harness parent and child requests can present an identical prompt prefix to DeepSeek's automatic context cache. It does not add an explicit cache key, cache breakpoint, cache identifier, or client-side KV cache.
+
+The selector plugin owns settings registration and UI only. It has no hook into agent request construction, subagent session creation, or LLM serialization, so this work must not add runtime request behavior to the plugin or modify Harness core.
+
+## Three separate questions
+
+Context inheritance asks whether a child session receives parent session events. A fork copies the parent event prefix through the last completed turn; a spawn starts without parent messages. The child metadata records the parent session and, for a fork, the seed length.
+
+Harness cache control asks whether Harness supplies a DeepSeek cache key or breakpoint across requests or sessions. The DeepSeek adapter serializes ordinary Chat Completions input and reads official usage fields; it supplies no explicit cache control.
+
+Server cache reuse asks whether byte-identical request prefixes can hit DeepSeek's automatic context cache. This is best-effort server behavior and is confirmed only when official response usage reports a positive `prompt_cache_hit_tokens` value. Latency and price are not evidence.
+
+## Reuse characterization
+
+The test-only audit representation is versioned and canonical. Object keys are sorted recursively, while arrays retain their model-visible order. A SHA-256 fingerprint is computed over UTF-8 JSON containing the provider, model, system prompt, tool schemas, and inherited messages.
+
+A child is reusable only when it is a fork, declares parent-context inheritance, and its provider, model, system prompt, tools, and inherited messages equal the parent's stable envelope. Spawn mode, a changed persona or system prompt, changed tool schema or order, changed provider or model route, and changed history are rejected. The audit never repairs or concatenates mismatched contexts.
+
+The characterization does not guarantee that two independently assembled HTTP bodies have the same byte prefix: JSON property order and the child-only continuation still belong to the DeepSeek adapter. The live test captures the actual immutable agent-loop request options and compares the stable inherited envelope before allowing a cache-reuse claim.
+
+## Safe evidence record
+
+An evidence event may contain only the audit version, prefix fingerprint, estimated shared-prefix tokens, parent and child session identifiers, mode, eligibility or reason, cache-read tokens, cache-miss tokens, observed prompt tokens, and confirmation status. It must not contain prompts, messages, tool arguments or results, tool schemas, permissions, environment values, credentials, or secrets.
+
+Usage is internally consistent only when `cacheReadTokens + cacheMissTokens` equals the observed prompt-token total. A positive cache-read count confirms a natural cache hit for that request. Missing or zero cache-read usage yields `unconfirmed`, never a claimed miss caused by Harness.
+
+## TDD acceptance criteria
+
+The RED test imports an absent test-support module and defines the required behavior before implementation. The GREEN implementation remains under `tests/support` and exports no product runtime API.
+
+- Fork accepts an identical completed-turn prefix and produces the same fingerprint for parent and child views.
+- Spawn is ineligible because it does not inherit parent messages.
+- Persona, tool schema or order, provider, model, and history mismatches are ineligible.
+- Safe evidence records contain only the allowlisted fields and never contain representative secret or tool-result content.
+- Usage projection accepts hit plus miss equaling the prompt total and rejects inconsistent totals.
+- The existing selector runtime source remains unchanged, so disabling or omitting the plugin cannot affect agent requests.
+- A key-gated host-side live DeepSeek E2E test uses an isolated in-memory context and task-local `DSH_HOME`; it reports only sanitized usage evidence.
+- Existing fork, spawn, request-reconstruction, DeepSeek usage-projection, selector-plugin tests, the full build, and `git diff --check` pass.
+
+## Operational boundaries
+
+Tests do not connect to the active web profile, start or restart a Harness service, deploy code, or write session logs outside the isolated test environment. The test-only implementation adds no product runtime API and does not alter active profile settings or service state.