pi-extensions-tool-display 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-extensions-tool-display
 
-`pi-extensions-tool-display` provides the shared tool-result rendering protocol and component helpers used by Pi extensions.
+`pi-extensions-tool-display` provides the Pi tool-display host plus the shared tool-result rendering protocol and component helpers used by Pi extensions.
 
 It provides:
 
@@ -8,7 +8,7 @@ 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.
 
-It is not a standalone Pi extension: it registers no tools, commands, or entry renderers. It is intended to be consumed as a runtime dependency by extensions such as `pi-distill` and `pi-tool-supervisor`.
+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 packages such as `pi-distill` and `pi-tool-supervisor` initialize the same host through this runtime dependency, so installing either feature package is sufficient and does not require a second host package.
 
 ## Boundary
 
@@ -18,7 +18,17 @@ This package owns the display protocol and generic component composition only. E
 
 The display integration is designed to work with the MIT-licensed [`MasuRii/pi-tool-display`](https://github.com/MasuRii/pi-tool-display), the original full-featured Pi tool-display project. We thank MasuRii for that work.
 
-This package is a separate shared-runtime extraction from this repository's own extension bridges. It does not bundle or redistribute `pi-tool-display`'s implementation; the upstream project remains the reference for full tool rendering.
+The host implementation is based on the MIT-licensed upstream project and is now maintained in this package so consumers do not need a second separately installed host package.
+
+## Install
+
+Install this package directly when you want only the tool-display host:
+
+```bash
+pi install npm:pi-extensions-tool-display
+```
+
+`pi-distill` and `pi-tool-supervisor` also initialize the host automatically when they are loaded.
 
 ## Development
 

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 # pi-extensions-tool-display
 
-`pi-extensions-tool-display` 是 Pi 扩展共享的工具结果展示协议和组件工具包。
+`pi-extensions-tool-display` 提供 Pi 工具展示宿主，以及扩展共享的工具结果展示协议和组件工具包。
 
 它提供：
 
@@ -8,17 +8,27 @@
 - Pi 展示宿主尚未加载时的 pending 注册队列；
 - 安全识别组件，以及把审计面板追加到原始工具结果后的通用组件组合。
 
-它不是一个独立的 Pi 扩展，不注册工具、命令或 entry renderer。通常由 `pi-distill`、`pi-tool-supervisor` 等扩展作为运行时依赖使用。
+它同时是一个独立的 Pi 扩展。可以把这个包直接加入 Pi 的 package 列表加载工具展示宿主；`pi-distill`、`pi-tool-supervisor` 等功能包加载时也会通过这个运行时依赖自动初始化同一个宿主，不需要额外安装第二份宿主包。
 
 ## 设计边界
 
-这个包只负责展示协议和通用组件组合。具体业务的审计数据提取、文案、状态和布局仍由调用方维护，避免把不同扩展耦合在一起。
+这个包负责实际工具展示、展示协议和通用组件组合。具体业务的审计数据提取、文案、状态和布局仍由调用方维护，避免把不同扩展耦合在一起。
 
 ## 上游引用
 
 本包的展示集成设计用于兼容 MIT 许可的 [`MasuRii/pi-tool-display`](https://github.com/MasuRii/pi-tool-display)，这是 Pi 生态中原始的完整工具展示项目。感谢 MasuRii 的工作。
 
-本包是从本仓库自身的扩展 bridge 中提取出的独立共享运行时，不打包或再发布 `pi-tool-display` 的实现；完整工具渲染仍以上游项目为参考实现。
+宿主实现基于 MIT 许可的上游项目，并迁移到本包中统一维护，消费者不再需要额外安装第二个宿主包。
+
+## 安装
+
+如果只需要工具展示宿主，可以直接安装：
+
+```bash
+pi install npm:pi-extensions-tool-display
+```
+
+安装 `pi-distill` 或 `pi-tool-supervisor` 时，宿主也会由共享运行时自动初始化。
 
 ## 开发
 

package/config.example.json

@@ -0,0 +1,40 @@
+{
+  "enabled": true,
+  "debug": false,
+  "registerToolOverrides": {
+    "read": true,
+    "grep": true,
+    "find": true,
+    "ls": true,
+    "bash": true,
+    "edit": true,
+    "write": true
+  },
+  "customToolOverrides": {
+    "ide_find_symbol": {
+      "enabled": false,
+      "kind": "generic",
+      "outputMode": "summary"
+    },
+    "custom_mcp_gateway": {
+      "enabled": false,
+      "kind": "mcp",
+      "outputMode": "summary"
+    }
+  },
+  "enableNativeUserMessageBox": true,
+  "readOutputMode": "hidden",
+  "searchOutputMode": "hidden",
+  "mcpOutputMode": "hidden",
+  "previewLines": 8,
+  "expandedPreviewMaxLines": 4000,
+  "bashOutputMode": "opencode",
+  "bashCollapsedLines": 10,
+  "diffViewMode": "auto",
+  "diffIndicatorMode": "bars",
+  "diffSplitMinWidth": 120,
+  "diffCollapsedLines": 24,
+  "diffWordWrap": true,
+  "showTruncationHints": false,
+  "showRtkCompactionHints": false
+}

package/index.ts

@@ -0,0 +1,6 @@
+import toolDisplayExtension from "./src/index.js";
+
+export { ensureToolDisplayHost, toolDisplayReloadRequired } from "./src/index.js";
+export * from "./src/result-render-middleware.js";
+
+export default toolDisplayExtension;

package/package.json

@@ -1,20 +1,24 @@
 {
   "name": "pi-extensions-tool-display",
-  "version": "0.1.1",
-  "description": "Shared result-rendering protocol and component helpers for Pi extensions",
+  "version": "0.2.0",
+  "description": "Pi tool display host and shared result-rendering protocol for extensions",
   "type": "module",
-  "main": "./src/index.ts",
+  "main": "./index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./index.ts"
   },
   "files": [
+    "index.ts",
+    "tool-display-api-consumer.js",
+    "tool-display-api-consumer.d.ts",
     "src",
+    "config.example.json",
     "README.md",
     "README.zh-CN.md",
     "tsconfig.json"
   ],
   "scripts": {
-    "test": "tsx --test tests/tool-display.test.ts",
+    "test": "tsx --test tests/*.test.ts",
     "typecheck": "tsc --noEmit --pretty false",
     "build": "npm run typecheck",
     "check": "npm run typecheck && npm test && npm pack --dry-run --json > /dev/null"
@@ -43,9 +47,16 @@
     "tool-display"
   ],
   "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.80.0 <0.81.0",
     "@earendil-works/pi-tui": ">=0.80.0 <0.81.0"
   },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
   "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.80.10",
     "@earendil-works/pi-tui": "0.80.10",
     "@types/node": "24.12.4",
     "tsx": "4.23.1",

package/src/agent-dir.ts

@@ -0,0 +1,32 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const PI_AGENT_DIR_ENV_VAR = "PI_CODING_AGENT_DIR";
+
+interface AgentDirEnvironment {
+	[name: string]: string | undefined;
+}
+
+function expandHomeDirectory(configuredDir: string, homeDirectory: string): string {
+	if (configuredDir === "~") {
+		return homeDirectory;
+	}
+
+	if (configuredDir.startsWith("~/") || configuredDir.startsWith("~\\")) {
+		return join(homeDirectory, configuredDir.slice(2));
+	}
+
+	return configuredDir;
+}
+
+export function resolvePiAgentDir(
+	env: AgentDirEnvironment = process.env,
+	homeDirectory = homedir(),
+): string {
+	const configuredDir = env[PI_AGENT_DIR_ENV_VAR];
+	if (!configuredDir) {
+		return join(homeDirectory, ".pi", "agent");
+	}
+
+	return expandHomeDirectory(configuredDir, homeDirectory);
+}

package/src/ansi-utils.ts

@@ -0,0 +1,116 @@
+const ANSI_SGR_PATTERN = /\x1b\[([0-9;]*)m/g;
+const STYLE_RESET_PARAMS = [39, 22, 23, 24, 25, 27, 28, 29, 59] as const;
+
+export { ANSI_SGR_PATTERN, STYLE_RESET_PARAMS };
+
+export function expandSgrReset(param: number): readonly number[] | undefined {
+  return param === 0 ? STYLE_RESET_PARAMS : undefined;
+}
+
+export function toSgrParams(rawParams: string): number[] {
+  if (!rawParams.trim()) {
+    return [0];
+  }
+
+  const parsed = rawParams
+    .split(";")
+    .map((token) => Number.parseInt(token, 10))
+    .filter((value) => Number.isFinite(value));
+
+  return parsed.length > 0 ? parsed : [];
+}
+
+export function isFiniteSgrParam(value: number | undefined): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+export function readSgrColorSequence(params: number[], index: number): number[] | undefined {
+  const param = params[index];
+  if (param !== 38 && param !== 48) {
+    return undefined;
+  }
+
+  const colorMode = params[index + 1];
+  if (colorMode === 5) {
+    const colorValue = params[index + 2];
+    return isFiniteSgrParam(colorValue) ? [param, colorMode, colorValue] : undefined;
+  }
+
+  if (colorMode === 2) {
+    const red = params[index + 2];
+    const green = params[index + 3];
+    const blue = params[index + 4];
+    return isFiniteSgrParam(red) && isFiniteSgrParam(green) && isFiniteSgrParam(blue)
+      ? [param, colorMode, red, green, blue]
+      : undefined;
+  }
+
+  return undefined;
+}
+
+export function stripBackgroundSgrParams(params: readonly number[]): number[] {
+  const sanitized: number[] = [];
+
+  for (let index = 0; index < params.length; index++) {
+    const param = params[index] ?? 0;
+
+    if (param === 0) {
+      sanitized.push(...expandSgrReset(param)!);
+      continue;
+    }
+
+    if (param === 49 || (param >= 40 && param <= 47) || (param >= 100 && param <= 107)) {
+      continue;
+    }
+
+    if (param === 38 || param === 48) {
+      const sequence = readSgrColorSequence(params as number[], index);
+      if (sequence) {
+        if (param === 38) {
+          sanitized.push(...sequence);
+        }
+        index += sequence.length - 1;
+        continue;
+      }
+      const advance = params[index + 1] === 5 ? 2 : params[index + 1] === 2 ? 4 : 0;
+      if (advance > 0) {
+        index += advance;
+        if (param === 38) {
+          sanitized.push(param);
+        }
+        continue;
+      }
+    }
+
+    sanitized.push(param);
+  }
+
+  return sanitized;
+}
+
+export function filterSgrSequences(
+  text: string,
+  filter: (params: number[]) => number[],
+): string {
+  if (!text || !text.includes("\x1b[")) {
+    return text;
+  }
+
+  return text.replace(ANSI_SGR_PATTERN, (_sequence, rawParams: string) => {
+    const parsed = toSgrParams(rawParams);
+    if (parsed.length === 0) {
+      return "";
+    }
+
+    const sanitized = filter(parsed);
+    if (sanitized.length === 0) {
+      return "";
+    }
+
+    return `\x1b[${sanitized.join(";")}m`;
+  });
+}
+
+export function sanitizeAnsiForThemedOutput(text: string): string {
+  return filterSgrSequences(text, stripBackgroundSgrParams);
+}

package/src/bash-display.ts

@@ -0,0 +1,191 @@
+import { Text } from "@earendil-works/pi-tui";
+import { registerCleanup, registerTimer } from "./disposable.js";
+
+const BASH_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
+const BASH_SPINNER_INTERVAL_MS = 200;
+const BASH_SPINNER_STATE_KEY = "__piToolDisplayBashSpinner";
+const BASH_SPINNER_TOOL_CALL_ID_KEY = "__piToolDisplayBashSpinnerToolCallId";
+
+interface BashCallArgs {
+	command?: string;
+	commandPrefix?: string;
+	shellPath?: string;
+	timeout?: number;
+}
+
+interface BashCallRenderTheme {
+	fg(color: string, text: string): string;
+	bold(text: string): string;
+}
+
+interface BashSpinnerState {
+	frameIndex: number;
+	startedAt?: number;
+	timer?: ReturnType<typeof setInterval>;
+}
+
+interface BashSpinnerStateCarrier {
+	[BASH_SPINNER_STATE_KEY]?: BashSpinnerState;
+	[BASH_SPINNER_TOOL_CALL_ID_KEY]?: string;
+}
+
+interface BashCallRenderContextLike {
+	executionStarted: boolean;
+	isPartial: boolean;
+	invalidate?: () => void;
+	lastComponent?: unknown;
+	state?: unknown;
+	toolCallId?: string;
+}
+
+const spinnerStatesByToolCallId = new Map<string, BashSpinnerState>();
+let nextSyntheticToolCallId = 0;
+
+function toStateCarrier(value: unknown): BashSpinnerStateCarrier | undefined {
+	if (!value || typeof value !== "object") {
+		return undefined;
+	}
+	return value as BashSpinnerStateCarrier;
+}
+
+function getSyntheticToolCallId(carrier: BashSpinnerStateCarrier | undefined): string | undefined {
+	if (!carrier) {
+		return undefined;
+	}
+
+	if (!carrier[BASH_SPINNER_TOOL_CALL_ID_KEY]) {
+		carrier[BASH_SPINNER_TOOL_CALL_ID_KEY] = `state:${++nextSyntheticToolCallId}`;
+	}
+	return carrier[BASH_SPINNER_TOOL_CALL_ID_KEY];
+}
+
+function getToolCallId(context: BashCallRenderContextLike): string | undefined {
+	if (typeof context.toolCallId === "string" && context.toolCallId.trim().length > 0) {
+		return context.toolCallId;
+	}
+	return getSyntheticToolCallId(toStateCarrier(context.state));
+}
+
+function getOrCreateSpinnerState(
+	toolCallId: string | undefined,
+	carrier: BashSpinnerStateCarrier | undefined,
+): BashSpinnerState | undefined {
+	if (!toolCallId) {
+		return undefined;
+	}
+
+	let state = spinnerStatesByToolCallId.get(toolCallId);
+	if (!state) {
+		state = { frameIndex: 0 };
+		spinnerStatesByToolCallId.set(toolCallId, state);
+	}
+	if (carrier) {
+		carrier[BASH_SPINNER_STATE_KEY] = state;
+	}
+	return state;
+}
+
+function stopSpinner(toolCallId: string | undefined, state: BashSpinnerState | undefined): void {
+	if (!state) {
+		return;
+	}
+
+	if (state.timer) {
+		clearInterval(state.timer);
+		state.timer = undefined;
+	}
+	state.frameIndex = 0;
+	state.startedAt = undefined;
+	if (toolCallId) {
+		spinnerStatesByToolCallId.delete(toolCallId);
+	}
+}
+
+function formatElapsed(elapsedMs: number): string {
+	const totalSeconds = Math.max(0, Math.floor(elapsedMs / 1000));
+	if (totalSeconds < 60) {
+		return `${totalSeconds}s`;
+	}
+
+	const totalMinutes = Math.floor(totalSeconds / 60);
+	const seconds = totalSeconds % 60;
+	if (totalMinutes < 60) {
+		return `${totalMinutes}m ${seconds}s`;
+	}
+
+	const hours = Math.floor(totalMinutes / 60);
+	const minutes = totalMinutes % 60;
+	return `${hours}h ${minutes}m`;
+}
+
+function isDefaultShellPath(shellPath: string): boolean {
+	const normalized = shellPath.trim().replace(/\\/g, "/").toLowerCase();
+	const basename = normalized.split("/").pop() || normalized;
+	return basename === "bash" || basename === "cmd.exe";
+}
+
+function buildCommandDisplay(args: BashCallArgs): string {
+	const command =
+		typeof args.command === "string" && args.command.trim().length > 0
+			? args.command
+			: "...";
+	const prefix =
+		typeof args.commandPrefix === "string" && args.commandPrefix.trim().length > 0
+			? args.commandPrefix.trim()
+			: "";
+	return prefix ? `${prefix} ${command}` : command;
+}
+
+function buildBashCallText(
+	args: BashCallArgs,
+	theme: BashCallRenderTheme,
+	spinnerFrame?: string,
+	elapsedMs?: number,
+): string {
+	const commandDisplay = buildCommandDisplay(args);
+	const shellSuffix =
+		typeof args.shellPath === "string" &&
+		args.shellPath.trim().length > 0 &&
+		!isDefaultShellPath(args.shellPath)
+			? theme.fg("muted", ` [shell: ${args.shellPath}]`)
+			: "";
+	const timeoutSuffix = args.timeout
+		? theme.fg("muted", ` (timeout ${args.timeout}s)`)
+		: "";
+	const spinnerPrefix = spinnerFrame ? `${theme.fg("warning", `${spinnerFrame} `)}` : "";
+	const elapsedSuffix =
+		spinnerFrame && elapsedMs !== undefined
+			? theme.fg("muted", ` · ${formatElapsed(elapsedMs)}`)
+			: "";
+	return `${spinnerPrefix}${theme.fg("toolTitle", theme.bold("$"))} ${theme.fg("accent", commandDisplay)}${shellSuffix}${timeoutSuffix}${elapsedSuffix}`;
+}
+
+export function renderBashCall(
+	args: BashCallArgs,
+	theme: BashCallRenderTheme,
+	context: BashCallRenderContextLike,
+): Text {
+	const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+	const carrier = toStateCarrier(context.state);
+	const toolCallId = getToolCallId(context);
+	const spinnerState = getOrCreateSpinnerState(toolCallId, carrier);
+	const shouldSpin = context.executionStarted && context.isPartial;
+
+	if (!shouldSpin) {
+		stopSpinner(toolCallId, spinnerState);
+		text.setText(buildBashCallText(args, theme));
+		return text;
+	}
+
+	// Bash 总结模型执行期间工具会长时间保持 partial。动态 spinner 会不断修改
+	// Text，并触发 TUI 重绘，即使不显式 invalidate 也可能造成闪烁。因此只显示
+	// 一个静态执行标记，彻底避免定时器和动画带来的重绘。
+	if (spinnerState) {
+		spinnerState.startedAt ??= Date.now();
+		if (spinnerState.timer) {
+			stopSpinner(toolCallId, spinnerState);
+		}
+	}
+	text.setText(buildBashCallText(args, theme, spinnerState ? "⏳" : undefined));
+	return text;
+}

package/src/capabilities.ts

@@ -0,0 +1,85 @@
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { resolvePiAgentDir } from "./agent-dir.js";
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { logToolDisplayDebug } from "./debug-logger.js";
+import { isMcpToolCandidate } from "./tool-metadata.js";
+import type { ToolDisplayConfig } from "./types.js";
+
+export interface ToolDisplayCapabilities {
+	hasMcpTooling: boolean;
+	hasRtkOptimizer: boolean;
+}
+
+function hasMcpTooling(pi: ExtensionAPI): boolean {
+	try {
+		const allTools = pi.getAllTools();
+		return allTools.some((tool) => isMcpToolCandidate(tool));
+	} catch (error) {
+		logToolDisplayDebug("MCP capability detection failed.", error);
+		return false;
+	}
+}
+
+function hasRtkCommand(pi: ExtensionAPI): boolean {
+	try {
+		const commands = pi.getCommands();
+		return commands.some((command) => typeof command.name === "string" && (command.name === "rtk" || command.name.startsWith("rtk-")));
+	} catch (error) {
+		logToolDisplayDebug("RTK command capability detection failed.", error);
+		return false;
+	}
+}
+
+const rtkPathProbeCache = new Map<string, { fingerprint: string; exists: boolean }>();
+
+function getPathFingerprint(path: string): string {
+	try {
+		const stats = statSync(path);
+		return `${stats.mtimeMs}:${stats.size}`;
+	} catch {
+		return "missing";
+	}
+}
+
+function cachedPathExists(path: string): boolean {
+	const fingerprint = getPathFingerprint(path);
+	const cached = rtkPathProbeCache.get(path);
+	if (cached && cached.fingerprint === fingerprint) {
+		return cached.exists;
+	}
+
+	let exists = false;
+	try {
+		exists = existsSync(path);
+	} catch (error) {
+		logToolDisplayDebug(`RTK capability path probe failed for ${path}.`, error);
+	}
+	rtkPathProbeCache.set(path, { fingerprint, exists });
+	return exists;
+}
+
+function hasRtkExtensionPath(cwd: string): boolean {
+	const candidates = [join(resolvePiAgentDir(), "extensions", "pi-rtk-optimizer"), join(cwd, ".pi", "extensions", "pi-rtk-optimizer")];
+
+	return candidates.some((candidate) => cachedPathExists(candidate));
+}
+
+export function detectToolDisplayCapabilities(pi: ExtensionAPI, cwd: string): ToolDisplayCapabilities {
+	return {
+		hasMcpTooling: hasMcpTooling(pi),
+		hasRtkOptimizer: hasRtkCommand(pi) || hasRtkExtensionPath(cwd),
+	};
+}
+
+export function applyCapabilityConfigGuards(
+	config: ToolDisplayConfig,
+	capabilities: ToolDisplayCapabilities,
+): ToolDisplayConfig {
+	return {
+		...config,
+		registerToolOverrides: { ...config.registerToolOverrides },
+		mcpOutputMode: config.mcpOutputMode,
+		showRtkCompactionHints: capabilities.hasRtkOptimizer ? config.showRtkCompactionHints : false,
+	};
+}