@trim21/personal-pi-extensions 0.1.678 → 0.1.680

package/README.md

@@ -31,21 +31,34 @@
 
 `codemode` 让模型写一段 JavaScript（作为 async 函数体，`await` 与 `return` 都可用），在
 进程内的 worker 线程里用 QuickJS wasm VM 执行。VM 里没有 node、文件系统、网络、timer
-或模块加载，脚本唯一的出口是 `tools.<name>(args)`。
-
-- **嵌套调用经工具总线**：`tools.Read({ file_path })` 最终执行的是 `Read` 工具自己的
-  `execute`，所以工具的审批照常生效（写工作区外会弹 write-guard，Bash 沙箱外执行会弹
-  自己的提权确认）。codemode 不额外加确认层：脚本里连发十次写操作就是十次工具自己的
-  审批（需要审批的那些）。
-- **可调用集合** = 总线上实际注册的工具减去 `codemode` 自身，执行时再与当前 active
-  列表求交，所以 `personalExtensions.disabledTools`、pi 的 `defaultTools` / `--tools`、
-  子代理的工具白名单都同样约束脚本。
+或模块加载，脚本的出口只有 `call(name, args)` 与 `fs.read` / `fs.write` 两个文件原语。
+
+- **嵌套调用经工具总线**：`call("Bash", { command })` 最终执行的是 `Bash` 工具自己的
+  `execute`，所以工具的审批照常生效（Bash 沙箱外执行会弹自己的提权确认）。codemode
+  不额外加确认层：脚本里连发十次调用就是十次工具自己的审批（需要审批的那些）。
+- **可调用集合** = 总线上实际注册的工具减去排除名单（`codemode` 自身、`spawn-agent`、
+  以及两套文件工具集的 `Read`/`Edit`/`Write` 与 `read`/`edit`/`write`），执行时再与当前
+  active 列表求交，所以 `personalExtensions.disabledTools`、pi 的 `defaultTools` /
+  `--tools`、子代理的工具白名单都同样约束脚本。
+- **文件读写只有 `fs` 一条路**：`fs.read(path)` 返回文件全文的原始 UTF-8 文本（不加行号、
+  不截断、不设大小上限，只有内容不是合法 UTF-8 时报错），`fs.write(path, content)` 整体写入并自动创建
+  父目录，相对路径相对当前 cwd。`fs.write` 与写类工具共用同一套保护：写前要求「已读且读后
+  未变」（记账与文件工具共享，工具读过的文件脚本可以直接写），工作区外写入走 write-guard
+  的 diff 审批，headless / Windows / `/bwrap-deny-request` 下直接拒绝。文件读写工具本身
+  不在可调用集合里，脚本要改一行内容也走 `fs.read` + `fs.write`（行级替换用 `Edit` 工具
+  直接改，不进脚本）。
 - **只有脚本输出进上下文**：`text(value)` / `console.log(...)` 与 `return` 值进入工具结果，
   中间的工具调用与它们的返回内容不会（也不在会话记录里留下工具调用条目）。
-- **脚本接口**：`tools` / `ALL_TOOLS` / `text` / `image` / `exit` / `console.*` /
-  `store.set` / `store.get` / `store.list`（会话内持久的键值表）；首行可选
-  `// @options: {"max_output_tokens": 10000}`。
+- **返回值**：声明了 `structuredSchema` 的工具（如 gh-readonly 的读类工具）把结果放在
+  `structuredResult` 里，`call()` 解包成对象给脚本；`{ 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}`。
   脚本没有超时：死循环由调用方中止（Esc）结束，等嵌套调用返回（含用户审批弹窗）多久都不算超时。
+- **工具描述**里给出每个可调用工具的 `declare function call(name, args): Promise<T>` 重载，
+  参数与返回类型都取自工具自己的 schema，所以模型在写脚本前就知道返回值形状。
 - **store** 记在每次成功调用工具结果的 `details.store` 上（与 `src/lib/file-reads.ts` 的
   已读记账同一套做法），下一次调用从当前分支的 toolResult 重放；输出超过 `max_output_tokens`
   时头尾截断并把全文落到 `$TMPDIR/pi-codemode-*.txt`。

package/package.json

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

