@trim21/personal-pi-extensions 0.1.678 → 0.1.679

package/README.md

@@ -31,9 +31,9 @@
 
 `codemode` 让模型写一段 JavaScript（作为 async 函数体，`await` 与 `return` 都可用），在
 进程内的 worker 线程里用 QuickJS wasm VM 执行。VM 里没有 node、文件系统、网络、timer
-或模块加载，脚本唯一的出口是 `tools.<name>(args)`。
+或模块加载，脚本唯一的出口是 `call(name, args)`。
 
-- **嵌套调用经工具总线**：`tools.Read({ file_path })` 最终执行的是 `Read` 工具自己的
+- **嵌套调用经工具总线**：`call("Read", { file_path })` 最终执行的是 `Read` 工具自己的
   `execute`，所以工具的审批照常生效（写工作区外会弹 write-guard，Bash 沙箱外执行会弹
   自己的提权确认）。codemode 不额外加确认层：脚本里连发十次写操作就是十次工具自己的
   审批（需要审批的那些）。
@@ -42,10 +42,16 @@
   子代理的工具白名单都同样约束脚本。
 - **只有脚本输出进上下文**：`text(value)` / `console.log(...)` 与 `return` 值进入工具结果，
   中间的工具调用与它们的返回内容不会（也不在会话记录里留下工具调用条目）。
