@sukeai/pi-logfwd 0.1.1 → 0.2.2

package/README.md

@@ -2,18 +2,20 @@
 
 实时命令日志转发：当 pi 运行命令时，把输出**实时流式**转发回来（而不是内置 bash 工具那样攒到最后一次性返回 + 截断）。
 
-- **bash_logged 工具**：pi 扩展，经 Go 二进制 `pi-logfwd` 在伪终端（PTY）中运行命令，JSONL 事件流逐块推送，可选追加日志文件。
+- **bash 工具（覆盖内置）**：pi 扩展注册名为 `bash`，同名覆盖 pi 内置的缓冲式 bash——模型每次调用 bash 都固定经 Go 二进制 `pi-logfwd` 在伪终端（PTY）中运行命令，JSONL 事件流逐块推送，可选追加日志文件。
 - **pi-logfwd 二进制**：跨平台预编译二进制，作为 npm 平台包随主包一起分发（见下方「平台支持」）。
 
 动机：pi 内置 bash/process 工具是缓冲式的——输出攒到最后一次性返回，且截断为末尾 2000 行 / 50KB；没有 TTY、没有交互输入通道。pi-logfwd 补上：实时流式输出、PTY 支持、日志落盘。
 
+> **为什么不叫 bash_logged**：早期版本注册成独立的 `bash_logged` 工具，与内置 `bash` 并列——模型每次执行命令都在两个工具间“随缘二选一”，导致 pi-logfwd 有时生效有时不生效（实测 23 个会话中仅 4 个用到，shell 调用占比约 3%）。0.2.0 起直接注册名为 `bash` 覆盖内置工具，触发从此 100% 确定：要么不用这个包，要用就全走实时转发。
+
 > 密码提示与 GUI 授权弹窗**不支持**（PTY 只能渲染提示、无人应答；弹窗无法程序化操作）——此时告诉用户手动执行。
 
 ## 架构
 
 ```
 pi (agent)
-  │  bash_logged 工具（@sukeai/pi-logfwd 扩展）
+  │  bash 工具（@sukeai/pi-logfwd 扩展，覆盖内置 bash）
   ▼
 pi-logfwd run -- "shell script"          ← 接收 shell 脚本 / 任意命令
   │  内部：PTY 分配（默认）或管道（--no-pty）
@@ -40,7 +42,15 @@ pi install /path/to/pi-log-forwarder
 pi -e npm:@sukeai/pi-logfwd
 ```
 
-装完在 pi 里 `/reload`，即可调用 `bash_logged` 工具（参数 `command` / `timeout` / `cwd` / `logFile` / `noPty`）。
+装完在 pi 里 `/reload`，内置 `bash` 即被替换——所有 shell 命令自动走实时转发（参数 `command` / `timeout` / `cwd` / `logFile` / `noPty` 可用）。想还原内置 bash：`pi remove npm:@sukeai/pi-logfwd` 后 `/reload`。
+
+## 工具结果标记
+
+每次调用的结果末尾会附加一行状态标记，命令失败**不会静默**：
+
+- 退出码非零 → `(exit code: N)`（真退出码取自 Go 端 JSONL `exit` 事件，非 pi-logfwd 进程自身退出码）
+- `timeout` 杀进程 → `(timed out after Ns, exit code 124)`（判据是 exit 事件的 `message: "killed by --timeout"`，命令自己 `exit 124` 不会被误判为超时）
+- 正常退出（0）→ 无标记
 
 ## 平台支持
 
@@ -56,7 +66,7 @@ pi -e npm:@sukeai/pi-logfwd
 
 **Windows 为什么不支持**：`pi-logfwd` 的 PTY 层用 creack/pty，它在 Windows 上直接返回 `ErrUnsupported`（`--no-pty` 管道模式理论上可行，但需额外改 shell 默认值/信号处理，成本高收益低），因此不发布 win32 平台包。
 
-**不支持的平台如何提醒**：全部平台包被 npm 跳过 → 二进制缺失 → `bash_logged` 不会静默报 ENOENT，而是返回明确说明：
+**不支持的平台如何提醒**：全部平台包被 npm 跳过 → 二进制缺失 → `bash`（pi-logfwd）不会静默报 ENOENT，而是返回明确说明：
 
 - **win32**：提示「Windows 不受支持（creack/pty ErrUnsupported），建议在 WSL/容器中运行 pi」；自行编译仅管道版可设 `PI_LOG_FWD_BIN` 绕过。
 - **其他缺二进制**：给出三种装法（`pi install npm:@sukeai/pi-logfwd` / `go build` / 放入 PATH 或 `~/.pi/agent/bin`）。
