@zhushanwen/pi-goal 0.4.1 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-goal",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Codex-style /goal command for Pi — persistent goal-driven autonomous loop with evidence-based completion, token/time budgets, blocked detection, and steering templates.",
   "type": "module",
   "main": "src/index.ts",
@@ -27,6 +27,9 @@
     "@mariozechner/pi-coding-agent": "*",
     "@sinclair/typebox": "*"
   },
+  "dependencies": {
+    "@xyz-agent/extension-protocol": "^0.2.0"
+  },
   "peerDependenciesMeta": {
     "@earendil-works/pi-tui": {
       "optional": true

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

@@ -0,0 +1,79 @@
+// 提示词质量回归：goal_control tool description + runtime 错误文案必须是
+// "可纠正的行为约束器"，而非干巴巴的错误。
+//
+// agent（LLM）唯一能看到的 tool 元信息就是 description + 报错文案。弱模型
+// （如 step-3.7-flash）会在首次调用时省略条件必填字段（create 漏 slug、
+// complete 漏 evidence——complete 需模型主动生成内容，省略动因最强）。
+// description 补完整 JSON 正例 + 结构反例，runtime throw 补 "Correct:" 纠正
+// 正例，能让弱模型在首轮或报错后无需猜测即可对齐。
+//
+// 本测试用源码断言（读 .ts 文件文本）锁定这些约束，防止后续重构把正例/反例
+// 或纠错文案删掉。读源码而非 import，避免 mock 链（goal-control-adapter.ts
+// 依赖 pi-ai/typebox/pi-tui/ExtensionAPI 等值导入）。
+//
+// 模式参考：subagent-workflow/src/interface/__tests__/subagent-tool-prompt.test.ts。
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ADAPTER_SRC = readFileSync(
+	join(__dirname, "../adapters/goal-control-adapter.ts"),
+	"utf-8",
+);
+
+/** 提取 description: `...` 模板字符串的原始内容。 */
+function extractDescription(src: string): string {
+	const m = src.match(/description:\s*`([\s\S]*?)`/);
+	if (!m) throw new Error("description template literal not found");
+	return m[1];
+}
+
+const DESCRIPTION = extractDescription(ADAPTER_SRC);
+
+describe("goal_control description — 含完整 JSON 正例（弱模型首轮误用防御）", () => {
+	it("含 create 正例子串", () => {
+		// create 是弱模型最易漏 slug 的 action；完整 JSON 正例给出可直接复用的形态。
+		expect(DESCRIPTION).toContain('{"action":"create"');
+	});
+
+	it("含 complete 正例子串", () => {
+		// complete 需模型主动生成 evidence，省略动因最强；正例锁定必填字段。
+		expect(DESCRIPTION).toContain('{"action":"complete"');
+	});
+
+	it("含 report_blocked 正例子串", () => {
+		expect(DESCRIPTION).toContain('{"action":"report_blocked"');
+	});
+});
+
+describe("goal_control description — 含参数结构反例（Don't 段）", () => {
+	it("含 Don't 段", () => {
+		expect(DESCRIPTION).toMatch(/Don't/);
+	});
+
+	it("Don't 段含 evidence 结构反例关键词（complete 漏 evidence）", () => {
+		// complete 漏 evidence 是核心失败模式之一；反例文案必须提及 evidence。
+		expect(DESCRIPTION).toMatch(/evidence/);
+	});
+});
+
+describe("goal_control runtime 错误文案 — 含 'Correct:' 纠正正例（≥4 处）", () => {
+	it("源码含 ≥4 处 'Correct:' 纠错文案（4 条 required throw 各一带正例）", () => {
+		// objective/slug/evidence/reason 四条必填 throw 各应带完整 JSON 正例，
+		// 让弱模型在报错后无需猜测即可纠正。读整份源码统计出现次数。
+		const matches = ADAPTER_SRC.match(/Correct:/g) || [];
+		expect(matches.length).toBeGreaterThanOrEqual(4);
+	});
+
+	it("objective 报错带 Correct 正例", () => {
+		expect(ADAPTER_SRC).toMatch(/'objective' is required[\s\S]*?Correct:/);
+	});
+
+	it("evidence 报错带 Correct 正例", () => {
+		expect(ADAPTER_SRC).toMatch(/'evidence' is required[\s\S]*?Correct:/);
+	});
+});

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

@@ -0,0 +1,284 @@
+/**
+ * goal_control tool — execute handler RPC 分支 handler 级测试（W3 Wave __gui__ 协议）
+ *
+ * PR review 补测：registerGoalControlTool execute handler 中
+ *   `if (ctx.mode === "rpc" && session.state)` 分支和 __gui__ 注入。
+ *
+ * 覆盖场景：
+ * - RPC 模式 + session.state 非 null → details.__gui__ 存在（card 或 stats-line）
+ * - RPC 模式 + session.state = null → 跳过路径守卫生效（前置 handler throw，验证分支不可达）
+ * - TUI 模式 → __gui__ 不附加
+ * - RPC 模式 + 有 budget → __gui__ 为 card 类型（progress-bar + stats-line）
+ * - RPC 模式 + 无 budget → __gui__ 为 stats-line 类型
+ *
+ * 范式参考 ask-user/src/__tests__/index.test.ts R-1~R-7（handler 级：注册 → 捕获 → 直接调 execute）。
+ * 不 mock handleCreate：走真实 createGoal 让 session.state 含完整字段（slug/objective/budget），
+ * 避免 hand-rolled state 与生产路径不一致。pi/ctx 用最小 fake（对齐 index.test.ts makeFactoryFixture）。
+ */
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { describe, expect, it } from "vitest";
+
+import { registerGoalControlTool, type GoalControlDetails } from "../adapters/goal-control-adapter";
+import { createGoalSession } from "../session";
+
+// ── Types ─────────────────────────────────────────────
+
+type ExecuteResult = {
+	content: Array<{ type: "text"; text: string }>;
+	details: GoalControlDetails;
+};
+
+interface CapturedTool {
+	name: string;
+	execute: (
+		toolCallId: string,
+		params: Record<string, unknown>,
+		signal: AbortSignal | undefined,
+		onUpdate: unknown,
+		ctx: ExtensionContext,
+	) => Promise<ExecuteResult>;
+}
+
+// ── Fake pi + ctx（最小化，对齐 index.test.ts 的 makeFactoryFixture）──
+
+interface FakeFixture {
+	pi: ExtensionAPI;
+	ctx: ExtensionContext;
+	notifications: Array<{ text: string; level: string }>;
+}
+
+/**
+ * 构造最小 fake pi / ctx。ctx.mode 由调用方覆盖（默认 "rpc"）。
+ *
+ * ports.ts 的 buildPorts 读 ctx.ui.theme.fg/bold、ctx.ui.setWidget/setStatus/notify、
+ * ctx.sessionManager.getEntries、ctx.getContextUsage、ctx.signal、ctx.hasUI——全部 mock。
+ */
+function makeFixture(mode: "rpc" | "tui" | "json" | "print" = "rpc"): FakeFixture {
+	const notifications: Array<{ text: string; level: string }> = [];
+	const pi = {
+		registerTool: () => {},
+		on: () => {},
+		registerCommand: () => {},
+		registerMessageRenderer: () => {},
+		appendEntry: () => {},
+		sendMessage: () => {},
+		sendUserMessage: () => {},
+	} as unknown as ExtensionAPI;
+
+	const ctx = {
+		mode,
+		hasUI: mode === "tui" || mode === "rpc",
+		signal: undefined as AbortSignal | undefined,
+		cwd: "/tmp",
+		getContextUsage: () => null,
+		ui: {
+			notify: (text: string, level: string) => {
+				notifications.push({ text, level });
+			},
+			setStatus: () => {},
+			setWidget: () => {},
+			theme: { fg: (_c: string, t: string) => t, bold: (t: string) => t },
+		},
+		sessionManager: { getEntries: () => [], getBranch: () => undefined },
+	} as unknown as ExtensionContext;
+
+	return { pi, ctx, notifications };
+}
+
+/** 注册 tool 并捕获其 execute handler。 */
+function captureTool(pi: ExtensionAPI): CapturedTool {
+	let captured: CapturedTool | undefined;
+	const capturePi = {
+		...pi,
+		registerTool(tool: CapturedTool): void {
+			captured = tool;
+		},
+	} as unknown as ExtensionAPI;
+	registerGoalControlTool(capturePi, createGoalSession());
+	if (!captured) throw new Error("registerGoalControlTool did not register a tool");
+	return captured;
+}
+
+/** 调一次 create 让 session 持有带 budget 的 active state（走真实路径，state 字段完整）。 */
+function createViaHandler(
+	tool: CapturedTool,
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	params: { slug: string; objective: string; tokenBudget?: number; timeBudgetMinutes?: number },
+): Promise<ExecuteResult> {
+	return tool.execute(
+		"call-1",
+		{ action: "create", ...params },
+		undefined,
+		undefined,
+		ctx,
+	);
+}
+
+// ── 测试场景 ─────────────────────────────────────────
+
+describe("goal_control execute — RPC __gui__ 注入分支", () => {
+	it("RPC + 有 state（有 budget）→ details.__gui__ 存在且为 card 类型", async () => {
+		const { pi, ctx } = makeFixture("rpc");
+		const tool = captureTool(pi);
+		// create 后 session.state 有 tokenBudget → buildGoalGui 走 card 分支
+		const result = await createViaHandler(tool, pi, ctx, {
+			slug: "rpc-card",
+			objective: "rpc card goal",
+			tokenBudget: 10000,
+		});
+		expect(result.details.__gui__).toBeDefined();
+		const gui = result.details.__gui__!;
+		expect(gui.component.type).toBe("card");
+		// card body 含 progress-bar（tokenBudget）+ stats-line
+		const body = gui.component.props.body as Array<{ type: string }>;
+		const types = body.map((c) => c.type);
+		expect(types).toContain("progress-bar");
+		expect(types).toContain("stats-line");
+	});
+
+	it("RPC + 有 state（无 budget）→ details.__gui__ 存在且为 stats-line 类型", async () => {
+		const { pi, ctx } = makeFixture("rpc");
+		const tool = captureTool(pi);
+		// create 不传 budget → buildGoalGui 走 stats-line 分支
+		const result = await createViaHandler(tool, pi, ctx, {
+			slug: "rpc-stats",
+			objective: "rpc stats goal",
+		});
+		expect(result.details.__gui__).toBeDefined();
+		const gui = result.details.__gui__!;
+		expect(gui.component.type).toBe("stats-line");
+		// stats-line items 含 goal/status/turn/tokens
+		const items = gui.component.props.items as Array<{ label: string }>;
+		const labels = items.map((i) => i.label);
+		expect(labels).toContain("goal");
+		expect(labels).toContain("status");
+	});
+
+	it("RPC + session.state = null → 跳过路径守卫生效（前置 handler throw，分支不可达）", async () => {
+		// 源码 line 380: `if (ctx.mode === "rpc" && session.state)` 的 session.state 守卫。
+		// execute 路径上，create 总会 set session.state；complete/report_blocked 前置守卫
+		// 要求 session.state 非 null 否则 throw——所以 session.state=null 时分支条件恒不成立。
+		// 验证：全新 session（state=null）下，complete 前置守卫先 throw，不进 __gui__ 注入逻辑。
+		const { pi, ctx } = makeFixture("rpc");
+		let captured: CapturedTool | undefined;
+		const capturePi = {
+			...pi,
+			registerTool(tool: CapturedTool): void {
+				captured = tool;
+			},
+		} as unknown as ExtensionAPI;
+		registerGoalControlTool(capturePi, createGoalSession());
+		const tool2 = captured!;
+		// complete 在 state=null 时 throw（handleComplete 前置守卫）—— 不会走到 __gui__ 分支
+		await expect(
+			tool2.execute(
+				"id",
+				{ action: "complete", evidence: "x" },
+				undefined,
+				undefined,
+				ctx,
+			),
+		).rejects.toThrow(/not active/i);
+	});
+
+	it("TUI 模式 → __gui__ 不附加（即使有 state）", async () => {
+		const { pi, ctx } = makeFixture("tui");
+		const tool = captureTool(pi);
+		const result = await createViaHandler(tool, pi, ctx, {
+			slug: "tui-no-gui",
+			objective: "tui goal",
+			tokenBudget: 5000,
+		});
+		// TUI 模式不注入 __gui__
+		expect(result.details.__gui__).toBeUndefined();
+		// 但 content 仍正常
+		expect(result.content[0]!.text).toContain("Goal created");
+	});
+
+	it("RPC + complete 动作 → __gui__ 也附加（用终态 state 渲染）", async () => {
+		// 验证 __gui__ 注入不限于 create：complete 后 session.state 仍非 null（status=complete）
+		const { pi, ctx } = makeFixture("rpc");
+		const tool = captureTool(pi);
+		// 先 create（建 active state）
+		await createViaHandler(tool, pi, ctx, { slug: "comp", objective: "to complete" });
+		// 再 complete —— session.state.status=complete，buildGoalGui 走 card variant=success
+		const result = await tool.execute(
+			"call-2",
+			{ action: "complete", evidence: "tests green" },
+			undefined,
+			undefined,
+			ctx,
+		);
+		expect(result.details.__gui__).toBeDefined();
+		expect(result.details.status).toBe("complete");
+		const gui = result.details.__gui__!;
+		// 无 budget → stats-line
+		expect(gui.component.type).toBe("stats-line");
+		const items = gui.component.props.items as Array<{ label: string; value: string }>;
+		const statusItem = items.find((i) => i.label === "status");
+		expect(statusItem!.value).toBe("complete");
+	});
+
+	it("RPC + report_blocked 动作 → __gui__ 附加，status severity danger", async () => {
+		const { pi, ctx } = makeFixture("rpc");
+		const tool = captureTool(pi);
+		await createViaHandler(tool, pi, ctx, { slug: "blk", objective: "to block" });
+		const result = await tool.execute(
+			"call-3",
+			{ action: "report_blocked", reason: "stuck on dependency" },
+			undefined,
+			undefined,
+			ctx,
+		);
+		expect(result.details.__gui__).toBeDefined();
+		expect(result.details.status).toBe("blocked");
+		// 无 budget → stats-line；blocked status severity=danger
+		const gui = result.details.__gui__!;
+		expect(gui.component.type).toBe("stats-line");
+		const items = gui.component.props.items as Array<{ label: string; severity?: string }>;
+		const statusItem = items.find((i) => i.label === "status");
+		expect(statusItem!.severity).toBe("danger");
+	});
+
+	it("RPC + 有 time budget → __gui__ card 含 time progress-bar", async () => {
+		const { pi, ctx } = makeFixture("rpc");
+		const tool = captureTool(pi);
+		const result = await createViaHandler(tool, pi, ctx, {
+			slug: "time-budget",
+			objective: "time boxed",
+			timeBudgetMinutes: 30,
+		});
+		const gui = result.details.__gui__!;
+		expect(gui.component.type).toBe("card");
+		const body = gui.component.props.body as Array<{ type: string; props: { label?: string } }>;
+		const timeBar = body.find((c) => c.type === "progress-bar" && c.props.label === "time");
+		expect(timeBar).toBeDefined();
+	});
+});
+
+// ── 边界：非 RPC 模式（json/print）也不注入 __gui__ ──
+
+describe("goal_control execute — 非 RPC 模式不注入 __gui__", () => {
+	it("json 模式 → __gui__ 不附加", async () => {
+		const { pi, ctx } = makeFixture("json");
+		const tool = captureTool(pi);
+		const result = await createViaHandler(tool, pi, ctx, {
+			slug: "json-mode",
+			objective: "json goal",
+			tokenBudget: 1000,
+		});
+		expect(result.details.__gui__).toBeUndefined();
+	});
+
+	it("print 模式 → __gui__ 不附加", async () => {
+		const { pi, ctx } = makeFixture("print");
+		const tool = captureTool(pi);
+		const result = await createViaHandler(tool, pi, ctx, {
+			slug: "print-mode",
+			objective: "print goal",
+			tokenBudget: 1000,
+		});
+		expect(result.details.__gui__).toBeUndefined();
+	});
+});

package/src/__tests__/gui.test.ts

@@ -0,0 +1,195 @@
+/**
+ * buildGoalGui 测试 — goal 的 GUI 渲染描述符构造（W3 Wave __gui__ 协议）
+ *
+ * 覆盖：
+ * - 有 tokenBudget/timeBudget → card(progress-bar + stats-line)
+ * - 预算消耗阈值（≥70% warn, ≥90% danger）
+ * - 状态→severity/variant 映射
+ * - 无 budget → stats-line 摘要
+ */
+import { describe, expect, it } from "vitest";
+
+import { buildGoalGui } from "../adapters/goal-control-adapter";
+import { createGoalState } from "../engine/goal";
+import type { GoalRuntimeState } from "../engine/types";
+
+function makeState(overrides: Partial<GoalRuntimeState> = {}): GoalRuntimeState {
+	return {
+		...createGoalState("test"),
+		...overrides,
+	};
+}
+
+describe("buildGoalGui", () => {
+	it("有 tokenBudget → card 含 progress-bar + stats-line", () => {
+		const gui = buildGoalGui(
+			makeState({
+				tokensUsed: 4200,
+				budget: { tokenBudget: 10000 },
+				currentTurnIndex: 3,
+			}),
+		);
+		expect(gui.v).toBe(1);
+		expect(gui.component.type).toBe("card");
+		const body = gui.component.props.body as { type: string; props: Record<string, unknown> }[];
+		// body[0] = progress-bar(tokens), body[1] = stats-line
+		const tokenBar = body.find((c) => c.type === "progress-bar")!;
+		expect(tokenBar.props).toMatchObject({ current: 4200, total: 10000, severity: "ok" });
+		const stats = body.find((c) => c.type === "stats-line")!;
+		expect(stats.props.items).toContainEqual(expect.objectContaining({ label: "status", value: "active" }));
+	});
+
+	it("token 消耗 ≥90% → severity danger", () => {
+		const gui = buildGoalGui(
+			makeState({
+				tokensUsed: 9500,
+				budget: { tokenBudget: 10000 },
+			}),
+		);
+		const body = gui.component.props.body as { type: string; props: Record<string, unknown> }[];
+		const tokenBar = body.find((c) => c.type === "progress-bar")!;
+		expect(tokenBar.props.severity).toBe("danger");
+	});
+
+	it("token 消耗 ≥70% → severity warn", () => {
+		const gui = buildGoalGui(
+			makeState({
+				tokensUsed: 7500,
+				budget: { tokenBudget: 10000 },
+			}),
+		);
+		const body = gui.component.props.body as { type: string; props: Record<string, unknown> }[];
+		const tokenBar = body.find((c) => c.type === "progress-bar")!;
+		expect(tokenBar.props.severity).toBe("warn");
+	});
+
+	it("无 budget → stats-line 摘要", () => {
+		const gui = buildGoalGui(
+			makeState({
+				currentTurnIndex: 5,
+				tokensUsed: 3000,
+			}),
+		);
+		expect(gui.component.type).toBe("stats-line");
+		const items = gui.component.props.items as { label?: string }[];
+		const labels = items.map((i) => i.label);
+		expect(labels).toContain("goal");
+		expect(labels).toContain("status");
+		expect(labels).toContain("turn");
+		expect(labels).toContain("tokens");
+	});
+
+	it("blocked 状态 → card variant danger", () => {
+		const gui = buildGoalGui(
+			makeState({
+				status: "blocked",
+				budget: { tokenBudget: 10000 },
+			}),
+		);
+		expect(gui.component.type).toBe("card");
+		expect(gui.component.props.variant).toBe("danger");
+	});
+
+	it("complete 状态 → card variant success", () => {
+		const gui = buildGoalGui(
+			makeState({
+				status: "complete",
+				budget: { tokenBudget: 10000 },
+			}),
+		);
+		expect(gui.component.type).toBe("card");
+		expect(gui.component.props.variant).toBe("success");
+	});
+
+	it("time 进度条：≥90% → danger", () => {
+		const gui = buildGoalGui(
+			makeState({
+				timeUsedSeconds: 5 * 60 + 1, // 5.01 min / 5 min budget
+				budget: { timeBudgetMinutes: 5 },
+			}),
+		);
+		const body = gui.component.props.body as { type: string; props: { label?: string; severity?: string } }[];
+		const timeBar = body.find((c) => c.type === "progress-bar" && c.props.label === "time")!;
+		expect(timeBar.props.severity).toBe("danger");
+	});
+
+	it("slug 缺省 → header 用 goalId 前 8 字符", () => {
+		const state = makeState({ slug: undefined, budget: { tokenBudget: 10000 } });
+		const gui = buildGoalGui(state);
+		expect(gui.component.props.header).toBe(state.goalId.slice(0, 8));
+	});
+
+	// ── S#2: statusSeverity 完整覆盖 ──
+
+	it("budget_limited 状态 → status severity danger（S#2）", () => {
+		const gui = buildGoalGui(makeState({ status: "budget_limited", budget: { tokenBudget: 10000 } }));
+		const body = gui.component.props.body as { type: string; props: { items: Array<{ label: string; severity: string }> } }[];
+		const stats = body.find((c) => c.type === "stats-line")!;
+		const statusItem = stats.props.items.find((i) => i.label === "status")!;
+		expect(statusItem.severity).toBe("danger");
+	});
+
+	it("time_limited 状态 → status severity danger（S#2）", () => {
+		const gui = buildGoalGui(makeState({ status: "time_limited", budget: { tokenBudget: 10000 } }));
+		const body = gui.component.props.body as { type: string; props: { items: Array<{ label: string; severity: string }> } }[];
+		const stats = body.find((c) => c.type === "stats-line")!;
+		const statusItem = stats.props.items.find((i) => i.label === "status")!;
+		expect(statusItem.severity).toBe("danger");
+	});
+
+	it("cancelled 状态 → status severity danger（S#2）", () => {
+		const gui = buildGoalGui(makeState({ status: "cancelled", budget: { tokenBudget: 10000 } }));
+		const body = gui.component.props.body as { type: string; props: { items: Array<{ label: string; severity: string }> } }[];
+		const stats = body.find((c) => c.type === "stats-line")!;
+		const statusItem = stats.props.items.find((i) => i.label === "status")!;
+		expect(statusItem.severity).toBe("danger");
+	});
+
+	it("paused 状态 → status severity warn（S#2）", () => {
+		const gui = buildGoalGui(makeState({ status: "paused", budget: { tokenBudget: 10000 } }));
+		const body = gui.component.props.body as { type: string; props: { items: Array<{ label: string; severity: string }> } }[];
+		const stats = body.find((c) => c.type === "stats-line")!;
+		const statusItem = stats.props.items.find((i) => i.label === "status")!;
+		expect(statusItem.severity).toBe("warn");
+	});
+
+	// ── S#14: 阈值边界精确值 ──
+
+	it("token 消耗正好 90% → severity danger（边界 ≥，S#14）", () => {
+		const gui = buildGoalGui(makeState({ tokensUsed: 9000, budget: { tokenBudget: 10000 } }));
+		const body = gui.component.props.body as { type: string; props: { label?: string; severity?: string } }[];
+		const tokenBar = body.find((c) => c.type === "progress-bar" && c.props.label === "tokens")!;
+		expect(tokenBar.props.severity).toBe("danger");
+	});
+
+	it("token 消耗正好 70% → severity warn（边界 ≥，S#14）", () => {
+		const gui = buildGoalGui(makeState({ tokensUsed: 7000, budget: { tokenBudget: 10000 } }));
+		const body = gui.component.props.body as { type: string; props: { label?: string; severity?: string } }[];
+		const tokenBar = body.find((c) => c.type === "progress-bar" && c.props.label === "tokens")!;
+		expect(tokenBar.props.severity).toBe("warn");
+	});
+
+	it("time 消耗正好 70% → severity warn（边界 ≥，S#14）", () => {
+		const gui = buildGoalGui(makeState({ timeUsedSeconds: 7 * 60, budget: { timeBudgetMinutes: 10 } }));
+		const body = gui.component.props.body as { type: string; props: { label?: string; severity?: string } }[];
+		const timeBar = body.find((c) => c.type === "progress-bar" && c.props.label === "time")!;
+		expect(timeBar.props.severity).toBe("warn");
+	});
+
+	// ── I#1: tokenBudget=0 口径统一 ──
+
+	it("tokenBudget=0 → 无 progress-bar（口径 >0，I#1）", () => {
+		const gui = buildGoalGui(makeState({ tokensUsed: 0, budget: { tokenBudget: 0 } }));
+		// tokenBudget=0 → hasBudget=false → 走无 budget 分支的 stats-line
+		expect(gui.component.type).toBe("stats-line");
+	});
+
+	// ── 无 budget 分支的 status severity ──
+
+	it("无 budget 时 status severity 正确（S#14）", () => {
+		const gui = buildGoalGui(makeState({ status: "active" }));
+		const items = gui.component.props.items as Array<{ label: string; severity?: string }>;
+		const statusItem = items.find((i) => i.label === "status");
+		expect(statusItem!.severity).toBe("ok");
+	});
+});

package/src/__tests__/service.test.ts

@@ -141,8 +141,8 @@ describe("applyEvent — 简单事件", () => {
 				usage: { input: 100, output: 50, cacheRead: 20 },
 			},
 		}, makeFakePorts());
-		// accumulateTokens: max(100 - 20, 0) + 50 = 130
-		expect(session.state.tokensUsed).toBe(before + 130);
+		// accumulateTokens: 100×1 + 20×0.02 + 50×2 = 200.4（加权口径，对齐 workflow 包）
+		expect(session.state.tokensUsed).toBe(before + 200.4);
 	});
 
 	it("message_end 忽略非 assistant 消息", () => {

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

@@ -24,13 +24,15 @@
  * 错误处理：用 throw new Error（CLAUDE.md Tool 设计规范），不返回错误成功模式。
  */
 
-import { StringEnum } from "@mariozechner/pi-ai";
+import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext, Theme } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
+import { type GuiComponent, guiComponent, type GuiRenderResult,guiResult } from "@xyz-agent/extension-protocol";
 import { type Static, Type } from "typebox";
 
+import { BUDGET_RATIO_HIGH, BUDGET_RATIO_LOW, SECONDS_PER_MINUTE, SHORT_ID_LENGTH } from "../constants";
 import { isActiveStatus, isTerminalStatus, transitionStatus } from "../engine/goal";
-import type { BudgetConfig, GoalStatus } from "../engine/types";
+import type { BudgetConfig, GoalRuntimeState, GoalStatus } from "../engine/types";
 import { updateWidget } from "../projection/widget";
 import { createGoal, finalizeAndPersist, persistState, type ServicePorts, tickState } from "../service";
 import type { GoalSession } from "../session";
@@ -90,6 +92,8 @@ export interface GoalControlDetails {
 	goalId: string;
 	status: GoalStatus;
 	slug?: string;
+	/** RPC 模式下的 GUI 渲染描述符（progress-bar 预算进度）。TUI 模式无此字段。 */
+	__gui__?: GuiRenderResult;
 }
 
 // ── 业务 handler（契约对齐 §3，可测：fake ports）──────
@@ -114,11 +118,15 @@ export function handleCreate(
 ): GoalControlDetails {
 	const objective = params.objective?.trim();
 	if (!objective) {
-		throw new Error("'objective' is required for create. Describe the concrete objective to pursue.");
+		throw new Error(
+			"'objective' is required for create. Describe the concrete objective to pursue. Correct: {\"action\":\"create\",\"slug\":\"<kebab-case>\",\"objective\":\"<concrete objective>\"}",
+		);
 	}
 	const slug = params.slug?.trim();
 	if (!slug) {
-		throw new Error("'slug' is required for create. Provide a short kebab-case identifier (e.g. 'refactor-auth').");
+		throw new Error(
+			"'slug' is required for create. Provide a short kebab-case identifier (e.g. 'refactor-auth'). Correct: {\"action\":\"create\",\"slug\":\"refactor-auth\",\"objective\":\"<concrete objective>\"}",
+		);
 	}
 
 	// D25 严格守卫：非终态旧 goal（active/paused/blocked）→ 拒绝创建（防静默覆盖未完成工作）
@@ -177,7 +185,9 @@ export function handleComplete(
 	}
 	const evidence = params.evidence?.trim();
 	if (!evidence) {
-		throw new Error("'evidence' is required for complete. Provide concrete completion evidence.");
+		throw new Error(
+			"'evidence' is required for complete. Provide concrete completion evidence. Correct: {\"action\":\"complete\",\"evidence\":\"Modified src/auth.ts; pnpm test auth passed (12/12); tsc --noEmit clean.\"}",
+		);
 	}
 
 	// FR-3.3: 唯一终态序列入口（内部：tickState → finalizeGoal(transition+history) → persist）
@@ -206,7 +216,9 @@ export function handleReportBlocked(
 	}
 	const reason = params.reason?.trim();
 	if (!reason) {
-		throw new Error("'reason' is required for report_blocked. Describe the blocking condition.");
+		throw new Error(
+			"'reason' is required for report_blocked. Describe the blocking condition. Correct: {\"action\":\"report_blocked\",\"reason\":\"<blocker + what was tried (at least 3 approaches)>\"}",
+		);
 	}
 
 	state.lastBlockerReason = reason;
@@ -221,6 +233,124 @@ export function handleReportBlocked(
 	return { action: "report_blocked", goalId: state.goalId, status: state.status };
 }
 
+// ── GUI 渲染描述符构造 ───────────────────────────────
+
+/**
+ * 按 GoalStatus 映射 stats-line severity（S#2）。
+ *
+ *   active/complete → ok（正常运行/成功完成）
+ *   paused          → warn（暂停可恢复）
+ *   blocked         → danger（阻塞需干预）
+ *   budget_limited/time_limited/cancelled → danger（预算耗尽/取消，错误终态）
+ *
+ * 对齐 projection/widget.ts 的 getBudgetColor 语义——终态预算耗尽渲染为 error。
+ */
+/** renderResult 的 result 是否含 details 字段（类型守卫，替代全可选结构断言 as {details?}）。
+ * 收紧：除检查 "details" in r 外，还验证其值为 object 或 undefined（防 details 是 string/number
+ * 时下游读 d.status 得到 undefined 却被类型系统当作 GoalControlDetails）。 */
+function hasGoalDetails(r: unknown): r is { details?: GoalControlDetails } {
+	if (typeof r !== "object" || r === null || !("details" in r)) return false;
+	const d = (r as Record<string, unknown>).details;
+	return d === undefined || typeof d === "object";
+}
+
+function goalStatusSeverity(status: GoalStatus): "ok" | "warn" | "danger" {
+	switch (status) {
+		case "active":
+		case "complete":
+			return "ok";
+		case "paused":
+			return "warn";
+		case "blocked":
+		case "budget_limited":
+		case "time_limited":
+		case "cancelled":
+			return "danger";
+	}
+}
+
+/**
+ * 构造 goal 的 GUI 渲染描述符（RPC 模式下放进 details.__gui__）。
+ *
+ * 逻辑参考 projection/widget.ts 的 renderWidgetLines 预算计算，但此处只构造
+ * 结构化数据（GuiComponent），不做 ANSI 渲染。
+ *
+ * - 有 tokenBudget 或 timeBudgetMinutes → card(progress-bar + stats-line) 展示预算消耗
+ * - 无 budget → stats-line 展示状态摘要
+ */
+export function buildGoalGui(state: GoalRuntimeState): GuiRenderResult {
+	const slug = state.slug ?? state.goalId.slice(0, SHORT_ID_LENGTH);
+	// statusSeverity 按 GoalStatus 完整覆盖（S#2）：
+	//   active/complete → ok；blocked → danger；paused → warn；
+	//   budget_limited/time_limited/cancelled → danger（预算耗尽/取消是错误终态）
+	const statusSeverity = goalStatusSeverity(state.status);
+
+	// hasBudget 与进度条判定统一口径：用 > 0 而非 truthy（I#1：tokenBudget=0 不应触发 card 容器）
+	const hasBudget = (state.budget.tokenBudget ?? 0) > 0 || (state.budget.timeBudgetMinutes ?? 0) > 0;
+
+	if (hasBudget) {
+		const body: GuiComponent[] = [];
+		// token 进度条（>0 判定，与 hasBudget 口径一致）
+		const tokenBudget = state.budget.tokenBudget;
+		if ((tokenBudget ?? 0) > 0) {
+			const tb = tokenBudget!;
+			const tokenPct = state.tokensUsed / tb;
+			body.push(
+				guiComponent("progress-bar", {
+					label: "tokens",
+					current: state.tokensUsed,
+					total: tb,
+					unit: "tok",
+					severity: tokenPct >= BUDGET_RATIO_HIGH ? "danger" : tokenPct >= BUDGET_RATIO_LOW ? "warn" : "ok",
+				}),
+			);
+		}
+		// time 进度条（>0 判定，与 hasBudget 口径一致）
+		const timeBudgetMinutes = state.budget.timeBudgetMinutes;
+		if ((timeBudgetMinutes ?? 0) > 0) {
+			const timeBudgetSec = timeBudgetMinutes! * SECONDS_PER_MINUTE;
+			const timePct = state.timeUsedSeconds / timeBudgetSec;
+			body.push(
+				guiComponent("progress-bar", {
+					label: "time",
+					current: state.timeUsedSeconds,
+					total: timeBudgetSec,
+					unit: "s",
+					severity: timePct >= BUDGET_RATIO_HIGH ? "danger" : timePct >= BUDGET_RATIO_LOW ? "warn" : "ok",
+				}),
+			);
+		}
+		// 状态 + turn 统计行
+		body.push(
+			guiComponent("stats-line", {
+				items: [
+					{ label: "status", value: state.status, severity: statusSeverity },
+					{ label: "turn", value: String(state.currentTurnIndex) },
+				],
+			}),
+		);
+		return guiResult(
+			guiComponent("card", {
+				variant: state.status === "blocked" ? "danger" : state.status === "complete" ? "success" : "default",
+				header: slug,
+				body,
+			}),
+		);
+	}
+
+	// 无 budget：stats-line 摘要
+	return guiResult(
+		guiComponent("stats-line", {
+			items: [
+				{ label: "goal", value: slug },
+				{ label: "status", value: state.status, severity: statusSeverity },
+				{ label: "turn", value: String(state.currentTurnIndex) },
+				{ label: "tokens", value: String(state.tokensUsed) },
+			],
+		}),
+	);
+}
+
 // ── Tool 注册 ────────────────────────────────────────
 
 export function registerGoalControlTool(pi: ExtensionAPI, session: GoalSession): void {
@@ -228,7 +358,22 @@ export function registerGoalControlTool(pi: ExtensionAPI, session: GoalSession):
 		name: "goal_control",
 		label: "Goal Control",
 		description:
-			"Manage the goal for this thread.\n\nActions:\n- create: start a new goal. Requires `slug` (a short kebab-case identifier you generate) and `objective` (the full description). Only use when the user explicitly asks to start a goal; do not infer goals from ordinary tasks. Fails if a goal is already active/paused/blocked (use /goal resume or /goal clear first).\n- complete: mark the active goal complete. Requires `evidence` with concrete proof (files/tests/commands). Recommend finishing all todos (including verification todos) first, but you decide.\n- report_blocked: mark the active goal blocked by a real blocker. Requires `reason` describing the block and what was tried. Only after genuine exhaustion of alternatives.",
+			`Manage the goal for this thread.
+
+Actions:
+- create: start a new goal. Requires 'slug' (a short kebab-case identifier you generate) and 'objective' (the full description). Only use when the user explicitly asks to start a goal; do not infer goals from ordinary tasks. Fails if a goal is already active/paused/blocked (use /goal resume or /goal clear first).
+- complete: mark the active goal complete. Requires 'evidence' with concrete proof (files/tests/commands). Recommend finishing all todos (including verification todos) first, but you decide.
+- report_blocked: mark the active goal blocked by a real blocker. Requires 'reason' describing the block and what was tried. Only after genuine exhaustion of alternatives.
+
+Examples:
+{"action":"create","slug":"refactor-auth","objective":"Refactor the auth module to use JWT and add integration tests"}
+{"action":"complete","evidence":"Modified src/auth.ts; pnpm test auth passed (12/12); tsc --noEmit clean."}
+{"action":"report_blocked","reason":"Blocked: DB migration API changed mid-task (tried: regenerate client, pin old version, rewrite queries)."}
+
+Don't:
+- create without 'slug': {"action":"create","objective":"..."} — slug is required, generate a kebab-case id.
+- complete without 'evidence': {"action":"complete"} — must provide concrete completion proof (files/tests/commands).
+- complete when no goal is active — create or resume one first (fails with 'Goal mode not active').`,
 		promptSnippet:
 			"Use goal_control to manage the thread goal: create (with slug + objective, only when user asks) or complete (with evidence) or report_blocked (with reason, after trying alternatives).",
 		executionMode: "sequential",
@@ -262,6 +407,11 @@ export function registerGoalControlTool(pi: ExtensionAPI, session: GoalSession):
 					: details.action === "complete"
 						? `Goal completed.\nGoal ID: ${details.goalId}`
 						: `Goal reported blocked.\nGoal ID: ${details.goalId}\nReason: ${params.reason?.trim() ?? ""}`;
+
+			// RPC 模式下附加 __gui__（用展开避免 details 来自 frozen 对象时加字段失败）
+			if (ctx.mode === "rpc" && session.state) {
+				return { content: [{ type: "text", text }], details: { ...details, __gui__: buildGoalGui(session.state) } };
+			}
 			return { content: [{ type: "text", text }], details };
 		},
 
@@ -278,7 +428,7 @@ export function registerGoalControlTool(pi: ExtensionAPI, session: GoalSession):
 		},
 
 		renderResult(result: unknown, _options: { expanded: boolean }, theme: Theme): Text {
-			const d = (result as { details?: GoalControlDetails }).details;
+			const d = hasGoalDetails(result) ? result.details : undefined;
 			if (!d) return new Text(theme.fg("dim", "goal_control"), 0, 0);
 			const statusColor =
 				d.status === "active"

package/src/constants.ts

@@ -24,6 +24,7 @@ export const BUDGET_PERCENT_LOW = 70;    // widget 颜色变黄
 // ── 长度/数量上限 ───────────────────────────────────
 
 export const UPDATE_PREFIX_LENGTH = 7;        // "update ".length
+export const SHORT_ID_LENGTH = 8;             // goalId 截取前 8 字符作短标识（GUI 显示 fallback）
 
 // ── 百分比换算因子 ──────────────────────────────────
 

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

@@ -38,11 +38,13 @@ const makeState = (overrides: Partial<GoalRuntimeState> = {}): GoalRuntimeState
 // ── accumulateTokens（FR-8.6）─────────────────────────
 
 describe("accumulateTokens", () => {
-	it("input/output 有 → max(input-cacheRead,0)+output", () => {
-		expect(accumulateTokens(1000, { input: 100, output: 50, cacheRead: 20 })).toBe(1130);
+	it("input/output 有 → 加权 input×1 + cacheRead×0.02 + output×2", () => {
+		// 100×1 + 20×0.02 + 50×2 = 200.4；1000 + 200.4 = 1200.4
+		expect(accumulateTokens(1000, { input: 100, output: 50, cacheRead: 20 })).toBe(1200.4);
 	});
-	it("cacheRead > input → max=0", () => {
-		expect(accumulateTokens(1000, { input: 50, output: 30, cacheRead: 100 })).toBe(1030);
+	it("cacheRead > input → 加权后 input 仍计全量（不折底为 0）", () => {
+		// 50×1 + 100×0.02 + 30×2 = 112；1000 + 112 = 1112
+		expect(accumulateTokens(1000, { input: 50, output: 30, cacheRead: 100 })).toBe(1112);
 	});
 	it("input=0 output=0 → fallback totalTokens", () => {
 		expect(accumulateTokens(1000, { totalTokens: 200 })).toBe(1200);
@@ -50,8 +52,8 @@ describe("accumulateTokens", () => {
 	it("全空 → 不累加", () => {
 		expect(accumulateTokens(1000, {})).toBe(1000);
 	});
-	it("无 cacheRead → 视为 0", () => {
-		expect(accumulateTokens(0, { input: 100, output: 50 })).toBe(150);
+	it("无 cacheRead → 视为 0（加权 100×1 + 0×0.02 + 50×2 = 200）", () => {
+		expect(accumulateTokens(0, { input: 100, output: 50 })).toBe(200);
 	});
 });
 

package/src/engine/budget.ts

@@ -18,6 +18,11 @@ const PERCENT_FACTOR = 100;
 const SECONDS_PER_MINUTE = 60;
 const MS_PER_SECOND = 1000;
 
+// 加权系数（与 @zhushanwen/pi-subagent-workflow Budget.consume 对齐，ADR-030 token 口径统一）
+const INPUT_WEIGHT = 1;
+const CACHE_READ_WEIGHT = 0.02;
+const OUTPUT_WEIGHT = 2;
+
 // ── 类型 ────────────────────────────────────────────
 
 export interface TokenUsage {
@@ -50,7 +55,10 @@ export function accumulateTokens(currentTokensUsed: number, usage: TokenUsage):
 	const output = usage.output ?? 0;
 	const cacheRead = usage.cacheRead ?? 0;
 	if (input > 0 || output > 0) {
-		return currentTokensUsed + Math.max(input - cacheRead, 0) + output;
+		// 加权口径：input×1 + cacheRead×0.02 + output×2
+		// 与 @zhushanwen/pi-subagent-workflow Budget.consume() 对齐（ADR-030 token 口径统一），
+		// 修复旧公式 max(input-cacheRead,0)+output 在长 session 中 cacheRead>0 时低估预算消耗
+		return currentTokensUsed + input * INPUT_WEIGHT + cacheRead * CACHE_READ_WEIGHT + output * OUTPUT_WEIGHT;
 	}
 	return currentTokensUsed + (usage.totalTokens ?? 0);
 }