@lll9p/pi-better-compaction 0.2.1 → 0.5.0

package/README.md

@@ -1,116 +1,61 @@
 # pi-better-compaction
 
-A Pi extension that upgrades compaction with two coordinated strategies:
+English | [中文](README.zh-CN.md)
 
-1. **OpenAI Responses APIs** (`openai-responses`, `openai-codex-responses`) use the provider's
-   native `/responses/compact` endpoint, then replay the opaque compacted window on later
-   requests without patching Pi core.
-2. **Every other API** (Anthropic, Gemini, etc.) runs Pi's own native compaction method,
-   optionally driven by a **dedicated compaction model** so you can summarize with a cheaper/faster
-   model than the one you are chatting with.
+A [pi](https://github.com/nicepkg/pi) extension that upgrades context compaction with three coordinated strategies:
 
-Everything fails open: if any step cannot proceed, the extension returns control to Pi's default
-compaction so a compaction never breaks because of this extension.
+1. An optional **mid-run guard** aborts an oversized tool loop, waits for `agent_settled`, compacts once, then resumes with a hidden custom message.
+2. **OpenAI Responses APIs** use the provider's native compaction endpoint, preserving opaque context that plain text summaries lose.
+3. **All other APIs** (Anthropic, Gemini, etc.) can run pi's built-in compaction with a **dedicated cheaper/faster model**, so summarization doesn't consume quota on your primary model.
 
-## Requirements
-
-- **Minimum Pi version:** `@earendil-works/pi-coding-agent >= 0.80.0`
-
-This extension relies on `modelRegistry.getApiKeyAndHeaders(model)` and the exported native
-`compact()` function.
-
-## Behavior
-
-The `session_before_compact` decision tree:
-
-```
-session_before_compact
-│
-├─ config.enabled == false ───────────────────────► Pi default compaction
-│
-├─ current model API is a Responses API
-│   │  (openai-responses / openai-codex-responses, narrowable via config)
-│   ├─ POST /responses/compact
-│   │   ├─ success ─────────────────────────────────► store opaque window + real summary
-│   │   ├─ user aborted ─────────────────────────────► cancel
-│   │   └─ failure (404 / network / malformed) ──────► fall through ▼
-│   └─ (missing base URL / API key) ─────────────────► fall through ▼
-│
-├─ config.compactionModel is set and resolvable and ≠ current model
-│   └─ run Pi's native compact() with that model ────► use its result
-│
-└─ otherwise ─────────────────────────────────────► Pi default compaction
-      (no model configured, or it equals the current model — Pi runs the
-       same native method itself, keeping its streaming progress UI)
-```
-
-On the next supported Responses request after a native `/responses/compact`, the
-`before_provider_request` hook rewrites Pi's summary-oriented replay into:
-
-- fresh current prompt envelope
-- stored opaque compacted window
-- live post-compaction tail
-
-Requests produced by the native-method fallback carry Pi's standard `{readFiles, modifiedFiles}`
-details, so they replay through Pi's default path — no rewrite, no special handling.
-
-By default, a session whose latest compaction is not a stored native opaque window does not attempt
-`/responses/compact`, preserving strict replay continuity. Set `allowCompactionContinuityBreak` to
-`true` to restart native compaction from Pi's current effective context instead. Any information
-already omitted by Pi's text summary cannot be recovered, but the successful compact response
-becomes the new opaque replay checkpoint for later turns.
-
-### Selection is by API, not provider
-
-Any provider speaking a Responses API gets a native compact attempt, including OpenAI-compatible
-proxies with a custom `baseUrl`. If such an endpoint does not implement `/responses/compact`, the
-request 404s and the extension fails through to the configured fallback model (or Pi default). To
-avoid the probe entirely for one API, narrow `responsesCompactApis`.
+Everything fails open — if any step cannot proceed, pi's default compaction takes over.
 
 ## Install
 
-From npm (recommended):
-
 ```bash
+# From npm (recommended)
 pi install npm:@lll9p/pi-better-compaction
-```
-
-Try it for a single run without installing:
 
-```bash
+# Try without installing
 pi -e npm:@lll9p/pi-better-compaction
-```
-
-From a checkout (development):
 
-```bash
+# From source
 git clone https://github.com/lll9p/pi-better-compaction.git
-cd pi-better-compaction
-pi install .
+cd pi-better-compaction && pi install .
 ```
 
 After installation, run `/reload`.
 
+## Requirements
+
+- **pi** ≥ 0.84.3 (`@earendil-works/pi-coding-agent >= 0.84.3`)
+
 ## Configuration
 
-Single source, merged over built-in defaults:
+Config file location:
 
 ```
 ~/.pi/agent/extensions/pi-better-compaction/config.json
 ```
 
-A missing file silently uses the defaults below. The extension never writes this file for you.
+If the file doesn't exist, all defaults apply. The extension never creates this file.
 
-```json
+### Defaults
+
+```jsonc
 {
   "enabled": true,
-  "allowCompactionContinuityBreak": false,
-
-  "compactionModel": "openai/gpt-5.1-mini",
+  "midRun": {
+    "enabled": false,
+    "thresholdPercent": 80
+  },
+  "compactionVersion": "v2",
+  "compactionModel": null,
   "compactionThinkingLevel": "off",
-
   "responsesCompactApis": ["openai-responses", "openai-codex-responses"],
+  "allowCompactionContinuityBreak": false,
 
+  // Debug & logging
   "notifyOnLoad": false,
   "debug": false,
   "logProviderPayloads": false,
@@ -120,31 +65,82 @@ A missing file silently uses the defaults below. The extension never writes this
 }
 ```
 
-| Key | Default | Description |
-|-----|---------|-------------|
-| `enabled` | `true` | Master switch. `false` → Pi default compaction everywhere. |
-| `allowCompactionContinuityBreak` | `false` | Opt in to native compact recovery when the latest session compaction was created by Pi or another non-native path. The extension serializes `buildSessionContext().messages`, including Pi's text summary, into a new `/responses/compact` request. This sacrifices strict opaque-window continuity at that boundary; a successful response establishes a new native replay chain. |
-| `compactionModel` | *(unset)* | `"provider/model-id"` used for native-method fallback (non-Responses APIs, or when the compact endpoint fails). `null`/unset → use the current model via Pi's default path. The provider is split on the first `/`, so model ids may contain slashes (e.g. `"openrouter/deepseek/deepseek-chat"`). |
-| `compactionThinkingLevel` | `"off"` | Thinking level passed to the native `compact()` fallback. One of `off, minimal, low, medium, high, xhigh, max`. |
-| `responsesCompactApis` | both Responses APIs | Which Responses APIs use the compact endpoint. May only narrow the built-in set; unknown entries are ignored with a warning. |
-| `notifyOnLoad` | `false` | Show a load notification in the TUI. |
-| `debug` | `false` | Write lifecycle + compaction-event artifacts. |
-| `logProviderPayloads` | `false` | Write `before_provider_request` payload artifacts. |
-| `logCompactResponses` | `false` | Write compact endpoint request/response artifacts. |
-| `redactSensitiveData` | `true` | Redact secrets in artifacts. Keep on. |
-| `artifactRoot` | `~/.pi/agent/artifacts/pi-better-compaction` | Debug artifact root. `~/` and relative paths (resolved against the config dir) are supported. |
+### Options reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Master switch. Set `false` to disable the extension entirely. |
+| `midRun.enabled` | `boolean` | `false` | Enable the mid-run guard. It may abort a long tool loop once context reaches the configured threshold. |
+| `midRun.thresholdPercent` | `number` | `80` | Context usage percentage that triggers the mid-run guard after a tool-bearing turn. Must be greater than 0 and at most 100. |
+| `compactionVersion` | `"v1" \| "v2"` | `"v2"` | Protocol for Responses-family APIs. **V2** (streaming, encrypted blob) is the current OpenAI default. **V1** uses the legacy `/responses/compact` endpoint. |
+| `compactionModel` | `string \| null` | `null` | Model for fallback compaction (non-Responses APIs, or when native compact fails). Format: `"provider/model-id"`, e.g. `"openai/gpt-5.1-mini"`. `null` = let pi use the current chat model. |
+| `compactionThinkingLevel` | `string` | `"off"` | Thinking level for the fallback compaction model. One of: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. |
+| `responsesCompactApis` | `string[]` | `["openai-responses", "openai-codex-responses"]` | Which Responses APIs use native compaction. Can only narrow the built-in set; unknown entries are ignored with a warning. |
+| `allowCompactionContinuityBreak` | `boolean` | `false` | Allow restarting native compaction when the latest session compaction was created by pi's default path (not this extension). Sacrifices opaque-window continuity at that boundary. |
+| `notifyOnLoad` | `boolean` | `false` | Show a notification in the TUI when the extension loads. |
+| `debug` | `boolean` | `false` | Write lifecycle and compaction-event debug artifacts. |
+| `logProviderPayloads` | `boolean` | `false` | Write `before_provider_request` payload artifacts. |
+| `logCompactResponses` | `boolean` | `false` | Write compact endpoint request/response artifacts. |
+| `redactSensitiveData` | `boolean` | `true` | Redact secrets in debug artifacts. |
+| `artifactRoot` | `string` | `"~/.pi/agent/artifacts/pi-better-compaction"` | Root directory for debug artifacts. Supports `~/` and relative paths (resolved against config dir). |
+
+### Example: enable mid-run compaction
+
+```json
+{
+  "midRun": {
+    "enabled": true,
+    "thresholdPercent": 80
+  }
+}
+```
+
+### Example: use a cheap model for fallback compaction
+
+```json
+{
+  "compactionModel": "openai/gpt-5.1-mini",
+  "compactionThinkingLevel": "off"
+}
+```
+
+### Example: force V1 compaction protocol
+
+```json
+{
+  "compactionVersion": "v1"
+}
+```
+
+## How it works
+
+With `midRun.enabled`, a completed tool-bearing `turn_end` above the threshold only calls `ctx.abort()`. After Pi emits `agent_settled`, the guard reuses any compaction Pi already completed during abort handling; otherwise it calls `ctx.compact()` exactly once. A successful or coalesced compaction triggers the next turn with a hidden custom message. Failed compaction does not resume, preventing a compact-fail-resume loop.
 
-### Codex-aligned compact request
+When pi triggers compaction (`session_before_compact`):
 
-For Responses compaction, the extension mirrors the latest codex_rs `CompactionInput` fields
-(`tools`, `parallel_tool_calls`, `reasoning`, `service_tier`, `prompt_cache_key`, `text`) by
-capturing them from the most recent live provider request for the same model/session and attaching
-them to the compact request body. When no such request has been seen yet, the compact request falls
-back to the minimal `model` / `input` / `instructions` body.
+1. **Responses API detected** → run native compaction (V2 or V1 per config):
+   - **V2**: streams a request with `compaction_trigger` to `/responses`; the API returns an encrypted compaction blob. Retained user/developer messages + blob form the compacted context.
+   - **V1**: POSTs to `/responses/compact`; receives an opaque compacted window.
+   - On success, the compacted window is stored and replayed on subsequent requests via `before_provider_request`.
 
-## Debug artifacts
+2. **Not a Responses API, or native compact failed** → if `compactionModel` is configured and differs from the current model, run pi's built-in `compact()` with that model.
 
-Written per session under:
+3. **No fallback configured** → pi's default compaction runs as if the extension weren't installed.
+
+Selection is by API type, not provider — any OpenAI-compatible proxy speaking a Responses API gets a native compact attempt. If the endpoint doesn't support it, the request fails and falls through to the configured fallback.
+
+## Debugging
+
+Enable debug artifacts:
+
+```json
+{
+  "debug": true,
+  "logCompactResponses": true
+}
+```
+
+Then `/reload`, run `/compact`, send a follow-up message, and inspect:
 
 ```
 <artifactRoot>/sessions/<session-id>/
@@ -154,38 +150,13 @@ Written per session under:
 └── lifecycle/
 ```
 
-Troubleshooting flow:
-
-1. set `debug: true` and `logCompactResponses: true` (keep `redactSensitiveData: true`)
-2. `/reload`
-3. run `/compact`, then send a follow-up message
-4. inspect the newest artifact in the session directory
-
-## Package structure
-
-```
-package-root/
-├── index.ts                     # entrypoint declared in package.json
-├── src/
-│   ├── extension-runtime.ts     # hook registration + compaction decision tree
-│   ├── config.ts                # config.json loader (single source + defaults)
-│   ├── runtime.ts               # API-based environment resolution + auth
-│   ├── compact-client.ts        # /responses/compact client + summary extraction
-│   ├── native-fallback.ts       # configured-model native compact() driver
-│   ├── request-context-cache.ts # captures codex-aligned fields from live requests
-│   ├── serializer.ts            # Responses input serialization
-│   ├── payload-rewrite.ts       # native opaque-window replay rewrite
-│   ├── details-store.ts         # latest-valid native compaction lookup
-│   ├── debug.ts                 # artifact writing + redaction
-│   ├── supported-environment.ts # re-exports
-│   └── types.ts                 # config + persisted native-compaction types
-└── test/
-```
-
 ## Tests
 
 ```bash
 bun test
 bun test --coverage --coverage-reporter=text --coverage-reporter=lcov
-bun test ./test/pi-smoke.test.ts
 ```
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,162 @@
+# pi-better-compaction
+
+[English](README.md) | 中文
+
+一个 [pi](https://github.com/nicepkg/pi) 扩展，通过三条协同策略提升上下文压缩效果：
+
+1. 可选的 **mid-run guard** 在工具循环占满上下文时先中止运行，等待 `agent_settled` 后只压缩一次，再通过隐藏消息继续任务。
+2. **OpenAI Responses 系列 API** 使用提供商原生压缩端点，保留纯文本摘要无法留存的不透明上下文。
+3. **其他所有 API**（Anthropic、Gemini 等）可用一个**独立的低成本模型**执行 pi 内置压缩，避免在主模型上消耗额度。
+
+所有环节都安全降级——任何步骤无法执行时，pi 的默认压缩自动接管。
+
+## 安装
+
+```bash
+# 从 npm 安装（推荐）
+pi install npm:@lll9p/pi-better-compaction
+
+# 临时试用，不安装
+pi -e npm:@lll9p/pi-better-compaction
+
+# 从源码安装
+git clone https://github.com/lll9p/pi-better-compaction.git
+cd pi-better-compaction && pi install .
+```
+
+安装后执行 `/reload` 生效。
+
+## 要求
+
+- **pi** ≥ 0.84.3（`@earendil-works/pi-coding-agent >= 0.84.3`）
+
+## 配置
+
+配置文件路径：
+
+```
+~/.pi/agent/extensions/pi-better-compaction/config.json
+```
+
+文件不存在时使用默认值。扩展不会自动创建此文件。
+
+### 默认配置
+
+```jsonc
+{
+  "enabled": true,
+  "midRun": {
+    "enabled": false,
+    "thresholdPercent": 80
+  },
+  "compactionVersion": "v2",
+  "compactionModel": null,
+  "compactionThinkingLevel": "off",
+  "responsesCompactApis": ["openai-responses", "openai-codex-responses"],
+  "allowCompactionContinuityBreak": false,
+
+  // 调试与日志
+  "notifyOnLoad": false,
+  "debug": false,
+  "logProviderPayloads": false,
+  "logCompactResponses": false,
+  "redactSensitiveData": true,
+  "artifactRoot": "~/.pi/agent/artifacts/pi-better-compaction"
+}
+```
+
+### 配置项说明
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `enabled` | `boolean` | `true` | 总开关。设为 `false` 完全禁用扩展。 |
+| `midRun.enabled` | `boolean` | `false` | 启用 mid-run guard。上下文达到阈值后，它可能主动中止长工具循环。 |
+| `midRun.thresholdPercent` | `number` | `80` | 工具型 turn 完成后触发 mid-run guard 的上下文占用百分比。必须大于 0 且不超过 100。 |
+| `compactionVersion` | `"v1" \| "v2"` | `"v2"` | Responses 系列 API 的压缩协议。**V2**（流式，加密 blob）是 OpenAI 当前默认协议；**V1** 使用旧版 `/responses/compact` 端点。 |
+| `compactionModel` | `string \| null` | `null` | 回退压缩使用的模型（用于非 Responses API，或原生压缩失败时）。格式：`"provider/model-id"`，如 `"openai/gpt-5.1-mini"`。`null` = 由 pi 使用当前对话模型。 |
+| `compactionThinkingLevel` | `string` | `"off"` | 回退压缩模型的思考级别。可选：`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。 |
+| `responsesCompactApis` | `string[]` | `["openai-responses", "openai-codex-responses"]` | 启用原生压缩的 Responses API 列表。只能缩小内置集合，不能添加新值。 |
+| `allowCompactionContinuityBreak` | `boolean` | `false` | 当会话最近一次压缩不是本扩展创建的时，是否允许重新开始原生压缩。会在该边界处牺牲不透明窗口的连续性。 |
+| `notifyOnLoad` | `boolean` | `false` | 扩展加载时在 TUI 中显示通知。 |
+| `debug` | `boolean` | `false` | 写入生命周期和压缩事件的调试文件。 |
+| `logProviderPayloads` | `boolean` | `false` | 写入 `before_provider_request` 请求体调试文件。 |
+| `logCompactResponses` | `boolean` | `false` | 写入压缩端点的请求/响应调试文件。 |
+| `redactSensitiveData` | `boolean` | `true` | 在调试文件中脱敏。 |
+| `artifactRoot` | `string` | `"~/.pi/agent/artifacts/pi-better-compaction"` | 调试文件根目录。支持 `~/` 和相对路径（相对于配置文件目录解析）。 |
+
+### 示例：启用 mid-run 压缩
+
+```json
+{
+  "midRun": {
+    "enabled": true,
+    "thresholdPercent": 80
+  }
+}
+```
+
+### 示例：使用低成本模型做回退压缩
+
+```json
+{
+  "compactionModel": "openai/gpt-5.1-mini",
+  "compactionThinkingLevel": "off"
+}
+```
+
+### 示例：强制使用 V1 压缩协议
+
+```json
+{
+  "compactionVersion": "v1"
+}
+```
+
+## 工作原理
+
+启用 `midRun.enabled` 后，超过阈值的工具型 `turn_end` 只调用 `ctx.abort()`。Pi 发出 `agent_settled` 后，guard 会复用 abort 收尾阶段已经完成的压缩；如果没有，则只调用一次 `ctx.compact()`。压缩成功或竞争合并后，通过隐藏 custom message 触发下一轮。压缩失败时不会自动继续，避免进入“压缩失败—继续—再次失败”的循环。
+
+pi 触发压缩时（`session_before_compact`）：
+
+1. **检测到 Responses API** → 执行原生压缩（根据配置选择 V2 或 V1）：
+   - **V2**：向 `/responses` 端点发送携带 `compaction_trigger` 的流式请求，API 返回加密压缩 blob。保留的用户/开发者消息 + blob 组成压缩后的上下文。
+   - **V1**：POST 到 `/responses/compact`，接收不透明的压缩窗口。
+   - 成功后，压缩窗口被存储，后续请求通过 `before_provider_request` 钩子回放。
+
+2. **非 Responses API，或原生压缩失败** → 若配置了 `compactionModel` 且与当前模型不同，使用该模型执行 pi 内置的 `compact()` 方法。
+
+3. **未配置回退模型** → pi 的默认压缩照常执行，如同扩展未安装。
+
+判断依据是 API 类型而非提供商——任何使用 Responses API 协议的 OpenAI 兼容代理都会触发原生压缩尝试。如果端点不支持，请求失败后自动回退。
+
+## 调试
+
+启用调试文件输出：
+
+```json
+{
+  "debug": true,
+  "logCompactResponses": true
+}
+```
+
+然后 `/reload`，执行 `/compact`，发送一条后续消息，检查：
+
+```
+<artifactRoot>/sessions/<session-id>/
+├── provider-requests/
+├── compact-responses/
+├── compaction-events/
+└── lifecycle/
+```
+
+## 测试
+
+```bash
+bun test
+bun test --coverage --coverage-reporter=text --coverage-reporter=lcov
+```
+
+## 许可证
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lll9p/pi-better-compaction",
-  "version": "0.2.1",
+  "version": "0.5.0",
   "type": "module",
   "description": "Better compaction for pi: native /responses/compact replay for OpenAI Responses APIs, plus a configurable compaction model driving pi's native summarization everywhere else.",
   "author": "Lilin Lao",
@@ -33,18 +33,23 @@
   "files": [
     "index.ts",
     "src/compact-client.ts",
+    "src/compact-client-v2.ts",
     "src/config.ts",
     "src/debug.ts",
     "src/details-store.ts",
     "src/extension-runtime.ts",
+    "src/midrun.ts",
     "src/native-fallback.ts",
     "src/payload-rewrite.ts",
     "src/request-context-cache.ts",
+    "src/retained-messages.ts",
     "src/runtime.ts",
     "src/serializer.ts",
+    "src/shared-headers.ts",
     "src/supported-environment.ts",
     "src/types.ts",
     "README.md",
+    "README.zh-CN.md",
     "LICENSE"
   ],
   "scripts": {
@@ -55,6 +60,6 @@
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
     "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": ">=0.80.0"
+    "@earendil-works/pi-coding-agent": ">=0.84.3"
   }
 }