pi-extensions-tool-display 1.2.0 → 1.3.1

package/README.md

@@ -8,6 +8,8 @@ It provides:
 - a pending registration queue for when the Pi display host loads later;
 - safe component detection and a helper for appending an audit panel to the original tool result.
 
+A result-render middleware registered for `"*"` really does run for every extension-registered tool: the host wires the middleware chain into any tool it does not already own, keeping the tool's own `renderResult` (or Pi's plain text preview when it has none) as the base. `isResultRenderPipelineActive` therefore reports `true` for those tools as well, so a consumer never needs to fall back to a separate transcript entry. Pi's own built-in tools stay behind the `registerToolOverrides` switches.
+
 It is also a standalone Pi extension. Install or include this package in Pi's package list to load the actual tool-display host. Feature package manifests include this dependency's extension entry, so installing either feature package loads one shared host without requiring a second host package.
 
 ## Boundary

package/README.zh-CN.md

@@ -8,6 +8,8 @@
 - Pi 展示宿主尚未加载时的 pending 注册队列；
 - 安全识别组件，以及把审计面板追加到原始工具结果后的通用组件组合。
 
+用 `"*"` 注册的结果渲染 middleware 会真的作用到每个扩展注册的工具上：宿主会把这套中间件链路接进自己还没接管的工具，基线保留工具自带的 `renderResult`（没有自带渲染时复刻 Pi 的纯文本预览）。`isResultRenderPipelineActive` 对这些工具也会返回 `true`，调用方不需要再退回「往会话里追加独立 entry」的兜底显示。Pi 自己的内建工具仍由 `registerToolOverrides` 的开关控制。
+
 它同时是一个独立的 Pi 扩展。可以把这个包直接加入 Pi 的 package 列表加载工具展示宿主；`pi-distill`、`pi-tool-supervisor` 的包清单也会声明这个依赖的扩展入口，因此安装功能包时只会加载一个公共宿主，不需要额外安装第二份宿主包。
 
 ## 设计边界

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensions-tool-display",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Pi tool display host and shared result-rendering protocol for extensions",
   "type": "module",
   "main": "./index.ts",
