pi-distill 0.3.0 → 0.3.1

package/README.md

@@ -4,6 +4,40 @@
 
 `pi-distill` is a Pi extension that controls how tool results enter the agent context. It does not replace tools or change how commands run; it adds an optional result-processing layer after the tool has returned its real output.
 
+## What it solves
+
+Coding agents often need only the important lines from a command, search, or file read. Passing every byte of a large result into the next turn increases context usage and can hide the signal in logs or generated files. `pi-distill` adds a result-level distillation layer without replacing Pi's built-in tools.
+
+## Context savings in practice
+
+Build logs, diff output, and test reports often contain repeated status lines, unchanged context, stack-trace noise, and details that are not needed for the next decision. Those are strong candidates for high compression. In one real Pi session, the result below went from 51,215 characters to 240 characters: **213.40× compression and 99.5% fewer output characters**.
+
+![pi-distill context savings example](./assets/context-savings-example.png)
+
+The screenshot reports character reduction, not an exact tokenizer measurement. In practice this usually removes a similar order of magnitude of context tokens, but the exact token saving depends on the language, content, and model tokenizer. Treat 90%+ as an observed outcome for suitable verbose outputs, not a guarantee for every command; use `RAW` whenever the complete output is needed.
+
+| Scenario | Typical noise | What the distill result keeps |
+| --- | --- | --- |
+| Build / compile | Repeated progress, warnings, and unchanged setup lines | Pass/fail, first actionable errors, affected files, and next steps |
+| Diff inspection | Large unchanged hunks and formatting noise | Changed files, relevant hunks, and review-relevant facts |
+| Tests | Per-test verbosity, snapshots, and framework boilerplate | Totals, failed cases, key assertions, and useful diagnostics |
+
+## Prompt language
+
+The distillation prompt strictly follows the current locale selected by `/pi-language`. Changing the persisted locale is picked up on the next tool call, including when the language command and `pi-distill` are loaded from separate package instances. `PI_EXTENSIONS_LOCALE` remains the explicit environment-variable override. The original user message is included only as language context and never overrides the selected locale.
+
+## How it works
+
+- Observes `bash`, `read`, `grep`, and `find` through Pi's native `tool_call` / `tool_result` events.
+- Uses the tool's `outputPrompt` as the source of truth for whether and how to distill a result.
+- Treats a prompt containing only `RAW` as an explicit request for the original output.
+- Uses the current session model by default, or a configured `provider/model` override.
+- Keeps diagnostic metadata such as status, character counts, compression ratio, duration, and anomalies in the tool result details.
+- Writes oversized distilled output or final output to a temporary file and returns its path instead of overflowing the tool result.
+- Adds a compact audit card when the active Pi display middleware is available, with a fallback renderer otherwise. The shared display protocol is provided by `pi-extensions-tool-display`.
+
+It does not register a second `bash`, `read`, `grep`, or `find` tool.
+
 ## Install
 
 ```bash
@@ -99,7 +133,7 @@ The distillation prompt strictly follows the locale selected by `/pi-language`:
 ## Scope and boundaries
 
 - Handles every active tool with an object parameter schema; whether `outputPrompt` can be injected is determined by the tool schema, not a fixed allowlist.
-- Registers no replacement tools, does not change tool execution semantics, and does not depend on `pi-tool-display`.
+- Registers no replacement tools, does not change tool execution semantics, and does not depend on the unrelated npm package `pi-tool-display`.
 - Text distillation is lossy; use `RAW` when completeness matters.
 - Non-text results are a completeness boundary: images, audio, binary data, and mixed content bypass text distillation.
 - Oversized distilled or final text is written to a temporary file and represented by its path, preventing unbounded context growth.

package/README.zh-CN.md

@@ -4,6 +4,40 @@
 
 `pi-distill` 是一个 Pi 扩展：它不替换工具，也不改变命令的执行方式，只在工具已经返回真实结果之后，帮助 Agent 决定哪些内容值得进入下一轮上下文。
 
+## 解决什么问题
+
+编码 Agent 通常只需要命令、搜索或文件读取结果中的关键信息。把大段日志、生成文件或搜索结果完整塞入下一轮，会增加上下文消耗，也容易让有效信号被噪声淹没。`pi-distill` 在不替换 Pi 内置工具的前提下，增加一层结果级提炼。
+
+## 实际上下文节省效果
+
+构建日志、diff 输出和测试报告经常包含重复状态行、未变化上下文、堆栈噪声，以及下一步决策并不需要的细节。这些内容通常很适合高比例压缩。下面这张真实 Pi 会话截图中，结果从 51,215 个字符压缩到 240 个字符：**213.40 倍压缩，输出字符减少 99.5%**。
+
+![pi-distill 上下文节省示例](./assets/context-savings-example.png)
+
+截图统计的是字符减少比例，不是 tokenizer 得出的精确 token 统计。实际使用时通常会带来同量级的上下文 token 节省，但精确数值取决于语言、内容和模型 tokenizer。对于适合压缩的冗长输出，90% 以上是已经观察到的效果，但不是每个命令的保证；需要完整输出时请使用 `RAW`。
+
+| 场景 | 常见噪声 | 提炼结果保留 |
+| --- | --- | --- |
+| 构建 / 编译 | 重复进度、警告和未变化的环境信息 | 成功/失败、首个可行动错误、受影响文件和后续步骤 |
+| Diff 检查 | 大量未变化 hunk 和格式化噪声 | 变更文件、相关 hunk 和评审所需事实 |
+| 测试 | 单测逐条输出、snapshot 和框架模板 | 总数、失败用例、关键断言和有效诊断 |
+
+## Prompt 语言
+
+提炼 prompt 会严格跟随 `/pi-language` 当前选择的语言。持久化语言发生变化后，下一次工具调用会读取新设置，即使语言命令和 `pi-distill` 来自不同的包实例也可以同步。`PI_EXTENSIONS_LOCALE` 仍然是显式的环境变量覆盖项。原始用户消息只作为语言上下文传入，不能覆盖已选择的语言。
+
+## 工作方式
+
+- 通过 Pi 原生的 `tool_call` / `tool_result` 事件监听 `bash`、`read`、`grep` 和 `find`。
+- 以工具的 `outputPrompt` 作为是否提炼、如何提炼的依据。
+- 当提示词严格只有 `RAW` 时，视为明确要求返回原始输出。
+- 默认使用当前会话模型，也可以配置独立的 `provider/model`。
+- 在工具结果 details 中保留状态、字符数、压缩比、耗时和异常等诊断信息。
+- 提炼结果或最终返回结果过大时写入临时文件，只把文件路径返回给 Agent，避免工具结果失控膨胀。
+- 当前 Pi 展示中间件可用时显示紧凑审计卡片，否则使用自己的 fallback renderer。展示协议由公共运行库 `pi-extensions-tool-display` 提供。
+
+它不会注册第二个 `bash`、`read`、`grep` 或 `find` 工具。
+
 ## 安装
 
 ```bash
