@zhushanwen/pi-goal 0.14.3 → 0.14.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-goal",
-  "version": "0.14.3",
+  "version": "0.14.5",
   "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,11 @@
     "@earendil-works/pi-coding-agent": "^0.84.4",
     "@earendil-works/pi-tui": "^0.84.4",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.7.3"
+    "@zhushanwen/pi-pending-notifications": "0.7.5"
   },
   "dependencies": {
-    "@taiji/extension-protocol": "0.11.0"
+    "@zhushanwen/extension-protocol": "0.12.0",
+    "@zhushanwen/pi-extension-logger": "0.6.1"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-tui": {

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

@@ -3,7 +3,7 @@
  *
  * 覆盖场景：
  * - RPC 模式 create/complete/report_blocked → details 无 __gui__ 字段（状态展示改由
- *   handle* 内 updateWidget 经 guiSetWidget 推送 M17 对话流 widget 面板）
+ *   handle* 内 updateWidget 经 guiSetWidget 推送 composer 任务托盘的协议 widget 区）
  * - RPC 模式 + session.state = null → 前置 handler throw（分支不可达）
  * - 非 RPC 模式（tui/json/print）→ details 同样无 __gui__，content 文本正常
  *
@@ -11,12 +11,22 @@
  * 不 mock handleCreate：走真实 createGoal 让 session.state 含完整字段（slug/objective/budget），
  * 避免 hand-rolled state 与生产路径不一致。pi/ctx 用最小 fake（对齐 index.test.ts makeFactoryFixture）。
  */
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { describe, expect, it } from "vitest";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { describe, expect, it, vi, beforeEach } from "vitest";
 
 import { registerGoalControlTool, type GoalControlDetails } from "../adapters/goal-control-adapter";
 import { createGoalSession } from "../session";
 
+// ── mock：logger + updateWidget（UI 通道降级用例断言面；其余用例下两者为 no-op，
+//    与真实路径行为等价——fixture 的 setWidget/notify 本就是 no-op）──
+const loggerWarnSpy = vi.hoisted(() => vi.fn());
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+	getLogger: () => ({ warn: loggerWarnSpy, debug: vi.fn(), error: vi.fn() }),
+}));
+vi.mock("../projection/widget", () => ({ updateWidget: vi.fn() }));
+
+import { updateWidget } from "../projection/widget";
+
 // ── Types ─────────────────────────────────────────────
 
 type ExecuteResult = {
@@ -33,6 +43,7 @@ interface CapturedTool {
 		onUpdate: unknown,
 		ctx: ExtensionContext,
 	) => Promise<ExecuteResult>;
+	renderCall: (args: Record<string, unknown>, theme: Theme) => unknown;
 }
 
 // ── Fake pi + ctx（最小化，对齐 index.test.ts 的 makeFactoryFixture）──
@@ -215,3 +226,105 @@ describe("goal_control execute — 非 RPC 模式无 __gui__", () => {
 		expect(result.content[0].text).toContain("Goal created");
 	});
 });
