@zhushanwen/pi-goal 0.3.0 → 0.4.0

package/src/index.ts

@@ -1,445 +1,200 @@
 /**
- * Pi /goal Extension — Codex-style persistent goal-driven autonomous loop
+ * Pi /goal Extension — 工厂入口（重构后架构）
  *
- * 功能：
- * - 持久化目标设定，支持 pause/resume/clear/update
- * - Evidence-based completion（完成任务必须提供具体证据）
- * - Token 预算 + 时间预算（含 70%/90% 预警）
- * - Blocked 状态检测（连续 stall 自动阻塞）
- * - Steering 模板化（continuation / budget-limit / objective-updated）
- * - 任务清单追踪
+ * 注册 command / events，全部委托 adapters 层。
+ * __goalInit 内部调 service.createGoal（FR-4.1）。
  *
- * 健壮性保障：
- * - goalId snapshot 防止旧回调操作新 goal
- * - 时间累计统一由 persistState 管理，无双写
- * - before_agent_start 注入 context，agent_end 负责 continuation（预算检查/进度评估/续跑）
- * - deserializeState 向后兼容旧格式
- * - isProcessing 防重入（agent_end 重入时直接返回）
+ * 架构（D-21 双路径 + Ports/Adapters）：
+ * - engine/：零 Pi 依赖的纯状态机（goal/budget/types）
+ * - ports.ts：机器可检查的能力边界
+ * - adapters/ports.ts：Pi → ServicePorts 桥接（单一构造点）
+ * - service.ts：事件入口协调器（applyEvent）
+ * - adapters/：Pi 桥接（command-adapter / event-adapter / ports）
+ * - projection/：渲染（widget / prompts）
+ *
+ * FR-4.2/D-16：ctx 必填，移除 lastCtx 模块级可变状态。
+ * FR-6.4：移除 hasPendingInjection。
+ * FR-6.7：移除 pendingPause（ESC 改用 ctx.signal.aborted 守卫，在 event-adapter）。
  */
 
-import type { CustomEntry, ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
-import { type Static } from "typebox";
 
-import { handleAgentEnd } from "./agent-end-handler";
-import { handleBeforeAgentStart } from "./before-agent-start-handler";
-import { handleGoalCommand } from "./command-handler";
-import {
-	ELLIPSIS_LENGTH,
-	EXT_INIT_TASK_DESC_MAX,
-	MAX_HISTORY_ENTRIES,
-} from "./constants";
+import { handleGoalCommand } from "./adapters/command-adapter";
 import {
-	createInitialState,
-	deserializeState,
-	getCompletedCount,
-	type GoalExternalInit,
-	isActiveStatus,
-	isTerminalStatus,
-} from "./state";
-import {
-	executeGoalAction,
-	type GoalManagerDetails,
-	GoalManagerParams,
-	type GoalSession,
-	HISTORY_ENTRY_TYPE,
-	isGoalEntry,
-	isStaleContextError,
-	persistGoalState,
-	updateWidget,
-} from "./tool-handler";
-import { toSingleLine } from "./widget";
-
-// ── Local Interfaces (avoid `any` on Pi callback/event signatures) ────
+	handleAgentEnd,
+	handleAgentStart,
+	handleBeforeAgentStart,
+	handleMessageEnd,
+	handleSessionStart,
+	handleTurnEnd,
+} from "./adapters/event-adapter";
+import { registerGoalControlTool } from "./adapters/goal-control-adapter";
+import { buildPorts } from "./adapters/ports";
+import { createGoal } from "./service";
+import { createGoalSession, type GoalSession } from "./session";
+
+// ── Local Interfaces (Like*Event — 避免 any on Pi callback/event signatures) ────
 
-/** Fields accessed from BeforeAgentStartEvent */
 interface BeforeAgentStartLikeEvent {
 	type: "before_agent_start";
 	prompt: string;
 	systemPrompt: string;
 }
 