package/src/claude-code/files.ts

@@ -595,8 +595,14 @@ export function registerFileTools(
   // 它们由 manager 的 onEnabled 回调注册，不在这里注册。
 }
 
-/** 会更新 reads state 并随 details 持久化快照的工具名。 */
-const FILE_TOOL_NAMES = new Set(["Read", "Edit", "Write", "lsp-rename"]);
+/**
+ * 会更新 reads state 并随 details 持久化快照的工具名。
+ *
+ * 含 `codemode`：脚本的 `fs.read` / `fs.write`（src/codemode/fs.ts）与本工具集共用
+ * 同一个 ReadsState，脚本记下的已读落在 codemode 自己的工具结果里，重放分支时要一起
+ * 收回来（见 `restoreReads`）。
+ */
+const FILE_TOOL_NAMES = new Set(["Read", "Edit", "Write", "lsp-rename", "codemode"]);
 
 export interface ClaudeCodeFileToolOptions extends LspServiceOptions {
   /** 与 bash runtime 共享的非沙盒请求策略；独立入口不传，自建一份。 */
@@ -619,6 +625,8 @@ export interface FileToolset {
   register(bus: ToolBus): void;
   onLspEnabled(bus: ToolBus, service: LspService): void;
   restoreReads(ctx: ExtensionContext): void;
+  /** 与工具共用的已读记账：codemode 的 fs 原语拿它做 stale 保护（两边互通）。 */
+  readonly reads: ReadsState;
 }
 
 /**
@@ -668,6 +676,8 @@ export function createClaudeCodeFileTools(
     restoreReads(ctx) {
       restoreReads(state, ctx.sessionManager, FILE_TOOL_NAMES);
     },
+
+    reads: state,
   };
 
   // 独立入口没有注入 manager 时自建一份（入口共享的那份由入口创建）。

package/src/codemode/declarations.ts

@@ -1,9 +1,9 @@
 /**
- * 把工具的参数 schema 渲染成脚本侧的 TypeScript 声明：写进 codemode 的工具描述里，
- * 模型据此知道脚本里能写 `await tools.Read({ file_path: "..." })`。
+ * 把工具声明渲染成 codemode 脚本侧的 TypeScript：写进 codemode 的工具描述里，模型据此
+ * 知道脚本里能写 `await call("Read", { file_path: "..." })`，以及每个工具返回什么。
  *
  * 只处理本仓库工具实际用到的形状（object / array / string / number / boolean /
- * union / enum），其余退化成 `unknown`——宁可少给类型，也不要编出错类型。
+ * const / union / enum），其余退化成 `unknown`——宁可少给类型，也不要编出错类型。
  */
 
 import type { ScriptTool } from "./protocol.js";
@@ -12,6 +12,7 @@ interface ToolLike {
   name: string;
   description?: string;
   parameters?: unknown;
+  structuredSchema?: unknown;
 }
 
 type JsonSchema = Record<string, unknown>;
@@ -24,7 +25,7 @@ function literal(value: unknown): string {
   return typeof value === "string" ? JSON.stringify(value) : String(value);
 }
 
-/** 工具名作为属性访问：非法标识符用引号形式。 */
+/** 对象成员名：非法标识符用引号形式。 */
 function propertyName(name: string): string {
   return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
 }
@@ -33,6 +34,10 @@ function renderType(schema: unknown, indent: string): string {
   if (!isSchema(schema)) {
     return "unknown";
   }
+  // TypeBox 的 Type.Literal / StringEnum 产出 const，而不是 enum
+  if ("const" in schema) {
+    return literal(schema.const);
+  }
   if (Array.isArray(schema.enum) && schema.enum.length > 0) {
     return schema.enum.map((value) => literal(value)).join(" | ");
   }
@@ -76,24 +81,42 @@ function renderType(schema: unknown, indent: string): string {
   }
 }
 
-/** 单个工具在脚本里的签名（`tools` 的一个成员）。 */
-function renderToolMember(tool: ToolLike): string {
+/**
+ * 单个工具在脚本里的调用重载：`declare function call(name: "X", args: T): Promise<R>;`。
+ * 返回类型取自工具声明的输出结构，未声明就是文本（`string`）。
+ */
+function renderOverload(tool: ToolLike): string {
   const summary = tool.description?.split("\n", 1)[0]?.trim();
-  const doc = summary ? `/** ${summary} */\n  ` : "";
-  return `${doc}${propertyName(tool.name)}(args: ${renderType(tool.parameters, "  ")}): Promise<unknown>;`;
+  const doc = summary ? `/** ${summary} */\n` : "";
+  const output =
+    tool.structuredSchema === undefined ? "string" : renderType(tool.structuredSchema, "");
+  return `${doc}declare function call(name: ${JSON.stringify(tool.name)}, args: ${renderType(tool.parameters, "")}): Promise<${output}>;`;
 }
 
 /** 给脚本用的工具清单（名字 + 说明）。 */
 export function toScriptTools(tools: readonly ToolLike[]): ScriptTool[] {
-  return tools.map((tool) => ({ name: tool.name, description: tool.description }));
+  return tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    structuredSchema: tool.structuredSchema,
+  }));
 }
 
