@trim21/personal-pi-extensions 0.0.241 → 0.0.243

package/README.md

@@ -17,6 +17,14 @@
 | [question](#question)           | opencode 风格的提问工具，阻塞式询问用户选择             |
 | [talk](#talk)                   | session 间消息传递，SQLite 邮箱 + 双向 ask 时间戳仲裁   |
 
+> **两套工具风格，按预期只启用其中一套**：本包同时提供 opencode 风格
+> （小写 `read`/`edit`/`write`/`bash`/`todowrite`/`question`）与 Claude Code
+> 风格（大写 `Read`/`Edit`/`Write`/`Bash`/`Grep`/`Glob`/`TodoWrite`/
+> `AskUserQuestion`）两套工具集，二者共享 bwrap 沙箱与写保护实现。两套同时
+> 启用会带来预期外的冗余：同名命令重复注册（如 `/bwrap` 出现 `/bwrap:1`
+> 后缀）、系统提示重复注入。请只启用其中一套：在 `~/.pi/agent/settings.json`
+> 的 `defaultTools` 中只列出一套，或启动时用 `--exclude-tools` 排除另一套。
+
 ---
 
 ## bwrap

package/package.json

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

package/src/bwrap/runtime.ts

@@ -320,5 +320,3 @@ export class BwrapRuntime {
 export function createBwrapRuntime(): BwrapRuntime {
   return new BwrapRuntime();
 }
-
-export const bwrapRuntime = createBwrapRuntime();

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/claude-code/shell.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { bwrapRuntime } from "../bwrap/runtime.js";
+import { type BwrapRuntime, createBwrapRuntime } from "../bwrap/runtime.js";
 import { resolveWorkdir } from "../lib/path.js";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
@@ -13,8 +13,15 @@ const MAX_TIMEOUT_MS = 600_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();
 
-export function registerShellTools(pi: ExtensionAPI): void {
-  bwrapRuntime.setup(pi);
+/**
+ * runtime 由调用方注入：扩展工厂持有一个实例（不依赖模块级全局状态），
+ * 测试可注入预置模式的实例。状态随扩展实例生命周期，session 切换重建即重置。
+ */
+export function registerShellTools(
+  pi: ExtensionAPI,
+  runtime: BwrapRuntime = createBwrapRuntime(),
+): void {
+  runtime.setup(pi);
   pi.registerTool({
     name: "Bash",
     promptSnippet: "execute command",
@@ -58,7 +65,7 @@ export function registerShellTools(pi: ExtensionAPI): void {
       const cwd = params.workdir ? await resolveWorkdir(params.workdir, ctx.cwd) : ctx.cwd;
 
       try {
-        return await bwrapRuntime.execute({
+        return await runtime.execute({
           ctx: { ...ctx, cwd },
           toolCallId: id,
           command: params.command,

package/src/opencode/bash.ts

@@ -1,14 +1,17 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { bwrapRuntime } from "../bwrap/runtime.js";
+import { createBwrapRuntime } from "../bwrap/runtime.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 {
-  bwrapRuntime.setup(pi);
+  // 每个扩展实例持有自己的 runtime：不依赖模块级全局状态，状态随扩展
+  // 实例生命周期（进程启动 / /reload / session 切换时工厂重建即重置）。
+  const runtime = createBwrapRuntime();
+  runtime.setup(pi);
   pi.registerTool({
     name: "bash",
     label: "bash",
@@ -52,7 +55,7 @@ export default function opencodeBash(pi: ExtensionAPI): void {
       const cwd = params.workdir ? await resolveWorkdir(params.workdir, ctx.cwd) : ctx.cwd;
 
       try {
-        return await bwrapRuntime.execute({
+        return await runtime.execute({
           ctx: { ...ctx, cwd },
           toolCallId: id,
           command: params.command,

package/src/spawn-agent.ts

@@ -54,9 +54,9 @@ const MAX_PROGRESS_LINES = 5;
  * built-in tool, the matching opencode extension is loaded via `-e` so the
  * subagent uses the enhanced implementation instead of the built-in one.
  *
- * The bash override also carries the bwrap sandbox: opencode/bash.ts calls
- * bwrapRuntime.setup() and runs commands through bwrapRuntime.execute(), so
- * agents that declare the bash tool get sandboxing automatically. Agents
+ * The bash override also carries the bwrap sandbox: opencode/bash.ts creates
+ * its own bwrap runtime instance and runs commands through runtime.execute(),
+ * so agents that declare the bash tool get sandboxing automatically. Agents
  * without bash need no bwrap setup (there are no commands to sandbox).
  * (Workspace write protection is embedded in the opencode write/edit tools.)
  *