@trim21/personal-pi-extensions 0.1.680 → 0.1.683

package/README.md

@@ -36,10 +36,12 @@
 - **嵌套调用经工具总线**：`call("Bash", { command })` 最终执行的是 `Bash` 工具自己的
   `execute`，所以工具的审批照常生效（Bash 沙箱外执行会弹自己的提权确认）。codemode
   不额外加确认层：脚本里连发十次调用就是十次工具自己的审批（需要审批的那些）。
-- **可调用集合** = 总线上实际注册的工具减去排除名单（`codemode` 自身、`spawn-agent`、
-  以及两套文件工具集的 `Read`/`Edit`/`Write` 与 `read`/`edit`/`write`），执行时再与当前
-  active 列表求交，所以 `personalExtensions.disabledTools`、pi 的 `defaultTools` /
-  `--tools`、子代理的工具白名单都同样约束脚本。
+- **可调用集合** = 总线上实际注册的工具减去排除名单，执行时再与当前 active 列表求交，
+  所以 `personalExtensions.disabledTools`、pi 的 `defaultTools` / `--tools`、子代理的工具
+  白名单都同样约束脚本。排除名单：`codemode` 自身与 `spawn-agent`；两套文件工具集的
+  读写工具（`Read`/`Edit`/`Write` 与 `read`/`edit`/`write`）；两套工具集的搜索工具
+  （`Grep`/`Glob` 与 `grep`/`glob`）——脚本搜文件用 `call("Bash", { command: "rg …" })`，
+  走同一个沙箱、拿得到退出码，还能拼管道，而那两个工具是给模型看结果的。
 - **文件读写只有 `fs` 一条路**：`fs.read(path)` 返回文件全文的原始 UTF-8 文本（不加行号、
   不截断、不设大小上限，只有内容不是合法 UTF-8 时报错），`fs.write(path, content)` 整体写入并自动创建
   父目录，相对路径相对当前 cwd。`fs.write` 与写类工具共用同一套保护：写前要求「已读且读后
@@ -49,10 +51,12 @@
   直接改，不进脚本）。
 - **只有脚本输出进上下文**：`text(value)` / `console.log(...)` 与 `return` 值进入工具结果，
   中间的工具调用与它们的返回内容不会（也不在会话记录里留下工具调用条目）。
-- **返回值**：声明了 `structuredSchema` 的工具（如 gh-readonly 的读类工具）把结果放在
-  `structuredResult` 里，`call()` 解包成对象给脚本；`{ ok: false, error }` 会 reject 成
-  `CallFailedError`（脚本可按 `instanceof CallFailedError` 区分调用失败与自身运行期错误）。
-  没有声明输出结构的工具回退成工具输出的文本。
+- **返回值**：声明了 `structuredSchema` 的工具把结果放在 `structuredResult` 里，`call()`
+  解包成对象给脚本——gh-readonly 的读类工具给解析后的 JSON，`Bash` / `bash` 给
+  `{ exitCode, output }`（`exitCode` 为 `null` 表示命令被超时/中止杀掉；命令非零退出是正常
+  结果，直接读 `exitCode` 分支即可）。`{ ok: false, error }` 会 reject 成 `CallFailedError`
+  （脚本可按 `instanceof CallFailedError` 区分调用失败与自身运行期错误）。没有声明输出
+  结构的工具回退成工具输出的文本。
 - **脚本接口**：`call` / `CallFailedError` / `ALL_TOOLS` / `fs.read` / `fs.write` /
   `text` / `image` / `exit` / `console.*` / `store.set` / `store.get` / `store.list`
   （会话内持久的键值表）；首行可选 `// @options: {"max_output_tokens": 10000}`。
@@ -64,7 +68,10 @@
   时头尾截断并把全文落到 `$TMPDIR/pi-codemode-*.txt`。
 - **构建**：worker 入口是 esbuild 产物 `src/codemode/worker.js`（随仓库提交，
   `pnpm run build:codemode-worker` 重新生成，pre-commit 会自动跑）；`quickjs-wasi` 的
