@trim21/personal-pi-extensions 0.1.678 → 0.1.680

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,36 @@ 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);
+
+	// 脚本的文件原语：与工具走同一条桥，但它们是内建能力而不是工具——不进 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();
@@ -227,8 +250,10 @@ 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, "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 });
@@ -240,7 +265,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 +280,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;
@@ -295,13 +320,16 @@ var PRELUDE_SOURCE = String.raw`(function (bridge, toolsJson, storeJson) {
 // src/codemode/protocol.ts
 import { Type } from "typebox";
 import { Value } from "typebox/value";
+var MEMORY_LIMIT_BYTES = 2 * 1024 ** 3;
 var outputItemSchema = Type.Union([
   Type.Object({ type: Type.Literal("text"), text: Type.String() }),
   Type.Object({ type: Type.Literal("image"), data: Type.String(), mimeType: Type.String() })
 ]);
 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 +357,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 +386,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);
@@ -371,10 +399,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 +517,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 +554,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 +601,3 @@ function main() {
   });
 }
 main();
-export {
-  toScriptIdentifier
-};

package/src/codemode/worker.ts

@@ -17,20 +17,13 @@ import { PRELUDE_SOURCE } from "./prelude.js";
 import {
   decodeHostMessage,
   type HostMessage,
+  MEMORY_LIMIT_BYTES,
   type ScriptError,
   type StoreWrites,
   type WorkerBootstrap,
   type WorkerMessage,
 } from "./protocol.js";
 
-/** 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 +171,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 +218,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,
+  );
 }

package/src/gh/schemas.ts

@@ -0,0 +1,230 @@
+/**
+ * gh-readonly 工具的结构化结果 schema（TypeBox）。
+ *
+ * 两个用途：codemode 脚本侧据此渲染 `call()` 的返回类型；工具总线在运行期用它复核
+ * `structuredResult.value`。因此 schema 必须**允许额外字段**（GitHub 的 JSON 只多不少，
+ * 多出来的字段不该让工具失败），只对工具本身已经依赖的字段设 required。
+ *
+ * 字段名取自 GitHub 的两种传输：`gh ... view --json`（GraphQL，actor 叫 `author` /
+ * `user`）与 REST（`/pulls/:n/comments` 等，用了 `diff_hunk` / `submitted_at` 这类
+ * 下划线命名）。评论与评审条目因此放宽成两者的并集。
+ */
+
+import { Type } from "typebox";
+
+// ── 共享片段 ─────────────────────────────────────────────────────────────────
+
+/** GitHub 的 actor（author / assignee / mergedBy / review 作者）。 */
+export const ghActorSchema = Type.Object({
+  login: Type.Optional(Type.String()),
+  name: Type.Optional(Type.String()),
+  is_bot: Type.Optional(Type.Boolean()),
+});
+
+export const ghLabelSchema = Type.Object({
+  name: Type.String(),
+  color: Type.Optional(Type.String()),
+  description: Type.Optional(Type.String()),
+});
+
+export const ghMilestoneSchema = Type.Object({
+  title: Type.String(),
+  number: Type.Optional(Type.Number()),
+  dueOn: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+});
+
+/** 评论条目：GraphQL 的 `author`/`createdAt` 与 REST 的 `user`/`diff_hunk` 并集。 */
+export const ghCommentSchema = Type.Object({
+  id: Type.Optional(Type.Union([Type.String(), Type.Number()])),
+  body: Type.Optional(Type.String()),
+  author: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  user: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  path: Type.Optional(Type.String()),
+  line: Type.Optional(Type.Union([Type.Number(), Type.Null()])),
+  diff_hunk: Type.Optional(Type.String()),
+  createdAt: Type.Optional(Type.String()),
+  url: Type.Optional(Type.String()),
+});
+
+/** 评审条目：GraphQL 的 `reviews` 与 REST 的 `/pulls/:n/reviews` 并集。 */
+export const ghReviewSchema = Type.Object({
+  id: Type.Optional(Type.Union([Type.String(), Type.Number()])),
+  body: Type.Optional(Type.String()),
+  author: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  user: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  state: Type.Optional(Type.String()),
+  createdAt: Type.Optional(Type.String()),
+  submitted_at: Type.Optional(Type.String()),
+  url: Type.Optional(Type.String()),
+});
+
+/** 待评审人：可能是用户（login）也可能是团队（slug）。 */
+export const ghReviewRequestSchema = Type.Object({
+  login: Type.Optional(Type.String()),
+  name: Type.Optional(Type.String()),
+  slug: Type.Optional(Type.String()),
+});
+
+/** `read-github-pr-status` / 两个 wait 工具共用的检查桶。 */
+export const checkBucketSchema = Type.Union([
+  Type.Literal("pass"),
+  Type.Literal("fail"),
+  Type.Literal("pending"),
+  Type.Literal("skipped"),
+]);
+
+// ── 各工具的输出 ─────────────────────────────────────────────────────────────
+
+/** `read-github-issue`：`gh issue view --json` 的输出。 */
+export const issueViewSchema = Type.Object({
+  number: Type.Number(),
+  title: Type.String(),
+  state: Type.String(),
+  body: Type.Optional(Type.String()),
+  author: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  createdAt: Type.Optional(Type.String()),
+  updatedAt: Type.Optional(Type.String()),
+  closedAt: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  url: Type.Optional(Type.String()),
+  labels: Type.Optional(Type.Array(ghLabelSchema)),
+  assignees: Type.Optional(Type.Array(ghActorSchema)),
+  comments: Type.Optional(Type.Array(ghCommentSchema)),
+  milestone: Type.Optional(Type.Union([ghMilestoneSchema, Type.Null()])),
+});
+
+/** `read-github-pr`：`gh pr view --json` 的输出，比 issue 多出合并与 diff 统计。 */
+export const prViewSchema = Type.Object({
+  number: Type.Number(),
+  title: Type.String(),
+  state: Type.String(),
+  body: Type.Optional(Type.String()),
+  author: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  createdAt: Type.Optional(Type.String()),
+  updatedAt: Type.Optional(Type.String()),
+  closedAt: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  mergedAt: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  mergedBy: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  headRefName: Type.Optional(Type.String()),
+  baseRefName: Type.Optional(Type.String()),
+  url: Type.Optional(Type.String()),
+  additions: Type.Optional(Type.Number()),
+  deletions: Type.Optional(Type.Number()),
+  changedFiles: Type.Optional(Type.Number()),
+  labels: Type.Optional(Type.Array(ghLabelSchema)),
+  assignees: Type.Optional(Type.Array(ghActorSchema)),
+  reviewRequests: Type.Optional(Type.Array(ghReviewRequestSchema)),
+  reviews: Type.Optional(Type.Array(ghReviewSchema)),
+  comments: Type.Optional(Type.Array(ghCommentSchema)),
+  milestone: Type.Optional(Type.Union([ghMilestoneSchema, Type.Null()])),
+});
+
+/** `read-github-issue-comments`：`gh issue view --json comments`。 */
+export const issueCommentsSchema = Type.Object({
+  comments: Type.Array(ghCommentSchema),
+});
+
+/**
+ * `read-github-pr-comments`：默认模式是 `gh pr view --json comments`（只有 comments），
+ * `reviews: true` 时走 REST 同时给出 reviews 与行内评论。两个字段都可选。
+ */
+export const prCommentsSchema = Type.Object({
+  comments: Type.Optional(Type.Array(ghCommentSchema)),
+  reviews: Type.Optional(Type.Array(ghReviewSchema)),
+});
+
+/** `read-github-pr-status`：工具自己拼的 `{pr, repo, head_sha, checks}`。 */
+export const prStatusSchema = Type.Object({
+  pr: Type.Number(),
+  repo: Type.String(),
+  head_sha: Type.String(),
+  checks: Type.Array(
+    Type.Object({
+      name: Type.String(),
+      bucket: checkBucketSchema,
+      event: Type.Union([Type.String(), Type.Null()]),
+      run_id: Type.Union([Type.Number(), Type.Null()]),
+      job_id: Type.Union([Type.Number(), Type.Null()]),
+      url: Type.Union([Type.String(), Type.Null()]),
+    }),
+  ),
+});
+
+export const workflowJobsSchema = Type.Object({
+  total_count: Type.Number(),
+  jobs: Type.Array(
+    Type.Object({
+      id: Type.Number(),
+      run_id: Type.Number(),
+      run_url: Type.String(),
+      name: Type.String(),
+      status: Type.String(),
+      conclusion: Type.Union([Type.String(), Type.Null()]),
+      html_url: Type.Union([Type.String(), Type.Null()]),
+      steps: Type.Array(
+        Type.Object({
+          name: Type.String(),
+          number: Type.Number(),
+          status: Type.String(),
+          conclusion: Type.Union([Type.String(), Type.Null()]),
+          started_at: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+        }),
+      ),
+    }),
+  ),
+});
+
+/** `read-github-ci-logs`：`CiLogsJobIndex`（步骤带它在原始日志里的行号范围）。 */
+export const ciLogsSchema = Type.Object({
+  name: Type.String(),
+  id: Type.Number(),
+  status: Type.String(),
+  conclusion: Type.Union([Type.String(), Type.Null()]),
+  log_file: Type.String(),
+  steps: Type.Array(
+    Type.Object({
+      number: Type.Number(),
+      name: Type.String(),
+      conclusion: Type.Union([Type.String(), Type.Null()]),
+      start_line: Type.Optional(Type.Number()),
+      end_line: Type.Optional(Type.Number()),
+    }),
+  ),
+});
+
+/** `download-github-release-assets`：下载目录里此刻的文件清单。 */
+export const releaseDownloadSchema = Type.Object({
+  repo: Type.String(),
+  tag: Type.String(),
+  dir: Type.String(),
+  files: Type.Array(
+    Type.Object({ name: Type.String(), path: Type.String(), bytes: Type.Number() }),
+  ),
+});
+
+/** 两个 wait 工具共享的判定结果（`waitChecksReport` 的 payload）。 */
+export const checksVerdictSchema = Type.Object({
+  status: Type.Union([Type.Literal("success"), Type.Literal("failure"), Type.Literal("pending")]),
+  totalChecks: Type.Number(),
+  checks: Type.Array(
+    Type.Object({
+      name: Type.String(),
+      bucket: checkBucketSchema,
+      startedAt: Type.Union([Type.String(), Type.Null()]),
+      link: Type.Union([Type.String(), Type.Null()]),
+      event: Type.Union([Type.String(), Type.Null()]),
+      runId: Type.Union([Type.Number(), Type.Null()]),
+      jobId: Type.Union([Type.Number(), Type.Null()]),
+    }),
+  ),
+  failedJobs: Type.Array(
+    Type.Object({
+      runId: Type.Number(),
+      runName: Type.String(),
+      runUrl: Type.String(),
+      jobId: Type.Number(),
+      jobName: Type.String(),
+      conclusion: Type.String(),
+      jobUrl: Type.Optional(Type.String()),
+    }),
+  ),
+});