@zhushanwen/pi-goal 0.2.0 → 0.4.0

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

@@ -0,0 +1,115 @@
+/**
+ * 事件 5: before_agent_start（context wrap-up + injection）。
+ *
+ * FR-8.1 G-007 + FR-8.6。返回 message（注入到 LLM context）或 undefined（无注入）。
+ *
+ * 分支顺序：
+ * 1. 终态：currentTurnIndex - completedAtTurnIndex >= AUTO_CLEAR_TURNS(2) → clearGoalSession
+ * 2. ADR-002：Context 使用率 > 85% → 保持 active + 注入 wrap-up 指令
+ * 3. 正常：注入 contextInjectionPrompt
+ *
+ * 无 ESC 守卫（before_agent_start 是 agent 开始前的信号，此时无 aborted 可能）。
+ *
+ * 全解耦：不再做 staleness 检测（原依赖 pi.__todoGetList，跨 ext 失效），
+ * 不再探测 plan extension（原 typeof pi.__planStart，跨 ext 失效）。
+ * contextInjectionPrompt 恒定建议 plan mode（AI 自行决定是否用）。
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import { AUTO_CLEAR_TURNS, CONTEXT_USAGE_RATIO_LIMIT } from "../../constants";
+import { isActiveStatus, isTerminalStatus } from "../../engine/goal";
+import { contextInjectionPrompt } from "../../projection/prompts";
+import { asTheme, renderTerminalStatusLine } from "../../projection/widget";
+import type { GoalSession } from "../../session";
+import { clearGoalSession } from "../../session";
+import { buildPorts } from "../ports";
+
+interface BeforeAgentStartResult {
+	message: {
+		customType: string;
+		content: string;
+		display: boolean;
+	};
+}
+
+export async function handleBeforeAgentStart(
+	pi: ExtensionAPI,
+	session: GoalSession,
+	ctx: ExtensionContext,
+): Promise<BeforeAgentStartResult | undefined> {
+	if (!session.state) return;
+
+	// 终态处理
+	if (isTerminalStatus(session.state.status)) {
+		handleTerminalStateBeforeAgent(pi, session, ctx);
+		return;
+	}
+	if (!isActiveStatus(session.state.status)) return;
+
+	// Context 使用率检查（ADR-002：保持 active，仅注入提示）
+	const ctxResult = checkContextUsage(session, ctx);
+	if (ctxResult) return ctxResult;
+
+	// 正常 context injection。
+	// 全解耦：planAvailable 恒 true（contextInjectionPrompt 恒定建议 plan mode，AI 自行决定）。
+	return {
+		message: {
+			customType: "goal-context",
+			content: contextInjectionPrompt(session.state, session.state.timeUsedSeconds, true),
+			display: false,
+		},
+	};
+}
+
+/**
+ * FR-8.1 G-007：终态 goal 在 AUTO_CLEAR_TURNS(2) 轮后自动清理。
+ * 未到清理阈值时：折叠 status bar（显示终态单行），清 widget。
+ */
+function handleTerminalStateBeforeAgent(
+	pi: ExtensionAPI,
+	session: GoalSession,
+	ctx: ExtensionContext,
+): void {
+	const state = session.state!;
+	const turnsInTerminal = state.currentTurnIndex - (state.completedAtTurnIndex ?? 0);
+	if (turnsInTerminal >= AUTO_CLEAR_TURNS) {
+		clearGoalSession(session, buildPorts(pi, ctx).ui);
+		return;
+	}
+	// 折叠 status bar（终态显示）
+	const statusText = renderTerminalStatusLine(state, asTheme(buildPorts(pi, ctx).ui));
+	if (statusText && ctx.hasUI) ctx.ui.setStatus("goal", statusText);
+	if (ctx.hasUI) ctx.ui.setWidget("goal", undefined);
+}
+
+/**
+ * ADR-002 context usage 提示：getContextUsage 超过 CONTEXT_USAGE_RATIO_LIMIT(0.85)
+ * → goal **保持 active**（不转 paused），仅注入 wrap-up 指令让 AI 自行 complete/cancel。
+ * 不做状态变更、不 persist、不 tick（资源保护通过"提示"而非"状态机"实现）。
+ */
+function checkContextUsage(
+	_session: GoalSession,
+	_ctx: ExtensionContext,
+): BeforeAgentStartResult | undefined {
+	const usage = _ctx.getContextUsage();
+	if (
+		usage &&
+		usage.contextWindow > 0 &&
+		(usage.tokens ?? 0) / usage.contextWindow > CONTEXT_USAGE_RATIO_LIMIT
+	) {
+		return {
+			message: {
+				customType: "goal-context-exceeded",
+				content:
+					"[GOAL — context space low, must wrap up now]\n" +
+					"1. Check remaining work and verify what is genuinely completed\n" +
+					"2. Only report completion for work backed by concrete evidence\n" +
+					"3. Summarize current progress and remaining work\n" +
+					"Do not start new work.",
+				display: false,
+			},
+		};
+	}
+	return undefined;
+}

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

