@trim21/personal-pi-extensions 0.0.249 → 0.0.251

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.249",
+  "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,10 +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 { createLocalBashOperations } 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";
@@ -45,12 +54,18 @@ export interface BwrapExecutionRequest {
 }
 
 /**
- * 底层执行结果：完整退出码 + 完整输出（stdout/stderr 合并，未截断）。
- * 退出码语义（grep exit 1 等）由上层 Bash 工具解释，这里不做成败判定。
+ * 底层执行结果：完整退出码 + 截断后的输出文本。
+ * 输出在运行时就直接写入 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 {
@@ -71,30 +86,87 @@ function fenceCodeBlock(code: string): string {
 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 的流式输出累积器。
- * 内存中保留全部输出供最终结果使用；进度快照只取尾部。
+ * 合并 stdout/stderr 的流式输出累积器：输出在运行时就直接写入
+ * agent-dir/tmp/{uuid}.txt（完整内容），内存只保留尾部缓冲。
+ * 大输出不会撑爆内存；最终结果只返回截断后的文本。
  */
 class BashOutput {
-  private chunks: Buffer[] = [];
+  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.chunks.push(data);
     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;
+    }
   }
 
-  toString(): string {
-    return Buffer.concat(this.chunks, this.totalBytes).toString("utf8");
+  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.chunks.length - 1; i >= 0 && remaining > 0; i--) {
-      const chunk = this.chunks[i];
+    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;
@@ -251,7 +323,15 @@ export class BwrapRuntime {
         signal: request.signal,
         timeout: request.timeout,
       });
-      return { exitCode, output: output.toString() };
+      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:")) {
@@ -267,6 +347,7 @@ export class BwrapRuntime {
     } finally {
       if (updateTimer) clearTimeout(updateTimer);
       if (onUpdate && dirty) emitUpdate();
+      await output.close();
     }
   }
 

package/src/claude-code/shell.ts

@@ -1,17 +1,9 @@
-import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import {
-  type BashToolDetails,
-  DEFAULT_MAX_BYTES,
-  formatSize,
-  getAgentDir,
-  truncateTail,
-} 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";
@@ -42,24 +34,17 @@ function formatBashError(exitCode: number | null, output: string): string {
 }
 
 /**
- * 成功路径：truncateTail 截断 + 全量落盘临时文件，
- * 提示文本 `[Showing lines X-Y of N. Full output: path]`。
+ * 成功路径：消费 runtime 的截断结果（输出已由 runtime 截断并落盘），
+ * 截断时追加 `[Showing lines X-Y of N. Full output: path]` 提示。
  * opencode 套件的 bash 工具复用同一逻辑。
  */
-export async function formatBashSuccess(
-  output: string,
-): Promise<{ content: { type: "text"; text: string }[]; details: BashToolDetails | undefined }> {
-  const truncation = truncateTail(output);
-  let text = truncation.content || "(no output)";
-  let details: BashToolDetails | undefined;
-  if (truncation.truncated) {
-    // 完整输出落盘到 agent 数据目录的 tmp 子目录（与 pi 的 agent 状态同处，
-    // 模型可读；系统临时目录可能被清理）
-    const dir = join(getAgentDir(), "tmp");
-    await mkdir(dir, { recursive: true });
-    const fullOutputPath = join(dir, `${randomUUID()}.txt`);
-    await writeFile(fullOutputPath, output, "utf8");
-    details = { truncation, fullOutputPath };
+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) {
@@ -70,10 +55,13 @@ export async function formatBashSuccess(
     } 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 ?? DEFAULT_MAX_BYTES)} limit). Full output: ${fullOutputPath}]`;
+      text += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines} (${formatSize(truncation.maxBytes)} limit). Full output: ${fullOutputPath}]`;
     }
   }
-  return { content: [{ type: "text", text }], details };
+  return {
+    content: [{ type: "text", text }],
+    details: fullOutputPath && truncation.truncated ? { truncation, fullOutputPath } : undefined,
+  };
 }
 
 /**
@@ -151,13 +139,16 @@ export function registerShellTools(
       }
 
       // 对齐 Claude Code：非 0 退出码视为错误（不做 grep/find 等命令语义化特判，
-      // 任何非 0 都抛错）；成功路径返回纯输出
+      // 任何非 0 都抛错）；错误文本用完整输出（从落盘文件读取，必要时头尾截断）
       if (result.exitCode !== 0 && result.exitCode !== null) {
-        throw new Error(formatBashError(result.exitCode, result.output), {
+        const full = result.fullOutputPath
+          ? await readFile(result.fullOutputPath, "utf8")
+          : result.output;
+        throw new Error(formatBashError(result.exitCode, full), {
           cause: result,
         });
       }
-      return formatBashSuccess(result.output);
+      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

@@ -2,16 +2,25 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
 import { type BwrapRuntime, createBwrapRuntime } from "../bwrap/runtime.js";
-import { formatBashSuccess } from "../claude-code/shell.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",
@@ -68,23 +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 退出码都视为失败（不做命令语义化特判）
-      if (result.exitCode !== 0 && result.exitCode !== null) {
-        const status = `Command exited with code ${result.exitCode}`;
-        throw new Error(result.output ? `${result.output}\n\n${status}` : status, {
-          cause: result,
-        });
+      // 命令失败（非 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 formatBashSuccess(result.output);
+      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 }),
+        },
+      };
     },
   });
 }