@trim21/personal-pi-extensions 0.1.439 → 0.1.441

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.439",
+  "version": "0.1.441",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -23,6 +23,7 @@
     "format": "prettier --write .",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "sandbox": "tsx bin/sandbox.ts",
     "prepare": "husky"
   },
   "peerDependencies": {
@@ -52,6 +53,8 @@
     "husky": "^9.1.7",
     "lint-staged": "^17.3.0",
     "prettier": "^3.9.6",
+    "shlex": "^3.0.0",
+    "tsx": "^4.23.12",
     "typebox": "1.3.1",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "typescript-eslint": "^8.67.0",

package/src/bwrap/core.ts

@@ -187,7 +187,9 @@ export function getBwrapConfigPaths(cwd: string): BwrapConfigPaths {
 
 export function loadBwrapConfig(cwd: string, paths = getBwrapConfigPaths(cwd)): BwrapConfig {
   let config = DEFAULT_CONFIG;
-  for (const path of [paths.global, paths.project]) {
+  // 去重：调用方用同一路径表达「只读这一个文件」时不做二次合并
+  // （否则 extraWritablePaths / approvalRules 会被重复拼接）
+  for (const path of new Set([paths.global, paths.project])) {
     if (!existsSync(path)) continue;
     config = deepMerge(config, parseBwrapConfigFile(path));
   }
@@ -375,9 +377,16 @@ function killChild(child: ChildProcess): void {
   }
 }
 
+/** 网络栈子进程输出转发通道，仅用于诊断（默认丢弃）。 */
+export interface NetworkStackLog {
+  holder?: (chunk: string) => void;
+  slirp?: (chunk: string) => void;
+}
+
 /** 为 net-allowlist 模式创建网络栈；非该模式返回 undefined。每次命令现建现停。 */
 export async function createNetworkStack(
   resolved: ResolvedBwrap,
+  log?: NetworkStackLog,
 ): Promise<NetworkStack | undefined> {
   if (!resolved.network || resolved.networkAllowlist.length === 0) return undefined;
   return startNetworkStack({
@@ -385,9 +394,77 @@ export async function createNetworkStack(
     dnsServers: await resolveDnsServers(),
     mihomoPath: findMihomo(resolved.mihomoPath),
     slirp4netnsPath: findSlirp4netns(resolved.slirp4netnsPath),
+    ...(log?.holder && { onHolderOutput: log.holder }),
+    ...(log?.slirp && { onSlirpOutput: log.slirp }),
   });
 }
 
+/** 一次 bwrap 调用的完整组装结果：argv 与干净环境。 */
+export interface BwrapInvocation {
+  /** bwrap 可执行文件路径 */
+  file: string;
+  /** bwrap 参数（不含结尾的 `-- shell -lc command`） */
+  args: string[];
+  /** 沙箱内 shell 的绝对路径 */
+  shell: string;
+  /** 交给 shell 的命令 */
+  command: string;
+  /** 命令执行目录 */
+  cwd: string;
+  /** 沙箱内环境（不继承父进程） */
+  env: Record<string, string>;
+  /** net-allowlist 模式：命令需先经 nsenter 进入 holder 的 netns。 */
+  needsNetworkStack: boolean;
+}
+
+/**
+ * 组装一次 bwrap 调用。实际执行（createBwrapBashOperations）与调试打印共用这里，
+ * 保证 `--print-args` 输出的命令行与真正跑的那条完全一致。
+ */
+export async function buildBwrapInvocation(
+  resolved: ResolvedBwrap,
+  workspace: string,
+  command: string,
+  cwd: string,
+): Promise<BwrapInvocation> {
+  // 干净环境：不继承父进程 env/PATH，由 bash -lc 从 /etc/profile 与用户 profile 重建
+  const home = process.env.HOME;
+  if (home === undefined) {
+    throw new Error("HOME is not set; refusing to run bash in a clean environment");
+  }
+  return {
+    // 沙箱内不透传 PATH，execvp 的默认路径可能找不到 bash（如 NixOS），故在父进程解析绝对路径
+    shell: getShellConfig().shell,
+    file: findBwrap(resolved.bwrapPath),
+    args: [
+      "--ro-bind",
+      "/",
+      "/",
+      ...(await buildBwrapArgs(resolved, workspace)),
+      "--dev",
+      "/dev",
+      "--proc",
+      "/proc",
+    ],
+    command,
+    cwd,
+    env: {
+      HOME: home,
+      SHELL: "/bin/bash",
+      TERM: "dumb",
+      LANG: "C.UTF-8",
+      // 基础 PATH：profile 加载阶段（设置 PATH 前）需要系统命令（如 id），由 profile 随后覆盖；不含 sbin
+      PATH: "/usr/local/bin:/usr/bin:/bin",
+    },
+    needsNetworkStack: resolved.network && resolved.networkAllowlist.length > 0,
+  };
+}
+
+/** 完整 argv（`[bwrap, ...args, "--", shell, "-lc", command]`），spawn 与打印共用。 */
+export function bwrapArgv(invocation: BwrapInvocation): string[] {
+  return [invocation.file, ...invocation.args, "--", invocation.shell, "-lc", invocation.command];
+}
+
 /**
  * @param workspace session 工作区：writablePaths 的 "." 与 PROTECTED_DIRS 都基于它解析，
  *   与当次命令的 cwd（仅作为进程执行目录）解耦，避免 workdir 参数漂移可写边界。
@@ -397,8 +474,6 @@ export function createBwrapBashOperations(
   workspace: string,
   networkStack?: NetworkStack,
 ): BashOperations {
-  // 沙箱内不透传 PATH，execvp 的默认路径可能找不到 bash（如 NixOS），故在父进程解析绝对路径
-  const shell = getShellConfig().shell;
   return {
     async exec(command, cwd, { onData, signal, timeout }) {
       await fsAccess(cwd, constants.F_OK).catch(() => {
@@ -407,58 +482,32 @@ export function createBwrapBashOperations(
       // 已中断（signal.reason 是 name=AbortError 的 DOMException）：直接抛，不再执行
       signal?.throwIfAborted();
 
-      // 干净环境：不继承父进程 env/PATH，由 bash -lc 从 /etc/profile 与用户 profile 重建
-      const home = process.env.HOME;
-      if (home === undefined) {
-        throw new Error("HOME is not set; refusing to run bash in a clean environment");
-      }
+      const invocation = await buildBwrapInvocation(resolved, workspace, command, cwd);
 
-      const baseArgs = [
-        "--ro-bind",
-        "/",
-        "/",
-        ...(await buildBwrapArgs(resolved, workspace)),
-        "--dev",
-        "/dev",
-        "--proc",
-        "/proc",
-      ];
-      const env = {
-        HOME: home,
-        SHELL: "/bin/bash",
-        TERM: "dumb",
-        LANG: "C.UTF-8",
-        // 基础 PATH：profile 加载阶段（设置 PATH 前）需要系统命令（如 id），由 profile 随后覆盖；不含 sbin
-        PATH: "/usr/local/bin:/usr/bin:/bin",
-      };
-
-      if (resolved.network && resolved.networkAllowlist.length > 0) {
+      if (invocation.needsNetworkStack) {
         if (!networkStack) {
           throw new Error("Network stack is not initialized for net-allowlist mode");
         }
         return networkStack.exec({
           command,
           cwd,
-          bwrapPath: findBwrap(resolved.bwrapPath),
-          bwrapArgs: baseArgs,
-          shell,
-          env,
+          bwrapPath: invocation.file,
+          bwrapArgs: invocation.args,
+          shell: invocation.shell,
+          env: invocation.env,
           onData,
           signal,
           timeout,
         });
       }
 
-      const child = spawn(
-        findBwrap(resolved.bwrapPath),
-        [...baseArgs, "--", shell, "-lc", command],
-        {
-          cwd,
-          detached: true,
-          stdio: ["ignore", "pipe", "pipe"],
-          env,
-        },
-      );
+      const argv = bwrapArgv(invocation);
+      const child = spawn(argv[0], argv.slice(1), {
+        cwd,
+        detached: true,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: invocation.env,
+      });
 
       return new Promise<{ exitCode: number | null }>((resolve, reject) => {
         let timedOut = false;

package/src/bwrap/network-stack.ts

@@ -21,6 +21,13 @@ export interface NetworkStackOptions {
   readonly dnsServers: readonly string[];
   readonly mihomoPath: string;
   readonly slirp4netnsPath: string;
+  /**
+   * holder（unshare + mihomo）输出透传。默认只用于就绪探测、内容丢弃，
+   * 因此启动失败时只剩 "exited before mihomo started"，诊断需要它。
+   */
+  readonly onHolderOutput?: (chunk: string) => void;
+  /** slirp4netns 输出透传；不传时其 stdio 保持 ignore。 */
+  readonly onSlirpOutput?: (chunk: string) => void;
 }
 
 export interface NetworkStackExecOptions {
@@ -121,9 +128,25 @@ function killChild(pid: number | undefined): void {
   }
 }
 
+/**
+ * 额外转发子进程输出给诊断回调（就绪探测的监听器不受影响）。
+ * 注册 error 监听器后 spawn 失败（如 unshare 缺失）不再以未捕获异常结束进程。
+ */
+function forwardOutput(child: ChildProcess, onOutput: ((chunk: string) => void) | undefined): void {
+  if (!onOutput) return;
+  const write = (chunk: Buffer): void => onOutput(chunk.toString());
+  child.stdout?.on("data", write);
+  child.stderr?.on("data", write);
+  child.once("error", (error) => onOutput(String(error)));
+}
+
 export interface NetworkStack {
   exec(options: NetworkStackExecOptions): Promise<{ exitCode: number | null }>;
   stop(): Promise<void>;
+  /** holder pid：可 `nsenter -U -n --preserve-credentials -t <pid>` 手动进入该 netns 排查。 */
+  readonly holderPid: number;
+  /** 生成的 mihomo 配置路径（stop() 后随临时目录一起删除）。 */
+  readonly configPath: string;
 }
 
 interface NetworkStackState {
@@ -145,7 +168,14 @@ const stackFinalizer = new FinalizationRegistry<NetworkStackState>((state) => {
  * netns/mihomo/slirp4netns 均已就绪，命令通过 nsenter 进入该 netns 执行。
  */
 export async function startNetworkStack(options: NetworkStackOptions): Promise<NetworkStack> {
-  const { allowlist, dnsServers, mihomoPath, slirp4netnsPath } = options;
+  const {
+    allowlist,
+    dnsServers,
+    mihomoPath,
+    slirp4netnsPath,
+    onHolderOutput: holderOutput,
+    onSlirpOutput: slirpOutput,
+  } = options;
   const directory = await mkdtemp(join(tmpdir(), "pi-netns-"));
   const configPath = join(directory, "mihomo.json");
   const config = generateMihomoConfig({ allowlist, dnsServers });
@@ -159,6 +189,7 @@ export async function startNetworkStack(options: NetworkStackOptions): Promise<N
     // mihomo 日志经 holder 透传到这里的 stdout/stderr，用于判定就绪
     stdio: ["ignore", "pipe", "pipe"],
   });
+  forwardOutput(holder, holderOutput);
   if (holder.pid === undefined) {
     throw new Error("Failed to start network namespace holder");
   }
@@ -175,8 +206,10 @@ export async function startNetworkStack(options: NetworkStackOptions): Promise<N
       String(holderPid),
       "tap0",
     ],
-    { stdio: "ignore" },
+    // 默认丢弃 slirp4netns 日志；诊断时改为管道转发
+    { stdio: slirpOutput ? ["ignore", "pipe", "pipe"] : "ignore" },
   );
+  forwardOutput(slirp, slirpOutput);
   const slirpPid = slirp.pid;
   await waitForMihomoStarted(holder);
 
@@ -253,6 +286,8 @@ export async function startNetworkStack(options: NetworkStackOptions): Promise<N
       killProcess(state.holderPid);
       await rm(state.directory, { recursive: true, force: true }).catch(() => false);
     },
+    holderPid,
+    configPath,
   };
   stackFinalizer.register(stack, state);
   return stack;

package/src/bwrap/runtime.ts

@@ -5,7 +5,6 @@ import { dirname, join } from "node:path";
 
 import {
   type AgentToolUpdateCallback,
-  createLocalBashOperations,
   type ExtensionAPI,
   type ExtensionCommandContext,
   type ExtensionContext,
@@ -28,8 +27,6 @@ import { type ApprovalRule, evaluateBashApproval, matchRule } from "./approval-r
 import { commandPatternsFor } from "./approval-suggest.js";
 import {
   type BwrapMode,
-  createBwrapBashOperations,
-  createNetworkStack,
   findBwrap,
   getBwrapConfigPaths,
   loadBwrapConfig,
@@ -39,6 +36,7 @@ import {
   resolveHeadlessBwrap,
 } from "./core.js";
 import { dcgSuggestion } from "./dcg-scan.js";
+import { loadSandboxConfig, runInSandbox } from "./sandbox.js";
 
 export type EscalationDecision = { kind: "dialog" } | { kind: "deny"; reason: string };
 
@@ -345,7 +343,7 @@ export class BwrapRuntime {
   }
 
   setMode(cwd: string, mode: BwrapMode): ResolvedBwrap {
-    this.resolved = resolveBwrap({ ...loadBwrapConfig(cwd), mode });
+    this.resolved = loadSandboxConfig({ workspace: cwd, mode });
     this.sandboxDisabled = false;
     return this.resolved;
   }
@@ -389,21 +387,8 @@ export class BwrapRuntime {
         await this.approveFullAccess(request.ctx, request.command, request.description, execCwd);
       }
     }
+    // 不经沙箱的三种情形：Windows（无 bubblewrap）、审批通过的全权限、allow-all 模式
     const local = isWindows || needsApproval || !runtime.bwrapEnabled;
-    // 每次命令现建网络栈（启动约 140ms），作用域结束自动停栈；allowlist 变化即时生效
-    const networkStack = local ? undefined : await createNetworkStack(runtime);
-    await using _stack = {
-      async [Symbol.asyncDispose]() {
-        try {
-          await networkStack?.stop();
-        } catch {
-          // best-effort：停栈失败（进程已退出/目录删除失败）不掩盖命令结果
-        }
-      },
-    };
-    const operations = local
-      ? createLocalBashOperations()
-      : createBwrapBashOperations(runtime, workspace, networkStack);
     await using output = new BashOutput(request.ctx.sessionManager.getSessionId());
     const { onUpdate } = request;
 
@@ -420,8 +405,12 @@ export class BwrapRuntime {
     );
 
     try {
-      if (onUpdate) onUpdate({ content: [], details: undefined });
-      const { exitCode } = await operations.exec(request.command, execCwd, {
+      onUpdate?.({ content: [], details: undefined });
+      const { exitCode } = await runInSandbox(runtime, {
+        workspace,
+        commandCwd: execCwd,
+        command: request.command,
+        unsandboxed: local,
         onData: (data) => {
           output.append(data);
           emitUpdate();

package/src/bwrap/sandbox.ts

@@ -0,0 +1,190 @@
+/**
+ * 纯沙箱执行层：加载配置 → 解析执行策略 → 需要时现建 netns 网络栈 → 在 bwrap 里跑命令。
+ *
+ * 这里刻意不含 UI、审批与会话上下文（那些属于扩展层 runtime.ts）：
+ * pi 的 Bash 工具、`node bin/sandbox.ts` 和集成测试共用这条路径，
+ * 因此沙箱行为可以脱离 agent 循环单独复现和验证。
+ *
+ * 唯一的调用方交互是 `onData`（流式输出）与 `signal` / `timeout`（取消）；
+ * `log` / `onNetworkStack` 是诊断出口，用于看 holder（unshare + mihomo）与
+ * slirp4netns 的原始日志——网络栈起不来时只有它们能说明原因。
+ */
+
+import { existsSync } from "node:fs";
+
+import { createLocalBashOperations } from "@earendil-works/pi-coding-agent";
+
+import { expandHome } from "../lib/path.js";
+import {
+  buildBwrapInvocation,
+  bwrapArgv,
+  type BwrapConfig,
+  type BwrapMode,
+  createBwrapBashOperations,
+  createNetworkStack,
+  getBwrapConfigPaths,
+  loadBwrapConfig,
+  type NetworkStackLog,
+  resolveBwrap,
+  resolveBwrapPath,
+  type ResolvedBwrap,
+  resolveHeadlessBwrap,
+} from "./core.js";
+import type { NetworkStack } from "./network-stack.js";
+
+export interface SandboxConfigInput {
+  /** 沙箱工作区：默认配置文件的查找目录，也是 writablePaths 中 "." 的解析基准。 */
+  workspace: string;
+  /** 只使用该配置文件（跳过全局 + 项目两级合并）。 */
+  configPath?: string;
+  /** 覆盖配置中的 mode（等价于会话内切 /bwrap 模式）。 */
+  mode?: BwrapMode;
+  /** 无 UI 会话策略：无论配置如何都强制 readonly。 */
+  headless?: boolean;
+}
+
+export interface SandboxRunOptions {
+  /** 沙箱工作区（可写边界与 .git 只读保护的基准），与命令执行目录解耦。 */
+  workspace: string;
+  /** 交给 `shell -lc` 的命令字符串。 */
+  command: string;
+  /** 命令执行目录，缺省同 workspace。 */
+  commandCwd?: string;
+  /** 流式输出回调（stdout 与 stderr 已合并）。 */
+  onData: (data: Buffer) => void;
+  /** 取消执行：kill 整个进程组并以 AbortError 结束。 */
+  signal?: AbortSignal;
+  /** 超时秒数：kill 整个进程组并以 TimeoutError 结束。 */
+  timeout?: number;
+  /** 调用方已决定不经沙箱（审批通过的全权限、Windows）。allow-all 模式无需显式设置。 */
+  unsandboxed?: boolean;
+  /** 网络栈子进程输出转发，仅诊断用（默认丢弃）。 */
+  log?: NetworkStackLog;
+  /** 网络栈就绪回调：取 holder pid 与 mihomo 配置路径手动排查。 */
+  onNetworkStack?: (stack: NetworkStack) => void;
+}
+
+export interface SandboxRunResult {
+  /** 命令退出码；被信号杀死时为 null。 */
+  exitCode: number | null;
+}
+
+/** 把 "."/"~" 形式的路径收敛成绝对路径，使执行策略自成一体、可断言。 */
+function resolveSandboxPaths(resolved: ResolvedBwrap, workspace: string): ResolvedBwrap {
+  const expand = (paths: string[]): string[] =>
+    paths.map((path) => resolveBwrapPath(path, workspace));
+  return {
+    ...resolved,
+    writablePaths: expand(resolved.writablePaths),
+    extraWritablePaths: expand(resolved.extraWritablePaths),
+    denyPaths: expand(resolved.denyPaths),
+  };
+}
+
+/** 加载 bwrap 配置并解析成执行策略（配置文件缺失字段回落到默认值）。 */
+export function loadSandboxConfig(input: SandboxConfigInput): ResolvedBwrap {
+  const workspace = expandHome(input.workspace);
+  const configPath = input.configPath === undefined ? undefined : expandHome(input.configPath);
+  // 显式指定的配置文件必须存在：拼错路径时静默回落到默认值会让调试结论失效
+  if (configPath !== undefined && !existsSync(configPath)) {
+    throw new Error(`bwrap configuration file not found: ${configPath}`);
+  }
+  const paths =
+    configPath === undefined
+      ? getBwrapConfigPaths(workspace)
+      : // 同一文件两侧：loadBwrapConfig 内部去重，等价于「只读这一个文件」
+        { global: configPath, project: configPath };
+  const config: BwrapConfig = loadBwrapConfig(workspace, paths);
+  const configured: BwrapConfig =
+    input.mode === undefined ? config : { ...config, mode: input.mode };
+  const resolved =
+    input.headless === true ? resolveHeadlessBwrap(configured) : resolveBwrap(configured);
+  return resolveSandboxPaths(resolved, workspace);
+}
+
+/**
+ * 在 resolved 描述的沙箱里执行一条命令；net-allowlist 模式下现建现停网络栈。
+ * 超时与取消的错误语义由底层 operations.exec 抛出（TimeoutError / AbortError）。
+ */
+export async function runInSandbox(
+  resolved: ResolvedBwrap,
+  options: SandboxRunOptions,
+): Promise<SandboxRunResult> {
+  const workspace = expandHome(options.workspace);
+  const commandCwd = expandHome(options.commandCwd ?? workspace);
+  const local = options.unsandboxed === true || !resolved.bwrapEnabled;
+  // 每次执行现建网络栈（启动约 140ms），作用域结束即停栈：allowlist 变更即时生效
+  const stack = local ? undefined : await createNetworkStack(resolved, options.log);
+  try {
+    if (stack) {
+      options.onNetworkStack?.(stack);
+    }
+    const operations = local
+      ? createLocalBashOperations()
+      : createBwrapBashOperations(resolved, workspace, stack);
+    const { exitCode } = await operations.exec(options.command, commandCwd, {
+      onData: options.onData,
+      signal: options.signal,
+      timeout: options.timeout,
+    });
+    return { exitCode };
+  } finally {
+    try {
+      await stack?.stop();
+    } catch {
+      // best-effort：停栈失败（进程已退出/目录删除失败）不掩盖命令结果
+    }
+  }
+}
+
+/** 一步式入口：按配置加载策略并在对应沙箱里执行命令（CLI 与集成测试用）。 */
+export async function runSandboxCommand(
+  options: SandboxConfigInput & Omit<SandboxRunOptions, "unsandboxed">,
+): Promise<SandboxRunResult> {
+  return runInSandbox(loadSandboxConfig(options), options);
+}
+
+/** holder 尚未启动时，预览 argv 中标记 holder pid 位置的占位符。 */
+export const HOLDER_PID_PLACEHOLDER = "<HOLDER_PID>";
+
+export interface SandboxPreview {
+  /** 完整 argv，逐项给出（结构化输出，不拼 shell 文本，无需 quoting 即可读懂）。 */
+  argv: string[];
+  /** 沙箱内环境（不继承父进程）。 */
+  env: Record<string, string>;
+  /** 需要先有 netns holder 才能真正执行（此时 argv 中的 pid 可能是 HOLDER_PID_PLACEHOLDER）。 */
+  needsNetworkStack: boolean;
+}
+
+/**
+ * 打印将要执行的命令行（`--print-args`）。与 runInSandbox 共用同一段组装逻辑，
+ * 不存在「打印的是一回事、跑的是另一回事」的漂移。
+ */
+export async function previewSandboxCommand(
+  resolved: ResolvedBwrap,
+  options: Pick<SandboxRunOptions, "workspace" | "command" | "commandCwd" | "unsandboxed"> & {
+    holderPid?: number;
+  },
+): Promise<SandboxPreview> {
+  const workspace = expandHome(options.workspace);
+  const commandCwd = expandHome(options.commandCwd ?? workspace);
+  const invocation = await buildBwrapInvocation(resolved, workspace, options.command, commandCwd);
+  if (!invocation.needsNetworkStack || options.unsandboxed === true) {
+    return { argv: bwrapArgv(invocation), env: invocation.env, needsNetworkStack: false };
+  }
+  return {
+    // 与 network-stack.ts 的实际 spawn 一致；holder 未启动时用占位符标出 pid 的位置
+    argv: [
+      "nsenter",
+      "-U",
+      "-n",
+      "--preserve-credentials",
+      "-t",
+      options.holderPid === undefined ? HOLDER_PID_PLACEHOLDER : String(options.holderPid),
+      "--",
+      ...bwrapArgv(invocation),
+    ],
+    env: invocation.env,
+    needsNetworkStack: true,
+  };
+}