@trim21/personal-pi-extensions 0.1.20261012023047 → 0.1.20261012031237

package/README.md

@@ -35,8 +35,9 @@
 `sleep`。
 
 - **嵌套调用经工具总线**：`call("Bash", { command })` 最终执行的是 `Bash` 工具自己的
-  `execute`，所以工具的审批照常生效（Bash 沙箱外执行会弹自己的提权确认）。codemode
-  不额外加确认层：脚本里连发十次调用就是十次工具自己的审批（需要审批的那些）。
+  `execute`。**脚本里不弹审批**：需要人工授权的调用（写工作区外、Bash 申请沙箱外执行）
+  在 codemode 内直接以 `CallFailedError` 失败，错误信息提示改用直调；模型直调同一个工具时
+  审批照常出现。此外 codemode 不额外加确认层：不需要审批的调用不会多出任何确认框。
 - **可调用集合 = 声明了结构化输出的工具**（有 `structuredSchema` 的才进），执行时再与当前
   active 列表求交，所以 `personalExtensions.disabledTools`、pi 的 `defaultTools` /
   `--tools`、子代理的工具白名单都同样约束脚本。脚本拿到的返回值必须有确定的形状，因此没给
@@ -62,10 +63,14 @@
   结构的工具不进集合，`call()` 会报「not available in codemode」。
 - **脚本接口**：`call` / `CallFailedError` / `ALL_TOOLS` / `fs.read` / `fs.write` /
   `text` / `image` / `exit` / `sleep` / `console.*` / `store.set` / `store.get` / `store.list`
-  （会话内持久的键值表）；首行可选 `// @options: {"max_output_tokens": 10000}`。
-  脚本没有超时：死循环由调用方中止（Esc）结束，等嵌套调用返回（含用户审批弹窗）多久都不算超时。
+  （会话内持久的键值表）；首行可选
+  `// @options: {"max_output_tokens": 10000, "timeout_ms": 600000}`——选项留在脚本里而不是工具参数，
+  因为 pi 的 grammar 约束（`constrainedSampling`）只支持单个自由文本参数，多出来的参数在支持
+  grammar 的模型上会被静默忽略。不声明 `timeout_ms` 时脚本没有时间上限：死循环由调用方中止（Esc）
+  结束，等嵌套调用返回（含慢命令）多久都不算超时。声明了 `timeout_ms` 就有墙钟预算（含等待嵌套
+  调用的时间），到点时正在跑的调用被中止、结果以超时结束，已产生的输出与调用记录仍然返回。
   `await sleep(seconds)`（秒，可为小数）是脚本唯一的等待手段，由 worker 线程自己的定时器驱动
-  （不经主线程、不产生进度帧），也没有上限——要等多久由脚本决定，不想等就中止。
+  （不经主线程、不产生进度帧），它自己也没有上限——但会被 `timeout_ms` 结束。
 - **工具描述**里给出每个可调用工具的 `declare function call(name, args): Promise<T>` 重载，
   参数与返回类型都取自工具自己的 schema，所以模型在写脚本前就知道返回值形状。
 - **store** 记在每次成功调用工具结果的 `details.store` 上（与 `src/lib/file-reads.ts` 的

package/package.json

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

package/src/bwrap/runtime.ts

@@ -86,6 +86,8 @@ export interface BwrapExecutionRequest {
   signal?: AbortSignal;
   onUpdate?: AgentToolUpdateCallback;
   ctx: ExtensionContext;
+  /** 本次调用不可请求用户审批（codemode 的嵌套调用）：提权请求直接失败，不弹框。 */
+  unapprovable?: boolean;
 }
 
 /**
@@ -333,6 +335,13 @@ function describeLimits(resolved: ResolvedBwrap): string {
  */
 const UNSANDBOXED_DENIED = "User denied unsandboxed execution.";
 