@@ -0,0 +1,37 @@
+/**
+ * 事件 3: message_end（FR-6.7 ESC 守卫 + token 累加）。
+ *
+ * FR-6.7 ESC 守卫：ctx.signal.aborted 时跳过 token 累加。
+ * FR-8.6: token 累加算法（委托 service.applyEvent("message_end")）。
+ *
+ * 不 persist / updateWidget。
+ */
+
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import { applyEvent } from "../../service";
+import type { GoalSession } from "../../session";
+
+export interface MessageEndLikeEvent {
+	message: {
+		role: string;
+		usage?: {
+			input?: number;
+			output?: number;
+			cacheRead?: number;
+			totalTokens?: number;
+		};
+	};
+}
+
+export async function handleMessageEnd(
+	session: GoalSession,
+	ctx: ExtensionContext,
+	event: MessageEndLikeEvent,
+): Promise<void> {
+	if (!session.state) return;
+	// FR-6.7 ESC 守卫
+	if (ctx.signal?.aborted) return;
+
+	applyEvent(session, "message_end", event);
+}

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

@@ -0,0 +1,24 @@
+/**
+ * 事件 4: session_start（状态重建）。
+ *
+ * 调 reconstructGoalState 重建持久化状态 + updateWidget。
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import { updateWidget } from "../../projection/widget";
+import type { GoalSession } from "../../session";
+import { reconstructGoalState } from "../../session";
+import { buildPorts } from "../ports";
+
+export async function handleSessionStart(
+	pi: ExtensionAPI,
+	session: GoalSession,
+	ctx: ExtensionContext,
+): Promise<void> {
+	const ports = buildPorts(pi, ctx);
+	reconstructGoalState(session, ports.session);
+	if (session.state) {
+		updateWidget(session, ports.ui);
+	}
+}

package/src/adapters/event-handlers/shared.ts

@@ -0,0 +1,46 @@
+/**
+ * event-handlers 共享辅助（adapters/event-handlers 层）。
+ *
+ * - makeStaleChecker：FR-8.2 G-020 goalId snapshot，agent_end 入口构造、每个副作用前 checkStale
+ * - acquireProcessing / releaseProcessing：FR-8.2 G-021 isProcessing 防重入的锁语义封装
+ *
+ * 当前 handleAgentEnd 直接操纵 session.isProcessing（历史实现），未调用 acquire/release；
+ * 这两个封装保留供后续 handler 复用 + 被 stale-checker.test.ts 直接测试。
+ */
+
+import type { GoalSession } from "../../session";
+
+/**
+ * 构造 stale-check 闭包：入口快照 goalId，后续判断是否被新 goal 覆盖。
+ *
+ * 用法（agent_end）：
+ * ```ts
+ * const checkStale = makeStaleChecker(session);
+ * // ... 长流程 ...
+ * if (checkStale()) return; // goal 被覆盖，本次 agent_end 作废
+ * ```
+ *
+ * 语义：snapshot 时 session.state 可能为 null（首次启动），此时 snapshotGoalId
+ * 为 undefined；后续若有新 goal（goalId !== undefined）即视为 stale。
+ */
+export function makeStaleChecker(session: GoalSession): () => boolean {
+	const snapshotGoalId = session.state?.goalId;
+	return () => !session.state || session.state.goalId !== snapshotGoalId;
+}
+
+/**
+ * FR-8.2 G-021：isProcessing 防重入。
+ *
+ * agent_end 可能并发触发（多 message），重入时直接返回（不重复预算检查/续跑）。
+ * 通过 session.isProcessing flag 实现（定义在 session.ts）。
+ * 本函数为 agent_end 提供「锁住 + 解锁」语义。
+ */
+export function acquireProcessing(session: GoalSession): boolean {
+	if (session.isProcessing) return false; // 已被占用
+	session.isProcessing = true;
+	return true;
+}
+
+export function releaseProcessing(session: GoalSession): void {
+	session.isProcessing = false;
+}

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

