@lienat/pi-jev-compaction 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jul1en-Lin
+
+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.en.md

@@ -0,0 +1,215 @@
+# 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.
+
+## Demo
+
+![Jev instant compaction demo](./assets/tamarajtran-jev-compaction.gif)
+
+Video source: [Tamara Tran's post on X](https://x.com/tamarajtran/status/2100694549362553153).
+The GIF is included as demonstration material; all rights remain with the
+original author.
+
+## How it works
+
+For both manual `/compact` and automatic compaction:
+
+```text
+Pi prepares a compaction
+        |
+        v
+session_before_compact
+        |
+        v
+Jev reviews eligible tool call/result pairs
+        |
+        +-- success --> replace only the two native message arrays
+        |                 |
+        |                 v
+        |            Pi's native compact()
+        |
+        +-- timeout/error/invalid response --> leave preparation unchanged
+                                              |
+                                              v
+                                         Pi's native compact()
+```
+
+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.
+
+The adapter only modifies:
+
+- `messagesToSummarize`
+- `turnPrefixMessages`
+
+All other compaction metadata remains fully owned by Pi and is never touched
+by this extension, including:
+
+- `firstKeptEntryId`
+- `tokensBefore`
+- `previousSummary`
+- `fileOps`
+- `settings`
+- `isSplitTurn`
+
+### 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:
+
+- user and assistant prose;
+- thinking blocks and image content;
+- 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.
+
+## Compatibility
+
+- Pi `0.85.1`
+- 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.
+
+This package does not modify Pi's source code or call Pi's exported
+`compact()` function itself.
+
+## Installation
+
+Install from Pi Package (npm):
+
+```sh
+pi install npm:@lienat/pi-jev-compaction
+```
+
+Install from the GitHub repository:
+
+```sh
+pi install git:github.com/Jul1en-Lin/pi-jev-compaction@main
+```
+
+Or install a local checkout for development:
+
+```sh
+pi install /Users/lien/prj/pi-fast-jev-compaction
+```
+
+Restart Pi after installation. Verify with:
+
+```sh
+pi list
+```
+
+To uninstall the GitHub version:
+
+```sh
+pi remove git:github.com/Jul1en-Lin/pi-jev-compaction
+```
+
+## Configuration
+
+The extension reaches the official TypeSafe Jev endpoint through the upstream
+package. Set the API key in the environment of the terminal that starts Pi:
+
+```sh
+export TYPESAFE_API_KEY='your-typesafe-key'
+```
+
+The key is read at runtime and used only to authenticate Jev requests. It is
+never written to the package, Pi settings, session files, or extension logs.
+Do not commit it or paste it into a shared shell history.
+
+The Jev decision payload can include conversation text and tool input, which
+may contain source code, file paths, commands, or other sensitive data. Only
+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:
+
+```sh
+export PI_FAST_JEV_TIMEOUT_MS=15000
+```
+
+If the API key is missing, the Pi version is unsupported, Jev times out, the
+request fails, or the response is invalid, the adapter prints a brief warning
+and leaves the original preparation unchanged. Pi then runs its ordinary
+native compaction. The extension never invokes `/compact` recursively.
+
+When the user cancels a compaction, the cancellation signal is forwarded to
+the Jev request and the native preparation is not replaced or modified.
+
+## Development
+
+Install dependencies without running lifecycle scripts:
+
+```sh
+npm install --ignore-scripts --no-audit --no-fund
+```
+
+Run the checks:
+
+```sh
+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
+npm run build
+```
+
+Create a local npm tarball without publishing:
+
+```sh
+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.
+
+If you believe this repository contains material that infringes your rights,
+or if the attribution needs to be corrected, please open an issue at
+[github.com/Jul1en-Lin/pi-jev-compaction/issues](https://github.com/Jul1en-Lin/pi-jev-compaction/issues).
+We will review the request and remove or revise the affected material where
+appropriate.
+
+## License
+
+This adapter is released under the MIT License. Please also review the
+upstream project's license and attribution requirements:
+[`fast-jev-compaction`](https://github.com/tamaratran/fast-jev-compaction).

package/README.md

@@ -0,0 +1,171 @@
+# 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 适配层**，不是对 Pi 原生压缩系统的替换。Jev 只负责判断哪些工具调用应保留、删除或截短；最终摘要、压缩节点、文件操作信息和近期上下文仍由 Pi 原生 `compact()` 生成和管理。
+
+## 视频演示
+
+![Jev instant compaction demo](./assets/tamarajtran-jev-compaction.gif)
+
+视频来源：[Tamara Tran 在 X 发布的视频](https://x.com/tamarajtran/status/2100694549362553153)。GIF 仅作为项目演示素材保留，版权归原作者所有。
+
+## 工作方式
+
+手动执行 `/compact` 或 Pi 自动触发压缩时，流程如下：
+
+```text
+Pi 准备压缩
+    ↓
+session_before_compact
+    ↓
+Jev 检查符合条件的工具调用/结果对
+    ├─ 成功：只替换 Pi 原生的待摘要消息数组
+    │          ↓
+    │       Pi 原生 compact()
+    └─ 超时、报错或响应无效：保持原始数组不变
+               ↓
+            Pi 原生 compact()
+```
+
+适配层不会把 Jev 的简化 transcript 重新拼回 Pi，而是将 Jev 的决策映射回原始 Pi 消息。因此，Pi 的 thinking、图片、工具调用元数据和其他原生消息数据不会因为适配而被转换成普通文字。
+
+适配层只会修改：
+
+- `messagesToSummarize`
+- `turnPrefixMessages`
+
+以下字段仍完全由 Pi 管理，不会被本扩展修改：
+
+- `firstKeptEntryId`
+- `tokensBefore`
+- `previousSummary`
+- `fileOps`
+- `settings`
+- `isSplitTurn`
+
+### 哪些内容可以被筛选
+
+只有位于同一个原生压缩输入中的、成对且纯文本的工具调用和工具结果才会参与筛选。以下内容会保持不变：
+
+- 用户消息和助手正文；
+- thinking 块和图片内容；
+- 包含图片的工具结果；
+- 缺少对应调用或结果的消息；
+- 重复 ID 的调用/结果；
+- 跨越两个原生输入边界的调用/结果对；
+- Pi 单独保留的近期消息区域；
+- 没有有效调用对应的工具结果。
+
+如果 Jev 返回 `drop_call`，扩展会删除调用及其对应结果。如果返回 `drop_result`，则保留调用，并将结果截短为前 300 个字符加上一条说明。处理完成后，Pi 仍会照常生成原生摘要。
+
+## 兼容性
+
+- 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 导出的 `compact()` 函数。
+
+## 安装
+
+从 Pi Package（npm）安装：
+
+```sh
+pi install npm:@lienat/pi-jev-compaction
+```
+
+从 GitHub 安装：
+
+```sh
+pi install git:github.com/Jul1en-Lin/pi-jev-compaction@main
+```
+
+也可以安装本地 checkout：
+
+```sh
+pi install /Users/lien/prj/pi-fast-jev-compaction
+```
+
+安装后重启 Pi。查看已安装包：
+
+```sh
+pi list
+```
+
+卸载 GitHub 版本：
+
+```sh
+pi remove git:github.com/Jul1en-Lin/pi-jev-compaction
+```
+
+## 配置
+
+扩展通过上游包访问官方 TypeSafe Jev 服务。请在启动 Pi 的终端中配置 API Key：
+
+```sh
+export TYPESAFE_API_KEY='your-typesafe-key'
+```
+
+API Key 只在运行时读取，并只用于认证 Jev 请求；不会写入本项目、Pi settings、会话文件或扩展日志。请不要提交 API Key，也不要把它放进共享的 shell 历史记录。
+
+发送给 Jev 的决策状态可能包含会话文本和工具输入，其中可能有源代码、文件路径、命令或其他敏感信息。只有在你接受这些信息发送到 TypeSafe 的情况下，才应使用本扩展。
+
+### 超时配置
+
+`PI_FAST_JEV_TIMEOUT_MS` 控制一次 Jev 尝试的总时限，默认值为 15 秒：
+
+```sh
+export PI_FAST_JEV_TIMEOUT_MS=15000
+```
+
+如果 API Key 缺失、Pi 版本不支持、Jev 超时、请求失败或响应无效，扩展会显示简短提示并保持原始压缩输入不变，然后由 Pi 执行普通原生压缩。扩展不会递归调用 `/compact`。
+
+用户主动取消压缩时，取消信号会传递给 Jev，扩展不会替换或修改原生压缩输入。
+
+## 开发
+
+安装依赖：
+
+```sh
+npm install --ignore-scripts --no-audit --no-fund
+```
+
+执行检查：
+
+```sh
+npm run typecheck
+npm test
+```
+
+测试使用注入的 Jev asker 和计时器，不会访问 TypeSafe，也不会调用主模型。测试覆盖消息映射、工具调用/结果配对、图片和 thinking 保留、两组压缩输入、超时、取消、原生回退和 Pi hook 行为。
+
+构建：
+
+```sh
+npm run build
+```
+
+创建本地 npm 压缩包（不会发布）：
+
+```sh
+npm pack --ignore-scripts
+```
+
+## 致谢与署名
+
+本适配层基于 [Tamara Tran](https://github.com/tamaratran) 的
+[`fast-jev-compaction`](https://github.com/tamaratran/fast-jev-compaction) 项目，感谢原作者提供 Jev 决策逻辑。
+
+如果你认为本仓库包含侵犯你权利的内容，或署名信息需要修正，请在
+[GitHub Issues](https://github.com/Jul1en-Lin/pi-jev-compaction/issues) 联系维护者。我们会审核请求，并在适当情况下删除或修订相关内容。
+
+## 许可证
+
+本适配层使用 MIT License。使用时也请查看上游
+[`fast-jev-compaction`](https://github.com/tamaratran/fast-jev-compaction) 项目的许可证和署名要求。

package/extensions/fast-jev-compaction.ts

@@ -0,0 +1,94 @@
+import { VERSION, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  createDeadline,
+  createJevAsker,
+  DEFAULT_TIMEOUT_MS,
+  filterPreparation,
+  type TimerApi,
+} from "../src/adapter.js";
+import type { JevAsker } from "fast-jev-compaction";
+
+const SUPPORTED_PI_VERSION = "0.85.1";
+
+export interface ExtensionDependencies {
+  apiKey?: string;
+  asker?: JevAsker;
+  timers?: TimerApi;
+}
+
+export function parseTimeout(value: string | undefined): number {
+  if (value === undefined || value === "") return DEFAULT_TIMEOUT_MS;
+  const timeout = Number(value);
+  return Number.isFinite(timeout) && timeout > 0 ? Math.floor(timeout) : DEFAULT_TIMEOUT_MS;
+}
+
+/** Short, transient console line: nothing here is written to the session or disk. */
+export function formatElapsed(milliseconds: number): string {
+  return milliseconds < 1000 ? `${milliseconds}ms` : `${(milliseconds / 1000).toFixed(1)}s`;
+}
+
+export function install(pi: ExtensionAPI, dependencies: ExtensionDependencies = {}): void {
+  pi.on("session_before_compact", async (event, ctx) => {
+    if (VERSION !== SUPPORTED_PI_VERSION) {
+      ctx.ui.notify(
+        `[jev] skipped: Pi ${VERSION} is not ${SUPPORTED_PI_VERSION}; using Pi's native compaction.`,
+        "warning",
+      );
+      return;
+    }
+
+    const apiKey = dependencies.apiKey ?? process.env.TYPESAFE_API_KEY;
+    if (!apiKey && !dependencies.asker) {
+      ctx.ui.notify("[jev] skipped: TYPESAFE_API_KEY is not set; using Pi's native compaction.", "warning");
+      return;
+    }
+
+    const timeoutMs = parseTimeout(process.env.PI_FAST_JEV_TIMEOUT_MS);
+    const deadline = createDeadline(event.signal, timeoutMs, dependencies.timers);
+    const startedAt = Date.now();
+
+    try {
+      const asker = dependencies.asker ?? createJevAsker(apiKey as string, deadline.signal);
+      const filtered = await filterPreparation(
+        event.preparation.messagesToSummarize,
+        event.preparation.turnPrefixMessages,
+        { asker, signal: deadline.signal },
+      );
+
+      // User cancellation owns the outcome. Do not replace either input after it.
+      if (event.signal.aborted) return;
+
+      const elapsed = formatElapsed(Date.now() - startedAt);
+      if (!filtered.changed) {
+        ctx.ui.notify(
+          `[jev] ${filtered.candidateCalls} call(s) reviewed: nothing dropped · ${elapsed}; Pi will create the native summary.`,
+          "info",
+        );
+        return;
+      }
+
+      // These are the only preparation fields this extension changes. Pi still
+      // creates its own summary and compaction entry with its native metadata.
+      event.preparation.messagesToSummarize = filtered.messagesToSummarize;
+      event.preparation.turnPrefixMessages = filtered.turnPrefixMessages;
+      ctx.ui.notify(
+        `[jev] ${filtered.candidateCalls} call(s) reviewed: dropped ${filtered.droppedCalls}, shortened ${filtered.truncatedResults} · ${elapsed}; Pi will create the native summary.`,
+        "info",
+      );
+    } catch {
+      if (event.signal.aborted) return;
+      const elapsed = formatElapsed(Date.now() - startedAt);
+      if (deadline.timedOut()) {
+        ctx.ui.notify(`[jev] timed out after ${timeoutMs}ms · ${elapsed}; using Pi's native compaction.`, "warning");
+      } else {
+        ctx.ui.notify(`[jev] failed · ${elapsed}; using Pi's native compaction.`, "warning");
+      }
+    } finally {
+      deadline.dispose();
+    }
+  });
+}
+
+export default function fastJevCompaction(pi: ExtensionAPI): void {
+  install(pi);
+}

package/node_modules/fast-jev-compaction/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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.