+/**
+ * codemode 内的提权请求：脚本里弹不了审批框（那次工具调用只经 codemode 暴露），
+ * 因此直接拒绝，并让模型知道改用直调就能走正常审批。
+ */
+const UNSANDBOXED_DENIED_IN_CODEMODE =
+  "Unsandboxed execution needs user approval, which codemode cannot ask for. Call Bash directly instead of from a script.";
+
 /** 命令没经沙箱时沿用 prompt 里的说法，给出在沙盒外重跑的手段。 */
 const SANDBOX_ESCAPE_HATCH =
   "If the command needs more than that, use the `dangerouslyDisableSandbox` parameter to request unsandboxed execution; the user must approve this request.";
@@ -571,6 +580,7 @@ export class BwrapRuntime {
             request.description,
             execCwd,
             ruleSet,
+            request.unapprovable === true,
           )) === "sandbox";
       }
     }
@@ -706,11 +716,16 @@ export class BwrapRuntime {
     reason: string | undefined,
     execCwd: string,
     ruleSet: ApprovalRuleSet,
+    unapprovable: boolean,
   ): Promise<FullAccessGrant> {
     // hasUI 判定推迟到审批时刻：无 UI 会话弹不了审批框，按用户点 Deny 的标准文案拒绝
     if (!ctx.hasUI) {
       throw new Error(UNSANDBOXED_DENIED);
     }
+    // codemode 内一律不弹审批：提权请求直接失败，并提示改用直调
+    if (unapprovable) {
+      throw new Error(UNSANDBOXED_DENIED_IN_CODEMODE);
+    }
     const decision = await this.approveFullAccessUI(ctx, command, reason, execCwd, ruleSet);
     // 关闭对话框 = 中断并拒绝，不循环重问
     if (decision === undefined) {

package/src/claude-code/shell.ts

@@ -127,7 +127,7 @@ export function registerShellTools(bus: ToolBus, pi: ExtensionAPI, runtime: Bwra
         },
         { additionalProperties: false },
       ),
-      async execute(id, params, signal, onUpdate, ctx) {
+      async execute(id, params, signal, onUpdate, ctx, callOptions) {
         const timeout = params.timeout ?? BASH_DEFAULT_TIMEOUT_MS;
         if (!Number.isFinite(timeout) || timeout <= 0 || timeout > BASH_MAX_TIMEOUT_MS) {
           throw new Error(`timeout must be between 1 and ${BASH_MAX_TIMEOUT_MS} milliseconds`);
@@ -147,6 +147,7 @@ export function registerShellTools(bus: ToolBus, pi: ExtensionAPI, runtime: Bwra
             description: params.description,
             signal,
             onUpdate,
+            unapprovable: callOptions?.unapprovable,
           });
         } catch (error) {
           if (!(error instanceof Error)) {

package/src/codemode/fs.ts

@@ -36,6 +36,8 @@ const FS_WRITE = "fs.write";
 export interface FsCallContext {
   ctx: ExtensionContext;
   signal?: AbortSignal;
+  /** 本次调用不可请求用户审批（脚本里弹不了框）：区外写入直接失败。 */
+  unapprovable?: boolean;
 }
 
 /** 一次 fs 原语的结果：`value` 回给脚本，`reads` 是本次新增的已读记账（进 details.reads）。 */
@@ -114,6 +116,7 @@ export function createCodemodeFs(options: CodemodeFsOptions): CodemodeFs {
       },
       policy,
       signal: call.signal,
+      unapprovable: call.unapprovable,
     });
     await mkdir(dirname(absolutePath), { recursive: true });
     await writeFile(absolutePath, content, { encoding: "utf8", signal: call.signal });

package/src/codemode/prelude.ts

@@ -351,7 +351,7 @@ export const PRELUDE_SOURCE = String.raw`(function (bridge, toolsJson, storeJson
 				stringify({
 					name: "Error",
 					message:
-						"The script is waiting on a promise that can never settle: no tool call is pending, and timers do not exist here.",
+						"The script is waiting on a promise that can never settle: no tool call and no sleep is pending.",
 				}),
 			);
 			return true;

package/src/codemode/protocol.ts

@@ -84,7 +84,7 @@ export interface WorkerBootstrap {
 export type CodemodeOutputItem =
   { type: "text"; text: string } | { type: "image"; data: string; mimeType: string };
 
-export type ScriptErrorKind = "script" | "aborted" | "sandbox";
+export type ScriptErrorKind = "script" | "aborted" | "timeout" | "sandbox";
 
 export interface ScriptError {
   kind: ScriptErrorKind;

package/src/codemode/sandbox.ts

@@ -52,8 +52,18 @@ export interface SandboxRunOptions {
   toolCallId: string;
   /** 调用方中止本次执行；脚本没有自己的超时，死循环只能靠它结束。 */
   signal?: AbortSignal;
-  /** 每次嵌套调用：由调用方执行工具并把结果回给脚本。 */
-  onCall(request: { id: number; name: string; args: unknown }): Promise<SandboxCallOutcome>;
+  /**
+   * 本次执行的墙钟预算（毫秒），含等待嵌套调用的时间；缺省不设上限。
+   * 到点后执行以 `kind: "timeout"` 结束，正在跑的嵌套调用收到中止信号。
+   */
+  timeoutMs?: number;
+  /** 每次嵌套调用：由调用方执行工具并把结果回给脚本。`signal` 含调用方中止与本次预算。 */
+  onCall(request: {
+    id: number;
+    name: string;
+    args: unknown;
+    signal: AbortSignal;
+  }): Promise<SandboxCallOutcome>;
   /** 脚本流式产生的输出项，用于 toolcall 进度。 */
   onOutput?(items: readonly CodemodeOutputItem[]): void;
   /** 嵌套调用的开始与结束，用于 toolcall 进度；事件里带截至此刻的调用记录快照。 */
@@ -108,6 +118,15 @@ function runInWorker(wasm: object, options: SandboxRunOptions): Promise<SandboxO
     const started = new Map<number, { name: string; at: number }>();
     let callSequence = 0;
     let settled = false;
+    let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
+
+    // 超时与调用方中止合成一条信号，交给嵌套调用：预算到点时正在跑的工具也要停，
+    // 否则 terminate 只杀 worker，工具会在主线程继续跑完并留下副作用
+    const aborter = new AbortController();
+    const signal =
+      options.signal === undefined
+        ? aborter.signal
+        : AbortSignal.any([options.signal, aborter.signal]);
 
     // 进度帧发出去的是拷贝：记录随后会被改成终态，已经发出去的帧不能被它改掉
     const snapshotCalls = (): ScriptCall[] => calls.map((call) => ({ ...call }));
@@ -121,6 +140,7 @@ function runInWorker(wasm: object, options: SandboxRunOptions): Promise<SandboxO
         return;
       }
       settled = true;
+      clearTimeout(timeoutTimer);
       void worker.terminate();
       resolve({ ...body, output, calls });
     };
@@ -143,6 +163,15 @@ function runInWorker(wasm: object, options: SandboxRunOptions): Promise<SandboxO
       );
     }
 
+    if (options.timeoutMs !== undefined) {
+      const timeoutMs = options.timeoutMs;
+      timeoutTimer = setTimeout(() => {
+        // 先中止正在跑的嵌套调用，再定结果：terminate 不会自动停主线程里的工具
+        aborter.abort();
+        fail(`Execution timed out after ${timeoutMs} ms`, "timeout");
+      }, timeoutMs);
+    }
+
     const handleCall = async (id: number, name: string, args: unknown): Promise<void> => {
       callSequence += 1;
       const record: ScriptCall = {
@@ -157,7 +186,7 @@ function runInWorker(wasm: object, options: SandboxRunOptions): Promise<SandboxO
       options.onCallProgress?.({ phase: "start", name, args, calls: snapshotCalls() });
       let outcome: SandboxCallOutcome;
       try {
-        outcome = await options.onCall({ id, name, args });
+        outcome = await options.onCall({ id, name, args, signal });
       } catch (error) {
         outcome = { ok: false, error: error instanceof Error ? error.message : String(error) };
       }

package/src/codemode/source.ts

@@ -1,12 +1,15 @@
 /**
- * codemode 脚本源码的解析：首行可选的 `// @options: {"max_output_tokens":…}`。
+ * codemode 脚本源码的解析：首行可选的 `// @options: {"max_output_tokens":…, "timeout_ms":…}`。
  *
  * 选项行与脚本首行共用一行，解析后原样保留为空行，脚本里报错的行号因此与用户写的
  * 一致。解析失败（空输入、JSON 非法、未知字段、只有选项行没有代码）直接报错。
  */
 
 const OPTIONS_PREFIX = "// @options:";
-const SUPPORTED_FIELDS = ["max_output_tokens"] as const;
+const SUPPORTED_FIELDS = ["max_output_tokens", "timeout_ms"] as const;
+
+/** `timeout_ms` 的上限：`setTimeout` 能接受的最大延时（毫秒）。 */
+const MAX_TIMEOUT_MS = 2_147_483_647;
 
 export const DEFAULT_OUTPUT_TOKENS = 10_000;
 
@@ -19,6 +22,8 @@ export class CodemodeSourceError extends Error {
 
 export interface CodemodeSourceOptions {
   maxOutputTokens: number;
+  /** 本次执行的墙钟预算（毫秒）。不声明时脚本没有时间上限。 */
+  timeoutMs: number;
 }
 
 export interface ParsedCodemodeSource {
@@ -45,6 +50,20 @@ function parseOptions(json: string): Partial<CodemodeSourceOptions> {
         `${OPTIONS_PREFIX} does not support ${JSON.stringify(key)}; supported fields are ${SUPPORTED_FIELDS.map((field) => `\`${field}\``).join(" and ")}`,
       );
     }
+    if (key === "timeout_ms") {
+      if (
+        typeof value !== "number" ||
+        !Number.isSafeInteger(value) ||
+        value <= 0 ||
+        value > MAX_TIMEOUT_MS
+      ) {
+        throw new CodemodeSourceError(
+          `${OPTIONS_PREFIX} \`timeout_ms\` must be a positive integer up to ${MAX_TIMEOUT_MS}`,
+        );
+      }
+      options.timeoutMs = value;
+      continue;
+    }
     if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
       throw new CodemodeSourceError(`${OPTIONS_PREFIX} ${key} must be a positive number`);
     }