@@ -0,0 +1,37 @@
+/**
+ * 事件 2: turn_end（FR-6.7 ESC 守卫 + 递增）。
+ *
+ * FR-6.7 ESC 守卫：ctx.signal.aborted 时跳过递增（ESC 不算 goal turn）。
+ * 正常路径：currentTurnIndex++ + updateWidget。
+ *
+ * 委托 service.applyEvent("turn_end")——它递增 currentTurnIndex 并返回
+ * EventEffect[{kind:"updateWidget"}]。adapter 执行该 effect。
+ *
+ * 不 persist（与旧 index.ts 行为对齐——turn_end 只内存变更 + widget）。
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import { updateWidget } from "../../projection/widget";
+import { applyEvent } from "../../service";
+import type { GoalSession } from "../../session";
+import { buildPorts } from "../ports";
+
+export async function handleTurnEnd(
+	pi: ExtensionAPI,
+	session: GoalSession,
+	ctx: ExtensionContext,
+): Promise<void> {
+	if (!session.state) return;
+	// FR-6.7 ESC 守卫
+	if (ctx.signal?.aborted) return;
+
+	const ports = buildPorts(pi, ctx);
+	const effects = applyEvent(session, "turn_end", undefined, ports);
+	// 执行 effects（updateWidget 等）
+	for (const effect of effects) {
+		if (effect.kind === "updateWidget") {
+			updateWidget(session, ports.ui);
+		}
+	}
+}

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

@@ -0,0 +1,296 @@
+/**
+ * goal_control tool — agent 控制入口（create / complete / report_blocked）
+ *
+ * #3：替代已删除的 goal_manager tool。
+ *
+ * 职责分层：
+ * - execute 层（adapter 职责）：signal 守卫
+ * - handler 层（goal 业务，契约对齐 code-architecture §3 handleCreate/handleComplete/handleReportBlocked）：
+ *   active 守卫 + evidence/reason 必填 + 状态转换
+ *
+ * 全解耦：goal 不再读 todo/plan 状态。complete 不做 todo 完成前置硬检查——
+ * todo 是否全完成由 AI 自行判断，goal 仅通过 prompt 软建议（见 prompts.ts）。
+ *
+ * 复用 engine/service 既有函数，不重写：
+ * - create: service.createGoal（FR-3.1 唯一创建入口；非终态旧 goal 拒绝，对齐 D25 / Codex create_goal）
+ * - complete: finalizeAndPersist(state, "complete", ...)（内部已含 tickState → finalizeGoal → persist）
+ * - report_blocked: 手动 tickState（status 仍 active 才累加当前运行段）→ transitionStatus(active→blocked) → persistState
+ *
+ * create 不调 sendUserMessage：toolcall 时 AI 已在 turn 中，返回结果后自行续跑
+ * （与 /goal set 的 followUp 触发区分；对齐 Codex create_goal 不自动续跑）。
+ *
+ * executionMode: "sequential"——状态变更 tool，不可与同批其他 tool 并行执行。
+ *
+ * 错误处理：用 throw new Error（CLAUDE.md Tool 设计规范），不返回错误成功模式。
+ */
+
+import { StringEnum } from "@mariozechner/pi-ai";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { type Static, Type } from "typebox";
+
+import { isActiveStatus, isTerminalStatus, transitionStatus } from "../engine/goal";
+import type { BudgetConfig, GoalStatus } from "../engine/types";
+import { updateWidget } from "../projection/widget";
+import { createGoal, finalizeAndPersist, persistState, type ServicePorts, tickState } from "../service";
+import type { GoalSession } from "../session";
+import { buildPorts } from "./ports";
+
+// ── Params schema ────────────────────────────────────
+
+const GoalControlParams = Type.Object({
+	action: StringEnum(["create", "complete", "report_blocked"] as const),
+	slug: Type.Optional(
+		Type.String({
+			description:
+				"Required for 'create'. A short kebab-case identifier you generate to title this goal in the status bar (e.g. 'refactor-auth', 'fix-login-bug'). Keep it concise and descriptive.",
+		}),
+	),
+	objective: Type.Optional(
+		Type.String({
+			description:
+				"Required for 'create'. The concrete objective to start pursuing. Only create a goal when explicitly requested by the user.",
+		}),
+	),
+	evidence: Type.Optional(
+		Type.String({
+			description:
+				"Required for 'complete'. Concrete completion evidence (files created/modified, tests passed, commands run). Do not mark complete on assumption, intent, or partial progress.",
+		}),
+	),
+	reason: Type.Optional(
+		Type.String({
+			description:
+				"Required for 'report_blocked'. The specific blocking condition and what was already tried (at least 3 approaches). Do NOT use for uncertainty, slow/hard work, or incomplete progress — keep working.",
+		}),
+	),
+	tokenBudget: Type.Optional(
+		Type.Number({
+			description: "Optional, for 'create'. Positive token budget for the new goal. Omit unless the user specifies one.",
+		}),
+	),
+	timeBudgetMinutes: Type.Optional(
+		Type.Number({
+			description: "Optional, for 'create'. Positive time budget in minutes for the new goal. Omit unless the user specifies one.",
+		}),
+	),
+	completedTasks: Type.Optional(
+		Type.Number({
+			description: "Optional. Number of completed tasks, written into goal history on 'complete'. Defaults to 0.",
+		}),
+	),
+});
+
+export type GoalControlActionParams = Static<typeof GoalControlParams>;
+
+// ── Details（renderResult 数据来源）──────────────────
+
+export interface GoalControlDetails {
+	action: "create" | "complete" | "report_blocked";
+	goalId: string;
+	status: GoalStatus;
+	slug?: string;
+}
+
+// ── 业务 handler（契约对齐 §3，可测：fake ports）──────
+
+/**
+ * create 业务逻辑：slug + objective 均必填 + 非终态旧 goal 守卫 + service.createGoal。
+ *
+ * slug：AI 生成的短标识，仅 widget 标题 + history 用，不注入 prompt。
+ * objective：完整描述，注入每轮 context prompt（保证方向感）。
+ *
+ * 全解耦：不读 todo/plan。toolcall 时 AI 已在 turn 中，**不**调 sendUserMessage
+ * （AI 返回后自行续跑，对齐 Codex create_goal）。
+ *
+ * 守卫用 D25 严格语义：非终态 active/paused/blocked 全挡，提示用 /goal resume 或
+ * /goal clear——防 AI 静默覆盖含未完成工作的 goal。
+ * 终态旧 goal 走 createGoal 快速路径覆盖（createGoal 内部 active 守卫，终态可覆盖）。
+ */
+export function handleCreate(
+	params: GoalControlActionParams,
+	session: GoalSession,
+	ports: ServicePorts,
+): GoalControlDetails {
+	const objective = params.objective?.trim();
+	if (!objective) {
+		throw new Error("'objective' is required for create. Describe the concrete objective to pursue.");
+	}
+	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').");
+	}
+
+	// D25 严格守卫：非终态旧 goal（active/paused/blocked）→ 拒绝创建（防静默覆盖未完成工作）
+	if (session.state && !isTerminalStatus(session.state.status)) {
+		throw new Error(
+			`Goal already active (status: ${session.state.status}). Use /goal resume to continue or /goal clear to reset before creating a new one.`,
+		);
+	}
+
+	// budget 校验：非法预算直接拒绝，不静默截断
+	const budget: Partial<BudgetConfig> = {};
+	if (params.tokenBudget !== undefined) {
+		if (params.tokenBudget <= 0) {
+			throw new Error("'tokenBudget' must be greater than 0.");
+		}
+		budget.tokenBudget = params.tokenBudget;
+	}
+	if (params.timeBudgetMinutes !== undefined) {
+		if (params.timeBudgetMinutes <= 0) {
+			throw new Error("'timeBudgetMinutes' must be greater than 0.");
+		}
+		budget.timeBudgetMinutes = params.timeBudgetMinutes;
+	}
+
+	// FR-3.1: 唯一创建入口（isExternalInit=false）。终态旧 goal 走覆盖快速路径。
+	const created = createGoal(session, objective, budget, ports, false, slug);
+	if (!created) {
+		// createGoal 内部 active 守卫兜底（理论上上面守卫已挡；防御性）
+		throw new Error("Goal already active. Cannot create a new one.");
+	}
+	updateWidget(session, ports.ui);
+
+	const state = session.state!;
+	const budgetNotice: string[] = [];
+	if (budget.tokenBudget) budgetNotice.push(`Token budget: ${budget.tokenBudget}`);
+	if (budget.timeBudgetMinutes) budgetNotice.push(`Time budget: ${budget.timeBudgetMinutes} min`);
+	ports.ui.notify([`Goal created [${slug}]: ${objective}`, ...budgetNotice].join("\n"), "info");
+
+	return { action: "create", goalId: state.goalId, status: state.status, slug };
+}
+
+/**
+ * complete 业务逻辑：active 守卫 + evidence 必填 + finalizeAndPersist。
+ *
+ * 全解耦后不再做 todo 完成前置检查——todo 是否全完成由 AI 自行判断（prompt 软建议）。
+ */
+export function handleComplete(
+	params: GoalControlActionParams,
+	session: GoalSession,
+	ports: ServicePorts,
+): GoalControlDetails {
+	const state = session.state;
+	if (!state) throw new Error("Goal mode not active.");
+	if (!isActiveStatus(state.status)) {
+		throw new Error(`Goal is not active (status: ${state.status}). Only an active goal can be completed.`);
+	}
+	const evidence = params.evidence?.trim();
+	if (!evidence) {
+		throw new Error("'evidence' is required for complete. Provide concrete completion evidence.");
+	}
+
+	// FR-3.3: 唯一终态序列入口（内部：tickState → finalizeGoal(transition+history) → persist）
+	finalizeAndPersist(state, "complete", params.completedTasks ?? 0, ports);
+	updateWidget(session, ports.ui);
+	ports.ui.notify(`Goal completed: ${state.objective}`, "info");
+
+	return { action: "complete", goalId: state.goalId, status: state.status };
+}
+
+/**
+ * report_blocked 业务逻辑：active 守卫 + reason 必填 + tickState + transitionStatus + persistState。
+ *
+ * 必须在 transitionStatus **之前** tickState，使 tick 看到 active 状态并累加当前运行段；
+ * 否则转 blocked 后 persistState 内部的 tick 因 status≠active 不累加，丢失最后一段运行时间。
+ */
+export function handleReportBlocked(
+	params: GoalControlActionParams,
+	session: GoalSession,
+	ports: ServicePorts,
+): GoalControlDetails {
+	const state = session.state;
+	if (!state) throw new Error("Goal mode not active.");
+	if (state.status !== "active") {
+		throw new Error(`Goal is not active (status: ${state.status}). Only an active goal can report_blocked.`);
+	}
+	const reason = params.reason?.trim();
+	if (!reason) {
+		throw new Error("'reason' is required for report_blocked. Describe the blocking condition.");
+	}
+
+	state.lastBlockerReason = reason;
+	// 先 tickState 累加当前运行段（此时 status 仍为 active）
+	tickState(state);
+	state.status = transitionStatus(state.status, "blocked");
+
+	persistState(session, ports);
+	updateWidget(session, ports.ui);
+	ports.ui.notify(`Goal blocked: ${reason}`, "warning");
+
+	return { action: "report_blocked", goalId: state.goalId, status: state.status };
+}
+
+// ── Tool 注册 ────────────────────────────────────────
+
+export function registerGoalControlTool(pi: ExtensionAPI, session: GoalSession): void {
+	pi.registerTool({
+		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.",
+		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",
+		parameters: GoalControlParams,
+
+		async execute(
+			_toolCallId: string,
+			params: GoalControlActionParams,
+			signal: AbortSignal | undefined,
+			_onUpdate: unknown,
+			ctx: ExtensionContext,
+		): Promise<{ content: Array<{ type: "text"; text: string }>; details: GoalControlDetails }> {
+			if (signal?.aborted) {
+				throw new Error("goal_control aborted by signal.");
+			}
+			const ports = buildPorts(pi, ctx);
+
+			let details: GoalControlDetails;
+			if (params.action === "create") {
+				details = handleCreate(params, session, ports);
+			} else if (params.action === "complete") {
+				// 全解耦：不再做 todo 完成前置硬检查。AI 自行判断 todo 是否全完成（prompt 软建议）。
+				details = handleComplete(params, session, ports);
+			} else {
+				details = handleReportBlocked(params, session, ports);
+			}
+
+			const text =
+				details.action === "create"
+					? `Goal created.\nGoal ID: ${details.goalId}\nSlug: ${details.slug ?? ""}\nObjective: ${params.objective?.trim() ?? ""}`
+					: details.action === "complete"
+						? `Goal completed.\nGoal ID: ${details.goalId}`
+						: `Goal reported blocked.\nGoal ID: ${details.goalId}\nReason: ${params.reason?.trim() ?? ""}`;
+			return { content: [{ type: "text", text }], details };
+		},
+
+		renderCall(args: Record<string, unknown>, theme: Theme): Text {
+			const action = args.action as string;
+			const slug = typeof args.slug === "string" ? args.slug : "";
+			const actionLabel =
+				action === "create"
+					? theme.fg("accent", "create") + (slug ? theme.fg("dim", ` ${slug}`) : "")
+					: action === "complete"
+						? theme.fg("success", "complete")
+						: theme.fg("error", "report_blocked");
+			return new Text(theme.fg("toolTitle", theme.bold("goal_control ")) + actionLabel, 0, 0);
+		},
+
+		renderResult(result: unknown, _options: { expanded: boolean }, theme: Theme): Text {
+			const d = (result as { details?: GoalControlDetails }).details;
+			if (!d) return new Text(theme.fg("dim", "goal_control"), 0, 0);
+			const statusColor =
+				d.status === "active"
+					? "accent"
+					: d.status === "complete"
+						? "success"
+						: d.status === "blocked"
+							? "error"
+							: "muted";
+			const label = d.action === "create" ? "Created" : d.action === "complete" ? "Completed" : "Blocked";
+			const slugSuffix = d.slug ? theme.fg("dim", ` ${d.slug}`) : "";
+			return new Text(theme.fg(statusColor, `◆ Goal ${label}`) + slugSuffix, 0, 0);
+		},
+	});
+}