-- **脚本接口**：`tools` / `ALL_TOOLS` / `text` / `image` / `exit` / `console.*` /
-  `store.set` / `store.get` / `store.list`（会话内持久的键值表）；首行可选
+- **返回值**：声明了 `structuredSchema` 的工具（如 gh-readonly 的读类工具）把结果放在
+  `structuredResult` 里，`call()` 解包成对象给脚本；`{ ok: false, error }` 会 reject 成
+  `CallFailedError`（脚本可按 `instanceof CallFailedError` 区分工具失败与自身运行期错误）。
+  没有声明输出结构的工具回退成工具输出的文本。
+- **脚本接口**：`call` / `CallFailedError` / `ALL_TOOLS` / `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.679",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

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,35 @@ 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` 重载，外加 `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 }>;",
+    '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/prelude.ts

@@ -1,10 +1,12 @@
 /**
  * codemode 脚本侧的 prelude：在 QuickJS VM 里先于脚本求值，构建脚本能看到的全部
- * 能力（`tools` / `ALL_TOOLS` / `text` / `image` / `exit` / `console` / `store`），
- * 并把宿主桥接封在闭包里——脚本拿不到 `bridge` 本身。
+ * 能力（`call` / `CallFailedError` / `ALL_TOOLS` / `text` / `image` / `exit` /
+ * `console` / `store`），并把宿主桥接封在闭包里——脚本拿不到 `bridge` 本身。
  *
  * 值与参数过桥时都是 JSON 文本，本侧负责 parse/stringify；异步调用用一个 pending
- * 表把 id 映射到 promise，由宿主在结果到达时 settle。
+ * 表把 id 映射到 promise，由宿主在结果到达时 settle。每次嵌套调用失败都由宿主以
+ * `ok: false` 回报，本侧统一 reject 成 `CallFailedError`（脚本可以按 instanceof 区分
+ * 「工具失败」与自己的运行期错误）。
  *
  * 求值结果是一个函数 `(bridge, toolsJson, storeJson) => { settle, run, stalled }`。
  * `bridge(kind, a, b, c)`：
@@ -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,26 @@ 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);
+
 	// key -> JSON 文本；容量按 key 与 JSON 的字符数计
 	const stored = new Map();
 	const writes = new Map();
@@ -242,7 +257,8 @@ 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, "console", { value: console, enumerable: true });
 	Object.defineProperty(globalThis, "text", { value: text, enumerable: true });
@@ -255,7 +271,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 +286,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

@@ -23,6 +23,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 +56,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 +89,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 +119,7 @@ export interface StoreWrites {
 export interface ScriptTool {
   name: string;
   description?: string;
+  structuredSchema?: unknown;
 }
 
 export type HostMessage =

package/src/codemode/tool.ts

@@ -1,6 +1,6 @@
 /**
  * codemode 工具：模型写一段 JavaScript，脚本在 QuickJS VM（worker 线程）里执行，脚本唯一
- * 的能力是调用 `tools.*`——每个嵌套调用都由主线程经本仓库的工具总线执行，因此工具实现
+ * 的能力是调用 `call(name, args)`——每个嵌套调用都由主线程经本仓库的工具总线执行，因此工具实现
  * 内部的审批（工作区外写入、Bash 沙箱提权等）照常生效；codemode 不再加自己的确认层。
  *
  * 可调用集合：总线上实际注册的工具减去 codemode 自身与 spawn-agent，执行时再与 active
@@ -45,6 +45,7 @@ interface CallableTool {
   name: string;
   description?: string;
   parameters?: unknown;
+  structuredSchema?: unknown;
 }
 
 /** 只在 pi 有 active 工具概念时才求交（子代理、`--tools` 等场景）。 */
@@ -66,6 +67,7 @@ function collectTools(bus: ToolBus, allowed: Set<string> | undefined): CallableT
       name: definition.name,
       description: definition.description,
       parameters: definition.parameters,
+      structuredSchema: definition.structuredSchema,
     }));
 }
 
@@ -73,8 +75,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",
@@ -297,6 +299,11 @@ export function createCodemodeTools(pi: ExtensionAPI): CodemodeTools {
                 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 };

package/src/codemode/worker.js

@@ -13,6 +13,13 @@ var 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;
@@ -74,20 +81,26 @@ var 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);
+
 	// key -> JSON 文本；容量按 key 与 JSON 的字符数计
 	const stored = new Map();
 	const writes = new Map();
@@ -227,7 +240,8 @@ var 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, "console", { value: console, enumerable: true });
 	Object.defineProperty(globalThis, "text", { value: text, enumerable: true });
@@ -240,7 +254,7 @@ var 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;
@@ -255,7 +269,7 @@ var 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;
@@ -301,7 +315,9 @@ var outputItemSchema = Type.Union([
 ]);
 var toolDeclSchema = Type.Object({
   name: Type.String(),
-  description: Type.Optional(Type.String())
+  description: Type.Optional(Type.String()),
+  /** 工具的 structuredSchema（TypeBox schema）：脚本侧据此渲染 call() 的返回类型。 */
+  structuredSchema: Type.Optional(Type.Unknown())
 });
 var startSchema = Type.Object({
   t: Type.Literal("start"),
@@ -329,7 +345,7 @@ var callSchema = Type.Object({
   name: Type.String(),
   args: Type.Unknown()
 });
-var outputSchema = Type.Object({
+var outputFrameSchema = Type.Object({
   t: Type.Literal("output"),
   items: Type.Array(outputItemSchema)
 });
@@ -358,7 +374,7 @@ var doneSchema = Type.Union([
   })
 ]);
 var hostMessageSchema = Type.Union([startSchema, resultSchema]);
-var workerMessageSchema = Type.Union([callSchema, outputSchema, doneSchema]);
+var workerMessageSchema = Type.Union([callSchema, outputFrameSchema, doneSchema]);
 function decode(schema, value) {
   if (!Value.Check(schema, value)) {
     const preview = JSON.stringify(value).slice(0, 200);
@@ -372,9 +388,6 @@ function decodeHostMessage(value) {
 
 // src/codemode/worker.ts
 var MEMORY_LIMIT_BYTES = 512 * 1024 * 1024;
-function toScriptIdentifier(name) {
-  return name.replaceAll(/[^A-Za-z0-9_$]/g, "_").replaceAll(/^\d/g, "_");
-}
 function discardOutput(memory) {
   return {
     fd_write(_fd, iovsPtr, iovsLen, nwrittenPtr) {
@@ -493,8 +506,8 @@ async function runScript(wasm, start) {
           JSON.stringify(
             start.tools.map((tool) => ({
               name: tool.name,
-              jsName: toScriptIdentifier(tool.name),
-              description: tool.description
+              description: tool.description,
+              structuredSchema: tool.structuredSchema
             }))
           )
         ),
@@ -530,11 +543,8 @@ async function runScript(wasm, start) {
     drain();
   });
   try {
-    const fn = vm.evalCode(
-      `(async (tools, console) => {${start.code}
-})`,
-      "codemode.js"
-    );
+    const fn = vm.evalCode(`(async () => {${start.code}
+})`, "codemode.js");
     vm.callFunction(run, api, fn).dispose();
     fn.dispose();
     drain();
@@ -580,6 +590,3 @@ function main() {
   });
 }
 main();
-export {
-  toScriptIdentifier
-};

package/src/codemode/worker.ts

@@ -26,11 +26,6 @@ import {
 /** QuickJS VM 的堆上限：超量分配在脚本里变成 InternalError，而不是拖垮宿主。 */
 const MEMORY_LIMIT_BYTES = 512 * 1024 * 1024;
 
-/** 工具名到脚本标识符的归一化：非法字符换成 `_`，数字开头补 `_`。 */
-export function toScriptIdentifier(name: string): string {
-  return name.replaceAll(/[^A-Za-z0-9_$]/g, "_").replaceAll(/^\d/g, "_");
-}
-
 /**
  * QuickJS 把引擎诊断写到 fd 1 / 2，那会直接进 pi 的 TUI；按写入长度回报并丢弃内容，
  * 避免 libc 重试。
@@ -178,8 +173,8 @@ async function runScript(wasm: object, start: Extract<HostMessage, { t: "start"
           JSON.stringify(
             start.tools.map((tool) => ({
               name: tool.name,
-              jsName: toScriptIdentifier(tool.name),
               description: tool.description,
+              structuredSchema: tool.structuredSchema,
             })),
           ),
         ),
@@ -225,10 +220,7 @@ async function runScript(wasm: object, start: Extract<HostMessage, { t: "start"
 
   try {
     // 前缀与脚本首行共用一行，报错行号与用户写的脚本一致
-    const fn: JSValueHandle = vm.evalCode(
-      `(async (tools, console) => {${start.code}\n})`,
-      "codemode.js",
-    );
+    const fn: JSValueHandle = vm.evalCode(`(async () => {${start.code}\n})`, "codemode.js");
     vm.callFunction(run, api, fn).dispose();
     fn.dispose();
     drain();

package/src/gh/base.ts

@@ -9,7 +9,7 @@
 import { existsSync } from "node:fs";
 import { delimiter, join } from "node:path";
 
-import { Type } from "typebox";
+import { type Static, type TSchema, Type } from "typebox";
 import { Value } from "typebox/value";
 
 import { egress } from "../lib/egress.js";
@@ -25,7 +25,10 @@ import {
   type GithubSearch,
   renderHits,
 } from "../lib/github.js";
+import { parseWithSchema } from "../lib/parse-with-schema.js";
 import { type ToolPendant } from "../lib/pendant.js";
+import { type StructuredResult } from "../lib/tool-bus.js";
+import type { checksVerdictSchema } from "./schemas.js";
 
 /** A tool result: what the model sees plus the structured details payload. */
 export interface ToolResult {
@@ -33,6 +36,24 @@ export interface ToolResult {
   details: Record<string, unknown>;
 }
 
+/**
+ * 带结构化结果的结果：`structuredResult` 的成功支类型由 `T` 决定。声明了 structuredSchema
+ * 的工具用它，交给 codemode 脚本按名字调用时解包。它不改变 `content` 与 `details`。
+ */
+export type WithStructured<T> = ToolResult & { structuredResult: StructuredResult<T> };
+
+/** 某个 `structuredSchema` 对应的工具结果：成功支与 schema 的静态类型对齐。 */
+export type StructuredResultOf<TSchema_ extends TSchema> = WithStructured<Static<TSchema_>>;
+
+/** 结构化失败（Result 的失败支）：与具体的输出类型无关，任何结构化工具都能用。 */
+export interface StructuredFailure {
+  ok: false;
+  error: string;
+}
+
+/** 结构化失败的结果：不必抛异常就能把「没找到」这类结果告诉脚本。 */
+export type StructuredFailureResult = ToolResult & { structuredResult: StructuredFailure };
+
 /** What a toolcall handler receives from the framework. */
 export interface ToolCall<Params> {
   params: Params;
@@ -239,6 +260,32 @@ export function toToolResultJson(json: string, input?: unknown): ToolResult {
   };
 }
 
+/** 给结果附上结构化结果（成功支）：`value` 就是脚本解包后拿到的东西。 */
+export function withStructuredResult<T>(result: ToolResult, value: T): WithStructured<T> {
+  return { ...result, structuredResult: { ok: true, value } };
+}
+
+/**
+ * 透传型工具的成功结果：`gh --json` 的原始输出既是给模型的文本（整段 JSON，不经行
+ * 截断），也按 `schema` 解析成结构化结果。解析失败会抛错——schema 与 GitHub 实际返回
+ * 漂移时必须显式失败，不能悄悄少给字段。
+ */
+export function toStructuredJsonResult<T extends TSchema>(
+  json: string,
+  input: unknown,
+  schema: T,
+): StructuredResultOf<T> {
+  return withStructuredResult(
+    toToolResultJson(json, input),
+    parseWithSchema(schema, JSON.parse(json)),
+  );
+}
+
+/** 结构化失败（Result 的失败支）：不必抛异常就能把「没找到」这类结果告诉脚本。 */
+export function structuredFailure(error: string): StructuredFailure {
+  return { ok: false, error };
+}
+
 /**
  * Pendant subtitle for a tool result: `repo=x/y` (when provided) plus the
  * tool's id parameter, e.g. `repo=x/y number=123`. Returns undefined when
@@ -747,7 +794,7 @@ export async function waitChecksReport(options: {
   onUpdate: ((msg: ToolResult) => void) | undefined;
   params: unknown;
   pendant?: ToolPendant;
-}): Promise<ToolResult> {
+}): Promise<StructuredResultOf<typeof checksVerdictSchema>> {
   const { subject, owner, repo, headSha, failFast, event, signal, onUpdate, params, pendant } =
     options;
 
@@ -779,15 +826,18 @@ export async function waitChecksReport(options: {
   }
 
   const verdict = renderChecksVerdict({ subject, poll, actionJobs, enrichmentError });
-  return {
-    content: [{ type: "text", text: verdict.text }],
-    details: {
-      status: verdict.status,
-      totalChecks: poll.checks.length,
-      checks: poll.checks,
-      failedJobs: verdict.failedJobs,
-      input: params,
-      ...(pendant && { pendant }),
-    },
+  const payload = {
+    status: verdict.status,
+    totalChecks: poll.checks.length,
+    // 复制成可变数组：结构化结果的类型要与 structuredSchema 的静态类型一致
+    checks: [...poll.checks],
+    failedJobs: [...verdict.failedJobs],
   };
+  return withStructuredResult(
+    {
+      content: [{ type: "text", text: verdict.text }],
+      details: { ...payload, input: params, ...(pendant && { pendant }) },
+    },
+    payload,
+  );
 }