@khorsheed/dsh-context-guard 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# 变更记录
+
+## 0.1.0（2026-08-22）
+
+首个公开发布。
+
+- 上下文占用越过配置比例时，输入框工具栏自动出现琥珀色压缩按钮，低于阈值时隐藏
+- 点击执行官方 `/compact`，在上下文溢出拒绝请求之前提醒
+- 与输入框旁的进度环同一数据源（官方 `contextPressure` 投影），两者永不打架
+- 阈值比例（0.01–1）在设置 → 插件里实时调整，无需重启

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-plugins contributors
+
+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.en.md

@@ -0,0 +1,89 @@
+# @khorsheed/dsh-context-guard
+
+English | [中文](README.md)
+
+A context-window compaction reminder for the dsh web GUI: once **context occupancy** — the same number the composer's context ring shows — crosses a configured share of the model's context window, a compact button appears in the composer, and clicking it runs the official `/compact` command. Uninstalling removes every surface it adds.
+
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/context-guard-button.png" width="480" alt="the compact button appears in the composer once context occupancy crosses the configured ratio">
+
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/context-guard-settings.png" width="480" alt="the trigger ratio is configurable in settings (0.01–1)">
+
+## Features
+
+- **Compact button in the composer** — hidden below the threshold, appears in the amber warning tint above it.
+- **Same number as the context ring** — driven by the official `contextPressure` projection, so button and ring never disagree.
+- **Runs the official `/compact`** — idle-gating, the compaction lock, and presentation stay host-owned.
+- **One live tunable** — the occupancy threshold, editable in Settings → Plugins with no restart.
+
+## Install
+
+```sh
+dsh plugin --profile web add @khorsheed/dsh-context-guard
+```
+
+Restart the web instance after adding. Uninstall:
+
+```sh
+dsh plugin --profile web remove @khorsheed/dsh-context-guard
+```
+
+## Config
+
+One tunable, editable in the GUI (Settings → Plugins → "压缩提醒时机 / Compaction reminder timing") and live with no restart.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `thresholdRatio` | `0.8` | Context occupancy fraction at which the button appears (clamped to (0, 1]). Lower it to be reminded earlier — the provider rejection wall sits below 100% occupancy (see *How it works*). |
+
+```yaml
+plugins:
+  context-guard:
+    thresholdRatio: 0.65
+```
+
+**This field tunes ONLY when the button appears** — real compaction timing stays owned by the official compaction engine's own `thresholdRatio` / `auto` config.
+
+## Compatibility
+
+- npm release line (`@deepseek-ai/dsh@0.1.1-rc.2`): ✅ full — built and tested against the rc.8 type surface. This build REQUIRES rc.8: the `commands/execute` Remote gained a required `images` argument (rc.6/rc.7 hosts would receive shifted arguments) — stay on the previous build there. — also verified on 0.1.1-rc.1 (additive audit, 2026-08-21); re-audited for rc.2 (2026-08-22): consumed surface unchanged, full build+test green
+- source line (deepseek-harness master): ✅
+
+## Known Limitations
+
+- **Reminder, not guarantee** — context may grow between the button appearing and the click, and `/compact` can report `busy` while the agent runs.
+- **No output-cap knob** — the rejection wall depends on `window − maxTokens`, a model property, not a user preference.
+- **No auto-compaction** — the official 80% auto-compaction keeps running unchanged.
+
+## How it works
+
+<details>
+<summary>Why it exists and internals (click to expand)</summary>
+
+### Reminding you before the wall the meter does not show
+
+The official compaction-basic engine auto-compacts at 80% of the context window, and only between steps. But providers reject a request when `prompt + max_tokens > context_length` — the request reserves output tokens, so the rejection wall sits below 100% occupancy. With the deepseek adapter's defaults (window 1,000,000, output cap 256,000) the wall is ~74.4%, below even the official 80% point; the estimator also underprices CJK text and JSON schemas, so the provider-side count runs higher than the ring shows. On an idle session nothing signals that the next send will fail.
+
+At the default ratio (0.8) the button appears exactly when the official engine would compact anyway; **lower the ratio (e.g. 0.6–0.7) to be reminded earlier** — while a manual `/compact`'s summarization call still fits comfortably.
+
+### Mechanics
+
+- **Seat**: `conversation.input.right` (the composer's tool row, before the send button).
+- **Data**: the official `contextPressure` session projection — `projectedTokens` and `contextWindow`, with a fallback to the bare provider sample on older logs.
+- **Formula**: `projectedTokens / contextWindow >= thresholdRatio` — the same occupancy the context ring shows.
+- **Action**: the official `/compact` channel (`remote.commands.execute` → `ctx.commands` → `ctx.compaction.compactNow`).
+
+### Model experience
+
+Nothing changes for the model: clicking the button runs the same `/compact` the user could type, with the same command lifecycle in the session log. The plugin itself has no token or KV-cache effect.
+
+`/client` exports the plugin body (`apply`/`inject`) and the `CompactGuardButtonProps` / `ContextGuardSettingsCardProps` types.
+
+</details>
+
+## Development
+
+Part of the [dsh-plugins](https://github.com/Khorsheed/dsh-plugins) monorepo (`packages/context-guard`). Issues and contributions welcome there.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record: the git blob hash of each side as of the
+# last confirmed-consistent state. Both languages carry equal authority; after
+# editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/context-guard/README.en.md
+packages/context-guard/README.en.md: a84a48bccbd65b6d86314a390d442d3ed05b7ba2
+packages/context-guard/README.md: 54678e16c8d1322b9bc9987d1004a48a54c6584b

package/README.md

@@ -0,0 +1,89 @@
+# @khorsheed/dsh-context-guard
+
+[English](README.en.md) | 中文
+
+dsh Web GUI 的上下文窗口压缩提醒：当**上下文占用**——与输入框旁边进度环显示的是同一个数——越过模型上下文窗口的配置比例时，输入框工具栏里会自动出现一枚压缩按钮，点击即执行官方 `/compact` 命令。卸载即清除它添加的所有界面。
+
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/context-guard-button.png" width="480" alt="上下文占用越过配置比例后，聊天框出现压缩按钮">
+
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/context-guard-settings.png" width="480" alt="提醒比例可在设置中按偏好调整(0.01–1)">
+
+## 特性
+
+- **输入框里的压缩按钮**——低于阈值时隐藏，越过后以琥珀警示色自动出现。
+- **与进度环同一个数**——由官方 `contextPressure` 投影驱动，按钮与进度环永不打架。
+- **执行官方 `/compact`**——空闲门控、压缩锁与流程节点展示都由宿主负责。
+- **一个实时可调项**——占用阈值，在设置 → 插件里改，无需重启。
+
+## 安装
+
+```sh
+dsh plugin --profile web add @khorsheed/dsh-context-guard
+```
+
+安装后重启 web 实例。卸载：
+
+```sh
+dsh plugin --profile web remove @khorsheed/dsh-context-guard
+```
+
+## 配置
+
+一个可调项，在 GUI 里改（设置 → 插件配置 →「压缩提醒时机 / Compaction reminder timing」）且实时生效，无需重启。
+
+| 键 | 默认值 | 含义 |
+|---|---|---|
+| `thresholdRatio` | `0.8` | 压缩按钮出现时的上下文占用比例（限制在 (0, 1]）。想更早收到提醒就调低——provider 拒绝墙在 100% 占用之下（见「实现原理」）。 |
+
+```yaml
+plugins:
+  context-guard:
+    thresholdRatio: 0.65
+```
+
+**该字段只影响按钮出现的时机**——真实压缩时机仍由官方压缩引擎自己的 `thresholdRatio` / `auto` 配置决定。
+
+## 兼容性
+
+- npm 发布线（`@deepseek-ai/dsh@0.1.1-rc.2`）：✅ 完整——基于 rc.8 类型面构建并通过测试。本构建**要求 rc.8**：`commands/execute` Remote 新增必填 `images` 参数（rc.6/rc.7 宿主会收到错位的参数）——在旧宿主上请停留在上一个构建。——亦在 0.1.1-rc.1 上验证（纯增量审计，2026-08-21）；rc.1→rc.2 复核（2026-08-22）：消费面无变化，全量构建测试通过
+- source 线（deepseek-harness master）：✅
+
+## 已知限制
+
+- **提醒，不是保证**——从按钮出现到点击之间上下文可能继续增长，agent 运行中 `/compact` 可能报 `busy`。
+- **没有输出上限旋钮**——拒绝墙取决于 `window − maxTokens`，这是模型属性而非用户偏好。
+- **不自动压缩**——官方 80% 自动压缩保持原样运行。
+
+## 实现原理
+
+<details>
+<summary>它为什么存在与内部结构（点击展开）</summary>
+
+### 在进度环看不到的"墙"之前提醒你
+
+官方 compaction-basic 引擎在上下文窗口 80% 处自动压缩，且只在步间运行。但 provider 在 `prompt + max_tokens > context_length` 时拒绝请求——请求要预留输出 token，因此拒绝墙在 100% 占用之下。以 deepseek 适配器的默认值（窗口 1,000,000、输出上限 256,000）计，墙在约 74.4% 处，甚至低于官方 80% 压缩点；估算器还系统性低估 CJK 文本与 JSON schema，provider 侧计数比进度环显示的高。空闲会话上没有任何信号提示下一次发送会失败。
+
+默认比例（0.8）下按钮与官方引擎要压缩的点重合；**调低比例（如 0.6–0.7）可更早收到提醒**——此时手动 `/compact` 的摘要调用还放得下。
+
+### 机制
+
+- **位置**：`conversation.input.right`（输入框工具栏、发送按钮之前）。
+- **数据**：官方 `contextPressure` 会话投影——`projectedTokens` 与 `contextWindow`，旧日志回退到 provider 裸样本。
+- **公式**：`projectedTokens / contextWindow >= thresholdRatio`——与进度环显示的是同一个占用数。
+- **动作**：官方 `/compact` 命令通道（`remote.commands.execute` → `ctx.commands` → `ctx.compaction.compactNow`）。
+
+### 模型体验
+
+对模型没有任何变化：点击执行的是与用户手动输入相同的 `/compact`，会话日志里也是同样的命令生命周期。插件本身无 token 与 KV 缓存影响。
+
+`/client` 导出即插件本体（`apply`/`inject`）与 `CompactGuardButtonProps` / `ContextGuardSettingsCardProps` 类型。
+
+</details>
+
+## 开发
+
+隶属 [dsh-plugins](https://github.com/Khorsheed/dsh-plugins) monorepo（`packages/context-guard`）。问题与贡献请移步该仓库。
+
+## 变更记录
+
+见 [CHANGELOG.md](CHANGELOG.md)。

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# context-guard bundle patch: inserts the plugin row into the composing
+# profile. The client half is discovered through the package.json dsh.client
+# block; the host half registers the settings namespace the settings card
+# edits. The reminder ratio defaults to 0.8 (matching compaction-basic's
+# pressure threshold); the settings card can lower it — the README explains
+# why (the provider rejection wall is window − output cap, so a request can
+# fail before occupancy alone reaches 80%).
+- insert:
+    - id: context-guard
+      name: '@khorsheed/dsh-context-guard'