package/src/adapters/ports.ts

@@ -0,0 +1,89 @@
+/**
+ * Ports 桥接 — Pi → ServicePorts 适配（adapters 层）
+ *
+ * 单一 ports 构造点（DRY）：command-adapter / event-adapter / index 共用。
+ *
+ * - persistence: pi.appendEntry 映射到 appendState / appendHistory（type 字符串区分）
+ * - ui: ctx.ui 的 setWidget/setStatus/notify + hasUI + theme 的 fg/bold（满足 ThemeLike 形状）
+ * - messaging: pi.sendMessage 映射到 sendContextMessage / sendUserMessage
+ * - session: ctx.sessionManager.getEntries + ctx.getContextUsage + ctx.signal
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import { ENTRY_TYPE, HISTORY_ENTRY_TYPE } from "../persistence";
+import type { MessagingPort, PersistencePort, SessionPort, UiPort } from "../ports";
+import type { ServicePorts } from "../service";
+
+/**
+ * 把 Pi 的 pi / ctx 适配为 ServicePorts。
+ *
+ * persistence 的 appendState 用 ENTRY_TYPE，appendHistory 用 HISTORY_ENTRY_TYPE，
+ * 与 serializeState / makeHistoryEntry 的输出对齐（session.ts reconstructGoalState 据此识别）。
+ *
+ * UiPort 接口未声明 fg/bold（D-22：只声明机器可检查的能力边界），
+ * 构造满足 UiPort & ThemeLike 的对象后整体断言为 UiPort（多出的 fg/bold 运行时存在，
+ * projection/widget.ts 的 asTheme 用 `as unknown as ThemeLike` 单步断言取出）。
+ */
+export function buildPorts(pi: ExtensionAPI, ctx: ExtensionContext): ServicePorts {
+	const persistence: PersistencePort = {
+		appendState: (state): void => {
+			pi.appendEntry(ENTRY_TYPE, state);
+		},
+		appendHistory: (entry): void => {
+			pi.appendEntry(HISTORY_ENTRY_TYPE, entry);
+		},
+	};
+
+	const uiPort = {
+		setWidget(name: string, content: string[] | string | undefined): void {
+			ctx.ui.setWidget(name, content);
+		},
+		setStatus(name: string, text: string | undefined): void {
+			ctx.ui.setStatus(name, text);
+		},
+		notify(text: string, level: "info" | "warning" | "error"): void {
+			ctx.ui.notify(text, level);
+		},
+		get hasUI(): boolean {
+			return Boolean(ctx.hasUI);
+		},
+		// ThemeLike 形状：透传 ctx.ui.theme 的 fg/bold。
+		// `as never` 是合法的单步断言（ThemeColor 是 string 子集，运行时安全）。
+		fg(color: string, text: string): string {
+			return ctx.ui.theme.fg(color as never, text);
+		},
+		bold(text: string): string {
+			return ctx.ui.theme.bold(text);
+		},
+	} as UiPort;
+
+	const messaging: MessagingPort = {
+		sendContextMessage: (content, deliverAs, customType): void => {
+			pi.sendMessage(
+				{
+					customType: customType ?? "goal-context",
+					content,
+					display: false,
+				},
+				{ deliverAs },
+			);
+		},
+		sendUserMessage: (content, deliverAs): void => {
+			pi.sendUserMessage(content, { deliverAs });
+		},
+	};
+
+	const session: SessionPort = {
+		getEntries: () => ctx.sessionManager.getEntries(),
+		getContextUsage: () => {
+			const usage = ctx.getContextUsage();
+			return usage ? { tokens: usage.tokens, contextWindow: usage.contextWindow } : null;
+		},
+		get signal(): AbortSignal | undefined {
+			return ctx.signal;
+		},
+	};
+
+	return { persistence, ui: uiPort, messaging, session };
+}