pi-ptc-subagents 6.0.0 → 6.0.2

package/README.md

@@ -70,9 +70,12 @@ Which one you get depends on whether `codemode` is loaded and callable. Nothing
 
 ## PTC mode
 
-On a `full_ptc` session, PTC mode moves the built-in tools behind the program, so writing
-one becomes the shortest path. `/ptc mode off` restores them. `/ptc off` stops new
-dispatches and withdraws the orchestration tools; running tasks keep running.
+On a `full_ptc` session, PTC mode adds a routing lead to the system prompt: batch your
+tool calls into one program. `/ptc mode off` drops the lead.
+
+It does not hide the built-in tools from the model. pi keeps a tool callable from a
+program only while it is active, so narrowing the loadout would take `tools.read` away
+from the program too — the two cannot both hold on pi 1.4.0.
 
 ## Configuration
 

package/dist/index.js

@@ -1,4 +1,4 @@
-import { formatSkillsForPrompt, getAgentDir, loadSkills } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
@@ -4890,7 +4890,10 @@ function createPtcRunCodeTool(options) {
 		description: TOOLS$1.ptc_run_code.description(options.surface ?? "full_ptc"),
 		parameters: RUN_CODE_PARAMETERS,
 		renderResult: renderPtcResult("run_code"),
-		execute: async (_id, args) => {
+		execute: async (...rawArgs) => {
+			const args = rawArgs[1];
+			const ctx = rawArgs.find((value) => typeof value?.executeTool === "function");
+			options.onToolContext?.(ctx);
 			const outcome = await runPtcProgram({
 				code: args.code,
 				surface: "run_code",
@@ -4936,7 +4939,10 @@ function createPtcWorkflowTool(options) {
 		description: TOOLS$1.ptc_workflow.description(options.surface ?? "full_ptc"),
 		parameters: WORKFLOW_PARAMETERS,
 		renderResult: renderPtcResult("workflow"),
-		execute: async (_id, params) => {
+		execute: async (...rawArgs) => {
+			const params = rawArgs[1];
+			const ctx = rawArgs.find((value) => typeof value?.executeTool === "function");
+			options.onToolContext?.(ctx);
 			try {
 				validateWorkflowArgs(params.args);
 			} catch (error) {
@@ -5116,11 +5122,11 @@ const ROUTE_INDEX_LEAD = {
 	full_ptc: "批量调工具默认先写程序（ptc_run_code）；单次调用或要逐步判断、审批敏感的才直连。",
 	codemode_ptc: "编排写 codemode 脚本；批量派活经脚本内的 pi_task_codemode；要查/停任务用任务面三工具。"
 };
-function renderRouteIndex(surface) {
-	const lines = ROUTES.map((route) => `- ${route.name} — ${route.when}。这面怎么走：${route.how[surface]}。细节：${route.detail}`);
+function renderRouteIndex(surface, detailBase, nudge = true) {
+	const lines = ROUTES.map((route) => `- ${route.name} — ${route.when}。这面怎么走：${route.how[surface]}。细节：${detailBase ? join(detailBase, route.detail.split("/").pop()) : route.detail}`);
 	let index = [
 		`<ptc>`,
-		ROUTE_INDEX_LEAD[surface],
+		...nudge ? [ROUTE_INDEX_LEAD[surface]] : [],
 		"路由表（一条一行，详情按需 read）：",
 		...lines,
 		`</ptc>`
@@ -5221,6 +5227,9 @@ const textResult = (value) => ({
 	}],
 	details: void 0
 });
+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 piPtcEntry(pi) {
 	pi.on("session_start", (_event, ctx) => {
 		if (Number(process.env.PI_PTC_DEPTH ?? 0) > 0) {
@@ -5230,37 +5239,15 @@ function piPtcEntry(pi) {
 		const surface = pi.getActiveTools().includes("codemode") ? "codemode_ptc" : FALLBACK_SURFACE_MODE;
 		let modeEnabled = readDefaultModeConfig(getAgentDir());
 		let modeActive = false;
-		let baseLoadout = null;
 		const applyMode = () => {
-			const active = pi.getActiveTools();
-			const shouldEnter = surface === "full_ptc" && modeEnabled && active.includes("ptc_run_code");
-			if (shouldEnter && !modeActive) {
-				baseLoadout ??= [...active];
-				pi.setActiveTools(active.filter((name) => !KNOWN_BINDING_NAMES.includes(name)));
-				modeActive = true;
-			} else if (!shouldEnter && modeActive && baseLoadout) {
-				pi.setActiveTools(baseLoadout);
-				baseLoadout = null;
-				modeActive = false;
-			}
+			modeActive = surface === "full_ptc" && modeEnabled;
 		};
 		applyMode();
 		pi.on("before_agent_start", (event) => {
 			applyMode();
 			applyTaskFaceVisibility(pi, session);
 			const sections = event.systemPromptOptions?.sections;
-			if (sections) sections["ptc"] = renderRouteIndex(surface);
-			if (!modeActive) return;
-			const active = pi.getActiveTools();
-			if (active.includes("read") || active.includes("bash")) return;
-			const loaded = loadSkills({
-				cwd: process.cwd(),
-				agentDir: getAgentDir(),
-				skillPaths: [],
-				includeDefaults: true
-			});
-			if (loaded.skills.length === 0) return;
-			if (sections) sections["available_skills"] = formatSkillsForPrompt(loaded.skills, "indirect");
+			if (sections) sections["ptc"] = renderRouteIndex(surface, detailDir, modeActive);
 		});
 		const pool = new WorkerPool(spawnPtcWorker);
 		const notifications = new NotificationCenter();
@@ -5305,7 +5292,7 @@ function piPtcEntry(pi) {
 			]
 		});
 		pi.registerCommand("ptc", {
-			description: "/ptc off|on：派发开关 · /ptc why on|off：理由开关 · /ptc mode on|off：PTC 模式（收窄/恢复 loadout）",
+			description: "/ptc off|on：派发开关 · /ptc why on|off：理由开关 · /ptc mode on|off：PTC 模式（程序优先的引导层）",
 			handler: async (args, cmdCtx) => {
 				const [sub, rest] = args.trim().split(/\s+/);
 				if (sub === "off") {
@@ -5358,12 +5345,16 @@ function piPtcEntry(pi) {
 		};
 		registerTaskFace(registerTracked, session, surface);
 		applyTaskFaceVisibility(pi, session);
-		const bindings = createBindingTable(pi, ctx, session);
+		let toolContext;
+		const getBindings = () => createBindingTable(pi, session, () => toolContext);
 		registerPtcTools(registerTracked, {
-			getBindings: () => bindings,
+			getBindings,
 			cwd: process.cwd(),
 			surface,
-			getPool: () => pool
+			getPool: () => pool,
+			onToolContext: (ctx) => {
+				toolContext = ctx;
+			}
 		}, surface);
 		if (surface === "codemode_ptc") registerTaskDoor(registerTracked, session, surface);
 		pi.on("turn_end", () => pool.drain());
@@ -5463,18 +5454,30 @@ function registerChildToolsOnly(pi) {
 		})
 	});
 }
-function createBindingTable(pi, ctx, session) {
-	const executeTool = ctx.executeTool;
-	const names = resolveBindingNames(pi.getActiveTools());
+function normalizeToolValue(value) {
+	if (typeof value === "string") return value;
+	if (Array.isArray(value)) return value.map((block) => typeof block === "string" ? block : block?.text ?? JSON.stringify(block)).join("\n");
+	if (value && typeof value === "object") {
+		const obj = value;
+		if (typeof obj.content === "string") return obj.content;
+		if (typeof obj.text === "string") return obj.text;
+	}
+	return value;
+}
+function createBindingTable(pi, session, getToolContext) {
+	const active = pi.getActiveTools();
+	const known = new Set(KNOWN_BINDING_NAMES);
+	const names = resolveBindingNames(active.some((name) => known.has(name)) ? active : pi.getAllTools().map((tool) => tool.name));
 	const table = Object.fromEntries(names.map((name) => [name, async (args, callCtx) => {
-		if (!executeTool) throw new Error(`此 pi 版本不支持程序内工具调用（executeTool 不可用，binding: ${name}）`);
-		const outcome = await executeTool(`ptc/${name}`, name, args);
+		const ctx = getToolContext();
+		if (!ctx?.executeTool) throw new Error(`此 pi 版本没有程序内调用工具的通道（需 pi ≥ 0.99，binding: ${name}）`);
+		const outcome = await ctx.executeTool(name, args, { signal: callCtx.signal });
 		for (const block of outcome.result.content) if (block.type === "image") callCtx.emitImage(block);
 		if (outcome.isError) {
 			const text = outcome.result.content.map((block) => block.type === "text" ? block.text : `[${block.type}]`).join("\n");
 			throw new Error(text || `工具 ${name} 执行失败`);
 		}
-		return outcome.result.structuredContent ?? outcome.result.content;
+		return normalizeToolValue(outcome.result.structuredContent ?? outcome.result.content);
 	}]));
 	const taskBinding = createTaskBinding(session);
 	table[TASK_BINDING_NAME] = (args) => taskBinding.execute(args);

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

@@ -0,0 +1,15 @@
+# 派一个子代理
+
+入口两扇门面（ADR-0006），同参同形（名字随所在平面），只是所在平面不同：
+
+- `pi_task_ptc`：PTC 程序内的 binding，程序里 `tools.pi_task_ptc({...})`
+- `pi_task_codemode`：注册的工具（exposure: codemode，模型不可见），codemode 脚本里 `tools.pi_task_codemode({...})`
+
+参数：`task`（必填，孩子要干的活）、`label`、`wait`、`why`、`agent`、`agentScope`、`model`、`thinkingLevel`、`readOnly` 均已生效（`cwd` 待接）；
+agent 定义里的 `tools / model / thinkingLevel / childReport` 由 frontmatter 钉住。
+
+返回 handle：`{ taskId, label?, status: "queued" }`。默认不等；撞闸（随闸门落地）返回
+`{ status: "rejected", errorMessage }`，不抛异常。
+
+任务建成后在任务记录里排队（满员排队不拒绝，ADR-0010），经
+`ptc_task_list / ptc_task_output / ptc_task_stop` 查/停。

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

@@ -0,0 +1,9 @@
+# 管一个任务
+
+三个工具，有任务记录才出现在模型面前（ADR-0007：可见性 = 有无记录，不是独立开关）：
+
+- `ptc_task_list()`：在飞的全部 + 最近完成的（默认 10 条）
+- `ptc_task_output({ task_id })`：读一条记录（状态/产出/报告）
+- `ptc_task_stop({ task_id, reason? })`：排队中的抽掉（canceled）；在跑的转 stopping
+
+任务记录是派发的唯一痕迹：每次建任务都建记录，前台任务也一样。

package/docs/routes/reach-the-web.md

@@ -0,0 +1,15 @@
+# 上网查资料（web_ds_search，ADR-0001–0049）
+
+搜索能力**只活在被派出的子代理里**（父会话不注册这个工具）——「这条来源靠不靠谱」的判断力在干活的子代理侧。
+
+三动作：
+
+- `search({ query, count? })`：概览（title/url/snippet，默认 10 条）。snippet 是 DeepSeek 自算的短摘要——便宜且不丢事实；长 summary 不经概览给
+- `open({ url })`：抓整页（记忆命中最近结果则免费）
+- `find({ url, pattern })`：页内按正则匹配行（先查记忆）
+
+预算与配额：
+
+- 模型可见文本预算 12,000 字符；超了按排名**整条丢弃** + 告知丢了哪些（要哪个用 open 补抓）——不按字符截断
+- 配额每进程计（`searchMaxCalls`，默认 30 次/进程，0 = 不限；只计成功调用）
+- 开关 `webDsSearch`（`~/.pi/agent/ptc.json`）是布尔，**默认关**：开关关 = 工具不存在；开关开但缺凭据 = 注册但调用返回可读错误

package/docs/routes/report-what-you-did.md

@@ -0,0 +1,9 @@
+# 交报告（child report，旧 ADR-0032）
+
+子代理收工前交一份结构化报告，四样：`summary`（一句话结论）、`findings`（每条 what +
+独立 evidence）、`files_touched`、`usage`（input/output/cost/turns）。散文保留不替换。
+
+- 契约写在孩子的追加 system prompt（唯一处），形式：最终消息**末尾的 fenced JSON 块**
+- 宿主自动解析；`reportChannel` 四值：`tool` = 经 `ptc_child_report` 工具交的（首选通道，已落地）、`prompt-json` = 末尾 fenced JSON 解析到了、`none` = 没交（散文照交但不标可信）、`opted-out` = agent 定义 `childReport:false` 声明免交
+- 报告落 TaskRecord，经 `ptc_task_output` 读得到；没交报告的孩子永远明说，不静默
+- 工具通道（`ptc_child_report`）在子代理进程注册，已是首选；prompt 通道兜底

package/docs/routes/run-a-phased-workflow.md

@@ -0,0 +1,12 @@
+# 分阶段 workflow（ptc_workflow）
+
+`ptc_workflow({ meta: { name, description, phases? }, script, args?, timeoutMs? })`。
+
+script 内额外可用（仅 workflow 面注入）：
+
+- `workflow.log(...)`：阶段内日志
+- `workflow.phase(name)`：阶段标记
+- `workflow.parallel([fn, ...])`：并行执行
+- `workflow.pipeline(items, step)`：顺序流水线
+
+args 必须是可 JSON 序列化的值（进 worker 前校验）。

package/docs/routes/run-one-program.md

@@ -0,0 +1,11 @@
+# 批量调工具的一段程序（ptc_run_code）
+
+`ptc_run_code({ code, description, timeoutMs? })`：code 是 TypeScript 程序体，
+支持顶层 await 与 return。程序内 `tools.<name>(args)` 调工具：
+
+- 绑定表 = 内置名单 ∩ 会话活跃工具（`--tools` 收窄的会话不会拿到被滤掉的绑定）
+- `bash` 不在默认表里，需 opt-in 授权（旧 ADR-0040）
+- 程序返回值是归约后的结果；undefined 返回标记为「无完成值」
+
+默认 2 分钟超时（可经 timeoutMs 下调，上限 10 分钟）。输出超 50 KB 按 pi 截断契约切尾，
+全文写在临时文件、路径进尾注。

package/docs/routes/use-the-built-in-tools.md

@@ -0,0 +1,7 @@
+# 直接用内置工具
+
+单次调用、或每步都需要模型判断的场景（写操作、审批敏感），不要写程序，直接调。
+
+- PTC 程序内：`tools.read / grep / find / ls / edit / write`（绑定表收窄规则见 run-one-program）
+- `bash` 需 opt-in：embedder 的 optIns 参数或 `~/.pi/agent/ptc.json` 的 optInBindings，处处 fail-closed
+- 程序外的逐个直调走 pi 自己的工具调用管线

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ptc-subagents",
-  "version": "6.0.0",
+  "version": "6.0.2",
   "description": "Programmable tool calling (PTC) and subagent fan-out for pi",
   "keywords": [
     "pi",
@@ -20,6 +20,7 @@
   },
   "files": [
     "dist/**/*.js",
+    "docs/routes/**/*.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,7 +31,7 @@
   },
   "scripts": {
     "build": "pnpm -r run build",
-    "prepack": "pnpm run build && rm -rf dist && cp -R packages/entry/dist dist",
+    "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",
     "lint": "oxlint",
     "fmt": "oxfmt",