@zhushanwen/pi-goal 0.5.0 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-goal",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "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",
@@ -24,7 +24,7 @@
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-tui": "*",
-    "@mariozechner/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": "*",
     "@sinclair/typebox": "*"
   },
   "dependencies": {

package/src/__tests__/command-adapter.test.ts

@@ -9,7 +9,7 @@
  * 用 fake pi + fake ctx（不 import Pi SDK 真实实现）。
  * handleGoalCommand(pi, session, args, ctx) → Promise<void>。
  */
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { describe, expect, it } from "vitest";
 
 import { handleGoalCommand } from "../adapters/command-adapter";

package/src/__tests__/event-adapter.test.ts

@@ -9,7 +9,7 @@
  *
  * 用 fake pi + fake ctx（不 import Pi SDK）。handler 签名 (pi, session, ctx) → void/result。
  */
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { describe, expect, it, vi } from "vitest";
 
 import { handleAgentEnd } from "../adapters/event-handlers/agent-end";

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

@@ -15,7 +15,7 @@
  * 不 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 type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { describe, expect, it } from "vitest";
 
 import { registerGoalControlTool, type GoalControlDetails } from "../adapters/goal-control-adapter";

package/src/__tests__/index.test.ts

@@ -6,7 +6,7 @@
  *
  * 用最小 fake pi + fake ctx 实例化 goalExtension 工厂，再调 pi.__goalInit。
  */
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { describe, expect, it } from "vitest";
 
 import goalExtension from "../index";

package/src/adapters/command-adapter.ts

@@ -14,7 +14,7 @@
  * adapters 层可 import Pi 类型（桥接 Pi 和 service）。
  */
 
-import type { CustomEntry, ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { CustomEntry, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { parseGoalArgs } from "../commands";
 import {

package/src/adapters/event-handlers/agent-end.ts

@@ -18,7 +18,7 @@
  * 检查之后——终态 goal 仍走终态 notify（不被 ESC 影响），非 active 状态直接返回。
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { checkBudgetOnTurnEnd } from "../../engine/budget";
 import { isActiveStatus, isTerminalStatus } from "../../engine/goal";

package/src/adapters/event-handlers/before-agent-start.ts

@@ -15,7 +15,7 @@
  * contextInjectionPrompt 恒定建议 plan mode（AI 自行决定是否用）。
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { AUTO_CLEAR_TURNS, CONTEXT_USAGE_RATIO_LIMIT } from "../../constants";
 import { isActiveStatus, isTerminalStatus } from "../../engine/goal";

package/src/adapters/event-handlers/message-end.ts

@@ -7,7 +7,7 @@
  * 不 persist / updateWidget。
  */
 
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { applyEvent } from "../../service";
 import type { GoalSession } from "../../session";

package/src/adapters/event-handlers/session-start.ts

@@ -4,7 +4,7 @@
  * 调 reconstructGoalState 重建持久化状态 + updateWidget。
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { updateWidget } from "../../projection/widget";
 import type { GoalSession } from "../../session";

package/src/adapters/event-handlers/turn-end.ts

@@ -10,7 +10,7 @@
  * 不 persist（与旧 index.ts 行为对齐——turn_end 只内存变更 + widget）。
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { updateWidget } from "../../projection/widget";
 import { applyEvent } from "../../service";

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

@@ -25,8 +25,8 @@
  */
 
 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 { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 import { type GuiComponent, guiComponent, type GuiRenderResult,guiResult } from "@xyz-agent/extension-protocol";
 import { type Static, Type } from "typebox";
 
@@ -118,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）→ 拒绝创建（防静默覆盖未完成工作）
@@ -181,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）
@@ -210,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;
@@ -237,6 +245,15 @@ export function handleReportBlocked(
  *
  * 对齐 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":
@@ -341,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",
@@ -396,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/adapters/ports.ts

@@ -9,7 +9,7 @@
  * - session: ctx.sessionManager.getEntries + ctx.getContextUsage + ctx.signal
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { ENTRY_TYPE, HISTORY_ENTRY_TYPE } from "../persistence";
 import type { MessagingPort, PersistencePort, SessionPort, UiPort } from "../ports";

package/src/index.ts

@@ -17,8 +17,8 @@
  * FR-6.7：移除 pendingPause（ESC 改用 ctx.signal.aborted 守卫，在 event-adapter）。
  */
 
-import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@mariozechner/pi-coding-agent";
-import { Text } from "@mariozechner/pi-tui";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 
 import { handleGoalCommand } from "./adapters/command-adapter";
 import {