pi-ptc-subagents 6.1.0 → 7.0.0

package/dist/index.js

@@ -1,9 +1,9 @@
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { execSync, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { mkdir, open, readFile, rename, writeFile } from "node:fs/promises";
-import { spawn } from "node:child_process";
 import { gunzipSync, gzip } from "node:zlib";
 import { promisify } from "node:util";
 import { fileURLToPath } from "node:url";
@@ -3062,6 +3062,7 @@ const REPORT_CONTRACT_BLOCK = [
 	"```json",
 	"{ \"summary\": \"one sentence conclusion\", \"findings\": [{ \"what\": \"claim\", \"evidence\": \"where it comes from\" }], \"files_touched\": [\"relative/path\"], \"usage\": { \"input\": 0, \"output\": 0, \"cost\": 0, \"turns\": 0 } }",
 	"```",
+	"Rules: \"summary\" is your deliverable — answer the task asked, in one sentence. \"findings\" carries load-bearing evidence only; never recap content you merely read. Do NOT write report/summary .md files — your final message is what the parent reads.",
 	"findings/files_touched/usage may be omitted when empty. Your prose answer stays; the report is checked alongside it.",
 	"</child-report-contract>"
 ].join("\n");
@@ -3132,6 +3133,14 @@ function spawnChild(argv, env = process.env) {
 function escapeXmlText(text) {
 	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
+function supportsNoMcp(piVersion) {
+	if (!piVersion) return false;
+	const [major = "0", minor = "0"] = piVersion.trim().replace(/^v/, "").split(".");
+	const M = Number.parseInt(major, 10);
+	const m = Number.parseInt(minor, 10);
+	if (Number.isNaN(M) || Number.isNaN(m)) return false;
+	return M > 1 || M === 1 && m >= 1;
+}
 function buildPiArgv(input, context) {
 	const argv = [
 		"pi",
@@ -3148,6 +3157,8 @@ function buildPiArgv(input, context) {
 			"</pi-ptc-context>"
 		].filter(Boolean).join("\n")
 	];
+	argv.push("--no-extensions", "--no-skills");
+	if (supportsNoMcp(context.piVersion)) argv.push("--no-mcp");
 	const model = input.model ?? input.agentModel ?? context.sessionModel;
 	const thinking = input.thinkingLevel ?? input.agentThinkingLevel;
 	if (model) argv.push("--model", thinking ? `${model}:${thinking}` : model);
@@ -3235,6 +3246,8 @@ function parseChildStream(stdout) {
 				observedUsage = {
 					input: message.usage.input,
 					output: message.usage.output,
+					...message.usage.cacheRead !== void 0 ? { cacheRead: message.usage.cacheRead } : {},
+					...message.usage.cacheWrite !== void 0 ? { cacheWrite: message.usage.cacheWrite } : {},
 					...cost !== void 0 ? { cost } : {}
 				};
 			}
@@ -4964,6 +4977,7 @@ function assemblePtcSession(options = {}) {
 		registry,
 		gates: options.gates,
 		whyEnabled: options.whyEnabled,
+		context: options.context,
 		...options.engine
 	});
 	return {
@@ -4994,6 +5008,20 @@ const textResult = (value) => ({
 const packageRoot = fileURLToPath(new URL("..", import.meta.url));
 const publishedDetailDir = join(packageRoot, "docs", "routes");
 const detailDir = existsSync(publishedDetailDir) ? publishedDetailDir : join(packageRoot, "..", "routes", "docs", "routes");
+function resolvePiVersion() {
+	try {
+		return execSync("pi --version", {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim() || void 0;
+	} catch {
+		return;
+	}
+}
 function piPtcEntry(pi) {
 	pi.on("session_start", (_event, ctx) => {
 		if (Number(process.env.PI_PTC_DEPTH ?? 0) > 0) {
@@ -5034,6 +5062,7 @@ function piPtcEntry(pi) {
 			userDir: join(getAgentDir(), "agents"),
 			projectDir: join(process.cwd(), ".pi", "agents")
 		};
+		const piVersion = resolvePiVersion();
 		let session;
 		const faceAddedByUs = /* @__PURE__ */ new Set();
 		const applyTaskFaceVisibility = () => {
@@ -5055,6 +5084,10 @@ function piPtcEntry(pi) {
 		session = assemblePtcSession({
 			onTransition: () => applyTaskFaceVisibility(),
 			whyEnabled: () => whyEnabledOverride ?? whyEnabledPersisted,
+			context: {
+				depth: 0,
+				piVersion
+			},
 			engine: {
 				notifications,
 				resolveAgent: (name, scope) => findAgent(name, agentDirs, scope),

package/dist/worker.js

@@ -1,66 +1,76 @@
 import { stripTypeScriptTypes } from "node:module";
-import { inspect } from "node:util";
 import { parentPort, workerData } from "node:worker_threads";
+import vm from "node:vm";
 // ../ptc/src/compile.ts
 function compileProgram(source) {
-	const stripped = stripTypeScriptTypes(`async function __ptcProgram() {\n${source}\n}`, { mode: "strip" });
-	return new Function(`"use strict";\n${stripped}\nreturn __ptcProgram;`)();
-}
-// ../ptc/src/workflow-helpers.ts
-function createWorkflowHelpers(emit) {
-	return {
-		log: (...args) => emit(args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ")),
-		phase: (name) => emit(`— phase: ${name} —`),
-		parallel: (items) => Promise.allSettled(items.map((run) => run())),
-		pipeline: (items, step) => {
-			const results = [];
-			return items.reduce((chain, item, index) => chain.then(async () => {
-				results.push(await step(item, index));
-			}), Promise.resolve()).then(() => results);
-		}
-	};
+	return `"use strict";\n${stripTypeScriptTypes(`async function __ptcProgram() {\n${source}\n}`, { mode: "strip" })}\n;globalThis.__ptcProgram = __ptcProgram;`;
 }
 // ../ptc/src/worker-main.ts
+const CELL_PREAMBLE = `"use strict";
+(function () {
+var __bridge = globalThis.__ptcCall;
+var __emit = globalThis.__ptcConsole;
+var __args = JSON.parse(globalThis.__ptcArgsJson);
+// contextified 全局属性不可 delete（vm 限制）但可写——置 undefined 即脱手，桥只剩序言闭包可达
+globalThis.__ptcCall = undefined;
+globalThis.__ptcConsole = undefined;
+globalThis.__ptcArgsJson = undefined;
+function __ptcFmt(v) {
+  if (typeof v === "string") return v;
+  try { var s = JSON.stringify(v); return s === undefined ? String(v) : s; } catch (e) { return String(v); }
+}
+function __ptcJoin(values) {
+  var out = [];
+  for (var i = 0; i < values.length; i++) out.push(__ptcFmt(values[i]));
+  return out.join(" ");
+}
+var __ptcTools = {};
+__PTC_NAMES__.forEach(function (name) {
+  __ptcTools[name] = function (args) {
+    return new Promise(function (resolve, reject) {
+      __bridge(name, JSON.stringify(args === undefined ? null : args)).then(function (json) {
+        var value;
+        try { value = JSON.parse(json); } catch (e) { reject(e); return; }
+        resolve(value);
+      }, reject);
+    });
+  };
+});
+globalThis.tools = Object.freeze(__ptcTools);
+globalThis.console = Object.freeze({
+  log: function () { __emit("log", __ptcJoin(arguments)); },
+  info: function () { __emit("info", __ptcJoin(arguments)); },
+  warn: function () { __emit("warn", __ptcJoin(arguments)); },
+  error: function () { __emit("error", __ptcJoin(arguments)); },
+  debug: function () { __emit("debug", __ptcJoin(arguments)); }
+});
+globalThis.args = Object.freeze(__args);
+if (__PTC_WORKFLOW__) {
+  globalThis.workflow = Object.freeze({
+    log: function () { __emit("log", __ptcJoin(arguments)); },
+    phase: function (name) { __emit("log", "— phase: " + name + " —"); },
+    parallel: function (items) { return Promise.allSettled(items.map(function (run) { return run(); })); },
+    pipeline: function (items, step) {
+      var results = [];
+      return items.reduce(function (chain, item, index) {
+        return chain.then(function () { return Promise.resolve(step(item, index)).then(function (r) { results.push(r); }); });
+      }, Promise.resolve()).then(function () { return results; });
+    }
+  });
+}
+})();
+`;
 function workerMain(deps) {
-	let tools = {};
+	let bindingNames = [];
+	let surface = "run_code";
 	let pending = /* @__PURE__ */ new Map();
 	let nextCallId = 1;
 	let currentRunId = null;
 	let logs = [];
-	const globalBaseline = /* @__PURE__ */ new Set();
-	const consoleBaseline = { ...console };
 	deps.onFrame((frame) => {
 		if (frame.kind === "init") {
-			for (const name of Object.getOwnPropertyNames(globalThis)) globalBaseline.add(name);
-			tools = Object.freeze(Object.fromEntries(frame.bindingNames.map((name) => [name, (args) => {
-				if (currentRunId === null) return Promise.reject(/* @__PURE__ */ new Error("run 已结束：reset 后不再接受工具调用"));
-				const call = new Promise((resolve, reject) => {
-					const callId = nextCallId++;
-					pending.set(callId, {
-						resolve,
-						reject
-					});
-					deps.post({
-						kind: "call",
-						runId: currentRunId ?? "",
-						callId,
-						name,
-						args
-					});
-				});
-				call.catch(() => {});
-				return call;
-			}])));
-			defineGlobal("tools", tools);
-			if (frame.surface === "workflow") defineGlobal("workflow", createWorkflowHelpers((text) => {
-				logs.push(text);
-				deps.post({
-					kind: "log",
-					runId: currentRunId ?? "",
-					level: "log",
-					text
-				});
-			}));
+			bindingNames = frame.bindingNames;
+			surface = frame.surface;
 			deps.post({ kind: "ready" });
 			return;
 		}
@@ -68,8 +78,6 @@ function workerMain(deps) {
 			currentRunId = null;
 			for (const { reject } of pending.values()) reject(/* @__PURE__ */ new Error("run reset：worker 被复用"));
 			pending = /* @__PURE__ */ new Map();
-			for (const name of Object.getOwnPropertyNames(globalThis)) if (!globalBaseline.has(name)) delete globalThis[name];
-			Object.assign(console, consoleBaseline);
 			deps.post({ kind: "ready" });
 			return;
 		}
@@ -77,25 +85,28 @@ function workerMain(deps) {
 			const entry = pending.get(frame.callId);
 			if (!entry) return;
 			pending.delete(frame.callId);
-			if (frame.ok) entry.resolve(frame.value);
-			else entry.reject(new Error(frame.error));
+			if (frame.ok) {
+				let json;
+				try {
+					json = JSON.stringify(frame.value ?? null);
+				} catch {
+					json = void 0;
+				}
+				if (json === void 0) entry.reject(/* @__PURE__ */ new Error("binding 返回值不可 JSON 序列化（如循环引用）"));
+				else entry.resolve(json);
+			} else entry.reject(new Error(frame.error));
 			return;
 		}
 		if (frame.kind === "cancel") return;
 		run(frame.code, frame.id, frame.args);
 	});
-	function defineGlobal(name, value) {
-		Object.defineProperty(globalThis, name, {
-			value,
-			writable: false,
-			configurable: true
-		});
+	function preamble() {
+		return CELL_PREAMBLE.replace(/__PTC_NAMES__/g, () => JSON.stringify(bindingNames)).replace(/__PTC_WORKFLOW__/g, () => surface === "workflow" ? "true" : "false");
 	}
 	async function run(code, runId, args) {
 		currentRunId = runId;
 		logs = [];
-		defineGlobal("args", args ?? {});
-		installConsole((level, text) => {
+		const postLog = (level, text) => {
 			logs.push(text);
 			deps.post({
 				kind: "log",
@@ -103,17 +114,54 @@ function workerMain(deps) {
 				level,
 				text
 			});
-		});
-		const outcome = await execute(code);
+		};
+		const outcome = await execute(code, vm.createContext({
+			__ptcArgsJson: JSON.stringify(args ?? {}),
+			__ptcCall(name, argsJson) {
+				if (currentRunId === null) return Promise.reject(/* @__PURE__ */ new Error("run 已结束：reset 后不再接受工具调用"));
+				let parsed = null;
+				try {
+					parsed = JSON.parse(argsJson);
+				} catch {
+					return Promise.reject(/* @__PURE__ */ new Error("工具参数不是合法 JSON"));
+				}
+				const call = new Promise((resolve, reject) => {
+					const callId = nextCallId++;
+					pending.set(callId, {
+						resolve,
+						reject
+					});
+					deps.post({
+						kind: "call",
+						runId: currentRunId ?? "",
+						callId,
+						name,
+						args: parsed
+					});
+				});
+				call.catch(() => {});
+				return call;
+			},
+			__ptcConsole(level, text) {
+				postLog(level, String(text));
+			}
+		}));
 		deps.post({
 			kind: "settled",
 			runId,
 			outcome
 		});
 	}
-	async function execute(code) {
+	function errorMessage(error) {
+		if (error instanceof Error) return error.message;
+		if (error && typeof error === "object" && typeof error.message === "string") return error.message;
+		return String(error);
+	}
+	async function execute(code, context) {
 		try {
-			const value = await compileProgram(code).call({ tools });
+			vm.runInContext(preamble(), context, { filename: "ptc_preamble.js" });
+			vm.runInContext(compileProgram(code), context, { filename: "run_code.js" });
+			const value = await context.__ptcProgram.call(context);
 			if (value === void 0) return {
 				status: "fulfilled",
 				value: { $void: true },
@@ -133,21 +181,12 @@ function workerMain(deps) {
 		} catch (error) {
 			return {
 				status: "rejected",
-				error: error instanceof Error ? error.message : String(error),
+				error: errorMessage(error),
 				logs
 			};
 		}
 	}
 }
-function installConsole(emit) {
-	for (const level of [
-		"log",
-		"info",
-		"warn",
-		"error",
-		"debug"
-	]) console[level] = (...args) => emit(level, args.map((a) => typeof a === "string" ? a : inspect(a)).join(" "));
-}
 // ../ptc/src/worker-entry.ts
 if (!parentPort) throw new Error("worker-entry 只能在 worker 线程里加载");
 Object.freeze(workerData);

package/docs/routes/create-a-task.md

@@ -13,3 +13,14 @@ agent 定义里的 `tools / model / thinkingLevel / childReport` 由 frontmatter
 
 任务建成后在任务记录里排队（满员排队不拒绝，ADR-0010），经
 `ptc_task_list / ptc_task_output / ptc_task_stop` 查/停。
+
+## Briefing 纪律（省 token，派发前自查）
+
+- **给确切路径、命令、决策**：孩子看不到父会话。task 里写死一个路径，省孩子一轮探索
+  （每轮探索 = 一次工具调用结果 + 推理 token）。
+- **写明最终消息要带回什么**：孩子只回一次。要什么格式、哪些字段，task 里说清。
+- **不确定能否一次搜中才派**：目标明确（已知路径、已知行号）的活别派，主会话直接
+  `tools.read` 更省。
+- **同域的活合并给一个串行孩子**：每个孩子都付一份固定 harness 税（系统提示词 +
+  项目上下文）。多个重叠的小活拆并行 = 同一份探索被付费多次。
+- **孩子不写报告文件**：交付物就是最终消息（含报告 JSON 块），落盘 .md 是浪费。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ptc-subagents",
-  "version": "6.1.0",
+  "version": "7.0.0",
   "description": "Programmable tool calling (PTC) and subagent fan-out for pi",
   "keywords": [
     "pi",
@@ -30,10 +30,12 @@
     ".": "./dist/index.js"
   },
   "scripts": {
-    "build": "pnpm -r run build",
+    "build": "pnpm -r --filter=!@pi-ptc/website run build",
     "prepack": "pnpm run build && rm -rf dist docs/routes && cp -R packages/entry/dist dist && cp -R packages/routes/docs/routes docs/routes",
-    "check": "pnpm -r run check",
+    "check": "pnpm -r --filter=!@pi-ptc/website run check",
     "lint": "oxlint",
+    "test": "node --test tests/*.test.mjs",
+    "pretest": "pnpm run build",
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check"
   },