@trim21/personal-pi-extensions 0.1.552 → 0.1.554

package/package.json

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

package/src/bwrap/runtime.ts

@@ -91,6 +91,8 @@ export interface BwrapExecutionRequest {
  */
 export interface BwrapExecutionResult {
   exitCode: number | null;
+  /** 沙箱状态说明（写边界 + 网络层级），失败时由上层工具作为独立信息块附上；未沙箱执行时为 undefined。 */
+  sandboxHint: string | undefined;
   /** 截断后的输出（尾部），未截断时为完整输出；空输出为空字符串。 */
   output: string;
   /** 完整输出的文件路径；无输出时不存在。 */
@@ -112,16 +114,19 @@ export interface BashExecutionPartial {
 export class BashInterruptedError extends Error {
   readonly kind: "timeout" | "aborted";
   readonly partial: BashExecutionPartial;
+  readonly sandboxHint: string | undefined;
 
   constructor(
     kind: "timeout" | "aborted",
     message: string,
     partial: BashExecutionPartial,
+    sandboxHint: string | undefined,
     cause: unknown,
   ) {
     super(message, { cause });
     this.kind = kind;
     this.partial = partial;
+    this.sandboxHint = sandboxHint;
     // 对齐标准错误分类：中断=AbortError（用户取消），超时=TimeoutError
     this.name = kind === "aborted" ? "AbortError" : "TimeoutError";
   }
@@ -255,6 +260,41 @@ function notifyMode(
   ctx.ui.notify(labels[mode], "info");
 }
 
+/** 沙箱默认写边界：根只读、工作区可写、.git 只读。不展开用户配置的额外可写路径。 */
+const SANDBOX_WRITE_RULES = "/ is read-only, ./ is writable, ./.git/ is read-only";
+
+/** 网络层级：关 / 只放行白名单 / 完全放开（白名单域名本身不列出，对判断失败无用）。 */
+function describeNetwork(resolved: ResolvedBwrap): string {
+  if (!resolved.network) return "network access is off";
+  if (resolved.networkAllowlist.length > 0)
+    return "network access is limited to allowlisted addresses";
+  return "network access is unrestricted";
+}
+
+/** 命令没经沙箱时沿用 prompt 里的说法，给出在沙盒外重跑的手段。 */
+const SANDBOX_ESCAPE_HATCH =
+  "[Sandbox] If the command needs more than that, use the `dangerouslyDisableSandbox` parameter to request unsandboxed execution; the user must approve this request.";
+
+/**
+ * 命令失败时作为独立信息块附上的沙箱状态：默认写边界 + 网络层级，以及在沙盒外重跑的手段。
+ * 写边界只说沙箱布局（不展开用户配置的可写路径），网络只说层级（不列白名单域名）。
+ * 命令没经沙箱（allow-all、审批通过的全权限、Windows）时返回 undefined：
+ * 没有沙箱就没什么可提示的。
+ */
+export function describeSandbox(resolved: ResolvedBwrap, unsandboxed: boolean): string | undefined {
+  if (unsandboxed) return undefined;
+  const writes = resolved.mode === "readonly" ? "the filesystem is read-only" : SANDBOX_WRITE_RULES;
+  return [
+    `[Sandbox] This command ran in a sandbox: ${writes}; ${describeNetwork(resolved)}.`,
+    SANDBOX_ESCAPE_HATCH,
+  ].join("\n");
+}
+
+/** 失败结果里附加的沙箱状态块；未沙箱执行（hint 为 undefined）时没有这一块。 */
+export function sandboxHintBlock(hint: string | undefined): { type: "text"; text: string }[] {
+  return hint === undefined ? [] : [{ type: "text", text: hint }];
+}
+
 export class BwrapRuntime {
   private resolved: ResolvedBwrap | undefined;
   private sandboxDisabled = false;
@@ -383,6 +423,8 @@ export class BwrapRuntime {
       runtime.mihomoPath ??= this.mihomoPath ?? findMihomo();
       this.mihomoPath = runtime.mihomoPath;
     }
+    // 命令失败时附带的沙箱状态（写边界 + 网络层级），由上层拼进错误文本
+    const sandboxHint = describeSandbox(runtime, local);
     await using output = new BashOutput(request.ctx.sessionManager.getSessionId());
     const { onUpdate } = request;
 
@@ -415,6 +457,7 @@ export class BwrapRuntime {
       const partial = await this.finalizeOutput(output);
       return {
         exitCode,
+        sandboxHint,
         output: partial.output,
         ...(partial.fullOutputPath && { fullOutputPath: partial.fullOutputPath }),
         truncation: partial.truncation,
@@ -433,6 +476,7 @@ export class BwrapRuntime {
           "timeout",
           `Command timed out after ${error.message.slice("timeout:".length)} seconds`,
           partial,
+          sandboxHint,
           error,
         );
       }
@@ -440,7 +484,13 @@ export class BwrapRuntime {
       // 兼容 pi local ops 抛的 new Error("aborted")
       if (error instanceof Error && (error.name === "AbortError" || error.message === "aborted")) {
         const partial = await this.finalizeOutput(output);
-        throw new BashInterruptedError("aborted", "Command aborted by user", partial, error);
+        throw new BashInterruptedError(
+          "aborted",
+          "Command aborted by user",
+          partial,
+          sandboxHint,
+          error,
+        );
       }
       throw error;
     } finally {

package/src/claude-code/shell.ts

@@ -10,7 +10,12 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { BashInterruptedError, type BwrapRuntime, createBwrapRuntime } from "../bwrap/runtime.js";
+import {
+  BashInterruptedError,
+  type BwrapRuntime,
+  createBwrapRuntime,
+  sandboxHintBlock,
+} from "../bwrap/runtime.js";
 import { resolveWorkdir } from "../lib/path.js";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
@@ -154,20 +159,28 @@ export function registerShellTools(
           const full = text
             ? `${text}\n\nCommand timed out after ${timeout} milliseconds`
             : `Command timed out after ${timeout} milliseconds`;
-          throw new Error(full, { cause: error });
+          return {
+            content: [{ type: "text", text: full }, ...sandboxHintBlock(error.sandboxHint)],
+            details: undefined,
+          };
         }
         throw error;
       }
 
-      // 对齐 Claude Code：非 0 退出码视为错误（不做 grep/find 等命令语义化特判，
-      // 任何非 0 都抛错）；错误文本用完整输出（从落盘文件读取，必要时头尾截断）
+      // 对齐 Claude Code：非 0 退出码都算失败（不做 grep/find 等命令语义化特判）。
+      // 失败是命令的正常结果而不是异常：与成功一样 return，文本用完整输出
+      // （从落盘文件读取，必要时头尾截断），沙箱状态另行附一块
       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 {
+          content: [
+            { type: "text", text: formatBashError(result.exitCode, full) },
+            ...sandboxHintBlock(result.sandboxHint),
+          ],
+          details: undefined,
+        };
       }
       return formatBashSuccess(result);
     },

package/src/opencode/bash.ts

@@ -4,7 +4,12 @@ import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, TruncationResult } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { BashInterruptedError, type BwrapRuntime, createBwrapRuntime } from "../bwrap/runtime.js";
+import {
+  BashInterruptedError,
+  type BwrapRuntime,
+  createBwrapRuntime,
+  sandboxHintBlock,
+} from "../bwrap/runtime.js";
 import { resolveWorkdir } from "../lib/path.js";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
@@ -111,9 +116,13 @@ export default function opencodeBash(
               ? `Command exceeded timeout of ${timeout} ms. Retry with a larger timeout if the command is expected to take longer.`
               : "Command aborted by user";
           const full = text ? `${text}\n\n${status}` : status;
-          // 对齐上游 opencode：超时与中断都不抛错，输出与状态文本一起返回
+          // 对齐上游 opencode：超时与中断都不抛错，输出与状态文本一起返回；
+          // 超时可能是沙箱的网络限制导致的，附加沙箱状态（用户中断与沙箱无关）
           return {
-            content: [{ type: "text" as const, text: full }],
+            content: [
+              { type: "text" as const, text: full },
+              ...sandboxHintBlock(error.kind === "timeout" ? error.sandboxHint : undefined),
+            ],
             details: error.kind === "timeout" ? { timeout: true } : {},
           };
         }
@@ -123,10 +132,13 @@ export default function opencodeBash(
       // 命令失败（非 0 退出码）不抛错：输出与状态文本一起返回
       let text = result.output || "(no output)";
       text = appendTruncationNotice(text, result.truncation, result.fullOutputPath);
+      const failed = result.exitCode !== 0 && result.exitCode !== null;
       return {
         content: [
           { type: "text" as const, text },
           { type: "text" as const, text: `Command exited with code ${result.exitCode}.` },
+          // 失败可能是被沙箱的写边界或网络限制挡住的，附一块沙箱状态
+          ...sandboxHintBlock(failed ? result.sandboxHint : undefined),
         ],
         details: {
           exitCode: result.exitCode,