-/** Fields accessed from TurnEndEvent */
 interface TurnEndLikeEvent {
 	type: "turn_end";
 	turnIndex: number;
 }
 
-/** Subset of AgentMessage.usage accessed in message_end handler */
-interface LikeUsage {
-	input?: number;
-	output?: number;
-	cacheRead?: number;
-	totalTokens?: number;
-}
-
-/** Fields accessed from MessageEndEvent */
 interface MessageEndLikeEvent {
 	type: "message_end";
 	message: {
 		role: string;
-		usage?: LikeUsage;
+		usage?: { input?: number; output?: number; cacheRead?: number; totalTokens?: number };
 	};
 }
 
-/** Fields accessed from AgentEndEvent */
 interface AgentEndLikeEvent {
 	type: "agent_end";
 	messages: unknown[];
 }
 
-/** Fields accessed from SessionStartEvent */
 interface SessionStartLikeEvent {
 	type: "session_start";
 	reason: string;
 }
 
-/** Shape of CustomMessage passed to registerMessageRenderer */
 interface LikeCustomMessage {
 	customType: string;
 	content: string | unknown;
 }
 
-/** Options bag for registerMessageRenderer callback */
 interface LikeMessageRenderOptions {
 	expanded: boolean;
 }
 
-/** Result shape accessed in renderResult */
-interface LikeToolResult {
-	content: Array<{ type: string; text?: string }>;
-	details?: GoalManagerDetails;
-}
-
-/** Options bag for renderResult callback */
-interface LikeToolRenderResultOptions {
-	expanded: boolean;
-}
-
-// ── State Reconstruction ─────────────────────────────
-
-function reconstructGoalState(pi: ExtensionAPI, session: GoalSession, ctx: ExtensionContext): void {
-	session.state = null;
-	const entries = ctx.sessionManager.getEntries();
-
-	for (let i = entries.length - 1; i >= 0; i--) {
-		const entry = entries[i]!;
-		if (isGoalEntry(entry)) {
-			const data = entry.data as Record<string, unknown> | undefined;
-			if (data) {
-				try {
-					session.state = deserializeState(data);
-				} catch {
-					session.state = null;
-				}
-			}
-			break;
-		}
-	}
-
-	if (!session.state) return;
-
-	// 非终态 → 恢复为 active
-	if (!isTerminalStatus(session.state.status) && session.state.status !== "paused") {
-		session.state.status = "active";
-		session.state.timeStartedAt = Date.now();
-	}
-
-	// Entry GC — 标记旧的 goal-state entries
-	const goalEntryIndices: number[] = [];
-	let latestFound = false;
-	for (let i = entries.length - 1; i >= 0; i--) {
-		const entry = entries[i];
-		if (isGoalEntry(entry)) {
-			if (!latestFound) latestFound = true;
-			else goalEntryIndices.push(i);
-		}
-	}
-	for (const idx of goalEntryIndices) {
-		entries.splice(idx, 1);
-	}
-
-	// Goal-history entry GC
-	const historyIndices: number[] = [];
-	for (let i = 0; i < entries.length; i++) {
-		const entry = entries[i]!;
-		if (entry.type === "custom" && (entry as CustomEntry).customType === HISTORY_ENTRY_TYPE) {
-			historyIndices.push(i);
-		}
-	}
-	if (historyIndices.length > MAX_HISTORY_ENTRIES) {
-		const toDelete = historyIndices.slice(0, historyIndices.length - MAX_HISTORY_ENTRIES);
-		for (let i = toDelete.length - 1; i >= 0; i--) {
-			entries.splice(toDelete[i]!, 1);
-		}
-	}
-}
-
 // ── Extension Factory ─────────────────────────────────
 
 export default function goalExtension(pi: ExtensionAPI) {
-	const session: GoalSession = {
-		state: null,
-		tasksCompletedAtAgentStart: 0,
-		hasPendingInjection: false,
-		isProcessing: false, // P1-3: 防重入
-		pendingPause: false, // ESC 中断标记
-	};
+	const session: GoalSession = createGoalSession();
 
-	// Capture latest ctx for external API (initializeGoalFromExternal needs it for persistGoalState)
-	let lastCtx: ExtensionContext | undefined;
-
-	pi.registerTool({
-		name: "goal_manager",
-		label: "Goal Manager",
-			description:
-				"Goal mode task manager. This tool is only available after starting a goal via the /goal command. AI cannot trigger it proactively. If Goal mode is not active, calling this tool will error." +
-				"\n\nAvailable actions:" +
-				"\n- create_tasks: Decompose the objective into a task list (call once at goal start). Each task description must be a one-line summary (max 60 chars), no newlines or markdown. Accept verifications array for task verification." +
-				"\n- add_tasks: Append new tasks to the existing list (when omissions are discovered). Fails if no tasks exist yet — use create_tasks first. Each task description must be a one-line summary (max 60 chars), no newlines or markdown. Accept verifications array." +
-				"\n- update_tasks: Batch update task statuses. Must follow state machine: pending→in_progress→completed→verified. Cannot skip states (pending→completed is forbidden). Exactly one task should be in_progress at a time. Completed requires evidence. Cancelled does not block goal completion. Completing a task with verification triggers a verification prompt — then call update_tasks with status=verified and actual=<result>." +
-				"\n- list_tasks: View progress and remaining budget" +
-				"\n- complete_goal: Mark the objective as achieved. Only call when ALL tasks are completed or verified with concrete evidence. Do not mark complete merely because the budget is nearly exhausted or because you are stopping work. Before calling, use list_tasks to verify all tasks are done." +
-				"\n- cancel_goal: Cancel the current goal (use when user wants to exit/stop)" +
-				"\n- report_blocked: Report being blocked. Only use after trying at least 3 alternative approaches to the same blocking condition. Do not use merely because the work is hard, slow, uncertain, incomplete, or would benefit from clarification. Requires a specific reason describing what is blocking and what you have already tried." +
-				"\n- add_subtasks: Add subtasks to a specified task (params: taskId, texts[]). Use this instead of todo tool in Goal mode" +
-				"\n- update_subtasks: Batch update subtask statuses (params: taskId, subUpdates[])" +
-				"\n- delete_subtasks: Delete subtasks from a specified task (params: taskId, subIds[])",
-		promptSnippet: "Manage task list, completion status, and exit for /goal mode",
-		promptGuidelines: [
-			"[Workflow] After receiving the objective, the first step must be create_tasks to decompose. Do not re-call if task list already exists",
-			"[Status flow] Tasks must follow this order: pending → in_progress → completed → verified. You CANNOT skip in_progress. Before marking completed, always set status=in_progress first. Transitions: pending→in_progress | pending→cancelled, in_progress→completed | in_progress→cancelled, completed→verified (only if task has verification)",
-			"[Format] Each task description must be a one-line summary, max 60 chars. No newlines, markdown, or detailed parameter lists — those go in execution phase. Example: 'Fix hook-registry dedup logic' not 'Fix hook-registry dedup + transport-execute enhancementConfig guard + failover-loop ...'",
-			"[Append] When discovering omissions during execution, use add_tasks to append — do not re-call create_tasks",
-			"[Completion] After completing a task, call update_tasks with status=completed and provide evidence (e.g. 'test X passed', 'file F created')",
-			"[Goal completion] Only call complete_goal when all tasks are completed or verified with overall evidence",
-			"[Exit] When user says 'stop', 'exit', 'cancel', '不用了', '结束', etc. indicating they don't want to continue, immediately call cancel_goal — do not guide them through complete_goal",
-			"[Blocked] Do not call report_blocked the first time a blocker appears. Try at least 3 alternative approaches first. Only report blocked when genuinely at an impasse without user input — not because work is hard, slow, uncertain, or incomplete. Once you call report_blocked, include what you have already tried in the reason.",
-			"[Progress] Use list_tasks anytime to check remaining tasks and budget",
-			"[Cancel] To cancel a task, use update_tasks with status=cancelled. Cancelled tasks do not block goal completion",
-			"[Audit] Before marking a task completed, verify against actual current state (files, command output, test results). Intent, partial progress, or 'it should work' are NOT evidence. Do not redefine success around work already done — preserve original scope. Uncertain or indirect evidence means not completed, keep working.",
-			"[Fidelity] Optimize for movement toward the requested end state, not the easiest passing change. Do not substitute a narrower or safer solution because it is easier to verify. An edit is aligned only if it makes the requested final state more true.",
-			"[Forbidden] Do not mark tasks as completed without evidence, and do not call complete_goal without evidence. Do not mark completed due to budget exhaustion or because you are stopping work.",
-			"[Forbidden] Do not force task completion when the user explicitly wants to exit — call cancel_goal directly",
-			"[Quick exit] When no tasks have been created and you determine the objective is already met, call cancel_goal with cancelReason instead of creating tasks",
-			"[Forbidden] Do not re-call create_tasks to overwrite existing incomplete tasks — use add_tasks to append",
-			"[Subtask] For fine-grained step tracking in Goal mode, use add_subtasks — do not use the todo tool",
-			"[Verification] Each task should have a concrete verification method. Use verifications param in create_tasks/add_tasks. Templates:",
-			"[Verification] - Command: method='pnpm --filter <pkg> typecheck', expected='zero type errors'",
-			"[Verification] - Test: method='pnpm --filter <pkg> test', expected='all tests pass'",
-			"[Verification] - File: method='check <path> exists and contains <content>', expected='file exists with matching content'",
-			"[Verification] - Manual: method='manual check <specific items>', expected='<expected result'",
-			"[Verification] Multiple related tasks can share one verification — set verification on the LAST related task only",
-			"[Verification] Do NOT create a separate 'run tests' task for verification — use verification field instead",
-			"[Verification] When a task with verification is completed, run the verification command with bash. Then call update_tasks with status=verified and actual=<result>",
-		],
-		parameters: GoalManagerParams,
-
-		async execute(_toolCallId: string, params: Static<typeof GoalManagerParams>, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: ExtensionContext) {
-			lastCtx = ctx;
-			try {
-				// P1-4: 透传 signal
-				return await executeGoalAction(pi, session, params, ctx, signal);
-			} catch (err) {
-				// P1-2: Stale context 检测 — 静默吞掉
-				if (isStaleContextError(err)) {
-					return {
-						content: [{ type: "text" as const, text: "Goal context stale after compact or session replacement." }],
-						isError: true as const,
-					};
-				}
-				const msg = err instanceof Error ? err.message : String(err);
-				const inputSummary = JSON.stringify(params, null, 2); // eslint-disable-line no-magic-numbers -- JSON.stringify indent
-				return {
-					content: [{ type: "text", text: `${msg}\n\nInput: ${inputSummary}` }],
-					isError: true,
-				};
-			}
-		},
-
-		renderCall(args: Static<typeof GoalManagerParams>, theme: Theme) {
-			let text = theme.fg("toolTitle", theme.bold("goal_manager ")) + theme.fg("muted", args.action);
-			if (args.tasks) text += ` ${theme.fg("dim", `(${args.tasks.length} tasks)`)}`;
-			if (args.updates) text += ` ${theme.fg("dim", `(${args.updates.length} updates)`)}`;
-			if (args.taskId !== undefined) text += ` ${theme.fg("accent", `#${args.taskId}`)}`;
-			if (args.texts) text += ` ${theme.fg("dim", `(${args.texts.length} subtasks)`)}`;
-			if (args.subUpdates) text += ` ${theme.fg("dim", `(${args.subUpdates.length} subtask updates)`)}`;
-			if (args.subIds) text += ` ${theme.fg("dim", `del #${args.subIds.join(",")}`)}`;
-			return new Text(text, 0, 0);
-		},
-
-		renderResult(result: LikeToolResult, { expanded }: LikeToolRenderResultOptions, theme: Theme) {
-			const details = result.details as GoalManagerDetails | undefined;
-			if (!details || !Array.isArray(details.tasks)) {
-				const text = result.content[0];
-				return new Text(text?.type === "text" ? (text.text ?? "") : "", 0, 0);
-			}
-			const tasks = details.tasks;
-			const completed = getCompletedCount(tasks);
-			const summary = theme.fg("success", `✓ ${completed}/${tasks.length} completed`);
-			if (!expanded || tasks.length === 0) {
-				return new Text(summary, 0, 0);
-			}
-			const lines = [summary];
-			for (const t of tasks) {
-				const icon = t.status === "verified"
-					? theme.fg("success", "◉")
-					: t.status === "completed"
-						? theme.fg("success", "✓")
-						: t.status === "in_progress"
-							? theme.fg("warning", "●")
-							: t.status === "cancelled"
-								? theme.fg("dim", "✗")
-								: theme.fg("dim", "☐");
-				const descText = toSingleLine(t.description);
-				const desc = (t.status === "verified" || t.status === "completed" || t.status === "cancelled")
-					? theme.fg("dim", descText)
-					: theme.fg("text", descText);
-				lines.push(`  ${icon} ${theme.fg("accent", `#${t.id}`)} ${desc}`);
-			// Subtask items in expanded view — collapse when all completed
-			if (t.subtasks && t.subtasks.length > 0) {
-				const allSubCompleted = t.subtasks.every((s: { status: string }) => s.status === "completed");
-				if (!allSubCompleted) {
-					for (const s of t.subtasks) {
-						const subIcon = s.status === "completed"
-							? theme.fg("success", "\u2713")
-							: s.status === "in_progress"
-								? theme.fg("warning", "\u25cf")
-								: theme.fg("dim", "\u25cb");
-						const subText = s.status === "completed" ? theme.fg("dim", s.text) : theme.fg("muted", s.text);
-						lines.push(`    ${subIcon} ${theme.fg("dim", `${t.id}.${s.id}`)} ${subText}`);
-					}
-				}
-			}
-		}
-			return new Text(lines.join("\n"), 0, 0);
-		},
-	});
-
-	// ── Command: /goal ─────────────────────────────────
+	// ── Command: /goal ────────────────────────────────
 
 	pi.registerCommand("goal", {
 		description:
-			"Goal-driven mode: /goal <objective> [--tokens N] [--timeout N] [--max-turns N] | /goal pause | /goal resume | /goal abort | /goal clear | /goal update <new-objective> | /goal status | /goal history",
+			"Goal-driven mode: /goal <objective> [--tokens N] [--timeout N] | /goal resume | /goal clear | /goal update <new-objective> | /goal status | /goal history",
 		handler: async (args: string | undefined, ctx: ExtensionCommandContext) => {
 			await handleGoalCommand(pi, session, args, ctx);
 		},
 	});
 
-	// ── Event: before_agent_start ──────────────────────
+	// ── Tool: goal_control（complete / report_blocked，#3 替代已删 goal_manager）──
+
+	registerGoalControlTool(pi, session);
+
+	// ── Events（全部委托 adapters/event-adapter）────────
+
 	pi.on("before_agent_start", async (_event: BeforeAgentStartLikeEvent, ctx: ExtensionContext) => {
-		lastCtx = ctx;
 		return handleBeforeAgentStart(pi, session, ctx);
 	});
 
-	// ── Event: agent_start ─────────────────────────────
-
 	pi.on("agent_start", async () => {
-		if (!session.state || !isActiveStatus(session.state.status)) return;
-		session.tasksCompletedAtAgentStart = getCompletedCount(session.state.tasks);
+		await handleAgentStart(session);
 	});
 
-	// ── Event: turn_end ────────────────────────────────
 	pi.on("turn_end", async (_event: TurnEndLikeEvent, ctx: ExtensionContext) => {
-		if (!session.state) return;
-		session.state.currentTurnIndex++;
-		updateWidget(session, ctx);
+		await handleTurnEnd(pi, session, ctx);
 	});
 
-	// ── Event: message_end (token accounting) ──────────
-	pi.on("message_end", async (event: MessageEndLikeEvent, _ctx: ExtensionContext) => {
-		if (!session.state || !isActiveStatus(session.state.status)) return;
-		if (event.message.role !== "assistant") return;
-
-		const usage = event.message.usage;
-		if (usage) {
-			const input = usage.input ?? 0;
-			const output = usage.output ?? 0;
-			const cacheRead = usage.cacheRead ?? 0;
-			if (input > 0 || output > 0) {
-				session.state.tokensUsed += Math.max(input - cacheRead, 0) + output;
-			} else if (usage.totalTokens) {
-				session.state.tokensUsed += usage.totalTokens;
-			}
-		}
+	pi.on("message_end", async (event: MessageEndLikeEvent, ctx: ExtensionContext) => {
+		await handleMessageEnd(session, ctx, event);
 	});
 
-	// ── Event: agent_end ───────────────────────────────
 	pi.on("agent_end", async (_event: AgentEndLikeEvent, ctx: ExtensionContext) => {
 		await handleAgentEnd(pi, session, ctx);
 	});
 
-	// ── Event: session_start (state reconstruction) ───
 	pi.on("session_start", async (_event: SessionStartLikeEvent, ctx: ExtensionContext) => {
-		lastCtx = ctx;
-		reconstructGoalState(pi, session, ctx);
-		if (session.state) {
-			session.tasksCompletedAtAgentStart = getCompletedCount(session.state.tasks);
-			updateWidget(session, ctx);
-		}
+		await handleSessionStart(pi, session, ctx);
 	});
 
 	// ── Message Renderers ──────────────────────────────
 
-	const goalMessageTypes = [
-		"goal-context",
-		"goal-context-exceeded",
-		"goal-staleness-reminder",
-	];
-
+	const goalMessageTypes = ["goal-context", "goal-context-exceeded"];
 	for (const customType of goalMessageTypes) {
-		pi.registerMessageRenderer(customType, (message: LikeCustomMessage, _options: LikeMessageRenderOptions, theme: Theme) => {
-			const prefix =
-				message.customType === "goal-context-exceeded"
-					? theme.fg("error", "[GOAL Budget] ")
-					: message.customType === "goal-staleness-reminder"
-						? theme.fg("warning", "[GOAL Reminder] ")
+		pi.registerMessageRenderer(
+			customType,
+			(message: LikeCustomMessage, _options: LikeMessageRenderOptions, theme: Theme) => {
+				const prefix =
+					message.customType === "goal-context-exceeded"
+						? theme.fg("error", "[GOAL Budget] ")
 						: theme.fg("accent", "[GOAL] ");
-			const content = typeof message.content === "string" ? message.content : JSON.stringify(message.content);
-			return new Text(prefix + theme.fg("dim", content), 0, 0);
-		});
+				const content =
+					typeof message.content === "string" ? message.content : JSON.stringify(message.content);
+				return new Text(prefix + theme.fg("dim", content), 0, 0);
+			},
+		);
 	}
 
-	// ── External API: initializeGoalFromExternal ──────────
+	// ── External API: __goalInit（FR-4 双轨消除）──────────
 
 	/**
-	 * Allow other extensions (e.g. coding-workflow) to programmatically initialize a goal.
-	 * Skips the /goal command flow — directly creates state + tasks.
-	 * Returns true if initialized, false if goal already active.
+	 * 允许其他扩展（coding-workflow / plan）通过 pi.__goalInit 编程式初始化 goal。
+	 * 内部调 service.createGoal（FR-4.1——与 goal_control create 走同一创建逻辑）。
+	 *
+	 * FR-4.2/D-16: ctx 必填（消除 lastCtx 模块级可变状态）。
+	 * ports 构造复用 adapters/ports.buildPorts（DRY：单一 ports 构造点）。
+	 *
+	 * @param objective 目标描述
+	 * @param budget 预算配置，传 undefined 用默认值
+	 * @param ctx **必填**——调用方的 ExtensionContext。省略会返回 false（创建失败）。
+	 * @param slug 可选短标识（仅 widget 标题 + history 用，不注入 prompt）
+	 * @returns true 创建成功；false 已有 active goal 或 ctx 缺失
 	 */
-	function initializeGoalFromExternal(
+	const api = pi as unknown as Record<string, unknown>;
+	api.__goalInit = (
 		objective: string,
-		tasks: string[],
-		budget?: { tokenBudget?: number; timeBudgetMinutes?: number; maxTurns?: number },
-		ctx?: ExtensionContext,
-	): boolean {
-		if (session.state && isActiveStatus(session.state.status)) {
-			return false;
-		}
-
-		session.state = createInitialState(objective, budget);
-		session.tasksCompletedAtAgentStart = 0;
-
-		// Create tasks (same logic as handleCreateTasks)
-		session.state.tasks = tasks.map((desc, i) => ({
-			id: i + 1,
-			description: desc.length > EXT_INIT_TASK_DESC_MAX ? desc.slice(0, EXT_INIT_TASK_DESC_MAX - ELLIPSIS_LENGTH) + "..." : desc,
-			status: "pending" as const,
-			lastUpdatedTurn: session.state!.currentTurnIndex,
-		}));
+		budget: GoalInitBudget | undefined,
+		ctx: ExtensionContext,
+		slug?: string,
+	): boolean => {
+		if (!ctx) return false;
+		return createGoal(session, objective, budget ?? {}, buildPorts(pi, ctx), true, slug);
+	};
+}
 
-		// Persist state so it survives session reconstruction.
-		// Prefer explicitly passed ctx (from the calling extension's tool execute),
-		// fallback to lastCtx captured from this extension's own event handlers.
-		const persistCtx = ctx ?? lastCtx;
-		if (persistCtx) {
-			persistGoalState(pi, session, persistCtx);
-		}
+// ── Cross-extension API 类型（单一 source of truth，API-1）──────────
 
-		return true;
-	}
-
-	// Expose on pi for cross-extension access
-	const api = pi as unknown as Record<string, unknown>;
-	api.__goalInit = initializeGoalFromExternal satisfies GoalExternalInit;
+/**
+ * `pi.__goalInit` 的预算配置形状。
+ *
+ * 跨扩展（coding-workflow / plan）通过 `pi.__goalInit` 编程式初始化 goal 时使用。
+ * 与 `BudgetConfig` 的差异：本类型只暴露外部可设的可选字段，且全部 optional。
+ */
+export interface GoalInitBudget {
+	tokenBudget?: number;
+	timeBudgetMinutes?: number;
 }
+
+/**
+ * `pi.__goalInit` 的规范函数签名（API-1：单一 source of truth）。
+ *
+ * 跨扩展消费者应 import 本类型而非重复声明 inline alias，避免签名 drift：
+ * ```ts
+ * import type { GoalInitFn } from "@zhushanwen/pi-goal";
+ * const goalInit = (pi as unknown as { __goalInit?: GoalInitFn }).__goalInit;
+ * ```
+ *
+ * @param objective 目标描述
+ * @param budget 预算配置，传 undefined 用默认值
+ * @param ctx **必填**——调用方的 ExtensionContext。省略会返回 false（创建失败）。
+ * @param slug 可选短标识（仅 widget 标题 + history 用，不注入 prompt）
+ * @returns true 创建成功；false 已有 active goal 或 ctx 缺失
+ */
+export type GoalInitFn = (
+	objective: string,
+	budget: GoalInitBudget | undefined,
+	ctx: ExtensionContext,
+	slug?: string,
+) => boolean;

package/src/persistence.ts

@@ -0,0 +1,83 @@
+/**
+ * 持久化层 — serialize/deserialize + history entry 构造
+ *
+ * FR-5: 移除旧格式兼容，字段缺失直接 throw（tasks 字段例外——向后兼容忽略）。
+ * 零 Pi 依赖。
+ */
+
+import type { GoalRuntimeState } from "./engine/types";
+import type { GoalHistoryEntry } from "./ports";
+
+// ── 常量 ──────────────────────────────────────────────
+
+export const ENTRY_TYPE = "goal-state";
+export const HISTORY_ENTRY_TYPE = "goal-history";
+
+// ── serialize（深拷贝，纯函数）────────────────────────
+
+export function serializeState(state: GoalRuntimeState): GoalRuntimeState {
+	return {
+		...state,
+		budget: { ...state.budget },
+	};
+}
+
+// ── deserialize（FR-5 严格解析，缺字段 throw）──────────
+
+/**
+ * 反序列化持久化 state。
+ *
+ * 向后兼容：旧 entry 可能含 `tasks` 字段（task CRUD 删除前的格式），此处忽略不 throw。
+ * 其余必填字段缺失仍 throw（FR-5）。
+ */
+export function deserializeState(data: Record<string, unknown>): GoalRuntimeState {
+	const req = <T>(key: string): T => {
+		if (!(key in data) || data[key] === undefined) {
+			throw new Error(`Missing required field: ${key}`);
+		}
+		return data[key] as T;
+	};
+
+	return {
+		goalId: req("goalId"),
+		objective: req("objective"),
+		// slug 用可选解析：旧持久化数据无此字段，不能误用 req()（否则旧数据 throw → state 全丢，GAP-4）
+		slug: data.slug as string | undefined,
+		status: req("status"),
+		tokensUsed: req("tokensUsed"),
+		timeStartedAt: req("timeStartedAt"),
+		timeUsedSeconds: req("timeUsedSeconds"),
+		budget: req("budget"),
+		lastProgressTurn: req("lastProgressTurn"),
+		budgetLimitSteeringSent: req("budgetLimitSteeringSent"),
+		objectiveUpdatedAt: req("objectiveUpdatedAt"),
+		lastBlockerReason: req("lastBlockerReason"),
+		tokenWarning70Sent: req("tokenWarning70Sent"),
+		tokenWarning90Sent: req("tokenWarning90Sent"),
+		timeWarning70Sent: req("timeWarning70Sent"),
+		timeWarning90Sent: req("timeWarning90Sent"),
+		lastTurnTokensUsed: req("lastTurnTokensUsed"),
+		currentTurnIndex: req("currentTurnIndex"),
+		completedAtTurnIndex: data.completedAtTurnIndex as number | undefined,
+	};
+}
+
+// ── makeHistoryEntry ─────────────────────────────────
+
+/**
+ * 从 state 构造 GoalHistoryEntry（纯函数）。
+ *
+ * totalTasks 暂置 0（task CRUD 已删除，#7 注入 todo 进度后可重填）。
+ */
+export function makeHistoryEntry(state: GoalRuntimeState, completedTasks: number): GoalHistoryEntry {
+	return {
+		goalId: state.goalId,
+		objective: state.objective,
+		slug: state.slug,
+		status: state.status,
+		completedTasks,
+		totalTasks: 0,
+		elapsedSeconds: Math.floor(state.timeUsedSeconds),
+		timestamp: Date.now(),
+	};
+}