@lienat/pi-jev-compaction 0.1.0 → 0.1.1

package/README.en.md

@@ -1,14 +1,17 @@
 # pi-jev-compaction
 
 A [Pi](https://github.com/badlogic/pi-mono) extension for context compaction.
-The source code here is adapted from the native Claude Code plugin
-[`fast-jev-compaction`](https://github.com/tamaratran/fast-jev-compaction) by
-Tamara Tran, reworked to integrate with Pi. It filters out stale tool calls
-and their results before Pi runs its native compaction summary.
-
-This package is a **Pi adapter**, not a replacement for Pi's compaction system.
-Jev makes the keep/drop/truncate decisions; Pi still creates the summary,
-compaction entry, file-operation details, and retained recent context.
+It uses `fast-jev-compaction@0.4.0` for Jev's tool-call decisions and adapts
+those decisions to Pi's native message and compaction lifecycle.
+
+The `0.4.0` dependency is the
+[`aleksvega/fast-jev-compaction`](https://github.com/aleksvega/fast-jev-compaction)
+fork based on
+[`tamaratran/fast-jev-compaction`](https://github.com/tamaratran/fast-jev-compaction).
+This project is a **Pi adapter**, not a replacement for Pi's compaction system:
+Jev decides which eligible tool calls and results to keep, drop, or shorten;
+Pi still creates the summary, compaction entry, file-operation details, and
+retained recent context.
 
 ## Demo
 
@@ -43,17 +46,17 @@ Jev reviews eligible tool call/result pairs
 ```
 
 Rather than serializing Jev's simplified transcript back into Pi, the adapter
-maps Jev's decisions onto the original Pi messages. This means Pi's thinking
-blocks, images, tool-call metadata, and other native message data are never
-downgraded to plain text by the adapter.
+maps Jev's decisions onto the original Pi messages. Pi's thinking blocks,
+images, tool-call metadata, and other native message data therefore remain
+native in the final preparation.
 
 The adapter only modifies:
 
 - `messagesToSummarize`
 - `turnPrefixMessages`
 
-All other compaction metadata remains fully owned by Pi and is never touched
-by this extension, including:
+All other compaction metadata remains owned by Pi and is never touched by this
+extension, including:
 
 - `firstKeptEntryId`
 - `tokensBefore`
@@ -62,23 +65,42 @@ by this extension, including:
 - `settings`
 - `isSplitTurn`
 
+Pi computes some of this metadata before the hook runs. Consequently, if Jev
+removes an old `write` or `edit` call, `fileOps` may still describe that call;
+the extension does not recalculate Pi's native metadata.
+
 ### What can be filtered
 
 Only paired, text-only tool calls and tool results within the same native
-compaction input are eligible. The adapter leaves the following untouched:
+compaction input are eligible. `messagesToSummarize` and
+`turnPrefixMessages` are processed independently; they are never combined for
+Jev decisions. Pi's separately retained recent region and messages outside
+these two arrays are not sent to Jev.
+
+The adapter leaves the following native messages or content untouched:
 
 - user and assistant prose;
-- thinking blocks and image content;
+- thinking blocks and image content in the original Pi messages;
 - image-bearing tool results;
 - incomplete or duplicate call/result pairs;
 - pairs crossing the two native input boundaries;
 - Pi's separately retained recent region;
 - tool results without a valid matching call.
 
-A `drop_call` decision removes the call and its paired result. A
-`drop_result` decision keeps the call and truncates the result to the first
-300 characters plus a note. Pi then summarizes the filtered native messages
-normally.
+Ineligible tool results—unpaired results, duplicate IDs, image-bearing results,
+or pairs crossing the two compaction inputs—are not converted into ordinary
+user messages, and their text is excluded from Jev's temporary decision state.
+The original Pi messages remain preserved.
+
+A `drop_call` decision removes the call and its paired result. A `drop_result`
+decision keeps the call. With the default `truncateHeadChars` of 300, a result
+is shortened only when it is longer than 420 characters; shorter results stay
+unchanged. Longer results keep their first 300 characters and receive a note.
+Pi then summarizes the filtered native messages normally.
+
+The `reviewed` count in notifications includes only tool calls actually queried
+through Jev. It excludes calls kept by upstream protection rules (pinned) and
+is not a count of questions or request batches.
 
 ## Compatibility
 
@@ -86,12 +108,11 @@ normally.
 - Node.js `>=24`
 - `fast-jev-compaction` `0.4.0`
 
-The extension has a strict Pi `0.85.1` version guard because the adapter
-relies on the mutable `session_before_compact` preparation object introduced
-in that release — this is not a formally documented extension API for
-replacing native preparation arrays. On any other Pi version the extension
-leaves the preparation untouched and Pi falls back to ordinary native
-compaction.
+The extension has a strict Pi `0.85.1` version guard because the adapter relies
+on the mutable `session_before_compact` preparation object used by that release.
+This is not a formally documented extension API for replacing native
+preparation arrays. On any other Pi version the extension leaves the
+preparation untouched and Pi falls back to ordinary native compaction.
 
 This package does not modify Pi's source code or call Pi's exported
 `compact()` function itself.
@@ -147,8 +168,8 @@ use this extension if you are comfortable sending that information to TypeSafe.
 
 ### Timeout
 
-`PI_FAST_JEV_TIMEOUT_MS` controls the total time allowed for a single Jev
-attempt. It defaults to 15 seconds:
+`PI_FAST_JEV_TIMEOUT_MS` controls the total time allowed for one Jev attempt,
+including both native preparation arrays. It defaults to 15 seconds:
 
 ```sh
 export PI_FAST_JEV_TIMEOUT_MS=15000
@@ -177,11 +198,6 @@ npm run typecheck
 npm test
 ```
 
-Tests use injected Jev askers and timers and make no calls to TypeSafe or any
-main model. Coverage includes message mapping, tool-call/result pairing, image
-and thinking preservation, split compaction inputs, timeout and cancellation,
-native fallback, and Pi hook behavior.
-
 Build the package:
 
 ```sh
@@ -196,11 +212,12 @@ npm pack --ignore-scripts
 
 ## Acknowledgements and attribution
 
-This adapter is built on top of
-[`fast-jev-compaction`](https://github.com/tamaratran/fast-jev-compaction) by
-[Tamara Tran](https://github.com/tamaratran), and gratefully acknowledges her
-work. The upstream project provides the Jev decision logic that this Pi
-adapter integrates with native Pi compaction.
+This adapter uses `fast-jev-compaction@0.4.0`, the
+[`aleksvega/fast-jev-compaction`](https://github.com/aleksvega/fast-jev-compaction)
+fork based on [`fast-jev-compaction`](https://github.com/tamaratran/fast-jev-compaction)
+by [Tamara Tran](https://github.com/tamaratran). The upstream project provides
+the Jev decision logic that this Pi adapter integrates with native Pi
+compaction.
 
 If you believe this repository contains material that infringes your rights,
 or if the attribution needs to be corrected, please open an issue at

package/README.md

@@ -1,11 +1,10 @@
 # pi-jev-compaction
 
-
 English version: [README.en.md](README.en.md)
 
-一个用于上下文压缩之前 [Pi](https://github.com/badlogic/pi-mono) 的扩展，此处的源码来源于[`fast-jev-compaction`](https://github.com/tamaratran/fast-jev-compaction)的原生 claude code 的插件，针对 pi 的情况进行了适配。它会在 Pi 执行原生上下文压缩前，筛选不再需要的工具调用和工具结果。
+一个用于上下文压缩之前 [Pi](https://github.com/badlogic/pi-mono) 的扩展，核心判断逻辑复用了来源于[`fast-jev-compaction`](https://github.com/tamaratran/fast-jev-compaction)原作者的原生 claude code 的插件，针对 pi 的情况进行了适配。它会在 Pi 执行原生上下文压缩前，筛选不再需要的工具调用和工具结果，最终的压缩逻辑还是交给 Pi 原生的 `/compact()` 管理。
 
-本项目是 **Pi 适配层**，不是对 Pi 原生压缩系统的替换。Jev 只负责判断哪些工具调用应保留、删除或截短；最终摘要、压缩节点、文件操作信息和近期上下文仍由 Pi 原生 `compact()` 生成和管理。
+里面的决策策略由 Jev 模型负责判断哪些工具调用应保留、删除或截短，本插件不修改 Pi 源码，也不会自行调用 Pi 导出的 `compact()` 函数。
 
 ## 视频演示
 
@@ -13,6 +12,7 @@ English version: [README.en.md](README.en.md)
 
 视频来源：[Tamara Tran 在 X 发布的视频](https://x.com/tamarajtran/status/2100694549362553153)。GIF 仅作为项目演示素材保留，版权归原作者所有。
 
+
 ## 工作方式
 
 手动执行 `/compact` 或 Pi 自动触发压缩时，流程如下：
@@ -23,14 +23,21 @@ Pi 准备压缩
 session_before_compact
     ↓
 Jev 检查符合条件的工具调用/结果对
+    │
     ├─ 成功：只替换 Pi 原生的待摘要消息数组
     │          ↓
     │       Pi 原生 compact()
+    │
     └─ 超时、报错或响应无效：保持原始数组不变
                ↓
             Pi 原生 compact()
 ```
 
+
+## 数据管理
+
+Jev 并不会看到完整的 Pi 会话。它只处理 Pi 本次压缩提供的 `messagesToSummarize` 和 `turnPrefixMessages`，且这两组消息分别处理。
+
 适配层不会把 Jev 的简化 transcript 重新拼回 Pi，而是将 Jev 的决策映射回原始 Pi 消息。因此，Pi 的 thinking、图片、工具调用元数据和其他原生消息数据不会因为适配而被转换成普通文字。
 
 适配层只会修改：
@@ -60,17 +67,22 @@ Jev 检查符合条件的工具调用/结果对
 - Pi 单独保留的近期消息区域；
 - 没有有效调用对应的工具结果。
 
-如果 Jev 返回 `drop_call`，扩展会删除调用及其对应结果。如果返回 `drop_result`，则保留调用，并将结果截短为前 300 个字符加上一条说明。处理完成后，Pi 仍会照常生成原生摘要。
+不符合筛选条件的工具结果（未配对、重复 ID、包含图片，或配对跨越两组压缩输入）不会被转换成普通用户消息，其文本也不会进入 Jev 的临时决策状态；原始 Pi 消息仍然保留。
+
+如果 Jev 返回 `drop_call`，扩展会删除调用及其对应结果；
+如果返回 `drop_result`，则保留调用。如果 Jev 判断只需保留工具调用而不需要完整结果，扩展会沿用上游规则：默认情况下，只有结果超过 420 个字符时才会截短为前 300 个字符并追加说明；较短结果会保持原文。
+
+处理完成后，Pi 仍会照常生成原生摘要。
+
+通知中的 `reviewed` 只统计实际向 Jev 询问的工具调用，不包含被上游保护规则固定保留的调用（pinned），也不是问题数或请求批次数。
 
 ## 兼容性
 
 - Pi `0.85.1`
 - Node.js `>=24`
-- `fast-jev-compaction` `0.4.0`
 
-扩展对 Pi 版本进行严格检查，因为当前适配依赖 Pi `0.85.1` 的 `session_before_compact` preparation 对象可变行为；这不是 Pi 正式承诺的“替换原生压缩输入”扩展接口。使用其他 Pi 版本时，扩展不会修改压缩输入，Pi 会安全地回退到原生压缩。
+扩展对 Pi 版本进行严格检查，因为当前适配依赖 Pi `0.85.1` 的 `session_before_compact` preparation 对象可变行为；并没有替换原生压缩输入的扩展接口。所以使用其他 Pi 版本时，扩展不会修改压缩输入，Pi 会安全地回退到原生压缩。
 
-本项目不修改 Pi 源码，也不会自行调用 Pi 导出的 `compact()` 函数。
 
 ## 安装
 
@@ -124,7 +136,7 @@ API Key 只在运行时读取，并只用于认证 Jev 请求；不会写入本
 export PI_FAST_JEV_TIMEOUT_MS=15000
 ```
 
-如果 API Key 缺失、Pi 版本不支持、Jev 超时、请求失败或响应无效，扩展会显示简短提示并保持原始压缩输入不变，然后由 Pi 执行普通原生压缩。扩展不会递归调用 `/compact`。
+如果 API Key 缺失、Pi 版本不支持、Jev 超时、请求失败或响应无效，扩展会显示简短提示并保持原始压缩输入不变，然后由 Pi 执行普通原生压缩。
 
 用户主动取消压缩时，取消信号会传递给 Jev，扩展不会替换或修改原生压缩输入。
 
@@ -143,8 +155,6 @@ npm run typecheck
 npm test
 ```
 
-测试使用注入的 Jev asker 和计时器，不会访问 TypeSafe，也不会调用主模型。测试覆盖消息映射、工具调用/结果配对、图片和 thinking 保留、两组压缩输入、超时、取消、原生回退和 Pi hook 行为。
-
 构建：
 
 ```sh
@@ -165,6 +175,8 @@ npm pack --ignore-scripts
 如果你认为本仓库包含侵犯你权利的内容，或署名信息需要修正，请在
 [GitHub Issues](https://github.com/Jul1en-Lin/pi-jev-compaction/issues) 联系维护者。我们会审核请求，并在适当情况下删除或修订相关内容。
 
+欢迎大家使用并指出指导性意见，感谢！
+
 ## 许可证
 
 本适配层使用 MIT License。使用时也请查看上游

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lienat/pi-jev-compaction",
-  "version": "0.1.0",
-  "description": "Apply fast-jev-compaction decisions before Pi's native compaction summary.",
+  "version": "0.1.1",
+  "description": "Pi extension that uses TypeSafe Jev to prune eligible historical tool calls before native compaction, preserving native messages and falling back safely on failure.",
   "type": "module",
   "license": "MIT",
   "repository": {

package/src/adapter.ts

@@ -1,5 +1,6 @@
 import {
   compact,
+  resolveOptions,
   buildJevRequest,
   parseJevResponse,
   type CallDecision,
@@ -217,17 +218,23 @@ function toJevMessages(messages: readonly AgentMessage[], pairs: readonly Pair[]
       };
     }
 
-    if (message.role === "toolResult" && eligible.has(message.toolCallId)) {
-      return {
-        role: "user",
-        text: "",
-        toolUses: [],
-        toolResults: [{
-          tool_use_id: message.toolCallId,
-          text: contentText(message.content),
-          isError: message.isError,
-        }],
-      };
+    if (message.role === "toolResult") {
+      if (eligible.has(message.toolCallId)) {
+        return {
+          role: "user",
+          text: "",
+          toolUses: [],
+          toolResults: [{
+            tool_use_id: message.toolCallId,
+            text: contentText(message.content),
+            isError: message.isError,
+          }],
+        };
+      }
+
+      // Unpaired or ineligible results must not become user text or goals in
+      // Jev's state; the original Pi message is preserved on output.
+      return { role: "user", text: "", toolUses: [] };
     }
 
     return { role: "user", text: messageText(message), toolUses: [] };
@@ -345,13 +352,18 @@ export async function filterMessages(
     return { messages: [...messages], changed: false, candidateCalls: 0, droppedCalls: 0, truncatedResults: 0 };
   }
 
-  const compactOptions = options.compactOptions ?? {};
+  const compactOptions = resolveOptions(options.compactOptions ?? {});
   const result = await rejectOnAbort(
     compact(toJevMessages(messages, pairs), options.asker, compactOptions),
     options.signal,
   );
-  const headChars = compactOptions.truncateHeadChars ?? 300;
-  return applyActions(messages, decisionActions(result.decisions, pairs), headChars, pairs.length);
+  const reviewedCalls = result.decisions.filter((decision) => decision.reason !== "pinned").length;
+  return applyActions(
+    messages,
+    decisionActions(result.decisions, pairs),
+    compactOptions.truncateHeadChars,
+    reviewedCalls,
+  );
 }
 
 /** Filter Pi's two native summary inputs independently; their boundaries stay intact. */