@trim21/personal-pi-extensions 0.0.247 → 0.0.251

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.247",
+  "version": "0.0.251",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/bwrap/runtime.ts

@@ -1,9 +1,19 @@
+import { randomUUID } from "node:crypto";
+import { createWriteStream, mkdirSync, type WriteStream } from "node:fs";
+import { join } from "node:path";
+
 import type {
+  AgentToolUpdateCallback,
   ExtensionAPI,
   ExtensionCommandContext,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import { createBashTool } from "@earendil-works/pi-coding-agent";
+import {
+  createLocalBashOperations,
+  getAgentDir,
+  truncateTail,
+  type TruncationResult,
+} from "@earendil-works/pi-coding-agent";
 import { type TObject, Type } from "typebox";
 
 import { type CommandSpec, parseCommand } from "../lib/cli.js";
@@ -39,10 +49,25 @@ export interface BwrapExecutionRequest {
   requestFullAccess?: boolean;
   requestFullAccessReason?: string;
   signal?: AbortSignal;
-  onUpdate?: Parameters<ReturnType<typeof createBashTool>["execute"]>[3];
+  onUpdate?: AgentToolUpdateCallback;
   ctx: ExtensionContext;
 }
 
+/**
+ * 底层执行结果：完整退出码 + 截断后的输出文本。
+ * 输出在运行时就直接写入 agent-dir/tmp/{uuid}.txt（完整内容），内存不保留全量；
+ * `truncation.totalLines/totalBytes` 是精确统计值（非尾部缓冲的）。
+ * 退出码语义由上层 Bash 工具解释，这里不做成败判定。
+ */
+export interface BwrapExecutionResult {
+  exitCode: number | null;
+  /** 截断后的输出（尾部），未截断时为完整输出；空输出为空字符串。 */
+  output: string;
+  /** 完整输出的文件路径；无输出时不存在。 */
+  fullOutputPath?: string;
+  truncation: TruncationResult;
+}
+
 function escapeHtml(text: string): string {
   return text
     .replaceAll("&", "&amp;")
@@ -57,6 +82,103 @@ function fenceCodeBlock(code: string): string {
   return `${fence}\n${code}\n${fence}`;
 }
 
+/** 进度推送的节流间隔（对齐 pi 内置 bash 工具的 100ms）。 */
+const BASH_UPDATE_THROTTLE_MS = 100;
+/** 进度快照只保留尾部内容，避免大输出每 100ms 全量推给 TUI。 */
+const BASH_UPDATE_TAIL_BYTES = 64 * 1024;
+/** 内存尾部缓冲上限：必须大于 truncateTail 的默认上限（50KB / 2000 行）。 */
+const BASH_TAIL_LIMIT_BYTES = 1024 * 1024;
+
+function countNewlines(data: Buffer): number {
+  let count = 0;
+  for (const byte of data) {
+    if (byte === 0x0a) count++;
+  }
+  return count;
+}
+
+/**
+ * 合并 stdout/stderr 的流式输出累积器：输出在运行时就直接写入
+ * agent-dir/tmp/{uuid}.txt（完整内容），内存只保留尾部缓冲。
+ * 大输出不会撑爆内存；最终结果只返回截断后的文本。
+ */
+class BashOutput {
+  private stream: WriteStream | undefined;
+  private writeError: Error | undefined;
+  private tail: Buffer[] = [];
+  private tailBytes = 0;
+  private totalBytes = 0;
+  private totalLines = 0;
+  filePath: string | undefined;
+
+  append(data: Buffer): void {
+    this.totalBytes += data.length;
+    this.totalLines += countNewlines(data);
+    if (!this.stream) {
+      const dir = join(getAgentDir(), "tmp");
+      mkdirSync(dir, { recursive: true });
+      this.filePath = join(dir, `${randomUUID()}.txt`);
+      this.stream = createWriteStream(this.filePath, { flags: "w" });
+      this.stream.on("error", (error) => {
+        this.writeError = error;
+      });
+    }
+    this.stream.write(data);
+    this.tail.push(data);
+    this.tailBytes += data.length;
+    while (this.tailBytes > BASH_TAIL_LIMIT_BYTES && this.tail.length > 1) {
+      this.tailBytes -= this.tail[0].length;
+      this.tail.shift();
+    }
+    if (this.tailBytes > BASH_TAIL_LIMIT_BYTES && this.tail.length === 1) {
+      // 单个 chunk 超过上限：截掉头部，只保留尾部
+      this.tail[0] = this.tail[0].subarray(this.tailBytes - BASH_TAIL_LIMIT_BYTES);
+      this.tailBytes = BASH_TAIL_LIMIT_BYTES;
+    }
+  }
+
+  close(): Promise<void> {
+    if (!this.stream) return Promise.resolve();
+    const stream = this.stream;
+    this.stream = undefined;
+    return new Promise((resolve) => {
+      stream.end(() => {
+        if (this.writeError) {
+          // 落盘失败（如 readonly 沙箱）：降级为纯内存模式，命令仍正常返回
+          this.filePath = undefined;
+        }
+        resolve();
+      });
+    });
+  }
+
+  /** 尾部文本（截断结果的候选，未截断时即完整输出）。 */
+  tailText(): string {
+    return Buffer.concat(this.tail, this.tailBytes).toString("utf8");
+  }
+
+  get stats(): { totalBytes: number; totalLines: number } {
+    return { totalBytes: this.totalBytes, totalLines: this.totalLines };
+  }
+
+  /** 尾部快照（用于流式进度显示）。 */
+  tailSnapshot(): string {
+    let remaining = BASH_UPDATE_TAIL_BYTES;
+    const tail: Buffer[] = [];
+    for (let i = this.tail.length - 1; i >= 0 && remaining > 0; i--) {
+      const chunk = this.tail[i];
+      if (chunk.length <= remaining) {
+        tail.unshift(chunk);
+        remaining -= chunk.length;
+      } else {
+        tail.unshift(chunk.subarray(chunk.length - remaining));
+        remaining = 0;
+      }
+    }
+    return Buffer.concat(tail).toString("utf8");
+  }
+}
+
 function notifyMode(
   ctx: { ui: { notify: (message: string, type?: "info" | "warning" | "error") => void } },
   mode: BwrapMode,
@@ -143,7 +265,7 @@ export class BwrapRuntime {
     this.bwrapUnavailable = false;
   }
 
-  async execute(request: BwrapExecutionRequest) {
+  async execute(request: BwrapExecutionRequest): Promise<BwrapExecutionResult> {
     const runtime = this.resolve(request.ctx);
     if (this.bwrapUnavailable && runtime.bwrapEnabled && request.requestFullAccess !== true) {
       throw new Error(
@@ -154,16 +276,79 @@ export class BwrapRuntime {
     if (request.requestFullAccess === true && runtime.bwrapEnabled) {
       await this.approveFullAccess(request.ctx, request.command, request.requestFullAccessReason);
     }
-    const bash =
+    const operations =
       runtime.bwrapEnabled && request.requestFullAccess !== true
-        ? createBashTool(request.ctx.cwd, { operations: createBwrapBashOperations(runtime) })
-        : createBashTool(request.ctx.cwd);
-    return bash.execute(
-      request.toolCallId,
-      { command: request.command, timeout: request.timeout },
-      request.signal,
-      request.onUpdate,
-    );
+        ? createBwrapBashOperations(runtime)
+        : createLocalBashOperations();
+    const output = new BashOutput();
+    const { onUpdate } = request;
+
+    // 流式进度：节流推送尾部快照（对齐 pi 内置 bash 的实时输出体验）
+    let updateTimer: ReturnType<typeof setTimeout> | undefined;
+    let dirty = false;
+    let lastUpdateAt = 0;
+    const emitUpdate = () => {
+      if (!onUpdate || !dirty) return;
+      dirty = false;
+      lastUpdateAt = Date.now();
+      onUpdate({
+        content: [{ type: "text", text: output.tailSnapshot() }],
+        details: undefined,
+      });
+    };
+    const scheduleUpdate = () => {
+      if (!onUpdate) return;
+      dirty = true;
+      const delay = BASH_UPDATE_THROTTLE_MS - (Date.now() - lastUpdateAt);
+      if (delay <= 0) {
+        if (updateTimer) clearTimeout(updateTimer);
+        updateTimer = undefined;
+        emitUpdate();
+        return;
+      }
+      if (updateTimer) return;
+      updateTimer = setTimeout(() => {
+        updateTimer = undefined;
+        emitUpdate();
+      }, delay);
+    };
+
+    try {
+      if (onUpdate) onUpdate({ content: [], details: undefined });
+      const { exitCode } = await operations.exec(request.command, request.ctx.cwd, {
+        onData: (data) => {
+          output.append(data);
+          scheduleUpdate();
+        },
+        signal: request.signal,
+        timeout: request.timeout,
+      });
+      await output.close();
+      const truncation = truncateTail(output.tailText());
+      return {
+        exitCode,
+        output: truncation.content,
+        ...(output.filePath && { fullOutputPath: output.filePath }),
+        // 用精确统计值覆盖尾部缓冲的估算（提示文本的行数/字节数要准确）
+        truncation: { ...truncation, ...output.stats },
+      };
+    } catch (error) {
+      // 底层统一把超时/中断转成可读文案（对齐 pi 内置 bash 工具）
+      if (error instanceof Error && error.message.startsWith("timeout:")) {
+        throw new Error(
+          `Command timed out after ${error.message.slice("timeout:".length)} seconds`,
+          { cause: error },
+        );
+      }
+      if (error instanceof Error && error.message === "aborted") {
+        throw new Error("Command aborted", { cause: error });
+      }
+      throw error;
+    } finally {
+      if (updateTimer) clearTimeout(updateTimer);
+      if (onUpdate && dirty) emitUpdate();
+      await output.close();
+    }
   }
 
   private resolve(ctx: Pick<ExtensionContext, "cwd" | "hasUI">): ResolvedBwrap {

package/src/claude-code/shell.ts

@@ -1,7 +1,9 @@
 import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type BashToolDetails, formatSize } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
 import { type BwrapRuntime, createBwrapRuntime } from "../bwrap/runtime.js";
@@ -10,9 +12,58 @@ import { resolveWorkdir } from "../lib/path.js";
 const DEFAULT_TIMEOUT_MS = 120_000;
 const MAX_TIMEOUT_MS = 600_000;
 
+/** 对齐 Claude Code formatError：错误文本超过该长度时头尾各保留一半。 */
+const MAX_ERROR_CHARS = 10_000;
+
 /** Bash tool guidance, kept in markdown so it reads like documentation. */
 const BASH_PROMPT = readFileSync(fileURLToPath(new URL("bash.md", import.meta.url)), "utf8").trim();
 
+/**
+ * 对齐 Claude Code 的错误格式：`Exit code N` 在开头，完整输出随后；
+ * 超过 10000 字符时头尾各 5000 + 中间截断提示。
+ */
+function formatBashError(exitCode: number | null, output: string): string {
+  const full = [`Exit code ${exitCode ?? 1}`, output].filter(Boolean).join("\n");
+  if (full.length <= MAX_ERROR_CHARS) return full;
+  const half = MAX_ERROR_CHARS / 2;
+  return (
+    full.slice(0, half) +
+    `\n\n... [${full.length - MAX_ERROR_CHARS} characters truncated] ...\n\n` +
+    full.slice(-half)
+  );
+}
+
+/**
+ * 成功路径：消费 runtime 的截断结果（输出已由 runtime 截断并落盘），
+ * 截断时追加 `[Showing lines X-Y of N. Full output: path]` 提示。
+ * opencode 套件的 bash 工具复用同一逻辑。
+ */
+export function formatBashSuccess(result: Awaited<ReturnType<BwrapRuntime["execute"]>>): {
+  content: { type: "text"; text: string }[];
+  details: BashToolDetails | undefined;
+} {
+  const { output, truncation, fullOutputPath } = result;
+  let text = output || "(no output)";
+  if (fullOutputPath && truncation.truncated) {
+    const startLine = truncation.totalLines - truncation.outputLines + 1;
+    const endLine = truncation.totalLines;
+    if (truncation.lastLinePartial) {
+      const lastLineSize = formatSize(
+        output.length - output.lastIndexOf("\n", output.length - 2) - 1,
+      );
+      text += `\n\n[Showing last ${formatSize(truncation.outputBytes)} of line ${endLine} (line is ${lastLineSize}). Full output: ${fullOutputPath}]`;
+    } else if (truncation.truncatedBy === "lines") {
+      text += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines}. Full output: ${fullOutputPath}]`;
+    } else {
+      text += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines} (${formatSize(truncation.maxBytes)} limit). Full output: ${fullOutputPath}]`;
+    }
+  }
+  return {
+    content: [{ type: "text", text }],
+    details: fullOutputPath && truncation.truncated ? { truncation, fullOutputPath } : undefined,
+  };
+}
+
 /**
  * runtime 由调用方注入：扩展工厂持有一个实例（不依赖模块级全局状态），
  * 测试可注入预置模式的实例。状态随扩展实例生命周期，session 切换重建即重置。
@@ -64,8 +115,9 @@ export function registerShellTools(
 
       const cwd = params.workdir ? await resolveWorkdir(params.workdir, ctx.cwd) : ctx.cwd;
 
+      let result: Awaited<ReturnType<BwrapRuntime["execute"]>>;
       try {
-        return await runtime.execute({
+        result = await runtime.execute({
           ctx: { ...ctx, cwd },
           toolCallId: id,
           command: params.command,
@@ -85,6 +137,18 @@ export function registerShellTools(
           : error.message;
         throw new Error(message, { cause: error });
       }
+
+      // 对齐 Claude Code：非 0 退出码视为错误（不做 grep/find 等命令语义化特判，
+      // 任何非 0 都抛错）；错误文本用完整输出（从落盘文件读取，必要时头尾截断）
+      if (result.exitCode !== 0 && result.exitCode !== null) {
+        const full = result.fullOutputPath
+          ? await readFile(result.fullOutputPath, "utf8")
+          : result.output;
+        throw new Error(formatBashError(result.exitCode, full), {
+          cause: result,
+        });
+      }
+      return formatBashSuccess(result);
     },
   });
 }

package/src/claude-code/skills/claude-code-tools/SKILL.md

@@ -59,7 +59,10 @@ The capitalized tools below follow Claude Code behavior with a few deliberate de
 
 - Commands run through the bwrap sandbox (modes: `allow-all` / `workspace-write` / `allow-net` / `readonly`), switchable via `/bwrap-*` commands. `dangerouslyDisableSandbox: true` requests one-time unsandboxed execution and needs user approval (denied in headless sessions).
 - `timeout` is in milliseconds, default 120000, max 600000. `workdir` overrides the working directory.
-- **Deviation from Claude Code:** no auto-backgrounding on timeout — a timed-out command is killed and the error reports the timeout.
+- **Non-zero exit code is a tool failure**: the error text starts with `Exit code N` followed by the full output (head/tail-truncated at 10000 chars if larger). **Deviation from Claude Code:** no command-semantics special cases — `grep` with no matches (exit 1), `diff` differences, `test` false, etc. all fail like any other non-zero exit.
+- Output is streamed to a file under `agent-dir/tmp/<uuid>.txt` during execution; the tool result only contains the truncated tail (2000 lines / 50 KB). On truncation a note is appended: `[Showing lines X-Y of N. Full output: <path>]` — read that file for the complete output. In a read-only sandbox where the write fails, the result degrades to the in-memory tail only.
+- **Deviation from Claude Code:** no auto-backgrounding on timeout — a timed-out command is killed and the error reports `Command timed out after N milliseconds`.
+- The lowercase opencode-style `bash` tool differs: it **never throws** on non-zero exit — it returns the output plus a `Command exited with code N.` status text block; a timeout returns `Command exceeded timeout of N ms. Retry with a larger timeout...` instead of failing.
 
 ## TodoWrite
 

package/src/opencode/bash.ts

@@ -1,16 +1,26 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { createBwrapRuntime } from "../bwrap/runtime.js";
+import { type BwrapRuntime, createBwrapRuntime } from "../bwrap/runtime.js";
 import { resolveWorkdir } from "../lib/path.js";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
 const MAX_TIMEOUT_MS = 600_000;
 
-export default function opencodeBash(pi: ExtensionAPI): void {
+/** 对齐上游 opencode 的截断提示文案（tools/BashTool/bash.ts）。 */
+const CAPTURE_TRUNCATED_NOTICE = "[output capture truncated at the in-memory safety limit]";
+
+/**
+ * 对齐上游 opencode（packages/core/src/tool/bash.ts）：
+ * 命令失败（非 0 退出码）与超时都不抛错，输出与状态文本一起返回，
+ * 由模型根据 `Command exited with code N.` 自行判断。
+ */
+export default function opencodeBash(
+  pi: ExtensionAPI,
+  runtime: BwrapRuntime = createBwrapRuntime(),
+): void {
   // 每个扩展实例持有自己的 runtime：不依赖模块级全局状态，状态随扩展
   // 实例生命周期（进程启动 / /reload / session 切换时工厂重建即重置）。
-  const runtime = createBwrapRuntime();
   runtime.setup(pi);
   pi.registerTool({
     name: "bash",
@@ -54,8 +64,9 @@ export default function opencodeBash(pi: ExtensionAPI): void {
 
       const cwd = params.workdir ? await resolveWorkdir(params.workdir, ctx.cwd) : ctx.cwd;
 
+      let result: Awaited<ReturnType<BwrapRuntime["execute"]>>;
       try {
-        return await runtime.execute({
+        result = await runtime.execute({
           ctx: { ...ctx, cwd },
           toolCallId: id,
           command: params.command,
@@ -66,14 +77,39 @@ export default function opencodeBash(pi: ExtensionAPI): void {
         });
       } catch (error) {
         if (!(error instanceof Error)) throw error;
-        const timeoutMatch = /Command timed out after [\d.]+ seconds/.exec(error.message);
-        const message = timeoutMatch
-          ? error.message.slice(0, timeoutMatch.index) +
-            `Command timed out after ${timeout} milliseconds` +
-            error.message.slice(timeoutMatch.index + timeoutMatch[0].length)
-          : error.message;
-        throw new Error(message, { cause: error });
+        // 对齐上游 opencode：超时不抛错，返回提示文本（丢弃部分输出）
+        if (/Command timed out after [\d.]+ seconds/.test(error.message)) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Command exceeded timeout of ${timeout} ms. Retry with a larger timeout if the command is expected to take longer.`,
+              },
+              { type: "text" as const, text: "Command timed out before completion." },
+            ],
+            details: { timeout: true },
+          };
+        }
+        throw error;
+      }
+
+      // 命令失败（非 0 退出码）不抛错：输出与状态文本一起返回
+      let text = result.output || "(no output)";
+      if (result.truncation.truncated) {
+        text += `\n\n${CAPTURE_TRUNCATED_NOTICE}`;
+        if (result.fullOutputPath) text += `\nFull output: ${result.fullOutputPath}`;
       }
+      return {
+        content: [
+          { type: "text" as const, text },
+          { type: "text" as const, text: `Command exited with code ${result.exitCode}.` },
+        ],
+        details: {
+          exitCode: result.exitCode,
+          truncated: result.truncation.truncated,
+          ...(result.fullOutputPath && { fullOutputPath: result.fullOutputPath }),
+        },
+      };
     },
   });
 }