@trim21/personal-pi-extensions 0.0.246 → 0.0.249

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.246",
+  "version": "0.0.249",
   "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,10 @@
 import type {
+  AgentToolUpdateCallback,
   ExtensionAPI,
   ExtensionCommandContext,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import { createBashTool } from "@earendil-works/pi-coding-agent";
+import { createLocalBashOperations } from "@earendil-works/pi-coding-agent";
 import { type TObject, Type } from "typebox";
 
 import { type CommandSpec, parseCommand } from "../lib/cli.js";
@@ -39,10 +40,19 @@ export interface BwrapExecutionRequest {
   requestFullAccess?: boolean;
   requestFullAccessReason?: string;
   signal?: AbortSignal;
-  onUpdate?: Parameters<ReturnType<typeof createBashTool>["execute"]>[3];
+  onUpdate?: AgentToolUpdateCallback;
   ctx: ExtensionContext;
 }
 
+/**
+ * 底层执行结果：完整退出码 + 完整输出（stdout/stderr 合并，未截断）。
+ * 退出码语义（grep exit 1 等）由上层 Bash 工具解释，这里不做成败判定。
+ */
+export interface BwrapExecutionResult {
+  exitCode: number | null;
+  output: string;
+}
+
 function escapeHtml(text: string): string {
   return text
     .replaceAll("&", "&amp;")
@@ -57,6 +67,46 @@ 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;
+
+/**
+ * 合并 stdout/stderr 的流式输出累积器。
+ * 内存中保留全部输出供最终结果使用；进度快照只取尾部。
+ */
+class BashOutput {
+  private chunks: Buffer[] = [];
+  private totalBytes = 0;
+
+  append(data: Buffer): void {
+    this.chunks.push(data);
+    this.totalBytes += data.length;
+  }
+
+  toString(): string {
+    return Buffer.concat(this.chunks, this.totalBytes).toString("utf8");
+  }
+
+  /** 尾部快照（用于流式进度显示）。 */
+  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];
+      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 +193,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 +204,70 @@ 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,
+      });
+      return { exitCode, output: output.toString() };
+    } 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();
+    }
   }
 
   private resolve(ctx: Pick<ExtensionContext, "cwd" | "hasUI">): ResolvedBwrap {

package/src/claude-code/files.ts

@@ -187,6 +187,7 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
     label: "Read",
     description: [
       "Reads a file from the local filesystem. You can access any file directly using this tool.",
+      "Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.",
       "The file_path parameter must be an absolute path. By default, it reads the entire file; files over 256 KB or 25K tokens require offset and limit.",
       "Results use cat -n style line numbers starting at 1. Images are returned visually.",
       "This tool reads files, not directories.",
@@ -294,7 +295,9 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
       {
         file_path: Type.String({ description: "The absolute path to the file to modify" }),
         old_string: Type.String({ description: "The text to replace" }),
-        new_string: Type.String({ description: "The text to replace it with" }),
+        new_string: Type.String({
+          description: "The text to replace it with (must be different from old_string)",
+        }),
         replace_all: Type.Optional(
           Type.Boolean({ description: "Replace all occurrences of old_string", default: false }),
         ),

package/src/claude-code/glob.ts

@@ -118,7 +118,7 @@ export function registerGlobTool(pi: ExtensionAPI): void {
         path: Type.Optional(
           Type.String({
             description:
-              "The directory to search in. If omitted, the current working directory is used.",
+              'The directory to search in. If not specified, the current working directory will be used. IMPORTANT: Omit this field to use the default directory. DO NOT enter "undefined" or "null" - simply omit it for the default behavior. Must be a valid directory path if provided.',
           }),
         ),
       },

package/src/claude-code/shell.ts

@@ -1,7 +1,17 @@
+import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
 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 } from "typebox";
 
 import { type BwrapRuntime, createBwrapRuntime } from "../bwrap/runtime.js";
@@ -10,9 +20,62 @@ 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)
+  );
+}
+
+/**
+ * 成功路径：truncateTail 截断 + 全量落盘临时文件，
+ * 提示文本 `[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 };
+    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 ?? DEFAULT_MAX_BYTES)} limit). Full output: ${fullOutputPath}]`;
+    }
+  }
+  return { content: [{ type: "text", text }], details };
+}
+
 /**
  * runtime 由调用方注入：扩展工厂持有一个实例（不依赖模块级全局状态），
  * 测试可注入预置模式的实例。状态随扩展实例生命周期，session 切换重建即重置。
@@ -64,8 +127,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 +149,15 @@ export function registerShellTools(
           : error.message;
         throw new Error(message, { cause: error });
       }
+
+      // 对齐 Claude Code：非 0 退出码视为错误（不做 grep/find 等命令语义化特判，
+      // 任何非 0 都抛错）；成功路径返回纯输出
+      if (result.exitCode !== 0 && result.exitCode !== null) {
+        throw new Error(formatBashError(result.exitCode, result.output), {
+          cause: result,
+        });
+      }
+      return formatBashSuccess(result.output);
     },
   });
 }

package/src/opencode/bash.ts

@@ -1,7 +1,8 @@
 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 { formatBashSuccess } from "../claude-code/shell.js";
 import { resolveWorkdir } from "../lib/path.js";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
@@ -54,8 +55,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,
@@ -74,6 +76,15 @@ export default function opencodeBash(pi: ExtensionAPI): void {
           : error.message;
         throw new Error(message, { cause: 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,
+        });
+      }
+      return formatBashSuccess(result.output);
     },
   });
 }