-  wasm 在注册工具时编译一次，之后每次执行复用。
+  wasm 在注册工具时编译一次，之后每次执行复用。产物必须**自包含**：它由 `new Worker(url)`
+  作为普通 Node 模块加载，不像主线程那样经 jiti 从 pi 的 `node_modules` 解析裸包名，所以
+  除了 `quickjs-wasi`（我们自己的 dependency）之外的依赖都要打包进去——否则用户装好包后
+  worker 会在启动时报 `Cannot find package`。
 
 ## 工具启用配置
 
@@ -422,7 +429,7 @@ Claude Code 风格工具集：`Read` / `Edit` / `Write` / `Grep` / `Glob` / `Bas
 
 - **`Read` / `Edit` / `Write`**：与 opencode 风格共享 read-before-write 记账与文案（`File has not been read yet...` / `File has been modified since read...`），差异是三者都要求先 `Read`（`Edit` 用空 `old_string` 创建新文件、`Write` 创建新文件例外）。`Read` 支持 offset / limit 分页与 PDF `pages`
 - **`Grep` / `Glob`**：ripgrep 实现，行为跟随 Claude Code（`Glob` 带 `--no-ignore` / `--hidden` / `--sort=modified`，与 opencode 风格 `glob` 的差异是各自跟随上游）
-- **`Bash`**：与 opencode 风格 `bash` 共享 bwrap 运行时与 `dangerouslyDisableSandbox` 提权，默认超时 120 秒，只支持同步执行
+- **`Bash`**：与 opencode 风格 `bash` 共享 bwrap 运行时与 `dangerouslyDisableSandbox` 提权，默认超时 120 秒，只支持同步执行。结构化结果给 `{ exitCode, output }`：`output` 是命令的**完整**输出（文本该截断还截断，载荷里是全文），`exitCode` 为 `null` 表示被超时/中止杀掉；命令非零退出不是失败，脚本直接读 `exitCode` 分支
 - **`TodoWrite`**：任务列表工具（`merge` 语义），与 opencode 风格 `todowrite` 的完整替换语义不同，不要混用
 - **`AskUserQuestion`**：阻塞式向用户提问
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.680",
+  "version": "0.1.683",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -28,7 +28,7 @@
     "aft-search": "jiti bin/aft-search.ts",
     "build:holder": "esbuild src/bwrap/holder.ts --format=esm --target=node24 --outfile=src/bwrap/holder.js",
     "prepare": "husky",
-    "build:codemode-worker": "esbuild src/codemode/worker.ts --bundle --packages=external --format=esm --target=node24 --outfile=src/codemode/worker.js"
+    "build:codemode-worker": "esbuild src/codemode/worker.ts --bundle --platform=node --external:quickjs-wasi --format=esm --target=node24 --outfile=src/codemode/worker.js"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": ">=0.84.1",

package/src/claude-code/shell.ts

@@ -17,7 +17,7 @@ import {
   sandboxHintBlock,
 } from "../bwrap/runtime.js";
 import { resolveWorkdir } from "../lib/path.js";
-import type { ToolBus } from "../lib/tool-bus.js";
+import { defineStructuredTool, type ToolBus } from "../lib/tool-bus.js";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
 const MAX_TIMEOUT_MS = 7_200_000;
@@ -66,6 +66,39 @@ function appendTruncationNotice(
   return `${text}\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines} (${formatSize(truncation.maxBytes)} limit). Full output: ${fullOutputPath}]`;
 }
 
+/**
+ * `Bash` 的结构化结果：只有退出码与完整输出——命令非零退出不是失败，所以载荷里没有成败
+ * 标志，脚本直接读 `exitCode` 分支；超时/中止时 `exitCode` 为 `null`（原因在模型侧文本里）。
+ */
+const bashStructuredSchema = Type.Object({
+  exitCode: Type.Union([Type.Number(), Type.Null()], {
+    description: "Exit code of the command; null when it was killed (timeout or abort)",
+  }),
+  output: Type.String({
+    description:
+      "Complete output of the command (stdout and stderr merged). Never truncated, never mixed with tool-added notices.",
+  }),
+});
+
+/**
+ * 载荷里的输出：文本被截断时读回落盘的完整输出（读不到就退回那份截断文本），
+ * 因此脚本拿到的永远是命令真正输出的内容。
+ */
+async function fullOutput(
+  output: string,
+  truncation: TruncationResult,
+  spillPath: string | undefined,
+): Promise<string> {
+  if (spillPath === undefined || !truncation.truncated) {
+    return output;
+  }
+  try {
+    return await readFile(spillPath, "utf8");
+  } catch {
+    return output;
+  }
+}
+
 /**
  * 成功路径：消费 runtime 的截断结果（输出已由 runtime 截断并落盘），
  * 截断时追加 `[Showing lines X-Y of N. Full output: path]` 提示。
@@ -88,116 +121,154 @@ function formatBashSuccess(result: Awaited<ReturnType<BwrapRuntime["execute"]>>)
  * 测试可注入预置模式的实例。状态随扩展实例生命周期，session 切换重建即重置。
  */
 export function registerShellTools(bus: ToolBus, pi: ExtensionAPI, runtime: BwrapRuntime): void {
-  bus.register({
-    name: "Bash",
-    promptSnippet: "execute command",
-    promptGuidelines: [BASH_PROMPT],
-    label: "Bash",
-    description: [
-      "Executes a given bash command synchronously and returns its output.",
-      "timeout is in milliseconds, defaults to 120000, and may not exceed 7200000.",
-      "Every command runs in the foreground. Background command execution is not supported; shell jobs are waited for before the tool returns.",
-    ].join("\n"),
-    parameters: Type.Object(
-      {
-        command: Type.String({ description: "The command to execute" }),
-        timeout: Type.Optional(
-          Type.Number({ description: "Optional timeout in milliseconds (max 7200000)" }),
-        ),
-        description: Type.Optional(
-          Type.String({ description: "Clear, concise description of the command" }),
-        ),
-        workdir: Type.Optional(
-          Type.String({
-            description:
-              "Working directory to execute the command in. Defaults to the current directory; relative paths resolve from there.",
-          }),
-        ),
-        dangerouslyDisableSandbox: Type.Optional(
-          Type.Boolean({
-            description:
-              "Request one-time unsandboxed execution. The user must approve this request.",
-          }),
-        ),
-      },
-      { additionalProperties: false },
-    ),
-    async execute(id, params, signal, onUpdate, ctx) {
-      const timeout = params.timeout ?? DEFAULT_TIMEOUT_MS;
-      if (!Number.isFinite(timeout) || timeout <= 0 || timeout > MAX_TIMEOUT_MS) {
-        throw new Error(`timeout must be between 1 and ${MAX_TIMEOUT_MS} milliseconds`);
-      }
+  bus.register(
+    defineStructuredTool({
+      name: "Bash",
+      promptSnippet: "execute command",
+      promptGuidelines: [BASH_PROMPT],
+      label: "Bash",
+      description: [
+        "Executes a given bash command synchronously and returns its output.",
+        "timeout is in milliseconds, defaults to 120000, and may not exceed 7200000.",
+        "Every command runs in the foreground. Background command execution is not supported; shell jobs are waited for before the tool returns.",
+      ].join("\n"),
+      parameters: Type.Object(
+        {
+          command: Type.String({ description: "The command to execute" }),
+          timeout: Type.Optional(
+            Type.Number({ description: "Optional timeout in milliseconds (max 7200000)" }),
+          ),
+          description: Type.Optional(
+            Type.String({ description: "Clear, concise description of the command" }),
+          ),
+          workdir: Type.Optional(
+            Type.String({
+              description:
+                "Working directory to execute the command in. Defaults to the current directory; relative paths resolve from there.",
+            }),
+          ),
+          dangerouslyDisableSandbox: Type.Optional(
+            Type.Boolean({
+              description:
+                "Request one-time unsandboxed execution. The user must approve this request.",
+            }),
+          ),
+        },
+        { additionalProperties: false },
+      ),
+      async execute(id, params, signal, onUpdate, ctx) {
+        const timeout = params.timeout ?? DEFAULT_TIMEOUT_MS;
+        if (!Number.isFinite(timeout) || timeout <= 0 || timeout > MAX_TIMEOUT_MS) {
+          throw new Error(`timeout must be between 1 and ${MAX_TIMEOUT_MS} milliseconds`);
+        }
 
-      const cwd = params.workdir ? await resolveWorkdir(params.workdir, ctx.cwd) : ctx.cwd;
+        const cwd = params.workdir ? await resolveWorkdir(params.workdir, ctx.cwd) : ctx.cwd;
 
-      let result: Awaited<ReturnType<BwrapRuntime["execute"]>>;
-      try {
-        result = await runtime.execute({
-          ctx,
-          cwd,
-          toolCallId: id,
-          command: params.command,
-          timeout: timeout / 1000,
-          requestFullAccess: params.dangerouslyDisableSandbox,
-          description: params.description,
-          signal,
-          onUpdate,
-        });
-      } catch (error) {
-        if (!(error instanceof Error)) {
-          throw error;
-        }
-        if (error instanceof BashInterruptedError) {
-          // 输出在前（必要时带截断提示），状态文本在最后
-          const text = appendTruncationNotice(
-            error.partial.output || "",
-            error.partial.truncation,
-            error.partial.fullOutputPath,
-          );
-          if (error.kind === "aborted") {
-            // 用户取消：直接返回已捕获的输出，不抛错；时长只算命令真正运行的时间，
-            // 不含审批弹窗等 UI 交互
-            const status = `Command aborted by user after ${formatElapsedSeconds(error.elapsedMs)}`;
+        let result: Awaited<ReturnType<BwrapRuntime["execute"]>>;
+        try {
+          result = await runtime.execute({
+            ctx,
+            cwd,
+            toolCallId: id,
+            command: params.command,
+            timeout: timeout / 1000,
+            requestFullAccess: params.dangerouslyDisableSandbox,
+            description: params.description,
+            signal,
+            onUpdate,
+          });
+        } catch (error) {
+          if (!(error instanceof Error)) {
+            throw error;
+          }
+          if (error instanceof BashInterruptedError) {
+            // 输出在前（必要时带截断提示），状态文本在最后
+            const text = appendTruncationNotice(
+              error.partial.output || "",
+              error.partial.truncation,
+              error.partial.fullOutputPath,
+            );
+            if (error.kind === "aborted") {
+              // 用户取消：直接返回已捕获的输出，不抛错；时长只算命令真正运行的时间，
+              // 不含审批弹窗等 UI 交互
+              const status = `Command aborted by user after ${formatElapsedSeconds(error.elapsedMs)}`;
+              return {
+                content: [
+                  { type: "text" as const, text: text ? `${text}\n\n${status}` : status },
+                  ...sandboxHintBlock(error.sandboxReminder),
+                ],
+                details: undefined,
+                structuredResult: {
+                  ok: true as const,
+                  value: {
+                    exitCode: null,
+                    output: await fullOutput(
+                      error.partial.output,
+                      error.partial.truncation,
+                      error.partial.fullOutputPath,
+                    ),
+                  },
+                },
+              };
+            }
+            const full = text
+              ? `${text}\n\nCommand timed out after ${timeout} milliseconds`
+              : `Command timed out after ${timeout} milliseconds`;
             return {
               content: [
-                { type: "text", text: text ? `${text}\n\n${status}` : status },
+                { type: "text" as const, text: full },
+                ...sandboxHintBlock(error.sandboxHint),
                 ...sandboxHintBlock(error.sandboxReminder),
               ],
               details: undefined,
+              structuredResult: {
+                ok: true as const,
+                value: {
+                  exitCode: null,
+                  output: await fullOutput(
+                    error.partial.output,
+                    error.partial.truncation,
+                    error.partial.fullOutputPath,
+                  ),
+                },
+              },
             };
           }
-          const full = text
-            ? `${text}\n\nCommand timed out after ${timeout} milliseconds`
-            : `Command timed out after ${timeout} milliseconds`;
+          throw error;
+        }
+
+        // 对齐 Claude Code：非 0 退出码都算失败（不做 grep/find 等命令语义化特判）。
+        // 失败是命令的正常结果而不是异常：与成功一样 return，文本用完整输出
+        // （从落盘文件读取，必要时头尾截断），沙箱状态另行附一块
+        if (result.exitCode !== 0 && result.exitCode !== null) {
+          const full = result.fullOutputPath
+            ? await readFile(result.fullOutputPath, "utf8")
+            : result.output;
           return {
             content: [
-              { type: "text", text: full },
-              ...sandboxHintBlock(error.sandboxHint),
-              ...sandboxHintBlock(error.sandboxReminder),
+              { type: "text" as const, text: formatBashError(result.exitCode, full) },
+              ...sandboxHintBlock(result.sandboxHint),
+              ...sandboxHintBlock(result.sandboxReminder),
             ],
             details: undefined,
+            structuredResult: {
+              ok: true as const,
+              value: { exitCode: result.exitCode, output: full },
+            },
           };
         }
-        throw error;
-      }
-
-      // 对齐 Claude Code：非 0 退出码都算失败（不做 grep/find 等命令语义化特判）。
-      // 失败是命令的正常结果而不是异常：与成功一样 return，文本用完整输出
-      // （从落盘文件读取，必要时头尾截断），沙箱状态另行附一块
-      if (result.exitCode !== 0 && result.exitCode !== null) {
-        const full = result.fullOutputPath
-          ? await readFile(result.fullOutputPath, "utf8")
-          : result.output;
         return {
-          content: [
-            { type: "text", text: formatBashError(result.exitCode, full) },
-            ...sandboxHintBlock(result.sandboxHint),
-            ...sandboxHintBlock(result.sandboxReminder),
-          ],
-          details: undefined,
+          ...formatBashSuccess(result),
+          structuredResult: {
+            ok: true as const,
+            value: {
+              exitCode: result.exitCode,
+              output: await fullOutput(result.output, result.truncation, result.fullOutputPath),
+            },
+          },
         };
-      }
-      return formatBashSuccess(result);
-    },
-  });
+      },
+      structuredSchema: bashStructuredSchema,
+    }),
+  );
 }

package/src/codemode/tool.ts

@@ -36,7 +36,10 @@ export const CODEMODE_TOOL_NAME = "codemode";
  * - codemode 自身（防递归）；
  * - spawn-agent：它启动一个新的隔离会话，成本与运行时长都不适合放进脚本编排；
  * - 两套文件工具集的读写工具：脚本用 `fs.read` / `fs.write`（原文、不截断、按路径整体
- *   写入），不重复给一套为 LLM 上下文设计的行号/锚点语义。
+ *   写入），不重复给一套为 LLM 上下文设计的行号/锚点语义；
+ * - 两套工具集的搜索工具：脚本用 `call("Bash", { command })` 跑 `rg` / `grep` 更顺手——
+ *   退出码可用、能拼管道，而这两个工具是给模型看结果的（相对路径、分组渲染、分页尾巴），
+ *   声明块（尤其 Grep 的参数表与三选一输出）也白占 codemode 的描述篇幅。
  */
 const EXCLUDED_TOOL_NAMES: ReadonlySet<string> = new Set([
   CODEMODE_TOOL_NAME,
@@ -47,6 +50,10 @@ const EXCLUDED_TOOL_NAMES: ReadonlySet<string> = new Set([
   "read",
   "edit",
   "write",
+  "Grep",
+  "Glob",
+  "grep",
+  "glob",
 ]);
 
 /** 估计 token 用的字符数（与 pi 一致）。 */