@zhushanwen/pi-goal 0.8.0 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-goal",
-  "version": "0.8.0",
+  "version": "0.8.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",

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

@@ -106,6 +106,14 @@ describe("handleComplete — active 守卫 + evidence + finalizeAndPersist", ()
 			handleComplete({ action: "complete", evidence: "   " }, session, makeFakePorts()),
 		).toThrow(/evidence/);
 	});
+
+	it("evidence undefined → throw（schema 降级后 handler 唯一兜底：'required' 错误）", () => {
+		const session = createGoalSession();
+		session.state = activeState();
+		expect(() => handleComplete({ action: "complete" }, session, makeFakePorts())).toThrow(
+			/evidence.*required/,
+		);
+	});
 });
 
 // ── handleCreate ─────────────────────────────────────
@@ -142,6 +150,13 @@ describe("handleCreate — slug+objective 必填 + 非终态守卫 + createGoal"
 		).toThrow(/objective/);
 	});
 
+	it("objective undefined → throw（schema 降级后 handler 唯一兜底：'required' 错误）", () => {
+		const session = createGoalSession();
+		expect(() => handleCreate({ action: "create", successCriteria: "y" }, session, makeFakePorts())).toThrow(
+			/objective.*required/,
+		);
+	});
+
 	it("successCriteria 空 → throw（即使有 slug + objective）", () => {
 		const session = createGoalSession();
 		expect(() =>
@@ -153,6 +168,13 @@ describe("handleCreate — slug+objective 必填 + 非终态守卫 + createGoal"
 		).toThrow(/successCriteria/);
 	});
 
+	it("successCriteria undefined → throw（schema 降级后 handler 唯一兜底：'required' 错误）", () => {
+		const session = createGoalSession();
+		expect(() => handleCreate({ action: "create", objective: "x" }, session, makeFakePorts())).toThrow(
+			/successCriteria.*required/,
+		);
+	});
+
 	const NON_TERMINAL_STATUSES: GoalRuntimeState["status"][] = ["active", "paused", "blocked"];
 	it.each(NON_TERMINAL_STATUSES)("已有 %s goal → throw（D25 非终态守卫）", (status) => {
 		const session = createGoalSession();
@@ -250,4 +272,12 @@ describe("handleReportBlocked — active 守卫 + tick + transition + persist",
 			handleReportBlocked({ action: "report_blocked", reason: "" }, session, makeFakePorts()),
 		).toThrow(/reason/);
 	});
+
+	it("reason undefined → throw（schema 降级后 handler 唯一兜底：'required' 错误）", () => {
+		const session = createGoalSession();
+		session.state = activeState();
+		expect(() => handleReportBlocked({ action: "report_blocked" }, session, makeFakePorts())).toThrow(
+			/reason.*required/,
+		);
+	});
 });

package/src/__tests__/schema.test.ts

@@ -1,17 +1,30 @@
 /**
- * goal_control schema — discriminated union 校验测试（TC6 / CT3）
+ * goal_control schema — 扁平 Object 校验测试（OpenAI 兼容）
  *
- * schema 为 Type.Union（无 discriminator keyword）+ 各分支 additionalProperties:false，
- * 以 action literal 区分分支。pi 生产校验器为 typebox/compile 的 Compile(schema).Check(args)，
- * 与此处 Value.Check 同源（同一 typebox schema 语义），故用 Value.Check 验证拒绝行为。
+ * schema 为扁平 Type.Object + action 字段级 Type.Union（等价 enum）+ 各字段 Optional +
+ * additionalProperties:false。OpenAI function calling 要求 parameters 顶层 type:"object"，
+ * 顶层 Type.Union 序列化后只有 anyOf 无 type 字段，会被严格 OpenAI 兼容网关 400 拒绝
+ * 整个会话——故采用扁平结构（范式对齐 scheduler ScheduleControlParams）。
+ *
+ * typebox schema 对象即序列化形态：GoalControlParams.type 就是发往 provider 的 JSON 顶层 type。
+ * pi 生产校验器为 typebox/compile 的 Compile(schema).Check(args)，与此处 Value.Check 同源，
+ * 故用 Value.Check 验证。
+ *
+ * 分支隔离从 schema 层降级为运行时 handler 字段存在性校验（见 goal-control-adapter.test.ts）。
  */
 import { describe, expect, it } from "vitest";
 import { Value } from "typebox/value";
 
 import { GoalControlParams } from "../adapters/goal-control-adapter";
 