package/src/codemode/tool.ts

@@ -115,6 +115,10 @@ function buildDescription(tools: readonly CallableTool[]): string {
     "  return: urls, ids and metadata you will not use cost context and buy nothing.",
     "- `await sleep(seconds)` waits that many seconds (fractions allowed). It is the only way to",
     '  wait: the sandbox has no timers, and it beats `call("Bash", { command: "sleep 1" })`.',
+    "- Nested calls cannot ask for user approval: a call that would need it (writing outside the",
+    "  workspace, unsandboxed Bash) fails. Make those calls directly instead of from a script.",
+    '- `// @options: {"timeout_ms": N}` bounds the whole run in milliseconds; without it the script',
+    "  has no time limit beyond the user aborting it.",
     "- `store.set(key, value)`, `store.get(key)` and `store.list()` are a small key/value store that",
     "  persists across codemode calls in this session; `store.set(key, undefined)` removes a key.",
     "- The sandbox has no file system, network, timers or Node APIs: calling tools is its only",
@@ -294,9 +298,12 @@ export function createCodemodeTools(pi: ExtensionAPI): CodemodeTools {
         parameters: Type.Object({
           code: Type.String({
             description:
-              'Raw JavaScript source. Top-level await and return work. May start with a `// @options: {"max_output_tokens": 10000}` line.',
+              'Raw JavaScript source. Top-level await and return work. May start with a `// @options: {"max_output_tokens": 10000, "timeout_ms": 600000}` line.',
           }),
         }),
+        // 采样约束与 pi 内置 codemode 同形：grammar 只能约束一个自由文本参数，所以
+        // options 只能待在脚本里（多参数会让这个工具在支持 grammar 的模型上退化成
+        // 单字段 custom tool，额外参数被静默忽略）
         constrainedSampling: {
           type: "grammar",
           variants: { openai_lark: CODEMODE_SOURCE_GRAMMAR },
@@ -306,10 +313,12 @@ export function createCodemodeTools(pi: ExtensionAPI): CodemodeTools {
         async execute(toolCallId, params, signal, onUpdate, ctx) {
           let code: string;
           let maxOutputTokens = DEFAULT_OUTPUT_TOKENS;
+          let timeoutMs: number | undefined;
           try {
             const parsed = parseCodemodeSource(params.code);
             code = parsed.code;
             maxOutputTokens = parsed.options.maxOutputTokens ?? maxOutputTokens;
+            timeoutMs = parsed.options.timeoutMs;
           } catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             return {
@@ -335,6 +344,7 @@ export function createCodemodeTools(pi: ExtensionAPI): CodemodeTools {
             store: readStore(ctx),
             toolCallId,
             signal,
+            timeoutMs,
             onOutput: (items) => {
               const text = textOf(items);
               if (text === "") {
@@ -364,10 +374,15 @@ export function createCodemodeTools(pi: ExtensionAPI): CodemodeTools {
                 },
               });
             },
-            onCall: async ({ name, args }) => {
+            onCall: async ({ name, args, signal: callSignal }) => {
               if (fs.handles(name)) {
                 try {
-                  const result = await fs.execute(name, args, { ctx, signal });
+                  // 脚本里弹不了审批：需要授权的操作（工作区外写入）直接失败
+                  const result = await fs.execute(name, args, {
+                    ctx,
+                    signal: callSignal,
+                    unapprovable: true,
+                  });
                   if (result.reads !== undefined) {
                     Object.assign(recordedReads, result.reads);
                   }
@@ -382,7 +397,7 @@ export function createCodemodeTools(pi: ExtensionAPI): CodemodeTools {
               if (!callable.has(name)) {
                 return { ok: false, error: `Tool "${name}" is not available in codemode.` };
               }
-              return bus.executeCodemodeTool(name, args, { ctx, signal });
+              return bus.executeCodemodeTool(name, args, { ctx, signal: callSignal });
             },
           });
 

package/src/codemode/worker.js

@@ -344,7 +344,7 @@ var PRELUDE_SOURCE = String.raw`(function (bridge, toolsJson, storeJson) {
 				stringify({
 					name: "Error",
 					message:
-						"The script is waiting on a promise that can never settle: no tool call is pending, and timers do not exist here.",
+						"The script is waiting on a promise that can never settle: no tool call and no sleep is pending.",
 				}),
 			);
 			return true;

package/src/lib/tool-bus.ts

@@ -55,6 +55,7 @@ export interface StructuredToolDefinition<
     signal: AbortSignal | undefined,
     onUpdate: AgentToolUpdateCallback<TDetails> | undefined,
     ctx: ExtensionContext,
+    callOptions?: ToolCallOptions,
   ): Promise<AgentToolResult<TDetails> & { structuredResult: StructuredResult<Static<TOutput>> }>;
 }
 
@@ -111,16 +112,37 @@ export interface CodemodeToolDefinition<
   ): Promise<StructuredResult<Static<TOutput>>>;
 }
 
+/**
+ * 工具 `execute` 的额外调用选项：只有本仓库自己的调用路径会传（目前是 codemode 的嵌套
+ * 调用），pi 直接调用工具时它永远是 `undefined`。因此在 pi 的 `ToolDefinition` 之外，
+ * 总线单独把 `execute` 的签名放宽一个可选参数。
+ */
+export interface ToolCallOptions {
+  /** 本次调用不可请求用户审批：需要授权的操作直接失败，不弹审批框。 */
+  unapprovable?: boolean;
+}
+
 /**
  * 注册后的定义：`codemodeOnly` 标出未交给 pi 的脚本工具。`structuredSchema` 供 codemode
  * 渲染脚本侧返回类型；`scripted` 区分「`execute` 直接返回结构化结果」的脚本工具与经配置
  * 转成 codemode-only 的普通工具（后者仍返回 `AgentToolResult`，结构化结果在
  * `structuredResult` 里）。
  */
-export type RegisteredToolDefinition = ToolDefinition<TSchema, unknown, unknown> & {
+export type RegisteredToolDefinition = Omit<
+  ToolDefinition<TSchema, unknown, unknown>,
+  "execute"
+> & {
   structuredSchema?: TSchema;
   codemodeOnly?: boolean;
   scripted?: true;
+  execute(
+    toolCallId: string,
+    params: unknown,
+    signal: AbortSignal | undefined,
+    onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+    ctx: ExtensionContext,
+    callOptions?: ToolCallOptions,
+  ): Promise<AgentToolResult<unknown>>;
 };
 
 export interface ToolBus {
@@ -416,6 +438,8 @@ export function createToolBus(pi: ExtensionAPI, options: ToolBusOptions = {}): T
           options.signal,
           options.onUpdate,
           options.ctx,
+          // codemode 的嵌套调用弹不了审批框：需要授权的操作直接失败
+          { unapprovable: true },
         );
         if (definition.scripted === true) {
           return checkScriptedResult(name, definition.structuredSchema, result);

package/src/lib/write-guard.ts

@@ -139,6 +139,8 @@ export interface WriteGuardOptions {
   policy: RequestPolicy;
   /** 工具调用的中止信号：透传给审批对话框，工具被取消时对话框一起关掉。 */
   signal?: AbortSignal;
+  /** 本次调用不可请求用户审批（codemode 的嵌套调用）：区外写入直接失败，不弹框。 */
+  unapprovable?: boolean;
 }
 
 /**
@@ -164,6 +166,13 @@ export async function guardWriteAccess(
     throw new Error(`user deny ${opts.toolName}: blocked`);
   }
 
+  // codemode 内不弹审批：那次嵌套调用只经 codemode 暴露，弹不了框，因此直接失败并提示直调
+  if (opts.unapprovable === true) {
+    throw new Error(
+      `${opts.toolName} needs user approval to write outside the workspace, which codemode cannot ask for. Call the tool directly instead of from a script.`,
+    );
+  }
+
   if (process.platform === "win32") {
     // Windows 上退化为「只能写工作区」：无沙箱兜底，工作区外写入一律拒绝，
     // 不提供审批路径。

package/src/opencode/bash.ts

@@ -95,7 +95,7 @@ export function registerBashTool(bus: ToolBus, pi: ExtensionAPI, runtime: BwrapR
         },
         { additionalProperties: false },
       ),
-      async execute(id, params, signal, onUpdate, ctx) {
+      async execute(id, params, signal, onUpdate, ctx, callOptions) {
         const timeout = params.timeout ?? BASH_DEFAULT_TIMEOUT_MS;
         if (!Number.isFinite(timeout) || timeout <= 0 || timeout > BASH_MAX_TIMEOUT_MS) {
           throw new Error(`timeout must be between 1 and ${BASH_MAX_TIMEOUT_MS} milliseconds`);
@@ -115,6 +115,7 @@ export function registerBashTool(bus: ToolBus, pi: ExtensionAPI, runtime: BwrapR
             description: params.description,
             signal,
             onUpdate,
+            unapprovable: callOptions?.unapprovable,
           });
         } catch (error) {
           if (!(error instanceof Error)) {