@@ -97,7 +107,7 @@ pi-logfwd run --timeout 30s 'npm run build'
 
 ```
 cmd/pi-logfwd/           Go 源码（main.go / runner.go）
-extension/extension.ts   pi 扩展：注册 bash_logged 工具（平台解析 + 提醒逻辑）
+extension/extension.ts   pi 扩展：注册 bash 工具覆盖内置（平台解析 + 提醒逻辑）
 package.json             主包（pi manifest + optionalDependencies 平台包列表）
 scripts/release.sh       交叉编译 + 发布（Go build → 平台包 → npm publish）
 scripts/set-version.js   主包/平台包版本同步

package/extension/extension.ts

@@ -1,10 +1,19 @@
 /**
- * pi-logfwd - pi package extension registering a "bash_logged" tool.
+ * pi-logfwd - pi package extension registering a "bash" tool that REPLACES
+ * pi's built-in (buffered) bash.
+ *
+ * 为什么注册名用 bash：pi 的工具注册表里与内置工具同名的扩展工具会覆盖内置定义
+ * （_refreshToolRegistry：先放 built-in，再按工具名 set 扩展工具）。注册成 bash
+ * 后，模型每次调用 bash 都固定走 pi-logfwd（PTY + 实时流式转发 + 可选日志文件），
+ * 不再存在 "bash / bash_logged 由模型随缘二选一" 的触发不规律问题。
  *
  * Runs commands through the Go binary `pi-logfwd` (PTY, real-time log
  * forwarding, optional log file). Streaming chunks are pushed into the
  * conversation via onUpdate, so output appears as it happens instead of
- * being buffered and truncated by the built-in bash tool.
+ * being buffered until the process exits. Output longer than MAX_CHARS is
+ * mirrored to a temp file (reported at the end) instead of silently losing
+ * its head - the safety net pi's built-in bash used to provide via
+ * temp files.
  *
  * Binary resolution order (checked on every execute):
  *   1. env PI_LOG_FWD_BIN                      (explicit override)
@@ -23,15 +32,19 @@
  * Install:
  *   pi install npm:@sukeai/pi-logfwd    # 推荐：随包自动装当前平台二进制
  *
+ *   装好后 /reload 即覆盖内置 bash（所有 shell 命令经 pi-logfwd 实时转发）；
+ *   想还原内置 bash：pi remove npm:@sukeai/pi-logfwd 后 /reload。
+ *
  * Dev / manual overrides:
  *   PI_LOG_FWD_BIN=/path/to/pi-logfwd   # 指向自建/自编译二进制
  *   cd cmd/pi-logfwd && go build -o ~/.pi/agent/bin/pi-logfwd ./cmd/pi-logfwd
  */
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
-import { existsSync } from "node:fs";
+import { createWriteStream, existsSync } from "node:fs";
+import { rm } from "node:fs/promises";
 import { createRequire } from "node:module";
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -39,7 +52,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 const require = createRequire(import.meta.url);
-const MAX_CHARS = 60_000;
+const MAX_CHARS = 60_000; // 会话文本保留的尾部上限；超出部分镜像到临时文件并报告路径
 const STREAM_INTERVAL_MS = 150;
 
 /** Prebuilt binary platform packages published alongside this package. */
@@ -77,7 +90,7 @@ function resolveBin(): Resolution {
 			bin: null,
 			notice:
 				"Windows 不受支持: pi-logfwd 的 PTY 依赖 (creack/pty) 在 Windows 上返回 ErrUnsupported，未发布 win32 预编译包。\n" +
-				"建议: 在 WSL / 容器中运行 pi 以使用 bash_logged。\n" +
+				"建议: 在 WSL / 容器中运行 pi 以使用本 bash 工具（实时转发）。\n" +
 				"自行交叉编译仅管道版本 (--no-pty，无 PTY) 后，可设 PI_LOG_FWD_BIN 指向该二进制以绕过此提示。",
 		};
 	}
@@ -118,22 +131,28 @@ function resolveBin(): Resolution {
 
 export default function (pi: ExtensionAPI) {
 	pi.registerTool({
-		name: "bash_logged",
-		label: "Bash (streamed log forward)",
+		name: "bash",
+		label: "bash",
 		description:
-			"Run a shell command or script through pi-logfwd and stream its logs back in real time. " +
-			"Prefer bash_logged over bash when you need: (a) real-time output streaming instead of " +
-			"end-buffered/truncated output, (b) a command that requires a pseudo-terminal (PTY), or " +
-			"(c) a persistent log file. " +
-			"NOT supported by any pi tool (including this one): interactive secret prompts " +
-			"(sudo/ssh password) and GUI authorization dialogs - PTY can render a prompt but nothing " +
-			"can answer it. For those, tell the user to run the command manually.",
-		promptSnippet: "Run a shell command with real-time log forwarding (PTY support)",
-		// 自定义 renderCall：TUI 里完整显示命令，并追加一行 log-fwd 标签标识控制来源
+			"Run a bash command in the current working directory through pi-logfwd (PTY, real-time " +
+			"log forwarding). Output is streamed back in real time instead of being buffered until " +
+			"the process exits; the conversation keeps the last 60000 chars and longer output is " +
+			"mirrored to a temp file whose path is reported at the end. The real exit status is never " +
+			"silent: a non-zero exit appends `(exit code: N)` and a tool-timeout kill appends " +
+			"`(timed out after Ns, exit code 124)` at the end of the result. This tool replaces " +
+			"pi's built-in buffered bash. NOT supported: interactive secret prompts (sudo/ssh " +
+			"password) and GUI authorization dialogs - PTY can render a prompt but nothing can " +
+			"answer it, so tell the user to run those manually. Optionally provide a timeout " +
+			"(seconds), cwd, logFile to append to, or noPty.",
+		promptSnippet: "Execute bash commands (ls, grep, find, etc.) with real-time streamed output (PTY)",
+		promptGuidelines: [
+			"You can inspect PI_* environment variables for current model and session details.",
+		],
+		// 自定义 renderCall：TUI 里完整显示命令，并追加一行 log-fwd 标签标识「经 pi-logfwd 实时转发」
 			renderCall(args, theme, _context) {
 				const command = typeof args.command === "string" ? args.command : "";
 				const commandDisplay = command || theme.fg("toolOutput", "...");
-				let text = theme.fg("toolTitle", theme.bold(`bash_logged ${commandDisplay}`));
+				let text = theme.fg("toolTitle", theme.bold(commandDisplay));
 				if (typeof args.timeout === "number") {
 					text += theme.fg("muted", ` (timeout ${args.timeout}s)`);
 				}
@@ -156,7 +175,7 @@ export default function (pi: ExtensionAPI) {
 			const res = resolveBin();
 			if (!res.ok) {
 				return {
-					content: [{ type: "text", text: `bash_logged 不可用:\n${res.notice}` }],
+					content: [{ type: "text", text: `bash (pi-logfwd) 不可用:\n${res.notice}` }],
 					details: { exitCode: null, forwarded: false, reason: "binary-unavailable" },
 				};
 			}
@@ -170,39 +189,64 @@ export default function (pi: ExtensionAPI) {
 
 			const child = spawn(res.bin, args, { cwd: ctx.cwd, env: process.env });
 
-			let accumulated = "";
+			// 全量镜像到临时文件（原内置 bash 的“完整输出”兜底）：输出 <= MAX_CHARS 时删除
+			// 临时文件；超长时在结果末尾报告文件路径。会话文本始终只保留尾部 MAX_CHARS。
+			let totalChars = 0;
+			let tail = "";
 			let lastStream = 0;
+			let logPath: string | null = null;
+			let logStream: import("node:fs").WriteStream | null = null;
 			const push = (chunk: string) => {
-				accumulated += chunk;
-				if (accumulated.length > MAX_CHARS * 2) accumulated = accumulated.slice(-MAX_CHARS);
+				totalChars += chunk.length;
+				if (!logStream) {
+					logPath = join(tmpdir(), `pi-logfwd-${process.pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}.log`);
+					logStream = createWriteStream(logPath, { flags: "a" });
+				}
+				logStream.write(chunk);
+				tail = (tail + chunk).slice(-MAX_CHARS);
 				const now = Date.now();
 				if (now - lastStream > STREAM_INTERVAL_MS) {
 					lastStream = now;
-					onUpdate?.({ content: [{ type: "text", text: accumulated.slice(-MAX_CHARS) }] });
+					onUpdate?.({ content: [{ type: "text", text: tail }] });
 				}
 			};
 
+			// 消费 JSONL：output 事件进流式文本；exit 事件携带「真正」的命令退出码
+			// （超时被杀为 124 + message "killed by --timeout"）。child(Go 进程) 的 close
+			// code 虽经 os.Exit 透传命令退出码，但 Go 自身报错/被杀时即偏离、且丢失
+			// timeout 的 message 与 durationMs；故一律以 exit 事件为准，close code 仅在
+			// 事件缺失时兜底。
+			type ExitInfo = { code: number | null; durationMs: number; message: string };
+			let exitEv: ExitInfo | null = null;
 			const rl = createInterface({ input: child.stdout });
 			rl.on("line", (line) => {
 				try {
 					const ev = JSON.parse(line);
-					if (ev.event === "output") push(ev.data);
+					if (ev.event === "output") {
+						push(ev.data);
+					} else if (ev.event === "exit") {
+						exitEv = {
+							code: typeof ev.code === "number" ? ev.code : null,
+							durationMs: typeof ev.durationMs === "number" ? ev.durationMs : 0,
+							message: typeof ev.message === "string" ? ev.message : "",
+						};
+					}
 				} catch {
 					/* ignore malformed lines */
 				}
 			});
 
-			let exitCode: number | null = null;
+			let goExitCode: number | null = null; // child(Go 进程) 自身退出码，仅作 exit 事件缺失时的兜底
 			let errText = "";
 			child.stderr.on("data", (d: Buffer) => (errText += d.toString()));
 			child.on("error", (e: Error) => {
 				if (e && (e as NodeJS.ErrnoException).code === "ENOENT") {
-					errText += `\nbash_logged 不可用: ${res.bin} 不存在或不可执行。\n${res.notice}`;
+					errText += `\nbash (pi-logfwd) 不可用: ${res.bin} 不存在或不可执行。\n${res.notice}`;
 				} else {
 					errText += `pi-logfwd: ${e.message}\n`;
 				}
 			});
-			child.on("close", (c) => (exitCode = c));
+			child.on("close", (c) => (goExitCode = c));
 			signal?.addEventListener("abort", () => child.kill("SIGTERM"), { once: true });
 
 			await new Promise<void>((resolve) => {
@@ -216,11 +260,49 @@ export default function (pi: ExtensionAPI) {
 				child.on("error", finish);
 			});
 
-			const text = (accumulated || "(no output)").slice(-MAX_CHARS);
-			const resultText = errText ? `${text}\n${errText.trimEnd()}` : text;
+			// 关闭日志流；只在文本被截断（输出超长）时保留临时文件
+			if (logStream) {
+				await new Promise<void>((r) => logStream!.end(() => r()));
+				if (totalChars <= MAX_CHARS && logPath) {
+					try {
+						await rm(logPath, { force: true });
+					} catch {
+						/* best-effort cleanup */
+					}
+					logPath = null;
+				}
+			}
+
+			// 真退出码优先（exit 事件）；只有 Go 进程异常退出（未发 exit 事件）时才退回其进程退出码。
+			const exitCode = exitEv ? exitEv.code : goExitCode;
+			// 超时判据只看 exit 事件 message：Go 端仅在 timeout 杀死时写 "killed by --timeout"；
+			// 命令自己 exit 124（如 gnu timeout 惯例）时 message 为空，不应误判为超时。
+			const timedOut = /timeout/i.test(exitEv?.message ?? "");
+
+			const text = tail || "(no output)";
+			const notes: string[] = [];
+			if (timedOut) {
+				const t =
+					typeof params.timeout === "number"
+						? `${params.timeout}s`
+						: `${((exitEv?.durationMs ?? 0) / 1000).toFixed(1)}s`;
+				notes.push(`(timed out after ${t}, exit code 124)`);
+			} else if (exitCode !== null && exitCode !== 0) {
+				notes.push(`(exit code: ${exitCode})`);
+			}
+
+			let resultText = errText ? `${text}\n${errText.trimEnd()}` : text;
+			if (notes.length) resultText += `\n${notes.join("\n")}`;
+			if (logPath) resultText += `\n(输出超长，完整日志已存 ${logPath})`;
 			return {
 				content: [{ type: "text", text: resultText }],
-				details: { exitCode, forwarded: true, logFile: params.logFile ?? null },
+				details: {
+					exitCode,
+					forwarded: true,
+					timedOut,
+					durationMs: exitEv?.durationMs ?? null,
+					logFile: params.logFile ?? null,
+				},
 			};
 		},
 	});

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@sukeai/pi-logfwd",
-	"version": "0.1.1",
-	"description": "pi package: bash_logged tool that streams command logs in real time through the pi-logfwd Go binary (PTY, JSONL events, optional log file) / pi 实时命令日志转发扩展",
+	"version": "0.2.2",
+	"description": "pi package: replaces the built-in bash tool with real-time log forwarding via the pi-logfwd Go binary (PTY, JSONL events, optional log file) / pi 实时命令日志转发扩展（bash 覆盖内置）",
 	"type": "module",
 	"license": "MIT",
 	"keywords": [
@@ -26,10 +26,10 @@
 		"typebox": "*"
 	},
 	"optionalDependencies": {
-		"@sukeai/pi-logfwd-darwin-arm64": "0.1.1",
-		"@sukeai/pi-logfwd-darwin-amd64": "0.1.1",
-		"@sukeai/pi-logfwd-linux-arm64": "0.1.1",
-		"@sukeai/pi-logfwd-linux-amd64": "0.1.1"
+		"@sukeai/pi-logfwd-darwin-arm64": "0.2.2",
+		"@sukeai/pi-logfwd-darwin-amd64": "0.2.2",
+		"@sukeai/pi-logfwd-linux-arm64": "0.2.2",
+		"@sukeai/pi-logfwd-linux-amd64": "0.2.2"
 	},
 	"pi": {
 		"extensions": [