billion-context-dsh 0.1.0

package/LICENSE

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

@@ -0,0 +1,113 @@
+# billion-context-dsh
+
+**One billion, not one million.** [Active Context Pruning (ACP)](https://github.com/ranxianglei/acp-kernel) for the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — model-driven context management as a `CompactionEngine` backend.
+
+The model decides *when* and *what* to compress — not a hard limit. Long conversations stay lean while critical details (paths, decisions, errors) survive in high-fidelity summaries you can search and decompress.
+
+This is the DSH port of [billion-context-pi](https://github.com/ranxianglei/billion-context-pi) (the Pi coding-agent adapter). The compression kernel (`acp-kernel`) is reused verbatim; the adapter layer was rewritten against DSH's durable-surface model — see [docs/dsh-porting-verification.md](docs/dsh-porting-verification.md) for the verified mapping.
+
+## Upstream & credits
+
+This project is a **port/derivation** and stands on the shoulders of the following upstream work — all MIT licensed. **Thank you** to [ranxianglei](https://github.com/ranxianglei) and the DeepSeek Harness team for building these projects and making them open source:
+
+| Upstream | Author | Role |
+|---|---|---|
+| **[billion-context-pi](https://github.com/ranxianglei/billion-context-pi)** | [ranxianglei](https://github.com/ranxianglei) | The Pi coding-agent adapter this project ports to DeepSeek Harness; source of the adapter design, tool semantics, and this project's default configuration |
+| **[acp-kernel](https://github.com/ranxianglei/acp-kernel)** | [ranxianglei](https://github.com/ranxianglei) | Framework-agnostic context-compression engine — reused **verbatim** (refs, blocks, tiers, nudge decisions, search, status) |
+| **[opencode-acp](https://github.com/ranxianglei/opencode-acp)** | [ranxianglei](https://github.com/ranxianglei) | Origin of the ACP ("model decides when and what to compress") design |
+| **[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)** | DeepSeek AI | The host platform this project extends (compaction capability seam, agent presets, durable session log) |
+
+This project reuses `acp-kernel`'s compression core and `billion-context-pi`'s default behavior unchanged; the DSH adapter layer (session-event projection, durable surface transaction, model tools, nudge, config) is original work in this repository. Upstream copyright and licenses remain with their respective authors; see [LICENSE](LICENSE) for this project's terms.
+
+## How it works
+
+DSH derives every model request from its append-only session log (the *surface*). ACP semantics map onto that model directly:
+
+| ACP concept | DSH implementation |
+|---|---|
+| `compress` tool shadows a range | durable `surfaceOp: { op: 'replace' }` — the model-written summary becomes a checkpoint node; the originals stay in the log |
+| refs (`m00001` tags) | surface seqs, carried by the nudge's compressible-range table |
+| nudge ("you should compress") | injected at `agent/pre-step` by the kernel's pressure decision |
+| `decompress` | read-only recovery of shadowed originals from the log |
+| `search_context` | scores block summaries + originals rebuilt from the log |
+| `acp_status` | block ledger + context pressure |
+| block state | in-memory kernel state + **log-rebuilt ledger** (no sidecar files) |
+
+There is deliberately **no automatic summarization**: automatic policy only nudges the model (`compactIfNeeded` returns null). That is the ACP cost win — the model writes one dense summary instead of paying for a second LLM summarization call.
+
+## Install / mount
+
+The package is a drop-in compaction backend. Add one row to the host composition (or an agent preset's compaction realm):
+
+```yaml
+# host composition (e.g. profile cordis.patch.yml)
+- insert:
+    - id: compaction-billion-context
+      name: 'billion-context-dsh'
+      config:
+        modelContextLimit: 128000   # default; the pressure window
+```
+
+To replace `dsh-compaction-basic` for one agent, mount it inside the preset's `compaction` isolate realm instead:
+
+```yaml
+- id: compaction
+  name: cordis:group
+  group: true
+  isolate:
+    compaction: true
+  config:
+    - id: compaction-acp
+      name: 'billion-context-dsh'
+      config:
+        modelContextLimit: 128000
+```
+
+When the hosting context provides `ctx.tools` / `ctx.commands`, the engine also registers:
+
+- `compress` — replace ranges with dense summaries you write
+- `decompress` — recover a block's original content (read-only)
+- `search_context` — find information inside compressed blocks
+- `acp_status` — block ledger and pressure
+- `/acp` — status / compress / decompress from the command bar
+
+## Configuration
+
+| Key | Default | Meaning |
+|---|---|---|
+| `modelContextLimit` | `128000` | Context window used for the kernel's pressure decisions |
+| `nudgeMinContextLimitPct` | kernel default `0.45` | Nudge window lower bound (usage fraction) — same default as billion-context-pi |
+| `nudgeMaxContextLimitPct` | kernel default `0.75` | Over-limit line: above this the nudge fires regardless of growth |
+| `nudgeEmergencyThresholdPct` | kernel default `0.95` | Emergency nudge (bypasses the per-turn dedup) |
+| `coreOverrides` | — | Any other acp-kernel `Config` override (billion-context-pi's `coreOverrides` escape hatch) |
+| `autoTools` | `true` | Register the four model tools on `ctx.tools` |
+| `autoCommand` | `true` | Register the `/acp` command on `ctx.commands` |
+| `autoNudge` | `true` | Inject the nudge into `agent/pre-step` |
+
+## Development
+
+```bash
+npm install
+npm run typecheck   # strict TS
+npm test            # node --import tsx --test tests/*.test.ts
+npm run build       # tsup bundle (inlines acp-kernel) + .d.ts
+```
+
+`dist/index.js` is self-contained except for the `@deepseek-ai/*` seam packages, which the hosting deployment provides.
+
+## Architecture
+
+```
+src/
+├── index.ts      # AcpCompactionEngine (CompactionEngine backend) + wiring
+├── messages.ts   # M1: session events ↔ acp-kernel CoreMessage projection
+├── state.ts      # M2: per-session kernel state
+├── region.ts     # M5: durable region transaction + log-rebuilt block ledger
+├── tools.ts      # M3: compress / decompress / search_context / acp_status
+├── nudge.ts      # M4: kernel pressure decision → injected nudge message
+└── commands.ts   # M4: /acp slash command
+```
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,116 @@
+# billion-context-dsh
+
+[English](./README.md) | [中文](./README.zh-CN.md)
+
+**One billion, not one million（十亿，而非百万）。** 面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 [Active Context Pruning（ACP，主动上下文裁剪）](https://github.com/ranxianglei/acp-kernel)——以 `CompactionEngine` 后端形式提供的模型驱动上下文管理。
+
+由**模型自己决定何时压缩、压缩什么**——而不是一个硬性上限。长对话保持精简，关键细节（路径、决策、错误信息）以高保真摘要保留，且可搜索、可解压。
+
+这是 [billion-context-pi](https://github.com/ranxianglei/billion-context-pi)（Pi 编码代理适配器）在 DSH 上的移植。压缩内核（`acp-kernel`）原样复用；适配层针对 DSH 的 durable-surface（持久化表面）模型重写——验证过的映射关系见 [docs/dsh-porting-verification.md](docs/dsh-porting-verification.md)。
+
+## 上游项目与致谢
+
+本项目是一个**移植/派生项目**，站在以下上游工作的肩膀上——全部为 MIT 许可。**衷心感谢** [ranxianglei](https://github.com/ranxianglei) 和 DeepSeek Harness 团队创建并开源这些项目：
+
+| 上游项目 | 作者 | 角色 |
+|---|---|---|
+| **[billion-context-pi](https://github.com/ranxianglei/billion-context-pi)** | [ranxianglei](https://github.com/ranxianglei) | 本项目移植的 Pi 编码代理适配器；适配器设计、工具语义与本项目默认配置的来源 |
+| **[acp-kernel](https://github.com/ranxianglei/acp-kernel)** | [ranxianglei](https://github.com/ranxianglei) | 框架无关的上下文压缩引擎——**原样复用**（refs、blocks、tiers、nudge 决策、search、status） |
+| **[opencode-acp](https://github.com/ranxianglei/opencode-acp)** | [ranxianglei](https://github.com/ranxianglei) | ACP（"模型决定何时压缩、压缩什么"）设计的源头 |
+| **[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)** | DeepSeek AI | 本项目所扩展的宿主平台（compaction 能力接缝、agent preset、持久化会话日志） |
+
+本项目原样复用 `acp-kernel` 的压缩内核与 `billion-context-pi` 的默认行为；DSH 适配层（会话事件投影、持久化表面事务、模型工具、nudge、配置）为本仓库原创。上游版权与许可归其各自作者所有；本项目的许可条款见 [LICENSE](LICENSE)。
+
+## 工作原理
+
+DSH 的每个模型请求都派生自其 append-only 会话日志（*surface*）。ACP 语义直接映射到这一模型：
+
+| ACP 概念 | DSH 实现 |
+|---|---|
+| `compress` 工具遮蔽一段范围 | 持久化 `surfaceOp: { op: 'replace' }`——模型书写的摘要成为 checkpoint 节点；原文保留在日志中 |
+| refs（`m00001` 标签） | 表面 seq，由 nudge 的可压缩范围表携带 |
+| nudge（"你也许该压缩了"） | 由内核的压力决策在 `agent/pre-step` 注入 |
+| `decompress` | 从日志只读恢复被遮蔽的原文 |
+| `search_context` | 对从日志重建的块摘要与原文打分 |
+| `acp_status` | 块账本与上下文压力 |
+| 块状态 | 内存内核状态 + **日志重建账本**（无旁车文件） |
+
+刻意**不做自动摘要**：自动策略只 nudge 模型（`compactIfNeeded` 返回 null）。这正是 ACP 的成本优势——模型书写一份紧凑摘要，而不是为第二次 LLM 摘要调用付费。
+
+## 安装 / 挂载
+
+本包是即插即用的压缩后端。在宿主组合（或 agent preset 的 compaction realm）中添加一行：
+
+```yaml
+# 宿主组合（例如 profile 的 cordis.patch.yml）
+- insert:
+    - id: compaction-billion-context
+      name: 'billion-context-dsh'
+      config:
+        modelContextLimit: 128000   # 默认；压力窗口
+```
+
+要为某个 agent 替换 `dsh-compaction-basic`，改为挂载在 preset 的 `compaction` isolate realm 中：
+
+```yaml
+- id: compaction
+  name: cordis:group
+  group: true
+  isolate:
+    compaction: true
+  config:
+    - id: compaction-acp
+      name: 'billion-context-dsh'
+      config:
+        modelContextLimit: 128000
+```
+
+当宿主上下文提供 `ctx.tools` / `ctx.commands` 时，引擎还会注册：
+
+- `compress` — 用你书写的紧凑摘要替换范围
+- `decompress` — 恢复某块的原始内容（只读）
+- `search_context` — 在压缩块内查找信息
+- `acp_status` — 块账本与压力
+- `/acp` — 从命令栏执行 status / compress / decompress
+
+## 配置
+
+| 键 | 默认值 | 含义 |
+|---|---|---|
+| `modelContextLimit` | `128000` | 用于内核压力决策的上下文窗口 |
+| `nudgeMinContextLimitPct` | 内核默认 `0.45` | Nudge 窗口下界（用量占比）——与 billion-context-pi 相同的默认值 |
+| `nudgeMaxContextLimitPct` | 内核默认 `0.75` | 过限线：超过此值则无论增长与否都触发 nudge |
+| `nudgeEmergencyThresholdPct` | 内核默认 `0.95` | 紧急 nudge（绕过每轮去重） |
+| `coreOverrides` | — | 任何其他 acp-kernel `Config` 覆盖（billion-context-pi 的 `coreOverrides` 逃生口） |
+| `autoTools` | `true` | 在 `ctx.tools` 注册四个模型工具 |
+| `autoCommand` | `true` | 在 `ctx.commands` 注册 `/acp` 命令 |
+| `autoNudge` | `true` | 当内核建议时向 `agent/pre-step` 注入 nudge |
+
+## 开发
+
+```bash
+npm install
+npm run typecheck   # 严格 TS
+npm test            # node --import tsx --test tests/*.test.ts
+npm run build       # tsup 打包（内联 acp-kernel）+ .d.ts
+```
+
+`dist/index.js` 自包含，仅外链 `@deepseek-ai/*` 接缝包（由宿主部署提供）。
+
+## 架构
+
+```
+src/
+├── index.ts      # AcpCompactionEngine（CompactionEngine 后端）+ 接线
+├── messages.ts   # M1: 会话事件 ↔ acp-kernel CoreMessage 投影
+├── state.ts      # M2: 每会话内核状态
+├── region.ts     # M5: 持久化区域事务 + 日志重建块账本
+├── tools.ts      # M3: compress / decompress / search_context / acp_status
+├── nudge.ts      # M4: 内核压力决策 → 注入的建议式 nudge 消息
+├── system-prompt.ts # M4: ACP 指引系统提示段（一次性，不进 nudge）
+└── commands.ts   # M4: /acp 斜杠命令
+```
+
+## License
+
+MIT

package/dist/commands.d.ts

@@ -0,0 +1,9 @@
+/**
+ * M4 — the `/acp` slash command: a human-friendly window into the same
+ * machinery the model tools expose (status, one-shot compress, decompress).
+ * @module billion-context-dsh/commands
+ */
+import type { CommandDefinition } from '@deepseek-ai/dsh-commands';
+import type { ToolEnvironment } from './tools.ts';
+/** Register the /acp command (idempotent per engine). */
+export declare function acpCommand(env: ToolEnvironment): CommandDefinition;

package/dist/config.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Kernel configuration assembly — the DSH counterpart of billion-context-pi's
+ * `resolveConfig`: build acp-kernel's `Config` from adapter-level knobs.
+ *
+ * Defaults are deliberately the acp-kernel `defaultConfig` values (the same
+ * defaults billion-context-pi ships: nudge window 45%–75%, emergency 95%,
+ * growth ratio 5%, protected last messages 5). Every knob is optional — an
+ * omitted value keeps the kernel default, so the behavior matches the Pi
+ * adapter exactly unless a deployment opts out.
+ * @module billion-context-dsh/config
+ */
+import { type Config } from 'acp-kernel';
+/** The kernel-facing knobs shared by the nudge path and the compress tool. */
+export interface KernelConfigInput {
+    readonly modelContextLimit: number;
+    /** Nudge window lower bound (usage fraction). Kernel default: 0.45. */
+    readonly nudgeMinContextLimitPct?: number;
+    /** Nudge window upper bound — over-limit. Kernel default: 0.75. */
+    readonly nudgeMaxContextLimitPct?: number;
+    /** Emergency nudge threshold (bypasses per-turn dedup). Kernel default: 0.95. */
+    readonly nudgeEmergencyThresholdPct?: number;
+    /** Any other acp-kernel Config override (the billion-context-pi escape hatch). */
+    readonly coreOverrides?: Partial<Config>;
+}
+/**
+ * Assemble the kernel config: `defaultConfig(limit)` merged with the optional
+ * nudge thresholds (merged into the defaults, never replacing them wholesale)
+ * and any additional `coreOverrides`.
+ */
+export declare function kernelConfigFor(input: KernelConfigInput): Config;

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * billion-context-dsh — Active Context Pruning (ACP) for the DeepSeek Harness,
+ * delivered as a `CompactionEngine` backend.
+ *
+ * The model decides when and what to compress (pure ACP semantics):
+ *  - the `compress` tool durably shadows a surface range with the model-written
+ *    summary (no second LLM summarization call — the ACP cost win);
+ *  - the original events stay in the append-only session log, so `decompress`,
+ *    `search_context`, and replay always work;
+ *  - refs are surface seqs carried by the injected nudge's range table (DSH
+ *    has no in-memory message rewrite hook — see docs/dsh-porting-verification.md);
+ *  - automatic policy never summarizes by itself: it nudges the model.
+ *
+ * Mount it wherever a compaction backend is expected:
+ *
+ * ```yaml
+ * - id: compaction-billion-context
+ *   name: 'billion-context-dsh'
+ *   config:
+ *     modelContextLimit: 128000
+ * ```
+ *
+ * The package registers `ctx.compaction` plus the four model tools and the
+ * `/acp` command when the hosting composition provides `ctx.tools` /
+ * `ctx.commands`.
+ * @module billion-context-dsh
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { CompactionEngine, type CompactionAgentContext, type CompactionResult, type CompactionTrigger, type ManualCompactAgentContext } from '@deepseek-ai/dsh-compaction';
+import { type CompressionCore } from 'acp-kernel';
+import { AcpStateStore } from './state.ts';
+export { AcpStateStore } from './state.ts';
+export { kernelConfigFor, type KernelConfigInput } from './config.ts';
+export { ACP_SYSTEM_PROMPT, ACP_SYSTEM_PROMPT_ORDER } from './system-prompt.ts';
+export { makeTools, type ToolEnvironment } from './tools.ts';
+export { acpCommand } from './commands.ts';
+export { buildNudge, type NudgeEnvironment, type NudgeOutcome } from './nudge.ts';
+export { rebuildBlockLedger, resolveSurfaceRange, runCompactionTransaction, shadowedSeqsOf, findOpenTurn, assertNoActiveCompaction, type AcpBlockLedgerEntry, type CompactionTransactionInput, } from './region.ts';
+export { eventsToCoreMessages, projectEvent, surfaceEventsOf, extractEventText } from './messages.ts';
+export interface AcpConfig {
+    /** The context window used for pressure decisions. Default 128000. */
+    readonly modelContextLimit: number;
+    /** Nudge window lower bound (usage fraction). Kernel default 0.45 — same as billion-context-pi. */
+    readonly nudgeMinContextLimitPct?: number;
+    /** Nudge window upper bound (over-limit). Kernel default 0.75 — same as billion-context-pi. */
+    readonly nudgeMaxContextLimitPct?: number;
+    /** Emergency nudge threshold (bypasses per-turn dedup). Kernel default 0.95 — same as billion-context-pi. */
+    readonly nudgeEmergencyThresholdPct?: number;
+    /** Any other acp-kernel Config override (billion-context-pi's `coreOverrides` escape hatch). */
+    readonly coreOverrides?: Partial<import('acp-kernel').Config>;
+    /** Register the four model tools on `ctx.tools`. Default true. */
+    readonly autoTools: boolean;
+    /** Register the `/acp` command on `ctx.commands`. Default true. */
+    readonly autoCommand: boolean;
+    /** Inject the nudge into `agent/pre-step` when the kernel recommends it. Default true. */
+    readonly autoNudge: boolean;
+}
+export declare function resolveAcpConfig(config?: Partial<AcpConfig>): AcpConfig;
+/**
+ * The ACP compaction backend. Subclasses the seam exactly like
+ * `dsh-compaction-basic`; swaps summarization-driven compaction for
+ * model-driven block compression without touching the agent loop.
+ */
+export declare class AcpCompactionEngine extends CompactionEngine {
+    /** The framework-agnostic ACP compression core, reused verbatim. */
+    readonly kernel: CompressionCore;
+    /** Per-session kernel state. */
+    readonly store: AcpStateStore;
+    /** Resolved engine configuration. */
+    readonly config: AcpConfig;
+    private readonly lastNudgeTurn;
+    constructor(ctx: Context, config?: Partial<AcpConfig>);
+    /** ACP is model-driven: automatic pressure policy never summarizes by itself. */
+    compactIfNeeded(_agent: CompactionAgentContext, _trigger: CompactionTrigger, signal: AbortSignal): Promise<CompactionResult | null>;
+    /** Explicit idle-session compaction: ACP leaves the decision to the model. */
+    compactNow(_agent: ManualCompactAgentContext, signal: AbortSignal): Promise<CompactionResult | null>;
+    /**
+     * The model-driven path lands through the `compress` tool, which runs the
+     * full durable transaction directly. This seam method rejects with guidance:
+     * automatic summarization is exactly what ACP replaces.
+     */
+    compactRegion(_start: number, _end: number, _agent: CompactionAgentContext, signal?: AbortSignal): Promise<CompactionResult>;
+}
+export default AcpCompactionEngine;