@zhushanwen/pi-goal 0.16.0 → 0.16.2

package/README.md

@@ -26,15 +26,9 @@ ln -s /path/to/taiji/extensions/universal/goal \
 pi install npm:@zhushanwen/pi-goal
 ```
 
-## 工具激活（deferred）
+## 工具激活
 
-`goal_control` 工具为 `exposure: "deferred"`——不占常驻工具声明，由 pi 内置 `tool_search` 工具检索命中后按需激活。taiji 宿主内开箱即用（宿主启动时已激活 `tool_search`）；独立 pi 使用需在 `<agentDir>/settings.json`（默认 `~/.pi/agent/settings.json`）开启：
-
-```json
-{ "defaultTools": ["+tool_search"] }
-```
-
-`+` 前缀是增量修饰（保留 read/bash/edit/write 默认集）。未开启 `tool_search` 时该工具对模型不可见。
+`goal_control` 工具为 direct 常驻——注册不声明 `exposure` 字段（pi SDK 缺省 `direct`），工具声明随会话常驻、对模型默认可见，无需经 `tool_search` 检索激活，独立 pi 开箱即用。
 
 ## 使用
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-goal",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "description": "Codex-style /goal command for Pi — persistent goal-driven autonomous loop with evidence-based completion, token budget, agent-reported blocking, and steering templates.",
   "type": "module",
   "main": "src/index.ts",
@@ -29,10 +29,10 @@
     "@earendil-works/pi-coding-agent": "^1.0.0",
     "@earendil-works/pi-tui": "^1.0.0",
     "typebox": "1.3.27",
-    "@zhushanwen/pi-pending-notifications": "0.10.1"
+    "@zhushanwen/pi-pending-notifications": "0.11.0"
   },
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.23.0",
+    "@zhushanwen/extension-protocol": "0.24.0",
     "@zhushanwen/pi-extension-logger": "0.6.2",
     "@zhushanwen/pi-session-path": "0.1.0",
     "@zhushanwen/state-machine": "0.2.0"

package/src/__tests__/goal-control-rpc.test.ts

@@ -36,6 +36,8 @@ type ExecuteResult = {
 
 interface CapturedTool {
 	name: string;
+	/** pi SDK 的 exposure 缺省值 "direct"（常驻）——不写字段时 SDK 侧默认（pi-semantics PS-91），本视图可缺省。 */
+	exposure?: string;
 	execute: (
 		toolCallId: string,
 		params: Record<string, unknown>,
@@ -123,6 +125,18 @@ function createViaHandler(
 
 // ── 测试场景 ─────────────────────────────────────────
 
+// exposure 重划终态锚（C-ext-05，2026-10-23 ADR-0136）：goal_control 保持 direct 常驻 =
+// 注册时不写 exposure 字段（SDK 缺省 direct，pi-semantics PS-91）——误写 "deferred" 会把
+// 目标管理入口从模型默认可见集收走（tool_search 才可激活），此处红。
+describe("goal_control SDK 契约 — exposure 注册终态（C-ext-05）", () => {
+	it("direct 常驻：不写 exposure 字段（SDK 缺省 direct）", () => {
+		const { pi } = makeFixture("rpc");
+		const tool = captureTool(pi);
+		expect(tool.name).toBe("goal_control");
+		expect(tool.exposure).toBeUndefined();
+	});
+});
+
 describe("goal_control execute — RPC 模式 tool result 无 __gui__", () => {
 	it("RPC + 有 budget 的 create → details 无 __gui__ 字段（content 仍正常）", async () => {
 		const { pi, ctx } = makeFixture("rpc");

package/src/__tests__/goal-control-summary.test.ts

@@ -53,6 +53,32 @@ describe("buildGoalControlSummary", () => {
 		);
 	});
 
+	it("report_blocked reason 含换行 → summary 归一单行（S-1）", () => {
+		const details = { action: "report_blocked", goalId: "g1", status: "blocked" } as GoalControlDetails;
+		const summary = buildGoalControlSummary(
+			{ action: "report_blocked", reason: "第一行\n第二段\n\n尾行" } as never,
+			details,
+		);
+		expect(summary).toBe("Blocked: 第一行 第二段 尾行");
+	});
+
+	it("report_blocked reason 含 emoji 超长 → 截断不劈代理对（S-3）", () => {
+		const details = { action: "report_blocked", goalId: "g1", status: "blocked" } as GoalControlDetails;
+		// "x🎉" = 3 个 UTF-16 码元；UTF-16 slice(0,40) 会在第 40 码元处劈开 🎉 的代理对。
+		// 码点口径：50 码点 > 40 → 保留前 40 码点 = 20 组完整 "x🎉"
+		const summary = buildGoalControlSummary(
+			{ action: "report_blocked", reason: "x🎉".repeat(25) } as never,
+			details,
+		);
+		expect(summary).not.toContain("\n");
+		// Array.from 按码点切分后，孤立代理项表现为单码元的代理字符
+		const loneSurrogates = Array.from(summary).filter(
+			(ch) => ch.length === 1 && /[\uD800-\uDFFF]/.test(ch),
+		);
+		expect(loneSurrogates).toHaveLength(0);
+		expect(summary).toBe(`Blocked: ${"x🎉".repeat(20)}…`);
+	});
+
 	it("report_blocked 无 reason → 省略后缀", () => {
 		const details = { action: "report_blocked", goalId: "g1", status: "blocked" } as GoalControlDetails;
 		expect(buildGoalControlSummary({ action: "report_blocked" } as never, details)).toBe("Blocked");

package/src/adapters/goal-control-adapter.ts

@@ -33,7 +33,7 @@
 
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import { firstContentText } from "@zhushanwen/extension-protocol";
+import { resultContentText } from "@zhushanwen/extension-protocol";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { type Static, Type } from "typebox";
 
@@ -149,8 +149,21 @@ export interface GoalControlDetails {
 /** 收起态摘要中 reason 的保留长度（超长截断加省略号）。 */
 const BLOCKED_REASON_SUMMARY_CHARS = 40;
 
+/** 多行文本 → 单行摘要文本（换行与连续空白折叠为单空格；plan tool.ts 同模式）。
+ *  details.summary 单行契约见 extension-conventions.md「Tool result details.summary 约定」
+ *  （自由文本 reason 可含 \n，截断前先归一）。 */
+function toSingleLine(text: string): string {
+	return text.replace(/\s+/g, " ").trim();
+}
+
+/** 码点安全截断到上限（超长补省略号；Array.from 按码点切分，emoji 代理对不劈半）。 */
+function elide(text: string, max: number): string {
+	const chars = Array.from(text);
+	return chars.length > max ? chars.slice(0, max).join("") + "…" : text;
+}
+
 /** 收起态一行摘要：create → slug；complete → goalId（complete 的 details 无 slug）；
- *  report_blocked → reason 首段（超长加省略号）。 */
+ *  report_blocked → reason 归一单行后码点安全截断（超长加省略号）。 */
 export function buildGoalControlSummary(
 	params: GoalControlParamsT,
 	details: GoalControlDetails,
@@ -161,11 +174,9 @@ export function buildGoalControlSummary(
 		case "complete":
 			return `Goal completed: ${details.goalId}`;
 		case "report_blocked": {
-			const reason = params.reason?.trim() ?? "";
+			const reason = toSingleLine(params.reason ?? "");
 			if (reason === "") return "Blocked";
-			return reason.length > BLOCKED_REASON_SUMMARY_CHARS
-				? `Blocked: ${reason.slice(0, BLOCKED_REASON_SUMMARY_CHARS)}…`
-				: `Blocked: ${reason}`;
+			return `Blocked: ${elide(reason, BLOCKED_REASON_SUMMARY_CHARS)}`;
 		}
 		default:
 			return "Done";
@@ -367,9 +378,6 @@ export function registerGoalControlTool(pi: ExtensionAPI, session: GoalSession):
 	pi.registerTool({
 		name: "goal_control",
 		label: "Goal Control",
-		// deferred（tool-declaration-slimming D4）：不常驻声明，tool_search 命中即激活；
-		// 迁移写入的 +tool_search 条目（runtime pi-codemode-settings）承载检索入口
-		exposure: "deferred",
 		description: `管理当前会话的目标（goal）。目标用于追踪需要完成验证的复杂工作。动作：create（创建）| complete（完成）| report_blocked（阻塞报告）——各参数必填性与用法见 schema 字段说明，触发纪律见 guidelines。
 
 控制权归属：pause/resume 和 budget 变更由用户经 /goal 命令控制，你不能修改。`,
@@ -459,7 +467,7 @@ export function registerGoalControlTool(pi: ExtensionAPI, session: GoalSession):
 			const d = hasGoalDetails(result) ? result.details : undefined;
 			// 展开态 = content 纯文本（多行详情）；content 缺失时回退折叠形态
 			if (options.expanded) {
-				const content = getContentText(result);
+				const content = resultContentText(result);
 				if (content !== "") return new Text(content, 0, 0);
 			}
 			// 折叠态 = details.summary 一行（dim）；旧 entry 无 summary 时保留原 ◆ 状态行
@@ -471,19 +479,6 @@ export function registerGoalControlTool(pi: ExtensionAPI, session: GoalSession):
 	});
 }
 
-/** unknown 值按字段名安全取值（index-signature 收窄，替代全可选结构断言）。 */
-function fieldValue(v: unknown, key: string): unknown {
-	if (typeof v !== "object" || v === null) return undefined;
-	return (v as Record<string, unknown>)[key];
-}
-
-/** content[0] 的 text 纯文本（content 缺失或非 text 类型时兜底空串）。 */
-function getContentText(result: unknown): string {
-	const content = fieldValue(result, "content");
-	if (!Array.isArray(content)) return "";
-	return firstContentText({ content });
-}
-
 /** 旧形态回退（details 无 summary 的历史 entry）：原 ◆ 状态行，视觉零变化。 */
 function renderLegacyGoalResult(d: GoalControlDetails | undefined, theme: Theme): Text {
 	if (!d) return new Text(theme.fg("dim", "goal_control"), 0, 0);