+
+// ── 辅助 UI 通道降级（create/complete/blocked 的 updateWidget/notify 在核心副作用
+//    之后调用，UI 故障不得翻转工具结果）──────────────────
+
+describe("goal_control execute — 辅助 UI 通道失败降级", () => {
+	beforeEach(() => {
+		vi.mocked(updateWidget).mockReset();
+		loggerWarnSpy.mockClear();
+	});
+
+	/** 注册 tool 并同时持有 session 引用（断言持久化后的内存 state）。 */
+	function captureToolWithSession(pi: ExtensionAPI): { tool: CapturedTool; session: ReturnType<typeof createGoalSession> } {
+		let captured: CapturedTool | undefined;
+		const capturePi = {
+			...pi,
+			registerTool(tool: CapturedTool): void {
+				captured = tool;
+			},
+		} as unknown as ExtensionAPI;
+		const session = createGoalSession();
+		registerGoalControlTool(capturePi, session);
+		if (!captured) throw new Error("registerGoalControlTool did not register a tool");
+		return { tool: captured, session };
+	}
+
+	it("create + updateWidget 抛错 → 工具调用仍成功返回、状态已创建（warn 留痕非静默）", async () => {
+		vi.mocked(updateWidget).mockImplementation(() => {
+			throw new Error("widget channel broken");
+		});
+		const { pi, ctx } = makeFixture("rpc");
+		const { tool, session } = captureToolWithSession(pi);
+		const result = await tool.execute(
+			"call-ui-fail",
+			{ action: "create", slug: "ui-fail", objective: "survive ui failure", successCriteria: ["tests pass"] },
+			undefined,
+			undefined,
+			ctx,
+		);
+		// 工具成功返回（UI 异常未上抛翻转结果）
+		expect(result.details.action).toBe("create");
+		expect(result.details.status).toBe("active");
+		expect(result.content[0].text).toContain("Goal created");
+		// 核心副作用不受影响：state 已落盘到 session（内存态可见，persist 已在 createGoal 内完成）
+		expect(session.state?.status).toBe("active");
+		expect(session.state?.objective).toBe("survive ui failure");
+		// 降级留痕：warn 而非静默
+		expect(loggerWarnSpy).toHaveBeenCalledTimes(1);
+		expect(loggerWarnSpy).toHaveBeenCalledWith(
+			expect.stringContaining("goal_control create"),
+			expect.objectContaining({ detail: expect.objectContaining({ err: "widget channel broken" }) }),
+		);
+	});
+
+	it("complete + updateWidget 抛错 → 工具调用仍成功返回（终态已持久化）", async () => {
+		const { pi, ctx } = makeFixture("rpc");
+		const { tool, session } = captureToolWithSession(pi);
+		await createViaHandler(tool, pi, ctx, { slug: "ui-comp", objective: "to complete" });
+		vi.mocked(updateWidget).mockImplementation(() => {
+			throw new Error("widget channel broken");
+		});
+		const result = await tool.execute(
+			"call-ui-comp",
+			{ action: "complete", evidence: "tests green" },
+			undefined,
+			undefined,
+			ctx,
+		);
+		expect(result.details.status).toBe("complete");
+		expect(session.state?.status).toBe("complete");
+		expect(loggerWarnSpy).toHaveBeenCalledWith(
+			expect.stringContaining("goal_control complete"),
+			expect.objectContaining({ detail: expect.objectContaining({ err: "widget channel broken" }) }),
+		);
+	});
+});
+
+// ── renderCall 非法 args 安全渲染（TUI 渲染先于 schema 校验）──
+
+const stubTheme = {
+	fg: (_color: string, text: string) => text,
+	bold: (text: string) => text,
+} as unknown as Theme;
+
+/** 注册 → 捕获 tool → 以给定 args 调 renderCall，返回渲染文本（width 足够宽避免 wrap）。 */
+function renderedCallText(args: unknown): string {
+	const { pi } = makeFixture("rpc");
+	const tool = captureTool(pi);
+	const node = tool.renderCall(args as Record<string, unknown>, stubTheme) as {
+		render: (width: number) => string[];
+	};
+	return node.render(400).join("\n");
+}
+
+describe("renderCall — 非法 args 安全渲染", () => {
+	it("args 为 null → 占位文本，不抛错", () => {
+		expect(renderedCallText(null)).toContain("(invalid args)");
+	});
+
+	it("action 非字符串 → 不抛错，落 report_blocked 回落分支（与原行为一致）", () => {
+		expect(renderedCallText({ action: 42 })).toContain("report_blocked");
+	});
+});

package/src/__tests__/gui.test.ts

@@ -3,7 +3,8 @@
  *
  * 覆盖：
  * - 内容根 = group（透明组合容器）：stats-line（status/turn[+tokens]）+ list-tree（criteria）
