@trim21/personal-pi-extensions 0.0.192 → 0.0.194

package/README.md

@@ -13,6 +13,7 @@
 | [vision-agent](#vision-agent)                 | 视觉代理：主模型不支持视觉时，spawn 子 agent 识别图片  |
 | [todowrite](#todowrite)                       | opencode 风格的任务列表工具，完整列表替换语义          |
 | [question](#question)                         | opencode 风格的提问工具，阻塞式询问用户选择            |
+| [talk](#talk)                                 | session 间消息传递，SQLite 邮箱 + 双向 ask 时间戳仲裁  |
 
 ---
 
@@ -187,7 +188,7 @@ opencode 风格的任务列表工具，参数与语义和 opencode 的 [`todowri
 ### 使用
 
 ```bash
-pi -e ./src/todowrite.ts
+pi -e ./src/opencode-todo.ts
 ```
 
 ---
@@ -213,6 +214,68 @@ pi -e ./src/question.ts
 
 ---
 
+## talk
+
+session 间消息传递：不同 pi session（同一台机器）通过一个共享的 SQLite 邮箱互相发送消息、提问并等待回复。
+
+### 架构（三层）
+
+```
+storage.ts   —— 存储层：TalkStorage 接口 + SqliteTalkStorage 实现（node:sqlite，零 npm 依赖）
+core.ts      —— talk 核心：registry/mailbox/policy/format + TalkCore 协调器，只依赖存储层，通过回调 yield 投递/通知
+index.ts     —— pi adapter：把 core 接到 pi 的 sendMessage / 生命周期事件 / 工具注册
+```
+
+存储层抽象成接口是为了后续可换成 HTTP / remote 后端，talk 核心无需改动。
+
+### 工具（LLM 可见）
+
+| 工具                 | 作用                                                              |
+| -------------------- | ----------------------------------------------------------------- |
+| `talk-list-sessions` | 列出其他 session（presence：idle/working/not responding/offline） |
+| `talk-read-messages` | 主动读收件箱（读即消费）                                          |
+| `talk-ask`           | 向某个 session 提问并阻塞等待回复（默认 120s 超时）               |
+| `talk-wait`          | 阻塞等待新消息到达                                                |
+| `talk-send`          | 发送纯文本消息（`to: "*"` 广播所有，`to: "cwd"` 广播同 cwd）      |
+| `talk-reply`         | 回复一个 ask（`replyTo` 为 ask id，显式关联、不推断）             |
+
+对端消息在模型工作过程中以 steer 方式注入上下文；模型也可主动 `talk-read-messages` 拉取。
+
+### 关键设计
+
+- **投递成功才消费**：信件只在成功交给 `sendMessage` 后才从 inbox 删除，投递失败留在 inbox 下次重试——不会因 `sendMessage` 吞异常而静默丢信。
+- **双向 ask 仲裁**：`talk-ask` 发起前先检查收件箱（有对方消息就先读/先回）；阻塞等待期间若收到对方的 ask（而非 reply），按两个 ask 的 `ts` 字段仲裁——先 ask 者主导继续等，后 ask 者让位并先回复对方。`ts` 是信件内固定字段，双方读到同一对值，结论天然对称；同毫秒碰撞用 `session dir + session id` 字符串比较兜底。
+- **typebox runtime 验证**：所有从存储读出的值经 TypeBox schema 校验，损坏/伪造数据被拒绝，不做 `as T` 强转。
+- **安全**：纯文本 ≤32KB；10s 去重 / 30s 限速 8 条 / 50 积压上限（防环）；每条投递带「来自其他 session、无权威」声明。
+
+### 配置
+
+sqlite 文件路径按优先级取第一个可用值：
+
+1. 环境变量 `PI_TALK_DB`
+2. global `~/.pi/agent/settings.json` 里的 `talk.db_path`
+3. 默认 `~/.pi/agent/talk.db`
+
+```jsonc
+// ~/.pi/agent/settings.json
+{
+  "talk": { "db_path": "/path/to/talk.db" },
+}
+```
+
+| 变量              | 默认                              | 含义                          |
+| ----------------- | --------------------------------- | ----------------------------- |
+| `PI_TALK_DB`      | settings 或 `~/.pi/agent/talk.db` | SQLite 邮箱数据库路径         |
+| `PI_TALK_INBOUND` | `accept`                          | `refuse` 时丢弃所有 peer 消息 |
+
+### 使用
+
+```bash
+pi -e ./src/talk/index.ts
+```
+
+---
+
 ## 安装
 
 ### 通过 npm/git 包

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.192",
+  "version": "0.0.194",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -64,8 +64,9 @@
       "src/bash-default-timeout.ts",
       "src/gh-readonly.ts",
       "src/spawn-agent.ts",
-      "src/todowrite.ts",
-      "src/question.ts"
+      "src/opencode-todo.ts",
+      "src/question.ts",
+      "src/talk/index.ts"
     ]
   },
   "lint-staged": {

package/src/opencode-edit-engine.ts

@@ -1,8 +1,9 @@
 /**
  * Opencode edit matching engine.
  *
- * The core replacers and replace() function are copied directly from
- * https://github.com/anomalyco/opencode (packages/opencode/src/tool/edit.ts)
+ * The core replacers and replace() function are copied directly from opencode
+ * commit 999be62662 (v1.2.25-1672-g999be62662, 2026-08-12):
+ *   https://github.com/anomalyco/opencode/blob/999be62662/packages/opencode/src/tool/edit.ts
  * and wrapped in a pi extension so the behaviour is identical to opencode.
  *
  * Shared by:

package/src/opencode-edit.ts

@@ -2,6 +2,14 @@
  * Opencode Edit Extension — Replaces the built-in edit tool with opencode's
  * schema and matching engine.
  *
+ * Aligned with opencode commit 999be62662 (v1.2.25-1672-g999be62662, 2026-08-12):
+ *   https://github.com/anomalyco/opencode/blob/999be62662/packages/opencode/src/tool/edit.ts
+ * The matching engine (replacers + replace()) is byte-for-byte aligned with
+ * opencode (9 replacers, 0.65 similarity threshold, 0.25 line-delta, identical
+ * error messages), and empty-oldString file creation is implemented.
+ * Known gaps (intentionally not implemented): LSP diagnostics in the result,
+ * formatter run.
+ *
  * The matching engine (replacers + replace()) lives in opencode-edit-engine.ts
  * and is also used by workspace-guard for the diff preview.
  *
@@ -10,8 +18,8 @@
  */
 
 import { constants } from "node:fs";
-import { access, readFile, writeFile } from "node:fs/promises";
-import { isAbsolute, resolve } from "node:path";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
@@ -78,6 +86,36 @@ export default function opencodeEdit(pi: ExtensionAPI) {
       return withFileMutationQueue(absolutePath, async () => {
         throwIfAborted();
 
+        // opencode: 前置校验，先于空 oldString 分支
+        if (oldString === newString) {
+          throw new Error("No changes to apply: oldString and newString are identical.");
+        }
+
+        // opencode: 空 oldString + 文件不存在 → 创建新文件；文件存在 → 报错
+        if (oldString === "") {
+          let exists = true;
+          try {
+            await access(absolutePath, constants.F_OK);
+          } catch {
+            exists = false;
+          }
+          throwIfAborted();
+          if (exists) {
+            throw new Error(
+              "oldString cannot be empty when editing an existing file. Provide the exact text to replace, or use write for an intentional full-file replacement.",
+            );
+          }
+          // opencode: writeWithDirs 自动创建父目录；newString 开头的 BOM 原样保留
+          await mkdir(dirname(absolutePath), { recursive: true });
+          throwIfAborted();
+          await writeFile(absolutePath, newString, "utf8");
+          throwIfAborted();
+          return {
+            content: [{ type: "text" as const, text: "Edit applied successfully." }],
+            details: { diff: "", patch: "", firstChangedLine: 0 },
+          };
+        }
+
         try {
           await access(absolutePath, constants.R_OK | constants.W_OK);
         } catch (error: unknown) {
@@ -113,7 +151,7 @@ export default function opencodeEdit(pi: ExtensionAPI) {
           content: [
             {
               type: "text" as const,
-              text: `Successfully edited ${filePath}`,
+              text: "Edit applied successfully.",
             },
           ],
           details: { diff: diffResult.diff, patch, firstChangedLine: diffResult.firstChangedLine },

package/src/opencode-read.ts

@@ -1,6 +1,17 @@
 /**
  * Enhanced Read Tool Extension
  *
+ * Aligned with opencode commit 999be62662 (v1.2.25-1672-g999be62662, 2026-08-12):
+ *   https://github.com/anomalyco/opencode/blob/999be62662/packages/opencode/src/tool/read.ts
+ * Aligned behaviours: per-line `N: ` line-number prefix, single-line 2000-char
+ * truncation, 1-based offset (0 treated as 1), out-of-range offset error,
+ * cut/more/end truncation messages, `localeCompare` directory sorting.
+ * Known gaps (intentionally not implemented): PDF attachment support,
+ * instruction (AGENTS.md) loading and LSP warm-up.
+ * BMP sniffing is kept but `image/bmp` is NOT in SUPPORTED_IMAGE_MIMES, so a
+ * .bmp file falls through to binary detection — matching opencode, which only
+ * serves jpeg/png/gif/webp as attachments.
+ *
  * Overrides the built-in `read` tool with additional features inspired by
  * opencode's read implementation:
  *
@@ -31,15 +42,12 @@ import { Type } from "typebox";
 
 const DEFAULT_MAX_LINES = 2000;
 const DEFAULT_MAX_BYTES = 50 * 1024;
+const MAX_LINE_LENGTH = 2000;
+const MAX_LINE_SUFFIX = `... (line truncated to ${MAX_LINE_LENGTH} chars)`;
+const MAX_BYTES_LABEL = `${DEFAULT_MAX_BYTES / 1024} KB`;
 const SAMPLE_BYTES = 4096;
 
-const SUPPORTED_IMAGE_MIMES = new Set([
-  "image/jpeg",
-  "image/png",
-  "image/gif",
-  "image/webp",
-  "image/bmp",
-]);
+const SUPPORTED_IMAGE_MIMES = new Set(["image/jpeg", "image/png", "image/gif", "image/webp"]);
 
 const BINARY_EXTENSIONS = new Set([
   ".zip",
@@ -159,13 +167,7 @@ function isBinaryFileBySample(sample: Uint8Array): boolean {
   return nonPrintableCount / sample.length > 0.3;
 }
 
-function formatSize(bytes: number): string {
-  if (bytes < 1024) return `${bytes}B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
-  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
-}
-
-interface TruncationResult {
+export interface TruncationResult {
   content: string;
   truncated: boolean;
   truncatedBy: "lines" | "bytes" | null;
@@ -173,13 +175,17 @@ interface TruncationResult {
   totalBytes: number;
   outputLines: number;
   outputBytes: number;
-  lastLinePartial: boolean;
-  firstLineExceedsLimit: boolean;
   maxLines: number;
   maxBytes: number;
 }
 
-function truncateHead(
+/**
+ * Truncate the head of `content` the way opencode's ReadTool.lines does:
+ * - per-line truncation to MAX_LINE_LENGTH chars (with MAX_LINE_SUFFIX)
+ * - line cap via maxLines (more)
+ * - byte cap via maxBytes, computed on the truncated lines (cut)
+ */
+export function truncateHead(
   content: string,
   maxLines: number = DEFAULT_MAX_LINES,
   maxBytes: number = DEFAULT_MAX_BYTES,
@@ -189,68 +195,43 @@ function truncateHead(
   const totalLines = lines.length;
   const totalBytes = Buffer.byteLength(content, "utf8");
 
-  if (totalLines <= maxLines && totalBytes <= maxBytes) {
-    return {
-      content,
-      truncated: false,
-      truncatedBy: null,
-      totalLines,
-      totalBytes,
-      outputLines: totalLines,
-      outputBytes: totalBytes,
-      lastLinePartial: false,
-      firstLineExceedsLimit: false,
-      maxLines,
-      maxBytes,
-    };
-  }
-
-  const firstLineBytes = lines.length > 0 ? Buffer.byteLength(lines[0], "utf8") : 0;
-  if (firstLineBytes > maxBytes) {
-    return {
-      content: "",
-      truncated: true,
-      truncatedBy: "bytes",
-      totalLines,
-      totalBytes,
-      outputLines: 0,
-      outputBytes: 0,
-      lastLinePartial: false,
-      firstLineExceedsLimit: true,
-      maxLines,
-      maxBytes,
-    };
-  }
-
   const outputLinesArr: string[] = [];
   let outputBytesCount = 0;
-  let truncatedBy: "lines" | "bytes" = "lines";
-
-  for (let i = 0; i < lines.length && i < maxLines; i++) {
-    const lineBytes = Buffer.byteLength(lines[i], "utf8") + (i > 0 ? 1 : 0);
+  let truncated = false;
+  let truncatedBy: "lines" | "bytes" | null = null;
+
+  for (const rawLine of lines) {
+    // opencode: 行数到达 limit 即截断（more）
+    if (outputLinesArr.length >= maxLines) {
+      truncated = true;
+      truncatedBy = "lines";
+      break;
+    }
+    // opencode: 单行超过 MAX_LINE_LENGTH 截断并追加提示
+    const line =
+      rawLine.length > MAX_LINE_LENGTH
+        ? rawLine.slice(0, MAX_LINE_LENGTH) + MAX_LINE_SUFFIX
+        : rawLine;
+    const lineBytes = Buffer.byteLength(line, "utf8") + (outputLinesArr.length > 0 ? 1 : 0);
+    // opencode: 累计字节超 MAX_BYTES 即截断（cut，优先于 more）
     if (outputBytesCount + lineBytes > maxBytes) {
+      truncated = true;
       truncatedBy = "bytes";
       break;
     }
-    outputLinesArr.push(lines[i]);
+    outputLinesArr.push(line);
     outputBytesCount += lineBytes;
   }
 
-  if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
-    truncatedBy = "lines";
-  }
-
   const outputContent = outputLinesArr.join("\n");
   return {
     content: outputContent,
-    truncated: true,
+    truncated,
     truncatedBy,
     totalLines,
     totalBytes,
     outputLines: outputLinesArr.length,
     outputBytes: Buffer.byteLength(outputContent, "utf8"),
-    lastLinePartial: false,
-    firstLineExceedsLimit: false,
     maxLines,
     maxBytes,
   };
@@ -297,7 +278,8 @@ async function formatDirectoryEntries(dirPath: string): Promise<string[]> {
     results.push(item + (isDir ? "/" : ""));
   }
 
-  results.sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+  // opencode: items.sort((a, b) => a.localeCompare(b))
+  results.sort((a, b) => a.localeCompare(b));
   return results;
 }
 
@@ -311,10 +293,16 @@ export default function opencodeRead(pi: ExtensionAPI) {
     parameters: Type.Object({
       filePath: Type.String({ description: "The absolute path to the file or directory to read" }),
       offset: Type.Optional(
-        Type.Number({ description: "The line number to start reading from (1-indexed)" }),
+        Type.Integer({
+          minimum: 0,
+          description: "The line number to start reading from (1-indexed)",
+        }),
       ),
       limit: Type.Optional(
-        Type.Number({ description: "The maximum number of lines to read (defaults to 2000)" }),
+        Type.Integer({
+          minimum: 0,
+          description: "The maximum number of lines to read (defaults to 2000)",
+        }),
       ),
     }),
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
@@ -342,8 +330,9 @@ export default function opencodeRead(pi: ExtensionAPI) {
       if (fileStat.isDirectory()) {
         const entries = await formatDirectoryEntries(absolutePath);
         const limitVal = limit ?? DEFAULT_MAX_LINES;
-        const offsetVal = offset ?? 1;
-        const start = offsetVal <= 0 ? 0 : offsetVal - 1;
+        // opencode: params.offset || 1（0 视为 1）
+        const offsetVal = offset || 1;
+        const start = offsetVal - 1;
         const sliced = entries.slice(start, start + limitVal);
         const totalEntries = entries.length;
         const truncated = start + sliced.length < totalEntries;
@@ -353,8 +342,7 @@ export default function opencodeRead(pi: ExtensionAPI) {
         output += `<entries>\n`;
         output += sliced.join("\n");
         if (truncated) {
-          const next = offsetVal + sliced.length;
-          output += `\n(Showing ${sliced.length} of ${totalEntries} entries. Use offset=${next} to continue.)`;
+          output += `\n(Showing ${sliced.length} of ${totalEntries} entries. Use 'offset' parameter to read beyond entry ${offsetVal + sliced.length})`;
         } else {
           output += `\n(${totalEntries} entries)`;
         }
@@ -386,7 +374,8 @@ export default function opencodeRead(pi: ExtensionAPI) {
         const buffer = await readFile(absolutePath);
         const base64 = buffer.toString("base64");
         content = [
-          { type: "text", text: `[Image: ${mimeType}, ${formatSize(buffer.length)}]` },
+          // opencode: output is "Image read successfully"
+          { type: "text", text: "Image read successfully" },
           { type: "image", data: base64, mimeType },
         ];
         return { content, details: undefined };
@@ -405,72 +394,52 @@ export default function opencodeRead(pi: ExtensionAPI) {
       }
 
       const textContent = buffer.toString("utf8");
+      // opencode 用 Stream.splitLines，不含末尾换行产生的空行
       const allLines = textContent.split("\n");
+      if (textContent.endsWith("\n")) allLines.pop();
       const totalFileLines = allLines.length;
 
-      // Apply offset
-      const startLine = offset ? Math.max(0, offset - 1) : 0;
+      // opencode: offset 1 起始，offset=0 视为 1（params.offset || 1）
+      const effectiveOffset = offset || 1;
+      const startLine = Math.max(0, effectiveOffset - 1);
 
-      if (startLine >= allLines.length) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Offset ${offset} is beyond end of file (${allLines.length} lines total)`,
-            },
-          ],
-          details: undefined,
-        };
+      // opencode: 越界报错（空文件 + offset=1 除外）
+      if (totalFileLines < effectiveOffset && !(totalFileLines === 0 && effectiveOffset === 1)) {
+        throw new Error(
+          `Offset ${effectiveOffset} is out of range for this file (${totalFileLines} lines)`,
+        );
       }
 
       const startLineDisplay = startLine + 1;
 
-      let details: { truncation?: TruncationResult } | undefined;
-
-      // Apply user-specified limit or default truncation
-      let selectedContent: string;
-      let userLimitedLines: number | undefined;
-
-      if (limit === undefined) {
-        selectedContent = allLines.slice(startLine).join("\n");
-      } else {
-        const endLine = Math.min(startLine + limit, allLines.length);
-        selectedContent = allLines.slice(startLine, endLine).join("\n");
-        userLimitedLines = endLine - startLine;
-      }
-
-      // Apply byte/line truncation
-      const truncation = truncateHead(selectedContent);
+      // opencode: limit 即行数上限（默认 2000）
+      const selectedContent = allLines.slice(startLine).join("\n");
+      const truncation = truncateHead(selectedContent, limit ?? DEFAULT_MAX_LINES);
       let outputText: string;
 
       const endLineDisplay = startLineDisplay + truncation.outputLines - 1;
+      const header = `<path>${absolutePath}</path>\n<type>file</type>\n<content>\n`;
+      const footer = "\n</content>";
+      // opencode: 每行 `${i + offset}: ${line}` 行号前缀
+      const numbered =
+        truncation.content === ""
+          ? ""
+          : truncation.content
+              .split("\n")
+              .map((line, i) => `${startLineDisplay + i}: ${line}`)
+              .join("\n");
 
-      if (truncation.firstLineExceedsLimit) {
-        const firstLineSize = formatSize(Buffer.byteLength(allLines[startLine], "utf8"));
-        outputText = `<path>${absolutePath}</path>\n<type>file</type>\n`;
-        outputText += `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(DEFAULT_MAX_BYTES)} limit. Use bash to read this line.]`;
-        details = { truncation };
-      } else {
-        const header = `<path>${absolutePath}</path>\n<type>file</type>\n<content>\n`;
-        const footer = "\n</content>";
-        if (truncation.truncated) {
-          const nextOffset = endLineDisplay + 1;
-          if (truncation.truncatedBy === "lines") {
-            outputText = `${header}${truncation.content}\n\n(Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue.)${footer}`;
-          } else {
-            outputText = `${header}${truncation.content}\n\n(Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Use offset=${nextOffset} to continue.)${footer}`;
-          }
-          details = { truncation };
-        } else if (
-          userLimitedLines !== undefined &&
-          startLine + userLimitedLines < allLines.length
-        ) {
-          const remaining = allLines.length - (startLine + userLimitedLines);
-          const nextOffset = startLine + userLimitedLines + 1;
-          outputText = `${header}${truncation.content}\n\n(${remaining} more lines in file. Use offset=${nextOffset} to continue.)${footer}`;
+      let details: { truncation?: TruncationResult } | undefined;
+      if (truncation.truncated) {
+        const nextOffset = endLineDisplay + 1;
+        if (truncation.truncatedBy === "bytes") {
+          outputText = `${header}${numbered}\n\n(Output capped at ${MAX_BYTES_LABEL}. Showing lines ${startLineDisplay}-${endLineDisplay}. Use offset=${nextOffset} to continue.)${footer}`;
         } else {
-          outputText = `${header}${truncation.content}\n\n(End of file - total ${totalFileLines} lines)${footer}`;
+          outputText = `${header}${numbered}\n\n(Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue.)${footer}`;
         }
+        details = { truncation };
+      } else {
+        outputText = `${header}${numbered}\n\n(End of file - total ${totalFileLines} lines)${footer}`;
       }
 
       content = [{ type: "text", text: outputText }];

package/src/{todowrite.ts → opencode-todo.ts}

@@ -1,6 +1,12 @@
 /**
  * todowrite —— opencode 风格的任务列表工具
  *
+ * Aligned with opencode commit 999be62662 (v1.2.25-1672-g999be62662, 2026-08-12):
+ *   https://github.com/anomalyco/opencode/blob/999be62662/packages/opencode/src/tool/todo.ts
+ * 与 opencode 的差异：status/priority 这里用 StringEnum 做运行时校验
+ * （opencode schema 层不校验）；opencode 输出 title "N todos"，这里未设置；
+ * widget/pendant 渲染为本仓库增强（pi 特有）。
+ *
  * 完整列表替换语义（与 opencode 的 todowrite 工具一致）：
  *   每次调用用给定的 todos 数组整体替换当前任务列表。
  *   todos 数组，每项含 content / status / priority 三个字段：

package/src/opencode-write.ts

@@ -1,6 +1,13 @@
 /**
  * Enhanced Write Tool Extension
  *
+ * Aligned with opencode commit 999be62662 (v1.2.25-1672-g999be62662, 2026-08-12):
+ *   https://github.com/anomalyco/opencode/blob/999be62662/packages/opencode/src/tool/write.ts
+ * Aligned behaviours: BOM preservation (source.bom || next.bom).
+ * Known gaps (intentionally not implemented): LSP diagnostics in the result,
+ * formatter run. Unlike opencode (which has no write lock), this extension
+ * serialises writes via the mutation queue.
+ *
  * Overrides the built-in `write` tool with opencode-compatible parameter names.
  *
  * - Uses `filePath` (opencode) instead of `path` (pi built-in)
@@ -14,13 +21,37 @@
  *   cp enhanced-write.ts .pi/extensions/
  */
 
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, open, writeFile } from "node:fs/promises";
 import { dirname, resolve as resolvePath } from "node:path";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
+import { stripBom } from "./opencode-edit-engine.js";
+
+/**
+ * opencode: desiredBom = source.bom || next.bom —— 优先保留原文件 BOM，
+ * 否则用新内容自带的 BOM。
+ * @param existing - 旧文件前几个字节（undefined 表示文件不存在）
+ * @param content - 要写入的完整内容
+ */
+export function resolveBom(
+  existing: Buffer | undefined,
+  content: string,
+): { bom: string; text: string } {
+  const sourceBom =
+    existing !== undefined &&
+    existing.length >= 3 &&
+    existing[0] === 0xef &&
+    existing[1] === 0xbb &&
+    existing[2] === 0xbf
+      ? "\uFEFF"
+      : "";
+  const { bom: nextBom, text } = stripBom(content);
+  return { bom: sourceBom || nextBom, text };
+}
+
 export default function opencodeWrite(pi: ExtensionAPI) {
   pi.registerTool({
     name: "write",
@@ -46,13 +77,32 @@ export default function opencodeWrite(pi: ExtensionAPI) {
 
       return withFileMutationQueue(absolutePath, async () => {
         throwIfAborted();
+
+        // opencode: desiredBom = source.bom || next.bom —— 保留原文件 BOM，
+        // 否则用新内容自带的 BOM
+        let existing: Buffer | undefined;
+        try {
+          const fh = await open(absolutePath, "r");
+          try {
+            existing = Buffer.alloc(3);
+            const { bytesRead } = await fh.read(existing, 0, 3, 0);
+            if (bytesRead < 3) existing = undefined;
+          } finally {
+            await fh.close();
+          }
+        } catch {
+          // 文件不存在：无旧 BOM
+        }
+        throwIfAborted();
+        const { bom: desiredBom, text: nextText } = resolveBom(existing, content);
+
         await mkdir(dir, { recursive: true });
         throwIfAborted();
-        await writeFile(absolutePath, content, "utf8");
+        await writeFile(absolutePath, desiredBom + nextText, "utf8");
         throwIfAborted();
 
         return {
-          content: [{ type: "text", text: `Wrote file successfully: ${absolutePath}` }],
+          content: [{ type: "text", text: "Wrote file successfully." }],
           details: undefined,
         };
       });

package/src/question.ts

@@ -1,6 +1,11 @@
 /**
  * question —— opencode 风格的提问工具
  *
+ * Aligned with opencode commit 999be62662 (v1.2.25-1672-g999be62662, 2026-08-12):
+ *   https://github.com/anomalyco/opencode/blob/999be62662/packages/opencode/src/tool/question.ts
+ * 与 opencode 的差异：opencode 输出 title "Asked N question(s)"，这里未设置；
+ * 多选交互是平台差异（opencode 用 checkbox，这里循环 ctx.ui.select 勾选）。
+ *
  * 参数与语义和 opencode 的 `question` 工具一致：
  *   questions 数组，每项含 question / header / options / multiple：
  *   - options 每项为 label / description