billion-context-dsh 0.2.10 → 0.2.12

package/README.en.md

@@ -3,7 +3,7 @@
 [English](./README.en.md) | [中文](./README.md)
 
 > **⚠️ Beta notice — not for production use**
-> This project (**v0.2.10**) is a work-in-progress beta. The [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) itself is also in **public beta**. **Do not use either in engineering / production environments** — expect breaking changes and rough edges.
+> This project (**v0.2.12**) is a work-in-progress beta. The [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) itself is also in **public beta**. **Do not use either in engineering / production environments** — expect breaking changes and rough edges.
 
 <p align="center">
 <strong>Built with gratitude on top of these projects</strong> — please give them a ⭐:
@@ -53,25 +53,53 @@ This is the DeepSeek Harness port of [billion-context-pi](https://github.com/ran
 
 > 💡 **Want DeepSeek Harness to install it for you?** This repo itself runs on DSH: hand [docs/INSTALL.md](docs/INSTALL.md) to an agent in a session and it will read the guide, inspect your profile, wire the composition, and verify the mount. Two preconditions: ① the config lives under `~/.dsh`, so you approve one file-permission prompt; ② afterwards ask it to call `acp_status` as proof.
 
+**Path A (recommended): one-command install via the DSH store / `dsh plugin` (bundle) — globally active right after install, zero configuration.**
+
+Click install in DSH's plugin store, or run:
+
 ```bash
-npm install billion-context-dsh
+dsh plugin --profile web add billion-context-dsh
 ```
 
-> 💡 **One-command install via `dsh plugin` (bundle, v0.2.0+)**. The package declares a `dsh.bundle`
-> manifest, so DSH's plugin command installs it into the profile and applies the patch
-> automatically (equivalent to the composition row below):
+The command installs the package and automatically layers this package's bundle patch ([cordis.patch.yml](cordis.patch.yml)) into the profile's composition. The patch does two things:
+
+- **Disables the host `compaction-basic`** — so two backends do not both register `ctx.compaction` in the same realm (modern DSH web bundles already ship this disable; the row is an idempotent safety net that holds on every supported DSH);
+- **Mounts the ACP engine at the HOST plane** — the four model tools (`compress` / `decompress` / `search_context` / `acp_status`), the `/acp` command, the advisory nudge, and the ACP guidance section reach **EVERY mode** of the profile (standard / code / minimal / cordis / custom presets). Window auto-detection and the tools/command/nudge defaults are all on — **no manual configuration needed**.
+
+Restart `dsh` afterwards (bundle layers are composed at startup), open a new session, and verify: ask the model to call `acp_status`, or run `/acp status`. Shipped presets (standard / code / cordis) keep their realm-local `compaction-basic` fallback (automatic pressure compression still runs there; the ACP tools and nudge coexist); minimal and presets without a compaction realm use this engine directly.
+
+> **DSH version compatibility.** The package declares the peer range
+> `^0.1.0-rc.6 || ^0.1.1-rc.1` for `@deepseek-ai/dsh-compaction`, covering both the
+> `0.1.0-rc.x` and `0.1.1-rc.x` release lines (including the current DSH release;
+> the seam's `src/` is unchanged from `0.1.0-rc.6` to `0.1.1-rc.2`, so the public
+> API is identical). The range is two `||` clauses **on purpose**: npm
+> (node-semver) only lets a prerelease version satisfy a range that carries a
+> comparator on the SAME `[major, minor, patch]` tuple as the candidate, so a lone
+> `^0.1.0-rc.6` can never match `0.1.1-rc.x` (issue #68) — older releases fail to
+> install on DSH 0.1.1-rc.x; upgrade to a release containing this fix.
+
+**Path B: plain `npm install` (package only — a composition row is required).**
 
 ```bash
-dsh plugin --profile web add billion-context-dsh
+npm install billion-context-dsh
 ```
 
-Restart `dsh` afterwards (bundle layers are composed at startup). For custom `config`
-(such as `modelContextLimit` / `prompts`), keep the hand-written composition row — the
-bundle patch ([cordis.patch.yml](cordis.patch.yml)) only inserts the default row without `config`.
+This only installs the package into your project/global store; it does **not** touch any profile — add a composition row as shown below or the engine never mounts.
 
-That's it. Then add a composition row where a compaction backend is expected — two scopes, pick by how wide you want it:
+## Scope & customization
+
+Two audiences: ① Path B (plain npm install) users, who must write a composition row; ② Path A users who want custom `config` (the bundle already ships sane defaults — override them with a SAME-ID row).
+
+**Custom `config` (Path A bundle users).** Append a `compaction-acp` row with `config:` to your profile patch (e.g. `~/.dsh/profiles/web/cordis.patch.yml`) — the same-id row overrides the bundle's default row:
+
+```yaml
+- id: compaction-acp
+  name: 'billion-context-dsh'
+  config:
+    modelContextLimit: 128000   # optional; omit to auto-detect the model's real window (fallback 128000)
+```
 
-**Global — host plane, every mode** (recommended). In your profile patch (e.g. `~/.dsh/profiles/web/cordis.patch.yml`), add:
+**Global — host plane, every mode** (recommended). This is what Path A's bundle already does; plain-npm users add all of the following (bundle users skip the first two rows):
 
 ```yaml
 # ACP as the global compaction backend: four model tools + `/acp` command +
@@ -79,6 +107,7 @@ That's it. Then add a composition row where a compaction backend is expected —
 # (standard / code / minimal / cordis / custom presets).
 # Must also disable the host compaction-basic: two backends providing
 # `ctx.compaction` in the same realm collide.
+# (The bundle install already ships these two rows.)
 - id: compaction-basic
   disabled: true
 
@@ -171,7 +200,7 @@ This project reuses `acp-kernel`'s compression core and `billion-context-pi`'s d
 | Key | Default | Meaning |
 |---|---|---|
 | `modelContextLimit` | auto-detected (fallback `128000`) | Context window used for the kernel's pressure decisions; an explicit value wins and skips the probe |
-| `autoModelContextLimit` | `true` | Probe the model's real window from the model API (`agent.ctx.llm.resolveModelInfo`); fall back to the default on failure, the `/acp` command shows the window source (the `acp_status` model tool carries no window info) |
+| `autoModelContextLimit` | `true` | Probe the model's real window from the model API (`agent.ctx.llm.resolveModelInfo`); fall back to the default on failure, the `/acp` command shows the window source (the `acp_status` model tool carries no window info). A failed probe is surfaced in the host log and the `/acp` panel (`restart to re-probe`) — the failure is cached like a success, so fixing the gateway requires a restart or an explicit `modelContextLimit` before the probe retries |
 | `nudgeMinContextLimitPct` | kernel default `0.45` | Nudge window lower bound (usage fraction) — validation only; the growth-driven trigger has no percentage floor — same default as billion-context-pi |
 | `nudgeMaxContextLimitPct` | engine default `0.70` (kernel/pi default `0.75`) | Over-limit line: above this the nudge fires regardless of growth — deliberately below the host compaction-basic 80% auto-compaction line so the forced nudge fires first; an explicit value wins |
 | `nudgeEmergencyThresholdPct` | engine default `0.85` (kernel/pi default `0.95`) | Emergency nudge (bypasses the per-turn dedup) — lowered from `0.95`: at 95% the model has no room to act and the 80% auto-compaction line shadows it; an explicit value wins |

package/README.md

@@ -3,7 +3,7 @@
 [中文](./README.md) | [English](./README.en.md)
 
 > **⚠️ 测试版声明——请勿用于生产环境**
-> 本项目（**v0.2.10**）仍处于开发中的测试版。[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 本身也处于**公开测试版**阶段。**请勿将两者用于工程化 / 生产环境**——预期会有破坏性变更与粗糙之处。
+> 本项目（**v0.2.12**）仍处于开发中的测试版。[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 本身也处于**公开测试版**阶段。**请勿将两者用于工程化 / 生产环境**——预期会有破坏性变更与粗糙之处。
 
 <p align="center">
 <strong>衷心感谢以下项目——请给它们一个 ⭐：</strong>
@@ -56,30 +56,58 @@
 > 你的 profile、编辑组合配置并验证挂载。前提：① 配置写在 `~/.dsh` 下，需要
 > 你批准一次文件权限；② 装完让它调用 `acp_status` 自证。
 
+**方式一（推荐）：DSH 商店 / `dsh plugin` 一键装（bundle）——装完即全局生效，零配置。**
+
+在 DSH 的插件商店里点安装，或命令行执行：
+
 ```bash
-npm install billion-context-dsh
+dsh plugin --profile web add billion-context-dsh
 ```
 
-> 💡 **v0.2.0 起支持 `dsh plugin` 一键安装（bundle）**。包已声明 `dsh.bundle`
-> manifest，DSH 的插件命令会把它装进 profile 并自动应用补丁（等价于下面的组合行）：
+命令内部会装包并把本包的 bundle 补丁（[cordis.patch.yml](cordis.patch.yml)）自动挂进该 profile 的层栈。补丁做了两件事：
+
+- **禁用 host 的 `compaction-basic`**——避免同一 realm 内两个后端同时注册 `ctx.compaction` 冲突（现代 DSH 的 web bundle 已自带该禁用，此行为幂等兜底，任何受支持版本下都成立）；
+- **把 ACP 引擎挂到 host 平面**——四种模型工具（`compress` / `decompress` / `search_context` / `acp_status`）、`/acp` 命令、nudge、ACP 提示词段对该 profile 的**所有模式**（standard / code / minimal / cordis / 自定义预设）生效。窗口自动探测、工具/命令/nudge 默认全开，**无需任何手工配置**。
+
+装完**重启 `dsh`**（bundle 层在启动时组合），新开会话即可用——让模型调用 `acp_status` 或执行 `/acp status` 自证。shipped 预设（standard / code / cordis）内部的 realm 级 `compaction-basic` 自动压缩兜底仍然保留（这些模式里"自动摘要"照旧，ACP 工具与 nudge 并存）；minimal 等不带 compaction realm 的预设直接使用本引擎。
+
+> **与 DSH 版本的兼容性。** 包声明 peer 依赖 `@deepseek-ai/dsh-compaction` 为
+> `^0.1.0-rc.6 || ^0.1.1-rc.1`，同时覆盖 `0.1.0-rc.x` 与 `0.1.1-rc.x` 两条 rc 线
+> （含当前最新 DSH release；从 `0.1.0-rc.6` 到 `0.1.1-rc.2`，seam 的 `src/` 源码
+> 零改动，公开 API 完全一致）。范围写成两个并集子句是**有意为之**：npm
+> （node-semver）的预发布匹配规则要求 range 里存在与候选版本**相同
+> `[major, minor, patch]` 元组**的比较器，单一 `^0.1.0-rc.6` 永远匹配不了
+> `0.1.1-rc.x`（issue #68）——因此旧发布的包在 DSH 0.1.1-rc.x 上装不上，
+> 升级到含本次修复的新版本即可。
+
+**方式二：纯 `npm install`（只装包，需要手写组合行）。**
 
 ```bash
-dsh plugin --profile web add billion-context-dsh
+npm install billion-context-dsh
 ```
 
-装完重启 `dsh`（bundle 层在启动时组合）。需要自定义 `config`（如
-`modelContextLimit` / `prompts`）时仍建议手写组合行——bundle 补丁
-（[cordis.patch.yml](cordis.patch.yml)）只插入无 `config` 的默认行。
+这只把包装进你的项目/全局，**不会**触碰任何 profile——请按下方「两种生效范围与自定义」手写组合行，引擎才会挂载。
 
-就这样。然后在需要压缩后端的位置加组合配置——两种范围，按需选择：
+## 两种生效范围与自定义
+
+本节服务于两类人：① 方式二（纯 npm 安装，必须手写组合行）；② 方式一用户想自定义 `config`（bundle 已有默认行为，只需用**同 id** 行覆盖）。
+
+**自定义 config（方式一 bundle 用户）。** 在你的 profile 补丁（如 `~/.dsh/profiles/web/cordis.patch.yml`）里追加一个 `compaction-acp` 行并附 `config:`——同 id 行覆盖 bundle 的默认行：
+
+```yaml
+- id: compaction-acp
+  name: 'billion-context-dsh'
+  config:
+    modelContextLimit: 128000   # 可选；省略时自动探测模型真实窗口（回退 128000）
+```
 
-**全局生效（host 平面，所有模式）——推荐**。在你的 profile 补丁（如 `~/.dsh/profiles/web/cordis.patch.yml`）中追加：
+**全局生效（host 平面，所有模式）——推荐**。这是方式一 bundle 的默认行为；纯 npm 安装的用户在 profile 补丁中追加以下全部内容（bundle 用户跳过前两行）：
 
 ```yaml
 # ACP 作为全局压缩后端：四个模型工具 + `/acp` 命令 + nudge + ACP 提示词段，
 # 对所有模式（standard / code / minimal / cordis / 自定义预设）生效。
 # 必须同时禁用 host 的 compaction-basic：同一 realm 内两个后端同时
-# provide `ctx.compaction` 会冲突。
+# provide `ctx.compaction` 会冲突。（bundle 安装已自动带上这两行。）
 - id: compaction-basic
   disabled: true
 
@@ -172,7 +200,7 @@ DSH 的每个模型请求都派生自其 append-only 会话日志（*surface*）
 | 键 | 默认值 | 含义 |
 |---|---|---|
 | `modelContextLimit` | 自动探测（回退 `128000`） | 用于内核压力决策的上下文窗口；显式配置时优先且跳过探测 |
-| `autoModelContextLimit` | `true` | 从模型 API 自动探测真实窗口（`agent.ctx.llm.resolveModelInfo`）；探测失败回退默认值，`/acp` 命令展示窗口来源（模型工具 `acp_status` 不含窗口信息） |
+| `autoModelContextLimit` | `true` | 从模型 API 自动探测真实窗口（`agent.ctx.llm.resolveModelInfo`）；探测失败回退默认值，`/acp` 命令展示窗口来源（模型工具 `acp_status` 不含窗口信息）。探测失败会在宿主日志与 `/acp` 面板提示（`restart to re-probe`）——失败结果同样被缓存，修复网关后需重启或显式设置 `modelContextLimit` 才会重新探测 |
 | `nudgeMinContextLimitPct` | 内核默认 `0.45` | Nudge 窗口下界（用量占比）——仅作配置校验，增长路径的触发没有百分比下限——与 billion-context-pi 相同的默认值 |
 | `nudgeMaxContextLimitPct` | engine 默认 `0.70`（内核/pi 默认 `0.75`） | 过限线：超过此值则无论增长与否都触发 nudge——刻意低于宿主 compaction-basic 的 80% 自动压缩线，保证强制 nudge 先触发；显式配置优先 |
 | `nudgeEmergencyThresholdPct` | engine 默认 `0.85`（内核/pi 默认 `0.95`） | 紧急 nudge（绕过每轮去重）——从 `0.95` 下调：95% 时模型已无操作空间且会被 80% 自动压缩线遮蔽；显式配置优先 |

package/cordis.patch.yml

@@ -1,11 +1,32 @@
-# dsh bundle patch: inserts the ACP compaction backend into a profile's layer stack.
+# dsh bundle patch: makes billion-context-dsh ACTIVE right after a one-command
+# install — the plugin store and `dsh plugin --profile web add
+# billion-context-dsh` both run the same command, and this file (declared in
+# package.json as `dsh.bundle.patch`) becomes a layer of the profile's
+# composition automatically. No manual configuration is needed.
 #
-# This is what makes the package installable via `dsh plugin --profile web add
-# billion-context-dsh` (declared in package.json as `dsh.bundle.patch`). The row
-# below is exactly the manual composition row documented in docs/INSTALL.md (§2a),
-# minus config: omitting `modelContextLimit` means auto-detection (fallback 128000),
-# and the built-in prompt copy (config.prompts) is used. Users who want custom
-# config can still write the row by hand in their profile patch.
+# Two rows land in the profile's composition root:
+#   1. `compaction-basic` disabled — the host's own auto-compaction backend
+#      would otherwise register `ctx.compaction` at the root realm too, and
+#      only one provider per realm may own that service name. (On dsh
+#      0.1.0-rc.6+ the web-app bundle already ships this disable; the row is
+#      idempotent and keeps the plugin self-sufficient on every supported DSH.)
+#   2. `compaction-acp` — the ACP engine, mounted at the HOST plane, so its
+#      model tools (`compress`, `decompress`, `search_context`, `acp_status`),
+#      the `/acp` command, the advisory nudge, and the guidance section reach
+#      EVERY mode (standard / code / minimal / cordis / custom presets) of the
+#      profile the plugin was installed into.
+#
+# No `config` is set on purpose: the context window is auto-detected from the
+# model API (fallback 128000) and the built-in prompt copy is used. Users who
+# want custom config write a SAME-ID `compaction-acp` row in their profile's
+# own `cordis.patch.yml` — it overrides this row (see README).
+#
+# Shipped presets (standard / code / cordis) keep their realm-local
+# compaction-basic fallback (automatic pressure compression); minimal and
+# presets without a compaction realm use the host ACP engine directly.
+- id: compaction-basic
+  disabled: true
+
 - insert:
     - id: compaction-acp
-      name: 'billion-context-dsh'
+      name: 'billion-context-dsh'

package/dist/commands.d.ts

@@ -4,6 +4,6 @@
  * @module billion-context-dsh/commands
  */
 import type { CommandDefinition } from '@deepseek-ai/dsh-commands';
-import type { ToolEnvironment } from './tools.ts';
+import { type ToolEnvironment } from './tools.ts';
 /** Register the /acp command (idempotent per engine). */
 export declare function acpCommand(env: ToolEnvironment): CommandDefinition;

package/dist/index.js

@@ -3836,6 +3836,9 @@ function requireAgent(exec) {
   }
   return exec.agent;
 }
+async function resolveEffectiveWindow(env, agent) {
+  return env.windowFor === void 0 ? { limit: env.modelContextLimit, source: "explicit" } : await env.windowFor(agent);
+}
 var compressParameters = {
   // Tolerated wrapped-arguments form: some models emit
   // `{ "arguments": "{\"content\": [...]}" }` (double-nested) or
@@ -3947,7 +3950,8 @@ async function handleCompress(env, args, exec) {
   const coreMessages = allLogMessages(session);
   const surfaceMessages = eventsToCoreMessages(surfaceEventsOf(session));
   const tokenCount = resolveTokenCount(agent, surfaceMessages);
-  const config = kernelConfigFor(env);
+  const window = await resolveEffectiveWindow(env, agent);
+  const config = kernelConfigFor({ ...env, modelContextLimit: window.limit });
   const turn = env.kernel.processTurn({ messages: coreMessages, state, config, tokenCount });
   env.store.set(session, turn.state);
   const byRaw = turn.state.messageRefs.byRaw;
@@ -4231,7 +4235,8 @@ async function handleStatus(env, rawArgs, exec) {
   const coreMessages = allLogMessages(session);
   const surfaceMessages = eventsToCoreMessages(surface, toolNames);
   const tokenCount = resolveTokenCount(agent, surfaceMessages);
-  const config = kernelConfigFor(env);
+  const window = await resolveEffectiveWindow(env, agent);
+  const config = kernelConfigFor({ ...env, modelContextLimit: window.limit });
   const turn = env.kernel.processTurn({ messages: coreMessages, state, config, tokenCount });
   const statusMessages = eventsToCoreMessages(
     surface.filter((event) => !isCheckpointEvent(event)),
@@ -4304,6 +4309,7 @@ function windowSourceLabel(window) {
   if (window.source === "auto") {
     return `auto-detected from ${window.provider ?? "?"}/${window.model ?? "?"}`;
   }
+  if (window.probeFailed === true) return "default (auto-detection failed \u2014 restart to re-probe)";
   return "default (auto-detection unavailable)";
 }
 async function detectContextWindow(agent, provider, model) {
@@ -4327,7 +4333,7 @@ async function statusText(env, agent) {
   const coreMessages = allLogMessages(session);
   const surfaceMessages = eventsToCoreMessages(surfaceEventsOf(session));
   const estimated = resolveTokenCount(agent, surfaceMessages);
-  const window = env.windowFor === void 0 ? { limit: env.modelContextLimit, source: "explicit" } : await env.windowFor(agent);
+  const window = await resolveEffectiveWindow(env, agent);
   const limit = window.limit;
   const lines = [
     `ACP status \u2014 session ${session.id}`,
@@ -4336,6 +4342,9 @@ async function statusText(env, agent) {
     `  estimated context: ${estimated} / ${limit} (${Math.round(estimated / limit * 100)}%)`,
     `  context window: ${limit} (${windowSourceLabel(window)})`
   ];
+  if (window.probeFailed === true) {
+    lines.push(`  \u26A0 window auto-detection failed \u2014 using the ${limit} fallback (restart to re-probe, or set modelContextLimit explicitly)`);
+  }
   const state = structuredClone(env.store.stateFor(session));
   const config = kernelConfigFor({ ...env, modelContextLimit: limit });
   const turn = env.kernel.processTurn({ messages: coreMessages, state, config, tokenCount: estimated });
@@ -4569,7 +4578,14 @@ var AcpCompactionEngine = class extends CompactionEngine {
       window = { limit: DEFAULT_CONTEXT_WINDOW, source: "default", provider, model };
     } else {
       const detected = await detectContextWindow(agent, provider, model);
-      window = detected === null ? { limit: DEFAULT_CONTEXT_WINDOW, source: "default", provider, model } : { limit: detected, source: "auto", provider, model };
+      if (detected === null) {
+        this.ctx.logger.warn(
+          `billion-context-dsh: context-window auto-detection failed for ${provider}/${model} \u2014 using the ${DEFAULT_CONTEXT_WINDOW} fallback (restart to re-probe, or set modelContextLimit explicitly)`
+        );
+        window = { limit: DEFAULT_CONTEXT_WINDOW, source: "default", provider, model, probeFailed: true };
+      } else {
+        window = { limit: detected, source: "auto", provider, model };
+      }
     }
     this.windowCache.set(key, window);
     return window;