billion-context-omp 0.1.0 → 0.1.2

package/README.md

@@ -1,61 +1,199 @@
+# billion-context-omp
+
 [English](./README.md) | [中文](./README.zh-CN.md)
 
-# billion-context-omp
+<p align="center">
+<strong>Billion-Context</strong> for <a href="https://github.com/can1357/oh-my-pi">omp (oh-my-pi)</a>
+<br />
+The model decides <em>when</em> and <em>what</em> to compress — not a hard limit.
+</p>
+
+---
+
+<p align="center">
+<a href="https://www.npmjs.com/package/billion-context-omp"><img src="https://img.shields.io/npm/v/billion-context-omp.svg?style=flat-square" alt="npm"></a>
+<a href="https://github.com/ranxianglei/billion-context-omp/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/billion-context-omp.svg?style=flat-square" alt="license"></a>
+<a href="https://github.com/ranxianglei/billion-context-omp"><img src="https://img.shields.io/badge/GitHub-ranxianglei%2Fbillion--context--omp-181717?style=flat-square&logo=github" alt="GitHub"></a>
+</p>
 
-[oh-my-pi (omp)](https://github.com/can1357/oh-my-pi) client extension for [billion-context](https://www.npmjs.com/package/billion-context).
+<p align="center">
+<code>omp install billion-context-omp</code>
+</p>
 
-`billion-context` is a Node.js proxy that sits between any AI agent and its model API, rewriting Anthropic/OpenAI streams with [acp-kernel](https://github.com/ranxianglei/acp-kernel) compression. `billion-context-omp` wires **omp** — the terminal coding agent — into that pipeline: it builds the `base_url` override that routes omp's traffic through a running `billion-context` proxy, and **self-disables when it detects omp is already behind bili** so two layers of compression never stack.
+---
 
-> ⚠️ This is a **skeleton** package. The config-building helpers are placeholders.
-> Wire them to omp's actual provider/`base_url` config shape as you build it out.
+## Why?
 
-## Why
+When conversations get long, the model runs out of context. Most tools hard-truncate — silently dropping earlier messages. **billion-context** gives the model a `compress` tool: the LLM decides **when** and **what** to compress into high-fidelity summaries, preserving critical details (file paths, decisions, error strings) while reclaiming context space.
 
-Long coding sessions blow up context. Once you pass the context window the session degrades or dies, and every provider charges per token. Compression lets a single session run for days — billions of tokens through one window.
+Unlike omp's built-in auto-compaction (which replaces everything with a single summary), billion-context:
+- **Preserves structure** — compressed ranges become labeled blocks you can decompress later
+- **Multi-tier** — summaries can be further distilled (T1 → T2 → T3) as sessions grow
+- **Searchable** — `search_context` finds information inside compressed blocks without decompressing
+- **Selective** — protected tools, user messages, and the recent working set are never compressed
 
-omp already supports arbitrary providers and custom `base_url`. This package is the thin glue that points those `base_url`s at a bili proxy and keeps the `/bili/` self-detection signal consistent with the rest of the billion-context client family (`billion-context-pi`, `opencode-acp`, …).
+This means:
+
+1. **A single session handles enormous workloads.** Per simulation tests of the three-tier architecture (see [opencode-acp](https://github.com/ranxianglei/opencode-acp)), one session can process on the order of 10–60 billion cumulative tokens — while retaining long-term memory of distant key information (paths, decisions, signatures). You can work in the **same session for months** without outgrowing the context.
+2. **Context stays lean over the long run.** In practice context typically holds under ~150K tokens (opencode-acp keeps it under ~200K), so compared to traditional compaction that lets context balloon toward 1M, **a single session costs roughly 5× less in tokens**.
 
 ## Install
 
 ```bash
-npm install billion-context-omp
+omp install billion-context-omp
 ```
 
-## Quickstart
+That's it. The extension auto-loads on next omp startup. No configuration needed — it reads your model's context window automatically.
+
+Or add it to your omp settings (`~/.omp/agent/settings.json` or project `.omp/settings.json`):
 
-```ts
-import { BillionContextOmp } from 'billion-context-omp';
+```jsonc
+{
+  "extensions": ["billion-context-omp"]
+}
+```
 
-const omp = new BillionContextOmp({ endpoint: 'http://localhost:8787' });
+## How it works
 
-// Route a provider through bili:
-omp.buildBaseUrl('https://api.openai.com/v1');
-// => 'http://localhost:8787/bili/https://api.openai.com/v1'
+billion-context intercepts omp's `context` event (fired before each LLM call) and runs the acp-kernel pipeline:
 
-// Detect an already-routed URL (use to self-disable / avoid double compression):
-omp.isBiliBaseUrl('http://localhost:8787/bili/https://api.openai.com/v1'); // => true
 ```
+assign refs → fold in-stream compress calls → prune → nudge → emergency truncate
+```
+
+Each message gets an invisible `<acp>` ref tag (`m00001`, `m00002`, ...) visible to the model but not the user. The model uses these refs to specify compression ranges.
 
-## API
+**The session stream is the single source of truth.** Compress calls live in the stream itself: every compress tool call's arguments (ranges + summaries) are re-applied deterministically on each LLM call, on restart, and on resume — no sidecar state file to drift out of sync. Position ids (`p1..pN`) and model-facing refs (`m00001..`) are re-derived from the stream every turn; prefix rewrites (retry, rewind, host compaction) are detected and safely re-folded, with fingerprint guards against replaying a call onto the wrong messages.
 
-### `new BillionContextOmp(options?)`
+omp's built-in `/compact` is intercepted and replaced by an ACP model-summarized compaction that also preserves prior compress-call summaries — nothing is lost to the gap between the summary and the kept entries.
+
+## Plugin compatibility
+
+**Keep exactly one context-compression plugin installed.** If two compression extensions both rewrite the message list, they clobber each other's work — compressed ranges can be re-expanded or corrupted. omp's own `/compact` is already intercepted automatically by billion-context-omp, but any *third-party* compression/compaction extension should be uninstalled.
+
+## Model-facing tools
+
+| Tool | What it does |
+|------|-------------|
+| `compress` | Replace a contiguous message range with a detailed summary |
+| `decompress` | Restore a previously compressed block's content (to file by default; `inline:true` for single messages) |
+| `search_context` | Search compressed block summaries (and visible messages) by keyword |
+| `acp_status` | Show context usage, compressed blocks, compressible ranges |
+
+> The `acp_delegate` sub-agent subsystem from the Pi build is intentionally **not** registered — omp ships its own multi-agent orchestration, and duplicate delegation tools would conflict.
+
+## `/acp` command
+
+Rich status display for the user:
+
+```
+╭─────────────────────────────────────────────╮
+│           ACP Context Analysis              │
+╰─────────────────────────────────────────────╯
+ billion-context-omp@0.1.1
+
+ Context: 6% (57k / 1.0M)
+
+ Token Breakdown:
+   SysPrompt  ██░░░░░░░░░░░░░░░░░░  10%  5.9k
+   Framework  ██████████████████░░  90%  51k
+
+ Nudge: idle — max compressible 0 < threshold 20000; growth 0 < floor 20000
+
+ Blocks: 2 active / 2 total (21k tokens compressed)
+   [b1] T1 5.1k→1.0k: Fold architecture port
+   [b2] T1 15k→799: Replay guard hardening
+
+ Tag visibility: tags injected to LLM only (deep copy), not persisted in session, not shown in terminal.
+```
+
+## Configuration
+
+billion-context-omp works out of the box with no configuration. Optional keys can be set in a JSON config file.
+
+### Config file
+
+Create `~/.omp/acp-omp.json` (global) and/or `<project>/.omp/acp-omp.json` (project-local, overrides global):
+
+```json
+{
+  "debug": false,
+  "autoUpdate": true,
+  "modelContextLimit": 200000,
+  "compressModel": "zhipuai:glm-5.2",
+  "toolBashDefaultTimeout": 60,
+  "toolOutputMaxBytes": 200000,
+  "compress": {
+    "maxContextLimit": "75%",
+    "emergencyThresholdPercent": "95%",
+    "nudgeGrowthTokens": 50000
+  },
+
+  "prompts": {
+    "compressPhilosophy": "Override the compression philosophy...",
+    "howToCompressRules": "Override tier-1 rules...",
+    "tier2DistillRules": "Override tier-2 distillation rules...",
+    "tier3CondenseRules": "Override tier-3 condensation rules..."
+  },
+  "acknowledgePromptsRisk": true
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `debug` | `false` | Enable verbose **debug-level** events in the log. The always-on log (lifecycle events, errors, warnings) is written regardless; `debug` only adds extra diagnostics. Also enabled by env `ACP_DEBUG=1`. |
+| `autoUpdate` | `true` | On session start (throttled to one check per 3 minutes), check npm for a newer version and auto-install it. Disable to avoid all startup network calls. |
+| `modelContextLimit` | *(auto)* | Override the context limit (in tokens). Defaults to the model's `contextWindow`. |
+| `compressModel` | *(session model)* | `provider:modelId` used for `/compact` model-summarized compaction (e.g. `"zhipuai:glm-5.2"`). Defaults to the current session model when omitted. |
+| `toolBashDefaultTimeout` | `60` | Seconds injected into the `bash` tool when the model omits `timeout`. Without this a forgotten timeout can hang for thousands of seconds. `0` restores unbounded behavior. |
+| `toolOutputMaxBytes` | `200000` | Hard byte cap on tool result text (applied via the `tool_result` hook). Stops runaway output that omp's own caps can't catch. When it fires the model is told where the full output lives; set lower (e.g. `8192`) for a tighter context budget, or `0` to disable. |
+| `compress.maxContextLimit` | `"75%"` | Context usage threshold that triggers **forced compression** nudges (bypasses growth-gate + cadence). Accepts a ratio (`0.75`) or percent string (`"75%"`). Lower = compress earlier / more aggressively. |
+| `compress.emergencyThresholdPercent` | `"95%"` | Context usage threshold that triggers **emergency truncation** of large tool outputs to keep the session alive. Must be ≥ `maxContextLimit`. |
+| `compress.nudgeGrowthTokens` | `50000` | Token growth step for soft compression nudges. A nudge fires roughly every time this many tokens become compressible; if the model ignores it, it re-fires after the same amount of further growth. Lower = compress more often. |
+| `prompts` | *(kernel defaults)* | Override acp-kernel's 4 load-bearing compression prompt rules (`compressPhilosophy`, `howToCompressRules`, `tier2DistillRules`, `tier3CondenseRules`). Each set field replaces the default verbatim; omitted fields are inherited. Requires `acknowledgePromptsRisk: true`. |
+| `acknowledgePromptsRisk` | `false` | Safety gate for `prompts` overrides. Set `true` to acknowledge that replacing the tuned compression rules may reduce summary quality, and to make overrides take effect. |
+
+The three nudge thresholds (`maxContextLimit`, `emergencyThresholdPercent`, `nudgeGrowthTokens`) form a three-tier escalation: growth-driven soft nudges → forced nudges at `maxContextLimit` → emergency truncation at `emergencyThresholdPercent`.
+
+### Environment variables
+
+| Variable | Effect |
+|----------|--------|
+| `ACP_AUTO_UPDATE` | Set to `0` / `false` / `no` / `off` (case-insensitive) to disable auto-update, overriding the config. |
+| `ACP_MODEL_CONTEXT_LIMIT` | Override the context limit. Takes precedence over the config value. |
+| `ACP_DEBUG` | Set to `1` or `true` to enable debug-level logging (always-on events are written regardless). |
+| `ACP_LOG_FILE` | Override the log file path (default `~/.omp/acp-omp.log`). |
+
+### Logging
+
+billion-context-omp writes a structured, always-on log to `~/.omp/acp-omp.log` (override with `ACP_LOG_FILE`). It covers the model's whole working session and is useful for diagnosing problems:
+
+- **Always written** (even with `debug: false`): `error`, `warn`, `info` levels — session start, every context turn (token usage / nudge decision), compress/decompress, and **all errors and warnings**. Error lines include the message and stack trace.
+- **Written only when `debug: true`**: verbose `debug`-level diagnostics (full field dumps, per-turn internals, fold/replay events).
+
+Each line: `<ISO timestamp> [<level>] [<scope>] key=value key=value`. The file rotates to `~/.omp/acp-omp.log.old` at 10 MB.
+
+```sh
+tail -f ~/.omp/acp-omp.log                 # watch the session live
+grep '\[error\]' ~/.omp/acp-omp.log        # surface every recorded failure
+```
 
-| option     | type     | description                              |
-| ---------- | -------- | ---------------------------------------- |
-| `endpoint` | `string` | Origin of a running billion-context proxy. |
+### Compression philosophy
 
-### `omp.buildBaseUrl(upstream): string`
+The model receives detailed guidance (in its system prompt) on **when** to compress, **what** to keep verbatim (paths, signatures, errors, decisions, user intent), and **what** to drop (verbose logs, duplicates, consumed exploration). This guidance is injected on every turn so it stays in the model's attention.
 
-Wrap an upstream `base_url` as `${endpoint}/bili/${upstream}`. Throws if no endpoint is configured. Passes through unchanged if already routed.
+### What gets protected
 
-### `omp.isBiliBaseUrl(baseUrl): boolean`
+billion-context protects three categories of content from compression:
 
-True when the URL already carries the `/bili/` prefix — use this to self-disable when omp's `base_url` is already pointing at bili.
+1. **Always-protected tools** — `compress` calls are hard-protected (they're load-bearing metadata; compressing them breaks decompress and the "summary is historical" contract).
+2. **Soft recent-zone** — the last N messages (default 5) and last ~5K tokens are soft-protected so the model keeps its working set. Tool results from `decompress`, `search_context`, `read`, and `bash` are **excluded** from this zone: they're large and meant to be compressible once consumed.
+3. **Last user message** — always protected (user intent must survive).
 
-### `omp.buildConfig(providers): Record<provider, { base_url }>`
+## Built on acp-kernel
 
-Build base_url overrides for multiple omp providers at once. _(Skeleton.)_
+The compression engine is [`acp-kernel`](https://github.com/ranxianglei/acp-kernel) — a platform-agnostic, MIT-licensed library. It's bundled inline into `dist/index.js`, so there are zero runtime dependencies.
 
 ## License
 
-MIT © [ranxianglei](https://github.com/ranxianglei)
+MIT © ranxianglei

package/README.zh-CN.md

@@ -2,60 +2,198 @@
 
 # billion-context-omp
 
-[oh-my-pi (omp)](https://github.com/can1357/oh-my-pi) 的 [billion-context](https://www.npmjs.com/package/billion-context) 客户端扩展。
+<p align="center">
+面向 <a href="https://github.com/can1357/oh-my-pi">omp (oh-my-pi)</a> 的 <strong>Billion-Context</strong>
+<br />
+由模型决定<em>何时</em>压缩、<em>压缩什么</em> —— 而不是硬截断。
+</p>
 
-`billion-context` 是一个 Node.js 代理,架在任意 AI 助手与其模型 API 之间,用 [acp-kernel](https://github.com/ranxianglei/acp-kernel) 压缩重写 Anthropic/OpenAI 流。`billion-context-omp` 把 **omp** —— 终端编程助手 —— 接入这条链路:它生成 `base_url` 覆盖,把 omp 的流量路由到运行中的 `billion-context` 代理,并在**检测到 omp 已经位于 bili 之后时自动停用**,避免两层压缩叠加。
+---
 
-> ⚠️ 这是一个**骨架**包,配置构建辅助函数目前是占位实现。
-> 请按 omp 实际的 provider / `base_url` 配置形态对接后再行扩展。
+<p align="center">
+<a href="https://www.npmjs.com/package/billion-context-omp"><img src="https://img.shields.io/npm/v/billion-context-omp.svg?style=flat-square" alt="npm"></a>
+<a href="https://github.com/ranxianglei/billion-context-omp/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/billion-context-omp.svg?style=flat-square" alt="license"></a>
+<a href="https://github.com/ranxianglei/billion-context-omp"><img src="https://img.shields.io/badge/GitHub-ranxianglei%2Fbillion--context--omp-181717?style=flat-square&logo=github" alt="GitHub"></a>
+</p>
 
-## 为什么
+<p align="center">
+<code>omp install billion-context-omp</code>
+</p>
 
-长编程会话会把上下文撑爆。一旦超过上下文窗口,会话质量下降甚至崩掉,而各家 provider 按 token 计费。压缩能让**一个会话连跑数天** —— 海量 token 穿过同一个窗口。
+---
 
-omp 本就支持任意 provider 和自定义 `base_url`。本包提供薄薄一层胶水,把这些 `base_url` 指向 bili 代理,并保持 `/bili/` 自检信号与 billion-context 客户端家族(`billion-context-pi`、`opencode-acp` 等)一致。
+## 为什么？
+
+会话变长后，模型的上下文会耗尽。多数工具采用硬截断——悄悄丢弃早期消息。**billion-context** 给模型一个 `compress` 工具：由 LLM 自己决定**何时**压缩、**压缩什么**，生成高保真摘要，保留关键细节（文件路径、决策、报错原文）的同时回收上下文空间。
+
+与 omp 内置的自动 compaction（把一切都换成一条摘要）不同，billion-context：
+- **保留结构** —— 被压缩的区间变成带标签的块，之后可以解压还原
+- **多层蒸馏** —— 摘要可随会话增长继续蒸馏（T1 → T2 → T3）
+- **可搜索** —— `search_context` 不解压即可在压缩块摘要中检索信息
+- **有选择性** —— 受保护工具、用户消息、近期工作集永不被压缩
+
+这意味着：
+
+1. **单个会话可以承载巨大的工作量。** 三层架构的模拟测试（见 [opencode-acp](https://github.com/ranxianglei/opencode-acp)）显示，一个会话可处理 100~600 亿累计 token——同时保持对早期关键信息（路径、决策、签名）的长期记忆。你可以在**同一个会话里工作数月**而不会撑爆上下文。
+2. **上下文长期保持精瘦。** 实际运行中上下文通常保持在 ~150K token 以下（opencode-acp 控制在 ~200K 以下）。相比放任上下文膨胀到 1M 的传统 compaction，**单个会话的 token 成本约低 5 倍**。
 
 ## 安装
 
 ```bash
-npm install billion-context-omp
+omp install billion-context-omp
 ```
 
-## 快速开始
+就这一步。扩展在下次 omp 启动时自动加载，无需任何配置——它自动读取模型的上下文窗口。
 
-```ts
-import { BillionContextOmp } from 'billion-context-omp';
+或加入 omp 设置（`~/.omp/agent/settings.json` 或项目级 `.omp/settings.json`）：
 
-const omp = new BillionContextOmp({ endpoint: 'http://localhost:8787' });
+```jsonc
+{
+  "extensions": ["billion-context-omp"]
+}
+```
 
-// 让某个 provider 走 bili:
-omp.buildBaseUrl('https://api.openai.com/v1');
-// => 'http://localhost:8787/bili/https://api.openai.com/v1'
+## 工作原理
 
-// 检测已路由的 URL(用于自我停用 / 避免双重压缩):
-omp.isBiliBaseUrl('http://localhost:8787/bili/https://api.openai.com/v1'); // => true
+billion-context 拦截 omp 的 `context` 事件（每次 LLM 调用前触发）并运行 acp-kernel 管线：
+
+```
+分配 ref → 折叠流内 compress 调用 → 剪枝 → 提醒 → 紧急截断
 ```
 
-## API
+每条消息获得一个模型可见、用户不可见的 `<acp>` ref 标签（`m00001`、`m00002`、...）。模型用这些 ref 指定压缩区间。
+
+**会话流是唯一真相源。** compress 调用本身就存在于流中：每次 compress 工具调用的参数（区间 + 摘要）在每次 LLM 调用、重启、resume 时被确定性重放——没有会漂移失步的独立状态文件。位置 id（`p1..pN`）和面向模型的 ref（`m00001..`）每轮从流重新推导；前缀改写（retry、rewind、宿主 compaction）会被检测并安全重折叠，指纹守卫防止把调用重放到错误的消息上。
+
+omp 内置的 `/compact` 被拦截，替换为 ACP 模型摘要式 compaction，它同时保留之前的 compress 调用摘要——摘要与保留条目之间的空隙不会丢任何东西。
+
+## 插件兼容性
+
+**只安装一个上下文压缩插件。** 若两个压缩扩展都改写消息列表，它们会互相破坏对方的工作——被压缩的区间可能被重新展开或损坏。omp 自己的 `/compact` 已被 billion-context-omp 自动拦截，但任何*第三方*压缩/compaction 扩展都应卸载。
+
+## 面向模型的工具
+
+| 工具 | 作用 |
+|------|------|
+| `compress` | 把一段连续消息区间替换为详细摘要 |
+| `decompress` | 恢复之前压缩的块内容（默认写文件；单条消息可 `inline:true`） |
+| `search_context` | 按关键字搜索压缩块摘要（及可见消息） |
+| `acp_status` | 显示上下文用量、压缩块、可压缩区间 |
+
+> Pi 版中的 `acp_delegate` 子代理系统在此**有意不注册**——omp 自带多代理编排，重复的委派工具会冲突。
+
+## `/acp` 命令
+
+面向用户的富状态面板：
+
+```
+╭─────────────────────────────────────────────╮
+│           ACP Context Analysis              │
+╰─────────────────────────────────────────────╯
+ billion-context-omp@0.1.1
 
-### `new BillionContextOmp(options?)`
+ Context: 6% (57k / 1.0M)
+
+ Token Breakdown:
+   SysPrompt  ██░░░░░░░░░░░░░░░░░░  10%  5.9k
+   Framework  ██████████████████░░  90%  51k
+
+ Nudge: idle — max compressible 0 < threshold 20000; growth 0 < floor 20000
+
+ Blocks: 2 active / 2 total (21k tokens compressed)
+   [b1] T1 5.1k→1.0k: Fold architecture port
+   [b2] T1 15k→799: Replay guard hardening
+
+ Tag visibility: tags injected to LLM only (deep copy), not persisted in session, not shown in terminal.
+```
+
+## 配置
+
+billion-context-omp 开箱即用，无需配置。可选键写入 JSON 配置文件。
+
+### 配置文件
+
+创建 `~/.omp/acp-omp.json`（全局）和/或 `<项目>/.omp/acp-omp.json`（项目级覆盖全局）：
+
+```json
+{
+  "debug": false,
+  "autoUpdate": true,
+  "modelContextLimit": 200000,
+  "compressModel": "zhipuai:glm-5.2",
+  "toolBashDefaultTimeout": 60,
+  "toolOutputMaxBytes": 200000,
+  "compress": {
+    "maxContextLimit": "75%",
+    "emergencyThresholdPercent": "95%",
+    "nudgeGrowthTokens": 50000
+  },
+
+  "prompts": {
+    "compressPhilosophy": "覆盖压缩哲学...",
+    "howToCompressRules": "覆盖 tier-1 规则...",
+    "tier2DistillRules": "覆盖 tier-2 蒸馏规则...",
+    "tier3CondenseRules": "覆盖 tier-3 凝缩规则..."
+  },
+  "acknowledgePromptsRisk": true
+}
+```
+
+| 键 | 默认 | 说明 |
+|-----|------|------|
+| `debug` | `false` | 开启**debug 级**详细日志事件。常开日志（生命周期事件、错误、警告）无论如何都会写；`debug` 只增加诊断信息。也可用环境变量 `ACP_DEBUG=1` 开启。 |
+| `autoUpdate` | `true` | 会话启动时（节流为每 3 分钟最多一次）检查 npm 是否有新版本并自动安装。关闭可避免所有启动期网络请求。 |
+| `modelContextLimit` | *(自动)* | 覆盖上下文上限（token 数）。默认取模型的 `contextWindow`。 |
+| `compressModel` | *(会话模型)* | `/compact` 模型摘要式压缩使用的 `provider:modelId`（如 `"zhipuai:glm-5.2"`）。缺省用当前会话模型。 |
+| `toolBashDefaultTimeout` | `60` | 模型省略 `timeout` 时注入 `bash` 工具的秒数。没有它，一次忘记的 timeout 可能挂起数千秒。`0` 恢复无限制。 |
+| `toolOutputMaxBytes` | `200000` | 工具结果文本的硬字节上限（经 `tool_result` 钩子实施）。拦截 omp 自身上限管不住的失控输出。触发时模型会被告知完整输出在哪；调低（如 `8192`）可更省上下文，`0` 禁用。 |
+| `compress.maxContextLimit` | `"75%"` | 触发**强制压缩**提醒的上下文用量阈值（绕过增长门控与节拍）。接受比例（`0.75`）或百分比字符串（`"75%"`）。越低 = 越早/越激进压缩。 |
+| `compress.emergencyThresholdPercent` | `"95%"` | 触发**紧急截断**（截断失控工具输出以保住会话）的上下文用量阈值。必须 ≥ `maxContextLimit`。 |
+| `compress.nudgeGrowthTokens` | `50000` | 软压缩提醒的 token 增长步长。每积累约这么多可压缩 token 就提醒一次；模型无视则再增长同等数量后重新提醒。越低 = 越常压缩。 |
+| `prompts` | *(kernel 默认)* | 覆盖 acp-kernel 的 4 条承重压缩提示规则（`compressPhilosophy`、`howToCompressRules`、`tier2DistillRules`、`tier3CondenseRules`）。每个设置的字段逐字替换默认值；未设置的字段继承默认。需要 `acknowledgePromptsRisk: true`。 |
+| `acknowledgePromptsRisk` | `false` | `prompts` 覆盖的安全门。设 `true` 表示知悉替换调优过的压缩规则可能降低摘要质量，并使覆盖生效。 |
+
+三个提醒阈值（`maxContextLimit`、`emergencyThresholdPercent`、`nudgeGrowthTokens`）构成三级升级：增长驱动的软提醒 → `maxContextLimit` 处的强制提醒 → `emergencyThresholdPercent` 处的紧急截断。
+
+### 环境变量
+
+| 变量 | 效果 |
+|------|------|
+| `ACP_AUTO_UPDATE` | 设为 `0` / `false` / `no` / `off`（不区分大小写）禁用自动更新，覆盖配置。 |
+| `ACP_MODEL_CONTEXT_LIMIT` | 覆盖上下文上限。优先于配置值。 |
+| `ACP_DEBUG` | 设为 `1` 或 `true` 开启 debug 级日志（常开事件无论如何都写）。 |
+| `ACP_LOG_FILE` | 覆盖日志文件路径（默认 `~/.omp/acp-omp.log`）。 |
+
+### 日志
+
+billion-context-omp 向 `~/.omp/acp-omp.log`（可用 `ACP_LOG_FILE` 覆盖）写入结构化的常开日志，覆盖模型整个工作会话，适合诊断问题：
+
+- **始终写入**（即使 `debug: false`）：`error`、`warn`、`info` 级——会话启动、每个 context 轮次（token 用量/提醒决策）、压缩/解压，以及**全部错误和警告**。错误行含消息与堆栈。
+- **仅在 `debug: true` 时写入**：冗长的 `debug` 级诊断（完整字段转储、每轮内部状态、折叠/重放事件）。
+
+每行格式：`<ISO 时间戳> [<级别>] [<作用域>] key=value key=value`。文件在 10 MB 时轮转为 `~/.omp/acp-omp.log.old`。
+
+```sh
+tail -f ~/.omp/acp-omp.log                 # 实时观察会话
+grep '\[error\]' ~/.omp/acp-omp.log        # 列出所有已记录的失败
+```
 
-| 选项       | 类型     | 说明                              |
-| ---------- | -------- | --------------------------------- |
-| `endpoint` | `string` | 运行中的 billion-context 代理地址。 |
+### 压缩哲学
 
-### `omp.buildBaseUrl(upstream): string`
+模型（在其系统提示中）收到详细指引：**何时**压缩、**什么**必须逐字保留（路径、签名、报错、决策、用户意图）、**什么**该丢弃（冗长日志、重复内容、已消费的探索）。该指引每轮注入，保持在模型注意力内。
 
-把上游 `base_url` 包成 `${endpoint}/bili/${upstream}`。未配置 endpoint 时抛错。若已是路由过的 URL 则原样返回。
+### 受保护的内容
 
-### `omp.isBiliBaseUrl(baseUrl): boolean`
+billion-context 保护三类内容不被压缩：
 
-URL 含 `/bili/` 前缀时返回 true —— omp 的 `base_url` 已指向 bili 时用此方法自我停用。
+1. **永久保护的工具** —— `compress` 调用被硬保护（它们是承重元数据；压缩它们会破坏 decompress 与"摘要属于历史"的契约）。
+2. **软性近期区** —— 最后 N 条消息（默认 5 条）与最后约 5K token 被软保护，模型保持工作集。`decompress`、`search_context`、`read`、`bash` 的工具结果**排除**在该区之外：它们体量大、消费后本就该可压缩。
+3. **最后一条用户消息** —— 永久保护（用户意图必须存活）。
 
-### `omp.buildConfig(providers): Record<provider, { base_url }>`
+## 基于 acp-kernel
 
-一次性为多个 omp provider 生成 base_url 覆盖。_(骨架。)_
+压缩引擎是 [`acp-kernel`](https://github.com/ranxianglei/acp-kernel)——平台无关的 MIT 库。它被内联打包进 `dist/index.js`，因此零运行时依赖。
 
-## License
+## 许可
 
-MIT © [ranxianglei](https://github.com/ranxianglei)
+MIT © ranxianglei

package/dist/auto-compress.d.ts

@@ -0,0 +1,65 @@
+import { complete } from "@oh-my-pi/pi-ai";
+import type { ExtensionContext } from "@oh-my-pi/pi-coding-agent";
+import { type CoreMessage, type CompressionState, type CompressibleRange, type Prompts } from "acp-kernel";
+import { type AgentMessage } from "./messages.js";
+/** Reads `compressModel` from `~/.<CONFIG_DIR_NAME>/acp-omp.json as `provider:modelId`. */
+export declare function readCompressModel(): string | null;
+export declare function resolveCompressModel<T extends {
+    provider: string;
+    id: string;
+}>(registry: {
+    find(provider: string, modelId: string): T | undefined;
+}, currentModel: T | undefined, configured: string | null): {
+    model: T;
+    label: string;
+} | null;
+export declare function sliceRange(messages: CoreMessage[], state: CompressionState, startRef: string, endRef: string): CoreMessage[];
+/** Pick the compressible span to compress. The kernel's recommended ranges are
+ *  small groups (split at user boundaries and protected gaps) that routinely
+ *  fall below `minCompressRange`, which the kernel would reject. Seed on the
+ *  largest range and expand to adjacent ranges (smallest gap first) until the
+ *  span covers enough text — counting every message in the span, matching the
+ *  kernel's own validation. Returns null when even the whole compressible set
+ *  is below the threshold. */
+export declare function selectRangeSpan(ranges: CompressibleRange[], messages: CoreMessage[], state: CompressionState, minChars: number): {
+    startRef: string;
+    endRef: string;
+    tokens: number;
+} | null;
+export declare function formatSlice(slice: CoreMessage[], state: CompressionState): string;
+export declare function parseSummary(text: string): string | null;
+/** Build the summary-generation system prompt FROM the kernel's load-bearing
+ *  compression rules (the same `Prompts` the compress tool and tier-1
+ *  compression use), so /compact honors `acp-omp.json` prompt overrides and stays
+ *  consistent with the rest of the ACP pipeline. `/compact` compresses an old
+ *  contiguous range, so the tier-1 `howToCompressRules` are the right rule
+ *  set (not tier-2/tier-3 distillation rules). */
+export declare function buildSummaryPrompt(prompts: Prompts): string;
+/** Generate ONE summary covering the FULL set of messages omp is about to
+ *  discard on /compact (messagesToSummarize + turnPrefixMessages), matching
+ *  native compaction semantics — the compaction entry omp stores afterwards
+ *  is the durable record, and it truncates everything before firstKeptEntryId
+ *  from the LLM view, so the summary must cover all of it. Kernel blocks are
+ *  deliberately NOT used here: fold blocks only replay from in-stream
+ *  compress tool calls, which the truncation removes. `previousSummary` (an
+ *  earlier compaction's summary) is folded in so iterative compactions never
+ *  drop it. Returns null on any failure so the caller falls back to Pi's
+ *  native compaction. */
+export declare function summarizeMessages(ctx: ExtensionContext, messages: AgentMessage[], prompts: Prompts, configuredModel?: string | null, opts?: {
+    previousSummary?: string;
+    customInstructions?: string;
+    signal?: AbortSignal;
+    completeFn?: typeof complete;
+}): Promise<{
+    summary: string;
+    model: string;
+} | null>;
+/** Generate a summary for a message range using the compression model. Shared
+ *  entry point for the `/compact` handler. Returns null when no model is
+ *  usable, the slice is empty, the model is unauthenticated, or the response
+ *  is unparseable — the caller then returns `undefined` so Pi falls back to
+ *  its native compaction. */
+export declare function summarizeRange(ctx: ExtensionContext, messages: CoreMessage[], state: CompressionState, startRef: string, endRef: string, prompts: Prompts, configuredModel?: string | null): Promise<{
+    summary: string;
+    model: string;
+} | null>;

package/dist/commands.d.ts

@@ -0,0 +1,8 @@
+import type { RegisteredCommand } from "@oh-my-pi/pi-coding-agent";
+import type { AcpRuntime } from "./runtime.js";
+type CommandOptions = Omit<RegisteredCommand, "name" | "sourceInfo">;
+export declare function makeCommands(runtime: AcpRuntime): Array<{
+    name: string;
+    options: CommandOptions;
+}>;
+export {};

package/dist/compat.d.ts

@@ -0,0 +1,24 @@
+import type { ExtensionContext } from "@oh-my-pi/pi-coding-agent";
+/**
+ * Host compatibility layer for pi vs omp (oh-my-pi) API differences.
+ *
+ * pi: systemPrompt is string, getSystemPrompt() returns string
+ * omp: systemPrompt is string[], getSystemPrompt() returns string[]
+ *
+ * These helpers normalize the differences so the rest of the codebase
+ * can work with a consistent string interface.
+ */
+/** Normalize systemPrompt to a single string (join with newlines if array). */
+export declare function normalizeSystemPrompt(input: string | string[] | undefined): string;
+/**
+ * Format systemPrompt for the before_agent_start event handler.
+ * omp's BeforeAgentStartEventResult.systemPrompt is string[]: each entry is a
+ * prompt segment. We normalize the incoming base (string | string[]) to one
+ * string, append the ACP block, and return it as a single-element array.
+ */
+export declare function formatSystemPromptForEvent(base: string | string[], append: string): string[];
+/**
+ * Get the system prompt as a single string, regardless of host type.
+ * Handles both pi (string) and omp (string[]) return types.
+ */
+export declare function getSystemPromptText(ctx: ExtensionContext): string;

package/dist/compress-tool.d.ts

@@ -0,0 +1,27 @@
+import type { ToolDefinition } from "@oh-my-pi/pi-coding-agent";
+import type { AcpRuntime } from "./runtime.js";
+/** Label shown for a block when the model did not pass a topic: first
+ *  sentence-ish slice of the summary (≤30 chars). Decorative only — never
+ *  blocks compression. */
+export declare function topicFallback(summary: string): string;
+declare const CompressParams: import("@oh-my-pi/omptype").FluentType<{
+    content: {
+        endId: string;
+        startId: string;
+        summary: string;
+        topic?: string | undefined;
+    }[];
+    summaryMaxChars?: number | undefined;
+    topic?: string | undefined;
+}, {
+    content: {
+        endId: string;
+        startId: string;
+        summary: string;
+        topic?: string | undefined;
+    }[];
+    summaryMaxChars?: number | undefined;
+    topic?: string | undefined;
+}>;
+export declare function makeCompressTool(runtime: AcpRuntime): ToolDefinition<typeof CompressParams>;
+export {};