@@ -48,7 +48,7 @@
     "tool-display"
   ],
   "dependencies": {
-    "pi-extensions-i18n": "^0.5.0"
+    "pi-extensions-i18n": "^0.7.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.80.0",

package/src/index.ts

@@ -23,6 +23,7 @@ import {
   type ToolDisplayConfig,
 } from "./types.js";
 import {
+  installNoticeRenderer,
   notifyWithSource,
   type NoticeColor,
   type NoticeSource,
@@ -180,5 +181,7 @@ export default function toolDisplayExtension(
   pi: ExtensionAPI,
   initial: ConfigLoadResult = loadToolDisplayConfig(),
 ): void {
+  // 提示画成会话区里的带底色消息块；渲染器在本包这个模块实例里注册一次。
+  installNoticeRenderer(pi);
   ensureToolDisplayHost(pi, initial);
 }

package/src/result-middleware-coverage.ts

@@ -0,0 +1,51 @@
+/**
+ * 结果渲染中间件对工具行的覆盖。
+ *
+ * 中间件协议（`toolName: "*"`）的语义是「工具结果渲染时都会经过它」，但只有
+ * tool-display 自己装饰过的工具才会调用 `renderResultWithMiddleware`。没有被装饰的
+ * 工具（第三方扩展注册的工具、甚至没有 renderResult 的工具）拿不到中间件，调用方只
+ * 能退回「往会话里追加独立 entry」的兜底显示；这类 entry 长在工具行之外，折叠类扩展
+ * 收不到它，于是工具行收起了、审计行还留在原地。
+ *
+ * 这个模块提供把「被中间件命中、但我们还没接线的工具」补上接线所需的基线渲染：
+ * 工具自带 renderResult 时保留它，没有自带渲染时复刻 Pi 的默认结果块，接线前后观感
+ * 一致。
+ */
+
+import { Text } from "@earendil-works/pi-tui";
+import { sanitizeAnsiForThemedOutput } from "./ansi-utils.js";
+import { extractTextOutput, previewLines } from "./render-utils.js";
+
+interface RenderTheme {
+  fg(color: string, text: string): string;
+}
+
+interface ToolRenderResultOptions {
+  expanded?: boolean;
+  isPartial?: boolean;
+}
+
+/** Pi 在没有 renderResult 时只显示前 10 行；保持一致，接线后行数不变。 */
+export const GENERIC_RESULT_PREVIEW_LINES = 10;
+
+/**
+ * 复刻 Pi 的默认结果块：纯文本预览，折叠时超出部分给展开提示。
+ *
+ * 只用于没有自带 renderResult 的工具——它们本来就走 Pi 的这段渲染，这里复制一份是
+ * 为了让中间件有基线可挂，而不是改变这些工具的显示方式。
+ */
+export function renderGenericResultPreview(
+  result: unknown,
+  options: ToolRenderResultOptions,
+  theme: RenderTheme,
+): Text {
+  const output = sanitizeAnsiForThemedOutput(extractTextOutput(result as never)).replace(/\r/g, "");
+  const lines = output.length > 0 ? output.split("\n") : [];
+  const maxLines = options.expanded === true ? lines.length : GENERIC_RESULT_PREVIEW_LINES;
+  const { shown, remaining } = previewLines(lines, maxLines);
+  let text = shown.map((line) => theme.fg("toolOutput", line)).join("\n");
+  if (remaining > 0) {
+    text += theme.fg("muted", `\n... (${remaining} more lines, Ctrl+O to expand)`);
+  }
+  return new Text(text, 0, 0);
+}

package/src/tool-overrides.ts

@@ -27,6 +27,7 @@ import { resolvePiAgentDir } from "./agent-dir.js";
 import { renderBashCall } from "./bash-display.js";
 import { logToolDisplayDebug } from "./debug-logger.js";
 import { registerCleanup } from "./disposable.js";
+import { renderGenericResultPreview } from "./result-middleware-coverage.js";
 import {
   compactOutputLines,
   countNonEmptyLines,
@@ -183,6 +184,8 @@ export interface ToolDisplayApi {
   registerResultRenderMiddleware(registration: ToolResultRenderMiddlewareRegistration): string;
   unregisterResultRenderMiddleware(id: string): boolean;
   hasResultRenderMiddleware(id: string): boolean;
+  /** 已注册中间件命中过的工具名，含通配符 `*`。 */
+  listResultRenderMiddlewareToolNames(): string[];
   activateResultRenderPipeline(toolName: string): void;
   isResultRenderPipelineActive(toolName: string): boolean;
   renderResultWithMiddleware(
@@ -238,6 +241,15 @@ type PiWithRegisterToolInterception = ExtensionAPI & {
 const decoratedToolDescriptors = new WeakMap<RuntimeToolDefinition, ToolPropertyDescriptorSnapshot>();
 const decoratedTools = new Set<RuntimeToolDefinition>();
 
+/**
+ * 中间件注册之后的回调。
+ *
+ * 给工具补接线需要 pi 与当前工具列表，只有宿主拿得到，因此宿主在
+ * registerToolDisplayOverrides 里把自己那份实现挂上来；中间件在宿主安装之后才注册时
+ * （扩展加载顺序不固定），靠它立刻补上接线。
+ */
+let resultRenderMiddlewareRegistrationListener: (() => void) | undefined;
+
 function registerRuntimeTool(pi: ExtensionAPI, tool: RuntimeToolDefinition): void {
   pi.registerTool(tool as unknown as ToolDefinition);
 }
@@ -1613,6 +1625,7 @@ function installToolDisplayApi(getConfig: ConfigGetter): ToolDisplayApi {
     registerResultRenderMiddleware(registration: ToolResultRenderMiddlewareRegistration): string {
       const id = registration.id || `result-middleware-${++nextResultMiddlewareId}`;
       resultRenderMiddlewares.set(id, { ...registration, id });
+      resultRenderMiddlewareRegistrationListener?.();
       return id;
     },
     unregisterResultRenderMiddleware(id: string): boolean {
@@ -1621,6 +1634,9 @@ function installToolDisplayApi(getConfig: ConfigGetter): ToolDisplayApi {
     hasResultRenderMiddleware(id: string): boolean {
       return resultRenderMiddlewares.has(id);
     },
+    listResultRenderMiddlewareToolNames(): string[] {
+      return [...new Set([...resultRenderMiddlewares.values()].map((registration) => registration.toolName))];
+    },
     activateResultRenderPipeline(toolName: string): void {
       activeResultRenderPipelines.add(toolName);
     },
@@ -2196,6 +2212,118 @@ export function registerToolDisplayOverrides(
     wrappedMcpToolNames.add(toolName);
   };
 
+  /**
+   * 工具结果渲染函数的签名；包装与基线都用它。
+   */
+  type ResultRenderer = (
+    result: unknown,
+    options: ToolRenderResultOptions,
+    theme: RenderTheme,
+    context?: ToolRenderContextLike,
+  ) => unknown;
+
+  /** 已经补过接线的工具名，避免重复包装。 */
+  const resultMiddlewareCoveredToolNames = new Set<string>();
+  /**
+   * 补接线之前的 renderResult（包一层对象，用来区分「本来就没有」和「还没记录」）。
+   *
+   * 宿主被替换而旧宿主没跑清理时，工具上留的是上一轮的包装函数；只记最初那一份，
+   * 重复接线才不会把中间件套成多层。
+   */
+  const originalResultRenderers = new WeakMap<RuntimeToolDefinition, { renderResult?: ResultRenderer }>();
+
+  /** 取工具最初的 renderResult；同一个工具只取一次。 */
+  const getOriginalResultRenderer = (tool: RuntimeToolDefinition): ResultRenderer | undefined => {
+    const cached = originalResultRenderers.get(tool);
+    if (cached) {
+      return cached.renderResult;
+    }
+    const renderResult = typeof tool.renderResult === "function"
+      ? tool.renderResult as ResultRenderer
+      : undefined;
+    originalResultRenderers.set(tool, { renderResult });
+    return renderResult;
+  };
+
+  /** 已注册的中间件是否要求接管这个工具的结果渲染；通配符 `*` 要求所有工具。 */
+  const isResultMiddlewareTarget = (toolName: string): boolean => {
+    const registered = toolDisplayApi.listResultRenderMiddlewareToolNames();
+    return registered.includes("*") || registered.includes(toolName);
+  };
+
+  /**
+   * 是否是 Pi 自己的内建工具。
+   *
+   * 内建工具不在本次覆盖范围：它们的展示由 registerToolOverrides 的开关决定，只在
+   * 这里改渲染函数未必能作用到 Pi 已经建好的工具定义上。
+   */
+  const isPiBuiltInTool = (tool: RuntimeToolDefinition): boolean => {
+    return getTextField(toRecord(tool.sourceInfo), "source") === "builtin";
+  };
+
+  /**
+   * 给单个工具补接线：把它的结果渲染串进中间件链路。
+   *
+   * 只处理我们没接管的工具——内建工具与配置里的自定义工具，各自的渲染函数已经调用过
+   * 中间件。基线优先用工具自带的 renderResult，没有则复刻 Pi 的默认结果块，接线前后
+   * 观感一致，中间件只是多挂一个面板。
+   */
+  const coverToolForResultMiddlewares = (candidate: unknown): boolean => {
+    const tool = candidate as RuntimeToolDefinition;
+    const toolName = getTextField(tool, "name");
+    if (!toolName || isBuiltInToolName(toolName) || isPiBuiltInTool(tool)) {
+      return false;
+    }
+    if (resultMiddlewareCoveredToolNames.has(toolName) || !isResultMiddlewareTarget(toolName)) {
+      return false;
+    }
+
+    const originalRenderResult = getOriginalResultRenderer(tool);
+    const decorated = applyToolDisplayDecorationInPlace(tool, toolDisplayApi, {
+      kind: "generic",
+      overrideExistingRenderers: true,
+      renderResult: (result, options, theme, context) => toolDisplayApi.renderResultWithMiddleware(
+        { toolName, result, options, theme, renderContext: context },
+        () => originalRenderResult
+          ? originalRenderResult(result, options, theme, context)
+          : renderGenericResultPreview(result, options, theme),
+      ),
+    });
+    if (!decorated) {
+      return false;
+    }
+
+    resultMiddlewareCoveredToolNames.add(toolName);
+    toolDisplayApi.activateResultRenderPipeline(toolName);
+    return true;
+  };
+
+  /** 扫描当前全部工具，把被中间件命中的工具接上线。 */
+  const coverToolsForResultMiddlewares = (): void => {
+    const allTools = tryGetAllTools(pi, "Result middleware tool coverage discovery failed.");
+    if (!allTools) {
+      return;
+    }
+    for (const candidate of allTools) {
+      coverToolForResultMiddlewares(candidate);
+    }
+  };
+
+  /** 中间件注册后的回调：注册表变了就重扫一次，把新命中的工具接上线。 */
+  const resultMiddlewareListener = (): void => {
+    coverToolsForResultMiddlewares();
+  };
+  resultRenderMiddlewareRegistrationListener = resultMiddlewareListener;
+  registerCleanup(() => {
+    if (resultRenderMiddlewareRegistrationListener === resultMiddlewareListener) {
+      resultRenderMiddlewareRegistrationListener = undefined;
+    }
+    resultMiddlewareCoveredToolNames.clear();
+  });
+  // 中间件可能早于宿主注册（只进了等待队列），装完立即补一次；工具列表还拿不到时
+  // 交给 session_start / before_agent_start 那次扫描。
+  coverToolsForResultMiddlewares();
+
   const installMcpRegistrationInterceptor = (): void => {
     const piWithInterception = pi as PiWithRegisterToolInterception;
     const existingInterception = piWithInterception[TOOL_DISPLAY_REGISTER_TOOL_INTERCEPTOR_KEY];
@@ -2214,6 +2342,7 @@ export function registerToolDisplayOverrides(
         if (!decorateCustomToolOverrideCandidate(tool)) {
           decorateMcpToolCandidate(tool);
         }
+        coverToolForResultMiddlewares(tool);
       } catch (error) {
         logToolDisplayDebug("Tool display registration decoration failed.", error);
       }
@@ -2248,6 +2377,8 @@ export function registerToolDisplayOverrides(
       if (!decorateCustomToolOverrideCandidate(candidate)) {
         decorateMcpToolCandidate(candidate);
       }
+      // 自定义/MCP 覆盖会整体替换 renderResult，所以补接线必须排在它们之后。
+      coverToolForResultMiddlewares(candidate);
     }
   };