@trim21/personal-pi-extensions 0.0.240 → 0.0.242

package/package.json

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

package/src/bwrap/core.ts

@@ -167,7 +167,13 @@ function findDefaultBwrap(): string {
 }
 
 export function findBwrap(override?: string): string {
-  return override ?? findDefaultBwrap();
+  if (override) {
+    if (!existsSync(override)) {
+      throw new Error(`bwrap not found at configured path: ${override}`);
+    }
+    return override;
+  }
+  return findDefaultBwrap();
 }
 
 export function buildBwrapArgs(resolved: ResolvedBwrap, cwd: string): string[] {

package/src/bwrap/runtime.ts

@@ -73,6 +73,7 @@ function notifyMode(
 export class BwrapRuntime {
   private resolved: ResolvedBwrap | undefined;
   private sandboxDisabled = false;
+  private bwrapUnavailable = false;
 
   setup(pi: ExtensionAPI): void {
     pi.registerFlag("no-bwrap", {
@@ -84,13 +85,18 @@ export class BwrapRuntime {
     pi.on("session_start", (_event, ctx) => {
       this.sandboxDisabled = pi.getFlag("no-bwrap") === true && ctx.hasUI;
       this.resolved = undefined;
+      this.bwrapUnavailable = false;
       const runtime = this.resolve(ctx);
       if (runtime.bwrapEnabled) {
         try {
           findBwrap(runtime.bwrapPath);
         } catch (error) {
-          this.sandboxDisabled = true;
+          // Fail closed: a missing bwrap binary must not silently degrade to an
+          // unsandboxed allow-all session. Commands are refused until the user
+          // explicitly opts out via --no-bwrap or the bwrap-allow-all command.
+          this.bwrapUnavailable = true;
           this.resolved = undefined;
+          ctx.ui.setStatus("bwrap", ctx.ui.theme.fg("error", "bwrap: unavailable"));
           ctx.ui.notify(error instanceof Error ? error.message : "bwrap not found", "error");
           return;
         }
@@ -110,10 +116,16 @@ export class BwrapRuntime {
 
     pi.on("before_agent_start", (event, ctx) => {
       const runtime = this.resolve(ctx);
-      const prompt = ctx.hasUI
-        ? `\n\n## Command Execution\nCurrent bwrap mode: **${runtime.mode}**. The bwrap runtime selects sandboxing and, when requested, user approval for unsandboxed execution.\n`
-        : "\n\n## Command Execution\nThis headless session is forced into bwrap readonly mode. Unsandboxed execution cannot be approved.\n";
-      return { systemPrompt: event.systemPrompt + prompt };
+      const modeText = ctx.hasUI
+        ? `Current bwrap mode: **${runtime.mode}**. The bwrap runtime selects sandboxing and, when requested, user approval for unsandboxed execution.`
+        : "This headless session is forced into bwrap readonly mode. Unsandboxed execution cannot be approved.";
+      const unavailableText = this.bwrapUnavailable
+        ? " bwrap is unavailable (binary not found): bash commands are refused unless the user explicitly approves unsandboxed execution."
+        : "";
+      return {
+        systemPrompt:
+          event.systemPrompt + `\n\n## Command Execution\n${modeText}${unavailableText}\n`,
+      };
     });
 
     this.registerCommands(pi);
@@ -128,10 +140,17 @@ export class BwrapRuntime {
   reset(): void {
     this.resolved = undefined;
     this.sandboxDisabled = false;
+    this.bwrapUnavailable = false;
   }
 
   async execute(request: BwrapExecutionRequest) {
     const runtime = this.resolve(request.ctx);
+    if (this.bwrapUnavailable && runtime.bwrapEnabled && request.requestFullAccess !== true) {
+      throw new Error(
+        "bwrap (bubblewrap) not found; refusing to execute commands without sandboxing. " +
+          "Install bubblewrap and restart the session, or pass --no-bwrap to disable the sandbox explicitly.",
+      );
+    }
     if (request.requestFullAccess === true && runtime.bwrapEnabled) {
       await this.approveFullAccess(request.ctx, request.command, request.requestFullAccessReason);
     }
@@ -229,6 +248,13 @@ export class BwrapRuntime {
       handler: (args, ctx) =>
         this.runCommand(pi, specs.bwrap, args, ctx, (commandCtx) => {
           const runtime = this.resolve(commandCtx);
+          if (this.bwrapUnavailable) {
+            commandCtx.ui.notify(
+              "bwrap is unavailable: binary not found. Commands are refused unless sandboxing is explicitly disabled.",
+              "error",
+            );
+            return;
+          }
           if (!runtime.bwrapEnabled) {
             commandCtx.ui.notify(`bwrap disabled (mode: ${runtime.mode})`, "info");
             return;

package/src/claude-code/common.ts

@@ -1,10 +1,18 @@
 import { isAbsolute, normalize, resolve } from "node:path";
 
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+
 export interface FileSnapshot {
   digest: string;
   textEditable: boolean;
 }
 
+const fileSnapshotSchema = Type.Object({
+  digest: Type.String(),
+  textEditable: Type.Boolean(),
+});
+
 export interface ClaudeCodeState {
   readonly reads: Map<string, FileSnapshot>;
 }
@@ -33,3 +41,17 @@ export function throwIfAborted(signal: AbortSignal | undefined): void {
 export function snapshotsEqual(left: FileSnapshot, right: FileSnapshot): boolean {
   return left.digest === right.digest;
 }
+
+/**
+ * 从工具结果 details 里恢复文件已读记账（跨进程 resume / reload / fork）。
+ * 数据来自 session 文件，可能缺失或损坏：逐条 TypeBox 校验，非法条目丢弃。
+ * 只接受 plain object，数组、null 等异常形态直接返回空 map。
+ */
+export function deserializeReads(data: unknown): Map<string, FileSnapshot> {
+  const reads = new Map<string, FileSnapshot>();
+  if (typeof data !== "object" || data === null || Array.isArray(data)) return reads;
+  for (const [filePath, snapshot] of Object.entries(data)) {
+    if (Value.Check(fileSnapshotSchema, snapshot)) reads.set(filePath, snapshot);
+  }
+  return reads;
+}

package/src/claude-code/files.ts

@@ -44,6 +44,11 @@ export interface FileToolDetails {
   diff?: string;
   patch?: string;
   firstChangedLine?: number;
+  /**
+   * 本轮受影响文件的已读快照（path → snapshot）。随工具结果持久化到
+   * session 文件，resume 后由 session_start 重建 reads state。
+   */
+  reads?: Record<string, FileSnapshot>;
 }
 
 function snapshotOf(content: Uint8Array | string, textEditable = true): FileSnapshot {
@@ -216,8 +221,9 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
           { type: "text", text: `Read image file [${imageMime}]` },
           { type: "image", data, mimeType: imageMime },
         ];
-        state.reads.set(filePath, snapshotOf(image, false));
-        return { content, details: undefined };
+        const snapshot = snapshotOf(image, false);
+        state.reads.set(filePath, snapshot);
+        return { content, details: { reads: { [filePath]: snapshot } } };
       }
 
       const buffer = await readFile(filePath);
@@ -228,8 +234,12 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
         params.offset ?? 1,
         params.limit ?? DEFAULT_READ_LINES,
       );
-      state.reads.set(filePath, snapshotOf(buffer));
-      return { content: [{ type: "text", text: formatted.text }], details: undefined };
+      const snapshot = snapshotOf(buffer);
+      state.reads.set(filePath, snapshot);
+      return {
+        content: [{ type: "text", text: formatted.text }],
+        details: { reads: { [filePath]: snapshot } },
+      };
     },
   });
 
@@ -279,7 +289,8 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
           params.replace_all ?? false,
         );
         await writeFile(filePath, updated, "utf8");
-        state.reads.set(filePath, snapshotOf(updated));
+        const snapshot = snapshotOf(updated);
+        state.reads.set(filePath, snapshot);
         const diff = generateDiffString(original, updated);
         return {
           content: [{ type: "text", text: `The file ${filePath} has been updated successfully.` }],
@@ -287,6 +298,7 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
             diff: diff.diff,
             patch: generateUnifiedPatch(filePath, original, updated),
             firstChangedLine: diff.firstChangedLine,
+            reads: { [filePath]: snapshot },
           } satisfies FileToolDetails,
         };
       });
@@ -334,7 +346,8 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
         throwIfAborted(signal);
         await mkdir(dirname(filePath), { recursive: true });
         await writeFile(filePath, params.content, "utf8");
-        state.reads.set(filePath, snapshotOf(params.content));
+        const snapshot = snapshotOf(params.content);
+        state.reads.set(filePath, snapshot);
         const diff = generateDiffString(original ?? "", params.content);
         return {
           content: [{ type: "text", text: `File created successfully at: ${filePath}` }],
@@ -342,6 +355,7 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
             diff: diff.diff,
             patch: generateUnifiedPatch(filePath, original ?? "", params.content),
             firstChangedLine: diff.firstChangedLine,
+            reads: { [filePath]: snapshot },
           } satisfies FileToolDetails,
         };
       });

package/src/claude-code/index.ts

@@ -1,13 +1,33 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { createClaudeCodeState } from "./common.js";
+import { createClaudeCodeState, deserializeReads } from "./common.js";
 import { registerFileTools } from "./files.js";
 import { registerSearchTools } from "./search.js";
 import { registerSessionTools } from "./session-tools.js";
 import { registerShellTools } from "./shell.js";
 
+/** 会更新 reads state 并随 details 持久化快照的工具名。 */
+const FILE_TOOL_NAMES = new Set(["Read", "Edit", "Write"]);
+
 export default function claudeCodeTools(pi: ExtensionAPI): void {
   const state = createClaudeCodeState();
+
+  // 扩展实例在进程启动 / /reload / /new / /resume / /fork 时重建，内存里的
+  // 已读记账随之丢失。这里从当前分支的历史工具结果里恢复：digest 是当时的值，
+  // 若文件在此期间被外部修改，Edit/Write 时的指纹对比仍会要求重新 Read，
+  // 防呆语义不因重建而弱化。
+  pi.on("session_start", (_event, ctx) => {
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type !== "message" || entry.message.role !== "toolResult") continue;
+      if (!FILE_TOOL_NAMES.has(entry.message.toolName)) continue;
+      const details = entry.message.details as { reads?: unknown } | undefined;
+      if (!details?.reads) continue;
+      for (const [filePath, snapshot] of deserializeReads(details.reads)) {
+        state.reads.set(filePath, snapshot);
+      }
+    }
+  });
+
   registerFileTools(pi, state);
   registerSearchTools(pi);
   registerShellTools(pi);

package/src/claude-code/session-tools.ts

@@ -1,6 +1,7 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { Value } from "typebox/value";
 
 import { selectWithOptionalInput } from "../lib/ui.js";
 
@@ -102,23 +103,34 @@ async function askMultiple(
 }
 
 export function registerSessionTools(pi: ExtensionAPI): void {
+  const todoItemSchema = Type.Object(
+    {
+      content: Type.String({ minLength: 1 }),
+      status: StringEnum(TODO_STATUSES),
+      activeForm: Type.String({ minLength: 1 }),
+    },
+    { additionalProperties: false },
+  );
   const todoSchema = Type.Object(
     {
-      todos: Type.Array(
-        Type.Object(
-          {
-            content: Type.String({ minLength: 1 }),
-            status: StringEnum(TODO_STATUSES),
-            activeForm: Type.String({ minLength: 1 }),
-          },
-          { additionalProperties: false },
-        ),
-        { description: "The updated todo list" },
-      ),
+      todos: Type.Array(todoItemSchema, { description: "The updated todo list" }),
     },
     { additionalProperties: false },
   );
 
+  // TodoWrite 的列表随工具结果 details 持久化（跟随会话分支），但 widget 是
+  // 纯 TUI 状态，进程重启后丢失。session 恢复时从当前分支取最后一个 TodoWrite
+  // 的列表重新渲染（完整列表替换语义，后出现的覆盖前面的）。
+  pi.on("session_start", (_event, ctx) => {
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type !== "message" || entry.message.role !== "toolResult") continue;
+      if (entry.message.toolName !== "TodoWrite") continue;
+      if (Value.Check(todoSchema, entry.message.details)) {
+        ctx.ui.setWidget("claude-code-todos", formatTodos(entry.message.details.todos));
+      }
+    }
+  });
+
   pi.registerTool({
     name: "TodoWrite",
     label: "Todo Write",

package/src/gh-readonly.ts

@@ -29,9 +29,10 @@
  */
 
 import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { delimiter, dirname, join, resolve } from "node:path";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
@@ -52,6 +53,22 @@ interface GhResult {
 
 // ── helpers ──────────────────────────────────────────────────────────────────
 
+/**
+ * Check whether the `gh` CLI is on the system, scanning PATH like
+ * `findDefaultBwrap`. The extension registers no tools when `gh` is missing, so
+ * the model never sees GitHub tools that would fail on every call.
+ */
+export function isGhAvailable(): boolean {
+  const pathEnv = process.env.PATH ?? "";
+  for (const directory of pathEnv.split(delimiter)) {
+    if (existsSync(join(directory, "gh"))) return true;
+  }
+  for (const candidate of ["/usr/bin/gh", "/usr/local/bin/gh", "/run/current-system/sw/bin/gh"]) {
+    if (existsSync(candidate)) return true;
+  }
+  return false;
+}
+
 export function runGh(
   args: string[],
   ctx: { cwd?: string; signal?: AbortSignal; timeout?: number },
@@ -1082,6 +1099,19 @@ export async function writeLogFile(
 // ── tools ────────────────────────────────────────────────────────────────────
 
 export default function ghReadonlyTools(pi: ExtensionAPI) {
+  // Fail fast: the `gh` CLI is the only backend for these tools. Without it the
+  // extension registers nothing and reports the problem at session start, so
+  // the user gets one clear error instead of a dozen failing tool calls.
+  if (!isGhAvailable()) {
+    pi.on("session_start", (_event, ctx) => {
+      ctx.ui.notify(
+        "gh CLI not found in PATH: GitHub read-only tools are disabled. Install GitHub CLI (https://cli.github.com/) and reload the session.",
+        "error",
+      );
+    });
+    return;
+  }
+
   // ── read-github-issue ──────────────────────────────────────────────────────
   pi.registerTool({
     name: "read-github-issue",