- * - meta：title=slug、状态点语义（done/failed/idle/running）、token 进度（取整 + 百分比 + 阈值 severity）
+ * - meta：title=slug、状态点语义（done/failed/idle/running）、token 进度（取整 + 百分比 + 阈值 severity）、
+ *   托盘 icon（显式 'target' key）
  * - successCriteria 逐行 list-tree（不压扁/不截断/无 icon/不编号）
  * - token 展示走 formatTokens（无 budget 分支）
  */
@@ -60,12 +61,23 @@ describe("buildGoalGui（v1.1 meta head 架构）", () => {
 			}),
 		);
 		expect(gui.meta).toEqual({
+			icon: "target",
 			title: "fix-auth",
 			status: "running",
 			progress: { current: 4200, total: 10000, label: "42%", severity: "ok" },
 		});
 	});
 
+	it("meta.icon 推显式 'target' key（协议形状 string；badge 不推，宿主从 progress.label 派生）", () => {
+		const gui = buildGoalGui(makeState({ slug: "fix-auth", budget: { tokenBudget: 10000 } }));
+		// 协议形状：string（宿主按 lucide 名解析）或 { paths }（自定义形状）。
+		// goal 只用 key 形态——与宿主内置 widgetKey 映射（'goal'→Target）同款，
+		// 宿主改映射表也不会换掉 goal 图标。
+		expect(gui.meta!.icon).toBe("target");
+		// badge 留空：托盘缺省从 progress.label 派生同值百分比，推一份会变成双真相源
+		expect(gui.meta!.badge).toBeUndefined();
+	});
+
 	it("tokensUsed 浮点 → meta.progress.current 取整（1454.84…1 不进 UI）", () => {
 		const gui = buildGoalGui(
 			makeState({ tokensUsed: 1454.8400000000001, budget: { tokenBudget: 5000 } }),
@@ -104,7 +116,7 @@ describe("buildGoalGui（v1.1 meta head 架构）", () => {
 				tokensUsed: 3000,
 			}),
 		);
-		expect(gui.meta).toEqual({ title: expect.any(String), status: "running" });
+		expect(gui.meta).toEqual({ icon: "target", title: expect.any(String), status: "running" });
 		const stats = findChildComp(gui, "stats-line");
 		const items = stats.props.items as { label?: string; value?: string }[];
 		expect(items.find((i) => i.label === "tokens")).toMatchObject({ value: "3k" });

package/src/__tests__/ports.test.ts

@@ -16,7 +16,7 @@ import {
 	guiComponent,
 	guiResult,
 	type DualWidgetContent,
-} from "@taiji/extension-protocol";
+} from "@zhushanwen/extension-protocol";
 
 import { buildPorts } from "../adapters/ports";
 

package/src/__tests__/stubs/pi-sdk.ts

@@ -7,9 +7,17 @@ export function StringEnum<T extends readonly string[]>(values: T, _options?: Re
 	return values[0] as T[number];
 }
 
-// Text: pi-tui 的渲染节点 stub（goal-control-adapter renderCall/renderResult 返回值）
+// Text: pi-tui 的渲染节点 stub（goal-control-adapter renderCall/renderResult 返回值）。
+// 承载 content 并提供最小 render（原样单行返回）——renderCall 的非法 args 安全渲染
+// 测试经它断言渲染文本。
 export class Text {
-	constructor(_content: unknown, _x: number, _y: number) {}
+	content: unknown;
+	constructor(content: unknown, _x: number, _y: number) {
+		this.content = content;
+	}
+	render(_width: number): string[] {
+		return [String(this.content)];
+	}
 }
 
 // Pi SDK types used in import chains — re-export as empty

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

@@ -33,6 +33,7 @@
 
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { type Static, Type } from "typebox";
 
 import { SHORT_ID_LENGTH } from "../constants";
@@ -112,6 +113,26 @@ export const GoalControlParams = Type.Object(
 
 export type GoalControlParamsT = Static<typeof GoalControlParams>;
 
+const logger = getLogger("goal");
+
+/**
+ * 辅助 UI 通道降级包装：updateWidget / notify 失败只 warn 留痕不上抛。
+ *
+ * 调用点全部位于核心副作用（createGoal / finalizeAndPersist / persistState）之后——
+ * 状态已落盘，UI 通道故障不能翻转工具结果（与 base-tool-enhance notify.ts 的接入点
+ * 降级同构）。错误串格式化内联（Error message / String）而非复用
+ * @zhushanwen/pi-ext-guards 的 toErrorMessage——不为一个一行 helper 引入运行时依赖。
+ */
+function runUiChannelSafe(action: GoalControlDetails["action"], goalId: string, fn: () => void): void {
+	try {
+		fn();
+	} catch (err) {
+		logger.warn(`goal_control ${action}: ui channel failed; persisted state unaffected`, {
+			detail: { goalId, err: err instanceof Error ? err.message : String(err) },
+		});
+	}
+}
+
 // ── Details（renderResult 数据来源）──────────────────
 
 export interface GoalControlDetails {
@@ -212,14 +233,16 @@ export function handleCreate(
 		// createGoal 内部 active 守卫兜底（理论上上面守卫已挡；防御性）
 		throw new Error("Goal already active. Cannot create a new one.");
 	}
-	updateWidget(session, ports.ui);
 
 	const state = session.state!;
 	// slug fallback：未提供时用 goalId 截断作标题（与 buildGoalGui 一致，避免 [undefined]）
 	const slug = state.slug ?? state.goalId.slice(0, SHORT_ID_LENGTH);
 	const budgetNotice: string[] = [];
 	if (budget.tokenBudget) budgetNotice.push(`Token budget: ${budget.tokenBudget}`);
-	ports.ui.notify([`Goal created [${slug}]: ${objective}`, ...budgetNotice].join("\n"), "info");
+	runUiChannelSafe("create", state.goalId, () => {
+		updateWidget(session, ports.ui);
+		ports.ui.notify([`Goal created [${slug}]: ${objective}`, ...budgetNotice].join("\n"), "info");
+	});
 
 	return { action: "create", goalId: state.goalId, status: state.status, slug };
 }
@@ -251,8 +274,10 @@ export function handleComplete(
 
 	// FR-3.3: 唯一终态序列入口（内部：tickState → finalizeGoal(transition+history) → persist）
 	finalizeAndPersist(state, "complete", ports);
-	updateWidget(session, ports.ui);
-	ports.ui.notify(`Goal completed: ${state.objective}`, "info");
+	runUiChannelSafe("complete", state.goalId, () => {
+		updateWidget(session, ports.ui);
+		ports.ui.notify(`Goal completed: ${state.objective}`, "info");
+	});
 
 	return { action: "complete", goalId: state.goalId, status: state.status };
 }
@@ -289,8 +314,10 @@ export function handleReportBlocked(
 	state.status = transitionStatus(state.status, "blocked");
 
 	persistState(session, ports);
-	updateWidget(session, ports.ui);
-	ports.ui.notify(`Goal blocked: ${reason}`, "warning");
+	runUiChannelSafe("report_blocked", state.goalId, () => {
+		updateWidget(session, ports.ui);
+		ports.ui.notify(`Goal blocked: ${reason}`, "warning");
+	});
 
 	return { action: "report_blocked", goalId: state.goalId, status: state.status };
 }
@@ -376,12 +403,23 @@ export function registerGoalControlTool(pi: ExtensionAPI, session: GoalSession):
 						: `Goal reported blocked.\nGoal ID: ${details.goalId}\nReason: ${params.reason?.trim() ?? ""}`;
 
 			// 状态展示不再进 tool result（GUI 渲染字段已移除）：GUI 由 handle* 内的 updateWidget
-			// 经 guiSetWidget 推送（M17 对话流 widget 面板）。
+			// 经 setWidgetDual 推送（GUI 臂 = guiSetWidget/marker 通道，低层原语不单独调用；
+			// 渲染终点 = composer 任务托盘的协议 widget 区）。
 			return { content: [{ type: "text", text }], details };
 		},
 
 		renderCall(args: Record<string, unknown>, theme: Theme): Text {
-			const action = args.action as string;
+			// TUI 渲染先于 schema 校验（args 是未经 schema 收窄的原始形态）：非对象整体
+			// 走安全占位（不抛错）；action/slug 逐个 typeof 守卫替代裸断言——非法 action
+			// 落 report_blocked 回落分支（与原行为一致）
+			if (typeof args !== "object" || args === null) {
+				return new Text(
+					theme.fg("toolTitle", theme.bold("goal_control ")) + theme.fg("muted", "(invalid args)"),
+					0,
+					0,
+				);
+			}
+			const action = typeof args.action === "string" ? args.action : "";
 			const slug = typeof args.slug === "string" ? args.slug : "";
 			const actionLabel =
 				action === "create"

package/src/adapters/ports.ts

@@ -13,8 +13,8 @@
  */
 
 import type { ExtensionAPI, ExtensionContext, ThemeColor } from "@earendil-works/pi-coding-agent";
-import { setWidgetDual } from "@taiji/extension-protocol";
-import type { GuiContext } from "@taiji/extension-protocol";
+import { setWidgetDual } from "@zhushanwen/extension-protocol";
+import type { GuiContext } from "@zhushanwen/extension-protocol";
 
 import { ENTRY_TYPE, HISTORY_ENTRY_TYPE } from "../persistence";
 import type { MessagingPort, PersistencePort, SessionPort, UiPort } from "../ports";

package/src/engine/__tests__/goal.test.ts

@@ -91,7 +91,7 @@ describe("createGoalState", () => {
 
 describe("E1 守卫：src 内禁止 .status 裸赋值（必须走 transitionStatus 查表）", () => {
 	it("扫描 src/**/*.ts（排除 __tests__）：0 命中", () => {
-		// 正则逐字来自设计 docs/design/ext-simplify-03-goal.md §5.4「E1 守卫设计」，不得自行修改：
+		// 正则逐字来自设计定稿，不得自行修改：
 		// (?![=>]) 排除 ==/===/=>（比较与箭头函数形态）；(?!\s*transitionStatus\b) 放行白名单查表赋值。
 		// 扫描粒度 = 整文件内容（非逐行）：\s* 必须能跨行吃换行，才能排除
 		// `state.status =\n transitionStatus(...)` 这类跨行白名单赋值形态，逐行实现会误报。

package/src/index.ts

@@ -125,7 +125,7 @@ export default function goalExtension(pi: ExtensionAPI) {
 	 * 通道形态（C-ext-06 globalThis slot 惯例）：裸函数直挂——plan 侧使用点以 typeof 守卫
 	 * 读取 `globalThis[Symbol.for("@zhushanwen/pi-goal.goalInit")]`（plan/src/compact.ts）。
 	 * 不挂 pi API 对象：pi 0.84.4 为每个扩展创建独立 ExtensionAPI，挂 pi 对象的字段
-	 * 跨扩展不可见（设计 docs/design/goal-bridge-cross-extension.md §2.3）。
+	 * 跨扩展不可见。
 	 *
 	 * @param objective 目标描述
 	 * @param budget 预算配置，传 undefined 用默认值

package/src/ports.ts

@@ -6,7 +6,7 @@
  * adapter 层提供实现（包装 ctx / pi）。
  */
 
-import type { DualWidgetContent } from "@taiji/extension-protocol";
+import type { DualWidgetContent } from "@zhushanwen/extension-protocol";
 
 import type { GoalRuntimeState } from "./engine/types";
 

package/src/projection/__tests__/widget.test.ts

@@ -284,12 +284,17 @@ describe("updateWidget dual payload（gui 臂）", () => {
 		updateWidget(session, ui);
 		const widgetCall = calls.find((c) => c.method === "setWidget" && c.args[0] === "goal");
 		const payload = widgetCall!.args[1] as {
-			gui: { component: { type: string }; meta: { title: string; progress?: { total: number } } };
+			gui: {
+				component: { type: string };
+				meta: { title: string; progress?: { total: number }; icon?: string | { paths: string[] } };
+			};
 			text: string[];
 		};
 		// v1.1：gui 臂整个 GuiRenderResult（group 组合根 + meta 宿主元数据，head 由壳层渲染）
 		expect(payload.gui.component.type).toBe("group");
 		expect(payload.gui.meta.progress).toMatchObject({ total: 10000 });
+		// 托盘 icon 随 dual payload 的 gui 臂到达宿主（协议形状 = string key）
+		expect(payload.gui.meta.icon).toBe("target");
 		// text 臂同步构造（TUI 渲染行）
 		expect(payload.text.length).toBeGreaterThan(0);
 	});
@@ -301,9 +306,11 @@ describe("updateWidget dual payload（gui 臂）", () => {
 		updateWidget(session, ui);
 		const widgetCall = calls.find((c) => c.method === "setWidget" && c.args[0] === "goal");
 		const payload = widgetCall!.args[1] as {
-			gui: { component: { type: string }; meta: { title: string; progress?: unknown } };
+			gui: { component: { type: string }; meta: { title: string; progress?: unknown; icon?: unknown } };
 		};
 		expect(payload.gui.component.type).toBe("group");
 		expect(payload.gui.meta.progress).toBeUndefined();
+		// icon 与预算无关，两种形态都推（托盘不依赖宿主 widgetKey 映射兜底）
+		expect(payload.gui.meta.icon).toBe("target");
 	});
 });

package/src/projection/gui.ts

@@ -6,7 +6,8 @@
  *
  * 与 projection/widget.ts 的分工：
  * - widget.ts：TUI 模式渲染（ANSI 字符串，经 ctx.ui.setWidget）
- * - gui.ts：RPC 模式渲染（结构化 GuiComponent 描述符，经 guiSetWidget 推送给 M17 对话流 widget 面板）
+ * - gui.ts：RPC 模式渲染（结构化 GuiComponent 描述符，经 setWidgetDual 推送——GUI 臂 =
+ *   guiSetWidget/marker 通道，低层原语不单独调用；渲染终点 = composer 任务托盘的协议 widget 区）
  *
  * 预算阈值经 engine/budget.ts 的 getBudgetSeverity 单源化（H4）：
  * buildGoalGui（percent→severity）与 widget.getBudgetColor（percent→color）共用阈值。
@@ -19,7 +20,7 @@ import {
 	guiResult,
 	type TreeItem,
 	type WidgetMeta,
-} from "@taiji/extension-protocol";
+} from "@zhushanwen/extension-protocol";
 
 import { PERCENT_FACTOR, SHORT_ID_LENGTH } from "../constants";
 import { getBudgetSeverity } from "../engine/budget";
@@ -70,7 +71,7 @@ function metaStatus(status: GoalStatus): WidgetMeta["status"] {
 /**
  * 构造 goal 的 GUI 渲染描述符（v1.1 meta head 架构）。
  *
- * - meta（标题=slug / 状态点 / token 进度）由宿主壳层渲染成唯一 head；
+ * - meta（托盘 icon / 标题=slug / 状态点 / token 进度）由宿主壳层渲染成唯一 head；
  *   有预算时进度计数用百分比 + 预算阈值 severity（70/90 warn/danger 单源）。
  * - 内容根 = group（透明组合容器）：stats-line（status/turn，无预算时补 token
  *   绝对值）+ list-tree（criteria 逐行，无 icon——所有行同 icon 是无信息量装饰，
@@ -114,6 +115,11 @@ export function buildGoalGui(state: GoalRuntimeState): GuiRenderResult {
 	}
 
 	const meta: WidgetMeta = {
+		// 点名 lucide key "target"（与宿主内置 widgetKey 映射 "goal"→Target 同图标）：
+		// 宿主映射只是兜底，extension 显式声明后，宿主调整自己的映射表也不会换掉 goal 的图标。
+		// 不推 badge：托盘 badge 缺省由 progress.label 派生（"42%"），推一份同值字符串会把
+		// 百分比格式变成两个真相源。
+		icon: "target",
 		title: slug,
 		status: metaStatus(state.status),
 		...(hasBudget