-describe("GoalControlParams — discriminated union（TC6）", () => {
-	// valid：各分支完整 + optional 字段 → 通过
+describe("GoalControlParams — 扁平 Object（OpenAI 兼容）", () => {
+	// 顶层合规：序列化形态顶层必须有 type:"object"，不得有 anyOf（否则被严格网关 400 拒绝）
+	it("顶层 type === 'object' 且无 anyOf（OpenAI function calling 合规）", () => {
+		expect(GoalControlParams.type).toBe("object");
+		expect(GoalControlParams.anyOf).toBeUndefined();
+	});
+
+	// valid：各 action 完整 + optional 字段 → 通过
 	it.each([
 		["create 完整", { action: "create", objective: "x", successCriteria: "y" }],
 		["create + slug", { action: "create", slug: "refactor-auth", objective: "x", successCriteria: "y" }],
@@ -22,16 +35,19 @@ describe("GoalControlParams — discriminated union（TC6）", () => {
 		expect(Value.Check(GoalControlParams, params)).toBe(true);
 	});
 
-	// invalid：缺必填 / 额外字段（additionalProperties:false 代表性用例）/ 分支隔离 / 未知 action
+	// 关键语义变更：扁平化后所有声明的字段（含跨 action 的）均为 Optional，
+	// schema 不再做分支隔离。{action:"complete", evidence, objective} 放行
+	// （objective 是声明的 Optional 字段，schema 层无法区分它属于哪个 action）。
+	// 分支隔离降级为运行时 handler 字段存在性校验，见 goal-control-adapter.test.ts。
+	it("跨 action 字段（complete + objective）现在通过（分支隔离降级为运行时校验）", () => {
+		expect(Value.Check(GoalControlParams, { action: "complete", evidence: "x", objective: "leak" })).toBe(true);
+	});
+
+	// invalid：缺 action / 未知 action / 额外字段（additionalProperties:false）
 	it.each([
-		["create 缺 objective", { action: "create", successCriteria: "y" }],
-		["create 缺 successCriteria", { action: "create", objective: "x" }],
+		["缺 action", { objective: "x", successCriteria: "y" }],
+		["未知 action（不在 union 内）", { action: "unknown" }],
 		["create 含额外字段（additionalProperties:false）", { action: "create", objective: "x", successCriteria: "y", foo: 1 }],
-		["create 含 complete 分支字段 evidence（分支隔离）", { action: "create", objective: "x", successCriteria: "y", evidence: "leak" }],
-		["complete 缺 evidence", { action: "complete" }],
-		["report_blocked 缺 reason", { action: "report_blocked" }],
-		["未知 action", { action: "unknown" }],
-		["缺 action", { objective: "x" }],
 	])("invalid: %s → 拒绝", (_name, params) => {
 		expect(Value.Check(GoalControlParams, params)).toBe(false);
 	});

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

@@ -19,10 +19,12 @@
  * create 不调 sendUserMessage：toolcall 时 AI 已在 turn 中，返回结果后自行续跑
  * （与 /goal set 的 followUp 触发区分；对齐 Codex create_goal 不自动续跑）。
  *
- * schema：discriminated union（C3）——Type.Union 无 discriminator keyword，各分支以
- * action literal 区分 + additionalProperties:false。pi 生产校验器为 typebox/compile
- * 的 Compile(schema).Check(args)，缺失必填字段在 schema 层即被拒绝；execute 内仅保留
- * .trim() 空字符串校验（LLM 可能传空串穿透 schema）。
+ * schema：扁平 Type.Object（OpenAI 兼容，C3）——parameters 顶层必须是 type:"object"，
+ * 顶层 Type.Union 序列化后只有 anyOf 无 type，会被严格 OpenAI 兼容网关 400 拒绝。故采用
+ * 扁平 Object + action 字段级 Type.Union（等价 enum）+ 各字段 Optional + additionalProperties:false。
+ * 分支隔离从 schema 层降级为运行时 handler 字段存在性校验（见各 handler 开头）；
+ * pi 生产校验器为 typebox/compile 的 Compile(schema).Check(args)，缺失/错误 action、额外字段
+ * 在 schema 层拒绝，缺必填字段由 handler 校验兜底。
  *
  * executionMode: "sequential"——状态变更 tool，不可与同批其他 tool 并行执行。
  *
@@ -46,62 +48,60 @@ import { buildPorts } from "./ports";
 // ── Params schema（discriminated union，C3）────────────
 
 /**
- * goal_control 参数 schema。三分支以 action literal 区分（无 discriminator keyword），
- * 各分支 additionalProperties:false，缺失必填在 schema 层拒绝。
+ * goal_control 参数 schema。扁平 Type.Object + action 字段级 Type.Union（等价 enum）。
+ *
+ * OpenAI function calling 规范要求 parameters 顶层必须是 type:"object"；顶层 Type.Union
+ * 序列化后只有 anyOf 无 type 字段，会被严格的 OpenAI 兼容网关 400 拒绝整个会话。故采用
+ * 扁平 Object + action enum，分支隔离从 schema 层降级为运行时 handler 字段存在性校验
+ * （见各 handler 开头）。范式对齐 scheduler ScheduleControlParams。
+ *
+ * additionalProperties:false 阻挡未知字段；缺失/错误 action 仍由 schema 层拒绝。
  */
-const CreateParams = Type.Object(
+export const GoalControlParams = Type.Object(
 	{
-		action: Type.Literal("create"),
+		action: Type.Union(
+			[Type.Literal("create"), Type.Literal("complete"), Type.Literal("report_blocked")],
+			{ description: "create | complete | report_blocked" },
+		),
 		slug: Type.Optional(
 			Type.String({
 				description: "可选。状态栏标题用的短 kebab-case 标识，仅用于显示，不注入 prompt。",
 			}),
 		),
-		objective: Type.String({
-			description:
+		objective: Type.Optional(
+			Type.String({
+				description:
 				"必填。用你自己的话重述真实目标——用户实际想要达成什么，而非字面复述请求。模糊时推断最可能的意图并明确陈述。",
-		}),
-		successCriteria: Type.String({
-			description:
+			}),
+		),
+		successCriteria: Type.Optional(
+			Type.String({
+				description:
 				"必填。可检查的完成条件（如「测试通过」「文件 X 存在且含内容 Y」「命令 Z 输出 W」），不是愿景或「能用就行」。这是 complete 前必须逐条满足的门槛。",
-		}),
+			}),
+		),
 		tokenBudget: Type.Optional(
 			Type.Number({
 				description: "可选。新目标的 token 预算（正数）。除非用户指定，否则省略。",
 			}),
 		),
-	},
-	{ additionalProperties: false },
-);
-
-const CompleteParams = Type.Object(
-	{
-		action: Type.Literal("complete"),
-		evidence: Type.String({
-			description:
+		evidence: Type.Optional(
+			Type.String({
+				description:
 				"必填。具体完成证据（改动/新建的文件、通过的测试、运行的命令）。不要基于假设、意图或部分进度标记完成。",
-		}),
-	},
-	{ additionalProperties: false },
-);
-
-const ReportBlockedParams = Type.Object(
-	{
-		action: Type.Literal("report_blocked"),
-		reason: Type.String({
-			description:
+			}),
+		),
+		reason: Type.Optional(
+			Type.String({
+				description:
 				"必填。具体阻塞条件及已尝试的方案。不要用于不确定、困难、缓慢或未完成的工作——继续做。",
-		}),
+			}),
+		),
 	},
 	{ additionalProperties: false },
 );
 
-export const GoalControlParams = Type.Union([CreateParams, CompleteParams, ReportBlockedParams]);
-
-export type CreateActionParams = Static<typeof CreateParams>;
-export type CompleteActionParams = Static<typeof CompleteParams>;
-export type ReportBlockedActionParams = Static<typeof ReportBlockedParams>;
-export type GoalControlActionParams = Static<typeof GoalControlParams>;
+export type GoalControlParamsT = Static<typeof GoalControlParams>;
 
 // ── Details（renderResult 数据来源）──────────────────
 
@@ -131,13 +131,16 @@ export interface GoalControlDetails {
  * 终态旧 goal 走 createGoal 快速路径覆盖（createGoal 内部 active 守卫，终态可覆盖）。
  */
 export function handleCreate(
-	params: CreateActionParams,
+	params: GoalControlParamsT,
 	session: GoalSession,
 	ports: ServicePorts,
 ): GoalControlDetails {
+	if (params.objective === undefined) {
+		throw new Error("'objective' required for create. Correct: {\"action\":\"create\",\"objective\":\"...\",\"successCriteria\":\"...\"}");
+	}
 	const objective = params.objective.trim();
 	if (!objective) {
-		// schema 已挡缺失，此处仅挡空串（LLM 可能传空串穿透 schema）
+		// schema 已放行（扁平化后 optional），此处挡空串（LLM 可能传空串）
 		throw new Error(
 			"'objective' must not be empty. Describe the concrete objective to pursue. Correct: {\"action\":\"create\",\"slug\":\"<kebab-case>\",\"objective\":\"<concrete objective>\",\"successCriteria\":\"<checkable conditions>\"}",
 		);
@@ -145,6 +148,9 @@ export function handleCreate(
 	// slug 真 optional（TC11）：缺失时 fallback goalId 截断（与 buildGoalGui 口径一致），不强制必填
 	const slugInput = params.slug?.trim();
 
+	if (params.successCriteria === undefined) {
+		throw new Error("'successCriteria' required for create. Correct: {\"action\":\"create\",\"objective\":\"...\",\"successCriteria\":\"...\"}");
+	}
 	const successCriteria = params.successCriteria.trim();
 	if (!successCriteria) {
 		throw new Error(
@@ -192,7 +198,7 @@ export function handleCreate(
  * 全解耦后不再做 todo 完成前置检查——todo 是否全完成由 AI 自行判断（prompt 软建议）。
  */
 export function handleComplete(
-	params: CompleteActionParams,
+	params: GoalControlParamsT,
 	session: GoalSession,
 	ports: ServicePorts,
 ): GoalControlDetails {
@@ -201,6 +207,9 @@ export function handleComplete(
 	if (!isActiveStatus(state.status)) {
 		throw new Error(`Goal is not active (status: ${state.status}). Only an active goal can be completed.`);
 	}
+	if (params.evidence === undefined) {
+		throw new Error("'evidence' required for complete. Correct: {\"action\":\"complete\",\"evidence\":\"...\"}");
+	}
 	const evidence = params.evidence.trim();
 	if (!evidence) {
 		throw new Error(
@@ -223,7 +232,7 @@ export function handleComplete(
  * 否则转 blocked 后 persistState 内部的 tick 因 status≠active 不累加，丢失最后一段运行时间。
  */
 export function handleReportBlocked(
-	params: ReportBlockedActionParams,
+	params: GoalControlParamsT,
 	session: GoalSession,
 	ports: ServicePorts,
 ): GoalControlDetails {
@@ -232,6 +241,9 @@ export function handleReportBlocked(
 	if (state.status !== "active") {
 		throw new Error(`Goal is not active (status: ${state.status}). Only an active goal can report_blocked.`);
 	}
+	if (params.reason === undefined) {
+		throw new Error("'reason' required for report_blocked. Correct: {\"action\":\"report_blocked\",\"reason\":\"...\"}");
+	}
 	const reason = params.reason.trim();
 	if (!reason) {
 		throw new Error(
@@ -297,7 +309,7 @@ export function registerGoalControlTool(pi: ExtensionAPI, session: GoalSession):
 
 		async execute(
 			_toolCallId: string,
-			params: GoalControlActionParams,
+			params: GoalControlParamsT,
 			signal: AbortSignal | undefined,
 			_onUpdate: unknown,
 			ctx: ExtensionContext,
@@ -317,13 +329,14 @@ export function registerGoalControlTool(pi: ExtensionAPI, session: GoalSession):
 				details = handleReportBlocked(params, session, ports);
 			}
 
-			// 用 params.action 判断（TS 据此收窄 params 到对应分支，安全访问 objective/reason）
+			// 扁平化后 params.objective/reason 为 string|undefined（schema 不再按 action 收窄）；
+			// handler 已对必填字段做存在性校验，此处用 ?. 兜底，未定义时空串
 			const text =
 				params.action === "create"
-					? `Goal created.\nGoal ID: ${details.goalId}\nSlug: ${details.slug ?? ""}\nObjective: ${params.objective.trim()}`
+					? `Goal created.\nGoal ID: ${details.goalId}\nSlug: ${details.slug ?? ""}\nObjective: ${params.objective?.trim() ?? ""}`
 					: params.action === "complete"
 						? `Goal completed.\nGoal ID: ${details.goalId}`
-						: `Goal reported blocked.\nGoal ID: ${details.goalId}\nReason: ${params.reason.trim()}`;
+						: `Goal reported blocked.\nGoal ID: ${details.goalId}\nReason: ${params.reason?.trim() ?? ""}`;
 
 			// RPC 模式下附加 __gui__（用展开避免 details 来自 frozen 对象时加字段失败）
 			if (ctx.mode === "rpc" && session.state) {