@@ -101,7 +135,7 @@ Agent 消费更适合当前决策的结果，并获得可审计的处理诊断
 ## 覆盖范围与边界
 
 - 自动处理所有当前已启用且参数 schema 为 object 的工具；能否注入 `outputPrompt` 由工具 schema 决定，不维护固定工具名单。
-- 不注册替代工具，不改变原工具的执行语义，也不依赖 `pi-tool-display`。
+- 不注册替代工具，不改变原工具的执行语义，也不依赖无关的 npm 包 `pi-tool-display`。
 - 文本提炼是有损操作；完整性要求应使用 `RAW`。
 - 非文本结果是完整性边界：图片、音频、二进制和混合 content 不进入文本提炼链路。
 - 提炼结果或最终文本过大时写入临时文件并返回路径，避免上下文无限膨胀。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-distill",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Pi tool-output distillation with file-first configuration",
   "type": "module",
   "files": [
@@ -51,6 +51,9 @@
     "@earendil-works/pi-tui": ">=0.80.0 <0.81.0",
     "pi-extensions-i18n": "^0.3.0"
   },
+  "dependencies": {
+    "pi-extensions-tool-display": "^0.1.1"
+  },
   "devDependencies": {
     "@earendil-works/pi-ai": "0.80.10",
     "@earendil-works/pi-coding-agent": "0.80.10",

package/src/tool-display-bridge.ts

@@ -1,47 +1,14 @@
-import { Container, type Component } from "@earendil-works/pi-tui";
+import {
+  appendResultRenderPanel,
+  isResultRenderMiddlewareActive,
+  registerResultRenderMiddleware,
+  type ResultMiddleware,
+} from "pi-extensions-tool-display";
 import { buildDistillAuditLines, createDistillAuditComponent, resolveDistillRenderConfig } from "./fallback-renderer.ts";
 import { loadDistillConfig } from "./summary-utils.ts";
 
-const TOOL_DISPLAY_API_KEY = Symbol.for("pi-tool-display.api.v1");
-const PENDING_MIDDLEWARES_KEY = Symbol.for("pi-tool-display.pendingResultRenderMiddlewares.v1");
 const DISTILL_MIDDLEWARE_ID = "pi-distill.result-renderer.v1";
 
-type RenderTheme = {
-  fg(color: string, text: string): string;
-  bold(text: string): string;
-};
-
-type MiddlewareContext = {
-  toolName: string;
-  result: unknown;
-  options: { expanded?: boolean };
-  theme: RenderTheme;
-};
-
-type ResultMiddleware = (context: MiddlewareContext, next: () => unknown) => unknown;
-
-type MiddlewareRegistration = {
-  id: string;
-  toolName: string;
-  middleware: ResultMiddleware;
-};
-
-type ToolDisplayApi = {
-  registerResultRenderMiddleware?(registration: MiddlewareRegistration): string;
-  unregisterResultRenderMiddleware?(id: string): boolean;
-  hasResultRenderMiddleware?(id: string): boolean;
-  isResultRenderPipelineActive?(toolName: string): boolean;
-};
-
-type GlobalProtocol = typeof globalThis & {
-  [TOOL_DISPLAY_API_KEY]?: ToolDisplayApi;
-  [PENDING_MIDDLEWARES_KEY]?: MiddlewareRegistration[];
-};
-
-function getApi(): ToolDisplayApi | undefined {
-  return (globalThis as GlobalProtocol)[TOOL_DISPLAY_API_KEY];
-}
-
 function getDetails(result: unknown): Record<string, unknown> | undefined {
   if (!result || typeof result !== "object" || Array.isArray(result)) return undefined;
   const details = (result as Record<string, unknown>).details;
@@ -50,12 +17,6 @@ function getDetails(result: unknown): Record<string, unknown> | undefined {
     : undefined;
 }
 
-function asComponent(value: unknown): Component | undefined {
-  return value && typeof value === "object" && typeof (value as Component).render === "function"
-    ? value as Component
-    : undefined;
-}
-
 const distillMiddleware: ResultMiddleware = (context, next) => {
   const details = getDetails(context.result);
   if (!details) return next();
@@ -75,49 +36,17 @@ const distillMiddleware: ResultMiddleware = (context, next) => {
     && details.summaryText.trim().length > 0;
   if (summarized) return panel;
 
-  const base = asComponent(next());
-  if (!base) return panel;
-  const container = new Container();
-  container.addChild(base);
-  container.addChild(panel);
-  return container;
+  return appendResultRenderPanel(next(), panel);
 };
 
-function queueRegistration(registration: MiddlewareRegistration): void {
-  const globalProtocol = globalThis as GlobalProtocol;
-  const queue = Array.isArray(globalProtocol[PENDING_MIDDLEWARES_KEY])
-    ? globalProtocol[PENDING_MIDDLEWARES_KEY]!
-    : [];
-  const index = queue.findIndex((entry) => entry?.id === registration.id);
-  if (index >= 0) queue[index] = registration;
-  else queue.push(registration);
-  globalProtocol[PENDING_MIDDLEWARES_KEY] = queue;
-}
-
 export function registerDistillToolDisplayMiddleware(): () => void {
-  const registration: MiddlewareRegistration = {
+  return registerResultRenderMiddleware({
     id: DISTILL_MIDDLEWARE_ID,
     toolName: "*",
     middleware: distillMiddleware,
-  };
-  const api = getApi();
-  if (typeof api?.registerResultRenderMiddleware === "function") {
-    api.registerResultRenderMiddleware(registration);
-  } else {
-    queueRegistration(registration);
-  }
-
-  return () => {
-    getApi()?.unregisterResultRenderMiddleware?.(DISTILL_MIDDLEWARE_ID);
-    const queue = (globalThis as GlobalProtocol)[PENDING_MIDDLEWARES_KEY];
-    if (!Array.isArray(queue)) return;
-    const index = queue.findIndex((entry) => entry?.id === DISTILL_MIDDLEWARE_ID);
-    if (index >= 0) queue.splice(index, 1);
-  };
+  });
 }
 
 export function isDistillToolDisplayMiddlewareActive(toolName: string): boolean {
-  const api = getApi();
-  return api?.hasResultRenderMiddleware?.(DISTILL_MIDDLEWARE_ID) === true
-    && api.isResultRenderPipelineActive?.(toolName) === true;
+  return isResultRenderMiddlewareActive(DISTILL_MIDDLEWARE_ID, toolName);
 }