-/** 渲染脚本侧的声明：`declare const tools: {...}` 与全局辅助函数。 */
+/** 渲染脚本侧的声明：每个工具一条 `call` 重载，外加 `fs` 原语、`CallFailedError` 与全局辅助函数。 */
 export function renderDeclarations(tools: readonly ToolLike[]): string {
-  const members = tools.map((tool) => `  ${renderToolMember(tool)}`).join("\n");
   return [
-    `declare const tools: {\n${members}\n};`,
+    ...tools.map((tool) => renderOverload(tool)),
+    // 动态名字的兜底重载，必须放最后
+    "declare function call(name: string, args?: unknown): Promise<unknown>;",
     "declare const ALL_TOOLS: Array<{ name: string; description?: string }>;",
+    // 文件原语：直接读写文件。它们不是工具，所以不在上面的 call 重载里。
+    [
+      "declare const fs: {",
+      "  read(path: string): Promise<string>;",
+      "  write(path: string, content: string): Promise<void>;",
+      "};",
+    ].join("\n"),
+    'declare class CallFailedError extends Error { readonly name: "CallFailedError"; }',
     "declare function text(value: unknown): void;",
     "declare function image(value: unknown): void;",
     "declare function exit(): void;",

package/src/codemode/fs.ts

@@ -0,0 +1,138 @@
+/**
+ * codemode 的文件原语（`fs.read` / `fs.write`）：宿主用 `node:fs/promises` 直接读写，
+ * 不走工具总线——它们不是工具，不出现在工具列表里，也不参与工具开关与 active 工具求交。
+ *
+ * 两条保护与文件工具完全一致，而且共用同一份状态：
+ * - stale 保护：写入前要求目标文件「已读且读后未变」（`file-reads.ts` 的
+ *   `requireCurrentRead`），文件不存在时允许直接创建；读与写都记账，因此工具读过的
+ *   文件脚本可以直接写，反之亦然。
+ * - 审批：写入经 write-guard（工作区内与 `/tmp` 放行，区外弹 diff 审批，headless /
+ *   Windows / 请求策略下直接拒绝）。
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import {
+  type FileSnapshot,
+  type ReadsState,
+  recordRead,
+  requireCurrentRead,
+  snapshotOf,
+} from "../lib/file-reads.js";
+import { parseWithSchema } from "../lib/parse-with-schema.js";
+import type { RequestPolicy } from "../lib/request-policy.js";
+import { guardWriteAccess } from "../lib/write-guard.js";
+
+const readArgsSchema = Type.Object({ path: Type.String() });
+const writeArgsSchema = Type.Object({ path: Type.String(), content: Type.String() });
+
+const FS_READ = "fs.read";
+const FS_WRITE = "fs.write";
+
+export interface FsCallContext {
+  ctx: ExtensionContext;
+  signal?: AbortSignal;
+}
+
+/** 一次 fs 原语的结果：`value` 回给脚本，`reads` 是本次新增的已读记账（进 details.reads）。 */
+export interface FsCallResult {
+  value?: unknown;
+  reads?: Record<string, FileSnapshot>;
+}
+
+export interface CodemodeFs {
+  /** 该名字是否归 fs 原语（`fs.read` / `fs.write`）。 */
+  handles(name: string): boolean;
+  /** 执行一次 fs 原语；失败抛错，由调用方转成脚本侧的错误。 */
+  execute(name: string, args: unknown, call: FsCallContext): Promise<FsCallResult>;
+}
+
+export interface CodemodeFsOptions {
+  /** 与写类工具共享的请求策略：`/bwrap-deny-request` 生效时工作区外写入直接拒绝。 */
+  policy: RequestPolicy;
+  /** 与文件工具共享的已读记账。 */
+  reads: ReadsState;
+}
+
+/**
+ * 解码 UTF-8：`ignoreBOM: true` 表示不特殊处理 BOM（即保留它），这样内容与磁盘字节
+ * 一一对应——记账指纹与审批预览都是按原始字节比对的，丢掉 BOM 会让两者对不上。
+ */
+function decodeUtf8(buffer: Uint8Array, path: string): string {
+  try {
+    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(buffer);
+  } catch {
+    throw new Error(
+      `Cannot read "${path}" as UTF-8 text: the file is not valid UTF-8 (binary files are not supported).`,
+    );
+  }
+}
+
+/** 读文件；不存在时返回 undefined（新建文件免已读），其余错误照常抛出。 */
+async function readIfExists(path: string, signal?: AbortSignal): Promise<Buffer | undefined> {
+  try {
+    return await readFile(path, { signal });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+export function createCodemodeFs(options: CodemodeFsOptions): CodemodeFs {
+  const { policy, reads } = options;
+
+  async function read(args: unknown, call: FsCallContext): Promise<FsCallResult> {
+    const { path } = parseWithSchema(readArgsSchema, args);
+    const absolutePath = resolve(call.ctx.cwd, path);
+    // 不设大小上限：内容不进模型上下文，放不下时（VM 堆不够）会以错误回到脚本里
+    const buffer = await readFile(absolutePath, { signal: call.signal });
+    const text = decodeUtf8(buffer, absolutePath);
+    // 指纹按磁盘字节算：与文件工具共用记账，两侧的 digest 必须能互相对上
+    const recorded = await recordRead(reads, absolutePath, snapshotOf(buffer));
+    return { value: text, reads: recorded };
+  }
+
+  async function write(args: unknown, call: FsCallContext): Promise<FsCallResult> {
+    const { path, content } = parseWithSchema(writeArgsSchema, args);
+    const absolutePath = resolve(call.ctx.cwd, path);
+    const existing = await readIfExists(absolutePath, call.signal);
+    if (existing !== undefined) {
+      await requireCurrentRead(reads, absolutePath, existing);
+    }
+    await guardWriteAccess(call.ctx, {
+      toolName: FS_WRITE,
+      absolutePath,
+      mutation: {
+        contentOld: existing === undefined ? "" : decodeUtf8(existing, absolutePath),
+        contentNew: content,
+      },
+      policy,
+      signal: call.signal,
+    });
+    await mkdir(dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, content, { encoding: "utf8", signal: call.signal });
+    const recorded = await recordRead(reads, absolutePath, snapshotOf(content));
+    return { reads: recorded };
+  }
+
+  return {
+    handles(name) {
+      return name === FS_READ || name === FS_WRITE;
+    },
+    async execute(name, args, call) {
+      if (name === FS_READ) {
+        return await read(args, call);
+      }
+      if (name === FS_WRITE) {
+        return await write(args, call);
+      }
+      throw new Error(`Unknown fs operation "${name}".`);
+    },
+  };
+}

package/src/codemode/prelude.ts

@@ -1,14 +1,16 @@
 /**
  * codemode 脚本侧的 prelude：在 QuickJS VM 里先于脚本求值，构建脚本能看到的全部
- * 能力（`tools` / `ALL_TOOLS` / `text` / `image` / `exit` / `console` / `store`），
- * 并把宿主桥接封在闭包里——脚本拿不到 `bridge` 本身。
+ * 能力（`call` / `CallFailedError` / `ALL_TOOLS` / `fs` / `text` / `image` / `exit` /
+ * `console` / `store`），并把宿主桥接封在闭包里——脚本拿不到 `bridge` 本身。
  *
  * 值与参数过桥时都是 JSON 文本，本侧负责 parse/stringify；异步调用用一个 pending
- * 表把 id 映射到 promise，由宿主在结果到达时 settle。
+ * 表把 id 映射到 promise，由宿主在结果到达时 settle。每次调用失败（工具或 fs 原语）
+ * 都由宿主以 `ok: false` 回报，本侧统一 reject 成 `CallFailedError`（脚本可以按
+ * instanceof 区分「调用失败」与自己的运行期错误）。
  *
  * 求值结果是一个函数 `(bridge, toolsJson, storeJson) => { settle, run, stalled }`。
  * `bridge(kind, a, b, c)`：
- * - `"call"`（id, name, argsJson）
+ * - `"call"`（id, name, argsJson）：工具，以及名字为 `fs.read` / `fs.write` 的 fs 原语
  * - `"output"`（"text", text）/（"image", data, mimeType）
  * - `"done"`（ok, valueJsonOrErrorJson, writesJson）
  */
@@ -28,6 +30,13 @@ export const PRELUDE_SOURCE = String.raw`(function (bridge, toolsJson, storeJson
 	const promiseThen = Promise.prototype.then;
 	const ErrorCtor = Error;
 	const TypeErrorCtor = TypeError;
+	// 嵌套调用失败统一用它 reject：脚本能按 instanceof 区分「工具失败」与自身运行期错误
+	class CallFailedError extends ErrorCtor {
+		constructor(message) {
+			super(message);
+			this.name = "CallFailedError";
+		}
+	}
 	const pending = new Map();
 	let nextId = 1;
 	let finished = false;
@@ -89,20 +98,36 @@ export const PRELUDE_SOURCE = String.raw`(function (bridge, toolsJson, storeJson
 			});
 	}
 
-	const tools = Object.create(null);
+	const callers = new Map();
 	const allTools = [];
-	for (const { name, jsName, description } of parse(toolsJson)) {
-		const fn = caller(name);
-		// 两个名字归一化成同一个标识符时，第一个赢
-		if (!(jsName in tools)) {
-			tools[jsName] = fn;
-			allTools.push(Object.freeze({ name: jsName, description }));
-		}
-		if (!(name in tools)) tools[name] = fn;
+	for (const { name, description } of parse(toolsJson)) {
+		if (callers.has(name)) continue;
+		callers.set(name, caller(name));
+		allTools.push(Object.freeze({ name, description }));
 	}
-	Object.freeze(tools);
 	Object.freeze(allTools);
 
+	function call(name, args) {
+		const fn = callers.get(name);
+		if (fn === undefined) {
+			return Promise.reject(
+				new CallFailedError('Tool "' + String(name) + '" is not available in codemode.'),
+			);
+		}
+		return fn(args);
+	}
+	Object.freeze(call);
+
+	// 脚本的文件原语：与工具走同一条桥，但它们是内建能力而不是工具——不进 ALL_TOOLS，
+	// 也不出现在工具描述的工具重载里（声明单独渲染），写审批与已读记账由宿主负责。
+	// 脚本侧是 Node 风格的位置参数，过桥仍是一个可校验的对象。
+	const readFile = caller("fs.read");
+	const writeFile = caller("fs.write");
+	const fs = Object.freeze({
+		read: (path) => readFile({ path }),
+		write: (path, content) => writeFile({ path, content }),
+	});
+
 	// key -> JSON 文本；容量按 key 与 JSON 的字符数计
 	const stored = new Map();
 	const writes = new Map();
@@ -242,8 +267,10 @@ export const PRELUDE_SOURCE = String.raw`(function (bridge, toolsJson, storeJson
 	}
 	Object.freeze(console);
 
-	Object.defineProperty(globalThis, "tools", { value: tools, enumerable: true });
+	Object.defineProperty(globalThis, "call", { value: call, enumerable: true });
+	Object.defineProperty(globalThis, "CallFailedError", { value: CallFailedError, enumerable: true });
 	Object.defineProperty(globalThis, "ALL_TOOLS", { value: allTools, enumerable: true });
+	Object.defineProperty(globalThis, "fs", { value: fs, enumerable: true });
 	Object.defineProperty(globalThis, "console", { value: console, enumerable: true });
 	Object.defineProperty(globalThis, "text", { value: text, enumerable: true });
 	Object.defineProperty(globalThis, "image", { value: image, enumerable: true });
@@ -255,7 +282,7 @@ export const PRELUDE_SOURCE = String.raw`(function (bridge, toolsJson, storeJson
 			if (!entry) return;
 			pending.delete(id);
 			if (!ok) {
-				entry.reject(new ErrorCtor(payload));
+				entry.reject(new CallFailedError(payload));
 				return;
 			}
 			let value;
@@ -270,7 +297,7 @@ export const PRELUDE_SOURCE = String.raw`(function (bridge, toolsJson, storeJson
 		run(fn) {
 			let promise;
 			try {
-				promise = fn(tools, console);
+				promise = fn();
 			} catch (error) {
 				done(false, describeError(error));
 				return;

package/src/codemode/protocol.ts

@@ -13,6 +13,18 @@
 import { type TSchema, Type } from "typebox";
 import { Value } from "typebox/value";
 
+// ── 资源上限 ─────────────────────────────────────────────────────────────────
+
+/**
+ * QuickJS VM 的堆上限。它不是预留（创建 VM 只占几 MiB，按脚本实际分配增长），而是
+ * 「超量分配变成脚本里可捕获的 InternalError，而不是拖垮宿主」的那条线。
+ *
+ * 文件读取没有单独的上限：读进来的内容不进模型上下文，所以不需要按上下文预算裁剪；
+ * 真正放不下时（VM 堆不够、或超出宿主字符串/缓冲上限）会以错误回到脚本里，让它自己
+ * 决定怎么办。
+ */
+export const MEMORY_LIMIT_BYTES = 2 * 1024 ** 3;
+
 // ── 消息 schema ──────────────────────────────────────────────────────────────
 
 const outputItemSchema = Type.Union([
@@ -23,6 +35,8 @@ const outputItemSchema = Type.Union([
 const toolDeclSchema = Type.Object({
   name: Type.String(),
   description: Type.Optional(Type.String()),
+  /** 工具的 structuredSchema（TypeBox schema）：脚本侧据此渲染 call() 的返回类型。 */
+  structuredSchema: Type.Optional(Type.Unknown()),
 });
 
 const startSchema = Type.Object({
@@ -54,7 +68,7 @@ const callSchema = Type.Object({
   args: Type.Unknown(),
 });
 
-const outputSchema = Type.Object({
+const outputFrameSchema = Type.Object({
   t: Type.Literal("output"),
   items: Type.Array(outputItemSchema),
 });
@@ -87,7 +101,7 @@ const doneSchema = Type.Union([
 ]);
 
 const hostMessageSchema = Type.Union([startSchema, resultSchema]);
-const workerMessageSchema = Type.Union([callSchema, outputSchema, doneSchema]);
+const workerMessageSchema = Type.Union([callSchema, outputFrameSchema, doneSchema]);
 
 /** worker 启动数据：注册时编译好的 wasm 模块（结构化克隆可以带它跨线程）。 */
 export interface WorkerBootstrap {
@@ -117,6 +131,7 @@ export interface StoreWrites {
 export interface ScriptTool {
   name: string;
   description?: string;
+  structuredSchema?: unknown;
 }
 
 export type HostMessage =

package/src/codemode/tool.ts

@@ -1,11 +1,12 @@
 /**
- * codemode 工具：模型写一段 JavaScript，脚本在 QuickJS VM（worker 线程）里执行，脚本唯一
- * 的能力是调用 `tools.*`——每个嵌套调用都由主线程经本仓库的工具总线执行，因此工具实现
- * 内部的审批（工作区外写入、Bash 沙箱提权等）照常生效；codemode 不再加自己的确认层。
+ * codemode 工具：模型写一段 JavaScript，脚本在 QuickJS VM（worker 线程）里执行，脚本的
+ * 能力有两条：`call(name, args)` 调用工具（每个嵌套调用都由主线程经本仓库的工具总线执行，
+ * 因此工具实现内部的审批——工作区外写入、Bash 沙箱提权等——照常生效；codemode 不再加
+ * 自己的确认层），以及 `fs.read` / `fs.write` 两个文件原语（同样由主线程执行，与文件工具
+ * 共用写审批与已读记账，见 fs.ts）。
  *
- * 可调用集合：总线上实际注册的工具减去 codemode 自身与 spawn-agent，执行时再与 active
+ * 可调用集合：总线上实际注册的工具减去 `EXCLUDED_TOOL_NAMES`，执行时再与 active
  * 列表求交——pi 自己的 `defaultTools` / `--tools` / 子代理白名单的排除因此同样生效。
- * spawn-agent 被排除是因为它启动一个新的隔离会话、成本与运行时长都不适合放进脚本编排。
  *
  * wasm 在注册这个工具时编译一次（`createCodemodeSandbox`），worker 复用编译结果。
  */
@@ -18,33 +19,59 @@ import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
+import type { FileSnapshot, ReadsState } from "../lib/file-reads.js";
 import type { ToolPendant } from "../lib/pendant.js";
+import type { RequestPolicy } from "../lib/request-policy.js";
 import { type ToolBus, toolResultText } from "../lib/tool-bus.js";
 import { renderDeclarations, toScriptTools } from "./declarations.js";
+import { createCodemodeFs } from "./fs.js";
 import type { CodemodeOutputItem, ScriptError, StoreWrites } from "./protocol.js";
 import { type CodemodeSandbox, createCodemodeSandbox, type ScriptCall } from "./sandbox.js";
 import { CODEMODE_SOURCE_GRAMMAR, DEFAULT_OUTPUT_TOKENS, parseCodemodeSource } from "./source.js";
 
 export const CODEMODE_TOOL_NAME = "codemode";
 
-/** 不暴露给脚本的工具：codemode 自身（防递归）与 spawn-agent（见文件头注释）。 */
-const EXCLUDED_TOOL_NAMES: ReadonlySet<string> = new Set([CODEMODE_TOOL_NAME, "spawn-agent"]);
+/**
+ * 不暴露给脚本的工具：
+ * - codemode 自身（防递归）；
+ * - spawn-agent：它启动一个新的隔离会话，成本与运行时长都不适合放进脚本编排；
+ * - 两套文件工具集的读写工具：脚本用 `fs.read` / `fs.write`（原文、不截断、按路径整体
+ *   写入），不重复给一套为 LLM 上下文设计的行号/锚点语义。
+ */
+const EXCLUDED_TOOL_NAMES: ReadonlySet<string> = new Set([
+  CODEMODE_TOOL_NAME,
+  "spawn-agent",
+  "Read",
+  "Edit",
+  "Write",
+  "read",
+  "edit",
+  "write",
+]);
 
 /** 估计 token 用的字符数（与 pi 一致）。 */
 const CHARS_PER_TOKEN = 4;
 
+export interface CodemodeToolDeps {
+  /** 与写类工具共享的非沙盒请求策略（写审批要用）。 */
+  policy: RequestPolicy;
+  /** 与文件工具共享的已读记账：脚本的 fs 原语据此做 stale 保护（两边互通）。 */
+  reads: ReadsState;
+}
+
 export interface CodemodeTools {
   /**
    * 注册 codemode 工具。注册时编译 quickjs.wasm（编译失败则注册失败，由入口记成
    * 警告），之后每次执行复用同一份编译结果。
    */
-  register(bus: ToolBus): Promise<void>;
+  register(bus: ToolBus, deps: CodemodeToolDeps): Promise<void>;
 }
 
 interface CallableTool {
   name: string;
   description?: string;
   parameters?: unknown;
+  structuredSchema?: unknown;
 }
 
 /** 只在 pi 有 active 工具概念时才求交（子代理、`--tools` 等场景）。 */
@@ -66,6 +93,7 @@ function collectTools(bus: ToolBus, allowed: Set<string> | undefined): CallableT
       name: definition.name,
       description: definition.description,
       parameters: definition.parameters,
+      structuredSchema: definition.structuredSchema,
     }));
 }
 
@@ -73,8 +101,8 @@ function buildDescription(tools: readonly CallableTool[]): string {
   return [
     "Run JavaScript code that orchestrates tool calls in a QuickJS sandbox.",
     "- The code is the body of an async function: top-level `await` and `return` both work.",
-    "- Call tools with `await tools.<name>(args)`. Arguments and results make a JSON round trip,",
-    "  and a failing tool rejects with an `Error` you can catch.",
+    "- Call tools with `await call(name, args)`. Arguments and results make a JSON round trip,",
+    "  and a failing tool rejects with a `CallFailedError` you can catch.",
     "- Only what the script passes to `text(value)` / `console.log(...)` and its `return` value enter",
     "  this conversation; nested calls and their results stay out of it.",
     "- `store.set(key, value)`, `store.get(key)` and `store.list()` are a small key/value store that",
@@ -124,6 +152,11 @@ function readStore(ctx: ExtensionContext): Record<string, unknown> {
   return Object.fromEntries(store);
 }
 
+/** 本次脚本有没有通过 fs 读写过文件（决定 details 里要不要带 reads 记账）。 */
+function hasReads(reads: Record<string, FileSnapshot>): boolean {
+  return Object.keys(reads).length > 0;
+}
+
 function errorText(error: ScriptError): string {
   const head = error.name ? `${error.name}: ${error.message}` : error.message;
   return `${head}${error.stack && error.stack !== head ? `\n${error.stack}` : ""}`;
@@ -222,8 +255,9 @@ function formatCallSummary(calls: readonly ScriptCall[]): string {
 
 export function createCodemodeTools(pi: ExtensionAPI): CodemodeTools {
   return {
-    async register(bus) {
+    async register(bus, deps) {
       const sandbox: CodemodeSandbox = await createCodemodeSandbox();
+      const fs = createCodemodeFs(deps);
       const tools = collectTools(bus, allowedToolNames(pi));
       const callable = new Set(tools.map((tool) => tool.name));
       const scriptTools = toScriptTools(tools);
@@ -267,6 +301,9 @@ export function createCodemodeTools(pi: ExtensionAPI): CodemodeTools {
             };
           }
 
+          // 脚本的 fs 原语读到的文件也进同一份记账，随结果持久化（与 details.store 同一处）
+          const recordedReads: Record<string, FileSnapshot> = {};
+
           const outcome = await sandbox.run({
             code,
             tools: scriptTools,
@@ -293,10 +330,29 @@ export function createCodemodeTools(pi: ExtensionAPI): CodemodeTools {
               });
             },
             onCall: async ({ name, args }) => {
+              if (fs.handles(name)) {
+                try {
+                  const result = await fs.execute(name, args, { ctx, signal });
+                  if (result.reads !== undefined) {
+                    Object.assign(recordedReads, result.reads);
+                  }
+                  return { ok: true, value: result.value };
+                } catch (error) {
+                  return {
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                  };
+                }
+              }
               if (!callable.has(name)) {
                 return { ok: false, error: `Tool "${name}" is not available in codemode.` };
               }
               const result = await bus.executeTool(name, args, { ctx, signal });
+              if (result.structuredResult) {
+                return result.structuredResult.ok
+                  ? { ok: true, value: result.structuredResult.value }
+                  : { ok: false, error: result.structuredResult.error };
+              }
               const text = toolResultText(result);
               if (result.isError) {
                 return { ok: false, error: text };
@@ -329,6 +385,7 @@ export function createCodemodeTools(pi: ExtensionAPI): CodemodeTools {
                 calls: outcome.calls,
                 // store 的写入随工具结果持久化，下一次调用从这里重放恢复
                 ...(hasWrites && { store: writes }),
+                ...(hasReads(recordedReads) && { reads: recordedReads }),
                 pendant: scriptPendant(code, `${outcome.calls.length} tool call(s)`),
                 ...(truncated.fullOutputPath && { fullOutputPath: truncated.fullOutputPath }),
               },
@@ -349,6 +406,7 @@ export function createCodemodeTools(pi: ExtensionAPI): CodemodeTools {
             details: {
               calls: outcome.calls,
               error: outcome.error.kind,
+              ...(hasReads(recordedReads) && { reads: recordedReads }),
               pendant: scriptPendant(code, `failed (${outcome.error.kind})`),
             },
           };